physical_byte_agent/scripts/t06-t17.workflow.mjs
d-robotics 6d6a805d46
Some checks are pending
CI / quality-gate (push) Waiting to run
CI / type-drift (push) Waiting to run
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>
2026-08-14 15:35:49 +08:00

449 lines
32 KiB
JavaScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// 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 })),
};