admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Initial commit: AirCoding V1.0.0 Alpha architecture baseline

Browse Source 
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
This commit is contained in:
AirCoding
2026-05-28 18:45:01 +08:00
commit 82f3140847
366 changed files with 123826 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
AirPlan/docs/architecture/多模型三视角审查联合评估.md Normal file
View File

@@ -0,0 +1,174 @@
# 多模型三视角审查联合评估
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.