Files
ssw-platform/scripts/check-arch.sh
T
admin 217dadf008 feat(mcp): 落地 MCP 工具层 —— 4 元工具 + 分层加载 + 进程内适配器
- 新增 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
2026-10-31 10:29:14 +08:00

279 lines
9.7 KiB
Bash
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/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