diff --git a/.gitignore b/.gitignore index 1cc4fa1..9760d45 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,13 @@ dist/ .DS_Store # 本地 pi 符号链接(如有) pi + +# 运行时生成(createAgentSession 产物,不入库) +auth.json +models-store.json +models.json.bak + +# landlock-run 编译产物(源码入库,二进制不入库) +native/landlock-run/landlock-run-stub +native/landlock-run/landlock-run-aarch64 +native/landlock-run/landlock-run-aarch64-gnu diff --git a/Docs/postmortem/0001-e2e-smoke.md b/Docs/postmortem/0001-e2e-smoke.md new file mode 100644 index 0000000..2b58a4e --- /dev/null +++ b/Docs/postmortem/0001-e2e-smoke.md @@ -0,0 +1,224 @@ +# 0001 — T01 端到端装配冒烟 + +**日期**:2026-08-14 +**任务**:T01(P0 端到端冒烟) +**诚实状态**:T01 离线装配冒烟 ✅;真运行时冒烟 ⛔ 受网络阻断(pi 模型数据水合) + +--- + +## 1. 离线可跑的部分 ✅ + +### 1.1 verifyAssembly(稳定离线基线) + +`PhysicalByteAgent.verifyAssembly()` 确认 21 个域扩展工厂全部就位且都是函数: + +- 工厂数 = **21**(glm-provider / safety-gate / persistent-shell / pdf-reader / edit-strict / + length-recovery / subprocess-isolation / env-probe / mcp-bridge / server-runtime / + hardware-state / cross-compile / flash / peripheral-probe / jtag-debugger / + device-tree / board-link / datasheet-rag / hardware-verify / loop-orchestrator / build-tracker) +- 离线可跑,不依赖 pi 构建产物、不依赖联网。 + +### 1.2 FakePi mock 装配结果 + +vitest.config.ts 的 alias 把 `@earendil-works/pi-coding-agent` / `@earendil-works/pi-ai` +解析到 pi **源码**(`.ts`),故各工厂体内的 `await import("@earendil-works/pi-coding-agent")` +在测试内可解析到真 `defineTool` / `Type` / `createAgentSession` —— 工具注册真实发生。 + +**21 个工厂全部成功,0 个 assembly-error**(在 mock 下): + +| 指标 | 值 | +|------|----| +| 工厂总数 | 21 | +| 成功工厂 | 21 | +| 失败工厂(assembly-error) | 0 | +| 注册工具数 | 24(部分工厂注册多工具) | + +注册工具名:`glm_status`, `pshell`, `read_pdf`, `length_recovery_status`, `isolated_exec`, +`env_status`, `mcp_list`, `mcp_call`, `server_session`, `hw_state`, `xcompile`, `flash`, +`bus_probe`, `debugger`, `dt`, `board_connect`, `board_exec`, `board_scp`, `board_console`, +`datasheet_query`, `verify`, `loop_status`, `build`, `build_status` + +glm-provider 同时注册了 `drobotics-glm` provider(命门一根治点:thinkingFormat:"qwen")。 + +### 1.3 安全门钩子端到端(装配级) + +装配后 `pi.handlers["tool_call"]` 有 ≥1 handler。决策表验证: + +| 命令 | hasUI | 结果 | +|------|-------|------| +| `devmem 0x40020000 w 0x1` | false | block:true | +| `devmem 0x40020000 write 0x1` | true(confirm→false) | block:true | +| `i2cdump -y 0 0x76` | false | undefined(放行) | +| 非 bash 工具调用 | false | undefined(不拦截) | + +### 1.4 T02 hex-normalize 链路证明(装配级) + +glm-5.2 把 `0x40020000` 强转成十进制 `1073872896`。链路: + +``` +normalizeHexArg("1073872896") → { value:"0x40020000", corrected:true } +evaluateSafety("devmem 0x40020000 w 0x1") → block:true (rule: devmem-write) +``` + +归一后再过门命中拦截 —— **T02 hex-normalize → T01 safety-gate 链路在装配级端到端打通**。 + +### 1.5 vitest 输出(71/71 绿) + +``` + RUN v2.1.9 /Users/d-robotics/Desktop/physical_byte_agent + +stderr | tests/e2e-smoke.test.ts > ... 已知缺口记录 · 裸 decimal devmem 不经归一直接过门 +[T01 KNOWN-GAP] safety-gate does not block raw decimal devmem (no 0x prefix). Mitigated by glm-provider normalizeHexArg (T02) in prepareArguments pipeline. + +stderr | 对抗/模糊 +[T01 ADVERSARIAL-GAP] KNOWN-GAP: decimal 裸跑漏过(T02 归一兜底): "devmem 1073872896 w 0x1" not blocked (rule=none) +[T01 ADVERSARIAL-GAP] KNOWN-GAP: 64 位 decimal 漏过: "devmem 1099511627776 w" not blocked (rule=none) +[T01 ADVERSARIAL-GAP] KNOWN-GAP: 引号变形绕过词边界: "d'e'vmem 0x40020000 w" not blocked (rule=none) + + ✓ tests/e2e-smoke.test.ts (71 tests) 1517ms + ✓ T01 装配冒烟 —— barrel 装配 + fail-soft > FakePi + barrel 装配完成不抛错(fail-soft 保证单工厂崩不中断) + + Test Files 1 passed (1) + Tests 71 passed (71) + Duration 1.83s +``` + +### 1.6 测试方法学覆盖(响应质量上调) + +| 方法 | describe 块 | 覆盖内容 | +|------|------------|----------| +| 等价类划分 + 边界值 | `T01 边界值 · normalizeHexArg 地址区间` | EC1-EC5 等价类 + B1(7/8位) B2(minRange开区间) B3(maxRange闭区间) B4(越界) 边界 | +| 决策表 | `T01 决策表 · evaluateSafety 全覆盖` | 8 规则 × 命中/未命中 × allowRules 豁免 × hex/十进制,12 行 + 3 交叉断言 | +| 对抗/模糊 | `T01 对抗/模糊 · safety-gate 绕过尝试` | 10 条伪装绕过(write别名/devmem2/decimal/引号/变量/大小写/多空格)+ 6 假阳性 | +| 变异测试 | `T01 变异测试 · normalizeHexArg 边界算子变异` | M1(`<=`→`<`) M2(`>`→`>=`) M3(`>=`→`>`) 三变异被杀 | +| 元变性/不变量 | `T01 元变性/不变量 · allowRules 单调性` | block(B)⟹block(A) 对 A⊆B(100 组随机)+ 空集/全集推论 | +| 状态不变量 | `T01 状态不变量 · fail-soft 装配隔离` | 注入抛错工厂 → 其余仍装配 + assembly-error 记录 | + +--- + +## 2. 真运行时冒烟 ⛔ 受网络阻断 + +### 2.1 精确阻断点 + +`PhysicalByteAgent.launch()` → `import("@earendil-works/pi-coding-agent")` → +`createAgentSession()` 需要 pi **已构建**(`dist/`)。pi 构建(`npm run build:offline`) +前置 `check:model-data`,后者要求 `packages/ai/src/providers/data/*.json` 存在 —— +**该目录当前不存在**(连目录都没建)。这些 JSON 由 `generate-models.ts` 水合, +而该脚本需联网(见下)。 + +### 2.2 build:offline 实测失败(证据) + +``` +$ cd ../pi && npm run build:offline 2>&1 | tail -15 + +> @earendil-works/pi-ai@0.84.1 build:offline +> npm run check:model-data && tsgo -p tsconfig.build.json && ... + +> @earendil-works/pi-ai@0.84.1 check:model-data +> node scripts/check-model-data.ts + +amazon-bedrock.json is not valid JSON: ENOENT: no such file or directory, open +'/Users/d-robotics/Desktop/pi/packages/ai/src/providers/data/amazon-bedrock.json' + +Model data is missing or stale. Run `npm run hydrate:model-data` from the repository root. +npm error Lifecycle script `check:model-data` failed with error code 1 +``` + +失败发生在 `check:model-data`(build:offline 链第一步),因为 +`packages/ai/src/providers/data/` 目录不存在。 + +### 2.3 generate-models 网络依赖(不可离线水合) + +`packages/ai/scripts/generate-models.ts` 引用的远端端点(需联网 + 各厂商凭据): + +- `https://api.together.ai/v1`(Together AI) +- `https://ai-gateway.vercel.sh/v1`(Vercel AI Gateway) +- `https://{location}-aiplatform.googleapis.com`(Vertex AI) +- `https://integrate.api.nvidia.com/v1`(NVIDIA) +- `https://bedock-runtime.*.amazonaws.com`(Amazon Bedrock) +- `fetch(`${NVIDIA_BASE_URL}/models`)` —— 实际网络抓取 + +故 `npm run generate-models` / `hydrate:model-data` 在当前离线环境下不可行(需网络 + +可能需厂商 API key)。这是 T01 真运行时冒烟的网络硬阻断,非代码缺陷。 + +--- + +## 3. 诚实发现(非伪造) + +### 3.1 安全门 decimal devmem 缺口 + +当前 `safety-gate.ts` 的 `devmem-write` 正则只匹配 `0x` 前缀地址: + +```ts +pattern: /\bdevmem2?\s+0x[0-9a-fA-F]+\s+\b(w|write)\b/i +``` + +故 `devmem 1073872896 w 0x1`(十进制裸跑)**不被拦截**。这正是命门二(hex 强转砖板) +的残余面 —— 由 `glm-provider.normalizeHexArg` 在 `prepareArguments` 阶段先归一为 +`0x40020000` 再过门来兜底。链路已端到端验证(§1.4)。 + +对抗测试额外暴露的残余风险(非 decimal,归一也兜不住): +- 引号变形 `d'e'vmem 0x40020000 w` → 绕过词边界,不拦截 +- 变量间接 `devmem=$cmd; $devmem 0x40020000 w` → 不拦截 + +这些是 safety-gate 正则方案的固有局限,建议后续考虑命令 AST 化或 shell 展开后再匹配。 + +### 3.2 21 工厂全成功(mock 下) + +离线 mock 下 21/21 工厂成功装配、24 工具注册、0 错误。这是真实结果 —— +pi 源码在 vitest alias 下可解析,`defineTool`/`Type` 真实可用。未伪造。 + +--- + +## 4. 解除阻断的下一步 + +1. **网络访问**:在可联网环境跑 `cd ../pi && npm run hydrate:model-data` + (或 `npm run generate-models`)水合 `packages/ai/src/providers/data/*.json`。 +2. **构建 pi**:`cd ../pi && npm run build:offline` 生成 `dist/`。 +3. **真运行时冒烟**:`cd physical_byte_agent && npx tsx bin/pba.ts --print-extensions` + 触发 `PhysicalByteAgent.launch()` → `createAgentSession()`。 +4. (可选)vendor 模型数据:把水合后的 `data/*.json` 提交进仓库,彻底离线可用。 + +--- + +## 5. 诚实状态行 + +> **T01 离线装配冒烟 ✅(71/71 测试绿,21 工厂装配 + 安全门钩子 + T02 链路打通); +> 真运行时冒烟 ⛔ 受网络阻断(pi 模型数据 `packages/ai/src/providers/data/` 缺失, +> 需联网 `hydrate:model-data`)。** + +--- + +## 附:交付物 + +- `tests/e2e-smoke.test.ts`(728 行)—— 6 类测试方法 + FakePi mock + 装配冒烟 +- `docs/postmortem/0001-e2e-smoke.md`(本文件) + +**未触碰**:`src/` 下任何文件(并发 agent 编辑中,只读);`scripts/`。 + +--- + +## 更正(2026-08-14):T01 真运行时 boot 已离线验证 ✅ + +前文"运行时 ⛔ 网络"的判定**过于悲观**,已证伪。补充实测: + +`tests/e2e-runtime.test.ts` 通过 vitest 的 pi 源码别名(无需 `build:offline`)直接调真 +`createAgentSession({ agentDir, sessionManager: SessionManager.inMemory(), thinkingLevel:"off" })`: + +- **boot 成功,无异常,无 modelFallbackMessage**:pi-coding-agent 源码加载不需要 + `packages/ai/src/providers/data/`(pi-ai 模型 catalog 在 coding-agent 启动期不 eager-load); + pba barrel 经 pi 自动发现装配 → glm-provider 注册 drobotics-glm → glm-5.2 模型解析成功(无回退)。 +- session 内部状态真实(`_followUpMessages`/`_compactionAbortController` 等), + `extensionsResult = { extensions, errors, runtime }`。 + +**重新厘清阻塞边界**(之前的混淆点): +| 路径 | 状态 | 说明 | +|---|---|---| +| `createAgentSession` boot(vitest 源码别名) | ✅ 离线 | 真启动,不依赖 catalog | +| `bin/pba.ts`(tsx 解析到空 `dist`) | ⛔ 需 build | 需 `build:offline`(卡 `check:model-data`) | +| `build:offline` | ⛙ 网络 | 需 `generate-models`(Cloudflare)填 `providers/data/` | +| 真 LLM 推理一轮 turn | ⛙ 网络+key | 需 glm 网关 + 真 `${DROBOTICS_LLM_KEY}` | + +**结论**:T01 真运行时冒烟的"agent 能 boot 到可跑 turn"目标已离线达成(createAgentSession +真建 + 真装配 + 模型真解析)。剩余的是"真模型推理一轮"(需 key+网络)与"`bin/pba.ts` dist +分发"(需 build),均非"能跑"的硬阻塞,属运维/分发层。T01 状态更正为 ✅(离线 boot 验证)。 diff --git a/native/landlock-run/Makefile b/native/landlock-run/Makefile new file mode 100644 index 0000000..5e06bb4 --- /dev/null +++ b/native/landlock-run/Makefile @@ -0,0 +1,35 @@ +# landlock-run — 板侧沙箱 runner 构建规则(T05b) +# +# 真板部署:aarch64-linux musl 静态二进制(RDK X5/S100/S600,内核 ≥5.13)。 +# 宿主侧语法检查/契约测试:native(macOS/Linux)stub。 + +CC ?= cc +CFLAGS ?= -std=c11 -Wall -Wextra -O2 +SRC := landlock-run.c + +## 宿主侧 stub(macOS/Linux 通用;macOS 走 non-linux stub,Linux 无 landlock 头则缺) +.PHONY: native +native: + $(CC) $(CFLAGS) -o landlock-run-stub $(SRC) + +## 语法检查(不产二进制,CI 用) +.PHONY: syntax +syntax: + $(CC) $(CFLAGS) -fsyntax-only $(SRC) + +## aarch64-linux musl 静态(真板部署目标)。需 aarch64-linux-musl-gcc 在 PATH。 +## 安装:brew install FiloSottile/musl-cross/musl-cross(aarch64)或用 Docker toolchain。 +AARCH64_MUSL_CC ?= aarch64-linux-musl-gcc +.PHONY: cross-aarch64 +cross-aarch64: + $(AARCH64_MUSL_CC) -static -std=c11 -Wall -Wextra -O2 -o landlock-run-aarch64 $(SRC) + +## aarch64-linux-gnu glibc(若板上有 glibc + linux/landlock.h) +AARCH64_GNU_CC ?= aarch64-linux-gnu-gcc +.PHONY: cross-aarch64-gnu +cross-aarch64-gnu: + $(AARCH64_GNU_CC) -std=c11 -Wall -Wextra -O2 -o landlock-run-aarch64-gnu $(SRC) + +.PHONY: clean +clean: + rm -f landlock-run-stub landlock-run-aarch64 landlock-run-aarch64-gnu diff --git a/native/landlock-run/README.md b/native/landlock-run/README.md new file mode 100644 index 0000000..94e8f2d --- /dev/null +++ b/native/landlock-run/README.md @@ -0,0 +1,51 @@ +# landlock-run — 板侧命令沙箱 runner(T05b) + +板侧 Landlock 沙箱真身,嫁接 dsh `native/landlock-run`(C11,self-restrict-then-exec)到 pba。 + +## 设计 + +- `src/core/sandbox-policy.ts` 的 `applySandboxToArgv` 产出 argv 形如 + `["pba-board-sandbox","--ro",...,"--rw",...,"--",cmd,...]`;本程序即 `pba-board-sandbox` 真身。 +- 解析策略 → 建 Landlock ruleset(`LANDLOCK_RULE_PATH_ACCESS`,ro=读+执行,rw=读+写+执行+建/删)→ + `prctl(PR_SET_NO_NEW_PRIVS)` → `landlock_restrict_self` → `execvp(cmd)`。 + ruleset 跨 execve 继承(内核保证),子进程受同一围栏约束。 +- **fail-closed**:landlock 不可用(内核 <5.13 / 未编入 / syscall 号缺失)或 ruleset 构建失败 → + **拒绝 exec**(exit 126),与 `sandbox-policy.ts` 的 `unusable → exitCode 126` 对齐。 +- **probe 子命令**:`landlock-run --probe` → exit code 映射 `SandboxCapability`: + `0=full` / `1=partial` / `2=unusable`。`sandbox-policy.ts` 的 `probeViaBinary` 消费此契约。 + +## 构建 + +| 目标 | 命令 | 产物 | 用途 | +|---|---|---|---| +| 宿主 stub | `make native` | `landlock-run-stub` | macOS/Linux 契约测试(macOS 走 non-linux stub:probe 报 unusable) | +| 语法检查 | `make syntax` | — | CI(`clang -fsyntax-only`) | +| aarch64 musl 静态 | `make cross-aarch64` | `landlock-run-aarch64` | **真板部署**(需 `aarch64-linux-musl-gcc`) | +| aarch64 gnu | `make cross-aarch64-gnu` | `landlock-run-aarch64-gnu` | 板上有 glibc 时 | + +交叉编译器安装: +- musl 静态:`brew install FiloSottile/musl-cross/musl-cross`(aarch64 支持)或 Docker `muslcc/aarch64`。 +- gnu glibc:`brew install aarch64-elf-gcc` 不含 linux headers;推荐用 Docker `dockcross/linux-arm64`。 + +## 用法 + +```bash +# 探能力 +./landlock-run --probe # exit 0/1/2 = full/partial/unusable + +# 沙箱执行 +./landlock-run --ro / --ro /proc --rw /workspace -- /usr/bin/devmem 0x40020000 w +``` + +## 与 sandbox-policy.ts 的接线 + +`src/core/sandbox-policy.ts` 的 `probeViaBinary(binaryPath)` 执行 `landlock-run --probe`, +按 exit code 映射 `SandboxCapability`。板侧部署时 `PBA_BOARD_SANDBOX_BINARY` 环境变量指向 +本二进制路径,`resolveBoardSandbox` 优先用 binary probe(真 landlock),否则退回 env-var 模拟。 + +## 当前状态 + +- ✅ C 源(landlock path `__linux__` 守卫 + raw syscall;macOS stub 语法检查 + 契约验证通过) +- ✅ 宿主 stub:`make native` + `--probe` exit 2 验证 +- ⏳ aarch64 真二进制:本机无交叉编译器(无 aarch64-linux-musl-gcc / docker),真板部署需在 + 有 toolchain 的环境跑 `make cross-aarch64`。源码就绪,缺的只是 toolchain。 diff --git a/native/landlock-run/landlock-run.c b/native/landlock-run/landlock-run.c new file mode 100644 index 0000000..8251e85 --- /dev/null +++ b/native/landlock-run/landlock-run.c @@ -0,0 +1,260 @@ +/* + * landlock-run — 板侧命令沙箱 runner(T05b)。 + * + * 嫁接 dsh `native/landlock-run`(C11,self-restrict-then-exec)到 pba: + * pba board-link 的 applySandboxToArgv 产出的 argv 形如 + * ["pba-board-sandbox","--ro",...,"--rw",...,"--",cmd,args...] + * 本程序即 pba-board-sandbox 的真身:解析策略 → 建 landlock ruleset → + * 自限制(LANDLOCK_RULE_PATH_ACCESS)→ execve(cmd),ruleset 跨 execve 继承 + * (内核保证),fail-closed:landlock 不可用或建规则失败 → 拒绝 exec(exit 126)。 + * + * 设计要点(与 dsh native/landlock-run 对齐): + * - 不依赖 glibc landlock 包装(老 glibc 可能无 landlock_* 符号),用 raw syscall() + * 调 __NR_landlock_create_ruleset / __NR_landlock_add_rule / __NR_landlock_restrict_self。 + * - 单一 home 策略:只读根集 + 读写根集,与 src/core/sandbox-policy.ts 对齐。 + * - probe 子命令:`landlock-run --probe` → 探 landlock 能力,exit code 映射 + * 0=full / 1=partial / 2=unusable,对齐 SandboxCapability。 + * + * 仅 Linux(aarch64 RDK X5/S100/S600,内核 ≥5.13)真跑;macOS 下 __linux__ 守卫 + * 走 stub(--probe 报 unusable,-- 走 execve 真跑但不沙箱),便于语法检查与宿主侧 + * argv 契约测试。真板部署用 `make cross-aarch64` 交叉编译 musl 静态二进制。 + * + * 用法: + * landlock-run --probe + * landlock-run --ro / --ro /proc --rw /workspace -- /usr/bin/devmem 0x40020000 w + */ + +#ifdef __linux__ +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +# include +#else +/* 非 Linux(macOS 语法检查/宿主侧 stub):landlock 不可用 */ +# include +# include +# include +# include +# include +# define LANDLOCK_CREATE_RULESET_VERSION 1 +#endif + +/* ---------- raw landlock syscalls(Linux) ---------- */ +#ifdef __linux__ +#ifndef __NR_landlock_create_ruleset +/* 兜底:旧内核无 syscall 号 → 不可用 */ +#define NO_LANDLOCK_SYSCALL 1 +#endif + +static long landlock_create_ruleset(const void *attr, size_t size, unsigned int flags) { +#ifdef NO_LANDLOCK_SYSCALL + errno = ENOSYS; + return -1; +#else + return syscall(__NR_landlock_create_ruleset, attr, size, flags); +#endif +} + +static long landlock_add_rule(int fd, int type, const void *rule, unsigned int flags) { +#ifdef NO_LANDLOCK_SYSCALL + errno = ENOSYS; + return -1; +#else + return syscall(__NR_landlock_add_rule, fd, (long)type, rule, (long)flags); +#endif +} + +static long landlock_restrict_self(int fd, unsigned int flags) { +#ifdef NO_LANDLOCK_SYSCALL + errno = ENOSYS; + return -1; +#else + return syscall(__NR_landlock_restrict_self, fd, (long)flags); +#endif +} +#endif /* __linux__ */ + +/* ---------- probe ---------- */ +/* exit code 映射 SandboxCapability: 0=full 1=partial 2=unusable */ +#define PROBE_FULL 0 +#define PROBE_PARTIAL 1 +#define PROBE_UNUSABLE 2 + +static int probe_landlock(void) { +#ifdef __linux__ +#ifdef NO_LANDLOCK_SYSCALL + return PROBE_UNUSABLE; /* 编译期已知无 landlock syscall 号 */ +#else + /* 先探 ABI 版本:landlock_create_ruleset(NULL, 0, 0) 返回支持的 ruleset 版本 */ + int abi = (int)syscall(__NR_landlock_create_ruleset, NULL, 0, 0); + if (abi < 0) { + /* ENOSYS / EOPNOTSUPP → landlock 不可用(内核 <5.13 或未编入)→ unusable */ + if (errno == ENOSYS || errno == EOPNOTSUPP || errno == EINVAL) { + return PROBE_UNUSABLE; + } + return PROBE_UNUSABLE; + } + /* ABI ≥1 → landlock 可用。seccomp-only 回退(partial)不在此探;内核 ≥5.13=full */ + return PROBE_FULL; +#endif +#else + /* 非 Linux:永远 unusable(macOS 无 landlock) */ + return PROBE_UNUSABLE; +#endif +} + +/* ---------- ruleset 构建(Linux) ---------- */ +#ifdef __linux__ +#ifndef NO_LANDLOCK_SYSCALL +struct landlock_path_beneath_attr { + __u64 allowed_access; + __s64 parent_fd; +}; + +/* 构建一个只读+读写规则集,限制 path 访问。失败返回 -1(fail-closed)。 */ +static int build_ruleset(char **ro_roots, int ro_n, char **rw_roots, int rw_n) { + struct landlock_ruleset_attr { + __u64 handled_access_fs; + } attr; + /* 拦截所有常见 fs 访问(读/写/执行/设备/...) */ + attr.handled_access_fs = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_WRITE_FILE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR | + LANDLOCK_ACCESS_FS_REMOVE_DIR | + LANDLOCK_ACCESS_FS_REMOVE_FILE | + LANDLOCK_ACCESS_FS_MAKE_CHAR | + LANDLOCK_ACCESS_FS_MAKE_DIR | + LANDLOCK_ACCESS_FS_MAKE_REG | + LANDLOCK_ACCESS_FS_MAKE_SOCK | + LANDLOCK_ACCESS_FS_MAKE_FIFO | + LANDLOCK_ACCESS_FS_MAKE_BLOCK | + LANDLOCK_ACCESS_FS_MAKE_SYM; + + int fd = (int)landlock_create_ruleset(&attr, sizeof(attr), 0u); + if (fd < 0) return -1; + + __u64 ro_access = LANDLOCK_ACCESS_FS_READ_FILE | LANDLOCK_ACCESS_FS_READ_DIR | LANDLOCK_ACCESS_FS_EXECUTE; + __u64 rw_access = ro_access | LANDLOCK_ACCESS_FS_WRITE_FILE | LANDLOCK_ACCESS_FS_REMOVE_FILE | + LANDLOCK_ACCESS_FS_REMOVE_DIR | LANDLOCK_ACCESS_FS_MAKE_REG | LANDLOCK_ACCESS_FS_MAKE_DIR | + LANDLOCK_ACCESS_FS_MAKE_SYM; + + for (int i = 0; i < ro_n; i++) { + int pfd = open(ro_roots[i], O_PATH | O_CLOEXEC); + if (pfd < 0) { close(fd); return -1; } + struct landlock_path_beneath_attr rule = { .allowed_access = ro_access, .parent_fd = pfd }; + if (landlock_add_rule(fd, LANDLOCK_RULE_PATH_BENEATH, &rule, 0u) < 0) { + close(pfd); close(fd); return -1; + } + close(pfd); + } + for (int i = 0; i < rw_n; i++) { + int pfd = open(rw_roots[i], O_PATH | O_CLOEXEC); + if (pfd < 0) { close(fd); return -1; } + struct landlock_path_beneath_attr rule = { .allowed_access = rw_access, .parent_fd = pfd }; + if (landlock_add_rule(fd, LANDLOCK_RULE_PATH_BENEATH, &rule, 0u) < 0) { + close(pfd); close(fd); return -1; + } + close(pfd); + } + return fd; +} +#endif /* NO_LANDLOCK_SYSCALL */ +#endif /* __linux__ */ + +/* ---------- arg 解析 + exec ---------- */ +#define MAX_ROOTS 64 + +static void usage(const char *prog) { + fprintf(stderr, + "usage: %s --probe\n" + " %s [--ro ROOT]... [--rw ROOT]... -- CMD [ARGS...]\n" + "exit codes: 0=full 1=partial 2=unusable (probe); 126=refused(fail-closed)\n", + prog, prog); +} + +int main(int argc, char **argv) { + if (argc < 2) { usage(argv[0]); return PROBE_UNUSABLE; } + + /* --probe 子命令 */ + if (strcmp(argv[1], "--probe") == 0) { + return probe_landlock(); + } + + /* 解析 --ro / --rw / -- */ + char *ro_roots[MAX_ROOTS]; int ro_n = 0; + char *rw_roots[MAX_ROOTS]; int rw_n = 0; + int i = 1; + while (i < argc) { + if (strcmp(argv[i], "--ro") == 0) { + if (i + 1 >= argc || ro_n >= MAX_ROOTS) { usage(argv[0]); return 126; } + ro_roots[ro_n++] = argv[i + 1]; + i += 2; + } else if (strcmp(argv[i], "--rw") == 0) { + if (i + 1 >= argc || rw_n >= MAX_ROOTS) { usage(argv[0]); return 126; } + rw_roots[rw_n++] = argv[i + 1]; + i += 2; + } else if (strcmp(argv[i], "--") == 0) { + i++; /* 指向 cmd */ + break; + } else { + usage(argv[0]); + return 126; + } + } + if (i >= argc) { usage(argv[0]); return 126; } /* 缺 cmd */ + + char **cmd_argv = &argv[i]; + /* ---------- 沙箱构建 + exec ---------- */ +#ifdef __linux__ +#ifndef NO_LANDLOCK_SYSCALL + /* 先探能力:unusable → fail-closed 拒绝 exec */ + int cap = probe_landlock(); + if (cap == PROBE_UNUSABLE) { + fprintf(stderr, "[landlock-run] unusable: landlock not available — refusing exec (fail-closed)\n"); + return 126; + } + /* 构建规则集 */ + int ruleset_fd = build_ruleset(ro_roots, ro_n, rw_roots, rw_n); + if (ruleset_fd < 0) { + fprintf(stderr, "[landlock-run] ruleset build failed (%s) — refusing exec (fail-closed)\n", + strerror(errno)); + return 126; + } + /* 自限制:restrict_self 后,本进程及 execve 出的子进程都受规则集约束(内核继承) */ + if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) < 0) { + close(ruleset_fd); + fprintf(stderr, "[landlock-run] prctl(NO_NEW_PRIVS) failed — refusing exec\n"); + return 126; + } + if (landlock_restrict_self(ruleset_fd, 0u) < 0) { + close(ruleset_fd); + fprintf(stderr, "[landlock-run] restrict_self failed (%s) — refusing exec\n", strerror(errno)); + return 126; + } + close(ruleset_fd); + /* exec:规则集已生效并跨 execve 继承 */ + execvp(cmd_argv[0], cmd_argv); + fprintf(stderr, "[landlock-run] exec %s failed (%s)\n", cmd_argv[0], strerror(errno)); + return 126; +#else + /* 编译期无 landlock syscall号:fail-closed 拒绝(不应在真板出现) */ + fprintf(stderr, "[landlock-run] built without landlock syscall numbers — refusing exec\n"); + return 126; +#endif +#else + /* 非 Linux(macOS stub):不沙箱,直接 exec(仅 argv 契约验证用) */ + fprintf(stderr, "[landlock-run] non-linux stub: no landlock, exec without sandbox\n"); + execvp(cmd_argv[0], cmd_argv); + fprintf(stderr, "[landlock-run] exec %s failed (%s)\n", cmd_argv[0], strerror(errno)); + return 126; +#endif +} diff --git a/src/core/sandbox-policy.ts b/src/core/sandbox-policy.ts new file mode 100644 index 0000000..09b78df --- /dev/null +++ b/src/core/sandbox-policy.ts @@ -0,0 +1,317 @@ +/** + * @module sandbox-policy + * + * 板侧沙箱策略 —— 物理字节 Agent 的命令执行安全门第一层。 + * + * dsh 用 Landlock(Linux 5.13+,C11 `native/landlock-run`)+ sandbox-local + * (bwrap/Seatbelt/ACL)+ 单一 `sandbox-policy` home。pba 嫁接这个板侧能力。 + * T05a 用 shell-script runner 模拟(真实 landlock-run 交叉编译 C 是 T05b,延后)。 + * + * 三件事(纯逻辑,零 pi 依赖,可离线单测): + * ① DEFAULT_BOARD_SANDBOX_POLICY —— 单一共享策略 home(board-link + flash 都引用) + * ② probeSandbox —— 探活板侧 runner + 内核版本,判定 full/partial/unusable + * ③ applySandboxToArgv —— 用策略包装 argv(模拟 runner token 前缀) + * + * fail-closed 语义(安全不变式 —— 见 tests/sandbox-policy.test.ts ⑥): + * - runner 不可用 → capability="unusable" → shouldRunCommand=false → 调用方拒绝执行 + * - runner 可用但内核版本不可解析/缺失 → "unusable"(安全默认,文档化) + * - runner 可用 + 内核 < 5.13(无 Landlock)→ "partial"(seccomp-only 回退,仍可跑但降级) + * - runner 可用 + 内核 ≥ 5.13 → "full"(Landlock 完整) + * + * 正交阶段(单一职责,无副作用,确定性可测): + * parseKernelVersion(纯解析)→ probeSandbox(判定能力) + * → shouldRunCommand(执行门)→ applySandboxToArgv(包装) + * + * 范式:纯逻辑模块,无顶层 import type 以外的 pi 依赖;无副作用;确定性可测。 + * 见架构设计文档_v3.md §6.1 / §5.4。 + */ + +// ============================================================================ +// 命名常量 —— 消灭魔法串(runner token / 命令行 flag / Landlock 门槛) +// ============================================================================ + +/** 板侧沙箱 runner 的模拟 token(T05a shell-script;T05b 替换为 landlock-run 二进制)。 */ +export const RUNNER_TOKEN = "pba-board-sandbox"; +/** 只读根 flag。 */ +export const FLAG_READ_ONLY = "--ro"; +/** 读写根 flag。 */ +export const FLAG_READ_WRITE = "--rw"; +/** 策略根与原始命令的分隔符。 */ +export const FLAG_SEPARATOR = "--"; +/** Landlock 可用的最低内核主版本(Linux 5.13 引入 Landlock)。 */ +const LANDLOCK_MAJOR = 5; +/** Landlock 可用的最低内核次版本。 */ +const LANDLOCK_MINOR = 13; + +// ============================================================================ +// 类型 +// ============================================================================ + +/** + * 沙箱能力等级。 + * + * - "full" —— runner 可用 + 内核 ≥ 5.13(Landlock 完整) + * - "partial" —— runner 可用 + 内核 < 5.13(seccomp-only 回退,降级但仍可跑) + * - "unusable" —— runner 不可用(fail-closed,调用方必须拒绝执行) + */ +export type SandboxCapability = "full" | "partial" | "unusable"; + +/** + * 板侧沙箱策略 —— 单一共享 home。 + * + * board-link 和 flash 都引用 DEFAULT_BOARD_SANDBOX_POLICY(同一对象引用), + * 保证全 Agent 一套读写根策略,不分散在多处。 + * readonly 字段防止运行时意外篡改(默认策略另加 Object.freeze 冻结)。 + */ +export interface BoardSandboxPolicy { + /** 只读挂载根(Landlock 只读路径)。 */ + readonly readOnlyRoots: readonly string[]; + /** 读写挂载根(Landlock 读写路径)。 */ + readonly readWriteRoots: readonly string[]; + /** 可选:允许的 syscall 白名单(seccomp 过滤,T05a 模拟 runner 不消费)。 */ + readonly allowedSyscalls?: readonly string[]; +} + +/** + * 沙箱探活结果。 + */ +export interface SandboxProbeResult { + /** 能力等级。 */ + readonly capability: SandboxCapability; + /** 原因(诊断/日志用)。 */ + readonly reason: string; +} + +/** + * applySandboxToArgv 的包装结果。 + */ +export interface SandboxWrapResult { + /** 包装后的 argv(unusable 时原样返回)。 */ + readonly argv: readonly string[]; + /** 是否已沙箱包装(unusable 时 false —— 调用方应据此拒绝执行)。 */ + readonly sandboxed: boolean; +} + +// ============================================================================ +// 默认策略 —— 单一共享 home(深冻结,运行时不可变) +// ============================================================================ + +/** + * 默认板侧沙箱策略 —— 单一共享 home。 + * + * board-link(makeExec 包装)和 flash(烧录命令包装,TODO 另一 agent 接线) + * 都 import 这个常量,保证读写根策略全 Agent 一套。 + * + * 默认:只读全文件系统根 "/",读写工作目录 "/workspace"。 + * 深冻结(Object.freeze 对象 + 嵌套数组):运行时任何篡改尝试抛 TypeError。 + * + * flash 接线由另一 agent 拥有(见架构文档 §5.4)—— 本模块只导出常量,不改 flash.ts。 + */ +export const DEFAULT_BOARD_SANDBOX_POLICY: BoardSandboxPolicy = Object.freeze({ + readOnlyRoots: Object.freeze(["/"]), + readWriteRoots: Object.freeze(["/workspace"]), +}) as BoardSandboxPolicy; + +// ============================================================================ +// parseKernelVersion —— 纯解析(导出供测试 + 调用方诊断) +// ============================================================================ + +/** + * 解析内核版本串为 {major, minor}。 + * + * 接受形态(fail-tolerant,鲁棒解析): + * - "5.13.0-foo" → {5,13}(三段,后缀忽略) + * - "5.13" → {5,13}(两段,无 patch) + * - "5" → {5,0}(单段,minor 默认 0) + * - "v5.13" → {5,13}(v/V 前缀剥离) + * - "5.13.0-rc1" → {5,13}(rc 后缀剥离) + * - undefined / "" / " " → null(缺失) + * - "not-a-version" → null(不可解析) + * + * @param raw 内核版本串(undefined 表示缺失)。 + * @returns {major, minor} 或 null。 + */ +export function parseKernelVersion( + raw: string | undefined, +): { major: number; minor: number } | null { + // 缺失 → null + if (raw === undefined) return null; + const trimmed = raw.trim(); + // 空串 / 纯空白 → null + if (trimmed === "") return null; + // 剥离 v/V 前缀("v5.13" → "5.13") + const stripped = trimmed.replace(/^[vV]/, ""); + // 取首段数字:可能 "5.13.0-foo" / "5.13" / "5" + const match = stripped.match(/^(\d+)(?:\.(\d+))?/); + if (!match || match[1] === undefined) return null; + const major = Number.parseInt(match[1], 10); + const minor = match[2] !== undefined ? Number.parseInt(match[2], 10) : 0; + if (Number.isNaN(major) || Number.isNaN(minor)) return null; + return { major, minor }; +} + +// ============================================================================ +// probeSandbox —— 探活 + 内核版本判定 +// ============================================================================ + +/** + * 探活板侧沙箱 runner + 内核版本,判定能力等级。 + * + * fail-closed 决策树(见 tests/sandbox-policy.test.ts ② 决策表): + * 1. runner 不可用 → "unusable"(fail-closed,拒绝执行) + * 2. runner 可用 + 内核版本不可解析/缺失 → "unusable"(安全默认 —— 不知内核是否支持 + * Landlock 时拒绝执行,fail-closed;文档化) + * 3. runner 可用 + 内核 ≥ 5.13 → "full"(Landlock 完整) + * 4. runner 可用 + 内核 < 5.13 → "partial"(seccomp-only 回退,降级但仍可跑) + * + * @param runnerAvailable 板侧 sandbox runner 是否可用。 + * @param kernel 内核版本串(可选,"5.13.0-foo" / "v5.13" / "5" / undefined)。 + * @returns 探活结果。 + */ +export function probeSandbox( + runnerAvailable: boolean, + kernel?: string, +): SandboxProbeResult { + // 1. fail-closed:runner 不可用 → unusable + if (!runnerAvailable) { + return { + capability: "unusable", + reason: "board-side sandbox runner not available", + }; + } + + // 2. runner 可用 + 内核不可解析/缺失 → unusable(安全默认) + const parsed = parseKernelVersion(kernel); + if (parsed === null) { + const k = kernel && kernel.trim() !== "" ? kernel : "(missing)"; + return { + capability: "unusable", + reason: `kernel version ${k} unparseable — fail-closed unusable (safe default)`, + }; + } + + // 3. Landlock 需要 Linux 5.13+ + if ( + parsed.major > LANDLOCK_MAJOR || + (parsed.major === LANDLOCK_MAJOR && parsed.minor >= LANDLOCK_MINOR) + ) { + return { + capability: "full", + reason: `kernel ${parsed.major}.${parsed.minor} >= 5.13 — Landlock available`, + }; + } + + // 4. runner 可用 + 内核 < 5.13 → partial(seccomp-only 回退) + return { + capability: "partial", + reason: `kernel ${parsed.major}.${parsed.minor} < 5.13 — seccomp-only fallback (no Landlock)`, + }; +} + +// ============================================================================ +// shouldRunCommand —— fail-closed 执行门 +// ============================================================================ + +/** + * 判定是否应执行命令。 + * + * fail-closed:capability="unusable" → false(拒绝执行)。 + * full / partial → true(可执行,partial 降级但仍可跑)。 + * + * @param probe 探活结果。 + * @returns true=可执行,false=拒绝。 + */ +export function shouldRunCommand(probe: SandboxProbeResult): boolean { + return probe.capability !== "unusable"; +} + +// ============================================================================ +// probeViaBinary —— 真 landlock-run 二进制探活(T05b 接线) +// ============================================================================ + +import { spawnSync } from "node:child_process"; + +/** + * 二进制 runner 抽象(注入以便单测,避免真 spawn)。返回 exitCode(null=未退出/信号)。 + */ +export type SandboxBinaryRunner = (binaryPath: string) => { exitCode: number | null; stderr: string }; + +/** 默认 runner:同步 spawn `binaryPath --probe`,取 exit code。 */ +export const defaultBinaryRunner: SandboxBinaryRunner = (binaryPath) => { + const res = spawnSync(binaryPath, ["--probe"], { encoding: "utf8" }); + return { exitCode: res.status, stderr: res.stderr ?? "" }; +}; + +/** + * 调真 `landlock-run --probe`,按 exit code 映射 SandboxCapability(T05b)。 + * + * 契约(见 native/landlock-run/landlock-run.c):exit 0=full / 1=partial / 其它=unusable。 + * fail-closed:spawn 失败或 exit code 非 0/1 → unusable(不跑命令)。 + * + * @param binaryPath landlock-run 二进制路径。 + * @param runner 注入的 runner(默认 spawnSync,单测可 mock)。 + * @returns SandboxProbeResult。 + */ +export function probeViaBinary( + binaryPath: string, + runner: SandboxBinaryRunner = defaultBinaryRunner, +): SandboxProbeResult { + try { + const { exitCode } = runner(binaryPath); + if (exitCode === 0) { + return { capability: "full", reason: "binary probe exit 0 (landlock full)" }; + } + if (exitCode === 1) { + return { capability: "partial", reason: "binary probe exit 1 (seccomp-only fallback)" }; + } + return { + capability: "unusable", + reason: `binary probe exit ${exitCode ?? "null"} (fail-closed)`, + }; + } catch (e) { + return { capability: "unusable", reason: `binary probe failed: ${String(e)}` }; + } +} + +// ============================================================================ +// applySandboxToArgv —— 用策略包装 argv +// ============================================================================ + +/** + * 用沙箱策略包装 argv(模拟 runner token 前缀)。 + * + * T05a 用 shell-script runner 模拟,包装形式: + * [RUNNER_TOKEN, FLAG_READ_ONLY, ...readOnlyRoots, FLAG_READ_WRITE, ...readWriteRoots, FLAG_SEPARATOR, ...originalArgv] + * + * - capability="unusable" → 原样返回 argv + sandboxed:false(调用方应拒绝执行) + * - capability="full"|"partial" → 前缀 runner token + 策略根 + 分隔符 + 原始 argv + * + * 纯逻辑、确定性,无副作用,可单测。返回 readonly 数组防止调用方篡改包装结果。 + * + * @param argv 原始命令参数数组。 + * @param policy 沙箱策略(读写根)。 + * @param capability 探活判定的能力等级。 + * @returns 包装后的 argv + sandboxed 标记。 + */ +export function applySandboxToArgv( + argv: readonly string[], + policy: BoardSandboxPolicy, + capability: SandboxCapability, +): SandboxWrapResult { + // fail-closed:unusable → 不包装,调用方应拒绝执行 + if (capability === "unusable") { + return { argv, sandboxed: false }; + } + + // full / partial → 模拟 runner token 前缀 + const wrapped: string[] = [ + RUNNER_TOKEN, + FLAG_READ_ONLY, + ...policy.readOnlyRoots, + FLAG_READ_WRITE, + ...policy.readWriteRoots, + FLAG_SEPARATOR, + ...argv, + ]; + return { argv: wrapped, sandboxed: true }; +} diff --git a/src/core/tool-pipeline.ts b/src/core/tool-pipeline.ts new file mode 100644 index 0000000..63ce711 --- /dev/null +++ b/src/core/tool-pipeline.ts @@ -0,0 +1,316 @@ +/** + * @module tool-pipeline + * + * 五段工具执行流水线(T04)—— 嫁接 dsh `ToolRuntimeScheduler`(dsh + * `packages/core/tools/src/index.ts:451`)到 pba 扩展层。 + * + * 五段,正交、可组合、单一职责: + * ① pre-execute waterfall —— allow / deny / ask,listener 调 next() 委托 + * ② monotonic guards —— 身份保护,任一 deny 不可被 force-allow(单调不变式) + * ③ ctx.approval —— ask 的一次性裁决(fail-closed:无 resolver 则 deny) + * ④ execute around-waterfall—— timeout / retry / metrics 包裹 tool body + * ⑤ post-execute waterfall + finalizeContent —— accept / block / replace / add-context + * + * 与 dsh 的差异:不引 Cordis,自包含中间件链;guard 单调性靠"任一 deny ⟹ 终局 deny" + * 构造保证(非靠身份锁)。见架构设计文档_v3.md §5.3。 + * + * 纯逻辑 + 异步,零 pi 运行时依赖,可离线单测。 + */ + +// ============================================================================ +// 上下文 + 基础类型 +// ============================================================================ + +/** 一次工具调用的不可变上下文。 */ +export interface ToolCallContext { + readonly toolName: string; + readonly input: unknown; + readonly toolCallId: string; + /** 取消信号(around 的 timeout 容器消费)。 */ + readonly signal?: AbortSignal; + /** finalizeContent(工具定义可选注入)。 */ + readonly finalizeContent?: FinalizeContent; + /** ask 裁决器(缺省 fail-closed:ask → deny)。 */ + readonly approvalResolver?: ApprovalResolver; + /** 透传字段。 */ + readonly [key: string]: unknown; +} + +/** 工具产出(content-only 是 finalizeContent 的硬不变式)。 */ +export interface ToolResult { + readonly content: unknown; + readonly isError?: boolean; + readonly details?: unknown; +} + +// ============================================================================ +// ① pre-execute + ② guard 裁决 +// ============================================================================ + +export type GuardVerdict = + | { readonly decision: "allow" } + | { readonly decision: "deny"; readonly reason: string } + | { readonly decision: "ask"; readonly reason: string }; + +/** + * 单调 guard —— 身份保护(带不可变 id)。任一 guard deny 即终局 deny, + * 不可被 pre-execute listener 或其他 guard 的 allow 覆盖(单调不变式)。 + */ +export interface MonotonicGuard { + readonly id: string; + evaluate(ctx: ToolCallContext): GuardVerdict | Promise; +} + +/** pre-execute listener 裁决:allow/deny/ask 或 abstain(调 next() 委托)。 */ +export type PreExecuteVerdict = GuardVerdict | "abstain"; + +export type PreExecuteListener = ( + ctx: ToolCallContext, + next: () => Promise, +) => Promise; + +// ============================================================================ +// ④ execute around +// ============================================================================ + +export type ToolBody = (ctx: ToolCallContext) => Promise; + +/** around listener:包裹 tool body(timeout/retry/metrics)。调 next() 执行内层。 */ +export type AroundListener = (ctx: ToolCallContext, next: ToolBody) => Promise; + +// ============================================================================ +// ⑤ post-execute + finalizeContent +// ============================================================================ + +export type PostExecuteAction = + | { readonly action: "accept" } + | { readonly action: "block"; readonly reason: string } + | { readonly action: "replace"; readonly result: ToolResult } + | { readonly action: "addContext"; readonly context: unknown }; + +export type PostExecuteListener = ( + ctx: ToolCallContext, + result: ToolResult, + next: () => Promise, +) => Promise; + +/** + * finalizeContent —— 工具定义注入,materialize 前同步执行。 + * content-only 不变量:输出必须是"纯 content"(无嵌套 tool-call)。 + * 实现者负责把 details 等剥成 content;抛错 → snapshot 转 isError。 + */ +export type FinalizeContent = (result: ToolResult) => ToolResult; + +// ============================================================================ +// ③ approval +// ============================================================================ + +/** ask 裁决器。返回 true=allow-once,false=deny。无 resolver 时 ask→deny(fail-closed)。 */ +export type ApprovalResolver = (ctx: ToolCallContext, reason: string) => Promise; + +// ============================================================================ +// 终局裁决 +// ============================================================================ + +export type PipelineOutcome = + | { readonly outcome: "executed"; readonly result: ToolResult } + | { readonly outcome: "denied"; readonly reason: string } + | { readonly outcome: "blocked"; readonly reason: string; readonly result?: ToolResult } + | { readonly outcome: "replaced"; readonly result: ToolResult }; + +export type PreExecuteDecision = + | { readonly decision: "allow" } + | { readonly decision: "deny"; readonly reason: string }; + +// ============================================================================ +// ToolPipeline +// ============================================================================ + +/** + * 五段流水线调度器。模块级单例 {@link pipeline} 供 safety-gate 等扩展共用。 + * + * 单调性靠构造保证:guard verdicts 收集后 `find(deny)`,任一 deny 即终局 deny, + * pre-execute 的 allow 不参与 guard 聚合,故无法 force-allow。 + */ +export class ToolPipeline { + private readonly guards = new Map(); + private readonly preListeners: PreExecuteListener[] = []; + private readonly aroundListeners: AroundListener[] = []; + private readonly postListeners: PostExecuteListener[] = []; + + /** + * 注册单调 guard。id 唯一:重复 id 视为更新(替换 evaluate),不抛错—— + * 保证 barrel 重装配(测试多次装配 / session resume)幂等安全。返回 disposer。 + */ + registerGuard(guard: MonotonicGuard): () => void { + this.guards.set(guard.id, guard); + return () => this.guards.delete(guard.id); + } + + /** 注册 pre-execute listener。返回 disposer。 */ + onPreExecute(listener: PreExecuteListener): () => void { + this.preListeners.push(listener); + return () => { + const i = this.preListeners.indexOf(listener); + if (i >= 0) this.preListeners.splice(i, 1); + }; + } + + /** 注册 around listener(先注册=外层)。返回 disposer。 */ + onAround(listener: AroundListener): () => void { + this.aroundListeners.push(listener); + return () => { + const i = this.aroundListeners.indexOf(listener); + if (i >= 0) this.aroundListeners.splice(i, 1); + }; + } + + /** 注册 post-execute listener。返回 disposer。 */ + onPostExecute(listener: PostExecuteListener): () => void { + this.postListeners.push(listener); + return () => { + const i = this.postListeners.indexOf(listener); + if (i >= 0) this.postListeners.splice(i, 1); + }; + } + + /** 跑完整五段。 */ + async run(ctx: ToolCallContext, body: ToolBody): Promise { + // ①②③ pre-execute + guards + approval + const pre = await this.decide(ctx); + if (pre.decision === "deny") { + return { outcome: "denied", reason: pre.reason }; + } + + // ④ execute around-waterfall + const raw = await this.runAround(ctx, body); + + // ⑤ post-execute waterfall + const post = await this.runPostExecute(ctx, raw); + if (post.action === "block") { + return { outcome: "blocked", reason: post.reason, result: raw }; + } + const afterPost = post.action === "replace" ? post.result : raw; + + // finalizeContent(content-only 不变量) + const finalized = ctx.finalizeContent ? ctx.finalizeContent(afterPost) : afterPost; + return { outcome: post.action === "replace" ? "replaced" : "executed", result: finalized }; + } + + /** + * 只跑 ①②③(pre-execute + monotonic guards + approval),返回 allow/deny。 + * + * 供 safety-gate 的 tool_call 钩子用:钩子只能在执行前 block,不能跑 body, + * 故只取裁决阶段。单调性同 {@link run}:任一 guard deny ⟹ deny。 + */ + async decide(ctx: ToolCallContext): Promise { + const soft = await this.runPreExecute(ctx); + const guardVerdicts = await this.collectGuardVerdicts(ctx); + const deniedBy = guardVerdicts.find((v) => v.decision === "deny"); + if (deniedBy && deniedBy.decision === "deny") { + return { decision: "deny", reason: `[guard] ${deniedBy.reason}` }; + } + const denyFromSoft = soft?.decision === "deny" ? soft : undefined; + if (denyFromSoft && denyFromSoft.decision === "deny") { + return { decision: "deny", reason: `[pre-execute] ${denyFromSoft.reason}` }; + } + const guardAsk = guardVerdicts.find((v) => v.decision === "ask"); + const askVerdict = guardAsk?.decision === "ask" ? guardAsk : soft?.decision === "ask" ? soft : undefined; + if (askVerdict && askVerdict.decision === "ask") { + const resolver = ctx.approvalResolver; + if (!resolver) { + return { decision: "deny", reason: `[approval] ${askVerdict.reason} (no resolver, fail-closed)` }; + } + const allowed = await resolver(ctx, askVerdict.reason); + if (!allowed) { + return { decision: "deny", reason: `[approval] ${askVerdict.reason} (denied by user)` }; + } + } + return { decision: "allow" }; + } + + // ---- 内部:pre-execute waterfall(next() 委托) ---- + private async runPreExecute(ctx: ToolCallContext): Promise { + if (this.preListeners.length === 0) return undefined; + // 构造 next 链:listeners[i] 调 next() → 跑 listeners[i+1]…;末尾 abstain + let i = 0; + const next = async (): Promise => { + if (i >= this.preListeners.length) return "abstain"; + const listener = this.preListeners[i]; + i++; + return listener(ctx, next); + }; + const verdict = await next(); + return verdict === "abstain" ? undefined : verdict; + } + + // ---- 内部:guards 收集(全部评估,单调性靠聚合) ---- + private async collectGuardVerdicts(ctx: ToolCallContext): Promise { + const out: GuardVerdict[] = []; + for (const guard of this.guards.values()) { + out.push(await guard.evaluate(ctx)); + } + return out; + } + + // ---- 内部:around waterfall(先注册=外层) ---- + private async runAround(ctx: ToolCallContext, body: ToolBody): Promise { + let chain: ToolBody = body; + // 反向迭代:listeners[0] 成为最外层 + for (let i = this.aroundListeners.length - 1; i >= 0; i--) { + const listener = this.aroundListeners[i]; + const inner = chain; + chain = (c) => listener(c, inner); + } + return chain(ctx); + } + + // ---- 内部:post-execute waterfall(首个非 accept 生效;addContext 透传) ---- + private async runPostExecute(ctx: ToolCallContext, result: ToolResult): Promise { + if (this.postListeners.length === 0) return { action: "accept" }; + let i = 0; + const next = async (): Promise => { + if (i >= this.postListeners.length) return { action: "accept" }; + const listener = this.postListeners[i]; + i++; + return listener(ctx, result, next); + }; + return next(); + } +} + +/** 模块级单例:safety-gate 等扩展共用。 */ +export const pipeline = new ToolPipeline(); + +// ============================================================================ +// 通用 around 容器:timeout(fail-closed 超时即 isError) +// ============================================================================ + +/** + * timeout around 容器:body 超时 → 返回 isError 结果(不抛,转成 content)。 + * + * @param ms 超时毫秒。 + */ +export function withTimeout(ms: number): AroundListener { + return async (ctx, next) => { + const timeoutController = new AbortController(); + const timer = setTimeout(() => timeoutController.abort(), ms); + try { + // 竞速:body 完成 vs 超时 + const settled = await Promise.race([ + next(ctx).then((r) => ({ kind: "ok" as const, r })), + new Promise<{ kind: "timeout" }>((resolve) => + timeoutController.signal.addEventListener("abort", () => resolve({ kind: "timeout" }), { once: true }), + ), + ]); + if (settled.kind === "ok") return settled.r; + return { + content: [{ type: "text", text: `TIMEOUT: ${ctx.toolName} exceeded ${ms}ms` }], + isError: true, + details: { timeout: ms }, + }; + } finally { + clearTimeout(timer); + } + }; +} diff --git a/src/extensions/board-link.ts b/src/extensions/board-link.ts index 4858cca..dadb031 100644 --- a/src/extensions/board-link.ts +++ b/src/extensions/board-link.ts @@ -33,6 +33,15 @@ import type { ExecFn, ExecResult, } from "../shared/types.js"; +// 沙箱策略是纯逻辑模块(零 pi 依赖),可以值导入 —— 不破坏"顶层仅 import type"范式。 +import { + probeSandbox, + probeViaBinary, + applySandboxToArgv, + shouldRunCommand, + DEFAULT_BOARD_SANDBOX_POLICY, + type SandboxProbeResult, +} from "../core/sandbox-policy.js"; // 便于调用方一次性 import;类型本身定义在 shared/types.ts export type { BoardSpec, BoardLinkType, ExecFn, ExecResult }; @@ -172,6 +181,58 @@ export interface MakeExecResult { isStub: boolean; } +// ============================================================================ +// 板侧沙箱探活 —— fail-closed,单进程单次缓存 +// ============================================================================ + +/** + * 板侧沙箱探活缓存。同进程内只探一次(runner 不会从不可用变可用)。 + * 测试通过 PBA_BOARD_SANDBOX_RUNNER / PBA_BOARD_KERNEL 环境变量驱动。 + */ +let boardSandboxProbe: SandboxProbeResult | null = null; + +/** + * 重置沙箱探活缓存(测试用:切环境变量后重探)。 + */ +export function resetBoardSandboxProbe(): void { + boardSandboxProbe = null; +} + +/** + * 探活板侧沙箱 runner(单次缓存)。 + * + * 环境变量驱动(模拟 T05a shell-script runner 的可用性 + 内核版本): + * - PBA_BOARD_SANDBOX_RUNNER: "1"=可用, "0"或未设=不可用 → fail-closed unusable + * - PBA_BOARD_KERNEL: 内核版本串,如 "5.13.0-foo" + * + * fail-closed:未设环境变量 → runner 不可用 → unusable(拒绝执行)。 + * + * @returns 探活结果。 + */ +export function resolveBoardSandbox(): SandboxProbeResult { + if (boardSandboxProbe !== null) { + return boardSandboxProbe; + } + // T05b:若设了真二进制路径,优先调 landlock-run --probe(真 landlock 能力) + const binaryPath = process.env.PBA_BOARD_SANDBOX_BINARY; + if (binaryPath && binaryPath.length > 0) { + boardSandboxProbe = probeViaBinary(binaryPath); + return boardSandboxProbe; + } + const runnerFlag = process.env.PBA_BOARD_SANDBOX_RUNNER; + const runnerAvailable = runnerFlag === "1"; + const kernelVersion = process.env.PBA_BOARD_KERNEL; + boardSandboxProbe = probeSandbox(runnerAvailable, kernelVersion); + return boardSandboxProbe; +} + +/** 沙箱拒绝执行时的固定返回(fail-closed)。 */ +const SANDBOX_REFUSED_RESULT: ExecResult = { + stdout: "", + stderr: "[board-sandbox] board-side sandbox runner unusable — command refused (fail-closed)", + exitCode: 126, +}; + /** * 给定板 spec + 底层 exec(宿主 spawn),产出在该板执行命令的 ExecFn。 * @@ -187,20 +248,59 @@ export interface MakeExecResult { * @returns { exec, transport, isStub }。 */ export function makeExec(board: BoardSpec, underlying: ExecFn): MakeExecResult { + const probe = resolveBoardSandbox(); + const canRun = shouldRunCommand(probe); + switch (board.link) { case "ssh": { const exec: ExecFn = (command, args, opts) => { - return underlying("ssh", buildSshArgs(board, command, args), opts); + // fail-closed:沙箱不可用 → 拒绝执行,不 spawn + if (!canRun) { + return Promise.resolve(SANDBOX_REFUSED_RESULT); + } + const sshArgs = buildSshArgs(board, command, args); + // 沙箱包装 ssh argv(模拟 runner token 前缀) + const { argv: wrapped } = applySandboxToArgv( + sshArgs, + DEFAULT_BOARD_SANDBOX_POLICY, + probe.capability, + ); + // wrapped 是 readonly string[];ExecFn 期望 mutable string[],展开拷贝 + return underlying("ssh", [...wrapped], opts); }; return { exec, transport: `ssh:${board.address}`, isStub: false }; } case "serial": { - const exec: ExecFn = async () => SERIAL_STUB_RESULT; + const exec: ExecFn = async () => { + // serial stub 也尊重 fail-closed(沙箱不可用不返回 stub 结果) + if (!canRun) { + return SANDBOX_REFUSED_RESULT; + } + return SERIAL_STUB_RESULT; + }; const serial = parseSerialAddress(board.address); return { exec, transport: `serial:${serial.dev}@${serial.baudrate}`, isStub: true }; } case "local": { - return { exec: underlying, transport: "local", isStub: false }; + const exec: ExecFn = (command, args, opts) => { + // fail-closed:沙箱不可用 → 拒绝执行,不 spawn + if (!canRun) { + return Promise.resolve(SANDBOX_REFUSED_RESULT); + } + // local 直透:沙箱包装 command+args(模拟 runner token 前缀) + const { argv: wrapped } = applySandboxToArgv( + [command, ...args], + DEFAULT_BOARD_SANDBOX_POLICY, + probe.capability, + ); + // wrapped[0] 是 runner token,wrapped[1:] 是策略 + "--" + 原始命令 + // 但 underlying 期望 (command, args, opts) 签名,所以拆开: + // runner token 作为 command,其余作为 args + const runnerCmd = wrapped[0]; + const runnerArgs = wrapped.slice(1); + return underlying(runnerCmd, runnerArgs, opts); + }; + return { exec, transport: "local", isStub: false }; } default: { const exec: ExecFn = async (_command, _args, _opts) => ({ diff --git a/src/extensions/flash.ts b/src/extensions/flash.ts index eb155fd..fee0a50 100644 --- a/src/extensions/flash.ts +++ b/src/extensions/flash.ts @@ -726,6 +726,46 @@ let flashInProgress = false; // 扩展装配(运行时在真 pi 内动态 import defineTool/Type) // ============================================================================ +/** + * finalizeContent —— flash 工具的 content-only 不变量(T04)。 + * + * pi 的 `ToolDefinition` 不暴露 finalizeContent 字段(见 src/types/pi.d.ts:75), + * 故 pba 把它作为命名导出,由五段流水线(src/core/tool-pipeline.ts)经 + * `ctx.finalizeContent` 注入。flash 的 execute 已返回 `[{type:"text"}]` 结构, + * 此函数做防御性归一:保证 content 是 text-block 数组、剥离非 content 字段。 + * + * @param result flash execute 的原始产出。 + * @returns content-only 归一后的结果(details 保留在 details,不混入 content)。 + */ +export function finalizeFlashContent(result: { + content: unknown; + isError?: boolean; + details?: unknown; +}): { content: Array<{ type: "text"; text: string }>; isError?: boolean; details?: unknown } { + const raw = result.content; + let blocks: Array<{ type: "text"; text: string }>; + if (typeof raw === "string") { + blocks = [{ type: "text", text: raw }]; + } else if (Array.isArray(raw)) { + blocks = raw.map((b) => + typeof b === "string" + ? { type: "text" as const, text: b } + : { type: "text" as const, text: typeof b?.text === "string" ? b.text : JSON.stringify(b) }, + ); + } else if (raw && typeof raw === "object" && typeof (raw as { text?: unknown }).text === "string") { + blocks = [{ type: "text", text: (raw as { text: string }).text }]; + } else { + // 非 text-shaped:强制 stringify(content-only,绝不抛——抛了走 snapshot→isError) + blocks = [{ type: "text", text: JSON.stringify(raw) }]; + } + const out: { content: Array<{ type: "text"; text: string }>; isError?: boolean; details?: unknown } = { + content: blocks, + }; + if (result.isError) out.isError = true; + if (result.details !== undefined) out.details = result.details; + return out; +} + /** * flash 域扩展装配。 * diff --git a/src/extensions/index.ts b/src/extensions/index.ts index f3898e2..0199003 100644 --- a/src/extensions/index.ts +++ b/src/extensions/index.ts @@ -33,6 +33,7 @@ import datasheetRag from "./datasheet-rag.js"; import hardwareVerify from "./hardware-verify.js"; import loopOrchestrator from "./loop-orchestrator.js"; import buildTracker from "./build-tracker.js"; +import regTool from "./reg-tool.js"; /** 全部域扩展工厂(按依赖顺序:命门根治 → 安全门 → 基础设施 → 硬件能力 → 闭环)。 */ export const extensionFactories = [ @@ -57,6 +58,7 @@ export const extensionFactories = [ hardwareVerify, loopOrchestrator, buildTracker, + regTool, ] as const; /** diff --git a/src/extensions/reg-tool.ts b/src/extensions/reg-tool.ts new file mode 100644 index 0000000..aaf2406 --- /dev/null +++ b/src/extensions/reg-tool.ts @@ -0,0 +1,294 @@ +/** + * @module reg-tool + * + * 寄存器读写专用工具(T03)—— 安全门的" sanctioned path"。 + * + * 治命门二残余 + safety-gate devmem-via-bash 兜底的配套: + * - safety-gate 现在一律 block 裸 `devmem` 走 bash(无论 hex/十进制/64 位)。 + * - 本工具是唯一合法的寄存器访问路径:参数经 `makeHexNormalizingPrepareArguments` + * 归一(glm-5.2 十进制→hex),地址在 datasheet 已知寄存器表内校验通过才放行。 + * + * 三件事(纯逻辑可单测,零 pi 运行时依赖): + * ① KNOWN_REGISTERS —— RDK X5 SoC 起始寄存器表(datasheet-rag 后续扩展) + * ② validateRegisterAddress —— 地址在表内 + 可写性校验(fail-closed:未知即拒) + * ③ planRegOp —— 构造 read/write 计划(带 datasheetRef 可追溯) + * + * 装配层(工厂体内):动态 import defineTool/Type 注册 `reg` 工具, + * prepareArguments 接 hex 归一。见架构设计文档_v3.md §6.1 T03。 + */ + +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; +import { makeHexNormalizingPrepareArguments } from "./glm-provider.js"; + +// ============================================================================ +// 已知寄存器表(datasheet 起始集,可被 datasheet-rag 扩展) +// ============================================================================ + +/** 寄存器可写性。read-only 寄存器拒绝 write(fail-closed,防误写状态寄存器)。 */ +export type RegisterAccess = "ro" | "rw" | "wo"; + +/** datasheet 已知寄存器描述。地址 key 一律 0x 小写形式,便于查表。 */ +export interface KnownRegister { + /** 寄存器地址,0x 小写形式(如 "0x40020000")。 */ + address: string; + /** 寄存器名(datasheet 助记符)。 */ + name: string; + /** 所属模块(GPIO/I2C/UART/CAN...)。 */ + module: string; + /** 可写性。 */ + access: RegisterAccess; + /** 可选:datasheet 章节引用(追溯用)。 */ + datasheetRef?: string; +} + +/** + * RDK X5 SoC 起始已知寄存器表(示例子集,真实用例由 datasheet-rag 扩展)。 + * + * 地址以 0x 小写形式存储为 key,查表 O(1)。写未知地址一律 fail-closed 拒绝。 + */ +export const KNOWN_REGISTERS: Readonly> = Object.freeze({ + "0x40020000": Object.freeze({ + address: "0x40020000", + name: "GPIO_CTRL", + module: "GPIO", + access: "rw", + datasheetRef: "RDK-X5 TRM §12.4", + }), + "0x40020004": Object.freeze({ + address: "0x40020004", + name: "GPIO_OE", + module: "GPIO", + access: "rw", + datasheetRef: "RDK-X5 TRM §12.5", + }), + "0x40020008": Object.freeze({ + address: "0x40020008", + name: "GPIO_DATA", + module: "GPIO", + access: "rw", + }), + "0x4002000c": Object.freeze({ + address: "0x4002000c", + name: "GPIO_INTSTATUS", + module: "GPIO", + access: "ro", + }), + "0x50000000": Object.freeze({ + address: "0x50000000", + name: "CLK_CTRL", + module: "CLOCK", + access: "rw", + }), +}); + +// ============================================================================ +// 地址归一 + 校验 +// ============================================================================ + +/** 把任意 hex/十进制地址串归一为 0x 小写形式(查表用)。非地址返回 null。 */ +export function normalizeAddress(raw: string): string | null { + const trimmed = raw.trim().toLowerCase(); + // 已是 0x 形式 + if (/^0x[0-9a-f]+$/.test(trimmed)) { + return trimmed; + } + // 纯十进制 → hex(任意位数,覆盖 32/64 位;地址无 minDigits 限制) + if (/^\d+$/.test(trimmed)) { + try { + const big = BigInt(trimmed); + return "0x" + big.toString(16); + } catch { + return null; + } + } + return null; +} + +export interface AddressValidation { + /** 是否通过校验(地址在已知表内 + 可写性符合)。 */ + ok: boolean; + /** 命中的寄存器描述(ok=true 时)。 */ + register?: KnownRegister; + /** 失败原因(ok=false 时,fail-closed 诊断)。 */ + reason?: string; +} + +/** + * 校验地址是否在 datasheet 已知寄存器表内 + 可写性符合操作。 + * + * fail-closed:未知地址或归一失败一律拒绝(防砖板)。 + * + * @param raw 地址串(hex 或十进制,glm-5.2 强转的十进制也接受)。 + * @param op 读写操作(read 不查可写性;write 需 access≠"ro")。 + * @returns AddressValidation。 + */ +export function validateRegisterAddress(raw: string, op: "read" | "write"): AddressValidation { + const normalized = normalizeAddress(raw); + if (normalized === null) { + return { ok: false, reason: `address "${raw}" is not a valid hex/decimal register address` }; + } + const register = KNOWN_REGISTERS[normalized]; + if (register === undefined) { + return { ok: false, reason: `address ${normalized} not in datasheet known-register table — refuse (fail-closed)` }; + } + if (op === "write" && register.access === "ro") { + return { + ok: false, + reason: `register ${register.name} (${normalized}) is read-only — write refused`, + register, + }; + } + return { ok: true, register }; +} + +// ============================================================================ +// planRegOp —— 构造读写计划 +// ============================================================================ + +export interface RegOpPlan { + /** 归一化后的 0x 地址。 */ + address: string; + /** 寄存器描述。 */ + register: KnownRegister; + /** 操作。 */ + op: "read" | "write"; + /** 写值(op=write 时,0x 形式)。 */ + value?: string; + /** datasheet 引用(追溯)。 */ + datasheetRef?: string; +} + +export interface RegOpResult { + /** ok=true 时为计划;ok=false 时 undefined。 */ + plan?: RegOpPlan; + /** ok=false 时为原因。 */ + error?: string; + ok: boolean; +} + +/** reg 工具 execute 返回的统一 details 形状(ok 时带 plan/cmd,失败时带 reason)。 */ +export interface RegDetails { + ok: boolean; + reason?: string; + plan?: RegOpPlan; + cmd?: string; +} + +/** + * 构造寄存器读写计划:归一地址 → 校验在表内 + 可写性 → 成计划。 + * + * @param args 原始参数(address/value/op/datasheetRef)。 + * @returns RegOpResult(fail-closed:未知地址/只读写 → error)。 + */ +export function planRegOp(args: { + address: string; + value?: string; + op: "read" | "write"; + datasheetRef?: string; +}): RegOpResult { + const { address, value, op, datasheetRef } = args; + const v = validateRegisterAddress(address, op); + if (!v.ok || !v.register) { + return { ok: false, error: v.reason }; + } + const plan: RegOpPlan = { + address: v.register.address, + register: v.register, + op, + datasheetRef: datasheetRef ?? v.register.datasheetRef, + }; + if (op === "write") { + if (value === undefined || value.trim() === "") { + return { ok: false, error: "write op requires a value" }; + } + // 归一 value 为 0x 小写 + const normVal = normalizeAddress(value); + plan.value = normVal ?? value; + } + return { ok: true, plan }; +} + +// ============================================================================ +// 扩展装配 +// ============================================================================ + +/** + * reg 工具扩展装配。 + * + * - registerTool:`reg` 工具,schema {address, op, value?, datasheetRef?}, + * prepareArguments 接 hex 归一(命门二联动),execute 调 planRegOp 校验后产命令。 + * - safety-gate 已 block 裸 devmem;本工具是唯一寄存器访问路径。 + */ +export default async function regToolExtension(pi: ExtensionAPI): Promise { + const { defineTool } = await import("@earendil-works/pi-coding-agent"); + const { Type } = await import("@earendil-works/pi-ai"); + + const regSchema = Type.Object( + { + address: Type.String({ + description: "Register address (0x hex or decimal; glm-5.2 decimal coercion is auto-normalized).", + }), + op: Type.Union([Type.Literal("read"), Type.Literal("write")], { + description: "read or write (write requires datasheet-verified address + access≠ro).", + }), + value: Type.Optional( + Type.String({ description: "Value to write (0x hex or decimal); required for op=write." }), + ), + datasheetRef: Type.Optional( + Type.String({ description: "Datasheet reference for traceability." }), + ), + }, + { description: "Register read/write with datasheet address verification (sanctioned devmem path)." }, + ); + + const regTool = defineTool({ + name: "reg", + label: "Register Access", + description: + "Register read/write with datasheet address verification. Refuses unknown addresses (fail-closed). " + + "Use this instead of raw `devmem` (which safety-gate blocks).", + promptSnippet: "Read/write an MMIO register with datasheet-verified address", + parameters: regSchema, + executionMode: "sequential", + prepareArguments: makeHexNormalizingPrepareArguments(), + async execute(_id, params): Promise<{ + content: Array<{ type: "text"; text: string }>; + details: RegDetails; + isError?: boolean; + }> { + const p = params as { address: string; op: "read" | "write"; value?: string; datasheetRef?: string }; + const result = planRegOp(p); + if (!result.ok || !result.plan) { + return { + content: [{ type: "text", text: `REG REFUSED: ${result.error}` }], + details: { ok: false, reason: result.error }, + isError: true, + }; + } + const plan = result.plan; + const cmd = + plan.op === "read" + ? `devmem ${plan.address}` + : `devmem ${plan.address} w ${plan.value}`; + pi.appendEntry("reg:op", { + address: plan.address, + name: plan.register.name, + op: plan.op, + value: plan.value, + datasheetRef: plan.datasheetRef, + }); + return { + content: [ + { + type: "text", + text: `${plan.register.name} (${plan.address}, ${plan.register.module}, ${plan.register.access}) ${plan.op === "read" ? "read" : `← ${plan.value}`} — datasheet: ${plan.datasheetRef ?? "n/a"}\ncmd: ${cmd}`, + }, + ], + details: { ok: true, plan, cmd }, + isError: false, + }; + }, + }); + + pi.registerTool(regTool); +} diff --git a/src/extensions/safety-gate.ts b/src/extensions/safety-gate.ts index b9893b8..ffa186e 100644 --- a/src/extensions/safety-gate.ts +++ b/src/extensions/safety-gate.ts @@ -14,6 +14,9 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent"; import type { SafetyDecision } from "../shared/types.js"; +import type { ToolCallContext } from "../core/tool-pipeline.js"; +import { normalizeHexArg } from "./glm-provider.js"; +import { pipeline } from "../core/tool-pipeline.js"; // ============================================================================ // ① 破坏性命令检测 @@ -25,6 +28,11 @@ export interface SafetyRule { reason: string; safeAlternative?: string; requiresDryRun?: boolean; + /** + * 硬门:不可被 allowRules 豁免。用于"物理不可逆且无 bash 安全替代"的命令 + * (裸 devmem —— 必须走 `reg` 工具,allowRules 也绕不过)。 + */ + hardGate?: boolean; } /** @@ -59,6 +67,16 @@ export const DESTRUCTIVE_RULES: SafetyRule[] = [ reason: "raw devmem write to an MMIO register can brick the SoC. Verify the address against the datasheet.", safeAlternative: "reg tool with datasheet-verified address", }, + { + name: "devmem-via-bash", + // 匹配 devmem 作为独立 token(前后为空白/串首尾),不匹配 devmem.txt / devmem.log + // 这种子串。引号变形(d'e'vmem)由 deobfuscateCommand 还原后再过此正则。 + pattern: /(^|\s)devmem2?(?=\s|$)/i, + reason: "raw `devmem` through bash bypasses datasheet address verification — brick risk. Use the `reg` tool, which validates addresses against the known-register table and normalizes glm-5.2 hex→decimal coercion.", + safeAlternative: "reg tool (reg read / reg write)", + // 硬门:devmem 走 bash 一律不可豁免(即使 allowRules 含本规则名)—— 必须走 reg 工具。 + hardGate: true, + }, { name: "openocd-program-no-verify", pattern: /\bopenocd\b[^|]*\bprogram\b/i, @@ -86,13 +104,64 @@ export const DESTRUCTIVE_RULES: SafetyRule[] = [ export interface EvaluateOpts { /** 允许的破坏性命令白名单(按 rule name),用于 flash 工具内部调用豁免。 */ allowRules?: string[]; + /** 跳过 hex 归一(仅单测隔离用:直接对原始串过正则)。默认 false。 */ + skipNormalize?: boolean; +} + +/** + * 把命令串里"被 glm-5.2 强转成十进制的寄存器地址"还原成 0x 形式(命门二联动,T02)。 + * + * 按空白拆 token,对每个纯数字 token 跑 {@link normalizeHexArg}:落在寄存器地址区间 + * (0x10000, 0xffffffff] 且位数 ≥ 8 的十进制还原成 `0x...`,其余原样。`0x` 形式与 + * 非数字 token 不动。归一化只影响"是否能命中 devmem 规则",不会对非破坏性命令制造 + * 误拦(无 `devmem`/`dd of=`/`mkfs` 等触发词的命令归一化后仍无规则命中)。 + * + * @param command 原始 bash 命令串。 + * @returns 归一化后的命令串(用于过 DESTRUCTIVE_RULES)。 + */ +export function normalizeCommandHex(command: string): string { + if (!command) return command; + const tokens = command.split(/\s+/); + const out: string[] = []; + for (const tok of tokens) { + // 仅对"纯十进制数字"token 归一;0x 形式 / 带单位 / 命令名一律跳过 + if (tok && /^\d+$/.test(tok)) { + out.push(normalizeHexArg(tok).value); + } else { + out.push(tok); + } + } + return out.join(" "); +} + +/** + * 去引号混淆:剥离成对单引号,使 `d'e'vmem` → `devmem` 命中 `\bdevmem\b` 词边界。 + * + * 仅做轻量去引号(不解析 shell 语义),覆盖最常见的词边界绕过;非完整 shell 词法器。 + * 双引号/变量替换(`devmem=$cmd`)仍是残余风险,由 reg 工具的强制路由兜底(裸 devmem + * 走 bash 一律 block)。 + * + * @param command 原始命令串。 + * @returns 去成对单引号后的命令串。 + */ +export function deobfuscateCommand(command: string): string { + if (!command || !command.includes("'")) return command; + // 移除所有单引号:`d'e'vmem` → `devmem`;`'rm'` → `rm`。 + // 副作用:`echo 'a b'` → `echo a b`(引号保护的空格被拆 token)——对正则匹配无碍。 + return command.replace(/'/g, ""); } /** * 评估一条 bash 命令是否安全。fail-closed:命中规则即 block。 * + * 检测链(T02 + T03 联动): + * 1. 去引号混淆(`d'e'vmem` → `devmem`) + * 2. hex 归一(`devmem 1073872896 w` → `devmem 0x40020000 w`,命门二联动) + * 3. 过 DESTRUCTIVE_RULES:`devmem-via-bash` 兜底拦一切裸 devmem(含 64 位/无写词) + * * @param command bash 命令字符串。 * @param opts.allowRules 豁免的 rule 名(如 flash 工具内部 dd 豁免 dd-to-block-device)。 + * @param opts.skipNormalize 跳过归一(仅单测隔离)。 * @returns SafetyDecision。 */ export function evaluateSafety(command: string, opts: EvaluateOpts = {}): SafetyDecision { @@ -100,9 +169,11 @@ export function evaluateSafety(command: string, opts: EvaluateOpts = {}): Safety return { block: false }; } const allow = new Set(opts.allowRules ?? []); + const normalized = opts.skipNormalize ? command : deobfuscateCommand(normalizeCommandHex(command)); for (const rule of DESTRUCTIVE_RULES) { - if (allow.has(rule.name)) continue; - if (rule.pattern.test(command)) { + // 硬门不可豁免(allowRules 无视)—— 物理不可逆命令必须走专用工具 + if (!rule.hardGate && allow.has(rule.name)) continue; + if (rule.pattern.test(normalized)) { return { block: true, reason: rule.reason, rule: rule.name, safeAlternative: rule.safeAlternative }; } } @@ -140,6 +211,12 @@ export class ResourceLock { return this.locks.has(deviceId); } + /** 是否被"另一 owner"持有(同 owner 重入不算冲突,返回 false)。 */ + isHeldByOther(deviceId: string, owner: string): boolean { + const current = this.locks.get(deviceId); + return current !== undefined && current !== owner; + } + /** 释放某 owner 持有的所有锁(session 结束/abort 时清理)。 */ releaseAll(owner: string): string[] { const released: string[] = []; @@ -196,45 +273,89 @@ export function allowedToolsForSkill(skillName: string): string[] | null { // 单例资源锁(同进程跨 tool call 共享) const lock = new ResourceLock(); +/** + * 把 pi tool_call 事件适配为 ToolPipeline 的 ToolCallContext。 + * 非 bash 命令返回 null(safety-gate 只审 bash)。 + */ +function toPipelineCtx(event: { + toolName: string; + input: unknown; + toolCallId: string; +}): ToolCallContext | null { + if (event.toolName !== "bash") return null; + return { + toolName: event.toolName, + input: event.input, + toolCallId: event.toolCallId, + }; +} + /** * safety-gate 扩展装配。 * - * - tool_call:破坏性命令拦截 + 资源锁获取 + * T04 嫁接:把破坏性命令拦截 + 资源锁注册为五段流水线的单调 guards(stage ②), + * tool_call 钩子委托 `pipeline.decide()` 取 allow/deny 裁决(stage ①②③)。 + * UI 覆盖保留为"人类审批"层(decide deny 后的 escape hatch,非 guard force-allow, + * 单调性不变)。stage ④⑤(around/post/finalize)属 tool-body 执行,pi 扩展 API + * 在 tool_call 只能 block——全 wiring 待 pba agent-loop 集成(注释明示,不假装)。 + * + * - tool_call:pipeline.decide() 裁决 + UI 审批 + 资源锁获取 * - tool_result:释放资源锁 * - session_start:per-skill 工具收敛(读 PI_ACTIVE_SKILL 环境变量) */ export default function safetyGateExtension(pi: ExtensionAPI): void { - pi.on("tool_call", async (event, ctx: ExtensionContext) => { - if (event.toolName !== "bash") return undefined; - const command = (event.input as { command?: string }).command ?? ""; - const decision = evaluateSafety(command); + // 注册单调 guards 到流水线单例(任一 deny 不可 force-allow) + pipeline.registerGuard({ + id: "safety-gate:destructive", + evaluate: (c) => { + const command = (c.input as { command?: string }).command ?? ""; + const d = evaluateSafety(command); + if (d.block) { + return { decision: "deny", reason: `${d.reason}${d.safeAlternative ? ` → 改用 ${d.safeAlternative}` : ""}` }; + } + return { decision: "allow" }; + }, + }); + pipeline.registerGuard({ + id: "safety-gate:resource-lock", + evaluate: (c) => { + const command = (c.input as { command?: string }).command ?? ""; + const deviceId = extractDeviceId(command); + // 只检查(被另一 owner 持有即 deny);acquire 在 decide 允许后由钩子执行, + // 避免对已 deny 的命令占锁(防 lock 泄漏)。 + if (deviceId && lock.isHeldByOther(deviceId, c.toolCallId)) { + return { + decision: "deny", + reason: `device ${deviceId} is busy (another tool call holds the lock). Retry after it completes.`, + }; + } + return { decision: "allow" }; + }, + }); - if (decision.block) { + pi.on("tool_call", async (event, ctx: ExtensionContext) => { + const pctx = toPipelineCtx(event); + if (pctx === null) return undefined; + const command = (event.input as { command?: string }).command ?? ""; + + const pre = await pipeline.decide(pctx); + if (pre.decision === "deny") { + // UI 人类审批 escape hatch(非 guard force-allow;单调性不变) if (ctx.hasUI) { - const message = - `${command}\n\n原因:${decision.reason}\n` + - (decision.safeAlternative ? `建议改用:${decision.safeAlternative}\n` : "") + - "仍要放行?(不推荐)"; - const allow = await ctx.ui.confirm(`破坏性命令拦截 [${decision.rule}]`, message); + const message = `${command}\n\n原因:${pre.reason}\n仍要放行?(不推荐)`; + const allow = await ctx.ui.confirm(`破坏性命令拦截`, message); if (allow) { - pi.appendEntry("safegate:override", { rule: decision.rule, command }); + pi.appendEntry("safegate:override", { reason: pre.reason, command }); return undefined; } } - return { - block: true, - reason: `[safety-gate] ${decision.reason}${decision.safeAlternative ? ` → 改用 ${decision.safeAlternative}` : ""}`, - }; + return { block: true, reason: `[safety-gate] ${pre.reason}` }; } - - const deviceId = extractDeviceId(command); + // decide 允许后获取资源锁(guard 只检查,acquire 在此执行;同 owner 重入幂等) + const command2 = (event.input as { command?: string }).command ?? ""; + const deviceId = extractDeviceId(command2); if (deviceId) { - if (!lock.acquire(deviceId, event.toolCallId)) { - return { - block: true, - reason: `[safety-gate] device ${deviceId} is busy (another tool call holds the lock). Retry after it completes.`, - }; - } + lock.acquire(deviceId, event.toolCallId); } return undefined; }); diff --git a/tests/board-link.test.ts b/tests/board-link.test.ts index 97797c5..ab78886 100644 --- a/tests/board-link.test.ts +++ b/tests/board-link.test.ts @@ -1,4 +1,4 @@ -import { describe, it, expect, vi } from "vitest"; +import { describe, it, expect, vi, beforeEach } from "vitest"; import { BoardRegistry, parseSshAddress, @@ -8,8 +8,10 @@ import { healthCheck, computeFingerprint, SERIAL_STUB_RESULT, + resetBoardSandboxProbe, type RegistryEntry, } from "../src/extensions/board-link.js"; +import { DEFAULT_BOARD_SANDBOX_POLICY } from "../src/core/sandbox-policy.js"; import type { BoardSpec, ExecFn, ExecResult } from "../src/shared/types.js"; // ============================================================================ @@ -263,6 +265,13 @@ describe("board-link parseSerialAddress", () => { // ============================================================================ describe("board-link makeExec", () => { + beforeEach(() => { + // 沙箱 runner 可用 + 内核 5.13 → "full" capability(使 makeExec 正常包装并 spawn) + process.env.PBA_BOARD_SANDBOX_RUNNER = "1"; + process.env.PBA_BOARD_KERNEL = "5.13.0"; + resetBoardSandboxProbe(); + }); + it('ssh: calls underlying("ssh", sshArgs, opts)', async () => { const mock = makeMockExec({ stdout: "/tmp\n", exitCode: 0 }); const board = sshBoard("x5", "root@192.168.1.100:2222"); @@ -274,11 +283,15 @@ describe("board-link makeExec", () => { expect(result.stdout).toBe("/tmp\n"); expect(isStub).toBe(false); expect(transport).toBe("ssh:root@192.168.1.100:2222"); - // 验证 mock 被调时 command="ssh" 且 args 含 ssh 拼接 + // 验证 mock 被调时 command="ssh" 且 args 含沙箱包装 + ssh 拼接 const call = mock.mock.calls[0]; expect(call?.[0]).toBe("ssh"); const callArgs = call?.[1] as string[]; - expect(callArgs).toEqual(["-p", "2222", "root@192.168.1.100", "pwd"]); + // 沙箱包装前缀 + 原始 ssh 拼接后缀 + expect(callArgs).toEqual([ + "pba-board-sandbox", "--ro", "/", "--rw", "/workspace", "--", + "-p", "2222", "root@192.168.1.100", "pwd", + ]); }); it("ssh: opts 透传到 underlying", async () => { @@ -298,7 +311,11 @@ describe("board-link makeExec", () => { await exec("dmesg", []); const callArgs = mock.mock.calls[0]?.[1] as string[]; expect(callArgs).not.toContain("-p"); - expect(callArgs).toEqual(["root@192.168.1.100", "dmesg"]); + // 沙箱包装 + 默认端口 ssh 拼接(无 -p) + expect(callArgs).toEqual([ + "pba-board-sandbox", "--ro", "/", "--rw", "/workspace", "--", + "root@192.168.1.100", "dmesg", + ]); }); it("serial: 返回 stub,isStub=true,不调 underlying", async () => { @@ -320,7 +337,7 @@ describe("board-link makeExec", () => { expect(mock.mock.calls).toHaveLength(0); // underlying 没被调 }); - it("local: 直透 underlying(exec === underlying)", async () => { + it("local: 沙箱包装后调 underlying(runner token 作为 command)", async () => { const mock = makeMockExec({ stdout: "hello\n", exitCode: 0 }); const board: BoardSpec = { id: "local", @@ -336,10 +353,10 @@ describe("board-link makeExec", () => { expect(result.stdout).toBe("hello\n"); expect(isStub).toBe(false); expect(transport).toBe("local"); - // local 直透:command/args 原样传给 underlying + // local 沙箱包装:runner token 作为 command,策略根 + "--" + 原始命令作为 args const call = mock.mock.calls[0]; - expect(call?.[0]).toBe("echo"); - expect(call?.[1]).toEqual(["hello"]); + expect(call?.[0]).toBe("pba-board-sandbox"); + expect(call?.[1]).toEqual(["--ro", "/", "--rw", "/workspace", "--", "echo", "hello"]); }); }); @@ -348,9 +365,16 @@ describe("board-link makeExec", () => { // ============================================================================ describe("board-link healthCheck", () => { + beforeEach(() => { + // 沙箱 runner 可用 + 内核 5.13 → "full"(使 healthCheck 能 spawn 探活命令) + process.env.PBA_BOARD_SANDBOX_RUNNER = "1"; + process.env.PBA_BOARD_KERNEL = "5.13.0"; + resetBoardSandboxProbe(); + }); + it("exit 0 → alive (true)", async () => { const mock = makeMockExec({ exitCode: 0 }); - // local board: exec 直透 underlying,mock 能直接看到探活命令 + // local board: exec 沙箱包装后调 underlying,mock 能看到 runner token + 探活命令 const board: BoardSpec = { id: "local", name: "Local", @@ -361,8 +385,9 @@ describe("board-link healthCheck", () => { const { exec } = makeExec(board, mock); const alive = await healthCheck(board, exec); expect(alive).toBe(true); - // 验证探活命令是 "true" - expect(mock.mock.calls[0]?.[0]).toBe("true"); + // 探活命令 "true" 经沙箱包装后出现在 args 中 + const callArgs = mock.mock.calls[0]?.[1] as string[]; + expect(callArgs).toContain("true"); }); it("非 0 exit → dead (false)", async () => { @@ -400,7 +425,9 @@ describe("board-link healthCheck", () => { const { exec } = makeExec(board, mock); const alive = await healthCheck(board, exec, { probeCommand: "echo ok" }); expect(alive).toBe(true); - expect(mock.mock.calls[0]?.[0]).toBe("echo ok"); + // 自定义探活命令经沙箱包装后出现在 args 中 + const callArgs = mock.mock.calls[0]?.[1] as string[]; + expect(callArgs).toContain("echo ok"); }); it("timeout 透传到 exec opts", async () => { @@ -424,7 +451,7 @@ describe("board-link healthCheck", () => { const { exec } = makeExec(board, mock); const alive = await healthCheck(board, exec); expect(alive).toBe(true); - // ssh 包装:underlying 收到 "ssh" + 拼接的 args + // ssh 包装:underlying 收到 "ssh" + 拼接的 args(含沙箱前缀 + true) expect(mock.mock.calls[0]?.[0]).toBe("ssh"); const sshArgs = mock.mock.calls[0]?.[1] as string[]; expect(sshArgs).toContain("true"); @@ -461,3 +488,122 @@ describe("board-link computeFingerprint", () => { expect(a).toBe(b); }); }); + +// ============================================================================ +// board-side 沙箱 fail-closed (T05) +// ============================================================================ + +describe("board-side 沙箱 fail-closed (T05)", () => { + beforeEach(() => { + // 默认:沙箱 runner 未设 → unusable(fail-closed) + delete process.env.PBA_BOARD_SANDBOX_RUNNER; + delete process.env.PBA_BOARD_KERNEL; + resetBoardSandboxProbe(); + }); + + it("ssh: runner 不可用 → exec 返回 exitCode 126 + 拒绝 stderr,不 spawn underlying", async () => { + const mock = makeMockExec({ stdout: "should-not-see", exitCode: 0 }); + const board = sshBoard("x5", "root@192.168.1.100:22"); + const { exec } = makeExec(board, mock); + + const result = await exec("ls", ["/tmp"]); + + expect(result.exitCode).toBe(126); + expect(result.stdout).toBe(""); + expect(result.stderr).toContain("[board-sandbox]"); + expect(result.stderr).toContain("fail-closed"); + // 关键证明:underlying 从未被调用 + expect(mock.mock.calls).toHaveLength(0); + }); + + it("ssh: runner 可用 + 内核 5.13 → exec 跑通,argv 含沙箱包装", async () => { + process.env.PBA_BOARD_SANDBOX_RUNNER = "1"; + process.env.PBA_BOARD_KERNEL = "5.13.0"; + resetBoardSandboxProbe(); + + const mock = makeMockExec({ stdout: "ok\n", exitCode: 0 }); + const board = sshBoard("x5", "root@192.168.1.100:22"); + const { exec } = makeExec(board, mock); + + const result = await exec("ls", ["/tmp"]); + + expect(result.exitCode).toBe(0); + expect(result.stdout).toBe("ok\n"); + // underlying 被调用,且 argv 含沙箱 runner token + expect(mock.mock.calls).toHaveLength(1); + const callArgs = mock.mock.calls[0]?.[1] as string[]; + expect(callArgs).toContain("pba-board-sandbox"); + expect(callArgs).toContain("--ro"); + expect(callArgs).toContain("--rw"); + expect(callArgs).toContain("--"); + }); + + it("local: runner 不可用 → exec 返回 exitCode 126 + 拒绝 stderr,不 spawn underlying", async () => { + const mock = makeMockExec({ stdout: "should-not-see", exitCode: 0 }); + const board: BoardSpec = { + id: "local", + name: "Local", + link: "local", + address: "", + fingerprint: computeFingerprint("local", ""), + }; + const { exec } = makeExec(board, mock); + + const result = await exec("ls", ["/tmp"]); + + expect(result.exitCode).toBe(126); + expect(result.stderr).toContain("[board-sandbox]"); + expect(mock.mock.calls).toHaveLength(0); + }); + + it("local: runner 可用 + 内核 5.13 → exec 跑通,argv 含沙箱包装", async () => { + process.env.PBA_BOARD_SANDBOX_RUNNER = "1"; + process.env.PBA_BOARD_KERNEL = "5.13.0"; + resetBoardSandboxProbe(); + + const mock = makeMockExec({ stdout: "ok\n", exitCode: 0 }); + const board: BoardSpec = { + id: "local", + name: "Local", + link: "local", + address: "", + fingerprint: computeFingerprint("local", ""), + }; + const { exec } = makeExec(board, mock); + + const result = await exec("echo", ["hi"]); + + expect(result.exitCode).toBe(0); + expect(mock.mock.calls).toHaveLength(1); + expect(mock.mock.calls[0]?.[0]).toBe("pba-board-sandbox"); + const callArgs = mock.mock.calls[0]?.[1] as string[]; + expect(callArgs).toContain("echo"); + expect(callArgs).toContain("hi"); + }); + + it("serial: runner 不可用 → stub 也被拒绝(exitCode 126)", async () => { + const mock = makeMockExec(); + const board: BoardSpec = { + id: "serial-board", + name: "Serial Board", + link: "serial", + address: "/dev/ttyUSB0@115200", + fingerprint: computeFingerprint("serial", "/dev/ttyUSB0@115200"), + }; + const { exec } = makeExec(board, mock); + + const result = await exec("ls", []); + + expect(result.exitCode).toBe(126); + expect(result.stderr).toContain("[board-sandbox]"); + // serial stub 也不调 underlying + expect(mock.mock.calls).toHaveLength(0); + }); + + it("DEFAULT_BOARD_SANDBOX_POLICY 是 board-link 消费的单一共享 home", () => { + // board-link 通过值导入引用 sandbox-policy 的 DEFAULT_BOARD_SANDBOX_POLICY + // flash 接线由另一 agent 拥有(TODO,见架构文档 §5.4)—— 此处只验证 board-link 侧 + expect(DEFAULT_BOARD_SANDBOX_POLICY.readOnlyRoots).toEqual(["/"]); + expect(DEFAULT_BOARD_SANDBOX_POLICY.readWriteRoots).toEqual(["/workspace"]); + }); +}); diff --git a/tests/e2e-runtime.test.ts b/tests/e2e-runtime.test.ts new file mode 100644 index 0000000..b5ae650 --- /dev/null +++ b/tests/e2e-runtime.test.ts @@ -0,0 +1,75 @@ +/** + * @module e2e-runtime + * + * T01 真运行时冒烟(离线,via vitest 源别名解析 pi,无需 build)。 + * + * 与 e2e-smoke(FakePi 装配级)的区别:本测试调真 pi 的 createAgentSession, + * 验证 pba barrel 经 pi 自动发现装配 + glm-5.2 provider 注册后,session 能真建。 + * 不调真模型推理(无网络/无 key)——只验"能 boot 到可跑 turn 的状态"。 + * + * 若 pi-ai 模型 catalog 缺失(packages/ai/src/providers/data 空目录)致模型解析失败, + * 测试 tolerant 记录根因而非假绿——诚实区分"boot 成功"与"catalog 缺失阻塞"。 + */ +import { describe, it, expect } from "vitest"; +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), ".."); + +describe("T01 真运行时冒烟 —— createAgentSession boot", () => { + it("真 createAgentSession + inMemory session 不抛(barrel 自动装配 + provider 注册)", async () => { + const pi = await import("@earendil-works/pi-coding-agent"); + const createAgentSession = (pi as { createAgentSession: (o: unknown) => Promise }) + .createAgentSession; + const SessionManager = (pi as { SessionManager?: { inMemory?: () => unknown } }).SessionManager; + expect(typeof createAgentSession).toBe("function"); + + const opts: Record = { + cwd: PKG_ROOT, + agentDir: PKG_ROOT, + thinkingLevel: "off" as const, + }; + if (SessionManager && typeof SessionManager.inMemory === "function") { + opts.sessionManager = SessionManager.inMemory(); + } + + let result: unknown = null; + let bootError: unknown = null; + try { + result = await createAgentSession(opts); + } catch (e) { + bootError = e; + } + + if (bootError) { + // 诚实记录根因。若为 catalog 缺失 → skip(已知网络阻塞),否则 fail。 + const msg = bootError instanceof Error ? bootError.message : String(bootError); + // biome-ignore lint/suspicious/noConsole: 诊断根因 + console.warn("[T01-RUNTIME] createAgentSession threw:", msg.slice(0, 400)); + const catalogMissing = /models\.generated|providers\/data|ENOENT|model/i.test(msg) && + /\.json|data|catalog|not found|no such/i.test(msg); + if (catalogMissing) { + console.warn("[T01-RUNTIME] blocked on pi-ai model catalog (network-hydrated data) — known offline gap"); + expect(true).toBe(true); + return; + } + throw bootError; + } + + // boot 成功:断言 session + extensions 装载 + expect(result).toBeTruthy(); + const r = result as { session?: unknown; extensionsResult?: unknown; modelFallbackMessage?: string }; + expect(r.session).toBeTruthy(); + expect(r.extensionsResult).toBeTruthy(); + expect(r.modelFallbackMessage).toBeUndefined(); // glm-5.2 解析成功,无回退 + // 诊断:log extensionsResult 结构(工具注册证据) + const ext = r.extensionsResult as Record | undefined; + // biome-ignore lint/suspicious/noConsole: 装配证据 + console.log( + "[T01-RUNTIME] booted; session keys:", + Object.keys(r.session as Record ?? {}).slice(0, 8), + "ext keys:", + ext ? Object.keys(ext).slice(0, 8) : "n/a", + ); + }); +}); diff --git a/tests/e2e-smoke.test.ts b/tests/e2e-smoke.test.ts new file mode 100644 index 0000000..db8d673 --- /dev/null +++ b/tests/e2e-smoke.test.ts @@ -0,0 +1,743 @@ +/** + * @module tests/e2e-smoke + * + * T01 端到端装配冒烟 —— 离线 mock-pi 装配 + 安全门钩子端到端验证。 + * + * 本测试不依赖 pi 构建产物(dist/)也不依赖联网模型数据水合。vitest.config.ts 的 + * alias 把 `@earendil-works/pi-coding-agent` / `@earendil-works/pi-ai` 解析到 pi 源码 + * (.ts),故各域扩展工厂体内的 `await import("@earendil-works/pi-coding-agent")` 在 + * 测试内可解析到真 `defineTool` / `Type`,工具注册真实发生。 + * + * 测试方法学(响应质量上调要求,显式落进 describe 块): + * - 等价类划分 + 边界值(normalizeHexArg 地址区间) + * - 决策表(safety-gate allowRules × 规则 × hex/十进制) + * - 对抗/模糊(safety-gate 10+ 伪装绕过命令) + * - 变异测试(植入边界算子变异,断言被测试抓到) + * - 元变性/不变量(allowRules 单调性:allow 只放松不收紧) + * - 状态不变量(fail-soft 装配:单工厂崩不中断其余) + * + * 诚实约束:真 pi 运行时冒烟(createAgentSession)需 pi 构建且模型数据水合(联网), + * 本测试不伪造其成功,见 docs/postmortem/0001-e2e-smoke.md。 + */ + +import { describe, it, expect } from "vitest"; +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; +import { PhysicalByteAgent } from "../src/agent.js"; +import assembly, { extensionFactories } from "../src/extensions/index.js"; +import { + evaluateSafety, + DESTRUCTIVE_RULES, + extractDeviceId, +} from "../src/extensions/safety-gate.js"; +import { + normalizeHexArg, + normalizeToolArguments, +} from "../src/extensions/glm-provider.js"; + +// ============================================================================ +// FakePi —— 实现 ExtensionAPI 面的最小 mock(记录调用供断言) +// ============================================================================ + +interface FakeEntry { + type: string; + data?: unknown; +} + +/** FakePi 内部记录面(与 ExtensionAPI 交叉,供测试断言)。 */ +interface MockInternals { + tools: Array<{ name: string; [k: string]: unknown }>; + entries: FakeEntry[]; + handlers: Record unknown>>; + providers: Array<{ name: string; config: unknown }>; + activeTools: string[]; +} + +/** FakePi 类型 = ExtensionAPI + 记录面。 */ +type FakePi = ExtensionAPI & MockInternals; + +/** + * 构造一个记录型 FakePi。每个 ExtensionAPI 方法记录入参,供测试断言。 + * + * @returns FakePi 实例(含 tools/entries/handlers/providers 供断言)。 + */ +function createFakePi(): FakePi { + const tools: FakePi["tools"] = []; + const entries: FakeEntry[] = []; + const handlers: Record unknown>> = {}; + const providers: Array<{ name: string; config: unknown }> = []; + const activeTools: string[] = []; + const eventHandlers: Record void>> = {}; + + // mock 是测试替身:方法签名放宽(any),通过 unknown→FakePi 转型接入 ExtensionAPI 面。 + const pi = { + tools, + entries, + handlers, + providers, + activeTools, + events: { + _h: eventHandlers, + on(event: string, handler: (data: unknown) => void) { + (eventHandlers[event] ??= []).push(handler); + }, + emit(event: string, data: unknown) { + (eventHandlers[event] ??= []).forEach((f) => { + try { + f(data); + } catch { + // noop — fail-soft + } + }); + }, + }, + registerTool(def: any) { + tools.push(def); + return def; + }, + on(event: string, handler: (event: any, ctx: any) => unknown) { + (handlers[event] ??= []).push(handler); + return () => { + const arr = handlers[event]; + if (arr) { + const idx = arr.indexOf(handler); + if (idx >= 0) arr.splice(idx, 1); + } + }; + }, + registerProvider(name: string, config: unknown) { + providers.push({ name, config }); + }, + registerCommand() {}, + sendMessage() {}, + sendUserMessage() {}, + appendEntry(type: string, data?: unknown) { + entries.push({ type, data }); + }, + async exec() { + return { stdout: "", stderr: "", exitCode: 0 }; + }, + setActiveTools(names: string[]) { + activeTools.length = 0; + activeTools.push(...names); + }, + getActiveTools() { + return [...activeTools]; + }, + getAllTools() { + return tools; + }, + async setModel() { + return true; + }, + }; + return pi as unknown as FakePi; +} + +// ============================================================================ +// Step A — 装配冒烟(barrel + fail-soft + verifyAssembly) +// ============================================================================ + +describe("T01 装配冒烟 —— barrel 装配 + fail-soft", () => { + it("verifyAssembly:21 个域扩展工厂就位且全为函数(离线稳定基线)", () => { + const { count, domains } = PhysicalByteAgent.verifyAssembly(); + // 容忍并发开发(reg-tool 可能加入 → 22)。稳定基线 >= 21。 + expect(count).toBeGreaterThanOrEqual(21); + expect(domains.length).toBe(count); + for (const f of extensionFactories) { + expect(typeof f).toBe("function"); + } + }); + + it("FakePi + barrel 装配完成不抛错(fail-soft 保证单工厂崩不中断)", async () => { + const pi = createFakePi(); + await expect(assembly(pi)).resolves.toBeUndefined(); + // 装配审计条目落地 + const assembled = pi.entries.find((e) => e.type === "pba:assembled"); + expect(assembled).toBeDefined(); + }); + + it("装配后 21 个工厂全部成功注册(0 个 assembly-error)—— 真实装配结果", async () => { + const pi = createFakePi(); + await assembly(pi); + const errors = pi.entries.filter((e) => e.type === "pba:assembly-error"); + const assembled = pi.entries.find((e) => e.type === "pba:assembled"); + const expectedTotal = (assembled?.data as { extensions: number })?.extensions ?? 21; + expect(errors.length).toBe(0); + expect(expectedTotal).toBeGreaterThanOrEqual(21); + // 诚实记录:所有工厂在 mock 下成功(动态 import pi 源码在 vitest alias 下可解析)。 + expect(pi.tools.length).toBeGreaterThan(0); + }); + + it("关键工具已注册:glm_status / pshell / flash / verify / debugger / board_exec", async () => { + const pi = createFakePi(); + await assembly(pi); + const names = pi.tools.map((t) => t.name); + // 容忍并发开发:核心工具名稳定。 + for (const expected of ["glm_status", "pshell", "flash", "verify", "debugger", "board_exec"]) { + expect(names).toContain(expected); + } + }); + + it("glm-provider 注册了 drobotics-glm provider", async () => { + const pi = createFakePi(); + await assembly(pi); + expect(pi.providers.some((p) => p.name === "drobotics-glm")).toBe(true); + }); +}); + +// ============================================================================ +// Step B — 安全门钩子端到端(装配级:pi.on("tool_call") 钩子真实注册 + 拦截) +// ============================================================================ + +describe("T01 安全门钩子端到端 —— 装配级 tool_call 拦截", () => { + it("装配后 tool_call 钩子已注册(≥1 handler)", async () => { + const pi = createFakePi(); + await assembly(pi); + expect((pi.handlers["tool_call"] ?? []).length).toBeGreaterThanOrEqual(1); + }); + + /** + * 决策表(safety-gate tool_call 钩子):行=命令类别,列=ctx.hasUI,单元=拦截结果。 + * + * | 命令 | hasUI=false | hasUI=true(confirm→false) | + * |--------------------------|-------------|----------------------------| + * | hex devmem 写 | block:true | block:true | + * | 安全 i2cdump 读 | undefined | undefined | + * | decimal devmem(裸跑) | undefined* | undefined* | + * + * *decimal devmem 裸跑不被当前正则拦截(无 0x 前缀)——这是已知缺口,由 glm-provider + * 的 normalizeHexArg(T02)在 prepareArguments 阶段先归一再过门来兜底(见下用例)。 + */ + it("决策表 · hex devmem 写 → block(hasUI:false)", async () => { + const pi = createFakePi(); + await assembly(pi); + const handler = pi.handlers["tool_call"][0]; + const result = await handler( + { type: "tool_call", toolCallId: "tc1", toolName: "bash", input: { command: "devmem 0x40020000 w 0x1" } }, + { hasUI: false, ui: { confirm: async () => false } }, + ); + expect(result).toBeDefined(); + expect((result as { block: boolean }).block).toBe(true); + expect((result as { reason: string }).reason).toContain("safety-gate"); + }); + + it("决策表 · hex devmem 写 → block(hasUI:true 但 confirm→false 仍 block)", async () => { + const pi = createFakePi(); + await assembly(pi); + const handler = pi.handlers["tool_call"][0]; + const result = await handler( + { type: "tool_call", toolCallId: "tc2", toolName: "bash", input: { command: "devmem 0x40020000 write 0x1" } }, + { hasUI: true, ui: { confirm: async () => false } }, + ); + expect((result as { block: boolean }).block).toBe(true); + }); + + it("决策表 · 安全 i2cdump 读 → undefined(放行)", async () => { + const pi = createFakePi(); + await assembly(pi); + const handler = pi.handlers["tool_call"][0]; + const result = await handler( + { type: "tool_call", toolCallId: "tc3", toolName: "bash", input: { command: "i2cdump -y 0 0x76" } }, + { hasUI: false, ui: { confirm: async () => true } }, + ); + expect(result).toBeUndefined(); + }); + + it("决策表 · 非 bash 工具调用 → 不拦截(undefined)", async () => { + const pi = createFakePi(); + await assembly(pi); + const handler = pi.handlers["tool_call"][0]; + const result = await handler( + { type: "tool_call", toolCallId: "tc4", toolName: "flash", input: { method: "dd" } }, + { hasUI: false, ui: { confirm: async () => false } }, + ); + expect(result).toBeUndefined(); + }); + + it("T02 链路证明 · decimal devmem 经 normalizeHexArg 归一后再过门 → block", async () => { + // glm-5.2 把 0x40020000 强转成十进制 "1073872896"。prepareArguments 先归一: + const normalized = normalizeHexArg("1073872896"); + expect(normalized.corrected).toBe(true); + expect(normalized.value).toBe("0x40020000"); + // 归一后拼回 devmem 命令过安全门 → 命中 devmem-write 规则 block。 + const decision = evaluateSafety(`devmem ${normalized.value} w 0x1`); + expect(decision.block).toBe(true); + expect(decision.rule).toBe("devmem-write"); + }); + + it("已知缺口记录 · 裸 decimal devmem 不经归一直接过门 → 不 block(诚实记录)", async () => { + // 当前安全门正则只匹配 0x 前缀地址,decimal 裸跑漏过。这是 T02 归一层要兜的缺口。 + // 测试断言真实行为(不 block),并以 console.warn 记录缺口供 postmortem。 + const decision = evaluateSafety("devmem 1073872896 w 0x1"); + if (decision.block) { + // 若后续 src/safety-gate.ts 加固了 decimal 拦截,这里自然变绿——测试驱动正确方向。 + expect(decision.block).toBe(true); + } else { + // biome-ignore lint/suspicious/noConsole: 缺口记录 + console.warn( + "[T01 KNOWN-GAP] safety-gate does not block raw decimal devmem (no 0x prefix). " + + "Mitigated by glm-provider normalizeHexArg (T02) in prepareArguments pipeline.", + ); + expect(decision.block).toBe(false); + } + }); +}); + +// ============================================================================ +// 决策表测试 —— evaluateSafety allowRules × 规则 × hex/十进制 × 命中/未命中 +// ============================================================================ + +describe("T01 决策表 · evaluateSafety 全覆盖", () => { + /** 决策表行:{ 命令, 命中规则名(无则 null), 是否 hex } */ + const cases: Array<{ cmd: string; rule: string | null; hex: boolean }> = [ + { cmd: "dd if=img.bin of=/dev/mmcblk0", rule: "dd-to-block-device", hex: false }, + { cmd: "fastboot flash boot boot.img", rule: "fastboot-flash", hex: false }, + { cmd: "mkfs.ext4 /dev/sda1", rule: "mkfs-on-device", hex: false }, + { cmd: "devmem 0x40020000 w 0x1", rule: "devmem-write", hex: true }, + { cmd: "devmem 0x40020000 write 0x1", rule: "devmem-write", hex: true }, + { cmd: "openocd -f cfg -c 'program fw.elf'", rule: "openocd-program-no-verify", hex: false }, + { cmd: "rm -rf /dev/i2c-0", rule: "rm-dev", hex: false }, + { cmd: "chmod 777 /dev/i2c-0", rule: "chmod-777-dev", hex: false }, + { cmd: "rm -rf /", rule: "rm-rf-root", hex: false }, + // 未命中行(安全命令) + { cmd: "i2cdump -y 0 0x76", rule: null, hex: false }, + { cmd: "aarch64-linux-gnu-gcc -o app main.c", rule: null, hex: false }, + { cmd: "dmesg | grep i2c", rule: null, hex: false }, + ]; + + it.each(cases)("命令 «$cmd» → 命中规则 «$rule»(null=放行)", ({ cmd, rule }) => { + const d = evaluateSafety(cmd); + if (rule === null) { + expect(d.block).toBe(false); + expect(d.rule).toBeUndefined(); + } else { + expect(d.block).toBe(true); + expect(d.rule).toBe(rule); + } + }); + + it.each(cases)("allowRules 豁免命中规则后 → 放行(«$rule»)", ({ cmd, rule }) => { + if (rule === null) return; // 只对命中规则的行测豁免 + // T03:devmem 经 bash 现为硬门(devmem-via-bash 不可豁免)—— 豁免 devmem-write + // 后仍被 devmem-via-bash 兜底 block(必须走 reg 工具,allowRules 绕不过)。 + if (rule === "devmem-write") { + const d = evaluateSafety(cmd, { allowRules: [rule] }); + expect(d.block).toBe(true); // 硬门兜底,仍 block + return; + } + const d = evaluateSafety(cmd, { allowRules: [rule] }); + expect(d.block).toBe(false); + }); + + it("决策表 · devmem-via-bash 硬门:allowRules 含本规则名也不豁免", () => { + // 硬门不可豁免(即使显式 allowRules 含 devmem-via-bash) + const d = evaluateSafety("devmem 0x40020000 w 0x1", { + allowRules: ["devmem-write", "devmem-via-bash"], + }); + expect(d.block).toBe(true); + }); + + it("决策表 · hex 命中但 allowRules 不含该规则 → 仍 block", () => { + const d = evaluateSafety("devmem 0x40020000 w 0x1", { allowRules: ["dd-to-block-device"] }); + expect(d.block).toBe(true); + expect(d.rule).toBe("devmem-write"); + }); +}); + +// ============================================================================ +// 对抗/模糊测试 —— safety-gate 伪装绕过命令 +// ============================================================================ + +describe("T01 对抗/模糊 · safety-gate 绕过尝试", () => { + /** + * 伪装绕过命令集。诚实断言当前正则的真实拦截能力: + * - hex 形态 + write 别名 + devmem2 变体 → block(当前正则覆盖) + * - decimal 裸跑 / 引号变形 / 变量赋值 → 不 block(已知缺口,T02 归一兜底 decimal;引号/变量为残余风险) + * + * 测试驱动:记录每个绕过是否被拦,缺口写入 console.warn。 + */ + const adversarial: Array<{ cmd: string; expectBlock: boolean; note: string }> = [ + { cmd: "devmem 0x40020000 write", expectBlock: true, note: "write 别名 + hex" }, + { cmd: "devmem2 0x40020000 w", expectBlock: true, note: "devmem2 变体 + hex" }, + { cmd: "devmem 0xFFFFFFFF w 0x0", expectBlock: true, note: "32 位上界 hex" }, + { cmd: "devmem 0x10000 w 0x1", expectBlock: true, note: "下界 hex" }, + { cmd: "devmem 1073872896 w 0x1", expectBlock: false, note: "KNOWN-GAP: decimal 裸跑漏过(T02 归一兜底)" }, + { cmd: "devmem 1099511627776 w", expectBlock: false, note: "KNOWN-GAP: 64 位 decimal 漏过(超出 normalize 32 位范围)" }, + { cmd: "d'e'vmem 0x40020000 w", expectBlock: false, note: "KNOWN-GAP: 引号变形绕过词边界(残余风险)" }, + { cmd: "devmem=$cmd; $devmem 0x40020000 w", expectBlock: false, note: "KNOWN-GAP: 变量间接调用绕过" }, + { cmd: "DEVMEM 0X40020000 W 0x1", expectBlock: true, note: "大小写不敏感(/i flag)覆盖" }, + { cmd: " devmem 0x40020000 w ", expectBlock: true, note: "多空格 + hex 仍命中" }, + ]; + + it.each(adversarial)("对抗命令 «$note»", ({ cmd, expectBlock, note }) => { + const d = evaluateSafety(cmd); + if (!expectBlock && d.block) { + // 若 src 加固后拦截了,测试自然绿——驱动正确方向。 + expect(d.block).toBe(true); + } else if (expectBlock) { + expect(d.block).toBe(true); + } else { + // biome-ignore lint/suspicious/noConsole: 缺口记录供 postmortem + console.warn(`[T01 ADVERSARIAL-GAP] ${note}: "${cmd}" not blocked (rule=${d.rule ?? "none"})`); + expect(d.block).toBe(false); + } + }); + + it("安全读命令零误报(假阳性测试)", () => { + const safe = [ + "i2cdump -y 0 0x76", + "i2cget -y 1 0x50 0x10", + "cat /sys/class/gpio/gpio33/value", + "dmesg | tail -20", + "gpioget gpiochip0 33", + "ls /dev/i2c-0", + ]; + for (const cmd of safe) { + expect(evaluateSafety(cmd).block).toBe(false); + } + }); +}); + +// ============================================================================ +// 边界值测试 —— normalizeHexArg 地址区间(等价类划分 + 边界值) +// ============================================================================ + +describe("T01 边界值 · normalizeHexArg 地址区间", () => { + /** + * 等价类划分: + * EC1: 已是 0x 形式 → 原样(corrected:false) + * EC2: 纯十进制 + 落在 (minRange, maxRange] + 位数>=minDigits → 归一(corrected:true) + * EC3: 纯十进制但位数 < minDigits → 不归一 + * EC4: 纯十进制但超出范围 → 不归一 + * EC5: 非数字 → 不归一 + * + * 边界值: + * B1: 7 位 vs 8 位(minDigits 边界) + * B2: 0x10000(minRange,开区间下界) + * B3: 0xFFFFFFFF(maxRange,闭区间上界) + * B4: 0x100000000(maxRange+1,越界) + */ + + // EC1: 已是 hex + it("EC1 · 已是 0x 形式 → 原样不修正", () => { + const r = normalizeHexArg("0x40020000"); + expect(r.corrected).toBe(false); + expect(r.value).toBe("0x40020000"); + }); + + // B3: maxRange 闭区间上界 → 归一 + it("B3 · 0xFFFFFFFF(4294967295,maxRange 上界)→ 归一(闭区间)", () => { + const r = normalizeHexArg("4294967295"); + expect(r.corrected).toBe(true); + expect(r.value).toBe("0xffffffff"); + }); + + // B4: maxRange+1 越界 → 不归一 + it("B4 · 0x100000000(4294967296,越界)→ 不归一", () => { + const r = normalizeHexArg("4294967296"); + expect(r.corrected).toBe(false); + }); + + // B1: 7 位不触发(位数 < minDigits=8),即使在范围内 + it("B1 · 7 位十进制(9999999,在范围内但位数不足)→ 不归一", () => { + const r = normalizeHexArg("9999999"); // 0x98967F, 7 digits + expect(r.corrected).toBe(false); + }); + + // B1 对侧: 8 位触发 + it("B1 · 8 位十进制(10000000,在范围内 + 位数达标)→ 归一", () => { + const r = normalizeHexArg("10000000"); // 0x989680 + expect(r.corrected).toBe(true); + expect(r.value).toBe("0x989680"); + }); + + // EC2: 典型寄存器地址(命门二场景) + it("EC2 · 1073872896(0x40020000,glm-5.2 强转场景)→ 归一", () => { + const r = normalizeHexArg("1073872896"); + expect(r.corrected).toBe(true); + expect(r.value).toBe("0x40020000"); + }); + + // B2: minRange 开区间下界 — 65536 不归一(big > bigMin 严格大于) + it("B2 · 65536(0x10000,minRange 下界)→ 不归一(开区间)", () => { + const r = normalizeHexArg("00065536"); // 8 位才触发位数检查 + expect(r.corrected).toBe(false); + }); + + it("B2 · 65537(minRange+1,8 位补零)→ 归一(开区间内)", () => { + const r = normalizeHexArg("00065537"); // 8 digits, BigInt 65537 > 65536 + expect(r.corrected).toBe(true); + expect(r.value).toBe("0x10001"); + }); + + // EC3: 小十进制(baudrate 115200)→ 不归一(位数不足) + it("EC3 · 115200(baudrate,6 位)→ 不归一", () => { + const r = normalizeHexArg("115200"); + expect(r.corrected).toBe(false); + }); + + // EC5: 非数字 → 不归一 + it("EC5 · 非数字字符串 → 不归一", () => { + const r = normalizeHexArg("auto"); + expect(r.corrected).toBe(false); + }); + + // EC5: number 类型 + it("EC5 · number 类型在范围内 → 归一", () => { + const r = normalizeHexArg(1073872896); + expect(r.corrected).toBe(true); + expect(r.value).toBe("0x40020000"); + }); + + // denylist 字段跳过 + it("normalizeToolArguments · denylist 字段跳过归一", () => { + const { normalized, corrections } = normalizeToolArguments( + { address: "1073872896", baudrate: "4294967295" }, + { fieldDenylist: ["baudrate"] }, + ); + expect(normalized.address).toBe("0x40020000"); + expect(normalized.baudrate).toBe("4294967295"); // denylist 跳过 + expect(corrections.length).toBe(1); + expect(corrections[0].field).toBe("address"); + }); +}); + +// ============================================================================ +// 变异测试 —— 植入边界算子变异,断言测试能抓到(变异被杀) +// ============================================================================ + +describe("T01 变异测试 · normalizeHexArg 边界算子变异", () => { + /** + * 变异 1(M1):把 maxRange 比较 `big <= bigMax` 改成 `big < bigMax`。 + * 变异后 0xFFFFFFFF 不再归一(变成开区间),边界测试 B3 应能抓到(变异被杀)。 + */ + function normalizeHexArgMutant_M1(value: unknown): { corrected: boolean; value: string } { + const minRange = 0x10000; + const maxRange = 0xffffffff; + const minDigits = 8; + if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value.trim())) { + return { value, corrected: false }; + } + if (typeof value === "string" && /^\d+$/.test(value.trim())) { + const trimmed = value.trim(); + if (trimmed.length >= minDigits) { + const big = BigInt(trimmed); + const bigMin = BigInt(minRange); + const bigMax = BigInt(maxRange); + // MUTANT: big < bigMax (原: big <= bigMax) + if (big > bigMin && big < bigMax) { + return { value: "0x" + big.toString(16), corrected: true }; + } + } + } + return { value: String(value ?? ""), corrected: false }; + } + + it("M1 变异被杀 · 0xFFFFFFFF 在变异下不归一(与正确实现相反)", () => { + const correct = normalizeHexArg("4294967295"); + const mutant = normalizeHexArgMutant_M1("4294967295"); + // 正确实现归一,变异不归一 → 测试区分二者(变异被杀)。 + expect(correct.corrected).toBe(true); + expect(mutant.corrected).toBe(false); + expect(correct.corrected).not.toBe(mutant.corrected); + }); + + /** + * 变异 2(M2):把 minRange 比较 `big > bigMin` 改成 `big >= bigMin`。 + * 变异后 65536(minRange)会错误归一。 + */ + function normalizeHexArgMutant_M2(value: unknown): { corrected: boolean; value: string } { + const minRange = 0x10000; + const maxRange = 0xffffffff; + const minDigits = 8; + if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value.trim())) { + return { value, corrected: false }; + } + if (typeof value === "string" && /^\d+$/.test(value.trim())) { + const trimmed = value.trim(); + if (trimmed.length >= minDigits) { + const big = BigInt(trimmed); + const bigMin = BigInt(minRange); + const bigMax = BigInt(maxRange); + // MUTANT: big >= bigMin (原: big > bigMin) + if (big >= bigMin && big <= bigMax) { + return { value: "0x" + big.toString(16), corrected: true }; + } + } + } + return { value: String(value ?? ""), corrected: false }; + } + + it("M2 变异被杀 · minRange 下界 65536 在变异下错误归一(与正确实现相反)", () => { + const correct = normalizeHexArg("00065536"); + const mutant = normalizeHexArgMutant_M2("00065536"); + expect(correct.corrected).toBe(false); + expect(mutant.corrected).toBe(true); + expect(correct.corrected).not.toBe(mutant.corrected); + }); + + /** + * 变异 3(M3):把 minDigits 检查 `>= minDigits` 改成 `> minDigits`。 + * 变异后恰好 8 位的不再触发(需 >8 即 9+),8 位边界用例应抓到。 + */ + function normalizeHexArgMutant_M3(value: unknown): { corrected: boolean; value: string } { + const minRange = 0x10000; + const maxRange = 0xffffffff; + const minDigits = 8; + if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value.trim())) { + return { value, corrected: false }; + } + if (typeof value === "string" && /^\d+$/.test(value.trim())) { + const trimmed = value.trim(); + // MUTANT: trimmed.length > minDigits (原: >= minDigits) + if (trimmed.length > minDigits) { + const big = BigInt(trimmed); + if (big > BigInt(minRange) && big <= BigInt(maxRange)) { + return { value: "0x" + big.toString(16), corrected: true }; + } + } + } + return { value: String(value ?? ""), corrected: false }; + } + + it("M3 变异被杀 · 恰好 8 位(10000000)在变异下不归一(与正确实现相反)", () => { + const correct = normalizeHexArg("10000000"); + const mutant = normalizeHexArgMutant_M3("10000000"); + expect(correct.corrected).toBe(true); + expect(mutant.corrected).toBe(false); + expect(correct.corrected).not.toBe(mutant.corrected); + }); +}); + +// ============================================================================ +// 元变性/不变量 —— allowRules 单调性(allow 只放松不收紧) +// ============================================================================ + +describe("T01 元变性/不变量 · allowRules 单调性", () => { + /** + * 元性质(Metamorphic relation): + * 对任意命令 cmd 和任意两个 allow 集合 A ⊆ B, + * block(B) ⟹ block(A)(更多豁免只会放松,不会让原本放行的变 block)。 + * + * 即 block(·) 关于 allow 集合单调递减。 + * + * 手写参数化随机循环(不引入 fast-check 依赖)。 + */ + const sampleCommands = [ + "devmem 0x40020000 w 0x1", + "dd if=x of=/dev/mmcblk0", + "fastboot flash boot b.img", + "mkfs.ext4 /dev/sda1", + "openocd -c 'program x.elf'", + "rm -rf /dev/i2c-0", + "chmod 777 /dev/i2c-0", + "rm -rf /", + "i2cdump -y 0 0x76", + "dmesg | grep i2c", + "gcc -o app main.c", + ]; + const allRules = DESTRUCTIVE_RULES.map((r) => r.name); + // 伪随机种子固定保证可复现 + let seed = 42; + const rng = () => { + seed = (seed * 1103515245 + 12345) & 0x7fffffff; + return seed; + }; + const randomSubset = (): string[] => { + const n = rng() % (allRules.length + 1); + const copy = [...allRules]; + const out: string[] = []; + for (let i = 0; i < n; i++) { + const idx = rng() % copy.length; + out.push(copy.splice(idx, 1)[0]); + } + return out; + }; + + it("不变量 · block(B) ⟹ block(A) 对 A⊆B(100 组随机)", () => { + let violations = 0; + for (let i = 0; i < 100; i++) { + const cmd = sampleCommands[rng() % sampleCommands.length]; + const A = randomSubset(); + // B = A ∪ 额外随机规则(保证 A⊆B) + const extra = randomSubset(); + const B = Array.from(new Set([...A, ...extra])); + const blockA = evaluateSafety(cmd, { allowRules: A }).block; + const blockB = evaluateSafety(cmd, { allowRules: B }).block; + // block(B) ⟹ block(A) + if (blockB && !blockA) violations++; + } + expect(violations).toBe(0); + }); + + it("不变量 · 空集 allow(最严)下若放行,则任意 allow 也放行", () => { + for (const cmd of sampleCommands) { + const blockEmpty = evaluateSafety(cmd, { allowRules: [] }).block; + if (!blockEmpty) { + // 任意 allow 也应放行(单调性推论) + const blockFull = evaluateSafety(cmd, { allowRules: allRules }).block; + expect(blockFull).toBe(false); + } + } + }); + + it("不变量 · 全集 allow(最宽)下若 block,则空集下也 block", () => { + for (const cmd of sampleCommands) { + const blockFull = evaluateSafety(cmd, { allowRules: allRules }).block; + if (blockFull) { + // 全集都 block → 无规则命中(即不在规则集内)→ 空集也 block + // 实际上全集 allow = 无规则拦截,block 只可能来自全集外逻辑(当前实现无) + const blockEmpty = evaluateSafety(cmd, { allowRules: [] }).block; + expect(blockEmpty).toBe(true); + } + } + }); +}); + +// ============================================================================ +// 状态不变量 —— fail-soft 装配:单工厂崩不中断其余 +// ============================================================================ + +describe("T01 状态不变量 · fail-soft 装配隔离", () => { + it("注入一个抛错工厂后,其余工厂仍装配 + assembly-error 记录", async () => { + // 用一个会抛错的假工厂替换 barrel 列表中的一个,验证 fail-soft。 + // 用具名函数(.name="boom",无需 Object.assign——name 是只读属性)。 + const pi = createFakePi(); + async function boom() { + throw new Error("boom-injected-for-fail-soft-test"); + } + // 构造一个含 boom 的工厂列表 + const list = [extensionFactories[0]!, boom, ...extensionFactories.slice(1)]; + let errorCount = 0; + let toolCount = 0; + for (const factory of list) { + try { + await factory(pi); + toolCount++; + } catch (err) { + errorCount++; + pi.appendEntry("pba:assembly-error", { extension: factory.name, error: String(err) }); + } + } + expect(errorCount).toBe(1); + expect(toolCount).toBe(list.length - 1); + const errors = pi.entries.filter((e) => e.type === "pba:assembly-error"); + expect(errors.length).toBe(1); + expect((errors[0].data as { extension: string }).extension).toBe("boom"); + }); +}); + +// ============================================================================ +// extractDeviceId —— 资源锁键提取(辅助覆盖) +// ============================================================================ + +describe("T01 extractDeviceId · 资源锁键提取", () => { + it.each([ + ["i2cdump -y 0 0x76", "i2c-bus-0"], + ["i2cget -y 1 0x50 0x10", "i2c-bus-1"], + ["gpioget gpiochip0 33", "gpiochip0"], + ["ls -la", null], + ])("命令 «%s» → deviceId «%s»", (cmd, expected) => { + expect(extractDeviceId(cmd)).toBe(expected); + }); +}); diff --git a/tests/flash.test.ts b/tests/flash.test.ts index 8278fb0..0c8d7e5 100644 --- a/tests/flash.test.ts +++ b/tests/flash.test.ts @@ -12,6 +12,7 @@ import { deviceBasename, ROOT_MOUNTPOINTS, splitCommand, + finalizeFlashContent, type FlashPlanEx, } from "../src/extensions/flash.js"; import type { ExecFn } from "../src/shared/types.js"; @@ -486,3 +487,67 @@ describe("flash runFlash — 三段式编排", () => { expect(r.reason).toContain("write command failed"); }); }); + +// ============================================================================ +// T04 finalizeFlashContent —— flash content-only 不变量 +// ============================================================================ + +describe("T04 finalizeFlashContent —— content-only 归一", () => { + it("已是 text-block 数组 → 原样(details 保留)", () => { + const r = finalizeFlashContent({ + content: [{ type: "text", text: "flash OK" }], + details: { stage: "full" }, + }); + expect(r.content).toEqual([{ type: "text", text: "flash OK" }]); + expect(r.details).toEqual({ stage: "full" }); + expect(r.isError).toBeUndefined(); + }); + + it("裸字符串 content → 包成 text-block", () => { + const r = finalizeFlashContent({ content: "raw string" }); + expect(r.content).toEqual([{ type: "text", text: "raw string" }]); + }); + + it("字符串数组 content → 每项包成 text-block", () => { + const r = finalizeFlashContent({ content: ["a", "b"] }); + expect(r.content).toEqual([ + { type: "text", text: "a" }, + { type: "text", text: "b" }, + ]); + }); + + it("单个 text-shaped 对象 → 包成单块", () => { + const r = finalizeFlashContent({ content: { type: "text", text: "x" } }); + expect(r.content).toEqual([{ type: "text", text: "x" }]); + }); + + it("非 text-shaped content → 强制 stringify(content-only,绝不抛)", () => { + const r = finalizeFlashContent({ content: { weird: true } }); + expect(r.content).toEqual([{ type: "text", text: JSON.stringify({ weird: true }) }]); + }); + + it("isError 透传", () => { + const r = finalizeFlashContent({ content: "fail", isError: true }); + expect(r.isError).toBe(true); + }); + + // 不变式:所有输出 content 必是 Array<{type:"text",text:string}> + it("不变式:6 种输入归一后 content 恒为 text-block 数组", () => { + const inputs = [ + { content: "s" }, + { content: ["a"] }, + { content: [{ type: "text", text: "t" }] }, + { content: { type: "text", text: "o" } }, + { content: { x: 1 } }, + { content: 42 }, + ]; + for (const inp of inputs) { + const r = finalizeFlashContent(inp); + expect(Array.isArray(r.content)).toBe(true); + for (const b of r.content) { + expect(b.type).toBe("text"); + expect(typeof b.text).toBe("string"); + } + } + }); +}); diff --git a/tests/reg-tool.test.ts b/tests/reg-tool.test.ts new file mode 100644 index 0000000..e8b6c62 --- /dev/null +++ b/tests/reg-tool.test.ts @@ -0,0 +1,131 @@ +import { describe, it, expect } from "vitest"; +import { + KNOWN_REGISTERS, + normalizeAddress, + validateRegisterAddress, + planRegOp, +} from "../src/extensions/reg-tool.js"; + +describe("reg-tool normalizeAddress —— 等价类 + 边界值", () => { + it.each([ + ["0x40020000", "0x40020000"], // 已 hex 小写 + ["0X40020000", "0x40020000"], // 大写 0X → 小写 + ["1073872896", "0x40020000"], // 十进制 32 位 + ["1099511627776", "0x10000000000"], // 64 位十进制(BigInt 保精度) + ["0", "0x0"], // 零 + ])("归一为 0x 小写:%s → %s", (inp, exp) => { + expect(normalizeAddress(inp)).toBe(exp); + }); + + it.each([ + ["0xGGGG", null], // 非 hex 字符 + ["gpio33", null], // 非地址 + ["", null], // 空串 + ["0x", null], // 0x 无数字 + [" ", null], // 空白 + ])("非法地址返回 null:%s", (inp, exp) => { + expect(normalizeAddress(inp)).toBe(exp); + }); +}); + +describe("reg-tool validateRegisterAddress —— 决策表(地址已知性 × 可写性 × op)", () => { + // 决策表:address ∈ {已知rw, 已知ro, 未知, 非法} × op ∈ {read, write} + it.each([ + // 已知 rw 寄存器 + ["0x40020000", "read", true, "GPIO_CTRL"], // rw read → ok + ["0x40020000", "write", true, "GPIO_CTRL"], // rw write → ok + ["1073872896", "write", true, "GPIO_CTRL"], // 十进制归一 → ok(命门二联动) + // 已知 ro 寄存器 + ["0x4002000c", "read", true, "GPIO_INTSTATUS"], // ro read → ok + ["0x4002000c", "write", false, undefined], // ro write → fail-closed + // 未知地址 + ["0xdeadbeef", "read", false, undefined], // 未知 → fail-closed + ["0xdeadbeef", "write", false, undefined], + // 非法地址 + ["gpio33", "read", false, undefined], + ["", "read", false, undefined], + ])("决策行 «%s» op=%s → ok=%s reg=%s", (addr, op, ok, name) => { + const v = validateRegisterAddress(addr, op as "read" | "write"); + expect(v.ok).toBe(ok); + if (name) expect(v.register?.name).toBe(name); + if (!ok) expect(v.reason).toBeTruthy(); + }); +}); + +describe("reg-tool planRegOp —— 边界值 + 不变式", () => { + it("read 已知地址 → plan 含归一地址 + datasheetRef", () => { + const r = planRegOp({ address: "0x40020000", op: "read" }); + expect(r.ok).toBe(true); + expect(r.plan?.address).toBe("0x40020000"); + expect(r.plan?.register.name).toBe("GPIO_CTRL"); + expect(r.plan?.datasheetRef).toBe("RDK-X5 TRM §12.4"); + }); + + it("write 已知 rw 地址带 value → plan.value 归一", () => { + const r = planRegOp({ address: "0x40020008", op: "write", value: "1" }); + expect(r.ok).toBe(true); + expect(r.plan?.value).toBe("0x1"); + }); + + it("write 缺 value → fail-closed", () => { + const r = planRegOp({ address: "0x40020000", op: "write" }); + expect(r.ok).toBe(false); + expect(r.error).toContain("value"); + }); + + it("write ro 寄存器 → fail-closed(防误写状态寄存器)", () => { + const r = planRegOp({ address: "0x4002000c", op: "write", value: "0x1" }); + expect(r.ok).toBe(false); + expect(r.error).toContain("read-only"); + }); + + it("未知地址 → fail-closed(防砖板,T03 核心)", () => { + const r = planRegOp({ address: "0xffffffff", op: "read" }); + expect(r.ok).toBe(false); + expect(r.error).toContain("not in datasheet"); + }); + + it("十进制地址(glm-5.2 命门二)经归一命中已知寄存器", () => { + // 1073872896 = 0x40020000 + const r = planRegOp({ address: "1073872896", op: "read" }); + expect(r.ok).toBe(true); + expect(r.plan?.register.name).toBe("GPIO_CTRL"); + }); +}); + +describe("reg-tool 变异测试 —— 植入 bug 必被抓住", () => { + // M1:若归一被破坏(人为不归一十进制),未知十进制应漏过查表 → fail。 + // 证 normalizeAddress 非冗余:十进制必须归一才能查表。 + it("M1: 十进制不归一则查表失败(normalizeAddress 非冗余)", () => { + // 直接用十进制串查 KNOWN_REGISTERS → miss(证归一是查表前提) + expect(KNOWN_REGISTERS["1073872896"]).toBeUndefined(); + // 归一后命中 + expect(KNOWN_REGISTERS[normalizeAddress("1073872896") ?? ""]).toBeDefined(); + }); + + // M2:ro 寄存器 write 必须被拦。若 access 检查被移除(模拟),ro write 会过 → 证可写性检查非冗余。 + it("M2: ro 寄存器 access=ro,write 必被拦(可写性检查非冗余)", () => { + const roReg = Object.values(KNOWN_REGISTERS).find((r) => r.access === "ro"); + expect(roReg).toBeDefined(); + const r = planRegOp({ address: roReg!.address, op: "write", value: "0x1" }); + expect(r.ok).toBe(false); + }); +}); + +describe("reg-tool KNOWN_REGISTERS —— 不变式(冻结 + 地址小写)", () => { + it("表冻结:增删属性 throw(严格模式)", () => { + expect(() => { + // biome-ignore lint/suspicious/noExplicitAny: 测试冻结性 + (KNOWN_REGISTERS as any)["0x99999999"] = { address: "x" }; + }).toThrow(TypeError); + }); + + it("所有 key 是 0x 小写形式(查表一致性不变式)", () => { + for (const key of Object.keys(KNOWN_REGISTERS)) { + expect(key).toMatch(/^0x[0-9a-f]+$/); + expect(key).toBe(key.toLowerCase()); + // key 与条目 .address 一致 + expect(KNOWN_REGISTERS[key].address).toBe(key); + } + }); +}); diff --git a/tests/safety-gate.test.ts b/tests/safety-gate.test.ts index 3b635fc..7aff255 100644 --- a/tests/safety-gate.test.ts +++ b/tests/safety-gate.test.ts @@ -1,6 +1,8 @@ import { describe, it, expect } from "vitest"; import { evaluateSafety, + normalizeCommandHex, + deobfuscateCommand, DESTRUCTIVE_RULES, ResourceLock, extractDeviceId, @@ -127,3 +129,168 @@ describe("safety-gate per-skill allowed-tools", () => { expect(allowedToolsForSkill("HW-PROBE")).toEqual(SKILL_ALLOWED_TOOLS["hw-probe"]); }); }); + +// ============================================================================ +// T02 + T03 多方法测试套件 —— hex 归一联动 + devmem-via-bash 兜底 + 对抗/变异/元蜕变 +// ============================================================================ + +describe("T02 normalizeCommandHex —— 等价类 + 边界值", () => { + // EP:纯十进制寄存器地址(≥8 位,落在 (0x10000, 0xffffffff]) + it.each([ + ["devmem 1073872896 w 0x1", "devmem 0x40020000 w 0x1"], // 0x40020000 经典 + ["devmem 2684354560 w", "devmem 0xa0000000 w"], // 上半区 + ["devmem 10000000 w", "devmem 0x989680 w"], // 最小 8 位十进制(=0x989680 > minRange)→ 归一 + ])("EP1 十进制地址归一为 hex:%s", (inp, exp) => { + expect(normalizeCommandHex(inp)).toBe(exp); + }); + + // 边界值:位数边界(7/8 位)+ 值域边界(max/越界)。注:minDigits=8 使 < 8 位的 + // 十进制一律不归一(防 baudrate 115200 误拦),故 minRange 边界对 8+ 位串实际失效 + // (最小 8 位十进制 10000000 >> 0x10000),安全靠 devmem-via-bash 兜底兜住。 + it.each([ + ["devmem 9999999 w", "devmem 9999999 w"], // 7 位 < 8 → 不归一(兜底规则仍 block) + ["devmem 10000000 w", "devmem 0x989680 w"], // 8 位 且 > minRange → 归一 + ["devmem 4294967295 w", "devmem 0xffffffff w"], // = maxRange(闭区间)→ 归一 + ["devmem 4294967296 w", "devmem 4294967296 w"], // 越过 maxRange → 不归一(64 位由 devmem-via-bash 兜底) + ])("BV 位数/值域边界:%s", (inp, exp) => { + expect(normalizeCommandHex(inp)).toBe(exp); + }); + + // EP:已是 hex / 非数字 / 命令名 → 原样 + it.each([ + ["devmem 0x40020000 w", "devmem 0x40020000 w"], // 0x 形式不动 + ["baudrate 115200", "baudrate 115200"], // 6 位 < 8 不归一(防误拦) + ["stty -F /dev/ttyUSB0 115200 cs8", "stty -F /dev/ttyUSB0 115200 cs8"], // 115200 不归一 + ["aarch64-linux-gnu-gcc -o app main.c", "aarch64-linux-gnu-gcc -o app main.c"], // 非数字 token + ["", ""], // 空串 + ])("EP2 非破坏性/已 hex/非数字 不归一:%s", (inp, exp) => { + expect(normalizeCommandHex(inp)).toBe(exp); + }); +}); + +describe("T02 deobfuscateCommand —— 引号变形对抗", () => { + it.each([ + ["d'e'vmem 0x40020000 w", "devmem 0x40020000 w"], // 词边界绕过→还原 + ["'rm' -rf /", "rm -rf /"], + ["echo a b", "echo a b"], // 无引号不动 + ])("去成对单引号:%s", (inp, exp) => { + expect(deobfuscateCommand(inp)).toBe(exp); + }); +}); + +describe("T02+T03 evaluateSafety 决策表 —— devmem 变体 × 命中规则", () => { + // 决策表:命令变体 → {block, rule}。覆盖 hex/十进制/64位/无写词/引号变形/裸读。 + it.each([ + ["devmem 0x40020000 w 0x1", true, "devmem-write"], // hex+写 → devmem-write + ["devmem 1073872896 w 0x1", true, "devmem-write"], // 十进制经归一 → devmem-write(T02 核心) + ["devmem 1073872896 w", true, "devmem-write"], // 十进制无 value + ["devmem 1099511627776 w", true, "devmem-via-bash"], // 64 位越 maxRange 不归一 → 兜底规则 + ["devmem 0x40020000", true, "devmem-via-bash"], // 裸读 hex 无写词 → 兜底 + ["devmem 1073872896", true, "devmem-via-bash"], // 十进制无写词 → 兜底 + ["devmem2 0x40020000 w", true, "devmem-write"], // devmem2 变体 + ["d'e'vmem 0x40020000 w", true, "devmem-write"], // 引号变形经去混淆 → devmem-write + ["i2cdump -y 0 0x76", false, undefined], // 安全命令不拦 + ["baudrate 115200", false, undefined], // 波特率不误拦 + ["cat /sys/class/gpio/gpio33/value", false, undefined], // 读 sysfs 不拦 + ])("决策行 «%s» → block=%s rule=%s", (cmd, block, rule) => { + const d = evaluateSafety(cmd); + expect(d.block).toBe(block); + if (rule) expect(d.rule).toBe(rule); + }); +}); + +describe("T03 devmem-via-bash 兜底 —— 对抗/模糊", () => { + // 10+ 条伪装绕过命令,全断言 block(devmem-via-bash 兜底 + T02 归一) + const adversarial: string[] = [ + "devmem 0x40020000 write", + "devmem 1073872896 w", + "devmem2 0x40020000 w", + "DEVMEM 0x40020000 W", // 大小写 + "devmem 0x40020000", // 裸读 + "devmem 1073872896", // 十进制裸 + "devmem 1099511627776 w", // 64 位 + "sudo devmem 0x40020000 w", // 前缀 + "devmem 0x40020000 w", // 多空格 + "d'e'vmem 0x40020000 w", // 引号变形 + "devmem 0xDEADBEEF w", // 大写 hex + ]; + it.each(adversarial.map((c) => [c]))("对抗 «%s» 必须 block", (cmd) => { + expect(evaluateSafety(cmd).block).toBe(true); + }); + + // 假阳性检查:含 devmem 子串但非命令 → 不拦?devmem 词边界确保只拦真命令 + it.each([ + ["cat devmem.txt", false], // devmem.txt 词边界不匹配 \bdevmem2?\b(后跟 . 非 \b) + ["echo 'use reg tool not devmem'", true], // 含裸 devmem 词 → 拦(fail-closed 可接受:建议改 reg) + ])("假阳性 «%s» → block=%s", (cmd, block) => { + expect(evaluateSafety(cmd).block).toBe(block); + }); +}); + +describe("T02+T03 变异测试 —— 植入 bug 必被抓住", () => { + // M1:若归一化被跳过(skipNormalize=true),十进制 devmem 应漏过 devmem-write; + // 但 devmem-via-bash 兜底仍拦。证伪"归一是冗余"——归一让 rule 精准为 devmem-write。 + it("M1: skipNormalize 时十进制 devmem 不命中 devmem-write(归一非冗余)", () => { + const d = evaluateSafety("devmem 1073872896 w 0x1", { skipNormalize: true }); + // 无归一 → devmem-write 不匹配(无 0x)→ 落到 devmem-via-bash + expect(d.rule).not.toBe("devmem-write"); + expect(d.rule).toBe("devmem-via-bash"); + // 有归一 → 精准 devmem-write(证归一提供更准的诊断 rule 名) + expect(evaluateSafety("devmem 1073872896 w 0x1").rule).toBe("devmem-write"); + }); + + // M2:若 deobfuscateCommand 被禁用,引号变形应漏过 devmem-write + it("M2: 去混淆禁用时引号变形不命中 devmem-write(去混淆非冗余)", () => { + const d = evaluateSafety("d'e'vmem 0x40020000 w", { skipNormalize: true }); + // skipNormalize 跳过整个 normalize+deobfuscate → devmem-write 不匹配 d'e'vmem + expect(d.rule).not.toBe("devmem-write"); + }); +}); + +describe("T02+T03 元蜕变/不变式 —— allowRules 单调性 + 兜底恒真", () => { + // 元蜕变:devmem-via-bash 是兜底规则,不放 allowRules(allowRules 只豁免具名规则) + // 不变式:对任意 devmem 命令,若未被 allowRules 豁免 → block 恒真(无论地址形式) + const devmemVariants = [ + "devmem 0x40020000 w", + "devmem 1073872896 w", + "devmem 1099511627776 w", + "devmem 0x40020000", + "d'e'vmem 0x40020000 w", + ]; + it.each(devmemVariants.map((c) => [c]))("不变式: «%s» 无豁免 ⟹ block", (cmd) => { + expect(evaluateSafety(cmd).block).toBe(true); + }); + + // allowRules 单调性:allowRules 越大,越可能放行(A⊆B, 放行(B)⟹放行(A) 的逆否: + // block(B)⟹block(A))。对 dd 规则验证。 + it("allowRules 单调性:block(B)⟹block(A) for A⊆B(100 随机采样)", () => { + const allRules = DESTRUCTIVE_RULES.map((r) => r.name); + const cmd = "dd if=img of=/dev/mmcblk0"; + // 确定性伪随机:不引入 Math.random(脚本可复现) + let seed = 42; + const rand = () => { + seed = (seed * 1103515245 + 12345) & 0x7fffffff; + return seed; + }; + for (let i = 0; i < 100; i++) { + // 构造 A⊆B 两个子集 + const a = allRules.filter(() => rand() % 2 === 0); + const b = a.concat(allRules.filter((r) => !a.includes(r) && rand() % 3 === 0)); + // 保证 A⊆B + const aSet = new Set(a); + const bSet = new Set(b); + for (const x of aSet) expect(bSet.has(x)).toBe(true); + const blockB = evaluateSafety(cmd, { allowRules: b }).block; + const blockA = evaluateSafety(cmd, { allowRules: a }).block; + // block(B) ⟹ block(A) + expect(!blockB || blockA).toBe(true); + } + }); + + it("allowRules 空集与全集:空集 block,全集(含 dd-to-block-device)放行", () => { + expect(evaluateSafety("dd if=img of=/dev/mmcblk0", { allowRules: [] }).block).toBe(true); + expect( + evaluateSafety("dd if=img of=/dev/mmcblk0", { allowRules: ["dd-to-block-device"] }).block, + ).toBe(false); + }); +}); diff --git a/tests/sandbox-policy.test.ts b/tests/sandbox-policy.test.ts new file mode 100644 index 0000000..2e278f1 --- /dev/null +++ b/tests/sandbox-policy.test.ts @@ -0,0 +1,691 @@ +/** + * sandbox-policy 纯逻辑多方法测试套件 —— T05a 板侧沙箱 fail-closed 门。 + * + * 覆盖六种测试方法论(非单一 example-based): + * ① 等价类划分 + 边界值(EP + BVA)—— parseKernelVersion / probeSandbox 版本边界 + * ② 决策表 —— (runnerAvailable × kernel≥5.13) → {full, partial, unusable} × {run, refuse} + * ③ 状态转换 —— 命令生命周期:probe → policy resolve → wrap → spawn-or-refuse → result + * ④ 变异测试 —— 植入 3 个 bug,断言测试能抓住(mutation kill) + * ⑤ 对抗 / 模糊 —— 畸形内核串、空/巨 argv、空根策略 + * ⑥ 不变式 / 元蜕变 —— fail-closed 不变式:unusable ⟹ never wraps + refuse(跨所有 unusable 成因) + * + * 纯逻辑模块零 pi 依赖,离线可单测。见架构设计文档_v3.md §6.1 / §5.4。 + */ + +import { describe, it, expect } from "vitest"; +import { + parseKernelVersion, + probeSandbox, + shouldRunCommand, + applySandboxToArgv, + DEFAULT_BOARD_SANDBOX_POLICY, + RUNNER_TOKEN, + FLAG_READ_ONLY, + FLAG_READ_WRITE, + FLAG_SEPARATOR, + type BoardSandboxPolicy, + type SandboxCapability, + type SandboxProbeResult, +} from "../src/core/sandbox-policy.js"; + +// ============================================================================ +// ① 等价类划分 + 边界值 —— parseKernelVersion +// ============================================================================ +// 等价类: +// EC-K1: 标准三段 "5.13.0-foo" → {5,13}(后缀忽略) +// EC-K2: 两段 "5.13" → {5,13}(无 patch) +// EC-K3: 单段 "5" → {5,0}(minor 默认 0) +// EC-K4: v 前缀 "v5.13" → {5,13}(前缀剥离) +// EC-K5: undefined → null(缺失) +// EC-K6: 非版本串 "not-a-version" → null(不可解析) +// 边界值: +// BV-K1: 5.13.0(Landlock 门槛刚好满足) +// BV-K2: 5.12.99(门槛刚好不满足) +// BV-K3: 6.0.0(远大于门槛) +// BV-K4: 5.13.0-rc1(rc 后缀) + +describe("sandbox-policy parseKernelVersion — 等价类 + 边界值", () => { + // --- 等价类 --- + it("EC-K1: 三段版本 '5.13.0-foo' → {5,13}(后缀忽略)", () => { + expect(parseKernelVersion("5.13.0-foo")).toEqual({ major: 5, minor: 13 }); + }); + it("EC-K2: 两段 '5.13' → {5,13}", () => { + expect(parseKernelVersion("5.13")).toEqual({ major: 5, minor: 13 }); + }); + it("EC-K3: 单段 '5' → {5,0}(minor 默认 0)", () => { + expect(parseKernelVersion("5")).toEqual({ major: 5, minor: 0 }); + }); + it("EC-K4: v 前缀 'v5.13' → {5,13}(前缀剥离)", () => { + expect(parseKernelVersion("v5.13")).toEqual({ major: 5, minor: 13 }); + }); + it("EC-K4b: 大写 V 前缀 'V5.13' → {5,13}", () => { + expect(parseKernelVersion("V5.13")).toEqual({ major: 5, minor: 13 }); + }); + it("EC-K5: undefined → null(缺失)", () => { + expect(parseKernelVersion(undefined)).toBeNull(); + }); + it("EC-K6: 非版本串 'not-a-version' → null", () => { + expect(parseKernelVersion("not-a-version")).toBeNull(); + }); + + // --- 边界值 --- + it("BV-K1: '5.13.0' → {5,13}(Landlock 门槛刚好满足)", () => { + expect(parseKernelVersion("5.13.0")).toEqual({ major: 5, minor: 13 }); + }); + it("BV-K2: '5.12.99' → {5,12}(门槛刚好不满足)", () => { + expect(parseKernelVersion("5.12.99")).toEqual({ major: 5, minor: 12 }); + }); + it("BV-K3: '6.0.0' → {6,0}(远大于门槛)", () => { + expect(parseKernelVersion("6.0.0")).toEqual({ major: 6, minor: 0 }); + }); + it("BV-K4: '5.13.0-rc1' → {5,13}(rc 后缀剥离)", () => { + expect(parseKernelVersion("5.13.0-rc1")).toEqual({ major: 5, minor: 13 }); + }); + + // --- 空白 / 鲁棒 --- + it("首尾空白 ' 5.13.0 ' → {5,13}(trim)", () => { + expect(parseKernelVersion(" 5.13.0 ")).toEqual({ major: 5, minor: 13 }); + }); + it("空字符串 '' → null", () => { + expect(parseKernelVersion("")).toBeNull(); + }); + it("纯空白 ' ' → null", () => { + expect(parseKernelVersion(" ")).toBeNull(); + }); + it("v 前缀 + 单段 'v6' → {6,0}", () => { + expect(parseKernelVersion("v6")).toEqual({ major: 6, minor: 0 }); + }); +}); + +// ============================================================================ +// ① 等价类 + 边界值 —— probeSandbox 能力判定 +// ============================================================================ + +describe("sandbox-policy probeSandbox — 等价类 + 边界值", () => { + // EC1: runner 不可用 → unusable(无论内核版本) + it("EC1: runner=false + 任意内核 → unusable(fail-closed)", () => { + const r = probeSandbox(false, "5.13.0"); + expect(r.capability).toBe("unusable"); + expect(r.reason).toContain("not available"); + }); + it("EC1b: runner=false + 内核缺失 → unusable", () => { + expect(probeSandbox(false).capability).toBe("unusable"); + }); + + // EC2: runner + 内核 ≥ 5.13 → full + it("EC2: runner=true + 5.13.0 → full", () => { + const r = probeSandbox(true, "5.13.0"); + expect(r.capability).toBe("full"); + expect(r.reason).toContain("Landlock"); + }); + + // EC3: runner + 内核 < 5.13 → partial + it("EC3: runner=true + 5.12.0 → partial(seccomp-only 回退)", () => { + const r = probeSandbox(true, "5.12.0"); + expect(r.capability).toBe("partial"); + expect(r.reason).toContain("seccomp"); + }); + + // EC4: runner + 内核不可解析/缺失 → unusable(fail-closed 安全默认) + it("EC4: runner=true + undefined → unusable(fail-closed 安全默认)", () => { + const r = probeSandbox(true); + expect(r.capability).toBe("unusable"); + expect(r.reason).toContain("unparseable"); + }); + it("EC4b: runner=true + '' → unusable", () => { + expect(probeSandbox(true, "").capability).toBe("unusable"); + }); + it("EC4c: runner=true + 'garbage' → unusable", () => { + expect(probeSandbox(true, "garbage").capability).toBe("unusable"); + }); + + // --- 边界值 --- + it("BV1: 5.13.0 → full(门槛刚好满足)", () => { + expect(probeSandbox(true, "5.13.0").capability).toBe("full"); + }); + it("BV2: 5.13.1 → full(门槛之上 1)", () => { + expect(probeSandbox(true, "5.13.1").capability).toBe("full"); + }); + it("BV3: 5.12.99 → partial(门槛之下 1)", () => { + expect(probeSandbox(true, "5.12.99").capability).toBe("partial"); + }); + it("BV4: 6.0 → full(远大于门槛)", () => { + expect(probeSandbox(true, "6.0").capability).toBe("full"); + }); + it("BV5: 5.13 → full(无 patch 段)", () => { + expect(probeSandbox(true, "5.13").capability).toBe("full"); + }); + it("BV6: '5' → partial(单段 = 5.0 < 5.13)", () => { + expect(probeSandbox(true, "5").capability).toBe("partial"); + }); + it("BV7: 'v5.13' → full(v 前缀剥离后满足)", () => { + expect(probeSandbox(true, "v5.13").capability).toBe("full"); + }); + it("BV8: '5.13.0-rc1' → full(rc 后缀剥离后满足)", () => { + expect(probeSandbox(true, "5.13.0-rc1").capability).toBe("full"); + }); +}); + +// ============================================================================ +// ② 决策表 —— (runnerAvailable × kernel≥5.13) → capability × shouldRun +// ============================================================================ +// 完整决策表:每行一个组合,断言 capability + shouldRunCommand 联动。 + +interface DecisionRow { + runner: boolean; + kernel: string | undefined; + capability: SandboxCapability; + shouldRun: boolean; +} + +const DECISION_TABLE: DecisionRow[] = [ + // runner 不可用 → 永远 unusable + refuse + { runner: false, kernel: "5.13.0", capability: "unusable", shouldRun: false }, + { runner: false, kernel: "6.0.0", capability: "unusable", shouldRun: false }, + { runner: false, kernel: undefined, capability: "unusable", shouldRun: false }, + // runner 可用 + ≥5.13 → full + run + { runner: true, kernel: "5.13.0", capability: "full", shouldRun: true }, + { runner: true, kernel: "5.13.1", capability: "full", shouldRun: true }, + { runner: true, kernel: "6.0.0", capability: "full", shouldRun: true }, + { runner: true, kernel: "5.13", capability: "full", shouldRun: true }, + { runner: true, kernel: "v5.13", capability: "full", shouldRun: true }, + { runner: true, kernel: "5.13.0-rc1", capability: "full", shouldRun: true }, + // runner 可用 + <5.13 → partial + run(降级但仍可跑) + { runner: true, kernel: "5.12.0", capability: "partial", shouldRun: true }, + { runner: true, kernel: "5.12.99", capability: "partial", shouldRun: true }, + { runner: true, kernel: "4.19.0", capability: "partial", shouldRun: true }, + { runner: true, kernel: "5", capability: "partial", shouldRun: true }, // 5.0 < 5.13 + // runner 可用 + 内核不可解析/缺失 → unusable + refuse(fail-closed 安全默认) + { runner: true, kernel: undefined, capability: "unusable", shouldRun: false }, + { runner: true, kernel: "", capability: "unusable", shouldRun: false }, + { runner: true, kernel: "garbage", capability: "unusable", shouldRun: false }, + { runner: true, kernel: "not-a-version", capability: "unusable", shouldRun: false }, + { runner: true, kernel: "ubuntu-22.04", capability: "unusable", shouldRun: false }, +]; + +describe("sandbox-policy 决策表 — runner × kernel → capability × shouldRun", () => { + // 用 it.each 参数化驱动决策表全行 + it.each(DECISION_TABLE)( + "runner=$runner kernel=$kernel → capability=$capability shouldRun=$shouldRun", + (row) => { + const probe = probeSandbox(row.runner, row.kernel); + expect(probe.capability).toBe(row.capability); + expect(shouldRunCommand(probe)).toBe(row.shouldRun); + }, + ); + + // 决策表完整性:unusable ⟹ shouldRun=false;full/partial ⟹ shouldRun=true + it("决策表一致性:所有 unusable 行 shouldRun=false,所有 full/partial 行 shouldRun=true", () => { + for (const row of DECISION_TABLE) { + const probe = probeSandbox(row.runner, row.kernel); + if (probe.capability === "unusable") { + expect(shouldRunCommand(probe)).toBe(false); + } else { + expect(shouldRunCommand(probe)).toBe(true); + } + } + }); +}); + +// ============================================================================ +// ② shouldRunCommand —— fail-closed 执行门(独立 + 联动) +// ============================================================================ + +describe("sandbox-policy shouldRunCommand — fail-closed 执行门", () => { + it("unusable → false", () => { + expect(shouldRunCommand({ capability: "unusable", reason: "x" })).toBe(false); + }); + it("full → true", () => { + expect(shouldRunCommand({ capability: "full", reason: "x" })).toBe(true); + }); + it("partial → true(降级但仍可跑)", () => { + expect(shouldRunCommand({ capability: "partial", reason: "x" })).toBe(true); + }); + it("联动:runner=false → shouldRun=false", () => { + expect(shouldRunCommand(probeSandbox(false, "5.13.0"))).toBe(false); + }); + it("联动:runner=true + 5.13 → shouldRun=true", () => { + expect(shouldRunCommand(probeSandbox(true, "5.13.0"))).toBe(true); + }); +}); + +// ============================================================================ +// applySandboxToArgv —— 决策表(capability × argv 形态) +// ============================================================================ + +describe("sandbox-policy applySandboxToArgv — 决策表", () => { + const policy: BoardSandboxPolicy = DEFAULT_BOARD_SANDBOX_POLICY; + const sampleArgv = ["ls", "-la", "/tmp"]; + + // 行 1: unusable → 不包装,argv 原样返回(引用同一) + it("unusable → sandboxed=false,argv 原样返回(引用同一)", () => { + const result = applySandboxToArgv(sampleArgv, policy, "unusable"); + expect(result.sandboxed).toBe(false); + expect(result.argv).toBe(sampleArgv); + expect(result.argv).toEqual(["ls", "-la", "/tmp"]); + }); + + // 行 2: full → 包装 + it("full → sandboxed=true,argv 前缀 runner token + 策略根 + -- + 原始", () => { + const result = applySandboxToArgv(sampleArgv, policy, "full"); + expect(result.sandboxed).toBe(true); + expect(result.argv).toEqual([ + RUNNER_TOKEN, + FLAG_READ_ONLY, "/", + FLAG_READ_WRITE, "/workspace", + FLAG_SEPARATOR, + "ls", "-la", "/tmp", + ]); + }); + + // 行 3: partial → 包装(形式与 full 一致) + it("partial → sandboxed=true,包装形式与 full 一致", () => { + const result = applySandboxToArgv(sampleArgv, policy, "partial"); + expect(result.sandboxed).toBe(true); + expect(result.argv).toEqual([ + RUNNER_TOKEN, + FLAG_READ_ONLY, "/", + FLAG_READ_WRITE, "/workspace", + FLAG_SEPARATOR, + "ls", "-la", "/tmp", + ]); + }); + + // 包装后原始 argv 在 "--" 之后(可检索) + it("包装后原始 argv 是 '--' 之后的后缀", () => { + const result = applySandboxToArgv(["echo", "hello"], policy, "full"); + const sepIdx = result.argv.indexOf(FLAG_SEPARATOR); + expect(sepIdx).toBeGreaterThan(0); + expect(result.argv.slice(sepIdx + 1)).toEqual(["echo", "hello"]); + }); + + // 自定义策略(多根 + allowedSyscalls 不出现在 argv) + it("自定义策略(多只读/读写根)按序展开", () => { + const custom: BoardSandboxPolicy = { + readOnlyRoots: ["/etc", "/proc"], + readWriteRoots: ["/tmp", "/var/log"], + allowedSyscalls: ["read", "write", "openat"], + }; + const result = applySandboxToArgv(["cat", "/etc/hosts"], custom, "full"); + expect(result.argv).toEqual([ + RUNNER_TOKEN, + FLAG_READ_ONLY, "/etc", "/proc", + FLAG_READ_WRITE, "/tmp", "/var/log", + FLAG_SEPARATOR, + "cat", "/etc/hosts", + ]); + // allowedSyscalls 不在 argv 中(T05a 模拟 runner 不消费 syscall 白名单) + expect(result.argv).not.toContain("read"); + }); +}); + +// ============================================================================ +// ③ 状态转换 —— 命令生命周期:probe → resolve → wrap → spawn/refuse → result +// ============================================================================ +// 把沙箱决策建模为有限状态机,断言每个状态的转移条件 + 输出。 + +type LifecycleState = + | "probing" + | "resolved" + | "wrapped" + | "refused" + | "spawned"; + +interface LifecycleTrace { + state: LifecycleState; + probe: SandboxProbeResult; + canRun: boolean; + wrappedArgv: readonly string[] | null; + result: { exitCode: number; sandboxed: boolean } | null; +} + +/** + * 模拟命令生命周期状态机(纯逻辑,复用 sandbox-policy 原语)。 + * - probing: 探活 runner + 内核 → probe + * - resolved: shouldRunCommand(probe) → canRun + * - wrapped / refused: applySandboxToArgv 或拒绝 + * - spawned: 产出 exitCode + sandboxed + */ +function runLifecycle( + runnerAvailable: boolean, + kernel: string | undefined, + argv: readonly string[], + policy: BoardSandboxPolicy, +): LifecycleTrace { + // State: probing → resolved + const probe = probeSandbox(runnerAvailable, kernel); + const canRun = shouldRunCommand(probe); + // State: resolved → wrapped | refused + if (!canRun) { + return { state: "refused", probe, canRun, wrappedArgv: null, result: { exitCode: 126, sandboxed: false } }; + } + const { argv: wrapped, sandboxed } = applySandboxToArgv(argv, policy, probe.capability); + // State: wrapped → spawned + return { state: "spawned", probe, canRun, wrappedArgv: wrapped, result: { exitCode: 0, sandboxed } }; +} + +describe("sandbox-policy 状态转换 — 命令生命周期", () => { + const policy = DEFAULT_BOARD_SANDBOX_POLICY; + + it("full 路径:probing → resolved → wrapped → spawned", () => { + const trace = runLifecycle(true, "5.13.0", ["ls", "/tmp"], policy); + expect(trace.state).toBe("spawned"); + expect(trace.probe.capability).toBe("full"); + expect(trace.canRun).toBe(true); + expect(trace.wrappedArgv).not.toBeNull(); + expect(trace.result).toEqual({ exitCode: 0, sandboxed: true }); + }); + + it("partial 路径:probing → resolved → wrapped → spawned(降级但仍 spawn)", () => { + const trace = runLifecycle(true, "5.12.0", ["pwd"], policy); + expect(trace.state).toBe("spawned"); + expect(trace.probe.capability).toBe("partial"); + expect(trace.canRun).toBe(true); + expect(trace.result).toEqual({ exitCode: 0, sandboxed: true }); + }); + + it("unusable 路径(runner 缺失):probing → resolved → refused", () => { + const trace = runLifecycle(false, "5.13.0", ["ls"], policy); + expect(trace.state).toBe("refused"); + expect(trace.probe.capability).toBe("unusable"); + expect(trace.canRun).toBe(false); + expect(trace.wrappedArgv).toBeNull(); + expect(trace.result).toEqual({ exitCode: 126, sandboxed: false }); + }); + + it("unusable 路径(内核不可解析):probing → resolved → refused", () => { + const trace = runLifecycle(true, "garbage", ["ls"], policy); + expect(trace.state).toBe("refused"); + expect(trace.probe.capability).toBe("unusable"); + expect(trace.result).toEqual({ exitCode: 126, sandboxed: false }); + }); + + it("状态转移确定性:同输入两次跑产生相同 trace(元蜕变不变式)", () => { + const a = runLifecycle(true, "5.13.0", ["echo", "hi"], policy); + const b = runLifecycle(true, "5.13.0", ["echo", "hi"], policy); + expect(a.state).toBe(b.state); + expect(a.probe.capability).toBe(b.probe.capability); + expect(a.result).toEqual(b.result); + expect(a.wrappedArgv).toEqual(b.wrappedArgv); + }); +}); + +// ============================================================================ +// ④ 变异测试 —— 植入 3 个 bug,断言测试能抓住(mutation kill) +// ============================================================================ +// 每个变异体复制正确逻辑但植入一个 bug;断言变异体输出 ≠ 正确输出, +// 证明:若该 bug 进入生产,上述测试会失败(kill)。 + +describe("sandbox-policy 变异测试 —— 植入 bug 必被抓住", () => { + // --- 变异体 1:shouldRunCommand 的 !== 翻转为 === --- + // bug:unusable 本应返回 false,翻转后返回 true → 被抓 + it("M1: shouldRunCommand !==→=== 翻转:unusable 误返回 true(应 false)", () => { + const mutant = (probe: SandboxProbeResult): boolean => probe.capability === "unusable"; + const correct = shouldRunCommand({ capability: "unusable", reason: "x" }); + const mutated = mutant({ capability: "unusable", reason: "x" }); + expect(correct).toBe(false); + expect(mutated).toBe(true); // 变异体行为错误 + expect(mutated).not.toBe(correct); // 测试能区分 → kill + }); + + // --- 变异体 2:版本比较 >= 翻转为 >(5.13.0 本应 full,变异后变 partial)--- + it("M2: 版本比较 >=→> 翻转:5.13.0 误判 partial(应 full)", () => { + const mutant = (major: number, minor: number): boolean => { + // bug: >= 翻转为 >(5.13.0 不再满足) + return major > 5 || (major === 5 && minor > 13); + }; + const correctFull = mutant(5, 13) === false; // 正确逻辑下 5.13 应 full + expect(correctFull).toBe(true); // 变异体漏判 5.13 → 与正确行为不同 → kill + // 直接对照:正确 probeSandbox 给 full,变异体判 partial + expect(probeSandbox(true, "5.13.0").capability).toBe("full"); + expect(mutant(5, 13)).toBe(false); // 变异体说"不满足" → 与 full 矛盾 + }); + + // --- 变异体 3:parseKernelVersion 不剥离 v 前缀("v5.13" 误返 null → unusable)--- + it("M3: parseKernelVersion 不剥 v 前缀:'v5.13' 误返 null(应 {5,13})", () => { + // 变异体:不 strip 'v',直接 match + const mutant = (raw: string | undefined): { major: number; minor: number } | null => { + if (raw === undefined) return null; + const trimmed = raw.trim(); + if (trimmed === "") return null; + // bug:没有剥离 v 前缀,"v5.13" 不匹配 ^\d+ + const match = trimmed.match(/^(\d+)(?:\.(\d+))?/); + if (!match) return null; + const major = Number.parseInt(match[1], 10); + const minor = match[2] !== undefined ? Number.parseInt(match[2], 10) : 0; + return { major, minor }; + }; + // 正确逻辑能解析 v5.13 + expect(parseKernelVersion("v5.13")).toEqual({ major: 5, minor: 13 }); + // 变异体漏掉 v 前缀 → 返回 null + expect(mutant("v5.13")).toBeNull(); + expect(mutant("v5.13")).not.toEqual(parseKernelVersion("v5.13")); // 测试能区分 → kill + // 连锁:变异体下 probeSandbox(true,"v5.13") 会判 unusable(应为 full) + const correctProbe = probeSandbox(true, "v5.13"); + expect(correctProbe.capability).toBe("full"); + // 变异体路径:parse 返回 null → probeSandbox unusable + const mutantParse = mutant("v5.13"); + expect(mutantParse).toBeNull(); + }); +}); + +// ============================================================================ +// ⑤ 对抗 / 模糊 —— 畸形内核串、空/巨 argv、空根策略 +// ============================================================================ + +describe("sandbox-policy 对抗 / 模糊输入", () => { + const policy = DEFAULT_BOARD_SANDBOX_POLICY; + + // --- 畸形内核串(it.each 参数化)--- + const malformedKernels = [ + "", " ", "not-a-version", "ubuntu-22.04", "5.x", "abc.def", + "5.13.0.0.0.0", "v", "V", "5.", ".13", "---", "0x5", "five", + ]; + it.each(malformedKernels)("畸形内核 '%s' → parseKernelVersion 返回 null 或合法 {major,minor}", (k) => { + const parsed = parseKernelVersion(k); + // 要么 null(不可解析),要么合法数字对(不能是 NaN) + if (parsed !== null) { + expect(Number.isInteger(parsed.major)).toBe(true); + expect(Number.isInteger(parsed.minor)).toBe(true); + expect(Number.isNaN(parsed.major)).toBe(false); + expect(Number.isNaN(parsed.minor)).toBe(false); + } + }); + it.each(malformedKernels)("畸形内核 '%s' → probeSandbox(true, ...) 不崩溃", (k) => { + const probe = probeSandbox(true, k); + expect(["full", "partial", "unusable"]).toContain(probe.capability); + }); + + // --- 空 argv --- + it("空 argv [] → full 时包装为 runner token + 策略 + --", () => { + const result = applySandboxToArgv([], policy, "full"); + expect(result.sandboxed).toBe(true); + expect(result.argv).toEqual([ + RUNNER_TOKEN, + FLAG_READ_ONLY, "/", + FLAG_READ_WRITE, "/workspace", + FLAG_SEPARATOR, + ]); + }); + it("空 argv [] → unusable 时原样返回", () => { + const result = applySandboxToArgv([], policy, "unusable"); + expect(result.sandboxed).toBe(false); + expect(result.argv).toEqual([]); + }); + + // --- 巨 argv(10000 个参数)--- + it("巨 argv(10000 元素)→ 完整包装,原始元素全在 '--' 之后", () => { + const huge = Array.from({ length: 10_000 }, (_, i) => `arg${i}`); + const result = applySandboxToArgv(huge, policy, "full"); + expect(result.sandboxed).toBe(true); + expect(result.argv.length).toBe(huge.length + 6); // 6 = token + ro + 1 root + rw + 1 root + sep + const sepIdx = result.argv.indexOf(FLAG_SEPARATOR); + expect(sepIdx).toBe(5); + expect(result.argv.slice(sepIdx + 1)).toEqual(huge); + }); + + // --- 空根策略 --- + it("空根策略(readOnlyRoots=[] readWriteRoots=[])→ '--ro --rw --' 空展开", () => { + const empty: BoardSandboxPolicy = { readOnlyRoots: [], readWriteRoots: [] }; + const result = applySandboxToArgv(["pwd"], empty, "full"); + expect(result.argv).toEqual([RUNNER_TOKEN, FLAG_READ_ONLY, FLAG_READ_WRITE, FLAG_SEPARATOR, "pwd"]); + }); + + // --- 超大版本号(不溢出 / 不 NaN)--- + it("超大版本 '999999999.999999999' → parse 不 NaN", () => { + const parsed = parseKernelVersion("999999999.999999999"); + expect(parsed).not.toBeNull(); + expect(Number.isNaN(parsed!.major)).toBe(false); + }); +}); + +// ============================================================================ +// ⑥ 不变式 / 元蜕变 —— fail-closed:unusable ⟹ never wraps + refuse +// ============================================================================ +// 跨所有 unusable 成因,断言:shouldRunCommand=false AND applySandboxToArgv sandboxed=false。 +// 这是 fail-closed 安全不变式 —— 任何 unusable 原因都不能导致 spawn 或包装。 + +describe("sandbox-policy fail-closed 不变式 —— unusable ⟹ never wraps + refuse", () => { + const policy = DEFAULT_BOARD_SANDBOX_POLICY; + + // 枚举所有导致 unusable 的成因 + const unusableCauses: Array<{ name: string; runner: boolean; kernel: string | undefined }> = [ + { name: "runner 缺失", runner: false, kernel: "5.13.0" }, + { name: "runner=0 + 任意内核", runner: false, kernel: "6.0.0" }, + { name: "runner=0 + 内核缺失", runner: false, kernel: undefined }, + { name: "runner=1 + 内核 undefined", runner: true, kernel: undefined }, + { name: "runner=1 + 空串", runner: true, kernel: "" }, + { name: "runner=1 + 纯空白", runner: true, kernel: " " }, + { name: "runner=1 + 非版本串", runner: true, kernel: "not-a-version" }, + { name: "runner=1 + 发行版名", runner: true, kernel: "ubuntu-22.04" }, + { name: "runner=1 + 字母前缀无数字", runner: true, kernel: "garbage" }, + ]; + + it.each(unusableCauses)( + "不变式 [$name]:unusable ⟹ shouldRun=false AND sandboxed=false", + (cause) => { + const probe = probeSandbox(cause.runner, cause.kernel); + // 前提:确实判为 unusable + expect(probe.capability).toBe("unusable"); + // 不变式 1:shouldRunCommand=false(拒绝执行) + expect(shouldRunCommand(probe)).toBe(false); + // 不变式 2:applySandboxToArgv sandboxed=false(不包装,原样返回) + const wrap = applySandboxToArgv(["ls", "/tmp"], policy, probe.capability); + expect(wrap.sandboxed).toBe(false); + // 不变式 3:argv 不含 runner token(绝不产出可 spawn 的包装) + expect(wrap.argv).not.toContain(RUNNER_TOKEN); + expect(wrap.argv).toEqual(["ls", "/tmp"]); + }, + ); + + // 元蜕变:对任意输入,capability=unusable ⟹ sandboxed=false(对偶命题) + it("元蜕变:对任意 (runner, kernel),capability=unusable ⟹ applySandboxToArgv sandboxed=false", () => { + const inputs: Array<[boolean, string | undefined]> = [ + [false, "5.13.0"], [false, undefined], [false, ""], + [true, undefined], [true, ""], [true, "garbage"], [true, "not-a-version"], + [true, "5.12.0"], [true, "5.13.0"], [true, "v5.13"], + ]; + for (const [runner, kernel] of inputs) { + const probe = probeSandbox(runner, kernel); + const wrap = applySandboxToArgv(["echo"], policy, probe.capability); + if (probe.capability === "unusable") { + expect(wrap.sandboxed).toBe(false); + expect(wrap.argv).not.toContain(RUNNER_TOKEN); + } else { + expect(wrap.sandboxed).toBe(true); + expect(wrap.argv).toContain(RUNNER_TOKEN); + } + } + }); +}); + +// ============================================================================ +// DEFAULT_BOARD_SANDBOX_POLICY —— 单一共享 home + 不可变性 +// ============================================================================ + +describe("sandbox-policy DEFAULT_BOARD_SANDBOX_POLICY — 单一共享 home", () => { + it("默认策略:只读根=['/'],读写根=['/workspace']", () => { + expect(DEFAULT_BOARD_SANDBOX_POLICY.readOnlyRoots).toEqual(["/"]); + expect(DEFAULT_BOARD_SANDBOX_POLICY.readWriteRoots).toEqual(["/workspace"]); + }); + + it("Object.is 引用同一(ESM 模块单例)", () => { + expect(Object.is(DEFAULT_BOARD_SANDBOX_POLICY, DEFAULT_BOARD_SANDBOX_POLICY)).toBe(true); + }); + + it("Object.freeze:策略对象不可扩展(添加属性抛 TypeError strict mode / 静默失败)", () => { + // frozen 对象在 strict mode 下赋值新属性抛 TypeError + expect(() => { + (DEFAULT_BOARD_SANDBOX_POLICY as unknown as Record).evil = "x"; + }).toThrow(TypeError); + }); + + it("冻结的 readOnlyRoots 数组不可变(push 抛 TypeError)", () => { + expect(() => { + (DEFAULT_BOARD_SANDBOX_POLICY.readOnlyRoots as string[]).push("/evil"); + }).toThrow(TypeError); + }); + + it("冻结的 readWriteRoots 数组不可变", () => { + expect(() => { + (DEFAULT_BOARD_SANDBOX_POLICY.readWriteRoots as string[]).push("/evil"); + }).toThrow(TypeError); + }); +}); + +// ============================================================================ +// T05b probeViaBinary —— 真 landlock-run 二进制探活契约 +// ============================================================================ + +import { probeViaBinary, type SandboxBinaryRunner } from "../src/core/sandbox-policy.js"; + +describe("T05b probeViaBinary —— exit code 决策表", () => { + const mk = (exitCode: number | null, stderr = ""): SandboxBinaryRunner => () => ({ exitCode, stderr }); + it.each([ + [0, "full"], // landlock 完整 + [1, "partial"], // seccomp-only 回退 + [2, "unusable"], // probe 明示 unusable + [126, "unusable"], // fail-closed exit + [null, "unusable"], // 信号杀掉未退出 + [127, "unusable"], // 其它非 0/1 + ])("exit %s → capability %s", (code, cap) => { + const p = probeViaBinary("/x/landlock-run", mk(code as number | null)); + expect(p.capability).toBe(cap); + }); +}); + +describe("T05b probeViaBinary —— fail-closed 不变式", () => { + it("runner 抛错 → unusable(不泄漏异常)", () => { + const throwing: SandboxBinaryRunner = () => { throw new Error("spawn ENOENT"); }; + const p = probeViaBinary("/x/landlock-run", throwing); + expect(p.capability).toBe("unusable"); + expect(p.reason).toContain("failed"); + }); + + it("full/partial 应可跑,unusable 不可跑(与 shouldRunCommand 联动)", () => { + for (const code of [0, 1, 2, 126] as const) { + const p = probeViaBinary("/x", () => ({ exitCode: code, stderr: "" })); + const canRun = p.capability !== "unusable"; + if (code === 0 || code === 1) expect(canRun).toBe(true); + else expect(canRun).toBe(false); + } + }); +}); + +describe("T05b 真 landlock-run-stub 二进制契约", () => { + // 仅当本机编译了 stub(make native)才跑;CI/无编译器则 skip。 + const { existsSync } = require("node:fs"); + const stub = "native/landlock-run/landlock-run-stub"; + const hasStub = existsSync(stub); + (hasStub ? it : it.skip)("landlock-run-stub --probe 返回 exit 2(macOS 无 landlock = unusable)", () => { + const cp = require("node:child_process"); + const res = cp.spawnSync(stub, ["--probe"], { encoding: "utf8" }); + // macOS 无 landlock → exit 2 = unusable;Linux 无 landlock 头编译失败则 stub 不存在 + expect(res.status).toBe(2); + }); + (hasStub ? it : it.skip)("landlock-run-stub --ro/--rw/-- 执行 cmd(stub 不沙箱直 exec)", () => { + const cp = require("node:child_process"); + const res = cp.spawnSync(stub, ["--ro", "/", "--rw", "/tmp", "--", "/bin/echo", "ok"], { encoding: "utf8" }); + expect(res.stdout.trim()).toBe("ok"); + }); +}); diff --git a/tests/tool-pipeline.test.ts b/tests/tool-pipeline.test.ts new file mode 100644 index 0000000..2c7befd --- /dev/null +++ b/tests/tool-pipeline.test.ts @@ -0,0 +1,280 @@ +import { describe, it, expect } from "vitest"; +import { + ToolPipeline, + withTimeout, + type ToolCallContext, + type MonotonicGuard, + type PreExecuteListener, + type PostExecuteListener, + type AroundListener, + type ToolResult, +} from "../src/core/tool-pipeline.js"; + +/** 构造最小 ctx。 */ +function ctx(over: Partial = {}): ToolCallContext { + return { + toolName: over.toolName ?? "t", + input: over.input ?? {}, + toolCallId: over.toolCallId ?? "tc1", + ...over, + }; +} + +const okResult: ToolResult = { content: [{ type: "text", text: "ok" }] }; + +describe("tool-pipeline 状态转换 —— 五段顺序(T04)", () => { + // 状态机:pre-execute → guards → approval? → execute(around) → post → finalize + it("全 allow 路径:五段依次执行,终局 executed", async () => { + const p = new ToolPipeline(); + p.registerGuard({ id: "g1", evaluate: async () => ({ decision: "allow" }) }); + const body = async () => ({ content: [{ type: "text", text: "ran" }] }); + const out = await p.run(ctx(), body); + expect(out.outcome).toBe("executed"); + if (out.outcome === "executed") expect(out.result.content).toEqual([{ type: "text", text: "ran" }]); + }); + + it("guard deny 在 execute 前短路:body 不跑", async () => { + const p = new ToolPipeline(); + p.registerGuard({ id: "g-deny", evaluate: async () => ({ decision: "deny", reason: "no" }) }); + let ran = false; + const body = async () => { + ran = true; + return okResult; + }; + const out = await p.run(ctx(), body); + expect(out.outcome).toBe("denied"); + expect(ran).toBe(false); + }); + + it("pre-execute deny 在 execute 前短路:body 不跑", async () => { + const p = new ToolPipeline(); + p.onPreExecute(async () => ({ decision: "deny", reason: "pre-no" })); + let ran = false; + const out = await p.run(ctx(), async () => { + ran = true; + return okResult; + }); + expect(out.outcome).toBe("denied"); + expect(ran).toBe(false); + }); + + it("post-execute block:body 跑了但终局 blocked", async () => { + const p = new ToolPipeline(); + let ran = false; + p.onPostExecute(async () => ({ action: "block", reason: "post-no" })); + const out = await p.run(ctx(), async () => { + ran = true; + return okResult; + }); + expect(out.outcome).toBe("blocked"); + expect(ran).toBe(true); + }); + + it("post-execute replace:终局 replaced + 替换结果", async () => { + const p = new ToolPipeline(); + const replaced: ToolResult = { content: [{ type: "text", text: "replaced" }] }; + p.onPostExecute(async () => ({ action: "replace", result: replaced })); + const out = await p.run(ctx(), async () => okResult); + expect(out.outcome).toBe("replaced"); + if (out.outcome === "replaced") expect(out.result.content).toEqual(replaced.content); + }); + + it("finalizeContent 在 post 之后执行:强制 content-only", async () => { + const p = new ToolPipeline(); + const finalize = (r: ToolResult) => ({ content: `finalized(${JSON.stringify(r.content)})` }); + const out = await p.run(ctx({ finalizeContent: finalize }), async () => ({ + content: [{ type: "text", text: "raw" }], + })); + expect(out.outcome).toBe("executed"); + if (out.outcome === "executed") expect(out.result.content).toBe('finalized([{"type":"text","text":"raw"}])'); + }); +}); + +describe("tool-pipeline 单调不变式 —— 任一 guard deny ⟹ 终局 deny(无论多少 allow)", () => { + // 元蜕变:对任意 guard 序列,含 deny ⟹ denied;全 allow ⟹ executed。 + it("一个 deny + 多个 allow:终局 denied(force-allow 失败)", async () => { + const p = new ToolPipeline(); + p.registerGuard({ id: "a1", evaluate: async () => ({ decision: "allow" }) }); + p.registerGuard({ id: "deny1", evaluate: async () => ({ decision: "deny", reason: "brick" }) }); + p.registerGuard({ id: "a2", evaluate: async () => ({ decision: "allow" }) }); + const out = await p.run(ctx(), async () => okResult); + expect(out.outcome).toBe("denied"); + }); + + it("pre-execute allow 不能覆盖 guard deny(单调性)", async () => { + const p = new ToolPipeline(); + // pre-execute 明确 allow + p.onPreExecute(async () => ({ decision: "allow" })); + // guard deny + p.registerGuard({ id: "deny-g", evaluate: async () => ({ decision: "deny", reason: "guard-no" }) }); + const out = await p.run(ctx(), async () => okResult); + expect(out.outcome).toBe("denied"); + if (out.outcome === "denied") expect(out.reason).toContain("guard"); + }); + + // 确定性伪随机(不引入 Math.random):100 组 guard 序列,单调性恒成立 + it("元蜕变:100 组随机 guard 序列,含 deny ⟹ denied(确定性采样)", async () => { + let seed = 7; + const rand = () => { + seed = (seed * 1103515245 + 12345) & 0x7fffffff; + return seed; + }; + for (let i = 0; i < 100; i++) { + const p = new ToolPipeline(); + let hasDeny = false; + for (let g = 0; g < 5; g++) { + const d = rand() % 3; // 0=allow 1=deny 2=allow + if (d === 1) hasDeny = true; + p.registerGuard({ + id: `g${g}`, + evaluate: async () => + d === 1 ? { decision: "deny" as const, reason: "x" } : { decision: "allow" as const }, + }); + } + const out = await p.run(ctx(), async () => okResult); + if (hasDeny) expect(out.outcome).toBe("denied"); + else expect(out.outcome).toBe("executed"); + } + }); +}); + +describe("tool-pipeline 决策表 —— guard × pre-execute × post → outcome", () => { + it.each([ + // [guard, preExec, post, expected] + ["allow", "allow", "accept", "executed"], + ["deny", "allow", "accept", "denied"], + ["allow", "deny", "accept", "denied"], + ["allow", "allow", "block", "blocked"], + ["allow", "allow", "replace", "replaced"], + ["deny", "deny", "block", "denied"], // guard 优先于 pre + post + ])("guard=%s pre=%s post=%s → %s", async (g, pre, post, expected) => { + const p = new ToolPipeline(); + p.registerGuard({ + id: "g", + evaluate: async () => + g === "deny" ? { decision: "deny", reason: "g" } : { decision: "allow" }, + }); + if (pre === "deny") { + p.onPreExecute(async () => ({ decision: "deny", reason: "p" })); + } + p.onPostExecute(async () => { + if (post === "block") return { action: "block", reason: "b" }; + if (post === "replace") return { action: "replace", result: { content: "r" } }; + return { action: "accept" }; + }); + const out = await p.run(ctx(), async () => okResult); + expect(out.outcome).toBe(expected); + }); +}); + +describe("tool-pipeline 变异测试 —— 植入 bug 必被抓住", () => { + // M1:若单调性被破坏(用 last-wins 而非 any-deny),deny 不该被 allow 覆盖。 + // 证构造正确:deny 在前 + allow 在后仍 denied。 + it("M1: deny 在前、allow 在后 → 仍 denied(非 last-wins)", async () => { + const p = new ToolPipeline(); + p.registerGuard({ id: "deny-first", evaluate: async () => ({ decision: "deny", reason: "x" }) }); + p.registerGuard({ id: "allow-last", evaluate: async () => ({ decision: "allow" }) }); + const out = await p.run(ctx(), async () => okResult); + expect(out.outcome).toBe("denied"); + }); + + // M2:around 链顺序。timeout(外层)包裹 body;若顺序被破坏,timeout 不生效。 + it("M2: withTimeout 包裹慢 body → 超时 isError(around 顺序正确)", async () => { + const p = new ToolPipeline(); + p.onAround(withTimeout(30)); + const out = await p.run(ctx(), async () => { + await new Promise((r) => setTimeout(r, 200)); + return okResult; + }); + expect(out.outcome).toBe("executed"); + if (out.outcome === "executed") { + expect(out.result.isError).toBe(true); + const text = (out.result.content as Array<{ text: string }>)[0]?.text ?? ""; + expect(text).toContain("TIMEOUT"); + } + }); +}); + +describe("tool-pipeline approval —— ask fail-closed", () => { + it("ask 无 resolver → fail-closed denied", async () => { + const p = new ToolPipeline(); + p.registerGuard({ id: "ask-g", evaluate: async () => ({ decision: "ask", reason: "confirm?" }) }); + const out = await p.run(ctx(), async () => okResult); + expect(out.outcome).toBe("denied"); + if (out.outcome === "denied") expect(out.reason).toContain("fail-closed"); + }); + + it("ask + resolver=true → executed", async () => { + const p = new ToolPipeline(); + p.registerGuard({ id: "ask-g", evaluate: async () => ({ decision: "ask", reason: "confirm?" }) }); + const out = await p.run( + ctx({ approvalResolver: async () => true }), + async () => okResult, + ); + expect(out.outcome).toBe("executed"); + }); + + it("ask + resolver=false → denied", async () => { + const p = new ToolPipeline(); + p.registerGuard({ id: "ask-g", evaluate: async () => ({ decision: "ask", reason: "confirm?" }) }); + const out = await p.run( + ctx({ approvalResolver: async () => false }), + async () => okResult, + ); + expect(out.outcome).toBe("denied"); + }); +}); + +describe("tool-pipeline waterfall next() 委托 —— pre-execute 中间件链", () => { + it("listener A 包装结果传 B(A 在前,调 next() 给 B)", async () => { + const order: string[] = []; + const p = new ToolPipeline(); + p.onPreExecute(async (_c, next) => { + order.push("A-before"); + const v = await next(); + order.push("A-after"); + return v; + }); + p.onPreExecute(async () => { + order.push("B"); + return { decision: "allow" }; + }); + await p.run(ctx(), async () => okResult); + expect(order).toEqual(["A-before", "B", "A-after"]); + }); + + it("首 listener 不调 next() 即短路(abstain 不传递)", async () => { + const p = new ToolPipeline(); + p.onPreExecute(async () => ({ decision: "deny", reason: "first" })); + let bRan = false; + p.onPreExecute(async () => { + bRan = true; + return { decision: "allow" }; + }); + const out = await p.run(ctx(), async () => okResult); + expect(out.outcome).toBe("denied"); + expect(bRan).toBe(false); + }); +}); + +describe("tool-pipeline guard 身份保护 —— 重复 id 替换(重装配幂等)", () => { + it("重复 id 注册即替换(last evaluate 生效,重装配幂等不抛)", async () => { + const p = new ToolPipeline(); + p.registerGuard({ id: "dup", evaluate: async () => ({ decision: "deny", reason: "first" }) }); + // 重新注册同 id:替换为 allow,不抛 + p.registerGuard({ id: "dup", evaluate: async () => ({ decision: "allow" }) }); + const out = await p.run(ctx(), async () => okResult); + expect(out.outcome).toBe("executed"); // last evaluate(allow)生效 + }); + + it("disposer 卸载 guard 后不再评估", async () => { + const p = new ToolPipeline(); + const dispose = p.registerGuard({ + id: "tmp", + evaluate: async () => ({ decision: "deny", reason: "tmp" }), + }); + dispose(); + const out = await p.run(ctx(), async () => okResult); + expect(out.outcome).toBe("executed"); + }); +}); diff --git a/架构设计文档_v3.md b/架构设计文档_v3.md new file mode 100644 index 0000000..fbaaa52 --- /dev/null +++ b/架构设计文档_v3.md @@ -0,0 +1,844 @@ +# Physical Byte Agent 架构设计文档(v3) + +> 项目:`@d-robotics/physical-byte-agent`(pi 二开嵌入式硬件闭环 Agent) +> 路径:`/Users/d-robotics/Desktop/physical_byte_agent` +> 当前版本:v2 重构完成(commit 06a19a6,21 域扩展,732 单测,tsc 0 错,离线装配冒烟 21 工厂) +> v3 P0 进展(2026-08-14):**T01-T05a + T05b 全部落地**;1044 单测全绿,tsc 0 错。详见第七部分进度表。 +> 本版本:v3——嫁接 dsh 八条工业骨架到 pi 扩展底座,补齐致命差距,迈向"能安全跑通嵌入式闭环" +> 文档日期:2026-08-14 +> 文档目的:从顶层架构一路拆解到一堆具体的、可执行、可验证的开发任务,并在底部维护进度 +> 输入依据: +> - 《deepseek_harness_深度研究剖析报告.md》(dsh 架构与源码锚点) +> - 《deepseek_harness创新点与physical_byte_agent差距分析报告.md》(18 条差距矩阵 G1-G18) +> - physical_byte_agent 实读源码(src/extensions/*.ts、src/agent.ts、src/shared/types.ts、bin/pba.ts) + +--- + +## 0. 文档导读 + +本分七大部分: +- **第一部分**:项目定位与设计哲学(做层不做壳、收窄 RDK/ROS2、五条骨架嫁接) +- **第二部分**:与 pi 的对比(pi 是底座,本节厘清继承什么、二开什么、绕开什么) +- **第三部分**:与 deepseek-harness 的区别(dsh 是参照天花板,本节厘清取什么、不取什么) +- **第四部分**:顶层架构设计(五条骨架 + 嵌入式能力栈 + 数据流拓扑) +- **第五部分**:核心子系统设计(逐子系统接口契约 + 实现锚点) +- **第六部分**:开发任务分解(从架构拆到 T01-TN 可执行可验证任务,带验收标准) +- **第七部分**:开发任务进度表(维护中) + +--- + +# 第一部分:项目定位与设计哲学 + +## 1.1 一句话定位 + +Physical Byte Agent(pba)是一个**基于 pi 二开的、收窄到 RDK/ROS2 嵌入式硬件闭环的 C 层编程 Agent**——它不是写码助手(那是 pi / opencode 的赛道),不是机器人大脑(那是世界模型的赛道),而是**让 LLM agent 能在嵌入式开发场景里安全地"改码→交叉编译→烧板→上板验证→查日志"跑通硬件闭环**的中间层 agent。 + +## 1.2 三条设计哲学 + +### 哲学一:做层不做壳 + +pba 是"层"——夹在 pi(agent harness 底座)与嵌入式硬件(RDK X5/S100/S600 + ROS2)之间的能力层。不重新造 harness(pi 已造),不做完整 IDE(那是上游),不做机器人控制栈(那是下游)。pba 的价值在"把嵌入式硬件能力 + 嵌入式安全约束,封装成 pi 可加载的扩展与工具"。 + +### 哲学二:收窄 RDK/ROS2 + +不追求通用嵌入式(不碰 STM32 裸机、不碰 Arduino、不碰 FPGA)。收窄到 D-Robotics RDK X5/S100/S600(aarch64 Linux + BPU + ROS2)一条线。收窄的回报:能力栈可深度(devmem/i2cset/openocd/gdb MI/设备树 overlay 全为这块板打磨),安全约束可硬(砖板物理不可逆 → fail-closed 安全门)。 + +### 哲学三:五条骨架嫁接,底座不换 Cordis + +dsh 证明了工业级 agent harness 该有的八条骨架。pba **不引入 Cordis 全栈**(那是通用 harness 的复杂度投入),而是把其中五条骨架——**单一提交点 session log / 五段工具流水线 / OS 级沙箱 / scope 多 agent 隔离 / 能力接缝三角色**——用 pi 的扩展机制(`registerTool`/`on`/`appendEntry`/`events`/`defineTool`/`createAgentSession`)实现,嫁接到 pba 已有的 21 域嵌入式能力栈上。其余三条(compaction 完整工程 / 子代理 + 工作流 / 质量门)按需引入。 + +## 1.3 v3 的目标 + +把 v2(逻辑层 95%、运行时 0%)推进到 v3(逻辑层 95% + 运行时验证 + 安全骨架补齐): +- **能真跑**:联网 build pi + 真 key 端到端冒烟通过(G1) +- **能安全跑**:OS 级安全门 + 五段工具流水线 + 正则与 hex 归一联动堵 devmem 漏洞(G4/G5) +- **能长跑**:session 事件溯源 + compaction + typed events/scope(G2/G3/G8) +- **能多板**:能力接缝三角色,换板不动 tool(G6) +- **能可维护**:CI 覆盖门 + snapshot + doc-sync(G12) + +--- + +# 第二部分:与 pi 的对比 + +pi(`@earendil-works/pi`,v0.84.1)是 pba 的底座——一个 10 包 monorepo 的轻量 agent harness。pba 不是另起炉灶,是在 pi 扩展系统上二开。下表厘清 pba 对 pi 的**继承 / 二开 / 绕开**。 + +## 2.1 继承 pi(不动,直接用) + +| pi 能力 | pi 锚点 | pba 怎么用 | +|---|---|---| +| 扩展加载 `createAgentSession` | `packages/coding-agent/src/core/sdk.ts:171` | `PhysicalByteAgent.launch()`(`src/agent.ts:71`)动态 import | +| 扩展自动发现 | `packages/coding-agent/src/core/extensions/loader.ts:710` | `.pi/extensions/index.ts` 重导出 barrel | +| `registerTool` | `types.ts:1251` | 21 域扩展注册工具 | +| `defineTool` + `Type` (TypeBox) | `packages/coding-agent` | 工厂内动态 import,schema 定义 | +| `on("tool_call"/"tool_result"/"session_start"/"before_agent_start"/"message_end")` | `types.ts:901/1071-1080/1102-1106/1117-1120` | safety-gate/glm-provider 等挂钩子 | +| `registerProvider` | pi provider API | glm-provider 注册 glm-5.2 | +| `appendEntry` 持久化 | `types.ts:1318` | hardware-state/loop-orchestrator 审计 | +| `pi.events` EventBus | pi `EventBus` | 跨扩展通信(v3 升级为 typed event bus) | +| `setActiveTools` | pi | safety-gate per-skill 收敛 | +| `session_before_compact` 钩子 | `types.ts:1117-1120` | hardware-state compaction 保护 | +| `executionMode:"sequential"` | `agent-loop.ts:419-423` | flash 独占锁、单板串行 | +| pi-ai LLM 抽象 + 模型目录 | `@earendil-works/pi-ai` | glm-provider 复用 qwen thinkingFormat 分支 | + +## 2.2 二开 pi(治命门 + 补骨架) + +| pi 不足 | pba 二开 | 锚点 | +|---|---|---| +| glm-5.2 thinking 黑洞零输出(命门一) | `buildGlmModelConfig`:`thinkingFormat:"qwen"` + `maxTokens:8192` + `thinkingLevelMap` 全 null → 触发 pi `openai-completions.ts:762-763` 的 `enable_thinking:false` | `src/extensions/glm-provider.ts:81-102` | +| glm-5.2 hex 强转砖板(命门二) | `normalizeHexArg`(BigInt 保 64 位)+ `normalizeToolArguments`(递归 walk + denylist)+ `makeHexNormalizingPrepareArguments`(在 `prepareArguments` 拦截点归一,因 `BeforeToolCallResult` 不支持替换 args 只能 block) | `glm-provider.ts:166-262` | +| pi 无 OS 级沙箱 | v3 新增 `ctx.sandbox` 接缝(board-side landlock/seccomp) | 待建(见 T05) | +| pi 工具执行是单点 block | v3 升级为五段流水线(pre-execute/guard/around/post/finalize) | 待建(见 T04) | +| pi events 松散字符串 | v3 加 typed event bus(declaration merging + waterfall + scope) | 待建(见 T07) | +| pi 无全量 session 事件溯源 | v3 加 `SessionEventMap` + `deriveMessages`(最小子集) | 待建(见 T06) | +| pi 无能力接缝三角色 | v3 把 board-link/flash 抽 `ctx.boardLink`/`ctx.flash` 接缝 | 待建(见 T08) | + +## 2.3 绕开 pi(不改 pi 源码,扩展层兜底) + +| pi 内部够不着的 | pba 绕法 | 说明 | +|---|---|---| +| `partitionToolCalls`(agent-loop 内部) | 扩展层 prompt 注入兜底 + events 握手 | pi 扩展 API 够不着 agent-loop 内部,只做兜底,注释明说局限 | +| agent-loop 并发分类(exclusive/parallel) | flash 工具自带独占锁 + `executionMode:"sequential"` | 不依赖 pi 内部分类 | +| 真 pi 运行时构建(需联网 generate-models) | 离线用 `verifyAssembly()` 自检;联网后 build | 不 hack pi 构建流程 | + +## 2.4 与 pi 关系的本质 + +pba 是 pi 的**能力层扩展包**,不是 pi 的 fork。pba 通过 `package.json` 的 `"pi": {"extensions": ["src/extensions/index.ts"]}` 声明,pi 经 `readPiManifest`(`loader.ts:605-620`)解析后自动加载 pba 的 barrel。pba 的代码全在 `src/extensions/`,pi 源码不动(除 vendored patch 如有)。 + +--- + +# 第三部分:与 deepseek-harness 的区别 + +dsh(0.1.0-rc.5)是 pba 的**参照天花板**——它证明了工业级 agent harness 该有的骨架。但 pba **不照搬 dsh 全栈**。本节厘清取什么、不取什么、为什么。 + +## 3.1 取 dsh 的八条骨架(嫁接到 pi 扩展) + +| dsh 骨架 | dsh 锚点 | pba 怎么嫁接 | pba 任务 | +|---|---|---|---| +| ① append-only session log + "model-visible⟺logged" | `Session.append`(`packages/core/session/src/index.ts:604`)+ `deriveMessages`(`:726`)+ `SessionEventMap`(`types.ts:236`) | 定义 pba `SessionEventMap`(turn/step/tool-call/tool-result/hw:state/flash/verify),append 唯一提交点,`deriveMessages` 从 surface 投影,加 "model-visible⟺logged" 断言。先最小子集。 | T06 | +| ② OS 级进程沙箱 | `native/landlock-run`(C11)+ `sandbox-local`(bwrap/Seatbelt/ACL)+ `sandbox-policy` 单 home | board-side landlock/seccomp(aarch64 Linux 5.13+);host-side safety-gate 正则升级;devmem 强制走专用 reg 工具 | T05 | +| ③ 五段工具流水线 + 单调 guard + finalizeContent | `tools/index.ts:1342` + `ToolRuntimeScheduler`(`:451`)+ `guard`(`:1110`)+ `finalizeContent`(`:247`) | safety-gate `evaluateSafety` 升级为 pre-execute waterfall + monotonic guard(破坏性/资源锁/阻值门/datasheet 地址各一 guard,任一 deny 不可覆盖);flash 加 finalizeContent | T04 | +| ④ 类型化事件四分派 + waterfall + scope 链 | 四分派表(`docs/cordis-primer.md`)+ `scope`(`packages/core/scope/src/index.ts:137/170`)+ `agentEvents`(`packages/core/agent/src/dispatch.ts:107`) | 薄封装 `pi.events` 加 typed event bus(declaration merging + waterfall `next()` + scope key 多 agent 隔离) | T07 | +| ⑤ 能力接缝三角色 | `docs/capability-seams.md` 大表 | board-link 抽 `ctx.boardLink`(BoardLinkProvider 接口 + 各板 provider + tool consumer);flash 四方法抽 provider | T08 | +| ⑥ compaction 完整工程 | `compaction-basic`(KV cache 复用 + tool-result prune)+ `spillStore`/`spill-policy` | 加 tokenMeter 压力触发 + tool-result prune(i2cdump/gdb 大输出)+ spill 句柄(datasheet 大检索结果) | T10 | +| ⑦ 子代理 + 工作流引擎 | `ctx.subagents`(6 provider)+ `ctx.workflowEngine`(parallel/pipeline/phase + node:vm) | 评估 pi subagent 或自建轻量 `ctx.subagents`;loop-orchestrator 上层加 workflow 编排 | T11 | +| ⑧ 质量门 + postmortem | `test:coverage` per-file 100% + `test:snapshot` + `doc-sync` + `docs/postmortem/` | CI per-file 覆盖门 + 真实 API snapshot 回放 + doc-sync + postmortem 文化 | T13 | + +## 3.2 不取 dsh 的(过度工程,pba 收窄不需要) + +| dsh 东西 | 为什么 pba 不取 | +|---|---| +| Cordis 全栈框架(vendor/cordis) | pba 底座是 pi 扩展,已验证可装配 21 域。五条骨架用 pi 扩展实现,不引 Cordis 依赖 | +| Typert 类型图生成器 + api-gateway RPC(`ctx.typert`/`ctx.typertGateway`) | 为 web 客户端 + 远程 RPC 设计的重型类型基础设施。pba 不做 web 客户端 | +| 全 60 个 ctx 接缝(web-search/acp/e2b/otel/directory-picker...) | dsh 为通用 agent 设计。pba 只需嵌入式相关子集(boardLink/fs/subprocess/compaction/sandbox/subagents/skills/storage) | +| single-exe Python 分发(`python/sdk-runtime`) | pba 是 TS agent,不做 Python 分发 | +| windows-acl 沙箱(`packages/sandbox/sandbox-windows-acl`) | 嵌入式板是 aarch64 Linux,不需要 Windows ACL | +| 8 种 thinking dispatch 格式表(`THINKING_FORMAT_GATE`) | pba 只 glm-5.2,qwen 一种够用 | +| web-app bundle(`dsh-web-app`) | pba 不做浏览器应用,走 headless/CLI/JSON-RPC | +| headless bundle 的完整 snapshot 基建 | pba 按需取 snapshot 思路,不搬 dsh 的 ACP snapshot 全套 | + +## 3.3 pba 有而 dsh 没有的(嵌入式领域护城河,不丢) + +| pba 能力 | dsh 状态 | pba 锚点 | +|---|---|---| +| 三段式安全烧录(dd/fastboot/dfu/openocd) | dsh 无(dsh 有 `tool-bash` 但无烧录 gate) | `src/extensions/flash.ts` | +| JTAG/gdb MI 调试 | dsh 无 | `src/extensions/jtag-debugger.ts` | +| 外设探测(i2c/gpio/spi) | dsh 无 | `src/extensions/peripheral-probe.ts` | +| 设备树解析/校验 | dsh 无 | `src/extensions/device-tree.ts` | +| aarch64 交叉编译工具链 | dsh 无 | `src/extensions/cross-compile.ts` | +| 硬件信号验证判据(dmesg/gpio/i2c/sysfs/serial/current) | dsh 无 | `src/extensions/hardware-verify.ts` | +| 硬件状态持久化 + compaction 保护 | dsh 有通用 compaction 但不特化硬件状态 | `src/extensions/hardware-state.ts` | +| 闭环 checkpoint 状态机(edit→compile→flash→verify→check→done) | dsh 有通用 workflow 但无物理不可逆 fail-closed | `src/extensions/loop-orchestrator.ts` | +| glm-5.2 专属命门根治(thinking 黑洞 + hex 强转砖板) | dsh 不遇(DeepSeek 原生 adapter 不开 thinking 黑洞,不写 devmem) | `src/extensions/glm-provider.ts` | +| 离线可测架构(顶层 import type + factory 内动态 import) | dsh 需 build:lib:host 先 | 全 extensions 一致 | +| 单板串行 concurrency=1 物理约束建模 | dsh 是通用 `maxParallelToolCalls` | flash `executionMode:"sequential"` | + +## 3.4 与 dsh 关系的本质 + +dsh 是**通用 agent harness 的工业天花板参照**;pba 是**嵌入式硬件闭环 agent 的能力栈**。pba 取 dsh 的五条工业骨架(+ 三条按需)嫁接到 pi 扩展底座,叠加 pba 自有的嵌入式能力栈与 glm-5.2 命门根治,形成"工业骨架 + 领域能力 + 专属安全"三位一体。**不照搬、不 fork dsh,只学其骨架范式**。 + +--- + +# 第四部分:顶层架构设计 + +## 4.1 架构总览(分层图) + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 用户/CI 入口层 │ +│ bin/pba.ts (CLI) │ PhysicalByteAgent.launch() (程序化) │ CI │ +└─────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────┐ +│ pba 装配层(barrel) src/extensions/index.ts │ +│ physicalByteAgentAssembly(pi) → 依次装配所有域扩展工厂(fail-soft) │ +└─────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────┐ +│ pba 工业骨架层(v3 嫁接 dsh 五条 + 按需三条) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │Session log│ │Typed │ │工具流水线 │ │OS 沙箱 │ │能力接缝 │ │ +│ │append-only│ │Events │ │pre/guard/│ │landlock/ │ │三角色 │ │ +│ │+derive │ │+waterfall│ │around/ │ │seccomp + │ │Definition/│ │ +│ │+logged │ │+scope │ │post/ │ │fail-closed│Provider/ │ │ +│ │不变量 │ │隔离 │ │finalize │ │probe │ │Consumer │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │compaction│ │子代理+ │ │质量门 │ (按需引入) │ +│ │KV cache+ │ │workflow │ │CI 100%+ │ │ +│ │prune+spill│ │parallel/│ │snapshot+ │ │ +│ │ │ │pipeline │ │doc-sync │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +└─────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────┐ +│ pba 嵌入式能力栈层(v2 已有 21 域,v3 保留 + 接骨架) │ +│ glm-provider │ safety-gate │ persistent-shell │ pdf-reader │ +│ edit-strict │ length-recovery │ subprocess-isolation │ env-probe │ +│ mcp-bridge │ server-runtime │ hardware-state │ cross-compile │ +│ flash │ peripheral-probe │ jtag-debugger │ device-tree │ board-link │ +│ datasheet-rag │ hardware-verify │ loop-orchestrator │ build-tracker │ +└─────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────┐ +│ pi 底座层(继承,不动) │ +│ createAgentSession │ registerTool/defineTool/Type │ on(钩子) │ +│ registerProvider │ appendEntry │ pi.events │ setActiveTools │ +│ session_before_compact │ executionMode:sequential │ pi-ai LLM 抽象 │ +└─────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────┐ +│ 硬件/OS 层 │ +│ RDK X5/S100/S600(aarch64 Linux + BPU + ROS2)│ SSH/串口 │ devmem/i2c │ +│ /sys/class/gpio │ device-tree overlay │ openocd/gdb │ cross-gcc │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +## 4.2 五条骨架与 pi 的映射(嫁接点) + +| 骨架 | dsh 实现 | pba 嫁接到 pi 的方式 | pi 锚点 | +|---|---|---|---| +| Session log | `Session.append` + `deriveMessages` | pba `Session` 类包装 pi `appendEntry`,定义 `PbaSessionEventMap`,`deriveMessages` 从 pba 事件投影;"model-visible⟺logged" 用 `before_agent_start` + `message_end` 钩子断言 | `appendEntry`(`types.ts:1318`)+ `session_before_compact`(`:1117`) | +| Typed events + scope | Cordis `ctx.waterfall`/`scope` | 薄封装 `pi.events`:`PbaEventBus.emit/waterfall/serial` + `ScopeKey` 标签过滤(agent 隔离) | `pi.events`(`EventBus`) | +| 工具流水线 | `ToolRuntimeScheduler` 五段 | `pi.on("tool_call")` pre-execute waterfall + monotonic guards + `pi.on("tool_result")` post + 工具 `finalizeContent` | `on("tool_call"/"tool_result")`(`:901/1071`) | +| OS 沙箱 | `sandbox-local` + `landlock-run` | host-side:safety-gate 正则升级 + 与 hex 归一联动;board-side:landlock/seccomp 围栏(aarch64 Linux 5.13+) | `on("tool_call")` block + 工具内 spawn 包 argv | +| 能力接缝 | Definition/Provider/Consumer | board-link/flash 抽 `BoardLinkProvider`/`FlashProvider` 接口 + 各板/方法 provider + tool consumer | `registerTool` 消费 | + +## 4.3 数据流:一次硬件闭环 turn + +``` +用户 followup("烧新的 bootloader 到 X5") + → pba Session.append(turn/start) [骨架①] + → agent/pre-step waterfall(inject 寄存器表/runtime-context)[骨架④] + → systemPrompt.assemble(21 域工具 schema + 安全门 section)[pi] + → ctx.llm.stream(glm-5.2,命门一已关 thinking) [pi-ai qwen] + → assistant/chunk* → Session.append(assistant/message) [骨架①] + → 工具流水线(flash 工具) [骨架③] + → pre-execute waterfall: safety-gate 阻值门 guard + 资源锁 guard [骨架③] + → monotonic guards: 任一 deny 不可覆盖 [骨架③] + → tools/execute around: timeout/retry + 独占锁 [骨架③] + → tool body: planFlash → dryRun(根盘拒绝+sha256)→ verifyFlash + → board-side landlock 围栏包 argv [骨架②] + → ctx.boardLink provider(SSH 到 X5) [骨架⑤] + → post-execute: accept/block/replace/add context [骨架③] + → finalizeContent: verify 结果强制 content-only [骨架③] + → tools/result → Session.append(tool/result) [骨架①] + → compaction 如压力触发: prune + summarize + KV cache 复用 [骨架⑥] + → agent/turn-stopping serial [骨架④] + → Session.append(turn/end) [骨架①] +``` + +## 4.4 运行时拓扑(单板串行 + 板外并行) + +``` +宿主机(macOS/Linux) 目标板(RDK X5,aarch64 Linux) +┌────────────────────────┐ ┌────────────────────────┐ +│ pba agent (pi 进程) │ SSH/串口 │ 板侧 landlock runner │ +│ ├ glm-provider (网关) │ ───────────────→│ ├ boardlink:exec │ +│ ├ safety-gate (host 正则)│ │ ├ /sys/class/gpio │ +│ ├ flash 工具 (三段式) │ devmem/i2c │ ├ devmem/i2cset │ +│ ├ cross-compile (aarch64)│ ───────────────→│ ├ openocd/gdb │ +│ ├ loop-orchestrator │ │ └ landlock 围栏(fail- │ +│ └ Session log (JSONL) │ │ closed probe) │ +└────────────────────────┘ └────────────────────────┘ + 单板串行 concurrency=1(物理约束):flash/verify/devmem 独占锁 + 板外可并行:编译(宿主)+ 探板(板)+ datasheet RAG(宿主)—— v3 子代理/工作流 +``` + +--- + +# 第五部分:核心子系统设计 + +## 5.1 子系统 A:Session 事件溯源(骨架①) + +### 现状 +- pi 有 `appendEntry`(松散 CustomEntry)+ sqlite/jsonl 存储。 +- pba 的 `hardware-state`(`src/extensions/hardware-state.ts`)已有 `replayFromEntries`(`:134`)重建 `{locks, checkpoint, flashLog}`,但只覆盖硬件状态子集。 + +### v3 设计 +定义 pba 自己的 `PbaSessionEventMap`(merge-extensible),`PbaSession` 类包装 pi `appendEntry`: + +```ts +// src/core/pba-session.ts(新建) +export interface PbaSessionEventMap { + "turn/start": { turn: number }; + "turn/end": { turn: number; reason: TurnEndReason }; + "step/start": { turn: number; step: number }; + "step/end": { turn: number; step: number }; + "user/message": UserMessage; + "assistant/message": AssistantMessage; // surface, 带 sourceEventSeqs + "tool/call": { turn: number; step: number; name: string; args: unknown }; + "tool/result": { turn: number; step: number; name: string; result: unknown }; + "hw:state": HwEntry; // 复用 hardware-state + "flash/log": FlashLogEntry; + "verify/record": VerifyRecord; + "checkpoint/change": CheckpointState; +} +``` + +- `PbaSession.append(type, data)`:唯一提交点,lossless-JSON 快照 + 深冻结 + `seq` 连续性不变量。 +- `PbaSession.deriveMessages()`:从有序 surface(user/message + assistant/message + tool/result)投影模型历史,增量缓存。 +- "model-visible⟺logged" 断言:在 `before_agent_start` 钩子校验即将喂模型的消息全可从 log 重建。 +- `replayFromEntries` 推广到全量事件。 + +### 验收 +- `PbaSession.append` 唯一提交点,重入 guard。 +- `deriveMessages` 从 log 投影,compaction replace 重建。 +- "model-visible⟺logged" 断言在伪造"喂模型未 log 的消息"时抛错。 + +## 5.2 子系统 B:Typed Event Bus + Scope 隔离(骨架④) + +### 现状 +- pba 全用 `pi.events.emit/on`(松散字符串,无 waterfall/serial/scope/类型)。实例如 `loop-orchestrator.ts:503/508`、`board-link.ts:682-712`、`glm-provider.ts:406`。 + +### v3 设计 +薄封装 `pi.events`,加 `PbaEventBus`: + +```ts +// src/core/pba-event-bus.ts(新建) +export class PbaEventBus { + constructor(private pi: ExtensionAPI) {} + emit(event: K, payload: PbaEventMap[K], scope?: ScopeKey): void; + waterfall(event: K, payload, next): Promise; // around 中间件,调 next() 委托 + serial(event: K, payload): Promise; + on(event: K, listener, opts?: { scope?: ScopeKey; prepend?: boolean }): () => void; +} +export type ScopeKey = object; // identity-compared,agent 隔离 +``` + +- `waterfall`:listener 收 `(...args, next)`,调 `next()` 委托,不调即短路(dsh 范式)。 +- `scope`:`ScopeKey` 标签,无标签全局 + 匹配键/祖先键(注册向下继承、事件向上扩展)。 +- 迁移:现有 `pi.events.on("verify:passed", ...)` 等改 typed 版本;safety-gate `pi.on("tool_call")` 升级为 pre-execute waterfall。 + +### 验收 +- `waterfall` 链:A listener 包装结果传 B,B 收到 A 的包装。 +- scope:agent A 的事件不进 agent B 的 scoped listener。 +- 现有 21 域的 `pi.events` 调用全迁 typed 版本,tsc 编译期检查签名。 + +## 5.3 子系统 C:五段工具流水线(骨架③) + +### 现状 +- safety-gate(`src/extensions/safety-gate.ts:206`)`pi.on("tool_call")` 只在 pre-execute 段做正则拦截 + 资源锁;`pi.on("tool_result")` 释放锁。 +- flash 工具内联独占锁 + 三段式,但无通用 around/post/finalize 容器。 + +### v3 设计 +五段流水线(嫁接 dsh `ToolRuntimeScheduler`): + +``` +tools/pre-execute waterfall (allow|deny|ask) + ├ safety-gate: 破坏性命令 guard + ├ safety-gate: 资源锁 guard + ├ safety-gate: 上电前置阻值门 guard(v3 新增) + ├ datasheet 地址校验 guard(devmem 专用 reg 工具,v3 新增) + └ monotonic: 任一 deny 不可被另一 force-allow +→ ctx.approval(一次性,fail-closed,缺失 deny) +→ tools/execute around-waterfall + ├ timeout(通用容器) + ├ retry + ├ metrics + └ tool execute() body(flash 三段式 / devmem / openocd / ...) +→ tools/post-execute waterfall (accept|block|replace|add context) +→ finalizeContent(content-only 不变量) +→ tools/result(冻结、lossless-JSON、权威) +``` + +- pre-execute 改 `PbaEventBus.waterfall("tools/pre-execute", ...)`。 +- monotonic guards:注册式,`guardReason` 全局→scope 链最远优先,身份保护。 +- finalizeContent:工具定义可选,materialize 前同步校验 content-only。 +- **正则与 hex 归一联动**(堵 G5 漏洞):safety-gate 的 `evaluateSafety` 在过正则前先调 `normalizeHexArg` 归一命令里的地址,使 `devmem 1073872896 write` 归一成 `devmem 0x40020000 write` 再匹配 `devmem-write` 正则。 + +### 验收 +- 五段都能挂 listener,waterfall `next()` 委托生效。 +- 任一 guard deny,另一 guard 不能 force-allow(单调性测试)。 +- `devmem 1073872896 write`(十进制)经归一后被 `devmem-write` 正则命中并 block(堵漏洞测试)。 +- flash 工具的 verify 结果经 finalizeContent 强制 content-only。 + +## 5.4 子系统 D:OS 级沙箱(骨架②) + +### 现状 +- 零 OS 级沙箱。safety-gate 8 条正则在命令字符串层(`safety-gate.ts:35-110`)。 +- 具体漏洞:`devmem-write` 正则 `devmem2?\s+0x[0-9a-fA-F]+\s+\b(w|write)\b` 要求字面 0x,glm-5.2 命门二强转十进制后 `devmem 1073872896 write` 不匹配。 + +### v3 设计 +分两侧: + +**Host-side(宿主,pba agent 跑的地方)**: +- safety-gate 正则升级 + hex 归一联动(子系统 C 已述)。 +- 破坏性工具强制走专用工具(flash 已如此;devmem 建专用 `reg` 工具带 datasheet 地址校验,禁走 bash)。 +- 宿主侧可选 landlock(macOS/Linux 开发机)。 + +**Board-side(目标板,aarch64 Linux)**: +- `boardlink:exec` 在板侧包 argv:landlock(内核 5.13+,`grantArgs({readOnly:['/'], readWrite:[workspace]})`)或 seccomp 围栏。 +- fail-closed probe:板侧 runner 不可用时不跑命令直接报 `unusable`。 +- 单 `boardSandboxPolicy` home:board-link 与 flash 共享一个围栏策略,防围不同 root。 + +### 验收 +- board-side landlock runner probe 返回 `full`/`partial`/`unusable`,`unusable` 时命令不跑。 +- `devmem 1073872896 write`(十进制)在 host-side 被归一 + 正则 block。 +- devmem 强制走 `reg` 工具,走 bash 被 safety-gate block。 + +## 5.5 子系统 E:能力接缝三角色(骨架⑤) + +### 现状 +- board-link(`src/extensions/board-link.ts`,714 行)ssh/serial/local 三实现内联一个文件。 +- flash(`src/extensions/flash.ts`)dd/fastboot/dfu/openocd 四方法内联。 + +### v3 设计 +抽接缝(嫁接 dsh `ctx.boardLink` 范式): + +```ts +// src/capabilities/board-link/types.ts(新建) +export interface BoardLinkProvider { + readonly name: string; // "rdk-x5" | "rdk-s100" | "rdk-s600" | ... + readonly linkType: BoardLinkType; + exec(command: string, opts: ExecOpts): Promise; + healthCheck(): Promise; +} +// src/capabilities/board-link/index.ts +export class BoardLinkRegistry { + register(provider: BoardLinkProvider): () => void; // effect 可逆 + get(boardId: string): BoardLinkProvider | undefined; +} +// src/capabilities/board-link/providers/rdk-x5-ssh.ts +export class RdkX5SshProvider implements BoardLinkProvider { ... } +// src/capabilities/board-link/tool-board-link.ts(consumer) +// flash 同理:FlashProvider(dd/fastboot/dfu/openocd)+ 各方法 provider + tool consumer +``` + +- BoardSpec(`shared/types.ts:98`)做 provider 配置(板 id → provider 名 + 连接参数)。 +- 换板(X5→S100)= 加一个 provider + 改 BoardSpec 配置,不动 tool 代码。 + +### 验收 +- 加 RdkS100Provider 后,tool-board-link 无代码改动即可用 S100。 +- `BoardLinkRegistry.register` 返回 disposer,unload 后 tool 不见该板。 + +## 5.6 子系统 F:compaction 完整工程(骨架⑥) + +### 现状 +- length-recovery(`src/extensions/length-recovery.ts`)治 glm stop=length 零输出。 +- hardware-state `selectProtected`/`buildCompactionProtection`(`:227/312`)保 hw entry。 + +### v3 设计 +加 compaction provider(嫁接 dsh `compaction-basic` + `spillStore`): +- **压力触发**:`tokenMeter` 等价,量 context 用量,超阈值触发。 +- **tool-result prune**:i2cdump/gdb/dmesg 大输出先 model-free 压缩成摘要(保留寄存器地址 + 关键值)。 +- **summarize**:重放前缀 + append 压缩指令,**复用 pi-ai provider KV prefix cache**(降本)。 +- **surface replace**:`user/message` 带 `surfaceOp:{op:'replace',start,end}` 覆盖被遮蔽节点(接子系统 A 的 PbaSession)。 +- **spill 句柄**:超大 datasheet RAG 结果替成 `SpillLocator` branded 句柄 + 检索提示,模型按需取回。 + +### 验收 +- 压力触发后 summarize,KV cache 复用(provider 请求带前缀)。 +- i2cdump 大输出 prune 成摘要,寄存器地址不丢。 +- datasheet 大结果 spill 成句柄,模型可按句柄取回。 + +## 5.7 子系统 G:子代理 + 工作流(骨架⑦,按需) + +### 现状 +- 无子代理。loop-orchestrator `CheckpointMachine`(`:153`)线性状态机。 + +### v3 设计 +- 评估 pi 自带 subagent 机制;若不足,自建轻量 `ctx.subagents`(spawn-in-process provider 足够,fresh child 不继承上下文)。 +- loop-orchestrator 保留作单板闭环串行 gate(物理约束正确抽象);上层加 workflow 编排: + - parallel:编译(宿主)+ 探板(板)+ datasheet RAG(宿主)并行。 + - pipeline:edit→compile→flash→verify。 +- 工作流脚本能 fan out 子 agent,带上限(maxConcurrent/maxItems)。 + +### 验收 +- parallel 三任务并发,板外并行窗口利用。 +- pipeline edit→compile→flash→verify 串行,stage 抛错 item 落 null。 +- 子 agent 的 `agent/pre-step` 不进主 agent 的 scoped listener(子系统 B 验证)。 + +## 5.8 子系统 H:嵌入式能力栈保留 + 接骨架(v2 已有) + +21 域扩展(v2)保留,按需接骨架: +- safety-gate → 子系统 C(pre-execute waterfall + guards)+ 子系统 D(正则与 hex 联动)。 +- flash → 子系统 C(finalizeContent)+ 子系统 E(FlashProvider 接缝)+ 子系统 D(board-side 沙箱)。 +- hardware-state → 子系统 A(PbaSession 事件)+ 子系统 F(compaction 保护)。 +- loop-orchestrator → 子系统 A(checkpoint 写 log)+ 子系统 G(上层 workflow)。 +- glm-provider → 不变(命门根治已扎实,走 pi-ai qwen 分支,dsh 已生产验证)。 +- 其余 16 域 → 按需把 `pi.events` 迁 typed 版本(子系统 B)。 + +## 5.9 子系统 I:质量门 + postmortem(骨架⑧) + +### 现状 +- 732 单测(逻辑层),tsc 0 错(对类型镜像),装配冒烟 21 工厂。无 CI 覆盖门/snapshot/doc-sync/postmortem。 + +### v3 设计 +- **CI per-file 覆盖门**:`test:coverage` 对 `src/**/*.ts` per-file 100%(v8/istanbul)。 +- **真实 API snapshot**:联网 key 跑最小闭环,输出 snapshot,后续回归对比。 +- **doc-sync 文档门**:CI 校验 README/AGENTS/架构文档与代码同步(锚点 file:line 对齐)。 +- **类型漂移检测**:CI 定期对真 pi 源码 tsc(`tsconfig.realpi.json` 临时 paths 指真 pi),检测 `src/types/pi.d.ts` 镜像漂移。 +- **postmortem**:`docs/postmortem/` 编号事后复盘(砖板事故/零输出事故/装配挂事故)。 + +### 验收 +- CI `test:coverage` per-file 100% 门。 +- snapshot 回放对比,输出漂移即 CI 红。 +- doc-sync 校验架构文档锚点与代码一致。 +- 类型镜像漂移检测在 pi 升版后报红。 + +## 5.10 目录与包结构设计(v3 增量) + +``` +physical_byte_agent/ +├── src/ +│ ├── core/ [v3 新增] 工业骨架层 +│ │ ├── pba-session.ts # PbaSession + PbaSessionEventMap(骨架①) +│ │ ├── pba-event-bus.ts # PbaEventBus + ScopeKey(骨架④) +│ │ ├── tool-pipeline.ts # 五段流水线调度器(骨架③) +│ │ ├── sandbox-policy.ts # 单 sandboxPolicy home(骨架②) +│ │ └── invariants.ts # "model-visible⟺logged" 等断言 +│ ├── capabilities/ [v3 新增] 能力接缝三角色 +│ │ ├── board-link/ +│ │ │ ├── types.ts # BoardLinkProvider 接口(Definition) +│ │ │ ├── index.ts # BoardLinkRegistry(接缝) +│ │ │ ├── providers/ +│ │ │ │ ├── rdk-x5-ssh.ts +│ │ │ │ ├── rdk-s100-serial.ts +│ │ │ │ └── local.ts +│ │ │ └── tool-board-link.ts # Consumer +│ │ └── flash/ +│ │ ├── types.ts # FlashProvider 接口 +│ │ ├── providers/{dd,fastboot,dfu,openocd}.ts +│ │ └── tool-flash.ts +│ ├── compaction/ [v3 新增] compaction + spill(骨架⑥) +│ │ ├── token-meter.ts +│ │ ├── tool-result-pruner.ts +│ │ ├── summarizer.ts +│ │ └── spill.ts +│ ├── extensions/ [v2 已有,v3 接骨架] 21 域 +│ │ ├── index.ts # barrel +│ │ ├── glm-provider.ts +│ │ ├── safety-gate.ts # → 接 tool-pipeline + sandbox +│ │ ├── flash.ts # → 迁到 capabilities/flash/ +│ │ ├── board-link.ts # → 迁到 capabilities/board-link/ +│ │ └── ... (其余 17 域) +│ ├── shared/types.ts [v2 已有,v3 扩展] +│ ├── agent.ts +│ └── index.ts +├── tests/ [v2 已有 + v3 增量] +├── bin/pba.ts +├── models.json +├── .github/workflows/ [v3 新增] CI 门 +├── docs/postmortem/ [v3 新增] 事后复盘 +├── tsconfig.json +└── vitest.config.ts +``` + +--- + +# 第六部分:开发任务分解 + +> 原则:每个任务**可执行(有明确代码改动点)+ 可验证(有验收标准 + 测试)**。按优先级 P0→P1→P2 排序,前置依赖标注。锚点均为真实 file:line。 + +## 6.1 P0 任务(致命,不补会砖板/零输出/无法安全跑闭环) + +### T01 真端到端 pi 运行时冒烟【P0,无前置,G1】 +- **执行**: + 1. `cd /Users/d-robotics/Desktop/pi && npm run build`(需联网 generate-models)。 + 2. `cd /Users/d-robotics/Desktop/physical_byte_agent && DROBOTICS_LLM_KEY= npx tsx bin/pba.ts`。 + 3. 断言:①pi 加载 barrel(无 assembly-error)②glm-5.2 provider 注册(`glm_status` 工具可查)③21 工具注册(`pi.getActiveTools()` 含 flash/verify/pshell 等)④tool_call 钩子挂上(safety-gate 拦截测试命令)⑤最小闭环:edit→compile→flash(dry_run)→verify 不抛。 +- **验收**:冒烟脚本 `scripts/e2e-smoke.ts` 通过,输出落 `docs/postmortem/0001-e2e-smoke.md`(首次冒烟记录)。 +- **若失败**:按失败点定位(provider 注册失败 / 钩子签名漂移 / 工具 schema 被 pi 拒),记 postmortem。 +- **状态**:未开始(受联网约束,待用户授权联网 build pi)。 + +### T02 safety-gate 正则与 hex 归一联动堵 devmem 漏洞【P0,前置 T06 部分可用,G5】 +- **执行**: + 1. `src/extensions/safety-gate.ts` 的 `evaluateSafety`(`:98`)在过正则前,先调 `normalizeHexArg`(`glm-provider.ts:166`)归一命令里的十进制地址。 + 2. 新增测试:`devmem 1073872896 write` → 归一为 `devmem 0x40020000 write` → 命中 `devmem-write` 正则(`:57`)→ block。 + 3. 新增测试:`devmem 0x40020000 write`(已 hex)→ 原样命中 → block。 + 4. 新增测试:`baudrate 115200` → 不被误归一(denylist,`normalizeHexArg` 已支持)→ 放行。 +- **验收**:3 条测试全绿,`devmem` 十进制绕过漏洞堵死。 +- **状态**:未开始。 + +### T03 devmem 专用 reg 工具 + datasheet 地址校验【P0,前置 T02,G5】 +- **执行**: + 1. 新建 `src/extensions/reg-tool.ts`(或迁 `capabilities/`):`reg read/write` 工具,参数 `{address, value?, datasheetRef?}`。 + 2. write 前校验 `address` 在 datasheet 已知寄存器表内(datasheet-rag 联动),未校验即 block。 + 3. safety-gate 新增规则:裸 `devmem` 走 bash → block,建议改用 `reg` 工具。 + 4. `reg` 工具走 `prepareArguments` hex 归一(`makeHexNormalizingPrepareArguments`)。 +- **验收**:`devmem ... w` 走 bash 被 block;`reg write` 带 datasheet 校验通过;未知地址 block。 +- **状态**:未开始。 + +### T04 五段工具流水线(pre-execute waterfall + monotonic guards + finalizeContent)【P0,前置 T07,G4】 +- **执行**: + 1. `src/core/tool-pipeline.ts`:实现 `ToolPipeline` 调度器(嫁接 dsh `ToolRuntimeScheduler`,`packages/core/tools/src/index.ts:451`)。 + 2. safety-gate `pi.on("tool_call")` 升级为 `pre-execute` waterfall(allow/deny/ask)。 + 3. 注册 monotonic guards:破坏性命令 / 资源锁 / 阻值门(T03)/ datasheet 地址(T03),任一 deny 不可覆盖。 + 4. `tools/execute` around:通用 timeout/retry 容器。 + 5. `tools/post-execute`:accept/block/replace/add context。 + 6. flash 工具加 `finalizeContent`(verify 结果 content-only 不变量)。 +- **验收**:五段挂 listener;任一 guard deny 不可 force-allow(单调测试);flash verify 经 finalizeContent。 +- **状态**:未开始。 + +### T05 board-side landlock/seccomp 沙箱【P0,前置 T08,G5】 +- **执行**: + 1. `src/core/sandbox-policy.ts`:单 `boardSandboxPolicy` home(嫁接 dsh `sandbox-policy`)。 + 2. board-link `boardlink:exec` 在板侧包 argv:landlock(内核 5.13+ `grantArgs`)或 seccomp。 + 3. fail-closed probe:板侧 runner 不可用报 `unusable`,命令不跑。 + 4. 板侧 runner 先用 shell 脚本模拟(真 landlock-run 需交叉编译 C,作 T05b)。 +- **验收**:probe 返回 full/partial/unusable;unusable 时命令不跑;board-link 与 flash 共享围栏策略。 +- **状态**:未开始(T05a 脚本模拟先行,T05b 真 landlock-run 后续)。 + +## 6.2 P1 任务(重要,不补长会话/多 agent/可维护性差) + +### T06 PbaSession 事件溯源 + deriveMessages【P1,前置无,G2】 +- **执行**: + 1. `src/core/pba-session.ts`:`PbaSession` 类包装 pi `appendEntry`,定义 `PbaSessionEventMap`(turn/step/user-message/assistant-message/tool-call/tool-result/hw:state/flash-log/verify-record/checkpoint-change)。 + 2. `append` 唯一提交点:lossless-JSON 快照 + 深冻结 + `seq` 连续性。 + 3. `deriveMessages`:从有序 surface 投影模型历史,增量缓存。 + 4. `replayFromEntries` 推广到全量事件(从 hardware-state `:134` 抽公共)。 + 5. "model-visible⟺logged" 断言:`before_agent_start` 钩子校验。 +- **验收**:append 重入 guard;deriveMessages 从 log 投影;compaction replace 重建;伪造"未 log 喂模型"断言抛错。 +- **状态**:未开始。 + +### T07 PbaEventBus + ScopeKey 隔离【P1,前置无,G3】 +- **执行**: + 1. `src/core/pba-event-bus.ts`:`PbaEventBus` 薄封装 `pi.events`,加 `emit/waterfall/serial/on` + `ScopeKey` 标签过滤。 + 2. `waterfall` 实现:listener 收 `(...args, next)`,调 `next()` 委托。 + 3. scope:无标签全局 + 匹配键/祖先键(注册向下继承、事件向上扩展)。 + 4. 迁移:21 域现有 `pi.events.on/emit` 改 typed 版本(`verify:passed`/`build:done`/`boardlink:*`/`glm:*`/`xcompile:*`/`pdf-reader:*`/`debugger:*`/`length-recovery:*`)。 +- **验收**:waterfall 链委托生效;scope agent 隔离;21 域迁移后 tsc 编译期检查签名。 +- **状态**:未开始。 + +### T08 能力接缝三角色(board-link + flash)【P1,前置无,G6】 +- **执行**: + 1. `src/capabilities/board-link/types.ts`:`BoardLinkProvider` 接口(Definition)。 + 2. `src/capabilities/board-link/index.ts`:`BoardLinkRegistry`(接缝,`register` 返回 disposer)。 + 3. `src/capabilities/board-link/providers/`:从 `board-link.ts` 抽 `rdk-x5-ssh`/`rdk-s100-serial`/`local` 三 provider。 + 4. `src/capabilities/board-link/tool-board-link.ts`:consumer(原 tool 逻辑)。 + 5. flash 同理:`FlashProvider`(dd/fastboot/dfu/openocd)+ 各 provider + tool consumer。 + 6. BoardSpec(`shared/types.ts:98`)做 provider 配置。 +- **验收**:加 `RdkS100Provider` 后 tool-board-link 无改动可用 S100;`register` disposer 后 tool 不见该板。 +- **状态**:未开始。 + +### T09 compaction 完整工程【P1,前置 T06,G8】 +- **执行**: + 1. `src/compaction/token-meter.ts`:量 context 用量(嫁接 dsh `token-meter`)。 + 2. `src/compaction/tool-result-pruner.ts`:i2cdump/gdb/dmesg 大输出 model-free 压缩成摘要。 + 3. `src/compaction/summarizer.ts`:重放前缀 + append 压缩指令,复用 pi-ai KV prefix cache。 + 4. surface replace:`user/message` 带 `surfaceOp:{op:'replace',start,end}`(接 T06 PbaSession)。 + 5. `src/compaction/spill.ts`:`SpillStore` + `SpillLocator` branded 句柄,datasheet 大结果 spill。 +- **验收**:压力触发 summarize KV cache 复用;i2cdump prune 寄存器地址不丢;datasheet spill 句柄可取回。 +- **状态**:未开始。 + +### T10 CI 质量门 + snapshot + doc-sync【P1,前置 T01,G12】 +- **执行**: + 1. `.github/workflows/ci.yml`:`test:coverage` per-file 100% 门(v8/istanbul)。 + 2. `scripts/e2e-snapshot.ts`:联网 key 跑最小闭环,输出 snapshot,回归对比。 + 3. `scripts/doc-sync.ts`:校验架构文档锚点 file:line 与代码对齐。 + 4. `scripts/type-drift-check.ts`:CI 定期对真 pi 源码 tsc,检测镜像漂移。 + 5. `docs/postmortem/`:编号事后复盘模板。 +- **验收**:CI per-file 100% 门红即挡;snapshot 漂移红;doc-sync 锚点不一致红;类型漂移红。 +- **状态**:未开始(依赖 T01 联网)。 + +### T11 类型镜像漂移检测【P1,前置无,G13】 +- **执行**: + 1. `tsconfig.realpi.json`:paths 指真 pi 源码(`../pi/packages/*/src/index.ts`),临时用。 + 2. `scripts/type-drift-check.ts`:跑 `tsc -p tsconfig.realpi.json`,过滤 pi 自家内部错(已知 `packages/agent/src/*` 报错是 pi build 产物问题,非 pba),只看 `src/**/*.ts` 是否 0 错。 + 3. CI 定期跑(周)。 +- **验收**:pi 升版后若 pba `src/types/pi.d.ts` 镜像与真 pi 不符,CI 红。 +- **状态**:未开始(已实测:当前我文件对真 pi 源码 0 错,报错全在 pi 自家)。 + +## 6.3 P2 任务(改进,工程效率/通用性) + +### T12 子代理 + 工作流编排【P2,前置 T07/T08,G7】 +- **执行**: + 1. 评估 pi subagent 机制;不足则自建 `src/capabilities/subagent/`(spawn-in-process provider)。 + 2. loop-orchestrator 上层加 `src/capabilities/workflow/`:parallel(编译+探板+datasheet)/ pipeline(edit→compile→flash→verify)。 + 3. 工作流脚本能 fan out 子 agent,带上限。 +- **验收**:parallel 三任务并发;pipeline 串行 stage 抛错 item 落 null;子 agent 事件不串主 agent。 +- **状态**:未开始。 + +### T13 上下文注入三段(inject/steer/followup)【P2,前置 T06/T07,G9】 +- **执行**:pba Agent 接口加 `inject`(寄存器表 next-step 不唤醒)/`steer`(换板 next-step 唤醒)/`followup`(新任务 next-turn 唤醒)。 +- **验收**:三段语义区分;runtime-context 快照"取代更早快照"。 +- **状态**:未开始。 + +### T14 plan/goal/todo logged state【P2,前置 T06,G10】 +- **执行**:checkpoint 进度(`CheckpointState`,`shared/types.ts:45`)写进 PbaSession 事件,resume/fork 从 log 重建。 +- **验收**:session resume 后 checkpoint 状态从 log 重建。 +- **状态**:未开始。 + +### T15 profile/bundle 分层【P2,前置 T08,G11】 +- **执行**:维修诊断 profile vs 嵌入式开发 profile,共享 base + 叠差异(维修诊断要 pdf-reader/datasheet-rag/外设探测;嵌入式开发要 cross-compile/flash/jtag)。 +- **验收**:两 profile 共享 base,各叠差异扩展。 +- **状态**:未开始。 + +### T16 多 LLM provider 适配【P2,前置无,G14】 +- **执行**:glm-provider 扩展支持多 provider(复用 dsh `THINKING_FORMAT_GATE` 思路),支持 DeepSeek 原生 + 其他。 +- **验收**:换模型改配置行不改扩展。 +- **状态**:未开始。 + +### T17 审批接缝 + LSP/code-runtime + credentials/settings【P2,按需,G16-G18】 +- **执行**:按业务方向引入 `ctx.approval`(fail-closed 无人值守审批)/ `ctx.lsp`(嵌入式 IDE)/ `ctx.credentials`/`ctx.settings`。 +- **验收**:按需逐个。 +- **状态**:未开始。 + +## 6.4 任务依赖图 + +``` +T01(真冒烟) ────────────────── T10(CI 门) ──┐ + │ +T06(PbaSession) ─┬─ T09(compaction) │ + ├─ T13(inject/steer) │ + ├─ T14(plan/goal/todo) │ + └─ T04(流水线) ────────────┤ + │ +T07(PbaEventBus) ─┬─ T04(流水线) │ + ├─ T08(接缝) ── T15(profile) + ├─ T12(子代理+工作流) │ + └─ T13 │ + │ +T02(正则+hex联动) ── T03(reg 工具) ── T04 │ + │ +T08(接缝) ── T05(board 沙箱) │ + │ +T11(类型漂移) ─────────────────────────────┘ +``` + +关键路径:**T01 真冒烟**(解锁运行时验证)→ **T02/T03 安全门堵漏洞**(防砖板)→ **T07 typed events + T06 session log**(骨架底座)→ **T04 五段流水线**(安全结构化)→ **T08 接缝**(多板)→ **T05 board 沙箱**(板侧围栏)→ **T09 compaction**(长会话)→ **T10 CI 门**(可维护)。 + +--- + +# 第七部分:开发任务进度表 + +> 维护中。状态:✅ 完成 / 🔄 进行中 / ⏳ 未开始 / ⛔ 阻塞。每完成一项更新此表 + 附 commit hash + 测试证据。 + +## v2 已完成(commit 06a19a6) + +| 项 | 状态 | 证据 | +|---|---|---| +| 21 域扩展 barrel 装配 | ✅ | `src/extensions/index.ts:38-86`,`--print-extensions` 21 工厂 | +| glm-5.2 命门一根治(thinking 黑洞) | ✅ | `glm-provider.ts:81-102`,buildGlmModelConfig | +| glm-5.2 命门二根治(hex 强转砖板) | ✅ | `glm-provider.ts:166-262`,normalizeHexArg | +| 空输出检测 | ✅ | `glm-provider.ts:286-314` | +| safety-gate 破坏性命令拦截 + 资源锁 | ✅ | `safety-gate.ts:35-170` | +| flash 三段式安全烧录 | ✅ | `flash.ts:1-130` | +| hardware-state mini 事件溯源 | ✅ | `hardware-state.ts:134` | +| loop-orchestrator checkpoint 状态机 | ✅ | `loop-orchestrator.ts:153` | +| 732 单测 + tsc 0 错 + 装配冒烟 | ✅ | vitest 21 文件 732 绿 | +| PhysicalByteAgent.launch + verifyAssembly | ✅ | `src/agent.ts:44-93` | +| 密钥铁律(${DROBOTICS_LLM_KEY} 占位) | ✅ | grep sk-nAm = 0 | + +## v3 任务进度 + +| 任务 | 优先级 | 前置 | 状态 | commit | 验收证据 | +|---|---|---|---|---|---| +| T01 真 pi 端到端冒烟 | P0 | 无 | ✅ 离线 boot 验证 | (本批) | 1044 测试含 71 e2e-smoke + 1 e2e-runtime;真 `createAgentSession` boot 成功(vitest 源码别名,无需 build)+ 21/21 工厂装配 + 24 工具注册 + drobotics-glm provider + 模型无回退;剩余"真 LLM 一轮 turn"需 key+网络、"bin/pba.ts dist 分发"需 build:offline,均非硬阻塞(见 postmortem 0001 更正) | +| T02 safety-gate 正则与 hex 归一联动 | P0 | T06 部分 | ✅ | (本批) | `safety-gate.ts` evaluateSafety 接 normalizeCommandHex+deobfuscateCommand;70 测试(EP/边界/决策表/对抗/变异/元蜕变);`devmem 1073872896 w`→归一→block | +| T03 devmem 专用 reg 工具 + datasheet 校验 | P0 | T02 | ✅ | (本批) | `reg-tool.ts`(KNOWN_REGISTERS+validateRegisterAddress+planRegOp+工厂,prepareArguments 接 hex 归一);29 测试;devmem-via-bash 硬门(hardGate 不可 allowRules 豁免)+ barrel 注册 reg(22 工厂) | +| T04 五段工具流水线 | P0 | T07 | ✅ (①②wired/④⑤tested) | (本批) | `src/core/tool-pipeline.ts`(ToolPipeline 五段+单调 guards+decide();24 测试,含单调不变式元蜕变);safety-gate tool_call 钩子委托 pipeline.decide()(stage①②真 wired);flash finalizeFlashContent 导出(content-only);注:stage ④⑤全 agent-loop wiring 受 pi 扩展 API 在 tool_call 仅能 block 之限,pipeline 自身已实现+测试,未假装 | +| T05a board-side 沙箱(脚本模拟) | P0 | T08 | ✅ | (本批) | `src/core/sandbox-policy.ts`(probeSandbox full/partial/unusable + applySandboxToArgv + shouldRunCommand,Object.freeze 单一 home);board-link makeExec 包 argv + fail-closed(unusable→exitCode126 不 spawn);159 测试(EP/边界/决策表/状态转换/变异/对抗/元蜕变) | +| T05b board-side 真 landlock-run | P0 | T05a | ✅ 源码+契约验证 / ⏙ 待交叉编译 | (本批) | `native/landlock-run/landlock-run.c`(C11,raw syscall self-restrict-then-exec,fail-closed exit126,--probe exit 0/1/2 映射 capability)+ Makefile(cross-aarch64 musl 静态)+ README;sandbox-policy.ts 加 probeViaBinary + board-link resolveBoardSandbox 接真二进制优先;macOS stub 编译+--probe exit2 + -- exec 契约测试通过;aarch64 真二进制需 toolchain(本机无 aarch64-linux-musl-gcc/docker)跑 `make cross-aarch64` | +| T06 PbaSession 事件溯源 | P1 | 无 | ⏳ | - | - | +| T07 PbaEventBus + ScopeKey | P1 | 无 | ⏳ | - | - | +| T08 能力接缝三角色(board-link+flash) | P1 | 无 | ⏳ | - | - | +| T09 compaction 完整工程 | P1 | T06 | ⏳ | - | - | +| T10 CI 质量门 + snapshot + doc-sync | P1 | T01 | ⏳ | - | - | +| T11 类型镜像漂移检测 | P1 | 无 | ⏳ | - | - | +| T12 子代理 + 工作流编排 | P2 | T07/T08 | ⏳ | - | - | +| T13 上下文注入三段 | P2 | T06/T07 | ⏳ | - | - | +| T14 plan/goal/todo logged state | P2 | T06 | ⏳ | - | - | +| T15 profile/bundle 分层 | P2 | T08 | ⏳ | - | - | +| T16 多 LLM provider 适配 | P2 | 无 | ⏳ | - | - | +| T17 审批/LSP/credentials/settings | P2 | 按需 | ⏳ | - | - | + +## 里程碑 + +| 里程碑 | 范围 | 目标 | 状态 | +|---|---|---|---| +| M0 安全跑通 | T01/T02/T03/T04/T05a/T05b | 能 boot(真 createAgentSession 离线✅) + 不砖板(devmem 硬门+hex 联动+reg 工具) + 安全门结构化(五段流水线①②wired) + 板侧沙箱(landlock-run C 源+契约✅) | ✅ P0 全落(T05b aarch64 真二进制待 toolchain 编译) | +| M1 可长跑 | T06/T07/T08/T09 | session 事件溯源 + typed events + 接缝 + compaction | ⏳ | +| M2 可维护 | T10/T11 | CI 门 + snapshot + 漂移检测 | ⏳ | +| M3 可扩展 | T12-T17 | 子代理 + profile 分层 + 多 provider | ⏳ | + +## 下一步动作 + +1. **T05b aarch64 真二进制**:在有 aarch64-linux-musl-gcc 或 docker toolchain 的环境跑 `cd native/landlock-run && make cross-aarch64`,产物 `landlock-run-aarch64` 部署到板,`PBA_BOARD_SANDBOX_BINARY` 指向它即启用真 Landlock。源码+契约已就绪,缺的只是 toolchain。 +2. **T01 真 LLM 一轮 turn**(可选,需 key+网络):`bin/pba.ts` dist 分发需 `build:offline`(卡 `check:model-data`,需 `generate-models` 联网填 `providers/data/`);或直接用 vitest 源码别名跑一轮带 mock/真 key 的 agent turn。createAgentSession boot 已✅,差的只是真模型推理。 +3. **M1 启动**:T06 PbaSession + T07 PbaEventBus + T08 能力接缝(皆可离线并行启)。T04 的 stage ④⑤ 全 agent-loop wiring 依赖 T06/T07 落地后才能在 session/typed-event 层接 around/post/finalize。 +4. **T11 类型漂移门**:CI 定期对真 pi 源码 tsc,检测 `src/types/pi.d.ts` 镜像漂移。 + +--- + +## 附录 A:与 pi / dsh / pba 三方对比速查 + +| 维度 | pi | dsh | pba(v3 目标) | +|---|---|---|---| +| 框架底座 | 自研轻量 harness | vendored Cordis | pi 扩展(不引 Cordis) | +| session log | sqlite + appendEntry | append-only + deriveMessages + "logged"不变量 | PbaSession + deriveMessages(最小子集,T06) | +| 事件 | pi.events 松散 | 四分派 + waterfall + scope | PbaEventBus + waterfall + scope(T07) | +| 工具流水线 | registerTool + tool_call block | 五段 + 单调 guard + finalizeContent | 五段(T04) | +| 沙箱 | 无 | Landlock C11/Seatbelt/ACL | board-side landlock/seccomp + host 正则升级(T05) | +| 能力接缝 | 无 | Definition/Provider/Consumer | board-link/flash 三角色(T08) | +| LLM | pi-ai | ctx.llm + DeepSeek + pi-ai | glm-5.2 命门根治(已✅) | +| compaction | session_before_compact | KV cache + prune + spill | compaction 完整工程(T09) | +| 子代理/工作流 | 无原生 | ctx.subagents + workflowEngine | 子代理 + workflow(T12) | +| 嵌入式能力 | 无 | 无 | 21 域(已✅,dsh 完全没有) | +| 质量门 | 基本测试 | per-file 100% + snapshot + doc-sync | CI 门(T10) | + +## 附录 B:关键源码锚点速查 + +### pba 现状(v2) +| 主题 | 锚点 | +|---|---| +| barrel 装配 | `src/extensions/index.ts:38-86` | +| glm 命门一 | `src/extensions/glm-provider.ts:81-102` | +| glm 命门二 | `glm-provider.ts:166-262` | +| safety-gate 正则 | `src/extensions/safety-gate.ts:35-110` | +| safety-gate tool_call 钩子 | `safety-gate.ts:206-240` | +| flash 三段式 | `src/extensions/flash.ts:1-130` | +| hardware-state replay | `src/extensions/hardware-state.ts:134` | +| loop-orchestrator checkpoint | `src/extensions/loop-orchestrator.ts:153` | +| PhysicalByteAgent.launch | `src/agent.ts:71-93` | +| pi 类型镜像 | `src/types/pi.d.ts`(EventBus:141) | + +### dsh 参照(嫁接源) +| 主题 | 锚点 | +|---|---| +| Session.append | `packages/core/session/src/index.ts:604` | +| deriveMessages | `index.ts:726` | +| SessionEventMap | `packages/core/session/src/types.ts:236` | +| scope | `packages/core/scope/src/index.ts:137/170` | +| 工具流水线 | `packages/core/tools/src/index.ts:1342` | +| ToolRuntimeScheduler | `index.ts:451` | +| guard | `index.ts:706/1110` | +| landlock-run | `native/landlock-run/` | +| compaction | `packages/compaction/compaction/src/index.ts` | +| subagent | `packages/subagent/subagent/src/types.ts` | +| workflow | `packages/workflow/workflow/src/index.ts` | +| PiAiAdapter | `packages/llm/llm-pi-ai/src/adapter.ts:186` | + +### pi 底座(继承) +| 主题 | 锚点 | +|---|---| +| createAgentSession | `packages/coding-agent/src/core/sdk.ts:171` | +| 扩展自动发现 | `packages/coding-agent/src/core/extensions/loader.ts:710` | +| registerTool | `types.ts:1251` | +| on tool_call | `types.ts:901/1071-1080` | +| appendEntry | `types.ts:1318` | +| session_before_compact | `types.ts:1117-1120` | +| executionMode sequential | `agent-loop.ts:419-423` | +| openai-completions qwen 分支 | `openai-completions.ts:762-763` | + +--- + +*本架构文档基于 pba commit 06a19a6(v2)+ dsh commit 47f943859b + pi v0.84.1 源码。v3 任务进度表随开发实时更新,每完成一项附 commit hash + 测试证据。*