- 新增 crates/sspf-mcp:registry / jsonrpc / server / 4 个元工具(context·discover·describe·call) - 内核新增 mcp_adapter.rs(NativeAdapter,直接调 AppState)与 `--mcp` 子命令 - 工具定义自带五段自提示(含 pitfalls/examples),示例必须能被测试跑通 - 新增 scripts/mcp-smoke.sh(13 条)与 docs/mcp.md(接入说明) - 影响:协议层只暴露 4 个工具(常驻约 1.8K token);业务失败返回结构化 error 而非协议错 - 踩坑记录:内嵌 PG 会抢 fd 0/1,必须在开库前 detach 标准流;tokio 的 stdin 在管道上 ENXIO
279 lines
9.7 KiB
Bash
Executable File
279 lines
9.7 KiB
Bash
Executable File
#!/usr/bin/env bash
|
||
# sspf 架构边界自检 —— crate 依赖纪律 + 内存红线
|
||
#
|
||
# 目的:把 PLAN.md 判断 ②/⑥ 的架构约束变成**可执行的尺子**。
|
||
# 靠人读 Cargo.toml 守不住 —— 加依赖的人不会想到「这会让所有业务包背锅」。
|
||
#
|
||
# 🔴 **纯静态**:不编译、不启动。只需要 bash + python3(macOS 自带)。
|
||
#
|
||
# 用法:
|
||
# bash scripts/check-arch.sh # 全查
|
||
# bash scripts/check-arch.sh --self-test # 反自证:造已知违规,必须被抓到
|
||
#
|
||
# 退出码:0 全过 / 1 有 ❌ / 2 用法错
|
||
#
|
||
# ── 判据 ──
|
||
# AR1 `crates/sspf-sdk` 依赖只能有 `sspf-contract`
|
||
# —— 业务包只依赖 sdk ⇒ sdk 多一个依赖 = 所有业务包都要背
|
||
# AR2 `packs/*/Cargo.toml` 依赖 ⊆ {sspf-sdk, serde}
|
||
# —— 业务包必须能整目录搬走 ⇒ 不许挂在 axum / tokio / pglite 上
|
||
# AR3 `crates/sspf-contract` 源码不许 `use axum|tokio|pglite|sqlx`
|
||
# —— 契约层一旦有 IO,业务包就再也不是「轻依赖」
|
||
# AR4 `crates/sspf-contract` 依赖 ⊆ {serde, serde_json, uuid, http}
|
||
# AR5 `crates/sspf-mcp`(若已存在)依赖 ⊆ {sspf-contract, serde, serde_json, tokio, async-trait}
|
||
# —— MCP 层要能同时接「进程内内核」和「远端 Java 后端」⇒ **不许依赖内核内部**
|
||
# —— tokio / async-trait 是协议实现(stdio 异步读写)所需,不是业务依赖
|
||
# MEM1 非注释代码里不许出现 `SELECT *`
|
||
# —— 终端产品内存预算 ≤ 120MB(PLAN.md 判断 ⑥)⇒ 全表读进 Vec 直接爆
|
||
# MEM2 `crates/**` 与 `src/backend/src/platform/**` 里不许出现无界 `HashMap` 缓存
|
||
# (近似检查:`static` + `Mutex<HashMap` 必须有 `MAX` 常量同文件出现)
|
||
#
|
||
# 🔴 AR1–AR5 是 PLAN.md §3.2 的分层纪律;MEM1–MEM2 是判断 ⑥ 的四条内存红线的静态部分。
|
||
|
||
set -u
|
||
|
||
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||
CRATES="$ROOT/crates"
|
||
KERNEL="$ROOT/src/backend"
|
||
|
||
PASS=0
|
||
FAIL=0
|
||
SKIP=0
|
||
|
||
ok() { PASS=$((PASS + 1)); printf '✅ %s\n' "$1"; }
|
||
bad() { FAIL=$((FAIL + 1)); printf '❌ %s\n' "$1"; }
|
||
skip() { SKIP=$((SKIP + 1)); printf '⏭ %s\n' "$1"; }
|
||
|
||
usage() {
|
||
echo "用法: bash scripts/check-arch.sh [--self-test]"
|
||
echo " 静态检查 crate 依赖纪律(AR1–AR5)与内存红线(MEM1–MEM2)"
|
||
echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错"
|
||
}
|
||
|
||
# 取出 Cargo.toml 里 [dependencies] 段的包名(一行一个,已去空白)
|
||
deps_of() {
|
||
awk '
|
||
/^\[dependencies\]/ { f = 1; next }
|
||
/^\[/ { f = 0 }
|
||
f && /^[A-Za-z0-9_-]+[[:space:]]*=/ { sub(/[[:space:]]*=.*/, ""); print }
|
||
' "$1"
|
||
}
|
||
|
||
# 判断集合 A 是否 ⊆ 集合 B(两者都是空格分隔串)
|
||
subset_of() {
|
||
local need="$1" allowed=" $2 "
|
||
local x
|
||
for x in $need; do
|
||
case "$allowed" in
|
||
*" $x "*) : ;;
|
||
*) return 1 ;;
|
||
esac
|
||
done
|
||
return 0
|
||
}
|
||
|
||
# ---------------------------------------------------------------- AR1
|
||
check_ar1() {
|
||
local f="$CRATES/sspf-sdk/Cargo.toml"
|
||
[ -f "$f" ] || { skip "AR1 sspf-sdk 不存在(尚未拆分)"; return; }
|
||
local deps; deps="$(deps_of "$f" | tr '\n' ' ')"
|
||
if subset_of "$deps" "sspf-contract"; then
|
||
ok "AR1 sspf-sdk 依赖干净([$deps])"
|
||
else
|
||
bad "AR1 sspf-sdk 依赖越界:[$deps] —— 只允许 sspf-contract"
|
||
fi
|
||
}
|
||
|
||
# ---------------------------------------------------------------- AR2
|
||
check_ar2() {
|
||
local found=0 n=0
|
||
for f in "$ROOT"/packs/*/Cargo.toml; do
|
||
[ -f "$f" ] || continue
|
||
n=$((n + 1))
|
||
local deps; deps="$(deps_of "$f" | tr '\n' ' ')"
|
||
if subset_of "$deps" "sspf-sdk serde"; then
|
||
ok "AR2 $(basename "$(dirname "$f")") 依赖干净([$deps])"
|
||
else
|
||
bad "AR2 $(basename "$(dirname "$f")") 依赖越界:[$deps] —— 只允许 sspf-sdk / serde"
|
||
found=1
|
||
fi
|
||
done
|
||
[ "$n" -eq 0 ] && skip "AR2 尚无 packs/*(P3 才落地)"
|
||
return $found
|
||
}
|
||
|
||
# ---------------------------------------------------------------- AR3
|
||
check_ar3() {
|
||
local dir="$CRATES/sspf-contract/src"
|
||
[ -d "$dir" ] || { skip "AR3 sspf-contract 不存在"; return; }
|
||
local hits
|
||
hits="$(grep -rnE '^[[:space:]]*(pub )?use (axum|tokio|pglite|sqlx)' "$dir" 2>/dev/null || true)"
|
||
if [ -z "$hits" ]; then
|
||
ok "AR3 sspf-contract 无 IO 依赖(无 axum/tokio/pglite/sqlx 的 use)"
|
||
else
|
||
bad "AR3 sspf-contract 出现 IO 依赖:"
|
||
printf '%s\n' "$hits" | sed 's/^/ /'
|
||
fi
|
||
}
|
||
|
||
# ---------------------------------------------------------------- AR4
|
||
check_ar4() {
|
||
local f="$CRATES/sspf-contract/Cargo.toml"
|
||
[ -f "$f" ] || { skip "AR4 sspf-contract 不存在"; return; }
|
||
local deps; deps="$(deps_of "$f" | tr '\n' ' ')"
|
||
if subset_of "$deps" "serde serde_json uuid http"; then
|
||
ok "AR4 sspf-contract 依赖在白名单内([$deps])"
|
||
else
|
||
bad "AR4 sspf-contract 依赖越界:[$deps] —— 白名单 serde/serde_json/uuid/http"
|
||
fi
|
||
}
|
||
|
||
# ---------------------------------------------------------------- AR5
|
||
check_ar5() {
|
||
local f="$CRATES/sspf-mcp/Cargo.toml"
|
||
[ -f "$f" ] || { skip "AR5 sspf-mcp 不存在(P1 才落地)"; return; }
|
||
local deps; deps="$(deps_of "$f" | tr '\n' ' ')"
|
||
if subset_of "$deps" "sspf-contract serde serde_json tokio async-trait"; then
|
||
ok "AR5 sspf-mcp 依赖干净([$deps])"
|
||
else
|
||
bad "AR5 sspf-mcp 依赖越界:[$deps] —— 只允许 sspf-contract/serde/serde_json/tokio/async-trait"
|
||
fi
|
||
}
|
||
|
||
# ---------------------------------------------------------------- MEM1
|
||
# 只看**代码行**:去掉 `//` 之后的注释、`//!` / `///` 文档注释、以及字符串里的反引号示例。
|
||
check_mem1() {
|
||
local hits
|
||
hits="$(python3 - "$ROOT" <<'PY'
|
||
import os, re, sys
|
||
root = sys.argv[1]
|
||
pat = re.compile(r'SELECT\s+\*', re.I)
|
||
bad = []
|
||
for base in ('src/backend/src', 'crates'):
|
||
for dirpath, dirnames, files in os.walk(os.path.join(root, base)):
|
||
dirnames[:] = [d for d in dirnames if d not in ('target', 'tests', 'data')]
|
||
for fn in files:
|
||
if not fn.endswith('.rs'):
|
||
continue
|
||
p = os.path.join(dirpath, fn)
|
||
# 文件名以 _it.rs 结尾的是集成测试,不查
|
||
if fn.endswith('_it.rs'):
|
||
continue
|
||
try:
|
||
lines = open(p, encoding='utf-8').read().splitlines()
|
||
except OSError:
|
||
continue
|
||
in_test = False
|
||
for i, line in enumerate(lines, 1):
|
||
s = line.strip()
|
||
if s.startswith('#[cfg(test)]'):
|
||
in_test = True
|
||
if in_test:
|
||
continue
|
||
code = line.split('//', 1)[0]
|
||
if pat.search(code):
|
||
bad.append(f'{p}:{i}: {s}')
|
||
for b in bad:
|
||
print(b)
|
||
PY
|
||
)"
|
||
if [ -z "$hits" ]; then
|
||
ok "MEM1 无非注释的 SELECT *(全表读进 Vec 会直接超内存预算)"
|
||
else
|
||
bad "MEM1 发现 SELECT *(终端产品内存预算 ≤120MB,禁止整表载入):"
|
||
printf '%s\n' "$hits" | sed 's/^/ /'
|
||
fi
|
||
}
|
||
|
||
# ---------------------------------------------------------------- MEM2
|
||
# 近似检查:出现 `Mutex<HashMap` 的静态缓存,同文件必须有 MAX_ / CAPACITY 常量。
|
||
check_mem2() {
|
||
local hits
|
||
hits="$(python3 - "$ROOT" <<'PY'
|
||
import os, re, sys
|
||
root = sys.argv[1]
|
||
cache = re.compile(r'Mutex\s*<\s*(std::collections::)?HashMap')
|
||
cap = re.compile(r'\b(MAX|CAPACITY|LIMIT)_[A-Z0-9_]+\b')
|
||
bad = []
|
||
for base in ('src/backend/src', 'crates'):
|
||
for dirpath, dirnames, files in os.walk(os.path.join(root, base)):
|
||
dirnames[:] = [d for d in dirnames if d not in ('target', 'tests', 'data')]
|
||
for fn in files:
|
||
if not fn.endswith('.rs') or fn.endswith('_it.rs'):
|
||
continue
|
||
p = os.path.join(dirpath, fn)
|
||
try:
|
||
text = open(p, encoding='utf-8').read()
|
||
except OSError:
|
||
continue
|
||
if cache.search(text) and not cap.search(text):
|
||
for i, line in enumerate(text.splitlines(), 1):
|
||
if cache.search(line):
|
||
bad.append(f'{p}:{i}: {line.strip()}')
|
||
break
|
||
for b in bad:
|
||
print(b)
|
||
PY
|
||
)"
|
||
if [ -z "$hits" ]; then
|
||
ok "MEM2 缓存均有上限常量(无界缓存 = 慢性内存泄漏)"
|
||
else
|
||
bad "MEM2 发现疑似无界缓存(同文件没有 MAX_/CAPACITY_ 常量):"
|
||
printf '%s\n' "$hits" | sed 's/^/ /'
|
||
fi
|
||
}
|
||
|
||
# ---------------------------------------------------------------- 反自证
|
||
# 🔴 永远返回「干净」的尺子 = 没有尺子。造一个明知违规的临时 pack,必须被抓到。
|
||
self_test() {
|
||
echo "── 反自证:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
|
||
local tmp="$ROOT/packs/__arch_selftest__"
|
||
mkdir -p "$tmp"
|
||
cat > "$tmp/Cargo.toml" <<'TOML'
|
||
[package]
|
||
name = "arch-selftest"
|
||
version = "0.0.0"
|
||
edition = "2021"
|
||
|
||
[dependencies]
|
||
sspf-sdk = { path = "../../crates/sspf-sdk" }
|
||
axum = "0.8"
|
||
TOML
|
||
local before=$FAIL
|
||
check_ar2 >/dev/null 2>&1
|
||
local caught=0
|
||
[ "$FAIL" -gt "$before" ] && caught=1
|
||
rm -rf "$tmp"
|
||
# 恢复计数(自证不算进正式统计)
|
||
FAIL=$before
|
||
if [ "$caught" -eq 1 ]; then
|
||
echo "✅ 反自证通过:AR2 抓到了 axum 依赖"
|
||
return 0
|
||
fi
|
||
echo "❌ 反自证失败:AR2 没抓到明显违规 ⇒ 这把尺子是假的"
|
||
return 1
|
||
}
|
||
|
||
# ---------------------------------------------------------------- main
|
||
[ "${1:-}" = "--help" ] && { usage; exit 0; }
|
||
|
||
echo "── 架构边界闸门(crate 依赖纪律 + 内存红线)──"
|
||
check_ar1
|
||
check_ar2
|
||
check_ar3
|
||
check_ar4
|
||
check_ar5
|
||
check_mem1
|
||
check_mem2
|
||
|
||
echo
|
||
printf '结果: %d 通过 / %d 失败 / %d 跳过\n' "$PASS" "$FAIL" "$SKIP"
|
||
|
||
if [ "${1:-}" = "--self-test" ]; then
|
||
echo
|
||
self_test || exit 1
|
||
fi
|
||
|
||
[ "$FAIL" -eq 0 ] || exit 1
|
||
exit 0
|