diff --git a/README.md b/README.md index 12e0a51..3c83490 100644 --- a/README.md +++ b/README.md @@ -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 握手。 diff --git a/架构设计文档_v4.md b/架构设计文档_v4.md new file mode 100644 index 0000000..2f2426d --- /dev/null +++ b/架构设计文档_v4.md @@ -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 + → skill-bank: deriveSkillQuery → resolve → inject + → orchestration-bank: deriveTaskQuery → estimateDifficulty + selectWorkflow → inject + → variant-bank: inject (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 + 注入 ``(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` 检索技能 + 注入 `` + `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`。 +- **铁律**:forbidden(flash/erase/fuse/devmem/write)永不自创;升级门 usage` + `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` 工具 + 注入 `` + `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。