Files
ssw-platform/docs/mcp.md
T
admin 343772be42 docs(lowcode): 对齐 jnpf 运行时机制,纠正两处已实现代码的错误判断
- 新增 docs/visualdev-mechanism.md:接口契约 15 端点 / 列名规则 / 系统字段 / 自动填充 / 主子表,
  每条结论标了源码位置与复核命令
- 纠正①:列名 = lower(vModel)(VisualDevTableCre 原样写 vModel + PG toLowerCase),
  不是「剥前缀」;f_creatortime 就是真实列名,f_creator_time 属于平台表手写 DDL
- 纠正②:calculate 接收入参(create() 走 getIntValue),归入 Number,删掉 Computed 枚举
- 新增 widget::auto_fill/AutoFill:把 Java create() 的自动填充固化成可测枚举,
  并加交叉断言「被覆盖的字段不能标 acceptsInput」
- 影响:测试 344 → 346;十二闸全绿;v_model_to_column 简化为 to_lowercase
2026-10-31 12:02:15 +08:00

340 lines
15 KiB
Markdown
Raw 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/ssw-platform --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/ssw-platform --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 自纠
```
### 当前业务工具(22 个)
| 域 | 工具 | 一句话 | 写 |
|---|---|---|---|
| context | `context.get` | 取后端/应用/表数 | |
| schema | `schema.table.list` | 列出物理表 | |
| schema | `schema.table.describe` | 看表的列与类型 | |
| schema | `schema.index.list` | 索引与唯一约束 | |
| menu | `menu.tree` | 菜单树(按应用隔离) | |
| menu | `menu.create` | 建菜单(写全 enCode + systemId) | ✅ |
| menu | `menu.delete` | 软删菜单 | ✅ |
| permission | `permission.user.list` | 用户(**不含口令字段**) | |
| permission | `permission.user.create` | 建普通用户(可同时绑角色) | ✅ |
| permission | `permission.role.list` | 角色 | |
| 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` | 建字典分类 | ✅ |
| data | `data.query` | 按表名查数据(结构化条件) | |
| data | `data.count` | 按表名计数 | |
| form | `form.list` | 列低代码功能(`base_visual_dev`) | |
| form | `form.describe` | 解析表单:主表字段/子表/控件类型 | |
| form | `form.validate` | 校验表单声明的字段在表里是否真有列 | |
**写工具为什么少而严**:读工具错了只是「看到错的数据」,写工具错了是「把库改坏」。
所以写工具都在写库**之前**做完校验(必填/格式/父节点存在/编码唯一),
并给出可执行的 `hints`;删除一律软删。
🔴 **`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 补。
---
## 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` | `src/backend/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/ssw-platform &
cargo run -p sspf-adapter-baseline --example probe -- \
http://127.0.0.1:30994 admin "$(./target/release/ssw-platform --enc 123456)"
```
🔴 口令要传**密文**(`--enc` 生成)。适配器不复制 cipher 逻辑 ——
复制会漂移,下沉到 contract 会破坏「契约层无 IO」的边界(AR4)。
---
## 5. 已知限制(P1 阶段)
| 限制 | 说明 | 计划 |
|---|---|---|
| 没有登录态 | 进程内适配器是**管理员视角**,绕过菜单守卫 | 刻意如此(本地开发);对外暴露必须换 `BaselineHttpAdapter` |
| 业务工具 19 个 | 见上面清单;form / model / workflow 还没有 | P2 补 |
| 基线适配器只支持 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`
**协议层、元工具、注册表都不用改。** 这是分层加载的直接收益。