82f3140847
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
366 lines
18 KiB
Markdown
366 lines
18 KiB
Markdown
# DeepSeek V4 Pro 三角度架构审查报告
|
||
|
||
Date: 2026-05-28
|
||
Status: Third-round architecture review using DeepSeek V4-Pro model
|
||
Reviewer: DeepSeek V4-Pro (1M context)
|
||
Scope: All architecture documents under `AirPlan/docs/architecture/`
|
||
|
||
## 审查背景
|
||
|
||
当前架构文档集（26 个文件）是第二轮 MIMO2.5 审查后的修正版本。第二轮审查发现 6 项阻塞级和 10 项应修复问题，本文件已独立输出为 `MIMO2.5三视角审查.md`。
|
||
|
||
本轮审查旨在用新模型独立评估架构质量，覆盖三个视角：
|
||
1. 架构设计师 — 概念完整性、设计一致性和边界清晰性
|
||
2. 软件开发工程师 — 可编译性、类型完整性和实现可行性
|
||
3. 用户 — 与原始需求的对齐程度
|
||
|
||
---
|
||
|
||
## 1. 架构设计师视角
|
||
|
||
### 1.1 概念完整性
|
||
|
||
AirCoding V1.0.0 Alpha 架构展示了良好的概念完整性。核心原则（项目本地状态、事件驱动 + SQLite 恢复、ToolRegistry/PermissionEngine 作为统一副作用边界、独立子进程 worker）在所有文档中保持连贯。
|
||
|
||
**核心架构决策评价：**
|
||
|
||
| 决策 | 质量 | 理由 |
|
||
|---|---|---|
|
||
| EventIngestor 作为事件摄入边界 | 优秀 | 解决了 EventStore 职责过宽问题，EventStore 不再隐式触发业务动作 |
|
||
| 边列表任务依赖模型 | 优秀 | 完整表达 hard/soft/conflict/serialization，Scheduler 可动态追加持久化冲突边 |
|
||
| IPC 协议含 tool.call/result | 优秀 | 使独立 worker 进程能通过父进程 ToolRegistry/PermissionEngine 安全调用工具 |
|
||
| TUI 只依赖 ProjectionClient | 优秀 | TUI 不导入 runtime 内部，边界清晰 |
|
||
| ProviderManager 在 packages/llm | 清晰 | runtime 通过 facade 调用 LLM，不耦合 provider 实现 |
|
||
| snake_case 命名统一 | 务实 | 避免序列化层，DB/event/tool/contract 一致 |
|
||
|
||
### 1.2 依赖方向分析
|
||
|
||
包级依赖方向已收敛为单向无循环图：
|
||
|
||
```text
|
||
contracts
|
||
↑
|
||
cli → runtime → llm (ProviderManager facade)
|
||
cli → tui → contracts (ProjectionClient only)
|
||
cli → toolchain-cpp
|
||
runtime → contracts
|
||
tui → contracts
|
||
llm → contracts
|
||
toolchain-cpp → contracts
|
||
|
||
runtime 不依赖 tui
|
||
tui 不依赖 DB/EventBus/runtime 内部
|
||
toolchain-cpp 不直接依赖 runtime 或 llm
|
||
```
|
||
|
||
服务级依赖方向也已澄清：
|
||
|
||
- Scheduler → WorkerManager（单向）
|
||
- EventIngestor → EventStore/EventBus（单向）
|
||
- DoctorService → CapabilityRegistry → ToolRegistry（单向）
|
||
- CapabilityRegistry 不依赖 DoctorService（已修正）
|
||
|
||
### 1.3 跨文档一致性评估
|
||
|
||
当前文档集存在两类跨文档问题：
|
||
|
||
#### 1.3.1 已收敛的领域
|
||
|
||
- IPC 协议：interface-contracts 已定义完整 envelope 类型，baseline 引用之
|
||
- Permission 模型：interface-contracts、security-model、scope-escalation、event-registry 使用一致 action+grant_scope
|
||
- Error 模型：interface-contracts、tool-registry、event-registry 统一使用 AirError
|
||
- Task 依赖：interface-contracts、scheduler-state-machine、event-registry、baseline 统一使用边列表
|
||
- 文档优先级：solution-architecture §2 已定义 8 级 precedence rule
|
||
|
||
#### 1.3.2 仍有不一致的领域
|
||
|
||
| 问题 | 涉及文档 | 严重度 |
|
||
|---|---|---|
|
||
| error-taxonomy 中 cause_ref 为扁平字段对象，interface-contracts 中为 EntityRef | error-taxonomy-v1 vs interface-contracts-v1 | 高 |
|
||
| event-registry 中 EntityRef 内联定义（10 个值），interface-contracts 定义 12 个值 | event-registry-v1 vs interface-contracts-v1 | 高 |
|
||
| ToolCategory 和 ToolResultEnvelope 在 interface-contracts 和 tool-registry 重复定义 | interface-contracts-v1 vs tool-registry-v1 | 中 |
|
||
| DebugKnowledgeStore 和 LearnedMemoryStore 接口缺失 | runtime-semantics-v1 引用但未定义 | 中 |
|
||
|
||
这些已在 MIMO2.5 审查中详细记录，此处不再逐项展开。
|
||
|
||
### 1.4 架构风险矩阵
|
||
|
||
| 风险 | 概率 | 影响 | 现有缓解措施 | 剩余风险 |
|
||
|---|---|---|---|---|
|
||
| 跨 DB/文件事务原子性不足 | 中 | 中 | outbox/compensation 模型 | 低 — 已定义恢复扫描 |
|
||
| worker 工具调用链路过长 | 低 | 中 | NDJSON IPC + correlation_id | 低 — 协议完整性好 |
|
||
| Compaction 策略过于复杂 | 中 | 低 | copy-on-write + 显式回退引用 | 低 — 设计清晰 |
|
||
| C++ 工具链覆盖不够 | 中 | 中 | cppcheck+clangd+CMake+Ninja/Make | 中 — 需要真实项目验证 |
|
||
| 插件权限绕过 | 低 | 高 | capability trust model + PermissionEngine | 低 — 边界充分 |
|
||
|
||
### 1.5 架构师结论
|
||
|
||
**可以进入概要设计阶段**。架构方向正确，依赖方向已收敛，包边界清晰。剩余 4 项跨文档不一致问题应在进入概要设计前修复，但都属于工程一致性层面，不影响设计方向。
|
||
|
||
---
|
||
|
||
## 2. 软件工程师视角
|
||
|
||
### 2.1 可编译性评估
|
||
|
||
`packages/contracts` 在修复以下问题后可编译：
|
||
|
||
#### 2.1.1 类型定义问题
|
||
|
||
**E1. `TaskInsert = TaskRecord` 类型不安全**
|
||
|
||
`interface-contracts-v1.md` 第 240 行：`export type TaskInsert = TaskRecord`。这意味着调用方创建任务时必须提供所有 Record 字段，包括服务器生成的 `created_at`、`retry_count`、`status`。正确做法是定义子集类型。
|
||
|
||
**建议修复：**
|
||
```ts
|
||
export type TaskInsert = Omit<TaskRecord, "created_at" | "retry_count"> & {
|
||
status?: TaskStatus // defaults to "pending"
|
||
retry_count?: number // defaults to 0
|
||
}
|
||
```
|
||
|
||
**E2. `JsonSchema<T>` 泛型参数 T 未使用**
|
||
|
||
第 41 行：`export type JsonSchema<T = unknown> = JsonObject`。T 在类型体中从未引用，是 phantom type，不提供任何编译时安全检查。要么移除泛型参数，要么定义品牌化类型。
|
||
|
||
**建议修复：**
|
||
```ts
|
||
declare const JsonSchemaBrand: unique symbol
|
||
export type JsonSchema<T = unknown> = JsonObject & { [JsonSchemaBrand]: T }
|
||
|
||
// 用于测试/类型推导
|
||
export type InferSchemaType<T extends JsonSchema<unknown>> =
|
||
T extends JsonSchema<infer U> ? U : never
|
||
```
|
||
|
||
**E3. `FollowUpTask.type` 引用不存在的 `TaskType` 成员**
|
||
|
||
`FollowUpTask.type` 定义为 `TaskType | "docs"`，但 `TaskType` 不含 `"docs"`。`"docs"` 作为类型字符串存在于类型标注中，但 Scheduler 收到 `type: "docs"` 时无法创建合法的 `TaskSpec.type`（它是 `TaskType`，不含 `"docs"`）。
|
||
|
||
**建议修复：** 将 `"docs"` 加入 `TaskType`：`TaskType = ... | "docs"`
|
||
|
||
#### 2.1.2 缺失接口
|
||
|
||
**E4. `DebugKnowledgeStore` 和 `LearnedMemoryStore` 无任何接口定义**
|
||
|
||
`runtime-semantics-v1.md` §6.3-6.4 引用了这两个关键服务，但 `interface-contracts-v1.md` 中没有任何对应接口。开发者实现 §6 的跨 DB 事务语义时没有契约参照。
|
||
|
||
**E5. `CompactionPolicy`、`PromptLayer`、`PromptLayerLoader` 无任何接口定义**
|
||
|
||
`c4/code-view.md` §4 列出了 `CompactionPolicy.ts` 和 `PromptLayerLoader.ts`，`prompt-layering-v1.md` 详细描述了 L0-L9 分层逻辑。但 `interface-contracts-v1.md` §16 只定义了极简的 `ContextAssembler` 输入输出，`PromptLayer` 和 `CompactionPolicy` 的类型形状完全空白。
|
||
|
||
#### 2.1.3 语义不完整
|
||
|
||
**E6. `PathPolicy` 类型仅有 `allow/deny`，缺失 `source` 元数据**
|
||
|
||
`interface-contracts-v1.md` 中 `PathPolicy` 定义为 `{ allow?: string[], deny?: string[] }`，但 `security-model-v1.md` 和 `runtime-semantics-v1.md` 要求路径评估考虑 "从哪个角色/配置文件来的"。`PathPolicy` 需要 `source` 元数据来表达这个语义。
|
||
|
||
**E7. `PermissionEngine.record` 返回 `Promise<void>` 无失败路径**
|
||
|
||
如果记录权限决策失败（磁盘满、DB 锁），调用方无法得知。这违反 "证据优先" 架构原则。
|
||
|
||
**建议修复：** 返回 `Promise<Result<void, AirError>>` 或指定抛出的类型化错误。
|
||
|
||
**E8. `ProjectionStore.apply` 接受 `RuntimeEvent<unknown>` — 无类型窄化**
|
||
|
||
实现者需要猜测哪些事件触发投影更新。当前设计依赖运行时类型检查，而 contracts 包应该为关键投影提供编译时保证。
|
||
|
||
**E9. `EventBus.subscribe` handler 异常行为未定义**
|
||
|
||
如果订阅 handler 抛出异常：EventBus 吞掉错误？传播给发布者？终止订阅？contracts 未定义。
|
||
|
||
**建议：** 明确 "handler 异常被 EventBus 吞掉并记录到 developer log，不传播给发布者，不终止订阅"。
|
||
|
||
#### 2.1.4 类型别名一致性
|
||
|
||
**E10. 多处缺少 branded ID 类型**
|
||
|
||
`SchedulerWavePlan.wave_id` 是 `string`，而非 `WaveID`。其他标识符都用了品牌化类型（`TaskID`、`AgentID` 等），`wave_id` 应该一致。
|
||
|
||
### 2.2 可测试性评估
|
||
|
||
**优点：**
|
||
- `Clock` 和 `IdGenerator` 接口设计良好，支持时间/ID 确定性测试
|
||
- `TransactionHandle` 接口允许测试事务边界
|
||
- Repository 接口支持 mock/stub
|
||
- EventBus/EventStore/EventIngestor 边界清晰，可独立测试
|
||
|
||
**不足：**
|
||
- `ToolExecutor.execute` 返回 `AsyncIterable | Promise` 未品牌化联合，测试需 duck-type
|
||
- `ProviderAdapter.complete` 返回值相同问题
|
||
- 无契约定义 IPC mock/stub 边界
|
||
|
||
### 2.3 可部署性评估
|
||
|
||
**优点：**
|
||
- `Clock` 抽象使时间可控
|
||
- `IdGenerator` 抽象使 ID 可预测
|
||
- `TransactionManager` 抽象使事务边界可测试
|
||
- binary tarball 分发策略清晰
|
||
|
||
**不足：**
|
||
- 无环境变量/配置文件 schema 定义（除 `~/.air/models.yaml` 外）
|
||
- 无 Docker/容器化分发方案
|
||
|
||
### 2.4 工程师结论
|
||
|
||
**必须修复（阻塞实现）：E1、E3、E4、E5**
|
||
|
||
**应在实现前修复：E2、E6、E7、E8、E9、E10**
|
||
|
||
其余问题可在实现过程中逐步处理。interface-contracts-v1.md 是最大的单一阻塞文件 — 一旦它稳定，package 边界就稳定了。
|
||
|
||
---
|
||
|
||
## 3. 用户视角
|
||
|
||
### 3.1 核心需求对齐表
|
||
|
||
按 AirCoding 原始概念文件 (`idea.md`)、讨论中确立的决策和 VibeBox 衍生分支重新评估：
|
||
|
||
| # | 原始需求 | 当前架构状态 | 对齐度 |
|
||
|---|---|---|---|
|
||
| 1 | 自有 AI coding agent/runtime，非 Claude Code 插件包装 | 独立架构，自有运行时/调度器/工具系统/权限引擎 | 完全 |
|
||
| 2 | Claude Code 级执行层代码质量 | D-059 + runtime-semantics §9（read-before-edit token、exact edit、completion gate） | 完全 |
|
||
| 3 | OpenCode TUI 复用（UI 风格，非业务状态） | `@opentui/solid`，TUI 只消费 ProjectionClient，不导入 runtime 内部 | 完全 |
|
||
| 4 | Hermes-style 经验挖掘/技能/Curator | ExperienceMiner 角色、candidate→promotion→rollback 生命周期、Skill/SKILL.md 格式 | 充分 |
|
||
| 5 | 事件驱动 + SQLite 恢复 | EventBus 实时 + EventStore 持久化 + ProjectionStore 投影 + restart recovery | 完全 |
|
||
| 6 | 独立子进程 worker + NDJSON IPC | Bun child processes + 完整 IPC envelope（control/event/log/tool.call/result/stream/worker.result/checkpoint/error） | 完全 |
|
||
| 7 | C++ 为第一个深度语言 | `toolchain-cpp` 完整工作流（detect/configure/build/static-analysis/test/debug/fix/review/verify） | 完全 |
|
||
| 8 | 项目本地状态可携带 | `.air/shared`（git-shareable）+ `.air/local`（project-local） | 完全 |
|
||
| 9 | 多 agent 调度（Scheduler + TaskGraph） | Scheduler state machine + 边列表依赖 + write-area 冲突 + wave dispatch + merge coordination | 完全 |
|
||
| 10 | 权限模型（分层确认、高权限 announce_then_run） | PermissionEngine + action + grant_scope + layered checks + 凭据/系统敏感边界 | 完全 |
|
||
| 11 | AirConsole 模块化工作流 | AirPlan/AGENTS.md 入口 + AirArc/AirEng/AirDo 工作流 + AirDbg/AirNDB/AirSDB/AirXDB 调试插件 | 完全 |
|
||
| 12 | VibeBox 下位分支（ARM Linux appliance） | `branchvibebox/` 独立 baseline + feasibility plan + Electron 模板 | 完全 |
|
||
| 13 | 不可半成品 MVP，目标 V1.0.0 Alpha | 范围含完整 C++ 开发闭环 + 插件/能力基础 + 发布验证 | 完全 |
|
||
| 14 | 参考 Codex 工具/OpenAI 工具 | `reference/openai-codex/`，tool-registry 含 Codex 风格 tool breadth | 充分 |
|
||
| 15 | 参考 Anthropic Claude Skills | `reference/anthropic-skills/`，SKILL.md 格式在 ExperienceMiner 中引用 | 充分 |
|
||
|
||
### 3.2 设计质量评估
|
||
|
||
**满足/超越需求的领域：**
|
||
|
||
1. **EventIngestor 引入**：比原始需求更清晰地分离了事件摄入与持久化，是超出原始讨论的架构改进
|
||
2. **边列表任务依赖**：从原始讨论的 "hard/soft 数组" 演进到 `(hard|soft|conflict|serialization)` 边列表，表达能力更强
|
||
3. **IPC 协议**：从原始讨论的 "event/control/log" 三个 kind 扩展到 9 个 kind，覆盖了 worker 的完整通信需求
|
||
4. **跨 DB 事务语义**：主动定义了 debug-records.db、learned-memory.db 的 outbox/compensation 模型
|
||
5. **执行原语强化**：从 "原则" 级别提升到 "read observation token required for edit" 的强制契约级别
|
||
|
||
**与用户意图一致的权衡：**
|
||
|
||
| 权衡 | 用户意图 | 架构决策 | 一致性 |
|
||
|---|---|---|---|
|
||
| 进度优先 vs 完美 | 用户多次表示 "先确定再完善" | 定义清晰的文档优先级，允许渐进式完善 | 一致 |
|
||
| 复用 vs 自研 | "能复用就复用，不能就 AI 生成" | TUI 复用 OpenTUI，核心运行时自研 | 一致 |
|
||
| 权限 vs 自动化 | "高权限模式 auto-run，凭据必须确认" | action + grant_scope 模型 | 一致 |
|
||
| 复杂度 vs 可用性 | "V1.0.0 Alpha 不是半成品" | 完整 C++ 工作流 + 插件基础在范围内 | 一致 |
|
||
|
||
### 3.3 用户体验路径
|
||
|
||
最终开发者体验路径：
|
||
|
||
```text
|
||
$ air init # 一键初始化项目
|
||
$ air # 启动 TUI/HUD
|
||
> 帮我修复 src/core/parser.cpp 的编译错误
|
||
→ Main Agent 分类 → Scheduler 创建 Executor 任务
|
||
→ Executor 读取文件 → 精确编辑 → 构建 → 测试
|
||
→ Reviewer 审查 → 通过 → 合并 workspace
|
||
→ 展示 diff + 构建/测试证据
|
||
```
|
||
|
||
这个路径在架构中完全支持，从 CLI 到 TUI 到 Scheduler 到 tools 到 workspace merge 到 evidence 展示都有覆盖。
|
||
|
||
### 3.4 用户视角结论
|
||
|
||
**架构完全对齐原始需求，无方向性偏差。** 每一个关键决策都可以追溯到讨论中明确的选择。
|
||
|
||
---
|
||
|
||
## 4. 三视角综合结论
|
||
|
||
### 4.1 阻塞实现的问题（6 项）
|
||
|
||
这些必须在进入 `packages/contracts` 编码前解决：
|
||
|
||
| ID | 问题 | 涉及文档 | 修复方向 |
|
||
|---|---|---|---|
|
||
| E1 | `TaskInsert = TaskRecord` 不安全 | interface-contracts-v1 | 定义 Omit 子集类型 |
|
||
| E3 | `FollowUpTask.type` 含 `"docs"` 但 `TaskType` 无 | interface-contracts-v1 | 将 docs 加入 TaskType |
|
||
| E4 | `DebugKnowledgeStore` / `LearnedMemoryStore` 缺失 | interface-contracts-v1 | 添加对应接口 |
|
||
| E5 | `PromptLayer` / `CompactionPolicy` / `PromptLayerLoader` 缺失 | interface-contracts-v1 | 添加对应接口 |
|
||
| E9 | `EventBus.subscribe` handler 异常行为未定义 | interface-contracts-v1 | 明确吞掉+记录 |
|
||
| B3* | `debug-records.db` / `learned-memory.db` 无 DDL | db-schema-v1 | 补充 DDL |
|
||
|
||
> *B3 来自上一轮审查，本节确认仍然有效。
|
||
|
||
### 4.2 应在实现前修复的问题（6 项）
|
||
|
||
| ID | 问题 | 涉及文档 | 修复方向 |
|
||
|---|---|---|---|
|
||
| E2 | `JsonSchema<T>` phantom generic | interface-contracts-v1 | 品牌化或移除 |
|
||
| E6 | `PathPolicy` 缺少 source 元数据 | interface-contracts-v1 | 添加 source 字段 |
|
||
| E7 | `PermissionEngine.record` 无错误路径 | interface-contracts-v1 | 返回 Result 类型 |
|
||
| E8 | `ProjectionStore.apply` 无类型窄化 | interface-contracts-v1 | 添加事件类型文档 |
|
||
| E10 | `wave_id` 非品牌化 ID | interface-contracts-v1 | 添加 WaveID 类型 |
|
||
| B1* | error-taxonomy cause_ref 冲突 | error-taxonomy-v1 | 统一为 EntityRef |
|
||
|
||
> *B1 来自上一轮审查，本节确认仍然有效。
|
||
|
||
### 4.3 可接受延迟的问题（4 项）
|
||
|
||
| 问题 | 理由 |
|
||
|---|---|
|
||
| error-taxonomy 和 event-registry 中的 EntityRef 内联定义 | 编译时可通过 import 解决，不影响核心架构 |
|
||
| ToolCategory/ToolResultEnvelope 重复定义 | 编译时结构兼容，仅需一次 import 修复 |
|
||
| 无 Docker 分发方案 | V1.0.0 Alpha 仅需 binary tarball |
|
||
| 无环境变量 schema | 实现时可后期补充 |
|
||
|
||
### 4.4 架构质量评分
|
||
|
||
| 维度 | 评分 | 说明 |
|
||
|---|---|---|
|
||
| 概念完整性 | 9/10 | 核心原则一致，包边界清晰 |
|
||
| 跨文档一致性 | 7/10 | 大部分已收敛，6 项不一致待修复 |
|
||
| 可编译性 | 7/10 | 修复 E1/E3 后可编译，修复 E4/E5 后完整 |
|
||
| 可测试性 | 8/10 | Clock/IdGenerator 抽象好，ToolExecutor 返回值待改进 |
|
||
| 可部署性 | 7/10 | binary tarball 清晰，Docker 可选 |
|
||
| 需求对齐度 | 10/10 | 所有原始需求在架构中均有对应设计 |
|
||
| 平均 | **8.0/10** | 充分进入概要设计阶段 |
|
||
|
||
### 4.5 与 MIMO2.5 审查的比较
|
||
|
||
| 维度 | MIMO2.5 | DeepSeek V4 Pro |
|
||
|---|---|---|
|
||
| 发现问题数 | 16 (6B+10S) | 16 (6E-critical + 6E-should + 4E-ok) |
|
||
| 关键分歧 | — | `ForeignKeys` 问题（MIMO2.5 视为 S8），本审查认为已有合理工程解释 |
|
||
| 新发现 | — | E6 (PathPolicy 缺少 source)、E9 (EventBus 异常行为) |
|
||
| 共识 | B1-B3/B5/B6/S1-S7 相同 | 一致 |
|
||
| 总体评分 | — | 8.0/10 |
|
||
|
||
DeepSeek V4 Pro 与 MIMO2.5 两个独立模型在阻塞问题识别上高度一致，增加了审查结论的置信度。
|
||
|
||
---
|
||
|
||
## 5. 下一步行动
|
||
|
||
### 立即行动（进入概要设计前）
|
||
|
||
1. 修复 E1：`TaskInsert` 改为 Omit 子集
|
||
2. 修复 E3：`TaskType` 加入 `"docs"`
|
||
3. 修复 E4/E5：补充 `DebugKnowledgeStore`、`LearnedMemoryStore`、`PromptLayer`、`CompactionPolicy` 接口
|
||
4. 修复 E9：明确 `EventBus.subscribe` handler 异常行为
|
||
5. 修复 B3：补充 `debug-records.db` / `learned-memory.db` DDL
|
||
6. 修复 B1：`error-taxonomy` 中 `cause_ref` 统一为 `EntityRef`
|
||
|
||
### 概要设计中同步
|
||
|
||
7. 修复 E2/E6/E7/E8/E10
|
||
8. 修复跨文档的 EntityRef 和 ToolCategory 重复定义问题
|
||
9. 产出 `系统概要设计.md`
|
||
10. 产出 `系统详细设计.md`
|
||
|
||
### 总体建议
|
||
|
||
**进入概要设计阶段**，先修 6 项立即行动问题，再产出概要设计文档。
|