Agent-Native 软件设计范式

Agent-Native 软件设计范式

概述

Agent-Native 软件设计是指：将原本仅有人类用户界面（GUI、Web、原生应用）的软件，转化为 AI Agent 可直接操控的结构化接口。核心原则是”构建接口 TO 软件，而非替代软件”——不重实现软件功能，而是生成合法的中间文件后调用真实软件进行渲染。

1. Agent-Software Gap

1.1 问题定义

AI Agent 擅长逻辑推理和任务规划，但不擅长直接使用专业软件。当前的解决方案存在根本缺陷：

现有方案	缺陷
GUI 自动化（截图 + 像素点击）	脆弱、不可靠、随 UI 更新频繁失效
有限 API	仅覆盖部分功能，多数专业软件不提供 API
轻量重实现	丢失 90%+ 的专业能力，产生”玩具”版本

1.2 CLI 作为 Agent-Native 接口的优势

CLI 是 Agent 操控软件的最优接口形式，原因：

• 结构化可组合：文本命令天然匹配 LLM 的文本输出格式，易于链式组合复杂工作流
• 轻量通用：最小开销，跨所有系统工作，无额外依赖
• 自描述：--help 标志提供 Agent 可自动发现的能力文档
• 已被验证：AI 编程助手（Claude Code 等）通过 CLI 执行数千种真实工作流
• 面向 Agent 设计：--json 输出消除解析复杂性
• 确定可靠：一致的结果使 Agent 行为可预测

2. 核心架构模式

2.1 中间文件 + 真实后端模式

关键设计决策：

• CLI 是结构化命令层，不是功能重实现
• 中间文件使用软件的原生格式（MLT XML、ODF ZIP、SVG 等）
• 真实软件是硬依赖，不是可选的优雅降级
• 输出必须程序化验证（魔数、ZIP 结构、像素分析），不信任退出码

2.2 双模式交互

每个 Agent-Native CLI 应同时支持：

模式	用途	特征
无状态子命令	脚本、流水线、一次性操作	输入→输出，无上下文保持
有状态 REPL	交互式 Agent 会话	上下文保持、撤销/重做、项目状态持久化

默认行为：无参数启动时进入 REPL 模式（invoke_without_command=True）。

2.3 Agent 能力发现

Agent 通过标准机制发现 CLI 能力：

• --help：所有命令和子命令的文档
• --json：机器可读的结构化输出
• SKILL.md：自包含的技能定义文件（YAML frontmatter + Markdown 体）
• info/list/status 内省命令：Agent 在执行前了解当前状态

3. 渲染 Gap（Rendering Gap）

3.1 问题

GUI 应用在渲染时应用效果。当 CLI 直接操作项目文件后，如果使用简单工具导出，效果会被静默丢弃。

典型案例：

• 视频编辑器：CLI 向 MLT XML 添加了滤镜，但用 ffmpeg concat 导出时滤镜不生效
• 图片编辑器：CLI 修改了 .xcf 图层，但未调用 GIMP 的 GEGL 引擎处理

3.2 解决方案：Filter Translation Layer

三层优先级策略：

优先级：原生引擎 > 翻译滤镜图 > 脚本生成

翻译陷阱：

• 重复滤镜合并：多个同名滤镜在翻译时叠加
• 交错流排序：不同格式的流处理顺序不一致
• 参数空间差异：相同效果在不同工具中的参数范围不同
• 不可映射效果：某些效果在目标格式中无对应物

4. 通用实施流程

4.1 7 阶段分析-生成流水线

将任意软件转化为 Agent-Native CLI 的标准流程：

每个阶段的输入输出契约明确，可由 AI Agent 自主执行。

4.2 代码分析要点

1. 识别后端引擎：找到核心库/框架（MLT、GEGL、bpy 等）
2. 映射 GUI 操作到 API 调用：每个按钮/拖拽/菜单项对应一个函数调用
3. 识别数据模型：使用的文件格式（XML、JSON、二进制、数据库）
4. 发现现有 CLI 工具：后端自带的 CLI（melt、ffmpeg、convert）
5. 梳理撤销/重做系统：Command 模式的应用

5. 测试策略

5.1 四层测试

层级	测试对象	特征
单元测试	每个核心函数	合成数据、无外部依赖、快速确定性
E2E 原生测试	中间文件生成	ODF 结构、XML 合法性、格式验证
E2E 真实后端测试	真实软件调用	最终输出验证（魔数、ZIP 结构、像素分析）
CLI 子进程测试	已安装命令	完整工作流模拟，从任何目录执行

5.2 无优雅降级原则

真实软件必须安装。测试在软件缺失时必须失败而非跳过——因为 CLI 离开真实软件就毫无用处。

6. 输出验证方法论

不信任退出码为 0 就意味着成功。必须程序化验证：

• 魔数验证：PDF → %PDF-，DOCX/XLSX/PPTX → ZIP 结构
• 像素级分析：探测特定帧、比较亮度/饱和度
• 音频分析：RMS 级别、频谱对比
• 时长/格式检查：对比预期值

7. 陷阱与对策

陷阱	对策
重实现软件功能而非调用真实后端	坚持”接口 TO 软件”原则，生成中间文件+调用后端
渲染时效果丢失	使用 Filter Translation Layer，优先级：原生引擎 > 翻译 > 脚本
非整数帧率累积舍入误差	使用 round() 而非 int()，±1 帧容差
并发写入损坏 session 文件	使用排他文件锁定（flock）保护 JSON 保存
输出文件存在但内容无效	程序化验证魔数、结构、内容
Agent 无法理解当前状态	提供 info/status/--json 内省命令

8. MCP 后端模式

当目标软件提供 MCP 服务器而非传统 CLI 时：

• 每命令 spawn MCP server（无状态）或 Daemon 模式（一次 spawn，多命令复用）
• 同步包装异步 MCP 调用
• CLI 维护状态（URL、工作目录、导航历史）
• 适用于浏览器自动化（DOMShell）、知识库管理等场景