预工作流对话：CodeMachine 中的 Controller 模式

看起来您只提供了文章的来源链接，而没有贴出需要翻译的正文内容。请把要翻译的文本（除代码块、URL 之外）粘贴在这里，我会按照要求保留源链接并将其余部分翻译成简体中文。

带控制器阶段的代理工作流

在构建代理工作流时，常会出现一种模式：在自主流水线运行之前，需要有人收集需求。

CodeMachine v0.8.0 引入了 Controller 模式，这是一种一等方式，可在工作流执行之前与 AI 产品负责人（PO）进行对话。

本演练展示了一个 规范驱动的开发工作流，其中 PO 代理收集需求，然后交给专门的代理进行分析、架构设计和实现。

为什么需要单独的控制器？

多代理工作流通常以提示开始并自行运行。
而真实的开发则需要：

可视化概览

┌─────────────────────────────────────────────────────────────┐
│                    Controller Phase                         │
│              (Interactive PO conversation)                  │
│                                                             │
│   User ←→ spec-po agent (session persisted)                 │
│                                                             │
│   [Enter with empty input] → Confirmation Dialog            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ workflow:controller-continue
┌─────────────────────────────────────────────────────────────┐
│                   Execution Phase                           │
│              (Autonomous agent pipeline)                    │
│                                                             │
│   spec-analyst → spec-architect → spec‑api‑designer → …      │
│                                                             │
│   [Press C] → Return to Controller Dialog                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ workflow:return-to-controller
┌─────────────────────────────────────────────────────────────┐
│                 Return to Controller                        │
│          (Pause workflow, resume PO session)                │
│                                                             │
│   User ←→ spec-po agent (same session)                      │
│                                                             │
│   [Enter with empty input] → Resume Workflow                │
└─────────────────────────────────────────────────────────────┘

在代码中声明控制器

export default {
    name: 'Spec-Driven Development',
    controller: controller('spec-po', {}),   // PO agent for pre‑workflow chat
    specification: false,

    steps: [
        separator("∴ Discovery Phase ∴"),
        resolveStep('spec-po', {}),               // PO step (auto‑skipped)
        resolveStep('spec-analyst', {}),

        separator("∴ Design Phase ∴"),
        resolveStep('spec-architect', {}),
        resolveStep('spec-api-designer', {}),

        separator("∴ Implementation Phase ∴"),
        resolveStep('spec-setup', {}),
        resolveStep('spec-impl-orchestrator', {}),

        separator("⟲ Review Loop ⟲"),
        resolveStep('spec-tester', { interactive: false }),
        resolveModule('spec-review', { interactive: false, loopSteps: 2 }),
    ],
};

关键要点

• controller('spec-po', {}) – 声明用于前置工作流对话的 PO 代理。
• 同一 PO 代理也会出现在 第 1 步；当控制器阶段运行时，此步骤会自动标记为已完成（不会重复执行）。
• controller() 函数可以接受引擎/模型的覆盖参数：

controller('spec-po', {
    engine: 'claude',               // 覆盖引擎
    model:  'claude-4.5-sonnet'      // 覆盖模型
})

当 PO 对话需要的能力与后续步骤不同的时候，这非常有用。

Source: …

交互流程

启动工作流

┌──────────────────────────────────────────────────────────────┐
│  CodeMachine v0.8.0                                          │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ▸ spec-po (Running)                                         │
│                                                              │
│  您今天想要构建什么？                                        │
│──────────────────────────────────────────────────────────────│
│                                                              │
│  > 使用 Next.js 和 SQLite 的待办事项应用                     │
│                                                              │
└──────────────────────────────────────────────────────────────┘

对话会一直进行，直到您在空行上按 Enter。随后会出现确认对话框：

┌────────────────────────────────────────┐
│   准备好启动工作流吗？                 │
│                                        │
│   [Start]   [Continue Chat]            │
└────────────────────────────────────────┘

*选择 Start 会触发 workflow:controller-continue，并转入 执行阶段。

会话持久化

控制器会话会保存到磁盘，例如：

{
  "controllerConfig": {
    "agentId": "spec-po",
    "sessionId": "ses_44785e25dffeDZqs8kVN7KbfIx",
    "monitoringId": 1
  },
  "autonomousMode": "true"
}

好处

• 崩溃后恢复 – 如果 CLI 在对话中途崩溃，可以恢复会话。
• 返回控制器 – 在工作流进行中可以暂停并返回同一 PO 会话。
• 日志查看 – 点击已完成的 PO 步骤即可查看完整的对话历史。

暂停执行并返回控制器

在自主流水线运行时，按 C 暂停：

┌──────────────────────────────────────────────────────────────┐
│  工作流流水线 (8 项)                                          │
├──────────────────────────────────────────────────────────────┤
│  … (运行中的步骤)                                            │
│                                                              │
│  按 C 返回 PO 对话                                            │
└──────────────────────────────────────────────────────────────┘

此时会返回 返回控制器 视图，您可以继续与 PO 进行聊天。当您完成（输入空行）后，工作流会从中断处继续执行。

摘要

• Controller pattern 能够清晰地将需求收集与自主执行分离。
• 会话持久化支持 crash recovery（崩溃恢复）、mid‑workflow returns（工作流中途返回）以及 full conversation logs（完整对话日志）。
• 同一个 PO 代理既可以充当控制器，也可以作为普通步骤使用，系统会自动跳过以避免重复。
• 引擎/模型覆盖让您能够灵活定制 PO 对话的功能。

使用 CodeMachine v0.8.0，构建稳健、规范驱动的多代理开发流水线变得既简单又有弹性。

工作流概览

                                                             │
│  ✓ Hady [PO] (completed)                                     │
│  ▸ Moaz [Analyst] (running)         ← Paused               │
│  ○ Atef [Architect]                                          │
│  ○ Essam [API]                                               │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│  [C] Controller  [Esc] Stop                                  │
└──────────────────────────────────────────────────────────────┘

控制器交互

• 当按下 C 键时

  1. 中止当前步骤。
  2. 工作流状态机进入 PAUSE（暂停）状态。
  3. 阶段切换为 “onboarding”（入职）。
  4. 控制器会话恢复。

• 对话结束后

  • 按 Enter（回车）键从暂停的步骤继续工作流。

完全规范驱动工作流（含控制器）

export default {
    name: 'Spec-Driven Development',
    controller: controller('spec-po', {}),
    specification: false,

    tracks: {
        question: 'What are we working on?',
        options: {
            new_project: { label: 'New Project' },
            existing_app: { label: 'Existing App' },
            refactor: { label: 'Refactor' },
        },
    },

    conditionGroups: [
        {
            id: 'features',
            question: 'What features does your project have?',
            multiSelect: true,
            conditions: {
                has_ui:   { label: 'Has UI' },
                has_auth: { label: 'Has Authentication' },
                has_db:   { label: 'Has Database' },
            },
        },
    ],

    steps: [
        separator("∴ Discovery Phase ∴"),
        resolveStep('spec-po', {}),
        resolveStep('spec-analyst', {}),

        separator("∴ Design Phase ∴"),
        resolveStep('spec-architect', {}),
        resolveStep('spec-api-designer', {}),

        separator("∴ Implementation Phase ∴"),
        resolveStep('spec-setup', {}),
        resolveStep('spec-impl-orchestrator', {}),

        separator("⟲ Review Loop ⟲"),
        resolveStep('spec-tester', { interactive: false }),
        resolveModule('spec-review', { interactive: false, loopSteps: 2 }),
    ],

    subAgentIds: [
        'spec-dev-data',
        'spec-dev-api',
        'spec-dev-ui',
        'spec-dev-tests',
    ],
};

需求与解决方案

为什么使用控制器模式？

控制器模式填补了代理工作流中的关键空白：在系统自主运行之前，需要进行人类‑AI 对话。通过将此交互提升为一等原语，我们获得了：

• 会话持久化 – 工作可以稍后恢复，且不会丢失上下文。
• 清晰的交接用户体验 – 用户明确确认过渡，减少意外操作。
• 工作流中途返回 – 用户可以暂停、讨论，然后准确地从中断处继续。

这些能力使 CodeMachine 能更忠实地模拟真实的开发过程。

资源

• CodeMachine on GitHub
• Workflow Examples
• Documentation