架构设计文档_v4.md(新建,基于 v3 反映当前 as-built 架构): - 第一部分 定位+四哲学(新增哲学四:进化可信,硬件独有铁律) - 第二部分 与 pi 关系(继承/二开/绕开 + 命门一/二 + services 路径) - 第三部分 顶层架构(分层图:pi 底座 → v3 核心库 → 28 扩展 → L1-L5+X 自进化)+ 自进化 turn 数据流 - 第四部分 v3 底座子系统 A-I(全落地锚点) - 第五部分 自进化架构(J-P:L1-L5 + X.1+X.3+X.4,每层机器+装配+铁律+量化坐实) - 第六部分 目录与包结构 as-built(14 core 模块 + 28 barrel 工厂 + 6 eval) - 第七部分 测试与量化方法论(测试金字塔 + 7 评估标准 + 诚实边界) - 第八部分 里程碑 M0-M5+X 全 ✅ - 附录 A 源码锚点速查 + B 量化结果汇总 README.md 更新(从 21 扩展/2449 测 → 28 扩展/3018 测 + M1-M5+X 自进化): - 28 域扩展(22 域 + 6 自进化 bank)+ v4 自进化机器表(L1-L5+X 量化坐实) - 硬件独有铁律(§4.6 不对称/砖板率=0/forbidden 永不自改/risk 不增/§11.4 门) - 用法加 evolution-metrics CLI + 测试加 6 量化 eval - 里程碑 M0-M5+X 全 ✅ + 诚实边界 M1-M5.* 验证: tsc 0 / 全量 62 文件 3018 passed 5 skipped / sk- 明文 0 / 禁用词空 Co-Authored-By: Claude <noreply@anthropic.com>
30 KiB
Physical Byte Agent 架构设计文档(v4)
版本:v4(2026-08-17)—— 自进化能力全栈落地后的架构快照。 与 v3 的关系:v3 是"要建的设计";v4 是"已建的架构"。v3 的 P0+P1+P2 核心库底座(T06–T17)全部落地后,v4 在其之上新增了 L1–L5 五层自进化 + 跨层 X.1/X.3/X.4 闭环,pba 从"可长跑的嵌入式 Agent"升级为"全栈自进化嵌入式 Agent"。 姊妹文档:
自进化能力搭载设计.md(自进化的原理/数学/5 层/X 的量化坐实,本文档从架构视角汇总);Docs/postmortem/0003-real-pi-glm-x5-validation.md(真 pi+真 glm-5.2+真 RDK X5 端到端严验)。
0. 文档导读
| 你想了解 | 看哪节 |
|---|---|
| pba 是什么、为什么这么设计 | §1 |
| 与 pi / deepseek-harness 的关系 | §2 |
| 顶层分层(底座 + 自进化五层 + 跨层) | §3 |
| 核心子系统(v3 底座 A–I) | §4 |
| 自进化架构(L1–L5 + X,本文档重点) | §5 |
| 目录与包结构(as-built) | §6 |
| 测试与量化验证方法论 | §7 |
| 里程碑与进度(M0–M5+X 全 ✅) | §8 |
| 源码锚点速查 + 量化结果汇总 | 附录 A/B |
v4 相对 v3 的增量:
- 新增 7 个核心库模块(
experience-store/skill-manager/tool-growth/workflow-optimizer/variant-manager/feedback-collector/evolution-metrics)—— 自进化的机器。 - 新增 6 个扩展(
experience-bank/skill-bank/tool-bank/orchestration-bank/variant-bank/feedback-bank)—— 自进化接入 pi 钩子的装配层。barrel 22→28 工厂。 - 新增 1 个 CLI(
bin/evolution-metrics.ts)—— 进化可观测面板。 - 量化坐实:每层 + 跨层都有实验室级受控队列实验(seeded mulberry32 + Wilson CI + 真 manager 对齐),不只是"代码绿"。
第一部分:项目定位与设计哲学
1.1 一句话定位
pba = 基于 pi 二开的嵌入式开发 Agent + 全栈自进化闭环。在 pi 这个极简 agent harness 之上,加(a)嵌入式开发场景必需的能力栈(持久 shell、PDF/datasheet、硬件安全门、交叉编译、安全烧录、外设探测、JTAG、设备树、板链路、物理信号验证、闭环编排),(b)根治 pi + glm-5.2 组合的两个独家命门,(c)从硬件交互中持续改进自身的五层自进化闭环(经验库→技能表→工具生长→编排进化→脚手架自改 + 跨层反馈/可观测)。
1.2 四条设计哲学
哲学一:做层不做壳
pba 不重写 agent harness,而是在 pi 之上做"层"——核心库层(纯逻辑、注入式、无 pi 运行时)+ 扩展层(pi glue)。自进化是又一"层":L1–L5 各是独立核心库 + 扩展,叠加而非替换。
哲学二:收窄 RDK/ROS2
不追求通用机器人/嵌入式覆盖,收窄到 RDK X5/S100/S600 + 交叉编译/烧录/外设探测子集,把域知识做深。
哲学三:五条骨架嫁接,底座不换 Cordis
继承 pi 的 agent-loop/工具/exec/session 底座(Cordis),嫁接 deepseek-harness 的八条工程骨架(事件溯源/typed bus/工具流水线/沙箱/能力接缝/compaction/子代理/质量门)。
哲学四(v4 新增):进化可信,硬件独有铁律
自进化的难点不在"让它进化",而在"让进化 trustworthy"。pba 因硬件反馈可能不可逆,对 trustworthy 是一票否决级:砖板率=0(构造铁律)、forbidden 命门永不自改、不可逆暴露面 risk(G) 单调不增、§4.6 可信度不对称(不可逆失败只进 anti-pattern 永不进 actionable)。这些不是阈值,是构造不变式。
1.3 v4 的目标
把 pba 从 v3 的"可长跑嵌入式 Agent"升级为"机制层全栈自进化 + 量化坐实"的 Agent:五层自进化闭环(L1–L5)+ 跨层闭环(X.1 时序/X.3 v_t 全链路/X.4 可观测)全部落地,每层经实验室级受控实验量化验证有效 + 安全。
第二部分:与 pi 的关系
2.1 继承 pi(不动,直接用)
agent-loop、defineTool/registerTool、pi.exec、createAgentSession(Services)、session 持久化(better-sqlite3)、扩展加载(loader.ts createExtensionRuntime)、钩子时序(before_agent_start/tool_call/tool_result/message_end/session_before_compact/session_start)。
2.2 二开 pi(治命门 + 补骨架)
- 命门一(thinking 黑洞):
glm-provider.tsbuildGlmModelConfig()——thinkingFormat:"qwen"+maxTokens:8192+thinkingLevelMap全 null → piopenai-completions的enable_thinking:false分支。真 glm-5.2 实测usage.reasoning=0+ 真文本输出。 - 命门二(hex 强转砖板):
glm-provider.tsnormalizeHexArg()/makeHexNormalizingPrepareArguments()—— reg 工具prepareArguments把十进制还原 0x。真模型实测:1073872896→0x40020000。 - api id 铁律:pi 注册的 API id 是
"openai-completions"(非裸"openai");models.json + provider-registry + glm-provider 三处统一。 - apiKey 占位:pi 不对 provider apiKey 走
resolveConfigValue→glm-provider.tsresolveApiKey()在 pi 边界解析${DROBOTICS_LLM_KEY}。 - services 路径:
agent.tslaunch() 走createAgentSessionServices→createAgentSessionFromServices(flush 扩展 pendingProviderRegistrations 含真 key 到 modelRuntime;直连createAgentSession不 flush → 真 key 丢失)。
2.3 绕开 pi(不改 pi 源码,扩展层兜底)
length-recovery的partitionToolCallspi 扩展 API 够不着 agent-loop 内部 → prompt 注入兜底 + events 握手(不假装已完成)。- 自进化的
derive*(任务签名/蒸馏入参/先验校正/变体提案从 session 轨迹派生)默认经 feedback-bank 共享 collector 注入,不改 pi agent-loop。
2.4 与 pi 关系的本质
pba = pi 底座 + 嵌入式能力栈 + 自进化层。pi 提供"产生动作的机器",pba 加"嵌入式域知识 + 从反馈持续改进自身"。所有自进化都是 pi 扩展 + 核心库,不改 pi 源码。
第三部分:顶层架构设计
3.1 架构总览(分层图)
┌─────────────────────────────────────────────────────────────────────┐
│ 自进化层(v4 新增,L1–L5 + 跨层 X)—— 从硬件交互持续改进自身 │
│ ┌─────────────────────────────────────────────────────────────── │
│ │ L5 脚手架自改 variant-manager + variant-bank §11.4 不变式门 │
│ │ L4 编排进化 workflow-optimizer + orchestration-bank risk 不增│
│ │ L3 工具生长 tool-growth + tool-bank forbidden 拒绝 + 升级门│
│ │ L2 技能注册表 skill-manager + skill-bank infoGain 守卫防 plateau│
│ │ L1 硬件经验库 experience-store + experience-bank §4.6 不对称│
│ │ ───────────────────────────────────────────────────────────── │
│ │ 跨层 X.1+X.3 feedback-collector + feedback-bank tool_result │
│ │ →采集→derive*→5 层入库→检索→注入→约束(全链路) │
│ │ 跨层 X.4 evolution-metrics + bin/evolution-metrics CLI │
│ └─────────────────────────────────────────────────────────────── │
├─────────────────────────────────────────────────────────────────────┤
│ 核心库层(v3 P1+P2,T06–T17)—— 纯逻辑、注入式、无 pi 运行时 │
│ pba-session(事件溯源) · pba-event-bus · tool-pipeline · sandbox-policy│
│ context-injector · checkpoint-state · provider-registry │
│ + capabilities/{board-link,flash,subagent,workflow,approval,...} │
│ + compaction/{spill,summarizer,token-meter,tool-result-pruner} │
│ + profiles/{base,embedded-dev,repair-diagnosis} │
├─────────────────────────────────────────────────────────────────────┤
│ 扩展层(22 域扩展 + 6 自进化 bank = 28 barrel 工厂)—— pi glue │
│ 命门根治(glm-provider) · 安全门(safety-gate) · 基础设施 · 硬件能力 ·│
│ 闭环(loop-orchestrator/build-tracker) · 自进化 bank(6) │
├─────────────────────────────────────────────────────────────────────┤
│ pi Cordis 底座(继承不改)—— agent-loop / defineTool / pi.exec / │
│ createAgentSessionServices / session(better-sqlite3) / 扩展加载 │
└─────────────────────────────────────────────────────────────────────┘
3.2 数据流:一次自进化 turn
before_agent_start ──→ env-probe 探板(β) + feedback-bank.recordPrompt(σ派生)
──→ 4 bank 读 getSharedCollector().lastFinalized()
→ experience-bank: deriveSignature → query top-K → inject <experience_pack>
→ skill-bank: deriveSkillQuery → resolve → inject <skill_pack>
→ orchestration-bank: deriveTaskQuery → estimateDifficulty + selectWorkflow → inject <orchestration_plan>
→ variant-bank: inject <active_variants>(promoted 自改)
──→ runner 链式注入 systemPrompt → glm-5.2 决策
tool_call ──→ safety-gate 拦截破坏性命令 + tool-pipeline 五段流水线
tool_result ──→ feedback-bank.recordToolResult(outcome) 【X.1 采集】
message_end ──→ feedback-bank.finalize() → TaskFeedback 【X.3 结算】
session_before_compact ──→ 4 bank 的 derive* 读 lastFinalized
→ experience-bank: deriveDistillInput → distillEntry(§4.6 分级) → ExperienceStore.append
→ skill-bank: deriveSkillExtractInput → μ extract → register(infoGain 守卫)
→ orchestration-bank: derivePriorCorrection → correctPrior(滑动窗)
→ variant-bank: deriveProposals → propose(forbidden 命门 throw §11.3)
──→ 跨任务:下一轮 before_agent_start 检索到本轮蒸馏的经验/技能/…
3.3 运行时拓扑
单板串行(concurrency=1,板上跑闭环)+ 板外并行(多板 shadow A/B);自进化层每层独立 in-memory 单例(跨 turn 共享,跨 session 持久化 = M1-M5.* sqlite 接入)。
第四部分:核心子系统(v3 底座,已全落地)
v3 设计的 9 个子系统(A–I)在 v4 时点全部 ✅ 落地(M0–M3 完成)。本节仅列锚点,细节见 v3。
| 子系统 | 落点 | 状态 |
|---|---|---|
| A Session 事件溯源 | core/pba-session.ts(append 唯一提交点 lossless-JSON+深冻结+seq 连续+重入 guard + deriveMessages 增量缓存 + replayFromEntries + model-visible⟺logged) |
✅ |
| B Typed Event Bus + Scope 隔离 | core/pba-event-bus.ts(waterfall 链委托/短路 + emit 并行广播 + ScopeKey 单向冒泡) |
✅ |
| C 五段工具流水线 | core/tool-pipeline.ts(pre-execute waterfall + monotonic guards + finalizeContent) |
✅ |
| D OS 级沙箱 | core/sandbox-policy.ts(board_exec fail-closed landlock/seccomp + shouldRunCommand 门) |
✅ |
| E 能力接缝三角色 | capabilities/{board-link,flash,subagent,workflow}/(Provider+Registry fail-closed+consumer) |
✅ |
| F compaction 完整工程 | compaction/{spill,summarizer,token-meter,tool-result-pruner}.ts |
✅ |
| G 子代理 + 工作流 | capabilities/{subagent,workflow}/(InlineSubagentProvider + parallel/pipeline) |
✅ |
| H 嵌入式能力栈 | 22 域扩展(persistent-shell/pdf-reader/cross-compile/flash/peripheral-probe/jtag-debugger/device-tree/board-link/datasheet-rag/hardware-verify/...) | ✅ |
| I 质量门 + postmortem | .github/workflows/ci.yml + scripts/ + Docs/postmortem/ + type-drift-check |
✅ |
第五部分:自进化架构(v4 重点)
原理/数学/失败模式见
自进化能力搭载设计.md§2–§4。本节从架构视角讲每层的机器 + 落点 + 量化坐实。
5.1 自进化五层总览
| 层 | 机器(核心库) | 装配(扩展) | 进化的对象 | 形式化 | 量化坐实 |
|---|---|---|---|---|---|
| L1 硬件经验库 | experience-store.ts |
experience-bank.ts |
跨任务轨迹记忆 M | §4.2 R + §4.3 Distill/Evict | ΔJ=0.34, held-out 0.1545, CI STRONG |
| L2 技能注册表 | skill-manager.ts |
skill-bank.ts |
可调用技能 + μ | §4.4 infoGain + §8.3 μ | ΔJ=0.265, F1 负控 plateau 实证 |
| L3 工具生长 | tool-growth.ts |
tool-bank.ts |
工具定义 V | §4.7 V + §4.8 risk | 步效率 0.24(砍76%), 砖板率=0 EXACT |
| L4 编排进化 | workflow-optimizer.ts |
orchestration-bank.ts |
workflow 图 G | §4.7 G* + §4.8 risk 不增 | ΔJ=0.2975(θ固定), risk 不增 EXACT |
| L5 脚手架自改 | variant-manager.ts |
variant-bank.ts |
扩展代码 θ | §4.5 θ + §11.4 门 | ΔJ=0.15, forbidden 永不自改 EXACT, 回滚实证 |
5.2 子系统 J:L1 硬件经验库(experience-store + experience-bank)
- 机器:
ExperienceStore(append幂等去重+§4.6 强制 /query(σ,β,topK)打分排序+检索升权 /evict时间淘汰+β失配降权+低命中衰减 /BoardMemoryupsert 聚合)。可注入后端(in-memory 默认,sqlite 可选)+ 可注入时钟。 - 装配:
experience-bank(仿 env-probe)before_agent_start检索 top-K + 注入<experience_pack>(TTL 缓存)+session_before_compactdistillEntry(v_t 分级 + §4.6 不对称强制入库)+experience_recall工具。 - 铁律:§4.6 可信度不对称(
irreversible-fail⇒anti-pattern/inferred⇏actionable,assertAsymmetry运行时强制)。 - 量化(
tests/eval/experience-bank-eval.test.ts,N=400):ΔJ_full=0.34≥0.15、held-out ΔJ=0.1545≥0.05、distill-off=0、F4 负控=0、CI 非重叠 STRONG、真 store 与对照 5 指标全等。
5.3 子系统 K:L2 可学技能注册表(skill-manager + skill-bank)
- 机器:
SkillManager(μ:extract/registerinfoGain 守卫/resolve升权/supersede链/merge累积质量/evict)+SkillRegistry(仿 FlashRegistry)+ 纯函数extractSkill/infoGainGate/mergeSkills/scoreSkill。 - 装配:
skill-bankbefore_agent_start检索技能 + 注入<skill_pack>+session_before_compactμ extract/register +skill_recall。 - 铁律:infoGain 守卫防 F1 plateau(相似度>0.85→merge 不新增);双信号 exec 为主(0.7)+rubric(0.3);supersede 链防死技能堆积。
- 量化(
skill-registry-eval.test.ts,N=400):ΔJ=0.265、held-out 0.2545、F1 负控:守卫 OFF 技能数 400>12 但 J_E=0.685<J_A=0.875(infoGain 防 plateau 实证)、supersede active 有界、CI STRONG、真 manager 与对照 5 指标全等。
5.4 子系统 L:L3 工具生长(tool-growth + tool-bank)
- 机器:
ToolGrowthManager(propose白名单 forbidden 拒绝 throw §4.8 /recordUsage/tryPromote升级门 K+repeatable /verify/retire生命周期 draft→verified→promoted→retired /brickRate恒 0 构造铁律)+ 纯函数classifyProposal/promotionGate/canTransition。 - 装配:
tool-banktool_propose/tool_record/tool_promote/tool_list_grown/tool_retire工具 +before_agent_start注入<grown_tools>。 - 铁律:forbidden(flash/erase/fuse/devmem/write)永不自创;升级门 usage<K+passRate<阈值永不 promote;risk(G) 不增。
- 量化(
tool-growth-eval.test.ts,N=300):步效率 0.24<0.70(砍 76% 步)、ΔJ=0.1367、砖板率=0 EXACT 构造铁律、forbidden 7 拒/0 受、升级门低 usage promote=0、CI STRONG。
5.5 子系统 M:L4 编排进化(workflow-optimizer + orchestration-bank)
- 机器:
WorkflowOptimizer(estimateDifficultyd̂(σ,β) /selectWorkflow/evolveWorkflow符号反向传播backpropGradient+applyGradient+§4.8 risk 不增守卫 /registerWorkflowsupersede /correctPrior滑动窗)+WorkflowRegistry(按 taskClass 分桶)。 - 装配:
orchestration-bankbefore_agent_start难度估+workflow 选择 + 注入<orchestration_plan>+session_before_compact先验校正 +orchestration_recall。 - 铁律:θ 固定(ΔJ 归因 G 变化非模型变化,§10.5);risk(G*)≤risk(G_default) 构造铁律。
- 量化(
orchestration-eval.test.ts,N=400):ΔJ_G=0.2975≥0.10(θ 固定归因 G)、held-out 0.3182、难度 corr 0.6121>0、distill-off=0、risk 不增 EXACT(1≤1)、risk-increase 负控 242 拒、CI STRONG、真 optimizer 与对照对齐。
5.6 子系统 N:L5 脚手架自改(variant-manager + variant-bank,终局最强约束)
- 机器:
VariantManager(propose白名单 forbidden 命门 throw §11.3 /runInvariants注入InvariantChecker/abTest注入ABTestRunner/tryPromote不变式全过+A/B 胜出→promoted,不变式失败→rolled-back /rollback可逆 /resolve只返 promoted)+VariantRegistry+ 纯函数classifyProposalVariant/promotionDecision。 - 装配:
variant-bankvariant_propose/variant_list/variant_promote/variant_rollback工具 + 注入<active_variants>+session_before_compactderiveProposals。 - 铁律:自改范围白名单(forbidden 命门 safety-gate/sandbox-policy/flash/glm-provider 永不自改 §11.3);§11.4 不变式门(7 条:单测/tsc/sk- 扫/真模型 launch/沙箱门/砖板率=0/risk 不增);A/B 胜出+不变式全过才 promote;任何回归自动回滚。
- 量化(
variant-eval.test.ts,N=200):ΔJ_selfmod=0.15≥0.05、forbidden 命门 5 拒/0 受 EXACT(§11.3)、§11.4 门捕有害变体 2、回滚触发 1(§11.6 可逆性实证)、promoted 有益 3、全 promoted allPassed、CI STRONG、真 manager 与对照对齐。
5.7 子系统 O:跨层 X.1+X.3 反馈采集全链路(feedback-collector + feedback-bank)
- 机器:
FeedbackCollector(recordPrompt/recordBoardFingerprint/recordToolResult/finalize/lastFinalized/pending/clear)+ 纯变换derive*(deriveTaskSignature/deriveDistillInput/deriveSkillExtractInput/deriveSkillQuery/derivePriorCorrection/deriveProposals+inferOutcome/inferActionClass/inferValidatedBy/isIrreversibleTool)+ 共享单例getSharedCollector/initSharedCollector。 - 装配:
feedback-bankhookstool_result+message_end+before_agent_start+session_before_compact→ 采集 → finalize → 喂 derive* +feedback_recall工具。 - 生产自驱:4 bank(experience/skill/orchestration/variant)默认 derive* 读
getSharedCollector().lastFinalized()→ 生产闭环(tool_result 自动采集→derive* 蒸馏→5 层入库→检索→注入→约束)。向后兼容(无反馈→null→fail-closed)。 - 量化(
feedback-chain-eval.test.ts,集成型非 mock 队列):§4.6 分级 8/8=100%(success+ground-truth/可逆/不可逆/partial/empty/mixed 全过)、同签名检索命中 100%、注入块可见 100%、5 链 end-to-end、forbidden §11.3/§4.8 拒绝。
5.8 子系统 P:跨层 X.4 进化可观测面板(evolution-metrics + CLI)
- 机器:
aggregateMetrics/renderMetrics纯函数(5 层注册表聚合 →EvolutionMetrics:规模/命中率/infoGain/risk/砖板率/forbidden 拒绝)+EvolutionMetricsAggregator。 - 装配:
bin/evolution-metrics.tsCLI(npx tsx bin/evolution-metrics.ts打印面板;brickRate!==0时 exit 1 fail-closed 自检)。 - 量化(
evolution-metrics-eval.test.ts):精确指标全过(experienceHitRate=0.600/avgInfoGain=0.650/maxRisk=1/brickRate=0 EXACT 构造铁律/forbiddenRejected=7)。
5.9 时序三档接线(X.1)
| 时序 | 钩子 | 改的对象 | 落点 |
|---|---|---|---|
| task-time | before_agent_start(适配+注入)+ tool_call(safety-gate 拦截+收敛) |
当前 patch/工具调用/编排 | 5 bank + safety-gate |
| post-task | tool_result(采集)+ message_end(finalize)+ session_before_compact(蒸馏) |
d_t=Distill→M_{t+1} | feedback-bank + 4 bank derive* |
| stage-wise | (M5.* 真 θ 更新待) | θ 权重 | variant-manager 数据模型 + §11.4 门(真 CI 执行=M5.*) |
第六部分:目录与包结构(as-built)
physical_byte_agent/
├── package.json # @d-robotics/physical-byte-agent; pi.extensions:[src/extensions/index.ts]; bin:{pba,evolution-metrics}
├── tsconfig.json # paths 指向真 pi 源码(弃 shim)
├── vitest.config.ts # alias 指向真 pi 源码(运行时解析 .ts)
├── models.json # glm-5.2 条目(thinkingFormat:qwen/maxTokens:8192/api:openai-completions/key:${DROBOTICS_LLM_KEY})
├── bin/
│ ├── pba.ts # #!/usr/bin/env node → new PhysicalByteAgent().launch()
│ └── evolution-metrics.ts # X.4 可观测面板 CLI
├── src/
│ ├── index.ts # 公共 API re-export
│ ├── agent.ts # PhysicalByteAgent.launch() services 路径 + verifyAssembly()
│ ├── shared/types.ts # 跨扩展共享类型(含自进化 L1-L5+X 类型 + 纯函数)
│ ├── core/ # 核心库层(纯逻辑,无 pi 运行时)
│ │ ├── pba-session.ts · pba-event-bus.ts · tool-pipeline.ts · sandbox-policy.ts
│ │ ├── context-injector.ts · checkpoint-state.ts · provider-registry.ts
│ │ ├── experience-store.ts · skill-manager.ts · tool-growth.ts
│ │ ├── workflow-optimizer.ts · variant-manager.ts
│ │ ├── feedback-collector.ts · evolution-metrics.ts
│ ├── capabilities/ # 能力接缝三角色
│ │ ├── board-link/ · flash/ · subagent/ · workflow/
│ │ ├── approval.ts · credentials.ts · settings.ts · lsp.ts
│ ├── compaction/ # spill · summarizer · token-meter · tool-result-pruner
│ ├── profiles/ # base · embedded-dev · repair-diagnosis · index
│ ├── extensions/ # 28 barrel 工厂(22 域 + 6 自进化 bank)
│ │ ├── index.ts # 单一 barrel 装配入口
│ │ ├── glm-provider.ts · safety-gate.ts · ... · reg-tool.ts # 22 域
│ │ ├── experience-bank.ts · skill-bank.ts · tool-bank.ts # L1-L3
│ │ ├── orchestration-bank.ts · variant-bank.ts · feedback-bank.ts # L4-L5+X
│ └── types/pi.d.ts # pi 类型镜像(type-drift-check 对真 pi 源码)
├── tests/ # 62 测试文件(单测 + 集成 + 6 eval)
│ ├── *.test.ts # 模块单测(mock ExecFn,无硬件)
│ ├── eval/ # 6 个量化评估实验(seeded mulberry32 + Wilson CI)
│ │ ├── experience-bank-eval · skill-registry-eval · tool-growth-eval
│ │ ├── orchestration-eval · variant-eval · feedback-chain-eval · evolution-metrics-eval
│ └── system-integration.test.ts · e2e-runtime.test.ts · e2e-smoke.test.ts
└── Docs/ + 自进化能力搭载设计.md + 架构设计文档_v3.md(v3) + _v4.md(本)
barrel 28 工厂装配顺序:命门根治(glm-provider) → 安全门(safety-gate) → 基础设施 → 硬件能力 → 闭环(loop-orchestrator/build-tracker) → 自进化 L1-L3(experience/skill/tool-bank) → L4-L5(orchestration/variant-bank) → 跨层(feedback-bank)。
第七部分:测试与量化验证方法论
7.1 测试金字塔
- 单测(模块级,mock ExecFn,无硬件无 pi 运行时):等价类/边界值/决策表/状态转换/变异测试(每模块植入 seeded bug 必被杀)/对抗 fuzz/元蜕变不变式。
- 集成测试(跨模块闭环):
system-integration.test.ts+e2e-smoke.test.ts。 - 真运行时冒烟:
e2e-runtime.test.ts真 pi services 路径 boot(barrel 28 工厂装配 + provider 真 key 注册 + glm-5.2 解析不抛)。 - 量化评估实验(6 个,实验室级):seeded mulberry32 + N=200-400 受控队列 + Wilson 95% CI + 真 manager 与对照实现全等对齐 + 预注册阈值。
7.2 量化评估标准(每层 + 跨层)
| 评估 | 证明 | 预注册阈值(全 PASS) |
|---|---|---|
| experience-bank-eval | L1 经验库有效 | ΔJ_full≥0.15 / held-out≥0.05 / distill-off=0 / F4 负控=0 / CI STRONG |
| skill-registry-eval | L2 技能表有效+防 plateau | ΔJ≥0.15 / F1 负控(技能数爆但 J 不升)/ supersede 有界 / CI STRONG |
| tool-growth-eval | L3 工具生长有效+安全 | 步效率<0.70 / ΔJ≥0.05 / 砖板率=0 EXACT / forbidden 拒=受 / CI STRONG |
| orchestration-eval | L4 编排进化有效+risk 不增 | ΔJ_G≥0.10(θ固定) / 难度 corr>0 / risk 不增 EXACT / CI STRONG |
| variant-eval | L5 自改有效+安全 | ΔJ≥0.05 / forbidden 永不自改 EXACT / §11.4 门捕有害 / 回滚触发 / CI STRONG |
| feedback-chain-eval | X.1+X.3 全链路 end-to-end | §4.6 分级 100% / 检索命中 100% / 注入可见 100% / 5 链 end-to-end |
| evolution-metrics-eval | X.4 面板精确 | 精确指标 / brickRate=0 EXACT |
7.3 诚实边界(M1-M5.* 跟进,非缺陷)
- 评估为忠实 §4.2/§9 mock 策略受控实验,证机制与机器的因果效应;未测真 glm-5.2 经 pi 真读注入包后真受益的端到端门(前序 fail2ban 等环境阻塞)。
derive*真接线已落地(feedback-bank 共享 collector + 4 bank 生产自驱),但真 LLM 摘要钩子(更高质的蒸馏)= M1-M5.*。- stage-wise 真 θ 更新(L5 真权重)= M5.*;当前 L5 是数据模型 + §11.4 门(真 git worktree + 真 vm 沙箱 execute 变体工厂 + 真 CI 不变式执行 = M5.*)。
- 跨 session 持久化默认 in-memory;sqlite 后端为可注入扩展点(M1-M5.* 接入即跨 session)。
第八部分:里程碑与进度
| 里程碑 | 内容 | 状态 | 量化 |
|---|---|---|---|
| M0 | v3 P0 底座(22 域扩展 + 命门根治) | ✅ | 真 pi+真 glm-5.2+真 X5 端到端严验(postmortem 0003) |
| M1-M3 | v3 P1+P2 核心库(T06–T17) | ✅ | 39 文件 2449 passed |
| M1 | L1 硬件经验库 | ✅ | ΔJ=0.34, CI STRONG |
| M2 | L2 技能注册表 | ✅ | ΔJ=0.265, F1 防 plateau 实证 |
| M3 | L3 工具生长 | ✅ | 步效率 0.24, 砖板率=0 EXACT |
| M4 | L4 编排进化 | ✅ | ΔJ=0.2975(θ固定), risk 不增 EXACT |
| M5 | L5 脚手架自改 | ✅ | ΔJ=0.15, forbidden 永不自改, 回滚实证 |
| X.1+X.3 | 跨层反馈全链路 | ✅ | §4.6 100%, 5 链 end-to-end, 4 bank 生产自驱 |
| X.4 | 进化可观测面板 | ✅ | 精确指标, brickRate=0 EXACT |
当前:全量 62 文件 3018 passed / 5 skipped / tsc 0 / sk- 明文 0 / 真 pi T01 boot 过(barrel 28 扩展)。pba = "L1-L5 全栈自进化 + 跨层闭环嵌入式 Agent"。
下一步(M1-M5.*):live-LLM 端到端门坐实真模型受益;stage-wise 真 θ;真 git worktree + 真 CI §11.4 执行;sqlite 跨 session。
附录 A:源码锚点速查(as-built)
| 组件 | 锚点 |
|---|---|
| barrel 装配 | src/extensions/index.ts(28 工厂 + physicalByteAgentAssembly fail-soft) |
| 程序化启动 | src/agent.ts PhysicalByteAgent.launch()(services 路径)+ verifyAssembly() |
| 命门一/二 | src/extensions/glm-provider.ts buildGlmModelConfig/normalizeHexArg/resolveApiKey |
| L1 经验库 | src/core/experience-store.ts + src/extensions/experience-bank.ts |
| L2 技能表 | src/core/skill-manager.ts + src/extensions/skill-bank.ts |
| L3 工具生长 | src/core/tool-growth.ts + src/extensions/tool-bank.ts |
| L4 编排进化 | src/core/workflow-optimizer.ts + src/extensions/orchestration-bank.ts |
| L5 脚手架自改 | src/core/variant-manager.ts + src/extensions/variant-bank.ts |
| X.1+X.3 反馈链路 | src/core/feedback-collector.ts + src/extensions/feedback-bank.ts |
| X.4 可观测面板 | src/core/evolution-metrics.ts + bin/evolution-metrics.ts |
| §4.6 不对称强制 | src/shared/types.ts assertAsymmetry + distillEntry |
| §4.8 risk 不增 | src/core/workflow-optimizer.ts evolveWorkflow + src/shared/types.ts riskOfWorkflow |
| §11.4 不变式门 | src/core/variant-manager.ts runInvariants/promotionDecision + InvariantChecker |
| 事件溯源 | src/core/pba-session.ts |
| 工具流水线 | src/core/tool-pipeline.ts |
| 沙箱门 | src/core/sandbox-policy.ts shouldRunCommand |
附录 B:量化结果汇总(2026-08-17,独立复跑一致)
| 层 | 头条指标 | 实测 | 构造铁律 |
|---|---|---|---|
| L1 | ΔJ_full / held-out | 0.34 / 0.1545 | §4.6 不对称(distillEntry 强制) |
| L2 | ΔJ / F1 负控 | 0.265 / 技能 400>12 但 J 不升 | infoGain 守卫防 plateau |
| L3 | 步效率 / ΔJ | 0.24(砍76%) / 0.1367 | 砖板率=0 EXACT + forbidden 拒 |
| L4 | ΔJ_G(θ固定) / risk | 0.2975 / 1≤1 | risk 不增 EXACT |
| L5 | ΔJ / forbidden / 回滚 | 0.15 / 5拒0受 / 1触发 | forbidden 永不自改 EXACT + §11.4 门 |
| X.1+X.3 | §4.6 分级 / 5 链 | 8/8=100% / 全过 | 全链路 end-to-end + 4 bank 生产自驱 |
| X.4 | 精确指标 | 全精确 | brickRate=0 EXACT |
全部经真实 manager + 对照实现全等验证;Wilson 95% CI 非重叠达 STRONG 强度。诚实边界见 §7.3。