mnote/design/07-ai/done/7-18-agent-edit-clean-dirty-smoke-checklist-v1.md

7-18 Agent edit clean / dirty smoke closure checklist v1

创建时间：2026-06-06

状态：done

Owner：07-ai / 05-editor-mainline / 03-rust-web

父设计：design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md

1. 边界

本 checklist 只推进 local-first 普通 Markdown 的真实 agent 文件编辑闭环，不碰 LightRAG、Knowledge RAG、OCR、evidence index 或 OnlyOffice recipe 扩展。当前另一个 agent 正在修改 LightRAG 相关文件，本轮不得编辑：

• rust/crates/mnote-web/src/routes/knowledge_rag.rs
• rust/crates/mnote-web/src/hermes_tools/knowledge_rag.rs
• design/07-ai/done/7-50-lightrag-knowledge-rag-provider-v1.md
• scripts/task529* 到 scripts/task534*

2. 当前代码证据

已有基础能力：

• Page AI target 会生成 mnote.agent_target_package.v1，并给目标写入 allowedFiles、policy.conflictPolicy=fail_on_dirty_or_stale。
• 发送 run 前会通过 /api/documents/buffer-state 检查 dirty / external modified 状态；阻塞时抛 page_ai_target_buffer_not_writable。
• 后端会生成 mnote.agent_run_envelope.v1，其中 resultPolicy.changedFiles=required、refresh=watcher_or_explicit_resync。
• scripts/reasonix-acp-wrapper.mjs 会把 agentRunEnvelope 写进模型可见 prompt，要求 agent 使用自身文件工具编辑真实文件。
• local_agent_audit_finalize_run 会基于前后快照生成 changedFiles 和 mnote.agent_run_receipt.v1。
• 前端 pageAiDispatchReceiptRefresh(...) 会把 receipt 转成 tree:local-folder-watch-batch 和 mnote:page-ai-tool-write-completed。

当前缺口：

• 没有一条真实浏览器 smoke 证明 agent 原生 patch 修改当前 .md 后，前台 tiptap 在 clean buffer 下可见更新。
• dirty buffer 的阻塞虽然已有函数，但缺少端到端 smoke 证明不会启动可写 run 或不会静默覆盖。
• readonly 写入目前仍偏后置审计：read_only_write_rejected 可以记录结果，但还需要前置拒绝或 tool/ACP 层明确失败。
• 审计快照在 folder context 下会退回 full snapshot；产品化前需要限制为 allowedFiles / changedFiles 优先，并对超限降级有可见记录。

3. 非目标

• 不新增 MNote 普通 Markdown 写入工具。
• 不把 mnote.doc.markdown_edit 恢复为 local-first fallback。
• 不实现 streaming apply、review session、GhostTextOverlay。
• 不要求真实外部大模型；smoke 可以用受控 ACP stub / Hermes test runtime 模拟 agent 原生文件 patch，但必须真实写磁盘文件。
• 不把 LightRAG retrieval、evidence citation 或 OCR sidecar 混入本闭环。

4. Phase A：clean buffer 真实写入回收 smoke

目标：证明 agent 原生文件编辑 -> watcher / receipt -> 当前前台 tiptap 可见更新。

Checklist：

• 新增 scripts/task535-page-ai-local-agent-clean-edit-smoke.js。
• smoke 创建临时 local-folder workspace 和目标 AgentClean.md。
• 浏览器打开该 Markdown，确认 mnote-leptos-tiptap-island-editor-root ready。
• 通过 Page AI 发起本地 agent run，run payload 必须包含 targetPackage.currentFile.relativePath、allowedFiles。
• agent stub / ACP test runtime 只能在 allowedFiles 指向的真实 .md 上做最小 patch。
• run completed 后必须返回或触发 agentRunReceipt.changedFiles，路径为目标 .md。
• 前端必须触发 tree:local-folder-watch-batch，并对当前文档触发 mnote:page-ai-tool-write-completed。
• tiptap 可见正文更新为 agent 写入后的内容，不需要手动 reload。
• 网络断言本路径不调用 /api/documents/save。
• 工具事件断言本路径不调用 mnote.doc.markdown_edit。

验收：

• smoke 输出 tmp/task535-page-ai-local-agent-clean-edit-smoke/result.json，包含 run payload、changedFiles、current refresh、最终 editor text。
• result.json 中 ok=true，usedDocumentsSave=false，usedMarkdownEdit=false。

5. Phase B：dirty buffer 不静默覆盖 smoke

目标：证明用户本地未保存时，agent 写入不会绕过 buffer 冲突模型。

Checklist：

• 新增 scripts/task536-page-ai-local-agent-dirty-guard-smoke.js。
• 打开目标 Markdown 后在 tiptap 中输入未保存内容，制造 BufferStore dirty 状态。
• Page AI target chip / run 前检查能读到 dirty 状态。
• 点击发送可写 run 时，应出现明确阻塞或确认流程；当前最低验收是阻塞并返回 page_ai_target_buffer_not_writable。
• smoke 断言没有启动可写 ACP run。
• smoke 断言磁盘 .md 没有被 agent stub 修改。
• smoke 断言 editor 中未保存内容仍可见。

验收：

• smoke 输出 tmp/task536-page-ai-local-agent-dirty-guard-smoke/result.json。
• result.json 中 ok=true，blockedBeforeRun=true，diskChanged=false，editorDirtyTextStillVisible=true。

6. Phase C：readonly 前置拒绝 smoke

目标：证明 readonly target 不靠事后审计才发现写入失败。

Checklist：

• 新增 scripts/task537-page-ai-local-agent-readonly-write-guard-smoke.js。
• 构造只读授权或只读 targetPackage：permission=read，allowedFiles 可读但不可写。
• 发起“请修改当前文件”的 Page AI run。
• 前端或后端应在启动可写 ACP run 前拒绝，错误码稳定，例如 page_ai_target_readonly 或 local_agent_write_not_allowed。
• 若当前实现只能后置审计，应先把 smoke 写成 RED，记录实际行为，不伪造通过。
• smoke 断言磁盘文件未变化。
• smoke 断言 audit 中没有把 readonly 写入说成成功；若出现 read_only_write_rejected，必须在 UI 可见错误里体现。

验收：

• smoke 输出 tmp/task537-page-ai-local-agent-readonly-write-guard-smoke/result.json。
• result.json 中 ok=true 仅在前置拒绝落地后允许；当前若为 RED，应输出 ok=false 和真实行为证据。

7. Phase D：审计快照范围收口

目标：避免 local agent audit 因 folder context 退回扫全 root，影响大 workspace 和 run 返回速度。

Checklist：

• 后端 local_agent_audit_relative_paths_from_payload(...) 优先消费 agentRunEnvelope.allowedFiles / targetPackage.allowedFiles。
• folder context 不再直接强制 full snapshot；除非用户明确选择 folder-wide edit 且有上限。
• 增加审计上限：文件数、总字节数、耗时；超限时进入 auditScope=truncated，并在 receipt 中可见。
• 单测覆盖 allowedFiles 优先、folder context 不扫全 root、超限截断。

验收：

• cargo test -p mnote-web local_agent_audit -- --test-threads=1 或等价 targeted tests 通过。
• clean smoke 中 audit snapshot 只包含目标文件及必要 changed file。

8. Phase E：文档与 manifest 退役口径

目标：锁死 local-first 普通 Markdown 不走旧 MNote 写入工具。

Checklist：

• Page AI / Hermes guidance 对 local-folder 普通 Markdown 明确优先 agent 原生 patch/diff。
• mnote.doc.markdown_edit 在 manifest 中只标注为 online/cloud/compat 历史工具或结构校验辅助。
• reasonix-acp-wrapper.mjs selftest 断言 prompt 包含“不使用 MNote doc/page write tools for ordinary local Markdown edits”。
• smoke 断言 local-first agent edit 不调用 /api/documents/save、mnote.doc.markdown_edit、mnote.page.save。

验收：

• 7-18-local-first-agent-file-editing-control-plane-v1.md Phase B/C 可勾选。
• 本 checklist 可移动到 design/07-ai/done/，父设计 7-18 仅剩跨 workspace / 多 target 的产品确认项。

补充证据：

• 2026-06-07：task539-local-agent-audit-scope-contract.js 复跑 task535 并断言 targetPackage.allowedFiles=["AgentClean.md"]、runTargetSnapshot.frozenAt 存在、未调用 /api/documents/save / mnote.doc.markdown_edit / mnote.page.save；同时运行 cargo test -p mnote-web local_agent_audit -- --test-threads=1，覆盖 auditScope.scope=allowed_files 与 fileCount=1。

9. 推荐执行顺序

1. 先写 task535 clean smoke，允许 RED，固定真实 run payload / receipt / 前台刷新证据。
2. 再写 task536 dirty guard smoke，优先验证当前已有 dirty blocker。
3. 再写 task537 readonly guard smoke，若当前只能后置审计则保持 RED。
4. 最后做审计快照范围收口和 manifest/guidance 口径收紧。

10. 归档条件

• clean buffer smoke 真实通过。
• dirty buffer smoke 证明不会静默覆盖。
• readonly write smoke 证明前置拒绝或 UI 明确失败。
• local-first 普通 Markdown agent edit 不调用旧 MNote 写入工具。
• LightRAG 相关 diff 不在本 checklist 中被修改或作为验收前置。