d-robotics 68d8567ad9
Some checks are pending
CI / quality-gate (push) Waiting to run
CI / type-drift (push) Waiting to run
docs(v3): 进度表同步 — T06–T17 全 ✅,M1/M2/M3 全落
P1+P2 12 模块开发完成后的文档对齐(doc-sync 精神):
- 进度表 T06–T17 ⏳ → ✅,各填落地说明 + 测试数
- 里程碑 M1 可长跑 / M2 可维护 / M3 可扩展 全 ✅
- 头部进度行更新至 2449 单测全绿

Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-14 15:39:29 +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();

测试

npm test            # vitest 全量单测(mock ExecFn,无需硬件)
npx tsc --noEmit    # 对真 pi 源码类型检查

设计取舍

  • 逻辑/扩展分离 + 测试前置:纯逻辑内联进扩展文件并以命名导出,注入 mock ExecFn 单测,无需真实硬件即可严谨验证。这是 pi 自家 coding-agent 的同款分层。
  • 单一 barrel 装配:pi 只加载 src/extensions/index.ts 一个扩展,它依次装配 21 个子扩展——最大化内聚,避免散装。
  • fail-closed:硬件判据默认拒绝/失败,不放过任何破坏性或不确定操作。

已知局限

  • length-recovery 的 partitionToolCalls 需 patch pi agent-loop 源码(pi 扩展 API 够不着),本扩展只做 prompt 注入兜底 + events 握手。
  • 真板硬件侧集成(烧录/外设/物理信号)逻辑已单测,真 aarch64 板上端到端待跑。
Description
No description provided
Readme 1.5 MiB
Languages
TypeScript 98%
JavaScript 1.7%
C 0.3%