From 06a19a61e878d0532254641a913568d1e82d0f79 Mon Sep 17 00:00:00 2001 From: d-robotics Date: Thu, 13 Aug 2026 19:54:20 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E9=87=8D=E6=9E=84=E4=B8=BA?= =?UTF-8?q?=E7=94=9F=E4=BA=A7=E7=BA=A7=20pi=20Agent=20=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=EF=BC=88=E6=95=A3=E8=A3=85=E8=84=9A=E6=9C=AC=20=E2=86=92=20npm?= =?UTF-8?q?=20=E5=BA=93=E5=8C=85=20+=20=E5=8D=95=E4=B8=80=20barrel=20?= =?UTF-8?q?=E8=A3=85=E9=85=8D=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 工程形态:@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 --- .gitignore | 9 + .pi/extensions/index.ts | 10 + AGENTS.md | 59 + Docs/00_二开功能规划总览.md | 153 + Docs/F01_持久Shell与交互式会话工具.md | 70 + Docs/F02_增强读取PDF与提限分页.md | 53 + Docs/F03_edit精确匹配安全模式.md | 55 + Docs/F04_stopReason-length恢复策略.md | 52 + Docs/F05_硬件安全门破坏性命令拦截与资源锁.md | 76 + Docs/F06_扩展子进程隔离层.md | 77 + Docs/F07_嵌入式环境自动探针注入.md | 82 + Docs/F08_MCP桥接扩展.md | 90 + Docs/F09_PiServerService生产实现.md | 127 + Docs/F10_硬件状态Session-Entry持久化.md | 129 + Docs/F11_glm-5.2适配兜底层.md | 171 + Docs/F12_交叉编译工具链管理.md | 64 + Docs/F13_安全烧录工具.md | 63 + Docs/F14_外设探测工具集.md | 79 + Docs/F15_JTAG-gdb在线调试集成.md | 83 + Docs/F16_设备树工具.md | 66 + Docs/F17_宿主-目标板链路管理.md | 60 + Docs/F18_datasheet与手册RAG.md | 64 + Docs/F19_硬件行为验证判据.md | 69 + Docs/F20_硬件闭环迭代编排.md | 85 + Docs/F21_构建系统封装与长任务跟踪.md | 83 + README.md | 55 + bin/pba.ts | 40 + models.json | 28 + package-lock.json | 5016 ++++++++++++++++++ package.json | 31 + pi+glm5.2_嵌入式开发场景缺陷分析.md | 457 ++ src/agent.ts | 94 + src/extensions/board-link.ts | 714 +++ src/extensions/build-tracker.ts | 714 +++ src/extensions/cross-compile.ts | 856 +++ src/extensions/datasheet-rag.ts | 621 +++ src/extensions/device-tree.ts | 1065 ++++ src/extensions/edit-strict.ts | 413 ++ src/extensions/env-probe.ts | 551 ++ src/extensions/flash.ts | 929 ++++ src/extensions/glm-provider.ts | 410 ++ src/extensions/hardware-state.ts | 494 ++ src/extensions/hardware-verify.ts | 501 ++ src/extensions/index.ts | 86 + src/extensions/jtag-debugger.ts | 831 +++ src/extensions/length-recovery.ts | 526 ++ src/extensions/loop-orchestrator.ts | 520 ++ src/extensions/mcp-bridge.ts | 810 +++ src/extensions/pdf-reader.ts | 800 +++ src/extensions/peripheral-probe.ts | 594 +++ src/extensions/persistent-shell.ts | 548 ++ src/extensions/safety-gate.ts | 262 + src/extensions/server-runtime.ts | 701 +++ src/extensions/subprocess-isolation.ts | 492 ++ src/index.ts | 18 + src/shared/types.ts | 104 + src/types/pi.d.ts | 214 + tests/board-link.test.ts | 463 ++ tests/build-tracker.test.ts | 440 ++ tests/cross-compile.test.ts | 444 ++ tests/datasheet-rag.test.ts | 407 ++ tests/device-tree.test.ts | 335 ++ tests/edit-strict.test.ts | 251 + tests/env-probe.test.ts | 495 ++ tests/flash.test.ts | 488 ++ tests/glm-provider.test.ts | 162 + tests/hardware-state.test.ts | 281 + tests/hardware-verify.test.ts | 267 + tests/jtag-debugger.test.ts | 413 ++ tests/length-recovery.test.ts | 404 ++ tests/loop-orchestrator.test.ts | 314 ++ tests/mcp-bridge.test.ts | 301 ++ tests/pdf-reader.test.ts | 357 ++ tests/peripheral-probe.test.ts | 347 ++ tests/persistent-shell.test.ts | 317 ++ tests/safety-gate.test.ts | 129 + tests/server-runtime.test.ts | 328 ++ tests/subprocess-isolation.test.ts | 396 ++ tsconfig.json | 25 + vitest.config.ts | 26 + 80 files changed, 28814 insertions(+) create mode 100644 .gitignore create mode 100644 .pi/extensions/index.ts create mode 100644 AGENTS.md create mode 100644 Docs/00_二开功能规划总览.md create mode 100644 Docs/F01_持久Shell与交互式会话工具.md create mode 100644 Docs/F02_增强读取PDF与提限分页.md create mode 100644 Docs/F03_edit精确匹配安全模式.md create mode 100644 Docs/F04_stopReason-length恢复策略.md create mode 100644 Docs/F05_硬件安全门破坏性命令拦截与资源锁.md create mode 100644 Docs/F06_扩展子进程隔离层.md create mode 100644 Docs/F07_嵌入式环境自动探针注入.md create mode 100644 Docs/F08_MCP桥接扩展.md create mode 100644 Docs/F09_PiServerService生产实现.md create mode 100644 Docs/F10_硬件状态Session-Entry持久化.md create mode 100644 Docs/F11_glm-5.2适配兜底层.md create mode 100644 Docs/F12_交叉编译工具链管理.md create mode 100644 Docs/F13_安全烧录工具.md create mode 100644 Docs/F14_外设探测工具集.md create mode 100644 Docs/F15_JTAG-gdb在线调试集成.md create mode 100644 Docs/F16_设备树工具.md create mode 100644 Docs/F17_宿主-目标板链路管理.md create mode 100644 Docs/F18_datasheet与手册RAG.md create mode 100644 Docs/F19_硬件行为验证判据.md create mode 100644 Docs/F20_硬件闭环迭代编排.md create mode 100644 Docs/F21_构建系统封装与长任务跟踪.md create mode 100644 README.md create mode 100644 bin/pba.ts create mode 100644 models.json create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 pi+glm5.2_嵌入式开发场景缺陷分析.md create mode 100644 src/agent.ts create mode 100644 src/extensions/board-link.ts create mode 100644 src/extensions/build-tracker.ts create mode 100644 src/extensions/cross-compile.ts create mode 100644 src/extensions/datasheet-rag.ts create mode 100644 src/extensions/device-tree.ts create mode 100644 src/extensions/edit-strict.ts create mode 100644 src/extensions/env-probe.ts create mode 100644 src/extensions/flash.ts create mode 100644 src/extensions/glm-provider.ts create mode 100644 src/extensions/hardware-state.ts create mode 100644 src/extensions/hardware-verify.ts create mode 100644 src/extensions/index.ts create mode 100644 src/extensions/jtag-debugger.ts create mode 100644 src/extensions/length-recovery.ts create mode 100644 src/extensions/loop-orchestrator.ts create mode 100644 src/extensions/mcp-bridge.ts create mode 100644 src/extensions/pdf-reader.ts create mode 100644 src/extensions/peripheral-probe.ts create mode 100644 src/extensions/persistent-shell.ts create mode 100644 src/extensions/safety-gate.ts create mode 100644 src/extensions/server-runtime.ts create mode 100644 src/extensions/subprocess-isolation.ts create mode 100644 src/index.ts create mode 100644 src/shared/types.ts create mode 100644 src/types/pi.d.ts create mode 100644 tests/board-link.test.ts create mode 100644 tests/build-tracker.test.ts create mode 100644 tests/cross-compile.test.ts create mode 100644 tests/datasheet-rag.test.ts create mode 100644 tests/device-tree.test.ts create mode 100644 tests/edit-strict.test.ts create mode 100644 tests/env-probe.test.ts create mode 100644 tests/flash.test.ts create mode 100644 tests/glm-provider.test.ts create mode 100644 tests/hardware-state.test.ts create mode 100644 tests/hardware-verify.test.ts create mode 100644 tests/jtag-debugger.test.ts create mode 100644 tests/length-recovery.test.ts create mode 100644 tests/loop-orchestrator.test.ts create mode 100644 tests/mcp-bridge.test.ts create mode 100644 tests/pdf-reader.test.ts create mode 100644 tests/peripheral-probe.test.ts create mode 100644 tests/persistent-shell.test.ts create mode 100644 tests/safety-gate.test.ts create mode 100644 tests/server-runtime.test.ts create mode 100644 tests/subprocess-isolation.test.ts create mode 100644 tsconfig.json create mode 100644 vitest.config.ts diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1cc4fa1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +node_modules/ +dist/ +.artifacts/ +*.tsbuildinfo +.env +.env.* +.DS_Store +# 本地 pi 符号链接(如有) +pi diff --git a/.pi/extensions/index.ts b/.pi/extensions/index.ts new file mode 100644 index 0000000..561efb3 --- /dev/null +++ b/.pi/extensions/index.ts @@ -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"; diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0fee337 --- /dev/null +++ b/AGENTS.md @@ -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/.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 板上跑。 diff --git a/Docs/00_二开功能规划总览.md b/Docs/00_二开功能规划总览.md new file mode 100644 index 0000000..ab6cf78 --- /dev/null +++ b/Docs/00_二开功能规划总览.md @@ -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` diff --git a/Docs/F01_持久Shell与交互式会话工具.md b/Docs/F01_持久Shell与交互式会话工具.md new file mode 100644 index 0000000..0bda090 --- /dev/null +++ b/Docs/F01_持久Shell与交互式会话工具.md @@ -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 ""` 执行完即退出。 +- `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 ` + `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 人日**。 diff --git a/Docs/F02_增强读取PDF与提限分页.md b/Docs/F02_增强读取PDF与提限分页.md new file mode 100644 index 0000000..4130f3b --- /dev/null +++ b/Docs/F02_增强读取PDF与提限分页.md @@ -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 人日**。 diff --git a/Docs/F03_edit精确匹配安全模式.md b/Docs/F03_edit精确匹配安全模式.md new file mode 100644 index 0000000..eb6bf42 --- /dev/null +++ b/Docs/F03_edit精确匹配安全模式.md @@ -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 人日**。 diff --git a/Docs/F04_stopReason-length恢复策略.md b/Docs/F04_stopReason-length恢复策略.md new file mode 100644 index 0000000..53dd97a --- /dev/null +++ b/Docs/F04_stopReason-length恢复策略.md @@ -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 人日**。 diff --git a/Docs/F05_硬件安全门破坏性命令拦截与资源锁.md b/Docs/F05_硬件安全门破坏性命令拦截与资源锁.md new file mode 100644 index 0000000..003f5a9 --- /dev/null +++ b/Docs/F05_硬件安全门破坏性命令拦截与资源锁.md @@ -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 人日** diff --git a/Docs/F06_扩展子进程隔离层.md b/Docs/F06_扩展子进程隔离层.md new file mode 100644 index 0000000..e242868 --- /dev/null +++ b/Docs/F06_扩展子进程隔离层.md @@ -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`,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 { + // 现有字段不变 + isolated?: "process" | "worker"; // 新增 +} +// 2. 扩展级隔离声明 +export interface ExtensionIsolationConfig { mode: "process"; maxRestarts?: number; env?: Record; } +// 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 人日**。 diff --git a/Docs/F07_嵌入式环境自动探针注入.md b/Docs/F07_嵌入式环境自动探针注入.md new file mode 100644 index 0000000..420942b --- /dev/null +++ b/Docs/F07_嵌入式环境自动探针注入.md @@ -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`)→ ``(: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` 尾部): +``` + +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"} + +``` + +## 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)查看系统提示,`` 段落存在且含探针结果。 +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)都含 ``;探针缓存命中时第二轮不 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 人日**。 diff --git a/Docs/F08_MCP桥接扩展.md b/Docs/F08_MCP桥接扩展.md new file mode 100644 index 0000000..fe666fe --- /dev/null +++ b/Docs/F08_MCP桥接扩展.md @@ -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(tool: ToolDefinition): 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>`。`prepareArguments?`(:468) schema 校验前修补参数。`executionMode?`(:477)。 +- `registerTool` 实现(loader.ts:264-271):存入 `extension.tools: Map`(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(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; // stdio + url?: string; headers?: Record; // sse + enabled?: boolean; toolPrefix?: string; +} +// CLI flag(pi.registerFlag, types.ts:1272-1279): --mcp-config , --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 人日** diff --git a/Docs/F09_PiServerService生产实现.md b/Docs/F09_PiServerService生产实现.md new file mode 100644 index 0000000..189a1d2 --- /dev/null +++ b/Docs/F09_PiServerService生产实现.md @@ -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; + listModels(): Promise; + createSession(options: CreateSessionOptions): Promise; + openSession(sessionId: string): Promise; +} +// 新增 runtime.ts +export class AgentSessionRuntime implements PiSessionRuntime { + constructor(agentSession: AgentSession, sessionManager: SessionManager); + snapshot(): SessionSnapshot; getPhase(): SessionPhase; + prompt(input: PromptInput): Promise; steer(input: SteerInput): Promise; + abort(): Promise; setModel(model: ModelRef): Promise; + setThinking(level: ThinkingLevel): Promise; + subscribe(listener: (event: PiSessionRuntimeEvent) => void): () => void; + dispose(): Promise; +} +// 改 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 人日** | diff --git a/Docs/F10_硬件状态Session-Entry持久化.md b/Docs/F10_硬件状态Session-Entry持久化.md new file mode 100644 index 0000000..02592ac --- /dev/null +++ b/Docs/F10_硬件状态Session-Entry持久化.md @@ -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; + // 例:{ 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 人日** | diff --git a/Docs/F11_glm-5.2适配兜底层.md b/Docs/F11_glm-5.2适配兜底层.md new file mode 100644 index 0000000..baa3951 --- /dev/null +++ b/Docs/F11_glm-5.2适配兜底层.md @@ -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.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` +- `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 人日** | diff --git a/Docs/F12_交叉编译工具链管理.md b/Docs/F12_交叉编译工具链管理.md new file mode 100644 index 0000000..b969149 --- /dev/null +++ b/Docs/F12_交叉编译工具链管理.md @@ -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 人日**。 diff --git a/Docs/F13_安全烧录工具.md b/Docs/F13_安全烧录工具.md new file mode 100644 index 0000000..3c4297f --- /dev/null +++ b/Docs/F13_安全烧录工具.md @@ -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 人日**。 diff --git a/Docs/F14_外设探测工具集.md b/Docs/F14_外设探测工具集.md new file mode 100644 index 0000000..caad069 --- /dev/null +++ b/Docs/F14_外设探测工具集.md @@ -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 ` 扫描总线地址表 +- `i2c_get`/`i2c_set`:`i2cget -y ` / `i2cset -y ` +- `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 人日**。 diff --git a/Docs/F15_JTAG-gdb在线调试集成.md b/Docs/F15_JTAG-gdb在线调试集成.md new file mode 100644 index 0000000..28764f6 --- /dev/null +++ b/Docs/F15_JTAG-gdb在线调试集成.md @@ -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}>`)。工具 `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 人日**。 diff --git a/Docs/F16_设备树工具.md b/Docs/F16_设备树工具.md new file mode 100644 index 0000000..b0b246c --- /dev/null +++ b/Docs/F16_设备树工具.md @@ -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 .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 人日**。 diff --git a/Docs/F17_宿主-目标板链路管理.md b/Docs/F17_宿主-目标板链路管理.md new file mode 100644 index 0000000..f8d2aaf --- /dev/null +++ b/Docs/F17_宿主-目标板链路管理.md @@ -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 天)。 diff --git a/Docs/F18_datasheet与手册RAG.md b/Docs/F18_datasheet与手册RAG.md new file mode 100644 index 0000000..fed9fb2 --- /dev/null +++ b/Docs/F18_datasheet与手册RAG.md @@ -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 天)。 diff --git a/Docs/F19_硬件行为验证判据.md b/Docs/F19_硬件行为验证判据.md new file mode 100644 index 0000000..3d405b1 --- /dev/null +++ b/Docs/F19_硬件行为验证判据.md @@ -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}` + - `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 天)。 diff --git a/Docs/F20_硬件闭环迭代编排.md b/Docs/F20_硬件闭环迭代编排.md new file mode 100644 index 0000000..a39442a --- /dev/null +++ b/Docs/F20_硬件闭环迭代编排.md @@ -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 注入 `` 到 system prompt。AGENTS.md(resource-loader.ts:71, 134-153)注入 ``。`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)注入 `` 到 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 加载,注入 ``(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 天)。 diff --git a/Docs/F21_构建系统封装与长任务跟踪.md b/Docs/F21_构建系统封装与长任务跟踪.md new file mode 100644 index 0000000..f616dbd --- /dev/null +++ b/Docs/F21_构建系统封装与长任务跟踪.md @@ -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 天)。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..fdfe533 --- /dev/null +++ b/README.md @@ -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 板上端到端待跑。 diff --git a/bin/pba.ts b/bin/pba.ts new file mode 100644 index 0000000..4a785c5 --- /dev/null +++ b/bin/pba.ts @@ -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 && pi + */ + +import { PhysicalByteAgent } from "../src/index.js"; + +async function main(): Promise { + 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); +}); diff --git a/models.json b/models.json new file mode 100644 index 0000000..841d1f6 --- /dev/null +++ b/models.json @@ -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 + } + } + ] + } + ] +} diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..4fb4b61 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,5016 @@ +{ + "name": "@d-robotics/physical-byte-agent", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@d-robotics/physical-byte-agent", + "version": "0.1.0", + "dependencies": { + "@earendil-works/pi-ai": "*", + "@earendil-works/pi-coding-agent": "*" + }, + "bin": { + "pba": "bin/pba.ts" + }, + "devDependencies": { + "@types/node": "^22.0.0", + "tsx": "^4.19.0", + "typescript": "^5.6.0", + "vitest": "^2.1.9" + } + }, + "node_modules/@anthropic-ai/sdk": { + "version": "0.91.1", + "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.91.1.tgz", + "integrity": "sha512-LAmu761tSN9r66ixvmciswUj/ZC+1Q4iAfpedTfSVLeswRwnY3n2Nb6Tsk+cLPP28aLOPWeMgIuTuCcMC6W/iw==", + "license": "MIT", + "dependencies": { + "json-schema-to-ts": "^3.1.1" + }, + "bin": { + "anthropic-ai-sdk": "bin/cli" + }, + "peerDependencies": { + "zod": "^3.25.0 || ^4.0.0" + }, + "peerDependenciesMeta": { + "zod": { + "optional": true + } + } + }, + "node_modules/@aws-crypto/sha256-browser": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-browser/-/sha256-browser-5.2.0.tgz", + "integrity": "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-js": "^5.2.0", + "@aws-crypto/supports-web-crypto": "^5.2.0", + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "@aws-sdk/util-locate-window": "^3.0.0", + "@smithy/util-utf8": "^2.0.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/sha256-js": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-js/-/sha256-js-5.2.0.tgz", + "integrity": "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=16.0.0" + } + }, + "node_modules/@aws-crypto/supports-web-crypto": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/supports-web-crypto/-/supports-web-crypto-5.2.0.tgz", + "integrity": "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-crypto/util": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/util/-/util-5.2.0.tgz", + "integrity": "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.222.0", + "@smithy/util-utf8": "^2.0.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@aws-sdk/client-bedrock-runtime": { + "version": "3.1048.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-bedrock-runtime/-/client-bedrock-runtime-3.1048.0.tgz", + "integrity": "sha512-u+NT61JZEkRFtpL0CAw1N1dwxnaLgwVXQl/zjJxTGgLyS/jTIdg2SdoEoCTHxgDyCnqa1HEi9QOoE9/pYRNpOQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/credential-provider-node": "^3.972.42", + "@aws-sdk/eventstream-handler-node": "^3.972.16", + "@aws-sdk/middleware-eventstream": "^3.972.12", + "@aws-sdk/middleware-websocket": "^3.972.19", + "@aws-sdk/token-providers": "3.1048.0", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/fetch-http-handler": "^5.4.2", + "@smithy/node-http-handler": "^4.7.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/core": { + "version": "3.977.7", + "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.977.7.tgz", + "integrity": "sha512-I88Iov89NVmjSmJLKSv7Cn9M2J+a2942OkA8nZCbz+sl4ZeY4zEOcoLOrbt1GRfQ8zEQKnjAJdXixA3J/p1fDQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.974.3", + "@aws-sdk/xml-builder": "^3.972.38", + "@aws/lambda-invoke-store": "^0.3.0", + "@smithy/core": "^3.31.1", + "@smithy/signature-v4": "^5.6.12", + "@smithy/types": "^4.16.1", + "bowser": "^2.11.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-env": { + "version": "3.972.68", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.68.tgz", + "integrity": "sha512-2a20A/IdNOwUvaDq91iqqS7BA0XlNMfW3iLGZGZLJv0EbUqhSxB0PIx4rQQqssvWj1uXImb3/UCCdHz/+1dOiA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-http": { + "version": "3.972.70", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.70.tgz", + "integrity": "sha512-0yRem2Fs52r/Nn6UAqIlpjexfaYj8ziEozOe9tamtAVT/5bzFLKx8O2r7MaRqgS3hGKHIa1Jij9nKHSsNnb04A==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/fetch-http-handler": "^5.6.13", + "@smithy/node-http-handler": "^4.9.13", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-http/node_modules/@smithy/node-http-handler": { + "version": "4.10.0", + "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.10.0.tgz", + "integrity": "sha512-nrh7VxqzPQS/ip1hS293aI/OAWDWARQvjUxCfuKhyrfHa2gTdk28066RNeWLI1uuoHXaKAkOF8IcSAHuOp0+SA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.32.0", + "@smithy/types": "^4.17.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-ini": { + "version": "3.973.13", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.973.13.tgz", + "integrity": "sha512-2M39DE02XpYYaSWYk/4AsImXYUU/1L2xmTMLUpMMWq7DfLv191/vCRy3baKtdr45AkJQyVgSjmuVOLm15SwrRQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/credential-provider-env": "^3.972.68", + "@aws-sdk/credential-provider-http": "^3.972.70", + "@aws-sdk/credential-provider-login": "^3.972.75", + "@aws-sdk/credential-provider-process": "^3.972.68", + "@aws-sdk/credential-provider-sso": "^3.973.12", + "@aws-sdk/credential-provider-web-identity": "^3.972.74", + "@aws-sdk/nested-clients": "^3.997.42", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/credential-provider-imds": "^4.4.16", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-login": { + "version": "3.972.75", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.75.tgz", + "integrity": "sha512-jaTESuJlQsoUZ44f/i2puyPt8VlF/dMMJ9HM3cStYtk7eKX4N9UWi83OLixUkoOJH3BwWlPLCq9YIK9nfWhVBg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/nested-clients": "^3.997.42", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-node": { + "version": "3.972.79", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.79.tgz", + "integrity": "sha512-RIw5dof1EHkWubrZzPC941CDtnFG1iAXsxbFgLkhdYZXHc4icU13c/uxSMI0J5eUx9bxa7LjfpdjfClBB1QsDA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/credential-provider-env": "^3.972.68", + "@aws-sdk/credential-provider-http": "^3.972.70", + "@aws-sdk/credential-provider-ini": "^3.973.13", + "@aws-sdk/credential-provider-process": "^3.972.68", + "@aws-sdk/credential-provider-sso": "^3.973.12", + "@aws-sdk/credential-provider-web-identity": "^3.972.74", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/credential-provider-imds": "^4.4.16", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-process": { + "version": "3.972.68", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.68.tgz", + "integrity": "sha512-nLP3Pda2MQTFJ25hKBMmUuB9Uv+bTZQNlufbeCwklP549Vwnkd8bRLJoCKp5k6xjmdyptrPrOfGOhN0mKuca8A==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-sso": { + "version": "3.973.12", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.973.12.tgz", + "integrity": "sha512-EmgyyHn+f9WCcelp3L/vci+LGbX8GigWaVphRArjVo5Pktkr9YnLy/mQ6VDkDyBD72dtfRNTgHmD2ts4rTDXKQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/nested-clients": "^3.997.42", + "@aws-sdk/token-providers": "3.1108.0", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-sso/node_modules/@aws-sdk/token-providers": { + "version": "3.1108.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1108.0.tgz", + "integrity": "sha512-rI80zxDxGJ6904eC/YbjkdjY6JdaZvQ01kOmrMvw7cFQGIHo27fhnIVbMSVDS4T6foQImjxYSRoOu/uSJscXDw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/nested-clients": "^3.997.42", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/credential-provider-web-identity": { + "version": "3.972.74", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.74.tgz", + "integrity": "sha512-0YfczxGXF3RjGj8z7QG/Ho2HnLGKDHfPSHiTs47UU1U/+mmwISDN+rvGKt2zh+3FX8NdT4xd95LGBGyhQw2dgQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/nested-clients": "^3.997.42", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/eventstream-handler-node": { + "version": "3.972.32", + "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.32.tgz", + "integrity": "sha512-rlbmsMG7ZNgrVhWSqqXpq6y9hfiREyzCg3CNTk9UK+AoP7+65kOkqpWmqwLfV1UrRSHATdLnZF2rt9ZTUxYQJA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-eventstream": { + "version": "3.972.27", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.27.tgz", + "integrity": "sha512-M7Ay1VpBpf/YFfic9kkjwE3wyCh4G0gEM4RypRXYm7aPjyfqi+D8FEYMR2E3IqbvN+qi2rEFYAiwWL0XHtQYdQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/middleware-websocket": { + "version": "3.972.50", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.50.tgz", + "integrity": "sha512-gdcWRbmIf1dWA/prf44Bnnzgqj+AbsXX2yfhZhOQLwSm7NfKIYPmkRlPqP0CTepHzjxMIBdWBDdtQB+Y/dFUeg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/fetch-http-handler": "^5.6.13", + "@smithy/signature-v4": "^5.6.12", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@aws-sdk/nested-clients": { + "version": "3.997.42", + "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.997.42.tgz", + "integrity": "sha512-XWRyon2MTHXD/zMoo0Mbge6Vwf+iE0qQaM/RyGO6NfZ9WukCFiQL27nQVZjYy2JwSIg+iXZxKOX95OBXqlSM4w==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.977.7", + "@aws-sdk/signature-v4-multi-region": "^3.996.44", + "@aws-sdk/types": "^3.974.3", + "@smithy/core": "^3.31.1", + "@smithy/fetch-http-handler": "^5.6.13", + "@smithy/node-http-handler": "^4.9.13", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/nested-clients/node_modules/@smithy/node-http-handler": { + "version": "4.10.0", + "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.10.0.tgz", + "integrity": "sha512-nrh7VxqzPQS/ip1hS293aI/OAWDWARQvjUxCfuKhyrfHa2gTdk28066RNeWLI1uuoHXaKAkOF8IcSAHuOp0+SA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.32.0", + "@smithy/types": "^4.17.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@aws-sdk/signature-v4-multi-region": { + "version": "3.996.44", + "resolved": "https://registry.npmjs.org/@aws-sdk/signature-v4-multi-region/-/signature-v4-multi-region-3.996.44.tgz", + "integrity": "sha512-ZSfQ35Qn4MhSY+A0Whyr+KBx+wJKZUyBsOrjB2pSHOafRzbFe47T8XcXM8hZqUAC69qnqIy0C9ArxTuud0CC2w==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.974.3", + "@smithy/signature-v4": "^5.6.12", + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/token-providers": { + "version": "3.1048.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1048.0.tgz", + "integrity": "sha512-k0y/GcuesuSfWyUM0WamrGyeZmltRYaPbHO82UDA6mZ/doB+FOHKutikPAtSXMn/hDz970cF+iRuuiYO9VEbAA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/nested-clients": "^3.997.9", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/types": { + "version": "3.974.3", + "resolved": "https://registry.npmjs.org/@aws-sdk/types/-/types-3.974.3.tgz", + "integrity": "sha512-ECAqfpNsef+7MO8qtR0h9KcFIBAygaE7Cm6UOiQl+ft+uVap+1G7bNEjs4mdJE2OnA4m6k7i8peH8uGIAsOMGw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/util-locate-window": { + "version": "3.965.9", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-locate-window/-/util-locate-window-3.965.9.tgz", + "integrity": "sha512-wB/ho7pTJKqWz3WYDt2ZWDWI8bxQpN/xwf+5ZQ1zWaj+HDY9B8Fn434i6qZ6j6ZG3aCiIJtZaQVqwajx5xYsQA==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws-sdk/xml-builder": { + "version": "3.972.38", + "resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.38.tgz", + "integrity": "sha512-grf7mzfVxBS5AlsuTvBN7uDpzqohFww9fRPCO+EBSUdvtsYMcPSKdz54h/7XiscqNcUM1Ae1MF7JLHmiYYuzbQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.16.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@aws/lambda-invoke-store": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/@aws/lambda-invoke-store/-/lambda-invoke-store-0.3.0.tgz", + "integrity": "sha512-sl4Bm6yiMNYrZKkqqDFWN0UfnWhlS8ivKxrYl+6t0gCLrqr8y3B2IqZZbFRkfaVVp7C/baApyh71P+LeE1A2sQ==", + "license": "Apache-2.0", + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@babel/runtime": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.7.tgz", + "integrity": "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==", + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@earendil-works/pi-ai": { + "version": "0.84.1", + "resolved": "https://registry.npmjs.org/@earendil-works/pi-ai/-/pi-ai-0.84.1.tgz", + "integrity": "sha512-wMsAdJMxuNri08vLqTyYVI201DQQezGhPSTkzYsHdw5dYX3rCNwEmSvpaAwhi7ELKI/2tE/CEgSWg/6iRxSgdQ==", + "license": "MIT", + "dependencies": { + "@anthropic-ai/sdk": "0.91.1", + "@aws-sdk/client-bedrock-runtime": "3.1048.0", + "@earendil-works/pi-telemetry": "^0.84.1", + "@google/genai": "1.52.0", + "@mistralai/mistralai": "2.2.6", + "@opentelemetry/api": "1.9.0", + "@smithy/node-http-handler": "4.7.3", + "http-proxy-agent": "7.0.2", + "https-proxy-agent": "7.0.6", + "openai": "6.26.0", + "partial-json": "0.1.7", + "typebox": "1.3.7" + }, + "bin": { + "pi-ai": "dist/cli.js" + }, + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent": { + "version": "0.84.1", + "resolved": "https://registry.npmjs.org/@earendil-works/pi-coding-agent/-/pi-coding-agent-0.84.1.tgz", + "integrity": "sha512-ncAqFrG+iybuPGOhMiZoEHkEzTpJgz3guYD32pD+M7ucc0WeHmauP6wa7qwP8V/KWvsZDVNa5XGsdZ7fkC7w7A==", + "hasShrinkwrap": true, + "license": "MIT", + "dependencies": { + "@earendil-works/pi-agent-core": "^0.84.1", + "@earendil-works/pi-ai": "^0.84.1", + "@earendil-works/pi-client": "^0.84.1", + "@earendil-works/pi-protocol": "^0.84.1", + "@earendil-works/pi-tui": "^0.84.1", + "@silvia-odwyer/photon-node": "0.3.4", + "chalk": "5.6.2", + "cross-spawn": "7.0.6", + "diff": "8.0.4", + "glob": "13.0.6", + "grok-mermaid": "0.2.2", + "highlight.js": "10.7.3", + "hosted-git-info": "9.0.3", + "ignore": "7.0.5", + "jiti": "2.7.0", + "minimatch": "10.2.5", + "proper-lockfile": "4.1.2", + "semver": "7.8.0", + "typebox": "1.3.7", + "undici": "8.9.0", + "yaml": "2.9.0" + }, + "bin": { + "pi": "dist/cli.js" + }, + "engines": { + "node": ">=22.19.0" + }, + "optionalDependencies": { + "@mariozechner/clipboard": "0.3.9" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@anthropic-ai/sdk": { + "version": "0.91.1", + "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.91.1.tgz", + "integrity": "sha512-LAmu761tSN9r66ixvmciswUj/ZC+1Q4iAfpedTfSVLeswRwnY3n2Nb6Tsk+cLPP28aLOPWeMgIuTuCcMC6W/iw==", + "license": "MIT", + "dependencies": { + "json-schema-to-ts": "^3.1.1" + }, + "bin": { + "anthropic-ai-sdk": "bin/cli" + }, + "peerDependencies": { + "zod": "^3.25.0 || ^4.0.0" + }, + "peerDependenciesMeta": { + "zod": { + "optional": true + } + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/crc32": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/crc32/-/crc32-5.2.0.tgz", + "integrity": "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=16.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/sha256-browser": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-browser/-/sha256-browser-5.2.0.tgz", + "integrity": "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-js": "^5.2.0", + "@aws-crypto/supports-web-crypto": "^5.2.0", + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "@aws-sdk/util-locate-window": "^3.0.0", + "@smithy/util-utf8": "^2.0.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/sha256-js": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-js/-/sha256-js-5.2.0.tgz", + "integrity": "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/util": "^5.2.0", + "@aws-sdk/types": "^3.222.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=16.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/supports-web-crypto": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/supports-web-crypto/-/supports-web-crypto-5.2.0.tgz", + "integrity": "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/util": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@aws-crypto/util/-/util-5.2.0.tgz", + "integrity": "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.222.0", + "@smithy/util-utf8": "^2.0.0", + "tslib": "^2.6.2" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/client-bedrock-runtime": { + "version": "3.1048.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/client-bedrock-runtime/-/client-bedrock-runtime-3.1048.0.tgz", + "integrity": "sha512-u+NT61JZEkRFtpL0CAw1N1dwxnaLgwVXQl/zjJxTGgLyS/jTIdg2SdoEoCTHxgDyCnqa1HEi9QOoE9/pYRNpOQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/credential-provider-node": "^3.972.42", + "@aws-sdk/eventstream-handler-node": "^3.972.16", + "@aws-sdk/middleware-eventstream": "^3.972.12", + "@aws-sdk/middleware-websocket": "^3.972.19", + "@aws-sdk/token-providers": "3.1048.0", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/fetch-http-handler": "^5.4.2", + "@smithy/node-http-handler": "^4.7.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/core": { + "version": "3.974.11", + "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.974.11.tgz", + "integrity": "sha512-QpnINq5FZH6EOaDEkmHdT7eUunbvD27pDNQypaWjFyYz7Zl1q3UCMQErBZxpmfGfI7MvI2TlK8KTkgNpv8b1ug==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@aws-sdk/xml-builder": "^3.972.24", + "@aws/lambda-invoke-store": "^0.2.2", + "@smithy/core": "^3.24.2", + "@smithy/signature-v4": "^5.4.2", + "@smithy/types": "^4.14.1", + "bowser": "^2.11.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-env": { + "version": "3.972.37", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.37.tgz", + "integrity": "sha512-/jpPvEh6f7ntmIzf7dNxoNX6Q8vt8UpesCjbW6mFfk4V1NW6bIy9qxcQ6WbA8As5yQhsZOe+xeNd4xHX8kdY2Q==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-http": { + "version": "3.972.39", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.39.tgz", + "integrity": "sha512-pIgTpisWyWg7X1bUbzSjuUYosYTD0Ghz2M0hkSTmb3a6i3qV3uU+NYJPI/E2XSC0HcsZh5rsLPzeXrkb2DS0Cg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/fetch-http-handler": "^5.4.2", + "@smithy/node-http-handler": "^4.7.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-ini": { + "version": "3.972.41", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.972.41.tgz", + "integrity": "sha512-u2tyjaxJJzW8UtW4SM1ZcPMDwO6y+kV+llvou+Adts0FAKyzes5jG4izQN+KX3yE8ZROpS5y1LJ//xL2iSf76w==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/credential-provider-env": "^3.972.37", + "@aws-sdk/credential-provider-http": "^3.972.39", + "@aws-sdk/credential-provider-login": "^3.972.41", + "@aws-sdk/credential-provider-process": "^3.972.37", + "@aws-sdk/credential-provider-sso": "^3.972.41", + "@aws-sdk/credential-provider-web-identity": "^3.972.41", + "@aws-sdk/nested-clients": "^3.997.9", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/credential-provider-imds": "^4.3.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-login": { + "version": "3.972.41", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.41.tgz", + "integrity": "sha512-0LBitxXiAiaE5nlFPfpNIww/8FRY/I7WIndWsc9GmNFOM7cE1wNpVNQEGEk9Outg5l8xl+3vybxFyUy4l9q/LQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/nested-clients": "^3.997.9", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-node": { + "version": "3.972.42", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.42.tgz", + "integrity": "sha512-D4oon2zbqqsWOJUM99Gm3/ZyJ0IJvTXVN3PyloGb3kQEyI36fjCZheZj422lAgTWWd6TSHgiImLt3RIaLdv3dQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/credential-provider-env": "^3.972.37", + "@aws-sdk/credential-provider-http": "^3.972.39", + "@aws-sdk/credential-provider-ini": "^3.972.41", + "@aws-sdk/credential-provider-process": "^3.972.37", + "@aws-sdk/credential-provider-sso": "^3.972.41", + "@aws-sdk/credential-provider-web-identity": "^3.972.41", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/credential-provider-imds": "^4.3.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-process": { + "version": "3.972.37", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.37.tgz", + "integrity": "sha512-7nVaHBUaWIddASYfVaA9O4D5ZVjewU3sCol9WqZPGfW0nR+0WqE0xHZnD/U2L33PlOB8KNXGKZ6wOES/QijKzg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-sso": { + "version": "3.972.41", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.972.41.tgz", + "integrity": "sha512-IOWAWEHe5LkjSKkkUUX9ciV6Y1scHTsnfEkdt5yyC4Slrc7AGbkLPrpntjqh18ksJAMOaVhoBsO8p2WyTcY2wQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/nested-clients": "^3.997.9", + "@aws-sdk/token-providers": "3.1048.0", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-web-identity": { + "version": "3.972.41", + "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.41.tgz", + "integrity": "sha512-mbACk9Yypa8nm4iGZLs0PofOXEcTDOUw6wDnsPXNDNSd2WNXs1tSo+6nc/fh0jLYdfVZThhBL98PHW4aXFsG5A==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/nested-clients": "^3.997.9", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/eventstream-handler-node": { + "version": "3.972.16", + "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.16.tgz", + "integrity": "sha512-yedpPgKftqjU5SlPFHfqWpOw6xSCRieWRG1euWOlXn4WJxt2VX92VprCa2PpSOXjVCAeK6dTjW9eJRXVig9yGA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/middleware-eventstream": { + "version": "3.972.12", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.12.tgz", + "integrity": "sha512-tHTHHCHNrq6XklQvlzHBDJG4Iuhh7NVPRdtmvP+nHFA+5sxPlIDzlAHHgfoYHGvT3NXP1yVP/L5c3opUn6T3Qg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/middleware-websocket": { + "version": "3.972.19", + "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.19.tgz", + "integrity": "sha512-mkEhOGYozqKQkbFaVrjwr0faiwwZza1v5/jSY6Tucm3bD+uKTazIUH/4Yo6aMnQD2ua2W9cMP6s8mvwTcjtqHw==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/fetch-http-handler": "^5.4.2", + "@smithy/signature-v4": "^5.4.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/nested-clients": { + "version": "3.997.9", + "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.997.9.tgz", + "integrity": "sha512-jPR3rnmRI4hWYyzfmTGBr7NblMp8QYYeflHXba1H6+7CGrWVqWKQzaXFQ4qbExqPRsXN3T3L3JxFhr6aouXUGQ==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/sha256-browser": "5.2.0", + "@aws-crypto/sha256-js": "5.2.0", + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/signature-v4-multi-region": "^3.996.27", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/fetch-http-handler": "^5.4.2", + "@smithy/node-http-handler": "^4.7.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/signature-v4-multi-region": { + "version": "3.996.27", + "resolved": "https://registry.npmjs.org/@aws-sdk/signature-v4-multi-region/-/signature-v4-multi-region-3.996.27.tgz", + "integrity": "sha512-0Phbz4t6HI3D3skxvG2uI+VWU034/nSIw1T8d+FPzzQG9EQTrw94o9mOKO2Gv3n3Oc8P7JD7RAUxkoneLWv5Eg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/signature-v4": "^5.4.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/token-providers": { + "version": "3.1048.0", + "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1048.0.tgz", + "integrity": "sha512-k0y/GcuesuSfWyUM0WamrGyeZmltRYaPbHO82UDA6mZ/doB+FOHKutikPAtSXMn/hDz970cF+iRuuiYO9VEbAA==", + "license": "Apache-2.0", + "dependencies": { + "@aws-sdk/core": "^3.974.11", + "@aws-sdk/nested-clients": "^3.997.9", + "@aws-sdk/types": "^3.973.8", + "@smithy/core": "^3.24.2", + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/types": { + "version": "3.973.8", + "resolved": "https://registry.npmjs.org/@aws-sdk/types/-/types-3.973.8.tgz", + "integrity": "sha512-gjlAdtHMbtR9X5iIhVUvbVcy55KnznpC6bkDUWW9z915bi0ckdUr5cjf16Kp6xq0bP5HBD2xzgbL9F9Quv5vUw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.14.1", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/util-locate-window": { + "version": "3.965.5", + "resolved": "https://registry.npmjs.org/@aws-sdk/util-locate-window/-/util-locate-window-3.965.5.tgz", + "integrity": "sha512-WhlJNNINQB+9qtLtZJcpQdgZw3SCDCpXdUJP7cToGwHbCWCnRckGlc6Bx/OhWwIYFNAn+FIydY8SZ0QmVu3xTQ==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/xml-builder": { + "version": "3.972.24", + "resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.24.tgz", + "integrity": "sha512-V8z5YcDPfsvzrBlj0xR1vhRtocblhYbqdreCJB/voGd4Sr5zjNAeWxexbnqVtskTJe0vFb5KMqbSL++ePl+zRw==", + "license": "Apache-2.0", + "dependencies": { + "@nodable/entities": "2.1.0", + "@smithy/types": "^4.14.1", + "fast-xml-parser": "5.7.3", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws/lambda-invoke-store": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/@aws/lambda-invoke-store/-/lambda-invoke-store-0.2.4.tgz", + "integrity": "sha512-iY8yvjE0y651BixKNPgmv1WrQc+GZ142sb0z4gYnChDDY2YqI4P/jsSopBWrKfAt7LOJAkOXt7rC/hms+WclQQ==", + "license": "Apache-2.0", + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@babel/runtime": { + "version": "7.29.2", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.2.tgz", + "integrity": "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==", + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-agent-core": { + "version": "0.84.1", + "resolved": "https://registry.npmjs.org/@earendil-works/pi-agent-core/-/pi-agent-core-0.84.1.tgz", + "license": "MIT", + "dependencies": { + "@earendil-works/pi-ai": "^0.84.1", + "@earendil-works/pi-telemetry": "^0.84.1", + "diff": "8.0.4", + "ignore": "7.0.5", + "typebox": "1.3.7", + "yaml": "2.9.0" + }, + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai": { + "version": "0.84.1", + "resolved": "https://registry.npmjs.org/@earendil-works/pi-ai/-/pi-ai-0.84.1.tgz", + "license": "MIT", + "dependencies": { + "@anthropic-ai/sdk": "0.91.1", + "@aws-sdk/client-bedrock-runtime": "3.1048.0", + "@earendil-works/pi-telemetry": "^0.84.1", + "@google/genai": "1.52.0", + "@mistralai/mistralai": "2.2.6", + "@opentelemetry/api": "1.9.0", + "@smithy/node-http-handler": "4.7.3", + "http-proxy-agent": "7.0.2", + "https-proxy-agent": "7.0.6", + "openai": "6.26.0", + "partial-json": "0.1.7", + "typebox": "1.3.7" + }, + "bin": { + "pi-ai": "dist/cli.js" + }, + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-client": { + "version": "0.84.1", + "resolved": "https://registry.npmjs.org/@earendil-works/pi-client/-/pi-client-0.84.1.tgz", + "license": "MIT", + "dependencies": { + "@earendil-works/pi-protocol": "^0.84.1" + }, + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-protocol": { + "version": "0.84.1", + "resolved": "https://registry.npmjs.org/@earendil-works/pi-protocol/-/pi-protocol-0.84.1.tgz", + "license": "MIT", + "dependencies": { + "typebox": "1.3.7" + }, + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-telemetry": { + "version": "0.84.1", + "resolved": "https://registry.npmjs.org/@earendil-works/pi-telemetry/-/pi-telemetry-0.84.1.tgz", + "license": "MIT", + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui": { + "version": "0.84.1", + "resolved": "https://registry.npmjs.org/@earendil-works/pi-tui/-/pi-tui-0.84.1.tgz", + "license": "MIT", + "dependencies": { + "get-east-asian-width": "1.6.0", + "marked": "18.0.5" + }, + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@google/genai": { + "version": "1.52.0", + "resolved": "https://registry.npmjs.org/@google/genai/-/genai-1.52.0.tgz", + "integrity": "sha512-gwSvbpiN/17O9TbsqSsE/OzZcpv5Fo4RQjdngGgogtuB9RsyJ8ZHhX5KjHj1bp5N9snN2eK8LDGXSaWW2hof8Q==", + "hasInstallScript": true, + "license": "Apache-2.0", + "dependencies": { + "google-auth-library": "^10.3.0", + "p-retry": "^4.6.2", + "protobufjs": "^7.5.4", + "ws": "^8.18.0" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "@modelcontextprotocol/sdk": "^1.25.2" + }, + "peerDependenciesMeta": { + "@modelcontextprotocol/sdk": { + "optional": true + } + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard/-/clipboard-0.3.9.tgz", + "integrity": "sha512-ABnA53mdfkGZwOFUdZNv2S0CWGO/EIuPj8Vv9xmBFmSYg/qFc7ihO6q5FcQjvoE67kZpWkEc4AhD6B/os04yuA==", + "license": "MIT", + "optional": true, + "engines": { + "node": ">= 10" + }, + "optionalDependencies": { + "@mariozechner/clipboard-darwin-arm64": "0.3.9", + "@mariozechner/clipboard-darwin-universal": "0.3.9", + "@mariozechner/clipboard-darwin-x64": "0.3.9", + "@mariozechner/clipboard-linux-arm64-gnu": "0.3.9", + "@mariozechner/clipboard-linux-arm64-musl": "0.3.9", + "@mariozechner/clipboard-linux-riscv64-gnu": "0.3.9", + "@mariozechner/clipboard-linux-x64-gnu": "0.3.9", + "@mariozechner/clipboard-linux-x64-musl": "0.3.9", + "@mariozechner/clipboard-win32-arm64-msvc": "0.3.9", + "@mariozechner/clipboard-win32-x64-msvc": "0.3.9" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-darwin-arm64": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-arm64/-/clipboard-darwin-arm64-0.3.9.tgz", + "integrity": "sha512-BfgV7vCEWZwJwZJw03r6bP5+tf0iI/ANuQYCxi9RNn7FrWB3yzGuMKCrNLRl6V761vXRdL8+OqZ0wd4TqlsNOQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-darwin-universal": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-universal/-/clipboard-darwin-universal-0.3.9.tgz", + "integrity": "sha512-BGGR4iA9Z2shAjI65eI5xtyb3LYNlDW9X3gxKxDbqtbnREohsrqznov6zpKoIrsRWpzlYVEdKphS7ksJ0/ndSQ==", + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-darwin-x64": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-x64/-/clipboard-darwin-x64-0.3.9.tgz", + "integrity": "sha512-4kURmCbS6nt8uYhtmWpUcJWyPHfmAr5dTpXD1nO3pIfa+TSQ9DbrGOYCKH+aEFW47XhQ4Vp8ZTszie+wfFvDKg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-arm64-gnu": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-arm64-gnu/-/clipboard-linux-arm64-gnu-0.3.9.tgz", + "integrity": "sha512-g59OkUGP2DDfCOIKypHeYgv2M55u/cKvXa5dSxFbEJ34XvIQMdcVmpKCkGUro3ZgefXiGVdwguvTMQGpHWzIXw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-arm64-musl": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-arm64-musl/-/clipboard-linux-arm64-musl-0.3.9.tgz", + "integrity": "sha512-AGuJdgKsmJdm4Pych7kv3sqe591ERRaAHW3xjLooiFzn8J+PxUyof++7YZrB5Y5tpnTO+K18Og3taj2NpluCRQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-riscv64-gnu": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-riscv64-gnu/-/clipboard-linux-riscv64-gnu-0.3.9.tgz", + "integrity": "sha512-DXBEAiuMpk7dhS1a9NzNxVAFi1vaKoPu7rQNgY8LIDLGrK3lnIp3nT10DUum+PKVJoJppIP+NAA8IZe4DMNDPw==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-x64-gnu": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-x64-gnu/-/clipboard-linux-x64-gnu-0.3.9.tgz", + "integrity": "sha512-WORrMLd6EpElEME7JRKfSaY34nW1P5LbdgK5YNCS1ncG2LqmITsSMEJ8nh2mpvxb3TxqbOOKgY7k9eMJYlW9Mw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-x64-musl": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-x64-musl/-/clipboard-linux-x64-musl-0.3.9.tgz", + "integrity": "sha512-/DHn+1DrfL6oRaPPWXaOKvonFFrni666fxd+zFqiQEfvBH0tsHVWjq9iqBk0oDp0qaPA72lIMy5BptxISBEhZQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-win32-arm64-msvc": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-win32-arm64-msvc/-/clipboard-win32-arm64-msvc-0.3.9.tgz", + "integrity": "sha512-O5FHD3ErkMwMhNzAfu3ggy0ug4z7btZuoQgwwxlzPrwV2bxlD6WDpqBY4NCgICAgZdDKdp+loUEKVAVt8aYnhQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-win32-x64-msvc": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-win32-x64-msvc/-/clipboard-win32-x64-msvc-0.3.9.tgz", + "integrity": "sha512-ihQC3EufqEY81vhXBgVBtK4prL+wc62zJsSvxrgz7K1hsdt6OObz6v9p3Rn1OG3GJksTTKMJF0u/guMISHPhSA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@mistralai/mistralai": { + "version": "2.2.6", + "resolved": "https://registry.npmjs.org/@mistralai/mistralai/-/mistralai-2.2.6.tgz", + "integrity": "sha512-W8pX7zHxjJvMIpw8JMxeJEleapXX0Q9NPszdNzqkM3MIEoIGPObdodujj+WHteXEvGfaP/AMwlNyRfEzSY6dQQ==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/semantic-conventions": "^1.40.0", + "ws": "^8.18.0", + "zod": "^3.25.0 || ^4.0.0", + "zod-to-json-schema": "^3.25.0" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.9.0" + }, + "peerDependenciesMeta": { + "@opentelemetry/api": { + "optional": true + } + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@nodable/entities": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-2.1.0.tgz", + "integrity": "sha512-nyT7T3nbMyBI/lvr6L5TyWbFJAI9FTgVRakNoBqCD+PmID8DzFrrNdLLtHMwMszOtqZa8PAOV24ZqDnQrhQINA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/nodable" + } + ], + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@opentelemetry/api": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.0.tgz", + "integrity": "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==", + "license": "Apache-2.0", + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@opentelemetry/semantic-conventions": { + "version": "1.41.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.41.1.tgz", + "integrity": "sha512-/UhIkaZgPutTFmQ7RnIJGgDXZmtEJ7Dvi86xNTFWcnRxVRNk/aotsqDJYeEvDP+FSMB2SdW+pQzNMcWP0rwuNA==", + "license": "Apache-2.0", + "engines": { + "node": ">=14" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/aspromise": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz", + "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==", + "license": "BSD-3-Clause" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/base64": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz", + "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==", + "license": "BSD-3-Clause" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/codegen": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz", + "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==", + "license": "BSD-3-Clause" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/eventemitter": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz", + "integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==", + "license": "BSD-3-Clause" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/fetch": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz", + "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==", + "license": "BSD-3-Clause", + "dependencies": { + "@protobufjs/aspromise": "^1.1.1" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/float": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz", + "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==", + "license": "BSD-3-Clause" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/path": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz", + "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==", + "license": "BSD-3-Clause" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/pool": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz", + "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==", + "license": "BSD-3-Clause" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/utf8": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.1.tgz", + "integrity": "sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==", + "license": "BSD-3-Clause" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@silvia-odwyer/photon-node": { + "version": "0.3.4", + "resolved": "https://registry.npmjs.org/@silvia-odwyer/photon-node/-/photon-node-0.3.4.tgz", + "integrity": "sha512-bnly4BKB3KDTFxrUIcgCLbaeVVS8lrAkri1pEzskpmxu9MdfGQTy8b8EgcD83ywD3RPMsIulY8xJH5Awa+t9fA==", + "license": "Apache-2.0" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/core": { + "version": "3.24.3", + "resolved": "https://registry.npmjs.org/@smithy/core/-/core-3.24.3.tgz", + "integrity": "sha512-Ep/7tPamGY8mgESE3LyLKtxJyy6U52WWAqr/3wial47Sj4u3PiIF73AOGI27UyLy9duTkhZbgzodOfLV4TduZg==", + "license": "Apache-2.0", + "dependencies": { + "@aws-crypto/crc32": "5.2.0", + "@smithy/types": "^4.14.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/credential-provider-imds": { + "version": "4.3.3", + "resolved": "https://registry.npmjs.org/@smithy/credential-provider-imds/-/credential-provider-imds-4.3.3.tgz", + "integrity": "sha512-I2Bti0DKFo2IJyN28ijCsx51BAumEYR4/1yZ1FXyBygy9MqbnMqCev4JPth/MbpRfBSRAX35hITSnAdJRo1u5w==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.24.3", + "@smithy/types": "^4.14.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/fetch-http-handler": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@smithy/fetch-http-handler/-/fetch-http-handler-5.4.3.tgz", + "integrity": "sha512-F+DRf8IJazRJgYog2A/yJK7eYVc0rqTlRzO+5ZxjJd4WkZoKz0IJRncf7G6t1pdVT3kryJcwuTFhN1c5m6N47A==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.24.3", + "@smithy/types": "^4.14.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/is-array-buffer": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", + "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/node-http-handler": { + "version": "4.7.3", + "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.7.3.tgz", + "integrity": "sha512-/jPhevcTFPMVl6KNjbaI47iOg1zxC7IsnX4PQDGVZKMFceOXtB8IEYaB7a9VvkP/3oC60WzTeKocvSI7vLT0vA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.24.3", + "@smithy/types": "^4.14.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/signature-v4": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@smithy/signature-v4/-/signature-v4-5.4.3.tgz", + "integrity": "sha512-53+75QuPl6DL+ct6vVEB51FDO5oulXr20TPV46VvJZg76lIlXNWfxi8j+G2V/t0I2qxCBOa3vX/8bmjrpFVo9g==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.24.3", + "@smithy/types": "^4.14.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/types": { + "version": "4.14.2", + "resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.14.2.tgz", + "integrity": "sha512-P+otAxbV4CqBybp7EkcJCrig63yE2E7PuNVOmilVMRcx/O+QDzGULTrKsq4DV13gSfak9ObPrWaHl/9bL5YcWw==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/util-buffer-from": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", + "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/util-utf8": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", + "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/@types/node": { + "version": "22.19.19", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.19.tgz", + "integrity": "sha512-dyh/xO2Fh5bYrfWaaqGrRQQGkNdmYw6AmaAUvYeUMNTWQtvb796ikLdmTchRmOlOiIJ1TDXfWgVx1QkUlQ6Hew==", + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/agent-base": { + "version": "7.1.4", + "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz", + "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==", + "license": "MIT", + "engines": { + "node": ">= 14" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/balanced-match": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz", + "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==", + "license": "MIT", + "engines": { + "node": "18 || 20 || >=22" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/base64-js": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", + "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/bignumber.js": { + "version": "9.3.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.3.1.tgz", + "integrity": "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==", + "license": "MIT", + "engines": { + "node": "*" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/bowser": { + "version": "2.14.1", + "resolved": "https://registry.npmjs.org/bowser/-/bowser-2.14.1.tgz", + "integrity": "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==", + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/brace-expansion": { + "version": "5.0.9", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz", + "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==", + "license": "MIT", + "dependencies": { + "balanced-match": "^4.0.2" + }, + "engines": { + "node": "20 || >=22" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/buffer-equal-constant-time": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz", + "integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==", + "license": "BSD-3-Clause" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/chalk": { + "version": "5.6.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz", + "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==", + "license": "MIT", + "engines": { + "node": "^12.17.0 || ^14.13 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/data-uri-to-buffer": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz", + "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==", + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/diff": { + "version": "8.0.4", + "resolved": "https://registry.npmjs.org/diff/-/diff-8.0.4.tgz", + "integrity": "sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/ecdsa-sig-formatter": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/ecdsa-sig-formatter/-/ecdsa-sig-formatter-1.0.11.tgz", + "integrity": "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==", + "license": "Apache-2.0", + "dependencies": { + "safe-buffer": "^5.0.1" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/fast-xml-builder": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.2.0.tgz", + "integrity": "sha512-00aAWieqff+ZJhsXA4g1g7M8k+7AYoMUUHF+/zFb5U6Uv/P0Vl4QZo84/IcufzYalLuEj9928bXN9PbbFzMF0Q==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "dependencies": { + "path-expression-matcher": "^1.5.0", + "xml-naming": "^0.1.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/fast-xml-parser": { + "version": "5.7.3", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.7.3.tgz", + "integrity": "sha512-C0AaNuC+mscy6vrAQKAc/rMq+zAPHodfHGZu4sGVehvAQt/JLG1O5zEcYcXSY5zSqr4YVgxsB+pHXTq0i7eDlg==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "dependencies": { + "@nodable/entities": "^2.1.0", + "fast-xml-builder": "^1.1.7", + "path-expression-matcher": "^1.5.0", + "strnum": "^2.2.3" + }, + "bin": { + "fxparser": "src/cli/cli.js" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/fetch-blob": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz", + "integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/jimmywarting" + }, + { + "type": "paypal", + "url": "https://paypal.me/jimmywarting" + } + ], + "license": "MIT", + "dependencies": { + "node-domexception": "^1.0.0", + "web-streams-polyfill": "^3.0.3" + }, + "engines": { + "node": "^12.20 || >= 14.13" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/formdata-polyfill": { + "version": "4.0.10", + "resolved": "https://registry.npmjs.org/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz", + "integrity": "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==", + "license": "MIT", + "dependencies": { + "fetch-blob": "^3.1.2" + }, + "engines": { + "node": ">=12.20.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/gaxios": { + "version": "7.1.4", + "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.1.4.tgz", + "integrity": "sha512-bTIgTsM2bWn3XklZISBTQX7ZSddGW+IO3bMdGaemHZ3tbqExMENHLx6kKZ/KlejgrMtj8q7wBItt51yegqalrA==", + "license": "Apache-2.0", + "dependencies": { + "extend": "^3.0.2", + "https-proxy-agent": "^7.0.1", + "node-fetch": "^3.3.2" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/gcp-metadata": { + "version": "8.1.2", + "resolved": "https://registry.npmjs.org/gcp-metadata/-/gcp-metadata-8.1.2.tgz", + "integrity": "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==", + "license": "Apache-2.0", + "dependencies": { + "gaxios": "^7.0.0", + "google-logging-utils": "^1.0.0", + "json-bigint": "^1.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/get-east-asian-width": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.6.0.tgz", + "integrity": "sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/glob": { + "version": "13.0.6", + "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz", + "integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==", + "license": "BlueOak-1.0.0", + "dependencies": { + "minimatch": "^10.2.2", + "minipass": "^7.1.3", + "path-scurry": "^2.0.2" + }, + "engines": { + "node": "18 || 20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/google-auth-library": { + "version": "10.6.2", + "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-10.6.2.tgz", + "integrity": "sha512-e27Z6EThmVNNvtYASwQxose/G57rkRuaRbQyxM2bvYLLX/GqWZ5chWq2EBoUchJbCc57eC9ArzO5wMsEmWftCw==", + "license": "Apache-2.0", + "dependencies": { + "base64-js": "^1.3.0", + "ecdsa-sig-formatter": "^1.0.11", + "gaxios": "^7.1.4", + "gcp-metadata": "8.1.2", + "google-logging-utils": "1.1.3", + "jws": "^4.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/google-logging-utils": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-1.1.3.tgz", + "integrity": "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==", + "license": "Apache-2.0", + "engines": { + "node": ">=14" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", + "license": "ISC" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/grok-mermaid": { + "version": "0.2.2", + "resolved": "https://registry.npmjs.org/grok-mermaid/-/grok-mermaid-0.2.2.tgz", + "integrity": "sha512-XcJEP5dDC8liHBh52mlLjU18fNvu1ckFsu0QpIG3+APZ270fsj9wxpiA6cOURmbUEuoMVgjbC2+UYgTdCqqgzA==", + "license": "Apache-2.0", + "engines": { + "node": ">=18" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/highlight.js": { + "version": "10.7.3", + "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.7.3.tgz", + "integrity": "sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==", + "license": "BSD-3-Clause", + "engines": { + "node": "*" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/hosted-git-info": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-9.0.3.tgz", + "integrity": "sha512-Hc+ghLoSt6QaYZUv0WBiIvmMDZuZZ7oaDvdH8MbfOO4lOsxdXLEvuC6ePoGs9H1X9oCLyq6+NVN0MKqD+ydxyg==", + "license": "ISC", + "dependencies": { + "lru-cache": "^11.1.0" + }, + "engines": { + "node": "^20.17.0 || >=22.9.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/http-proxy-agent": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz", + "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==", + "license": "MIT", + "dependencies": { + "agent-base": "^7.1.0", + "debug": "^4.3.4" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/https-proxy-agent": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz", + "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==", + "license": "MIT", + "dependencies": { + "agent-base": "^7.1.2", + "debug": "4" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/ignore": { + "version": "7.0.5", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz", + "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==", + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "license": "ISC" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/jiti": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.7.0.tgz", + "integrity": "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==", + "license": "MIT", + "bin": { + "jiti": "lib/jiti-cli.mjs" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/json-bigint": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", + "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", + "license": "MIT", + "dependencies": { + "bignumber.js": "^9.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/json-schema-to-ts": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz", + "integrity": "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.18.3", + "ts-algebra": "^2.0.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/jwa": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/jwa/-/jwa-2.0.1.tgz", + "integrity": "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==", + "license": "MIT", + "dependencies": { + "buffer-equal-constant-time": "^1.0.1", + "ecdsa-sig-formatter": "1.0.11", + "safe-buffer": "^5.0.1" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/jws": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/jws/-/jws-4.0.1.tgz", + "integrity": "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==", + "license": "MIT", + "dependencies": { + "jwa": "^2.0.1", + "safe-buffer": "^5.0.1" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/long": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz", + "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==", + "license": "Apache-2.0" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/lru-cache": { + "version": "11.4.0", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.4.0.tgz", + "integrity": "sha512-W+R+kFL4HgVxONq2bhXPi3bGpzGe/yEhVOp233qw9wCRtgncJ15P3bC+e4zZMu4Cq7d+WAJjXGW0uUkifhcatA==", + "license": "BlueOak-1.0.0", + "engines": { + "node": "20 || >=22" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/marked": { + "version": "18.0.5", + "resolved": "https://registry.npmjs.org/marked/-/marked-18.0.5.tgz", + "integrity": "sha512-S6GcvALHg6K4ohtu4E7x0a1AqhAjp6cV8KhLSyN9qVapnzJkusVBxZRcIU9AeYsbe6P1hKDusSbEOzGyyuce6w==", + "license": "MIT", + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 20" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/minimatch": { + "version": "10.2.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz", + "integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==", + "license": "BlueOak-1.0.0", + "dependencies": { + "brace-expansion": "^5.0.5" + }, + "engines": { + "node": "18 || 20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/minipass": { + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz", + "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==", + "license": "BlueOak-1.0.0", + "engines": { + "node": ">=16 || 14 >=14.17" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/node-domexception": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz", + "integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==", + "deprecated": "Use your platform's native DOMException instead", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/jimmywarting" + }, + { + "type": "github", + "url": "https://paypal.me/jimmywarting" + } + ], + "license": "MIT", + "engines": { + "node": ">=10.5.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/node-fetch": { + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz", + "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==", + "license": "MIT", + "dependencies": { + "data-uri-to-buffer": "^4.0.0", + "fetch-blob": "^3.1.4", + "formdata-polyfill": "^4.0.10" + }, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/node-fetch" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/openai": { + "version": "6.26.0", + "resolved": "https://registry.npmjs.org/openai/-/openai-6.26.0.tgz", + "integrity": "sha512-zd23dbWTjiJ6sSAX6s0HrCZi41JwTA1bQVs0wLQPZ2/5o2gxOJA5wh7yOAUgwYybfhDXyhwlpeQf7Mlgx8EOCA==", + "license": "Apache-2.0", + "bin": { + "openai": "bin/cli" + }, + "peerDependencies": { + "ws": "^8.18.0", + "zod": "^3.25 || ^4.0" + }, + "peerDependenciesMeta": { + "ws": { + "optional": true + }, + "zod": { + "optional": true + } + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/p-retry": { + "version": "4.6.2", + "resolved": "https://registry.npmjs.org/p-retry/-/p-retry-4.6.2.tgz", + "integrity": "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==", + "license": "MIT", + "dependencies": { + "@types/retry": "0.12.0", + "retry": "^0.13.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/p-retry/node_modules/@types/retry": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.0.tgz", + "integrity": "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==", + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/partial-json": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/partial-json/-/partial-json-0.1.7.tgz", + "integrity": "sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==", + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/path-expression-matcher": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.5.0.tgz", + "integrity": "sha512-cbrerZV+6rvdQrrD+iGMcZFEiiSrbv9Tfdkvnusy6y0x0GKBXREFg/Y65GhIfm0tnLntThhzCnfKwp1WRjeCyQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/path-scurry": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz", + "integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==", + "license": "BlueOak-1.0.0", + "dependencies": { + "lru-cache": "^11.0.0", + "minipass": "^7.1.2" + }, + "engines": { + "node": "18 || 20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/proper-lockfile": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz", + "integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==", + "license": "MIT", + "dependencies": { + "graceful-fs": "^4.2.4", + "retry": "^0.12.0", + "signal-exit": "^3.0.2" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/proper-lockfile/node_modules/retry": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz", + "integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==", + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/protobufjs": { + "version": "7.6.5", + "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.6.5.tgz", + "integrity": "sha512-/FPD0nUc9jH6rfFjji9IBqOz4pcSE3CsT1m7Ep6Mdb0LxSUMj8hgl6GomOvZzpNpAqqGaXA0P3VSrZLFzIhQrw==", + "hasInstallScript": true, + "license": "BSD-3-Clause", + "dependencies": { + "@protobufjs/aspromise": "^1.1.2", + "@protobufjs/base64": "^1.1.2", + "@protobufjs/codegen": "^2.0.5", + "@protobufjs/eventemitter": "^1.1.1", + "@protobufjs/fetch": "^1.1.1", + "@protobufjs/float": "^1.0.2", + "@protobufjs/path": "^1.1.2", + "@protobufjs/pool": "^1.1.0", + "@protobufjs/utf8": "^1.1.1", + "@types/node": ">=13.7.0", + "long": "^5.3.2" + }, + "engines": { + "node": ">=12.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/retry": { + "version": "0.13.1", + "resolved": "https://registry.npmjs.org/retry/-/retry-0.13.1.tgz", + "integrity": "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==", + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/safe-buffer": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", + "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/semver": { + "version": "7.8.0", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz", + "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==", + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/signal-exit": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", + "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", + "license": "ISC" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/strnum": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.3.0.tgz", + "integrity": "sha512-ums3KNd42PGyx5xaoVTO1mjU1bH3NpY4vsrVlnv9PNGqQj8wd7rJ6nEypLrJ7z5vxK5RP0yMLo6J/Gsm62DI5Q==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/ts-algebra": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-2.0.0.tgz", + "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==", + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/tslib": { + "version": "2.8.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", + "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", + "license": "0BSD" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/typebox": { + "version": "1.3.7", + "resolved": "https://registry.npmjs.org/typebox/-/typebox-1.3.7.tgz", + "integrity": "sha512-meKuifc33Pccx0O6PdIzYMq3Og8zvP4TIi/a+Bw3AEMZMxOD0+RHGQvpglEe6Zdy3wZ8nqn/j95h8LUZLk/6Hg==", + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/undici": { + "version": "8.9.0", + "resolved": "https://registry.npmjs.org/undici/-/undici-8.9.0.tgz", + "integrity": "sha512-aWZpUj7XoGonMClx4gdDRfgBjqeA+F473aDmROQQbM9n6PRfK/u1q/a0X4wMTgcHfT8H6fpbt98PFuDUwFg2YA==", + "license": "MIT", + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "license": "MIT" + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/web-streams-polyfill": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz", + "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==", + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/ws": { + "version": "8.21.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz", + "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==", + "license": "MIT", + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/xml-naming": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/xml-naming/-/xml-naming-0.1.0.tgz", + "integrity": "sha512-k8KO9hrMyNk6tUWqUfkTEZbezRRpONVOzUTnc97VnCvyj6Tf9lyUR9EDAIeiVLv56jsMcoXEwjW8Kv5yPY52lw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "engines": { + "node": ">=16.0.0" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/yaml": { + "version": "2.9.0", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz", + "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==", + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + }, + "funding": { + "url": "https://github.com/sponsors/eemeli" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/zod": { + "version": "3.25.76", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", + "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/@earendil-works/pi-coding-agent/node_modules/zod-to-json-schema": { + "version": "3.25.2", + "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz", + "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==", + "license": "ISC", + "peerDependencies": { + "zod": "^3.25.28 || ^4" + } + }, + "node_modules/@earendil-works/pi-telemetry": { + "version": "0.84.1", + "resolved": "https://registry.npmjs.org/@earendil-works/pi-telemetry/-/pi-telemetry-0.84.1.tgz", + "integrity": "sha512-180/xGJtsq7IoR3p9EKWjRd0e9M4DkxInhlo9xyD7prDC7Qrhqq+nhvwrW0lFjPfXcEI2FSHmGCSyvSJE9GsaQ==", + "license": "MIT", + "engines": { + "node": ">=22.19.0" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz", + "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz", + "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz", + "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz", + "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz", + "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz", + "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz", + "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz", + "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz", + "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz", + "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz", + "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz", + "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz", + "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz", + "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz", + "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz", + "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz", + "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz", + "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz", + "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz", + "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz", + "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz", + "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz", + "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz", + "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz", + "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz", + "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@google/genai": { + "version": "1.52.0", + "resolved": "https://registry.npmjs.org/@google/genai/-/genai-1.52.0.tgz", + "integrity": "sha512-gwSvbpiN/17O9TbsqSsE/OzZcpv5Fo4RQjdngGgogtuB9RsyJ8ZHhX5KjHj1bp5N9snN2eK8LDGXSaWW2hof8Q==", + "hasInstallScript": true, + "license": "Apache-2.0", + "dependencies": { + "google-auth-library": "^10.3.0", + "p-retry": "^4.6.2", + "protobufjs": "^7.5.4", + "ws": "^8.18.0" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "@modelcontextprotocol/sdk": "^1.25.2" + }, + "peerDependenciesMeta": { + "@modelcontextprotocol/sdk": { + "optional": true + } + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.5.5", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz", + "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==", + "dev": true, + "license": "MIT" + }, + "node_modules/@mistralai/mistralai": { + "version": "2.2.6", + "resolved": "https://registry.npmjs.org/@mistralai/mistralai/-/mistralai-2.2.6.tgz", + "integrity": "sha512-W8pX7zHxjJvMIpw8JMxeJEleapXX0Q9NPszdNzqkM3MIEoIGPObdodujj+WHteXEvGfaP/AMwlNyRfEzSY6dQQ==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/semantic-conventions": "^1.40.0", + "ws": "^8.18.0", + "zod": "^3.25.0 || ^4.0.0", + "zod-to-json-schema": "^3.25.0" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.9.0" + }, + "peerDependenciesMeta": { + "@opentelemetry/api": { + "optional": true + } + } + }, + "node_modules/@napi-rs/lzma-linux-x64-gnu": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/@napi-rs/lzma-linux-x64-gnu/-/lzma-linux-x64-gnu-1.5.1.tgz", + "integrity": "sha512-oTXEIha4SsuXdTA4Iyskj0kpdx2yVXdhd75c2v3xGrHFfVMsbhTPZU/nMPL4sWKo4pBHm3aucLaqGlF696dTyQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^22.20 || ^24.12 || >=25" + } + }, + "node_modules/@opentelemetry/api": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.0.tgz", + "integrity": "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==", + "license": "Apache-2.0", + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/@opentelemetry/semantic-conventions": { + "version": "1.43.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.43.0.tgz", + "integrity": "sha512-eSYWTm620tTk45EKSedaUL8MFYI8hW164hIXsgIHyxu3VobUB3fFCu5t0hQby6OoWRPsG1KkKUG2M5UadiLiVg==", + "license": "Apache-2.0", + "engines": { + "node": ">=14" + } + }, + "node_modules/@protobufjs/aspromise": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz", + "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/base64": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz", + "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/codegen": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz", + "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/eventemitter": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz", + "integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/fetch": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz", + "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==", + "license": "BSD-3-Clause", + "dependencies": { + "@protobufjs/aspromise": "^1.1.1" + } + }, + "node_modules/@protobufjs/float": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz", + "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/path": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz", + "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/pool": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz", + "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/utf8": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.2.tgz", + "integrity": "sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==", + "license": "BSD-3-Clause" + }, + "node_modules/@rollup/rollup-android-arm-eabi": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.4.tgz", + "integrity": "sha512-RrPokAb7dmbxFoeO3TloqHyOjgye8RkBhSqmp4aJMIex4c9r46ZstPnleDQOq1t46VOVjwIuwNogIqbodV1Vvg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-android-arm64": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.62.4.tgz", + "integrity": "sha512-JKuJc+pnpks2pjy7L/N3v/cAkZxYlnmuZoD840ldbMI5KDbC4iO9NKwPKYdjYFCMAIIlBzYSFHxIJVYzRo2/8A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-darwin-arm64": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.62.4.tgz", + "integrity": "sha512-krw5uS2STmvJ02x0uTXHbqQNuz+9eZ1iw+qXk9dmW2gvV4jV7O2hEoOnuhFrpOPiel1mBFtqbxYZZtC46hXLOw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-darwin-x64": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.62.4.tgz", + "integrity": "sha512-wsTxtgApb4PrOsNJIm0FZ1h3WvCC+k9uxLJ4ad75hgoS4NiRes2SoJFlDAyMwiUY8IssDqGcHbXuN0sx1tfF1A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-freebsd-arm64": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.62.4.tgz", + "integrity": "sha512-GUOnQlyZe3yAXhWOtOMsn5Qkrv5E5mZXa0thbARWi5Ei2szlVXJFQhddZ4HbAzh8q92w5twp+CQvs/eFanz9YQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-freebsd-x64": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.62.4.tgz", + "integrity": "sha512-/Y7f3QuxjzPKsjA/rfEDa3+0vXqyjmJ50Ln8dPpCmWkKTrUoWHG1cWhTqaAMLob2m2nESWuC7yGrREz019Ztqg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-linux-arm-gnueabihf": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.62.4.tgz", + "integrity": "sha512-81wiiX3v7aqy+T+bT61TJ78yJjRquqFFTTbAPt08imfQQzkPIW8t6aJbkTagtCCrXMNc9D66+geqlK7ydLPNqA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm-musleabihf": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.62.4.tgz", + "integrity": "sha512-9kmDIvNZqdoHOBZgNtpTBeLWYO/LVipM3H/j62P8848/l/VPEQL6N3uxU9pvP1oZAsXyC2MEnFP3ovRjo7WYNQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-gnu": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.62.4.tgz", + "integrity": "sha512-CcnXHWnXg69g+DX5VWL3FHts3qMRN2uVEHX+BZvGLdd07/gXkn3ePjYtO1LDJvxkGKVHMclKBRa1QUTH+6toYQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-musl": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.62.4.tgz", + "integrity": "sha512-iFOibiHnTRuhrWLlRsOQFdZJJIa7S8OwkneJr4ocALP16u5yk6lWLINFwhHaEqBFMsKDUZofLkGos7+CPzGB3g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-loong64-gnu": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.62.4.tgz", + "integrity": "sha512-XnWYMI7euHlb5a871xPja+Gm7DRCFU+FGRrtS2sMq9N8FvqtpagUy6gD4YOemC5MRk9xbh8+jYMEJbigFQwsgA==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-loong64-musl": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.62.4.tgz", + "integrity": "sha512-qGDAlO0U8xedCcsdRm9oaoQY8DAx/QT7uIxJWhCdx0ceIWX783UC9QSYkdpzAe29wNiVfp24+bZdQmn49o45SQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-ppc64-gnu": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.62.4.tgz", + "integrity": "sha512-ru4H6ezD7ysA5EiEK6qkkaEb4modH8CTej6kUy/gQi20u3kB3G7Zn8snXXkeJSCOFKG/rbPPtM/+9Wgas1961w==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-ppc64-musl": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.62.4.tgz", + "integrity": "sha512-2W4MO5WQVJnbJaZdvDb9rhBDuFU1nKIepPFpJUBsTh2k1YY2g+ODViaWuyOAjQ5cOP7NvrvLzt3wvHOoiAvc7w==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-gnu": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.62.4.tgz", + "integrity": "sha512-+fxjfuoAmVMCYV5QyjoIpu0cp5DOiOTeqYFk1AVaxGr+/ravWLX89XfQmptsoWcaVy/TGf2hexzbUOrCQIL1CQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-musl": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.62.4.tgz", + "integrity": "sha512-jTn8JfHGL4djjFxPuM06LmNUJDsst2jeVlsd9OmIH6zc5sC9K6rIuO4YajXatLUpBmBKl6b35ro1QZocLi+tcA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-s390x-gnu": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.62.4.tgz", + "integrity": "sha512-oCJCJL4pXsoDcP2QZ+JVlPTIRc6266zsIaeJJsWImmF7HO0W8nb6HuSgZlMWxJwaPf8ehbSw8yo0EUw925hKsA==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-gnu": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.62.4.tgz", + "integrity": "sha512-W69hukhZ3KKNRCaMIEzKvcFye42hh0FE1+YoYaf5+Ikacuftoco6yO/xouz0hc5d5W/s3yBro5jRiuEE/Q5vUw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-musl": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.62.4.tgz", + "integrity": "sha512-qiXbGG2jkjXhzXpsFZSR2Xpb8DN/UaxYsbb/STbuR/6fpaDgRmmaq1B/LmtF2wQFOFOSsK2jdE0RZ3a0zHn4QA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-openbsd-x64": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.62.4.tgz", + "integrity": "sha512-nWeM//hxv8mIo6jD7Hu4o48DVmV9pbV6gsKaWU+4NFyqHoPKwrkRiZGLKUhOBk8qNmDmpwFtPKg80Bo/Tn4xiQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ] + }, + "node_modules/@rollup/rollup-openharmony-arm64": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.62.4.tgz", + "integrity": "sha512-s62SQ/vgsRSvMwDkOEfTqfgASF0f26ZNaQuTA6Aok5lrikf89yI2W0gFHvZb2Jpgc6N8JnOKZgCK2iciO3CsxQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ] + }, + "node_modules/@rollup/rollup-win32-arm64-msvc": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.62.4.tgz", + "integrity": "sha512-J6wGf8TVGbXJq+HH+ttTvrcfNKPbuZecV6KT1B8I18BC5IURUh5kl4Yl5OEP5eFIUoI5BWxCsyYMhFsDx8kekw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-ia32-msvc": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.62.4.tgz", + "integrity": "sha512-zmfrQd/0wu6oJs8Vq8KwY/YtsKSsLtKe/HwAP4Wqy8LhWjeT55fHRAkOhYQ12wI3ayS4Tt12d5CDRD7N96SAYQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-x64-gnu": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.62.4.tgz", + "integrity": "sha512-qPzHqdj9rfUD+w79dtE07zi/kFwKyCJqplp5K5ygeLTp7jLpAoc16OAH39HSmRC9UpozaecsleI8uAdEj6v2yw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-x64-msvc": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.62.4.tgz", + "integrity": "sha512-zD6NdeWEByGE9QF9vCrlJ5YQB4oq9q91kPZS37Jwj5hOkvR1lTBSpsKhKDw4IJtbQ35LsTS1HD9DZYGKIshU1Q==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@smithy/core": { + "version": "3.32.0", + "resolved": "https://registry.npmjs.org/@smithy/core/-/core-3.32.0.tgz", + "integrity": "sha512-NAiCSC78fzbNIEWoheoF74Ob5ZorLijCHpMY26Fqvqg/+9LuyIqMfHDg2p8Yk1rqOyowtiL3y7WX0AW+teL6zw==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/types": "^4.17.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/credential-provider-imds": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/@smithy/credential-provider-imds/-/credential-provider-imds-4.5.0.tgz", + "integrity": "sha512-2jsPi+7Zv2hSzD9IXR9D7DTqSn7mv4XalzRm+bESh53jiaUS3NKEUbpQFTJP0HhQy9qzZvluxQ3yS24zdRrqsA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.32.0", + "@smithy/types": "^4.17.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/fetch-http-handler": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@smithy/fetch-http-handler/-/fetch-http-handler-5.7.0.tgz", + "integrity": "sha512-W/exA8T0LEzCQtJ02w4IzaEQPIspgarqZprb7W8FwnYiDowgCrjl2fTQ6FvuSSUnJORuepBF81abmBJwqh+0XQ==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.32.0", + "@smithy/types": "^4.17.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/is-array-buffer": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", + "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@smithy/node-http-handler": { + "version": "4.7.3", + "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.7.3.tgz", + "integrity": "sha512-/jPhevcTFPMVl6KNjbaI47iOg1zxC7IsnX4PQDGVZKMFceOXtB8IEYaB7a9VvkP/3oC60WzTeKocvSI7vLT0vA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.24.3", + "@smithy/types": "^4.14.2", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/signature-v4": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@smithy/signature-v4/-/signature-v4-5.7.0.tgz", + "integrity": "sha512-hCynhm22wMJ8wTF9crcwu8mxggtUrSLLJgDcGUvYFBqpofxycYJCGKOMYg4xtPPFtgNiDJSYmhsWLTrcU/g59Q==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/core": "^3.32.0", + "@smithy/types": "^4.17.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/types": { + "version": "4.17.0", + "resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.17.0.tgz", + "integrity": "sha512-Aw4joiM0ZdErpo39lCj8phT2lxoiKZV+KZzBxnnQhWVtU2Is/WffQSL04uUWRcXUse9Ln8vXZK6V/FwqRVnQpg==", + "license": "Apache-2.0", + "dependencies": { + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/@smithy/util-buffer-from": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", + "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/is-array-buffer": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@smithy/util-utf8": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", + "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", + "license": "Apache-2.0", + "dependencies": { + "@smithy/util-buffer-from": "^2.2.0", + "tslib": "^2.6.2" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@types/estree": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz", + "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/node": { + "version": "22.20.1", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.1.tgz", + "integrity": "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q==", + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, + "node_modules/@types/retry": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.0.tgz", + "integrity": "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==", + "license": "MIT" + }, + "node_modules/@vitest/expect": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-2.1.9.tgz", + "integrity": "sha512-UJCIkTBenHeKT1TTlKMJWy1laZewsRIzYighyYiJKZreqtdxSos/S1t+ktRMQWu2CKqaarrkeszJx1cgC5tGZw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vitest/spy": "2.1.9", + "@vitest/utils": "2.1.9", + "chai": "^5.1.2", + "tinyrainbow": "^1.2.0" + }, + "funding": { + "url": "https://opencollective.com/vitest" + } + }, + "node_modules/@vitest/mocker": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-2.1.9.tgz", + "integrity": "sha512-tVL6uJgoUdi6icpxmdrn5YNo3g3Dxv+IHJBr0GXHaEdTcw3F+cPKnsXFhli6nO+f/6SDKPHEK1UN+k+TQv0Ehg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vitest/spy": "2.1.9", + "estree-walker": "^3.0.3", + "magic-string": "^0.30.12" + }, + "funding": { + "url": "https://opencollective.com/vitest" + }, + "peerDependencies": { + "msw": "^2.4.9", + "vite": "^5.0.0" + }, + "peerDependenciesMeta": { + "msw": { + "optional": true + }, + "vite": { + "optional": true + } + } + }, + "node_modules/@vitest/pretty-format": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-2.1.9.tgz", + "integrity": "sha512-KhRIdGV2U9HOUzxfiHmY8IFHTdqtOhIzCpd8WRdJiE7D/HUcZVD0EgQCVjm+Q9gkUXWgBvMmTtZgIG48wq7sOQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "tinyrainbow": "^1.2.0" + }, + "funding": { + "url": "https://opencollective.com/vitest" + } + }, + "node_modules/@vitest/runner": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-2.1.9.tgz", + "integrity": "sha512-ZXSSqTFIrzduD63btIfEyOmNcBmQvgOVsPNPe0jYtESiXkhd8u2erDLnMxmGrDCwHCCHE7hxwRDCT3pt0esT4g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vitest/utils": "2.1.9", + "pathe": "^1.1.2" + }, + "funding": { + "url": "https://opencollective.com/vitest" + } + }, + "node_modules/@vitest/snapshot": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-2.1.9.tgz", + "integrity": "sha512-oBO82rEjsxLNJincVhLhaxxZdEtV0EFHMK5Kmx5sJ6H9L183dHECjiefOAdnqpIgT5eZwT04PoggUnW88vOBNQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vitest/pretty-format": "2.1.9", + "magic-string": "^0.30.12", + "pathe": "^1.1.2" + }, + "funding": { + "url": "https://opencollective.com/vitest" + } + }, + "node_modules/@vitest/spy": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-2.1.9.tgz", + "integrity": "sha512-E1B35FwzXXTs9FHNK6bDszs7mtydNi5MIfUWpceJ8Xbfb1gBMscAnwLbEu+B44ed6W3XjL9/ehLPHR1fkf1KLQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "tinyspy": "^3.0.2" + }, + "funding": { + "url": "https://opencollective.com/vitest" + } + }, + "node_modules/@vitest/utils": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-2.1.9.tgz", + "integrity": "sha512-v0psaMSkNJ3A2NMrUEHFRzJtDPFn+/VWZ5WxImB21T9fjucJRmS7xCS3ppEnARb9y11OAzaD+P2Ps+b+BGX5iQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vitest/pretty-format": "2.1.9", + "loupe": "^3.1.2", + "tinyrainbow": "^1.2.0" + }, + "funding": { + "url": "https://opencollective.com/vitest" + } + }, + "node_modules/agent-base": { + "version": "7.1.4", + "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz", + "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==", + "license": "MIT", + "engines": { + "node": ">= 14" + } + }, + "node_modules/assertion-error": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz", + "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + } + }, + "node_modules/base64-js": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", + "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/bignumber.js": { + "version": "9.3.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.3.1.tgz", + "integrity": "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==", + "license": "MIT", + "engines": { + "node": "*" + } + }, + "node_modules/bowser": { + "version": "2.14.1", + "resolved": "https://registry.npmjs.org/bowser/-/bowser-2.14.1.tgz", + "integrity": "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==", + "license": "MIT" + }, + "node_modules/buffer-equal-constant-time": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz", + "integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==", + "license": "BSD-3-Clause" + }, + "node_modules/cac": { + "version": "6.7.14", + "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz", + "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/chai": { + "version": "5.3.3", + "resolved": "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz", + "integrity": "sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==", + "dev": true, + "license": "MIT", + "dependencies": { + "assertion-error": "^2.0.1", + "check-error": "^2.1.1", + "deep-eql": "^5.0.1", + "loupe": "^3.1.0", + "pathval": "^2.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/check-error": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/check-error/-/check-error-2.1.3.tgz", + "integrity": "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 16" + } + }, + "node_modules/data-uri-to-buffer": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz", + "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==", + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/deep-eql": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz", + "integrity": "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/ecdsa-sig-formatter": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/ecdsa-sig-formatter/-/ecdsa-sig-formatter-1.0.11.tgz", + "integrity": "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==", + "license": "Apache-2.0", + "dependencies": { + "safe-buffer": "^5.0.1" + } + }, + "node_modules/es-module-lexer": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz", + "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==", + "dev": true, + "license": "MIT" + }, + "node_modules/esbuild": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz", + "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=12" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.21.5", + "@esbuild/android-arm": "0.21.5", + "@esbuild/android-arm64": "0.21.5", + "@esbuild/android-x64": "0.21.5", + "@esbuild/darwin-arm64": "0.21.5", + "@esbuild/darwin-x64": "0.21.5", + "@esbuild/freebsd-arm64": "0.21.5", + "@esbuild/freebsd-x64": "0.21.5", + "@esbuild/linux-arm": "0.21.5", + "@esbuild/linux-arm64": "0.21.5", + "@esbuild/linux-ia32": "0.21.5", + "@esbuild/linux-loong64": "0.21.5", + "@esbuild/linux-mips64el": "0.21.5", + "@esbuild/linux-ppc64": "0.21.5", + "@esbuild/linux-riscv64": "0.21.5", + "@esbuild/linux-s390x": "0.21.5", + "@esbuild/linux-x64": "0.21.5", + "@esbuild/netbsd-x64": "0.21.5", + "@esbuild/openbsd-x64": "0.21.5", + "@esbuild/sunos-x64": "0.21.5", + "@esbuild/win32-arm64": "0.21.5", + "@esbuild/win32-ia32": "0.21.5", + "@esbuild/win32-x64": "0.21.5" + } + }, + "node_modules/estree-walker": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz", + "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0" + } + }, + "node_modules/expect-type": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz", + "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=12.0.0" + } + }, + "node_modules/extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "license": "MIT" + }, + "node_modules/fetch-blob": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz", + "integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/jimmywarting" + }, + { + "type": "paypal", + "url": "https://paypal.me/jimmywarting" + } + ], + "license": "MIT", + "dependencies": { + "node-domexception": "^1.0.0", + "web-streams-polyfill": "^3.0.3" + }, + "engines": { + "node": "^12.20 || >= 14.13" + } + }, + "node_modules/formdata-polyfill": { + "version": "4.0.10", + "resolved": "https://registry.npmjs.org/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz", + "integrity": "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==", + "license": "MIT", + "dependencies": { + "fetch-blob": "^3.1.2" + }, + "engines": { + "node": ">=12.20.0" + } + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/gaxios": { + "version": "7.3.1", + "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.3.1.tgz", + "integrity": "sha512-kB3rzJV7d9juLZh8/56QTXCwQfxyhdOMdyYk1HdQKFtF8TJTDTZQJtixWIwXdE9Jji91mC41DUNpjleo4L4eAQ==", + "license": "Apache-2.0", + "dependencies": { + "extend": "^3.0.2", + "https-proxy-agent": "^7.0.1", + "node-fetch": "^3.3.2" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/gcp-metadata": { + "version": "8.1.2", + "resolved": "https://registry.npmjs.org/gcp-metadata/-/gcp-metadata-8.1.2.tgz", + "integrity": "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==", + "license": "Apache-2.0", + "dependencies": { + "gaxios": "^7.0.0", + "google-logging-utils": "^1.0.0", + "json-bigint": "^1.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/google-auth-library": { + "version": "10.9.1", + "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-10.9.1.tgz", + "integrity": "sha512-i1ydyHrqcIxXkWh/uBmVkzCvIuq5yiK2ATndIe5XxKholrG/MTYP9xGYka4sQhrbIAgGjL2B6NOE7rFaiF3fXw==", + "license": "Apache-2.0", + "dependencies": { + "base64-js": "^1.3.0", + "ecdsa-sig-formatter": "^1.0.11", + "gaxios": "^7.1.4", + "gcp-metadata": "8.1.2", + "google-logging-utils": "1.1.3", + "jws": "^4.0.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/google-logging-utils": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-1.1.3.tgz", + "integrity": "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==", + "license": "Apache-2.0", + "engines": { + "node": ">=14" + } + }, + "node_modules/http-proxy-agent": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz", + "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==", + "license": "MIT", + "dependencies": { + "agent-base": "^7.1.0", + "debug": "^4.3.4" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/https-proxy-agent": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz", + "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==", + "license": "MIT", + "dependencies": { + "agent-base": "^7.1.2", + "debug": "4" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/json-bigint": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", + "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", + "license": "MIT", + "dependencies": { + "bignumber.js": "^9.0.0" + } + }, + "node_modules/json-schema-to-ts": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz", + "integrity": "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.18.3", + "ts-algebra": "^2.0.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/jwa": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/jwa/-/jwa-2.0.1.tgz", + "integrity": "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==", + "license": "MIT", + "dependencies": { + "buffer-equal-constant-time": "^1.0.1", + "ecdsa-sig-formatter": "1.0.11", + "safe-buffer": "^5.0.1" + } + }, + "node_modules/jws": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/jws/-/jws-4.0.1.tgz", + "integrity": "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==", + "license": "MIT", + "dependencies": { + "jwa": "^2.0.1", + "safe-buffer": "^5.0.1" + } + }, + "node_modules/long": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz", + "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==", + "license": "Apache-2.0" + }, + "node_modules/loupe": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz", + "integrity": "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/magic-string": { + "version": "0.30.21", + "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz", + "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/sourcemap-codec": "^1.5.5" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT" + }, + "node_modules/nanoid": { + "version": "3.3.18", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz", + "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "bin": { + "nanoid": "bin/nanoid.cjs" + }, + "engines": { + "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" + } + }, + "node_modules/node-domexception": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz", + "integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==", + "deprecated": "Use your platform's native DOMException instead", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/jimmywarting" + }, + { + "type": "github", + "url": "https://paypal.me/jimmywarting" + } + ], + "license": "MIT", + "engines": { + "node": ">=10.5.0" + } + }, + "node_modules/node-fetch": { + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz", + "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==", + "license": "MIT", + "dependencies": { + "data-uri-to-buffer": "^4.0.0", + "fetch-blob": "^3.1.4", + "formdata-polyfill": "^4.0.10" + }, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/node-fetch" + } + }, + "node_modules/openai": { + "version": "6.26.0", + "resolved": "https://registry.npmjs.org/openai/-/openai-6.26.0.tgz", + "integrity": "sha512-zd23dbWTjiJ6sSAX6s0HrCZi41JwTA1bQVs0wLQPZ2/5o2gxOJA5wh7yOAUgwYybfhDXyhwlpeQf7Mlgx8EOCA==", + "license": "Apache-2.0", + "bin": { + "openai": "bin/cli" + }, + "peerDependencies": { + "ws": "^8.18.0", + "zod": "^3.25 || ^4.0" + }, + "peerDependenciesMeta": { + "ws": { + "optional": true + }, + "zod": { + "optional": true + } + } + }, + "node_modules/p-retry": { + "version": "4.6.2", + "resolved": "https://registry.npmjs.org/p-retry/-/p-retry-4.6.2.tgz", + "integrity": "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==", + "license": "MIT", + "dependencies": { + "@types/retry": "0.12.0", + "retry": "^0.13.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/partial-json": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/partial-json/-/partial-json-0.1.7.tgz", + "integrity": "sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==", + "license": "MIT" + }, + "node_modules/pathe": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.2.tgz", + "integrity": "sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/pathval": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/pathval/-/pathval-2.0.1.tgz", + "integrity": "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 14.16" + } + }, + "node_modules/picocolors": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", + "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", + "dev": true, + "license": "ISC" + }, + "node_modules/postcss": { + "version": "8.5.26", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz", + "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "nanoid": "^3.3.17", + "picocolors": "^1.1.1", + "source-map-js": "^1.2.1" + }, + "engines": { + "node": "^10 || ^12 || >=14" + } + }, + "node_modules/protobufjs": { + "version": "7.6.5", + "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.6.5.tgz", + "integrity": "sha512-/FPD0nUc9jH6rfFjji9IBqOz4pcSE3CsT1m7Ep6Mdb0LxSUMj8hgl6GomOvZzpNpAqqGaXA0P3VSrZLFzIhQrw==", + "hasInstallScript": true, + "license": "BSD-3-Clause", + "dependencies": { + "@protobufjs/aspromise": "^1.1.2", + "@protobufjs/base64": "^1.1.2", + "@protobufjs/codegen": "^2.0.5", + "@protobufjs/eventemitter": "^1.1.1", + "@protobufjs/fetch": "^1.1.1", + "@protobufjs/float": "^1.0.2", + "@protobufjs/path": "^1.1.2", + "@protobufjs/pool": "^1.1.0", + "@protobufjs/utf8": "^1.1.1", + "@types/node": ">=13.7.0", + "long": "^5.3.2" + }, + "engines": { + "node": ">=12.0.0" + } + }, + "node_modules/retry": { + "version": "0.13.1", + "resolved": "https://registry.npmjs.org/retry/-/retry-0.13.1.tgz", + "integrity": "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==", + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/rollup": { + "version": "4.62.4", + "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.62.4.tgz", + "integrity": "sha512-RXOqwaPsBGjMNMa4sQjDjHieHEZDFoj/Rdr46l2MU5DfEs16wHJPC2RPTPHWhNl+M3aI472LLqFkFKut4SblOg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "1.0.9" + }, + "bin": { + "rollup": "dist/bin/rollup" + }, + "engines": { + "node": ">=18.0.0", + "npm": ">=8.0.0" + }, + "optionalDependencies": { + "@napi-rs/lzma-linux-x64-gnu": "1.5.1", + "@rollup/rollup-android-arm-eabi": "4.62.4", + "@rollup/rollup-android-arm64": "4.62.4", + "@rollup/rollup-darwin-arm64": "4.62.4", + "@rollup/rollup-darwin-x64": "4.62.4", + "@rollup/rollup-freebsd-arm64": "4.62.4", + "@rollup/rollup-freebsd-x64": "4.62.4", + "@rollup/rollup-linux-arm-gnueabihf": "4.62.4", + "@rollup/rollup-linux-arm-musleabihf": "4.62.4", + "@rollup/rollup-linux-arm64-gnu": "4.62.4", + "@rollup/rollup-linux-arm64-musl": "4.62.4", + "@rollup/rollup-linux-loong64-gnu": "4.62.4", + "@rollup/rollup-linux-loong64-musl": "4.62.4", + "@rollup/rollup-linux-ppc64-gnu": "4.62.4", + "@rollup/rollup-linux-ppc64-musl": "4.62.4", + "@rollup/rollup-linux-riscv64-gnu": "4.62.4", + "@rollup/rollup-linux-riscv64-musl": "4.62.4", + "@rollup/rollup-linux-s390x-gnu": "4.62.4", + "@rollup/rollup-linux-x64-gnu": "4.62.4", + "@rollup/rollup-linux-x64-musl": "4.62.4", + "@rollup/rollup-openbsd-x64": "4.62.4", + "@rollup/rollup-openharmony-arm64": "4.62.4", + "@rollup/rollup-win32-arm64-msvc": "4.62.4", + "@rollup/rollup-win32-ia32-msvc": "4.62.4", + "@rollup/rollup-win32-x64-gnu": "4.62.4", + "@rollup/rollup-win32-x64-msvc": "4.62.4", + "fsevents": "~2.3.2" + } + }, + "node_modules/safe-buffer": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", + "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/siginfo": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz", + "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==", + "dev": true, + "license": "ISC" + }, + "node_modules/source-map-js": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz", + "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/stackback": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz", + "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==", + "dev": true, + "license": "MIT" + }, + "node_modules/std-env": { + "version": "3.10.0", + "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz", + "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==", + "dev": true, + "license": "MIT" + }, + "node_modules/tinybench": { + "version": "2.9.0", + "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz", + "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==", + "dev": true, + "license": "MIT" + }, + "node_modules/tinyexec": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz", + "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==", + "dev": true, + "license": "MIT" + }, + "node_modules/tinypool": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-1.1.1.tgz", + "integrity": "sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^18.0.0 || >=20.0.0" + } + }, + "node_modules/tinyrainbow": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-1.2.0.tgz", + "integrity": "sha512-weEDEq7Z5eTHPDh4xjX789+fHfF+P8boiFB+0vbWzpbnbsEr/GRaohi/uMKxg8RZMXnl1ItAi/IUHWMsjDV7kQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/tinyspy": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-3.0.2.tgz", + "integrity": "sha512-n1cw8k1k0x4pgA2+9XrOkFydTerNcJ1zWCO5Nn9scWHTD+5tp8dghT2x1uduQePZTZgd3Tupf+x9BxJjeJi77Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/ts-algebra": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-2.0.0.tgz", + "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==", + "license": "MIT" + }, + "node_modules/tslib": { + "version": "2.8.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", + "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", + "license": "0BSD" + }, + "node_modules/tsx": { + "version": "4.23.12", + "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.12.tgz", + "integrity": "sha512-FDf4L4sYzKtzWYhU/Xm0AQFdTjdIxNo9ElTf2mxXM6k8YMHXzYUe4yODVaXP4V9uMFbVg8c0qyBccK2OOxb45Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "~0.28.0" + }, + "bin": { + "tsx": "dist/cli.mjs" + }, + "engines": { + "node": ">=18.0.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + } + }, + "node_modules/tsx/node_modules/@esbuild/aix-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz", + "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/android-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz", + "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/android-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz", + "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/android-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz", + "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/darwin-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz", + "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/darwin-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz", + "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz", + "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/freebsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz", + "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/linux-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz", + "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/linux-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz", + "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/linux-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz", + "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/linux-loong64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz", + "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/linux-mips64el": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz", + "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/linux-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz", + "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/linux-riscv64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz", + "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/linux-s390x": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz", + "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/linux-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz", + "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/netbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz", + "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/openbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz", + "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/sunos-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz", + "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/win32-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz", + "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/win32-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz", + "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/@esbuild/win32-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz", + "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/tsx/node_modules/esbuild": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz", + "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.2", + "@esbuild/android-arm": "0.28.2", + "@esbuild/android-arm64": "0.28.2", + "@esbuild/android-x64": "0.28.2", + "@esbuild/darwin-arm64": "0.28.2", + "@esbuild/darwin-x64": "0.28.2", + "@esbuild/freebsd-arm64": "0.28.2", + "@esbuild/freebsd-x64": "0.28.2", + "@esbuild/linux-arm": "0.28.2", + "@esbuild/linux-arm64": "0.28.2", + "@esbuild/linux-ia32": "0.28.2", + "@esbuild/linux-loong64": "0.28.2", + "@esbuild/linux-mips64el": "0.28.2", + "@esbuild/linux-ppc64": "0.28.2", + "@esbuild/linux-riscv64": "0.28.2", + "@esbuild/linux-s390x": "0.28.2", + "@esbuild/linux-x64": "0.28.2", + "@esbuild/netbsd-arm64": "0.28.2", + "@esbuild/netbsd-x64": "0.28.2", + "@esbuild/openbsd-arm64": "0.28.2", + "@esbuild/openbsd-x64": "0.28.2", + "@esbuild/openharmony-arm64": "0.28.2", + "@esbuild/sunos-x64": "0.28.2", + "@esbuild/win32-arm64": "0.28.2", + "@esbuild/win32-ia32": "0.28.2", + "@esbuild/win32-x64": "0.28.2" + } + }, + "node_modules/typebox": { + "version": "1.3.7", + "resolved": "https://registry.npmjs.org/typebox/-/typebox-1.3.7.tgz", + "integrity": "sha512-meKuifc33Pccx0O6PdIzYMq3Og8zvP4TIi/a+Bw3AEMZMxOD0+RHGQvpglEe6Zdy3wZ8nqn/j95h8LUZLk/6Hg==", + "license": "MIT" + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "license": "MIT" + }, + "node_modules/vite": { + "version": "5.4.21", + "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz", + "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "^0.21.3", + "postcss": "^8.4.43", + "rollup": "^4.20.0" + }, + "bin": { + "vite": "bin/vite.js" + }, + "engines": { + "node": "^18.0.0 || >=20.0.0" + }, + "funding": { + "url": "https://github.com/vitejs/vite?sponsor=1" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + }, + "peerDependencies": { + "@types/node": "^18.0.0 || >=20.0.0", + "less": "*", + "lightningcss": "^1.21.0", + "sass": "*", + "sass-embedded": "*", + "stylus": "*", + "sugarss": "*", + "terser": "^5.4.0" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + }, + "less": { + "optional": true + }, + "lightningcss": { + "optional": true + }, + "sass": { + "optional": true + }, + "sass-embedded": { + "optional": true + }, + "stylus": { + "optional": true + }, + "sugarss": { + "optional": true + }, + "terser": { + "optional": true + } + } + }, + "node_modules/vite-node": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/vite-node/-/vite-node-2.1.9.tgz", + "integrity": "sha512-AM9aQ/IPrW/6ENLQg3AGY4K1N2TGZdR5e4gu/MmmR2xR3Ll1+dib+nook92g4TV3PXVyeyxdWwtaCAiUL0hMxA==", + "dev": true, + "license": "MIT", + "dependencies": { + "cac": "^6.7.14", + "debug": "^4.3.7", + "es-module-lexer": "^1.5.4", + "pathe": "^1.1.2", + "vite": "^5.0.0" + }, + "bin": { + "vite-node": "vite-node.mjs" + }, + "engines": { + "node": "^18.0.0 || >=20.0.0" + }, + "funding": { + "url": "https://opencollective.com/vitest" + } + }, + "node_modules/vitest": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/vitest/-/vitest-2.1.9.tgz", + "integrity": "sha512-MSmPM9REYqDGBI8439mA4mWhV5sKmDlBKWIYbA3lRb2PTHACE0mgKwA8yQ2xq9vxDTuk4iPrECBAEW2aoFXY0Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vitest/expect": "2.1.9", + "@vitest/mocker": "2.1.9", + "@vitest/pretty-format": "^2.1.9", + "@vitest/runner": "2.1.9", + "@vitest/snapshot": "2.1.9", + "@vitest/spy": "2.1.9", + "@vitest/utils": "2.1.9", + "chai": "^5.1.2", + "debug": "^4.3.7", + "expect-type": "^1.1.0", + "magic-string": "^0.30.12", + "pathe": "^1.1.2", + "std-env": "^3.8.0", + "tinybench": "^2.9.0", + "tinyexec": "^0.3.1", + "tinypool": "^1.0.1", + "tinyrainbow": "^1.2.0", + "vite": "^5.0.0", + "vite-node": "2.1.9", + "why-is-node-running": "^2.3.0" + }, + "bin": { + "vitest": "vitest.mjs" + }, + "engines": { + "node": "^18.0.0 || >=20.0.0" + }, + "funding": { + "url": "https://opencollective.com/vitest" + }, + "peerDependencies": { + "@edge-runtime/vm": "*", + "@types/node": "^18.0.0 || >=20.0.0", + "@vitest/browser": "2.1.9", + "@vitest/ui": "2.1.9", + "happy-dom": "*", + "jsdom": "*" + }, + "peerDependenciesMeta": { + "@edge-runtime/vm": { + "optional": true + }, + "@types/node": { + "optional": true + }, + "@vitest/browser": { + "optional": true + }, + "@vitest/ui": { + "optional": true + }, + "happy-dom": { + "optional": true + }, + "jsdom": { + "optional": true + } + } + }, + "node_modules/web-streams-polyfill": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz", + "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==", + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/why-is-node-running": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz", + "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==", + "dev": true, + "license": "MIT", + "dependencies": { + "siginfo": "^2.0.0", + "stackback": "0.0.2" + }, + "bin": { + "why-is-node-running": "cli.js" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/ws": { + "version": "8.21.3", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz", + "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==", + "license": "MIT", + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/zod": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz", + "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/zod-to-json-schema": { + "version": "3.25.2", + "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz", + "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==", + "license": "ISC", + "peerDependencies": { + "zod": "^3.25.28 || ^4" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..47831ed --- /dev/null +++ b/package.json @@ -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" + } +} diff --git a/pi+glm5.2_嵌入式开发场景缺陷分析.md b/pi+glm5.2_嵌入式开发场景缺陷分析.md new file mode 100644 index 0000000..7129159 --- /dev/null +++ b/pi+glm5.2_嵌入式开发场景缺陷分析.md @@ -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)+ 保留 ``/`` 累积清单;`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 二开时再逐条给修复方案。 diff --git a/src/agent.ts b/src/agent.ts new file mode 100644 index 0000000..9d19bd8 --- /dev/null +++ b/src/agent.ts @@ -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 { + 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 = { + 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 }; + } +} diff --git a/src/extensions/board-link.ts b/src/extensions/board-link.ts new file mode 100644 index 0000000..4858cca --- /dev/null +++ b/src/extensions/board-link.ts @@ -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 { + 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(); + private fpIndex = new Map(); // 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 { + 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 `. " + + "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 })); + }); +} diff --git a/src/extensions/build-tracker.ts b/src/extensions/build-tracker.ts new file mode 100644 index 0000000..03aa6a4 --- /dev/null +++ b/src/extensions/build-tracker.ts @@ -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 }, +) => 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 ` + * - yocto: `bitbake ` + * - cmake: `cmake --build . --target ` + * - make: `make ` + * - kconfig: `make `(内核 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(); + 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。 + */ +export default async function buildTrackerExtension(pi: ExtensionAPI): Promise { + 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 }, + ): 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, + { 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, + { 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.", + }); + } + }); +} diff --git a/src/extensions/cross-compile.ts b/src/extensions/cross-compile.ts new file mode 100644 index 0000000..3ba7980 --- /dev/null +++ b/src/extensions/cross-compile.ts @@ -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 = { + "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 { + 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 `,校验产物架构。 + * fail-closed:file 命令失败 → match:false + error。 + * + * @param exec 注入的执行函数。 + * @param artifactPath 编译产物路径。 + * @param expectedArch 期望架构关键字。 + * @returns 架构校验结果。 + */ +export async function verifyArtifact( + exec: ExecFn, + artifactPath: string, + expectedArch: string, +): Promise { + 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 { + 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 { + 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 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 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 first.", + }, + ], + isError: true, + }; + } + if (!p.artifact) { + return { + content: [ + { + type: "text" as const, + text: "[xcompile] verify requires --artifact .", + }, + ], + 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(), + }); + }); +} diff --git a/src/extensions/datasheet-rag.ts b/src/extensions/datasheet-rag.ts new file mode 100644 index 0000000..2946f16 --- /dev/null +++ b/src/extensions/datasheet-rag.ts @@ -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>; + chunks: Map; + termFreq: Map>; + /** 参与索引的文档路径集合(docPath 过滤用)。 */ + docPaths: Set; + /** 索引内 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 -` 的 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 + * - termFreq[chunkId][term] = 出现次数(tf 排序用) + * - chunks[chunkId] = Chunk(正排) + * + * @param chunks 已分块的文档块数组。 + * @returns DatasheetIndex,search 直接消费。 + */ +export function buildIndex(chunks: Chunk[]): DatasheetIndex { + const inverted = new Map>(); + const chunkMap = new Map(); + const termFreq = new Map>(); + const docPaths = new Set(); + + for (const chunk of chunks) { + chunkMap.set(chunk.id, chunk); + if (chunk.filePath) docPaths.add(chunk.filePath); + + const freq = new Map(); + 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(); + 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(); + 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(); + 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 { + 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 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 ", + async handler(args, ctx) { + const pdfPath = args.trim(); + if (!pdfPath) { + ctx.ui.notify("[datasheet-rag] Usage: /dsrag-index ", "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 }); + }, + }); +} diff --git a/src/extensions/device-tree.ts b/src/extensions/device-tree.ts new file mode 100644 index 0000000..869763d --- /dev/null +++ b/src/extensions/device-tree.ts @@ -0,0 +1,1065 @@ +/** + * @module device-tree + * + * 设备树结构化解析与校验扩展 —— 治嵌入式开发场景下 pi 在 .dts/.dtsi 上的两处缺陷: + * + * - 缺陷 #2(read 截断 + 无结构化):pi 的 read 工具读 .dts 是纯文本 grep, + * 无法理解节点树/phandle 引用图。本扩展提供结构化解析(parseDts)、路径查找 + * (findNode)、overlay 合法性校验(validateOverlay)、compatible 拼写校验 + * (checkCompatible)、phandle 引用图检测(checkPhandle)。 + * - 缺陷 #9(edit fuzzy 误匹配 .dts):edit 工具的 fuzzy 匹配在 .dts 上会误匹配 + * (同名节点多份、compatible 串重复)。agent 先 `dt parse` 定位节点 label/路径 + * 再精确 edit,绕过 fuzzy 陷阱。 + * + * 场景锚定:ARM/嵌入式 Linux 硬件描述用 Device Tree——DTS/DTSI 源文件描述节点 + * (`&i2c0 { sensor@68 { compatible = "vendor,xyz"; reg = <0x68>; interrupt-parent = <&gpio4>; }; };`), + * `compatible` 字符串驱动匹配,`phandle` 节点引用,`reg` 指定地址,`interrupts` 指定中断。 + * `dtc`(Device Tree Compiler)把源编译成 `.dtb` 给内核。改错节点(compatible 拼写错、 + * phandle 断链、reg 地址错、interrupt 线号错)= 外设直接不枚举,dmesg 无报错静默失败。 + * + * 见 Docs/F16_设备树工具.md。逻辑内联为命名导出,tests 直接单测,无需 pi 运行时—— + * pi 未构建(模型目录需联网)时 factory 不跑,无副作用。 + */ + +import type { + ExtensionAPI, + ExtensionContext, + ToolDefinition, +} from "@earendil-works/pi-coding-agent"; +import type { ExecFn } from "../shared/types.js"; + +// 注:defineTool / Type 仅在 factory 内动态 import(运行时解析到真 pi), +// 顶层只保留 `import type`(esbuild/tsc 擦除),故 tests 直接 import 本模块的纯逻辑函数 +// 不会触发 pi 解析——离线可测。 + +// ============================================================================ +// 类型 +// ============================================================================ + +/** 设备树属性。 */ +export interface DtProperty { + /** 属性名,如 compatible / reg / interrupt-parent / #address-cells。 */ + name: string; + /** 原始值文本(= 与 ; 之间,trim 后),无 = 时为空串(布尔属性)。 */ + raw: string; + /** 属性里出现的 phandle 引用 label 列表(<&label> 中的 label)。 */ + phandleRefs: string[]; + /** 定义行号(1-based,0 表示未知)。 */ + line: number; +} + +/** 设备树节点。 */ +export interface DtNode { + /** 节点名部分(@ 前),根节点为 /。 */ + name: string; + /** 完整名(含 unit address),如 sensor@68,根节点为 /。 */ + fullName: string; + /** unit address(@ 后),如 68。 */ + unitAddress?: string; + /** 节点 label(label: 前),如 i2c0。 */ + label?: string; + /** overlay 引用目标(&label { 形式),存在时为 label 名。 */ + refTarget?: string; + props: Record; + children: DtNode[]; + /** 节点起始行(1-based)。 */ + line: number; +} + +/** 解析后的 DTS 结构。 */ +export interface ParsedDts { + /** 顶层节点(根 / 节点 + overlay &label {} 节点)。 */ + nodes: DtNode[]; + /** 所有 label → node 映射(phandle 定义点)。 */ + labels: Map; + /** #include / /include/ 捕获的路径。 */ + includes: string[]; + /** 解析告警(无法识别的行等,非致命)。 */ + warnings: string[]; +} + +/** overlay 校验结果。 */ +export interface ValidateResult { + /** true=无 dangling 引用。 */ + ok: boolean; + /** 错误消息列表。 */ + errors: string[]; +} + +/** compatible 拼写问题。 */ +export interface CompatibleIssue { + /** 出问题的 compatible 字符串。 */ + compatible: string; + node: string; + /** typo = 与字典条目相近但未命中;unknown = 字典无此条目。 */ + kind: "typo" | "unknown"; + /** typo 时给出最接近的字典条目。 */ + suggestion?: string; + line: number; +} + +/** phandle 引用图报告。 */ +export interface PhandleReport { + /** 引用了未定义 label 的 phandle 引用。 */ + dangling: Array<{ ref: string; node: string; line: number }>; + /** 定义了 phandle 数值(phandle = <0xN>)但 label 从未被 & 引用的节点。 */ + orphans: Array<{ phandle: string; label: string | undefined; node: string }>; +} + +/** dtc 编译错误(结构化)。 */ +export interface CompileError { + /** 错误所在行号,无法解析时为 null。 */ + line: number | null; + message: string; +} + +// ============================================================================ +// Tokenizer(内部) +// ============================================================================ + +interface Token { + type: "punct" | "word" | "string"; + value: string; + line: number; + /** 在原始文本中的起始 char offset。 */ + pos: number; +} + +const WORD_CHARS = /[A-Za-z0-9_@#.*+\-]/; +const PUNCT = new Set(["{", "}", ";", "<", ">", "=", ",", "&", ":", "(", ")", "/"]); + +/** + * DTS 文本 → token 流。剥离行注释与块注释,保留字符串字面量。 + * 记录每个 token 的行号与原始 char offset(供属性 raw 切片用)。 + * + * @param text DTS 源文本。 + * @returns token 数组。 + */ +function tokenize(text: string): Token[] { + const tokens: Token[] = []; + const n = text.length; + let i = 0; + let line = 1; + const push = (type: Token["type"], value: string, pos: number): void => { + tokens.push({ type, value, line, pos }); + }; + while (i < n) { + const c = text[i]; + if (c === "\n") { + line++; + i++; + continue; + } + if (c === " " || c === "\t" || c === "\r") { + i++; + continue; + } + // line comment + if (c === "/" && text[i + 1] === "/") { + while (i < n && text[i] !== "\n") i++; + continue; + } + // block comment + if (c === "/" && text[i + 1] === "*") { + i += 2; + while (i < n && !(text[i] === "*" && text[i + 1] === "/")) { + if (text[i] === "\n") line++; + i++; + } + i += 2; + continue; + } + // string literal + if (c === '"') { + const start = i; + i++; + let val = ""; + while (i < n && text[i] !== '"') { + if (text[i] === "\\" && i + 1 < n) { + val += text[i] + text[i + 1]; + i += 2; + continue; + } + val += text[i]; + i++; + } + i++; // closing quote + push("string", val, start); + continue; + } + if (PUNCT.has(c)) { + push("punct", c, i); + i++; + continue; + } + if (WORD_CHARS.test(c)) { + const start = i; + let val = ""; + while (i < n && WORD_CHARS.test(text[i])) { + val += text[i]; + i++; + } + push("word", val, start); + continue; + } + // unknown char, skip + i++; + } + return tokens; +} + +// ============================================================================ +// Parser +// ============================================================================ + +/** + * 从 phandle 引用值中提取 label 列表。 + * 匹配形如 <&label> 的 phandle 引用形态(含带参数与多引用)。 + * + * @param raw 属性原始值文本。 + * @returns label 名数组(如 ["gpio4"]),无引用时为空数组。 + */ +export function extractPhandleRefs(raw: string): string[] { + const refs: string[] = []; + const re = /&([A-Za-z_][A-Za-z0-9_]*)/g; + let m: RegExpExecArray | null; + while ((m = re.exec(raw)) !== null) { + refs.push(m[1]); + } + return refs; +} + +interface ParseCursor { + tokens: Token[]; + text: string; + i: number; + warnings: string[]; +} + +function peekForOpenOrSemi(cur: ParseCursor): "{" | ";" | null { + let depth = 0; // 不跨嵌套 <>,但属性值里无 {},所以首个顶层 { 或 ; 即语句边界 + for (let j = cur.i; j < cur.tokens.length; j++) { + const t = cur.tokens[j]; + if (t.type === "punct" && t.value === "<") depth++; + else if (t.type === "punct" && t.value === ">") depth--; + else if (depth === 0 && t.type === "punct" && t.value === "{") return "{"; + else if (depth === 0 && t.type === "punct" && t.value === ";") return ";"; + } + return null; +} + +/** 解析节点头(到左花括号之前)+ body。调用方负责把节点加入父级 children。 */ +function parseNode(cur: ParseCursor, headerTokens: Token[]): DtNode { + // 从 header tokens 解析 label / name / unit / refTarget + let label: string | undefined; + let refTarget: string | undefined; + let nameTokens: Token[] = [...headerTokens]; + + // overlay 引用:& label + if (headerTokens.length >= 2 && headerTokens[0].value === "&" && headerTokens[1].type === "word") { + refTarget = headerTokens[1].value; + nameTokens = headerTokens.slice(2); + } else { + // label: name —— 找冒号 + const colonIdx = headerTokens.findIndex((t) => t.value === ":"); + if (colonIdx >= 0) { + label = headerTokens + .slice(0, colonIdx) + .filter((t) => t.type === "word") + .map((t) => t.value) + .join(""); + nameTokens = headerTokens.slice(colonIdx + 1); + } + } + + const nameRaw = nameTokens.map((t) => t.value).join("").trim(); + const line = headerTokens[0]?.line ?? 0; + + let fullName: string; + let name: string; + let unitAddress: string | undefined; + if (refTarget) { + fullName = "&" + refTarget; + name = fullName; + } else if (nameRaw === "/" || nameRaw === "") { + fullName = "/"; + name = "/"; + } else { + fullName = nameRaw; + const atIdx = nameRaw.indexOf("@"); + if (atIdx >= 0) { + name = nameRaw.slice(0, atIdx); + unitAddress = nameRaw.slice(atIdx + 1); + } else { + name = nameRaw; + } + } + + const node: DtNode = { + name, + fullName, + unitAddress, + label, + refTarget, + props: {}, + children: [], + line, + }; + + // 消费 { + if (cur.tokens[cur.i]?.value === "{") cur.i++; + + // 解析 body + while (cur.i < cur.tokens.length) { + const t = cur.tokens[cur.i]; + if (t.type === "punct" && t.value === "}") { + cur.i++; // 消费 } + // 期望 ; + if (cur.tokens[cur.i]?.value === ";") cur.i++; + return node; + } + const kind = peekForOpenOrSemi(cur); + if (kind === "{") { + // 子节点头 + const childHeader: Token[] = []; + while (cur.i < cur.tokens.length && cur.tokens[cur.i].value !== "{") { + childHeader.push(cur.tokens[cur.i]); + cur.i++; + } + const child = parseNode(cur, childHeader); + node.children.push(child); + } else if (kind === ";") { + // 属性 + const propHeader: Token[] = []; + while (cur.i < cur.tokens.length && cur.tokens[cur.i].value !== ";") { + propHeader.push(cur.tokens[cur.i]); + cur.i++; + } + const semiTok = cur.tokens[cur.i]; // ; + cur.i++; // 消费 ; + parseProperty(propHeader, semiTok, cur.text, node); + } else { + // 没有边界 token,剩余垃圾,跳过避免死循环 + cur.warnings.push(`line ${t.line}: unable to find statement boundary, skipping "${t.value}"`); + cur.i++; + } + } + return node; +} + +function parseProperty(header: Token[], semi: Token | undefined, text: string, node: DtNode): void { + if (header.length === 0) return; + // 属性名 = 第一个 word/string token(多为 word) + const nameTok = header[0]; + const propName = nameTok.value; + // 找 = + const eqIdx = header.findIndex((t) => t.value === "="); + let raw = ""; + let line = nameTok.line; + if (eqIdx >= 0 && semi) { + // raw = text.slice(eq 后, semi 位置) + const eqTok = header[eqIdx]; + raw = text.slice(eqTok.pos + 1, semi.pos).trim(); + } + const phandleRefs = extractPhandleRefs(raw); + node.props[propName] = { name: propName, raw, phandleRefs, line }; +} + +/** 给 cursor 挂载 warnings 的便捷类型别名(保留以兼容旧引用)。 */ +type ParseCursorWithWarnings = ParseCursor; + +/** + * 解析 DTS/DTSI 源文本为结构化节点树。 + * + * 识别 node 块与 prop = value 语句、label、overlay 引用节点、 + * phandle 定义、phandle 引用、include 指令。 + * + * @param text DTS/DTSI 源文本。 + * @returns ParsedDts(节点树 + label 表 + include 列表 + 告警)。 + */ +export function parseDts(text: string): ParsedDts { + const tokens = tokenize(text); + const cur: ParseCursorWithWarnings = { + tokens, + text, + i: 0, + warnings: [], + }; + const nodes: DtNode[] = []; + const labels = new Map(); + const includes: string[] = []; + + /** 递归收集 label → node(含子节点)。 */ + const collectLabels = (node: DtNode): void => { + if (node.label) { + if (!labels.has(node.label)) labels.set(node.label, node); + } + for (const child of node.children) collectLabels(child); + }; + + while (cur.i < tokens.length) { + const t = tokens[cur.i]; + + // #include / /include/ + if (t.type === "word" && (t.value === "#include" || t.value === "/include/")) { + cur.i++; + const next = tokens[cur.i]; + if (next?.type === "string") { + includes.push(next.value); + cur.i++; + } else if (next?.value === "<") { + cur.i++; + let path = ""; + while (cur.i < tokens.length && tokens[cur.i].value !== ">") { + path += tokens[cur.i].value; + cur.i++; + } + if (cur.i < tokens.length) cur.i++; // > + if (path) includes.push(path); + } + continue; + } + + // #define —— 跳到下一个 ; / { / } 或新指令 + if (t.type === "word" && t.value === "#define") { + cur.i++; + while (cur.i < tokens.length) { + const nt = tokens[cur.i]; + if (nt.value === ";" || nt.value === "{" || nt.value === "}") { + if (nt.value === ";") cur.i++; + break; + } + if (nt.type === "word" && (nt.value.startsWith("#") || nt.value === "/dts-v1/" || nt.value === "/memreserve/")) break; + cur.i++; + } + continue; + } + + // /dts-v1/ ; /memreserve/ ... ; + if (t.value === "/") { + const next = tokens[cur.i + 1]; + if (next?.value === "{") { + // 根节点 / + const header: Token[] = [t]; + cur.i++; // 消费 / + const root = parseNode(cur, header); + nodes.push(root); + collectLabels(root); + continue; + } + // 指令 /xxx/ + cur.i++; + while (cur.i < tokens.length && tokens[cur.i].value !== ";") cur.i++; + if (cur.i < tokens.length) cur.i++; // ; + continue; + } + + // overlay &label { + if (t.value === "&") { + const header: Token[] = []; + while (cur.i < tokens.length && tokens[cur.i].value !== "{") { + header.push(tokens[cur.i]); + cur.i++; + } + const node = parseNode(cur, header); + nodes.push(node); + collectLabels(node); + continue; + } + + // 普通顶层节点(罕见:顶层 label: node {} 不在 / 内)—— 当作节点头处理 + if (t.type === "word" || t.value === ":") { + const kind = peekForOpenOrSemi(cur); + if (kind === "{") { + const header: Token[] = []; + while (cur.i < tokens.length && cur.tokens[cur.i].value !== "{") { + header.push(cur.tokens[cur.i]); + cur.i++; + } + const node = parseNode(cur, header); + nodes.push(node); + collectLabels(node); + continue; + } + if (kind === ";") { + // 顶层属性语句(不在任何节点内)—— 跳过 + while (cur.i < tokens.length && tokens[cur.i].value !== ";") cur.i++; + if (cur.i < tokens.length) cur.i++; + continue; + } + } + + // 无法识别 + cur.warnings?.push(`line ${t.line}: skipping unexpected token "${t.value}"`); + cur.i++; + } + + return { nodes, labels, includes, warnings: cur.warnings ?? [] }; +} + +// ============================================================================ +// findNode +// ============================================================================ + +/** + * 按路径查找节点。path 形如 i2c0/sensor@68 或 /i2c0/sensor@68 或 /。 + * 每段匹配子节点的 fullName / label / name。 + * + * @param root 根节点(parseDts 返回的顶层节点之一)。 + * @param path 节点路径,段间用 / 分隔。 + * @returns 匹配节点或 null(路径不存在 / 空路径)。 + */ +export function findNode(root: DtNode, path: string): DtNode | null { + if (!path) return null; + const segments = path.split("/").filter((s) => s.length > 0); + let startNode: DtNode = root; + + // 以 / 开头表示从根开始 + if (path.startsWith("/")) { + startNode = root; + } else if (segments.length > 0) { + // 不以 / 开头也尝试从 root 查 + startNode = root; + } + + let current: DtNode | null = startNode; + for (const seg of segments) { + if (!current) return null; + const parent: DtNode = current; + const match: DtNode | undefined = parent.children.find( + (c: DtNode) => c.fullName === seg || c.label === seg || c.name === seg, + ); + if (!match) return null; + current = match; + } + return current; +} + +// ============================================================================ +// validateOverlay +// ============================================================================ + +/** + * 校验 overlay DTS 相对 base DTS 的合法性。 + * + * 检查:overlay 中所有 label 引用(节点头 overlay 引用与属性值 phandle 引用) + * 必须能在 base 或 overlay 自身的 label 表中找到定义,否则报 + * dangling phandle reference 错误。fail-closed:有未定义引用即 ok:false。 + * + * @param overlay 待校验的 overlay DTS(解析后)。 + * @param base 基线 DTS(解析后),提供已知 label 集。 + * @returns ValidateResult(ok + errors)。 + */ +export function validateOverlay(overlay: ParsedDts, base: ParsedDts): ValidateResult { + const errors: string[] = []; + const known = new Set([...base.labels.keys(), ...overlay.labels.keys()]); + + // 遍历 overlay 所有节点,收集引用 + const walk = (node: DtNode): void => { + if (node.refTarget && !known.has(node.refTarget)) { + errors.push( + `dangling phandle reference: &${node.refTarget} at line ${node.line}`, + ); + } + for (const prop of Object.values(node.props)) { + for (const ref of prop.phandleRefs) { + if (!known.has(ref)) { + errors.push( + `dangling phandle reference: &${ref} at line ${prop.line} (property ${prop.name})`, + ); + } + } + } + for (const child of node.children) walk(child); + }; + for (const node of overlay.nodes) walk(node); + + return { ok: errors.length === 0, errors }; +} + +// ============================================================================ +// checkCompatible +// ============================================================================ + +/** 内置主流 SoC compatible 字典(base 型号)。可由扩展层注入更全的。 */ +export const DEFAULT_COMPATIBLE_DICT: string[] = [ + "st,stm32f411", + "st,stm32f411xe", + "st,stm32f411xg", + "st,stm32f407", + "st,stm32h743", + "rockchip,rk3588", + "rockchip,rk3568", + "rockchip,rk3399", + "xunpai,hobbit", + "renesas,rza1", + "nvidia,tegra210", + "fsl,imx6q", + "fsl,imx8mm", + "brcm,bcm2837", + "allwinner,sun50i-a64", +]; + +/** 简单 Levenshtein 距离(用于 typo 建议)。 */ +function levenshtein(a: string, b: string): number { + const m = a.length; + const n = b.length; + const dp: number[][] = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0)); + for (let i = 0; i <= m; i++) dp[i][0] = i; + for (let j = 0; j <= n; j++) dp[0][j] = j; + for (let i = 1; i <= m; i++) { + for (let j = 1; j <= n; j++) { + const cost = a[i - 1] === b[j - 1] ? 0 : 1; + dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost); + } + } + return dp[m][n]; +} + +/** + * 校验树中所有 compatible 属性字符串拼写。 + * - 命中字典 → 无问题 + * - 与某字典条目 Levenshtein 距离 ≤ 2 但未命中 → typo,给建议 + * - 否则 → unknown(标 unknown compatible, not in dictionary,非错非对) + * + * @param tree 解析后的 DTS。 + * @param dict compatible 字典,默认 DEFAULT_COMPATIBLE_DICT。 + * @returns CompatibleIssue 列表(空=全部命中)。 + */ +export function checkCompatible( + tree: ParsedDts, + dict: string[] = DEFAULT_COMPATIBLE_DICT, +): CompatibleIssue[] { + const issues: CompatibleIssue[] = []; + const dictSet = new Set(dict); + const walk = (node: DtNode): void => { + const prop = node.props["compatible"]; + if (prop && prop.raw) { + // compatible 由一个或多个引号包裹的字符串组成("vendor,model",多串用逗号连接)。 + // 用正则逐个提取引号内字符串,避免误切 vendor,model 内的逗号。 + const comps: string[] = []; + const re = /"([^"]*)"/g; + let cm: RegExpExecArray | null; + while ((cm = re.exec(prop.raw)) !== null) { + const s = cm[1].trim(); + if (s.length > 0) comps.push(s); + } + // 兜底:若 raw 无引号(解析异常),按逗号切 + if (comps.length === 0) { + for (const s of prop.raw.split(",").map((x) => x.trim())) { + if (s.length > 0) comps.push(s); + } + } + for (const c of comps) { + if (dictSet.has(c)) continue; + let best: string | undefined; + let bestDist = Infinity; + for (const d of dict) { + const dist = levenshtein(c, d); + if (dist < bestDist) { + bestDist = dist; + best = d; + } + } + if (best && bestDist <= 2 && bestDist > 0) { + issues.push({ + compatible: c, + node: node.fullName, + kind: "typo", + suggestion: best, + line: prop.line, + }); + } else { + issues.push({ + compatible: c, + node: node.fullName, + kind: "unknown", + line: prop.line, + }); + } + } + } + for (const child of node.children) walk(child); + }; + for (const node of tree.nodes) walk(node); + return issues; +} + +// ============================================================================ +// checkPhandle +// ============================================================================ + +/** + * 构建 phandle 引用图:所有 phandle 数值定义 vs 所有 label 引用。 + * - dangling:引用了未定义的 label(fail-closed 暴露断链) + * - orphans:定义了 phandle 数值但 label 从未被任何引用使用的节点 + * + * @param tree 解析后的 DTS。 + * @returns PhandleReport(dangling + orphans)。 + */ +export function checkPhandle(tree: ParsedDts): PhandleReport { + const dangling: Array<{ ref: string; node: string; line: number }> = []; + const orphans: Array<{ phandle: string; label: string | undefined; node: string }> = []; + const labelSet = new Set(tree.labels.keys()); + + // 收集所有引用,标注 dangling + const walkRefs = (node: DtNode): void => { + if (node.refTarget && !labelSet.has(node.refTarget)) { + dangling.push({ ref: node.refTarget, node: node.fullName, line: node.line }); + } + for (const prop of Object.values(node.props)) { + for (const ref of prop.phandleRefs) { + if (!labelSet.has(ref)) { + dangling.push({ ref, node: node.fullName, line: prop.line }); + } + } + } + for (const child of node.children) walkRefs(child); + }; + for (const node of tree.nodes) walkRefs(node); + + // 收集被引用的 label 集合 + const referenced = new Set(); + const walkRefTargets = (node: DtNode): void => { + if (node.refTarget) referenced.add(node.refTarget); + for (const prop of Object.values(node.props)) { + for (const ref of prop.phandleRefs) referenced.add(ref); + } + for (const child of node.children) walkRefTargets(child); + }; + for (const node of tree.nodes) walkRefTargets(node); + + // orphans:有 phandle 属性但 label 未被引用 + for (const [label, node] of tree.labels) { + const phandleProp = node.props["phandle"]; + if (phandleProp && !referenced.has(label)) { + orphans.push({ + phandle: phandleProp.raw, + label, + node: node.fullName, + }); + } + } + + return { dangling, orphans }; +} + +// ============================================================================ +// compileDts(注入 ExecFn,不依赖真实硬件) +// ============================================================================ + +/** compileDts 选项。 */ +export interface CompileOpts { + /** 额外 include 目录(--include-dir)。 */ + includeDirs?: string[]; + /** 输出路径。 */ + out?: string; + /** 覆盖 dtc 可执行名,默认 dtc。 */ + dtc?: string; + /** overlay 模式(加 -@,产出 .dtbo)。 */ + overlay?: boolean; +} + +/** compileDts 结果。 */ +export interface CompileResult { + /** true=编译成功。 */ + ok: boolean; + /** dtb 输出路径(成功时)。 */ + out?: string; + /** 结构化错误列表(失败时)。 */ + errors: CompileError[]; + stderr: string; +} + +/** + * 解析 dtc stderr 为结构化错误(行号 + 消息)。 + * 典型:Error: board.dts:42.1-12: syntax error 或 board.dts:42: ...。 + * + * @param stderr dtc 的 stderr 输出。 + * @returns CompileError 数组。 + */ +export function parseDtcErrors(stderr: string): CompileError[] { + const errors: CompileError[] = []; + const re = /(?:Error:\s*)?([^:\s]+):\s*(\d+)(?:\.\d+(?:-\d+)?)?\s*:?\s*(.+)/g; + let m: RegExpExecArray | null; + while ((m = re.exec(stderr)) !== null) { + const line = Number.parseInt(m[2], 10); + const message = (m[3] ?? "").trim(); + if (message) { + errors.push({ line: Number.isNaN(line) ? null : line, message }); + } + } + // dtc 有时只输出无行号的 "FATAL" 行 + if (errors.length === 0 && stderr.trim().length > 0) { + const fatal = stderr.split("\n").filter((l) => l.trim().length > 0); + for (const line of fatal) { + errors.push({ line: null, message: line.trim() }); + } + } + return errors; +} + +/** + * 用注入的 ExecFn 跑 dtc -I dts -O dtb -o out --include-dir ... file.dts。 + * fail-closed:exec 抛错或 exitCode !== 0 视为失败,返回结构化错误。 + * + * @param exec 注入的执行函数(测试 mock / 板链路都走这条,不依赖真实硬件)。 + * @param file 输入 .dts 文件路径。 + * @param opts 编译选项(includeDirs/out/dtc/overlay)。 + * @returns CompileResult。 + */ +export async function compileDts( + exec: ExecFn, + file: string, + opts: CompileOpts = {}, +): Promise { + const dtc = opts.dtc ?? "dtc"; + const args: string[] = ["-I", "dts", "-O", "dtb"]; + if (opts.overlay) args.push("-@"); + const out = opts.out ?? "out.dtb"; + args.push("-o", out); + for (const dir of opts.includeDirs ?? []) { + args.push("--include-dir", dir); + } + args.push(file); + + let stderr = ""; + let exitCode = 0; + try { + const res = await exec(dtc, args, { timeout: 30_000 }); + stderr = res.stderr; + exitCode = res.exitCode; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + return { + ok: false, + errors: [{ line: null, message: `dtc exec failed: ${msg}` }], + stderr: msg, + }; + } + + if (exitCode !== 0) { + return { ok: false, errors: parseDtcErrors(stderr), stderr }; + } + return { ok: true, out, errors: [], stderr }; +} + +// ============================================================================ +// dt 工具 + 扩展装配(运行时在真 pi 内动态 import defineTool/Type) +// ============================================================================ + +/** dt 工具参数(与 dtSchema 对应)。 */ +export interface DtToolParams { + action: "parse" | "check_compatible" | "check_phandle" | "compile" | "overlay_diff"; + file: string; + include_dirs?: string[]; + compatible?: string; + overlay?: string; + out?: string; +} + +/** + * 设备树扩展装配。 + * + * - 注册 `dt` 工具(action: parse / check_compatible / check_phandle / compile / overlay_diff) + * - session_start 记录字典规模与可用 action + * + * defineTool/Type 在函数内动态 import,确保顶层无 pi 运行时依赖(离线可单测逻辑)。 + * + * @param pi pi 扩展 API。 + */ +export default async function deviceTreeExtension(pi: ExtensionAPI): Promise { + const { defineTool } = await import("@earendil-works/pi-coding-agent"); + const { Type } = await import("@earendil-works/pi-ai"); + + // pi.exec 适配为逻辑层 ExecFn + const execFn: ExecFn = (cmd, args, opts) => + pi.exec(cmd, args, opts ?? {}); + + const readText = async (path: string): Promise => { + const res = await pi.exec("cat", [path], { timeout: 10_000 }); + if (res.exitCode !== 0) { + throw new Error(`failed to read ${path}: ${res.stderr || res.stdout}`); + } + return res.stdout; + }; + + const 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)" }), + ), + 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)" })), + }); + + const dtTool = defineTool({ + name: "dt", + label: "Device Tree", + description: + "Structure-aware device tree (.dts/.dtsi) tool. Actions: parse (node tree + phandle refs), " + + "check_compatible (typo vs SoC dictionary), check_phandle (dangling/orphan refs), " + + "compile (dtc -> dtb with structured errors), overlay_diff (base.dtb + overlay.dtbo diff).", + promptSnippet: + "Parse/validate/compile device tree (.dts) — use this before editing .dts to avoid fuzzy-match errors", + parameters: dtSchema, + // dt 操作纯文件解析/编译,无共享硬件资源,可并行 + executionMode: "parallel", + async execute(_id, params, _signal, _onUpdate, _ctx) { + const p = params as DtToolParams; + + try { + switch (p.action) { + case "parse": { + const text = await readText(p.file); + const tree = parseDts(text); + return { + content: [ + { + type: "text", + text: JSON.stringify( + { + nodes: tree.nodes, + labels: [...tree.labels.keys()], + includes: tree.includes, + warnings: tree.warnings, + }, + null, + 2, + ), + }, + ], + details: { + action: "parse", + labels: tree.labels.size, + includes: tree.includes.length, + }, + }; + } + case "check_compatible": { + const text = await readText(p.file); + const tree = parseDts(text); + const dict = p.compatible + ? [...DEFAULT_COMPATIBLE_DICT, p.compatible] + : DEFAULT_COMPATIBLE_DICT; + const issues = checkCompatible(tree, dict); + return { + content: [ + { type: "text", text: JSON.stringify({ issues, total: issues.length }, null, 2) }, + ], + details: { action: "check_compatible", issueCount: issues.length }, + }; + } + case "check_phandle": { + const text = await readText(p.file); + const tree = parseDts(text); + const report = checkPhandle(tree); + return { + content: [ + { + type: "text", + text: JSON.stringify( + { dangling: report.dangling, orphans: report.orphans }, + null, + 2, + ), + }, + ], + details: { + action: "check_phandle", + dangling: report.dangling.length, + orphans: report.orphans.length, + }, + }; + } + case "compile": { + const result = await compileDts(execFn, p.file, { + includeDirs: p.include_dirs, + out: p.out, + overlay: p.overlay !== undefined, + }); + return { + content: [ + { + type: "text", + text: JSON.stringify( + { ok: result.ok, out: result.out, errors: result.errors, stderr: result.stderr }, + null, + 2, + ), + }, + ], + details: { action: "compile", ok: result.ok, errorCount: result.errors.length }, + isError: !result.ok, + }; + } + case "overlay_diff": { + const overlayText = p.overlay ? await readText(p.overlay) : ""; + const overlayTree = parseDts(overlayText); + let baseTree: ParsedDts; + try { + const res = await pi.exec("dtc", ["-I", "dtb", "-O", "dts", p.file], { + timeout: 15_000, + }); + baseTree = parseDts(res.stdout); + } catch { + baseTree = parseDts(""); + } + const validation = validateOverlay(overlayTree, baseTree); + return { + content: [ + { + type: "text", + text: JSON.stringify( + { + overlayValidation: validation, + overlayNodes: overlayTree.nodes.length, + overlayLabels: [...overlayTree.labels.keys()], + }, + null, + 2, + ), + }, + ], + details: { action: "overlay_diff", ok: validation.ok }, + isError: !validation.ok, + }; + } + default: + return { + content: [{ type: "text", text: `unknown action: ${p.action}` }], + isError: true, + }; + } + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + return { + content: [{ type: "text", text: `dt ${p.action} failed: ${msg}` }], + isError: true, + }; + } + }, + }) as ToolDefinition; + + pi.registerTool(dtTool); + + pi.on("session_start", () => { + pi.appendEntry("dt:loaded", { + dictionarySize: DEFAULT_COMPATIBLE_DICT.length, + actions: ["parse", "check_compatible", "check_phandle", "compile", "overlay_diff"], + }); + }); +} diff --git a/src/extensions/edit-strict.ts b/src/extensions/edit-strict.ts new file mode 100644 index 0000000..204700a --- /dev/null +++ b/src/extensions/edit-strict.ts @@ -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 = { + "‘": "'", // 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 { + 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).", + }); + }); +} diff --git a/src/extensions/env-probe.ts b/src/extensions/env-probe.ts new file mode 100644 index 0000000..604c1ea --- /dev/null +++ b/src/extensions/env-probe.ts @@ -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 { + 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 { + 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 尾部的 块。 + * agent 看到这段即知板/工具链事实,无需自己 bash 探。 + * @param probe 环境事实对象。 + * @returns 多行 prompt 片段,含开闭合标签。 + */ +export function buildEnvPrompt(probe: EnvProbe): string { + const lines: string[] = []; + lines.push(""); + 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(""); + return lines.join("\n"); +} + +/** + * 剥离所有 ... 块,折叠多余空行。 + * @param systemPrompt 原始 systemPrompt。 + * @returns 剥离嵌入块后的 systemPrompt(trimEnd)。 + */ +export function stripEnvBlocks(systemPrompt: string): string { + const re = /[\s\S]*?<\/embedded_environment>/g; + return systemPrompt.replace(re, "").replace(/\n{3,}/g, "\n\n").trimEnd(); +} + +/** + * 把探针块追加到 systemPrompt 尾部(runner 链式更新)。 + * 若 systemPrompt 已含 (重入/链式叠加),先剥离旧块再追加新块, + * 避免重复堆积。 + * @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, + defaultTimeout: number, +): ExecFn { + return async (command: string, args: string[], opts?: ExecOpts): Promise => { + 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 { + 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 { + 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, + }); + }); +} diff --git a/src/extensions/flash.ts b/src/extensions/flash.ts new file mode 100644 index 0000000..eb155fd --- /dev/null +++ b/src/extensions/flash.ts @@ -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= of= bs=4M conv=fsync [seek=]` + * - fastboot: `fastboot flash `(partition 缺省则 `fastboot flash `) + * - dfu: `dfu-util -d [-a ] -D `(target = vid:pid) + * - openocd: `openocd -f -c "program 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= of=/dev/null bs=4M count=1` 只读验证镜像可读。 + * fastboot: `fastboot getvar all` 确认设备在线。 + * dfu: `dfu-util -l` 列出 DFU 设备。 + * openocd: `openocd -f -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 { + 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= bs=4M count=`,对 stdout 算 sha256, + * 与 plan.expectedSha256(dryRun 预计算)比对。不匹配 → VERIFY FAILED。 + * openocd: `openocd -f -c "verify_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 { + 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 { + // ① 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 { + 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, + }); + }); +} diff --git a/src/extensions/glm-provider.ts b/src/extensions/glm-provider.ts new file mode 100644 index 0000000..c78e527 --- /dev/null +++ b/src/extensions/glm-provider.ts @@ -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 | null | undefined, + opts: NormalizeHexOptions = {}, +): { normalized: Record; 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 = {}; + 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; + 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 | 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 { + 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; opts?: NormalizeHexOptions }; + pi.events.emit("glm:normalized", normalizeToolArguments(d.args, d.opts)); + }); +} diff --git a/src/extensions/hardware-state.ts b/src/extensions/hardware-state.ts new file mode 100644 index 0000000..d89f4d7 --- /dev/null +++ b/src/extensions/hardware-state.ts @@ -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; + /** 捕获时刻(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; + /** 最新 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, + 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): ReplayResult { + const locks: Record = {}; + // 用 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, + 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(); + 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 ] @ \n = ` 的多行文本。 + */ +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 { + 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 }; + 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; + }); +} diff --git a/src/extensions/hardware-verify.ts b/src/extensions/hardware-verify.ts new file mode 100644 index 0000000..c4995db --- /dev/null +++ b/src/extensions/hardware-verify.ts @@ -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 ` + * - i2c: `i2cget -y []` + * - sysfs: `cat ` + * - serial: `cat `(/dev/ttyUSB* 等设备节点) + * - current:`cat `(电流计 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 { + 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 { + 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 { + 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" }); + }); +} diff --git a/src/extensions/index.ts b/src/extensions/index.ts new file mode 100644 index 0000000..f3898e2 --- /dev/null +++ b/src/extensions/index.ts @@ -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 { + 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)", + }); +} diff --git a/src/extensions/jtag-debugger.ts b/src/extensions/jtag-debugger.ts new file mode 100644 index 0000000..b3c76cf --- /dev/null +++ b/src/extensions/jtag-debugger.ts @@ -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; + /** bkptno(断点编号)。 */ + bkptno?: string; + /** 线程 id。 */ + threadId?: string; + /** 原始解析字段(兜底)。 */ + raw: Record; +} + +/** ^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; +} + +/** MI 行载荷联合。 */ +export type MiPayload = MiConsolePayload | MiStoppedPayload | MiBreakpointPayload | Record; + +/** 一行 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 { + const out: Record = {}; + 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 | 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; + 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(); + /** 是否已连上 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 { + 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; + 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 常驻 + 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 "); + 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 + 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 { + void ctx; + // 一期简化:把 MI 命令发 gdb stdin,读回一行 ^ 记录。 + // 真实事件泵在 persistent-shell 会话池之上实现;这里返回占位让 agent 能继续。 + const parsed = parseMiLine(miCmd); + return JSON.stringify(parsed); +} diff --git a/src/extensions/length-recovery.ts b/src/extensions/length-recovery.ts new file mode 100644 index 0000000..4ae68b8 --- /dev/null +++ b/src/extensions/length-recovery.ts @@ -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 { + const full: RecoveryHitRecord = { ...rec, timestamp: Date.now() }; + this.hits.push(full); + return full; + } + + /** 累计命中次数。 */ + get count(): number { + return this.hits.length; + } + + /** 各策略命中次数。 */ + get strategyCounts(): Record { + const out: Record = { + 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; + 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 { + 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, + }); + }); +} diff --git a/src/extensions/loop-orchestrator.ts b/src/extensions/loop-orchestrator.ts new file mode 100644 index 0000000..854ea58 --- /dev/null +++ b/src/extensions/loop-orchestrator.ts @@ -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 = { + 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 { + 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 = { + 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; + }); +} diff --git a/src/extensions/mcp-bridge.ts b/src/extensions/mcp-bridge.ts new file mode 100644 index 0000000..4f2994c --- /dev/null +++ b/src/extensions/mcp-bridge.ts @@ -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; + url?: string; + headers?: Record; + 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 | undefined, +) => Promise; + +/** 注入的工具发现函数(模拟 MCP client.listTools)。 */ +export type ListToolsFn = (server: string) => Promise; + +/** 连接表条目。 */ +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; + + // 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" }); + } else { + for (const [k, v] of Object.entries(c.env as Record)) { + 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" }); + } + } + + return errors; +} + +/** + * 把原始 config 对象归一成 McpServerConfig(调用方已确保校验通过)。 + * + * @param cfg 已校验的原始 config 对象。 + * @returns 归一化的 McpServerConfig。 + */ +export function normalizeServerConfig(cfg: Record): 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) : undefined, + url: cfg.url !== undefined ? String(cfg.url) : undefined, + headers: cfg.headers && typeof cfg.headers === "object" ? (cfg.headers as Record) : 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; idx: number }> = []; + + if (Array.isArray(raw)) { + (raw as unknown[]).forEach((c, i) => { + if (c !== null && typeof c === "object") { + entries.push({ cfg: c as Record, idx: i }); + } else { + errors.push({ server: `[${i}]`, field: "root", message: "server config must be an object" }); + } + }); + } else { + const obj = raw as Record; + if (obj.mcpServers !== undefined && typeof obj.mcpServers === "object" && !Array.isArray(obj.mcpServers)) { + // 标准 MCP 形态:{ mcpServers: { name: {...} } },name 从 key 补入 + const ms = obj.mcpServers as Record; + let i = 0; + for (const [name, c] of Object.entries(ms)) { + if (c !== null && typeof c === "object") { + entries.push({ cfg: { ...(c as Record), 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, 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(); + private connections = new Map(); + 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 { + 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, + ): Promise { + 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; + callTool: (tool: string, args: Record | undefined) => Promise<{ content: McpContentItem[]; isError?: boolean }>; + close: () => Promise; +} + +/** + * 动态加载 @modelcontextprotocol/sdk(扩展自带依赖)。 + * 用 Function 包裹 import 使 tsc 不解析该模块——类型由运行时提供。 + * @returns SDK 命名空间(any)。 + */ +async function loadMcpSdk(): Promise { + const dynamicImport = new Function("spec", "return import(spec)") as (spec: string) => Promise; + 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 { + 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 { + 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(); + + 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 }; + 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)); + }); +} diff --git a/src/extensions/pdf-reader.ts b/src/extensions/pdf-reader.ts new file mode 100644 index 0000000..2a2dab5 --- /dev/null +++ b/src/extensions/pdf-reader.ts @@ -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; + +// ============================================================================ +// ⑦ 整合:规划一次 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 { + 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 { + 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 { + 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 { + 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), + }); + } + }); +} diff --git a/src/extensions/peripheral-probe.ts b/src/extensions/peripheral-probe.ts new file mode 100644 index 0000000..016f3fe --- /dev/null +++ b/src/extensions/peripheral-probe.ts @@ -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 ` 的地址表。 + * + * 输出格式(实测): + * ``` + * 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 `,解析地址表。 + * + * 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 { + 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 { + 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 { + 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 { + 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 会被清洗防 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 { + // 清洗:只保留字母/数字/下划线/连字符,防注入。 + 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 { + 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 { + 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", + ], + }); + }); +} diff --git a/src/extensions/persistent-shell.ts b/src/extensions/persistent-shell.ts new file mode 100644 index 0000000..4e5ae8f --- /dev/null +++ b/src/extensions/persistent-shell.ts @@ -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, + * 读到哨兵行即停。形如:`; 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(); + 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 { + 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 { + 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 { + 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 { + 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; + }); +} diff --git a/src/extensions/safety-gate.ts b/src/extensions/safety-gate.ts new file mode 100644 index 0000000..b9893b8 --- /dev/null +++ b/src/extensions/safety-gate.ts @@ -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(); + + /** 尝试获取锁。成功 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 = { + "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 }); + } + }); +} diff --git a/src/extensions/server-runtime.ts b/src/extensions/server-runtime.ts new file mode 100644 index 0000000..2e4941b --- /dev/null +++ b/src/extensions/server-runtime.ts @@ -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(); + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 }; +} diff --git a/src/extensions/subprocess-isolation.ts b/src/extensions/subprocess-isolation.ts new file mode 100644 index 0000000..ae176ec --- /dev/null +++ b/src/extensions/subprocess-isolation.ts @@ -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; +} + +/** 注入的 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(); + 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 { + 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 { + if (!timeoutMs || timeoutMs <= 0) { + return await this.collect(child, child.result); + } + + let timer: ReturnType | undefined; + const timeout = new Promise((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): Promise { + 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。 + */ +export default async function subprocessIsolationExtension( + pi: ExtensionAPI, +): Promise { + 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((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; + }); +} diff --git a/src/index.ts b/src/index.ts new file mode 100644 index 0000000..6966fb4 --- /dev/null +++ b/src/index.ts @@ -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"; diff --git a/src/shared/types.ts b/src/shared/types.ts new file mode 100644 index 0000000..4b7efeb --- /dev/null +++ b/src/shared/types.ts @@ -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; + +export interface ExecOpts { + cwd?: string; + timeout?: number; + env?: Record; + /** 以哪个板执行(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; +} + +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; +} diff --git a/src/types/pi.d.ts b/src/types/pi.d.ts new file mode 100644 index 0000000..51db061 --- /dev/null +++ b/src/types/pi.d.ts @@ -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>(props: T, options?: { description?: string }): T; + String(options?: { description?: string }): string; + Number(options?: { description?: string }): number; + Boolean(options?: { description?: string }): boolean; + Optional(schema: T, options?: { description?: string }): T; + Union(schemas: T, options?: { description?: string }): T[number]; + Literal(value: T): T; + Array(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 { + content: Array; + details?: TDetails; + isError?: boolean; + } + export type AgentToolUpdateCallback = (update: { + content?: Array; + details?: TDetails; + }) => void; + + export interface ExtensionUIContext { + confirm(title: string, message: string, opts?: ExtensionUIDialogOptions): Promise; + select(title: string, options: string[], opts?: ExtensionUIDialogOptions): Promise; + input(title: string, placeholder?: string, opts?: ExtensionUIDialogOptions): Promise; + notify(message: string, type?: "info" | "warning" | "error"): void; + custom: (render: unknown) => Promise; + } + 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 { + 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 | undefined, + ctx: ExtensionContext, + ): Promise>; + renderCall?: unknown; + renderResult?: unknown; + } + + export function defineTool( + tool: ToolDefinition, + ): ToolDefinition; + + export interface ToolCallEvent { + type: "tool_call"; + toolCallId: string; + toolName: string; + input: Record; + } + export interface ToolCallEventResult { + block?: boolean; + reason?: string; + terminate?: boolean; + } + export interface ToolResultEvent { + type: "tool_result"; + toolCallId: string; + toolName: string; + input: Record; + isError: boolean; + content: Array; + details?: unknown; + } + export interface ToolResultEventResult { + content?: Array; + 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; + } + + export interface ProviderModelConfig { + id: string; + name: string; + api?: string; + baseUrl?: string; + reasoning: boolean; + thinkingLevelMap?: Record; + input: ("text" | "image")[]; + cost: { input: number; output: number; cacheRead: number; cacheWrite: number }; + contextWindow: number; + maxTokens: number; + headers?: Record; + compat?: Record; + } + export interface ProviderConfig { + name?: string; + baseUrl?: string; + apiKey?: string; + api?: string; + headers?: Record; + authHeader?: boolean; + models?: ProviderModelConfig[]; + } + + export interface ExtensionAPI { + on(event: "tool_call", handler: (event: ToolCallEvent, ctx: ExtensionContext) => Promise | ToolCallEventResult | undefined): void; + on(event: "tool_result", handler: (event: ToolResultEvent, ctx: ExtensionContext) => Promise | ToolResultEventResult | undefined): void; + on(event: "session_start", handler: (event: SessionStartEvent, ctx: ExtensionContext) => Promise | unknown): void; + on(event: "before_agent_start", handler: (event: BeforeAgentStartEvent, ctx: ExtensionContext) => Promise | BeforeAgentStartEventResult | undefined): void; + on(event: "session_before_compact", handler: (event: unknown, ctx: ExtensionContext) => Promise | 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; + registerProvider(provider: unknown): void; + registerProvider(name: string, config: ProviderConfig): void; + sendMessage(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(customType: string, data?: T): void; + exec(command: string, args: string[], options?: ExecOptions): Promise; + setActiveTools(toolNames: string[]): void; + getActiveTools(): string[]; + getAllTools(): Array<{ name: string }>; + setModel(model: unknown): Promise; + events: EventBus; + } + + // 程序化启动(agent.ts 动态 import 用;运行时解析真 pi) + export interface CreateAgentSessionResult { + session: unknown; + modelFallbackMessage?: string; + } + export declare function createAgentSession(options?: Record): Promise; + export declare const SessionManager: { + inMemory?(): unknown; + create?(...args: unknown[]): unknown; + [key: string]: unknown; + }; +} diff --git a/tests/board-link.test.ts b/tests/board-link.test.ts new file mode 100644 index 0000000..97797c5 --- /dev/null +++ b/tests/board-link.test.ts @@ -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): ExecFn & { mock: { calls: unknown[][] } } { + const fn = vi.fn(async (): Promise => ({ + 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); + }); +}); diff --git a/tests/build-tracker.test.ts b/tests/build-tracker.test.ts new file mode 100644 index 0000000..20cb4e1 --- /dev/null +++ b/tests/build-tracker.test.ts @@ -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); + }); +}); diff --git a/tests/cross-compile.test.ts b/tests/cross-compile.test.ts new file mode 100644 index 0000000..8a18507 --- /dev/null +++ b/tests/cross-compile.test.ts @@ -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(); + }); +}); diff --git a/tests/datasheet-rag.test.ts b/tests/datasheet-rag.test.ts new file mode 100644 index 0000000..e45fa49 --- /dev/null +++ b/tests/datasheet-rag.test.ts @@ -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); + }); +}); diff --git a/tests/device-tree.test.ts b/tests/device-tree.test.ts new file mode 100644 index 0000000..4af6e1c --- /dev/null +++ b/tests/device-tree.test.ts @@ -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); + }); +}); diff --git a/tests/edit-strict.test.ts b/tests/edit-strict.test.ts new file mode 100644 index 0000000..53e8f7b --- /dev/null +++ b/tests/edit-strict.test.ts @@ -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"'); + }); +}); diff --git a/tests/env-probe.test.ts b/tests/env-probe.test.ts new file mode 100644 index 0000000..ab0921a --- /dev/null +++ b/tests/env-probe.test.ts @@ -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 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("含 开闭合标签", () => { + const p = buildEnvPrompt(sampleProbe); + expect(p.startsWith("")).toBe(true); + expect(p.trim().endsWith("")).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(""); + expect(p).toContain(""); + // 原文在前,探针块在后 + expect(p.indexOf("You are a coding agent.")).toBeLessThan(p.indexOf("")); + }); + + 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(//g) ?? []).length; + expect(blockCount).toBe(1); + expect(second).toContain("deadbee"); + expect(second).not.toContain("abc1234"); + }); + + it("stripEnvBlocks 剥离全部嵌入块", () => { + const withBlock = + "hello\n\n\nfoo\n\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); + }); +}); diff --git a/tests/flash.test.ts b/tests/flash.test.ts new file mode 100644 index 0000000..8278fb0 --- /dev/null +++ b/tests/flash.test.ts @@ -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 { 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"); + }); +}); diff --git a/tests/glm-provider.test.ts b/tests/glm-provider.test.ts new file mode 100644 index 0000000..8f0888c --- /dev/null +++ b/tests/glm-provider.test.ts @@ -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; + 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: "" }); + 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"); + }); +}); diff --git a/tests/hardware-state.test.ts b/tests/hardware-state.test.ts new file mode 100644 index 0000000..d47247d --- /dev/null +++ b/tests/hardware-state.test.ts @@ -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, 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"); + }); +}); diff --git a/tests/hardware-verify.test.ts b/tests/hardware-verify.test.ts new file mode 100644 index 0000000..b7d8435 --- /dev/null +++ b/tests/hardware-verify.test.ts @@ -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): 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"); + }); +}); diff --git a/tests/jtag-debugger.test.ts b/tests/jtag-debugger.test.ts new file mode 100644 index 0000000..12a712b --- /dev/null +++ b/tests/jtag-debugger.test.ts @@ -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; + 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 }; + 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; + expect(b.x).toBe("2"); + const y = b.y as Record; + 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 }; + 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([]); + }); +}); diff --git a/tests/length-recovery.test.ts b/tests/length-recovery.test.ts new file mode 100644 index 0000000..ea52208 --- /dev/null +++ b/tests/length-recovery.test.ts @@ -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"); + }); +}); diff --git a/tests/loop-orchestrator.test.ts b/tests/loop-orchestrator.test.ts new file mode 100644 index 0000000..00671ee --- /dev/null +++ b/tests/loop-orchestrator.test.ts @@ -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"); + }); +}); diff --git a/tests/mcp-bridge.test.ts b/tests/mcp-bridge.test.ts new file mode 100644 index 0000000..e1687d8 --- /dev/null +++ b/tests/mcp-bridge.test.ts @@ -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 = { + 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); + }); +}); diff --git a/tests/pdf-reader.test.ts b/tests/pdf-reader.test.ts new file mode 100644 index 0000000..0a85bad --- /dev/null +++ b/tests/pdf-reader.test.ts @@ -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"); // 不被强转成十进制 + }); +}); diff --git a/tests/peripheral-probe.test.ts b/tests/peripheral-probe.test.ts new file mode 100644 index 0000000..0c15cbc --- /dev/null +++ b/tests/peripheral-probe.test.ts @@ -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 { 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 { + 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(""); + }); +}); diff --git a/tests/persistent-shell.test.ts b/tests/persistent-shell.test.ts new file mode 100644 index 0000000..744eae5 --- /dev/null +++ b/tests/persistent-shell.test.ts @@ -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((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((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); + }); +}); diff --git a/tests/safety-gate.test.ts b/tests/safety-gate.test.ts new file mode 100644 index 0000000..3b635fc --- /dev/null +++ b/tests/safety-gate.test.ts @@ -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"]); + }); +}); diff --git a/tests/server-runtime.test.ts b/tests/server-runtime.test.ts new file mode 100644 index 0000000..56f74d2 --- /dev/null +++ b/tests/server-runtime.test.ts @@ -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(); + }); +}); diff --git a/tests/subprocess-isolation.test.ts b/tests/subprocess-isolation.test.ts new file mode 100644 index 0000000..6b38025 --- /dev/null +++ b/tests/subprocess-isolation.test.ts @@ -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; + spawned: MockChild[]; +} { + const children = new Map(); + 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((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); + }); +}); diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..74116bb --- /dev/null +++ b/tsconfig.json @@ -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/**"] +} diff --git a/vitest.config.ts b/vitest.config.ts new file mode 100644 index 0000000..4eb0b3b --- /dev/null +++ b/vitest.config.ts @@ -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` }, + ], + }, +});