chore: push all design docs, V2 plan specs, and current working state

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>
2026-06-12 17:12:29 +08:00
parent 8f55c962bb
commit ae44be31d5
364 changed files with 46779 additions and 2812 deletions
--- a/AirPlan/docs/spec/AircOding-alpha1-plan.md
+++ b/AirPlan/docs/spec/AircOding-alpha1-plan.md
@@ -0,0 +1,246 @@
+# 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 不动，只加翻译层 |