feat: MCP 与 SealDice 指令桥接及 OB11 工具重构（4.16.0）

docs/02-架构设计.md

@@ -83,7 +83,7 @@
 
 ### 2. 指令消息(handleCommand)
 
-- 记录 `Tool.cmdArgs`(调用海豹内置指令的工具依赖它;为空时工具会提示先使用 `.r` 等指令)。
+- 指令消息默认不写入上下文；扩展指令工具的 `CmdArgs` 由 `src/tool/extension_executor.ts` 在每次调用现场按当前参数新建，不读取会话历史，也不要求先使用 `.r`。核心指令仍通过 `run_core_command` 的 OB11 核心桥执行。
 - 默认不写入上下文(`RECEIVE_CMD=false`);开启后在待机模式下把指令消息计入上下文。
 
 ### 3. 机器人自身消息(handleBotMessage)

docs/03-核心模块详解.md

@@ -14,7 +14,7 @@
 `MessagePipeline` 是唯一的事件处理入口:
 
 - `handleNonCommand(ctx, msg)`:执行忽略/触发判定,见 [02-架构设计](02-架构设计.md)。
-- `handleCommand(ctx, msg, cmdArgs)`:记录 `Tool.cmdArgs`;可选录入上下文。
+- `handleCommand(ctx, msg, cmdArgs)`:处理收到的指令消息;可选录入上下文。扩展指令工具所需 `CmdArgs` 不从这里缓存，而是在 `run_ext_command` 调用现场构造。
 - `handleBotMessage(ctx, msg)`:转发给工具监听;可选录入上下文。
 - 会话统一通过 `getSession(sid)` 获取;`sid` 私聊为用户 ID、群聊为群 ID。
 - CQ 码白名单 `CQ_TYPES_ALLOW = ["at","image","reply","face","poke"]`,含白名单之外 CQ 类型的消息不处理。
@@ -104,7 +104,7 @@
 - `context.ts`:`Context` 类:
   - 添加用户消息(自动改名、超长消息交给 `compress_agent` 压缩)、助手消息(触发记忆访问与总结检查)、系统用户消息、工具调用/回调消息。
   - `limitMessages()` 按 `MAX_ROUNDS`(出现一次 user 视作一轮)裁剪;`handleMessages` 另有 token 预算裁剪。
-  - `findUserId` / `findGroupId`:按 ID、名字(编辑距离容错)、上下文/记忆、群成员/好友列表解析用户与群。
+  - `getUserById` / `getGroupById`:仅按用户ID或群ID获取目标，不执行名称搜索。
   - `findImage`:支持 `user_avatar`、`group_avatar`、图片 ID、本地图片路径、记忆内图片。
   - `setName`/`updateName`:按 `autoNameMod`(0/1/2)自动把名字改为昵称或群名片。
 

docs/04-工具系统.md

@@ -9,21 +9,21 @@
 | 属性 | 说明 |
 | --- | --- |
 | `toolInfo` | OpenAI function calling 格式的描述(name/description/parameters JSON Schema) |
-| `ExtCmdInfo` | 海豹扩展指令信息(extName/cmd/staticArgs);非空时工具通过 `Tool.extensionSolve` 调用海豹内置指令 |
+| `solve` | 工具实际执行函数；扩展指令工具使用 `run_ext_command`，由 `src/tool/extension_executor.ts` 现场构造 `CmdArgs` 后调用扩展 `solve` |
 | `sessionType` | 适用会话类型:`'any'`(默认)、`'group'`、`'user'` |
 | `callBack` | 是否回调智能体(当前统一为 true) |
 | `sensitive` | 敏感工具标记(发消息/禁言/改名等),执行日志显著记录 |
 | `solve(ctx, msg, session, args)` | 工具实现,返回字符串作为给 AI 的结果 |
 
-`Tool.extensionSolve` 复用最近一次指令消息的 `cmdArgs`(`Tool.cmdArgs`),构造临时参数调用海豹扩展指令,并通过 `session.tool.listen` 监听该指令的发送消息作为返回值(10 秒超时)。因此**依赖海豹指令的工具需要先收到过指令消息**(如先使用 `.r`),否则返回提示。
+`run_ext_command` 在插件内**本地直接调用**扩展的 `solve`（构造独立的 `CmdArgs`，不依赖最近一次真实指令，也无需 MCP/中间件）；`run_core_command` 通过 `aiplugin4-backends/ob11-core-bridge`（MCP）注入标准 OB11 假消息执行核心指令。`run_ext_command` 的扩展名分为硬编码的 `builtin`（fun/story/coc7/deck/dnd5e/exp/log/reply）与 `non_builtin`；核心指令统一使用虚拟扩展名 `core`，例如 `core|ext`。指令前缀由「工具 → 指令前缀」配置，默认 `.`。两条路径都复用多消息收集器（空闲窗口 + 最大消息数 + 超时结束）。两种工具均支持 `trigger` 指定触发对象、`at` 指定 @ 对象；触发对象会替换本地临时 ctx/msg 或 OB11 假消息的 sender，@ 对象会写入消息段。
 
 ## 调用流程与校验链
 
 `Tool.handleToolCall` 按顺序校验:
 
 1. 函数是否已注册(`toolMap`)。
 2. 会话工具开关 `session.toolState[name]` 是否开启。
-3. 扩展指令工具是否有可用的 `cmdArgs`。
+3. 工具参数是否完整、扩展指令是否在白名单中（`core|ext` 为例外发现入口）。
 4. `sessionType` 是否匹配当前消息类型。
 5. 参数 JSON 是否可解析(失败时用 `fixJsonString` 修复)。
 6. 必需参数是否齐全;`Tool.validateArgs` 按 JSON Schema 的 type 做轻量校验。
@@ -49,6 +49,17 @@
 
 实现位置:`src/context/context.ts` 的 `addToolCallbackMessage`,调用侧由 `Tool.handleToolCall` 在结果上补充 `toolName`/`searchTarget` 字段。
 
+## OB11 核心指令中转
+
+中间件位于 `aiplugin4-backends/backends/ob11-core-bridge`，**仅用于核心指令**（插件无法在 JS 侧直接调用 `.ext`/`.help` 等核心指令）。SealDice 的 OB11 网络依赖作为 WebSocket 客户端主动连接中间件 `/core`（或 `/core/ws`）；中间件再出站主动连接协议端（NapCat/LLOneBot 或测试模拟器）的 WS 地址（启动即连、带指数退避重连）；插件通过 MCP（`/mcp`）调用 `run_core_command` 注入假消息，不直接连接中转 WS。扩展指令由 `run_ext_command` 在插件内本地直调扩展 `solve`，不经过中间件。
+
+- 中间件原样转发协议端与核心之间的 OB11 JSON；核心的 `send_private_msg`/`send_group_msg` 等 action（由 `call_ob11_api` 统一调用），以及 lane 模式下的 bot 消息事件，都可按当前调用的会话 lane 捕获。
+- 默认 `forward=true`：捕获后的 Action/消息事件默认继续发送到协议端；显式 `forward=false` 时拦截，但仍向核心返回成功 API 响应，避免核心阻塞。`run_core_command` 可通过 `captureMode`、`maxMessages`、`settleMs`、`timeoutMs` 调整监听策略。
+- 同一群/私聊 lane 串行化，单次调用使用 `settleMs` 空闲窗口收集多条消息；结果含 `ambiguous`、`completedBy`，因为纯 OB11 没有标准 trace_id，无法保证跨同 lane 的绝对关联。
+- `run_core_command` 的 `command=ext` 直接调用核心 `.ext`，用于查看所有扩展名称，不需要在配置中维护扩展列表。`run_ext_command` 的 `action=list` 仅能列出白名单 + 内置扩展 + 插件自身指令，完整扩展列表以 `run_core_command` 执行 `ext` 为准。
+
+中间件配置：`AIPLUGIN4_BACKEND_HOST`（默认 `0.0.0.0`）、`AIPLUGIN4_BACKEND_PORT`（默认 `46880`）、`AIPLUGIN4_BRIDGE_TOKEN`（MCP 鉴权 token）、`AIPLUGIN4_BRIDGE_CORE_TOKEN`（核心端鉴权）、`AIPLUGIN4_BRIDGE_PROTOCOL_URL` / `AIPLUGIN4_BRIDGE_PROTOCOL_TOKEN`（协议端地址与 token，中间件出站主动连接；也可在 WebUI「⚙ 配置」填写，重启生效），以及可选的 `AIPLUGIN4_BRIDGE_CORE_PATH`（默认 `/core`，同时接受 `/core/ws`）、`AIPLUGIN4_BRIDGE_MCP_PATH`（默认 `/mcp`）。插件在「工具 → MCP服务器配置」中接入 `ob11-core-bridge`（`http://127.0.0.1:46880/mcp`）；SealDice 侧的 OB11 正向 WS 配置填 `/core` 地址。
+
 ## 内置工具清单
 
 以下工具名来自 `src/tool/tools/` 各注册函数(基于当前代码):
@@ -57,31 +68,33 @@
 | --- | --- |
 | 记忆 | `add_memory`、`del_memory`、`search_memory`、`clear_memory` |
 | 知识库 | `kb_search`、`kb_read`、`kb_list`(只读检索,内容由「知识库」配置维护) |
-| 消息 | `send_msg`、`get_msg`、`delete_msg`、`send_forward_msg`、`get_context` |
+| OB11 API | `call_ob11_api`（通过 action 调用消息、查询、管理、文件和合并转发 API） |
 | 定时 | `set_timer`、`show_timer_list`、`cancel_timer` |
 | 触发 | `set_trigger_condition` |
-| 语音 | `record`、`text_to_sound` |
+| 音频资源 | `generate_audio`（生成 record 消息段，不直接发送） |
 | 网页 | `web_search`、`web_read` |
-| TRPG | `roll_check`、`san_check`、`jrrp`、`modu_roll`、`modu_search`、`draw_deck` |
+| 指令 | `run_ext_command`、`run_core_command`（调用 SealDice 扩展与核心指令） |
 | 属性 | `attr_show`、`attr_get`、`attr_set` |
 | 图片 | `image_to_text`、`text_to_image`、`meme_list`、`get_meme_info`、`meme_generator`、`render_markdown`、`render_html` |
-| QQ 管理 | `ban`、`whole_ban`、`get_ban_list`、`rename`、`group_sign` |
-| 群资料 | `get_list`、`get_group_member_list`、`search_chat`、`search_common_group`、`get_person_info` |
-| 精华消息 | `set_essence_msg`、`get_essence_msg_list`、`delete_essence_msg` |
-| 音乐 | `music_play` |
+| OB11 管理/查询 | 统一通过 `call_ob11_api` 传入对应 action |
+| 资源/群资料 | `list_resources`；群资料统一通过 `call_ob11_api` 传入对应 action |
+| 精华消息 | 统一通过 `call_ob11_api` 传入对应 action |
+| 音乐资源 | `search_music`（返回 music 消息段，不直接发送） |
 | 黑名单 | `suggest_block`(AI 建议拉黑,带冷却;默认需骰主用 `.ai block` 确认,可在工具配置关闭)、`unblock_user`、`get_block_list` |
 | 论坛 | `forum_get_posts`、`forum_get_post_detail`、`forum_search`、`forum_create_post`、`forum_manage_comment`、`forum_get_activity`、`forum_manage_post` |
 
-> 注：`draw_deck` 支持 `send` 参数——`true` 时直接把抽牌结果发送给用户；`false` 或省略（默认）时仅把结果返回给 AI，由 AI 转述，便于结合剧情再加工。
 
 > 注：`text_to_image` 支持可选 `image` 参数进行以图生图。参数可传图片 ID、`user_avatar:...`、`group_avatar:...`、图片 URL、data URL 或 base64；tti 模型配置需要在请求体中使用 `{image}`、`{image_url}` 或 `{image_base64}` 占位符。
 
+> 注：资源发送统一通过 `call_ob11_api` 的 image/record/video/file 消息段；文件区上传使用 `upload_group_file`/`upload_private_file`。本地绝对路径、`file://` URI、MCP `mcp://` 引用会在运行时解析，资源 ID 使用 `resource:资源名`。
+> 注：MCP 文件服务器 `mcp-files-exec` 支持把沙箱文件先导出为短时下载地址再发送。可使用 `mcp://mcp-files-exec/output/example.pdf`，或显式传 `source=mcp`、`server=mcp-files-exec`、`path=output/example.pdf`；相对 MCP 路径相对第一个沙箱根目录。
+
 外部注册:
 
-- MCP 工具:`<服务器名>_<工具名>`(见下节)。
+- MCP 工具:默认直接按远端 `tools/list` 返回的工具名注册;与本地/已有工具同名时自动跳过。
 - 技能工具:`use_skill`(见技能节)。
 
-依赖说明:ob11 相关工具(收发消息、用户/群信息、禁言、打卡等)需要安装 ob11 网络连接依赖或 HTTP 依赖;`text_to_sound` 预设音色需要支持 AI 语音的协议端,自定义音色需要生成音频依赖(tts)与 ffmpeg;`music_play` 需要协议端配置音卡签名;`text_to_image` 需要生成图片依赖(tti)。
+依赖说明：AI 只调用 `call_ob11_api`。有 ob11 网络连接依赖时 action 原样透传；没有依赖时原生可完成的发送和上下文查询继续可用，其余 action 返回 `OB11_DEPENDENCY_REQUIRED`。
 
 ## 工具权限(按会话开关)
 
@@ -94,10 +107,10 @@
 ## MCP 集成(src/tool/mcp.ts)
 
 - 配置项 `是否启用MCP`(工具分组,默认关闭)是 MCP 总开关;开启后才会解析 `MCP服务器配置` 并连接/注册 MCP 工具。
-- 配置项 `MCP服务器配置`(工具分组)只支持 JSON 格式的标准 `mcpServers` 块(Claude Desktop / Cursor `.mcp.json`):`{"mcpServers":{"名称":{"type":"http","url":"...","headers":{...}}}}`,支持任意自定义 headers 与 `token` 简写;`command`(stdio)与 `sse` 传输会明确提示后跳过。默认配置包含三个服务器:`mcp-files-exec`(文件执行)、`web-read`(网页读取)、`md-html-render`(Markdown/HTML 渲染),其中后两者是内置后端服务,由 `web_read` / `render_markdown` / `render_html` 包装工具调用,不会重复注册为 AI 工具;改 URL/Token 时服务器会话自动重建(热加载)
+- 配置项 `MCP服务器配置`(工具分组)只支持 JSON 格式的标准 `mcpServers` 块(Claude Desktop / Cursor `.mcp.json`):`{"mcpServers":{"名称":{"type":"http","url":"...","headers":{...}}}}`,支持任意自定义 headers 与 `token` 简写;`command`(stdio)与 `sse` 传输会明确提示后跳过。默认配置包含四个服务器:`mcp-files-exec`（文件读写、URL 下载、命令执行）、`web-read`(网页读取)、`md-html-render`(Markdown/HTML 渲染)、`ob11-core-bridge`(SealDice 核心指令中转)。工具名称、描述和参数 schema 均从远端 `tools/list` 自动发现,返回内容按 MCP 标准内容块处理;`run_ext_command` 由插件本地注册,不经 MCP。改 URL/Token 时服务器会话自动重建(热加载)
 - 协议:Streamable HTTP 上的 JSON-RPC(`initialize` → `notifications/initialized` → `tools/list` → `tools/call`),带 `Mcp-Session-Id` 会话头,兼容 SSE 响应。
-- 工具以 `<服务器名>_<工具名>` 注册为敏感工具,参数透传 `inputSchema`。
-- 工具列表有 60 秒 TTL 缓存;会话失效(`会话不存在/已失效/session`)时重新 initialize 并重试一次。
+- 远端工具默认用远端工具名注册为敏感工具,参数透传 `inputSchema`;返回纯文本时直接回传,返回标准 image 块或 base64 文本时保存为 `[img:...]` 并返回图片 ID。同名冲突会跳过。
+- 工具列表有 60 秒 TTL 缓存;会话失效/服务器未初始化（会话不存在/已失效/未初始化/Server not initialized）时自动重新 initialize 并重试一次。
 - MCP 配置修改后会按服务器名重建会话并同步工具差集;删除服务器或服务器返回的工具会从注册表移除。MCP 总开关关闭时不建立连接,system prompt 也不会展示不可调用的 MCP/技能入口。
 - 错误信息把 JSON-RPC 错误码映射为可读中文。
 
@@ -106,3 +119,4 @@
 - 配置项 `技能配置`(工具分组)只支持标准 SKILL.md 格式:直接粘贴 Claude/Codex/Cursor 的技能文件,frontmatter 的 `name`/`description` 自动解析为技能名与摘要,正文为技能内容
 - 注册 `use_skill` 工具;`getSkillSummaries()` 生成的技能摘要会追加到 system prompt 的"可用技能"段(两种工具模式都可见)。
 - 技能内容支持 `{{skill:名称}}` 引用其他技能(最大解析深度 2),单次返回上限 4000 字符(超出截断并注明)。
+- 默认技能包含当前 SealDice 核心命令、内置扩展命令及全部别名的调用帮助：扩展指令使用 `run_ext_command`，核心命令（含 `core|team`）使用 `run_core_command`；默认白名单与 SealDice 源码中的命令表同步。

docs/05-命令与配置.md

@@ -24,8 +24,8 @@
 | `memory` | 记忆管理 | 见下文 |
 | `kb` | 知识库查询(只读) | `.ai kb list`;`.ai kb search <关键词>`;`.ai kb read <ID>` |
 | `tool` | 工具管理 | 见下文 |
-| `ignore` | 群内忽略名单 | `.ai ign add @xxx`;`.ai ign rm @xxx`;`.ai ign lst`(仅群聊) |
-| `block` | 黑名单管理(骰主) | `.ai block add <统一ID/@xxx> <原因>`;`.ai block rm <统一ID/@xxx>`;`.ai block list`;被拉黑对象无法触发 AI 对话,指令不受影响;AI 建议拉黑默认需骰主确认,可在工具配置关闭 |
+| `ignore` | 群内忽略名单 | `.ai ign add <用户ID>`;`.ai ign rm <用户ID>`;`.ai ign lst`(仅群聊) |
+| `block` | 黑名单管理(骰主) | `.ai block add <用户ID/群ID> <原因>`;`.ai block rm <用户ID/群ID>`;`.ai block list`;被拉黑对象无法触发 AI 对话,指令不受影响;AI 建议拉黑默认需骰主确认,可在工具配置关闭 |
 | `token` | token 用量统计 | 见下文 |
 | `shut` | 打断当前流式对话 | `.ai shut` |
 | `model` | 查看/设置会话模型 | `.ai model`;`.ai model <模型名>`;`.ai model clr` |
@@ -34,7 +34,7 @@
 ### memory 子命令
 
 ```text
-.ai memo status (@xxx)              # 记忆状态,@ 查看个人记忆状态
+.ai memo status [用户ID]              # 记忆状态,传用户ID查看对应个人记忆状态
 .ai memo [p/g] st <内容>             # 设置个人/群聊设定(个人≤20字,群聊≤30字)
 .ai memo [p/g] st clr               # 清除设定
 .ai memo [p/g] del <ID1> <ID2> --关键词1 --关键词2   # 删除记忆
@@ -105,7 +105,7 @@
 | 对话 | 角色扮演设定、示例对话、对话保存轮数、上下文最大token、消息压缩阈值 | 每条设定第一行为角色设定名称(>20 截断),其余为设定;`$gSYSPROMPT` 选择 |
 | 消息接收 | 接收图片/指令消息/骰子发送的消息、忽略消息豹语条件、忽略消息正则表达式 | 接收图片只负责记录图片 URL；自动识别仍由图片识别条件和图片模型配置决定 |
 | 消息触发 | 触发正则表达式、触发需要满足的条件、触发次数上限、触发次数补充间隔 | 令牌桶配额 |
-| 工具 | 开启调用函数功能、切换为提示词工程、允许连续调用函数次数、工具响应压缩触发字数、禁止/默认关闭的函数、是否启用MCP、MCP服务器配置、技能配置、ai语音使用的音色 | 「是否启用MCP」默认关闭,开启后才会解析并连接 MCP 服务器;MCP 仅支持标准 mcpServers JSON(默认含 mcp-files-exec/web-read/md-html-render,格式见 modelcontextprotocol.io/specification/latest),技能仅支持标准 SKILL.md(格式见 agentskills.io/specification) |
+| 工具 | 开启调用函数功能、切换为提示词工程、允许连续调用函数次数、工具响应压缩触发字数、禁止/默认关闭的函数、是否启用MCP、MCP服务器配置、技能配置、ai语音使用的音色 | 「是否启用MCP」默认关闭,开启后才会解析并连接 MCP 服务器;MCP 仅支持标准 mcpServers JSON(默认后端直接提供 mcp-files-exec（read_file、download_file、run_shell）、web-read（web_read）、md-html-render/render_markdown/render_html、ob11-core-bridge/run_core_command,run_ext_command 仅由插件本地实现,格式见 modelcontextprotocol.io/specification/latest),技能仅支持标准 SKILL.md(格式见 agentskills.io/specification) |
 | 记忆 | 启用长期/总结/知识库记忆、长期记忆上限/展示数量、总结记忆上限/间隔/参与轮数、短期记忆上限、知识库注入阈值(字符)、知识库(Markdown 模板,每条一份完整文档) | 知识库只读,AI 通过 kb 工具/指令检索;修改后自动生效(缓存最多 1 分钟);Markdown 语法见 commonmark.org/help/ |
 | 回复 | 回复引用、回复最大字数、分段发送延时/基础延时/含图额外延时、禁止回复复读 | 回复过滤规则已内置硬编码 |
 | 后端 | 流式输出、图片转base64、联网搜索、用量图表、论坛地址/API Token/签名密钥 | 可自建,见 [08-相关后端项目](08-相关后端项目.md);网页读取与 md/html 渲染(MCP)在「工具 → MCP服务器配置」 |

docs/07-开发指南.md

@@ -35,7 +35,7 @@ npm run lint        # ESLint 检查 src/**/*.ts
 
 1. 在 `src/tool/tools/` 下新建文件(或放入已有分类目录),导出一个 `registerXxx()` 函数。
 2. 创建 `new Tool({ type:'function', function:{ name, description, parameters } })`,实现 `solve(ctx, msg, session, args)`,返回字符串给 AI。
-3. 可选配置:`sessionType`(group/user)、`sensitive`(敏感标记)、`ExtCmdInfo`(调用海豹内置指令)。
+3. 可选配置:`sessionType`(group/user)、`sensitive`(敏感标记)。如需调用海豹扩展指令，使用 `run_ext_command`；它会在每次调用时现场构造 `CmdArgs`，不依赖历史指令或 `.r`。
 4. 在 `src/tool/tool.ts` 的 `Tool.registerTool()` 中导入并调用注册函数。
 
 示例: