physical_byte_agent/pi+glm5.2_嵌入式开发场景缺陷分析.md
d-robotics 06a19a61e8 refactor: 重构为生产级 pi Agent 项目(散装脚本 → npm 库包 + 单一 barrel 装配)
- 工程形态:@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>
2026-08-13 19:54:20 +08:00

46 KiB
Raw Permalink Blame History

pi + glm-5.2 在嵌入式开发场景的不足与缺陷分析

研究对象:pi(earendil-works/pi v0.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/后端开发的七条本质差异

  1. 输出是物理硬件行为,不是 stdout——验证靠 LED/电机/示波器/dmesg 枚举,不是单元测试断言
  2. 错误代价是砖板/硬件损坏,不是重启服务——烧错 bootloader 要拆芯片 SPI 编程器离线恢复
  3. 双机工具链,状态跨宿主-目标分散——宿主编译、scp 到板、板上跑、日志回看
  4. 数值精度零容错——寄存器地址/位偏移错一位静默写错模块,写 MMIO 从不抛异常
  5. 长反馈回路 + 单板串行——每轮分钟级不可并行,试错代价大,一次对率要求高
  6. 硬件异构强绑型号——STM32F4 vs F7、X5 vs S100 引脚/时钟树/寄存器映射全不同,泛化即出错
  7. 领域知识靠 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() 起新子进程;:105 detached: 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-12 DEFAULT_MAX_LINES=2000 / DEFAULT_MAX_BYTES=50KB;truncate.ts:78 truncateHead 用于 read。read.ts:295-300 首行超 50KB 直接返回空内容 + sed fallback 指令。read.ts:250 detectImageMimeType 只支持 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 中 grep permission/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-847 session 是单文件 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-51 normalizeForFuzzyMatch 做 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/ 全局 grep mcp/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:489 executeToolCallsParallel 先串行 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:28 buildSystemPrompt 含角色 + 工具 + guidelines + pi docs + AGENTS.md + skills 索引 + cwd(:121-138);grep gitStatus/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:156 SUMMARIZATION_SYSTEM_PROMPT 产出固定结构(Goal/Constraints/Progress/Key Decisions/Next Steps/Critical Context)+ 保留 <read-files>/<modified-files> 累积清单;agent-harness.ts:340-342 keepRecentTokens: 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 字段,不是 OpenAI thinking 对象。若 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 的 thinkingFormat 11 变体(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,不是 OpenAI thinking:{type:...}。pi-ai compat 层(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_config tool_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 三字段。grep allowed-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:285 locked: 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 待验/未覆盖(下一步需补)

  1. pi-ai compat 层对接 glm-5.2 端到端:B 路只测了网关直连(curl + OpenAI 协议),未走 pi-ai 的 detectCompat() 嗅探 + thinkingFormat 适配链。缺陷 16 的"误配风险"是逻辑推断,需在 pi 里真实跑一次 glm-5.2 session 验证 enable_thinking:false 是否被正确下发。
  2. pi 在 aarch64 目标板上原生运行的内存/CPU 实测:原 pi 报告存疑项"pi 多会话内存表现未实测"未补,需上板 spike。
  3. glm-5.2 在 60k+ token 输入下的延迟实测:B 路测了 60k token 准确性(末尾正确读取),未测端到端延迟——嵌入式 datasheet 全文塞入时每轮延迟是否可接受,待测。
  4. 缺陷 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 扩展系统已为大部分功能提供基础设施,二开成本低于预期:

  1. 新工具注册 pi.registerTool(ToolDefinition)(types.ts:1251)
  2. fail-closed 安全门 pi.on("tool_call", handler) 返回 {block,reason,terminate}(types.ts:1071-1080)
  3. system prompt 注入 pi.on("before_agent_start", handler) 链式改写(types.ts:1102-1106)
  4. 串行降级 executionMode:"sequential"(agent-loop.ts:419-423)
  5. 状态持久化 pi.appendEntry(types.ts:1318)+ session_before_compact 钩子保护(types.ts:1117-1120)
  6. 跨扩展通信 pi.events.emit/on(event-bus.ts)
  7. 可插拔后端 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-agent npm 库包,单一 barrel src/extensions/index.ts 装配 21 个域扩展(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 语义全保留。
  • 两命门:命门一 buildGlmModelConfig()(thinkingFormat:qwen + maxTokens:8192 + thinkingLevelMap 全 null)+ detectEmptyOutput();命门二 normalizeHexArg() / makeHexNormalizingPrepareArguments()。
  • 验证:npx tsc --noEmit 0 错(对 src/types/pi.d.ts 类型镜像,已对照 pi 源码核对);npm test 732 用例全绿(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 二开时再逐条给修复方案。