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

8.0 KiB
Raw Permalink Blame History

@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 握手。