# 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 范围

**包含**:
- [x] CLI 启动 + .air/ 初始化
- [x] OpenCode TUI (split-footer, scrollback, footer, tool card)
- [x] 13 provider (含 openai-compatible → GLM-5.1)
- [x] 19 个工具 (read/write/edit/shell/glob/grep/task/question/websearch/webfetch/lsp/todo/plan/skill/apply_patch/repo_clone/repo_overview/mcp_websearch/invalid)
- [x] **Scheduler + TaskGraph + WavePlanner + 独立 Bun 子进程 Worker**
- [x] 级联失效 + ADR 回滚
- [x] **架构文档强制维护门控 (INV-3: 不更新文档不标记完成)**
- [x] C++ 工具链 9 个 (cpp.*)
- [x] Doctor
- [x] ExecutorRole + ReviewerRole (端到端验证)
- [x] 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 不动，只加翻译层 |