知识与 MCP：先判断需要哪一层事实

MCP 是 AI 客户端调用本地工具的协议。FH2 工具链既提供只读知识检索，也提供会创建文件、构建、打包或启动服务的工程工具。

如果你只想快速判断：

普通开发查 API、字段、错误码：用工具链内置知识。

要和某个后端版本严格对齐：再安装并固定目标后端知识包。

客户端连不上或工具不可用：看“配置本地 MCP 客户端”和排错页。

先分清两层知识，再决定要不要固定后端版本：

你的任务	用哪层知识	怎么用
查公开 API、字段、错误码，写普通插件	工具链内置 `developer-runtime`	随开发者工具提供，MCP 只读；不需要 `knowledge import`
需要和某个后端版本严格对齐，或使用该版本的流程节点目录	目标后端知识包	用 `knowledge import` 安装，`knowledge use` 固定到工程

developer-runtime 是开发者工具同版的公开契约投影，前端和后端的公开事实都在里面。它不是项目级知识包，也不需要每个工程安装一次。

目标后端知识包是同一套知识生成流程按目标 Worker 版本产出的快照，解决“部署后端版本可能不同”的问题。它不会替换 developer-runtime 的公开投影；固定后只影响当前工程的知识选择。

需要固定后端版本时

取得与目标后端版本匹配的知识包，在已注册 CLI 的终端执行：

import 校验并安装到本机缓存，不改项目锁。

use 只固定已安装身份，不下载/安装。

锁文件 backend-plugin-knowledge.lock.json 记录格式、身份和内容摘要，应随项目版本管理；不含下载 URL、凭据或 checker 执行路径。

status 是只读查询。核对 locked、active、installed、problems 和 checkerAvailable，不能只看退出码。有阻断项时 JSON 模式返回非零；未固定可能没有阻断，但仍没有可复现的项目选择。

当前没有同版本权威流程校验器，所以 checkerAvailable 可能是 false。固定知识不等于有权威校验器；工作流画布的快速预检通过也不等于流程可部署。

配置本地 MCP 客户端

先在终端运行 fh2-plugin mcp --help 查看当前配置说明。客户端通过 stdio（标准输入/输出）启动服务，不连接 Web IDE 端口。不要在启动包装器向 stdout 打印额外文字、Token 或配置值；stdout 用于协议帧。

以下是 OpenCode 项目配置的 JSON 片段。合并到现有配置，不覆盖其他配置。把 /path/to/plugin-workspace 换成已存在工程的实际绝对路径：

{
  "mcp": {
    "fh2": {
      "type": "local",
      "command": ["fh2-plugin", "mcp", "--root", "/path/to/plugin-workspace"],
      "enabled": true
    }
  }
}

GUI 客户端不一定继承终端 PATH：

找不到 Node/CLI 时，把 command 改为实际 Node 可执行文件、开发者工具的 packages/fh2-plugin-toolchain/bin/fh2-plugin.mjs 和参数组成的数组。

各路径使用绝对路径，保留 bin 入口，不绕过它直跑 dist/cli.js。

不要在公开配置中写私人路径或密钥。

启动后检查客户端连接状态、当前版本和可用工具；连接失败看 stderr/客户端日志。知识投影缺失或校验失败会导致服务启动失败，不是成功连接后可以忽略的空知识。

路径范围与只读授权

不传 --root 是开放模式，工程路径相对启动目录解析，任意绝对路径也可访问。传 --root 才将工具路径参数收纳到该已存在目录，检查相对路径、绝对路径和符号链接越界；根选择错误须改配置后重启。

这是工具入参的路径边界，不是构建沙箱、账号权限或只读模式：

构建依赖脚本和进程仍以启动者身份运行。

工程锁等文件仍可能写到归属工作区。

--root 不会替 AI 禁用写工具，也不会授予司空环境权限。

只做能力调查时，在 AI 客户端使用明确的工具白名单：允许 list_knowledge、search_knowledge、read_contract、只读 Resources，以及必要的 inspect。

需要检查已生成类型时，再单独允许带合法 check: true 的 generate。普通 validate 不写源码，但客户端授权仍应明确。

create、默认 generate、build、pack、start_dev、cancel_task 有写入、任务或进程副作用，分别确认工程路径、范围和授权。MCP 当前没有 preview 工具。

先检索再读取正文

问「有哪些」用 list_knowledge 并处理分页；查具体语义/标识用 search_knowledge。查询结果带摘要、正文和事实 Resource URI，优先读取完整 Resources；客户端不支持时用 read_contract 读取公开引用，不把 ref 当作任意文件路径。

{
  "query": "HTTP 预览 PAC",
  "limit": 5
}

核对结果 versions 中的工具链版本、知识/契约状态和摘要，再读权限、前置条件、限制及失败语义。

没有记录、未支持、环境未就绪和受阻不是同一个结论；知识陈述不证明实际宿主或设备已经验证。

工程任务与结束

build、pack、start_dev 受理后返回 taskId，不等待终态。用 get_task 持续核对状态、诊断、日志、产物和过期标记；获得 ID 不是构建通过，长运行 dev 处于运行中也不是完成全部业务验证。

取消使用 cancel_task，只操作本次服务拥有的任务，不猜其它会话的任务 ID。取消不是回滚已写入文件或撤销已生成产物。

结束时停止/取消自己启动的任务，再断开客户端。stdio 关闭或服务退出会清理所属运行任务，但不会删除已创建工程。

打包成功只生成未签名产物，上传须另行授权。工程目录和 CLI 参数见工具链命令行参考。

继续阅读

知识与 MCP：先判断需要哪一层事实

需要固定后端版本时#

配置本地 MCP 客户端#

路径范围与只读授权#

先检索再读取正文#