AI 工作流设计构想¶

将 AI 软件开发从一门不可预测的艺术，转变为一门系统化的工程学科。 在智能体的自主性与人类的监督之间取得完美平衡。

引言¶

当我使用像 Manus 或 SWE-Agent 这类智能体系统（Agentic System）来处理复杂的开发任务时，常常会遇到很高的失败率。如果我们给智能体一个诸如"构建一个全栈应用"这样笼统的目标，整个过程很容易因为目标模糊、中间步骤设计有误或无法从错误中恢复而偏离轨道。这迫使我们不得不从头再来，造成大量时间和计算资源（tokens）的浪费。

核心问题

大多数智能体工具的运行方式如同一个"黑箱"。我们发布一个指令后，只能被动地观察它的"意识流"或行为输出，缺乏在关键决策点进行干预、批准或在其误解需求时进行纠正的机制。

为了让 AI 智能体能够可靠地执行复杂、多步骤的工程任务，并赋予人类对过程的有效控制权，我们设计了这套工作流设计指南。

设计原则¶

我们创建这套工作流设计指南，是基于我们对软件工程与 AI 智能体协作的"第一性原理"思考：

五大信念

AI 的能力会持续进步，但复杂任务永远需要结构化的监督。 虽然 LLM 的编码能力会越来越强，但真正的工程实践涉及到架构设计、权衡取舍和分步执行。
对 AI 驱动的复杂任务的需求，将永远超过 AI 的自主能力。 随着我们的期望从"写一个函数"增长到"构建并管理一个分布式系统"，对稳健规划、错误处理和人类干预的需求只会变得更加关键。
当 AI 智能体负责主要开发工作时，人类的关注点将从逐行代码的可读性，转向整个系统的可靠性与可控性。 人类没有时间或意愿去审查 AI 生成的每一行代码。
AI 生成系统的可靠性，必须由完备的测试和"人在回路中"（Human-in-the-Loop）的治理来保障。 结构化的工作流允许我们设立专门的测试阶段和明确的审批关卡。
如果人类工程师需要理解流程中的某个特定部分，结构化的计划能为每一步的意图和产物提供清晰的上下文。

基本工作流设计规则¶

基于上述核心原则，我们精心设计了一套 AI 智能体工作流应遵循的基本规则：

规则	说明
分解意图	将宏大、模糊的目标分解为一系列职责单一的步骤。每一步由清晰的"意图"定义
分配具体工具	为每个意图明确指定执行的智能体（Python、Shell、文件操作等）
定义清晰依赖	使用 `dependencies` 将任务组织成有向无环图（DAG）
明确交付物	为每个任务声明预期的 artifacts，创建清晰的"契约"
实现人机交互节点	生成评审文件，轮询检查用户决策文件
规划并行探索	使用 `variants` 指令引导智能体并行探索多种实现方法
隔离功能与复用	将通用逻辑抽象成独立任务序列，减少冗余
让智能体处理细节	计划只定义"做什么"，智能体负责"怎么做"

示例：自动化 Lisp 编译器构建¶

原始方法：模糊、笼统的指令¶

传统上，我们会用一个单一、笼统的指令来驱动 AI 智能体：

"请用 Python 构建一个简单的 Lisp 编译器。它需要能解析 S-表达式，处理基本算术运算，并带有一个命令行界面。请确保其结构良好。"

问题

这种方法极易失败。智能体可能会选择一个次优的解析策略，生成的代码集成度不高，或者在某个细节上卡住而我们却无法干预。整个过程就是一个"黑箱"。

结构化工作流：意图导向型 YAML (I-YAML)¶

相反，我们可以使用意图导向型 YAML 格式来构建这个复杂任务。这个计划不是代码，而是一个为执行提供清晰度、可控性和可靠性的蓝图。

# 任务计划：构建 Lisp 编译器（基于可用工具的可执行版本）
name: "构建 Lisp 编译器的可执行计划"
description: "一个将高级意图映射到具体工具以构建 Lisp 编译器的高级计划。"
version: "3.0"

tasks:
  - id: setup_project_structure
    name: "1. 创建项目目录结构"
    agent: Shell
    intent: "为项目创建必要的基础目录：'src' 和 'tests'。"
    artifacts: ["./src", "./tests"]

  - id: implement_lexer
    name: "2. 实现词法分析器（Lexer）"
    agent: Python
    intent: "创建 'src/lexer.py'，包含 tokenize 函数。"
    artifacts: ["src/lexer.py"]

  - id: implement_parser
    name: "3. 实现语法分析器（Parser）"
    agent: Python
    intent: "创建 'src/parser.py'，包含 parse 函数。"
    artifacts: ["src/parser.py"]

  - id: propose_transpiler_code
    name: "4. 生成两种代码转译器方案"
    agent: Python
    variants: 2  # 并行探索两种实现
    intent: "生成两种不同的转译器实现方案。"
    artifacts: ["build/transpiler_v1.py", "build/transpiler_v2.py"]

  - id: wait_for_human_selection
    name: "5. [审核] 等待人工选择"
    agent: HumanReview  # 人类决策节点

  - id: improve_selected_transpiler
    name: "6. 改进选定的转译器"
    agent: Python
    intent: "将选定的方案改进后写入最终文件。"
    artifacts: ["src/transpiler.py"]

  - id: implement_cli_and_tests
    name: "7. 实现 CLI 并运行测试"
    agent: Python
    dependencies: [improve_selected_transpiler]
    intent: "创建主入口脚本和测试脚本，运行单元测试。"
    artifacts: ["test_report.txt"]

"解压"计划：智能体的解释过程¶

这个结构化的 YAML 不仅是一个计划，更是一个可执行的规范。

以 implement_lexer 任务为例

读取任务：编排器识别到 implement_lexer 任务
检查依赖：确认前置任务 setup_project_structure 已完成
识别智能体与意图：agent: Python，intent: "创建 'src/lexer.py'..."
生成并执行代码：调用指定工具完成意图
验证交付物：确认 src/lexer.py 已成功创建

这个过程将一个高层次的目标，转化为一个可验证的、基于工具的行动。

结论¶

核心价值

通过摒弃单一、庞杂的指令，转向结构化、意图导向的计划，我们将智能体系统从不可预测的"神秘黑箱"转变为可靠的工程伙伴。

遵循这套精心设计的指南——强调目标分解、工具化执行、明确契约和具体的人机交互机制——我们能够显著提升 AI 智能体的可靠性与可控性。

这种方法降低了失败率，增强了透明度，并最终在任何复杂度的软件项目上，实现了真正的人机协作。