08 - 相关后端项目¶

插件依赖的可选后端服务已迁移到独立仓库 aiplugin4-backends。在启动器 WebUI 点「📋 复制后端配置」/「📋 复制 MCP 配置」，把生成的 JSON 粘贴到插件对应配置项即可，不再逐项手填；除流式输出外，其余服务并非核心功能所必需。复制出的后端配置会带上各后端已设置的访问 token（在卡片「⚙ 配置」里设），因此不要公开分享；给后端设/改 token 后要重启该后端并重新复制一次。

后端清单¶

目录	服务	默认端口	对应配置项
`stream-output`	流式输出中转(SSE 分块/增量轮询)	3010	后端配置 → `backends.stream-output`
`image-url-to-base64`	图片 URL 转 base64	46678	后端配置 → `backends.image-url-to-base64`
`image-host`	私人图床 + 图库：抓取入库（sha256 去重）/ 稳定链接与 b64 出口 / 标签 / 回收站 / WebUI / MCP	46680	后端配置 → `backends.image-host`（url/token；可选「图片清理天数」）
`media-fetch`	媒体接口中转：代插件请求音频/图片接口，把二进制响应转成 base64 JSON	46679	后端配置 → `backends.media-fetch`
`usage-chart`	token 用量图表	3009	后端配置 → `backends.usage-chart`
`md-html-render`	Markdown/HTML 渲染为图片	37632	MCP配置 → `mcpServers.md-html-render`
`mcp-browser`	AI 浏览器操作与截图（导航/点击/输入/快照/截图，常驻会话）	8921	MCP配置 → `mcpServers.mcp-browser`
`mcp-files-exec`	本地文件读写/执行	3910	MCP配置 → `mcpServers.mcp-files-exec`
`ob11-core-bridge`	SealDice 核心正向 WS / OB11 协议端 / 插件控制 WS 透明中转（注入消息执行核心指令；扩展指令由插件本地执行）	46880	后端配置 → `backends.ob11-core-bridge`（默认 `ws://127.0.0.1:46880/plugin`）

md-html-render、mcp-files-exec、mcp-browser、image-host 为 MCP（Streamable HTTP） 服务：插件需先在「MCP → 是否启用MCP」打开总开关，再通过「MCP → MCP服务器」中的标准 mcpServers 对象接入。启动器「📋 复制 MCP 配置」会生成 4 台（含 image-host 的 /mcp；image-host 需要访问 token，设置 token 后要重启 image-host 再重新复制；没有 token 时该条目会鉴权失败，可从 MCP 配置里删掉，不影响「后端配置」里的图床）。也可以继续用配置生成器示例（http://127.0.0.1:37632/mcp、http://127.0.0.1:3910/mcp、http://127.0.0.1:8921/mcp）。插件不再为这些后端包装或改名：后端直接提供 read_file、download_file、run_shell、render_markdown、render_html、browser_navigate/browser_click/browser_type/browser_snapshot/browser_take_screenshot/browser_wait_for/browser_close，图片与核心多消息处理仍由对应适配器保留；run_ext_command 完全由插件本地实现，不属于 MCP。ob11-core-bridge 自 4.17.0 起改为插件直连 /plugin WebSocket（配置在「后端配置」的 backends.ob11-core-bridge，不再经 MCP），run_core_command 由插件本地注册。这些后端的 REST 接口已移除。

4.27.0 起「后端」页签的 8 个独立地址项合并为「后端配置」JSON（v1）：旧键不再注册、不再读取，不迁移、不兼容；升级后请点启动器「复制后端配置」重新粘贴一次。空的「后端配置」= 全部使用出厂默认地址。

media-fetch 是「整响应即音频/图片」的语音与生图接口能用的前提：海豹的 JS 引擎（goja）读不了二进制响应——其 fetch 只实现了 text()/json()，没有 arrayBuffer()/bytes()/blob()，而 text() 会按 UTF-8 解码把原始字节替换成 U+FFFD 永久损坏。因此 OpenAI 兼容 /audio/speech、百度短文本合成、阿里 CosyVoice 这类直接吐音频流的接口，插件无法自己读取。该后端代插件发起同一个请求（method/headers/body 原样透传），用 Python 无损拿到字节后转 base64 放进 JSON 返回，插件读 JSON 即可。上游若本来就返回 JSON（含 url 字段，如百炼 wanx），则原样交回、按 data_path 取数，与直连行为一致。配置了 backends.media-fetch 时插件直接走后端、不再先直连一次（避免同一上游被打两次、TTS 双倍合成/计费）；上游 4xx 非 JSON 时后端会把原文放进 bodyText，供插件错误分类与展示（需 media-fetch ≥ 1.0.1）。不启动它时，这类接口会明确报错并提示去启动该后端；返回 JSON 的接口（MiniMax hex、Google Cloud audioContent、绝大多数生图）不受影响，无需该后端。

usage-chart 与 token：/chart 同时返回 image_url 与 base64（新后端）。图表图片由 QQ 协议端拉取、带不上 Authorization，所以设置 token 时插件优先用 base64 + seal.base64ToImage 落本地图发送；这需要 usage-chart ≥ 1.0.1（旧后端只有 image_url，token 模式下会裂图）。

所有后端都支持访问 token：在启动器卡片「⚙ 配置」里给任意后端设 token（AIPLUGIN4_BACKEND_TOKEN）后，「📋 复制后端配置」会把它写进 backends.<名>.token，插件请求统一带 Authorization: Bearer <token>（stream-output / image-url-to-base64 / media-fetch / usage-chart / image-host / ob11-core-bridge 均适用）。设/改 token 后要重启该后端再重新复制；token 不一致会 401，日志会提示核对哪个 backends.<名>.token。

image-host 解决「QQ 图片直链过期 / 模型取不到图」：在「后端配置」的 backends.image-host 填地址和 token 后，插件在建图时就把 http(s) 图片上传入库（不等会话触发），生图/表情包的 base64 结果也会立即转存。图床有两个地址：url 是插件访问图床接口的地址（可填 http://127.0.0.1:46680）；publicUrl 是给 QQ 协议端与模型用的对外地址（IP 或域名，如 http://192.168.1.10:46680、https://img.example.com）。启动器「复制后端配置」里的「图床对外地址」会自动生成 publicUrl（留空自动探测本机 IP），不需要复制完再手改 JSON；没有 publicUrl 且 url 是回环时自动降级为「发图取 /i/<id>/b64 落本地文件、模型用内联 base64」，并在启动探测时 WARN。不再依赖 image-url-to-base64，也不再在插件存储里保留 base64。同字节只存一份（sha256 内容寻址），每张图有独立 id 与来源记录，清理按引用计数（所有引用都交还后才可能回收字节）。另有「图片清理天数」（默认 30 天，0 关闭）：过期未使用的图片记录会被清理并通知图床释放引用；图床侧删除会被自动对账标记。WebUI 提供图库/回收站/标签三视图、批量操作与每张图的「详情」，MCP 提供搜索/重命名/打标签/收进图库/标签清单。

部署与一键管理¶

后端仓库自带 launcher.py(纯 Python 标准库,Windows / Linux 通用):

默认不启动任何后端;start <名称...> 或 start --all 启动,首次启动某后端时自动创建独立 venv 并安装依赖,进程异常退出自动拉起;
port <名称> [端口|reset] 修改端口(默认值不变,后端读环境变量 AIPLUGIN4_BACKEND_PORT);
webui 提供 Web 管理界面(默认 http://127.0.0.1:8910,支持启停/装依赖/改端口/看日志,主题跟随系统);
package 打包为 dist/aiplugin4-backends-<版本>.zip,由该仓库发版流程自动发布。

详细用法见 aiplugin4-backends 的 README。

说明¶

默认值:本地回环地址 + 端口(如 http://127.0.0.1:46678),与 aiplugin4-backends 各后端默认端口一致,适合本机自建。联网搜索默认使用内置 SearXNG（https://searxng.fishwhite.top），可在「联网」页换成自建实例或其它 provider。