- HANDOFF §1 现状:端点 376(面 B 346)/ tables 52 / 测试 550 / 官方覆盖 365-372 - HANDOFF 新增 §1「批次 11」小节:表名≠控制器名、enCode 前缀化(create 用 !=0、 update 用 ==1,delete 比对用带前缀的码)、conditionJson 三层结构、方案列表 只需登录、SYS020/SYS021、3 处诚实降级 - HANDOFF 新增「本批踩到并解决的 5 个真 bug」+ §5「批次 11 新增的坑」6 条 - HANDOFF §3 待办:划掉批次 11,补批次 12 指引(缺口 system 55 / permission 26 / systemData 32) - HANDOFF 修正「八道闸门」为「十二道闸门」(旧措辞与 CLAUDE.md 不一致) - PLAN 差距表:面 B 331 → 346,base_* 49 → 52 - CLAUDE.md:cargo test 545 → 550(两处写死值) - memory 日志追加批次 11 段落:结论 / 9 个坑 / 数字(均已复验)
54 KiB
PLAN —— 尚数网统一开发平台(SSPF)总体架构与路线
本文件回答 「做成什么、为什么这么做、怎么算做完」。
CLAUDE.md是红线与当前范围(随阶段滚动更新),本文件是长期架构基线,阶段推进时只改 §9 的勾。 术语:基线平台 = 兼容目标(现称 JNPF v7 的那套 Java 平台,代码/文档内统一叫baseline,不再出现原厂名)。
0. 一句话定位
SSPF = 尚数网企业统一开发平台:以「元数据驱动 + 契约兼容 + AI 原生接口」三层能力, 让业务系统从「写代码」变成「声明 + 验证」,并保证存量前端/移动端/数据库零改动平滑接管。
三层价值,缺一不可:
| 层 | 是什么 | 为什么必须有 |
|---|---|---|
| 兼容层 | 逐字对齐基线平台的 HTTP 契约、base_* DDL、口令算法、响应信封 |
前端/移动端/存量库不动,才有「切换」而不是「重做」 |
| 元数据层 | 表/模型/表单/菜单/流程/权限全部是库里的数据,引擎解释执行 | 这才是「低代码」;也是「后续开发不用编译」的唯一干净实现 |
| AI 接口层 | MCP 2.0 元工具 + 自提示 + 分层加载 | 让 AI 成为第一开发者,而不是让人去点 20 个页面 |
1. 目标分解(三条时间线,别混)
| 时间线 | 目标 | 可验收的判据 | 依赖 |
|---|---|---|---|
| N(现在–Q1) | 提高基线平台开发速度 / 降低环境要求 | ① 同一需求 AI 交付耗时 ↓50% ② 部署从「Java+Redis+Nacos+DB」降到「单二进制 + 内嵌 PG」 | 轨道 A + B 并行 |
| M(Q1–Q2) | 完全稳定 / 行为一致后切换 Rust 版 | 影子对账 P0 差异 = 0;同一前端在两个后端跑同一套 E2E 全绿 | 轨道 B |
| L(Q2+) | 人 + AI 高效协作开发 | 业务需求从「提给开发」变成「对话产出 + 自动验证 + 可回滚」 | 轨道 A 成熟 |
1.1 🔴 关键:拆成两条轨道并行,不要串行
轨道 A(AI 工具面) ── 架在【现有 Java 后端】上,立刻可用 ──▶ 提速
│
│ 同一套 MCP 工具契约,后端实现可替换
▼
轨道 B(Rust 内核) ── 逐条迁契约,影子对账 ──▶ 降环境、去 Java ──▶ 切换
理由:基线平台的开发速度瓶颈不在 Java 运行时,而在「人/ AI 要理解平台、记住 50 个坑、点 20 个页面」。 dacli 的 4.7 万行 TypeScript 全部在解决这件事 —— 这证明「工具面」是可以独立于「后端实现」交付的价值。 反过来,如果先做 Rust 内核再想工具面,提速目标会被内核进度绑死半年。
架构保证:MCP 层只依赖 PlatformAdapter trait,不认具体后端。
// crates/sspf-mcp/src/adapter.rs
#[async_trait]
pub trait PlatformAdapter: Send + Sync {
async fn call(&self, op: &str, args: Value) -> Result<Value, ApiError>;
async fn describe_env(&self) -> EnvInfo; // app_code / system / db / 版本
}
// 两个实现:
// JnpfHttpAdapter —— 打现有 Java 后端(HTTP),P1 就能用
// SspfNativeAdapter —— 进程内直调 kernel,P4 切换
// 工具契约、自提示、返回形状,两边完全一致。
2. 五条核心判断(都会影响后续所有设计)
判断 ①:不改前端 ⇒ 「低代码引擎」在后端只是「元数据服务 + 动态数据路由」
基线平台的低代码渲染器在前端(Vue 的 FormGenerator 解释表单 JSON)。既然不迁前端, Rust 侧不需要重写渲染器,只需要三件事:
- 存取:
visualdev那套 JSON 原样存、原样取(同构,不改一个字段) - 动态 CRUD:给定
modelId→ 查元数据 → 解析出物理表/字段/权限 → 拼 SQL(零编译) - 发布/版本:表单草稿 → 发布 → 版本快照
⇒ 低代码引擎的工作量比直觉小一个量级,且天然满足「不编译」。这是第 8 条需求的落地点。
判断 ②:「不编译」有四级;动态库是必须项,不是可选项
Rust 没有稳定 ABI,cdylib 跨编译器版本会段错误。按「稳定性 × 成本」排序:
| 级 | 机制 | 编译 | 适用 | 风险 |
|---|---|---|---|---|
| L0 元数据 | 表单/模型/菜单/流程/权限 = 库里的 JSON | 零 | 80% 的业务 | 无 |
| L1 表达式 | Rhai 求值(受限宿主 API + 资源上限) | 零 | 15% 的业务(业务规则) | 低(沙箱化) |
| L2 静态 crate | packs/<app>/src 编成 rlib,链进内核 |
只编业务 crate(~30s) | 4% 的业务(外部集成、复杂算法) | 无 |
| L3 动态库 | cdylib + libloading,plugins/*.dylib 启动扫描 |
独立编、热替换 | 必须支持(见 §4.5) | 🟡 中(靠 ABI 契约 + 工具链锁定压住) |
L3 是硬需求,理由是终端产品形态:客户现场要能单独替换/升级某个业务能力,不能等整包发版。 代价必须用工程手段压住,而不是回避:
- 工具链锁死
1.95.0(rust-toolchain.toml+pack.toml的[pack.build].toolchain,CI 双向校验) - ABI 只暴露 4 个 C 函数,其余全部走 JSON(见 §4.5)
- 装载失败不能拖垮内核:版本不匹配直接拒载;
catch_unwind+ 独立线程兜底 - 热替换必须显式:
sspf plugin reload <name>,不做自动监控(自动热更 = 状态迁移地狱)
WASM 保留为 L3 的并行选项(不是替代):沙箱隔离更彻底,适合「AI 生成的业务逻辑先试跑」。
判断 ③:双向迁移的本质是「业务包格式」,不是「转换工具」
要做 jnpf ⇄ sspf 无缝,靠的不是写两个转换器,而是一个两边都能读的中间格式(见 §5)。
格式定得早,迁移就是打包/解包;定得晚,就是重写。
判断 ④:MCP 2.0 的胜负手是 token 预算,不是工具数量
200 个工具全量注册 ⇒ 光 schema 约 6 万 token,AI 直接被淹。 必须做 L0 常驻 4 个元工具 + L1 分类索引 + L2 按需 describe(见 §6)。 这与当前主流 agent 的「工具搜索 / 延迟加载」范式一致。
注:「MCP 2.0」是本项目的工具层架构代号,不是协议版本号。 协议侧按官方最新 spec 实现(
2025-06-18/2025-11-25:outputSchema、structuredContent、resources、prompts、elicitation、tool annotations、Streamable HTTP)。
判断 ⑤:以「前端是否依赖」划界,不依赖的全改
「去掉原厂字眼」与「契约一致」的冲突,用一条判据解决: 前端 / 移动端 / 存量数据库会读到的字符串,一个字不改;读不到的,全改。(细化见 §7) 改错层的后果是前端全挂。
判断 ⑥:内存是一级设计约束,不是优化项 🔴
产品形态:尚数网的连接器是终端产品(客户现场 / 一体机 / 边缘节点),不是机房里的中台。 完整 Java 版基线平台在目标硬件上跑不动;勉强起来之后,也没有余量再跑业务、跑沙箱、跑计算。
这一条把 Rust 版的性质改了:
| 原来的假设 | 修正后 |
|---|---|
| Rust 版是「稳定后切换」的优化项 | Rust 版是唯一可部署形态,是产品可行性的前置条件 |
| 轨道 B 可以慢慢来 | 轨道 B 的内存指标从 P0 就要进闸门,不能等 P5 |
| 沙箱/计算是后期增强 | 沙箱/计算是终端产品的卖点,架构必须从 P0 预留执行器位置 |
内存预算(进 P0 出口判据,scripts/mem-budget.sh 可执行):
| 场景 | 目标常驻 | 实测(2026-10-31) | 说明 |
|---|---|---|---|
| 空载(内核 + 空库 21 表) | ≤ 40 MB | 7 MB ✅ | 单二进制,strip 后静态链接;vmmap Physical footprint |
| 典型(20 表 / 1 万行 / 10 并发) | ≤ 120 MB | 待压测 | pglite 共享缓冲 + 会话表 |
| 峰值(导入导出 / 报表) | ≤ 256 MB | 待压测 | 必须流式,禁止整表载入 |
| 沙箱单实例 | ≤ 64 MB(可配) | 待 P3 | 超限即杀,不拖累主进程 |
| 对照:Java 全套 | 2–4 GB | — | JVM + Spring + Redis + Nacos |
🔴 7 MB 这个数字是终端产品可行性的第一份硬证据 —— 同一个业务契约, Java 栈要 2–4 GB,Rust 栈空载 7 MB。它同时说明:内存预算的风险不在「做不到」, 而在「后续不加约束地长胖」(无界缓存、整表载入、每请求 clone 大对象)。所以 MEM1/MEM2 进闸门。
四条内存红线(写进 check-arch.sh):
- 禁止
SELECT *全表读进Vec—— 导出/报表一律游标流式 - 禁止无界缓存(所有缓存必须有
max_entries+ LRU 淘汰) - 每个限额必须有默认值 + 可配,不许「不配就无限」
- 沙箱/计算必须能独立限额并强杀,不影响主进程存活
判断 ⑦:执行器(沙箱 + 计算)从 P0 预留位置,P3 落地
终端产品要跑的不只是 CRUD。架构上预留三个执行层,共享同一套资源限额:
| 执行器 | 用途 | 隔离级别 | 落地阶段 |
|---|---|---|---|
| 表达式(Rhai) | 字段校验/计算/联动 | 同进程,操作数上限 + 深度上限 | P2 |
| WASM 沙箱 | AI 生成的业务逻辑、第三方脚本 | 同进程独立内存,fuel 计量 | P3 |
| 进程沙箱 | 重计算 / 不可信代码 / 调用外部 CLI | 独立进程,cgroup/Job 限额,可强杀 | P4 |
🔴 三者共用 Executor trait,不许各写一套限额逻辑。
3. 架构
3.1 总图
┌──────────────────────────────────────────────────────────────────────┐
│ AI 客户端:Claude Code / Cursor / WorkBuddy / 自研 Agent │
└──────────────────────────┬───────────────────────────────────────────┘
│ MCP(stdio 本地 / Streamable HTTP 团队共享)
┌──────────────────────────▼───────────────────────────────────────────┐
│ sspf-mcp ── 元工具层(常驻 4 个,schema < 2K token) │
│ sspf_context 环境与工程上下文 │
│ sspf_discover 意图 → 工具/资源索引(L1 分类) │
│ sspf_describe 工具 → 完整 schema + 自提示(L2,含 pitfalls) │
│ sspf_call 统一执行(结构化返回 + next_actions) │
│ │
│ 唯一知识源 registry ──▶ 派生 tool schema / 文档 / 校验器 / CI 用例 │
└──────────────────────────┬───────────────────────────────────────────┘
│ trait PlatformAdapter(后端可替换)
┌────────────────┴─────────────────┐
▼ ▼
┌──────────────────┐ ┌──────────────────────────────────────┐
│ JnpfHttpAdapter │ │ SspfNativeAdapter │
│ 打现有 Java 后端 │ │ 进程内直调 │
└────────┬─────────┘ └──────────────┬───────────────────────┘
│ │
┌────────▼─────────┐ ┌──────────────▼───────────────────────┐
│ 基线平台(Java) │ │ sspf-kernel(单二进制) │
│ 现状,存量资产 │ │ ├ contract 信封/错误码/契约类型 │
└──────────────────┘ │ ├ auth cipher/session/guard │
│ ├ permission 四源合并 │
│ ├ lowcode 元数据引擎(解释型) │
│ ├ store pglite ⇄ 真实 PG │
│ └ plugin 业务包加载器(L0–L3) │
└──────────────┬───────────────────────┘
│
┌──────────────▼───────────────────────┐
│ packs/<app>/ ── 业务包(整目录可搬) │
│ ├ pack.toml 清单/兼容区间 │
│ ├ schema/*.sql DDL(f_ 前缀) │
│ ├ meta/*.json 表单/模型/菜单/流程 │
│ ├ src/ 可选:Rust 业务逻辑 │
│ └ tests/ 契约测试(两边都能跑) │
└──────────────────────────────────────┘
3.2 目录重构(从单 crate → workspace 多 crate)
现状是 src/backend 单 crate(1.6 万行)。要满足「内核不编译、业务可搬」,必须拆:
ssw-platform/
├── crates/
│ ├── sspf-contract/ # 契约类型:ActionResult / EntitySpec / MenuSpec / 错误码 / 码表
│ ├── sspf-sdk/ # 🔴 业务包唯一依赖。只含 trait + 数据类型,依赖仅 serde
│ ├── sspf-store/ # DB 抽象:pglite 后端 + 真实 PG 后端
│ ├── sspf-auth/ # cipher / session / guard
│ ├── sspf-permission/ # 四源合并 + 管理员短路 + 菜单树
│ ├── sspf-lowcode/ # 元数据引擎:form/model/menu/flow + 动态 CRUD
│ ├── sspf-plugin/ # 业务包加载器:静态注册 / dylib / wasm(后两者可选 feature)
│ ├── sspf-kernel/ # 启动装配 + 路由挂载(bin 目标)
│ └── sspf-mcp/ # MCP 服务 + registry + 4 元工具 + adapter
├── packs/ # 🔴 业务包,只依赖 sspf-sdk
│ ├── asset/
│ └── ...
├── tools/
│ ├── diff-harness/ # 影子对账(§8)
│ ├── pack-cli/ # pack 导入导出
│ └── gates/ # 六道闸门(从 scripts/ 迁入,保持可独立跑)
├── web/ # 复用基线平台前端(不改)
└── docs/
拆分纪律(已实现为 scripts/check-arch.sh,--self-test 会造违规反自证):
| 规则 | 内容 | 违反后果 |
|---|---|---|
| AR1 | sspf-sdk 依赖只能是 sspf-contract |
业务包被框架绑架,不可搬 |
| AR2 | packs/* 依赖 ⊆ {sspf-sdk, serde} |
同上 |
| AR3 | sspf-contract 不许 use axum/tokio/pglite/sqlx |
契约层有 IO ⇒ 业务包再也不「轻」 |
| AR4 | sspf-contract 依赖 ⊆ {serde, serde_json, uuid, http} |
同上 |
| AR5 | sspf-mcp 依赖 ⊆ {sspf-contract, serde, serde_json} |
无法同时接「进程内内核」与「远端 Java 后端」 |
| MEM1 | 非注释代码不许 SELECT * |
整表读进 Vec ⇒ 直接超内存预算 |
| MEM2 | 缓存必须有 MAX_* / CAPACITY_* 上限常量 |
无界缓存 = 慢性内存泄漏 |
3.3 现状 vs 目标(差距表)
| 能力 | 现状 | 目标 | 差距 |
|---|---|---|---|
| 面 B 契约端点 | ✅ 346 条(2026-11-01 批次 11 收尾) | 全量(含 lowcode/flow/file/message) | 官方端点覆盖 365/372;余下多为「本仓没这个模块」 |
base_* DDL |
✅ 52 张逐字对齐 | 全量 331 张中的必需集 | 按域补 |
| 平台/业务分层 | ✅ check-boundary.sh 钉住 |
升级为 crate 级隔离 | P0 已拆 contract / store / sdk;asset 包可独立编译;jnpf.rs→face_b.rs |
| 低代码元数据引擎 | ✅ P2-b 完成:解析 + 校验 + 建表 + 动态 CRUD(6 个工具) | visualdev 同构 + 动态 CRUD + 发布 | 读 release / 单据号 / 乐观锁 → P2-c |
| 业务包格式 | 🟡 pack.toml 已定稿、packs/asset 已有样板 |
导入导出工具 | P3 |
| MCP 工具面 | 🟡 P1 主体完成:4 元工具 + registry + 分层加载 + 双适配器 + 26 个业务工具 + 3 个流程模板 | 约 55 个业务工具(补 model/workflow/release) | P1 收尾 |
| 影子对账 | ❌ 无 | 语料库 + 归一化比对 | 全新,P4 |
| 部署形态 | 🟡 pglite 单二进制 | 单二进制 + 可选真实 PG | P5 收口 |
4. 动态加载机制(第 8 条落地)
4.1 业务实现四级(先判级,再动手)
写业务前先回答一个问题:这件事能不能只用数据描述?
需要新的业务能力
│
├─ 只是增删改查 + 表单 + 菜单 + 权限? ──────────▶ L0 元数据(零代码、零编译)
│
├─ 有校验/计算/联动/显隐等规则? ────────────────▶ L1 表达式(零编译)
│
├─ 要调外部系统 / 复杂算法 / 事务编排? ─────────▶ L2 业务 crate(编 30s)
│
└─ 需要独立发版、热替换、多团队并行? ───────────▶ L3 动态库(编 + 装载)
比例目标:L0+L1 ≥ 90%,L2 ≤ 9%,L3 ≤ 1%。达不到说明元数据层设计不足,而不是业务太复杂。
4.2 L0:元数据(真正的「不编译」)
引擎能力清单(sspf-lowcode):
| 能力 | 输入 | 行为 |
|---|---|---|
| 实体/表 | EntitySpec(列 + 类型 + 索引) |
建表 / 迁移(幂等) |
| 模型 | 模型 JSON(字段 + 关联 + 数据源) | 注册 + 动态解析 |
| 表单 | 表单 JSON(与基线平台同构) | 存取 + 发布 + 版本 |
| 菜单 | 菜单声明 | upsert 到 base_module + 授权 |
| 流程 | 流程 JSON(BPMN 子集) | 存取 + 节点绑定表单 |
| 数据 | modelId + 查询条件 |
动态拼 SQL(列白名单,非字符串拼接) |
🔴 动态 CRUD 的安全铁律:所有列名/表名只能来自元数据白名单,绝不接受请求体里的标识符。 这条比「参数化查询」更严 —— 参数化防值注入,白名单防结构注入。
4.3 L1:表达式 —— 用 Rhai,但必须沙箱化
选型:Rhai(成熟、纯 Rust、无 GC、可完全禁用危险能力)。 不自研求值器 —— 类型系统、字符串、正则、闭包这些特性自己写会变成长期负债; 业务方要的表达式能力一定会超出最初设想。
Rhai 的能力默认全关,只开白名单:
| 配置项 | 值 | 理由 |
|---|---|---|
eval |
禁用 | Rhai 的 eval 是元编程入口,等于开后门 |
| IO / 文件 / 网络 | 禁用 | 一律不注册 |
import / 模块加载 |
禁用 | 防跨脚本注入 |
| 时钟 | 只读 + 固定时区 | 可复现;不许拿来做限流 |
| 宿主函数 | 白名单注册 | 只有 lookup() / len() / matches() / hasRole() / now() / today() / coalesce() |
资源限额(缺一不可,全部可配 + 有默认):
| 限额 | 默认 | 作用 |
|---|---|---|
max_operations |
10,000 | 防长计算 / 死循环 |
max_expr_depths |
32 | 防深度炸弹 |
max_call_levels |
16 | 防递归 |
| 执行超时 | 50 ms | 兜底(operations 之外的阻塞) |
| 返回 / 中间值大小 | 64 KB | 防内存炸 |
四条实现约定:
- 编译一次,缓存 AST:
Engine::compile→AST,按表达式源 + 版本哈希缓存(有上限,LRU) - 表达式存元数据表 ⇒ 改规则 = 改数据 = 零编译
- 错误必须可读:
EvalAltResult要映射成「哪个字段 / 哪一行 / 期望什么」,不能把 Rhai 原始错误直接抛给业务 - 每次求值独立
Scope,不许跨请求共享变量(防串数据与越权读)
示例(业务方写的就是这个):
len(fullName) <= 50 && matches(code, "^[A-Z]{2}\\d{4}$")
amount * (1 + taxRate)
status == "draft" && hasRole("finance")
lookup("customer", customerId, "creditLimit") >= amount
4.4 L2:业务 crate(默认的「写代码」形态)
// packs/asset/src/lib.rs
//! 业务包唯一入口。依赖只有 sspf-sdk(+ serde)。
use sspf_sdk::{BusinessPack, Manifest, EntitySpec, MenuSpec, MetadataDoc, Result};
pub struct AssetPack;
impl BusinessPack for AssetPack {
fn manifest(&self) -> &Manifest {
&Manifest { app_code: "asset", name: "数据资源", version: "1.0.0" }
}
fn entities(&self) -> &[EntitySpec] { &[DATA_RESOURCE] }
fn menus(&self) -> &[MenuSpec] { &[DATA_RESOURCE_MENU] }
// 需要时再实现 routes() / hooks();L0 包一个都不用实现
}
// 注册(唯一接线点,不进内核)
sspf_sdk::register!(AssetPack);
内核侧:
// crates/sspf-kernel/src/main.rs —— 内核里唯一的「业务知识」
let packs: Vec<Box<dyn BusinessPack>> = vec![
Box::new(asset::AssetPack), // ← 加业务包只改这一行
];
🔴 这一行是唯一允许出现业务名的地方,由 check-arch.sh 白名单钉住。
4.5 L3:动态库(必做,feature dylib)
为什么手写 C ABI,而不用 abi_stable
业务插件的交互本来就是「收一个 JSON、返回一个 JSON」,不需要跨 ABI 传复杂类型。
C ABI + JSON 的调试成本最低(ctypes / dlopen 直接能测),而 abi_stable 要求业务方
把所有类型标注 StableAbi,学习成本与耦合度都更高。
⇒ 边界只有 JSON 字符串 + 6 个函数。
ABI 契约(v1,改动即升版本)
// 插件侧(每个业务 cdylib 必须导出,符号名固定)
#[no_mangle] pub extern "C" fn sspf_abi_version() -> u32; // 必须返回 1
#[no_mangle] pub extern "C" fn sspf_build_info() -> *mut c_char; // JSON: {rustc, profile, pack}
#[no_mangle] pub extern "C" fn sspf_init(ctx: *const c_char) -> *mut c_char; // 入参 JSON,返 handle 或 err
#[no_mangle] pub extern "C" fn sspf_invoke(handle: *const c_char, op: *const c_char,
args: *const c_char) -> *mut c_char;
#[no_mangle] pub extern "C" fn sspf_shutdown(handle: *const c_char) -> *mut c_char;
#[no_mangle] pub extern "C" fn sspf_free(ptr: *mut c_char); // 🔴 谁分配谁释放
六条铁律
| # | 铁律 | 不做的后果 |
|---|---|---|
| 1 | 内存所有权单向:插件分配的字符串必须由插件的 sspf_free 释放,内核只用不 free |
跨 allocator free ⇒ 堆破坏 / 随机崩溃 |
| 2 | 所有调用 catch_unwind:插件 panic 转成 {ok:false,error} JSON |
panic 跨 FFI 是 UB ⇒ 主进程直接死 |
| 3 | ABI 版本不匹配直接拒载,不尝试兼容 | 静默错位读写 ⇒ 最难查的一类 bug |
| 4 | 构建信息必须校验:ABI 版本 + rustc 版本 + panic 策略 三者全对才加载 |
换工具链重编的插件混进来 ⇒ 段错误 |
| 5 | 热替换前先排空:引用计数归零才 dlclose;dlclose 后复制到新路径再 dlopen |
同 inode 重载会拿到旧句柄 ⇒ "改了没生效" |
| 6 | 插件崩溃不能拖垮内核:可选 --plugin-isolation=process(子进程 + IPC) |
一个坏插件等于整站宕机 |
工具链锁定
# rust-toolchain.toml(仓库根,全仓生效)
[toolchain]
channel = "1.95.0"
components = ["rustfmt", "clippy"]
profile = "minimal"
pack.toml 的 [pack.build] 必须写同一版本,CI 双向校验:
ACTUAL=$(rustc --version | awk '{print $2}')
[ "$ACTUAL" = "1.95.0" ] || { echo "工具链漂移: $ACTUAL != 1.95.0"; exit 1; }
# 插件侧:读 build_info 里的 rustc 字段,与 manifest 声明比对
为什么是 1.95.0 而不是最新 stable:锁版本的意义是全仓可复现 + 插件 ABI 一致, 不是追新。1.95.0 是本机既有版本,立即可用;1.99.1 下载受本机代理限速(6 MB 卡死)。 要升级时按 §4.5 的四步走(改文件 → 全仓重编 → 插件全部重发 → 同步 pack.toml)。
🔴 panic = "abort" 绝对禁止(workspace 根 Cargo.toml 已有此注记):
abort 下 catch_unwind 抓不到 panic,铁律 2 直接失效。
装载流程
启动扫描 plugins/*/manifest.toml
│
├─ 读 build_info → 校验 ABI / rustc / profile ──✗──▶ 拒载 + 记 ERROR(不退出)
├─ dlopen(RTLD_NOW | RTLD_LOCAL) ──✗──▶ 拒载 + 记 ERROR
├─ sspf_init(ctx) → handle 或 err ──✗──▶ sspf_shutdown + 拒载
└─ 注册到 plugin registry(op → handler)
降级原则:插件加载失败 ⇒ 该插件提供的 op 返回 PLUGIN_UNAVAILABLE,
其余功能照常。内核绝不因为插件问题拒绝启动。
4.6 「链接就好」的准确含义(这段是给未来的自己看的)
| 说法 | 准确含义 |
|---|---|
| 「低代码不用编译」 | ✅ 真的。元数据在库里,改数据即生效 |
| 「内核不用编译」 | ✅ 加业务包时不用。加平台能力(新契约面/新存储)时仍要编,但频率极低 |
| 「业务链接就好」 | 🟡 L2 是静态链接(cargo build 30s,增量更快),L3 才是运行期 dlopen |
| 「热更新」 | ⚠️ 只有 L0/L1 是热的;L2 要重启进程;L3 要 dlopen + 状态迁移 |
不要对外承诺「什么都能热更」—— 会被 L2 打脸。
5. 业务包与双向迁移(第 8 条后半)
5.1 pack.toml
[pack]
app_code = "asset"
name = "数据资源"
version = "1.0.0"
kernel = ">=0.4,<0.5" # 内核兼容区间(不匹配则拒载)
migratable = true # 允许导出到基线平台
[pack.compat]
baseline = "v7" # 兼容基线版本
frontend = "vue3" # 前端族(决定表单 JSON 方言)
tenant = false # 本期单租户
[[pack.tables]]
name = "asset_data_resource"
ddl = "schema/001_init.sql"
baseline_table = "asset_data_resource" # 基线平台上的表名(允许不同,导出时映射)
[pack.metadata]
forms = ["meta/forms/data_resource.json"]
models = ["meta/models/data_resource.json"]
menus = ["meta/menus.json"]
flows = []
[pack.build] # 仅 L2/L3 需要
kind = "static" # static | dylib | wasm
toolchain = "1.85" # L3 必填,用于 ABI 校验
5.2 迁移 = 打包 / 解包,不是重写
sspf pack export asset --format=baseline --out=/tmp/asset.jnpfpack
# 产出:DDL(转基线方言) + visualdev JSON(字段名对齐) + 菜单/授权 SQL + 导入脚本
sspf pack import /tmp/asset.jnpfpack --format=baseline
# 读基线平台导出的包 → 归一化成 sspf pack → 落库 + 注册
对齐点(这四条对了,迁移就是搬箱子):
| 对齐项 | 规则 |
|---|---|
| 物理表 | 列名 f_ 前缀 + f_id VARCHAR(50) + 软删列;导出时若基线侧表名不同,用 baseline_table 映射 |
| 表单 JSON | 与基线平台 visualdev 同构,一个字段都不改(前端要靠它渲染) |
| 菜单 | f_url_address / f_en_code / f_system_id 三列语义一致 |
| 权限 | base_authorize 的 f_object_type + f_item_type 取值一致 |
🔴 反向迁移的坑:基线平台的口令是 md5(lower(md5(pwd)) + lower(secretkey)),
SSPF 侧若用简化式,导出时必须做一次换算(MIGRATION.md §7 已记录,单向、先备份)。
5.3 业务包的可搬性验收
一个包算合格,必须能过这条:
# 1) 独立构建(不依赖内核源码)
cd packs/asset && cargo build --target-dir /tmp/asset-build
# 2) 依赖审计:只能有 sspf-sdk + serde
cargo tree -p asset --depth 1 | grep -v "sspf-sdk\|serde" && exit 1
# 3) 导出 → 导入往返(幂等)
sspf pack export asset --format=baseline --out=/tmp/a.pack
sspf pack import /tmp/a.pack --target=/tmp/fresh-db
sspf verify contract --db=/tmp/fresh-db # 必须全绿
6. MCP 2.0:自提示 + 分层加载(第 6 条落地)
6.1 为什么不能「一个能力一个工具」
| 方案 | 常驻 token | 问题 |
|---|---|---|
| 全量注册 60 个工具 | ~18K | 还没干活就烧掉 1/6 上下文 |
| 全量注册 200 个工具 | ~60K | 直接废掉 |
| L0 + L1 + L2 按需 | ~1.8K 常驻,峰值 ~5K | 需要多一次 discover/describe 往返 |
6.2 L0:常驻四件套(协议层只注册这四个)
| 工具 | 入参 | 返回 | 作用 |
|---|---|---|---|
sspf_context |
scope: project|user|db|env |
{app, system, user, db, version, entities[], capabilities[]} |
会话第一步;后续工具的默认上下文 |
sspf_discover |
query?, category?, limit=10 |
[{id, title, one_liner, category, mutates, cost}] |
意图 → 工具索引;不带 query 返回分类树 |
sspf_describe |
tool_id, level=brief|full|pitfalls |
{schema, hints{...}, examples[], related[]} |
取完整 schema + 自提示 |
sspf_call |
tool_id, args, dry_run? |
{ok, data, effects[], next_actions[], hints[]} |
统一执行 |
为什么 describe 和 call 要分开:AI 可以先 dry_run + 看 pitfalls 再决定要不要真跑;
也允许「describe 一次、call 多次」,省掉重复 schema 成本。
6.3 L1/L2:工具分类(约 55 个,分 12 域)
| 域 | 工具(id) | 说明 |
|---|---|---|
context |
context.get context.set_app |
应用/系统切换 |
schema |
schema.table.create schema.table.list schema.table.describe schema.table.migrate |
物理表 |
model |
model.create model.update model.list model.describe |
数据模型 |
form |
form.create form.update form.release form.preview form.list form.export form.import |
低代码表单 |
menu |
menu.create menu.tree menu.update menu.delete |
菜单 |
permission |
perm.authorize perm.role.create perm.user.create perm.check perm.group.* |
权限 |
dict |
dict.type.upsert dict.data.upsert dict.list dict.resolve |
字典 |
data |
data.query data.insert data.update data.delete data.import |
通用数据 |
workflow |
flow.create flow.bind flow.publish flow.start flow.status |
流程 |
verify |
verify.gates verify.contract verify.smoke verify.diff |
验证(🔴 只读) |
release |
release.build release.deploy release.rollback |
发布 |
ops |
ops.health ops.logs ops.db.dump ops.db.restore |
运维 |
6.4 自提示:工具自带「坑」,不靠文档
每个工具必须提供五段(缺一段 CI 红):
pub struct Hints {
when_to_use: &'static [&'static str], // 什么场景用
when_not_to_use: &'static [&'static str], // 什么场景别用(防误用)
preconditions: &'static [&'static str], // 前置(如「先 context 拿 dbLinkId」)
pitfalls: &'static [Pitfall], // ❌ wrong / ✅ right / 为什么 / P0-P2
examples: &'static [Example], // 🔴 必须能被 CI dry_run 跑通
}
实际渲染效果(sspf_describe("form.create", level="pitfalls")):
{
"tool_id": "form.create",
"hints": {
"preconditions": ["先调 sspf_context 取 dbLinkId;为空会导致表单挂在默认库"],
"pitfalls": [
{
"severity": "P0",
"wrong": "字段名用 f_user_id 且 jnpfKey=inputNumber",
"right": "jnpfKey=relationForm + modelId=关联表单 id",
"rationale": "关联字段若用 inputNumber,前端渲染不报错但保存时外键为空,列表页显示空白。"
},
{
"severity": "P1",
"wrong": "enCode 带连字符 registration-form",
"right": "registration_form(自动 strip,但会多一条修正记录)",
"rationale": "物理列名不支持连字符;strip 后与前端路由不一致会导致菜单 404。"
}
],
"examples": [
{ "args": { "enCode": "asset_ledger", "fields": [] }, "note": "最小可用调用" }
]
}
}
自提示的三条铁律:
- 单一真值源:
registry里写一次,派生 tool schema /describe输出 / 静态文档 / CI 用例 - examples 必须可执行:CI 对每个 example 跑
dry_run,跑不通 = 构建失败(防文档腐烂) - 失败即教学:错误返回必须带
hints[] + next_actions[] + doc_ref,让 AI 一次就能自纠
6.5 失败返回的形状(比成功更重要)
{
"ok": false,
"error": {
"code": "FORM_ENCODE_EXISTS",
"message": "enCode 已存在:asset_ledger",
"field": "enCode",
"retryable": false
},
"hints": [
{ "level": "fix", "text": "换一个 enCode,或对已有表单调用 form.update", "auto_fixable": false }
],
"next_actions": [
{ "tool": "form.list", "args": { "keyword": "asset_ledger" }, "why": "先确认是否同一个表单" }
],
"doc": "sspf://errors#FORM_ENCODE_EXISTS"
}
6.6 Resources / Prompts / 协议特性
Resources(按需 resources/read,不占常驻上下文):
| URI | 内容 |
|---|---|
sspf://contract/endpoints |
契约端点表(机器可读) |
sspf://ddl/base |
base_* DDL |
sspf://docs/module-howto |
加业务模块指南 |
sspf://registry/tools |
全量工具索引(离线用) |
sspf://pack/{app} |
业务包清单与迁移状态 |
sspf://errors |
错误码字典 |
Prompts(把多步流程固化成可复用模板):
| prompt | 作用 |
|---|---|
new_business_module |
加业务模块(含 5 个 elicitation 追问) |
migrate_from_baseline |
从基线平台导入 |
verify_all |
跑全部闸门 + 出报告 |
diagnose_500 |
按错误码定位 |
协议特性使用:
outputSchema+structuredContent:返回强类型,AI 不用解析文本annotations:readOnlyHint(verify/context 全只读)、destructiveHint(delete/restore)、idempotentHint(upsert)elicitation:缺关键信息时反向问用户(不要瞎猜)Streamable HTTP:团队共享一个 MCP 实例;本地 stdio 给单人
6.7 验收判据
一个「AI 能独立完成」的闭环,必须全绿:
自然语言需求
→ sspf_context(拿 app/db)
→ sspf_discover("建一个带审批的报销单")
→ sspf_describe("form.create", pitfalls)
→ sspf_call("schema.table.create") ← dry_run 先看 DDL
→ sspf_call("form.create")
→ sspf_call("menu.create")
→ sspf_call("perm.authorize")
→ sspf_call("form.release")
→ sspf_call("verify.gates") ← 必须全绿
→ 前端页面可打开、可增删改查
任一步失败,AI 必须能靠 hints + next_actions 自纠,不需要人介入。 这是 MCP 层的唯一 KPI。
7. 契约与命名(第 7 条落地)
7.1 唯一判据:前端 / 移动端 / 存量库是否「依赖」它
「依赖」的严格定义:拿它做判断、查找、拼路径、解析、判分支。 只是「显示给人看」的不算依赖。
| 类别 | 举例 | 处理 |
|---|---|---|
| 结构性字符串(前端用它做逻辑) | HTTP 路径 /api/permission/Users、响应键名 data.list、请求头 Vue-Version: 3/App-Code/Jnpf-Origin、错误码 602、枚举值(f_type 的 1/2、f_is_system 的 1/2)、菜单 urlAddress/enCode、表单 JSON 的 jnpfKey、cipher key 字面量 |
❌ 一个字都不改 |
| 数据库标识(存量库迁移依赖) | 表名 base_user、列名 f_id/f_en_code |
❌ 一个字都不改 |
| 展示性文案(前端只渲染,不判断) | msg 里的中文提示、日志、注释、README |
✅ 全改(语义一致即可) |
| 内部标识(前端完全读不到) | crate 名、模块名、类型名、函数名、变量名、文件名 | ✅ 全改 |
🔴 这条判据解释了两个容易吵的点:
jnpfKey必须保留 —— 它出现在表单 JSON 里,前端componentMap.ts靠它选组件。 改了就白屏。名字难看也得留。msg可以改 —— 前端只是message.error(res.msg),不解析内容。 但语义不能变("用户名已存在" 不能改成 "操作失败")。
统一用词(仅用于「非结构性」位置):
| 场合 | 用词 |
|---|---|
| 代码标识符 | baseline(BaselineCompat、baseline_probe、crate::baseline) |
| 文档 | 基线平台(首次出现注明"兼容目标 v7") |
| 禁止 | jnpf / 引迈 / JNPF 出现在新增文件的标识符与文案里 |
7.2 check-naming.sh 的实现口径
不能简单 grep 关键词(会把契约字符串一起拦掉,改了就崩)。三层过滤:
第 1 层:豁免区(直接跳过,不检查)
docs/contract.md、db/schema.sql、src/**/routes.rs 里的路径字面量、
tests/**(断言要写真实路径)、任何 "..." 里被前端消费的常量白名单
第 2 层:必改区(出现即红)
*.rs / *.toml 里的 标识符(fn/struct/enum/mod/const/变量)、crate 名、注释
*.md 里的叙述文字(排除引用块与代码块中的契约示例)
第 3 层:人工复核区(黄灯,不阻断)
msg 文案、错误提示
实现建议:Rust 侧用 syn 解析取标识符(比正则可靠),文档侧用正则可接受。
🔴 白名单必须是「显式文件 + 行号」而非「关键词豁免」 —— 否则会漏。
7.3 规范一致的落地方式
「规范保持一致」不等于「代码长得一样」。真正要一致的是语义:
| 规范项 | 一致性要求 |
|---|---|
命名规范(f_ 前缀 / camelCase 键名 / 36 位 UUID) |
逐字一致 |
| 错误码语义 | 逐字一致(含 600/601/602 的用途区分) |
| 权限判据 | 两套并存(面 A 按菜单路径、面 B 按 f_en_code),语义各自一致 |
| 分层规范 | 一致,但用 Rust 的方式表达(crate 边界 + trait) |
| 提交/评审规范 | 沿用公司规范(dacli/docs/尚数网基本开发规范v3.0.md) |
8. 验证体系(「完全稳定/一致」怎么证明)
8.1 六道闸门 → 升级为八道
现状六道(静态 4 + 契约尺子 2)保留,新增两道:
| # | 闸门 | 测什么 | 何时跑 |
|---|---|---|---|
| 7 | check-arch.sh |
crate 边界 AR1–AR5 + 业务包依赖审计 | 每次提交 |
| 8 | diff-harness |
同一语料打两个后端,归一化比对 | 每日 + 发版前 |
8.2 影子对账(diff harness)
tools/diff-harness/
├── corpus/ # JSONL 语料,一条一个请求
│ ├── auth.jsonl # 登录/CurrentUser/过期/无权限
│ ├── crud.jsonl # 5 组 base_* 的增删改查 + 分页 + 搜索
│ ├── menu.jsonl # 菜单树/多应用隔离
│ ├── permission.jsonl # 授权写入/读取/四源合并
│ └── errors.jsonl # 错误码矩阵(400/403/500/600/602)
├── run.sh # 双打 + 落盘
├── normalize.py # 归一化(见下)
└── report.html # 按端点分组的差异报告
归一化规则(必须写死,否则天天误报):
| 类型 | 处理 |
|---|---|
| UUID / 主键 | → <id> |
| 时间戳 | → <ts>(保留"是否为空") |
| 列表顺序 | 按主键排序后再比 |
| 浮点/金额 | 转字符串比(防 9.9 vs 9.90) |
| 分页 total | 数据不同步时允许差,单独标 DATA_DRIFT 不算 P0 |
| 字段增删 | 基线有、SSPF 无 ⇒ P0;SSPF 多 ⇒ P2(前端不读就无害) |
分级与出口:
| 级别 | 定义 | 出口要求 |
|---|---|---|
| P0 | 字段缺失 / 类型不同 / 错误码不同 / 权限判定相反 | = 0 |
| P1 | 值不同(非 ID/时间)/ 排序不同 | ≤ 3 且每条有豁免记录 |
| P2 | 多返回字段 / 文案差异 | 不限 |
8.3 切换的三道门(缺一不可)
- 契约门:八道闸门全绿 + diff P0=0
- 体验门:同一前端 E2E(登录→菜单→5 个核心页 CRUD)在两个后端全绿
- 回滚门:切流开关能 30 秒内切回;数据双写/单向同步有对账脚本
9. 路线图
阶段出口判据 = 硬条件,不达标不进下一阶段。周期是量级参考,不是承诺。 🔴 P0 起每个阶段都要过内存门(§2 判断 ⑥ 的预算表)—— 终端产品形态下,内存超标等于不可交付。
P0 · 锁工具链、拆 crate(约 2 周)
| 项 | 内容 |
|---|---|
| 交付 | rust-toolchain.toml 锁 1.95.0;workspace 拆分(contract / store / sdk 已落地,kernel 原地待搬);sspf-sdk trait 定稿;pack.toml 定稿;check-arch.sh(AR1–AR5 + MEM1–MEM2);check-naming.sh(NM1–NM4);mem-budget.sh |
| 约束 | 行为零变化(九道闸门必须仍全绿) |
| 出口 | cargo build 通过;九闸绿;packs/asset 能独立构建;空载常驻 ≤ 40 MB 实测(已达 7 MB);内部标识零原厂名(NM1–NM3) |
| 风险 | 拆 crate 引入循环依赖(已定位:auth → jnpf 只有 is_jnpf + current_user 3 处,is_jnpf 下沉 contract、分流上移到路由层即可解开) |
P1 · MCP 2.0 骨架 + 基线适配器(约 4 周)
| 项 | 内容 |
|---|---|
| 交付 | sspf-mcp(4 元工具 + registry + discover/describe);BaselineHttpAdapter;首批 20 工具(context/form/menu/dict/permission/data);sspf:// resources |
| 价值 | 立刻可用:AI 通过 MCP 操作现有 Java 后端,开发速度提升先落地;同时充当 P4 对账的「参照侧」 |
| 出口 | §6.7 闭环全绿;单会话 token 峰值 < 8K;examples CI 全通过 |
| 风险 | 工具粒度设计反复 ⇒ 先按「一次调用 = 一个业务意图」定,别按 API 一一映射 |
P1 已完成(2026-10-31):
crates/sspf-mcp:协议(stdio NDJSON)+ registry + 4 元工具 + 五段自提示 + resourcesNativeAdapter(进程内,共用AppState)+--mcp子命令 +--mcp --with-http双形态- 业务工具 19 个:context(1) / schema(3) / menu(3) / permission(6) / dict(3) / data(2)
- 授权闭环:
authorize.grant/authorize.revoke/effective(四源并集 + 应用过滤两组数)user.create(建非管理员账号,让「授权是否真的生效」可验证)
- 多步模板 3 个:
new_business_module/diagnose_menu_not_visible/verify_all; 测试会核对模板里引用的工具 id 是否真实存在(防腐烂) BaselineHttpAdapter(crates/sspf-adapter-baseline):5 个只读 op 的端点映射- 形状归一化(
{code,msg,data:{list}}→ native 形状),P4 对账的前置件
- 形状归一化(
- 两道尺子:
mcp-smoke.sh32 条、baseline-smoke.sh10 条 - 接入说明见
docs/mcp.md
P1 待做:业务工具补到约 55 个(缺 form / model / workflow 三大域)、 基线适配器按对账需要扩展 op。
⚠️ 轨道 A 的定位要摆正:它是过渡期的开发加速器 + 对账基准,不是终态。 终端产品交付形态只有 Rust 版(判断 ⑥)。
P2 · 低代码元数据引擎 + Rhai 沙箱(约 6 周)
| 项 | 内容 |
|---|---|
| 交付 | sspf-lowcode:模型/表单/菜单/流程元数据 + 动态 CRUD + 发布版本;visualdev JSON 同构导入;sspf-expr(Rhai 沙箱,§4.3 全部限额);Executor trait 首版 |
| 出口 | 基线平台导出的表单 JSON,不改一个字段能在 SSPF 上渲染 + 存取;动态 CRUD 通过列白名单安全测试;Rhai 逃逸测试(eval/IO/递归/超深表达式)全部被拒 |
| 风险 | 表单 JSON 方言多(不同控件)⇒ 先覆盖 top 10 控件,其余降级 input |
P2 已完成(2026-10-31,第一波 P2-a):
crates/sspf-lowcode:form(控件树解析)/model(表结构解析)/widget(54 种 jnpfKey 分类) /validate(9 类诊断码),纯计算,38 个测试毫秒级跑完(AR7 钉住不许依赖 DB)- DDL:
base_visual_dev/base_visual_release进schema.sql,列与官方逐字一致(21 → 23 张表) - 真实样例落地为 fixture:官方初始化数据里的「应收费用」表单(主表 6 字段 / 子表 8 字段)
- MCP 工具 3 个(只读):
form.list/form.describe/form.validate;后两个支持 inline JSON (不用入库就能校验草稿) scripts/lowcode-smoke.sh8 条,含两条反自证:改坏__vModel__必须被抓、未知控件必须只 warn
第一波刻意没做的:动态 CRUD(写数据)、写表单定义。原因:写的前置是「解析 + 校验被真实数据验证透」, 否则等于让 AI 生成前端画不出来的 JSON。动态 CRUD 已在第二波补上,写表单定义仍未做。
P2-b 已完成(2026-10-31,第二波)—— 动态 CRUD 闭环:
sspf-lowcode::ddl:纯计算建表 DDL(类型映射 / 复合主键(f_id, f_tenant_id)/ 系统列 / 逻辑删除列)+rewrite_model(把真实列回写成f_tables_data的形态)- 内核
lowcode_ddl::create_and_sync:建表 → 回写f_tables_data(幂等;表已存在则跳过, 列不同报TABLE_EXISTS_DIFFERENT,不自动 ALTER) - 内核
lowcode_crud/lowcode_check:真实事务执行、子表差集对账、 落库前三重校验(单行唯一UNIQUE_CONSTRAINT_VIOLATED/ 业务主键组合唯一BUSINESS_KEY_VIOLATED/ 必填,失败一条 SQL 都不执行) - MCP 工具 4 个(写):
schema.table.create+data.record.insert/update/delete; 写工具默认dryRun=true(不传就是演练) - 开发期通道
--seed-lowcode-demo [--dry-run]:用官方 fixture 造一份可用的低代码功能 (固定enCode=receivableDemo,幂等;prod 档开库前拒绝;dry-run 连库都不开) scripts/mcp-smoke.sh扩到 48 条(M1–M47,其中阶段 B 用 python 动态驱动, 覆盖「演练不落库 → 真写 → 查证 → 子表差集 → 删除」)scripts/lowcode-smoke.sh扩到 15 条(L9–L14:类型映射 / 复合主键 / 逻辑删除列 / 系统列视图类型,含两条反自证)
P2-b 的关键判断(后续别改坏):
- 建表后必须回写
f_tables_data:不回写 ⇒ CRUD 层在模型里找不到f_delete_mark, 逻辑删除直接报LOGICAL_DELETE_UNSUPPORTED(已真实踩到)。 - 建表列来源 = 模型(不是表单控件):官方
f_tables_data本身就是建表后的回写产物, 列序与官方 DDL 逐列一致;模型驱动少一层「控件类型 ↔ DDL 类型」的多对一映射。 f_delete_mark是 INTEGER,不是 boolean(官方TableFeildsEnum也是"int")。- 单租户:
f_tenant_id固定"0",但列NOT NULL且参与复合主键 —— 不能省。 - 子表更新是差集对账(不是整条替换):入参没有的旧行会被删;主表则是部分更新。
P2-b 刻意没做的(留给 P2-c):读 base_visual_release(运行时读发布版)、
单据号生成器(需序号表)、真正的乐观锁(现在只写 f_version=0,不校验)。
P2-b 的前置件:docs/visualdev-mechanism.md —— 从 jnpf Java 源码逐条读出的运行时机制
(接口契约 15 个端点 / 列名规则 / 系统字段 / 自动填充 / 主子表),每条结论标了源码位置。
读这份文档时纠正了两个已实现代码里的错误判断(列名归因反了、calculate 不是只读)。
实测发现的三条方言(都已写进代码注释与测试):
f_tables_data的columnName全是 null ⇒ 只能从field推导,而推导不等于真实列名 (F_CreatorTime→f_creatortime,实际列是f_creator_time) ⇒ 本 crate 只保证「表单 ↔ 模型设计稿」自洽;与真实库的一致性由 P2-b 的写工具在落库前比对information_schema(对不上报COLUMN_MISMATCH,拒绝写)- 子表内字段的
tableName指向主表,不是子表 ⇒ 子表归属只能看父节点 formRef/formModel是 Vue 变量名,不是固定常量(见过elForm/formData,也见过formRef/dataForm)
P3 · 业务包 + 动态库 + 双向迁移(约 5 周)
| 项 | 内容 |
|---|---|
| 交付 | sspf-plugin(L2 静态 + L3 dylib 完整实现,§4.5 六条铁律全覆盖);pack export/import --format=baseline;packs/asset 样板;WASM 执行器(Executor 第二实现) |
| 出口 | §5.3 三条验收全过;asset 包往返幂等;ABI 三个反自证:版本不符拒载、插件 panic 不拖垮内核、热替换生效;插件内存超限被强杀 |
| 风险 | 表名/字段映射不一致 ⇒ 用 baseline_table 显式声明,禁止猜;dlclose 后重载拿到旧句柄 ⇒ 复制到新路径再 dlopen |
P4 · 影子对账 + 切换准备(约 4 周)
| 项 | 内容 |
|---|---|
| 交付 | diff-harness + 语料库(≥300 条);切换开关(按 app_code / 菜单 / 用户组分流);回滚脚本;进程沙箱执行器 |
| 出口 | P0=0、P1≤3;体验门全绿;回滚演练成功一次;整套峰值内存 ≤ 256 MB |
| 风险 | 语料覆盖不足 ⇒ 用前端真实流量采样补语料(脱敏) |
P5 · 切换与增强(持续)
| 项 | 内容 |
|---|---|
| 交付 | 真实 PG 支持收口;AI 协作流(需求 → 包 → 验证 → 发布);MCP 工具面全量化 |
| 出口 | 单二进制替代 Java 栈;部署步骤 ≤ 3 条命令;目标硬件实测跑通业务 + 沙箱 + 计算三件套 |
10. 风险与待决策
10.1 已识别风险
| # | 风险 | 影响 | 缓解 |
|---|---|---|---|
| R1 | 拆 crate 破坏现有 147 端点行为 | 高 | P0 只搬不改;六闸 + diff 基线先跑一次存档 |
| R2 | 表单 JSON 方言覆盖不全 | 中 | 先 top 10 控件;缺失控件降级 + 明确报「不支持」而非静默 |
| R3 | Rust 动态库 ABI 崩 | 中 | 默认关 feature;只给明确需要的团队;强制版本校验 |
| R4 | MCP 工具粒度过细 → token 反弹 | 中 | 按业务意图设计;CI 统计 describe 后平均 token,超阈值报警 |
| R5 | 影子对账语料不足 → 假绿 | 高 | 语料必须来自真实流量采样 + 每条差异人工过一遍 |
| R6 | 「去原厂字眼」误改契约字符串 | 🔴 极高 | check-naming.sh 白名单 + 契约文件只读保护 |
| R7 | 业务包依赖偷偷膨胀 | 中 | cargo tree 审计进 CI;sspf-sdk 依赖锁死 serde |
10.2 待决策(开工前定,不定就按推荐走)
10.2 决策台账
已定(2026-10-31):
| # | 决策 | 结论 | 约束 |
|---|---|---|---|
| D0 | 工具链 | Rust 1.95.0(rust-toolchain.toml 全仓锁定,本机既有版本) |
L3 动态库强依赖;插件 build_info 必须匹配;升级走 §4.5 四步 |
| D3 | L3 动态加载 | 必做(不是可选 feature 开关就不给降级余地) | §4.5 六条铁律;装载失败降级不退出 |
| D4 | 表达式引擎 | Rhai(沙箱化,能力全关 + 白名单) | §4.3 五项限额 + 四项约定 |
| D7 | 命名剥离判据 | 前端/移动端/存量库是否依赖(§7.1) | 结构性字符串一字不改;展示性文案可改 |
| D8 | 部署形态 | 终端产品(客户现场 / 一体机 / 边缘) | 内存预算进每阶段出口 |
仍待定(不定就按推荐走):
| # | 决策 | 推荐 | 备选 |
|---|---|---|---|
| D1 | 数据库形态 | P0–P4 用 pglite(零依赖);P5 提供真实 PG 后端(同一 SQL 方言) | 直接上 PG(部署要求变高,违背终端形态) |
| D2 | MCP 传输 | 本地 stdio + 团队 Streamable HTTP 双支持 | 只 stdio |
| D5 | 工具命名 | MCP 层 sspf_*(4 个元工具)+ 域.动作(tool_id) |
扁平命名 |
| D6 | 业务包目录 | packs/<app_code>/,与 app_code 同名 |
按团队分目录 |
| D9 | 插件隔离默认值 | in-process(快);客户端可切 process(稳) |
直接默认进程隔离(性能损失大) |
| D10 | 沙箱运行时 | WASM(wasmtime + 组件模型) | 独立进程 + 容器(重,但可跑任意语言) |
11. 与现有文档的关系
| 文档 | 职责 | 本文件与它的关系 |
|---|---|---|
CLAUDE.md |
当前阶段红线 + 范围 | 本文件定长期架构;CLAUDE.md 的 §2 范围随阶段滚动 |
HANDOFF.md |
现场交接 | 不变 |
MIGRATION.md |
Rust ⇄ 基线平台逐件映射 | 本文件 §5 是其上位设计 |
JNPF_COMPAT_SURFACE.md |
面 B 规格 | 契约真源,不改 |
PERMISSION.md |
权限与 base_* 红线 |
不改 |
HOWTO_MODULE.md |
加模块操作手册 | P3 后改为「加业务包」手册 |
| 本文件 | 架构基线 + 路线图 | 阶段推进只改 §9 的勾 |
12. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-31 | 首版:三层定位、双轨并行、五条核心判断、crate 拆分、L0–L3 动态加载、MCP 2.0 元工具设计、业务包双向迁移、影子对账、P0–P5 路线 |