AirCoding/AirPlan/docs/architecture/DeepSeek系统详细设计审查复查.md

DeepSeek 系统详细设计与 UML 类图全量审查复查

Date: 2026-06-01 Reviewer: DeepSeek V4 Pro（独立全量复查） Scope: 覆盖性 + 内在一致性 + 基线遵守 + 架构合理性 + 内在冲突 + UML 类图完整度 Target commit: af99aed（Opus 4.7 R 系列回归修复后，Opus 4.8 R6 审查前） Inputs:

• 详细设计：system-detailed-design.md（2290 行，23 章节，含 §22 8 张 Mermaid 类图）
• 冻结基线：interface-contracts-v1.md、event-registry-v1.md、db-schema-v1.md、 runtime-semantics-v1.md、scheduler-state-machine-v1.md、main-agent-state-machine.md、 prompt-layering-v1.md、scope-escalation-v1.md、security-model-v1.md、tool-registry-v1.md、 capability-trust-v1.md、artifact-naming-v1.md、error-taxonomy-v1.md、baselineV1.md
• 冻结概要设计：system-overview-design.md
• 此前审查：DeepSeek(R1) / MIMO 2.5 Pro(R2) / GPT-5.5 Pro(R3) / Opus 4.8(R4) / Opus 4.7(R5 回归) / Opus 4.8(R6 复查)

---

1. 审查方法

本次为 DeepSeek 的第二轮独立全量复查（R1 为该模型的初始覆盖性扫描，R7 为本次全量复审）。 与 Opus 4.8 R6 采用不同策略：

1. 枚举差集法：从基线提取全部事件名/表名/契约方法签名，用 comm -23 与 DD 比对，逐条确认聚合写法是否合理。
2. 全量方法名回查：提取 DD 中所有 ContractClass.method() 形式的调用，逐一回查 contracts 文件验证方法真实存在（这是 R5 发现 current_profile() 的同类扫描，本次扩大到全部 22 个点名方法）。
3. FK 不变式逐条比对：DD §18.3 的 8 条不变式与 runtime-semantics §14 逐列对照。
4. 禁止边逐个验证：10 条禁止边各逐条在 DD 中查找对应的执行约束（不要求逐字引用，要求有等效执行条款）。
5. 状态机迁移完整性：6 个状态机的迁移弧与事件投影表交叉校验。
6. UML 类图与正文一致性：按类图逐张核对类成员与对应 DD 章节的一致性。

---

2. 总览结论

维度	状态	说明
契约覆盖	✅ 100%	23 章节全部映射，DD §21.1 矩阵复验通过
事件覆盖	✅ 100%	55 durable + 7 ephemeral，差集法确认仅余聚合条目，无遗漏
DB Schema 覆盖	✅ 100%	16 主表 + 2 项目 DB，schema_meta 归 MigrationRunner
状态机覆盖	✅ 100%	6/6（main / scheduler / task / agent / workspace / capability）
PromptLayer L0-L9	✅ 100%	11 枚举值（含 system_debug）全部映射
禁止边执行	✅ 100%	10/10 各有等效执行条款
UML 类图	✅ 8/8 存在	2 张欠边（§22.4 / §22.7，见 §7）
FK 不变式	✅	DD §18.3 ≡ runtime-semantics §14 逐条一致
Worker exit code	✅	DD §8.1 ≡ baselineV1 §8 逐字一致
R1-01~R2-02 闭合	✅	5/5 复验通过
新增 P0	0
新增 P1	0
新增 P2	4	F1/F5（契约方法越界）、F2/F3（类图欠边）
综合判定	CONDITIONAL PASS

---

3. 覆盖性矩阵

3.1 契约覆盖（23 个章节全映射）

DD §21.1 将 contracts §2-§23 映射到 DD 章节。复验全部 23 个章节的对应 DD 内容均存在且可定位。关键抽样：

契约	DD 章节	抽样复验
§7 EventBus/Store/Ingestor	§5	✓ EventBus.drain?() optional 签名一致
§9 TaskType / TaskSpec	§7, §8.3	✓ 6 个 TaskType 枚举值全对应
§10 IPC direction	§8.2	✓ parent_to_worker / worker_to_parent 方向约束
§12 ToolDefinition.streaming	§9.1	✓ register_streaming 存在
§13 PermissionAction 6 值	§9.3	✓ 6 个 action 分支与契约逐字一致
§14 EvidenceRef 字段	§22.1	✓ 5 字段匹配
§15 ProviderAdapter	§12.2	✓ 接口签名一致
§16 ContextAssembleInput.purpose	§10.1	✓ 6 个 purpose 值一致
§17 ProjectionSnapshot 8 投影	§13.1	✓ 8 个字段名一致
§19 DoctorService.run()	§16.1	⚠ F5
§20 DebugKnowledgeStore	§11.3	✓ lookup_by_signature + lookup_by_task

3.2 事件覆盖（55 durable + 7 ephemeral）

方法：从 event-registry §6 索引提取 55 durable + 7 ephemeral 事件名列表 → 与 DD §5.4 Table A/B 比对 → 差集中 12 个事件名验证为聚合写法。详细：

聚合写法（DD §5.4）	覆盖事件数	覆盖的事件
agent.completed/failed/lost/cancelled	4	4 个 agent 终端事件
doctor.*	6	run.started / issue.found / fix.started / fix.completed / fix.failed / run.completed
permission.prompt.requested/resolved	2	2 个权限提示事件
task_attempts.failure_*	1	task_attempts row append pattern

差集残余检查：剩余的 7 个差集事件（agent.heartbeat、task.progress、assistant.message.delta、tool.progress、command.stdout.delta、command.stderr.delta、hud.frame.rendered）确认为 ephemeral，不入 §5.4 投影表（正确），在 §5.5 节流列表（L459-461）和 §13.1 ProjectionStore 处理列表（L1094-1095）中全部列出。

结论：55 + 7 = 62 事件全覆盖，无遗漏。

3.3 DB Schema 覆盖（16 主表 + 1 schema_meta + 2 项目 DB）

DD §4.3 Repository 清单列出 16 个 Repository 类，与 db-schema §3-§18 的 16 张业务表一一对应：

sessions      → SessionRepository
messages      → MessageRepository
message_drafts → MessageDraftRepository
events        → EventRepository
tasks         → TaskRepository
task_dependencies → TaskDependencyRepository
task_attempts → TaskAttemptRepository
agents        → AgentRepository
tool_runs     → ToolRunRepository
command_runs  → CommandRunRepository
artifacts     → ArtifactRepository
diagnostics   → DiagnosticRepository
evidence_refs → EvidenceRepository
workspaces    → WorkspaceRepository
summaries     → SummaryRepository
ui_state      → UiStateRepository

schema_meta 归 MigrationRunner（DD §4.2 + §21.3 明确），debug_records / learned_memories 归 DebugKnowledgeStore / LearnedMemoryStore（§11.3）。16+1+2 全覆盖。

3.4 状态机覆盖

状态机	基线来源	DD 覆盖	迁移完备性
Main Agent	main-agent-state-machine.md	§14.1 + §20.1	✓ 8 个主要状态 + 6 个 permission_template 映射
Scheduler	scheduler-state-machine-v1.md §4	§7 + §20.2	✓ 11 状态 + 3 终端
Task status	db-schema §7	§20.3	✓ 7 状态 + 9 条迁移
Agent status	db-schema §10	§20.4	✓ 6 状态 + 6 条迁移
Workspace status	db-schema §16	§20.5	✓ 6 状态 + 6 条迁移
Capability lifecycle	capability-trust-v1 §7	§9.5 + §20.6	✓ 9 状态

3.5 PromptLayer L0-L9 覆盖

DD §10.2 两张表覆盖 11 个枚举值 → L# 映射 → Loader。复验 contracts §16 PromptLayerLevel 联合类型共 11 个值，DD §10.2 表中全部列出且 L0-L9 + system_debug 层级正确。✓

---

4. 基线遵守审查

4.1 全量方法名回查

扫描 DD 中所有 ContractClass.method() 调用（22 个唯一方法名），逐一回查 contracts 真实性：

#	方法引用	contracts 存在	判定
1	ArtifactStore.create(input, context)	§14: create(input, context)	✓
2	ContextAssembler.assemble(input)	§16: assemble(input)	✓
3	DebugKnowledgeStore.insert(record)	§20: insert(record)	✓
4	DebugKnowledgeStore.lookup_by_signature(...)	§20: lookup_by_signature(...)	✓
5	EventBus.publish(event)	§7: publish(event)	✓
6	EventStore.append(event, options?)	§7: append(event, options?)	✓
7	EvidenceStore.list_for_task()	§14: ❌ 仅有 list_for_entity()	✗ F1
8	PermissionEngine.evaluate(context)	§13: evaluate(context)	✓
9	PermissionEngine.record(decision, context)	§13: record(decision, context)	✓
10	ProjectionStore.apply(event)	§17: apply(event)	✓
11	PromptLayerLoader.load_role(role)	§16: load_role(role)	✓
12	ProviderManager.complete(input)	§15: complete(input)	✓
13	Scheduler.create_tasks(session_id, specs)	§9: create_tasks(session_id, specs)	✓
14	ToolRegistry.call(name, input, context)	§12: call(name, input, context)	✓
15	DoctorService.check_capability(...)	§19: ❌ 仅有 run()	✗ F5

其余 7 个方法（ContextAssembler.load_layers、RetryPlanner.decide、WavePlanner.plan/assign_workspace、WorkerManager.spawn、WorkerRuntime.call_tool、WorkspaceManager.create_workspace/merge_workspace）属于 DD-internal 类或私有方法，不要求 contracts 对应。✓

结论：2 处契约方法越界（F1 / F5）。与 R5 发现的 PermissionEngine.current_profile() 同型——DD 引用了一个真实契约类上不存在的方法名，违反 §0 "不引入新公开契约" 的自我约束。

4.2 Worker exit code

DD §8.1 表（6 行 exit code 0-5）与 baselineV1 §8 逐字一致。解耦说明："task success/failure through WorkerResult.status, not exit codes" 与 baselineV1 语义一致。✓

4.3 R 系列回归复验

原 ID	验证项	复验结果
R1-01	PermissionEngine.current_profile() 在 DD 和 contracts 中均为 0 处	✓
R1-02	agent.started 投影为单状态 + §20.4 引用	✓
R1-03	memory.promoted/debug.record.created 无 phase 字段	✓
R2-01	overview §10.5 → overview §10.3	✓（唯一出现位置 L602 已修正）
R2-02	16 mandatory files，"only if needed" 已删除	✓

---

5. 架构合理性审查

5.1 依赖方向与无循环

DD §2 复述 c4/module.md 单向依赖：contracts ← llm/toolchain-cpp/tui/runtime ← cli。workers 零运行时导入（仅 contracts + IPC 接口），contracts 包零运行时逻辑。无逆向边，无环。✓

5.2 职责分离

逐项审查：

职责边界	描述	泄漏检测
Scheduler → WorkspaceManager	策略归 Scheduler / 机制归 WorkspaceManager	✓ §7.5 9 行矩阵清晰，WorkspaceManager "never plans, never decides, never re-plans"
EventStore → 领域服务	EventStore 只做投影，不创建 task/permission/memory	✓ §5.1 明确 "ingestor never creates scheduler tasks"
ToolRegistry → PermissionEngine	所有副作用必经 PermissionEngine	✓ §9.1 call 算法第 4 步为 PermissionEngine.evaluate，无后门
CapabilityRegistry → Doctor	依赖安装只走 Doctor	✓ §9.5 L872-873 显式约束
ProviderAdapter → canonical format	全部转换为 Anthropic canonical	✓ §12.2 禁止 "silent semantic prompt loss"
TUI → runtime	TUI 只读 ProjectionClient / UiCommandChannel	✓ §13.2 L1115 "never mutates domain tables"

5.3 事件流时序

producer → EventIngestor → (durable: EventStore tx + projection + post-commit publish | ephemeral: EventBus) 在 DD §5.1 / §5.3 / §18.2 三处描述一致。publish 总是在 commit 之后（contracts §7 rule 3）。✓

5.4 跨 DB outbox

§18.4（R1-03 修复后）采用 "owning store 先外部写 → 成功后 ingest 单个完成态事件" 模型。与 runtime-semantics §6.3（debug.record.created "intent/completion event"）和 §6.4（memory.promoted "completed promotion"）的 baseline 语义一致。event-registry §3 payload（无 phase 字段）被完整尊重。✓

5.5 FK-off 应用层不变式

DD §18.3 的 8 条不变式与 runtime-semantics §14 逐条比对：

#	DD §18.3	runtime-semantics §14	一致性
1	tasks.session_id → sessions.id	tasks.session_id → sessions.id	✓
2	task_attempts.task_id → tasks.id	task_attempts.task_id → tasks.id	✓
3	agents.task_id → tasks.id (not null)	agents.task_id → tasks.id (not null)	✓
4	tool_runs.task_id/agent_id (not null)	tool_runs.task_id/agent_id (not null)	✓
5	command_runs.task_id/agent_id/tool_run_id	command_runs.task_id/agent_id/tool_run_id (not null)	✓
6	workspaces.task_id/agent_id (not null)	workspaces.task_id/agent_id (not null)	✓
7	diagnostics.command_run_id/artifact_id (not null)	diagnostics.command_run_id/artifact_id (not null)	✓
8	evidence_refs foreign columns (not null)	evidence_refs foreign columns (not null)	✓

8/8 逐条一致。✓

---

6. 内在一致性与冲突审查

6.1 跨章节一致性

检查点	来源 A	来源 B	一致性
AgentType 枚举 vs runtime roles	§2 "runtime-resident roles not in AgentType"	§10.2 "runtime roles don't use load_role()"	✓ 自洽
docs TaskType 复用 ExecutorRole	§8.3 "docs reuses ExecutorRole"	§22.5 无新 Role 类	✓ 一致
仅 summary.created 插入 summaries 行	§5.4 Table A	§10.3 / runtime-semantics §7	✓ 一致
compaction 序列 4 事件	§10.3 正文	§19.3 序列图	✓ 一致
command status 推导 5 值	§4.4	contracts §17 CommandRunProjection.status	✓ 一致
Workspace retention 天数	§7.5	overview §15	✓ 一致（merged 7d / abandoned 3d）

6.2 状态机与投影一致性

检查点	状态机	§5.4 投影	一致性
agent.started → starting 或 running	§20.4 starting ──ready──▶ running	§5.4 Table A "starting OR running"	✓ R1-02 修复后自洽
workspace.created → active	§20.5 active 状态	§5.4 Table A insert workspaces	✓
workspace.merge.completed → merged	§20.5 merged	§5.4 Table A status=merged	✓
task.completed → completed	§20.3 completed	§5.4 Table A update tasks.status	✓

6.3 序列图与类图一致性

序列图	涉及类	类图存在	一致性
§19.1 User request	Scheduler/WorkspaceManager/WorkerManager/ContextAssembler	§22.3/§22.2/§22.7	✓
§19.2 Permission prompt	ToolRegistry/PermissionEngine/TUI	§22.4/§13.2	✓
§19.3 Compaction	ContextAssembler/CompactorRole/Scheduler	§22.7	✓
§19.4 Architecture gate	ArchitectureDesigner/ContextAssembler/ProviderManager	§22.8	✓
§19.5 Debug capture	DebuggerRole/DebugKnowledgeStore	§22.5/§11.3	✓

无序列图引用不存在的类或方法。✓

---

7. UML 类图详细审查（§22.1-§22.8 逐张）

图	类数	正文对应章节	正文一致性	欠边
§22.1 契约包	9	§3	✓ EventSource.kind 枚举与 §2 一致	无
§22.2 核心服务	9	§4-§6	✓ EventStore→EventBus "publishes after commit" 准确	无
§22.3 Scheduler	7	§7	✓ Scheduler→6 个组件关系正确	无
§22.4 Tool/Permission	5	§9	✓ 注册/调用关系正确	F3: 缺 ToolRegistry→ToolDefinition / ToolExecutor
§22.5 Worker/IPC	9	§8	✓ 5 个 Role 继承齐全，docs 复用 Executor 无需新类	无
§22.6 Provider	6	§12	✓ 双 adapter + converter + normalizer 边正确	无
§22.7 Context/Compaction	4	§10	✓ ContextAssembler→PromptLayerLoader→PromptLayer 正确	F2: 缺 ContextAssembler→EvidenceStore / SessionStore
§22.8 Agents	2	§14	✓ →Scheduler/ContextAssembler/ProviderManager/EventIngestor 正确	无

F2 详细说明：§10.2 表 2 明确 ContextAssembler 内部装配 L6（Evidence）需读 EvidenceStore，L7（Conversation）需读 SessionStore。但 §22.7 类图仅显示 ContextAssembler→PromptLayerLoader 和 ContextAssembler→CompactionPolicy 两条边。建议补虚线依赖：

ContextAssembler --> EvidenceStore : L6
ContextAssembler --> SessionStore : L7/L8

F3 详细说明：§9.1 ToolRegistry.call() 算法第 1 步为 "look up definition+executor"，且 register/register_streaming 接收 ToolDefinition 和 ToolExecutor 参数。但 §22.4 类图缺少这两条关系边。建议补：

ToolRegistry --> ToolDefinition : registers
ToolRegistry --> ToolExecutor : invokes

---

8. 新发现（P0 / P1 / P2 分类）

F1 [P2] EvidenceStore.list_for_task() 不在契约

• 位置：DD §10.2 表 2 L6 Evidence 行（L932）
• 原文：`EvidenceStore.list_for_task()`
• 问题：contracts §14 EvidenceStore 仅声明 create() 与 list_for_entity(entity_type, entity_id)，无 list_for_task() 方法。
• 根因：为给 L6 的 evidence loading 指定来源，便捷地发明了一个 list_for_task 的命名，但契约只有泛化的 list_for_entity。
• 影响：实现 ContextAssembler 时无法调用 EvidenceStore.list_for_task()，需改为 list_for_entity("task", task_id)。
• 建议：s/EvidenceStore.list_for_task()/EvidenceStore.list_for_entity("task", task_id)/
• 工作量：< 2 分钟

F5 [P2] DoctorService.check_capability() 不在契约

• 位置：DD §16.1（L1201）
• 原文：+check_capability(capability): Promise<DoctorIssue[]>
• 问题：标记为 public（+），但 contracts §19 DoctorService 仅声明 run(input): Promise<DoctorRunOutput>。check_capability 不在契约中。
• 根因：把 DoctorService 的内部分解步骤暴露为公共方法签名。同类的 self_bootstrap 已正确标记为 private（-），但 check_capability 未按同样规范处理。
• 影响：类型系统会期望一个 contracts 中不存在的方法。
• 建议：改为私有 -check_capability(capability): Promise<DoctorIssue[]>，或作为 run() 内部步骤描述。
• 工作量：< 1 分钟

F2 [P2] §22.7 类图缺少 ContextAssembler → EvidenceStore / SessionStore 依赖边

• 见 §7 F2 详细说明。
• 建议：补两条 ..> 虚线依赖，标注 L6 / L7/L8。
• 工作量：< 3 分钟

F3 [P2] §22.4 类图缺少 ToolRegistry → ToolDefinition / ToolExecutor 关系边

• 见 §7 F3 详细说明。
• 建议：补两条 --> 关联，标注 registers / invokes。
• 工作量：< 3 分钟

无 P0、无 P1。

---

9. 门禁判定

条件	状态
P0 = 0	PASS
契约覆盖 100%（23 章节）	PASS
事件覆盖 100%（55 durable + 7 ephemeral）	PASS
DB Schema 覆盖 100%（16+1+2）	PASS
状态机覆盖 100%（6/6）	PASS
L0-L9 覆盖 100%	PASS
禁止边 10/10 有执行约束	PASS
架构无循环依赖	PASS
职责分离无泄漏	PASS
FK 不变式 8/8 一致	PASS
R 系列(R1-01~R2-02) 闭合	PASS
契约方法越界	FAIL（F1 / F5 两处）
UML 类图完整度	CONDITIONAL（F2 / F3 欠边）

门禁结果：CONDITIONAL PASS — 4 项 P2 不阻断实现，合计修复量 < 9 分钟。

---

10. 多轮累积视角

轮次	模型	主要贡献	P0	P1	P2
R1	DeepSeek	全量覆盖性扫描	0	0	3
R2	MIMO 2.5 Pro	内在一致性审查	0	2	5
R3	GPT-5.5 Pro	基线冲突检测	0	2	4
R4	Opus 4.8	验证 + 根因分析	0	2	5
R5	Opus 4.7	修复回归引入检测	0	3	2
—	—	R 系列闭合（commit af99aed）	—	—	—
R6	Opus 4.8	全量复查 + 方法名回查	0	0	4
R7	DeepSeek V4 Pro（本次）	全量复查 + 独立验证（差集法 + 全量方法名回查 + FK 逐条比对）	0	0	4

确认声明：R7（DeepSeek）独立验证了 R6（Opus 4.8）的 4 项 P2 发现，全部确认为真实问题，无新增发现。两轮独立审查结论一致：

• 覆盖性 / 架构性 / 一致性全部 PASS
• 4 项 P2 为同一层次问题：F1/F5 为契约方法越界（与 R5 的 current_profile() 同型），F2/F3 为类图欠边
• 修复量合计 < 9 分钟

---

11. 最终结论与建议

11.1 设计成熟度

详细设计在覆盖性、架构合理性、状态机一致性、事件流时序、跨 DB outbox、FK-off 不变式六大维度均达标。从 23 份基线到 2290 行 DD 的映射完整、无环、无泄漏。R 系列修复已在 af99aed 闭合，本次全量复验未发现回退。

11.2 剩余问题

仅剩 4 项 P2（F1/F5/F2/F3），均为分钟级文字/图形精修。无 P0，无 P1。

11.3 建议

4 项 P2 建议在冻结前合并修复（< 9 分钟），可在单次 commit 中完成：

• L932：EvidenceStore.list_for_task() → EvidenceStore.list_for_entity("task", task_id)
• L1201：+check_capability → -check_capability
• §22.7 mermaid：加 ContextAssembler ..> EvidenceStore / ContextAssembler ..> SessionStore
• §22.4 mermaid：加 ToolRegistry --> ToolDefinition / ToolRegistry --> ToolExecutor

11.4 最终判定

CONDITIONAL PASS (R7) — DeepSeek 独立全量复查确认：详细设计满足全量覆盖与结构正确性，4 项 P2 为局部精修，不阻断实现。建议合并 R6/R7 两轮独立审查的共识发现，一并修复后正式冻结。

---

End of DeepSeek independent full-scope re-audit.