fix(skill): 自检/文档同步到方案 C(SC3/SC4/SC5 + rustdocflags + description)

- check-scaffold.py: 三条判据从旧模型(sspf 必须声明为 Cargo 依赖)改为方案 C:
  SC3 应用不声明平台/框架件;SC4 业务包不声明外部依赖;
  SC5 Cargo.toml 不出现 sspf(平台由 .cargo/config.toml 的 --extern 提供)。
  _base_tree 与 VIOLATIONS 同步,反自证仍 6/6。
- fetch-platform.sh: 生成的 .cargo/config.toml 同时写 rustdocflags
  (cargo test 的 doctest 走 rustdoc,不吃 build.rustflags,之前 E0432)。
- SKILL.md frontmatter description 改为「预编译 rlib / Gitea Release 按 tag+平台取包 / 零重编」。
- Cargo.toml 头部、HOWTO_MODULE、docs/runbook、new-pack/pack-sync 注释同步。

验证:verify.sh 全量 7/7(静态 3 步 + cargo test + release 构建 + 面 A/面 B 各 18 断言)。
This commit is contained in:
admin committed 2026-11-05 13:54:52 +08:00
1 parent a9c6bd34a3
commit d8a8165dd7
8 files changed
+82 -62

No files matched your search

+55 -43
View File
@@ -14,9 +14,9 @@
|---|---|---|
| SC1 | 没有平台实现目录(`platform/` / `routes.rs` / `crates/` / `db/schema.sql`) | 把平台源码抄回来 |
| SC2 | 没有 `base_*` 建表语句 | 业务包/应用自建平台表 |
| SC3 | 应用 crate 只依赖 `sspf` 门面 | 直接依赖 `sspf-core` / `pglite-rs` 等内部件 |
| SC4 | 每个业务包只依赖 `sspf`,且目录齐全 | 包里去连库 / 缺 `pack.toml` |
| SC5 | `sspf` 只从 workspace 的 git tag 来(成员不另写来源) | 有人偷偷改成 `path = "../ssw-platform"` |
| SC3 | 应用 crate 不声明平台/框架件(`sspf`/`axum`/`tokio`/… 全走 `--extern`) | 声明 `sspf-core` / `sspf` / `axum` 等,破坏 rlib 同源 |
| SC4 | 每个业务包不声明外部依赖,且目录齐全 | 包里去连库 / 缺 `pack.toml` |
| SC5 | `Cargo.toml` 里不出现 `sspf`(平台由 `.cargo/config.toml` 的 `--extern` 提供) | 有人又把 `sspf` 写成 path/git/version 依赖 |
| SC6 | 生成物与 `packs/*` 不漂移 | 加包没跑 `pack-sync.py` |
用法:
@@ -111,30 +111,34 @@ def _deps(toml_path):
return data.get("dependencies", {}) or {}
# 方案 C(2026-11-05):下面这些全部由平台包 lib/ 经 `.cargo/config.toml` 的 `--extern`
# 提供;一旦在 Cargo.toml 再声明一份,就是「同名 crate 两个实例」→ 跨 sspf API 边界 E0308。
_EXTERN_ONLY = (
"sspf", "axum", "tokio", "serde", "serde_json", "http", "bytes",
"ssw-platform", "pglite-rs", "aes", "ecb", "md-5",
)
def sc3_app_only_needs_facade(root):
"""应用 crate 只准依赖门面 `sspf`(+ 纯业务/框架件)。"""
"""应用 crate 只依赖业务包;平台/框架件一律走 .cargo/config.toml 的 --extern。"""
path = os.path.join(root, "src/backend/Cargo.toml")
if not os.path.isfile(path):
return False, "找不到 src/backend/Cargo.toml"
deps = _deps(path)
# 🔴 `sspf-pack-*` 是**业务包**(本仓自己的东西),不是平台内部件;
# 真正不许出现的是平台拆出来的那些 crate 与「被门面收编」的基础件。
# `sspf-pack-*` 是本仓自己的业务包(合法);其余平台拆件/框架件都不许声明。
bad = [
k
for k in deps
if (k.startswith("sspf-") and not k.startswith("sspf-pack-"))
or k in ("ssw-platform", "pglite-rs", "aes", "ecb", "md-5")
if k in _EXTERN_ONLY or (k.startswith("sspf-") and not k.startswith("sspf-pack-"))
]
if "sspf" not in deps:
return False, "应用 crate 没依赖 `sspf`(平台从哪来?)"
if bad:
return False, "应用 crate 直接依赖了平台内部件/被门面收编的件:" + ", ".join(sorted(bad))
return True, "应用 crate 只依赖 `sspf` 门面(+ axum/tokio + 业务包)"
return False, "应用 crate 声明了平台/框架件(应由 .cargo/config.toml --extern 提供):" + ", ".join(sorted(bad))
return True, "应用 crate 只依赖业务包(平台/框架件走 --extern)"
def sc4_packs_are_thin(root):
"""每个业务包只依赖 `sspf`,且四件套齐全。"""
"""每个业务包不声明外部依赖(`sspf` 走 --extern),且四件套齐全。"""
packs_dir = os.path.join(root, "packs")
if not os.path.isdir(packs_dir):
return False, "没有 packs/(示例业务包在哪?)"
@@ -155,41 +159,41 @@ def sc4_packs_are_thin(root):
cargo = os.path.join(base, "Cargo.toml")
if os.path.isfile(cargo):
deps = _deps(cargo)
extra = [k for k in deps if k != "sspf"]
if "sspf" not in deps:
problems.append(f"packs/{app} 没依赖 `sspf`")
if extra:
problems.append(f"packs/{app} 多了依赖:{', '.join(sorted(extra))}")
if deps:
problems.append(
f"packs/{app} 声明了依赖(应留空,平台/框架件走 --extern):{', '.join(sorted(deps))}"
)
if problems:
return False, ";".join(problems)
return True, f"{len(apps)} 个包都只依赖 `sspf`,目录齐全"
return True, f"{len(apps)} 个包都不声明外部依赖,目录齐全"
def sc5_sspf_comes_from_a_tag(root):
"""`sspf` 必须从 workspace 的 **git tag** 来,成员不许另写来源。"""
def sc5_no_sspf_in_cargo(root):
"""`Cargo.toml` 里不得出现 `sspf`:平台由 `.cargo/config.toml` 的 `--extern` 提供。"""
ws = os.path.join(root, "Cargo.toml")
with open(ws, "rb") as f:
data = tomllib.load(f)
dep = (data.get("workspace", {}).get("dependencies", {}) or {}).get("sspf")
if dep is None:
return False, "workspace.dependencies 里没有 `sspf`"
if isinstance(dep, str):
return False, "`sspf` 写成版本号(应锁 git tag,否则本地与 CI 拿到的不是同一份)"
if "git" not in dep or "tag" not in dep:
return False, "`sspf` 必须同时写 `git` 与 `tag`(现在是 %r)" % (dep,)
wdeps = (data.get("workspace", {}) or {}).get("dependencies", {}) or {}
if "sspf" in wdeps:
return False, "workspace.dependencies 仍声明了 `sspf`(方案 C 应由 .cargo/config.toml 的 --extern 提供)"
# 成员不许另写来源
offenders = []
for member in ("src/backend/Cargo.toml",):
path = os.path.join(root, member)
if os.path.isfile(path):
d = _deps(path).get("sspf")
if isinstance(d, dict) and ("git" in d or "path" in d or "version" in d):
offenders.append(member)
if os.path.isfile(path) and "sspf" in _deps(path):
offenders.append(member)
if offenders:
return False, "成员自己写了 `sspf` 来源(应 `{ workspace = true }`):" + ", ".join(offenders)
return True, f"`sspf` 锁 git tag `{dep.get('tag')}`"
return False, "成员声明了 `sspf`(应由 .cargo/config.toml 的 --extern 提供):" + ", ".join(offenders)
# 若已生成 config,顺手校验它确实喂了 sspf(没生成不算错:verify 可在 fetch 之前跑)
cfg = os.path.join(root, ".cargo/config.toml")
if os.path.isfile(cfg):
text = open(cfg, encoding="utf-8", errors="ignore").read()
if "sspf=" not in text or "dependency=" not in text:
return False, ".cargo/config.toml 里没有 `--extern sspf=…` + `-L dependency=…`(重跑 scripts/fetch-platform.sh)"
return True, "平台经 .cargo/config.toml 的 --extern 提供(Cargo.toml 未声明 sspf)"
return True, "Cargo.toml 未声明 sspf(构建前先跑 scripts/fetch-platform.sh 生成 .cargo/config.toml)"
def sc6_generated_files_in_sync(root):
@@ -211,9 +215,9 @@ def sc6_generated_files_in_sync(root):
CHECKS = [
("SC1", "本仓没有平台实现", sc1_no_vendored_platform),
("SC2", "业务侧不建 base_* 表", sc2_no_base_tables),
("SC3", "应用只依赖门面 sspf", sc3_app_only_needs_facade),
("SC4", "业务包只依赖 sspf", sc4_packs_are_thin),
("SC5", "sspf 锁 git tag", sc5_sspf_comes_from_a_tag),
("SC3", "应用不声明平台/框架件", sc3_app_only_needs_facade),
("SC4", "业务包不声明外部依赖", sc4_packs_are_thin),
("SC5", "Cargo.toml 不出现 sspf", sc5_no_sspf_in_cargo),
("SC6", "生成物无漂移", sc6_generated_files_in_sync),
]
@@ -249,19 +253,27 @@ def _base_tree(root):
_mk(
root,
"Cargo.toml",
'[workspace]\nmembers = ["src/backend", "packs/demo"]\n'
'[workspace.dependencies]\nsspf = { git = "http://x/y.git", tag = "v0.4.0" }\n',
'[workspace]\nmembers = ["src/backend", "packs/demo"]\n',
)
# 方案 C:平台经 .cargo/config.toml 的 --extern 提供(不再写进 Cargo.toml)
_mk(
root,
".cargo/config.toml",
'[build]\nrustflags = [\n'
' "--extern", "sspf=/tmp/lib/libsspf-x.rlib",\n'
' "-L", "dependency=/tmp/lib",\n'
']\n',
)
_mk(
root,
"src/backend/Cargo.toml",
'[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\nsspf = { workspace = true }\n',
'[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\n',
)
_mk(root, "src/backend/src/lib.rs", "// app\n")
_mk(
root,
"packs/demo/Cargo.toml",
'[package]\nname = "sspf-pack-demo"\nversion = "0.0.0"\n[dependencies]\nsspf = { workspace = true }\n',
'[package]\nname = "sspf-pack-demo"\nversion = "0.0.0"\n[dependencies]\n',
)
_mk(root, "packs/demo/pack.toml", '[pack]\napp_code = "demo"\n')
_mk(root, "packs/demo/src/lib.rs", "// pack\n")
@@ -289,7 +301,7 @@ def _base_tree(root):
_mk(
root,
"src/backend/Cargo.toml",
'[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\nsspf = { workspace = true }\n'
'[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\n'
"# >>>GEN:PACK_DEPS\n# <<<GEN:PACK_DEPS\n",
)
subprocess.run(
+7 -1
View File
@@ -179,11 +179,17 @@ if [[ -n "${SSPF_RLIB}" ]]; then
# ⚠️ 前提:rustc 版本 == vendor/${PKG}/rust-toolchain.toml(ABI 锁,否则链接失败)。
# 极端回退(要改平台源码):删本文件 + 改用 git 依赖 sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v${VERSION}" }
[build]
# rustc 用
rustflags = [
${EXTERN_LINES} "-L", "dependency=${SKILL_ROOT}/vendor/${PKG}/lib",
]
# 🔴 cargo test 的 doctest 走 rustdoc,**不吃 build.rustflags**;必须同样喂一遍,
# 否则测试阶段 doctest 里的 `use sspf::` 会 E0432(unresolved import)。
rustdocflags = [
${EXTERN_LINES} "-L", "dependency=${SKILL_ROOT}/vendor/${PKG}/lib",
]
EOF
echo "==> 已生成 .cargo/config.toml(--extern sspf/axum/tokio/serde/serde_json/http/bytes + -L dependency)"
echo "==> 已生成 .cargo/config.toml(rustflags + rustdocflags:--extern sspf/axum/tokio/serde/serde_json/http/bytes + -L dependency)"
echo " 消费方 Cargo.toml 无需声明这些依赖;代码照用 use sspf:: / use axum::"
else
echo "!! ⚠️ 包内 lib/ 缺 libsspf-*.rlib(旧包?)。请用新版 release.sh 重新出包:" >&2
+3 -2
View File
@@ -185,8 +185,9 @@ def pack_lib(app, entity, name, table, columns, sort):
//!
//! 🔴 **这里是业务真源**:表 + 列 + 菜单 + 面 B 路由都在这个目录里。
//! 面 A 适配器在同仓 `src/backend/src/modules/{app}.rs`(只做转发,不重写 spec)。
//! 🔴 **依赖纪律**:本包只依赖 `sspf` 门面;出现 axum / tokio / pglite 会被
//! `scripts/check-scaffold.sh` 判红 —— 这是「整目录可搬走」的技术保证。
//! 🔴 **依赖纪律**:本包**不声明外部依赖**(`sspf` 走 `.cargo/config.toml` 的 --extern);
//! 出现 sspf / axum / tokio / pglite 会被 `scripts/check-scaffold.py` 判红 ——
//! 这是「整目录可搬走」的技术保证。
use sspf::{{
BusinessPack, ColumnSpec, EntitySpec, HttpMethod, Manifest, MenuSpec, PackRoute, RouteAction,
+1 -1
View File
@@ -15,7 +15,7 @@
`--check` 在「改了包没跑生成」时**红**,不要让漂移活到运行时。
🔴 **真源**:
- 表 DDL / 列 / 菜单 / 面 B 路由 ⇒ `packs/<app>/`(业务包,只依赖 `sspf` 门面)
- 表 DDL / 列 / 菜单 / 面 B 路由 ⇒ `packs/<app>/`(业务包,不声明外部依赖,走 --extern)
- 面 A 适配器 / spec 转发 ⇒ `src/backend/src/modules/<app>.rs`
用法: