d-robotics 74f4cd428e
Some checks are pending
CI / quality-gate (push) Waiting to run
CI / type-drift (push) Waiting to run
feat(跨层 X.1+X.3+X.4): 反馈采集全链路 + 可观测面板 + 量化坐实 (M1-M5+X 全闭环)
跨层共享项落地(设计文档 §19.4 X.1/X.3/X.4):

X.1 时序三档接线 + X.3 v_t 全链路贯通:
- shared/types.ts: TaskFeedback/ToolOutcome/EvolutionMetrics/MetricsSources
  + hitRate/avgInfoGain/avgSkillQuality/maxWorkflowRisk/evolutionBrickRate 纯函数
- core/feedback-collector.ts: FeedbackCollector(recordPrompt/recordBoardFingerprint/
  recordToolResult/finalize/lastFinalized/pending/clear) + derive* 纯变换
  (deriveTaskSignature/deriveDistillInput/deriveSkillExtractInput/deriveSkillQuery/
  derivePriorCorrection/deriveProposals + inferOutcome/inferActionClass/
  inferValidatedBy/isIrreversibleTool) + getSharedCollector/initSharedCollector 共享单例
- extensions/feedback-bank.ts: hooks tool_result+message_end+before_agent_start
  → 采集 → finalize → session_before_compact 喂 derive* + feedback_recall 工具
  (仿 orchestration-bank/skill-bank 范式)
- **4 bank 默认 derive* 读共享 collector lastFinalized 生产自驱**
  (experience/skill/orchestration/variant bank) — X.1+X.3 生产闭环

X.4 进化可观测面板:
- core/evolution-metrics.ts: aggregateMetrics/renderMetrics 纯函数
  (5 层注册表聚合 → EvolutionMetrics:规模/命中率/infoGain/risk/砖板率/forbidden 拒绝)
- bin/evolution-metrics.ts CLI(brickRate!=0 时 exit 1 fail-closed 自检)

X.1+X.3 全链路评估(tests/eval/feedback-chain-eval.test.ts, 合成 session 轨迹→
feedback-bank hooks→collector→derive*→真 5 层 manager→断 v_t 全链路 end-to-end):
  §4.6 分级正确率 8/8=100% (success+ground-truth/可逆/不可逆/partial/empty/mixed)
  同签名检索命中 100% + 注入块可见 100%
  5 链 end-to-end (skill/workflow/variant/tool-growth)
  forbidden §11.3/§4.8 拒绝 (命门 safety-gate/flash 工具)

X.4 评估(tests/eval/evolution-metrics-eval.test.ts, 合成 5 层注册表→精确指标):
  experienceHitRate=0.600/avgInfoGain=0.650/maxRisk=1 精确
  brickRate=0 EXACT 构造铁律 forbiddenRejected=7 精确

结论: X.1(4/5 时序钩子全接, stage-wise θ=L5.*) + X.3(v_t 全链路贯通: tool_result
采集→derive* 蒸馏→5 层入库→检索→注入→约束, §4.6 100% + 5 链 end-to-end + 4 bank
生产自驱) + X.4(可观测面板精确指标, brickRate=0 构造铁律) 全部完成。诚实边界
(M1-M5.* 跟进): live-LLM 读注入包真受益端到端门 + stage-wise 真 θ 更新 + 真 git
worktree 变体 + 真 CI §11.4 执行 = M1-M5.* 工程项(机制层全闭环+量化坐实)。

验证: tsc 0 / 全量 62 文件 3018 passed 5 skipped / sk- 明文 0 / 真 pi T01 boot
过(barrel 28 扩展含 L1-L5 + 跨层反馈采集)
多 Agent 并行: K(feedback-collector+derive*)+L(feedback-bank+chain eval)+M(evolution-metrics)

Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-17 17:32:37 +08:00

@d-robotics/physical-byte-agent

基于 pi 二开的嵌入式开发 Agent,默认模型 glm-5.2(经 d-robotics 内部网关)。

定位:在 pi 这个极简 agent harness 之上,加一层嵌入式开发场景必需的能力——持久 shell、PDF/datasheet 读取、硬件安全门、交叉编译、安全烧录、外设探测、JTAG 调试、设备树、板链路、物理信号验证、闭环编排——并根治 pi + glm-5.2 组合的两个独家命门。

两个命门

命门 现象 根治点
一·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 形式

21 个域扩展

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

每个扩展文件 = pi glue(export default (pi) => {...})+ 纯逻辑命名导出(供单测)。详见 Docs/F01-F21。

用法

# 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)
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();

核心库层(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 重名)。

测试

npm test            # vitest 全量单测(39 文件 2449 passed,mock ExecFn,无需硬件)
npx tsc --noEmit    # 对真 pi 源码类型检查(0 错)
npx vitest run tests/system-integration.test.ts   # 跨 10 模块闭环集成测试

测试方法论:等价类划分 / 边界值 / 决策表 / 状态转换 / 变异测试(每模块植入 3-9 seeded bug 必被杀) / 对抗 fuzz / 元蜕变不变式。T06–T17 由 68 个 workflow agent 并行开发(dev+test+fix≤3 每,两层+barrier)。

设计取舍

  • 逻辑/扩展分离 + 测试前置:纯逻辑内联进扩展/核心库文件并以命名导出,注入 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 未知即抛)。
  • 密钥铁律:网关 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 编译(源码+契约已就绪)。
Description
No description provided
Readme 1.5 MiB
Languages
TypeScript 98%
JavaScript 1.7%
C 0.3%