# 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,不认具体后端。 ```rust // crates/sspf-mcp/src/adapter.rs #[async_trait] pub trait PlatformAdapter: Send + Sync { async fn call(&self, op: &str, args: Value) -> Result; async fn describe_env(&self) -> EnvInfo; // app_code / system / db / 版本 } // 两个实现: // JnpfHttpAdapter —— 打现有 Java 后端(HTTP),P1 就能用 // SspfNativeAdapter —— 进程内直调 kernel,P4 切换 // 工具契约、自提示、返回形状,两边完全一致。 ``` --- ## 2. 五条核心判断(都会影响后续所有设计) ### 判断 ①:不改前端 ⇒ 「低代码引擎」在后端只是「元数据服务 + 动态数据路由」 基线平台的低代码渲染器在**前端**(Vue 的 FormGenerator 解释表单 JSON)。既然不迁前端, Rust 侧**不需要重写渲染器**,只需要三件事: 1. **存取**:`visualdev` 那套 JSON 原样存、原样取(同构,不改一个字段) 2. **动态 CRUD**:给定 `modelId` → 查元数据 → 解析出物理表/字段/权限 → 拼 SQL(**零编译**) 3. **发布/版本**:表单草稿 → 发布 → 版本快照 ⇒ 低代码引擎的工作量比直觉小一个量级,**且天然满足「不编译」**。这是第 8 条需求的落地点。 ### 判断 ②:「不编译」有四级;**动态库是必须项,不是可选项** Rust 没有稳定 ABI,`cdylib` 跨编译器版本会段错误。按「稳定性 × 成本」排序: | 级 | 机制 | 编译 | 适用 | 风险 | |---|---|---|---|---| | **L0 元数据** | 表单/模型/菜单/流程/权限 = 库里的 JSON | **零** | 80% 的业务 | 无 | | **L1 表达式** | Rhai 求值(受限宿主 API + 资源上限) | **零** | 15% 的业务(业务规则) | 低(沙箱化) | | **L2 静态 crate** | `packs//src` 编成 rlib,链进内核 | 只编业务 crate(~30s) | 4% 的业务(外部集成、复杂算法) | 无 | | **L3 动态库** | `cdylib` + `libloading`,`plugins/*.dylib` 启动扫描 | 独立编、热替换 | **必须支持**(见 §4.5) | 🟡 中(靠 ABI 契约 + 工具链锁定压住) | **L3 是硬需求**,理由是终端产品形态:客户现场要能单独替换/升级某个业务能力,不能等整包发版。 代价必须用工程手段压住,而不是回避: 1. **工具链锁死 `1.95.0`**(`rust-toolchain.toml` + `pack.toml` 的 `[pack.build].toolchain`,CI 双向校验) 2. **ABI 只暴露 4 个 C 函数**,其余全部走 JSON(见 §4.5) 3. **装载失败不能拖垮内核**:版本不匹配直接拒载;`catch_unwind` + 独立线程兜底 4. **热替换必须显式**:`sspf plugin reload `,不做自动监控(自动热更 = 状态迁移地狱) 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`): 1. 禁止 `SELECT *` 全表读进 `Vec` —— 导出/报表一律游标流式 2. 禁止无界缓存(所有缓存必须有 `max_entries` + LRU 淘汰) 3. 每个限额必须有默认值 + 可配,不许「不配就无限」 4. 沙箱/计算必须能独立限额并强杀,不影响主进程存活 ### 判断 ⑦:执行器(沙箱 + 计算)从 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// ── 业务包(整目录可搬) │ │ ├ 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 | 防内存炸 | 四条实现约定: 1. **编译一次,缓存 AST**:`Engine::compile` → `AST`,按表达式源 + 版本哈希缓存(有上限,LRU) 2. **表达式存元数据表** ⇒ 改规则 = 改数据 = **零编译** 3. **错误必须可读**:`EvalAltResult` 要映射成「哪个字段 / 哪一行 / 期望什么」,不能把 Rhai 原始错误直接抛给业务 4. **每次求值独立 `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(默认的「写代码」形态) ```rust // 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); ``` 内核侧: ```rust // crates/sspf-kernel/src/main.rs —— 内核里唯一的「业务知识」 let packs: Vec> = 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,改动即升版本) ```rust // 插件侧(每个业务 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) | 一个坏插件等于整站宕机 | #### 工具链锁定 ```toml # rust-toolchain.toml(仓库根,全仓生效) [toolchain] channel = "1.95.0" components = ["rustfmt", "clippy"] profile = "minimal" ``` `pack.toml` 的 `[pack.build]` 必须写同一版本,CI 双向校验: ```bash 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` ```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 迁移 = 打包 / 解包,不是重写 ```bash 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 业务包的可搬性验收 一个包算合格,必须能过这条: ```bash # 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 红): ```rust 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")`): ```json { "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": "最小可用调用" } ] } } ``` **自提示的三条铁律**: 1. **单一真值源**:`registry` 里写一次,派生 tool schema / `describe` 输出 / 静态文档 / CI 用例 2. **examples 必须可执行**:CI 对每个 example 跑 `dry_run`,跑不通 = 构建失败(防文档腐烂) 3. **失败即教学**:错误返回必须带 `hints[] + next_actions[] + doc_ref`,让 AI 一次就能自纠 ### 6.5 失败返回的形状(比成功更重要) ```json { "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 名、模块名、类型名、函数名、变量名、文件名 | ✅ **全改** | 🔴 这条判据解释了两个容易吵的点: 1. **`jnpfKey` 必须保留** —— 它出现在表单 JSON 里,前端 `componentMap.ts` 靠它选组件。 改了就白屏。名字难看也得留。 2. **`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 / 主键 | → `` | | 时间戳 | → ``(保留"是否为空") | | 列表顺序 | 按主键排序后再比 | | 浮点/金额 | 转字符串比(防 `9.9` vs `9.90`) | | 分页 total | 数据不同步时允许差,单独标 `DATA_DRIFT` 不算 P0 | | 字段增删 | 基线有、SSPF 无 ⇒ **P0**;SSPF 多 ⇒ P2(前端不读就无害) | **分级与出口**: | 级别 | 定义 | 出口要求 | |---|---|---| | P0 | 字段缺失 / 类型不同 / 错误码不同 / 权限判定相反 | **= 0** | | P1 | 值不同(非 ID/时间)/ 排序不同 | ≤ 3 且每条有豁免记录 | | P2 | 多返回字段 / 文案差异 | 不限 | ### 8.3 切换的三道门(缺一不可) 1. **契约门**:八道闸门全绿 + diff P0=0 2. **体验门**:同一前端 E2E(登录→菜单→5 个核心页 CRUD)在两个后端全绿 3. **回滚门**:切流开关能 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 元工具 + 五段自提示 + resources - `NativeAdapter`(进程内,共用 `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.sh` 32 条、`baseline-smoke.sh` 10 条 - 接入说明见 `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.sh` 8 条,含**两条反自证**:改坏 `__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 的关键判断(后续别改坏)**: 1. **建表后必须回写** `f_tables_data`:不回写 ⇒ CRUD 层在模型里找不到 `f_delete_mark`, 逻辑删除直接报 `LOGICAL_DELETE_UNSUPPORTED`(已真实踩到)。 2. 建表列来源 = **模型**(不是表单控件):官方 `f_tables_data` 本身就是建表后的回写产物, 列序与官方 DDL 逐列一致;模型驱动少一层「控件类型 ↔ DDL 类型」的多对一映射。 3. `f_delete_mark` 是 **INTEGER**,不是 boolean(官方 `TableFeildsEnum` 也是 `"int"`)。 4. **单租户**:`f_tenant_id` 固定 `"0"`,但列 `NOT NULL` 且**参与复合主键** —— 不能省。 5. 子表更新是**差集对账**(不是整条替换):入参没有的旧行会被删;主表则是部分更新。 **P2-b 刻意没做的**(留给 P2-c):读 `base_visual_release`(运行时读发布版)、 单据号生成器(需序号表)、真正的乐观锁(现在只写 `f_version=0`,不校验)。 **P2-b 的前置件**:`docs/visualdev-mechanism.md` —— 从 jnpf Java 源码逐条读出的运行时机制 (接口契约 15 个端点 / 列名规则 / 系统字段 / 自动填充 / 主子表),每条结论标了源码位置。 读这份文档时纠正了两个已实现代码里的错误判断(列名归因反了、`calculate` 不是只读)。 **实测发现的三条方言**(都已写进代码注释与测试): 1. `f_tables_data` 的 `columnName` **全是 null** ⇒ 只能从 `field` 推导,而推导**不等于**真实列名 (`F_CreatorTime` → `f_creatortime`,实际列是 `f_creator_time`) ⇒ 本 crate 只保证「表单 ↔ 模型设计稿」自洽;与真实库的一致性由 P2-b 的写工具在落库前比对 `information_schema`(对不上报 `COLUMN_MISMATCH`,拒绝写) 2. 子表内字段的 `tableName` 指向**主表**,不是子表 ⇒ 子表归属只能看父节点 3. `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` 同名 | 按团队分目录 | | 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 路线 |