feat(v3): P1+P2 全落地 — T06–T17 + 系统集成测试
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:
parent
d671f174fe
commit
6d6a805d46
123
.github/workflows/ci.yml
vendored
Normal file
123
.github/workflows/ci.yml
vendored
Normal 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
4
.gitignore
vendored
@ -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
251
scripts/doc-sync.ts
Normal 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
197
scripts/e2e-snapshot.ts
Normal 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,
|
||||
};
|
||||
}
|
||||
448
scripts/t06-t17.workflow.mjs
Normal file
448
scripts/t06-t17.workflow.mjs
Normal 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
199
scripts/type-drift-check.ts
Normal 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,
|
||||
};
|
||||
}
|
||||
184
src/capabilities/approval.ts
Normal file
184
src/capabilities/approval.ts
Normal 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);
|
||||
}
|
||||
}
|
||||
}
|
||||
170
src/capabilities/board-link/index.ts
Normal file
170
src/capabilities/board-link/index.ts
Normal 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),
|
||||
]);
|
||||
41
src/capabilities/board-link/providers/local.ts
Normal file
41
src/capabilities/board-link/providers/local.ts
Normal 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);
|
||||
},
|
||||
};
|
||||
94
src/capabilities/board-link/providers/rdk-s100-serial.ts
Normal file
94
src/capabilities/board-link/providers/rdk-s100-serial.ts
Normal 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);
|
||||
},
|
||||
};
|
||||
131
src/capabilities/board-link/providers/rdk-x5-ssh.ts
Normal file
131
src/capabilities/board-link/providers/rdk-x5-ssh.ts
Normal 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);
|
||||
},
|
||||
};
|
||||
124
src/capabilities/board-link/types.ts
Normal file
124
src/capabilities/board-link/types.ts
Normal 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)}` };
|
||||
}
|
||||
}
|
||||
139
src/capabilities/credentials.ts
Normal file
139
src/capabilities/credentials.ts
Normal 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);
|
||||
}
|
||||
}
|
||||
167
src/capabilities/flash/index.ts
Normal file
167
src/capabilities/flash/index.ts
Normal 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),
|
||||
]);
|
||||
435
src/capabilities/flash/providers/dd.ts
Normal file
435
src/capabilities/flash/providers/dd.ts
Normal 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,
|
||||
};
|
||||
122
src/capabilities/flash/providers/dfu.ts
Normal file
122
src/capabilities/flash/providers/dfu.ts
Normal 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,
|
||||
};
|
||||
123
src/capabilities/flash/providers/fastboot.ts
Normal file
123
src/capabilities/flash/providers/fastboot.ts
Normal 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,
|
||||
};
|
||||
129
src/capabilities/flash/providers/openocd.ts
Normal file
129
src/capabilities/flash/providers/openocd.ts
Normal 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,
|
||||
};
|
||||
572
src/capabilities/flash/types.ts
Normal file
572
src/capabilities/flash/types.ts
Normal 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
85
src/capabilities/lsp.ts
Normal 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 无资源需释放
|
||||
}
|
||||
}
|
||||
184
src/capabilities/settings.ts
Normal file
184
src/capabilities/settings.ts
Normal 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 }));
|
||||
}
|
||||
}
|
||||
278
src/capabilities/subagent/index.ts
Normal file
278
src/capabilities/subagent/index.ts
Normal 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);
|
||||
}
|
||||
172
src/capabilities/workflow/index.ts
Normal file
172
src/capabilities/workflow/index.ts
Normal 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
178
src/compaction/spill.ts
Normal 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;
|
||||
}
|
||||
}
|
||||
159
src/compaction/summarizer.ts
Normal file
159
src/compaction/summarizer.ts
Normal 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,
|
||||
};
|
||||
}
|
||||
88
src/compaction/token-meter.ts
Normal file
88
src/compaction/token-meter.ts
Normal 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;
|
||||
}
|
||||
227
src/compaction/tool-result-pruner.ts
Normal file
227
src/compaction/tool-result-pruner.ts
Normal 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 };
|
||||
}
|
||||
284
src/core/checkpoint-state.ts
Normal file
284
src/core/checkpoint-state.ts
Normal 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;
|
||||
}
|
||||
}
|
||||
418
src/core/context-injector.ts
Normal file
418
src/core/context-injector.ts
Normal 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
393
src/core/pba-event-bus.ts
Normal 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
437
src/core/pba-session.ts
Normal 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;
|
||||
}
|
||||
}
|
||||
474
src/core/provider-registry.ts
Normal file
474
src/core/provider-registry.ts
Normal 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,
|
||||
]);
|
||||
42
src/index.ts
42
src/index.ts
@ -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
273
src/profiles/base.ts
Normal 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[] };
|
||||
}
|
||||
60
src/profiles/embedded-dev.ts
Normal file
60
src/profiles/embedded-dev.ts
Normal 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
77
src/profiles/index.ts
Normal 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];
|
||||
}
|
||||
44
src/profiles/repair-diagnosis.ts
Normal file
44
src/profiles/repair-diagnosis.ts
Normal 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;
|
||||
1320
tests/capabilities-misc.test.ts
Normal file
1320
tests/capabilities-misc.test.ts
Normal file
File diff suppressed because it is too large
Load Diff
2523
tests/capability-seams.test.ts
Normal file
2523
tests/capability-seams.test.ts
Normal file
File diff suppressed because it is too large
Load Diff
1157
tests/checkpoint-state.test.ts
Normal file
1157
tests/checkpoint-state.test.ts
Normal file
File diff suppressed because it is too large
Load Diff
1328
tests/compaction.test.ts
Normal file
1328
tests/compaction.test.ts
Normal file
File diff suppressed because it is too large
Load Diff
1167
tests/context-injector.test.ts
Normal file
1167
tests/context-injector.test.ts
Normal file
File diff suppressed because it is too large
Load Diff
1993
tests/doc-sync.test.ts
Normal file
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
729
tests/pba-event-bus.test.ts
Normal 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
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
1481
tests/profiles.test.ts
Normal file
File diff suppressed because it is too large
Load Diff
1085
tests/provider-registry.test.ts
Normal file
1085
tests/provider-registry.test.ts
Normal file
File diff suppressed because it is too large
Load Diff
243
tests/system-integration.test.ts
Normal file
243
tests/system-integration.test.ts
Normal 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");
|
||||
}
|
||||
749
tests/type-drift-check.test.ts
Normal file
749
tests/type-drift-check.test.ts
Normal 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
1329
tests/workflow.test.ts
Normal file
File diff suppressed because it is too large
Load Diff
11
tsconfig.realpi.json
Normal file
11
tsconfig.realpi.json
Normal 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"]
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user