- 工程形态:@d-robotics/physical-byte-agent npm 库包
- 单一 barrel src/extensions/index.ts 装配 21 域扩展(package.json pi.extensions 清单 + .pi/extensions/index.ts 重导出,pi 自动加载)
- src/agent.ts PhysicalByteAgent(launch() 程序化调 createAgentSession + verifyAssembly() 离线自检)
- bin/pba.ts CLI、models.json(glm-5.2 条目)、README.md、AGENTS.md
- 命名:全部域命名(glm-provider/safety-gate/flash/jtag-debugger/loop-orchestrator…),去掉 F 编号
- 架构:内联逻辑 + 顶层仅 import type(esbuild 擦除)+ 工厂内动态 import defineTool/Type
- 逻辑离线可单测(不解析 pi),工厂在真 pi 内装配;fail-closed 语义保留
- 两命门:glm-provider.ts buildGlmModelConfig()(thinkingFormat:qwen + maxTokens:8192 + thinkingLevelMap 全 null)+ detectEmptyOutput();normalizeHexArg() + makeHexNormalizingPrepareArguments()
- 验证:tsc --noEmit 0 错(对 src/types/pi.d.ts 类型镜像)+ vitest 732 用例/21 文件全绿 + tsx 离线装配冒烟 21 扩展全就位
- 密钥铁律:grep sk-nAm 在 src/tests/bin/.pi = 0,key 全程 ${DROBOTICS_LLM_KEY} 占位
Co-Authored-By: Claude <noreply@anthropic.com>
46 KiB
pi + glm-5.2 在嵌入式开发场景的不足与缺陷分析
研究对象:pi(
earendil-works/piv0.84.1,源码/Users/d-robotics/Desktop/pi)+ glm-5.2(智谱 GLM-5.2,经内部网关https://ai-api.d-robotics.cc/v1,模型 id 实测为glm-5.2) 场景:嵌入式开发(交叉编译 / 烧录 / 外设驱动 / JTAG 在线调试 / 设备树 / datasheet 寄存器级编码 / 板上调测 / ROS·tros) 成文日期:2026-08-13 本文只做一件事:把问题钉死。每条结论均有源码坐标(file:line)或真实 API 响应作证,不臆测、不给修复方案。修复方案留下一步"对 pi 框架二开"时单独成文。
0. 文档定位、方法与边界
0.1 为什么先只写问题
"问题已经解决了一半"——把问题描述清楚本身就是进展。本文止于"问题描述",下一阶段(pi 二开优化)才进入"怎么改"。两类内容物理隔离,避免在没钉清问题前就跳进方案、把方案当结论。
0.2 方法:三路并发研究 + 主 agent 交叉对齐
| 路 | 职责 | 产出 | 证据形态 |
|---|---|---|---|
| A 路 | pi v0.84.1 源码实证其在嵌入式场景的框架层缺陷 | 15 条缺陷 | 全部带 packages/.../*.ts:行号 源码坐标;并核对了原 pi 调研报告 4 处出入 |
| B 路 | 走网关对 glm-5.2 真实 API 探针 | 8 项探针 + 能力画像表 | 全部带真实 HTTP 响应字段(finish_reason / token 计数 / tool_calls 内容) |
| C 路 | 嵌入式开发域对一个 code agent 的真实需求基线 | 10 维需求 + 7 条本质差异 + 堪用能力清单 | 带可查工程来源(kernel.org / cmake.org / openocd.org / elixir.bootlin.com / docs.ros.org) |
主 agent(本文)把三路交叉对齐:pi 能力 + glm-5.2 能力 + 嵌入式需求 → 三者 gap 即缺陷。
0.3 三层归因模型
每条缺陷标归因层,便于下一步二开时分配着力点:
- 【pi 框架层】:缺陷在 pi 本身的架构/工具/会话/扩展设计里,二开 pi 可解
- 【glm-5.2 模型层】:缺陷在模型的 token 行为/格式输出/数值转换里,二开 pi 只能"绕"不能"治"
- 【域知识缺口】:缺陷在"通用 agent 缺嵌入式领域知识"里,靠 RAG/skill/AGENTS.md 补,非框架二开
0.4 实证边界(诚实声明)
- 已实证确定:A 路全部 15 条(源码可查)、B 路全部 8 项探针(真实响应可复现)、C 路工程事实(公开文档可查)
- 网关 key 不入库:本文全程不出现真实 key 字符串,仅以环境变量
${DROBOTICS_LLM_KEY}占位;B 路探针在 bash 进程内用 env 传入,未落盘任何含 key 文件 - 未覆盖:pi 在 aarch64 目标板上原生运行的内存/CPU 实测(需上板);glm-5.2 在 60k+ token 输入下的延迟实测;pi-ai
compat层对接 glm-5.2 的端到端跑通(B 路只测了网关直连,未走 pi-ai 适配链)
1. 嵌入式开发对 code agent 的硬需求基线(浓缩自 C 路)
1.1 十维需求与真实工具
| # | 维度 | 典型工具/命令/文件 | agent 难点 |
|---|---|---|---|
| 1 | 交叉编译工具链 | aarch64-linux-gnu-gcc、arm-none-eabi-gcc、CMake CMAKE_TOOLCHAIN_FILE、--sysroot |
默认用宿主 gcc 编,产物跑不了;要自觉选三元组 + sysroot |
| 2 | 烧录与镜像 | dd of=/dev/mmcblk0、fastboot flash、dfu-util、openocd -c "program" |
破坏性不可逆,烧错盘=砖板,需物理恢复 |
| 3 | 外设驱动 | i2c-tools、spidev、/dev/ttyS*+termios、libgpiod(/dev/gpiochipN)、/sys/class/pwm |
查 datasheet 寄存器映射、位域操作、时序、I2C 7/8 位歧义、SPI 4 mode |
| 4 | 在线调试 | OpenOCD + gdb-multiarch target remote :3333、hbreak/watch/x/wx 0x... |
gdb 是交互式长会话,状态跨多步保持 |
| 5 | 设备树 | DTS/DTSI、compatible/phandle/reg/interrupts、dtc、overlay .dtbo |
改错节点=外设静默不枚举,dmesg 无报错 |
| 6 | datasheet/register 精度 | SoC 参考手册(千页 PDF)、寄存器映射表、位域、复位值、时序图 | 上下文巨大 + 数值零容错,地址错一位=写错模块 |
| 7 | 构建系统 | buildroot、Yocto/Bitbake、CMake、Kconfig/defconfig | 配置矩阵大、一次构建几十分钟,不能频繁全量试错 |
| 8 | 板上调测 | ssh root@board dmesg、scp、minicom -D /dev/ttyUSB0、/proc/iomem、/proc/interrupts |
双机协作,状态分散在宿主+目标板 |
| 9 | 硬件闭环迭代 | 改码→交叉编译→scp/烧→上板→看 dmesg/示波器→再改 | 单板串行、每轮分钟级、烧坏物理恢复 |
| 10 | ROS/tros | ros2 topic echo/hz、launch.py、rqt_graph、DDS QoS、tros hobot_dnn |
分布式多节点,故障跨节点,QoS 不匹配静默不连 |
1.2 嵌入式开发 vs 普通 web/后端开发的七条本质差异
- 输出是物理硬件行为,不是 stdout——验证靠 LED/电机/示波器/dmesg 枚举,不是单元测试断言
- 错误代价是砖板/硬件损坏,不是重启服务——烧错 bootloader 要拆芯片 SPI 编程器离线恢复
- 双机工具链,状态跨宿主-目标分散——宿主编译、scp 到板、板上跑、日志回看
- 数值精度零容错——寄存器地址/位偏移错一位静默写错模块,写 MMIO 从不抛异常
- 长反馈回路 + 单板串行——每轮分钟级不可并行,试错代价大,一次对率要求高
- 硬件异构强绑型号——STM32F4 vs F7、X5 vs S100 引脚/时钟树/寄存器映射全不同,泛化即出错
- 领域知识靠 datasheet+设备树+内核源码——精确寄存器定义藏在千页 PDF 和
include/linux/里,不在 npm/Stack Overflow
1.3 通用 code agent 开箱覆盖度(C 路结论)
10 项堪用能力里,通用 code agent(含 pi)开箱集中在"部分"档——懂语法概念,但五项明显偏弱:交叉工具链自觉选用、破坏性命令防护、寄存器级零容错查证、长会话有状态调试、物理信号判读。这五项恰是嵌入式命门。
以上是基线。下文每条缺陷都对照"它砸在这五项里的哪一项"。
2. 缺陷总表(21 条,按严重度)
| # | 标题 | 归因层 | 严重度 | 砸的命门 |
|---|---|---|---|---|
| 1 | bash 每命令新进程 → gdb/OpenOCD/minicom 交互式长会话不可用 | pi 框架 | 🔴高 | 长会话有状态调试 |
| 2 | read 头部截断 2000 行/50KB + 零 PDF → datasheet 不可读 | pi 框架 | 🔴高 | 寄存器级查证 |
| 3 | 无运行时权限门 → dd/rm-sys/reboot 破坏性命令零拦截 | pi 框架 | 🔴高 | 破坏性命令防护 |
| 4 | session 纯文本 JSONL + bash 新进程 → 零硬件状态/外设会话持久化 | pi 框架 | 🔴高 | 长会话有状态调试 |
| 5 | 扩展 jiti 主进程零隔离 → 硬件操作扩展崩带崩整个 agent | pi 框架 | 🔴高 | 破坏性命令防护 |
| 6 | AgentHarness 全 HarnessNotImplemented + pi-server 无生产实现 → 服务化/批量 eval/durable runtime 空壳 | pi 框架 | 🔴高 | 长反馈回路 |
| 7 | 命门一:thinking 默认开启 = token 黑洞,max_tokens=2048 时零输出 | glm-5.2 | 🔴高 | 一次对率 |
| 8 | 命门二:hex→decimal 强转,tool arg 寄存器地址变十进制,砖板风险 | glm-5.2 | 🔴高 | 数值精度零容错 |
| 9 | edit fuzzy 匹配 → .dts/.ld 误匹配 + 归一化破坏对齐空白 | pi 框架 | 🟠中 | 寄存器级查证 |
| 10 | 无 MCP → 板卡画像/仪器生态零复用 | pi 框架 | 🟠中 | 物理信号判读 |
| 11 | 工具并行默认开启 → 串口/JTAG/flash 共享硬件并发撞车 | pi 框架 | 🟠中 | 长反馈回路 |
| 12 | stopReason==="length" 整批拒执行 → 长上下文工具调用全否 | pi 框架 | 🟠中 | 长反馈回路 |
| 13 | system prompt 无 env/toolchain 注入 → 交叉编译环境靠 AGENTS.md 手写 | pi 框架 | 🟠中 | 交叉工具链自觉 |
| 14 | compaction 视图截断 → 寄存器值/调试状态被摘要掉 | pi 框架 | 🟠中 | 长会话有状态调试 |
| 15 | reasoning 占 25–72% completion token → 长代码生成成本高且易截断 | glm-5.2 | 🟠中 | 一次对率 |
| 16 | thinkingFormat 误配风险 → OpenAI thinking:{type} 无效,需 enable_thinking:false |
glm-5.2 | 🟠中 | 一次对率 |
| 17 | 模糊枚举值不稳定 → "50MHz"→speed 档波动 | glm-5.2 | 🟠中 | 数值精度零容错 |
| 18 | max_tokens 不足时连"不存在"都答不出 → SPI7 在 2048 时空输出 | glm-5.2 | 🟠中 | 寄存器级查证 |
| 19 | skills allowed-tools 字段纯摆设 → 源码零解析 |
pi 框架 | 🟡低 | 破坏性命令防护 |
| 20 | pi-server locked 恒 true + 协议层无认证 → session 锁状态假报/裸奔 |
pi 框架 | 🟡低 | 破坏性命令防护 |
| 21 | 模型 id 别名混淆 → 用户写 glm5.2 不通,真实是 glm-5.2 |
网关/模型 | 🟡低 | — |
共 21 条:🔴高 8 条、🟠中 10 条、🟡低 3 条。归因层分布:pi 框架层 13 条、glm-5.2 模型层 7 条、网关层 1 条。
3. 致命级缺陷详述(🔴 高,直接阻断嵌入式闭环)
缺陷 1:bash 每命令新进程,非持久 shell — 交互式工具链会话不可用
- 归因层:【pi 框架】|严重度:🔴高
- 现象:agent 发 gdb / openocd / minicom 命令时,每次调用 spawn 一个新子进程,上一次的断点、加载的 ELF、连接的 JTAG target、串口会话全丢。
- 实证证据:
bash.ts:103用spawn()起新子进程;:105detached: process.platform !== "win32";终止时shell.ts:213-215对整个进程组发SIGKILL。cd/export不跨调用保留——每调用独立 spawn,无 shell 状态持久化机制。 - 嵌入式后果:嵌入式闭环(改码→交叉编译→烧→上板→gdb 调→再改)核心断链点。
arm-none-eabi-gdb是交互式长会话(load/break/continue/step 必须在同一 gdb 进程内连续执行),openocd -f interface.cfg需常驻后台做 JTAG 桥接,minicom/picocom需串口交互。pi 下:agent 每发一条 gdb 命令就 spawn 新 gdb,断点/ELF/target 全丢;常驻 openocd 在命令结束被 SIGKILL,下一条 gdb 命令找不到 OpenOCD 服务。 - BashOperations 接口(
bash.ts:62-80)+user_bash事件(types.ts:1083-1088)允许替换执行后端,但持久 shell(tmux/expect 会话池)等于重写 bash 执行模型。
缺陷 2:read 工具头部截断 2000 行/50KB + 零 PDF — datasheet/巨型寄存器头文件不可读
- 归因层:【pi 框架】|严重度:🔴高
- 现象:agent 直接读 datasheet PDF 不可读;读巨型
.h寄存器定义只能看前 2000 行。 - 实证证据:
truncate.ts:11-12DEFAULT_MAX_LINES=2000/DEFAULT_MAX_BYTES=50KB;truncate.ts:78truncateHead用于 read。read.ts:295-300首行超 50KB 直接返回空内容 + sed fallback 指令。read.ts:250detectImageMimeType只支持 jpg/png/gif/webp/bmp——mime.ts和read.ts全局无任何 PDF 处理。 - 嵌入式后果:SoC datasheet 通常 3000–8000 页 PDF,寄存器定义头文件(CMSIS Device Header)动辄 5000+ 行。read 对 PDF 零支持 = agent 无法直接查寄存器偏移;对巨型
.h只能看前 2000 行,需多轮 offset/limit 分页续读,每轮吃一个 tool call + 上下文 token。首行超 50KB 的单行 minified 文件直接不可读。对照 C 路命门"寄存器级零容错查证"——查不到就靠记忆,靠记忆就幻觉,幻觉就写错寄存器。
缺陷 3:无运行时权限门 — dd 烧盘 / rm -rf /sys / reboot 等破坏性命令零拦截
- 归因层:【pi 框架】|严重度:🔴高
- 现象:agent 若(被 prompt injection 或自身推理错误)发出
dd of=/dev/sda或reboot,pi 直接执行,无任何运行时审批。 - 实证证据:
SECURITY.md:50明确"the Pi coding agent intentionally does not have a sandbox"。唯一门是加载期 project trust(未信任项目不加载.pi/资源)。agent-session.ts中 greppermission/allow/deny零命中。tool_call钩子可 block + terminate(agent-session.ts:486-499→agent-loop.ts:636-646),且 fail-closed(handler 抛错→工具不执行,:493-498、:661-667),但这是扩展能力,非内置规则表。 - 嵌入式后果:
dd if=sdcard.img of=/dev/mmcblk0烧错盘号毁掉宿主系统盘;rm -rf /sys/class/gpio/*破坏内核 GPIO 状态;reboot/init 6断板。门没建好前完全裸奔。tool_call钩子能做 fail-closed 硬件安全门(这是 pi 的优势点),但不是开箱即有——需自建门。
缺陷 4:session 纯文本 JSONL + bash 新进程 — 零硬件状态/外设会话状态持久化
- 归因层:【pi 框架】|严重度:🔴高
- 现象:嵌入式闭环中的有状态资源(已开 gdb session 的断点列表、已占用的 i2c 总线地址、已配置的 GPIO 方向、OpenOCD 连接状态、串口波特率)在 pi 里无处存。
- 实证证据:
session-manager.ts:845-847session 是单文件 JSONL 追加树;entry 类型(:53-144)有 SessionMessageEntry / ThinkingLevelChangeEntry / ModelChangeEntry / CompactionEntry / BranchSummaryEntry / CustomEntry / LabelEntry / SessionInfoEntry / CustomMessageEntry——无任何"硬件状态/外设会话/总线占用"类型。CustomEntry(:104-108)可存任意数据但不参与 LLM 上下文(:101-102)。 - 嵌入式后果:每轮 bash 新进程(缺陷 1)意味着 gdb 断点丢、i2c 总线释放、GPIO 方向复位。agent 要么每次重新初始化(吃大量 tool call),要么靠对话上下文文本推断状态(不可靠,compaction 后可能被摘要掉,见缺陷 14)。即便 session 里记了 gdb 断点列表,下次 bash 调用也无法发给同一 gdb 进程(缺陷 1 与 4 耦合)。
缺陷 5:扩展 jiti 主进程零隔离 — 嵌入式硬件操作扩展崩溃带崩整个 agent
- 归因层:【pi 框架】|严重度:🔴高
- 现象:操作 GPIO/i2c/USB 仪器的扩展一旦段错误或资源泄漏,直接带崩整个 pi 进程——session、未落盘上下文、所有扩展全死。
- 实证证据:
loader.ts:455扩展加载通过jiti.import(extensionPath)在主进程内直接执行。无 worker thread、无子进程隔离、无沙箱。文档原话"Extensions run with your full system permissions"。 - 嵌入式后果:嵌入式扩展比纯 JS 文件操作更容易崩——
i2c-dev的 ioctl 参数错误致 SIGSEGV、GPIO mmap 后忘 unmap 致资源泄漏、USB 仪器 libusb 调用异常。这些原生 FFI/内核驱动交互一旦崩,主进程即死。对照 Claude Code 的 hook 是子进程 stdio,崩溃不影响主进程。这是框架层设计,无解于扩展层——只能把硬件操作外包到独立守护进程 + IPC 缓解(自建隔离层)。
缺陷 6:AgentHarness 全 HarnessNotImplemented + pi-server 无生产实现 — 服务化/批量 eval/durable runtime 空壳
- 归因层:【pi 框架】|严重度:🔴高
- 现象:想把 agent loop 跑在目标板上或做 eval 批量跑题(多 session 并发管理),durable runtime 是空壳。
- 实证证据:
AgentHarness(agent-harness.ts:305)实现AgentLane接口,但除getModel/setModel/getActiveTools/setActiveTools/getThinkingLevel/setThinkingLevel纯 getter/setter 外,所有操作方法(prompt/compact/navigateTree/resume/abort/steer/followUp/watch/createLane)全走this.unavailable()(:355-356)返回HarnessNotImplemented;create在有历史 record 时也抛(:351);hooks/events 用UnavailableRegistry(:326-327)on()直接 throw。pi-server 侧:PiServerService是纯接口(server/src/types.ts:55-60,4 方法),server 包内无任何 concrete 实现;PiServer(server.ts:39)接收外部 service 但无默认实现。 - 嵌入式后果:eval 平台批量跑 HWE-Bench 题需多会话服务化——每题一 session,RPC 驱动 prompt/abort/get_state。AgentHarness 是这些能力的接口骨架但实现全空。进程内
agentLoop(agent-loop.ts:155)可用但不是服务化底座。注:原 pi 调研报告说"每个方法都抛",A 路源码核实纠正为"操作方法抛,纯 getter/setter 不抛"——结论不变(durable runtime 不可用)。
缺陷 7:命门一 — thinking 默认开启 = token 黑洞,max_tokens=2048 时零输出
- 归因层:【glm-5.2 模型】|严重度:🔴高
- 现象:pi-ai 若用默认参数(max_tokens=2048)跑嵌入式代码生成任务,glm-5.2 会静默返回空字符串。
- 实证证据(B 路真实 API 响应四组对比):
| 场景 | finish_reason | content 长度 | completion_tokens | reasoning_tokens |
|---|---|---|---|---|
| 不设 max_tokens(GPIO 配置题) | stop | 2850 chars | 2996 | 2157(72%) |
| max_tokens=8192(Linux 驱动题) | stop | 12001 chars | 4757 | 1181(25%) |
| max_tokens=2048(I2C 驱动题,thinking ON) | length | 0 chars | 2049 | 2048(100%) |
| max_tokens=2048 + enable_thinking:false | length | 6895 chars(被截断) | 2048 | 0 |
- 嵌入式后果:这是最致命缺陷。写一个完整
.c驱动(通常 200–500 行 ≈ 3–8K token)必须max_tokens≥8192且关 thinking,否则要么零输出要么截断。pi-ai 默认 max_tokens 若是 2048,agent 这一轮发完所有 tool call 后会收到空 assistant message——而缺陷 12 会把这种 length 状态放大成"整批 tool call 全拒执行",闭环直接卡死。 - 关键纠错:memory 记录"glm-5.2 须 max_tokens2048+discard 放宽"被 B 路实证推翻——2048 在默认 thinking 模式下产出为零,不是"放宽"能解决的。
缺陷 8:命门二 — hex→decimal 强转,tool arg 寄存器地址变十进制,砖板风险
- 归因层:【glm-5.2 模型】|严重度:🔴高
- 现象:即便 tool description 明确写"address MUST be a hex string like 0x40020000",glm-5.2 仍把 hex 地址转成十进制字符串塞进 tool arg。
- 实证证据(B 路真实响应):
read_register(0x40020000)→ arg{"address": "1073872896", ...};0x48000004→"1207959556"。三次复现一致(系统性,非偶发)。模型同时正确支持原生 tool_calls(finish_reason:"tool_calls")和 parallel tool calls(单响应 2 个 tool_calls,index 0+1)。 - 嵌入式后果:嵌入式里寄存器地址错一位=写错硬件模块。若 pi-ai 的 tool handler 用
int(addr, 16)解析"1073872896",得到0x1073872896(完全错误地址,可能砖板);用int(addr, 0)可自适配但依赖 handler 实现正确。对照 C 路命门"数值精度零容错"——这正好砸在最痛处:模型协议层(tool_call 合法)看似正常,但参数语义已被悄悄改写,下游稍有不慎即砖板。
4. 严重级缺陷详述(🟠 中,显著劣化或潜在砖板)
缺陷 9:edit 的 fuzzy 匹配在 .dts/.ld 上误匹配 + 归一化破坏对齐空白
- 归因层:【pi 框架】|现象:设备树/链接脚本节点结构高度重复,agent 给的 oldText 不够长时 fuzzy 易错配;fuzzy 匹配返回归一化 content,未改行也被重写(尾部空白 strip、Unicode 替换),破坏 .dts/.ld 对齐空白。
- 实证证据:
edit-diff.ts:208先精确indexOf,:219-222失败后 fuzzy;:27-51normalizeForFuzzyMatch做 NFKC + 尾部空白 strip + Unicode 破折号/连字符/特殊空格归一;:237-243返回归一化 content 做替换。 - 嵌入式后果:
.dts里&i2c0{...}/&i2c1{...}结构重复,.ld里.text/.text.init/.text.startup段名相似。oldText 不足时 NFKC+尾部 strip 可能让匹配&i2c1的 oldText 错配到&i2c0归一化内容——改错节点=外设静默不枚举。
缺陷 10:无 MCP — 板卡画像/仪器生态零复用
- 归因层:【pi 框架】|现象:MCP 生态有现成的 i2c scanner、SPI flash reader、GPIO sysfs、示波器/逻辑分析仪/万用表 MCP server,pi 全用不上。
- 实证证据:
packages/coding-agent/src/全局 grepmcp/MCP/ModelContextProtocol零命中。扩展通过registerTool()(types.ts:1251)注册 TS 函数,非 MCP 协议客户端。对比 opencode/Claude Code 原生支持 MCP。 - 嵌入式后果:每个嵌入式工具操作要从零写成 pi 扩展 TS 函数,无法复用 MCP server 生态。对照 C 路命门"物理信号判读"——仪器控制 MCP server 复用性归零。
缺陷 11:工具并行默认开启 — 串口/JTAG/flash 共享硬件并发撞车
- 归因层:【pi 框架】|现象:agent 一轮里并行发
st-flash write+arm-none-eabi-gdb -ex load+minicom -D /dev/ttyUSB0,三命令竞争同一串口/JTAG,至少一个失败。 - 实证证据:
agent.ts:237默认toolExecution = ... ?? "parallel";agent-loop.ts:489executeToolCallsParallel先串行 preflight 再Promise.all并发执行(:540);任一工具声明executionMode:"sequential"整批降级(:419-423)。 - 嵌入式后果:嵌入式命令多有隐式共享资源——同串口(
/dev/ttyUSB0不能同时被 minicom 和 st-flash 占)、同 JTAG 适配器(OpenOCD 和 gdb 不能同时独占)、同 flash(dd of=/dev/mmcblk0和mount /dev/mmcblk0p1不能并发)。模型无法预知这些共享。内置 bash 工具无executionMode属性,bash 并行不可从工具声明层控制。
缺陷 12:stopReason==="length" 整批拒执行 — 长上下文工具调用全否
- 归因层:【pi 框架】|现象:LLM 输出被 token 上限截断时,这一轮想发的所有 tool call 全被拒绝,agent 要重发一轮。
- 实证证据:
agent-loop.ts:211-214当stopReason === "length",整批 tool call 全标记错误不执行;failToolCallsFromTruncatedMessage(:381-406)给每个 tool call 返回 "was not executed: response hit output token limit, args may be truncated"。 - 嵌入式后果:嵌入式上下文极长(交叉编译 warning 海洋、datasheet 寄存器表、设备树全文、OpenOCD 配置)。一旦 stopReason=length,agent 这轮想同时 edit 源码 + bash 编译 + read 日志全被拒,重发一轮浪费 token 和时间。与缺陷 7 叠加放大:glm-5.2 默认 thinking 极易触发 length,而 length 会把整批 tool call 全否——闭环效率塌方。
缺陷 13:system prompt 无 env/toolchain 注入 — 交叉编译环境靠 AGENTS.md 手写
- 归因层:【pi 框架】|现象:目标板型号、交叉工具链版本、内核版本、ROS 发行版、dtc 版本这些直接影响编译命令的信息,pi 不注入,agent 每次自己 bash 探。
- 实证证据:
system-prompt.ts:28buildSystemPrompt含角色 + 工具 + guidelines + pi docs + AGENTS.md + skills 索引 + cwd(:121-138);grepgitStatus/date/kernel/uname/aarch64/arm-none/toolchain零命中。 - 嵌入式后果:RDK X5 vs S100 vs S600、arm-none-eabi-gcc 10.3 vs 12.2、内核 5.4 vs 6.1、humble vs tros、dtc 1.6 vs 1.7——这些决定编译命令/链接/API 选择。不注入 = agent 每轮
uname -a+arm-none-eabi-gcc --version+cat /proc/device-tree/model自探,吃 tool call。AGENTS.md 可手写但需人维护、不自动更新。对照 C 路命门"交叉工具链自觉选用"。
缺陷 14:compaction 视图截断 — 寄存器值/调试状态被摘要掉
- 归因层:【pi 框架】|现象:长嵌入式链路里关键寄存器值、外设初始化序列、调试观测的错误日志行可能落在 compaction 截断区间,LLM 看到的只是结构化摘要。
- 实证证据:compaction 是"视图截断"不丢原文(全文仍在 JSONL),但 LLM 上下文只看到摘要。
compaction/utils.ts:156SUMMARIZATION_SYSTEM_PROMPT产出固定结构(Goal/Constraints/Progress/Key Decisions/Next Steps/Critical Context)+ 保留<read-files>/<modified-files>累积清单;agent-harness.ts:340-342keepRecentTokens: 20000;切点绝不在 toolResult 上切。 - 嵌入式后果:嵌入式链路(改码→编译→烧→上板→gdb 调→再编)极长,上下文易超。关键值如
0x7D0 = 0x1F、i2cset -y 0 0x50 0x10 0x3F、调试观测的错误日志行可能被摘要掉。compaction 后 agent 可能忘记之前写了什么寄存器值,导致重复初始化或错误操作。摘要的 Critical Context 由 LLM 生成,不保证保留所有寄存器值。
缺陷 15:reasoning 占 25–72% completion token — 长代码生成成本高且易截断
- 归因层:【glm-5.2 模型】|现象:默认 thinking 模式下 reasoning 吃掉 25–72% completion token,长代码生成要么成本高(max_tokens≥8192)要么易截断。
- 实证证据:见缺陷 7 实证表——不设 max_tokens 时 reasoning 占 72%,max_tokens=8192 时占 25%。
- 嵌入式后果:写完整
.c驱动(3–8K token)必须max_tokens≥8192,每轮成本翻倍;若压 max_tokens 省 cost,则极易触发 length(缺陷 12)。嵌入式单板串行、每轮分钟级本就贵,token 成本叠加让闭环更慢更贵。
缺陷 16:thinkingFormat 误配风险 — OpenAI thinking:{type} 无效,需 enable_thinking:false
- 归因层:【glm-5.2 模型】(与 pi 框架 thinkingFormat 适配交叉)|现象:glm-5.2 的 thinking 是 GLM 原生
reasoning_content字段,不是 OpenAIthinking对象。若 pi-ai 误用thinking:{type:"disabled"},reasoning 不会被关闭,token 全被吃掉。 - 实证证据:
enable_thinking:false→content:'391', reasoning_content:'', completion_tokens:2(成功关);thinking:{type:"disabled"}→content:'', reasoning_content:'1. Analyze...'finish=length, reasoning_tokens=256(无效,reasoning 照开)。 - 嵌入式后果:pi-ai 的
thinkingFormat11 变体(types.ts:567-578:openai/openrouter/deepseek/together/baseten/zai/qwen/chat-template/qwen-chat-template/string-thinking/ant-ling)无 GLM 专属。openai-completions.ts:493流式响应搜reasoning_content/reasoning/reasoning_text三字段提取 thinking——glm-5.2 的reasoning_content可被命中,承载侧够。但关闭 reasoning 的正确参数是 GLM 私有布尔enable_thinking:false,不是 OpenAIthinking:{type:...}。pi-aicompat层(types.ts:542-582)+detectCompat()嗅探(按 baseUrl)能否正确给 glm-5.2 下发enable_thinking:false——待端到端实测(B 路只测了网关直连,未走 pi-ai 适配链)。若误配,缺陷 7 的 token 黑洞会全程存在。
缺陷 17:模糊枚举值不稳定 — "50MHz"→speed 档波动
- 归因层:【glm-5.2 模型】|现象:模糊输入的枚举值选择不稳定。
- 实证证据:同一
set_pin_configtool_call 请求(输入"50MHz")发 3 次:speed在"high"(run1/run3)和"very_high"(run2)间波动。JSON 格式 3/3 合法一致。 - 嵌入式后果:选错 speed 档不会砖板但会导致 SPI/I2C 时序问题,信号质量劣化。嵌入式里时序参数本就零容错,模糊映射波动放大不确定性。
缺陷 18:max_tokens 不足时连"不存在"都答不出 — SPI7 在 2048 时空输出
- 归因层:【glm-5.2 模型】|现象:token 不够时模型连"这个外设不存在"都答不出,直接空输出。
- 实证证据:问不存在的
FOOBAR_Z(max_tokens 足)→ 正确拒绝"no peripheral named FOOBAR_Z";问SPI7(STM32G4 只有 SPI1–4,max_tokens=8192)→ 正确拒绝"does not have SPI7...only SPI1-SPI4";问SPI7(max_tokens=2048,thinking ON)→ reasoning 吃光,空输出,无法拒绝。 - 嵌入式后果:已知寄存器事实确定性高(GPIOA_BASE 3/3 一致正确
0x48000000),不存在的外设会拒绝——但前提是 max_tokens 足够。token 不足时连基本的"拒答"都做不到,可能让 agent 误以为模型在思考而无限等待或误读空响应为"通过"。与缺陷 7/12 叠加。
5. 限制级缺陷详述(🟡 低,可用但有坑)
缺陷 19:skills allowed-tools 字段纯摆设 — 源码零解析
- 归因层:【pi 框架】|实证证据:
docs/skills.md:148文档声称allowed-tools是"Space-delimited list of pre-approved tools (experimental)"。但skills.ts的SkillFrontmatter(:67-72)只定义name/description/disable-model-invocation三字段。grepallowed-tools/allowedTools在 skills.ts 零命中,parseFrontmatter 读入后存入[key:string]:unknown通用槽(:71),无代码读取或执行。 - 嵌入式后果:嵌入式需精细工具管控(GPIO skill 只允许 bash + gpio-set,不许 dd;flash skill 只许 dd + bash,不许 edit)。
allowed-tools若可用可实现 per-skill 工具白名单,但纯摆设,声明不产生运行时效果。
缺陷 20:pi-server locked 恒 true + 协议层无认证 — session 锁状态假报/裸奔
- 归因层:【pi 框架】|实证证据:
sessions.ts:285locked: true硬编码无条件;connection.ts注释说"authorized ordered byte connection"但"authorized"靠传输层,pi-server 自身不做认证。 - 嵌入式后果:所有 session 快照恒报锁定,客户端无法区分真锁假锁;eval server 若暴露网络,任何客户端可创建/操作 session。与缺陷 6 同属服务化缺口。
缺陷 21:模型 id 别名混淆 — 用户写 glm5.2 不通,真实是 glm-5.2
- 归因层:【网关/模型】|实证证据:B 路探活时
/v1/models列表确认真实模型 id 是glm-5.2(带中划线);另有glm-5.2-cc/qianfan/glm-5.2/bailian/glm-5.2三个别名。用户手写glm5.2(无中划线)不通。 - 嵌入式后果:配置 pi-ai provider 时 model id 写错直接 404/模型不存在。低级但真实坑。网关报
max_input_tokens=1000000(1M)、max_output_tokens=131072(128K)——上下文与输出上限充足,不是瓶颈。
6. 缺陷归因矩阵(下一步二开着力点分布)
| 归因层 | 缺陷编号 | 条数 | 二开可解性 |
|---|---|---|---|
| pi 框架层 | 1,2,3,4,5,6,9,10,11,12,13,14,19,20 | 13 | 二开 pi 可直接治(持久 shell / PDF read / 权限门 / 硬件状态 entry / 子进程隔离 / 实现 PiServerService / sequential 默认 / env 注入 / compaction 钩子 / allowed-tools 解析) |
| glm-5.2 模型层 | 7,8,15,16,17,18 | 6 | 二开 pi 只能"绕"不能"治"(默认参数兜底 / arg 后处理 hex 归一 / thinking 关闭策略 / 枚举值约束 / max_tokens 下限门) |
| 网关/模型层 | 21 | 1 | 配置层(写对 model id) |
| 域知识缺口 | (隐含在 2,13,14) | — | RAG/skill/AGENTS.md 补,非框架二开 |
关键洞察:21 条里 pi 框架层占 13 条且可二开直接治;glm-5.2 模型层 6 条只能靠 pi 侧兜底绕开(模型行为改不了)。下一步二开的主战场在 pi 框架层,glm-5.2 层是"适配与兜底"而非"根治"。
7. 诚实声明:已实证 vs 待验
7.1 已实证确定(可复现)
- A 路 15 条 pi 框架缺陷:全部带
packages/.../*.ts:行号源码坐标,可Read复核。并核对纠正了原 pi 调研报告 4 处出入(事件数 30→26、AgentHarness"每方法抛"→"操作方法抛、getter/setter 不抛"、其余 2 处确认一致)。 - B 路 8 项 glm-5.2 探针:全部带真实 HTTP 响应字段(finish_reason / completion_tokens / reasoning_tokens / tool_calls 内容)。命门一(thinking 吃光 token)和命门二(hex→decimal 强转)均三次复现一致。
- C 路嵌入式域需求:全部带可查公开文档来源(kernel.org / cmake.org / openocd.org / elixir.bootlin.com / docs.ros.org / devicetree.org)。
7.2 待验/未覆盖(下一步需补)
- pi-ai
compat层对接 glm-5.2 端到端:B 路只测了网关直连(curl + OpenAI 协议),未走 pi-ai 的detectCompat()嗅探 +thinkingFormat适配链。缺陷 16 的"误配风险"是逻辑推断,需在 pi 里真实跑一次 glm-5.2 session 验证enable_thinking:false是否被正确下发。 - pi 在 aarch64 目标板上原生运行的内存/CPU 实测:原 pi 报告存疑项"pi 多会话内存表现未实测"未补,需上板 spike。
- glm-5.2 在 60k+ token 输入下的延迟实测:B 路测了 60k token 准确性(末尾正确读取),未测端到端延迟——嵌入式 datasheet 全文塞入时每轮延迟是否可接受,待测。
- 缺陷 5(jiti 零隔离)的真实崩溃传播:A 路是源码层确认"无隔离",未实际写一个会 SIGSEGV 的嵌入式扩展去触发带崩主进程——设计层证据确凿但缺触发实证。
附录 A:三路研究证据索引
| 路 | 证据形态 | 条数 | 关键发现 |
|---|---|---|---|
| A 路 pi 源码 | packages/coding-agent/src/ + packages/agent/src/ + packages/server/src/ + packages/ai/src/ 共 25+ 文件 Read/grep |
15 条缺陷 | bash 新进程 / read 截断+无PDF / 无权限门 / AgentHarness 空壳 / jiti 零隔离 / 工具并行 / stopReason length 整批拒 / 无 env 注入 / session 无硬件状态 / compaction 截断 / skills allowed-tools 摆设 |
| B 路 glm-5.2 API | 网关 /v1/models + /v1/chat/completions 8 项探针真实响应 |
2 命门 + 4 中 + 2 低 | 命门一 thinking 吃光 token 零输出;命门二 hex→decimal 强转砖板风险;reasoning_content 原生 + enable_thinking:false 关闭;1M 上下文/60k 不截断/中英混排/10 并发全过 |
| C 路嵌入式域 | 公开文档(kernel/cmake/openocd/elixir/ros/devicetree) | 10 维 + 7 差异 + 10 能力 | 五命门:交叉工具链自觉/破坏性命令防护/寄存器级零容错查证/长会话有状态调试/物理信号判读 |
附录 B:pi 源码坐标清单(A 路核实,可 Read 复核)
| 文件 | 行号 | 核实内容 |
|---|---|---|
packages/coding-agent/src/core/tools/bash.ts |
58-80, 103-105 | BashOperations 接口、spawn detached、每命令新进程 |
packages/coding-agent/src/utils/shell.ts |
213-215 | killProcessTree SIGKILL |
packages/coding-agent/src/core/tools/truncate.ts |
11-12, 78 | DEFAULT_MAX_LINES=2000 / DEFAULT_MAX_BYTES=50KB |
packages/coding-agent/src/core/tools/read.ts |
49-56, 250, 295-300 | ReadOperations、无 PDF、首行超限 fallback |
packages/coding-agent/src/core/tools/edit-diff.ts |
27-51, 208, 219-243 | 两段式匹配、NFKC+dash/space 归一 |
packages/coding-agent/src/core/extensions/types.ts |
1034-1059, 1071-1080, 1102-1106, 1117-1120, 1251 | 26 事件、tool_call block、before_agent_start、session_before_compact、registerTool |
packages/coding-agent/src/core/extensions/loader.ts |
444-455 | jiti.import 主进程零隔离 |
packages/coding-agent/src/core/agent-session.ts |
480-499, 1023-1057 | beforeToolCall 安装 + fail-closed catch、_rebuildSystemPrompt(无 env 注入) |
packages/coding-agent/src/core/system-prompt.ts |
28, 121-138 | buildSystemPrompt 无 git/date/env 注入 |
packages/agent/src/agent-loop.ts |
211-214, 381-406, 419-423, 489-548, 600-668 | stopReason length 整批拒、executeToolCallsParallel、prepareToolCall block |
packages/agent/src/agent.ts |
237 | 默认 toolExecution="parallel" |
packages/agent/src/harness/agent-harness.ts |
233, 326-327, 351, 355-449 | AgentHarness unavailable、UnavailableRegistry on() throw |
packages/server/src/types.ts |
42-60 | PiServerService 纯接口、PiSessionRuntime |
packages/server/src/server.ts |
39, 54 | PiServer 无内置实现 |
packages/server/src/sessions.ts |
285 | locked: true 硬编码 |
packages/ai/src/types.ts |
564-578 | thinkingFormat 11 变体(无 GLM 专属) |
packages/ai/src/api/openai-completions.ts |
493, 749-822 | reasoning_content/reasoning/reasoning_text 三字段搜索 |
packages/coding-agent/src/core/skills.ts |
67-72 | SkillFrontmatter 无 allowed-tools |
packages/coding-agent/src/core/session-manager.ts |
845-847, 100-108 | JSONL 树、entry 类型无硬件状态、CustomEntry 不入 LLM 上下文 |
packages/coding-agent/src/core/compaction/utils.ts |
156-158 | SUMMARIZATION_SYSTEM_PROMPT 模板 |
SECURITY.md |
50 | "intentionally does not have a sandbox" |
附录 C:glm-5.2 探针原始响应摘要(B 路,key 不入库)
- 探针 1(tool calling):原生
finish_reason:"tool_calls"+ parallel 支持;但0x40020000→"1073872896"、0x48000004→"1207959556"(hex→decimal,3/3 一致复现) - 探针 2(上下文):
/v1/models报 1M input / 128K output;60k token 输入末尾0xDEADBEEF正确读取 - 探针 3(max_tokens/reasoning):见缺陷 7 实证表——2048+thinking ON=零输出,8192=正常,enable_thinking:false=关 reasoning
- 探针 4(确定性):GPIOA_BASE 3/3=
0x48000000(正确一致);FOOBAR_Z/SPI7 正确拒绝(需 max_tokens 足);speed 档 high/very_high 波动 - 探针 5(thinking):
enable_thinking:false→content:'391',reasoning_content:'';thinking:{type:"disabled"}→无效,reasoning 照开 - 探针 6(长输入):60k token 无中段截断
- 探针 7(中英混排):英文 datasheet→中文解释+C 代码+中文注释,无混乱
- 探针 8(并发):10 并发全 HTTP 200,无 429
网关 key 全程以环境变量
${DROBOTICS_LLM_KEY}在 bash 进程内传入,未写入任何文件、未出现在本文。复现探针时KEY=$(printenv DROBOTICS_LLM_KEY) curl -H "Authorization: Bearer $KEY" ...。
8. 工作规划与进度(pi 二开)
本节追加于 2026-08-13。基于上述 21 条缺陷,已完成对 pi 的二开功能规划与逐功能文档。每功能有独立文档(
Docs/F01–F21),含清晰验收标准。本节是工作进度看板。
8.1 二开功能全景(21 个功能)
分两层:缺陷修复层 11 个(治已定缺陷)+ 嵌入式主动能力层 10 个(让 pi 真正胜任嵌入式)。详见 Docs/00_二开功能规划总览.md。
| 代号 | 名称 | 治缺陷/满足维度 | 优先级 | 人日 | 状态 | 文档 |
|---|---|---|---|---|---|---|
| F01 | 持久 Shell 与交互式会话 | #1 | P0 | 4-5 | ⬜ 未开始 | F01 |
| F02 | 增强读取 PDF+提限分页 | #2 | P0 | 3-4 | ⬜ 未开始 | F02 |
| F03 | edit 精确匹配安全模式 | #9 | P2 | 2 | ⬜ 未开始 | F03 |
| F04 | stopReason=length 恢复 | #12 | P2 | 3-4 | ⬜ 未开始 | F04 |
| F05 | 硬件安全门 | #3/#11/#19 | P0 | 4-5 | ⬜ 未开始 | F05 |
| F06 | 扩展子进程隔离层 | #5 | P1 | 6-10 | ⬜ 未开始 | F06 |
| F07 | 嵌入式环境探针注入 | #13 | P1 | 1-2 | ⬜ 未开始 | F07 |
| F08 | MCP 桥接扩展 | #10 | P1 | 5-8 | ⬜ 未开始 | F08 |
| F09 | PiServerService 实现 | #6/#20 | P1 | 12-15 | ⬜ 未开始 | F09 |
| F10 | 硬件状态 Entry 持久化 | #4/#14 | P2 | 5-7 | ⬜ 未开始 | F10 |
| F11 | glm-5.2 适配兜底层 | #7/#8/#15/#16/#17/#18/#21 | P0 | 3-4 | ⬜ 未开始 | F11 |
| F12 | 交叉编译工具链管理 | 工具链 | P1 | 3-4 | ⬜ 未开始 | F12 |
| F13 | 安全烧录工具 | 烧录 | P0 | 4-5 | ⬜ 未开始 | F13 |
| F14 | 外设探测工具集 | 外设 | P1 | 4-5 | ⬜ 未开始 | F14 |
| F15 | JTAG/gdb 在线调试集成 | 在线调试 | P1 | 6-8 | ⬜ 未开始 | F15 |
| F16 | 设备树工具 | 设备树 | P2 | 4-5 | ⬜ 未开始 | F16 |
| F17 | 宿主-目标板链路管理 | 板上调测 | P0 | 5-7 | ⬜ 未开始 | F17 |
| F18 | datasheet 与手册 RAG | datasheet | P1 | 6-8 | ⬜ 未开始 | F18 |
| F19 | 硬件行为验证判据 | 闭环 | P1 | 4-5 | ⬜ 未开始 | F19 |
| F20 | 硬件闭环迭代编排 | 闭环 | P2 | 4-5 | ⬜ 未开始 | F20 |
| F21 | 构建系统封装长任务 | 构建 | P1 | 5-6 | ⬜ 未开始 | F21 |
总工作量约 88–115 人日。P0 共 6 个(F01/F02/F05/F11/F13/F17),是"先不建门前裸奔"的最小可用集。
8.2 实施阶段与里程碑
阶段 0 — 命门根治与安全门(P0,约 20 人日)
- F11 glm-5.2 适配(命门一 thinking 黑洞 + 命门二 hex 强转,零代码 models.json 配置,最先做)
- F05 硬件安全门(dd/reboot 拦截,参照 permission-gate.ts 范式)
- F13 安全烧录工具(烧前 lsblk 确认 + dry-run + verify)
- F01 持久 Shell(gdb/openocd/minicom 长会话)
- F02 增强读取(PDF datasheet 不可读=靠记忆=幻觉)
- F17 板链路(所有板上操作前置依赖)
- 里程碑 M0:嵌入式闭环可安全跑通"编译→烧→看 dmesg"且不砖板、不零输出。
阶段 1 — 探查与调试能力(P1,约 40 人日)
- F07 环境探针 → F12 交叉编译 → F14 外设探测 → F15 JTAG/gdb → F18 datasheet RAG
- F21 构建封装 → F19 硬件验证判据 → F20 闭环编排
- F06 子进程隔离(硬件扩展前置)→ F08 MCP 桥接 → F09 服务化(eval 批量)
- 里程碑 M1:agent 能主动看(视觉/RAG)、主动测(probe)、主动调试(gdb)、主动验证(verify)。
阶段 2 — 精度与编排收尾(P2,约 15 人日)
- F03 edit 精确匹配 / F04 length 恢复 / F10 硬件状态持久化 / F16 设备树
- 里程碑 M2:精度收敛 + 闭环编排自洽,eval 批量跑题可用(F09)。
8.3 关键路径依赖
F11(glm适配) ── 独立,最先(models.json)
F05(安全门) ─┬─ F13(烧录)
└─ F19(验证) ─ F20(闭环)
F07(环境注入) ─┬─ F12(交叉编译)
├─ F15(JTAG/gdb)
└─ F16(设备树)
F01(持久shell) ─┬─ F15(共享长会话范式)
└─ F21(构建 tmux 后台)
F17(板链路) ─┬─ F15(板上 gdb)
├─ F19(板上 dmesg 采集)
└─ F21(板上构建)
F06(子进程隔离) ─ F14/F15 native 硬件扩展前置
F10(硬件状态持久化) ─ F14/F15/F19 状态跨 tool call
F02(PDF read) ─ F18(datasheet RAG 抽取)
关键路径:F11 → F05 → F13 → F01 → F17 → F14/F15 → F19 → F20(从命门根治到闭环跑通)。
8.4 归因层与修复可解性
- pi 框架层(F01–F10, F12–F21,除 F11):20 个功能,二开 pi 可直接治(改源码或扩展注册)。主战场。
- glm-5.2 模型层(F11):1 个综合功能,只能绕不能治——靠 pi 侧 max_tokens 门 + enable_thinking:false + hex 归一 + 空输出检测兜底。
8.5 实现范式(六路研究一致结论)
pi 扩展系统已为大部分功能提供基础设施,二开成本低于预期:
- 新工具注册
pi.registerTool(ToolDefinition)(types.ts:1251) - fail-closed 安全门
pi.on("tool_call", handler)返回{block,reason,terminate}(types.ts:1071-1080) - system prompt 注入
pi.on("before_agent_start", handler)链式改写(types.ts:1102-1106) - 串行降级
executionMode:"sequential"(agent-loop.ts:419-423) - 状态持久化
pi.appendEntry(types.ts:1318)+session_before_compact钩子保护(types.ts:1117-1120) - 跨扩展通信
pi.events.emit/on(event-bus.ts) - 可插拔后端 BashOperations/ReadOperations/EditOperations 接口
8.6 进度状态
| 阶段 | 范围 | 状态 |
|---|---|---|
| 问题钉死 | 21 条缺陷实证(A pi 源码 / B glm-5.2 API / C 域需求) | ✅ 完成(本文) |
| 功能规划 | 21 个二开功能 + 优先级 + 依赖图 | ✅ 完成(Docs/00) |
| 逐功能文档 | F01–F21 每功能现状+方案+schema+联动+验收+风险+工作量 | ✅ 完成(Docs/F01–F21) |
| 编码落地 v1 | 21 功能散装 src/logic + src/extensions + tests(F 编号命名 + type shim) | ✅ 完成(已重构) |
| 生产级重构 v2 | npm 库包 + 单一 barrel 装配 + 域命名 + 真集成 + JSDoc | ✅ 完成 |
| 全量验证 | vitest 732 用例 + tsc 0 错 + tsx 离线装配冒烟 21 扩展 | ✅ 完成 |
v2 生产级重构已落地(散装 F 编号脚本 → 生产级 pi Agent 项目):
- 工程形态:
@d-robotics/physical-byte-agentnpm 库包,单一 barrelsrc/extensions/index.ts装配 21 个域扩展(pi.extensions清单 +.pi/extensions/index.ts重导出,pi 自动加载)。src/agent.ts导出PhysicalByteAgent(launch()程序化调createAgentSession+verifyAssembly()离线自检),bin/pba.tsCLI,models.jsonglm-5.2 条目,README.md/AGENTS.md。- 命名:全部域命名(glm-provider / safety-gate / flash / jtag-debugger / loop-orchestrator…),无 F 编号。
- 架构:内联逻辑 + 顶层仅
import type(esbuild 擦除)+ 工厂内动态importdefineTool/Type——逻辑离线可单测(不拉 pi),工厂在真 pi 内装配。fail-closed 语义全保留。- 两命门:命门一
buildGlmModelConfig()(thinkingFormat:qwen + maxTokens:8192 + thinkingLevelMap 全 null)+detectEmptyOutput();命门二normalizeHexArg()/makeHexNormalizingPrepareArguments()。- 验证:
npx tsc --noEmit0 错(对src/types/pi.d.ts类型镜像,已对照 pi 源码核对);npm test732 用例全绿(21 域);npx tsx bin/pba.ts --print-extensions离线装配冒烟通过(21 扩展全就位)。- 真 pi 运行时冒烟:离线受限——pi 自家
packages/ai/src/providers/data/*.json是 generate-models 联网产物,离线缺失致 pi 无法npm run build(SessionManager等 undefined)。launch()失败于此,非本项目问题。联网后cd ../pi && npm run build即可真跑。- 密钥铁律:
grep -rn sk-nAm src/ tests/ bin/ .pi/= 0(key 全程${DROBOTICS_LLM_KEY}占位)。下一步:① 联网构建 pi(
cd ../pi && npm run build)后npx tsx bin/pba.ts真 pi 端到端冒烟;② 真板(aarch64)跑 F14 外设探测 / F13 烧录 / F19 物理信号验证集成;③ F13/F15 寄存器地址归一接入makeHexNormalizingPrepareArguments()。
一句话总结
pi + glm-5.2 在嵌入式开发场景有 21 条实证缺陷(8 高 / 10 中 / 3 低),其中 pi 框架层 13 条可二开直接治(主战场在持久 shell / PDF read / 权限门 / 硬件状态持久化 / 工具串行 / env 注入 / 服务化实现),glm-5.2 模型层 6 条只能靠 pi 侧兜底绕开——两个独家命门最致命:thinking 默认开导致 max_tokens=2048 零输出(与 stopReason length 整批拒执行叠加放大),hex 地址被强转十进制(寄存器地址错一位即砖板)。本文止于钉问题,下一步对 pi 二开时再逐条给修复方案。