feat(v3): P1+P2 全落地 — T06–T17 + 系统集成测试
Some checks are pending
CI / quality-gate (push) Waiting to run
CI / type-drift (push) Waiting to run

12 模块多 agent 并行开发(dev+test+fix 每,两层 + barrier):
- T06 PbaSession 事件溯源 + deriveMessages + logged 不变量
- T07 PbaEventBus typed event bus + waterfall + ScopeKey 隔离
- T08 能力接缝三角色(board-link + flash Provider/Registry/consumer)
- T09 compaction 完整工程(token-meter/pruner/summarizer/spill)
- T10 CI 质量门 + snapshot + doc-sync
- T11 类型镜像漂移检测(tsconfig.realpi + type-drift-check)
- T12 子代理 + 工作流编排(parallel/pipeline/InlineSubagentProvider)
- T13 上下文注入三段(inject/steer/followup)
- T14 plan/goal/todo checkpoint logged state(look-ahead 状态机)
- T15 profile/bundle 分层(维修诊断 vs 嵌入式开发,共享 base)
- T16 多 LLM provider 适配(ProviderRegistry + glm-5.2/deepseek)
- T17 审批接缝(fail-closed auto-deny)+ credentials/settings/lsp

集成(串行):
- src/index.ts 公共 re-export(board-link/flash 具名避 shared/types 重名)
- tests/system-integration.test.ts 跨模块 10 闭环(事件溯源→compaction→bus→
  接缝→checkpoint→inject→workflow→approval→provider→profile)
- 全量 tsc=0;vitest 39 文件 2449 passed/5 skipped(1044 baseline +~1400 模块 + 10 系统)
- 密钥铁律:\${DROBOTICS_LLM_KEY} 占位,grep sk- 明文 0

68 workflow agent / 0 error / ~3M token;mutation 测试每模块 3-9 seeded bug 全杀。

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
d-robotics 2026-08-14 15:35:49 +08:00
parent d671f174fe
commit 6d6a805d46
51 changed files with 23694 additions and 0 deletions

123
.github/workflows/ci.yml vendored Normal file
View File

@ -0,0 +1,123 @@
# CI 质量门(T10)—— per-file 覆盖门 + doc-sync + type-drift-check
# 见架构设计文档_v3.md §5.9
#
# 两个 Job:
# quality-gate —— 每次 push/PR 跑:vitest per-file 100% 覆盖门 + tsc 类型检查
# + doc-sync 锚点对齐(调本仓 scripts/doc-sync.ts)
# type-drift —— 周期(schedule)+ 手动触发跑:类型镜像漂移检测
# (调 T11 的 scripts/type-drift-check.ts,需 ../pi/packages 源码)
# 非「每次提交」跑,因 type-drift 需真 pi 源码树且属升版级检查。
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
schedule:
# 每周二 03:17 UTC 跑 type-drift(错峰,避开 :00)
- cron: "17 3 * * 2"
workflow_dispatch:
permissions:
contents: read
jobs:
# ==========================================================================
# quality-gate:per-file 100% 覆盖 + 类型检查 + doc-sync
# ==========================================================================
quality-gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: Install deps
run: npm ci
- name: Typecheck (tsc --noEmit)
run: npm run typecheck
# per-file 100% 覆盖门:v8 istanbul,thresholds.perFile 对 src/**/*.ts 逐文件
- name: Test + per-file 100% coverage gate
run: |
npx vitest run \
--coverage.enabled \
--coverage.provider=v8 \
--coverage.include='src/**/*.ts' \
--coverage.thresholds.perFile=true \
--coverage.thresholds.lines=100 \
--coverage.thresholds.branches=100 \
--coverage.thresholds.functions=100 \
--coverage.thresholds.statements=100
# doc-sync:校验架构文档锚点 file:line 与代码对齐,不符即红。
# 用 stdin ESM + 动态 import(process.cwd() 可移植),规避 tsx -e 的
# eval-CJS 上下文无法解析 .js→.ts 相对路径的问题。
- name: doc-sync
run: |
cat <<'EOF' | npx tsx --input-type=module
const cwd = process.cwd();
const m = await import(cwd + "/scripts/doc-sync.js");
const r = m.checkDocSync({
readFile: m.defaultReadFile,
grepSymbol: m.defaultGrepSymbol,
anchors: m.DEFAULT_DOC_ANCHORS,
});
if (!r.ok) {
console.error("doc-sync mismatches:\n" + r.mismatches
.map(x => ` - ${x.anchor.docFile}:${x.anchor.docLine} -> ${x.reason}`)
.join("\n"));
process.exit(1);
}
console.log("doc-sync: all anchors aligned");
EOF
# ==========================================================================
# type-drift:类型镜像漂移检测(周期 + 手动,需真 pi 源码树)
# ==========================================================================
type-drift:
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: Install deps
run: npm ci
# type-drift-check 需 ../pi/packages 真源码(tsconfig.realpi.json paths 指向)
# 源码树不在本仓(gitignore 的 pi 符号链接/目录);缺源码则无法验证,跳过并告警
- name: Verify pi source tree present
id: pi-src
run: |
if [ -d "../pi/packages" ]; then
echo "present=true" >> "$GITHUB_OUTPUT"
else
echo "::warning::../pi/packages not present; type-drift-check skipped (no source to verify against)"
echo "present=false" >> "$GITHUB_OUTPUT"
fi
- name: type-drift-check
if: steps.pi-src.outputs.present == 'true'
run: |
cat <<'EOF' | npx tsx --input-type=module
const cwd = process.cwd();
const m = await import(cwd + "/scripts/type-drift-check.js");
const r = m.checkTypeDrift({});
if (r.driftDetected) {
console.error("type drift detected (pba src mirror stale):\n" + r.pbaErrors.join("\n"));
process.exit(1);
}
console.log("type-drift: no drift");
console.log("pi-internal errors (ignored): " + r.piInternalErrors.length);
EOF

4
.gitignore vendored
View File

@ -17,3 +17,7 @@ models.json.bak
native/landlock-run/landlock-run-stub
native/landlock-run/landlock-run-aarch64
native/landlock-run/landlock-run-aarch64-gnu
# 变异测试运行时产物(m1-m4.mjs 等测试时生成的 bug 副本,不入库)
tests/.mutation-kill/
*.mutation.mjs

251
scripts/doc-sync.ts Normal file
View File

@ -0,0 +1,251 @@
/**
* @module doc-sync
*
* 文档锚点同步校验(T10)—— 校验架构文档的 file:line 锚点与代码对齐。
*
* 为什么需要:架构设计文档_v3.md 通篇用 `src/foo.ts:NN` 锚点引用真实代码
* (如「`src/core/tool-pipeline.ts`:实现 `ToolPipeline` 调度器」)。代码重构后
* 文档锚点易漂移——文件路径搬走、符号改名、整段删除——而文档仍指旧位置,
* 误导后续维护者。本模块把「文档声称的锚点 ⟺ 代码真实存在」做成可注入的纯校验,
* CI 跑之,锚点与代码不符即红。
*
* 双侧校验(一个 DocAnchor 同时钉住文档侧与代码侧):
* - 文档侧:docFile 的第 docLine 行必须确实引用 codeFile(锚点位置没飘)。
* - 代码侧:codeSymbol 必须在 codeFile 中存在(grepSymbol 返回 >0 行号)。
* 任一侧不符即记一条 mismatch,附可读 reason。两侧皆过才 ok。
*
* fail-closed(安全不变式):
* - docFile 不可读 / docLine 越界 → mismatch(无法确认锚点对齐,安全默认红)。
* - codeFile 不可读 → mismatch(同上)。
* - grepSymbol 返回 ≤0(约定 -1 表未命中;0 表非法行号)→ mismatch。
*
* 正交阶段(单一职责,确定性可测):
* checkDocSync(纯校验,readFile/grepSymbol 注入)为唯一主入口;
* defaultReadFile / defaultGrepSymbol 是真 IO 适配器(CI 装配,单测注入 mock);
* DEFAULT_DOC_ANCHORS 是已人工核对落地的锚点清单(CI 默认跑)。
*
* 纯逻辑 + readFile/grepSymbol 可注入,零 pi 运行时依赖,可离线单测。
* 见架构设计文档_v3.md §5.9(CI 质量门:doc-sync 文档门)。
*/
import { readFileSync } from "node:fs";
// ============================================================================
// 命名常量 —— 消灭魔法值
// ============================================================================
/**
* grepSymbol「未命中」哨兵。行号 1-indexed,故 ≤0 一律视为未命中(兼容 -1 与 0
* 两种约定,fail-closed:歧义即红)。
*/
const GREP_NOT_FOUND_MAX = 0;
/** 默认架构文档文件(doc-sync 校验对象)。 */
const DEFAULT_DOC_FILE = "架构设计文档_v3.md";
// ============================================================================
// 类型契约
// ============================================================================
/**
* 一条文档锚点:声明「docFile 的第 docLine 行引用了 codeFile 中的 codeSymbol」。
*
* docFile / codeFile 均为仓库相对路径。docLine 1-indexed。
*/
export interface DocAnchor {
/** 文档文件(仓库相对路径,如 "架构设计文档_v3.md")。 */
readonly docFile: string;
/** 文档内锚点行号(1-indexed)。 */
readonly docLine: number;
/** 锚点引用的代码文件(仓库相对路径,如 "src/core/tool-pipeline.ts")。 */
readonly codeFile: string;
/** 锚点声称在 codeFile 中存在的符号(子串匹配,如 "ToolPipeline")。 */
readonly codeSymbol: string;
}
/** 单条锚点校验不符。 */
export interface DocSyncMismatch {
/** 触发不符的锚点。 */
readonly anchor: DocAnchor;
/** 人类可读的不符原因。 */
readonly reason: string;
}
/** checkDocSync 返回值。 */
export interface DocSyncResult {
/** 全部锚点两侧皆过即 true。 */
readonly ok: boolean;
/** 不符清单(保持锚点输入序,稳定可测)。 */
readonly mismatches: readonly DocSyncMismatch[];
}
/** readFile 抽象(注入以便单测 mock,避免真 fs)。 */
export type ReadFile = (path: string) => string;
/** grepSymbol 抽象(注入以便单测 mock)。返回 1-indexed 行号,未命中返回 -1。 */
export type GrepSymbol = (file: string, symbol: string) => number;
// ============================================================================
// 真 IO 适配器 —— CI 装配用(单测注入 mock 替代)
// ============================================================================
/**
* 默认 readFile:同步读 UTF-8 文本。
*
* 抛错(文件不存在等)由调用方 {@link checkDocSync} 的 try/catch 兜成 mismatch。
*
* @param path 仓库相对路径。
* @returns 文件 UTF-8 文本。
*/
export const defaultReadFile: ReadFile = (path) => readFileSync(path, "utf8");
/**
* 默认 grepSymbol:在 file 中按行子串查找 symbol,返回首个命中行号(1-indexed)。
*
* 子串匹配即可(注释/实现皆算)——doc-sync 只关心「符号概念仍在该文件」,
* 不要求精确到定义行。未命中返回 -1。
*
* @param file 代码文件路径。
* @param symbol 要查的符号子串。
* @returns 首个命中行号(1-indexed),未命中 -1。
*/
export const defaultGrepSymbol: GrepSymbol = (file, symbol) => {
const text = readFileSync(file, "utf8");
const lines = text.split("\n");
for (let i = 0; i < lines.length; i++) {
if (lines[i].includes(symbol)) return i + 1;
}
return -1;
};
// ============================================================================
// DEFAULT_DOC_ANCHORS —— 已人工核对落地的锚点(CI 默认跑)
// ============================================================================
/**
* 深冻结 DocAnchor 数组:外层数组 + 逐元素对象均 Object.freeze。
*
* Object.freeze(arr) 仅浅冻结——元素 DocAnchor 对象的 docFile/docLine 等属性
* 仍可写、可被运行时静默篡改(如 `DEFAULT_DOC_ANCHORS[0].docFile = 'x'` 不抛错)。
* 逐元素 Object.freeze 方达「深冻结」语义,兑现下方注释的安全不变式承诺。
*
* @param anchors 待冻结锚点(元素须为纯对象)。
* @returns 深冻结后的同一引用(外层 + 元素皆 Object.isFrozen===true)。
*/
function deepFreezeAnchors(anchors: readonly DocAnchor[]): readonly DocAnchor[] {
for (const anchor of anchors) {
Object.freeze(anchor);
}
return Object.freeze(anchors) as readonly DocAnchor[];
}
/**
* 默认锚点清单。每条均经人工核对:docLine 行确实引用 codeFile,codeSymbol 确在
* codeFile 中存在。新增锚点须先核对再追加,勿盲填。
*
* 深冻结(deepFreezeAnchors):外层数组 + 逐元素对象均 Object.freeze,
* 防运行时意外篡改 docFile/docLine 等字段(与 sandbox-policy 的
* DEFAULT_BOARD_SANDBOX_POLICY 同范式)。
*/
export const DEFAULT_DOC_ANCHORS: readonly DocAnchor[] = deepFreezeAnchors([
{
docFile: DEFAULT_DOC_FILE,
docLine: 274,
codeFile: "src/extensions/hardware-state.ts",
codeSymbol: "replayFromEntries",
},
{
docFile: DEFAULT_DOC_FILE,
docLine: 582,
codeFile: "src/core/tool-pipeline.ts",
codeSymbol: "ToolPipeline",
},
{
docFile: DEFAULT_DOC_FILE,
docLine: 749,
codeFile: "src/core/sandbox-policy.ts",
codeSymbol: "probeSandbox",
},
]);
// ============================================================================
// checkDocSync —— 主入口(纯逻辑,readFile/grepSymbol 注入)
// ============================================================================
/**
* 校验文档锚点 file:line 与代码对齐。
*
* 对每个 anchor 做双侧校验:
* 1. 文档侧——读 docFile,取第 docLine 行,确认其确实引用 codeFile
* (字符串包含 codeFile 路径)。docFile 不可读 / 行越界 → mismatch(fail-closed)。
* 2. 代码侧——grepSymbol(codeFile, codeSymbol) 返回 >0 行号表存在;
* ≤0 或抛错 → mismatch(fail-closed:无法确认存在即视为漂移)。
*
* mismatches 保持锚点输入序(稳定、可测);ok 当且仅当 mismatches 为空。
*
* 纯逻辑、readFile/grepSymbol 可注入、无 pi 运行时依赖、确定性可测。
*
* @param opts.readFile 文件读取器(默认 fs.readFileSync;单测注入 mock)。
* @param opts.anchors 待校验锚点清单。
* @param opts.grepSymbol 符号查找器(默认按行子串;单测注入 mock)。
* @returns 校验结果(ok + mismatches)。
*/
export function checkDocSync(opts: {
readFile: ReadFile;
anchors: readonly DocAnchor[];
grepSymbol: GrepSymbol;
}): DocSyncResult {
const { readFile, anchors, grepSymbol } = opts;
const mismatches: DocSyncMismatch[] = [];
for (const anchor of anchors) {
// ---- 文档侧 ----
let docText: string;
try {
docText = readFile(anchor.docFile);
} catch {
mismatches.push({
anchor,
reason: `doc file not readable: ${anchor.docFile}`,
});
continue;
}
const docLines = docText.split("\n");
const docLine = docLines[anchor.docLine - 1];
if (docLine === undefined) {
mismatches.push({
anchor,
reason: `doc line ${anchor.docLine} out of range (file has ${docLines.length} lines)`,
});
continue;
}
if (!docLine.includes(anchor.codeFile)) {
mismatches.push({
anchor,
reason: `doc line ${anchor.docLine} does not reference "${anchor.codeFile}"`,
});
continue;
}
// ---- 代码侧 ----
let codeLine: number;
try {
codeLine = grepSymbol(anchor.codeFile, anchor.codeSymbol);
} catch {
mismatches.push({
anchor,
reason: `code file not readable: ${anchor.codeFile}`,
});
continue;
}
if (codeLine <= GREP_NOT_FOUND_MAX) {
mismatches.push({
anchor,
reason: `symbol "${anchor.codeSymbol}" not found in ${anchor.codeFile}`,
});
}
}
return { ok: mismatches.length === 0, mismatches };
}

197
scripts/e2e-snapshot.ts Normal file
View File

@ -0,0 +1,197 @@
/**
* @module e2e-snapshot
*
* 闭环 snapshot 回归对比(T10)—— 结构化深比较 actual vs baseline。
*
* 为什么需要:联网 key 跑最小闭环(工具调用序列 / 硬件状态快照 / 判据输出),
* 落一份 baseline snapshot 入库;后续回归跑同用例,对比 actual 与 baseline,
* 任何叶子漂移即 CI 红。用结构化路径而非全文本 diff,定位精确到字段。
*
* 设计:把 actual / baseline 各自拍平成 path→序列化值 的扁平表,再对 path 集合
* 做集合运算:
* - added : actual 有、baseline 无(回归新增字段)
* - removed: baseline 有、actual 无(回归丢失字段)
* - changed: 同 path 两边序列化值不同(值漂移)
* - match : 三者皆空
*
* 拍平规则(确定性):
* - 原始值 / null / 非纯对象(Date/Map 等)→ 叶子,JSON 序列化。
* - 纯对象 → 按 key 递归,path 以 "." 连接(根 key 不加前导点)。
* - 数组 → 按下标递归,下标作 path 段("a.0.b")。
* - 空对象 "{}" / 空数组 "[]" → 叶子(结构本身是值,结构变化即漂移)。
* path 升序排序 → added/removed/changed 输出稳定(元蜕变不变式:确定性)。
*
* 纯逻辑、零 IO、零 pi 运行时依赖、可离线单测。
* 见架构设计文档_v3.md §5.9(CI 质量门:真实 API snapshot)。
*/
// ============================================================================
// 类型契约
// ============================================================================
/** 闭环 snapshot 对比差异。path 为点号连接的扁平字段路径。 */
export interface SnapshotDiff {
/** actual 与 baseline 结构完全一致即 true。 */
readonly match: boolean;
/** actual 独有 path(baseline 缺失)。升序。 */
readonly added: readonly string[];
/** baseline 独有 path(actual 缺失)。升序。 */
readonly removed: readonly string[];
/** 两边皆有 path 但序列化值不同。升序。 */
readonly changed: readonly string[];
}
// ============================================================================
// 内部工具:序列化 / 纯对象判定 / 拍平
// ============================================================================
/**
* 序列化叶子值,保证「不同语义值 → 不同串」不碰撞。
*
* JSON.stringify 的已知陷阱(本函数逐一规避):
* - undefined → 返回裸 undefined(非串)→ 此处特判为 "undefined"。
* - NaN / Infinity / -Infinity → 均序列化为 "null",与真 null 碰撞 →
* 分别特判为 "NaN" / "Infinity" / "-Infinity"。
* - function → 返回裸 undefined → 特判为 "function"(与「键不存在」的
* undefined 哨兵区分,保证同函数自反 match=true)。
* - symbol → JSON.stringify 返回裸 undefined(非串)→ 会落到 "undefined"
* 与真 undefined 碰撞 → 特判为 "symbol"(不透明身份类型,与 function 同
* 处理范式:不序列化内部描述,保证自反 match=true 且与 undefined 区分)。
* - bigint → JSON.stringify 抛 TypeError("Do not know how to serialize a
* BigInt")未被兜底 → 特判为 `bigint:${value}`(带类型前缀以与 JSON 序列化
* 的数字 "1" / 字符串 "\"1\"" 区分,同时保留数值供漂移检测:BigInt(1) 与
* BigInt(2) 串不同 → changed;BigInt(1) 自反 → match=true)。
* - -0(负零)→ JSON.stringify(-0) 返回 "0",与正零 0 碰撞,而
* Object.is(-0, 0) === false(语义不同)→ 特判为 "-0"(在 number 分支内
* 优先于 NaN / Infinity 判定,保证 -0 与 0 串不同 → 0→-0 漂移即 changed;
* -0 自反 → match=true)。
* 其余(null / 有限数字 / 字符串 / 布尔 / 非纯对象 toJSON)走 JSON 标准序列化,
* 稳定可比。
*/
function serializeLeaf(value: unknown): string {
if (value === undefined) return "undefined";
if (typeof value === "function") return "function";
if (typeof value === "symbol") return "symbol";
if (typeof value === "bigint") return `bigint:${value}`;
if (typeof value === "number") {
// -0 与 0 语义不同(Object.is(-0,0)===false)但 JSON.stringify 均得 "0"
// → 优先特判 "-0",避免 0↔-0 漂移被静默掩盖。
if (Object.is(value, -0)) return "-0";
if (Number.isNaN(value)) return "NaN";
if (!Number.isFinite(value)) return value > 0 ? "Infinity" : "-Infinity";
}
const serialized = JSON.stringify(value);
return serialized === undefined ? "undefined" : serialized;
}
/** 是否纯对象(proto 为 null 或 Object.prototype)。Date/Map/类实例 → false → 当叶子。 */
function isPlainObject(value: object): boolean {
const proto = Object.getPrototypeOf(value);
return proto === null || proto === Object.prototype;
}
/** path 连接:根 prefix 为空串时直接取段,否则以 "." 连接。 */
function joinPath(prefix: string, segment: string): string {
return prefix === "" ? segment : `${prefix}.${segment}`;
}
/**
* 把 value 拍平进 out(path→序列化值)。递归纯对象/数组,其余当叶子。
*
* @param value 待拍平值。
* @param prefix 当前 path 前缀(根为 "")。
* @param out 累积目标表。
*/
function flatten(value: unknown, prefix: string, out: Map<string, string>): void {
// 原始值或 null(typeof null === "object",故先判 null)
if (value === null || typeof value !== "object") {
out.set(prefix, serializeLeaf(value));
return;
}
// 数组:空数组当叶子,否则按下标递归
if (Array.isArray(value)) {
if (value.length === 0) {
out.set(prefix, "[]");
return;
}
for (let i = 0; i < value.length; i++) {
flatten(value[i], joinPath(prefix, String(i)), out);
}
return;
}
// 非纯对象(Date/Map/Set/类实例)→ 叶子(走 toJSON),经 serializeLeaf 统一守卫
if (!isPlainObject(value)) {
out.set(prefix, serializeLeaf(value));
return;
}
// 纯对象:空对象当叶子,否则按 key 递归
const entries = Object.entries(value as Record<string, unknown>);
if (entries.length === 0) {
out.set(prefix, "{}");
return;
}
for (const [key, child] of entries) {
flatten(child, joinPath(prefix, key), out);
}
}
// ============================================================================
// compareSnapshot —— 主入口(纯逻辑)
// ============================================================================
/**
* 结构化深比较 actual 与 baseline,返回字段级差异。
*
* 拍平两侧为 path→序列化值 表后做集合运算:
* - added = actual 有 baseline 无的 path
* - removed = baseline 有 actual 无的 path
* - changed = 两边皆有但值不同的 path
* 三者升序排列保证确定性;match 当且仅当三者皆空。
*
* 不变式:compareSnapshot(a,b) 与 compareSnapshot(b,a) 的 added/removed 互换、
* changed 不变、match 不变——对称性可单测。空输入(undefined/null)当叶子处理。
*
* 纯逻辑、零 IO、无 pi 运行时依赖、确定性可测。
*
* @param actual 回归实跑产出的 snapshot。
* @param baseline 入库基线 snapshot。
* @returns 字段级差异。
*/
export function compareSnapshot(actual: unknown, baseline: unknown): SnapshotDiff {
const actualFlat = new Map<string, string>();
const baselineFlat = new Map<string, string>();
flatten(actual, "", actualFlat);
flatten(baseline, "", baselineFlat);
const added: string[] = [];
const removed: string[] = [];
const changed: string[] = [];
for (const [path, value] of actualFlat) {
const baselineValue = baselineFlat.get(path);
if (baselineValue === undefined) {
added.push(path);
} else if (baselineValue !== value) {
changed.push(path);
}
}
for (const [path] of baselineFlat) {
if (!actualFlat.has(path)) {
removed.push(path);
}
}
added.sort();
removed.sort();
changed.sort();
return {
match: added.length === 0 && removed.length === 0 && changed.length === 0,
added,
removed,
changed,
};
}

View File

@ -0,0 +1,448 @@
// physical_byte_agent — T06–T17 多 agent 并行开发工作流
// 两层 + barrier:Layer0(无依赖)并行 → barrier → Layer1(依赖 Layer0)并行。
// 每模块 pipeline:dev → test → fix(≤3)。barrel index.ts 任何 agent 都不碰(集成阶段我串行接)。
// 纯 JS,无 Date.now/Math.random。
export const meta = {
name: 'pba-t06-t17-build',
description: 'physical_byte_agent P1+P2 (T06–T17) 多 agent 并行开发:dev+test+fix 每模块',
phases: [
{ title: 'Layer0', detail: 'T06/T07/T08/T11/T16/T17 并行 dev→test→fix' },
{ title: 'Layer1', detail: 'T09/T13/T14/T15/T12/T10 并行 dev→test→fix(依赖 Layer0)' },
],
};
const DIR = '/Users/d-robotics/Desktop/physical_byte_agent';
// ───────────────────────── schemas ─────────────────────────
const DEV_SCHEMA = {
type: 'object',
required: ['module', 'files', 'exports', 'smokeTestCount', 'vitestGreen', 'notes'],
properties: {
module: { type: 'string' },
files: { type: 'array', items: { type: 'string' } },
exports: { type: 'array', items: { type: 'string' } },
smokeTestCount: { type: 'integer' },
vitestGreen: { type: 'boolean' },
notes: { type: 'string' },
},
};
const TEST_SCHEMA = {
type: 'object',
required: ['module', 'testFile', 'testCount', 'methods', 'mutationBugsPlanted', 'mutationKilled', 'allGreen', 'findings'],
properties: {
module: { type: 'string' },
testFile: { type: 'string' },
testCount: { type: 'integer' },
methods: { type: 'array', items: { type: 'string' } },
mutationBugsPlanted: { type: 'integer' },
mutationKilled: { type: 'integer' },
allGreen: { type: 'boolean' },
findings: {
type: 'array',
items: {
type: 'object',
required: ['severity', 'summary', 'file'],
properties: {
severity: { type: 'string', enum: ['high', 'medium', 'low'] },
summary: { type: 'string' },
file: { type: 'string' },
line: { type: 'integer' },
failureScenario: { type: 'string' },
},
},
},
},
};
// ───────────────────────── module specs ─────────────────────────
// 每个模块:key, title, files(严格独占), testFile, contract(精确导出+签名), spec, refs, deps
const MODULES = [
// ═══════════════════════ LAYER 0 ═══════════════════════
{
key: 'T06', layer: 0,
title: 'PbaSession 事件溯源 + deriveMessages',
files: ['src/core/pba-session.ts'],
testFile: 'tests/pba-session.test.ts',
contract: `PbaSessionEventMap (interface): keys turn/step/user-message/assistant-message/tool-call/tool-result/hw:state/flash-log/verify-record/checkpoint-change,每键映射到该事件的 data 形状(你定义合理字段)。
class PbaSession {
constructor(opts: { appendEntry: (type: string, data: unknown) => void; deepFreeze?: boolean });
append(event: { type: string; data: unknown }): void; // 唯一提交点:lossless-JSON 快照 + 深冻结 + seq 连续 + 重入 guard(重入抛错)
deriveMessages(): unknown[]; // 从有序 surface 投影模型历史,增量缓存(第二次调用命中缓存)
replayFromEntries(entries: ReadonlyArray<{type:string;data:unknown;seq?:number}>): PbaSession; // 从 log 重建(推广 hardware-state replayFromEntries 到全量事件)
assertModelVisibleLogged(visibleTypes: readonly string[]): void; // "model-visible⟺logged" 不变量:若 deriveMessages() 投影里有某 type 但 log 里没 append 过 → 抛错
}
纯逻辑,注入 appendEntry(无 pi 运行时 import)。深冻结常量。`,
spec: `事件溯源底座。append 是唯一提交点(防旁路写)。lossless-JSON 快照 = 结构化克隆语义(处理 Date/Map/Set 折叠成 plain)。seq 单调连续,缺口即抛。deriveMessages 增量缓存(append 后失效)。replayFromEntries 从 entries 重建一个等价 PbaSession。model-visible⟺logged 不变量由 before_agent_start 钩子校验(本模块只暴露 assert 方法,钩子接线留给集成)。`,
refs: 'src/extensions/hardware-state.ts:134 replayFromEntries(重放范式)+ :99 makeHwEntry + :312 buildCompactionProtection;src/core/tool-pipeline.ts(深冻结/不变式范式)',
deps: [],
},
{
key: 'T07', layer: 0,
title: 'PbaEventBus + ScopeKey 隔离',
files: ['src/core/pba-event-bus.ts'],
testFile: 'tests/pba-event-bus.test.ts',
contract: `type ScopeKey = string; // branded 语义:用 "a.b.c" 路径式 scope,祖先-后代关系
interface PbaListener { (args: unknown, next: () => void): void; }
class PbaEventBus {
constructor(opts?: { emitter?: { on:(e:string,l:Function)=>(()=>void); emit:(e:string,a:unknown)=>void } }); // 注入 emitter 供单测;默认内存 emitter
on(event: string, listener: PbaListener, scope?: ScopeKey): () => void; // 返回 disposer
off(event: string, listener: PbaListener): void;
emit(event: string, args: unknown, scope?: ScopeKey): void; // 事件向上扩展到祖先 scope(后代监听器收到祖先发的事件?反:scope 匹配键或祖先键的监听器收事件)
waterfall(event: string, args: unknown, scope?: ScopeKey): unknown; // 顺序链:listener 收 (...args, next),调 next() 委托下一个;不调 next 即短路
scopedScope(parent: ScopeKey, child: ScopeKey): ScopeKey; // 拼接
listenerCount(event: string): number;
}
scope 规则:无 scope=全局监听收所有事件;注册时 scope=child,emit scope=child 则 child + 祖先监听器收(注册向下继承、事件向上扩展——子 agent 的事件冒泡到父 scope,父 scope 注册的监听也收)。typed event 名约定(文档化常量数组 KNOWN_EVENTS):verify:passed/build:done/boardlink:connect/glm:empty-output/xcompile:done/pdf-reader:page/debugger:attach/length-recovery:recovered。
纯逻辑,emitter 可注入(无 pi 顶层 import)。`,
spec: `薄封装 pi.events 加 typed event bus。waterfall 链委托(next() 不调=短路)。scope 多 agent 隔离:子 agent 事件不串主 agent(子 scope 的事件冒泡到父,但父 scope emit 不下渗到子——单向冒泡)。21 域迁移留给集成阶段(本模块只提供 bus)。`,
refs: 'src/core/tool-pipeline.ts(waterfall/next 范式 + disposer 范式);src/extensions/index.ts:70 fail-soft 装配',
deps: [],
},
{
key: 'T08', layer: 0,
title: '能力接缝三角色(board-link + flash)',
files: ['src/capabilities/board-link/types.ts', 'src/capabilities/board-link/index.ts', 'src/capabilities/board-link/providers/rdk-x5-ssh.ts', 'src/capabilities/board-link/providers/rdk-s100-serial.ts', 'src/capabilities/board-link/providers/local.ts', 'src/capabilities/flash/types.ts', 'src/capabilities/flash/index.ts', 'src/capabilities/flash/providers/dd.ts', 'src/capabilities/flash/providers/fastboot.ts', 'src/capabilities/flash/providers/dfu.ts', 'src/capabilities/flash/providers/openocd.ts'],
testFile: 'tests/capability-seams.test.ts',
contract: `// board-link
interface BoardLinkProvider { id: string; linkType: BoardLinkType; createExec(board: BoardSpec, underlying: ExecFn): ExecFn; healthCheck?(exec: ExecFn): Promise<{ok:boolean;reason?:string}>; }
class BoardLinkRegistry { register(p: BoardLinkProvider): () => void; resolve(board: BoardSpec): BoardLinkProvider; list(): readonly BoardLinkProvider[]; } // resolve fail-closed:无匹配 provider 抛错
const RDK_X5_SSH_PROVIDER, RDK_S100_SERIAL_PROVIDER, LOCAL_PROVIDER: BoardLinkProvider; // 从 board-link.ts makeExec 抽 ssh/serial-stub/local 三实现
// flash
interface FlashProvider { id: FlashMethod; plan(opts: FlashPlanOptions, ctx?: {lsblk?: LsblkRow[]}): FlashPlanEx; run(plan: FlashPlanEx, exec: ExecFn): Promise<RunFlashResult>; verify(plan: FlashPlanEx, exec: ExecFn): Promise<VerifyResult>; }
class FlashRegistry { register(p: FlashProvider): () => void; resolve(method: FlashMethod): FlashProvider; list(): readonly FlashProvider[]; }
const DD_PROVIDER, FASTBOOT_PROVIDER, DFU_PROVIDER, OPENOCD_PROVIDER: FlashProvider;
BoardSpec(shared/types.ts:98)做 provider 配置。纯逻辑,import type 来自 shared/types + 现有 board-link.ts/flash.ts 的类型(re-export 或 import type)。
❗不删 board-link.ts / flash.ts(仍在 barrel);本模块是新接缝层,provider 逻辑从那两文件抽出来。不修改原扩展文件。`,
spec: `Definition/Provider/Consumer 三角色。board-link 抽 BoardLinkProvider + Registry + 3 provider(rdk-x5-ssh/rdk-s100-serial/local)。flash 同理 4 provider(dd/fastboot/dfu/openocd)。验收:加 RdkS100Provider 后 resolve(S100 board) 无改动可用;register disposer 后 list 不见该 provider。fail-closed resolve。`,
refs: 'src/extensions/board-link.ts:250 makeExec(ssh/serial-stub/local 三分支逻辑搬到 provider)+:380 BoardRegistry(registry 范式)+:507 computeFingerprint;src/extensions/flash.ts:188 planFlash +:630 runFlash +:558 verifyFlash(按 method 分到 4 provider);src/shared/types.ts:75 FlashMethod/FlashPlan',
deps: [],
},
{
key: 'T11', layer: 0,
title: '类型镜像漂移检测',
files: ['tsconfig.realpi.json', 'scripts/type-drift-check.ts'],
testFile: 'tests/type-drift-check.test.ts',
contract: `// tsconfig.realpi.json: extends ./tsconfig.json,paths 覆盖 @earendil-works/pi-coding-agent + pi-ai + pi-agent-core 指向 ../pi/packages/*/src/index.ts(真源码)。include src/ + scripts/。
// scripts/type-drift-check.ts
interface TscResult { exitCode: number; stdout: string; stderr: string; }
function checkTypeDrift(opts: { tsconfigPath?: string; runTsc?: (args: string[]) => TscResult; pbaSrcPattern?: RegExp }): {
driftDetected: boolean;
pbaErrors: string[]; // 命中 src/**/*.ts 的错(真漂移)
piInternalErrors: string[]; // 仅 packages/ 内的错(pi 自家,忽略)
};
默认 runTsc = spawnSync('npx tsc -p <tsconfig> --noEmit')。过滤逻辑:每条 error 行按文件路径分类,src/ 下的进 pbaErrors,packages/ 下的进 piInternalErrors。driftDetected = pbaErrors.length>0。
纯逻辑,runTsc 可注入(单测 mock)。`,
spec: `对真 pi 源码 tsc,检测 src/types/pi.d.ts 镜像漂移。已知 pi 自家 packages/agent/src 报错是 pi build 产物问题,非 pba,过滤掉只看 src/。CI 周期跑。`,
refs: '现有 tsconfig.json(看 paths 结构);src/types/pi.d.ts(被检测的镜像)',
deps: [],
},
{
key: 'T16', layer: 0,
title: '多 LLM provider 适配',
files: ['src/core/provider-registry.ts'],
testFile: 'tests/provider-registry.test.ts',
contract: `interface ProviderDescriptor {
id: string; provider: string; baseUrl: string; apiKeyEnv: string; // key 占位变量名,值走 env,绝不入库
thinkingFormat?: "qwen"|"none"; maxTokens: number; contextWindow: number; reasoning: boolean;
input?: ("text"|"image")[]; cost?: {input:number;output:number;cacheRead:number;cacheWrite:number};
}
function buildProviderConfig(desc: ProviderDescriptor): { name: string; config: ProviderConfig }; // 泛化 glm-provider buildGlmModelConfig+toProviderConfig;thinkingFormat:"qwen" 触发 enable_thinking:false 兼容(THINKING_FORMAT_GATE 思路)
class ProviderRegistry { register(desc: ProviderDescriptor): () => void; resolve(modelId: string): ProviderDescriptor; list(): readonly ProviderDescriptor[]; }
const KNOWN_PROVIDERS: readonly ProviderDescriptor[]; // glm-5.2(默认)+ deepseek-native(stub)
const DEFAULT_GLM_DESCRIPTOR: ProviderDescriptor; // baseUrl=ai-api.d-robotics.cc/v1, apiKeyEnv=DROBOTICS_LLM_KEY, thinkingFormat:"qwen", maxTokens:8192
纯逻辑,ProviderConfig 仅 import type。❗key 全程 \${DROBOTICS_LLM_KEY} 占位,绝不出现 sk- 明文。`,
spec: `换模型改配置行不改扩展。glm-provider 扩展支持多 provider。复用 dsh THINKING_FORMAT_GATE 思路支持 DeepSeek 原生+其他。本模块是新 core lib(不重度改 glm-provider.ts,glm-provider 可后续接进来)。`,
refs: 'src/extensions/glm-provider.ts:81 buildGlmModelConfig +:109 toProviderConfig(泛化这两函数)+:39 GlmCompat(thinkingFormat 范式)',
deps: [],
},
{
key: 'T17', layer: 0,
title: '审批接缝 + credentials/settings + LSP',
files: ['src/capabilities/approval.ts', 'src/capabilities/credentials.ts', 'src/capabilities/settings.ts', 'src/capabilities/lsp.ts'],
testFile: 'tests/capabilities-misc.test.ts',
contract: `// approval.ts —— fail-closed 无人值守审批
type ApprovalMode = "auto-deny" | "auto-approve" | "interactive";
interface ApprovalRequest { action: string; risk: "low"|"medium"|"high"; timeoutMs?: number; context?: string; }
interface ApprovalResult { decision: "approve"|"deny"; reason: string; by: "auto"|"approver"|"timeout"; }
class ApprovalGate {
constructor(opts?: { mode?: ApprovalMode; timeoutMs?: number });
setMode(m: ApprovalMode): void;
registerApprover(fn: (req: ApprovalRequest) => Promise<ApprovalResult>): () => void; // disposer
request(req: ApprovalRequest): Promise<ApprovalResult>; // auto-deny→直接 deny;auto-approve→approve;interactive→调注册的 approver,无 approver→deny(fail-closed),超时→deny
}
// credentials.ts —— 凭据 store,key 永不明文 echo
class CredentialsStore {
get(name: string): string | undefined; // 先 memory 后 process.env[name]
set(name: string, value: string): void; // 仅 memory,不落盘
has(name: string): boolean;
redact(s: string): string; // 把形似 sk-xxx/长 token 的串替换成 <redacted>
}
// settings.ts —— typed settings
class SettingsStore<T extends object = Record<string, unknown>> {
constructor(defaults: T);
get<K extends keyof T>(k: K): T[K];
set<K extends keyof T>(k: K, v: T[K]): void;
snapshot(): Readonly<T>;
}
// lsp.ts —— 嵌入式 IDE 桥(on-demand stub)
interface LspBridge { initialize(opts: {rootUri: string}): Promise<{ok:boolean}>; shutdown(): Promise<void>; }
class NoopLspBridge implements LspBridge; // 默认 no-op 实现(on-demand)
纯逻辑,无 pi import。`,
spec: `按需逐个。approval fail-closed 无人值守。credentials 永不 echo key。settings typed。lsp stub 接口。`,
refs: 'src/extensions/safety-gate.ts(fail-closed + hardGate 范式);src/core/sandbox-policy.ts(fail-closed unusable→拒绝 范式)',
deps: [],
},
// ═══════════════════════ LAYER 1 ═══════════════════════
{
key: 'T09', layer: 1,
title: 'compaction 完整工程',
files: ['src/compaction/token-meter.ts', 'src/compaction/tool-result-pruner.ts', 'src/compaction/summarizer.ts', 'src/compaction/spill.ts'],
testFile: 'tests/compaction.test.ts',
contract: `// token-meter.ts
function estimateTokens(text: string): number; // chars/4 启发 + 中文按 char 计
function measureContext(messages: ReadonlyArray<{role:string;content:string}>): number;
// tool-result-pruner.ts
interface PruneOptions { tool: "i2cdump"|"gdb"|"dmesg"|"general"; maxLines?: number; }
interface PruneResult { pruned: string; dropped: number; preservedAddrs?: string[]; }
function pruneToolResult(content: string, opts: PruneOptions): PruneResult; // i2cdump 保留寄存器地址行(0xXX: 格式)+ 最后 dump 行;gdb 保留 #frame 行;dmesg 保留 error/critical/warn 行;general 截断 maxLines
// summarizer.ts
interface CompactionSummary { summary: string; reusedPrefix: boolean; droppedEntries: number; }
function buildCompactionSummary(opts: { prefix: string; recentEntries: ReadonlyArray<{type:string;data:unknown}>; maxTokens: number }): CompactionSummary; // 重放前缀 + append 压缩指令,标记 reusedPrefix(复用 KV prefix cache 语义)
// spill.ts
type SpillLocator = string & { readonly __brand: "SpillLocator" };
class SpillStore {
spill(key: string, data: unknown): SpillLocator; // 大结果溢出,返 branded 句柄
recall(locator: SpillLocator): unknown; // 取回
has(locator: SpillLocator): boolean;
evict(olderThanBytes?: number): number; // 容量回收
}
纯逻辑。import type 来自 ../core/pba-session.js(surface replace op 类型,T06 实际产出)。`,
spec: `compaction 完整:tokenMeter 压力触发 + tool-result prune(i2cdump/gdb/dmesg 大输出 model-free 压缩)+ spill(datasheet 大结果句柄)。验收:压力触发 summarize 标 reusedPrefix;i2cdump prune 寄存器地址不丢;spill 句柄可 recall。`,
refs: 'src/extensions/hardware-state.ts:295 buildCompactionProtection(compaction 保护范式);src/core/pba-session.ts(T06 产出,import type)',
deps: ['T06'],
},
{
key: 'T13', layer: 1,
title: '上下文注入三段(inject/steer/followup)',
files: ['src/core/context-injector.ts'],
testFile: 'tests/context-injector.test.ts',
contract: `type InjectionPhase = "inject" | "steer" | "followup";
interface Injection { phase: InjectionPhase; content: string; boardId?: string; nextStep: boolean; nextTurn: boolean; replacesSnapshot?: string; }
class ContextInjector {
inject(content: string): Injection; // 寄存器表 next-step,NO wake(nextStep=true 但不触发)
steer(content: string, boardId?: string): Injection; // 换板 next-step 唤醒
followup(content: string): Injection; // 新任务 next-turn 唤醒
snapshot(): { content: string; boardId?: string; ts: number }; // runtime-context 快照,取代更早快照
deriveActiveContext(): { injections: Injection[]; active: Injection | null }; // 最新 snapshot 取代更早
clear(phase?: InjectionPhase): void;
}
纯逻辑。import type 来自 ../core/pba-session.js(可选)。`,
spec: `inject(寄存器表 next-step 不唤醒)/steer(换板 next-step 唤醒)/followup(新任务 next-turn 唤醒)三段语义区分。runtime-context 快照"取代更早快照"。`,
refs: 'src/core/pba-session.ts(T06);src/extensions/env-probe.ts(注入范式参考)',
deps: ['T06', 'T07'],
},
{
key: 'T14', layer: 1,
title: 'plan/goal/todo logged state',
files: ['src/core/checkpoint-state.ts'],
testFile: 'tests/checkpoint-state.test.ts',
contract: `class CheckpointRecorder {
constructor(opts: { append: (entry: {type:string;data:unknown}) => void }); // 注入 PbaSession.append 或独立 append
record(step: CheckpointStep, passed: boolean, timestamp: number): void; // 写进 session 事件(type="checkpoint-change")
current(): CheckpointState; // 读当前
rebuild(entries: ReadonlyArray<{type:string;data:unknown}>): CheckpointState; // resume 从 log 重建
fork(): CheckpointRecorder; // 从当前 fork(子任务)
}
CheckpointState(shared/types.ts:45 已存在:currentStep/stepPassed/history)。CheckpointStep(:43 已存在)。
纯逻辑,append 注入。`,
spec: `checkpoint 进度写进 PbaSession 事件,resume/fork 从 log 重建。验收:session resume 后 checkpoint 状态从 log 重建。`,
refs: 'src/shared/types.ts:43 CheckpointStep +:45 CheckpointState(已存在,直接用);src/extensions/loop-orchestrator.ts(checkpoint 范式);src/core/pba-session.ts(T06 append)',
deps: ['T06'],
},
{
key: 'T15', layer: 1,
title: 'profile/bundle 分层',
files: ['src/profiles/base.ts', 'src/profiles/repair-diagnosis.ts', 'src/profiles/embedded-dev.ts', 'src/profiles/index.ts'],
testFile: 'tests/profiles.test.ts',
contract: `interface Profile { id: string; extensions: readonly string[]; tools: readonly string[]; note?: string; }
const BASE_PROFILE: Profile; // 共享 base(safety-gate/glm-provider/persistent-shell/edit-length-recovery/subprocess-isolation/env-probe/mcp-bridge/server-runtime/hardware-state 等公共)
const REPAIR_DIAGNOSIS_PROFILE: Profile; // base + pdf-reader/datasheet-rag/peripheral-probe(维修诊断要的)
const EMBEDDED_DEV_PROFILE: Profile; // base + cross-compile/flash/jtag-debugger/device-tree/board-link/reg-tool(嵌入式开发要的)
function resolveProfile(id: string): Profile; // fail-closed:未知 id 抛错
function mergeProfiles(base: Profile, delta: Pick<Profile,"extensions"|"tools">): Profile; // 共享 base + 叠差异
function diffProfiles(a: Profile, b: Profile): {added:string[];removed:string[]};
纯逻辑。`,
spec: `维修诊断 profile vs 嵌入式开发 profile,共享 base + 叠差异。验收:两 profile 共享 base,各叠差异扩展。`,
refs: 'src/extensions/index.ts:39 extensionFactories(21 域名清单,照此选 extensions/tools 名)',
deps: ['T08'],
},
{
key: 'T12', layer: 1,
title: '子代理 + 工作流编排',
files: ['src/capabilities/subagent/index.ts', 'src/capabilities/workflow/index.ts'],
testFile: 'tests/workflow.test.ts',
contract: `// subagent
interface SubagentResult { ok: boolean; value?: unknown; error?: string; scope: string; }
interface SubagentProvider { spawn(prompt: string, opts?: {scope?: string; timeoutMs?: number}): Promise<SubagentResult>; }
class InlineSubagentProvider implements SubagentProvider { // spawn-in-process:跑一个注入的 handler 函数(构造器收 (prompt,opts)=>Promise<unknown>)
constructor(handler: (prompt: string, opts?: {scope?:string}) => Promise<unknown>);
spawn(...): Promise<SubagentResult>; // scope 隔离:子 agent 事件不串主 agent(靠 ScopeKey,import type 自 T07)
}
class SubagentRegistry { register(p: SubagentProvider): ()=>void; resolve(id: string): SubagentProvider; }
// workflow
function parallel(thunks: ReadonlyArray<() => Promise<unknown>>): Promise<unknown[]>; // barrier:全等齐,单 thunk 抛错→该位 null(不 reject)
function pipeline<T>(items: ReadonlyArray<T>, ...stages: Array<(prev: unknown, item: T, i: number) => Promise<unknown>>): Promise<unknown[]>; // 每 item 过全 stage,stage 间无 barrier;stage 抛错→item 落 null 跳后续
function phase(name: string): void; // 标记进度(no-op,仅记录)
const MAX_CONCURRENCY = 8;
纯逻辑。`,
spec: `loop-orchestrator 上层加 workflow:parallel(编译+探板+datasheet 三并发)/ pipeline(edit→compile→flash→verify 串行)。子 agent 事件不串主 agent。验收:parallel 三任务并发;pipeline 串行 stage 抛错 item 落 null。`,
refs: 'src/core/pba-event-bus.ts(T07 ScopeKey 隔离);src/extensions/loop-orchestrator.ts(闭环编排范式)',
deps: ['T07', 'T08'],
},
{
key: 'T10', layer: 1,
title: 'CI 质量门 + snapshot + doc-sync',
files: ['.github/workflows/ci.yml', 'scripts/e2e-snapshot.ts', 'scripts/doc-sync.ts'],
testFile: 'tests/doc-sync.test.ts',
contract: `// scripts/doc-sync.ts —— 校验架构文档锚点 file:line 与代码对齐
interface DocAnchor { docFile: string; docLine: number; codeFile: string; codeSymbol: string; }
function checkDocSync(opts: { readFile: (p: string) => string; anchors: readonly DocAnchor[]; grepSymbol: (file: string, symbol: string) => number; }): { ok: boolean; mismatches: Array<{anchor: DocAnchor; reason: string}> };
// scripts/e2e-snapshot.ts —— 闭环 snapshot 回归对比(结构化)
interface SnapshotDiff { match: boolean; added: string[]; removed: string[]; changed: string[]; }
function compareSnapshot(actual: unknown, baseline: unknown): SnapshotDiff;
// .github/workflows/ci.yml —— test:coverage per-file 门 + doc-sync + type-drift-check(调 T11 的 scripts/type-drift-check.ts)
纯逻辑(readFile/grepSymbol 注入)。type-drift-check.ts 由 T11 拥有,本模块只在 ci.yml 里调它。`,
spec: `CI per-file 100% 覆盖门 + snapshot 漂移红 + doc-sync 锚点不一致红 + 类型漂移红。验收:doc-sync 锚点 file:line 与代码不符→红。`,
refs: 'scripts/type-drift-check.ts(T11 产出,ci.yml 调用);架构设计文档_v3.md(doc-sync 校验对象)',
deps: ['T11'],
},
];
// ───────────────────────── prompt builders ─────────────────────────
function devPrompt(m) {
return [
`你是 physical_byte_agent 项目模块 ${m.key}(${m.title})的【开发 Agent】。项目目录:${DIR}`,
``,
`【目标】用最优雅的架构、最干净的代码实现本模块。禁止任何临时性妥协代码、禁止 bad smell(god object、隐式全局、魔法串、未处理边界、深嵌套、命名含糊)。纯逻辑、依赖可注入、JSDoc 注释(中文模块头 + 每导出 @param/@returns)。遵循现有风格:见 src/core/tool-pipeline.ts、src/core/sandbox-policy.ts、src/extensions/hardware-state.ts(命名导出 + 顶层仅 import type + 逻辑内联 + 深冻结常量 + fail-closed)。`,
``,
`【独占文件——只创建/修改这些文件,严禁触碰任何其他文件(尤其 src/extensions/index.ts 不许动)】`,
m.files.map((f) => ' - ' + f).join('\n'),
``,
`【契约——必须精确产出这些导出与签名,下游模块依赖这些名字,不得擅自改名】`,
m.contract,
``,
`【SPEC】`,
m.spec,
``,
`【参考文件(读这些学范式,勿盲抄)】`,
m.refs,
...(m.deps.length ? [``, `【依赖模块已落地(Layer0 已完成)——读它们真实的导出再写 import,若实际导出名与契约不符以实际为准自适应】` + m.deps.join(', ')] : []),
``,
`【密钥铁律】gateway key 一律用 \${DROBOTICS_LLM_KEY} 占位,绝不出现 sk- 开头明文,绝不写进 git-tr踪文件。`,
``,
`【自检门——返回前必须过】`,
`1. 写一个最小冒烟测试 ${m.testFile}(3-6 用例:happy path + 一个边界 + 一个不变式),用 npx vitest 跑:`,
` cd ${DIR} && npx vitest run ${m.testFile} # 必须 all green`,
` 测试直接 import 你的命名导出,mock 注入依赖,无 pi 运行时无硬件。`,
`2. 确认你的文件顶层无 pi 运行时 import(仅 import type),以保离线可测。`,
`3. 违反独占文件/触碰 barrel/明文 key 一律算失败。`,
``,
`返回 DEV_SCHEMA(module=${m.key},列出 files/exports/smokeTestCount/vitestGreen/notes)。`,
].join('\n');
}
function testPrompt(m) {
return [
`你是 physical_byte_agent 项目模块 ${m.key}(${m.title})的【测试 Agent】。项目目录:${DIR}`,
``,
`【目标】为该模块的命名导出写一套严谨、多方法论、测试前置的测试套件。测试要严到植入的 bug 活不过。`,
``,
`【测试文件——只写这一个,是你的独占】`,
` ${m.testFile}`,
`先读开发 Agent 写的冒烟测试(如有),然后 REPLACE 成完整套件。`,
``,
`【被测对象】读 ${m.files.join(' / ')} 的命名导出(按契约)。直接 import,mock 注入依赖(appendEntry/exec/emitter/runTsc/readFile 等),无 pi 运行时无硬件无网络。`,
``,
`【必须应用的多测试方法论(每个 describe 块标注方法论名)】`,
`- 等价类划分(有效/无效/边界类)`,
`- 边界值分析(off-by-one、空、单元素、max、min)`,
`- 决策表(组合输入→期望,覆盖全分支)`,
`- 状态转换(若有状态:状态+迁移+不可达状态+重入)`,
`- 变异测试:至少植入 3 个 seeded bug(例:< 改 <=、off-by-one、错默认值、漏 freeze、漏 seq 校验、短路逻辑反),在测试内联一份带 bug 的逻辑副本/包装器,断言每个 bug 被【某条测试】杀死(植入后该测试失败=bug 被杀)。文档化每个植入 bug + 杀它的测试。最后确认真实(未植入 bug)代码全过。`,
`- 对抗/fuzz:畸形/滥用输入(null、undefined、巨大、NaN、循环引用、并发重入、负 seq)`,
`- 元蜕变/不变式:跨变换保持的性质(append 两次=replay 等价;freeze→篡改抛 TypeError;单调 deny;waterfall 不调 next=短路;fail-closed unusable=拒)`,
``,
`【门】`,
`1. cd ${DIR} && npx vitest run ${m.testFile} # 真实代码必须 all green`,
`2. 每个植入 bug 变体单独跑,确认它 FAIL(bug 被杀)。`,
``,
`若发现开发代码的真实 bug(非植入),列入 findings[](file+line+severity+failureScenario),【不要自己改】——留给 fix 阶段的开发 Agent。`,
`返回 TEST_SCHEMA(module=${m.key})。`,
].join('\n');
}
function fixPrompt(m, test) {
return [
`你是 physical_byte_agent 项目模块 ${m.key}(${m.title})的【修复 Agent】。项目目录:${DIR}`,
``,
`测试 Agent 报告:allGreen=${test.allGreen}, testCount=${test.testCount}, mutationKilled=${test.mutationKilled}/${test.mutationBugsPlanted}`,
`findings:`,
JSON.stringify(test.findings, null, 2),
``,
`【任务】逐条修复 findings 在你的独占文件里:`,
m.files.map((f) => ' - ' + f).join('\n'),
`严禁触碰其他文件。遵循现有风格 + JSDoc。密钥占位 \${DROBOTICS_LLM_KEY}。`,
``,
`【门】cd ${DIR} && npx vitest run ${m.testFile} # 必须 all green 后再返回`,
`返回 DEV_SCHEMA(module=${m.key})。`,
].join('\n');
}
// ───────────────────────── pipeline stages ─────────────────────────
async function devStage(m) {
return agent(devPrompt(m), { schema: DEV_SCHEMA, phase: m.layer === 0 ? 'Layer0' : 'Layer1', label: `dev:${m.key}` });
}
async function testStage(_dev, m) {
return agent(testPrompt(m), { schema: TEST_SCHEMA, phase: m.layer === 0 ? 'Layer0' : 'Layer1', label: `test:${m.key}` });
}
async function fixStage(test, m) {
let cur = test;
let attempts = 0;
const MAX = 3;
while (cur && (!cur.allGreen || (cur.findings && cur.findings.length > 0)) && attempts < MAX) {
attempts++;
await agent(fixPrompt(m, cur), { schema: DEV_SCHEMA, phase: m.layer === 0 ? 'Layer0' : 'Layer1', label: `fix:${m.key}#${attempts}` });
cur = await agent(testPrompt(m), { schema: TEST_SCHEMA, phase: m.layer === 0 ? 'Layer0' : 'Layer1', label: `retest:${m.key}#${attempts}` });
}
return { module: m.key, title: m.title, test: cur, fixAttempts: attempts, files: m.files };
}
// ───────────────────────── run ─────────────────────────
const layer0 = MODULES.filter((m) => m.layer === 0);
const layer1 = MODULES.filter((m) => m.layer === 1);
phase('Layer0');
log(`Layer0 并行:${layer0.map((m) => m.key).join(',')}(每模块 dev→test→fix≤3)`);
const l0 = await parallel(
layer0.map((m) => () =>
pipeline([m], (mod) => devStage(mod), (dev, mod) => testStage(dev, mod), (test, mod) => fixStage(test, mod)).then((r) => r[0])
)
);
const l0r = l0.filter(Boolean);
log(`Layer0 完成:${l0r.length}/${layer0.length} 模块。绿:${l0r.filter((r) => r.test && r.test.allGreen && (!r.test.findings || !r.test.findings.length)).length}`);
phase('Layer1');
log(`Layer1 并行(依赖 Layer0 已落盘):${layer1.map((m) => m.key).join(',')}`);
const l1 = await parallel(
layer1.map((m) => () =>
pipeline([m], (mod) => devStage(mod), (dev, mod) => testStage(dev, mod), (test, mod) => fixStage(test, mod)).then((r) => r[0])
)
);
const l1r = l1.filter(Boolean);
log(`Layer1 完成:${l1r.length}/${layer1.length} 模块。绿:${l1r.filter((r) => r.test && r.test.allGreen && (!r.test.findings || !r.test.findings.length)).length}`);
return {
layer0: l0r.map((r) => ({ module: r.module, allGreen: r.test?.allGreen, testCount: r.test?.testCount, findings: r.test?.findings?.length ?? 0, fixAttempts: r.fixAttempts })),
layer1: l1r.map((r) => ({ module: r.module, allGreen: r.test?.allGreen, testCount: r.test?.testCount, findings: r.test?.findings?.length ?? 0, fixAttempts: r.fixAttempts })),
};

199
scripts/type-drift-check.ts Normal file
View File

@ -0,0 +1,199 @@
/**
* @module type-drift-check
*
* 类型镜像漂移检测(T11)—— 对真 pi 源码跑 tsc --noEmit,检测
* src/types/pi.d.ts 镜像是否与真 pi 扩展 API 面漂移。
*
* 为什么需要:pba 在 src/types/pi.d.ts 维护了一份 pi 扩展 API 的类型镜像
* (离线 tsc 用),pi 升级 API 后镜像可能过时。本模块用 tsconfig.realpi.json
* (paths 覆盖为真 pi 源码 ../pi/packages 下的 index.ts)跑 tsc,把报错按
* 文件路径分类:
* - src/ 下的错 → pbaErrors(真漂移——镜像与真 pi 不一致,需修镜像)
* - packages/ 下的错 → piInternalErrors(pi 自家 build 产物问题,非 pba,忽略)
*
* 正交阶段(单一职责,确定性可测):
* extractErrorPath(纯解析:一行 tsc 输出 → 文件路径 | null)
* → checkTypeDrift(分类 + fail-closed 兜底)
*
* 纯逻辑 + runTsc 可注入(单测 mock),零 pi 运行时依赖,可离线单测。
* CI 周期跑(非每次提交)。见架构设计文档_v3.md §type-drift。
*/
import { spawnSync } from "node:child_process";
// ============================================================================
// 命名常量 —— 消灭魔法串
// ============================================================================
/** 默认 tsconfig 路径(paths 指向真 pi 源码的覆盖配置)。 */
const DEFAULT_TSCONFIG_PATH = "tsconfig.realpi.json";
/**
* pba 源码路径匹配模式。tsc 报错文件路径以此开头即为 pba 自身代码的错(真漂移)。
* 默认匹配 src/ 下所有文件(tsc 只对 .ts/.tsx/.d.ts 报错,无需额外过滤扩展名)。
*/
const DEFAULT_PBA_SRC_PATTERN = /^src\//;
/** pi 自家源码路径匹配模式。报错文件路径含此片段即为 pi 内部错(忽略)。 */
const PI_INTERNAL_PATTERN = /packages\//;
/**
* tsc 报错行路径提取正则。
*
* 匹配两种 tsc 输出格式(捕获组 1 = 文件路径,行/列标记之前的部分):
* - 非 pretty(CI 默认):src/foo.ts(23,5): error TS2322: msg
* - pretty(TTY): src/foo.ts:23:5 - error TS2322: msg
*
* 非贪婪 `(.+?)` 保证只取行/列标记之前的路径段;Unix 路径无冒号,首段 `:` 即
* pretty 格式的 `:line:col` 分隔,不会误截路径内部。
*/
const TSC_ERROR_PATH_RE = /^(.+?)(?:\(\d+,\d+\)|:\d+:\d+)/;
/** tsc 错误码标记(用于判定一行是否为 tsc 报错行)。 */
const TSC_ERROR_MARKER = /error\s+TS\d+:/;
// ============================================================================
// 类型契约
// ============================================================================
/** tsc 执行结果。 */
export interface TscResult {
/** 进程退出码(0=无错,非 0=有错或执行失败;-1=进程未正常退出)。 */
readonly exitCode: number;
/** 标准输出(tsc 报错默认走 stdout)。 */
readonly stdout: string;
/** 标准错误(tsc 启动失败 / spawn 错误走 stderr)。 */
readonly stderr: string;
}
/** 类型漂移检测结果。 */
export interface TypeDriftResult {
/** 是否检测到真漂移(pbaErrors 非空即 true)。 */
readonly driftDetected: boolean;
/** 命中 src/ 下文件的 tsc 报错行(真漂移——镜像与真 pi 不一致)。 */
readonly pbaErrors: readonly string[];
/** 仅 packages/ 下文件的 tsc 报错行(pi 自家问题,忽略)。 */
readonly piInternalErrors: readonly string[];
}
/** tsc 执行器抽象(注入以便单测 mock,避免真 spawn)。 */
export type TscRunner = (args: string[]) => TscResult;
// ============================================================================
// extractErrorPath —— 纯解析(导出供测试 + 调用方诊断)
// ============================================================================
/**
* 从一行 tsc 输出中提取报错文件路径。
*
* 匹配两种 tsc 格式(见 {@link TSC_ERROR_PATH_RE}):
* - 非 pretty:src/foo.ts(23,5): error TS2322: msg → "src/foo.ts"
* - pretty: src/foo.ts:23:5 - error TS2322: msg → "src/foo.ts"
*
* 非报错行(不含 `error TSxxxx:`)返回 null,不误分类上下文行或摘要行。
*
* @param line tsc 输出的一行。
* @returns 文件路径,或 null(非报错行)。
*/
export function extractErrorPath(line: string): string | null {
if (!TSC_ERROR_MARKER.test(line)) return null;
const match = line.match(TSC_ERROR_PATH_RE);
return match ? match[1].trim() : null;
}
// ============================================================================
// defaultRunTsc —— 默认 tsc 执行器(注入以便单测 mock)
// ============================================================================
/**
* 默认 tsc 执行器:同步 spawn `npx tsc <args>`。
*
* fail-tolerant:spawn 失败(npx 未安装、PATH 缺失等)时 exitCode=-1、
* stderr 含 spawn 错误信息,由 {@link checkTypeDrift} 的 fail-closed 兜底。
*
* @param args 传给 tsc 的参数(如 ["-p", "tsconfig.realpi.json", "--noEmit"])。
* @returns tsc 执行结果。
*/
export const defaultRunTsc: TscRunner = (args) => {
const res = spawnSync("npx", ["tsc", ...args], { encoding: "utf8" });
const stderr = res.stderr ?? "";
const spawnErr = res.error?.message ?? "";
return {
exitCode: res.status ?? -1,
stdout: res.stdout ?? "",
stderr: stderr || spawnErr,
};
};
// ============================================================================
// checkTypeDrift —— 主入口
// ============================================================================
/**
* 对真 pi 源码跑 tsc --noEmit,检测 src/types/pi.d.ts 镜像漂移。
*
* 执行流程:
* 1. 构造 tsc 参数 `["-p", tsconfigPath, "--noEmit"]`(默认 tsconfig.realpi.json)
* 2. 调 `runTsc`(默认 `npx tsc`,可注入 mock)
* 3. 逐行解析 tsc 输出(stdout + stderr),按文件路径分类报错:
* - 匹配 `pbaSrcPattern`(默认 `^src/`)→ pbaErrors(真漂移)
* - 匹配 `packages/` → piInternalErrors(pi 自家,忽略)
* - 既非 src/ 亦非 packages/(如 scripts/)→ pbaErrors(fail-closed)
*
* fail-closed(安全不变式):
* - tsc 退出码非 0 但无可解析报错(如 npx 崩溃、tsconfig 不存在)→
* 将原始 stderr 推入 pbaErrors,driftDetected=true
* (无法确认无漂移即视为有漂移,安全默认)。
*
* 纯逻辑、runTsc 可注入、无 pi 运行时依赖、确定性可测。
*
* @param opts.tsconfigPath tsconfig 路径(默认 "tsconfig.realpi.json")。
* @param opts.runTsc tsc 执行器(默认 spawnSync npx tsc;单测注入 mock)。
* @param opts.pbaSrcPattern pba 源码路径匹配正则(默认 `/^src\//`)。
* @returns 漂移检测结果。
*/
export function checkTypeDrift(opts: {
tsconfigPath?: string;
runTsc?: TscRunner;
pbaSrcPattern?: RegExp;
}): TypeDriftResult {
const tsconfigPath = opts.tsconfigPath ?? DEFAULT_TSCONFIG_PATH;
const pbaSrcPattern = opts.pbaSrcPattern ?? DEFAULT_PBA_SRC_PATTERN;
const runTsc = opts.runTsc ?? defaultRunTsc;
const args = ["-p", tsconfigPath, "--noEmit"];
const result = runTsc(args);
// 合并 stdout + stderr(tsc 报错默认走 stdout,但启动失败走 stderr)
const output = [result.stdout, result.stderr].filter(Boolean).join("\n");
const lines = output.split("\n");
const pbaErrors: string[] = [];
const piInternalErrors: string[] = [];
for (const line of lines) {
const path = extractErrorPath(line);
if (path === null) continue;
if (pbaSrcPattern.test(path)) {
pbaErrors.push(line);
} else if (PI_INTERNAL_PATTERN.test(path)) {
piInternalErrors.push(line);
} else {
// 既非 src/ 亦非 packages/(如 scripts/)—— fail-closed:视为 pba 漂移
pbaErrors.push(line);
}
}
// fail-closed:tsc 非零退出但无可解析报错 → 工具失败,无法确认无漂移
if (result.exitCode !== 0 && pbaErrors.length === 0 && piInternalErrors.length === 0) {
const raw = result.stderr.trim() || result.stdout.trim() || "(no output)";
pbaErrors.push(`tsc exited ${result.exitCode} with no parseable errors: ${raw}`);
}
return {
driftDetected: pbaErrors.length > 0,
pbaErrors,
piInternalErrors,
};
}

View File

@ -0,0 +1,184 @@
/**
* @module approval
*
* 无人值守审批门 —— 物理字节 Agent 的风险动作裁决层。
*
* 嵌入式开发场景里 agent 会发起高风险动作(烧录、dd、devmem 写寄存器)。
* 无人值守(CI / 夜跑)时必须有 fail-closed 默认:无审批者即拒,绝不放行。
*
* 三模式(ApprovalMode):
* - "auto-deny" —— 默认 fail-closed,所有请求直接拒(无人值守默认)
* - "auto-approve" —— 全部放行(仅受信任的隔离沙箱用,非默认)
* - "interactive" —— 委托注册的审批者;无审批者 → deny(fail-closed);超时 → deny
*
* 设计要点:
* - 纯逻辑 + 异步,零 pi 依赖,可离线单测。
* - registerApprover 返回 disposer,可注销(session 结束清理);后注册者覆盖前者,
* disposer 只摘除自己(不误摘后来注册者)。
* - 超时用 Promise.race,计时器在 finally 必 clear,防事件循环悬挂。
* - 审批者抛错 → deny(fail-closed,绝不因审批者故障放行)。
* - 未知 mode 一律按 auto-deny 处理(fail-closed 兜底)。
*
* 见 src/extensions/safety-gate.ts 的 fail-closed 范式、src/core/sandbox-policy.ts
* 的 unusable→拒绝 范式。本模块是它们之上的"人类审批"裁决层。
*/
// ============================================================================
// 命名常量 —— 消灭魔法串
// ============================================================================
/** 默认审批模式:fail-closed 无人值守。 */
export const DEFAULT_APPROVAL_MODE: ApprovalMode = "auto-deny";
/** 默认超时(ms):interactive 模式无显式 timeoutMs 时的兜底。 */
const DEFAULT_TIMEOUT_MS = 10_000;
// ============================================================================
// 类型契约 —— 下游依赖这些名字,不得改名
// ============================================================================
/** 审批模式。 */
export type ApprovalMode = "auto-deny" | "auto-approve" | "interactive";
/** 一次风险动作的审批请求。 */
export interface ApprovalRequest {
/** 动作名(如 "flash" / "devmem-write")。 */
action: string;
/** 风险等级。 */
risk: "low" | "medium" | "high";
/** 覆盖默认超时(ms);仅 interactive 模式生效。 */
timeoutMs?: number;
/** 可选上下文(命令串 / 目标 / 原因)。 */
context?: string;
}
/** 审批裁决。 */
export interface ApprovalResult {
/** 决定。 */
decision: "approve" | "deny";
/** 原因(诊断/审计用)。 */
reason: string;
/** 裁决来源:auto=模式自动 / approver=注册审批者 / timeout=超时 fail-closed。 */
by: "auto" | "approver" | "timeout";
}
/** 审批者签名:接收请求,返回裁决。 */
export type ApproverFn = (req: ApprovalRequest) => Promise<ApprovalResult>;
// ============================================================================
// ApprovalGate —— fail-closed 审批门
// ============================================================================
/**
* 审批门。fail-closed 无人值守:
* - auto-deny → 直接 deny(by "auto")
* - auto-approve → approve(by "auto")
* - interactive → 调注册的 approver;无 approver → deny;approver 抛错 → deny;超时 → deny
*
* @example
* const gate = new ApprovalGate({ mode: "interactive" });
* gate.registerApprover(async (req) => ({ decision: "approve", reason: "ok", by: "approver" }));
* const r = await gate.request({ action: "flash", risk: "high" });
*/
export class ApprovalGate {
private mode: ApprovalMode;
private readonly timeoutMs: number | undefined;
private approver: ApproverFn | undefined;
/**
* @param opts.mode 审批模式,默认 "auto-deny"(fail-closed)。
* @param opts.timeoutMs interactive 模式默认超时;缺省用 DEFAULT_TIMEOUT_MS。
*/
constructor(opts?: { mode?: ApprovalMode; timeoutMs?: number }) {
this.mode = opts?.mode ?? DEFAULT_APPROVAL_MODE;
this.timeoutMs = opts?.timeoutMs;
}
/** 切换审批模式。 */
setMode(m: ApprovalMode): void {
this.mode = m;
}
/**
* 注册审批者。返回 disposer:调用即注销(仅摘除自己,不误摘后来注册者)。
*
* @param fn 审批者函数。
* @returns 注销函数。
*/
registerApprover(fn: ApproverFn): () => void {
this.approver = fn;
return () => {
// 仅当仍是本 fn 时摘除,避免误摘后来注册者
if (this.approver === fn) this.approver = undefined;
};
}
/**
* 请求审批。fail-closed 决策:
* - 非 auto-approve / 非 interactive(含 auto-deny 与未知)→ deny by "auto"
* - auto-approve → approve by "auto"
* - interactive + 无 approver → deny by "auto"(fail-closed)
* - interactive + approver:race 超时;approver 抛错 → deny;approver 正常 → 其裁决
*
* 超时优先级:req.timeoutMs > 构造 timeoutMs > DEFAULT_TIMEOUT_MS。
*
* @param req 审批请求。
* @returns 审批裁决。
*/
async request(req: ApprovalRequest): Promise<ApprovalResult> {
// fail-closed 兜底:非 auto-approve / 非 interactive → deny(含 auto-deny 与未知)
if (this.mode !== "auto-approve" && this.mode !== "interactive") {
return {
decision: "deny",
reason: `mode "${this.mode}" → auto-deny`,
by: "auto",
} satisfies ApprovalResult;
}
if (this.mode === "auto-approve") {
return {
decision: "approve",
reason: "auto-approve mode",
by: "auto",
} satisfies ApprovalResult;
}
// interactive
const approver = this.approver;
if (approver === undefined) {
return {
decision: "deny",
reason: "no approver registered (fail-closed)",
by: "auto",
} satisfies ApprovalResult;
}
const timeoutMs = req.timeoutMs ?? this.timeoutMs ?? DEFAULT_TIMEOUT_MS;
let timer: ReturnType<typeof setTimeout> | undefined;
const timeoutP = new Promise<ApprovalResult>((resolve) => {
timer = setTimeout(
() =>
resolve({
decision: "deny",
reason: `approval timed out after ${timeoutMs}ms`,
by: "timeout",
} satisfies ApprovalResult),
timeoutMs,
);
});
try {
return await Promise.race([
approver(req).catch(
(e: unknown): ApprovalResult => ({
decision: "deny",
reason: `approver threw: ${String(e)}`,
by: "auto",
}),
),
timeoutP,
]);
} finally {
// 计时器务必 clear,防事件循环悬挂(即使 approver 先 resolve)
if (timer !== undefined) clearTimeout(timer);
}
}
}

View File

@ -0,0 +1,170 @@
/**
* @module capabilities/board-link
*
* 板链路能力接缝入口 —— Definition/Provider/Consumer 三角色之 Consumer 层。
*
* BoardLinkRegistry:register provider(返回 disposer)→ resolve(board)(按 linkType
* 匹配 provider,fail-closed 无匹配抛错)→ list(只读快照)。
*
* 验收不变式(见 tests/capability-seams.test.ts):
* ① register RDK_S100_SERIAL_PROVIDER 后 resolve(serial board) 无改动可用
* ② register disposer 调用后 list 不见该 provider
* ③ resolve 无匹配 provider → 抛错(fail-closed)
*
* 纯逻辑,零 pi 运行时依赖。顶层仅 `import type`(esbuild 擦除)+ 同模块纯值导入,
* tests 直接 import 命名导出离线可测。
*
* 见 Docs/T08_能力接缝三角色.md。
*/
import type { BoardSpec, BoardLinkType } from "../../shared/types.js";
import type { BoardLinkProvider } from "./types.js";
// 三个 provider 是纯值(BoardLinkProvider 实例),不含 pi 运行时依赖,可值导入。
import { RDK_X5_SSH_PROVIDER } from "./providers/rdk-x5-ssh.js";
import { RDK_S100_SERIAL_PROVIDER } from "./providers/rdk-s100-serial.js";
import { LOCAL_PROVIDER } from "./providers/local.js";
// 类型 + 共享健康检查 re-export(调用方一次性 import)
export type {
BoardLinkProvider,
BoardLinkHealthResult,
BoardSpec,
BoardLinkType,
ExecFn,
ExecResult,
} from "./types.js";
export { defaultBoardHealthCheck } from "./types.js";
// provider 地址解析工具 re-export(调用方诊断/日志用)
export {
parseSshAddress,
buildSshArgs,
type SshTarget,
} from "./providers/rdk-x5-ssh.js";
export {
parseSerialAddress,
SERIAL_STUB_RESULT,
type SerialTarget,
} from "./providers/rdk-s100-serial.js";
// ============================================================================
// BoardLinkRegistry
// ============================================================================
/**
* 板链路 Provider 注册表。
*
* - register(p): 按 p.id 存储,返回 disposer(调用后从注册表移除)。
* disposer 只移除"仍是同一个 provider 实例"的条目——避免后注册的同 id provider
* 被前者的 disposer 误删(override 安全)。
* - resolve(board): 按 board.linkType 匹配 provider,fail-closed 无匹配抛错。
* - list(): 只读快照(调用方不可篡改内部状态)。
*
* 与 BoardRegistry(板注册表)的区别:BoardRegistry 管理"板实例"(BoardSpec),
* 本注册表管理"链路 provider"(BoardLinkProvider)。一板一链路类型,一链路类型一 provider。
*/
export class BoardLinkRegistry {
/** id → provider(插入序,Map 保证)。 */
private readonly providers = new Map<string, BoardLinkProvider>();
/**
* 注册一个 provider。id 唯一:重复 id 视为更新(替换),保证 barrel
* 重装配(测试多次装配 / session resume)幂等安全。返回 disposer。
*
* @param provider 板链路 provider。
* @returns disposer——调用后从注册表移除该 provider(仅当仍是同一实例时移除)。
*/
register(provider: BoardLinkProvider): () => void {
this.providers.set(provider.id, provider);
return () => {
if (this.providers.get(provider.id) === provider) {
this.providers.delete(provider.id);
}
};
}
/**
* 按板规格解析 provider(按 linkType 匹配)。
*
* fail-closed:无匹配 provider 抛错(绝不返回 undefined 让调用方裸调)。
* 多个同 linkType provider 时取首个匹配(插入序)。
*
* @param board 目标板规格。
* @returns 匹配的 BoardLinkProvider。
* @throws {Error} 无匹配 provider 时抛错。
*/
resolve(board: BoardSpec): BoardLinkProvider {
for (const provider of this.providers.values()) {
if (provider.linkType === board.link) {
return provider;
}
}
throw new Error(
`board-link: no provider registered for link type "${board.link}" (board id="${board.id}")`,
);
}
/**
* 列出所有已注册 provider(只读快照)。
*
* @returns 只读 provider 数组(按插入序)。
*/
list(): readonly BoardLinkProvider[] {
return [...this.providers.values()];
}
}
// ============================================================================
// 预置 provider 常量(调用方可直接 import 或 register 到自定义 registry)
// ============================================================================
export { RDK_X5_SSH_PROVIDER } from "./providers/rdk-x5-ssh.js";
export { RDK_S100_SERIAL_PROVIDER } from "./providers/rdk-s100-serial.js";
export { LOCAL_PROVIDER } from "./providers/local.js";
/**
* 递归深冻结对象/函数——冻结自身 + 所有自有属性值(递归)。
*
* `Object.freeze([...])` 只冻结数组外壳,内部 provider 对象仍可被篡改
* (`providers[0].id = "MUTATED"` 静默成功)。深冻结递归冻结每个 provider,
* 使 `.id = "MUTATED"` 在严格模式抛 TypeError(fail-closed 不变式)。
*
* 与 flash/index.ts 的 deepFreeze 实现完全对称,保证 board-link 与 flash 两侧
* 的不可变不变式行为一致。
*
* 已冻结对象跳过(幂等安全),非对象/函数直透。
*
* @param value 待冻结值。
* @returns 冻结后的同一引用。
*/
function deepFreeze<T>(value: T): T {
if (value === null || value === undefined) return value;
if (typeof value !== "object" && typeof value !== "function") return value;
if (Object.isFrozen(value)) return value;
Object.freeze(value);
if (typeof value === "object") {
for (const key of Object.keys(value)) {
deepFreeze((value as Record<string, unknown>)[key]);
}
}
return value;
}
/**
* 全部预置 board-link provider(按 linkType 覆盖 ssh/serial/local)。
*
* 消费方可用 `DEFAULT_BOARD_LINK_PROVIDERS.forEach(r => r.register(p))` 批量注册,
* 或按需挑选。解构后单独 register 亦可。
*
* 深冻结,运行时不可变——数组外壳 + 每个 provider 对象均冻结,
* 篡改 provider 属性(如 `.id`)在严格模式抛 TypeError(fail-closed 不变式)。
* 与 DEFAULT_FLASH_PROVIDERS 对称:flash 侧早已 deepFreeze 每个 provider,
* board-link 侧原先仅 Object.freeze([...]) 浅冻结数组外壳,provider 对象仍可被
* 静默篡改(`RDK_X5_SSH_PROVIDER.id = "MUTATED"` 不报错),违反 fail-closed 不可变不变式。
*/
export const DEFAULT_BOARD_LINK_PROVIDERS: readonly BoardLinkProvider[] = Object.freeze([
deepFreeze(RDK_X5_SSH_PROVIDER),
deepFreeze(RDK_S100_SERIAL_PROVIDER),
deepFreeze(LOCAL_PROVIDER),
]);

View File

@ -0,0 +1,41 @@
/**
* @module capabilities/board-link/providers/local
*
* 本地链路 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 从 board-link.ts makeExec local 分支抽出:宿主即目标板,直透 underlying。
* 纯逻辑,无 pi 运行时依赖。
*
* 沙箱包装由消费方(扩展层)单独施加,本 provider 只负责 local 直透语义——
* 单一职责,纯净可测。
*/
import type { ExecFn } from "../../../shared/types.js";
import type {
BoardLinkProvider,
BoardLinkHealthResult,
} from "../types.js";
import { defaultBoardHealthCheck } from "../types.js";
// ============================================================================
// Provider 实例
// ============================================================================
/**
* Local Provider。
*
* createExec 产出直透 ExecFn:underlying(command, args, opts) —— 宿主即目标板。
* healthCheck 委托 defaultBoardHealthCheck(在宿主跑 `true`,exit 0 = alive)。
*/
export const LOCAL_PROVIDER: BoardLinkProvider = {
id: "local",
linkType: "local",
createExec(_board, underlying: ExecFn): ExecFn {
return (command, args, opts) => underlying(command, args, opts);
},
async healthCheck(exec: ExecFn): Promise<BoardLinkHealthResult> {
return defaultBoardHealthCheck(exec);
},
};

View File

@ -0,0 +1,94 @@
/**
* @module capabilities/board-link/providers/rdk-s100-serial
*
* RDK S100 串口链路 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 从 board-link.ts makeExec serial 分支抽出:解析串口地址、返回 stub ExecFn。
* 纯逻辑不能操作真实串口 fd,真实运行时由扩展层接 PTY / 子进程隔离层。
*
* 沙箱包装由消费方(扩展层)单独施加,本 provider 只负责 serial stub 语义——
* 单一职责,纯净可测。
*/
import type { ExecFn, ExecResult } from "../../../shared/types.js";
import type {
BoardLinkProvider,
BoardLinkHealthResult,
} from "../types.js";
import { defaultBoardHealthCheck } from "../types.js";
// ============================================================================
// Serial 地址解析
// ============================================================================
/** 串口地址解析结果。 */
export interface SerialTarget {
/** 设备节点路径。 */
dev: string;
/** 波特率。 */
baudrate: number;
}
/** 默认串口波特率。 */
const DEFAULT_BAUDRATE = 115_200;
/**
* 解析串口地址 /dev/ttyUSB0@115200 → { dev, baudrate }。
* 无 @baudrate 后缀时默认 115200。
*
* @param address 串口地址串。
* @returns 解析出的 SerialTarget。
*/
export function parseSerialAddress(address: string): SerialTarget {
const idx = address.lastIndexOf("@");
if (idx >= 0) {
const baud = address.slice(idx + 1);
if (/^\d+$/.test(baud)) {
return {
dev: address.slice(0, idx),
baudrate: Number.parseInt(baud, 10),
};
}
}
return { dev: address.trim(), baudrate: DEFAULT_BAUDRATE };
}
// ============================================================================
// Serial stub 固定返回
// ============================================================================
/**
* Serial stub 的固定返回。
*
* 纯逻辑不能操作真实串口 fd,真实运行时由扩展层接 PTY / 子进程隔离层。
*/
export const SERIAL_STUB_RESULT: ExecResult = {
stdout:
"[serial-stub] serial transport requires a real PTY; command not executed in pure-logic mode.\n",
stderr: "",
exitCode: 0,
};
// ============================================================================
// Provider 实例
// ============================================================================
/**
* RDK S100 Serial Provider。
*
* createExec 产出 stub ExecFn:返回 SERIAL_STUB_RESULT(纯逻辑不能操作串口 fd)。
* 真实运行时由扩展层接 PTY 替换此 stub。
* healthCheck 委托 defaultBoardHealthCheck(stub 模式下 exitCode 0 = alive)。
*/
export const RDK_S100_SERIAL_PROVIDER: BoardLinkProvider = {
id: "rdk-s100-serial",
linkType: "serial",
createExec(_board, _underlying: ExecFn): ExecFn {
return async () => SERIAL_STUB_RESULT;
},
async healthCheck(exec: ExecFn): Promise<BoardLinkHealthResult> {
return defaultBoardHealthCheck(exec);
},
};

View File

@ -0,0 +1,131 @@
/**
* @module capabilities/board-link/providers/rdk-x5-ssh
*
* RDK X5 SSH 链路 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 从 board-link.ts makeExec ssh 分支抽出:解析 SSH 地址、拼接 ssh argv、
* 委托 underlying("ssh", sshArgs, opts) 执行。纯逻辑,无 pi 运行时依赖。
*
* 沙箱包装由消费方(扩展层)单独施加,本 provider 只负责 ssh 命令拼接——
* 单一职责,纯净可测(createExec 无 env-var 全局状态依赖)。
*/
import type { BoardSpec, ExecFn } from "../../../shared/types.js";
import type {
BoardLinkProvider,
BoardLinkHealthResult,
} from "../types.js";
import { defaultBoardHealthCheck } from "../types.js";
// ============================================================================
// SSH 地址解析
// ============================================================================
/** SSH 地址解析结果。 */
export interface SshTarget {
/** 登录用户名。 */
user: string;
/** 主机名或 IP。 */
host: string;
/** 端口。 */
port: number;
}
/**
* 解析 SSH 地址串。
*
* - "root@192.168.1.100:2222" → { user:"root", host:"192.168.1.100", port:2222 }
* - "root@board" → { user:"root", host:"board", port:22 }(默认 22)
* - "board" → { user:"root"(默认), host:"board", port:22 }
* - "[::1]:2222" → IPv6 带端口
*
* fail-tolerant:解析不出端口的默认 22,解析不出 user 的默认 root。
*
* @param address SSH 地址串。
* @returns 解析出的 SshTarget。
*/
export function parseSshAddress(address: string): SshTarget {
let rest = address.trim();
let user = "root";
const atIdx = rest.indexOf("@");
if (atIdx >= 0) {
user = rest.slice(0, atIdx);
rest = rest.slice(atIdx + 1);
}
let port = 22;
let host = rest;
// IPv6 [::1]:port 或普通 host:port
const lastColon = rest.lastIndexOf(":");
if (lastColon >= 0) {
const after = rest.slice(lastColon + 1);
if (/^\d+$/.test(after)) {
port = Number.parseInt(after, 10);
host = rest.slice(0, lastColon);
}
}
// 去除 IPv6 方括号
host = host.replace(/^\[/, "").replace(/\]$/, "");
return { user, host, port };
}
// ============================================================================
// SSH 命令拼接
// ============================================================================
/** 默认 SSH 端口(不加 -p 参数,减少噪声)。 */
const DEFAULT_SSH_PORT = 22;
/**
* 构造 ssh 调用的参数数组(喂给 spawn("ssh", args))。
*
* 例:board.address="root@192.168.1.100:2222", command="ls", args=["-la"]
* → ["-p", "2222", "root@192.168.1.100", "ls", "-la"]
*
* 默认端口 22 不加 -p(与 ssh 默认行为一致,减少参数噪声)。
*
* @param board 目标板规格(取 .address 解析)。
* @param command 要在板上执行的命令。
* @param args 命令参数。
* @returns ssh argv 数组。
*/
export function buildSshArgs(
board: BoardSpec,
command: string,
args: string[],
): string[] {
const { user, host, port } = parseSshAddress(board.address);
const sshArgs: string[] = [];
if (port !== DEFAULT_SSH_PORT) {
sshArgs.push("-p", String(port));
}
sshArgs.push(`${user}@${host}`);
sshArgs.push(command);
sshArgs.push(...args);
return sshArgs;
}
// ============================================================================
// Provider 实例
// ============================================================================
/**
* RDK X5 SSH Provider。
*
* createExec 产出 ExecFn:调 underlying("ssh", buildSshArgs(board, command, args), opts)。
* healthCheck 委托 defaultBoardHealthCheck(在板上跑 `true`,exit 0 = alive)。
*/
export const RDK_X5_SSH_PROVIDER: BoardLinkProvider = {
id: "rdk-x5-ssh",
linkType: "ssh",
createExec(board: BoardSpec, underlying: ExecFn): ExecFn {
return (command, args, opts) => {
const sshArgs = buildSshArgs(board, command, args);
return underlying("ssh", sshArgs, opts);
};
},
async healthCheck(exec: ExecFn): Promise<BoardLinkHealthResult> {
return defaultBoardHealthCheck(exec);
},
};

View File

@ -0,0 +1,124 @@
/**
* @module capabilities/board-link/types
*
* 板链路能力接缝 —— Definition/Provider/Consumer 三角色之 Definition 层。
*
* 治原 board-link.ts makeExec 三分支(ssh / serial-stub / local)硬编码在单文件、
* 新增链路类型需改主文件的缺陷。抽成 BoardLinkProvider 接口 + Registry,
* 每种链路一个 provider 文件,新增链路只 register 不改主逻辑(开闭原则)。
*
* 三角色:
* - Definition —— 本文件:BoardLinkProvider 接口 + BoardLinkHealthResult 类型
* - Provider —— providers/*.ts:ssh / serial / local 三实现(BoardLinkProvider 实例)
* - Consumer —— index.ts:BoardLinkRegistry(register/resolve/list,fail-closed resolve)
*
* 纯逻辑,零 pi 运行时依赖。顶层仅 `import type`(esbuild 擦除),tests 直接 import
* 命名导出离线可测,无 pi 运行时、无真实硬件。
*
* 与原 board-link.ts 的关系:原 makeExec 把"链路类型命令包装"与"板侧沙箱包装"耦合在一起。
* 本接缝层只负责链路类型命令包装(ssh 拼 args / serial stub / local 直透),
* 沙箱包装是正交安全关注点,由消费方(扩展层)用 core/sandbox-policy 单独施加。
* 这使 provider 纯净可测——createExec 无 env-var 全局状态依赖。
*
* 见 Docs/T08_能力接缝三角色.md。
*/
import type {
BoardSpec,
BoardLinkType,
ExecFn,
ExecResult,
} from "../../shared/types.js";
// 便于调用方一次性 import;类型本身定义在 shared/types.ts
export type { BoardSpec, BoardLinkType, ExecFn, ExecResult };
// ============================================================================
// 常量 —— 消灭魔法串
// ============================================================================
/** 健康探活默认命令(exit 0 = alive)。 */
const DEFAULT_PROBE_COMMAND = "true";
/** 健康探活默认超时(毫秒)。 */
const DEFAULT_HEALTH_TIMEOUT = 10_000;
// ============================================================================
// 类型契约
// ============================================================================
/** 健康检查结果。 */
export interface BoardLinkHealthResult {
/** 板是否在线。 */
ok: boolean;
/** 离线/异常原因(诊断用)。 */
reason?: string;
}
/**
* 板链路 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 每个 provider 封装一种链路类型(ssh / serial / local)的命令包装逻辑。
* createExec 给定板规格 + 底层 exec,产出在该板执行命令的 ExecFn。
* 新增链路类型只需新建一个 provider 文件并 register,不改已有逻辑(开闭原则)。
*/
export interface BoardLinkProvider {
/** provider 唯一标识(如 "rdk-x5-ssh")。 */
readonly id: string;
/** 该 provider 服务的链路类型。 */
readonly linkType: BoardLinkType;
/**
* 给定板规格 + 底层 exec,产出在该板执行命令的 ExecFn。
*
* ssh: 调 underlying("ssh", buildSshArgs(board, command, args), opts)
* serial: 返回 stub(纯逻辑不能操作串口 fd,真实运行时由扩展层接 PTY)
* local: 直透 underlying(command, args, opts) —— 宿主即目标板
*
* @param board 目标板规格。
* @param underlying 底层执行函数(宿主 spawn)。
* @returns 该板专用的 ExecFn。
*/
createExec(board: BoardSpec, underlying: ExecFn): ExecFn;
/**
* 健康探活(可选)。在板上跑探活命令,exit 0 = alive。
* fail-closed:exec 抛异常或非 0 exit → false(板离线/不可达)。
*
* @param exec 该板的 ExecFn(由 createExec 产出)。
* @returns 健康检查结果。
*/
healthCheck?(exec: ExecFn): Promise<BoardLinkHealthResult>;
}
// ============================================================================
// 共享健康检查 —— 三 provider 共用,注入 exec 即可
// ============================================================================
/**
* 默认健康检查:在板上跑探活命令(默认 `true`),exit 0 = alive。
*
* fail-closed:exec 抛异常或非 0 exit → { ok:false }(板离线/不可达)。
* 三 provider 共用此实现,注入各自的 exec 即可。
*
* @param exec 该板的 ExecFn(由 createExec 产出)。
* @param probeCommand 自定义探活命令(默认 "true")。
* @param timeout 超时毫秒(默认 10000)。
* @returns 健康检查结果。
*/
export async function defaultBoardHealthCheck(
exec: ExecFn,
probeCommand: string = DEFAULT_PROBE_COMMAND,
timeout: number = DEFAULT_HEALTH_TIMEOUT,
): Promise<BoardLinkHealthResult> {
try {
const result = await exec(probeCommand, [], { timeout });
if (result.exitCode === 0) {
return { ok: true };
}
return {
ok: false,
reason: `probe exit ${result.exitCode}: ${result.stderr.trim() || "(no stderr)"}`,
};
} catch (e) {
return { ok: false, reason: `probe threw: ${String(e)}` };
}
}

View File

@ -0,0 +1,139 @@
/**
* @module credentials
*
* 凭据 store —— 密钥永不明文 echo。
*
* 治嵌入式 Agent 场景:LLM 网关 key(${DROBOTICS_LLM_KEY} 占位)、板侧 SSH 密码、
* 烧录证书等。凭据只进进程内存,绝不落盘、绝不写进 git-tracked 文件、绝不在日志/
* stdout 明文 echo。redact() 是日志脱敏兜底:任何形似 sk-xxx / 长不透明 token 的串
* 一律替换成 <redacted>。
*
* 设计要点:
* - get:先查内存,后回退 process.env[name](只读 env,不写 env)。
* - set:仅写内存 Map,不落盘、不写 env、不持久化。
* - redact:纯正则脱敏,命名常量模式(非魔法正则),无副作用。
* - 纯逻辑,零 pi 依赖,可离线单测。
*
* 密钥铁律:gateway key 一律用 ${DROBOTICS_LLM_KEY} 占位,绝不出现 sk- 开头明文,
* 绝不写进 git-tracked 文件(见 glm-provider.ts:83 的占位范式)。
*/
// ============================================================================
// 命名常量 —— 消灭魔法串 / 魔法正则
// ============================================================================
/** redact 替换占位。导出供调用方 / 测试引用,杜绝散落魔法串。 */
export const REDACTED_PLACEHOLDER = "<redacted>" as const;
/**
* 已知凭据前缀(OpenAI / GitHub / Slack / GitLab PAT 等)。匹配这些前缀 + 8 位以上
* 字符即视为密钥。前缀均无正则特殊字符,故不需 escape。
*/
const SECRET_PREFIXES = [
"sk-",
"ghp_",
"gho_",
"ghs_",
"ghr_",
"ghu_",
"github_pat_",
"xoxb-",
"xoxp-",
"glpat-",
] as const;
/** 长不透明 token 门槛:连续 40+ 位 [A-Za-z0-9_-] 视为 token(SHA-256=64、JWT 段等)。 */
const LONG_TOKEN_MIN = 40;
/**
* 凭据识别正则(全局):前缀密钥 或 长不透明 token。
*
* 两支:
* ① (?:prefix)[A-Za-z0-9_-]{8,} —— 已知前缀 + 8 位以上
* ② [A-Za-z0-9_-]{40,} —— 40+ 连续字符(通用长 token)
*
* 线性量词无嵌套回溯,无 catastrophic backtracking 风险。
*/
const SECRET_PATTERN: RegExp = new RegExp(
`(?:${SECRET_PREFIXES.join("|")})[A-Za-z0-9_-]{8,}|[A-Za-z0-9_-]{${LONG_TOKEN_MIN},}`,
"g",
);
// ============================================================================
// 类型契约
// ============================================================================
/** 凭据环境读取函数签名(注入以便单测,避免直接耦合 process.env)。 */
export type EnvLookup = (name: string) => string | undefined;
// ============================================================================
// CredentialsStore —— 凭据 store
// ============================================================================
/**
* 凭据 store。key 永不明文 echo。
*
* - get:先内存后 env(默认 process.env,可注入 envLookup 以便单测)。
* - set:仅内存,不落盘、不写 env。
* - redact:日志脱敏兜底,把形似 sk-xxx / 长 token 的串替换成 {@link REDACTED_PLACEHOLDER}。
*
* @example
* const store = new CredentialsStore();
* store.set("DROBOTICS_LLM_KEY", process.env.DROBOTICS_LLM_KEY!);
* store.redact("Authorization: Bearer sk-abcdef0123456789"); // → "Authorization: Bearer <redacted>"
*/
export class CredentialsStore {
private readonly memory = new Map<string, string>();
private readonly envLookup: EnvLookup;
/**
* @param envLookup env 读取函数,默认读 process.env。注入以便单测隔离。
*/
constructor(envLookup: EnvLookup = (name) => process.env[name]) {
this.envLookup = envLookup;
}
/**
* 取凭据。先内存后 env;均无返回 undefined。
*
* @param name 凭据名。
* @returns 凭据值或 undefined。
*/
get(name: string): string | undefined {
const mem = this.memory.get(name);
if (mem !== undefined) return mem;
return this.envLookup(name);
}
/**
* 存凭据。仅写内存,不落盘、不写 env。
*
* @param name 凭据名。
* @param value 凭据值。
*/
set(name: string, value: string): void {
this.memory.set(name, value);
}
/**
* 凭据是否存在(内存或 env)。
*
* @param name 凭据名。
* @returns true=存在。
*/
has(name: string): boolean {
return this.get(name) !== undefined;
}
/**
* 脱敏:把串里形似密钥 / 长 token 的子串替换成 {@link REDACTED_PLACEHOLDER}。
* 用于日志 / 审计串的兜底过滤,保证 key 永不明文 echo。
*
* @param s 待脱敏串。
* @returns 脱敏后串(密钥子串被 <redacted> 替换)。
*/
redact(s: string): string {
if (!s) return s;
return s.replace(SECRET_PATTERN, REDACTED_PLACEHOLDER);
}
}

View File

@ -0,0 +1,167 @@
/**
* @module capabilities/flash
*
* 安全烧录能力接缝入口 —— Definition/Provider/Consumer 三角色之 Consumer 层。
*
* FlashRegistry:register provider(返回 disposer)→ resolve(method)(按 id 匹配
* provider,fail-closed 无匹配抛错)→ list(只读快照)。
*
* 验收不变式(见 tests/capability-seams.test.ts):
* ① register DD_PROVIDER 后 resolve("dd") 无改动可用
* ② register disposer 调用后 list 不见该 provider
* ③ resolve 无匹配 method → 抛错(fail-closed)
*
* 纯逻辑,零 pi 运行时依赖。顶层仅 `import type`(esbuild 擦除)+ 同模块纯值导入,
* tests 直接 import 命名导出离线可测。
*
* 见 Docs/T08_能力接缝三角色.md + Docs/F13_安全烧录工具.md。
*/
import type { FlashMethod } from "../../shared/types.js";
import type { FlashProvider } from "./types.js";
// 四个 provider 是纯值(FlashProvider 实例),不含 pi 运行时依赖,可值导入。
import { DD_PROVIDER } from "./providers/dd.js";
import { FASTBOOT_PROVIDER } from "./providers/fastboot.js";
import { DFU_PROVIDER } from "./providers/dfu.js";
import { OPENOCD_PROVIDER } from "./providers/openocd.js";
// 类型 + 共享纯函数 re-export(调用方一次性 import)
export type {
FlashProvider,
FlashPlanEx,
FlashPlanOptions,
DryRunResult,
VerifyResult,
RunFlashResult,
LsblkRow,
FlashMethod,
FlashPlan,
ExecFn,
} from "./types.js";
export {
DD_BLOCK_SIZE,
ROOT_MOUNTPOINTS,
parseOffset,
parseLsblk,
isRootDiskTarget,
targetExistsInRows,
matchesDeviceName,
deviceBasename,
splitCommand,
orchestrateRun,
probeDryRun,
exitCodeVerify,
} from "./types.js";
// ============================================================================
// FlashRegistry
// ============================================================================
/**
* 烧录 Provider 注册表。
*
* - register(p): 按 p.id(= FlashMethod)存储,返回 disposer。
* disposer 只移除"仍是同一 provider 实例"的条目——override 安全。
* - resolve(method): 按 FlashMethod 匹配 provider,fail-closed 无匹配抛错。
* - list(): 只读快照。
*
* 与 FlashProvider 的关系:一 FlashMethod 一 provider。
* 新增烧录方法只需新建 provider 文件并 register,不改已有逻辑(开闭原则)。
*/
export class FlashRegistry {
/** FlashMethod → provider(插入序,Map 保证)。 */
private readonly providers = new Map<FlashMethod, FlashProvider>();
/**
* 注册一个 provider。id(= FlashMethod)唯一:重复视为更新(替换),
* 保证 barrel 重装配幂等安全。返回 disposer。
*
* @param provider 烧录 provider。
* @returns disposer——调用后从注册表移除该 provider(仅当仍是同一实例时移除)。
*/
register(provider: FlashProvider): () => void {
this.providers.set(provider.id, provider);
return () => {
if (this.providers.get(provider.id) === provider) {
this.providers.delete(provider.id);
}
};
}
/**
* 按烧录方法解析 provider(按 FlashMethod 匹配)。
*
* fail-closed:无匹配 provider 抛错(绝不返回 undefined 让调用方裸调)。
*
* @param method 烧录方法。
* @returns 匹配的 FlashProvider。
* @throws {Error} 无匹配 provider 时抛错。
*/
resolve(method: FlashMethod): FlashProvider {
const provider = this.providers.get(method);
if (!provider) {
throw new Error(
`flash: no provider registered for method "${method}"`,
);
}
return provider;
}
/**
* 列出所有已注册 provider(只读快照)。
*
* @returns 只读 provider 数组(按插入序)。
*/
list(): readonly FlashProvider[] {
return [...this.providers.values()];
}
}
// ============================================================================
// 预置 provider 常量(调用方可直接 import 或 register 到自定义 registry)
// ============================================================================
export { DD_PROVIDER } from "./providers/dd.js";
export { FASTBOOT_PROVIDER } from "./providers/fastboot.js";
export { DFU_PROVIDER } from "./providers/dfu.js";
export { OPENOCD_PROVIDER } from "./providers/openocd.js";
/**
* 递归深冻结对象/函数——冻结自身 + 所有自有属性值(递归)。
*
* `Object.freeze([...])` 只冻结数组外壳,内部 provider 对象仍可被篡改
* (`providers[0].id = "MUTATED"` 静默成功)。深冻结递归冻结每个 provider,
* 使 `.id = "MUTATED"` 在严格模式抛 TypeError(fail-closed 不变式)。
*
* 已冻结对象跳过(幂等安全),非对象/函数直透。
*
* @param value 待冻结值。
* @returns 冻结后的同一引用。
*/
function deepFreeze<T>(value: T): T {
if (value === null || value === undefined) return value;
if (typeof value !== "object" && typeof value !== "function") return value;
if (Object.isFrozen(value)) return value;
Object.freeze(value);
if (typeof value === "object") {
for (const key of Object.keys(value)) {
deepFreeze((value as Record<string, unknown>)[key]);
}
}
return value;
}
/**
* 全部预置 flash provider(覆盖 dd/fastboot/dfu/openocd 四种方法)。
*
* 消费方可用 `DEFAULT_FLASH_PROVIDERS.forEach(p => registry.register(p))` 批量注册,
* 或按需挑选。深冻结,运行时不可变——数组外壳 + 每个 provider 对象均冻结,
* 篡改 provider 属性(如 `.id`)在严格模式抛 TypeError。
*/
export const DEFAULT_FLASH_PROVIDERS: readonly FlashProvider[] = Object.freeze([
deepFreeze(DD_PROVIDER),
deepFreeze(FASTBOOT_PROVIDER),
deepFreeze(DFU_PROVIDER),
deepFreeze(OPENOCD_PROVIDER),
]);

View File

@ -0,0 +1,435 @@
/**
* @module capabilities/flash/providers/dd
*
* dd 烧录 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 从 flash.ts planFlash/dryRun/verifyFlash 的 dd 分支抽出:
* - plan(): `dd if=<image> of=<target> bs=4M conv=fsync [seek=<blocks>]`
* - run(): dryRun(lsblk 根盘校验 + stat 镜像大小 + sha256 预计算 + 只读探针)
* → 写 → verify(读回 sha256 比对)
* - verify(): 读回 `dd if=<target> bs=4M count=<blockCount>`,sha256 比对
*
* fail-closed:target 不存在 / 是根盘 / offset+镜像越界 / 无 expectedSha256 → 拒绝。
* 纯逻辑,ExecFn 注入,node:crypto 算 sha256,无真实硬件依赖。
*/
import { createHash } from "node:crypto";
import type { ExecFn } from "../../../shared/types.js";
import type {
FlashProvider,
FlashPlanEx,
FlashPlanOptions,
DryRunResult,
VerifyResult,
RunFlashResult,
LsblkRow,
} from "../types.js";
import {
DD_BLOCK_SIZE,
parseOffset,
parseLsblk,
isRootDiskTarget,
targetExistsInRows,
matchesDeviceName,
deviceBasename,
ROOT_MOUNTPOINTS,
orchestrateRun,
} from "../types.js";
// ============================================================================
// plan — 构建 dd 命令序列
// ============================================================================
/**
* 构建 dd 烧录计划。
*
* 命令:`dd if=<image> of=<target> bs=4M conv=fsync [seek=<blocks>]`
* offset > 0 时 seek= 以 bs 为单位(字节偏移 → 块数)。
*
* 注意:seek 用 Math.floor(offset / DD_BLOCK_SIZE) 将字节偏移转块数,非块对齐的
* offset 会被截断(如 offset=16 → seek=0 → dd 从字节 0 写)。dryRun 会 fail-closed
* 拒绝非 DD_BLOCK_SIZE 整数倍的 offset,plan() 本身不做此校验(纯构建,校验归 dryRun)。
*
* 若 ctx.lsblk 提供,做早期 fail-closed 根盘检查(target 不存在 / 是根盘 → 抛错)。
*
* @param opts 烧录参数。
* @param ctx 可选 lsblk 行数组(早期根盘校验)。
* @returns FlashPlanEx。
* @throws {Error} image/target 为空 / offset 不可解析 / target 是根盘。
*/
function ddPlan(opts: FlashPlanOptions, ctx?: { lsblk?: LsblkRow[] }): FlashPlanEx {
if (!opts.image || opts.image.trim() === "") {
throw new Error("flash dd: image path required");
}
if (!opts.target || opts.target.trim() === "") {
throw new Error("flash dd: target required");
}
const parsed = parseOffset(opts.offset);
if (parsed === null) {
throw new Error(
`flash dd: invalid offset "${opts.offset}" (expect decimal or 0x hex)`,
);
}
const parts = [
"dd",
`if=${opts.image}`,
`of=${opts.target}`,
"bs=4M",
"conv=fsync",
];
if (parsed > 0) {
parts.push(`seek=${Math.floor(parsed / DD_BLOCK_SIZE)}`);
}
const plan: FlashPlanEx = {
method: "dd",
commands: [parts.join(" ")],
target: opts.target,
image: opts.image,
offsetBytes: parsed,
dryRun: opts.dryRun,
verify: opts.verify,
};
// 早期 fail-closed 根盘校验(lsblk 行已提供时)
if (ctx?.lsblk && ctx.lsblk.length > 0) {
if (!targetExistsInRows(opts.target, ctx.lsblk)) {
throw new Error(`flash dd: target ${opts.target} not found in lsblk`);
}
if (isRootDiskTarget(opts.target, ctx.lsblk)) {
throw new Error(
`flash dd: target ${opts.target} is a mounted root disk — refusing`,
);
}
}
return plan;
}
// ============================================================================
// dryRun — lsblk 根盘校验 + stat 镜像大小 + sha256 预计算 + 只读探针
// ============================================================================
/**
* dd dry-run:不写真写,只校验可烧条件。
*
* 1. lsblk 确认 target 存在 + 非根盘
* 2. stat 取镜像大小
* 3. offset 越界校验(三段 fail-closed):
* a. offset >= 目标设备容量 → 拒绝(offset 单独越界)
* b. offset 非块对齐 → 拒绝(dd seek 截断)
* c. offset + imageSize > 目标设备容量 → 拒绝(镜像写过设备末尾)
* 4. sha256sum 预计算
* 5. 只读验证镜像可读:dd if=image of=/dev/null bs=4M count=1
*
* fail-closed:任一步失败 → ok:false。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @returns DryRunResult。
*/
async function ddDryRun(
plan: FlashPlanEx,
exec: ExecFn,
): Promise<DryRunResult> {
const probeCommands: string[] = [];
// 1. lsblk 确认 target 存在 + 非根盘
const lsblkCmd = "lsblk";
const lsblkArgs = ["-b", "-o", "NAME,SIZE,TYPE,MOUNTPOINT"];
probeCommands.push(`${lsblkCmd} ${lsblkArgs.join(" ")}`);
const lsblkRes = await exec(lsblkCmd, lsblkArgs);
if (lsblkRes.exitCode !== 0) {
return {
ok: false,
reason: `lsblk failed: ${lsblkRes.stderr.trim() || `exit ${lsblkRes.exitCode}`}`,
plan,
targetExists: false,
isRootDisk: false,
probeCommands,
};
}
const rows = parseLsblk(lsblkRes.stdout);
if (!targetExistsInRows(plan.target, rows)) {
return {
ok: false,
reason: `target ${plan.target} not found in lsblk`,
plan,
targetExists: false,
isRootDisk: false,
probeCommands,
};
}
const base = deviceBasename(plan.target);
if (isRootDiskTarget(plan.target, rows)) {
const rootMounts = rows
.filter(
(r) =>
matchesDeviceName(base, r.name) &&
r.mountpoint &&
ROOT_MOUNTPOINTS.has(r.mountpoint),
)
.map((r) => `${r.name}:${r.mountpoint}`);
return {
ok: false,
reason: `target ${plan.target} has mounted ${rootMounts.join(", ")} — refusing`,
plan,
targetExists: true,
isRootDisk: true,
probeCommands,
};
}
// 2. stat 取镜像大小
const statCmd = "stat";
const statArgs = ["-c", "%s", plan.image];
probeCommands.push(`${statCmd} ${statArgs.join(" ")}`);
const statRes = await exec(statCmd, statArgs);
if (statRes.exitCode !== 0) {
return {
ok: false,
reason: `stat image failed: ${statRes.stderr.trim() || `exit ${statRes.exitCode}`}`,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
};
}
const imageSize = Number.parseInt(statRes.stdout.trim(), 10);
if (!Number.isFinite(imageSize) || imageSize <= 0) {
return {
ok: false,
reason: `invalid image size: "${statRes.stdout.trim()}"`,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
};
}
plan.imageSizeBytes = imageSize;
plan.blockCount = Math.max(1, Math.ceil(imageSize / DD_BLOCK_SIZE));
// 3. offset 越界校验
// 修正:旧逻辑把 target seek offset 与 source image size 比较(offset >= imageSize),
// 拒绝了合法的分区偏移烧录(如 4MB 镜像烧到 8MB 偏移分区)。
// 正确语义:offset 不得超过目标设备容量(从 lsblk 行取 target 大小)。
// 未知设备大小时回退到 offset >= imageSize 保守边界(fail-closed)。
const targetRow = rows.find((r) => r.name === base);
const targetDeviceSize = targetRow?.size ?? 0;
if (plan.offsetBytes !== undefined) {
if (targetDeviceSize > 0) {
// 已知目标设备大小:offset 不得超过设备容量
if (plan.offsetBytes >= targetDeviceSize) {
// 修正:实际比较的是 offset >= targetDeviceSize(设备容量),而非 image size。
// 原消息 "offset X >= image size Y" 误导操作员去查镜像大小而非设备容量。
// 现以 "exceeds target device size" 为主诊断,附带 image size 上下文——
// offset 也 >= image size 时标注 ">= image size",否则标注 "< image size",
// 使操作员聚焦设备容量(真正越界的维度)。
const exceedsImageToo = plan.offsetBytes >= imageSize;
return {
ok: false,
reason: `offset ${plan.offsetBytes} exceeds target device size ${targetDeviceSize} (offset ${exceedsImageToo ? ">= image size" : "< image size"} ${imageSize})`,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
};
}
} else {
// 未知设备大小:回退到 offset 不超过镜像大小(保守边界)
if (plan.offsetBytes >= imageSize) {
return {
ok: false,
reason: `offset ${plan.offsetBytes} >= image size ${imageSize}`,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
};
}
}
// 修正(非对齐 offset 静默截断):plan() 用 Math.floor(offset / DD_BLOCK_SIZE)
// 将字节偏移转成 dd seek= 块数。非块对齐的 offset 被静默截断——如 offset=16
// → seek=0 → dd 从字节 0 开始写,而非字节 16,造成静默数据错位(可能损坏分区表)。
// dryRun 的 offset 越界校验用字节语义(offset vs targetDeviceSize),但实际 seek
// 用块语义,形成 validation/execution mismatch。此处 fail-closed 拒绝非对齐 offset,
// 要求 offset 为 DD_BLOCK_SIZE (bs=4M) 的整数倍。
if (plan.offsetBytes > 0 && plan.offsetBytes % DD_BLOCK_SIZE !== 0) {
return {
ok: false,
reason: `offset ${plan.offsetBytes} is not a multiple of block size ${DD_BLOCK_SIZE} (dd seek truncates non-aligned byte offsets; use a multiple of bs=4M)`,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
};
}
// 修正(offset + imageSize 越界):模块 doc(types.ts:24)承诺 "offset + 镜像大小
// 越过目标设备容量 → 拒绝"。上方旧检查只查 offset >= targetDeviceSize(offset 单独
// 越界),漏掉 offset < targetDeviceSize 但 offset + imageSize > targetDeviceSize 的
// 情形——如 8GB 设备 / 5GB 镜像 / 6GB 偏移(4MiB 对齐):6GB < 8GB 通过旧检查,
// 但 6GB + 5GB = 11GB > 8GB,dd 写过设备末尾,静默截断镜像数据,违反 fail-closed
// 安全不变式。此处补全:offset + imageSize 越过设备容量即拒绝。
// guard offset > 0:offset=0 时 "0 + imageSize > deviceSize" 属 "镜像本身大于设备"
// 的独立语义,不在此 offset 越界检查中重复(避免误伤 imageSize > deviceSize 的
// 合法 mock 场景);本检查聚焦 offset 促发的越界。
// guard targetDeviceSize > 0:未知设备大小走上方 else 分支的保守边界,不重复。
if (
plan.offsetBytes > 0 &&
targetDeviceSize > 0 &&
plan.offsetBytes + imageSize > targetDeviceSize
) {
return {
ok: false,
reason: `offset ${plan.offsetBytes} + image size ${imageSize} (${plan.offsetBytes + imageSize}) exceeds target device size ${targetDeviceSize}`,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
};
}
}
// 4. sha256sum 预计算
const shaCmd = "sha256sum";
const shaArgs = [plan.image];
probeCommands.push(`${shaCmd} ${shaArgs.join(" ")}`);
const shaRes = await exec(shaCmd, shaArgs);
if (shaRes.exitCode !== 0) {
return {
ok: false,
reason: `sha256sum failed: ${shaRes.stderr.trim() || `exit ${shaRes.exitCode}`}`,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
};
}
const hash = shaRes.stdout.trim().split(/\s+/)[0] ?? "";
if (!/^[0-9a-f]{64}$/i.test(hash)) {
return {
ok: false,
reason: `unparsable sha256sum output: "${shaRes.stdout.trim().slice(0, 80)}"`,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
sha256sumOutput: shaRes.stdout,
};
}
plan.expectedSha256 = hash;
// 5. 只读验证镜像可读
const ddProbe = "dd";
const ddProbeArgs = [`if=${plan.image}`, "of=/dev/null", "bs=4M", "count=1"];
probeCommands.push(`${ddProbe} ${ddProbeArgs.join(" ")}`);
const ddProbeRes = await exec(ddProbe, ddProbeArgs);
if (ddProbeRes.exitCode !== 0) {
return {
ok: false,
reason: `image read probe failed: ${ddProbeRes.stderr.trim() || `exit ${ddProbeRes.exitCode}`}`,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
sha256sumOutput: shaRes.stdout,
};
}
return {
ok: true,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
sha256sumOutput: shaRes.stdout,
};
}
// ============================================================================
// verify — 读回 sha256 比对
// ============================================================================
/**
* dd 烧后校验:读回 `dd if=<target> bs=4M count=<blockCount>`,
* 对 stdout 算 sha256,与 plan.expectedSha256(dryRun 预计算)比对。
*
* fail-closed:无 expectedSha256(未 dry-run)→ 拒绝;读回失败 → fail。
*
* @param plan 烧录计划(dryRun 填充了 expectedSha256/blockCount)。
* @param exec 注入的执行函数。
* @returns VerifyResult。
*/
async function ddVerify(
plan: FlashPlanEx,
exec: ExecFn,
): Promise<VerifyResult> {
if (!plan.expectedSha256) {
return { ok: false, reason: "no expectedSha256 in plan — run dryRun first" };
}
const blockCount = plan.blockCount ?? 1;
const cmd = "dd";
const args = [`if=${plan.target}`, "bs=4M", `count=${blockCount}`];
const res = await exec(cmd, args);
if (res.exitCode !== 0) {
return {
ok: false,
expected: plan.expectedSha256,
reason: `readback dd failed: ${res.stderr.trim() || `exit ${res.exitCode}`}`,
verifyCommand: `${cmd} ${args.join(" ")}`,
};
}
const actual = createHash("sha256").update(res.stdout).digest("hex");
if (actual === plan.expectedSha256) {
return {
ok: true,
expected: plan.expectedSha256,
actual,
verifyCommand: `${cmd} ${args.join(" ")}`,
};
}
return {
ok: false,
expected: plan.expectedSha256,
actual,
reason: "VERIFY FAILED: sha256 mismatch",
verifyCommand: `${cmd} ${args.join(" ")}`,
};
}
// ============================================================================
// run — 三段式编排(委托 orchestrateRun)
// ============================================================================
/**
* dd 三段式编排:dryRun → 写 → verify。
* 委托 orchestrateRun,注入 ddDryRun + ddVerify。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @returns RunFlashResult。
*/
async function ddRun(
plan: FlashPlanEx,
exec: ExecFn,
): Promise<RunFlashResult> {
return orchestrateRun(plan, exec, ddDryRun, ddVerify);
}
// ============================================================================
// Provider 实例
// ============================================================================
/**
* dd 烧录 Provider。
*
* 磁盘级烧录(SD 卡 / eMMC),强制 dry-run + sha256 校验,拒绝宿主系统盘。
*/
export const DD_PROVIDER: FlashProvider = {
id: "dd",
plan: ddPlan,
run: ddRun,
verify: ddVerify,
};

View File

@ -0,0 +1,122 @@
/**
* @module capabilities/flash/providers/dfu
*
* dfu-util 烧录 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 从 flash.ts planFlash/dryRun/verifyFlash 的 dfu 分支抽出:
* - plan(): `dfu-util -d <target> [-a <alt>] -D <image>`(target = vid:pid)
* - run(): dryRun(dfu-util -l 列出 DFU 设备)→ 写 → verify(-l 再探活)
* - verify(): `dfu-util -l`,exit 0 为通过
*
* 纯逻辑,ExecFn 注入,无真实硬件依赖。
*/
import type { ExecFn } from "../../../shared/types.js";
import type {
FlashProvider,
FlashPlanEx,
FlashPlanOptions,
} from "../types.js";
import {
orchestrateRun,
probeDryRun,
exitCodeVerify,
} from "../types.js";
// ============================================================================
// plan — 构建 dfu-util 命令序列
// ============================================================================
/**
* 构建 dfu-util 烧录计划。
*
* - partition 提供(alt-setting):`dfu-util -d <target> -a <alt> -D <image>`
* - partition 缺省:`dfu-util -d <target> -D <image>`
*
* target = vid:pid(如 0483:df11)。
*
* @param opts 烧录参数。
* @returns FlashPlanEx。
* @throws {Error} image/target 为空。
*/
function dfuPlan(opts: FlashPlanOptions): FlashPlanEx {
if (!opts.image || opts.image.trim() === "") {
throw new Error("flash dfu: image path required");
}
if (!opts.target || opts.target.trim() === "") {
throw new Error("flash dfu: target required");
}
const alt = opts.partition?.trim();
const parts = ["dfu-util", `-d ${opts.target}`];
if (alt) parts.push(`-a ${alt}`);
parts.push(`-D ${opts.image}`);
return {
method: "dfu",
commands: [parts.join(" ")],
target: opts.target,
image: opts.image,
dryRun: opts.dryRun,
verify: opts.verify,
};
}
// ============================================================================
// dryRun — dfu-util -l 列出 DFU 设备
// ============================================================================
/** dfu 探活命令。 */
const DFU_PROBE = { cmd: "dfu-util", args: ["-l"] };
// ============================================================================
// verify — dfu-util -l 再探活
// ============================================================================
/**
* dfu 烧后校验:`dfu-util -l`,exit 0 为通过。
* dfu 无逐字节校验,只探设备仍在线。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @returns VerifyResult。
*/
async function dfuVerify(plan: FlashPlanEx, exec: ExecFn) {
return exitCodeVerify(plan, exec, DFU_PROBE);
}
// ============================================================================
// run — 三段式编排
// ============================================================================
/**
* dfu 三段式编排:dryRun(dfu-util -l 探活)→ 写 → verify(-l)。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @returns RunFlashResult。
*/
async function dfuRun(plan: FlashPlanEx, exec: ExecFn) {
return orchestrateRun(
plan,
exec,
(p, e) => probeDryRun(p, e, DFU_PROBE),
dfuVerify,
);
}
// ============================================================================
// Provider 实例
// ============================================================================
/**
* dfu-util 烧录 Provider。
*
* USB DFU 协议烧录(STM32 等),dfu-util -l 探活 + exitCode 校验。
*/
export const DFU_PROVIDER: FlashProvider = {
id: "dfu",
plan: dfuPlan,
run: dfuRun,
verify: dfuVerify,
};

View File

@ -0,0 +1,123 @@
/**
* @module capabilities/flash/providers/fastboot
*
* fastboot 烧录 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 从 flash.ts planFlash/dryRun/verifyFlash 的 fastboot 分支抽出:
* - plan(): `fastboot flash <partition> <image>`(partition 缺省则 `fastboot flash <image>`)
* - run(): dryRun(getvar all 探活)→ 写 → verify(getvar all 再探活)
* - verify(): `fastboot getvar all`,exit 0 为通过(fastboot 无逐字节校验)
*
* 纯逻辑,ExecFn 注入,无真实硬件依赖。
*/
import type { ExecFn } from "../../../shared/types.js";
import type {
FlashProvider,
FlashPlanEx,
FlashPlanOptions,
} from "../types.js";
import {
orchestrateRun,
probeDryRun,
exitCodeVerify,
} from "../types.js";
// ============================================================================
// plan — 构建 fastboot 命令序列
// ============================================================================
/**
* 构建 fastboot 烧录计划。
*
* - partition 提供:`fastboot flash <partition> <image>`
* - partition 缺省:`fastboot flash <image>`
*
* @param opts 烧录参数。
* @returns FlashPlanEx。
* @throws {Error} image/target 为空。
*/
function fastbootPlan(opts: FlashPlanOptions): FlashPlanEx {
if (!opts.image || opts.image.trim() === "") {
throw new Error("flash fastboot: image path required");
}
if (!opts.target || opts.target.trim() === "") {
throw new Error("flash fastboot: target required");
}
const part = opts.partition?.trim();
const cmd = part
? `fastboot flash ${part} ${opts.image}`
: `fastboot flash ${opts.image}`;
return {
method: "fastboot",
commands: [cmd],
target: opts.target,
image: opts.image,
dryRun: opts.dryRun,
verify: opts.verify,
};
}
// ============================================================================
// dryRun — getvar all 探活
// ============================================================================
/** fastboot 探活命令。 */
const FASTBOOT_PROBE = { cmd: "fastboot", args: ["getvar", "all"] };
// ============================================================================
// verify — getvar all 再探活
// ============================================================================
/**
* fastboot 烧后校验:`fastboot getvar all`,exit 0 为通过。
* fastboot 无逐字节校验,只探设备仍在线。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @returns VerifyResult。
*/
async function fastbootVerify(
plan: FlashPlanEx,
exec: ExecFn,
) {
return exitCodeVerify(plan, exec, FASTBOOT_PROBE);
}
// ============================================================================
// run — 三段式编排
// ============================================================================
/**
* fastboot 三段式编排:dryRun(getvar all 探活)→ 写 → verify(getvar all)。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @returns RunFlashResult。
*/
async function fastbootRun(plan: FlashPlanEx, exec: ExecFn) {
return orchestrateRun(
plan,
exec,
(p, e) => probeDryRun(p, e, FASTBOOT_PROBE),
fastbootVerify,
);
}
// ============================================================================
// Provider 实例
// ============================================================================
/**
* fastboot 烧录 Provider。
*
* Android/fastboot 协议烧录(USB),getvar all 探活 + exitCode 校验。
*/
export const FASTBOOT_PROVIDER: FlashProvider = {
id: "fastboot",
plan: fastbootPlan,
run: fastbootRun,
verify: fastbootVerify,
};

View File

@ -0,0 +1,129 @@
/**
* @module capabilities/flash/providers/openocd
*
* openocd 烧录 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 从 flash.ts planFlash/dryRun/verifyFlash 的 openocd 分支抽出:
* - plan(): `openocd -f <target> -c "program <image> verify reset exit"`(target = cfg 路径)
* - run(): dryRun(openocd -f cfg -c init -c exit 探 JTAG 连通)→ 写 → verify
* - verify(): `openocd -f <cfg> -c "verify_image <image>" -c exit`,exit 0 为通过
*
* 纯逻辑,ExecFn 注入,无真实硬件依赖。
*/
import type { ExecFn } from "../../../shared/types.js";
import type {
FlashProvider,
FlashPlanEx,
FlashPlanOptions,
} from "../types.js";
import {
orchestrateRun,
probeDryRun,
exitCodeVerify,
} from "../types.js";
// ============================================================================
// plan — 构建 openocd 命令序列
// ============================================================================
/**
* 构建 openocd 烧录计划。
*
* 命令:`openocd -f <target> -c "program <image> verify reset exit"`
* target = openocd cfg 路径(如 interface/stlink.cfg)。
*
* @param opts 烧录参数。
* @returns FlashPlanEx。
* @throws {Error} image/target 为空。
*/
function openocdPlan(opts: FlashPlanOptions): FlashPlanEx {
if (!opts.image || opts.image.trim() === "") {
throw new Error("flash openocd: image path required");
}
if (!opts.target || opts.target.trim() === "") {
throw new Error("flash openocd: target (cfg path) required");
}
return {
method: "openocd",
commands: [`openocd -f ${opts.target} -c "program ${opts.image} verify reset exit"`],
target: opts.target,
image: opts.image,
dryRun: opts.dryRun,
verify: opts.verify,
};
}
// ============================================================================
// dryRun — openocd init/exit 探 JTAG 连通
// ============================================================================
/**
* 构建 openocd 探活命令(依赖 plan.target = cfg 路径)。
*
* @param plan 烧录计划。
* @returns 探活命令 + 参数。
*/
function openocdProbe(plan: FlashPlanEx): { cmd: string; args: string[] } {
return {
cmd: "openocd",
args: ["-f", plan.target, "-c", "init", "-c", "exit"],
};
}
// ============================================================================
// verify — verify_image exitCode 校验
// ============================================================================
/**
* openocd 烧后校验:`openocd -f <cfg> -c "verify_image <image>" -c exit`,
* exit 0 为通过。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @returns VerifyResult。
*/
async function openocdVerify(plan: FlashPlanEx, exec: ExecFn) {
return exitCodeVerify(plan, exec, {
cmd: "openocd",
args: ["-f", plan.target, "-c", `verify_image ${plan.image}`, "-c", "exit"],
});
}
// ============================================================================
// run — 三段式编排
// ============================================================================
/**
* openocd 三段式编排:dryRun(init/exit 探 JTAG 连通)→ 写 → verify(verify_image)。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @returns RunFlashResult。
*/
async function openocdRun(plan: FlashPlanEx, exec: ExecFn) {
const probe = openocdProbe(plan);
return orchestrateRun(
plan,
exec,
(p, e) => probeDryRun(p, e, probe),
openocdVerify,
);
}
// ============================================================================
// Provider 实例
// ============================================================================
/**
* openocd 烧录 Provider。
*
* JTAG/SWD 协议烧录(MCU Flash),init/exit 探连通 + verify_image 校验。
*/
export const OPENOCD_PROVIDER: FlashProvider = {
id: "openocd",
plan: openocdPlan,
run: openocdRun,
verify: openocdVerify,
};

View File

@ -0,0 +1,572 @@
/**
* @module capabilities/flash/types
*
* 安全烧录能力接缝 —— Definition/Provider/Consumer 三角色之 Definition 层。
*
* 治原 flash.ts planFlash/dryRun/verifyFlash/runFlash 按 method switch 分派、
* 新增烧录方法需改主文件的缺陷。抽成 FlashProvider 接口 + Registry,
* 每种烧录方法一个 provider 文件,新增方法只 register 不改主逻辑(开闭原则)。
*
* 三角色:
* - Definition —— 本文件:FlashProvider 接口 + FlashPlanEx/FlashPlanOptions +
* RunFlashResult/VerifyResult/DryRunResult/LsblkRow 类型 + 共享纯函数(parseOffset /
* parseLsblk / isRootDiskTarget / splitCommand 等供各 provider 复用)
* - Provider —— providers/*.ts:dd / fastboot / dfu / openocd 四实现(FlashProvider 实例)
* - Consumer —— index.ts:FlashRegistry(register/resolve/list,fail-closed resolve)
*
* 纯逻辑,零 pi 运行时依赖。顶层仅 `import type`(esbuild 擦除)+ node:crypto(Node 内置),
* tests 直接 import 命名导出离线可测,无 pi 运行时、无真实硬件。
*
* fail-closed 语义(安全不变式):
* - dryRun 默认 true(第一次必须先 dry-run 再写真写)
* - target 是宿主系统盘(挂载了 / /boot /home 等)或根分区 → 拒绝
* - target 不存在 → 拒绝
* - offset + 镜像大小 越过目标设备容量 → 拒绝(非 offset vs 镜像大小)
* - 烧后 sha256 不匹配 → VERIFY FAILED
*
* 见 Docs/T08_能力接缝三角色.md + Docs/F13_安全烧录工具.md。
*/
import type {
FlashMethod,
FlashPlan,
ExecFn,
} from "../../shared/types.js";
// 便于调用方一次性 import;类型本身定义在 shared/types.ts
export type { FlashMethod, FlashPlan, ExecFn };
// ============================================================================
// 类型契约
// ============================================================================
/**
* 扩展 FlashPlan:plan() 填充的偏移 + dryRun/verify 标记,dryRun()/verify() 填充的
* 镜像大小 / 块数 / 预期 sha256(verify 用)。
*/
export interface FlashPlanEx extends FlashPlan {
/** dd seek= 的字节偏移(解析自 opts.offset,十进制或 0x hex)。 */
offsetBytes?: number;
/** 镜像字节数(dryRun 经 stat 填充,verify dd 读回 count 用)。 */
imageSizeBytes?: number;
/** dd bs=4M 块数(ceil(imageSizeBytes / 4MiB)),verify 读回 count。 */
blockCount?: number;
/** 是否先 dry-run(默认 true,fail-closed)。run() 据此决定是否跳过写。 */
dryRun?: boolean;
/** 烧后是否 verify(默认 true)。run() 据此决定是否跳过 verify。 */
verify?: boolean;
}
/**
* flash provider plan() 的入参。method/image/target 必填,其余可选。
*/
export interface FlashPlanOptions {
/** 烧录方法。 */
method: FlashMethod;
/** 镜像/载荷文件路径。 */
image: string;
/** 目标设备节点 / 串号 / cfg 路径。 */
target: string;
/** dd seek= 字节偏移(十进制或 0x hex 字符串)。 */
offset?: string;
/** fastboot 分区名(如 boot)或 dfu alt-setting。 */
partition?: string;
/** 是否先 dry-run(默认 true,fail-closed)。 */
dryRun?: boolean;
/** 烧后是否 verify(默认 true)。 */
verify?: boolean;
}
/** dryRun 结果。 */
export interface DryRunResult {
/** 是否通过 dry-run 校验。 */
ok: boolean;
/** 失败原因(fail-closed 诊断用)。 */
reason?: string;
/** 烧录计划(dryRun 可能填充 imageSizeBytes/blockCount/expectedSha256)。 */
plan: FlashPlanEx;
/** target 设备节点是否存在于 lsblk 输出。 */
targetExists: boolean;
/** target 是否挂载了根/启动分区(→ 拒绝)。 */
isRootDisk: boolean;
/** dry-run 阶段实际执行的探测命令(审计用)。 */
probeCommands: string[];
/** sha256sum 镜像原始输出(dd 方法)。 */
sha256sumOutput?: string;
}
/** verify 结果。 */
export interface VerifyResult {
/** 是否通过烧后校验。 */
ok: boolean;
/** 预期 sha256(dd 方法)。 */
expected?: string;
/** 实际 sha256(dd 方法)。 */
actual?: string;
/** 失败原因。 */
reason?: string;
/** verify 阶段执行的命令。 */
verifyCommand?: string;
}
/** lsblk 行解析结果。 */
export interface LsblkRow {
/** 设备名(如 sda1, mmcblk0p1)。 */
name: string;
/** 字节大小。 */
size: number;
/** 设备类型(disk/part)。 */
type: string;
/** 挂载点(空串=未挂载)。 */
mountpoint: string;
}
/** run() 三段式编排结果。 */
export interface RunFlashResult {
/** dry-run 阶段结果。 */
dryRun: DryRunResult;
/** 是否真正执行了写命令。 */
written: boolean;
/** 写命令执行结果(每条 command 的 exitCode)。 */
writeExitCodes: number[];
/** verify 阶段结果(跳过 verify 时 undefined)。 */
verify?: VerifyResult;
/** 总体是否成功(dryRun ok + 写全 0 + verify ok)。 */
ok: boolean;
/** 失败原因。 */
reason?: string;
}
// ============================================================================
// 常量 —— 消灭魔法串
// ============================================================================
/** dd 块大小(与文档一致 bs=4M)。 */
export const DD_BLOCK_SIZE = 4 * 1024 * 1024;
/**
* 深冻结 Set 包装器 —— 运行时不可变。
*
* `Object.freeze(new Set(...))` 只冻结 Set 对象引用,不阻止 `.add()/.delete()`
* 修改集合内容(freeze 对 Set 内容无效果)。本包装器不暴露 add/delete/clear,
* 从运行时根除突变可能:调用方拿到的是只读视图,任何 `.add()/.delete()` 调用
* 在运行时直接抛 TypeError(fail-closed)。
*
* 实现 ReadonlySet<T> 全部只读接口,类型与运行时双重不可变。
*/
class FrozenSet<T> implements ReadonlySet<T> {
/** 私有底层 Set——外部不可达,无法通过 `.backing.delete()` 绕过。 */
private readonly backing: Set<T>;
constructor(items: readonly T[]) {
this.backing = new Set(items);
}
get size(): number {
return this.backing.size;
}
has(value: T): boolean {
return this.backing.has(value);
}
entries(): IterableIterator<[T, T]> {
return this.backing.entries();
}
keys(): IterableIterator<T> {
return this.backing.keys();
}
values(): IterableIterator<T> {
return this.backing.values();
}
forEach(
callback: (value: T, value2: T, set: ReadonlySet<T>) => void,
thisArg?: unknown,
): void {
this.backing.forEach((v) => callback.call(thisArg, v, v, this));
}
[Symbol.iterator](): IterableIterator<T> {
return this.backing[Symbol.iterator]();
}
}
/** 视为宿主系统盘的挂载点(命中任一即拒绝写)。深冻结,运行时不可变。 */
export const ROOT_MOUNTPOINTS: ReadonlySet<string> = new FrozenSet<string>([
"/",
"/boot",
"/boot/efi",
"/home",
"/var",
"/usr",
"/swap",
"[SWAP]",
]);
/** lsblk 树形输出前缀字符(├─ └─ │ ─ 等非 ASCII 盒绘字符)。 */
const LSBLK_TREE_CHARS = /[─-╼│├└─\s]+/;
// ============================================================================
// 共享纯函数 —— 各 provider 复用
// ============================================================================
/**
* 把 offset 字符串(十进制或 0x hex)解析成字节数。
*
* @param offset 十进制或 0x hex 字符串,undefined/空 → 0。
* @returns 字节数;无法解析返回 null。
*/
export function parseOffset(offset: string | undefined): number | null {
if (offset === undefined || offset === "") return 0;
const trimmed = offset.trim();
if (/^0x[0-9a-fA-F]+$/.test(trimmed)) {
const n = Number(trimmed);
if (Number.isFinite(n) && n >= 0) return n;
return null;
}
if (/^\d+$/.test(trimmed)) {
try {
const big = BigInt(trimmed);
if (big > BigInt(Number.MAX_SAFE_INTEGER)) {
return Number.MAX_SAFE_INTEGER;
}
return Number(big);
} catch {
return null;
}
}
return null;
}
/**
* 解析 `lsblk -b -o NAME,SIZE,TYPE,MOUNTPOINT` 的原始输出为行数组。
* 处理树形盒绘字符前缀(├─ └─ │)与空 mountpoint。
*
* @param raw lsblk 原始 stdout。
* @returns 解析后的行数组。
*/
export function parseLsblk(raw: string): LsblkRow[] {
const lines = raw.split("\n");
const rows: LsblkRow[] = [];
let started = false;
for (const line of lines) {
if (!line.trim()) continue;
if (!started) {
if (/^NAME/i.test(line.trim())) {
started = true;
continue;
}
}
const cleaned = line.replace(LSBLK_TREE_CHARS, " ").trim();
if (!cleaned) continue;
const cols = cleaned.split(/\s+/);
if (cols.length < 3) continue;
const name = cols[0] ?? "";
const size = Number.parseInt(cols[1] ?? "0", 10);
const type = cols[2] ?? "";
const mountpoint = cols.slice(3).join(" ") ?? "";
rows.push({
name,
size: Number.isFinite(size) ? size : 0,
type,
mountpoint,
});
}
return rows;
}
/**
* 从目标设备路径提取 basename(/dev/sda1 → sda1,/dev/mmcblk0p2 → mmcblk0p2)。
*
* @param target 设备路径。
* @returns basename。
*/
export function deviceBasename(target: string): string {
const m = target.match(/\/dev\/(.+)$/);
return m ? m[1] : target.replace(/^\/+/, "");
}
/**
* 判断 lsblk 行名是否匹配目标设备(整盘自身或其分区)。
*
* 匹配规则:`name === base` 或 `name === base + 分区后缀`。
* 分区后缀模式为 `p?\d+`(覆盖 sda1 / mmcblk0p1 / nvme0n1p2 等命名约定)。
*
* 替代旧的 `row.name.startsWith(base)`,后者会误匹配前缀相同但不同设备
* (如 base "sda" 误匹配 "sdab";base "mmcblk0" 误匹配 "mmcblk0boot0")。
*
* @param base 目标设备 basename(deviceBasename 提取)。
* @param name lsblk 行的 NAME 字段。
* @returns true 表示该行属于目标设备或其分区。
*/
export function matchesDeviceName(base: string, name: string): boolean {
if (name === base) return true;
// 转义 base 中的正则元字符(设备名通常无元字符,但防御性转义)
const escaped = base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
// 分区后缀:p?\d+(sda1 / mmcblk0p1 / nvme0n1p2)
return new RegExp(`^${escaped}(?:p?\\d+)?$`).test(name);
}
/**
* 判断 target 是否为宿主系统盘:target 自身或其任一分区挂载了根/启动目录。
*
* @param target 设备路径。
* @param rows lsblk 解析后的行数组。
* @returns true 表示是宿主系统盘(应拒绝写)。
*/
export function isRootDiskTarget(
target: string,
rows: LsblkRow[],
): boolean {
const base = deviceBasename(target);
for (const row of rows) {
if (matchesDeviceName(base, row.name)) {
if (row.mountpoint && ROOT_MOUNTPOINTS.has(row.mountpoint)) {
return true;
}
}
}
return false;
}
/**
* 判断 target 是否出现在 lsblk 输出里(设备节点存在)。
*
* @param target 设备路径。
* @param rows lsblk 解析后的行数组。
* @returns true 表示设备存在。
*/
export function targetExistsInRows(
target: string,
rows: LsblkRow[],
): boolean {
const base = deviceBasename(target);
return rows.some((r) => matchesDeviceName(base, r.name));
}
/**
* 简易命令拆分:按空格切,但保留双引号内的整体
* (openocd -c "program x verify reset exit")。
*
* 仅供 run() 内部把 plan.commands 字符串拆回 command+args。
*
* 空引号参数保留:`a -c ""` → `['a', '-c', '']`(空串是合法 argv,
* 不能因 `if (cur)` 丢弃)。靠 hadQuote 标记区分"空引号 token"与"未入 token"。
*
* @param cmdStr 命令字符串。
* @returns 拆分后的 token 数组(第一项为命令,其余为参数)。
*/
export function splitCommand(cmdStr: string): string[] {
const tokens: string[] = [];
let cur = "";
let inQuote = false;
let hadQuote = false; // 当前 token 是否进入过引号区域(空引号 "" 也算)
for (let i = 0; i < cmdStr.length; i++) {
const ch = cmdStr[i];
if (ch === '"') {
inQuote = !inQuote;
hadQuote = true;
continue;
}
if (ch === " " && !inQuote) {
if (cur || hadQuote) tokens.push(cur);
cur = "";
hadQuote = false;
continue;
}
cur += ch;
}
if (cur || hadQuote) tokens.push(cur);
return tokens;
}
// ============================================================================
// 共享编排 helper —— 各 provider 的 run() 复用(DRY,消灭三段式样板)
// ============================================================================
/**
* 三段式编排:dryRun(fail-closed)→ 写 → verify。
*
* 各 provider 的 run() 委托此函数,注入自己的 dryRunFn / verifyFn 即可——
* 编排逻辑(skipWrite 判定、逐条写、失败短路)只此一份,不复制到每个 provider。
*
* - plan.dryRun !== false → 只 dry-run 不写真写(fail-closed 默认)
* - plan.verify === false → 跳过 verify
*
* @param plan 烧录计划(plan() 产出,dryRun/verify 标记已设)。
* @param exec 注入的执行函数。
* @param dryRunFn provider 的 dryRun 实现。
* @param verifyFn provider 的 verify 实现。
* @returns RunFlashResult。
*/
export async function orchestrateRun(
plan: FlashPlanEx,
exec: ExecFn,
dryRunFn: (plan: FlashPlanEx, exec: ExecFn) => Promise<DryRunResult>,
verifyFn: (plan: FlashPlanEx, exec: ExecFn) => Promise<VerifyResult>,
): Promise<RunFlashResult> {
// ① dry-run(fail-closed:不通过不写)
const dr = await dryRunFn(plan, exec);
if (!dr.ok) {
return {
dryRun: dr,
written: false,
writeExitCodes: [],
ok: false,
reason: dr.reason,
};
}
// dryRun 默认 true:未显式传 false 即只 dry-run
const dryOnly = plan.dryRun !== false;
if (dryOnly) {
return { dryRun: dr, written: false, writeExitCodes: [], ok: true };
}
// ② 写:逐条执行 plan.commands
const writeExitCodes: number[] = [];
for (const cmdStr of plan.commands) {
const parts = splitCommand(cmdStr);
const res = await exec(parts[0], parts.slice(1));
writeExitCodes.push(res.exitCode);
if (res.exitCode !== 0) {
return {
dryRun: dr,
written: true,
writeExitCodes,
ok: false,
reason: `write command failed (${cmdStr}): ${res.stderr.trim() || `exit ${res.exitCode}`}`,
};
}
}
// ③ verify(verify !== false 时执行)
const vr = plan.verify === false ? undefined : await verifyFn(plan, exec);
const ok = vr ? vr.ok : true;
return {
dryRun: dr,
written: true,
writeExitCodes,
verify: vr,
ok,
reason: vr?.ok ? undefined : vr?.reason,
};
}
/**
* probe-based dryRun 通用实现(fastboot/dfu/openocd 共用)。
*
* 跑一条探测命令,exit 0 = ok。fail-closed:非 0 → ok:false。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @param probe 探测命令 + 参数。
* @returns DryRunResult。
*/
export async function probeDryRun(
plan: FlashPlanEx,
exec: ExecFn,
probe: { cmd: string; args: string[] },
): Promise<DryRunResult> {
const probeCommands = [`${probe.cmd} ${probe.args.join(" ")}`];
const res = await exec(probe.cmd, probe.args);
if (res.exitCode !== 0) {
return {
ok: false,
reason: `${plan.method} probe failed: ${res.stderr.trim() || `exit ${res.exitCode}`}`,
plan,
targetExists: false,
isRootDisk: false,
probeCommands,
};
}
return {
ok: true,
plan,
targetExists: true,
isRootDisk: false,
probeCommands,
};
}
/**
* exitCode-based verify 通用实现(fastboot/dfu/openocd 共用)。
*
* 跑一条校验命令,exit 0 = ok。fail-closed:非 0 → ok:false。
*
* @param plan 烧录计划。
* @param exec 注入的执行函数。
* @param verifyCmd 校验命令 + 参数。
* @returns VerifyResult。
*/
export async function exitCodeVerify(
plan: FlashPlanEx,
exec: ExecFn,
verifyCmd: { cmd: string; args: string[] },
): Promise<VerifyResult> {
const res = await exec(verifyCmd.cmd, verifyCmd.args);
const cmdStr = `${verifyCmd.cmd} ${verifyCmd.args.join(" ")}`;
if (res.exitCode !== 0) {
return {
ok: false,
reason: `${plan.method} verify failed: ${res.stderr.trim() || `exit ${res.exitCode}`}`,
verifyCommand: cmdStr,
};
}
return { ok: true, verifyCommand: cmdStr };
}
// ============================================================================
// FlashProvider 接口 —— Definition/Provider/Consumer 三角色之 Provider 契约
// ============================================================================
/**
* 安全烧录 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 每个 provider 封装一种烧录方法(dd/fastboot/dfu/openocd)的三段式安全流程:
* - plan(): 构建命令序列(FlashPlanEx)
* - run(): dryRun → 写 → verify 三段式编排(fail-closed)
* - verify(): 烧后校验(dd sha256 比对 / 其他 exitCode 校验)
*
* 新增烧录方法只需新建一个 provider 文件并 register,不改已有逻辑(开闭原则)。
*/
export interface FlashProvider {
/** provider 标识 = 烧录方法。 */
readonly id: FlashMethod;
/**
* 由 method + image + target + opts 构建烧录计划。
*
* 纯构建,不做 target 存在性/根盘校验(那是 dryRun 的职责)。
* 若 ctx.lsblk 提供,可做早期 fail-closed 根盘检查。
*
* @param opts 烧录参数(method/image/target 必填)。
* @param ctx 可选上下文(lsblk 行数组,用于早期根盘校验)。
* @returns FlashPlanEx。
* @throws {Error} method 不合法 / image 或 target 为空 / offset 不可解析。
*/
plan(opts: FlashPlanOptions, ctx?: { lsblk?: LsblkRow[] }): FlashPlanEx;
/**
* 三段式编排:dryRun(fail-closed)→ 写 → verify。
*
* - plan.dryRun !== false → 只 dry-run 不写真写
* - plan.verify === false → 跳过 verify
*
* @param plan 烧录计划(plan() 产出)。
* @param exec 注入的执行函数。
* @returns RunFlashResult。
*/
run(plan: FlashPlanEx, exec: ExecFn): Promise<RunFlashResult>;
/**
* 烧后校验。
*
* dd: 读回 sha256 比对;其他: exitCode 校验。
*
* @param plan 烧录计划(dryRun 填充了 expectedSha256/blockCount)。
* @param exec 注入的执行函数。
* @returns VerifyResult。
*/
verify(plan: FlashPlanEx, exec: ExecFn): Promise<VerifyResult>;
}

85
src/capabilities/lsp.ts Normal file
View File

@ -0,0 +1,85 @@
/**
* @module lsp
*
* 嵌入式 IDE 桥(on-demand stub)—— LSP 协议的占位接口。
*
* 场景:嵌入式 Agent 在交互式编辑(edit-strict / 交叉编译诊断回填)时需 LSP 能力
* (定义跳转、诊断、补全)。但 LSP 服务进程重、且依赖具体板侧工具链(clangd
* 交叉编译参数),on-demand 启动。本模块只定义接口 + 提供 no-op 默认实现,真实
* LSP 桥(spawn clangd / 持久 JSON-RPC)由后续模块接线,现以 NoopLspBridge 占位。
*
* 设计要点:
* - LspBridge 接口:initialize(opts) + shutdown(),最小契约。
* - NoopLspBridge:默认 no-op,initialize 永返回 {ok:true},shutdown 无副作用。
* - 纯逻辑,零 pi 依赖,可离线单测。
* - 不假装真实 LSP 能力(不做诊断/补全),只保证调用方在不接线时获得稳定 stub。
*/
// ============================================================================
// 类型契约 —— 下游依赖这些名字,不得改名
// ============================================================================
/** initialize 入参。 */
export interface LspInitOptions {
/** 工作区根 URI(如 "file:///workspace")。 */
rootUri: string;
/** 可选:额外初始化选项(透传给具体 LSP server)。 */
initializationOptions?: Record<string, unknown>;
}
/** initialize 返回。 */
export interface LspInitResult {
/** 是否成功。 */
ok: boolean;
/** 失败原因(ok=false 时)。 */
reason?: string;
}
/**
* LSP 桥接口。on-demand:调用方按需 initialize,用完 shutdown。
* 真实实现负责 spawn clangd / 持久 JSON-RPC;NoopLspBridge 为占位。
*/
export interface LspBridge {
/**
* 初始化 LSP 会话。
*
* @param opts 初始化参数(rootUri 必填)。
* @returns 初始化结果。
*/
initialize(opts: LspInitOptions): Promise<LspInitResult>;
/**
* 关闭 LSP 会话,释放资源。幂等。
*
* @returns 关闭完成。
*/
shutdown(): Promise<void>;
}
// ============================================================================
// NoopLspBridge —— 默认 no-op 实现(on-demand stub)
// ============================================================================
/**
* no-op LSP 桥。默认实现:initialize 永成功、shutdown 无副作用。
*
* 用于无真实 LSP 环境的占位,保证调用方代码路径在不接线时仍稳定运行。
* 不做任何诊断 / 补全 / 跳转 —— 只满足 {@link LspBridge} 契约。
*/
export class NoopLspBridge implements LspBridge {
/**
* 初始化:永返回 { ok: true }。
*
* @param _opts 初始化参数(on-demand stub 不消费)。
* @returns { ok: true }。
*/
async initialize(_opts: LspInitOptions): Promise<LspInitResult> {
return { ok: true };
}
/**
* 关闭:无副作用,永 resolve。幂等。
*/
async shutdown(): Promise<void> {
// no-op —— on-demand stub 无资源需释放
}
}

View File

@ -0,0 +1,184 @@
/**
* @module settings
*
* typed settings store —— 类型安全的运行时配置。
*
* 嵌入式 Agent 有大量运行时配置(超时、重试、寄存器表路径、板 ID……)。本 store
* 用泛型约束键集:构造时传入 defaults,get/set 的键被收窄到 defaults 的字面量键,
* 值类型跟随 defaults,杜绝魔法串键与类型漂移。
*
* 设计要点:
* - 构造深拷贝 defaults(隔离外部对 defaults 的后续篡改,含嵌套对象引用)。
* - get/set 由 keyof T 约束,编译期捕获未知键。
* - snapshot 返回深冻结副本(运行时不可变),调用方可安全传递 / 缓存。
* - 纯逻辑,零 pi 依赖,可离线单测。
*
* 见 src/core/sandbox-policy.ts 的深冻结范式(DEFAULT_BOARD_SANDBOX_POLICY)。
*/
// ============================================================================
// 内部工具 —— 深克隆 + 深冻结
// ============================================================================
/**
* 深克隆对象(递归复制)。用于构造时深拷贝 defaults 与 snapshot 前复制:先复制再
* 冻结,确保冻结不波及 store 内部状态。对非对象(string/number/...)原样返回;
* 数组逐元素递归克隆。
*
* 内置引用类型显式处理,避免落入 plain-object 分支被掏空:
* - Date:用 `new Date(getTime())` 复制(Date 无可枚举自有键,plain-object 分支
* 会产出空 `{}`,丢失值与类型)。
* - RegExp:用 `new RegExp(source, flags)` 复制。
* - Map:逐 entry 递归克隆键与值后重建。
* - Set:逐元素递归克隆后重建。
*
* @param obj 待克隆对象。
* @returns 与原对象无共享引用的深副本。
*/
function deepClone<T>(obj: T): T {
if (obj === null || typeof obj !== "object") return obj;
if (Array.isArray(obj)) {
return obj.map((e) => deepClone(e)) as unknown as T;
}
// Date:plain-object 分支会得空 {},须用构造器保值保类型
if (obj instanceof Date) {
return new Date(obj.getTime()) as unknown as T;
}
// RegExp:同上,source/flags 复制
if (obj instanceof RegExp) {
return new RegExp(obj.source, obj.flags) as unknown as T;
}
// Map:逐 entry 递归克隆键值(键/值可能含嵌套引用)
if (obj instanceof Map) {
const map = new Map<unknown, unknown>();
for (const [k, v] of obj as Map<unknown, unknown>) {
map.set(deepClone(k), deepClone(v));
}
return map as unknown as T;
}
// Set:逐元素递归克隆
if (obj instanceof Set) {
const set = new Set<unknown>();
for (const v of obj as Set<unknown>) {
set.add(deepClone(v));
}
return set as unknown as T;
}
const clone: Record<string, unknown> = {};
for (const key of Object.keys(obj as Record<string, unknown>)) {
clone[key] = deepClone((obj as Record<string, unknown>)[key]);
}
return clone as unknown as T;
}
/**
* 深冻结对象(递归 Object.freeze)。用于 snapshot 输出,保证运行时不可变。
* 调用方须确保传入的是独占副本(见 {@link deepClone}),否则会原地冻结共享引用。
* 对非对象(string/number/...)原样返回。
*
* 内置容器递归冻结以与 {@link deepClone} 对齐:
* - Map:冻结 Map 本身并递归冻结各键/值。
* - Set:冻结 Set 本身并递归冻结各元素。
* - Date/RegExp:冻结对象本身即可(无可变嵌套引用)。
*
* @param obj 待冻结对象(须为独占副本)。
* @returns 冻结后的对象(Readonly)。
*/
function deepFreeze<T>(obj: T): Readonly<T> {
if (obj === null || typeof obj !== "object") return obj as Readonly<T>;
if (obj instanceof Map) {
for (const [k, v] of obj as Map<unknown, unknown>) {
if (k !== null && typeof k === "object" && !Object.isFrozen(k)) deepFreeze(k);
if (v !== null && typeof v === "object" && !Object.isFrozen(v)) deepFreeze(v);
}
Object.freeze(obj);
return obj as Readonly<T>;
}
if (obj instanceof Set) {
for (const v of obj as Set<unknown>) {
if (v !== null && typeof v === "object" && !Object.isFrozen(v)) deepFreeze(v);
}
Object.freeze(obj);
return obj as Readonly<T>;
}
Object.freeze(obj);
for (const key of Object.keys(obj as Record<string, unknown>)) {
const v = (obj as Record<string, unknown>)[key];
if (v !== null && typeof v === "object" && !Object.isFrozen(v)) {
deepFreeze(v);
}
}
return obj as Readonly<T>;
}
// ============================================================================
// 类型契约
// ============================================================================
/** 构造选项。 */
export interface SettingsStoreOptions<T extends object> {
/** 初始 defaults(深拷贝隔离)。 */
defaults: T;
}
// ============================================================================
// SettingsStore —— typed settings
// ============================================================================
/**
* 类型安全 settings store。
*
* 泛型 T 约束键集与值类型:构造传入 defaults,后续 get/set 的键被收窄到 keyof T,
* 值类型为 T[K]。默认泛型 Record<string, unknown> 兼容无强类型场景。
*
* @example
* const s = new SettingsStore({ retries: 3, boardId: "x5" });
* s.set("retries", 5); // ok
* s.get("boardId"); // "x5"
* s.snapshot(); // 深冻结只读副本
*/
export class SettingsStore<T extends object = Record<string, unknown>> {
private readonly store: T;
/**
* @param defaults 初始默认值;深拷贝以隔离外部篡改(含嵌套对象引用)。
*/
constructor(defaults: T) {
// 深拷贝:隔离外部对 defaults 任意层级(含嵌套对象)的后续 mutation,
// 避免调用方篡改 defaults 嵌套字段回渗污染 store 内部状态。
this.store = deepClone(defaults);
}
/**
* 取某项配置。
*
* @param k 配置键(keyof T)。
* @returns 配置值。
*/
get<K extends keyof T>(k: K): T[K] {
return this.store[k];
}
/**
* 设某项配置。键由 keyof T 约束,编译期拒绝未知键。
*
* @param k 配置键。
* @param v 配置值(类型跟随 T[K])。
*/
set<K extends keyof T>(k: K, v: T[K]): void {
this.store[k] = v;
}
/**
* 返回当前全部配置的深冻结只读副本。调用方可安全传递 / 缓存,不影响内部状态。
*
* 实现先 {@link deepClone} 复制全部嵌套引用,再 {@link deepFreeze} 冻结副本,
* 确保冻结不波及内部 store 的嵌套对象。构造亦已深拷贝 defaults,故内部 store
* 与调用方传入的 defaults 无共享嵌套引用。
*
* @returns 深冻结只读副本(与内部状态无共享引用)。
*/
snapshot(): Readonly<T> {
return deepFreeze(deepClone({ ...this.store }));
}
}

View File

@ -0,0 +1,278 @@
/**
* @module capabilities/subagent
*
* 子代理能力接缝(T12)—— spawn-in-process 子 agent + 作用域隔离注册表。
*
* 治嵌入式开发场景下"主 agent 单线推进、无法把可并行的子任务(编译/探板/
* datasheet RAG)分派给隔离子 agent"的缺陷。本模块提供:
* ① SubagentProvider 抽象 + InlineSubagentProvider(spawn-in-process 实现)
* ② SubagentRegistry(register/resolve,fail-closed 无匹配抛错)
* ③ isolatedSubagentScope —— 把任意 scope 挂到 "subagent" 命名空间根下,
* 使子 agent 作用域与主 agent 作用域互不为祖孙(T07 scopeReceives 双向
* 不匹配),故子 agent 事件不串主 agent(核心隔离不变式)。
*
* 作用域隔离不变式(靠 T07 ScopeKey,见 tests/workflow.test.ts ⑥):
* - 主 agent 监听 scope=M,子 agent emit scope="subagent…":
* "subagent…" 不以 M 为段前缀(除非 M 恰为 "subagent",但主 agent 不应监听
* 此根)→ scopeReceives 返回 false → 主 agent 不收子 agent 事件(不串)。
* - 主 agent emit scope=M,子 agent 监听 scope="subagent…":
* M 非 "subagent…" 的祖先后缀 → scopeReceives 返回 false → 子 agent 不收
* 主 agent 事件(不下渗)。
* - 双向不串:子 agent 事件不污染主 agent,主 agent 事件不下渗子 agent。
* 需要观测子 agent 的集成层可在 scope="subagent"(根)注册监听收全部子 agent
* 事件,这不破坏隔离——主 agent 仍只监听自己的 scope。
*
* 纯逻辑:顶层仅 `import type`(esbuild 擦除),零 pi 运行时依赖,无硬件。
* tests 直接 import 命名导出即可离线单测。与 tool-pipeline / sandbox-policy /
* board-link 的注册器范式同源(disposer + fail-closed resolve + 深冻结常量)。
*
* 见架构设计文档_v3.md §7(T12)/ Docs/T08_能力接缝三角色.md。
*/
import type { ScopeKey } from "../../core/pba-event-bus.js";
// ============================================================================
// 命名常量 —— 消灭魔法串(隔离根 / 默认 provider id)
// ============================================================================
/**
* 子代理事件隔离根作用域前缀。
*
* 所有子 agent 作用域都挂在此根下("subagent.<…>"),与主 agent 作用域
* (任意非 "subagent" 前缀的路径)互不为祖孙,实现双向事件不串。深冻结。
*/
export const SUBAGENT_SCOPE_ROOT = "subagent" as const;
/**
* InlineSubagentProvider 的默认 id。
*
* 单实例 spawn-in-process 场景的默认注册键;需注册多个 inline provider 时
* 构造器显式传不同 id 即可。深冻结。
*/
export const INLINE_SUBAGENT_ID = "inline-subagent" as const;
// ============================================================================
// 类型契约
// ============================================================================
/**
* 子代理 spawn 结果。
*
* - ok=true 时 value 携带 handler 返回值;error 缺省。
* - ok=false 时 error 携带失败原因(handler 抛错 / 超时);value 缺省。
* - scope 始终为子 agent 实际运行所在的隔离作用域键(经 isolatedSubagentScope 派生)。
*
* fail-closed:handler 抛错或超时绝不向上传播,统一转成 ok:false 结果,
* 由调用方决定如何处理(与 tool-pipeline 的 timeout around 容器同道)。
*/
export interface SubagentResult {
/** true=handler 正常返回;false=抛错或超时。 */
readonly ok: boolean;
/** handler 返回值(ok=true 时)。 */
readonly value?: unknown;
/** 失败原因(ok=false 时)。 */
readonly error?: string;
/** 子 agent 实际运行的隔离作用域键("subagent…" 形式)。 */
readonly scope: string;
}
/**
* spawn 选项。
*/
export interface SubagentSpawnOptions {
/**
* 语义作用域提示。经 isolatedSubagentScope 挂到 "subagent" 根下后作为子 agent
* 的隔离作用域;缺省则用序号派生唯一键。无论传什么,最终 scope 都隔离于主 agent。
*/
readonly scope?: string;
/** 超时毫秒;超时转 ok:false(fail-closed,不抛)。缺省=不限。 */
readonly timeoutMs?: number;
}
/**
* 子代理 Provider —— Definition/Provider/Consumer 三角色之 Provider。
*
* 每个封装一种 spawn 后端(in-process / 真 pi subagent / 远程 agent)。
* id 是注册键(与 BoardLinkProvider / ProviderDescriptor 同道)。
*/
export interface SubagentProvider {
/** provider 唯一标识(注册键)。 */
readonly id: string;
/**
* 派生一个子 agent 执行 prompt,返回隔离结果。
*
* @param prompt 子 agent 的任务提示。
* @param opts scope 提示 + 超时。
* @returns SubagentResult(fail-closed,绝不 reject)。
*/
spawn(prompt: string, opts?: SubagentSpawnOptions): Promise<SubagentResult>;
}
// ============================================================================
// isolatedSubagentScope —— 作用域隔离(纯函数,确定性可测)
// ============================================================================
/**
* 把任意 scope 挂到 "subagent" 命名空间根下,保证与主 agent 作用域双向不串。
*
* 归一(按 "." 切段、滤空段)后前缀 SUBAGENT_SCOPE_ROOT:
* - undefined / "" / " " → "subagent"(仅根,仍隔离)
* - "compile" → "subagent.compile"
* - "main.task" → "subagent.main.task"
* - "a..b" / ".b" → "subagent.a.b"(滤空段)
*
* 隔离保证(T07 scopeReceives):派生后的 scope 恒以 "subagent" 为段前缀,
* 任何非 "subagent" 前缀的主 agent 作用域 M 都不是它的祖先也不是后代,
* 故主 agent emit/监听 与 子 agent emit/监听 互不派发(双向不串)。
*
* @param scope 原始作用域提示(可 undefined)。
* @returns 挂在 "subagent" 根下的隔离作用域键。
*/
export function isolatedSubagentScope(scope: string | undefined): ScopeKey {
const segs = (scope ?? "").split(".").filter((s) => s.length > 0);
return segs.length === 0 ? SUBAGENT_SCOPE_ROOT : `${SUBAGENT_SCOPE_ROOT}.${segs.join(".")}`;
}
// ============================================================================
// InlineSubagentProvider —— spawn-in-process 实现
// ============================================================================
/**
* spawn-in-process 子代理 provider —— 跑一个注入的 handler 函数。
*
* - 构造器收 handler:`(prompt, opts?) => Promise<unknown>`。opts 只含 scope
* (handler 不负责超时,超时由 provider 在外层 race 包裹)。
* - spawn 派生隔离 scope(isolatedSubagentScope),把派生后的 scope 透传给 handler,
* 使 handler 在隔离作用域上下文内运行;记录 scope 进 SubagentResult。
* - 超时(opts.timeoutMs):handler 与 timer 竞速,超时转 ok:false(fail-closed)。
* - handler 抛错:转 ok:false + error 串(绝不向上传播 reject)。
*
* @param handler 在进程内跑子 agent 任务的函数(注入以便单测 mock)。
* @param id 注册键;缺省 INLINE_SUBAGENT_ID。需注册多个 inline provider 时传不同 id。
*/
export class InlineSubagentProvider implements SubagentProvider {
readonly id: string;
private readonly handler: (prompt: string, opts?: { scope?: string }) => Promise<unknown>;
constructor(
handler: (prompt: string, opts?: { scope?: string }) => Promise<unknown>,
id: string = INLINE_SUBAGENT_ID,
) {
this.handler = handler;
this.id = id;
}
/** @inheritdoc */
async spawn(prompt: string, opts?: SubagentSpawnOptions): Promise<SubagentResult> {
const scope = isolatedSubagentScope(opts?.scope);
try {
const value = await runWithTimeout(this.handler(prompt, { scope }), opts?.timeoutMs);
return { ok: true, value, scope };
} catch (e) {
return { ok: false, error: errorMessage(e), scope };
}
}
}
// ============================================================================
// SubagentRegistry —— 可注册/解析的子代理表
// ============================================================================
/**
* 子代理 Provider 注册表 —— 维护 id → provider 映射。
*
* - register(p): 按 p.id 存储,返回 disposer。disposer 只在"仍是同一 provider 实例"
* 时移除——避免后注册的同 id provider 被前者的 disposer 误删(override 安全,
* 与 BoardLinkRegistry / ProviderRegistry 同道)。
* - resolve(id): fail-closed,未知 id 抛错(无 provider = 拒绝 spawn,不静默回退)。
* - list(): 只读快照(调用方不可篡改内部状态)。
*
* 重复 id 视为更新(替换),保证 barrel 重装配 / session resume 幂等安全。
*/
export class SubagentRegistry {
/** id → provider(插入序,Map 保证)。 */
private readonly providers = new Map<string, SubagentProvider>();
/**
* 注册一个 provider。重复 id 视为更新(替换),旧 disposer 失效。
*
* @param provider 子代理 provider。
* @returns disposer——调用后从注册表移除该 provider(仅当仍是同一实例时移除)。
*/
register(provider: SubagentProvider): () => void {
this.providers.set(provider.id, provider);
return () => {
if (this.providers.get(provider.id) === provider) {
this.providers.delete(provider.id);
}
};
}
/**
* 按 id 解析 provider。
*
* fail-closed:未知 id 抛错(绝不返回 undefined 让调用方裸调,避免误用未配置子代理)。
*
* @param id provider 注册键。
* @returns 匹配的 SubagentProvider。
* @throws {Error} 未注册该 id。
*/
resolve(id: string): SubagentProvider {
const provider = this.providers.get(id);
if (!provider) {
throw new Error(`[subagent] no provider registered for id "${id}" (fail-closed)`);
}
return provider;
}
/**
* 列出全部已注册 provider(只读快照,按插入序)。
*
* @returns 只读 provider 数组。
*/
list(): readonly SubagentProvider[] {
return [...this.providers.values()];
}
}
// ============================================================================
// 内部工具 —— 超时竞速 + 错误归一(纯逻辑,无副作用泄漏)
// ============================================================================
/**
* handler 与超时竞速。超时 reject(由 spawn 的 catch 转成 ok:false)。
*
* - ms 缺省/非有限正 → 不限时,直透 promise。
* - 超时 reject Error("subagent spawn timeout after <ms>ms")。
* - finally 清 timer,防句柄泄漏。
*
* @param p handler promise。
* @param ms 超时毫秒(可选)。
* @returns handler 的值;超时则 reject。
*/
function runWithTimeout<T>(p: Promise<T>, ms: number | undefined): Promise<T> {
if (ms === undefined || !Number.isFinite(ms) || ms <= 0) return p;
let timer: ReturnType<typeof setTimeout> | undefined;
return Promise.race([
p,
new Promise<never>((_resolve, reject) => {
timer = setTimeout(
() => reject(new Error(`subagent spawn timeout after ${ms}ms`)),
ms,
);
}),
]).finally(() => {
if (timer !== undefined) clearTimeout(timer);
});
}
/**
* 把 unknown 错误归一为可读串。
*
* @param e 抛出的值。
* @returns Error.message 或 String(e)。
*/
function errorMessage(e: unknown): string {
if (e instanceof Error) return e.message;
return String(e);
}

View File

@ -0,0 +1,172 @@
/**
* @module capabilities/workflow
*
* 工作流编排原语(T12)—— loop-orchestrator 上层的并发/串行编排引擎。
*
* 三个纯逻辑原语,正交、单一职责:
* ① parallel —— barrier 原语:全等齐(Promise.allSettled 语义),单 thunk 抛错
* → 该位落 null(不 reject)。用于编译(宿主)+ 探板(板)+ datasheet RAG
* (宿主)三并发。
* ② pipeline —— 流水线原语:每 item 过全 stage,stage 间无全局 barrier(item 在
* 有界并发下独立流过 stage 链),stage 抛错 → item 落 null 跳后续 stage。
* 用于 edit→compile→flash→verify 串行(单板物理约束下 items 长度=1)。
* ③ phase —— 进度标记锚点(no-op;记录委托给集成层 T07 事件总线 / pi UI)。
*
* 设计决策:
* - parallel 不限并发("barrier:全等齐"= 等全部 settle,不是限流)。需限流的
* 调用方自行分片或用 pipeline(pipeline 按 MAX_CONCURRENCY 限 item 并发)。
* - pipeline 按 MAX_CONCURRENCY 限 item 并发;每 item 串行过 stage(stage[i+1]
* 需 stage[i] 的 prev)。stage 间无全局 barrier = item 不在 stage 边界等齐
* 其余 item,可同时处于不同 stage(streaming 语义)。
* - 结果保序:result[i] 恒对应 items[i](pipeline)/ thunks[i](parallel)。
* - 无顶层可变状态:runWithConcurrency 是纯函数式并发限制器(cursor 在单线程
* 事件循环内单调推进,无真并行竞态);phase 是无副作用锚点,绝不持模块级
* 可变集合(禁隐式全局)。
*
* 纯逻辑:顶层零 import(无 pi 运行时、无 node 内置依赖),确定性可测。
* 见架构设计文档_v3.md §7(T12)/ §11(G7 上层 workflow)。
*/
// ============================================================================
// 命名常量 —— 消灭魔法串(并发上限)
// ============================================================================
/**
* pipeline 的默认 item 并发上限。
*
* 物理单板串行场景调用方传 items 长度=1(loop-orchestrator 已强制单板串行);
* 非硬件批处理场景(如多源 datasheet 并行解析)用 8 作合理上限,防 promise 风暴。
* 深冻结,运行时不可变。
*/
export const MAX_CONCURRENCY: Readonly<number> = Object.freeze(8) as number;
// ============================================================================
// ① parallel —— barrier 原语
// ============================================================================
/**
* 并发执行全部 thunk,等齐后返回(barrier 语义)。
*
* - 全部 thunk 立即并发启动(map 内调 t())。
* - 用 Promise.allSettled 等全部 settle:fulfilled → 取 value;rejected → 该位 null。
* - 单 thunk 抛错绝不向上传播(不 reject),只把对应位落 null;其余位不受影响。
* - 结果保序:result[i] 对应 thunks[i]。
* - 空 thunk 数组 → 空结果数组。
*
* @param thunks 待并发执行的零参 async 函数数组(只读)。
* @returns 与 thunks 同序的结果数组;rejected thunk 位为 null。
*/
export async function parallel(
thunks: ReadonlyArray<() => Promise<unknown>>,
): Promise<unknown[]> {
// 用 Promise.resolve().then(t) 包裹每个 thunk:把同步 throw 转成被 allSettled
// 吸收的 rejection(落 null),兑现"单 thunk 抛错绝不向上传播"的不变式——
// 否则 t() 同步抛错会逃逸 map,allSettled 从未执行,parallel 整体 reject。
const settled = await Promise.allSettled(
thunks.map((t) => Promise.resolve().then(t)),
);
return settled.map((s) => (s.status === "fulfilled" ? s.value : null));
}
// ============================================================================
// ② pipeline —— 流水线原语
// ============================================================================
/**
* 把每个 item 串行流过全部 stage,返回每 item 的终态。
*
* 语义:
* - 每 item 依次过 stage[0] → stage[1] → … → stage[n-1];stage[i+1] 收 stage[i]
* 的返回值作 prev(stage[0] 收 undefined 作 prev)。
* - stage 间无全局 barrier:item 在 MAX_CONCURRENCY 有界并发下独立流过 stage
* 链,不等待其余 item 在 stage 边界对齐(streaming 语义)。
* - stage 抛错 → 该 item 落 null,跳过其后续 stage(fail-soft per-item)。
* - 结果保序:result[i] 恒对应 items[i];未失败 item 的终态 = 末 stage 返回值
* (stages 为空时终态 = item 本身,identity 语义)。
* - 空 items → 空结果数组。
*
* @param items 待流水线处理的 item 数组(只读)。
* @param stages 有序 stage 函数:`(prev, item, i) => Promise<unknown>`。
* @returns 与 items 同序的结果数组;stage 抛错的 item 位为 null。
*/
export async function pipeline<T>(
items: ReadonlyArray<T>,
...stages: Array<(prev: unknown, item: T, i: number) => Promise<unknown>>
): Promise<unknown[]> {
const results: unknown[] = new Array(items.length).fill(null);
await runWithConcurrency(items, MAX_CONCURRENCY, async (item, i) => {
let prev: unknown = undefined;
for (const stage of stages) {
try {
prev = await stage(prev, item, i);
} catch {
// stage 抛错:该 item 落 null(results[i] 已初始化为 null),跳后续 stage。
return;
}
}
// stages 为空 → identity(终态 = item 本身);否则终态 = 末 stage 返回值。
results[i] = stages.length === 0 ? item : prev;
});
return results;
}
// ============================================================================
// ③ phase —— 进度标记锚点(no-op)
// ============================================================================
/**
* 标记一个编排阶段进度。no-op:不影响控制流,无返回值,无副作用。
*
* "仅记录"= 逻辑上标记阶段边界,但实际记录(日志/UI notify/事件总线 emit)
* 委托给集成层(T07 PbaEventBus emit / pi UI notify)。本函数作为编排代码中
* 稳定的阶段锚点存在——集成层可在调用点外包 phase 调用来观测进度,而
* parallel/pipeline 原语本身不耦合观测(保持纯逻辑、可离线单测)。
*
* 不持模块级可变集合(禁隐式全局);故多次调用彼此独立,无累积状态。
*
* @param name 阶段名(如 "compile-phase")。
*/
export function phase(name: string): void {
// no-op 锚点:void name 消费参数防 lint unused 警告,无运行时效果。
void name;
}
// ============================================================================
// 内部:有界并发执行器(纯函数式,cursor 在单线程事件循环内单调推进)
// ============================================================================
/**
* 在有界并发下对 items 跑 fn,全部完成后 resolve(barrier)。
*
* - limit 经 Math.max(1, min(limit, items.length)) 钳制;items 为空立即 resolve。
* - 起 effectiveLimit 个 worker,每个循环从 cursor 取下一个未处理 item;
* cursor 在单线程事件循环内 ++ 单调推进(await 切点间无真并行,无竞态)。
* - fn 抛错不阻断其余 item(fn 内部应自行 try/catch 或让 pipeline 的 per-item
* 语义吸收;此执行器把 fn 视为已封装)。
*
* @param items 待处理 item 数组(只读)。
* @param limit 并发上限。
* @param fn 处理单个 item 的函数(收 item + index)。
*/
async function runWithConcurrency<T>(
items: ReadonlyArray<T>,
limit: number,
fn: (item: T, index: number) => Promise<void>,
): Promise<void> {
if (items.length === 0) return;
const effectiveLimit = Math.max(1, Math.min(limit, items.length));
let cursor = 0;
const worker = async (): Promise<void> => {
while (cursor < items.length) {
const idx = cursor;
cursor++;
if (idx >= items.length) return;
await fn(items[idx], idx);
}
};
const workers: Promise<void>[] = [];
for (let w = 0; w < effectiveLimit; w++) {
workers.push(worker());
}
await Promise.all(workers);
}

178
src/compaction/spill.ts Normal file
View File

@ -0,0 +1,178 @@
/**
* @module compaction/spill
*
* 大结果溢出句柄库(T09 第四件)—— 治 datasheet/大回包占爆上下文。
*
* datasheet RAG 命中的整页文本、i2cdump 全量寄存器表动辄数十 KB,若原样塞进 LLM 上下文
* 会瞬间超压。spill 把这些大结果暂存进带 brand 的句柄,模型上下文里只留一个不透明 locator,
* 需要时 recall 取回。句柄是 nominal brand(外部不可伪造),只由 SpillStore 发放。
*
* 纯逻辑:数据存内存 Map(注入式存储可测);TextEncoder 算字节(web 标准,无 pi 依赖);
* evict 按序列化字节大小回收容量。零 pi 运行时依赖,离线可单测。
*
* 范式:纯逻辑,零依赖,零副作用(除内部 Map 状态),确定性可测。
* 见架构设计文档_v3.md §6.2。
*/
// ============================================================================
// 命名常量 —— 消灭魔法串
// ============================================================================
/** locator 前缀(brand 之外的明文命名空间,便于诊断)。 */
const LOCATOR_PREFIX = "pba-spill";
/** locator 各段分隔符。 */
const LOCATOR_SEP = ":";
// ============================================================================
// 类型契约
// ============================================================================
/**
* 溢出句柄(nominal brand,外部不可伪造)。
*
* 仅 SpillStore.spill 能产出合法 SpillLocator;recall/has 只认此类型。
* 运行时底层是字符串,但 TS brand 阻止外部直接构造(brand 字段不导出构造器)。
*/
export type SpillLocator = string & { readonly __brand: "SpillLocator" };
/** 内部存储条目:原始数据 + 序列化字节大小。 */
interface SpillEntry {
readonly data: unknown;
readonly bytes: number;
}
// ============================================================================
// 内部纯函数:locator 构造 + 字节度量
// ============================================================================
/**
* 把 key + 序号封成 SpillLocator(brand 注入,仅本模块可调)。
*
* @param key 调用方语义键。
* @param seq 单调序号(同 key 唯一化)。
* @returns branded locator 句柄。
*/
function makeLocator(key: string, seq: number): SpillLocator {
return `${LOCATOR_PREFIX}${LOCATOR_SEP}${key}${LOCATOR_SEP}${seq}` as SpillLocator;
}
/** 全局 TextEncoder(复用,避免反复构造)。 */
const encoder = new TextEncoder();
/**
* 度量任意值的 UTF-8 序列化字节大小(evict 容量回收依据)。
*
* fail-soft:不可 JSON 序列化(循环)→ 退回 String(value) 的字节长度,不抛错。
* 注意 JSON.stringify(undefined) 返回 undefined(非字符串、且不抛),故对 try 块
* 结果做 typeof string 守卫:非字符串一律退回 String(value),杜绝把 undefined 赋给
* text 后 `text.length` 解引用抛 TypeError(破坏文档化 fail-soft 契约)。
*
* @param value 任意值。
* @returns UTF-8 字节长度(≥ 0)。
*/
function measureBytes(value: unknown): number {
let text: string;
try {
text = JSON.stringify(value);
} catch {
text = String(value);
}
// JSON.stringify 对 undefined/function/symbol 返 undefined(非字符串、不抛),
// 必须退回 String(value) 守卫,否则 text.length 解引用抛 TypeError。
if (typeof text !== "string") {
text = String(value);
}
if (text.length === 0) return 0;
return encoder.encode(text).length;
}
// ============================================================================
// SpillStore
// ============================================================================
/**
* 大结果溢出句柄库。
*
* - spill(key, data):暂存大结果,返 branded locator(上下文里只留 locator)。
* - recall(locator):取回原数据;未知 locator → undefined(fail-closed)。
* - has(locator):存在性查询。
* - evict(olderThanBytes?):容量回收;undefined → 清空全部;否则回收字节 > 阈值的条目。
*
* 内部用 Map 保持插入序,evict 在超阈值集合内按插入序回收(FIFO 语义)。
*/
export class SpillStore {
/** 句柄 → 条目(插入序)。 */
private readonly store = new Map<string, SpillEntry>();
/** key → 已发序号(同 key 的自增计数)。 */
private readonly seqByKey = new Map<string, number>();
/**
* 暂存大结果,返 branded locator 句柄。
*
* 同一 key 可多次 spill(序号自增),每次返不同 locator。
*
* @param key 调用方语义键(如 "datasheet:rmii")。
* @param data 任意可序列化大结果。
* @returns branded locator 句柄。
*/
spill(key: string, data: unknown): SpillLocator {
const seq = (this.seqByKey.get(key) ?? 0) + 1;
this.seqByKey.set(key, seq);
const locator = makeLocator(key, seq);
this.store.set(locator, { data, bytes: measureBytes(data) });
return locator;
}
/**
* 取回溢出数据。
*
* fail-closed:未知 locator(含被 evict 回收的)→ undefined。
*
* @param locator SpillStore 发放的 branded 句柄。
* @returns 原数据;不存在时 undefined。
*/
recall(locator: SpillLocator): unknown {
return this.store.get(locator)?.data;
}
/**
* 查询 locator 是否仍存活(未被 evict 回收)。
*
* @param locator branded 句柄。
* @returns 存在 true;否则 false。
*/
has(locator: SpillLocator): boolean {
return this.store.has(locator);
}
/**
* 容量回收。
*
* - olderThanBytes 缺省:清空全部条目,返回被清条数(full reclaim)。
* 注意:full reclaim 只清 store,不清 seqByKey —— seq 必须单调续号,
* 否则 evict 后同 key 再 spill 会让 seq 重置为 1,复用刚被回收的 locator 字符串,
* 致已 evict 的旧 locator 引用静默解析为新数据(违反 fail-closed 不变式)。
* - olderThanBytes 给定:回收序列化字节 > olderThanBytes 的条目(大 blob 优先回收),
* 返回回收条数。阈值用 ">" 而非 ">=" —— 恰等于阈值的条目保留(边界值友好)。
*
* @param olderThanBytes 字节阈值(可选)。
* @returns 被回收的条数(≥ 0)。
*/
evict(olderThanBytes?: number): number {
if (olderThanBytes === undefined) {
const n = this.store.size;
this.store.clear();
// 故意不清 seqByKey:让 seq 单调续号,evict 后同 key 再 spill 用新 seq,
// 不复用已回收的 locator 字符串(fail-closed 不变式)。
return n;
}
let evicted = 0;
for (const [loc, entry] of this.store) {
if (entry.bytes > olderThanBytes) {
this.store.delete(loc);
evicted++;
}
}
return evicted;
}
}

View File

@ -0,0 +1,159 @@
/**
* @module compaction/summarizer
*
* 上下文压缩摘要构建器(T09 第三件)—— compaction 压力触发后的 model-free 摘要。
*
* 当 token-meter 测出上下文超压时,compaction 需把近期 entry 压成一段摘要喂回模型。
* 本模块重放稳定前缀(prefix,命中 KV prefix cache)+ append 一条压缩指令(近期 entry 的
* 结构化摘要),全程不调 LLM(model-free 确定性摘要),故离线可单测。
*
* reusedPrefix 语义:prefix 非空 → 标记 true(前缀是已缓存段的逐字重放,模型 KV prefix
* cache 可复用,不重算);prefix 空 → false(冷启动,无前缀可复用)。
*
* 范式:纯逻辑,仅 import type 自 T06 surface + import 同仓 token-meter;
* 零 pi 运行时依赖,零副作用,确定性可测。见架构设计文档_v3.md §5.1 / §6.2。
*/
import type { PbaSessionEntry } from "../core/pba-session.js";
import { estimateTokens } from "./token-meter.js";
// ============================================================================
// 命名常量 —— 消灭魔法串/魔法数
// ============================================================================
/** 压缩指令的标题(摘要正文里标记压缩段起点)。 */
const DIRECTIVE_HEADER = "## Compaction Summary";
/** 单条 entry 摘要的最大字符数(超出加省略号,控制摘要体积)。 */
const DIGEST_MAX_CHARS = 120;
/** 摘要省略号。 */
const ELLIPSIS = "…";
// ============================================================================
// 类型契约
// ============================================================================
/**
* compaction 摘要结果。
*
* @property summary 重放前缀 + 压缩指令 + 近期 entry 摘要(受 maxTokens 约束)。
* @property reusedPrefix 是否复用了非空前缀(KV prefix cache 命中语义)。
* @property droppedEntries 被压缩进摘要、从活跃上下文移除的 entry 数。
*/
export interface CompactionSummary {
readonly summary: string;
readonly reusedPrefix: boolean;
readonly droppedEntries: number;
}
/** recentEntries 元素形状:取自 T06 surface entry 的 {type,data} 投影。 */
type RecentEntry = Pick<PbaSessionEntry, "type" | "data">;
// ============================================================================
// 内部纯函数:entry 摘要 + token 预算裁剪
// ============================================================================
/**
* 把单条 entry 压成一行摘要(type + 截断后的 data JSON)。
*
* fail-soft:data 不可 JSON 序列化(含循环)→ 退回 "[unserializable]"。
*
* @param entry 会话 entry(type + data)。
* @returns 形如 `- tool-result: {"name":"i2cdump",...}` 的摘要行。
*/
function digestEntry(entry: RecentEntry): string {
let body: string;
try {
body = JSON.stringify(entry.data);
} catch {
body = "[unserializable]";
}
if (body.length > DIGEST_MAX_CHARS) {
body = body.slice(0, DIGEST_MAX_CHARS) + ELLIPSIS;
}
return `- ${entry.type}: ${body}`;
}
/**
* 在 token 预算内从最新端保留尽可能多的摘要行(drop 最旧的)。
*
* 摘要行按时间顺序 oldest→newest;超预算时从头部丢弃最旧行,保留最新上下文。
* base(前缀+指令)始终保留不被裁剪(前缀是 KV cache 复用段,不可截断)。
*
* @param digestLines entry 摘要行数组(oldest→newest)。
* @param base 基础文本(前缀 + 指令头,始终保留)。
* @param maxTokens token 预算上限。
* @returns 保留的摘要行数组 + 是否裁剪过。
*/
function fitDigestsToBudget(
digestLines: readonly string[],
base: string,
maxTokens: number,
): { kept: string[]; trimmed: boolean } {
const kept = [...digestLines];
let trimmed = false;
// 估算 base + 当前 kept 的总 token;超预算则从最旧端(头部)逐行丢弃。
const estimateAll = (): number =>
estimateTokens(base) +
(kept.length > 0 ? estimateTokens(kept.join("\n")) : 0);
while (kept.length > 0 && estimateAll() > maxTokens) {
kept.shift();
trimmed = true;
}
// base 自身超预算时:不再加摘要行(前缀不可截断,仅记录裁剪)。
if (kept.length === 0 && estimateTokens(base) > maxTokens) {
trimmed = digestLines.length > 0;
}
return { kept, trimmed };
}
// ============================================================================
// 主入口
// ============================================================================
/**
* 构建 compaction 摘要:重放前缀 + append 压缩指令 + 近期 entry 摘要。
*
* 流程(确定性、model-free):
* 1. reusedPrefix = prefix.trim() 非空;
* 2. base = [prefix?, DIRECTIVE_HEADER + 计数说明];
* 3. 为每条 recentEntry 生成一行摘要(type + 截断 data JSON);
* 4. 在 maxTokens 预算内从最新端保留尽可能多摘要行(drop 最旧);
* 5. summary = base + 保留摘要行;droppedEntries = recentEntries.length。
*
* 前缀始终保留(KV prefix cache 复用语义,不可截断);超预算只裁摘要行。
*
* @param opts.prefix 稳定前缀(已缓存段的逐字重放)。
* @param opts.recentEntries 近期会话 entry(type + data,oldest→newest)。
* @param opts.maxTokens 摘要 token 预算上限。
* @returns compaction 摘要结果。
*/
export function buildCompactionSummary(opts: {
prefix: string;
recentEntries: ReadonlyArray<RecentEntry>;
maxTokens: number;
}): CompactionSummary {
const { prefix, recentEntries, maxTokens } = opts;
const reusedPrefix = prefix.trim().length > 0;
const directiveLine =
`${DIRECTIVE_HEADER}\n` +
`${recentEntries.length} recent entries compacted (model-free digest):`;
const baseParts: string[] = [];
if (reusedPrefix) baseParts.push(prefix);
baseParts.push(directiveLine);
const base = baseParts.join("\n\n");
const digestLines = recentEntries.map(digestEntry);
const { kept } = fitDigestsToBudget(digestLines, base, maxTokens);
const summary =
kept.length > 0 ? `${base}\n${kept.join("\n")}` : base;
return {
summary,
reusedPrefix,
droppedEntries: recentEntries.length,
};
}

View File

@ -0,0 +1,88 @@
/**
* @module compaction/token-meter
*
* 上下文 token 估算 —— compaction 的压力触发器(T09 第一件)。
*
* 嵌入式 agent 的工具输出(i2cdump/gdb/dmesg)动辄数 KB,会快速吃满模型上下文窗。
* token-meter 给 compaction 一个 model-free 的 token 估算,供 summarizer 判断"何时压"
* 与"压完多大"。不依赖任何 tokenizer(pi 运行时无依赖),故离线可单测。
*
* 启发式(文档化、确定性):
* - ASCII/拉丁部分:chars/4(OpenAI 系 tokenizer 的经验上界,glm-5.2 同量级)
* - CJK 统一表意部分:每 char 计 1 token(CJK 常被逐字切分,char 计更准)
* - 二者叠加取整上界,空串返回 0
*
* 范式:纯逻辑,零依赖,零副作用,确定性可测。见架构设计文档_v3.md §5.1 / §6.2。
*/
// ============================================================================
// 命名常量 —— 消灭魔法数
// ============================================================================
/** 非部分每 N 字符折算 1 token(OpenAI/glm 经验上界)。 */
const LATIN_CHARS_PER_TOKEN = 4;
/** 每条消息的角色/结构开销 token(role tag + 分隔符的保守估算)。 */
const PER_MESSAGE_OVERHEAD_TOKENS = 4;
/**
* CJK 统一表意 + 扩展 A + 兼容表意的字符集(逐字计 1 token)。
* 深冻结:仅作为 RegExp 源字符范围,不运行时改写。
*/
const CJK_PATTERN = /[一-鿿㐀-䶿豈-﫿]/g;
// ============================================================================
// 估算原语
// ============================================================================
/**
* 统计文本中的 CJK 表意字符数(逐字计 token 的来源)。
*
* @param text 任意文本。
* @returns CJK 字符出现次数(非 CJK 计 0)。
*/
function countCjk(text: string): number {
let n = 0;
for (const _ of text.matchAll(CJK_PATTERN)) n++;
return n;
}
/**
* 估算一段文本的 token 数(model-free 启发)。
*
* - 空串 → 0
* - CJK 部分:每 char 计 1 token
* - 非 CJK 部分:⌈len/4⌉ token
* - 二者相加
*
* 确定性:同一输入恒同输出;不调任何 tokenizer,离线可测。
*
* @param text 待估文本。
* @returns token 估算值(≥ 0 整数)。
*/
export function estimateTokens(text: string): number {
if (text.length === 0) return 0;
const cjk = countCjk(text);
const nonCjk = text.length - cjk;
const nonCjkTokens = Math.ceil(nonCjk / LATIN_CHARS_PER_TOKEN);
return cjk + nonCjkTokens;
}
/**
* 估算一组消息的总上下文 token 数(含每条消息的结构开销)。
*
* 对每条消息累加 `estimateTokens(content) + PER_MESSAGE_OVERHEAD_TOKENS`,
* 反映 role 标签/分隔符在真实上下文里的固定开销。空消息数组 → 0。
*
* @param messages 模型消息序列(只读,不修改)。
* @returns 总 token 估算值(≥ 0 整数)。
*/
export function measureContext(
messages: ReadonlyArray<{ role: string; content: string }>,
): number {
let total = 0;
for (const m of messages) {
if (!m) continue;
total += estimateTokens(m.content ?? "") + PER_MESSAGE_OVERHEAD_TOKENS;
}
return total;
}

View File

@ -0,0 +1,227 @@
/**
* @module compaction/tool-result-pruner
*
* 工具大输出 model-free 压缩(T09 第二件)—— 治嵌入式场景的工具回包爆窗。
*
* i2cdump 一片寄存器表 ~256 行、gdb backtrace 数十帧、dmesg 滚屏数百行,
* 原样喂模型既吃 token 又模糊重点。本模块按工具语义保留诊断关键行、丢弃噪声,
* 全程不调 LLM(model-free),确定性可离线单测。
*
* 四类工具的保留语义(fail-soft:格式不符时退回首尾行,绝不丢全部上下文):
* - i2cdump 保留寄存器地址行(0xXX:/XX: 格式)+ 最后 dump 行;preservedAddrs 回传地址标签
* - gdb 保留 #frame 行(#0/#1… 栈帧头)
* - dmesg 保留 error/critical/warn 行(含 dmesg 级别标记 <0..4>)
* - general 截断到 maxLines(默认 200 行)
*
* 范式:纯逻辑,零依赖,零副作用,确定性可测。见架构设计文档_v3.md §6.2。
*/
// ============================================================================
// 命名常量 —— 消灭魔法串/魔法数
// ============================================================================
/** general 工具未指定 maxLines 时的默认截断行数。 */
const DEFAULT_GENERAL_MAX_LINES = 200;
/** 单条 entry 摘要截断字符数(summarizer 用,本模块引用统一来源)。 */
/** i2cdump 寄存器地址行:可选 0x 前缀 + 1~4 位十六进制 + 冒号。 */
const I2C_ADDR_LINE = /^(?:0x[0-9a-fA-F]+|[0-9a-fA-F]{1,4}):/;
/** i2cdump 地址标签提取(冒号前的部分,含 0x 前缀)。 */
const I2C_ADDR_LABEL = /^(0x[0-9a-fA-F]+|[0-9a-fA-F]{1,4}):/;
/** gdb 栈帧行:#数字 开头。 */
const GDB_FRAME_LINE = /^#\d+\b/;
/** dmesg 级别标记 <0..4>(emerg/alert/crit/err/warn)。 */
const DMESG_LEVEL = /<[0-4]>/;
/** dmesg 关键字(error/critical/warn 及常见缩写,大小写不敏感)。 */
const DMESG_KEYWORD = /error|critical|warn/i;
// ============================================================================
// 类型契约
// ============================================================================
/** 可剪枝的工具类别(每类有独立保留语义)。 */
export type PruneToolKind = "i2cdump" | "gdb" | "dmesg" | "general";
/**
* 剪枝选项。
*
* @property tool 工具类别(决定保留语义)。
* @property maxLines 仅 general 用:保留的最大行数(缺省 DEFAULT_GENERAL_MAX_LINES)。
*/
export interface PruneOptions {
readonly tool: PruneToolKind;
readonly maxLines?: number;
}
/**
* 剪枝结果。
*
* @property pruned 剪枝后的内容(保留行用 \n 连接)。
* @property dropped 被丢弃的行数(原总行数 - 保留行数)。
* @property preservedAddrs 仅 i2cdump:被保留的寄存器地址标签列表(0xXX/XX)。
*/
export interface PruneResult {
readonly pruned: string;
readonly dropped: number;
readonly preservedAddrs?: string[];
}
// ============================================================================
// 内部纯函数:行切割 + 首尾兜底
// ============================================================================
/**
* 按行切割文本,保留行序(不去空行,计数忠实于原始结构)。
*
* @param content 原始文本。
* @returns 行数组(空串 → [""];统一不返回尾随空元素除非原文本以换行结尾)。
*/
function splitLines(content: string): string[] {
if (content.length === 0) return [""];
return content.split("\n");
}
/**
* 取最后一个非空行(i2cdump 的"最后 dump 行")。
*
* @param lines 行数组。
* @returns 最后一个 trim 后非空的行;全空 → null。
*/
function lastNonEmptyLine(lines: readonly string[]): string | null {
for (let i = lines.length - 1; i >= 0; i--) {
const ln = lines[i];
if (ln && ln.trim().length > 0) return ln;
}
return null;
}
/**
* fail-soft 兜底:当按工具语义一行都没保留到时,退回首尾行,避免上下文全丢。
*
* @param lines 行数组。
* @returns 兜底保留行集合(去重后的行,保持原序)。
*/
function fallbackBookends(lines: readonly string[]): string[] {
const first = lines[0] ?? "";
const last = lastNonEmptyLine(lines);
if (first.length === 0 && last === null) return [];
if (last === null || last === first) return [first];
return [first, last];
}
/**
* 按谓词过滤行,记录被保留行下标,返回保留行 + 保留下标集合。
*
* @param lines 行数组。
* @param pred 保留谓词。
* @returns 保留行数组、保留下标 Set。
*/
function selectBy(
lines: readonly string[],
pred: (ln: string) => boolean,
): { kept: string[]; keptIdx: Set<number> } {
const kept: string[] = [];
const keptIdx = new Set<number>();
for (let i = 0; i < lines.length; i++) {
const ln = lines[i];
if (pred(ln)) {
kept.push(ln);
keptIdx.add(i);
}
}
return { kept, keptIdx };
}
// ============================================================================
// 四类工具的保留谓词
// ============================================================================
/** i2cdump 寄存器地址行谓词。 */
const isI2cAddrLine = (ln: string): boolean => I2C_ADDR_LINE.test(ln);
/** gdb 栈帧行谓词。 */
const isGdbFrameLine = (ln: string): boolean => GDB_FRAME_LINE.test(ln);
/** dmesg error/critical/warn 行谓词(级别标记或关键字)。 */
const isDmesgSevereLine = (ln: string): boolean =>
DMESG_LEVEL.test(ln) || DMESG_KEYWORD.test(ln);
/**
* 从 i2cdump 地址行提取地址标签(冒号前部分)。
*
* @param ln 地址行。
* @returns 地址标签(如 "00"/"0x10");不匹配时 null。
*/
function extractAddr(ln: string): string | null {
const m = I2C_ADDR_LABEL.exec(ln);
return m ? m[1] ?? null : null;
}
// ============================================================================
// 主入口
// ============================================================================
/**
* 按工具语义剪枝工具回包,保留诊断关键行、丢弃噪声。
*
* - i2cdump:保留寄存器地址行 + 最后 dump 行;preservedAddrs 回传地址标签;
* 一行都没匹配则退回首尾行(fail-soft,不丢全部上下文)。
* - gdb:保留 #frame 行;无帧则退回首尾行。
* - dmesg:保留 error/critical/warn 行;benign dmesg 无匹配 → pruned 为空(正确语义)。
* - general:截断到 maxLines(默认 200);超出即丢弃。
*
* 不变量:`dropped === lines.length - preservedLines`;空内容 → { pruned:"", dropped:0 }。
*
* @param content 工具原始回包文本。
* @param opts 剪枝选项(tool 必填,maxLines 仅 general 用)。
* @returns 剪枝结果。
*/
export function pruneToolResult(content: string, opts: PruneOptions): PruneResult {
if (content.length === 0) {
return { pruned: "", dropped: 0, preservedAddrs: opts.tool === "i2cdump" ? [] : undefined };
}
const lines = splitLines(content);
if (opts.tool === "general") {
const limit = opts.maxLines ?? DEFAULT_GENERAL_MAX_LINES;
const max = Math.max(0, limit);
const kept = lines.slice(0, max);
const dropped = lines.length - kept.length;
return { pruned: kept.join("\n"), dropped };
}
if (opts.tool === "i2cdump") {
const { kept, keptIdx } = selectBy(lines, isI2cAddrLine);
const addrs: string[] = [];
for (const ln of kept) {
const a = extractAddr(ln);
if (a !== null && !addrs.includes(a)) addrs.push(a);
}
// 最后 dump 行:取最后一个非空行,若未被地址谓词保留则补入(去重)。
const tail = lastNonEmptyLine(lines);
let preserved = kept;
const preservedIdx = new Set(keptIdx);
if (tail !== null) {
const tailIdx = lines.lastIndexOf(tail);
if (tailIdx >= 0 && !preservedIdx.has(tailIdx)) {
preserved = [...kept, tail];
preservedIdx.add(tailIdx);
}
}
if (preserved.length === 0) preserved = fallbackBookends(lines);
return {
pruned: preserved.join("\n"),
dropped: lines.length - preserved.length,
preservedAddrs: addrs,
};
}
if (opts.tool === "gdb") {
const { kept } = selectBy(lines, isGdbFrameLine);
const preserved = kept.length > 0 ? kept : fallbackBookends(lines);
return { pruned: preserved.join("\n"), dropped: lines.length - preserved.length };
}
// dmesg
const { kept } = selectBy(lines, isDmesgSevereLine);
// benign dmesg(无 error/warn)→ pruned 为空是正确语义,不兜底。
return { pruned: kept.join("\n"), dropped: lines.length - kept.length };
}

View File

@ -0,0 +1,284 @@
/**
* @module checkpoint-state
*
* plan/goal/todo logged state(T14)—— 闭环 checkpoint 进度的事件溯源记录器。
*
* 治嵌入式开发场景缺陷:闭环每轮(edit→compile→flash→verify→check→done)
* 的进度状态须持久化进 session 事件 log,使 session resume / fork 子任务后
* 能从 log 重建 checkpoint 状态,不丢进度、不重跑已通过步骤。
*
* 三件事(纯逻辑,append 注入,零 pi 运行时依赖,离线可单测):
* ① record —— 推进 checkpoint 状态 + 写一条 "checkpoint-change" 事件
* (data = 全量 CheckpointState 快照,含完整 history)。
* ② current —— 读当前 CheckpointState(深拷贝,防外部篡改)。
* ③ rebuild —— 从 log entries 重建状态(resume 用:取最后一条
* checkpoint-change 快照,回填内部状态)。
* fork —— 从当前状态 fork 出子记录器(子任务独立推进,共享 append sink)。
*
* 与 loop-orchestrator(src/extensions/loop-orchestrator.ts)的关系:
* loop-orchestrator 的 CheckpointMachine 是扩展层的同进程状态机单例,
* advance + serialize + restore 全在扩展内。本模块把 checkpoint 进度的
* 持久化下沉为可注入的核心层记录器——append 注入 PbaSession.append(T06),
* 事件 type="checkpoint-change" 与 PbaSessionEventMap 对齐
* (src/core/pba-session.ts:92),resume 时从 PbaSession.getEntries() 重建。
*
* 推进逻辑复用 CheckpointMachine.advance 的已证范式(src/extensions/loop-orchestrator.ts:200):
* - passed + 末步(done) → 停在 done,stepPassed=true。
* - passed + 非末步且 nextStep 在 currentStep 之后 → 前进,stepPassed 重置 false。
* - passed + 已到/已过 → 不回退(重入补跑仅记 history)。
* - failed → 停在该步(退回重试),stepPassed=false。
* 差异:timestamp 由调用方注入(确定性可测),不内部取 Date.now()。
*
* 范式:纯逻辑模块,顶层仅 import type(shared/types),无 pi 运行时依赖;
* 深冻结常量;fail-closed(非法 step 兜底;rebuild 缺 checkpoint-change 则回初始态)。
* 见架构设计文档_v3.md §5.1。
*/
import type { CheckpointState, CheckpointStep } from "../shared/types.js";
// ============================================================================
// 命名常量 —— 消灭魔法串(事件 type / 步骤序 / 初始态)
// ============================================================================
/** checkpoint 进度写入 session 的事件类型(与 PbaSessionEventMap 对齐)。 */
export const CHECKPOINT_CHANGE_TYPE = "checkpoint-change" as const;
/**
* 闭环 6 步顺序(与 loop-orchestrator STEP_ORDER 一致,深冻结)。
*
* edit → compile → flash → verify → check → done。
*/
export const STEP_ORDER: readonly CheckpointStep[] = Object.freeze([
"edit",
"compile",
"flash",
"verify",
"check",
"done",
] as const);
/** 初始 checkpoint 状态(深冻结,运行时不可变)。 */
export const INITIAL_CHECKPOINT_STATE: CheckpointState = Object.freeze({
currentStep: "edit",
stepPassed: false,
history: Object.freeze([]) as readonly { step: CheckpointStep; passed: boolean; timestamp: number }[],
} as CheckpointState);
// ============================================================================
// 类型守卫 —— rebuild 时校验 log entry data 形状
// ============================================================================
/**
* 判定一个值是否是合法的 CheckpointState(rebuild 前校验,fail-tolerant 跳过坏条)。
*
* @param value 任意值。
* @returns true=合法 CheckpointState。
*/
function isCheckpointState(value: unknown): value is CheckpointState {
if (value === null || typeof value !== "object") return false;
const s = value as Record<string, unknown>;
if (typeof s.currentStep !== "string") return false;
// 拒绝越界 currentStep:须为 STEP_ORDER 内的合法步骤串,防篡改/坏快照。
// 否则 advanceState 以 state.currentStep 算 curIdx=STEP_ORDER.indexOf(...)=-1,
// 使后续 record 的 targetIdx>-1 恒成立,可从被篡改/损坏的快照
// (currentStep='bogus' 等)向前跳过 edit→compile→flash→verify→check→done
// 的正常推进门——例如 rebuild({currentStep:'bogus'}) 后 record('check',true)
// 会把 currentStep 直接跳到 'done',再 record('done',true) 即伪造完成态。
// 坏快照在此被拒 → rebuild 回初始态(fail-closed)。
if (!STEP_ORDER.includes(s.currentStep as CheckpointStep)) return false;
if (typeof s.stepPassed !== "boolean") return false;
if (!Array.isArray(s.history)) return false;
return s.history.every(
(h) =>
h !== null &&
typeof h === "object" &&
typeof (h as Record<string, unknown>).step === "string" &&
typeof (h as Record<string, unknown>).passed === "boolean" &&
typeof (h as Record<string, unknown>).timestamp === "number",
);
}
// ============================================================================
// 内部纯函数:状态推进 + 深拷贝
// ============================================================================
/**
* 深拷贝 CheckpointState(防外部/内部引用共享)。
*
* @param s 源状态。
* @returns 独立拷贝(history 每条也浅拷贝)。
*/
function cloneState(s: CheckpointState): CheckpointState {
return {
currentStep: s.currentStep,
stepPassed: s.stepPassed,
history: Array.isArray(s.history)
? s.history.map((h) => ({ step: h.step, passed: h.passed, timestamp: h.timestamp }))
: [],
};
}
/**
* 推进 checkpoint 状态(复用 CheckpointMachine.advance 已证范式)。
*
* 语义见模块头。纯函数:修改传入的 state 对象(调用方负责传入可变拷贝)。
*
* @param state 要推进的状态(原地修改)。
* @param step 执行的步骤。
* @param passed 该步骤是否通过。
* @param timestamp 记录时刻(epoch ms)。
*/
function advanceState(
state: CheckpointState,
step: CheckpointStep,
passed: boolean,
timestamp: number,
): void {
state.history.push({ step, passed, timestamp });
const idx = STEP_ORDER.indexOf(step);
if (idx < 0) return; // 未知 step:仅记 history,不动 currentStep
const curIdx = STEP_ORDER.indexOf(state.currentStep);
if (passed) {
if (idx === STEP_ORDER.length - 1) {
// done 通过:停在 done。守卫 idx <= curIdx:终态通过只在已抵达 done 时生效,
// 禁止从早期步骤(如 edit)向前跳伪造到达终态 done 的完成表象。
// 与 failed 分支(下文 idx <= curIdx)对称——失败不向前跳伪造进度,
// 通过亦不向前跳伪造完成态。idx > curIdx 时仅记 history,不置 stepPassed=true。
if (idx <= curIdx) {
state.currentStep = step;
state.stepPassed = true;
}
} else {
const targetIdx = idx + 1;
// 只前进不回退:target 在 currentStep 之后才推进
if (targetIdx > curIdx) {
state.currentStep = STEP_ORDER[targetIdx] as CheckpointStep;
state.stepPassed = false;
}
// targetIdx <= curIdx:已到或已过,不回退(重入补跑仅记 history)
}
} else {
// 失败:退回该步重试。守卫 idx <= curIdx:失败只退回/停留,不向前跳
// (与 passed 路径的单调不变式对称——禁止经失败到达尚未抵达的步骤,
// 尤其禁止经失败伪造到达终态 done 的进度表象)。
if (idx <= curIdx) {
state.currentStep = step;
state.stepPassed = false;
}
// idx > curIdx:失败一个在 currentStep 之后的步骤,不前进(仅记 history)
}
}
// ============================================================================
// CheckpointRecorder —— 事件溯源记录器
// ============================================================================
/** append 注入函数的入参形状(与 PbaSession.append 一致)。 */
export interface CheckpointAppendEntry {
/** 事件类型(开放 string)。 */
type: string;
/** 事件载荷。 */
data: unknown;
}
/**
* 闭环 checkpoint 进度的事件溯源记录器。
*
* append 注入 PbaSession.append(或独立 sink);record 推进状态并写一条
* "checkpoint-change" 事件;current 返回深拷贝;rebuild 从 log 重建(resume);
* fork 从当前状态派生子记录器(子任务独立推进)。
*
* 纯逻辑:append 注入,无 pi 运行时依赖,离线可单测。
*/
export class CheckpointRecorder {
/** 注入的提交下沉(PbaSession.append 或测试 mock)。record 经此写出事件。 */
private readonly appendFn: (entry: CheckpointAppendEntry) => void;
/** 可变内部状态(record/rebuild 修改,current 返回拷贝)。 */
private state: CheckpointState;
/**
* @param opts.append 注入的提交下沉(PbaSession.append 或 mock)。record 唯一提交点经此写出。
*/
constructor(opts: { append: (entry: CheckpointAppendEntry) => void }) {
this.appendFn = opts.append;
this.state = cloneState(INITIAL_CHECKPOINT_STATE);
}
/**
* 推进 checkpoint 状态并写一条 "checkpoint-change" 事件进 session。
*
* 推进语义见模块头(复用 CheckpointMachine.advance 范式,timestamp 注入)。
* 写出的 data 是推进后的全量 CheckpointState 快照(含完整 history)。
*
* @param step 执行的步骤。
* @param passed 该步骤是否通过。
* @param timestamp 记录时刻(epoch ms,注入以保确定性可测)。
*/
record(step: CheckpointStep, passed: boolean, timestamp: number): void {
advanceState(this.state, step, passed, timestamp);
const snapshot = cloneState(this.state);
this.appendFn({ type: CHECKPOINT_CHANGE_TYPE, data: snapshot });
}
/**
* 读当前 checkpoint 状态(深拷贝,防外部篡改内部状态)。
*
* @returns 当前 CheckpointState 的独立拷贝。
*/
current(): CheckpointState {
return cloneState(this.state);
}
/**
* 从 log entries 重建 checkpoint 状态(resume 用)。
*
* 扫描 entries,取最后一条 type="checkpoint-change" 且 data 合法的快照,
* 回填内部状态。无 checkpoint-change 条目时回初始态(全新 session)。
*
* fail-tolerant:缺字段/乱序/坏条静默跳过,不抛异常(旧 session 不崩)。
* entries 非数组(null/undefined/number/object 等)时静默回初始态,
* 不抛 TypeError(与 fail-tolerant 姿态一致)。重建后 current() 返回重建
* 状态,record() 在重建基础上继续推进。
*
* @param entries pi session 的 entry 列表(只读,不修改)。
* @returns 重建后的 CheckpointState(独立拷贝)。
*/
rebuild(entries: ReadonlyArray<{ type: string; data: unknown }>): CheckpointState {
let rebuilt: CheckpointState | null = null;
// 非数组(null/undefined/number/object 等):静默回初始态,不抛 TypeError
if (!Array.isArray(entries)) {
this.state = cloneState(INITIAL_CHECKPOINT_STATE);
return cloneState(this.state);
}
for (const entry of entries) {
if (!entry || typeof entry.type !== "string") continue;
if (entry.type !== CHECKPOINT_CHANGE_TYPE) continue;
if (isCheckpointState(entry.data)) {
// 每条 checkpoint-change 是全量快照,取最后一条胜出
rebuilt = cloneState(entry.data);
}
}
if (rebuilt !== null) {
this.state = rebuilt;
} else {
this.state = cloneState(INITIAL_CHECKPOINT_STATE);
}
return cloneState(this.state);
}
/**
* 从当前状态 fork 出子记录器(子任务独立推进)。
*
* 子记录器共享父的 append sink(写进同一 session),但拥有父状态的独立拷贝。
* 子的 record 不影响父的 current(),反之亦然。
*
* @returns 从当前状态派生的新 CheckpointRecorder。
*/
fork(): CheckpointRecorder {
const child = new CheckpointRecorder({ append: this.appendFn });
child.state = cloneState(this.state);
return child;
}
}

View File

@ -0,0 +1,418 @@
/**
* @module context-injector
*
* 上下文注入三段(T13)—— inject / steer / followup 三段语义区分的
* runtime-context 注入器 + 快照"取代更早快照"不变量。
*
* 场景锚定:嵌入式闭环 agent 跨 turn / 跨 step 的上下文干预有三类截然不同的意图,
* pi 的 sendMessage 只给 deliverAs("steer"/"followUp"/"nextTurn") 开关,缺语义层抽象:
*
* ① inject —— 寄存器表 next-step,NO wake:把寄存器映射表 / 设备树片段 / datasheet
* 摘要登记进 runtime-context,下一 step 生效,但不主动唤醒 agent(被动补料,
* 不打断当前工具流水线)。对应 deliverAs 不触发。
* ② steer —— 换板 next-step 唤醒:切到另一块目标板(X5→S100),标记 replacesSnapshot
* 取代更早快照,下一 step 唤醒 agent 重新定向。对应 deliverAs:"steer"。
* ③ followup—— 新任务 next-turn 唤醒:用户派新任务("烧新 bootloader"),next-turn 唤醒,
* 取代更早快照。对应 deliverAs:"followUp"/"nextTurn"。
*
* "runtime-context 快照取代更早快照":每次 snapshot() 全量捕获当前 live 注入集合,
* 新快照即刻取代所有更早快照(仅最新快照为"the"runtime-context)。steer/followup
* 通过 replacesSnapshot 指向被取代的快照 id,显式声明取代关系。live 注入集合 =
* 最近一次 steer/followup(含)之后的所有 inject 累积(无 steer/followup 则全部 live),
* 体现"寄存器表累积 + 换板/新任务刷新"语义。
*
* 纯逻辑:appendEntry 下沉由构造注入(PbaSession.append 适配或测试 mock),顶层仅
* `import type`(esbuild 擦除),无 pi 运行时依赖,离线可单测。深冻结常量 + fail-closed
* (空 content / 未知 phase 抛错)。见架构设计文档_v3.md §6.3 T13。
*/
import type { PbaSessionEntry } from "../core/pba-session.js";
// ============================================================================
// 命名常量 —— 消灭魔法串(phase 合法集 / 注入事件 type / 快照 id 前缀)
// ============================================================================
/**
* 三段注入 phase 合法集合。深冻结。
*
* inject=寄存器表被动补料 / steer=换板 next-step 唤醒 / followup=新任务 next-turn 唤醒。
*/
export const INJECTION_PHASES = Object.freeze(["inject", "steer", "followup"] as const) as readonly InjectionPhase[];
/** appendEntry 下沉用的事件 type(落 PbaSession 后跨 session resume 可重放)。 */
export const CONTEXT_INJECTION_TYPE = "context-injection" as const;
/** 内部快照 id 前缀(不外泄,仅供 replacesSnapshot 引用)。 */
const SNAPSHOT_ID_PREFIX = "snap-" as const;
/**
* trim() 不剥离的 Unicode Default_Ignorable / 零宽字符集。
*
* String.prototype.trim() 只剥 Unicode White_Space 属性(含 U+FEFF BOM/ZWNBSP,
* 自 ES2019 起并入 WhiteSpace production),不剥其余 Default_Ignorable_Code_Point:
* U+200B 零宽空格 / U+200C ZWNJ / U+200D ZWJ / U+2060 WORD JOINER /
* U+2061–206F 不可见数学/格式符。这些字符视觉上不可见,纯由其组成的 content
* 等价于空串,会绕过 fail-closed 掩盖调用方 bug,故 assertContent 须先手动
* 剥除再判空(见 findings[]:trim-only 判空被 U+200B 绕过)。
*
* 注:U+FEFF 不在此列——trim() 已剥离它(见 findings[]:列入 regex 为冗余覆盖,
* 行为虽正确但属 dead-branch,故移除以保持集合语义为"trim 真正不剥的字符")。
*/
const INVISIBLE_CHARS = /[\u200B\u200C\u200D\u2060-\u206F]/g;
// ============================================================================
// 类型契约 —— 下游模块依赖这些名字,不得擅自改名
// ============================================================================
/** 注入阶段。 */
export type InjectionPhase = "inject" | "steer" | "followup";
/**
* 一条上下文注入。
*
* - phase —— inject / steer / followup 三段之一。
* - content —— 注入文本(寄存器表片段 / 换板指令 / 新任务 prompt)。
* - boardId —— steer 携带目标板 id;inject/followup 不带(undefined)。
* - nextStep —— true=下一 step 生效(inject/steer);false=不绑 step(followup)。
* - nextTurn —— true=下一 turn 唤醒(followup);false=不绑 turn(inject/steer)。
* - replacesSnapshot —— 声明取代的更早快照 id(steer/followup 取代 prior runtime-context;
* inject 不取代,undefined)。仅在 prior snapshot 存在时填充。
*/
export interface Injection {
readonly phase: InjectionPhase;
readonly content: string;
readonly boardId?: string;
readonly nextStep: boolean;
readonly nextTurn: boolean;
readonly replacesSnapshot?: string;
}
/**
* runtime-context 快照:某一时刻 live 注入集合的全量捕获。每次调用取代更早快照。
*/
export interface RuntimeSnapshot {
/** 合并后的 live 注入文本(live 注入按序 "\n\n" 拼接;空集合 → "")。 */
readonly content: string;
/** live 注入中最新 boardId(steer 的板;无 steer → undefined)。 */
readonly boardId?: string;
/** 捕获时刻(epoch ms)。 */
readonly ts: number;
}
/** appendEntry 下沉类型(与 PbaSession.append 注入的 appendEntry 同构)。 */
export type InjectionSink = (type: string, data: unknown) => void;
/** deriveActiveContext 产物:完整寄存器表 + 当前 active 注入。 */
export interface ActiveContext {
/** 全量寄存器表(所有曾注入的 Injection,按序)。 */
readonly injections: ReadonlyArray<Injection>;
/** 当前 active 注入 = live 集合最新一条(无 live 注入 → null)。 */
readonly active: Injection | null;
}
// ============================================================================
// 内部工具:深冻结 + phase 校验 + live 集合计算
// ============================================================================
/**
* 递归冻结对象/数组(原始值原样返回)。与 pba-session / sandbox-policy 范式一致:
* 运行时任何篡改抛 TypeError。
*
* @param value 任意值。
* @returns 冻结后的同一引用。
*/
function deepFreeze<T>(value: T): T {
if (value === null || typeof value !== "object") return value;
if (Array.isArray(value)) {
for (const v of value) deepFreeze(v);
} else {
for (const v of Object.values(value as Record<string, unknown>)) deepFreeze(v);
}
Object.freeze(value);
return value;
}
/**
* fail-closed phase 校验:非合法 phase 抛错。
* @param phase 待校验 phase。
*/
function assertPhase(phase: InjectionPhase): void {
if (!INJECTION_PHASES.includes(phase)) {
throw new Error(
`ContextInjector: invalid injection phase "${phase}" — must be one of ${INJECTION_PHASES.join("/")}`,
);
}
}
/**
* fail-closed content 校验:非非空字符串抛错。
*
* 嵌入式注入的 content 是寄存器表/换板指令/任务 prompt,空串无意义且掩盖调用方 bug,
* 故 fail-closed 拒绝而非静默吞。trim() 只剥 Unicode White_Space,不剥零宽
* Default_Ignorable(U+200B 零宽空格 / U+200D ZWJ 等),纯零宽字符串视觉为空却
* 绕过 trim-only 判空;故先以 INVISIBLE_CHARS 剥除零宽字符再 trim 判空。
*
* @param content 待校验内容。
*/
function assertContent(content: string): void {
// 嵌入式注入的 content 是寄存器表/换板指令/任务 prompt,空串与纯空白均无意义
// 且掩盖调用方 bug,故 fail-closed 拒绝而非静默吞。trim() 只剥 White_Space,
// 不剥零宽 Default_Ignorable(U+200B 等),须先手动剥除再判空,否则纯零宽
// 字符串视觉为空却绕过 fail-closed(见 findings[])。
if (typeof content !== "string" || content.replace(INVISIBLE_CHARS, "").trim().length === 0) {
throw new Error("ContextInjector: injection content must be a non-empty string (fail-closed)");
}
}
/**
* 计算当前 live 注入集合:最近一次 steer/followup(含)之后的所有注入按序累积;
* 无 steer/followup 则全部注入 live。体现"寄存器表累积 + 换板/新任务刷新"语义。
*
* @param injections 全量寄存器表。
* @returns live 注入子集(保持原序,原引用)。
*/
function computeLiveInjections(injections: ReadonlyArray<Injection>): Injection[] {
let pivot = -1;
for (let i = injections.length - 1; i >= 0; i--) {
const phase = injections[i]?.phase;
if (phase === "steer" || phase === "followup") {
pivot = i;
break;
}
}
return pivot === -1 ? [...injections] : injections.slice(pivot);
}
// ============================================================================
// ContextInjector —— 三段注入器 + 快照取代不变量
// ============================================================================
/**
* 上下文注入三段注入器。
*
* 纯逻辑:appendEntry 下沉由构造注入(PbaSession.append 适配或测试 mock),无 pi 运行时依赖。
* 维护 append-only 寄存器表 + append-only 快照历史;每次 snapshot() 取代更早快照。
* steer/followup 通过 replacesSnapshot 声明取代关系。live 集合由 computeLiveInjections 推导。
*/
export class ContextInjector {
/** 注入下沉(落 PbaSession 跨 session resume);无则 undefined(纯内存模式)。 */
private readonly appendEntry: InjectionSink | undefined;
/** 是否深冻结产物(默认 true,运行时不可变;测试可关)。 */
private readonly useFreeze: boolean;
/** append-only 寄存器表。 */
private readonly injections: Injection[] = [];
/** append-only 快照历史(仅最新一条为 live runtime-context)。 */
private readonly snapshots: InternalSnapshot[] = [];
/** 快照 id 自增计数(供 replacesSnapshot 引用)。 */
private snapshotSeq = 0;
/**
* @param opts.appendEntry 注入下沉(与 PbaSession 构造注入的 appendEntry 同构)。
* 每条注入经此落库;省略则纯内存(测试默认)。
* @param opts.deepFreeze 是否深冻结产物(默认 true)。
*/
constructor(opts: { appendEntry?: InjectionSink; deepFreeze?: boolean } = {}) {
this.appendEntry = opts.appendEntry;
this.useFreeze = opts.deepFreeze ?? true;
}
/**
* inject —— 寄存器表 next-step,NO wake。
*
* 把寄存器映射表 / 设备树片段 / datasheet 摘要登记进 runtime-context,下一 step 生效,
* 但不主动唤醒 agent(被动补料)。不取代更早快照(replacesSnapshot=undefined)。
*
* @param content 注入文本(非空)。
* @returns Injection{ phase:"inject", nextStep:true, nextTurn:false }。
*/
inject(content: string): Injection {
assertContent(content);
return this.register({
phase: "inject",
content,
nextStep: true,
nextTurn: false,
});
}
/**
* steer —— 换板 next-step 唤醒。
*
* 切到另一块目标板,下一 step 唤醒 agent 重新定向。标记 replacesSnapshot 取代当前
* runtime-context 快照(若已存在快照),声明换板刷新语义。
*
* @param content 换板指令文本(非空)。
* @param boardId 目标板 id(可选,省略则不绑定特定板)。
* @returns Injection{ phase:"steer", nextStep:true, nextTurn:false, boardId?, replacesSnapshot? }。
*/
steer(content: string, boardId?: string): Injection {
assertContent(content);
return this.register({
phase: "steer",
content,
boardId,
nextStep: true,
nextTurn: false,
replacesSnapshot: this.currentSnapshotId(),
});
}
/**
* followup —— 新任务 next-turn 唤醒。
*
* 用户派新任务,下一 turn 唤醒。标记 replacesSnapshot 取代当前 runtime-context 快照
* (若已存在快照),声明新任务刷新语义。不绑 step(nextStep=false)。
*
* @param content 新任务 prompt(非空)。
* @returns Injection{ phase:"followup", nextStep:false, nextTurn:true, replacesSnapshot? }。
*/
followup(content: string): Injection {
assertContent(content);
return this.register({
phase: "followup",
content,
nextStep: false,
nextTurn: true,
replacesSnapshot: this.currentSnapshotId(),
});
}
/**
* runtime-context 快照:全量捕获当前 live 注入集合,新快照即刻取代所有更早快照。
*
* - content = live 注入按序 "\n\n" 拼接(空 live → "")。
* - boardId = live 注入中最新 boardId(steer 的板;无 → undefined)。
* - ts = Date.now()。
*
* 新快照 append 进历史,成为唯一 live runtime-context(更早快照被取代)。
*
* @returns 当前 runtime-context 快照。
*/
snapshot(): RuntimeSnapshot {
const live = computeLiveInjections(this.injections);
const content = live.map((i) => i.content).join("\n\n");
let boardId: string | undefined;
for (let i = live.length - 1; i >= 0; i--) {
if (live[i]?.boardId !== undefined) {
boardId = live[i]?.boardId;
break;
}
}
this.snapshotSeq += 1;
const internal: InternalSnapshot = {
id: `${SNAPSHOT_ID_PREFIX}${this.snapshotSeq}`,
content,
boardId,
ts: Date.now(),
};
this.snapshots.push(internal);
const external: RuntimeSnapshot = {
content: internal.content,
boardId: internal.boardId,
ts: internal.ts,
};
return this.useFreeze ? (deepFreeze(external) as RuntimeSnapshot) : external;
}
/**
* 推导当前 active 上下文:全量寄存器表 + 当前 active 注入。
*
* active 注入 = live 集合最新一条(最近 steer/followup 之后累积的最新注入);
* 无 live 注入 → null。体现"最新 snapshot 取代更早"——live 集合随快照刷新而刷新,
* 更早被取代的注入不参与 active。
*
* @returns { injections: 全量表, active: live 最新一条或 null }。
*/
deriveActiveContext(): ActiveContext {
const live = computeLiveInjections(this.injections);
const active = live.length > 0 ? (live[live.length - 1] as Injection) : null;
const view: ActiveContext = {
injections: this.useFreeze ? (deepFreeze([...this.injections]) as ReadonlyArray<Injection>) : [...this.injections],
active,
};
return this.useFreeze ? (deepFreeze(view) as ActiveContext) : view;
}
/**
* 清除寄存器表。phase 给定则只清该 phase;省略则全清(含快照历史,完整重置)。
*
* @param phase 可选,仅清该 phase 的注入。
*/
clear(phase?: InjectionPhase): void {
if (phase !== undefined) {
assertPhase(phase);
for (let i = this.injections.length - 1; i >= 0; i--) {
if (this.injections[i]?.phase === phase) {
this.injections.splice(i, 1);
}
}
return;
}
this.injections.length = 0;
this.snapshots.length = 0;
this.snapshotSeq = 0;
}
// ---- 内部 ----
/**
* 统一注册:校验 phase → 冻结 Injection → 追加寄存器表 → 经 appendEntry 下沉。
* @param partial 待注册注入(缺 replacesSnapshot/boardId 由调用方按 phase 填)。
* @returns 冻结后的 Injection。
*/
private register(partial: Omit<Injection, "replacesSnapshot"> & { replacesSnapshot?: string }): Injection {
assertPhase(partial.phase);
const injection: Injection = {
phase: partial.phase,
content: partial.content,
boardId: partial.boardId,
nextStep: partial.nextStep,
nextTurn: partial.nextTurn,
replacesSnapshot: partial.replacesSnapshot,
};
const frozen = this.useFreeze ? (deepFreeze(injection) as Injection) : injection;
this.injections.push(frozen);
if (this.appendEntry) {
this.appendEntry(CONTEXT_INJECTION_TYPE, frozen);
}
return frozen;
}
/**
* 当前(最新)快照 id,供 steer/followup 填 replacesSnapshot。无快照 → undefined。
* @returns 最新快照 id 或 undefined。
*/
private currentSnapshotId(): string | undefined {
return this.snapshots.length > 0 ? (this.snapshots[this.snapshots.length - 1]?.id) : undefined;
}
}
/** 内部快照(带 id,供 replacesSnapshot 引用;id 不外泄到 RuntimeSnapshot)。 */
interface InternalSnapshot {
readonly id: string;
readonly content: string;
readonly boardId?: string;
readonly ts: number;
}
/**
* 把一条 Injection 序列化成 PbaSession appendEntry 兼容的 entry 形状(供集成层 T07/T09
* 跨 session resume 重放)。纯函数,无副作用。
*
* @param injection 注入。
* @param seq 序号(调用方自增)。
* @param ts 提交时刻(省略取 Date.now())。
* @returns PbaSessionEntry 形状 { type, data, seq, ts }。
*/
export function toSessionEntry(
injection: Injection,
seq: number,
ts: number = Date.now(),
): PbaSessionEntry {
return {
type: CONTEXT_INJECTION_TYPE,
data: injection,
seq,
ts,
};
}

393
src/core/pba-event-bus.ts Normal file
View File

@ -0,0 +1,393 @@
/**
* @module pba-event-bus
*
* 物理字节 Agent 类型化事件总线(T07)—— 薄封装 pi.events,叠加三层能力:
* ① typed event 名约定(KNOWN_EVENTS)—— 消灭魔法串,集中文档化领域事件
* ② ScopeKey 隔离 —— 路径式 scope("a.b.c")做祖先-后代关系,子 agent 事件
* 单向冒泡到父 scope(父监听收子事件),但父 emit 不下渗到子(单向冒泡)
* ③ waterfall 链委托 —— listener 收 (args, next),调 next() 委托下一个;
* 不调 next 即短路(与 tool-pipeline 的 pre/around/post 中间件范式同源)
*
* scope 语义不变式(见 tests/pba-event-bus.test.ts ⑥):
* - 无 scope(global)监听收所有事件(根节点,一切冒泡到根)
* - 注册 scope=L,emit scope=S:L 收 ⟺ L===S 或 L 是 S 的祖先(S=L+"…" 前缀)
* - global emit(scope 缺省)只达 global 监听,不下渗到任何子 scope(单向冒泡)
*
* 与 pi.events 的关系:bus 自持作用域监听注册表(Map<event, ListenerEntry[]>),
* 作用域匹配/冒泡在 bus 内完成(pi.events 的 emit 不带 scope,无法承载)。
* emit 在派发完 bus 监听后向 emitter.emit 转发(outbound 薄封装),
* 让仍用 pi.events.on 的原始监听在迁移过渡期也能收到事件。
* emitter 可注入(默认内存 emitter);inbound 桥接(pi.events.emit → bus 监听)
* 留给集成阶段,本模块只提供 bus。
*
* 纯逻辑,顶层零 pi 运行时 import(仅 import type,esbuild 擦除),
* tests 直接 import 命名导出即可离线单测,无 pi 运行时无硬件。
* 见架构设计文档_v3.md §5.2 / §7(T07)。
*/
// ============================================================================
// 类型契约
// ============================================================================
/**
* 作用域键 —— branded 语义的路径式字符串 "a.b.c"。
*
* 以 "." 分段,祖先-后代关系靠段前缀("a" 是 "a.b" 的祖先,但 "a" 不是 "ab" 的祖先,
* 因段边界对齐)。空串/undefined 归一为 global(根作用域)。
*/
export type ScopeKey = string;
/**
* 事件监听器。收 (args, next):
* - 在 emit(广播)语义下,next 是 no-op(广播不短路,全部监听独立触发)
* - 在 waterfall(链式)语义下,调 next() 委托下一个监听;不调即短路
*
* @param args 事件载荷(按引用传递,监听可读可改,waterfall 下改后下游可见)
* @param next 委托下一个监听(waterfall 语义;emit 下为 no-op)
*/
export interface PbaListener {
(args: unknown, next: () => void): void;
}
/**
* 可注入的事件传输层(pi.events 的 disposer 变体)。
*
* pi.events.on 返回 void,本接口要求 on 返回 disposer(供单测清理 / 未来 inbound 桥接)。
* 集成阶段用 adapter 包 pi.events 即可(on 返回 () => pi.events.off(...))。
* 本模块仅用 emit(outbound 转发);on 供默认内存 emitter 自洽 + 集成阶段 inbound 桥接。
*/
export interface PbaEmitter {
/**
* 注册原始监听。返回 disposer(卸载该监听)。
* @param event 事件名
* @param handler 原始监听(收 data)
* @returns 卸载函数
*/
on(event: string, handler: (data: unknown) => void): () => void;
/**
* 派发事件到该传输层注册的原始监听。
* @param event 事件名
* @param data 载荷
*/
emit(event: string, data: unknown): void;
}
/**
* PbaEventBus 构造选项。
*/
export interface PbaEventBusOptions {
/**
* 注入的事件传输层(默认内存 emitter)。
* 单测注入 spy emitter 可断言 outbound 转发;集成阶段注入 pi.events adapter。
*/
readonly emitter?: PbaEmitter;
}
// ============================================================================
// 命名常量 —— 消灭魔法串(typed event 名约定)
// ============================================================================
/**
* 领域事件名约定 —— 全 Agent 共享的 typed event 集合(深冻结,运行时不可变)。
*
* bus 不强制只能用这些事件名(开放扩展),但所有 21 域扩展约定只用 KNOWN_EVENTS
* 内的名字,避免魔法串散落各处。新增事件改这里一处。
*
* 成员(与现有扩展 pi.events.emit 调用对齐):
* - verify:passed 硬件验证通过(hardware-verify)
* - build:done 构建完成(build-tracker)
* - boardlink:connect 板链路连通(board-link)
* - glm:empty-output glm 零输出命门(glm-provider)
* - xcompile:done 交叉编译完成(cross-compile)
* - pdf-reader:page PDF 单页抽取(pdf-reader)
* - debugger:attach 调试器附着(jtag-debugger)
* - length-recovery:recovered 长度截断恢复(length-recovery)
*/
export const KNOWN_EVENTS = Object.freeze([
"verify:passed",
"build:done",
"boardlink:connect",
"glm:empty-output",
"xcompile:done",
"pdf-reader:page",
"debugger:attach",
"length-recovery:recovered",
] as const);
// ============================================================================
// 内部:作用域归一 + 冒泡判定(纯函数,确定性可测)
// ============================================================================
/**
* 归一化作用域键:按 "." 切段、滤空段、重连。
*
* - undefined / "" / " " → undefined(global)
* - "a.b.c" → "a.b.c"
* - "a..b" / "a." / ".b" → 滤空段后 "a.b" / "a" / "b"
*
* 归一保证段边界对齐,使祖先判定不靠裸前缀("a" 不会误匹配 "ab")。
*
* @param scope 原始作用域键(可 undefined)
* @returns 归一后的作用域字符串,或 undefined(global)
*/
function normalizeScope(scope: ScopeKey | undefined): string | undefined {
if (scope === undefined) return undefined;
const segs = scope.split(".").filter((s) => s.length > 0);
return segs.length === 0 ? undefined : segs.join(".");
}
/**
* 判定注册于 listenerScope 的监听是否应收到 emit 于 emitScope 的事件。
*
* 冒泡不变式(单向向上):
* - listenerScope=undefined(global)→ 恒收(根节点,一切冒泡到根)
* - emitScope=undefined(global emit)→ 非 global 监听恒不收(不下渗到子)
* - listenerScope === emitScope → 收
* - emitScope 以 listenerScope + "." 为段前缀 → 收(listenerScope 是祖先)
* - 否则 → 不收(listenerScope 是后代或旁支,事件不向下/旁冒泡)
*
* @param listenerScope 监听注册时的归一作用域(undefined=global)
* @param emitScope emit 时的归一作用域(undefined=global emit)
* @returns 是否派发
*/
function scopeReceives(
listenerScope: string | undefined,
emitScope: string | undefined,
): boolean {
if (listenerScope === undefined) return true; // global 收所有
if (emitScope === undefined) return false; // global emit 不下渗到子
if (listenerScope === emitScope) return true;
return emitScope.startsWith(listenerScope + ".");
}
/** no-op next —— emit(广播)语义下传入监听的 next,调它无副作用。 */
const NOOP_NEXT: () => void = Object.freeze(() => {}) as () => void;
// ============================================================================
// 内部:默认内存 emitter(无 pi 依赖,单测默认可用)
// ============================================================================
/**
* 默认内存 emitter —— 极简 pub/sub,on 返回 disposer,emit 快照派发(防迭代中增删)。
*
* bus 自身不在 emitter 上注册(作用域派发在 bus 内),故默认 emitter 的 handler 集常态空,
* emit 转发在此为 no-op;单测可直接在默认 emitter 上 on 来断言 outbound 转发。
*/
class InMemoryEmitter {
private readonly handlers = new Map<string, Set<(data: unknown) => void>>();
on(event: string, handler: (data: unknown) => void): () => void {
let set = this.handlers.get(event);
if (!set) {
set = new Set();
this.handlers.set(event, set);
}
set.add(handler);
return () => {
const s = this.handlers.get(event);
if (!s) return;
s.delete(handler);
if (s.size === 0) this.handlers.delete(event);
};
}
emit(event: string, data: unknown): void {
const set = this.handlers.get(event);
if (!set) return;
for (const h of [...set]) {
try {
h(data);
} catch {
// 传输层单监听失败不阻断其余(fail-soft,与 bus emit 同道)
}
}
}
}
// ============================================================================
// 监听注册表条目
// ============================================================================
/** 一条注册:监听引用 + 归一作用域。按引用比 `===`(disposer 精确卸载单条)。 */
interface ListenerEntry {
readonly listener: PbaListener;
readonly scope: string | undefined;
}
// ============================================================================
// PbaEventBus
// ============================================================================
/**
* 类型化事件总线 —— pi.events 的薄封装 + scope 隔离 + waterfall 链委托。
*
* 自持 `Map<event, ListenerEntry[]>` 注册表,作用域冒泡在 bus 内判定(pi.events 的
* emit 不带 scope,无法承载)。emit 先按 scope 冒泡派发 bus 监听,再向 emitter.emit
* 转发(outbound,过渡期原始 pi.events 监听仍可收)。waterfall 构造 next 链,不调
* next 即短路。
*
* 故障语义:
* - emit(广播):单监听抛错被隔离(fail-soft,其余监听照派发),不阻断 emitter 转发
* - waterfall(链):监听抛错向上传播(链即断,调用方显式处理),不静默吞
* - emitter 转发失败不阻断 bus(传输层故障与 bus 监听解耦)
*/
export class PbaEventBus {
private readonly registry = new Map<string, ListenerEntry[]>();
private readonly emitter: PbaEmitter;
/**
* @param opts emitter 注入(默认内存 emitter)。单测注入 spy 可断言 outbound 转发。
*/
constructor(opts?: PbaEventBusOptions) {
this.emitter = opts?.emitter ?? new InMemoryEmitter();
}
/**
* 注册监听。返回 disposer(卸载该条注册,幂等)。
*
* 同一 (event, listener) 可多次注册(不同 scope 各占一条);disposer 仅卸载自身那一条。
* 重复注册不抛(barrel 重装配 / session resume 幂等安全,与 tool-pipeline 同道)。
*
* @param event 事件名(约定用 KNOWN_EVENTS 内名字,但不强制)
* @param listener 监听器(收 args + next)
* @param scope 作用域键(缺省=global,收所有事件;路径式 "a.b.c")
* @returns 卸载函数(调一次即移除该条;再调 no-op)
*/
on(event: string, listener: PbaListener, scope?: ScopeKey): () => void {
const norm = normalizeScope(scope);
const entry: ListenerEntry = { listener, scope: norm };
let list = this.registry.get(event);
if (!list) {
list = [];
this.registry.set(event, list);
}
list.push(entry);
return () => {
const arr = this.registry.get(event);
if (!arr) return;
const idx = arr.indexOf(entry);
if (idx >= 0) arr.splice(idx, 1);
if (arr.length === 0) this.registry.delete(event);
};
}
/**
* 按 listener 引用卸载某事件的所有注册(跨所有 scope)。
*
* 不触 emitter(bus 自持注册表)。未注册/事件不存在为 no-op(不抛)。
*
* @param event 事件名
* @param listener 待卸监听引用(`===` 比对)
*/
off(event: string, listener: PbaListener): void {
const arr = this.registry.get(event);
if (!arr) return;
for (let i = arr.length - 1; i >= 0; i--) {
if (arr[i].listener === listener) arr.splice(i, 1);
}
if (arr.length === 0) this.registry.delete(event);
}
/**
* 广播派发事件:按 scope 冒泡选匹配监听,各独立触发(不短路),再向 emitter 转发。
*
* 冒泡规则(见 {@link scopeReceives}):
* - emit scope=S → global 监听 + 注册 scope 为 S 或其祖先的监听收
* - emit 无 scope → 仅 global 监听收(不下渗子 scope)
*
* fail-soft:单监听抛错被隔离(catch 后续派发照常),emitter 转发失败亦不阻断 bus。
*
* @param event 事件名
* @param args 载荷(按引用传,监听可读可改)
* @param scope emit 作用域(缺省=global emit,仅达 global 监听)
*/
emit(event: string, args: unknown, scope?: ScopeKey): void {
const norm = normalizeScope(scope);
const arr = this.registry.get(event);
if (arr) {
// 快照防迭代中增删(监听内 on/off 自身或同事件)
const snapshot = arr.slice();
for (const entry of snapshot) {
if (scopeReceives(entry.scope, norm)) {
try {
entry.listener(args, NOOP_NEXT);
} catch {
// fail-soft:单监听崩溃不阻断其余监听 + 转发
}
}
}
}
// outbound 薄封装:bus emit 同步转发到传输层,过渡期原始 pi.events 监听可收
try {
this.emitter.emit(event, args);
} catch {
// 传输层故障与 bus 监听解耦
}
}
/**
* 链式派发事件:按 scope 冒泡选匹配监听,构造 next 链顺序执行。
*
* listener 收 (args, next):调 next() 委托下一个监听;不调即短路(下游不跑)。
* 链末(无更多监听)next 为 no-op。返回穿线后的 args(监听 void,按引用可改后下游可见)。
*
* 与 emit 的区别:waterfall 是顺序链(可短路),emit 是并行广播(不可短路)。
* 故障语义不同:waterfall 监听抛错向上传播(链断,调用方显式处理);
* 不向 emitter 转发(链是请求语义,非广播,原始 pi.events 监听不应介入链中)。
*
* 同步语义:listener 必须同步调 next() 才能续链;异步调 next 链在 waterfall 返回前不完成。
*
* @param event 事件名
* @param args 载荷(按引用穿线,下游监听见上游改动)
* @param scope emit 作用域(冒泡规则同 emit)
* @returns 穿线后的 args(短路点或链末的 args)
*/
waterfall(event: string, args: unknown, scope?: ScopeKey): unknown {
const norm = normalizeScope(scope);
const arr = this.registry.get(event);
const matched: ListenerEntry[] = arr
? arr.filter((e) => scopeReceives(e.scope, norm))
: [];
let i = 0;
const next = (): void => {
if (i >= matched.length) return; // 链末
const entry = matched[i];
i++;
// 抛错向上传播(链断),不静默吞 —— 与 emit fail-soft 区别
entry.listener(args, next);
};
next();
return args;
}
/**
* 拼接父子作用域键(路径式,段边界对齐)。
*
* 归一两侧(滤空段)后按序连 "parent.child"。空侧归一为 global,故:
* - scopedScope("a", "b") → "a.b"
* - scopedScope("", "b") → "b"(父空=global)
* - scopedScope("a", "") → "a"
* - scopedScope("", "") → ""(global)
*
* @param parent 父作用域键
* @param child 子作用域键
* @returns 拼接后的作用域键
*/
scopedScope(parent: ScopeKey, child: ScopeKey): ScopeKey {
const ps = normalizeScope(parent);
const cs = normalizeScope(child);
if (ps === undefined) return cs ?? "";
if (cs === undefined) return ps;
return `${ps}.${cs}`;
}
/**
* 返回某事件注册监听总数(跨所有 scope)。
*
* @param event 事件名
* @returns 注册条数(未注册返回 0)
*/
listenerCount(event: string): number {
return this.registry.get(event)?.length ?? 0;
}
}

437
src/core/pba-session.ts Normal file
View File

@ -0,0 +1,437 @@
/**
* @module pba-session
*
* Physical Byte Agent 会话事件溯源底座(T06)—— 全量事件 log 的唯一提交点 +
* 模型历史投影 + "model-visible⟺logged" 不变量。
*
* 推广 hardware-state 的 replayFromEntries(src/extensions/hardware-state.ts:134)
* 从硬件状态子集到全量事件:turn / step / user-message / assistant-message /
* tool-call / tool-result / hw:state / flash-log / verify-record / checkpoint-change。
*
* 三件事(纯逻辑,注入 appendEntry,零 pi 运行时依赖,离线可单测):
* ① append —— 唯一提交点:lossless-JSON 快照(Date/Map/Set 折叠成 plain
* 标记对象,结构化克隆语义)+ 深冻结 + seq 单调连续 +
* 重入 guard(重入抛错,防 appendEntry 回调旁路写)。
* ② deriveMessages —— 从有序 surface(user-message / assistant-message /
* tool-call / tool-result)投影模型历史,增量缓存
* (append 后失效,第二次调用命中缓存)。
* ③ replayFromEntries —— 从 log 重建等价 PbaSession(seq 连续性校验,缺口即抛;
* 推广 hardware-state replayFromEntries 到全量事件)。
*
* "model-visible⟺logged" 不变量由 assertModelVisibleLogged 暴露:
* 声明喂模型的每个 type 必须在 log 里 append 过,否则抛错(fail-closed,
* 防止旁路喂模型未 log 的消息)。before_agent_start 钩子接线留给集成层(T07/T09)。
*
* 范式:纯逻辑模块,顶层仅 import type(shared/types),无 pi 运行时依赖;
* 深冻结常量;fail-closed(重入 / seq 缺口 / 未 log 均抛错)。
* 见架构设计文档_v3.md §5.1。
*/
import type { CheckpointState, VerifyRecord } from "../shared/types.js";
// ============================================================================
// 命名常量 —— 消灭魔法串(lossless 标记 / 模型可见类型集)
// ============================================================================
/** lossless 快照的类型标记命名空间(折叠 Date/Map/Set 成 plain 时打标签,保 round-trip 无损)。 */
const LOSSLESS_TAG = "__pbaType" as const;
/**
* 模型可见事件类型集合(deriveMessages 的投影源)。深冻结。
*
* 只有这四种 type 参与 deriveMessages 投影;turn/step/hw:state 等是非投影事件
* (持久化但不直接进模型历史)。assertModelVisibleLogged 的典型入参即此集合的子集。
*/
export const MODEL_VISIBLE_TYPES = Object.freeze([
"user-message",
"assistant-message",
"tool-call",
"tool-result",
] as const) as readonly string[];
// ============================================================================
// 事件 Map —— 类型契约(merge-extensible:append 接受任意 string type,此 Map 供类型化调用方)
// ============================================================================
/** hw:state 事件 data 形状(与 hardware-state 扩展的 HwStateData 结构兼容)。 */
export interface PbaHwStateData {
/** 状态/事件类别。 */
type: string;
/** 任意状态载荷。 */
data: Record<string, unknown>;
/** 捕获时刻(epoch ms)。 */
ts: number;
}
/** flash-log 事件 data 形状(与 hardware-state 扩展的 FlashLogEntry 结构兼容)。 */
export interface PbaFlashLogData {
method: string;
target: string;
image: string;
sha256?: string;
result: "ok" | "fail";
ts: number;
}
/**
* PbaSession 全量事件 Map —— 每个 key 映射到该事件的 data 形状。
*
* merge-extensible:append 的入参 type 是开放 string(不强制在此枚举内),
* 故新事件类型无需改本 Map 即可 append;此 Map 仅供类型化调用方与文档化不变量。
*/
export interface PbaSessionEventMap {
"turn": { turn: number; phase: "start" | "end"; reason?: string };
"step": { turn: number; step: number; phase: "start" | "end" };
"user-message": { role: "user"; content: string };
"assistant-message": { role: "assistant"; content: string };
"tool-call": { name: string; args: unknown; turn?: number; step?: number };
"tool-result": { name: string; result: unknown; turn?: number; step?: number };
"hw:state": PbaHwStateData;
"flash-log": PbaFlashLogData;
"verify-record": VerifyRecord;
"checkpoint-change": CheckpointState;
}
/** 内部持久化的一条会话事件(append / replay 共用)。 */
export interface PbaSessionEntry {
/** 事件类型(开放 string)。 */
readonly type: string;
/** lossless-JSON 快照后的 data(plain,可深冻结)。 */
readonly data: unknown;
/** 单调连续序号(从 1 起,append 自增 / replay 校验)。 */
readonly seq: number;
/** 提交时刻(epoch ms)。 */
readonly ts: number;
}
// ============================================================================
// deriveMessages 投影产物
// ============================================================================
/**
* deriveMessages 投影出的单条模型消息。
*
* - user-message → { role:"user", content }
* - assistant-message → { role:"assistant", content }
* - tool-call → { role:"assistant", toolCalls:[{name,args}] }
* - tool-result → { role:"tool", name, content: result }
*/
export interface DerivedMessage {
readonly role: "user" | "assistant" | "tool";
readonly content: unknown;
/** tool-result 的工具名(role:"tool" 时)。 */
readonly name?: string;
/** tool-call 的调用列表(role:"assistant" 且为工具调用时)。 */
readonly toolCalls?: ReadonlyArray<{ name: string; args: unknown }>;
}
// ============================================================================
// 内部纯函数:lossless-JSON 快照 + 深冻结
// ============================================================================
/**
* 把任意值折叠成 lossless-JSON plain 快照(结构化克隆语义)。
*
* - Date → { __pbaType:"Date", value: iso }(保 round-trip 无损)
* - Map → { __pbaType:"Map", value: [[k,v],...] }(键值递归快照)
* - Set → { __pbaType:"Set", value: [...] }(元素递归快照)
* - Array/Object → 递归每个元素/值
* - 原始值 → 原样
* - 循环引用 → 抛错(fail-closed:循环结构不可 JSON 序列化,拒绝快照)
*
* 产物是纯 plain 对象/数组/原始值,JSON.stringify 安全 + 可深冻结。
*
* @param value 任意值。
* @returns plain JSON-safe 快照。
*/
function toLosslessSnapshot(value: unknown): unknown {
return snapshotValue(value, new WeakSet<object>());
}
function snapshotValue(value: unknown, seen: WeakSet<object>): unknown {
if (value === null || typeof value !== "object") return value;
const ref = value as object;
if (seen.has(ref)) {
throw new Error("PbaSession: cannot snapshot cyclic object (lossless-JSON invariant)");
}
seen.add(ref);
if (value instanceof Date) {
return { [LOSSLESS_TAG]: "Date", value: value.toISOString() };
}
if (value instanceof Map) {
const entries = [...value.entries()].map(([k, v]) => [
snapshotValue(k, seen),
snapshotValue(v, seen),
]);
return { [LOSSLESS_TAG]: "Map", value: entries };
}
if (value instanceof Set) {
return { [LOSSLESS_TAG]: "Set", value: [...value].map((v) => snapshotValue(v, seen)) };
}
if (Array.isArray(value)) {
return value.map((v) => snapshotValue(v, seen));
}
const out: Record<string, unknown> = {};
for (const [k, v] of Object.entries(value)) {
out[k] = snapshotValue(v, seen);
}
return out;
}
/**
* 递归冻结对象/数组(原始值原样返回)。
*
* 与 sandbox-policy / tool-pipeline 的深冻结范式一致:运行时任何篡改抛 TypeError。
*
* @param value 任意值。
* @returns 冻结后的同一引用。
*/
function deepFreeze<T>(value: T): T {
if (value === null || typeof value !== "object") return value;
if (Array.isArray(value)) {
for (const v of value) deepFreeze(v);
} else {
for (const v of Object.values(value as Record<string, unknown>)) deepFreeze(v);
}
Object.freeze(value);
return value;
}
// ============================================================================
// deriveMessages 投影:单条事件 → 模型消息(非投影类型返回 null)
// ============================================================================
/**
* 把一条会话事件投影成模型消息。非 MODEL_VISIBLE 类型返回 null(跳过)。
*
* @param entry 会话事件。
* @returns 投影消息或 null。
*/
function projectMessage(entry: PbaSessionEntry): DerivedMessage | null {
const data = (entry.data ?? null) as Record<string, unknown> | null;
switch (entry.type) {
case "user-message":
return { role: "user", content: data?.content ?? "" };
case "assistant-message":
return { role: "assistant", content: data?.content ?? "" };
case "tool-call":
return {
role: "assistant",
content: null,
toolCalls: [{ name: String(data?.name ?? ""), args: data?.args ?? null }],
};
case "tool-result":
return {
role: "tool",
name: String(data?.name ?? ""),
content: data?.result ?? null,
};
default:
return null;
}
}
// ============================================================================
// PbaSession —— 事件溯源底座
// ============================================================================
/**
* 会话事件溯源底座。append 是唯一提交点(防旁路写);deriveMessages 从有序 surface
* 投影模型历史并增量缓存;replayFromEntries 从 log 重建等价会话。
*
* 纯逻辑:appendEntry 由构造注入(pi 的 appendEntry 或测试 mock),无 pi 运行时依赖。
*/
export class PbaSession {
private readonly appendEntry: (type: string, data: unknown) => void;
private readonly useFreeze: boolean;
private seq = 0;
private readonly log: PbaSessionEntry[] = [];
private readonly loggedTypes = new Set<string>();
private messagesCache: ReadonlyArray<unknown> | null = null;
/** getEntries 的冻结快照缓存(append/loadEntries 后失效,二次调用命中同引用)。 */
private entriesView: readonly PbaSessionEntry[] | null = null;
private appending = false;
/**
* @param opts.appendEntry 注入的提交下沉(pi appendEntry 或 mock)。append 唯一提交点经此写出。
* @param opts.deepFreeze 是否深冻结快照(默认 true,运行时不可变;测试可关)。
*/
constructor(opts: { appendEntry: (type: string, data: unknown) => void; deepFreeze?: boolean }) {
this.appendEntry = opts.appendEntry;
this.useFreeze = opts.deepFreeze ?? true;
}
/**
* 唯一提交点:lossless-JSON 快照 + 深冻结 + seq 自增 + 调 appendEntry 下沉 +
* 本地 log 追加 + 缓存失效。
*
* 重入 guard:若 appendEntry 回调再次进入 append(旁路写),立即抛错(fail-closed,
* 防 seq 乱序 / 双写)。下沉抛错时回滚 seq,保持状态一致。
*
* @param event { type, data } —— type 开放 string;data 任意(Date/Map/Set 折叠成 plain)。
*/
append(event: { type: string; data: unknown }): void {
if (this.appending) {
throw new Error(
"PbaSession: reentrant append detected — appendEntry must not re-enter append (唯一提交点 guard)",
);
}
this.appending = true;
try {
const snap = toLosslessSnapshot(event.data);
const stored = this.useFreeze ? deepFreeze(snap) : snap;
this.seq += 1;
const entry: PbaSessionEntry = {
type: event.type,
data: stored,
seq: this.seq,
ts: Date.now(),
};
if (this.useFreeze) Object.freeze(entry);
try {
this.appendEntry(event.type, stored);
} catch (err) {
// 下沉失败:回滚 seq,保持单调连续不变量(此条未真正提交)。
this.seq -= 1;
throw err;
}
this.log.push(entry);
this.loggedTypes.add(event.type);
this.messagesCache = null; // 失效增量缓存
this.entriesView = null; // 失效 getEntries 冻结快照缓存
} finally {
this.appending = false;
}
}
/**
* 从有序 surface(user-message / assistant-message / tool-call / tool-result)
* 投影模型历史。增量缓存:append 后失效,第二次调用命中缓存(同引用)。
*
* @returns 投影消息数组(深冻结若 useFreeze;缓存命中时返回同一引用)。
*/
deriveMessages(): unknown[] {
if (this.messagesCache !== null) return this.messagesCache as unknown[];
const messages: DerivedMessage[] = [];
for (const entry of this.log) {
const m = projectMessage(entry);
if (m) messages.push(m);
}
const out = this.useFreeze ? (deepFreeze(messages) as unknown[]) : (messages as unknown[]);
this.messagesCache = out;
return out;
}
/**
* 只读访问内部 log 的冻结快照(entry 与数组容器均冻结)。供 compaction(T09)等下游读取。
*
* 返回数组容器的 Object.freeze 视图(与 stored data 的深冻结防线对称):下游 push/splice
* 等结构性篡改会抛 TypeError,无法旁路 append 唯一提交点 guard。增量缓存:append/loadEntries
* 后失效,第二次调用命中同引用。entry 本身已在 append 时深冻结。
*
* @returns 内部 log 的冻结只读快照(数组容器冻结;entry 已冻结;append 后返回新引用)。
*/
getEntries(): readonly PbaSessionEntry[] {
if (this.entriesView !== null) return this.entriesView;
this.entriesView = Object.freeze([...this.log]);
return this.entriesView;
}
/**
* 从 log entries 重建一个等价 PbaSession(推广 hardware-state replayFromEntries 到全量事件)。
*
* seq 连续性校验(fail-closed,缺口即抛):
* - entries 带 seq 时,必须严格 +1 递增(首条为基线,非 1 起亦可,支持 compaction 续写);
* - entries 不带 seq 时,按序赋 1..n;
* - 混合时:带 seq 的校验连续,不带 seq 的按 lastSeq+1 填充。
* 重建后新会话沿用本会话的 appendEntry / useFreeze,seq 续 lastSeq,可继续 append。
*
* @param entries log entry 列表(只读,不修改)。
* @returns 等价的新 PbaSession。
*/
replayFromEntries(
entries: ReadonlyArray<{ type: string; data: unknown; seq?: number }>,
): PbaSession {
const next = new PbaSession({ appendEntry: this.appendEntry, deepFreeze: this.useFreeze });
next.loadEntries(entries);
return next;
}
/**
* "model-visible⟺logged" 不变量校验:声明喂模型的每个 type 必须在 log 里 append 过。
*
* fail-closed:若 visibleTypes 中某 type 从未 append 过(loggedTypes 无此 type)→ 抛错
* (防止旁路喂模型未 log 的消息——唯一提交点被绕过)。
*
* 反向(logged 但未声明 visible)不在本方法职责内,由集成层保证声明完整。
*
* @param visibleTypes 声明为模型可见的 type 列表(典型为 MODEL_VISIBLE_TYPES 子集)。
*/
assertModelVisibleLogged(visibleTypes: readonly string[]): void {
for (const t of visibleTypes) {
if (!this.loggedTypes.has(t)) {
throw new Error(
`PbaSession: type "${t}" declared model-visible but never logged (model-visible⟺logged invariant violated)`,
);
}
}
}
/**
* 内部:从 entries 校验 seq 连续性并装载进本会话(replayFromEntries 用)。
*
* seq 校验(fail-closed,违例即抛):
* - 下界:带 seq 的 entry 必须 seq >= 1(0/负数/NaN 不可作为 compaction 基线;
* PbaSessionEntry.seq 文档化“从 1 起”不变量;NaN 因 typeof===\"number\" 通过类型门,
* 故用 !(seq>=1) 一并拒绝)。
* - 连续性:带 seq 的 entry 必须严格 +1 递增(首条为基线,非 1 起亦可,支持 compaction 续写);
* 不带 seq 的按序赋 1..n;混合时带 seq 的校验连续,不带 seq 的按 lastSeq+1 填充。
*
* 私有:仅供同类实例跨实例调用(TS private 跨实例可访问)。
*/
private loadEntries(entries: ReadonlyArray<{ type: string; data: unknown; seq?: number }>): void {
let lastSeq: number | null = null;
const loaded: PbaSessionEntry[] = [];
for (let i = 0; i < entries.length; i++) {
const e = entries[i];
if (!e || typeof e.type !== "string") {
throw new Error(`PbaSession: replay entry[${i}] missing string type`);
}
let seq: number;
if (typeof e.seq === "number") {
seq = e.seq;
// 下界校验:seq >= 1(NaN/0/负数拒绝;compaction 续写可非 1 起,但不可低于 1)
if (!(seq >= 1)) {
throw new Error(
`PbaSession: replay entry[${i}] seq ${seq} violates lower bound — must be >= 1 (PbaSessionEntry.seq 从 1 起不变量)`,
);
}
if (lastSeq !== null && seq !== lastSeq + 1) {
throw new Error(
`PbaSession: seq discontinuity at entry[${i}] — expected ${lastSeq + 1}, got ${seq}`,
);
}
} else {
seq = lastSeq === null ? 1 : lastSeq + 1;
}
lastSeq = seq;
const snap = toLosslessSnapshot(e.data);
const stored = this.useFreeze ? deepFreeze(snap) : snap;
const entry: PbaSessionEntry = {
type: e.type,
data: stored,
seq,
ts: Date.now(),
};
if (this.useFreeze) Object.freeze(entry);
loaded.push(entry);
}
for (const e of loaded) {
this.log.push(e);
this.loggedTypes.add(e.type);
}
this.seq = lastSeq ?? 0;
this.messagesCache = null;
this.entriesView = null;
}
}

View File

@ -0,0 +1,474 @@
/**
* @module provider-registry
*
* 多 LLM provider 适配核心库(T16)—— 换模型改配置行不改扩展。
*
* glm-provider 扩展当前硬编码 glm-5.2 单 provider。本模块把"描述一个 provider"
* 抽象成 {@link ProviderDescriptor},泛化 glm-provider 的 buildGlmModelConfig +
* toProviderConfig 两函数为单一 {@link buildProviderConfig},并维护一个可注册/解析
* 的 provider 表({@link ProviderRegistry})。glm-provider 扩展可后续改为先查
* registry 再 registerProvider,从而支持 DeepSeek 原生及其他 provider。
*
* 复用 dsh THINKING_FORMAT_GATE 思路:thinkingFormat:"qwen" 触发 pi
* openai-completions 的 enable_thinking:false 兼容分支(治命门一"thinking 吃光
* max_tokens 零输出");thinkingFormat:"none" 或缺省则不注入 qwen compat,留给
* provider 原生 reasoning 语义。
*
* 纯逻辑:顶层仅 `import type`(esbuild 擦除),ProviderConfig/ProviderModelConfig
* 仅作类型,运行时不解析 pi。tests 直接 import 命名导出即可离线单测,无 pi 运行时
* 依赖、无硬件。
*
* 密钥铁律:gateway key 一律用 `${DROBOTICS_LLM_KEY}` 形式占位(env 变量名来自
* desc.apiKeyEnv),绝不出现 sk- 开头明文,绝不写进 git-tracked 文件。
*/
import type { ProviderConfig, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
// ============================================================================
// 命名常量 —— 消灭魔法串(网关 / provider 名 / 思考格式 / 默认窗口)
// ============================================================================
/** d-robotics 内部 LLM 网关 base url(glm-5.2 默认走此网关,实测见缺陷分析 §3 #7)。 */
const DROBOTICS_GATEWAY_URL = "https://ai-api.d-robotics.cc/v1";
/** glm-5.2 经网关的 provider 名(pi.registerProvider 第一参数)。 */
const GLM_PROVIDER_NAME = "drobotics-glm";
/** glm-5.2 真实模型 id(带中划线,实测见缺陷分析 §3 #7)。 */
const GLM_MODEL_ID = "glm-5.2";
/** DeepSeek 原生 provider 名(stub,后续接线真实网关)。 */
const DEEPSEEK_PROVIDER_NAME = "deepseek-native";
/** DeepSeek 原生模型 id(官方 chat 模型)。 */
const DEEPSEEK_MODEL_ID = "deepseek-chat";
/** DeepSeek 原生官方网关 base url(stub,可被私有网关覆盖)。 */
const DEEPSEEK_GATEWAY_URL = "https://api.deepseek.com/v1";
/** DeepSeek 原生官方 key 的环境变量名(占位,值走 env)。 */
const DEEPSEEK_API_KEY_ENV = "DEEPSEEK_API_KEY";
/** glm-5.2 默认 key 的环境变量名(占位,值走 env)。 */
const GLM_API_KEY_ENV = "DROBOTICS_LLM_KEY";
/** glm-5.2 默认 max_tokens(治命门一:从缺陷默认 2048 提到 8192,防 thinking 吃光)。 */
const GLM_MAX_TOKENS = 8192;
/** glm-5.2 上下文窗口(1M token)。 */
const GLM_CONTEXT_WINDOW = 1_000_000;
/** DeepSeek 上下文窗口(128K token,官方文档)。 */
const DEEPSEEK_CONTEXT_WINDOW = 128_000;
/** DeepSeek 默认 max_tokens。 */
const DEEPSEEK_MAX_TOKENS = 8192;
// ============================================================================
// 类型契约
// ============================================================================
/**
* 思考格式门 —— 复用 dsh THINKING_FORMAT_GATE 思路。
*
* - "qwen" —— 注入 compat.thinkingFormat:"qwen" + thinkingLevelMap 全 null +
* supportsReasoningEffort:false,触发 pi openai-completions 的 enable_thinking:false
* 分支(治命门一:glm-5.2 默认开 thinking 吃光 max_tokens 致零输出)。
* - "none" —— 不注入 qwen compat,留给 provider 原生 reasoning 语义。
*/
export type ThinkingFormat = "qwen" | "none";
/**
* provider 描述符 —— 声明式描述一个 LLM provider 的全部接线信息。
*
* 设计为纯数据(可深冻结、可序列化、可 diff)。key 不入库:只记环境变量名
* (apiKeyEnv),运行时由 {@link buildProviderConfig} 展开成 `${VAR}` 占位交 pi。
*
* 下游模块(glm-provider 扩展、配置加载器)依赖这些字段名,不得擅自改名。
*/
export interface ProviderDescriptor {
/** 模型 id(带中划线如 "glm-5.2",pi 模型匹配键)。 */
readonly id: string;
/** pi provider 名(pi.registerProvider 第一参数)。 */
readonly provider: string;
/** 网关 base url(含 /v1 后缀)。 */
readonly baseUrl: string;
/** key 占位变量名,值走 env,绝不入库(展开为 `${VAR}`)。 */
readonly apiKeyEnv: string;
/** 思考格式门;缺省视为 "none"。 */
readonly thinkingFormat?: ThinkingFormat;
/** 最大输出 token 数。 */
readonly maxTokens: number;
/** 上下文窗口(token 数)。 */
readonly contextWindow: number;
/** 是否支持 reasoning(thinking)输出。 */
readonly reasoning: boolean;
/** 支持的输入模态;缺省 ["text"]。 */
readonly input?: readonly ("text" | "image")[];
/** 计费(每百万 token,美元);缺省全 0(内部网关不计费)。 */
readonly cost?: {
readonly input: number;
readonly output: number;
readonly cacheRead: number;
readonly cacheWrite: number;
};
}
// ============================================================================
// 内部:思考格式门 —— 把 thinkingFormat 展开成 pi compat/thinkingLevelMap
// ============================================================================
/** thinkingLevelMap 全 null 形态(关掉 reasoning effort 映射,配合 qwen compat)。 */
const NULL_THINKING_LEVEL_MAP = Object.freeze({
off: null,
low: null,
medium: null,
high: null,
});
/** thinkingLevelMap 默认直通形态(effort 名原样透传给 provider 原生 reasoning)。 */
const PASSTHROUGH_THINKING_LEVEL_MAP = Object.freeze({
off: null,
low: "low",
medium: "medium",
high: "high",
});
/**
* 把 thinkingFormat 展开成 pi 的 compat + thinkingLevelMap + supportsReasoningEffort。
*
* THINKING_FORMAT_GATE:thinkingFormat:"qwen" 注入 compat.thinkingFormat:"qwen"
* 触发 pi enable_thinking:false 分支;"none"/缺省则用直通 map,留原生语义。
*
* none 分支 quirk(文档化,见 {@link buildProviderConfig} JSDoc):返回 compat=undefined,
* 故返回的 supportsReasoningEffort(= desc.reasoning)在 buildProviderConfig 中因 compat
* 不存在而被丢弃——pi 仅从 compat.supportsReasoningEffort 读此字段。当前无 none+
* reasoning:true 的已知 provider,故无实际影响;未来若需为这类 provider 暴露
* reasoning-effort 控制,应在此分支产出携带 supportsReasoningEffort 的 compat 对象。
*
* @param desc provider 描述符。
* @returns { thinkingLevelMap, compat, supportsReasoningEffort } 三元组。
*/
function applyThinkingFormatGate(desc: ProviderDescriptor): {
thinkingLevelMap: Record<string, unknown>;
compat: Record<string, unknown> | undefined;
supportsReasoningEffort: boolean;
} {
if (desc.thinkingFormat === "qwen") {
return {
thinkingLevelMap: NULL_THINKING_LEVEL_MAP,
compat: { thinkingFormat: "qwen", supportsReasoningEffort: false },
supportsReasoningEffort: false,
};
}
return {
thinkingLevelMap: PASSTHROUGH_THINKING_LEVEL_MAP,
compat: undefined,
supportsReasoningEffort: desc.reasoning,
};
}
// ============================================================================
// buildProviderConfig —— 泛化 glm-provider buildGlmModelConfig + toProviderConfig
// ============================================================================
/**
* 把 {@link ProviderDescriptor} 转成 pi.registerProvider(name, config) 的入参。
*
* 泛化 glm-provider 的 buildGlmModelConfig + toProviderConfig 两函数:descriptor 是
* 纯数据,本函数把它展开成 pi 能消费的 { name, config }。thinkingFormat:"qwen"
* 触发 enable_thinking:false 兼容(THINKING_FORMAT_GATE 思路,治命门一)。
*
* 密钥铁律:apiKey 展开为 `${desc.apiKeyEnv}` 占位,绝不出现 sk- 明文。
*
* 低层信任契约(finding 2 文档化硬约束):本函数信任入参、**不**调用
* {@link assertDescriptorValid},留给上层决定校验时机——glm-provider 扩展传入已知良好的
* 冻结常量(KNOWN_PROVIDERS),无需再校验。但这是一条 fail-open 路径:畸形 descriptor
* (如 `{}`)**不被拒绝**,而会产出 `apiKey="${undefined}"`、`name=undefined` 的半成品 config
* (pi.registerProvider 会接受,但运行时报晦涩的 auth 错而非注册期 fail-closed 清晰错)。
* 不能在此加校验——若干对抗/变异测试(buildProviderConfig({}) 不抛而产 ${undefined}、
* M5 mutant)显式 pin 此 fail-open 行为作为低层信任 quirk。故任何传入外部/用户构造的
* descriptor 的 caller(配置加载器、用户配置路径)**必须**走 fail-closed 入口
* {@link buildProviderConfigValidated}(先校验再构建),绝不可直接调本函数。
*
* cost 防篡改硬化(治 finding 1):`cost: desc.cost ? Object.freeze(desc.cost)
* : Object.freeze({...})`。原实现直接别名 `desc.cost` 进 model(与 `input` 的
* spread-copy 不一致),caller 在 build 后改写 `desc.cost.input` 会**静默**腐蚀已构建
* config 的 cost(input 因已拷贝无此害)。本函数不能改成 spread-copy——等价类/对抗
* 测试(model.cost === desc.cost 同引用 quirk、循环引用 cost 不爆栈)显式 pin 此同引用
* 契约。改用 Object.freeze 原地冻结 desc.cost:保留同引用(toBe 不破),同时 caller 再
* 改写 `desc.cost.input` 会**loudly** 抛 TypeError 而非静默腐蚀——把静默 bug 变成显式崩溃。
* 冻结对已知良好入参(KNOWN_PROVIDERS 已 deepFreeze)是 no-op;仅对 mutable descriptor
* caller 生效,而 mutable descriptor 本就违反"纯数据/可深冻结"设计不变式(见
* {@link ProviderDescriptor} JSDoc),故此冻结是硬化而非副作用污染。
*
* none 分支思考格式门 quirk(文档化):thinkingFormat:"none"/缺省时,
* {@link applyThinkingFormatGate} 返回 compat=undefined(不注入 qwen shim,留给 provider
* 原生 reasoning 语义),故 supportsReasoningEffort(= desc.reasoning)计算后被丢弃——
* pi 只从 compat.supportsReasoningEffort 读此字段,compat 缺省即不暴露 reasoning-effort
* 控制。当前 DeepSeek stub(reasoning:false)不受影响(丢弃的值本就是 false);仅当未来
* 出现 none+reasoning:true 的 provider 且需要 reasoning-effort 控制时,需扩展 gate 在 none
* 分支产出携带 supportsReasoningEffort 的 compat 对象(会改变 compat=undefined 契约,
* 须同步更新测试)。
*
* @param desc provider 描述符(低层信任,不校验)。
* @returns { name, config } 供 pi.registerProvider 使用。
*/
export function buildProviderConfig(desc: ProviderDescriptor): {
name: string;
config: ProviderConfig;
} {
const apiKey = `\${${desc.apiKeyEnv}}`;
const { thinkingLevelMap, compat, supportsReasoningEffort } = applyThinkingFormatGate(desc);
const model: ProviderModelConfig = {
id: desc.id,
name: desc.id,
reasoning: desc.reasoning,
thinkingLevelMap,
input: [...(desc.input ?? ["text"])] as ("text" | "image")[],
// 治 finding 1:原别名 `desc.cost` 与 input 的 spread-copy 不一致,build 后改写
// desc.cost.input 会静默腐蚀此 model.cost。Object.freeze 原地冻结保留同引用
// (model.cost === desc.cost 契约不破),改写改抛 TypeError(静默→显式)。
// 不用 spread-copy:会破坏同引用 quirk 测试;冻结对已冻结的 KNOWN_PROVIDERS 是 no-op。
cost: desc.cost ? Object.freeze(desc.cost) : Object.freeze({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }),
contextWindow: desc.contextWindow,
maxTokens: desc.maxTokens,
compat,
};
// supportsReasoningEffort 是 pi ProviderModelConfig.compat 的可选子字段(镜像 glm-provider),
// 透传进 compat 以兼容 pi 当前 schema(compat 为 Record<string,unknown>)。
// 注意:none 分支 compat=undefined 时此处跳过——见上 JSDoc 的 quirk 文档化。
if (compat) {
compat.supportsReasoningEffort = supportsReasoningEffort;
}
return {
name: desc.provider,
config: {
name: desc.id,
baseUrl: desc.baseUrl,
apiKey,
api: "openai",
authHeader: true,
models: [model],
},
};
}
/**
* fail-closed 入口:先 {@link assertDescriptorValid} 校验,再 {@link buildProviderConfig} 构建。
*
* 治 finding:buildProviderConfig 低层信任不校验,配置加载器等外部 caller 直接传畸形
* descriptor 会产出半成品 config(apiKey="${undefined}"、name=undefined),违反密钥铁律/
* fail-closed 契约。本函数给外部 caller 一个一步到位的 fail-closed 路径——缺字段直接抛错,
* 绝不产出半成品 provider config 交 pi.registerProvider。
*
* glm-provider 扩展传已知良好常量时可直接用 {@link buildProviderConfig}(免重复校验);
* 配置加载器/用户配置路径务必用本函数。
*
* @param desc 待校验+构建的 provider 描述符。
* @returns { name, config } 供 pi.registerProvider 使用。
* @throws {Error} id/provider/baseUrl/apiKeyEnv 为空串或 maxTokens/contextWindow 非有限正。
*/
export function buildProviderConfigValidated(desc: ProviderDescriptor): {
name: string;
config: ProviderConfig;
} {
assertDescriptorValid(desc);
return buildProviderConfig(desc);
}
// ============================================================================
// 描述符校验 —— fail-closed(缺字段拒绝注册,不静默吞错)
// ============================================================================
/**
* 校验描述符必填字段。fail-closed:缺字段抛错,绝不注册半成品 provider。
*
* 导出供外部 caller(配置加载器、{@link buildProviderConfigValidated})复用同一套校验
* 契约——buildProviderConfig 低层信任不校验(见其 JSDoc),外部 descriptor 入站时务必
* 先过本函数或直接走 {@link buildProviderConfigValidated}。
*
* @param desc 待校验描述符。
* @throws {Error} id/provider/baseUrl/apiKeyEnv 为空串或 maxTokens<=0。
*/
export function assertDescriptorValid(desc: ProviderDescriptor): void {
const required: ReadonlyArray<readonly [unknown, string]> = [
[desc.id, "id"],
[desc.provider, "provider"],
[desc.baseUrl, "baseUrl"],
[desc.apiKeyEnv, "apiKeyEnv"],
];
for (const [value, label] of required) {
if (typeof value !== "string" || value.trim() === "") {
throw new Error(`[provider-registry] invalid descriptor: ${label} must be non-empty string`);
}
}
if (!Number.isFinite(desc.maxTokens) || desc.maxTokens <= 0) {
throw new Error(`[provider-registry] invalid descriptor: maxTokens must be finite positive (got ${desc.maxTokens})`);
}
if (!Number.isFinite(desc.contextWindow) || desc.contextWindow <= 0) {
throw new Error(`[provider-registry] invalid descriptor: contextWindow must be finite positive (got ${desc.contextWindow})`);
}
}
// ============================================================================
// ProviderRegistry —— 可注册/解析的 provider 表
// ============================================================================
/**
* provider 注册表 —— 维护 id → descriptor 映射,支持 register/resolve/list。
*
* 设计为模块内可实例化的纯逻辑类(非单例,便于测试与多配置隔离)。register 返回
* disposer(与 tool-pipeline/sandbox-policy 的注册器范式一致),重复 id 视为更新
* (替换 descriptor,旧 disposer 失效),保证 barrel 重装配幂等。
*
* fail-closed:resolve 未知 id 抛错(无 descriptor = 无 provider = 拒绝使用,
* 不静默回退到默认,避免误用未配置模型)。
*
* 代际计数器单调不重置(治 finding):disposer 仅移除 descriptor,不删 generations[id],
* 计数器单调递增永不回退,确保 dispose→re-register 同 id 周期后旧 disposer 永久 no-op
* (见 {@link ProviderRegistry.register} disposer 注释)。
*/
export class ProviderRegistry {
private readonly descriptors = new Map<string, ProviderDescriptor>();
/** id → 单调递增的代际号(永不重置/删除,旧 disposer 的代际号过期则 no-op)。 */
private readonly generations = new Map<string, number>();
/**
* 注册一个 provider 描述符。重复 id 视为更新(替换),旧 disposer 失效。
*
* 不可变存储(治 finding):先校验,再 {@link cloneDescriptor} 拷贝 + {@link deepFreezeDescriptor}
* 深冻结后存入表。调用方原对象不被冻结/不持同引用——resolve 返回的是 registry 自己的
* 深冻结副本,调用方无法通过 resolved 对象篡改内部状态,注册后改写原对象也不会让 Map
* key 与存储条目状态分裂,守住"纯数据/可深冻结"不变式。
*
* @param desc provider 描述符(先校验,fail-closed;存储深冻结副本)。
* @returns disposer:调用即移除本次注册(若已被同 id 后续注册覆盖则 no-op)。
*/
register(desc: ProviderDescriptor): () => void {
assertDescriptorValid(desc);
const id = desc.id;
const stored = deepFreezeDescriptor(cloneDescriptor(desc));
const generation = (this.generations.get(id) ?? 0) + 1;
this.generations.set(id, generation);
this.descriptors.set(id, stored);
return () => {
// 只有当前代际的 disposer 才真移除 descriptor;被覆盖后的旧 disposer no-op。
// 治 finding:disposer 不删 generations[id]——保留单调递增计数器,永不回退。
// 原实现同时 generations.delete(id),致 dispose→re-register 同 id 周期后 generation
// 重算为 `(undefined ?? 0)+1 = 1`,与已触发(应永久 no-op)的旧 disposer 捕获的
// 代际号 1 碰撞,旧 disposer 复活误删新注册条目,破坏 dispose 幂等性与 fail-closed。
// 保留 generations[id] 后,旧 disposer 代际号恒小于当前代际号 → 永久 no-op。
if (this.generations.get(id) === generation) {
this.descriptors.delete(id);
}
};
}
/**
* 按 model id 解析 provider 描述符。
*
* fail-closed:未知 id 抛错(绝不静默回退默认,防误用未配置模型)。
*
* @param modelId 模型 id(如 "glm-5.2")。
* @returns 对应描述符。
* @throws {Error} 未注册该 id。
*/
resolve(modelId: string): ProviderDescriptor {
const desc = this.descriptors.get(modelId);
if (!desc) {
throw new Error(`[provider-registry] no provider registered for model id "${modelId}" (fail-closed)`);
}
return desc;
}
/**
* 列出全部已注册描述符(按注册序,只读快照)。
*
* @returns 只读数组(调用方不可篡改表内状态)。
*/
list(): readonly ProviderDescriptor[] {
return [...this.descriptors.values()];
}
}
// ============================================================================
// 内部:深冻结描述符(运行时不可变,防意外篡改)
// ============================================================================
/**
* 深拷贝一个描述符(顶层浅拷贝 + cost/input 副本),不冻结调用方原对象。
*
* 供 {@link ProviderRegistry.register} 存储前隔离用——registry 持有自己的纯数据副本,
* 调用方注册后仍可安全复用/改写原对象,不会让 Map key 与存储条目状态分裂。
*
* @param desc 待拷贝描述符。
* @returns 全新对象(cost/input 为新引用,顶层字段从原对象复制)。
*/
function cloneDescriptor(desc: ProviderDescriptor): ProviderDescriptor {
return {
id: desc.id,
provider: desc.provider,
baseUrl: desc.baseUrl,
apiKeyEnv: desc.apiKeyEnv,
thinkingFormat: desc.thinkingFormat,
maxTokens: desc.maxTokens,
contextWindow: desc.contextWindow,
reasoning: desc.reasoning,
input: desc.input ? [...desc.input] as ("text" | "image")[] : undefined,
cost: desc.cost ? { ...desc.cost } : undefined,
};
}
/**
* 深冻结一个描述符及其嵌套 cost/input 数组。
*
* @param desc 待冻结描述符。
* @returns 同一对象(已深冻结,运行时篡改抛 TypeError)。
*/
function deepFreezeDescriptor<T extends ProviderDescriptor>(desc: T): Readonly<T> {
if (desc.cost) Object.freeze(desc.cost);
if (desc.input) Object.freeze(desc.input);
return Object.freeze(desc);
}
// ============================================================================
// 已知 provider 常量 —— glm-5.2(默认)+ deepseek-native(stub)
// ============================================================================
/**
* glm-5.2 默认描述符 —— 经 d-robotics 内部网关,thinkingFormat:"qwen" 治命门一。
*
* baseUrl=ai-api.d-robotics.cc/v1, apiKeyEnv=DROBOTICS_LLM_KEY, thinkingFormat:"qwen",
* maxTokens=8192。深冻结,运行时不可变。
*/
export const DEFAULT_GLM_DESCRIPTOR: Readonly<ProviderDescriptor> = deepFreezeDescriptor({
id: GLM_MODEL_ID,
provider: GLM_PROVIDER_NAME,
baseUrl: DROBOTICS_GATEWAY_URL,
apiKeyEnv: GLM_API_KEY_ENV,
thinkingFormat: "qwen",
maxTokens: GLM_MAX_TOKENS,
contextWindow: GLM_CONTEXT_WINDOW,
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
});
/**
* DeepSeek 原生 stub 描述符 —— 走官方网关,thinkingFormat:"none"(原生 reasoning 语义)。
*
* stub:baseUrl/apiKeyEnv 指官方端点,后续接线真实私有网关时覆盖即可。深冻结。
*/
const DEEPSEEK_DESCRIPTOR: Readonly<ProviderDescriptor> = deepFreezeDescriptor({
id: DEEPSEEK_MODEL_ID,
provider: DEEPSEEK_PROVIDER_NAME,
baseUrl: DEEPSEEK_GATEWAY_URL,
apiKeyEnv: DEEPSEEK_API_KEY_ENV,
thinkingFormat: "none",
maxTokens: DEEPSEEK_MAX_TOKENS,
contextWindow: DEEPSEEK_CONTEXT_WINDOW,
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
});
/**
* 已知 provider 列表 —— glm-5.2(默认)+ deepseek-native(stub)。
*
* 深冻结只读。配置加载器默认把这组注册进 ProviderRegistry;用户配置可覆盖/追加。
*/
export const KNOWN_PROVIDERS: readonly ProviderDescriptor[] = Object.freeze([
DEFAULT_GLM_DESCRIPTOR,
DEEPSEEK_DESCRIPTOR,
]);

View File

@ -16,3 +16,45 @@ export type {
LaunchResult,
} from "./agent.js";
export * from "./shared/types.js";
// ============================================================================
// v3 P1+P2 公共 API(T06–T17)—— 核心库导出,供 agent 层与外部消费者使用。
// board-link / flash 能力 barrel 各自也 re-export 了 shared 类型(BoardSpec/FlashPlan
// 等),为避免与上方 `export * from "./shared/types.js"` 重名冲突,这两者只用具名
// re-export 它们的【新增】符号(Registry/Provider/默认 provider),共享类型继续由
// shared/types 单一事实源导出。
// ============================================================================
// T06 事件溯源 + T07 typed event bus + T13 上下文注入 + T14 checkpoint + T16 provider
export * from "./core/pba-session.js";
export * from "./core/pba-event-bus.js";
export * from "./core/provider-registry.js";
export * from "./core/context-injector.js";
export * from "./core/checkpoint-state.js";
// T09 compaction 完整工程
export * from "./compaction/token-meter.js";
export * from "./compaction/tool-result-pruner.js";
export * from "./compaction/summarizer.js";
export * from "./compaction/spill.js";
// T17 审批 / 凭据 / settings / lsp
export * from "./capabilities/approval.js";
export * from "./capabilities/credentials.js";
export * from "./capabilities/settings.js";
export * from "./capabilities/lsp.js";
// T12 子代理 + 工作流编排
export * from "./capabilities/subagent/index.js";
export * from "./capabilities/workflow/index.js";
// T15 profile/bundle 分层
export * from "./profiles/index.js";
// T08 能力接缝 —— board-link + flash(具名 re-export 新增符号,共享类型走 shared/types)
export { BoardLinkRegistry, DEFAULT_BOARD_LINK_PROVIDERS } from "./capabilities/board-link/index.js";
export { RDK_X5_SSH_PROVIDER, RDK_S100_SERIAL_PROVIDER, LOCAL_PROVIDER } from "./capabilities/board-link/index.js";
export type { BoardLinkProvider, BoardLinkHealthResult } from "./capabilities/board-link/index.js";
export { FlashRegistry, DEFAULT_FLASH_PROVIDERS } from "./capabilities/flash/index.js";
export { DD_PROVIDER, FASTBOOT_PROVIDER, DFU_PROVIDER, OPENOCD_PROVIDER } from "./capabilities/flash/index.js";
export type { FlashProvider } from "./capabilities/flash/index.js";

273
src/profiles/base.ts Normal file
View File

@ -0,0 +1,273 @@
/**
* @module profiles/base
*
* Physical Byte Agent —— profile/bundle 分层基座(T15)。
*
* 两个业务方向各自一个 profile,共享 base + 叠差异:
* - 维修诊断(repair-diagnosis):base + pdf-reader / datasheet-rag / peripheral-probe
* - 嵌入式开发(embedded-dev):base + cross-compile / flash / jtag-debugger /
* device-tree / board-link / reg-tool
*
* 单一事实源:{@link DOMAIN_TOOLS} 把每个扩展域映射到它真实注册的工具名
* (取自各扩展 `defineTool({ name })` 的真实串,非臆造)。profiles 的 `tools`
* 由 `toolsFor(extensions)` 派生,扩展域改工具只改这一处,杜绝重复与魔法串。
*
* 三个纯函数(fail-closed / 确定性 / 无副作用 / 可离线单测):
* ① mergeProfiles —— 共享 base + 叠差异(并集、去重、稳定序)
* ② diffProfiles —— 两 profile 的扩展域差异(added / removed)
* ③ toolsFor —— 由扩展域列表派生其暴露的工具名
*
* 范式:纯逻辑模块,顶层无 pi 运行时依赖(零 import type 以外的 pi 引用),
* 无副作用,确定性可测。深冻结所有导出常量。见架构设计文档_v3.md。
*/
// ============================================================================
// 类型契约
// ============================================================================
/**
* 一个 profile —— 一组扩展域 + 它们暴露给 LLM 的工具,附 id 与可选说明。
*
* `extensions`:要装配的扩展域 kebab 名(对应 src/extensions/index.ts 的
* extensionFactories 域名清单,如 "glm-provider" / "safety-gate")。
* `tools`:上述扩展真实注册的工具名(取自各扩展 `defineTool({ name })`,
* 如 "glm_status" / "pshell"),由 {@link toolsFor} 从 {@link DOMAIN_TOOLS}
* 派生,保证每个串都有真实 referent,无魔法串。
*
* 全字段 readonly + 深冻结,运行时不可变。
*/
export interface Profile {
/** profile 标识(resolveProfile 据此查表,fail-closed)。 */
readonly id: string;
/** 要装配的扩展域 kebab 名清单(稳定序:base 在前,差异在后)。 */
readonly extensions: readonly string[];
/** 上述扩展暴露给 LLM 的真实工具名清单(稳定序,去重)。 */
readonly tools: readonly string[];
/** 可选:profile 用途说明(诊断/文档用)。 */
readonly note?: string;
}
// ============================================================================
// 单一事实源 —— 扩展域 → 真实注册工具名(取自各扩展 defineTool name)
// ============================================================================
/**
* 扩展域 → 该扩展真实注册的工具名(取自 src/extensions/<域>.ts 的
* `defineTool({ name })`,逐条核对,非臆造)。
*
* 只挂工具名(safety-gate 是守护规则、edit-strict 是 hook,均不注册工具 → 空数组)。
* 深冻结:每个数组也冻结,运行时篡改抛 TypeError。
*
* 这是 `tools` 的唯一来源:profiles 的 tools 全部由 `toolsFor` 从此表派生,
* 扩展改工具名只需改本表,所有 profile 自动同步,杜绝重复清单与魔法串。
*/
export const DOMAIN_TOOLS: Readonly<Record<string, readonly string[]>> = Object.freeze({
"glm-provider": Object.freeze(["glm_status"]),
"safety-gate": Object.freeze([]), // 守护规则(blocklist),不注册工具
"persistent-shell": Object.freeze(["pshell"]),
"pdf-reader": Object.freeze(["read_pdf"]),
"edit-strict": Object.freeze([]), // hook(before/after),不注册工具
"length-recovery": Object.freeze(["length_recovery_status"]),
"subprocess-isolation": Object.freeze(["isolated_exec"]),
"env-probe": Object.freeze(["env_status"]),
"mcp-bridge": Object.freeze(["mcp_list", "mcp_call"]),
"server-runtime": Object.freeze(["server_session"]),
"hardware-state": Object.freeze(["hw_state"]),
"cross-compile": Object.freeze(["xcompile"]),
flash: Object.freeze(["flash"]),
"peripheral-probe": Object.freeze(["bus_probe"]),
"jtag-debugger": Object.freeze(["debugger"]),
"device-tree": Object.freeze(["dt"]),
"board-link": Object.freeze([
"board_connect",
"board_exec",
"board_scp",
"board_console",
]),
"datasheet-rag": Object.freeze(["datasheet_query"]),
"hardware-verify": Object.freeze(["verify"]),
"loop-orchestrator": Object.freeze(["loop_status"]),
"build-tracker": Object.freeze(["build", "build_status"]),
"reg-tool": Object.freeze(["reg"]),
});
// ============================================================================
// 内部纯工具 —— 深冻结 / 稳定并集 / 派生工具
// ============================================================================
/**
* 冻结一个字符串数组并返回其 readonly 视图(深冻结辅助)。
*
* @param xs 待冻结数组。
* @returns 冻结后的 readonly 数组(运行时篡改抛 TypeError)。
*/
function frozen(xs: readonly string[]): readonly string[] {
return Object.freeze([...xs]) as readonly string[];
}
/**
* 稳定并集:base 在前(保序),其后追加 base 中没有的 delta 项(保序去重)。
*
* 纯逻辑、确定性、无副作用。用作 mergeProfiles 的并集核心。
*
* @param base 基底数组(顺序保留)。
* @param delta 差异数组(仅追加 base 未含项,保序)。
* @returns 去重并集(深冻结)。
*/
function unionStable(
base: readonly string[],
delta: readonly string[],
): readonly string[] {
const seen = new Set<string>(base);
const out: string[] = [...base];
for (const x of delta) {
if (!seen.has(x)) {
seen.add(x);
out.push(x);
}
}
return frozen(out);
}
// ============================================================================
// toolsFor —— 由扩展域派生其暴露的工具名(单一事实源派生)
// ============================================================================
/**
* 由扩展域清单派生其暴露的工具名(从 {@link DOMAIN_TOOLS} 查表,保序去重)。
*
* 未知域 fail-closed:抛错(防止 profile 引入不存在的扩展域,早暴露拼写错误)。
* 这是 `tools` 的唯一来源,杜绝工具名与扩展域脱钩的魔法串。
*
* @param domains 扩展域 kebab 名清单。
* @returns 这些扩展真实注册的工具名(去重保序,深冻结)。
* @throws {Error} 当 domains 含 {@link DOMAIN_TOOLS} 未收录的域时(fail-closed)。
*/
export function toolsFor(domains: readonly string[]): readonly string[] {
const out: string[] = [];
const seen = new Set<string>();
for (const d of domains) {
const tools = DOMAIN_TOOLS[d];
if (tools === undefined) {
throw new Error(
`toolsFor: unknown extension domain "${d}" — not in DOMAIN_TOOLS (fail-closed)`,
);
}
for (const t of tools) {
if (!seen.has(t)) {
seen.add(t);
out.push(t);
}
}
}
return frozen(out);
}
// ============================================================================
// BASE_PROFILE —— 两业务方向共享的扩展基座
// ============================================================================
/**
* base 扩展域清单 —— 两业务方向共享的公共基座。
*
* 来源:契约 base 项(safety-gate / glm-provider / persistent-shell /
* edit-length-recovery / subprocess-isolation / env-probe / mcp-bridge /
* server-runtime / hardware-state)。其中 "edit-length-recovery" 是契约简写,
* 实际无此单一扩展,展开为真实的 edit-strict + length-recovery 两扩展
* (均为 hook/恢复类公共基座,T08 已按真实名自适应)。
*/
export const BASE_EXTENSIONS: readonly string[] = Object.freeze([
"glm-provider",
"safety-gate",
"persistent-shell",
"edit-strict",
"length-recovery",
"subprocess-isolation",
"env-probe",
"mcp-bridge",
"server-runtime",
"hardware-state",
]);
/**
* base profile —— 两业务方向共享的扩展 + 工具基座。
*
* tools 由 {@link toolsFor} 从 {@link BASE_EXTENSIONS} 派生(含 pshell /
* glm_status / isolated_exec / env_status / mcp_list / mcp_call /
* server_session / hw_state / length_recovery_status;safety-gate 与
* edit-strict 不注册工具,故 base 工具数 < 扩展数)。深冻结,运行时不可变。
*/
export const BASE_PROFILE: Profile = Object.freeze({
id: "base",
extensions: BASE_EXTENSIONS,
tools: toolsFor(BASE_EXTENSIONS),
note: "共享基座:provider / 安全门 / 持久 shell / 编辑恢复 / 子进程隔离 / 环境探针 / MCP 桥 / 服务运行时 / 硬件状态",
}) as Profile;
// ============================================================================
// mergeProfiles —— 共享 base + 叠差异(并集去重,稳定序)
// ============================================================================
/**
* 共享 base + 叠差异:返回 base 与 delta 的扩展/工具并集(去重,base 序在前)。
*
* 契约签名 delta: Pick<Profile,"extensions"|"tools"> —— delta 不带 id/note,
* 故结果继承 base 的 id/note;具体命名 profile(repair-diagnosis /
* embedded-dev)在调用处用对象展开覆盖 id/note,复用本函数做并集重活。
*
* 纯逻辑、确定性、无副作用。结果深冻结。
*
* @param base 基底 profile(extensions/tools 序保留在前)。
* @param delta 差异(仅 extensions/tools;追加 base 未含项)。
* @returns 合并后的新 profile(id/note 继承 base,深冻结)。
*/
export function mergeProfiles(
base: Profile,
delta: Pick<Profile, "extensions" | "tools">,
): Profile {
return Object.freeze({
id: base.id,
extensions: unionStable(base.extensions, delta.extensions),
tools: unionStable(base.tools, delta.tools),
note: base.note,
}) as Profile;
}
// ============================================================================
// diffProfiles —— 两 profile 扩展域差异(added / removed)
// ============================================================================
/**
* 两 profile 的扩展域差异:b 比 a 多的 = added,b 比 a 少的 = removed。
*
* 按 SPEC "各叠差异扩展" 只 diff `extensions`(profile 选择主轴,工具随扩展派生,
* 避免扩展域名与工具名同形如 "flash" 的碰撞歧义)。工具差异调用方可直接 diff
* `.tools`。added/removed 各保序(不主动去重;遍历 a/b.extensions 逐条比对,
* 重复由输入驱动 —— 真实 profile 无重复扩展条目,故输出无重复;若传入含重复
* 的畸形 profile,输出会保留重复条目,调用方负责输入归一)。
*
* 纯逻辑、确定性、无副作用。结果数组深冻结。
*
* @param a 基准 profile。
* @param b 对比 profile。
* @returns { added: b 有 a 无;removed: a 有 b 无 }(均深冻结 readonly)。
*/
export function diffProfiles(
a: Profile,
b: Profile,
): { added: readonly string[]; removed: readonly string[] } {
const aSet = new Set(a.extensions);
const bSet = new Set(b.extensions);
const added: string[] = [];
for (const x of b.extensions) {
if (!aSet.has(x)) added.push(x);
}
const removed: string[] = [];
for (const x of a.extensions) {
if (!bSet.has(x)) removed.push(x);
}
return Object.freeze({
added: frozen(added),
removed: frozen(removed),
}) as { added: readonly string[]; removed: readonly string[] };
}

View File

@ -0,0 +1,60 @@
/**
* @module profiles/embedded-dev
*
* 嵌入式开发 profile —— base + cross-compile / flash / jtag-debugger /
* device-tree / board-link / reg-tool。
*
* 第二个业务方向(嵌入式 C 层开发)要的能力:交叉编译(cross-compile 的
* xcompile)、三段式烧录(flash 的 flash)、JTAG 调试(jtag-debugger 的
* debugger)、设备树解析(device-tree 的 dt)、板链路连接与执行(board-link
* 的 board_connect/board_exec/board_scp/board_console)、寄存器读写(reg-tool
* 的 reg)。
*
* 由 {@link mergeProfiles}(BASE_PROFILE, EMBEDDED_DELTA) 复用 base 并集重活,
* 仅覆盖 id / note —— 单一事实源,无重复清单。深冻结,运行时不可变。
*
* 范式:纯逻辑,顶层仅 import type + 命名导出,零 pi 运行时依赖。
*/
import type { Profile } from "./base.js";
import { BASE_PROFILE, mergeProfiles, toolsFor } from "./base.js";
/**
* 嵌入式开发差异扩展域(base 之上叠加)。
* tools 由 {@link toolsFor} 从本域派生 → xcompile / flash / debugger / dt /
* board_connect / board_exec / board_scp / board_console / reg。
*/
export const EMBEDDED_DEV_DELTA: Readonly<
Pick<Profile, "extensions" | "tools">
> = Object.freeze({
extensions: Object.freeze([
"cross-compile",
"flash",
"jtag-debugger",
"device-tree",
"board-link",
"reg-tool",
]),
tools: toolsFor([
"cross-compile",
"flash",
"jtag-debugger",
"device-tree",
"board-link",
"reg-tool",
]),
}) as Readonly<Pick<Profile, "extensions" | "tools">>;
/**
* 嵌入式开发 profile —— base + cross-compile / flash / jtag-debugger /
* device-tree / board-link / reg-tool。
*
* 复用 {@link mergeProfiles} 做 extensions/tools 并集(去重保序),仅覆盖 id/note。
* 工具集 = base 工具 + xcompile + flash + debugger + dt + board_connect +
* board_exec + board_scp + board_console + reg。
*/
export const EMBEDDED_DEV_PROFILE: Profile = Object.freeze({
...mergeProfiles(BASE_PROFILE, EMBEDDED_DEV_DELTA),
id: "embedded-dev",
note: "嵌入式开发:base + 交叉编译 + 烧录 + JTAG 调试 + 设备树 + 板链路 + 寄存器读写",
}) as Profile;

77
src/profiles/index.ts Normal file
View File

@ -0,0 +1,77 @@
/**
* @module profiles
*
* profile/bundle 分层 barrel(T15)。
*
* 职责:
* - re-export 三 profile 常量 + Profile 类型 + mergeProfiles / diffProfiles /
* toolsFor / DOMAIN_TOOLS / BASE_EXTENSIONS(命名导出,下游可深引用)
* - {@link resolveProfile}:fail-closed 按 id 查表,未知 id 抛错
*
* 范式:纯逻辑,顶层仅 import type + 命名 re-export,零 pi 运行时依赖。
* 不注册任何扩展、不改 src/extensions/index.ts barrel(独占文件边界)。
*/
import type { Profile } from "./base.js";
// 仅把注册表(PROFILE_REGISTRY)实际引用的三个 profile 常量作值导入;
// 纯函数 / 类型 / delta 用 `export ... from` 直通 re-export,避免重复值导入。
import { BASE_PROFILE } from "./base.js";
import { REPAIR_DIAGNOSIS_PROFILE } from "./repair-diagnosis.js";
import { EMBEDDED_DEV_PROFILE } from "./embedded-dev.js";
// 类型 re-export(import type 擦除,下游类型侧统一从本 barrel 取)
export type { Profile } from "./base.js";
// 域→工具表 + base 扩展清单 re-export(下游诊断/装配用)
export { DOMAIN_TOOLS, BASE_EXTENSIONS } from "./base.js";
// 纯函数 re-export(直通,不经本模块值绑定)
export { mergeProfiles, diffProfiles, toolsFor } from "./base.js";
// 差异清单 re-export
export { REPAIR_DIAGNOSIS_DELTA } from "./repair-diagnosis.js";
export { EMBEDDED_DEV_DELTA } from "./embedded-dev.js";
// 三 profile 常量 re-export
export { BASE_PROFILE } from "./base.js";
export { REPAIR_DIAGNOSIS_PROFILE } from "./repair-diagnosis.js";
export { EMBEDDED_DEV_PROFILE } from "./embedded-dev.js";
// ============================================================================
// PROFILE_REGISTRY + resolveProfile —— fail-closed 按 id 查表
// ============================================================================
/**
* id → profile 注册表(深冻结,运行时不可变)。
*
* resolveProfile 据此查表。新增 profile 只需在此注册一行,resolveProfile 自动覆盖。
*/
const PROFILE_REGISTRY: Readonly<Record<string, Profile>> = Object.freeze({
[BASE_PROFILE.id]: BASE_PROFILE,
[REPAIR_DIAGNOSIS_PROFILE.id]: REPAIR_DIAGNOSIS_PROFILE,
[EMBEDDED_DEV_PROFILE.id]: EMBEDDED_DEV_PROFILE,
}) as Readonly<Record<string, Profile>>;
/**
* 按 id 解析 profile —— fail-closed:未知 id 抛错(不返回 undefined/默认值,
* 防止调用方静默拿到错 profile 后装配出错扩展)。
*
* 用 {@link Object.hasOwn} 判定而非 `id in PROFILE_REGISTRY` 或下标取值后
* `!== undefined`:后两者走原型链,对 "toString" / "constructor" / "__proto__"
* 等 Object.prototype 继承键会取到继承的函数/对象(!== undefined → 不抛 →
* 返回继承成员当 Profile 用,调用方后续访问 .extensions/.tools 行为不可预期)。
* `Object.hasOwn` 只认自身属性,继承键一律判为未注册 → fail-closed 抛错。
*
* 纯逻辑、确定性、无副作用。返回注册表中的冻结实例(引用共享,不复制)。
*
* @param id profile 标识("base" / "repair-diagnosis" / "embedded-dev")。
* @returns 对应的冻结 profile。
* @throws {Error} 当 id 未在 {@link PROFILE_REGISTRY} 注册时(fail-closed)。
*/
export function resolveProfile(id: string): Profile {
if (!Object.hasOwn(PROFILE_REGISTRY, id)) {
throw new Error(
`resolveProfile: unknown profile id "${id}" — registered: ${Object.keys(
PROFILE_REGISTRY,
).join(", ")} (fail-closed)`,
);
}
return PROFILE_REGISTRY[id];
}

View File

@ -0,0 +1,44 @@
/**
* @module profiles/repair-diagnosis
*
* 维修诊断 profile —— base + pdf-reader / datasheet-rag / peripheral-probe。
*
* 第一个业务方向(电子维修诊断 9 阶段 SOP)要的能力:读器件 datasheet PDF
* (pdf-reader 的 read_pdf)、按器件型号 RAG 查 datasheet 段落(datasheet-rag
* 的 datasheet_query)、探外设总线(peripheral-probe 的 bus_probe)。
*
* 由 {@link mergeProfiles}(BASE_PROFILE, REPAIR_DELTA) 复用 base 并集重活,
* 仅覆盖 id / note —— 单一事实源,无重复清单。深冻结,运行时不可变。
*
* 范式:纯逻辑,顶层仅 import type + 命名导出,零 pi 运行时依赖。
*/
import type { Profile } from "./base.js";
import { BASE_PROFILE, mergeProfiles, toolsFor } from "./base.js";
/**
* 维修诊断差异扩展域(base 之上叠加)。
* tools 由 {@link toolsFor} 从本域派生 → read_pdf / datasheet_query / bus_probe。
*/
export const REPAIR_DIAGNOSIS_DELTA: Readonly<
Pick<Profile, "extensions" | "tools">
> = Object.freeze({
extensions: Object.freeze([
"pdf-reader",
"datasheet-rag",
"peripheral-probe",
]),
tools: toolsFor(["pdf-reader", "datasheet-rag", "peripheral-probe"]),
}) as Readonly<Pick<Profile, "extensions" | "tools">>;
/**
* 维修诊断 profile —— base + pdf-reader / datasheet-rag / peripheral-probe。
*
* 复用 {@link mergeProfiles} 做 extensions/tools 并集(去重保序),仅覆盖 id/note。
* 工具集 = base 工具 + read_pdf + datasheet_query + bus_probe。
*/
export const REPAIR_DIAGNOSIS_PROFILE: Profile = Object.freeze({
...mergeProfiles(BASE_PROFILE, REPAIR_DIAGNOSIS_DELTA),
id: "repair-diagnosis",
note: "维修诊断:base + PDF datasheet 阅读 + datasheet RAG 检索 + 外设总线探针",
}) as Profile;

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

1328
tests/compaction.test.ts Normal file

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

1993
tests/doc-sync.test.ts Normal file

File diff suppressed because it is too large Load Diff

729
tests/pba-event-bus.test.ts Normal file
View File

@ -0,0 +1,729 @@
/**
* pba-event-bus 测试套件 —— T07 类型化事件总线 + ScopeKey 隔离。
*
* 被测对象:src/core/pba-event-bus.ts 的命名导出
* (PbaEventBus, KNOWN_EVENTS, 及类型 PbaListener/PbaEmitter/PbaEventBusOptions/ScopeKey)。
*
* 多方法论覆盖(每个 describe 块标题标注方法论名):
* ① 等价类划分 —— 作用域归一/冒泡的有效·无效·边界类
* ② 边界值分析 —— off-by-one / 空 / 单元素 / 多元素 / 段边界
* ③ 决策表 —— scopeReceives 全分支组合 → 期望
* ④ 状态转换 —— 注册表生命周期 + 迁移 + 重入 + 不可达态
* ⑤ 变异测试 —— 5 个 seeded bug 内联副本,逐个被杀
* ⑥ 对抗/fuzz —— 畸形/滥用输入
* ⑦ 元蜕变/不变式 —— 跨变换保持的性质
*
* 纯逻辑模块零 pi 依赖,离线单测,无硬件无网络。见架构设计文档_v3.md §5.2 / §7(T07)。
*/
import { describe, it, expect } from "vitest";
import {
PbaEventBus,
KNOWN_EVENTS,
type PbaListener,
type PbaEmitter,
type ScopeKey,
} from "../src/core/pba-event-bus.js";
// ============================================================================
// 辅助:spy emitter(断言 outbound 转发)
// ============================================================================
/** 构造记录调用的 spy emitter。 */
function spyEmitter(): PbaEmitter & { calls: Array<{ event: string; data: unknown }> } {
const calls: Array<{ event: string; data: unknown }> = [];
return {
calls,
on: () => () => {},
emit: (event, data) => calls.push({ event, data }),
};
}
/** 记录型 listener 工厂。 */
function recorder(): { listener: PbaListener; seen: unknown[] } {
const seen: unknown[] = [];
return { seen, listener: (a) => seen.push(a) };
}
// ============================================================================
// ① 等价类划分 —— 作用域归一 / 冒泡的有效·无效·边界类
// ============================================================================
describe("① 等价类划分 —— normalizeScope 行为类(经 on/emit 可观察)", () => {
// 有效类:单段 / 多段 / global(undefined)
it.each([
["单段 'agent'", "agent"],
["多段 'agent.sub.deep'", "agent.sub.deep"],
])("有效作用域 %s 正常冒泡(global 监听收)", (_label, scope) => {
const bus = new PbaEventBus();
const { listener, seen } = recorder();
bus.on("build:done", listener); // global
bus.emit("build:done", 1, scope);
expect(seen).toEqual([1]); // global 收一切
});
it.each([
["undefined", undefined],
["空串 ''", ""],
["纯空白 ' '", " "],
["只有点 '.'", "."],
["多点 '..'", ".."],
])("无效/归零作用域 %s 归一为 global(等同缺省)", (_label, scope) => {
const bus = new PbaEventBus();
const got: string[] = [];
// 注册一个 scoped 监听(agent),emit 用归零 scope 不应下渗到子
bus.on("build:done", () => got.push("scoped"), "agent");
bus.emit("build:done", null, scope);
expect(got).toEqual([]); // 归零为 global emit → 不下渗到 scoped
});
it.each([
["'a..b' → 'a.b'", "a..b", "a.b"],
["'a.' → 'a'", "a.", "a"],
["'.b' → 'b'", ".b", "b"],
["'.a.b.' → 'a.b'", ".a.b.", "a.b"],
["'a...b' → 'a.b'", "a...b", "a.b"],
])("含空段作用域 %s 归一(段边界对齐)", (_label, raw, norm) => {
// 用 scopedScope + 祖先冒泡反推归一结果:注册于 norm 的监听应收 emit 于 raw
const bus = new PbaEventBus();
const { listener, seen } = recorder();
bus.on("build:done", listener, norm);
bus.emit("build:done", "x", raw); // raw 归一后应 === norm → 收
expect(seen).toEqual(["x"]);
});
});
// ============================================================================
// ② 边界值分析 —— off-by-one / 空 / 单 / 多 / 段边界
// ============================================================================
describe("② 边界值分析 —— 监听数边界(0/1/2/N)", () => {
it("0 监听:emit 无副作用不抛,仍转发 emitter", () => {
const spy = spyEmitter();
const bus = new PbaEventBus({ emitter: spy });
expect(() => bus.emit("build:done", null)).not.toThrow();
expect(bus.listenerCount("build:done")).toBe(0);
expect(spy.calls.length).toBe(1);
});
it("1 监听:收一次", () => {
const bus = new PbaEventBus();
const { listener, seen } = recorder();
bus.on("build:done", listener);
bus.emit("build:done", "only");
expect(seen).toEqual(["only"]);
expect(bus.listenerCount("build:done")).toBe(1);
});
it("2 监听:按注册序广播,均收,互不影响", () => {
const bus = new PbaEventBus();
const order: string[] = [];
bus.on("build:done", () => order.push("a"));
bus.on("build:done", () => order.push("b"));
bus.emit("build:done", null);
expect(order).toEqual(["a", "b"]);
expect(bus.listenerCount("build:done")).toBe(2);
});
it("N=50 监听:全收,顺序严格递增", () => {
const bus = new PbaEventBus();
const N = 50;
const order: number[] = [];
for (let k = 0; k < N; k++) bus.on("build:done", () => order.push(order.length));
bus.emit("build:done", null);
expect(order.length).toBe(N);
expect(order).toEqual(Array.from({ length: N }, (_, k) => k));
});
});
describe("② 边界值分析 —— scope 段边界(off-by-one 祖先判定)", () => {
it.each([
["等价:agent vs agent", "agent", "agent", true],
["深一层:agent vs agent.sub", "agent", "agent.sub", true],
["深两层:agent vs agent.sub.deep", "agent", "agent.sub.deep", true],
["浅一层(后代不收父):agent.sub vs agent", "agent.sub", "agent", false],
["段边界:agent vs agentX(非裸前缀)", "agent", "agentX", false],
["段边界:agent vs agent-(连字符非分隔)", "agent", "agent-", false],
["旁支:agent vs other", "agent", "other", false],
["前缀但非祖先:ab vs abc 段", "ab", "abc", false],
])(
"段边界 %s:listenerScope=%s emitScope=%s → receives=%s",
(_label, ls, es, expected) => {
const bus = new PbaEventBus();
let got = false;
bus.on("build:done", () => (got = true), ls);
bus.emit("build:done", null, es);
expect(got).toBe(expected);
},
);
});
describe("② 边界值分析 —— scopedScope 拼接边界", () => {
it.each([
["('a','b') → 'a.b'", "a", "b", "a.b"],
["('','b') → 'b'(父空=global)", "", "b", "b"],
["('a','') → 'a'(子空)", "a", "", "a"],
["('','') → ''(global)", "", "", ""],
["('a.b','c.d') → 'a.b.c.d'", "a.b", "c.d", "a.b.c.d"],
["('a..','b') → 'a.b'(归一)", "a..", "b", "a.b"],
])("scopedScope %s", (_label, p, c, expected) => {
expect(new PbaEventBus().scopedScope(p as ScopeKey, c as ScopeKey)).toBe(expected);
});
});
// ============================================================================
// ③ 决策表 —— scopeReceives 全分支组合 → 期望
// ============================================================================
describe("③ 决策表 —— scopeReceives 全分支(listenerScope × emitScope)", () => {
// 决策表(L=listenerScope, E=emitScope, R=receives):
// L=undef E=undef → true (global 收 global emit)
// L=undef E=str → true (global 收一切)
// L=str E=undef → false (global emit 不下渗子)
// L=str E=L → true (等价)
// L=str E=L+".x" → true (祖先)
// L=str E=L[:-1]+"X" → false (段边界)
// L=str E=其它 → false (旁支/后代)
const cases: Array<[string | undefined, string | undefined, boolean, string]> = [
[undefined, undefined, true, "global 监听收 global emit"],
[undefined, "agent", true, "global 监听收 scoped emit"],
["agent", undefined, false, "global emit 不下渗到 scoped 监听"],
["agent", "agent", true, "等价 scope 收"],
["agent", "agent.sub", true, "祖先监听收子 emit"],
["agent", "agent.sub.deep", true, "远祖收深子"],
["agent.sub", "agent", false, "后代不收父 emit"],
["agent", "agentX", false, "段边界非裸前缀"],
["agent", "other", false, "旁支不收"],
["agent.sub", "agent.other", false, "兄弟节点不收"],
];
for (const [ls, es, expected, name] of cases) {
it(`决策表:${name} (L=${ls}, E=${es}) → ${expected}`, () => {
const bus = new PbaEventBus();
let got = false;
bus.on("build:done", () => (got = true), ls);
bus.emit("build:done", null, es);
expect(got).toBe(expected);
});
}
});
// ============================================================================
// ④ 状态转换 —— 注册表生命周期 + 迁移 + 重入 + 不可达态
// ============================================================================
describe("④ 状态转换 —— 注册表生命周期迁移", () => {
it("empty → on → has1 → on → has2 → off → has1 → dispose → empty", () => {
const bus = new PbaEventBus();
expect(bus.listenerCount("build:done")).toBe(0); // empty
const l: PbaListener = () => {};
const d1 = bus.on("build:done", l);
expect(bus.listenerCount("build:done")).toBe(1); // has1
const d2 = bus.on("build:done", l, "agent");
expect(bus.listenerCount("build:done")).toBe(2); // has2
bus.off("build:done", l);
expect(bus.listenerCount("build:done")).toBe(0); // empty(off 清全部)
// 不可达态:dispose 已卸载条目(d1/d2)应为 no-op,不复活条目
d1();
d2();
expect(bus.listenerCount("build:done")).toBe(0); // 仍 empty
});
it("disposer 卸载单条(幂等;不影响同 listener 其它条)", () => {
const bus = new PbaEventBus();
const l: PbaListener = () => {};
const dA = bus.on("build:done", l, "a");
bus.on("build:done", l, "b");
expect(bus.listenerCount("build:done")).toBe(2);
dA(); // 仅卸 scope=a 那条
expect(bus.listenerCount("build:done")).toBe(1);
dA(); // 幂等 no-op
expect(bus.listenerCount("build:done")).toBe(1);
});
it("未注册事件 off / listenerCount 为 no-op/0(防御不可达态)", () => {
const bus = new PbaEventBus();
expect(bus.listenerCount("nope")).toBe(0);
expect(() => bus.off("nope", () => {})).not.toThrow();
});
});
describe("④ 状态转换 —— 迭代中重入(on/off/dispose/emit during emit)", () => {
it("emit 期间监听自卸载(dispose)不崩,快照隔离保证后续仍跑", () => {
const bus = new PbaEventBus();
const order: string[] = [];
let d = () => {};
d = bus.on("build:done", () => {
order.push("a");
d(); // 迭代中卸载自身
});
bus.on("build:done", () => order.push("b"));
bus.emit("build:done", null);
expect(order).toEqual(["a", "b"]); // 快照:b 仍跑
expect(bus.listenerCount("build:done")).toBe(1); // a 已卸
});
it("emit 期间新增 on 不被当前 emit 触发(快照不含后增)", () => {
const bus = new PbaEventBus();
const order: string[] = [];
bus.on("build:done", () => {
order.push("a");
bus.on("build:done", () => order.push("late")); // 迭代中增
});
bus.emit("build:done", null);
expect(order).toEqual(["a"]); // late 不在本轮快照
expect(bus.listenerCount("build:done")).toBe(2);
bus.emit("build:done", null);
expect(order).toEqual(["a", "a", "late"]); // 下一轮才见
});
it("emit 期间 off 后续监听:快照仍含(snapshot 语义,已卸条仍跑)", () => {
const bus = new PbaEventBus();
const order: string[] = [];
const lNext: PbaListener = () => order.push("b");
bus.on("build:done", () => {
order.push("a");
bus.off("build:done", lNext); // 迭代中卸 b
});
bus.on("build:done", lNext);
bus.emit("build:done", null);
// 快照仍含 b → b 仍跑(已知 snapshot 语义,文档化)
expect(order).toEqual(["a", "b"]);
expect(bus.listenerCount("build:done")).toBe(1); // b 已从注册表删
});
it("重入 emit(监听内再 emit 同事件)有界终止不无限递归", () => {
const bus = new PbaEventBus();
let depth = 0;
let maxDepth = 0;
bus.on("build:done", () => {
depth++;
maxDepth = Math.max(maxDepth, depth);
if (depth < 3) bus.emit("build:done", null); // 重入
depth--;
});
expect(() => bus.emit("build:done", null)).not.toThrow();
expect(maxDepth).toBe(3);
});
});
// ============================================================================
// ④ 状态转换 —— waterfall 链状态机(链首/链中/链末/短路/重入)
// ============================================================================
describe("④ 状态转换 —— waterfall 链状态", () => {
it("链首→链中→链末:均调 next,全跑完,返回穿线 args(同引用)", () => {
const bus = new PbaEventBus();
const order: string[] = [];
bus.on("debugger:attach", (_a, next) => { order.push("a"); next(); });
bus.on("debugger:attach", (_a, next) => { order.push("b"); next(); });
bus.on("debugger:attach", () => { order.push("c"); }); // 链末不调 next
const payload = { x: 1 };
const out = bus.waterfall("debugger:attach", payload);
expect(order).toEqual(["a", "b", "c"]);
expect(out).toBe(payload);
});
it("链首不调 next → 短路(状态=断),中/末不跑", () => {
const bus = new PbaEventBus();
const order: string[] = [];
bus.on("debugger:attach", () => { order.push("a"); /* 不调 next */ });
bus.on("debugger:attach", () => order.push("b"));
bus.on("debugger:attach", () => order.push("c"));
const out = bus.waterfall("debugger:attach", "p");
expect(order).toEqual(["a"]);
expect(out).toBe("p");
});
it("链中不调 next → 短路于中(末不跑)", () => {
const bus = new PbaEventBus();
const order: string[] = [];
bus.on("debugger:attach", (_a, next) => { order.push("a"); next(); });
bus.on("debugger:attach", () => { order.push("b"); /* 短路 */ });
bus.on("debugger:attach", () => order.push("c"));
bus.waterfall("debugger:attach", null);
expect(order).toEqual(["a", "b"]);
});
it("空链(0 监听)waterfall 不抛,返回原 args", () => {
const bus = new PbaEventBus();
const out = bus.waterfall("nope", { z: 9 });
expect(out).toEqual({ z: 9 });
});
it("waterfall args 按引用穿线:上游改动下游可见", () => {
const bus = new PbaEventBus();
bus.on("build:done", (a, next) => { (a as { v?: number }).v = 1; next(); });
bus.on("build:done", (a, next) => { (a as { v?: number }).v = (a as { v?: number }).v! + 10; next(); });
const payload: { v?: number } = {};
const out = bus.waterfall("build:done", payload) as { v?: number };
expect(out).toBe(payload);
expect(out.v).toBe(11);
});
it("waterfall 监听抛错向上传播(链断,不静默吞)", () => {
const bus = new PbaEventBus();
const order: string[] = [];
bus.on("build:done", (_a, next) => { order.push("a"); next(); });
bus.on("build:done", () => { order.push("b"); throw new Error("boom"); });
bus.on("build:done", () => order.push("c"));
expect(() => bus.waterfall("build:done", null)).toThrow("boom");
expect(order).toEqual(["a", "b"]); // c 不跑
});
it("waterfall 按 scope 冒泡选监听(同 emit 规则)", () => {
const bus = new PbaEventBus();
const ran: string[] = [];
bus.on("debugger:attach", (_a, next) => { ran.push("parent"); next(); }, "agent");
bus.on("debugger:attach", (_a, next) => { ran.push("sibling"); next(); }, "agent.other");
bus.on("debugger:attach", (_a, next) => { ran.push("global"); next(); });
bus.waterfall("debugger:attach", null, "agent.sub");
expect(ran).toEqual(["parent", "global"]); // 祖先 + global 续链;旁支 sibling 非匹配不收
});
});
// ============================================================================
// ⑥ 对抗/fuzz —— 畸形/滥用输入
// ============================================================================
describe("⑥ 对抗/fuzz —— 畸形/滥用输入不崩", () => {
it("args=null/undefined/0/false/'' 均原样穿透", () => {
const bus = new PbaEventBus();
const seen: unknown[] = [];
bus.on("build:done", (a) => seen.push(a));
for (const a of [null, undefined, 0, false, "", NaN]) {
bus.emit("build:done", a);
}
expect(seen).toEqual([null, undefined, 0, false, "", NaN]);
});
it("循环引用对象作 args 不崩(按引用传,监听可读)", () => {
const bus = new PbaEventBus();
const obj: { self?: unknown; n: number } = { n: 1 };
obj.self = obj;
let got: unknown = null;
bus.on("build:done", (a) => { got = a; });
bus.emit("build:done", obj);
expect(got).toBe(obj);
});
it("巨大 payload(1e6 元素数组)不崩、同引用", () => {
const bus = new PbaEventBus();
const big = new Array(1_000_000).fill(0);
let got: unknown = null;
bus.on("build:done", (a) => { got = a; });
bus.emit("build:done", big);
expect(got).toBe(big);
});
it("超长 scope 字符串(1e4 段)归一不崩", () => {
const bus = new PbaEventBus();
const segs = Array.from({ length: 10_000 }, (_, i) => `s${i}`).join(".");
const { listener, seen } = recorder();
bus.on("build:done", listener); // global 收
bus.emit("build:done", 1, segs);
expect(seen).toEqual([1]);
});
it("event 名含特殊字符 / 空串 不崩(开放扩展,不强制 KNOWN_EVENTS)", () => {
const bus = new PbaEventBus();
const seen: string[] = [];
bus.on("weird:event:with:colons", () => seen.push("a"));
bus.on("", () => seen.push("b"));
bus.emit("weird:event:with:colons", null);
bus.emit("", null);
expect(seen).toEqual(["a", "b"]);
});
it("waterfall 监听内多次调 next(滥用):链被推进但不重入已越界项,仍终止", () => {
const bus = new PbaEventBus();
const order: string[] = [];
bus.on("build:done", (_a, next) => { order.push("a"); next(); next(); /* 误调两次 */ });
bus.on("build:done", () => order.push("b"));
expect(() => bus.waterfall("build:done", null)).not.toThrow();
// a 首 next → 跑 b(i→2);a 次 next → i=2>=len(2) 直接返回,不重跑 b
expect(order).toEqual(["a", "b"]);
});
it("disposer 在 emit 内对另一事件操作互不干扰", () => {
const bus = new PbaEventBus();
const d = bus.on("a", () => {});
bus.on("b", () => d()); // emit b 时卸 a
expect(bus.listenerCount("a")).toBe(1);
bus.emit("b", null);
expect(bus.listenerCount("a")).toBe(0);
});
});
// ============================================================================
// ⑤ 变异测试 —— 5 个 seeded bug 内联副本,逐个被杀
// 每个 it:real 副本产正确值,buggy 副本产错误值 →
// 断言「正确值」的测试若植入该 bug 即 FAIL(bug 被杀)。
// 副本镜像 src/core/pba-event-bus.ts 对应纯函数/方法逻辑。
// ============================================================================
// --- 镜像:normalizeScope(src 第 133-140 行) ---
function normalizeScopeReal(scope: string | undefined): string | undefined {
if (scope === undefined) return undefined;
const segs = scope.split(".").filter((s) => s.length > 0);
return segs.length === 0 ? undefined : segs.join(".");
}
// 变体 M2:filter 条件 `s.length > 0` → `s.length >= 0`(恒真,保留空段)
function normalizeScopeBuggyKeepEmpty(scope: string | undefined): string | undefined {
if (scope === undefined) return undefined;
const segs = scope.split(".").filter((s) => s.length >= 0); // BUG
return segs.length === 0 ? undefined : segs.join(".");
}
// --- 镜像:scopeReceives(src 第 153-163 行) ---
function scopeReceivesReal(ls: string | undefined, es: string | undefined): boolean {
if (ls === undefined) return true;
if (es === undefined) return false;
if (ls === es) return true;
return es.startsWith(ls + ".");
}
// 变体 M1:丢段边界 "."(裸前缀匹配)→ "agent" 误判为 "agentX" 祖先
function scopeReceivesBuggyNakedPrefix(ls: string | undefined, es: string | undefined): boolean {
if (ls === undefined) return true;
if (es === undefined) return false;
if (ls === es) return true;
return es.startsWith(ls); // BUG:丢 "."
}
// --- 镜像:waterfall next 链(src 第 350-360 行) ---
function waterfallReal(matched: PbaListener[], args: unknown): unknown {
let i = 0;
const next = (): void => {
if (i >= matched.length) return; // 链末
const entry = matched[i];
i++;
entry(args, next);
};
next();
return args;
}
// 变体 M3:`i >= matched.length` → `i > matched.length`(off-by-one,链末越界)
function waterfallBuggyOffByOne(matched: PbaListener[], args: unknown): unknown {
let i = 0;
const next = (): void => {
if (i > matched.length) return; // BUG:应为 >=
const entry = matched[i]; // 链末时越界 → undefined
i++;
entry(args, next); // undefined(args,next) → TypeError
};
next();
return args;
}
// --- 镜像:disposer splice(src 第 283-289 行 on 返回闭包核心) ---
function disposeReal(arr: unknown[], entry: unknown): void {
const idx = arr.indexOf(entry);
if (idx >= 0) arr.splice(idx, 1);
}
// 变体 M4:`idx >= 0` → `idx > 0`(off-by-one,漏卸 index 0)
function disposeBuggySkipIndex0(arr: unknown[], entry: unknown): void {
const idx = arr.indexOf(entry);
if (idx > 0) arr.splice(idx, 1); // BUG
}
// --- 变体 M5:KNOWN_EVENTS 漏 Object.freeze(可变) ---
const KNOWN_EVENTS_BUGGY_NOFREEZE: string[] = [...KNOWN_EVENTS];
describe("⑤ 变异测试 —— seeded bug 逐个被杀", () => {
it("M1 [scopeReceives 丢段边界]:'agent' 不应是 'agentX' 的祖先", () => {
const correct = false;
expect(scopeReceivesReal("agent", "agentX")).toBe(correct); // 正确
expect(scopeReceivesBuggyNakedPrefix("agent", "agentX")).toBe(true); // 变体误判
// 杀伤验证:buggy 副本跑真实断言必 FAIL(bug 被杀)
expect(() => expect(scopeReceivesBuggyNakedPrefix("agent", "agentX")).toBe(correct)).toThrow();
// 杀它的测试:② 段边界 / ③ 决策表「段边界非裸前缀」
});
it("M2 [normalizeScope 保留空段]:'a..b' 应归一为 'a.b'", () => {
const correct = "a.b";
expect(normalizeScopeReal("a..b")).toBe(correct); // 正确
expect(normalizeScopeBuggyKeepEmpty("a..b")).toBe("a..b"); // 变体未归一
// 杀伤验证:buggy 副本跑真实断言必 FAIL
expect(() => expect(normalizeScopeBuggyKeepEmpty("a..b")).toBe(correct)).toThrow();
// 杀它的测试:① 等价类「含空段作用域归一」
});
it("M3 [waterfall 链末 >= 改 > off-by-one]:空链应安全返回不抛", () => {
expect(() => waterfallReal([], null)).not.toThrow(); // 正确
expect(() => waterfallBuggyOffByOne([], null)).toThrow(); // 变体越界抛
// 杀伤验证:buggy 副本跑真实断言(不抛)必 FAIL
expect(() => expect(() => waterfallBuggyOffByOne([], null)).not.toThrow()).toThrow();
expect(waterfallReal([], null)).toBe(null);
// 杀它的测试:④ waterfall「空链不抛」+「三链全跑完链末 next no-op」
});
it("M4 [disposer idx>=0 改 >0 off-by-one]:index 0 的条目应可卸载", () => {
const entry = {};
const arrReal = [entry];
const arrBuggy = [entry];
disposeReal(arrReal, entry);
disposeBuggySkipIndex0(arrBuggy, entry);
expect(arrReal).toEqual([]); // 正确:卸掉
expect(arrBuggy).toEqual([entry]); // 变体:漏卸 index 0
// 杀伤验证:buggy 副本跑真实断言(卸后为空)必 FAIL
expect(() => expect(arrBuggy).toEqual([])).toThrow();
// 杀它的测试:④「disposer 卸载单条」+ ② 单元素边界
});
it("M5 [KNOWN_EVENTS 漏 freeze]:push 应抛 TypeError", () => {
expect(() => (KNOWN_EVENTS as unknown as string[]).push("evil")).toThrow(TypeError); // 正确:冻结
expect(() => KNOWN_EVENTS_BUGGY_NOFREEZE.push("evil")).not.toThrow(); // 变体:未冻结可改
expect(KNOWN_EVENTS_BUGGY_NOFREEZE).toContain("evil");
// 杀伤验证:buggy 副本跑真实断言(push 抛 TypeError)必 FAIL
expect(() => expect(() => KNOWN_EVENTS_BUGGY_NOFREEZE.push("evil2")).toThrow(TypeError)).toThrow();
// 杀它的测试:⑦ 不变式「深冻结:push 抛 TypeError」
});
it("真实代码无植入 bug:全方法论断言均成立(all green 前提)", () => {
// 抽样确认真实副本与真实 bus 行为一致
const bus = new PbaEventBus();
let got = false;
bus.on("build:done", () => (got = true), "agent");
bus.emit("build:done", null, "agentX");
expect(got).toBe(false); // = scopeReceivesReal("agent","agentX")
expect(scopeReceivesReal("agent", "agentX")).toBe(false);
});
});
// ============================================================================
// ⑦ 元蜕变/不变式 —— 跨变换保持的性质
// ============================================================================
describe("⑦ 元蜕变/不变式 —— 跨变换保持的性质", () => {
it("不变式:global 监听收一切(任意 scoped emit)", () => {
const bus = new PbaEventBus();
let n = 0;
bus.on("build:done", () => n++); // global
bus.emit("build:done", null, "agent");
bus.emit("build:done", null, "agent.sub.deep");
bus.emit("build:done", null); // global emit
expect(n).toBe(3);
});
it("不变式:global emit 不下渗到任何 scoped 监听(fail-closed 单向冒泡)", () => {
const bus = new PbaEventBus();
let n = 0;
bus.on("build:done", () => n++, "agent");
bus.on("build:done", () => n++, "agent.sub");
bus.on("build:done", () => n++, "other");
bus.emit("build:done", null); // global emit
expect(n).toBe(0);
});
it("元蜕变:广播一次到 N 监听 ≡ 逐个 emit 各收一次(计数等价)", () => {
const bus = new PbaEventBus();
const a = recorder();
const b = recorder();
const c = recorder();
bus.on("build:done", a.listener);
bus.on("build:done", b.listener);
bus.on("build:done", c.listener);
bus.emit("build:done", "p"); // 一次广播
expect(a.seen).toEqual(["p"]);
expect(b.seen).toEqual(["p"]);
expect(c.seen).toEqual(["p"]);
});
it("元蜕变:append 两次(两监听)后单次 emit ≡ 两次单监听 emit 的并集(序保持)", () => {
// 变换 A:注册 a,b 后 emit 一次
const busA = new PbaEventBus();
const logA: string[] = [];
busA.on("build:done", () => logA.push("a"));
busA.on("build:done", () => logA.push("b"));
busA.emit("build:done", null);
// 变换 B:分别注册单监听各 emit 一次,拼接
const logB: string[] = [];
const busB1 = new PbaEventBus();
busB1.on("build:done", () => logB.push("a"));
busB1.emit("build:done", null);
const busB2 = new PbaEventBus();
busB2.on("build:done", () => logB.push("b"));
busB2.emit("build:done", null);
expect(logA).toEqual(logB); // 两种变换等价
});
it("不变式:KNOWN_EVENTS 深冻结——push/改写均抛 TypeError", () => {
expect(() => (KNOWN_EVENTS as unknown as string[]).push("x")).toThrow(TypeError);
expect(() => {
(KNOWN_EVENTS as unknown as unknown[])[0] = "evil";
}).toThrow(TypeError);
expect(() => Object.defineProperty(KNOWN_EVENTS, "length", { value: 99 })).toThrow();
});
it("不变式:KNOWN_EVENTS 8 成员齐备且有序", () => {
expect(KNOWN_EVENTS).toEqual([
"verify:passed",
"build:done",
"boardlink:connect",
"glm:empty-output",
"xcompile:done",
"pdf-reader:page",
"debugger:attach",
"length-recovery:recovered",
]);
});
it("单调 deny:scope 匹配是纯函数——同 (L,E) 多次 emit 结果恒定", () => {
const bus = new PbaEventBus();
let count = 0;
bus.on("build:done", () => count++, "agent.sub");
for (let i = 0; i < 5; i++) bus.emit("build:done", null, "agent");
expect(count).toBe(0); // 后代监听恒不收父 emit
for (let i = 0; i < 5; i++) bus.emit("build:done", null, "agent.sub.deep");
expect(count).toBe(5); // 祖先恒收
});
it("waterfall 不调 next=短路(下游恒不跑)——单调性", () => {
const bus = new PbaEventBus();
let downstream = 0;
bus.on("build:done", () => { /* 短路 */ });
bus.on("build:done", () => downstream++);
for (let i = 0; i < 10; i++) bus.waterfall("build:done", null);
expect(downstream).toBe(0);
});
it("emit fail-soft 不变式:单监听抛错不阻断其余 + emitter 转发", () => {
const spy = spyEmitter();
const bus = new PbaEventBus({ emitter: spy });
const order: string[] = [];
bus.on("build:done", () => { order.push("a"); throw new Error("boom"); });
bus.on("build:done", () => order.push("b"));
expect(() => bus.emit("build:done", null)).not.toThrow();
expect(order).toEqual(["a", "b"]);
expect(spy.calls.length).toBe(1);
});
it("emitter 转发解耦:emitter 抛错不阻断 bus 监听", () => {
const throwing: PbaEmitter = { on: () => () => {}, emit: () => { throw new Error("x"); } };
const bus = new PbaEventBus({ emitter: throwing });
const { listener, seen } = recorder();
bus.on("build:done", listener);
expect(() => bus.emit("build:done", 1)).not.toThrow();
expect(seen).toEqual([1]);
});
it("emit 同步转发 (event, args) 到 emitter(outbound 薄封装)", () => {
const spy = spyEmitter();
const bus = new PbaEventBus({ emitter: spy });
bus.emit("build:done", { ok: true });
bus.emit("verify:passed", 42, "agent");
expect(spy.calls).toEqual([
{ event: "build:done", data: { ok: true } },
{ event: "verify:passed", data: 42 },
]);
});
it("waterfall 不向 emitter 转发(链是请求语义,非广播)", () => {
const spy = spyEmitter();
const bus = new PbaEventBus({ emitter: spy });
bus.on("build:done", (_a, next) => next());
bus.waterfall("build:done", null);
expect(spy.calls.length).toBe(0);
});
});

1053
tests/pba-session.test.ts Normal file

File diff suppressed because it is too large Load Diff

1481
tests/profiles.test.ts Normal file

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,243 @@
/**
* @module system-integration
*
* 系统级集成测试 —— T06–T17 落地后的跨模块闭环验证。
*
* 不是单模块单测(那些各模块自己有 1400+ 测试),而是验证模块间组合的【真实接线】:
* ① 事件溯源闭环:PbaSession.append → deriveMessages 投影 → assertModelVisibleLogged
* ② compaction 接 PbaSession:i2cdump 大输出 prune → spill 句柄 → recall
* ③ typed event bus:waterfall 链委托 + ScopeKey 隔离(子 scope 事件不串主)
* ④ 能力接缝:BoardLinkRegistry/FlashRegistry resolve fail-closed + provider 装配
* ⑤ 闭环 checkpoint:CheckpointRecorder.record → rebuild 从 log 重建
* ⑥ 上下文注入:inject(不唤醒)vs steer(换板唤醒)语义区分
* ⑦ 工作流:parallel(并发 barrier)+ pipeline(串行 stage 抛错落 null)
* ⑧ 审批 fail-closed:无人值守 auto-deny
* ⑨ provider registry:buildProviderConfig 产出 glm-5.2 配置(key 占位)
* ⑩ profile 分层:resolveProfile 共享 base + 叠差异
*
* 密钥铁律:所有 key 断言为 ${DROBOTICS_LLM_KEY} 占位,绝不出现真 key。
*/
import { describe, it, expect } from "vitest";
import { PbaSession } from "../src/core/pba-session.js";
import { PbaEventBus } from "../src/core/pba-event-bus.js";
import { pruneToolResult } from "../src/compaction/tool-result-pruner.js";
import { SpillStore } from "../src/compaction/spill.js";
import { BoardLinkRegistry, RDK_X5_SSH_PROVIDER, RDK_S100_SERIAL_PROVIDER, LOCAL_PROVIDER } from "../src/capabilities/board-link/index.js";
import { FlashRegistry, DD_PROVIDER, FASTBOOT_PROVIDER } from "../src/capabilities/flash/index.js";
import { CheckpointRecorder } from "../src/core/checkpoint-state.js";
import { ContextInjector } from "../src/core/context-injector.js";
import { parallel, pipeline } from "../src/capabilities/workflow/index.js";
import { ApprovalGate } from "../src/capabilities/approval.js";
import { ProviderRegistry, buildProviderConfig, DEFAULT_GLM_DESCRIPTOR } from "../src/core/provider-registry.js";
import { resolveProfile, BASE_PROFILE, REPAIR_DIAGNOSIS_PROFILE, EMBEDDED_DEV_PROFILE } from "../src/profiles/index.js";
import type { BoardSpec } from "../src/shared/types.js";
// 工具:最小 appendEntry 收集器(注入 PbaSession,替代 pi 运行时)
function makeCollector() {
const entries: Array<{ type: string; data: unknown }> = [];
return {
appendEntry: (type: string, data: unknown) => entries.push({ type, data }),
entries,
};
}
describe("system integration — T06–T17 跨模块闭环", () => {
it("① PbaSession 事件溯源:append → deriveMessages 投影 → logged 不变量", () => {
const col = makeCollector();
const sess = new PbaSession({ appendEntry: col.appendEntry });
sess.append({ type: "user-message", data: { content: "读 0x40020000" } });
sess.append({ type: "assistant-message", data: { content: "ok" } });
const msgs = sess.deriveMessages();
expect(Array.isArray(msgs)).toBe(true);
expect(msgs.length).toBeGreaterThan(0);
// 第二次 derive 命中增量缓存(不抛、结果一致)
expect(sess.deriveMessages()).toEqual(msgs);
// logged 不变量:投影里出现的 type 都在 log 里 append 过 → 不抛
expect(() => sess.assertModelVisibleLogged(["user-message", "assistant-message"])).not.toThrow();
// 伪造:声称投影里有但实际没 append 的 type → 抛
expect(() => sess.assertModelVisibleLogged(["verify-record"])).toThrow();
});
it("② compaction 接 PbaSession:i2cdump 大输出 prune 寄存器地址不丢 + spill recall", () => {
const i2cdump = [
" 0 1 2 3 4 5 6 7 8 9 a b c d e f",
"00: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00",
"10: 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10",
"20: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff",
].join("\n");
const pruned = pruneToolResult(i2cdump, { tool: "i2cdump", maxLines: 2 });
// 寄存器地址行(0xXX:)保留
expect(pruned.pruned).toMatch(/10:|20:/);
expect(pruned.dropped).toBeGreaterThan(0);
// spill 句柄 → recall 取回
const store = new SpillStore();
const loc = store.spill("datasheet-page-42", { reg: "0x40020000", desc: "GPIO_CTRL" });
expect(store.has(loc)).toBe(true);
const recalled = store.recall(loc);
expect(recalled).toEqual({ reg: "0x40020000", desc: "GPIO_CTRL" });
});
it("③ PbaEventBus:waterfall 链委托 + ScopeKey 隔离(子 scope 事件不串主)", () => {
const bus = new PbaEventBus();
const order: string[] = [];
bus.on("boardlink:connect", (_args, next) => {
order.push("global-1");
next();
});
bus.on("boardlink:connect", () => {
order.push("global-2-terminal");
});
bus.waterfall("boardlink:connect", { board: "x5" });
// 链顺序:global-1 调 next → global-2-terminal
expect(order).toEqual(["global-1", "global-2-terminal"]);
// scope 隔离:子 scope 注册的监听不响应父 scope 的事件(子不串父)
const subScope = "subagent:child-1";
const seen: string[] = [];
bus.on("verify:passed", () => seen.push("child"), subScope);
// 父 scope(无 scope / 祖先)发事件 → 子 scope 监听不应被触发(单向冒泡:子→父,非父→子)
bus.emit("verify:passed", { ok: true });
expect(seen).toEqual([]);
// 子 scope 自己发事件 → 子监听收(+ 冒泡到父,但这里只断言子收到)
bus.emit("verify:passed", { ok: true }, subScope);
expect(seen).toEqual(["child"]);
});
it("④ 能力接缝:BoardLinkRegistry + FlashRegistry resolve fail-closed + provider 装配", () => {
const bl = new BoardLinkRegistry();
bl.register(RDK_X5_SSH_PROVIDER);
bl.register(RDK_S100_SERIAL_PROVIDER);
expect(bl.list().length).toBe(2);
// register LOCAL → 3(三 provider 各一;按 id 去重不重复)
const dispose = bl.register(LOCAL_PROVIDER);
expect(bl.list().length).toBe(3);
// disposer 后回到 before(2)
dispose();
expect(bl.list().length).toBe(2);
const x5: BoardSpec = { id: "x5", name: "RDK X5", link: "ssh", address: "robot@10.0.0.1", fingerprint: "fp" };
const resolved = bl.resolve(x5);
expect(resolved.id).toBeTruthy();
expect(resolved.linkType).toBe("ssh");
const fl = new FlashRegistry();
fl.register(DD_PROVIDER);
fl.register(FASTBOOT_PROVIDER);
expect(fl.resolve("dd")).toBeDefined();
// 未注册 method(dfu 没装)→ fail-closed 抛错
expect(() => fl.resolve("dfu")).toThrow();
});
it("⑤ CheckpointRecorder:record(look-ahead 推进)→ rebuild 从 log 重建", () => {
const col = makeCollector();
const rec = new CheckpointRecorder({ append: (e) => col.appendEntry(e.type, e.data) });
rec.record("edit", true, 1000);
rec.record("compile", true, 2000);
rec.record("flash", true, 3000);
const cur = rec.current();
// look-ahead 语义:flash 通过后推进到下一 pending 步 verify(stepPassed=false)
expect(cur.currentStep).toBe("verify");
expect(cur.stepPassed).toBe(false);
expect(cur.history.length).toBe(3);
// 从 log 重建等价
const rebuilt = rec.rebuild(col.entries);
expect(rebuilt.currentStep).toBe("verify");
expect(rebuilt.history.length).toBe(3);
// 跑完全程到 done passed → 终态 stepPassed=true(完成态)
rec.record("verify", true, 4000);
rec.record("check", true, 5000);
rec.record("done", true, 6000);
expect(rec.current().currentStep).toBe("done");
expect(rec.current().stepPassed).toBe(true);
});
it("⑥ ContextInjector:inject(不唤醒)vs steer(换板唤醒)语义区分", () => {
const inj = new ContextInjector();
const a = inj.inject("寄存器表 next-step 不唤醒");
expect(a.nextStep).toBe(true);
expect(a.nextTurn).toBe(false);
const s = inj.steer("换板到 S100", "s100-board");
expect(s.boardId).toBe("s100-board");
expect(s.nextStep).toBe(true);
const f = inj.followup("新任务");
expect(f.nextTurn).toBe(true);
// 最新 snapshot 取代更早
const act = inj.deriveActiveContext();
expect(act).toBeDefined();
});
it("⑦ workflow:parallel(并发 barrier)+ pipeline(串行 stage 抛错落 null)", async () => {
const results: number[] = [];
const out = await parallel([
async () => { results.push(1); return "a"; },
async () => { results.push(2); return "b"; },
async () => { results.push(3); return "c"; },
]);
expect(out).toEqual(["a", "b", "c"]);
expect(results.length).toBe(3);
// pipeline 串行:stage2 抛错 → 该 item 落 null,其它不受影响
// stage 签名:(prev, item, i);stage1 的 prev 为 undefined → 用 item
const pip = await pipeline(
[1, 2, 3],
async (_prev, item: number) => item * 10,
async (prev) => { const n = prev as number; return n === 20 ? throwErr() : n + 1; },
);
expect(pip[0]).toBe(11); // 1*10=10 → 11
expect(pip[1]).toBeNull(); // 2*10=20 → 抛错落 null
expect(pip[2]).toBe(31); // 3*10=30 → 31
});
it("⑧ ApprovalGate fail-closed:无人值守 auto-deny", async () => {
const gate = new ApprovalGate({ mode: "auto-deny" });
const r = await gate.request({ action: "flash /dev/mmcblk0", risk: "high" });
expect(r.decision).toBe("deny");
// interactive 模式无 approver → fail-closed deny
gate.setMode("interactive");
const r2 = await gate.request({ action: "rm -rf", risk: "high", timeoutMs: 100 });
expect(r2.decision).toBe("deny");
});
it("⑨ ProviderRegistry:buildProviderConfig 产出 glm-5.2 配置(key 占位)", () => {
const reg = new ProviderRegistry();
reg.register(DEFAULT_GLM_DESCRIPTOR);
const desc = reg.resolve("glm-5.2");
expect(desc).toBeDefined();
const { name, config } = buildProviderConfig(desc);
expect(name).toBeTruthy();
// 密钥铁律:key 必须是 ${DROBOTICS_LLM_KEY} 占位,绝不出现 sk- 明文
const keyStr = JSON.stringify(config);
expect(keyStr).toContain("${DROBOTICS_LLM_KEY}");
expect(keyStr).not.toMatch(/sk-nAm/i);
expect(/sk-[A-Za-z0-9]{20,}/.test(keyStr)).toBe(false);
});
it("⑩ profile 分层:两 profile 共享 base + 各叠差异", () => {
expect(BASE_PROFILE.extensions.length).toBeGreaterThan(0);
// 维修诊断有 pdf-reader/datasheet-rag;嵌入式开发有 cross-compile/flash
const repair = REPAIR_DIAGNOSIS_PROFILE.extensions as readonly string[];
const emb = EMBEDDED_DEV_PROFILE.extensions as readonly string[];
expect(repair.some((e) => e.includes("pdf") || e.includes("datasheet"))).toBe(true);
expect(emb.some((e) => e.includes("cross-compile") || e.includes("flash"))).toBe(true);
// resolveProfile 未知 id fail-closed
expect(() => resolveProfile("nonexistent-profile")).toThrow();
});
});
function throwErr(): never {
throw new Error("boom");
}

View File

@ -0,0 +1,749 @@
/**
* @module type-drift-check.test
*
* T11 类型镜像漂移检测 —— 完整测试套件(多方法论)。
*
* 被测对象:scripts/type-drift-check.ts 的命名导出
* - extractErrorPath(line): string | null 纯解析(一行 tsc 输出 → 路径)
* - checkTypeDrift(opts): TypeDriftResult 主入口(分类 + fail-closed)
* - defaultRunTsc: TscRunner 默认 tsc 执行器(spawnSync 包装)
* - 类型契约 TscResult / TypeDriftResult / TscRunner
*
* 依赖注入:runTsc 可注入;defaultRunTsc 的 spawnSync 用 vi.mock 控制。
* 无 pi 运行时 / 无硬件 / 无网络 —— 纯逻辑 + mock。
*
* 多方法论(每个 describe 标注):
* 1. 等价类划分 + 边界值分析 (extractErrorPath / checkTypeDrift 边界)
* 2. 决策表 (分类 + fail-closed 全分支组合)
* 3. 状态转换 (drift 状态空间:有效/迁移/不可达/重入)
* 4. 对抗 / fuzz (畸形输入:null/undefined/NaN/巨大/循环引用/并发重入/负值)
* 5. 元蜕变 / 不变式 (确定性、append 等价、单调 deny、短路优先、fail-closed)
* 6. 变异测试 (4 个 seeded bug,每个被 killer 杀死;真实代码全过)
*/
import { describe, it, expect, vi, beforeEach } from "vitest";
// defaultRunTsc 依赖 spawnSync,整体 mock node:child_process(hoisted)
vi.mock("node:child_process", () => ({ spawnSync: vi.fn() }));
import { spawnSync } from "node:child_process";
import {
checkTypeDrift,
extractErrorPath,
defaultRunTsc,
} from "../scripts/type-drift-check.js";
import type { TscResult, TscRunner, TypeDriftResult } from "../scripts/type-drift-check.js";
// ============================================================================
// 工具:构造 TscRunner
// ============================================================================
function runner(r: TscResult): TscRunner {
return () => r;
}
const ERR_LINE_PRETTY = (path: string, msg = "Type mismatch") =>
`${path}:10:3 - error TS2322: ${msg}`;
const ERR_LINE_PLAIN = (path: string, msg = "Type mismatch") =>
`${path}(23,5): error TS2322: ${msg}`;
// ============================================================================
// 方法论 1:等价类划分 + 边界值分析 —— extractErrorPath
// ============================================================================
describe("等价类划分 + 边界值分析:extractErrorPath", () => {
// 有效类 A:非 pretty 报错行
describe("有效类·非 pretty 报错行", () => {
it.each([
["src/extensions/hardware-state.ts(23,5): error TS2322: Type mismatch", "src/extensions/hardware-state.ts"],
["src/types/pi.d.ts(1,1): error TS2307: Cannot find module", "src/types/pi.d.ts"],
// 边界:极短路径
["a.ts(1,1): error TS1: x", "a.ts"],
// pi 内部路径(非 pretty)
["../pi/packages/agent/src/index.ts(42,8): error TS2307: Cannot find module", "../pi/packages/agent/src/index.ts"],
])("«%s» → «%s»", (line, expected) => {
expect(extractErrorPath(line)).toBe(expected);
});
});
// 有效类 B:pretty 报错行
describe("有效类·pretty 报错行", () => {
it.each([
["src/types/pi.d.ts:10:3 - error TS2322: Type mismatch", "src/types/pi.d.ts"],
["../pi/packages/ai/src/foo.ts:5:1 - error TS2307: Cannot find name", "../pi/packages/ai/src/foo.ts"],
// 边界:行号/列号到达大数
["src/big.ts:999999:1 - error TS9999: msg", "src/big.ts"],
])("«%s» → «%s»", (line, expected) => {
expect(extractErrorPath(line)).toBe(expected);
});
});
// 无效类:非报错行 → null
describe("无效类·非报错行 → null", () => {
it.each([
["Found 3 errors in 2 files.", null], // 摘要行
["", null], // 空串
[" ", null], // 空白行
["src/foo.ts(23,5): warning TS0: something", null], // 警告非 error
["context: src/foo.ts:23:5", null], // 上下文行无 error 标记
["error: something", null], // 有 error 字样但无 TSxxxx:
["TS2322: foo", null], // 有错误码无 path 格式
])("«%s» → %s", (line, expected) => {
expect(extractErrorPath(line)).toBe(expected);
});
});
// 边界值:off-by-one / 最小 / 单元素
describe("边界值", () => {
it("最小 pretty 报错行(路径 1 字符 + 最小行列)", () => {
expect(extractErrorPath("a:1:1 - error TS1: x")).toBe("a");
});
it("最小 非 pretty 报错行", () => {
expect(extractErrorPath("a(1,1): error TS1: x")).toBe("a");
});
it("路径含空格与 unicode(Unix 路径无冒号,首段仍正确截取)", () => {
expect(extractErrorPath("src/中文 路径/foo.ts(1,2): error TS2322: x")).toBe(
"src/中文 路径/foo.ts",
);
});
it("pretty 行后紧跟多段冒号(非贪婪不误截)", () => {
// msg 里的冒号不应被吃进路径
expect(extractErrorPath("src/x.ts:1:2 - error TS2322: a: b: c")).toBe("src/x.ts");
});
it("error 与 TS 间多空格仍命中 marker", () => {
expect(extractErrorPath("src/x.ts(1,1): error TS2322: msg")).toBe("src/x.ts");
});
});
});
// ============================================================================
// 方法论 2:决策表 —— checkTypeDrift 分类 + fail-closed 全分支
// ============================================================================
describe("决策表:checkTypeDrift 分类 + fail-closed", () => {
// 决策表列:exitCode / src 报错 / packages 报错 / 其它路径报错 / 可解析报错数
// → driftDetected / pbaErrors.length / piInternalErrors.length
it.each([
// 1. exit 0,无任何报错 → 无漂移
{ name: "D1 exit0 无报错", exit: 0, src: "", pkg: "", other: "", expDrift: false, expPba: 0, expPi: 0 },
// 2. exit 1,仅 src 报错 → 漂移
{ name: "D2 仅 src 报错", exit: 1, src: ERR_LINE_PLAIN("src/a.ts"), pkg: "", other: "", expDrift: true, expPba: 1, expPi: 0 },
// 3. exit 1,仅 packages 报错 → 无漂移
{ name: "D3 仅 packages 报错", exit: 1, src: "", pkg: ERR_LINE_PLAIN("../pi/packages/agent/x.ts"), other: "", expDrift: false, expPba: 0, expPi: 1 },
// 4. exit 1,src + packages 混合 → 漂移(src 收录)
{ name: "D4 src+packages 混合", exit: 1, src: ERR_LINE_PLAIN("src/a.ts"), pkg: ERR_LINE_PLAIN("../pi/packages/b.ts"), other: "", expDrift: true, expPba: 1, expPi: 1 },
// 5. exit 1,仅其它路径(scripts/)→ fail-closed 归入 pba
{ name: "D5 仅其它路径→pba", exit: 1, src: "", pkg: "", other: ERR_LINE_PLAIN("scripts/x.ts"), expDrift: true, expPba: 1, expPi: 0 },
// 6. exit 2,tsc 崩溃无可解析报错 → fail-closed
{ name: "D6 tsc 崩溃 fail-closed", exit: 2, src: "", pkg: "", other: "", expDrift: true, expPba: 1, expPi: 0 },
// 7. exit 1,无可解析报错(tsconfig 缺失场景)→ fail-closed
{ name: "D7 exit1 无可解析→fail-closed", exit: 1, src: "", pkg: "", other: "", expDrift: true, expPba: 1, expPi: 0 },
// 8. exit 0 但 stdout 撒谎含 src 报错 → 分类不依赖 exitCode,仍检出
{ name: "D8 exit0 但含 src 报错", exit: 0, src: ERR_LINE_PLAIN("src/lie.ts"), pkg: "", other: "", expDrift: true, expPba: 1, expPi: 0 },
// 9. exit 0 + 无报错 + 崩溃 stderr → 不触发 fail-closed(exit 0 = 无漂移)
{ name: "D9 exit0+stderr 不 fail-closed", exit: 0, src: "", pkg: "", other: "", expDrift: false, expPba: 0, expPi: 0 },
])(
"$name → drift=$expDrift pba=$expPba pi=$expPi",
({ exit, src, pkg, other, expDrift, expPba, expPi }) => {
const stdout = [src, pkg, other].filter(Boolean).join("\n");
const stderr = exit !== 0 && !src && !pkg && !other ? "npx: command not found" : "";
const r = checkTypeDrift({
runTsc: runner({ exitCode: exit, stdout, stderr }),
});
expect(r.driftDetected).toBe(expDrift);
expect(r.pbaErrors).toHaveLength(expPba);
expect(r.piInternalErrors).toHaveLength(expPi);
},
);
it("fail-closed 兜底信息含退出码与原始输出", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: 2, stdout: "", stderr: "npx: command not found" }),
});
expect(r.pbaErrors[0]).toContain("exited 2");
expect(r.pbaErrors[0]).toContain("npx: command not found");
});
it("fail-closed 优先取 stderr,stderr 空则取 stdout,皆空则 (no output)", () => {
const onlyStdout = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: "boom-stdout", stderr: "" }),
});
expect(onlyStdout.pbaErrors[0]).toContain("boom-stdout");
const empty = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: "", stderr: "" }),
});
expect(empty.pbaErrors[0]).toContain("(no output)");
});
});
// ============================================================================
// 方法论 1 续:边界值分析 —— checkTypeDrift(单元素/空/args/默认值/自定义)
// ============================================================================
describe("边界值分析:checkTypeDrift(off-by-one / 空 / 单 / 默认 / 自定义)", () => {
it("空:exit 0 + 空输出 → 空数组(非 undefined)", () => {
const r = checkTypeDrift({ runTsc: runner({ exitCode: 0, stdout: "", stderr: "" }) });
expect(r.pbaErrors).toEqual([]);
expect(r.piInternalErrors).toEqual([]);
expect(Array.isArray(r.pbaErrors)).toBe(true);
});
it("单元素:仅 1 条 src 报错 → pbaErrors 长度恰为 1", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/a.ts"), stderr: "" }),
});
expect(r.pbaErrors).toHaveLength(1);
});
it("max:100 条 src + 100 条 packages 报错 → 各 100,顺序保持", () => {
const srcLines = Array.from({ length: 100 }, (_, i) => ERR_LINE_PLAIN(`src/a${i}.ts`));
const pkgLines = Array.from({ length: 100 }, (_, i) => ERR_LINE_PLAIN(`../pi/packages/p${i}.ts`));
// src 全部先于 packages(stdout 内顺序)
const r = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: [...srcLines, ...pkgLines].join("\n"), stderr: "" }),
});
expect(r.pbaErrors).toHaveLength(100);
expect(r.piInternalErrors).toHaveLength(100);
// 顺序保持:首条 src = a0
expect(r.pbaErrors[0]).toContain("src/a0.ts");
// 末条 packages = p99
expect(r.piInternalErrors[99]).toContain("packages/p99.ts");
});
it("args:默认 tsconfigPath → runTsc 收到 [\"-p\",\"tsconfig.realpi.json\",\"--noEmit\"]", () => {
const spy = vi.fn<TscRunner>();
spy.mockReturnValue({ exitCode: 0, stdout: "", stderr: "" });
checkTypeDrift({ runTsc: spy });
expect(spy).toHaveBeenCalledWith(["-p", "tsconfig.realpi.json", "--noEmit"]);
});
it("args:自定义 tsconfigPath → 透传", () => {
const spy = vi.fn<TscRunner>();
spy.mockReturnValue({ exitCode: 0, stdout: "", stderr: "" });
checkTypeDrift({ tsconfigPath: "custom.json", runTsc: spy });
expect(spy).toHaveBeenCalledWith(["-p", "custom.json", "--noEmit"]);
});
it("注入优先级:注入的 runTsc 必胜出,defaultRunTsc 不被触达", () => {
// 不注入 runTsc 会走 defaultRunTsc(真 spawnSync npx tsc)——避免真执行
const spy = vi.fn<TscRunner>();
spy.mockReturnValue({ exitCode: 0, stdout: "", stderr: "" });
const r = checkTypeDrift({ runTsc: spy });
expect(spy).toHaveBeenCalledTimes(1);
expect(r.driftDetected).toBe(false);
});
it("自定义 pbaSrcPattern:覆盖分类边界", () => {
// 只认 lib/ 开头为 pba,src/ 报错落为“其它”→ fail-closed 归 pba
const r = checkTypeDrift({
pbaSrcPattern: /^lib\//,
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/a.ts"), stderr: "" }),
});
expect(r.pbaErrors).toHaveLength(1); // src/ 不匹配 lib → 其它 → pba
expect(r.piInternalErrors).toHaveLength(0);
});
});
// ============================================================================
// 方法论 3:状态转换 —— drift 状态空间(有效状态/迁移/不可达/重入)
// ============================================================================
describe("状态转换:drift 状态空间", () => {
// 状态机:checkTypeDrift 是无状态纯函数,但其返回值定义一个状态空间:
// S0 NoDrift : drift=false ∧ pba=0
// S1 PiOnly : drift=false ∧ pba=0 ∧ pi>0
// S2 Drift : drift=true ∧ pba>0
// S3 FailClosed: drift=true ∧ pba=1 ∧ 行含 "exited"
// 不可达:drift=true ∧ pba=0 / drift=false ∧ pba>0
it("S0 NoDrift:exit0 无报错", () => {
const r = checkTypeDrift({ runTsc: runner({ exitCode: 0, stdout: "", stderr: "" }) });
expect(r).toMatchObject({ driftDetected: false, pbaErrors: [], piInternalErrors: [] });
});
it("S1 PiOnly:仅 packages 报错,无漂移", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("../pi/packages/x.ts"), stderr: "" }),
});
expect(r.driftDetected).toBe(false);
expect(r.piInternalErrors.length).toBeGreaterThan(0);
});
it("S2 Drift:src 报错触发漂移", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/x.ts"), stderr: "" }),
});
expect(r.driftDetected).toBe(true);
expect(r.pbaErrors.length).toBeGreaterThan(0);
});
it("S3 FailClosed:tsc 崩溃 → 状态含 exited 标记", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: 2, stdout: "", stderr: "boom" }),
});
expect(r.driftDetected).toBe(true);
expect(r.pbaErrors[0]).toMatch(/exited/);
});
it("迁移·单调:PiOnly 叠加 src 报错 → Drift(不可回退到 NoDrift)", () => {
// 先 PiOnly
const before = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("../pi/packages/x.ts"), stderr: "" }),
});
expect(before.driftDetected).toBe(false);
// 叠加 src 报错(状态迁移 PiOnly → Drift)
const after = checkTypeDrift({
runTsc: runner({
exitCode: 1,
stdout: `${ERR_LINE_PLAIN("../pi/packages/x.ts")}\n${ERR_LINE_PLAIN("src/y.ts")}`,
stderr: "",
}),
});
expect(after.driftDetected).toBe(true);
});
it("不可达状态:drift=true ∧ pbaErrors 为空 —— 全决策表样本校验", () => {
const samples: TscRunner[] = [
runner({ exitCode: 0, stdout: "", stderr: "" }),
runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/x.ts"), stderr: "" }),
runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("../pi/packages/x.ts"), stderr: "" }),
runner({ exitCode: 2, stdout: "", stderr: "crash" }),
];
for (const runTsc of samples) {
const r = checkTypeDrift({ runTsc });
// 不变式:driftDetected ⟺ pbaErrors.length > 0
expect(r.driftDetected, `drift=${r.driftDetected} pba=${r.pbaErrors.length}`).toBe(
r.pbaErrors.length > 0,
);
}
});
it("重入/幂等:同一 runTsc 连续调用两次 → 结果深相等(无状态泄漏)", () => {
const runTsc = runner({
exitCode: 1,
stdout: ERR_LINE_PRETTY("src/x.ts"),
stderr: "",
});
const r1 = checkTypeDrift({ runTsc });
const r2 = checkTypeDrift({ runTsc });
expect(r1).toEqual(r2);
});
});
// ============================================================================
// 方法论 4:对抗 / fuzz —— 畸形与滥用输入
// ============================================================================
describe("对抗 / fuzz:畸形与滥用输入", () => {
it("extractErrorPath(null) → 不抛、返回 null(非报错行)", () => {
// String(null)="null",不含 error TSxxxx: 标记
expect(extractErrorPath(null as unknown as string)).toBeNull();
});
it("extractErrorPath(undefined) → 不抛、返回 null", () => {
expect(extractErrorPath(undefined as unknown as string)).toBeNull();
});
it("extractErrorPath(NaN) → 不抛、返回 null", () => {
expect(extractErrorPath(NaN as unknown as string)).toBeNull();
});
it("extractErrorPath(数字) → 不抛、返回 null", () => {
expect(extractErrorPath(12345 as unknown as string)).toBeNull();
});
it("extractErrorPath(巨大字符串) → 不抛、正确截取路径", () => {
const huge = "src/big.ts(1,1): error TS2322: " + "x".repeat(1_000_000);
expect(extractErrorPath(huge)).toBe("src/big.ts");
});
it("extractErrorPath(循环引用对象) → 不抛、String()=「[object Object]」无 marker → null(安全不误分类)", () => {
// 普通循环对象的 toString() 返回 "[object Object]"(不抛),不含 marker → 判非报错行 → null
const circ: unknown = {};
(circ as Record<string, unknown>).self = circ;
expect(extractErrorPath(circ as unknown as string)).toBeNull();
});
it("extractErrorPath(toString 抛异常的对象) → 透传异常(不吞、不静默误分类)", () => {
// 对象 toString 抛 → String() 抛 → .test() 抛 → 透传;不返回假路径
const bomb = {
toString() {
throw new Error("toString exploded");
},
};
expect(() => extractErrorPath(bomb as unknown as string)).toThrow("toString exploded");
});
it("checkTypeDrift:runTsc 返回非字符串 stdout(数字)→ 不抛、按字符串归约", () => {
const r = checkTypeDrift({
// @ts-expect-error 故意畸形
runTsc: runner({ exitCode: 0, stdout: 12345, stderr: "" }),
});
expect(r.driftDetected).toBe(false);
});
it("checkTypeDrift:stdout 含 null 字节 → 不崩,仍按行解析", () => {
const r = checkTypeDrift({
runTsc: runner({
exitCode: 1,
stdout: `src/a.ts(1,1): error TS2322: bad\x00null`,
stderr: "",
}),
});
expect(r.driftDetected).toBe(true);
expect(r.pbaErrors[0]).toContain("src/a.ts");
});
it("checkTypeDrift:CRLF 行尾 → 仍正确解析(split 在 \\n)", () => {
const r = checkTypeDrift({
runTsc: runner({
exitCode: 1,
stdout: `src/a.ts(1,1): error TS2322: x\r\nsrc/b.ts(2,2): error TS2322: y\r\n`,
stderr: "",
}),
});
expect(r.pbaErrors).toHaveLength(2);
// CRLF 残留的 \r 应留在行尾(不影响路径提取)
expect(r.pbaErrors[0]).toContain("src/a.ts");
});
it("checkTypeDrift:负退出码 → !== 0 → fail-closed", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: -1, stdout: "", stderr: "spawn killed" }),
});
expect(r.driftDetected).toBe(true);
expect(r.pbaErrors[0]).toContain("exited -1");
});
it("checkTypeDrift:并发重入(两次交错调用)→ 结果互不污染", () => {
// 无模块级可变状态 → 交错安全。用两个不同 runTsc 模拟“并发”
const r1 = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/a.ts"), stderr: "" }),
});
const r2 = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("../pi/packages/b.ts"), stderr: "" }),
});
expect(r1.driftDetected).toBe(true);
expect(r2.driftDetected).toBe(false);
expect(r1.pbaErrors).toHaveLength(1);
expect(r2.piInternalErrors).toHaveLength(1);
});
it("checkTypeDrift:runTsc 抛异常 → 透传(不吞异常伪装无漂移)", () => {
const throwing: TscRunner = () => {
throw new Error("runner exploded");
};
expect(() => checkTypeDrift({ runTsc: throwing })).toThrow("runner exploded");
});
});
// ============================================================================
// 方法论 5:元蜕变 / 不变式 —— 跨变换保持的性质
// ============================================================================
describe("元蜕变 / 不变式:跨变换保持的性质", () => {
// 不变式 I1:driftDetected ⟺ pbaErrors.length > 0(已覆盖,此处显式断言为不变式)
it("I1 单调 deny:driftDetected 恒等于 pbaErrors 非空(多场景)", () => {
const cases: TscRunner[] = [
runner({ exitCode: 0, stdout: "", stderr: "" }),
runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/x.ts"), stderr: "" }),
runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("../pi/packages/x.ts"), stderr: "" }),
runner({ exitCode: 2, stdout: "", stderr: "crash" }),
runner({ exitCode: 1, stdout: `${ERR_LINE_PLAIN("src/x.ts")}\n${ERR_LINE_PLAIN("../pi/packages/y.ts")}`, stderr: "" }),
];
for (const runTsc of cases) {
const r = checkTypeDrift({ runTsc });
expect(r.driftDetected, `pba=${r.pbaErrors.length}`).toBe(r.pbaErrors.length > 0);
}
});
// 元蜕变 M1:append 等价 —— 输出拆到 stdout/stderr 两次 vs 合并到 stdout 一次,结果等价
it("M1 append 等价:stdout+stderr 拆分 vs 合并到 stdout → 同 pbaErrors/piInternal", () => {
const src = ERR_LINE_PLAIN("src/a.ts");
const pkg = ERR_LINE_PLAIN("../pi/packages/b.ts");
// 拆分:src 在 stdout,pkg 在 stderr
const split = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: src, stderr: pkg }),
});
// 合并:全部在 stdout(顺序 src 然后 pkg,与 join 行为一致:stdout 先 stderr 后)
const merged = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: `${src}\n${pkg}`, stderr: "" }),
});
expect(split.pbaErrors).toEqual(merged.pbaErrors);
expect(split.piInternalErrors).toEqual(merged.piInternalErrors);
expect(split.driftDetected).toBe(merged.driftDetected);
});
// 元蜕变 M2:replay 等价 —— 同输入跑两次结果完全相同(确定性)
it("M2 replay 等价:同 runTsc 两次 → 深相等", () => {
const runTsc = runner({
exitCode: 1,
stdout: `${ERR_LINE_PRETTY("src/a.ts")}\n${ERR_LINE_PLAIN("../pi/packages/b.ts")}`,
stderr: "warn",
});
expect(checkTypeDrift({ runTsc })).toEqual(checkTypeDrift({ runTsc }));
});
// 不变式 I2:短路优先 —— pbaSrcPattern 先于 PI_INTERNAL_PATTERN 判定
it("I2 短路优先:路径同时匹配 src/ 与 packages/ → 归 pba(先匹配先归)", () => {
// "src/packages/foo.ts" 同时匹配 ^src/ 与 packages/
const r = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/packages/foo.ts"), stderr: "" }),
});
expect(r.pbaErrors).toHaveLength(1);
expect(r.piInternalErrors).toHaveLength(0);
});
// 不变式 I3:fail-closed unusable = reject
it("I3 fail-closed:tsc 不可用(非零退出 + 无可解析报错)→ 必判漂移", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: 127, stdout: "", stderr: "command not found" }),
});
expect(r.driftDetected).toBe(true);
});
// 不变式 I4:分类独立于 exitCode(信任输出文本,不因 exitCode 门控)
it("I4 分类独立于 exitCode:exit0 含 src 报错仍检出;exit0 无报错不误报", () => {
const lying = checkTypeDrift({
runTsc: runner({ exitCode: 0, stdout: ERR_LINE_PLAIN("src/lie.ts"), stderr: "" }),
});
expect(lying.driftDetected).toBe(true);
const honest = checkTypeDrift({
runTsc: runner({ exitCode: 0, stdout: "", stderr: "" }),
});
expect(honest.driftDetected).toBe(false);
});
// 不变式 I5:结果字段为 readonly 快照(运行时至少保持数组 identity 一致)
it("I5 结果快照:返回值三字段类型符合契约且非 undefined", () => {
const r = checkTypeDrift({ runTsc: runner({ exitCode: 0, stdout: "", stderr: "" }) });
expect(typeof r.driftDetected).toBe("boolean");
expect(Array.isArray(r.pbaErrors)).toBe(true);
expect(Array.isArray(r.piInternalErrors)).toBe(true);
});
// 不变式 I6:pbaSrcPattern 默认锚定 ^src/(前缀匹配,非子串)
it("I6 默认 pbaSrcPattern 锚定 ^src/:my-src/x.ts 不匹配真 src 漂移路径", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("my-src/x.ts"), stderr: "" }),
});
// my-src/ 不匹配 ^src/ → 落为“其它”→ fail-closed 归 pba
expect(r.pbaErrors).toHaveLength(1);
// 与真 src/ 路径区分:真 src 应匹配默认 pattern
const real = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/x.ts"), stderr: "" }),
});
expect(real.pbaErrors).toHaveLength(1);
});
});
// ============================================================================
// 方法论 6:变异测试 —— 4 个 seeded bug,每个被 killer 杀死
// ============================================================================
describe("变异测试:seeded bug 与 killer", () => {
// 复制私有常量(mutant 副本需要它们)
const TSC_ERROR_MARKER = /error\s+TS\d+:/;
const TSC_ERROR_PATH_RE = /^(.+?)(?:\(\d+,\d+\)|:\d+:\d+)/;
const PI_INTERNAL_PATTERN = /packages\//;
const DEFAULT_TSCONFIG_PATH = "tsconfig.realpi.json";
const DEFAULT_PBA_SRC_PATTERN = /^src\//;
// --- Mutant M1:extractErrorPath 漏 marker 守卫 ---
// BUG: 删除 `if (!TSC_ERROR_MARKER.test(line)) return null;`
// → 非报错行但带路径形(如 warning/摘要)被误当路径返回
function extractErrorPath_M1(line: string): string | null {
// (BUG: marker guard removed)
const match = line.match(TSC_ERROR_PATH_RE);
return match ? match[1].trim() : null;
}
it("M1 真实代码:warning 行 → null(killer 通过)", () => {
expect(extractErrorPath("src/foo.ts(23,5): warning TS0: something")).toBeNull();
});
it("M1 变体被杀:mutant 对 warning 行返回路径 → killer(null) 失败", () => {
// 同输入下 mutant 偏离正确值,证明 killer(期望 null)能杀掉 M1
expect(extractErrorPath_M1("src/foo.ts(23,5): warning TS0: something")).toBe("src/foo.ts");
});
// --- Mutant M2:checkTypeDrift 删除 fail-closed 块 ---
// BUG: 去掉 `if (exitCode !== 0 && pba=0 && pi=0) push(raw)`
// → tsc 崩溃(非零退出 + 无可解析报错)静默判无漂移
function checkTypeDrift_M2(opts: {
tsconfigPath?: string;
runTsc?: TscRunner;
pbaSrcPattern?: RegExp;
}): TypeDriftResult {
const tsconfigPath = opts.tsconfigPath ?? DEFAULT_TSCONFIG_PATH;
const pbaSrcPattern = opts.pbaSrcPattern ?? DEFAULT_PBA_SRC_PATTERN;
const runTsc = opts.runTsc ?? (() => ({ exitCode: 0, stdout: "", stderr: "" }));
const args = ["-p", tsconfigPath, "--noEmit"];
const result = runTsc(args);
const output = [result.stdout, result.stderr].filter(Boolean).join("\n");
const lines = output.split("\n");
const pbaErrors: string[] = [];
const piInternalErrors: string[] = [];
for (const line of lines) {
if (!TSC_ERROR_MARKER.test(line)) continue;
const match = line.match(TSC_ERROR_PATH_RE);
const path = match ? match[1].trim() : null;
if (path === null) continue;
if (pbaSrcPattern.test(path)) pbaErrors.push(line);
else if (PI_INTERNAL_PATTERN.test(path)) piInternalErrors.push(line);
else pbaErrors.push(line);
}
// (BUG: fail-closed block removed)
return { driftDetected: pbaErrors.length > 0, pbaErrors, piInternalErrors };
}
it("M2 真实代码:tsc 崩溃 → 漂移=true(killer 通过)", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: 2, stdout: "", stderr: "npx: command not found" }),
});
expect(r.driftDetected).toBe(true);
expect(r.pbaErrors).toHaveLength(1);
});
it("M2 变体被杀:mutant 对崩溃静默判无漂移 → killer(true) 失败", () => {
const r = checkTypeDrift_M2({
runTsc: runner({ exitCode: 2, stdout: "", stderr: "npx: command not found" }),
});
expect(r.driftDetected).toBe(false); // mutant 的错误行为
expect(r.pbaErrors).toHaveLength(0);
});
// --- Mutant M3:checkTypeDrift 交换分类顺序(pi 先于 pba)---
// BUG: `if (PI_INTERNAL_PATTERN.test(path)) piInternal.push; else if (pbaSrcPattern...) pba.push`
// → 同时匹配 src/ 与 packages/ 的路径误归 piInternal
function checkTypeDrift_M3(opts: {
tsconfigPath?: string;
runTsc?: TscRunner;
pbaSrcPattern?: RegExp;
}): TypeDriftResult {
const pbaSrcPattern = opts.pbaSrcPattern ?? DEFAULT_PBA_SRC_PATTERN;
const runTsc = opts.runTsc ?? (() => ({ exitCode: 0, stdout: "", stderr: "" }));
const tsconfigPath = opts.tsconfigPath ?? DEFAULT_TSCONFIG_PATH;
const args = ["-p", tsconfigPath, "--noEmit"];
const result = runTsc(args);
const output = [result.stdout, result.stderr].filter(Boolean).join("\n");
const lines = output.split("\n");
const pbaErrors: string[] = [];
const piInternalErrors: string[] = [];
for (const line of lines) {
if (!TSC_ERROR_MARKER.test(line)) continue;
const match = line.match(TSC_ERROR_PATH_RE);
const path = match ? match[1].trim() : null;
if (path === null) continue;
// (BUG: pi pattern tested first → short-circuit reversed)
if (PI_INTERNAL_PATTERN.test(path)) piInternalErrors.push(line);
else if (pbaSrcPattern.test(path)) pbaErrors.push(line);
else pbaErrors.push(line);
}
if (result.exitCode !== 0 && pbaErrors.length === 0 && piInternalErrors.length === 0) {
const raw = result.stderr.trim() || result.stdout.trim() || "(no output)";
pbaErrors.push(`tsc exited ${result.exitCode} with no parseable errors: ${raw}`);
}
return { driftDetected: pbaErrors.length > 0, pbaErrors, piInternalErrors };
}
it("M3 真实代码:src/packages/foo.ts → pbaErrors(killer 通过)", () => {
const r = checkTypeDrift({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/packages/foo.ts"), stderr: "" }),
});
expect(r.pbaErrors).toHaveLength(1);
expect(r.piInternalErrors).toHaveLength(0);
});
it("M3 变体被杀:mutant 把同时匹配路径误归 piInternal → killer(pba=1) 失败", () => {
const r = checkTypeDrift_M3({
runTsc: runner({ exitCode: 1, stdout: ERR_LINE_PLAIN("src/packages/foo.ts"), stderr: "" }),
});
expect(r.pbaErrors).toHaveLength(0); // mutant 的错误行为
expect(r.piInternalErrors).toHaveLength(1);
});
// --- Mutant M4:DEFAULT_TSCONFIG_PATH 错默认值 ---
// BUG: 默认 tsconfig 路径 = "tsconfig.json"(非 "tsconfig.realpi.json")
// → 跑错 tsconfig,漏检真 pi 镜像漂移
function checkTypeDrift_M4(opts: {
runTsc?: TscRunner;
}): TypeDriftResult {
const tsconfigPath = "tsconfig.json"; // (BUG: wrong default)
const runTsc = opts.runTsc ?? (() => ({ exitCode: 0, stdout: "", stderr: "" }));
const args = ["-p", tsconfigPath, "--noEmit"];
const result = runTsc(args);
const output = [result.stdout, result.stderr].filter(Boolean).join("\n");
const lines = output.split("\n");
const pbaErrors: string[] = [];
const piInternalErrors: string[] = [];
for (const line of lines) {
if (!TSC_ERROR_MARKER.test(line)) continue;
const match = line.match(TSC_ERROR_PATH_RE);
const path = match ? match[1].trim() : null;
if (path === null) continue;
if (DEFAULT_PBA_SRC_PATTERN.test(path)) pbaErrors.push(line);
else if (PI_INTERNAL_PATTERN.test(path)) piInternalErrors.push(line);
else pbaErrors.push(line);
}
if (result.exitCode !== 0 && pbaErrors.length === 0 && piInternalErrors.length === 0) {
const raw = result.stderr.trim() || result.stdout.trim() || "(no output)";
pbaErrors.push(`tsc exited ${result.exitCode} with no parseable errors: ${raw}`);
}
return { driftDetected: pbaErrors.length > 0, pbaErrors, piInternalErrors };
}
it("M4 真实代码:默认 args 含 tsconfig.realpi.json(killer 通过)", () => {
const spy = vi.fn<TscRunner>();
spy.mockReturnValue({ exitCode: 0, stdout: "", stderr: "" });
checkTypeDrift({ runTsc: spy });
expect(spy).toHaveBeenCalledWith(["-p", "tsconfig.realpi.json", "--noEmit"]);
});
it("M4 变体被杀:mutant 默认 tsconfig.json → killer(realpi) 失败", () => {
const spy = vi.fn<TscRunner>();
spy.mockReturnValue({ exitCode: 0, stdout: "", stderr: "" });
checkTypeDrift_M4({ runTsc: spy });
expect(spy).toHaveBeenCalledWith(["-p", "tsconfig.json", "--noEmit"]);
});
});
// ============================================================================
// 补:defaultRunTsc —— spawnSync 包装的归一化逻辑(vi.mock 控制 spawnSync)
// ============================================================================
describe("defaultRunTsc:spawnSync 归一化(依赖注入 child_process)", () => {
const mockedSpawn = vi.mocked(spawnSync);
beforeEach(() => {
mockedSpawn.mockReset();
});
it("正常:status=0 → exitCode=0,stdout/stderr 透传", () => {
mockedSpawn.mockReturnValue({
status: 0,
stdout: "out",
stderr: "err",
} as never);
const r = defaultRunTsc(["-p", "x.json", "--noEmit"]);
expect(r.exitCode).toBe(0);
expect(r.stdout).toBe("out");
expect(r.stderr).toBe("err");
// 透传 npx tsc 前缀
expect(mockedSpawn).toHaveBeenCalledWith(
"npx",
["tsc", "-p", "x.json", "--noEmit"],
expect.objectContaining({ encoding: "utf8" }),
);
});
it("spawn 错误:status=null + error → exitCode=-1,stderr 取 error.message", () => {
mockedSpawn.mockReturnValue({
status: null,
stdout: "",
stderr: "",
error: new Error("boom-spawn"),
} as never);
const r = defaultRunTsc([]);
expect(r.exitCode).toBe(-1);
expect(r.stderr).toBe("boom-spawn");
});
it("spawn 错误但 stderr 非空:stderr 优先于 error.message", () => {
mockedSpawn.mockReturnValue({
status: null,
stdout: "",
stderr: "real-stderr",
error: new Error("ignored"),
} as never);
const r = defaultRunTsc([]);
expect(r.stderr).toBe("real-stderr");
});
it("stdout/stderr 为 undefined → 兜底空串", () => {
mockedSpawn.mockReturnValue({
status: 1,
stdout: undefined,
stderr: undefined,
} as never);
const r = defaultRunTsc([]);
expect(r.stdout).toBe("");
expect(r.stderr).toBe("");
expect(r.exitCode).toBe(1);
});
it("status=undefined → exitCode=-1(nullish 合并)", () => {
mockedSpawn.mockReturnValue({ status: undefined, stdout: "", stderr: "" } as never);
expect(defaultRunTsc([]).exitCode).toBe(-1);
});
it("status=0(假值边界):0 非空,exitCode=0", () => {
mockedSpawn.mockReturnValue({ status: 0, stdout: "", stderr: "" } as never);
expect(defaultRunTsc([]).exitCode).toBe(0);
});
});

1329
tests/workflow.test.ts Normal file

File diff suppressed because it is too large Load Diff

11
tsconfig.realpi.json Normal file
View File

@ -0,0 +1,11 @@
{
"extends": "./tsconfig.json",
"compilerOptions": {
"paths": {
"@earendil-works/pi-ai": ["../pi/packages/ai/src/index.ts"],
"@earendil-works/pi-coding-agent": ["../pi/packages/coding-agent/src/index.ts"],
"@earendil-works/pi-agent-core": ["../pi/packages/agent/src/index.ts"]
}
},
"include": ["src/**/*.ts", "scripts/**/*.ts"]
}