# 20 Post-LightRAG / Agent Edit / Runtime hardening checklist v1 > 创建时间：2026-06-07 > > 状态：`done` > > Owner：10-review / 07-ai / 03-rust-web / 05-editor-mainline > > 上位依据： > - `design/07-ai/done/7-50-lightrag-knowledge-rag-provider-v1.md` > - `design/07-ai/done/7-51-lightrag-post-commit-hardening-v1.md` > - `design/07-ai/done/7-18-agent-edit-clean-dirty-smoke-checklist-v1.md` > - `design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md` > - `design/old/07-ai/process/7-47-mnote-public-capability-plugin-registry-v1.md`（历史能力注册表） > - `design/old/10-review/done/19-non-lightrag-design-cleanup-followup-checklist-v1.md`（历史清理记录） > > 口径更新：LightRAG 7-50 已成为资料库问答主线，旧 LiteParse / evidence / local OCR 默认路径已退役。后续不再按“扩 RAG”理解，而是按“post-commit audit、边界硬化、减少 runtime 竞态和能力注册漂移”推进。 ## 1. 当前工作树边界 当前执行本 checklist 前，需要先确认工作树中已有未提交改动的归属，避免覆盖他人或历史提交后的本地调整： - `rust/crates/mnote-web/src/routes/search.rs` - `scripts/task452-local-search-index-browser-smoke.js` - `scripts/task531-lightrag-dashboard-ui-smoke.js` 本 checklist 默认不修改上述文件，除非本轮任务明确转入 local search / dashboard smoke 收口。 ## 2. 执行原则 - 不回滚 7-50 的主线口径：资料库问答、PDF / Office / 图片 OCR、跨资料 citation 默认走 LightRAG。 - 不恢复 `mnote.evidence.*`、`mnote.index.*`、旧 local OCR API 或 LiteParse provider 作为 agent fallback。 - 不把 LightRAG storage、input wrapper、sidecar、chunk、vector、graph 当成用户正文真相；MNote local-folder source 仍是真相。 - 不在普通页面搜索、文件树、编辑器打开路径中引入对 LightRAG 可用性的硬依赖。 - 发现需要更细粒度实施时，先在对应 `design/*/process/` 下拆子 checklist，再实施代码。 - 可以使用 subagent，但 subagent 只能做受控叶子任务：限定读写范围、验证命令、交付文件、禁止再派生 runner / subagent / worktree；主控必须复核 diff 和验证结果。 ## 3. P0：LightRAG 7-50 post-commit audit 目标：确认 7-50 作为 `done` 主线是稳定的，找出需要补的硬边界，不重复建设第二套 RAG。 Checklist： - [x] 只读 review 7-50 相关改动面： - `rust/crates/mnote-web/src/routes/knowledge_rag.rs` - `rust/crates/mnote-web/src/hermes_tools/knowledge_rag.rs` - `rust/crates/mnote-web/src/hermes_tools/manifest.rs` - `rust/crates/mnote-web/src/hermes_tools/skill.rs` - `scripts/reasonix-acp-wrapper.mjs` - `skills/mnote-knowledge-rag/SKILL.md` - 资料库设置 UI、FileTree 状态灯、Page AI final answer smoke。 - [x] 核对 source truth：registry 必须以 MNote source path 为真相；symlink / input wrapper / parsed cache 只作为派生物。 - [x] 核对 delete / prune 语义：`delete-source`、watcher stale sync、prune registry 不得删除用户原始 source。 - [x] 核对 stale / deleted source：source 删除、hash 变化、rename / move 后，旧 LightRAG reference 不得继续作为有效 citation 暴露。 - [x] 核对 status bridge：ingest / reindex 后的状态同步必须是有界 backoff；不得形成长期无界前台 polling。 - [x] 核对 image wrapper：图片 source 生成 Markdown wrapper 后，registry 和 citation 仍映射回原始图片 source，而不是把 wrapper 当用户资料真相。 - [x] 核对 query scope：`sourcePaths` 当前是否只是 query 后过滤 MNote mapped references；若 provider 层未能预过滤，UI / agent 文档必须明确这是“provider 检索后 MNote scope 过滤”。 - [x] 核对 locator 降级：无 page / bbox / sidecar 命中时必须返回并展示 `locatorDegraded=true`，不得伪造页码、bbox 或 block id。 - [x] 核对 LightRAG dashboard：MNote 只打开或嵌入 dashboard，不接管 LightRAG 内部图谱 / 文档任务真相。 审计结论： - source truth、image wrapper、delete 不删用户 source、status bridge 有界 backoff、旧 evidence/index tool retired 口径均有代码和测试证据。 - 发现的缺口已拆到并完成 `design/07-ai/done/7-51-lightrag-post-commit-hardening-v1.md`： - watcher stale sync 删除失败时可能丢失 `lightRagDocId`，后续难以重试 provider orphan doc 删除；Phase A 已补保留 doc id、retry 状态、delete confirmed 后清 doc id 和 unmapped reference 过滤。 - `sourcePaths` 是 provider 检索后过滤 mapped references，HTTP API 仍返回未过滤 `raw`；已显式返回 `sourceScopeMode=post_filter_mapped_references` 与 `rawScopeFiltered=false`。 - sidecar locator 的 `first_positioned_block` fallback 可能在 quote 不匹配时生成错误 page/bbox；已移除 fallback，未匹配时降级到 resourceTab citation。 - degraded citation 的 skill / wrapper / UI 文案已统一，并由 Page AI final answer smoke 覆盖。 - Reasonix wrapper 仍是手写工具表；已补短期 drift guard，长期按 7-47 动态注册。 验证： - [x] `cargo test -p mnote-web knowledge_rag -- --nocapture` - [x] `MNOTE_REASONIX_ACP_SELFTEST=1 node scripts/reasonix-acp-wrapper.mjs` - [x] `node --check scripts/task529-knowledge-rag-citation-resource-tab-smoke.js` - [x] `node --check scripts/task530-knowledge-rag-page-ai-final-answer-smoke.js` - [x] `node --check scripts/task531-lightrag-dashboard-ui-smoke.js` - [x] `node --check scripts/task532-knowledge-rag-docx-ingestion-smoke.js` - [x] `node --check scripts/task533-knowledge-rag-source-watcher-sync-smoke.js` - [x] `node --check scripts/task534-knowledge-rag-source-management-scope-smoke.js` - [x] `node --check scripts/task538-knowledge-rag-source-scope-api-smoke.js` - [x] `node scripts/task529-knowledge-rag-citation-resource-tab-smoke.js` - [x] `node scripts/task530-knowledge-rag-page-ai-final-answer-smoke.js` - [x] `node scripts/task531-lightrag-dashboard-ui-smoke.js` - [x] `node scripts/task532-knowledge-rag-docx-ingestion-smoke.js` - [x] `node scripts/task533-knowledge-rag-source-watcher-sync-smoke.js` - [x] `MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3300 node scripts/task534-knowledge-rag-source-management-scope-smoke.js` - [x] `MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3300 node scripts/task538-knowledge-rag-source-scope-api-smoke.js` 运行态验证结果： - `cargo test -p mnote-web knowledge_rag -- --nocapture` 通过 27 项。 - Reasonix ACP selftest 通过。 - `task529` 已改为当前可重复的 image source 降级 citation 正例；2026-06-07 在当前 3000 通过，验证 query/open_reference citationUrl 能打开 image resource tab，且不伪造 page/bbox。 - `task531` 已改为读取当前 status documents summary，不再硬编码 `Completed (5)` / `Fail (4)` / 固定扫描 PDF doc id；2026-06-07 在当前 3000 通过，验证 Documents / Graph / Retrieval 入口。 - `task530` 已改为当前可重复的 image source degraded citation 场景；2026-06-07 在当前 3000 通过，验证 Page AI Reasonix 最终回答可引用降级 citation，且不编造 p.N / bbox、不泄漏 raw JSON / tool 名。 - `task538` 新增 API-only source scope smoke；2026-06-07 在 3300 新构建通过，验证 `sourceScopeMode=post_filter_mapped_references`、`rawScopeFiltered=false`、references 过滤和 `delete-source` 不删除原始 source。 - `task534` 已修复默认过滤导致 source row 不可见的问题；2026-06-07 在 3300 最新构建通过，覆盖 UI source management、删除索引不删原始 source、删除后 scoped query 不再返回该 source。 - `task532` 当前 3000 通过：DOCX ingestion、degraded citation、Office resource tab 打开均验证成功。 - `task533` 当前 3000 通过：watcher Remove(File) batch、registry stale/delete 标记、query 不继续暴露 deleted source 已验证。 - `7-51` Phase A/B/C/D/E 已完成主要代码硬化和单测/selftest；已移动到 `design/07-ai/done/`。 产出： - [x] 若只发现小问题，直接在本 checklist 记录 audit 结果和 follow-up。 - [x] 若发现需要代码硬化，新建 `design/07-ai/process/7-51-lightrag-post-commit-hardening-v1.md`，拆 Phase A/B/C 后再实施；完成后已归档到 `design/07-ai/done/7-51-lightrag-post-commit-hardening-v1.md`。 ## 4. P1：7-18 agent file edit 归档收尾 目标：把 local-first 普通 Markdown agent 原生文件编辑从 `process` 收到可归档状态。 Checklist： - [x] 补 clean smoke 的真实后端 audit 证据：不要只依赖 mocked SSE receipt；要证明后端 `local_agent_audit` 的 `auditScope` 使用 `allowed_files`。 - [x] 在 `task535` 或新 `task539` 中断言 `auditScope.fileCount=1` 或等价目标文件范围证据。 - [x] smoke 继续断言不调用 `/api/documents/save`、`mnote.doc.markdown_edit`、`mnote.page.save`。 - [x] 补 allowed roots 外写入拒绝验证：run payload 或 agent result 涉及 root 外路径时，后端 / wrapper / 审计层必须拒绝，不得返回成功 receipt。 - [x] 补发送后 frozen target 摘要：消息或 run 记录里能看到当次冻结 target；用户切换 tab 不影响已启动 run 的目标可解释性。 - [x] 多 tab / 跨 workspace / dirty write 确认先拆设计，不强行塞进当前 7-18 归档。 - [x] 更新 `design/07-ai/process/7-18-agent-edit-clean-dirty-smoke-checklist-v1.md` 状态。 - [x] 满足归档条件后移动到 `design/07-ai/done/`。 验证： - [x] `cargo test -p mnote-web local_agent_audit -- --test-threads=1` - [x] `node scripts/task535-page-ai-local-agent-clean-edit-smoke.js` - [x] `node scripts/task536-page-ai-local-agent-dirty-guard-smoke.js` - [x] `node scripts/task537-page-ai-local-agent-readonly-write-guard-smoke.js` - [x] `node scripts/task539-local-agent-audit-scope-contract.js` - [x] 新增 allowed-root 外写入 smoke 或 targeted test。 运行态验证结果： - `task535` 当前 3000 通过：clean buffer 下 agent 原生文件 patch 后，receipt refresh 触发当前文档和 filetree 刷新，tiptap 可见更新，且未调用旧保存/写入工具。 - `task536` 当前 3000 通过：dirty buffer 在 `/runs` 前阻塞，磁盘未变，编辑器 dirty 文本仍可见。 - `task537` 当前 3000 通过：readonly 写入在 `/runs` 前阻塞，磁盘未变。 - `task539` 当前 3000 通过：复跑 `task535`，断言 frozen target / allowedFiles；同时跑 `cargo test -p mnote-web local_agent_audit -- --test-threads=1`，证明后端 auditScope 使用 `allowed_files` / `fileCount=1`，并覆盖 client 注入 root 外 `allowedRoots` 会被 SQLite grant 改写。 ## 5. P2：Local-folder browser event bus 目标：减少 sidebar、document session、resource tab、Page AI receipt 对 local-folder watcher / realtime / refresh 的重复连接和竞态。 先拆设计： - [x] 新建并完成归档 `design/03-rust-web/done/3-24-local-folder-browser-event-bus-v1.md`。 - [x] 盘点现有入口： - `rust/crates/mnote-web/browser/tree-live-controller.js` - `rust/crates/mnote-web/browser/sidebar-tree-live-apply-runtime.js` - `rust/crates/mnote-web/browser/document-session-runtime.js` - `rust/crates/mnote-web/browser/document-resource-tab-runtime.js` - `rust/crates/mnote-web/browser/sidebar-page-ai-runtime.js` - [x] 明确 event bus 的输入源：`/api/realtime/ws` 主链、`/api/tree/events` SSE fallback、Page AI receipt synthesized batch。 - [x] 明确 event bus 的输出事件： - `watch_batch` - `document_changed` - `resource_changed` - `filetree_parent_changed` - `knowledge_rag_source_updated` - `resync_required` - [x] 明确订阅方职责：sidebar 只刷新 projection / filetree parent；document session 只刷新当前文档；resource tab 只刷新当前资源；Page AI 只派发 receipt refresh。 设计产出： - `design/03-rust-web/done/3-24-local-folder-browser-event-bus-v1.md` 已记录当前重复连接来源、bus 输入/输出事件、订阅方职责、分 Phase 实施和 smoke 验收。 实施 Checklist： - [x] 新增浏览器 singleton：同一 `workspaceId/rootUri` 只允许一个 realtime 连接。 - Phase A 已新增 `local-folder-event-bus-runtime.js`，并让 `tree-live-controller.js` 的 local-folder 分支优先通过 `window.__mnoteLocalFolderEventBus.startLocalFolderWatcher(...)` 创建 watcher；`document-session-runtime.js` / `document-resource-tab-runtime.js` 仍待 Phase C 切换后才能勾选总体验收。 - Phase C-1 已让 document session 与 passive resource tab 在 bus 可用时复用 root 级 watcher；`task540` 已验证 sidebar/tree live + document session 同页只创建 1 个 `/api/local-folder/events` EventSource。resource tab + Page AI 全组合仍待 smoke 扩展后勾选总项。 - 扩展 `task540` 覆盖 resource tab 后发现 tree live / resource tab 的 workspaceId 解析可能不一致，已把 bus 连接 key 收口为页面内 `rootUri`，避免同一 root 重复建 watcher。 - `task540` 当前在 3300 通过，已覆盖 document page + passive resource tab + `synthetic_page_ai_receipt` 同页只创建 1 个 `/api/local-folder/events`；真实 Page AI 面板点击到 receipt 的完整 UI 链路仍待扩展。 - [x] 保留 WS 主链和 SSE fallback，但连接创建由 event bus 统一管理。 - 非 local-folder tree live 仍保留 `tree-live-ws` / `tree-live-sse`；local-folder watcher 正常路径由 event bus 统一管理，bus 不可用时保留旧 EventSource fallback。 - [x] `refreshLocalFolderSidebarSnapshot` 增加 orchestrator：同一 tick 合并请求、记录 reason、避免重复 sidebar projection 和 filetree parent refresh。 - [x] sidebar live apply 改为订阅 event bus，不直接拥有全部连接与刷新策略。 - [x] document session 改为订阅当前文档变更事件，不直接假设所有 watch batch 都要刷新。 - [x] resource tab 改为订阅资源路径变更事件，不与 document session 重复处理。 - [x] Page AI receipt 转为 event bus synthetic event，避免 receipt + watcher echo 双刷新。 - 当前仍保留 bus 不可用时的旧 `tree:local-folder-watch-batch` fallback。 验证： - [x] 新增 smoke：同一页面只存在一个 WS 或 EventSource local-folder realtime 连接。 - `scripts/task540-local-folder-event-bus-single-connection-smoke.js` 已新增并在 3300 通过；当前覆盖 sidebar/tree live + document session + passive resource tab + Page AI synthetic receipt，尚未覆盖真实 Page AI 面板点击完整链路。 - [x] 外部修改当前 `.md` 后，tiptap 可见刷新。 - [x] 外部新增 / 删除文件后，filetree 只做局部 parent refresh。 - [x] Page AI agent file edit receipt 后，不重复请求 sidebar projection。 - [x] 复跑 tree realtime 基线：`task446`、`task447`、`task448` 或相邻 smoke。 - `task446` / `task447` / `task448` 当前仍请求无 workspace 的 `/api/tree/commands` cloud/Convex 旧入口，结果为 `convex_retired`，不作为 local-folder event bus 证据。 - 相邻 local-folder runtime smoke 已通过：`task435`、`task436`、`task535`、`task540`。 运行态验证结果： - `task540` 在 3300 最新 mnote-web 通过：document page + passive resource tab + `synthetic_page_ai_receipt` 同页只创建 1 个 `/api/local-folder/events`；连续两个同 tick receipt 只触发 1 次 filetree parent projection，sidebar projection 为 0。 - `task535` 在 3300 最新 mnote-web 通过：真实 Page AI clean agent receipt 后当前文档和 filetree 均刷新，且未调用 `/api/documents/save`、`mnote.doc.markdown_edit`、`mnote.page.save`。 - `task436` 在 3300 最新 mnote-web 通过：当前打开 local `.md` 外部修改后 tiptap 可见刷新，dirty 文档进入冲突保护。 - `task435` 在 3300 最新 mnote-web 通过：外部创建/重命名/删除 Markdown 与非 Markdown 资源后 page tree / filetree 原地更新且无 reload。 ## 6. P3：Page Aggregate local-first hard guard 目标：防止 local-first 文档页回落到 legacy block / compat content 影子路径。 Checklist： - [x] 新建或更新 `design/05-editor-mainline/process/*page-aggregate-local-first-hard-guard*.md`；完成后已归档为 `design/05-editor-mainline/done/5-36-page-aggregate-local-first-hard-guard-v1.md`。 - [x] 复核 `document-tiptap-conversion-runtime.js` 的 source 判定：local-first 正常路径必须优先 `page_aggregate.block_document`。 - [x] 对 `compat.legacy_content` fallback 增加 telemetry 或 DOM diagnostic，便于 smoke 断言。 - [x] local-first `.md` 文档页 smoke 断言不得出现 `compat.legacy_content`。 - [x] cloud / legacy / explicit compat 场景继续允许 fallback，并保留独立 contract test。 - [x] 保存链路继续向 `EditorBlockDocument` / `tiptapDocument` 单一主 payload 收口，不扩大 legacyBlocks 使用面。 验证： - [x] `node scripts/task522-page-aggregate-compat-fallback-contract.js` - [x] `node scripts/task167-local-markdown-title-body-options-no-convex-smoke.js` - [x] 新增并通过 `node scripts/task541-page-aggregate-local-first-hard-guard-smoke.js` - [x] 涉及保存链路时补跑 Page Aggregate body / options smoke；本轮未改保存链路，已用 `task167` 覆盖 local-first title/body/options 写入与回读。 运行态验证结果： - `task522` 通过：`blockDocument` 优先于 legacy content，explicit compat legacy-only 仍允许 `compat.legacy_content`。 - `task167` 通过：local-first Page Aggregate 保持 `projectionSource=local_markdown.content` 且输出 `blockDocument`，标题、正文、页面设置写入后不退回 legacy。 - `task541` 通过：真实浏览器打开 local `.md`，editor root 诊断为 `data-mnote-page-body-source=page_aggregate.block_document`、`data-mnote-page-body-local-compat-fallback=false`、`data-mnote-page-body-hard-guard=local_ok`。 - `cargo test -p mnote-web document_editor_adapter_runtime_contains_host_contracts -- --test-threads=1` 通过，覆盖 runtime source 诊断合同。 ## 7. P4：7-47 capability registry 口径重写与实施 目标：减少 Hermes manifest、Reasonix wrapper、Page AI UI、tool disabled policy 的手写漂移。 先修订设计： - [x] 更新历史 capability registry，将试点从 `mnote-local-index` 改为 `mnote-knowledge-rag`；该注册表现已归档到 `design/old/07-ai/`。 - [x] 删除或改写 `mnote.evidence.*`、`mnote.index.*` 作为 active capability 示例的内容。 - [x] 明确旧 alias：`mnote-document-evidence` / `mnote-local-index` 只映射到 `mnote-knowledge-rag`，不恢复旧工具。 Phase A：只加 registry，不改 UI 行为。 - [x] 新增或整理 capability pack 单一注册表。 - [x] Rust manifest tools 自动带 `capabilityId`。 - [x] `/api/hermes/tools/mnote/manifest` 输出 `capabilities[]`。 - [x] 旧 `/client/skills`、`/client/tools` 响应兼容。 Phase B：UI 消费 capability pack。 - [x] `/api/hermes/client/capabilities` 成为 Page AI “能力”页数据源。 - [x] 能力行展示 tools 数、read/write、contextRefs、enabled 状态。 - [x] Runtime 高级页 tools 按 capability 分组。 Phase C：能力包开关驱动工具硬策略。 - [x] `/api/hermes/client/capabilities/toggle` 同步 skill preference 与 profile tool disabled policy。 - [x] `page_ai_capability_policy()` 过滤 disabled capability。 - [x] `execute_mnote_tool_call()` 对 disabled capability 下的 tool 继续硬拒绝。 Phase D：减少 Reasonix / Hermes adapter 手写漂移。 - [x] Reasonix wrapper 启动时优先读取 Rust manifest 动态注册工具。 - [x] 手写工具表降为 mnote-web 未启动时的 fallback。 - [x] Hermes plugin 若仍需要本机 Python plugin，则从 Rust manifest 生成或同步；当前 repo 主链不直接写 `/home/lix/.hermes/plugins/mnote`，7-47 已记录为后续独立生成条件。 验证： - [x] 新增 Rust tool 后，只改 manifest / capability pack，Page AI 能力页与 Reasonix 工具可见性同步变化。 - [x] 关闭 `mnote-knowledge-rag` 后，agent 不看到该能力摘要。 - [x] 关闭后直接调用 `mnote.knowledge_rag.query` 返回 disabled / capability disabled。 - [x] `MNOTE_REASONIX_ACP_SELFTEST=1 node scripts/reasonix-acp-wrapper.mjs` 通过。 运行态验证结果： - `cargo test -p mnote-web page_ai_capabilities_expose_knowledge_rag_and_toggle_tools -- --test-threads=1` 通过：能力页不暴露 `mnote-local-index`，暴露 `mnote-knowledge-rag`；toggle 后 `mnote.knowledge_rag.query` 在 tools 响应中为 disabled。 - `cargo test -p mnote-web hermes_tools_manifest_exposes_mnote_capability_packs -- --test-threads=1` 通过：manifest 输出 `capabilities[]`，knowledge-rag tools 带 `capabilityIds`，旧 `mnote.index.status` 不注册。 - `MNOTE_REASONIX_ACP_SELFTEST=1 node scripts/reasonix-acp-wrapper.mjs` 通过。 - `timeout 3s env MNOTE_REASONIX_ACP_DEBUG=1 MNOTE_WEB_URL=http://127.0.0.1:3000 node scripts/reasonix-acp-wrapper.mjs