AirCoding/AirPlan/docs/architecture/多模型三视角审查联合评估.md

多模型三视角审查联合评估

Date: 2026-05-28 Status: Resolved — all P0/P1/P2/UX issues addressed; ready for system overview design Scope:

• AirPlan/docs/architecture/MIMO2.5三视角审查.md
• AirPlan/docs/architecture/DeepSeekV4Pro三视角审查.md
• Opus4.7三视角审查.md
• AirPlan/docs/analysis/requirements.md
• AirPlan/docs/architecture/*
• AirPlan/plan.md
• AirPlan/todo.md
• idea.md

1. Executive Conclusion

三份多模型三视角审查在总体方向上高度一致：AirCoding V1.0.0 Alpha 的核心架构方向成立，需求主干对齐，包边界和事件驱动/SQLite 恢复/ToolRegistry + PermissionEngine/独立 worker 进程等关键决策没有方向性错误。

但报告指出的问题大部分属实，且集中在进入下一阶段前最容易放大的层面：公共契约冻结、跨文档源定义冲突、V1.0.0 Alpha 范围表述漂移，以及若干原始用户体验需求未进入 plan.md / todo.md。因此不建议直接进入系统概要设计或详细设计。

阶段门建议：

GO with remediation gate:
先处理 P0/P1 架构与契约清理，再进入系统概要设计；
不要在这些问题未清理前开始 packages/contracts 或详细设计。

2. Cross-Model Consensus

Area	MIMO2.5	DeepSeek V4 Pro	Opus 4.7	Joint assessment
Core architecture direction	正确	正确	正确	属实：方向成立
Requirements alignment	基本满足	完全对齐	技术主干满足、UX 计划遗漏	属实但需区分技术主干与 UX 表面
Interface-contract drift	高风险	高风险	高风险	属实：进入实现前必须清理
DB / event / external store gaps	高风险	高风险	中高风险	属实：尤其 project-level DB schema 与 FK invariant
V1.0.0 Alpha vs MVP wording	未作为主问题	未作为主问题	关键问题	属实：文档漂移影响范围纪律
TUI/runtime boundary	基本认可 ProjectionClient	基本认可 ProjectionClient	认为 transport 未定	部分属实：边界有，传输机制缺
User-facing command/UX gaps	基本认为满足	基本认为满足	明确指出遗漏	属实：计划/todo 未覆盖若干原始需求

3. Verified Findings

P0 — Must fix before next phase

这些问题会导致 packages/contracts 冻结失败、实现者根据不同文档写出不兼容代码，或使下一阶段设计建立在不稳定接口上。

ID	Finding	Source evidence	Verdict	Required action
P0-1	AirError.cause_ref 类型冲突	interface-contracts-v1.md defines cause_ref?: EntityRef; error-taxonomy-v1.md defines multi-key object	True	选定唯一形状。若按 current precedence，改 error-taxonomy-v1.md 为 EntityRef；若采用多引用诊断能力，则更新 interface-contracts-v1.md 并明确 cause_refs 数组
P0-2	EntityRef / EntityType 重复且集合不一致	interface-contracts-v1.md has 12 types including capability and provider; event-registry-v1.md inline EntityRef has 10	True	event-registry-v1.md 不再内联定义，引用 contracts 的 EntityRef
P0-3	PermissionProfile 概念命名冲突	security-model-v1.md uses PermissionProfile = low/normal/high/developer; interface-contracts-v1.md and baselineV1.md use permission_profile = main_direct/executor/...	True	将角色模板字段改为 permission_template 或 role_permission_template；安全态势保留 permission_profile
P0-4	TaskInsert = TaskRecord 不适合作为 insert 契约	interface-contracts-v1.md line concept requires caller-provided generated/default fields	True	定义 TaskInsert / EventInsert 子集类型，移除调用方不应提供的默认/生成字段
P0-5	FollowUpTask.type 包含 docs，但 TaskType 不包含	interface-contracts-v1.md: TaskType lacks docs; `FollowUpTask.type?: TaskType	"docs"`	True
P0-6	DebugKnowledgeStore / LearnedMemoryStore 被运行时语义引用但无契约	runtime-semantics-v1.md references DebugKnowledgeStore and ExperienceMiner/Curator learned-memory writes; interface-contracts-v1.md lacks interfaces	True	在 contracts 或 runtime public contract 中补接口与错误/恢复语义
P0-7	PromptLayer / PromptLayerLoader / CompactionPolicy 被 code-view 引用但 interface contracts 未定义	c4/code-view.md lists classes and PromptLayer[]; interface-contracts-v1.md only has minimal ContextAssembler	True	补上下文层契约，至少定义 PromptLayer、预算结果、加载器/策略边界
P0-8	debug-records.db / learned-memory.db 无 DDL	db-schema-v1.md only defines session DB, while these DBs are in project layout and event/runtime semantics	True	在 db-schema-v1.md 增加 project-level DB schema 或独立 schema 文档并加入 precedence
P0-9	ProviderAdapter 方法名跨文档冲突	interface-contracts-v1.md uses list_models, validate_model, count_tokens; provider-capability-matrix-v1.md uses camelCase	True	统一为 internal exported contracts 的 snake_case，并更新 matrix 文档
P0-10	Diagnostic 类型缺失	c4/code-view.md has DiagnosticParser.parse_compiler_output(...): Diagnostic[]; contracts only define event payload/DB row concepts	True	增加 Diagnostic / DiagnosticRecord / parser output contract

P1 — Should fix before system overview design

这些问题未必阻止 contracts 首次编译，但会影响概要设计的边界表达、测试计划和任务拆解。

ID	Finding	Source evidence	Verdict	Required action
P1-1	V1.0.0 Alpha 与 MVP cut line 术语漂移	多个较旧规范仍有 MVP Cut Line; newer requirements.md, plan.md, runtime-semantics-v1.md use V1.0.0 Alpha	True	将所有规范中的 MVP cut line 改为 V1.0.0 Alpha cut line，或明确定义 MVP skeleton 是 Alpha 内部阶段
P1-2	main-agent-state-machine.md 仍是早期草案	无日期/status；事件名如 UserMessageReceived 不在 event registry；DIRECT_MODE 未与 scheduler/task/write scope 绑定	True	重写或降级为 historical；对齐 event registry、direct mode、confirmation flow
P1-3	C++ DiagnosticParser ownership 表述冲突	baselineV1.md says LLM-based DiagnosticParser; runtime-semantics-v1.md says deterministic extraction in toolchain-cpp and LLM interpretation in runtime Debugger/Reviewer	True	更新 baselineV1.md：toolchain-cpp only deterministic parse/signature；LLM interpretation belongs runtime roles
P1-4	TUI ↔ runtime transport 未定	contracts define ProjectionClient; C4 says narrow UI API; no in-process vs IPC/command-channel contract	Partially true	保留 ProjectionClient 边界，但补 ProjectionTransport / UI command API 的最小 V1 决策
P1-5	foreign_keys = OFF 有理由但缺应用层一致性契约	db-schema-v1.md gives rationale; no orphan/invariant check list	True	在 runtime semantics 或 DB schema 增加 repository invariant checks、orphan scan、release gate
P1-6	EventBus.subscribe handler 异常行为未定义	contracts only define signature; no error propagation semantics	True	明确 handler error 不传播到 publisher，记录 developer log / event，订阅是否保持
P1-7	PermissionEngine.record 无失败路径	returns Promise<void> despite evidence-first and durable decision record expectations	True	改为 Result-like contract 或明确 typed throw / failure event
P1-8	PathPolicy 缺 source/role 元数据	PathPolicy only allow/deny; permission model depends on profile/task/capability layers	Mostly true	若 PathPolicy 只是 raw path list，可延迟；若用于审计决策，需补 source / origin
P1-9	SchedulerWavePlan.wave_id 未品牌化	wave_id: string; other IDs are aliases	True but low impact	增加 WaveID 或接受为 non-persistent local ID并说明
P1-10	ToolCategory / ToolResultEnvelope 重复定义	interface-contracts-v1.md and tool-registry-v1.md both inline definitions	True as documentation drift	tool registry doc 改为引用 contracts；避免未来复制到同一 package 时报重复
P1-11	IPC handshake/protocol lifecycle不足	IpcEnvelope has direction but no protocol_version; only agent.start.version; no worker ready/hello	True	增加 protocol_version 或 worker.ready / version negotiation 最小流程
P1-12	IPC direction not type-enforced	IpcEnvelope.direction exists but payload union not discriminated by direction/kind	True but can be runtime-guarded	最好定义 parent/worker message union；否则明确 runtime validation guard
P1-13	DB closed enums 多处未规范	task_attempts.status, summaries.type, evidence_refs.kind, artifacts.type, diagnostics.severity are open TEXT	True	在 DB schema and contracts 增加 closed enum inventory or documented open extension policy

P2 — Can defer, but should be tracked

ID	Finding	Verdict	Suggested handling
P2-1	JsonSchema<T> phantom generic	True	可先品牌化或记录 nominal-only；不阻塞概要设计
P2-2	ToolExecutor.execute() stream/non-stream union不便测试	True	可在 contracts pass 中拆分 ToolExecutor / StreamingToolExecutor
P2-3	ProjectionStore.apply(RuntimeEvent) 未类型窄化	True	可通过 doc + event handler map 实现；非阶段门阻塞
P2-4	MessageRecord.role: string 等 open string	True	与 P1 closed enum pass 合并处理
P2-5	route_prefix SQLite LIKE 索引性能	Plausible, not architectural blocker	实现/性能测试阶段处理
P2-6	Workspace GC retention	True	加入 runtime semantics/todo；不阻塞 contracts
P2-7	Doctor bootstrap self-check	True	加入 Doctor design/todo；不阻塞 contracts

4. User-Requirement Alignment Check

技术主干需求已经在 requirements.md 和架构中覆盖：自有 runtime、项目本地状态、SQLite 恢复、独立 worker、C++ 深度工具链、PermissionEngine、Provider boundary、OpenTUI ProjectionStore、Doctor、插件/能力基础均成立。

但 Opus 用户视角指出的若干 UX/操作面计划遗漏属实：

Requirement / decision	Evidence	Current plan/todo state	Verdict
/direct / /done direct mode	idea.md §5.2; baselineV1.md says direct mode foreground lane; main-agent-state-machine.md mentions DIRECT_MODE	plan.md and todo.md have no direct-mode task/contract	True gap
air restore three granularities	idea.md §10.3; D-032	no explicit restore task in todo.md	True gap
ExperienceMiner N-turn Nudge trigger	idea.md §12.2; D-024	T-033 only says candidate flow; no cadence/trigger scheduler detail	True gap
Curator periodic dedup/archive	idea.md §12.2; D-024	no todo item	True gap
self-patch flow for stale rules/skills	D-024; runtime-semantics mentions outdated rules route to ExperienceMiner/Curator	no explicit todo/acceptance criterion	True gap
Doctor fix mode and bundle export	FR-018 requires fix mode; plan Phase 8 has doctor report bundle; T-034 only read-only Doctor	Partially covered; todo incomplete
CLI command catalog (resume, compact, history, etc.)	idea-level UX	not in plan.md / todo.md	True gap if intended for Alpha; otherwise explicitly defer
VibeBox branch visibility	branch baseline exists	main plan/todo does not schedule VibeBox	Not blocker for AirCoding Alpha if explicitly downstream/post-Alpha

Conclusion: the architecture does not conflict with user intent, but the Alpha plan risks delivering a strong runtime with an under-specified user-facing command surface unless the omissions are either scheduled or explicitly deferred.

5. Findings That Are Not Fully Supported

Claim	Assessment
foreign_keys = OFF is itself a blocker	Overstated. The setting is documented with rationale in db-schema-v1.md; the real issue is missing invariant/recovery checks, not FK-off itself.
TUI boundary is completely missing	Overstated. ProjectionClient and no-DB/no-EventBus rules exist. Missing part is transport and UI command channel, not the architectural boundary.
Core architecture fails original requirements	Not supported. Requirements are broadly covered; gaps are UX scheduling and contract details.
Provider capability matrix is necessarily over-engineered	Judgment call. It is more elaborate than minimal Alpha, but it supports stated provider flexibility and conversion-report requirements.
14 architecture docs should be trimmed before proceeding	Optional. The real requirement is consistency and precedence, not fewer docs.

6. Recommended Remediation Plan

Pass A — Source-of-truth and vocabulary cleanup

1. Replace or define all MVP Cut Line sections as V1.0.0 Alpha Cut Line / V1 skeleton within Alpha.
2. Add packages/contracts to the canonical package list in baselineV1.md.
3. Mark main-agent-state-machine.md as V1-aligned or historical; if kept, align event names with event-registry-v1.md.
4. Update baselineV1.md DiagnosticParser wording to match runtime-semantics-v1.md.

Pass B — Public contract freeze repair

1. Resolve AirError.cause_ref shape.
2. Single-source EntityRef and EntityType.
3. Rename role permission template field away from security PermissionProfile.
4. Fix TaskInsert, EventInsert, TaskType/docs, WaveID.
5. Add missing contracts: Diagnostic, DebugKnowledgeStore, LearnedMemoryStore, PromptLayer, PromptLayerLoader, CompactionPolicy, EventSchemaRegistry.
6. Normalize ProviderAdapter method names to snake_case.
7. Decide IPC protocol version/handshake and direction-typed unions or runtime validation contract.

Pass C — Persistence/runtime invariant repair

1. Add schema for debug-records.db and learned-memory.db, or create separate canonical schema docs.
2. Add application-level reference consistency invariants for foreign_keys = OFF.
3. Define EventBus subscriber error behavior.
4. Define PermissionEngine record failure behavior.
5. Add closed enum inventory for DB/contract fields or explicitly mark extension points.

Pass D — UX scope gate

1. Decide which UX commands are Alpha: /direct, /done, air restore, resume, compact, history, doctor --fix, doctor --bundle.
2. For included commands, add todo.md rows and plan deliverables.
3. For deferred commands, record explicit post-Alpha scope so they are not silently lost.
4. Add ExperienceMiner Nudge cadence, Curator, and self-patch acceptance criteria if they remain Alpha.

7. Phase-Gate Decision

Do not start implementation or detailed design yet.

Recommended next step:

1. Complete Pass A–C as architecture/document edits.
2. Update `AirPlan/todo.md` with any P0/P1 remediation tasks and UX scope decisions.
3. Then proceed to system overview design.
4. Only after overview design is consistent, produce detailed design and start Phase 0 contracts implementation.

Rationale:

• P0 findings directly affect packages/contracts, DB schema, and code-view boundaries.
• If ignored, they will force contract churn during Phase 0/1 and invalidate parallel execution boundaries.
• The fixes are mostly documentation/contract edits, not architectural redesign.
• Core architecture is sound, so the remediation should be short and bounded rather than a new planning cycle.