admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
main
AirCoding/AirPlan/docs/architecture/多模型三视角审查联合评估.md
AirCoding 82f3140847 Initial commit: AirCoding V1.0.0 Alpha architecture baseline 
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
2026-05-28 18:45:01 +08:00

175 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 多模型三视角审查联合评估
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`。因此不建议直接进入系统概要设计或详细设计。
阶段门建议：
```text
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 | 将 `docs` 加入 `TaskType`，或把 follow-up docs 从 scheduler task 类型中分离 |
| 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:
```text
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.
Reference in New Issue View Git Blame Copy Permalink