# 7-47 local-first Page AI 写入入口口径漂移

## 状态

- 状态：done
- Owner：07-ai / Page AI / design governance
- 发现时间：2026-05-31

## 现象

`design/10-review/done/11-current-full-architecture-review-v1.md` 保留了“`mnote.doc.markdown_edit` 已是简单正文编辑主路径”的历史结论。但当前 AGENTS、ARCHITECTURE、CURRENT_ARCHITECTURE 与 `7-18` 都已经把 local-first 普通 Markdown 编辑主路径改为：定位真实 `.md` 文件，Hermes/Reasonix 在 allowed roots 内使用自身 patch/diff/文件编辑能力写入，再由 watcher / BufferStore / Page Aggregate 同步。旧 review 结论容易误导后续 worker 继续扩 `mnote.doc.markdown_edit`。

## 证据

- `design/10-review/done/11-current-full-architecture-review-v1.md` 写明 `mnote.doc.markdown_edit` 是简单正文编辑主路径。
- `AGENTS.md` 与 `ARCHITECTURE.md` 当前口径明确：`mnote.doc.markdown_edit` 只作为 cloud / remote agent / compat fallback。
- `design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md` 明确要求 Agent Target Resolver、allowed roots/files、dirty guard 和 agent 原生 patch/diff 主路径。

## 影响

- 后续 Page AI 任务可能绕开 `7-18` 的 target package / allowed roots / dirty conflict 模型。
- AI 写入审计、文件版本冲突和 watcher 同步难以统一。
- `mnote.page.save` / `mnote.doc.markdown_edit` 可能被继续当成 local-first 精确编辑入口扩张。

## 修复建议

- 在 `11-current-full-architecture-review-v1.md` 补充“历史快照，local-first 主路径已被 `7-18` 覆盖”的说明，或在 `7-18` 中添加覆盖旧 review 的显式引用。
- Page AI 新任务默认从 `7-18` 拆 checklist，不从 `11` 的旧 tool 主路径拆实现。
- 对 Hermes tool guidance 增加断言：local-first 普通 Markdown 编辑优先文件引用和 patch/diff，工具写入只作为 fallback。

## 本轮进展

- 2026-05-31：已在 `design/10-review/done/11-current-full-architecture-review-v1.md` 顶部补充历史快照说明，明确当前 local-first 普通 Markdown 编辑主路径以 `AGENTS.md`、`CURRENT_ARCHITECTURE.md`、`ARCHITECTURE.md` 和 `7-18` 为准。
- 2026-06-01：已补 Page AI run 的 `mnote.agent_target_package.v1` 输入和后端 sanitize / allowedFiles 派生，避免 local-first agent 只拿到目录级 `allowedRoots` 而缺少冻结目标文件。该进展只覆盖运行时输入合同，target chip / picker、真实 agent 写入回收和 dirty conflict 仍按 `7-18` 后续阶段推进。

- 2026-06-01：已检查 Hermes client runtime guidance。local-first 分支已经明确“普通 Markdown 编辑优先使用 agent 原生 patch/diff 写入真实文件”；remote/cloud/compat 分支中 `mnote_doc_markdown_edit` 的描述已补上“远端 / cloud / compat”限定，测试名同步改为 `hermes_client_run_guidance_prefers_markdown_edit_only_for_remote_compat_plain_body_edits`。
- 2026-06-01：已给 `design/10-review/done/08`、`09`、`10` 补充历史快照说明，避免旧 review 结论继续覆盖 `7-18` 当前口径。

## 验收

- [x] `rg -n "markdown_edit.*主路径|简单正文编辑主路径|应优先调用 mnote_doc_markdown_edit|mnote_doc_markdown_edit for plain" design AGENTS.md ARCHITECTURE.md CURRENT_ARCHITECTURE.md rust/crates/mnote-web/src/routes/hermes_client.rs -g '*.md' -g '*.rs'` 的剩余命中均属于历史快照说明、已退役/降级口径、old 目录或 remote/cloud/compat 分支。
- [x] Page AI task prompt / skill guidance 中明确区分 local-first 主路径与 cloud/remote/compat fallback。
- [x] `cargo test -p mnote-web hermes_client_run_guidance_prefers_markdown_edit_only_for_remote_compat_plain_body_edits -- --test-threads=1`
