三角色自动化编排系统

---

可移植的 AI 多 Agent 协作开发框架。复制本文件夹到任何项目根目录下即可使用。

快速开始

1. 复制本文件夹到目标项目

你的项目/
├── automation/          ← 复制本文件夹到这里
├── src/                 ← 你的源代码
├── tasks/               ← 自动生成（运行时创建）
└── ...

2. 配置开发步骤

编辑 automation/docs/dev-steps/stages-index.json，定义你的项目步骤：

{
  "steps": [
    { "id": "1.1-xxx", "title": "步骤标题", "stage": 1, "source": "stage-1-xxx.md", "complexity": 2 }
  ]
}

• complexity: 1-2 使用 GPT 5.5，≥3 使用 Sonnet 4.6

3. 编写阶段详情文档

在 automation/docs/dev-steps/ 下创建 stage-{N}-{名称}.md，用 ## 步骤 X.Y 格式组织每个步骤的需求。

4. 运行

# 全量开发
pwsh -ExecutionPolicy Bypass -File ".\automation\orchestrator.ps1" -RunAll

# 干跑（只生成 prompt，不调用 AI）
pwsh -File ".\automation\orchestrator.ps1" -RunAll -DryRun

# 单步骤
pwsh -File ".\automation\orchestrator.ps1" -StepId "1.1-xxx" -StepTitle "步骤标题"

# BUG 修复模式
pwsh -File ".\automation\orchestrator.ps1" -Mode bugfix
pwsh -File ".\automation\orchestrator.ps1" -BugId "BUG-001"

# 断点恢复
pwsh -File ".\automation\orchestrator.ps1" -Resume "2.1-xxx"

# 查看需要人工介入的任务
pwsh -File ".\automation\resume.ps1" -List

# 恢复任务
pwsh -File ".\automation\resume.ps1" -TaskId "2.1-xxx"

前置依赖

工具	用途	必需
PowerShell 5.1+	编排器运行环境	✅
kiro-cli	规划师(Opus 4.6) + 执行者(Sonnet 4.6)	✅
codex	执行者(GPT 5.5)，低复杂度任务	可选
codebuddy	审计员(GLM 5.1)	可选（失败时降级到 kiro）
git	审计通过后自动提交	✅

文件结构

automation/
├── orchestrator.ps1           ← 主编排器入口
├── resume.ps1                 ← 快速恢复工具
├── modules/
│   ├── state_manager.ps1      ← 状态机（status.json）
│   ├── agent_runner.ps1       ← 统一 Agent 调用器
│   ├── failure_classifier.ps1 ← 失败分类与策略
│   ├── prompt_builder.ps1     ← 修复 prompt 自动生成
│   ├── report_writer.ps1      ← 人工介入报告
│   └── watchdog.ps1           ← 独立后台监控
├── docs/
│   ├── workflow.md            ← 三角色协作完整规范
│   ├── context-management.md  ← 上下文/token 管理策略
│   ├── role-anchoring.md      ← 角色锚定（人类操作手册）
│   ├── planner-instructions.md
│   ├── planner-quickref.md
│   ├── executor-instructions.md
│   ├── executor-quickref.md
│   ├── auditor-instructions.md
│   ├── auditor-quickref.md
│   ├── bugfix/
│   │   ├── _index.md         ← BUG 分诊入口
│   │   ├── level-1-direct.md
│   │   ├── level-2-dialog.md
│   │   ├── level-3-orchestrator.md
│   │   ├── methods-locate.md
│   │   ├── methods-verify.md
│   │   └── templates-l3.md
│   └── dev-steps/
│       └── stages-index.json  ← 步骤索引（需按项目自定义）
└── README.md                  ← 本文件

核心机制

三角色分工

角色	职责	使用的 AI	不可做
规划者	拆任务、定接口、写验收标准	kiro Opus 4.6	不写代码
执行者	按任务卡写代码和测试	kiro Sonnet 4.6 / codex GPT 5.5	不改设计
审计员	独立验证产出	codebuddy GLM 5.1	不修代码

状态机

PENDING → PLANNING → PLAN_READY → CODING → CODE_DONE → REVIEWING
→ REVIEW_PASSED → DONE
→ REVIEW_REJECTED → FIXING → CODE_DONE（循环）
→ NEED_HUMAN（最多 3 次 REJECT 后熔断）

失败自动恢复

• TIMEOUT → 缩小任务范围重试
• NO_OUTPUT → 追加强约束重试
• AUTH_ERROR → 标记 NEED_HUMAN
• REVIEW_REJECTED → 自动生成 fix_prompt 返工
• 3 次失败 → 熔断，生成 human_report.md

BUG 修复三级分诊

• L1：根因明确、单文件 → 直接修
• L2：2-3 文件、需确认 → 对话式修复
• L3：4+ 模块、根因不明 → 编排器全流程

自定义

更换 AI 工具

修改 orchestrator.ps1 中的以下位置：

• $KiroCli：kiro-cli 路径
• Invoke-PlannerV2 中的 --model 参数
• Invoke-AuditorV2 中的 CLI 和模型
• Select-Executor 中的路由逻辑

调整超时

修改 modules/agent_runner.ps1 中的 $script:DefaultTimeouts。

调整重试上限

修改 orchestrator.ps1 中的 $MaxReject（默认 3）。