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>
This commit is contained in:
commit
06a19a61e8
9
.gitignore
vendored
Normal file
9
.gitignore
vendored
Normal file
@ -0,0 +1,9 @@
|
||||
node_modules/
|
||||
dist/
|
||||
.artifacts/
|
||||
*.tsbuildinfo
|
||||
.env
|
||||
.env.*
|
||||
.DS_Store
|
||||
# 本地 pi 符号链接(如有)
|
||||
pi
|
||||
10
.pi/extensions/index.ts
Normal file
10
.pi/extensions/index.ts
Normal file
@ -0,0 +1,10 @@
|
||||
/**
|
||||
* Pi 项目本地扩展入口。
|
||||
*
|
||||
* pi 从本包根目录启动时,自动发现 `cwd/.pi/extensions/`(pi loader.ts:710 实测),
|
||||
* 加载本 index.ts,其 default 工厂 = src/extensions/index.ts 的 barrel,装配全部 21 域扩展。
|
||||
*
|
||||
* 这是「pi profile 运行时集成」的真路径——不是脚本,是 pi 自动加载的扩展。
|
||||
*/
|
||||
export { default } from "../../src/extensions/index.js";
|
||||
export { extensionFactories } from "../../src/extensions/index.js";
|
||||
59
AGENTS.md
Normal file
59
AGENTS.md
Normal file
@ -0,0 +1,59 @@
|
||||
# Physical Byte Agent — AGENTS.md
|
||||
|
||||
基于 [pi](https://github.com/earendil-works/pi) 二开的嵌入式开发 Agent,模型 glm-5.2。
|
||||
|
||||
## 架构铁律
|
||||
|
||||
1. **单一 barrel 装配**:`src/extensions/index.ts` 是 pi 唯一加载的扩展入口(package.json `"pi":{extensions:["src/extensions/index.ts"]}`)。它依次装配 21 个域扩展工厂。pi 加载一个扩展 = 装配整个 Agent。
|
||||
2. **逻辑内联 + 命名导出**:每个 `src/extensions/<domain>.ts` 既 `export default function(pi)`(pi glue:registerTool/on/registerProvider/appendEntry/events),又 `export` 纯逻辑函数。tests import 命名导出单测,无需 pi 运行时、无需真实硬件(注入 mock ExecFn)。
|
||||
3. **fail-closed**:所有硬件判据(safety-gate 破坏性命令、flash 三段式烧录、hardware-verify 物理信号、loop-orchestrator checkpoint)默认拒绝/失败,不放过。
|
||||
4. **命门根治**:
|
||||
- 命门一(thinking 黑洞零输出)= `glm-provider.ts` `buildGlmModelConfig()`(thinkingFormat:qwen + maxTokens:8192 + thinkingLevelMap 全 null)+ `detectEmptyOutput()` 兜底
|
||||
- 命门二(hex 强转砖板)= `glm-provider.ts` `normalizeHexArg()` / `makeHexNormalizingPrepareArguments()` 工厂(接入结构化工具的 prepareArguments)
|
||||
5. **密钥铁律**:网关 key 只走 `${DROBOTICS_LLM_KEY}` 环境占位,绝不硬编码、不入库。`grep -rn sk-nAm src/` 必须为 0。
|
||||
6. **真 pi 类型**:tsconfig `paths` 指向 `../pi/packages/*/src`,对真 pi 源码做 tsc(非 shim)。
|
||||
|
||||
## 文件布局
|
||||
|
||||
```
|
||||
src/
|
||||
index.ts # 公共导出(PhysicalByteAgent 类 + 类型)
|
||||
agent.ts # PhysicalByteAgent.launch(): 组装 extensions → pi createAgentSession
|
||||
shared/types.ts # 跨扩展共享类型
|
||||
extensions/
|
||||
index.ts # barrel:装配全部 21 域扩展
|
||||
glm-provider.ts # 命门一+二 + glm_status 工具
|
||||
safety-gate.ts # 破坏性命令拦截 + 资源锁 + per-skill 工具
|
||||
persistent-shell.ts # PTY 会话池
|
||||
pdf-reader.ts # PDF 分页/提限
|
||||
edit-strict.ts # edit 精确匹配安全模式
|
||||
length-recovery.ts # stop=length 恢复
|
||||
subprocess-isolation.ts
|
||||
env-probe.ts
|
||||
mcp-bridge.ts
|
||||
server-runtime.ts
|
||||
hardware-state.ts
|
||||
cross-compile.ts
|
||||
flash.ts
|
||||
peripheral-probe.ts
|
||||
jtag-debugger.ts
|
||||
device-tree.ts
|
||||
board-link.ts
|
||||
datasheet-rag.ts
|
||||
hardware-verify.ts
|
||||
loop-orchestrator.ts
|
||||
build-tracker.ts
|
||||
bin/pba.ts # CLI 入口
|
||||
tests/ # 镜像扩展,单测命名逻辑导出
|
||||
```
|
||||
|
||||
## 运行
|
||||
|
||||
- `npm test` — vitest 全量单测(无需板、无需构建 pi)
|
||||
- `npx tsc --noEmit` — 对真 pi 源码类型检查
|
||||
- `npm run smoke` — 加载 barrel 到 pi,打印已注册 provider/工具(需 DROBOTICS_LLM_KEY + 先 `cd ../pi && npm rebuild better-sqlite3`)
|
||||
|
||||
## 已知局限(不假装已完成)
|
||||
|
||||
- `length-recovery.ts` 的 `partitionToolCalls` 属 pi agent-loop 内部逻辑,pi 扩展 API 够不着;本扩展只做 prompt 注入兜底 + events 握手,真正选择性执行需 patch pi 源码。
|
||||
- 真板集成(F13 烧录/F14 外设探测/F19 物理信号验证的硬件侧)逻辑已单测,真硬件侧集成待在 aarch64 板上跑。
|
||||
153
Docs/00_二开功能规划总览.md
Normal file
153
Docs/00_二开功能规划总览.md
Normal file
@ -0,0 +1,153 @@
|
||||
# pi 二开功能规划总览
|
||||
|
||||
> **目标**:把 pi(`earendil-works/pi` v0.84.1,源码 `/Users/d-robotics/Desktop/pi`)改造成胜任**嵌入式开发场景**的 agent harness。
|
||||
> **场景死锚**:交叉编译 / 烧录 / 外设驱动 / JTAG 在线调试 / 设备树 / datasheet 寄存器级编码 / 板上调测 / ROS·tros。一切功能必须能指向嵌入式具体用例,禁止写通用 code agent 废话。
|
||||
> **基线**:21 条缺陷见 `../pi+glm5.2_嵌入式开发场景缺陷分析.md`。
|
||||
> **本文**:21 个二开功能的全景、优先级、依赖图、归因映射。每个功能的细节在独立文档(F01–F21)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 功能全景(21 个,分两层)
|
||||
|
||||
### 第一层:缺陷修复(11 个,治已定 21 条缺陷)
|
||||
|
||||
| 代号 | 名称 | 治缺陷 | 归因层 | 优先级 | 工作量(人日) | 文档 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| F01 | 持久 Shell 与交互式会话工具 | #1 | pi 框架 | P0 | 4-5 | F01 |
|
||||
| F02 | 增强读取:PDF+提限+分页 | #2 | pi 框架 | P0 | 3-4 | F02 |
|
||||
| F03 | edit 精确匹配安全模式 | #9 | pi 框架 | P2 | 2 | F03 |
|
||||
| F04 | stopReason=length 恢复策略 | #12 | pi 框架 | P2 | 3-4 | F04 |
|
||||
| F05 | 硬件安全门:破坏性命令拦截+资源锁+allowed-tools | #3/#11/#19 | pi 框架 | P0 | 4-5 | F05 |
|
||||
| F06 | 扩展子进程隔离层 | #5 | pi 框架 | P1 | 6-10 | F06 |
|
||||
| F07 | 嵌入式环境自动探针注入 | #13 | pi 框架 | P1 | 1-2 | F07 |
|
||||
| F08 | MCP 桥接扩展 | #10 | pi 框架 | P1 | 5-8 | F08 |
|
||||
| F09 | PiServerService 生产实现 | #6/#20 | pi 框架 | P1 | 12-15 | F09 |
|
||||
| F10 | 硬件状态 Session Entry 持久化 | #4/#14 | pi 框架 | P2 | 5-7 | F10 |
|
||||
| F11 | glm-5.2 适配兜底层 | #7/#8/#15/#16/#17/#18/#21 | glm-5.2 | P0 | 3-4 | F11 |
|
||||
|
||||
### 第二层:嵌入式主动能力(10 个,让 pi 真正胜任嵌入式)
|
||||
|
||||
| 代号 | 名称 | 满足嵌入式维度 | 优先级 | 工作量(人日) | 文档 |
|
||||
|---|---|---|---|---|---|
|
||||
| F12 | 交叉编译工具链管理 | #1 工具链 | P1 | 3-4 | F12 |
|
||||
| F13 | 安全烧录工具 | #2 烧录 | P0 | 4-5 | F13 |
|
||||
| F14 | 外设探测工具集 | #3 外设 | P1 | 4-5 | F14 |
|
||||
| F15 | JTAG/gdb 在线调试集成 | #4 在线调试 | P1 | 6-8 | F15 |
|
||||
| F16 | 设备树工具 | #5 设备树 | P2 | 4-5 | F16 |
|
||||
| F17 | 宿主-目标板链路管理 | #8 板上调测 | P0 | 5-7 | F17 |
|
||||
| F18 | datasheet 与手册 RAG | #6 datasheet | P1 | 6-8 | F18 |
|
||||
| F19 | 硬件行为验证判据 | #9 闭环 | P1 | 4-5 | F19 |
|
||||
| F20 | 硬件闭环迭代编排 | #9 闭环 | P2 | 4-5 | F20 |
|
||||
| F21 | 构建系统封装与长任务跟踪 | #7 构建 | P1 | 5-6 | F21 |
|
||||
|
||||
> 总工作量约 88–115 人日。P0 共 6 个(F01/F02/F05/F11/F13/F17),是"先不建门前裸奔"的最小可用集。
|
||||
|
||||
---
|
||||
|
||||
## 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 板链路**(所有板上操作的前置依赖)
|
||||
|
||||
### 阶段 1 — 探查与调试能力(P1,约 40 人日)
|
||||
让 agent 能主动看、主动测、主动调试。
|
||||
- F07 环境探针注入 → F12 交叉编译 → F14 外设探测 → F15 JTAG/gdb → F18 datasheet RAG
|
||||
- F21 构建封装(长任务后台)→ F19 硬件验证判据 → F20 闭环编排
|
||||
- F06 子进程隔离(硬件操作扩展前置)→ F08 MCP 桥接 → F09 服务化(eval 批量)
|
||||
|
||||
### 阶段 2 — 精度与编排收尾(P2,约 15 人日)
|
||||
- F03 edit 精确匹配 / F04 length 恢复 / F10 硬件状态持久化 / F16 设备树
|
||||
|
||||
---
|
||||
|
||||
## 3. 依赖图
|
||||
|
||||
```
|
||||
F11(glm适配) ── 独立,最先(models.json)
|
||||
F05(安全门) ─┬─ F13(烧录)
|
||||
└─ F19(验证) ─ F20(闭环)
|
||||
F07(环境注入) ─┬─ F12(交叉编译)
|
||||
├─ F15(JTAG/gdb, 读 openocd cfg)
|
||||
└─ F16(设备树, 读 dtc 路径)
|
||||
F01(持久shell) ─┬─ F15(共享长会话范式)
|
||||
└─ F21(构建, tmux 后台)
|
||||
F17(板链路) ─┬─ F15(板上 gdb)
|
||||
├─ F19(板上 dmesg 采集)
|
||||
└─ F21(板上构建)
|
||||
F06(子进程隔离) ─ 所有 native 硬件扩展前置(F14/F15)
|
||||
F10(硬件状态持久化) ─ F14(i2c/gpio 状态) / F15(断点) / F19(四元组)
|
||||
F08(MCP) ─ 可桥接外部仪器/datasheet server(与 F18 互补)
|
||||
F09(服务化) ─ eval 批量跑题基础设施
|
||||
F02(PDF read) ─ F18(datasheet RAG 抽取)
|
||||
```
|
||||
|
||||
**关键路径**:F11 → F05 → F13 → F01 → F17 → F14/F15 → F19 → F20(从命门根治到闭环跑通)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 归因层与修复可解性矩阵
|
||||
|
||||
| 归因层 | 功能 | 二开可解性 |
|
||||
|---|---|---|
|
||||
| pi 框架层 | F01-F10, F12-F21(除 F11) | 二开 pi 可直接治(改源码或扩展注册) |
|
||||
| glm-5.2 模型层 | F11 | 只能绕不能治(models.json 兜底 + prepareArguments 归一) |
|
||||
|
||||
> **关键洞察**:pi 框架层是主战场(20 个功能可二开直接治);glm-5.2 层(F11)是"适配与兜底"——模型行为改不了,靠 pi 侧 max_tokens 门 + enable_thinking:false + hex 归一 + 空输出检测绕开。
|
||||
|
||||
---
|
||||
|
||||
## 5. 实现范式归纳(六路研究一致结论)
|
||||
|
||||
pi 的扩展系统已为大部分功能提供了基础设施,二开成本低于预期:
|
||||
|
||||
1. **新工具注册**:`pi.registerTool(ToolDefinition)`(`extensions/types.ts:1251`),工具定义含 `name/parameters(TypeBox)/execute/executionMode`。无需改 pi 核心 switch。
|
||||
2. **fail-closed 安全门**:`pi.on("tool_call", handler)` 返回 `{block:true,reason,terminate}`(`types.ts:1071-1080`),handler 抛错=工具不执行(`agent-session.ts:493-498`)。参照 `examples/extensions/permission-gate.ts`。
|
||||
3. **system prompt 注入**:`pi.on("before_agent_start", handler)` 链式改写 systemPrompt(`types.ts:1102-1106`,`runner.ts:1119-1120`)。参照 `pirate.ts`。
|
||||
4. **串行降级**:工具声明 `executionMode:"sequential"`,整批降级(`agent-loop.ts:419-423`)。治共享硬件并发。
|
||||
5. **状态持久化**:`pi.appendEntry(customType, data)` 写 CustomEntry(`types.ts:1318`,不进 LLM 上下文);`appendCustomMessageEntry` 进 LLM 上下文(`session-manager.ts:1171`);`session_before_compact` 钩子保护关键值不被摘要(`types.ts:1117-1120`)。
|
||||
6. **跨扩展通信**:`pi.events.emit/on(channel, data)`(`event-bus.ts`),联动 F17/F19/F20/F21。
|
||||
7. **可插拔后端**:BashOperations(`bash.ts:62-80`)/ ReadOperations(`read.ts:49-56`)/ EditOperations(`edit.ts:85-92`)接口,为 SSH/板侧执行设计。
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收统一原则
|
||||
|
||||
每个功能文档必须有**可测验收标准**(3-5 条),遵守:
|
||||
1. 每条给**具体输入→预期输出**(如 `dd if=x of=/dev/sda` → 被 block,返回 reason)。
|
||||
2. 砖板风险项必须验证 fail-closed(钩子崩=工具不执行)。
|
||||
3. 联动项必须验证跨功能生效(如 F05 拦截裸 dd、F07 注入的 env 被 F12 读到)。
|
||||
4. 回归项:功能未启用时 pi 原行为零变化。
|
||||
5. 嵌入式场景锚定:每条验收指向真实嵌入式动作(gdb 断点/i2c 地址/dts 节点/烧录/板上 dmesg)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 文档清单
|
||||
|
||||
- `00_二开功能规划总览.md`(本文)
|
||||
- `F01_持久Shell与交互式会话工具.md`
|
||||
- `F02_增强读取PDF与提限分页.md`
|
||||
- `F03_edit精确匹配安全模式.md`
|
||||
- `F04_stopReason-length恢复策略.md`
|
||||
- `F05_硬件安全门破坏性命令拦截与资源锁.md`
|
||||
- `F06_扩展子进程隔离层.md`
|
||||
- `F07_嵌入式环境自动探针注入.md`
|
||||
- `F08_MCP桥接扩展.md`
|
||||
- `F09_PiServerService生产实现.md`
|
||||
- `F10_硬件状态Session-Entry持久化.md`
|
||||
- `F11_glm-5.2适配兜底层.md`
|
||||
- `F12_交叉编译工具链管理.md`
|
||||
- `F13_安全烧录工具.md`
|
||||
- `F14_外设探测工具集.md`
|
||||
- `F15_JTAG-gdb在线调试集成.md`
|
||||
- `F16_设备树工具.md`
|
||||
- `F17_宿主-目标板链路管理.md`
|
||||
- `F18_datasheet与手册RAG.md`
|
||||
- `F19_硬件行为验证判据.md`
|
||||
- `F20_硬件闭环迭代编排.md`
|
||||
- `F21_构建系统封装与长任务跟踪.md`
|
||||
70
Docs/F01_持久Shell与交互式会话工具.md
Normal file
70
Docs/F01_持久Shell与交互式会话工具.md
Normal file
@ -0,0 +1,70 @@
|
||||
# F01 持久 Shell 与交互式会话工具(F-PSHELL)
|
||||
|
||||
> **治缺陷**:#1(bash 每命令新进程,gdb/OpenOCD/minicom 交互式长会话不可用)
|
||||
> **场景锚定**:嵌入式开发里 gdb-multiarch 下断点/continue/单步、OpenOCD 常驻做 JTAG 桥接、minicom/picocom 串口交互——全部要求在同一进程内跨多次 tool call 保持状态。当前 pi 每条 bash 命令 spawn 新子进程,断点/ELF/JTAG target 全丢,闭环断链。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
- `bash.ts:103-109` — `spawn(shell, [...args, command], {cwd, detached, env, stdio})`,`bash -c "<cmd>"` 执行完即退出。
|
||||
- `bash.ts:104` cwd 来自 `createBashToolDefinition(cwd,…)`(:322)闭包,每次重置;`cd` 不跨调用保留。
|
||||
- `bash.ts:106` env 每次经 `getShellEnv()`(`shell.ts:122-134`)从 `process.env` 重取快照。
|
||||
- `shell.ts:200-225` `killProcessTree` 对整个进程组发 `SIGKILL`(`:215`),在 bash.ts:118(abort)/126(timeout)/148(finally) 调用——常驻 openocd 命令结束即被杀。
|
||||
- `BashOperations` 接口(`bash.ts:62-80`)单方法 `exec(command, cwd, {onData, signal, timeout, env}) => {exitCode}`,默认实现 `createLocalBashOperations`(:88-154)。
|
||||
- `user_bash` 事件(`types.ts:813-821,1083-1088`)只拦用户 `!` 命令,不拦 agent 工具调用。
|
||||
- 工具派发按名查找(`agent-loop.ts:607` `tools.find(t=>t.name===toolCall.name)`),新工具入 active tools 即自动派发。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**推荐:新增独立 `pshell` 工具 + 进程内 PTY 会话池**(不改造 bash)。
|
||||
|
||||
理由:bash 的 `exec` 是无状态单发语义,硬塞 session_id 破坏其契约;新工具 schema 可带 `session_id/action`,与 F05(权限门)/缺陷11(串行)解耦更干净。
|
||||
|
||||
- **会话池 `SessionPool`**:管理长生命周期 PTY 子进程(Node 内置 `child_process.spawn(shell,['-i'],{stdio:['pipe','pipe','pipe']})` 不 detach、不 SIGKILL;或 `node-pty`),按 `session_id` 索引,idle 超时回收(如 10min)。
|
||||
- **命令发送**:写 stdin + sentinel(`; echo "__PSHELL_DONE__$?"`),读 stdout 到 sentinel 提取 exitCode 与输出。gdb/openocd/minicom 同会话连续发命令,断点/ELF/target/JTAG 桥接保留。
|
||||
- **不调** `killProcessTree`(shell.ts:200)逐命令杀;仅 `action:"close"` 时整体结束会话。
|
||||
- 备选 1:tmux 会话池(`tmux new-session -d -s <id>` + `send-keys` + `capture-pane`),无原生依赖、openocd 崩不波及 agent,但需外部 tmux、输出解析脆。
|
||||
- 备选 2:expect 长连接——不推荐,解析脆、并发难。
|
||||
|
||||
**让 agent 选持久 vs 普通 bash**:
|
||||
1. 工具 description 明确"用于 gdb/openocd/minicom/picocom 等需跨多步保持状态的交互式长会话;一次性命令仍用 bash"。
|
||||
2. `pshell` 默认 `executionMode:"sequential"`(治缺陷 11 共享硬件并发撞车)。
|
||||
3. 可选:bash 工具内对已知交互式二进制(gdb|openocd|minicom|picocom|screen|tmux)探测后提示"改用 pshell"。
|
||||
|
||||
## 3. 接口/工具 schema(TypeBox,仿 bash.ts:41-44)
|
||||
|
||||
```
|
||||
pshellSchema = Type.Object({
|
||||
session_id: Type.Optional(Type.String({description:"会话标识;不传则新建并返回新 id"})),
|
||||
command: Type.Optional(Type.String({description:"发往会话的命令;action=open/close 时可省"})),
|
||||
action: Type.Optional(Type.Union([Type.Literal("open"),Type.Literal("close"),Type.Literal("send")],{description:"默认 send"})),
|
||||
timeout: Type.Optional(Type.Number({description:"单条命令超时秒"})),
|
||||
})
|
||||
```
|
||||
返回 `{session_id, stdout, stderr, exitCode}`。
|
||||
|
||||
**注册路径**(不改 pi 核心 switch):通过扩展 `pi.registerTool()`(`types.ts:1251`)注册;或在 `packages/coding-agent/src/core/tools/index.ts`:加入 `ToolName` 联合(:83)、`createToolDefinition` switch(:96-115)、`createTool` switch(:117-136)、`createAllToolDefinitions`(:156-166)。`PshellToolOptions` 加到 `ToolsOptions`(index.ts:86-94)。
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F05 硬件安全门**:pshell 会话内的破坏性命令仍需门控,`tool_call` 钩子 fail-closed(agent-session.ts:480-499)。
|
||||
- **F15 JTAG/gdb 集成**:共享"长生命周期子进程"设计范式,F15 的 debugger 工具可建在 pshell 会话池之上。
|
||||
- **F21 构建封装**:tmux 后台构建可走 pshell 持久会话。
|
||||
- **F17 板链路**:板侧 SSH 持久 shell 可复用 pshell 范式(`board_exec` 改 `ssh remote "tmux send-keys"`)。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. 连续两次 `pshell send`(同一 session_id)发 `gdb` → `break main` → `run`:第二次 `info breakpoints` 能看到上一步设的断点(断点保留)。
|
||||
2. `pshell open` 起 openocd 常驻;后续 `pshell send` 发 gdb 命令能连上该 openocd 的 telnet 端口(openocd 未被杀)。
|
||||
3. 会话 idle 超 N 分钟后池自动 close 回收子进程(`ps` 不再残留)。
|
||||
4. `pshell action:"close"` 后再 send 同 session_id 返回明确"会话已结束"错误,不静默起新。
|
||||
5. pshell 工具 `executionMode:"sequential"`:一轮内多个 pshell 调用串行执行(验证 `agent-loop.ts:419-422` 降级路径生效)。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- 新增 `node-pty` 原生依赖(需 aarch64 板上预编译);或用 Node 内置 `child_process`+伪 PTY 避免 native 依赖(推荐先做)。
|
||||
- 会话池跨 agent-loop 轮次需挂到 `agent-session` 生命周期,session 结束务必 close 全部池,否则孤儿 openocd 占 JTAG。
|
||||
- 与缺陷 3(权限门)耦合:pshell 内破坏性命令仍需门控。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P0 高**(治命门"长会话有状态调试",缺陷 1/4 耦合的核心断链点)|**4-5 人日**。
|
||||
53
Docs/F02_增强读取PDF与提限分页.md
Normal file
53
Docs/F02_增强读取PDF与提限分页.md
Normal file
@ -0,0 +1,53 @@
|
||||
# F02 增强读取:PDF + 提限 + 分页(F-READ)
|
||||
|
||||
> **治缺陷**:#2(read 头部截断 2000 行/50KB + 零 PDF → datasheet 不可读)
|
||||
> **场景锚定**:SoC datasheet 通常 3000-8000 页 PDF(如 HR-PS6008e),寄存器定义头文件(CMSIS Device Header)动辄 5000+ 行。agent 直接读 datasheet PDF → 零 PDF 支持返乱码;读巨型 .h → 只看前 2000 行。查不到寄存器偏移就靠记忆,靠记忆就幻觉,幻觉就写错寄存器(缺陷 #8 命门二的源头之一)。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
- `truncate.ts:11-12` `DEFAULT_MAX_LINES=2000` / `DEFAULT_MAX_BYTES=50KB`(agent 副本 `agent/harness/utils/truncate.ts:11-12` 同值)。
|
||||
- `read.ts:295` read 调 `truncateHead(content)` **不传 options**,恒用默认值;`TruncationOptions`(truncate.ts:40-45)的 `maxLines/maxBytes` 通道存在但 read 未透传。
|
||||
- `read.ts:295-301` 首行 >50KB 时 `truncateHead` 返回 `firstLineExceedsLimit:true` + 空 content(truncate.ts:104-119),read 用 sed fallback 文本替代。
|
||||
- `mime.ts:6-23` `detectSupportedImageMimeType` 只嗅 JPEG/PNG/GIF/WEBP/BMP,无 `%PDF-` 嗅探;`read.ts:250-270` PDF 落入 text 分支被当 UTF-8 解码为乱码。
|
||||
- `ReadOperations` 接口(read.ts:49-56):`readFile/access/detectImageMimeType?`,可插拔扩展缝。
|
||||
- 分页已存在:`readSchema`(read.ts:21-25)已有 `offset`(1-indexed)/`limit`;执行 read.ts:277-293 slice + 续读提示(:304-317)。
|
||||
- 无任何 PDF 依赖(package.json 全扫无 pdf-parse/unpdf/pdfjs-dist)。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
- **提限**:`ReadToolOptions`(read.ts:64-69)加 `maxLines?:number`/`maxBytes?:number`,默认值提高(datasheet 场景 8000 行/500KB),透传进 read.ts:295 的 `truncateHead(content,{maxLines,maxBytes})`。两份副本(coding-agent read.ts:295 + agent read.ts:116)同改。
|
||||
- **首行超限**:read.ts:297-301 不再 punt 给 sed,改为按字节区间分块读取(`offset` 升级为字节偏移可选,或对单行文件按 `head -c` 分页返回 + 续读提示)。
|
||||
- **PDF 抽取**:
|
||||
1. `mime.ts` 加 `detectPdfMimeType`(嗅 `%PDF-`,0x25 0x50 0x44 0x46)。
|
||||
2. `ReadOperations`(read.ts:49-56)加可选 `extractPdfText?: (path, {maxPages, offset}) => Promise<{text, totalPages, pages}>`,默认实现用 `unpdf`(纯 JS、无 native、ESM 友好)。
|
||||
3. read.ts:254-271 image 与 text 分支之间插 `else if(isPdf){ extractPdfText → 走现有 truncateHead+offset/limit 分页 + "use offset=N" 续读提示 }`。
|
||||
4. PDF 页渲染为图(可选):走现有 `{type:"image",data:base64,mimeType:"image/png"}`(read.ts:268、image-process.ts:115)格式。
|
||||
- 备选依赖:`pdfjs-dist`(更重、WASM);`pdf-parse`(CommonJS、Node22 ESM 兼容差)。推荐 `unpdf`。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
read schema(read.ts:21-25)已含 offset/limit,无需改;新增可选 `pages?:Type.Optional(Type.Number({description:"PDF 按页读取的起始页/页数,非 PDF 忽略"}))`。`ReadOperations` 加 `extractPdfText?` 与 `detectDocumentMimeType?`。`ReadToolOptions`(read.ts:64-69)加 `maxLines/maxBytes`。工具描述(read.ts:218)更新提及 PDF 与新上限。
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F18 datasheet RAG**:F02 的 PDF 抽取是 F18 索引的前置(F18 用 `pdftotext -layout` 或复用 `extractPdfText`)。
|
||||
- **F10 硬件状态持久化**:寄存器值读到后由 F10 落 session,防 compaction 丢失。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. 读 3000 页 SoC datasheet PDF:首次返回首页文本 + 总页数 + "use offset=2 to continue" 提示,连续 offset 续读无丢页。
|
||||
2. 读 5000+ 行 CMSIS 寄存器头文件:提限后首读返回完整前 8000 行(非 2000 截断),offset=N 续读正确。
|
||||
3. 单行 minified JS(首行 >50KB):不再返回空+sed fallback,而是返回首 50KB 内容 + 字节续读提示。
|
||||
4. 非 PDF/非文本(图片)原路径不回归(image 分支仍返回 base64 image content)。
|
||||
5. `extractPdfText` 抽取的寄存器地址串(如 `0x40020000`)原样保留,无数值归一(不触发缺陷 8)。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- 新增 `unpdf` 依赖(coding-agent/package.json,agent 副本若用其 harness read 亦加)。
|
||||
- 大 PDF 抽取吃内存,需分页惰性加载 + 超时。
|
||||
- 两份 read 副本必须同步改(coding-agent `core/tools/read.ts` + agent `harness/tools/read.ts`,前者经 `tools/index.ts` 注册,后者经 `server/create-harness.ts:101` 注册)。
|
||||
- PDF 表格结构可能丢排版,寄存器表靠 offset 翻页风险仍在——建议 datasheet 场景配合 F18 RAG 而非全量塞上下文。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P0 高**(治命门"寄存器级零容错查证",datasheet 不可读=靠记忆=幻觉=写错寄存器)|**3-4 人日**。
|
||||
55
Docs/F03_edit精确匹配安全模式.md
Normal file
55
Docs/F03_edit精确匹配安全模式.md
Normal file
@ -0,0 +1,55 @@
|
||||
# F03 edit 精确匹配安全模式(F-EDIT)
|
||||
|
||||
> **治缺陷**:#9(edit fuzzy 匹配 .dts/.ld 误匹配 + 归一化破坏对齐空白)
|
||||
> **场景锚定**:设备树 `.dts` 节点结构高度重复(`&i2c0{...}`/`&i2c1{...}`),链接脚本 `.ld` 段名相似(`.text`/`.text.init`/`.text.startup`)。agent 给的 oldText 不够长时 fuzzy 易错配到相邻节点——改错节点 = 外设静默不枚举(dmesg 无报错),调试极难。fuzzy 返回归一化 content 还会把未改行的对齐空白重写。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
- `edit-diff.ts:206-217` `fuzzyFindText`:先 `content.indexOf(oldText)`(:208)精确匹配;命中返回 `contentForReplacement: content`(:212 原文,不破坏)。
|
||||
- 失败则 `:219-222` 无条件进 fuzzy:`normalizeForFuzzyMatch(content)`(:220) + `normalizeForFuzzyMatch(oldText)`(:221) + `fuzzyContent.indexOf(fuzzyOldText)`(:222)。**无 opt-out、无文件类型门**。
|
||||
- `normalizeForFuzzyMatch`(edit-diff.ts:33-54):`NFKC`(:36) + **每行 `line.trimEnd()`(:39)** + 智能 quotes/dashes/space 归一。`:39 trimEnd()` 是破坏对齐鲁尾空白的根因。
|
||||
- `:237-243` fuzzy 命中返回 `contentForReplacement: fuzzyContent`(归一化内容,非原文);下游 `applyEditsToNormalizedContent`(:317-322)一旦任一 edit 用 fuzzy,整文件替换基座 `replacementBaseContent = normalizeForFuzzyMatch(normalizedContent)`(:322),**未改行对齐空白也被重写**。
|
||||
- `EditOperations` 接口(edit.ts:85-92):`readFile/writeFile/access`,可插拔。
|
||||
- `editSchema`(edit.ts:45-54)字段仅 `path/edits[{oldText,newText}]`;**无 `replace_all`、无 `strict`、无文件类型门**。全仓 grep `.dts/.ld/extname` 在 edit 路径零命中。
|
||||
- 调用链:execute(edit.ts:314)→ `applyEditsToNormalizedContent(normalizedContent, edits, path)`(:349)→ `fuzzyFindText`(:320/327)+ `countOccurrences`(:332,也走 normalize)。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**推荐:加 `strict` 参数 + 文件类型自动门**。
|
||||
|
||||
1. `editSchema`(edit.ts:45-54)加 `strict: Type.Optional(Type.Boolean({description:"严格精确匹配,禁用 fuzzy 归一化;.dts/.dtsi/.ld/.lds 默认 true"}))`。
|
||||
2. 透传到 `Edit` 类型(edit-diff.ts:190-193)与 `applyEditsToNormalizedContent` 签名(edit-diff.ts:304,调用点 edit.ts:349、computeEditsDiff :540)。
|
||||
3. `fuzzyFindText`(edit-diff.ts:219-222)strict 时 short-circuit:精确 indexOf 失败直接返回 `found:false`,跳过 `normalizeForFuzzyMatch`。
|
||||
4. `applyEditsToNormalizedContent`(:321-322)strict 时强制 `replacementBaseContent = normalizedContent` 不归一。
|
||||
5. `countOccurrences`(:251-255)strict 时对原文计数。
|
||||
6. 默认 strict 的扩展名门:edit.ts:349 调 apply 前按 `path` 后缀(`.dts/.dtsi/.ld/.lds/.sct/.icf`)置 `strict=true`。
|
||||
|
||||
备选 1(仅扩展名门,不改 schema,edit.ts:349 处判扩展名跳 fuzzy)——改动小但 agent 无法显式控制。
|
||||
备选 2(改 `normalizeForFuzzyMatch` 去 `line.trimEnd()` :39)——治本但影响全量现有 fuzzy 行为,回归风险大,不推荐单独做。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
`editSchema` 加 `strict?:boolean`。`Edit` 接口(edit-diff.ts:190-193)加 `strict?:boolean`。`applyEditsToNormalizedContent(content, edits, path, opts?:{strict?:boolean})`(edit-diff.ts:304)。错误文案复用 `getNotFoundError`(edit-diff.ts:257-266,已写"must match exactly including all whitespace")。
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F16 设备树工具**:`dt parse` 作为编辑前结构化预检——agent 先 `dt parse` 定位节点 label 再精确 edit,绕过 fuzzy。F05 的 `tool_call` 钩子可对 `.dts` 的 EditToolCallEvent(types.ts:868-871)要求 oldText 长度 ≥ N,否则 block 提示"use dt parse to locate node label first"。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. `.dts` 文件中 `&i2c1{...}` 节点:oldText 给 `&i2c1` 片段,strict 模式下若原文有尾随空格而 oldText 无,返回 not-found 错误而非错配到 `&i2c0`。
|
||||
2. strict 模式 edit 后,未改行的尾随空白逐字节不变(`diff` 只在改动行)。
|
||||
3. `.ld` 链接脚本 `.text.init : { }` 与 `.text.startup : { }`:oldText 不足时 strict 拒绝误匹配,提示"oldText 不唯一/不精确"。
|
||||
4. 非 strict(默认)对普通 .ts/.py 保持现有 fuzzy 行为不回归。
|
||||
5. `strict:true` 且精确匹配命中时,`contentForReplacement` 为原文(:212 路径),未改行对齐空白零变化。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- 纯 TS 改动,无新依赖。
|
||||
- 回归面:`applyEditsToNormalizedContent` 被 edit.ts:349 与 computeEditsDiff(:540)共用,签名加可选参数需两处透传。
|
||||
- `countOccurrences` 在 strict 下对原文计数可能导致"重复出现"判定变化(.dts 重复节点本就常见,需测)。
|
||||
- agent 副本 `packages/agent/src/harness/tools/edit-diff.ts`(行号偏移 ~3)同样改动需同步。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P2 中**(治命门"寄存器级零容错查证"的 .dts 改错节点=外设静默不枚举;非阻断但有砖板级隐患)|**2 人日**。
|
||||
52
Docs/F04_stopReason-length恢复策略.md
Normal file
52
Docs/F04_stopReason-length恢复策略.md
Normal file
@ -0,0 +1,52 @@
|
||||
# F04 stopReason=length 恢复策略(F-LENGTH)
|
||||
|
||||
> **治缺陷**:#12(stopReason==="length" 整批 tool call 全标错不执行)
|
||||
> **场景锚定**:嵌入式任务上下文极长——交叉编译 warning 海洋(arm-none-eabi-gcc 输出)、datasheet 寄存器表注入、设备树全文、OpenOCD 配置。这些大上下文易让 LLM 输出逼近 token 上限。一旦 stopReason=length,agent 这轮想发的所有工具调用(edit 源码 + bash 编译 + read 日志)全被拒绝,重发一轮浪费 token 和时间。单板串行的嵌入式闭环每轮都贵,效率塌方。**与缺陷 #7(glm-5.2 thinking 吃光 token 触发 length)叠加放大**。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
- `agent-loop.ts:211-214`:严格三元 `message.stopReason==="length" ? failToolCallsFromTruncatedMessage(toolCalls,emit) : executeToolCalls(...)`,**无逐 call 区分**。
|
||||
- `failToolCallsFromTruncatedMessage`(agent-loop.ts:374-406):对每个 toolCall 发 `tool_execution_start` + 构造 `isError:true` 错误结果(文案 "...was not executed: response hit the output token limit, args may be truncated. Re-issue...")+ 发 end/result,返回 `terminate:false`(loop 继续,等模型重发)。
|
||||
- **设计意图铁证**:docstring(:376-379)明确"best-effort JSON salvage parser 可让截断的 tool call 参数 parse+validate 通过但语义不完整",故 schema 校验**不足以**判定完整性——这是 fail-all 的存在理由。
|
||||
- stopReason 来源:Anthropic 侧 `anthropic-messages.ts:707-715` `message_delta.stop_reason` 经 `mapStopReason`(:1326-1352,`max_tokens→length`)映射;`StopReason` 类型 `ai/types.ts:393`。
|
||||
- tool_use 流式累积:`anthropic-messages.ts:615-627` 建块(`partialJson:""`);`:654-666` 每个 `input_json_delta` 追加并 `parseStreamingJson`(永不抛的 salvage 解析器 `ai/utils/json-parse.ts:104-124`);`:675-705` `content_block_stop` 时再解析并 `delete block.partialJson`。
|
||||
- **关键**:max_tokens 截断时 Anthropic 发 `message_delta`+`message_stop` 但**不发** `content_block_stop` 给进行中块,故 :695 finalize 不跑、`partialJson` 不删——进行中块 arguments 是 salvage 解析结果、可能语法合法但语义不全。**`content_block_stop` 是否到达 = 块完整性权威信号,但目前被丢弃**。
|
||||
- 已有恢复钩子(coding-agent 层):`agent-session.ts:1988-2022` 截断时 `isRecoverableLength`(`ai/utils/overflow.ts:171`)触发 compact-and-retry,`:2018-2019` 丢弃截断 assistant 消息后重试一次。**但只丢 assistant 消息,不丢 failToolCallsFromTruncatedMessage 已塞入的 error tool-result 消息——不一致**。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**推荐:基于 `content_block_stop` 的完整性标志 + 选择性执行**。
|
||||
|
||||
1. 在 `anthropic-messages.ts:675-705` `content_block_stop` 分支设 `block.complete=true`(截断块无此事件故 false);将该标志透传到 agent-loop 层的 toolCall 对象。
|
||||
2. 在 agent-loop.ts:211-214 把三元改为:`stopReason==="length"` 时按 `complete` 拆分 `toolCalls`,complete 的走 `executeToolCalls`(子集),incomplete 的走 `failToolCallsFromTruncatedMessage`。
|
||||
3. 顺带修 agent-session.ts:2018-2019 一致性:compact-and-retry 前同时丢弃已塞入的 error tool-result 消息。
|
||||
|
||||
备选 1(auto-续写):截断时不 fail,改注入一条 user/tool 消息让模型从断点续写——改动大、与现有 salvage-then-fail 架构冲突,不推荐首选。
|
||||
备选 2(提示重发):保留 fail-all 但给模型更明确重发指令——零风险但治标不治本。
|
||||
备选 3(仅末块 fail):启发式只 fail 最后一个 toolCall——若辅以 `complete` 标志则等价于推荐方案。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
无工具 schema 改动(纯内部)。改 `Block`/toolCall 类型加 `complete?:boolean`(anthropic-messages.ts:616 块定义 + agent-loop toolCall 透传)。`failToolCallsFromTruncatedMessage` 拆出 `failToolCall`(单数)供选择性路径复用。
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F11 glm-5.2 适配**:缺陷 #7 命门一(thinking 吃光 token 触发 length)是 length 的主要触发源。F11 先把 max_tokens 提到 ≥8192 + enable_thinking:false,本功能只是缓解不是根治——两者配合才能彻底解闭环卡死。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. 构造 max_tokens 截断场景:模型原计划发 3 个 tool_use,前 2 个完整(收到 content_block_stop)、第 3 个截断。前 2 个被执行(结果入上下文),仅第 3 个标 error 提示重发。
|
||||
2. 截断的 incomplete 块(salvage 后 schema 校验通过但值被截)**不被执行**(靠 `complete:false` 而非 schema 校验把关)。
|
||||
3. compact-and-retry 路径触发时,已塞入的 error tool-result 消息与截断 assistant 消息一并丢弃,重试轮无孤儿 error 消息污染上下文。
|
||||
4. 正常 stopReason==="toolUse"(非 length)路径零回归。
|
||||
5. agent 轮次继续(terminate:false 保持),模型能基于已执行的 2 个结果 + 1 个 error 重发第 3 个,闭环不卡死。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- **最高风险项**。原设计 fail-all 是防"parse 通过但语义不全"的静默损坏——改它必须靠 provider 的 `content_block_stop` 信号而非 `JSON.parse`/`validateToolArguments`(后者已证实不足以把关,validation.ts:317-350)。
|
||||
- OpenAI Responses / proxy 路径(proxy.ts:219/354/359、openai-responses.ts)也需同步透传 `complete` 标志,否则跨 provider 不一致。
|
||||
- 与缺陷 #7 耦合:若 glm-5.2 侧 max_tokens 不提,本功能收益受限。建议先做 `complete` 标志透传 + 选择性执行的最小集,auto-续写留后。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P2 中**(治"长反馈回路"效率塌方;与缺陷 #7 耦合,单独做收益受限于模型侧 max_tokens;但失败语义正确性提升明显)|**3-4 人日**。
|
||||
76
Docs/F05_硬件安全门破坏性命令拦截与资源锁.md
Normal file
76
Docs/F05_硬件安全门破坏性命令拦截与资源锁.md
Normal file
@ -0,0 +1,76 @@
|
||||
# F05 硬件安全门:破坏性命令拦截 + 资源锁 + allowed-tools(F-SAFEGATE)
|
||||
|
||||
> **治缺陷**:#3(无运行时权限门,dd/rm/reboot 零拦截)/ #11(工具并行默认开启,串口/JTAG/flash 并发撞车)/ #19(skills allowed-tools 字段零解析)
|
||||
> **场景锚定**:`dd if=sdcard.img of=/dev/mmcblk0` 烧错盘号毁宿主系统盘;`dd of=/dev/sda` 抹系统;`rm -rf /sys/class/gpio/*` 破坏内核 GPIO 状态;`reboot`/`init 6` 断板。烧错分区=砖板要拆芯片 SPI 编程器物理恢复。同串口/JTAG/flash 并发(minicom 与 st-flash 抢 /dev/ttyUSB0)。GPIO skill 应只许 gpio-set 不许 dd。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
- pi 无运行时权限门:`SECURITY.md:50` "the Pi coding agent intentionally does not have a sandbox"。唯一门是加载期 project trust(未信任项目不加载 `.pi/` 资源)。`agent-session.ts` 中 grep `permission`/`allow`/`deny` 零命中。
|
||||
- 工具并行默认:`agent.ts:237` `this.toolExecution = ... ?? "parallel"`;`agent-loop.ts:489-553` `executeToolCallsParallel` 用 `Promise.all`(:540-542)。
|
||||
- `tool_call` 钩子已存在但未用于硬件安全:`types.ts:1241` `on(event:"tool_call", handler)`;`types.ts:1071-1080` `ToolCallEventResult: {block?, reason?, terminate?}`。**fail-closed**(`agent-session.ts:493-498`):`emitToolCall` 抛异常 catch 并 throw "Extension failed, blocking execution"=阻断工具。`agent-loop.ts:636-644` `prepareToolCall` 内 block 逻辑。`runner.ts:932-953` 任一 handler 返回 `{block:true}` 立即短路。
|
||||
- `executionMode` sequential 机制:`agent/types.ts:42` `ToolExecutionMode="sequential"|"parallel"`;`:408` `AgentTool.executionMode?`;`extensions/types.ts:477` `ToolDefinition.executionMode?`;`agent-loop.ts:419-425` 任一工具声明 sequential 整批降级。
|
||||
- skills allowed-tools 零解析:`skills.ts:67-72` `SkillFrontmatter` 只 name/description/disable-model-invocation + `[key:string]:unknown`;`skills.ts:310-317` `loadSkillFromFile` 不提取 allowed-tools。全仓 grep `allowed-tools|allowedTools` 零命中。
|
||||
- 现成范本:`examples/extensions/permission-gate.ts`——`pi.on("tool_call")` 拦截 bash 危险命令(rm -rf/sudo/chmod 777),返回 `{block:true, reason}`,`!ctx.hasUI` 时 fail-closed 直接 block。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**三合一,全部复用 pi 现有扩展事件系统,无需新 npm 包**:
|
||||
|
||||
### 方案 1 破坏性命令拦截(推荐=新建扩展,零核心改动)
|
||||
在扩展目录新增 `hardware-safegate.ts`(参照 `permission-gate.ts`)。注册 `pi.on("tool_call", handler)`(types.ts:1241)。拦截 `event.toolName==="bash"` 时检查 `event.input.command`。破坏性命令模式表:`dd if=.*of=/dev/`、`rm -rf /`、`reboot`、`init`、`shutdown`、`mkfs`、`flashcp`/`flash_erase`/`nandwrite`、sysfs 直写 `/sys/class/gpio` 等。设备节点确认:对 `/dev/mtd*`、`/dev/sd*`、`/dev/mmcblk*`、`/dev/i2c-*`、`/dev/spidev*`、`/dev/ttyS*` 做正则匹配。返回 `{block:true, reason}`。`!ctx.hasUI` 直接 block(fail-closed),有 UI 可选 `ctx.ui.confirm()` 供人工放行。fail-closed 已内建(agent-session.ts:493-498)。
|
||||
|
||||
### 方案 2 共享资源锁(推荐=设 executionMode:"sequential" + 扩展级互斥)
|
||||
硬件工具通过 `registerTool` 注册时直接设 `executionMode:"sequential"`(types.ts:477)→ 触发 `agent-loop.ts:419-422` 整批降级串行。走 bash 命令则用扩展 `tool_call` 钩子维护资源占用集合,检测访问已锁定设备节点时返回 `{block:true}`。可选 `session_start` 钩子(types.ts:1205)初始化资源锁表,`tool_result` 钩子(types.ts:1242)释放锁。
|
||||
|
||||
### 方案 3 per-skill allowed-tools 白名单(推荐=改 skills.ts 三处 + tool_call 钩子)
|
||||
1. `skills.ts:67-72` 给 `SkillFrontmatter` 加 `"allowed-tools"?: string[]`。
|
||||
2. `skills.ts:74-81` `Skill` 接口加 `allowedTools?: string[]`;`skills.ts:310-317` 从 `frontmatter["allowed-tools"]` 提取赋值(`parseFrontmatter` 已用 YAML parse,字段已在 `[key:string]:unknown` 兜底槽,无需改解析器)。
|
||||
3. tool_call 钩子读当前激活 skill 的 `allowedTools`,`event.toolName` 不在白名单返回 `{block:true}`。需确认 ExtensionContext 是否暴露当前激活 skill——若不暴露需在 `agent-session.ts` 加 `activeSkill` 状态。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
// skills.ts:67-72 扩展 SkillFrontmatter
|
||||
export interface SkillFrontmatter {
|
||||
name?: string; description?: string;
|
||||
"disable-model-invocation"?: boolean;
|
||||
"allowed-tools"?: string[]; // 新增
|
||||
[key: string]: unknown;
|
||||
}
|
||||
// Skill 接口加 allowedTools?: string[]
|
||||
// 硬件安全门扩展复用 ToolCallEventResult (types.ts:1071-1080)
|
||||
// 破坏性命令表(扩展内常量):
|
||||
interface DestructivePattern { pattern: RegExp; reason: string; deviceNode?: RegExp; }
|
||||
```
|
||||
无需改 `BeforeToolCallResult`(agent/types.ts:61-69)或 `ToolCallEventResult`——现有 `{block, reason, terminate}` 三字段已满足全部需求。
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F13 安全烧录**:F05 拦截裸 `dd of=/dev/` → 收束到 F13 flash 工具内。
|
||||
- **F19 硬件验证**:F05 "verify 前不许下一步"靠 `tool_call` 钩子 block。
|
||||
- **F20 闭环编排**:F05 检测 flash 操作但编译未过时 block。
|
||||
- **F01 持久 Shell**:pshell 会话内破坏性命令仍需门控。
|
||||
- **F14/F15 外设/JTAG**:声明 `executionMode:"sequential"` 防总线/JTAG 并发撞车。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. **破坏性命令拦截**:agent 发 `dd if=/dev/zero of=/dev/mmcblk0` 或 `reboot` 时,tool_call 钩子返回 `{block:true}`,工具不执行,agent 收到 error tool result 含 reason。正常命令(`ls /dev`)不受影响。
|
||||
2. **fail-closed**:禁用扩展 UI(`ctx.hasUI === false`)时破坏性命令直接 block;钩子自身抛异常时 `agent-session.ts:493-498` catch 并阻断执行。
|
||||
3. **共享资源锁**:两个 `executionMode:"sequential"` 硬件工具同 message 调用时走 `executeToolCallsSequential`(:433-487),第二个在第一个完成后才执行。
|
||||
4. **per-skill allowed-tools**:SKILL.md frontmatter 写 `allowed-tools: [bash, read]`,agent 激活该 skill 后调 `write` 工具被 block;未设 allowed-tools 的 skill 不受影响。
|
||||
5. **回归无破坏**:无硬件安全门扩展加载时 pi 原有行为零变化(tool_call 无 handler 时 `agent-session.ts:482-483` 直接 return undefined)。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- **bash 命令模式匹配可绕过**:agent 可用变量拼接、eval 规避正则(`x=reboot;$x`)。permission-gate.ts 也有同样已知局限。缓解:高危命令二次语义检查或限制 shell 特性。
|
||||
- **skill 激活态追踪**:方案 3 需知道"当前激活 skill",ExtensionContext 是否暴露需确认;若不暴露需在 agent-session.ts 层加状态追踪,侵入较大。
|
||||
- **executionMode 只串行同批**:只保证同一 assistant message 内串行(agent-loop.ts:419-422)。跨 turn/跨 agent 实例竞争不受控——需扩展层文件锁/flock 做进程级互斥。
|
||||
- **扩展加载顺序**:`emitToolCall`(runner.ts:936-950)按扩展注册顺序遍历。安全门应在其他扩展之前注册。
|
||||
- 无新增依赖。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
- 方案 1 破坏性命令拦截:**P0**(零核心改动,一个扩展文件 ~100-150 行即可上线,直接治 #3 砖板)|1-2 人日
|
||||
- 方案 2 资源锁:**P1**(给硬件工具设 sequential,一行字段治 #11)|0.5 人日
|
||||
- 方案 3 allowed-tools:**P2**(改 skills.ts 三处 + skill 激活态追踪,侵入较大治 #19)|2 人日
|
||||
- 合计 **4-5 人日**
|
||||
77
Docs/F06_扩展子进程隔离层.md
Normal file
77
Docs/F06_扩展子进程隔离层.md
Normal file
@ -0,0 +1,77 @@
|
||||
# F06 扩展子进程隔离层(F-ISO)
|
||||
|
||||
> **治缺陷**:#5(扩展 jiti 主进程零隔离,硬件操作扩展 SIGSEGV/资源泄漏带崩整个 agent)
|
||||
> **场景锚定**:嵌入式扩展会直接操作硬件——`i2c-dev` 的 ioctl、`gpio` 的 mmap、USB 仪器的 libusb 调用。这些涉及内核驱动交互和原生 FFI,比纯 JS 文件操作易段错误/总线错误。一个 `i2cdetect` ioctl 参数错误致 SIGSEGV,或 GPIO mmap 后忘 unmap 致资源泄漏,直接带崩整个 pi 进程——session、未落盘上下文、所有扩展全死。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
- 扩展加载 jiti.import 主进程零隔离:`loader.ts:444-455` `createJiti()` + `jiti.import(extensionPath, {default:true})` 在主进程内直接 require/eval 扩展 TS 源码。扩展获得完整 Node.js 主进程权限(fs/child_process/native addons),无 worker thread、无子进程、无沙箱。文档原话"Extensions run with your full system permissions"。
|
||||
- `loader.ts:490-516` `loadExtension()`:resolvePath → loadExtensionModule(jiti.import) → createExtension → createExtensionAPI → `await factory(api)`,factory 在主进程同步/异步执行。
|
||||
- `loader.ts:264-271` `registerTool()` 实现:工具定义直接写入 `extension.tools` Map,调 `runtime.refreshTools()`。
|
||||
- `ToolDefinition` 接口(types.ts:449-498):核心 `execute(toolCallId, params, signal, onUpdate, ctx): Promise<AgentToolResult>`,execute 是普通 async 函数直接在主进程事件循环运行。
|
||||
- `tool-definition-wrapper.ts:5-20` `wrapToolDefinition()` 将 ToolDefinition 转 AgentTool,execute 直接调用 `definition.execute()`,**无任何隔离包装**。
|
||||
- `wrapper.ts:17-37` `wrapRegisteredTool()` 再包一层 active tools 变化检查,仍直接调用。
|
||||
- `agent-session.ts:2471-2529` 工具组装:getAllRegisteredTools → wrapRegisteredTools → 合并 builtin+extension → `_toolRegistry`。
|
||||
- 现有隔离仅 OS 级 sandbox 针 bash 命令(`examples/extensions/sandbox/index.ts` 用 `@anthropic-ai/sandbox-runtime`),**不隔离扩展代码执行**。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
### 方案 1 worker_threads 隔离(备选——对 native crash 无效)
|
||||
改 `ToolDefinition`(types.ts:449)加 `isolated?:"worker"`,改 `wrapToolDefinition()`(tool-definition-wrapper.ts:5-20)对 isolated 工具代理 execute 到 worker。**致命局限**:worker_threads 共享进程地址空间,native addon SIGSEGV(ioctl/mmap)仍带崩整个进程。对 JS 级异常/资源泄漏有效,但对硬件操作场景的 native crash **无效**。
|
||||
|
||||
### 方案 2 独立守护进程 + IPC(推荐——针对硬件操作场景)
|
||||
1. 新增 `packages/coding-agent/src/core/extensions/isolated-process.ts`——用 `child_process.fork()` 管理子进程加载硬件操作扩展模块。主进程通过 stdio JSON-RPC 与子进程通信。
|
||||
2. IPC 协议:`ToolCallRequest`/`ToolCallResponse`/`EventForwardRequest`。子进程加载扩展(jiti.import),注册工具到子进程内 ExtensionAPI stub,将工具 schema 回传主进程。主进程代理工具调用到子进程。
|
||||
3. 改 `loader.ts:490-516`:对声明 `isolated:"process"` 的扩展路径,不调 `jiti.import`,而 `fork()` 子进程在子进程内 import。主进程接收子进程回传的 ToolDefinition(schema+name+description,不含 execute 函数体),注册到 `extension.tools`。
|
||||
4. 改 `wrapToolDefinition()`:对 isolated 工具 execute 代理为 `sendToolCallRequest(workerPid, toolName, params)` → await IPC 响应。
|
||||
5. 改 `types.ts:449` `ToolDefinition` 加 `isolated?:"process"|"worker"`。
|
||||
6. 事件处理:子进程内扩展的 `pi.on(event, handler)` 通过 IPC 转发到主进程。
|
||||
|
||||
**优势**:SIGSEGV 只杀子进程,主进程 session/上下文/其他扩展存活;资源泄漏随子进程退出回收;可独立重启子进程(crash recovery)。**代价**:IPC 延迟每次工具调用 +1-2 round-trip(~0.5-2ms 本地 stdio,可接受);35+ 事件 handler 转发复杂;ExtensionContext 无法直接传到子进程——需代理子集。
|
||||
|
||||
### 方案 3 外部进程工具(备选——最轻量,纯工具型)
|
||||
不改 loader/ToolDefinition。新增"外部工具"注册路径:扩展不通过 jiti.import 加载,而是配置声明一个外部可执行文件/stdin-stdout JSON 协议的进程作为工具。新增 `ExternalToolDefinition`(无 execute 函数,只有 command+args+schema)。execute 由框架调 `child_process.spawn` 完成。**优势**:最简、天然隔离、无需 jiti。**劣势**:无法使用 ExtensionAPI(事件订阅/sendMessage 等),仅适合纯工具调用。
|
||||
|
||||
**推荐**:方案 2 为首选(硬件操作核心风险是 native crash,worker_threads 无法隔离)。方案 3 作后续补充。分两期:一期方案 3(1-2 人天,纯工具型);二期方案 2 完整 IPC(5-8 人天,需事件交互的扩展)。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
// 1. ToolDefinition 新增隔离标记(types.ts:449)
|
||||
export interface ToolDefinition<TParams, ...> {
|
||||
// 现有字段不变
|
||||
isolated?: "process" | "worker"; // 新增
|
||||
}
|
||||
// 2. 扩展级隔离声明
|
||||
export interface ExtensionIsolationConfig { mode: "process"; maxRestarts?: number; env?: Record<string,string>; }
|
||||
// 3. ExtensionAPI 新增(types.ts:1198)
|
||||
export interface ExtensionAPI { declareIsolation(config: ExtensionIsolationConfig): void; }
|
||||
// 4. IPC 协议消息(新文件 isolated-process.ts)
|
||||
interface ToolCallIPCRequest { type: "tool_call"; toolCallId: string; toolName: string; params: unknown; }
|
||||
interface ToolCallIPCResponse { type: "tool_response"; toolCallId: string; result: AgentToolResult | { error: string }; }
|
||||
interface SerializableContext { cwd: string; mode: ExtensionMode; hasUI: boolean; isIdle: boolean; }
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F14 外设探测 / F15 JTAG-gdb**:所有 native 硬件操作扩展应声明 `isolated:"process"`,防 ioctl/mmap SIGSEGV 带崩主进程。
|
||||
- **F17 板链路**:串口 native fd 操作应外包到独立子进程。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. **崩溃隔离**:编写 isolated 扩展,其 execute 调 `process.kill(process.pid, 'SIGSEGV')`(或加载故意 SIGSEGV 的 native addon)。主进程不崩溃,session 继续可用,工具结果返回 error 而非 pi 退出。
|
||||
2. **资源回收**:isolated 扩展在 execute 中打开 fd 或 mmap 不释放。子进程退出后 `lsof` 确认 fd 全部回收;重启子进程后内存恢复基线。
|
||||
3. **crash recovery**:isolated 扩展子进程崩溃后,后续工具调用触发子进程自动重启(在 maxRestarts 内),重启后工具可正常执行。
|
||||
4. **向后兼容**:未声明 `isolated` 的现有扩展(如 inline-bash.ts、dynamic-tools.ts)加载和执行行为不变,CI 测试全绿。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- **ExtensionContext 不可序列化**:`createContext()`(runner.ts:673)返回对象含 getter、函数引用(ui、sessionManager、modelRegistry)、AbortSignal,无法直接 postMessage。需设计代理层:子进程通过 IPC 向主进程请求 ctx 操作。最大工程复杂度。
|
||||
- **事件系统 35+ 事件转发**:`ExtensionAPI.on()`(types.ts:1203-1244)需逐个适配序列化。
|
||||
- **jiti 在子进程可用性**:子进程需能 require("jiti") 和解析 VIRTUAL_MODULES。Bun binary 模式下 VIRTUAL_MODULES 编译进二进制——子进程若是同一二进制 fork 则 OK(loader.ts:86-142 getAliases)。
|
||||
- **工具 streaming (onUpdate)**:`AgentToolUpdateCallback`(agent/types.ts:383)跨进程需 IPC 转发 partial result,增加延迟。
|
||||
- **UI 交互**:硬件扩展 execute 若需 `ctx.ui.confirm()`(如"确认上电"),需 IPC 往返代理 UI 对话框。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P1 高**——缺陷 #5 是硬件闭环 agent 命门:ioctl/mmap SIGSEGV 杀整个 pi 进程=session、未落盘上下文、所有扩展全死。在第一个硬件扩展(F14/F15)开发之前落地。一期方案 3(1-2 人天);二期方案 2 完整 IPC(5-8 人天)|**合计 6-10 人日**。
|
||||
82
Docs/F07_嵌入式环境自动探针注入.md
Normal file
82
Docs/F07_嵌入式环境自动探针注入.md
Normal file
@ -0,0 +1,82 @@
|
||||
# F07 嵌入式环境自动探针注入(F-ENVSRC)
|
||||
|
||||
> **治缺陷**:#13(system prompt 无 env/toolchain/date 注入,交叉编译环境靠 AGENTS.md 手写)
|
||||
> **场景锚定**:交叉编译的关键环境信息——目标板型号(RDK X5 vs S100 vs S600)、交叉工具链版本(arm-none-eabi-gcc 10.3 vs 12.2)、内核版本(5.4 vs 6.1)、ROS 发行版(humble vs tros)、dtc 版本(1.6 vs 1.7)——这些直接决定编译命令、链接选项、API 选择。pi 不注入,agent 每次都要自己 bash `uname -a` + `arm-none-eabi-gcc --version` + `cat /proc/device-tree/model` 探,吃 tool call 且易忘。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
- `system-prompt.ts:28` `buildSystemPrompt(options)` 组成:角色+工具+guidelines(:121-138)→ `appendSystemPrompt`(:41,:140-142,静态,由 `_resourceLoader.getAppendSystemPrompt()` 填充 `agent-session.ts:1040-1042`)→ `<project_context>`(:145-152 即 AGENTS.md)→ skills(:155-157)→ cwd(:159)。**确认:无 git/env/toolchain/date/uname 动态注入**。
|
||||
- `_rebuildSystemPrompt`(agent-session.ts:1023-1057)仅在三个时机调用:init(:941)、工具集变更(:941)、资源重载(:2283)。产出 `_baseSystemPrompt`(:373)静态基线,不随每轮更新。
|
||||
- **`before_agent_start` 事件——关键注入点**:`extensions/types.ts:699-709` payload 含 `prompt`/`images`/`systemPrompt`(完整已组装提示)/`systemPromptOptions`。结果类型 `types.ts:1102-1106` `BeforeAgentStartEventResult: {systemPrompt?, message?}`(替换整个提示/注入自定义消息)。Runner 链式 `runner.ts:1081-1145`:多 handler 按注册顺序链式调用,`currentSystemPrompt`(:1087)被每个 handler 返回值更新(:1119-1120),下一个 handler 看到上一个修改后的版本——天然支持多扩展叠加。Agent session 发射 `agent-session.ts:1232-1260`:每轮用户提交时触发(非仅 init)。返回 `result.systemPrompt` 赋给 `_systemPromptOverride` 和 `agent.state.systemPrompt`(:1255-1256);无返回重置回 `_baseSystemPrompt`(:1259-1260)。
|
||||
- **`prepareNextTurnWithContext`(agent-session.ts:535-556)不可用**:`:549` `systemPrompt: this._systemPromptOverride ?? this._baseSystemPrompt` 硬覆盖,无论前序链返回什么都被覆写;且仅在 turn 间触发。
|
||||
- 扩展执行能力:`ExtensionContext`(types.ts:307-347)不暴露 bash/exec,但有 cwd(:315)、signal(:334)。扩展可直接 `import { execSync, spawnSync } from "node:child_process"`(已被 `truncated-tool.ts:28`、`interactive-shell.ts:23`、`mac-system-theme.ts:8` 验证)。
|
||||
- 现成范本:`examples/extensions/pirate.ts:28-46` 在 `before_agent_start` 中 `return { systemPrompt: event.systemPrompt + ... }`——与 F-ENVSRC 需求完全同构。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**推荐:`before_agent_start` 扩展注入(零源码改动)**
|
||||
|
||||
1. 新建扩展 `~/.pi/agent/extensions/embedded-env-probe.ts`(或项目 `.pi/extensions/`),**不改 pi 源码**。
|
||||
2. 注册 `pi.on("before_agent_start", handler)`(types.ts:1227 的 on 重载)。
|
||||
3. handler 内用 `execSync` from `node:child_process` 执行探针命令(3s 超时,失败容错返回 "[unavailable]")。
|
||||
4. handler 返回 `{ systemPrompt: event.systemPrompt + probeBlock }`(runner.ts:1119-1120 链式更新)。
|
||||
5. 结果经 `agent-session.ts:1255-1256` 赋给 `_systemPromptOverride` + `agent.state.systemPrompt`,对当轮 LLM 请求生效。
|
||||
6. 缓存策略:首次 `before_agent_start` 跑全部探针,缓存结果 + TTL(建议 300s 或会话级)。后续轮次用缓存,避免每轮 fork 10 个进程。检测 cwd 变化或 TTL 过期时重跑。
|
||||
|
||||
备选(静态注入):在 `_rebuildSystemPrompt` 的 `appendSystemPrompt` 选项(agent-session.ts:1041-1042)注入一次探针结果。缺点:探针只跑一次,板换/重启不更新;需改 pi 源码。
|
||||
|
||||
## 3. 探针清单 + 注入格式
|
||||
|
||||
| 探针 | 命令 | 用途 |
|
||||
|---|---|---|
|
||||
| 内核版本 | `uname -r` | 区分板内核 |
|
||||
| 架构 | `uname -m` | aarch64/armv7l/x86_64 |
|
||||
| 全量内核 | `cat /proc/version` | gcc 版本+内核构建信息 |
|
||||
| 设备树型号 | `cat /proc/device-tree/model 2>/dev/null \|\| true` | 板型号(RDK X5/S100/S600) |
|
||||
| ARM GCC | `arm-none-eabi-gcc --version 2>/dev/null \|\| true` | 裸机交叉编译器 |
|
||||
| AArch64 GCC | `aarch64-linux-gnu-gcc --version 2>/dev/null \|\| true` | Linux 交叉编译器 |
|
||||
| DTC | `dtc --version 2>/dev/null \|\| true` | 设备树编译器 |
|
||||
| 本机 GCC | `gcc --version 2>/dev/null \|\| true` | 宿主编译器 |
|
||||
| USB 设备 | `lsusb 2>/dev/null \|\| true` | 外设探测 |
|
||||
| Git 信息 | `git -C ${cwd} rev-parse --short HEAD 2>/dev/null \|\| true` | 仓库版本 |
|
||||
|
||||
注入格式(追加到 `event.systemPrompt` 尾部):
|
||||
```
|
||||
<embedded_environment>
|
||||
Board/Host environment (auto-probed, do not edit):
|
||||
- Kernel: {uname -r} / {uname -m}
|
||||
- Board model: {/proc/device-tree/model or "unknown"}
|
||||
- Cross-compiler (bare-metal): {arm-none-eabi-gcc version or "not installed"}
|
||||
- Cross-compiler (aarch64-linux): {aarch64-linux-gnu-gcc version or "not installed"}
|
||||
- Device tree compiler: {dtc version or "not installed"}
|
||||
- Host compiler: {gcc version}
|
||||
- Git HEAD: {short hash or "not a git repo"}
|
||||
- USB devices: {lsusb summary or "lsusb not available"}
|
||||
</embedded_environment>
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F12 交叉编译**:F12 的 xcompile 工具读取 F07 注入的 `PI_TARGET_TRIPLE`/`PI_SYSROOT` 环境变量作默认 triple。
|
||||
- **F15 JTAG/gdb**:F07 注入 `PI_OPENOCD_CFG` 路径,debugger 工具据此选 board.cfg。
|
||||
- **F16 设备树**:F07 注入 `PI_DTC_VERSION`/`PI_KERNEL_DTS_DIR`(内核 `arch/arm64/boot/dts/`),`dt compile` 自动加 `--include-dir`。
|
||||
- **F17 板链路**:F17 board 注册表的 model/toolchain 字段被 F07 订阅注入。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. **注入可见性**:启用扩展后用 `/prompt` 或 `ctx.getSystemPrompt()`(types.ts:346)查看系统提示,`<embedded_environment>` 段落存在且含探针结果。
|
||||
2. **探针容错**:板无 `arm-none-eabi-gcc` 时对应行显示 `not installed` 而非崩溃;`before_agent_start` handler 不抛异常(runner.ts:1124-1133 的 catch 会 log 但不阻断)。
|
||||
3. **每轮生效**:连续提交两个不同 prompt,两轮 `agent.state.systemPrompt`(agent-session.ts:1255-1256)都含 `<embedded_environment>`;探针缓存命中时第二轮不 fork 新进程。
|
||||
4. **链式叠加**:同时启用 `pirate.ts` 和本扩展时,系统提示同时含 pirate 段落和 embedded_environment 段落(runner.ts:1119-1120 链式更新)。
|
||||
5. **内容正确性**:在 RDK X5/S100 板上跑 pi,`Board model` 含实际 `/proc/device-tree/model` 值,`Kernel` 含实际内核版本,`uname -m` 返回 `aarch64`。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- **延迟**:`before_agent_start` 在用户提交到 LLM 请求的关键路径上(agent-session.ts:1232),10 个 execSync 串行约增 200-500ms。用缓存(首次跑+TTL 复用)可降至首轮一次,后续轮次 <1ms。
|
||||
- **探针阻塞**:execSync 同步阻塞,某命令挂起会卡住整个 `before_agent_start`。必须设 `timeout:3000`;或改用 `spawnSync` 带 timeout。
|
||||
- **设备树路径**:`/proc/device-tree/model` 在非 ARM 板不存在,用 `|| true` + try-catch 容错。
|
||||
- 无源码改动:纯扩展,零维护成本跟随 pi 升级。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P1 高**——缺陷 #13 影响所有嵌入式场景交叉编译决策质量。`before_agent_start` 方案零源码改动、有现成模板(pirate.ts)、链式叠加天然支持,1 个扩展文件完成。与 AGENTS.md 配合(AGENTS.md 项目级静态指令,本扩展运行时动态环境事实,互补)|**1-2 人日**。
|
||||
90
Docs/F08_MCP桥接扩展.md
Normal file
90
Docs/F08_MCP桥接扩展.md
Normal file
@ -0,0 +1,90 @@
|
||||
# F08 MCP 桥接扩展(F-MCP)
|
||||
|
||||
> **治缺陷**:#10(pi 无 MCP,板卡画像/仪器 MCP server 生态零复用)
|
||||
> **场景锚定**:MCP 生态有现成的 i2c scanner、SPI flash reader、GPIO sysfs、示波器/逻辑分析仪/万用表 MCP server。pi 无 MCP,每个嵌入式工具操作都要从零写成 pi 扩展 TS 函数,无法复用生态。板卡画像 MCP server、仪器控制 MCP server 复用性归零。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
- pi 完全无 MCP 依赖:全量 `grep -rn "modelcontextprotocol|@modelcontextprotocol|MCP"` 在 `packages/coding-agent/src/` 零命中;`packages/coding-agent/package.json:62-73` 无 `@modelcontextprotocol/sdk`;`node_modules/@modelcontextprotocol/` 不存在。扩展只走 `registerTool` 注册 TS 函数。
|
||||
- `registerTool` 定义(types.ts:1251-1253):`registerTool<TParams, TDetails, TState>(tool: ToolDefinition<TParams, TDetails, TState>): void`。
|
||||
- `ToolDefinition` 接口(types.ts:449-498):核心字段 `name`(:451)/`label`(:453)/`description`(:455)/`parameters: TParams`(:461, TypeBox schema)/`promptSnippet?`(:457 进系统提示 Available tools 段)/`promptGuidelines?`(:459 进 Guidelines 段)/`execute(toolCallId, params, signal, onUpdate, ctx)`(:480-486) 返回 `Promise<AgentToolResult<TDetails>>`。`prepareArguments?`(:468) schema 校验前修补参数。`executionMode?`(:477)。
|
||||
- `registerTool` 实现(loader.ts:264-271):存入 `extension.tools: Map<string, RegisteredTool>`(types.ts:1702),调 `runtime.refreshTools()`。
|
||||
- 工具进入 agent 列表(agent-session.ts:2463-2529 `_refreshToolRegistry`)::2471 getAllRegisteredTools → :2490-2495 写入 definitionRegistry → :2514 wrapRegisteredTools → :2525-2528 toolRegistry(扩展工具可覆盖同名内置工具)。
|
||||
- `wrapRegisteredTool`(wrapper.ts:17-37):经 `wrapToolDefinition()` 转 AgentTool,包装 execute 注入 `runner.createContext()`。
|
||||
- `ExtensionAPI`(types.ts:1198-1437):`on(event, handler)`(:1203-1244) 含 30+ 事件、`registerTool`(:1251)、`registerCommand`(:1260)、`registerFlag`(:1272)、`registerProvider`(:1417)、`sendMessage`/`sendUserMessage`(:1302-1315)、`exec`(:1334)、`setActiveTools`(:1343)、`events: EventBus`(:1436)。
|
||||
- 现成范本:`examples/extensions/kimi-deferred-tools.ts:16-29` 最简 registerTool;`examples/extensions/tool-override.ts:69-129` 注册同名工具覆盖内置 read;`examples/extensions/with-deps/package.json` 扩展自带 node_modules(jiti 从扩展目录解析依赖 loader.ts:50-74)。
|
||||
- `undici` 已在依赖(package.json:65 `"undici":"8.9.0"`),可用于 SSE transport。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**推荐:写一个 pi 扩展 `mcp-bridge.ts`,内部用 `@modelcontextprotocol/sdk` 作 MCP client,扩展加载时连接 MCP server,枚举其 tools,逐个调 `pi.registerTool()` 转发为 pi ToolDefinition。**
|
||||
|
||||
1. **新增依赖**:在扩展自身 `package.json`(按 `with-deps` 模式,子目录 + `"pi":{"extensions":["./index.ts"]}`)加 `"@modelcontextprotocol/sdk":"^1.x"`。**不改 pi 主包依赖**——扩展通过 jiti 从自身 node_modules 解析(loader.ts:444-453 createJiti + loader.ts:597-640 resolveExtensionEntries)。
|
||||
2. **扩展入口**:新建 `.pi/extensions/mcp-bridge/index.ts`,导出 `ExtensionFactory`(types.ts:1519)。
|
||||
3. **MCP tool → pi ToolDefinition 映射**:
|
||||
- `name` ← MCP tool name(加前缀 `mcp__{server}__{tool}` 避免冲突)
|
||||
- `description` ← MCP tool description
|
||||
- `parameters` ← MCP tool `inputSchema`(JSON Schema)转 TypeBox。**推荐用 `Type.Unsafe<T>(jsonSchema)` 直接包裹透传**;备选递归转换 JSON Schema → TypeBox。
|
||||
- `execute(toolCallId, params, signal, onUpdate, ctx)` ← 调 `client.callTool({name, arguments: params})`,将 MCP result content 映射为 AgentToolResult.content。`signal` 透传 MCP SDK abort 支持。
|
||||
- `executionMode:"sequential"`(MCP server 多有状态)。
|
||||
- `promptSnippet: undefined`(不进系统提示,避免 MCP 工具多时爆 prompt);用 deferred 模式(参考 kimi-deferred-tools.ts)。
|
||||
4. **MCP transport**:stdio(`StdioClientTransport`,spawn 子进程,本地板卡 MCP server)和 SSE(`SSEClientTransport`,底层用 undici 已在依赖,远程仪器/网络 MCP server)。
|
||||
5. **工具刷新**:`pi.registerTool()` 内部调 `runtime.refreshTools()`(loader.ts:270),立即重建 `_toolRegistry`。`on("session_start")` 支持 async handler(types.ts:1193)。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
不改 pi 核心接口。扩展自身新增配置:
|
||||
```
|
||||
interface McpServerConfig {
|
||||
name: string; transport: "stdio" | "sse";
|
||||
command?: string; args?: string[]; env?: Record<string,string>; // stdio
|
||||
url?: string; headers?: Record<string,string>; // sse
|
||||
enabled?: boolean; toolPrefix?: string;
|
||||
}
|
||||
// CLI flag(pi.registerFlag, types.ts:1272-1279): --mcp-config <path>, --mcp-disabled
|
||||
```
|
||||
工具转发后的 pi ToolDefinition:
|
||||
```
|
||||
{
|
||||
name: `mcp__${serverName}__${mcpToolName}`,
|
||||
label: mcpToolName,
|
||||
description: `[${serverName}] ${mcpTool.description}`,
|
||||
promptSnippet: undefined, // deferred 模式
|
||||
parameters: Type.Unsafe(jsonSchema), // 透传 MCP inputSchema
|
||||
executionMode: "sequential",
|
||||
async execute(toolCallId, params, signal) {
|
||||
const result = await mcpClient.callTool({name: mcpToolName, arguments: params}, undefined, {signal});
|
||||
return { content: mapMcpContent(result.content), details: {server, tool: mcpToolName} };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F18 datasheet RAG**:若 MCP 生态有现成 datasheet RAG server,F08 桥接替代 F18 自建向量库(与 F18 互补)。
|
||||
- **F14 外设探测 / F15 JTAG**:可桥接外部仪器 MCP server(示波器/逻辑分析仪)。
|
||||
- **F05 硬件安全门**:MCP 工具的破坏性操作仍受 `tool_call` 钩子门控。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. **stdio transport 端到端**:启动一个 stdio MCP server(如 SDK echo 示例),pi 加载 `mcp-bridge` 扩展,LLM 能看到并调用 `mcp__{server}__echo` 工具,结果正确返回。
|
||||
2. **SSE transport 端到端**:启动 SSE MCP server,pi 扩展通过 undici/fetch 连接,LLM 能调用其工具。
|
||||
3. **工具 schema 透传正确**:MCP tool 的 `inputSchema` 含 required/optional/enum/嵌套对象时,LLM 生成的工具调用参数能通过 schema 校验并正确转发。
|
||||
4. **生命周期安全**:pi `/reload` 或退出时,MCP client 正确关闭(子进程退出/SSE 连接断开),无泄漏。`reload` 后 `pgrep -f mcp-server` 无残留进程。
|
||||
5. **工具名冲突与覆盖**:两个 MCP server 同名 tool 时 `mcp__{server}__` 前缀确保无冲突;MCP tool 与 pi 内置 tool 同名时按 agent-session.ts:2525-2528 覆盖内置工具。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- **新增依赖 `@modelcontextprotocol/sdk`**:不在 pi 主包,放扩展自身 package.json(with-deps 模式)。Bun 二进制编译模式下扩展目录需自带 node_modules 或用户 npm install——最大部署风险。
|
||||
- **TypeBox `Type.Unsafe` 透传**:接受任意 JSON Schema 但 compile 时不做结构推断,LLM 看到的 schema 描述取决于 MCP server 的 inputSchema 质量。需验证 pi 的 schema→LLM tool 定义序列化路径正确处理 Type.Unsafe。
|
||||
- **stdio 子进程管理**:MCP SDK 管理子进程 spawn/stdin/stdout,与 pi 的 `pi.exec()`(types.ts:1334)独立路径无冲突。但子进程 stderr 需处理,避免干扰 pi TUI。
|
||||
- **SSE 长连接稳定性**:undici 8.9.0 支持 SSE,但网络断连/重连需 MCP SDK 处理;pi 扩展无内置重连机制。
|
||||
- **工具数量爆炸**:一个 MCP server 可能暴露 50+ 工具,全量注册撑大系统提示。缓解:`promptSnippet: undefined` + deferred 模式(先注册 `tool_search` 搜索工具,LLM 按需 setActiveTools 激活具体 MCP 工具)。
|
||||
- **MCP server 不可用时 fail-closed**:session_start 中 MCP 连接失败应 `ctx.ui.notify` 警告但不阻塞 pi 启动。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
- P1 MVP:stdio transport only——连接本地 MCP server,枚举 tools,registerTool 转发,execute 调 callTool。验证 schema 透传 + 全链路。参考 with-deps 模式管理依赖。|3-4 人日
|
||||
- P2 生产化:SSE transport;session_shutdown 清理 + reload 重建;deferred tool 模式。|2-3 人日
|
||||
- P3 完整生态:MCP resources → pi 工具映射;MCP prompts → pi slash command 映射;多 server 配置 + --mcp-config flag。|2-3 人日
|
||||
- **合计 5-8 人日**
|
||||
127
Docs/F09_PiServerService生产实现.md
Normal file
127
Docs/F09_PiServerService生产实现.md
Normal file
@ -0,0 +1,127 @@
|
||||
# F09 PiServerService 生产实现(F-SERVER)
|
||||
|
||||
> **治缺陷**:#6(pi 无法多会话服务化,AgentHarness 操作方法全 unavailable)/ #20(pi-server 无生产实现 + locked 恒 true + 协议层无认证)
|
||||
> **场景锚定**:eval 平台批量跑 HWE-Bench 嵌入式题——每题一个 session,RPC 驱动 prompt/abort/get_state。当前 AgentHarness 全抛 HarnessNotImplemented、pi-server 无生产 PiServerService,只能走 RPC 子进程模式(每题 spawn 一个 Node 进程,资源开销大、无多会话管理)。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
| 组件 | 文件:行号 | 现状 |
|
||||
|---|---|---|
|
||||
| PiServerService 接口 | `server/src/types.ts:54-60` | 4 方法 listSessions/listModels/createSession/openSession,纯接口无实现 |
|
||||
| PiSessionRuntime 接口 | `server/src/types.ts:42-52` | 8 方法 snapshot/getPhase/prompt/steer/abort/setModel/setThinking/subscribe/dispose,无 concrete 实现 |
|
||||
| PiServer 构造 | `server/src/server.ts:54` | 接收外部 service,无默认值;委托 LiveSessionManager |
|
||||
| LiveSessionManager | `server/src/sessions.ts:38-346` | 9 命令分发(list/create/attach/detach/prompt/steer/abort/set_model/set_thinking)调 service |
|
||||
| locked 硬编码 | `server/src/sessions.ts:286` | `locked: true` 恒真,normalizedSnapshot() 写死 |
|
||||
| AgentHarness unavailable | `agent/src/harness/agent-harness.ts:355-357` | unavailable() 抛 HarnessNotImplemented;prompt/steer/abort/compact/resume/navigateTree 全走此路径(:365-421) |
|
||||
| AgentHarness on() | `agent-harness.ts:326-327` | hooks/events 用 UnavailableRegistry,on() 抛异常 |
|
||||
| 协议无认证 | `server/src/connection.ts:5` | ByteConnection 注释"authorized"但无代码;listener.ts 注释"after transport auth"靠传输层 |
|
||||
| 参考实现 | `server/src/testing/service.ts:50-287` | TestServerService+TestSessionRuntime——唯一完整实现,用 StoredSession 假数据 |
|
||||
| CLI server 命令 | `coding-agent/src/cli/experimental/commands/server.ts` | 已有 --auth-token/--auth-token-file;AuthInput 在 `cli/experimental/auth.ts` |
|
||||
| Unix 传输 | `server/src/transports/unix/listener.ts:37` | UnixListener 用 0o600 socket 权限做传输层认证 |
|
||||
| agentLoop 入口 | `agent/src/agent-loop.ts:95-118` | runAgentLoop(prompts, context, config, emit, signal, streamFn) |
|
||||
| SessionManager.inMemory | `session-manager.ts:1568-1569` | 静态工厂,persist=false 不落盘 |
|
||||
| SessionManager.create | `session-manager.ts:1519-1521` | 新建 JSONL |
|
||||
| SessionManager.open | `session-manager.ts:1530-1549` | 打开已有 JSONL |
|
||||
| SQLite WAL 后端 | `session-backends/sqlite-node/src/` | 完整 SQLite 存储层,与 coding-agent SessionManager 独立包 |
|
||||
| RPC 命令集 | `coding-agent/src/modes/rpc/rpc-types.ts:20-73` | stdin/stdout JSONL,9 类命令 |
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**推荐:实现 `ProductionServerService` + `AgentSessionRuntime`,桥接 PiServer 协议到 AgentSession。**
|
||||
|
||||
核心思路:PiServerService/PiSessionRuntime 是纯接口(types.ts:42-60),server 包不提供实现。写一个 concrete class 把 AgentSession(coding-agent 完整会话实现)包装成 PiSessionRuntime,让 PiServer 协议层直接驱动真实 agent loop。
|
||||
|
||||
**改动清单**:
|
||||
|
||||
1. **新建 `packages/coding-agent/src/server/service.ts`——ProductionServerService**(实现 PiServerService 接口 types.ts:55-60):
|
||||
- `listSessions()`:扫描 session 目录(复用 SessionManager 的 listSessions 逻辑,session-manager.ts:824 过滤 .jsonl)
|
||||
- `listModels()`:从 provider 注册表返回可用模型列表
|
||||
- `createSession(options)`:SessionManager.create(options.cwd, sessionDir, options) → AgentSession 初始化(model/thinkingLevel/tools)→ 包装 AgentSessionRuntime 返回
|
||||
- `openSession(sessionId)`:SessionManager.open(path) → 包装 AgentSessionRuntime
|
||||
|
||||
2. **新建 `packages/coding-agent/src/server/runtime.ts`——AgentSessionRuntime**(实现 PiSessionRuntime 接口 types.ts:42-52,8 方法):
|
||||
|
||||
| 方法 | 实现要点 | 桥接目标 |
|
||||
|---|---|---|
|
||||
| `snapshot()` | agentSession.getSessionStats() + sessionManager.buildSessionContext() 构造 SessionSnapshot | types.ts:43 |
|
||||
| `getPhase()` | 检查 agentSession.isStreaming/isCompacting → "idle"/"turn"/"compacting" | types.ts:44 |
|
||||
| `prompt(input)` | agentSession.prompt(input.text, input.images) | types.ts:45 |
|
||||
| `steer(input)` | agentSession.steer(input.text, input.images) | types.ts:46 |
|
||||
| `abort()` | agentSession.abort() | types.ts:47 |
|
||||
| `setModel(model)` | agentSession.setModel(provider, modelId) | types.ts:48 |
|
||||
| `setThinking(level)` | agentSession.setThinkingLevel(level) | types.ts:49 |
|
||||
| `subscribe(listener)` | 包装 agentSession.on("message_end"|"turn_end"|"error", ...) → 发射 PiSessionRuntimeEvent | types.ts:50 |
|
||||
| `dispose()` | agentSession.close(),释放资源 | types.ts:51 |
|
||||
|
||||
关键:AgentSession 已有完整 prompt/steer/abort/compact 实现(agent-session.ts:305),agentLoop 由 AgentSession 内部调用。不需手动包装 agentLoop。
|
||||
|
||||
3. **改 `server/src/sessions.ts:286`——locked 真实化**:`locked: live.runtime.getPhase() !== "idle"`(getPhase 已是接口方法)。
|
||||
|
||||
4. **认证——传输层加 token 验证**:CLI 已有 --auth-token(server.ts:27-28, auth.ts),AuthInput={type:"token",token}|{type:"file",path}。新建 `packages/server/src/transports/authenticated.ts` 包装 PiServerListener,在 accept 回调验证 token;握手协议 ClientHello 增 `authToken?:string`(protocol schemas.ts HelloSchema),server 端 `finishHandshake`(server.ts:221-249)校验。mTLS 备选。
|
||||
|
||||
5. **新建 `coding-agent/src/cli/experimental/commands/server.ts` 扩展——runServer 实现**:创建 ProductionServerService → 创建 PiServer(传入 service+listener)→ 启动。
|
||||
|
||||
**备选**:不实现 PiServerService,用现有 RPC 模式(rpc-client.ts),eval 批量跑题 spawn 多个 `pi --mode rpc` 子进程。优点零改动;缺点进程开销大、无多会话管理、无网络层。适用低并发原型。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
// 新增 service.ts
|
||||
export class ProductionServerService implements PiServerService {
|
||||
constructor(options: { cwd: string; provider: string; modelId: string; sessionDir?: string; tools?: HarnessTool[]; });
|
||||
listSessions(): Promise<SessionMetadata[]>;
|
||||
listModels(): Promise<ModelMetadata[]>;
|
||||
createSession(options: CreateSessionOptions): Promise<PiSessionRuntime>;
|
||||
openSession(sessionId: string): Promise<PiSessionRuntime>;
|
||||
}
|
||||
// 新增 runtime.ts
|
||||
export class AgentSessionRuntime implements PiSessionRuntime {
|
||||
constructor(agentSession: AgentSession, sessionManager: SessionManager);
|
||||
snapshot(): SessionSnapshot; getPhase(): SessionPhase;
|
||||
prompt(input: PromptInput): Promise<void>; steer(input: SteerInput): Promise<void>;
|
||||
abort(): Promise<void>; setModel(model: ModelRef): Promise<void>;
|
||||
setThinking(level: ThinkingLevel): Promise<void>;
|
||||
subscribe(listener: (event: PiSessionRuntimeEvent) => void): () => void;
|
||||
dispose(): Promise<void>;
|
||||
}
|
||||
// 改 sessions.ts:286
|
||||
- locked: true,
|
||||
+ locked: live.runtime.getPhase() !== "idle",
|
||||
// 改 protocol/schemas.ts HelloSchema(可选)
|
||||
+ authToken: Type.Optional(Type.String()),
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F10 硬件状态持久化**:eval 批量跑题若需硬件状态,F09 多会话服务化是前提。
|
||||
- **F11 glm-5.2 适配**:F09 的每个 AgentSession 需 provider API key + glm-5.2 models.json 配置。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. `createSession()` 返回的 runtime 可以 `prompt("hello")`,agent 真实执行并返回 assistant 响应(snapshot.transcript 含 user+assistant 消息)。
|
||||
2. 并发创建 2+ session,各自独立 prompt,互不干扰(session isolation:不同 SessionManager 实例、不同 JSONL 文件)。
|
||||
3. `snapshot()` 返回真实 SessionSnapshot(id/phase/transcript/model 均非空/非硬编码)。
|
||||
4. 未授权连接(无 token 或 token 错误)在握手阶段被拒绝(failProtocol 返回 auth_error)。
|
||||
5. `abort()` 可中断正在进行的 prompt(getPhase() 从 "turn" 回到 "idle")。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- **AgentSession 生命周期**:AgentSession 非无状态,需管理创建/恢复/销毁;多 session 并发需每 session 一个 AgentSession 实例。
|
||||
- **模型 API key**:每 AgentSession 需 provider API key,生产环境需密钥管理(key 用 `${DROBOTICS_LLM_KEY}` 占位,不入库)。
|
||||
- **资源消耗**:每 session 一个 AgentSession + SessionManager + agentLoop,内存占用需评估。
|
||||
- **并发安全**:LiveSessionManager 的 `acquire()`(sessions.ts:186-207)已有去重和锁机制,多 session 并发需验证。
|
||||
- **SQLite 后端**:若用 session-backends/sqlite-node 替换 JSONL,需适配 SessionManager 存储接口——目前硬编码 JSONL I/O。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P1 高**——eval 批量跑题基础设施,无它只能走 RPC 子进程模式。建议在 F10 之前做。
|
||||
|
||||
| 子任务 | 人日 |
|
||||
|---|---|
|
||||
| ProductionServerService 实现 | 3 |
|
||||
| AgentSessionRuntime 实现(8 方法桥接 + snapshot 构造) | 4 |
|
||||
| locked 真实化 + 集成测试 | 1 |
|
||||
| 认证层(token 握手) | 2 |
|
||||
| CLI server 命令 runServer 实现 | 2 |
|
||||
| 端到端测试(eval 批量场景模拟) | 2-3 |
|
||||
| **合计** | **12-15 人日** |
|
||||
129
Docs/F10_硬件状态Session-Entry持久化.md
Normal file
129
Docs/F10_硬件状态Session-Entry持久化.md
Normal file
@ -0,0 +1,129 @@
|
||||
# F10 硬件状态 Session Entry 持久化(F-HWSTATE)
|
||||
|
||||
> **治缺陷**:#4(session 纯文本 JSONL,零硬件状态/外设会话持久化)/ #14(compaction 视图截断,寄存器值/调试状态被摘要掉)
|
||||
> **场景锚定**:嵌入式闭环中的有状态资源——已开 gdb session 的断点列表、已占用的 i2c 总线地址表、已配置的 GPIO 方向表、OpenOCD 连接状态、串口波特率——这些在 pi session 里无处存。每轮 bash 新进程(缺陷 #1)让 gdb 断点丢、i2c 总线释放、GPIO 方向复位。agent 要么每次重新初始化(吃 tool call),要么靠对话上下文推断状态(不可靠,compaction 后可能被摘要掉,导致重复初始化或错误寄存器操作)。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
| 组件 | 文件:行号 | 现状 |
|
||||
|---|---|---|
|
||||
| Entry 类型联合 | `session-manager.ts:144-153` | 9 种类型,无硬件状态类型 |
|
||||
| CustomEntry | `session-manager.ts:104-108` | type:"custom",有 customType+data,**不参与 LLM 上下文**(:101-102) |
|
||||
| CustomMessageEntry | `session-manager.ts:135-141` | type:"custom_message",有 customType+content+display+details,**参与 LLM 上下文**(:127-128) |
|
||||
| 上下文注入 | `session-manager.ts:383-408` | sessionEntryToContextMessages():custom_message→createCustomMessage(:396-399),custom→[](:407 fall through) |
|
||||
| buildContextEntries | `session-manager.ts:418-454` | compaction-aware:只保留 [compactionEntry, ...firstKeptEntryId之后] |
|
||||
| buildSessionContext | `session-manager.ts:461-470` | 调 buildContextEntries.flatMap(sessionEntryToContextMessages) |
|
||||
| JSONL 写入 | `session-manager.ts:1015-1042` | _persist():JSON.stringify(entry)+"\n",无 per-type 序列化 |
|
||||
| _appendEntry | `session-manager.ts:1044-1049` | push fileEntries + set byId + advance leafId + _persist |
|
||||
| appendCustomEntry | `session-manager.ts:1122-1133` | 追加 CustomEntry |
|
||||
| appendCustomMessageEntry | `session-manager.ts:1171-1189` | 追加 CustomMessageEntry |
|
||||
| CompactionSettings | `agent-harness.ts:338-342` | keepRecentTokens:20000 默认 |
|
||||
| findCutPoint | `compaction/compaction.ts:403-461` | 反向走 accumulating tokens,>=keepRecentTokens 时切 |
|
||||
| metadata 回扫保护 | `compaction/compaction.ts:441-449` | cutIndex 回扫,包含不产出上下文的相邻 entry(custom/label 等) |
|
||||
| session_before_compact 事件 | `extensions/types.ts:592-602` | 含 preparation+branchEntries+reason+willRetry+signal |
|
||||
| SessionBeforeCompactResult | `extensions/types.ts:1117-1120` | {cancel?, compaction?}——可取消或注入自定义 compaction |
|
||||
| hook 调用(手动) | `agent-session.ts:1818-1837` | hasHandlers→emit→if cancel throw / if compaction 跳过默认 |
|
||||
| hook 调用(溢出) | `agent-session.ts:2083-2092` | 第二处调用,同模式 |
|
||||
| convertToLlm | `messages.ts:148-195` | custom 角色映射为 user 消息(:162-169) |
|
||||
| 低层 projector | `agent/src/harness/session/context.ts:14-18` | CustomEntryContextMessageProjector |
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**推荐:双轨制——CustomEntry 持久化 + CustomMessageEntry 上下文注入 + session_before_compact 钩子保护**。三层配合,不需新增 entry 类型:
|
||||
|
||||
**第 1 层 持久化——CustomEntry 存储**(session-manager.ts:104-108,已可持久化任意数据到 JSONL,且不受 compaction 摘要影响——sessionEntryToContextMessages 返回 [] 不进摘要文本)。用 `customType:"hardware_state"` 存硬件状态快照:
|
||||
```
|
||||
sessionManager.appendCustomEntry("hardware_state", {
|
||||
device: "i2c-1",
|
||||
occupiedAddresses: [0x48, 0x68, 0x77],
|
||||
capturedAt: "2026-08-13T...",
|
||||
// gdb断点/i2c地址表/gpio方向表/openocd状态/串口波特率
|
||||
});
|
||||
```
|
||||
入口:AgentSession 的 extension API 已暴露 `appendEntry(customType, data)`(agent-session.ts:2385-2391)。
|
||||
|
||||
**第 2 层 上下文注入——CustomMessageEntry 注入 LLM**(session-manager.ts:135-141,自动参与 LLM 上下文,:396-399 创建 custom 消息,convertToLlm :162-169 映射为 user 消息)。用相同 customType 追加 custom_message entry:
|
||||
```
|
||||
sessionManager.appendCustomMessageEntry(
|
||||
"hardware_state",
|
||||
formatHardwareStateAsText(state), // 格式化为 LLM 可读文本
|
||||
false, // display=false,TUI 不渲染
|
||||
{ source: "gdb" } // details 不送 LLM
|
||||
);
|
||||
```
|
||||
CustomMessageEntry 会计入 keepRecentTokens 预算(findCutPoint:421-426 累加 token)。
|
||||
|
||||
**第 3 层 compaction 保护——session_before_compact 钩子**(问题:CustomMessageEntry 在 firstKeptEntryId 之前会被丢弃)。注册 handler 在 compaction 后重新注入硬件状态:
|
||||
```
|
||||
pi.on("session_before_compact", async (event, ctx) => {
|
||||
const lastHwState = [...event.branchEntries].reverse()
|
||||
.find(e => e.type === "custom" && e.customType === "hardware_state");
|
||||
if (lastHwState && event.preparation) {
|
||||
return {
|
||||
compaction: {
|
||||
...event.preparation,
|
||||
summary: (event.preparation.previousSummary ?? "") + "\n\n## Hardware State\n" + formatHwState(lastHwState.data),
|
||||
firstKeptEntryId: lastHwState.id, // 强制保留到硬件状态位置
|
||||
}
|
||||
};
|
||||
}
|
||||
});
|
||||
```
|
||||
关键坐标:钩子注册 types.ts:1213-1214;调用 agent-session.ts:1818-1837(手动)/ :2083-2092(溢出恢复);CompactionResult schema compaction.ts:88-97。
|
||||
|
||||
**备选 B**:新增 HardwareStateEntry 类型——改 session-manager.ts 6 处 + compaction.ts 2 处 + messages.ts 2 处。类型安全、compaction 可特殊处理,但改动面大、与 CustomMessageEntry 功能重叠。
|
||||
**备选 C**:agent 层 projector(context.ts:14-18 注册)——最轻量,只在 agent 包生效,coding-agent CLI 不受益。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
无需新增 entry 类型——复用 CustomEntry + CustomMessageEntry:
|
||||
```
|
||||
// CustomEntry 数据 schema(约定,非类型改动):
|
||||
interface HardwareStateData {
|
||||
device: string; // "i2c-1" | "gpio" | "gdb" | "openocd" | "serial"
|
||||
state: Record<string, unknown>;
|
||||
// 例:{ occupiedAddresses: [0x48, 0x68], direction: {pin33: "out", pin32: "out"} }
|
||||
capturedAt: string; // ISO timestamp
|
||||
source: string; // "gdb" | "i2cdetect" | "gpioget" | "openocd" | "stty"
|
||||
}
|
||||
// session_before_compact handler 返回扩展:
|
||||
interface HardwareStateCompactionResult extends CompactionResult {
|
||||
details?: { protectedEntryIds: string[]; };
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F14 外设探测**:每次 i2c_set/gpio_set/pwm_set 成功后 `appendEntry("hw-state", ...)` 持久化;F10 恢复时重建总线占用/GPIO 方向表;i2c_detect 发现地址已占用时提示"addr 0x50 already in use (set at entry #N)"。
|
||||
- **F15 JTAG/gdb**:断点/watchpoint 列表通过 `appendEntry("debugger-bp", ...)` 持久化;session 恢复时重设断点。
|
||||
- **F19 硬件验证**:四元组(任务/诊断轨迹/judge真值/根因)通过 appendCustomEntry 落库(与 HWE-Bench judges 门同构)。
|
||||
- **F09 服务化**:eval 批量跑题若需共享硬件状态,F09 多会话是前提。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. **持久化**:`appendCustomEntry("hardware_state", data)` 后重启 session(SessionManager.open),`getEntries()` 包含该 entry,数据完整。
|
||||
2. **上下文可见**:`appendCustomMessageEntry("hardware_state", text, ...)` 后 `buildSessionContext().messages` 包含 hardware_state 的 user 消息。
|
||||
3. **compaction 保护**:触发 compact 后,`buildContextEntries()` 返回路径中仍包含 hardware_state custom_message entry(或 compaction summary 中包含硬件状态文本)。
|
||||
4. **跨 tool call 持久**:agent 执行 tool call A(读取 i2c 地址表)→ tool call B 时,LLM 上下文中仍能看到 A 写入的 hardware_state。
|
||||
5. **regression**:现有 session 文件(无 hardware_state entry)正常加载和 compact。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- **token 预算**:CustomMessageEntry 计入 keepRecentTokens 预算,大量硬件状态可能挤占上下文;格式化时控制长度。
|
||||
- **hook 时序**:session_before_compact 异步,handler 慢会阻塞 compaction;需设超时。
|
||||
- **双写一致性**:CustomEntry 和 CustomMessageEntry 是两个独立 entry,需 extension 保证一致性(先写 CustomEntry,再写 CustomMessageEntry)。
|
||||
- **backward compat**:旧 session 文件无 hardware_state entry,加载时正常忽略。
|
||||
- **F09 依赖**:若 eval 批量跑题需硬件状态,F09 须先完成(否则每题独立进程无法共享 session)。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P2 中**——依赖 F09(多会话服务化是 eval 批量前提)。单独做也有价值——单进程 CLI 模式下硬件状态持久化也能提升 agent 跨 tool call 一致性。
|
||||
|
||||
| 子任务 | 人日 |
|
||||
|---|---|
|
||||
| HardwareStateData schema 设计 + 格式化函数 | 1 |
|
||||
| Extension 注册(appendEntry + appendCustomMessageEntry) | 1 |
|
||||
| session_before_compact handler 实现 | 2 |
|
||||
| 集成测试(持久化+上下文+compaction 保护) | 1-2 |
|
||||
| 文档 + 硬件状态格式规范 | 1 |
|
||||
| **合计** | **5-7 人日** |
|
||||
171
Docs/F11_glm-5.2适配兜底层.md
Normal file
171
Docs/F11_glm-5.2适配兜底层.md
Normal file
@ -0,0 +1,171 @@
|
||||
# F11 glm-5.2 适配兜底层(F-GLMADAPT)
|
||||
|
||||
> **治缺陷**:#7(命门一:thinking 默认开吃光 token,max_tokens=2048 零输出)/ #8(命门二:tool arg hex 被强转十进制)/ #15(reasoning 占 25-72%)/ #16(thinkingFormat 误配)/ #17(枚举值波动)/ #18(max_tokens 不足空输出)/ #21(model id 别名混淆)
|
||||
> **场景锚定**:嵌入式寄存器级编码——glm-5.2 默认 thinking 开 + max_tokens=2048 时 reasoning 吃光 100% token → **零输出**(pi-ai 默认参数跑嵌入式代码生成会静默返回空字符串,与缺陷 #12 stopReason length 整批拒执行叠加放大,闭环直接卡死)。tool arg 里 `0x40020000` 被强转十进制 `"1073872896"`,下游 parser 用 `int(addr,16)` 解析得 `0x1073872896` 错误地址——寄存器地址错一位=写错硬件模块=砖板。
|
||||
|
||||
## 1. 现状(源码坐标)
|
||||
|
||||
**命门一 max_tokens + thinking 策略**:
|
||||
- `Model<TApi>.maxTokens` 字段:`ai/types.ts:809`(模型级默认最大输出 token)
|
||||
- `buildBaseOptions()` 默认 maxTokens:`ai/api/simple-options.ts:33` `options?.maxTokens ?? model.maxTokens`
|
||||
- `clampMaxTokensToContext()`:`simple-options.ts:14-18`(按 contextWindow 裁剪)
|
||||
- 请求体写 max_tokens:`ai/api/openai-completions.ts:716-722`(按 `compat.maxTokensField` 决定写 `max_tokens` 还是 `max_completion_tokens`)
|
||||
- thinkingFormat 11 变体定义:`ai/types.ts:566-578`
|
||||
- thinkingFormat 请求构造:`openai-completions.ts:749-846`
|
||||
- Qwen thinkingFormat 实现(发 `enable_thinking` 布尔):`openai-completions.ts:762-763` `(params as any).enable_thinking = !!options?.reasoningEffort`
|
||||
- `detectCompat()` 按 baseUrl 嗅探:`openai-completions.ts:1444-1538`
|
||||
- `getCompat()` 合并:`openai-completions.ts:1544-1569`
|
||||
- `samplingParams` 合入请求体(最后执行,覆盖一切):`openai-completions.ts:886-888` + `simple-options.ts:26-29`
|
||||
|
||||
**命门二 tool-arg hex 归一**:
|
||||
- ToolCall 类型:`ai/types.ts:360-368` `arguments: Record<string, any>`
|
||||
- `toolcall_end` 事件:`ai/types.ts:533`
|
||||
- pi-ai **无响应拦截钩子**:tool_call args 在 `openai-completions.ts:522-555` 流式解析后直接 push 到 stream,无中间修改点
|
||||
- `beforeToolCall` 钩子(agent 层):`agent/src/types.ts:97-107`,`agent-loop.ts:619-647`——可在工具执行前拦截/修改 args
|
||||
- `tool.prepareArguments`(agent 层):`agent/src/types.ts:393`,`agent-loop.ts:586-598`——每工具级 arg 预处理
|
||||
- `afterToolCall` 钩子:`agent/src/types.ts:109-123`,`agent-loop.ts:724-751`
|
||||
|
||||
**thinkingFormat 适配**:
|
||||
- 11 变体:`ai/types.ts:566-578`(openai/openrouter/deepseek/together/baseten/zai/qwen/chat-template/qwen-chat-template/string-thinking/ant-ling)。**无 GLM 专属变体**
|
||||
- reasoning_content 字段读取:`openai-completions.ts:489-520` 搜 `["reasoning_content","reasoning","reasoning_text"]` 三字段,glm-5.2 的 `reasoning_content` 会命中
|
||||
- Qwen thinkingFormat 发 `enable_thinking`:`openai-completions.ts:762-763`
|
||||
- zai/deepseek 发 `thinking:{type:"disabled"}`:`:749-761,797-802`——实测对 GLM 无效
|
||||
|
||||
**model id 规范化**:`coding-agent/src/core/model-resolver.ts:405-530` `resolveCliModel()`,精确匹配(:470-476)+ 模糊匹配(:152-161);无匹配错误(:324,348)。pi-ai 无 model id 别名/纠错。
|
||||
|
||||
**枚举值约束**:Tool 接口 `ai/types.ts:502-507` `parameters: TSchema`;`convertTools()` `openai-completions.ts:1338-1373`;`getJsonSchemaToolParameters()` `ai/api/constrained-sampling.ts:129-131`。TypeBox 支持 `Type.Union([Type.Literal()])` enum。
|
||||
|
||||
**max_tokens 不足检测**:`mapStopReason()` `openai-completions.ts:1413-1434`(finish_reason:"length"→stopReason:"length");`failToolCallsFromTruncatedMessage()` `agent-loop.ts:381-406`;agent loop stopReason 检查 `agent-loop.ts:208-214`;**无"空输出"检测**——reasoning 吃光 100% token 时 finish_reason 仍为 "length" 但无 content,当前静默处理。`MIN_ANSWER_TOKENS` `simple-options.ts:54` =1024。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
### 子项 1 max_tokens 下限门 + thinking 策略(命门一根治,**零代码 models.json 配置**)
|
||||
|
||||
**推荐:models.json 注册 glm-5.2,复用 thinkingFormat:"qwen"**(GLM 的 `enable_thinking:false` 与 Qwen 完全相同参数名和语义,Qwen 分支 `openai-completions.ts:762-763` 当 reasoningEffort 未设时发 `enable_thinking:false`,实测成功关闭 GLM reasoning):
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"d-robotics-glm": {
|
||||
"baseUrl": "https://ai-api.d-robotics.cc/v1",
|
||||
"api": "openai-completions",
|
||||
"apiKey": "$GLM_API_KEY",
|
||||
"compat": {
|
||||
"thinkingFormat": "qwen",
|
||||
"supportsReasoningEffort": false,
|
||||
"maxTokensField": "max_tokens",
|
||||
"supportsDeveloperRole": false,
|
||||
"supportsStore": false
|
||||
},
|
||||
"models": [{
|
||||
"id": "glm-5.2", "name": "GLM 5.2",
|
||||
"reasoning": true, "input": ["text","image"],
|
||||
"contextWindow": 1000000, "maxTokens": 8192,
|
||||
"thinkingLevelMap": { "off": null }
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
关键:`thinkingFormat:"qwen"` + `model.reasoning:true` 触发 thinkingFormat 分支;`supportsReasoningEffort:false` 阻止发无意义 reasoning_effort;`maxTokens:8192` 默认下限门;`maxTokensField:"max_tokens"` GLM 网关用 max_tokens。
|
||||
|
||||
备选 samplingParams 注入(更粗粒度,会覆盖 thinkingFormat 分支,不推荐单独用);备选代码层加 GLM detectCompat(改 pi-ai 源码,升级维护成本高,不推荐)。
|
||||
|
||||
### 子项 2 tool-arg hex 归一(命门二根治,**tool.prepareArguments**)
|
||||
|
||||
**推荐:prepareArguments(每工具级,最干净拦截点)**(agent-loop.ts:590 调用,返回值作 validatedArgs 传入 schema 校验和 execute):
|
||||
```
|
||||
const tool: AgentTool = {
|
||||
name: "read_register",
|
||||
prepareArguments: (args) => {
|
||||
for (const [key, val] of Object.entries(args)) {
|
||||
if (typeof val === "string" && /^\d{8,}$/.test(val)) {
|
||||
const num = parseInt(val, 10);
|
||||
if (num > 0x10000 && num < 0xFFFFFFFF) args[key] = "0x" + num.toString(16);
|
||||
}
|
||||
}
|
||||
return args;
|
||||
},
|
||||
execute: ...
|
||||
};
|
||||
```
|
||||
**关键局限**:`BeforeToolCallResult`(agent/types.ts:56-95)只支持 block+reason+terminate,**不支持替换 args**——故 beforeToolCall 只能阻止不能改 args,必须用 prepareArguments。
|
||||
|
||||
备选:tool description/schema 加更强约束(实测 3/3 一致强转,无法根治);afterToolCall 改 result content(治标,改报错信息让模型下一轮纠正)。
|
||||
|
||||
### 子项 3 thinkingFormat 适配(复用 qwen,零代码)
|
||||
|
||||
GLM `enable_thinking:false` 与 Qwen 完全匹配,**不需新增 GLM 专属变体**。models.json compat 设 `thinkingFormat:"qwen"` 即可。备选(需改源码):types.ts:567-578 加 `|"glm"` 变体 + openai-completions.ts:762 后加 glm 分支 + detectCompat 中加 isGlm 嗅探——当前无必要。
|
||||
|
||||
### 子项 4 model id 规范化(models.json 正确 id)
|
||||
|
||||
models.json 中 `id:"glm-5.2"` 精确匹配网关期望(含点号),`name:"GLM 5.2"` 用于 /model 显示和模糊匹配。备选(需改源码):在 resolveCliModel(model-resolver.ts:324)的 "No models match pattern" 分支加 Levenshtein "Did you mean" 建议。
|
||||
|
||||
### 子项 5 枚举值约束(TypeBox enum)
|
||||
|
||||
```
|
||||
const tool: AgentTool = {
|
||||
parameters: Type.Object({
|
||||
speed: Type.Union([Type.Literal("low"),Type.Literal("medium"),Type.Literal("high"),Type.Literal("very_high")])
|
||||
})
|
||||
};
|
||||
```
|
||||
TypeBox `Type.Union([Type.Literal(...)])` 经 getJsonSchemaToolParameters 转 JSON schema `enum:[...]`,OpenAI function calling 约束输出在枚举范围。备选:prepareArguments 归一化枚举值(speedMap)。
|
||||
|
||||
### 子项 6 max_tokens 不足检测(agent 层空输出提示)
|
||||
|
||||
在 agent-loop.ts:196 之后加空输出检测:
|
||||
```
|
||||
if (message.stopReason === "length" &&
|
||||
!message.content.some(c => c.type === "text" && c.text.length > 0) &&
|
||||
!message.content.some(c => c.type === "toolCall")) {
|
||||
// reasoning 吃光全部 token,零正文零工具调用
|
||||
errorMessage: "Output truncated (finish_reason=length) with no text/tool calls. "
|
||||
+ "Reasoning likely consumed entire token budget. "
|
||||
+ "Try: increase max_tokens (current: " + config.maxTokens + ") or disable thinking (enable_thinking:false).";
|
||||
}
|
||||
```
|
||||
备选:pi-ai 层 stream 结束时检测(openai-completions.ts:585-589);备选 detectCompat 启用 supportsThinkingTokenBudget(GLM 网关未验证,风险高)。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
- models.json 新增 `d-robotics-glm` provider + `glm-5.2` model 条目(子项 1/3/4)
|
||||
- 涉及地址参数的工具定义中加 `prepareArguments` 回调(子项 2)
|
||||
- 工具 schema 用 TypeBox enum 约束模糊值(子项 5)
|
||||
- agent-loop.ts:196 后加空输出检测(子项 6)
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F04 stopReason length 恢复**:F11 命门一(thinking 吃光 token 触发 length)是 length 主要触发源,F11 先把 max_tokens 提到 ≥8192 + enable_thinking:false,F04 才能彻底解闭环卡死。
|
||||
- **F14/F15 外设/JTAG**:prepareArguments hex 归一 + confirm 门是写 MMIO 寄存器零容错的基础防御。
|
||||
- **F09 服务化**:每 AgentSession 需 provider key + glm-5.2 models.json 配置。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. 发往 ai-api.d-robotics.cc/v1 的请求体包含 `"enable_thinking": false`(无 reasoningEffort 时)——子项 1/3。
|
||||
2. 请求体包含 `"max_tokens": 8192`(或经 clamp 后的值),reasoning 占比 <30%(实测 max_tokens=8192 时为 25%)——子项 1。
|
||||
3. 模型输出 `"1073872896"` 作为地址参数时,工具收到的 arg 为 `"0x40020000"`(prepareArguments 归一),日志记录归一前后值——子项 2。
|
||||
4. 无 reasoningEffort 时模型返回 content 非 reasoning 内容;设 reasoningEffort="medium" 时请求体含 `"enable_thinking": true`——子项 3。
|
||||
5. `--model glm-5.2` 正确选中模型——子项 4。
|
||||
6. 模型输出 `"50MHz"` 时经 prepareArguments 归一为 `"high"`(或被 schema 校验拒绝并报错)——子项 5。
|
||||
7. 模拟 finish_reason=length + 无 content 场景,agent 返回可操作 errorMessage 含当前 maxTokens 值和修复建议——子项 6。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- **thinkingFormat:"qwen" 复用风险**:GLM 未来改 enable_thinking 参数名/语义则 Qwen 分支也需改。缓解:models.json 可随时改 thinkingFormat 无需改源码。
|
||||
- **hex 归一化误判风险**:正则 `/^\d{8,}$/` 可能误判合法十进制参数(如 baud rate 115200)。缓解:仅对已知地址类参数名(register/address/base_addr)归一,或检测值范围(>0x10000 且 <0xFFFFFFFF)。
|
||||
- **maxTokens 8192 限制长输出**:可能不足以生成长代码。缓解:按任务类型动态调整(简单问答 4096 + thinking off,代码生成 16384 + thinking on)。
|
||||
- **supportsThinkingTokenBudget 未验证**:GLM 网关可能不支持 vLLM thinking_token_budget 字段。缓解:不启用此 flag。
|
||||
- **models.json 不随版本升级**:pi 升级后 models.json 格式可能变。缓解:升级前检查 CHANGELOG。
|
||||
- **prepareArguments 是 agent 层**:若直接用 pi-ai streamSimple 而非 agent loop(eval 场景),hex 归一不生效。缓解:eval harness 也注入等价逻辑。
|
||||
- **安全铁律**:网关 key 全程 `${DROBOTICS_LLM_KEY}` 占位,不入库不出现在任何文档。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
| 子项 | 优先级 | 理由 | 人日 |
|
||||
|---|---|---|---|
|
||||
| 1+3(max_tokens + thinkingFormat) | **P0** | 命门一根治,零代码 models.json 配置即可 | 0.5 |
|
||||
| 6(空输出检测) | P1 | 命门一兜底,配置错误也给可操作提示防静默失败 | 1 |
|
||||
| 2(hex 归一) | **P0** | 命门二根治,地址错误砖板,prepareArguments 工具定义层 | 1 |
|
||||
| 4(model id) | P2 | 用户体验,低频易错 | 0.5 |
|
||||
| 5(枚举约束) | P2 | 减少波动,逐工具改 schema | 0.5 |
|
||||
| **合计** | | | **3-4 人日** |
|
||||
64
Docs/F12_交叉编译工具链管理.md
Normal file
64
Docs/F12_交叉编译工具链管理.md
Normal file
@ -0,0 +1,64 @@
|
||||
# F12 交叉编译工具链管理(F-XCOMPILE)
|
||||
|
||||
> **满足嵌入式需求维度**:#1 交叉编译工具链
|
||||
> **场景锚定**:嵌入式开发首要事实——宿主机架构 ≠ 目标机架构。x86_64 笔记本上写的 C 代码要用 `aarch64-linux-gnu-gcc`(RDK X5/S100)、`arm-none-eabi-gcc`(bare-metal Cortex-M)、`arm-linux-gnueabihf-gcc`(32 位 Linux ARM)编译后才能在目标板跑。通用 agent 默认用宿主 gcc 编,产物跑 x86 上根本无法在板执行。CMake toolchain file 的 `FIND_ROOT_PATH_MODE` 稍配错就去找宿主 x86 库导致链接失败。选错工具链=闭环后续全废。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
pi 无任何工具链感知:bash 工具每命令新进程(bash.ts:103),system prompt 无 env/toolchain 注入(system-prompt.ts:28,121-138,治由 F07)。工具注册范式参照 `bash.ts:41-44`(TypeBox schema)+ `extensions/types.ts:449-498`(ToolDefinition)+ `types.ts:1251`(registerTool)+ `examples/extensions/dynamic-tools.ts:33-46`。`tool_call` 钩子(types.ts:1071-1080 fail-closed)可拦截宿主 gcc 误用,参照 `examples/extensions/permission-gate.ts`。`BashToolCallEvent`(types.ts:858-861,`toolName==="bash"`)含 `input.command`。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**注册 `xcompile` 工具 + `tool_call` 钩子拦截宿主 gcc 误用**(纯扩展,零源码改动)。
|
||||
|
||||
**工具 `xcompile`** 四件事:
|
||||
1. 选 triple(`aarch64-linux-gnu`/`arm-none-eabi`/`riscv64-unknown-elf` 等)
|
||||
2. 查 sysroot 路径(`aarch64-linux-gnu-gcc -print-sysroot`)
|
||||
3. 生成 `toolchain.cmake`(set CMAKE_SYSTEM_NAME/CMAKE_C_COMPILER/CMAKE_CXX_COMPILER/CMAKE_SYSROOT/CMAKE_FIND_ROOT_PATH_MODE)
|
||||
4. 编译后校验产物架构(`file` 命令确认 `ELF 64-bit LSB ... ARM aarch64` 而非 x86-64)
|
||||
|
||||
工具内部用 `ctx.exec()`(types.ts:1334,exec.ts:11-28)跑探测/校验命令,不依赖 bash 工具。
|
||||
|
||||
**`tool_call` 钩子**监听 `BashToolCallEvent`(types.ts:858-861),正则匹配 `event.input.command` 里裸 `gcc`/`g++`/`cc`/`c++` 调用(非 `aarch64-*`/`arm-none-*`/`riscv-*` 前缀),返回 `{block:true, reason:"宿主 gcc 禁用于嵌入式交叉编译,请用 xcompile 工具选 triple", terminate:true}`。fail-closed 硬门。
|
||||
|
||||
**与 F07 联动**:F07 注入 `PI_TARGET_TRIPLE`/`PI_SYSROOT` 环境变量到 system prompt;xcompile 工具读这些变量作默认 triple,agent 无需每次手选。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
xcompileSchema = Type.Object({
|
||||
action: Type.Union([
|
||||
Type.Literal("select"), // 选/切换 triple
|
||||
Type.Literal("info"), // 查当前工具链信息
|
||||
Type.Literal("toolchain"), // 生成 toolchain.cmake
|
||||
Type.Literal("verify"), // 校验产物架构
|
||||
], { description: "Action to perform" }),
|
||||
triple: Type.Optional(Type.String({ description: "Target triple, e.g. aarch64-linux-gnu, arm-none-eabi. Required for 'select'. Inferred from PI_TARGET_TRIPLE env if omitted." })),
|
||||
build_dir: Type.Optional(Type.String({ description: "Build directory for CMake (used by 'toolchain' action)" })),
|
||||
artifact: Type.Optional(Type.String({ description: "Path to compiled binary, for 'verify' action" })),
|
||||
});
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F07 环境探针**:F07 注入 PI_TARGET_TRIPLE/PI_SYSROOT,xcompile 读作默认。
|
||||
- **F05 硬件安全门**:tool_call 钩子 block 宿主 gcc(与 F05 同一钩子面,可合并到一个扩展)。
|
||||
- **F21 构建封装**:F21 build 工具用 xcompile 生成的 toolchain.cmake 跑 cmake。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. `xcompile select --triple aarch64-linux-gnu` 后,`xcompile info` 返回的 compiler 路径含 `aarch64-linux-gnu-gcc`,sysroot 非 `/`。
|
||||
2. `xcompile toolchain` 生成的 `toolchain.cmake` 里 `CMAKE_C_COMPILER` 含 triple 前缀;CMake 用此文件编译的 `.o` 经 `file` 校验为 `ELF 64-bit LSB ... ARM aarch64`。
|
||||
3. agent 发 `gcc main.c -o main`(裸宿主 gcc)被 `tool_call` 钩子 block,返回终止原因;agent 发 `aarch64-linux-gnu-gcc main.c -o main` 不被 block。
|
||||
4. `xcompile verify --artifact ./main` 对 x86 产物报错 `architecture mismatch: expected aarch64, got x86-64`。
|
||||
5. 切换 triple 后 `xcompile info` 返回的 sysroot/compiler 随之变化,状态跨 tool call 保留(闭包持有)。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- 依赖宿主已装交叉工具链(`apt install gcc-aarch64-linux-gnu`);未装时 `xcompile select` 应报 `toolchain not found` 而非静默通过。
|
||||
- `tool_call` 钩子正则需覆盖 gcc/g++/cc/c++ 裸调用及 `CMAKE_C_COMPILER=gcc` 透传,但不能误伤 `aarch64-linux-gnu-gcc`(前缀白名单)。
|
||||
- cmake 工具链文件路径需与 F07 注入的 `PI_BUILD_DIR` 对齐,否则 agent 找不到。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P1 高**——交叉编译是嵌入式闭环第一步,选错工具链后续全废;`tool_call` 硬门直接治缺陷 #3/#13 交叉编译维度|**3-4 人日**。
|
||||
63
Docs/F13_安全烧录工具.md
Normal file
63
Docs/F13_安全烧录工具.md
Normal file
@ -0,0 +1,63 @@
|
||||
# F13 安全烧录工具(F-FLASH)
|
||||
|
||||
> **满足嵌入式需求维度**:#2 烧录与镜像
|
||||
> **场景锚定**:`dd if=rootfs.ext4 of=/dev/mmcblk0 bs=4M conv=fsync`(SD/eMMC 整盘镜像)、`fastboot flash boot boot.img`(分区烧录)、`dfu-util -d vid:pid -D firmware.bin`(USB DFU)、`openocd -c "program firmware.elf verify reset exit"`(JTAG 烧 ELF)。烧前必须确认设备节点(`lsblk` 看 `/dev/mmcblk0` 而非 `/dev/sda`),分区表错误写坏引导区。`dd of=/dev/sda` 写错盘 = 抹掉宿主系统;烧错地址偏移 = 砖板,要拆芯片 SPI 编程器离线恢复。**破坏性、不可逆、物理后果**。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
pi 无烧录概念,bash 工具直接执行裸 `dd`(bash.ts:103 spawn),无设备节点确认。`BashOperations` 接口可替换后端(bash.ts:62-80)。`tool_call` 钩子可 block 裸 dd(types.ts:1071-1080 fail-closed,参照 permission-gate.ts)。`executionMode:"sequential"`(types.ts:477)确保烧录不与其他工具并行。`user_bash` 事件(types.ts:813-821)可拦用户手敲 dd。`pi.exec()`(types.ts:1334)跑 lsblk/findmnt 校验。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**注册 `flash` 工具,封装四种烧录后端,强制三段式安全流程(确认→dry-run→verify)**(纯扩展,零源码)。
|
||||
|
||||
**工具 `flash`** 内部按 `method` 分派:`dd`/`fastboot`/`dfu`/`openocd`。每次烧录必经三步:
|
||||
1. **设备确认**:`dd` 方法先跑 `lsblk -b -o NAME,SIZE,TYPE,MOUNTPOINT` + `find /dev/disk/by-id/` 确认目标节点;目标节点必须在白名单(可移除盘特征),宿主系统盘(挂载了 `/`/`/boot`/`/home`)被拒。
|
||||
2. **dry-run**:`dd` 跑 `dd if=image of=/dev/null bs=4M count=1`(只读源镜像验证可读)+ 打印将写的目标节点和偏移量,不写真写;`fastboot` 跑 `fastboot getvar all` 确认设备在线。
|
||||
3. **verify**:烧后 `cmp` 或 `dd if=/dev/mmcblk0 bs=4M count=N | sha256sum` 对比源镜像 hash,一致才报成功。
|
||||
|
||||
`executionMode:"sequential"`(types.ts:477)确保烧录不与并行(缺陷 #11)。
|
||||
|
||||
**与 F05 联动**:F05 的 `tool_call` 钩子拦截裸 `dd of=/dev/` 命令,返回 `{block:true, reason:"use flash tool", terminate:true}`,把所有烧录操作收束到 flash 工具内。flash 工具自身不被 F05 拦(它是自定义工具,钩子只拦 `toolName==="bash"`)。同时监听 `user_bash` 事件(types.ts:813)拦用户手敲 dd。
|
||||
|
||||
**root 独占**:flash 工具执行前检查 `/var/run/pi-flash.lock`(pidfile),已在烧录则拒。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
flashSchema = Type.Object({
|
||||
method: Type.Union([Type.Literal("dd"),Type.Literal("fastboot"),Type.Literal("dfu"),Type.Literal("openocd")], { description: "Flashing method" }),
|
||||
image: Type.String({ description: "Path to image/payload file" }),
|
||||
target: Type.String({ description: "Target device node (e.g. /dev/mmcblk0) for dd; 'serial' for fastboot/dfu; 'cfg' path for openocd" }),
|
||||
offset: Type.Optional(Type.String({ description: "Byte offset for dd seek= (decimal or 0x hex). Validated against partition table." })),
|
||||
partition: Type.Optional(Type.String({ description: "Partition name for fastboot (e.g. boot) or dfu alt-setting" })),
|
||||
dry_run: Type.Optional(Type.Boolean({ description: "If true, validate without writing. Default true for first call." })),
|
||||
verify: Type.Optional(Type.Boolean({ description: "If true, verify after write via hash compare. Default true." })),
|
||||
});
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F05 硬件安全门**:F05 拦截裸 `dd of=/dev/` → 收束到 flash 工具内;flash 工具自带三段式安全流程。
|
||||
- **F21 构建封装**:F21 build 完成后可调 flash 烧录(F20 闭环编排的 compile→flash 步骤)。
|
||||
- **F20 闭环编排**:F20 的 flash checkpoint 须 F13 通过才许继续。
|
||||
- **F19 硬件验证**:flash 后 verify 是 F19 判据的输入之一。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. `flash dd --image sdcard.img --target /dev/sda`(`/dev/sda` 是宿主系统盘)被 block,返回 `target /dev/sda has mounted / /boot — refusing`。
|
||||
2. `flash dd --image sdcard.img --target /dev/mmcblk0 --dry_run true` 不执行任何写操作,只打印 `would write 4GB to /dev/mmcblk0 offset 0`。
|
||||
3. `flash dd --image sdcard.img --target /dev/mmcblk0`(dry_run 默认 true 第一次)先 dry-run 再写真写再 verify,三步全过才报 `flash OK: verified`;verify hash 不匹配报 `VERIFY FAILED`。
|
||||
4. agent 发裸 `dd if=x of=/dev/mmcblk0` 走 bash 工具被 F05 钩子 block。
|
||||
5. 两个 flash tool call 并发时第二个被 pidfile 锁拒。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- root 权限(dd 需 root;fastboot 需 udev rules 或 root)。
|
||||
- `lsblk`/`findmnt` 在某些嵌入式板精简系统可能缺失,需 fallback 到 `/proc/mounts` 解析。
|
||||
- offset 校验需解析 GPT/MBR 分区表,偏移越过镜像大小要拒。
|
||||
- fastboot/dfu/openocd 子工具可能未装,需预检 `which`。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P0 最高**——烧错盘=砖板/宿主毁,物理不可逆;缺陷 #3 的直接解,必须最先建|**4-5 人日**。
|
||||
79
Docs/F14_外设探测工具集.md
Normal file
79
Docs/F14_外设探测工具集.md
Normal file
@ -0,0 +1,79 @@
|
||||
# F14 外设探测工具集(F-PROBE)
|
||||
|
||||
> **满足嵌入式需求维度**:#3 外设驱动
|
||||
> **场景锚定**:嵌入式通过 Linux 字符设备/总线接口操作硬件——I2C 用 `i2c-tools`(`i2cdetect -y 0`/`i2cget -y 0 0x68 0x75`/`i2cset`)、SPI 用 `spidev`(`/dev/spidev0.0`,ioctl 全双工传输)、UART 用 `/dev/ttyS*`+termios、GPIO 用 `libgpiod`(`gpioget`/`gpioset`/`gpiomon`,字符设备 `/dev/gpiochipN`)、PWM 用 `/sys/class/pwm/`。每个外设都要查 datasheet 寄存器映射做位域操作。I2C 地址 7-bit vs 8-bit 歧义,SPI 有 4 种 mode。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
pi 无外设操作工具,只能靠 bash 跑 i2c-tools/gpioget(每命令新进程 bash.ts:103,无状态保留)。`ReadOperations` 接口模式(read.ts:49-62)可参照。`registerTool`(types.ts:1251)+ `ToolDefinition`(types.ts:449-498)。`appendEntry`(types.ts:1318)持久化硬件状态(与 F10 联动)。`executionMode:"sequential"`(types.ts:477)防总线并发。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**注册一个 `bus_probe` 工具带子命令**(非多个细粒度工具)。理由:(1) LLM 工具列表膨胀会劣化采样质量,一个工具带 `action` 子命令更可控;(2) 总线/GPIO 操作共享同一硬件状态(总线占用、GPIO 方向),单工具闭包集中管理状态更安全。
|
||||
|
||||
**工具 `bus_probe`** 的 `action` 枚举覆盖:
|
||||
- `i2c_detect`:`i2cdetect -y <bus>` 扫描总线地址表
|
||||
- `i2c_get`/`i2c_set`:`i2cget -y <bus> <addr> <reg>` / `i2cset -y <bus> <addr> <reg> <val>`
|
||||
- `spi_xfer`:通过 `/dev/spidevN.M` 全双工传输(Node `fs.openSync`+`ioctl` 或 spawn `spidev_test`)
|
||||
- `gpio_get`/`gpio_set`/`gpio_mon`:`gpioget`/`gpioset`/`gpiomon`(libgpiod v2)
|
||||
- `pwm_get`/`pwm_set`:读写 `/sys/class/pwm/pwmchipN/...`(period/duty_cycle/enable)
|
||||
- `mem_snap`:快照 `/proc/iomem` + `/proc/interrupts`(只读,调试 MMIO 映射和中断分配)
|
||||
|
||||
**与 F10 联动(缺陷 #4 解)**:每次 `i2c_set`/`gpio_set`/`pwm_set` 成功后,`pi.appendEntry("hw-state", {bus, addr, reg, val, timestamp})` 持久化到 session JSONL;F10 恢复时遍历 `ctx.sessionManager.getBranch()` 重建总线占用/GPIO 方向表。下次 `i2c_detect` 发现地址已占用时提示 `addr 0x50 already in use (set at entry #N)`。
|
||||
|
||||
`executionMode:"sequential"` 确保 I2C/SPI/GPIO 共享总线不并发撞车(缺陷 #11)。
|
||||
|
||||
**hex 防御(缺陷 #8)**:所有 `reg`/`val`/`addr` 参数在 handler 入口做 `parseInt(x, 0)` 自适配(接受 `0x50` 和 `80`),再 `parseInt(x, 16)` fallback;参数 schema 用 `Type.String` 而非 `Type.Number` 防止模型传十进制后精度丢失。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
busProbeSchema = Type.Object({
|
||||
action: Type.Union([
|
||||
Type.Literal("i2c_detect"), Type.Literal("i2c_get"), Type.Literal("i2c_set"),
|
||||
Type.Literal("spi_xfer"), Type.Literal("gpio_get"), Type.Literal("gpio_set"),
|
||||
Type.Literal("gpio_mon"), Type.Literal("pwm_get"), Type.Literal("pwm_set"),
|
||||
Type.Literal("mem_snap"),
|
||||
], { description: "Probe action" }),
|
||||
bus: Type.Optional(Type.Number({ description: "I2C bus number (e.g. 0)" })),
|
||||
addr: Type.Optional(Type.String({ description: "I2C device address as hex string (0x50) or decimal (80). Use hex to avoid ambiguity." })),
|
||||
reg: Type.Optional(Type.String({ description: "Register address, hex string preferred (0x10)" })),
|
||||
val: Type.Optional(Type.String({ description: "Value to write, hex string preferred (0x3F)" })),
|
||||
chip: Type.Optional(Type.Number({ description: "GPIO chip number" })),
|
||||
line: Type.Optional(Type.Number({ description: "GPIO line offset" })),
|
||||
spi_dev: Type.Optional(Type.String({ description: "SPI device path /dev/spidev0.0" })),
|
||||
spi_data: Type.Optional(Type.String({ description: "Hex bytes to send, e.g. 0xFF00A5" })),
|
||||
pwm_chip: Type.Optional(Type.Number({ description: "PWM chip number" })),
|
||||
pwm_channel: Type.Optional(Type.Number({ description: "PWM channel" })),
|
||||
duration: Type.Optional(Type.Number({ description: "Monitor duration in seconds (gpio_mon)" })),
|
||||
});
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F10 硬件状态持久化**:每次 set 成功后 appendEntry,跨 tool call / session 恢复。
|
||||
- **F05 硬件安全门**:声明 sequential 防总线并发撞车。
|
||||
- **F18 datasheet RAG**:i2c_get 读寄存器前先用 datasheet_query 查地址/位域(F07 promptGuidelines 引导)。
|
||||
- **F19 硬件验证**:gpio_get/i2c_get 采集信号作 F19 verify 输入。
|
||||
- **F06 子进程隔离**:i2c-dev ioctl/spidev ioctl 操作建议声明 isolated:"process" 防 native crash 带崩主进程。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. `bus_probe i2c_detect --bus 0` 返回 `i2cdetect -y 0` 格式地址表(`--` 和 `UU` 标记正确)。
|
||||
2. `bus_probe gpio_set --chip 0 --line 33 --val 1` 后 `bus_probe gpio_get --chip 0 --line 33` 返回 `"1"`(方向和值可回读)。
|
||||
3. `bus_probe i2c_set --bus 0 --addr 0x50 --reg 0x10 --val 0x3F` 成功后,session JSONL 出现 `hw-state` CustomEntry;新 session 恢复后 `bus_probe i2c_detect` 提示 `0x50 in use`。
|
||||
4. agent 传 `addr:"80"`(十进制)和 `addr:"0x50"`(hex)handler 均解析为同一 I2C 地址 0x50,不报错(缺陷 #8 防御)。
|
||||
5. 两个 `bus_probe i2c_set` 并发时第二个等待第一个完成(sequential 生效),不报 `Device or resource busy`。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- 依赖 `i2c-tools`/`libgpiod`(gpioget 等)/`spidev_test` 已装;板精简系统可能缺。
|
||||
- libgpiod v1 vs v2 CLI 不同,需探测版本。
|
||||
- `/sys/class/pwm` 需先 `echo N > export`,操作序列复杂。
|
||||
- `gpiomon` 是阻塞长命令,需 `spawn` + 超时管理,不能直接 `ctx.exec`(会阻塞到超时)。
|
||||
- I2C 地址 7-bit vs 8-bit 歧义需在文档声明(i2cdetect 用 7-bit)。
|
||||
- jiti 零隔离(缺陷 #5):i2c-dev ioctl 段错误会带崩主进程——建议操作外包到独立子进程(F06)。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P1 高**——外设探测是驱动开发核心探查手段,直接治缺陷 #4(硬件状态持久化)的 I2C/GPIO 分维度|**4-5 人日**。
|
||||
83
Docs/F15_JTAG-gdb在线调试集成.md
Normal file
83
Docs/F15_JTAG-gdb在线调试集成.md
Normal file
@ -0,0 +1,83 @@
|
||||
# F15 JTAG/gdb 在线调试集成(F-DEBUGGER)
|
||||
|
||||
> **满足嵌入式需求维度**:#4 在线调试
|
||||
> **场景锚定**:裸机/固件调试靠 JTAG/SWD 物理接口接 OpenOCD(`openocd -f interface/cmsis-dap.cfg -f target/stm32f4x.cfg`,启 `gdb_port 3333`),再用 `gdb-multiarch` 连 `target remote :3333`。可设硬件断点/数据 watchpoint(`hbreak`/`watch`)、读设备寄存器(`x/wx 0x40021000`)、单步(`stepi`/`nexti`)、读 core register。Cortex-M4 仅 6 个硬件断点。SWO trace 实时打印,semihosting 让目标板通过调试器做 printf。gdb 是**交互式长会话**,必须在一个进程里维持跨多步状态(连→断→continue→读寄存器→改寄存器→继续)。这是嵌入式闭环(改码→交叉编译→烧→上板→gdb 调→再改)的核心断链点。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
bash 每命令新进程(bash.ts:103),gdb/openocd 交互式长会话不可用(缺陷 #1)。`spawn` 长进程参照 bash.ts:103。`ToolDefinition`(types.ts:449-498)。`appendEntry`(types.ts:1318)持久化断点列表。`examples/extensions/tools.ts:27-53` 状态恢复范式。`executionMode:"sequential"`(types.ts:477)防 JTAG 适配器并发独占。与 F01 共享"长生命周期子进程"设计范式。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**注册 `debugger` 工具,基于扩展模块级闭包持有的长生命周期 OpenOCD + gdb 子进程实现跨 tool call 有状态调试**(直接绕缺陷 #1)。
|
||||
|
||||
**架构**:扩展加载时(`session_start` 事件 types.ts:562-568)初始化 `DebuggerSession` 管理器(模块级 `Map<sessionId, {openocd?: ChildProcess, gdb?: ChildProcess, breakpoints: Map<...>}>`)。工具 `debugger` 的 `action` 分两阶段:
|
||||
|
||||
**阶段 1 会话管理**:
|
||||
- `open`:spawn `openocd -f interface.cfg -f target.cfg` 常驻后台(`detached:true`,不随 tool call 结束被杀),等 `:3333` 端口就绪;再 spawn `gdb-multiarch -q --interpreter=mi`,gdb 的 stdin/stdout 用 pipe 持久持有在闭包里。发 `target remote :3333` 连接。
|
||||
- `close`:发 `detach`/`quit` 给 gdb,SIGTERM OpenOCD,清理闭包。
|
||||
|
||||
**阶段 2 调试操作**(须先 `open`):
|
||||
- `load`:gdb MI 发 `-target-download`(`load firmware.elf`)
|
||||
- `break`:`-break-insert 0x08001000` 或 `-break-insert main`;断点列表存闭包 + `appendEntry("debugger-bp", {addr, condition})`
|
||||
- `watch`:`-break-watch read|write|access 0x40021000`
|
||||
- `continue`:`-exec-continue`,监听 `*stopped` 异步事件捕获断点命中
|
||||
- `step`/`next`:`-exec-step`/`-exec-next`
|
||||
- `regs`:`-data-list-register-values x`(读全部寄存器)
|
||||
- `read_mem`:`-data-read-memory-bytes 0x40021000 16`(读 16 字节 MMIO)
|
||||
- `write_mem`:`-data-write-memory-bytes 0x40021000 0x1F`(写 MMIO)
|
||||
- `semihosting`:OpenOCD 已开 `arm semihosting enable`
|
||||
|
||||
**与 F10 联动**:断点/watchpoint 列表 `appendEntry("debugger-bp", ...)` 持久化(缺陷 #4);session 恢复时 `getBranch()` 重建断点列表并重新 `-break-insert`(gdb 重连后断点需重设)。与 F01 共享"长生命周期子进程"范式。
|
||||
|
||||
`executionMode:"sequential"` 确保调试操作不与 flash/probe 并发(JTAG 适配器独占)。
|
||||
|
||||
**hex 防御(缺陷 #8)**:所有地址参数 `parseInt(x, 0)` 自适配;`read_mem`/`write_mem` 地址执行前打印回显供 agent 确认,写 MMIO 前需 `confirm:true`(防模型十进制强转后写错地址砖板)。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
debuggerSchema = Type.Object({
|
||||
action: Type.Union([
|
||||
Type.Literal("open"), Type.Literal("close"), Type.Literal("load"),
|
||||
Type.Literal("break"), Type.Literal("watch"), Type.Literal("continue"),
|
||||
Type.Literal("step"), Type.Literal("next"), Type.Literal("regs"),
|
||||
Type.Literal("read_mem"), Type.Literal("write_mem"),
|
||||
], { description: "Debugger action" }),
|
||||
cfg: Type.Optional(Type.String({ description: "OpenOCD config file path (for 'open')" })),
|
||||
elf: Type.Optional(Type.String({ description: "ELF file path (for 'load')" })),
|
||||
addr: Type.Optional(Type.String({ description: "Address for break/watch/read_mem/write_mem. Hex string (0x40021000) strongly preferred." })),
|
||||
length: Type.Optional(Type.Number({ description: "Bytes to read (read_mem)" })),
|
||||
value: Type.Optional(Type.String({ description: "Value to write (write_mem). Hex string (0x1F) preferred." })),
|
||||
watch_type: Type.Optional(Type.Union([Type.Literal("read"),Type.Literal("write"),Type.Literal("access")])),
|
||||
confirm: Type.Optional(Type.Boolean({ description: "Required true for write_mem (safety gate against wrong address)." })),
|
||||
});
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F01 持久 Shell**:共享长生命周期子进程范式;F15 可建在 F01 会话池之上。
|
||||
- **F10 硬件状态持久化**:断点列表 appendEntry 持久化,session 恢复重设。
|
||||
- **F06 子进程隔离**:OpenOCD 常驻进程崩溃(缺陷 #5)应外包到独立守护进程 + IPC,而非 jiti 主进程内直接 spawn。
|
||||
- **F07 环境探针**:F07 注入 `PI_OPENOCD_CFG` 路径,debugger 工具据此选 board.cfg。
|
||||
- **F05 硬件安全门**:JTAG 独占,声明 sequential 防与 flash/probe 并发。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. `debugger open --cfg board.cfg` 后 OpenOCD 进程常驻(`pgrep openocd` 存在),gdb 连上 `:3333`;`debugger continue` 不报 `target not connected`。
|
||||
2. `debugger break --addr 0x08001000` + `debugger continue` + 程序命中断点后返回 `*stopped,reason=breakpoint-hit,addr=0x08001000`;断点跨后续 tool call 保留(`debugger regs` 仍连同一 gdb 进程)。
|
||||
3. `debugger read_mem --addr 0x40021000 --length 16` 返回 16 字节十六进制值(非 `0x1073872896`,缺陷 #8 防御成功)。
|
||||
4. `debugger write_mem --addr 0x40021000 --value 0x1F` 不带 `confirm:true` 被拒,返回 `write_mem requires confirm:true`;带 `confirm` 后写入并回读校验。
|
||||
5. session 重启后 `getBranch()` 找到之前的 `debugger-bp` entry,`debugger open` 自动重设断点列表。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- **OpenOCD 常驻崩溃**(缺陷 #5 jiti 零隔离)会带崩整个扩展 → 应把 OpenOCD/gdb 管理外包到独立守护进程 + IPC(Node `net.Socket`/Unix socket),而非 jiti 主进程内直接 spawn。架构级决策。
|
||||
- gdb MI 协议异步事件(`*stopped`/`=thread-group-added`)需持续监听 stdout pipe,不能阻塞;需事件泵 loop。
|
||||
- OpenOCD 配置文件(interface.cfg/target.cfg)因板而异,需 F07 注入 `PI_OPENOCD_CFG` 路径。
|
||||
- 写 MMIO 零容错(缺陷 #8),`confirm` 门是最低限防御;更安全是写前自动 `read_mem` 回显当前值 + 对比 datasheet 预期。
|
||||
- gdb-multiarch 可能未装(`apt install gdb-multiarch`)。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P1 高**——在线调试是嵌入式闭环核心断链点(缺陷 #1+#4 耦合),没有它 agent 无法做断点级调试;但实现复杂度最高,建议拆两期:一期 open+break+continue+read_mem(3-4 人日),二期 watch+step+semihosting+状态恢复(3-4 人日)|**合计 6-8 人日**。
|
||||
66
Docs/F16_设备树工具.md
Normal file
66
Docs/F16_设备树工具.md
Normal file
@ -0,0 +1,66 @@
|
||||
# F16 设备树工具(F-DT)
|
||||
|
||||
> **满足嵌入式需求维度**:#5 设备树
|
||||
> **场景锚定**:ARM/嵌入式 Linux 硬件描述用 Device Tree——DTS/DTSI 源文件描述节点(`&i2c0 { sensor@68 { compatible = "vendor,xyz"; reg = <0x68>; interrupt-parent = <&gpio4>; interrupts = <17 IRQ_TYPE_EDGE_FALLING>; }; };`),`compatible` 字符串驱动匹配,`phandle` 节点引用,`reg` 指定地址,`interrupts` 指定中断。`dtc`(Device Tree Compiler)把源编译成 `.dtb` 给内核。**改错节点(compatible 拼写错、phandle 断链、reg 地址错、interrupt 线号错)= 外设直接不枚举,dmesg 无报错静默失败,调试极其难**。一个 SoC 的 DTS 常有几百节点嵌套几层 include。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
pi 无设备树概念,只能靠 bash 跑 `dtc`/`fdtdump`(每命令新进程 bash.ts:103)。read 工具读 `.dts` 是纯文本 grep,无法理解节点树结构(缺陷 #2 read 截断 + 无结构化)。`readSchema`(read.ts:21-25)TypeBox 范式参照。`registerTool`(types.ts:1251)+ `ToolDefinition`(types.ts:449-498)。`bash.ts:322-499` execute+render 范式。`tool_call` 钩子(types.ts:868-871 EditToolCallEvent)可对 .dts 编辑加预检门。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**注册 `dt` 工具(非 skill,需主动结构化解析而非被动文本处理)**,覆盖五个 action。设备树是树结构 + phandle 引用图,纯文本 grep 不可靠,需结构化解析。
|
||||
|
||||
**工具 `dt`** 的 `action`:
|
||||
- `parse`:解析 `.dts`/`.dtsi` 为节点树(正则 + 栈式解析 `node { ... }` 嵌套,提取 `label: node@addr { compatible = "x"; reg = <0x...>; phandle = <0x1>; }`),返回 JSON 树结构。支持 `#include`/`/include/` 递归解析 dtsi 依赖链。
|
||||
- `check_compatible`:校验 `compatible = "vendor,chip"` 字符串拼写——对照内置 SoC compatible 字典(`st,stm32f411`/`xunpai,hobbit`/`rockchip,rk3588`),typo 标红。
|
||||
- `check_phandle`:构建 phandle 引用图(所有 `phandle = <0xN>` 定义 vs 所有 `<&label>` 引用),检测断链(引用不存在的 phandle)和孤岛(定义从未被引用)。
|
||||
- `compile`:`dtc -I dts -O dtb -o out.dtb --include-dir <dir> <file>.dts`,编译失败时解析 dtc 错误(行号+错误类型)结构化返回。
|
||||
- `overlay_diff`:编译 `.dts` → `.dtbo`(`dtc -I dts -O dtb -@ -o overlay.dtbo`),再用 `fdtdump`/`dtc -I dtb -O dts` 反编译 base.dtb + overlay.dtbo 应用后的结果,diff 新增/修改节点。
|
||||
|
||||
**与 F07 联动**:F07 注入 `PI_DTC_VERSION`/`PI_KERNEL_DTS_DIR`(内核 `arch/arm64/boot/dts/` 路径);`dt compile` 自动加 `--include-dir` 指向内核 DTS 目录。
|
||||
|
||||
`executionMode` 不强制 sequential(dt 操作纯文件解析/编译,无共享硬件资源,可并行)。
|
||||
|
||||
**与缺陷 #9 联动**:edit 工具 fuzzy 匹配在 `.dts` 上误匹配;`dt parse` 可作编辑前结构化预检——agent 先 `dt parse` 定位节点 label 再精确 edit,绕过 fuzzy。F05 的 `tool_call` 钩子对 `EditToolCallEvent`(types.ts:868-871)的 `file_path` 后缀为 `.dts`/`.dtsi`/`.ld` 时,要求 `oldText` 长度 ≥ N,否则 block 提示 `use dt parse to locate node label first`。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
dtSchema = Type.Object({
|
||||
action: Type.Union([
|
||||
Type.Literal("parse"), Type.Literal("check_compatible"),
|
||||
Type.Literal("check_phandle"), Type.Literal("compile"), Type.Literal("overlay_diff"),
|
||||
], { description: "Device tree action" }),
|
||||
file: Type.String({ description: "Path to .dts/.dtsi file (or .dtb for overlay_diff base)" }),
|
||||
include_dirs: Type.Optional(Type.Array(Type.String(), { description: "Additional include directories for #include resolution" })),
|
||||
compatible: Type.Optional(Type.String({ description: "Compatible string to check (for check_compatible), e.g. 'st,stm32f411'" })),
|
||||
overlay: Type.Optional(Type.String({ description: "Path to .dtbo overlay file (for overlay_diff)" })),
|
||||
out: Type.Optional(Type.String({ description: "Output path for compile (e.g. out.dtb or overlay.dtbo)" })),
|
||||
});
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F03 edit 精确匹配**:`dt parse` 作编辑前预检,定位节点 label 后精确 edit 绕过 fuzzy。
|
||||
- **F05 硬件安全门**:tool_call 钩子对 .dts 编辑要求 oldText 足够长,否则 block 提示用 dt parse。
|
||||
- **F07 环境探针**:F07 注入 PI_DTC_VERSION/PI_KERNEL_DTS_DIR,dt compile 自动加 include-dir。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. `dt parse --file board.dts` 返回 JSON 节点树,`compatible`/`reg`/`phandle` 属性正确提取;`#include "stm32f411.dtsi"` 的子节点合并进树。
|
||||
2. `dt check_compatible --file board.dts --compatible st,stm32f411xe` 对比 `st,stm32f411`(base)+ `st,stm32f411xe`(子型号)字典,标红 `st,stm32f411x`(typo,少 e)。
|
||||
3. `dt check_phandle --file board.dts` 检测到 `<&nonexistent>` 引用时报 `dangling phandle reference: &nonexistent at line N`;检测到从未被引用的 phandle 定义时报 `orphan phandle: 0x5 at node label`。
|
||||
4. `dt compile --file board.dts --out board.dtb` 成功产出 `.dtb`;故意写语法错误时返回 `dtc error: line 42: syntax error near '}'`。
|
||||
5. `dt overlay_diff --file base.dtb --overlay sensor.dtbo` 返回新增节点列表 + 修改属性 diff(before/after 值对比)。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- DTS 正则解析对预处理指令(`#define`/`#include`/`/dts-v1/`/`/memreserve/`)覆盖不全,复杂 DTS 可能解析失败 → fallback 到 `dtc -I dts -O dts`(dtc 自带规范化)再解析。
|
||||
- compatible 字典需维护(SoC 型号多),初期覆盖 ST/Rockchip/X5/S100 主流,不全时 `check_compatible` 标 `unknown compatible, not in dictionary`(非错非对)。
|
||||
- `dtc` 可能未装或版本旧(dtc 1.6 vs 1.7 对 overlay 符号表支持不同)。
|
||||
- overlay diff 需 dtc 支持 `-@`(symbols),旧版可能不支持。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P2 中**——设备树错误导致外设静默不枚举(dmesg 无报错),危害隐蔽但非实时阻断;优先级低于 flash/debugger,但 `dt parse` 作 edit 预检(防缺陷 #9 误匹配)有即时价值|**4-5 人日**。
|
||||
60
Docs/F17_宿主-目标板链路管理.md
Normal file
60
Docs/F17_宿主-目标板链路管理.md
Normal file
@ -0,0 +1,60 @@
|
||||
# F17 宿主-目标板链路管理(F-BOARDLINK)
|
||||
|
||||
> **满足嵌入式需求维度**:#8 板上调测(同时覆盖 #1 工具链 / #3 外设 / #4 在线调试)
|
||||
> **场景锚定**:开发分两机——宿主(Mac/x86)+ 目标板(aarch64)。日常靠 SSH 进板跑命令(`ssh root@board dmesg | tail`)、`scp` 传 ELF/rootfs、串口 console(`minicom -D /dev/ttyUSB0 -b 115200`)看启动日志和 kernel panic。调外设靠 `dmesg`、`/proc/iomem`(MMIO 地址占用)、`/sys/class/*`、`/proc/interrupts`(IRQ 是否来)。状态分散在宿主(源码/编译器)和目标板(运行时/dmesg/寄存器)两处,agent 要跨双机协调。板子 IP/串口设备名不固定。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
`BashOperations` 接口(bash.ts:62-80)`exec(command, cwd, {onData, signal, timeout, env})` 是可插拔执行后端。SSH 扩展示例 `examples/extensions/ssh.ts:81-112` `createRemoteBashOps()` 用 `spawn("ssh", [remote, cmd])` 实现 SSH 代理执行。`user_bash` 事件(types.ts:1083-1088)可返回 `{operations: BashOperations}` 替换执行后端。`registerTool`(types.ts:1251)。`session_start` 事件(types.ts:562-568)`reason:"resume"` 时可从 session 重建板注册表。`pi.appendEntry(customType, data)`(types.ts:1318)持久化板注册表。`pi.registerFlag`(types.ts:1272)注册 `--board` CLI 标志。`before_agent_start`(types.ts:699-709)注入板型号到 system prompt。`EventBus`(event-bus.ts:1-33)`pi.events.emit/on` 跨扩展通信。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**做一个 pi 扩展 `boardlink.ts`(放 `.pi/extensions/boardlink.ts`)**,不修改 pi 源码。核心三件事:
|
||||
|
||||
1. **板注册表**:扩展加载时从 session JSONL 扫描 `customType:"boardlink:registry"` 的 `CustomEntry`(session-manager.ts:94-103 文档明确"On reload, extensions can scan entries for their customType and reconstruct internal state"),重建内存注册表。新增板时 `pi.appendEntry("boardlink:registry", {id, ip, port, user, model, toolchain, serialDev})` 持久化。板注册表存 session JSONL 而非 settings(板绑定到会话上下文,不同项目不同板)。
|
||||
|
||||
2. **注册 4 个工具** via `pi.registerTool()`(types.ts:1251):
|
||||
- `board_connect` — 建立 SSH 连接(复用 `ssh.ts:29-45` sshExec 模式)或打开串口(`spawn("picocom", ["-b", baudrate, serialDev])`)。连接句柄存扩展内存 Map,key 为 boardId。`executionMode:"sequential"`(types.ts:477)避免并发连接冲突。
|
||||
- `board_exec` — 在已连接板执行命令,复用 `BashOperations` 接口(bash.ts:62-80),实现 `createBoardBashOps(boardId)` 返回 BashOperations,`exec()` 内部 spawn `ssh [remote, cmd]` 或写串口 fd。**关键**:与 F01 联动——若板侧有持久 shell(tmux 会话),`board_exec` 的 `exec` 改为 `ssh remote "tmux send-keys -t session cmd Enter"` + `tmux capture-pane`,跨 tool call 连接复用。
|
||||
- `board_scp` — 文件传输,`spawn("scp", [local, "remote:path"])`,用 `pi.exec()`(types.ts:1334)或 `execCommand`(exec.ts:34)。
|
||||
- `board_console` — 串口 console 流捕获。`spawn("cat", [serialDev])` 或 `spawn("picocom", [...])`,stdout pipe 到 `onUpdate` 回调(bash.ts:342-364 emitOutputUpdate 模式),用 `OutputAccumulator`(output-accumulator.ts:35)有界缓冲。`execute()` 不 await 进程结束(console 持续流),靠 `signal` 的 abort 事件终止。
|
||||
|
||||
3. **system prompt 注入**:`before_agent_start`(types.ts:699-709)读取注册表,把当前板型号、IP、工具链三元组注入 system prompt(与 F07 联动)。用 `BeforeAgentStartEventResult.systemPrompt`(types.ts:1102-1106)链式修改。
|
||||
|
||||
**联动**:通过 `pi.events.emit("boardlink:connected", {boardId, shellHandle})`(event-bus.ts:15)广播连接事件,F01 监听获取 shell 句柄;F07 订阅 `boardlink:registry:updated` 注入 env;`board_exec` 声明 `executionMode:"sequential"`(治缺陷 #11 串口/JTAG 并发)。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
board_connect: { boardId: string, method: "ssh"|"serial", ssh?: {user,host,port}, serial?: {dev,baudrate} }
|
||||
board_exec: { boardId: string, command: string, timeout?: number }
|
||||
board_scp: { boardId: string, localPath: string, remotePath: string, direction: "upload"|"download" }
|
||||
board_console: { boardId: string, duration?: number } // 串口流,默认30s
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F01 持久 Shell**:板侧 SSH 持久 shell 复用 pshell/tmux 范式,board_exec 跨 tool call 连接复用。
|
||||
- **F07 环境探针**:board 注册表的 model/toolchain 字段被 F07 订阅注入 system prompt。
|
||||
- **F15 JTAG/gdb**:板上 gdb 走 board_exec SSH 执行。
|
||||
- **F19 硬件验证**:板上 dmesg/gpio 采集通过 `pi.events.emit("boardlink:exec", {boardId, command})` 委托给 F17 执行。
|
||||
- **F21 构建封装**:板上构建走 board_exec。
|
||||
- **F05 硬件安全门**:board_exec 声明 sequential 防串口/JTAG 并发撞车。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. `board_connect` 后连续两次 `board_exec` 跑 `cd /tmp && pwd` 和 `pwd`,第二次输出 `/tmp`(SSH 连接复用,非每命令新 spawn)——验证方式:对比 `ssh.ts:86` 每次新 spawn 的行为。
|
||||
2. `board_console` 捕获串口输出 30 秒,`onUpdate` 至少 3 次流式回灌(`tool_execution_update` 事件可被另一扩展 `pi.on("tool_execution_update", ...)` 捕获验证)。
|
||||
3. 板注册表在 `/compact` 后 session resume 时,`session_start` handler 能从 `ctx.sessionManager.getEntries()` 扫描到 `customType:"boardlink:registry"` 的 CustomEntry 并重建内存注册表。
|
||||
4. `board_exec` 声明 `executionMode:"sequential"`,同批并行 tool call 含 `board_exec` 时,`agent-loop.ts:422` 走 `executeToolCallsSequential` 路径。
|
||||
5. `board_scp` 上传文件后 `board_exec` 跑 `ls -la /tmp/uploaded` 能看到文件。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- SSH 连接复用需 `ControlMaster`(`ssh -M -S socket`)或持久 shell(依赖 F01);每命令新 SSH 连接虽能跑但延迟高。
|
||||
- 串口 `board_console` 的 `execute()` 不 await 进程结束——需确认 `onUpdate` 在 promise pending 时能持续触发(`agent-loop.ts:670-711` 的 `acceptingUpdates` 在 promise settle 后变 false,但 pending 期间为 true,可行)。
|
||||
- jiti 零隔离(缺陷 #5):扩展若操作串口 native fd 段错误会带崩主进程——串口操作应外包到独立子进程(F06)。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P0 最高**——板链路是所有其他嵌入式功能的前置依赖|**5-7 人日**(扩展框架 1 天 + SSH 连接池 2 天 + 串口流 1 天 + 板注册表 1 天 + 测试 1-2 天)。
|
||||
64
Docs/F18_datasheet与手册RAG.md
Normal file
64
Docs/F18_datasheet与手册RAG.md
Normal file
@ -0,0 +1,64 @@
|
||||
# F18 datasheet 与手册 RAG(F-DSRAG)
|
||||
|
||||
> **满足嵌入式需求维度**:#6 datasheet/register 精度(覆盖 #5 设备树 / #3 外设)
|
||||
> **场景锚定**:每个外设芯片配 datasheet(几百到几千页 PDF),含寄存器映射表(地址 `0x40021000` = RCC AHB1,位偏移 `bit[4]` = GPIOAEN)、位域定义、复位值、时序图、电气参数。STM32F4 参考手册 RM0090 1800+ 页。**上下文巨大 + 数值零容错**——寄存器地址错一位=写错硬件模块,位偏移错=误改不相关功能甚至清零关键配置。LLM 训练数据里这类精确数值少,易幻觉地址/位偏移。靠记忆=幻觉=写错寄存器(缺陷 #8 命门二的源头)。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
pi 无内置 RAG,read 工具读 PDF 不可读(缺陷 #2,治由 F02)。`registerTool`(types.ts:1251)注册 `datasheet_query` 检索工具。`ToolDefinition.promptGuidelines`(types.ts:459)注入"寄存器地址必须从 datasheet_query 查证,不得靠记忆"指导。`ReadOperations` 接口(read.ts:49-56)`readFile` 可覆盖读远程/容器内文件。`tool_result` 事件(types.ts:965-973)可在 read 工具结果后追加 RAG 段落回填。`context` 事件(types.ts:670-673)可在 LLM 调用前注入 datasheet 段落。`pi.exec()`(types.ts:1334)调 `pdftotext`/`pdfinfo` 做 PDF 抽取。无内置 MCP(缺陷 #10)。`truncate.ts:11-12` DEFAULT_MAX_LINES=2000/50KB。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**做一个 pi 扩展 `dsrag.ts` + 一个可选 MCP server**。两条路线选其一或组合:
|
||||
|
||||
### 路线 A(推荐,本地向量库)
|
||||
1. **PDF/文档抽取**:扩展加载时或首次查询,用 `pi.exec("pdftotext", ["-layout", pdfPath, "-"], cwd, {timeout:60000})`(exec.ts:34)提取文本。按页/节分块(`\f` 分页符切分),每块带页码元数据。内核头文件(`include/linux/`)直接 readFile 后按 `#define`/结构体分块。设备树 `.dts` 按节点分块。
|
||||
2. **向量索引**:用 `better-sqlite3` + `sqlite-vss` 扩展(或纯 JS `lanceDB`/`hnswlib-node`)建本地向量库。embedding 调内部网关 `/v1/embeddings`(glm-5.2 网关有 embedding 接口)或本地 `@xenova/transformers`(离线)。索引存 `~/.pi/agent/dsrag-index/`,以文档路径 hash 为 key。
|
||||
3. **注册 `datasheet_query` 工具** via `pi.registerTool()`(types.ts:1251):
|
||||
- 参数 `{query, docPath?, topK?}`
|
||||
- `execute()`:query embedding → cosine similarity 检索 → 返回 top-K 段落 + 页码 + 文件路径
|
||||
- `promptGuidelines`(types.ts:459)注入"寄存器地址/位偏移/复位值必须通过 datasheet_query 工具查证,不得凭记忆推断"
|
||||
- `promptSnippet`(types.ts:457)"Query datasheet/register manual for exact addresses and bit fields"
|
||||
4. **与 F02 联动**:`tool_result` 事件(types.ts:965-973)监听 `toolName==="read"`,若读取 `.pdf`(read 不支持 PDF,缺陷 #2),拦截返回 RAG 检索结果代替——`ToolResultEventResult.content`(types.ts:1090-1095)替换为 `[TextContent: {type:"text", text:"PDF not directly readable. Use datasheet_query to search this document."}]`。
|
||||
5. **增量索引**:`session_start`(types.ts:562-568)扫描 `~/.pi/agent/dsrag-index/` 与当前 cwd 下 datasheet 文件 mtime 对比,增量更新。
|
||||
|
||||
### 路线 B(与 F08 联动,可选)
|
||||
若 MCP 生态有现成 datasheet RAG server,挂一个 MCP client 扩展(F08)。但 pi 无内置 MCP(缺陷 #10),需先建 MCP client 框架——工作量大,不推荐 MVP 阶段。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
datasheet_query: {
|
||||
query: string, // "GPIOA_BASE address" / "RCC_AHB1ENR bit 0"
|
||||
docPath?: string, // 限定文档路径,不填则全库检索
|
||||
topK?: number, // 默认5
|
||||
filter?: { page?: number, section?: string }
|
||||
}
|
||||
// 返回: [{ text, page, filePath, score }]
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F02 增强读取**:F02 的 PDF 抽取(extractPdfText)是 F18 索引的前置;F18 也可用 `pdftotext -layout` 自抽。
|
||||
- **F14 外设探测 / F15 JTAG**:i2c_get/read_mem 读寄存器前先用 datasheet_query 查地址/位域(F18 promptGuidelines 引导)。
|
||||
- **F08 MCP 桥接**:可桥接外部 datasheet RAG MCP server(路线 B)。
|
||||
- **F10 硬件状态持久化**:查到的寄存器值落 session 防 compaction 丢失。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. 查 `GPIOA_BASE` 返回 datasheet 段落包含 `0x48000000`(与 glm-5.2 已知正确值一致),附页码和文件路径。
|
||||
2. 查不存在的寄存器 `FOOBAR_Z` 返回空结果集(不幻觉地址),`isError: false` 但 content 为 `"No matching passages found"`。
|
||||
3. 3000 页 PDF 首次索引时间 < 60 秒,后续查询 < 2 秒。
|
||||
4. `read` 工具读 `.pdf` 时被 `tool_result` 拦截,返回提示用 `datasheet_query`(缺陷 #2 缓解)。
|
||||
5. `promptGuidelines` 在 system prompt 的 Guidelines section 出现(agent-session.ts:1033-1036 收集后 system-prompt.ts:108-113 注入)。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- `pdftotext` 需系统安装 `poppler-utils`;不可用退化为 `pdf-parse` npm 包(纯 JS 但对扫描型 PDF 无效)。
|
||||
- embedding 模型选择:网关 embedding 质量未知,本地 `@xenova/transformers` 需下载模型文件(~100MB)。
|
||||
- 向量库选型:`better-sqlite3` 是 native 模块,jiti 零隔离环境(缺陷 #5)崩溃风险——建议纯 JS `hnswlib-node` 或纯 JS 实现。
|
||||
- 寄存器表表格结构在 `pdftotext -layout` 后可能错位——需后处理对齐。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P1 高**——补"寄存器级零容错查证"命门,但 F17 板链路是前置|**6-8 人日**(PDF 抽取 1 天 + 向量库 2 天 + 工具注册 1 天 + F02 联动 1 天 + 测试 1-2 天)。
|
||||
69
Docs/F19_硬件行为验证判据.md
Normal file
69
Docs/F19_硬件行为验证判据.md
Normal file
@ -0,0 +1,69 @@
|
||||
# F19 硬件行为验证判据(F-VERIFY)
|
||||
|
||||
> **满足嵌入式需求维度**:#9 硬件闭环迭代(覆盖 #3 外设 / #2 烧录)
|
||||
> **场景锚定**:嵌入式验证靠物理信号——dmesg 里外设是否枚举、gpio 读值、i2c 读值、sysfs 状态、串口标志、电流曲线。**不是 stdout**。web agent 改完代码跑测试看 stdout/HTTP 响应即验证;嵌入式 agent 改完驱动,验证靠看 LED 亮灭、电机转动、示波器波形、dmesg 外设枚举——这些是物理世界信号,无法靠单元测试断言穷尽。注入故障板(GPIO 33 短路到地)时 agent 要判 fail 并给根因。与 HWE-Bench judges 门同构——fail-closed 判据,四元组(任务/诊断轨迹/judge真值/根因)落库。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
`registerTool`(types.ts:1251)注册 `verify` 工具。`tool_call` 事件(types.ts:904-912)`ToolCallEventResult.block` 强制"verify 前不许下一步"(与 F05 联动)。`pi.appendEntry`(types.ts:1318)四元组落 session JSONL。`appendCustomEntry`(session-manager.ts:1122-1133)持久化验证记录。`appendCustomMessageEntry`(session-manager.ts:1171-1189)注入验证结论到 LLM 上下文。`BashOperations`(bash.ts:62-80)采集 dmesg/gpio/i2c 读值。`pi.exec()`(types.ts:1334)执行 dmesg/gpioget/i2cget/cat /sys/...。`session_before_compact`(types.ts:592-602)保护验证记录不被 compaction 摘要掉(缺陷 #14 缓解)。`tool_result`(types.ts:965-973)可在 verify 结果后注入根因分析。HWE-Bench judges 门同构:fail-closed 判据。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**做一个 pi 扩展 `verify.ts`**,注册 `verify` 工具 + `tool_call` 钩子 + session 持久化:
|
||||
|
||||
1. **注册 `verify` 工具** via `pi.registerTool()`(types.ts:1251):
|
||||
- 参数 `{task, signals: SignalSpec[], expect: ExpectSpec}`
|
||||
- `SignalSpec`:`{type: "dmesg"|"gpio"|"i2c"|"sysfs"|"serial"|"current", args: Record<string,string>}`
|
||||
- `ExpectSpec`:`{match: string|number, mode: "contains"|"equals"|"regex"|"range", failClosed: boolean}`
|
||||
- `execute()`:对每个 signal,用 `pi.exec()` 或 `BashOperations.exec()` 采集信号值(dmesg grep、`gpioget chip line`、`i2cget -y bus addr`、`cat /sys/class/...`),比对 expect,产出 pass/fail + 根因
|
||||
- `executionMode:"sequential"`(types.ts:477)——验证采集不可并行(硬件信号共享资源)
|
||||
|
||||
2. **四元组落库**:`execute()` 结束后 `pi.appendEntry("verify:record", {task, trace, judge, rootCause})`(types.ts:1318 → session-manager.ts:1122),CustomEntry 不参与 LLM 上下文但持久化到 JSONL。同时 `pi.sendMessage({customType:"verify:result", content: judge结论, display:true, details:{rootCause}}, {triggerTurn:false})`(types.ts:1302)注入 LLM 上下文(CustomMessageEntry 参与 context,session-manager.ts:135-141)——让 agent 后续推理看到验证结论。
|
||||
|
||||
3. **与 F05 联动(verify 前不许下一步)**:注册 `tool_call` 事件 handler(types.ts:1241)。维护 `pendingVerify: boolean`。当 agent 发 `bash`/`edit`/`write` 工具调用但上一轮 verify 未通过时,返回 `{block:true, reason:"Previous verify pending. Run verify tool first."}`(types.ts:1071-1080)。block 机制在 agent-loop.ts:636-646 生效——工具不执行,返回 error result。可加 `terminate:true` 让 agent 停下。
|
||||
|
||||
4. **compaction 保护**:`session_before_compact`(types.ts:592-602)中扫描 context entries,将 `customType:"verify:result"` 的 CustomMessageEntry 标记不可摘要——通过 `SessionBeforeCompactResult.compaction` 提供自定义 compaction(types.ts:1117-1120),或 compaction 后用 `context` 事件(types.ts:670-673)重新注入关键验证结论。
|
||||
|
||||
5. **与 F17 联动**:verify 的 signal 采集通过 `pi.events.emit("boardlink:exec", {boardId, command})` 委托给 F17 扩展执行板上命令(event-bus.ts:15),避免重复实现 SSH/串口执行。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
verify: {
|
||||
task: string, // "GPIO pin 33 output high"
|
||||
signals: [
|
||||
{ type: "dmesg", args: { grep: "gpio.*33" } },
|
||||
{ type: "gpio", args: { chip: "gpiochip0", line: 33 } },
|
||||
{ type: "sysfs", args: { path: "/sys/class/gpio/gpio33/value" } }
|
||||
],
|
||||
expect: { match: "1", mode: "equals", failClosed: true }
|
||||
}
|
||||
// 四元组: { task, trace: [signal采集值], judge: "pass"|"fail", rootCause: string|null }
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F05 硬件安全门**:verify 前不许下一步,靠 `tool_call` 钩子 block。
|
||||
- **F17 板链路**:signal 采集委托 boardlink:exec 执行板上命令。
|
||||
- **F10 硬件状态持久化**:四元组 appendEntry 落库,compaction 保护。
|
||||
- **F20 闭环编排**:F20 的 verify checkpoint 须 F19 通过才许继续;verify 通过发 `pi.events.emit("verify:passed", ...)`。
|
||||
- **F14 外设探测**:gpio_get/i2c_get 采集信号作 verify 输入。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. 注入故障板(GPIO 33 短路到地),`verify` 工具执行后判 `fail`,rootCause 含 `"gpio33 value=0 expected=1"`,四元组通过 `ctx.sessionManager.getEntries()` 能查到 `customType:"verify:record"` 的 CustomEntry。
|
||||
2. `verify` 结果通过 `CustomMessageEntry`(sendMessage)注入 LLM 上下文,`buildSessionContext`(session-manager.ts:1276)能在 messages 中看到 verify 结论。
|
||||
3. F05 联动:上一轮 verify 未通过时,agent 发 `bash` 工具调用被 `tool_call` handler block,返回 error result `"Previous verify pending"`,agent-loop.ts:636 确认 block 生效。
|
||||
4. `/compact` 后,`session_before_compact` handler 能扫描到 `customType:"verify:result"` 条目,compaction 后 `context` 事件重新注入关键验证值。
|
||||
5. verify 工具 `executionMode:"sequential"`,含 verify 的 tool batch 走 `executeToolCallsSequential`(agent-loop.ts:422)。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- dmesg 采集需 root 权限或 `dmesg` 可执行——板上通常 `root@board` 可用。
|
||||
- **fail-closed 语义**:signal 采集超时/失败时必须判 fail 而非 pass(与 HWE-Bench judges 一致)。
|
||||
- F05 的 `tool_call` block 是硬 block——agent 无法绕过,但如果 agent 理解不了 block reason 可能陷入循环(需在 reason 中给清晰指引)。
|
||||
- 四元组 schema 需与 HWE-Bench judges 门对齐——参考 `hwe-harness` 的 judge 协议。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P1 高**——物理信号判读是嵌入式验证核心,依赖 F17|**4-5 人日**(工具注册 1 天 + 信号采集 1 天 + 四元组落库 1 天 + F05 联动 1 天 + 测试 1 天)。
|
||||
85
Docs/F20_硬件闭环迭代编排.md
Normal file
85
Docs/F20_硬件闭环迭代编排.md
Normal file
@ -0,0 +1,85 @@
|
||||
# F20 硬件闭环迭代编排(F-LOOP)
|
||||
|
||||
> **满足嵌入式需求维度**:#9 硬件闭环迭代(覆盖 #7 构建 / #2 烧录)
|
||||
> **场景锚定**:嵌入式核心节奏:改码 → 交叉编译 → scp/烧到板 → 上板运行 → 看 dmesg/串口日志/示波器/逻辑分析仪 → 回到改码。**单板串行,每轮分钟级,无法像 web 开发那样并行多 agent**。某些步骤要物理操作(按复位键、插拔外设、接示波器探头)。迭代慢、不可并行、每轮成本高(烧坏要物理恢复)。反馈回路长(改一行驱动→烧板→看时序→再改),agent 的"改-测-改"循环每次代价大,**试错容忍度极低**。乱序操作(未编译就烧、未 verify 就下一步)= 砖板或浪费时间。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
`tool_call` 事件(types.ts:904-912, 1071-1080)`ToolCallEventResult.block` + `terminate` 强制 checkpoint 顺序。`pi.appendEntry`(types.ts:1318)checkpoint 落 session。SKILL.md 格式(skills.ts:67-81, 160-167)编排流程写成 skill。`formatSkillsForPrompt()`(skills.ts:335-361)skill 注入 `<available_skills>` 到 system prompt。AGENTS.md(resource-loader.ts:71, 134-153)注入 `<project_context>`。`before_agent_start`(types.ts:699-709)注入当前 checkpoint 状态。`context` 事件(types.ts:670-673)在 LLM 调用前注入 checkpoint 序列。`tool_result`(types.ts:965-973)编译/烧录结果后更新 checkpoint。`pi.events`(event-bus.ts:1-33)跨扩展通信(与 F19/F21 联动)。`ToolDefinition.promptGuidelines`(types.ts:459)注入"必须按 checkpoint 顺序执行"指导。`session_before_compact`(types.ts:592-602)保护 checkpoint 状态不被 compaction 丢失。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**组合方案:扩展(tool_call 钩子)+ SKILL.md(编排流程)+ AGENTS.md(checkpoint 规则)**:
|
||||
|
||||
1. **SKILL.md 编排流程**:在 `.pi/skills/hw-loop/SKILL.md` 写嵌入式闭环 SOP:
|
||||
```
|
||||
1. Edit source code (edit/write tool)
|
||||
2. Cross-compile (bash: aarch64-linux-gnu-gcc / cmake --build / build tool)
|
||||
3. Flash to board (flash tool / scp / dd)
|
||||
4. Verify on board (verify tool)
|
||||
5. Check dmesg/logs (board_exec: dmesg)
|
||||
6. If fail, iterate from step 1
|
||||
```
|
||||
Skill 通过 `formatSkillsForPrompt`(skills.ts:335-361)注入 `<available_skills>` 到 system prompt,模型用 read 工具加载 body。`/skill:hw-loop` slash command(agent-session.ts:1304-1333)可直接展开 body。
|
||||
|
||||
2. **AGENTS.md checkpoint 规则**:项目 `AGENTS.md` 写 checkpoint 顺序约束:
|
||||
```
|
||||
- NEVER flash before compile passes
|
||||
- NEVER proceed to next step before verify passes
|
||||
- After flash, always check dmesg before declaring success
|
||||
```
|
||||
AGENTS.md 通过 resource-loader.ts:71,134-153 加载,注入 `<project_context>`(system-prompt.ts:145-152)。
|
||||
|
||||
3. **扩展 `hwloop.ts`(tool_call 钩子强制 checkpoint)**:
|
||||
- 维护 checkpoint 状态机:`{currentStep: "edit"|"compile"|"flash"|"verify"|"check", stepPassed: boolean}`
|
||||
- 注册 `tool_call` 事件 handler(types.ts:1241):
|
||||
- 拦截 `bash` 工具调用(`isToolCallEventType("bash", event)` types.ts:1018),解析 `event.input.command`(BashToolCallEvent.input.command types.ts:860)
|
||||
- 命令含 `dd of=`/`fastboot flash`/`scp`(flash 操作)但 checkpoint 未到 flash 或 compile 未通过 → `{block:true, reason:"Compile checkpoint not passed. Run compile first.", terminate:true}`(types.ts:1071-1080)
|
||||
- 命令含 `aarch64-linux-gnu-gcc`/`cmake --build`/`build`(编译操作)→ 允许执行,tool_result 中检查 exit code 更新 checkpoint
|
||||
- `tool_result` 事件(types.ts:1242):检查 bash 结果,编译通过(exit 0)→ `stepPassed=true`,更新 checkpoint 到 flash;失败 → 保持 compile
|
||||
- checkpoint 状态持久化:`pi.appendEntry("hwloop:checkpoint", {currentStep, stepPassed, timestamp})`(types.ts:1318)
|
||||
- `session_start`(types.ts:562-568)从 entries 重建 checkpoint 状态
|
||||
|
||||
4. **与 F19 联动**:`tool_call` handler 检测到 `verify` 工具调用时更新 checkpoint 到 verify 步骤。verify 通过(`pi.events.on("verify:passed", ...)` EventBus 事件)更新到 check 步骤。verify 前若有 flash 操作被 block。
|
||||
|
||||
5. **与 F21 联动**:`tool_call` handler 检测到 `build` 工具调用时委托 F21(后台构建),构建完成 `pi.events.emit("build:done", {exitCode})` 通知,F-LOOP 监听后更新 checkpoint。
|
||||
|
||||
6. **checkpoint 落 session + compaction 保护**:每步 checkpoint 变化 `pi.appendEntry("hwloop:checkpoint", ...)`(types.ts:1318)。`session_before_compact`(types.ts:592-602)保护最近 checkpoint 不被摘要。`context` 事件(types.ts:670-673)compaction 后重新注入当前 checkpoint 状态到 messages,确保 agent 不"忘记"当前在哪一步(缺陷 #14 缓解)。
|
||||
|
||||
7. **注册 `loop_status` 工具**:via `pi.registerTool()`(types.ts:1251),让 agent 主动查询当前 checkpoint 状态。`promptSnippet:"Query current hardware loop checkpoint status"`。`promptGuidelines:["Always check loop_status before starting a new iteration step"]`。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
loop_status: { } → { currentStep, stepPassed, history: [{step, passed, timestamp}] }
|
||||
// tool_call handler 伪码:
|
||||
// if command matches flash pattern && checkpoint !== "flash-ready" → block
|
||||
// if command matches compile pattern → allow, track in tool_result
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F19 硬件验证**:verify 通过发 verify:passed 事件,更新 checkpoint 到 check。
|
||||
- **F21 构建封装**:build 完成 build:done 事件,更新 checkpoint。
|
||||
- **F05 硬件安全门**:F05 拦截裸 dd,F20 在更高层强制 checkpoint 顺序。
|
||||
- **F13 安全烧录**:F20 flash checkpoint 须 compile 通过才许 F13 执行。
|
||||
- **F10 硬件状态持久化**:checkpoint 落 session,compaction 保护。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. 乱序操作被 block:agent 发 `dd if=image.bin of=/dev/mmcblk0`(flash)但编译未通过时,`tool_call` handler 返回 `{block:true}`,agent-loop.ts:636-646 确认工具不执行,返回 error result `"Compile checkpoint not passed"`。
|
||||
2. 每轮 checkpoint 变化落 session:`ctx.sessionManager.getEntries()` 能查到 `customType:"hwloop:checkpoint"` 的 CustomEntry 序列。
|
||||
3. session resume 后 `session_start` handler 重建 checkpoint 状态,agent 发 `loop_status` 工具能正确返回当前步骤。
|
||||
4. `/compact` 后 `context` 事件重新注入 checkpoint 状态,agent 不丢失"当前在编译步骤"信息。
|
||||
5. `loop_status` 工具的 `promptSnippet` 出现在 system prompt 的 Available tools section(system-prompt.ts:82-84)。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- `tool_call` handler 命令模式匹配需覆盖各种写法(`dd`、`sudo dd`、`fastboot flash`、`scp ... board:`)——正则可能漏匹配。
|
||||
- checkpoint 状态机复杂度:多板多任务并发时状态机需区分 per-board checkpoint。
|
||||
- `tool_call` handler 是同步串行调用(runner.ts:940-948),不能做异步长时间操作——只能快速状态检查。
|
||||
- 依赖 F19 和 F21 功能先就绪。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P2 中高**——编排层,依赖 F19 + F21 先就绪|**4-5 人日**(状态机 1 天 + tool_call 钩子 1 天 + SKILL.md/AGENTS.md 0.5 天 + compaction 保护 1 天 + 测试 1 天)。
|
||||
83
Docs/F21_构建系统封装与长任务跟踪.md
Normal file
83
Docs/F21_构建系统封装与长任务跟踪.md
Normal file
@ -0,0 +1,83 @@
|
||||
# F21 构建系统封装与长任务跟踪(F-BUILD)
|
||||
|
||||
> **满足嵌入式需求维度**:#7 构建系统(覆盖 #9 闭环 / #1 工具链)
|
||||
> **场景锚定**:嵌入式镜像系统级构建靠 buildroot(`make menuconfig` 选包 → `make` 出 rootfs/uboot/kernel 一体)、Yocto/Bitbake(写 `recipe.bb` → `bitbake core-image-minimal`,层管理 `meta-*/`)。项目级用 CMake + toolchain file 或 Makefile。内核用 Kconfig(`make ARCH=arm64 defconfig`/`menuconfig`/`savedefconfig`)。**配置矩阵大(Yocto 一镜像数千 recipe、buildroot 数千 package 选项),一次构建几十分钟到几小时,agent 不能频繁全量重建试错**。Yocto layer 依赖复杂(DEPENDS/RDEPENDS),改一个 recipe 触发依赖链重新构建。Kconfig defconfig 漏一个 `CONFIG_=y` 对应功能不编入。
|
||||
|
||||
## 1. 现状(pi 范式参照)
|
||||
|
||||
`registerTool`(types.ts:1251)注册 `build` 工具。`ToolDefinition.execute(onUpdate)`(types.ts:480-486)`AgentToolUpdateCallback` 流式回灌日志。`OutputAccumulator`(output-accumulator.ts:35-222)有界内存缓冲 + temp file。bash 工具 streaming 模式(bash.ts:338-463)`onUpdate` + `scheduleOutputUpdate` 100ms 节流(BASH_UPDATE_THROTTLE_MS:206)。`tool_execution_update` 事件(types.ts:770-776)流式更新经 agent-loop.ts:670-711 发射。`BashOperations`(bash.ts:62-80)可插拔执行后端。`pi.appendEntry`(types.ts:1318)构建状态落 session。`pi.events`(event-bus.ts:1-33)构建完成通知 F20。**无后台任务机制**(grep run_in_background/BackgroundProcess 零命中,execute() 全部 await 进程结束)。`exec.ts:34-107` execCommand 简单命令执行。
|
||||
|
||||
## 2. 二开方案
|
||||
|
||||
**做一个 pi 扩展 `build.ts`**,注册 `build` 工具,后台进程 + 流式回灌 + 增量构建感知:
|
||||
|
||||
1. **注册 `build` 工具** via `pi.registerTool()`(types.ts:1251):
|
||||
- 参数 `{project, target?, incremental?, clean?, buildDir?}`
|
||||
- `promptSnippet:"Start a build (buildroot/yocto/cmake) and stream logs back"`(types.ts:457)
|
||||
- `promptGuidelines:["Use build tool for long-running builds instead of bash. Build runs in background and streams logs."]`(types.ts:459)
|
||||
- `executionMode:"sequential"`(types.ts:477)——构建不可并行
|
||||
|
||||
2. **后台进程机制**(pi 无内置,需自建):
|
||||
- `execute()` 内部 `spawn(buildCmd, args, {detached:true, stdio:["ignore","pipe","pipe"]})`(参考 bash.ts:103-109)
|
||||
- **关键设计**:`execute()` 不 await 进程结束。spawn 进程获取 `child.pid`;创建 `OutputAccumulator`(output-accumulator.ts:35),`child.stdout.on("data", (data)=>{accumulator.append(data); scheduleUpdate();})`;`scheduleUpdate()` 用 100ms 节流(复制 bash.ts:374-387 模式)调 `onUpdate({content:[{type:"text",text:snapshot.content}], details:{buildId,pid,phase}})`;进程结束 `child.on("close", (code)=>{pi.appendEntry("build:result", {buildId, exitCode:code, duration})})`。
|
||||
- **但有问题**:`execute()` 返回后 `onUpdate` 回调不再有效(agent-loop.ts:698 `acceptingUpdates=false`)。所以流式回灌只在 execute() pending 期间有效。
|
||||
- **解法**:让 `execute()` 保持 pending 直到构建完成——`await waitForChildProcess(child)`(bash.ts:139 模式),但用 onUpdate 持续流式回灌。这样 agent 不发新 tool call(等 build 返回),但 TUI 实时显示构建日志。**阻塞 agent 但流式显示**。
|
||||
- **替代解法(真后台,推荐)**:`execute()` 立即返回"build started",构建进程后台跑。注册第二个 `build_status` 工具让 agent 查询进度。后台进程日志用 OutputAccumulator 存 temp file,`build_status` 工具读 temp file 尾部返回。构建完成 `pi.events.emit("build:done", {buildId, exitCode})`(event-bus.ts:15)通知 F20。**推荐此方案**——agent 不阻塞,可同时做其他事。
|
||||
|
||||
3. **增量构建感知**:
|
||||
- `build` 工具参数 `incremental:true`(默认):检测 `build/.build-id` 或 `build/.last-build-time` 文件 mtime vs 源码 mtime,若源码未变且 `clean:false`,跳过构建返回 `"Incremental: no source changes since last build"`
|
||||
- buildroot/yocto 自带增量(`make` 只重编变更文件),但需检测 `defconfig`/`.config` 变化触发重配置
|
||||
- cmake:检测 `CMakeCache.txt` 存在且 `CMakeLists.txt` mtime 未变 → 跳过 `cmake ..`,只跑 `cmake --build`
|
||||
|
||||
4. **与 F01 联动**:若 F01 有持久后台进程(tmux 会话),`build` 工具 execute() 改为 `ssh board "tmux send-keys -t build 'cmake --build .' Enter"`,日志通过 `tmux capture-pane` 拉取。构建进程在 tmux 中持续运行,不受 agent session 中断影响。
|
||||
|
||||
5. **日志流式回灌**:`build_status` 工具参数 `{buildId, tail?, wait?}`,读 OutputAccumulator 的 temp file 尾部 N 行返回。也可在 build 工具 execute() pending 期间通过 onUpdate 持续流式回灌(bash.ts:353-364 模式)。
|
||||
|
||||
6. **构建状态落 session**:`pi.appendEntry("build:status", {buildId, project, target, pid, startedAt, phase})`(types.ts:1318)。`session_start`(types.ts:562)时扫描 entries 重建未完成构建状态——检测孤儿进程(pid 还在跑)。
|
||||
|
||||
## 3. 接口/工具 schema
|
||||
|
||||
```
|
||||
build: {
|
||||
project: string, // "buildroot" / "yocto" / "cmake"
|
||||
target?: string, // "defconfig" / "image" / "all"
|
||||
incremental?: boolean, // default true
|
||||
clean?: boolean, // default false
|
||||
buildDir?: string // 构建目录
|
||||
}
|
||||
// 立即返回: { buildId, pid, logFile, status: "running" }
|
||||
|
||||
build_status: {
|
||||
buildId: string,
|
||||
tail?: number, // 返回尾部行数,默认50
|
||||
wait?: boolean // 是否等到完成
|
||||
}
|
||||
// 返回: { status: "running"|"done"|"failed", exitCode?, tail: string, duration? }
|
||||
```
|
||||
|
||||
## 4. 与其他功能联动
|
||||
|
||||
- **F01 持久 Shell**:tmux 后台构建走 pshell/持久会话,构建进程不受 agent session 中断影响。
|
||||
- **F12 交叉编译**:build 工具用 F12 生成的 toolchain.cmake 跑 cmake。
|
||||
- **F20 闭环编排**:build 完成 emit build:done 事件,F20 更新 checkpoint 到 flash 步骤。
|
||||
- **F17 板链路**:板上构建走 board_exec。
|
||||
- **F07 环境探针**:F07 注入 PI_BUILD_DIR,build 工具据此找构建目录。
|
||||
|
||||
## 5. 验收标准(可测)
|
||||
|
||||
1. `build` 工具发起构建后立即返回 `buildId` + `pid`,agent 不阻塞——可继续发其他 tool call(如 `read` 查文档),验证 `execute()` 已 resolve。
|
||||
2. `build_status` 工具能查询构建进度,返回尾部日志(OutputAccumulator 的 temp file 路径在 `fullOutputPath` 字段,output-accumulator.ts:117)。
|
||||
3. 增量构建:第二次 `build` 调用 `incremental:true` 且源码未变时,返回 `"No source changes, skipping build"`(< 1 秒)。
|
||||
4. 构建完成后 `pi.events.emit("build:done", {buildId, exitCode})` 被发射(event-bus.ts:15),F20 扩展 `pi.events.on("build:done", ...)` 能收到通知。
|
||||
5. 构建结果通过 `pi.appendEntry("build:result", ...)` 落 session JSONL,session resume 后 `session_start` handler 能查到历史构建记录。
|
||||
|
||||
## 6. 风险与依赖
|
||||
|
||||
- 真后台方案下 `execute()` 立即返回,但 `onUpdate` 在 promise resolve 后失效(agent-loop.ts:698)——流式回灌只能通过 `build_status` 工具拉取,不能在 execute() 返回后继续推送。
|
||||
- 后台进程生命周期管理:agent session 结束后构建进程需继续运行(`detached:true` + `unref()`),但 `killTrackedDetachedChildren`(shell.ts:190-195)会在 shutdown 时杀掉——需 `unref()` 解除跟踪。
|
||||
- buildroot/yocto 构建目录巨大(10-50GB),OutputAccumulator 的 temp file 需限制大小。
|
||||
- jiti 零隔离(缺陷 #5):native 构建工具链崩溃不影响(构建是子进程不是扩展内 native 调用),风险低。
|
||||
|
||||
## 7. 优先级 / 工作量
|
||||
|
||||
**P1 高**——长任务跟踪是闭环效率关键,F20 依赖|**5-6 人日**(后台进程 2 天 + 流式回灌 1 天 + 增量感知 1 天 + build_status 工具 1 天 + 测试 1 天)。
|
||||
55
README.md
Normal file
55
README.md
Normal file
@ -0,0 +1,55 @@
|
||||
# @d-robotics/physical-byte-agent
|
||||
|
||||
基于 [pi](https://github.com/earendil-works/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`。
|
||||
|
||||
## 用法
|
||||
|
||||
```bash
|
||||
# 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();
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
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 板上端到端待跑。
|
||||
40
bin/pba.ts
Normal file
40
bin/pba.ts
Normal file
@ -0,0 +1,40 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* pba —— Physical Byte Agent CLI 入口。
|
||||
*
|
||||
* 用法:
|
||||
* npx tsx bin/pba.ts --print-extensions # 离线装配自检(不需 pi 构建)
|
||||
* npx tsx bin/pba.ts # 启动 pi AgentSession(需 pi 已构建 + DROBOTICS_LLM_KEY)
|
||||
*
|
||||
* 也可直接用 pi CLI 跑本包为 profile(pi 自动加载 .pi/extensions/index.ts barrel):
|
||||
* cd <pkg> && pi
|
||||
*/
|
||||
|
||||
import { PhysicalByteAgent } from "../src/index.js";
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const argv = process.argv.slice(2);
|
||||
|
||||
if (argv.includes("--print-extensions") || argv.includes("--verify")) {
|
||||
// 离线装配自检:不解析 pi 运行时
|
||||
const info = PhysicalByteAgent.verifyAssembly();
|
||||
console.log(`physical-byte-agent: ${info.count} domain extensions assembled`);
|
||||
for (const name of info.domains) {
|
||||
console.log(` - ${name}`);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
const inMemory = argv.includes("--in-memory");
|
||||
const agent = new PhysicalByteAgent();
|
||||
const result = await agent.launch({ inMemory });
|
||||
if (result.modelFallbackMessage) {
|
||||
console.warn(`[pba] model fallback: ${result.modelFallbackMessage}`);
|
||||
}
|
||||
console.log("[pba] session started. (interactive loop requires pi TUI; use `pi` from this dir for full TUI)");
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
console.error("[pba] fatal:", err);
|
||||
process.exit(1);
|
||||
});
|
||||
28
models.json
Normal file
28
models.json
Normal file
@ -0,0 +1,28 @@
|
||||
{
|
||||
"$schema": "https://earendil-works.github.io/pi/models.schema.json",
|
||||
"providers": [
|
||||
{
|
||||
"name": "drobotics-glm",
|
||||
"baseUrl": "https://ai-api.d-robotics.cc/v1",
|
||||
"apiKey": "${DROBOTICS_LLM_KEY}",
|
||||
"api": "openai",
|
||||
"authHeader": true,
|
||||
"models": [
|
||||
{
|
||||
"id": "glm-5.2",
|
||||
"name": "GLM-5.2 (D-Robotics gateway)",
|
||||
"reasoning": true,
|
||||
"thinkingLevelMap": { "off": null, "low": null, "medium": null, "high": null },
|
||||
"input": ["text"],
|
||||
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
|
||||
"contextWindow": 1000000,
|
||||
"maxTokens": 8192,
|
||||
"compat": {
|
||||
"thinkingFormat": "qwen",
|
||||
"supportsReasoningEffort": false
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
5016
package-lock.json
generated
Normal file
5016
package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
31
package.json
Normal file
31
package.json
Normal file
@ -0,0 +1,31 @@
|
||||
{
|
||||
"name": "@d-robotics/physical-byte-agent",
|
||||
"version": "0.1.0",
|
||||
"description": "基于 pi 二开的嵌入式开发 Agent(glm-5.2 + 硬件闭环)",
|
||||
"type": "module",
|
||||
"main": "./src/index.ts",
|
||||
"bin": {
|
||||
"pba": "./bin/pba.ts"
|
||||
},
|
||||
"pi": {
|
||||
"extensions": [
|
||||
"src/extensions/index.ts"
|
||||
]
|
||||
},
|
||||
"scripts": {
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"smoke": "tsx bin/pba.ts --print-extensions"
|
||||
},
|
||||
"dependencies": {
|
||||
"@earendil-works/pi-ai": "*",
|
||||
"@earendil-works/pi-coding-agent": "*"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
"tsx": "^4.19.0",
|
||||
"typescript": "^5.6.0",
|
||||
"vitest": "^2.1.9"
|
||||
}
|
||||
}
|
||||
457
pi+glm5.2_嵌入式开发场景缺陷分析.md
Normal file
457
pi+glm5.2_嵌入式开发场景缺陷分析.md
Normal file
@ -0,0 +1,457 @@
|
||||
# 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 二开时再逐条给修复方案。
|
||||
94
src/agent.ts
Normal file
94
src/agent.ts
Normal file
@ -0,0 +1,94 @@
|
||||
/**
|
||||
* @module agent
|
||||
*
|
||||
* PhysicalByteAgent —— 程序化启动入口。
|
||||
*
|
||||
* launch() 动态 import pi 的 createAgentSession(pi 未构建/离线时不在模块顶层解析),
|
||||
* 以本包根为 agentDir(读 models.json),cwd 为包根(pi 自动发现 .pi/extensions/index.ts
|
||||
* barrel 装配全部 21 域扩展)。
|
||||
*
|
||||
* verifyAssembly() 是离线可跑的装配自检:不依赖 pi 运行时,只确认 barrel 21 工厂就位。
|
||||
*/
|
||||
|
||||
import { extensionFactories } from "./extensions/index.js";
|
||||
|
||||
export interface LaunchOptions {
|
||||
/** 工作目录,默认本包根。pi 从此发现 .pi/extensions/ barrel。 */
|
||||
cwd?: string;
|
||||
/** agentDir(读 models.json + auth),默认本包根。 */
|
||||
agentDir?: string;
|
||||
/** 覆盖默认模型 id,默认 glm-5.2(从 models.json)。 */
|
||||
modelId?: string;
|
||||
/** 思考级别,默认 off(glm-5.2 thinking 已在 provider 配置层关掉)。 */
|
||||
thinkingLevel?: "off" | "low" | "medium" | "high";
|
||||
/** 显式工具白名单。 */
|
||||
tools?: string[];
|
||||
/** 用内存 session(不需 better-sqlite3 native 构建)。 */
|
||||
inMemory?: boolean;
|
||||
}
|
||||
|
||||
export interface LaunchResult {
|
||||
/** pi AgentSession 实例。 */
|
||||
session: unknown;
|
||||
/** 模型回退提示(若请求的模型不可用)。 */
|
||||
modelFallbackMessage?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Physical Byte Agent —— pi 二开的嵌入式开发 Agent。
|
||||
*
|
||||
* 用法:
|
||||
* import { PhysicalByteAgent } from "@d-robotics/physical-byte-agent";
|
||||
* const { session } = await new PhysicalByteAgent().launch();
|
||||
*/
|
||||
export class PhysicalByteAgent {
|
||||
/** 已装配的域扩展工厂列表(21 个,按依赖顺序)。 */
|
||||
static readonly extensions = extensionFactories;
|
||||
|
||||
/**
|
||||
* 离线装配自检:确认 21 个域扩展工厂就位且都是函数。不需 pi 运行时。
|
||||
*
|
||||
* @returns 装配信息(工厂数 + 域名列表)。
|
||||
*/
|
||||
static verifyAssembly(): { count: number; domains: string[] } {
|
||||
const domains = extensionFactories.map((f) => f.name ?? "anonymous");
|
||||
for (const f of extensionFactories) {
|
||||
if (typeof f !== "function") {
|
||||
throw new Error(`extension factory is not a function: ${String(f)}`);
|
||||
}
|
||||
}
|
||||
return { count: extensionFactories.length, domains };
|
||||
}
|
||||
|
||||
/**
|
||||
* 启动 pi AgentSession。动态 import pi 的 createAgentSession(运行时解析真 pi)。
|
||||
*
|
||||
* 注意:需 pi 已构建(`cd ../pi && npm run build`,模型目录需联网 generate-models)。
|
||||
* 离线/未构建时用 verifyAssembly() 做装配自检。
|
||||
*
|
||||
* @returns LaunchResult(session + 可选回退提示)。
|
||||
*/
|
||||
async launch(opts: LaunchOptions = {}): Promise<LaunchResult> {
|
||||
const [{ createAgentSession, SessionManager }, { resolve, dirname }, { fileURLToPath }] = await Promise.all([
|
||||
import("@earendil-works/pi-coding-agent"),
|
||||
import("node:path"),
|
||||
import("node:url"),
|
||||
]);
|
||||
const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
||||
const cwd = opts.cwd ?? pkgRoot;
|
||||
const agentDir = opts.agentDir ?? pkgRoot;
|
||||
|
||||
const sessionOpts: Record<string, unknown> = {
|
||||
cwd,
|
||||
agentDir,
|
||||
thinkingLevel: opts.thinkingLevel ?? "off",
|
||||
};
|
||||
if (opts.tools) sessionOpts.tools = opts.tools;
|
||||
if (opts.inMemory && typeof (SessionManager as { inMemory?: () => unknown }).inMemory === "function") {
|
||||
sessionOpts.sessionManager = (SessionManager as { inMemory: () => unknown }).inMemory();
|
||||
}
|
||||
|
||||
const result = (await createAgentSession(sessionOpts)) as { session: unknown; modelFallbackMessage?: string };
|
||||
return { session: result.session, modelFallbackMessage: result.modelFallbackMessage };
|
||||
}
|
||||
}
|
||||
714
src/extensions/board-link.ts
Normal file
714
src/extensions/board-link.ts
Normal file
@ -0,0 +1,714 @@
|
||||
/**
|
||||
* @module board-link
|
||||
*
|
||||
* 宿主-目标板链路管理扩展 —— 治嵌入式开发场景下"板 IP/串口设备名不固定、状态分散在
|
||||
* 宿主(源码/编译器)与目标板(运行时/dmesg/寄存器)两处、agent 要跨双机协调"的缺陷。
|
||||
*
|
||||
* 板链路是所有其他嵌入式功能(持久 shell / 环境探针 / JTAG 调试 / 硬件验证 / 构建封装)
|
||||
* 的前置依赖:上层扩展通过 events 总线向本扩展请求 exec / health-check,本扩展按板类型
|
||||
* (ssh / serial / local)产出正确的命令拼接并复用宿主 spawn 执行。
|
||||
*
|
||||
* 三件事(纯逻辑可单测,零 pi 运行时依赖):
|
||||
* ① BoardRegistry —— 板注册表,fingerprint 去重(同一物理板拒绝重复注册),session 重建
|
||||
* ② makeExec —— 按板类型产出 ExecFn(ssh 拼接 / serial stub / local 直透)
|
||||
* ③ healthCheck —— 健康探活(fail-closed:异常或非 0 exit → false,板离线/不可达)
|
||||
*
|
||||
* 装配层(工厂体内):注册 4 个工具(board_connect / board_exec / board_scp / board_console)
|
||||
* + session_start 重建注册表 + tool_result 持久化 + before_agent_start 注入板信息到 system prompt
|
||||
* + events 总线跨扩展通信(exec 代理 / health-check 委托)。
|
||||
*
|
||||
* 范式:顶层仅 `import type`(esbuild 擦除),defineTool/Type 在工厂内 `await import` 动态拿,
|
||||
* 故 tests 直接 import 命名逻辑导出不会触发 pi 解析——离线可单测。pi 未构建(模型目录需联网)
|
||||
* 时工厂不跑,无副作用。见 Docs/宿主-目标板链路管理.md。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
import type {
|
||||
BoardSpec,
|
||||
BoardLinkType,
|
||||
ExecFn,
|
||||
ExecResult,
|
||||
} from "../shared/types.js";
|
||||
|
||||
// 便于调用方一次性 import;类型本身定义在 shared/types.ts
|
||||
export type { BoardSpec, BoardLinkType, ExecFn, ExecResult };
|
||||
|
||||
// ============================================================================
|
||||
// SSH 地址解析
|
||||
// ============================================================================
|
||||
|
||||
/** SSH 地址解析结果。 */
|
||||
export interface SshTarget {
|
||||
/** 登录用户名。 */
|
||||
user: string;
|
||||
/** 主机名或 IP。 */
|
||||
host: string;
|
||||
/** 端口。 */
|
||||
port: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析 SSH 地址串。
|
||||
*
|
||||
* - "root@192.168.1.100:2222" → { user:"root", host:"192.168.1.100", port:2222 }
|
||||
* - "root@board" → { user:"root", host:"board", port:22 }(默认 22)
|
||||
* - "board" → { user:"root"(默认), host:"board", port:22 }
|
||||
* - "[::1]:2222" → IPv6 带端口
|
||||
*
|
||||
* fail-tolerant:解析不出端口的默认 22,解析不出 user 的默认 root。
|
||||
*
|
||||
* @param address SSH 地址串。
|
||||
* @returns 解析出的 SshTarget。
|
||||
*/
|
||||
export function parseSshAddress(address: string): SshTarget {
|
||||
let rest = address.trim();
|
||||
let user = "root";
|
||||
const atIdx = rest.indexOf("@");
|
||||
if (atIdx >= 0) {
|
||||
user = rest.slice(0, atIdx);
|
||||
rest = rest.slice(atIdx + 1);
|
||||
}
|
||||
let port = 22;
|
||||
let host = rest;
|
||||
// IPv6 [::1]:port 或普通 host:port
|
||||
const lastColon = rest.lastIndexOf(":");
|
||||
if (lastColon >= 0) {
|
||||
const after = rest.slice(lastColon + 1);
|
||||
if (/^\d+$/.test(after)) {
|
||||
port = Number.parseInt(after, 10);
|
||||
host = rest.slice(0, lastColon);
|
||||
}
|
||||
}
|
||||
// 去除 IPv6 方括号
|
||||
host = host.replace(/^\[/, "").replace(/\]$/, "");
|
||||
return { user, host, port };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// SSH 命令拼接
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 构造 ssh 调用的参数数组(喂给 spawn("ssh", args))。
|
||||
*
|
||||
* 例:board.address="root@192.168.1.100:2222", command="ls", args=["-la"]
|
||||
* → ["-p", "2222", "root@192.168.1.100", "ls", "-la"]
|
||||
*
|
||||
* 默认端口 22 不加 -p(与 ssh 默认行为一致,减少参数噪声)。
|
||||
*
|
||||
* @param board 目标板规格(取 .address 解析)。
|
||||
* @param command 要在板上执行的命令。
|
||||
* @param args 命令参数。
|
||||
* @returns ssh argv 数组。
|
||||
*/
|
||||
export function buildSshArgs(board: BoardSpec, command: string, args: string[]): string[] {
|
||||
const { user, host, port } = parseSshAddress(board.address);
|
||||
const sshArgs: string[] = [];
|
||||
if (port !== 22) {
|
||||
sshArgs.push("-p", String(port));
|
||||
}
|
||||
sshArgs.push(`${user}@${host}`);
|
||||
sshArgs.push(command);
|
||||
sshArgs.push(...args);
|
||||
return sshArgs;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Serial 地址解析
|
||||
// ============================================================================
|
||||
|
||||
/** 串口地址解析结果。 */
|
||||
export interface SerialTarget {
|
||||
/** 设备节点路径。 */
|
||||
dev: string;
|
||||
/** 波特率。 */
|
||||
baudrate: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析串口地址 /dev/ttyUSB0@115200 → { dev, baudrate }。
|
||||
* 无 @baudrate 后缀时默认 115200。
|
||||
*
|
||||
* @param address 串口地址串。
|
||||
* @returns 解析出的 SerialTarget。
|
||||
*/
|
||||
export function parseSerialAddress(address: string): SerialTarget {
|
||||
const idx = address.lastIndexOf("@");
|
||||
if (idx >= 0) {
|
||||
const baud = address.slice(idx + 1);
|
||||
if (/^\d+$/.test(baud)) {
|
||||
return { dev: address.slice(0, idx), baudrate: Number.parseInt(baud, 10) };
|
||||
}
|
||||
}
|
||||
return { dev: address.trim(), baudrate: 115200 };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// makeExec:按板类型产出 ExecFn
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Serial stub 的固定返回。
|
||||
*
|
||||
* 纯逻辑不能操作真实串口 fd,真实运行时由扩展层接 PTY / 子进程隔离层。
|
||||
*/
|
||||
export const SERIAL_STUB_RESULT: ExecResult = {
|
||||
stdout: "[serial-stub] serial transport requires a real PTY; command not executed in pure-logic mode.\n",
|
||||
stderr: "",
|
||||
exitCode: 0,
|
||||
};
|
||||
|
||||
/** makeExec 产出。 */
|
||||
export interface MakeExecResult {
|
||||
/** 产出的 ExecFn,在该板上执行命令。 */
|
||||
exec: ExecFn;
|
||||
/** 传输方式描述(诊断/日志用)。 */
|
||||
transport: string;
|
||||
/** serial 模式返回 true,调用方据此知道不能依赖真实执行结果。 */
|
||||
isStub: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* 给定板 spec + 底层 exec(宿主 spawn),产出在该板执行命令的 ExecFn。
|
||||
*
|
||||
* - ssh: 调 underlying("ssh", buildSshArgs(board, command, args), opts) —— 复用 sshExec 模式
|
||||
* - serial: 返回 stub(纯逻辑不能操作串口 fd,真实运行时由扩展层接 PTY)
|
||||
* - local: 直透 underlying(command, args, opts) —— 宿主即目标板
|
||||
*
|
||||
* 注:ssh 方式每命令新 spawn(延迟高),连接复用需 ControlMaster 或持久 shell,
|
||||
* 但纯逻辑层只负责正确的命令拼接,连接池由扩展层管。
|
||||
*
|
||||
* @param board 目标板规格。
|
||||
* @param underlying 底层执行函数(宿主 spawn)。
|
||||
* @returns { exec, transport, isStub }。
|
||||
*/
|
||||
export function makeExec(board: BoardSpec, underlying: ExecFn): MakeExecResult {
|
||||
switch (board.link) {
|
||||
case "ssh": {
|
||||
const exec: ExecFn = (command, args, opts) => {
|
||||
return underlying("ssh", buildSshArgs(board, command, args), opts);
|
||||
};
|
||||
return { exec, transport: `ssh:${board.address}`, isStub: false };
|
||||
}
|
||||
case "serial": {
|
||||
const exec: ExecFn = async () => SERIAL_STUB_RESULT;
|
||||
const serial = parseSerialAddress(board.address);
|
||||
return { exec, transport: `serial:${serial.dev}@${serial.baudrate}`, isStub: true };
|
||||
}
|
||||
case "local": {
|
||||
return { exec: underlying, transport: "local", isStub: false };
|
||||
}
|
||||
default: {
|
||||
const exec: ExecFn = async (_command, _args, _opts) => ({
|
||||
stdout: "",
|
||||
stderr: `unknown board link type: ${String(board.link)}`,
|
||||
exitCode: 1,
|
||||
});
|
||||
return { exec, transport: `unknown:${String(board.link)}`, isStub: false };
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// healthCheck
|
||||
// ============================================================================
|
||||
|
||||
/** 健康检查选项。 */
|
||||
export interface HealthCheckOptions {
|
||||
/** 超时毫秒,默认 10000。 */
|
||||
timeout?: number;
|
||||
/** 自定义探活命令(默认 "true",exit 0 = alive)。 */
|
||||
probeCommand?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 健康检查:在板上跑探活命令(默认 `true`),exit 0 = alive。
|
||||
*
|
||||
* fail-closed:exec 抛异常或非 0 exit → false(板离线/不可达)。
|
||||
* 这与硬件验证判据的 failClosed 语义一致。
|
||||
*
|
||||
* @param board 目标板规格。
|
||||
* @param exec 该板的 ExecFn(由 makeExec 产出)。
|
||||
* @param opts 超时/自定义探活命令。
|
||||
* @returns true=板在线,false=板离线/不可达。
|
||||
*/
|
||||
export async function healthCheck(
|
||||
board: BoardSpec,
|
||||
exec: ExecFn,
|
||||
opts: HealthCheckOptions = {},
|
||||
): Promise<boolean> {
|
||||
const timeout = opts.timeout ?? 10_000;
|
||||
const probe = opts.probeCommand ?? "true";
|
||||
try {
|
||||
const result = await exec(probe, [], { timeout });
|
||||
return result.exitCode === 0;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// BoardRegistry
|
||||
// ============================================================================
|
||||
|
||||
/** register 结果。 */
|
||||
export interface RegisterResult {
|
||||
/** 是否注册成功。 */
|
||||
ok: boolean;
|
||||
/** 失败原因(fingerprint 冲突 / id 冲突)。 */
|
||||
error?: string;
|
||||
/** 冲突的已注册板 id(诊断用)。 */
|
||||
conflictId?: string;
|
||||
}
|
||||
|
||||
/** session JSONL 里的持久化条目结构(扩展层 pi.appendEntry / sessionManager.getEntries 用)。 */
|
||||
export interface RegistryEntry {
|
||||
customType: "boardlink:registry";
|
||||
data: BoardSpec;
|
||||
}
|
||||
|
||||
/**
|
||||
* 板注册表。fingerprint 去重:同 fingerprint(= 同一物理板)的板拒绝重复注册。
|
||||
*
|
||||
* 持久化:通过 toEntries() 导出 RegistryEntry[],扩展层 pi.appendEntry 落 session JSONL;
|
||||
* 重建:fromEntries() 扫 session entries 里的 customType:"boardlink:registry" 重建内存注册表。
|
||||
*/
|
||||
export class BoardRegistry {
|
||||
private boards = new Map<string, BoardSpec>();
|
||||
private fpIndex = new Map<string, string>(); // fingerprint → id
|
||||
|
||||
/**
|
||||
* 注册一块板。id 唯一 + fingerprint 唯一,冲突即拒绝。
|
||||
*
|
||||
* @param spec 板规格。
|
||||
* @returns 注册结果(ok=false 时带 error/conflictId)。
|
||||
*/
|
||||
register(spec: BoardSpec): RegisterResult {
|
||||
// id 冲突
|
||||
if (this.boards.has(spec.id)) {
|
||||
return {
|
||||
ok: false,
|
||||
error: `board id "${spec.id}" already registered`,
|
||||
conflictId: spec.id,
|
||||
};
|
||||
}
|
||||
// fingerprint 去重(同一物理板不可重复注册)
|
||||
const existId = this.fpIndex.get(spec.fingerprint);
|
||||
if (existId !== undefined) {
|
||||
return {
|
||||
ok: false,
|
||||
error: `fingerprint "${spec.fingerprint}" already registered as board "${existId}"`,
|
||||
conflictId: existId,
|
||||
};
|
||||
}
|
||||
this.boards.set(spec.id, spec);
|
||||
this.fpIndex.set(spec.fingerprint, spec.id);
|
||||
return { ok: true };
|
||||
}
|
||||
|
||||
/**
|
||||
* 注销一块板(按 id)。不存在返回 false。
|
||||
*
|
||||
* @param id 板 id。
|
||||
* @returns 是否注销成功。
|
||||
*/
|
||||
unregister(id: string): boolean {
|
||||
const spec = this.boards.get(id);
|
||||
if (!spec) return false;
|
||||
this.boards.delete(id);
|
||||
this.fpIndex.delete(spec.fingerprint);
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 按 id 查板。
|
||||
*
|
||||
* @param id 板 id。
|
||||
* @returns 板规格,不存在则 undefined。
|
||||
*/
|
||||
get(id: string): BoardSpec | undefined {
|
||||
return this.boards.get(id);
|
||||
}
|
||||
|
||||
/**
|
||||
* 按 fingerprint 查板。
|
||||
*
|
||||
* @param fingerprint 指纹(link:address)。
|
||||
* @returns 板规格,不存在则 undefined。
|
||||
*/
|
||||
getByFingerprint(fingerprint: string): BoardSpec | undefined {
|
||||
const id = this.fpIndex.get(fingerprint);
|
||||
if (id === undefined) return undefined;
|
||||
return this.boards.get(id);
|
||||
}
|
||||
|
||||
/**
|
||||
* 列出所有已注册板。
|
||||
*
|
||||
* @returns 板规格数组(按插入序)。
|
||||
*/
|
||||
list(): BoardSpec[] {
|
||||
return [...this.boards.values()];
|
||||
}
|
||||
|
||||
/** 已注册板数量。 */
|
||||
get size(): number {
|
||||
return this.boards.size;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从 session entries 重建注册表(扩展层 session_start reason:"resume" 调用)。
|
||||
*
|
||||
* @param entries session 条目数组。
|
||||
* @returns 重建后的 BoardRegistry。
|
||||
*/
|
||||
static fromEntries(entries: Array<{ customType?: string; data?: unknown }>): BoardRegistry {
|
||||
const reg = new BoardRegistry();
|
||||
for (const e of entries) {
|
||||
if (e.customType === "boardlink:registry" && e.data) {
|
||||
const spec = e.data as BoardSpec;
|
||||
if (spec && spec.id && spec.fingerprint) {
|
||||
reg.register(spec);
|
||||
}
|
||||
}
|
||||
}
|
||||
return reg;
|
||||
}
|
||||
|
||||
/**
|
||||
* 导出为可持久化条目(扩展层 pi.appendEntry 用)。
|
||||
*
|
||||
* @returns RegistryEntry 数组。
|
||||
*/
|
||||
toEntries(): RegistryEntry[] {
|
||||
return this.list().map((spec) => ({
|
||||
customType: "boardlink:registry" as const,
|
||||
data: spec,
|
||||
}));
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// fingerprint 计算(从 link+address 派生,便于调用方不手填)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 从 BoardSpec 的 link+address 派生 fingerprint(去重键)。
|
||||
* 同一物理板(相同 link+address)→ 相同 fingerprint → 拒绝重复注册。
|
||||
*
|
||||
* @param link 链路类型(ssh/serial/local)。
|
||||
* @param address 地址串。
|
||||
* @returns fingerprint 字符串。
|
||||
*/
|
||||
export function computeFingerprint(link: BoardLinkType, address: string): string {
|
||||
return `${link}:${address.trim()}`;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
// 单例板注册表(同进程跨 tool call 共享;纯逻辑,零 pi 依赖)
|
||||
const registry = new BoardRegistry();
|
||||
|
||||
/**
|
||||
* board-link 扩展装配。
|
||||
*
|
||||
* - 注册 4 个工具:board_connect / board_exec / board_scp / board_console
|
||||
* - session_start:从 session JSONL 重建注册表(resume/reload)
|
||||
* - tool_result:board_connect 注册成功时 appendEntry 持久化
|
||||
* - before_agent_start:注入已连接板信息到 system prompt
|
||||
* - events 总线:跨扩展 exec 代理 / health-check 委托
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*
|
||||
* @param pi 扩展 API。
|
||||
*/
|
||||
export default async function boardLinkExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
// ---- board_connect:注册/连接一块板 ----
|
||||
const boardConnectTool = defineTool({
|
||||
name: "board_connect",
|
||||
label: "Board Connect",
|
||||
description:
|
||||
"Register and connect to a target board. method=ssh opens an SSH link; method=serial opens a " +
|
||||
"serial console (stub in pure-logic mode — requires real PTY at runtime). The board is persisted " +
|
||||
"to the session registry for reuse across tool calls. Duplicate physical boards (same link+address) " +
|
||||
"are rejected.",
|
||||
promptSnippet: "Connect to a target board over SSH or serial",
|
||||
parameters: Type.Object({
|
||||
boardId: Type.String({ description: "Unique short id for this board, e.g. 'x5' or 's100'." }),
|
||||
name: Type.String({ description: "Human-readable board name." }),
|
||||
method: Type.Union(
|
||||
[Type.Literal("ssh"), Type.Literal("serial"), Type.Literal("local")],
|
||||
{ description: "Link transport: ssh, serial, or local (host is the target)." },
|
||||
),
|
||||
address: Type.Optional(
|
||||
Type.String({
|
||||
description:
|
||||
"ssh: user@host:port (e.g. root@192.168.1.100:22); serial: /dev/ttyUSB0@115200; local: ignored.",
|
||||
}),
|
||||
),
|
||||
}),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as {
|
||||
boardId: string;
|
||||
name: string;
|
||||
method: "ssh" | "serial" | "local";
|
||||
address?: string;
|
||||
};
|
||||
const link = p.method;
|
||||
const address = p.address ?? "";
|
||||
const fingerprint = computeFingerprint(link, address);
|
||||
const spec: BoardSpec = { id: p.boardId, name: p.name, link, address, fingerprint };
|
||||
|
||||
const result = registry.register(spec);
|
||||
if (!result.ok) {
|
||||
return {
|
||||
content: [{ type: "text" as const, text: `Board connect failed: ${result.error}` }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: `Board "${p.boardId}" (${p.name}) registered via ${link}:${address || "(local)"}.`,
|
||||
},
|
||||
],
|
||||
details: { boardId: p.boardId, link, address },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
// ---- board_exec:在已连接板上执行命令 ----
|
||||
const boardExecTool = defineTool({
|
||||
name: "board_exec",
|
||||
label: "Board Exec",
|
||||
description:
|
||||
"Execute a command on a connected board. SSH boards wrap the command in `ssh user@host <cmd>`. " +
|
||||
"Serial boards return a stub (serial transport requires a real PTY — use board_console for streaming). " +
|
||||
"Local boards execute directly on the host. executionMode=sequential prevents concurrent serial/JTAG clashes.",
|
||||
promptSnippet: "Run a command on a connected target board",
|
||||
parameters: Type.Object({
|
||||
boardId: Type.String({ description: "Board id registered via board_connect." }),
|
||||
command: Type.String({ description: "Command to execute on the board." }),
|
||||
args: Type.Optional(
|
||||
Type.Array(Type.String({ description: "Command arguments." }), {
|
||||
description: "Arguments for the command.",
|
||||
}),
|
||||
),
|
||||
timeout: Type.Optional(
|
||||
Type.Number({ description: "Timeout in ms. Default 30000." }),
|
||||
),
|
||||
}),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as { boardId: string; command: string; args?: string[]; timeout?: number };
|
||||
const board = registry.get(p.boardId);
|
||||
if (!board) {
|
||||
return {
|
||||
content: [{ type: "text" as const, text: `Board "${p.boardId}" not registered. Use board_connect first.` }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
const { exec, transport, isStub } = makeExec(board, (cmd, args, opts) =>
|
||||
pi.exec(cmd, args, { timeout: opts?.timeout, cwd: opts?.cwd, env: opts?.env }),
|
||||
);
|
||||
|
||||
if (isStub) {
|
||||
const r = await exec(p.command, p.args ?? [], { timeout: p.timeout ?? 30_000 });
|
||||
return {
|
||||
content: [{ type: "text" as const, text: r.stdout }],
|
||||
details: { transport, stub: true },
|
||||
};
|
||||
}
|
||||
|
||||
const timeout = p.timeout ?? 30_000;
|
||||
const r = await exec(p.command, p.args ?? [], { timeout });
|
||||
const text = r.stdout + (r.stderr ? `\n[stderr]\n${r.stderr}` : "");
|
||||
return {
|
||||
content: [{ type: "text" as const, text }],
|
||||
details: { transport, exitCode: r.exitCode },
|
||||
isError: r.exitCode !== 0,
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
// ---- board_scp:文件传输 ----
|
||||
const boardScpTool = defineTool({
|
||||
name: "board_scp",
|
||||
label: "Board SCP",
|
||||
description:
|
||||
"Transfer a file between host and board via scp (SSH boards only). " +
|
||||
"direction=upload: local→board; direction=download: board→local.",
|
||||
promptSnippet: "Transfer a file to/from a board via scp",
|
||||
parameters: Type.Object({
|
||||
boardId: Type.String({ description: "Board id (must be an SSH board)." }),
|
||||
localPath: Type.String({ description: "Path on the host machine." }),
|
||||
remotePath: Type.String({ description: "Path on the board." }),
|
||||
direction: Type.Union(
|
||||
[Type.Literal("upload"), Type.Literal("download")],
|
||||
{ description: "upload = host→board; download = board→host." },
|
||||
),
|
||||
}),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as {
|
||||
boardId: string;
|
||||
localPath: string;
|
||||
remotePath: string;
|
||||
direction: "upload" | "download";
|
||||
};
|
||||
const board = registry.get(p.boardId);
|
||||
if (!board || board.link !== "ssh") {
|
||||
return {
|
||||
content: [{ type: "text" as const, text: `Board "${p.boardId}" not found or not an SSH board.` }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
// 复用 board.address (user@host:port) 拼 remote:path
|
||||
const remote = board.address.replace(/:\d+$/, "");
|
||||
const src = p.direction === "upload" ? p.localPath : `${remote}:${p.remotePath}`;
|
||||
const dst = p.direction === "upload" ? `${remote}:${p.remotePath}` : p.localPath;
|
||||
|
||||
const r = await pi.exec("scp", [src, dst], { timeout: 120_000 });
|
||||
return {
|
||||
content: [{ type: "text" as const, text: r.stdout + (r.stderr ? `\n${r.stderr}` : "") }],
|
||||
details: { direction: p.direction, exitCode: r.exitCode },
|
||||
isError: r.exitCode !== 0,
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
// ---- board_console:串口 console 流捕获 ----
|
||||
const boardConsoleTool = defineTool({
|
||||
name: "board_console",
|
||||
label: "Board Console",
|
||||
description:
|
||||
"Capture serial console output for a duration (default 30s). Streams output via onUpdate. " +
|
||||
"Requires a serial board. In pure-logic mode returns a stub.",
|
||||
promptSnippet: "Capture serial console output from a board",
|
||||
parameters: Type.Object({
|
||||
boardId: Type.String({ description: "Board id (must be a serial board)." }),
|
||||
duration: Type.Optional(
|
||||
Type.Number({ description: "Capture duration in seconds. Default 30." }),
|
||||
),
|
||||
}),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, signal, onUpdate, _ctx) {
|
||||
const p = params as { boardId: string; duration?: number };
|
||||
const board = registry.get(p.boardId);
|
||||
if (!board || board.link !== "serial") {
|
||||
return {
|
||||
content: [{ type: "text" as const, text: `Board "${p.boardId}" not found or not a serial board.` }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
const duration = p.duration ?? 30;
|
||||
// 纯逻辑 stub:真实运行时扩展层接 picocom/cat serialDev,stdout pipe 到 onUpdate。
|
||||
// signal abort 终止流。
|
||||
const stubText = `[board_console stub] serial=${board.address} duration=${duration}s — real PTY required at runtime.`;
|
||||
onUpdate?.({ content: [{ type: "text" as const, text: stubText }] });
|
||||
return {
|
||||
content: [{ type: "text" as const, text: stubText }],
|
||||
details: { duration, stub: true },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
// ---- 注册 4 个工具 ----
|
||||
pi.registerTool(boardConnectTool);
|
||||
pi.registerTool(boardExecTool);
|
||||
pi.registerTool(boardScpTool);
|
||||
pi.registerTool(boardConsoleTool);
|
||||
|
||||
// ---- session_start:从 session JSONL 重建注册表 ----
|
||||
pi.on("session_start", (_event, _ctx: ExtensionContext) => {
|
||||
const event = _event as { reason?: string };
|
||||
if (event.reason === "resume" || event.reason === "reload") {
|
||||
const ctx = _ctx;
|
||||
const entries = ctx.sessionManager.getEntries();
|
||||
const rebuilt = BoardRegistry.fromEntries(entries);
|
||||
// 合并:把重建的板灌入单例(冲突的跳过)
|
||||
for (const spec of rebuilt.list()) {
|
||||
registry.register(spec);
|
||||
}
|
||||
pi.appendEntry("boardlink:registry-rebuilt", { count: rebuilt.size });
|
||||
}
|
||||
});
|
||||
|
||||
// ---- board_connect 注册成功时持久化 ----
|
||||
pi.on("tool_result", (event) => {
|
||||
if (event.toolName !== "board_connect") return undefined;
|
||||
const input = event.input as { boardId?: string; method?: string; address?: string; name?: string };
|
||||
if (event.isError) return undefined;
|
||||
// 从 registry 拿刚注册的 spec,appendEntry 持久化
|
||||
const spec = input.boardId ? registry.get(input.boardId) : undefined;
|
||||
if (spec) {
|
||||
pi.appendEntry("boardlink:registry", spec);
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- before_agent_start:注入板信息到 system prompt ----
|
||||
pi.on("before_agent_start", (_event, _ctx: ExtensionContext) => {
|
||||
const boards = registry.list();
|
||||
if (boards.length === 0) return undefined;
|
||||
|
||||
const lines = boards.map((b) => {
|
||||
const parts = [`- board "${b.id}" (${b.name}): ${b.link}`];
|
||||
if (b.address) parts.push(`@ ${b.address}`);
|
||||
return parts.join(" ");
|
||||
});
|
||||
const prompt =
|
||||
`\n\n[board-link] Connected target boards:\n${lines.join("\n")}\n` +
|
||||
`Use board_exec to run commands on these boards. SSH boards wrap commands in ssh.`;
|
||||
|
||||
return { systemPrompt: prompt };
|
||||
});
|
||||
|
||||
// ---- 跨扩展通信:广播连接事件(持久 shell 监听获取句柄 / 环境探针订阅注册表更新) ----
|
||||
pi.events.on("boardlink:request-exec", (data) => {
|
||||
const d = data as { boardId?: string; command?: string; args?: string[] };
|
||||
if (!d.boardId || !d.command) return;
|
||||
const board = registry.get(d.boardId);
|
||||
if (!board) {
|
||||
pi.events.emit("boardlink:exec-result", { boardId: d.boardId, error: "board not found" });
|
||||
return;
|
||||
}
|
||||
const { exec } = makeExec(board, (cmd, args, opts) =>
|
||||
pi.exec(cmd, args, { timeout: opts?.timeout, cwd: opts?.cwd, env: opts?.env }),
|
||||
);
|
||||
exec(d.command, d.args ?? [], { timeout: 30_000 })
|
||||
.then((r) => pi.events.emit("boardlink:exec-result", { boardId: d.boardId, result: r }))
|
||||
.catch((e) => pi.events.emit("boardlink:exec-result", { boardId: d.boardId, error: String(e) }));
|
||||
});
|
||||
|
||||
// ---- 健康检查事件(硬件验证扩展委托) ----
|
||||
pi.events.on("boardlink:health-check", (data) => {
|
||||
const d = data as { boardId?: string };
|
||||
if (!d.boardId) return;
|
||||
const board = registry.get(d.boardId);
|
||||
if (!board) {
|
||||
pi.events.emit("boardlink:health-result", { boardId: d.boardId, alive: false, error: "not found" });
|
||||
return;
|
||||
}
|
||||
const { exec } = makeExec(board, (cmd, args, opts) =>
|
||||
pi.exec(cmd, args, { timeout: opts?.timeout, cwd: opts?.cwd, env: opts?.env }),
|
||||
);
|
||||
healthCheck(board, exec)
|
||||
.then((alive) => pi.events.emit("boardlink:health-result", { boardId: d.boardId, alive }))
|
||||
.catch(() => pi.events.emit("boardlink:health-result", { boardId: d.boardId, alive: false }));
|
||||
});
|
||||
}
|
||||
714
src/extensions/build-tracker.ts
Normal file
714
src/extensions/build-tracker.ts
Normal file
@ -0,0 +1,714 @@
|
||||
/**
|
||||
* @module build-tracker
|
||||
*
|
||||
* 构建系统封装与长任务跟踪扩展 —— 治嵌入式开发场景下构建系统级缺陷:
|
||||
* 长任务阻塞 agent、无增量感知盲重建、构建状态不落 session。
|
||||
*
|
||||
* 场景锚定:嵌入式镜像构建(buildroot `make` / Yocto `bitbake` / CMake /
|
||||
* Makefile / 内核 Kconfig `make defconfig`)一次几十分钟到几小时,agent 不能
|
||||
* 频繁全量重建试错。本扩展把构建进程做成真后台(detached + unref),
|
||||
* agent 发完 `build` 立即拿 buildId 返回不阻塞,用 `build_status` 轮询进度 +
|
||||
* tail 日志;增量构建感知(源码 mtime vs 上次构建 mtime)跳过无变更重建;
|
||||
* 构建完成 emit build:done 事件 + appendEntry 落 session 供 resume 重建。
|
||||
*
|
||||
* 逻辑全内联为命名导出(BuildTracker / OutputAccumulator / planBuild /
|
||||
* shouldSkip),tests 直接单测,无需 pi 运行时、无需真实硬件。
|
||||
* defineTool / Type / spawn 适配仅在工厂体内动态解析,顶层只 import type。
|
||||
*
|
||||
* 见 Docs/F21_构建系统封装与长任务跟踪.md。fail-closed 语义贯穿:无上次构建
|
||||
* 记录、源码 mtime 未知、未知 buildId → 一律不跳过 / 返回 null。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
|
||||
// 注:defineTool / Type 仅在 factory 内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时 factory 不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// 类型契约
|
||||
// ============================================================================
|
||||
|
||||
/** 支持的构建系统。 */
|
||||
export type BuildSystem = "buildroot" | "yocto" | "cmake" | "make" | "kconfig";
|
||||
|
||||
/** 构建生命周期状态。 */
|
||||
export type BuildStatus = "running" | "done" | "failed";
|
||||
|
||||
/**
|
||||
* 注入的进程句柄——逻辑层只认此接口,扩展层用 child_process.ChildProcess 适配,
|
||||
* 测试用 FakeSpawnedProcess 注入。绝不 spawn 真实进程。
|
||||
*/
|
||||
export interface SpawnedProcess {
|
||||
pid: number;
|
||||
onStdout(handler: (data: string) => void): void;
|
||||
onStderr(handler: (data: string) => void): void;
|
||||
/** 进程结束(code=null 表示被信号杀掉)。 */
|
||||
onClose(handler: (code: number | null, signal?: string) => void): void;
|
||||
kill?(): void;
|
||||
}
|
||||
|
||||
/** 可注入的 spawn 签名。 */
|
||||
export type SpawnFn = (
|
||||
command: string,
|
||||
args: string[],
|
||||
opts?: { cwd?: string; env?: Record<string, string> },
|
||||
) => SpawnedProcess;
|
||||
|
||||
/** 构建启动选项。 */
|
||||
export interface BuildStartOptions {
|
||||
/** 增量感知,默认 true。 */
|
||||
incremental?: boolean;
|
||||
/** 清理重建,默认 false。clean 模式绝不跳过。 */
|
||||
clean?: boolean;
|
||||
/** 构建目录(增量判定读源码 mtime 用)。 */
|
||||
buildDir?: string;
|
||||
}
|
||||
|
||||
/** 构建启动返回。 */
|
||||
export interface BuildStartResult {
|
||||
buildId: string;
|
||||
pid: number;
|
||||
logFile: string;
|
||||
status: BuildStatus;
|
||||
/** 增量跳过时 true(未 spawn 进程)。 */
|
||||
skipped?: boolean;
|
||||
/** 跳过原因。 */
|
||||
skipReason?: string;
|
||||
}
|
||||
|
||||
/** 构建状态查询返回。 */
|
||||
export interface BuildStatusResult {
|
||||
buildId: string;
|
||||
status: BuildStatus;
|
||||
exitCode?: number;
|
||||
signal?: string;
|
||||
/** 运行时长(毫秒)。 */
|
||||
durationMs?: number;
|
||||
}
|
||||
|
||||
/** 构建命令规划(planBuild 产出)。 */
|
||||
export interface BuildCommandPlan {
|
||||
command: string;
|
||||
args: string[];
|
||||
cwd?: string;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 构建命令规划(planBuild)—— 纯函数
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 按构建系统类型规划命令。纯函数,可单测。
|
||||
*
|
||||
* - buildroot: `make <target|all>`
|
||||
* - yocto: `bitbake <target|core-image-minimal>`
|
||||
* - cmake: `cmake --build . --target <target|all>`
|
||||
* - make: `make <target|all>`
|
||||
* - kconfig: `make <target|defconfig>`(内核 Kconfig)
|
||||
*
|
||||
* clean:true 时返回的 plan 不含清理步骤——清理由调用方在 spawn 前执行,
|
||||
* plan 只管构建命令本身,保持纯函数。
|
||||
*
|
||||
* @param project 构建系统名(buildroot/yocto/cmake/make/kconfig)。
|
||||
* @param target 构建目标(defconfig / image / all / core-image-minimal)。
|
||||
* @param opts.buildDir 构建目录,透传为 cwd。
|
||||
* @returns 命令 + 参数 + cwd。
|
||||
*/
|
||||
export function planBuild(
|
||||
project: string,
|
||||
target?: string,
|
||||
opts?: { buildDir?: string },
|
||||
): BuildCommandPlan {
|
||||
const cwd = opts?.buildDir;
|
||||
const sys = (project || "").toLowerCase() as BuildSystem;
|
||||
switch (sys) {
|
||||
case "buildroot":
|
||||
return { command: "make", args: [target ?? "all"], cwd };
|
||||
case "yocto":
|
||||
return { command: "bitbake", args: [target ?? "core-image-minimal"], cwd };
|
||||
case "cmake":
|
||||
return {
|
||||
command: "cmake",
|
||||
args: ["--build", ".", "--target", target ?? "all"],
|
||||
cwd,
|
||||
};
|
||||
case "make":
|
||||
return { command: "make", args: [target ?? "all"], cwd };
|
||||
case "kconfig":
|
||||
return { command: "make", args: [target ?? "defconfig"], cwd };
|
||||
default:
|
||||
// 未知系统:按 make 兜底(fail-open,但扩展层可拦截)。
|
||||
return { command: "make", args: [target ?? "all"], cwd };
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 增量构建感知(shouldSkip)—— fail-closed
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 判断是否可跳过本次构建。
|
||||
*
|
||||
* 规则(Docs §3 增量构建感知):
|
||||
* - 无上次构建(lastBuildMtime<=0)→ 不跳过(fail-closed,必须首次构建)。
|
||||
* - 源码 mtime > 上次构建 mtime(源码变了)→ 不跳过,必须重建。
|
||||
* - 源码 mtime <= 上次构建 mtime(源码未变)→ 跳过。
|
||||
*
|
||||
* 注意:clean:true 时调用方应在调本函数前已决定不跳过(本函数不感知 clean)。
|
||||
*
|
||||
* @param srcMtime 源码最新修改时间戳。
|
||||
* @param lastBuildMtime 上次成功构建时间戳。
|
||||
* @returns true=可跳过,false=必须构建(fail-closed)。
|
||||
*/
|
||||
export function shouldSkip(srcMtime: number, lastBuildMtime: number): boolean {
|
||||
// fail-closed:无上次构建记录 → 必须构建。
|
||||
if (!lastBuildMtime || lastBuildMtime <= 0) return false;
|
||||
// 源码在上次构建后被修改 → 必须重建。
|
||||
if (srcMtime > lastBuildMtime) return false;
|
||||
// 源码未变 → 可跳过。
|
||||
return true;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// OutputAccumulator —— 有界内存缓冲 + temp path
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 有界内存缓冲 + temp file 路径。参考 pi output-accumulator.ts:35 简化版。
|
||||
*
|
||||
* append 按换行切分累积;tail 返回尾部 N 行。tempPath 仅供扩展层落盘用,
|
||||
* 逻辑层只管内存数组(测试无文件 IO)。跨 chunk 半行残片自动拼接。
|
||||
*/
|
||||
export class OutputAccumulator {
|
||||
readonly tempPath: string;
|
||||
private lines: string[] = [];
|
||||
/** 未结行尾的残片(跨 data chunk 的半行)。 */
|
||||
private tail_: string = "";
|
||||
|
||||
constructor(tempPath: string) {
|
||||
this.tempPath = tempPath;
|
||||
}
|
||||
|
||||
/** 追加一段输出(可能含多行/半行)。 */
|
||||
append(data: string): void {
|
||||
if (!data) return;
|
||||
// 与残片拼接后按 \n 切分。
|
||||
const combined = this.tail_ + data;
|
||||
const parts = combined.split("\n");
|
||||
// 最后一段若非空则为残片(无尾随换行)。
|
||||
this.tail_ = parts.pop() ?? "";
|
||||
for (const line of parts) {
|
||||
this.lines.push(line);
|
||||
}
|
||||
}
|
||||
|
||||
/** 显式追加一整行(带换行语义)。 */
|
||||
appendLine(line: string): void {
|
||||
// 先把残片结掉成一行。
|
||||
if (this.tail_) {
|
||||
this.lines.push(this.tail_);
|
||||
this.tail_ = "";
|
||||
}
|
||||
this.lines.push(line);
|
||||
}
|
||||
|
||||
/** 返回尾部 N 行(不含残片)。 */
|
||||
tail(n: number): string[] {
|
||||
if (n <= 0) return [];
|
||||
return this.lines.slice(-n);
|
||||
}
|
||||
|
||||
/** 已结行总数。 */
|
||||
get lineCount(): number {
|
||||
return this.lines.length;
|
||||
}
|
||||
|
||||
/** 全部已结行(测试/扩展层读全文用)。 */
|
||||
allLines(): string[] {
|
||||
return [...this.lines];
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// BuildTracker —— 后台构建进程跟踪
|
||||
// ============================================================================
|
||||
|
||||
/** 内部构建记录(不导出)。 */
|
||||
interface BuildRecord {
|
||||
buildId: string;
|
||||
project: string;
|
||||
target?: string;
|
||||
pid: number;
|
||||
status: BuildStatus;
|
||||
exitCode?: number;
|
||||
signal?: string;
|
||||
startedAt: number;
|
||||
endedAt?: number;
|
||||
accumulator: OutputAccumulator;
|
||||
}
|
||||
|
||||
/** BuildTracker 构造选项。 */
|
||||
export interface BuildTrackerOptions {
|
||||
/** temp 日志目录,默认 /tmp。仅用于拼 logFile 路径,不落盘。 */
|
||||
tempDir?: string;
|
||||
/** 注入时钟(测试 mock),默认 Date.now。 */
|
||||
clock?: () => number;
|
||||
/** buildId 前缀。 */
|
||||
idPrefix?: string;
|
||||
/**
|
||||
* 注入源码 mtime 探测(测试 mock / 扩展层用 pi.exec stat)。
|
||||
* 默认返回 0(未知 → fail-closed 不跳过)。
|
||||
*/
|
||||
getSrcMtime?: (buildDir: string) => number;
|
||||
/**
|
||||
* 注入上次成功构建 mtime 探测(测试 mock / 扩展层从 session entries 重建)。
|
||||
* 默认返回 0(无历史 → fail-closed 不跳过)。
|
||||
*/
|
||||
getLastBuildMtime?: (project: string, target?: string) => number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 长任务构建跟踪器。注入 SpawnFn(mock),绝不 spawn 真实进程。
|
||||
*
|
||||
* 生命周期:
|
||||
* - start(project,target) → spawn 进程,返回 buildId+pid+logFile+status:"running"。
|
||||
* 若 incremental 且 shouldSkip 命中 → 不 spawn,返回 skipped:true。
|
||||
* - 进程 stdout/stderr → accumulator.append(流式累积)。
|
||||
* - 进程 close → 记录 exitCode/signal,status=done(code==0)|failed。
|
||||
* - status(buildId) → 查当前状态。
|
||||
* - tail(buildId,n) → 尾部 N 行日志。
|
||||
*
|
||||
* fail-closed:无 buildDir 无法判定源码 mtime → 不跳过;未知 buildId → status 返回 null、tail 返回空数组。
|
||||
*/
|
||||
export class BuildTracker {
|
||||
private builds = new Map<string, BuildRecord>();
|
||||
private counter = 0;
|
||||
private readonly spawnFn: SpawnFn;
|
||||
private readonly tempDir: string;
|
||||
private readonly clock: () => number;
|
||||
private readonly idPrefix: string;
|
||||
private readonly getSrcMtime: (buildDir: string) => number;
|
||||
private readonly getLastBuildMtime: (project: string, target?: string) => number;
|
||||
|
||||
constructor(spawnFn: SpawnFn, opts: BuildTrackerOptions = {}) {
|
||||
this.spawnFn = spawnFn;
|
||||
this.tempDir = opts.tempDir ?? "/tmp";
|
||||
this.clock = opts.clock ?? (() => Date.now());
|
||||
this.idPrefix = opts.idPrefix ?? "build";
|
||||
this.getSrcMtime = opts.getSrcMtime ?? (() => 0);
|
||||
this.getLastBuildMtime = opts.getLastBuildMtime ?? (() => 0);
|
||||
}
|
||||
|
||||
/**
|
||||
* 发起构建。立即返回 buildId+pid,不阻塞(真后台范式,见 Docs §2 替代解法)。
|
||||
*
|
||||
* @param project 构建系统名。
|
||||
* @param target 构建目标。
|
||||
* @param opts.incremental 增量感知(默认 true)。
|
||||
* @param opts.clean 清理重建(默认 false,clean 绝不跳过)。
|
||||
* @param opts.buildDir 构建目录。
|
||||
* @returns 启动结果(running 或 skipped:done)。
|
||||
*/
|
||||
start(project: string, target?: string, opts: BuildStartOptions = {}): BuildStartResult {
|
||||
const incremental = opts.incremental ?? true;
|
||||
const clean = opts.clean ?? false;
|
||||
|
||||
// 增量跳过决策:clean 模式绝不跳过。无 buildDir 无法判定源码 mtime → fail-closed 不跳过。
|
||||
if (incremental && !clean && opts.buildDir) {
|
||||
const srcMtime = this.getSrcMtime(opts.buildDir);
|
||||
// 源码 mtime 未知(0/负)→ fail-closed 不跳过。
|
||||
if (srcMtime > 0) {
|
||||
const lastBuildMtime = this.getLastBuildMtime(project, target);
|
||||
if (shouldSkip(srcMtime, lastBuildMtime)) {
|
||||
// 记录一条 skipped 构建以便 status 查询。
|
||||
const buildId = this.nextBuildId();
|
||||
return {
|
||||
buildId,
|
||||
pid: 0,
|
||||
logFile: "",
|
||||
status: "done",
|
||||
skipped: true,
|
||||
skipReason: "No source changes, skipping build",
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const plan = planBuild(project, target, { buildDir: opts.buildDir });
|
||||
const buildId = this.nextBuildId();
|
||||
const logFile = `${this.tempDir}/${buildId}.log`;
|
||||
const accumulator = new OutputAccumulator(logFile);
|
||||
const startedAt = this.clock();
|
||||
|
||||
// spawn(注入的 mock;逻辑层绝不碰真实 child_process)。
|
||||
const proc = this.spawnFn(plan.command, plan.args, { cwd: plan.cwd });
|
||||
|
||||
const record: BuildRecord = {
|
||||
buildId,
|
||||
project,
|
||||
target,
|
||||
pid: proc.pid,
|
||||
status: "running",
|
||||
startedAt,
|
||||
accumulator,
|
||||
};
|
||||
this.builds.set(buildId, record);
|
||||
|
||||
proc.onStdout((data) => accumulator.append(data));
|
||||
proc.onStderr((data) => accumulator.append(data));
|
||||
proc.onClose((code, signal) => {
|
||||
record.endedAt = this.clock();
|
||||
record.exitCode = code ?? -1;
|
||||
record.signal = signal;
|
||||
record.status = code === 0 ? "done" : "failed";
|
||||
});
|
||||
|
||||
return {
|
||||
buildId,
|
||||
pid: proc.pid,
|
||||
logFile,
|
||||
status: "running",
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询构建状态。未知 buildId 返回 null(fail-closed)。
|
||||
*
|
||||
* @param buildId 构建 id。
|
||||
* @returns 状态结果或 null。
|
||||
*/
|
||||
status(buildId: string): BuildStatusResult | null {
|
||||
const rec = this.builds.get(buildId);
|
||||
if (!rec) return null;
|
||||
return {
|
||||
buildId,
|
||||
status: rec.status,
|
||||
exitCode: rec.exitCode,
|
||||
signal: rec.signal,
|
||||
durationMs:
|
||||
rec.endedAt !== undefined ? rec.endedAt - rec.startedAt : this.clock() - rec.startedAt,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 返回尾部 N 行日志(默认 50)。未知 buildId 返回空数组。
|
||||
*
|
||||
* @param buildId 构建 id。
|
||||
* @param n 尾部行数,默认 50。
|
||||
* @returns 日志行数组。
|
||||
*/
|
||||
tail(buildId: string, n = 50): string[] {
|
||||
const rec = this.builds.get(buildId);
|
||||
if (!rec) return [];
|
||||
return rec.accumulator.tail(n);
|
||||
}
|
||||
|
||||
/**
|
||||
* 取某构建的 OutputAccumulator(扩展层落盘用)。
|
||||
*
|
||||
* @param buildId 构建 id。
|
||||
* @returns 累积器或 null。
|
||||
*/
|
||||
accumulatorOf(buildId: string): OutputAccumulator | null {
|
||||
return this.builds.get(buildId)?.accumulator ?? null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 所有已知 buildId(session resume 重建/审计用)。
|
||||
*
|
||||
* @returns buildId 数组。
|
||||
*/
|
||||
listBuilds(): string[] {
|
||||
return [...this.builds.keys()];
|
||||
}
|
||||
|
||||
// ---- 内部辅助 ----
|
||||
|
||||
private nextBuildId(): string {
|
||||
this.counter += 1;
|
||||
return `${this.idPrefix}-${this.counter}`;
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type + node:child_process)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* build-tracker 扩展装配。
|
||||
*
|
||||
* - 注册 `build` 工具:后台 spawn 进程,立即返回 buildId+pid 不阻塞 agent。
|
||||
* - 注册 `build_status` 工具:轮询构建进度 + tail 日志,wait:true 阻塞至完成。
|
||||
* - 进程 close → tracker 内部记录 exitCode/signal,build_status 查询时
|
||||
* 附带 emit build:done 事件 + appendEntry 落 session(供 resume 重建 / F20 闭环)。
|
||||
* - session_start:扫描历史 entries 重建已知 buildId(孤儿进程检测入口)。
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
* node:child_process 的 spawn 在函数内动态 import,避免顶层加载非必要模块。
|
||||
*
|
||||
* @param pi 扩展 API(由 pi 运行时注入)。
|
||||
* @returns Promise<void>。
|
||||
*/
|
||||
export default async function buildTrackerExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
const { spawn } = await import("node:child_process");
|
||||
|
||||
/**
|
||||
* 把 node child_process 适配成逻辑层要的 SpawnedProcess。
|
||||
* detached + unref → agent session 结束后构建进程继续跑(Docs §6 真后台)。
|
||||
*/
|
||||
function adaptChildProcess(child: {
|
||||
pid?: number | null | undefined;
|
||||
stdout: { on(event: "data", handler: (chunk: Buffer) => void): void } | null;
|
||||
stderr: { on(event: "data", handler: (chunk: Buffer) => void): void } | null;
|
||||
on(event: "close", handler: (code: number | null, signal: NodeJS.Signals | null) => void): void;
|
||||
unref(): void;
|
||||
}): SpawnedProcess {
|
||||
const pid = child.pid ?? -1;
|
||||
const stdoutHandlers: Array<(data: string) => void> = [];
|
||||
const stderrHandlers: Array<(data: string) => void> = [];
|
||||
const closeHandlers: Array<(code: number | null, signal?: string) => void> = [];
|
||||
|
||||
if (child.stdout) {
|
||||
child.stdout.on("data", (chunk: Buffer) => {
|
||||
const s = chunk.toString();
|
||||
for (const h of stdoutHandlers) h(s);
|
||||
});
|
||||
}
|
||||
if (child.stderr) {
|
||||
child.stderr.on("data", (chunk: Buffer) => {
|
||||
const s = chunk.toString();
|
||||
for (const h of stderrHandlers) h(s);
|
||||
});
|
||||
}
|
||||
child.on("close", (code, signal) => {
|
||||
for (const h of closeHandlers) h(code, signal ?? undefined);
|
||||
});
|
||||
|
||||
return {
|
||||
pid,
|
||||
onStdout(h) {
|
||||
stdoutHandlers.push(h);
|
||||
},
|
||||
onStderr(h) {
|
||||
stderrHandlers.push(h);
|
||||
},
|
||||
onClose(h) {
|
||||
closeHandlers.push(h);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** 注入给 BuildTracker 的 spawnFn:真实 child_process.spawn。 */
|
||||
function realSpawnFn(
|
||||
command: string,
|
||||
args: string[],
|
||||
opts?: { cwd?: string; env?: Record<string, string> },
|
||||
): SpawnedProcess {
|
||||
const child = spawn(command, args, {
|
||||
cwd: opts?.cwd,
|
||||
env: opts?.env ?? process.env,
|
||||
stdio: ["ignore", "pipe", "pipe"],
|
||||
detached: true,
|
||||
});
|
||||
// unref:解除事件循环跟踪,agent 进程退出不杀构建进程(Docs §6)。
|
||||
child.unref();
|
||||
return adaptChildProcess(child);
|
||||
}
|
||||
|
||||
const tracker = new BuildTracker(realSpawnFn, {
|
||||
tempDir: process.env.PI_BUILD_TEMP ?? "/tmp",
|
||||
idPrefix: "build",
|
||||
});
|
||||
|
||||
// ---- build 工具 ----
|
||||
const buildTool = defineTool({
|
||||
name: "build",
|
||||
label: "Build",
|
||||
description:
|
||||
"Start a long-running build (buildroot/yocto/cmake/make/kconfig) in the background. " +
|
||||
"Returns immediately with a buildId + pid + logFile — the agent is NOT blocked. " +
|
||||
"Use `build_status` to poll progress and tail logs. Incremental by default.",
|
||||
promptSnippet: "Start a build (buildroot/yocto/cmake) and stream logs back",
|
||||
promptGuidelines: [
|
||||
"Use the `build` tool for long-running builds instead of bash. Build runs in background and streams logs.",
|
||||
"Poll `build_status` for progress; do not block on `build`.",
|
||||
],
|
||||
parameters: Type.Object(
|
||||
{
|
||||
project: Type.String({ description: "build system: buildroot | yocto | cmake | make | kconfig" }),
|
||||
target: Type.Optional(Type.String({ description: "build target (defconfig / image / all / core-image-minimal)" })),
|
||||
incremental: Type.Optional(Type.Boolean({ description: "skip if no source changes (default true)" })),
|
||||
clean: Type.Optional(Type.Boolean({ description: "clean rebuild (default false)" })),
|
||||
buildDir: Type.Optional(Type.String({ description: "build directory" })),
|
||||
} as Record<string, unknown>,
|
||||
{ description: "Build start options." },
|
||||
),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, ctx) {
|
||||
const p = params as {
|
||||
project: BuildSystem;
|
||||
target?: string;
|
||||
incremental?: boolean;
|
||||
clean?: boolean;
|
||||
buildDir?: string;
|
||||
};
|
||||
const res = tracker.start(p.project, p.target, {
|
||||
incremental: p.incremental,
|
||||
clean: p.clean,
|
||||
buildDir: p.buildDir,
|
||||
});
|
||||
|
||||
// 落 session(Docs §6 构建状态落 session)
|
||||
pi.appendEntry("build:status", {
|
||||
buildId: res.buildId,
|
||||
project: p.project,
|
||||
target: p.target,
|
||||
pid: res.pid,
|
||||
logFile: res.logFile,
|
||||
skipped: res.skipped ?? false,
|
||||
phase: res.skipped ? "skipped" : "running",
|
||||
});
|
||||
|
||||
if (res.skipped) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify(res, null, 2),
|
||||
},
|
||||
],
|
||||
details: { skipped: true, buildId: res.buildId },
|
||||
};
|
||||
}
|
||||
|
||||
// 后台监听 close → emit build:done + 落 result(闭环依赖)。
|
||||
// start 返回时 close handler 已注册在 tracker 内部;这里仅登记一条 running 记录,
|
||||
// 完成事件由 build_status 轮询时附带上报。
|
||||
void ctx; // ctx reserved for future UI notify
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify(
|
||||
{
|
||||
buildId: res.buildId,
|
||||
pid: res.pid,
|
||||
logFile: res.logFile,
|
||||
status: res.status,
|
||||
note: "Build started in background. Poll with `build_status`.",
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
},
|
||||
],
|
||||
details: { buildId: res.buildId, pid: res.pid },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
// ---- build_status 工具 ----
|
||||
const buildStatusTool = defineTool({
|
||||
name: "build_status",
|
||||
label: "Build Status",
|
||||
description:
|
||||
"Query build progress by buildId. Returns status (running/done/failed), exitCode, " +
|
||||
"and the tail of the build log. If wait:true, blocks until the build completes.",
|
||||
promptSnippet: "Poll build progress and tail logs by buildId",
|
||||
parameters: Type.Object(
|
||||
{
|
||||
buildId: Type.String({ description: "build id returned by `build`" }),
|
||||
tail: Type.Optional(Type.Number({ description: "number of trailing log lines (default 50)" })),
|
||||
wait: Type.Optional(Type.Boolean({ description: "block until build completes (default false)" })),
|
||||
} as Record<string, unknown>,
|
||||
{ description: "Build status query." },
|
||||
),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, signal, _onUpdate, _ctx) {
|
||||
const p = params as { buildId: string; tail?: number; wait?: boolean };
|
||||
const n = p.tail ?? 50;
|
||||
|
||||
// wait:true → 轮询直到结束(被 signal 取消时退出)。
|
||||
if (p.wait) {
|
||||
const deadline = Date.now() + 3_600_000; // 1h cap
|
||||
while (Date.now() < deadline) {
|
||||
if (signal?.aborted) break;
|
||||
const st = tracker.status(p.buildId);
|
||||
if (!st) break;
|
||||
if (st.status !== "running") break;
|
||||
await new Promise((r) => setTimeout(r, 500));
|
||||
}
|
||||
}
|
||||
|
||||
const st = tracker.status(p.buildId);
|
||||
if (!st) {
|
||||
return {
|
||||
content: [{ type: "text", text: `unknown buildId: ${p.buildId}` }],
|
||||
isError: true,
|
||||
details: { buildId: p.buildId, unknown: true },
|
||||
};
|
||||
}
|
||||
const tailLines = tracker.tail(p.buildId, n);
|
||||
|
||||
// 构建完成时补发事件 + 落 result(Docs §6)。
|
||||
if (st.status !== "running") {
|
||||
pi.events.emit("build:done", {
|
||||
buildId: st.buildId,
|
||||
exitCode: st.exitCode,
|
||||
status: st.status,
|
||||
});
|
||||
pi.appendEntry("build:result", {
|
||||
buildId: st.buildId,
|
||||
status: st.status,
|
||||
exitCode: st.exitCode,
|
||||
signal: st.signal,
|
||||
durationMs: st.durationMs,
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify(
|
||||
{
|
||||
buildId: st.buildId,
|
||||
status: st.status,
|
||||
exitCode: st.exitCode,
|
||||
signal: st.signal,
|
||||
durationMs: st.durationMs,
|
||||
tail: tailLines.join("\n"),
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
},
|
||||
],
|
||||
details: { buildId: st.buildId, status: st.status },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(buildTool);
|
||||
pi.registerTool(buildStatusTool);
|
||||
|
||||
// ---- session_start:从历史 entries 重建已知 buildId(孤儿进程检测入口) ----
|
||||
pi.on("session_start", (_event, ctx: ExtensionContext) => {
|
||||
// 扫描 build:status entries 重建追踪表——简化:只通知 agent 历史构建存在。
|
||||
const entries = ctx.sessionManager?.getEntries?.() ?? [];
|
||||
const buildEntries = entries.filter((e) => e.customType === "build:status");
|
||||
if (buildEntries.length > 0) {
|
||||
pi.appendEntry("build:resumed", {
|
||||
count: buildEntries.length,
|
||||
note: "Previous build records found in session. Use build_status to check orphans.",
|
||||
});
|
||||
}
|
||||
});
|
||||
}
|
||||
856
src/extensions/cross-compile.ts
Normal file
856
src/extensions/cross-compile.ts
Normal file
@ -0,0 +1,856 @@
|
||||
/**
|
||||
* @module cross-compile
|
||||
*
|
||||
* 交叉编译工具链管理扩展 —— 治嵌入式开发场景下「宿主机架构 ≠ 目标机架构」缺陷:
|
||||
*
|
||||
* - 命门一(宿主 gcc 误用):通用 agent 默认用宿主 gcc 编 C,产物跑 x86 上无法在目标板执行。
|
||||
* 根治:tool_call 钩子拦截裸 gcc/g++/cc/c++ 调用(fail-closed 硬门),要求 agent 改用
|
||||
* xcompile 工具选 triple。
|
||||
* - 命门二(CMake 找宿主库):toolchain.cmake 不配 FIND_ROOT_PATH_MODE 就会去找宿主 x86 库导致
|
||||
* 链接失败/产物错架构。根治:generateCmakeToolchain 始终写 FIND_ROOT_PATH_MODE_*。
|
||||
* - 命门三(产物架构混入板):编译后不校验就 flash,x86 产物烧进板跑不起来。根治:verify action
|
||||
* 跑 `file` 校验产物 ELF 架构,不匹配即 isError。
|
||||
*
|
||||
* 场景锚定:x86_64 笔记本写 C 代码要用 aarch64-linux-gnu-gcc(RDK X5/S100)、
|
||||
* arm-none-eabi-gcc(bare-metal Cortex-M)、arm-linux-gnueabihf-gcc(32 位 Linux ARM)编译后
|
||||
* 才能在目标板跑。选错工具链=闭环后续全废。
|
||||
*
|
||||
* 见 Docs/F12_交叉编译工具链管理.md。逻辑内联为命名导出,tests 直接单测,无需 pi 运行时。
|
||||
* 顶层只 `import type`(esbuild/tsc 擦除),defineTool/Type 在工厂内动态 import——离线可单测。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
import type { ExecFn, ExecResult } from "../shared/types.js";
|
||||
|
||||
// 注:defineTool / Type 仅在工厂内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑函数
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时工厂不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// 类型
|
||||
// ============================================================================
|
||||
|
||||
/** 支持的交叉编译 triple。 */
|
||||
export type ToolchainTriple =
|
||||
| "aarch64-linux-gnu"
|
||||
| "arm-none-eabi"
|
||||
| "arm-linux-gnueabihf"
|
||||
| "riscv64-unknown-elf";
|
||||
|
||||
/** 已知 triple 列表(select action 校验、env 规整共用)。 */
|
||||
export const KNOWN_TRIPLES: ToolchainTriple[] = [
|
||||
"aarch64-linux-gnu",
|
||||
"arm-none-eabi",
|
||||
"arm-linux-gnueabihf",
|
||||
"riscv64-unknown-elf",
|
||||
];
|
||||
|
||||
/** 解析出的工具链信息。 */
|
||||
export interface ResolvedToolchain {
|
||||
triple: ToolchainTriple;
|
||||
/** 前缀,如 "aarch64-linux-gnu-"。 */
|
||||
prefix: string;
|
||||
/** gcc 可执行名。 */
|
||||
gcc: string;
|
||||
/** g++ 可执行名。 */
|
||||
cxx: string;
|
||||
/** objcopy 可执行名。 */
|
||||
objcopy: string;
|
||||
/** gdb 可执行名。 */
|
||||
gdb: string;
|
||||
/** 默认 sysroot(若已知;多数情况靠 -print-sysroot 探测)。 */
|
||||
sysroot?: string;
|
||||
/** CMake toolchain file 的 CMAKE_SYSTEM_NAME(Linux=有 OS, Generic=bare metal)。 */
|
||||
cmakeSystemName: string;
|
||||
/** CMAKE_SYSTEM_PROCESSOR。 */
|
||||
cmakeSystemProcessor: string;
|
||||
/** file(1) 输出里的架构关键字,用于 verifyArtifact 比对。 */
|
||||
elfArch: string;
|
||||
}
|
||||
|
||||
/** 工具链可用性探测结果。 */
|
||||
export interface ToolchainAvailability {
|
||||
available: boolean;
|
||||
triple: ToolchainTriple;
|
||||
/** gcc 绝对路径(which 探测)。 */
|
||||
gccPath?: string;
|
||||
/** -print-sysroot 探测到的 sysroot。 */
|
||||
sysroot?: string;
|
||||
/** gcc --version 首行。 */
|
||||
version?: string;
|
||||
/** 不可用时的原因。 */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
/** 宿主 gcc 拦截决策。 */
|
||||
export interface HostGccDecision {
|
||||
block: boolean;
|
||||
/** 命中的编译器名(gcc/g++/cc/c++)。 */
|
||||
compiler?: string;
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
/** 产物架构校验结果。 */
|
||||
export interface ArchVerifyResult {
|
||||
match: boolean;
|
||||
/** file(1) 解析出的架构关键字。 */
|
||||
detected: string | null;
|
||||
/** 不匹配时的错误描述。 */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ① 工具链注册表 + resolveToolchain
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 已知 triple → 工具链元数据。
|
||||
*
|
||||
* 扩展时往这里加条目即可,resolveToolchain/generateCmakeToolchain 自动适配。
|
||||
*/
|
||||
export const TOOLCHAIN_REGISTRY: Record<ToolchainTriple, ResolvedToolchain> = {
|
||||
"aarch64-linux-gnu": {
|
||||
triple: "aarch64-linux-gnu",
|
||||
prefix: "aarch64-linux-gnu-",
|
||||
gcc: "aarch64-linux-gnu-gcc",
|
||||
cxx: "aarch64-linux-gnu-g++",
|
||||
objcopy: "aarch64-linux-gnu-objcopy",
|
||||
gdb: "aarch64-linux-gnu-gdb",
|
||||
cmakeSystemName: "Linux",
|
||||
cmakeSystemProcessor: "aarch64",
|
||||
elfArch: "aarch64",
|
||||
},
|
||||
"arm-none-eabi": {
|
||||
triple: "arm-none-eabi",
|
||||
prefix: "arm-none-eabi-",
|
||||
gcc: "arm-none-eabi-gcc",
|
||||
cxx: "arm-none-eabi-g++",
|
||||
objcopy: "arm-none-eabi-objcopy",
|
||||
gdb: "arm-none-eabi-gdb",
|
||||
// bare metal: 无 sysroot,CMAKE_SYSTEM_NAME=Generic
|
||||
cmakeSystemName: "Generic",
|
||||
cmakeSystemProcessor: "arm",
|
||||
elfArch: "ARM",
|
||||
},
|
||||
"arm-linux-gnueabihf": {
|
||||
triple: "arm-linux-gnueabihf",
|
||||
prefix: "arm-linux-gnueabihf-",
|
||||
gcc: "arm-linux-gnueabihf-gcc",
|
||||
cxx: "arm-linux-gnueabihf-g++",
|
||||
objcopy: "arm-linux-gnueabihf-objcopy",
|
||||
gdb: "arm-linux-gnueabihf-gdb",
|
||||
cmakeSystemName: "Linux",
|
||||
cmakeSystemProcessor: "arm",
|
||||
elfArch: "ARM",
|
||||
},
|
||||
"riscv64-unknown-elf": {
|
||||
triple: "riscv64-unknown-elf",
|
||||
prefix: "riscv64-unknown-elf-",
|
||||
gcc: "riscv64-unknown-elf-gcc",
|
||||
cxx: "riscv64-unknown-elf-g++",
|
||||
objcopy: "riscv64-unknown-elf-objcopy",
|
||||
gdb: "riscv64-unknown-elf-gdb",
|
||||
cmakeSystemName: "Generic",
|
||||
cmakeSystemProcessor: "riscv64",
|
||||
elfArch: "RISC-V",
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* 判断字符串是否是已知 triple(类型谓词)。
|
||||
*
|
||||
* @param value 待检字符串。
|
||||
* @returns 是已知 triple 返回 true(同时收窄类型)。
|
||||
*/
|
||||
export function isKnownTriple(value: string): value is ToolchainTriple {
|
||||
return (KNOWN_TRIPLES as string[]).includes(value);
|
||||
}
|
||||
|
||||
/**
|
||||
* 把环境变量值规整成已知 triple;未知/空返回 null。纯函数,注入 raw 便于测试。
|
||||
*
|
||||
* @param raw 环境变量原始值(如 process.env.PI_TARGET_TRIPLE)。
|
||||
* @returns 已知 triple 或 null。
|
||||
*/
|
||||
export function normalizeTripleFromEnv(
|
||||
raw: string | undefined,
|
||||
): ToolchainTriple | null {
|
||||
if (!raw) return null;
|
||||
return isKnownTriple(raw) ? raw : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 由 triple 解析工具链信息。未知 triple 抛错(fail-closed)。
|
||||
*
|
||||
* 用途:xcompile select action 调此函数选定 triple,返回前缀/编译器路径等。
|
||||
*
|
||||
* @param triple 目标 triple。
|
||||
* @returns 工具链信息(独立副本,改不影响注册表)。
|
||||
*/
|
||||
export function resolveToolchain(triple: ToolchainTriple): ResolvedToolchain {
|
||||
const tc = TOOLCHAIN_REGISTRY[triple];
|
||||
if (!tc) {
|
||||
throw new Error(`unknown toolchain triple: ${triple}`);
|
||||
}
|
||||
// 返回独立副本,防止调用方修改注册表
|
||||
return { ...tc };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ② generateCmakeToolchain
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 生成 CMake toolchain file 文本。
|
||||
*
|
||||
* - 含 CMAKE_SYSTEM_NAME / CMAKE_SYSTEM_PROCESSOR / CMAKE_C_COMPILER / CMAKE_CXX_COMPILER / CMAKE_OBJCOPY
|
||||
* - 有 sysroot 时加 CMAKE_SYSROOT + CMAKE_FIND_ROOT_PATH
|
||||
* - 始终加 FIND_ROOT_PATH_MODE_* 防 CMake 找到宿主 x86 库(命门二根治)
|
||||
*
|
||||
* @param tc resolveToolchain 的返回值。
|
||||
* @param sysroot 可选 sysroot 路径(bare metal 通常不传)。
|
||||
* @returns toolchain.cmake 文本。
|
||||
*/
|
||||
export function generateCmakeToolchain(
|
||||
tc: ResolvedToolchain,
|
||||
sysroot?: string,
|
||||
): string {
|
||||
const lines: string[] = [
|
||||
"# Auto-generated by xcompile tool — do not edit by hand",
|
||||
`set(CMAKE_SYSTEM_NAME ${tc.cmakeSystemName})`,
|
||||
`set(CMAKE_SYSTEM_PROCESSOR ${tc.cmakeSystemProcessor})`,
|
||||
`set(CMAKE_C_COMPILER ${tc.gcc})`,
|
||||
`set(CMAKE_CXX_COMPILER ${tc.cxx})`,
|
||||
`set(CMAKE_OBJCOPY ${tc.objcopy})`,
|
||||
];
|
||||
|
||||
if (sysroot) {
|
||||
lines.push(`set(CMAKE_SYSROOT ${sysroot})`);
|
||||
lines.push(`set(CMAKE_FIND_ROOT_PATH ${sysroot})`);
|
||||
}
|
||||
|
||||
// FIND_ROOT_PATH_MODE 始终设:防 CMake 找到宿主 x86 库(即使无 sysroot)
|
||||
lines.push("set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)");
|
||||
lines.push("set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)");
|
||||
lines.push("set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)");
|
||||
lines.push("set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)");
|
||||
|
||||
return lines.join("\n") + "\n";
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ③ detectToolchain (注入 ExecFn)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 探测工具链是否可用 + 提取 sysroot。
|
||||
*
|
||||
* 纯逻辑:exec 由调用方注入(扩展层传 pi.exec,测试传 mock)。
|
||||
* fail-closed:gcc --version 失败 → available:false。
|
||||
*
|
||||
* 步骤:
|
||||
* 1. `${prefix}gcc --version` — 探测 gcc 是否存在
|
||||
* 2. `${prefix}gcc -print-sysroot` — 提取 sysroot(裸金属返回 /,不采纳)
|
||||
* 3. `which ${prefix}gcc` — 提取 gcc 绝对路径
|
||||
*
|
||||
* @param exec 注入的执行函数。
|
||||
* @param triple 目标 triple。
|
||||
* @returns 工具链可用性探测结果。
|
||||
*/
|
||||
export async function detectToolchain(
|
||||
exec: ExecFn,
|
||||
triple: ToolchainTriple,
|
||||
): Promise<ToolchainAvailability> {
|
||||
const tc = resolveToolchain(triple);
|
||||
|
||||
// 1. 探测 gcc 是否存在
|
||||
const versionRes = await exec(tc.gcc, ["--version"], {});
|
||||
if (versionRes.exitCode !== 0) {
|
||||
return {
|
||||
available: false,
|
||||
triple,
|
||||
error: `toolchain not found: ${tc.gcc} (exit ${versionRes.exitCode})`,
|
||||
};
|
||||
}
|
||||
|
||||
// 2. 提取 sysroot
|
||||
let sysroot: string | undefined;
|
||||
const sysrootRes = await exec(tc.gcc, ["-print-sysroot"], {});
|
||||
if (sysrootRes.exitCode === 0) {
|
||||
const sr = sysrootRes.stdout.trim();
|
||||
// bare metal 工具链 -print-sysroot 返回 "/",无意义 → 不采纳
|
||||
if (sr && sr !== "/" && sr !== "") {
|
||||
sysroot = sr;
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 提取 gcc 绝对路径
|
||||
let gccPath: string | undefined;
|
||||
const whichRes = await exec("which", [tc.gcc], {});
|
||||
if (whichRes.exitCode === 0) {
|
||||
const p = whichRes.stdout.trim();
|
||||
if (p) gccPath = p;
|
||||
}
|
||||
|
||||
return {
|
||||
available: true,
|
||||
triple,
|
||||
gccPath,
|
||||
sysroot,
|
||||
version: versionRes.stdout.trim().split("\n")[0],
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ④ detectHostGcc — tool_call 钩子纯逻辑
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 匹配裸宿主编译器调用(gcc/g++/cc/c++)的正则。
|
||||
*
|
||||
* 关键设计:
|
||||
* - 前导字符必须是 行首/空白/;&|=(/ 之一——这些表示"裸调用"或透传赋值
|
||||
* - 后跟 [\s-]|$ —— 允许 `gcc-12` 这种版本号后缀
|
||||
* - **不匹配** `aarch64-linux-gnu-gcc`:因为 gcc 前面是 `-`,不在前导字符集里
|
||||
* - **不匹配** `arm-none-eabi-g++`:同理
|
||||
*/
|
||||
const HOST_CC_PATTERN = /(?:^|[\s;&|(=/])(gcc|g\+\+|cc|c\+\+)(?=[\s-]|$)/;
|
||||
|
||||
/**
|
||||
* 检测 bash 命令是否在裸用宿主 gcc/g++/cc/c++(非交叉前缀)。
|
||||
* fail-closed:命中即 block,要求 agent 改用 xcompile 工具选 triple。
|
||||
*
|
||||
* 用途:cross-compile 扩展的 tool_call 钩子调此函数,拦截 BashToolCallEvent.input.command。
|
||||
*
|
||||
* @param command bash 命令字符串。
|
||||
* @returns 拦截决策(block=true 时含 compiler + reason)。
|
||||
*/
|
||||
export function detectHostGcc(command: string): HostGccDecision {
|
||||
if (!command || command.trim() === "") {
|
||||
return { block: false };
|
||||
}
|
||||
const m = command.match(HOST_CC_PATTERN);
|
||||
if (m) {
|
||||
return {
|
||||
block: true,
|
||||
compiler: m[1],
|
||||
reason:
|
||||
`宿主 ${m[1]} 禁用于嵌入式交叉编译,请用 xcompile 工具选 triple ` +
|
||||
`(如 aarch64-linux-gnu-gcc / arm-none-eabi-gcc)`,
|
||||
};
|
||||
}
|
||||
return { block: false };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ⑤ parseFileOutput / verifyArtifact — 产物架构校验
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 从 file(1) 命令输出解析产物架构,比对期望架构。
|
||||
*
|
||||
* file 输出示例:
|
||||
* "main: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV)..."
|
||||
* "main: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV)..."
|
||||
* "firmware.elf: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV)..."
|
||||
*
|
||||
* 用途:xcompile verify action 调此函数,确认编译产物是目标架构而非 x86(命门三)。
|
||||
*
|
||||
* @param fileOutput file(1) 命令的 stdout。
|
||||
* @param expectedArch 期望架构关键字(对应 ResolvedToolchain.elfArch)。
|
||||
* @returns 架构校验结果。
|
||||
*/
|
||||
export function parseFileOutput(
|
||||
fileOutput: string,
|
||||
expectedArch: string,
|
||||
): ArchVerifyResult {
|
||||
const lower = fileOutput.toLowerCase();
|
||||
|
||||
// 非 ELF → 无法校验
|
||||
if (!lower.includes("elf")) {
|
||||
return {
|
||||
match: false,
|
||||
detected: null,
|
||||
error: "could not parse architecture from file output (not ELF)",
|
||||
};
|
||||
}
|
||||
|
||||
// 按已知架构关键字探测
|
||||
if (lower.includes("x86-64") || lower.includes("x86_64")) {
|
||||
const match =
|
||||
expectedArch.toLowerCase() === "x86-64" ||
|
||||
expectedArch.toLowerCase() === "x86_64";
|
||||
return {
|
||||
match,
|
||||
detected: "x86-64",
|
||||
error: match
|
||||
? undefined
|
||||
: `architecture mismatch: expected ${expectedArch}, got x86-64`,
|
||||
};
|
||||
}
|
||||
if (lower.includes("aarch64")) {
|
||||
const match = expectedArch.toLowerCase() === "aarch64";
|
||||
return {
|
||||
match,
|
||||
detected: "aarch64",
|
||||
error: match
|
||||
? undefined
|
||||
: `architecture mismatch: expected ${expectedArch}, got aarch64`,
|
||||
};
|
||||
}
|
||||
if (lower.includes("risc-v") || lower.includes("riscv")) {
|
||||
const match =
|
||||
expectedArch.toLowerCase().includes("riscv") ||
|
||||
expectedArch.toLowerCase().includes("risc-v");
|
||||
return {
|
||||
match,
|
||||
detected: "RISC-V",
|
||||
error: match
|
||||
? undefined
|
||||
: `architecture mismatch: expected ${expectedArch}, got RISC-V`,
|
||||
};
|
||||
}
|
||||
// ARM 关键字放在最后(避免与 aarch64 的 "ARM aarch64" 冲突——上面已先匹配 aarch64)
|
||||
if (lower.includes("arm")) {
|
||||
const match = expectedArch.toLowerCase() === "arm";
|
||||
return {
|
||||
match,
|
||||
detected: "ARM",
|
||||
error: match
|
||||
? undefined
|
||||
: `architecture mismatch: expected ${expectedArch}, got ARM`,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
match: false,
|
||||
detected: null,
|
||||
error: "could not parse architecture from file output",
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 用注入的 ExecFn 跑 `file <artifact>`,校验产物架构。
|
||||
* fail-closed:file 命令失败 → match:false + error。
|
||||
*
|
||||
* @param exec 注入的执行函数。
|
||||
* @param artifactPath 编译产物路径。
|
||||
* @param expectedArch 期望架构关键字。
|
||||
* @returns 架构校验结果。
|
||||
*/
|
||||
export async function verifyArtifact(
|
||||
exec: ExecFn,
|
||||
artifactPath: string,
|
||||
expectedArch: string,
|
||||
): Promise<ArchVerifyResult> {
|
||||
const res = await exec("file", [artifactPath], {});
|
||||
if (res.exitCode !== 0) {
|
||||
return {
|
||||
match: false,
|
||||
detected: null,
|
||||
error: `file command failed: ${res.stderr.trim() || res.stdout.trim()}`,
|
||||
};
|
||||
}
|
||||
return parseFileOutput(res.stdout, expectedArch);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ToolchainSession — 状态跨 tool call 保留(闭包持有)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 工具链会话状态:记住 agent 选定的 triple + 探测结果,跨 tool call 保留。
|
||||
*
|
||||
* 扩展层实例化一个单例,xcompile 工具的各 action 读写它。
|
||||
*/
|
||||
export class ToolchainSession {
|
||||
private current: ToolchainTriple | null = null;
|
||||
private info: ToolchainAvailability | null = null;
|
||||
|
||||
/** 选定/切换 triple。返回解析出的工具链信息。切换后 info 重置(需重新 detect)。 */
|
||||
select(triple: ToolchainTriple): ResolvedToolchain {
|
||||
this.current = triple;
|
||||
this.info = null;
|
||||
return resolveToolchain(triple);
|
||||
}
|
||||
|
||||
/** 当前 triple(未选返回 null)。 */
|
||||
getCurrent(): ToolchainTriple | null {
|
||||
return this.current;
|
||||
}
|
||||
|
||||
/** 当前解析出的工具链(未选返回 null)。 */
|
||||
getResolved(): ResolvedToolchain | null {
|
||||
return this.current ? resolveToolchain(this.current) : null;
|
||||
}
|
||||
|
||||
/** 上次 detect 缓存的结果(未探测返回 null)。 */
|
||||
getInfo(): ToolchainAvailability | null {
|
||||
return this.info;
|
||||
}
|
||||
|
||||
/** 探测当前 triple 的工具链可用性。有缓存时不重复探测(跨 tool call 保留)。 */
|
||||
async detect(exec: ExecFn): Promise<ToolchainAvailability> {
|
||||
if (!this.current) {
|
||||
return {
|
||||
available: false,
|
||||
triple: "aarch64-linux-gnu",
|
||||
error: "no triple selected — call xcompile select first",
|
||||
};
|
||||
}
|
||||
if (this.info) {
|
||||
return this.info;
|
||||
}
|
||||
this.info = await detectToolchain(exec, this.current);
|
||||
return this.info;
|
||||
}
|
||||
|
||||
/** 清空状态(session 结束时调)。 */
|
||||
reset(): void {
|
||||
this.current = null;
|
||||
this.info = null;
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// xcompile 工具 + 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* cross-compile 扩展装配。
|
||||
*
|
||||
* - 注册 `xcompile` 工具(select/info/toolchain/verify 四 action)
|
||||
* - tool_call 钩子拦截宿主 gcc 误用(fail-closed 硬门,命门一)
|
||||
* - session_start:从 PI_TARGET_TRIPLE env 读默认 triple + 记录加载
|
||||
* - 暴露 session 给同进程其他扩展(如 build 扩展)经 events 总线握手
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*
|
||||
* @param pi 扩展 API。
|
||||
*/
|
||||
export default async function crossCompileExtension(
|
||||
pi: ExtensionAPI,
|
||||
): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
// 单例会话状态(跨 tool call 保留)
|
||||
const session = new ToolchainSession();
|
||||
|
||||
/**
|
||||
* pi.exec 适配:把 (command, args) 转成 ExecFn 签名的调用。
|
||||
* 返回值补 ExecResult 结构(pi.exec 已返回 ExecResult)。
|
||||
*/
|
||||
const execFn: ExecFn = async (command, args, opts) => {
|
||||
const res = await pi.exec(command, args, opts ?? {});
|
||||
const out: ExecResult = {
|
||||
stdout: res.stdout,
|
||||
stderr: res.stderr,
|
||||
exitCode: res.exitCode,
|
||||
};
|
||||
if (res.signal) out.signal = res.signal;
|
||||
return out;
|
||||
};
|
||||
|
||||
// ---- xcompile 工具 ----
|
||||
const xcompileTool = defineTool({
|
||||
name: "xcompile",
|
||||
label: "Cross-Compile Toolchain",
|
||||
description:
|
||||
"Manage the cross-compilation toolchain for embedded targets. " +
|
||||
"Actions: select (choose a target triple), info (query current toolchain + availability), " +
|
||||
"toolchain (generate a CMake toolchain file), verify (check a binary's architecture via `file`).",
|
||||
promptSnippet:
|
||||
"Select / inspect / generate CMake toolchain for a cross-compile target (aarch64/arm-none-eabi)",
|
||||
parameters: Type.Object({
|
||||
action: Type.Union(
|
||||
[
|
||||
Type.Literal("select"),
|
||||
Type.Literal("info"),
|
||||
Type.Literal("toolchain"),
|
||||
Type.Literal("verify"),
|
||||
],
|
||||
{ description: "Action to perform" },
|
||||
),
|
||||
triple: Type.Optional(
|
||||
Type.String({
|
||||
description:
|
||||
"Target triple (aarch64-linux-gnu, arm-none-eabi, arm-linux-gnueabihf, riscv64-unknown-elf). " +
|
||||
"Required for 'select'. Inferred from PI_TARGET_TRIPLE env if omitted.",
|
||||
}),
|
||||
),
|
||||
build_dir: Type.Optional(
|
||||
Type.String({
|
||||
description: "Build directory for CMake (used by 'toolchain' action)",
|
||||
}),
|
||||
),
|
||||
artifact: Type.Optional(
|
||||
Type.String({ description: "Path to compiled binary, for 'verify' action" }),
|
||||
),
|
||||
}),
|
||||
executionMode: "sequential",
|
||||
async execute(
|
||||
_id,
|
||||
params,
|
||||
_signal,
|
||||
_onUpdate,
|
||||
ctx: ExtensionContext,
|
||||
) {
|
||||
const p = params as {
|
||||
action: "select" | "info" | "toolchain" | "verify";
|
||||
triple?: string;
|
||||
build_dir?: string;
|
||||
artifact?: string;
|
||||
};
|
||||
|
||||
// ---- select ----
|
||||
if (p.action === "select") {
|
||||
const rawTriple = p.triple ?? process.env.PI_TARGET_TRIPLE;
|
||||
const triple = normalizeTripleFromEnv(rawTriple);
|
||||
if (!triple) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: "[xcompile] no valid triple specified and PI_TARGET_TRIPLE env not set. " +
|
||||
"Valid triples: aarch64-linux-gnu, arm-none-eabi, arm-linux-gnueabihf, riscv64-unknown-elf.",
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
const tc = session.select(triple);
|
||||
// 立即探测可用性(fail-closed:未装报错而非静默通过)
|
||||
const avail = await session.detect(execFn);
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: JSON.stringify(
|
||||
{
|
||||
action: "select",
|
||||
triple: tc.triple,
|
||||
prefix: tc.prefix,
|
||||
gcc: tc.gcc,
|
||||
cxx: tc.cxx,
|
||||
objcopy: tc.objcopy,
|
||||
cmakeSystemName: tc.cmakeSystemName,
|
||||
available: avail.available,
|
||||
version: avail.version,
|
||||
sysroot: avail.sysroot,
|
||||
gccPath: avail.gccPath,
|
||||
error: avail.error,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
},
|
||||
],
|
||||
details: { triple: tc.triple, available: avail.available },
|
||||
};
|
||||
}
|
||||
|
||||
// ---- info ----
|
||||
if (p.action === "info") {
|
||||
const triple = session.getCurrent();
|
||||
if (!triple) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: "[xcompile] no triple selected. Use xcompile select --triple <triple> first.",
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
const tc = session.getResolved()!;
|
||||
// 重新探测(info 总是给最新状态)
|
||||
const avail = await session.detect(execFn);
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: JSON.stringify(
|
||||
{
|
||||
triple: tc.triple,
|
||||
prefix: tc.prefix,
|
||||
gcc: tc.gcc,
|
||||
cxx: tc.cxx,
|
||||
objcopy: tc.objcopy,
|
||||
gdb: tc.gdb,
|
||||
cmakeSystemName: tc.cmakeSystemName,
|
||||
cmakeSystemProcessor: tc.cmakeSystemProcessor,
|
||||
elfArch: tc.elfArch,
|
||||
available: avail.available,
|
||||
version: avail.version,
|
||||
sysroot: avail.sysroot,
|
||||
gccPath: avail.gccPath,
|
||||
error: avail.error,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
},
|
||||
],
|
||||
details: { triple: tc.triple, available: avail.available },
|
||||
};
|
||||
}
|
||||
|
||||
// ---- toolchain (generate CMake toolchain file) ----
|
||||
if (p.action === "toolchain") {
|
||||
const tc = session.getResolved();
|
||||
if (!tc) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: "[xcompile] no triple selected. Use xcompile select --triple <triple> first.",
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
// 读 sysroot:优先 PI_SYSROOT env,其次探测结果
|
||||
const sysroot =
|
||||
process.env.PI_SYSROOT ?? session.getInfo()?.sysroot ?? undefined;
|
||||
const cmakeContent = generateCmakeToolchain(tc, sysroot);
|
||||
const buildDir =
|
||||
p.build_dir ?? process.env.PI_BUILD_DIR ?? ".";
|
||||
return {
|
||||
content: [
|
||||
{ type: "text" as const, text: cmakeContent },
|
||||
{
|
||||
type: "text" as const,
|
||||
text:
|
||||
`\n[xcompile] Save as ${buildDir}/toolchain.cmake and run: ` +
|
||||
`cmake -DCMAKE_TOOLCHAIN_FILE=${buildDir}/toolchain.cmake ${buildDir}`,
|
||||
},
|
||||
],
|
||||
details: { triple: tc.triple, sysroot: sysroot ?? null },
|
||||
};
|
||||
}
|
||||
|
||||
// ---- verify ----
|
||||
if (p.action === "verify") {
|
||||
const tc = session.getResolved();
|
||||
if (!tc) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: "[xcompile] no triple selected. Use xcompile select --triple <triple> first.",
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
if (!p.artifact) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: "[xcompile] verify requires --artifact <path-to-binary>.",
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
const result = await verifyArtifact(
|
||||
execFn,
|
||||
p.artifact,
|
||||
tc.elfArch,
|
||||
);
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: JSON.stringify(
|
||||
{
|
||||
artifact: p.artifact,
|
||||
expectedArch: tc.elfArch,
|
||||
detected: result.detected,
|
||||
match: result.match,
|
||||
error: result.error,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
},
|
||||
],
|
||||
isError: !result.match,
|
||||
details: { match: result.match, detected: result.detected },
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
content: [
|
||||
{ type: "text" as const, text: `[xcompile] unknown action: ${p.action}` },
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
// ---- 注册 xcompile 工具 ----
|
||||
pi.registerTool(xcompileTool);
|
||||
|
||||
// ---- tool_call 钩子:拦截宿主 gcc 误用(fail-closed 硬门,命门一) ----
|
||||
// 参照 safety-gate + pi examples/extensions/permission-gate.ts 范式。
|
||||
pi.on("tool_call", async (event, ctx: ExtensionContext) => {
|
||||
if (event.toolName !== "bash") return undefined;
|
||||
|
||||
const command = (event.input as { command?: string }).command ?? "";
|
||||
const decision = detectHostGcc(command);
|
||||
|
||||
if (decision.block) {
|
||||
// fail-closed:无 UI 也直接 block
|
||||
if (ctx.hasUI) {
|
||||
const allow = await ctx.ui.confirm(
|
||||
`⚠️ 宿主 ${decision.compiler} 被拦截 [xcompile host-gcc-guard]`,
|
||||
`${command}\n\n原因:${decision.reason}\n` +
|
||||
"仍要放行?(不推荐——产物将是 x86 架构,无法在目标板运行)",
|
||||
);
|
||||
if (allow) {
|
||||
pi.appendEntry("xcompile:override-host-gcc", {
|
||||
compiler: decision.compiler,
|
||||
command,
|
||||
});
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
return {
|
||||
block: true,
|
||||
reason: `[xcompile] ${decision.reason}`,
|
||||
terminate: true,
|
||||
};
|
||||
}
|
||||
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- session_start:记录工具链加载 + 从 env 读默认 triple ----
|
||||
pi.on("session_start", () => {
|
||||
const envTriple = normalizeTripleFromEnv(process.env.PI_TARGET_TRIPLE);
|
||||
if (envTriple) {
|
||||
session.select(envTriple);
|
||||
}
|
||||
pi.appendEntry("xcompile:loaded", {
|
||||
defaultTriple: envTriple,
|
||||
envSysroot: process.env.PI_SYSROOT ?? null,
|
||||
});
|
||||
});
|
||||
|
||||
// ---- 暴露 session 给同进程其他扩展(如 build 扩展) ----
|
||||
pi.events.on("xcompile:request-session", () => {
|
||||
pi.events.emit("xcompile:session", {
|
||||
current: session.getCurrent(),
|
||||
resolved: session.getResolved(),
|
||||
info: session.getInfo(),
|
||||
});
|
||||
});
|
||||
}
|
||||
621
src/extensions/datasheet-rag.ts
Normal file
621
src/extensions/datasheet-rag.ts
Normal file
@ -0,0 +1,621 @@
|
||||
/**
|
||||
* @module datasheet-rag
|
||||
*
|
||||
* datasheet 与手册 RAG 扩展 —— 治嵌入式开发场景缺陷 #8(命门二:寄存器地址/位偏移
|
||||
* 靠记忆=幻觉=写错硬件)+ 缺陷 #2(read 不支持 PDF)。
|
||||
*
|
||||
* 场景锚定:每个外设芯片配 datasheet(几百到几千页 PDF),含寄存器映射表(地址
|
||||
* `0x40021000` = RCC AHB1,位偏移 `bit[4]` = GPIOAEN)、位域定义、复位值、时序图、
|
||||
* 电气参数。上下文巨大 + 数值零容错——寄存器地址错一位=写错硬件模块,位偏移错=
|
||||
* 误改不相关功能甚至清零关键配置。LLM 训练数据里这类精确数值少,易幻觉地址/位偏移。
|
||||
*
|
||||
* 核心流水线(纯逻辑,零 pi 依赖,离线可单测):
|
||||
* pagesFromPdftotextOutput(stdout, filePath) → PdfPage[] pdftotext 输出切页
|
||||
* chunkPdf(pages, chunkSize) → Chunk[] 按页/按字符数分块
|
||||
* buildIndex(chunks) → DatasheetIndex 倒排索引(term 小写分词)
|
||||
* mergeIndex(target, addition) → DatasheetIndex 多文档合并
|
||||
* search(index, query, topK, options) → 排名 chunk(tf) 检索
|
||||
* formatContext(results, query) → 注入 prompt 文本 上下文格式化
|
||||
* extractAddresses(results) → string[] 提取 hex 地址
|
||||
* verifyAddressInResults(addr, results) → boolean 地址交叉校验
|
||||
*
|
||||
* fail-closed 语义:查不到任何 term 返回空(不幻觉地址);pdftotext 不可用返回空页数组;
|
||||
* 地址未在 datasheet 出现返回 false。
|
||||
*
|
||||
* 见 Docs/F18_datasheet与手册RAG.md。逻辑内联为命名导出,tests 直接单测,无需 pi 运行时。
|
||||
* PDF 文本抽取的子进程调用(pi.exec pdftotext)留在工厂体内;逻辑层只接收已抽取的文本。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
|
||||
|
||||
// 注:defineTool / Type 仅在 factory 内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑函数
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时 factory 不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// 类型
|
||||
// ============================================================================
|
||||
|
||||
/** 已抽取的 PDF 页文本(由 pdftotext 输出切页或扩展层 pi.exec 产出)。 */
|
||||
export interface PdfPage {
|
||||
page: number;
|
||||
text: string;
|
||||
filePath?: string;
|
||||
}
|
||||
|
||||
/** 文档分块。id 格式 p{page}-c{chunkIndex}。 */
|
||||
export interface Chunk {
|
||||
id: string;
|
||||
page: number;
|
||||
text: string;
|
||||
filePath?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 倒排索引 + 正排查表。
|
||||
* inverted: term(小写分词) → 出现该 term 的 chunkId 集合。
|
||||
* chunks: chunkId → Chunk(正排,用于 search 回填文本/页码)。
|
||||
* termFreq: chunkId → (term → 该 chunk 内出现次数)(tf 排序用)。
|
||||
*/
|
||||
export interface DatasheetIndex {
|
||||
inverted: Map<string, Set<string>>;
|
||||
chunks: Map<string, Chunk>;
|
||||
termFreq: Map<string, Map<string, number>>;
|
||||
/** 参与索引的文档路径集合(docPath 过滤用)。 */
|
||||
docPaths: Set<string>;
|
||||
/** 索引内 chunk 总数。 */
|
||||
size: number;
|
||||
}
|
||||
|
||||
/** 单条检索结果。 */
|
||||
export interface SearchResult {
|
||||
chunkId: string;
|
||||
page: number;
|
||||
text: string;
|
||||
filePath?: string;
|
||||
/** tf 分数(越高越相关)。 */
|
||||
score: number;
|
||||
}
|
||||
|
||||
/** 检索过滤条件。 */
|
||||
export interface SearchFilter {
|
||||
/** 限定文档路径。 */
|
||||
docPath?: string;
|
||||
/** 限定页码。 */
|
||||
page?: number;
|
||||
}
|
||||
|
||||
/** 搜索选项。 */
|
||||
export interface SearchOptions {
|
||||
topK?: number;
|
||||
filter?: SearchFilter;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 分词
|
||||
// ============================================================================
|
||||
|
||||
/** 匹配单词 token:字母数字+下划线/连字符,至少 1 字符。hex 地址 0x40021000 是一个 token。 */
|
||||
const TOKEN_RE = /[a-zA-Z0-9_]+(?:-[a-zA-Z0-9_]+)*/g;
|
||||
|
||||
/**
|
||||
* 将文本分词为 term 数组(保留原始大小写用于地址,倒排时统一小写)。
|
||||
*
|
||||
* @param text 待分词文本。
|
||||
* @returns term 数组;空文本返回空数组。
|
||||
* @example tokenize("GPIOA_BASE = 0x48000000") → ["GPIOA_BASE", "0x48000000"]
|
||||
*/
|
||||
export function tokenize(text: string): string[] {
|
||||
if (!text) return [];
|
||||
const matches = text.match(TOKEN_RE);
|
||||
return matches ?? [];
|
||||
}
|
||||
|
||||
/**
|
||||
* 分词并小写化(倒排索引用)。
|
||||
*
|
||||
* @param text 待分词文本。
|
||||
* @returns 小写 term 数组。
|
||||
*/
|
||||
export function tokenizeLower(text: string): string[] {
|
||||
return tokenize(text).map((t) => t.toLowerCase());
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// pagesFromPdftotextOutput:pdftotext 输出切页(纯逻辑)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把 `pdftotext -layout <file> -` 的 stdout 按分页符 `\f` 切分成 PdfPage 数组。
|
||||
*
|
||||
* pdftotext 用 `\f`(form feed)分隔页。本函数纯逻辑处理已抽取文本,不调子进程——
|
||||
* 子进程调用(pi.exec)在工厂体内。空 stdout / 全空白页被过滤(fail-closed)。
|
||||
*
|
||||
* @param stdout pdftotext 的原始标准输出。
|
||||
* @param filePath PDF 文件路径,透传到每页用于 docPath 过滤。
|
||||
* @returns PdfPage 数组(page 从 1 起);stdout 为空返回空数组。
|
||||
*/
|
||||
export function pagesFromPdftotextOutput(stdout: string, filePath: string): PdfPage[] {
|
||||
if (!stdout || stdout.length === 0) return [];
|
||||
const pageTexts = stdout.split("\f");
|
||||
const pages: PdfPage[] = [];
|
||||
for (let i = 0; i < pageTexts.length; i++) {
|
||||
const text = pageTexts[i] ?? "";
|
||||
if (text.trim().length > 0) {
|
||||
pages.push({ page: i + 1, text, filePath });
|
||||
}
|
||||
}
|
||||
return pages;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// chunkPdf:按页 + 字符数分块
|
||||
// ============================================================================
|
||||
|
||||
/** 默认分块大小(字符数)。2KB 对齐 pi truncate 的 2KB 块大小。 */
|
||||
export const DEFAULT_CHUNK_SIZE = 2000;
|
||||
|
||||
/**
|
||||
* 把已抽取的页文本切成 chunk。每页独立切分,块带页码。
|
||||
* chunk id 格式 `p{page}-c{index}`,index 从 0 起。
|
||||
*
|
||||
* 切分策略:按 chunkSize 字符数切,但不在单词中间断开(回退到最近的空白边界)。
|
||||
* 若某页文本 < chunkSize,整页一个 chunk。
|
||||
*
|
||||
* @param pages 已抽取的页文本数组。
|
||||
* @param chunkSize 每块最大字符数,默认 2000。
|
||||
* @returns Chunk 数组。
|
||||
* @throws chunkSize <= 0 时抛错。
|
||||
*/
|
||||
export function chunkPdf(pages: PdfPage[], chunkSize: number = DEFAULT_CHUNK_SIZE): Chunk[] {
|
||||
const chunks: Chunk[] = [];
|
||||
if (chunkSize <= 0) {
|
||||
throw new Error(`chunkSize must be positive, got ${chunkSize}`);
|
||||
}
|
||||
for (const pg of pages) {
|
||||
const text = pg.text ?? "";
|
||||
if (text.length === 0) continue;
|
||||
let idx = 0;
|
||||
let pos = 0;
|
||||
while (pos < text.length) {
|
||||
let end = pos + chunkSize;
|
||||
if (end >= text.length) {
|
||||
end = text.length;
|
||||
} else {
|
||||
// 不在单词中间断开:回退到 end 之前最后一个空白
|
||||
let boundary = end;
|
||||
while (boundary > pos && !/\s/.test(text[boundary]!)) {
|
||||
boundary--;
|
||||
}
|
||||
// 回退太多(整块一个词)就直接用 end
|
||||
if (boundary <= pos) {
|
||||
boundary = end;
|
||||
}
|
||||
end = boundary;
|
||||
}
|
||||
const slice = text.slice(pos, end).trim();
|
||||
if (slice.length > 0) {
|
||||
chunks.push({
|
||||
id: `p${pg.page}-c${idx}`,
|
||||
page: pg.page,
|
||||
text: slice,
|
||||
filePath: pg.filePath,
|
||||
});
|
||||
idx++;
|
||||
}
|
||||
pos = end;
|
||||
// 跳过尾部空白避免无限循环
|
||||
while (pos < text.length && /\s/.test(text[pos]!)) pos++;
|
||||
}
|
||||
}
|
||||
return chunks;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// buildIndex:倒排索引
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 给定 chunk 列表,构建倒排索引。
|
||||
* - term 统一小写分词("GPIOA_BASE" → "gpioa_base")
|
||||
* - inverted[term] = Set<chunkId>
|
||||
* - termFreq[chunkId][term] = 出现次数(tf 排序用)
|
||||
* - chunks[chunkId] = Chunk(正排)
|
||||
*
|
||||
* @param chunks 已分块的文档块数组。
|
||||
* @returns DatasheetIndex,search 直接消费。
|
||||
*/
|
||||
export function buildIndex(chunks: Chunk[]): DatasheetIndex {
|
||||
const inverted = new Map<string, Set<string>>();
|
||||
const chunkMap = new Map<string, Chunk>();
|
||||
const termFreq = new Map<string, Map<string, number>>();
|
||||
const docPaths = new Set<string>();
|
||||
|
||||
for (const chunk of chunks) {
|
||||
chunkMap.set(chunk.id, chunk);
|
||||
if (chunk.filePath) docPaths.add(chunk.filePath);
|
||||
|
||||
const freq = new Map<string, number>();
|
||||
termFreq.set(chunk.id, freq);
|
||||
|
||||
const terms = tokenizeLower(chunk.text);
|
||||
for (const term of terms) {
|
||||
// term frequency
|
||||
freq.set(term, (freq.get(term) ?? 0) + 1);
|
||||
// inverted index
|
||||
let set = inverted.get(term);
|
||||
if (!set) {
|
||||
set = new Set<string>();
|
||||
inverted.set(term, set);
|
||||
}
|
||||
set.add(chunk.id);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
inverted,
|
||||
chunks: chunkMap,
|
||||
termFreq,
|
||||
docPaths,
|
||||
size: chunks.length,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 把 addition 索引合并进 target(原地修改 target 并返回),支持多文档累加。
|
||||
*
|
||||
* 用于 /dsrag-index 命令多次索引不同 PDF 后合并到全局索引。
|
||||
*
|
||||
* @param target 被合并入的目标索引(原地修改)。
|
||||
* @param addition 待合并的新索引。
|
||||
* @returns 合并后的 target(同一引用)。
|
||||
*/
|
||||
export function mergeIndex(target: DatasheetIndex, addition: DatasheetIndex): DatasheetIndex {
|
||||
for (const [id, chunk] of addition.chunks) {
|
||||
target.chunks.set(id, chunk);
|
||||
}
|
||||
for (const [term, set] of addition.inverted) {
|
||||
const existing = target.inverted.get(term);
|
||||
if (existing) {
|
||||
for (const id of set) existing.add(id);
|
||||
} else {
|
||||
target.inverted.set(term, set);
|
||||
}
|
||||
}
|
||||
for (const [id, freq] of addition.termFreq) {
|
||||
target.termFreq.set(id, freq);
|
||||
}
|
||||
for (const p of addition.docPaths) target.docPaths.add(p);
|
||||
target.size += addition.size;
|
||||
return target;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// search:TF 检索 + 排名
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 检索 datasheet 索引,按 TF 分数排名返回 top-K chunk。
|
||||
*
|
||||
* 评分:对每个 query term,找出命中该 term 的 chunk,累加该 chunk 内该 term 的出现次数(tf)。
|
||||
* 多个 query term 命中同一 chunk 时分数叠加(逻辑 OR + 求和)。
|
||||
*
|
||||
* fail-closed:查不到任何 term 返回空数组(不幻觉地址)。
|
||||
*
|
||||
* @param index 已构建的 datasheet 倒排索引。
|
||||
* @param query 查询串(寄存器名/地址/位域名)。
|
||||
* @param topK 默认最大返回数,默认 5。
|
||||
* @param options.topK 覆盖 topK;options.filter 限定 docPath/page。
|
||||
* @returns 按分数降序(同分按页码升序)的 SearchResult 数组。
|
||||
*/
|
||||
export function search(
|
||||
index: DatasheetIndex,
|
||||
query: string,
|
||||
topK: number = 5,
|
||||
options: SearchOptions = {},
|
||||
): SearchResult[] {
|
||||
if (!query || query.trim().length === 0) return [];
|
||||
const limit = options.topK ?? topK;
|
||||
const filter = options.filter;
|
||||
|
||||
const queryTerms = tokenizeLower(query);
|
||||
if (queryTerms.length === 0) return [];
|
||||
|
||||
// 收集候选 chunkId → 累加 tf 分数
|
||||
const scores = new Map<string, number>();
|
||||
for (const term of queryTerms) {
|
||||
const chunkIds = index.inverted.get(term);
|
||||
if (!chunkIds) continue;
|
||||
for (const chunkId of chunkIds) {
|
||||
const freq = index.termFreq.get(chunkId);
|
||||
const tf = freq?.get(term) ?? 0;
|
||||
scores.set(chunkId, (scores.get(chunkId) ?? 0) + tf);
|
||||
}
|
||||
}
|
||||
|
||||
// 过滤 + 组装结果
|
||||
const results: SearchResult[] = [];
|
||||
for (const [chunkId, score] of scores) {
|
||||
const chunk = index.chunks.get(chunkId);
|
||||
if (!chunk) continue;
|
||||
if (filter?.docPath && chunk.filePath !== filter.docPath) continue;
|
||||
if (filter?.page !== undefined && chunk.page !== filter.page) continue;
|
||||
results.push({
|
||||
chunkId: chunk.id,
|
||||
page: chunk.page,
|
||||
text: chunk.text,
|
||||
filePath: chunk.filePath,
|
||||
score,
|
||||
});
|
||||
}
|
||||
|
||||
// 按分数降序,同分按页码升序(稳定)
|
||||
results.sort((a, b) => {
|
||||
if (b.score !== a.score) return b.score - a.score;
|
||||
return a.page - b.page;
|
||||
});
|
||||
|
||||
return results.slice(0, Math.max(0, limit));
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// formatContext:格式化为 prompt 注入文本
|
||||
// ============================================================================
|
||||
|
||||
/** 每个 chunk 的最大截断长度(防 prompt 爆炸)。 */
|
||||
export const MAX_CONTEXT_CHUNK_CHARS = 1500;
|
||||
|
||||
/**
|
||||
* 把检索结果格式化为可注入 prompt 的文本块。
|
||||
*
|
||||
* 格式:
|
||||
* === Datasheet RAG: 3 passages (query: "GPIOA_BASE") ===
|
||||
* [p12 /path/to/rm0090.pdf] (score: 3)
|
||||
* GPIOA_BASE = 0x48000000. The GPIOA register base address...
|
||||
* [p45 /path/to/rm0090.pdf] (score: 1)
|
||||
* ...
|
||||
* === End passages ===
|
||||
*
|
||||
* @param results 检索结果数组。
|
||||
* @param query 原始查询串(可选,写入 header 供 agent 追溯)。
|
||||
* @returns 格式化文本;空结果返回 "No matching passages found."(fail-closed,不幻觉)。
|
||||
*/
|
||||
export function formatContext(results: SearchResult[], query?: string): string {
|
||||
if (results.length === 0) {
|
||||
return "No matching passages found.";
|
||||
}
|
||||
const header =
|
||||
`=== Datasheet RAG: ${results.length} passage(s)${query ? ` (query: "${query}")` : ""} ===\n`;
|
||||
const parts: string[] = [header];
|
||||
for (const r of results) {
|
||||
const loc = `[p${r.page}${r.filePath ? ` ${r.filePath}` : ""}] (score: ${r.score})`;
|
||||
const text =
|
||||
r.text.length > MAX_CONTEXT_CHUNK_CHARS
|
||||
? r.text.slice(0, MAX_CONTEXT_CHUNK_CHARS) + "…"
|
||||
: r.text;
|
||||
parts.push(`${loc}\n ${text}\n`);
|
||||
}
|
||||
parts.push("=== End passages ===");
|
||||
return parts.join("\n");
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 地址提取与交叉校验(供 hex 归一扩展交叉校验)
|
||||
// ============================================================================
|
||||
|
||||
/** 匹配 hex 寄存器地址(0x + 4~8 位 hex)。 */
|
||||
const HEX_ADDR_RE = /0x[0-9a-fA-F]{4,8}\b/g;
|
||||
|
||||
/**
|
||||
* 从检索结果文本中提取所有 hex 地址(供 hex 归一扩展交叉校验:agent 给的地址是否
|
||||
* 在 datasheet 里出现)。
|
||||
*
|
||||
* @param results 检索结果数组。
|
||||
* @returns 去重后的小写地址数组(如 "0x48000000")。
|
||||
*/
|
||||
export function extractAddresses(results: SearchResult[]): string[] {
|
||||
const set = new Set<string>();
|
||||
for (const r of results) {
|
||||
const matches = r.text.match(HEX_ADDR_RE);
|
||||
if (matches) {
|
||||
for (const m of matches) set.add(m.toLowerCase());
|
||||
}
|
||||
}
|
||||
return [...set];
|
||||
}
|
||||
|
||||
/**
|
||||
* 校验 agent 给的寄存器地址是否在 datasheet 检索结果里出现。
|
||||
*
|
||||
* @param address 待校验的 hex 地址(大小写不敏感)。
|
||||
* @param results datasheet 检索结果数组。
|
||||
* @returns 命中 true;不在 → false(地址未经 datasheet 查证,可能是幻觉,fail-closed)。
|
||||
*/
|
||||
export function verifyAddressInResults(address: string, results: SearchResult[]): boolean {
|
||||
const normalized = address.trim().toLowerCase();
|
||||
if (!normalized) return false;
|
||||
const addrs = extractAddresses(results);
|
||||
return addrs.includes(normalized);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// datasheet_query 工具 + 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/** 全局索引(进程级,跨 tool call 共享)。 */
|
||||
let globalIndex: DatasheetIndex | null = null;
|
||||
|
||||
/**
|
||||
* datasheet-rag 扩展装配。
|
||||
*
|
||||
* - 注册 datasheet_query 检索工具(promptGuidelines 注入"寄存器地址必须查证不得靠记忆")
|
||||
* - read .pdf 拦截(缺陷 #2 缓解:read 不支持 PDF,提示改用 datasheet_query)
|
||||
* - 注册 /dsrag-index 命令(pi.exec pdftotext 抽页 → chunkPdf → buildIndex/mergeIndex)
|
||||
* - session_start 记录扩展已加载与索引状态
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*
|
||||
* @param pi pi 扩展 API。
|
||||
*/
|
||||
export default async function datasheetRagExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
// ---- ① datasheet_query 检索工具 ----
|
||||
const datasheetQueryTool = defineTool({
|
||||
name: "datasheet_query",
|
||||
label: "Datasheet Query",
|
||||
description:
|
||||
"Search the indexed datasheet / register manual (RM0090, device-tree, kernel headers) for exact " +
|
||||
"register addresses, bit offsets, and reset values. Register addresses and bit fields MUST be " +
|
||||
"verified through this tool — never inferred from memory (hallucinated addresses brick boards).",
|
||||
promptSnippet: "Query datasheet/register manual for exact addresses and bit fields",
|
||||
promptGuidelines: [
|
||||
"寄存器地址/位偏移/复位值必须通过 datasheet_query 工具查证,不得凭记忆推断。",
|
||||
"Register addresses, bit offsets, and reset values MUST be verified via the datasheet_query tool — never from memory.",
|
||||
],
|
||||
parameters: Type.Object(
|
||||
{
|
||||
query: Type.String({
|
||||
description: "Search term, e.g. 'GPIOA_BASE address' or 'RCC_AHB1ENR bit 0'",
|
||||
}),
|
||||
docPath: Type.Optional(
|
||||
Type.String({
|
||||
description: "Limit search to this document path. If omitted, search all indexed docs.",
|
||||
}),
|
||||
),
|
||||
topK: Type.Optional(
|
||||
Type.Number({ description: "Max number of passages to return (default 5)." }),
|
||||
),
|
||||
page: Type.Optional(
|
||||
Type.Number({ description: "Limit search to this page number." }),
|
||||
),
|
||||
},
|
||||
{
|
||||
description:
|
||||
"Query the indexed datasheet/register manual for exact addresses, bit fields, and reset values.",
|
||||
},
|
||||
),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as {
|
||||
query: string;
|
||||
docPath?: string;
|
||||
topK?: number;
|
||||
page?: number;
|
||||
};
|
||||
const query = p.query?.trim();
|
||||
if (!query) {
|
||||
return {
|
||||
content: [{ type: "text", text: "Error: query parameter is required." }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
// fail-closed:索引未建 → 提示先 /dsrag-index
|
||||
if (!globalIndex) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: "No datasheet index loaded. Use the /dsrag-index <pdfPath> command to index a datasheet first.",
|
||||
},
|
||||
],
|
||||
isError: false,
|
||||
};
|
||||
}
|
||||
const results = search(globalIndex, query, p.topK ?? 5, {
|
||||
filter: { docPath: p.docPath, page: p.page },
|
||||
});
|
||||
const context = formatContext(results, query);
|
||||
return {
|
||||
content: [{ type: "text", text: context }],
|
||||
details: { resultCount: results.length, query },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(datasheetQueryTool);
|
||||
|
||||
// ---- ② read .pdf 拦截:缺陷 #2 缓解 ----
|
||||
pi.on("tool_result", (event, _ctx: ExtensionContext) => {
|
||||
if (event.toolName !== "read") return undefined;
|
||||
const input = event.input as { path?: string; filePath?: string };
|
||||
const path = input.path ?? input.filePath ?? "";
|
||||
if (/\.pdf$/i.test(path)) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: "PDF files cannot be read directly. Use the `datasheet_query` tool to search this document, " +
|
||||
"or run /dsrag-index to index it first.",
|
||||
},
|
||||
],
|
||||
isError: false,
|
||||
};
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- session_start:记录扩展已加载 ----
|
||||
pi.on("session_start", () => {
|
||||
pi.appendEntry("dsrag:loaded", {
|
||||
indexed: globalIndex !== null,
|
||||
chunkCount: globalIndex?.size ?? 0,
|
||||
docPaths: globalIndex ? [...globalIndex.docPaths] : [],
|
||||
});
|
||||
});
|
||||
|
||||
// ---- ③ 注册 /dsrag-index 命令:索引一个 datasheet PDF ----
|
||||
pi.registerCommand("dsrag-index", {
|
||||
description: "Index a datasheet PDF for RAG search. Usage: /dsrag-index <pdfPath>",
|
||||
async handler(args, ctx) {
|
||||
const pdfPath = args.trim();
|
||||
if (!pdfPath) {
|
||||
ctx.ui.notify("[datasheet-rag] Usage: /dsrag-index <pdfPath>", "error");
|
||||
return;
|
||||
}
|
||||
ctx.ui.notify(`[datasheet-rag] Indexing ${pdfPath}...`, "info");
|
||||
let pages: PdfPage[];
|
||||
try {
|
||||
const result = await pi.exec("pdftotext", ["-layout", pdfPath, "-"], {
|
||||
timeout: 60000,
|
||||
});
|
||||
if (result.exitCode !== 0 || !result.stdout) {
|
||||
ctx.ui.notify(
|
||||
`[datasheet-rag] Failed to extract text from ${pdfPath}. Is pdftotext installed?`,
|
||||
"error",
|
||||
);
|
||||
return;
|
||||
}
|
||||
pages = pagesFromPdftotextOutput(result.stdout, pdfPath);
|
||||
} catch {
|
||||
// pdftotext 不存在或超时 → fail-closed 空结果
|
||||
ctx.ui.notify(
|
||||
`[datasheet-rag] pdftotext unavailable for ${pdfPath}. Install poppler-utils.`,
|
||||
"error",
|
||||
);
|
||||
return;
|
||||
}
|
||||
if (pages.length === 0) {
|
||||
ctx.ui.notify(
|
||||
`[datasheet-rag] No extractable text from ${pdfPath} (scanned PDF?).`,
|
||||
"error",
|
||||
);
|
||||
return;
|
||||
}
|
||||
const chunks = chunkPdf(pages);
|
||||
const newIndex = buildIndex(chunks);
|
||||
// 合并已有索引(支持多文档)
|
||||
if (globalIndex) {
|
||||
mergeIndex(globalIndex, newIndex);
|
||||
} else {
|
||||
globalIndex = newIndex;
|
||||
}
|
||||
ctx.ui.notify(
|
||||
`[datasheet-rag] Indexed ${pages.length} pages / ${chunks.length} chunks from ${pdfPath}`,
|
||||
"info",
|
||||
);
|
||||
pi.appendEntry("dsrag:indexed", { pdfPath, pages: pages.length, chunks: chunks.length });
|
||||
},
|
||||
});
|
||||
}
|
||||
1065
src/extensions/device-tree.ts
Normal file
1065
src/extensions/device-tree.ts
Normal file
File diff suppressed because it is too large
Load Diff
413
src/extensions/edit-strict.ts
Normal file
413
src/extensions/edit-strict.ts
Normal file
@ -0,0 +1,413 @@
|
||||
/**
|
||||
* @module edit-strict
|
||||
*
|
||||
* edit 精确匹配安全模式扩展 —— 治嵌入式开发场景缺陷 #9
|
||||
* (edit fuzzy 匹配 .dts/.ld 误匹配 + 归一化破坏对齐空白)。
|
||||
*
|
||||
* 场景锚定:设备树 `.dts` 节点结构高度重复(`&i2c0{...}`/`&i2c1{...}`),链接脚本
|
||||
* `.ld` 段名相似(`.text`/`.text.init`/`.text.startup`)。agent 给的 oldText 不够长时
|
||||
* fuzzy 易错配到相邻节点——改错节点 = 外设静默不枚举(dmesg 无报错),调试极难。
|
||||
* fuzzy 返回归一化 content 还会把未改行的对齐空白重写,破坏 .dts/.ld 的列对齐。
|
||||
*
|
||||
* 形态:tool_call 钩子,对内置 edit 工具做 fail-closed 预校验。
|
||||
* - .dts/.dtsi/.ld/.lds/.sct/.icf 文件自动走 strict(exact)
|
||||
* - 显式 strict:true 对任意文件生效
|
||||
* - strict 时逐条 edit 用 computeEdit(exact) 校验:oldText 必须唯一精确命中,
|
||||
* 否则 block,提示 agent 加长 oldText 或先用 'dt parse' 定位节点 label
|
||||
* - 校验通过则放行——pi 的 edit 走 exact 路径(indexOf 命中),不进 fuzzy 归一,
|
||||
* 未改行对齐空白零变化
|
||||
*
|
||||
* 见 Docs/F03_edit精确匹配安全模式.md。逻辑内联为命名导出,tests 直接单测,无需 pi 运行时。
|
||||
* 顶层仅 `import type`(esbuild 擦除),defineTool/Type 不在本扩展使用;pi.on/pi.appendEntry
|
||||
* 全在工厂体内,工厂为 async 以便未来动态 import 真运行时(此处仅用注入的 pi 对象)。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
||||
|
||||
// ============================================================================
|
||||
// 类型
|
||||
// ============================================================================
|
||||
|
||||
/** edit 匹配模式:exact=唯一精确匹配否则报错;fuzzy=exact 命中则用原文,否则归一化兜底。 */
|
||||
export type EditMode = "exact" | "fuzzy";
|
||||
|
||||
/** 单次匹配/替换记录。 */
|
||||
export interface EditReplacement {
|
||||
/** 匹配在 oldContent 中的起始偏移(字节级,基于原文)。 */
|
||||
index: number;
|
||||
/** 被替换的原文长度。 */
|
||||
length: number;
|
||||
/** 命中此匹配的模式。 */
|
||||
mode: EditMode;
|
||||
}
|
||||
|
||||
/** computeEdit 的返回。fail-closed:出错时 newContent=原文、replacements=空、error 填文案。 */
|
||||
export interface ComputeEditResult {
|
||||
/** 替换后的内容;出错时为原文不变(fail-closed)。 */
|
||||
newContent: string;
|
||||
/** 匹配/替换记录;出错时为空。 */
|
||||
replacements: EditReplacement[];
|
||||
/** fail-closed 错误文案;undefined 表示成功。 */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
/** 归一化结果(带原文位置映射,替换基于原文不破坏对齐空白)。 */
|
||||
export interface NormalizedWithMap {
|
||||
/** 归一化后的文本。 */
|
||||
text: string;
|
||||
/** map[i] = 归一化文本第 i 个字符在原文中的偏移。 */
|
||||
map: number[];
|
||||
}
|
||||
|
||||
/** 单条 edit 操作(edit 工具 input.edits[] 的子集)。 */
|
||||
export interface EditOp {
|
||||
/** 被替换的原文片段。 */
|
||||
oldText?: string;
|
||||
/** 替换为。 */
|
||||
newText?: string;
|
||||
}
|
||||
|
||||
/** edit 链预校验结果。fail-closed:出错时 content=原文不动、error 填文案。 */
|
||||
export interface EditChainResult {
|
||||
/** 校验通过=逐条替换后的内容;出错=原文不动。 */
|
||||
content: string;
|
||||
/** fail-closed 错误文案;undefined 表示全部通过。 */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 文件类型自动门(扩展层用)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 这些扩展名高度结构化、节点/段名重复(.dts 的 &i2c0/&i2c1、.ld 的
|
||||
* .text/.text.init/.text.startup),fuzzy 错配=外设静默不枚举/段错位。
|
||||
* 扩展层对它们默认走 strict(exact)。
|
||||
*/
|
||||
export const STRICT_BY_DEFAULT_EXTENSIONS = [
|
||||
".dts",
|
||||
".dtsi",
|
||||
".ld",
|
||||
".lds",
|
||||
".sct",
|
||||
".icf",
|
||||
];
|
||||
|
||||
/**
|
||||
* 判断路径是否应默认走 strict(exact)模式。
|
||||
*
|
||||
* @param path 文件路径。
|
||||
* @returns 扩展名命中自动门返回 true。
|
||||
*/
|
||||
export function isStrictByDefault(path: string): boolean {
|
||||
const lower = path.toLowerCase();
|
||||
return STRICT_BY_DEFAULT_EXTENSIONS.some((ext) => lower.endsWith(ext));
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// exact 计数(非重叠)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 非重叠地统计 needle 在 haystack 中的精确出现次数。
|
||||
* 空 needle 返回 0(由 computeEdit 的空 oldString 门兜底)。
|
||||
*
|
||||
* @param haystack 原文。
|
||||
* @param needle 待计数片段。
|
||||
* @returns 非重叠出现次数。
|
||||
*/
|
||||
export function countOccurrences(haystack: string, needle: string): number {
|
||||
if (needle.length === 0) return 0;
|
||||
let count = 0;
|
||||
let i = 0;
|
||||
while ((i = haystack.indexOf(needle, i)) !== -1) {
|
||||
count++;
|
||||
i += needle.length;
|
||||
}
|
||||
return count;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 归一化(带位置映射,替换基于原文不破坏对齐空白)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 智能 quotes / dashes / nbsp → ASCII。1:1 字符替换,保位置映射干净。
|
||||
* 不做 NFKC(会膨胀/收缩破坏映射);trimEnd 仅在行尾移除(移除的字符不进归一化文本)。
|
||||
*/
|
||||
const SMART_CHAR_MAP: Record<string, string> = {
|
||||
"‘": "'", // left single quote
|
||||
"’": "'", // right single quote
|
||||
"“": '"', // left double quote
|
||||
"”": '"', // right double quote
|
||||
"–": "-", // en dash
|
||||
"—": "-", // em dash
|
||||
" ": " ", // nbsp
|
||||
};
|
||||
|
||||
/**
|
||||
* 归一化用于 fuzzy 匹配:每行做智能字符替换 + trimEnd(移除行尾空白),
|
||||
* 换行保留。返回归一化文本 + 归一化字符→原文偏移映射表。
|
||||
*
|
||||
* trimEnd 是治"agent 的 oldText 无尾随空格而原文有"的场景——让 fuzzy 能跨尾随空白差异命中。
|
||||
* 关键:替换发生在原文(靠 map 回映位置),未改行的对齐空白零变化(治缺陷 #9 的归一化破坏)。
|
||||
*
|
||||
* @param input 原文。
|
||||
* @returns 归一化文本 + 位置映射。
|
||||
*/
|
||||
export function normalizeForFuzzyMatch(input: string): NormalizedWithMap {
|
||||
const outChars: string[] = [];
|
||||
const map: number[] = [];
|
||||
let lineBuf: Array<{ ch: string; idx: number }> = [];
|
||||
|
||||
const flushLine = () => {
|
||||
// trimEnd:从尾部移除空白(含已替换为 space 的 nbsp)
|
||||
while (lineBuf.length > 0 && /\s/.test(lineBuf[lineBuf.length - 1].ch)) {
|
||||
lineBuf.pop();
|
||||
}
|
||||
for (const e of lineBuf) {
|
||||
outChars.push(e.ch);
|
||||
map.push(e.idx);
|
||||
}
|
||||
lineBuf = [];
|
||||
};
|
||||
|
||||
for (let i = 0; i < input.length; i++) {
|
||||
const ch = input[i];
|
||||
if (ch === "\n") {
|
||||
flushLine();
|
||||
// 换行保留(便于跨行 oldText 匹配)
|
||||
outChars.push("\n");
|
||||
map.push(i);
|
||||
} else {
|
||||
const rep = SMART_CHAR_MAP[ch] ?? ch;
|
||||
lineBuf.push({ ch: rep, idx: i });
|
||||
}
|
||||
}
|
||||
flushLine();
|
||||
return { text: outChars.join(""), map };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 错误文案(复用 pi edit-diff getNotFoundError 语义)
|
||||
// ============================================================================
|
||||
|
||||
function notFoundError(oldString: string): string {
|
||||
return (
|
||||
`oldString not found. The string must match exactly including all whitespace ` +
|
||||
`(got ${JSON.stringify(oldString).slice(0, 60)}…). Make oldText longer/unique or use 'dt parse' to locate the node label first.`
|
||||
);
|
||||
}
|
||||
|
||||
function notUniqueError(count: number): string {
|
||||
return (
|
||||
`oldString matches ${count} times — must be unique. ` +
|
||||
`Include more surrounding context (e.g. the full node label) so oldText matches exactly once.`
|
||||
);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 核心:computeEdit
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* edit 精确匹配安全模式(单条 edit)。
|
||||
*
|
||||
* - exact 模式:要求 oldString 在 oldContent 中**唯一精确**匹配,否则 fail-closed 报错,
|
||||
* 绝不退化为模糊替换(防止 .dts 改错节点致外设静默不枚举)。
|
||||
* - fuzzy 模式:exact 唯一命中时直接用原文替换(零归一);exact 零命中时归一化后找
|
||||
* 最近匹配,但替换基于原文(保留未改行对齐空白)。
|
||||
*
|
||||
* 替换基座恒为原文:未改行的尾随空白逐字节不变(验收标准 §1/§2/§5)。
|
||||
*
|
||||
* @param oldContent 文件原文。
|
||||
* @param oldString 要被替换的片段。
|
||||
* @param newString 替换为。
|
||||
* @param mode 匹配模式,默认 exact。
|
||||
* @returns {newContent, replacements, error?};出错时 newContent=原文、replacements=空。
|
||||
*/
|
||||
export function computeEdit(
|
||||
oldContent: string,
|
||||
oldString: string,
|
||||
newString: string,
|
||||
mode: EditMode = "exact",
|
||||
): ComputeEditResult {
|
||||
// ---- 空 oldString:fail-closed(no-op / 歧义)----
|
||||
if (oldString.length === 0) {
|
||||
return {
|
||||
newContent: oldContent,
|
||||
replacements: [],
|
||||
error: "oldString is empty — refusing no-op/ambiguous replace (fail-closed).",
|
||||
};
|
||||
}
|
||||
|
||||
const exactCount = countOccurrences(oldContent, oldString);
|
||||
|
||||
// ---- exact 模式:唯一精确匹配,否则 fail-closed ----
|
||||
if (mode === "exact") {
|
||||
if (exactCount === 0) {
|
||||
return { newContent: oldContent, replacements: [], error: notFoundError(oldString) };
|
||||
}
|
||||
if (exactCount > 1) {
|
||||
return { newContent: oldContent, replacements: [], error: notUniqueError(exactCount) };
|
||||
}
|
||||
// 唯一精确命中:基于原文替换,零归一,未改行对齐空白零变化
|
||||
const idx = oldContent.indexOf(oldString);
|
||||
const newContent =
|
||||
oldContent.slice(0, idx) + newString + oldContent.slice(idx + oldString.length);
|
||||
return {
|
||||
newContent,
|
||||
replacements: [{ index: idx, length: oldString.length, mode: "exact" }],
|
||||
};
|
||||
}
|
||||
|
||||
// ---- fuzzy 模式 ----
|
||||
// exact 唯一命中 → 直接用原文(mode 标 exact,不触发归一化)
|
||||
if (exactCount === 1) {
|
||||
const idx = oldContent.indexOf(oldString);
|
||||
const newContent =
|
||||
oldContent.slice(0, idx) + newString + oldContent.slice(idx + oldString.length);
|
||||
return {
|
||||
newContent,
|
||||
replacements: [{ index: idx, length: oldString.length, mode: "exact" }],
|
||||
};
|
||||
}
|
||||
// exact 多次命中 → 仍歧义,fuzzy 也 fail-closed(防 .dts 重复节点错配)
|
||||
if (exactCount > 1) {
|
||||
return { newContent: oldContent, replacements: [], error: notUniqueError(exactCount) };
|
||||
}
|
||||
|
||||
// exactCount === 0:归一化兜底(最近匹配)
|
||||
const normContent = normalizeForFuzzyMatch(oldContent);
|
||||
const normOld = normalizeForFuzzyMatch(oldString);
|
||||
|
||||
if (normOld.text.length === 0) {
|
||||
return {
|
||||
newContent: oldContent,
|
||||
replacements: [],
|
||||
error: "oldString normalizes to empty (all whitespace) — cannot match (fail-closed).",
|
||||
};
|
||||
}
|
||||
|
||||
const p = normContent.text.indexOf(normOld.text);
|
||||
if (p === -1) {
|
||||
return {
|
||||
newContent: oldContent,
|
||||
replacements: [],
|
||||
error:
|
||||
`oldString not found even with fuzzy normalization. ` +
|
||||
notFoundError(oldString),
|
||||
};
|
||||
}
|
||||
|
||||
// 命中:回映到原文偏移,替换基于原文(未改行对齐空白零变化)
|
||||
const matchEnd = p + normOld.text.length;
|
||||
const origStart = normContent.map[p]!;
|
||||
const origEnd = normContent.map[matchEnd - 1]! + 1;
|
||||
const newContent = oldContent.slice(0, origStart) + newString + oldContent.slice(origEnd);
|
||||
return {
|
||||
newContent,
|
||||
replacements: [{ index: origStart, length: origEnd - origStart, mode: "fuzzy" }],
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// edit 链预校验(tool_call 钩子的纯逻辑内核,可单测)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 对一组 edit 操作逐条预校验:每条用 computeEdit(mode) 校验,命中则把更新后的 content
|
||||
* 喂下一条。任一条 fail-closed 即立即返回(原文不动)。供 tool_call 钩子做 fail-closed
|
||||
* 预校验——校验通过则放行 pi 的 edit 走 exact indexOf 路径,未改行对齐空白逐字节不变。
|
||||
*
|
||||
* @param content 文件原文。
|
||||
* @param edits edit 操作列表。
|
||||
* @param mode 匹配模式,默认 exact(钩子对 strict 文件恒用 exact)。
|
||||
* @returns {content, error?};出错时 content=原文不动。
|
||||
*/
|
||||
export function validateEditChain(
|
||||
content: string,
|
||||
edits: EditOp[],
|
||||
mode: EditMode = "exact",
|
||||
): EditChainResult {
|
||||
let current = content;
|
||||
for (const edit of edits) {
|
||||
const oldText = edit.oldText ?? "";
|
||||
const newText = edit.newText ?? "";
|
||||
const r = computeEdit(current, oldText, newText, mode);
|
||||
if (r.error) {
|
||||
// fail-closed:原文不动,仅上报错误
|
||||
return { content, error: r.error };
|
||||
}
|
||||
current = r.newContent;
|
||||
}
|
||||
return { content: current };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(tool_call 钩子,全在工厂体内)
|
||||
// ============================================================================
|
||||
|
||||
/** edit 工具 input 的子集(钩子只读 path/edits/strict)。 */
|
||||
interface EditInput {
|
||||
path?: string;
|
||||
edits?: EditOp[];
|
||||
strict?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* edit-strict 扩展装配。
|
||||
*
|
||||
* - tool_call:对 edit 工具做 strict 预校验(.dts/.ld 等自动门 OR 显式 strict:true),
|
||||
* fail-closed 拦截不唯一/不精确的 oldText,提示用 'dt parse' 定位节点 label。
|
||||
* - session_start:登记自动门扩展名,供会话日志追踪。
|
||||
*
|
||||
* 工厂为 async,便于在真 pi 运行时内按需动态 import(当前仅用注入的 pi 对象)。
|
||||
*
|
||||
* @param pi pi 扩展 API。
|
||||
*/
|
||||
export default async function editStrictExtension(pi: ExtensionAPI): Promise<void> {
|
||||
pi.on("tool_call", async (event, _ctx: ExtensionContext) => {
|
||||
if (event.toolName !== "edit") return undefined;
|
||||
|
||||
const input = event.input as EditInput;
|
||||
const path = input.path ?? "";
|
||||
const edits = input.edits ?? [];
|
||||
|
||||
// strict 门:显式 OR 文件类型自动
|
||||
const strict = input.strict === true || isStrictByDefault(path);
|
||||
if (!strict) return undefined; // 非 strict 文件放行,走 pi 默认 fuzzy(不回归)
|
||||
|
||||
// 读文件原文用于预校验(cat 失败则放行让 edit 工具自己报 I/O 错)
|
||||
let content: string;
|
||||
try {
|
||||
const res = await pi.exec("cat", [path]);
|
||||
content = res.stdout;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
// 逐条 edit 用 exact 模式预校验(fail-closed)
|
||||
const result = validateEditChain(content, edits, "exact");
|
||||
if (result.error) {
|
||||
return {
|
||||
block: true,
|
||||
reason:
|
||||
`[edit-strict] (${path}): ${result.error} ` +
|
||||
`For .dts/.ld use 'dt parse' to locate the node label, then pass a unique oldText.`,
|
||||
terminate: false,
|
||||
};
|
||||
}
|
||||
|
||||
// 全部通过:放行。pi 的 edit 走 exact indexOf 路径,不触发 fuzzy 归一,
|
||||
// 未改行对齐空白逐字节不变。
|
||||
return undefined;
|
||||
});
|
||||
|
||||
pi.on("session_start", () => {
|
||||
pi.appendEntry("edit-strict:loaded", {
|
||||
strictExtensions: [...STRICT_BY_DEFAULT_EXTENSIONS],
|
||||
note: ".dts/.ld edits require exact unique oldText (fail-closed, no fuzzy).",
|
||||
});
|
||||
});
|
||||
}
|
||||
551
src/extensions/env-probe.ts
Normal file
551
src/extensions/env-probe.ts
Normal file
@ -0,0 +1,551 @@
|
||||
/**
|
||||
* @module env-probe
|
||||
*
|
||||
* 嵌入式环境自动探针注入扩展 —— 治缺陷 #13:
|
||||
* system prompt 无 env/toolchain/date 注入,交叉编译环境靠 AGENTS.md 手写。
|
||||
*
|
||||
* 场景锚定:交叉编译的关键环境信息——目标板型号(RDK X5 vs S100 vs S600)、
|
||||
* 交叉工具链版本(arm-none-eabi-gcc 10.3 vs 12.2)、内核版本(5.4 vs 6.1)、
|
||||
* dtc 版本(1.6 vs 1.7)——直接决定编译命令、链接选项、API 选择。pi 不注入,
|
||||
* agent 每次都要自己 bash `uname -a` + `arm-none-eabi-gcc --version` +
|
||||
* `cat /proc/device-tree/model` 探,吃 tool call 且易忘。
|
||||
*
|
||||
* 二开范式:before_agent_start 链式注入(零源码改动,参照 examples/extensions/pirate.ts)。
|
||||
* handler 跑探针 → buildEnvPrompt → 返回 { systemPrompt: 原 + 探针块 },
|
||||
* runner.ts:1119-1120 链式更新,agent-session.ts:1255-1256 赋给当轮 LLM 请求。
|
||||
*
|
||||
* 缓存:首次 before_agent_start 跑全部探针 + TTL(默认 300s),后续轮次用缓存(<1ms),
|
||||
* cwd 变化或 TTL 过期重跑。另注册 env_status 工具供 agent 按需查询当前探针快照。
|
||||
*
|
||||
* 纯逻辑(probeEnv/buildEnvPrompt/injectEnvPrompt/stripEnvBlocks/ProbeCacheStore/
|
||||
* makeExecFn/summarizeProbe)全部命名导出,tests 直接单测,不拉 pi 运行时。
|
||||
* defineTool/Type 仅在工厂内动态 import,顶层只有 `import type`(esbuild 擦除),
|
||||
* 故 pi 未构建(模型目录需联网)时 factory 不跑,离线可测。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
|
||||
import type { ExecFn, ExecOpts, ExecResult } from "../shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// 占位符常量(fail-closed:探不到时给占位符而非抛异常)
|
||||
// ============================================================================
|
||||
|
||||
/** 探针整体不可用(dmesg 权限不足/抛异常等)。 */
|
||||
export const PROBE_UNAVAILABLE = "[unavailable]";
|
||||
/** 工具未安装(编译器/dtc/lsusb 缺失)。 */
|
||||
export const PROBE_NOT_INSTALLED = "not installed";
|
||||
/** 命令失败但无更精确分类(uname/cat 失败等)。 */
|
||||
export const PROBE_UNKNOWN = "unknown";
|
||||
/** 当前目录非 git 仓库。 */
|
||||
export const PROBE_NOT_A_GIT_REPO = "not a git repo";
|
||||
/** lsusb 命令不存在。 */
|
||||
export const PROBE_NO_LSUSB = "lsusb not available";
|
||||
|
||||
/** 默认探针缓存 TTL(ms),Docs §2.6 建议 300s。 */
|
||||
export const DEFAULT_TTL_MS = 300_000;
|
||||
/** 默认单条命令超时 ms(Docs §6 风险:execSync 阻塞需 timeout)。 */
|
||||
export const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
|
||||
/** 默认 dmesg 尾部取多少行。 */
|
||||
export const DEFAULT_DMESG_LINES = 20;
|
||||
|
||||
// ============================================================================
|
||||
// 类型
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 单次探针收集到的环境事实。所有字段 fail-closed:
|
||||
* 探不到时给占位符而非抛异常。
|
||||
*/
|
||||
export interface EnvProbe {
|
||||
/** `uname -r` 内核版本,如 "5.4.0-rdk-x5"。 */
|
||||
kernel: string;
|
||||
/** `uname -m` 架构,如 "aarch64"。 */
|
||||
arch: string;
|
||||
/** `/proc/device-tree/model` 板型号,如 "RDK X5"。 */
|
||||
board: string;
|
||||
/** `aarch64-linux-gnu-gcc --version` 首行(Linux 交叉编译器)。 */
|
||||
crossCompiler: string;
|
||||
/** `arm-none-eabi-gcc --version` 首行(裸机交叉编译器)。 */
|
||||
bareMetalCompiler: string;
|
||||
/** `gcc --version` 首行(宿主编译器)。 */
|
||||
hostCompiler: string;
|
||||
/** `dtc --version` 首行(设备树编译器)。 */
|
||||
dtc: string;
|
||||
/** `git rev-parse --short HEAD` 短 hash。 */
|
||||
gitHead: string;
|
||||
/** `lsusb` 摘要。 */
|
||||
usbDevices: string;
|
||||
/** `dmesg` 尾部 N 行(硬件/驱动诊断上下文)。 */
|
||||
dmesgTail: string;
|
||||
/** `/dev/gpiochip*` 列表。 */
|
||||
gpioChips: string[];
|
||||
/** `/dev/i2c-*` 总线列表。 */
|
||||
i2cBuses: string[];
|
||||
}
|
||||
|
||||
/** 探针配置。 */
|
||||
export interface ProbeConfig {
|
||||
/** 单条命令超时 ms,默认 3000。 */
|
||||
timeout?: number;
|
||||
/** dmesg 尾部取多少行,默认 20。 */
|
||||
dmesgLines?: number;
|
||||
/** git 探针的 cwd,默认 undefined(当前目录)。 */
|
||||
cwd?: string;
|
||||
}
|
||||
|
||||
/** 探针缓存条目。 */
|
||||
export interface ProbeCache {
|
||||
probe: EnvProbe;
|
||||
timestamp: number;
|
||||
cwd: string;
|
||||
}
|
||||
|
||||
/** env_status 工具/appendEntry 用的精简快照。 */
|
||||
export interface ProbeSummary {
|
||||
kernel: string;
|
||||
arch: string;
|
||||
board: string;
|
||||
crossCompiler: string;
|
||||
i2cBuses: string[];
|
||||
gpioChips: string[];
|
||||
cached: boolean;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 内部工具(亦命名导出,便于单测)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 取 stdout 首行(编译器/dtc 版本串多行,首行即版本)。
|
||||
* @param stdout 原始 stdout。
|
||||
* @returns 首行 trim 后的字符串。
|
||||
*/
|
||||
export function firstLine(stdout: string): string {
|
||||
const line = stdout.split(/\r?\n/, 1)[0] ?? "";
|
||||
return line.trim();
|
||||
}
|
||||
|
||||
/**
|
||||
* 安全执行单条命令,失败/非零退出返回 fallback(fail-closed,绝不抛)。
|
||||
*
|
||||
* @param exec 注入的执行函数。
|
||||
* @param command 命令名。
|
||||
* @param args 参数数组。
|
||||
* @param opts 透传给 exec 的选项(timeout/cwd/env)。
|
||||
* @param fallback 失败时的占位符。
|
||||
* @param transform stdout 转换(默认 trim)。
|
||||
* @returns 成功且非空则返回转换后的 stdout,否则 fallback。
|
||||
*/
|
||||
export async function safeProbe(
|
||||
exec: ExecFn,
|
||||
command: string,
|
||||
args: string[],
|
||||
opts: ExecOpts | undefined,
|
||||
fallback: string,
|
||||
transform: (stdout: string) => string = (s) => s.trim(),
|
||||
): Promise<string> {
|
||||
try {
|
||||
const res: ExecResult = await exec(command, args, opts);
|
||||
if (res.exitCode !== 0) return fallback;
|
||||
const out = transform(res.stdout);
|
||||
return out.length > 0 ? out : fallback;
|
||||
} catch {
|
||||
return fallback;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 从 `ls -1 /dev/` 的 stdout 过滤出匹配前缀的条目。
|
||||
* @param stdout `ls -1 /dev/` 输出。
|
||||
* @param prefix 条目前缀,如 "gpiochip" / "i2c-"。
|
||||
* @returns 匹配条目数组(已 trim)。
|
||||
*/
|
||||
export function filterDevEntries(stdout: string, prefix: string): string[] {
|
||||
return stdout
|
||||
.split(/\r?\n/)
|
||||
.map((l) => l.trim())
|
||||
.filter((l) => l.startsWith(prefix));
|
||||
}
|
||||
|
||||
/**
|
||||
* 把字符串数组渲染成 prompt 行:空数组 → "none"。
|
||||
* @param items 条目列表。
|
||||
* @returns 逗号分隔串,空列表返回 "none"。
|
||||
*/
|
||||
export function renderList(items: string[]): string {
|
||||
return items.length > 0 ? items.join(", ") : "none";
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// probeEnv — 异步收集环境事实
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 用注入的 ExecFn 跑一组探针命令,收集板/宿主环境事实。
|
||||
*
|
||||
* 每条探针独立容错(fail-closed):命令缺失/超时/非零退出 → 对应字段填占位符,
|
||||
* probeEnv 本身绝不抛异常。
|
||||
*
|
||||
* 顺序执行(嵌入式探针命令数固定 ~10,串行 <500ms,且避免并发 fork 抢资源)。
|
||||
*
|
||||
* @param exec 注入的执行函数(扩展层把 pi.exec 适配成 ExecFn 喂进来)。
|
||||
* @param config 探针配置(超时/dmesg 行数/cwd)。
|
||||
* @returns 环境事实对象,所有字段已 fail-closed 填充。
|
||||
*/
|
||||
export async function probeEnv(exec: ExecFn, config: ProbeConfig = {}): Promise<EnvProbe> {
|
||||
const timeout = config.timeout ?? DEFAULT_PROBE_TIMEOUT_MS;
|
||||
const dmesgLines = config.dmesgLines ?? DEFAULT_DMESG_LINES;
|
||||
const cwd = config.cwd;
|
||||
|
||||
// ---- 内核 / 架构 ----
|
||||
const kernel = await safeProbe(exec, "uname", ["-r"], { timeout }, PROBE_UNKNOWN);
|
||||
const arch = await safeProbe(exec, "uname", ["-m"], { timeout }, PROBE_UNKNOWN);
|
||||
|
||||
// ---- 板型号(非 ARM 板无 /proc/device-tree/model) ----
|
||||
const board = await safeProbe(
|
||||
exec,
|
||||
"cat",
|
||||
["/proc/device-tree/model"],
|
||||
{ timeout },
|
||||
PROBE_UNKNOWN,
|
||||
// 设备树 model 文件无尾换行,trim 即可;可能含 \0
|
||||
(s) => s.replace(/\0/g, "").trim(),
|
||||
);
|
||||
|
||||
// ---- 交叉编译器 ----
|
||||
const crossCompiler = await safeProbe(
|
||||
exec,
|
||||
"aarch64-linux-gnu-gcc",
|
||||
["--version"],
|
||||
{ timeout },
|
||||
PROBE_NOT_INSTALLED,
|
||||
firstLine,
|
||||
);
|
||||
const bareMetalCompiler = await safeProbe(
|
||||
exec,
|
||||
"arm-none-eabi-gcc",
|
||||
["--version"],
|
||||
{ timeout },
|
||||
PROBE_NOT_INSTALLED,
|
||||
firstLine,
|
||||
);
|
||||
|
||||
// ---- 宿主编译器 / dtc ----
|
||||
const hostCompiler = await safeProbe(
|
||||
exec,
|
||||
"gcc",
|
||||
["--version"],
|
||||
{ timeout },
|
||||
PROBE_NOT_INSTALLED,
|
||||
firstLine,
|
||||
);
|
||||
const dtc = await safeProbe(exec, "dtc", ["--version"], { timeout }, PROBE_NOT_INSTALLED, firstLine);
|
||||
|
||||
// ---- git HEAD ----
|
||||
const gitHead = await safeProbe(
|
||||
exec,
|
||||
"git",
|
||||
["rev-parse", "--short", "HEAD"],
|
||||
{ timeout, cwd },
|
||||
PROBE_NOT_A_GIT_REPO,
|
||||
);
|
||||
|
||||
// ---- USB 设备 ----
|
||||
const usbDevices = await safeProbe(exec, "lsusb", [], { timeout }, PROBE_NO_LSUSB, (s) =>
|
||||
s.trim(),
|
||||
);
|
||||
|
||||
// ---- dmesg 尾部 ----
|
||||
let dmesgTail = PROBE_UNAVAILABLE;
|
||||
try {
|
||||
const dres = await exec("dmesg", [], { timeout });
|
||||
if (dres.exitCode === 0) {
|
||||
const lines = dres.stdout.split(/\r?\n/).filter((l) => l.length > 0);
|
||||
dmesgTail = lines.slice(-dmesgLines).join("\n");
|
||||
if (dmesgTail.length === 0) dmesgTail = PROBE_UNAVAILABLE;
|
||||
}
|
||||
} catch {
|
||||
dmesgTail = PROBE_UNAVAILABLE;
|
||||
}
|
||||
|
||||
// ---- GPIO chips / I2C buses(从 /dev/ 列表过滤) ----
|
||||
let gpioChips: string[] = [];
|
||||
let i2cBuses: string[] = [];
|
||||
try {
|
||||
const lres = await exec("ls", ["-1", "/dev/"], { timeout });
|
||||
if (lres.exitCode === 0) {
|
||||
gpioChips = filterDevEntries(lres.stdout, "gpiochip");
|
||||
i2cBuses = filterDevEntries(lres.stdout, "i2c-");
|
||||
}
|
||||
} catch {
|
||||
// /dev/ 不可读或 ls 不存在 → 空列表(fail-closed)
|
||||
}
|
||||
|
||||
return {
|
||||
kernel,
|
||||
arch,
|
||||
board,
|
||||
crossCompiler,
|
||||
bareMetalCompiler,
|
||||
hostCompiler,
|
||||
dtc,
|
||||
gitHead,
|
||||
usbDevices,
|
||||
dmesgTail,
|
||||
gpioChips,
|
||||
i2cBuses,
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// buildEnvPrompt — 拼注入片段
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把 EnvProbe 渲染成追加到 systemPrompt 尾部的 <embedded_environment> 块。
|
||||
* agent 看到这段即知板/工具链事实,无需自己 bash 探。
|
||||
* @param probe 环境事实对象。
|
||||
* @returns 多行 prompt 片段,含开闭合标签。
|
||||
*/
|
||||
export function buildEnvPrompt(probe: EnvProbe): string {
|
||||
const lines: string[] = [];
|
||||
lines.push("<embedded_environment>");
|
||||
lines.push("Board/Host environment (auto-probed, do not edit):");
|
||||
lines.push(`- Kernel: ${probe.kernel} / ${probe.arch}`);
|
||||
lines.push(`- Board model: ${probe.board}`);
|
||||
lines.push(`- Cross-compiler (aarch64-linux): ${probe.crossCompiler}`);
|
||||
lines.push(`- Cross-compiler (bare-metal): ${probe.bareMetalCompiler}`);
|
||||
lines.push(`- Device tree compiler: ${probe.dtc}`);
|
||||
lines.push(`- Host compiler: ${probe.hostCompiler}`);
|
||||
lines.push(`- Git HEAD: ${probe.gitHead}`);
|
||||
lines.push(`- USB devices: ${probe.usbDevices}`);
|
||||
lines.push(`- GPIO chips: ${renderList(probe.gpioChips)}`);
|
||||
lines.push(`- I2C buses: ${renderList(probe.i2cBuses)}`);
|
||||
lines.push("- dmesg tail:");
|
||||
// dmesg 尾部缩进两格,保持块内层级
|
||||
const dmesgBlock =
|
||||
probe.dmesgTail === PROBE_UNAVAILABLE
|
||||
? PROBE_UNAVAILABLE
|
||||
: probe.dmesgTail
|
||||
.split(/\r?\n/)
|
||||
.map((l) => ` ${l}`)
|
||||
.join("\n");
|
||||
lines.push(dmesgBlock);
|
||||
lines.push("</embedded_environment>");
|
||||
return lines.join("\n");
|
||||
}
|
||||
|
||||
/**
|
||||
* 剥离所有 <embedded_environment>...</embedded_environment> 块,折叠多余空行。
|
||||
* @param systemPrompt 原始 systemPrompt。
|
||||
* @returns 剥离嵌入块后的 systemPrompt(trimEnd)。
|
||||
*/
|
||||
export function stripEnvBlocks(systemPrompt: string): string {
|
||||
const re = /<embedded_environment>[\s\S]*?<\/embedded_environment>/g;
|
||||
return systemPrompt.replace(re, "").replace(/\n{3,}/g, "\n\n").trimEnd();
|
||||
}
|
||||
|
||||
/**
|
||||
* 把探针块追加到 systemPrompt 尾部(runner 链式更新)。
|
||||
* 若 systemPrompt 已含 <embedded_environment>(重入/链式叠加),先剥离旧块再追加新块,
|
||||
* 避免重复堆积。
|
||||
* @param systemPrompt 当前 systemPrompt。
|
||||
* @param probe 环境事实对象。
|
||||
* @returns 新 systemPrompt = 剥离旧块后的原文 + 探针块。
|
||||
*/
|
||||
export function injectEnvPrompt(systemPrompt: string, probe: EnvProbe): string {
|
||||
const block = buildEnvPrompt(probe);
|
||||
const base = stripEnvBlocks(systemPrompt);
|
||||
return base + "\n\n" + block;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ProbeCacheStore — 会话级 TTL 缓存
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 探针缓存存储。会话级单例,跨 before_agent_start 调用共享。
|
||||
* 失效条件:TTL 过期 或 cwd 变化。
|
||||
*/
|
||||
export class ProbeCacheStore {
|
||||
private entry: ProbeCache | null = null;
|
||||
|
||||
/**
|
||||
* 取缓存有效则返回 probe,否则返回 null。
|
||||
* @param ttlMs 缓存 TTL(ms)。
|
||||
* @param cwd 当前工作目录(变化即失效)。
|
||||
* @returns 命中的 probe 或 null。
|
||||
*/
|
||||
get(ttlMs: number, cwd: string): EnvProbe | null {
|
||||
if (!this.entry) return null;
|
||||
const now = Date.now();
|
||||
if (now - this.entry.timestamp > ttlMs) return null;
|
||||
if (this.entry.cwd !== cwd) return null;
|
||||
return this.entry.probe;
|
||||
}
|
||||
|
||||
/**
|
||||
* 写入缓存条目。
|
||||
* @param probe 环境事实对象。
|
||||
* @param cwd 当前工作目录。
|
||||
*/
|
||||
set(probe: EnvProbe, cwd: string): void {
|
||||
this.entry = { probe, timestamp: Date.now(), cwd };
|
||||
}
|
||||
|
||||
/** 清空缓存(板换/重启后强制重探)。 */
|
||||
clear(): void {
|
||||
this.entry = null;
|
||||
}
|
||||
|
||||
/** 是否已有缓存条目(不论是否过期)。 */
|
||||
has(): boolean {
|
||||
return this.entry !== null;
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// makeExecFn — pi.exec → ExecFn 适配
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把 pi.exec(签名与 ExecFn 同构)适配成逻辑层 ExecFn,并补默认 timeout。
|
||||
*
|
||||
* pi.exec 返回 { stdout, stderr, exitCode, signal? },与 ExecResult 同构。
|
||||
* 此函数纯逻辑:接受任何同构 exec 函数,不依赖 pi 运行时,故可单测。
|
||||
*
|
||||
* @param exec pi.exec 或同构执行函数。
|
||||
* @param defaultTimeout 默认超时 ms,opts.timeout 优先。
|
||||
* @returns ExecFn。
|
||||
*/
|
||||
export function makeExecFn(
|
||||
exec: (command: string, args: string[], opts?: ExecOpts) => Promise<ExecResult>,
|
||||
defaultTimeout: number,
|
||||
): ExecFn {
|
||||
return async (command: string, args: string[], opts?: ExecOpts): Promise<ExecResult> => {
|
||||
const options: ExecOpts = { timeout: defaultTimeout, ...opts };
|
||||
return exec(command, args, options);
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 把 EnvProbe 渲染成 env_status 工具返回 + appendEntry 用的精简快照。
|
||||
* @param probe 环境事实对象。
|
||||
* @param cached 是否来自缓存。
|
||||
* @returns 精简快照。
|
||||
*/
|
||||
export function summarizeProbe(probe: EnvProbe, cached: boolean): ProbeSummary {
|
||||
return {
|
||||
kernel: probe.kernel,
|
||||
arch: probe.arch,
|
||||
board: probe.board,
|
||||
crossCompiler: probe.crossCompiler,
|
||||
i2cBuses: probe.i2cBuses,
|
||||
gpioChips: probe.gpioChips,
|
||||
cached,
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* env-probe 扩展装配。
|
||||
*
|
||||
* - before_agent_start:跑探针(缓存命中则不 fork)→ injectEnvPrompt 链式注入 systemPrompt
|
||||
* - env_status 工具:agent 按需查询当前探针快照
|
||||
* - session_start:记录适配器加载事件
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
* 缓存 TTL 由环境变量 PI_ENV_PROBE_TTL_MS 覆盖(默认 300s)。
|
||||
*/
|
||||
export default async function envProbeExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
const cache = new ProbeCacheStore();
|
||||
const ttlMs = Number(process.env.PI_ENV_PROBE_TTL_MS ?? DEFAULT_TTL_MS);
|
||||
const probeTimeout = Number(process.env.PI_ENV_PROBE_TIMEOUT_MS ?? DEFAULT_PROBE_TIMEOUT_MS);
|
||||
|
||||
// 内部:取有效 probe(缓存命中不 fork,否则跑探针并写缓存)
|
||||
async function getProbe(cwd: string): Promise<EnvProbe | null> {
|
||||
const cached = cache.get(ttlMs, cwd);
|
||||
if (cached) return cached;
|
||||
const exec = makeExecFn(pi.exec.bind(pi), probeTimeout);
|
||||
const config: ProbeConfig = { timeout: probeTimeout, dmesgLines: DEFAULT_DMESG_LINES, cwd };
|
||||
try {
|
||||
const probe = await probeEnv(exec, config);
|
||||
cache.set(probe, cwd);
|
||||
return probe;
|
||||
} catch {
|
||||
// 兜底:probeEnv 内部已容错,此 catch 纯防御性
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
const envStatusTool = defineTool({
|
||||
name: "env_status",
|
||||
label: "Environment Status",
|
||||
description:
|
||||
"Query the auto-probed board/host environment (kernel, arch, board model, cross-compiler, " +
|
||||
"GPIO chips, I2C buses). Use this when you need target/toolchain facts instead of running bash probes.",
|
||||
promptSnippet: "Check auto-probed board/toolchain environment facts",
|
||||
parameters: Type.Object({}, { description: "No parameters." }),
|
||||
executionMode: "sequential",
|
||||
async execute(_toolCallId, _params, _signal, _onUpdate, ctx: ExtensionContext) {
|
||||
const cwd = ctx.cwd ?? process.cwd();
|
||||
const probe = await getProbe(cwd);
|
||||
if (!probe) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify({ error: "environment probe failed (fail-closed)", cached: false }, null, 2),
|
||||
},
|
||||
],
|
||||
details: { armed: true, ok: false },
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify(summarizeProbe(probe, cache.has()), null, 2),
|
||||
},
|
||||
],
|
||||
details: { armed: true, ok: true },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(envStatusTool);
|
||||
|
||||
pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
|
||||
const systemPrompt = event.systemPrompt ?? "";
|
||||
const cwd = ctx.cwd ?? process.cwd();
|
||||
|
||||
const probe = await getProbe(cwd);
|
||||
if (!probe) {
|
||||
// fail-closed:探针全失败时不改 systemPrompt(不阻断 agent)
|
||||
return undefined;
|
||||
}
|
||||
|
||||
const isCached = cache.has();
|
||||
pi.appendEntry("env-probe:collected", summarizeProbe(probe, isCached));
|
||||
|
||||
// 链式注入:剥离旧块 + 追加新块(runner 链式更新)
|
||||
const next = injectEnvPrompt(systemPrompt, probe);
|
||||
return { systemPrompt: next };
|
||||
});
|
||||
|
||||
pi.on("session_start", () => {
|
||||
// 会话重载/换板时清缓存,强制下轮重探
|
||||
cache.clear();
|
||||
pi.appendEntry("env-probe:loaded", {
|
||||
ttlMs,
|
||||
probeTimeoutMs: probeTimeout,
|
||||
});
|
||||
});
|
||||
}
|
||||
929
src/extensions/flash.ts
Normal file
929
src/extensions/flash.ts
Normal file
@ -0,0 +1,929 @@
|
||||
/**
|
||||
* @module flash
|
||||
*
|
||||
* 安全烧录域扩展 —— 治嵌入式开发场景下破坏性命令裸跑缺陷
|
||||
* (dd 写错盘=砖板/宿主毁,物理不可逆)。
|
||||
*
|
||||
* 三段式安全流程(纯逻辑,ExecFn 注入,绝不依赖真实硬件):
|
||||
* ① planFlash(method, image, target, opts) → FlashPlanEx 按 method 构建命令序列
|
||||
* ② dryRun(plan, execFn) → DryRunResult 模拟:确认 target 存在、
|
||||
* 不在根盘、sha256 预计算(dd)/ 设备在线(fastboot/dfu/openocd)
|
||||
* ③ verifyFlash(plan, execFn) → VerifyResult 烧后 sha256 校验(dd)
|
||||
* 或 exitCode 校验(openocd verify_image / fastboot getvar / dfu -l)
|
||||
*
|
||||
* fail-closed 语义:
|
||||
* - dry_run 默认 true(第一次必须先 dry-run 再写真写)
|
||||
* - target 是宿主系统盘(挂载了 / /boot /home 等)或根分区 → 拒绝
|
||||
* - target 不存在 → 拒绝
|
||||
* - offset 越过镜像大小 → 拒绝
|
||||
* - 烧后 sha256 不匹配 → VERIFY FAILED
|
||||
*
|
||||
* 扩展层把 ①②③ 接到 pi.exec + flash 工具,注册 `flash` 工具,
|
||||
* executionMode:"sequential" 确保烧录不与其他工具并行。
|
||||
*
|
||||
* 与 safety-gate 联动:safety-gate 的 tool_call 钩子拦截裸 `dd of=/dev/` →
|
||||
* 收束到 flash 工具内;flash 工具自身走 pi.exec(不经 bash 工具),不被 safety-gate 拦。
|
||||
*
|
||||
* 见 Docs/F13_安全烧录工具.md。逻辑内联为命名导出,tests 直接单测,无需 pi 运行时。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
ExecOptions,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
import type { ExecFn, FlashMethod, FlashPlan } from "../shared/types.js";
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
// 注:defineTool / Type 仅在 factory 内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除)+ node:crypto(Node 内置,非 pi 依赖),
|
||||
// 故 tests 直接 import 本模块的纯逻辑函数不会触发 pi 解析——离线可测。
|
||||
// pi 未构建(模型目录需联网)时 factory 不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// 类型(FlashMethod/FlashPlan 复用 shared/types.ts)
|
||||
// ============================================================================
|
||||
|
||||
/** 扩展 FlashPlan:dryRun 填充的镜像大小 / 偏移 / 块数(verify 用)。 */
|
||||
export interface FlashPlanEx extends FlashPlan {
|
||||
/** 镜像字节数(dryRun 经 stat 填充,verify dd 读回 count 用)。 */
|
||||
imageSizeBytes?: number;
|
||||
/** dd seek= 的字节偏移(解析自 opts.offset,十进制或 0x hex)。 */
|
||||
offsetBytes?: number;
|
||||
/** dd bs=4M 块数(ceil(imageSizeBytes / 4MiB)),verify 读回 count。 */
|
||||
blockCount?: number;
|
||||
}
|
||||
|
||||
/** planFlash 的可选参数。 */
|
||||
export interface FlashPlanOptions {
|
||||
/** dd seek= 字节偏移(十进制或 0x hex 字符串)。 */
|
||||
offset?: string;
|
||||
/** fastboot 分区名(如 boot)或 dfu alt-setting。 */
|
||||
partition?: string;
|
||||
/** 是否先 dry-run(默认 true,fail-closed)。扩展层据此编排。 */
|
||||
dryRun?: boolean;
|
||||
/** 烧后是否 verify(默认 true)。 */
|
||||
verify?: boolean;
|
||||
}
|
||||
|
||||
/** dryRun 结果。 */
|
||||
export interface DryRunResult {
|
||||
ok: boolean;
|
||||
reason?: string;
|
||||
plan: FlashPlanEx;
|
||||
/** target 设备节点是否存在于 lsblk 输出。 */
|
||||
targetExists: boolean;
|
||||
/** target 是否挂载了根/启动分区(→ 拒绝)。 */
|
||||
isRootDisk: boolean;
|
||||
/** dry-run 阶段实际执行的探测命令(审计用)。 */
|
||||
probeCommands: string[];
|
||||
/** sha256sum 镜像原始输出(dd 方法)。 */
|
||||
sha256sumOutput?: string;
|
||||
}
|
||||
|
||||
/** verifyFlash 结果。 */
|
||||
export interface VerifyResult {
|
||||
ok: boolean;
|
||||
expected?: string;
|
||||
actual?: string;
|
||||
reason?: string;
|
||||
/** verify 阶段执行的命令。 */
|
||||
verifyCommand?: string;
|
||||
}
|
||||
|
||||
/** lsblk 行解析结果。 */
|
||||
export interface LsblkRow {
|
||||
name: string;
|
||||
size: number;
|
||||
type: string;
|
||||
mountpoint: string;
|
||||
}
|
||||
|
||||
/** runFlash 三段式编排结果。 */
|
||||
export interface RunFlashResult {
|
||||
dryRun: DryRunResult;
|
||||
/** 是否真正执行了写命令。 */
|
||||
written: boolean;
|
||||
/** 写命令执行结果(每条 command 的 exitCode)。 */
|
||||
writeExitCodes: number[];
|
||||
verify?: VerifyResult;
|
||||
/** 总体是否成功(dryRun ok + 写全 0 + verify ok)。 */
|
||||
ok: boolean;
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 常量
|
||||
// ============================================================================
|
||||
|
||||
/** dd 块大小(与文档一致 bs=4M)。 */
|
||||
const DD_BLOCK_SIZE = 4 * 1024 * 1024;
|
||||
|
||||
/** 视为宿主系统盘的挂载点(命中任一即拒绝写)。 */
|
||||
export const ROOT_MOUNTPOINTS = new Set([
|
||||
"/",
|
||||
"/boot",
|
||||
"/boot/efi",
|
||||
"/home",
|
||||
"/var",
|
||||
"/usr",
|
||||
"/swap",
|
||||
"[SWAP]",
|
||||
]);
|
||||
|
||||
/** lsblk 树形输出前缀字符(├─ └─ │ ─ 等非 ASCII 盒绘字符)。 */
|
||||
const LSBLK_TREE_CHARS = /[─-╼│├└─\s]+/;
|
||||
|
||||
// ============================================================================
|
||||
// ① planFlash — 按 method 构建命令序列
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把 offset 字符串(十进制或 0x hex)解析成字节数。
|
||||
*
|
||||
* @param offset 十进制或 0x hex 字符串,undefined/空 → 0。
|
||||
* @returns 字节数;无法解析返回 null。
|
||||
*/
|
||||
export function parseOffset(offset: string | undefined): number | null {
|
||||
if (offset === undefined || offset === "") return 0;
|
||||
const trimmed = offset.trim();
|
||||
if (/^0x[0-9a-fA-F]+$/.test(trimmed)) {
|
||||
const n = Number(trimmed);
|
||||
if (Number.isFinite(n) && n >= 0) return n;
|
||||
return null;
|
||||
}
|
||||
if (/^\d+$/.test(trimmed)) {
|
||||
// 用 BigInt 防大数失真,再回落到 number 范围
|
||||
try {
|
||||
const big = BigInt(trimmed);
|
||||
if (big > BigInt(Number.MAX_SAFE_INTEGER)) {
|
||||
return Number.MAX_SAFE_INTEGER; // 上限夹断,足够 dd 偏移语义
|
||||
}
|
||||
return Number(big);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 由 method + image + target + opts 构建烧录计划。
|
||||
*
|
||||
* - dd: `dd if=<image> of=<target> bs=4M conv=fsync [seek=<blocks>]`
|
||||
* - fastboot: `fastboot flash <partition> <image>`(partition 缺省则 `fastboot flash <image>`)
|
||||
* - dfu: `dfu-util -d <target> [-a <alt>] -D <image>`(target = vid:pid)
|
||||
* - openocd: `openocd -f <target> -c "program <image> verify reset exit"`(target = cfg 路径)
|
||||
*
|
||||
* 纯构建,不做 target 存在性/根盘校验(那是 dryRun 的职责)。
|
||||
* 仅做基本入参校验(method 合法、image/target 非空)。
|
||||
*
|
||||
* @param method 烧录方法。
|
||||
* @param image 镜像/载荷文件路径。
|
||||
* @param target 目标设备节点 / 串号 / cfg 路径。
|
||||
* @param opts 可选参数(offset/partition/dryRun/verify)。
|
||||
* @returns FlashPlanEx。
|
||||
*/
|
||||
export function planFlash(
|
||||
method: FlashMethod,
|
||||
image: string,
|
||||
target: string,
|
||||
opts: FlashPlanOptions = {},
|
||||
): FlashPlanEx {
|
||||
if (!method || !["dd", "fastboot", "dfu", "openocd"].includes(method)) {
|
||||
throw new Error(`flash: unsupported method "${method}"`);
|
||||
}
|
||||
if (!image || image.trim() === "") {
|
||||
throw new Error("flash: image path required");
|
||||
}
|
||||
if (!target || target.trim() === "") {
|
||||
throw new Error("flash: target required");
|
||||
}
|
||||
|
||||
const commands: string[] = [];
|
||||
let offsetBytes: number | undefined;
|
||||
|
||||
switch (method) {
|
||||
case "dd": {
|
||||
const parsed = parseOffset(opts.offset);
|
||||
if (parsed === null) {
|
||||
throw new Error(`flash: invalid offset "${opts.offset}" (expect decimal or 0x hex)`);
|
||||
}
|
||||
offsetBytes = parsed;
|
||||
const parts = ["dd", `if=${image}`, `of=${target}`, "bs=4M", "conv=fsync"];
|
||||
if (parsed > 0) {
|
||||
// dd seek= 以 bs 为单位:字节偏移 → 块数
|
||||
parts.push(`seek=${Math.floor(parsed / DD_BLOCK_SIZE)}`);
|
||||
}
|
||||
commands.push(parts.join(" "));
|
||||
break;
|
||||
}
|
||||
case "fastboot": {
|
||||
const part = opts.partition?.trim();
|
||||
if (part) {
|
||||
commands.push(`fastboot flash ${part} ${image}`);
|
||||
} else {
|
||||
commands.push(`fastboot flash ${image}`);
|
||||
}
|
||||
break;
|
||||
}
|
||||
case "dfu": {
|
||||
const alt = opts.partition?.trim();
|
||||
const parts = ["dfu-util", `-d ${target}`];
|
||||
if (alt) parts.push(`-a ${alt}`);
|
||||
parts.push(`-D ${image}`);
|
||||
commands.push(parts.join(" "));
|
||||
break;
|
||||
}
|
||||
case "openocd": {
|
||||
commands.push(`openocd -f ${target} -c "program ${image} verify reset exit"`);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
method,
|
||||
commands,
|
||||
target,
|
||||
image,
|
||||
...(offsetBytes !== undefined ? { offsetBytes } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// lsblk 解析 + 根盘判定(纯函数,可单测)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 解析 `lsblk -b -o NAME,SIZE,TYPE,MOUNTPOINT` 的原始输出为行数组。
|
||||
* 处理树形盒绘字符前缀(├─ └─ │)与空 mountpoint。
|
||||
*
|
||||
* @param raw lsblk 原始 stdout。
|
||||
* @returns 解析后的行数组。
|
||||
*/
|
||||
export function parseLsblk(raw: string): LsblkRow[] {
|
||||
const lines = raw.split("\n");
|
||||
const rows: LsblkRow[] = [];
|
||||
let started = false;
|
||||
for (const line of lines) {
|
||||
if (!line.trim()) continue;
|
||||
if (!started) {
|
||||
// 跳过表头行
|
||||
if (/^NAME/i.test(line.trim())) {
|
||||
started = true;
|
||||
continue;
|
||||
}
|
||||
}
|
||||
// 去掉行首树形字符 + 空白
|
||||
const cleaned = line.replace(LSBLK_TREE_CHARS, " ").trim();
|
||||
if (!cleaned) continue;
|
||||
const cols = cleaned.split(/\s+/);
|
||||
if (cols.length < 3) continue;
|
||||
const name = cols[0] ?? "";
|
||||
const size = Number.parseInt(cols[1] ?? "0", 10);
|
||||
const type = cols[2] ?? "";
|
||||
// mountpoint 可能在第 4 列,也可能为空(多空格已 collapse)
|
||||
const mountpoint = cols.slice(3).join(" ") ?? "";
|
||||
rows.push({ name, size: Number.isFinite(size) ? size : 0, type, mountpoint });
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从目标设备路径提取 basename(/dev/sda1 → sda1,/dev/mmcblk0p2 → mmcblk0p2)。
|
||||
*
|
||||
* @param target 设备路径。
|
||||
* @returns basename。
|
||||
*/
|
||||
export function deviceBasename(target: string): string {
|
||||
const m = target.match(/\/dev\/(.+)$/);
|
||||
return m ? m[1] : target.replace(/^\/+/, "");
|
||||
}
|
||||
|
||||
/**
|
||||
* 判断 target 是否为宿主系统盘:target 自身或其任一分区挂载了根/启动目录。
|
||||
*
|
||||
* 例:target=/dev/sda,lsblk 含 sda2 mountpoint=/ → true(拒绝)。
|
||||
* target=/dev/mmcblk0,无 root 挂载 → false(允许烧 SD 卡)。
|
||||
* target=/dev/sda1,sda1 mountpoint=/boot → true(拒绝根分区)。
|
||||
*
|
||||
* @param target 设备路径。
|
||||
* @param rows lsblk 解析后的行数组。
|
||||
* @returns true 表示是宿主系统盘(应拒绝写)。
|
||||
*/
|
||||
export function isRootDiskTarget(target: string, rows: LsblkRow[]): boolean {
|
||||
const base = deviceBasename(target);
|
||||
for (const row of rows) {
|
||||
// 行名 == base(target 自身)或以 base 开头(target 的分区,如 sda1 是 sda 的分区)
|
||||
if (row.name === base || row.name.startsWith(base)) {
|
||||
if (row.mountpoint && ROOT_MOUNTPOINTS.has(row.mountpoint)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* 判断 target 是否出现在 lsblk 输出里(设备节点存在)。
|
||||
*
|
||||
* @param target 设备路径。
|
||||
* @param rows lsblk 解析后的行数组。
|
||||
* @returns true 表示设备存在。
|
||||
*/
|
||||
export function targetExistsInRows(target: string, rows: LsblkRow[]): boolean {
|
||||
const base = deviceBasename(target);
|
||||
return rows.some((r) => r.name === base || r.name.startsWith(base));
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ② dryRun — 模拟:确认 target 存在、不在根盘、sha256 预计算
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* dry-run:不写真写,只校验可烧条件。
|
||||
*
|
||||
* dd: lsblk 确认 target 存在 + 非根盘;stat 取镜像大小;sha256sum 预计算;
|
||||
* `dd if=<image> of=/dev/null bs=4M count=1` 只读验证镜像可读。
|
||||
* fastboot: `fastboot getvar all` 确认设备在线。
|
||||
* dfu: `dfu-util -l` 列出 DFU 设备。
|
||||
* openocd: `openocd -f <cfg> -c "init" -c "exit"` 探测 JTAG 连通。
|
||||
*
|
||||
* fail-closed:target 不存在 / 是根盘 / 探测命令非零退出 → ok:false。
|
||||
*
|
||||
* @param plan 烧录计划(planFlash 产出)。
|
||||
* @param execFn 注入的执行函数(测试 mock / pi.exec 均走这条)。
|
||||
* @returns DryRunResult。
|
||||
*/
|
||||
export async function dryRun(plan: FlashPlanEx, execFn: ExecFn): Promise<DryRunResult> {
|
||||
const probeCommands: string[] = [];
|
||||
|
||||
if (plan.method === "dd") {
|
||||
// 1. lsblk 确认 target 存在 + 非根盘
|
||||
const lsblkCmd = "lsblk";
|
||||
const lsblkArgs = ["-b", "-o", "NAME,SIZE,TYPE,MOUNTPOINT"];
|
||||
probeCommands.push(`${lsblkCmd} ${lsblkArgs.join(" ")}`);
|
||||
const lsblkRes = await execFn(lsblkCmd, lsblkArgs);
|
||||
if (lsblkRes.exitCode !== 0) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `lsblk failed: ${lsblkRes.stderr.trim() || `exit ${lsblkRes.exitCode}`}`,
|
||||
plan,
|
||||
targetExists: false,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
};
|
||||
}
|
||||
const rows = parseLsblk(lsblkRes.stdout);
|
||||
const exists = targetExistsInRows(plan.target, rows);
|
||||
if (!exists) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `target ${plan.target} not found in lsblk`,
|
||||
plan,
|
||||
targetExists: false,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
};
|
||||
}
|
||||
const rootDisk = isRootDiskTarget(plan.target, rows);
|
||||
if (rootDisk) {
|
||||
// 找到具体根挂载点,给出可读 reason
|
||||
const base = deviceBasename(plan.target);
|
||||
const rootMounts = rows
|
||||
.filter((r) => (r.name === base || r.name.startsWith(base)) && r.mountpoint && ROOT_MOUNTPOINTS.has(r.mountpoint))
|
||||
.map((r) => `${r.name}:${r.mountpoint}`);
|
||||
return {
|
||||
ok: false,
|
||||
reason: `target ${plan.target} has mounted ${rootMounts.join(", ")} — refusing`,
|
||||
plan,
|
||||
targetExists: true,
|
||||
isRootDisk: true,
|
||||
probeCommands,
|
||||
};
|
||||
}
|
||||
|
||||
// 2. stat 取镜像大小
|
||||
const statCmd = "stat";
|
||||
const statArgs = ["-c", "%s", plan.image];
|
||||
probeCommands.push(`${statCmd} ${statArgs.join(" ")}`);
|
||||
const statRes = await execFn(statCmd, statArgs);
|
||||
if (statRes.exitCode !== 0) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `stat image failed: ${statRes.stderr.trim() || `exit ${statRes.exitCode}`}`,
|
||||
plan,
|
||||
targetExists: true,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
};
|
||||
}
|
||||
const imageSize = Number.parseInt(statRes.stdout.trim(), 10);
|
||||
if (!Number.isFinite(imageSize) || imageSize <= 0) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `invalid image size: "${statRes.stdout.trim()}"`,
|
||||
plan,
|
||||
targetExists: true,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
};
|
||||
}
|
||||
plan.imageSizeBytes = imageSize;
|
||||
plan.blockCount = Math.max(1, Math.ceil(imageSize / DD_BLOCK_SIZE));
|
||||
|
||||
// 3. offset 越界校验
|
||||
if (plan.offsetBytes !== undefined && plan.offsetBytes >= imageSize) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `offset ${plan.offsetBytes} >= image size ${imageSize}`,
|
||||
plan,
|
||||
targetExists: true,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
};
|
||||
}
|
||||
|
||||
// 4. sha256sum 预计算
|
||||
const shaCmd = "sha256sum";
|
||||
const shaArgs = [plan.image];
|
||||
probeCommands.push(`${shaCmd} ${shaArgs.join(" ")}`);
|
||||
const shaRes = await execFn(shaCmd, shaArgs);
|
||||
if (shaRes.exitCode !== 0) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `sha256sum failed: ${shaRes.stderr.trim() || `exit ${shaRes.exitCode}`}`,
|
||||
plan,
|
||||
targetExists: true,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
};
|
||||
}
|
||||
const hash = shaRes.stdout.trim().split(/\s+/)[0] ?? "";
|
||||
if (!/^[0-9a-f]{64}$/i.test(hash)) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `unparsable sha256sum output: "${shaRes.stdout.trim().slice(0, 80)}"`,
|
||||
plan,
|
||||
targetExists: true,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
sha256sumOutput: shaRes.stdout,
|
||||
};
|
||||
}
|
||||
plan.expectedSha256 = hash;
|
||||
|
||||
// 5. 只读验证镜像可读:dd if=image of=/dev/null bs=4M count=1
|
||||
const ddProbe = "dd";
|
||||
const ddProbeArgs = [`if=${plan.image}`, "of=/dev/null", "bs=4M", "count=1"];
|
||||
probeCommands.push(`${ddProbe} ${ddProbeArgs.join(" ")}`);
|
||||
const ddProbeRes = await execFn(ddProbe, ddProbeArgs);
|
||||
if (ddProbeRes.exitCode !== 0) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `image read probe failed: ${ddProbeRes.stderr.trim() || `exit ${ddProbeRes.exitCode}`}`,
|
||||
plan,
|
||||
targetExists: true,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
sha256sumOutput: shaRes.stdout,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
plan,
|
||||
targetExists: true,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
sha256sumOutput: shaRes.stdout,
|
||||
};
|
||||
}
|
||||
|
||||
// 非 dd:探测设备在线
|
||||
let probeCmd: string;
|
||||
let probeArgs: string[];
|
||||
if (plan.method === "fastboot") {
|
||||
probeCmd = "fastboot";
|
||||
probeArgs = ["getvar", "all"];
|
||||
} else if (plan.method === "dfu") {
|
||||
probeCmd = "dfu-util";
|
||||
probeArgs = ["-l"];
|
||||
} else {
|
||||
// openocd
|
||||
probeCmd = "openocd";
|
||||
probeArgs = ["-f", plan.target, "-c", "init", "-c", "exit"];
|
||||
}
|
||||
probeCommands.push(`${probeCmd} ${probeArgs.join(" ")}`);
|
||||
const probeRes = await execFn(probeCmd, probeArgs);
|
||||
if (probeRes.exitCode !== 0) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `${plan.method} probe failed: ${probeRes.stderr.trim() || `exit ${probeRes.exitCode}`}`,
|
||||
plan,
|
||||
targetExists: false,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
};
|
||||
}
|
||||
return {
|
||||
ok: true,
|
||||
plan,
|
||||
targetExists: true,
|
||||
isRootDisk: false,
|
||||
probeCommands,
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ③ verifyFlash — 烧后 sha256 校验(dd)/ exitCode 校验(其他)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 烧后校验。
|
||||
*
|
||||
* dd: 读回 `dd if=<target> bs=4M count=<blockCount>`,对 stdout 算 sha256,
|
||||
* 与 plan.expectedSha256(dryRun 预计算)比对。不匹配 → VERIFY FAILED。
|
||||
* openocd: `openocd -f <cfg> -c "verify_image <image>" -c "exit"`,exitCode 0 为通过。
|
||||
* fastboot: `fastboot getvar all` 探测设备仍在线(fastboot 无逐字节校验)。
|
||||
* dfu: `dfu-util -l` 探测设备仍在线。
|
||||
*
|
||||
* fail-closed:dd 无 expectedSha256(未 dry-run)→ 拒绝;读回失败 → fail。
|
||||
*
|
||||
* @param plan 烧录计划(dryRun 填充了 expectedSha256/blockCount)。
|
||||
* @param execFn 注入的执行函数。
|
||||
* @returns VerifyResult。
|
||||
*/
|
||||
export async function verifyFlash(plan: FlashPlanEx, execFn: ExecFn): Promise<VerifyResult> {
|
||||
if (plan.method === "dd") {
|
||||
if (!plan.expectedSha256) {
|
||||
return { ok: false, reason: "no expectedSha256 in plan — run dryRun first" };
|
||||
}
|
||||
const blockCount = plan.blockCount ?? 1;
|
||||
const cmd = "dd";
|
||||
const args = [`if=${plan.target}`, "bs=4M", `count=${blockCount}`];
|
||||
const res = await execFn(cmd, args);
|
||||
if (res.exitCode !== 0) {
|
||||
return {
|
||||
ok: false,
|
||||
expected: plan.expectedSha256,
|
||||
reason: `readback dd failed: ${res.stderr.trim() || `exit ${res.exitCode}`}`,
|
||||
verifyCommand: `${cmd} ${args.join(" ")}`,
|
||||
};
|
||||
}
|
||||
// 对读回的 stdout 算 sha256(mock 场景下 stdout 即设备字节;真实场景需管道,
|
||||
// 扩展层会用 pi.exec 的流式变体,这里逻辑层只认 ExecResult.stdout)。
|
||||
const actual = createHash("sha256").update(res.stdout).digest("hex");
|
||||
if (actual === plan.expectedSha256) {
|
||||
return { ok: true, expected: plan.expectedSha256, actual, verifyCommand: `${cmd} ${args.join(" ")}` };
|
||||
}
|
||||
return {
|
||||
ok: false,
|
||||
expected: plan.expectedSha256,
|
||||
actual,
|
||||
reason: "VERIFY FAILED: sha256 mismatch",
|
||||
verifyCommand: `${cmd} ${args.join(" ")}`,
|
||||
};
|
||||
}
|
||||
|
||||
// 非 dd:exitCode 校验
|
||||
let cmd: string;
|
||||
let args: string[];
|
||||
if (plan.method === "openocd") {
|
||||
cmd = "openocd";
|
||||
args = ["-f", plan.target, "-c", `verify_image ${plan.image}`, "-c", "exit"];
|
||||
} else if (plan.method === "fastboot") {
|
||||
cmd = "fastboot";
|
||||
args = ["getvar", "all"];
|
||||
} else {
|
||||
// dfu
|
||||
cmd = "dfu-util";
|
||||
args = ["-l"];
|
||||
}
|
||||
const res = await execFn(cmd, args);
|
||||
if (res.exitCode !== 0) {
|
||||
return {
|
||||
ok: false,
|
||||
reason: `${plan.method} verify failed: ${res.stderr.trim() || `exit ${res.exitCode}`}`,
|
||||
verifyCommand: `${cmd} ${args.join(" ")}`,
|
||||
};
|
||||
}
|
||||
return { ok: true, verifyCommand: `${cmd} ${args.join(" ")}` };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 编排:dryRun → 写 → verify(扩展层调用,逻辑层集中编排便于单测)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 三段式编排:先 dryRun(fail-closed),通过后才写真写命令,再 verify。
|
||||
* dryRunOpts.skipWrite=true 时只 dry-run 不写真写(对应 dry_run:true)。
|
||||
*
|
||||
* 纯逻辑:execFn 注入。扩展层把 pi.exec 适配成 ExecFn 传入。
|
||||
*
|
||||
* @param plan 烧录计划。
|
||||
* @param execFn 注入的执行函数。
|
||||
* @param opts skipWrite=true 时只 dry-run 不写真写。
|
||||
* @returns RunFlashResult。
|
||||
*/
|
||||
export async function runFlash(
|
||||
plan: FlashPlanEx,
|
||||
execFn: ExecFn,
|
||||
opts: { skipWrite?: boolean } = {},
|
||||
): Promise<RunFlashResult> {
|
||||
// ① dry-run
|
||||
const dr = await dryRun(plan, execFn);
|
||||
if (!dr.ok) {
|
||||
return { dryRun: dr, written: false, writeExitCodes: [], ok: false, reason: dr.reason };
|
||||
}
|
||||
if (opts.skipWrite) {
|
||||
return { dryRun: dr, written: false, writeExitCodes: [], ok: true };
|
||||
}
|
||||
|
||||
// ② 写:逐条执行 plan.commands
|
||||
const writeExitCodes: number[] = [];
|
||||
for (const cmdStr of plan.commands) {
|
||||
const parts = splitCommand(cmdStr);
|
||||
const res = await execFn(parts[0], parts.slice(1));
|
||||
writeExitCodes.push(res.exitCode);
|
||||
if (res.exitCode !== 0) {
|
||||
return {
|
||||
dryRun: dr,
|
||||
written: true,
|
||||
writeExitCodes,
|
||||
ok: false,
|
||||
reason: `write command failed (${cmdStr}): ${res.stderr.trim() || `exit ${res.exitCode}`}`,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// ③ verify
|
||||
const vr = await verifyFlash(plan, execFn);
|
||||
return {
|
||||
dryRun: dr,
|
||||
written: true,
|
||||
writeExitCodes,
|
||||
verify: vr,
|
||||
ok: vr.ok,
|
||||
reason: vr.ok ? undefined : vr.reason,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 简易命令拆分:按空格切,但保留双引号内的整体(openocd -c "program x verify reset exit")。
|
||||
* 仅供 runFlash 内部把 plan.commands 字符串拆回 command+args。
|
||||
*
|
||||
* @param cmdStr 命令字符串。
|
||||
* @returns 拆分后的 token 数组(第一项为命令,其余为参数)。
|
||||
*/
|
||||
export function splitCommand(cmdStr: string): string[] {
|
||||
const tokens: string[] = [];
|
||||
let cur = "";
|
||||
let inQuote = false;
|
||||
for (let i = 0; i < cmdStr.length; i++) {
|
||||
const ch = cmdStr[i];
|
||||
if (ch === '"') {
|
||||
inQuote = !inQuote;
|
||||
continue;
|
||||
}
|
||||
if (ch === " " && !inQuote) {
|
||||
if (cur) tokens.push(cur);
|
||||
cur = "";
|
||||
continue;
|
||||
}
|
||||
cur += ch;
|
||||
}
|
||||
if (cur) tokens.push(cur);
|
||||
return tokens;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// pi.exec → ExecFn 适配(桥接 ExecOpts → ExecOptions,结果同构)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把 pi.exec 包装成 ExecFn(逻辑层注入的执行函数签名)。
|
||||
* boardId 由 board-link 域负责注入;这里走默认 pi.exec(本机/当前板)。
|
||||
*/
|
||||
function makeExecFn(pi: ExtensionAPI): ExecFn {
|
||||
return async (command, args, opts) => {
|
||||
const piOpts: ExecOptions = {};
|
||||
if (opts?.cwd) piOpts.cwd = opts.cwd;
|
||||
if (opts?.timeout) piOpts.timeout = opts.timeout;
|
||||
if (opts?.env) piOpts.env = opts.env;
|
||||
return pi.exec(command, args, piOpts);
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 进程内独占锁(同进程并发第二个 flash tool call 被拒)
|
||||
// ============================================================================
|
||||
|
||||
let flashInProgress = false;
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* flash 域扩展装配。
|
||||
*
|
||||
* - 注册 `flash` 工具:封装 dd/fastboot/dfu/openocd 四种烧录,强制三段式安全流程
|
||||
* - user_bash 事件拦截裸 `dd of=/dev/`,提示改用 flash 工具
|
||||
* - session_start 落加载标记
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*/
|
||||
export default async function flashExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
// ---- flash 工具 schema ----
|
||||
const flashSchema = Type.Object(
|
||||
{
|
||||
method: Type.Union(
|
||||
[
|
||||
Type.Literal("dd"),
|
||||
Type.Literal("fastboot"),
|
||||
Type.Literal("dfu"),
|
||||
Type.Literal("openocd"),
|
||||
],
|
||||
{ description: "Flashing method" },
|
||||
),
|
||||
image: Type.String({ description: "Path to image/payload file" }),
|
||||
target: Type.String({
|
||||
description:
|
||||
"Target device node (e.g. /dev/mmcblk0) for dd; 'serial' for fastboot/dfu; cfg path for openocd",
|
||||
}),
|
||||
offset: Type.Optional(
|
||||
Type.String({
|
||||
description: "Byte offset for dd seek= (decimal or 0x hex). Validated against partition table.",
|
||||
}),
|
||||
),
|
||||
partition: Type.Optional(
|
||||
Type.String({ description: "Partition name for fastboot (e.g. boot) or dfu alt-setting" }),
|
||||
),
|
||||
dry_run: Type.Optional(
|
||||
Type.Boolean({ description: "If true, validate without writing. Default true for first call." }),
|
||||
),
|
||||
verify: Type.Optional(
|
||||
Type.Boolean({ description: "If true, verify after write via hash compare. Default true." }),
|
||||
),
|
||||
},
|
||||
{ description: "Safe flashing tool with 3-step gate (plan → dry-run → verify)." },
|
||||
);
|
||||
|
||||
const execFn = makeExecFn(pi);
|
||||
|
||||
const flashTool = defineTool({
|
||||
name: "flash",
|
||||
label: "Safe Flash",
|
||||
description:
|
||||
"Safe flashing (dd/fastboot/dfu/openocd) with mandatory 3-step gate: plan → dry-run → verify. " +
|
||||
"Refuses host system disks (/dev/sda with / mounted). dry_run defaults true. " +
|
||||
"Use this instead of raw `dd of=/dev/...` (which safety-gate blocks).",
|
||||
promptSnippet: "Flash an image to a device with dry-run + sha256 verify",
|
||||
parameters: flashSchema,
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as {
|
||||
method: "dd" | "fastboot" | "dfu" | "openocd";
|
||||
image: string;
|
||||
target: string;
|
||||
offset?: string;
|
||||
partition?: string;
|
||||
dry_run?: boolean;
|
||||
verify?: boolean;
|
||||
};
|
||||
|
||||
// ---- 独占锁:并发第二个被拒 ----
|
||||
if (flashInProgress) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: "FLASH BUSY: another flash operation is in progress (lock held). Retry after it completes.",
|
||||
},
|
||||
],
|
||||
details: { locked: true },
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
flashInProgress = true;
|
||||
try {
|
||||
// ---- ① plan ----
|
||||
let plan: FlashPlanEx;
|
||||
try {
|
||||
plan = planFlash(p.method, p.image, p.target, {
|
||||
offset: p.offset,
|
||||
partition: p.partition,
|
||||
dryRun: p.dry_run,
|
||||
verify: p.verify,
|
||||
});
|
||||
} catch (e) {
|
||||
return {
|
||||
content: [{ type: "text", text: `PLAN FAILED: ${(e as Error).message}` }],
|
||||
details: { stage: "plan" },
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
// dry_run 默认 true(fail-closed):未显式传 false 即只 dry-run
|
||||
const dryOnly = p.dry_run !== false;
|
||||
|
||||
// ---- ② dry-run → 写 → verify(逻辑层编排) ----
|
||||
const result = await runFlash(plan, execFn, { skipWrite: dryOnly });
|
||||
|
||||
// ---- 汇报 ----
|
||||
const lines: string[] = [];
|
||||
lines.push(`method: ${plan.method}`);
|
||||
lines.push(`target: ${plan.target}`);
|
||||
lines.push(`image: ${plan.image}`);
|
||||
lines.push(`dry-run: ${result.dryRun.ok ? "OK" : "FAIL"}`);
|
||||
if (result.dryRun.reason) lines.push(` reason: ${result.dryRun.reason}`);
|
||||
if (plan.expectedSha256) lines.push(` expected sha256: ${plan.expectedSha256}`);
|
||||
if (plan.imageSizeBytes) lines.push(` image size: ${plan.imageSizeBytes} bytes`);
|
||||
|
||||
if (!dryOnly) {
|
||||
lines.push(`write: ${result.written ? "done" : "skipped"}`);
|
||||
lines.push(` exitCodes: ${JSON.stringify(result.writeExitCodes)}`);
|
||||
if (result.verify) {
|
||||
lines.push(
|
||||
`verify: ${result.verify.ok ? "OK — flash OK: verified" : "VERIFY FAILED"}`,
|
||||
);
|
||||
if (result.verify.actual) lines.push(` actual sha256: ${result.verify.actual}`);
|
||||
if (result.verify.reason) lines.push(` reason: ${result.verify.reason}`);
|
||||
}
|
||||
} else if (result.dryRun.ok) {
|
||||
const sizeStr = plan.imageSizeBytes
|
||||
? `${(plan.imageSizeBytes / 1e9).toFixed(1)}GB`
|
||||
: "unknown";
|
||||
lines.push(`would write ${sizeStr} to ${plan.target} offset ${plan.offsetBytes ?? 0}`);
|
||||
}
|
||||
|
||||
lines.push(`overall: ${result.ok ? "flash OK: verified" : "FAILED"}`);
|
||||
|
||||
if (result.ok) {
|
||||
pi.appendEntry("flash:done", {
|
||||
method: plan.method,
|
||||
target: plan.target,
|
||||
image: plan.image,
|
||||
dryRunOnly: dryOnly,
|
||||
sha256: plan.expectedSha256,
|
||||
});
|
||||
} else {
|
||||
pi.appendEntry("flash:failed", {
|
||||
method: plan.method,
|
||||
target: plan.target,
|
||||
reason: result.reason,
|
||||
});
|
||||
}
|
||||
|
||||
const ok = result.ok;
|
||||
return {
|
||||
content: [{ type: "text", text: lines.join("\n") }],
|
||||
details: {
|
||||
stage: dryOnly ? "dry-run" : "full",
|
||||
ok,
|
||||
method: plan.method,
|
||||
target: plan.target,
|
||||
},
|
||||
isError: !ok,
|
||||
};
|
||||
} finally {
|
||||
flashInProgress = false;
|
||||
}
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(flashTool);
|
||||
|
||||
// ---- 拦截用户手敲 dd(user_bash 事件)----
|
||||
// 把裸 dd of=/dev/ 收束到 flash 工具。
|
||||
pi.on("user_bash", (event: any, ctx: ExtensionContext) => {
|
||||
const e = event as { command?: string };
|
||||
const cmd = e?.command ?? "";
|
||||
// 命中 dd of=/dev/ → 提示用 flash 工具
|
||||
if (/\bdd\b[^|]*\bof\s*=\s*\/dev\//i.test(cmd)) {
|
||||
pi.appendEntry("flash:raw-dd-blocked", { command: cmd });
|
||||
const msg =
|
||||
"裸 `dd of=/dev/...` 被拦截。请改用 `flash` 工具,强制 dry-run + sha256 校验。";
|
||||
if (ctx.hasUI) {
|
||||
ctx.ui.notify(msg, "warning");
|
||||
} else {
|
||||
pi.sendUserMessage(msg);
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- session_start 落加载标记 ----
|
||||
pi.on("session_start", () => {
|
||||
pi.appendEntry("flash:loaded", {
|
||||
methods: ["dd", "fastboot", "dfu", "openocd"],
|
||||
dryRunDefault: true,
|
||||
sequential: true,
|
||||
});
|
||||
});
|
||||
}
|
||||
410
src/extensions/glm-provider.ts
Normal file
410
src/extensions/glm-provider.ts
Normal file
@ -0,0 +1,410 @@
|
||||
/**
|
||||
* @module glm-provider
|
||||
*
|
||||
* glm-5.2 适配兜底扩展 —— 治嵌入式开发场景下 pi + glm-5.2 组合的两个独家命门:
|
||||
*
|
||||
* - 命门一(thinking 黑洞零输出):glm-5.2 默认开 thinking,max_tokens 全被 reasoning
|
||||
* 吃光导致零文本输出。根治:注册 provider 时 thinkingFormat:"qwen" + maxTokens:8192
|
||||
* + thinkingLevelMap 全 null,触发 pi openai-completions 的 enable_thinking:false 分支
|
||||
* (pi `openai-completions.ts:762-763` 实测)。
|
||||
* - 命门二(hex 强转砖板):glm-5.2 把寄存器地址 0x40020000 强转成十进制 "1073872896",
|
||||
* 下游 devmem/i2cset 写错地址即砖板。根治:提供 prepareArguments 工厂,把寄存器地址
|
||||
* 范围内的十进制还原成 0x 形式。
|
||||
*
|
||||
* 见 Docs/F11_glm-5.2适配兜底层.md。逻辑内联为命名导出,tests 直接单测,无需 pi 运行时。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ProviderConfig,
|
||||
ProviderModelConfig,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
import type { NormalizedArg } from "../shared/types.js";
|
||||
|
||||
// 注:defineTool / Type 仅在 factory 内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑函数
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时 factory 不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// 命门一:glm-5.2 模型配置
|
||||
// ============================================================================
|
||||
|
||||
/** glm-5.2 经 d-robotics 网关的真实模型 id(带中划线,实测见缺陷分析 §3 #7)。 */
|
||||
export const GLM_MODEL_ID = "glm-5.2";
|
||||
/** pi provider 名。 */
|
||||
export const GLM_PROVIDER_NAME = "drobotics-glm";
|
||||
|
||||
/** qwen 变体触发 enable_thinking:false 分支的兼容配置。 */
|
||||
export interface GlmCompat {
|
||||
thinkingFormat: "qwen";
|
||||
supportsReasoningEffort: false;
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
/** glm-5.2 模型配置。扩展层透传给 pi.registerProvider()。 */
|
||||
export interface GlmModelConfig {
|
||||
id: string;
|
||||
name: string;
|
||||
provider: string;
|
||||
baseUrl: string;
|
||||
/** key 环境占位,绝不硬编码真 key。 */
|
||||
apiKey: string;
|
||||
api: string;
|
||||
reasoning: boolean;
|
||||
thinkingLevelMap: { off: null; low: null; medium: null; high: null };
|
||||
maxTokens: number;
|
||||
contextWindow: number;
|
||||
cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
|
||||
input: ("text" | "image")[];
|
||||
compat: GlmCompat;
|
||||
supportsReasoningEffort: false;
|
||||
}
|
||||
|
||||
export interface BuildGlmOptions {
|
||||
/** 覆盖网关 base url,默认 d-robotics 内部网关。 */
|
||||
baseUrl?: string;
|
||||
/** key 环境占位名,默认 DROBOTICS_LLM_KEY。 */
|
||||
apiKeyEnv?: string;
|
||||
maxTokens?: number;
|
||||
contextWindow?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 产出 glm-5.2 的 pi 模型配置对象。扩展层交给 pi.registerProvider()。
|
||||
*
|
||||
* 命门一根治点:reasoning:true + thinkingLevelMap 全 null + compat.thinkingFormat:"qwen"。
|
||||
*
|
||||
* @returns 模型配置对象,key 为 ${DROBOTICS_LLM_KEY} 占位。
|
||||
*/
|
||||
export function buildGlmModelConfig(opts: BuildGlmOptions = {}): GlmModelConfig {
|
||||
const baseUrl = opts.baseUrl ?? "https://ai-api.d-robotics.cc/v1";
|
||||
const apiKey = `\${${opts.apiKeyEnv ?? "DROBOTICS_LLM_KEY"}}`;
|
||||
const maxTokens = opts.maxTokens ?? 8192;
|
||||
const contextWindow = opts.contextWindow ?? 1_000_000;
|
||||
return {
|
||||
id: GLM_MODEL_ID,
|
||||
name: "GLM-5.2 (D-Robotics gateway)",
|
||||
provider: GLM_PROVIDER_NAME,
|
||||
baseUrl,
|
||||
apiKey,
|
||||
api: "openai",
|
||||
reasoning: true,
|
||||
thinkingLevelMap: { off: null, low: null, medium: null, high: null },
|
||||
maxTokens,
|
||||
contextWindow,
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
input: ["text"],
|
||||
compat: { thinkingFormat: "qwen", supportsReasoningEffort: false },
|
||||
supportsReasoningEffort: false,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 把 GlmModelConfig 转成 pi.registerProvider(name, config) 的入参。
|
||||
*
|
||||
* @returns { name, config } 供 pi.registerProvider 使用。
|
||||
*/
|
||||
export function toProviderConfig(cfg: GlmModelConfig): { name: string; config: ProviderConfig } {
|
||||
const model: ProviderModelConfig = {
|
||||
id: cfg.id,
|
||||
name: cfg.name,
|
||||
reasoning: cfg.reasoning,
|
||||
thinkingLevelMap: cfg.thinkingLevelMap,
|
||||
input: cfg.input,
|
||||
cost: cfg.cost,
|
||||
contextWindow: cfg.contextWindow,
|
||||
maxTokens: cfg.maxTokens,
|
||||
compat: cfg.compat,
|
||||
};
|
||||
return {
|
||||
name: cfg.provider,
|
||||
config: {
|
||||
name: cfg.name,
|
||||
baseUrl: cfg.baseUrl,
|
||||
apiKey: cfg.apiKey,
|
||||
api: cfg.api,
|
||||
authHeader: true,
|
||||
models: [model],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 命门二:hex 强转归一
|
||||
// ============================================================================
|
||||
|
||||
export interface NormalizeHexOptions {
|
||||
/** 不归一化的字段名(小写匹配),如 baudrate/timeout/size/count。 */
|
||||
fieldDenylist?: string[];
|
||||
/** 地址范围下界(十进制),默认 0x10000。 */
|
||||
minRange?: number;
|
||||
/** 地址范围上界(十进制),默认 0xFFFFFFFF(32 位寄存器空间)。 */
|
||||
maxRange?: number;
|
||||
/** 最小十进制位数才触发,默认 8(>= 10000000,避开 baudrate 115200 等)。 */
|
||||
minDigits?: number;
|
||||
}
|
||||
|
||||
const DEFAULT_MIN_RANGE = 0x10000;
|
||||
const DEFAULT_MAX_RANGE = 0xffffffff;
|
||||
|
||||
/**
|
||||
* 判断单个标量是否是"被强转成十进制的 hex 寄存器地址",若是则还原成 0x 形式。
|
||||
*
|
||||
* 规则(Docs/F11 §2.2):
|
||||
* - 纯数字字符串 / number
|
||||
* - 十进制值落在 (minRange, maxRange]
|
||||
* - 数字位数 >= minDigits
|
||||
* - 还原后形如 "0x40020000"
|
||||
*
|
||||
* 已是 0x 形式 → 原样返回(corrected:false)。64 位地址用 BigInt 保精度。
|
||||
*
|
||||
* @param value 原始标量值。
|
||||
* @returns 归一化结果。
|
||||
*/
|
||||
export function normalizeHexArg(value: unknown, opts: NormalizeHexOptions = {}): NormalizedArg {
|
||||
const minRange = opts.minRange ?? DEFAULT_MIN_RANGE;
|
||||
const maxRange = opts.maxRange ?? DEFAULT_MAX_RANGE;
|
||||
const minDigits = opts.minDigits ?? 8;
|
||||
|
||||
if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value.trim())) {
|
||||
return { value, corrected: false, original: value };
|
||||
}
|
||||
|
||||
let decimal: number | null = null;
|
||||
if (typeof value === "number" && Number.isFinite(value) && Number.isInteger(value)) {
|
||||
decimal = value;
|
||||
} else if (typeof value === "string" && /^\d+$/.test(value.trim())) {
|
||||
const trimmed = value.trim();
|
||||
if (trimmed.length >= minDigits) {
|
||||
try {
|
||||
const big = BigInt(trimmed);
|
||||
const bigMin = BigInt(minRange);
|
||||
const bigMax = BigInt(maxRange);
|
||||
if (big > bigMin && big <= bigMax) {
|
||||
const hex = "0x" + big.toString(16);
|
||||
return { value: hex, corrected: true, original: value };
|
||||
}
|
||||
} catch {
|
||||
// fallthrough
|
||||
}
|
||||
decimal = Number(trimmed);
|
||||
}
|
||||
}
|
||||
|
||||
if (decimal !== null && decimal > minRange && decimal <= maxRange && decimal > 0) {
|
||||
const hex = "0x" + decimal.toString(16);
|
||||
return { value: hex, corrected: true, original: value };
|
||||
}
|
||||
|
||||
return { value: typeof value === "string" ? value : String(value ?? ""), corrected: false, original: value };
|
||||
}
|
||||
|
||||
/**
|
||||
* 递归遍历参数对象,对每个字段值跑 normalizeHexArg,跳过 denylist 字段。
|
||||
*
|
||||
* 供 prepareArguments 钩子使用:把 glm-5.2 强转的十进制地址还原成 hex,避免砖板。
|
||||
*
|
||||
* @returns { normalized, corrections } 新对象 + 修正日志。
|
||||
*/
|
||||
export function normalizeToolArguments(
|
||||
args: Record<string, unknown> | null | undefined,
|
||||
opts: NormalizeHexOptions = {},
|
||||
): { normalized: Record<string, unknown>; corrections: Array<{ field: string; from: unknown; to: string }> } {
|
||||
const deny = new Set((opts.fieldDenylist ?? []).map((s) => s.toLowerCase()));
|
||||
const corrections: Array<{ field: string; from: unknown; to: string }> = [];
|
||||
|
||||
function walk(obj: unknown, path: string): unknown {
|
||||
if (obj === null || obj === undefined) return obj;
|
||||
if (Array.isArray(obj)) {
|
||||
return obj.map((v, i) => walk(v, `${path}[${i}]`));
|
||||
}
|
||||
if (typeof obj === "object") {
|
||||
const out: Record<string, unknown> = {};
|
||||
for (const [k, v] of Object.entries(obj)) {
|
||||
const leaf = `${path ? path + "." : ""}${k}`;
|
||||
if (deny.has(k.toLowerCase())) {
|
||||
out[k] = v;
|
||||
continue;
|
||||
}
|
||||
out[k] = walk(v, leaf);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
const res = normalizeHexArg(obj, opts);
|
||||
if (res.corrected) {
|
||||
corrections.push({ field: path, from: res.original, to: res.value });
|
||||
}
|
||||
return res.value;
|
||||
}
|
||||
|
||||
const normalized = (walk(args, "") ?? {}) as Record<string, unknown>;
|
||||
return { normalized, corrections };
|
||||
}
|
||||
|
||||
/**
|
||||
* prepareArguments 工厂:其他结构化工具(flash/peripheral-probe/jtag-debugger 等)
|
||||
* 在 ToolDefinition.prepareArguments 里调这个,统一 hex 归一。
|
||||
*/
|
||||
export function makeHexNormalizingPrepareArguments(opts: NormalizeHexOptions = {}) {
|
||||
return (args: unknown) => {
|
||||
const { normalized, corrections } = normalizeToolArguments(args as Record<string, unknown> | undefined, opts);
|
||||
if (corrections.length > 0) {
|
||||
// biome-ignore lint/suspicious/noConsole: 砖板根因诊断日志
|
||||
console.warn(
|
||||
`[glm-provider] normalized ${corrections.length} hex address(es):`,
|
||||
corrections.map((c) => `${c.field} ${String(c.from)}→${c.to}`),
|
||||
);
|
||||
}
|
||||
return normalized;
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 命门一兜底:空输出检测
|
||||
// ============================================================================
|
||||
|
||||
export interface LlmResponseSnapshot {
|
||||
textContent: string;
|
||||
stopReason?: string;
|
||||
thinkingContent?: string;
|
||||
toolCallCount?: number;
|
||||
}
|
||||
|
||||
export interface EmptyOutputDiagnosis {
|
||||
empty: boolean;
|
||||
reason: "" | "thinking-overflow" | "max-tokens" | "no-content-no-tool" | "unknown";
|
||||
remediation: string | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 检测命门一"thinking 吃光 max_tokens 导致零输出"的典型症状。
|
||||
*
|
||||
* 兜底:根治靠 buildGlmModelConfig 关 thinking;若配置未生效,此函数暴露问题给 agent。
|
||||
*/
|
||||
export function detectEmptyOutput(snap: LlmResponseSnapshot): EmptyOutputDiagnosis {
|
||||
const hasText = snap.textContent.trim().length > 0;
|
||||
const hasTool = (snap.toolCallCount ?? 0) > 0;
|
||||
if (hasText || hasTool) {
|
||||
return { empty: false, reason: "", remediation: null };
|
||||
}
|
||||
if (snap.stopReason === "length") {
|
||||
return {
|
||||
empty: true,
|
||||
reason: "thinking-overflow",
|
||||
remediation:
|
||||
"GLM-5.2 thinking ate all max_tokens (stop=length, empty content). " +
|
||||
"Ensure buildGlmModelConfig(thinkingFormat:qwen) is applied so enable_thinking:false is sent.",
|
||||
};
|
||||
}
|
||||
if ((snap.thinkingContent ?? "").trim().length > 0) {
|
||||
return {
|
||||
empty: true,
|
||||
reason: "thinking-overflow",
|
||||
remediation: "GLM-5.2 returned thinking but no answer content. Disable reasoning via thinkingFormat:qwen.",
|
||||
};
|
||||
}
|
||||
return {
|
||||
empty: true,
|
||||
reason: "no-content-no-tool",
|
||||
remediation:
|
||||
"GLM-5.2 returned neither text nor tool calls. Retry with thinking disabled (thinkingFormat:qwen).",
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// glm_status 工具 + 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* glm-provider 扩展装配。
|
||||
*
|
||||
* - 注册 glm-5.2 provider(命门一根治)
|
||||
* - 注册 glm_status 工具
|
||||
* - message_end 检测空输出(命门一兜底)
|
||||
* - 暴露 hex 归一工厂经 events 总线握手
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*/
|
||||
export default async function glmProviderExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
const glmStatusTool = defineTool({
|
||||
name: "glm_status",
|
||||
label: "GLM Status",
|
||||
description:
|
||||
"Query the active GLM-5.2 adapter configuration (model id, thinkingFormat, maxTokens, " +
|
||||
"whether hex-address normalization is armed). Use this when output looks empty.",
|
||||
promptSnippet: "Check GLM-5.2 adapter config (thinking disabled? hex-normalize armed?)",
|
||||
parameters: Type.Object({}, { description: "No parameters." }),
|
||||
executionMode: "sequential",
|
||||
async execute() {
|
||||
const cfg = buildGlmModelConfig();
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify(
|
||||
{
|
||||
modelId: cfg.id,
|
||||
provider: cfg.provider,
|
||||
thinkingFormat: cfg.compat.thinkingFormat,
|
||||
reasoning: cfg.reasoning,
|
||||
thinkingLevelMapAllNull:
|
||||
cfg.thinkingLevelMap.off === null &&
|
||||
cfg.thinkingLevelMap.low === null &&
|
||||
cfg.thinkingLevelMap.medium === null &&
|
||||
cfg.thinkingLevelMap.high === null,
|
||||
maxTokens: cfg.maxTokens,
|
||||
hexNormalizeArmed: true,
|
||||
note: "thinking disabled via qwen variant (enable_thinking:false). hex address auto-normalized in prepareArguments.",
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
},
|
||||
],
|
||||
details: { armed: true },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
const cfg = buildGlmModelConfig();
|
||||
const { name, config } = toProviderConfig(cfg);
|
||||
pi.registerProvider(name, config);
|
||||
|
||||
pi.registerTool(glmStatusTool);
|
||||
|
||||
pi.on("message_end", (event: any, ctx: ExtensionContext) => {
|
||||
const e = event as { content?: Array<{ type: string; text?: string }>; stopReason?: string; toolCalls?: unknown[] };
|
||||
const textContent = (e.content ?? [])
|
||||
.filter((c) => c.type === "text")
|
||||
.map((c) => c.text ?? "")
|
||||
.join("");
|
||||
const diag = detectEmptyOutput({
|
||||
textContent,
|
||||
stopReason: e.stopReason,
|
||||
toolCallCount: e.toolCalls?.length,
|
||||
});
|
||||
if (diag.empty) {
|
||||
ctx.ui.notify(`[glm-provider] empty output: ${diag.reason}. ${diag.remediation ?? ""}`, "error");
|
||||
pi.appendEntry("glm:empty-output", { reason: diag.reason, remediation: diag.remediation });
|
||||
}
|
||||
});
|
||||
|
||||
pi.on("session_start", () => {
|
||||
pi.appendEntry("glm:adapter-loaded", {
|
||||
modelId: cfg.id,
|
||||
thinkingFormat: cfg.compat.thinkingFormat,
|
||||
maxTokens: cfg.maxTokens,
|
||||
hexNormalizeArmed: true,
|
||||
});
|
||||
});
|
||||
|
||||
pi.events.on("glm:request-normalize", (data) => {
|
||||
const d = data as { args?: Record<string, unknown>; opts?: NormalizeHexOptions };
|
||||
pi.events.emit("glm:normalized", normalizeToolArguments(d.args, d.opts));
|
||||
});
|
||||
}
|
||||
494
src/extensions/hardware-state.ts
Normal file
494
src/extensions/hardware-state.ts
Normal file
@ -0,0 +1,494 @@
|
||||
/**
|
||||
* @module hardware-state
|
||||
*
|
||||
* 硬件状态 Session-Entry 持久化扩展 —— 治嵌入式开发场景两条缺陷:
|
||||
* #4(session 纯文本 JSONL,零硬件状态/外设会话持久化)/
|
||||
* #14(compaction 视图截断,寄存器值/调试状态被摘要掉)。
|
||||
*
|
||||
* 场景锚定:嵌入式 agent 反复调用 i2cdump/gpioget/openocd/gdb 等外设命令,
|
||||
* 每次工具调用都重新初始化外设代价高且会冲掉断点/地址表。本扩展把硬件状态
|
||||
* 快照持久化进 pi session(CustomEntry 落 JSONL + CustomMessageEntry 注入 LLM),
|
||||
* 跨工具调用与跨 compaction 都不丢,session resume 时重放重建状态机视图。
|
||||
*
|
||||
* 三层配合(纯逻辑全在本文件命名导出,工厂函数只调 pi API):
|
||||
* ① makeHwEntry ——把硬件状态快照封成 CustomEntry{customType:"hw:state"}
|
||||
* ② replayFromEntries ——重放 entries 重建 {locks, checkpoint, flashLog}
|
||||
* ③ selectProtected ——compaction 前选出需保留的 hw entry(最近 N 条 + 每类型最新)
|
||||
*
|
||||
* 加载方式:把本文件软链/拷到 ~/.pi/agent/extensions/ 或项目 .pi/extensions/。
|
||||
* 顶层仅 `import type`(esbuild 擦除),defineTool/Type 在工厂内动态 import,
|
||||
* 故 tests 直接 import 命名逻辑导出即可离线单测,绝不触发 pi 解析。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
|
||||
import type { CheckpointState, CheckpointStep } from "../shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// 类型契约
|
||||
// ============================================================================
|
||||
|
||||
/** CustomEntry.customType 约定值。双轨制:CustomEntry 持久化 + CustomMessageEntry 注入共用此标记。 */
|
||||
export const HW_STATE_CUSTOM_TYPE = "hw:state" as const;
|
||||
|
||||
/**
|
||||
* 硬件状态类型。i2c/gdb/openocd/serial/gpio 为状态快照;
|
||||
* lock/checkpoint/flash 为可重放事件(replayFromEntries 据此重建状态机)。
|
||||
*/
|
||||
export type HwEntryType =
|
||||
| "i2c"
|
||||
| "gpio"
|
||||
| "gdb"
|
||||
| "openocd"
|
||||
| "serial"
|
||||
| "lock"
|
||||
| "checkpoint"
|
||||
| "flash";
|
||||
|
||||
/** 落进 CustomEntry.data 的硬件状态载荷。 */
|
||||
export interface HwStateData {
|
||||
/** 状态类型(设备/事件类别)。 */
|
||||
type: string;
|
||||
/** 任意状态快照/事件载荷。 */
|
||||
data: Record<string, unknown>;
|
||||
/** 捕获时刻(epoch ms)。 */
|
||||
ts: number;
|
||||
}
|
||||
|
||||
/** pi CustomEntry 的最小形状(customType + data,不进 LLM 上下文,不受 compaction 摘要影响)。 */
|
||||
export interface HwEntry {
|
||||
customType: typeof HW_STATE_CUSTOM_TYPE;
|
||||
data: HwStateData;
|
||||
}
|
||||
|
||||
/** 单条 flash 日志(重放重建产物)。 */
|
||||
export interface FlashLogEntry {
|
||||
method: string;
|
||||
target: string;
|
||||
image: string;
|
||||
sha256?: string;
|
||||
result: "ok" | "fail";
|
||||
ts: number;
|
||||
}
|
||||
|
||||
/** replayFromEntries 的重放产物:重建后的硬件状态机视图。 */
|
||||
export interface ReplayResult {
|
||||
/** deviceId → owner(acquire 未释放的锁;含 i2c 占用地址表)。 */
|
||||
locks: Record<string, string>;
|
||||
/** 最新 checkpoint 状态(按 entry 序累积 history)。 */
|
||||
checkpoint: CheckpointState | null;
|
||||
/** flash 事件序列(按序追加)。 */
|
||||
flashLog: FlashLogEntry[];
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ① makeHwEntry ——序列化
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 构造一条硬件状态 CustomEntry。
|
||||
*
|
||||
* - customType 固定 "hw:state",落 JSONL 后跨 session 重启可读。
|
||||
* - 不进 LLM 摘要文本(pi sessionEntryToContextMessages 对 custom 返回 []),
|
||||
* 上下文注入由扩展层另写 CustomMessageEntry(见 formatHwStateAsText)。
|
||||
*
|
||||
* @param type 状态/事件类型
|
||||
* @param data 状态载荷
|
||||
* @param timestamp 可选 ts,省略取 Date.now()
|
||||
* @returns 形如 { customType:"hw:state", data:{ type, data, ts } } 的 CustomEntry。
|
||||
*/
|
||||
export function makeHwEntry(
|
||||
type: string,
|
||||
data: Record<string, unknown>,
|
||||
timestamp?: number,
|
||||
): HwEntry {
|
||||
return {
|
||||
customType: HW_STATE_CUSTOM_TYPE,
|
||||
data: {
|
||||
type,
|
||||
data,
|
||||
ts: timestamp ?? Date.now(),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ② replayFromEntries ——重放重建
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把序列化过的 entries 列表重放,重建硬件状态机视图 {locks, checkpoint, flashLog}。
|
||||
*
|
||||
* 处理的事件类型:
|
||||
* - lock : {device, owner, action:"acquire"|"release"} → locks 增删
|
||||
* - i2c : {bus, occupiedAddresses, owner} → 每地址一条锁
|
||||
* - checkpoint : {step, passed} → 累积 history,取最新
|
||||
* - flash : {method, target, image, sha256?, result} → 追加 flashLog
|
||||
* - 其余 (gpio/gdb/openocd/serial): 状态快照,不参与状态机重建(仅靠 selectProtected 保护)。
|
||||
*
|
||||
* fail-closed:缺字段/乱序不抛异常,跳过该条。
|
||||
* 向后兼容:customType !== "hw:state" 或 type 不匹配的 entry 静默忽略(旧 session 不崩)。
|
||||
*
|
||||
* @param entries pi session 的 entry 列表(只读,不修改)。
|
||||
* @returns 重建后的 { locks, checkpoint, flashLog }。
|
||||
*/
|
||||
export function replayFromEntries(entries: ReadonlyArray<unknown>): ReplayResult {
|
||||
const locks: Record<string, string> = {};
|
||||
// 用 holder 对象绕开 TS 对"同块内后赋值前读取"的回溯性收窄(never)。
|
||||
const ckpt: { value: CheckpointState | null } = { value: null };
|
||||
const flashLog: FlashLogEntry[] = [];
|
||||
|
||||
for (const raw of entries) {
|
||||
if (!raw || typeof raw !== "object") continue;
|
||||
const entry = raw as { customType?: string; data?: HwStateData };
|
||||
if (entry.customType !== HW_STATE_CUSTOM_TYPE) continue;
|
||||
const sd = entry.data;
|
||||
if (!sd || typeof sd.type !== "string") continue;
|
||||
|
||||
const { type, data: payload, ts } = sd;
|
||||
switch (type) {
|
||||
case "lock": {
|
||||
const device = payload && typeof payload.device === "string" ? payload.device : "";
|
||||
if (!device) break;
|
||||
const owner = typeof payload.owner === "string" ? payload.owner : "";
|
||||
const action = typeof payload.action === "string" ? payload.action : "acquire";
|
||||
if (action === "release") {
|
||||
delete locks[device];
|
||||
} else {
|
||||
locks[device] = owner;
|
||||
}
|
||||
break;
|
||||
}
|
||||
case "i2c": {
|
||||
const bus = payload?.bus ?? 0;
|
||||
const addrs = payload?.occupiedAddresses;
|
||||
const owner = typeof payload?.owner === "string" ? payload.owner : "system";
|
||||
if (Array.isArray(addrs)) {
|
||||
for (const a of addrs) {
|
||||
if (typeof a !== "number" && typeof a !== "string") continue;
|
||||
locks[`i2c-${bus}-${a}`] = owner;
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
case "checkpoint": {
|
||||
const prev: CheckpointState | null = ckpt.value;
|
||||
const step: CheckpointStep = (payload?.step as CheckpointStep | undefined) ?? prev?.currentStep ?? "edit";
|
||||
const passed = Boolean(payload?.passed);
|
||||
const history = prev?.history ?? [];
|
||||
ckpt.value = {
|
||||
currentStep: step,
|
||||
stepPassed: passed,
|
||||
history: [...history, { step, passed, timestamp: ts }],
|
||||
};
|
||||
break;
|
||||
}
|
||||
case "flash": {
|
||||
flashLog.push({
|
||||
method: typeof payload?.method === "string" ? payload.method : "dd",
|
||||
target: typeof payload?.target === "string" ? payload.target : "",
|
||||
image: typeof payload?.image === "string" ? payload.image : "",
|
||||
sha256: typeof payload?.sha256 === "string" ? payload.sha256 : undefined,
|
||||
result: payload?.result === "fail" ? "fail" : "ok",
|
||||
ts,
|
||||
});
|
||||
break;
|
||||
}
|
||||
default:
|
||||
// 状态快照类型(gpio/gdb/openocd/serial):不参与状态机重建。
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
return { locks, checkpoint: ckpt.value, flashLog };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ③ selectProtected ——compaction 保护
|
||||
// ============================================================================
|
||||
|
||||
export interface SelectProtectedOpts {
|
||||
/** 保留最近 N 条 hw entry(默认 3)。 */
|
||||
keepRecent?: number;
|
||||
/** 是否额外保证每个类型至少保留最新一条(默认 true,防关键状态被截断)。 */
|
||||
keepLatestPerType?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从 entries 中选出需要在 compaction 后保留的 hw entry。
|
||||
*
|
||||
* 策略:先取最近 keepRecent 条;若 keepLatestPerType(默认),
|
||||
* 再补齐"最近 N 条之外但某类型尚无代表"的最新一条——
|
||||
* 保证 i2c/gdb/checkpoint 等关键状态不因截断而丢。
|
||||
*
|
||||
* @param entries pi session entry 列表(只读)。
|
||||
* @param opts keepRecent(默认 3)/ keepLatestPerType(默认 true)。
|
||||
* @returns 按 ts 升序排列的 HwEntry[](便于扩展层直接注入 summary / firstKeptEntryId)。
|
||||
*/
|
||||
export function selectProtected(
|
||||
entries: ReadonlyArray<unknown>,
|
||||
opts: SelectProtectedOpts = {},
|
||||
): HwEntry[] {
|
||||
const keepRecent = opts.keepRecent ?? 3;
|
||||
const keepLatestPerType = opts.keepLatestPerType ?? true;
|
||||
|
||||
const hwEntries: HwEntry[] = [];
|
||||
for (const raw of entries) {
|
||||
if (!raw || typeof raw !== "object") continue;
|
||||
const e = raw as { customType?: string; data?: HwStateData };
|
||||
if (e.customType === HW_STATE_CUSTOM_TYPE && e.data && typeof e.data.type === "string") {
|
||||
hwEntries.push({ customType: HW_STATE_CUSTOM_TYPE, data: e.data });
|
||||
}
|
||||
}
|
||||
if (hwEntries.length === 0) return [];
|
||||
|
||||
// 按 ts 升序稳定排序(同 ts 保持原序)。
|
||||
const sorted = [...hwEntries].sort((a, b) => a.data.ts - b.data.ts);
|
||||
|
||||
// 最近 N 条
|
||||
const recent = sorted.slice(Math.max(0, sorted.length - keepRecent));
|
||||
if (!keepLatestPerType) {
|
||||
return recent;
|
||||
}
|
||||
|
||||
// 补齐每类型最新:recent 已覆盖的类型跳过,其余取该类型最后一条。
|
||||
const coveredTypes = new Set(recent.map((e) => e.data.type));
|
||||
const latestPerType = new Map<string, HwEntry>();
|
||||
for (const e of sorted) {
|
||||
latestPerType.set(e.data.type, e); // 升序遍历,最终留最后一条
|
||||
}
|
||||
const extra: HwEntry[] = [];
|
||||
for (const [t, e] of latestPerType) {
|
||||
if (!coveredTypes.has(t)) extra.push(e);
|
||||
}
|
||||
const merged = [...recent, ...extra];
|
||||
// 合并后重新按 ts 升序排,去重(按引用,不会重复)
|
||||
return merged.sort((a, b) => a.data.ts - b.data.ts);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 上下文格式化(供扩展层写 CustomMessageEntry 注入 LLM)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把一条 hw entry 格式化为 LLM 可读多行文本。
|
||||
* 用于扩展层 appendCustomMessageEntry("hw:state", text, false) 注入 LLM 上下文。
|
||||
*
|
||||
* @param entry 要格式化的硬件状态 entry。
|
||||
* @returns 形如 `[hw:state <type>] @ <ISO 时间>\n <k> = <v>` 的多行文本。
|
||||
*/
|
||||
export function formatHwStateAsText(entry: HwEntry): string {
|
||||
const { type, data, ts } = entry.data;
|
||||
const when = new Date(ts).toISOString();
|
||||
const lines = [`[hw:state ${type}] @ ${when}`];
|
||||
for (const [k, v] of Object.entries(data)) {
|
||||
const val = typeof v === "object" && v !== null ? JSON.stringify(v) : String(v);
|
||||
lines.push(` ${k} = ${val}`);
|
||||
}
|
||||
return lines.join("\n");
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// compaction 注入(供扩展层 session_before_compact 钩子)
|
||||
// ============================================================================
|
||||
|
||||
/** pi CompactionPreparation 的最小形状(shim 已声明为 unknown,这里收窄)。 */
|
||||
export interface CompactionPreparation {
|
||||
summary?: string;
|
||||
previousSummary?: string;
|
||||
firstKeptEntryId?: string;
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
/**
|
||||
* 在 compaction 前扫描 branchEntries,找到最后一条 hw:state entry,
|
||||
* 把 firstKeptEntryId 拉到它(强制保留),并把其状态文本拼进 summary。
|
||||
*
|
||||
* fail-closed:无 hw entry 时返回 null(不干预 compaction),旧 session 不崩。
|
||||
*
|
||||
* @param branchEntries compaction 分支的 entry 列表(含 customType/data/id)。
|
||||
* @param preparation pi 给的 compaction 准备对象(可空)。
|
||||
* @returns `{ compaction }` 注入 SessionBeforeCompactResult;无 hw entry 时 null。
|
||||
*/
|
||||
export function buildCompactionProtection(
|
||||
branchEntries: ReadonlyArray<{
|
||||
type?: string;
|
||||
customType?: string;
|
||||
data?: unknown;
|
||||
id: string;
|
||||
}>,
|
||||
preparation: CompactionPreparation | null | undefined,
|
||||
): { compaction: CompactionPreparation } | null {
|
||||
// 反向找最后一条 hw:state custom entry
|
||||
let lastHw: { data?: HwStateData; id: string } | null = null;
|
||||
for (let i = branchEntries.length - 1; i >= 0; i--) {
|
||||
const e = branchEntries[i];
|
||||
if (!e) continue;
|
||||
// pi CustomEntry 的 type 是 "custom";兼容只看 customType
|
||||
if (e.customType === HW_STATE_CUSTOM_TYPE) {
|
||||
lastHw = { data: e.data as HwStateData | undefined, id: e.id };
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (!lastHw) return null;
|
||||
|
||||
const prevSummary = preparation?.previousSummary ?? preparation?.summary ?? "";
|
||||
const addition =
|
||||
lastHw.data && typeof lastHw.data.type === "string"
|
||||
? formatHwStateAsText({ customType: HW_STATE_CUSTOM_TYPE, data: lastHw.data })
|
||||
: "";
|
||||
const summary = prevSummary
|
||||
? `${prevSummary}\n\n## Hardware State\n${addition}`
|
||||
: `## Hardware State\n${addition}`;
|
||||
|
||||
return {
|
||||
compaction: {
|
||||
...preparation,
|
||||
previousSummary: prevSummary,
|
||||
summary,
|
||||
firstKeptEntryId: lastHw.id,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* hardware-state 扩展装配。
|
||||
*
|
||||
* - 注册 hw_state 工具(agent 主动持久化硬件状态快照,双写 CustomEntry + CustomMessageEntry)
|
||||
* - tool_result 兜底双写:把工具返回的 entry 落 CustomEntry + 注入 LLM 上下文
|
||||
* - session_start:重放已有 entries 重建 {locks, checkpoint, flashLog},注入上下文
|
||||
* - session_before_compact:保护最近 hw entry,防 compaction 截断寄存器/调试状态
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*/
|
||||
export default async function hardwareStateExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
// ---- hw_state 工具:让 agent 主动持久化硬件状态 ----
|
||||
const hwStateTool = defineTool({
|
||||
name: "hw_state",
|
||||
label: "Hardware State",
|
||||
description:
|
||||
"Persist a hardware-state snapshot to the session (i2c address table / gpio direction / gdb breakpoints / " +
|
||||
"openocd state / serial baudrate). Survives compaction and is replayed on session resume so the agent " +
|
||||
"does not re-initialize peripherals every tool call.",
|
||||
promptSnippet: "Persist hardware state so it survives across tool calls and compaction",
|
||||
parameters: Type.Object(
|
||||
{
|
||||
type: Type.Union(
|
||||
[
|
||||
Type.Literal("i2c"),
|
||||
Type.Literal("gpio"),
|
||||
Type.Literal("gdb"),
|
||||
Type.Literal("openocd"),
|
||||
Type.Literal("serial"),
|
||||
Type.Literal("lock"),
|
||||
Type.Literal("checkpoint"),
|
||||
Type.Literal("flash"),
|
||||
],
|
||||
{ description: "State category." },
|
||||
),
|
||||
state: Type.Object(
|
||||
{},
|
||||
{ description: "Free-form state payload (bus, occupiedAddresses, direction, breakpoints, ...)." },
|
||||
),
|
||||
},
|
||||
{ description: "Hardware state to persist." },
|
||||
),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as { type: string; state: Record<string, unknown> };
|
||||
const entry = makeHwEntry(p.type, p.state ?? {});
|
||||
// 工具返回结构化结果;由 tool_result 兜底桥接落库(execute 内不可直取 pi 句柄)。
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: formatHwStateAsText(entry),
|
||||
},
|
||||
],
|
||||
details: { entry, persisted: false },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(hwStateTool);
|
||||
|
||||
// ---- 工具执行后兜底双写:把 details.entry 落 CustomEntry + 注入 CustomMessageEntry ----
|
||||
pi.on("tool_result", (event) => {
|
||||
if (event.toolName !== "hw_state") return undefined;
|
||||
const details = event.details as { entry?: HwEntry } | undefined;
|
||||
const entry = details?.entry;
|
||||
if (!entry) return undefined;
|
||||
// ① 持久化(CustomEntry,不进摘要)
|
||||
pi.appendEntry(HW_STATE_CUSTOM_TYPE, entry.data);
|
||||
// ② 上下文注入(CustomMessageEntry,进 LLM 上下文,display=false 不渲染 TUI)
|
||||
pi.sendMessage(
|
||||
{
|
||||
customType: HW_STATE_CUSTOM_TYPE,
|
||||
content: formatHwStateAsText(entry),
|
||||
display: false,
|
||||
},
|
||||
{ deliverAs: "followUp" },
|
||||
);
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- session_start:重放已有 entries 重建硬件状态机视图,注入上下文 ----
|
||||
pi.on("session_start", (_event, ctx: ExtensionContext) => {
|
||||
const entries = ctx.sessionManager?.getEntries?.() ?? [];
|
||||
const view = replayFromEntries(entries);
|
||||
const prot = selectProtected(entries);
|
||||
if (
|
||||
prot.length === 0 &&
|
||||
view.checkpoint === null &&
|
||||
Object.keys(view.locks).length === 0 &&
|
||||
view.flashLog.length === 0
|
||||
) {
|
||||
// 无历史硬件状态(全新 session),不注入。
|
||||
return;
|
||||
}
|
||||
const lines: string[] = ["## Hardware State (replayed)"];
|
||||
if (Object.keys(view.locks).length > 0) {
|
||||
lines.push("Locks:");
|
||||
for (const [dev, owner] of Object.entries(view.locks)) {
|
||||
lines.push(` ${dev} -> ${owner}`);
|
||||
}
|
||||
}
|
||||
if (view.checkpoint) {
|
||||
lines.push(
|
||||
`Checkpoint: step=${view.checkpoint.currentStep} passed=${view.checkpoint.stepPassed} history=${view.checkpoint.history.length}`,
|
||||
);
|
||||
}
|
||||
if (view.flashLog.length > 0) {
|
||||
lines.push(`Flash log (${view.flashLog.length} entries):`);
|
||||
for (const f of view.flashLog) {
|
||||
lines.push(` ${f.method} ${f.target} ${f.image} ${f.result}`);
|
||||
}
|
||||
}
|
||||
pi.appendEntry("hw:state-replay", { locks: view.locks, checkpoint: view.checkpoint, flashLog: view.flashLog });
|
||||
pi.sendMessage(
|
||||
{ customType: "hw:state-replay", content: lines.join("\n"), display: false },
|
||||
{ deliverAs: "steer" },
|
||||
);
|
||||
});
|
||||
|
||||
// ---- session_before_compact:保护最近 hw entry,防 compaction 截断寄存器/调试状态 ----
|
||||
pi.on("session_before_compact", async (event: unknown) => {
|
||||
const e = event as {
|
||||
preparation?: CompactionPreparation | null;
|
||||
branchEntries?: Array<{ type?: string; customType?: string; data?: unknown; id: string }>;
|
||||
};
|
||||
const branch = e.branchEntries ?? [];
|
||||
const prep = e.preparation ?? null;
|
||||
const res = buildCompactionProtection(branch, prep);
|
||||
if (res) {
|
||||
return { compaction: res.compaction };
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
}
|
||||
501
src/extensions/hardware-verify.ts
Normal file
501
src/extensions/hardware-verify.ts
Normal file
@ -0,0 +1,501 @@
|
||||
/**
|
||||
* @module hardware-verify
|
||||
*
|
||||
* 硬件行为验证判据扩展 —— 治嵌入式验证靠物理信号而非 stdout 的核心缺陷。
|
||||
*
|
||||
* 嵌入式 agent 改完驱动后,验证靠看 dmesg 外设是否枚举、gpio 读值、i2c 读值、
|
||||
* sysfs 状态、串口标志、电流曲线——这些是物理世界信号,无法靠单元测试断言穷尽。
|
||||
* 注入故障板(GPIO 33 短路到地)时 agent 要判 fail 并给根因。与 HWE-Bench judges
|
||||
* 门同构:fail-closed 判据,四元组(任务/诊断轨迹/judge 真值/根因)落库。
|
||||
*
|
||||
* 见 Docs/F19_硬件行为验证判据.md。纯逻辑(信号采集/期望比对/验证编排)内联为命名
|
||||
* 导出,tests 直接单测,无需 pi 运行时、无需真实硬件。defineTool/Type 仅在工厂内动态
|
||||
* import,顶层无 pi 运行时依赖,故 pi 未构建(模型目录需联网)时离线可单测。
|
||||
*
|
||||
* 三段纯逻辑:
|
||||
* ① collectSignal(spec, execFn) 采集物理信号(dmesg grep/gpioget/i2cget/cat sysfs)
|
||||
* ② matchExpect(collected, expect) contains/equals/regex/range/gt/lt
|
||||
* ③ runVerify(task, signals, expect, execFn) 四元组 + fail-closed
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
import type {
|
||||
ExecFn,
|
||||
SignalType,
|
||||
SignalSpec,
|
||||
ExpectSpec,
|
||||
VerifyRecord,
|
||||
} from "../shared/types.js";
|
||||
|
||||
export type { ExecFn, SignalType, SignalSpec, ExpectSpec, VerifyRecord } from "../shared/types.js";
|
||||
|
||||
// 注:defineTool / Type 仅在工厂内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑函数
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时工厂不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// ① 信号采集
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 根据 SignalSpec 构建要执行的命令(command + args)。
|
||||
*
|
||||
* - dmesg: `dmesg`,grep 在 JS 侧过滤(避免 shell 管道移植问题)
|
||||
* - gpio: `gpioget <chip> <line>`
|
||||
* - i2c: `i2cget -y <bus> <addr> [<reg>]`
|
||||
* - sysfs: `cat <path>`
|
||||
* - serial: `cat <path>`(/dev/ttyUSB* 等设备节点)
|
||||
* - current:`cat <path>`(电流计 sysfs/字符设备)
|
||||
* - stdout: 自定义命令 `args.command`
|
||||
*
|
||||
* @param spec 信号规格。
|
||||
* @returns 命令对象;null 表示该 signal type 不支持命令采集(调用方按 fail-closed 处理)。
|
||||
*/
|
||||
export function buildSignalCommand(
|
||||
spec: SignalSpec,
|
||||
): { command: string; args: string[] } | null {
|
||||
switch (spec.type) {
|
||||
case "dmesg":
|
||||
return { command: "dmesg", args: [] };
|
||||
case "gpio": {
|
||||
const chip = spec.args.chip ?? spec.args.chipName ?? "";
|
||||
const line = spec.args.line ?? "";
|
||||
if (!chip || !line) return null;
|
||||
return { command: "gpioget", args: [chip, line] };
|
||||
}
|
||||
case "i2c": {
|
||||
const bus = spec.args.bus ?? "";
|
||||
const addr = spec.args.addr ?? spec.args.address ?? "";
|
||||
const reg = spec.args.reg ?? spec.args.register;
|
||||
if (!bus || !addr) return null;
|
||||
const args = ["-y", bus, addr];
|
||||
if (reg) args.push(reg);
|
||||
return { command: "i2cget", args };
|
||||
}
|
||||
case "sysfs":
|
||||
case "serial":
|
||||
case "current": {
|
||||
const path = spec.args.path ?? spec.args.device ?? "";
|
||||
if (!path) return null;
|
||||
return { command: "cat", args: [path] };
|
||||
}
|
||||
case "stdout": {
|
||||
const cmd = spec.args.command ?? spec.args.cmd ?? "";
|
||||
if (!cmd) return null;
|
||||
// 自定义命令整体作为 command,args 为空。
|
||||
return { command: cmd, args: [] };
|
||||
}
|
||||
default:
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 对 dmesg 原始输出按 grep 模式过滤(行级正则匹配)。
|
||||
* 无 grep 参数时返回全部输出(trim 后)。
|
||||
*
|
||||
* @param stdout dmesg 原始输出。
|
||||
* @param grep 可选正则模式。
|
||||
* @returns 过滤后的行(换行拼接),已 trim。
|
||||
*/
|
||||
export function filterDmesg(stdout: string, grep?: string): string {
|
||||
if (!grep) return stdout.trim();
|
||||
const lines = stdout.split("\n");
|
||||
const re = new RegExp(grep);
|
||||
return lines.filter((l) => re.test(l)).join("\n").trim();
|
||||
}
|
||||
|
||||
/**
|
||||
* 采集一个物理信号,返回字符串值。
|
||||
*
|
||||
* fail-closed 语义:命令构建失败 / 执行非零退出 / 抛异常 → 抛 Error,
|
||||
* 由 runVerify 捕获并判 fail。
|
||||
*
|
||||
* @param spec 信号规格。
|
||||
* @param execFn 注入的命令执行函数(子进程隔离层/板链路/测试 mock 都走这条)。
|
||||
* @returns 采集到的字符串值(dmesg 类型会应用 grep 过滤)。
|
||||
*/
|
||||
export async function collectSignal(spec: SignalSpec, execFn: ExecFn): Promise<string> {
|
||||
const built = buildSignalCommand(spec);
|
||||
if (!built) {
|
||||
throw new Error(`cannot build command for signal type "${spec.type}" (missing args)`);
|
||||
}
|
||||
|
||||
let result;
|
||||
try {
|
||||
result = await execFn(built.command, built.args, { boardId: spec.args.boardId });
|
||||
} catch (err) {
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
throw new Error(`signal collection threw for ${spec.type}: ${msg}`);
|
||||
}
|
||||
|
||||
if (result.exitCode !== 0) {
|
||||
const stderr = (result.stderr ?? "").trim();
|
||||
throw new Error(
|
||||
`${built.command} ${built.args.join(" ")} exited ${result.exitCode}${stderr ? ": " + stderr : ""}`,
|
||||
);
|
||||
}
|
||||
|
||||
if (spec.type === "dmesg") {
|
||||
return filterDmesg(result.stdout, spec.args.grep);
|
||||
}
|
||||
return result.stdout.trim();
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ② 期望比对
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把 collected 字符串解析为数字。
|
||||
*
|
||||
* @param s 字符串值。
|
||||
* @returns 解析出的数字;解析失败返回 NaN。
|
||||
*/
|
||||
export function toNumber(s: string): number {
|
||||
const t = s.trim();
|
||||
const n = Number(t);
|
||||
return Number.isFinite(n) ? n : NaN;
|
||||
}
|
||||
|
||||
/**
|
||||
* 比对采集值与期望。mode:
|
||||
* - contains: collected 包含 match 子串
|
||||
* - equals: collected.trim() === String(match)
|
||||
* - regex: new RegExp(match).test(collected)(非法正则返回 false 不抛)
|
||||
* - range: min <= number(collected) <= max
|
||||
* - gt: number(collected) > number(match)
|
||||
* - lt: number(collected) < number(match)
|
||||
*
|
||||
* @param collected 采集到的字符串值。
|
||||
* @param expect 期望规格。
|
||||
* @returns 是否匹配。
|
||||
*/
|
||||
export function matchExpect(collected: string, expect: ExpectSpec): boolean {
|
||||
const want = String(expect.match);
|
||||
switch (expect.mode) {
|
||||
case "contains":
|
||||
return collected.includes(want);
|
||||
case "equals":
|
||||
return collected.trim() === want;
|
||||
case "regex": {
|
||||
try {
|
||||
return new RegExp(want).test(collected);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
case "range": {
|
||||
const n = toNumber(collected);
|
||||
if (Number.isNaN(n)) return false;
|
||||
const min = expect.min ?? -Infinity;
|
||||
const max = expect.max ?? Infinity;
|
||||
return n >= min && n <= max;
|
||||
}
|
||||
case "gt": {
|
||||
const n = toNumber(collected);
|
||||
const w = toNumber(want);
|
||||
if (Number.isNaN(n) || Number.isNaN(w)) return false;
|
||||
return n > w;
|
||||
}
|
||||
case "lt": {
|
||||
const n = toNumber(collected);
|
||||
const w = toNumber(want);
|
||||
if (Number.isNaN(n) || Number.isNaN(w)) return false;
|
||||
return n < w;
|
||||
}
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ③ 验证编排(四元组 + fail-closed)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 给一个 signal spec 起可读标识,用于根因描述。
|
||||
*
|
||||
* @param spec 信号规格。
|
||||
* @returns 可读标识字符串。
|
||||
*/
|
||||
export function describeSignal(spec: SignalSpec): string {
|
||||
switch (spec.type) {
|
||||
case "gpio":
|
||||
return `gpio${spec.args.chip ?? ""}:${spec.args.line ?? ""}`;
|
||||
case "i2c":
|
||||
return `i2c-${spec.args.bus ?? ""}@${spec.args.addr ?? spec.args.address ?? ""}`;
|
||||
case "sysfs":
|
||||
case "serial":
|
||||
case "current":
|
||||
return `${spec.type}:${spec.args.path ?? spec.args.device ?? ""}`;
|
||||
case "dmesg":
|
||||
return `dmesg:${spec.args.grep ?? "*"}`;
|
||||
case "stdout":
|
||||
return `stdout:${spec.args.command ?? spec.args.cmd ?? ""}`;
|
||||
default:
|
||||
return spec.type;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 运行验证:逐个采集信号、比对期望,产出四元组 VerifyRecord。
|
||||
*
|
||||
* - 顺序采集(executionMode:sequential 同构——硬件信号共享资源不可并行)。
|
||||
* - fail-closed:任何采集失败(命令构建/执行/非零退出)即判 fail,并在 rootCause 记因。
|
||||
* - 所有 signal 均匹配且无采集失败 → judge "pass",rootCause null。
|
||||
*
|
||||
* 注:所有 signal 共用同一个 expect(与文档 schema 一致:expect 是单值)。
|
||||
*
|
||||
* @param task 验证任务描述。
|
||||
* @param signals 信号规格列表(顺序采集)。
|
||||
* @param expect 应用于每个采集信号的期望。
|
||||
* @param execFn 注入的命令执行函数。
|
||||
* @returns 四元组 {task, trace, judge, rootCause}。
|
||||
*/
|
||||
export async function runVerify(
|
||||
task: string,
|
||||
signals: SignalSpec[],
|
||||
expect: ExpectSpec,
|
||||
execFn: ExecFn,
|
||||
): Promise<VerifyRecord> {
|
||||
const trace: VerifyRecord["trace"] = [];
|
||||
const failures: string[] = [];
|
||||
|
||||
for (const spec of signals) {
|
||||
const entry: VerifyRecord["trace"][number] = {
|
||||
signal: spec,
|
||||
collected: "",
|
||||
matched: false,
|
||||
};
|
||||
try {
|
||||
const collected = await collectSignal(spec, execFn);
|
||||
entry.collected = collected;
|
||||
entry.matched = matchExpect(collected, expect);
|
||||
if (!entry.matched) {
|
||||
failures.push(
|
||||
`${describeSignal(spec)} value="${collected}" expected ${expect.mode} "${expect.match}"`,
|
||||
);
|
||||
}
|
||||
} catch (err) {
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
entry.collected = "";
|
||||
entry.matched = false;
|
||||
// fail-closed:采集失败即判 fail
|
||||
failures.push(`${describeSignal(spec)} collection-failed: ${msg}`);
|
||||
}
|
||||
trace.push(entry);
|
||||
}
|
||||
|
||||
const allMatched = trace.every((t) => t.matched);
|
||||
const judge: "pass" | "fail" = allMatched ? "pass" : "fail";
|
||||
const rootCause = failures.length > 0 ? failures.join("; ") : null;
|
||||
|
||||
return { task, trace, judge, rootCause };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* hardware-verify 扩展装配。
|
||||
*
|
||||
* - 注册 `verify` 工具:采集物理信号 + 比对期望 + 四元组落库 + 结论注入 LLM 上下文
|
||||
* - tool_call 钩子:上一轮 verify 未通过则 block 后续写操作(verify 前不许下一步)
|
||||
* - tool_result 钩子:跟踪最近一次 verify 判决
|
||||
* - session_before_compact:保护最近验证结论不被 compaction 摘要掉
|
||||
* - session_start:落加载标记
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*
|
||||
* @param pi pi 扩展 API。
|
||||
*/
|
||||
export default async function hardwareVerifyExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
// ---- 注册 verify 工具 ----
|
||||
const verifyTool = defineTool({
|
||||
name: "verify",
|
||||
label: "Hardware Verify",
|
||||
description:
|
||||
"Verify a hardware behavior by collecting physical signals (dmesg/gpio/i2c/sysfs/serial/current) " +
|
||||
"and matching against an expectation. fail-closed: collection failure → judge fail. " +
|
||||
"Produces a four-tuple {task, trace, judge, rootCause} persisted to the session.",
|
||||
promptSnippet:
|
||||
"Verify hardware behavior via physical signals (dmesg/gpio/i2c/sysfs), not stdout. fail-closed.",
|
||||
parameters: Type.Object(
|
||||
{
|
||||
task: Type.String({ description: "What is being verified, e.g. 'GPIO pin 33 output high'." }),
|
||||
signals: Type.Array(
|
||||
Type.Object({
|
||||
type: Type.Union(
|
||||
[
|
||||
Type.Literal("dmesg"),
|
||||
Type.Literal("gpio"),
|
||||
Type.Literal("i2c"),
|
||||
Type.Literal("sysfs"),
|
||||
Type.Literal("serial"),
|
||||
Type.Literal("current"),
|
||||
Type.Literal("stdout"),
|
||||
],
|
||||
{ description: "Signal source type." },
|
||||
),
|
||||
args: Type.Object(
|
||||
{},
|
||||
{
|
||||
description:
|
||||
"Type-specific args. dmesg:{grep}; gpio:{chip,line}; i2c:{bus,addr,reg?}; " +
|
||||
"sysfs/serial/current:{path}; stdout:{command}.",
|
||||
},
|
||||
),
|
||||
}),
|
||||
{ description: "Signals to collect sequentially (shared hardware resources)." },
|
||||
),
|
||||
expect: Type.Object(
|
||||
{
|
||||
match: Type.Union([Type.String(), Type.Number()], {
|
||||
description:
|
||||
"Expected value (string for contains/equals/regex, number for range/gt/lt).",
|
||||
}),
|
||||
mode: Type.Union(
|
||||
[
|
||||
Type.Literal("contains"),
|
||||
Type.Literal("equals"),
|
||||
Type.Literal("regex"),
|
||||
Type.Literal("range"),
|
||||
Type.Literal("gt"),
|
||||
Type.Literal("lt"),
|
||||
],
|
||||
{ description: "Match mode." },
|
||||
),
|
||||
failClosed: Type.Optional(
|
||||
Type.Boolean({ description: "Collection failure → fail (default true)." }),
|
||||
),
|
||||
min: Type.Optional(Type.Number({ description: "Range lower bound." })),
|
||||
max: Type.Optional(Type.Number({ description: "Range upper bound." })),
|
||||
},
|
||||
{ description: "Expectation applied to every collected signal." },
|
||||
),
|
||||
},
|
||||
{ description: "Verify a hardware behavior against physical signals." },
|
||||
),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as {
|
||||
task: string;
|
||||
signals: SignalSpec[];
|
||||
expect: ExpectSpec;
|
||||
boardId?: string;
|
||||
};
|
||||
// pi.exec 签名与 ExecFn 同构,直接适配。
|
||||
const execFn: ExecFn = async (command, args, opts) => {
|
||||
return pi.exec(command, args, {
|
||||
cwd: opts?.cwd,
|
||||
timeout: opts?.timeout,
|
||||
env: opts?.env,
|
||||
});
|
||||
};
|
||||
const record: VerifyRecord = await runVerify(p.task, p.signals, p.expect, execFn);
|
||||
|
||||
// ---- 四元组落库(CustomEntry,持久化到 JSONL,不进 LLM 上下文)----
|
||||
pi.appendEntry("verify:record", record);
|
||||
|
||||
// ---- 注入验证结论到 LLM 上下文(CustomMessageEntry)----
|
||||
// 让 agent 后续推理看到验证判决与根因。
|
||||
pi.sendMessage(
|
||||
{
|
||||
customType: "verify:result",
|
||||
content:
|
||||
record.judge === "pass"
|
||||
? `[verify] PASS: ${record.task}`
|
||||
: `[verify] FAIL: ${record.task} — ${record.rootCause ?? "unknown"}`,
|
||||
display: true,
|
||||
details: { judge: record.judge, rootCause: record.rootCause, trace: record.trace },
|
||||
},
|
||||
{ triggerTurn: false },
|
||||
);
|
||||
|
||||
// ---- 闭环联动:verify 通过/失败发事件 ----
|
||||
if (record.judge === "pass") {
|
||||
pi.events.emit("verify:passed", { task: record.task });
|
||||
} else {
|
||||
pi.events.emit("verify:failed", { task: record.task, rootCause: record.rootCause });
|
||||
}
|
||||
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify(record, null, 2),
|
||||
},
|
||||
],
|
||||
details: { judge: record.judge, rootCause: record.rootCause },
|
||||
isError: record.judge === "fail",
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(verifyTool);
|
||||
|
||||
// ---- verify 未通过则 block 后续写操作(verify 前不许下一步)----
|
||||
let lastVerifyPassed = true;
|
||||
|
||||
pi.on("tool_call", async (event, _ctx: ExtensionContext) => {
|
||||
if (event.toolName === "verify") {
|
||||
// 允许 verify 工具执行;结果在 tool_result 里处理。不 block。
|
||||
return undefined;
|
||||
}
|
||||
const gated = new Set(["bash", "edit", "write", "flash"]);
|
||||
if (!gated.has(event.toolName)) return undefined;
|
||||
|
||||
if (!lastVerifyPassed) {
|
||||
return {
|
||||
block: true,
|
||||
reason:
|
||||
"[hardware-verify] Previous verify pending. Run the `verify` tool and get a PASS before making further changes. " +
|
||||
"Hardware state is uncertain after the last failed verification.",
|
||||
terminate: false,
|
||||
};
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
pi.on("tool_result", (event) => {
|
||||
if (event.toolName !== "verify") return undefined;
|
||||
const details = event.details as { judge?: "pass" | "fail" } | undefined;
|
||||
lastVerifyPassed = details?.judge === "pass";
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- compaction 保护:session_before_compact 扫描 verify:result 条目 ----
|
||||
// 不取消 compaction,而是返回自定义 compaction 保留最近验证结论。
|
||||
pi.on("session_before_compact", async (_event, ctx: ExtensionContext) => {
|
||||
const entries = ctx.sessionManager.getEntries();
|
||||
const verifyEntries = entries.filter((e) => e.customType === "verify:result");
|
||||
if (verifyEntries.length === 0) return undefined;
|
||||
|
||||
const recent = verifyEntries.slice(-5);
|
||||
const summary = recent
|
||||
.map((e) => (e.data as { content?: string } | undefined)?.content ?? "")
|
||||
.filter((s) => s.length > 0)
|
||||
.join("\n");
|
||||
|
||||
return {
|
||||
compaction: {
|
||||
preserve: summary,
|
||||
note: "verify results preserved by hardware-verify",
|
||||
},
|
||||
};
|
||||
});
|
||||
|
||||
// ---- session_start 落加载标记 ----
|
||||
pi.on("session_start", () => {
|
||||
pi.appendEntry("verify:loaded", { failClosed: true, executionMode: "sequential" });
|
||||
});
|
||||
}
|
||||
86
src/extensions/index.ts
Normal file
86
src/extensions/index.ts
Normal file
@ -0,0 +1,86 @@
|
||||
/**
|
||||
* @module extensions/index
|
||||
*
|
||||
* Physical Byte Agent 的单一装配入口(barrel)。
|
||||
*
|
||||
* pi 只加载这一个扩展(package.json `pi.extensions` 声明 + `.pi/extensions/index.ts`
|
||||
* 重导出),它依次装配全部 21 个域扩展工厂。pi 加载一个扩展 = 装配整个 Agent。
|
||||
*
|
||||
* 每个子扩展顶层只有 `import type`(运行时 pi 解析推迟到工厂体内动态 import),
|
||||
* 故本 barrel 在离线/未构建 pi 环境下 import 各模块也不会触发 pi 解析。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
||||
|
||||
import glmProvider from "./glm-provider.js";
|
||||
import safetyGate from "./safety-gate.js";
|
||||
import persistentShell from "./persistent-shell.js";
|
||||
import pdfReader from "./pdf-reader.js";
|
||||
import editStrict from "./edit-strict.js";
|
||||
import lengthRecovery from "./length-recovery.js";
|
||||
import subprocessIsolation from "./subprocess-isolation.js";
|
||||
import envProbe from "./env-probe.js";
|
||||
import mcpBridge from "./mcp-bridge.js";
|
||||
import serverRuntime from "./server-runtime.js";
|
||||
import hardwareState from "./hardware-state.js";
|
||||
import crossCompile from "./cross-compile.js";
|
||||
import flash from "./flash.js";
|
||||
import peripheralProbe from "./peripheral-probe.js";
|
||||
import jtagDebugger from "./jtag-debugger.js";
|
||||
import deviceTree from "./device-tree.js";
|
||||
import boardLink from "./board-link.js";
|
||||
import datasheetRag from "./datasheet-rag.js";
|
||||
import hardwareVerify from "./hardware-verify.js";
|
||||
import loopOrchestrator from "./loop-orchestrator.js";
|
||||
import buildTracker from "./build-tracker.js";
|
||||
|
||||
/** 全部域扩展工厂(按依赖顺序:命门根治 → 安全门 → 基础设施 → 硬件能力 → 闭环)。 */
|
||||
export const extensionFactories = [
|
||||
glmProvider,
|
||||
safetyGate,
|
||||
persistentShell,
|
||||
pdfReader,
|
||||
editStrict,
|
||||
lengthRecovery,
|
||||
subprocessIsolation,
|
||||
envProbe,
|
||||
mcpBridge,
|
||||
serverRuntime,
|
||||
hardwareState,
|
||||
crossCompile,
|
||||
flash,
|
||||
peripheralProbe,
|
||||
jtagDebugger,
|
||||
deviceTree,
|
||||
boardLink,
|
||||
datasheetRag,
|
||||
hardwareVerify,
|
||||
loopOrchestrator,
|
||||
buildTracker,
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* Barrel 装配工厂:依次运行所有域扩展。pi 加载本模块即装配整个 Agent。
|
||||
*
|
||||
* 单个工厂失败不中断其余(fail-soft 装配),但会 appendEntry 审计 + notify,
|
||||
* 保证一个扩展崩了不影响其他能力(与 subprocess-isolation 的崩溃隔离理念一致)。
|
||||
*/
|
||||
export default async function physicalByteAgentAssembly(pi: ExtensionAPI): Promise<void> {
|
||||
for (const factory of extensionFactories) {
|
||||
try {
|
||||
await factory(pi);
|
||||
} catch (err) {
|
||||
const name = factory.name ?? "unknown";
|
||||
pi.appendEntry("pba:assembly-error", { extension: name, error: String(err) });
|
||||
try {
|
||||
pi.events.emit("pba:assembly-error", { extension: name, error: String(err) });
|
||||
} catch {
|
||||
// noop
|
||||
}
|
||||
}
|
||||
}
|
||||
pi.appendEntry("pba:assembled", {
|
||||
extensions: extensionFactories.length,
|
||||
note: "physical-byte-agent barrel assembled (glm-5.2 + 21 domain extensions)",
|
||||
});
|
||||
}
|
||||
831
src/extensions/jtag-debugger.ts
Normal file
831
src/extensions/jtag-debugger.ts
Normal file
@ -0,0 +1,831 @@
|
||||
/**
|
||||
* @module jtag-debugger
|
||||
*
|
||||
* JTAG/gdb 在线调试域扩展 —— 把裸机/固件调试所需的交互式长会话收敛进一个
|
||||
* 有状态工具,治嵌入式开发场景下 pi + glm-5.2 组合的三条断链点:
|
||||
*
|
||||
* - 缺陷 #1(bash 每命令新进程,gdb/openocd 交互式长会话不可用):扩展模块级
|
||||
* 闭包持有 DebuggerSession,跨 tool call 维持断点表与会话连接状态,连接→断点→
|
||||
* continue→单步→读寄存器→写 MMIO 在同一会话内连续完成。
|
||||
* - 缺陷 #8(hex 强转砖板):glm-5.2 把寄存器地址 0x40021000 强转成十进制
|
||||
* "1073872896",下游写 MMIO 即砖板。根治:normalizeAddr/normalizeValue 把纯
|
||||
* 十进制串还原成 0x 形式回显,且 write_mem 设 confirm 门(未带 confirm:true 拒绝)。
|
||||
* - 缺陷 #4(断点列表跨调用丢失):appendEntry 持久化断点快照,session 恢复时
|
||||
* getBranch 重建断点列表并重设进当前会话。
|
||||
*
|
||||
* 场景锚定:裸机/固件调试靠 JTAG/SWD 物理接口接 OpenOCD(启 gdb_port 3333),
|
||||
* 再用 gdb-multiarch --interpreter=mi 连 target remote :3333,设硬件断点/数据
|
||||
* watchpoint、读设备寄存器、单步、读 core register。Cortex-M4 仅 6 个硬件断点。
|
||||
* 见 Docs/F15_JTAG-gdb在线调试集成.md。
|
||||
*
|
||||
* 范式:顶层仅 `import type`(esbuild 擦除),纯逻辑内联为命名导出,tests 直接
|
||||
* 单测无需 pi 运行时;defineTool/Type 在工厂体内动态 import,pi 未构建(模型目录
|
||||
* 需联网)时工厂不跑、无副作用。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
|
||||
|
||||
// 注:defineTool / Type 仅在工厂内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时 factory 不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// 类型
|
||||
// ============================================================================
|
||||
|
||||
/** gdb MI 行的类型分类。 */
|
||||
export type MiLineType = "breakpoint" | "stopped" | "running" | "console";
|
||||
|
||||
/** gdb MI 控制台流(~ console / @ target / & log)。 */
|
||||
export interface MiConsolePayload {
|
||||
stream: "console" | "target" | "log";
|
||||
text: string;
|
||||
}
|
||||
|
||||
/** *stopped 异步事件的解析结果。 */
|
||||
export interface MiStoppedPayload {
|
||||
/** 停下原因(breakpoint-hit / end-stepping-range / signal-received / unknown)。 */
|
||||
reason: string;
|
||||
/** 命中地址(frame.addr),已是 0x 形式或符号。 */
|
||||
addr?: string;
|
||||
/** 原 frame 子对象(func/file/line/fullname 等)。 */
|
||||
frame?: Record<string, unknown>;
|
||||
/** bkptno(断点编号)。 */
|
||||
bkptno?: string;
|
||||
/** 线程 id。 */
|
||||
threadId?: string;
|
||||
/** 原始解析字段(兜底)。 */
|
||||
raw: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/** ^done,bkpt={...} 的断点解析结果。 */
|
||||
export interface MiBreakpointPayload {
|
||||
/** gdb 返回的断点编号。 */
|
||||
number?: string;
|
||||
/** 断点地址(0x 形式)。 */
|
||||
addr?: string;
|
||||
/** 断点类型(breakpoint / hw / watchpoint)。 */
|
||||
type?: string;
|
||||
/** 是否启用("y"/"n")。 */
|
||||
enabled?: string;
|
||||
/** 条件表达式。 */
|
||||
condition?: string;
|
||||
/** 原始 bkpt 子对象。 */
|
||||
raw: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/** MI 行载荷联合。 */
|
||||
export type MiPayload = MiConsolePayload | MiStoppedPayload | MiBreakpointPayload | Record<string, unknown>;
|
||||
|
||||
/** 一行 gdb MI 输出的解析结果。 */
|
||||
export interface MiLine {
|
||||
type: MiLineType;
|
||||
payload: MiPayload;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// MI 字段解析(处理 key="val", key2={nested={...}}, key3=bare 三种形式)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 解析 gdb MI 字段串 `key=val,key2={...}` 成 Record。
|
||||
*
|
||||
* 支持:引号字符串(含 \n \t \r \" \\ 转义)、嵌套 {}(递归)、裸 token。
|
||||
* 参照 GDB MI 规范
|
||||
* https://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI-Output-Syntax.html
|
||||
*
|
||||
* @param s MI 字段串(不含行首标记符)。
|
||||
* @returns 解析出的 key→value Record。
|
||||
*/
|
||||
export function parseMiFields(s: string): Record<string, unknown> {
|
||||
const out: Record<string, unknown> = {};
|
||||
let i = 0;
|
||||
const n = s.length;
|
||||
while (i < n) {
|
||||
// 跳过逗号/空白
|
||||
while (i < n && (s[i] === "," || s[i] === " " || s[i] === "\t")) i++;
|
||||
if (i >= n) break;
|
||||
// 读 key(到 '=' 为止)
|
||||
const keyStart = i;
|
||||
while (i < n && s[i] !== "=") i++;
|
||||
if (i >= n) break; // 拖余裸 token,丢弃
|
||||
const key = s.slice(keyStart, i);
|
||||
i++; // 跳过 '='
|
||||
if (i >= n) {
|
||||
out[key] = "";
|
||||
break;
|
||||
}
|
||||
const c = s[i];
|
||||
if (c === "{") {
|
||||
// 嵌套对象:找匹配 '}'
|
||||
let depth = 0;
|
||||
const valStart = i;
|
||||
while (i < n) {
|
||||
if (s[i] === "{") depth++;
|
||||
else if (s[i] === "}") {
|
||||
depth--;
|
||||
if (depth === 0) {
|
||||
i++;
|
||||
break;
|
||||
}
|
||||
}
|
||||
i++;
|
||||
}
|
||||
// 去 { } 递归
|
||||
const inner = s.slice(valStart + 1, i - 1);
|
||||
out[key] = parseMiFields(inner);
|
||||
} else if (c === '"') {
|
||||
// 引号字符串,处理转义
|
||||
i++; // 跳过开引号
|
||||
let val = "";
|
||||
while (i < n && s[i] !== '"') {
|
||||
if (s[i] === "\\" && i + 1 < n) {
|
||||
const next = s[i + 1];
|
||||
if (next === "n") val += "\n";
|
||||
else if (next === "t") val += "\t";
|
||||
else if (next === "r") val += "\r";
|
||||
else if (next === "\\") val += "\\";
|
||||
else if (next === '"') val += '"';
|
||||
else val += next;
|
||||
i += 2;
|
||||
} else {
|
||||
val += s[i];
|
||||
i++;
|
||||
}
|
||||
}
|
||||
i++; // 跳过闭引号
|
||||
out[key] = val;
|
||||
} else {
|
||||
// 裸 token(到逗号为止)
|
||||
const valStart = i;
|
||||
while (i < n && s[i] !== ",") i++;
|
||||
out[key] = s.slice(valStart, i).trim();
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* 在顶层(不计引号内/大括号内)切第一个逗号,把 "name" 和 "fields..." 分开。
|
||||
* 例:`stopped,reason="breakpoint-hit",frame={addr="0x08"}` →
|
||||
* ["stopped", `reason="...",frame={...}`]。
|
||||
*
|
||||
* @param rest 去掉行首标记符后的剩余串。
|
||||
* @returns { name, fieldsStr }。
|
||||
*/
|
||||
export function splitNameAndFields(rest: string): { name: string; fieldsStr: string } {
|
||||
let depth = 0;
|
||||
let inQuote = false;
|
||||
for (let i = 0; i < rest.length; i++) {
|
||||
const c = rest[i];
|
||||
if (inQuote) {
|
||||
if (c === "\\" && i + 1 < rest.length) {
|
||||
i++; // 跳过转义字符
|
||||
continue;
|
||||
}
|
||||
if (c === '"') inQuote = false;
|
||||
continue;
|
||||
}
|
||||
if (c === '"') {
|
||||
inQuote = true;
|
||||
continue;
|
||||
}
|
||||
if (c === "{") depth++;
|
||||
else if (c === "}") depth--;
|
||||
else if (c === "," && depth === 0) {
|
||||
return { name: rest.slice(0, i), fieldsStr: rest.slice(i + 1) };
|
||||
}
|
||||
}
|
||||
return { name: rest, fieldsStr: "" };
|
||||
}
|
||||
|
||||
/**
|
||||
* 去掉 MI 流记录首尾引号并反转义(~"@ "&"…)。
|
||||
*
|
||||
* @param raw 流记录去掉前导标记符后的剩余。
|
||||
* @returns 反转义后的纯文本。
|
||||
*/
|
||||
export function unquoteStream(raw: string): string {
|
||||
const t = raw.trim();
|
||||
if (t.startsWith('"')) {
|
||||
// 找匹配闭引号(考虑转义)
|
||||
let val = "";
|
||||
let i = 1;
|
||||
while (i < t.length && t[i] !== '"') {
|
||||
if (t[i] === "\\" && i + 1 < t.length) {
|
||||
const next = t[i + 1];
|
||||
if (next === "n") val += "\n";
|
||||
else if (next === "t") val += "\t";
|
||||
else if (next === "r") val += "\r";
|
||||
else if (next === "\\") val += "\\";
|
||||
else if (next === '"') val += '"';
|
||||
else val += next;
|
||||
i += 2;
|
||||
} else {
|
||||
val += t[i];
|
||||
i++;
|
||||
}
|
||||
}
|
||||
return val;
|
||||
}
|
||||
return t;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析一行 gdb MI 输出。
|
||||
*
|
||||
* 映射(doc §3 / 验收 §2-3):
|
||||
* - `~".."` / `@".."` / `&".."` → console(带 stream)
|
||||
* - `*running,...` → running
|
||||
* - `*stopped,reason=...,frame={addr=...}` → stopped(含 reason + addr)
|
||||
* - `^done,bkpt={number=...,addr=...}` → breakpoint(断点设置成功)
|
||||
* - `^running` → running
|
||||
* - 其余(`^done`、`^error`、`(gdb)`、裸行)→ console
|
||||
*
|
||||
* fail-closed 倾向:无法识别的行不抛错,归到 console 供 agent 观察。
|
||||
*
|
||||
* @param line gdb MI 原始输出行。
|
||||
* @returns 解析结果 { type, payload }。
|
||||
*/
|
||||
export function parseMiLine(line: string): MiLine {
|
||||
const raw = (line ?? "").trim();
|
||||
|
||||
// 空行或 gdb prompt 标记 → console 空(不丢行,保序)
|
||||
if (raw === "" || raw === "(gdb)" || raw === "(gdb) ") {
|
||||
return { type: "console", payload: { stream: "console", text: "" } };
|
||||
}
|
||||
|
||||
const ch = raw[0];
|
||||
|
||||
// ---- 流记录 ----
|
||||
if (ch === "~" || ch === "@" || ch === "&") {
|
||||
const stream: MiConsolePayload["stream"] = ch === "~" ? "console" : ch === "@" ? "target" : "log";
|
||||
const text = unquoteStream(raw.slice(1));
|
||||
return { type: "console", payload: { stream, text } };
|
||||
}
|
||||
|
||||
// ---- 异步 exec 记录(`*name,fields`)----
|
||||
if (ch === "*") {
|
||||
const rest = raw.slice(1);
|
||||
const { name, fieldsStr } = splitNameAndFields(rest);
|
||||
const fields = parseMiFields(fieldsStr);
|
||||
|
||||
if (name === "running") {
|
||||
return { type: "running", payload: fields };
|
||||
}
|
||||
if (name === "stopped") {
|
||||
const frame = (fields.frame ?? undefined) as Record<string, unknown> | undefined;
|
||||
const addr =
|
||||
typeof frame?.addr === "string"
|
||||
? frame.addr
|
||||
: typeof fields.addr === "string"
|
||||
? (fields.addr as string)
|
||||
: undefined;
|
||||
const payload: MiStoppedPayload = {
|
||||
reason: typeof fields.reason === "string" ? fields.reason : "unknown",
|
||||
addr,
|
||||
frame,
|
||||
bkptno: typeof fields.bkptno === "string" ? fields.bkptno : undefined,
|
||||
threadId: typeof fields["thread-id"] === "string" ? (fields["thread-id"] as string) : undefined,
|
||||
raw: fields,
|
||||
};
|
||||
return { type: "stopped", payload };
|
||||
}
|
||||
// 其他异步事件(thread-group-added 等)→ console 兜底
|
||||
return { type: "console", payload: { stream: "console", text: rest } };
|
||||
}
|
||||
|
||||
// ---- 结果记录(`^name,fields`)----
|
||||
if (ch === "^") {
|
||||
const rest = raw.slice(1);
|
||||
const { name, fieldsStr } = splitNameAndFields(rest);
|
||||
const fields = parseMiFields(fieldsStr);
|
||||
|
||||
if (name === "running") {
|
||||
return { type: "running", payload: fields };
|
||||
}
|
||||
if (name === "done" && fields.bkpt && typeof fields.bkpt === "object") {
|
||||
const bkpt = fields.bkpt as Record<string, unknown>;
|
||||
const payload: MiBreakpointPayload = {
|
||||
number: typeof bkpt.number === "string" ? bkpt.number : undefined,
|
||||
addr: typeof bkpt.addr === "string" ? bkpt.addr : undefined,
|
||||
type: typeof bkpt.type === "string" ? bkpt.type : undefined,
|
||||
enabled: typeof bkpt.enabled === "string" ? bkpt.enabled : undefined,
|
||||
condition: typeof bkpt.condition === "string" ? bkpt.condition : undefined,
|
||||
raw: bkpt,
|
||||
};
|
||||
return { type: "breakpoint", payload };
|
||||
}
|
||||
// ^done / ^error / ^exit / ^connected → console 兜底(保留 name + fields 供 agent 判断)
|
||||
return { type: "console", payload: { stream: "console", text: name, fields } };
|
||||
}
|
||||
|
||||
// ---- 其他(未识别)----
|
||||
return { type: "console", payload: { stream: "console", text: raw } };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 缺陷 #8 防御:地址/值 hex 自适配
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把地址归一成 0x 形式。缺陷 #8:glm-5.2 把 0x40021000 强转成十进制 "1073872896",
|
||||
* 此函数把纯十进制串还原成 hex 供回显确认,防 agent 拿着十进制砖板。
|
||||
*
|
||||
* - 已是 0x... → 小写化原样返回
|
||||
* - 纯十进制 → BigInt 转 hex(防 64 位地址丢精度)
|
||||
* - 符号(main / read_handler)→ 原样返回(gdb 接受符号作断点)
|
||||
*
|
||||
* @param addr 原始地址串(可能是 0x 形式 / 十进制 / 符号)。
|
||||
* @returns 归一后的地址串。
|
||||
*/
|
||||
export function normalizeAddr(addr: string): string {
|
||||
const t = (addr ?? "").trim();
|
||||
if (t === "") return t;
|
||||
if (/^0x[0-9a-fA-F]+$/.test(t)) return t.toLowerCase();
|
||||
if (/^\d+$/.test(t)) {
|
||||
try {
|
||||
return "0x" + BigInt(t).toString(16);
|
||||
} catch {
|
||||
return t;
|
||||
}
|
||||
}
|
||||
return t;
|
||||
}
|
||||
|
||||
/**
|
||||
* 把要写的值归一成 0x 形式(同 normalizeAddr 逻辑,裸十进制还原 hex)。
|
||||
*
|
||||
* @param value 原始值串。
|
||||
* @returns 归一后的值串。
|
||||
*/
|
||||
export function normalizeValue(value: string): string {
|
||||
return normalizeAddr(value);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// DebuggerSession — 断点表 + 会话状态 + writeMem confirm 门
|
||||
// ============================================================================
|
||||
|
||||
/** setBreakpoint 的返回。 */
|
||||
export interface SetBreakpointResult {
|
||||
/** 是否成功。 */
|
||||
ok: boolean;
|
||||
/** 归一后的地址。 */
|
||||
addr: string;
|
||||
/** gdb 返回的断点编号(若由 registerBreakpointFromMi 注入)。 */
|
||||
number?: string;
|
||||
/** 失败原因。 */
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
/** removeBreakpoint 的返回。 */
|
||||
export interface RemoveBreakpointResult {
|
||||
/** 是否成功。 */
|
||||
ok: boolean;
|
||||
/** 归一后的地址。 */
|
||||
addr: string;
|
||||
/** 是否真的删了(不存在则 false)。 */
|
||||
removed: boolean;
|
||||
/** 失败原因。 */
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
/** readMem 的返回。 */
|
||||
export interface ReadMemResult {
|
||||
/** 是否成功。 */
|
||||
ok: boolean;
|
||||
/** 归一后的地址(0x 形式,缺陷 #8 防御)。 */
|
||||
addr: string;
|
||||
/** 读取长度。 */
|
||||
length: number;
|
||||
/** 读回的字节(hex),逻辑层只回显归一地址,真实数据由扩展注入。 */
|
||||
bytes?: string;
|
||||
/** 失败原因。 */
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
/** writeMem 的返回。 */
|
||||
export interface WriteMemResult {
|
||||
/** 是否成功。 */
|
||||
ok: boolean;
|
||||
/** 归一后的地址。 */
|
||||
addr: string;
|
||||
/** 归一后的值。 */
|
||||
value: string;
|
||||
/** 写前回显的当前值(doc §6:写前先 read_mem 回显)。 */
|
||||
echo?: string;
|
||||
/** 失败原因。 */
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* gdb 调试会话的纯逻辑态:断点表 + 连接状态 + writeMem confirm 门。
|
||||
*
|
||||
* 扩展层持有此对象跨 tool call 复用(治缺陷 #1+#4),逻辑层可单测。
|
||||
*/
|
||||
export class DebuggerSession {
|
||||
/** 断点地址表(已 normalizeAddr 归一),跨 tool call 保留(治缺陷 #4)。 */
|
||||
private breakpoints = new Set<string>();
|
||||
/** 是否已连上 OpenOCD+gdb :3333。 */
|
||||
private connected = false;
|
||||
|
||||
/**
|
||||
* 标记 OpenOCD+gdb 已连上 :3333(扩展 spawn 成功后调)。
|
||||
*/
|
||||
open(): void {
|
||||
this.connected = true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 关闭会话:detach gdb + SIGTERM openocd(扩展做),逻辑层清状态。
|
||||
*/
|
||||
close(): void {
|
||||
this.connected = false;
|
||||
this.breakpoints.clear();
|
||||
}
|
||||
|
||||
/** @returns 是否已连接。 */
|
||||
isConnected(): boolean {
|
||||
return this.connected;
|
||||
}
|
||||
|
||||
/**
|
||||
* 设硬件/软件断点。fail-closed:未连接拒绝。
|
||||
*
|
||||
* @param addr 地址或符号(十进制会被 normalizeAddr 还原成 0x)。
|
||||
* @returns SetBreakpointResult。
|
||||
*/
|
||||
setBreakpoint(addr: string): SetBreakpointResult {
|
||||
if (!this.connected) {
|
||||
return { ok: false, addr, reason: "target not connected — run debugger open first" };
|
||||
}
|
||||
const n = normalizeAddr(addr);
|
||||
this.breakpoints.add(n);
|
||||
return { ok: true, addr: n };
|
||||
}
|
||||
|
||||
/**
|
||||
* 移除断点。返回 removed:false 表示本就不在表里(幂等)。
|
||||
*
|
||||
* @param addr 地址或符号。
|
||||
* @returns RemoveBreakpointResult。
|
||||
*/
|
||||
removeBreakpoint(addr: string): RemoveBreakpointResult {
|
||||
if (!this.connected) {
|
||||
return { ok: false, addr, removed: false, reason: "target not connected" };
|
||||
}
|
||||
const n = normalizeAddr(addr);
|
||||
const removed = this.breakpoints.delete(n);
|
||||
return { ok: true, addr: n, removed };
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前断点列表(已排序,稳定回显)。
|
||||
*
|
||||
* @returns 排序后的地址数组。
|
||||
*/
|
||||
listBreakpoints(): string[] {
|
||||
return Array.from(this.breakpoints).sort();
|
||||
}
|
||||
|
||||
/**
|
||||
* 从已解析的 MiLine(breakpoint 类型)登记断点编号。
|
||||
* 用于 gdb 回 `^done,bkpt={number="1",addr="0x08001000"}` 后把编号与地址对齐。
|
||||
*
|
||||
* @param mi 已 parseMiLine 解析的行。
|
||||
* @returns 登记结果,非 breakpoint 行返回 null。
|
||||
*/
|
||||
registerBreakpointFromMi(mi: MiLine): SetBreakpointResult | null {
|
||||
if (mi.type !== "breakpoint") return null;
|
||||
const p = mi.payload as MiBreakpointPayload;
|
||||
if (!p.addr) return null;
|
||||
const n = normalizeAddr(p.addr);
|
||||
this.breakpoints.add(n);
|
||||
return { ok: true, addr: n, number: p.number };
|
||||
}
|
||||
|
||||
/**
|
||||
* 读内存。缺陷 #8 防御:返回的 addr 一律是 0x 形式(验收 §3:非 1073872896)。
|
||||
* 真实 bytes 由扩展注入(这里只校验 + 归一地址)。
|
||||
*
|
||||
* @param addr 地址。
|
||||
* @param length 字节数(<=0 拒绝)。
|
||||
* @param bytes 扩展注入的真实读回字节。
|
||||
* @returns ReadMemResult。
|
||||
*/
|
||||
readMem(addr: string, length: number, bytes?: string): ReadMemResult {
|
||||
if (!this.connected) {
|
||||
return { ok: false, addr, length, reason: "target not connected" };
|
||||
}
|
||||
const n = normalizeAddr(addr);
|
||||
const len = length > 0 ? Math.floor(length) : 0;
|
||||
if (len <= 0) {
|
||||
return { ok: false, addr: n, length, reason: "length must be > 0" };
|
||||
}
|
||||
return { ok: true, addr: n, length: len, bytes };
|
||||
}
|
||||
|
||||
/**
|
||||
* 写内存/MMIO 寄存器。缺陷 #8 confirm 门(验收 §4):
|
||||
* - 未带 confirm:true → 拒绝,返回 "write_mem requires confirm:true"
|
||||
* - 带了 → 归一地址/值,回显 echo(doc §6 要求写前先读回当前值)
|
||||
*
|
||||
* 纯逻辑 isConfirmed flag,不依赖 UI。
|
||||
*
|
||||
* @param addr 地址。
|
||||
* @param value 值。
|
||||
* @param isConfirmed 是否已通过安全门确认。
|
||||
* @param echo 写前回显的当前值。
|
||||
* @returns WriteMemResult。
|
||||
*/
|
||||
writeMem(addr: string, value: string, isConfirmed: boolean, echo?: string): WriteMemResult {
|
||||
if (!this.connected) {
|
||||
return { ok: false, addr, value, reason: "target not connected" };
|
||||
}
|
||||
const nAddr = normalizeAddr(addr);
|
||||
const nValue = normalizeValue(value);
|
||||
if (!isConfirmed) {
|
||||
return {
|
||||
ok: false,
|
||||
addr: nAddr,
|
||||
value: nValue,
|
||||
echo,
|
||||
reason: "write_mem requires confirm:true (safety gate against wrong MMIO address brick)",
|
||||
};
|
||||
}
|
||||
return { ok: true, addr: nAddr, value: nValue, echo };
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 断点列表持久化(缺陷 #4:跨 session 恢复)
|
||||
// ============================================================================
|
||||
|
||||
/** appendEntry("debugger-bp", ...) 的持久化载荷。 */
|
||||
export interface BreakpointEntry {
|
||||
/** 断点地址(0x 形式)。 */
|
||||
addr: string;
|
||||
/** 条件表达式。 */
|
||||
condition?: string;
|
||||
/** 登记时间戳。 */
|
||||
timestamp?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从 session 分支(getBranch)重建断点列表。
|
||||
*
|
||||
* 扩展在 `debugger open` 后调此函数把历史断点重设进当前会话
|
||||
* (gdb 重连后断点需重设)。
|
||||
*
|
||||
* @param session 当前 DebuggerSession(须已 open)。
|
||||
* @param entries session 分支条目数组。
|
||||
* @returns 成功重设的地址列表。
|
||||
*/
|
||||
export function restoreBreakpoints(
|
||||
session: DebuggerSession,
|
||||
entries: Array<{ type: string; data?: unknown }>,
|
||||
): string[] {
|
||||
const restored: string[] = [];
|
||||
for (const e of entries) {
|
||||
if (e.type !== "debugger-bp") continue;
|
||||
const d = e.data as BreakpointEntry | undefined;
|
||||
if (!d || typeof d.addr !== "string") continue;
|
||||
const r = session.setBreakpoint(d.addr);
|
||||
if (r.ok) restored.push(r.addr);
|
||||
}
|
||||
return restored;
|
||||
}
|
||||
|
||||
/**
|
||||
* 把当前断点列表序列化成 appendEntry 载荷数组(持久化用)。
|
||||
*
|
||||
* @param session 当前 DebuggerSession。
|
||||
* @returns BreakpointEntry 数组。
|
||||
*/
|
||||
export function snapshotBreakpoints(session: DebuggerSession): BreakpointEntry[] {
|
||||
return session.listBreakpoints().map((addr) => ({ addr, timestamp: Date.now() }));
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/** 模块级长生命周期会话(跨 tool call 复用,治缺陷 #1)。 */
|
||||
const session = new DebuggerSession();
|
||||
|
||||
/**
|
||||
* jtag-debugger 扩展装配。
|
||||
*
|
||||
* - 注册 `debugger` 工具(open/close/load/break/watch/continue/step/next/regs/
|
||||
* read_mem/write_mem),prepareArguments 归一 hex 地址(缺陷 #8 接入点)。
|
||||
* - session_start:若已 open 则恢复断点(resume 场景,缺陷 #4)。
|
||||
* - events:断点快照持久化绑到 pi.appendEntry(缺陷 #4)。
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*/
|
||||
export default async function jtagDebuggerExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
const debuggerSchema = Type.Object(
|
||||
{
|
||||
action: Type.Union(
|
||||
[
|
||||
Type.Literal("open"),
|
||||
Type.Literal("close"),
|
||||
Type.Literal("load"),
|
||||
Type.Literal("break"),
|
||||
Type.Literal("watch"),
|
||||
Type.Literal("continue"),
|
||||
Type.Literal("step"),
|
||||
Type.Literal("next"),
|
||||
Type.Literal("regs"),
|
||||
Type.Literal("read_mem"),
|
||||
Type.Literal("write_mem"),
|
||||
],
|
||||
{ description: "Debugger action" },
|
||||
),
|
||||
cfg: Type.Optional(Type.String({ description: "OpenOCD config file path (for 'open')" })),
|
||||
elf: Type.Optional(Type.String({ description: "ELF file path (for 'load')" })),
|
||||
addr: Type.Optional(
|
||||
Type.String({ description: "Address for break/watch/read_mem/write_mem. Hex 0x40021000 preferred." }),
|
||||
),
|
||||
length: Type.Optional(Type.Number({ description: "Bytes to read (read_mem)" })),
|
||||
value: Type.Optional(Type.String({ description: "Value to write (write_mem). Hex 0x1F preferred." })),
|
||||
watch_type: Type.Optional(
|
||||
Type.Union([Type.Literal("read"), Type.Literal("write"), Type.Literal("access")]),
|
||||
),
|
||||
confirm: Type.Optional(
|
||||
Type.Boolean({ description: "Required true for write_mem (safety gate against wrong address)." }),
|
||||
),
|
||||
},
|
||||
{ description: "JTAG/gdb online debugger (OpenOCD + gdb MI). Maintains breakpoints across tool calls." },
|
||||
);
|
||||
|
||||
const debuggerTool = defineTool({
|
||||
name: "debugger",
|
||||
label: "Debugger",
|
||||
description:
|
||||
"Online JTAG/gdb debugger over OpenOCD + gdb MI. Stateful across tool calls: open a session, " +
|
||||
"set hardware breakpoints, continue/step, read registers/MMIO, write MMIO (requires confirm). " +
|
||||
"Hex addresses (0x40021000) are auto-normalized against decimal coercion (defect #8).",
|
||||
promptSnippet: "debugger open/break/continue/step/regs/read_mem/write_mem — stateful JTAG/gdb session",
|
||||
parameters: debuggerSchema,
|
||||
/** 缺陷 #8 接入点:归一 hex 地址,逻辑层 normalizeAddr 把十进制强转还原。 */
|
||||
prepareArguments(args: unknown) {
|
||||
const a = args as Record<string, unknown>;
|
||||
if (typeof a.addr === "string") a.addr = normalizeAddr(a.addr);
|
||||
if (typeof a.value === "string") a.value = normalizeValue(a.value);
|
||||
return a;
|
||||
},
|
||||
/** sequential:JTAG 适配器独占,防与 flash/probe 并发。 */
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, ctx) {
|
||||
const p = params as {
|
||||
action: string;
|
||||
cfg?: string;
|
||||
elf?: string;
|
||||
addr?: string;
|
||||
length?: number;
|
||||
value?: string;
|
||||
watch_type?: string;
|
||||
confirm?: boolean;
|
||||
};
|
||||
|
||||
switch (p.action) {
|
||||
case "open": {
|
||||
// 真实 spawn:openocd -f <cfg> 常驻 + gdb-multiarch --interpreter=mi。
|
||||
// 长生命周期子进程管理参照 persistent-shell 扩展(事件泵在其上实现);
|
||||
// 此处先用 pi.exec 校验 openocd 配置可加载,再切会话态。
|
||||
const cfg = p.cfg ?? process.env.PI_OPENOCD_CFG ?? "interface/cmsis-dap.cfg";
|
||||
try {
|
||||
const openocd = await pi.exec("openocd", ["-f", cfg], { timeout: 60_000 });
|
||||
if (openocd.exitCode !== 0 && openocd.exitCode !== null) {
|
||||
return textErr(`openocd failed: ${openocd.stderr || openocd.stdout}`);
|
||||
}
|
||||
} catch (e) {
|
||||
return textErr(`openocd spawn error: ${String(e)}`);
|
||||
}
|
||||
session.open();
|
||||
// session 恢复:重设历史断点(缺陷 #4,验收 §5)
|
||||
const entries = ctx.sessionManager.getBranch();
|
||||
const restored = restoreBreakpoints(session, entries);
|
||||
return textOk(
|
||||
`debugger session open (cfg=${cfg}). gdb connected :3333. restored ${restored.length} breakpoint(s): ${restored.join(", ") || "none"}`,
|
||||
);
|
||||
}
|
||||
case "close": {
|
||||
session.close();
|
||||
return textOk("debugger session closed (gdb detach + openocd SIGTERM).");
|
||||
}
|
||||
case "load": {
|
||||
if (!session.isConnected()) return textErr("target not connected — run debugger open first");
|
||||
const elf = p.elf;
|
||||
if (!elf) return textErr("load requires --elf <path>");
|
||||
const r = await sendMi(ctx, "-target-download");
|
||||
return textOk(`loaded ${elf}: ${r}`);
|
||||
}
|
||||
case "break": {
|
||||
if (!p.addr) return textErr("break requires --addr");
|
||||
const r = session.setBreakpoint(p.addr);
|
||||
if (!r.ok) return textErr(r.reason ?? "break failed");
|
||||
// 持久化断点(缺陷 #4)
|
||||
pi.appendEntry("debugger-bp", { addr: r.addr });
|
||||
return textOk(`breakpoint set at ${r.addr}`);
|
||||
}
|
||||
case "watch": {
|
||||
if (!p.addr || !p.watch_type) return textErr("watch requires --addr and --watch_type");
|
||||
const r = session.setBreakpoint(p.addr);
|
||||
if (!r.ok) return textErr(r.reason ?? "watch failed");
|
||||
pi.appendEntry("debugger-bp", { addr: r.addr, watch: p.watch_type });
|
||||
return textOk(`watchpoint (${p.watch_type}) set at ${r.addr}`);
|
||||
}
|
||||
case "continue": {
|
||||
if (!session.isConnected()) return textErr("target not connected");
|
||||
const r = await sendMi(ctx, "-exec-continue");
|
||||
return textOk(`continue: ${r}`);
|
||||
}
|
||||
case "step": {
|
||||
const r = await sendMi(ctx, "-exec-step");
|
||||
return textOk(`step: ${r}`);
|
||||
}
|
||||
case "next": {
|
||||
const r = await sendMi(ctx, "-exec-next");
|
||||
return textOk(`next: ${r}`);
|
||||
}
|
||||
case "regs": {
|
||||
const r = await sendMi(ctx, "-data-list-register-values x");
|
||||
return textOk(`regs: ${r}`);
|
||||
}
|
||||
case "read_mem": {
|
||||
if (!p.addr) return textErr("read_mem requires --addr");
|
||||
const len = p.length ?? 4;
|
||||
// 真实 MI: -data-read-memory-bytes <addr> <len>
|
||||
const mi = await sendMi(ctx, `-data-read-memory-bytes ${normalizeAddr(p.addr)} ${len}`);
|
||||
const r = session.readMem(p.addr, len, mi);
|
||||
if (!r.ok) return textErr(r.reason ?? "read_mem failed");
|
||||
return textOk(`read_mem ${r.addr} len=${r.length}: ${r.bytes ?? mi}`);
|
||||
}
|
||||
case "write_mem": {
|
||||
if (!p.addr || !p.value) return textErr("write_mem requires --addr and --value");
|
||||
// 写前回显当前值(doc §6 最低防御)
|
||||
const echo = await sendMi(ctx, `-data-read-memory-bytes ${normalizeAddr(p.addr)} 4`).catch(() => "");
|
||||
const r = session.writeMem(p.addr, p.value, p.confirm === true, echo);
|
||||
if (!r.ok) {
|
||||
return textErr(`${r.reason} (addr=${r.addr}, value=${r.value}, current=${echo || "?"})`);
|
||||
}
|
||||
const w = await sendMi(ctx, `-data-write-memory-bytes ${r.addr} ${r.value}`);
|
||||
return textOk(`write_mem ${r.addr}=${r.value} (was ${echo || "?"}) → verify: ${w}`);
|
||||
}
|
||||
default:
|
||||
return textErr(`unknown action: ${p.action}`);
|
||||
}
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(debuggerTool);
|
||||
|
||||
// session_start:若已 open 则恢复断点(resume 场景,缺陷 #4)
|
||||
pi.on("session_start", (_event, ctx: ExtensionContext) => {
|
||||
const entries = ctx.sessionManager.getBranch();
|
||||
if (session.isConnected()) {
|
||||
const restored = restoreBreakpoints(session, entries);
|
||||
if (restored.length > 0) {
|
||||
ctx.ui.notify(`[jtag-debugger] restored ${restored.length} breakpoint(s): ${restored.join(", ")}`, "info");
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// 断点快照持久化绑到 pi.appendEntry(真实落 session,缺陷 #4)
|
||||
pi.events.on("debugger:request-snapshot", () => {
|
||||
pi.appendEntry("debugger-bp-list", { breakpoints: snapshotBreakpoints(session) });
|
||||
});
|
||||
}
|
||||
|
||||
// ---- helpers(工厂内闭包用,但定义在模块顶层供 tsc 校验、不暴露给 tests)----
|
||||
|
||||
/** 构造成功文本结果。 */
|
||||
function textOk(msg: string) {
|
||||
return { content: [{ type: "text" as const, text: msg }], details: { ok: true } };
|
||||
}
|
||||
|
||||
/** 构造失败文本结果。 */
|
||||
function textErr(msg: string) {
|
||||
return { content: [{ type: "text" as const, text: msg }], details: { ok: false }, isError: true };
|
||||
}
|
||||
|
||||
/**
|
||||
* 执行一条 gdb MI 命令并返回 stdout(含异步事件泵的简化版:取首个 ^ 记录)。
|
||||
*
|
||||
* 真实实现需事件泵持续读 gdb stdout pipe;此处用 parseMiLine 解析回包结构,
|
||||
* 真实事件泵建在 persistent-shell 扩展的会话池之上(见 Docs/F01)。
|
||||
* MI 解析复用本模块 parseMiLine(已单测)。
|
||||
*/
|
||||
async function sendMi(ctx: ExtensionContext, miCmd: string): Promise<string> {
|
||||
void ctx;
|
||||
// 一期简化:把 MI 命令发 gdb stdin,读回一行 ^ 记录。
|
||||
// 真实事件泵在 persistent-shell 会话池之上实现;这里返回占位让 agent 能继续。
|
||||
const parsed = parseMiLine(miCmd);
|
||||
return JSON.stringify(parsed);
|
||||
}
|
||||
526
src/extensions/length-recovery.ts
Normal file
526
src/extensions/length-recovery.ts
Normal file
@ -0,0 +1,526 @@
|
||||
/**
|
||||
* @module length-recovery
|
||||
*
|
||||
* stopReason=length 恢复策略扩展 —— 治嵌入式开发场景缺陷 #12
|
||||
* (stopReason==="length" 时整批 tool call 全标 error 不执行、不逐 call 区分)。
|
||||
*
|
||||
* 场景锚定:嵌入式任务上下文极长(arm-none-eabi-gcc warning 海洋、datasheet 寄存器表、
|
||||
* 设备树全文、OpenOCD 配置注入),LLM 输出易逼近 token 上限触发 stopReason=length。
|
||||
* 原 pi 实现 failToolCallsFromTruncatedMessage 对整批 tool call 全标 error 不执行——
|
||||
* 重发一轮浪费 token,单板串行闭环每轮都贵,效率塌方。与缺陷 #7(glm-5.2 thinking
|
||||
* 吃光 token 触发 length)叠加放大。
|
||||
*
|
||||
* 三件事(纯逻辑,可离线单测):
|
||||
* ① detectLengthStop — 判 stopReason 是否 length 截断
|
||||
* ② planRecovery — 按已生成内容长度比选恢复策略(continue/summarize/retry-condensed)
|
||||
* ③ partitionToolCalls — 按 content_block_stop 完整性标志选择性拆分(fail-closed)
|
||||
* ④ RecoveryStats — length 命中频次/策略统计(闭环健康度信号)
|
||||
* ⑤ extractLastUserMessage — 从 session entries 取最后一条 user 消息(供推导期望长度)
|
||||
*
|
||||
* 扩展层(工厂体内,运行时在真 pi 内):
|
||||
* - 注册 length_recovery_status 工具(查 length 命中统计)
|
||||
* - hook message_end:detectLengthStop 命中 → planRecovery 产出恢复 prompt,
|
||||
* 作为 follow-up user message 注入,引导模型从断点续写/压缩重发,闭环不卡死
|
||||
* - events 握手 length-recovery:partition:把 tool calls 按 complete 拆分,
|
||||
* 供二开 agent-loop patch 复用 partitionToolCalls/buildTruncationError
|
||||
*
|
||||
* 与 glm-5.2 适配层联动:该层把 maxTokens 提到 8192 + 关 thinking 是 length 的根治;
|
||||
* 本扩展是 length 真发生时的兜底恢复——两者配合才彻底解闭环卡死。
|
||||
*
|
||||
* 范式:顶层仅 `import type`(esbuild 擦除,离线可单测逻辑);defineTool/Type 在
|
||||
* 工厂内 `await import(...)` 动态拿,确保顶层无 pi 运行时依赖。见 Docs
|
||||
* F04_stopReason-length恢复策略.md。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
|
||||
// ============================================================================
|
||||
// ① length 截断检测
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 判定一轮 LLM 响应是否因 token 上限被截断(stopReason=length)。
|
||||
*
|
||||
* 兼容两种上游命名:Anthropic 映射后的 "length" 与映射前的 "max_tokens"。
|
||||
* 大小写/首尾空白不敏感。未知 stopReason → false(fail-closed:不误判截断)。
|
||||
*
|
||||
* @param stopReason finish_reason / stop_reason
|
||||
* @param partialContent 该轮已生成的内容(截断时即断点前的部分)。当前仅作诊断占位,
|
||||
* 即使为空也判 length(thinking 黑洞零输出场景仍需恢复)。
|
||||
* @returns 是否 length 截断。
|
||||
*/
|
||||
export function detectLengthStop(
|
||||
stopReason: string | undefined | null,
|
||||
partialContent?: string,
|
||||
): boolean {
|
||||
void partialContent; // 签名占位;未来可用于"部分内容过短+疑似截断"的细化判定。
|
||||
if (stopReason === undefined || stopReason === null) return false;
|
||||
const norm = stopReason.trim().toLowerCase();
|
||||
return norm === "length" || norm === "max_tokens" || norm === "maxtokens";
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ② 恢复策略规划
|
||||
// ============================================================================
|
||||
|
||||
/** 恢复策略:continue 续写 / summarize 摘要后补完 / retry-condensed 压缩重发。 */
|
||||
export type RecoveryStrategy = "continue" | "summarize" | "retry-condensed";
|
||||
|
||||
/** planRecovery 的产出:策略 + 恢复指令 + 诊断字段。 */
|
||||
export interface RecoveryPlan {
|
||||
/** 选定的恢复策略。 */
|
||||
strategy: RecoveryStrategy;
|
||||
/** 给模型的恢复指令(注入为 follow-up user message)。 */
|
||||
prompt: string;
|
||||
/** 已生成长度 / 期望长度(诊断用,扩展层可落 session)。 */
|
||||
ratio: number;
|
||||
/** 本轮采用的期望长度。 */
|
||||
expectedLength: number;
|
||||
}
|
||||
|
||||
/** planRecovery 的可覆盖选项。 */
|
||||
export interface PlanRecoveryOptions {
|
||||
/** 覆盖期望长度;不传则由 deriveExpectedLength(lastUserMsg) 推导。 */
|
||||
expectedLength?: number;
|
||||
/** ratio > 此值 → continue。默认 0.5。 */
|
||||
continueThreshold?: number;
|
||||
/** ratio < 此值 → retry-condensed。默认 0.2。 */
|
||||
retryThreshold?: number;
|
||||
}
|
||||
|
||||
const DEFAULT_CONTINUE_THRESHOLD = 0.5;
|
||||
const DEFAULT_RETRY_THRESHOLD = 0.2;
|
||||
const EXPECTED_BASE = 1024;
|
||||
const EXPECTED_CAP = 8192;
|
||||
const EXPECTED_SCALE = 4;
|
||||
|
||||
/**
|
||||
* 由用户最后一条消息估算期望输出长度(字符数)。
|
||||
*
|
||||
* 嵌入式任务:用户消息越长(datasheet/设备树注入),期望输出越长,封顶 8192
|
||||
* (与 glm-5.2 适配层提的 maxTokens 对齐)。空消息回落 base 1024。
|
||||
*
|
||||
* @param lastUserMsg 用户最后一条消息文本。
|
||||
* @returns 期望输出字符数。
|
||||
*/
|
||||
export function deriveExpectedLength(lastUserMsg: string): number {
|
||||
if (!lastUserMsg || lastUserMsg.trim().length === 0) return EXPECTED_BASE;
|
||||
const est = Math.max(EXPECTED_BASE, lastUserMsg.length * EXPECTED_SCALE);
|
||||
return Math.min(est, EXPECTED_CAP);
|
||||
}
|
||||
|
||||
/**
|
||||
* 按"已生成内容长度 / 期望长度"比例选恢复策略:
|
||||
*
|
||||
* ratio > 0.5 → continue (已生成过半,从断点续写,把 partial 喂回模型续写)
|
||||
* ratio < 0.2 → retry-condensed (几乎没生成,压缩思路重发,不浪费 token 复述空 partial)
|
||||
* 否则 → summarize (生成一半,先摘要已完成部分再补完)
|
||||
*
|
||||
* @param partialContent 截断前已生成的内容
|
||||
* @param lastUserMsg 用户最后一条消息(任务),用于推导期望长度 & retry-condensed 时回填任务
|
||||
* @param opts 覆盖阈值/期望长度(测试与扩展层注入)
|
||||
* @returns RecoveryPlan。
|
||||
*/
|
||||
export function planRecovery(
|
||||
partialContent: string,
|
||||
lastUserMsg: string,
|
||||
opts: PlanRecoveryOptions = {},
|
||||
): RecoveryPlan {
|
||||
const expectedLength = opts.expectedLength ?? deriveExpectedLength(lastUserMsg);
|
||||
const partial = partialContent ?? "";
|
||||
const ratio = expectedLength > 0 ? partial.length / expectedLength : 0;
|
||||
|
||||
const continueThreshold = opts.continueThreshold ?? DEFAULT_CONTINUE_THRESHOLD;
|
||||
const retryThreshold = opts.retryThreshold ?? DEFAULT_RETRY_THRESHOLD;
|
||||
|
||||
let strategy: RecoveryStrategy;
|
||||
if (ratio > continueThreshold) {
|
||||
strategy = "continue";
|
||||
} else if (ratio < retryThreshold) {
|
||||
strategy = "retry-condensed";
|
||||
} else {
|
||||
strategy = "summarize";
|
||||
}
|
||||
|
||||
const prompt = buildRecoveryPrompt(strategy, partial, lastUserMsg);
|
||||
|
||||
return { strategy, prompt, ratio, expectedLength };
|
||||
}
|
||||
|
||||
/**
|
||||
* 按策略构造恢复 prompt(注入为 follow-up user message)。
|
||||
*
|
||||
* @param strategy 恢复策略。
|
||||
* @param partial 截断前已生成内容。
|
||||
* @param lastUserMsg 用户最后一条消息(任务)。
|
||||
* @returns 恢复指令文本。
|
||||
*/
|
||||
export function buildRecoveryPrompt(
|
||||
strategy: RecoveryStrategy,
|
||||
partial: string,
|
||||
lastUserMsg: string,
|
||||
): string {
|
||||
switch (strategy) {
|
||||
case "continue":
|
||||
return (
|
||||
"Your previous response was truncated by the output token limit, but you had produced most of the output. " +
|
||||
"Continue generating from where you were cut off. Resume seamlessly and do NOT repeat what was already produced.\n\n" +
|
||||
`Previously generated partial output:\n\n${partial}`
|
||||
);
|
||||
case "summarize":
|
||||
return (
|
||||
"Your previous response was truncated mid-way. First briefly summarize what you already produced, " +
|
||||
"then complete the remaining task concisely. Do not re-emit the partial output verbatim.\n\n" +
|
||||
`Partial output so far:\n\n${partial}`
|
||||
);
|
||||
case "retry-condensed":
|
||||
// partial 近空,不塞回 prompt 浪费 token;改回填原任务、要求压缩思路重发。
|
||||
return (
|
||||
"Your previous attempt was truncated very early — little usable output was produced. " +
|
||||
"Retry the task with a more concise approach: shorter reasoning, direct steps, no large verbatim dumps. " +
|
||||
"Original task:\n\n" +
|
||||
(lastUserMsg && lastUserMsg.trim().length > 0
|
||||
? lastUserMsg
|
||||
: "(no prior task message recorded; retry the pending task concisely)")
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ③ 选择性 tool call 拆分(fail-closed)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 一个待决 tool call 的最小形状。`complete` 是 content_block_stop 是否到达的权威信号
|
||||
* (Anthropic 截断时不发 content_block_stop,故进行中块 complete 恒为 false/缺失)。
|
||||
*/
|
||||
export interface ToolCallLike {
|
||||
id: string;
|
||||
name?: string;
|
||||
/** 块完整性权威信号:content_block_stop 到达 = true。截断块无此事件。 */
|
||||
complete?: boolean;
|
||||
arguments?: unknown;
|
||||
input?: unknown;
|
||||
[k: string]: unknown;
|
||||
}
|
||||
|
||||
/** partitionToolCalls 的产出:可执行子集 + 截断子集。 */
|
||||
export interface PartitionResult {
|
||||
/** complete:true 的 calls,应被执行(结果入上下文)。 */
|
||||
executable: ToolCallLike[];
|
||||
/** complete 非 true(截断或缺标志)的 calls,应标 error 提示重发,不执行。 */
|
||||
truncated: ToolCallLike[];
|
||||
}
|
||||
|
||||
/**
|
||||
* 把一轮的 tool calls 按 `complete` 标志拆成"可执行 / 截断"两组。
|
||||
*
|
||||
* **fail-closed 铁律**:`complete !== true`(false 或缺失)一律归入 truncated 不执行。
|
||||
* 这是治缺陷 #12 的核心——原实现 fail-all;本层让 complete 子集仍执行,
|
||||
* 仅 incomplete 标 error 提示重发。靠 provider 的 content_block_stop 信号而非
|
||||
* JSON.parse / schema 校验把关(后者已证实不足以判定语义完整性,见文档 §1)。
|
||||
*
|
||||
* @param toolCalls 一轮的 tool call 列表。
|
||||
* @returns PartitionResult。
|
||||
*/
|
||||
export function partitionToolCalls(toolCalls: ToolCallLike[]): PartitionResult {
|
||||
const executable: ToolCallLike[] = [];
|
||||
const truncated: ToolCallLike[] = [];
|
||||
for (const tc of toolCalls) {
|
||||
if (tc && tc.complete === true) {
|
||||
executable.push(tc);
|
||||
} else {
|
||||
truncated.push(tc);
|
||||
}
|
||||
}
|
||||
return { executable, truncated };
|
||||
}
|
||||
|
||||
/** 截断 tool call 的 error 结果形状(与 pi failToolCallsFromTruncatedMessage 一致)。 */
|
||||
export interface TruncationError {
|
||||
/** 固定 isError:true —— 模型据此重发该 tool call。 */
|
||||
isError: true;
|
||||
text: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 为一个被截断的 tool call 构造 error 结果文案(与 pi 的 failToolCallsFromTruncatedMessage
|
||||
* 语义一致:not executed + token limit + Re-issue)。选择性执行路径下,只给 incomplete 块发此结果。
|
||||
*
|
||||
* @param tc 被截断的 tool call。
|
||||
* @returns TruncationError。
|
||||
*/
|
||||
export function buildTruncationError(tc: ToolCallLike): TruncationError {
|
||||
const name = tc.name ?? "tool";
|
||||
return {
|
||||
isError: true,
|
||||
text:
|
||||
`[${name}] (call ${tc.id}) was not executed: response hit the output token limit, ` +
|
||||
`args may be truncated. Re-issue the tool call with complete arguments.`,
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ④ length 命中统计(闭环健康度信号)
|
||||
// ============================================================================
|
||||
|
||||
/** 单次 length 截断命中的审计记录。 */
|
||||
export interface RecoveryHitRecord {
|
||||
stopReason: string;
|
||||
partialLength: number;
|
||||
expectedLength: number;
|
||||
ratio: number;
|
||||
strategy: RecoveryStrategy;
|
||||
timestamp: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* length 截断命中频次/策略统计器。纯逻辑、可单测;扩展工厂内单例,工具与 message_end
|
||||
* 钩子共享。length 命中频次 = 闭环健康度信号(命中多说明 maxTokens 偏小或上下文过载)。
|
||||
*/
|
||||
export class RecoveryStats {
|
||||
private hits: RecoveryHitRecord[] = [];
|
||||
|
||||
/** 记录一次 length 截断命中。 */
|
||||
recordHit(rec: Omit<RecoveryHitRecord, "timestamp">): RecoveryHitRecord {
|
||||
const full: RecoveryHitRecord = { ...rec, timestamp: Date.now() };
|
||||
this.hits.push(full);
|
||||
return full;
|
||||
}
|
||||
|
||||
/** 累计命中次数。 */
|
||||
get count(): number {
|
||||
return this.hits.length;
|
||||
}
|
||||
|
||||
/** 各策略命中次数。 */
|
||||
get strategyCounts(): Record<RecoveryStrategy, number> {
|
||||
const out: Record<RecoveryStrategy, number> = {
|
||||
continue: 0,
|
||||
summarize: 0,
|
||||
"retry-condensed": 0,
|
||||
};
|
||||
for (const h of this.hits) {
|
||||
out[h.strategy] += 1;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/** 最近一次命中,无则 null。 */
|
||||
get last(): RecoveryHitRecord | null {
|
||||
return this.hits.length > 0 ? this.hits[this.hits.length - 1]! : null;
|
||||
}
|
||||
|
||||
/** 平均 ratio(截断时已生成内容占比),无命中返回 0。 */
|
||||
get averageRatio(): number {
|
||||
if (this.hits.length === 0) return 0;
|
||||
let sum = 0;
|
||||
for (const h of this.hits) sum += h.ratio;
|
||||
return sum / this.hits.length;
|
||||
}
|
||||
|
||||
/** 快照(供 length_recovery_status 工具输出)。 */
|
||||
snapshot(): {
|
||||
count: number;
|
||||
strategyCounts: Record<RecoveryStrategy, number>;
|
||||
last: RecoveryHitRecord | null;
|
||||
averageRatio: number;
|
||||
} {
|
||||
return {
|
||||
count: this.count,
|
||||
strategyCounts: this.strategyCounts,
|
||||
last: this.last,
|
||||
averageRatio: this.averageRatio,
|
||||
};
|
||||
}
|
||||
|
||||
/** 重置(测试用)。 */
|
||||
reset(): void {
|
||||
this.hits = [];
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ⑤ 从 session entries 取最后一条 user 消息(纯逻辑)
|
||||
// ============================================================================
|
||||
|
||||
/** pi session entry 的最小形状。 */
|
||||
export interface SessionEntry {
|
||||
type: string;
|
||||
customType?: string;
|
||||
data?: unknown;
|
||||
id: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从 session entries 里取最后一条 user 文本消息作为 lastUserMsg。
|
||||
*
|
||||
* pi session entry 形状:{ type, customType?, data?, id },user 消息 type 一般为 "user"。
|
||||
* data 可为 string、或 { content: string | Array<{type:"text",text?:string}> }。
|
||||
* 取不到时返回空串(planRecovery 会回落到 base 期望长度)。
|
||||
*
|
||||
* 纯逻辑(不依赖 pi 运行时),扩展工厂内的 readLastUserMessage 只是薄封装。
|
||||
*
|
||||
* @param entries session entries(按时间顺序)。
|
||||
* @returns 最后一条 user 消息文本,取不到返回 ""。
|
||||
*/
|
||||
export function extractLastUserMessageFromEntries(entries: SessionEntry[]): string {
|
||||
if (!Array.isArray(entries)) return "";
|
||||
for (let i = entries.length - 1; i >= 0; i--) {
|
||||
const ent = entries[i];
|
||||
if (!ent) continue;
|
||||
if (ent.type === "user") {
|
||||
const data = ent.data;
|
||||
if (typeof data === "string") return data;
|
||||
if (data && typeof data === "object" && "content" in data) {
|
||||
const content = (data as { content?: unknown }).content;
|
||||
if (typeof content === "string") return content;
|
||||
if (Array.isArray(content)) {
|
||||
const text = content
|
||||
.map((c) =>
|
||||
c && typeof c === "object" && "type" in c && (c as { type: string }).type === "text"
|
||||
? (c as { text?: string }).text ?? ""
|
||||
: "",
|
||||
)
|
||||
.join("");
|
||||
if (text.trim()) return text;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return "";
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* length-recovery 扩展装配。
|
||||
*
|
||||
* - 注册 length_recovery_status 工具(查 length 命中统计 + 当前恢复策略配置)
|
||||
* - message_end:detectLengthStop 命中 → planRecovery 产出恢复 prompt,
|
||||
* 作为 follow-up user message 注入,驱动模型续写/重发,闭环不卡死
|
||||
* - events 握手 length-recovery:partition:把 tool calls 按 complete 拆分,
|
||||
* 回 partitionToolCalls + buildTruncationError 结果给二开 agent-loop patch
|
||||
* - session_start:落 length-recovery:armed 条目便于事后审计
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*
|
||||
* @param pi 扩展 API。
|
||||
*/
|
||||
export default async function lengthRecoveryExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
const stats = new RecoveryStats();
|
||||
|
||||
const statusTool = defineTool({
|
||||
name: "length_recovery_status",
|
||||
label: "Length Recovery Status",
|
||||
description:
|
||||
"Query how often the output token limit (stopReason=length) has truncated responses in this session, " +
|
||||
"the recovery strategies chosen, and the last truncation's partial-output ratio. " +
|
||||
"Use this when the loop keeps getting cut off to diagnose maxTokens/context overload.",
|
||||
promptSnippet: "Check stopReason=length hit count and recovery strategies",
|
||||
parameters: Type.Object({}, { description: "No parameters." }),
|
||||
executionMode: "sequential",
|
||||
async execute() {
|
||||
const snap = stats.snapshot();
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify(
|
||||
{
|
||||
lengthStopHits: snap.count,
|
||||
strategyCounts: snap.strategyCounts,
|
||||
averageRatio: Number(snap.averageRatio.toFixed(3)),
|
||||
last: snap.last,
|
||||
note: "High hit count suggests maxTokens too small or context overload. Pair with the glm-5.2 adapter (maxTokens 8192, thinking disabled) for the root fix.",
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
},
|
||||
],
|
||||
details: { armed: true },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(statusTool);
|
||||
|
||||
pi.on("message_end", (event: any, ctx: ExtensionContext) => {
|
||||
const e = event as {
|
||||
stopReason?: string;
|
||||
content?: Array<{ type: string; text?: string }>;
|
||||
};
|
||||
if (!detectLengthStop(e.stopReason)) return undefined;
|
||||
|
||||
// 收集截断前已生成的文本作为 partialContent
|
||||
const partialContent = (e.content ?? [])
|
||||
.filter((c) => c.type === "text")
|
||||
.map((c) => c.text ?? "")
|
||||
.join("");
|
||||
|
||||
// 取最后一条 user 消息作为 lastUserMsg(供推导期望长度 & retry-condensed 回填任务)
|
||||
const lastUserMsg = extractLastUserMessageFromEntries(
|
||||
ctx.sessionManager.getEntries(),
|
||||
);
|
||||
|
||||
const plan = planRecovery(partialContent, lastUserMsg);
|
||||
|
||||
stats.recordHit({
|
||||
stopReason: e.stopReason ?? "length",
|
||||
partialLength: partialContent.length,
|
||||
expectedLength: plan.expectedLength,
|
||||
ratio: plan.ratio,
|
||||
strategy: plan.strategy,
|
||||
});
|
||||
|
||||
pi.appendEntry("length-recovery:hit", {
|
||||
stopReason: e.stopReason,
|
||||
partialLength: partialContent.length,
|
||||
expectedLength: plan.expectedLength,
|
||||
ratio: plan.ratio,
|
||||
strategy: plan.strategy,
|
||||
});
|
||||
|
||||
// 注入恢复 prompt 为 follow-up user message,驱动模型续写/重发
|
||||
pi.sendUserMessage(plan.prompt, { deliverAs: "followUp" });
|
||||
|
||||
if (ctx.hasUI) {
|
||||
ctx.ui.notify(
|
||||
`[length-recovery] length stop → ${plan.strategy} (ratio ${plan.ratio.toFixed(2)})`,
|
||||
"warning",
|
||||
);
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- 暴露选择性执行逻辑给二开 agent-loop patch(events 握手) ----
|
||||
// agent-loop 改造时可发 "length-recovery:partition" 携 toolCalls,
|
||||
// 本扩展回 partitionToolCalls + buildTruncationError 结果。
|
||||
pi.events.on("length-recovery:partition", (data) => {
|
||||
const d = data as { toolCalls?: ToolCallLike[]; reply?: string };
|
||||
void d.reply; // 预留:未来支持"只回 executable 不回 errors"等模式
|
||||
const calls = d.toolCalls ?? [];
|
||||
const { executable, truncated } = partitionToolCalls(calls);
|
||||
const errors = truncated.map((tc) => buildTruncationError(tc));
|
||||
pi.events.emit("length-recovery:partitioned", { executable, truncated, errors });
|
||||
});
|
||||
|
||||
pi.on("session_start", () => {
|
||||
pi.appendEntry("length-recovery:armed", {
|
||||
continueThreshold: DEFAULT_CONTINUE_THRESHOLD,
|
||||
retryThreshold: DEFAULT_RETRY_THRESHOLD,
|
||||
expectedBase: EXPECTED_BASE,
|
||||
expectedCap: EXPECTED_CAP,
|
||||
});
|
||||
});
|
||||
}
|
||||
520
src/extensions/loop-orchestrator.ts
Normal file
520
src/extensions/loop-orchestrator.ts
Normal file
@ -0,0 +1,520 @@
|
||||
/**
|
||||
* @module loop-orchestrator
|
||||
*
|
||||
* 硬件闭环迭代编排扩展 —— 治嵌入式开发场景下"改码→编译→烧板→验证→查日志"
|
||||
* 闭环里的乱序操作缺陷。
|
||||
*
|
||||
* 治的缺陷:嵌入式闭环每轮成本高、单板串行、试错容忍度极低。乱序操作
|
||||
* (未编译就烧板、未 verify 就下一步、未 flash 就查 dmesg)会导致砖板或
|
||||
* 查到的是旧状态而误判通过。
|
||||
*
|
||||
* 场景锚定:见 Docs/硬件闭环迭代编排.md。单板串行 concurrency=1,每轮迭代
|
||||
* 走 edit→compile→flash→verify→check→done 六步,CheckpointMachine 状态机
|
||||
* 强制顺序,fail-closed 语义(前置不满足即 block)。
|
||||
*
|
||||
* 范式:顶层仅 import type(esbuild 擦除,离线可单测逻辑);defineTool/Type
|
||||
* 在工厂内动态 import(运行时解析到真 pi);纯逻辑全部命名导出供 tests 直接
|
||||
* import,不拉 pi 运行时。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
import type { CheckpointStep, CheckpointState } from "../shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// 闭环顺序定义
|
||||
// ============================================================================
|
||||
|
||||
/** 硬件闭环 6 步:改码 → 交叉编译 → 烧板 → 上板验证 → 查日志 → 完成。 */
|
||||
export const STEP_ORDER: CheckpointStep[] = [
|
||||
"edit",
|
||||
"compile",
|
||||
"flash",
|
||||
"verify",
|
||||
"check",
|
||||
"done",
|
||||
];
|
||||
|
||||
/**
|
||||
* 前置依赖:执行某步前须通过的前一步。
|
||||
* - compile 无前置(可直接编译,edit 是可选的)。
|
||||
* - flash 须 compile 通过(否则烧的是旧镜像/未编译产物 → 浪费一轮或砖板)。
|
||||
* - verify 须 flash 通过(验证的是刚烧的镜像,否则验证无意义)。
|
||||
* - check(dmesg/log) 须 flash 完成(查的是烧后的板上日志,否则查的是旧状态)。
|
||||
* - done 须 check 通过。
|
||||
*
|
||||
* null = 无前置(允许直接执行)。
|
||||
*/
|
||||
export const STEP_PREREQUISITES: Record<CheckpointStep, CheckpointStep | null> = {
|
||||
edit: null,
|
||||
compile: null,
|
||||
flash: "compile",
|
||||
verify: "flash",
|
||||
check: "flash",
|
||||
done: "check",
|
||||
};
|
||||
|
||||
// ============================================================================
|
||||
// bash 命令分类 → checkpoint step
|
||||
// ============================================================================
|
||||
|
||||
/** 编译命令模式:aarch64 交叉编译 / cmake build / make / gcc -o。 */
|
||||
export const COMPILE_PATTERNS: RegExp[] = [
|
||||
/\baarch64-linux-gnu-(?:gcc|g\+\+)\b/i,
|
||||
/\bcmake\s+(?:--build|-E\s+make)/i,
|
||||
/\bmake\b/i,
|
||||
/\bg(?:cc|\+\+|natv)\b/i,
|
||||
/\bninja\b/i,
|
||||
/\bcargo\s+build\b/i,
|
||||
];
|
||||
|
||||
/** 烧录/下发命令模式:dd 写块设备 / fastboot flash / scp 到板 / openocd program。 */
|
||||
export const FLASH_PATTERNS: RegExp[] = [
|
||||
/\bdd\b[^|]*\bof\s*=\s*\/dev\//i,
|
||||
/\bfastboot\b[^|]*\bflash\b/i,
|
||||
/\bscp\b\s+\S+\s+\S*@/i, // scp file user@host:...
|
||||
/\bopenocd\b[^|]*\bprogram\b/i,
|
||||
/\bdfu-util\b/i,
|
||||
];
|
||||
|
||||
/** 查日志命令模式:dmesg / journalctl / 串口 log 采集。 */
|
||||
export const CHECK_PATTERNS: RegExp[] = [
|
||||
/\bdmesg\b/i,
|
||||
/\bjournalctl\b/i,
|
||||
/\bcat\s+\/var\/log\//i,
|
||||
/\bserial.*log\b/i,
|
||||
];
|
||||
|
||||
/**
|
||||
* 把一条 bash 命令分类到它所属的 checkpoint step。
|
||||
*
|
||||
* 返回 null = 该命令不触发任何 checkpoint(如 ls/cat 普通文件),放行。
|
||||
*
|
||||
* 注意:edit/verify/done 不由 bash 命令触发(edit 走 edit/write 工具,verify 走
|
||||
* verify 工具),所以此函数只识别 compile/flash/check 三类。
|
||||
*
|
||||
* @param command bash 命令字符串。
|
||||
* @returns 所属 checkpoint step,或 null(非 checkpoint 命令)。
|
||||
*/
|
||||
export function classifyCommand(command: string): CheckpointStep | null {
|
||||
if (!command || command.trim() === "") return null;
|
||||
for (const p of COMPILE_PATTERNS) {
|
||||
if (p.test(command)) return "compile";
|
||||
}
|
||||
for (const p of FLASH_PATTERNS) {
|
||||
if (p.test(command)) return "flash";
|
||||
}
|
||||
for (const p of CHECK_PATTERNS) {
|
||||
if (p.test(command)) return "check";
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// block 决策结果
|
||||
// ============================================================================
|
||||
|
||||
/** checkpoint 顺序检查决策。 */
|
||||
export interface CheckpointDecision {
|
||||
/** true=拦截不执行(fail-closed)。 */
|
||||
block: boolean;
|
||||
/** block 时的原因(给 agent 看的可操作修复建议)。 */
|
||||
reason?: string;
|
||||
/** 命令分类出的 step(便于审计)。 */
|
||||
step?: CheckpointStep;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// CheckpointMachine — 闭环状态机
|
||||
// ============================================================================
|
||||
|
||||
const INITIAL_STATE: CheckpointState = {
|
||||
currentStep: "edit",
|
||||
stepPassed: false,
|
||||
history: [],
|
||||
};
|
||||
|
||||
/**
|
||||
* 硬件闭环 checkpoint 状态机。
|
||||
*
|
||||
* 状态:{currentStep, stepPassed, history}
|
||||
* - currentStep: 当前应执行的步骤。
|
||||
* - stepPassed: 当前步骤是否已通过(true 后可推进到下一步)。
|
||||
* - history: 每步执行记录(含失败重试),compaction 后靠它重建。
|
||||
*
|
||||
* 核心方法:
|
||||
* - advance(step, passed): 推进/记录一步。
|
||||
* - assertOrder(before, attemptedCmd): 检查 attemptedCmd 的前置 before 是否满足。
|
||||
* - serialize()/restore(): 落 session / 从 session 重建。
|
||||
*/
|
||||
export class CheckpointMachine {
|
||||
private state: CheckpointState;
|
||||
|
||||
/**
|
||||
* @param initial 可选的初始状态(从 session 重建时传入)。不传则用 INITIAL_STATE。
|
||||
*/
|
||||
constructor(initial?: CheckpointState) {
|
||||
this.state = initial ? cloneState(initial) : cloneState(INITIAL_STATE);
|
||||
// 兜底:非法 currentStep 回到 edit
|
||||
if (!STEP_ORDER.includes(this.state.currentStep)) {
|
||||
this.state.currentStep = "edit";
|
||||
this.state.stepPassed = false;
|
||||
}
|
||||
}
|
||||
|
||||
/** 当前步骤。 */
|
||||
getCurrentStep(): CheckpointStep {
|
||||
return this.state.currentStep;
|
||||
}
|
||||
|
||||
/** 当前步骤是否已通过。 */
|
||||
isStepPassed(): boolean {
|
||||
return this.state.stepPassed;
|
||||
}
|
||||
|
||||
/**
|
||||
* 某一步骤是否已通过(查 history 是否有 passed:true 记录)。
|
||||
* 用于前置依赖检查:flash 前查 isPassed("compile")。
|
||||
*
|
||||
* @param step 要检查的步骤。
|
||||
* @returns 该步骤是否有过 passed:true 记录。
|
||||
*/
|
||||
isPassed(step: CheckpointStep): boolean {
|
||||
return this.state.history.some((h) => h.step === step && h.passed);
|
||||
}
|
||||
|
||||
/**
|
||||
* 推进 checkpoint。
|
||||
*
|
||||
* - passed=true 且 step 是末步(done) → 标记通过,停在 done。
|
||||
* - passed=true 且 nextStep(step) 在 currentStep 之前 → 仅记 history,不回退(重入补跑)。
|
||||
* - passed=true 且 nextStep(step) 在 currentStep 之后 → 前进到 nextStep,stepPassed 重置 false。
|
||||
* - passed=false → 记 history(passed=false),currentStep 回到该失败步(停在/退到该步),stepPassed=false。
|
||||
*
|
||||
* @param step 执行的步骤。
|
||||
* @param passed 该步骤是否通过。
|
||||
*/
|
||||
advance(step: CheckpointStep, passed: boolean): void {
|
||||
this.state.history.push({
|
||||
step,
|
||||
passed,
|
||||
timestamp: Date.now(),
|
||||
});
|
||||
|
||||
const idx = STEP_ORDER.indexOf(step);
|
||||
if (idx < 0) return;
|
||||
const curIdx = STEP_ORDER.indexOf(this.state.currentStep);
|
||||
|
||||
if (passed) {
|
||||
if (idx === STEP_ORDER.length - 1) {
|
||||
// done 通过
|
||||
this.state.currentStep = step;
|
||||
this.state.stepPassed = true;
|
||||
} else {
|
||||
const targetIdx = idx + 1;
|
||||
// 只前进不回退:target 在 currentStep 之后才推进
|
||||
if (targetIdx > curIdx) {
|
||||
this.state.currentStep = STEP_ORDER[targetIdx] as CheckpointStep;
|
||||
this.state.stepPassed = false;
|
||||
}
|
||||
// targetIdx <= curIdx:已到或已过,不回退
|
||||
}
|
||||
} else {
|
||||
// 失败:停在该步(退回该步继续重试)
|
||||
this.state.currentStep = step;
|
||||
this.state.stepPassed = false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 显式前置检查:attemptedCmd 执行前,步骤 `before` 必须已通过。
|
||||
* 未通过 → block(fail-closed)。
|
||||
*
|
||||
* 例:flash 前须 compile 通过 → assertOrder("compile", "dd ...") 。
|
||||
*
|
||||
* @param before 必须已通过的前置步骤。
|
||||
* @param attemptedCmd 待执行的命令(用于分类审计)。
|
||||
* @returns CheckpointDecision(block=true 表示 fail-closed 拦截)。
|
||||
*/
|
||||
assertOrder(before: CheckpointStep, attemptedCmd: string): CheckpointDecision {
|
||||
const step = classifyCommand(attemptedCmd);
|
||||
if (this.isPassed(before)) {
|
||||
return { block: false, step: step ?? undefined };
|
||||
}
|
||||
const reason =
|
||||
`${cap(before)} checkpoint not passed. Run ${before} first before ` +
|
||||
`attempting this ${step ?? "unknown"} command.`;
|
||||
return { block: true, reason, step: step ?? undefined };
|
||||
}
|
||||
|
||||
/**
|
||||
* 返回 history 的深拷贝(防止外部篡改内部状态)。
|
||||
*
|
||||
* @returns history 记录数组的拷贝。
|
||||
*/
|
||||
getHistory(): CheckpointState["history"] {
|
||||
return this.state.history.map((h) => ({ ...h }));
|
||||
}
|
||||
|
||||
/**
|
||||
* 序列化当前状态(落 session 用)。
|
||||
*
|
||||
* @returns 状态的深拷贝。
|
||||
*/
|
||||
serialize(): CheckpointState {
|
||||
return cloneState(this.state);
|
||||
}
|
||||
|
||||
/**
|
||||
* 从序列化数据重建状态(session resume / compaction 后用)。
|
||||
* 非法 currentStep 兜底回 edit,缺 history 兜底空数组。
|
||||
*
|
||||
* @param data 序列化的 CheckpointState。
|
||||
*/
|
||||
restore(data: CheckpointState): void {
|
||||
this.state = cloneState(data);
|
||||
if (!STEP_ORDER.includes(this.state.currentStep)) {
|
||||
this.state.currentStep = "edit";
|
||||
this.state.stepPassed = false;
|
||||
}
|
||||
if (!Array.isArray(this.state.history)) {
|
||||
this.state.history = [];
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 顶层便捷函数:给定 machine 与 attemptedCmd,自动分类并检查前置依赖。
|
||||
* 供扩展层 tool_call handler 直接调用。
|
||||
*
|
||||
* - 命令分类不出 step(null)→ 放行(非 checkpoint 命令)。
|
||||
* - 该 step 无前置(prereq=null)→ 放行。
|
||||
* - 前置满足 → 放行;否则 block(fail-closed)。
|
||||
*
|
||||
* @param machine checkpoint 状态机实例。
|
||||
* @param attemptedCmd 待执行的 bash 命令。
|
||||
* @returns CheckpointDecision(block=true 表示 fail-closed 拦截)。
|
||||
*/
|
||||
export function assertCommandOrder(
|
||||
machine: CheckpointMachine,
|
||||
attemptedCmd: string,
|
||||
): CheckpointDecision {
|
||||
const step = classifyCommand(attemptedCmd);
|
||||
if (step === null) {
|
||||
return { block: false };
|
||||
}
|
||||
const prereq = STEP_PREREQUISITES[step];
|
||||
if (prereq === null || prereq === undefined) {
|
||||
return { block: false, step };
|
||||
}
|
||||
if (machine.isPassed(prereq)) {
|
||||
return { block: false, step };
|
||||
}
|
||||
const reason =
|
||||
`${cap(prereq)} checkpoint not passed. Run ${prereq} first before ` +
|
||||
`attempting this ${step} command.`;
|
||||
return { block: true, reason, step };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 内部工具
|
||||
// ============================================================================
|
||||
|
||||
function cap(s: string): string {
|
||||
return s.charAt(0).toUpperCase() + s.slice(1);
|
||||
}
|
||||
|
||||
function cloneState(s: CheckpointState): CheckpointState {
|
||||
return {
|
||||
currentStep: s.currentStep,
|
||||
stepPassed: s.stepPassed,
|
||||
history: Array.isArray(s.history) ? s.history.map((h) => ({ ...h })) : [],
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/** checkpoint 落 session 的 customType 前缀。 */
|
||||
const CHECKPOINT_ENTRY = "loop:checkpoint";
|
||||
|
||||
/** 同进程单例状态机(单板串行,concurrency=1)。 */
|
||||
let machine = new CheckpointMachine();
|
||||
|
||||
/**
|
||||
* loop-orchestrator 扩展装配。
|
||||
*
|
||||
* 组合:
|
||||
* ① loop_status 工具:让 agent 主动查当前 checkpoint 状态。
|
||||
* ② tool_call 钩子:bash 命令走 assertCommandOrder 强制 checkpoint 顺序(fail-closed),
|
||||
* 结构化工具(flash/verify)查前置依赖。
|
||||
* ③ tool_result 钩子:按编译/烧录结果推进 checkpoint。
|
||||
* ④ session_start:从 session entries 重建 checkpoint(compaction/resume 后不丢)。
|
||||
* ⑤ 事件总线联动:verify:passed → 推进 verify;build:done → 按退出码推进 compile。
|
||||
* ⑥ session_before_compact:重新注入当前 checkpoint,防 compaction 丢失。
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*
|
||||
* @param pi pi 扩展 API。
|
||||
*/
|
||||
export default async function loopOrchestratorExtension(
|
||||
pi: ExtensionAPI,
|
||||
): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
// ---- ① 注册 loop_status 工具 ----
|
||||
const loopStatusTool = defineTool({
|
||||
name: "loop_status",
|
||||
label: "Loop Status",
|
||||
description:
|
||||
"Query the current hardware loop checkpoint state (current step, whether it passed, " +
|
||||
"and full history). Always check loop_status before starting a new iteration step to " +
|
||||
"avoid out-of-order operations (e.g. flashing before compile passes).",
|
||||
promptSnippet: "Query current hardware loop checkpoint status",
|
||||
promptGuidelines: ["Always check loop_status before starting a new iteration step"],
|
||||
parameters: Type.Object({}, { description: "No parameters." }),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, _params, _signal, _onUpdate, _ctx) {
|
||||
const state = machine.serialize();
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify(
|
||||
{
|
||||
currentStep: state.currentStep,
|
||||
stepPassed: state.stepPassed,
|
||||
history: state.history,
|
||||
note: "Order: edit → compile → flash → verify → check → done. " +
|
||||
"Flash requires compile passed; verify requires flash passed.",
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
},
|
||||
],
|
||||
details: { state },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(loopStatusTool);
|
||||
|
||||
// ---- ④ session_start:从 session entries 重建 checkpoint 状态 ----
|
||||
pi.on("session_start", async (_event, ctx: ExtensionContext) => {
|
||||
// 取最近一条 loop:checkpoint entry 重建
|
||||
const entries = ctx.sessionManager.getEntries();
|
||||
const last = [...entries].reverse().find((e) => e.customType === CHECKPOINT_ENTRY);
|
||||
if (last?.data) {
|
||||
machine = new CheckpointMachine(last.data as CheckpointState);
|
||||
ctx.ui.notify(
|
||||
`[loop-orchestrator] checkpoint restored: step=${machine.getCurrentStep()} passed=${machine.isStepPassed()}`,
|
||||
"info",
|
||||
);
|
||||
} else {
|
||||
// 新 session,重置
|
||||
machine = new CheckpointMachine();
|
||||
pi.appendEntry(CHECKPOINT_ENTRY, machine.serialize());
|
||||
}
|
||||
});
|
||||
|
||||
// ---- ② tool_call 钩子:强制 checkpoint 顺序(fail-closed) ----
|
||||
pi.on("tool_call", async (event, ctx: ExtensionContext) => {
|
||||
// bash 命令走 assertCommandOrder
|
||||
if (event.toolName === "bash") {
|
||||
const command = (event.input as { command?: string }).command ?? "";
|
||||
const decision: CheckpointDecision = assertCommandOrder(machine, command);
|
||||
if (decision.block) {
|
||||
if (ctx.hasUI) {
|
||||
const allow = await ctx.ui.confirm(
|
||||
"闭环顺序违规",
|
||||
`命令:${command}\n当前步骤:${machine.getCurrentStep()}\n\n` +
|
||||
`原因:${decision.reason}\n` +
|
||||
"仍要放行?(不推荐,可能砖板)",
|
||||
);
|
||||
if (allow) {
|
||||
pi.appendEntry("loop:override", { command, ...decision });
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
return {
|
||||
block: true,
|
||||
reason: `[loop-orchestrator] ${decision.reason} (current step: ${machine.getCurrentStep()})`,
|
||||
terminate: false,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// 结构化工具(flash/verify)的 checkpoint 检查
|
||||
// flash 工具调用前须 compile 通过
|
||||
if (event.toolName === "flash" && !machine.isPassed("compile")) {
|
||||
return {
|
||||
block: true,
|
||||
reason: "[loop-orchestrator] Compile checkpoint not passed. Run compile first before flashing.",
|
||||
terminate: false,
|
||||
};
|
||||
}
|
||||
// verify 工具调用前须 flash 通过
|
||||
if (event.toolName === "verify" && !machine.isPassed("flash")) {
|
||||
return {
|
||||
block: true,
|
||||
reason: "[loop-orchestrator] Flash checkpoint not passed. Flash before verifying.",
|
||||
terminate: false,
|
||||
};
|
||||
}
|
||||
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- ③ tool_result 钩子:按结果推进 checkpoint ----
|
||||
pi.on("tool_result", (event) => {
|
||||
// bash 命令:按分类 + exitCode 推进
|
||||
if (event.toolName === "bash") {
|
||||
const command = (event.input as { command?: string }).command ?? "";
|
||||
const step = classifyCommand(command);
|
||||
if (step === null) return undefined;
|
||||
const passed = !event.isError;
|
||||
machine.advance(step, passed);
|
||||
pi.appendEntry(CHECKPOINT_ENTRY, machine.serialize());
|
||||
return undefined;
|
||||
}
|
||||
|
||||
// 结构化工具推进
|
||||
const toolToStep: Record<string, CheckpointStep> = {
|
||||
flash: "flash",
|
||||
verify: "verify",
|
||||
build: "compile",
|
||||
};
|
||||
const step = toolToStep[event.toolName];
|
||||
if (step) {
|
||||
machine.advance(step, !event.isError);
|
||||
pi.appendEntry(CHECKPOINT_ENTRY, machine.serialize());
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- ⑤ 事件总线联动 ----
|
||||
// verify:passed(hardware-verify 扩展)→ 推进 verify checkpoint
|
||||
pi.events.on("verify:passed", () => {
|
||||
machine.advance("verify", true);
|
||||
pi.appendEntry(CHECKPOINT_ENTRY, machine.serialize());
|
||||
});
|
||||
// build:done(build 扩展)→ 按退出码推进 compile checkpoint
|
||||
pi.events.on("build:done", (data) => {
|
||||
const d = data as { exitCode?: number };
|
||||
machine.advance("compile", d.exitCode === 0);
|
||||
pi.appendEntry(CHECKPOINT_ENTRY, machine.serialize());
|
||||
});
|
||||
|
||||
// ---- ⑥ compaction 保护:session_before_compact 保留最近 checkpoint ----
|
||||
pi.on("session_before_compact", async () => {
|
||||
// 重新注入当前 checkpoint 状态,防 compaction 丢失
|
||||
pi.appendEntry(CHECKPOINT_ENTRY, machine.serialize());
|
||||
return undefined;
|
||||
});
|
||||
}
|
||||
810
src/extensions/mcp-bridge.ts
Normal file
810
src/extensions/mcp-bridge.ts
Normal file
@ -0,0 +1,810 @@
|
||||
/**
|
||||
* @module mcp-bridge
|
||||
*
|
||||
* MCP 桥接生产级域扩展 —— 治嵌入式开发场景缺陷:
|
||||
* pi 无 MCP 依赖,板卡画像 / 仪器(i2c scanner、SPI flash reader、GPIO sysfs、
|
||||
* 示波器 / 逻辑分析仪 / 万用表)MCP server 生态零复用;每个嵌入式工具操作都
|
||||
* 要从零写成 pi 扩展 TS 函数。
|
||||
*
|
||||
* 根治:写一个 pi 扩展,内部用 @modelcontextprotocol/sdk 作 MCP client,扩展加载
|
||||
* 时连接 MCP server,枚举其 tools,经 mcp_list / mcp_call 两个 pi 工具路由转发。
|
||||
* discovered tools 按 mcp__{server}__{tool} 命名(deferred,不进系统提示防爆 prompt)。
|
||||
*
|
||||
* 范式(参照 glm-provider / safety-gate):
|
||||
* - 顶层只 `import type`(esbuild 擦除),无任何运行时 pi import;
|
||||
* - 纯逻辑(类型 / 函数 / 类 / 常量)全部命名导出,从旧散装逻辑迁移(已过单测,可信);
|
||||
* - `export default async function` 工厂内 `const { defineTool } = await import(...)`;
|
||||
* `const { Type } = await import(...)` 动态拿 pi 运行时;
|
||||
* - tests 直接 import 命名逻辑导出,不 import 工厂 / defineTool,离线可单测。
|
||||
*
|
||||
* 密钥铁律:env 值用 ${DROBOTICS_LLM_KEY} 占位,绝不硬编码 sk-(validateServerConfig 拦截)。
|
||||
* fail-closed 语义:未注册 / 未连接 / 被禁用 server 的 callTool 返回 error,绝不静默。
|
||||
*
|
||||
* 见 Docs/ 下 MCP 桥接扩展文档。运行时 MCP client 真实连接由扩展自带依赖
|
||||
* @modelcontextprotocol/sdk 提供(with-deps 模式,jiti 从扩展目录解析)。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
|
||||
|
||||
// 注:defineTool / Type 仅在工厂内动态 import(运行时解析到真 pi),
|
||||
// 顶层只 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑函数
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时工厂不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// 类型
|
||||
// ============================================================================
|
||||
|
||||
/** MCP server 传输方式:stdio(spawn 子进程,本地板卡)/ sse(远端仪器,网络)。 */
|
||||
export type McpTransport = "stdio" | "sse";
|
||||
|
||||
/**
|
||||
* 单个 MCP server 配置。
|
||||
* @param name server 名(唯一键)。
|
||||
* @param transport 传输方式。
|
||||
* @param command stdio 的 spawn 命令。
|
||||
* @param args stdio 的 spawn 参数。
|
||||
* @param env stdio 子进程环境变量(key 用 ${DROBOTICS_LLM_KEY} 占位,绝不硬编码 sk-)。
|
||||
* @param url sse 的远端 url。
|
||||
* @param headers sse 的请求头。
|
||||
* @param enabled 默认 true;false 则不连接。
|
||||
* @param toolPrefix 工具名前缀,默认 mcp__{server}。
|
||||
*/
|
||||
export interface McpServerConfig {
|
||||
name: string;
|
||||
transport: McpTransport;
|
||||
command?: string;
|
||||
args?: string[];
|
||||
env?: Record<string, string>;
|
||||
url?: string;
|
||||
headers?: Record<string, string>;
|
||||
enabled?: boolean;
|
||||
toolPrefix?: string;
|
||||
}
|
||||
|
||||
/** parseMcpConfig 的解析结果:合法 server + 校验错误(fail-closed:坏 server 不进 servers)。 */
|
||||
export interface ParsedMcpConfig {
|
||||
servers: McpServerConfig[];
|
||||
errors: ParseConfigError[];
|
||||
}
|
||||
|
||||
/** 单条配置校验错误。 */
|
||||
export interface ParseConfigError {
|
||||
server: string;
|
||||
field: string;
|
||||
message: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* MCP 返回的内容块(与 pi 的 TextContent / ImageContent 兼容)。
|
||||
* @param type "text" 或 "image"。
|
||||
* @param text type=text 时的文本。
|
||||
*/
|
||||
export interface McpContentItem {
|
||||
type: "text" | "image";
|
||||
text?: string;
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
/** MCP callTool 的返回(模拟 @modelcontextprotocol/sdk 的 CallToolResult 子集)。 */
|
||||
export interface McpRpcResult {
|
||||
content: McpContentItem[];
|
||||
isError?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* 注入的 RPC 调用(模拟 MCP client.callTool)。测试 mock,绝不依赖真实硬件。
|
||||
* @param server server 名。
|
||||
* @param tool 工具名。
|
||||
* @param args 工具参数。
|
||||
* @returns MCP 结果。
|
||||
*/
|
||||
export type RpcCall = (
|
||||
server: string,
|
||||
tool: string,
|
||||
args: Record<string, unknown> | undefined,
|
||||
) => Promise<McpRpcResult>;
|
||||
|
||||
/** 注入的工具发现函数(模拟 MCP client.listTools)。 */
|
||||
export type ListToolsFn = (server: string) => Promise<string[]>;
|
||||
|
||||
/** 连接表条目。 */
|
||||
export interface McpConnection {
|
||||
serverName: string;
|
||||
config: McpServerConfig;
|
||||
/** 连接时发现的工具名(原始名,不含前缀)。 */
|
||||
tools: string[];
|
||||
connected: boolean;
|
||||
connectedAt?: number;
|
||||
/** 连接失败原因(fail-closed 记录)。 */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
/** callTool 的最终结果(扩展层映射为 pi AgentToolResult)。 */
|
||||
export interface McpToolCallResult {
|
||||
ok: boolean;
|
||||
content: McpContentItem[];
|
||||
details: { server: string; tool: string };
|
||||
error?: string;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ① config 校验 + 解析
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 校验单个 server config,返回错误列表(空 = 合法)。
|
||||
*
|
||||
* fail-closed:缺 name / 缺 command(stdio) / 缺 url(sse) / env 裸 sk- 真 key 均
|
||||
* 产出错误,调用方据此把坏 server 挡在 servers 外。
|
||||
*
|
||||
* @param cfg 原始 server config 对象。
|
||||
* @param idx 在数组中的下标(仅用于错误 label)。
|
||||
* @returns 错误列表,空表示合法。
|
||||
*/
|
||||
export function validateServerConfig(cfg: unknown, idx?: number): ParseConfigError[] {
|
||||
const errors: ParseConfigError[] = [];
|
||||
const label = idx !== undefined ? `servers[${idx}]` : "server";
|
||||
|
||||
if (cfg === null || typeof cfg !== "object") {
|
||||
errors.push({ server: label, field: "root", message: "server config must be an object" });
|
||||
return errors;
|
||||
}
|
||||
const c = cfg as Record<string, unknown>;
|
||||
|
||||
// name
|
||||
if (typeof c.name !== "string" || c.name.trim() === "") {
|
||||
errors.push({ server: label, field: "name", message: "name is required and must be a non-empty string" });
|
||||
}
|
||||
|
||||
// transport:显式给出或从 command/url 推断
|
||||
let transport: unknown = c.transport;
|
||||
if (transport === undefined) {
|
||||
transport = c.command !== undefined ? "stdio" : c.url !== undefined ? "sse" : undefined;
|
||||
}
|
||||
if (transport !== "stdio" && transport !== "sse") {
|
||||
errors.push({
|
||||
server: label,
|
||||
field: "transport",
|
||||
message: 'transport must be "stdio" or "sse" (or inferable from command/url)',
|
||||
});
|
||||
}
|
||||
|
||||
// stdio 字段
|
||||
const isStdio = transport === "stdio" || c.command !== undefined;
|
||||
if (isStdio) {
|
||||
if (typeof c.command !== "string" || c.command.trim() === "") {
|
||||
errors.push({ server: label, field: "command", message: "stdio transport requires a non-empty command" });
|
||||
}
|
||||
if (c.args !== undefined && !Array.isArray(c.args)) {
|
||||
errors.push({ server: label, field: "args", message: "args must be an array of strings" });
|
||||
}
|
||||
if (c.env !== undefined) {
|
||||
if (typeof c.env !== "object" || c.env === null) {
|
||||
errors.push({ server: label, field: "env", message: "env must be a Record<string,string>" });
|
||||
} else {
|
||||
for (const [k, v] of Object.entries(c.env as Record<string, unknown>)) {
|
||||
if (typeof v !== "string") {
|
||||
errors.push({ server: label, field: `env.${k}`, message: "env values must be strings" });
|
||||
}
|
||||
// 密钥铁律:env 值里若出现裸 sk- 开头真 key,标记错误
|
||||
if (typeof v === "string" && /^sk-[A-Za-z0-9]{12,}/.test(v)) {
|
||||
errors.push({
|
||||
server: label,
|
||||
field: `env.${k}`,
|
||||
message: "env value looks like a hardcoded API key (sk-…); use ${DROBOTICS_LLM_KEY} placeholder",
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// sse 字段
|
||||
const isSse = transport === "sse" || c.url !== undefined;
|
||||
if (isSse) {
|
||||
if (typeof c.url !== "string" || c.url.trim() === "") {
|
||||
errors.push({ server: label, field: "url", message: "sse transport requires a non-empty url" });
|
||||
}
|
||||
if (c.headers !== undefined && (typeof c.headers !== "object" || c.headers === null)) {
|
||||
errors.push({ server: label, field: "headers", message: "headers must be a Record<string,string>" });
|
||||
}
|
||||
}
|
||||
|
||||
return errors;
|
||||
}
|
||||
|
||||
/**
|
||||
* 把原始 config 对象归一成 McpServerConfig(调用方已确保校验通过)。
|
||||
*
|
||||
* @param cfg 已校验的原始 config 对象。
|
||||
* @returns 归一化的 McpServerConfig。
|
||||
*/
|
||||
export function normalizeServerConfig(cfg: Record<string, unknown>): McpServerConfig {
|
||||
const transport: McpTransport =
|
||||
cfg.transport === "sse" ? "sse" : cfg.command !== undefined ? "stdio" : "sse";
|
||||
return {
|
||||
name: String(cfg.name),
|
||||
transport,
|
||||
command: cfg.command !== undefined ? String(cfg.command) : undefined,
|
||||
args: Array.isArray(cfg.args) ? (cfg.args as unknown[]).map(String) : undefined,
|
||||
env: cfg.env && typeof cfg.env === "object" ? (cfg.env as Record<string, string>) : undefined,
|
||||
url: cfg.url !== undefined ? String(cfg.url) : undefined,
|
||||
headers: cfg.headers && typeof cfg.headers === "object" ? (cfg.headers as Record<string, string>) : undefined,
|
||||
enabled: cfg.enabled !== undefined ? Boolean(cfg.enabled) : true,
|
||||
toolPrefix: cfg.toolPrefix !== undefined ? String(cfg.toolPrefix) : undefined,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析 MCP 配置 JSON。支持三种形态:
|
||||
* - 标准 MCP: { mcpServers: { name: {command,args,env}, ... } }
|
||||
* - 数组形态: { servers: [ {name,command,...}, ... ] }
|
||||
* - 裸数组: [ {name,...}, ... ]
|
||||
*
|
||||
* fail-closed:校验失败的 server 进 errors,不进 servers(不注册坏配置)。
|
||||
*
|
||||
* @param raw 原始配置(对象 / 数组)。
|
||||
* @returns 解析结果,servers 合法、errors 记录坏配置。
|
||||
*/
|
||||
export function parseMcpConfig(raw: unknown): ParsedMcpConfig {
|
||||
const errors: ParseConfigError[] = [];
|
||||
const servers: McpServerConfig[] = [];
|
||||
|
||||
if (raw === null || typeof raw !== "object") {
|
||||
return {
|
||||
servers: [],
|
||||
errors: [{ server: "root", field: "root", message: "config must be an object or array" }],
|
||||
};
|
||||
}
|
||||
|
||||
const entries: Array<{ cfg: Record<string, unknown>; idx: number }> = [];
|
||||
|
||||
if (Array.isArray(raw)) {
|
||||
(raw as unknown[]).forEach((c, i) => {
|
||||
if (c !== null && typeof c === "object") {
|
||||
entries.push({ cfg: c as Record<string, unknown>, idx: i });
|
||||
} else {
|
||||
errors.push({ server: `[${i}]`, field: "root", message: "server config must be an object" });
|
||||
}
|
||||
});
|
||||
} else {
|
||||
const obj = raw as Record<string, unknown>;
|
||||
if (obj.mcpServers !== undefined && typeof obj.mcpServers === "object" && !Array.isArray(obj.mcpServers)) {
|
||||
// 标准 MCP 形态:{ mcpServers: { name: {...} } },name 从 key 补入
|
||||
const ms = obj.mcpServers as Record<string, unknown>;
|
||||
let i = 0;
|
||||
for (const [name, c] of Object.entries(ms)) {
|
||||
if (c !== null && typeof c === "object") {
|
||||
entries.push({ cfg: { ...(c as Record<string, unknown>), name }, idx: i++ });
|
||||
} else {
|
||||
errors.push({ server: name, field: "root", message: "server config must be an object" });
|
||||
}
|
||||
}
|
||||
} else if (Array.isArray(obj.servers)) {
|
||||
(obj.servers as unknown[]).forEach((c, i) => {
|
||||
if (c !== null && typeof c === "object") {
|
||||
entries.push({ cfg: c as Record<string, unknown>, idx: i });
|
||||
} else {
|
||||
errors.push({ server: `servers[${i}]`, field: "root", message: "server config must be an object" });
|
||||
}
|
||||
});
|
||||
} else {
|
||||
return {
|
||||
servers: [],
|
||||
errors: [
|
||||
{ server: "root", field: "root", message: "config must have mcpServers object, servers array, or be an array" },
|
||||
],
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
for (const { cfg, idx } of entries) {
|
||||
const errs = validateServerConfig(cfg, idx);
|
||||
if (errs.length > 0) {
|
||||
errors.push(...errs);
|
||||
} else {
|
||||
servers.push(normalizeServerConfig(cfg));
|
||||
}
|
||||
}
|
||||
|
||||
return { servers, errors };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ② 工具名前缀(mcp__{server}__{tool})
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 构建 pi 工具名,避免与内置工具冲突。
|
||||
* @param server server 名。
|
||||
* @param tool 工具原始名。
|
||||
* @param toolPrefix 自定义前缀,默认 mcp__{server}。
|
||||
* @returns 形如 mcp__i2c__scan 的工具名。
|
||||
*/
|
||||
export function buildMcpToolName(server: string, tool: string, toolPrefix?: string): string {
|
||||
const prefix = toolPrefix ?? `mcp__${server}`;
|
||||
return `${prefix}__${tool}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从 pi 工具名解出 {server, tool}。
|
||||
* @param name 工具名。
|
||||
* @returns {server, tool} 或 null(非 mcp__ 前缀或无 __ 分隔)。
|
||||
*/
|
||||
export function parseMcpToolName(name: string): { server: string; tool: string } | null {
|
||||
const prefix = "mcp__";
|
||||
if (!name.startsWith(prefix)) return null;
|
||||
const rest = name.slice(prefix.length);
|
||||
const idx = rest.indexOf("__");
|
||||
if (idx === -1) return null;
|
||||
return { server: rest.slice(0, idx), tool: rest.slice(idx + 2) };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ③ McpBridge:连接表 + callTool 路由(注入 RpcCall mock)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* MCP 桥接核心。维护 server 配置表 + 连接表,callTool 路由到注入的 RpcCall。
|
||||
*
|
||||
* fail-closed:未注册 / 未连接 / 被禁用 server 的 callTool 返回 error,绝不静默;
|
||||
* rpc 抛错也透传成 error,不吞。逻辑层用注入的 RpcCall / ListToolsFn mock,
|
||||
* 绝不依赖真实硬件或 @modelcontextprotocol/sdk。
|
||||
*/
|
||||
export class McpBridge {
|
||||
private configs = new Map<string, McpServerConfig>();
|
||||
private connections = new Map<string, McpConnection>();
|
||||
private readonly rpc: RpcCall;
|
||||
private readonly listTools: ListToolsFn;
|
||||
|
||||
/**
|
||||
* @param rpc 注入的 RPC 调用(测试 mock,路由到运行时 MCP client)。
|
||||
* @param listTools 注入的工具发现函数(连接时发现工具)。
|
||||
*/
|
||||
constructor(rpc: RpcCall, listTools?: ListToolsFn) {
|
||||
this.rpc = rpc;
|
||||
this.listTools = listTools ?? (async () => []);
|
||||
}
|
||||
|
||||
/**
|
||||
* 注册一个 server 配置。
|
||||
* @param config server 配置。
|
||||
* @throws {McpConfigError} 校验失败。
|
||||
*/
|
||||
registerServer(config: McpServerConfig): void {
|
||||
const errs = validateServerConfig(config);
|
||||
if (errs.length > 0) {
|
||||
throw new McpConfigError(errs);
|
||||
}
|
||||
this.configs.set(config.name, config);
|
||||
}
|
||||
|
||||
/** 批量注册(从 parseMcpConfig 结果)。 */
|
||||
registerServers(servers: McpServerConfig[]): void {
|
||||
for (const s of servers) this.registerServer(s);
|
||||
}
|
||||
|
||||
/** 是否已注册(配置层)。 */
|
||||
isRegistered(serverName: string): boolean {
|
||||
return this.configs.has(serverName);
|
||||
}
|
||||
|
||||
/**
|
||||
* 连接一个 server:调注入的 listTools 发现工具。
|
||||
* fail-closed:失败不抛,记 error 标未连接。
|
||||
* @param serverName server 名。
|
||||
* @returns 连接条目。
|
||||
*/
|
||||
async connect(serverName: string): Promise<McpConnection> {
|
||||
const config = this.configs.get(serverName);
|
||||
if (!config) {
|
||||
throw new Error(`[mcp-bridge] unknown server "${serverName}" — not registered`);
|
||||
}
|
||||
if (config.enabled === false) {
|
||||
const conn: McpConnection = {
|
||||
serverName,
|
||||
config,
|
||||
tools: [],
|
||||
connected: false,
|
||||
error: "server disabled in config",
|
||||
};
|
||||
this.connections.set(serverName, conn);
|
||||
return conn;
|
||||
}
|
||||
try {
|
||||
const tools = await this.listTools(serverName);
|
||||
const conn: McpConnection = {
|
||||
serverName,
|
||||
config,
|
||||
tools,
|
||||
connected: true,
|
||||
connectedAt: Date.now(),
|
||||
};
|
||||
this.connections.set(serverName, conn);
|
||||
return conn;
|
||||
} catch (e) {
|
||||
// fail-closed:连接失败 → 标记未连接 + 记录原因,不抛
|
||||
const conn: McpConnection = {
|
||||
serverName,
|
||||
config,
|
||||
tools: [],
|
||||
connected: false,
|
||||
error: e instanceof Error ? e.message : String(e),
|
||||
};
|
||||
this.connections.set(serverName, conn);
|
||||
return conn;
|
||||
}
|
||||
}
|
||||
|
||||
/** 断开单个 server。 */
|
||||
disconnect(serverName: string): boolean {
|
||||
return this.connections.delete(serverName);
|
||||
}
|
||||
|
||||
/** 断开所有(pi reload/退出时清理,防子进程/SSE 泄漏)。 */
|
||||
disconnectAll(): void {
|
||||
this.connections.clear();
|
||||
}
|
||||
|
||||
/** 是否已连接(连接层)。 */
|
||||
isConnected(serverName: string): boolean {
|
||||
return this.connections.get(serverName)?.connected ?? false;
|
||||
}
|
||||
|
||||
/** 已连接 server 发现的工具列表(原始名)。 */
|
||||
listServerTools(serverName: string): string[] {
|
||||
return this.connections.get(serverName)?.tools ?? [];
|
||||
}
|
||||
|
||||
/** 所有已连接 server 名。 */
|
||||
listConnectedServers(): string[] {
|
||||
return [...this.connections.values()].filter((c) => c.connected).map((c) => c.serverName);
|
||||
}
|
||||
|
||||
/** 取连接条目(扩展层用来构建 pi ToolDefinition)。 */
|
||||
getConnection(serverName: string): McpConnection | undefined {
|
||||
return this.connections.get(serverName);
|
||||
}
|
||||
|
||||
/** 已注册 server 配置。 */
|
||||
getConfig(serverName: string): McpServerConfig | undefined {
|
||||
return this.configs.get(serverName);
|
||||
}
|
||||
|
||||
/**
|
||||
* 调用 MCP 工具。fail-closed:
|
||||
* - 未注册 server → error
|
||||
* - 未连接 server → error
|
||||
* - 被禁用 server → error
|
||||
* - rpc 抛错 → error(不静默吞)
|
||||
* 成功 → ok:true + content。
|
||||
*
|
||||
* @param server server 名。
|
||||
* @param tool 工具名。
|
||||
* @param args 工具参数。
|
||||
* @returns 调用结果(ok=false 时 content 含 fail-closed 说明)。
|
||||
*/
|
||||
async callTool(
|
||||
server: string,
|
||||
tool: string,
|
||||
args?: Record<string, unknown>,
|
||||
): Promise<McpToolCallResult> {
|
||||
const config = this.configs.get(server);
|
||||
if (!config) {
|
||||
return {
|
||||
ok: false,
|
||||
content: [
|
||||
{ type: "text", text: `[mcp-bridge] server "${server}" is not registered — callTool refused (fail-closed).` },
|
||||
],
|
||||
details: { server, tool },
|
||||
error: `server "${server}" not registered`,
|
||||
};
|
||||
}
|
||||
if (config.enabled === false) {
|
||||
return {
|
||||
ok: false,
|
||||
content: [{ type: "text", text: `[mcp-bridge] server "${server}" is disabled.` }],
|
||||
details: { server, tool },
|
||||
error: "server disabled",
|
||||
};
|
||||
}
|
||||
const conn = this.connections.get(server);
|
||||
if (!conn || !conn.connected) {
|
||||
return {
|
||||
ok: false,
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: `[mcp-bridge] server "${server}" is not connected${conn?.error ? `: ${conn.error}` : ""} — callTool refused (fail-closed).`,
|
||||
},
|
||||
],
|
||||
details: { server, tool },
|
||||
error: `server "${server}" not connected`,
|
||||
};
|
||||
}
|
||||
try {
|
||||
const result = await this.rpc(server, tool, args);
|
||||
return {
|
||||
ok: !result.isError,
|
||||
content: result.content,
|
||||
details: { server, tool },
|
||||
error: result.isError ? "MCP server returned isError=true" : undefined,
|
||||
};
|
||||
} catch (e) {
|
||||
return {
|
||||
ok: false,
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: `[mcp-bridge] rpc call to "${server}.${tool}" failed: ${e instanceof Error ? e.message : String(e)}`,
|
||||
},
|
||||
],
|
||||
details: { server, tool },
|
||||
error: e instanceof Error ? e.message : String(e),
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* config 校验失败错误(registerServer 抛)。
|
||||
* @param errors 校验错误列表。
|
||||
*/
|
||||
export class McpConfigError extends Error {
|
||||
constructor(public errors: ParseConfigError[]) {
|
||||
super(`MCP config invalid: ${errors.map((e) => `${e.server}.${e.field}: ${e.message}`).join("; ")}`);
|
||||
this.name = "McpConfigError";
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 运行时 MCP client 胶水(扩展自带依赖,非导出,tests 不触达)
|
||||
// ============================================================================
|
||||
|
||||
/** 运行时 MCP client 暴露给桥接的最小面。 */
|
||||
interface RuntimeMcpClient {
|
||||
listTools: () => Promise<string[]>;
|
||||
callTool: (tool: string, args: Record<string, unknown> | undefined) => Promise<{ content: McpContentItem[]; isError?: boolean }>;
|
||||
close: () => Promise<void>;
|
||||
}
|
||||
|
||||
/**
|
||||
* 动态加载 @modelcontextprotocol/sdk(扩展自带依赖)。
|
||||
* 用 Function 包裹 import 使 tsc 不解析该模块——类型由运行时提供。
|
||||
* @returns SDK 命名空间(any)。
|
||||
*/
|
||||
async function loadMcpSdk(): Promise<any> {
|
||||
const dynamicImport = new Function("spec", "return import(spec)") as (spec: string) => Promise<any>;
|
||||
return dynamicImport("@modelcontextprotocol/sdk");
|
||||
}
|
||||
|
||||
/**
|
||||
* 用 SDK 为一个 server 建立真实 MCP client,返回 { listTools, callTool, close }。
|
||||
* stdio → StdioClientTransport(spawn 子进程);sse → SSEClientTransport。
|
||||
* @param config server 配置。
|
||||
* @returns 运行时 client。
|
||||
*/
|
||||
async function connectMcpServer(config: McpServerConfig): Promise<RuntimeMcpClient> {
|
||||
const sdk = await loadMcpSdk();
|
||||
const { Client } = sdk.client ?? sdk;
|
||||
let transport: unknown;
|
||||
if (config.transport === "sse") {
|
||||
const { SSEClientTransport } = sdk.sseClientTransport ?? sdk.client?.sse ?? sdk;
|
||||
transport = new SSEClientTransport(new URL(config.url ?? ""));
|
||||
} else {
|
||||
const { StdioClientTransport } = sdk.stdioClientTransport ?? sdk.client?.stdio ?? sdk;
|
||||
transport = new StdioClientTransport({
|
||||
command: config.command,
|
||||
args: config.args ?? [],
|
||||
env: config.env,
|
||||
});
|
||||
}
|
||||
const client = new Client({ name: "pi-mcp-bridge", version: "0.1.0" }, { capabilities: {} });
|
||||
await client.connect(transport as any);
|
||||
return {
|
||||
async listTools() {
|
||||
const res = await client.listTools();
|
||||
return (res.tools ?? []).map((t: any) => t.name as string);
|
||||
},
|
||||
async callTool(tool, args) {
|
||||
const res = await client.callTool({ name: tool, arguments: args });
|
||||
return { content: (res.content ?? []) as McpContentItem[], isError: res.isError };
|
||||
},
|
||||
async close() {
|
||||
await client.close();
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** 把 McpContentItem[] 映射为 pi AgentToolResult 的 content(类型兼容,直接透传)。 */
|
||||
function mapContent(items: McpContentItem[]): Array<{ type: "text" | "image"; text?: string; [k: string]: unknown }> {
|
||||
return items.map((it) => ({ ...it }));
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool / Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* mcp-bridge 扩展装配。
|
||||
*
|
||||
* - 注册 mcp_list / mcp_call 两个 pi 工具,路由到桥接的 MCP server。
|
||||
* - session_start:读 PI_MCP_CONFIG(JSON 路径)→ parseMcpConfig → registerServers →
|
||||
* 连接所有 server,发现的工具按 mcp__{server}__{tool} 命名(deferred,不进系统提示)。
|
||||
* - before_agent_start:reload 时清理旧连接防子进程 / SSE 泄漏。
|
||||
* - process 退出兜底:关子进程。
|
||||
*
|
||||
* defineTool / Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
* MCP server 不可用时 fail-closed:仅 notify 警告,不阻塞 pi 启动。
|
||||
*
|
||||
* @param pi 扩展 API。
|
||||
*/
|
||||
export default async function mcpBridgeExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
const configPath = process.env.PI_MCP_CONFIG;
|
||||
const mcpDisabled = process.env.PI_MCP_DISABLED === "1" || process.env.PI_MCP_DISABLED === "true";
|
||||
|
||||
// 持有真实 MCP client(运行时建立),供注入的 RpcCall / ListToolsFn 路由
|
||||
const runtimeClients = new Map<string, RuntimeMcpClient>();
|
||||
|
||||
const bridge = new McpBridge(
|
||||
// RpcCall:路由到运行时 MCP client
|
||||
async (server, tool, args) => {
|
||||
const c = runtimeClients.get(server);
|
||||
if (!c) {
|
||||
return { content: [{ type: "text" as const, text: `[mcp-bridge] no runtime client for "${server}"` }], isError: true };
|
||||
}
|
||||
return c.callTool(tool, args);
|
||||
},
|
||||
// ListToolsFn:连接时发现工具(真实 listTools 在 ensureRuntimeClient 里完成)
|
||||
async () => [],
|
||||
);
|
||||
|
||||
/**
|
||||
* 为一个 server 建立运行时 client 并把发现的真实工具注入 bridge 连接表。
|
||||
* fail-closed:失败返回未连接 + error,不抛。
|
||||
*/
|
||||
async function ensureRuntimeClient(
|
||||
config: McpServerConfig,
|
||||
): Promise<{ tools: string[]; connected: boolean; error?: string }> {
|
||||
try {
|
||||
const c = await connectMcpServer(config);
|
||||
const tools = await c.listTools();
|
||||
runtimeClients.set(config.name, c);
|
||||
// 用真实发现的工具回填 bridge 连接表(绕过注入的空 listToolsFn)
|
||||
const conn = await bridge.connect(config.name);
|
||||
// bridge.connect 调了空 listTools → 手动补 tools
|
||||
// (bridge 不开放 set,故通过重新 register + connect 注入)
|
||||
conn.tools = tools;
|
||||
return { tools, connected: true };
|
||||
} catch (e) {
|
||||
return { tools: [], connected: false, error: e instanceof Error ? e.message : String(e) };
|
||||
}
|
||||
}
|
||||
|
||||
// ---- mcp_list 工具:列出所有已连接 server 及其工具 ----
|
||||
const mcpListTool = defineTool({
|
||||
name: "mcp_list",
|
||||
label: "MCP Servers",
|
||||
description:
|
||||
"List connected MCP servers and their tools (bridged from the MCP ecosystem: i2c scanner, SPI flash reader, GPIO sysfs, oscilloscope, etc.). " +
|
||||
"Use mcp_call to invoke a specific tool via mcp__{server}__{tool} name.",
|
||||
parameters: Type.Object({}, { description: "No parameters." }),
|
||||
executionMode: "sequential",
|
||||
async execute() {
|
||||
const connected = bridge.listConnectedServers();
|
||||
const lines: string[] = connected.length === 0 ? ["(no MCP servers connected)"] : [];
|
||||
for (const s of connected) {
|
||||
const tools = bridge.listServerTools(s);
|
||||
lines.push(`[${s}] tools: ${tools.map((t) => buildMcpToolName(s, t)).join(", ") || "(none)"}`);
|
||||
}
|
||||
return {
|
||||
content: [{ type: "text", text: lines.join("\n") }],
|
||||
details: { servers: connected },
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
// ---- mcp_call 工具:调一个 MCP server 的工具 ----
|
||||
const mcpCallTool = defineTool({
|
||||
name: "mcp_call",
|
||||
label: "MCP Call",
|
||||
description:
|
||||
"Call a tool on a connected MCP server. Pass the mcp__{server}__{tool} name (see mcp_list) and arguments. " +
|
||||
"fail-closed: unknown/unconnected servers return an error, never silently succeed.",
|
||||
parameters: Type.Object({
|
||||
tool: Type.String({ description: "Full tool name mcp__{server}__{tool} or raw {server}.{tool}." }),
|
||||
args: Type.Optional(Type.Object({}, { description: "Tool arguments (JSON object)." })),
|
||||
}),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as { tool: string; args?: Record<string, unknown> };
|
||||
let server: string;
|
||||
let tool: string;
|
||||
const parsed = parseMcpToolName(p.tool);
|
||||
if (parsed) {
|
||||
server = parsed.server;
|
||||
tool = parsed.tool;
|
||||
} else if (p.tool.includes(".")) {
|
||||
[server, tool] = p.tool.split(".", 2);
|
||||
} else {
|
||||
return {
|
||||
content: [{ type: "text", text: `[mcp-bridge] cannot parse tool name "${p.tool}" — use mcp__{server}__{tool}.` }],
|
||||
details: { tool: p.tool },
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
const r = await bridge.callTool(server, tool, p.args);
|
||||
return {
|
||||
content: mapContent(r.content) as Array<{ type: "text"; text: string } | { type: "image"; [k: string]: unknown }>,
|
||||
details: r.details,
|
||||
isError: !r.ok,
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(mcpListTool);
|
||||
pi.registerTool(mcpCallTool);
|
||||
|
||||
// ---- session_start:加载配置 + 连接所有 server ----
|
||||
pi.on("session_start", async (_event, ctx: ExtensionContext) => {
|
||||
if (mcpDisabled) {
|
||||
ctx.ui.notify("[mcp-bridge] MCP bridge disabled (PI_MCP_DISABLED)", "info");
|
||||
return;
|
||||
}
|
||||
if (!configPath) {
|
||||
return; // 无配置,静默跳过
|
||||
}
|
||||
let raw: unknown;
|
||||
try {
|
||||
const { readFileSync } = await import("node:fs");
|
||||
raw = JSON.parse(readFileSync(configPath, "utf8"));
|
||||
} catch (e) {
|
||||
ctx.ui.notify(`[mcp-bridge] failed to read MCP config ${configPath}: ${e instanceof Error ? e.message : e}`, "error");
|
||||
return;
|
||||
}
|
||||
const { servers, errors } = parseMcpConfig(raw);
|
||||
if (errors.length > 0) {
|
||||
ctx.ui.notify(
|
||||
`[mcp-bridge] MCP config has ${errors.length} error(s): ${errors.map((e) => `${e.server}.${e.field}`).join(", ")}`,
|
||||
"warning",
|
||||
);
|
||||
}
|
||||
bridge.registerServers(servers);
|
||||
for (const cfg of servers) {
|
||||
if (cfg.enabled === false) continue;
|
||||
const rt = await ensureRuntimeClient(cfg);
|
||||
if (!rt.connected) {
|
||||
ctx.ui.notify(`[mcp-bridge] MCP server "${cfg.name}" connect failed: ${rt.error ?? "unknown"}`, "warning");
|
||||
pi.appendEntry("mcp:connect-failed", { server: cfg.name, error: rt.error });
|
||||
} else {
|
||||
pi.appendEntry("mcp:connected", { server: cfg.name, tools: rt.tools });
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// ---- before_agent_start:reload 时清理旧连接防子进程/SSE 泄漏 ----
|
||||
pi.on("before_agent_start", () => {
|
||||
for (const [name, c] of runtimeClients) {
|
||||
c.close().catch((e) => {
|
||||
pi.appendEntry("mcp:close-error", { server: name, error: String(e) });
|
||||
});
|
||||
runtimeClients.delete(name);
|
||||
}
|
||||
bridge.disconnectAll();
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- process 退出兜底:关子进程 ----
|
||||
const cleanup = async () => {
|
||||
for (const [, c] of runtimeClients) {
|
||||
await c.close().catch(() => {});
|
||||
}
|
||||
};
|
||||
process.once("exit", cleanup);
|
||||
process.once("SIGTERM", () => {
|
||||
void cleanup().finally(() => process.exit(0));
|
||||
});
|
||||
}
|
||||
800
src/extensions/pdf-reader.ts
Normal file
800
src/extensions/pdf-reader.ts
Normal file
@ -0,0 +1,800 @@
|
||||
/**
|
||||
* @module pdf-reader
|
||||
*
|
||||
* PDF 增强读取扩展 —— 治嵌入式开发场景下 datasheet 不可读的命门:
|
||||
* 旧 read 工具头部截断 2000 行/50KB 且零 PDF 支持,agent 读 SoC datasheet
|
||||
* (3000-8000 页 PDF)要么拿乱码、要么只看前 1/4,查不到寄存器偏移就靠记忆
|
||||
* → 幻觉 → 写错寄存器 → 砖板。
|
||||
*
|
||||
* 三件套:
|
||||
* ① PDF 魔数嗅探(%PDF-),fail-closed:不是 PDF 绝不当 PDF 解码(避免乱码)
|
||||
* ② 页范围解析 + 字节上限截断 + 续读提示(offset=N to continue)
|
||||
* ③ 提限:datasheet 场景 8000 行/500KB(旧 2000 行/50KB 的根因配置保留供对比)
|
||||
*
|
||||
* 寄存器地址串(如 0x40020000)原样保留,无数值归一(不触发 hex 强转砖板)。
|
||||
*
|
||||
* 见 Docs/增强读取PDF与提限分页 文档。纯逻辑内联为命名导出,tests 直接单测,
|
||||
* 无需 pi 运行时、无需真实 PDF 文件或硬件。运行时 PDF 抽取用 unpdf(纯 JS、ESM
|
||||
* 友好),仅在工具执行时 dynamic import,不影响离线构建/单测。
|
||||
*
|
||||
* 密钥:本扩展不接触 LLM key;任何需要 key 的联动经 events 总线由 glm-provider 注入,
|
||||
* 绝不在此硬编码 sk-。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
|
||||
// 注:defineTool / Type 仅在 factory 内 dynamic import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时 factory 不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// ① PDF 魔数嗅探
|
||||
// ============================================================================
|
||||
|
||||
/** PDF 文件魔数:%PDF-(0x25 0x50 0x44 0x46 0x2D)。 */
|
||||
const PDF_MAGIC = [0x25, 0x50, 0x44, 0x46, 0x2d];
|
||||
|
||||
/**
|
||||
* 嗅探前几字节是否为 PDF 魔数。
|
||||
*
|
||||
* fail-closed:字节不足或首字节不匹配 → false(不当 PDF 处理,避免乱码解码)。
|
||||
*
|
||||
* @param bytes 文件头部字节。
|
||||
* @returns 是 PDF 魔数返回 true,否则 false。
|
||||
*/
|
||||
export function isPdfMagic(bytes: Uint8Array): boolean {
|
||||
if (!bytes || bytes.length < 5) return false;
|
||||
for (let i = 0; i < PDF_MAGIC.length; i++) {
|
||||
if (bytes[i] !== PDF_MAGIC[i]) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 把文件路径扩展名 + 头部字节综合判断是否为 PDF。
|
||||
* 路径 .pdf 后缀是弱信号,魔数是强信号;两者都检查,魔数优先。
|
||||
*
|
||||
* @param path 文件路径。
|
||||
* @param headBytes 可选的文件头部字节(强信号)。
|
||||
* @returns 判定为 PDF 返回 true。
|
||||
*/
|
||||
export function detectPdfMimeType(
|
||||
path: string,
|
||||
headBytes?: Uint8Array,
|
||||
): boolean {
|
||||
const lowerPath = (path ?? "").toLowerCase();
|
||||
const isPdfExt = lowerPath.endsWith(".pdf");
|
||||
if (headBytes) {
|
||||
return isPdfMagic(headBytes);
|
||||
}
|
||||
// 无字节时仅靠扩展名(弱信号,扩展层读文件头后会二次确认)
|
||||
return isPdfExt;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ② 页范围解析
|
||||
// ============================================================================
|
||||
|
||||
/** 一个连续页范围(1-indexed,两端闭区间)。 */
|
||||
export interface PageRange {
|
||||
/** 起始页(1-indexed,含)。 */
|
||||
start: number;
|
||||
/** 结束页(1-indexed,含)。 */
|
||||
end: number;
|
||||
}
|
||||
|
||||
/** parsePageRange 的返回。 */
|
||||
export interface ParsedPageRange {
|
||||
/** 解析出的页范围列表(已排序、去重、合并相邻/重叠)。 */
|
||||
ranges: PageRange[];
|
||||
/** 输入为 "all" 时 true。 */
|
||||
all: boolean;
|
||||
/** 解析是否成功。 */
|
||||
valid: boolean;
|
||||
/** 失败时的错误信息。 */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析页范围字符串。支持以下形态:
|
||||
*
|
||||
* - `"all"` → all:true(totalPages 已知时展开为 [1, totalPages])
|
||||
* - `"1-5"` → [{start:1, end:5}]
|
||||
* - `"3,7,10"` → [{3,3}, {7,7}, {10,10}]
|
||||
* - `"1-3,7,10-12"` → [{1,3}, {7,7}, {10,12}]
|
||||
*
|
||||
* 容忍空格/换行。totalPages 提供时做越界 clamp + 校验。
|
||||
*
|
||||
* fail-closed:任何非法片段 → valid:false + error(绝不返回半解析结果)。
|
||||
*
|
||||
* @param input 页范围字符串。
|
||||
* @param totalPages 可选总页数,提供时做越界 clamp + 校验。
|
||||
* @returns 解析结果。
|
||||
*/
|
||||
export function parsePageRange(input: string, totalPages?: number): ParsedPageRange {
|
||||
const trimmed = (input ?? "").trim().toLowerCase();
|
||||
|
||||
if (trimmed === "") {
|
||||
return { ranges: [], all: false, valid: false, error: "empty page range" };
|
||||
}
|
||||
|
||||
if (trimmed === "all") {
|
||||
if (totalPages !== undefined && totalPages > 0) {
|
||||
return { ranges: [{ start: 1, end: totalPages }], all: true, valid: true };
|
||||
}
|
||||
// all 但不知道总页数——合法,由调用方先探测首页再续读
|
||||
return { ranges: [], all: true, valid: true };
|
||||
}
|
||||
|
||||
const ranges: PageRange[] = [];
|
||||
const parts = trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
|
||||
|
||||
for (const part of parts) {
|
||||
// "1-5" range form
|
||||
const rangeMatch = part.match(/^(\d+)\s*-\s*(\d+)$/);
|
||||
if (rangeMatch) {
|
||||
const start = parseInt(rangeMatch[1], 10);
|
||||
const end = parseInt(rangeMatch[2], 10);
|
||||
if (start < 1 || end < 1) {
|
||||
return { ranges: [], all: false, valid: false, error: `page numbers must be >= 1: "${part}"` };
|
||||
}
|
||||
if (start > end) {
|
||||
return { ranges: [], all: false, valid: false, error: `range start > end: "${part}"` };
|
||||
}
|
||||
if (totalPages !== undefined) {
|
||||
if (start > totalPages) {
|
||||
return { ranges: [], all: false, valid: false, error: `page ${start} exceeds total ${totalPages}` };
|
||||
}
|
||||
ranges.push({ start, end: Math.min(end, totalPages) });
|
||||
} else {
|
||||
ranges.push({ start, end });
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
// single page "7"
|
||||
const singleMatch = part.match(/^(\d+)$/);
|
||||
if (singleMatch) {
|
||||
const page = parseInt(singleMatch[1], 10);
|
||||
if (page < 1) {
|
||||
return { ranges: [], all: false, valid: false, error: `page numbers must be >= 1: "${part}"` };
|
||||
}
|
||||
if (totalPages !== undefined && page > totalPages) {
|
||||
return { ranges: [], all: false, valid: false, error: `page ${page} exceeds total ${totalPages}` };
|
||||
}
|
||||
ranges.push({ start: page, end: page });
|
||||
continue;
|
||||
}
|
||||
|
||||
return { ranges: [], all: false, valid: false, error: `unrecognized page spec: "${part}"` };
|
||||
}
|
||||
|
||||
if (ranges.length === 0) {
|
||||
return { ranges: [], all: false, valid: false, error: "no valid page ranges parsed" };
|
||||
}
|
||||
|
||||
// 排序后合并相邻/重叠范围
|
||||
ranges.sort((a, b) => a.start - b.start);
|
||||
const merged: PageRange[] = [{ ...ranges[0] }];
|
||||
for (let i = 1; i < ranges.length; i++) {
|
||||
const last = merged[merged.length - 1];
|
||||
const cur = ranges[i];
|
||||
if (cur.start <= last.end + 1) {
|
||||
last.end = Math.max(last.end, cur.end);
|
||||
} else {
|
||||
merged.push({ ...cur });
|
||||
}
|
||||
}
|
||||
|
||||
return { ranges: merged, all: false, valid: true };
|
||||
}
|
||||
|
||||
/**
|
||||
* 把 ParsedPageRange 展开为具体的页码列表(1-indexed)。
|
||||
* all 且无 ranges 时返回空数组(调用方应先探测总页数)。
|
||||
*
|
||||
* @param parsed parsePageRange 的返回。
|
||||
* @returns 页码列表。
|
||||
*/
|
||||
export function expandPages(parsed: ParsedPageRange): number[] {
|
||||
const pages: number[] = [];
|
||||
for (const r of parsed.ranges) {
|
||||
for (let p = r.start; p <= r.end; p++) {
|
||||
pages.push(p);
|
||||
}
|
||||
}
|
||||
return pages;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ③ token 估算(chars/4 近似)
|
||||
// ============================================================================
|
||||
|
||||
/** 文本字节/token 估算结果。 */
|
||||
export interface TextByteEstimate {
|
||||
/** 字符数。 */
|
||||
chars: number;
|
||||
/** 估算 token 数(chars/4,向上取整)。 */
|
||||
estimatedTokens: number;
|
||||
/** UTF-8 编码字节数(精确)。 */
|
||||
estimatedBytes: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从文本估算 token 数与字节数。
|
||||
*
|
||||
* token 估算用经验法则 chars/4 ≈ tokens(OpenAI / glm-5.2 近似)。
|
||||
* 字节数用 UTF-8 编码精确计算(用于截断决策的 maxBytes 比较)。
|
||||
*
|
||||
* @param text 文本。
|
||||
* @returns 字符数 / 估算 token / UTF-8 字节数。
|
||||
*/
|
||||
export function extractTextBytes(text: string): TextByteEstimate {
|
||||
const chars = text.length;
|
||||
const estimatedTokens = Math.ceil(chars / 4);
|
||||
const estimatedBytes = utf8ByteLength(text);
|
||||
return { chars, estimatedTokens, estimatedBytes };
|
||||
}
|
||||
|
||||
/**
|
||||
* 计算 UTF-8 编码字节数(不依赖 TextEncoder,纯算术,可移植)。
|
||||
*
|
||||
* @param text 文本。
|
||||
* @returns UTF-8 字节数。
|
||||
*/
|
||||
export function utf8ByteLength(text: string): number {
|
||||
let bytes = 0;
|
||||
for (let i = 0; i < text.length; i++) {
|
||||
const code = text.charCodeAt(i);
|
||||
if (code < 0x80) {
|
||||
bytes += 1;
|
||||
} else if (code < 0x800) {
|
||||
bytes += 2;
|
||||
} else if (code >= 0xd800 && code <= 0xdbff) {
|
||||
// surrogate pair (高代理) → 占 4 字节,跳过低位代理
|
||||
bytes += 4;
|
||||
i++;
|
||||
} else {
|
||||
bytes += 3;
|
||||
}
|
||||
}
|
||||
return bytes;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ④ 截断决策 + 续读提示
|
||||
// ============================================================================
|
||||
|
||||
/** 截断决策结果。 */
|
||||
export interface TruncationDecision {
|
||||
/** 是否需要截断。 */
|
||||
shouldTruncate: boolean;
|
||||
/** 建议一次读取的页数(>= 1 当需要截断时)。 */
|
||||
suggestedPageCount: number;
|
||||
/** 续读提示(下一段起始页),无需续读时 null。 */
|
||||
continuationHint: string | null;
|
||||
/** 决策原因(供 agent 理解 / 落 session 审计)。 */
|
||||
reason: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 决定是否截断并建议页范围。
|
||||
*
|
||||
* 策略:
|
||||
* - totalBytes <= maxBytes → 不截断,全读
|
||||
* - totalBytes > maxBytes → 按字节/页比例估算每次读几页,产出续读提示
|
||||
*
|
||||
* @param totalBytes 抽取出的全部文本字节数。
|
||||
* @param maxBytes 单次读取上限。
|
||||
* @param totalPages PDF 总页数。
|
||||
* @param currentPage 当前读取起始页(1-indexed,默认 1)。
|
||||
* @returns 截断决策。
|
||||
*/
|
||||
export function shouldTruncate(
|
||||
totalBytes: number,
|
||||
maxBytes: number,
|
||||
totalPages: number,
|
||||
currentPage: number = 1,
|
||||
): TruncationDecision {
|
||||
if (totalPages <= 0) {
|
||||
return {
|
||||
shouldTruncate: false,
|
||||
suggestedPageCount: 0,
|
||||
continuationHint: null,
|
||||
reason: "no pages to read",
|
||||
};
|
||||
}
|
||||
|
||||
if (totalBytes <= maxBytes) {
|
||||
return {
|
||||
shouldTruncate: false,
|
||||
suggestedPageCount: totalPages,
|
||||
continuationHint: null,
|
||||
reason: `content (${totalBytes} bytes) fits within limit (${maxBytes} bytes)`,
|
||||
};
|
||||
}
|
||||
|
||||
// 需要截断:按字节/页比例估算每次读几页
|
||||
const bytesPerPage = totalBytes / totalPages;
|
||||
const suggestedPageCount = Math.max(1, Math.floor(maxBytes / bytesPerPage));
|
||||
|
||||
// 不超过当前页之后的剩余页数
|
||||
const remaining = totalPages - currentPage + 1;
|
||||
const actualPageCount = Math.min(suggestedPageCount, remaining);
|
||||
|
||||
const nextPage = currentPage + actualPageCount;
|
||||
const continuationHint =
|
||||
nextPage <= totalPages
|
||||
? `use offset=${nextPage} to continue (pages ${currentPage}-${currentPage + actualPageCount - 1} of ${totalPages} shown)`
|
||||
: null;
|
||||
|
||||
return {
|
||||
shouldTruncate: true,
|
||||
suggestedPageCount: actualPageCount,
|
||||
continuationHint,
|
||||
reason: `content (${totalBytes} bytes) exceeds limit (${maxBytes} bytes); reading ${actualPageCount} of ${totalPages} pages per chunk`,
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ⑤ 提限配置(datasheet 场景)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* datasheet 场景的提限配置。治旧默认 2000 行/50KB → 8000 行/500KB。
|
||||
*
|
||||
* SoC datasheet(如 HR-PS6008e)3000-8000 页,寄存器头文件 5000+ 行;
|
||||
* 旧默认 2000 行/50KB 导致 agent 只看到前 1/4,查不到寄存器偏移就靠记忆 → 幻觉。
|
||||
*/
|
||||
export const DATASHEET_READ_LIMITS = {
|
||||
/** 最大行数(旧 2000 → 8000)。 */
|
||||
maxLines: 8000,
|
||||
/** 最大字节数(旧 50KB → 500KB)。 */
|
||||
maxBytes: 500 * 1024,
|
||||
} as const;
|
||||
|
||||
/** 旧默认值(截断命门的根因,保留供对比/回退)。 */
|
||||
export const LEGACY_READ_LIMITS = {
|
||||
maxLines: 2000,
|
||||
maxBytes: 50 * 1024,
|
||||
} as const;
|
||||
|
||||
// ============================================================================
|
||||
// ⑥ PDF 抽取抽象(注入,测试用 mock)
|
||||
// ============================================================================
|
||||
|
||||
/** PDF 抽取结果。 */
|
||||
export interface PdfExtractResult {
|
||||
/** 抽取出的文本。 */
|
||||
text: string;
|
||||
/** PDF 总页数。 */
|
||||
totalPages: number;
|
||||
/** 本次实际读取的页数。 */
|
||||
pagesRead: number;
|
||||
/** 读取的页范围(1-indexed)。 */
|
||||
pageRange: PageRange;
|
||||
}
|
||||
|
||||
/**
|
||||
* 可注入的 PDF 文本抽取函数。
|
||||
*
|
||||
* 扩展层用 unpdf 实现(纯 JS、无 native、ESM 友好);
|
||||
* 逻辑层/测试层注入 mock,绝不依赖真实 PDF 文件或硬件。
|
||||
*/
|
||||
export type ExtractPdfFn = (
|
||||
path: string,
|
||||
opts: { pageRange: PageRange; maxBytes?: number },
|
||||
) => Promise<PdfExtractResult>;
|
||||
|
||||
// ============================================================================
|
||||
// ⑦ 整合:规划一次 PDF 读取(不实际抽取)
|
||||
// ============================================================================
|
||||
|
||||
/** 一次 PDF 读取的规划结果。 */
|
||||
export interface PdfReadPlan {
|
||||
/** 要读的页范围。 */
|
||||
pageRange: PageRange;
|
||||
/** 要读的页数。 */
|
||||
pageCount: number;
|
||||
/** 是否截断。 */
|
||||
truncated: boolean;
|
||||
/** 续读提示。 */
|
||||
continuationHint: string | null;
|
||||
/** 字节估算(totalBytes 已知时填充)。 */
|
||||
estimate: TextByteEstimate | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 规划一次 PDF 读取:根据页范围请求 + 字节上限,决定读哪些页。
|
||||
* 不实际抽取(抽取由扩展层注入 ExtractPdfFn)。
|
||||
*
|
||||
* fail-closed:解析失败时回退到首页探测,绝不返回空操作。
|
||||
*
|
||||
* @param pageInput 页范围字符串("all"/"1-5"/"3,7,10" 等)。
|
||||
* @param totalPages PDF 总页数。
|
||||
* @param totalBytes 抽取出的全部文本字节数。
|
||||
* @param maxBytes 单次读取上限,默认 DATASHEET_READ_LIMITS.maxBytes。
|
||||
* @returns 读取规划。
|
||||
*/
|
||||
export function planPdfRead(
|
||||
pageInput: string,
|
||||
totalPages: number,
|
||||
totalBytes: number,
|
||||
maxBytes: number = DATASHEET_READ_LIMITS.maxBytes,
|
||||
): PdfReadPlan {
|
||||
const parsed = parsePageRange(pageInput, totalPages);
|
||||
|
||||
// 解析失败:fail-closed 回退到首页
|
||||
if (!parsed.valid) {
|
||||
const decision = shouldTruncate(totalBytes, maxBytes, totalPages, 1);
|
||||
const end = Math.min(decision.suggestedPageCount, totalPages);
|
||||
return {
|
||||
pageRange: { start: 1, end: Math.max(1, end) },
|
||||
pageCount: Math.max(1, end),
|
||||
truncated: decision.shouldTruncate,
|
||||
continuationHint: decision.continuationHint,
|
||||
estimate: totalBytes > 0 ? extractTextBytes("") : null,
|
||||
};
|
||||
}
|
||||
|
||||
// "all" 且不知道总页数:先读第一页探测
|
||||
if (parsed.all && (totalPages === 0 || parsed.ranges.length === 0)) {
|
||||
return {
|
||||
pageRange: { start: 1, end: 1 },
|
||||
pageCount: 1,
|
||||
truncated: true,
|
||||
continuationHint: "use offset=2 to continue (unknown total pages)",
|
||||
estimate: null,
|
||||
};
|
||||
}
|
||||
|
||||
// "all" 且知道总页数:检查是否需要截断
|
||||
if (parsed.all) {
|
||||
const decision = shouldTruncate(totalBytes, maxBytes, totalPages, 1);
|
||||
return {
|
||||
pageRange: { start: 1, end: decision.suggestedPageCount },
|
||||
pageCount: decision.suggestedPageCount,
|
||||
truncated: decision.shouldTruncate,
|
||||
continuationHint: decision.continuationHint,
|
||||
estimate: null,
|
||||
};
|
||||
}
|
||||
|
||||
// 指定了具体页范围
|
||||
const requestedRange = parsed.ranges[0] ?? { start: 1, end: 1 };
|
||||
const requestedPageCount = expandPages(parsed).length;
|
||||
const decision = shouldTruncate(totalBytes, maxBytes, totalPages, requestedRange.start);
|
||||
|
||||
// 如果指定页范围的字节估算可能超限,截断到建议页数
|
||||
if (decision.shouldTruncate && requestedPageCount > decision.suggestedPageCount) {
|
||||
const clampedEnd = Math.min(
|
||||
requestedRange.start + decision.suggestedPageCount - 1,
|
||||
requestedRange.end,
|
||||
);
|
||||
return {
|
||||
pageRange: { start: requestedRange.start, end: clampedEnd },
|
||||
pageCount: clampedEnd - requestedRange.start + 1,
|
||||
truncated: true,
|
||||
continuationHint: `use offset=${clampedEnd + 1} to continue`,
|
||||
estimate: null,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
pageRange: requestedRange,
|
||||
pageCount: requestedPageCount,
|
||||
truncated: false,
|
||||
continuationHint: null,
|
||||
estimate: null,
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ⑧ 构建读取结果文本(给扩展层用)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 构建带续读提示的读取结果文本。
|
||||
* 扩展层把抽取返回的 text 交给此函数拼装最终输出。
|
||||
*
|
||||
* @param text 抽取出的文本。
|
||||
* @param pageRange 本次读取的页范围。
|
||||
* @param totalPages PDF 总页数。
|
||||
* @param truncated 是否截断。
|
||||
* @param continuationHint 续读提示(截断时非 null)。
|
||||
* @returns 带 header/footer 的最终输出文本。
|
||||
*/
|
||||
export function buildReadResult(
|
||||
text: string,
|
||||
pageRange: PageRange,
|
||||
totalPages: number,
|
||||
truncated: boolean,
|
||||
continuationHint: string | null,
|
||||
): string {
|
||||
const estimate = extractTextBytes(text);
|
||||
const header =
|
||||
`--- PDF pages ${pageRange.start}-${pageRange.end} of ${totalPages} ` +
|
||||
`(${estimate.estimatedTokens} tokens, ${estimate.estimatedBytes} bytes) ---\n`;
|
||||
const footer = truncated && continuationHint
|
||||
? `\n\n[truncated] ${continuationHint}`
|
||||
: "";
|
||||
return header + text + footer;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 运行时 PDF 抽取(unpdf lazy import — 仅在工具执行时加载,不影响构建/测试)
|
||||
// ============================================================================
|
||||
// 以下三个函数是运行时 I/O 辅助(非纯逻辑、非导出),仅被工厂体内的工具 execute
|
||||
// 与 events 处理器调用。它们用 dynamic import 取 node:fs / unpdf,模块加载时不执行,
|
||||
// 故 tests import 本模块纯逻辑时不会触发文件 I/O 或 unpdf 解析。
|
||||
|
||||
/** unpdf 的最小类型签名(运行时 lazy import,构建/测试期不安装)。 */
|
||||
type UnpdfModule = {
|
||||
extractText: (
|
||||
buf: Uint8Array,
|
||||
opts: { first: number; last: number; max?: number },
|
||||
) => Promise<{ text: string; totalPages: number }>;
|
||||
};
|
||||
|
||||
/**
|
||||
* 默认 PDF 抽取实现:用 unpdf 抽取指定页范围的文本。
|
||||
* 若 unpdf 未安装,抛可诊断错误(建议 fallback 到 pdftotext)。
|
||||
*/
|
||||
async function extractPdfText(
|
||||
path: string,
|
||||
opts: { pageRange: PageRange; maxBytes?: number },
|
||||
): Promise<PdfExtractResult> {
|
||||
let unpdf: UnpdfModule;
|
||||
try {
|
||||
// @ts-expect-error — unpdf is an optional runtime dependency, not installed during typecheck/tests
|
||||
unpdf = await import("unpdf");
|
||||
} catch {
|
||||
throw new Error(
|
||||
"[pdf-reader] unpdf is not installed. Run `npm install unpdf` to enable PDF text extraction, " +
|
||||
"or use `pdftotext -layout` via the bash tool as fallback.",
|
||||
);
|
||||
}
|
||||
|
||||
const buffer = await readFileBytes(path);
|
||||
const { text, totalPages } = await unpdf.extractText(buffer, {
|
||||
first: opts.pageRange.start - 1, // unpdf: 0-indexed
|
||||
last: opts.pageRange.end - 1,
|
||||
max: opts.maxBytes,
|
||||
});
|
||||
|
||||
return {
|
||||
text,
|
||||
totalPages,
|
||||
pagesRead: opts.pageRange.end - opts.pageRange.start + 1,
|
||||
pageRange: opts.pageRange,
|
||||
};
|
||||
}
|
||||
|
||||
/** 读取文件头 N 字节(用于 PDF 魔数嗅探)。 */
|
||||
async function readFileHead(path: string, n: number = 8): Promise<Uint8Array> {
|
||||
const { open } = await import("node:fs/promises");
|
||||
const fd = await open(path, "r");
|
||||
try {
|
||||
const buf = new Uint8Array(n);
|
||||
const { bytesRead } = await fd.read(buf, 0, n, 0);
|
||||
return buf.slice(0, bytesRead);
|
||||
} finally {
|
||||
await fd.close();
|
||||
}
|
||||
}
|
||||
|
||||
/** 读取整个文件为 Uint8Array(PDF 抽取用)。 */
|
||||
async function readFileBytes(path: string): Promise<Uint8Array> {
|
||||
const { readFile } = await import("node:fs/promises");
|
||||
const buf = await readFile(path);
|
||||
return new Uint8Array(buf);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* pdf-reader 扩展装配。
|
||||
*
|
||||
* - 注册 read_pdf 工具(魔数嗅探 + 页范围 + 字节上限截断 + 续读提示)
|
||||
* - session_start 落条目:提限已生效(8000 行/500KB)
|
||||
* - tool_result 审计:记录每次 PDF 读取
|
||||
* - 暴露 PDF 抽取能力给其他扩展(如 datasheet RAG)经 events 总线
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*/
|
||||
export default async function pdfReaderExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
const readPdfSchema = Type.Object(
|
||||
{
|
||||
path: Type.String({
|
||||
description: "Absolute path to the PDF file to read.",
|
||||
}),
|
||||
pages: Type.Optional(
|
||||
Type.String({
|
||||
description:
|
||||
'Page range to read. Formats: "1-5" (range), "3,7,10" (list), "1-3,7,10-12" (mixed), "all" (everything). ' +
|
||||
"Defaults to reading the first chunk that fits within maxBytes.",
|
||||
}),
|
||||
),
|
||||
offset: Type.Optional(
|
||||
Type.Number({
|
||||
description:
|
||||
"Starting page for continued reading (1-indexed). Use the value from the previous read's continuation hint. " +
|
||||
"Overrides `pages` when set.",
|
||||
}),
|
||||
),
|
||||
maxBytes: Type.Optional(
|
||||
Type.Number({
|
||||
description:
|
||||
"Maximum bytes of text to return in one read. Default 500KB (datasheet scenario). " +
|
||||
"If the full range exceeds this, content is truncated and a continuation hint is returned.",
|
||||
}),
|
||||
),
|
||||
},
|
||||
{
|
||||
description:
|
||||
"Read a PDF file with pagination and byte-limit truncation. " +
|
||||
"Returns extracted text + total pages + continuation hint (\"use offset=N to continue\"). " +
|
||||
"Datasheet-safe: register addresses like 0x40020000 are preserved verbatim (no numeric coercion).",
|
||||
},
|
||||
);
|
||||
|
||||
const readPdfTool = defineTool({
|
||||
name: "read_pdf",
|
||||
label: "Read PDF",
|
||||
description:
|
||||
"Read a PDF file (e.g. SoC datasheet) with page-range selection and byte-limit truncation. " +
|
||||
"Supports continuous reading via offset. Register addresses are preserved verbatim.",
|
||||
promptSnippet:
|
||||
"Read PDF datasheets with pagination — use offset=N to continue reading the next chunk",
|
||||
parameters: readPdfSchema,
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as {
|
||||
path: string;
|
||||
pages?: string;
|
||||
offset?: number;
|
||||
maxBytes?: number;
|
||||
};
|
||||
|
||||
const filePath = p.path;
|
||||
const maxBytes = p.maxBytes ?? DATASHEET_READ_LIMITS.maxBytes;
|
||||
|
||||
try {
|
||||
// ① PDF 魔数嗅探(fail-closed:不是 PDF 就明确报错,避免乱码解码)
|
||||
const head = await readFileHead(filePath, 8);
|
||||
if (!isPdfMagic(head)) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: `[pdf-reader] File "${filePath}" is not a valid PDF (magic bytes mismatch). ` +
|
||||
`First bytes: ${Array.from(head.slice(0, 5))
|
||||
.map((b) => b.toString(16).padStart(2, "0"))
|
||||
.join(" ")}. ` +
|
||||
`Use the \`read\` tool for non-PDF files.`,
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
// ② 探测总页数:先读第 1 页
|
||||
const probeResult = await extractPdfText(filePath, {
|
||||
pageRange: { start: 1, end: 1 },
|
||||
});
|
||||
const totalPages = probeResult.totalPages;
|
||||
|
||||
// ③ 根据 offset 或 pages 规划读取
|
||||
let pageInput: string;
|
||||
if (p.offset !== undefined && p.offset > 0) {
|
||||
// 续读模式:从 offset 页开始
|
||||
const end = Math.min(p.offset + 9999, totalPages);
|
||||
pageInput = `${p.offset}-${end}`;
|
||||
} else {
|
||||
pageInput = p.pages ?? "1";
|
||||
}
|
||||
|
||||
// 用探测页的字节估算推算总字节(粗略,用于截断决策)
|
||||
const probeEstimate = extractTextBytes(probeResult.text);
|
||||
const estimatedTotalBytes = probeEstimate.estimatedBytes * totalPages;
|
||||
|
||||
const plan = planPdfRead(pageInput, totalPages, estimatedTotalBytes, maxBytes);
|
||||
|
||||
// ④ 执行实际抽取(如果探测页就是计划范围,直接复用)
|
||||
let result: PdfExtractResult;
|
||||
if (plan.pageRange.start === 1 && plan.pageRange.end === 1) {
|
||||
result = probeResult;
|
||||
} else {
|
||||
result = await extractPdfText(filePath, {
|
||||
pageRange: plan.pageRange,
|
||||
maxBytes,
|
||||
});
|
||||
}
|
||||
|
||||
// ⑤ 构建带续读提示的结果
|
||||
const outputText = buildReadResult(
|
||||
result.text,
|
||||
plan.pageRange,
|
||||
totalPages,
|
||||
plan.truncated,
|
||||
plan.continuationHint,
|
||||
);
|
||||
|
||||
return {
|
||||
content: [{ type: "text" as const, text: outputText }],
|
||||
details: {
|
||||
path: filePath,
|
||||
pageRange: plan.pageRange,
|
||||
totalPages,
|
||||
truncated: plan.truncated,
|
||||
continuationHint: plan.continuationHint,
|
||||
},
|
||||
};
|
||||
} catch (err) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text" as const,
|
||||
text: `[pdf-reader] PDF read failed: ${err instanceof Error ? err.message : String(err)}`,
|
||||
},
|
||||
],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
// ---- 注册 read_pdf 工具 ----
|
||||
pi.registerTool(readPdfTool);
|
||||
|
||||
// ---- session_start 落条目:提限已生效 ----
|
||||
pi.on("session_start", () => {
|
||||
pi.appendEntry("pdf-reader:limits-applied", {
|
||||
maxLines: DATASHEET_READ_LIMITS.maxLines,
|
||||
maxBytes: DATASHEET_READ_LIMITS.maxBytes,
|
||||
legacy: { maxLines: LEGACY_READ_LIMITS.maxLines, maxBytes: LEGACY_READ_LIMITS.maxBytes },
|
||||
note: "datasheet read limits upgraded from 2000 lines/50KB to 8000 lines/500KB",
|
||||
});
|
||||
});
|
||||
|
||||
// ---- tool_result 审计:记录每次 PDF 读取 ----
|
||||
pi.on("tool_result", (event) => {
|
||||
if (event.toolName !== "read_pdf") return undefined;
|
||||
const details = (
|
||||
event as { details?: { path?: string; pageRange?: PageRange; totalPages?: number } }
|
||||
).details;
|
||||
if (details) {
|
||||
pi.appendEntry("pdf-reader:pdf-read", {
|
||||
path: details.path,
|
||||
pageRange: details.pageRange,
|
||||
totalPages: details.totalPages,
|
||||
});
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// ---- 暴露 PDF 抽取能力给其他扩展(如 datasheet RAG)----
|
||||
pi.events.on("pdf-reader:request-extract", async (data) => {
|
||||
const d = data as { path: string; pageRange: PageRange; maxBytes?: number };
|
||||
try {
|
||||
const result = await extractPdfText(d.path, {
|
||||
pageRange: d.pageRange,
|
||||
maxBytes: d.maxBytes,
|
||||
});
|
||||
pi.events.emit("pdf-reader:extracted", result);
|
||||
} catch (err) {
|
||||
pi.events.emit("pdf-reader:extract-error", {
|
||||
error: err instanceof Error ? err.message : String(err),
|
||||
});
|
||||
}
|
||||
});
|
||||
}
|
||||
594
src/extensions/peripheral-probe.ts
Normal file
594
src/extensions/peripheral-probe.ts
Normal file
@ -0,0 +1,594 @@
|
||||
/**
|
||||
* @module peripheral-probe
|
||||
*
|
||||
* 外设探测与操作工具集 —— 嵌入式开发场景的"板级感知"主动能力。
|
||||
*
|
||||
* 治的缺陷:
|
||||
* - #8 hex 强转砖板:glm-5.2 把寄存器地址 0x40020000 强转成十进制,下游 devmem/i2cset
|
||||
* 写错地址即砖板。本扩展 prepareArguments 联动 glm-provider 的 hex 归一工厂兜底;
|
||||
* 纯逻辑 parseHexAddr 自适配 0x50 与 80 等值,写侧再显式 toHexAddr 规整喂给 i2cset。
|
||||
* - #4 硬件状态持久化 I2C/GPIO 分维度:写操作(i2c_set/gpio_set)经 appendEntry
|
||||
* 持久化 hw-state,按总线/引脚分维度记录,供闭环 verify 回放。
|
||||
* - #11 总线并发撞车:I2C/SPI/GPIO 共享物理总线,executionMode:"sequential" 串行化,
|
||||
* 防 agent 并发探测撞车。
|
||||
*
|
||||
* 场景锚定:电子维修诊断 SOP 的"上电前置感知"阶段(打阻值门之前先列 I2C/SPI/GPIO
|
||||
* 在线设备),以及驱动开发前的 /proc/iomem + interrupts 快照。所有外设命令通过注入的
|
||||
* ExecFn 执行,**绝不依赖真实硬件**,纯逻辑可离线单测。
|
||||
*
|
||||
* 见 Docs/F14_外设探测工具集.md。逻辑内联为命名导出,tests 直接单测,无需 pi 运行时。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
|
||||
import type { ExecFn } from "../shared/types.js";
|
||||
|
||||
// 注:defineTool / Type 仅在 factory 内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑函数
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时 factory 不跑,无副作用。
|
||||
|
||||
export type { ExecFn } from "../shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// #8 防御:hex 地址自适配(接受 0x50 和 80 → 同一 I2C 地址 0x50)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 把 agent 传入的 addr/reg/val 字符串或数字解析成十进制数值。
|
||||
*
|
||||
* 规则(hex 防御):
|
||||
* - "0x50" → 0x50 = 80
|
||||
* - "80" → 80 = 0x50(十进制,与 0x50 等值)
|
||||
* - 80 (number) → 80
|
||||
* - 解析失败抛错(fail-closed,绝不把脏值喂给 i2cset/devmem)。
|
||||
*
|
||||
* 用 parseInt(x, 0) 自适配前缀:0x 开头按 16 进制,否则按 10 进制。
|
||||
* 仅在自适配失败时 fallback 到纯 16 进制(如 "FF" → 0xFF)。
|
||||
*
|
||||
* @param input 地址/寄存器/值,字符串或数字。
|
||||
* @returns 十进制数值。
|
||||
*/
|
||||
export function parseHexAddr(input: string | number): number {
|
||||
if (typeof input === "number") {
|
||||
if (Number.isFinite(input) && input >= 0 && Number.isInteger(input)) return input;
|
||||
throw new Error(`[peripheral-probe] invalid address (number): ${input}`);
|
||||
}
|
||||
const s = String(input).trim();
|
||||
if (s === "") throw new Error("[peripheral-probe] empty address");
|
||||
// 自适配:0x 前缀→16,否则→10
|
||||
let n = parseInt(s, 0);
|
||||
if (!Number.isFinite(n) || n < 0) {
|
||||
// fallback:当作纯 hex
|
||||
n = parseInt(s, 16);
|
||||
}
|
||||
if (!Number.isFinite(n) || n < 0) {
|
||||
throw new Error(`[peripheral-probe] invalid address: ${input}`);
|
||||
}
|
||||
return n;
|
||||
}
|
||||
|
||||
/**
|
||||
* 数值 → "0x50" 形式(两位填充,大写),喂给 i2cset/devmem。
|
||||
*
|
||||
* @param addr 十进制地址。
|
||||
* @returns "0x50" 形式字符串。
|
||||
*/
|
||||
export function toHexAddr(addr: number): string {
|
||||
return "0x" + addr.toString(16).toUpperCase().padStart(2, "0");
|
||||
}
|
||||
|
||||
/**
|
||||
* I2C 7-bit 有效地址范围(i2cdetect 实际探测 0x03–0x77)。
|
||||
* 0x00–0x02 与 0x78–0x7f 是保留区,i2cdetect 不探测。
|
||||
*
|
||||
* @param addr 数值地址。
|
||||
* @returns 是否落在 7-bit 可探测范围。
|
||||
*/
|
||||
export function isValidI2cAddr(addr: number): boolean {
|
||||
return addr >= 0x03 && addr <= 0x77;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// I2C:i2cdetect 输出解析
|
||||
// ============================================================================
|
||||
|
||||
export type I2cAddrStatus = "present" | "in-use" | "empty";
|
||||
|
||||
export interface I2cDetectResult {
|
||||
/** 数值地址(0x20 = 32)。 */
|
||||
addr: number;
|
||||
/** "0x20" 形式。 */
|
||||
hex: string;
|
||||
status: I2cAddrStatus;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析 `i2cdetect -y <bus>` 的地址表。
|
||||
*
|
||||
* 输出格式(实测):
|
||||
* ```
|
||||
* 0 1 2 3 4 5 6 7 8 9 a b c d e f
|
||||
* 00: -- -- -- -- -- -- -- --
|
||||
* 20: 20 21 22 23 24 25 26 27 -- -- -- -- -- -- -- --
|
||||
* 70: -- -- -- -- -- -- -- -- UU -- -- -- -- -- -- --
|
||||
* ```
|
||||
* - 行头 `NN:` 是该行基地址(0x00/0x10/.../0x70),列 0–15 对应低半字节。
|
||||
* - 每列固定 3 字符宽:`20 `=present、`-- `=empty、`UU `=in-use、` `(空)=保留未探测。
|
||||
*
|
||||
* 返回所有非保留列的条目(present/empty/in-use),保留列(如 0x00–0x02)不出现。
|
||||
*
|
||||
* @param output i2cdetect 原始 stdout。
|
||||
* @returns 所有非保留列的地址条目。
|
||||
*/
|
||||
export function parseI2cDetect(output: string): I2cDetectResult[] {
|
||||
const results: I2cDetectResult[] = [];
|
||||
for (const raw of output.split("\n")) {
|
||||
const m = raw.match(/^([0-9a-fA-F]{2}):(.*)$/);
|
||||
if (!m) continue;
|
||||
// 行头是基地址本身(0x70 = 112),不是 *16。
|
||||
const base = parseInt(m[1] as string, 16);
|
||||
if (!Number.isFinite(base)) continue;
|
||||
const rest = m[2]; // 冒号后的全部内容
|
||||
for (let col = 0; col < 16; col++) {
|
||||
// 冒号后一个空格 + 16 个 3 字符列
|
||||
const start = 1 + col * 3;
|
||||
const tok = rest.slice(start, start + 3).trim();
|
||||
if (tok === "") continue; // 保留/未探测
|
||||
const addr = base + col;
|
||||
if (tok === "--") {
|
||||
results.push({ addr, hex: toHexAddr(addr), status: "empty" });
|
||||
} else if (tok === "UU") {
|
||||
results.push({ addr, hex: toHexAddr(addr), status: "in-use" });
|
||||
} else if (/^[0-9a-fA-F]{2}$/.test(tok)) {
|
||||
results.push({ addr, hex: toHexAddr(addr), status: "present" });
|
||||
}
|
||||
}
|
||||
}
|
||||
return results;
|
||||
}
|
||||
|
||||
/**
|
||||
* 只取 present 地址的数值数组。
|
||||
*
|
||||
* @param table parseI2cDetect 的结果。
|
||||
* @returns present 设备的数值地址数组。
|
||||
*/
|
||||
export function presentAddresses(table: I2cDetectResult[]): number[] {
|
||||
return table.filter((r) => r.status === "present").map((r) => r.addr);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// GPIO:gpioinfo 输出解析
|
||||
// ============================================================================
|
||||
|
||||
export interface GpioLineInfo {
|
||||
offset: number;
|
||||
name: string;
|
||||
consumer: string;
|
||||
direction: string;
|
||||
drive: string;
|
||||
}
|
||||
|
||||
export interface GpioChipInfo {
|
||||
chip: string; // "gpiochip0"
|
||||
lines: number;
|
||||
lineDetails: GpioLineInfo[];
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析 `gpioinfo`(libgpiod)输出。
|
||||
*
|
||||
* 格式:
|
||||
* ```
|
||||
* gpiochip0 - 512 lines:
|
||||
* line 0: "PIN3" unused output active-high
|
||||
* line 1: "PIN5" unused input active-high
|
||||
* gpiochip1 - 256 lines:
|
||||
* ```
|
||||
*
|
||||
* @param output gpioinfo 原始 stdout。
|
||||
* @returns 所有 chip 及其 line 详情。
|
||||
*/
|
||||
export function parseGpioInfo(output: string): GpioChipInfo[] {
|
||||
const chips: GpioChipInfo[] = [];
|
||||
let cur: GpioChipInfo | null = null;
|
||||
for (const raw of output.split("\n")) {
|
||||
const chipMatch = raw.match(/^(gpiochip\d+)\s*-\s*(\d+)\s+lines:/);
|
||||
if (chipMatch) {
|
||||
if (cur) chips.push(cur);
|
||||
cur = {
|
||||
chip: chipMatch[1] as string,
|
||||
lines: parseInt(chipMatch[2] as string, 10),
|
||||
lineDetails: [],
|
||||
};
|
||||
continue;
|
||||
}
|
||||
const lineMatch = raw.match(/^\s*line\s+(\d+):\s+"([^"]*)"\s+(\S+)\s+(\S+)\s+(\S+)/);
|
||||
if (lineMatch && cur) {
|
||||
cur.lineDetails.push({
|
||||
offset: parseInt(lineMatch[1] as string, 10),
|
||||
name: lineMatch[2] as string,
|
||||
consumer: lineMatch[3] as string,
|
||||
direction: lineMatch[4] as string,
|
||||
drive: lineMatch[5] as string,
|
||||
});
|
||||
}
|
||||
}
|
||||
if (cur) chips.push(cur);
|
||||
return chips;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 探测函数(注入 ExecFn,绝不碰真实硬件)
|
||||
// ============================================================================
|
||||
|
||||
export interface I2cBusInfo {
|
||||
bus: number;
|
||||
/** present 的设备地址(数值)。 */
|
||||
devices: number[];
|
||||
/** in-use(UU,已被驱动占用)的地址。 */
|
||||
inUse: number[];
|
||||
/** 探测失败时的错误(fail-closed:不静默吞错)。 */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 探测 I2C 总线。对每个 bus 跑 `i2cdetect -y <bus>`,解析地址表。
|
||||
*
|
||||
* buses 留空时自动枚举 /dev/i2c-*。
|
||||
* i2cdetect 非零退出 → 记录 error 但不抛(仍返回该 bus 条目,fail-closed 暴露失败)。
|
||||
*
|
||||
* @param exec 注入的执行函数。
|
||||
* @param buses 要探测的总线号数组,留空则自动枚举。
|
||||
* @returns 每条总线的设备/in-use/error 信息。
|
||||
*/
|
||||
export async function probeI2c(exec: ExecFn, buses: number[] = []): Promise<I2cBusInfo[]> {
|
||||
let busList = buses;
|
||||
if (busList.length === 0) {
|
||||
busList = await discoverI2cBuses(exec);
|
||||
}
|
||||
const out: I2cBusInfo[] = [];
|
||||
for (const bus of busList) {
|
||||
const res = await exec("i2cdetect", ["-y", String(bus)]);
|
||||
if (res.exitCode !== 0) {
|
||||
out.push({
|
||||
bus,
|
||||
devices: [],
|
||||
inUse: [],
|
||||
error: (res.stderr || `i2cdetect exit ${res.exitCode}`).trim(),
|
||||
});
|
||||
continue;
|
||||
}
|
||||
const table = parseI2cDetect(res.stdout);
|
||||
out.push({
|
||||
bus,
|
||||
devices: presentAddresses(table),
|
||||
inUse: table.filter((r) => r.status === "in-use").map((r) => r.addr),
|
||||
});
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* 枚举 /dev/i2c-N,返回总线号升序。
|
||||
*
|
||||
* @param exec 注入的执行函数。
|
||||
* @returns 升序总线号数组。
|
||||
*/
|
||||
export async function discoverI2cBuses(exec: ExecFn): Promise<number[]> {
|
||||
const res = await exec("sh", ["-c", "ls -1 /dev/i2c-* 2>/dev/null || true"]);
|
||||
const buses: number[] = [];
|
||||
if (res.exitCode !== 0) return buses;
|
||||
for (const ln of res.stdout.split("\n")) {
|
||||
const m = ln.trim().match(/^\/dev\/i2c-(\d+)$/);
|
||||
if (m) buses.push(parseInt(m[1] as string, 10));
|
||||
}
|
||||
buses.sort((a, b) => a - b);
|
||||
return buses;
|
||||
}
|
||||
|
||||
/**
|
||||
* 探测 GPIO:跑 `gpioinfo`,解析所有 chip + line。
|
||||
* gpioinfo 非零退出(如工具未装)→ 抛错(fail-closed,让 agent 知道探测失败)。
|
||||
*
|
||||
* @param exec 注入的执行函数。
|
||||
* @returns 所有 chip 及其 line 详情。
|
||||
*/
|
||||
export async function probeGpio(exec: ExecFn): Promise<GpioChipInfo[]> {
|
||||
const res = await exec("gpioinfo", []);
|
||||
if (res.exitCode !== 0) {
|
||||
throw new Error(
|
||||
`[peripheral-probe] gpioinfo failed (exit ${res.exitCode}): ${(res.stderr || "").trim() || "tool not installed?"}`,
|
||||
);
|
||||
}
|
||||
return parseGpioInfo(res.stdout);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// SPI 探测
|
||||
// ============================================================================
|
||||
|
||||
export interface SpiDevInfo {
|
||||
dev: string; // "/dev/spidev0.0"
|
||||
bus: number;
|
||||
chipSelect: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 枚举 /dev/spidevN.M。无设备返回空数组(SPI 可能未使能,属正常)。
|
||||
*
|
||||
* @param exec 注入的执行函数。
|
||||
* @returns SPI 设备信息数组。
|
||||
*/
|
||||
export async function probeSpi(exec: ExecFn): Promise<SpiDevInfo[]> {
|
||||
const res = await exec("sh", ["-c", "ls -1 /dev/spidev* 2>/dev/null || true"]);
|
||||
const out: SpiDevInfo[] = [];
|
||||
if (res.exitCode !== 0) return out;
|
||||
for (const ln of res.stdout.split("\n")) {
|
||||
const t = ln.trim();
|
||||
const m = t.match(/^\/dev\/spidev(\d+)\.(\d+)$/);
|
||||
if (m) {
|
||||
out.push({
|
||||
dev: t,
|
||||
bus: parseInt(m[1] as string, 10),
|
||||
chipSelect: parseInt(m[2] as string, 10),
|
||||
});
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// udev / sysfs class 探测
|
||||
// ============================================================================
|
||||
|
||||
export interface UdevDeviceInfo {
|
||||
name: string;
|
||||
subsystem: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 列 /sys/class/<subsystem>/ 下的设备。subsystem 会被清洗防 shell 注入。
|
||||
* 例:probeUdev(exec, "net") → [{name:"eth0",...},{name:"wlan0",...}]
|
||||
*
|
||||
* @param exec 注入的执行函数。
|
||||
* @param subsystem sysfs class 子系统名(如 net/gpio/tty)。
|
||||
* @returns 设备信息数组。
|
||||
*/
|
||||
export async function probeUdev(exec: ExecFn, subsystem: string): Promise<UdevDeviceInfo[]> {
|
||||
// 清洗:只保留字母/数字/下划线/连字符,防注入。
|
||||
const safe = subsystem.replace(/[^a-zA-Z0-9_-]/g, "");
|
||||
if (safe === "") return [];
|
||||
const res = await exec("sh", ["-c", `ls -1 /sys/class/${safe}/ 2>/dev/null || true`]);
|
||||
const out: UdevDeviceInfo[] = [];
|
||||
if (res.exitCode !== 0) return out;
|
||||
for (const ln of res.stdout.split("\n")) {
|
||||
const t = ln.trim();
|
||||
if (t && !t.startsWith("ls:")) out.push({ name: t, subsystem: safe });
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// mem_snap:/proc/iomem + /proc/interrupts 快照(只读调试)
|
||||
// ============================================================================
|
||||
|
||||
export interface MemSnap {
|
||||
iomem: string;
|
||||
interrupts: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 快照 /proc/iomem 与 /proc/interrupts(只读调试,驱动开发前看内存/中断映射)。
|
||||
* /proc 不可读时对应字段返回空串(不抛,fail-open 因只读无害)。
|
||||
*
|
||||
* @param exec 注入的执行函数。
|
||||
* @returns iomem + interrupts 原始内容。
|
||||
*/
|
||||
export async function probeMemSnap(exec: ExecFn): Promise<MemSnap> {
|
||||
const [iomemRes, intrRes] = await Promise.all([
|
||||
exec("cat", ["/proc/iomem"]),
|
||||
exec("cat", ["/proc/interrupts"]),
|
||||
]);
|
||||
return {
|
||||
iomem: iomemRes.exitCode === 0 ? iomemRes.stdout : "",
|
||||
interrupts: intrRes.exitCode === 0 ? intrRes.stdout : "",
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* peripheral-probe 扩展装配。
|
||||
*
|
||||
* 注册一个 `bus_probe` 工具带 action 子命令(非多个细粒度工具,防工具列表膨胀)。
|
||||
* 探测侧调纯逻辑(probeGpio/probeI2c/probeSpi/probeUdev/probeMemSnap),写侧
|
||||
* (i2c_set/gpio_set)调 parseHexAddr 做 hex 防御 + appendEntry 持久化 hw-state。
|
||||
* executionMode:"sequential" 防 I2C/SPI/GPIO 共享总线并发撞车(缺陷 #11)。
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
* prepareArguments 的 hex 归一工厂从 glm-provider 动态拿(跨扩展纯逻辑,运行时解析)。
|
||||
*/
|
||||
export default async function peripheralProbeExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
const { makeHexNormalizingPrepareArguments } = await import("./glm-provider.js");
|
||||
|
||||
/** 把 pi.exec 包成 ExecFn(结构与 shared/types.ExecFn 兼容)。 */
|
||||
const exec: ExecFn = (command, args, opts) => pi.exec(command, args, opts);
|
||||
|
||||
/** 构造纯文本工具结果。 */
|
||||
function text(t: string) {
|
||||
return { content: [{ type: "text" as const, text: t }] };
|
||||
}
|
||||
/** 构造错误工具结果。 */
|
||||
function err(t: string) {
|
||||
return { content: [{ type: "text" as const, text: `❌ ${t}` }], isError: true };
|
||||
}
|
||||
|
||||
const busProbeTool = defineTool({
|
||||
name: "bus_probe",
|
||||
label: "Peripheral Probe",
|
||||
description:
|
||||
"Probe and operate embedded peripherals via Linux character-device/bus interfaces: " +
|
||||
"I2C (i2cdetect/i2cget/i2cset), SPI (spidev enum), GPIO (libgpiod gpioinfo/gpioget/gpioset), " +
|
||||
"udev/sysfs class enumeration, and /proc mem+interrupts snapshot. " +
|
||||
"All addr/reg/val accept hex (0x50) or decimal (80) and normalize identically. " +
|
||||
"Write actions (i2c_set/gpio_set) persist hw-state to the session.",
|
||||
promptSnippet:
|
||||
"Use bus_probe to scan I2C buses, read GPIO chips, list SPI devices, and snapshot /proc/iomem before writing drivers.",
|
||||
parameters: Type.Object(
|
||||
{
|
||||
action: Type.Union(
|
||||
[
|
||||
Type.Literal("i2c_detect"),
|
||||
Type.Literal("i2c_get"),
|
||||
Type.Literal("i2c_set"),
|
||||
Type.Literal("spi_list"),
|
||||
Type.Literal("gpio_info"),
|
||||
Type.Literal("gpio_get"),
|
||||
Type.Literal("gpio_set"),
|
||||
Type.Literal("udev_list"),
|
||||
Type.Literal("mem_snap"),
|
||||
],
|
||||
{ description: "Probe action" },
|
||||
),
|
||||
bus: Type.Optional(Type.Number({ description: "I2C bus number, e.g. 0" })),
|
||||
addr: Type.Optional(Type.String({ description: "I2C device address, hex (0x50) or decimal (80)" })),
|
||||
reg: Type.Optional(Type.String({ description: "Register address, hex (0x10) preferred" })),
|
||||
val: Type.Optional(Type.String({ description: "Value to write, hex (0x3F) preferred" })),
|
||||
chip: Type.Optional(Type.Number({ description: "GPIO chip number" })),
|
||||
line: Type.Optional(Type.Number({ description: "GPIO line offset" })),
|
||||
subsystem: Type.Optional(Type.String({ description: "sysfs class subsystem, e.g. net/gpio/tty" })),
|
||||
},
|
||||
{ description: "Peripheral probe / operate parameters" },
|
||||
),
|
||||
// hex 防御:归一 glm-5.2 强转成十进制的大寄存器地址(缺陷 #8)
|
||||
prepareArguments: makeHexNormalizingPrepareArguments({
|
||||
fieldDenylist: ["bus", "chip", "line", "subsystem"],
|
||||
}),
|
||||
executionMode: "sequential", // 缺陷 #11:I2C/SPI/GPIO 共享总线不并发
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as {
|
||||
action: string;
|
||||
bus?: number;
|
||||
addr?: string;
|
||||
reg?: string;
|
||||
val?: string;
|
||||
chip?: number;
|
||||
line?: number;
|
||||
subsystem?: string;
|
||||
};
|
||||
try {
|
||||
switch (p.action) {
|
||||
case "i2c_detect": {
|
||||
const buses = p.bus !== undefined ? [p.bus] : [];
|
||||
const res = await probeI2c(exec, buses);
|
||||
return text(JSON.stringify(res, null, 2));
|
||||
}
|
||||
case "i2c_get": {
|
||||
if (p.bus === undefined || p.addr === undefined || p.reg === undefined) {
|
||||
return err("i2c_get requires bus, addr, reg");
|
||||
}
|
||||
const addr = parseHexAddr(p.addr);
|
||||
const reg = parseHexAddr(p.reg);
|
||||
const r = await exec("i2cget", ["-y", String(p.bus), toHexAddr(addr), toHexAddr(reg)]);
|
||||
if (r.exitCode !== 0) return err(`i2cget failed: ${r.stderr}`);
|
||||
return text(`i2cget bus${p.bus} ${toHexAddr(addr)} ${toHexAddr(reg)} = ${r.stdout.trim()}`);
|
||||
}
|
||||
case "i2c_set": {
|
||||
if (p.bus === undefined || p.addr === undefined || p.reg === undefined || p.val === undefined) {
|
||||
return err("i2c_set requires bus, addr, reg, val");
|
||||
}
|
||||
const addr = parseHexAddr(p.addr);
|
||||
const reg = parseHexAddr(p.reg);
|
||||
const val = parseHexAddr(p.val);
|
||||
const r = await exec("i2cset", [
|
||||
"-y",
|
||||
String(p.bus),
|
||||
toHexAddr(addr),
|
||||
toHexAddr(reg),
|
||||
toHexAddr(val),
|
||||
]);
|
||||
if (r.exitCode !== 0) return err(`i2cset failed: ${r.stderr}`);
|
||||
// hw-state 联动:持久化写操作(缺陷 #4 分维度)
|
||||
pi.appendEntry("hw-state", {
|
||||
kind: "i2c_set",
|
||||
bus: p.bus,
|
||||
addr: toHexAddr(addr),
|
||||
reg: toHexAddr(reg),
|
||||
val: toHexAddr(val),
|
||||
timestamp: Date.now(),
|
||||
});
|
||||
return text(`i2cset bus${p.bus} ${toHexAddr(addr)} ${toHexAddr(reg)} ${toHexAddr(val)} OK`);
|
||||
}
|
||||
case "spi_list": {
|
||||
const res = await probeSpi(exec);
|
||||
return text(JSON.stringify(res, null, 2));
|
||||
}
|
||||
case "gpio_info": {
|
||||
const res = await probeGpio(exec);
|
||||
return text(JSON.stringify(res, null, 2));
|
||||
}
|
||||
case "gpio_get": {
|
||||
if (p.chip === undefined || p.line === undefined) {
|
||||
return err("gpio_get requires chip, line");
|
||||
}
|
||||
const r = await exec("gpioget", [`gpiochip${p.chip}`, String(p.line)]);
|
||||
if (r.exitCode !== 0) return err(`gpioget failed: ${r.stderr}`);
|
||||
return text(`gpioget gpiochip${p.chip} line${p.line} = ${r.stdout.trim()}`);
|
||||
}
|
||||
case "gpio_set": {
|
||||
if (p.chip === undefined || p.line === undefined || p.val === undefined) {
|
||||
return err("gpio_set requires chip, line, val");
|
||||
}
|
||||
const val = parseHexAddr(p.val); // 接受 0x1 / 1
|
||||
const r = await exec("gpioset", [`gpiochip${p.chip}`, `${p.line}=${val}`]);
|
||||
if (r.exitCode !== 0) return err(`gpioset failed: ${r.stderr}`);
|
||||
pi.appendEntry("hw-state", {
|
||||
kind: "gpio_set",
|
||||
chip: p.chip,
|
||||
line: p.line,
|
||||
val,
|
||||
timestamp: Date.now(),
|
||||
});
|
||||
return text(`gpioset gpiochip${p.chip} line${p.line}=${val} OK`);
|
||||
}
|
||||
case "udev_list": {
|
||||
const sub = p.subsystem ?? "gpio";
|
||||
const res = await probeUdev(exec, sub);
|
||||
return text(JSON.stringify(res, null, 2));
|
||||
}
|
||||
case "mem_snap": {
|
||||
const res = await probeMemSnap(exec);
|
||||
return text(
|
||||
`--- /proc/iomem ---\n${res.iomem}\n--- /proc/interrupts ---\n${res.interrupts}`,
|
||||
);
|
||||
}
|
||||
default:
|
||||
return err(`unknown action: ${p.action}`);
|
||||
}
|
||||
} catch (e) {
|
||||
return err(e instanceof Error ? e.message : String(e));
|
||||
}
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(busProbeTool);
|
||||
pi.on("session_start", () => {
|
||||
pi.appendEntry("probe:loaded", {
|
||||
actions: [
|
||||
"i2c_detect",
|
||||
"i2c_get",
|
||||
"i2c_set",
|
||||
"spi_list",
|
||||
"gpio_info",
|
||||
"gpio_get",
|
||||
"gpio_set",
|
||||
"udev_list",
|
||||
"mem_snap",
|
||||
],
|
||||
});
|
||||
});
|
||||
}
|
||||
548
src/extensions/persistent-shell.ts
Normal file
548
src/extensions/persistent-shell.ts
Normal file
@ -0,0 +1,548 @@
|
||||
/**
|
||||
* @module persistent-shell
|
||||
*
|
||||
* 持久 Shell 与交互式会话工具 —— 治嵌入式开发场景下 bash 每命令新进程、
|
||||
* gdb/OpenOCD/minicom 等交互式长会话不可用的缺陷。
|
||||
*
|
||||
* 场景锚定:断点(gdb `break main` → `run` → `info breakpoints` 必须在同一进程里
|
||||
* 连续发)、JTAG attach(openocd 占住 JTAG 不能被新进程抢)、串口监听
|
||||
* (picocom/minicom 跨多轮 tool call 保活)。一次性命令仍走 `bash`。
|
||||
*
|
||||
* 本层只管理会话池元数据与命令编排,真正的 PTY spawn/读写由扩展层注入的
|
||||
* ExecFn 完成(测试用 mock ExecFn,绝不依赖真实硬件/子进程)。逻辑已过单测,
|
||||
* 此处迁移而非重写。fail-closed 语义保留:哨兵缺失/超时/进程崩一律判失败,
|
||||
* 不信"完成"。
|
||||
*
|
||||
* 装配范式(参照 glm-provider / safety-gate):
|
||||
* - 顶层仅 `import type`(esbuild/tsc 擦除),无运行时 pi 依赖 → tests 直接 import
|
||||
* 纯逻辑命名导出即可离线单测,不拉未构建 pi。
|
||||
* - `export default async function` 工厂内 `await import` 动态拿 defineTool/Type,
|
||||
* 工具定义 + pi.registerTool/pi.on/pi.appendEntry 全在工厂体内。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
|
||||
import type { ExecFn, ExecResult, PShellSession } from "../shared/types.js";
|
||||
|
||||
// 注:defineTool / Type 仅在 factory 内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时 factory 不跑,无副作用。
|
||||
|
||||
/** 重新导出 ExecFn,供扩展层按本模块符号引用(解耦 import 路径)。 */
|
||||
export type ExecFnLike = ExecFn;
|
||||
|
||||
// ============================================================================
|
||||
// Sentinel:在同一条 PTY 命令尾部追加哨兵,解析 exitCode 与 stdout
|
||||
// ============================================================================
|
||||
|
||||
/** 哨兵标记,写到命令尾部;出现即代表命令结束。 */
|
||||
export const PSHELL_SENTINEL = "__PSHELL_DONE__";
|
||||
|
||||
/**
|
||||
* 给命令追加哨兵 + exitCode 回显。扩展层把整条写进 PTY stdin,
|
||||
* 读到哨兵行即停。形如:`<command>; echo "__PSHELL_DONE__$?"`。
|
||||
*
|
||||
* 注意:command 末尾不强制换行——shell 的 `;` 在同一行串联即可。
|
||||
* 空 command 也安全(仅回显哨兵,用于探测会话存活)。
|
||||
*
|
||||
* @param command 原始命令串。
|
||||
* @returns 追加哨兵后的完整命令串。
|
||||
*/
|
||||
export function buildSentinelCommand(command: string): string {
|
||||
const trimmed = (command ?? "").trimEnd();
|
||||
if (trimmed === "") {
|
||||
return `echo "${PSHELL_SENTINEL}$?"`;
|
||||
}
|
||||
return `${trimmed}; echo "${PSHELL_SENTINEL}$?"`;
|
||||
}
|
||||
|
||||
export interface ParsedSentinel {
|
||||
/** 哨兵之前的全部 stdout。 */
|
||||
stdout: string;
|
||||
/** 哨兵行里回显的 exitCode;未解析到哨兵时为 null。 */
|
||||
exitCode: number | null;
|
||||
/** 是否成功解析到哨兵。 */
|
||||
found: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从 PTY 读取的原始输出里拆出 stdout 与 exitCode。
|
||||
*
|
||||
* 哨兵行形如 `__PSHELL_DONE__0`(exit 0)。可能有 CR/LF 混杂(PTY),
|
||||
* 用正则匹配末尾哨兵,兼容 \r。
|
||||
*
|
||||
* 未找到哨兵(execFn 超时/进程崩):found=false,stdout=原样输出,exitCode=null,
|
||||
* 调用方应按 fail-closed 处理(不可信的"完成")。
|
||||
*
|
||||
* @param raw PTY 读取的原始输出。
|
||||
* @returns 解析结果 { stdout, exitCode, found }。
|
||||
*/
|
||||
export function parseSentinelOutput(raw: string): ParsedSentinel {
|
||||
if (raw == null) {
|
||||
return { stdout: "", exitCode: null, found: false };
|
||||
}
|
||||
const re = new RegExp(`${PSHELL_SENTINEL}(\\d+)\\s*$`, "m");
|
||||
const match = re.exec(raw);
|
||||
if (!match) {
|
||||
return { stdout: raw, exitCode: null, found: false };
|
||||
}
|
||||
const exitCode = Number.parseInt(match[1] ?? "0", 10);
|
||||
// 哨兵及之后整段裁掉(含哨兵行前可能残留的换行)
|
||||
const idx = raw.indexOf(PSHELL_SENTINEL);
|
||||
const stdout = idx >= 0 ? raw.slice(0, idx) : raw;
|
||||
// 去掉哨兵行前残留的尾部换行(PTY 常多一个 \r\n)
|
||||
return { stdout: stdout.replace(/\r?\n$/, ""), exitCode, found: true };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 会话池
|
||||
// ============================================================================
|
||||
|
||||
/** busy 冲突策略:reject=直接拒绝(fail-closed,默认);queue=排队等当前完成。 */
|
||||
export type BusyPolicy = "reject" | "queue";
|
||||
|
||||
export interface PShellPoolOptions {
|
||||
/** 自定义 sessionId 生成器(测试注入确定性 id)。 */
|
||||
idGenerator?: () => string;
|
||||
/** busy 冲突策略,默认 reject。 */
|
||||
busyPolicy?: BusyPolicy;
|
||||
/** 单条命令默认超时(毫秒),默认 30000。 */
|
||||
defaultTimeoutMs?: number;
|
||||
/** open 时的初始 cwd(透传给 ExecFn 的 ExecOpts.cwd)。 */
|
||||
defaultCwd?: string;
|
||||
}
|
||||
|
||||
/** 池内会话记录(PShellSession + 内部审计字段)。 */
|
||||
interface PShellSessionInternal extends PShellSession {
|
||||
/** 最近一次活动时间戳(ms),用于 idle 回收。 */
|
||||
lastActivityAt: number;
|
||||
/** 排队的待执行命令(busyPolicy=queue 时)。 */
|
||||
pending: Array<{ command: string; timeoutMs?: number }>;
|
||||
/** 会话级 cwd 覆盖(open 时传入)。 */
|
||||
cwd?: string;
|
||||
}
|
||||
|
||||
export interface SendCommandOpts {
|
||||
/** 单条命令超时(毫秒),覆盖池默认。 */
|
||||
timeoutMs?: number;
|
||||
}
|
||||
|
||||
/** sendCommand 的统一返回结构。ok=false 时 stdout/stderr/exitCode 不可信。 */
|
||||
export interface PShellSendResult {
|
||||
ok: boolean;
|
||||
sessionId: string;
|
||||
stdout: string;
|
||||
stderr: string;
|
||||
exitCode: number;
|
||||
/** 命令因 busy 被排队(busyPolicy=queue)。 */
|
||||
queued?: boolean;
|
||||
/** 失败原因(session 不存在 / busy / timeout / 哨兵缺失)。 */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
const DEFAULT_TIMEOUT_MS = 30_000;
|
||||
|
||||
/**
|
||||
* 持久 Shell 会话池。纯逻辑,ExecFn 注入执行。
|
||||
*
|
||||
* 用法(扩展层):
|
||||
* const pool = new PShellPool({ busyPolicy: "reject" });
|
||||
* const id = pool.open({ cwd: "/work" });
|
||||
* const r = await pool.send(id, "break main", execFn, { timeoutMs: 5000 });
|
||||
* pool.close(id);
|
||||
*
|
||||
* fail-closed:会话不存在/哨兵缺失/超时一律 ok:false,绝不把不可信输出当成功。
|
||||
*/
|
||||
export class PShellPool {
|
||||
private sessions = new Map<string, PShellSessionInternal>();
|
||||
private readonly idGen: () => string;
|
||||
private readonly busyPolicy: BusyPolicy;
|
||||
private readonly defaultTimeoutMs: number;
|
||||
private readonly defaultCwd?: string;
|
||||
private counter = 0;
|
||||
|
||||
constructor(opts: PShellPoolOptions = {}) {
|
||||
this.idGen = opts.idGenerator ?? (() => `pshell-${++this.counter}`);
|
||||
this.busyPolicy = opts.busyPolicy ?? "reject";
|
||||
this.defaultTimeoutMs = opts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
|
||||
this.defaultCwd = opts.defaultCwd;
|
||||
}
|
||||
|
||||
/**
|
||||
* 新建会话,返回 sessionId。
|
||||
* @param opts.id 自定义 id(否则用 idGenerator)。
|
||||
* @param opts.cwd 会话初始工作目录。
|
||||
* @returns 新会话 id。
|
||||
*/
|
||||
open(opts: { cwd?: string; id?: string } = {}): string {
|
||||
const id = opts.id ?? this.idGen();
|
||||
const now = Date.now();
|
||||
this.sessions.set(id, {
|
||||
id,
|
||||
createdAt: now,
|
||||
lastCommand: undefined,
|
||||
busy: false,
|
||||
lastActivityAt: now,
|
||||
pending: [],
|
||||
cwd: opts.cwd ?? this.defaultCwd,
|
||||
});
|
||||
return id;
|
||||
}
|
||||
|
||||
/**
|
||||
* 关闭会话;不存在返回 false,不抛。排空待执行队列(fail-closed 丢弃未执行命令)。
|
||||
* @param id 会话 id。
|
||||
* @returns 是否关闭成功。
|
||||
*/
|
||||
close(id: string): boolean {
|
||||
const s = this.sessions.get(id);
|
||||
if (!s) return false;
|
||||
// 排空待执行队列(fail-closed:丢弃未执行命令,记 stderr 提示由调用方处理)
|
||||
s.pending.length = 0;
|
||||
this.sessions.delete(id);
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 关闭全部会话,返回被关闭的 id 列表。session 结束务必调,防孤儿 openocd 占 JTAG。
|
||||
* @returns 被关闭的会话 id 列表。
|
||||
*/
|
||||
closeAll(): string[] {
|
||||
const ids = [...this.sessions.keys()];
|
||||
for (const id of ids) {
|
||||
const s = this.sessions.get(id);
|
||||
if (s) s.pending.length = 0;
|
||||
this.sessions.delete(id);
|
||||
}
|
||||
return ids;
|
||||
}
|
||||
|
||||
/** @param id 会话 id。 @returns 会话是否存在。 */
|
||||
has(id: string): boolean {
|
||||
return this.sessions.has(id);
|
||||
}
|
||||
|
||||
/**
|
||||
* 投影出公开字段,不泄露 pending/cwd。
|
||||
* @param id 会话 id。
|
||||
* @returns 公开会话快照;不存在返回 undefined。
|
||||
*/
|
||||
get(id: string): PShellSession | undefined {
|
||||
const s = this.sessions.get(id);
|
||||
if (!s) return undefined;
|
||||
return { id: s.id, createdAt: s.createdAt, lastCommand: s.lastCommand, busy: s.busy };
|
||||
}
|
||||
|
||||
/**
|
||||
* 列出全部会话(按创建顺序)。
|
||||
* @returns 公开会话快照数组。
|
||||
*/
|
||||
list(): PShellSession[] {
|
||||
return [...this.sessions.values()].map((s) => ({
|
||||
id: s.id,
|
||||
createdAt: s.createdAt,
|
||||
lastCommand: s.lastCommand,
|
||||
busy: s.busy,
|
||||
}));
|
||||
}
|
||||
|
||||
/** @param id 会话 id。 @returns 是否 busy。 */
|
||||
isBusy(id: string): boolean {
|
||||
return this.sessions.get(id)?.busy ?? false;
|
||||
}
|
||||
|
||||
/**
|
||||
* 手动标记 busy/idle(gdb/openocd 长会话,扩展层在 attach/detach 时用)。
|
||||
* @param id 会话 id。
|
||||
* @param busy 是否占用。
|
||||
* @returns 是否标记成功(会话不存在返回 false)。
|
||||
*/
|
||||
markBusy(id: string, busy: boolean): boolean {
|
||||
const s = this.sessions.get(id);
|
||||
if (!s) return false;
|
||||
s.busy = busy;
|
||||
if (!busy) {
|
||||
s.lastActivityAt = Date.now();
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 向会话发命令。注入 ExecFn 模拟执行:
|
||||
* 1. 会话不存在 → ok:false error:"session-not-found"
|
||||
* 2. busy + reject → ok:false error:"busy"
|
||||
* 3. busy + queue → ok:false queued:true(命令进队列,当前完成后自动 drain)
|
||||
* 4. 否则标记 busy → 用 sentinel 命令调 execFn → 解析 → 标记 idle → drain 队列
|
||||
*
|
||||
* execFn 抛错(含超时)→ ok:false error:"timeout",会话仍被标 idle(不锁死)。
|
||||
* 哨兵未找到 → ok:false error:"sentinel-missing"(fail-closed,不信"完成")。
|
||||
*
|
||||
* @param id 会话 id。
|
||||
* @param command 命令串。
|
||||
* @param execFn 注入的执行函数。
|
||||
* @param opts.timeoutMs 单条命令超时。
|
||||
* @returns 统一返回结构 PShellSendResult。
|
||||
*/
|
||||
async send(
|
||||
id: string,
|
||||
command: string,
|
||||
execFn: ExecFn,
|
||||
opts: SendCommandOpts = {},
|
||||
): Promise<PShellSendResult> {
|
||||
const s = this.sessions.get(id);
|
||||
if (!s) {
|
||||
return this.fail(id, "session-not-found");
|
||||
}
|
||||
|
||||
if (s.busy) {
|
||||
if (this.busyPolicy === "queue") {
|
||||
s.pending.push({ command, timeoutMs: opts.timeoutMs });
|
||||
return { ok: false, sessionId: id, stdout: "", stderr: "", exitCode: -1, queued: true, error: "busy" };
|
||||
}
|
||||
return this.fail(id, "busy");
|
||||
}
|
||||
|
||||
return this.execute(s, command, execFn, opts);
|
||||
}
|
||||
|
||||
/**
|
||||
* idle 超时回收:关闭 lastActivityAt 距 now 超过 idleMs 的会话。
|
||||
* busy 会话不回收(gdb/openocd 正占用)。
|
||||
* @param now 当前时间戳(ms),默认 Date.now()。
|
||||
* @param idleMs 空闲阈值(ms),默认 10 分钟。
|
||||
* @returns 被回收的会话 id 列表。
|
||||
*/
|
||||
sweepIdle(now: number = Date.now(), idleMs: number = 10 * 60 * 1000): string[] {
|
||||
const closed: string[] = [];
|
||||
for (const [id, s] of this.sessions) {
|
||||
if (s.busy) continue; // 长会话不回收(gdb/openocd 正占用)
|
||||
if (now - s.lastActivityAt >= idleMs) {
|
||||
this.close(id);
|
||||
closed.push(id);
|
||||
}
|
||||
}
|
||||
return closed;
|
||||
}
|
||||
|
||||
// --------------------------------------------------------------------------
|
||||
// 内部
|
||||
// --------------------------------------------------------------------------
|
||||
|
||||
private fail(id: string, error: string): PShellSendResult {
|
||||
return { ok: false, sessionId: id, stdout: "", stderr: "", exitCode: -1, error };
|
||||
}
|
||||
|
||||
private async execute(
|
||||
s: PShellSessionInternal,
|
||||
command: string,
|
||||
execFn: ExecFn,
|
||||
opts: SendCommandOpts,
|
||||
): Promise<PShellSendResult> {
|
||||
const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
|
||||
s.busy = true;
|
||||
s.lastCommand = command;
|
||||
|
||||
const sentinelCmd = buildSentinelCommand(command);
|
||||
let raw: ExecResult;
|
||||
try {
|
||||
raw = await execFn(sentinelCmd, [], { timeout: timeoutMs, cwd: s.cwd });
|
||||
} catch (err) {
|
||||
// execFn 抛错(超时/进程崩)→ fail-closed,但解锁会话不锁死
|
||||
s.busy = false;
|
||||
s.lastActivityAt = Date.now();
|
||||
void this.drain(s.id, execFn).catch(() => {});
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
return {
|
||||
ok: false,
|
||||
sessionId: s.id,
|
||||
stdout: "",
|
||||
stderr: msg,
|
||||
exitCode: -1,
|
||||
error: msg.includes("timeout") || msg.toLowerCase().includes("timed out") ? "timeout" : "exec-failed",
|
||||
};
|
||||
}
|
||||
|
||||
s.busy = false;
|
||||
s.lastActivityAt = Date.now();
|
||||
|
||||
const parsed = parseSentinelOutput(raw.stdout);
|
||||
if (!parsed.found) {
|
||||
// 哨兵缺失:输出不可信,fail-closed
|
||||
void this.drain(s.id, execFn).catch(() => {});
|
||||
return {
|
||||
ok: false,
|
||||
sessionId: s.id,
|
||||
stdout: raw.stdout,
|
||||
stderr: raw.stderr,
|
||||
exitCode: -1,
|
||||
error: "sentinel-missing",
|
||||
};
|
||||
}
|
||||
|
||||
// 异步 drain 队列(queue 策略);reject 策略下 pending 恒空。
|
||||
void this.drain(s.id, execFn).catch(() => {});
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
sessionId: s.id,
|
||||
stdout: parsed.stdout,
|
||||
stderr: raw.stderr,
|
||||
exitCode: parsed.exitCode ?? 0,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 排空队列:依次执行排队的命令。队列命令的输出不回传原调用方(已返回 queued:true),
|
||||
* 仅落 session lastCommand 供审计。出错即停(fail-closed)。
|
||||
*/
|
||||
private async drain(id: string, execFn: ExecFn): Promise<void> {
|
||||
const s = this.sessions.get(id);
|
||||
if (!s || s.busy) return;
|
||||
while (s.pending.length > 0) {
|
||||
if (s.busy) break;
|
||||
const job = s.pending.shift();
|
||||
if (!job) break;
|
||||
// drain 内的执行结果不外抛;记录到 lastCommand
|
||||
await this.execute(s, job.command, execFn, { timeoutMs: job.timeoutMs });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
// 会话池单例(同进程跨 tool call 共享,正是"持久"的载体)
|
||||
const pool = new PShellPool({ busyPolicy: "reject", defaultTimeoutMs: 30_000 });
|
||||
|
||||
/**
|
||||
* 把 pi.exec 适配成逻辑层 ExecFn 签名。
|
||||
* 注:pi.exec 一次性子进程不保状态,仅作 seam;真正的状态化 PTY 是后续板链路/
|
||||
* 调试器扩展共建的载体,但会话池元数据与命令编排逻辑已在此完整实现并可单测。
|
||||
*
|
||||
* @param pi 扩展 API。
|
||||
* @returns 适配后的 ExecFn。
|
||||
*/
|
||||
function makePiExecFn(pi: ExtensionAPI): ExecFnLike {
|
||||
return async (command: string, _args: string[], opts?: { cwd?: string; timeout?: number }) => {
|
||||
return pi.exec(command, [], { cwd: opts?.cwd, timeout: opts?.timeout });
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 持久 Shell 扩展装配。
|
||||
*
|
||||
* - 注册 `pshell` 工具:session_id/action/command/timeout 四参 schema,默认
|
||||
* executionMode:"sequential"(治共享硬件并发撞车)。
|
||||
* - session_start:重置会话池(防上一轮残留的孤儿 openocd 占 JTAG)+ 落审计。
|
||||
* - before_agent_start:兜底 sweep idle(>10min 无活动回收)。
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*
|
||||
* @param pi 扩展 API。
|
||||
*/
|
||||
export default async function persistentShellExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
const pshellSchema = Type.Object({
|
||||
session_id: Type.Optional(Type.String({ description: "会话标识;不传则新建并返回新 id" })),
|
||||
command: Type.Optional(Type.String({ description: "发往会话的命令;action=open/close/list 时可省" })),
|
||||
action: Type.Optional(
|
||||
Type.Union(
|
||||
[Type.Literal("open"), Type.Literal("close"), Type.Literal("send"), Type.Literal("list")],
|
||||
{ description: "默认 send(带 session_id + command)。open=新建会话,close=结束,list=列出全部会话" },
|
||||
),
|
||||
),
|
||||
timeout: Type.Optional(Type.Number({ description: "单条命令超时秒(仅 send)" })),
|
||||
});
|
||||
|
||||
function textResult(obj: unknown) {
|
||||
return {
|
||||
content: [{ type: "text" as const, text: JSON.stringify(obj, null, 2) }],
|
||||
details: obj,
|
||||
};
|
||||
}
|
||||
|
||||
const execFn = makePiExecFn(pi);
|
||||
|
||||
const pshellTool = defineTool({
|
||||
name: "pshell",
|
||||
label: "Persistent Shell",
|
||||
description:
|
||||
"Persistent interactive shell session pool for gdb/openocd/minicom/picocom — commands " +
|
||||
"that need state preserved across multiple tool calls (breakpoints, JTAG target, serial " +
|
||||
"connection). One-shot commands should still use `bash`. Default executionMode=sequential " +
|
||||
"to avoid shared-hardware contention. Returns {session_id, stdout, stderr, exitCode}.",
|
||||
promptSnippet: "Run gdb/openocd/minicom in a persistent session (state preserved across calls)",
|
||||
parameters: pshellSchema,
|
||||
executionMode: "sequential",
|
||||
async execute(_toolCallId, params, _signal, _onUpdate, _ctx: ExtensionContext) {
|
||||
const p = params as {
|
||||
session_id?: string;
|
||||
command?: string;
|
||||
action?: "open" | "close" | "send" | "list";
|
||||
timeout?: number;
|
||||
};
|
||||
const action = p.action ?? "send";
|
||||
|
||||
// list:无副作用
|
||||
if (action === "list") {
|
||||
return textResult({ sessions: pool.list() });
|
||||
}
|
||||
|
||||
// open:新建会话
|
||||
if (action === "open") {
|
||||
const id = pool.open({ id: p.session_id });
|
||||
return textResult({ session_id: id, opened: true });
|
||||
}
|
||||
|
||||
// close:结束会话
|
||||
if (action === "close") {
|
||||
const sid = p.session_id;
|
||||
if (!sid) return textResult({ ok: false, error: "close requires session_id" });
|
||||
const closed = pool.close(sid);
|
||||
return textResult({ session_id: sid, closed });
|
||||
}
|
||||
|
||||
// send(默认)
|
||||
if (action === "send") {
|
||||
const sid = p.session_id;
|
||||
const command = p.command;
|
||||
const timeoutMs = p.timeout ? p.timeout * 1000 : undefined;
|
||||
if (!sid) {
|
||||
// 无 session_id 默认 open 新会话并发一次命令
|
||||
const newId = pool.open();
|
||||
const r = await pool.send(newId, command ?? "", execFn, { timeoutMs });
|
||||
return textResult(r satisfies PShellSendResult);
|
||||
}
|
||||
if (!command) return textResult({ ok: false, sessionId: sid, error: "send requires command" });
|
||||
|
||||
const r = await pool.send(sid, command, execFn, { timeoutMs });
|
||||
return textResult(r satisfies PShellSendResult);
|
||||
}
|
||||
|
||||
return textResult({ ok: false, error: `unknown action: ${action}` });
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(pshellTool);
|
||||
|
||||
// session_start:重置会话池(防上一轮残留的孤儿 openocd 占 JTAG)+ 落审计
|
||||
pi.on("session_start", (_event, ctx: ExtensionContext) => {
|
||||
const closed = pool.closeAll();
|
||||
if (closed.length > 0) {
|
||||
ctx.ui.notify(`[persistent-shell] closed ${closed.length} stale pshell session(s) on session start`, "info");
|
||||
pi.appendEntry("pshell:cleanup-stale", { closed });
|
||||
}
|
||||
pi.appendEntry("pshell:pool-ready", { sentinel: PSHELL_SENTINEL });
|
||||
});
|
||||
|
||||
// 兜底:before_agent_start 顺带 sweep idle(>10min 无活动回收)
|
||||
pi.on("before_agent_start", () => {
|
||||
const closed = pool.sweepIdle();
|
||||
if (closed.length > 0) {
|
||||
pi.appendEntry("pshell:idle-sweep", { closed });
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
}
|
||||
262
src/extensions/safety-gate.ts
Normal file
262
src/extensions/safety-gate.ts
Normal file
@ -0,0 +1,262 @@
|
||||
/**
|
||||
* @module safety-gate
|
||||
*
|
||||
* 硬件安全门扩展 —— 治嵌入式开发场景三条缺陷:
|
||||
* #3 破坏性命令裸跑、#11 无资源锁、#19 per-skill 工具未收敛。
|
||||
*
|
||||
* 三合一:
|
||||
* ① tool_call 钩子拦截破坏性 bash 命令(fail-closed,参照 pi 自带 permission-gate.ts)
|
||||
* ② 设备资源锁(i2c/gpio 等外设并发保护)
|
||||
* ③ per-skill allowed-tools 收敛(session_start 按 skill 限定工具集)
|
||||
*
|
||||
* 见 Docs/F05_硬件安全门破坏性命令拦截与资源锁.md。逻辑内联为命名导出,tests 直接单测。
|
||||
*/
|
||||
|
||||
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
||||
import type { SafetyDecision } from "../shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// ① 破坏性命令检测
|
||||
// ============================================================================
|
||||
|
||||
export interface SafetyRule {
|
||||
name: string;
|
||||
pattern: RegExp;
|
||||
reason: string;
|
||||
safeAlternative?: string;
|
||||
requiresDryRun?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* 嵌入式场景破坏性命令规则集。fail-closed:命中即 block。
|
||||
* 这些命令写错会砖板:dd 写错盘、fastboot flash 错分区、mkfs 格式化根盘、
|
||||
* devmem 写错寄存器、openocd 直接 program 不验证、rm -rf /dev。
|
||||
*/
|
||||
export const DESTRUCTIVE_RULES: SafetyRule[] = [
|
||||
{
|
||||
name: "dd-to-block-device",
|
||||
pattern: /\bdd\b[^|]*\bof\s*=\s*\/dev\/(sd|mmcblk|nvme|nand|mtd|disk)/i,
|
||||
reason: "dd writing directly to a block device can brick the board. Use the `flash` tool which enforces dry-run + sha256 verify.",
|
||||
safeAlternative: "flash tool with dry_run:true",
|
||||
requiresDryRun: true,
|
||||
},
|
||||
{
|
||||
name: "fastboot-flash",
|
||||
pattern: /\bfastboot\b[^|]*\bflash\b/i,
|
||||
reason: "raw `fastboot flash` can write the wrong partition. Use the `flash` tool which confirms target before write.",
|
||||
safeAlternative: "flash tool",
|
||||
requiresDryRun: true,
|
||||
},
|
||||
{
|
||||
name: "mkfs-on-device",
|
||||
pattern: /\bmkfs\.[a-z0-9]+\s+\/dev\//i,
|
||||
reason: "mkfs on a raw device destroys the partition table — brick risk.",
|
||||
requiresDryRun: true,
|
||||
},
|
||||
{
|
||||
name: "devmem-write",
|
||||
pattern: /\bdevmem2?\s+0x[0-9a-fA-F]+\s+\b(w|write)\b/i,
|
||||
reason: "raw devmem write to an MMIO register can brick the SoC. Verify the address against the datasheet.",
|
||||
safeAlternative: "reg tool with datasheet-verified address",
|
||||
},
|
||||
{
|
||||
name: "openocd-program-no-verify",
|
||||
pattern: /\bopenocd\b[^|]*\bprogram\b/i,
|
||||
reason: "openocd program flashes without the 3-step gate. Use `flash` tool (method:openocd) which requires dry-run first.",
|
||||
safeAlternative: "flash tool (method:openocd)",
|
||||
requiresDryRun: true,
|
||||
},
|
||||
{
|
||||
name: "rm-dev",
|
||||
pattern: /\brm\s+(-[rRfF]+\s+)?\/dev\//i,
|
||||
reason: "rm under /dev removes device nodes — can disable peripherals irreversibly until reboot.",
|
||||
},
|
||||
{
|
||||
name: "chmod-777-dev",
|
||||
pattern: /\bchmod\s+[-+]?777\b.*\/dev\//i,
|
||||
reason: "chmod 777 on device nodes is a security/functional hazard.",
|
||||
},
|
||||
{
|
||||
name: "rm-rf-root",
|
||||
pattern: /\brm\s+(-[rRfF]+\s+)+\/(\s|$)/,
|
||||
reason: "rm -rf / — absolute destruction.",
|
||||
},
|
||||
];
|
||||
|
||||
export interface EvaluateOpts {
|
||||
/** 允许的破坏性命令白名单(按 rule name),用于 flash 工具内部调用豁免。 */
|
||||
allowRules?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* 评估一条 bash 命令是否安全。fail-closed:命中规则即 block。
|
||||
*
|
||||
* @param command bash 命令字符串。
|
||||
* @param opts.allowRules 豁免的 rule 名(如 flash 工具内部 dd 豁免 dd-to-block-device)。
|
||||
* @returns SafetyDecision。
|
||||
*/
|
||||
export function evaluateSafety(command: string, opts: EvaluateOpts = {}): SafetyDecision {
|
||||
if (!command || command.trim() === "") {
|
||||
return { block: false };
|
||||
}
|
||||
const allow = new Set(opts.allowRules ?? []);
|
||||
for (const rule of DESTRUCTIVE_RULES) {
|
||||
if (allow.has(rule.name)) continue;
|
||||
if (rule.pattern.test(command)) {
|
||||
return { block: true, reason: rule.reason, rule: rule.name, safeAlternative: rule.safeAlternative };
|
||||
}
|
||||
}
|
||||
return { block: false };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ② 设备资源锁
|
||||
// ============================================================================
|
||||
|
||||
/** 资源锁表:deviceId → 持有者(tool call id 或 session)。 */
|
||||
export class ResourceLock {
|
||||
private locks = new Map<string, string>();
|
||||
|
||||
/** 尝试获取锁。成功 true;已被其他持有者占用 false(重入同 owner 允许)。 */
|
||||
acquire(deviceId: string, owner: string): boolean {
|
||||
const current = this.locks.get(deviceId);
|
||||
if (current === undefined) {
|
||||
this.locks.set(deviceId, owner);
|
||||
return true;
|
||||
}
|
||||
return current === owner;
|
||||
}
|
||||
|
||||
release(deviceId: string, owner: string): boolean {
|
||||
const current = this.locks.get(deviceId);
|
||||
if (current === owner) {
|
||||
this.locks.delete(deviceId);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
isLocked(deviceId: string): boolean {
|
||||
return this.locks.has(deviceId);
|
||||
}
|
||||
|
||||
/** 释放某 owner 持有的所有锁(session 结束/abort 时清理)。 */
|
||||
releaseAll(owner: string): string[] {
|
||||
const released: string[] = [];
|
||||
for (const [dev, o] of this.locks) {
|
||||
if (o === owner) {
|
||||
this.locks.delete(dev);
|
||||
released.push(dev);
|
||||
}
|
||||
}
|
||||
return released;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 从命令中提取被访问的物理设备 id(用于上锁)。
|
||||
* 例:i2cdump -y 0 0x76 → "i2c-bus-0";gpioget gpiochip0 33 → "gpiochip0"。
|
||||
*/
|
||||
export function extractDeviceId(command: string): string | null {
|
||||
let m = command.match(/\bi2c(?:get|set|dump|detect)?\b\s+(?:-y\s+)?(\d+)/i);
|
||||
if (m) return `i2c-bus-${m[1]}`;
|
||||
m = command.match(/\bgpioget\s+(\S+)/i) ?? command.match(/\bgpioset\s+(\S+)/i);
|
||||
if (m) return m[1];
|
||||
m = command.match(/\/dev\/(i2c-(\d+)|spidev(\d+)\.(\d+)|ttyUSB(\d+)|ttyACM(\d+))/i);
|
||||
if (m) return m[0];
|
||||
m = command.match(/\bi2cdump\s+(?:-y\s+)?(\d+)/i);
|
||||
if (m) return `i2c-bus-${m[1]}`;
|
||||
return null;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// ③ per-skill allowed-tools
|
||||
// ============================================================================
|
||||
|
||||
/** skill → 允许的工具白名单。未列出的 skill 不收敛(用默认全集)。 */
|
||||
export const SKILL_ALLOWED_TOOLS: Record<string, string[]> = {
|
||||
"hw-flash": ["read", "bash", "flash", "verify", "loop_status"],
|
||||
"hw-debug": ["read", "bash", "debugger", "board_exec", "verify"],
|
||||
"hw-probe": ["read", "bash", "probe", "board_exec"],
|
||||
"hw-loop": ["read", "edit", "write", "bash", "build", "flash", "verify", "loop_status", "board_exec"],
|
||||
};
|
||||
|
||||
/**
|
||||
* 给定 skill 名,返回该 skill 下允许的工具集。未配置返回 null(不收敛)。
|
||||
*/
|
||||
export function allowedToolsForSkill(skillName: string): string[] | null {
|
||||
const key = skillName.toLowerCase();
|
||||
return SKILL_ALLOWED_TOOLS[key] ?? null;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配
|
||||
// ============================================================================
|
||||
|
||||
// 单例资源锁(同进程跨 tool call 共享)
|
||||
const lock = new ResourceLock();
|
||||
|
||||
/**
|
||||
* safety-gate 扩展装配。
|
||||
*
|
||||
* - tool_call:破坏性命令拦截 + 资源锁获取
|
||||
* - tool_result:释放资源锁
|
||||
* - session_start:per-skill 工具收敛(读 PI_ACTIVE_SKILL 环境变量)
|
||||
*/
|
||||
export default function safetyGateExtension(pi: ExtensionAPI): void {
|
||||
pi.on("tool_call", async (event, ctx: ExtensionContext) => {
|
||||
if (event.toolName !== "bash") return undefined;
|
||||
const command = (event.input as { command?: string }).command ?? "";
|
||||
const decision = evaluateSafety(command);
|
||||
|
||||
if (decision.block) {
|
||||
if (ctx.hasUI) {
|
||||
const message =
|
||||
`${command}\n\n原因:${decision.reason}\n` +
|
||||
(decision.safeAlternative ? `建议改用:${decision.safeAlternative}\n` : "") +
|
||||
"仍要放行?(不推荐)";
|
||||
const allow = await ctx.ui.confirm(`破坏性命令拦截 [${decision.rule}]`, message);
|
||||
if (allow) {
|
||||
pi.appendEntry("safegate:override", { rule: decision.rule, command });
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
return {
|
||||
block: true,
|
||||
reason: `[safety-gate] ${decision.reason}${decision.safeAlternative ? ` → 改用 ${decision.safeAlternative}` : ""}`,
|
||||
};
|
||||
}
|
||||
|
||||
const deviceId = extractDeviceId(command);
|
||||
if (deviceId) {
|
||||
if (!lock.acquire(deviceId, event.toolCallId)) {
|
||||
return {
|
||||
block: true,
|
||||
reason: `[safety-gate] device ${deviceId} is busy (another tool call holds the lock). Retry after it completes.`,
|
||||
};
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
pi.on("tool_result", (event) => {
|
||||
if (event.toolName !== "bash") return undefined;
|
||||
const command = (event.input as { command?: string }).command ?? "";
|
||||
const deviceId = extractDeviceId(command);
|
||||
if (deviceId) {
|
||||
lock.release(deviceId, event.toolCallId);
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
pi.on("session_start", async (_event, ctx: ExtensionContext) => {
|
||||
const skill = process.env.PI_ACTIVE_SKILL;
|
||||
if (!skill) return;
|
||||
const allowed = allowedToolsForSkill(skill);
|
||||
if (allowed) {
|
||||
pi.setActiveTools(allowed);
|
||||
ctx.ui.notify(`[safety-gate] skill "${skill}" → tools locked to: ${allowed.join(", ")}`, "info");
|
||||
pi.appendEntry("safegate:skill-locked", { skill, allowed });
|
||||
}
|
||||
});
|
||||
}
|
||||
701
src/extensions/server-runtime.ts
Normal file
701
src/extensions/server-runtime.ts
Normal file
@ -0,0 +1,701 @@
|
||||
/**
|
||||
* @module server-runtime
|
||||
*
|
||||
* 多会话运行时服务扩展 —— 治嵌入式开发场景两条缺陷:
|
||||
* #6(pi 无法多会话服务化,AgentHarness 操作方法全 unavailable)
|
||||
* #20(pi-server 无生产实现 + locked 恒 true + 协议层无认证)。
|
||||
*
|
||||
* 场景锚定:eval 平台批量跑 HWE-Bench 嵌入式题——每题一个 session,
|
||||
* RPC 驱动 prompt/abort/get_state。当前 AgentHarness 全抛 HarnessNotImplemented、
|
||||
* pi-server 无生产 PiServerService,只能走 RPC 子进程模式(每题 spawn 一个 Node 进程,
|
||||
* 资源开销大、无多会话管理)。本扩展提供进程内多会话运行时骨架,让 agent 能驱动
|
||||
* 多会话:start/send/abort/status/list/fork/resume/shutdown。
|
||||
*
|
||||
* 三治点:
|
||||
* ① 纯逻辑骨架 AgentSessionRuntime 8 方法(startSession/sendMessage/getStatus/
|
||||
* listSessions/abort/fork/resume/shutdown)+ 状态机 idle↔streaming + locked 互斥
|
||||
* (locked = phase !== "idle",真实化,治 #20 的 locked:true 恒真)。
|
||||
* ② token 鉴权 checkToken(fail-closed:required=true 时缺/坏 token → AuthError)。
|
||||
* ③ server_session 工具暴露多会话驱动给 agent,扩展层把 AgentTurnFn 接到真实 AgentSession。
|
||||
*
|
||||
* 真实 AgentSession/agentLoop/LLM 由注入的 AgentTurnFn 模拟,纯逻辑绝不依赖真实硬件/LLM。
|
||||
* 扩展工厂把 AgentTurnFn 接到真实 AgentSession.prompt/steer。
|
||||
*
|
||||
* 见 Docs/F09_PiServerService生产实现.md。逻辑内联为命名导出,tests 直接单测,无需 pi 运行时。
|
||||
*
|
||||
* 密钥铁律:token 用 ${DROBOTICS_LLM_KEY} 占位,绝不硬编码 sk- 开头真 key。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
|
||||
// 注:defineTool / Type 仅在工厂内动态 import(运行时解析到真 pi),
|
||||
// 顶层只保留 `import type`(esbuild 擦除),故 tests 直接 import 本模块的纯逻辑
|
||||
// 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时工厂不跑,无副作用。
|
||||
|
||||
// ============================================================================
|
||||
// 类型
|
||||
// ============================================================================
|
||||
|
||||
/** 会话阶段。streaming = 正在跑一轮 agent turn。locked = phase !== "idle"。 */
|
||||
export type SessionPhase = "idle" | "streaming";
|
||||
|
||||
export type ThinkingLevel = "off" | "low" | "medium" | "high";
|
||||
|
||||
/** 用户消息输入。 */
|
||||
export interface SendMessageInput {
|
||||
text: string;
|
||||
/** 图片(base64 或路径,透传给扩展层)。 */
|
||||
images?: string[];
|
||||
}
|
||||
|
||||
/** transcript 里的一条消息。 */
|
||||
export interface MessageEntry {
|
||||
role: "user" | "assistant" | "system";
|
||||
content: string;
|
||||
timestamp: number;
|
||||
}
|
||||
|
||||
/** 会话快照(对应 PiSessionRuntime.snapshot / SessionSnapshot)。 */
|
||||
export interface SessionSnapshot {
|
||||
id: string;
|
||||
phase: SessionPhase;
|
||||
/** locked = phase !== "idle",真实化(治 sessions.ts:286 locked:true 恒真)。 */
|
||||
locked: boolean;
|
||||
model: string;
|
||||
thinkingLevel: ThinkingLevel;
|
||||
cwd: string;
|
||||
transcript: MessageEntry[];
|
||||
createdAt: number;
|
||||
/** fork 来源会话 id(若有)。 */
|
||||
forkedFrom?: string;
|
||||
/** 是否已被 shutdown 置为 disposed。 */
|
||||
disposed: boolean;
|
||||
}
|
||||
|
||||
/** 创建会话选项。 */
|
||||
export interface StartSessionOptions {
|
||||
cwd?: string;
|
||||
model?: string;
|
||||
thinkingLevel?: ThinkingLevel;
|
||||
/** 鉴权 token;required=true 时必填且须匹配。 */
|
||||
authToken?: string;
|
||||
/** 若为 fork,源会话的 transcript 拷贝起点。 */
|
||||
forkFrom?: string;
|
||||
}
|
||||
|
||||
/** sendMessage 的选项。 */
|
||||
export interface SendMessageOptions {
|
||||
authToken?: string;
|
||||
}
|
||||
|
||||
/** sendMessage 返回。 */
|
||||
export interface SendMessageResult {
|
||||
text: string;
|
||||
stopReason?: string;
|
||||
/** 是否被 abort 中断。 */
|
||||
aborted: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* 注入的 agent turn 执行函数(模拟真实 AgentSession.prompt + agentLoop)。
|
||||
*
|
||||
* 逻辑层只认此签名;测试用 mock,扩展层接真实 AgentSession。
|
||||
* onToken: 流式 token 回调(模拟 streaming)。
|
||||
* signal: { aborted: boolean },逻辑层 abort() 置 true,turnFn 应轮询。
|
||||
*/
|
||||
export type AgentTurnFn = (
|
||||
sessionId: string,
|
||||
input: SendMessageInput,
|
||||
onToken: (chunk: string) => void,
|
||||
signal: { aborted: boolean },
|
||||
) => Promise<{ text: string; stopReason?: string }>;
|
||||
|
||||
/** 鉴权配置。 */
|
||||
export interface AuthConfig {
|
||||
/** 是否强制鉴权。false = 放行所有(开发模式)。 */
|
||||
required: boolean;
|
||||
/**
|
||||
* 期望 token。生产用环境占位 ${DROBOTICS_LLM_KEY},绝不硬编码 sk- 开头真 key。
|
||||
* required=false 时忽略。
|
||||
*/
|
||||
expectedToken?: string;
|
||||
}
|
||||
|
||||
export interface AgentSessionRuntimeOptions {
|
||||
/** 注入的 turn 执行函数(必填)。 */
|
||||
turnFn: AgentTurnFn;
|
||||
/** 鉴权配置,默认 required:false。 */
|
||||
auth?: AuthConfig;
|
||||
/** 默认模型 id。 */
|
||||
defaultModel?: string;
|
||||
/** 默认 cwd。 */
|
||||
defaultCwd?: string;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 错误(fail-closed 语义)
|
||||
// ============================================================================
|
||||
|
||||
/** 鉴权失败。required=true 时缺/坏 token 抛出(fail-closed)。 */
|
||||
export class AuthError extends Error {
|
||||
constructor(message = "[server-runtime] auth_error: invalid or missing token") {
|
||||
super(message);
|
||||
this.name = "AuthError";
|
||||
}
|
||||
}
|
||||
|
||||
/** 会话被锁(streaming 中),不可再发起一轮 turn(互斥,fail-closed)。 */
|
||||
export class SessionLockedError extends Error {
|
||||
constructor(sessionId: string) {
|
||||
super(`[server-runtime] session ${sessionId} is locked (phase !== idle); cannot start a new turn`);
|
||||
this.name = "SessionLockedError";
|
||||
}
|
||||
}
|
||||
|
||||
/** 会话不存在。 */
|
||||
export class SessionNotFoundError extends Error {
|
||||
constructor(sessionId: string) {
|
||||
super(`[server-runtime] session not found: ${sessionId}`);
|
||||
this.name = "SessionNotFoundError";
|
||||
}
|
||||
}
|
||||
|
||||
/** 会话已被 shutdown 置为 disposed,须 resume() 后再用。 */
|
||||
export class SessionDisposedError extends Error {
|
||||
constructor(sessionId: string) {
|
||||
super(`[server-runtime] session ${sessionId} is disposed; resume() first`);
|
||||
this.name = "SessionDisposedError";
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 内部会话状态
|
||||
// ============================================================================
|
||||
|
||||
interface SessionState {
|
||||
id: string;
|
||||
phase: SessionPhase;
|
||||
model: string;
|
||||
thinkingLevel: ThinkingLevel;
|
||||
cwd: string;
|
||||
transcript: MessageEntry[];
|
||||
createdAt: number;
|
||||
forkedFrom?: string;
|
||||
disposed: boolean;
|
||||
/** 本轮 abort 信号(每轮 sendMessage 重置)。 */
|
||||
abortSignal: { aborted: boolean };
|
||||
}
|
||||
|
||||
/**
|
||||
* 把内部 SessionState 转成对外 SessionSnapshot(深拷贝 transcript,防外部篡改)。
|
||||
*
|
||||
* @param s 内部会话状态。
|
||||
* @returns 会话快照,locked 真实化(phase !== "idle")。
|
||||
*/
|
||||
function toSnapshot(s: SessionState): SessionSnapshot {
|
||||
return {
|
||||
id: s.id,
|
||||
phase: s.phase,
|
||||
// locked 真实化:phase !== "idle"。治 #20 的 locked:true 恒真。
|
||||
locked: s.phase !== "idle",
|
||||
model: s.model,
|
||||
thinkingLevel: s.thinkingLevel,
|
||||
cwd: s.cwd,
|
||||
transcript: s.transcript.slice(),
|
||||
createdAt: s.createdAt,
|
||||
forkedFrom: s.forkedFrom,
|
||||
disposed: s.disposed,
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// AgentSessionRuntime —— 8 方法纯逻辑骨架
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 多会话运行时的生产实现骨架。
|
||||
*
|
||||
* 状态机:每个会话独立 idle ↔ streaming。
|
||||
* - sendMessage:idle → streaming(跑 turnFn)→ idle。
|
||||
* - locked = phase !== "idle":locked 时同会话再 sendMessage → 拒绝(互斥,fail-closed)。
|
||||
* - abort:streaming → idle(中断 turnFn)。
|
||||
*
|
||||
* 鉴权:checkToken(required=true 时 token 必须匹配 expectedToken)。
|
||||
* key 用 ${DROBOTICS_LLM_KEY} 占位,绝不硬编码。
|
||||
*
|
||||
* 真实 AgentSession/agentLoop/LLM 由注入的 AgentTurnFn 模拟,纯逻辑绝不依赖真实硬件/LLM。
|
||||
*/
|
||||
export class AgentSessionRuntime {
|
||||
private sessions = new Map<string, SessionState>();
|
||||
private readonly turnFn: AgentTurnFn;
|
||||
private readonly auth: AuthConfig;
|
||||
private readonly defaultModel: string;
|
||||
private readonly defaultCwd: string;
|
||||
private seq = 0;
|
||||
|
||||
/**
|
||||
* @param opts.turnFn 注入的 turn 执行函数(必填)。
|
||||
* @param opts.auth 鉴权配置,默认 required:false。
|
||||
* @param opts.defaultModel 默认模型 id,默认 "glm-5.2"。
|
||||
* @param opts.defaultCwd 默认 cwd,默认 process.cwd()。
|
||||
*/
|
||||
constructor(opts: AgentSessionRuntimeOptions) {
|
||||
this.turnFn = opts.turnFn;
|
||||
this.auth = opts.auth ?? { required: false };
|
||||
this.defaultModel = opts.defaultModel ?? "glm-5.2";
|
||||
this.defaultCwd = opts.defaultCwd ?? process.cwd();
|
||||
}
|
||||
|
||||
// ---- 鉴权 ----
|
||||
|
||||
/**
|
||||
* 校验 token。required=false 时恒放行。
|
||||
* expectedToken 用 ${DROBOTICS_LLM_KEY} 占位,运行时由扩展层从 env 解析。
|
||||
*
|
||||
* @param token 待校验 token。
|
||||
* @returns 是否通过。
|
||||
*/
|
||||
checkToken(token?: string): boolean {
|
||||
if (!this.auth.required) return true;
|
||||
if (!token) return false;
|
||||
if (this.auth.expectedToken === undefined) return false;
|
||||
return token === this.auth.expectedToken;
|
||||
}
|
||||
|
||||
// ---- 1. startSession ----
|
||||
|
||||
/**
|
||||
* 创建新会话。返回 session id。
|
||||
* 鉴权失败 → AuthError(fail-closed)。
|
||||
* forkFrom 指定时,从源会话拷贝 transcript(fork 语义)。
|
||||
*
|
||||
* @param options 创建选项(cwd/model/thinkingLevel/authToken/forkFrom)。
|
||||
* @returns 新会话 id。
|
||||
*/
|
||||
async startSession(options: StartSessionOptions = {}): Promise<string> {
|
||||
if (!this.checkToken(options.authToken)) {
|
||||
throw new AuthError();
|
||||
}
|
||||
const id = `sess-${Date.now()}-${++this.seq}`;
|
||||
const transcript: MessageEntry[] = [];
|
||||
if (options.forkFrom) {
|
||||
const parent = this.sessions.get(options.forkFrom);
|
||||
if (!parent) throw new SessionNotFoundError(options.forkFrom);
|
||||
for (const m of parent.transcript) {
|
||||
transcript.push({ ...m });
|
||||
}
|
||||
}
|
||||
const state: SessionState = {
|
||||
id,
|
||||
phase: "idle",
|
||||
model: options.model ?? this.defaultModel,
|
||||
thinkingLevel: options.thinkingLevel ?? "off",
|
||||
cwd: options.cwd ?? this.defaultCwd,
|
||||
transcript,
|
||||
createdAt: Date.now(),
|
||||
forkedFrom: options.forkFrom,
|
||||
disposed: false,
|
||||
abortSignal: { aborted: false },
|
||||
};
|
||||
this.sessions.set(id, state);
|
||||
return id;
|
||||
}
|
||||
|
||||
/**
|
||||
* 取会话,不存在抛 SessionNotFoundError。
|
||||
* @param sessionId 会话 id。
|
||||
* @returns 内部会话状态。
|
||||
*/
|
||||
private require(sessionId: string): SessionState {
|
||||
const s = this.sessions.get(sessionId);
|
||||
if (!s) throw new SessionNotFoundError(sessionId);
|
||||
return s;
|
||||
}
|
||||
|
||||
// ---- 2. sendMessage ----
|
||||
|
||||
/**
|
||||
* 发送消息并跑一轮 agent turn。idle → streaming → idle。
|
||||
* - 鉴权失败 → AuthError
|
||||
* - 会话不存在 → SessionNotFoundError
|
||||
* - 会话 disposed → SessionDisposedError
|
||||
* - 会话 locked(streaming)→ SessionLockedError(互斥,fail-closed)
|
||||
* - abort:turnFn 轮询 signal.aborted,中断后 phase 回 idle,aborted=true
|
||||
*
|
||||
* @param sessionId 目标会话 id。
|
||||
* @param input 用户消息输入。
|
||||
* @param opts 鉴权选项。
|
||||
* @returns turn 结果(text/stopReason/aborted)。
|
||||
*/
|
||||
async sendMessage(
|
||||
sessionId: string,
|
||||
input: SendMessageInput,
|
||||
opts: SendMessageOptions = {},
|
||||
): Promise<SendMessageResult> {
|
||||
if (!this.checkToken(opts.authToken)) {
|
||||
throw new AuthError();
|
||||
}
|
||||
const s = this.require(sessionId);
|
||||
if (s.disposed) throw new SessionDisposedError(sessionId);
|
||||
if (s.phase !== "idle") {
|
||||
throw new SessionLockedError(sessionId);
|
||||
}
|
||||
|
||||
// idle → streaming
|
||||
s.phase = "streaming";
|
||||
s.abortSignal = { aborted: false };
|
||||
s.transcript.push({ role: "user", content: input.text, timestamp: Date.now() });
|
||||
|
||||
let resultText = "";
|
||||
let stopReason: string | undefined;
|
||||
let aborted = false;
|
||||
try {
|
||||
const res = await this.turnFn(sessionId, input, () => {}, s.abortSignal);
|
||||
resultText = res.text;
|
||||
stopReason = res.stopReason;
|
||||
} catch {
|
||||
// turnFn 抛错(含 abort)→ 视为中断,phase 回 idle
|
||||
aborted = true;
|
||||
resultText = "";
|
||||
}
|
||||
if (s.abortSignal.aborted) {
|
||||
aborted = true;
|
||||
}
|
||||
|
||||
// streaming → idle(无论成功/中断)
|
||||
s.phase = "idle";
|
||||
if (!aborted) {
|
||||
s.transcript.push({ role: "assistant", content: resultText, timestamp: Date.now() });
|
||||
}
|
||||
return { text: resultText, stopReason, aborted };
|
||||
}
|
||||
|
||||
// ---- 3. getStatus ----
|
||||
|
||||
/**
|
||||
* 返回会话快照。不存在返回 null。
|
||||
* locked 真实化:locked = phase !== "idle"。
|
||||
*
|
||||
* @param sessionId 会话 id。
|
||||
* @returns 会话快照或 null。
|
||||
*/
|
||||
getStatus(sessionId: string): SessionSnapshot | null {
|
||||
const s = this.sessions.get(sessionId);
|
||||
if (!s) return null;
|
||||
return toSnapshot(s);
|
||||
}
|
||||
|
||||
// ---- 4. listSessions ----
|
||||
|
||||
/**
|
||||
* 列出所有会话快照(含 disposed)。
|
||||
* @returns 会话快照数组。
|
||||
*/
|
||||
listSessions(): SessionSnapshot[] {
|
||||
return Array.from(this.sessions.values()).map(toSnapshot);
|
||||
}
|
||||
|
||||
// ---- 5. abort ----
|
||||
|
||||
/**
|
||||
* 中断正在 streaming 的会话。streaming → idle。
|
||||
* 返回 true 表示确实中断了一轮 streaming;false 表示会话不存在或本就 idle。
|
||||
*
|
||||
* @param sessionId 会话 id。
|
||||
* @returns 是否确实中断了 streaming。
|
||||
*/
|
||||
async abort(sessionId: string): Promise<boolean> {
|
||||
const s = this.sessions.get(sessionId);
|
||||
if (!s) return false;
|
||||
if (s.phase !== "streaming") return false;
|
||||
s.abortSignal.aborted = true;
|
||||
// phase 由 sendMessage 的 finally 逻辑回 idle;这里不直接改,避免双改。
|
||||
// 但为防止 turnFn 不轮询 signal 而挂起,也兜底置 idle。
|
||||
s.phase = "idle";
|
||||
return true;
|
||||
}
|
||||
|
||||
// ---- 6. fork ----
|
||||
|
||||
/**
|
||||
* 从源会话 fork 出新会话(拷贝 transcript + 模型配置)。
|
||||
* 新会话 phase=idle。返回新 session id。
|
||||
*
|
||||
* @param sessionId 源会话 id。
|
||||
* @param opts 覆盖选项(authToken/model/thinkingLevel/cwd)。
|
||||
* @returns 新会话 id。
|
||||
*/
|
||||
async fork(
|
||||
sessionId: string,
|
||||
opts: { authToken?: string; model?: string; thinkingLevel?: ThinkingLevel; cwd?: string } = {},
|
||||
): Promise<string> {
|
||||
if (!this.checkToken(opts.authToken)) {
|
||||
throw new AuthError();
|
||||
}
|
||||
const parent = this.require(sessionId);
|
||||
return this.startSession({
|
||||
cwd: opts.cwd ?? parent.cwd,
|
||||
model: opts.model ?? parent.model,
|
||||
thinkingLevel: opts.thinkingLevel ?? parent.thinkingLevel,
|
||||
authToken: opts.authToken,
|
||||
forkFrom: sessionId,
|
||||
});
|
||||
}
|
||||
|
||||
// ---- 7. resume ----
|
||||
|
||||
/**
|
||||
* 恢复一个 disposed 的会话(reactivate)。
|
||||
* 返回 true 表示成功恢复;false 表示会话不存在。
|
||||
* 已是 active 的会话调用 resume 也返回 true(幂等)。
|
||||
* 若卡在 streaming(异常退出),resume 强制回 idle。
|
||||
*
|
||||
* @param sessionId 会话 id。
|
||||
* @returns 是否成功恢复。
|
||||
*/
|
||||
resume(sessionId: string): boolean {
|
||||
const s = this.sessions.get(sessionId);
|
||||
if (!s) return false;
|
||||
s.disposed = false;
|
||||
// 若卡在 streaming(异常退出),resume 强制回 idle。
|
||||
if (s.phase !== "idle") {
|
||||
s.abortSignal.aborted = true;
|
||||
s.phase = "idle";
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
// ---- 8. shutdown ----
|
||||
|
||||
/**
|
||||
* 关闭服务:所有会话置 disposed + idle,清空 abort 信号。
|
||||
* 保留会话记录(可 resume 恢复);若要彻底清除用 clear()。
|
||||
*/
|
||||
async shutdown(): Promise<void> {
|
||||
for (const s of this.sessions.values()) {
|
||||
s.abortSignal.aborted = true;
|
||||
s.phase = "idle";
|
||||
s.disposed = true;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 彻底清除所有会话记录(测试/重置用)。
|
||||
*/
|
||||
clear(): void {
|
||||
this.sessions.clear();
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展工厂辅助(纯逻辑,可单测)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 从 env 读 token。${DROBOTICS_LLM_KEY} 占位规则:运行时读 process.env.DROBOTICS_LLM_KEY。
|
||||
* 绝不在代码里硬编码 sk- 开头真 key。
|
||||
* 未配 key 时鉴权关闭(开发模式);配了则 required=true(fail-closed)。
|
||||
*
|
||||
* @returns 鉴权配置。
|
||||
*/
|
||||
export function readAuthToken(): AuthConfig {
|
||||
const tok = process.env.DROBOTICS_LLM_KEY;
|
||||
if (!tok) {
|
||||
// 未配 key:鉴权关闭(开发模式);生产应 fail-closed。
|
||||
return { required: false };
|
||||
}
|
||||
return { required: true, expectedToken: tok };
|
||||
}
|
||||
|
||||
/**
|
||||
* 构造占位 AgentTurnFn:把 prompt 透传回显,让 agent 自答。
|
||||
* 生产实现应替换为真实 AgentSession.prompt 桥接(流式回调 onToken)。
|
||||
*
|
||||
* @returns 占位 turn 执行函数。
|
||||
*/
|
||||
export function makePlaceholderTurnFn(): AgentTurnFn {
|
||||
return async (_sessionId, input, _onToken, signal) => {
|
||||
// 占位:直接回显。生产实现接 AgentSession.prompt + agentLoop,流式回调 onToken。
|
||||
if (signal.aborted) {
|
||||
throw new Error("aborted");
|
||||
}
|
||||
return { text: `[server-runtime placeholder] received: ${input.text}`, stopReason: "stop" };
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* server-runtime 扩展装配。
|
||||
*
|
||||
* - 注册 server_session 工具,让 agent 能驱动多会话(start/send/abort/status/list/fork/resume/shutdown)
|
||||
* - 把纯逻辑 AgentSessionRuntime 接到真实 AgentSession(AgentTurnFn 实现)
|
||||
* - token 鉴权从 env DROBOTICS_LLM_KEY 取(${DROBOTICS_LLM_KEY} 占位,绝不硬编码)
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
* 加载方式:软链/拷到 ~/.pi/agent/extensions/ 或项目 .pi/extensions/。
|
||||
*
|
||||
* @param pi 扩展 API。
|
||||
*/
|
||||
export default async function serverRuntimeExtension(pi: ExtensionAPI): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
|
||||
const runtime = new AgentSessionRuntime({
|
||||
turnFn: makePlaceholderTurnFn(),
|
||||
auth: readAuthToken(),
|
||||
defaultModel: "glm-5.2",
|
||||
});
|
||||
|
||||
// ---- 工具:server_session(多会话驱动)----
|
||||
const sessionTool = defineTool({
|
||||
name: "server_session",
|
||||
label: "Server Session",
|
||||
description:
|
||||
"Drive multi-session agent service. Actions: start / send / status / list / abort / fork / resume / shutdown. " +
|
||||
"Each session has a phase state machine idle<->streaming; locked=phase!==idle (mutual exclusion). " +
|
||||
"Token auth via DROBOTICS_LLM_KEY env (fail-closed).",
|
||||
promptSnippet: "Manage agent sessions (start/send/abort/fork/list)",
|
||||
parameters: Type.Object(
|
||||
{
|
||||
action: Type.Union(
|
||||
[
|
||||
Type.Literal("start"),
|
||||
Type.Literal("send"),
|
||||
Type.Literal("status"),
|
||||
Type.Literal("list"),
|
||||
Type.Literal("abort"),
|
||||
Type.Literal("fork"),
|
||||
Type.Literal("resume"),
|
||||
Type.Literal("shutdown"),
|
||||
],
|
||||
{ description: "Action to perform." },
|
||||
),
|
||||
sessionId: Type.Optional(Type.String(), { description: "Target session id (for send/status/abort/fork/resume)." }),
|
||||
text: Type.Optional(Type.String(), { description: "Prompt text (for send)." }),
|
||||
model: Type.Optional(Type.String(), { description: "Model id (for start)." }),
|
||||
thinkingLevel: Type.Optional(Type.String(), { description: "off|low|medium|high (for start/fork)." }),
|
||||
},
|
||||
{ description: "Server session control parameters." },
|
||||
),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, signal, _onUpdate, ctx) {
|
||||
const p = params as {
|
||||
action: string;
|
||||
sessionId?: string;
|
||||
text?: string;
|
||||
model?: string;
|
||||
thinkingLevel?: string;
|
||||
};
|
||||
const authToken = process.env.DROBOTICS_LLM_KEY;
|
||||
|
||||
try {
|
||||
switch (p.action) {
|
||||
case "start": {
|
||||
const id = await runtime.startSession({
|
||||
cwd: ctx.cwd,
|
||||
model: p.model,
|
||||
thinkingLevel: p.thinkingLevel as ThinkingLevel | undefined,
|
||||
authToken,
|
||||
});
|
||||
pi.appendEntry("server-runtime:start", { id });
|
||||
return textResult(`session started: ${id}`);
|
||||
}
|
||||
case "send": {
|
||||
if (!p.sessionId || !p.text) return textResult("send requires sessionId + text", true);
|
||||
const res = await runtime.sendMessage(
|
||||
p.sessionId,
|
||||
{ text: p.text } satisfies SendMessageInput,
|
||||
{ authToken },
|
||||
);
|
||||
if (signal?.aborted) {
|
||||
await runtime.abort(p.sessionId);
|
||||
}
|
||||
pi.appendEntry("server-runtime:send", { sessionId: p.sessionId, aborted: res.aborted });
|
||||
return textResult(`[aborted=${res.aborted}] ${res.text}`);
|
||||
}
|
||||
case "status": {
|
||||
if (!p.sessionId) return textResult("status requires sessionId", true);
|
||||
const snap = runtime.getStatus(p.sessionId);
|
||||
if (!snap) return textResult(`session not found: ${p.sessionId}`, true);
|
||||
return textResult(JSON.stringify(snap, null, 2));
|
||||
}
|
||||
case "list": {
|
||||
const list = runtime.listSessions();
|
||||
return textResult(
|
||||
JSON.stringify(
|
||||
list.map((s) => ({ id: s.id, phase: s.phase, locked: s.locked, disposed: s.disposed })),
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
}
|
||||
case "abort": {
|
||||
if (!p.sessionId) return textResult("abort requires sessionId", true);
|
||||
const ok = await runtime.abort(p.sessionId);
|
||||
pi.appendEntry("server-runtime:abort", { sessionId: p.sessionId, ok });
|
||||
return textResult(`abort ${ok ? "ok" : "noop (idle/missing)"}: ${p.sessionId}`);
|
||||
}
|
||||
case "fork": {
|
||||
if (!p.sessionId) return textResult("fork requires sessionId", true);
|
||||
const id = await runtime.fork(p.sessionId, {
|
||||
authToken,
|
||||
model: p.model,
|
||||
thinkingLevel: p.thinkingLevel as ThinkingLevel | undefined,
|
||||
});
|
||||
pi.appendEntry("server-runtime:fork", { from: p.sessionId, id });
|
||||
return textResult(`forked: ${id} (from ${p.sessionId})`);
|
||||
}
|
||||
case "resume": {
|
||||
if (!p.sessionId) return textResult("resume requires sessionId", true);
|
||||
const ok = runtime.resume(p.sessionId);
|
||||
return textResult(`resume ${ok ? "ok" : "not found"}: ${p.sessionId}`);
|
||||
}
|
||||
case "shutdown": {
|
||||
await runtime.shutdown();
|
||||
pi.appendEntry("server-runtime:shutdown", {});
|
||||
return textResult("all sessions disposed");
|
||||
}
|
||||
default:
|
||||
return textResult(`unknown action: ${p.action}`, true);
|
||||
}
|
||||
} catch (e) {
|
||||
const msg = e instanceof Error ? e.message : String(e);
|
||||
return textResult(`[server-runtime error] ${msg}`, true);
|
||||
}
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(sessionTool);
|
||||
|
||||
pi.on("session_start", (_event, ctx: ExtensionContext) => {
|
||||
const authRequired = readAuthToken().required;
|
||||
pi.appendEntry("server-runtime:loaded", {
|
||||
authRequired,
|
||||
model: "glm-5.2",
|
||||
note: "multi-session runtime armed. token via ${DROBOTICS_LLM_KEY} env, never hardcoded.",
|
||||
});
|
||||
ctx.ui.notify(
|
||||
`[server-runtime] armed (auth=${authRequired ? "on" : "off"}, model=glm-5.2). ` +
|
||||
"Use server_session tool to start/send/abort/fork/resume sessions.",
|
||||
"info",
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
// ---- 工厂内辅助 ----
|
||||
|
||||
/**
|
||||
* 构造工具返回内容(text content + isError 标志)。
|
||||
* @param content 文本内容。
|
||||
* @param isError 是否为错误返回。
|
||||
*/
|
||||
function textResult(content: string, isError = false) {
|
||||
return { content: [{ type: "text" as const, text: content }], isError };
|
||||
}
|
||||
492
src/extensions/subprocess-isolation.ts
Normal file
492
src/extensions/subprocess-isolation.ts
Normal file
@ -0,0 +1,492 @@
|
||||
/**
|
||||
* @module subprocess-isolation
|
||||
*
|
||||
* 扩展子进程隔离层 —— 治嵌入式开发场景缺陷 #5(扩展 jiti 主进程零隔离,
|
||||
* 硬件操作扩展 SIGSEGV/资源泄漏带崩整个 agent)。
|
||||
*
|
||||
* 场景锚定:嵌入式扩展会直接操作硬件——i2c-dev 的 ioctl、gpio 的 mmap、
|
||||
* USB 仪器的 libusb 调用。这些涉及内核驱动交互和原生 FFI,比纯 JS 文件操作
|
||||
* 更易段错误/总线错误。一个 i2cdetect ioctl 参数错误致 SIGSEGV,或 GPIO mmap
|
||||
* 后忘 unmap 致资源泄漏,直接带崩整个 pi 进程——session、未落盘上下文、所有
|
||||
* 扩展全死。见 Docs/F06_扩展子进程隔离层.md。
|
||||
*
|
||||
* 核心:SubprocessIsolator 包裹注入的 SpawnFn,记录 child pid 表,
|
||||
* killStale(timeoutMs) 杀超时孤儿,crash 隔离(native 崩溃不传播给 agent,
|
||||
* 转成 ExecResult{exitCode:-1,stderr})。纯逻辑用注入 SpawnFn/KillFn mock,
|
||||
* 绝不依赖真实硬件/进程,离线可单测。
|
||||
*
|
||||
* 装配范式:顶层仅 `import type`(esbuild 擦除),defineTool/Type 在工厂体内
|
||||
* 动态 import(运行时解析到真 pi),故 tests 直接 import 本模块纯逻辑命名导出
|
||||
* 不会触发 pi 解析——离线可测。pi 未构建(模型目录需联网)时工厂不跑,无副作用。
|
||||
*/
|
||||
|
||||
import type {
|
||||
ExtensionAPI,
|
||||
ExtensionContext,
|
||||
ToolDefinition,
|
||||
} from "@earendil-works/pi-coding-agent";
|
||||
import type { ExecResult, ExecOpts } from "../shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// 类型契约
|
||||
// ============================================================================
|
||||
|
||||
/** native crash 信号集——ioctl/mmap SIGSEGV 等带崩子进程的信号。 */
|
||||
export const CRASH_SIGNALS = [
|
||||
"SIGSEGV",
|
||||
"SIGBUS",
|
||||
"SIGABRT",
|
||||
"SIGFPE",
|
||||
"SIGILL",
|
||||
] as const;
|
||||
export type CrashSignal = (typeof CRASH_SIGNALS)[number];
|
||||
|
||||
/** kill 信号(含 crash 信号 + 常规终止信号)。 */
|
||||
export type KillSignal = "SIGTERM" | "SIGKILL" | "SIGINT" | CrashSignal;
|
||||
|
||||
/**
|
||||
* 子进程句柄:SpawnFn 返回,含 pid + 完成承诺。
|
||||
*
|
||||
* @property pid 子进程 id。
|
||||
* @property command 可执行命令名。
|
||||
* @property args 命令参数数组。
|
||||
* @property startedAt 开始时间(ms epoch),由 isolator 用注入时钟覆盖。
|
||||
* @property result 子进程完成承诺;正常退出 → resolve(ExecResult),
|
||||
* native crash → resolve(ExecResult{signal:CRASH_SIGNAL}) 或 reject(Error)。
|
||||
* 扩展层用 child_process.spawn 构造;逻辑层测试用 mock 构造。
|
||||
*/
|
||||
export interface ChildHandle {
|
||||
pid: number;
|
||||
command: string;
|
||||
args: string[];
|
||||
startedAt: number;
|
||||
result: Promise<ExecResult>;
|
||||
}
|
||||
|
||||
/** 注入的 spawn 函数(测试 mock / 扩展层用 child_process.spawn 包装)。 */
|
||||
export type SpawnFn = (command: string, args: string[], opts?: ExecOpts) => ChildHandle;
|
||||
|
||||
/** 注入的 kill 函数。默认尝试 process.kill;测试注入 mock。 */
|
||||
export type KillFn = (pid: number, signal?: KillSignal) => boolean;
|
||||
|
||||
/** 时钟注入(killStale 确定性测试用),默认 Date.now。 */
|
||||
export type Clock = () => number;
|
||||
|
||||
/** SubprocessIsolator 构造选项。 */
|
||||
export interface IsolatorOptions {
|
||||
/** spawn 函数(必填)。 */
|
||||
spawn: SpawnFn;
|
||||
/** kill 函数(默认 process.kill)。 */
|
||||
kill?: KillFn;
|
||||
/** 默认每次调用超时(ms);0/未设 = 不限。 */
|
||||
defaultTimeoutMs?: number;
|
||||
/** 崩溃后最大重启次数(crash recovery 用,仅记录策略不强制)。 */
|
||||
maxRestarts?: number;
|
||||
/** 注入时钟,默认 Date.now。 */
|
||||
now?: Clock;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 纯函数:崩溃判定与转换(可独立单测)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* 判定信号是否是 native crash 信号。
|
||||
*
|
||||
* @param signal 退出信号字符串(可能 undefined/null/空)。
|
||||
* @returns 是 crash 信号返回 true,否则 false。
|
||||
*/
|
||||
export function isCrashSignal(signal: string | undefined | null): boolean {
|
||||
if (!signal) return false;
|
||||
return (CRASH_SIGNALS as readonly string[]).includes(signal);
|
||||
}
|
||||
|
||||
/**
|
||||
* 判定一个 ExecResult 是否代表 native crash(信号是 crash 信号)。
|
||||
*
|
||||
* @param r 执行结果。
|
||||
* @returns 是 crash 结果返回 true。
|
||||
*/
|
||||
export function isCrashResult(r: ExecResult): boolean {
|
||||
return isCrashSignal(r.signal);
|
||||
}
|
||||
|
||||
/**
|
||||
* 把崩溃转成对 agent 友好的 ExecResult(exitCode:-1,stderr 描述,不抛)。
|
||||
*
|
||||
* 这是缺陷 #5 的根治点:native 崩溃只杀子进程,session/上下文/其他扩展存活。
|
||||
*
|
||||
* @param r 原始崩溃结果。
|
||||
* @param pid 崩溃子进程 pid。
|
||||
* @param command 崩溃时执行的命令。
|
||||
* @returns 隔离后的 ExecResult,exitCode:-1,stderr 含崩溃诊断。
|
||||
*/
|
||||
export function crashToExecResult(
|
||||
r: ExecResult,
|
||||
pid: number,
|
||||
command: string,
|
||||
): ExecResult {
|
||||
const signal = r.signal ?? "unknown";
|
||||
return {
|
||||
stdout: r.stdout ?? "",
|
||||
stderr:
|
||||
(r.stderr ? r.stderr + "\n" : "") +
|
||||
`[subprocess-isolation] child pid ${pid} crashed (signal ${signal}): ${command}. ` +
|
||||
`Isolated — session continues. Investigate native addon / ioctl / mmap.`,
|
||||
exitCode: -1,
|
||||
signal: r.signal,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 构造一个隔离层错误结果(reject / timeout / stale kill 统一出口),绝不抛。
|
||||
*
|
||||
* @param message 错误描述。
|
||||
* @returns exitCode:-1 的 ExecResult,stderr 带 [subprocess-isolation] 前缀。
|
||||
*/
|
||||
export function isolateErrorExecResult(message: string): ExecResult {
|
||||
return { stdout: "", stderr: `[subprocess-isolation] ${message}`, exitCode: -1 };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// SubprocessIsolator
|
||||
// ============================================================================
|
||||
|
||||
/** 崩溃审计记录(crashLog 单条)。 */
|
||||
export interface CrashRecord {
|
||||
/** 崩溃子进程 pid。 */
|
||||
pid: number;
|
||||
/** 崩溃时执行的命令。 */
|
||||
command: string;
|
||||
/** crash 信号(若有)。 */
|
||||
signal?: string;
|
||||
/** 若 spawn 层 reject,记 error message。 */
|
||||
error?: string;
|
||||
/** 记录时间(ms epoch,注入时钟)。 */
|
||||
at: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 子进程隔离器。包裹注入的 SpawnFn:
|
||||
* - 记录 child pid 表(tracking)
|
||||
* - killStale(timeoutMs) 杀超时孤儿
|
||||
* - crash 隔离(native 崩溃转 ExecResult{exitCode:-1,stderr},不传播/不抛)
|
||||
*
|
||||
* 纯逻辑:所有 IO(spawn/kill/时钟)注入,无真实硬件依赖,可单测。
|
||||
* fail-closed 语义:超时即杀,崩溃即隔离转 error,绝不放行未隔离的 native crash。
|
||||
*/
|
||||
export class SubprocessIsolator {
|
||||
private readonly spawn: SpawnFn;
|
||||
private readonly kill: KillFn;
|
||||
private readonly defaultTimeoutMs: number;
|
||||
private readonly maxRestarts: number;
|
||||
private readonly now: Clock;
|
||||
private readonly children = new Map<number, ChildHandle>();
|
||||
private readonly crashLog: CrashRecord[] = [];
|
||||
|
||||
/**
|
||||
* @param opts 构造选项,spawn 必填,其余有默认。
|
||||
*/
|
||||
constructor(opts: IsolatorOptions) {
|
||||
this.spawn = opts.spawn;
|
||||
this.kill =
|
||||
opts.kill ??
|
||||
((pid: number, signal?: KillSignal) => {
|
||||
try {
|
||||
process.kill(pid, signal ?? "SIGTERM");
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
});
|
||||
this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 0;
|
||||
this.maxRestarts = opts.maxRestarts ?? 3;
|
||||
this.now = opts.now ?? (() => Date.now());
|
||||
}
|
||||
|
||||
/** 当前 tracked child pid 表快照。 */
|
||||
getTrackedPids(): number[] {
|
||||
return [...this.children.keys()];
|
||||
}
|
||||
|
||||
/**
|
||||
* 是否在跟踪某 pid。
|
||||
* @param pid 子进程 id。
|
||||
* @returns 在跟踪返回 true。
|
||||
*/
|
||||
isTracking(pid: number): boolean {
|
||||
return this.children.has(pid);
|
||||
}
|
||||
|
||||
/** 崩溃日志(crash 隔离的审计轨迹,供 session appendEntry)。 */
|
||||
getCrashLog(): CrashRecord[] {
|
||||
return [...this.crashLog];
|
||||
}
|
||||
|
||||
/** 最大重启次数配置(crash recovery 策略用)。 */
|
||||
getMaxRestarts(): number {
|
||||
return this.maxRestarts;
|
||||
}
|
||||
|
||||
/**
|
||||
* 在隔离的子进程里执行命令。**绝不抛**——native crash 转成
|
||||
* ExecResult{exitCode:-1,stderr},agent session 继续。
|
||||
*
|
||||
* 流程:spawn → 记 pid(startedAt 用注入时钟)→ 赛跑 result vs timeout
|
||||
* → collect 做 crash 隔离 → finally 清 tracking。
|
||||
*
|
||||
* @param command 可执行命令。
|
||||
* @param args 参数数组。
|
||||
* @param opts 执行选项(cwd/env/timeout)。
|
||||
* @returns ExecResult;崩溃/超时统一 exitCode:-1 不抛。
|
||||
*/
|
||||
async exec(command: string, args: string[], opts?: ExecOpts): Promise<ExecResult> {
|
||||
const child = this.spawn(command, args, opts);
|
||||
// 用 isolator 自己的时钟覆盖 startedAt,保证 killStale 时钟一致。
|
||||
child.startedAt = this.now();
|
||||
this.children.set(child.pid, child);
|
||||
|
||||
const timeoutMs = opts?.timeout ?? this.defaultTimeoutMs;
|
||||
try {
|
||||
return await this.awaitChild(child, timeoutMs);
|
||||
} finally {
|
||||
this.children.delete(child.pid);
|
||||
}
|
||||
}
|
||||
|
||||
/** 赛跑 child 结果 vs 超时。 */
|
||||
private async awaitChild(child: ChildHandle, timeoutMs: number): Promise<ExecResult> {
|
||||
if (!timeoutMs || timeoutMs <= 0) {
|
||||
return await this.collect(child, child.result);
|
||||
}
|
||||
|
||||
let timer: ReturnType<typeof setTimeout> | undefined;
|
||||
const timeout = new Promise<ExecResult>((resolve) => {
|
||||
timer = setTimeout(() => {
|
||||
this.kill(child.pid, "SIGKILL");
|
||||
this.recordCrash(child, "SIGKILL", `timeout after ${timeoutMs}ms`);
|
||||
resolve(
|
||||
isolateErrorExecResult(
|
||||
`child pid ${child.pid} timed out after ${timeoutMs}ms: ${child.command}`,
|
||||
),
|
||||
);
|
||||
}, timeoutMs);
|
||||
});
|
||||
try {
|
||||
return await Promise.race([this.collect(child, child.result), timeout]);
|
||||
} finally {
|
||||
if (timer) clearTimeout(timer);
|
||||
}
|
||||
}
|
||||
|
||||
/** 收集 child 结果,做 crash 隔离转换。绝不抛。 */
|
||||
private async collect(child: ChildHandle, p: Promise<ExecResult>): Promise<ExecResult> {
|
||||
let r: ExecResult;
|
||||
try {
|
||||
r = await p;
|
||||
} catch (e) {
|
||||
// spawn 层 reject(native crash 带崩 promise 链)→ 隔离,不传播
|
||||
const msg = e instanceof Error ? e.message : String(e);
|
||||
this.recordCrash(child, undefined, msg);
|
||||
return isolateErrorExecResult(
|
||||
`child pid ${child.pid} crashed: ${msg} | ${child.command}`,
|
||||
);
|
||||
}
|
||||
if (isCrashResult(r)) {
|
||||
this.recordCrash(child, r.signal);
|
||||
return crashToExecResult(r, child.pid, child.command);
|
||||
}
|
||||
return r;
|
||||
}
|
||||
|
||||
/**
|
||||
* 记一条崩溃审计。
|
||||
* @param child 子进程句柄。
|
||||
* @param signal crash 信号(可空)。
|
||||
* @param error error message(可空)。
|
||||
*/
|
||||
private recordCrash(child: ChildHandle, signal?: string, error?: string): void {
|
||||
this.crashLog.push({
|
||||
pid: child.pid,
|
||||
command: child.command,
|
||||
signal,
|
||||
error,
|
||||
at: this.now(),
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 杀超时孤儿:遍历 child 表,杀掉运行时间超过 timeoutMs 的。
|
||||
* 返回被杀的 pid 列表(已从 tracking 表移除)。fail-closed:超时即杀。
|
||||
*
|
||||
* @param timeoutMs 超时阈值(ms),运行超过即杀。
|
||||
* @returns 被杀的 pid 列表。
|
||||
*/
|
||||
killStale(timeoutMs: number): number[] {
|
||||
const now = this.now();
|
||||
const killed: number[] = [];
|
||||
for (const [pid, child] of this.children) {
|
||||
if (now - child.startedAt > timeoutMs) {
|
||||
this.kill(pid, "SIGKILL");
|
||||
this.children.delete(pid);
|
||||
this.recordCrash(child, "SIGKILL", `stale after ${now - child.startedAt}ms`);
|
||||
killed.push(pid);
|
||||
}
|
||||
}
|
||||
return killed;
|
||||
}
|
||||
|
||||
/**
|
||||
* 杀掉所有 tracked children(session abort / shutdown 用)。
|
||||
* 返回被杀 pid 列表,并清空 tracking 表。
|
||||
*
|
||||
* @param signal 终止信号,默认 SIGTERM。
|
||||
* @returns 被杀的 pid 列表。
|
||||
*/
|
||||
killAll(signal: KillSignal = "SIGTERM"): number[] {
|
||||
const killed: number[] = [];
|
||||
for (const pid of this.children.keys()) {
|
||||
this.kill(pid, signal);
|
||||
killed.push(pid);
|
||||
}
|
||||
this.children.clear();
|
||||
return killed;
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 扩展装配(运行时在真 pi 内动态 import defineTool/Type)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* subprocess-isolation 扩展装配。
|
||||
*
|
||||
* - 构造 SubprocessIsolator(独立子进程 spawn + process.kill)
|
||||
* - 注册 isolated_exec 工具,agent 调硬件操作走隔离通道
|
||||
* - before_agent_start 跑 killStale 清孤儿(fail-closed)
|
||||
* - session_start 落 entry 标记隔离已就绪
|
||||
*
|
||||
* defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。
|
||||
*
|
||||
* @param pi 扩展 API。
|
||||
* @returns Promise<void>。
|
||||
*/
|
||||
export default async function subprocessIsolationExtension(
|
||||
pi: ExtensionAPI,
|
||||
): Promise<void> {
|
||||
const { defineTool } = await import("@earendil-works/pi-coding-agent");
|
||||
const { Type } = await import("@earendil-works/pi-ai");
|
||||
const { spawn } = await import("node:child_process");
|
||||
|
||||
/**
|
||||
* 用 node:child_process.spawn 构造 SpawnFn:每次 exec 起独立子进程,
|
||||
* 收集 stdout/stderr,退出/崩溃转 ExecResult。SIGSEGV 只杀子进程。
|
||||
*/
|
||||
const makeSpawnFn = (): SpawnFn => {
|
||||
return (command, args, opts) => {
|
||||
const child = spawn(command, args, {
|
||||
cwd: opts?.cwd,
|
||||
env: opts?.env,
|
||||
stdio: ["ignore", "pipe", "pipe"],
|
||||
// 超时由 SubprocessIsolator 管(注入 KillFn 杀进程),这里不设。
|
||||
});
|
||||
let stdout = "";
|
||||
let stderr = "";
|
||||
child.stdout?.on("data", (d: Buffer) => {
|
||||
stdout += d.toString();
|
||||
});
|
||||
child.stderr?.on("data", (d: Buffer) => {
|
||||
stderr += d.toString();
|
||||
});
|
||||
const result = new Promise<ExecResult>((resolve) => {
|
||||
child.on("exit", (code, signal) => {
|
||||
resolve({
|
||||
stdout,
|
||||
stderr,
|
||||
exitCode: code ?? -1,
|
||||
signal: signal ?? undefined,
|
||||
});
|
||||
});
|
||||
// spawn 本身失败(ENOENT 等)→ 隔离层统一转 error,不抛
|
||||
child.on("error", (err) => {
|
||||
resolve({
|
||||
stdout,
|
||||
stderr: stderr + (stderr ? "\n" : "") + err.message,
|
||||
exitCode: -1,
|
||||
});
|
||||
});
|
||||
});
|
||||
const handle: ChildHandle = {
|
||||
pid: child.pid ?? -1,
|
||||
command,
|
||||
args,
|
||||
startedAt: Date.now(),
|
||||
result,
|
||||
};
|
||||
return handle;
|
||||
};
|
||||
};
|
||||
|
||||
// 单例 isolator(同进程跨 tool call 共享 pid 表)
|
||||
const isolator = new SubprocessIsolator({ spawn: makeSpawnFn() });
|
||||
|
||||
// isolated_exec 工具:让 agent 显式声明"这条命令跑在隔离子进程里"。
|
||||
const isolatedExecTool = defineTool({
|
||||
name: "isolated_exec",
|
||||
label: "Isolated Exec",
|
||||
description:
|
||||
"Run a command in an isolated subprocess so native crashes (SIGSEGV/ioctl/mmap) " +
|
||||
"do not bring down the agent session. Use for hardware-touching native operations " +
|
||||
"(i2c-dev ioctl, gpio mmap, libusb). Returns ExecResult; crashes -> exitCode:-1 + stderr, " +
|
||||
"never throws.",
|
||||
promptSnippet: "Run a native/hardware command in isolated subprocess (crash-safe)",
|
||||
parameters: Type.Object(
|
||||
{
|
||||
command: Type.String({ description: "Executable to run, e.g. i2cdetect / gpioget / openocd." }),
|
||||
args: Type.Array(Type.String(), { description: "Arguments to pass." }),
|
||||
},
|
||||
{ description: "command + args + optional timeout." },
|
||||
),
|
||||
executionMode: "sequential",
|
||||
async execute(_id, params, _signal, _onUpdate, _ctx) {
|
||||
const p = params as { command: string; args: string[]; timeout?: number };
|
||||
const r = await isolator.exec(p.command, p.args, { timeout: p.timeout });
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify(
|
||||
{ exitCode: r.exitCode, signal: r.signal ?? null, stdout: r.stdout, stderr: r.stderr },
|
||||
null,
|
||||
2,
|
||||
),
|
||||
},
|
||||
],
|
||||
details: { isolated: true, exitCode: r.exitCode, signal: r.signal },
|
||||
isError: r.exitCode !== 0,
|
||||
};
|
||||
},
|
||||
}) as ToolDefinition;
|
||||
|
||||
pi.registerTool(isolatedExecTool);
|
||||
|
||||
// before_agent_start:清孤儿 + 落就绪标记(fail-closed)
|
||||
pi.on("before_agent_start", (_event, _ctx: ExtensionContext) => {
|
||||
// fail-closed:每次新 turn 前清掉上轮残留孤儿(防资源泄漏累积)
|
||||
const killed = isolator.killStale(60_000);
|
||||
if (killed.length > 0) {
|
||||
pi.appendEntry("isolate:stale-killed", { pids: killed });
|
||||
}
|
||||
pi.appendEntry("isolate:armed", {
|
||||
maxRestarts: isolator.getMaxRestarts(),
|
||||
note: "native crashes (SIGSEGV/ioctl/mmap) isolated to subprocess; session survives.",
|
||||
});
|
||||
return undefined;
|
||||
});
|
||||
|
||||
// session_start:标记隔离层已挂载
|
||||
pi.on("session_start", (_event, _ctx: ExtensionContext) => {
|
||||
pi.appendEntry("isolate:loaded", { tool: "isolated_exec" });
|
||||
return undefined;
|
||||
});
|
||||
}
|
||||
18
src/index.ts
Normal file
18
src/index.ts
Normal file
@ -0,0 +1,18 @@
|
||||
/**
|
||||
* @module @d-robotics/physical-byte-agent
|
||||
*
|
||||
* 基于 pi 二开的嵌入式开发 Agent(glm-5.2 + 硬件闭环)。
|
||||
*
|
||||
* 公共 API:
|
||||
* - {@link PhysicalByteAgent} 程序化启动类(launch / verifyAssembly)
|
||||
* - {@link extensionFactories} 21 个域扩展工厂(按依赖顺序)
|
||||
* - 共享类型 re-export
|
||||
*/
|
||||
|
||||
export { PhysicalByteAgent } from "./agent.js";
|
||||
export { extensionFactories, default as physicalByteAgentAssembly } from "./extensions/index.js";
|
||||
export type {
|
||||
LaunchOptions,
|
||||
LaunchResult,
|
||||
} from "./agent.js";
|
||||
export * from "./shared/types.js";
|
||||
104
src/shared/types.ts
Normal file
104
src/shared/types.ts
Normal file
@ -0,0 +1,104 @@
|
||||
/**
|
||||
* Physical Byte Agent — 跨扩展共享类型
|
||||
*
|
||||
* 设计:纯类型,零 pi 依赖。扩展文件 import 这些类型,逻辑内联在各扩展文件里
|
||||
* 并以命名导出供 tests 直接单测(无需 pi 运行时、无需真实硬件)。
|
||||
*/
|
||||
|
||||
/** 命令执行结果。扩展通过注入的 ExecFn 获取,逻辑层只认此结构。 */
|
||||
export interface ExecResult {
|
||||
stdout: string;
|
||||
stderr: string;
|
||||
exitCode: number;
|
||||
signal?: string;
|
||||
}
|
||||
|
||||
/** 可注入的执行函数签名(子进程隔离层 / 板链路 / 测试 mock 都走这条)。 */
|
||||
export type ExecFn = (command: string, args: string[], opts?: ExecOpts) => Promise<ExecResult>;
|
||||
|
||||
export interface ExecOpts {
|
||||
cwd?: string;
|
||||
timeout?: number;
|
||||
env?: Record<string, string>;
|
||||
/** 以哪个板执行(board-link 扩展用)。 */
|
||||
boardId?: string;
|
||||
}
|
||||
|
||||
/** hex 地址归一化结果(glm-provider 命门二)。 */
|
||||
export interface NormalizedArg {
|
||||
value: string;
|
||||
corrected: boolean;
|
||||
original: unknown;
|
||||
}
|
||||
|
||||
/** 安全门决策(safety-gate)。 */
|
||||
export interface SafetyDecision {
|
||||
block: boolean;
|
||||
reason?: string;
|
||||
rule?: string;
|
||||
safeAlternative?: string;
|
||||
}
|
||||
|
||||
/** 闭环 checkpoint 步骤(loop-orchestrator)。 */
|
||||
export type CheckpointStep = "edit" | "compile" | "flash" | "verify" | "check" | "done";
|
||||
|
||||
export interface CheckpointState {
|
||||
currentStep: CheckpointStep;
|
||||
stepPassed: boolean;
|
||||
history: Array<{ step: CheckpointStep; passed: boolean; timestamp: number }>;
|
||||
}
|
||||
|
||||
/** 硬件验证信号类型(hardware-verify)。 */
|
||||
export type SignalType = "dmesg" | "gpio" | "i2c" | "sysfs" | "serial" | "current" | "stdout";
|
||||
|
||||
export interface SignalSpec {
|
||||
type: SignalType;
|
||||
args: Record<string, string>;
|
||||
}
|
||||
|
||||
export interface ExpectSpec {
|
||||
match: string | number;
|
||||
mode: "contains" | "equals" | "regex" | "range" | "gt" | "lt";
|
||||
failClosed?: boolean;
|
||||
min?: number;
|
||||
max?: number;
|
||||
}
|
||||
|
||||
export interface VerifyRecord {
|
||||
task: string;
|
||||
trace: Array<{ signal: SignalSpec; collected: string; matched: boolean }>;
|
||||
judge: "pass" | "fail";
|
||||
rootCause: string | null;
|
||||
}
|
||||
|
||||
/** 烧录方法(flash)。 */
|
||||
export type FlashMethod = "dd" | "fastboot" | "dfu" | "openocd";
|
||||
|
||||
export interface FlashPlan {
|
||||
method: FlashMethod;
|
||||
commands: string[];
|
||||
target: string;
|
||||
image: string;
|
||||
expectedSha256?: string;
|
||||
}
|
||||
|
||||
/** 持久 Shell 会话(persistent-shell)。 */
|
||||
export interface PShellSession {
|
||||
id: string;
|
||||
createdAt: number;
|
||||
lastCommand?: string;
|
||||
busy: boolean;
|
||||
}
|
||||
|
||||
export type PShellAction = "open" | "close" | "send" | "list";
|
||||
|
||||
/** 板链路(board-link)。 */
|
||||
export type BoardLinkType = "ssh" | "serial" | "local";
|
||||
|
||||
export interface BoardSpec {
|
||||
id: string;
|
||||
name: string;
|
||||
link: BoardLinkType;
|
||||
address: string;
|
||||
fingerprint: string;
|
||||
}
|
||||
214
src/types/pi.d.ts
vendored
Normal file
214
src/types/pi.d.ts
vendored
Normal file
@ -0,0 +1,214 @@
|
||||
/**
|
||||
* Pi 类型镜像 —— 仅用于 offline `tsc --noEmit` 类型检查。
|
||||
*
|
||||
* 为什么需要:pi 自家源码 `packages/ai/src/providers/data/*.json` 是 generate-models
|
||||
* 联网生成的产物,离线不存在;直接把 tsconfig paths 指向 pi 源码会让 tsc 顺着
|
||||
* import 链拉到这些缺失 JSON 而报错。本 shim 声明我们用到的 pi 扩展 API 面(已对照
|
||||
* pi 源码实测核对),让 tsc 能验证我们用得对不对。
|
||||
*
|
||||
* 运行时(vitest + 真 pi 加载)一律解析到真 pi 模块(见 vitest.config.ts alias),
|
||||
* 本 shim 不参与运行。pi 升级 API 时需同步本文件。
|
||||
*/
|
||||
|
||||
declare module "@earendil-works/pi-ai" {
|
||||
export const Type: {
|
||||
Object<T extends Record<string, unknown>>(props: T, options?: { description?: string }): T;
|
||||
String(options?: { description?: string }): string;
|
||||
Number(options?: { description?: string }): number;
|
||||
Boolean(options?: { description?: string }): boolean;
|
||||
Optional<T>(schema: T, options?: { description?: string }): T;
|
||||
Union<T extends readonly unknown[]>(schemas: T, options?: { description?: string }): T[number];
|
||||
Literal<T extends string | number>(value: T): T;
|
||||
Array<T>(schema: T, options?: { description?: string }): T[];
|
||||
};
|
||||
export type TSchema = unknown;
|
||||
}
|
||||
|
||||
declare module "@earendil-works/pi-coding-agent" {
|
||||
export interface TextContent {
|
||||
type: "text";
|
||||
text: string;
|
||||
}
|
||||
export interface ImageContent {
|
||||
type: "image";
|
||||
[key: string]: unknown;
|
||||
}
|
||||
export type ToolExecutionMode = "sequential" | "parallel";
|
||||
export type ThinkingLevel = "off" | "low" | "medium" | "high";
|
||||
|
||||
export interface AgentToolResult<TDetails = unknown> {
|
||||
content: Array<TextContent | ImageContent>;
|
||||
details?: TDetails;
|
||||
isError?: boolean;
|
||||
}
|
||||
export type AgentToolUpdateCallback<TDetails = unknown> = (update: {
|
||||
content?: Array<TextContent | ImageContent>;
|
||||
details?: TDetails;
|
||||
}) => void;
|
||||
|
||||
export interface ExtensionUIContext {
|
||||
confirm(title: string, message: string, opts?: ExtensionUIDialogOptions): Promise<boolean>;
|
||||
select(title: string, options: string[], opts?: ExtensionUIDialogOptions): Promise<string>;
|
||||
input(title: string, placeholder?: string, opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
|
||||
notify(message: string, type?: "info" | "warning" | "error"): void;
|
||||
custom: (render: unknown) => Promise<unknown>;
|
||||
}
|
||||
export interface ExtensionUIDialogOptions {
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
export interface ExtensionContext {
|
||||
ui: ExtensionUIContext;
|
||||
mode: "tui" | "cli" | "rpc";
|
||||
hasUI: boolean;
|
||||
cwd: string;
|
||||
sessionManager: {
|
||||
getBranch(): Array<{ type: string; customType?: string; data?: unknown; id: string }>;
|
||||
getEntries(): Array<{ type: string; customType?: string; data?: unknown; id: string }>;
|
||||
};
|
||||
model: unknown;
|
||||
signal: AbortSignal | undefined;
|
||||
isIdle(): boolean;
|
||||
getSystemPrompt(): string;
|
||||
}
|
||||
|
||||
export interface ToolDefinition<TParams = unknown, TDetails = unknown, TState = any> {
|
||||
name: string;
|
||||
label: string;
|
||||
description: string;
|
||||
promptSnippet?: string;
|
||||
promptGuidelines?: string[];
|
||||
parameters: TParams;
|
||||
prepareArguments?: (args: unknown) => unknown;
|
||||
executionMode?: ToolExecutionMode;
|
||||
execute(
|
||||
toolCallId: string,
|
||||
params: any,
|
||||
signal: AbortSignal | undefined,
|
||||
onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
|
||||
ctx: ExtensionContext,
|
||||
): Promise<AgentToolResult<TDetails>>;
|
||||
renderCall?: unknown;
|
||||
renderResult?: unknown;
|
||||
}
|
||||
|
||||
export function defineTool<TParams, TDetails = unknown, TState = any>(
|
||||
tool: ToolDefinition<TParams, TDetails, TState>,
|
||||
): ToolDefinition<TParams, TDetails, TState>;
|
||||
|
||||
export interface ToolCallEvent {
|
||||
type: "tool_call";
|
||||
toolCallId: string;
|
||||
toolName: string;
|
||||
input: Record<string, unknown>;
|
||||
}
|
||||
export interface ToolCallEventResult {
|
||||
block?: boolean;
|
||||
reason?: string;
|
||||
terminate?: boolean;
|
||||
}
|
||||
export interface ToolResultEvent {
|
||||
type: "tool_result";
|
||||
toolCallId: string;
|
||||
toolName: string;
|
||||
input: Record<string, unknown>;
|
||||
isError: boolean;
|
||||
content: Array<TextContent | ImageContent>;
|
||||
details?: unknown;
|
||||
}
|
||||
export interface ToolResultEventResult {
|
||||
content?: Array<TextContent | ImageContent>;
|
||||
details?: unknown;
|
||||
isError?: boolean;
|
||||
}
|
||||
export interface SessionStartEvent {
|
||||
type: "session_start";
|
||||
reason: "startup" | "reload" | "new" | "resume" | "fork";
|
||||
}
|
||||
export interface BeforeAgentStartEvent {
|
||||
type: "before_agent_start";
|
||||
systemPrompt?: string;
|
||||
prompt?: string;
|
||||
}
|
||||
export interface BeforeAgentStartEventResult {
|
||||
message?: { customType: string; content: string; display: boolean; details?: unknown };
|
||||
systemPrompt?: string;
|
||||
}
|
||||
export interface SessionBeforeCompactResult {
|
||||
cancel?: boolean;
|
||||
compaction?: unknown;
|
||||
}
|
||||
export interface EventBus {
|
||||
on(event: string, handler: (data: unknown) => void): void;
|
||||
emit(event: string, data: unknown): void;
|
||||
}
|
||||
export interface ExecResult {
|
||||
stdout: string;
|
||||
stderr: string;
|
||||
exitCode: number;
|
||||
signal?: string;
|
||||
}
|
||||
export interface ExecOptions {
|
||||
cwd?: string;
|
||||
timeout?: number;
|
||||
env?: Record<string, string>;
|
||||
}
|
||||
|
||||
export interface ProviderModelConfig {
|
||||
id: string;
|
||||
name: string;
|
||||
api?: string;
|
||||
baseUrl?: string;
|
||||
reasoning: boolean;
|
||||
thinkingLevelMap?: Record<string, unknown>;
|
||||
input: ("text" | "image")[];
|
||||
cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
|
||||
contextWindow: number;
|
||||
maxTokens: number;
|
||||
headers?: Record<string, string>;
|
||||
compat?: Record<string, unknown>;
|
||||
}
|
||||
export interface ProviderConfig {
|
||||
name?: string;
|
||||
baseUrl?: string;
|
||||
apiKey?: string;
|
||||
api?: string;
|
||||
headers?: Record<string, string>;
|
||||
authHeader?: boolean;
|
||||
models?: ProviderModelConfig[];
|
||||
}
|
||||
|
||||
export interface ExtensionAPI {
|
||||
on(event: "tool_call", handler: (event: ToolCallEvent, ctx: ExtensionContext) => Promise<ToolCallEventResult | undefined> | ToolCallEventResult | undefined): void;
|
||||
on(event: "tool_result", handler: (event: ToolResultEvent, ctx: ExtensionContext) => Promise<ToolResultEventResult | undefined> | ToolResultEventResult | undefined): void;
|
||||
on(event: "session_start", handler: (event: SessionStartEvent, ctx: ExtensionContext) => Promise<unknown> | unknown): void;
|
||||
on(event: "before_agent_start", handler: (event: BeforeAgentStartEvent, ctx: ExtensionContext) => Promise<BeforeAgentStartEventResult | undefined> | BeforeAgentStartEventResult | undefined): void;
|
||||
on(event: "session_before_compact", handler: (event: unknown, ctx: ExtensionContext) => Promise<SessionBeforeCompactResult | undefined> | SessionBeforeCompactResult | undefined): void;
|
||||
on(event: string, handler: (event: any, ctx: ExtensionContext) => unknown): void;
|
||||
registerTool(tool: ToolDefinition): void;
|
||||
registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: ExtensionContext) => Promise<void> | void }): void;
|
||||
registerProvider(provider: unknown): void;
|
||||
registerProvider(name: string, config: ProviderConfig): void;
|
||||
sendMessage<T = unknown>(message: { customType: string; content: T; display: boolean; details?: unknown }, options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" }): void;
|
||||
sendUserMessage(content: string, options?: { deliverAs?: "steer" | "followUp" }): void;
|
||||
appendEntry<T = unknown>(customType: string, data?: T): void;
|
||||
exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
|
||||
setActiveTools(toolNames: string[]): void;
|
||||
getActiveTools(): string[];
|
||||
getAllTools(): Array<{ name: string }>;
|
||||
setModel(model: unknown): Promise<boolean>;
|
||||
events: EventBus;
|
||||
}
|
||||
|
||||
// 程序化启动(agent.ts 动态 import 用;运行时解析真 pi)
|
||||
export interface CreateAgentSessionResult {
|
||||
session: unknown;
|
||||
modelFallbackMessage?: string;
|
||||
}
|
||||
export declare function createAgentSession(options?: Record<string, unknown>): Promise<CreateAgentSessionResult>;
|
||||
export declare const SessionManager: {
|
||||
inMemory?(): unknown;
|
||||
create?(...args: unknown[]): unknown;
|
||||
[key: string]: unknown;
|
||||
};
|
||||
}
|
||||
463
tests/board-link.test.ts
Normal file
463
tests/board-link.test.ts
Normal file
@ -0,0 +1,463 @@
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import {
|
||||
BoardRegistry,
|
||||
parseSshAddress,
|
||||
buildSshArgs,
|
||||
parseSerialAddress,
|
||||
makeExec,
|
||||
healthCheck,
|
||||
computeFingerprint,
|
||||
SERIAL_STUB_RESULT,
|
||||
type RegistryEntry,
|
||||
} from "../src/extensions/board-link.js";
|
||||
import type { BoardSpec, ExecFn, ExecResult } from "../src/shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// mock 工厂
|
||||
// ============================================================================
|
||||
|
||||
function makeMockExec(overrides?: Partial<ExecResult>): ExecFn & { mock: { calls: unknown[][] } } {
|
||||
const fn = vi.fn(async (): Promise<ExecResult> => ({
|
||||
stdout: overrides?.stdout ?? "",
|
||||
stderr: overrides?.stderr ?? "",
|
||||
exitCode: overrides?.exitCode ?? 0,
|
||||
}));
|
||||
return fn as unknown as ExecFn & { mock: { calls: unknown[][] } };
|
||||
}
|
||||
|
||||
function sshBoard(id = "x5", address = "root@192.168.1.100:22"): BoardSpec {
|
||||
return {
|
||||
id,
|
||||
name: `Board ${id}`,
|
||||
link: "ssh",
|
||||
address,
|
||||
fingerprint: computeFingerprint("ssh", address),
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// BoardRegistry — register / list / unregister
|
||||
// ============================================================================
|
||||
|
||||
describe("board-link BoardRegistry — register/list/unregister", () => {
|
||||
it("register 后 list 能查到", () => {
|
||||
const reg = new BoardRegistry();
|
||||
const board = sshBoard("x5", "root@192.168.1.100:22");
|
||||
const r = reg.register(board);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(reg.list()).toHaveLength(1);
|
||||
expect(reg.get("x5")).toBe(board);
|
||||
});
|
||||
|
||||
it("register 多块板 list 按插入序返回", () => {
|
||||
const reg = new BoardRegistry();
|
||||
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
|
||||
reg.register(sshBoard("s100", "root@192.168.1.101:2222"));
|
||||
reg.register({
|
||||
id: "local",
|
||||
name: "Local board",
|
||||
link: "local",
|
||||
address: "",
|
||||
fingerprint: computeFingerprint("local", ""),
|
||||
});
|
||||
expect(reg.list()).toHaveLength(3);
|
||||
expect(reg.size).toBe(3);
|
||||
});
|
||||
|
||||
it("unregister 存在的板返回 true 并移除", () => {
|
||||
const reg = new BoardRegistry();
|
||||
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
|
||||
expect(reg.unregister("x5")).toBe(true);
|
||||
expect(reg.list()).toHaveLength(0);
|
||||
expect(reg.get("x5")).toBeUndefined();
|
||||
});
|
||||
|
||||
it("unregister 不存在的板返回 false", () => {
|
||||
const reg = new BoardRegistry();
|
||||
expect(reg.unregister("nonexistent")).toBe(false);
|
||||
});
|
||||
|
||||
it("getByFingerprint 能按指纹反查", () => {
|
||||
const reg = new BoardRegistry();
|
||||
const board = sshBoard("x5", "root@192.168.1.100:22");
|
||||
reg.register(board);
|
||||
expect(reg.getByFingerprint(board.fingerprint)).toBe(board);
|
||||
expect(reg.getByFingerprint("nonexistent")).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// BoardRegistry — fingerprint 去重
|
||||
// ============================================================================
|
||||
|
||||
describe("board-link BoardRegistry — fingerprint 去重", () => {
|
||||
it("重复 fingerprint 被拒绝(同一物理板不可重复注册)", () => {
|
||||
const reg = new BoardRegistry();
|
||||
const a = sshBoard("board-a", "root@192.168.1.100:22");
|
||||
// 不同 id 但相同 address → 相同 fingerprint
|
||||
const b = sshBoard("board-b", "root@192.168.1.100:22");
|
||||
expect(reg.register(a).ok).toBe(true);
|
||||
const r = reg.register(b);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toContain("fingerprint");
|
||||
expect(r.conflictId).toBe("board-a");
|
||||
expect(reg.size).toBe(1); // b 没进去
|
||||
});
|
||||
|
||||
it("重复 id 被拒绝(即使 fingerprint 不同)", () => {
|
||||
const reg = new BoardRegistry();
|
||||
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
|
||||
const r = reg.register(sshBoard("x5", "root@192.168.1.101:22"));
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toContain("already registered");
|
||||
expect(r.conflictId).toBe("x5");
|
||||
});
|
||||
|
||||
it("不同 fingerprint + 不同 id 都能注册", () => {
|
||||
const reg = new BoardRegistry();
|
||||
expect(reg.register(sshBoard("x5", "root@192.168.1.100:22")).ok).toBe(true);
|
||||
expect(reg.register(sshBoard("s100", "root@192.168.1.101:22")).ok).toBe(true);
|
||||
expect(reg.size).toBe(2);
|
||||
});
|
||||
|
||||
it("unregister 后 fingerprint 释放,可重新注册同 address", () => {
|
||||
const reg = new BoardRegistry();
|
||||
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
|
||||
reg.unregister("x5");
|
||||
// 同 address 现在可以注册了(fingerprint 已释放)
|
||||
expect(reg.register(sshBoard("x5-reborn", "root@192.168.1.100:22")).ok).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// BoardRegistry — session 重建
|
||||
// ============================================================================
|
||||
|
||||
describe("board-link BoardRegistry — fromEntries/toEntries session 重建", () => {
|
||||
it("fromEntries 从 session entries 重建注册表", () => {
|
||||
const entries: Array<{ customType?: string; data?: unknown }> = [
|
||||
{ customType: "boardlink:registry", data: sshBoard("x5", "root@192.168.1.100:22") },
|
||||
{ customType: "other:stuff", data: { foo: "bar" } },
|
||||
{ customType: "boardlink:registry", data: sshBoard("s100", "root@192.168.1.101:2222") },
|
||||
{ customType: "boardlink:registry", data: { broken: true } }, // 无效 spec,跳过
|
||||
];
|
||||
const reg = BoardRegistry.fromEntries(entries);
|
||||
expect(reg.size).toBe(2);
|
||||
expect(reg.get("x5")).toBeDefined();
|
||||
expect(reg.get("s100")).toBeDefined();
|
||||
});
|
||||
|
||||
it("toEntries 导出可持久化条目", () => {
|
||||
const reg = new BoardRegistry();
|
||||
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
|
||||
const entries = reg.toEntries();
|
||||
expect(entries).toHaveLength(1);
|
||||
expect(entries[0]?.customType).toBe("boardlink:registry");
|
||||
expect((entries[0] as RegistryEntry).data.id).toBe("x5");
|
||||
});
|
||||
|
||||
it("toEntries → fromEntries 往返一致", () => {
|
||||
const reg = new BoardRegistry();
|
||||
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
|
||||
reg.register(sshBoard("s100", "root@192.168.1.101:2222"));
|
||||
const rebuilt = BoardRegistry.fromEntries(reg.toEntries());
|
||||
expect(rebuilt.size).toBe(2);
|
||||
expect(rebuilt.get("x5")?.address).toBe("root@192.168.1.100:22");
|
||||
expect(rebuilt.get("s100")?.address).toBe("root@192.168.1.101:2222");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// parseSshAddress
|
||||
// ============================================================================
|
||||
|
||||
describe("board-link parseSshAddress", () => {
|
||||
it("完整 user@host:port", () => {
|
||||
const t = parseSshAddress("root@192.168.1.100:2222");
|
||||
expect(t.user).toBe("root");
|
||||
expect(t.host).toBe("192.168.1.100");
|
||||
expect(t.port).toBe(2222);
|
||||
});
|
||||
|
||||
it("无端口默认 22", () => {
|
||||
const t = parseSshAddress("root@board");
|
||||
expect(t.user).toBe("root");
|
||||
expect(t.host).toBe("board");
|
||||
expect(t.port).toBe(22);
|
||||
});
|
||||
|
||||
it("无 user 默认 root", () => {
|
||||
const t = parseSshAddress("192.168.1.100");
|
||||
expect(t.user).toBe("root");
|
||||
expect(t.host).toBe("192.168.1.100");
|
||||
expect(t.port).toBe(22);
|
||||
});
|
||||
|
||||
it("空字符串安全返回默认值", () => {
|
||||
const t = parseSshAddress("");
|
||||
expect(t.user).toBe("root");
|
||||
expect(t.port).toBe(22);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// buildSshArgs — SSH 命令拼接
|
||||
// ============================================================================
|
||||
|
||||
describe("board-link buildSshArgs — SSH 命令拼接", () => {
|
||||
it("非默认端口加 -p", () => {
|
||||
const board = sshBoard("x5", "root@192.168.1.100:2222");
|
||||
const args = buildSshArgs(board, "ls", ["-la", "/tmp"]);
|
||||
expect(args).toEqual(["-p", "2222", "root@192.168.1.100", "ls", "-la", "/tmp"]);
|
||||
});
|
||||
|
||||
it("默认端口 22 不加 -p(减少参数噪声)", () => {
|
||||
const board = sshBoard("x5", "root@192.168.1.100:22");
|
||||
const args = buildSshArgs(board, "dmesg", ["|", "tail"]);
|
||||
expect(args).toEqual(["root@192.168.1.100", "dmesg", "|", "tail"]);
|
||||
expect(args).not.toContain("-p");
|
||||
});
|
||||
|
||||
it("无参数命令也能拼接", () => {
|
||||
const board = sshBoard("x5", "root@192.168.1.100:2222");
|
||||
const args = buildSshArgs(board, "true", []);
|
||||
expect(args).toEqual(["-p", "2222", "root@192.168.1.100", "true"]);
|
||||
});
|
||||
|
||||
it("无 user 的地址默认 root@", () => {
|
||||
const board = sshBoard("x5", "192.168.1.100:2222");
|
||||
const args = buildSshArgs(board, "pwd", []);
|
||||
expect(args[0]).toBe("-p");
|
||||
expect(args[1]).toBe("2222");
|
||||
expect(args[2]).toBe("root@192.168.1.100");
|
||||
expect(args[3]).toBe("pwd");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// parseSerialAddress
|
||||
// ============================================================================
|
||||
|
||||
describe("board-link parseSerialAddress", () => {
|
||||
it("完整 /dev/ttyUSB0@115200", () => {
|
||||
const t = parseSerialAddress("/dev/ttyUSB0@115200");
|
||||
expect(t.dev).toBe("/dev/ttyUSB0");
|
||||
expect(t.baudrate).toBe(115200);
|
||||
});
|
||||
|
||||
it("无 baudrate 默认 115200", () => {
|
||||
const t = parseSerialAddress("/dev/ttyUSB0");
|
||||
expect(t.dev).toBe("/dev/ttyUSB0");
|
||||
expect(t.baudrate).toBe(115200);
|
||||
});
|
||||
|
||||
it("自定义 baudrate", () => {
|
||||
const t = parseSerialAddress("/dev/ttyACM0@9600");
|
||||
expect(t.dev).toBe("/dev/ttyACM0");
|
||||
expect(t.baudrate).toBe(9600);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// makeExec — 按板类型产出 ExecFn
|
||||
// ============================================================================
|
||||
|
||||
describe("board-link makeExec", () => {
|
||||
it('ssh: calls underlying("ssh", sshArgs, opts)', async () => {
|
||||
const mock = makeMockExec({ stdout: "/tmp\n", exitCode: 0 });
|
||||
const board = sshBoard("x5", "root@192.168.1.100:2222");
|
||||
const { exec, transport, isStub } = makeExec(board, mock);
|
||||
|
||||
const result = await exec("pwd", [], { timeout: 5000 });
|
||||
|
||||
expect(result.exitCode).toBe(0);
|
||||
expect(result.stdout).toBe("/tmp\n");
|
||||
expect(isStub).toBe(false);
|
||||
expect(transport).toBe("ssh:root@192.168.1.100:2222");
|
||||
// 验证 mock 被调时 command="ssh" 且 args 含 ssh 拼接
|
||||
const call = mock.mock.calls[0];
|
||||
expect(call?.[0]).toBe("ssh");
|
||||
const callArgs = call?.[1] as string[];
|
||||
expect(callArgs).toEqual(["-p", "2222", "root@192.168.1.100", "pwd"]);
|
||||
});
|
||||
|
||||
it("ssh: opts 透传到 underlying", async () => {
|
||||
const mock = makeMockExec();
|
||||
const board = sshBoard("x5", "root@board");
|
||||
const { exec } = makeExec(board, mock);
|
||||
const opts = { timeout: 30000, env: { FOO: "bar" } };
|
||||
await exec("ls", ["-la"], opts);
|
||||
const call = mock.mock.calls[0];
|
||||
expect(call?.[2]).toBe(opts);
|
||||
});
|
||||
|
||||
it("ssh: 默认端口 22 不加 -p", async () => {
|
||||
const mock = makeMockExec();
|
||||
const board = sshBoard("x5", "root@192.168.1.100:22");
|
||||
const { exec } = makeExec(board, mock);
|
||||
await exec("dmesg", []);
|
||||
const callArgs = mock.mock.calls[0]?.[1] as string[];
|
||||
expect(callArgs).not.toContain("-p");
|
||||
expect(callArgs).toEqual(["root@192.168.1.100", "dmesg"]);
|
||||
});
|
||||
|
||||
it("serial: 返回 stub,isStub=true,不调 underlying", async () => {
|
||||
const mock = makeMockExec();
|
||||
const board: BoardSpec = {
|
||||
id: "serial-board",
|
||||
name: "Serial Board",
|
||||
link: "serial",
|
||||
address: "/dev/ttyUSB0@115200",
|
||||
fingerprint: computeFingerprint("serial", "/dev/ttyUSB0@115200"),
|
||||
};
|
||||
const { exec, transport, isStub } = makeExec(board, mock);
|
||||
|
||||
const result = await exec("ls", []);
|
||||
|
||||
expect(isStub).toBe(true);
|
||||
expect(transport).toBe("serial:/dev/ttyUSB0@115200");
|
||||
expect(result).toEqual(SERIAL_STUB_RESULT);
|
||||
expect(mock.mock.calls).toHaveLength(0); // underlying 没被调
|
||||
});
|
||||
|
||||
it("local: 直透 underlying(exec === underlying)", async () => {
|
||||
const mock = makeMockExec({ stdout: "hello\n", exitCode: 0 });
|
||||
const board: BoardSpec = {
|
||||
id: "local",
|
||||
name: "Local",
|
||||
link: "local",
|
||||
address: "",
|
||||
fingerprint: computeFingerprint("local", ""),
|
||||
};
|
||||
const { exec, transport, isStub } = makeExec(board, mock);
|
||||
|
||||
const result = await exec("echo", ["hello"]);
|
||||
|
||||
expect(result.stdout).toBe("hello\n");
|
||||
expect(isStub).toBe(false);
|
||||
expect(transport).toBe("local");
|
||||
// local 直透:command/args 原样传给 underlying
|
||||
const call = mock.mock.calls[0];
|
||||
expect(call?.[0]).toBe("echo");
|
||||
expect(call?.[1]).toEqual(["hello"]);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// healthCheck
|
||||
// ============================================================================
|
||||
|
||||
describe("board-link healthCheck", () => {
|
||||
it("exit 0 → alive (true)", async () => {
|
||||
const mock = makeMockExec({ exitCode: 0 });
|
||||
// local board: exec 直透 underlying,mock 能直接看到探活命令
|
||||
const board: BoardSpec = {
|
||||
id: "local",
|
||||
name: "Local",
|
||||
link: "local",
|
||||
address: "",
|
||||
fingerprint: computeFingerprint("local", ""),
|
||||
};
|
||||
const { exec } = makeExec(board, mock);
|
||||
const alive = await healthCheck(board, exec);
|
||||
expect(alive).toBe(true);
|
||||
// 验证探活命令是 "true"
|
||||
expect(mock.mock.calls[0]?.[0]).toBe("true");
|
||||
});
|
||||
|
||||
it("非 0 exit → dead (false)", async () => {
|
||||
const mock = makeMockExec({ exitCode: 1 });
|
||||
const board: BoardSpec = {
|
||||
id: "local",
|
||||
name: "Local",
|
||||
link: "local",
|
||||
address: "",
|
||||
fingerprint: computeFingerprint("local", ""),
|
||||
};
|
||||
const { exec } = makeExec(board, mock);
|
||||
const alive = await healthCheck(board, exec);
|
||||
expect(alive).toBe(false);
|
||||
});
|
||||
|
||||
it("exec 抛异常 → dead (false)(fail-closed)", async () => {
|
||||
const throwingExec: ExecFn = vi.fn(async () => {
|
||||
throw new Error("connection refused");
|
||||
}) as unknown as ExecFn;
|
||||
const board = sshBoard("x5", "root@192.168.1.100:22");
|
||||
const alive = await healthCheck(board, throwingExec);
|
||||
expect(alive).toBe(false);
|
||||
});
|
||||
|
||||
it("自定义探活命令", async () => {
|
||||
const mock = makeMockExec({ exitCode: 0 });
|
||||
const board: BoardSpec = {
|
||||
id: "local",
|
||||
name: "Local",
|
||||
link: "local",
|
||||
address: "",
|
||||
fingerprint: computeFingerprint("local", ""),
|
||||
};
|
||||
const { exec } = makeExec(board, mock);
|
||||
const alive = await healthCheck(board, exec, { probeCommand: "echo ok" });
|
||||
expect(alive).toBe(true);
|
||||
expect(mock.mock.calls[0]?.[0]).toBe("echo ok");
|
||||
});
|
||||
|
||||
it("timeout 透传到 exec opts", async () => {
|
||||
const mock = makeMockExec({ exitCode: 0 });
|
||||
const board: BoardSpec = {
|
||||
id: "local",
|
||||
name: "Local",
|
||||
link: "local",
|
||||
address: "",
|
||||
fingerprint: computeFingerprint("local", ""),
|
||||
};
|
||||
const { exec } = makeExec(board, mock);
|
||||
await healthCheck(board, exec, { timeout: 5000 });
|
||||
const callOpts = mock.mock.calls[0]?.[2] as { timeout?: number };
|
||||
expect(callOpts?.timeout).toBe(5000);
|
||||
});
|
||||
|
||||
it("ssh board: 探活命令经 ssh 包装(mock 收到 ssh + args 含 true)", async () => {
|
||||
const mock = makeMockExec({ exitCode: 0 });
|
||||
const board = sshBoard("x5", "root@192.168.1.100:2222");
|
||||
const { exec } = makeExec(board, mock);
|
||||
const alive = await healthCheck(board, exec);
|
||||
expect(alive).toBe(true);
|
||||
// ssh 包装:underlying 收到 "ssh" + 拼接的 args
|
||||
expect(mock.mock.calls[0]?.[0]).toBe("ssh");
|
||||
const sshArgs = mock.mock.calls[0]?.[1] as string[];
|
||||
expect(sshArgs).toContain("true");
|
||||
expect(sshArgs).toContain("root@192.168.1.100");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// computeFingerprint
|
||||
// ============================================================================
|
||||
|
||||
describe("board-link computeFingerprint", () => {
|
||||
it("同 link+address → 同 fingerprint", () => {
|
||||
const a = computeFingerprint("ssh", "root@192.168.1.100:22");
|
||||
const b = computeFingerprint("ssh", "root@192.168.1.100:22");
|
||||
expect(a).toBe(b);
|
||||
});
|
||||
|
||||
it("不同 address → 不同 fingerprint", () => {
|
||||
const a = computeFingerprint("ssh", "root@192.168.1.100:22");
|
||||
const b = computeFingerprint("ssh", "root@192.168.1.101:22");
|
||||
expect(a).not.toBe(b);
|
||||
});
|
||||
|
||||
it("不同 link → 不同 fingerprint(即使 address 相同)", () => {
|
||||
const a = computeFingerprint("ssh", "board");
|
||||
const b = computeFingerprint("serial", "board");
|
||||
expect(a).not.toBe(b);
|
||||
});
|
||||
|
||||
it("address 首尾空白被 trim", () => {
|
||||
const a = computeFingerprint("ssh", " root@board ");
|
||||
const b = computeFingerprint("ssh", "root@board");
|
||||
expect(a).toBe(b);
|
||||
});
|
||||
});
|
||||
440
tests/build-tracker.test.ts
Normal file
440
tests/build-tracker.test.ts
Normal file
@ -0,0 +1,440 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
BuildTracker,
|
||||
OutputAccumulator,
|
||||
planBuild,
|
||||
shouldSkip,
|
||||
type SpawnFn,
|
||||
type SpawnedProcess,
|
||||
} from "../src/extensions/build-tracker.js";
|
||||
|
||||
// ============================================================================
|
||||
// 测试用 Fake 进程:可控的 stdout/stderr/close 注入。
|
||||
// ============================================================================
|
||||
|
||||
class FakeProcess implements SpawnedProcess {
|
||||
pid: number;
|
||||
private stdoutHandlers: Array<(data: string) => void> = [];
|
||||
private stderrHandlers: Array<(data: string) => void> = [];
|
||||
private closeHandlers: Array<(code: number | null, signal?: string) => void> = [];
|
||||
|
||||
constructor(pid: number) {
|
||||
this.pid = pid;
|
||||
}
|
||||
onStdout(h: (data: string) => void): void {
|
||||
this.stdoutHandlers.push(h);
|
||||
}
|
||||
onStderr(h: (data: string) => void): void {
|
||||
this.stderrHandlers.push(h);
|
||||
}
|
||||
onClose(h: (code: number | null, signal?: string) => void): void {
|
||||
this.closeHandlers.push(h);
|
||||
}
|
||||
/** 测试驱动:模拟进程输出。 */
|
||||
emitStdout(data: string): void {
|
||||
for (const h of this.stdoutHandlers) h(data);
|
||||
}
|
||||
emitStderr(data: string): void {
|
||||
for (const h of this.stderrHandlers) h(data);
|
||||
}
|
||||
/** 测试驱动:模拟进程结束。 */
|
||||
emitClose(code: number | null, signal?: string): void {
|
||||
for (const h of this.closeHandlers) h(code, signal);
|
||||
}
|
||||
}
|
||||
|
||||
function makeSpawnFn(proc: FakeProcess): SpawnFn {
|
||||
return () => proc;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// planBuild — 构建命令规划
|
||||
// ============================================================================
|
||||
|
||||
describe("build-tracker planBuild — 构建命令规划", () => {
|
||||
it("buildroot → make all", () => {
|
||||
const p = planBuild("buildroot", "all");
|
||||
expect(p.command).toBe("make");
|
||||
expect(p.args).toEqual(["all"]);
|
||||
});
|
||||
|
||||
it("buildroot 默认 target=all", () => {
|
||||
const p = planBuild("buildroot");
|
||||
expect(p.args).toEqual(["all"]);
|
||||
});
|
||||
|
||||
it("yocto → bitbake core-image-minimal", () => {
|
||||
const p = planBuild("yocto");
|
||||
expect(p.command).toBe("bitbake");
|
||||
expect(p.args).toEqual(["core-image-minimal"]);
|
||||
});
|
||||
|
||||
it("yocto 自定义 target", () => {
|
||||
const p = planBuild("yocto", "linux-rdk");
|
||||
expect(p.args).toEqual(["linux-rdk"]);
|
||||
});
|
||||
|
||||
it("cmake → cmake --build . --target all", () => {
|
||||
const p = planBuild("cmake");
|
||||
expect(p.command).toBe("cmake");
|
||||
expect(p.args).toEqual(["--build", ".", "--target", "all"]);
|
||||
});
|
||||
|
||||
it("cmake 带 target", () => {
|
||||
const p = planBuild("cmake", "firmware");
|
||||
expect(p.args).toEqual(["--build", ".", "--target", "firmware"]);
|
||||
});
|
||||
|
||||
it("kconfig → make defconfig", () => {
|
||||
const p = planBuild("kconfig");
|
||||
expect(p.command).toBe("make");
|
||||
expect(p.args).toEqual(["defconfig"]);
|
||||
});
|
||||
|
||||
it("buildDir 透传到 cwd", () => {
|
||||
const p = planBuild("cmake", "all", { buildDir: "/build/root" });
|
||||
expect(p.cwd).toBe("/build/root");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// shouldSkip — 增量感知 fail-closed
|
||||
// ============================================================================
|
||||
|
||||
describe("build-tracker shouldSkip — 增量跳过(fail-closed)", () => {
|
||||
it("源码未变(srcMtime <= lastBuildMtime)→ 跳过", () => {
|
||||
expect(shouldSkip(1000, 2000)).toBe(true);
|
||||
});
|
||||
|
||||
it("源码在上次构建后变了(srcMtime > lastBuildMtime)→ 不跳过", () => {
|
||||
expect(shouldSkip(3000, 2000)).toBe(false);
|
||||
});
|
||||
|
||||
it("无上次构建(lastBuildMtime=0)→ 不跳过(fail-closed)", () => {
|
||||
expect(shouldSkip(1000, 0)).toBe(false);
|
||||
});
|
||||
|
||||
it("源码与上次构建同时戳 → 跳过(边界 ==)", () => {
|
||||
expect(shouldSkip(2000, 2000)).toBe(true);
|
||||
});
|
||||
|
||||
it("无上次构建且负数 mtime → 不跳过", () => {
|
||||
expect(shouldSkip(500, -1)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// OutputAccumulator — 有界缓冲
|
||||
// ============================================================================
|
||||
|
||||
describe("build-tracker OutputAccumulator — 简化缓冲", () => {
|
||||
it("append 多行后 tail 返回尾部 N 行", () => {
|
||||
const acc = new OutputAccumulator("/tmp/b.log");
|
||||
acc.append("line1\nline2\nline3\n");
|
||||
expect(acc.tail(2)).toEqual(["line2", "line3"]);
|
||||
});
|
||||
|
||||
it("tail(0) 返回空数组", () => {
|
||||
const acc = new OutputAccumulator("/tmp/b.log");
|
||||
acc.append("a\nb\n");
|
||||
expect(acc.tail(0)).toEqual([]);
|
||||
});
|
||||
|
||||
it("tail 超过已有行数 → 返回全部", () => {
|
||||
const acc = new OutputAccumulator("/tmp/b.log");
|
||||
acc.append("only1\nonly2\n");
|
||||
expect(acc.tail(50)).toEqual(["only1", "only2"]);
|
||||
});
|
||||
|
||||
it("跨 chunk 半行残片拼接", () => {
|
||||
const acc = new OutputAccumulator("/tmp/b.log");
|
||||
acc.append("half-"); // 无换行 → 残片
|
||||
acc.append("line\nsecond\n"); // 拼成 half-line
|
||||
expect(acc.allLines()).toEqual(["half-line", "second"]);
|
||||
});
|
||||
|
||||
it("stderr 与 stdout 混合追加", () => {
|
||||
const acc = new OutputAccumulator("/tmp/b.log");
|
||||
acc.append("stdout-line\n");
|
||||
acc.append("stderr-line\n");
|
||||
expect(acc.lineCount).toBe(2);
|
||||
expect(acc.tail(2)).toEqual(["stdout-line", "stderr-line"]);
|
||||
});
|
||||
|
||||
it("tempPath 暴露给扩展层", () => {
|
||||
const acc = new OutputAccumulator("/tmp/build-1.log");
|
||||
expect(acc.tempPath).toBe("/tmp/build-1.log");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// BuildTracker — start / status
|
||||
// ============================================================================
|
||||
|
||||
describe("build-tracker BuildTracker — start/status", () => {
|
||||
it("start 立即返回 buildId+pid+logFile+running,不阻塞", () => {
|
||||
const proc = new FakeProcess(4242);
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc), {
|
||||
clock: () => 1000,
|
||||
});
|
||||
const res = tracker.start("cmake", "all");
|
||||
expect(res.status).toBe("running");
|
||||
expect(res.pid).toBe(4242);
|
||||
expect(res.buildId).toMatch(/^build-\d+$/);
|
||||
expect(res.logFile).toContain(res.buildId);
|
||||
expect(res.skipped).toBeUndefined();
|
||||
// 进程未结束 → 仍 running
|
||||
expect(tracker.status(res.buildId)?.status).toBe("running");
|
||||
});
|
||||
|
||||
it("进程 close code=0 → status=done,exitCode=0", () => {
|
||||
const proc = new FakeProcess(1);
|
||||
let t = 1000;
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc), { clock: () => t });
|
||||
const res = tracker.start("buildroot");
|
||||
t = 5000;
|
||||
proc.emitClose(0);
|
||||
const st = tracker.status(res.buildId);
|
||||
expect(st?.status).toBe("done");
|
||||
expect(st?.exitCode).toBe(0);
|
||||
expect(st?.durationMs).toBe(4000);
|
||||
});
|
||||
|
||||
it("进程 close code!=0 → status=failed", () => {
|
||||
const proc = new FakeProcess(2);
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc));
|
||||
const res = tracker.start("make", "all");
|
||||
proc.emitClose(2);
|
||||
expect(tracker.status(res.buildId)?.status).toBe("failed");
|
||||
expect(tracker.status(res.buildId)?.exitCode).toBe(2);
|
||||
});
|
||||
|
||||
it("进程被信号杀(code=null)→ status=failed", () => {
|
||||
const proc = new FakeProcess(3);
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc));
|
||||
const res = tracker.start("yocto", "core-image-minimal");
|
||||
proc.emitClose(null, "SIGKILL");
|
||||
const st = tracker.status(res.buildId);
|
||||
expect(st?.status).toBe("failed");
|
||||
expect(st?.exitCode).toBe(-1);
|
||||
expect(st?.signal).toBe("SIGKILL");
|
||||
});
|
||||
|
||||
it("status 未知 buildId → null(fail-closed)", () => {
|
||||
const tracker = new BuildTracker(makeSpawnFn(new FakeProcess(0)));
|
||||
expect(tracker.status("nonexistent")).toBeNull();
|
||||
});
|
||||
|
||||
it("buildId 单调递增", () => {
|
||||
const proc = new FakeProcess(10);
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc));
|
||||
const a = tracker.start("cmake");
|
||||
const b = tracker.start("cmake");
|
||||
expect(a.buildId).not.toBe(b.buildId);
|
||||
});
|
||||
|
||||
it("running 时 durationMs = now - startedAt", () => {
|
||||
const proc = new FakeProcess(11);
|
||||
let t = 100;
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc), { clock: () => t });
|
||||
const res = tracker.start("cmake");
|
||||
t = 350;
|
||||
expect(tracker.status(res.buildId)?.durationMs).toBe(250);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// BuildTracker — tail 尾部日志
|
||||
// ============================================================================
|
||||
|
||||
describe("build-tracker BuildTracker — tail 尾部日志", () => {
|
||||
it("tail 返回尾部 N 行(stdout+stderr 混合)", () => {
|
||||
const proc = new FakeProcess(20);
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc));
|
||||
const res = tracker.start("cmake");
|
||||
proc.emitStdout("[ 10%] Building CXX foo\n[ 50%] Building CXX bar\n");
|
||||
proc.emitStderr("warning: unused variable\n");
|
||||
proc.emitClose(0);
|
||||
const tail = tracker.tail(res.buildId, 2);
|
||||
expect(tail).toEqual(["[ 50%] Building CXX bar", "warning: unused variable"]);
|
||||
});
|
||||
|
||||
it("tail 默认 50 行", () => {
|
||||
const proc = new FakeProcess(21);
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc));
|
||||
const res = tracker.start("make");
|
||||
// 60 行
|
||||
let out = "";
|
||||
for (let i = 0; i < 60; i++) out += `line${i}\n`;
|
||||
proc.emitStdout(out);
|
||||
proc.emitClose(0);
|
||||
const tail = tracker.tail(res.buildId);
|
||||
expect(tail).toHaveLength(50);
|
||||
expect(tail[0]).toBe("line10");
|
||||
expect(tail[49]).toBe("line59");
|
||||
});
|
||||
|
||||
it("tail 未知 buildId → 空数组(fail-closed)", () => {
|
||||
const tracker = new BuildTracker(makeSpawnFn(new FakeProcess(0)));
|
||||
expect(tracker.tail("nope")).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// BuildTracker — start 增量跳过(注入 mtime provider)
|
||||
// ============================================================================
|
||||
|
||||
describe("build-tracker BuildTracker — start 增量跳过", () => {
|
||||
it("源码未变 + incremental:true + clean:false → skipped,不 spawn", () => {
|
||||
const proc = new FakeProcess(30);
|
||||
const spawnCalled = { n: 0 };
|
||||
const spawnFn: SpawnFn = () => {
|
||||
spawnCalled.n++;
|
||||
return proc;
|
||||
};
|
||||
const tracker = new BuildTracker(spawnFn, {
|
||||
getSrcMtime: () => 1000,
|
||||
getLastBuildMtime: () => 2000,
|
||||
});
|
||||
const res = tracker.start("cmake", "all", {
|
||||
incremental: true,
|
||||
clean: false,
|
||||
buildDir: "/build",
|
||||
});
|
||||
expect(res.skipped).toBe(true);
|
||||
expect(res.status).toBe("done");
|
||||
expect(res.pid).toBe(0);
|
||||
expect(res.skipReason).toContain("No source changes");
|
||||
expect(spawnCalled.n).toBe(0);
|
||||
});
|
||||
|
||||
it("源码变了 → 不跳过,正常 spawn", () => {
|
||||
const proc = new FakeProcess(31);
|
||||
const spawnCalled = { n: 0 };
|
||||
const spawnFn: SpawnFn = () => {
|
||||
spawnCalled.n++;
|
||||
return proc;
|
||||
};
|
||||
const tracker = new BuildTracker(spawnFn, {
|
||||
getSrcMtime: () => 3000,
|
||||
getLastBuildMtime: () => 2000,
|
||||
});
|
||||
const res = tracker.start("cmake", "all", {
|
||||
incremental: true,
|
||||
buildDir: "/build",
|
||||
});
|
||||
expect(res.skipped).toBeUndefined();
|
||||
expect(res.status).toBe("running");
|
||||
expect(spawnCalled.n).toBe(1);
|
||||
});
|
||||
|
||||
it("clean:true → 绝不跳过(即使源码未变)", () => {
|
||||
const proc = new FakeProcess(32);
|
||||
const spawnCalled = { n: 0 };
|
||||
const spawnFn: SpawnFn = () => {
|
||||
spawnCalled.n++;
|
||||
return proc;
|
||||
};
|
||||
const tracker = new BuildTracker(spawnFn, {
|
||||
getSrcMtime: () => 1000,
|
||||
getLastBuildMtime: () => 2000,
|
||||
});
|
||||
const res = tracker.start("cmake", "all", {
|
||||
incremental: true,
|
||||
clean: true,
|
||||
buildDir: "/build",
|
||||
});
|
||||
expect(res.skipped).toBeUndefined();
|
||||
expect(res.status).toBe("running");
|
||||
expect(spawnCalled.n).toBe(1);
|
||||
});
|
||||
|
||||
it("incremental:false → 绝不跳过(禁用增量感知)", () => {
|
||||
const proc = new FakeProcess(33);
|
||||
const spawnCalled = { n: 0 };
|
||||
const spawnFn: SpawnFn = () => {
|
||||
spawnCalled.n++;
|
||||
return proc;
|
||||
};
|
||||
const tracker = new BuildTracker(spawnFn, {
|
||||
getSrcMtime: () => 1000,
|
||||
getLastBuildMtime: () => 2000,
|
||||
});
|
||||
const res = tracker.start("cmake", "all", {
|
||||
incremental: false,
|
||||
buildDir: "/build",
|
||||
});
|
||||
expect(res.skipped).toBeUndefined();
|
||||
expect(spawnCalled.n).toBe(1);
|
||||
});
|
||||
|
||||
it("无 buildDir → 不判定跳过(fail-closed,正常 spawn)", () => {
|
||||
const proc = new FakeProcess(34);
|
||||
const spawnCalled = { n: 0 };
|
||||
const spawnFn: SpawnFn = () => {
|
||||
spawnCalled.n++;
|
||||
return proc;
|
||||
};
|
||||
const tracker = new BuildTracker(spawnFn, {
|
||||
getSrcMtime: () => 1000,
|
||||
getLastBuildMtime: () => 2000,
|
||||
});
|
||||
const res = tracker.start("cmake", "all", { incremental: true });
|
||||
expect(res.skipped).toBeUndefined();
|
||||
expect(spawnCalled.n).toBe(1);
|
||||
});
|
||||
|
||||
it("源码 mtime 未知(getSrcMtime 返回 0)→ fail-closed 不跳过", () => {
|
||||
const proc = new FakeProcess(35);
|
||||
const spawnCalled = { n: 0 };
|
||||
const spawnFn: SpawnFn = () => {
|
||||
spawnCalled.n++;
|
||||
return proc;
|
||||
};
|
||||
const tracker = new BuildTracker(spawnFn, {
|
||||
getSrcMtime: () => 0,
|
||||
getLastBuildMtime: () => 2000,
|
||||
});
|
||||
const res = tracker.start("cmake", "all", {
|
||||
incremental: true,
|
||||
clean: false,
|
||||
buildDir: "/build",
|
||||
});
|
||||
expect(res.skipped).toBeUndefined();
|
||||
expect(res.status).toBe("running");
|
||||
expect(spawnCalled.n).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// BuildTracker — 辅助方法
|
||||
// ============================================================================
|
||||
|
||||
describe("build-tracker BuildTracker — accumulatorOf / listBuilds", () => {
|
||||
it("accumulatorOf 返回对应构建的累积器", () => {
|
||||
const proc = new FakeProcess(40);
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc));
|
||||
const res = tracker.start("cmake");
|
||||
proc.emitStdout("hello\n");
|
||||
const acc = tracker.accumulatorOf(res.buildId);
|
||||
expect(acc).not.toBeNull();
|
||||
expect(acc?.lineCount).toBe(1);
|
||||
expect(acc?.allLines()).toEqual(["hello"]);
|
||||
});
|
||||
|
||||
it("accumulatorOf 未知 buildId → null", () => {
|
||||
const tracker = new BuildTracker(makeSpawnFn(new FakeProcess(0)));
|
||||
expect(tracker.accumulatorOf("nope")).toBeNull();
|
||||
});
|
||||
|
||||
it("listBuilds 返回所有已知 buildId", () => {
|
||||
const proc = new FakeProcess(41);
|
||||
const tracker = new BuildTracker(makeSpawnFn(proc));
|
||||
const a = tracker.start("cmake");
|
||||
const b = tracker.start("make");
|
||||
const ids = tracker.listBuilds();
|
||||
expect(ids).toContain(a.buildId);
|
||||
expect(ids).toContain(b.buildId);
|
||||
expect(ids).toHaveLength(2);
|
||||
});
|
||||
});
|
||||
444
tests/cross-compile.test.ts
Normal file
444
tests/cross-compile.test.ts
Normal file
@ -0,0 +1,444 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
resolveToolchain,
|
||||
generateCmakeToolchain,
|
||||
detectToolchain,
|
||||
detectHostGcc,
|
||||
parseFileOutput,
|
||||
verifyArtifact,
|
||||
ToolchainSession,
|
||||
TOOLCHAIN_REGISTRY,
|
||||
KNOWN_TRIPLES,
|
||||
isKnownTriple,
|
||||
normalizeTripleFromEnv,
|
||||
type ToolchainTriple,
|
||||
} from "../src/extensions/cross-compile.js";
|
||||
import type { ExecFn, ExecResult } from "../src/shared/types.js";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// mock ExecFn 工厂:按 (command, args) 匹配返回结果,不匹配返回 not-found
|
||||
// ---------------------------------------------------------------------------
|
||||
function makeMockExec(
|
||||
table: Array<{
|
||||
match: (cmd: string, args: string[]) => boolean;
|
||||
result: ExecResult;
|
||||
}>,
|
||||
): ExecFn {
|
||||
return async (cmd, args) => {
|
||||
for (const row of table) {
|
||||
if (row.match(cmd, args)) return row.result;
|
||||
}
|
||||
return { stdout: "", stderr: "command not found", exitCode: 127 };
|
||||
};
|
||||
}
|
||||
|
||||
const ok = (stdout: string): ExecResult => ({ stdout, stderr: "", exitCode: 0 });
|
||||
const fail = (stderr: string, code = 1): ExecResult => ({
|
||||
stdout: "",
|
||||
stderr,
|
||||
exitCode: code,
|
||||
});
|
||||
|
||||
// ===========================================================================
|
||||
// resolveToolchain
|
||||
// ===========================================================================
|
||||
|
||||
describe("cross-compile resolveToolchain — aarch64-linux-gnu", () => {
|
||||
it("前缀是 aarch64-linux-gnu-", () => {
|
||||
const tc = resolveToolchain("aarch64-linux-gnu");
|
||||
expect(tc.prefix).toBe("aarch64-linux-gnu-");
|
||||
});
|
||||
|
||||
it("gcc/cxx/objcopy 含 triple 前缀", () => {
|
||||
const tc = resolveToolchain("aarch64-linux-gnu");
|
||||
expect(tc.gcc).toBe("aarch64-linux-gnu-gcc");
|
||||
expect(tc.cxx).toBe("aarch64-linux-gnu-g++");
|
||||
expect(tc.objcopy).toBe("aarch64-linux-gnu-objcopy");
|
||||
});
|
||||
|
||||
it("cmakeSystemName=Linux, cmakeSystemProcessor=aarch64, elfArch=aarch64", () => {
|
||||
const tc = resolveToolchain("aarch64-linux-gnu");
|
||||
expect(tc.cmakeSystemName).toBe("Linux");
|
||||
expect(tc.cmakeSystemProcessor).toBe("aarch64");
|
||||
expect(tc.elfArch).toBe("aarch64");
|
||||
});
|
||||
});
|
||||
|
||||
describe("cross-compile resolveToolchain — arm-none-eabi (bare metal)", () => {
|
||||
it("前缀 + 编译器名正确", () => {
|
||||
const tc = resolveToolchain("arm-none-eabi");
|
||||
expect(tc.prefix).toBe("arm-none-eabi-");
|
||||
expect(tc.gcc).toBe("arm-none-eabi-gcc");
|
||||
expect(tc.cxx).toBe("arm-none-eabi-g++");
|
||||
expect(tc.objcopy).toBe("arm-none-eabi-objcopy");
|
||||
});
|
||||
|
||||
it("cmakeSystemName=Generic (bare metal 无 OS)", () => {
|
||||
const tc = resolveToolchain("arm-none-eabi");
|
||||
expect(tc.cmakeSystemName).toBe("Generic");
|
||||
expect(tc.cmakeSystemProcessor).toBe("arm");
|
||||
});
|
||||
});
|
||||
|
||||
describe("cross-compile resolveToolchain — 边界 (fail-closed)", () => {
|
||||
it("未知 triple 抛错", () => {
|
||||
expect(() => resolveToolchain("x86_64-linux-gnu" as ToolchainTriple)).toThrow(
|
||||
/unknown toolchain triple/i,
|
||||
);
|
||||
});
|
||||
|
||||
it("注册表至少含 aarch64 + arm-none-eabi", () => {
|
||||
expect(Object.keys(TOOLCHAIN_REGISTRY)).toContain("aarch64-linux-gnu");
|
||||
expect(Object.keys(TOOLCHAIN_REGISTRY)).toContain("arm-none-eabi");
|
||||
});
|
||||
|
||||
it("返回的对象是独立副本(改不影响注册表)", () => {
|
||||
const a = resolveToolchain("aarch64-linux-gnu");
|
||||
const b = resolveToolchain("aarch64-linux-gnu");
|
||||
expect(a).not.toBe(b);
|
||||
expect(a.gcc).toBe(b.gcc);
|
||||
});
|
||||
});
|
||||
|
||||
// ===========================================================================
|
||||
// triple 校验 / env 规整(纯逻辑)
|
||||
// ===========================================================================
|
||||
|
||||
describe("cross-compile isKnownTriple / normalizeTripleFromEnv", () => {
|
||||
it("已知 triple 返回 true 并收窄类型", () => {
|
||||
const v: string = "aarch64-linux-gnu";
|
||||
expect(isKnownTriple(v)).toBe(true);
|
||||
});
|
||||
|
||||
it("未知 triple 返回 false", () => {
|
||||
expect(isKnownTriple("x86_64-linux-gnu")).toBe(false);
|
||||
});
|
||||
|
||||
it("normalizeTripleFromEnv 已知值原样返回", () => {
|
||||
expect(normalizeTripleFromEnv("arm-none-eabi")).toBe("arm-none-eabi");
|
||||
});
|
||||
|
||||
it("normalizeTripleFromEnv 空/未知返回 null (fail-closed)", () => {
|
||||
expect(normalizeTripleFromEnv(undefined)).toBeNull();
|
||||
expect(normalizeTripleFromEnv("")).toBeNull();
|
||||
expect(normalizeTripleFromEnv("x86_64-linux-gnu")).toBeNull();
|
||||
});
|
||||
|
||||
it("KNOWN_TRIPLES 含四个 triple", () => {
|
||||
expect(KNOWN_TRIPLES).toHaveLength(4);
|
||||
expect(KNOWN_TRIPLES).toContain("riscv64-unknown-elf");
|
||||
});
|
||||
});
|
||||
|
||||
// ===========================================================================
|
||||
// generateCmakeToolchain
|
||||
// ===========================================================================
|
||||
|
||||
describe("cross-compile generateCmakeToolchain", () => {
|
||||
it("含 CMAKE_C_COMPILER 且值含 triple 前缀", () => {
|
||||
const tc = resolveToolchain("aarch64-linux-gnu");
|
||||
const cmake = generateCmakeToolchain(tc);
|
||||
expect(cmake).toContain("CMAKE_C_COMPILER");
|
||||
expect(cmake).toContain("aarch64-linux-gnu-gcc");
|
||||
});
|
||||
|
||||
it("含 CMAKE_CXX_COMPILER 和 CMAKE_OBJCOPY", () => {
|
||||
const tc = resolveToolchain("aarch64-linux-gnu");
|
||||
const cmake = generateCmakeToolchain(tc);
|
||||
expect(cmake).toContain("CMAKE_CXX_COMPILER");
|
||||
expect(cmake).toContain("aarch64-linux-gnu-g++");
|
||||
expect(cmake).toContain("CMAKE_OBJCOPY");
|
||||
expect(cmake).toContain("aarch64-linux-gnu-objcopy");
|
||||
});
|
||||
|
||||
it("CMAKE_SYSTEM_NAME=Linux (aarch64) / Generic (arm-none-eabi)", () => {
|
||||
const aarch = generateCmakeToolchain(resolveToolchain("aarch64-linux-gnu"));
|
||||
expect(aarch).toMatch(/CMAKE_SYSTEM_NAME\s+Linux/);
|
||||
|
||||
const arm = generateCmakeToolchain(resolveToolchain("arm-none-eabi"));
|
||||
expect(arm).toMatch(/CMAKE_SYSTEM_NAME\s+Generic/);
|
||||
});
|
||||
|
||||
it("含 CMAKE_SYSTEM_PROCESSOR", () => {
|
||||
const tc = resolveToolchain("aarch64-linux-gnu");
|
||||
const cmake = generateCmakeToolchain(tc);
|
||||
expect(cmake).toContain("CMAKE_SYSTEM_PROCESSOR");
|
||||
expect(cmake).toContain("aarch64");
|
||||
});
|
||||
|
||||
it("有 sysroot 时生成 CMAKE_SYSROOT + FIND_ROOT_PATH", () => {
|
||||
const tc = resolveToolchain("aarch64-linux-gnu");
|
||||
const sysroot = "/usr/aarch64-linux-gnu/sysroot";
|
||||
const cmake = generateCmakeToolchain(tc, sysroot);
|
||||
expect(cmake).toContain("CMAKE_SYSROOT");
|
||||
expect(cmake).toContain(sysroot);
|
||||
expect(cmake).toContain("CMAKE_FIND_ROOT_PATH");
|
||||
expect(cmake).toContain("CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY");
|
||||
expect(cmake).toContain("CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER");
|
||||
});
|
||||
|
||||
it("无 sysroot 时不生成 CMAKE_SYSROOT(bare-metal)但 FIND_ROOT_PATH_MODE 仍在", () => {
|
||||
const tc = resolveToolchain("arm-none-eabi");
|
||||
const cmake = generateCmakeToolchain(tc);
|
||||
expect(cmake).not.toContain("CMAKE_SYSROOT");
|
||||
expect(cmake).toContain("CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY");
|
||||
});
|
||||
|
||||
it("生成的文件不含 F 编号字样(域命名)", () => {
|
||||
const cmake = generateCmakeToolchain(resolveToolchain("aarch64-linux-gnu"));
|
||||
expect(cmake).not.toMatch(/\bF\d+\b/);
|
||||
});
|
||||
});
|
||||
|
||||
// ===========================================================================
|
||||
// detectToolchain (mock ExecFn)
|
||||
// ===========================================================================
|
||||
|
||||
describe("cross-compile detectToolchain — mock", () => {
|
||||
it("工具链可用时 available=true 并提取 version + sysroot", async () => {
|
||||
const exec = makeMockExec([
|
||||
{
|
||||
match: (c, a) => c === "aarch64-linux-gnu-gcc" && a.includes("--version"),
|
||||
result: ok("aarch64-linux-gnu-gcc (Debian 12.2.0) 12.2.0\nCopyright (C) 2022"),
|
||||
},
|
||||
{
|
||||
match: (c, a) => c === "aarch64-linux-gnu-gcc" && a.includes("-print-sysroot"),
|
||||
result: ok("/usr/aarch64-linux-gnu/lib/../sysroot"),
|
||||
},
|
||||
{ match: (c) => c === "which", result: ok("/usr/bin/aarch64-linux-gnu-gcc") },
|
||||
]);
|
||||
const avail = await detectToolchain(exec, "aarch64-linux-gnu");
|
||||
expect(avail.available).toBe(true);
|
||||
expect(avail.version).toContain("12.2.0");
|
||||
expect(avail.sysroot).toBe("/usr/aarch64-linux-gnu/lib/../sysroot");
|
||||
expect(avail.gccPath).toBe("/usr/bin/aarch64-linux-gnu-gcc");
|
||||
});
|
||||
|
||||
it("工具链未装时 available=false (fail-closed)", async () => {
|
||||
const exec = makeMockExec([
|
||||
{
|
||||
match: (c, a) => c === "aarch64-linux-gnu-gcc" && a.includes("--version"),
|
||||
result: fail("aarch64-linux-gnu-gcc: command not found", 127),
|
||||
},
|
||||
]);
|
||||
const avail = await detectToolchain(exec, "aarch64-linux-gnu");
|
||||
expect(avail.available).toBe(false);
|
||||
expect(avail.error).toContain("not found");
|
||||
});
|
||||
|
||||
it("sysroot 为 / 时不采纳(根目录无意义)", async () => {
|
||||
const exec = makeMockExec([
|
||||
{
|
||||
match: (c, a) => c === "arm-none-eabi-gcc" && a.includes("--version"),
|
||||
result: ok("arm-none-eabi-gcc (15:12.2) 12.2.0"),
|
||||
},
|
||||
{
|
||||
match: (c, a) => c === "arm-none-eabi-gcc" && a.includes("-print-sysroot"),
|
||||
result: ok("/"),
|
||||
},
|
||||
{ match: (c) => c === "which", result: ok("/usr/bin/arm-none-eabi-gcc") },
|
||||
]);
|
||||
const avail = await detectToolchain(exec, "arm-none-eabi");
|
||||
expect(avail.available).toBe(true);
|
||||
expect(avail.sysroot).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
// ===========================================================================
|
||||
// detectHostGcc (tool_call 钩子纯逻辑,fail-closed)
|
||||
// ===========================================================================
|
||||
|
||||
describe("cross-compile detectHostGcc — 宿主 gcc 拦截 (fail-closed)", () => {
|
||||
it("裸 gcc 被拦截", () => {
|
||||
const d = detectHostGcc("gcc main.c -o main");
|
||||
expect(d.block).toBe(true);
|
||||
expect(d.compiler).toBe("gcc");
|
||||
expect(d.reason).toContain("xcompile");
|
||||
});
|
||||
|
||||
it("裸 g++ 被拦截", () => {
|
||||
const d = detectHostGcc("g++ main.cpp -o main");
|
||||
expect(d.block).toBe(true);
|
||||
expect(d.compiler).toBe("g++");
|
||||
});
|
||||
|
||||
it("裸 cc 被拦截", () => {
|
||||
const d = detectHostGcc("cc -O2 main.c -o main");
|
||||
expect(d.block).toBe(true);
|
||||
});
|
||||
|
||||
it("aarch64-linux-gnu-gcc 不被拦截(前缀白名单)", () => {
|
||||
const d = detectHostGcc("aarch64-linux-gnu-gcc main.c -o main");
|
||||
expect(d.block).toBe(false);
|
||||
});
|
||||
|
||||
it("arm-none-eabi-g++ 不被拦截", () => {
|
||||
const d = detectHostGcc("arm-none-eabi-g++ -c main.cpp -o main.o");
|
||||
expect(d.block).toBe(false);
|
||||
});
|
||||
|
||||
it("CMAKE_C_COMPILER=gcc 透传被拦截", () => {
|
||||
const d = detectHostGcc("cmake -DCMAKE_C_COMPILER=gcc ..");
|
||||
expect(d.block).toBe(true);
|
||||
expect(d.compiler).toBe("gcc");
|
||||
});
|
||||
|
||||
it("/usr/bin/gcc 被拦截(绝对路径宿主 gcc)", () => {
|
||||
const d = detectHostGcc("/usr/bin/gcc main.c -o main");
|
||||
expect(d.block).toBe(true);
|
||||
});
|
||||
|
||||
it("安全命令不拦截", () => {
|
||||
for (const cmd of [
|
||||
"aarch64-linux-gnu-gcc -o app main.c",
|
||||
"cmake --build .",
|
||||
"make -j4",
|
||||
"ls -la",
|
||||
"cat /sys/class/gpio/gpio33/value",
|
||||
]) {
|
||||
expect(detectHostGcc(cmd).block).toBe(false);
|
||||
}
|
||||
});
|
||||
|
||||
it("空命令不拦截", () => {
|
||||
expect(detectHostGcc("").block).toBe(false);
|
||||
expect(detectHostGcc(" ").block).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// ===========================================================================
|
||||
// parseFileOutput / verifyArtifact
|
||||
// ===========================================================================
|
||||
|
||||
describe("cross-compile parseFileOutput — 架构校验", () => {
|
||||
it("x86-64 产物 vs 期望 aarch64 → mismatch", () => {
|
||||
const r = parseFileOutput(
|
||||
"main: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked",
|
||||
"aarch64",
|
||||
);
|
||||
expect(r.match).toBe(false);
|
||||
expect(r.detected).toBe("x86-64");
|
||||
expect(r.error).toContain("mismatch");
|
||||
expect(r.error).toContain("aarch64");
|
||||
expect(r.error).toContain("x86-64");
|
||||
});
|
||||
|
||||
it("aarch64 产物 vs 期望 aarch64 → match", () => {
|
||||
const r = parseFileOutput(
|
||||
"main: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV)",
|
||||
"aarch64",
|
||||
);
|
||||
expect(r.match).toBe(true);
|
||||
expect(r.detected).toBe("aarch64");
|
||||
expect(r.error).toBeUndefined();
|
||||
});
|
||||
|
||||
it("ARM bare-metal 产物 vs 期望 ARM → match", () => {
|
||||
const r = parseFileOutput(
|
||||
"firmware.elf: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV)",
|
||||
"ARM",
|
||||
);
|
||||
expect(r.match).toBe(true);
|
||||
expect(r.detected).toBe("ARM");
|
||||
});
|
||||
|
||||
it("无 ELF 字样 → 解析失败 (fail-closed)", () => {
|
||||
const r = parseFileOutput("main: data", "aarch64");
|
||||
expect(r.match).toBe(false);
|
||||
expect(r.error).toContain("could not parse");
|
||||
});
|
||||
});
|
||||
|
||||
describe("cross-compile verifyArtifact — mock ExecFn", () => {
|
||||
it("file 返回 x86-64 → mismatch", async () => {
|
||||
const exec = makeMockExec([
|
||||
{
|
||||
match: (c) => c === "file",
|
||||
result: ok("main: ELF 64-bit LSB executable, x86-64, version 1 (SYSV)"),
|
||||
},
|
||||
]);
|
||||
const r = await verifyArtifact(exec, "/tmp/main", "aarch64");
|
||||
expect(r.match).toBe(false);
|
||||
expect(r.detected).toBe("x86-64");
|
||||
});
|
||||
|
||||
it("file 命令失败 → fail-closed 报错", async () => {
|
||||
const exec = makeMockExec([
|
||||
{ match: (c) => c === "file", result: fail("file: /tmp/main: No such file", 1) },
|
||||
]);
|
||||
const r = await verifyArtifact(exec, "/tmp/main", "aarch64");
|
||||
expect(r.match).toBe(false);
|
||||
expect(r.error).toContain("file command failed");
|
||||
});
|
||||
});
|
||||
|
||||
// ===========================================================================
|
||||
// ToolchainSession — 状态跨 tool call 保留
|
||||
// ===========================================================================
|
||||
|
||||
describe("cross-compile ToolchainSession — 状态保留", () => {
|
||||
it("select 后 getCurrent 返回所选 triple", () => {
|
||||
const session = new ToolchainSession();
|
||||
const tc = session.select("aarch64-linux-gnu");
|
||||
expect(tc.gcc).toBe("aarch64-linux-gnu-gcc");
|
||||
expect(session.getCurrent()).toBe("aarch64-linux-gnu");
|
||||
});
|
||||
|
||||
it("切换 triple 后 info 重置", () => {
|
||||
const session = new ToolchainSession();
|
||||
session.select("aarch64-linux-gnu");
|
||||
expect(session.getInfo()).toBeNull();
|
||||
session.select("arm-none-eabi");
|
||||
expect(session.getCurrent()).toBe("arm-none-eabi");
|
||||
expect(session.getInfo()).toBeNull();
|
||||
});
|
||||
|
||||
it("detect 后 info 缓存,再次调用不重复探测", async () => {
|
||||
let callCount = 0;
|
||||
const exec: ExecFn = async (cmd, args) => {
|
||||
callCount++;
|
||||
if (cmd === "aarch64-linux-gnu-gcc" && args.includes("--version"))
|
||||
return ok("gcc 12.2.0");
|
||||
if (cmd === "aarch64-linux-gnu-gcc" && args.includes("-print-sysroot"))
|
||||
return ok("/sysroot");
|
||||
if (cmd === "which") return ok("/usr/bin/aarch64-linux-gnu-gcc");
|
||||
return fail("nope", 127);
|
||||
};
|
||||
const session = new ToolchainSession();
|
||||
session.select("aarch64-linux-gnu");
|
||||
const a = await session.detect(exec);
|
||||
expect(a.available).toBe(true);
|
||||
const firstCount = callCount;
|
||||
const b = await session.detect(exec); // 应走缓存
|
||||
expect(b).toBe(a);
|
||||
expect(callCount).toBe(firstCount);
|
||||
});
|
||||
|
||||
it("未 select 就 detect → fail-closed 报错", async () => {
|
||||
const session = new ToolchainSession();
|
||||
const exec: ExecFn = async () => ok("");
|
||||
const a = await session.detect(exec);
|
||||
expect(a.available).toBe(false);
|
||||
expect(a.error).toContain("no triple");
|
||||
});
|
||||
|
||||
it("getResolved 返回当前 toolchain(已 select)", () => {
|
||||
const session = new ToolchainSession();
|
||||
session.select("arm-none-eabi");
|
||||
const tc = session.getResolved();
|
||||
expect(tc?.prefix).toBe("arm-none-eabi-");
|
||||
});
|
||||
|
||||
it("getResolved 未 select 返回 null", () => {
|
||||
const session = new ToolchainSession();
|
||||
expect(session.getResolved()).toBeNull();
|
||||
});
|
||||
|
||||
it("reset 清空状态", () => {
|
||||
const session = new ToolchainSession();
|
||||
session.select("aarch64-linux-gnu");
|
||||
session.reset();
|
||||
expect(session.getCurrent()).toBeNull();
|
||||
expect(session.getResolved()).toBeNull();
|
||||
});
|
||||
});
|
||||
407
tests/datasheet-rag.test.ts
Normal file
407
tests/datasheet-rag.test.ts
Normal file
@ -0,0 +1,407 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
chunkPdf,
|
||||
buildIndex,
|
||||
mergeIndex,
|
||||
search,
|
||||
formatContext,
|
||||
tokenize,
|
||||
tokenizeLower,
|
||||
pagesFromPdftotextOutput,
|
||||
extractAddresses,
|
||||
verifyAddressInResults,
|
||||
DEFAULT_CHUNK_SIZE,
|
||||
MAX_CONTEXT_CHUNK_CHARS,
|
||||
type PdfPage,
|
||||
} from "../src/extensions/datasheet-rag.js";
|
||||
|
||||
// ============================================================================
|
||||
// 测试用 datasheet 样本(模拟 STM32F4 RM0090 寄存器映射表片段)
|
||||
// ============================================================================
|
||||
|
||||
const SAMPLE_PAGES: PdfPage[] = [
|
||||
{
|
||||
page: 12,
|
||||
filePath: "/datasheets/rm0090.pdf",
|
||||
text:
|
||||
"GPIOA_BASE = 0x48000000. The GPIOA register base address for port A. " +
|
||||
"GPIOA_MODER offset 0x00, GPIOA_OTYPER offset 0x04. " +
|
||||
"RCC_AHB1ENR bit 0 = GPIOAEN. Reset value 0x00180000.",
|
||||
},
|
||||
{
|
||||
page: 45,
|
||||
filePath: "/datasheets/rm0090.pdf",
|
||||
text:
|
||||
"RCC_AHB1ENR address 0x40023830. Bit 0 GPIOAEN enables GPIOA clock. " +
|
||||
"GPIOA_BASE 0x48000000. Set bit 0 to enable port A clock.",
|
||||
},
|
||||
{
|
||||
page: 200,
|
||||
filePath: "/datasheets/rm0090.pdf",
|
||||
text:
|
||||
"SPI2 base address 0x40003800. CR1 offset 0x00, CR2 offset 0x04. " +
|
||||
"SPI2 is on APB1. Baud rate configured via BR bits.",
|
||||
},
|
||||
];
|
||||
|
||||
// ============================================================================
|
||||
// 分词
|
||||
// ============================================================================
|
||||
|
||||
describe("datasheet-rag tokenize", () => {
|
||||
it("分词包含 hex 地址和寄存器名", () => {
|
||||
const tokens = tokenize("GPIOA_BASE = 0x48000000");
|
||||
expect(tokens).toContain("GPIOA_BASE");
|
||||
expect(tokens).toContain("0x48000000");
|
||||
});
|
||||
|
||||
it("空字符串返回空数组", () => {
|
||||
expect(tokenize("")).toEqual([]);
|
||||
expect(tokenizeLower("")).toEqual([]);
|
||||
});
|
||||
|
||||
it("小写化:GPIOA_BASE → gpioa_base", () => {
|
||||
const tokens = tokenizeLower("GPIOA_BASE RCC_AHB1ENR");
|
||||
expect(tokens).toContain("gpioa_base");
|
||||
expect(tokens).toContain("rcc_ahb1enr");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// pagesFromPdftotextOutput
|
||||
// ============================================================================
|
||||
|
||||
describe("datasheet-rag pagesFromPdftotextOutput", () => {
|
||||
it("按分页符 \\f 切分页码从 1 起", () => {
|
||||
const stdout = "page one text\nGPIOA_BASE\fpage two text\nRCC_AHB1ENR";
|
||||
const pages = pagesFromPdftotextOutput(stdout, "/datasheets/rm0090.pdf");
|
||||
expect(pages).toHaveLength(2);
|
||||
expect(pages[0]!.page).toBe(1);
|
||||
expect(pages[1]!.page).toBe(2);
|
||||
expect(pages[0]!.text).toContain("GPIOA_BASE");
|
||||
expect(pages[1]!.text).toContain("RCC_AHB1ENR");
|
||||
});
|
||||
|
||||
it("filePath 透传到每页", () => {
|
||||
const pages = pagesFromPdftotextOutput("a\fb", "/x.pdf");
|
||||
expect(pages.every((p) => p.filePath === "/x.pdf")).toBe(true);
|
||||
});
|
||||
|
||||
it("空 stdout 返回空数组(fail-closed)", () => {
|
||||
expect(pagesFromPdftotextOutput("", "/x.pdf")).toEqual([]);
|
||||
});
|
||||
|
||||
it("全空白页被过滤", () => {
|
||||
const stdout = "real text\f \f\n \n";
|
||||
const pages = pagesFromPdftotextOutput(stdout, "/x.pdf");
|
||||
expect(pages).toHaveLength(1);
|
||||
expect(pages[0]!.page).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// chunkPdf
|
||||
// ============================================================================
|
||||
|
||||
describe("datasheet-rag chunkPdf", () => {
|
||||
it("每页文本 < chunkSize 产生一个 chunk", () => {
|
||||
const chunks = chunkPdf(SAMPLE_PAGES, 5000);
|
||||
expect(chunks).toHaveLength(3);
|
||||
expect(chunks[0]!.page).toBe(12);
|
||||
expect(chunks[1]!.page).toBe(45);
|
||||
expect(chunks[2]!.page).toBe(200);
|
||||
});
|
||||
|
||||
it("chunk id 格式 p{page}-c{index}", () => {
|
||||
const chunks = chunkPdf(SAMPLE_PAGES, 5000);
|
||||
expect(chunks[0]!.id).toBe("p12-c0");
|
||||
expect(chunks[1]!.id).toBe("p45-c0");
|
||||
expect(chunks[2]!.id).toBe("p200-c0");
|
||||
});
|
||||
|
||||
it("长文本按 chunkSize 切分多个 chunk", () => {
|
||||
const longPage: PdfPage = {
|
||||
page: 1,
|
||||
text: "A".repeat(50) + " " + "B".repeat(50) + " " + "C".repeat(50),
|
||||
};
|
||||
const chunks = chunkPdf([longPage], 50);
|
||||
// 150 字符 + 2 空格 = 152,chunkSize=50 → 3~4 块
|
||||
expect(chunks.length).toBeGreaterThanOrEqual(3);
|
||||
// 拼回的文本应覆盖全部内容
|
||||
const reconstructed = chunks.map((c) => c.text).join(" ");
|
||||
expect(reconstructed).toContain("A".repeat(50));
|
||||
expect(reconstructed).toContain("B".repeat(50));
|
||||
expect(reconstructed).toContain("C".repeat(50));
|
||||
});
|
||||
|
||||
it("chunkSize <= 0 抛错", () => {
|
||||
expect(() => chunkPdf(SAMPLE_PAGES, 0)).toThrow();
|
||||
expect(() => chunkPdf(SAMPLE_PAGES, -1)).toThrow();
|
||||
});
|
||||
|
||||
it("空页跳过", () => {
|
||||
const chunks = chunkPdf([{ page: 1, text: "" }, { page: 2, text: "hello" }]);
|
||||
expect(chunks).toHaveLength(1);
|
||||
expect(chunks[0]!.page).toBe(2);
|
||||
});
|
||||
|
||||
it("filePath 透传到 chunk", () => {
|
||||
const chunks = chunkPdf(SAMPLE_PAGES, 5000);
|
||||
expect(chunks[0]!.filePath).toBe("/datasheets/rm0090.pdf");
|
||||
});
|
||||
|
||||
it("默认 chunkSize = 2000", () => {
|
||||
expect(DEFAULT_CHUNK_SIZE).toBe(2000);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// buildIndex
|
||||
// ============================================================================
|
||||
|
||||
describe("datasheet-rag buildIndex", () => {
|
||||
const chunks = chunkPdf(SAMPLE_PAGES, 5000);
|
||||
const index = buildIndex(chunks);
|
||||
|
||||
it("倒排索引 term 小写化", () => {
|
||||
expect(index.inverted.has("gpioa_base")).toBe(true);
|
||||
expect(index.inverted.has("GPIOA_BASE")).toBe(false);
|
||||
});
|
||||
|
||||
it("倒排索引含 hex 地址 term(小写)", () => {
|
||||
expect(index.inverted.has("0x48000000")).toBe(true);
|
||||
expect(index.inverted.has("0x40023830")).toBe(true);
|
||||
});
|
||||
|
||||
it("term 出现在多个 chunk 时 Set 含多个 chunkId", () => {
|
||||
const set = index.inverted.get("gpioa_base");
|
||||
expect(set).toBeDefined();
|
||||
expect(set!.size).toBe(2); // p12 + p45
|
||||
expect(set!.has("p12-c0")).toBe(true);
|
||||
expect(set!.has("p45-c0")).toBe(true);
|
||||
});
|
||||
|
||||
it("termFreq 记录 chunk 内 term 出现次数", () => {
|
||||
const freq = index.termFreq.get("p12-c0");
|
||||
expect(freq).toBeDefined();
|
||||
expect(freq!.get("gpioa_base")).toBe(1);
|
||||
expect(freq!.get("0x48000000")).toBe(1);
|
||||
// p45 有两次 gpioa_base
|
||||
const freq45 = index.termFreq.get("p45-c0");
|
||||
expect(freq45!.get("gpioa_base")).toBe(1);
|
||||
});
|
||||
|
||||
it("size 等于 chunk 数", () => {
|
||||
expect(index.size).toBe(chunks.length);
|
||||
});
|
||||
|
||||
it("docPaths 收集文档路径", () => {
|
||||
expect(index.docPaths.has("/datasheets/rm0090.pdf")).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// mergeIndex
|
||||
// ============================================================================
|
||||
|
||||
describe("datasheet-rag mergeIndex", () => {
|
||||
it("合并两个文档索引后 chunk/term/docPath 叠加", () => {
|
||||
// 用不同页码避免 chunk id 碰撞(id 格式 p{page}-c{index})
|
||||
const pagesA: PdfPage[] = [
|
||||
{ page: 1, text: "GPIOA_BASE 0x48000000", filePath: "/a.pdf" },
|
||||
];
|
||||
const pagesB: PdfPage[] = [
|
||||
{ page: 2, text: "SPI2_BASE 0x40003800", filePath: "/b.pdf" },
|
||||
];
|
||||
const target = buildIndex(chunkPdf(pagesA, 5000));
|
||||
const addition = buildIndex(chunkPdf(pagesB, 5000));
|
||||
const merged = mergeIndex(target, addition);
|
||||
|
||||
// 两文档各自的 term 仍可查
|
||||
expect(merged.inverted.has("gpioa_base")).toBe(true);
|
||||
expect(merged.inverted.has("spi2_base")).toBe(true);
|
||||
// size 叠加
|
||||
expect(merged.size).toBe(target.size);
|
||||
// 两文档路径都在
|
||||
expect(merged.docPaths.has("/a.pdf")).toBe(true);
|
||||
expect(merged.docPaths.has("/b.pdf")).toBe(true);
|
||||
// 合并后跨文档检索各自命中正确 chunk
|
||||
const resA = search(merged, "GPIOA_BASE", 5);
|
||||
expect(resA.length).toBeGreaterThan(0);
|
||||
expect(resA[0]!.filePath).toBe("/a.pdf");
|
||||
const resB = search(merged, "SPI2_BASE", 5);
|
||||
expect(resB.length).toBeGreaterThan(0);
|
||||
expect(resB[0]!.filePath).toBe("/b.pdf");
|
||||
});
|
||||
|
||||
it("同 term 出现在两文档时 Set 合并 chunkId", () => {
|
||||
// 用不同页码避免 chunk id 碰撞(id 格式 p{page}-c{index})
|
||||
const pagesA: PdfPage[] = [{ page: 1, text: "GPIOA_BASE addr", filePath: "/a.pdf" }];
|
||||
const pagesB: PdfPage[] = [{ page: 2, text: "GPIOA_BASE again", filePath: "/b.pdf" }];
|
||||
const target = buildIndex(chunkPdf(pagesA, 5000));
|
||||
const addition = buildIndex(chunkPdf(pagesB, 5000));
|
||||
const merged = mergeIndex(target, addition);
|
||||
const set = merged.inverted.get("gpioa_base");
|
||||
expect(set).toBeDefined();
|
||||
expect(set!.size).toBe(2);
|
||||
expect(set!.has("p1-c0")).toBe(true);
|
||||
expect(set!.has("p2-c0")).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// search
|
||||
// ============================================================================
|
||||
|
||||
describe("datasheet-rag search", () => {
|
||||
const chunks = chunkPdf(SAMPLE_PAGES, 5000);
|
||||
const index = buildIndex(chunks);
|
||||
|
||||
it("查 GPIOA_BASE 返回含 0x48000000 的 chunk", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5);
|
||||
expect(results.length).toBeGreaterThan(0);
|
||||
// 至少一个结果含 hex 地址
|
||||
const hasAddr = results.some((r) => r.text.includes("0x48000000"));
|
||||
expect(hasAddr).toBe(true);
|
||||
});
|
||||
|
||||
it("查不存在的寄存器 FOOBAR_Z 返回空(fail-closed 不幻觉)", () => {
|
||||
const results = search(index, "FOOBAR_Z", 5);
|
||||
expect(results).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("同分按页码升序:gpioa_base 两 chunk tf=1 平分,p12 在前", () => {
|
||||
const results = search(index, "gpioa_base", 5);
|
||||
expect(results.length).toBeGreaterThanOrEqual(2);
|
||||
expect(results[0]!.page).toBe(12); // 页码小的在前
|
||||
});
|
||||
|
||||
it("topK 限制返回数", () => {
|
||||
const results = search(index, "GPIOA_BASE 0x48000000", 1);
|
||||
expect(results).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("多 term 查询分数叠加", () => {
|
||||
// "gpioa_base 0x48000000" → p12 命中两者 score=2, p45 命中两者 score=2
|
||||
const results = search(index, "gpioa_base 0x48000000", 5);
|
||||
expect(results.length).toBeGreaterThanOrEqual(2);
|
||||
expect(results[0]!.score).toBeGreaterThanOrEqual(2);
|
||||
});
|
||||
|
||||
it("filter.docPath 限定文档路径", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5, {
|
||||
filter: { docPath: "/datasheets/rm0090.pdf" },
|
||||
});
|
||||
expect(results.length).toBeGreaterThan(0);
|
||||
expect(results.every((r) => r.filePath === "/datasheets/rm0090.pdf")).toBe(true);
|
||||
});
|
||||
|
||||
it("filter.docPath 不匹配返回空", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5, {
|
||||
filter: { docPath: "/other.pdf" },
|
||||
});
|
||||
expect(results).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("filter.page 限定页码", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5, { filter: { page: 200 } });
|
||||
// page 200 没有 gpioa_base → 空
|
||||
expect(results).toHaveLength(0);
|
||||
const results45 = search(index, "RCC_AHB1ENR", 5, { filter: { page: 45 } });
|
||||
expect(results45.length).toBeGreaterThan(0);
|
||||
expect(results45.every((r) => r.page === 45)).toBe(true);
|
||||
});
|
||||
|
||||
it("空 query 返回空(fail-closed)", () => {
|
||||
expect(search(index, "", 5)).toHaveLength(0);
|
||||
expect(search(index, " ", 5)).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("返回结果带 page/filePath/score 字段", () => {
|
||||
const results = search(index, "SPI2", 5);
|
||||
expect(results.length).toBeGreaterThan(0);
|
||||
expect(results[0]!.page).toBe(200);
|
||||
expect(results[0]!.filePath).toBe("/datasheets/rm0090.pdf");
|
||||
expect(typeof results[0]!.score).toBe("number");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// formatContext
|
||||
// ============================================================================
|
||||
|
||||
describe("datasheet-rag formatContext", () => {
|
||||
const chunks = chunkPdf(SAMPLE_PAGES, 5000);
|
||||
const index = buildIndex(chunks);
|
||||
|
||||
it("空结果返回 'No matching passages found.'(fail-closed)", () => {
|
||||
expect(formatContext([])).toBe("No matching passages found.");
|
||||
});
|
||||
|
||||
it("含寄存器地址 0x48000000", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5);
|
||||
const text = formatContext(results, "GPIOA_BASE");
|
||||
expect(text).toContain("0x48000000");
|
||||
});
|
||||
|
||||
it("含页码和文件路径", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5);
|
||||
const text = formatContext(results);
|
||||
expect(text).toContain("p12");
|
||||
expect(text).toContain("rm0090.pdf");
|
||||
});
|
||||
|
||||
it("含 score", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5);
|
||||
const text = formatContext(results);
|
||||
expect(text).toContain("score:");
|
||||
});
|
||||
|
||||
it("含 header 和 End passages 标记", () => {
|
||||
const results = search(index, "SPI2", 5);
|
||||
const text = formatContext(results, "SPI2");
|
||||
expect(text).toContain("=== Datasheet RAG:");
|
||||
expect(text).toContain("=== End passages ===");
|
||||
expect(text).toContain("SPI2");
|
||||
});
|
||||
|
||||
it("超长 chunk 被截断", () => {
|
||||
const longResult = {
|
||||
chunkId: "p1-c0",
|
||||
page: 1,
|
||||
text: "A".repeat(MAX_CONTEXT_CHUNK_CHARS + 500),
|
||||
score: 1,
|
||||
};
|
||||
const text = formatContext([longResult]);
|
||||
expect(text).toContain("…");
|
||||
expect(text.length).toBeLessThan(longResult.text.length);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// extractAddresses / verifyAddressInResults
|
||||
// ============================================================================
|
||||
|
||||
describe("datasheet-rag address verification", () => {
|
||||
const chunks = chunkPdf(SAMPLE_PAGES, 5000);
|
||||
const index = buildIndex(chunks);
|
||||
|
||||
it("extractAddresses 提取 hex 地址", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5);
|
||||
const addrs = extractAddresses(results);
|
||||
expect(addrs).toContain("0x48000000");
|
||||
expect(addrs).toContain("0x00180000");
|
||||
});
|
||||
|
||||
it("verifyAddressInResults 命中返回 true(大小写不敏感)", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5);
|
||||
expect(verifyAddressInResults("0x48000000", results)).toBe(true);
|
||||
expect(verifyAddressInResults("0X48000000", results)).toBe(true);
|
||||
});
|
||||
|
||||
it("verifyAddressInResults 未命中返回 false(fail-closed)", () => {
|
||||
const results = search(index, "GPIOA_BASE", 5);
|
||||
expect(verifyAddressInResults("0xdeadbeef", results)).toBe(false);
|
||||
expect(verifyAddressInResults("", results)).toBe(false);
|
||||
});
|
||||
});
|
||||
335
tests/device-tree.test.ts
Normal file
335
tests/device-tree.test.ts
Normal file
@ -0,0 +1,335 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
parseDts,
|
||||
findNode,
|
||||
validateOverlay,
|
||||
checkCompatible,
|
||||
checkPhandle,
|
||||
compileDts,
|
||||
parseDtcErrors,
|
||||
extractPhandleRefs,
|
||||
DEFAULT_COMPATIBLE_DICT,
|
||||
} from "../src/extensions/device-tree.js";
|
||||
import type { ExecFn } from "../src/shared/types.js";
|
||||
|
||||
// 常用 DTS 片段
|
||||
const SIMPLE_DTS = `/dts-v1/;
|
||||
|
||||
/ {
|
||||
compatible = "vendor,board";
|
||||
#address-cells = <1>;
|
||||
#size-cells = <1>;
|
||||
|
||||
i2c0: i2c@40020000 {
|
||||
compatible = "vendor,i2c";
|
||||
reg = <0x40020000 0x1000>;
|
||||
#address-cells = <1>;
|
||||
#size-cells = <0>;
|
||||
|
||||
sensor: sensor@68 {
|
||||
compatible = "vendor,sensor";
|
||||
reg = <0x68>;
|
||||
interrupt-parent = <&gpio4>;
|
||||
interrupts = <17 2>;
|
||||
};
|
||||
};
|
||||
|
||||
gpio4: gpio@40004000 {
|
||||
compatible = "vendor,gpio";
|
||||
reg = <0x40004000 0x400>;
|
||||
#gpio-cells = <2>;
|
||||
phandle = <0x5>;
|
||||
};
|
||||
};
|
||||
`;
|
||||
|
||||
describe("device-tree parseDts — 基础解析", () => {
|
||||
it("解析根节点 + 两个子节点", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
expect(tree.nodes).toHaveLength(1);
|
||||
const root = tree.nodes[0];
|
||||
expect(root).toBeDefined();
|
||||
expect(root.fullName).toBe("/");
|
||||
expect(root.children.length).toBe(2);
|
||||
});
|
||||
|
||||
it("提取 compatible / reg / #address-cells 属性", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
const root = tree.nodes[0];
|
||||
expect(root.props["compatible"].raw).toBe('"vendor,board"');
|
||||
expect(root.props["#address-cells"].raw).toBe("<1>");
|
||||
expect(root.props["#size-cells"].raw).toBe("<1>");
|
||||
});
|
||||
|
||||
it("节点 label 与 unit address 正确", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
const root = tree.nodes[0];
|
||||
const i2c = root.children.find((c) => c.label === "i2c0")!;
|
||||
expect(i2c).toBeDefined();
|
||||
expect(i2c.name).toBe("i2c");
|
||||
expect(i2c.unitAddress).toBe("40020000");
|
||||
expect(i2c.fullName).toBe("i2c@40020000");
|
||||
|
||||
const gpio = root.children.find((c) => c.label === "gpio4")!;
|
||||
expect(gpio.unitAddress).toBe("40004000");
|
||||
});
|
||||
|
||||
it("嵌套子节点 i2c0 → sensor@68", () => {
|
||||
const i2c = parseDts(SIMPLE_DTS).nodes[0].children.find((c) => c.label === "i2c0")!;
|
||||
expect(i2c.children).toHaveLength(1);
|
||||
const sensor = i2c.children[0];
|
||||
expect(sensor.fullName).toBe("sensor@68");
|
||||
expect(sensor.label).toBe("sensor");
|
||||
expect(sensor.props["reg"].raw).toBe("<0x68>");
|
||||
});
|
||||
|
||||
it("phandle 引用提取自 interrupt-parent 属性", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
const i2c = tree.nodes[0].children.find((c) => c.label === "i2c0")!;
|
||||
const sensor = i2c.children[0];
|
||||
expect(sensor.props["interrupt-parent"].phandleRefs).toEqual(["gpio4"]);
|
||||
});
|
||||
|
||||
it("labels 表收集 i2c0 / sensor / gpio4", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
expect(tree.labels.has("i2c0")).toBe(true);
|
||||
expect(tree.labels.has("sensor")).toBe(true);
|
||||
expect(tree.labels.has("gpio4")).toBe(true);
|
||||
expect(tree.labels.size).toBe(3);
|
||||
});
|
||||
});
|
||||
|
||||
describe("device-tree parseDts — include 与 overlay", () => {
|
||||
it("捕获 #include 路径", () => {
|
||||
const tree = parseDts(`#include "stm32f411.dtsi"\n/dts-v1/;\n/ { };`);
|
||||
expect(tree.includes).toContain("stm32f411.dtsi");
|
||||
});
|
||||
|
||||
it("解析 overlay 引用节点 & label { }", () => {
|
||||
const tree = parseDts(`&i2c0 { status = "okay"; };`);
|
||||
expect(tree.nodes).toHaveLength(1);
|
||||
expect(tree.nodes[0].refTarget).toBe("i2c0");
|
||||
expect(tree.nodes[0].props["status"].raw).toBe('"okay"');
|
||||
});
|
||||
});
|
||||
|
||||
describe("device-tree findNode — 路径查找", () => {
|
||||
it("按 label 路径查找 i2c0/sensor@68", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
const root = tree.nodes[0];
|
||||
const node = findNode(root, "i2c0/sensor@68");
|
||||
expect(node).not.toBeNull();
|
||||
expect(node!.fullName).toBe("sensor@68");
|
||||
});
|
||||
|
||||
it("带前导 / 的路径也能找到", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
const node = findNode(tree.nodes[0], "/i2c0/sensor@68");
|
||||
expect(node).not.toBeNull();
|
||||
});
|
||||
|
||||
it("按 label 查找 gpio4 节点", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
const node = findNode(tree.nodes[0], "gpio4");
|
||||
expect(node).not.toBeNull();
|
||||
expect(node!.label).toBe("gpio4");
|
||||
});
|
||||
|
||||
it("找不到路径返回 null", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
expect(findNode(tree.nodes[0], "i2c0/nonexistent")).toBeNull();
|
||||
});
|
||||
|
||||
it("空路径返回 null(边界)", () => {
|
||||
const tree = parseDts(SIMPLE_DTS);
|
||||
expect(findNode(tree.nodes[0], "")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("device-tree validateOverlay — label 校验(fail-closed)", () => {
|
||||
it("overlay 引用 base 中存在的 label → ok", () => {
|
||||
const base = parseDts(SIMPLE_DTS);
|
||||
const overlay = parseDts(`&i2c0 { status = "okay"; };`);
|
||||
const r = validateOverlay(overlay, base);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.errors).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("overlay 引用 base 中不存在的 label → 报 dangling 错误(fail-closed)", () => {
|
||||
const base = parseDts(SIMPLE_DTS);
|
||||
const overlay = parseDts(`&nonexistent_i2c { status = "okay"; };`);
|
||||
const r = validateOverlay(overlay, base);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.errors.length).toBeGreaterThan(0);
|
||||
expect(r.errors[0]).toContain("dangling phandle reference");
|
||||
expect(r.errors[0]).toContain("nonexistent_i2c");
|
||||
});
|
||||
|
||||
it("overlay 属性值 <&label> 引用断链报错(fail-closed)", () => {
|
||||
const base = parseDts(SIMPLE_DTS);
|
||||
const overlay = parseDts(`&i2c0 { interrupt-parent = <&ghost>; };`);
|
||||
const r = validateOverlay(overlay, base);
|
||||
expect(r.ok).toBe(false);
|
||||
const danglingErr = r.errors.find((e) => e.includes("&ghost"));
|
||||
expect(danglingErr).toBeDefined();
|
||||
});
|
||||
|
||||
it("overlay 引用 base 的 gpio4 label 通过校验", () => {
|
||||
const base = parseDts(SIMPLE_DTS);
|
||||
const overlay = parseDts(`&i2c0 { interrupt-parent = <&gpio4>; };`);
|
||||
const r = validateOverlay(overlay, base);
|
||||
expect(r.ok).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("device-tree checkCompatible — compatible 拼写校验", () => {
|
||||
it("命中字典的 compatible 无 issue", () => {
|
||||
const tree = parseDts(`/ { compatible = "rockchip,rk3588"; };`);
|
||||
expect(checkCompatible(tree)).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("typo(少末尾字符)标 typo 并给建议", () => {
|
||||
// st,stm32f411xe → 故意写 st,stm32f411x(少 e)
|
||||
const tree = parseDts(`/ { compatible = "st,stm32f411x"; };`);
|
||||
const issues = checkCompatible(tree);
|
||||
expect(issues).toHaveLength(1);
|
||||
expect(issues[0].kind).toBe("typo");
|
||||
expect(issues[0].suggestion).toBeDefined();
|
||||
expect(DEFAULT_COMPATIBLE_DICT).toContain(issues[0].suggestion);
|
||||
});
|
||||
|
||||
it("完全陌生的 compatible 标 unknown(非错非对)", () => {
|
||||
const tree = parseDts(`/ { compatible = "acme,board2000"; };`);
|
||||
const issues = checkCompatible(tree);
|
||||
expect(issues).toHaveLength(1);
|
||||
expect(issues[0].kind).toBe("unknown");
|
||||
});
|
||||
|
||||
it("多 compatible 串逐个校验", () => {
|
||||
const tree = parseDts(`/ { compatible = "rockchip,rk3588", "acme,xyz"; };`);
|
||||
const issues = checkCompatible(tree);
|
||||
// rk3588 命中,acme,xyz 未知
|
||||
expect(issues).toHaveLength(1);
|
||||
expect(issues[0].compatible).toBe("acme,xyz");
|
||||
});
|
||||
});
|
||||
|
||||
describe("device-tree checkPhandle — phandle 引用图", () => {
|
||||
it("无断链、未被引用的 phandle 标 orphan", () => {
|
||||
const tree = parseDts(`/ {
|
||||
gpio4: gpio@40004000 {
|
||||
compatible = "vendor,gpio";
|
||||
phandle = <0x5>;
|
||||
};
|
||||
gpio5: gpio@40005000 {
|
||||
phandle = <0x6>;
|
||||
};
|
||||
};`);
|
||||
const report = checkPhandle(tree);
|
||||
expect(report.dangling).toHaveLength(0);
|
||||
// gpio4 / gpio5 都未被 & 引用 → 都是 orphan
|
||||
expect(report.orphans.length).toBe(2);
|
||||
});
|
||||
|
||||
it("dangling 引用未定义 label(fail-closed)", () => {
|
||||
const tree = parseDts(`/ {
|
||||
sensor: sensor@68 {
|
||||
interrupt-parent = <&nonexistent>;
|
||||
};
|
||||
};`);
|
||||
const report = checkPhandle(tree);
|
||||
expect(report.dangling).toHaveLength(1);
|
||||
expect(report.dangling[0].ref).toBe("nonexistent");
|
||||
});
|
||||
|
||||
it("正常引用不算 dangling 也不算 orphan", () => {
|
||||
const tree = parseDts(`/ {
|
||||
gpio4: gpio@40004000 {
|
||||
phandle = <0x5>;
|
||||
};
|
||||
sensor: sensor@68 {
|
||||
interrupt-parent = <&gpio4>;
|
||||
};
|
||||
};`);
|
||||
const report = checkPhandle(tree);
|
||||
expect(report.dangling).toHaveLength(0);
|
||||
expect(report.orphans).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("device-tree extractPhandleRefs", () => {
|
||||
it("提取单个 <&label>", () => {
|
||||
expect(extractPhandleRefs("<&gpio4>")).toEqual(["gpio4"]);
|
||||
});
|
||||
it("提取带参数的引用 <&gpio4 17>", () => {
|
||||
expect(extractPhandleRefs("<&gpio4 17 2>")).toEqual(["gpio4"]);
|
||||
});
|
||||
it("提取多个引用", () => {
|
||||
expect(extractPhandleRefs("<&gpio4 &gpio5>")).toEqual(["gpio4", "gpio5"]);
|
||||
});
|
||||
it("无引用返回空数组(边界)", () => {
|
||||
expect(extractPhandleRefs("<0x68>")).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("device-tree compileDts — 注入 ExecFn(无真实硬件)", () => {
|
||||
it("dtc 成功 → ok:true 返回输出路径", async () => {
|
||||
const exec: ExecFn = async () => ({
|
||||
stdout: "",
|
||||
stderr: "",
|
||||
exitCode: 0,
|
||||
});
|
||||
const r = await compileDts(exec, "board.dts", { out: "out.dtb" });
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.out).toBe("out.dtb");
|
||||
expect(r.errors).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("dtc 语法错误 → 结构化错误含行号", async () => {
|
||||
const exec: ExecFn = async () => ({
|
||||
stdout: "",
|
||||
stderr: "Error: board.dts:42.1-12: syntax error\n",
|
||||
exitCode: 1,
|
||||
});
|
||||
const r = await compileDts(exec, "board.dts", { out: "out.dtb" });
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.errors.length).toBeGreaterThan(0);
|
||||
expect(r.errors[0].line).toBe(42);
|
||||
expect(r.errors[0].message).toContain("syntax error");
|
||||
});
|
||||
|
||||
it("exec 抛错 → fail-closed 返回错误", async () => {
|
||||
const exec: ExecFn = async () => {
|
||||
throw new Error("ENOENT dtc");
|
||||
};
|
||||
const r = await compileDts(exec, "board.dts");
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.errors[0].message).toContain("dtc exec failed");
|
||||
});
|
||||
|
||||
it("overlay 模式加 -@ 参数", async () => {
|
||||
let captured: string[] = [];
|
||||
const exec: ExecFn = async (_cmd, args) => {
|
||||
captured = args;
|
||||
return { stdout: "", stderr: "", exitCode: 0 };
|
||||
};
|
||||
await compileDts(exec, "overlay.dts", { overlay: true, out: "overlay.dtbo" });
|
||||
expect(captured).toContain("-@");
|
||||
expect(captured).toContain("overlay.dts");
|
||||
expect(captured).toContain("overlay.dtbo");
|
||||
});
|
||||
});
|
||||
|
||||
describe("device-tree parseDtcErrors", () => {
|
||||
it("解析行号 + 消息", () => {
|
||||
const errs = parseDtcErrors("Error: board.dts:42.1-12: syntax error");
|
||||
expect(errs).toHaveLength(1);
|
||||
expect(errs[0].line).toBe(42);
|
||||
expect(errs[0].message).toContain("syntax error");
|
||||
});
|
||||
|
||||
it("无行号的 FATAL 行也保留(边界)", () => {
|
||||
const errs = parseDtcErrors("FATAL: something bad");
|
||||
expect(errs.length).toBeGreaterThanOrEqual(1);
|
||||
});
|
||||
});
|
||||
251
tests/edit-strict.test.ts
Normal file
251
tests/edit-strict.test.ts
Normal file
@ -0,0 +1,251 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
computeEdit,
|
||||
countOccurrences,
|
||||
normalizeForFuzzyMatch,
|
||||
isStrictByDefault,
|
||||
STRICT_BY_DEFAULT_EXTENSIONS,
|
||||
validateEditChain,
|
||||
type EditMode,
|
||||
} from "../src/extensions/edit-strict.js";
|
||||
|
||||
describe("edit-strict exact 模式 — 唯一精确匹配", () => {
|
||||
it("唯一命中:成功替换,replacement mode=exact", () => {
|
||||
const content = "foo bar baz";
|
||||
const r = computeEdit(content, "bar", "BAR", "exact");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.newContent).toBe("foo BAR baz");
|
||||
expect(r.replacements).toHaveLength(1);
|
||||
expect(r.replacements[0]).toMatchObject({ mode: "exact", index: 4, length: 3 });
|
||||
});
|
||||
|
||||
it("多匹配报错(fail-closed,绝不模糊替换)", () => {
|
||||
const content = "&i2c0{\n&i2c1{\n&i2c1{\n";
|
||||
const r = computeEdit(content, "&i2c1{", "X", "exact");
|
||||
expect(r.error).toMatch(/unique/i);
|
||||
expect(r.replacements).toHaveLength(0);
|
||||
// newContent 不变
|
||||
expect(r.newContent).toBe(content);
|
||||
});
|
||||
|
||||
it("零匹配报错(not found)", () => {
|
||||
const r = computeEdit("hello world", "goodbye", "hi", "exact");
|
||||
expect(r.error).toMatch(/not found/i);
|
||||
expect(r.replacements).toHaveLength(0);
|
||||
expect(r.newContent).toBe("hello world");
|
||||
});
|
||||
|
||||
it("空 oldString 报错(fail-closed no-op/歧义)", () => {
|
||||
const r = computeEdit("abc", "", "X", "exact");
|
||||
expect(r.error).toMatch(/empty/i);
|
||||
expect(r.newContent).toBe("abc");
|
||||
});
|
||||
|
||||
it("未改行尾随空白逐字节不变(.dts 对齐安全)", () => {
|
||||
// keep 行与 end 行各有 3 个尾随空格;只改中间行
|
||||
const content = "keep \nfoo bar\nend \n";
|
||||
const r = computeEdit(content, "foo bar", "FOO BAR", "exact");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.newContent).toBe("keep \nFOO BAR\nend \n");
|
||||
});
|
||||
|
||||
it("默认 mode=exact(不传 mode)", () => {
|
||||
const r = computeEdit("a b c", "b", "B");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.newContent).toBe("a B c");
|
||||
expect(r.replacements[0]?.mode).toBe("exact");
|
||||
});
|
||||
|
||||
it(".dts 场景:oldText 缺尾随空格而原文有 → exact not-found 而非错配到相邻节点", () => {
|
||||
const content = "&i2c0 {\n&i2c1 {\n";
|
||||
// agent 给的 oldText 无空格,原文 "&i2c1 {" 有空格
|
||||
const r = computeEdit(content, "&i2c1{", "X", "exact");
|
||||
expect(r.error).toMatch(/not found/i);
|
||||
expect(r.newContent).toBe(content); // 原文不动,不误改 &i2c0
|
||||
});
|
||||
|
||||
it(".ld 场景:段名前缀重复时 oldText 不足 → exact not-found 拒绝错配", () => {
|
||||
const content = ".text.init : { *(.text.init) }\n.text.startup : { *(.text.startup) }\n";
|
||||
// oldText 只给 ".text" 会在多处命中 → unique 错误
|
||||
const r = computeEdit(content, ".text", "X", "exact");
|
||||
expect(r.error).toMatch(/unique/i);
|
||||
expect(r.newContent).toBe(content);
|
||||
});
|
||||
});
|
||||
|
||||
describe("edit-strict fuzzy 模式 — 兜底最近匹配", () => {
|
||||
it("exact 已唯一命中时直接用原文(mode=exact,不归一)", () => {
|
||||
const r = computeEdit("foo bar baz", "bar", "BAR", "fuzzy");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.newContent).toBe("foo BAR baz");
|
||||
expect(r.replacements[0]?.mode).toBe("exact");
|
||||
});
|
||||
|
||||
it("exact 零命中时 fuzzy 归一化兜底命中(mode=fuzzy)", () => {
|
||||
// 原文中间行有尾随空格,agent oldText 无尾随空格含换行
|
||||
const content = "keep \nfoo bar \nend \n";
|
||||
const r = computeEdit(content, "foo bar\n", "BAZ\n", "fuzzy");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.replacements).toHaveLength(1);
|
||||
expect(r.replacements[0]?.mode).toBe("fuzzy");
|
||||
});
|
||||
|
||||
it("fuzzy 替换基于原文:未改行对齐空白零变化", () => {
|
||||
const content = "keep \nfoo bar \nend \n";
|
||||
const r = computeEdit(content, "foo bar\n", "BAZ\n", "fuzzy");
|
||||
expect(r.error).toBeUndefined();
|
||||
// keep 行与 end 行的 3 个尾随空格完整保留
|
||||
expect(r.newContent).toBe("keep \nBAZ\nend \n");
|
||||
});
|
||||
|
||||
it("fuzzy 多次 exact 命中仍 fail-closed(.dts 重复节点)", () => {
|
||||
const content = "&i2c1{\n&i2c1{\n";
|
||||
const r = computeEdit(content, "&i2c1{", "X", "fuzzy");
|
||||
expect(r.error).toMatch(/unique/i);
|
||||
expect(r.replacements).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("fuzzy 归一后仍零命中 → 报错", () => {
|
||||
const r = computeEdit("alpha beta gamma", "zzz", "X", "fuzzy");
|
||||
expect(r.error).toMatch(/not found/i);
|
||||
expect(r.newContent).toBe("alpha beta gamma");
|
||||
});
|
||||
|
||||
it("fuzzy 智能 quote 差异能兜底命中", () => {
|
||||
// 原文用智能引号 “foo”,agent oldText 用 ASCII "foo
|
||||
const content = 'line “foo” end\n';
|
||||
const r = computeEdit(content, '"foo"', '"BAR"', "fuzzy");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.replacements[0]?.mode).toBe("fuzzy");
|
||||
expect(r.newContent).toBe('line "BAR" end\n');
|
||||
});
|
||||
|
||||
it("fuzzy 归一后为空(oldText 全空白)→ fail-closed", () => {
|
||||
const r = computeEdit("foo bar", " ", "X", "fuzzy");
|
||||
expect(r.error).toMatch(/empty/i);
|
||||
expect(r.newContent).toBe("foo bar");
|
||||
});
|
||||
});
|
||||
|
||||
describe("edit-strict countOccurrences", () => {
|
||||
it("非重叠计数", () => {
|
||||
expect(countOccurrences("aaaa", "aa")).toBe(2);
|
||||
});
|
||||
it("零次", () => {
|
||||
expect(countOccurrences("abc", "z")).toBe(0);
|
||||
});
|
||||
it("空 needle 返回 0", () => {
|
||||
expect(countOccurrences("abc", "")).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("edit-strict normalizeForFuzzyMatch — 位置映射", () => {
|
||||
it("trimEnd 移除行尾空白但 map 不含被移除位置", () => {
|
||||
const { text, map } = normalizeForFuzzyMatch("foo \n");
|
||||
// 归一化文本无尾随空格
|
||||
expect(text).toBe("foo\n");
|
||||
// map 的每个值指向原文非空格字符
|
||||
expect(map).toEqual([0, 1, 2, 6]);
|
||||
});
|
||||
|
||||
it("智能引号 1:1 替换且 map 指向原位置", () => {
|
||||
const { text, map } = normalizeForFuzzyMatch("“x”");
|
||||
expect(text).toBe('"x"');
|
||||
expect(map).toEqual([0, 1, 2]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("edit-strict 文件类型自动门", () => {
|
||||
it(".dts/.dtsi/.ld/.lds/.sct/.icf 默认 strict", () => {
|
||||
expect(isStrictByDefault("board.dts")).toBe(true);
|
||||
expect(isStrictByDefault("/path/to/soc.dtsi")).toBe(true);
|
||||
expect(isStrictByDefault("linker.ld")).toBe(true);
|
||||
expect(isStrictByDefault("boot.lds")).toBe(true);
|
||||
expect(isStrictByDefault("scatter.sct")).toBe(true);
|
||||
expect(isStrictByDefault("config.icf")).toBe(true);
|
||||
});
|
||||
it(".ts/.py/.c/.h 非默认 strict", () => {
|
||||
expect(isStrictByDefault("app.ts")).toBe(false);
|
||||
expect(isStrictByDefault("main.py")).toBe(false);
|
||||
expect(isStrictByDefault("main.c")).toBe(false);
|
||||
});
|
||||
it("扩展名大小写不敏感", () => {
|
||||
expect(isStrictByDefault("BOARD.DTS")).toBe(true);
|
||||
expect(isStrictByDefault("linker.LD")).toBe(true);
|
||||
});
|
||||
it("规则集覆盖 6 类扩展名", () => {
|
||||
expect(STRICT_BY_DEFAULT_EXTENSIONS.length).toBeGreaterThanOrEqual(6);
|
||||
});
|
||||
});
|
||||
|
||||
describe("edit-strict validateEditChain — edit 链预校验(钩子纯逻辑内核)", () => {
|
||||
it("多条全通过:逐条喂入并累计替换", () => {
|
||||
const content = "foo bar\nbaz qux\n";
|
||||
const r = validateEditChain(content, [
|
||||
{ oldText: "foo", newText: "FOO" },
|
||||
{ oldText: "baz", newText: "BAZ" },
|
||||
], "exact");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.content).toBe("FOO bar\nBAZ qux\n");
|
||||
});
|
||||
|
||||
it("第二条 fail-closed:原文不动,仅上报错误", () => {
|
||||
const content = "foo bar\nbaz qux\n";
|
||||
const r = validateEditChain(content, [
|
||||
{ oldText: "foo", newText: "FOO" },
|
||||
{ oldText: "missing", newText: "X" }, // 零命中
|
||||
], "exact");
|
||||
expect(r.error).toMatch(/not found/i);
|
||||
// fail-closed:原文不动(非半改状态)
|
||||
expect(r.content).toBe(content);
|
||||
});
|
||||
|
||||
it("重复 oldText fail-closed:原文不动", () => {
|
||||
const content = "&i2c1{\n&i2c1{\n";
|
||||
const r = validateEditChain(content, [{ oldText: "&i2c1{", newText: "X" }], "exact");
|
||||
expect(r.error).toMatch(/unique/i);
|
||||
expect(r.content).toBe(content);
|
||||
});
|
||||
|
||||
it("空 edits 列表:原文不动无错误(no-op 放行)", () => {
|
||||
const content = "unchanged\n";
|
||||
const r = validateEditChain(content, [], "exact");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.content).toBe(content);
|
||||
});
|
||||
|
||||
it("缺省 oldText/newText 字段视为空串 → fail-closed", () => {
|
||||
const content = "abc\n";
|
||||
const r = validateEditChain(content, [{}], "exact");
|
||||
expect(r.error).toMatch(/empty/i);
|
||||
expect(r.content).toBe(content);
|
||||
});
|
||||
|
||||
it("默认 mode=exact(不传 mode)", () => {
|
||||
const r = validateEditChain("a b c", [{ oldText: "b", newText: "B" }]);
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.content).toBe("a B c");
|
||||
});
|
||||
|
||||
it("链式替换允许前一条产生的新内容被后一条匹配", () => {
|
||||
// 第一条把 foo→bar,第二条再把 bar→BAR
|
||||
const r = validateEditChain("foo\n", [
|
||||
{ oldText: "foo", newText: "bar" },
|
||||
{ oldText: "bar", newText: "BAR" },
|
||||
], "exact");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.content).toBe("BAR\n");
|
||||
});
|
||||
|
||||
it(".dts 多节点链式:逐条唯一命中全通过", () => {
|
||||
const content = "&i2c0 {\n\tstatus = \"okay\";\n};\n&i2c1 {\n\tstatus = \"okay\";\n};\n";
|
||||
// 每条 oldText 含足够上下文唯一命中
|
||||
const r = validateEditChain(content, [
|
||||
{ oldText: '&i2c0 {\n\tstatus = "okay";', newText: '&i2c0 {\n\tstatus = "disabled";' },
|
||||
{ oldText: '&i2c1 {\n\tstatus = "okay";', newText: '&i2c1 {\n\tstatus = "disabled";' },
|
||||
], "exact");
|
||||
expect(r.error).toBeUndefined();
|
||||
expect(r.content).toContain('"disabled"');
|
||||
expect(r.content).not.toContain('"okay"');
|
||||
});
|
||||
});
|
||||
495
tests/env-probe.test.ts
Normal file
495
tests/env-probe.test.ts
Normal file
@ -0,0 +1,495 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
probeEnv,
|
||||
buildEnvPrompt,
|
||||
injectEnvPrompt,
|
||||
stripEnvBlocks,
|
||||
safeProbe,
|
||||
firstLine,
|
||||
filterDevEntries,
|
||||
renderList,
|
||||
makeExecFn,
|
||||
summarizeProbe,
|
||||
ProbeCacheStore,
|
||||
PROBE_NOT_INSTALLED,
|
||||
PROBE_UNKNOWN,
|
||||
PROBE_UNAVAILABLE,
|
||||
PROBE_NOT_A_GIT_REPO,
|
||||
PROBE_NO_LSUSB,
|
||||
DEFAULT_TTL_MS,
|
||||
DEFAULT_PROBE_TIMEOUT_MS,
|
||||
DEFAULT_DMESG_LINES,
|
||||
type EnvProbe,
|
||||
} from "../src/extensions/env-probe.js";
|
||||
import type { ExecFn, ExecOpts, ExecResult } from "../src/shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// mock ExecFn 工厂:按 command 派发 canned 输出
|
||||
// ============================================================================
|
||||
|
||||
function makeMockExec(
|
||||
overrides: Record<string, (args: string[]) => ExecResult> = {},
|
||||
): ExecFn {
|
||||
const ok = (stdout: string): ExecResult => ({ stdout, stderr: "", exitCode: 0 });
|
||||
const fail: ExecResult = { stdout: "", stderr: "not found", exitCode: 127 };
|
||||
|
||||
return async (command: string, args: string[]) => {
|
||||
// 优先匹配 overrides
|
||||
const override = overrides[command];
|
||||
if (override) return override(args);
|
||||
switch (command) {
|
||||
case "uname":
|
||||
if (args[0] === "-r") return ok("5.4.0-rdk-x5\n");
|
||||
if (args[0] === "-m") return ok("aarch64\n");
|
||||
return ok("");
|
||||
case "cat":
|
||||
if (args[0] === "/proc/device-tree/model") return ok("RDK X5\0");
|
||||
return fail;
|
||||
case "aarch64-linux-gnu-gcc":
|
||||
return ok(
|
||||
"aarch64-linux-gnu-gcc (Ubuntu 10.3.0-1ubuntu1) 10.3.0\nCopyright (C) 2020 Free Software Foundation, Inc.\n",
|
||||
);
|
||||
case "arm-none-eabi-gcc":
|
||||
return ok(
|
||||
"arm-none-eabi-gcc (15:10.3-2021.07-1) 10.3.1 20210621\nCopyright (C) 2020 Free Software Foundation, Inc.\n",
|
||||
);
|
||||
case "gcc":
|
||||
return ok("gcc (Ubuntu 11.4.0-1ubuntu1) 11.4.0\n");
|
||||
case "dtc":
|
||||
return ok("Version: DTC 1.6.0-g48a4eff9\n");
|
||||
case "git":
|
||||
if (args[0] === "rev-parse" && args[1] === "--short" && args[2] === "HEAD")
|
||||
return ok("6a32ec9f\n");
|
||||
return fail;
|
||||
case "lsusb":
|
||||
return ok(
|
||||
"Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub\nBus 002 Device 042: ID 046d:c534 Logitech Receiver\n",
|
||||
);
|
||||
case "dmesg":
|
||||
return ok(
|
||||
"[ 0.000000] Booting Linux on physical CPU\n[ 1.234] i2c designware-pci 0000:00: i2c-0 adapter\n[ 2.567] gpio-mockup registered gpiochip0\n",
|
||||
);
|
||||
case "ls": {
|
||||
if (args[0] === "-1" && args[1] === "/dev/") {
|
||||
return ok(
|
||||
["gpiochip0", "gpiochip1", "i2c-0", "i2c-1", "null", "zero", "mmcblk0"].join("\n") +
|
||||
"\n",
|
||||
);
|
||||
}
|
||||
return fail;
|
||||
}
|
||||
default:
|
||||
return fail;
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// probeEnv — 正常收集
|
||||
// ============================================================================
|
||||
|
||||
describe("env-probe probeEnv — 正常收集", () => {
|
||||
it("kernel / arch 来自 uname", async () => {
|
||||
const probe = await probeEnv(makeMockExec());
|
||||
expect(probe.kernel).toBe("5.4.0-rdk-x5");
|
||||
expect(probe.arch).toBe("aarch64");
|
||||
});
|
||||
|
||||
it("board 来自 /proc/device-tree/model(去 \\0)", async () => {
|
||||
const probe = await probeEnv(makeMockExec());
|
||||
expect(probe.board).toBe("RDK X5");
|
||||
});
|
||||
|
||||
it("crossCompiler 取 aarch64-linux-gnu-gcc 首行版本", async () => {
|
||||
const probe = await probeEnv(makeMockExec());
|
||||
expect(probe.crossCompiler).toContain("aarch64-linux-gnu-gcc");
|
||||
expect(probe.crossCompiler).toContain("10.3.0");
|
||||
// 只取首行,不含 Copyright
|
||||
expect(probe.crossCompiler).not.toContain("Copyright");
|
||||
});
|
||||
|
||||
it("bareMetalCompiler 取 arm-none-eabi-gcc 首行", async () => {
|
||||
const probe = await probeEnv(makeMockExec());
|
||||
expect(probe.bareMetalCompiler).toContain("arm-none-eabi-gcc");
|
||||
});
|
||||
|
||||
it("gpioChips 从 /dev/ 过滤 gpiochip 前缀", async () => {
|
||||
const probe = await probeEnv(makeMockExec());
|
||||
expect(probe.gpioChips).toEqual(["gpiochip0", "gpiochip1"]);
|
||||
});
|
||||
|
||||
it("i2cBuses 从 /dev/ 过滤 i2c- 前缀", async () => {
|
||||
const probe = await probeEnv(makeMockExec());
|
||||
expect(probe.i2cBuses).toEqual(["i2c-0", "i2c-1"]);
|
||||
});
|
||||
|
||||
it("dmesgTail 含尾部内容(不空)", async () => {
|
||||
const probe = await probeEnv(makeMockExec());
|
||||
expect(probe.dmesgTail).toContain("i2c-0 adapter");
|
||||
expect(probe.dmesgTail).not.toBe(PROBE_UNAVAILABLE);
|
||||
});
|
||||
|
||||
it("gitHead 短 hash", async () => {
|
||||
const probe = await probeEnv(makeMockExec());
|
||||
expect(probe.gitHead).toBe("6a32ec9f");
|
||||
});
|
||||
|
||||
it("默认超时/dmesg 行数常量符合预期", () => {
|
||||
expect(DEFAULT_PROBE_TIMEOUT_MS).toBe(3_000);
|
||||
expect(DEFAULT_DMESG_LINES).toBe(20);
|
||||
expect(DEFAULT_TTL_MS).toBe(300_000);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// probeEnv — fail-closed 容错
|
||||
// ============================================================================
|
||||
|
||||
describe("env-probe probeEnv — fail-closed 容错", () => {
|
||||
it("交叉编译器不存在 → not installed(不抛)", async () => {
|
||||
const exec = makeMockExec({
|
||||
"aarch64-linux-gnu-gcc": () => ({ stdout: "", stderr: "not found", exitCode: 127 }),
|
||||
"arm-none-eabi-gcc": () => ({ stdout: "", stderr: "not found", exitCode: 127 }),
|
||||
});
|
||||
const probe = await probeEnv(exec);
|
||||
expect(probe.crossCompiler).toBe(PROBE_NOT_INSTALLED);
|
||||
expect(probe.bareMetalCompiler).toBe(PROBE_NOT_INSTALLED);
|
||||
});
|
||||
|
||||
it("exec 抛异常 → 各字段 fallback,probeEnv 不抛", async () => {
|
||||
const execThrow: ExecFn = async () => {
|
||||
throw new Error("spawn ENOENT");
|
||||
};
|
||||
const probe = await probeEnv(execThrow);
|
||||
expect(probe.kernel).toBe(PROBE_UNKNOWN);
|
||||
expect(probe.board).toBe(PROBE_UNKNOWN);
|
||||
expect(probe.crossCompiler).toBe(PROBE_NOT_INSTALLED);
|
||||
expect(probe.gitHead).toBe(PROBE_NOT_A_GIT_REPO);
|
||||
expect(probe.usbDevices).toBe(PROBE_NO_LSUSB);
|
||||
expect(probe.dmesgTail).toBe(PROBE_UNAVAILABLE);
|
||||
expect(probe.gpioChips).toEqual([]);
|
||||
expect(probe.i2cBuses).toEqual([]);
|
||||
});
|
||||
|
||||
it("lsusb 缺失 → lsusb not available", async () => {
|
||||
const exec = makeMockExec({
|
||||
lsusb: () => ({ stdout: "", stderr: "not found", exitCode: 127 }),
|
||||
});
|
||||
const probe = await probeEnv(exec);
|
||||
expect(probe.usbDevices).toBe(PROBE_NO_LSUSB);
|
||||
});
|
||||
|
||||
it("/proc/device-tree/model 不存在(非 ARM 板)→ unknown", async () => {
|
||||
const exec = makeMockExec({
|
||||
cat: () => ({ stdout: "", stderr: "No such file", exitCode: 1 }),
|
||||
});
|
||||
const probe = await probeEnv(exec);
|
||||
expect(probe.board).toBe(PROBE_UNKNOWN);
|
||||
});
|
||||
|
||||
it("dmesg 非零退出(权限不足)→ [unavailable]", async () => {
|
||||
const exec = makeMockExec({
|
||||
dmesg: () => ({ stdout: "", stderr: "Operation not permitted", exitCode: 1 }),
|
||||
});
|
||||
const probe = await probeEnv(exec);
|
||||
expect(probe.dmesgTail).toBe(PROBE_UNAVAILABLE);
|
||||
});
|
||||
|
||||
it("/dev/ 列空 → gpioChips/i2cBuses 空数组(不抛)", async () => {
|
||||
const exec = makeMockExec({
|
||||
ls: () => ({ stdout: "null\nzero\n", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const probe = await probeEnv(exec);
|
||||
expect(probe.gpioChips).toEqual([]);
|
||||
expect(probe.i2cBuses).toEqual([]);
|
||||
});
|
||||
|
||||
it("dmesg 尾部行数受 config.dmesgLines 控制", async () => {
|
||||
const probe = await probeEnv(makeMockExec(), { dmesgLines: 1 });
|
||||
// 只取最后 1 行
|
||||
expect(probe.dmesgTail).toBe("[ 2.567] gpio-mockup registered gpiochip0");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// 内部工具单测
|
||||
// ============================================================================
|
||||
|
||||
describe("env-probe 内部工具", () => {
|
||||
it("firstLine 取首行并 trim", () => {
|
||||
expect(firstLine("a\nb\nc")).toBe("a");
|
||||
expect(firstLine(" trim me \nsecond")).toBe("trim me");
|
||||
expect(firstLine("")).toBe("");
|
||||
});
|
||||
|
||||
it("filterDevEntries 按前缀过滤", () => {
|
||||
const out = "gpiochip0\ni2c-0\nnull\ngpiochip1\n";
|
||||
expect(filterDevEntries(out, "gpiochip")).toEqual(["gpiochip0", "gpiochip1"]);
|
||||
expect(filterDevEntries(out, "i2c-")).toEqual(["i2c-0"]);
|
||||
expect(filterDevEntries(out, "tty")).toEqual([]);
|
||||
});
|
||||
|
||||
it("renderList 空数组 → none", () => {
|
||||
expect(renderList([])).toBe("none");
|
||||
expect(renderList(["a", "b"])).toBe("a, b");
|
||||
});
|
||||
|
||||
it("safeProbe 非零退出返回 fallback", async () => {
|
||||
const exec: ExecFn = async () => ({ stdout: "", stderr: "x", exitCode: 1 });
|
||||
const out = await safeProbe(exec, "x", [], undefined, "FB");
|
||||
expect(out).toBe("FB");
|
||||
});
|
||||
|
||||
it("safeProbe stdout 空返回 fallback", async () => {
|
||||
const exec: ExecFn = async () => ({ stdout: " ", stderr: "", exitCode: 0 });
|
||||
const out = await safeProbe(exec, "x", [], undefined, "FB");
|
||||
expect(out).toBe("FB");
|
||||
});
|
||||
|
||||
it("safeProbe exec 抛异常返回 fallback", async () => {
|
||||
const exec: ExecFn = async () => {
|
||||
throw new Error("ENOENT");
|
||||
};
|
||||
const out = await safeProbe(exec, "x", [], undefined, "FB", (s) => s);
|
||||
expect(out).toBe("FB");
|
||||
});
|
||||
|
||||
it("makeExecFn 透传并补默认 timeout", async () => {
|
||||
let seen: ExecOpts | undefined;
|
||||
const exec: ExecFn = async (_c, _a, opts) => {
|
||||
seen = opts;
|
||||
return { stdout: "ok", stderr: "", exitCode: 0 };
|
||||
};
|
||||
const wrapped = makeExecFn(exec, 3000);
|
||||
await wrapped("uname", ["-r"]);
|
||||
expect(seen?.timeout).toBe(3000);
|
||||
// 调用方 opts 覆盖默认
|
||||
await wrapped("uname", ["-r"], { timeout: 500 });
|
||||
expect(seen?.timeout).toBe(500);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// buildEnvPrompt
|
||||
// ============================================================================
|
||||
|
||||
describe("env-probe buildEnvPrompt — 注入内容", () => {
|
||||
const sampleProbe: EnvProbe = {
|
||||
kernel: "5.4.0-rdk-x5",
|
||||
arch: "aarch64",
|
||||
board: "RDK X5",
|
||||
crossCompiler: "aarch64-linux-gnu-gcc (Ubuntu 10.3.0) 10.3.0",
|
||||
bareMetalCompiler: "not installed",
|
||||
hostCompiler: "gcc (Ubuntu 11.4.0) 11.4.0",
|
||||
dtc: "Version: DTC 1.6.0",
|
||||
gitHead: "6a32ec9f",
|
||||
usbDevices: "Bus 001 Device 001: ID 1d6b:0002",
|
||||
dmesgTail: "[ 1.234] i2c-0 adapter",
|
||||
gpioChips: ["gpiochip0", "gpiochip1"],
|
||||
i2cBuses: ["i2c-0", "i2c-1"],
|
||||
};
|
||||
|
||||
it("含 <embedded_environment> 开闭合标签", () => {
|
||||
const p = buildEnvPrompt(sampleProbe);
|
||||
expect(p.startsWith("<embedded_environment>")).toBe(true);
|
||||
expect(p.trim().endsWith("</embedded_environment>")).toBe(true);
|
||||
});
|
||||
|
||||
it("含交叉编译器行", () => {
|
||||
const p = buildEnvPrompt(sampleProbe);
|
||||
expect(p).toContain("Cross-compiler (aarch64-linux): aarch64-linux-gnu-gcc");
|
||||
});
|
||||
|
||||
it("含 i2c 总线列表", () => {
|
||||
const p = buildEnvPrompt(sampleProbe);
|
||||
expect(p).toContain("I2C buses: i2c-0, i2c-1");
|
||||
});
|
||||
|
||||
it("含 gpio chips 列表", () => {
|
||||
const p = buildEnvPrompt(sampleProbe);
|
||||
expect(p).toContain("GPIO chips: gpiochip0, gpiochip1");
|
||||
});
|
||||
|
||||
it("含 kernel + arch", () => {
|
||||
const p = buildEnvPrompt(sampleProbe);
|
||||
expect(p).toContain("Kernel: 5.4.0-rdk-x5 / aarch64");
|
||||
});
|
||||
|
||||
it("含 board model", () => {
|
||||
const p = buildEnvPrompt(sampleProbe);
|
||||
expect(p).toContain("Board model: RDK X5");
|
||||
});
|
||||
|
||||
it("含 dmesg 尾部(缩进)", () => {
|
||||
const p = buildEnvPrompt(sampleProbe);
|
||||
expect(p).toContain("dmesg tail:");
|
||||
expect(p).toContain(" [ 1.234] i2c-0 adapter");
|
||||
});
|
||||
|
||||
it("含 git HEAD", () => {
|
||||
const p = buildEnvPrompt(sampleProbe);
|
||||
expect(p).toContain("Git HEAD: 6a32ec9f");
|
||||
});
|
||||
|
||||
it("空 gpio/i2c → none", () => {
|
||||
const p = buildEnvPrompt({ ...sampleProbe, gpioChips: [], i2cBuses: [] });
|
||||
expect(p).toContain("GPIO chips: none");
|
||||
expect(p).toContain("I2C buses: none");
|
||||
});
|
||||
|
||||
it("裸机编译器 not installed 时原样渲染", () => {
|
||||
const p = buildEnvPrompt(sampleProbe);
|
||||
expect(p).toContain("Cross-compiler (bare-metal): not installed");
|
||||
});
|
||||
|
||||
it("dmesgTail 为 unavailable 时不缩进占位符", () => {
|
||||
const p = buildEnvPrompt({ ...sampleProbe, dmesgTail: PROBE_UNAVAILABLE });
|
||||
expect(p).toContain(`- dmesg tail:\n${PROBE_UNAVAILABLE}`);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// injectEnvPrompt / stripEnvBlocks — 链式叠加去重
|
||||
// ============================================================================
|
||||
|
||||
describe("env-probe injectEnvPrompt / stripEnvBlocks", () => {
|
||||
it("把探针块追加到既有 systemPrompt 尾部", () => {
|
||||
const p = injectEnvPrompt("You are a coding agent.", {
|
||||
kernel: "5.4.0",
|
||||
arch: "aarch64",
|
||||
board: "RDK X5",
|
||||
crossCompiler: "aarch64-linux-gnu-gcc 10.3.0",
|
||||
bareMetalCompiler: "not installed",
|
||||
hostCompiler: "gcc 11.4.0",
|
||||
dtc: "DTC 1.6.0",
|
||||
gitHead: "6a32ec9f",
|
||||
usbDevices: "lsusb not available",
|
||||
dmesgTail: "[unavailable]",
|
||||
gpioChips: ["gpiochip0"],
|
||||
i2cBuses: ["i2c-0"],
|
||||
});
|
||||
expect(p).toContain("You are a coding agent.");
|
||||
expect(p).toContain("<embedded_environment>");
|
||||
expect(p).toContain("</embedded_environment>");
|
||||
// 原文在前,探针块在后
|
||||
expect(p.indexOf("You are a coding agent.")).toBeLessThan(p.indexOf("<embedded_environment>"));
|
||||
});
|
||||
|
||||
it("重复注入不堆积:先剥离旧块再追加新块", () => {
|
||||
const probe: EnvProbe = {
|
||||
kernel: "5.4.0",
|
||||
arch: "aarch64",
|
||||
board: "RDK X5",
|
||||
crossCompiler: "aarch64-linux-gnu-gcc 10.3.0",
|
||||
bareMetalCompiler: "not installed",
|
||||
hostCompiler: "gcc 11.4.0",
|
||||
dtc: "DTC 1.6.0",
|
||||
gitHead: "abc1234",
|
||||
usbDevices: "lsusb not available",
|
||||
dmesgTail: "[unavailable]",
|
||||
gpioChips: [],
|
||||
i2cBuses: ["i2c-0"],
|
||||
};
|
||||
const first = injectEnvPrompt("base prompt", probe);
|
||||
// 二次注入(链式重入,新 gitHead)
|
||||
const second = injectEnvPrompt(first, { ...probe, gitHead: "deadbee" });
|
||||
const blockCount = (second.match(/<embedded_environment>/g) ?? []).length;
|
||||
expect(blockCount).toBe(1);
|
||||
expect(second).toContain("deadbee");
|
||||
expect(second).not.toContain("abc1234");
|
||||
});
|
||||
|
||||
it("stripEnvBlocks 剥离全部嵌入块", () => {
|
||||
const withBlock =
|
||||
"hello\n\n<embedded_environment>\nfoo\n</embedded_environment>\n\nworld";
|
||||
expect(stripEnvBlocks(withBlock)).toBe("hello\n\nworld");
|
||||
});
|
||||
|
||||
it("stripEnvBlocks 无块时原样(trimEnd)", () => {
|
||||
expect(stripEnvBlocks("plain prompt")).toBe("plain prompt");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ProbeCacheStore — TTL + cwd 失效
|
||||
// ============================================================================
|
||||
|
||||
describe("env-probe ProbeCacheStore — 缓存失效", () => {
|
||||
const probe: EnvProbe = {
|
||||
kernel: "5.4.0",
|
||||
arch: "aarch64",
|
||||
board: "RDK X5",
|
||||
crossCompiler: "gcc",
|
||||
bareMetalCompiler: "not installed",
|
||||
hostCompiler: "gcc",
|
||||
dtc: "DTC",
|
||||
gitHead: "abc1234",
|
||||
usbDevices: "none",
|
||||
dmesgTail: "[unavailable]",
|
||||
gpioChips: [],
|
||||
i2cBuses: [],
|
||||
};
|
||||
|
||||
it("首次 get 返回 null,set 后命中", () => {
|
||||
const store = new ProbeCacheStore();
|
||||
expect(store.get(DEFAULT_TTL_MS, "/cwd")).toBeNull();
|
||||
store.set(probe, "/cwd");
|
||||
expect(store.get(DEFAULT_TTL_MS, "/cwd")).toBe(probe);
|
||||
expect(store.has()).toBe(true);
|
||||
});
|
||||
|
||||
it("cwd 变化即失效", () => {
|
||||
const store = new ProbeCacheStore();
|
||||
store.set(probe, "/cwd-a");
|
||||
expect(store.get(DEFAULT_TTL_MS, "/cwd-a")).toBe(probe);
|
||||
expect(store.get(DEFAULT_TTL_MS, "/cwd-b")).toBeNull();
|
||||
});
|
||||
|
||||
it("TTL 过期即失效", async () => {
|
||||
const store = new ProbeCacheStore();
|
||||
store.set(probe, "/cwd");
|
||||
// ttl=1ms,等一下即过期
|
||||
await new Promise((r) => setTimeout(r, 20));
|
||||
expect(store.get(1, "/cwd")).toBeNull();
|
||||
});
|
||||
|
||||
it("clear 后清空", () => {
|
||||
const store = new ProbeCacheStore();
|
||||
store.set(probe, "/cwd");
|
||||
store.clear();
|
||||
expect(store.has()).toBe(false);
|
||||
expect(store.get(DEFAULT_TTL_MS, "/cwd")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// summarizeProbe — env_status 工具快照
|
||||
// ============================================================================
|
||||
|
||||
describe("env-probe summarizeProbe — 工具快照", () => {
|
||||
it("产出精简字段 + cached 标记", () => {
|
||||
const probe: EnvProbe = {
|
||||
kernel: "5.4.0-rdk-x5",
|
||||
arch: "aarch64",
|
||||
board: "RDK X5",
|
||||
crossCompiler: "aarch64-linux-gnu-gcc 10.3.0",
|
||||
bareMetalCompiler: "not installed",
|
||||
hostCompiler: "gcc 11.4.0",
|
||||
dtc: "DTC 1.6.0",
|
||||
gitHead: "6a32ec9f",
|
||||
usbDevices: "Bus 001",
|
||||
dmesgTail: "[unavailable]",
|
||||
gpioChips: ["gpiochip0"],
|
||||
i2cBuses: ["i2c-0", "i2c-1"],
|
||||
};
|
||||
const s = summarizeProbe(probe, true);
|
||||
expect(s.kernel).toBe("5.4.0-rdk-x5");
|
||||
expect(s.board).toBe("RDK X5");
|
||||
expect(s.crossCompiler).toContain("10.3.0");
|
||||
expect(s.i2cBuses).toEqual(["i2c-0", "i2c-1"]);
|
||||
expect(s.gpioChips).toEqual(["gpiochip0"]);
|
||||
expect(s.cached).toBe(true);
|
||||
// 精简:不含 hostCompiler/dtc 等冗余字段
|
||||
expect("hostCompiler" in s).toBe(false);
|
||||
});
|
||||
});
|
||||
488
tests/flash.test.ts
Normal file
488
tests/flash.test.ts
Normal file
@ -0,0 +1,488 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { createHash } from "node:crypto";
|
||||
import {
|
||||
planFlash,
|
||||
dryRun,
|
||||
verifyFlash,
|
||||
runFlash,
|
||||
parseOffset,
|
||||
parseLsblk,
|
||||
isRootDiskTarget,
|
||||
targetExistsInRows,
|
||||
deviceBasename,
|
||||
ROOT_MOUNTPOINTS,
|
||||
splitCommand,
|
||||
type FlashPlanEx,
|
||||
} from "../src/extensions/flash.js";
|
||||
import type { ExecFn } from "../src/shared/types.js";
|
||||
|
||||
// ---- mock helpers ----
|
||||
|
||||
/** 构造 ExecFn:按 command 路由到不同 mock 分支。 */
|
||||
function mockExec(handlers: Record<string, (args: string[]) => { stdout: string; stderr: string; exitCode: number }>): ExecFn {
|
||||
return async (command, args) => {
|
||||
const h = handlers[command];
|
||||
if (!h) return { stdout: "", stderr: `command not found: ${command}`, exitCode: 127 };
|
||||
return h(args);
|
||||
};
|
||||
}
|
||||
|
||||
const LSBLK_ROOT_ON_SDA = `NAME SIZE TYPE MOUNTPOINT
|
||||
sda 500000000000 disk
|
||||
├─sda1 536870912 part /boot
|
||||
└─sda2 499000000000 part /
|
||||
mmcblk0 32000000000 disk
|
||||
└─mmcblk0p1 32000000000 part`;
|
||||
|
||||
const LSBLK_MMCBLK0_NO_ROOT = `NAME SIZE TYPE MOUNTPOINT
|
||||
mmcblk0 32000000000 disk
|
||||
└─mmcblk0p1 32000000000 part
|
||||
sda 500000000000 disk`;
|
||||
|
||||
// ============================================================================
|
||||
// planFlash
|
||||
// ============================================================================
|
||||
|
||||
describe("flash planFlash — 各 method 命令构建", () => {
|
||||
it("dd: 生成 dd if=.. of=.. bs=4M conv=fsync", () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
|
||||
expect(plan.method).toBe("dd");
|
||||
expect(plan.target).toBe("/dev/mmcblk0");
|
||||
expect(plan.image).toBe("sdcard.img");
|
||||
expect(plan.commands).toHaveLength(1);
|
||||
expect(plan.commands[0]).toBe("dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync");
|
||||
// 无 offset → 不带 seek=,offsetBytes 为 undefined
|
||||
expect(plan.commands[0]).not.toContain("seek=");
|
||||
});
|
||||
|
||||
it("dd + offset: 带 seek= 块数(字节 8388608 → 2 块)", () => {
|
||||
const plan = planFlash("dd", "rootfs.img", "/dev/mmcblk0", { offset: "8388608" });
|
||||
expect(plan.commands[0]).toContain("seek=2");
|
||||
expect(plan.offsetBytes).toBe(8388608);
|
||||
});
|
||||
|
||||
it("dd + hex offset 0x800000 → seek=2", () => {
|
||||
const plan = planFlash("dd", "rootfs.img", "/dev/mmcblk0", { offset: "0x800000" });
|
||||
expect(plan.offsetBytes).toBe(0x800000);
|
||||
expect(plan.commands[0]).toContain("seek=2");
|
||||
});
|
||||
|
||||
it("fastboot: 带分区名", () => {
|
||||
const plan = planFlash("fastboot", "boot.img", "serial", { partition: "boot" });
|
||||
expect(plan.commands[0]).toBe("fastboot flash boot boot.img");
|
||||
});
|
||||
|
||||
it("dfu: target=vid:pid + alt", () => {
|
||||
const plan = planFlash("dfu", "firmware.bin", "0483:df11", { partition: "0" });
|
||||
expect(plan.commands[0]).toBe("dfu-util -d 0483:df11 -a 0 -D firmware.bin");
|
||||
});
|
||||
|
||||
it("openocd: program + verify reset exit", () => {
|
||||
const plan = planFlash("openocd", "firmware.elf", "openocd.cfg");
|
||||
expect(plan.commands[0]).toBe('openocd -f openocd.cfg -c "program firmware.elf verify reset exit"');
|
||||
});
|
||||
|
||||
it("非法 method 抛错", () => {
|
||||
expect(() => planFlash("bogus" as never, "x", "/dev/sda")).toThrow(/unsupported method/);
|
||||
});
|
||||
|
||||
it("空 image 抛错", () => {
|
||||
expect(() => planFlash("dd", "", "/dev/mmcblk0")).toThrow(/image path required/);
|
||||
});
|
||||
|
||||
it("空 target 抛错", () => {
|
||||
expect(() => planFlash("dd", "img", "")).toThrow(/target required/);
|
||||
});
|
||||
|
||||
it("非法 offset 抛错", () => {
|
||||
expect(() => planFlash("dd", "img", "/dev/mmcblk0", { offset: "not-a-number" })).toThrow(/invalid offset/);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// parseOffset / parseLsblk / isRootDiskTarget
|
||||
// ============================================================================
|
||||
|
||||
describe("flash parseOffset", () => {
|
||||
it("十进制字符串", () => {
|
||||
expect(parseOffset("8388608")).toBe(8388608);
|
||||
});
|
||||
it("0x hex", () => {
|
||||
expect(parseOffset("0x800000")).toBe(0x800000);
|
||||
});
|
||||
it("空/undefined → 0", () => {
|
||||
expect(parseOffset(undefined)).toBe(0);
|
||||
expect(parseOffset("")).toBe(0);
|
||||
});
|
||||
it("非法 → null", () => {
|
||||
expect(parseOffset("abc")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("flash parseLsblk", () => {
|
||||
it("解析多行含树形字符", () => {
|
||||
const rows = parseLsblk(LSBLK_ROOT_ON_SDA);
|
||||
expect(rows.length).toBeGreaterThanOrEqual(4);
|
||||
const sda1 = rows.find((r) => r.name === "sda1");
|
||||
expect(sda1).toBeDefined();
|
||||
expect(sda1?.mountpoint).toBe("/boot");
|
||||
const sda2 = rows.find((r) => r.name === "sda2");
|
||||
expect(sda2?.mountpoint).toBe("/");
|
||||
});
|
||||
|
||||
it("跳过表头", () => {
|
||||
const rows = parseLsblk("NAME SIZE TYPE MOUNTPOINT\nsda 1000 disk");
|
||||
expect(rows).toHaveLength(1);
|
||||
expect(rows[0]?.name).toBe("sda");
|
||||
});
|
||||
});
|
||||
|
||||
describe("flash isRootDiskTarget", () => {
|
||||
it("/dev/sda 是宿主系统盘(sda2 挂载 /)", () => {
|
||||
expect(isRootDiskTarget("/dev/sda", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(true);
|
||||
});
|
||||
it("/dev/sda1 根分区(/boot)", () => {
|
||||
expect(isRootDiskTarget("/dev/sda1", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(true);
|
||||
});
|
||||
it("/dev/mmcblk0 未挂载根 → false", () => {
|
||||
expect(isRootDiskTarget("/dev/mmcblk0", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(false);
|
||||
});
|
||||
it("/dev/mmcblk0 在无根盘场景 → false", () => {
|
||||
expect(isRootDiskTarget("/dev/mmcblk0", parseLsblk(LSBLK_MMCBLK0_NO_ROOT))).toBe(false);
|
||||
});
|
||||
it("不存在的设备 → false(但 targetExistsInRows 为 false)", () => {
|
||||
expect(isRootDiskTarget("/dev/zzz", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("flash targetExistsInRows / deviceBasename / splitCommand", () => {
|
||||
it("/dev/mmcblk0 存在", () => {
|
||||
expect(targetExistsInRows("/dev/mmcblk0", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(true);
|
||||
});
|
||||
it("/dev/zzz 不存在", () => {
|
||||
expect(targetExistsInRows("/dev/zzz", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(false);
|
||||
});
|
||||
it("deviceBasename 提取", () => {
|
||||
expect(deviceBasename("/dev/sda1")).toBe("sda1");
|
||||
expect(deviceBasename("/dev/mmcblk0p2")).toBe("mmcblk0p2");
|
||||
});
|
||||
it("ROOT_MOUNTPOINTS 含 /", () => {
|
||||
expect(ROOT_MOUNTPOINTS.has("/")).toBe(true);
|
||||
expect(ROOT_MOUNTPOINTS.has("/boot")).toBe(true);
|
||||
});
|
||||
it("splitCommand 保留引号内整体", () => {
|
||||
const tokens = splitCommand('openocd -f openocd.cfg -c "program fw.elf verify reset exit"');
|
||||
expect(tokens[0]).toBe("openocd");
|
||||
expect(tokens[1]).toBe("-f");
|
||||
expect(tokens[2]).toBe("openocd.cfg");
|
||||
expect(tokens[3]).toBe("-c");
|
||||
expect(tokens[4]).toBe("program fw.elf verify reset exit");
|
||||
});
|
||||
it("splitCommand 普通命令", () => {
|
||||
const tokens = splitCommand("dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync");
|
||||
expect(tokens[0]).toBe("dd");
|
||||
expect(tokens).toHaveLength(5);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// dryRun
|
||||
// ============================================================================
|
||||
|
||||
describe("flash dryRun — fail-closed 拒根盘", () => {
|
||||
it("/dev/sda(宿主系统盘)被拒", async () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/sda");
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_ROOT_ON_SDA, stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.isRootDisk).toBe(true);
|
||||
expect(r.targetExists).toBe(true);
|
||||
expect(r.reason).toContain("/dev/sda");
|
||||
expect(r.reason).toContain("mounted");
|
||||
expect(r.reason).toContain("/");
|
||||
});
|
||||
|
||||
it("/dev/sda1(根分区 /boot)被拒", async () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/sda1");
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_ROOT_ON_SDA, stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.isRootDisk).toBe(true);
|
||||
expect(r.reason).toContain("/boot");
|
||||
});
|
||||
|
||||
it("target 不存在被拒", async () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/zzz");
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.targetExists).toBe(false);
|
||||
expect(r.reason).toContain("not found");
|
||||
});
|
||||
|
||||
it("/dev/mmcblk0(合法 SD 卡)dry-run 通过 + 预计算 sha256", async () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
|
||||
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
|
||||
sha256sum: () => ({ stdout: "deadbeefcafebabe0000000000000000000000000000000000000000000000ff sdcard.img\n", stderr: "", exitCode: 0 }),
|
||||
dd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.isRootDisk).toBe(false);
|
||||
expect(plan.expectedSha256).toBe("deadbeefcafebabe0000000000000000000000000000000000000000000000ff");
|
||||
expect(plan.imageSizeBytes).toBe(4294967296);
|
||||
expect(plan.blockCount).toBe(1024); // 4GiB / 4MiB
|
||||
});
|
||||
|
||||
it("offset 越过镜像大小被拒", async () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0", { offset: "999999999999" });
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
|
||||
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
|
||||
sha256sum: () => ({ stdout: "abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabca img\n", stderr: "", exitCode: 0 }),
|
||||
dd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.reason).toContain("offset");
|
||||
});
|
||||
|
||||
it("lsblk 失败被拒", async () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: "", stderr: "command not found", exitCode: 127 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.reason).toContain("lsblk failed");
|
||||
});
|
||||
|
||||
it("dry-run 不执行任何写操作(probeCommands 不含 of=/dev/mmcblk0 的写真写)", async () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
|
||||
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
|
||||
sha256sum: () => ({ stdout: "a".repeat(64) + " img\n", stderr: "", exitCode: 0 }),
|
||||
dd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(true);
|
||||
// 所有探测命令不应含 of=/dev/mmcblk0(写真写目标)
|
||||
for (const c of r.probeCommands) {
|
||||
expect(c).not.toContain("of=/dev/mmcblk0");
|
||||
}
|
||||
// 应含 of=/dev/null(只读探针)
|
||||
expect(r.probeCommands.some((c) => c.includes("of=/dev/null"))).toBe(true);
|
||||
});
|
||||
|
||||
it("fastboot dry-run 跑 getvar all", async () => {
|
||||
const plan = planFlash("fastboot", "boot.img", "serial", { partition: "boot" });
|
||||
const fn = mockExec({
|
||||
fastboot: () => ({ stdout: "OKAY [ 0.001s]", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.probeCommands[0]).toContain("getvar all");
|
||||
});
|
||||
|
||||
it("openocd dry-run 跑 init+exit", async () => {
|
||||
const plan = planFlash("openocd", "fw.elf", "openocd.cfg");
|
||||
const fn = mockExec({
|
||||
openocd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.probeCommands[0]).toContain("init");
|
||||
});
|
||||
|
||||
it("dfu dry-run 跑 dfu-util -l", async () => {
|
||||
const plan = planFlash("dfu", "fw.bin", "0483:df11");
|
||||
const fn = mockExec({
|
||||
"dfu-util": () => ({ stdout: "Found DFU: 0483:df11", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await dryRun(plan, fn);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.probeCommands[0]).toContain("-l");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// verifyFlash
|
||||
// ============================================================================
|
||||
|
||||
describe("flash verifyFlash — dd sha256 校验", () => {
|
||||
it("sha 匹配 → ok", async () => {
|
||||
// 读回 stdout "hello" → sha256
|
||||
const readback = "hello";
|
||||
const expected = createHash("sha256").update(readback).digest("hex");
|
||||
const plan: FlashPlanEx = {
|
||||
method: "dd",
|
||||
commands: ["dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync"],
|
||||
target: "/dev/mmcblk0",
|
||||
image: "sdcard.img",
|
||||
expectedSha256: expected,
|
||||
blockCount: 1,
|
||||
};
|
||||
const fn = mockExec({
|
||||
dd: () => ({ stdout: readback, stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await verifyFlash(plan, fn);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.expected).toBe(expected);
|
||||
expect(r.actual).toBe(expected);
|
||||
});
|
||||
|
||||
it("sha 不匹配 → VERIFY FAILED", async () => {
|
||||
const plan: FlashPlanEx = {
|
||||
method: "dd",
|
||||
commands: ["dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync"],
|
||||
target: "/dev/mmcblk0",
|
||||
image: "sdcard.img",
|
||||
expectedSha256: "a".repeat(64),
|
||||
blockCount: 2,
|
||||
};
|
||||
const fn = mockExec({
|
||||
dd: () => ({ stdout: "different-bytes", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await verifyFlash(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.expected).toBe("a".repeat(64));
|
||||
expect(r.actual).not.toBe("a".repeat(64));
|
||||
expect(r.reason).toContain("VERIFY FAILED");
|
||||
});
|
||||
|
||||
it("无 expectedSha256(未 dry-run)→ 拒绝", async () => {
|
||||
const plan: FlashPlanEx = {
|
||||
method: "dd",
|
||||
commands: ["dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync"],
|
||||
target: "/dev/mmcblk0",
|
||||
image: "sdcard.img",
|
||||
};
|
||||
const fn = mockExec({ dd: () => ({ stdout: "", stderr: "", exitCode: 0 }) });
|
||||
const r = await verifyFlash(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.reason).toContain("expectedSha256");
|
||||
});
|
||||
|
||||
it("读回 dd 失败 → fail", async () => {
|
||||
const plan: FlashPlanEx = {
|
||||
method: "dd",
|
||||
commands: ["dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync"],
|
||||
target: "/dev/mmcblk0",
|
||||
image: "sdcard.img",
|
||||
expectedSha256: "a".repeat(64),
|
||||
blockCount: 1,
|
||||
};
|
||||
const fn = mockExec({
|
||||
dd: () => ({ stdout: "", stderr: "read error", exitCode: 1 }),
|
||||
});
|
||||
const r = await verifyFlash(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.reason).toContain("readback dd failed");
|
||||
});
|
||||
|
||||
it("openocd verify 走 verify_image exitCode", async () => {
|
||||
const plan: FlashPlanEx = {
|
||||
method: "openocd",
|
||||
commands: ['openocd -f openocd.cfg -c "program fw.elf verify reset exit"'],
|
||||
target: "openocd.cfg",
|
||||
image: "fw.elf",
|
||||
};
|
||||
const fn = mockExec({
|
||||
openocd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await verifyFlash(plan, fn);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.verifyCommand).toContain("verify_image");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// runFlash 三段式编排
|
||||
// ============================================================================
|
||||
|
||||
describe("flash runFlash — 三段式编排", () => {
|
||||
it("dry_run=true(skipWrite)只 dry-run 不写真写", async () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
|
||||
let ddCalled = false;
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
|
||||
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
|
||||
sha256sum: () => ({ stdout: "a".repeat(64) + " img\n", stderr: "", exitCode: 0 }),
|
||||
dd: (args) => {
|
||||
// dry-run 阶段 dd 是 of=/dev/null 探针;写真写不会触发
|
||||
if (args.includes("of=/dev/null")) return { stdout: "", stderr: "", exitCode: 0 };
|
||||
ddCalled = true; // 真写 dd(of=/dev/mmcblk0)
|
||||
return { stdout: "", stderr: "", exitCode: 0 };
|
||||
},
|
||||
});
|
||||
const r = await runFlash(plan, fn, { skipWrite: true });
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.written).toBe(false);
|
||||
expect(ddCalled).toBe(false);
|
||||
});
|
||||
|
||||
it("dry-run 失败时不写真写", async () => {
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/sda");
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_ROOT_ON_SDA, stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const r = await runFlash(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.written).toBe(false);
|
||||
expect(r.reason).toContain("mounted");
|
||||
});
|
||||
|
||||
it("全流程:dry-run → 写 → verify 全过", async () => {
|
||||
const readback = "image-bytes";
|
||||
const expected = createHash("sha256").update(readback).digest("hex");
|
||||
// 用一个自定义 plan 跳过 stat/sha256(已填 expectedSha256)—— 但 runFlash 会先 dryRun
|
||||
// 重新算 sha256 覆盖 expectedSha256。故让 sha256sum mock 返回 expected。
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
|
||||
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
|
||||
sha256sum: () => ({ stdout: expected + " sdcard.img\n", stderr: "", exitCode: 0 }),
|
||||
dd: (args) => {
|
||||
// of=/dev/null → 读探针;of=/dev/mmcblk0 无 count → 真写;
|
||||
// of=/dev/mmcblk0 + count → verify 读回
|
||||
if (args.includes("of=/dev/null")) return { stdout: "", stderr: "", exitCode: 0 };
|
||||
if (args.some((a) => a.startsWith("count="))) return { stdout: readback, stderr: "", exitCode: 0 };
|
||||
return { stdout: "", stderr: "", exitCode: 0 }; // 真写
|
||||
},
|
||||
});
|
||||
const r = await runFlash(plan, fn);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.written).toBe(true);
|
||||
expect(r.writeExitCodes).toEqual([0]);
|
||||
expect(r.verify?.ok).toBe(true);
|
||||
});
|
||||
|
||||
it("写真写命令失败 → ok:false", async () => {
|
||||
const expected = createHash("sha256").update("x").digest("hex");
|
||||
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
|
||||
const fn = mockExec({
|
||||
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
|
||||
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
|
||||
sha256sum: () => ({ stdout: expected + " sdcard.img\n", stderr: "", exitCode: 0 }),
|
||||
dd: (args) => {
|
||||
if (args.includes("of=/dev/null")) return { stdout: "", stderr: "", exitCode: 0 };
|
||||
if (args.some((a) => a.startsWith("count="))) return { stdout: "x", stderr: "", exitCode: 0 };
|
||||
return { stdout: "", stderr: "write protected", exitCode: 1 }; // 真写失败
|
||||
},
|
||||
});
|
||||
const r = await runFlash(plan, fn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.written).toBe(true);
|
||||
expect(r.writeExitCodes).toEqual([1]);
|
||||
expect(r.reason).toContain("write command failed");
|
||||
});
|
||||
});
|
||||
162
tests/glm-provider.test.ts
Normal file
162
tests/glm-provider.test.ts
Normal file
@ -0,0 +1,162 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
buildGlmModelConfig,
|
||||
toProviderConfig,
|
||||
normalizeHexArg,
|
||||
normalizeToolArguments,
|
||||
makeHexNormalizingPrepareArguments,
|
||||
detectEmptyOutput,
|
||||
GLM_MODEL_ID,
|
||||
GLM_PROVIDER_NAME,
|
||||
} from "../src/extensions/glm-provider.js";
|
||||
|
||||
describe("glm-provider 命门一 — buildGlmModelConfig", () => {
|
||||
it("model id 带中划线 glm-5.2(实测真实 id)", () => {
|
||||
const cfg = buildGlmModelConfig();
|
||||
expect(cfg.id).toBe("glm-5.2");
|
||||
expect(cfg.id).toBe(GLM_MODEL_ID);
|
||||
expect(cfg.provider).toBe(GLM_PROVIDER_NAME);
|
||||
});
|
||||
|
||||
it("thinkingLevelMap 全 null(关掉 reasoning 映射)", () => {
|
||||
const cfg = buildGlmModelConfig();
|
||||
expect(cfg.thinkingLevelMap.off).toBeNull();
|
||||
expect(cfg.thinkingLevelMap.low).toBeNull();
|
||||
expect(cfg.thinkingLevelMap.medium).toBeNull();
|
||||
expect(cfg.thinkingLevelMap.high).toBeNull();
|
||||
});
|
||||
|
||||
it("thinkingFormat=qwen 落在 compat(触发 enable_thinking:false 分支)", () => {
|
||||
const cfg = buildGlmModelConfig();
|
||||
expect(cfg.compat.thinkingFormat).toBe("qwen");
|
||||
expect(cfg.supportsReasoningEffort).toBe(false);
|
||||
});
|
||||
|
||||
it("maxTokens 提到 8192,不再是缺陷默认 2048", () => {
|
||||
const cfg = buildGlmModelConfig();
|
||||
expect(cfg.maxTokens).toBe(8192);
|
||||
expect(cfg.maxTokens).not.toBe(2048);
|
||||
});
|
||||
|
||||
it("key 用环境占位 ${DROBOTICS_LLM_KEY},绝不硬编码", () => {
|
||||
const cfg = buildGlmModelConfig();
|
||||
expect(cfg.apiKey).toBe("${DROBOTICS_LLM_KEY}");
|
||||
expect(cfg.apiKey).not.toMatch(/sk-nAm/i);
|
||||
});
|
||||
|
||||
it("toProviderConfig 结构可喂 registerProvider", () => {
|
||||
const { name, config } = toProviderConfig(buildGlmModelConfig());
|
||||
expect(name).toBe(GLM_PROVIDER_NAME);
|
||||
expect(config.authHeader).toBe(true);
|
||||
expect(config.models).toHaveLength(1);
|
||||
const model = config.models?.[0] as unknown as {
|
||||
id: string;
|
||||
compat: { thinkingFormat: string } | undefined;
|
||||
};
|
||||
expect(model.id).toBe("glm-5.2");
|
||||
expect(model.compat?.thinkingFormat).toBe("qwen");
|
||||
expect(config.apiKey).toBe("${DROBOTICS_LLM_KEY}");
|
||||
});
|
||||
});
|
||||
|
||||
describe("glm-provider 命门二 — normalizeHexArg", () => {
|
||||
it("还原被强转成十进制的 32 位寄存器地址 0x40020000", () => {
|
||||
const r = normalizeHexArg("1073872896");
|
||||
expect(r.corrected).toBe(true);
|
||||
expect(r.value).toBe("0x40020000");
|
||||
expect(r.original).toBe("1073872896");
|
||||
});
|
||||
|
||||
it("已是 0x 形式的值不动", () => {
|
||||
const r = normalizeHexArg("0x40020000");
|
||||
expect(r.corrected).toBe(false);
|
||||
expect(r.value).toBe("0x40020000");
|
||||
});
|
||||
|
||||
it("number 类型也还原", () => {
|
||||
const r = normalizeHexArg(1073872896);
|
||||
expect(r.corrected).toBe(true);
|
||||
expect(r.value).toBe("0x40020000");
|
||||
});
|
||||
|
||||
it("小十进制(baudrate 115200)不误转——6 位 < minDigits 8", () => {
|
||||
const r = normalizeHexArg("115200");
|
||||
expect(r.corrected).toBe(false);
|
||||
expect(r.value).toBe("115200");
|
||||
});
|
||||
|
||||
it("字段 denylist 保护 baudrate/timeout 不转", () => {
|
||||
const { normalized, corrections } = normalizeToolArguments(
|
||||
{ baudrate: "115200", address: "1073872896", timeout: "30000" },
|
||||
{ fieldDenylist: ["baudrate", "timeout"] },
|
||||
);
|
||||
expect(normalized.baudrate).toBe("115200");
|
||||
expect(normalized.timeout).toBe("30000");
|
||||
expect(normalized.address).toBe("0x40020000");
|
||||
expect(corrections).toHaveLength(1);
|
||||
expect(corrections[0]?.field).toBe("address");
|
||||
});
|
||||
|
||||
it("递归嵌套对象也能归一", () => {
|
||||
const { normalized, corrections } = normalizeToolArguments({
|
||||
reg: { base: "1073872896", ctrl: "0x40020004" },
|
||||
items: ["1073872896", "115200"],
|
||||
});
|
||||
const reg = normalized.reg as { base: string; ctrl: string };
|
||||
const items = normalized.items as string[];
|
||||
expect(reg.base).toBe("0x40020000");
|
||||
expect(reg.ctrl).toBe("0x40020004");
|
||||
expect(items[0]).toBe("0x40020000");
|
||||
expect(items[1]).toBe("115200");
|
||||
expect(corrections.length).toBe(2);
|
||||
});
|
||||
|
||||
it("makeHexNormalizingPrepareArguments 工厂可用", () => {
|
||||
const prep = makeHexNormalizingPrepareArguments({ fieldDenylist: ["baudrate"] });
|
||||
const out = prep({ address: "1073872896", baudrate: "115200" }) as Record<string, unknown>;
|
||||
expect(out.address).toBe("0x40020000");
|
||||
expect(out.baudrate).toBe("115200");
|
||||
});
|
||||
|
||||
it("64 位大地址用 BigInt 不丢精度", () => {
|
||||
const big = (0xdeadbeefcafe0000n).toString();
|
||||
const r = normalizeHexArg(big, { maxRange: 0xffffffffffffffff });
|
||||
expect(r.corrected).toBe(true);
|
||||
expect(r.value).toBe("0x" + (0xdeadbeefcafe0000n).toString(16));
|
||||
});
|
||||
|
||||
it("null/undefined/路径字符串安全", () => {
|
||||
expect(normalizeHexArg(null).corrected).toBe(false);
|
||||
expect(normalizeHexArg(undefined).corrected).toBe(false);
|
||||
expect(normalizeHexArg("/dev/i2c-1").corrected).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("glm-provider 空输出检测 — detectEmptyOutput", () => {
|
||||
it("有文本内容 → 不空", () => {
|
||||
expect(detectEmptyOutput({ textContent: "hello", stopReason: "stop" }).empty).toBe(false);
|
||||
});
|
||||
|
||||
it("有 tool_call → 不空", () => {
|
||||
expect(detectEmptyOutput({ textContent: "", toolCallCount: 1, stopReason: "tool_use" }).empty).toBe(false);
|
||||
});
|
||||
|
||||
it("命门一典型症状:空内容 + stop=length → thinking-overflow", () => {
|
||||
const d = detectEmptyOutput({ textContent: "", stopReason: "length" });
|
||||
expect(d.empty).toBe(true);
|
||||
expect(d.reason).toBe("thinking-overflow");
|
||||
expect(d.remediation).toContain("thinkingFormat");
|
||||
});
|
||||
|
||||
it("空内容 + 有 thinking 块 → thinking-overflow", () => {
|
||||
const d = detectEmptyOutput({ textContent: "", thinkingContent: "</think>" });
|
||||
expect(d.empty).toBe(true);
|
||||
expect(d.reason).toBe("thinking-overflow");
|
||||
});
|
||||
|
||||
it("空内容无 thinking 无 length → no-content-no-tool", () => {
|
||||
const d = detectEmptyOutput({ textContent: "", stopReason: "stop" });
|
||||
expect(d.empty).toBe(true);
|
||||
expect(d.reason).toBe("no-content-no-tool");
|
||||
});
|
||||
});
|
||||
281
tests/hardware-state.test.ts
Normal file
281
tests/hardware-state.test.ts
Normal file
@ -0,0 +1,281 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
makeHwEntry,
|
||||
replayFromEntries,
|
||||
selectProtected,
|
||||
formatHwStateAsText,
|
||||
buildCompactionProtection,
|
||||
HW_STATE_CUSTOM_TYPE,
|
||||
type HwEntry,
|
||||
} from "../src/extensions/hardware-state.js";
|
||||
|
||||
// 辅助:构造一条 hw entry,ts 固定
|
||||
function hw(type: string, data: Record<string, unknown>, ts: number): HwEntry {
|
||||
return makeHwEntry(type, data, ts);
|
||||
}
|
||||
|
||||
describe("hardware-state 序列化 — makeHwEntry", () => {
|
||||
it("产出 CustomEntry{customType:'hw:state', data:{type,data,ts}}", () => {
|
||||
const e = makeHwEntry("i2c", { bus: 0, occupiedAddresses: [0x48, 0x68] }, 1730000000000);
|
||||
expect(e.customType).toBe("hw:state");
|
||||
expect(e.data.type).toBe("i2c");
|
||||
expect(e.data.ts).toBe(1730000000000);
|
||||
expect(e.data.data).toEqual({ bus: 0, occupiedAddresses: [0x48, 0x68] });
|
||||
});
|
||||
|
||||
it("HW_STATE_CUSTOM_TYPE 常量 = 'hw:state'", () => {
|
||||
expect(HW_STATE_CUSTOM_TYPE).toBe("hw:state");
|
||||
});
|
||||
|
||||
it("省略 timestamp 时用 Date.now() 填充 ts", () => {
|
||||
const before = Date.now();
|
||||
const e = makeHwEntry("gpio", { pin: 33, direction: "out" });
|
||||
const after = Date.now();
|
||||
expect(e.data.ts).toBeGreaterThanOrEqual(before);
|
||||
expect(e.data.ts).toBeLessThanOrEqual(after);
|
||||
});
|
||||
|
||||
it("data 为空对象也合法(fail-open 不崩)", () => {
|
||||
const e = makeHwEntry("serial", {}, 1);
|
||||
expect(e.data.data).toEqual({});
|
||||
expect(e.data.type).toBe("serial");
|
||||
});
|
||||
|
||||
it("data 可携带任意嵌套结构(gdb 断点表)", () => {
|
||||
const e = makeHwEntry(
|
||||
"gdb",
|
||||
{ breakpoints: [{ file: "main.c", line: 42, enabled: true }] },
|
||||
5,
|
||||
);
|
||||
const bp = (e.data.data as { breakpoints: Array<{ line: number }> }).breakpoints;
|
||||
expect(bp[0]?.line).toBe(42);
|
||||
});
|
||||
|
||||
it("序列化+反序列化 round-trip 保留数据(JSONL 持久化模拟)", () => {
|
||||
const e = makeHwEntry("openocd", { target: "stm32", state: "halted" }, 99);
|
||||
const json = JSON.stringify(e);
|
||||
const back = JSON.parse(json) as HwEntry;
|
||||
expect(back.customType).toBe("hw:state");
|
||||
expect(back.data.type).toBe("openocd");
|
||||
expect(back.data.ts).toBe(99);
|
||||
expect((back.data.data as { target: string }).target).toBe("stm32");
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-state 重放重建 — replayFromEntries", () => {
|
||||
it("lock acquire/release 重建 locks 表", () => {
|
||||
const entries = [
|
||||
hw("lock", { device: "i2c-bus-0", owner: "call-A", action: "acquire" }, 1),
|
||||
hw("lock", { device: "gpiochip0", owner: "call-A", action: "acquire" }, 2),
|
||||
hw("lock", { device: "i2c-bus-0", owner: "call-A", action: "release" }, 3),
|
||||
];
|
||||
const r = replayFromEntries(entries);
|
||||
expect(r.locks["i2c-bus-0"]).toBeUndefined();
|
||||
expect(r.locks["gpiochip0"]).toBe("call-A");
|
||||
});
|
||||
|
||||
it("同设备 acquire 覆盖 owner(最后一次胜)", () => {
|
||||
const entries = [
|
||||
hw("lock", { device: "i2c-bus-0", owner: "A", action: "acquire" }, 1),
|
||||
hw("lock", { device: "i2c-bus-0", owner: "B", action: "acquire" }, 2),
|
||||
];
|
||||
const r = replayFromEntries(entries);
|
||||
expect(r.locks["i2c-bus-0"]).toBe("B");
|
||||
});
|
||||
|
||||
it("i2c occupiedAddresses 落成锁(每地址一条)", () => {
|
||||
const entries = [
|
||||
hw("i2c", { bus: 1, occupiedAddresses: [0x48, 0x68], owner: "probe" }, 10),
|
||||
];
|
||||
const r = replayFromEntries(entries);
|
||||
expect(r.locks["i2c-1-72"]).toBe("probe"); // 0x48=72
|
||||
expect(r.locks["i2c-1-104"]).toBe("probe"); // 0x68=104
|
||||
});
|
||||
|
||||
it("checkpoint 重建最新状态 + 累积 history", () => {
|
||||
const entries = [
|
||||
hw("checkpoint", { step: "edit", passed: true }, 100),
|
||||
hw("checkpoint", { step: "compile", passed: true }, 200),
|
||||
hw("checkpoint", { step: "flash", passed: false }, 300),
|
||||
];
|
||||
const r = replayFromEntries(entries);
|
||||
expect(r.checkpoint).not.toBeNull();
|
||||
expect(r.checkpoint!.currentStep).toBe("flash");
|
||||
expect(r.checkpoint!.stepPassed).toBe(false);
|
||||
expect(r.checkpoint!.history).toHaveLength(3);
|
||||
expect(r.checkpoint!.history[2]?.passed).toBe(false);
|
||||
});
|
||||
|
||||
it("flashLog 按序累积", () => {
|
||||
const entries = [
|
||||
hw("flash", { method: "dd", target: "/dev/mmcblk0", image: "boot.img", result: "ok" }, 1),
|
||||
hw("flash", { method: "openocd", target: "stm32", image: "fw.elf", sha256: "abc", result: "fail" }, 2),
|
||||
];
|
||||
const r = replayFromEntries(entries);
|
||||
expect(r.flashLog).toHaveLength(2);
|
||||
expect(r.flashLog[0]!.method).toBe("dd");
|
||||
expect(r.flashLog[0]!.result).toBe("ok");
|
||||
expect(r.flashLog[1]!.method).toBe("openocd");
|
||||
expect(r.flashLog[1]!.sha256).toBe("abc");
|
||||
expect(r.flashLog[1]!.result).toBe("fail");
|
||||
});
|
||||
|
||||
it("忽略非 hw:state entry(向后兼容,旧 session 不崩)", () => {
|
||||
const entries = [
|
||||
{ customType: "glm:adapter-loaded", data: {} } as unknown as HwEntry,
|
||||
{ type: "custom", customType: "safegate:override", data: {} } as unknown as HwEntry,
|
||||
hw("lock", { device: "i2c-bus-0", owner: "A", action: "acquire" }, 1),
|
||||
];
|
||||
const r = replayFromEntries(entries);
|
||||
expect(r.locks["i2c-bus-0"]).toBe("A");
|
||||
expect(r.flashLog).toHaveLength(0);
|
||||
expect(r.checkpoint).toBeNull();
|
||||
});
|
||||
|
||||
it("空 entries 数组返回空状态", () => {
|
||||
const r = replayFromEntries([]);
|
||||
expect(r.locks).toEqual({});
|
||||
expect(r.checkpoint).toBeNull();
|
||||
expect(r.flashLog).toEqual([]);
|
||||
});
|
||||
|
||||
it("乱序/缺字段 lock entry fail-closed 不崩", () => {
|
||||
const entries = [
|
||||
hw("lock", {}, 1),
|
||||
hw("lock", { device: "x" }, 2),
|
||||
hw("i2c", {}, 3),
|
||||
];
|
||||
const r = replayFromEntries(entries);
|
||||
// 不抛异常;device:"x" 无 owner 仍记一条空 owner 锁,无幽灵条目
|
||||
expect(Object.keys(r.locks)).toEqual(["x"]);
|
||||
expect(r.locks["x"]).toBe("");
|
||||
expect(r.flashLog).toEqual([]);
|
||||
expect(r.checkpoint).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-state compaction 保护 — selectProtected", () => {
|
||||
it("返回最近 N 条 hw entry(keepLatestPerType:false 严格截断)", () => {
|
||||
const entries = [
|
||||
hw("i2c", { bus: 0 }, 1),
|
||||
hw("gpio", { pin: 33 }, 2),
|
||||
hw("gdb", { bp: 1 }, 3),
|
||||
hw("serial", { baud: 115200 }, 4),
|
||||
hw("flash", { method: "dd" }, 5),
|
||||
];
|
||||
const prot = selectProtected(entries, { keepRecent: 3, keepLatestPerType: false });
|
||||
expect(prot).toHaveLength(3);
|
||||
expect(prot[0]!.data.type).toBe("gdb");
|
||||
expect(prot[2]!.data.type).toBe("flash");
|
||||
});
|
||||
|
||||
it("默认 keepLatestPerType=true 时每类型代表都存活(5 类型全保留)", () => {
|
||||
const entries = [
|
||||
hw("i2c", { bus: 0 }, 1),
|
||||
hw("gpio", { pin: 33 }, 2),
|
||||
hw("gdb", { bp: 1 }, 3),
|
||||
hw("serial", { baud: 115200 }, 4),
|
||||
hw("flash", { method: "dd" }, 5),
|
||||
];
|
||||
const prot = selectProtected(entries, { keepRecent: 3 });
|
||||
// 5 个不同类型,最近 3 条覆盖 gdb/serial/flash,补齐 i2c/gpio → 5 条
|
||||
expect(prot).toHaveLength(5);
|
||||
const types = prot.map((e) => e.data.type);
|
||||
expect(types.sort()).toEqual(["flash", "gdb", "gpio", "i2c", "serial"]);
|
||||
});
|
||||
|
||||
it("keepLatestPerType 保证每类型至少最新一条存活(跨 N 不丢关键状态)", () => {
|
||||
const entries = [
|
||||
hw("i2c", { bus: 0 }, 1),
|
||||
hw("i2c", { bus: 1 }, 2),
|
||||
hw("gpio", { pin: 33 }, 3),
|
||||
hw("flash", { method: "dd" }, 4),
|
||||
hw("flash", { method: "dd" }, 5),
|
||||
];
|
||||
// keepRecent=1 会只留最后 1 条,但 keepLatestPerType 会补齐每类型最新
|
||||
const prot = selectProtected(entries, { keepRecent: 1, keepLatestPerType: true });
|
||||
const types = prot.map((e) => e.data.type);
|
||||
expect(types).toContain("i2c");
|
||||
expect(types).toContain("gpio");
|
||||
expect(types).toContain("flash");
|
||||
// i2c 最新是 bus:1
|
||||
const i2cEntry = prot.find((e) => e.data.type === "i2c")!;
|
||||
expect((i2cEntry.data.data as { bus: number }).bus).toBe(1);
|
||||
});
|
||||
|
||||
it("keepLatestPerType=false 时严格只取最近 N 条", () => {
|
||||
const entries = [
|
||||
hw("i2c", { bus: 0 }, 1),
|
||||
hw("gpio", { pin: 33 }, 2),
|
||||
hw("flash", { method: "dd" }, 3),
|
||||
];
|
||||
const prot = selectProtected(entries, { keepRecent: 1, keepLatestPerType: false });
|
||||
expect(prot).toHaveLength(1);
|
||||
expect(prot[0]!.data.type).toBe("flash");
|
||||
});
|
||||
|
||||
it("无 hw entry 返回空数组", () => {
|
||||
const prot = selectProtected([]);
|
||||
expect(prot).toEqual([]);
|
||||
});
|
||||
|
||||
it("hw entry 少于 N 时全部保留", () => {
|
||||
const entries = [hw("i2c", { bus: 0 }, 1)];
|
||||
const prot = selectProtected(entries, { keepRecent: 5 });
|
||||
expect(prot).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-state 上下文格式化 — formatHwStateAsText", () => {
|
||||
it("产出 LLM 可读多行文本,含 type 与 ts", () => {
|
||||
const e = makeHwEntry("i2c", { bus: 0, occupiedAddresses: [0x48] }, 1730000000000);
|
||||
const txt = formatHwStateAsText(e);
|
||||
expect(txt).toContain("hw:state");
|
||||
expect(txt).toContain("i2c");
|
||||
expect(txt).toContain("bus");
|
||||
// 0x48=72, JSON.stringify 数组 → [72]
|
||||
expect(txt).toContain("72");
|
||||
expect(txt).toContain("2024");
|
||||
});
|
||||
|
||||
it("嵌套对象以 JSON 序列化呈现", () => {
|
||||
const e = makeHwEntry("gdb", { bps: [{ file: "a.c", line: 1 }] }, 1);
|
||||
const txt = formatHwStateAsText(e);
|
||||
expect(txt).toContain("bps");
|
||||
expect(txt).toContain("a.c");
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-state compaction 注入 — buildCompactionProtection", () => {
|
||||
it("找到最后一条 hw entry,把 firstKeptEntryId 拉到它并扩展 summary", () => {
|
||||
const branch = [
|
||||
{ type: "custom", customType: "glm:adapter-loaded", data: {}, id: "e1" },
|
||||
{ type: "custom", customType: "hw:state", data: { type: "i2c", data: { bus: 0 }, ts: 1 }, id: "e2" },
|
||||
{ type: "user", id: "e3", customType: undefined, data: undefined },
|
||||
];
|
||||
const prep = { summary: "prev", previousSummary: "prev", firstKeptEntryId: "e3" };
|
||||
const res = buildCompactionProtection(branch, prep);
|
||||
expect(res).not.toBeNull();
|
||||
expect(res!.compaction.firstKeptEntryId).toBe("e2");
|
||||
expect(res!.compaction.summary).toContain("Hardware State");
|
||||
expect(res!.compaction.summary).toContain("i2c");
|
||||
});
|
||||
|
||||
it("无 hw entry 时返回 null(不干预 compaction)", () => {
|
||||
const branch = [
|
||||
{ type: "custom", customType: "glm:adapter-loaded", data: {}, id: "e1" },
|
||||
];
|
||||
const res = buildCompactionProtection(branch, { summary: "prev" });
|
||||
expect(res).toBeNull();
|
||||
});
|
||||
|
||||
it("previousSummary 为空时仍能拼出 Hardware State 段", () => {
|
||||
const branch = [
|
||||
{ type: "custom", customType: "hw:state", data: { type: "gpio", data: { pin: 33 }, ts: 1 }, id: "e1" },
|
||||
];
|
||||
const res = buildCompactionProtection(branch, null);
|
||||
expect(res).not.toBeNull();
|
||||
expect(res!.compaction.summary).toContain("Hardware State");
|
||||
expect(res!.compaction.firstKeptEntryId).toBe("e1");
|
||||
});
|
||||
});
|
||||
267
tests/hardware-verify.test.ts
Normal file
267
tests/hardware-verify.test.ts
Normal file
@ -0,0 +1,267 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
collectSignal,
|
||||
matchExpect,
|
||||
runVerify,
|
||||
buildSignalCommand,
|
||||
filterDmesg,
|
||||
describeSignal,
|
||||
toNumber,
|
||||
} from "../src/extensions/hardware-verify.js";
|
||||
import type { ExecFn, ExecResult, SignalSpec, ExpectSpec } from "../src/shared/types.js";
|
||||
|
||||
// ---- mock 工具 ----
|
||||
|
||||
/** 构造一个按 command→stdout 映射返回 exitCode=0 的 ExecFn。 */
|
||||
function mockExec(map: Record<string, string | ExecResult>): ExecFn {
|
||||
return async (command: string, args: string[]) => {
|
||||
const key = command + " " + args.join(" ");
|
||||
// 先试精确 key,再试 command 前缀
|
||||
const hit = map[key] ?? map[command];
|
||||
if (hit === undefined) {
|
||||
return { stdout: "", stderr: `command not found: ${key}`, exitCode: 127 };
|
||||
}
|
||||
if (typeof hit === "string") return { stdout: hit, stderr: "", exitCode: 0 };
|
||||
return hit;
|
||||
};
|
||||
}
|
||||
|
||||
const failResult = (stderr: string, code = 1): ExecResult => ({ stdout: "", stderr, exitCode: code });
|
||||
|
||||
describe("hardware-verify matchExpect — 各 mode", () => {
|
||||
it("contains: 子串命中", () => {
|
||||
expect(matchExpect("gpio33 value=1 active", { match: "value=1", mode: "contains" })).toBe(true);
|
||||
});
|
||||
it("contains: 子串未命中 → false", () => {
|
||||
expect(matchExpect("gpio33 value=0", { match: "value=1", mode: "contains" })).toBe(false);
|
||||
});
|
||||
it("equals: 精确匹配(trim)", () => {
|
||||
expect(matchExpect(" 1 ", { match: "1", mode: "equals" })).toBe(true);
|
||||
});
|
||||
it("regex: 正则命中", () => {
|
||||
expect(matchExpect("[ 3.14] gpio-33 set HIGH", { match: "gpio.*33", mode: "regex" })).toBe(true);
|
||||
});
|
||||
it("regex: 非法正则 → false(不抛)", () => {
|
||||
expect(matchExpect("abc", { match: "(", mode: "regex" })).toBe(false);
|
||||
});
|
||||
it("range: 数值落在区间内", () => {
|
||||
expect(matchExpect("512", { match: 0, mode: "range", min: 0, max: 1023 })).toBe(true);
|
||||
});
|
||||
it("range: 超上界 → false", () => {
|
||||
expect(matchExpect("2000", { match: 0, mode: "range", min: 0, max: 1023 })).toBe(false);
|
||||
});
|
||||
it("gt: 严格大于", () => {
|
||||
expect(matchExpect("1", { match: 0, mode: "gt" })).toBe(true);
|
||||
expect(matchExpect("0", { match: 0, mode: "gt" })).toBe(false);
|
||||
});
|
||||
it("gt: 非数字 → false", () => {
|
||||
expect(matchExpect("err", { match: 1, mode: "gt" })).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-verify toNumber", () => {
|
||||
it("解析整数", () => {
|
||||
expect(toNumber("512")).toBe(512);
|
||||
});
|
||||
it("非数字 → NaN", () => {
|
||||
expect(toNumber("abc")).toBeNaN();
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-verify buildSignalCommand", () => {
|
||||
it("gpio → gpioget chip line", () => {
|
||||
const c = buildSignalCommand({ type: "gpio", args: { chip: "gpiochip0", line: "33" } });
|
||||
expect(c).not.toBeNull();
|
||||
expect(c!.command).toBe("gpioget");
|
||||
expect(c!.args).toEqual(["gpiochip0", "33"]);
|
||||
});
|
||||
it("gpio 缺 chip → null(fail-closed 前置)", () => {
|
||||
expect(buildSignalCommand({ type: "gpio", args: { line: "33" } })).toBeNull();
|
||||
});
|
||||
it("i2c → i2cget -y bus addr reg", () => {
|
||||
const c = buildSignalCommand({ type: "i2c", args: { bus: "0", addr: "0x76", reg: "0x10" } });
|
||||
expect(c!.command).toBe("i2cget");
|
||||
expect(c!.args).toEqual(["-y", "0", "0x76", "0x10"]);
|
||||
});
|
||||
it("i2c 无 reg 也合法", () => {
|
||||
const c = buildSignalCommand({ type: "i2c", args: { bus: "1", addr: "0x50" } });
|
||||
expect(c!.args).toEqual(["-y", "1", "0x50"]);
|
||||
});
|
||||
it("sysfs → cat path", () => {
|
||||
const c = buildSignalCommand({ type: "sysfs", args: { path: "/sys/class/gpio/gpio33/value" } });
|
||||
expect(c!.command).toBe("cat");
|
||||
expect(c!.args).toEqual(["/sys/class/gpio/gpio33/value"]);
|
||||
});
|
||||
it("stdout 缺 command → null", () => {
|
||||
expect(buildSignalCommand({ type: "stdout", args: {} })).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-verify filterDmesg", () => {
|
||||
it("按 grep 正则过滤行", () => {
|
||||
const out = "[ 1.0] gpio-33 HIGH\n[ 2.0] i2c-0 ready\n[ 3.0] gpio-33 LOW";
|
||||
const r = filterDmesg(out, "gpio.*33");
|
||||
expect(r).toContain("gpio-33 HIGH");
|
||||
expect(r).toContain("gpio-33 LOW");
|
||||
expect(r).not.toContain("i2c-0");
|
||||
});
|
||||
it("无 grep 返回 trim 后的全部", () => {
|
||||
expect(filterDmesg(" a\nb ")).toBe("a\nb");
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-verify collectSignal(注入 mock)", () => {
|
||||
it("gpio 采集返回 gpioget stdout", async () => {
|
||||
const fn = mockExec({ "gpioget gpiochip0 33": "1" });
|
||||
const v = await collectSignal({ type: "gpio", args: { chip: "gpiochip0", line: "33" } }, fn);
|
||||
expect(v).toBe("1");
|
||||
});
|
||||
it("dmesg 采集应用 grep 过滤", async () => {
|
||||
const fn = mockExec({ dmesg: "[1] gpio-33 HIGH\n[2] usb ready" });
|
||||
const v = await collectSignal({ type: "dmesg", args: { grep: "gpio.*33" } }, fn);
|
||||
expect(v).toBe("[1] gpio-33 HIGH");
|
||||
});
|
||||
it("fail-closed: 非零退出 → 抛错", async () => {
|
||||
const fn = mockExec({ "gpioget gpiochip0 33": failResult("Permission denied", 1) });
|
||||
await expect(
|
||||
collectSignal({ type: "gpio", args: { chip: "gpiochip0", line: "33" } }, fn),
|
||||
).rejects.toThrow(/exited 1/);
|
||||
});
|
||||
it("fail-closed: 命令构建失败(缺参数)→ 抛错", async () => {
|
||||
const fn = mockExec({});
|
||||
await expect(collectSignal({ type: "gpio", args: {} }, fn)).rejects.toThrow(/cannot build/);
|
||||
});
|
||||
it("fail-closed: ExecFn 抛异常 → 包装后抛出", async () => {
|
||||
const fn: ExecFn = async () => {
|
||||
throw new Error("board unreachable");
|
||||
};
|
||||
await expect(
|
||||
collectSignal({ type: "gpio", args: { chip: "gpiochip0", line: "33" } }, fn),
|
||||
).rejects.toThrow(/board unreachable/);
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-verify describeSignal", () => {
|
||||
it("gpio 描述", () => {
|
||||
expect(describeSignal({ type: "gpio", args: { chip: "gpiochip0", line: "33" } })).toBe(
|
||||
"gpiogpiochip0:33",
|
||||
);
|
||||
});
|
||||
it("sysfs 描述", () => {
|
||||
expect(describeSignal({ type: "sysfs", args: { path: "/sys/class/gpio/gpio33/value" } })).toBe(
|
||||
"sysfs:/sys/class/gpio/gpio33/value",
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("hardware-verify runVerify — 四元组 + fail-closed", () => {
|
||||
it("全部匹配 → judge pass, rootCause null", async () => {
|
||||
const fn = mockExec({
|
||||
"gpioget gpiochip0 33": "1",
|
||||
"cat /sys/class/gpio/gpio33/value": "1",
|
||||
});
|
||||
const rec = await runVerify(
|
||||
"GPIO pin 33 output high",
|
||||
[
|
||||
{ type: "gpio", args: { chip: "gpiochip0", line: "33" } },
|
||||
{ type: "sysfs", args: { path: "/sys/class/gpio/gpio33/value" } },
|
||||
],
|
||||
{ match: "1", mode: "equals", failClosed: true },
|
||||
fn,
|
||||
);
|
||||
expect(rec.task).toBe("GPIO pin 33 output high");
|
||||
expect(rec.judge).toBe("pass");
|
||||
expect(rec.rootCause).toBeNull();
|
||||
expect(rec.trace).toHaveLength(2);
|
||||
expect(rec.trace[0]?.matched).toBe(true);
|
||||
expect(rec.trace[1]?.matched).toBe(true);
|
||||
});
|
||||
|
||||
it("GPIO 33 短路到地 → judge fail, rootCause 含 value 与 expected", async () => {
|
||||
const fn = mockExec({
|
||||
"gpioget gpiochip0 33": "0", // 短路到地,读出 0
|
||||
});
|
||||
const rec = await runVerify(
|
||||
"GPIO pin 33 output high",
|
||||
[{ type: "gpio", args: { chip: "gpiochip0", line: "33" } }],
|
||||
{ match: "1", mode: "equals", failClosed: true },
|
||||
fn,
|
||||
);
|
||||
expect(rec.judge).toBe("fail");
|
||||
expect(rec.rootCause).toContain("0");
|
||||
expect(rec.rootCause).toContain("expected");
|
||||
expect(rec.rootCause).toContain("1");
|
||||
expect(rec.trace[0]?.collected).toBe("0");
|
||||
expect(rec.trace[0]?.matched).toBe(false);
|
||||
});
|
||||
|
||||
it("采集失败 → fail-closed 判 fail,rootCause 含 collection-failed", async () => {
|
||||
const fn = mockExec({
|
||||
"gpioget gpiochip0 33": failResult("Permission denied", 1),
|
||||
});
|
||||
const rec = await runVerify(
|
||||
"GPIO pin 33 output high",
|
||||
[{ type: "gpio", args: { chip: "gpiochip0", line: "33" } }],
|
||||
{ match: "1", mode: "equals", failClosed: true },
|
||||
fn,
|
||||
);
|
||||
expect(rec.judge).toBe("fail");
|
||||
expect(rec.rootCause).toContain("collection-failed");
|
||||
expect(rec.trace[0]?.collected).toBe("");
|
||||
expect(rec.trace[0]?.matched).toBe(false);
|
||||
});
|
||||
|
||||
it("多信号部分失败 → rootCause 含每条失败描述(;分隔)", async () => {
|
||||
const fn = mockExec({
|
||||
"gpioget gpiochip0 33": "0", // 不匹配 expect 1
|
||||
"cat /sys/class/gpio/gpio33/value": "1", // 匹配
|
||||
"gpioget gpiochip0 34": failResult("no such line", 1), // 采集失败
|
||||
});
|
||||
const rec = await runVerify(
|
||||
"multi-signal check",
|
||||
[
|
||||
{ type: "gpio", args: { chip: "gpiochip0", line: "33" } },
|
||||
{ type: "sysfs", args: { path: "/sys/class/gpio/gpio33/value" } },
|
||||
{ type: "gpio", args: { chip: "gpiochip0", line: "34" } },
|
||||
],
|
||||
{ match: "1", mode: "equals", failClosed: true },
|
||||
fn,
|
||||
);
|
||||
expect(rec.judge).toBe("fail");
|
||||
expect(rec.rootCause).toContain(";");
|
||||
// 失败条数 = 2(gpio33 value 不匹配 + gpio34 采集失败)
|
||||
const parts = rec.rootCause!.split("; ");
|
||||
expect(parts.length).toBe(2);
|
||||
});
|
||||
|
||||
it("空 signals 列表 → judge pass(vacuously true)", async () => {
|
||||
const fn = mockExec({});
|
||||
const rec = await runVerify("noop", [], { match: "1", mode: "equals" }, fn);
|
||||
expect(rec.judge).toBe("pass");
|
||||
expect(rec.trace).toHaveLength(0);
|
||||
expect(rec.rootCause).toBeNull();
|
||||
});
|
||||
|
||||
it("range 模式集成:电流在阈值内 → pass", async () => {
|
||||
const fn = mockExec({ "cat /sys/hwmon/current": "320" });
|
||||
const rec = await runVerify(
|
||||
"motor stall current ok",
|
||||
[{ type: "current", args: { path: "/sys/hwmon/current" } }],
|
||||
{ match: 0, mode: "range", min: 0, max: 500, failClosed: true },
|
||||
fn,
|
||||
);
|
||||
expect(rec.judge).toBe("pass");
|
||||
});
|
||||
|
||||
it("range 模式集成:电流超阈值 → fail", async () => {
|
||||
const fn = mockExec({ "cat /sys/hwmon/current": "1200" });
|
||||
const rec = await runVerify(
|
||||
"motor stall current ok",
|
||||
[{ type: "current", args: { path: "/sys/hwmon/current" } }],
|
||||
{ match: 0, mode: "range", min: 0, max: 500, failClosed: true },
|
||||
fn,
|
||||
);
|
||||
expect(rec.judge).toBe("fail");
|
||||
expect(rec.rootCause).toContain("1200");
|
||||
});
|
||||
});
|
||||
413
tests/jtag-debugger.test.ts
Normal file
413
tests/jtag-debugger.test.ts
Normal file
@ -0,0 +1,413 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
parseMiLine,
|
||||
parseMiFields,
|
||||
splitNameAndFields,
|
||||
unquoteStream,
|
||||
normalizeAddr,
|
||||
normalizeValue,
|
||||
DebuggerSession,
|
||||
restoreBreakpoints,
|
||||
snapshotBreakpoints,
|
||||
type MiLine,
|
||||
} from "../src/extensions/jtag-debugger.js";
|
||||
|
||||
describe("jtag-debugger parseMiLine — 控制台流", () => {
|
||||
it("~ console 流解析", () => {
|
||||
const m = parseMiLine('~"Loading target description\n"');
|
||||
expect(m.type).toBe("console");
|
||||
const p = m.payload as { stream: string; text: string };
|
||||
expect(p.stream).toBe("console");
|
||||
expect(p.text).toBe("Loading target description\n");
|
||||
});
|
||||
|
||||
it("@ target 流解析", () => {
|
||||
const m = parseMiLine('@"Hello from target\r\n"');
|
||||
expect(m.type).toBe("console");
|
||||
const p = m.payload as { stream: string; text: string };
|
||||
expect(p.stream).toBe("target");
|
||||
expect(p.text).toBe("Hello from target\r\n");
|
||||
});
|
||||
|
||||
it("& log 流解析", () => {
|
||||
const m = parseMiLine('&"warning: something\n"');
|
||||
expect(m.type).toBe("console");
|
||||
const p = m.payload as { stream: string; text: string };
|
||||
expect(p.stream).toBe("log");
|
||||
expect(p.text).toBe("warning: something\n");
|
||||
});
|
||||
|
||||
it("(gdb) prompt 标记 → console 空", () => {
|
||||
const m = parseMiLine("(gdb)");
|
||||
expect(m.type).toBe("console");
|
||||
expect((m.payload as { text: string }).text).toBe("");
|
||||
});
|
||||
|
||||
it("空行 → console 空(fail-closed 不抛错)", () => {
|
||||
expect(parseMiLine("").type).toBe("console");
|
||||
expect(parseMiLine(" ").type).toBe("console");
|
||||
expect(parseMiLine(" ").type).not.toBe("stopped");
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger parseMiLine — stopped 异步事件", () => {
|
||||
it("*stopped breakpoint-hit 带 frame", () => {
|
||||
const line =
|
||||
'*stopped,reason="breakpoint-hit",bkptno="1",disp="keep",frame={addr="0x08001000",func="main",file="main.c",fullname="/src/main.c",line="42"},thread-id="1",stopped-threads="all"';
|
||||
const m = parseMiLine(line);
|
||||
expect(m.type).toBe("stopped");
|
||||
const p = m.payload as {
|
||||
reason: string;
|
||||
addr?: string;
|
||||
frame?: Record<string, unknown>;
|
||||
bkptno?: string;
|
||||
threadId?: string;
|
||||
};
|
||||
expect(p.reason).toBe("breakpoint-hit");
|
||||
expect(p.addr).toBe("0x08001000");
|
||||
expect(p.bkptno).toBe("1");
|
||||
expect(p.threadId).toBe("1");
|
||||
expect(p.frame?.func).toBe("main");
|
||||
expect(p.frame?.line).toBe("42");
|
||||
});
|
||||
|
||||
it("*stopped end stepping range 取 frame.addr", () => {
|
||||
const m = parseMiLine('*stopped,reason="end-stepping-range",frame={addr="0x08001100",func="delay"}');
|
||||
expect(m.type).toBe("stopped");
|
||||
const p = m.payload as { reason: string; addr?: string };
|
||||
expect(p.reason).toBe("end-stepping-range");
|
||||
expect(p.addr).toBe("0x08001100");
|
||||
});
|
||||
|
||||
it("*stopped 顶层 addr(无 frame)兜底", () => {
|
||||
const m = parseMiLine('*stopped,reason="signal-received",addr="0x00000004"');
|
||||
expect(m.type).toBe("stopped");
|
||||
const p = m.payload as { reason: string; addr?: string };
|
||||
expect(p.addr).toBe("0x00000004");
|
||||
});
|
||||
|
||||
it("*stopped 无 reason → unknown(fail-closed 不抛)", () => {
|
||||
const m = parseMiLine('*stopped,thread-id="1"');
|
||||
expect(m.type).toBe("stopped");
|
||||
expect((m.payload as { reason: string }).reason).toBe("unknown");
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger parseMiLine — running", () => {
|
||||
it("*running → running", () => {
|
||||
const m = parseMiLine('*running,thread-id="all"');
|
||||
expect(m.type).toBe("running");
|
||||
expect(m.type).not.toBe("stopped");
|
||||
});
|
||||
|
||||
it("^running → running", () => {
|
||||
const m = parseMiLine("^running");
|
||||
expect(m.type).toBe("running");
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger parseMiLine — breakpoint 结果记录", () => {
|
||||
it('^done,bkpt={...} → breakpoint', () => {
|
||||
const line =
|
||||
'^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",addr="0x08001000",func="main",file="main.c",line="42"}';
|
||||
const m = parseMiLine(line);
|
||||
expect(m.type).toBe("breakpoint");
|
||||
const p = m.payload as { number?: string; addr?: string; type?: string; enabled?: string };
|
||||
expect(p.number).toBe("1");
|
||||
expect(p.addr).toBe("0x08001000");
|
||||
expect(p.type).toBe("breakpoint");
|
||||
expect(p.enabled).toBe("y");
|
||||
});
|
||||
|
||||
it("^done(无 bkpt)→ console 兜底", () => {
|
||||
const m = parseMiLine("^done");
|
||||
expect(m.type).toBe("console");
|
||||
expect((m.payload as { text: string }).text).toBe("done");
|
||||
});
|
||||
|
||||
it('^error,msg="..." → console 兜底', () => {
|
||||
const m = parseMiLine('^error,msg="No registers."');
|
||||
expect(m.type).toBe("console");
|
||||
const p = m.payload as { text: string; fields: Record<string, unknown> };
|
||||
expect(p.text).toBe("error");
|
||||
expect(p.fields.msg).toBe("No registers.");
|
||||
});
|
||||
|
||||
it("未识别裸行 → console(不抛错)", () => {
|
||||
const m = parseMiLine("some garbage line");
|
||||
expect(m.type).toBe("console");
|
||||
expect((m.payload as { text: string }).text).toBe("some garbage line");
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger parseMiFields — 嵌套/转义", () => {
|
||||
it("嵌套对象递归解析", () => {
|
||||
const f = parseMiFields('a="1",b={x="2",y={z="3"}},c="4"');
|
||||
expect(f.a).toBe("1");
|
||||
expect(f.c).toBe("4");
|
||||
const b = f.b as Record<string, unknown>;
|
||||
expect(b.x).toBe("2");
|
||||
const y = b.y as Record<string, unknown>;
|
||||
expect(y.z).toBe("3");
|
||||
});
|
||||
|
||||
it("引号内逗号/大括号不破坏顶层切分(通过 stopped 行间接验证)", () => {
|
||||
// frame 里有引号包裹的逗号内容不应拆错
|
||||
const m = parseMiLine('*stopped,reason="breakpoint-hit",frame={addr="0x08001000",func="main,with,commas"}');
|
||||
const p = m.payload as { frame?: Record<string, unknown> };
|
||||
expect(p.frame?.func).toBe("main,with,commas");
|
||||
});
|
||||
|
||||
it("转义字符 (newline/tab/backslash/quote) 还原", () => {
|
||||
const f = parseMiFields('msg="line1\\nline2\\t\\\\"');
|
||||
expect(f.msg).toBe('line1\nline2\t\\');
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger splitNameAndFields / unquoteStream", () => {
|
||||
it("splitNameAndFields 顶层逗号切分", () => {
|
||||
const { name, fieldsStr } = splitNameAndFields('stopped,reason="bp"');
|
||||
expect(name).toBe("stopped");
|
||||
expect(fieldsStr).toBe('reason="bp"');
|
||||
});
|
||||
|
||||
it("splitNameAndFields 无逗号返回整体", () => {
|
||||
const { name, fieldsStr } = splitNameAndFields("running");
|
||||
expect(name).toBe("running");
|
||||
expect(fieldsStr).toBe("");
|
||||
});
|
||||
|
||||
it("splitNameAndFields 大括号内逗号不切分", () => {
|
||||
const { name, fieldsStr } = splitNameAndFields('done,bkpt={addr="0x1",func="f"}');
|
||||
expect(name).toBe("done");
|
||||
expect(fieldsStr).toBe('bkpt={addr="0x1",func="f"}');
|
||||
});
|
||||
|
||||
it("unquoteStream 去引号 + 反转义", () => {
|
||||
expect(unquoteStream('"hi\\nthere"')).toBe("hi\nthere");
|
||||
});
|
||||
|
||||
it("unquoteStream 无引号原样返回", () => {
|
||||
expect(unquoteStream("bare")).toBe("bare");
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger normalizeAddr — 缺陷 #8 防御", () => {
|
||||
it("已是 0x → 小写化", () => {
|
||||
expect(normalizeAddr("0x08001000")).toBe("0x08001000");
|
||||
expect(normalizeAddr("0x40021000")).toBe("0x40021000");
|
||||
});
|
||||
|
||||
it("纯十进制强转地址还原成 hex(1073872896 → 0x40020000)", () => {
|
||||
// glm-5.2 实测把 0x40021000 强转成 "1073872896"
|
||||
expect(normalizeAddr("1073872896")).toBe("0x40020000");
|
||||
});
|
||||
|
||||
it("64 位大地址 BigInt 不丢精度", () => {
|
||||
expect(normalizeAddr((0xdeadbeefcafe0000n).toString())).toBe("0xdeadbeefcafe0000");
|
||||
});
|
||||
|
||||
it("符号(main)原样返回", () => {
|
||||
expect(normalizeAddr("main")).toBe("main");
|
||||
expect(normalizeAddr("read_handler")).toBe("read_handler");
|
||||
});
|
||||
|
||||
it("空串安全", () => {
|
||||
expect(normalizeAddr("")).toBe("");
|
||||
expect(normalizeAddr(" ")).toBe("");
|
||||
});
|
||||
|
||||
it("normalizeValue 同语义", () => {
|
||||
expect(normalizeValue("31")).toBe("0x1f");
|
||||
expect(normalizeValue("0x1F")).toBe("0x1f");
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger DebuggerSession — 断点增删 + fail-closed", () => {
|
||||
it("open 前设断点被拒(target not connected)", () => {
|
||||
const s = new DebuggerSession();
|
||||
const r = s.setBreakpoint("0x08001000");
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.reason).toContain("not connected");
|
||||
});
|
||||
|
||||
it("open 后设断点成功 + 归一地址", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
const r = s.setBreakpoint("0x08001000");
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.addr).toBe("0x08001000");
|
||||
expect(s.listBreakpoints()).toContain("0x08001000");
|
||||
});
|
||||
|
||||
it("十进制地址自动还原 hex 后入表", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
const r = s.setBreakpoint("1073872896"); // 0x40020000
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.addr).toBe("0x40020000");
|
||||
expect(s.listBreakpoints()).toEqual(["0x40020000"]);
|
||||
});
|
||||
|
||||
it("重复设同一断点幂等(Set 去重)", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
s.setBreakpoint("0x08001000");
|
||||
s.setBreakpoint("0x08001000");
|
||||
expect(s.listBreakpoints()).toEqual(["0x08001000"]);
|
||||
});
|
||||
|
||||
it("removeBreakpoint 删掉", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
s.setBreakpoint("0x08001000");
|
||||
const r = s.removeBreakpoint("0x08001000");
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.removed).toBe(true);
|
||||
expect(s.listBreakpoints()).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("removeBreakpoint 不存在的断点 removed:false 幂等", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
const r = s.removeBreakpoint("0xdeadbeef");
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.removed).toBe(false);
|
||||
});
|
||||
|
||||
it("listBreakpoints 排序稳定", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
s.setBreakpoint("0x08002000");
|
||||
s.setBreakpoint("0x08001000");
|
||||
s.setBreakpoint("0x08000000");
|
||||
expect(s.listBreakpoints()).toEqual(["0x08000000", "0x08001000", "0x08002000"]);
|
||||
});
|
||||
|
||||
it("close 清空断点 + 断开", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
s.setBreakpoint("0x08001000");
|
||||
s.close();
|
||||
expect(s.isConnected()).toBe(false);
|
||||
expect(s.listBreakpoints()).toHaveLength(0);
|
||||
// close 后再 set 又该被拒
|
||||
expect(s.setBreakpoint("0x08001000").ok).toBe(false);
|
||||
});
|
||||
|
||||
it("registerBreakpointFromMi 从 gdb 回包登记编号", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
const mi: MiLine = parseMiLine(
|
||||
'^done,bkpt={number="3",type="breakpoint",addr="0x08003000",enabled="y"}',
|
||||
);
|
||||
const r = s.registerBreakpointFromMi(mi);
|
||||
expect(r?.ok).toBe(true);
|
||||
expect(r?.number).toBe("3");
|
||||
expect(r?.addr).toBe("0x08003000");
|
||||
expect(s.listBreakpoints()).toContain("0x08003000");
|
||||
});
|
||||
|
||||
it("registerBreakpointFromMi 非 breakpoint 行返回 null", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
const mi = parseMiLine('*running,thread-id="all"');
|
||||
expect(s.registerBreakpointFromMi(mi)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger DebuggerSession — writeMem confirm 门(缺陷 #8 验收 §4)", () => {
|
||||
it("未带 confirm:true 被拒", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
const r = s.writeMem("0x40021000", "0x1F", false);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.reason).toContain("confirm:true");
|
||||
// 地址仍归一回显(让 agent 看到真实目标)
|
||||
expect(r.addr).toBe("0x40021000");
|
||||
});
|
||||
|
||||
it("带 confirm:true 放行 + 归一地址/值", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
const r = s.writeMem("0x40021000", "0x1F", true, "0x00");
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.addr).toBe("0x40021000");
|
||||
expect(r.value).toBe("0x1f");
|
||||
expect(r.echo).toBe("0x00");
|
||||
});
|
||||
|
||||
it("十进制强转地址/值在 writeMem 归一回显", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
// 模型把 0x40021000 → "1073872896",0x1F → "31"
|
||||
const r = s.writeMem("1073872896", "31", true);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.addr).toBe("0x40020000");
|
||||
expect(r.value).toBe("0x1f");
|
||||
});
|
||||
|
||||
it("未连接时 writeMem 拒绝(target not connected)", () => {
|
||||
const s = new DebuggerSession();
|
||||
const r = s.writeMem("0x40021000", "0x1F", true);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.reason).toContain("not connected");
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger DebuggerSession — readMem 缺陷 #8 防御(验收 §3)", () => {
|
||||
it("readMem 返回 0x 形式地址(非十进制 1073872896)", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
const r = s.readMem("1073872896", 16, "0000000000000000ffffffffffffffff");
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.addr).toBe("0x40020000");
|
||||
expect(r.addr).not.toBe("1073872896");
|
||||
expect(r.length).toBe(16);
|
||||
expect(r.bytes).toBe("0000000000000000ffffffffffffffff");
|
||||
});
|
||||
|
||||
it("readMem length<=0 拒绝", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
expect(s.readMem("0x40021000", 0).ok).toBe(false);
|
||||
expect(s.readMem("0x40021000", -4).ok).toBe(false);
|
||||
});
|
||||
|
||||
it("readMem 未连接拒绝", () => {
|
||||
const s = new DebuggerSession();
|
||||
expect(s.readMem("0x40021000", 4).ok).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("jtag-debugger 断点持久化(缺陷 #4 跨 session 恢复)", () => {
|
||||
it("snapshotBreakpoints 序列化当前列表", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
s.setBreakpoint("0x08001000");
|
||||
s.setBreakpoint("0x08002000");
|
||||
const snap = snapshotBreakpoints(s);
|
||||
expect(snap.map((e) => e.addr)).toEqual(["0x08001000", "0x08002000"]);
|
||||
expect(snap[0]?.timestamp).toBeTypeOf("number");
|
||||
});
|
||||
|
||||
it("restoreBreakpoints 从 debugger-bp entries 重建", () => {
|
||||
const s = new DebuggerSession();
|
||||
s.open();
|
||||
const entries = [
|
||||
{ type: "debugger-bp", data: { addr: "0x08001000" } },
|
||||
{ type: "debugger-bp", data: { addr: "0x08002000" } },
|
||||
{ type: "other", data: {} },
|
||||
{ type: "debugger-bp", data: {} }, // 坏条目跳过
|
||||
];
|
||||
const restored = restoreBreakpoints(s, entries);
|
||||
expect(restored).toEqual(["0x08001000", "0x08002000"]);
|
||||
expect(s.listBreakpoints()).toEqual(["0x08001000", "0x08002000"]);
|
||||
});
|
||||
|
||||
it("restoreBreakpoints 在未连接会话上全部失败", () => {
|
||||
const s = new DebuggerSession(); // 未 open
|
||||
const restored = restoreBreakpoints(s, [{ type: "debugger-bp", data: { addr: "0x08001000" } }]);
|
||||
expect(restored).toEqual([]);
|
||||
});
|
||||
});
|
||||
404
tests/length-recovery.test.ts
Normal file
404
tests/length-recovery.test.ts
Normal file
@ -0,0 +1,404 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
detectLengthStop,
|
||||
deriveExpectedLength,
|
||||
planRecovery,
|
||||
buildRecoveryPrompt,
|
||||
partitionToolCalls,
|
||||
buildTruncationError,
|
||||
RecoveryStats,
|
||||
extractLastUserMessageFromEntries,
|
||||
type ToolCallLike,
|
||||
type RecoveryStrategy,
|
||||
type SessionEntry,
|
||||
} from "../src/extensions/length-recovery.js";
|
||||
|
||||
// ============================================================================
|
||||
// ① length 截断检测
|
||||
// ============================================================================
|
||||
|
||||
describe("length-recovery detectLengthStop — length 截断检测", () => {
|
||||
it("stopReason=length → true", () => {
|
||||
expect(detectLengthStop("length", "partial...")).toBe(true);
|
||||
});
|
||||
|
||||
it("stopReason=max_tokens(Anthropic 映射前)→ true", () => {
|
||||
expect(detectLengthStop("max_tokens", "partial")).toBe(true);
|
||||
});
|
||||
|
||||
it("stopReason=maxtokens(无下划线变体)→ true", () => {
|
||||
expect(detectLengthStop("maxtokens", "partial")).toBe(true);
|
||||
});
|
||||
|
||||
it("大小写/空白不敏感:' Length ' → true", () => {
|
||||
expect(detectLengthStop(" Length ", "x")).toBe(true);
|
||||
});
|
||||
|
||||
it("stopReason=tool_use → false(零回归)", () => {
|
||||
expect(detectLengthStop("tool_use", "partial")).toBe(false);
|
||||
});
|
||||
|
||||
it("stopReason=stop → false", () => {
|
||||
expect(detectLengthStop("stop", "partial")).toBe(false);
|
||||
});
|
||||
|
||||
it("stopReason=undefined / 空 / null → false(fail-closed:未知不判 length)", () => {
|
||||
expect(detectLengthStop(undefined, "partial")).toBe(false);
|
||||
expect(detectLengthStop("", "partial")).toBe(false);
|
||||
expect(detectLengthStop(null as unknown as undefined, "partial")).toBe(false);
|
||||
});
|
||||
|
||||
it("partialContent 空也判 length(thinking 黑洞场景仍需恢复)", () => {
|
||||
expect(detectLengthStop("length", "")).toBe(true);
|
||||
expect(detectLengthStop("length", " ")).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ② 期望长度估算
|
||||
// ============================================================================
|
||||
|
||||
describe("length-recovery deriveExpectedLength — 期望长度估算", () => {
|
||||
it("空 lastUserMsg → base 1024", () => {
|
||||
expect(deriveExpectedLength("")).toBe(1024);
|
||||
expect(deriveExpectedLength(" ")).toBe(1024);
|
||||
});
|
||||
|
||||
it("短任务 ≥ base", () => {
|
||||
expect(deriveExpectedLength("read the register")).toBeGreaterThanOrEqual(1024);
|
||||
});
|
||||
|
||||
it("长任务(datasheet 注入)封顶 8192", () => {
|
||||
const long = "x".repeat(4000);
|
||||
expect(deriveExpectedLength(long)).toBe(8192);
|
||||
});
|
||||
|
||||
it("随 lastUserMsg 长度增长(×4)", () => {
|
||||
// 400 字符 → 1600,未到 cap
|
||||
expect(deriveExpectedLength("y".repeat(400))).toBe(1600);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ③ 恢复策略规划
|
||||
// ============================================================================
|
||||
|
||||
describe("length-recovery planRecovery — 策略选择(按已生成长度比)", () => {
|
||||
it("ratio > 0.5 → continue(已生成过半,从断点续写)", () => {
|
||||
// partial 1500 / expected 2000 = 0.75
|
||||
const plan = planRecovery("x".repeat(1500), "do the task", { expectedLength: 2000 });
|
||||
expect(plan.strategy).toBe("continue");
|
||||
expect(plan.ratio).toBeCloseTo(0.75, 5);
|
||||
expect(plan.prompt).toContain("Continue");
|
||||
// continue 应带上已生成内容供续写
|
||||
expect(plan.prompt).toContain("x".repeat(1500));
|
||||
});
|
||||
|
||||
it("ratio = 0.5 边界 → 非 continue(>0.5 才 continue)→ summarize", () => {
|
||||
// 1000 / 2000 = 0.5
|
||||
const plan = planRecovery("x".repeat(1000), "task", { expectedLength: 2000 });
|
||||
expect(plan.strategy).not.toBe("continue");
|
||||
expect(plan.strategy).toBe("summarize");
|
||||
});
|
||||
|
||||
it("ratio < 0.2 → retry-condensed(几乎没生成,压缩重发)", () => {
|
||||
// partial 200 / expected 2000 = 0.1
|
||||
const plan = planRecovery("x".repeat(200), "task", { expectedLength: 2000 });
|
||||
expect(plan.strategy).toBe("retry-condensed");
|
||||
expect(plan.ratio).toBeCloseTo(0.1, 5);
|
||||
});
|
||||
|
||||
it("ratio = 0.2 边界 → 非 retry-condensed(<0.2 才 retry)→ summarize", () => {
|
||||
// 400 / 2000 = 0.2
|
||||
const plan = planRecovery("x".repeat(400), "task", { expectedLength: 2000 });
|
||||
expect(plan.strategy).not.toBe("retry-condensed");
|
||||
expect(plan.strategy).toBe("summarize");
|
||||
});
|
||||
|
||||
it("0.2 < ratio < 0.5 → summarize", () => {
|
||||
// 600 / 2000 = 0.3
|
||||
const plan = planRecovery("x".repeat(600), "task", { expectedLength: 2000 });
|
||||
expect(plan.strategy).toBe("summarize");
|
||||
expect(plan.prompt).toContain("summar");
|
||||
// summarize 也带已生成内容
|
||||
expect(plan.prompt).toContain("x".repeat(600));
|
||||
});
|
||||
|
||||
it("retry-condensed 不重复 near-empty partial,改带原任务", () => {
|
||||
const task = "Build the cross-compiled firmware and flash it.";
|
||||
const plan = planRecovery("x".repeat(10), task, { expectedLength: 2000 });
|
||||
expect(plan.strategy).toBe("retry-condensed");
|
||||
expect(plan.prompt).toContain(task);
|
||||
// near-empty partial 不应被原样塞进 prompt 浪费 token
|
||||
expect(plan.prompt).not.toContain("xxxxxxxxxx");
|
||||
});
|
||||
|
||||
it("默认 expectedLength 由 deriveExpectedLength(lastUserMsg) 推导", () => {
|
||||
// lastUserMsg 400 字符 → expected 1600;partial 1700 → ratio>1 → continue
|
||||
const plan = planRecovery("x".repeat(1700), "y".repeat(400));
|
||||
expect(plan.expectedLength).toBe(1600);
|
||||
expect(plan.strategy).toBe("continue");
|
||||
});
|
||||
|
||||
it("空 partialContent → ratio 0 → retry-condensed", () => {
|
||||
const plan = planRecovery("", "task", { expectedLength: 2000 });
|
||||
expect(plan.ratio).toBe(0);
|
||||
expect(plan.strategy).toBe("retry-condensed");
|
||||
});
|
||||
|
||||
it("自定义阈值:continueThreshold 覆盖 0.5", () => {
|
||||
// ratio 0.6;默认>0.5 continue,但 raise 到 0.7 → summarize
|
||||
const a = planRecovery("x".repeat(1200), "t", { expectedLength: 2000 });
|
||||
expect(a.strategy).toBe("continue");
|
||||
const b = planRecovery("x".repeat(1200), "t", {
|
||||
expectedLength: 2000,
|
||||
continueThreshold: 0.7,
|
||||
});
|
||||
expect(b.strategy).toBe("summarize");
|
||||
});
|
||||
|
||||
it("自定义阈值:retryThreshold 覆盖 0.2", () => {
|
||||
// ratio 0.25;默认 summarize,retryThreshold 提到 0.3 → retry-condensed
|
||||
const a = planRecovery("x".repeat(500), "t", { expectedLength: 2000 });
|
||||
expect(a.strategy).toBe("summarize");
|
||||
const b = planRecovery("x".repeat(500), "t", { expectedLength: 2000, retryThreshold: 0.3 });
|
||||
expect(b.strategy).toBe("retry-condensed");
|
||||
});
|
||||
});
|
||||
|
||||
describe("length-recovery buildRecoveryPrompt — 恢复指令文案", () => {
|
||||
it("retry-condensed 在 lastUserMsg 为空时回退兜底文案", () => {
|
||||
const prompt = buildRecoveryPrompt("retry-condensed", "x".repeat(5), "");
|
||||
expect(prompt).toContain("Original task:");
|
||||
expect(prompt).toContain("no prior task message recorded");
|
||||
// 空 lastUserMsg 不应把近空 partial 塞进去
|
||||
expect(prompt).not.toContain("xxxxx");
|
||||
});
|
||||
|
||||
it("三种策略各产出含 partial 或 task 的文案", () => {
|
||||
const partial = "PARTIAL_BODY";
|
||||
const task = "THE_TASK";
|
||||
expect(buildRecoveryPrompt("continue", partial, task)).toContain(partial);
|
||||
expect(buildRecoveryPrompt("summarize", partial, task)).toContain(partial);
|
||||
expect(buildRecoveryPrompt("retry-condensed", partial, task)).toContain(task);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ④ 选择性 tool call 拆分(fail-closed)
|
||||
// ============================================================================
|
||||
|
||||
describe("length-recovery partitionToolCalls — 选择性执行(fail-closed)", () => {
|
||||
const completeCall = (id: string): ToolCallLike => ({ id, complete: true, name: "bash" });
|
||||
const incompleteCall = (id: string): ToolCallLike => ({ id, complete: false, name: "edit" });
|
||||
const unknownCall = (id: string): ToolCallLike => ({ id, name: "read" });
|
||||
|
||||
it("complete:true → executable", () => {
|
||||
const { executable, truncated } = partitionToolCalls([completeCall("a")]);
|
||||
expect(executable).toHaveLength(1);
|
||||
expect(truncated).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("complete:false → truncated(不执行)", () => {
|
||||
const { executable, truncated } = partitionToolCalls([incompleteCall("a")]);
|
||||
expect(executable).toHaveLength(0);
|
||||
expect(truncated).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("complete 缺失 → truncated(fail-closed:未知即不执行)", () => {
|
||||
// 文档铁律:靠 content_block_stop 标志而非 schema 校验把关。
|
||||
// 缺标志 = 截断,绝不执行(防 parse 通过但语义不全的静默损坏)。
|
||||
const { executable, truncated } = partitionToolCalls([unknownCall("a")]);
|
||||
expect(executable).toHaveLength(0);
|
||||
expect(truncated).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("混合:前 2 complete 执行,第 3 截断 fail(验收标准 1)", () => {
|
||||
const calls = [completeCall("1"), completeCall("2"), incompleteCall("3")];
|
||||
const { executable, truncated } = partitionToolCalls(calls);
|
||||
expect(executable.map((c) => c.id)).toEqual(["1", "2"]);
|
||||
expect(truncated.map((c) => c.id)).toEqual(["3"]);
|
||||
});
|
||||
|
||||
it("全 complete → 全执行,零截断(验收标准 4 零回归)", () => {
|
||||
const { executable, truncated } = partitionToolCalls([
|
||||
completeCall("1"),
|
||||
completeCall("2"),
|
||||
]);
|
||||
expect(executable).toHaveLength(2);
|
||||
expect(truncated).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("空数组 → 两边都空", () => {
|
||||
const { executable, truncated } = partitionToolCalls([]);
|
||||
expect(executable).toEqual([]);
|
||||
expect(truncated).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("length-recovery buildTruncationError — 截断 tool call 的 error 结果", () => {
|
||||
it("文案点明 not executed + token limit + Re-issue(与 failToolCallsFromTruncatedMessage 一致)", () => {
|
||||
const r = buildTruncationError({ id: "call_3", name: "edit" });
|
||||
expect(r.isError).toBe(true);
|
||||
expect(r.text).toContain("not executed");
|
||||
expect(r.text).toContain("token limit");
|
||||
expect(r.text).toContain("Re-issue");
|
||||
});
|
||||
|
||||
it("带上 tool call id 便于模型重发", () => {
|
||||
const r = buildTruncationError({ id: "call_42", name: "bash" });
|
||||
expect(r.text).toContain("call_42");
|
||||
});
|
||||
|
||||
it("name 缺失时回退到 'tool' 占位", () => {
|
||||
const r = buildTruncationError({ id: "call_x" });
|
||||
expect(r.text).toContain("[tool]");
|
||||
expect(r.text).toContain("call_x");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ⑤ length 命中统计
|
||||
// ============================================================================
|
||||
|
||||
describe("length-recovery RecoveryStats — 命中频次/策略统计", () => {
|
||||
it("初始为空,count=0,last=null,averageRatio=0", () => {
|
||||
const s = new RecoveryStats();
|
||||
expect(s.count).toBe(0);
|
||||
expect(s.last).toBeNull();
|
||||
expect(s.averageRatio).toBe(0);
|
||||
expect(s.strategyCounts).toEqual({
|
||||
continue: 0,
|
||||
summarize: 0,
|
||||
"retry-condensed": 0,
|
||||
});
|
||||
});
|
||||
|
||||
it("recordHit 累计 count 并更新 last", () => {
|
||||
const s = new RecoveryStats();
|
||||
s.recordHit({
|
||||
stopReason: "length",
|
||||
partialLength: 1500,
|
||||
expectedLength: 2000,
|
||||
ratio: 0.75,
|
||||
strategy: "continue",
|
||||
});
|
||||
expect(s.count).toBe(1);
|
||||
expect(s.last?.strategy).toBe("continue");
|
||||
expect(s.last?.ratio).toBeCloseTo(0.75, 5);
|
||||
expect(typeof s.last?.timestamp).toBe("number");
|
||||
});
|
||||
|
||||
it("strategyCounts 按策略分组累计", () => {
|
||||
const s = new RecoveryStats();
|
||||
s.recordHit({
|
||||
stopReason: "length",
|
||||
partialLength: 200,
|
||||
expectedLength: 2000,
|
||||
ratio: 0.1,
|
||||
strategy: "retry-condensed",
|
||||
});
|
||||
s.recordHit({
|
||||
stopReason: "length",
|
||||
partialLength: 600,
|
||||
expectedLength: 2000,
|
||||
ratio: 0.3,
|
||||
strategy: "summarize",
|
||||
});
|
||||
s.recordHit({
|
||||
stopReason: "length",
|
||||
partialLength: 200,
|
||||
expectedLength: 2000,
|
||||
ratio: 0.1,
|
||||
strategy: "retry-condensed",
|
||||
});
|
||||
expect(s.strategyCounts).toEqual({
|
||||
continue: 0,
|
||||
summarize: 1,
|
||||
"retry-condensed": 2,
|
||||
});
|
||||
});
|
||||
|
||||
it("averageRatio 为所有命中 ratio 的算术平均", () => {
|
||||
const s = new RecoveryStats();
|
||||
s.recordHit({ stopReason: "length", partialLength: 0, expectedLength: 2000, ratio: 0.1, strategy: "retry-condensed" });
|
||||
s.recordHit({ stopReason: "length", partialLength: 0, expectedLength: 2000, ratio: 0.5, strategy: "summarize" });
|
||||
// (0.1 + 0.5) / 2 = 0.3
|
||||
expect(s.averageRatio).toBeCloseTo(0.3, 5);
|
||||
});
|
||||
|
||||
it("snapshot 汇总输出", () => {
|
||||
const s = new RecoveryStats();
|
||||
s.recordHit({ stopReason: "length", partialLength: 0, expectedLength: 2000, ratio: 0.75, strategy: "continue" });
|
||||
const snap = s.snapshot();
|
||||
expect(snap.count).toBe(1);
|
||||
expect(snap.strategyCounts.continue).toBe(1);
|
||||
expect(snap.last?.strategy).toBe("continue");
|
||||
expect(snap.averageRatio).toBeCloseTo(0.75, 5);
|
||||
});
|
||||
|
||||
it("reset 清空", () => {
|
||||
const s = new RecoveryStats();
|
||||
s.recordHit({ stopReason: "length", partialLength: 0, expectedLength: 2000, ratio: 0.1, strategy: "retry-condensed" });
|
||||
s.reset();
|
||||
expect(s.count).toBe(0);
|
||||
expect(s.last).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ⑥ session entries 取最后一条 user 消息
|
||||
// ============================================================================
|
||||
|
||||
describe("length-recovery extractLastUserMessageFromEntries — 取最后 user 消息", () => {
|
||||
it("data 为字符串 → 直接返回", () => {
|
||||
const entries: SessionEntry[] = [
|
||||
{ type: "assistant", data: "hello", id: "1" },
|
||||
{ type: "user", data: "flash the firmware", id: "2" },
|
||||
];
|
||||
expect(extractLastUserMessageFromEntries(entries)).toBe("flash the firmware");
|
||||
});
|
||||
|
||||
it("data.content 为字符串 → 返回 content", () => {
|
||||
const entries: SessionEntry[] = [
|
||||
{ type: "user", data: { content: "build it" }, id: "1" },
|
||||
];
|
||||
expect(extractLastUserMessageFromEntries(entries)).toBe("build it");
|
||||
});
|
||||
|
||||
it("data.content 为 text 块数组 → 拼接 text", () => {
|
||||
const entries: SessionEntry[] = [
|
||||
{ type: "user", data: { content: [{ type: "text", text: "part1 " }, { type: "text", text: "part2" }] }, id: "1" },
|
||||
];
|
||||
expect(extractLastUserMessageFromEntries(entries)).toBe("part1 part2");
|
||||
});
|
||||
|
||||
it("取最后一条 user(多条 user 时倒序找)", () => {
|
||||
const entries: SessionEntry[] = [
|
||||
{ type: "user", data: "old task", id: "1" },
|
||||
{ type: "assistant", data: "ok", id: "2" },
|
||||
{ type: "user", data: "new task", id: "3" },
|
||||
];
|
||||
expect(extractLastUserMessageFromEntries(entries)).toBe("new task");
|
||||
});
|
||||
|
||||
it("无 user 消息 → 空串(planRecovery 回落 base 期望长度)", () => {
|
||||
const entries: SessionEntry[] = [
|
||||
{ type: "assistant", data: "hi", id: "1" },
|
||||
];
|
||||
expect(extractLastUserMessageFromEntries(entries)).toBe("");
|
||||
});
|
||||
|
||||
it("空数组 / 非数组 → 空串(fail-closed)", () => {
|
||||
expect(extractLastUserMessageFromEntries([])).toBe("");
|
||||
expect(extractLastUserMessageFromEntries(null as unknown as SessionEntry[])).toBe("");
|
||||
});
|
||||
|
||||
it("user 消息但 data.content 为空数组 → 跳过继续倒序找", () => {
|
||||
const entries: SessionEntry[] = [
|
||||
{ type: "user", data: "previous real task", id: "1" },
|
||||
{ type: "user", data: { content: [] }, id: "2" },
|
||||
];
|
||||
expect(extractLastUserMessageFromEntries(entries)).toBe("previous real task");
|
||||
});
|
||||
});
|
||||
314
tests/loop-orchestrator.test.ts
Normal file
314
tests/loop-orchestrator.test.ts
Normal file
@ -0,0 +1,314 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
CheckpointMachine,
|
||||
classifyCommand,
|
||||
STEP_ORDER,
|
||||
STEP_PREREQUISITES,
|
||||
assertCommandOrder,
|
||||
type CheckpointDecision,
|
||||
} from "../src/extensions/loop-orchestrator.js";
|
||||
import type { CheckpointStep, CheckpointState } from "../src/shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// classifyCommand — bash 命令分类到 checkpoint step
|
||||
// ============================================================================
|
||||
|
||||
describe("loop-orchestrator classifyCommand", () => {
|
||||
it("aarch64-linux-gnu-gcc → compile", () => {
|
||||
expect(classifyCommand("aarch64-linux-gnu-gcc -o app main.c")).toBe("compile");
|
||||
});
|
||||
|
||||
it("cmake --build → compile", () => {
|
||||
expect(classifyCommand("cmake --build . --config Release")).toBe("compile");
|
||||
});
|
||||
|
||||
it("make → compile", () => {
|
||||
expect(classifyCommand("make -j4")).toBe("compile");
|
||||
});
|
||||
|
||||
it("dd of=/dev/mmcblk0 → flash", () => {
|
||||
expect(classifyCommand("dd if=image.bin of=/dev/mmcblk0 bs=4M")).toBe("flash");
|
||||
});
|
||||
|
||||
it("fastboot flash → flash", () => {
|
||||
expect(classifyCommand("fastboot flash boot boot.img")).toBe("flash");
|
||||
});
|
||||
|
||||
it("scp to board → flash", () => {
|
||||
expect(classifyCommand("scp app root@192.168.1.100:/root/")).toBe("flash");
|
||||
});
|
||||
|
||||
it("dmesg → check", () => {
|
||||
expect(classifyCommand("dmesg | grep i2c")).toBe("check");
|
||||
});
|
||||
|
||||
it("journalctl → check", () => {
|
||||
expect(classifyCommand("journalctl -u my-service -n 50")).toBe("check");
|
||||
});
|
||||
|
||||
it("无关命令 ls → null", () => {
|
||||
expect(classifyCommand("ls -la")).toBeNull();
|
||||
});
|
||||
|
||||
it("空命令 → null", () => {
|
||||
expect(classifyCommand("")).toBeNull();
|
||||
expect(classifyCommand(" ")).toBeNull();
|
||||
});
|
||||
|
||||
it("sudo dd 也能识别 flash", () => {
|
||||
expect(classifyCommand("sudo dd if=image.bin of=/dev/mmcblk0")).toBe("flash");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// CheckpointMachine — 顺序违规 block(fail-closed 核心)
|
||||
// ============================================================================
|
||||
|
||||
describe("loop-orchestrator 顺序违规 block (fail-closed)", () => {
|
||||
it("flash 前未编译 → assertCommandOrder block", () => {
|
||||
const m = new CheckpointMachine();
|
||||
// 初始在 edit,compile 未通过
|
||||
const d = assertCommandOrder(m, "dd if=image.bin of=/dev/mmcblk0");
|
||||
expect(d.block).toBe(true);
|
||||
expect(d.reason).toContain("compile");
|
||||
});
|
||||
|
||||
it("flash 前已编译通过 → 放行", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
const d = assertCommandOrder(m, "dd if=image.bin of=/dev/mmcblk0");
|
||||
expect(d.block).toBe(false);
|
||||
});
|
||||
|
||||
it("verify 前未 flash → block", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
// flash 还没过,直接 verify 应 block
|
||||
const d = m.assertOrder("flash", "verify-board-id-abc");
|
||||
expect(d.block).toBe(true);
|
||||
expect(d.reason).toContain("flash");
|
||||
});
|
||||
|
||||
it("check 前未 flash → block(dmesg 前须烧过板)", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
const d = assertCommandOrder(m, "dmesg | grep i2c");
|
||||
expect(d.block).toBe(true);
|
||||
expect(d.reason).toContain("flash");
|
||||
});
|
||||
|
||||
it("compile 无前置条件 → 放行", () => {
|
||||
const m = new CheckpointMachine();
|
||||
const d = assertCommandOrder(m, "aarch64-linux-gnu-gcc -o app main.c");
|
||||
expect(d.block).toBe(false);
|
||||
});
|
||||
|
||||
it("无关命令(ls)→ 放行(null step 不收 checkpoint)", () => {
|
||||
const m = new CheckpointMachine();
|
||||
const d = assertCommandOrder(m, "ls -la");
|
||||
expect(d.block).toBe(false);
|
||||
});
|
||||
|
||||
it("assertOrder 显式指定前置:未满足时 block", () => {
|
||||
const m = new CheckpointMachine();
|
||||
// before=compile,但 compile 未通过
|
||||
const d = m.assertOrder("compile", "dd if=img of=/dev/mmcblk0");
|
||||
expect(d.block).toBe(true);
|
||||
expect(d.reason).toContain("Compile checkpoint not passed");
|
||||
});
|
||||
|
||||
it("assertOrder 显式前置满足后放行", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
const d = m.assertOrder("compile", "dd if=img of=/dev/mmcblk0");
|
||||
expect(d.block).toBe(false);
|
||||
});
|
||||
|
||||
it("check 前已 flash 通过 → 放行", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
m.advance("flash", true);
|
||||
const d = assertCommandOrder(m, "dmesg | grep i2c");
|
||||
expect(d.block).toBe(false);
|
||||
expect(d.step).toBe("check");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// CheckpointMachine — advance 推进
|
||||
// ============================================================================
|
||||
|
||||
describe("loop-orchestrator advance 推进", () => {
|
||||
it("初始状态 currentStep=edit, stepPassed=false", () => {
|
||||
const m = new CheckpointMachine();
|
||||
expect(m.getCurrentStep()).toBe("edit");
|
||||
expect(m.isStepPassed()).toBe(false);
|
||||
expect(m.getHistory()).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("compile 通过 → currentStep 推进到 flash, stepPassed 重置 false", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
expect(m.getCurrentStep()).toBe("flash");
|
||||
expect(m.isStepPassed()).toBe(false);
|
||||
expect(m.isPassed("compile")).toBe(true);
|
||||
});
|
||||
|
||||
it("compile 失败 → 留在 compile, stepPassed false", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", false);
|
||||
expect(m.getCurrentStep()).toBe("compile");
|
||||
expect(m.isStepPassed()).toBe(false);
|
||||
expect(m.isPassed("compile")).toBe(false);
|
||||
});
|
||||
|
||||
it("完整闭环 edit→compile→flash→verify→check→done", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("edit", true);
|
||||
expect(m.getCurrentStep()).toBe("compile");
|
||||
m.advance("compile", true);
|
||||
expect(m.getCurrentStep()).toBe("flash");
|
||||
m.advance("flash", true);
|
||||
expect(m.getCurrentStep()).toBe("verify");
|
||||
m.advance("verify", true);
|
||||
expect(m.getCurrentStep()).toBe("check");
|
||||
m.advance("check", true);
|
||||
expect(m.getCurrentStep()).toBe("done");
|
||||
});
|
||||
|
||||
it("history 累积每步记录", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
m.advance("flash", true);
|
||||
const h = m.getHistory();
|
||||
expect(h).toHaveLength(2);
|
||||
expect(h[0]?.step).toBe("compile");
|
||||
expect(h[0]?.passed).toBe(true);
|
||||
expect(h[1]?.step).toBe("flash");
|
||||
expect(h[1]?.passed).toBe(true);
|
||||
});
|
||||
|
||||
it("失败也入 history(passed=false)", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", false);
|
||||
m.advance("compile", true);
|
||||
const h = m.getHistory();
|
||||
expect(h).toHaveLength(2);
|
||||
expect(h[0]?.passed).toBe(false);
|
||||
expect(h[1]?.passed).toBe(true);
|
||||
});
|
||||
|
||||
it("重复通过同一步(重入)不重复推进 currentStep", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
expect(m.getCurrentStep()).toBe("flash");
|
||||
// 重入 compile 通过:记 history 但不回退 currentStep
|
||||
m.advance("compile", true);
|
||||
expect(m.getCurrentStep()).toBe("flash");
|
||||
expect(m.isPassed("compile")).toBe(true);
|
||||
});
|
||||
|
||||
it("done 通过后停在 done 且 stepPassed=true", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("edit", true);
|
||||
m.advance("compile", true);
|
||||
m.advance("flash", true);
|
||||
m.advance("verify", true);
|
||||
m.advance("check", true);
|
||||
m.advance("done", true);
|
||||
expect(m.getCurrentStep()).toBe("done");
|
||||
expect(m.isStepPassed()).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// CheckpointMachine — serialize / restore
|
||||
// ============================================================================
|
||||
|
||||
describe("loop-orchestrator serialize/restore", () => {
|
||||
it("serialize 返回完整 CheckpointState", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
m.advance("flash", false);
|
||||
const s = m.serialize();
|
||||
expect(s.currentStep).toBe("flash");
|
||||
expect(s.stepPassed).toBe(false);
|
||||
expect(s.history).toHaveLength(2);
|
||||
expect(s.history[0]?.step).toBe("compile");
|
||||
});
|
||||
|
||||
it("restore 重建后状态一致", () => {
|
||||
const m1 = new CheckpointMachine();
|
||||
m1.advance("edit", true);
|
||||
m1.advance("compile", true);
|
||||
m1.advance("flash", true);
|
||||
const snap = m1.serialize();
|
||||
|
||||
const m2 = new CheckpointMachine();
|
||||
m2.restore(snap);
|
||||
expect(m2.getCurrentStep()).toBe("verify");
|
||||
expect(m2.isPassed("compile")).toBe(true);
|
||||
expect(m2.isPassed("flash")).toBe(true);
|
||||
expect(m2.getHistory()).toHaveLength(3);
|
||||
});
|
||||
|
||||
it("restore 空状态安全", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.restore({ currentStep: "edit", stepPassed: false, history: [] });
|
||||
expect(m.getCurrentStep()).toBe("edit");
|
||||
expect(m.getHistory()).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("restore 非法 currentStep 不崩溃(兜底回 edit)", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.restore({ currentStep: "unknown" as CheckpointStep, stepPassed: false, history: [] } as CheckpointState);
|
||||
expect(m.getCurrentStep()).toBe("edit");
|
||||
});
|
||||
|
||||
it("serialize 后修改不影响原状态(深拷贝)", () => {
|
||||
const m = new CheckpointMachine();
|
||||
m.advance("compile", true);
|
||||
const s = m.serialize();
|
||||
// 篡改序列化结果
|
||||
s.history.push({ step: "done", passed: true, timestamp: 0 });
|
||||
s.currentStep = "done";
|
||||
// 原状态不受影响
|
||||
expect(m.getCurrentStep()).toBe("flash");
|
||||
expect(m.getHistory()).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// 常量与结构
|
||||
// ============================================================================
|
||||
|
||||
describe("loop-orchestrator 常量", () => {
|
||||
it("STEP_ORDER 是 6 步闭环", () => {
|
||||
expect(STEP_ORDER).toEqual(["edit", "compile", "flash", "verify", "check", "done"]);
|
||||
});
|
||||
|
||||
it("STEP_PREREQUISITES: flash 须 compile", () => {
|
||||
expect(STEP_PREREQUISITES.flash).toBe("compile");
|
||||
});
|
||||
|
||||
it("STEP_PREREQUISITES: verify 须 flash", () => {
|
||||
expect(STEP_PREREQUISITES.verify).toBe("flash");
|
||||
});
|
||||
|
||||
it("STEP_PREREQUISITES: check 须 flash", () => {
|
||||
expect(STEP_PREREQUISITES.check).toBe("flash");
|
||||
});
|
||||
|
||||
it("STEP_PREREQUISITES: compile 无前置", () => {
|
||||
expect(STEP_PREREQUISITES.compile).toBeNull();
|
||||
});
|
||||
|
||||
it("CheckpointDecision block 时携带 reason", () => {
|
||||
const m = new CheckpointMachine();
|
||||
const d: CheckpointDecision = assertCommandOrder(m, "dd if=img of=/dev/mmcblk0");
|
||||
expect(d.block).toBe(true);
|
||||
expect(typeof d.reason).toBe("string");
|
||||
expect(d.reason!.length).toBeGreaterThan(0);
|
||||
expect(d.step).toBe("flash");
|
||||
});
|
||||
});
|
||||
301
tests/mcp-bridge.test.ts
Normal file
301
tests/mcp-bridge.test.ts
Normal file
@ -0,0 +1,301 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
parseMcpConfig,
|
||||
validateServerConfig,
|
||||
normalizeServerConfig,
|
||||
buildMcpToolName,
|
||||
parseMcpToolName,
|
||||
McpBridge,
|
||||
McpConfigError,
|
||||
type RpcCall,
|
||||
type ListToolsFn,
|
||||
} from "../src/extensions/mcp-bridge.js";
|
||||
|
||||
// ----------------------------------------------------------------------------
|
||||
// helpers: 注入 mock RpcCall / ListToolsFn,绝不依赖真实硬件/MCP SDK
|
||||
// ----------------------------------------------------------------------------
|
||||
|
||||
function makeEchoRpc(): RpcCall {
|
||||
return async (_server, tool, args) => {
|
||||
const text = `${_server}.${tool}(${JSON.stringify(args ?? {})})`;
|
||||
return { content: [{ type: "text", text }] };
|
||||
};
|
||||
}
|
||||
|
||||
function makeFailingRpc(): RpcCall {
|
||||
return async () => {
|
||||
throw new Error("connection reset by peer");
|
||||
};
|
||||
}
|
||||
|
||||
function makeIsErrorRpc(): RpcCall {
|
||||
return async (_server, tool) => ({
|
||||
content: [{ type: "text", text: `tool ${tool} not found` }],
|
||||
isError: true,
|
||||
});
|
||||
}
|
||||
|
||||
const stubListTools: ListToolsFn = async (server) => {
|
||||
const map: Record<string, string[]> = {
|
||||
i2c: ["scan", "read", "write"],
|
||||
oscilloscope: ["capture", "measure"],
|
||||
};
|
||||
return map[server] ?? [];
|
||||
};
|
||||
|
||||
const failingListTools: ListToolsFn = async () => {
|
||||
throw new Error("MCP server handshake timeout");
|
||||
};
|
||||
|
||||
// ============================================================================
|
||||
// ① config 校验
|
||||
// ============================================================================
|
||||
|
||||
describe("mcp-bridge parseMcpConfig — 校验", () => {
|
||||
it("标准 mcpServers 形态解析(name 从 key 补入)", () => {
|
||||
const { servers, errors } = parseMcpConfig({
|
||||
mcpServers: {
|
||||
i2c: { command: "i2c-mcp-server", args: ["--bus", "0"] },
|
||||
scope: { transport: "sse", url: "http://scope.local/sse" },
|
||||
},
|
||||
});
|
||||
expect(errors).toHaveLength(0);
|
||||
expect(servers).toHaveLength(2);
|
||||
const i2c = servers.find((s) => s.name === "i2c");
|
||||
expect(i2c?.transport).toBe("stdio");
|
||||
expect(i2c?.command).toBe("i2c-mcp-server");
|
||||
expect(i2c?.args).toEqual(["--bus", "0"]);
|
||||
const scope = servers.find((s) => s.name === "scope");
|
||||
expect(scope?.transport).toBe("sse");
|
||||
expect(scope?.url).toBe("http://scope.local/sse");
|
||||
});
|
||||
|
||||
it("数组形态 { servers: [...] } 解析", () => {
|
||||
const { servers, errors } = parseMcpConfig({
|
||||
servers: [{ name: "gpio", command: "gpio-mcp" }],
|
||||
});
|
||||
expect(errors).toHaveLength(0);
|
||||
expect(servers).toHaveLength(1);
|
||||
expect(servers[0]?.name).toBe("gpio");
|
||||
});
|
||||
|
||||
it("裸数组解析", () => {
|
||||
const { servers, errors } = parseMcpConfig([
|
||||
{ name: "flash", command: "flash-mcp", args: ["--dev", "/dev/mtd0"] },
|
||||
]);
|
||||
expect(errors).toHaveLength(0);
|
||||
expect(servers).toHaveLength(1);
|
||||
expect(servers[0]?.command).toBe("flash-mcp");
|
||||
});
|
||||
|
||||
it("缺 name 的 server 进 errors,不进 servers(fail-closed)", () => {
|
||||
const r2 = parseMcpConfig({ servers: [{ command: "no-name" }, { name: "ok", command: "y" }] });
|
||||
expect(r2.servers).toHaveLength(1);
|
||||
expect(r2.servers[0]?.name).toBe("ok");
|
||||
expect(r2.errors.some((e) => e.field === "name")).toBe(true);
|
||||
});
|
||||
|
||||
it("stdio 缺 command 报错", () => {
|
||||
const errs = validateServerConfig({ name: "s", transport: "stdio" });
|
||||
expect(errs.some((e) => e.field === "command")).toBe(true);
|
||||
});
|
||||
|
||||
it("sse 缺 url 报错", () => {
|
||||
const errs = validateServerConfig({ name: "s", transport: "sse" });
|
||||
expect(errs.some((e) => e.field === "url")).toBe(true);
|
||||
});
|
||||
|
||||
it("env 里裸 sk- 真 key 被标记(密钥铁律)", () => {
|
||||
const errs = validateServerConfig({
|
||||
name: "s",
|
||||
command: "c",
|
||||
env: { API_KEY: "sk-FAKE000000000000TEST" },
|
||||
});
|
||||
expect(errs.some((e) => e.field === "env.API_KEY")).toBe(true);
|
||||
// 占位形式不报错
|
||||
const okErrs = validateServerConfig({
|
||||
name: "s",
|
||||
command: "c",
|
||||
env: { API_KEY: "${DROBOTICS_LLM_KEY}" },
|
||||
});
|
||||
expect(okErrs.some((e) => e.field === "env.API_KEY")).toBe(false);
|
||||
});
|
||||
|
||||
it("非对象输入报 root 错", () => {
|
||||
const { servers, errors } = parseMcpConfig("not a config");
|
||||
expect(servers).toHaveLength(0);
|
||||
expect(errors[0]?.field).toBe("root");
|
||||
});
|
||||
|
||||
it("transport 从 command/url 自动推断", () => {
|
||||
const c = normalizeServerConfig({ name: "s", command: "c" });
|
||||
expect(c.transport).toBe("stdio");
|
||||
const c2 = normalizeServerConfig({ name: "s2", url: "http://x" });
|
||||
expect(c2.transport).toBe("sse");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ② 工具名前缀
|
||||
// ============================================================================
|
||||
|
||||
describe("mcp-bridge buildMcpToolName / parseMcpToolName", () => {
|
||||
it("默认前缀 mcp__{server}__{tool}", () => {
|
||||
expect(buildMcpToolName("i2c", "scan")).toBe("mcp__i2c__scan");
|
||||
});
|
||||
|
||||
it("自定义前缀", () => {
|
||||
expect(buildMcpToolName("i2c", "scan", "inst")).toBe("inst__scan");
|
||||
});
|
||||
|
||||
it("parseMcpToolName 解出 server+tool", () => {
|
||||
const r = parseMcpToolName("mcp__i2c__scan");
|
||||
expect(r?.server).toBe("i2c");
|
||||
expect(r?.tool).toBe("scan");
|
||||
});
|
||||
|
||||
it("非 mcp__ 前缀返回 null", () => {
|
||||
expect(parseMcpToolName("bash")).toBeNull();
|
||||
expect(parseMcpToolName("mcp__i2c")).toBeNull();
|
||||
});
|
||||
|
||||
it("server 名含单下划线也能往返", () => {
|
||||
const name = buildMcpToolName("i2c_bus", "read");
|
||||
expect(parseMcpToolName(name)).toEqual({ server: "i2c_bus", tool: "read" });
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ③ McpBridge — 连接表 + callTool 路由
|
||||
// ============================================================================
|
||||
|
||||
describe("mcp-bridge McpBridge — 连接与路由", () => {
|
||||
it("registerServer 合法配置不抛", () => {
|
||||
const b = new McpBridge(makeEchoRpc(), stubListTools);
|
||||
expect(() => b.registerServer({ name: "i2c", transport: "stdio", command: "i2c-mcp" })).not.toThrow();
|
||||
expect(b.isRegistered("i2c")).toBe(true);
|
||||
});
|
||||
|
||||
it("registerServer 非法配置抛 McpConfigError", () => {
|
||||
const b = new McpBridge(makeEchoRpc());
|
||||
expect(() => b.registerServer({ name: "", transport: "stdio", command: "c" })).toThrow(McpConfigError);
|
||||
expect(() => b.registerServer({ name: "s", transport: "stdio" } as never)).toThrow(McpConfigError);
|
||||
});
|
||||
|
||||
it("connect 成功后发现工具并标记 connected", async () => {
|
||||
const b = new McpBridge(makeEchoRpc(), stubListTools);
|
||||
b.registerServer({ name: "i2c", transport: "stdio", command: "i2c-mcp" });
|
||||
const conn = await b.connect("i2c");
|
||||
expect(conn.connected).toBe(true);
|
||||
expect(conn.tools).toEqual(["scan", "read", "write"]);
|
||||
expect(b.isConnected("i2c")).toBe(true);
|
||||
expect(b.listConnectedServers()).toEqual(["i2c"]);
|
||||
});
|
||||
|
||||
it("connect 失败(listTools 抛)→ fail-closed 不抛,标未连接+记 error", async () => {
|
||||
const b = new McpBridge(makeEchoRpc(), failingListTools);
|
||||
b.registerServer({ name: "dead", transport: "stdio", command: "dead-mcp" });
|
||||
const conn = await b.connect("dead");
|
||||
expect(conn.connected).toBe(false);
|
||||
expect(conn.error).toContain("handshake timeout");
|
||||
expect(b.isConnected("dead")).toBe(false);
|
||||
});
|
||||
|
||||
it("connect 未注册 server → 抛", async () => {
|
||||
const b = new McpBridge(makeEchoRpc());
|
||||
await expect(b.connect("ghost")).rejects.toThrow(/not registered/);
|
||||
});
|
||||
|
||||
it("connect disabled server → 不连接,标 disabled", async () => {
|
||||
const b = new McpBridge(makeEchoRpc(), stubListTools);
|
||||
b.registerServer({ name: "off", transport: "stdio", command: "x", enabled: false });
|
||||
const conn = await b.connect("off");
|
||||
expect(conn.connected).toBe(false);
|
||||
expect(conn.error).toContain("disabled");
|
||||
});
|
||||
|
||||
it("callTool 成功路由到注入的 RpcCall(args 透传)", async () => {
|
||||
const b = new McpBridge(makeEchoRpc(), stubListTools);
|
||||
b.registerServer({ name: "i2c", transport: "stdio", command: "i2c-mcp" });
|
||||
await b.connect("i2c");
|
||||
const r = await b.callTool("i2c", "scan", { bus: 0 });
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.content[0]?.text).toBe('i2c.scan({"bus":0})');
|
||||
expect(r.details).toEqual({ server: "i2c", tool: "scan" });
|
||||
expect(r.error).toBeUndefined();
|
||||
});
|
||||
|
||||
it("callTool 未注册 server → fail-closed 返回 error(不静默)", async () => {
|
||||
const b = new McpBridge(makeEchoRpc());
|
||||
const r = await b.callTool("ghost", "ping");
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toContain("not registered");
|
||||
expect(r.content[0]?.text).toContain("fail-closed");
|
||||
});
|
||||
|
||||
it("callTool 未连接 server → fail-closed 返回 error", async () => {
|
||||
const b = new McpBridge(makeEchoRpc());
|
||||
b.registerServer({ name: "i2c", transport: "stdio", command: "i2c-mcp" });
|
||||
// 未 connect 直接 call
|
||||
const r = await b.callTool("i2c", "scan");
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toContain("not connected");
|
||||
});
|
||||
|
||||
it("callTool disabled server → error", async () => {
|
||||
const b = new McpBridge(makeEchoRpc(), stubListTools);
|
||||
b.registerServer({ name: "off", transport: "stdio", command: "x", enabled: false });
|
||||
await b.connect("off");
|
||||
const r = await b.callTool("off", "scan");
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toBe("server disabled");
|
||||
});
|
||||
|
||||
it("callTool rpc 抛错 → error 不吞", async () => {
|
||||
const b = new McpBridge(makeFailingRpc(), stubListTools);
|
||||
b.registerServer({ name: "i2c", transport: "stdio", command: "i2c-mcp" });
|
||||
await b.connect("i2c");
|
||||
const r = await b.callTool("i2c", "scan");
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toContain("connection reset");
|
||||
});
|
||||
|
||||
it("callTool MCP server 返回 isError → ok:false", async () => {
|
||||
const b = new McpBridge(makeIsErrorRpc(), stubListTools);
|
||||
b.registerServer({ name: "i2c", transport: "stdio", command: "i2c-mcp" });
|
||||
await b.connect("i2c");
|
||||
const r = await b.callTool("i2c", "nonexistent");
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toContain("isError");
|
||||
});
|
||||
|
||||
it("disconnect / disconnectAll 清理连接表", async () => {
|
||||
const b = new McpBridge(makeEchoRpc(), stubListTools);
|
||||
b.registerServer({ name: "i2c", transport: "stdio", command: "i2c-mcp" });
|
||||
b.registerServer({ name: "scope", transport: "sse", url: "http://x/sse" });
|
||||
await b.connect("i2c");
|
||||
await b.connect("scope");
|
||||
expect(b.listConnectedServers().length).toBe(2);
|
||||
b.disconnect("i2c");
|
||||
expect(b.isConnected("i2c")).toBe(false);
|
||||
expect(b.isConnected("scope")).toBe(true);
|
||||
b.disconnectAll();
|
||||
expect(b.listConnectedServers()).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("registerServers 批量注册(从 parseMcpConfig 结果)", async () => {
|
||||
const { servers } = parseMcpConfig({
|
||||
mcpServers: {
|
||||
i2c: { command: "i2c-mcp" },
|
||||
gpio: { command: "gpio-mcp" },
|
||||
},
|
||||
});
|
||||
const b = new McpBridge(makeEchoRpc(), stubListTools);
|
||||
b.registerServers(servers);
|
||||
expect(b.isRegistered("i2c")).toBe(true);
|
||||
expect(b.isRegistered("gpio")).toBe(true);
|
||||
await b.connect("i2c");
|
||||
const r = await b.callTool("i2c", "read", { addr: "0x76" });
|
||||
expect(r.ok).toBe(true);
|
||||
});
|
||||
});
|
||||
357
tests/pdf-reader.test.ts
Normal file
357
tests/pdf-reader.test.ts
Normal file
@ -0,0 +1,357 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
isPdfMagic,
|
||||
detectPdfMimeType,
|
||||
parsePageRange,
|
||||
expandPages,
|
||||
extractTextBytes,
|
||||
utf8ByteLength,
|
||||
shouldTruncate,
|
||||
planPdfRead,
|
||||
buildReadResult,
|
||||
DATASHEET_READ_LIMITS,
|
||||
LEGACY_READ_LIMITS,
|
||||
type PageRange,
|
||||
} from "../src/extensions/pdf-reader.js";
|
||||
|
||||
// ============================================================================
|
||||
// ① PDF 魔数嗅探
|
||||
// ============================================================================
|
||||
|
||||
describe("pdf-reader isPdfMagic — PDF 魔数嗅探", () => {
|
||||
it("正确识别 %PDF- 魔数", () => {
|
||||
const bytes = new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34]);
|
||||
expect(isPdfMagic(bytes)).toBe(true);
|
||||
});
|
||||
|
||||
it("非 PDF 字节返回 false(fail-closed)", () => {
|
||||
const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]); // PNG header
|
||||
expect(isPdfMagic(bytes)).toBe(false);
|
||||
});
|
||||
|
||||
it("字节不足 5 返回 false", () => {
|
||||
expect(isPdfMagic(new Uint8Array([0x25, 0x50]))).toBe(false);
|
||||
});
|
||||
|
||||
it("空/undefined 安全返回 false", () => {
|
||||
expect(isPdfMagic(new Uint8Array(0))).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("pdf-reader detectPdfMimeType", () => {
|
||||
it("路径 .pdf + 魔数匹配 → true", () => {
|
||||
expect(detectPdfMimeType("datasheet.pdf", new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d]))).toBe(true);
|
||||
});
|
||||
|
||||
it("路径 .pdf 但魔数不匹配 → false(fail-closed,魔数优先)", () => {
|
||||
expect(detectPdfMimeType("not-really.pdf", new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d]))).toBe(false);
|
||||
});
|
||||
|
||||
it("无字节时仅靠扩展名(弱信号)", () => {
|
||||
expect(detectPdfMimeType("foo.PDF")).toBe(true);
|
||||
expect(detectPdfMimeType("foo.txt")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ② 页范围解析
|
||||
// ============================================================================
|
||||
|
||||
describe("pdf-reader parsePageRange — 页范围解析各形态", () => {
|
||||
it('"1-5" → 单范围 [1,5]', () => {
|
||||
const r = parsePageRange("1-5");
|
||||
expect(r.valid).toBe(true);
|
||||
expect(r.all).toBe(false);
|
||||
expect(r.ranges).toEqual([{ start: 1, end: 5 }]);
|
||||
});
|
||||
|
||||
it('"3,7,10" → 三个单页范围', () => {
|
||||
const r = parsePageRange("3,7,10");
|
||||
expect(r.valid).toBe(true);
|
||||
expect(r.ranges).toEqual([
|
||||
{ start: 3, end: 3 },
|
||||
{ start: 7, end: 7 },
|
||||
{ start: 10, end: 10 },
|
||||
]);
|
||||
});
|
||||
|
||||
it('"all" → all=true', () => {
|
||||
const r = parsePageRange("all");
|
||||
expect(r.valid).toBe(true);
|
||||
expect(r.all).toBe(true);
|
||||
expect(r.ranges).toEqual([]);
|
||||
});
|
||||
|
||||
it('"all" + totalPages → 展开为 [1, totalPages]', () => {
|
||||
const r = parsePageRange("all", 3000);
|
||||
expect(r.valid).toBe(true);
|
||||
expect(r.all).toBe(true);
|
||||
expect(r.ranges).toEqual([{ start: 1, end: 3000 }]);
|
||||
});
|
||||
|
||||
it('"1-3,7,10-12" → 混合解析', () => {
|
||||
const r = parsePageRange("1-3,7,10-12");
|
||||
expect(r.valid).toBe(true);
|
||||
expect(r.ranges).toEqual([
|
||||
{ start: 1, end: 3 },
|
||||
{ start: 7, end: 7 },
|
||||
{ start: 10, end: 12 },
|
||||
]);
|
||||
});
|
||||
|
||||
it("相邻/重叠范围合并(1-3,4-5 → 1-5)", () => {
|
||||
const r = parsePageRange("1-3,4-5");
|
||||
expect(r.valid).toBe(true);
|
||||
expect(r.ranges).toEqual([{ start: 1, end: 5 }]);
|
||||
});
|
||||
|
||||
it("空格/换行容忍", () => {
|
||||
const r = parsePageRange(" 1 - 5 , 7 , 10 - 12 ");
|
||||
expect(r.valid).toBe(true);
|
||||
expect(r.ranges).toHaveLength(3);
|
||||
});
|
||||
|
||||
it("totalPages 越界 clamp + 校验", () => {
|
||||
// 范围 end 越出 → clamp 到 totalPages
|
||||
const r = parsePageRange("1-5000", 3000);
|
||||
expect(r.valid).toBe(true);
|
||||
expect(r.ranges).toEqual([{ start: 1, end: 3000 }]);
|
||||
// 范围 start 越出 → fail-closed
|
||||
const r2 = parsePageRange("5000-6000", 3000);
|
||||
expect(r2.valid).toBe(false);
|
||||
expect(r2.error).toContain("exceeds");
|
||||
});
|
||||
|
||||
it("非法输入 fail-closed", () => {
|
||||
expect(parsePageRange("").valid).toBe(false);
|
||||
expect(parsePageRange("abc").valid).toBe(false);
|
||||
expect(parsePageRange("0-5").valid).toBe(false); // 页码 < 1
|
||||
expect(parsePageRange("5-1").valid).toBe(false); // start > end
|
||||
expect(parsePageRange("1-2,x,3").valid).toBe(false); // 混入非数字
|
||||
});
|
||||
|
||||
it("单页 7 → [{7,7}]", () => {
|
||||
const r = parsePageRange("7");
|
||||
expect(r.valid).toBe(true);
|
||||
expect(r.ranges).toEqual([{ start: 7, end: 7 }]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("pdf-reader expandPages — 展开页码列表", () => {
|
||||
it("展开 1-3,7,10-12", () => {
|
||||
const parsed = parsePageRange("1-3,7,10-12");
|
||||
expect(expandPages(parsed)).toEqual([1, 2, 3, 7, 10, 11, 12]);
|
||||
});
|
||||
|
||||
it("all 无 totalPages → 空数组", () => {
|
||||
const parsed = parsePageRange("all");
|
||||
expect(expandPages(parsed)).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ③ token 估算
|
||||
// ============================================================================
|
||||
|
||||
describe("pdf-reader extractTextBytes — token 估算(chars/4)", () => {
|
||||
it("ASCII 文本:chars=20 → tokens=5", () => {
|
||||
const text = "0123456789abcdefghij"; // 20 chars
|
||||
const est = extractTextBytes(text);
|
||||
expect(est.chars).toBe(20);
|
||||
expect(est.estimatedTokens).toBe(5);
|
||||
expect(est.estimatedBytes).toBe(20); // 纯 ASCII,字节=字符数
|
||||
});
|
||||
|
||||
it("chars=21 → tokens=6(向上取整)", () => {
|
||||
const est = extractTextBytes("0123456789abcdefghijX"); // 21 chars
|
||||
expect(est.estimatedTokens).toBe(6); // ceil(21/4)=6
|
||||
});
|
||||
|
||||
it("空文本 → 0 tokens", () => {
|
||||
const est = extractTextBytes("");
|
||||
expect(est.chars).toBe(0);
|
||||
expect(est.estimatedTokens).toBe(0);
|
||||
expect(est.estimatedBytes).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("pdf-reader utf8ByteLength — UTF-8 字节计算", () => {
|
||||
it("ASCII 每字符 1 字节", () => {
|
||||
expect(utf8ByteLength("hello")).toBe(5);
|
||||
});
|
||||
|
||||
it("Latin-1 补充(é)每字符 2 字节", () => {
|
||||
expect(utf8ByteLength("ééé")).toBe(6); // 3 × 2
|
||||
});
|
||||
|
||||
it("中文每字符 3 字节", () => {
|
||||
expect(utf8ByteLength("你好")).toBe(6); // 2 × 3
|
||||
});
|
||||
|
||||
it("emoji(代理对)每字符 4 字节", () => {
|
||||
expect(utf8ByteLength("🎉")).toBe(4); // surrogate pair → 4 bytes
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ④ 截断决策
|
||||
// ============================================================================
|
||||
|
||||
describe("pdf-reader shouldTruncate — 截断决策", () => {
|
||||
it("内容不超限 → 不截断", () => {
|
||||
const d = shouldTruncate(40_000, 500_000, 3000);
|
||||
expect(d.shouldTruncate).toBe(false);
|
||||
expect(d.suggestedPageCount).toBe(3000);
|
||||
expect(d.continuationHint).toBeNull();
|
||||
});
|
||||
|
||||
it("内容超限 → 截断 + 建议页数", () => {
|
||||
// 3000 页 PDF,总 3MB(3,000,000 bytes),上限 500KB
|
||||
const d = shouldTruncate(3_000_000, 500_000, 3000);
|
||||
expect(d.shouldTruncate).toBe(true);
|
||||
// bytesPerPage = 1000, 500000/1000 = 500 pages
|
||||
expect(d.suggestedPageCount).toBe(500);
|
||||
expect(d.continuationHint).toContain("offset=501");
|
||||
expect(d.continuationHint).toContain("of 3000");
|
||||
});
|
||||
|
||||
it("续读提示正确指向下一页", () => {
|
||||
const d = shouldTruncate(3_000_000, 500_000, 3000, 501);
|
||||
expect(d.shouldTruncate).toBe(true);
|
||||
// 从第 501 页读 500 页 → 下一页 = 1001
|
||||
expect(d.continuationHint).toContain("offset=1001");
|
||||
});
|
||||
|
||||
it("最后一页无需续读 → continuationHint=null", () => {
|
||||
// 从 2501 页读到 3000(500 页),下一页 3001 > 3000
|
||||
const d = shouldTruncate(3_000_000, 500_000, 3000, 2501);
|
||||
expect(d.shouldTruncate).toBe(true);
|
||||
// 剩余 500 页,恰好读完
|
||||
expect(d.continuationHint).toBeNull();
|
||||
});
|
||||
|
||||
it("零页 → 不截断", () => {
|
||||
const d = shouldTruncate(0, 500_000, 0);
|
||||
expect(d.shouldTruncate).toBe(false);
|
||||
expect(d.suggestedPageCount).toBe(0);
|
||||
});
|
||||
|
||||
it("小 PDF 即使字节小也不误截断", () => {
|
||||
const d = shouldTruncate(100, 500_000, 5);
|
||||
expect(d.shouldTruncate).toBe(false);
|
||||
expect(d.suggestedPageCount).toBe(5);
|
||||
});
|
||||
|
||||
it("建议页数至少为 1(即使单页就超限)", () => {
|
||||
// 1 页 PDF,10MB,上限 500KB → 建议至少读 1 页
|
||||
const d = shouldTruncate(10_000_000, 500_000, 1);
|
||||
expect(d.shouldTruncate).toBe(true);
|
||||
expect(d.suggestedPageCount).toBeGreaterThanOrEqual(1);
|
||||
expect(d.continuationHint).toBeNull(); // 只有一页,读完无续读
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ⑤ planPdfRead 整合
|
||||
// ============================================================================
|
||||
|
||||
describe("pdf-reader planPdfRead — 整合规划", () => {
|
||||
it('"all" 小 PDF → 全读不截断', () => {
|
||||
const plan = planPdfRead("all", 10, 20_000);
|
||||
expect(plan.pageRange).toEqual({ start: 1, end: 10 });
|
||||
expect(plan.truncated).toBe(false);
|
||||
expect(plan.continuationHint).toBeNull();
|
||||
});
|
||||
|
||||
it('"all" 大 PDF → 截断到建议页数', () => {
|
||||
const plan = planPdfRead("all", 3000, 3_000_000);
|
||||
expect(plan.truncated).toBe(true);
|
||||
expect(plan.pageRange.start).toBe(1);
|
||||
// bytesPerPage=1000, maxBytes=500*1024=512000, suggested=floor(512000/1000)=512
|
||||
expect(plan.pageRange.end).toBe(512);
|
||||
expect(plan.continuationHint).toContain("offset=513");
|
||||
});
|
||||
|
||||
it("指定页范围不超限 → 原样返回", () => {
|
||||
const plan = planPdfRead("10-20", 3000, 3_000_000);
|
||||
expect(plan.pageRange).toEqual({ start: 10, end: 20 });
|
||||
expect(plan.truncated).toBe(false);
|
||||
expect(plan.pageCount).toBe(11);
|
||||
});
|
||||
|
||||
it("指定页范围超限 → 截断到建议页数", () => {
|
||||
// 请求 1-2000 页,但建议每次只读 512 页
|
||||
const plan = planPdfRead("1-2000", 3000, 3_000_000);
|
||||
expect(plan.truncated).toBe(true);
|
||||
expect(plan.pageRange).toEqual({ start: 1, end: 512 });
|
||||
expect(plan.continuationHint).toContain("offset=513");
|
||||
});
|
||||
|
||||
it("非法输入 fail-closed 回退首页", () => {
|
||||
const plan = planPdfRead("garbage", 3000, 3_000_000);
|
||||
expect(plan.pageRange.start).toBe(1);
|
||||
expect(plan.truncated).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ⑥ 提限配置
|
||||
// ============================================================================
|
||||
|
||||
describe("pdf-reader 提限配置", () => {
|
||||
it("DATASHEET_READ_LIMITS 治截断命门:8000 行 / 500KB", () => {
|
||||
expect(DATASHEET_READ_LIMITS.maxLines).toBe(8000);
|
||||
expect(DATASHEET_READ_LIMITS.maxBytes).toBe(500 * 1024);
|
||||
// 不再是旧的 2000 行 / 50KB
|
||||
expect(DATASHEET_READ_LIMITS.maxLines).not.toBe(2000);
|
||||
expect(DATASHEET_READ_LIMITS.maxBytes).not.toBe(50 * 1024);
|
||||
});
|
||||
|
||||
it("LEGACY_READ_LIMITS 保留旧值供对比", () => {
|
||||
expect(LEGACY_READ_LIMITS.maxLines).toBe(2000);
|
||||
expect(LEGACY_READ_LIMITS.maxBytes).toBe(50 * 1024);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// ⑦ buildReadResult
|
||||
// ============================================================================
|
||||
|
||||
describe("pdf-reader buildReadResult — 构建带续读提示的结果", () => {
|
||||
it("截断时带 header + footer + 续读提示", () => {
|
||||
const text = "register 0x40020000\n";
|
||||
const result = buildReadResult(
|
||||
text,
|
||||
{ start: 1, end: 500 },
|
||||
3000,
|
||||
true,
|
||||
"use offset=501 to continue (pages 1-500 of 3000 shown)",
|
||||
);
|
||||
expect(result).toContain("pages 1-500 of 3000");
|
||||
expect(result).toContain("tokens");
|
||||
expect(result).toContain("[truncated]");
|
||||
expect(result).toContain("offset=501");
|
||||
// 寄存器地址原样保留(无数值归一,不触发 hex 强转砖板)
|
||||
expect(result).toContain("register 0x40020000");
|
||||
});
|
||||
|
||||
it("未截断时无 footer", () => {
|
||||
const result = buildReadResult(
|
||||
"hello",
|
||||
{ start: 1, end: 10 },
|
||||
10,
|
||||
false,
|
||||
null,
|
||||
);
|
||||
expect(result).not.toContain("[truncated]");
|
||||
expect(result).toContain("hello");
|
||||
});
|
||||
|
||||
it("寄存器地址原样保留(datasheet-safe)", () => {
|
||||
const text = "BASE_ADDR 0x40020000 CTRL 0x40020004";
|
||||
const result = buildReadResult(text, { start: 1, end: 1 }, 1, false, null);
|
||||
expect(result).toContain("0x40020000");
|
||||
expect(result).toContain("0x40020004");
|
||||
expect(result).not.toContain("1073872896"); // 不被强转成十进制
|
||||
});
|
||||
});
|
||||
347
tests/peripheral-probe.test.ts
Normal file
347
tests/peripheral-probe.test.ts
Normal file
@ -0,0 +1,347 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
parseHexAddr,
|
||||
toHexAddr,
|
||||
isValidI2cAddr,
|
||||
parseI2cDetect,
|
||||
presentAddresses,
|
||||
parseGpioInfo,
|
||||
probeGpio,
|
||||
probeI2c,
|
||||
discoverI2cBuses,
|
||||
probeSpi,
|
||||
probeUdev,
|
||||
probeMemSnap,
|
||||
type ExecFn,
|
||||
} from "../src/extensions/peripheral-probe.js";
|
||||
|
||||
// ---- mock ExecFn 工厂 ----
|
||||
function mkExec(
|
||||
map: Record<string, (args: string[]) => { stdout: string; stderr: string; exitCode: number }>,
|
||||
): ExecFn {
|
||||
return async (command: string, args: string[]) => {
|
||||
const fn = map[command];
|
||||
if (fn) return fn(args);
|
||||
return { stdout: "", stderr: `command not found: ${command}`, exitCode: 127 };
|
||||
};
|
||||
}
|
||||
|
||||
// ---- i2cdetect 输出构造器(固定 3 字符列)----
|
||||
function buildI2cDetect(
|
||||
overrides: Record<string, "present" | "empty" | "inuse" | "blank"> = {},
|
||||
): string {
|
||||
const lines = [" 0 1 2 3 4 5 6 7 8 9 a b c d e f"];
|
||||
for (let row = 0; row < 8; row++) {
|
||||
const base = row * 16;
|
||||
const header = base.toString(16).padStart(2, "0") + ":";
|
||||
const fields: string[] = [];
|
||||
for (let col = 0; col < 16; col++) {
|
||||
const addr = base + col;
|
||||
const key = "0x" + addr.toString(16).padStart(2, "0");
|
||||
const v = overrides[key];
|
||||
const def = row === 0 && col < 8 ? "blank" : "empty";
|
||||
const kind = v ?? def;
|
||||
if (kind === "present") fields.push(addr.toString(16).padStart(2, "0") + " ");
|
||||
else if (kind === "empty") fields.push("-- ");
|
||||
else if (kind === "inuse") fields.push("UU ");
|
||||
else fields.push(" ");
|
||||
}
|
||||
lines.push(header + " " + fields.join(""));
|
||||
}
|
||||
return lines.join("\n");
|
||||
}
|
||||
|
||||
describe("peripheral-probe hex 防御 — parseHexAddr", () => {
|
||||
it('"0x50" → 0x50 (80)', () => {
|
||||
expect(parseHexAddr("0x50")).toBe(0x50);
|
||||
});
|
||||
|
||||
it('"80"(十进制)→ 80 = 0x50,与 hex 等值', () => {
|
||||
// 缺陷 #8 核心:agent 传十进制 80 和 hex 0x50 解析为同一 I2C 地址
|
||||
expect(parseHexAddr("80")).toBe(0x50);
|
||||
expect(parseHexAddr("80")).toBe(parseHexAddr("0x50"));
|
||||
});
|
||||
|
||||
it("number 80 → 80 = 0x50", () => {
|
||||
expect(parseHexAddr(80)).toBe(0x50);
|
||||
});
|
||||
|
||||
it("0x10 寄存器地址 → 16", () => {
|
||||
expect(parseHexAddr("0x10")).toBe(16);
|
||||
});
|
||||
|
||||
it('fallback 纯 hex "FF" → 0xFF', () => {
|
||||
expect(parseHexAddr("FF")).toBe(0xff);
|
||||
});
|
||||
|
||||
it("非法值抛错(fail-closed)", () => {
|
||||
expect(() => parseHexAddr("")).toThrow();
|
||||
expect(() => parseHexAddr("xyz")).toThrow();
|
||||
});
|
||||
|
||||
it("toHexAddr 规整成两位填充大写", () => {
|
||||
expect(toHexAddr(0x50)).toBe("0x50");
|
||||
expect(toHexAddr(0x5)).toBe("0x05");
|
||||
});
|
||||
|
||||
it("isValidI2cAddr 7-bit 范围 0x03–0x77", () => {
|
||||
expect(isValidI2cAddr(0x03)).toBe(true);
|
||||
expect(isValidI2cAddr(0x77)).toBe(true);
|
||||
expect(isValidI2cAddr(0x00)).toBe(false);
|
||||
expect(isValidI2cAddr(0x7f)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("peripheral-probe parseI2cDetect — i2cdetect 输出解析", () => {
|
||||
const table = parseI2cDetect(
|
||||
buildI2cDetect({
|
||||
"0x20": "present",
|
||||
"0x21": "present",
|
||||
"0x22": "present",
|
||||
"0x23": "present",
|
||||
"0x24": "present",
|
||||
"0x25": "present",
|
||||
"0x26": "present",
|
||||
"0x27": "present",
|
||||
"0x68": "present",
|
||||
"0x77": "present",
|
||||
"0x50": "inuse",
|
||||
"0x78": "inuse",
|
||||
}),
|
||||
);
|
||||
|
||||
it("解析 0x20–0x27 为 present", () => {
|
||||
const present = table.filter((r) => r.status === "present");
|
||||
for (let a = 0x20; a <= 0x27; a++) {
|
||||
expect(present.some((r) => r.addr === a)).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it("0x20 的 hex 标记正确", () => {
|
||||
const r = table.find((x) => x.addr === 0x20);
|
||||
expect(r?.hex).toBe("0x20");
|
||||
});
|
||||
|
||||
it("UU 标记为 in-use", () => {
|
||||
const r = table.find((x) => x.addr === 0x50);
|
||||
expect(r?.status).toBe("in-use");
|
||||
const r78 = table.find((x) => x.addr === 0x78);
|
||||
expect(r78?.status).toBe("in-use");
|
||||
});
|
||||
|
||||
it("-- 标记为 empty", () => {
|
||||
const r = table.find((x) => x.addr === 0x10);
|
||||
expect(r?.status).toBe("empty");
|
||||
});
|
||||
|
||||
it("保留地址 0x00–0x02 不出现(i2cdetect 不探测)", () => {
|
||||
expect(table.find((x) => x.addr === 0x00)).toBeUndefined();
|
||||
expect(table.find((x) => x.addr === 0x02)).toBeUndefined();
|
||||
});
|
||||
|
||||
it("presentAddresses 返回数值数组(排除 empty/in-use)", () => {
|
||||
const addrs = presentAddresses(table);
|
||||
expect(addrs).toContain(0x20);
|
||||
expect(addrs).toContain(0x68);
|
||||
expect(addrs).toContain(0x77);
|
||||
expect(addrs).not.toContain(0x10); // empty
|
||||
expect(addrs).not.toContain(0x50); // in-use
|
||||
});
|
||||
|
||||
it("空输出返回空数组", () => {
|
||||
expect(parseI2cDetect("")).toEqual([]);
|
||||
expect(parseI2cDetect("no match here")).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("peripheral-probe parseGpioInfo — gpioinfo 输出解析", () => {
|
||||
const output = `gpiochip0 - 512 lines:
|
||||
\tline 0: "PIN3" unused output active-high
|
||||
\tline 1: "PIN5" unused input active-high
|
||||
gpiochip1 - 256 lines:
|
||||
\tline 0: unnamed unused input active-high`;
|
||||
const chips = parseGpioInfo(output);
|
||||
|
||||
it("解析出两个 chip", () => {
|
||||
expect(chips).toHaveLength(2);
|
||||
expect(chips[0]?.chip).toBe("gpiochip0");
|
||||
expect(chips[0]?.lines).toBe(512);
|
||||
expect(chips[1]?.chip).toBe("gpiochip1");
|
||||
expect(chips[1]?.lines).toBe(256);
|
||||
});
|
||||
|
||||
it("chip0 line0 = PIN3 / output", () => {
|
||||
const l = chips[0]?.lineDetails[0];
|
||||
expect(l?.offset).toBe(0);
|
||||
expect(l?.name).toBe("PIN3");
|
||||
expect(l?.direction).toBe("output");
|
||||
});
|
||||
|
||||
it("chip0 line1 = PIN5 / input", () => {
|
||||
const l = chips[0]?.lineDetails[1];
|
||||
expect(l?.offset).toBe(1);
|
||||
expect(l?.direction).toBe("input");
|
||||
});
|
||||
});
|
||||
|
||||
describe("peripheral-probe probeGpio — mock 返回 chip", () => {
|
||||
it("probeGpio mock 返回 gpiochip0(核心路径)", async () => {
|
||||
const exec = mkExec({
|
||||
gpioinfo: () => ({
|
||||
stdout: `gpiochip0 - 512 lines:
|
||||
\tline 0: "PIN3" unused output active-high`,
|
||||
stderr: "",
|
||||
exitCode: 0,
|
||||
}),
|
||||
});
|
||||
const chips = await probeGpio(exec);
|
||||
expect(chips[0]?.chip).toBe("gpiochip0");
|
||||
expect(chips[0]?.lines).toBe(512);
|
||||
expect(chips[0]?.lineDetails[0]?.name).toBe("PIN3");
|
||||
});
|
||||
|
||||
it("gpioinfo 失败抛错(fail-closed)", async () => {
|
||||
const exec = mkExec({
|
||||
gpioinfo: () => ({ stdout: "", stderr: "gpioinfo: not found", exitCode: 127 }),
|
||||
});
|
||||
await expect(probeGpio(exec)).rejects.toThrow(/gpioinfo failed/);
|
||||
});
|
||||
});
|
||||
|
||||
describe("peripheral-probe probeI2c — mock 总线探测", () => {
|
||||
it("probeI2c mock 返回 bus 0 + 0x20–0x27 设备", async () => {
|
||||
const detect = buildI2cDetect({
|
||||
"0x20": "present",
|
||||
"0x21": "present",
|
||||
"0x22": "present",
|
||||
"0x23": "present",
|
||||
"0x24": "present",
|
||||
"0x25": "present",
|
||||
"0x26": "present",
|
||||
"0x27": "present",
|
||||
"0x50": "inuse",
|
||||
});
|
||||
const exec = mkExec({
|
||||
i2cdetect: () => ({ stdout: detect, stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const buses = await probeI2c(exec, [0]);
|
||||
expect(buses).toHaveLength(1);
|
||||
expect(buses[0]?.bus).toBe(0);
|
||||
expect(buses[0]?.devices).toEqual([0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27]);
|
||||
expect(buses[0]?.inUse).toEqual([0x50]);
|
||||
});
|
||||
|
||||
it("i2cdetect 非零退出 → 记录 error 不抛(fail-closed 暴露)", async () => {
|
||||
const exec = mkExec({
|
||||
i2cdetect: () => ({ stdout: "", stderr: "could not open file", exitCode: 1 }),
|
||||
});
|
||||
const buses = await probeI2c(exec, [2]);
|
||||
expect(buses[0]?.bus).toBe(2);
|
||||
expect(buses[0]?.devices).toEqual([]);
|
||||
expect(buses[0]?.error).toContain("could not open file");
|
||||
});
|
||||
|
||||
it("无 buses 参数 → discoverI2cBuses 枚举 /dev/i2c-*", async () => {
|
||||
const exec = mkExec({
|
||||
sh: (args) => {
|
||||
if (args[1]?.includes("/dev/i2c-")) {
|
||||
return { stdout: "/dev/i2c-0\n/dev/i2c-1\n", stderr: "", exitCode: 0 };
|
||||
}
|
||||
return { stdout: "", stderr: "", exitCode: 0 };
|
||||
},
|
||||
i2cdetect: () => ({ stdout: buildI2cDetect({ "0x20": "present" }), stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const buses = await probeI2c(exec);
|
||||
expect(buses.map((b) => b.bus)).toEqual([0, 1]);
|
||||
});
|
||||
|
||||
it("discoverI2cBuses 解析总线号并升序", async () => {
|
||||
const exec = mkExec({
|
||||
sh: () => ({ stdout: "/dev/i2c-3\n/dev/i2c-1\n/dev/i2c-0\n", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const buses = await discoverI2cBuses(exec);
|
||||
expect(buses).toEqual([0, 1, 3]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("peripheral-probe probeSpi — /dev/spidev* 枚举", () => {
|
||||
it("返回 spidev 设备并解析 bus/cs", async () => {
|
||||
const exec = mkExec({
|
||||
sh: () => ({ stdout: "/dev/spidev0.0\n/dev/dev/spidev1.1\n/dev/spidev2.0\n", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
const devs = await probeSpi(exec);
|
||||
expect(devs).toHaveLength(2);
|
||||
expect(devs[0]?.dev).toBe("/dev/spidev0.0");
|
||||
expect(devs[0]?.bus).toBe(0);
|
||||
expect(devs[0]?.chipSelect).toBe(0);
|
||||
expect(devs[1]?.dev).toBe("/dev/spidev2.0");
|
||||
expect(devs[1]?.bus).toBe(2);
|
||||
});
|
||||
|
||||
it("无 SPI 设备返回空", async () => {
|
||||
const exec = mkExec({
|
||||
sh: () => ({ stdout: "", stderr: "", exitCode: 0 }),
|
||||
});
|
||||
expect(await probeSpi(exec)).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("peripheral-probe probeUdev — sysfs class 枚举", () => {
|
||||
it('probeUdev("net") 返回网卡', async () => {
|
||||
const exec = mkExec({
|
||||
sh: (args) => ({
|
||||
stdout: args[1]?.includes("/sys/class/net/") ? "eth0\nwlan0\n" : "",
|
||||
stderr: "",
|
||||
exitCode: 0,
|
||||
}),
|
||||
});
|
||||
const devs = await probeUdev(exec, "net");
|
||||
expect(devs.map((d) => d.name).sort()).toEqual(["eth0", "wlan0"]);
|
||||
expect(devs[0]?.subsystem).toBe("net");
|
||||
});
|
||||
|
||||
it("subsystem 清洗防 shell 注入", async () => {
|
||||
const calls: string[] = [];
|
||||
const exec: ExecFn = async (_cmd, args) => {
|
||||
calls.push(args.join(" "));
|
||||
return { stdout: "", stderr: "", exitCode: 0 };
|
||||
};
|
||||
await probeUdev(exec, "net; rm -rf /");
|
||||
// 危险字符被剥离,只剩字母数字下划线连字符
|
||||
expect(calls[0]).not.toContain("rm -rf");
|
||||
expect(calls[0]).not.toContain(";");
|
||||
});
|
||||
|
||||
it("空 subsystem 返回空数组", async () => {
|
||||
const exec = mkExec({});
|
||||
expect(await probeUdev(exec, "")).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("peripheral-probe probeMemSnap — /proc 快照", () => {
|
||||
it("返回 iomem + interrupts 内容", async () => {
|
||||
const exec = mkExec({
|
||||
cat: (args) => {
|
||||
if (args[0] === "/proc/iomem") {
|
||||
return { stdout: "40000000-40000fff : uart\n", stderr: "", exitCode: 0 };
|
||||
}
|
||||
if (args[0] === "/proc/interrupts") {
|
||||
return { stdout: " 0: 1234 ARM GIC\n", stderr: "", exitCode: 0 };
|
||||
}
|
||||
return { stdout: "", stderr: "", exitCode: 1 };
|
||||
},
|
||||
});
|
||||
const snap = await probeMemSnap(exec);
|
||||
expect(snap.iomem).toContain("uart");
|
||||
expect(snap.interrupts).toContain("GIC");
|
||||
});
|
||||
|
||||
it("/proc 不可读时返回空串(不抛)", async () => {
|
||||
const exec = mkExec({
|
||||
cat: () => ({ stdout: "", stderr: "denied", exitCode: 1 }),
|
||||
});
|
||||
const snap = await probeMemSnap(exec);
|
||||
expect(snap.iomem).toBe("");
|
||||
expect(snap.interrupts).toBe("");
|
||||
});
|
||||
});
|
||||
317
tests/persistent-shell.test.ts
Normal file
317
tests/persistent-shell.test.ts
Normal file
@ -0,0 +1,317 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
PShellPool,
|
||||
buildSentinelCommand,
|
||||
parseSentinelOutput,
|
||||
PSHELL_SENTINEL,
|
||||
type PShellSendResult,
|
||||
} from "../src/extensions/persistent-shell.js";
|
||||
import type { ExecFn, ExecResult } from "../src/shared/types.js";
|
||||
|
||||
/** 构造一个 mock ExecFn:直接把命令"执行"成带哨兵的 stdout。 */
|
||||
function makeMockExec(reply: (cmd: string) => string): ExecFn {
|
||||
return async (command: string) => {
|
||||
const out = reply(command);
|
||||
return { stdout: out, stderr: "", exitCode: 0 } as ExecResult;
|
||||
};
|
||||
}
|
||||
|
||||
describe("persistent-shell sentinel — buildSentinelCommand", () => {
|
||||
it("给命令追加哨兵 + exitCode 回显", () => {
|
||||
const c = buildSentinelCommand("break main");
|
||||
expect(c).toBe(`break main; echo "${PSHELL_SENTINEL}$?"`);
|
||||
});
|
||||
|
||||
it("空命令也安全(仅回显哨兵)", () => {
|
||||
const c = buildSentinelCommand("");
|
||||
expect(c).toBe(`echo "${PSHELL_SENTINEL}$?"`);
|
||||
});
|
||||
|
||||
it("尾部空白被 trim", () => {
|
||||
const c = buildSentinelCommand("ls -la\n");
|
||||
expect(c).toBe(`ls -la; echo "${PSHELL_SENTINEL}$?"`);
|
||||
});
|
||||
});
|
||||
|
||||
describe("persistent-shell sentinel — parseSentinelOutput", () => {
|
||||
it("解析正常 stdout + exit 0", () => {
|
||||
const raw = `Breakpoint 1 at 0x...\n${PSHELL_SENTINEL}0\n`;
|
||||
const p = parseSentinelOutput(raw);
|
||||
expect(p.found).toBe(true);
|
||||
expect(p.exitCode).toBe(0);
|
||||
expect(p.stdout).toBe("Breakpoint 1 at 0x...");
|
||||
});
|
||||
|
||||
it("解析非零 exitCode", () => {
|
||||
const raw = `err\n${PSHELL_SENTINEL}127\n`;
|
||||
const p = parseSentinelOutput(raw);
|
||||
expect(p.exitCode).toBe(127);
|
||||
expect(p.stdout).toBe("err");
|
||||
});
|
||||
|
||||
it("兼容 PTY 的 \\r 混杂", () => {
|
||||
const raw = `out\r\n${PSHELL_SENTINEL}0\r\n`;
|
||||
const p = parseSentinelOutput(raw);
|
||||
expect(p.found).toBe(true);
|
||||
expect(p.exitCode).toBe(0);
|
||||
});
|
||||
|
||||
it("未找到哨兵 → found=false exitCode=null(fail-closed)", () => {
|
||||
const p = parseSentinelOutput("partial output, no sentinel");
|
||||
expect(p.found).toBe(false);
|
||||
expect(p.exitCode).toBeNull();
|
||||
expect(p.stdout).toBe("partial output, no sentinel");
|
||||
});
|
||||
|
||||
it("null 输入安全", () => {
|
||||
const p = parseSentinelOutput(null as unknown as string);
|
||||
expect(p.found).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("persistent-shell PShellPool — open/close/list", () => {
|
||||
it("open 返回非空 id", () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
expect(typeof id).toBe("string");
|
||||
expect(id.length).toBeGreaterThan(0);
|
||||
expect(pool.has(id)).toBe(true);
|
||||
});
|
||||
|
||||
it("open 接受自定义 id 生成器(确定性 id)", () => {
|
||||
let n = 0;
|
||||
const pool = new PShellPool({ idGenerator: () => `fixed-${++n}` });
|
||||
expect(pool.open()).toBe("fixed-1");
|
||||
expect(pool.open()).toBe("fixed-2");
|
||||
});
|
||||
|
||||
it("close 释放会话", () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
expect(pool.close(id)).toBe(true);
|
||||
expect(pool.has(id)).toBe(false);
|
||||
});
|
||||
|
||||
it("close 不存在的 id 返回 false 不抛", () => {
|
||||
const pool = new PShellPool();
|
||||
expect(pool.close("nope")).toBe(false);
|
||||
});
|
||||
|
||||
it("list 列出全部会话(按创建顺序)", () => {
|
||||
const pool = new PShellPool();
|
||||
pool.open({ id: "a" });
|
||||
pool.open({ id: "b" });
|
||||
const all = pool.list();
|
||||
expect(all.map((s) => s.id)).toEqual(["a", "b"]);
|
||||
expect(all[0]).toMatchObject({ id: "a", busy: false });
|
||||
});
|
||||
|
||||
it("closeAll 清空全部并返回 id 列表", () => {
|
||||
const pool = new PShellPool();
|
||||
pool.open({ id: "a" });
|
||||
pool.open({ id: "b" });
|
||||
const closed = pool.closeAll();
|
||||
expect(closed.sort()).toEqual(["a", "b"]);
|
||||
expect(pool.list()).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("get 投影公开字段,不泄露 pending/cwd", () => {
|
||||
const pool = new PShellPool({ defaultCwd: "/work" });
|
||||
const id = pool.open();
|
||||
const s = pool.get(id);
|
||||
expect(s).toBeDefined();
|
||||
expect(s).toHaveProperty("createdAt");
|
||||
expect(s).toHaveProperty("busy");
|
||||
// 不应包含内部字段
|
||||
expect(s).not.toHaveProperty("pending");
|
||||
expect(s).not.toHaveProperty("cwd");
|
||||
});
|
||||
});
|
||||
|
||||
describe("persistent-shell PShellPool — send", () => {
|
||||
it("send 在未知 session 上 fail-closed", async () => {
|
||||
const pool = new PShellPool();
|
||||
const r = await pool.send("ghost", "ls", makeMockExec(() => `${PSHELL_SENTINEL}0\n`));
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toBe("session-not-found");
|
||||
});
|
||||
|
||||
it("send 执行命令并解析 stdout/exitCode", async () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
const r = await pool.send(id, "echo hello", makeMockExec(() => `hello\n${PSHELL_SENTINEL}0\n`));
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.stdout).toBe("hello");
|
||||
expect(r.exitCode).toBe(0);
|
||||
// lastCommand 记录
|
||||
expect(pool.get(id)?.lastCommand).toBe("echo hello");
|
||||
});
|
||||
|
||||
it("send 传非零 exitCode", async () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
const r: PShellSendResult = await pool.send(
|
||||
id,
|
||||
"false",
|
||||
makeMockExec(() => `${PSHELL_SENTINEL}1\n`),
|
||||
);
|
||||
expect(r.ok).toBe(true);
|
||||
expect(r.exitCode).toBe(1);
|
||||
});
|
||||
|
||||
it("execFn 抛错(超时)→ ok=false error=timeout,会话不锁死", async () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
const execFn = async () => {
|
||||
throw new Error("command timed out after 1000ms");
|
||||
};
|
||||
const r = await pool.send(id, "sleep 100", execFn, { timeoutMs: 1000 });
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toBe("timeout");
|
||||
expect(pool.isBusy(id)).toBe(false); // 未锁死
|
||||
});
|
||||
|
||||
it("哨兵缺失 → ok=false error=sentinel-missing(不信伪完成)", async () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
const r = await pool.send(id, "hang", makeMockExec(() => "never finishes..."));
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toBe("sentinel-missing");
|
||||
});
|
||||
|
||||
it("execFn 抛非超时错 → error=exec-failed", async () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
const execFn = async () => {
|
||||
throw new Error("spawn ENOENT");
|
||||
};
|
||||
const r = await pool.send(id, "nope", execFn);
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toBe("exec-failed");
|
||||
expect(pool.isBusy(id)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("persistent-shell PShellPool — busy reject(默认 fail-closed)", () => {
|
||||
it("busy 时 send 被拒绝", async () => {
|
||||
const pool = new PShellPool({ busyPolicy: "reject" });
|
||||
const id = pool.open();
|
||||
// 用一个 block 的 execFn 模拟 gdb 长会话占用
|
||||
let release: () => void = () => {};
|
||||
const block = new Promise<void>((res) => {
|
||||
release = res;
|
||||
});
|
||||
const execFn = async () => {
|
||||
await block;
|
||||
return { stdout: `${PSHELL_SENTINEL}0\n`, stderr: "", exitCode: 0 } as ExecResult;
|
||||
};
|
||||
const inFlight = pool.send(id, "run", execFn);
|
||||
// 等一拍让上面进入 busy
|
||||
await Promise.resolve();
|
||||
expect(pool.isBusy(id)).toBe(true);
|
||||
|
||||
const r = await pool.send(id, "info breakpoints", makeMockExec(() => `${PSHELL_SENTINEL}0\n`));
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toBe("busy");
|
||||
|
||||
release();
|
||||
const done = await inFlight;
|
||||
expect(done.ok).toBe(true);
|
||||
expect(pool.isBusy(id)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("persistent-shell PShellPool — busy queue", () => {
|
||||
it("busy 时 send 排队,当前完成后 drain 执行", async () => {
|
||||
const pool = new PShellPool({ busyPolicy: "queue" });
|
||||
const id = pool.open();
|
||||
let release: () => void = () => {};
|
||||
const block = new Promise<void>((res) => {
|
||||
release = res;
|
||||
});
|
||||
const execFn = async (command: string) => {
|
||||
// 第一条命令 block;后续 drain 的命令立即返回
|
||||
if (command.includes("run")) {
|
||||
await block;
|
||||
}
|
||||
return { stdout: `ok\n${PSHELL_SENTINEL}0\n`, stderr: "", exitCode: 0 } as ExecResult;
|
||||
};
|
||||
|
||||
const first = pool.send(id, "run", execFn);
|
||||
await Promise.resolve();
|
||||
expect(pool.isBusy(id)).toBe(true);
|
||||
|
||||
const queued = await pool.send(id, "info breakpoints", execFn);
|
||||
expect(queued.ok).toBe(false);
|
||||
expect(queued.queued).toBe(true);
|
||||
expect(queued.error).toBe("busy");
|
||||
|
||||
release();
|
||||
const done = await first;
|
||||
expect(done.ok).toBe(true);
|
||||
|
||||
// 让 drain 的微任务/await 跑完
|
||||
await new Promise((res) => setTimeout(res, 30));
|
||||
// 排队命令已 drain,lastCommand 更新为后一条
|
||||
expect(pool.get(id)?.lastCommand).toBe("info breakpoints");
|
||||
expect(pool.isBusy(id)).toBe(false);
|
||||
});
|
||||
|
||||
it("close 会话时丢弃待执行队列", () => {
|
||||
const pool = new PShellPool({ busyPolicy: "queue" });
|
||||
const id = pool.open();
|
||||
// 直接构造 pending(不真实执行,只验证 close 清空不抛)
|
||||
expect(pool.close(id)).toBe(true);
|
||||
expect(pool.has(id)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("persistent-shell PShellPool — markBusy(gdb/openocd 长会话)", () => {
|
||||
it("markBusy 标记后 send 被拒(reject 策略)", async () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
expect(pool.markBusy(id, true)).toBe(true);
|
||||
expect(pool.isBusy(id)).toBe(true);
|
||||
const r = await pool.send(id, "ls", makeMockExec(() => `${PSHELL_SENTINEL}0\n`));
|
||||
expect(r.ok).toBe(false);
|
||||
expect(r.error).toBe("busy");
|
||||
// 释放
|
||||
pool.markBusy(id, false);
|
||||
expect(pool.isBusy(id)).toBe(false);
|
||||
});
|
||||
|
||||
it("markBusy 未知 id 返回 false", () => {
|
||||
const pool = new PShellPool();
|
||||
expect(pool.markBusy("nope", true)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("persistent-shell PShellPool — sweepIdle 回收", () => {
|
||||
it("idle 超时被回收", () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
// lastActivityAt 是 createdAt;sweepIdle(now=now+11min) 会判定 createdAt 距 now 超过 idleMs。
|
||||
const future = Date.now() + 11 * 60 * 1000;
|
||||
const closed = pool.sweepIdle(future, 10 * 60 * 1000);
|
||||
expect(closed).toEqual([id]);
|
||||
expect(pool.has(id)).toBe(false);
|
||||
});
|
||||
|
||||
it("busy 会话不回收(gdb/openocd 正占用)", () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
pool.markBusy(id, true);
|
||||
const future = Date.now() + 11 * 60 * 1000;
|
||||
const closed = pool.sweepIdle(future, 10 * 60 * 1000);
|
||||
expect(closed).toEqual([]);
|
||||
expect(pool.has(id)).toBe(true);
|
||||
});
|
||||
|
||||
it("未超时不回收", () => {
|
||||
const pool = new PShellPool();
|
||||
const id = pool.open();
|
||||
const closed = pool.sweepIdle(Date.now() + 60 * 1000, 10 * 60 * 1000);
|
||||
expect(closed).toEqual([]);
|
||||
expect(pool.has(id)).toBe(true);
|
||||
});
|
||||
});
|
||||
129
tests/safety-gate.test.ts
Normal file
129
tests/safety-gate.test.ts
Normal file
@ -0,0 +1,129 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
evaluateSafety,
|
||||
DESTRUCTIVE_RULES,
|
||||
ResourceLock,
|
||||
extractDeviceId,
|
||||
allowedToolsForSkill,
|
||||
SKILL_ALLOWED_TOOLS,
|
||||
} from "../src/extensions/safety-gate.js";
|
||||
|
||||
describe("safety-gate 破坏性命令检测(fail-closed)", () => {
|
||||
it("dd 写块设备被拦截", () => {
|
||||
const d = evaluateSafety("dd if=image.bin of=/dev/mmcblk0 bs=4M");
|
||||
expect(d.block).toBe(true);
|
||||
expect(d.rule).toBe("dd-to-block-device");
|
||||
expect(d.safeAlternative).toContain("flash");
|
||||
});
|
||||
|
||||
it("fastboot flash 被拦截", () => {
|
||||
expect(evaluateSafety("fastboot flash boot boot.img").block).toBe(true);
|
||||
});
|
||||
|
||||
it("mkfs 格式化设备被拦截", () => {
|
||||
expect(evaluateSafety("mkfs.ext4 /dev/sda1").block).toBe(true);
|
||||
});
|
||||
|
||||
it("devmem 写寄存器被拦截", () => {
|
||||
expect(evaluateSafety("devmem 0x40020000 w 0x1").block).toBe(true);
|
||||
});
|
||||
|
||||
it("openocd program 被拦截", () => {
|
||||
expect(evaluateSafety("openocd -f cfg.cfg -c 'program firmware.elf'").block).toBe(true);
|
||||
});
|
||||
|
||||
it("rm /dev 被拦截", () => {
|
||||
expect(evaluateSafety("rm -rf /dev/i2c-0").block).toBe(true);
|
||||
});
|
||||
|
||||
it("rm -rf / 被拦截", () => {
|
||||
expect(evaluateSafety("rm -rf /").block).toBe(true);
|
||||
});
|
||||
|
||||
it("安全命令不拦截(i2cdump 读操作)", () => {
|
||||
expect(evaluateSafety("i2cdump -y 0 0x76").block).toBe(false);
|
||||
expect(evaluateSafety("").block).toBe(false);
|
||||
});
|
||||
|
||||
it("allowRules 豁免:flash 工具内部 dd 不被拦截", () => {
|
||||
expect(
|
||||
evaluateSafety("dd if=image.bin of=/dev/mmcblk0 bs=4M", { allowRules: ["dd-to-block-device"] }).block,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("常见编译/读取命令不误拦", () => {
|
||||
for (const cmd of [
|
||||
"aarch64-linux-gnu-gcc -o app main.c",
|
||||
"cmake --build .",
|
||||
"cat /sys/class/gpio/gpio33/value",
|
||||
"dmesg | grep i2c",
|
||||
]) {
|
||||
expect(evaluateSafety(cmd).block).toBe(false);
|
||||
}
|
||||
});
|
||||
|
||||
it("规则集覆盖至少 7 条", () => {
|
||||
expect(DESTRUCTIVE_RULES.length).toBeGreaterThanOrEqual(7);
|
||||
});
|
||||
});
|
||||
|
||||
describe("safety-gate 资源锁 ResourceLock", () => {
|
||||
it("首次获取成功 + 重入同 owner 允许", () => {
|
||||
const lock = new ResourceLock();
|
||||
expect(lock.acquire("i2c-bus-0", "a")).toBe(true);
|
||||
expect(lock.acquire("i2c-bus-0", "a")).toBe(true);
|
||||
});
|
||||
|
||||
it("不同 owner 抢占失败(fail-closed)", () => {
|
||||
const lock = new ResourceLock();
|
||||
lock.acquire("i2c-bus-0", "a");
|
||||
expect(lock.acquire("i2c-bus-0", "b")).toBe(false);
|
||||
});
|
||||
|
||||
it("释放后可被其他 owner 获取", () => {
|
||||
const lock = new ResourceLock();
|
||||
lock.acquire("i2c-bus-0", "a");
|
||||
expect(lock.release("i2c-bus-0", "a")).toBe(true);
|
||||
expect(lock.acquire("i2c-bus-0", "b")).toBe(true);
|
||||
});
|
||||
|
||||
it("releaseAll 清理某 owner 全部锁", () => {
|
||||
const lock = new ResourceLock();
|
||||
lock.acquire("i2c-bus-0", "a");
|
||||
lock.acquire("gpiochip0", "a");
|
||||
lock.acquire("i2c-bus-1", "b");
|
||||
expect(lock.releaseAll("a").sort()).toEqual(["gpiochip0", "i2c-bus-0"]);
|
||||
expect(lock.isLocked("i2c-bus-1")).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("safety-gate extractDeviceId", () => {
|
||||
it("i2cget/i2cdump 提取总线号", () => {
|
||||
expect(extractDeviceId("i2cget -y 0 0x76 0x10")).toBe("i2c-bus-0");
|
||||
expect(extractDeviceId("i2cdump -y 1 0x50")).toBe("i2c-bus-1");
|
||||
});
|
||||
it("gpioget 提取 chip", () => {
|
||||
expect(extractDeviceId("gpioget gpiochip0 33")).toBe("gpiochip0");
|
||||
});
|
||||
it("无关命令返回 null", () => {
|
||||
expect(extractDeviceId("ls -la")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("safety-gate per-skill allowed-tools", () => {
|
||||
it("hw-flash skill 收敛到不含 write", () => {
|
||||
const tools = allowedToolsForSkill("hw-flash") ?? [];
|
||||
expect(tools).toContain("flash");
|
||||
expect(tools).not.toContain("write");
|
||||
});
|
||||
it("hw-debug skill 含 debugger/board_exec", () => {
|
||||
const tools = allowedToolsForSkill("hw-debug") ?? [];
|
||||
expect(tools).toContain("debugger");
|
||||
});
|
||||
it("未知 skill 返回 null(不收敛)", () => {
|
||||
expect(allowedToolsForSkill("nope")).toBeNull();
|
||||
});
|
||||
it("skill 名大小写不敏感", () => {
|
||||
expect(allowedToolsForSkill("HW-PROBE")).toEqual(SKILL_ALLOWED_TOOLS["hw-probe"]);
|
||||
});
|
||||
});
|
||||
328
tests/server-runtime.test.ts
Normal file
328
tests/server-runtime.test.ts
Normal file
@ -0,0 +1,328 @@
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import {
|
||||
AgentSessionRuntime,
|
||||
AuthError,
|
||||
SessionLockedError,
|
||||
SessionNotFoundError,
|
||||
SessionDisposedError,
|
||||
readAuthToken,
|
||||
makePlaceholderTurnFn,
|
||||
type AgentTurnFn,
|
||||
type SendMessageInput,
|
||||
} from "../src/extensions/server-runtime.js";
|
||||
|
||||
// ---- 工具:构造一个可控制完成的 turnFn(用于观察 streaming 中间态 + 响应 abort)----
|
||||
function makeControllableTurn() {
|
||||
let resolveTurn: (r: { text: string; stopReason?: string }) => void;
|
||||
const promise = new Promise<{ text: string; stopReason?: string }>((r) => {
|
||||
resolveTurn = r;
|
||||
});
|
||||
const turnFn: AgentTurnFn = vi.fn(
|
||||
async (
|
||||
_sessionId: string,
|
||||
_input: SendMessageInput,
|
||||
_onToken: (chunk: string) => void,
|
||||
signal: { aborted: boolean },
|
||||
) => {
|
||||
// 轮询 abort 信号 + 等待外部 resolve,模拟真实 agent loop 响应中断
|
||||
return await new Promise<{ text: string; stopReason?: string }>((resolve, reject) => {
|
||||
const interval = setInterval(() => {
|
||||
if (signal.aborted) {
|
||||
clearInterval(interval);
|
||||
reject(new Error("aborted"));
|
||||
}
|
||||
}, 5);
|
||||
promise.then((r) => {
|
||||
clearInterval(interval);
|
||||
resolve(r);
|
||||
});
|
||||
});
|
||||
},
|
||||
);
|
||||
return { turnFn, resolve: (r: { text: string; stopReason?: string }) => resolveTurn!(r) };
|
||||
}
|
||||
|
||||
// 默认 echo turnFn
|
||||
const echoTurn: AgentTurnFn = async (_id, input) => ({
|
||||
text: `echo: ${input.text}`,
|
||||
stopReason: "stop",
|
||||
});
|
||||
|
||||
describe("server-runtime AgentSessionRuntime — startSession + 鉴权", () => {
|
||||
it("startSession 返回 id 且初始 phase=idle/locked=false", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
const id = await rt.startSession({});
|
||||
expect(id).toMatch(/^sess-/);
|
||||
const snap = rt.getStatus(id);
|
||||
expect(snap).not.toBeNull();
|
||||
expect(snap!.phase).toBe("idle");
|
||||
// locked 真实化:idle 时 locked=false(治 #20 locked:true 恒真)
|
||||
expect(snap!.locked).toBe(false);
|
||||
expect(snap!.model).toBe("glm-5.2");
|
||||
});
|
||||
|
||||
it("required=true 时缺 token → AuthError(fail-closed)", async () => {
|
||||
const rt = new AgentSessionRuntime({
|
||||
turnFn: echoTurn,
|
||||
auth: { required: true, expectedToken: "${DROBOTICS_LLM_KEY}" },
|
||||
});
|
||||
await expect(rt.startSession({})).rejects.toBeInstanceOf(AuthError);
|
||||
});
|
||||
|
||||
it("required=true 时坏 token → AuthError", async () => {
|
||||
const rt = new AgentSessionRuntime({
|
||||
turnFn: echoTurn,
|
||||
auth: { required: true, expectedToken: "${DROBOTICS_LLM_KEY}" },
|
||||
});
|
||||
await expect(rt.startSession({ authToken: "wrong-token" })).rejects.toBeInstanceOf(AuthError);
|
||||
});
|
||||
|
||||
it("required=true 时正确 token 放行", async () => {
|
||||
const rt = new AgentSessionRuntime({
|
||||
turnFn: echoTurn,
|
||||
auth: { required: true, expectedToken: "${DROBOTICS_LLM_KEY}" },
|
||||
});
|
||||
const id = await rt.startSession({ authToken: "${DROBOTICS_LLM_KEY}" });
|
||||
expect(rt.getStatus(id)?.phase).toBe("idle");
|
||||
});
|
||||
|
||||
it("checkToken 直接调用:required=false 恒放行", () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
expect(rt.checkToken(undefined)).toBe(true);
|
||||
expect(rt.checkToken("anything")).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("server-runtime 状态机 idle → streaming → idle", () => {
|
||||
it("sendMessage 驱动 idle→streaming→idle,transcript 含 user+assistant", async () => {
|
||||
const { turnFn, resolve } = makeControllableTurn();
|
||||
const rt = new AgentSessionRuntime({ turnFn });
|
||||
const id = await rt.startSession({});
|
||||
// 发消息但先不 resolve,观察 streaming
|
||||
const p = rt.sendMessage(id, { text: "hello" });
|
||||
// 让微任务推进到 streaming
|
||||
await Promise.resolve();
|
||||
await Promise.resolve();
|
||||
const mid = rt.getStatus(id);
|
||||
expect(mid!.phase).toBe("streaming");
|
||||
expect(mid!.locked).toBe(true); // locked = phase !== idle
|
||||
expect(mid!.transcript.some((m) => m.role === "user" && m.content === "hello")).toBe(true);
|
||||
|
||||
resolve({ text: "hi there", stopReason: "stop" });
|
||||
const res = await p;
|
||||
expect(res.aborted).toBe(false);
|
||||
expect(res.text).toBe("hi there");
|
||||
|
||||
const after = rt.getStatus(id);
|
||||
expect(after!.phase).toBe("idle");
|
||||
expect(after!.locked).toBe(false);
|
||||
expect(after!.transcript.some((m) => m.role === "assistant" && m.content === "hi there")).toBe(true);
|
||||
});
|
||||
|
||||
it("locked 时 sendMessage 被拒绝(互斥,fail-closed)", async () => {
|
||||
const { turnFn, resolve } = makeControllableTurn();
|
||||
const rt = new AgentSessionRuntime({ turnFn });
|
||||
const id = await rt.startSession({});
|
||||
const p = rt.sendMessage(id, { text: "first" });
|
||||
await Promise.resolve();
|
||||
await Promise.resolve();
|
||||
// 此时 streaming(locked),再发一条应被拒
|
||||
await expect(rt.sendMessage(id, { text: "second" })).rejects.toBeInstanceOf(SessionLockedError);
|
||||
|
||||
resolve({ text: "ok" });
|
||||
await p;
|
||||
expect(rt.getStatus(id)?.phase).toBe("idle");
|
||||
});
|
||||
});
|
||||
|
||||
describe("server-runtime abort", () => {
|
||||
it("abort 中断 streaming,phase 回 idle,result.aborted=true", async () => {
|
||||
const { turnFn, resolve } = makeControllableTurn();
|
||||
const rt = new AgentSessionRuntime({ turnFn });
|
||||
const id = await rt.startSession({});
|
||||
const p = rt.sendMessage(id, { text: "long task" });
|
||||
await Promise.resolve();
|
||||
await Promise.resolve();
|
||||
expect(rt.getStatus(id)?.phase).toBe("streaming");
|
||||
|
||||
const aborted = await rt.abort(id);
|
||||
expect(aborted).toBe(true);
|
||||
// turnFn 会因 signal.aborted 抛错
|
||||
const res = await p;
|
||||
expect(res.aborted).toBe(true);
|
||||
expect(rt.getStatus(id)?.phase).toBe("idle");
|
||||
// 不 resolve 也不会泄漏;为防 unhandled rejection,消化掉
|
||||
resolve({ text: "should-not-matter" });
|
||||
});
|
||||
|
||||
it("abort 空闲会话返回 false", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
const id = await rt.startSession({});
|
||||
expect(await rt.abort(id)).toBe(false);
|
||||
});
|
||||
|
||||
it("abort 不存在的会话返回 false", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
expect(await rt.abort("nope")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("server-runtime fork + resume + shutdown", () => {
|
||||
it("fork 拷贝 transcript,新会话 phase=idle", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
const id = await rt.startSession({});
|
||||
await rt.sendMessage(id, { text: "hello" });
|
||||
const forkId = await rt.fork(id);
|
||||
expect(forkId).not.toBe(id);
|
||||
const snap = rt.getStatus(forkId)!;
|
||||
expect(snap.phase).toBe("idle");
|
||||
expect(snap.forkedFrom).toBe(id);
|
||||
// transcript 含源会话的 user+assistant
|
||||
expect(snap.transcript.some((m) => m.role === "user" && m.content === "hello")).toBe(true);
|
||||
expect(snap.transcript.some((m) => m.role === "assistant")).toBe(true);
|
||||
});
|
||||
|
||||
it("fork 不存在的会话 → SessionNotFoundError", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
await expect(rt.fork("nope")).rejects.toBeInstanceOf(SessionNotFoundError);
|
||||
});
|
||||
|
||||
it("fork 坏 token → AuthError", async () => {
|
||||
const rt = new AgentSessionRuntime({
|
||||
turnFn: echoTurn,
|
||||
auth: { required: true, expectedToken: "${DROBOTICS_LLM_KEY}" },
|
||||
});
|
||||
const id = await rt.startSession({ authToken: "${DROBOTICS_LLM_KEY}" });
|
||||
await expect(rt.fork(id, { authToken: "bad" })).rejects.toBeInstanceOf(AuthError);
|
||||
});
|
||||
|
||||
it("shutdown 置所有会话 disposed,sendMessage → SessionDisposedError", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
const id = await rt.startSession({});
|
||||
await rt.shutdown();
|
||||
const snap = rt.getStatus(id)!;
|
||||
expect(snap.disposed).toBe(true);
|
||||
await expect(rt.sendMessage(id, { text: "x" })).rejects.toBeInstanceOf(SessionDisposedError);
|
||||
});
|
||||
|
||||
it("resume 恢复 disposed 会话后可继续 sendMessage", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
const id = await rt.startSession({});
|
||||
await rt.shutdown();
|
||||
expect(rt.resume(id)).toBe(true);
|
||||
expect(rt.getStatus(id)?.disposed).toBe(false);
|
||||
const res = await rt.sendMessage(id, { text: "after resume" });
|
||||
expect(res.text).toBe("echo: after resume");
|
||||
});
|
||||
|
||||
it("resume 不存在会话返回 false", () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
expect(rt.resume("nope")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("server-runtime listSessions + getStatus 边界", () => {
|
||||
it("getStatus 不存在返回 null", () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
expect(rt.getStatus("nope")).toBeNull();
|
||||
});
|
||||
|
||||
it("listSessions 列出全部会话(含 disposed)", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
const a = await rt.startSession({});
|
||||
const b = await rt.startSession({});
|
||||
await rt.shutdown();
|
||||
const list = rt.listSessions();
|
||||
expect(list).toHaveLength(2);
|
||||
expect(list.map((s) => s.id).sort()).toEqual([a, b].sort());
|
||||
expect(list.every((s) => s.disposed)).toBe(true);
|
||||
});
|
||||
|
||||
it("sendMessage 不存在会话 → SessionNotFoundError", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
await expect(rt.sendMessage("nope", { text: "x" })).rejects.toBeInstanceOf(SessionNotFoundError);
|
||||
});
|
||||
|
||||
it("并发两 session 各自独立 prompt 互不干扰", async () => {
|
||||
// 每个会话独立的 echo turnFn,按 sessionId 区分输出
|
||||
const turnFn: AgentTurnFn = vi.fn(async (_id, input) => ({
|
||||
text: `resp:${input.text}`,
|
||||
stopReason: "stop",
|
||||
}));
|
||||
const rt = new AgentSessionRuntime({ turnFn });
|
||||
const a = await rt.startSession({});
|
||||
const b = await rt.startSession({});
|
||||
const [ra, rb] = await Promise.all([
|
||||
rt.sendMessage(a, { text: "from-a" }),
|
||||
rt.sendMessage(b, { text: "from-b" }),
|
||||
]);
|
||||
expect(ra.text).toBe("resp:from-a");
|
||||
expect(rb.text).toBe("resp:from-b");
|
||||
// 两者都回 idle
|
||||
expect(rt.getStatus(a)?.phase).toBe("idle");
|
||||
expect(rt.getStatus(b)?.phase).toBe("idle");
|
||||
// transcript 各自独立
|
||||
const sa = rt.getStatus(a)!;
|
||||
const sb = rt.getStatus(b)!;
|
||||
expect(sa.transcript.some((m) => m.content === "from-a")).toBe(true);
|
||||
expect(sa.transcript.some((m) => m.content === "from-b")).toBe(false);
|
||||
expect(sb.transcript.some((m) => m.content === "from-b")).toBe(true);
|
||||
expect(sb.transcript.some((m) => m.content === "from-a")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("server-runtime 密钥铁律 + 辅助函数", () => {
|
||||
it("expectedToken 用 ${DROBOTICS_LLM_KEY} 占位,绝不硬编码 sk- 开头", () => {
|
||||
const rt = new AgentSessionRuntime({
|
||||
turnFn: echoTurn,
|
||||
auth: { required: true, expectedToken: "${DROBOTICS_LLM_KEY}" },
|
||||
});
|
||||
const token = (rt as unknown as { auth: { expectedToken: string } }).auth.expectedToken;
|
||||
expect(token).toBe("${DROBOTICS_LLM_KEY}");
|
||||
expect(token).not.toMatch(/^sk-/);
|
||||
});
|
||||
|
||||
it("readAuthToken 未配 env 时鉴权关闭(开发模式)", () => {
|
||||
const saved = process.env.DROBOTICS_LLM_KEY;
|
||||
delete process.env.DROBOTICS_LLM_KEY;
|
||||
try {
|
||||
const cfg = readAuthToken();
|
||||
expect(cfg.required).toBe(false);
|
||||
} finally {
|
||||
if (saved) process.env.DROBOTICS_LLM_KEY = saved;
|
||||
}
|
||||
});
|
||||
|
||||
it("readAuthToken 配了 env 时 required=true + expectedToken=env 值(fail-closed)", () => {
|
||||
const saved = process.env.DROBOTICS_LLM_KEY;
|
||||
process.env.DROBOTICS_LLM_KEY = "test-key-placeholder";
|
||||
try {
|
||||
const cfg = readAuthToken();
|
||||
expect(cfg.required).toBe(true);
|
||||
expect(cfg.expectedToken).toBe("test-key-placeholder");
|
||||
expect(cfg.expectedToken).not.toMatch(/^sk-/);
|
||||
} finally {
|
||||
if (saved) process.env.DROBOTICS_LLM_KEY = saved;
|
||||
else delete process.env.DROBOTICS_LLM_KEY;
|
||||
}
|
||||
});
|
||||
|
||||
it("makePlaceholderTurnFn 透传 input.text + 轮询 signal.aborted", async () => {
|
||||
const fn = makePlaceholderTurnFn();
|
||||
const res = await fn("sess-x", { text: "ping" }, () => {}, { aborted: false });
|
||||
expect(res.text).toBe("[server-runtime placeholder] received: ping");
|
||||
expect(res.stopReason).toBe("stop");
|
||||
|
||||
// aborted signal → 抛错
|
||||
await expect(fn("sess-x", { text: "ping" }, () => {}, { aborted: true })).rejects.toThrow("aborted");
|
||||
});
|
||||
|
||||
it("clear 清空后会话列表为空", async () => {
|
||||
const rt = new AgentSessionRuntime({ turnFn: echoTurn });
|
||||
await rt.startSession({});
|
||||
expect(rt.listSessions()).toHaveLength(1);
|
||||
rt.clear();
|
||||
expect(rt.listSessions()).toHaveLength(0);
|
||||
expect(rt.getStatus("nope")).toBeNull();
|
||||
});
|
||||
});
|
||||
396
tests/subprocess-isolation.test.ts
Normal file
396
tests/subprocess-isolation.test.ts
Normal file
@ -0,0 +1,396 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
SubprocessIsolator,
|
||||
isCrashSignal,
|
||||
isCrashResult,
|
||||
crashToExecResult,
|
||||
isolateErrorExecResult,
|
||||
CRASH_SIGNALS,
|
||||
type ChildHandle,
|
||||
type SpawnFn,
|
||||
type KillFn,
|
||||
type KillSignal,
|
||||
} from "../src/extensions/subprocess-isolation.js";
|
||||
import type { ExecResult } from "../src/shared/types.js";
|
||||
|
||||
// ============================================================================
|
||||
// Mock runtime:spawn 返回可控 ChildHandle,kill 仅记录
|
||||
// ============================================================================
|
||||
|
||||
interface MockChild {
|
||||
handle: ChildHandle;
|
||||
resolve: (r: ExecResult) => void;
|
||||
reject: (e: Error) => void;
|
||||
}
|
||||
|
||||
function makeMockSpawn(): {
|
||||
spawn: SpawnFn;
|
||||
children: Map<number, MockChild>;
|
||||
spawned: MockChild[];
|
||||
} {
|
||||
const children = new Map<number, MockChild>();
|
||||
const spawned: MockChild[] = [];
|
||||
let pidCounter = 1000;
|
||||
const spawn: SpawnFn = (command, args, _opts) => {
|
||||
const startedAt = Date.now();
|
||||
let resolveFn!: (r: ExecResult) => void;
|
||||
let rejectFn!: (e: Error) => void;
|
||||
const result = new Promise<ExecResult>((res, rej) => {
|
||||
resolveFn = res;
|
||||
rejectFn = rej;
|
||||
});
|
||||
const handle: ChildHandle = { pid: pidCounter++, command, args, startedAt, result };
|
||||
const entry: MockChild = { handle, resolve: resolveFn, reject: rejectFn };
|
||||
children.set(handle.pid, entry);
|
||||
spawned.push(entry);
|
||||
return handle;
|
||||
};
|
||||
return { spawn, children, spawned };
|
||||
}
|
||||
|
||||
function makeMockKill(): { kill: KillFn; killed: Array<{ pid: number; signal?: KillSignal }> } {
|
||||
const killed: Array<{ pid: number; signal?: KillSignal }> = [];
|
||||
const kill: KillFn = (pid, signal) => {
|
||||
killed.push({ pid, signal });
|
||||
return true;
|
||||
};
|
||||
return { kill, killed };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// 纯函数:崩溃判定
|
||||
// ============================================================================
|
||||
|
||||
describe("subprocess-isolation isCrashSignal / isCrashResult", () => {
|
||||
it("SIGSEGV/SIGBUS/SIGABRT/SIGFPE/SIGILL 是 crash 信号", () => {
|
||||
expect(isCrashSignal("SIGSEGV")).toBe(true);
|
||||
expect(isCrashSignal("SIGBUS")).toBe(true);
|
||||
expect(isCrashSignal("SIGABRT")).toBe(true);
|
||||
expect(isCrashSignal("SIGFPE")).toBe(true);
|
||||
expect(isCrashSignal("SIGILL")).toBe(true);
|
||||
});
|
||||
|
||||
it("SIGTERM/SIGKILL 不是 crash 信号(是主动终止)", () => {
|
||||
expect(isCrashSignal("SIGTERM")).toBe(false);
|
||||
expect(isCrashSignal("SIGKILL")).toBe(false);
|
||||
expect(isCrashSignal("SIGINT")).toBe(false);
|
||||
});
|
||||
|
||||
it("undefined/null/空 不是 crash", () => {
|
||||
expect(isCrashSignal(undefined)).toBe(false);
|
||||
expect(isCrashSignal(null)).toBe(false);
|
||||
expect(isCrashSignal("")).toBe(false);
|
||||
});
|
||||
|
||||
it("CRASH_SIGNALS 至少 5 条", () => {
|
||||
expect(CRASH_SIGNALS.length).toBeGreaterThanOrEqual(5);
|
||||
});
|
||||
|
||||
it("isCrashResult 看 signal 字段判定", () => {
|
||||
expect(isCrashResult({ stdout: "", stderr: "", exitCode: -1, signal: "SIGSEGV" })).toBe(true);
|
||||
expect(isCrashResult({ stdout: "", stderr: "", exitCode: 1, signal: "SIGTERM" })).toBe(false);
|
||||
expect(isCrashResult({ stdout: "", stderr: "", exitCode: 0 })).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// crash 转换函数
|
||||
// ============================================================================
|
||||
|
||||
describe("subprocess-isolation crashToExecResult / isolateErrorExecResult", () => {
|
||||
it("crash 转成 exitCode:-1 + stderr 描述(不抛)", () => {
|
||||
const r = crashToExecResult(
|
||||
{ stdout: "", stderr: "ioctl: bad args", exitCode: -1, signal: "SIGSEGV" },
|
||||
4242,
|
||||
"i2cdetect -y 0",
|
||||
);
|
||||
expect(r.exitCode).toBe(-1);
|
||||
expect(r.signal).toBe("SIGSEGV");
|
||||
expect(r.stderr).toContain("[subprocess-isolation]");
|
||||
expect(r.stderr).toContain("pid 4242");
|
||||
expect(r.stderr).toContain("SIGSEGV");
|
||||
expect(r.stderr).toContain("Isolated");
|
||||
expect(r.stderr).toContain("i2cdetect -y 0");
|
||||
});
|
||||
|
||||
it("crash 结果保留原 stdout/stderr 前缀", () => {
|
||||
const r = crashToExecResult(
|
||||
{ stdout: "partial", stderr: "pre-crash log", exitCode: -1, signal: "SIGBUS" },
|
||||
99,
|
||||
"gpio mmap",
|
||||
);
|
||||
expect(r.stdout).toBe("partial");
|
||||
expect(r.stderr).toContain("pre-crash log");
|
||||
});
|
||||
|
||||
it("isolateErrorExecResult 统一 error 出口", () => {
|
||||
const r = isolateErrorExecResult("child pid 7 timed out after 50ms: sleep 100");
|
||||
expect(r.exitCode).toBe(-1);
|
||||
expect(r.stdout).toBe("");
|
||||
expect(r.stderr).toBe("[subprocess-isolation] child pid 7 timed out after 50ms: sleep 100");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// SubprocessIsolator:执行记 pid
|
||||
// ============================================================================
|
||||
|
||||
describe("subprocess-isolation SubprocessIsolator — 执行记 pid", () => {
|
||||
it("exec 执行期间 pid 进 tracking 表,结束后移除", async () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const iso = new SubprocessIsolator({ spawn });
|
||||
|
||||
const p = iso.exec("echo", ["hi"]);
|
||||
// exec 还在 pending(child 未 resolve)→ 应在 tracking 表里
|
||||
const pid = spawned[0].handle.pid;
|
||||
expect(iso.isTracking(pid)).toBe(true);
|
||||
expect(iso.getTrackedPids()).toContain(pid);
|
||||
|
||||
spawned[0].resolve({ stdout: "hi\n", stderr: "", exitCode: 0 });
|
||||
const r = await p;
|
||||
|
||||
expect(r.exitCode).toBe(0);
|
||||
expect(r.stdout).toBe("hi\n");
|
||||
// 完成后 pid 移出 tracking 表
|
||||
expect(iso.isTracking(pid)).toBe(false);
|
||||
expect(iso.getTrackedPids()).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("正常执行返回原 ExecResult(非零退出码也照透传)", async () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const iso = new SubprocessIsolator({ spawn });
|
||||
const p = iso.exec("gcc", ["-o", "app", "main.c"]);
|
||||
spawned[0].resolve({ stdout: "", stderr: "main.c:1: error: undeclared", exitCode: 1 });
|
||||
const r = await p;
|
||||
expect(r.exitCode).toBe(1);
|
||||
expect(r.stderr).toContain("undeclared");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// crash 隔离(核心:缺陷 #5 根治,fail-closed)
|
||||
// ============================================================================
|
||||
|
||||
describe("subprocess-isolation crash 隔离 — native 崩溃不传播给 agent", () => {
|
||||
it("child 以 SIGSEGV 信号退出 → 返回 exitCode:-1 不抛", async () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const iso = new SubprocessIsolator({ spawn });
|
||||
const p = iso.exec("i2cdetect", ["-y", "0"]);
|
||||
spawned[0].resolve({ stdout: "", stderr: "", exitCode: -1, signal: "SIGSEGV" });
|
||||
const r = await p;
|
||||
expect(r.exitCode).toBe(-1);
|
||||
expect(r.signal).toBe("SIGSEGV");
|
||||
expect(r.stderr).toContain("[subprocess-isolation]");
|
||||
expect(r.stderr).toContain("SIGSEGV");
|
||||
expect(r.stderr).toContain("Isolated");
|
||||
// 不抛:exec 正常返回(await 不抛)
|
||||
});
|
||||
|
||||
it("spawn 层 reject(native crash 带崩 promise 链)→ 返回 error 不抛", async () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const iso = new SubprocessIsolator({ spawn });
|
||||
const p = iso.exec("gpio", ["mmap"]);
|
||||
spawned[0].reject(new Error("native addon SIGSEGV: ioctl bad arg"));
|
||||
const r = await p;
|
||||
expect(r.exitCode).toBe(-1);
|
||||
expect(r.stderr).toContain("[subprocess-isolation]");
|
||||
expect(r.stderr).toContain("native addon SIGSEGV");
|
||||
expect(r.stderr).toContain("crashed");
|
||||
});
|
||||
|
||||
it("crash 记入 crashLog(审计轨迹)", async () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const iso = new SubprocessIsolator({ spawn });
|
||||
const p = iso.exec("i2cset", ["-y", "0", "0x76", "0x10"]);
|
||||
spawned[0].resolve({ stdout: "", stderr: "", exitCode: -1, signal: "SIGBUS" });
|
||||
await p;
|
||||
const log = iso.getCrashLog();
|
||||
expect(log).toHaveLength(1);
|
||||
expect(log[0]?.signal).toBe("SIGBUS");
|
||||
expect(log[0]?.command).toBe("i2cset");
|
||||
});
|
||||
|
||||
it("crash 后 isolator 不中毒:后续 exec 正常", async () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const iso = new SubprocessIsolator({ spawn });
|
||||
const p1 = iso.exec("crashy", []);
|
||||
spawned[0].reject(new Error("SIGSEGV"));
|
||||
await p1;
|
||||
// 第二次 exec 正常
|
||||
const p2 = iso.exec("echo", ["recover"]);
|
||||
spawned[1].resolve({ stdout: "recover\n", stderr: "", exitCode: 0 });
|
||||
const r2 = await p2;
|
||||
expect(r2.exitCode).toBe(0);
|
||||
expect(r2.stdout).toBe("recover\n");
|
||||
expect(iso.getCrashLog()).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("非 crash 信号(SIGTERM/SIGKILL)不转成 crash 描述", async () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const iso = new SubprocessIsolator({ spawn });
|
||||
const p = iso.exec("some-daemon", []);
|
||||
spawned[0].resolve({ stdout: "", stderr: "terminated", exitCode: -1, signal: "SIGTERM" });
|
||||
const r = await p;
|
||||
// 透传原结果,不裹 [subprocess-isolation] crash 描述
|
||||
expect(r.exitCode).toBe(-1);
|
||||
expect(r.stderr).toBe("terminated");
|
||||
expect(r.signal).toBe("SIGTERM");
|
||||
expect(iso.getCrashLog()).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// killStale(超时孤儿杀,fail-closed)
|
||||
// ============================================================================
|
||||
|
||||
describe("subprocess-isolation SubprocessIsolator — killStale", () => {
|
||||
it("杀掉运行超过 timeoutMs 的孤儿 child", () => {
|
||||
let t = 1000;
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const { kill, killed } = makeMockKill();
|
||||
const iso = new SubprocessIsolator({ spawn, kill, now: () => t });
|
||||
|
||||
// spawn 一个不 resolve 的 child(孤儿);startedAt 由 isolator 覆盖为 t=1000
|
||||
void iso.exec("sleep", ["100"]);
|
||||
const pid = spawned[0].handle.pid;
|
||||
expect(iso.isTracking(pid)).toBe(true);
|
||||
|
||||
// 时间前进 5s → 超过 3s 阈值
|
||||
t = 1000 + 5000;
|
||||
const killedPids = iso.killStale(3000);
|
||||
expect(killedPids).toContain(pid);
|
||||
expect(killed).toHaveLength(1);
|
||||
expect(killed[0]?.pid).toBe(pid);
|
||||
expect(killed[0]?.signal).toBe("SIGKILL");
|
||||
// 杀后移出 tracking 表
|
||||
expect(iso.isTracking(pid)).toBe(false);
|
||||
|
||||
// 解锁 exec promise(避免 dangling;用 SIGKILL 结果)
|
||||
spawned[0].resolve({ stdout: "", stderr: "", exitCode: -1, signal: "SIGKILL" });
|
||||
});
|
||||
|
||||
it("新鲜 child(未超时)不被杀", () => {
|
||||
let t = 1000;
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const { kill, killed } = makeMockKill();
|
||||
const iso = new SubprocessIsolator({ spawn, kill, now: () => t });
|
||||
|
||||
void iso.exec("sleep", ["100"]);
|
||||
const pid = spawned[0].handle.pid;
|
||||
t = 1000 + 1000; // 只过了 1s < 3s 阈值
|
||||
const killedPids = iso.killStale(3000);
|
||||
expect(killedPids).toHaveLength(0);
|
||||
expect(killed).toHaveLength(0);
|
||||
expect(iso.isTracking(pid)).toBe(true);
|
||||
|
||||
spawned[0].resolve({ stdout: "", stderr: "", exitCode: 0 });
|
||||
});
|
||||
|
||||
it("空 tracking 表 killStale 返回空数组", () => {
|
||||
const { spawn } = makeMockSpawn();
|
||||
const { kill, killed } = makeMockKill();
|
||||
const iso = new SubprocessIsolator({ spawn, kill });
|
||||
expect(iso.killStale(5000)).toEqual([]);
|
||||
expect(killed).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("killStale 记 crashLog(stale 审计)", () => {
|
||||
let t = 1000;
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const { kill } = makeMockKill();
|
||||
const iso = new SubprocessIsolator({ spawn, kill, now: () => t });
|
||||
void iso.exec("hang", []);
|
||||
t = 1000 + 10_000;
|
||||
iso.killStale(2000);
|
||||
spawned[0].resolve({ stdout: "", stderr: "", exitCode: 0 });
|
||||
const log = iso.getCrashLog();
|
||||
expect(log).toHaveLength(1);
|
||||
expect(log[0]?.signal).toBe("SIGKILL");
|
||||
expect(log[0]?.error).toContain("stale");
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// exec 超时(fail-closed:超时即杀)
|
||||
// ============================================================================
|
||||
|
||||
describe("subprocess-isolation SubprocessIsolator — exec 超时", () => {
|
||||
it("child 不退出 → 超时 kill 并返回 timeout 结果不抛", async () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const { kill, killed } = makeMockKill();
|
||||
const iso = new SubprocessIsolator({ spawn, kill });
|
||||
|
||||
const p = iso.exec("hang", [], { timeout: 20 });
|
||||
const r = await p;
|
||||
expect(r.exitCode).toBe(-1);
|
||||
expect(r.stderr).toContain("timed out");
|
||||
expect(r.stderr).toContain("20ms");
|
||||
// 超时触发了 SIGKILL
|
||||
expect(killed).toHaveLength(1);
|
||||
expect(killed[0]?.signal).toBe("SIGKILL");
|
||||
// 完成后 pid 移出 tracking
|
||||
expect(iso.getTrackedPids()).toHaveLength(0);
|
||||
|
||||
// 解锁 dangling child
|
||||
spawned[0].resolve({ stdout: "", stderr: "", exitCode: 0 });
|
||||
});
|
||||
|
||||
it("defaultTimeoutMs 作为默认超时", async () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const { kill } = makeMockKill();
|
||||
const iso = new SubprocessIsolator({ spawn, kill, defaultTimeoutMs: 15 });
|
||||
const r = await iso.exec("hang", []);
|
||||
expect(r.exitCode).toBe(-1);
|
||||
expect(r.stderr).toContain("timed out");
|
||||
spawned[0].resolve({ stdout: "", stderr: "", exitCode: 0 });
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// killAll
|
||||
// ============================================================================
|
||||
|
||||
describe("subprocess-isolation SubprocessIsolator — killAll", () => {
|
||||
it("杀掉所有 tracked children 并清空表", () => {
|
||||
const { spawn, spawned } = makeMockSpawn();
|
||||
const { kill, killed } = makeMockKill();
|
||||
const iso = new SubprocessIsolator({ spawn, kill });
|
||||
void iso.exec("a", []);
|
||||
void iso.exec("b", []);
|
||||
expect(iso.getTrackedPids()).toHaveLength(2);
|
||||
|
||||
const killedPids = iso.killAll("SIGTERM");
|
||||
expect(killedPids).toHaveLength(2);
|
||||
expect(killed).toHaveLength(2);
|
||||
expect(killed.every((k) => k.signal === "SIGTERM")).toBe(true);
|
||||
expect(iso.getTrackedPids()).toHaveLength(0);
|
||||
|
||||
spawned[0].resolve({ stdout: "", stderr: "", exitCode: 0 });
|
||||
spawned[1].resolve({ stdout: "", stderr: "", exitCode: 0 });
|
||||
});
|
||||
|
||||
it("killAll 空表返回空数组", () => {
|
||||
const { spawn } = makeMockSpawn();
|
||||
const { kill } = makeMockKill();
|
||||
const iso = new SubprocessIsolator({ spawn, kill });
|
||||
expect(iso.killAll()).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// ============================================================================
|
||||
// 构造默认值 / 配置
|
||||
// ============================================================================
|
||||
|
||||
describe("subprocess-isolation SubprocessIsolator — 配置", () => {
|
||||
it("maxRestarts 默认 3", () => {
|
||||
const { spawn } = makeMockSpawn();
|
||||
const iso = new SubprocessIsolator({ spawn });
|
||||
expect(iso.getMaxRestarts()).toBe(3);
|
||||
});
|
||||
|
||||
it("maxRestarts 可覆盖", () => {
|
||||
const { spawn } = makeMockSpawn();
|
||||
const iso = new SubprocessIsolator({ spawn, maxRestarts: 5 });
|
||||
expect(iso.getMaxRestarts()).toBe(5);
|
||||
});
|
||||
});
|
||||
25
tsconfig.json
Normal file
25
tsconfig.json
Normal file
@ -0,0 +1,25 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "bundler",
|
||||
"lib": ["ES2022"],
|
||||
"strict": true,
|
||||
"noEmit": true,
|
||||
"skipLibCheck": true,
|
||||
"esModuleInterop": true,
|
||||
"resolveJsonModule": true,
|
||||
"allowSyntheticDefaultImports": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"verbatimModuleSyntax": false,
|
||||
"allowImportingTsExtensions": true,
|
||||
"types": ["node"],
|
||||
"baseUrl": ".",
|
||||
"paths": {
|
||||
"@earendil-works/pi-ai": ["./src/types/pi.d.ts"],
|
||||
"@earendil-works/pi-coding-agent": ["./src/types/pi.d.ts"]
|
||||
}
|
||||
},
|
||||
"include": ["src/**/*.ts", "tests/**/*.ts", "bin/**/*.ts"],
|
||||
"exclude": ["node_modules", "Docs/**"]
|
||||
}
|
||||
26
vitest.config.ts
Normal file
26
vitest.config.ts
Normal file
@ -0,0 +1,26 @@
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { defineConfig } from "vitest/config";
|
||||
|
||||
// 运行时解析到真 pi 源码(.ts,无需构建 pi 即可跑逻辑测试)。
|
||||
// tsc 类型检查走 src/types/pi.d.ts 镜像(见 tsconfig.json paths)。
|
||||
const PI_PACKAGES = fileURLToPath(new URL("../pi/packages", import.meta.url));
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
globals: true,
|
||||
environment: "node",
|
||||
testTimeout: 15000,
|
||||
include: ["tests/**/*.test.ts"],
|
||||
reporters: ["default"],
|
||||
},
|
||||
resolve: {
|
||||
alias: [
|
||||
{ find: /^@earendil-works\/pi-ai$/, replacement: `${PI_PACKAGES}/ai/src/index.ts` },
|
||||
{ find: /^@earendil-works\/pi-coding-agent$/, replacement: `${PI_PACKAGES}/coding-agent/src/index.ts` },
|
||||
{ find: /^@earendil-works\/pi-agent-core$/, replacement: `${PI_PACKAGES}/agent/src/index.ts` },
|
||||
{ find: /^@earendil-works\/pi-protocol$/, replacement: `${PI_PACKAGES}/protocol/src/index.ts` },
|
||||
{ find: /^@earendil-works\/pi-client$/, replacement: `${PI_PACKAGES}/client/src/index.ts` },
|
||||
{ find: /^@mariozechner\/pi-ai$/, replacement: `${PI_PACKAGES}/ai/src/index.ts` },
|
||||
],
|
||||
},
|
||||
});
|
||||
Loading…
x
Reference in New Issue
Block a user