附录 C　连接器配置与排错

这一篇解决一件事：为什么我的入口后面没接上引擎。

先说结论：七成的问题是同一个原因——新引擎装了，但没登记“信任”，于是被安全机制静默跳过。

它不报错、不提示，就是不用。这一篇教你怎么查出来。

C.1 三个概念先分清

词	是什么	在哪儿
入口	你看到的界面：对话框、专家卡、画布	桌面应用图标
连接器（引擎）	一条把能力接进来的通道	配置文件 `mcp.json`
信任登记	允许这个引擎被使用的许可	配置文件 `mcp-approvals.json`

关键：装了连接器 ≠ 能用。还要有信任登记，并且指令里点到工具名。

三者缺一，会分别出现三种不同的现象，见 C.4 的对照表。

C.2 配置在哪儿（两个位置，别弄错）

项目	位置
配置根目录（macOS）	`~/.workbuddy-ai/`　（部分版本是 `~/.workbuddy/`）
连接器登记文件	配置根目录下的 `mcp.json`
信任登记文件	配置根目录下的 `mcp-approvals.json`
运行日志	配置根目录下 `logs/<日期>/workbuddyMainThread*.log`

两个常见错误：

把连接器写进了子目录（例如 connectors/default/mcp.json）——应用只读根目录那一份，写在子目录里等于没写。
连接器名字写成带前缀的形式（custom-mcp:doc-filler）——登记时要用裸名 doc-filler。

（带前缀的形式只出现在日志的 configId= 里，那是应用内部叫法。）

C.3 配一次连接器的完整步骤

以新增 doc-filler 引擎为例（其他引擎同理）：

第 1 步　登记连接器。

在配置根目录的 mcp.json 里，增加一条：

"doc-filler": {
  "type": "streamableHttp",
  "url": "https://zhenyuonline.cn/doc-filler-mcp",
  "disabled": false
}

第 2 步　登记信任。

在 mcp-approvals.json 里增加一条，键是 <域名标识>::<连接器名>，值是一个时间戳：

"<域名标识>::doc-filler": 1789609067974

第 3 步　完全退出应用再打开。

这一步最容易做错：应用只在启动时读一次配置。关窗口不算退出——

用应用菜单里的“退出”（或快捷键 Cmd+Q）
确认进程真的没了
再重新打开

第 4 步　验证。

打开日志文件，搜连接器名字，应该能看到两行：

[MCP-Connect] ok  configId=custom-mcp:doc-filler  transport=streamableHttp
[MCP-Inspect] end configId=custom-mcp:doc-filler  tools=5

tools=5 就是引擎挂上了、里面有 5 个工具。没有这两行，就是不生效。

C.4 三种现象对照表（照着查）

现象	原因	怎么排
问“我接了哪些引擎”，数目不对／少了	第 1 步没做，或写在了子目录、或名字带了前缀	检查 `mcp.json` 是否为根目录那一份、名字是否为裸名
日志里有 `skipping untrusted server “doc-filler”`	第 2 步没做——信任门静默拦截	在 `mcp-approvals.json` 补登记，然后完全退出应用再打开
引擎连上了（日志有 `tools=N`），但它还是自己动手写代码	指令里没点名工具	在指令里点名，如“用 `filler_batch` 出这批作业”
改完配置毫无变化	应用没真正退出（只是关了窗口）	完全退出后重开

日志里认这几种字样：

字样	意思
`[MCP-Connect] ok`	连接器连上了
`[MCP-Inspect] end ... tools=N`	这个引擎有几个工具可用
`[MCP-Connect] transport-failed`	连不上（地址错、服务没起来、网络不通）
`[MCP Security] skipping untrusted server`	信任门拦截，去补 C.3 第 2 步
`handshake SLOW`	连上了但慢（网络问题，不影响使用）

C.5 数据安全：什么能传，什么不能传

引擎跑在服务器上，数据会离开你的电脑。按下面三条判断：

数据类型	能不能传	说明
公开教材、已发表文献、公开政策文件	可以	本来就是公开的
自己写的教案、大纲、课件	可以	你的劳动成果，注意别带未公开的合作方内容
学生个人信息（姓名、学号、成绩）	谨慎	只在必要的填制场景用，用完及时清理产物；不要上传整班的成绩单
未公开的科研数据、合作方保密材料	不要	先脱敏，或改成本机处理
涉密文件	绝对不要	任何情况下都不上传

一条实用建议：做学生名单相关的事，先在纸上或本地表格里把名单准备好，

只把这一次任务需要的最小字段填进去（比如只给姓名和学号，不给身份证号、家庭住址、成绩）。

C.6 交付前的自检（三问）

每次交活之前问自己三句，能省掉大部分返工：

产物在不在？ 我手上有没有一个能打开的文件或一个能访问的网址？只有一个“已生成”的说法不算。
校验过了没？ 填制类看 filler_check 的 verdict 是不是「校验通过（未替换 0 / 缺失 0）」；

名单类做一次名单对账（应交 / 实交 / 缺谁）。

名字写对没？ 教研材料里引用工具时，引擎名和工具名要写全（附录 A 可以直接抄）。

C.7 一句话记住

**连接器登记在根目录 mcp.json；信任登记在 mcp-approvals.json；

改完必须完全退出应用再打开；验证看日志里的 tools=N。**

不生效的时候，先怀疑“信任门”，十有八九是它。

附录 C 连接器配置与排错