mnote/design/old/07-ai/process/7-47-mnote-public-capability-plugin-registry-v1.md

[recycle] 7-47 MNote 公共 capability/plugin 注册表设计 v1

2026-06-28 覆盖说明：本文的 Hermes / Reasonix / LightRAG 能力注册口径已退为 legacy 参考。当前能力模型应围绕 OpenHub / opencode / WeKnora，旧 mnote-knowledge-rag 与 mnote_lightrag_bridge 仅保留兼容映射和迁移对照。

状态：process

目标：把当前分裂的 MNote builtin skill、mnote tool manifest、Hermes plugin、Reasonix wrapper 和 Page AI UI 开关收口为同一个“AI 能力”模型。对用户来说 skill / plugin / tool 都是“授予 AI 的能力”，UI 不应暴露实现层分类；实现层再把一个能力映射到说明书、工具、runtime adapter 和权限策略。本轮只整理 MNote 公共能力；Reasonix / Hermes 自带的 skills/plugins 维持现状，不纳入统一注册表迁移范围。

2026-06-07 口径更新：7-50 后资料库问答主线已切到 LightRAG，第一批能力包试点从旧 mnote-local-index 改为 mnote-knowledge-rag。mnote-document-evidence / mnote-local-index 只作为兼容 alias 映射到 mnote-knowledge-rag，不再恢复 mnote.evidence.* / mnote.index.* 作为 active tool。

当前实施状态

• Phase A 已落地：rust/crates/mnote-web/src/hermes_tools/skill.rs 已有 MnoteCapabilityPack / CAPABILITY_PACKS，manifest.rs 已输出 capabilities[] 并给 tools 标注 capabilityId / capabilityIds。
• Phase B 已落地：/api/hermes/client/capabilities 已存在，Page AI runtime=mnote 技能目录优先请求 capabilities，能力 payload 内含 tools、readOnly、contextRefs、enabled/status。
• Phase C 已落地：/api/hermes/client/capabilities/toggle 会同步 capability skill preference 和 profile tool disabled policy；直接调用被关闭 tool 会走 mnote_tool_disabled 硬拒绝。
• Phase D 已完成 Reasonix 侧最小收口：scripts/reasonix-acp-wrapper.mjs 启动时优先读取 /api/hermes/tools/mnote/manifest 动态注册 MNote tool specs，mnote-web 不可用时才回落到静态 fallback；Hermes Python plugin 生成仍作为后续独立收口。

0. 用户口径

用户不需要理解 skill、plugin、tool 的区别。Page AI 设置中统一展示为“AI 能力”：

• 当前页读取
• 资料库问答
• 本地文件编辑
• 思维导图
• ONLYOFFICE 实时编辑
• 纯聊天

每个能力只有一个主开关。展开后可以显示该能力包含的工具、上下文要求和读写权限，但这些是高级详情，不是主概念。

实现层映射：

• skill：能力说明书，告诉 agent 什么时候用、怎么用。
• tool：能力的可执行函数，真正落到 Rust runtime / kernel。
• plugin / adapter：把同一套工具暴露给 Hermes ACP、Reasonix ACP 或其它 agent runtime。
• policy：决定该能力是否可见、是否启用、是否允许写入。

后续 UI 文案统一使用“能力”，不再把 MNote builtin skill、Hermes skill、Reasonix skill、mnote tool 作为并列用户入口。

1. 当前盘点

1.1 MNote builtin skills

当前入口：rust/crates/mnote-web/src/hermes_tools/skill.rs

现有内置 skill：

• mnote-current-page
• mnote-knowledge-rag
• mnote-local-file
• mnote-onlyoffice-live
• mnote-mindmap
• mnote-chat-only

特点：

• skill 是 Rust 静态注册，正文来自 skills/*/SKILL.md。
• /api/hermes/client/skills?runtime=mnote&agentId=... 通过 mnote_builtin_skills_payload() 输出到 UI。
• 每个 skill 现在已经带 toolNames 和 requiresContextRefs，但这些只是弱引用，不是一个正式 capability/plugin 合同。
• mnote.skill.read 能懒加载正文；旧 mnote-document-evidence / mnote-local-index 只作为兼容别名映射到 mnote-knowledge-rag，不恢复旧 evidence / index 工具。

1.2 MNote tools

当前入口：rust/crates/mnote-web/src/hermes_tools/manifest.rs

现有工具大类：

• skill/context：mnote.skill.read、mnote.context.*
• knowledge-rag：mnote.knowledge_rag.status、mnote.knowledge_rag.query、mnote.knowledge_rag.open_reference
• retired evidence/index：mnote.evidence.*、mnote.index.* 只保留历史对照，不作为 active manifest / capability 示例
• doc/block/page/artifact：mnote.doc.*、mnote.block.*、mnote.page.*、mnote.artifact.*
• mindmap：mnote.mindmap.*
• office/onlyoffice：mnote.office.*、mnote.onlyoffice.*

执行入口：

• 当前中性入口：/api/mnote/tools/manifest
• 当前中性入口：/api/mnote/tools/call
• legacy alias：/api/hermes/tools/mnote/manifest
• legacy alias：/api/hermes/tools/mnote/call
• execute_mnote_tool_call() 统一做认证、profile 禁用检查、workspace 校验、capabilityScope 校验、写入 guard、audit、idempotency。

问题：

• manifest 只有 plugin 总描述和扁平 tools，没有“哪个 tool 属于哪个公共能力包”的结构。
• /api/hermes/client/tools?scope=mnote&profile=... 只展示扁平工具列表。
• tool 开关写入 Hermes profile 的 mnote.tools.disabled，skill 开关写入 MNote SQLite user preference，两个开关域不同步。

1.3 Hermes plugin

当前本机存在 /home/lix/.hermes/plugins/mnote/，包括：

• plugin.yaml
• __init__.py

现状：

• 这是 Hermes 用户插件，不在 mnote repo 内。
• plugin.yaml 只列出旧批次工具：mnote_page_get/save/update_title/update_options、mnote_doc_*、mnote_block_*、artifact 等。
• 没有 mnote_evidence_*、mnote_index_*、mindmap、onlyoffice live 等新工具。
• __init__.py 手写 Python wrapper，把 Hermes tool call 转发到 legacy /api/hermes/tools/mnote/call；OpenHub/WeKnora 主线应使用 /api/mnote/tools/call。

问题：

• Hermes 用户插件和 Rust manifest 已经漂移。
• 新增 Rust tool 后不会自动进入 Hermes plugin。
• 如果继续维护该插件，必须由 Rust manifest 生成 plugin.yaml / Python adapter，不能手写。

1.4 Reasonix wrapper

当前入口：scripts/reasonix-acp-wrapper.mjs

现状：

• 手写 Reasonix ACP 可见工具名，例如 mnote_evidence_search、mnote_index_status。
• 手写 REASONIX_TOOL_TO_MNOTE_TOOL 映射到 Rust mnote.* 工具。
• 手写每个工具的 parameters。

问题：

• 与 Rust manifest 重复。
• 与 Hermes plugin 重复。
• 新增/改名工具必须同步改 wrapper，否则 agent 看得到 skill 也无法调用工具。

1.5 Page AI UI

当前入口：

• skills panel：rust/crates/mnote-web/browser/sidebar-page-ai-skill-runtime.js
• runtime/tools panel：rust/crates/mnote-web/browser/sidebar-page-ai-render-runtime.js
• data load/toggle：rust/crates/mnote-web/browser/sidebar-page-ai-runtime.js

现状：

• Skills 页能展示 MNote builtin skills、Reasonix skills、Hermes profile skills。
• Runtime/高级页展示扁平 mnote tools 列表。
• MNote skill 开关调用 /api/hermes/client/skills/toggle，写 SQLite user preference。
• Tool 开关调用 /api/hermes/client/tools/toggle，写 profile YAML mnote.tools.disabled。

问题：

• 用户想管理的是“索引能力包”，不是单独 skill 或一堆扁平工具。
• 现在 UI 上 skill 和 tool 分两个地方，不能表达“启用索引 skill，同时启用对应工具”。
• 无法像公共 skill 一样展示 plugin/capability 包的工具内容、权限、启停状态。

2. 设计判断

当前应该引入 MnoteAiCapability / MnoteCapabilityPack，而不是继续把 skill、tool、plugin 分开维护。代码中可叫 capability pack；UI 中只叫“AI 能力”。

定义：

pub struct MnoteCapabilityPack {
    pub id: &'static str,
    pub title: &'static str,
    pub description: &'static str,
    pub agent_ids: &'static [&'static str],
    pub read_only: bool,
    pub requires_context_refs: &'static [&'static str],
    pub skill_id: &'static str,
    pub skill_content: &'static str,
    pub tool_names: &'static [&'static str],
    pub ui_kind: &'static str,      // capability | chat | compat
    pub category: &'static str,     // mnote, office, resource, chat
    pub public: bool,
}

原则：

• 一个公共能力包可以包含一个 skill 和多个 tools。
• UI 主要展示 capability pack，不再让用户先理解 skill/tool/plugin 三套概念。
• agent prompt 仍注入短 skill/capability 摘要，正文仍走 mnote.skill.read 懒加载。
• tool manifest 仍是执行真相，但每个 tool 必须能反查所属 capability pack。
• Reasonix wrapper / Hermes plugin 都从同一份 capability/tool manifest 生成或动态注册。

3. 目标 API

3.1 新增 capability 列表

GET /api/hermes/client/capabilities?runtime=mnote&agentId=reasonix&profile=...

返回：

{
  "ok": true,
  "runtime": "mnote",
  "categories": [
    {
      "name": "mnote",
      "title": "MNote",
      "capabilities": [
        {
          "id": "mnote-knowledge-rag",
          "title": "资料库问答",
          "description": "Ask the LightRAG-backed knowledge library and open returned MNote source references.",
          "enabled": true,
          "toggleable": true,
          "readOnly": false,
          "skillId": "mnote-knowledge-rag",
          "toolNames": [
            "mnote.knowledge_rag.status",
            "mnote.knowledge_rag.query",
            "mnote.knowledge_rag.open_reference"
          ],
          "tools": [
            {
              "name": "mnote.knowledge_rag.query",
              "kind": "read",
              "status": "available",
              "enabled": true,
              "requiresWritePermission": true
            }
          ],
          "requiresContextRefs": ["folder"],
          "configScope": "user_sqlite+profile_tool_policy"
        }
      ]
    }
  ]
}

3.2 新增 capability toggle

PUT /api/hermes/client/capabilities/toggle

入参：

{
  "runtime": "mnote",
  "profile": "reasonix",
  "id": "mnote-knowledge-rag",
  "enabled": true
}

行为：

• 写入 MNote SQLite user preference：ai.agent.mnote_builtin.skill.{id}.enabled
• 对包内 tools 批量更新 profile mnote.tools.disabled
• 保留单 tool 开关作为高级功能，但 UI 默认展示包开关。

3.3 manifest 扩展

/api/hermes/tools/mnote/manifest 增加：

{
  "capabilities": [
    {
      "id": "mnote-knowledge-rag",
      "skillId": "mnote-knowledge-rag",
      "toolNames": ["mnote.knowledge_rag.status", "mnote.knowledge_rag.query", "mnote.knowledge_rag.open_reference"]
    }
  ],
  "tools": [
    {
      "name": "mnote.knowledge_rag.query",
      "capabilityId": "mnote-knowledge-rag",
      "capabilityScope": ["knowledge_rag.read", "evidence.read"]
    }
  ]
}

4. UI 设计

4.1 Skills 页改为 AI 能力页

在 Page AI 的 Skills 页中，用户看到的是统一“AI 能力”列表，不再分 skill / plugin / tool：

• 行标题：资料库问答
• 副标题：知识库 / LightRAG · 3 tools · 需要 folder
• 状态 chip：只读 / 可写 / 部分工具关闭 / 只读上下文不可写
• 主开关：启用/关闭整个能力包
• 展开项：列出 tools，显示 read/write、enabled、status

不新增单独 landing/settings 页；沿用当前 Skills 页即可，避免再散一处入口。

页面标题建议从 Skills 改为 能力；内部 source filter 可以保留 MNote / Hermes / Reasonix，但展示为能力来源，不作为用户要理解的能力类型。

4.2 Runtime 高级页保留扁平工具

Runtime 页继续保留 mnote tools，但作为高级调试面：

• 默认按 capability 分组，而不是纯扁平列表。
• 单 tool 开关仍保留，用于排查或临时禁用某个写工具。
• 若 capability 关闭，包内工具显示 disabled_by_capability。

4.3 索引面板与能力包关系

Sidebar 的“资料库 / 知识库设置”仍是用户直接管理 LightRAG source、索引范围和服务状态的产品 UI；Page AI 的 mnote-knowledge-rag capability 是 agent 能力开关。

两者职责不同：

• 知识库设置面板：用户手动新增/删除/刷新 source，查看 LightRAG 服务和 source registry 状态。
• MNote knowledge-rag capability：允许 agent 使用工具查询资料库、查看状态和打开返回来源；sourcePaths 当前只过滤返回 references，不声称 provider 层预过滤 raw chunks。

5. Runtime 适配

5.1 Reasonix

短期：

• 保留 scripts/reasonix-acp-wrapper.mjs。
• 但 wrapper 启动时请求 /api/hermes/tools/mnote/manifest，按 manifest 自动注册工具。
• 保留手写 fallback，避免 mnote-web 未启动时 wrapper 不能初始化。

中期：

• 删除 REASONIX_TOOL_TO_MNOTE_TOOL 手写表。
• 工具名转换统一由函数生成：
  • mnote.knowledge_rag.status -> mnote_knowledge_rag_status
  • mnote.knowledge_rag.open_reference -> mnote_knowledge_rag_open_reference

5.2 Hermes ACP

短期：

• MNote 继续通过 AcpMnoteToolContext 把 availableSkills 和 capability policy 交给 Hermes ACP。
• 如果 Hermes ACP 原生不能消费 Rust manifest 注册工具，则仍依赖 /home/lix/.hermes/plugins/mnote。

中期：

• 用 Rust manifest 生成 /home/lix/.hermes/plugins/mnote/plugin.yaml 和 Python adapter。
• 生成内容覆盖当前手写旧插件，确保 Hermes plugin tools 与 Rust manifest 一致。

长期：

• Hermes ACP 若支持从 host 动态接收 tools，则不再需要本机 Python plugin，只保留 Rust manifest。

6. 迁移方案

Phase A：只加 registry，不改 UI 行为

• 新增 hermes_tools/capability.rs。
• 将当前 SKILLS 迁到 CAPABILITY_PACKS，skill_summaries_for_agent() 从 pack 派生。
• manifest() 给每个 tool 增加 capabilityId，并输出 capabilities。
• 保持 /client/skills、/client/tools 响应兼容。

验收：

• mnote-knowledge-rag 在 /client/skills?runtime=mnote 与 /client/capabilities?runtime=mnote 可见，mnote-local-index 不再作为 active capability 暴露。
• /api/hermes/tools/mnote/manifest 可看到 capabilities[]。
• 旧 mnote.skill.read 不破。

Phase B：UI 展示 capability pack

• 新增 /api/hermes/client/capabilities。
• Skills 页对 runtime=mnote 优先消费 capabilities。
• 能力包行展示 tools 数、read/write、contextRefs。
• Runtime 页 tools 按 capability 分组。

验收：

• Page AI Skills / 能力页中 资料库问答 像公共 skill 一样可见。
• 展开能看到 mnote.knowledge_rag.*，看不到 mnote.evidence.* / mnote.index.* active tools。
• 开关 capability 后，下一次 run 的 skillPreferences.mnote 同步变化。

Phase C：能力包开关驱动工具开关

• 新增 /api/hermes/client/capabilities/toggle。
• 开关包时同步 skill preference 和 profile tool disabled 列表。
• page_ai_capability_policy() 过滤 disabled capability，且 execute_mnote_tool_call() 对 disabled tool 继续硬拒绝。

验收：

• 关闭 mnote-knowledge-rag 后 agent 不再看到该 skill 摘要。
• 关闭后直接调用 mnote.knowledge_rag.query 返回 mnote_tool_disabled 或 capability disabled。
• 再打开后恢复。

Phase D：生成 Reasonix/Hermes adapters

• Reasonix wrapper 从 manifest 自动注册工具。
• Hermes plugin 从 manifest 生成或在启动时同步。
• 删除手写工具表漂移。

验收：

• 新增 Rust tool 后，只改 Rust manifest/capability pack，Reasonix/Hermes UI 与 runtime 均自动出现。
• node scripts/reasonix-acp-wrapper.mjs selftest 覆盖 manifest 动态注册。
• hermes plugins list / Hermes tool list 显示与 Rust manifest 一致。

7. 对 mnote-knowledge-rag 的落地形态

mnote-knowledge-rag 是第一批公共能力包试点：

• skill：skills/mnote-knowledge-rag/SKILL.md
• tools：
  • mnote.knowledge_rag.status
  • mnote.knowledge_rag.query
  • mnote.knowledge_rag.open_reference
• requiresContextRefs：folder
• readOnly：true
• write guard：本能力包不写用户 source；source 管理 UI / API 另归知识库设置面，不通过 agent capability 暴露写入。
• UI 文案：知识库 / LightRAG · 可回跳来源

8. 非目标

• 不把索引设置面板挪进 Page AI。
• 不让 agent 直接读写 .mnote/index 文件。
• 不让 Hermes plugin 直接写 Convex 或绕过 Rust runtime。
• 不在前端手写工具 schema。
• 不把 Reasonix wrapper 作为长期 tool registry 真相。

9. 风险

• Hermes Python plugin 当前在 /home/lix/.hermes/plugins/mnote，不在 repo，自动生成前仍会漂移。
• tool 开关现在是 profile 级，skill 开关是用户级；能力包 toggle 需要明确优先级。
• mnote-local-file 是 agent 原生文件能力指导，当前没有对应 MNote 写工具，放入 capability pack 时需要标记为 native_agent_tools，避免误以为 MNote 提供文件 patch tool。
• mnote-chat-only 不是业务能力包，应保留为 agent mode skill，不参与 tools。

10. 建议执行顺序

1. 先做 Phase A：Rust MnoteCapabilityPack registry，完全兼容现有接口。
2. 再做 Phase B：UI 展示 capability pack，保留旧 skills/tools fallback。
3. 再做 Phase C：能力包 toggle 批量控制 skill + tools。
4. 最后做 Phase D：Reasonix/Hermes adapter 从 manifest 自动生成。