ae44be31d5
Includes AirPlan design documents, AircOding-alpha1-plan, AirPlanV2, AirPlan-ParaV2, AirPlan-Para V1 reference docs, and all working code changes across packages. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
247 lines
11 KiB
Markdown
Executable File
247 lines
11 KiB
Markdown
Executable File
# 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 不动，只加翻译层 |
|