AirCoding/docs/implementation-plan.md

AirCoding 实现计划

版本: 2.0 日期: 2026-06-12 基线: OpenCode v1.17.4 (commit abda3515) 参考: aircoding-architecture-mvp.md (完整架构设计)、reference/airplan-v2 (可复用 prompt)

---

1. 最终方案：4 Agent + 4 文件

Main Agent（对话 + 意图分类 + 架构规划）
  │
  ├── Scheduler Agent（任务拆解 + 派发 + 监控 + 状态落盘）
  │     └── Worker Agent（EXECUTE / DEBUG 双模式，通过 shell 调用 cmake/ctest/cppcheck 等）
  │
  └── Architecture Designer（架构规划 + 里程碑审查 fork）

C++ 工具链不单独封装为 Plugin——Worker 直接通过 OpenCode 已有的 shell 工具调用命令行。 取证工具（截图/抓包）同理，Worker 直接通过 shell 调用 ffmpeg/tcpdump。

---

2. 文件清单

#	文件	内容	类型
1	agents/scheduler.json	Scheduler agent 配置 + system prompt	JSON + prompt
2	agents/worker.json	Worker agent 配置 + 双模式 system prompt	JSON + prompt
3	agents/architect.json	Arc agent 配置 + system prompt（含审查 fork）	JSON + prompt
4	.opencode/tool/coordinator.ts	listen / dispatch / status 三个调度工具	TypeScript

运行时自动生成：.air/local/state/scheduler-state.json（调度器状态落盘）

---

3. 可复用的 AirPlan V2 资源

AirCoding Agent	V2 对应	可复用文件
Scheduler	AirEng	reference/airplan-v2/commands/eng.md — 调度逻辑、轮询规则、自主决策指令
Worker (EXECUTE)	AirDo	reference/airplan-v2/commands/do.md — 执行行为、验收标准
Worker (DEBUG)	AirDbg	reference/airplan-v2/commands/dbg.md — 调试工作流、先取证后修复规则
Architecture Designer	AirArc	reference/airplan-v2/commands/arc.md — 架构规划、需求探讨、审查指令
审查 fork	AirRvr	reference/airplan-v2/commands/rvr.md — Code-to-Design 审查、高风险审计

复用方式：将 V2 命令文件中的关键指令提取、适配后写入对应 Agent 的 system prompt。不是原封不动复制，而是提取核心约束规则，去掉 V2 特有的 Python runtime 部分。

---

4. 各文件实现细节

4.1 agents/scheduler.json

{
  "id": "scheduler",
  "name": "Scheduler",
  "description": "任务调度引擎，负责任务拆解、派发、监控和结果汇总",
  "mode": "subagent",
  "model": { "primary": "claude-sonnet-4-20250514" },
  "tools": [
    "read", "glob", "grep",
    "coordinator.listen", "coordinator.dispatch", "coordinator.status",
    "task"
  ],
  "steps": 200,
  "system_prompt_file": "agents/prompts/scheduler.md"
}

system prompt 核心指令（从 eng.md 提取）：

• 语言锁定中文
• 自主决策原则（不询问用户，除非修复预算耗尽/需求歧义/资源耗尽）
• 不写代码（工具白名单已硬阻断）
• 任务拆解策略（按模块拆分、按依赖排序）
• 流程规则（Worker 完成 → 下一个任务 / 失败 → 重新派发调试）
• 状态落盘要求（每次状态变更写 scheduler-state.json）
• 10 分钟不活跃自动巡检

4.2 agents/worker.json

{
  "id": "worker",
  "name": "Worker",
  "description": "执行器/调试器双模式 Worker",
  "mode": "subagent",
  "model": { "primary": "claude-sonnet-4-20250514" },
  "tools": [
    "read", "write", "edit", "shell", "glob", "grep"
  ],
  "steps": 100,
  "system_prompt_file": "agents/prompts/worker.md"
}

system prompt 核心指令（从 do.md + dbg.md 提取）：

## EXECUTE 模式（task.type = "execute"）
- 按 acceptance_criteria 实现功能
- 先读后改，小步编辑
- 通过 shell 执行 cmake --build 和 ctest 验证
- **每次任务完成前必须通过 shell 运行 cppcheck --enable=all（不可跳过）**
- 编译通过 + 测试通过 + cppcheck 无严重问题 = 完成
- 不修改 scope.denied_paths 中的文件
- 完成后输出结构化结果（必须包含 cppcheck 输出）
- **Scheduler 校验：WorkerResult 中无 cppcheck 输出则拒绝，要求补跑**

## DEBUG 模式（task.type = "debug"）
- 先取证后修改（不可违反）
- 必须至少通过 shell 执行一种取证命令：
  · GUI 问题 → ffmpeg -f kmsgrab 截图
  · 网络问题 → tcpdump 抓包
  · C++ 问题 → cppcheck 静态分析
  · 通用 → 代码追踪 + 日志分析
- 取证结果记录后才能开始修改代码
- 修复后必须重新编译 + 测试验证
- 修复失败不超过 retry_budget 次

4.3 agents/architect.json

{
  "id": "architect",
  "name": "Architecture Designer",
  "description": "架构规划器，负责需求分析、架构设计和里程碑审查",
  "mode": "subagent",
  "model": { "primary": "claude-sonnet-4-20250514" },
  "tools": ["read", "glob", "grep", "task"],
  "steps": 100,
  "system_prompt_file": "agents/prompts/architect.md"
}

system prompt 核心指令（从 arc.md + rvr.md 提取）：

• 纯规划器，禁止写代码（工具白名单硬阻断）
• 三阶段流程：探讨 → 确认 → 生成计划
• 任务描述规范（避免歧义词、包含保留约束）
• 里程碑审查：fork 只读子 session 做 Code-to-Design 审查
• 审查结果精简后返回 Scheduler

4.4 .opencode/tool/coordinator.ts

三个工具的实现要点：

coordinator.listen：

• 订阅 OpenCode EventV2 事件总线
• 等待匹配的子代理事件（task.completed / task.failed / task.progress）
• 超时返回 timeout 状态（触发 Scheduler 巡检）
• 每次调用时检查 last_activity → 超过 10 分钟自动巡检

coordinator.dispatch：

• 接收任务列表
• 为每个任务创建 OpenCode BackgroundJob（非阻塞子 session）
• 返回 jobId 列表
• 更新 scheduler-state.json

coordinator.status：

• 查询所有活跃 BackgroundJob 的状态
• 返回 [{ jobId, taskId, agentType, status, lastHeartbeat }]
• 检测卡死任务（心跳超时 / 硬超时）

关键技术点：需要研究 OpenCode 的以下 API：

• packages/opencode/src/background/job.ts — BackgroundJob 的 start/wait/cancel
• packages/core/src/event.ts — EventV2 的 subscribe/listen
• packages/opencode/src/tool/task.ts — TaskTool 的子 session 创建

---

5. 实现顺序

Step 1: 环境搭建 + 读 API（0.5 天）

• 确认 Bun 环境可用
• 读懂 OpenCode Plugin 工具注册机制（registry.ts + .opencode/tool/）
• 读懂 BackgroundJob API（packages/opencode/src/background/job.ts）
• 读懂 EventV2 API（packages/core/src/event.ts）

Step 2: 调度工具（1-2 天）

• 实现 coordinator.ts（listen + dispatch + status）
• 这是唯一的自定义代码，需要吃透 OpenCode 内部 API
• 验证子 session 创建和事件订阅可用

Step 3: Agent 配置 + Prompt（1 天）

• 写 scheduler.json + system prompt（从 eng.md 提取）
• 写 worker.json + system prompt（从 do.md + dbg.md 提取）
• 写 architect.json + system prompt（从 arc.md + rvr.md 提取）

Step 4: 端到端测试（0.5-1 天）

• 准备一个简单 C++ 项目
• 测试完整流程：用户提需求 → Main Agent → Scheduler 拆解 → Worker 执行 → 结果汇总
• 修复发现的问题

总计：3-5 天

---

6. 已知风险和对策

风险	对策
OpenCode Plugin API 不够用	读源码确认，必要时做最小修改
BackgroundJob 不支持非阻塞派发	用 OpenCode 的 task 工具 + background: true 参数
EventV2 事件格式不符合预期	在 coordinator.listen 中做适配层
System prompt 不够稳定	从 V2 提取已验证的指令，反复测试调优
上下文窗口不够	简化 prompt，Worker 只传必要上下文

---

7. 后续迭代路线（当前不做）

1. C++ 工具链 Plugin（cpp.build/test/analyze/diagnose）— Worker 目前直接用 shell
2. 取证工具 Plugin（evidence.screenshot/pcap）— Worker 目前直接用 shell
3. 独立 Reviewer Agent
4. 证据门控策略（10 种任务类型 × 证据表）
5. 动态 DAG 调度算法（增量重规划）
6. ContextAssembler（按需抽取上下文）
7. 上下文压缩（Copy-on-Write）
8. ExperienceMiner + Debug Knowledge
9. HUD / Status Layer
10. 多语言 toolchain（Python/Rust/JS）
11. 二进制分发

---

8. 核心设计决策速查

决策	结论
基线	OpenCode v1.17.4
进程模型	单进程（子代理 = 子 session）
C++ 工具链	Worker 直接用 shell 调用（不封装 Plugin）
Scheduler	独立 Agent，事件驱动
防卡死	10 分钟不活跃定时器 + 状态落盘
LLM 策略	混合：正常流程确定性代码，异常走 LLM
接口契约	中等粒度 + stability 标记
审查	两层：Worker 自验 + Arc 里程碑审查 fork
上下文共享	共享文件 + ContextPack + WorkerResult
Worker 模式	EXECUTE + DEBUG 双模式合一