Files
admin acf076df5a refactor: 内核瘦身 —— 示例搬成业务包 + 装配/测试各归其位
- 内核只有 lib:启动装配 → crates/sspf-admin(bin sspf-admin);37 个集成测试 → crates/tests(package sspf-tests)。
- demo/shop/books 的 spec/菜单/DDL/面 B 路由搬进 packs/{demo,shop,books};内核 modules/*.rs 只剩「面 A 适配器 + pub use」⇒ 内核零业务知识,示例可整目录搬走。面 A 与前端零改动。
- 示例表 DDL 按平台规则补 f_tenant_id + 复合主键(spec 不加 ⇒ JSON 键与响应逐字不变)。
- 修 is_builtin_table 只认 schema.sql 的漏洞:包表(含 asset_data_resource)此前可被建模页删除/改;现为「平台 DDL ∪ 包表」。
- sspf-compat-online_dev → onlinedev(包名/模块/文件/路由别名同步);6 个 5 行转发壳合并为 forward.rs。
- 新增 AR16 闸门 + lib.rs「30 秒地图」+ src/backend/README.md;pack-sync 补两处判据(module_key=None 的 urlAddress、apiFile 查存在性)。
- 回归:704 tests / 6 道静态闸门全绿;health 181 表;四个包面 A/面 B 运行时全部 200。
2026-11-04 14:46:12 +08:00

451 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MCP 工具层 —— 让 AI 直接驱动 SSPF
> 一个进程、一条 stdio、4 个工具,AI 就能建表 / 建菜单 / 查数据。
> 架构与设计动机见 `PLAN.md` §6;本文只讲**怎么接、怎么用、踩过什么坑**。
---
## 1. 30 秒接入
```bash
# 确认二进制在
cargo build --release
# 手动跑一次(可选)—— 应该立刻回一行 initialize 的 JSON
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
| ./target/release/sspf-admin --mcp 2>/dev/null
```
### Claude Code / 通用 MCP 客户端
在 MCP 配置里加一条(`~/.claude.json` 的 `mcpServers`,或客户端对应的配置文件):
```json
{
"mcpServers": {
"sspf": {
"command": "/绝对路径/ssw-platform",
"args": ["--mcp"],
"env": {
"PGLITE_DIR": "/绝对路径/数据目录/lite.pg"
}
}
}
}
```
🔴 **`PGLITE_DIR` 必须写绝对路径**:MCP 客户端启动子进程时 cwd 不确定,
相对路径会把库建到奇怪的地方(默认值依赖「从可执行文件向上找锚点」,MCP 下也不稳)。
### 想同时用浏览器看效果?
```bash
./target/release/sspf-admin --mcp --with-http
```
**同一进程、同一个 `AppState`、同一个库**:AI 通过 MCP 建的表 / 写的菜单,
浏览器刷新就能看到;反之亦然。这才是「人 + AI 协作」该有的手感 ——
不用来回切进程、切数据目录。
MCP 客户端里加 `"args": ["--mcp", "--with-http"]` 即可,
HTTP 默认监听 30010(`PORT` 可改),前端代理指过来就行。
⚠️ **一个数据目录只能被一个进程打开**(pglite 独占)。
已经用 `--with-http` 起了服务,就别再单独起一个 `ssw-platform`。
---
## 2. 只有 4 个工具,但能干所有事
`tools/list` 永远只返回这四个:
| 工具 | 干什么 | 典型参数 |
|---|---|---|
| `sspf_context` | 我是谁、连的哪个后端、多少表 | `{}` |
| `sspf_discover` | 我想干 X → 有哪些工具 | `{"query":"表单 创建"}` |
| `sspf_describe` | 这个工具怎么用、有什么坑 | `{"tool_id":"form.create","level":"pitfalls"}` |
| `sspf_call` | 执行 | `{"tool_id":"schema.table.list","args":{}}` |
**为什么不全量下发**:55 个工具全注册约 18K token,200 个约 60K —— 还没干活就烧掉大半上下文。
现在常驻约 1.8K,用一个按需取一个(约 300 token)。
### 推荐调用顺序
```
sspf_context # 1. 先确认环境
→ sspf_discover("建一个报销单") # 2. 找工具(返回精简索引)
→ sspf_describe(level="pitfalls") # 3. 先看坑(比看参数更重要)
→ sspf_call(dry_run=true) # 4. 校验形态
→ sspf_call # 5. 真执行
→ 失败则读 error.hints / next_actions 自纠
```
### 当前业务工具(52 个)
| 域 | 工具 | 一句话 | 写 |
|---|---|---|---|
| context | `context.get` | 取后端/应用/表数 | |
| context | `context.app.list` | 列多应用(`base_system`,默认不含主系统) | |
| schema | `schema.table.list` | 列出物理表 | |
| schema | `schema.table.describe` | 看表的列与类型 | |
| schema | `schema.index.list` | 索引与唯一约束 | |
| schema | `schema.table.create` | 按低代码设计稿建表 + 回写模型 | ✅ |
| menu | `menu.tree` | 菜单树(按应用隔离) | |
| menu | `menu.info` | 菜单详情(改之前先看) | |
| menu | `menu.create` | 建菜单(写全 enCode + systemId) | ✅ |
| menu | `menu.update` | 改菜单(名称/地址/图标/排序) | ✅ |
| menu | `menu.delete` | 软删菜单 | ✅ |
| permission | `permission.user.list` | 用户(**不含口令字段**) | |
| permission | `permission.user.create` | 建普通用户(可同时绑角色) | ✅ |
| permission | `permission.user.delete` | 软删用户(管理员不可删) | ✅ |
| permission | `permission.organize.tree` | 组织机构(平铺,含 parentId) | |
| permission | `permission.role.list` | 角色 | |
| permission | `permission.role.create` | 建角色(enCode 全平台唯一) | ✅ |
| permission | `permission.role.delete` | 软删角色(系统角色不可删) | ✅ |
| permission | `permission.authorize.list` | 查某对象的直授 | |
| permission | `permission.authorize.grant` | 给用户/角色/组织/岗位授菜单(幂等) | ✅ |
| permission | `permission.authorize.revoke` | 撤权(软删,撤不存在会报错) | ✅ |
| permission | `permission.effective` | 四源并集算出**实际**可见的菜单 | |
| dict | `dict.type.list` | 字典分类 | |
| dict | `dict.data.list` | 字典项 | |
| dict | `dict.type.create` | 建字典分类 | ✅ |
| dict | `dict.type.update` | 改字典分类 | ✅ |
| dict | `dict.type.delete` | 软删分类(**不级联**字典项) | ✅ |
| dict | `dict.data.create` | 往分类追加字典项 | ✅ |
| data | `data.query` | 按表名查数据(结构化条件) | |
| data | `data.count` | 按表名计数 | |
| data | `data.record.insert` | 按设计稿新增记录(主表 + 子表) | ✅ |
| data | `data.record.update` | 按设计稿更新(子表差集对账) | ✅ |
| data | `data.record.delete` | 删记录(逻辑/物理按功能设置) | ✅ |
| form | `form.list` | 列低代码功能(`base_visual_dev`) | |
| form | `form.describe` | 解析表单:主表字段/子表/控件类型 | |
| form | `form.validate` | 校验表单声明的字段在表里是否真有列 | |
| form | `form.create` | 建表单定义(草稿态;`formData` 可传对象) | ✅ |
| form | `form.update` | 改表单定义(只 SET 传了的键) | ✅ |
| form | `form.delete` | 软删功能(菜单需另行清理) | ✅ |
| form | `form.selector` | 功能下拉(挂菜单/绑流程用) | |
| workflow | `workflow.template.list` | 流程模板列表(元数据) | |
| workflow | `workflow.template.info` | 模板详情 | |
| workflow | `workflow.template.create` | 建模板(只写元数据) | ✅ |
| workflow | `workflow.template.update` | 改模板 | ✅ |
| workflow | `workflow.template.delete` | 软删模板 | ✅ |
| workflow | `workflow.template.selector` | 流程下拉(绑表单/菜单用) | |
| workflow | `workflow.task.list` | 任务元数据(无引擎 ⇒ 通常为空) | |
| ops | `ops.health` | 表数 / 会话数 / admin 就绪 | |
| ops | `ops.logs` | 按分类查系统日志 | |
| ops | `ops.online` | 按账号聚合的在线会话(不含 token) | |
| ops | `ops.schedule.list` | 定时任务定义(不跑调度) | |
| ops | `ops.db.stats` | 关键表行数 + 库体积 | |
**P3 这批(26 个)怎么实现的**:不重写 SQL,而是**进程内直调契约面 handler**
(`crates/sspf-mcp-adapter/src/mcp_compat.rs`),与 HTTP 路由注册的是同一个函数 ⇒ 校验、默认值、
软删语义只有一份。代价是 MCP 适配器必须构造管理员请求头(`SessionStore::issue` 一个
`admin` 会话),所以**它只适用于本地开发**;对外暴露要走 `BaselineHttpAdapter` 带真实 token。
**写工具为什么少而严**:读工具错了只是「看到错的数据」,写工具错了是「把库改坏」。
所以写工具都在写库**之前**做完校验(必填/格式/父节点存在/编码唯一),
并给出可执行的 `hints`;删除一律软删。
🔴 **`data.query` 不投影口令 / 密钥列**(`f_password` / `f_secretkey`):
缺省投影会跳过它们并在结果里返回 `hiddenColumns`(藏了几列);
显式在 `columns` / `where` / `orderBy` 里要它们 ⇒ `SENSITIVE_COLUMN`。
要用户信息请用 `permission.user.list`(它本来就不返回口令字段)。
🔴 **`menu.create` 比 HTTP 侧的 `module_save` 更完整**:后者只写 12 列,缺
`f_en_code`(面 B 权限判据)与 `f_system_id`(多应用隔离)——那两列缺了,
菜单要么点进去 403,要么根本不显示。P2 元数据引擎统一时会把两处合成一处。
### 授权闭环:建完菜单不等于看得见
```
menu.create 建菜单
→ permission.authorize.grant 授给角色(推荐)或用户(临时特批)
→ permission.user.create 建一个**非管理员**账号验证
→ permission.effective 看他实际能访问什么,每项标明来自哪个源
```
🔴 **绝不能用 admin 验证**:`is_admin == 1` 在守卫第一条判据就返回 true,
根本不查授权表 —— 用 admin 测等于什么都没测。`permission.effective` 会显式
返回 `isAdmin: true` 与 `mode: "admin-bypass"`,提醒你这个结果不代表授权生效。
`permission.effective` 返回两组数,这是排查「授权了但看不见」的关键:
| 字段 | 含义 |
|---|---|
| `fourSource` | 四源并集(直授 + 角色 + 组织 + 岗位),**不按应用过滤** |
| `visible` | 再与当前应用的菜单求交 —— 这才是用户真正能点到的 |
| `sources.*` | 每个源各贡献了哪些菜单 id(定位「这条权限从哪来」) |
两者不一致 ⇒ 授权指向了别的应用的菜单(或菜单已删)。
### 低代码:看懂一张表单,先于写它
```
form.list 有哪些功能(type/state)
→ form.describe 主表字段 / 子表 / 每个控件的存储类别
→ form.validate 表单声明的字段 ↔ 表结构对不对得上
```
`form.describe` 和 `form.validate` 支持**两种输入**:
| 模式 | 入参 | 用在哪 |
|---|---|---|
| 查库 | `id` 或 `enCode` | 功能已经在 `base_visual_dev` 里 |
| **inline** | `formData`(+ `tablesData`) | 草稿还没入库,先校验再说 |
inline 模式是刻意的:AI 生成一份表单 JSON 后**先校验、后落库**,比写完再报错成本低得多。
**控件分类决定数据怎么存**(`sspf-lowcode/src/widget.rs`,54 种 jnpfKey → 11 类):
| 类别 | 举例 | 接收入参 |
|---|---|---|
| text / number / dateTime / enum | `input` `inputNumber` `datePicker` `select` | ✅ |
| entityRef | `userSelect` `organizeSelect` | ✅(存 id) |
| attachment | `uploadFile` | ✅(URL 列表 JSON) |
| **systemGenerated** | `billRule` `createUser` `createTime` | ❌ 后端填 |
| **layout** | `groupTitle` `divider` | ❌ 不占列 |
| **subTable** | `table` | ❌ 数据在独立表 |
🔴 让入参覆盖 `billRule`(单据号)或 `createUser`,会破坏业务编号规则与审计链路 ——
这是「数据被写坏」最常见的来源,所以 `acceptsInput` 在 `describe` 里显式返回。
**列名规则是确定的**(已对齐 jnpf 建表逻辑,见 `docs/visualdev-mechanism.md` §3):
```
低代码动态建的表:列名 = lower(__vModel__)
F_Room → f_room F_CreatorTime → f_creatortime(不是 f_creator_time)
```
jnpf 建表时原样写 vModel,PG/Kingsbase 再 `toLowerCase()`。
⚠️ 平台表(`base_*`)的 `f_creator_time` 是**手写 DDL**,与这条规则无关 —— 别混。
**`form.validate` 只保证「设计稿自洽」,不等于「表已经建好了」**:
它比对表单推导的列与模型 `field` 推导的列(两边同一套规则,所以能验出「表单引用了模型里没有的字段」)。
但库里到底有没有这张表、列够不够,要拿 `information_schema` 比 ——
这一步由 P2-b 的写工具在**落库前**做(对不上报 `COLUMN_MISMATCH` / `TABLE_NOT_IN_DB`,拒绝写)。
### 低代码动态 CRUD(P2-b)
```
schema.table.create(dryRun) 先看要建的 DDL 与回写后的模型
→ schema.table.create 建表 + 回写 f_tables_data(幂等)
→ data.record.insert(dryRun) 看 SQL 与参数
→ data.record.insert 落库
→ data.query 查证
→ data.record.update 改主表字段 / 子表差集对账
→ data.record.delete 删(逻辑或物理,按功能的 logicalDelete)
```
**建表不是可选项**:低代码功能的表不会自己出现。`data.record.*` 直接写一张不存在的表
会报 `TABLE_NOT_IN_DB` —— 这时先 `schema.table.create`。
🔴 **建表后必须回写 `f_tables_data`**(工具内部做,`dryRun=false` 时)。
不回写的后果不是「少一列」这么轻:CRUD 层在**模型**里找 `f_delete_mark`,
找不到就报 `LOGICAL_DELETE_UNSUPPORTED`;而且「设计稿 vs 真实库」的列比对永远对不上。
基线平台 `VisualDevTableCre.tableList()` 建完表也是把装配后的 `TableModel` 写回 `f_tables_data`。
`schema.table.create` 支持两种输入:
| 模式 | 入参 | 能落库吗 |
|---|---|---|
| 查库 | `id` / `enCode` | ✅ `dryRun=false` 建表 + 回写 |
| inline | `formData` + `tablesData` | ❌ 只能演练(`INLINE_REQUIRES_DRY_RUN`)—— 没有可回写的功能记录 |
**子表更新是差集对账,不是整条替换**(与主表的部分更新语义不同):
| 情况 | 动作 |
|---|---|
| 入参行的主键在库里 | `updateSub` |
| 入参行的主键不在库里 | `insertSub` |
| 库里有、入参没有 | 删除(`logicalDelete` 开则 `softDelete`,否则 `hardDelete`) |
🔴 因此「只改子表一行的某个字段」也必须把**这张子表的所有行**都传进来,
否则没传的旧行会被删掉。只想追加不改动,就先把现有行查出来一起传。
**三道落库前校验**(都对齐基线平台,失败时一条 SQL 都不执行):
| 校验 | 触发条件 | 错误码 |
|---|---|---|
| 单行唯一 | 控件 `unique=true` 且是普通输入 | `UNIQUE_CONSTRAINT_VIOLATED` |
| 业务主键组合唯一 | 表单 `useBusinessKey=true` | `BUSINESS_KEY_VIOLATED` |
| 必填 | 控件 `required=true` | `MISSING_REQUIRED` |
查重只算**未删除**的行(`f_delete_mark=0` 或该列不存在);更新时排除自己。
**写工具默认 `dryRun=true`**(不传就是演练)。dry-run 会返回完整 SQL 与参数 ——
这是刻意的:AI 要先能看清「到底写什么」,才谈得上让人放心让它写。
返回值里不含任何口令字段(适配器层就不投影这类列);业务数据本身**不做脱敏** ——
dry-run 的意义就是让人核对真实值,遮掉反而看不出写错在哪。
### 造一份示例功能:`--seed-lowcode-demo`
```bash
PGLITE_DIR=/tmp/sspf-demo ./target/debug/sspf-admin --seed-lowcode-demo # 建表 + 写功能定义
PGLITE_DIR=/tmp/sspf-demo ./target/debug/sspf-admin --seed-lowcode-demo --dry-run # 只看不碰库(连库都不开)
```
- 固定 `id=lowcode-demo-receivable` + `enCode=receivableDemo` ⇒ **幂等**(重复跑是更新同一条)
- 数据来源是**官方 fixture**(基线初始化数据里的「应收费用」)⇒ 种出来的库就是真实低代码功能的样子
- 只在 dev 档可用:`SSW_PROFILE=prod|production` 在**开库前**就拒绝(它会建表)
- 种完可以立刻 `data.record.insert {"enCode":"receivableDemo",...}` 端到端试写
---
## 3. 失败返回长什么样(比成功更重要)
业务失败**不是** JSON-RPC error,而是正常返回里的结构化结果:
```json
{
"ok": false,
"tool_id": "form.create",
"error": {
"code": "FORM_ENCODE_EXISTS",
"message": "enCode 已存在:asset_ledger",
"field": "enCode",
"retryable": false,
"hints": ["换一个 enCode,或对已有表单调用 form.update"],
"next_actions": [
{ "tool": "form.list", "args": { "keyword": "asset_ledger" }, "why": "先确认是否同一个表单" }
]
}
}
```
**AI 应当据此改参数或先调 `next_actions` 里的工具,不要原样重试** ——
业务失败是确定性的(enCode 重复、无权限),原样重试一定再失败。
只有协议级问题(方法不存在、参数不是 JSON)才走 JSON-RPC 的 `error`。
---
## 4. 资源、模板与双后端
### 可读资源(`resources/read`)
| URI | 内容 |
|---|---|
| `sspf://registry/tools` | 全部业务工具索引(离线查阅用) |
| `sspf://docs/quickstart` | 上面的推荐顺序与常见误区 |
| `sspf://contract/endpoints` | HTTP 契约端点表(与 MCP 工具不是一一对应) |
### 多步流程模板(`prompts/*`)
模板回答的是「整件事按什么顺序做、做到哪算完成」——AI 最容易错的不是参数,
而是**漏步骤**(建了菜单忘授权、授权了没验证)。
| 模板 | 参数 | 干什么 |
|---|---|---|
| `new_business_module` | `module_name` / `module_code` / `role_id`(可选) | 建菜单 → 授权 → 建非管理员账号 → 验证可见,共 5 步 + 失败对照表 |
| `diagnose_menu_not_visible` | `account` | 五步定位法,按 `fourSource` / `visible` 分流判断根因 |
| `verify_all` | — | 一次跑完全部测试、静态闸门、契约尺子、内存实测 |
模板**不占常驻 token**(只在用户主动引用时 `prompts/get`)。
🔴 模板正文里引用了工具 id,工具改名后模板会变成错误指导且**没人会发现**。
`crates/sspf-mcp/src/prompts.rs` 的测试会扫出正文里所有 `域.动作` 字符串逐个核对,
引用不存在的工具 ⇒ 测试失败。
### 双后端:同一套工具打两种后端
`PlatformAdapter` 只有两个方法,实现有三个(`Null` 是测试用):
| 实现 | 位置 | 后端 | 用在哪 |
|---|---|---|---|
| `NativeAdapter` | `crates/sspf-mcp-adapter/src/mcp_adapter.rs` | 进程内 `AppState` | 主力形态(`--mcp`) |
| `BaselineHttpAdapter` | `crates/sspf-adapter-baseline` | 远端 HTTP(Java 后端或本仓内核) | P4 影子对账 / 过渡期提速 |
基线适配器**刻意只映射 5 个只读 op**(`context.get` / `menu.tree` /
`permission.user.list` / `permission.role.list` / `dict.type.list`):
- baseline 是**业务 API**,没有「列出表结构」这类端点 —— 硬凑会造出
「看起来能跑、语义其实不对」的工具,比明确不支持更糟
- 不支持的 op 返回 `CAPABILITY_UNSUPPORTED` + 「切 native」的可执行建议
它同时是**形状适配器**(这才是对账的关键):
```
baseline: {code,msg,data:{list,pagination}} → native: {count, users/roles/menus/types}
organize → organizeId
多余键(creatorTime/fullName…) → 裁掉
```
形状不统一时,对账每一条都是差异,看不出业务问题。
```bash
# 探针:用它打任意实现了契约的 HTTP 后端
PGLITE_DIR=/tmp/db PORT=30994 ./target/release/sspf-admin &
cargo run -p sspf-adapter-baseline --example probe -- \
http://127.0.0.1:30994 admin "$(./target/release/sspf-admin --enc 123456)"
```
🔴 口令要传**密文**(`--enc` 生成)。适配器不复制 cipher 逻辑 ——
复制会漂移,下沉到 contract 会破坏「契约层无 IO」的边界(AR4)。
---
## 5. 已知限制(P2-b 收尾时点)
| 限制 | 说明 | 计划 |
|---|---|---|
| 没有登录态 | 进程内适配器是**管理员视角**,绕过菜单守卫 | 刻意如此(本地开发);对外暴露必须换 `BaselineHttpAdapter` |
| 业务工具 26 个 | 见上面清单;model / workflow / release 域还没有 | P3 补 |
| 读的是 `base_visual_dev`,不是 release | 只读工具与动态 CRUD 都取草稿表;发布快照 `base_visual_release` 只有种子在写 | 运行时读 release 待补(P2-c) |
| 单据号生成器未做 | `billRule` 控件不接收入参,但**也不会自动生成**(需序号表);入参给了 `billRule` 字段会被忽略 | 序号表 + 规则引擎(P2-c) |
| 没有乐观锁 | `concurrencyLock=true` 时插入会写 `f_version=0`,但更新**不校验**版本 | 真并发控制(P3) |
| 建表只建不改 | 表已存在且列不同 ⇒ `TABLE_EXISTS_DIFFERENT`,不自动 ALTER | 刻意:自动迁移比报错危险 |
| `schema.table.create` 只在 dev 档建表 | 生产档拒绝(会改库结构) | 刻意 |
| 基线适配器只支持 5 个只读 op | baseline 无元数据 API | P4 按对账需要再补 |
| 基线适配器只支持 `http://` | 未引入 TLS 栈;`https://` 构造期直接报错 | 需要时再加 |
| `permission.user.create` 不开放建管理员 | `isAdministrator` 硬编码 false | 刻意:避免 AI 顺手造超管 |
| 🔴 **stderr 不能是 `/dev/null`** | 见下方「坑 ④」 | 已在代码里尽量兜,但客户端请收 stderr |
### 🔴 坑 ④:stderr 指向 `/dev/null` 时会零响应
`--mcp` 模式会把 fd 1 让给 stderr(为了让 PG 的 `backend>` 日志不污染 NDJSON)。
如果**stderr 恰好是 `/dev/null`**,协议通道会和它共享同一个 file 描述,
导致写出去的数据被吞 —— 表现为**一条响应都没有,退出码却是 0**。
- ✅ MCP 客户端(Claude Code / Cursor 等)都会收 stderr 进日志 ⇒ 生产场景没问题
- ✅ shell 里测试用 `2>/tmp/mcp.log`
- ❌ 别用 `2>/dev/null` 测 MCP
`mcp-smoke.sh` 用的就是 `2> "$ERR"`(文件),所以能跑。
---
## 6. 🔴 三个踩过的坑(改 MCP 代码前必读)
**① 内嵌 PostgreSQL 会抢 stdin 和 stdout**
`pglite` 的 PG single-user 后端会:
- 往 **fd 1** 打 `PostgreSQL stand-alone backend 17.5` 和 `backend>` 提示符
- **占用 fd 0** 读 SQL —— 直接读 stdin 会拿到 `ENXIO (Device not configured)`
⇒ 内核在**开库之前**调 `detach_stdio_for_mcp()`:先 `dup` 出协议通道,
再把 fd 0 指到 `/dev/null`、fd 1 指到 stderr。之后 PG 随便折腾,协议走专属 fd。
`mcp-smoke.sh` 的 M11/M12 就是钉住这个行为,改回去会立刻红。
**② tokio 的 stdin / 文件 API 在管道上会 ENXIO**
`tokio::io::stdin()` 与 `tokio::fs::File` 都要求 fd 可被 io 驱动注册;
复制出来的管道 fd 不满足。⇒ 用「独立线程同步读 + 同步写」(`BlockingWriter`)。
**③ 业务失败与协议失败必须分开**
混在一起,AI 分不清「我调错了」和「操作被业务规则拒了」,
会去改 `tool_id` 而不是改参数。协议错误只留给:方法不存在、参数不是 JSON。
---
## 7. 加一个业务工具的完整成本
1. 在 `crates/sspf-mcp/src/tools/mod.rs` 写一个 `ToolDef`:
schema + 注解 + **五段自提示**(when_to_use / when_not_to_use / preconditions / pitfalls / examples)
2. 加进 `ALL_TOOLS`
3. 适配层 `mcp_adapter.rs` 的 `invoke()` 加同名分支(`op` == `tool.id`,刻意同名)
4. `cargo test -p sspf-mcp` —— 元测试会校验 schema 合法、`one_liner` ≤ 40 字、示例是合法 JSON、每个坑都有 `rationale`
**协议层、元工具、注册表都不用改。** 这是分层加载的直接收益。