架构设计文档_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>
@d-robotics/physical-byte-agent
基于 pi 二开的嵌入式开发 Agent + 全栈自进化闭环,默认模型 glm-5.2(经 d-robotics 内部网关)。
定位:在 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 分支(真模型实测 usage.reasoning=0) |
| 二·hex 强转 | glm-5.2 把寄存器地址 0x40020000 强转成十进制 "1073872896",下游写错地址即砖板 |
glm-provider.ts normalizeHexArg() / makeHexNormalizingPrepareArguments():reg 工具 prepareArguments 把十进制还原 0x(真模型实测 1073872896→0x40020000) |
28 个域扩展(barrel 工厂)
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
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 条)。
用法
# 1. 装 pi(已 clone 到 ../pi)
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,28 工厂)
cd ../physical-byte-agent
npx tsx bin/pba.ts # 或 pi --agent-dir .
# 4. 程序化
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 自检)
测试
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 # 跨模块闭环集成
npx vitest run tests/e2e-runtime.test.ts # 真 pi services 路径 boot 冒烟
npx vitest run tests/eval/ # 6 个实验室级量化评估
测试方法论:等价类/边界值/决策表/状态转换/变异测试(每模块植入 seeded bug 必被杀)/对抗 fuzz/元蜕变不变式 + 实验室级量化评估(seeded mulberry32 + N=200-400 受控队列 + Wilson 95% CI + 真 manager 与对照实现全等对齐 + 预注册阈值)。每层 + 跨层都证明"有效 + 安全"(ΔJ 阈值 + 构造铁律)。
设计取舍
- 逻辑/扩展分离 + 测试前置:纯逻辑内联进扩展/核心库文件并以命名导出,注入 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)。
里程碑
- 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 握手。