chore: land tree view-state, vault, Pi module split, and repo hygiene
Persist PageTree expand state via control-plane view-state and align chevron/DOM with restored expansion; keep Sidex-style shallow page-tree scan and drop the unused recursive scanner that only added cargo noise. Add password vault workbench routes/runtime/skill/CLI, split page_ai_pi into a module package, and retire Hermes/ACP/OpenHub recycle + root harness evidence from the index while gitignoring recycle and local diag dumps. Archive superseded design/bugs docs under old/, point architecture at ARCHITECTURE.md, and refresh smokes for Pi S1–S7, vault, and editor regressions so the working tree can stay clean.
This commit is contained in:
Agent Board
@@ -1,24 +1,24 @@
|
||||
# MNote knowledge RAG
|
||||
|
||||
> 2026-07-01 口径：当前默认知识库主线切到 RAGFlow。WeKnora 与 LightRAG 只作为 legacy fallback / 显式调试路径，不作为默认资料库问答路径。
|
||||
> 2026-07-19 口径：当前默认知识库主线是 **LightRAG**（runtime 默认 `lightrag_legacy` / `lightrag`）。WeKnora 与 RAGFlow 只作为 env 显式切换的备用 / 调试路径，不是普通资料库问答默认。
|
||||
|
||||
使用场景：用户要求“资料库问答”、跨多本书/论文/PDF/Office 附件问答，或明确需要 RAGFlow 知识库结果。
|
||||
使用场景：用户要求“资料库问答”、跨多本书/论文/PDF/Office 附件问答，或需要可回跳 citation 的知识库结果。
|
||||
|
||||
工具使用：
|
||||
|
||||
- 先用 `mnote.knowledge_rag.status` 检查当前知识库 provider 是否可用、当前 root 是否有 source registry。
|
||||
- 用 `mnote.knowledge_rag.query` 提问。指定资料细节时可传 `sourcePaths`，但当前语义是 provider 检索后，MNote 只过滤返回的 `references`；不要把 `raw` 当作已被 scope 限制的来源。
|
||||
- 当前 RAGFlow provider 的 MNote 后端 query/search/ingest adapter 尚未完成时，先打开 `/knowledge` 使用 RAGFlow 原生页面验证上传、解析、检索、citation 与 `positions`。
|
||||
- 如果返回 `documentStructureIndex`，它只是一张章节地图。需要阅读某个章节范围时，调用 `mnote.knowledge_rag.section_context`，传 `sourcePath` 以及 `startBlockOrdinal/endBlockOrdinal` 或 `startParagraphOrdinal/endParagraphOrdinal`，并限制 `maxBlocks/maxChars`。
|
||||
- 回答必须引用 `references` 中的来源；优先使用返回的 `citationMarkdown`。
|
||||
- 对大书/长文档：query 时传 `includeDocumentStructureIndex=true`（或等价字段）。如果返回 `documentStructureIndex`，它只是一张章节地图；需要阅读某个章节范围时，再调用 `mnote.knowledge_rag.section_context`，传 `sourcePath` 以及 `startBlockOrdinal/endBlockOrdinal` 或 `startParagraphOrdinal/endParagraphOrdinal`，并限制 `maxBlocks/maxChars`。
|
||||
- 回答必须引用 `references` 中的来源；优先使用返回的 `citationMarkdown`。不要在最终回答中手写 `/documents`、`mnote://`、`file://` 或搜索引擎包装链接。
|
||||
- 若需要打开来源，调用 `mnote.knowledge_rag.open_reference`，不要手拼 provider dashboard、`file://` 或 provider 内部路径。
|
||||
- 如果当前 Agent runtime 只有 MCP 入口，优先调用当前 RAGFlow MCP / provider-neutral bridge；WeKnora、`mnote_lightrag_bridge.*` 和 `lightrag_native.*` 只用于 legacy fallback 或显式调试，不作为普通问答首选。
|
||||
- 引入或变更 RAGFlow bridge、`mnote.knowledge_rag.*` 工具、citation 渲染或 open-reference 映射后，必须跑 Page AI 浏览器验收：AI 可见回答包含 citation 链接，点击该链接后 MNote 能打开对应资源并落到 locator。
|
||||
- 如果当前 Agent runtime 只有 MCP 入口，优先走 provider-neutral 的 `mnote.knowledge_rag.*` / MNote LightRAG bridge；`lightrag_native.*` 只在需要原生 graph/documents/pipeline 管理时使用，不要用它绕过 source registry 和 citation 映射。
|
||||
- 引入或变更 LightRAG bridge、`mnote.knowledge_rag.*` 工具、citation 渲染或 open-reference 映射后，必须跑 Page AI 浏览器验收：AI 可见回答包含 citation 链接，点击该链接后 MNote 能打开对应资源并落到 locator。
|
||||
|
||||
边界：
|
||||
|
||||
- 知识库 provider 是派生缓存，不是 MNote Markdown 正文真相。
|
||||
- `filePath` 是 provider-local 名称；只有 registry 命中的 reference 才能映射回 MNote source。
|
||||
- 如果返回 `locatorDegraded: true`，可以使用返回的 `citationMarkdown`，但必须明说“来源定位降级”，不要伪造页码、bbox 或 provider 内部路径。
|
||||
- 当前 provider 不可用时，不要声称资料库已查到；提示用户启动或检查 RAGFlow provider。旧 WeKnora / LightRAG / LiteParse / evidence 检索已退役，不作为默认 fallback。
|
||||
- 当前 provider 不可用时，不要声称资料库已查到；提示用户启动或检查 LightRAG / 知识库服务。旧 WeKnora / RAGFlow / LiteParse / `mnote.evidence.*` 本地 evidence 检索不作为默认 fallback。
|
||||
- MNote 的职责不是重排、补召回或再做一套全文搜索；MNote 只做 allowed roots、source registry、结果过滤、有限 section context 和 citation/open-reference 映射。
|
||||
- 兼容 skill 别名：`mnote-document-evidence` / `mnote-local-index` 只解析到本 skill，不恢复旧 evidence/index 工具面。
|
||||
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
name: mnote_lightrag_bridge
|
||||
description: Use when an agent must query MNote's LightRAG-backed knowledge library through MNote source registry, or convert LightRAG references/file_path/chunk_id into clickable MNote locators.
|
||||
---
|
||||
|
||||
# MNote LightRAG Bridge
|
||||
|
||||
> 2026-06-28 口径：LightRAG bridge 已退为 legacy fallback / 历史调试工具。普通资料库问答默认走 WeKnora / OpenHub，不再优先使用本 skill。
|
||||
|
||||
用途：把 agent 的资料库查询稳定路由到 MNote `knowledge_rag` facade，并把引用映射成 MNote 可点击、可打开、可定位的 locator。
|
||||
|
||||
## 工具分层
|
||||
|
||||
- `mnote_lightrag_bridge.mnote_knowledge_rag_query`：首选资料库问答入口，调用 MNote `/api/knowledge-rag/query`，返回已映射的 references/citations。
|
||||
- `mnote_lightrag_bridge.mnote_knowledge_rag_section_context`：按 `documentStructureIndex` 中的 section range 拉取有限 sidecar blocks/chunks，用于大书/长文档二次阅读，不做召回或重排。
|
||||
- `mnote_lightrag_bridge.mnote_knowledge_rag_open_reference` / `open_mnote_reference`：把 `file_path/chunk_id` 映射为 `citationUrl`、`openAction`。
|
||||
- `lightrag_native`：只在需要 LightRAG 原生 graph/documents/pipeline 管理时使用；普通资料库问答优先走 MNote bridge，避免绕过 source registry 和 citation contract。
|
||||
|
||||
## 使用流程
|
||||
|
||||
1. 资料库问答直接调用 `mnote_lightrag_bridge.mnote_knowledge_rag_query`；大书/长文档问题传 `source_paths` 并设置 `include_document_structure_index=true`。
|
||||
2. 回答依据必须来自返回的 `references[]` / `citations[]`；`documentStructureIndex` 只作章节导航，不单独当证据。
|
||||
3. 需要阅读某章节时，调用 `mnote_knowledge_rag_section_context`，传 `source_path` 以及 `start_block_ordinal/end_block_ordinal` 或 `start_paragraph_ordinal/end_paragraph_ordinal`，并限制 `max_blocks/max_chars`。
|
||||
4. 如已有 LightRAG 原生 `file_path/chunk_id`，调用 `mnote_lightrag_bridge.open_mnote_reference` 或 `mnote_knowledge_rag_open_reference` 转成 MNote locator。
|
||||
5. 最终回答引用 bridge 返回的 `citationMarkdown` 或让 MNote UI 渲染 citation；不要手写 `/documents`、`file://`、LightRAG dashboard URL。
|
||||
|
||||
## 边界
|
||||
|
||||
- `file_path` 是 LightRAG provider 内部文件名，不等于用户本地相对路径。
|
||||
- 普通问答不要直接调用 `lightrag_native.query_*` 绕过 MNote；否则 citations 可能没有 source registry 和定位信息。
|
||||
- 只有 MNote registry 命中的 reference 才能映射回本地资源和页面。
|
||||
- `locatorDegraded=true` 时必须说明“来源定位降级”，不能伪造页码、bbox、段落或坐标。
|
||||
- 不要用 bridge 做召回、重排、全文 fallback 或资料管理。
|
||||
@@ -10,3 +10,4 @@ Rules:
|
||||
- After writing, read the file back with the agent's native file tools and report changed files.
|
||||
- Do not use MNote file tools for pure chat.
|
||||
- If authorization is missing, ask the user to grant access instead of guessing a path.
|
||||
- **Password vault is forbidden:** never read, write, list, patch, or search `.mnote/vault/**` (entries, cipher-book, index, audit, trash, attachments) via local file tools or generic open/resource APIs. Credentials and cipher fragments go through the password vault UI / `mnote.vault.*` (see skill `mnote-vault`) and share-to-ai — not this skill.
|
||||
|
||||
@@ -1,33 +0,0 @@
|
||||
# MNote local index
|
||||
|
||||
使用场景：需要检索本地工作区资料、引用可回跳证据，或让 agent 帮忙查看、新增、刷新、删除本地索引范围。
|
||||
|
||||
证据检索：
|
||||
|
||||
- 先用 `mnote.evidence.search` 搜索资料证据，回答时保留返回的 `quote`、`source` 和 `openAction`。
|
||||
- `mnote.evidence.search` / `mnote.evidence.read` 会返回 `citationUrl`、`citationLabel`、`citationMarkdown`。最终回答引用时优先直接使用 `citationMarkdown`，格式如 `[文件名 · p.3](citationUrl)`；该链接在 MNote Page AI 中点击会在当前页面的资源新 tab 打开，并按 `page` / `bbox` / `blockId` / `sourceMapPath` 跳转或高亮到证据位置。
|
||||
- 如果用户查询语言与资料语言可能不一致，不要假定目标资料语言，也不要只把整句原文直接丢给 FTS。先保留用户意图，再根据文件名、题名、领域术语和已知上下文生成 2-6 个轻量多语关键词候选；不确定时优先同时尝试原语言关键词和常见英文术语。中文问法查生命科学文献时，例如“分子对接软件”可扩展为 `分子对接`, `molecular docking`, `docking software`, `AutoDock`, `Vina`。
|
||||
- 关键词扩展只是检索策略，不是结论。回答仍按用户语言组织，且只根据 evidence 结果确认事实。
|
||||
- 需要更多上下文时，用 `mnote.evidence.read` 按 locator 读回周边证据。
|
||||
- 需要让 UI 打开定位时，用 `mnote.evidence.open`，不要自行拼接 URL。
|
||||
|
||||
索引管理：
|
||||
|
||||
- 用 `mnote.index.status` 查看当前 root 的 `settings`、`effectiveSettings`、索引文件是否存在、文档数和证据块数。
|
||||
- 用 `mnote.index.update_settings` 新增或删除索引范围。`includePaths` 是 root 内相对路径；已保存范围视为固化记录，不直接改目录。要改目录时，删除旧范围并新增新范围。
|
||||
- `includePaths: []` 表示删除当前用户的索引范围；当没有任何有效范围时，会清空 `.mnote/index/search-index.json` 和 `.mnote/index/evidence.sqlite`。
|
||||
- 用 `mnote.index.refresh` 重建当前有效范围的索引缓存。刷新只重建索引，不修改 Markdown 正文。
|
||||
|
||||
写入约束：
|
||||
|
||||
- 调用 `mnote.index.update_settings` 必须显式携带 `dryRun` 和 `idempotencyKey`。
|
||||
- 在只读或共享只读 AI scope 下，不要调用 `mnote.index.update_settings`。
|
||||
- `dryRun: true` 只返回计划，不写设置、不重建索引。
|
||||
|
||||
回答要求：
|
||||
|
||||
- 关键事实必须带可回跳来源，至少包含文档名、资源名或页码、quote 摘要。
|
||||
- 关键事实后必须给可点击引用链接；如果 `citationMarkdown` 缺失，先调用 `mnote.evidence.open` 取得 `citationUrl`，不要自己拼 `file://`、`.mnote/index` 或 OCR sidecar 路径。
|
||||
- 不要直接读取 `.mnote/index`、OCR sidecar 或 provider 原始响应来替代 evidence tool。
|
||||
- 不要把 OCR 文本当成 owner Markdown 正文真相。
|
||||
- 如果 evidence 结果没有 page、bbox 或 section，只说明定位能力降级，不伪造页码。
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: mnote-vault
|
||||
description: >
|
||||
MNote AI 密码本（多 agent 唯一策略）。登录优先 mnote.vault.login（复用/刷新 session）；
|
||||
取密 mnote.vault.resolve；禁扫 .mnote/vault 文件。Cloudflare 时人机验证后 session 回写。
|
||||
---
|
||||
|
||||
# MNote 密码箱 / AI 密码本
|
||||
|
||||
**SSOT**：`/home/lix/.agent-infra/vault-policy.md`
|
||||
|
||||
## 稳态：登录（目标约 3 次 shell：鉴权 + list? + login×2）
|
||||
|
||||
```
|
||||
# 本机 mnote-web 鉴权（一次性，非 vault）
|
||||
eval $(node scripts/mnote-vault-cli.js auth-e2e)
|
||||
|
||||
# 可选 list 找 id；已知 id 则跳过
|
||||
node scripts/mnote-vault-cli.js list
|
||||
|
||||
# 核心：复用 session / 登录并保存
|
||||
node scripts/mnote-vault-cli.js login --id <id>
|
||||
# 再调一次应 reused=true
|
||||
|
||||
# Cloudflare：人验证后
|
||||
node scripts/mnote-vault-cli.js session --id <id> --cookie '...'
|
||||
```
|
||||
|
||||
Pi：`mnote.vault.login` / `session` 同语义。
|
||||
|
||||
**禁止**每次：读 policy、猜 /api/auth 路径、list+resolve+多次 chrome 试错。
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| `mnote.vault.login` | **首选**：复用/刷新登录态 |
|
||||
| `mnote.vault.session` | 人机验证后回写 Cookie |
|
||||
| `mnote.vault.list` / `get` | 选型；L0 无密文 |
|
||||
| `mnote.vault.resolve` | 仅当需要密码本身（非登录会话） |
|
||||
|
||||
HTTP/CLI 同语义：`/api/vault/ai/items/{id}/login|session`、`scripts/mnote-vault-cli.js login|session`。
|
||||
|
||||
## 硬规则
|
||||
|
||||
1. 禁 file/local_file 扫 `.mnote/vault/**`
|
||||
2. 聊天不贴 password/cookieHeader
|
||||
3. 长期态存在 **AI 密码本条目**（session + playbook），不另建文件池
|
||||
4. 人机验证：本机 **chrome-bridge** / 远程 **Paseo 浏览器** → `session` 回写；过期再验证
|
||||
|
||||
## 工作流
|
||||
|
||||
1. 用户共享条目到 AI 本（自动带默认 playbook：email 优先 + api_first）
|
||||
2. Agent：`login(id)`
|
||||
3. 用返回 cookie 访问站点；或 human_required 后等人回写再 `login`
|
||||
Reference in New Issue
Block a user