- 新增 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
340 lines
15 KiB
Markdown
340 lines
15 KiB
Markdown
# 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`
|
||
|
||
**协议层、元工具、注册表都不用改。** 这是分层加载的直接收益。
|