AirCoding/AirPlan/docs/spec/AircOding-alpha1-plan.md

AircOding Alpha 1 融合方案

日期: 2026-06-11 基线:

• OpenCode 1.15.5 (MIT) — TUI / 工具 / Provider / Agent 循环
• AirCoding (自研) — 调度系统 / Worker IPC / 事件系统
• AirPlanV2 设计文档 — 需求与架构规格

---

一、融合架构

┌─ OpenCode 交互层 ──────────────────────────────┐
│  TUI (132文件)                                  │
│  scrollback / footer / tool-card / markdown      │
│       ▲                                          │
│       │ ProjectionClient.subscribe()             │
│       │ → StreamCommit 翻译层 (~150行)           │
│       │                                          │
│  Agent Loop (tool-runtime.ts)                   │
│  LLM → tool_call / text → 工具执行 / 回复用户    │
│       │                                          │
│       │ task 工具调用                             │
│       ▼                                          │
│  ┌── AirCoding 调度层 ───────────────────────┐  │
│  │  Scheduler.create_tasks()                 │  │
│  │    → TaskGraph (hard/soft/conflict 依赖)   │  │
│  │    → WavePlanner (写区冲突 + 波次)         │  │
│  │    → DISPATCHING (独立 Bun 子进程)         │  │
│  │      → Worker1 (Executor)                 │  │
│  │      → Worker2 (Reviewer)                 │  │
│  │      → Worker3 (Debugger)                 │  │
│  │    → MONITORING (心跳/超时/结果消费)       │  │
│  │    → MERGE → REVIEW → 下一个 Wave          │  │
│  │                                            │  │
│  │  需求变更:                                  │  │
│  │    requirement.changed                     │  │
│  │      → ArchitectureDesigner 评估           │  │
│  │      → TaskGraph.invalidate_by_adr         │  │
│  │      → dispatch_frozen = true              │  │
│  │      → git rollback snapshot               │  │
│  │      → PlanDelta 重规划                     │  │
│  │      → apply_delta → unfreeze              │  │
│  │      → 继续调度                              │  │
│  └───────────────────────────────────────────┘  │
└────────────────────────────────────────────────┘

关键数据流: 用户 → Agent Loop → task工具 → TaskGraph → Scheduler → Worker → 结果事件 → ProjectionClient → TUI 实时刷新

---

二、组件分工与移植策略

2.1 从 OpenCode 复用 (不动或微改)

组件	路径	说明
TUI	packages/ui/ packages/opencode/src/cli/cmd/tui/	132文件, scrollback, footer, tool-card, markdown
Agent Loop	llm/src/tool-runtime.ts	340行, LLM自主决策调工具/说人话
工具系统	packages/opencode/src/tool/*.ts	19个成熟工具，Effect Schema验证
Provider	llm/src/providers/*.ts llm/src/protocols/*.ts	13个provider + 6个协议，配置代码+HTTP代码
SQLite 基础	core/src/database/	Drizzle ORM， WAL/NORMAL， migration
PTY Shell	opencode/src/pty/	Bun原生PTY
权限基础	opencode/src/permission/	Agent级规则 + 200+ bash arity检测

Provider具体复用方案: 接口不变。OpenCode内部用Message格式，协议层各管各的转换。直接对接GLM-5.1网关走openai-compatible provider。

工具执行路径Alpha方案: 先用OpenCode的路径（ctx.ask()/Effect Schema/直接调用），安全模型后续迭代按AirCoding 6层PermissionEngine加。

2.2 从 AirCoding 移植 (核心调度)

组件	来源行数	说明
Scheduler 状态机	850行	IDLE→LOADING→PLANNING→DISPATCHING→MONITORING→MERGE→REVIEW→REPAIR→COMPLETE/BLOCK/CANCEL/FROZEN
TaskGraph	473行	add_task / add_dependency / get_runnable / apply_delta / invalidate_by_adr / tasks_by_adr
WavePlanner	108行	写区冲突检测 → 波次规划 → 并发度控制
RetryPlanner	97行	retry / retry_serial / debug / skip / block / cancel
AgentMonitor	119行	心跳 / soft 5min / hard 10min 超时
WorkspaceManager	362行	git worktree / main / isolated_copy
ADR 级联	内嵌 TaskGraph	tasks_by_adr → invalidate_by_adr → dispatch_frozen → git rollback → 解冻

2.3 Worker 角色 (从 AirCoding 移植)

Role	说明	状态
ExecutorRole	接收TaskSpec → 调LLM决策工具 → 验收 → WorkerResult	当前workers/src/roles/ExecutorRole.ts
ReviewerRole	只读审查：正确性/安全/架构合规/证据充足	当前代码存在，需验证
DebuggerRole	7步调试：确认症状→取证→定位→修复→验证→关闭	当前代码存在，需验证
CompactorRole	Copy-on-write压缩 + CompressionValidator	Alpha 保留位置
ExperienceMinerRole	经验挖掘	Alpha 保留位置

2.4 新增目录结构

packages/
  contracts/       # 共享类型 (不动)
  ui/              # ← OpenCode UI组件 (npm-dep @opentui/solid)
  core/            # ← OpenCode DB/event/session 基础
  llm/             # ← OpenCode 13 provider + 6 protocol (替换原有)
  opencode/        # ← OpenCode CLI/TUI/tools/pty
  runtime/         # ← 重写: 对接调度+worker+投影
  scheduler/       # ← AirCoding 调度系统 (新包)
  workers/         # ← AirCoding 5个 Worker Role
  toolchain-cpp/   # ← AirCoding C++工具链
  doctor/          # ← AirCoding Doctor
  experience/      # ← 保留位置 (Hermes后续)
  context/         # ← 保留位置 (AirContext后续)

---

三、集成胶水 (~400行)

3.1 Agent Loop → TaskGraph 桥接 (~100行)

OpenCode task 工具被调用时:
  → 不直接 forkIn
  → 调用 Scheduler.create_tasks([{id, type, title, description, depends_on}])
  → Scheduler 插入 TaskGraph
  → Agent 立刻回到对话状态
  → 完成后通过 ProjectionClient 推送 TUI

3.2 Event → StreamCommit 翻译层 (~150行)

EventBus 事件             →  OpenCode StreamCommit
task.started              →  StreamCommit.tool_start
task.completed            →  StreamCommit.text("完成: ...")
tool.completed            →  StreamCommit.tool_output
permission.prompt.requested → FooterOutput.permission

3.3 RuntimeApp 重组 (~100行)

新的启动流程:
  1. 加载 OpenCode CLI config
  2. 打开/创建 .air/ 项目
  3. 初始化 SQLite session (Drizzle ORM)
  4. 创建 Scheduler + TaskGraph
  5. 启动 OpenCode TUI renderer (split-footer)
  6. Agent ready → 等待用户输入

3.4 架构文档强制维护门控 (~80行) ← 新增

INV-3: 架构同步强制 — 不更新架构文档不能标记任务完成。

Scheduler REVIEWING_WAVE 阶段:
  1. 收集所有 completed Worker 的 changed_files
  2. ArchitectureDesigner.assess_impact(files) 判定是否需要文档更新
  3. 判定触发条件 (AP-97):
     - 公共接口/DB schema/IPC contract/provider contract 变更
     - 包依赖方向变更
     - ADR/C4/plan/todo 需要变更
     - Reviewer 发出 category=architecture
     - Worker 返回 architecture/interface blocker
  4. 命中任一条件:
     a. ArchitectureDesigner.update_architecture_docs() 写入对应文档
     b. emit architecture.plan.updated
     c. 更新未完成 → WorkerResult.status → blocked, 不进 completed
  5. 未命中 → 跳过, 正常完成

实现: REVIEWING_WAVE case 加门控逻辑, ArchitectureDesigner 已有 assess_impact() 和 update_architecture_docs() 方法，补充调用链即可。

3.5 工具执行路径适配 (~50行)

Alpha: OpenCode 工具执行路径不变
  ctx.ask({permission, patterns}) → Effect orDie → execute
后续: 注入 AirCoding PermissionEngine (向后兼容)

---

四、Alpha 1 范围

包含:

• CLI 启动 + .air/ 初始化
• OpenCode TUI (split-footer, scrollback, footer, tool card)
• 13 provider (含 openai-compatible → GLM-5.1)
• 19 个工具 (read/write/edit/shell/glob/grep/task/question/websearch/webfetch/lsp/todo/plan/skill/apply_patch/repo_clone/repo_overview/mcp_websearch/invalid)
• Scheduler + TaskGraph + WavePlanner + 独立 Bun 子进程 Worker
• 级联失效 + ADR 回滚
• 架构文档强制维护门控 (INV-3: 不更新文档不标记完成)
• C++ 工具链 9 个 (cpp.*)
• Doctor
• ExecutorRole + ReviewerRole (端到端验证)
• DebuggerRole (Alpha 至少跑通一条失败诊断链)

不含（后续迭代）:

• AirContext (上下文压缩) — 保留架构位置
• Hermes (经验挖掘) — 保留架构位置
• CompactorRole 端到端验证
• ExperienceMinerRole
• 6层 PermissionEngine (先用 OpenCode agent级规则)
• 二进制 tarball 打包

---

五、开发顺序

Phase 1: 骨架搭建 (Day 1)

1. 创建 packages/scheduler/，移植 TaskGraph + Scheduler + WavePlanner + RetryPlanner + AgentMonitor
2. 创建 packages/workers/，移植 WorkerManager + WorkerProcess + WorkerProtocol + 5个role
3. 删除 MainAgent 正则分类器 + TuiApp.tsx 中的 console.log
4. 装上 OpenCode llm/ui/core/opencode 包

Phase 2: Agent 循环重写 (Day 2)

1. task 工具拦截 → Scheduler.create_tasks() 而非 forkIn
2. Agent 不等待 → 立刻回对话
3. Worker 完成 → EventBus → ProjectionClient → TUI
4. REVIEWING_WAVE 加架构文档门控: ArchitectureDesigner → 强制更新 → 不更新则 blocked

Phase 3: 结果通知与 TUI (Day 2-3)

1. Event → StreamCommit 翻译层
2. 端到端: 用户输入 → TaskGraph → Worker → TUI 刷新

Phase 4: C++ + Doctor + 验证 (Day 3-4)

1. C++ 工具链移植
2. Doctor 移植
3. 第一条工作流端到端验证: 创建hello.txt

Phase 5: 级联 + 并行 + 审查 (Day 4-5)

1. ADR 级联端到端验证
2. 并行任务: 两个Worker同时跑, 无写区冲突
3. Debugger 诊断链验证

---

六、关键决策记录

DD	决策	理由
1	Provider 接口不动	OpenCode Message + Protocol 是可工作的模式，换接口无收益
2	Alpha 工具权限用 OpenCode 方案	OpenAI Codex 级别，够用。6 层模型后续加
3	子代理用 AirCoding 独立进程	TaskGraph 需要子代理独立崩溃隔离，OpenCode fiber 不够
4	AirContext 留架构位	后续迭代，不影响核心调度链路
5	Hermes 留架构位	同上
6	TUI 数据通道: ProjectionClient → StreamCommit 翻译	TUI 不动，只加翻译层