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>
449 lines
32 KiB
JavaScript
449 lines
32 KiB
JavaScript
// 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 })),
|
||
};
|