- 新增 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
15 KiB
MCP 工具层 —— 让 AI 直接驱动 SSPF
一个进程、一条 stdio、4 个工具,AI 就能建表 / 建菜单 / 查数据。 架构与设计动机见
PLAN.md§6;本文只讲怎么接、怎么用、踩过什么坑。
1. 30 秒接入
# 确认二进制在
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,或客户端对应的配置文件):
{
"mcpServers": {
"sspf": {
"command": "/绝对路径/ssw-platform",
"args": ["--mcp"],
"env": {
"PGLITE_DIR": "/绝对路径/数据目录/lite.pg"
}
}
}
}
🔴 PGLITE_DIR 必须写绝对路径:MCP 客户端启动子进程时 cwd 不确定,
相对路径会把库建到奇怪的地方(默认值依赖「从可执行文件向上找锚点」,MCP 下也不稳)。
想同时用浏览器看效果?
./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,而是正常返回里的结构化结果:
{
"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…) → 裁掉
形状不统一时,对账每一条都是差异,看不出业务问题。
# 探针:用它打任意实现了契约的 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. 加一个业务工具的完整成本
- 在
crates/sspf-mcp/src/tools/mod.rs写一个ToolDef: schema + 注解 + 五段自提示(when_to_use / when_not_to_use / preconditions / pitfalls / examples) - 加进
ALL_TOOLS - 内核
mcp_adapter.rs的invoke()加同名分支(op==tool.id,刻意同名) cargo test -p sspf-mcp—— 元测试会校验 schema 合法、one_liner≤ 40 字、示例是合法 JSON、每个坑都有rationale
协议层、元工具、注册表都不用改。 这是分层加载的直接收益。