AirCoding/docs/meeting-notes-20260613.md

AirCoding 会议记录与当前状态

日期：2026-06-13 状态：架构已确定，实现进行中，需要补全各层代码级保证和协作 prompt

---

一、核心架构决策（已确定）

1.1 总体架构

用户 ↔ Main Agent（客服/乙方代表，用户唯一交互入口）
         └── Scheduler（核心枢纽，事件路由器）
               ├── Architect（按需咨询/里程碑审查）
               │     └── fork → Reviewer（审查时临时创建，审查完销毁）
               ├── Executor Worker（写代码、编译、测试）
               ├── Debugger Worker（证据收集、问题定位、修复）
               └── 读写 .air/shared/ 共享文件

• Main Agent = 客服角色：面向用户，理解意图，传达需求，汇报进度，处理变更，不做技术活
• Scheduler = 项目经理：拆解任务，派发 Worker，监控进度，协调资源，不写代码
• Architect = 技术总监：需求分析，架构设计，里程碑审查，常驻提供咨询
• Worker = 工程师：EXECUTE + DEBUG 双模式，写代码/编译/测试/调试

1.2 通信模型

• EventV2 事件总线 + coordinator 工具（listen/dispatch/status）
• 子 agent 完成 → EventV2 广播 → Scheduler 收到 → 按规则派发下一个
• 共享文件（.air/shared/）+ ContextPack（派发时传递上下文引用）
• 不是 agent 之间直接对话，而是通过事件 + Scheduler 路由

1.3 三条通信路径

1. Scheduler → Architect：重规划/异常咨询，Arc 读图 → 输出 PlanDelta
2. Scheduler → Reviewer：Code-to-Design 对照审查，审查报告写入 WorkerResult
3. Scheduler → Architect（consult）：Scheduler 无法决策时求助

1.4 流程规则（Scheduler 状态机）

Executor 完成 → 自动触发 Reviewer（逐任务审查）
Reviewer 通过 → 标记任务完成
build/test 失败 → 自动触发 Debugger
Reviewer 发现问题 → 重新派发 Executor 修复
阶段内所有任务完成 → 自动触发 Architect（里程碑审查）
里程碑审查通过 → 进入下一阶段
里程碑审查发现问题 → Architect 生成修复任务 → Scheduler 派发
需求变更 → 触发动态 DAG 调度算法
Scheduler 异常无法决策 → 派发 Architect（咨询）
所有任务完成 → 汇总结果返回 Main Agent

1.5 核心设计约束

• 单进程模型：子代理 = OpenCode 子 session（TaskTool + BackgroundJob）
• 代码级硬阻断：工具白名单是硬阻断不是建议
• LLM 混合策略：正常调度走确定性代码，异常/边界才调 LLM
• 防卡死：10 分钟不活跃定时器 + scheduler-state.json 实时落盘
• cppcheck 强制：每次任务完成前必须运行，无输出不允许标记完成
• 证据门控：按任务类型决定必需证据
• 两层审查：Worker 自验 + Architect 里程碑审查 fork

1.6 基线

• Fork OpenCode v1.17.4（commit abda3515）
• TypeScript + Bun，单进程，Effect v4 beta
• 不封装 C++ 工具链 Plugin，Worker 直接用 shell 调用 cmake/ctest/cppcheck

---

二、当前实现状态

2.1 已完成的文件

文件	位置	状态
coordinator.ts	workspace/.../src/tool/coordinator.ts	✅ 已写入，类型检查通过
registry.ts	workspace/.../src/tool/registry.ts	✅ 已修改（+4 工具注册）
agent.ts	workspace/.../src/agent/agent.ts	⚠️ 已回退，需要重新修改
scheduler.txt	workspace/.../src/agent/prompt/scheduler.txt	✅ 已写入，但缺少协作指令
worker.txt	workspace/.../src/agent/prompt/worker.txt	✅ 已写入，但缺少协作指令
architect.txt	workspace/.../src/agent/prompt/architect.txt	✅ 已写入，但缺少协作指令
AGENTS.md	E:\WorkSpace\AirCodingCli\AGENTS.md	✅ 已写入
opencode.json	E:\WorkSpace\AirCodingCli\opencode.json	✅ 已创建
bun install	workspace	✅ 成功（需要设置 WindowsSdkDir 环境变量）
bun typecheck	workspace	✅ 通过

2.2 启动方式

cd E:\WorkSpace\AirCodingCli\workspace
export WindowsSdkDir="D:/Dev/IDE/VS/VSIDE/Windows Kits/10/"
export VCToolsInstallDir="D:/Dev/IDE/VS/VSIDE/VC/Tools/MSVC/14.50.35717/"
export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
bun dev

或运行 workspace\start.bat / workspace\start.sh。

2.3 测试结果

• TUI 正常渲染 ✅
• 只能看到 build 和 plan 两个 agent ❌（scheduler/worker/architect 未注册）
• Main Agent 不会自动派发 Scheduler ❌
• 各 Agent 之间无法协作 ❌

---

三、待解决的问题（按优先级）

3.1 每层都需要 A（代码级保证）+ B（协作 Prompt）

这是用户反复强调的核心要求。不能只靠 prompt，也不能只有代码没有 prompt。

Agent	A：代码级保证（需要改 OpenCode 源码）	B：协作 Prompt（需要补全）
Main Agent	prompt.ts 强制转发给 Scheduler（代码路由）	怎么汇报结果、转达变更、与用户沟通
Scheduler	代码保证只能通过 task 工具派发 Worker/Architect	怎么拆任务、怎么用 coordinator 工具、怎么读写 task-graph、怎么和 Architect 协作
Architect	工具白名单已有（只读）	怎么写 task-graph.json、怎么 fork Reviewer、审查结果发给谁
Worker	Scheduler 校验 WorkerResult 包含 cppcheck 输出	怎么汇报结果（WorkerResult 格式）、EXECUTE/DEBUG 模式切换、结果返回给谁

3.2 每个 Agent 需要知道的协作信息

我是谁 → 我的角色和约束
我的上游是谁 → 谁派发了我，结果返回给谁
我的下游是谁 → 我能派发谁，用什么工具
通信协议 → 共享文件在哪、结果格式是什么、事件怎么收

3.3 具体改动清单

改动 1：agent.ts — 注册 3 个自定义 Agent

// 在 agents 对象中添加：
scheduler: {
  name: "scheduler",
  description: "AirCoding 调度引擎",
  mode: "subagent",   // 不是 primary，由 Main Agent 派发
  native: true,
  steps: 200,
  prompt: PROMPT_SCHEDULER,
  permission: Permission.merge(defaults, Permission.fromConfig({
    edit: "deny", write: "deny", todowrite: "deny", task: "allow",
  }), user),
},
worker: { ... mode: "subagent", prompt: PROMPT_WORKER, ... },
architect: { ... mode: "subagent", prompt: PROMPT_ARCHITECT,
  permission: { "*": "deny", read: "allow", glob: "allow", grep: "allow", task: "allow" }
},

改动 2：build agent 加 prompt — Main Agent 编排逻辑

build: {
  name: "build",
  prompt: PROMPT_AIRCODING_MAIN,  // ← 新增
  mode: "primary",
  ...
}

PROMPT_AIRCODING_MAIN 内容：

• 你是 AirCoding 主代理，面向用户的唯一交互入口
• 你不直接执行复杂任务，通过 task 工具派发 scheduler
• 始终设置 background: true
• 子代理完成后自动通知你，你负责向用户汇报

改动 3：prompt.ts — 代码级路由（可选但推荐）

在主循环中插入确定性路由，强制将复杂任务转发给 Scheduler：

// 在 runLoop 中，LLM 调用之前
// 如果当前 agent 是 build，且用户消息不是简单问答
// → 确定性派发 scheduler（不经过 LLM 判断）

改动 4：各 Agent prompt 补全协作指令

每个 prompt 需要补充：

• 上游/下游是谁
• 用什么工具通信（task, coordinator.listen, coordinator.status）
• 共享文件路径和格式（task-graph.json, review-result.json）
• 结果格式（WorkerResult 结构）

---

四、设计文档索引

文档	路径	内容
架构设计	aircoding-architecture-mvp.md	完整架构（16 章，7 项已确定决策）
实现计划	implementation-plan.md	实现步骤 v2.0
集成指南	INTEGRATION.md	如何集成到 OpenCode fork
AI 编码指南	AGENTS.md	代码风格 + Agent 约束
V1 痛点	airplanV2-Qwen3.7-Max设计.md	25 个 P0/P1 缺陷及 V2 方案
原始愿景	idea.md	完整系统设计（参考用）
V1 基线	baselineV1.md	早期基线设计（参考用）

---

五、环境配置

# Bun 版本
bun 1.3.14

# 必需环境变量
WindowsSdkDir=D:\Dev\IDE\VS\VSIDE\Windows Kits\10\
VCToolsInstallDir=D:\Dev\IDE\VS\VSIDE\VC\Tools\MSVC\14.50.35717\
OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true

# 项目结构
E:\WorkSpace\AirCodingCli\
├── workspace/          # OpenCode v1.17.4 fork（工作目录）
├── reference/opencode/ # OpenCode v1.17.4 原始参考
├── reference/airplan-v2/ # V2 插件 prompt 参考
├── src/                # AirCoding 自有源码（coordinator.ts, prompts）
└── *.md                # 设计文档

---

六、关键代码参考

coordinator.ts 已实现的 4 个工具

1. coordinator_listen — 等待后台 Worker 完成，返回结果
2. coordinator_status — 查询所有后台 Worker 状态
3. coordinator_save_state — 保存调度状态到 scheduler-state.json
4. coordinator_load_state — 从 scheduler-state.json 恢复状态

TaskTool 关键 API（OpenCode 已有）

// 派发子代理（前台/后台）
task({
  description: "任务描述",
  prompt: "详细任务指令",
  subagent_type: "scheduler",  // 或 "worker", "architect"
  background: true,            // 后台运行
  task_id: "复用已有session的ID"  // 可选，复用持久 session
})

共享文件结构

.air/shared/
├── plan/
│   ├── plan.md           # 架构方案
│   ├── task-graph.json   # 任务图（source of truth）
│   ├── requirements.md   # 原始需求
│   └── docs/ADR-*.md     # 架构决策记录
└── rules/
    ├── project-rules.md
    └── toolchain-rules.md

.air/local/
├── state/
│   └── scheduler-state.json  # 调度器实时状态
└── sessions/