lix-2026
1956a8a21a
- 统一 local-first MVP 后阶段架构口径，补充 process 执行总序和 Reasonix 协作记录 - 归档已完成的 design checklist，标注参考型 process，更新 AGENTS/REASONIX/架构文档 - 补充文件树/主编辑器下载与上下文菜单相关实现、bug 记录和 smoke 脚本 验证：git diff --check；codegraph sync .；cargo test -p mnote-web；node --check scripts/task476-filetree-editor-context-menu-download-smoke.js
363 lines
17 KiB
Markdown
363 lines
17 KiB
Markdown
# Worker D：design 07/10 审查报告
|
||
|
||
> 执行时间：2026-05-27
|
||
> 范围：`design/07-ai/process/` + `design/10-review/process/`
|
||
> 口径：local-first MVP 后阶段统一口径
|
||
> 约束：只读审查，不移动/修改/删除 design 文件
|
||
|
||
---
|
||
|
||
## 综合结论
|
||
|
||
审查的 16 个文档中：
|
||
|
||
| 建议状态 | 数量 | 文档 |
|
||
|---------|------|------|
|
||
| keep-process | 5 | 7-10, 7-12, 7-14, 7-15, 7-27 |
|
||
| mark-process-reference | 6 | 7-17, 7-28, 12, 13, 14, 15 |
|
||
| archive-done（建议归档） | 5 | 7-16, 7-30, 7-31, 7-32, 7-33 |
|
||
|
||
**核心发现**：design 07 中 2026-05-16 之前的文档（7-10/12/14/15）均已叠加 local-first 口径修正，无遗留的「BlockNote 默认主链」或「mnote.doc.markdown_edit 唯一主路径」问题。07 最近的 checklist（7-30~7-33）大部分已完成，仅余次要项。10-review 的四份 doc 均为已消耗的审查参考。
|
||
|
||
---
|
||
|
||
## 逐文档审查
|
||
|
||
### 1. `design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md`
|
||
|
||
**建议状态**：`keep-process`
|
||
|
||
**证据**：
|
||
- Phase 1–7（Page Aggregate → block.move_after）全部已勾，有真实 smoke 证据（tmp JSON + 截图 + 测试通过记录）[phase-1-7-complete]
|
||
- Phase 8 全部未勾：UI / Review Mode 的 4 项均为未完成状态 [phase-8-pending]
|
||
- DONE 条件明确要求 Phase 8 未完成即不能归档 [done-condition-unmet]
|
||
- 已包含 2026-05-16 和 2026-05-19 两轮口径修正，对齐 local-first 文件编辑主线 [section-1.0, 1.0.1]
|
||
|
||
**归档/保留原因**：Phase 8 UI / Review Mode 仍冻结（Phase C 政策），但 Phase 1–7 的实打实执行证据在此文档中集中记录。如果强行归档到 done/，则 Phase 8 的跟踪上下文丢失。
|
||
|
||
**建议补充说明**：无。
|
||
|
||
---
|
||
|
||
### 2. `design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md`
|
||
|
||
**建议状态**：`keep-process`
|
||
|
||
**证据**：
|
||
- Phase A（设计治理）已勾 [phase-a-done]
|
||
- Phase B（Manifest 合同收口）全部未勾 [phase-b-open]
|
||
- Phase C（block-edit-workflow 改造）全部未勾 [phase-c-open]
|
||
- Phase D（Review session）部分已勾（schema 定义），UI 未勾 [phase-d-partial]
|
||
- Phase E（状态统一）全部未勾 [phase-e-open]
|
||
- Phase F（验收 smoke）除 selection guard 外全部未勾 [phase-f-open]
|
||
- 2026-05-18 已补充 local-first 口径修正 [section-0]
|
||
|
||
**归档/保留原因**：定义了当前 AI 编辑的完整架构方向——local-first 文件编辑为主、mnote 兼容工具为辅。Phases B–F 是后续执行 roadmap。
|
||
|
||
**建议补充说明**：Phase C 与 Phase C policy（Phase C 冻结）存在矛盾——本文 Phase C 要求将 block-edit-workflow 改造成 router，但统一口径要求「不要恢复 page-ai fast-path」。建议在本文 Phase C 开头标注「当前仍冻结，待 Phase C 解冻后实施」。
|
||
|
||
---
|
||
|
||
### 3. `design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md`
|
||
|
||
**建议状态**：`keep-process`
|
||
|
||
**证据**：
|
||
- 当前产品默认形态已切到 local-first workspace [section-0-update]
|
||
- 明确两层模型：agent 原生 patch/diff 为主、mnote.doc.markdown_edit 为 compat fallback [section-1-conclusion]
|
||
- Phase A（当前立即）有 5 项，Phase B（Phase A 后）、Phase A/B 后补充、Phase C（远期）均未完成 [section-8-phases]
|
||
- CLI Main 参考分析深入，已转化为采纳清单 [section-2.1]
|
||
|
||
**归档/保留原因**：本文是最全面定义「两层 AI 编辑模型」的设计文档，是当前本地 vs 在线编辑口径的权威来源。Phase A 的部分实现（scope/detail/markdown 优先）仍待执行。
|
||
|
||
**建议补充说明**：无。
|
||
|
||
---
|
||
|
||
### 4. `design/07-ai/process/7-15-page-ai-acp-agent-runtime-unified-layer-v1.md`
|
||
|
||
**建议状态**：`keep-process`
|
||
|
||
**证据**：
|
||
- 17 步执行计划中 step-1 到 step-7 已被后续 checklist（7-30 到 7-33）覆盖 [section-9-low-friction]
|
||
- step-8 到 step-17 仍待实施（Reasonix wrapper、前端运行时选择器、存量迁移、旧代码退役）[steps-in-progress]
|
||
- 不包含勾选状态，是架构设计而非 checklist [no-checkboxes]
|
||
- 已包含 2026-05-18 local-first 口径补充 [section-1.2]
|
||
|
||
**归档/保留原因**：ACP 统一架构的实施蓝图。后续 checklist（7-30~7-33）已覆盖前 7 步，但 step-8 之后仍需此文档指导。
|
||
|
||
**建议补充说明**：建议标注哪些步骤已被 7-30~7-33 覆盖，以便新 reader 快速定位执行状态。
|
||
|
||
---
|
||
|
||
### 5. `design/07-ai/process/7-16-page-block-ai-real-smoke-followup-matrix-v1.md`
|
||
|
||
**建议状态**：`archive-done`
|
||
|
||
**证据**：
|
||
- 3.1 到 3.7 全部已完成，有真实 JSON 和截图证据 [sections-3.1-to-3.7-done]
|
||
- 3.8（UI / Review Mode 边界）全部未勾 [section-3.8-open]
|
||
- 本文开头声明「不新增 AI 功能面」——3.8 是唯一剩余项，且已被 Phase C 政策冻结 [scope-statement]
|
||
- 冻结策略明确写于 7-10 和 7-12：「Phase C 仍冻结，不实施流式 apply 或新的审阅 UI」[phase-c-frozen]
|
||
|
||
**归档/保留原因**：本文范围内的所有可执行 smoke 项目已完成。剩余的 3.8（4 项）属于 Phase C 范畴，当前已被统一口径冻结。继续留在 process/ 会产生「还有事要做」的误导，但实际上这些项不能在当前阶段执行。
|
||
|
||
**建议补充说明**：由于本 worker 只读不移动文件，此建议需人工确认后执行 `mv`。若 3.8 解冻，需重新打开此文档或创建新 checklist。
|
||
|
||
---
|
||
|
||
### 6. `design/07-ai/process/7-17-acp-session-convex-sharing-contract-v1.md`
|
||
|
||
**建议状态**：`mark-process-reference`
|
||
|
||
**证据**：
|
||
- 文档自标「状态：PROCESS / FUTURE」[status-future]
|
||
- Phase A（约束固化）已完成「ACP 默认主链可用、账号作用域写入 Convex、旧 HTTP 主链进入 recycle」[phase-a]
|
||
- Phase B–E 全部标记为项目基本完成后的远期计划 [phases-b-c-d-e]
|
||
- 本文冻结 API 草案形状，不要求当前实施 [section-6-api-draft]
|
||
|
||
**归档/保留原因**：Phase A 已完成。Phase B–E 是项目基本完成后的产品化功能，不改变当前架构方向。保留在 process/ 作为合同参考。
|
||
|
||
**建议补充说明**：无。
|
||
|
||
---
|
||
|
||
### 7. `design/07-ai/process/7-27-online-markdown-writeback-final-content-truth-v2.md`
|
||
|
||
**建议状态**：`keep-process`
|
||
|
||
**证据**：
|
||
- 本文是针对 7-24/7-25 已知缺陷的修复设计 [bug-references]
|
||
- 详细实施计划：6 个步骤（增强 blocks_to_markdown → 实现 parse_final → 实现 build_page_content → 替换写回路径 → 更新 full_content → 清理死代码）[implementation-plan]
|
||
- 新增 5 个测试矩阵 P0/P1 级 [test-matrix]
|
||
- 没有代码已完成的证据：本文是设计稿，代码尚未实施 [no-code-evidence]
|
||
|
||
**归档/保留原因**：是当前活跃的待实施修复。`mnote.doc.markdown_edit` 在线文档路径仍然以「二次推导」而非「最终 markdown」为写回真源，7-27 是改正此问题的方案。
|
||
|
||
**建议补充说明**：高优先级——如果不实施，7-24/7-25 修复后的在线 markdown_edit 在 full_content 和多 operation 场景仍然受限。
|
||
|
||
---
|
||
|
||
### 8. `design/07-ai/process/7-28-resource-ai-tool-contract-v1.md`
|
||
|
||
**建议状态**：`mark-process-reference`
|
||
|
||
**证据**：
|
||
- 定义 mindmap / office 工具合同，无勾选状态 [no-checkboxes]
|
||
- 无实施记录或代码证据 [no-code-evidence]
|
||
- 不属于当前 AI 编辑主路径（主路径是文件编辑 + ACP session）[outside-main-path]
|
||
|
||
**归档/保留原因**：保留在 process/ 作为远期资源工具设计的参考合同。当前不需要实施——mindmap 和 office 的 AI 操作尚未成为产品优先级。
|
||
|
||
**建议补充说明**：无。
|
||
|
||
---
|
||
|
||
### 9. `design/07-ai/process/7-30-acp-session-load-resume-checklist-v1.md`
|
||
|
||
**建议状态**：`archive-done`
|
||
|
||
**证据**：
|
||
- 6/7 项已勾：load_session、ensure_session、ACP run 优先尝试 loaded session、mock 测试覆盖 [checklist-checks]
|
||
- 仅 1 项未完成：「明确区分 MNote session id 与 ACP adapter session id；需要持久化/返回时字段名不能混淆」[remaining-item]
|
||
- 执行记录：2026-05-20 Reasonix 实施 + Codex 复核通过 [exec-record]
|
||
- 验收命令全部通过 [verification-commands]
|
||
|
||
**归档/保留原因**：核心功能（session/load → ensure_session 流程）完整实现并通过 Codex 复核。剩余项是 session id 字段全链路持久化问题，不属于功能性缺陷，适合作为后续产品化工作的一部分跟踪。
|
||
|
||
**建议补充说明**：由于本 worker 只读不移动文件，此建议需人工 `mv` 到 `design/07-ai/done/`。
|
||
|
||
---
|
||
|
||
### 10. `design/07-ai/process/7-31-acp-permission-decision-loop-checklist-v1.md`
|
||
|
||
**建议状态**：`archive-done`
|
||
|
||
**证据**：
|
||
- 文档自标「状态：done」[status-done-header]
|
||
- 6/7 项已勾：incoming handler、pending map、SSE permission.requested、HTTP endpoint resolve、超时 deny [checklist-checks]
|
||
- 仅 1 项未完成：「补 mock ACP 测试：incoming request 等待决策、allow 返回 result、deny 返回 result/error、timeout deny」[remaining-item]
|
||
- 执行记录 + Codex 修正记录详细 [exec-record]
|
||
|
||
**归档/保留原因**：真实 permission 闭环（前端 allow/deny → 后端 JSON-RPC response）已完整实现。剩余 end-to-end mock 测试是测试覆盖的增强项，不妨碍功能完整性。
|
||
|
||
**建议补充说明**：虽然文档自标 done，但未完成项可能会导致后续重构时缺少回归保护。建议归档时在备注中标注此测试缺口。
|
||
|
||
---
|
||
|
||
### 11. `design/07-ai/process/7-32-acp-tool-location-and-open-action-checklist-v1.md`
|
||
|
||
**建议状态**：`archive-done`
|
||
|
||
**证据**：
|
||
- 6/7 项已勾：ToolLocation 结构、locations SSE、tool card 展示、打开按钮 [checklist-checks]
|
||
- 代码层已通过 Codex 复核 [exec-record]
|
||
- 仅 1 项未完成：「补测试覆盖 locations parse、SSE 数据、前端字符串断言或 smoke」[remaining-item]
|
||
|
||
**归档/保留原因**：ACP tool locations 解析、SSE 桥接、前端 tool card 打开动作完整实现。剩余 browser smoke 是验证性补充，核心功能已就绪。
|
||
|
||
**建议补充说明**：无。
|
||
|
||
---
|
||
|
||
### 12. `design/07-ai/process/7-33-acp-session-info-plan-ui-checklist-v1.md`
|
||
|
||
**建议状态**：`archive-done`
|
||
|
||
**证据**：
|
||
- 5/6 项已勾：session.info.updated SSE、plan.updated SSE、前端 title 更新持久化、plan 面板渲染、bridge 单测 [checklist-checks]
|
||
- 仅 1 项未完成：「tool raw output 中包含 todo JSON 时，可以复用 plan 区域或 tool card 状态显示」[remaining-item]
|
||
- 执行记录 + Codex 复核通过 [exec-record]
|
||
|
||
**归档/保留原因**：ACP session info/plan 的完整桥接+UI 链路已实现。剩余 todo JSON 解析项因格式未确认而暂缓，不影响 session 自动标题和 plan 面板功能。
|
||
|
||
**建议补充说明**：无。
|
||
|
||
---
|
||
|
||
### 13. `design/10-review/process/12-sidex-vscode-workbench-gap-review-v1.md`
|
||
|
||
**建议状态**：`mark-process-reference`
|
||
|
||
**证据**：
|
||
- 审查发现的 P0/P1/P2 缺口已拆分为执行 checklist（5-16、5-17、4-38、5-18、5-19、4-39、4-40、5-20、4-41、4-42、5-21、4-43、5-22、5-23、4-44、4-45）[execution-split]
|
||
- 本文本身不再包含待执行项目 [no-remaining-items]
|
||
- 「不建议照搬」部分已明确 MNote 的吸收边界 [section-7]
|
||
|
||
**归档/保留原因**：已完成审查输出——缺口分析已有对应执行文档跟进。本文保留作为 Sidex 对照原始证据和决策记录。
|
||
|
||
**建议补充说明**：无。
|
||
|
||
---
|
||
|
||
### 14. `design/10-review/process/13-hermes-vscode-plugin-gap-review-v1.md`
|
||
|
||
**建议状态**：`mark-process-reference`
|
||
|
||
**证据**：
|
||
- 审查发现的 P0 缺口已拆分为 7-30、7-31、7-32、7-33（均已实施完成）[execution-split-7-30-33]
|
||
- P1/P2 缺口未拆分，但列为后续执行参考 [p1-p2-open]
|
||
- 本文本身无待执行勾选 [no-checkboxes]
|
||
|
||
**归档/保留原因**：审查产出的 4 份 P0 checklist 均已实施。本文保留作为 Hermes VSCode 插件对照的原始证据和 P1/P2 参考。
|
||
|
||
**建议补充说明**：P1/P2 如果后续拆分执行，建议更新本文关联或创建新 review。
|
||
|
||
---
|
||
|
||
### 15. `design/10-review/process/14-sidex-workbench-gap-followup-review-v1.md`
|
||
|
||
**建议状态**：`mark-process-reference`
|
||
|
||
**证据**：
|
||
- 审查发现的缺口已拆分为执行 checklist（5-24、5-25、5-26、4-45）[execution-split]
|
||
- 明确列出「不建议继续照搬」[section-4]
|
||
- 本文本身无待执行项 [no-remaining-items]
|
||
|
||
**归档/保留原因**：同 12——审查已输出到执行 checklist。
|
||
|
||
**建议补充说明**：无。
|
||
|
||
---
|
||
|
||
### 16. `design/10-review/process/15-design-governance-mvp-post-review-v1.md`
|
||
|
||
**建议状态**：`mark-process-reference`
|
||
|
||
**证据**：
|
||
- 本文是当前的 governance 框架文档，定义了本次审查的范式 [meta-document]
|
||
- Workers A/B/C/D 由此散发 [section-3]
|
||
- 不包含待执行代码项 [no-code-items]
|
||
|
||
**归档/保留原因**：是本次治理审查的元文档和框架定义。如果归档，将失去当前治理周期的 root 文档。
|
||
|
||
**建议补充说明**：建议在所有 Worker 报告完成后，将本文与各 Worker 报告一同作为 governance 周期快照归档到 `design/10-review/done/` 或 `design/10-review/process/` 之内保留。
|
||
|
||
---
|
||
|
||
## 最高风险项
|
||
|
||
按风险从高到低：
|
||
|
||
### 🔴 H1：7-27 尚未实施（keep-process）
|
||
|
||
`mnote.doc.markdown_edit` 的在线文档写回路径仍然以「二次推导」而非「最终 markdown」为真源。7-24/7-25 已修复拒绝写入的安全问题，但 full_content 和多 operation 场景的正确性仍未达到设计目标。如不尽快实施，已有 bugfix 的保护措施效果有限，且代码与设计文档的差距会随时间扩大。
|
||
|
||
**建议**：优先安排 7-27 的 6 步实施计划。
|
||
|
||
### 🟡 H2：7-10 Phase 8 冻结与后续解冻风险（keep-process）
|
||
|
||
Phase 1–7 全部完成，但 Phase 8（UI / Review Mode）因 Phase C 政策冻结。如果后续「冻结」解除，接手者需要从零启动——当前 design 文档不承诺 UI 形状、不包含 mockup、不定义用户交互路径。7-16 3.8 的 4 项未勾项同样属此问题。
|
||
|
||
**建议**：在 Phase C 解冻前标记「Phase 8 实施时需新建设计文档，当前只保留缺口清单」。
|
||
|
||
### 🟡 H3：7-15 执行计划分化（keep-process）
|
||
|
||
17 步计划中只有前 7 步被 7-30~7-33 覆盖实施。step-8 之后（Reasonix ACP wrapper、前端运行时选择器、存量迁移、旧代码退役）仍然没有对应的 checklist 或代码证据。若 ACP 架构的目标是「Hermes 与 Reasonix 可互换」，则后续步骤仍需要推动。
|
||
|
||
**建议**：创建 7-34 ~ 7-36 覆盖 Reasonix wrapper、前端选择器和存量迁移。
|
||
|
||
### 🟢 H4：7-30/31/32/33 剩余未完成项（archive-done）
|
||
|
||
这些 checklist 的核心功能已完成，但各有 1 项未完成：
|
||
- 7-30：session id 全链路持久化
|
||
- 7-31：end-to-end mock 测试缺口
|
||
- 7-32：browser smoke 未补
|
||
- 7-33：todo JSON 格式解析
|
||
|
||
**建议**：归档后将这些剩余项汇总到统一 tracker（如 bugs/07-ai/process/ 或 project board），避免分散丢失。
|
||
|
||
---
|
||
|
||
## 无过期口径声明
|
||
|
||
检查所有文档后确认：**没有文档仍在将 `mnote.doc.markdown_edit` 或 `page-ai/block-edit-workflow` 描述为 local-first 普通 Markdown 编辑的唯一/默认主路径。** 2026-05-16 之后的各轮口径修正已正确覆盖：
|
||
|
||
- 7-10 §1.0.1：「local-first 普通正文编辑默认给 Hermes / Reasonix 当前文件引用」
|
||
- 7-12 §0：「local-first 普通 Markdown 编辑默认给 Hermes / Reasonix 授权文件引用」
|
||
- 7-14 §0：「local-first 普通 Markdown 编辑优先给 agent 授权文件引用」
|
||
- 7-15 §1.2：「local-first 普通 Markdown 编辑默认不要求 runtime 调 mnote.doc.markdown_edit」
|
||
- 7-16 §1：「local-first 普通 Markdown 编辑主路径仍是授权文件引用 + agent 原生 patch/diff + watcher 同步」
|
||
- 7-27 §0：「本地 .md 路径的默认 AI 编辑主路径是授权文件引用 + agent 原生 patch/diff + watcher 同步」
|
||
- 7-17、7-28、7-30~33 不涉及编辑主路径定义
|
||
|
||
---
|
||
|
||
## 归档建议汇总（需人工执行）
|
||
|
||
以下文件建议由人工移动到 `done/` 目录：
|
||
|
||
```bash
|
||
# 07-ai 已完成 checklist
|
||
mv design/07-ai/process/7-16-page-block-ai-real-smoke-followup-matrix-v1.md design/07-ai/done/
|
||
mv design/07-ai/process/7-30-acp-session-load-resume-checklist-v1.md design/07-ai/done/
|
||
mv design/07-ai/process/7-31-acp-permission-decision-loop-checklist-v1.md design/07-ai/done/
|
||
mv design/07-ai/process/7-32-acp-tool-location-and-open-action-checklist-v1.md design/07-ai/done/
|
||
mv design/07-ai/process/7-33-acp-session-info-plan-ui-checklist-v1.md design/07-ai/done/
|
||
```
|
||
|
||
10-review 的四份文档保留为参考（mark-process-reference），不归档。
|
||
|
||
---
|
||
|
||
## 验证命令执行摘要
|
||
|
||
```bash
|
||
# 1. 文件列表验证
|
||
find design/07-ai/process design/10-review/process -maxdepth 1 -type f -name '*.md' | sort
|
||
# → 16 files confirmed
|
||
|
||
# 2. 高危模式搜索
|
||
rg -n "mnote\\.doc\\.markdown_edit.*主路径|page-ai.*唯一|BlockNote.*默认" \
|
||
design/07-ai/process design/10-review/process
|
||
# → 无匹配：所有文档已更新口径
|
||
```
|
||
|
||
---
|
||
|
||
## 文件范围
|
||
|
||
本报告写入 `.codex/reasonix-tasks/results/design-governance-worker-d-07-10.md`。
|
||
|
||
未修改 design/ 下任何文件。未提交 git。未运行浏览器 smoke。
|