physical_byte_agent/架构设计文档_v4.md
d-robotics bf9ae71183
Some checks failed
CI / quality-gate (push) Has been cancelled
CI / type-drift (push) Has been cancelled
docs: 架构设计文档_v4 + README 更新(M1-M5+X 全栈自进化架构 as-built)
架构设计文档_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>
2026-08-17 18:02:45 +08:00

30 KiB
Raw Permalink Blame History

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 的增量:

  1. 新增 7 个核心库模块(experience-store/skill-manager/tool-growth/workflow-optimizer/variant-manager/feedback-collector/evolution-metrics)—— 自进化的机器。
  2. 新增 6 个扩展(experience-bank/skill-bank/tool-bank/orchestration-bank/variant-bank/feedback-bank)—— 自进化接入 pi 钩子的装配层。barrel 22→28 工厂。
  3. 新增 1 个 CLI(bin/evolution-metrics.ts)—— 进化可观测面板。
  4. 量化坐实:每层 + 跨层都有实验室级受控队列实验(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.ts buildGlmModelConfig() —— thinkingFormat:"qwen" + maxTokens:8192 + thinkingLevelMap 全 null → pi openai-completions 的 enable_thinking:false 分支。真 glm-5.2 实测 usage.reasoning=0 + 真文本输出。
  • 命门二(hex 强转砖板):glm-provider.ts normalizeHexArg()/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.ts resolveApiKey() 在 pi 边界解析 ${DROBOTICS_LLM_KEY}。
  • services 路径:agent.ts launch() 走 createAgentSessionServices→createAgentSessionFromServices(flush 扩展 pendingProviderRegistrations 含真 key 到 modelRuntime;直连 createAgentSession 不 flush → 真 key 丢失)。

2.3 绕开 pi(不改 pi 源码,扩展层兜底)

  • length-recovery 的 partitionToolCalls pi 扩展 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 时间淘汰+β失配降权+低命中衰减 / BoardMemory upsert 聚合)。可注入后端(in-memory 默认,sqlite 可选)+ 可注入时钟。
  • 装配:experience-bank(仿 env-probe)before_agent_start 检索 top-K + 注入 <experience_pack>(TTL 缓存)+ session_before_compact distillEntry(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-bank before_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-bank tool_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(estimateDifficulty d̂(σ,β) / selectWorkflow / evolveWorkflow 符号反向传播 backpropGradient+applyGradient+§4.8 risk 不增守卫 / registerWorkflow supersede / correctPrior 滑动窗)+ WorkflowRegistry(按 taskClass 分桶)。
  • 装配:orchestration-bank before_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-bank variant_propose/variant_list/variant_promote/variant_rollback 工具 + 注入 <active_variants> + session_before_compact deriveProposals。
  • 铁律:自改范围白名单(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-bank hooks tool_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.ts CLI(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.* 跟进,非缺陷)

  1. 评估为忠实 §4.2/§9 mock 策略受控实验,证机制与机器的因果效应;未测真 glm-5.2 经 pi 真读注入包后真受益的端到端门(前序 fail2ban 等环境阻塞)。
  2. derive* 真接线已落地(feedback-bank 共享 collector + 4 bank 生产自驱),但真 LLM 摘要钩子(更高质的蒸馏)= M1-M5.*。
  3. stage-wise 真 θ 更新(L5 真权重)= M5.*;当前 L5 是数据模型 + §11.4 门(真 git worktree + 真 vm 沙箱 execute 变体工厂 + 真 CI 不变式执行 = M5.*)。
  4. 跨 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。