AirCoding/AirPlan/docs/architecture/DeepSeekV4Pro三视角审查.md

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 依赖方向分析

包级依赖方向已收敛为单向无循环图：

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。正确做法是定义子集类型。

建议修复：

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，不提供任何编译时安全检查。要么移除泛型参数，要么定义品牌化类型。

建议修复：

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 用户体验路径

最终开发者体验路径：

$ 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 项立即行动问题，再产出概要设计文档。