# AirCoding Agent 设计文档

> 最后更新：2026-05-26
> Canonical baseline: `AirPlan/docs/architecture/baselineV1.md`
> 历史决策记录：`AirPlan/docs/architecture/decisions-round-1.md`、`decisions-round-2.md`、`decisions-round-3.md`

## 1. 背景与动机

当前 Air 系列插件主要运行在 Claude Code 已暴露的 agent/plugin 接口之上，能力边界受限。尤其是 AirContext 为了参与上下文管理，需要通过插件层绕行，这种方式不够优雅，也不利于长期演进。

新的方向是：从"Claude Code 插件外挂式扩展"转向"自有 agent/runtime 架构"。

目标不是做一个泛用 Claude Code clone，而是构建一个以 C++ 为首个深度支持语言、后续可扩展至 Python/Rust/JS 等多语言的长期可用 AI Coding Agent。

## 2. 核心定位

AirCoding Agent 的核心 runtime 是语言无关的。C++ 是第一个深度支持的语言 profile，后续按 `toolchain-<lang>` 包扩展。

开发闭环：

```text
需求理解
  → 架构/接口设计
  → 代码阅读
  → 修改计划
  → 编译
  → 静态分析
  → 单测/集成测试
  → 运行/调试
  → 崩溃/日志/网络/GUI 证据分析
  → 修复
  → 变更总结
  → 经验沉淀
```

## 3. 参考项目分工

### 3.1 OpenCode

OpenCode 作为 runtime 骨架、TUI、provider 抽象、session/tool registry 的主要参考。

- TUI 交互布局以 OpenCode 为设计规范
- runtime 分层（session/event/sync、多 agent 组织）
- provider / model 抽象
- plugin / SDK 扩展层

### 3.2 Claude Code CLI

Claude Code CLI 作为执行层代码质量、Executor 行为、工具调用策略、记忆系统、文件编辑安全边界的标杆。AirCoding 的执行层功能应尽可能与 Claude Code 对齐，以提升代码修改质量、安全性和验证纪律。

- 工具生命周期、schema 校验
- 权限模型
- 子代理调度
- 文件 read/edit/write 与 diff/update 执行原语
- 小步精确编辑、先读后改、避免无关重构、失败时定位根因而不是随机重试
- build/test/debug 证据闭环，完成前必须验证或明确说明未验证原因
- 实现中发现架构/接口冲突时显式上报 blocker
- compact / resume / history / rewind 交互
- **记忆系统**（MEMORY.md + frontmatter + 多类型分层）
- **TAOR / TORI 设计**（Task-Agent-Observation-Result / Tool-Observation-Reasoning-Iteration 循环）

### 3.3 Hermes Agent

Hermes Agent 作为长期运行、跨会话学习、技能生成和 Curator 机制的参考。

- Nudge Engine 计数触发机制
- Curator Daemon 定期去重/合并/归档
- 使用中自我 patch
- SKILL.md 格式（YAML frontmatter + Markdown body）
- FTS5 语义搜索

### 3.4 Codex / OpenAI Coding Agent

Codex / OpenAI 开源 coding agent 作为通用工具调用与多模态工具面的补充参考。

- shell / patch / test 直接闭环
- coding sandbox 与工具调用编排
- tools / plugin / core-plugins / MCP 相关实现
- 图像生成、图像编辑、视觉输入等通用工具能力的 capability 设计参考
- 只作为工具面参考，不作为 AirCoding 核心 runtime 形态参考
- 本地参考路径：`reference/openai-codex/`

### 3.5 Anthropic / Claude Skills

Anthropic/Claude 开源 Skills 项目作为 skill/tool 组织方式的重要参考。

- SKILL.md 结构、frontmatter、触发描述与资源组织
- 技能包内 scripts / references / assets 的组织方式
- 可复用工具步骤如何沉淀成 skill
- skill 与 MCP / capability / Project Rules 的边界划分
- 作为 AirCoding SkillGenerator、ExperienceMiner、Capability 文档格式的参考
- 本地参考路径：`reference/anthropic-skills/`

### 3.6 asciinema / Atuin / claude-hud

- asciinema：PTY 接管与终端流捕获
- Atuin：SQLite 命令历史结构化存储与搜索
- claude-hud：实时 HUD / statusline 设计

## 4. 语言选型（已确定）

### 4.1 主语言：TypeScript + Bun

- **运行时**：Bun（内置 SQLite，原生 TSX 支持）
- **TUI 框架**：`@opentui/solid`（MIT 许可独立项目，npm 依赖引入）
- **包结构**：Bun workspaces + Turborepo monorepo

### 4.2 Python 角色

Python 退化为纯 subprocess 工具调用（`Bun.spawn` + JSON-over-stdio），仅用于封装已有 C++ 工具链脚本和 Python 特有库。经验提炼、上下文组装、记忆管理全部留在 TS runtime 内部。

### 4.3 多语言 toolchain 包结构

Runtime 核心是语言无关的。每种语言通过独立包 + LanguageDetector plugin 扩展：

```
packages/
  tui/              — 语言无关 TUI
  runtime/          — 语言无关 Agent Runtime
  llm/              — 语言无关 Provider 抽象
  cli/              — 语言无关入口
  toolchain-cpp/    — C++ 工具链
  toolchain-python/ — Python 工具链（后续）
  toolchain-rust/   — Rust 工具链（后续）
  toolchain-js/     — JS/TS 工具链（后续）
```

## 5. 架构设计

### 5.1 架构模型

事件驱动。Main Agent 订阅 EventBus 获取 agent/task/tool 事件并渲染 TUI/HUD。

Main Agent 状态机详见 `AirPlan/docs/architecture/main-agent-state-machine.md`：

```text
IDLE → CLASSIFYING（LLM 判断意图）
  → DELEGATING（需要执行时）
  → CONFIRMING（架构级变更需确认，实现级静默通过）
  → EXECUTING（Scheduler 派发任务，Main Agent 监控进度）
  → INTERRUPTING（用户中途变更，LLM 判断意图）
  → SUMMARIZING（汇总结果，触发 ExperienceMiner）
  → IDLE
```

核心约束：Main Agent 必须保持空闲可响应用户介入。后台任务派子代理做。

**确认门控**：实现级变更（不影响接口/架构）→ 静默进入 EXECUTING。架构级变更 → Architecture Designer 评估 → 低权限需确认，高权限自动推进但结果显示给用户。

### 5.2 Agent 层级

```
Main Agent（用户唯一交互入口）
  ├── 对话模式（默认）：不直接操作文件和命令
  └── 直通模式（/direct 触发，/done 退出）

Architecture Designer（全周期架构规划与审查）

Scheduler（任务图拆解、并行/串行调度、进度监控）
  ├── Executor（写代码、改文件、编译、测试验证）
  ├── Reviewer（代码审查、静态分析审查，只读不改代码）
  └── Debugger（证据收集、问题定位、插桩修复，吸收 Fixer 职责）
```

### 5.3 子代理进程模型

每个 Executor/Reviewer/Debugger 是**独立 Bun 进程**（非单进程内异步任务，也非 Worker 线程）。IPC 通过 stdio + JSON。崩溃隔离、上下文隔离、天然适配 worktree。

### 5.4 心跳与超时

- **心跳**：Push 模型。子代理每 N 秒主动推送 `AgentHeartbeat`（当前状态、turn 数、已用 token）
- **超时**：混合硬超时（kill）+ 软超时（警告 + 允许申请延期）。Scheduler 按任务类型分情况决定
- **死循环检测**：同一错误签名出现 N+ 次 → 上报 Main Agent

### 5.5 并发写入策略

轻量 write_area 粗分：

- 不同写集 → 默认可并发
- 相同写集但大概率不写相同代码块 → git worktree 隔离并发，事后合并
- 高概率改同一代码块或公共接口 → 串行

Scheduler 是合并协调者，非统一写入器。lockfile、构建配置、公共 API/schema 默认提高并发风险。

### 5.6 Worker Agent 类型

**Executor**（Claude Code 为行为标杆）：
- 内部 loop：LOADING → THINKING → ACTING → OBSERVING → （调试子循环）→ FINALIZING
- 自治完成完整闭环，不逐步骤汇报
- 出口：TaskCompleted / TaskBlocked / TaskFailed
- TaskSpec 附带 max_turns / acceptance_criteria / timeout

**Reviewer**（只读）：
- 流程规则自动触发（Executor 完成 → Reviewer）
- loop：LOADING → REVIEWING → DECIDING（approved / changes_requested / blocked）

**Debugger**（build/test 失败自动触发）：
- loop：GATHERING → ANALYZING → FIXING → RECORDING 或 ESCALATING
- 产出 DebuggerResult + DebugRecord 候选

三个子代理的 Agent Loop **各自独立实现**，不共享通用 loop 引擎。

### 5.7 流程规则

```text
Executor 完成切片 → 自动触发 Reviewer
build/test 失败 → 自动触发 Debugger
静态分析报警 → 自动触发 Reviewer 或 Debugger
阶段完成 → 自动触发 Architecture Designer 架构审查
项目完成 → Architecture Designer 最终一致性审查
```

### 5.8 需求变更协议

用户需求变更先由 Main Agent 做 LLM 分类：

- execution 级 → Scheduler 直接调整
- possible_design 级 → Architecture Designer 轻量 impact check
- design/interface/goal 级 → Architecture Designer 完整影响评估

Scheduler 基于分类结果或 Arc Revision 调整 TaskGraph。

### 5.9 Worker Result 标准

所有 Worker 结果必须结构化（非自由文本摘要）。格式详见 idea.md 原始定义（ExecutorResult / ReviewerResult / DebuggerResult）。

## 6. C++ Toolchain 工具链

### 6.1 分层

```text
Agent 接口: build(config) → BuildResult, test(filter) → TestResult, analyze() → Diagnostic[]
       ↓
C++ Toolchain Adapter（屏蔽 CMake/MSBuild/Bazel 差异）
       ↓
Native Tool Execution（实际调用 cmake/ninja/msbuild/...）
```

### 6.2 BuildTool

优先级：CMake（内置）> Meson/Bazel/XMake（capability plugin）> Makefile/.sln

冲突处理：多种构建系统文件同时存在 → 询问用户
Generator：Ninja 优先，失败回退 Make
配置失败：BuildTool 内置逻辑先尝试修复 → 失败则交给 Debugger

### 6.3 CompilerDiagnosticParser

**全部走 LLM 解析**（不用正则），生成结构化 Diagnostic + 语义错误签名（归一化 GCC/Clang/MSVC 措辞差异）。链接器错误单独归类。

### 6.4 TestRunner / StaticAnalysis / CodeIntelligence

- TestRunner：CTest + GoogleTest 内置，Catch2/Boost.Test 插件
- StaticAnalysis：cppcheck 内置，clang-tidy 插件
- CodeIntelligence：MVP 走 clangd CLI 模式（spawn 用完即退），LSP daemon 模式后续按需加

### 6.5 compile_commands.json

按需生成（`cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON`），不做持久化缓存。

## 7. Project Model 项目模型

### 7.1 设计原则

- 多语言通用：语言无关层 + 语言特定层分离
- Scanner 只收集文件系统元数据（目录树 + 文件扩展名 + 特殊文件），不读文件内容
- LLM 驱动理解，用户确认修正

### 7.2 Scanner 策略

- **无递归深度限制、无目录排除**——完整目录树本身就是有用的结构信息
- 15 秒硬超时兜底，超时返回部分结果 + incomplete 标记
- 首次全量，后续增量（mtime diff）
- 再打开时加载 project.json + 快速确认顶层无变化，有变化才增量扫描

### 7.3 LLM 驱动的项目初始化

Scanner 收集事实 → Main Agent + LLM 推理 → 提出假设 → 用户确认/修正 → 沉淀

- **Schema 校验**：宽松接受，缺失字段标记 unknown，不让 LLM 反复重试
- **用户纠正**：增量更新单字段 + 提示"关联判断可能受影响"，不自动重写整个 json
- **版本迁移**：打开项目时检测旧 schema → 备份后提示用户确认迁移 → 失败回滚

## 8. Agent 目录结构

### 8.1 全局目录

```text
~/.air/
  ├── config.yaml
  ├── models.yaml
  ├── permissions.yaml
  ├── compaction-rules.md       # 用户模板
  ├── project-index.db          # 最近项目索引，不是 source of truth
  ├── cache/                    # plugins/providers/lsp/downloads
  ├── resources/versions/<version>/
  ├── skills/                   # 跨项目复用技能（SKILL.md 格式）
  └── logs/
      ├── air.log               # 用户可读（启动失败、异常报错）
      └── air.developer.log     # 开发组公钥加密全量调试日志，保留 7 天
```

### 8.2 项目内 `.air/`

```text
<project>/.air/
  ├── shared/                   # 可提交 git，共享给团队
  │   ├── project.json          # 含 stable UUID project_id
  │   ├── permissions.yaml
  │   ├── compaction-rules.md
  │   ├── rules/
  │   │   ├── project-rules.md
  │   │   └── toolchain-rules.md
  │   └── plan/                 # 原 AirPlan 工作流内化
  │       ├── AGENTS.md
  │       ├── plan.md
  │       ├── todo.md
  │       └── docs/
  └── local/                    # 可随项目携带但默认 gitignore
      ├── sessions/<session-id>/
      │   ├── session.db
      │   └── artifacts/
      ├── state/
      ├── backups/              # Git 仓库管理的项目外文件备份
      ├── debug-records.db
      ├── learned-memory.db
      ├── workspaces/
      ├── tmp/
      └── locks/
```

推荐 `.gitignore`：

```gitignore
.air/local/
```

## 9. Provider / Model 抽象层

- 原生支持 Anthropic API + OpenAI API
- 兼容接入：OpenRouter / ollama / 自定义 endpoint（通过 Anthropic/OpenAI 兼容模式）
- **内部存储格式**：Anthropic 原生 content blocks（Claude Code 路线）
- **Provider 转换**：API 边界做双向转换，存回 Anthropic 格式
- **同 provider 切换**：零开销
- **跨 provider 切换**：API 边界双向转换

## 10. Permission 权限模型

### 10.1 核心原则

```text
只读操作 → 永远允许
项目目录内 → 完全开放（含 build 目录，C++ 打包部署需要手动组织运行库）
项目外非系统 → 自动备份 + Git 记录，静默执行
高危系统操作 → 用户确认
```

### 10.2 边界定义

- **Symlink**：按物理路径（follow realpath），防止逃逸
- **`.git/`**：默认写保护（需确认），可在 permissions.yaml 关闭
- **build 目录**：不加特殊规则，Agent 需要完全读写
- **`sudo`**：不算高危（开发机日常操作）
- **高危判断**：静态路径白名单（`/etc/fstab`、`/boot/`、`/etc/default/grub` 等），模糊情况走 LLM escape hatch
- **`~/.air/`**：AirCoding 自身管理，不经过 PermissionEngine

### 10.3 备份与还原

- 项目外文件修改备份为 **Git 仓库**（`<project>/.air/local/backups/`）
- 每次修改 = `cp` + `git add && git commit`（commit message: session_id、agent_type、reason）
- `air restore` 三个粒度：单文件最近版本、指定时间点、整个 session
- 用户手动删备份，不做自动清理

## 11. 会话持久化

### 11.1 存储策略

- 按 session 分库 SQLite（`<project>/.air/local/sessions/<id>/session.db`）
- 消息存储：Anthropic 原生 content blocks（canonical source）
- `message_drafts` 保存流式 assistant 中间态，完成后删除
- 调度状态由 domain tables 持久化：tasks / task_dependencies / task_attempts / agents / tool_runs / command_runs / artifacts / diagnostics / evidence_refs / workspaces / events
- `ui_state` 只保存 UI 恢复状态，定时和退出时 flush
- ProjectionStore 从 DB + EventBus 重建 TUI/HUD view model
- 中断恢复：Scheduler 从 domain tables 重建调度队列，running 状态按心跳时间戳判断存亡

### 11.2 Event Store 分层

- **EventBus**：高频实时事件（TokenDelta、StdoutChunk、AgentHeartbeat），不落盘
- **PersistentEventStore**：durable events（AgentStarted、TaskCompleted、ToolRunCompleted 等），SQLite 主线程同步写入
- **ArtifactStore**：大体积内容（build log、test log、pcap、screenshot），DB 存引用 + 摘要 + hash

## 12. 上下文与记忆系统

### 12.1 记忆分层

```text
Project Rules（权威层，Claude Code 风格 Markdown + frontmatter）
  → Project Profile（事实层）
  → Session Memory（会话层）
  → Learned Experience（学习层，tentative）
  → Debug Knowledge（结构化经验库）
  → User Preference（用户偏好）
```

### 12.2 ExperienceMiner

- **触发**：DebugRecord 产生时 + 会话结束时 + 每 N 轮/工具调用中间触发（Hermes Nudge Engine 风格）
- **执行者**：独立后台子代理，不阻塞 Main Agent
- **去重**：周期性 Curator Daemon（识别重叠技能、建议合并、标记过期、归档无用）
- **自我 patch**：Agent 执行中发现经验/规则不对，转发给 ExperienceMiner 做 patch
- **升级**：非调试经验按出现次数（N=3）提醒升级；调试经验以验证证据为置信度，不打分
- **格式**：SKILL.md（YAML frontmatter + Markdown body）

### 12.3 上下文压缩

- **触发**：Context window 占比达 70%
- **策略**：Markdown + frontmatter 规则文件驱动，三层继承（系统默认 → 用户模板 `~/.air/compaction-rules.md` → 项目规则 `.air/shared/compaction-rules.md`）
- **机制**：Copy-on-Write。快照消息 1-N → 异步压缩（独立 Compactor 子代理）→ 新消息继续追加 → 完成后插入压缩标记。LLM 看到：摘要 + 标记 + 新消息。原始消息保留，LLM 可显式回溯。
- **系统默认模板**：确保没写规则的项目也能正常压缩

## 13. Debug Knowledge Network

- 本地优先，provider 接口预留远程共享
- DebugRecord 结构化存储（症状、错误签名、根因、修复方案、验证步骤、证据引用）
- 隐私：默认不上传，上传前脱敏，显式授权，可撤回

## 14. 分发与日志

### 14.1 分发

- **前期**：二进制 tarball（Bun compile 独立可执行文件 + Bundled Bun runtime + Python 脚本 + 默认资源文件），不发布公开渠道
- **后续**：稳定后再考虑 npm / brew / apt / winget

### 14.2 日志

- `air.log`：用户可读（启动失败、异常报错、环境配置问题）
- `air.developer.log`：开发组公钥加密全量调试日志 + 性能指标，7 天保留
- `air doctor`：崩溃诊断包收集命令；诊断包不自动脱敏，但必须用户显式导出/发送
- 下次启动自动检测异常退出并提示

## 15. 测试策略

- **单元测试**：bun test，CI 每次 push，<30s，无 LLM（覆盖所有确定性逻辑）
- **集成测试**：CI 每次 push，<1min，录制 LLM fixture 回放（覆盖 Agent Loop、Scheduler、IPC、session 持久化、压缩、worktree）
- **E2E 测试**：Release gate，真实 LLM（完整 C++ 项目场景），必须通过

## 16. HUD / Status Layer

- HUD 作为 runtime 内建层，通过 ProjectionStore 消费 DB + EventBus 派生状态（不依赖外部脚本解析 transcript）
- 展示：model/project/git/session/context/tasks/agents/tools/build/test/debug
- Preset：Full / Essential / Minimal
- 参考 claude-hud 的 threshold 颜色、多行布局、中文 label

## 17. 架构决策记录（ADR）

原始 13 项 ADR + 三轮讨论补充的新决策，详见：
- `AirPlan/docs/architecture/decisions-round-1.md`（D-001 ~ D-020）
- `AirPlan/docs/architecture/decisions-round-2.md`（D-021 ~ D-037）
- `AirPlan/docs/architecture/decisions-round-3.md`（D-038 ~ D-059）
- `AirPlan/docs/architecture/main-agent-state-machine.md`

## 18. MVP 第一阶段

```text
C++ local dev loop
+ @opentui/solid TUI
+ durable sessions（项目本地 per-session SQLite，domain tables 持续持久化）
+ Copy-on-Write 上下文压缩（三层继承规则文件）
+ Claude Code 风格 Project Rules + Hermes 风格 ExperienceMiner + Curator
+ local debug knowledge base
+ 事件驱动 EventBus + HUD
+ 二进制分发
```

具体包含：

1. Agent 目录与配置（`~/.air/` + `.air/shared/project.json` + `.air/local/`）
2. LLM 驱动的项目初始化（Scanner → LLM → 用户确认 → `.air/shared/project.json`）
3. 多语言 Project Model（语言无关层 + 语言特定 profile + LanguageDetector 接口）
4. TUI Shell + HUD（`@opentui/solid` + ProjectionStore）
5. SQLite Session Store（项目 `.air/local` per-session 分库，Anthropic 原生格式 + domain tables）
6. C++ Toolchain（BuildTool / DiagnosticParser LLM / TestRunner / StaticAnalysis / clangd CLI）
7. Provider / Model（Anthropic + OpenAI 原生，API 边界转换）
8. Permission 引擎（信任优先 + Git 备份 + 静态白名单高危检测）
9. Agent 分层（Main Agent 状态机 + Architecture Designer + Scheduler + Executor/Reviewer/Debugger 独立进程）
10. Context / Memory（Project Rules + ExperienceMiner + Curator + Copy-on-Write 压缩）
11. Local DebugRecord Store
12. Capability Plugin Prototype（AirSDB 优先改造）