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

15 KiB
Raw Blame History

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. 加一个业务工具的完整成本

  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

协议层、元工具、注册表都不用改。 这是分层加载的直接收益。