docs: 架构设计文档_v4 + README 更新(M1-M5+X 全栈自进化架构 as-built)
Some checks failed
CI / quality-gate (push) Has been cancelled
CI / type-drift (push) Has been cancelled

架构设计文档_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>
This commit is contained in:
d-robotics 2026-08-17 18:02:45 +08:00
parent 74f4cd428e
commit bf9ae71183
2 changed files with 401 additions and 41 deletions

View File

@ -1,21 +1,42 @@
# @d-robotics/physical-byte-agent
基于 [pi](https://github.com/earendil-works/pi) 二开的**嵌入式开发 Agent**,默认模型 `glm-5.2`(经 d-robotics 内部网关)。
基于 [pi](https://github.com/earendil-works/pi) 二开的**嵌入式开发 Agent + 全栈自进化闭环**,默认模型 `glm-5.2`(经 d-robotics 内部网关)。
定位:在 pi 这个极简 agent harness 之上,加一层嵌入式开发场景必需的能力——持久 shell、PDF/datasheet 读取、硬件安全门、交叉编译、安全烧录、外设探测、JTAG 调试、设备树、板链路、物理信号验证、闭环编排——并根治 pi + glm-5.2 组合的两个独家命门。
定位:在 pi 这个极简 agent harness 之上,加(a)嵌入式开发场景必需的能力栈——持久 shell、PDF/datasheet 读取、硬件安全门、交叉编译、安全烧录、外设探测、JTAG 调试、设备树、板链路、物理信号验证、闭环编排;(b)根治 pi + glm-5.2 组合的两个独家命门;(c)**从硬件交互中持续改进自身的五层自进化闭环**(经验库→技能表→工具生长→编排进化→脚手架自改 + 跨层反馈/可观测)。
## 两个命门
> 架构全貌见 `架构设计文档_v4.md`;自进化原理/数学/量化见 `自进化能力搭载设计.md`;真 pi+真 glm-5.2+真 RDK X5 端到端严验见 `Docs/postmortem/0003-real-pi-glm-x5-validation.md`。
## 两个命门(根治)
| 命门 | 现象 | 根治点 |
|---|---|---|
| 一·thinking 黑洞 | glm-5.2 默认开 thinking,max_tokens 全被 reasoning 吃光 → 零文本输出 | `glm-provider.ts` `buildGlmModelConfig()`:`thinkingFormat:"qwen"` + `maxTokens:8192` + `thinkingLevelMap` 全 null,触发 pi `openai-completions` 的 `enable_thinking:false` 分支 |
| 二·hex 强转 | glm-5.2 把寄存器地址 `0x40020000` 强转成十进制 `"1073872896"`,下游写错地址即砖板 | `glm-provider.ts` `normalizeHexArg()` / `makeHexNormalizingPrepareArguments()`:在 `prepareArguments` 把寄存器地址范围内的十进制还原成 0x 形式 |
| 一·thinking 黑洞 | glm-5.2 默认开 thinking,max_tokens 全被 reasoning 吃光 → 零文本输出 | `glm-provider.ts` `buildGlmModelConfig()`:`thinkingFormat:"qwen"` + `maxTokens:8192` + `thinkingLevelMap` 全 null → pi `openai-completions` 的 `enable_thinking:false` 分支(真模型实测 `usage.reasoning=0`) |
| 二·hex 强转 | glm-5.2 把寄存器地址 `0x40020000` 强转成十进制 `"1073872896"`,下游写错地址即砖板 | `glm-provider.ts` `normalizeHexArg()` / `makeHexNormalizingPrepareArguments()`:reg 工具 `prepareArguments` 把十进制还原 0x(真模型实测 `1073872896`→`0x40020000`) |
## 21 个域扩展
## 28 个域扩展(barrel 工厂)
`glm-provider` · `safety-gate` · `persistent-shell` · `pdf-reader` · `edit-strict` · `length-recovery` · `subprocess-isolation` · `env-probe` · `mcp-bridge` · `server-runtime` · `hardware-state` · `cross-compile` · `flash` · `peripheral-probe` · `jtag-debugger` · `device-tree` · `board-link` · `datasheet-rag` · `hardware-verify` · `loop-orchestrator` · `build-tracker`
**22 域**:`glm-provider` · `safety-gate` · `persistent-shell` · `pdf-reader` · `edit-strict` · `length-recovery` · `subprocess-isolation` · `env-probe` · `mcp-bridge` · `server-runtime` · `hardware-state` · `cross-compile` · `flash` · `peripheral-probe` · `jtag-debugger` · `device-tree` · `board-link` · `datasheet-rag` · `hardware-verify` · `loop-orchestrator` · `build-tracker` · `reg-tool`
每个扩展文件 = pi glue(`export default (pi) => {...}`)+ 纯逻辑命名导出(供单测)。详见 `Docs/F01-F21`。
**6 自进化 bank(L1–L5 + 跨层)**:`experience-bank`(L1 经验库)· `skill-bank`(L2 技能表)· `tool-bank`(L3 工具生长)· `orchestration-bank`(L4 编排进化)· `variant-bank`(L5 脚手架自改)· `feedback-bank`(跨层反馈采集)
每个扩展文件 = pi glue(`export default (pi) => {...}`)+ 纯逻辑命名导出(供单测)。
## 核心库层(纯逻辑、注入式、无 pi 运行时)
**v3 底座(T06–T17)**:`pba-session`(事件溯源)· `pba-event-bus`(typed bus + Scope 隔离)· `tool-pipeline`(五段流水线)· `sandbox-policy`(board_exec fail-closed 沙箱门)· `context-injector`(inject/steer/followup 三段)· `checkpoint-state` · `provider-registry`(多 LLM provider)· `capabilities/{board-link,flash,subagent,workflow,approval,credentials,settings,lsp}` · `compaction/{spill,summarizer,token-meter,tool-result-pruner}` · `profiles/{base,embedded-dev,repair-diagnosis}`
**v4 自进化机器(L1–L5 + 跨层)**:
| 层 | 核心库 | 进化的对象 | 量化坐实 |
|---|---|---|---|
| L1 经验库 | `core/experience-store.ts` | 跨任务轨迹记忆 | ΔJ=0.34, held-out 0.1545, CI STRONG |
| L2 技能表 | `core/skill-manager.ts` | 可调用技能 + μ | ΔJ=0.265, infoGain 防 plateau 实证 |
| L3 工具生长 | `core/tool-growth.ts` | 工具定义 V | 步效率 0.24(砍76%), **砖板率=0 EXACT** |
| L4 编排进化 | `core/workflow-optimizer.ts` | workflow 图 G | ΔJ=0.2975(θ固定), **risk 不增 EXACT** |
| L5 脚手架自改 | `core/variant-manager.ts` | 扩展代码 θ | ΔJ=0.15, **forbidden 永不自改**, 回滚实证 |
| 跨层 X.1+X.3 | `core/feedback-collector.ts` | 反馈采集全链路 | §4.6 分级 100%, 5 链 end-to-end |
| 跨层 X.4 | `core/evolution-metrics.ts` | 进化可观测面板 | 精确指标, brickRate=0 EXACT |
**硬件独有铁律(构造不变式,非阈值)**:§4.6 可信度不对称(不可逆失败只进 anti-pattern 永不进 actionable)· 砖板率=0 · forbidden 命门(safety-gate/sandbox/flash/glm-provider)永不自改 · risk(G) 单调不增 · §11.4 不变式门(7 条)。
## 用法
@ -26,7 +47,7 @@ cd ../pi && npm install --ignore-scripts && npm rebuild better-sqlite3
# 2. 配 key(环境占位,绝不写进代码)
export DROBOTICS_LLM_KEY=sk-...
# 3. 作为 pi profile 跑(pi 自动加载 src/extensions/index.ts barrel)
# 3. 作为 pi profile 跑(pi 自动加载 src/extensions/index.ts barrel,28 工厂)
cd ../physical-byte-agent
npx tsx bin/pba.ts # 或 pi --agent-dir .
@ -34,49 +55,42 @@ npx tsx bin/pba.ts # 或 pi --agent-dir .
import { PhysicalByteAgent } from "@d-robotics/physical-byte-agent";
const agent = new PhysicalByteAgent();
const { session } = await agent.launch();
# 5. 进化可观测面板(X.4)
npx tsx bin/evolution-metrics.ts # 打印 5 层注册表聚合指标(brickRate!=0 时 exit 1 自检)
```
## 核心库层(v3 P1+P2,T06–T17)
21 域扩展(P0)之上,v3 加了一层**核心库**(纯逻辑、注入式依赖、无 pi 运行时、各自独立单测 + 跨模块系统集成测试)。这是 pba 从"散装扩展"走向"可长跑/可维护/可扩展 Agent"的底座。里程碑 M0/M1/M2/M3 全 ✅。
| 任务 | 模块 | 落地点 |
|---|---|---|
| T06 | `src/core/pba-session.ts` | 事件溯源:append 唯一提交点(lossless-JSON+深冻结+seq 连续+重入 guard)+ deriveMessages 增量缓存 + replayFromEntries + "model-visible⟺logged" 不变量 |
| T07 | `src/core/pba-event-bus.ts` | typed event bus:waterfall 链委托/短路 + emit 并行广播 + ScopeKey 单向冒泡(子 agent 事件不串主) |
| T08 | `src/capabilities/{board-link,flash}/` | 能力接缝三角色:Provider(Definition) + Registry(register/resolve fail-closed) + consumer;3 板 provider + 4 烧录 provider 抽自原扩展 |
| T09 | `src/compaction/` | compaction 完整工程:token-meter + i2cdump/gdb/dmesg prune(寄存器地址不丢)+ KV prefix 复用标记 + SpillStore branded 句柄 |
| T10 | `.github/workflows/ci.yml` + `scripts/` | CI 质量门:per-file 100% 覆盖 + snapshot 结构化 diff + doc-sync 锚点对齐 + type-drift-check |
| T11 | `tsconfig.realpi.json` + `scripts/type-drift-check.ts` | 类型镜像漂移检测:对真 pi 源码 tsc,分流 pbaErrors vs piInternalErrors |
| T12 | `src/capabilities/{subagent,workflow}/` | 子代理 + 工作流编排:InlineSubagentProvider spawn-in-process + parallel(barrier/null-on-throw) + pipeline(无 barrier/stage 抛错落 null) |
| T13 | `src/core/context-injector.ts` | 上下文注入三段:inject(不唤醒)/ steer(换板 next-step 唤醒)/ followup(next-turn 唤醒),最新 snapshot 取代更早 |
| T14 | `src/core/checkpoint-state.ts` | plan/goal/todo logged state:CheckpointRecorder record→checkpoint-change 事件 + rebuild 从 log 重建 + fork;look-ahead 状态机 |
| T15 | `src/profiles/` | profile/bundle 分层:BASE_PROFILE 共享 + 维修诊断/嵌入式开发两 profile 叠差异 + mergeProfiles/diffProfiles + resolveProfile fail-closed 防 prototype 污染 |
| T16 | `src/core/provider-registry.ts` | 多 LLM provider 适配:ProviderDescriptor + buildProviderConfig 泛化(glm-5.2/deepseek)+ ProviderRegistry;换模型改配置不改扩展 |
| T17 | `src/capabilities/{approval,credentials,settings,lsp}.ts` | 审批接缝(fail-closed 无人值守 auto-deny)+ CredentialsStore(env/memory 不落盘+redact) + SettingsStore typed + NoopLspBridge |
公共 API 经 `src/index.ts` re-export(board-link/flash 具名避 shared/types 重名)。
## 测试
```bash
npm test # vitest 全量单测(39 文件 2449 passed,mock ExecFn,无需硬件)
npm test # vitest 全量(62 文件 3018 passed / 5 skipped,mock ExecFn + 6 量化 eval,无需硬件)
npx tsc --noEmit # 对真 pi 源码类型检查(0 错)
npx vitest run tests/system-integration.test.ts # 跨 10 模块闭环集成测试
npx vitest run tests/system-integration.test.ts # 跨模块闭环集成
npx vitest run tests/e2e-runtime.test.ts # 真 pi services 路径 boot 冒烟
npx vitest run tests/eval/ # 6 个实验室级量化评估
```
测试方法论:等价类划分 / 边界值 / 决策表 / 状态转换 / **变异测试(每模块植入 3-9 seeded bug 必被杀)** / 对抗 fuzz / 元蜕变不变式。T06–T17 由 68 个 workflow agent 并行开发(dev+test+fix≤3 每,两层+barrier)。
测试方法论:等价类/边界值/决策表/状态转换/变异测试(每模块植入 seeded bug 必被杀)/对抗 fuzz/元蜕变不变式 + **实验室级量化评估**(seeded mulberry32 + N=200-400 受控队列 + Wilson 95% CI + 真 manager 与对照实现全等对齐 + 预注册阈值)。每层 + 跨层都证明"有效 + 安全"(ΔJ 阈值 + 构造铁律)。
## 设计取舍
- **逻辑/扩展分离 + 测试前置**:纯逻辑内联进扩展/核心库文件并以命名导出,注入 mock `ExecFn` 单测,无需真实硬件即可严谨验证。这是 pi 自家 `coding-agent` 的同款分层。
- **单一 barrel 装配**:pi 只加载 `src/extensions/index.ts` 一个扩展,它依次装配 22 个子扩展——最大化内聚,避免散装。核心库层(T06–T17)是纯逻辑库,由 agent 层(`src/agent.ts`)按需 import,不进 barrel。
- **fail-closed**:硬件判据默认拒绝/失败,不放过任何破坏性或不确定操作(devmem 硬门、approval auto-deny、registry resolve 未知即抛)。
- **逻辑/扩展分离 + 测试前置**:纯逻辑内联进扩展/核心库文件并以命名导出,注入 mock `ExecFn` 单测,无需真实硬件即可严谨验证(pi 自家分层同款)。
- **单一 barrel 装配**:pi 只加载 `src/extensions/index.ts`,依次装配 28 工厂——最大化内聚。核心库层由 `src/agent.ts` 按需 import,不进 barrel。
- **fail-closed + 构造铁律**:硬件判据默认拒绝/失败;砖板率=0、forbidden 命门永不自改、risk 不增、§4.6 不对称——全是构造不变式,不是阈值。
- **自进化可信(trustworthy)**:难点不在"让它进化"而在"让进化 trustworthy"——F1–F6 失败模式(plateau/弱 verifier/误差累积/记忆≠进化/分布漂移/不可逆误用)显式工程化对策 + 负控队列实证。
- **密钥铁律**:网关 key 一律 `${DROBOTICS_LLM_KEY}` 环境占位,绝不硬编码、不入库(`grep -rn sk-nAm src/` = 0)。
## 已知局限
## 里程碑
- `length-recovery` 的 `partitionToolCalls` 需 patch pi agent-loop 源码(pi 扩展 API 够不着),本扩展只做 prompt 注入兜底 + events 握手。
- 真板硬件侧集成(烧录/外设/物理信号)逻辑已单测,真 aarch64 板上端到端待跑。
- T06–T17 核心库目前是纯逻辑库(已 1400+ 测试 + 系统集成测试验证接线),接进 pi agent 主循环(before_agent_start 调 assertModelVisibleLogged、session_before_compact 接 T09 等)是下一阶段集成工程,非阻塞。
- T05b aarch64 真二进制需 toolchain 编译(源码+契约已就绪)。
- **M0** v3 P0 底座(22 域 + 命门根治)✅ —— 真 pi+真 glm-5.2+真 RDK X5 端到端严验。
- **M1–M3** v3 P1+P2 核心库(T06–T17)✅ —— 39 文件 2449 passed。
- **M1** L1 硬件经验库 ✅ · **M2** L2 技能注册表 ✅ · **M3** L3 工具生长 ✅ · **M4** L4 编排进化 ✅ · **M5** L5 脚手架自改 ✅ · **X.1+X.3** 跨层反馈全链路 ✅ · **X.4** 进化可观测面板 ✅。
- **当前**:全量 62 文件 3018 passed / tsc 0 / sk- 0 / 真 pi T01 boot 过。pba = "L1-L5 全栈自进化 + 跨层闭环嵌入式 Agent"。
## 诚实边界(M1-M5.\* 跟进,非缺陷)
- 6 个量化评估为忠实 §4.2/§9 mock 策略受控实验,证**机制与机器的因果效应**;**未**测真 glm-5.2 经 pi 真读注入包后真受益的 live-LLM 端到端门(前序 fail2ban 等环境阻塞)。
- `derive*` 真接线已落地(feedback-bank 共享 collector + 4 bank 生产自驱读 `lastFinalized`),但真 LLM 摘要钩子(更高质蒸馏)= M1-M5.\*。
- stage-wise 真 θ 更新(L5 真权重)= M5.\*;当前 L5 是数据模型 + §11.4 门(真 git worktree + 真 vm 沙箱 execute + 真 CI 不变式执行 = M5.\*)。
- 跨 session 持久化默认 in-memory;sqlite 后端为可注入扩展点。
- `length-recovery` 的 `partitionToolCalls` 需 patch pi agent-loop 源码,本扩展只做 prompt 注入兜底 + events 握手。

346
架构设计文档_v4.md Normal file
View File

@ -0,0 +1,346 @@
# 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`/`register`infoGain 守卫/`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。