v1.24.2：作者「周衡」+ 市场文案重写

嵌入式工具箱 v1.24.2：署名与市场文案（patch）

统一作者名为「周衡」，并把五个技能的市场能力介绍改成招揽式文案：痛点开头 + 硬指标
（12 树/77 节点、148 坑、37 计算器）+ 差异化（带出处、不编造、全离线），便于在
WorkBuddy / Trae 等市场展示。

变更

• 作者：liujycode → 周衡（5 个 SKILL.md、plugin.json、打包脚本同步）
• 能力介绍（description_zh / description_en）重写为痛点 + 硬指标 + 差异化的市场文案
• 插件版本 1.24.2；技能内容与检索数据不变

验证

• 门禁全绿：475 项测试、仓库检查、知识库校验
• 上架包（对外 1.0.0）已重打，包内作者/文案与仓库一致
• 打包器补 YAML 解析兜底：frontmatter 非法时报告问题而不是崩栈

安装（不变）

• Claude Code：/plugin marketplace add liujycode/embedded-toolkit 后 /plugin install embedded-toolkit@embedded-toolkit
• 其他 Agent：npx skills add liujycode/embedded-toolkit

v1.24.1：首跑体验修正（--help 示例）

嵌入式工具箱 v1.24.1：首次使用体验修正（patch）

三个新技能（决策树 / 避坑清单 / 时序计算器）补 --help 使用示例，修掉"新人装上后
不知道第一条命令怎么敲"的首跑断点；版本号 patch 递增（trees 1.3.1 / pitfalls 1.2.1 /
timing-calc 1.1.1），内容与检索数据不变。

变更

• --help epilog 增加可复制的示例命令（search/show/list/demo 等常用路径）
• 版本：debug-trees 1.3.0→1.3.1、peripheral-pitfalls 1.2.0→1.2.1、timing-calc 1.1.0→1.1.1
• 插件版本 1.24.1

验证

• 门禁全绿：475 项测试、检索评测 241/241=100%（p@1 96.7% / MRR 97.9%）
• 上架包（对外版本 1.0.0）内容与仓库逐字节一致

安装（不变）

• Claude Code：/plugin marketplace add liujycode/embedded-toolkit 后 /plugin install embedded-toolkit@embedded-toolkit
• 其他 Agent：npx skills add liujycode/embedded-toolkit

v1.24.0：五技能统一版（12 树/77 节点 · 25 类 148 坑 · 37 个计算器）

嵌入式工具箱 v1.24.0：五技能统一版（查/验/修/防/算）

五技能全部入仓并统一版本：寄存器查询 1.11.1、寄存器核验 1.16.2、排障决策树 1.3.0、
外设避坑清单 1.2.0、时序计算器 1.1.0。本版把此前的知识技能全覆盖轮（原 v1.23.0 计划内容）
与时序计算器入库合并发布，并包含一轮全量体检修复。

一、时序计算器 1.1.0 入库（37 个计算器）

• 覆盖 UART BRR、定时器 PSC/ARR、I2C 上拉/耗时、CAN 位时序、ADC 源阻抗、SPI、Nyquist、
  死区、FPGA（UART/slack/PWM/I2C/消抖/CDC/FIFO）、看门狗、PLL、分压、NTC、RC、晶振 ppm、
  ESP32/RP2040 时钟、PWM 调光、WS2812、舵机、步进、RTC 漂移、USB 48MHz、电池、Modbus、
  Flash 寿命、传感器 LSB。
• 审查单 R1-R3 修复：
  • I2C Rp(max)：std/fast/Fm+ 统一 tr/(0.8473×Cb)；Hs-mode 是电流源上拉，明确报
    E_UNSUPPORTED，不再套无源公式。
  • CAN 位时序：新增 --family {bxcan,fdcan}；bxCAN 每位最多 25 TQ（TSEG1≤16/TSEG2≤8），
    超出直接报错，避免 F1/F4 上"算得出配不出"的假 PASS。
  • ADC 源阻抗：改用 datasheet 的 ts/(Cs×ln(2^(N+2)))−Radc 口径（整定 1/4 LSB），
    支持 --radc 扣减并注明未扣时的偏差。
• 其余修正：USB 48MHz 分频链、sensor-lsb 双极性默认、RTC 负 ppm、分压电流口径、
  RP2040 UART 16+6 位分频、WS2812 低电平可选校验、Flash 记录页模型。

二、排障决策树 1.3.0：12 棵 / 77 节点

• 新增 FPGA/RTL 树（8 节点）：综合后行为异常、参数漏透传（silent default）、
  复位循环杀 RAM 推断、跨时钟域、I2C clock stretching、非阻塞赋值旧值、
  实测数值 vs 设计缺陷、回归归因。
• 保留并合入既有 11 棵：HardFault / 通信 / DMA / RTOS / 启动 / 低功耗 / CAN / USB /
  Flash / RTC / 显示与触摸；节点带 see 树间跳转。
• 节点 refs 只引公开文档名（IEEE Verilog LRM、Gowin Synthesis/Timing 指南、
  Cummings CDC/FIFO 论文等），不编造章节页码。

三、外设避坑清单 1.2.0：25 类 / 148 坑

• 13 个新类：DMA / USB / Flash / RTC / DAC / CRC / MPU / DBG / 以太网 / SD 卡 /
  C 语言与编译器 / 链接脚本 / Modbus / 传感器总线，另补电机外设配置坑。
• refs 148/148：每条都有文档级依据；next 字段把时序/阈值类问题引导到
  embedded-timing-calc 的可执行命令。
• 修正：USB 设备描述符长度口径、MPU 背景区域语义（PRIVDEFENA）。

四、寄存器查询 / 核验修复

• lookup 1.11.1：SVD 寄存器包含关系判定、lint 重叠区间扫描、枚举
  enumeratedValues usage 读/写分组（缓存格式升 2，旧缓存自动失效）、字段级
  readAction 提示、配置 UTF-8 BOM 兼容、ETK_SVD_DIR 上限与截断告警。
• verify 1.16.2：有"报"结果时退出码为 1（此前恒 0，CI 无法拦截）；E05 显式枚举
  优先于 isDefault 默认值；E09/E11 补丁模式按全文件判关系、只归属补丁行；
  时钟使能必须早于首次外设访问。

五、检索与评测

• 修正评测量具：此前评测未按分数排序就比对，排名指标失真；统一排序后重新定基线。
• 检索评测 241/241 = 100%（树场景 + 坑场景），p@1 96.7%，MRR 97.9%。
• 475 项测试全绿；check_repo.py、knowledge_check.py（schema + 同源）、
  五技能 demo 探针全部通过。
• 触发评测：触发率强依赖路由模型。v1.2.0 轮（deepseek_for_coding）决策树 52.5%、
  避坑 14.3%、反例零误触发；v1.3.0 FPGA 抽测（deepseek-v4-flash，10 例）正例 1/7、
  反例 3/3 未触发（n03 超时按未触发计）。强编码模型偏向直接作答，详见
  benchmarks/trigger-results-trees.md。

六、工程

• 上架打包器新增脏树拒绝：五个技能目录只要有一个未提交就拒绝出包。
• 五技能版本、plugin 1.24.0、README、references 与评测记录同步。
• timing-calc 输出统一 UTF-8，修复 GBK 控制台上 µ 字符导致的崩溃。

七、安装

• Claude Code：/plugin marketplace add liujycode/embedded-toolkit 后
  /plugin install embedded-toolkit@embedded-toolkit
• 其他 Agent：npx skills add liujycode/embedded-toolkit

嵌入式工具箱 v1.22.1：知识技能触发描述 A/B 优化

两个知识技能完成真机触发 A/B 优化（同模型 glm-5.3-flash，同用例同管线）：

• 决策树 49% → 59%、避坑清单 38% → 47%：SKILL.md description 重构为中文症状句前置（"程序跑飞/串口乱码/DMA 丢数据…"），救回全部通信/启动类症状用例；反例 32/32 全程零误触发
• 结论记录：触发率强依赖路由模型（deepseek-v4-flash 参照轮 95%）；检索评测 106/106 与技能命令行为与模型无关
• 评测原始转录不入库（.gitignore），仅保留汇总 �enchmarks/trigger-results-trees.md（含逐例漏报分析）

查/验/决策树/避坑 四技能当前版本：1.11.0 / 1.16.1 / 1.1.0 / 1.1.0。

嵌入式工具箱 v1.22.0：知识技能并入与深化（决策树 v1.1.0 / 避坑清单 v1.1.0）

嵌入式工具箱 v1.22.0：知识技能并入与深化（debug-trees v1.1.0 / peripheral-pitfalls v1.1.0）

工具箱从"查 + 验"扩成四个技能：新增的排障决策树与外设配置坑清单两个知识技能
并入本仓库，按与查/验相同的质量标准完成深化与量化验收。

一、并入工具箱仓库

• skills/embedded-debug-trees、skills/embedded-peripheral-pitfalls 与查/验两技能同仓：
  同一套质量门（SKILL.md 规范、触发用例正 ≥20 反 ≥10、仅标准库、禁 eval/exec、Python 3.9 语法）、
  同一条 CI（三平台 × Python 3.9/3.12）；npx skills add liujycode/embedded-toolkit 一次装四个。

二、内容扩容

• 排障决策树 5→6 棵、24→39 节点：新增"低功耗与唤醒"整树（睡死叫不醒/唤醒后时钟回落/
  进不了低功耗/调试器影响）；HardFault 补 FPU/NOCP 与 LOCKUP 双重故障；通信补 RS485 方向切换
  时机（等 TC 再切，TXE 不行）；DMA 补 DMAMUX 请求映射；RTOS 补时基没跑（vTaskDelay 卡住）；
  启动失败补 SWD 连不上（Connect under Reset）。
• 外设避坑清单 9→11 类、38→61 坑：新增低功耗 PWR（唤醒时钟/唤醒标志/SRAM 保持/引脚漏电）
  与看门狗 WDG（调试冻结/喂狗路径/WWDG 窗口/选项字节硬件看门狗）两类；既有九类补 EXTI 线映射
  （EXTICR）、NVIC 两层使能、定时器 CEN、多定时器主从同步、ADC 序列长度与"带使能校准"顺序、
  RS485 方向、I2C 超时恢复、SPI 软件片选、CAN 环回自测与 FDCAN 内核时钟等 23 坑。

三、检索质量（对 AI 使用最关键）

• 中文整句反向关键词匹配：中文不做分词，"任务卡死""定时器周期不对"这类整句查询通过
  "节点关键词出现在查询串"反向命中——不再要求查询恰好包含关键词。
• 全命令 --format json；search --tree/--category 限定范围；demo 升级为检索探针自检
  （14 条典型症状必须命中对应树/类）。
• 两脚本补 stdout UTF-8 输出重配置（管道/Agent 场景不再乱码）。

四、量化验收（与查/验同标准）

• tools/knowledge_check.py：schema 校验（必填字段/唯一 id/keywords 非空）+ references 与
  JSON 同源（references/trees.md、pitfalls.md 由 JSON 自动生成，杜绝手抄漂移）。
• tools/knowledge_bench.py：检索评测 106/106 = 100%（46 条决策树场景 + 60 条坑位场景，
  逐条 ground truth，被测代码 = 技能脚本里的检索函数本体）；CI 强制；结果见
  benchmarks/knowledge-recall.md。
• tests/test_knowledge.py 5 项（schema/评测/CLI 自检/JSON 输出/版本一致）；全仓 410 项测试全过。
• 诚实化："覆盖 80% 故障面"改为具体覆盖描述；根因排行标注"按实战经验排序（非实测统计）"。

五、安装（不变）

• Claude Code：/plugin marketplace add liujycode/embedded-toolkit 后 /plugin install embedded-toolkit@embedded-toolkit
• 其他 Agent：npx skills add liujycode/embedded-toolkit

嵌入式工具箱 v1.21.1：交付体检修正（verify v1.16.1 / lookup v1.11.0）

嵌入式工具箱 v1.21.1：交付体检修正（verify v1.16.1 / lookup v1.11.0）

这一版是"上架前全面体检"的修正版：修掉 1 个规则误报、补齐闭环提示、消除静默与陈旧文案。
功能面（查/验能力）与 v1.21.0 相同，行为更严谨。

一、E13 覆盖判定修正（重要）

• 初版 E13（v1.16.0）只要"寄存器含写 1 清零（oneToClear）位域"就报——体检时正样本集
  EXTI->PR |= EXTI_PR_P0 | EXTI_PR_P1;（唯一 W1C 位 P0 已被掩码提到）被误报。
• 修正为只有当写 1 清零位未被本次写入掩码覆盖时才报：读改写会把"没被掩码提到、但当前
  已置位"的标志顺带清零（写 1 = 清零），这才是真正会丢中断的情形；掩码明确提到的位是代码
  本意要动的，不算误伤。
  • 会报：UART0->UARTICR |= 0x10;（UARTICR 有 TXIC/RTIC 两个 W1C 位，只提到 TXIC）；
    EXTI->PR |= EXTI_PR_P0;（P1..P15 未提到）。
  • 不会报：UART0->UARTICR = 0x10;（直写）；UART0->UARTICR |= TXIC_Msk | RTIC_Msk;
    （掩码覆盖全部 W1C 位）；ADSR |= ADF_Msk;（唯一 W1C 位被提到）。
  • 未判定：读改写掩码无法静态求值（如 REG |= flags; 变量）——无法确认覆盖范围，不猜。
• 正样本集回到 0 报（55 文件 117 处写入）。

二、闭环提示（lookup v1.11.0）

• lookup 寄存器视图新增"读改写提示"：写 1 清零寄存器会显示"读改写会把读回时已置位的标志
  一并写回（写 1 = 清零），可能顺带清掉没提到的标志；清标志请直写目标标志"——与核验器 E13
  的 next 命令（"查看该寄存器的写语义"）形成闭环。
• decode --write / set 的 oneToClear 提示同步精确化（原为通用"可能误改状态位"）。

三、消除静默与陈旧文案（verify v1.16.1）

• --define 坏值不再静默：值明显无法求值（不含任何标识符 → 不可能引用其它宏）时给警告
  "该宏按未定义处理"。
• verify rules、verify --help、README 的"E01–E11"陈旧文案全部更新为"E01–E13"。

四、全面体检记录（交付上架前）

• CLI 边界矩阵 50 用例：两工具全部子命令 + 异常输入（文件/SVD 不存在、SVD 是目录、
  非 XML/截断 SVD、无参数、未知子命令、坏地址/坏值、字段不存在、坏 --headers、坏
  --define、空文件、BOM+CRLF、GBK 注释、中文/空格路径、空目录、补丁文件不存在）——
  退出码与 JSON 有效性全部符合预期，错误信息带 [E_*] 代码与提示。
• 闭环命令逐字执行：E13 finding 的 next（结构化 {tool, args, reason}）逐字跑通，
  lookup 输出写语义与读改写提示。
• 安装副本：中性目录运行正常（无 cwd 依赖）。
• 交付文件扫描：无绝对路径泄漏（D:\ / C:\Users）、无 eval/exec/compile 等禁用 API、
  仅标准库。
• 语料零回归：九生态（ESP-IDF 224/0/34/190、TI 363/0/300/63、libopencm3 366/3/287/76、
  AVR 33/0/2/31、SAMD 49/0/22/27、Renesas 36/0/26/10、Silabs 309/0/218/91、NXP 3/0/1/2）+
  pico-sdk 47/0/14/33 全部与上版一致。
• 405 项测试全过；召回 229/229；性能 0.030s/1000 行（目标 ≤ 2.0s）。

安装（不变）

• Claude Code：/plugin marketplace add liujycode/embedded-toolkit 后 /plugin install embedded-toolkit@embedded-toolkit
• 其他 Agent：npx skills add liujycode/embedded-toolkit

嵌入式工具箱 v1.21.0：E13 + pico-sdk 生态（verify v1.16.0）

嵌入式工具箱 v1.21.0：E13 + pico-sdk 生态（verify v1.16.0）

这轮把"写 1 清零"（oneToClear）语义的规则补上（E13），并自己抓了 pico-sdk 真实语料做探雷，
顺带支持了 RP2040/pico-sdk 的三种真实写法。

一、E13：写 1 清零寄存器上的读改写

• SVD 带 modifiedWriteValues="oneToClear"（寄存器级或位域级）时，读改写（|=/&=/^=/
  SET_BIT/CLEAR_BIT/MODIFY_REG/REG_SET_FIELD/REG_CLR_FIELD）会先读回寄存器（已置位
  标志为 1）、再整体写回——写 1 即清零，于是当前所有已置位的标志都被清零（包括并非本意
  清除的那些；若对应其它中断源，可能丢中断）。
• 真阳性示例（真实 RP2040 SVD）：

  UART0->UARTICR |= 0x10;   /* E13：会把当前已置位的所有中断标志清零 */
  UART0->UARTICR = 0x10;    /* 正确：直写目标标志 */
  

• 与 E10/E12 同口径：条件编译块内记未判定；只写寄存器走 E12；无 modifiedWriteValues 数据时
  不猜、不报。

二、pico-sdk 2.1.0 语料（RP2040）

• 抓取 pico-sdk 2.1.0，选 22 个含寄存器写入的源文件（uart/gpio/dma/timer/clocks/flash/i2c/spi/
  adc/pwm/irq/pll/xosc/watchdog/ticks/time/rtc/rand/multicore/…），配 RP2040 官方 SVD + SDK
  头文件核验：47 处写入 → 0 报、33 通过、14 未判定。
• 过程中修掉 1 个真实误报：clocks_hw->resus.ctrl（SDK 的嵌套结构体名 ↔ SVD 的扁平名
  CLK_SYS_RESUS_CTRL）→ 新增"下划线拼接名后缀唯一匹配"；匹配不到唯一寄存器时改记
  "多段成员名"未判定（不再误报 E02）。

三、pico-sdk 写法支持

• 小写指针宏按地址解析：#define dma_hw ((dma_hw_t *)DMA_BASE) → dma_hw->intr 核到 DMA.INTR；
• _u() 单参数拼贴宏：#define _u(x) x ## u → _u(0x50000000) 求值成功（地址链路打通）；
• 运行时下标（io_bank0_hw->intr[gpio / 8]、clocks_hw->clk[gpclk].ctrl）照常记未判定。

四、顺带修掉的一个误报类：MODIFY_REG 带位置取值

• ST 风格 MODIFY_REG(reg, Msk, VALUE << Pos)（置位值带位置）此前会误报 E04（"值超出位域宽度"）
  ——现在字段相对与带位置两种约定都接受，位域之外置位才报；唯一字段 + 字段相对取值时跳过
  只读位扫描（避免错位误报）。

五、实测

• 九生态语料复测零回归（ESP-IDF 224/0/34/190、TI 363/0/300/63、libopencm3 366/3/287/76、
  AVR 33/0/2/31、SAMD 49/0/22/27、Renesas 36/0/26/10、Silabs 309/0/218/91、NXP 3/0/1/2）；
• 404 项测试全过（新增 E13×2、MODIFY_REG 带位置用例）；召回 229/229 保持；正样本 55 文件 0 误报。

安装（不变）

• Claude Code：/plugin marketplace add liujycode/embedded-toolkit 后 /plugin install embedded-toolkit@embedded-toolkit
• 其他 Agent：npx skills add liujycode/embedded-toolkit

嵌入式工具箱 v1.20.0：细节深化 III（verify v1.15.0）

嵌入式工具箱 v1.20.0：细节深化 III（verify v1.15.0）

继续补细节缺口：把"值求值"扩到 C/C++ enum 常量，把补丁模式的文件级检查做对。

一、C/C++ enum 常量求值

• 文件内与 --headers 头文件里的 enum 常量现在参与数值核验：
  • enum { MODE_FAST = 0x2, MODE_SLOW, MODE_MAX = 0x10000 }; → MODE_SLOW 按 C 语义自增为 3；
  • typedef enum { ... } name_t;（头文件常见形式）同样识别；
  • #define 优先于同名 enum 常量；某表达式算不出时，其后的隐式项跳过（不猜）。
• 效果：现代 HAL 风格"用 enum 常量写寄存器"（TIM1->CR1 = LEVEL_HIGH;）不再进"未判定"，
  值超宽（E04）等检查得以生效；此前只能记"无法映射的标识符"。

二、补丁模式整文件上下文（修一类误报）

• 此前 --patch 把 diff 还原成"只含新增行"的合成文本再核验——文件级检查（E06/E07/E11）
  看不到未改动的时钟使能/置位，会误报（例如新增一行 USART1 写入，而开时钟在没改的那几行里）。
• 现在：磁盘上有完整文件时（按当前目录与补丁所在目录查找），文件级上下文取自整文件，
  只对新增行出结论；行号仍按新文件对齐。
• 找不到完整文件时明确提示："文件级检查看不到未改动的上下文，可能有误报；建议在仓库目录内
  运行或加 --no-clock-check"。

三、实测

• 九生态语料复测零回归（ESP-IDF 224/0/34/190、TI 363/0/300/63、libopencm3 366/3/287/76、
  AVR 33/0/2/31、SAMD 49/0/22/27、Renesas 36/0/26/10、Silabs 309/0/218/91、NXP 3/0/1/2）；
• 401 项测试全过（新增 enum 常量 ×2、补丁上下文 ×2 用例）；召回 229/229 保持；
  正样本 55 文件 0 误报。

安装（不变）

• Claude Code：/plugin marketplace add liujycode/embedded-toolkit 后 /plugin install embedded-toolkit@embedded-toolkit
• 其他 Agent：npx skills add liujycode/embedded-toolkit

嵌入式工具箱 v1.19.1：文本汇总消歧（verify v1.14.1）

嵌入式工具箱 v1.19.1：文本汇总消歧（verify v1.14.1）

端到端实测发现的小补丁：文本汇总行里"报 N"按写入数统计、括号里按问题条数统计，
一处写入命中多条问题时数字对不上（如 报 2（E03 1、E12 2）——2 与 1+2=3 看着矛盾）。

修复

• 多处命中时写明：报 2（3 条问题：E03 1、E12 2）；
• 单问题时保持原样（报 1（E05 1）），不增加噪音。

实测

• 397 项测试全过（E12 用例补文本汇总断言）；九生态语料零回归；召回 229/229 保持。

安装（不变）

• Claude Code：/plugin marketplace add liujycode/embedded-toolkit 后 /plugin install embedded-toolkit@embedded-toolkit
• 其他 Agent：npx skills add liujycode/embedded-toolkit

嵌入式工具箱 v1.19.0：细节深化 II（verify v1.14.0 / lookup v1.10.0）

嵌入式工具箱 v1.19.0：细节深化 II（verify v1.14.0 / lookup v1.10.0）

继续补细节缺口：这轮把 E12（只写寄存器读改写）的形态补全，并把 SVD 的"读语义"用起来。

一、verify v1.14.0：E12 补齐读改写形态

• MODIFY_REG：先读回、改掩码位、再写回——同样是读改写，此前 op（modify_reg）不在检查
  列表里，只写寄存器上的 MODIFY_REG 会被漏报；现在会报。
• REG_CLR_FIELD：op 名（clear_field）与检查列表里的 clr_field 拼写不一致，此前不报；
  现在与 REG_SET_FIELD 一起覆盖（地址可解析时）。
• 报告里的形态名显示为规范宏名：对只写寄存器 PORTX.BSRR 做读改写（MODIFY_REG）…。
• 文件类型收集补 .hxx（目录模式与 --headers 头文件扫描）。

二、lookup v1.10.0：读语义提示与宏生成细节

• readAction=modifyExternal（读后由硬件修改）：decode --write / set 给出读改写提示
  ——"读改写（reg |= x）会把读取时的外部变化一并写回，轮询与读改写需谨慎"。覆盖
  Silicon Labs / XMC / nRF 等带该语义的 SVD（此前只提示 modifiedWriteValues 一类）。
• macros 默认项说明：isDefault 枚举默认项输出为"默认项 X：其余取值（不生成宏）"，
  不再误写成"含任意位（模式 xx）"的位模式注释。

三、实测

• 九生态语料复测零回归（ESP-IDF 224/0/34/190、TI 363/0/300/63、libopencm3 366/3/287/76、
  AVR 33/0/2/31、SAMD 49/0/22/27、Renesas 36/0/26/10、Silabs 309/0/218/91、NXP 3/0/1/2）；
• 397 项测试全过（新增 MODIFY_REG/REG_CLR_FIELD 的 E12 用例、读语义提示用例、.hxx 收集用例、
  默认项宏注释用例）；召回 229/229 保持；正样本 55 文件 0 误报。

安装（不变）

• Claude Code：/plugin marketplace add liujycode/embedded-toolkit 后 /plugin install embedded-toolkit@embedded-toolkit
• 其他 Agent：npx skills add liujycode/embedded-toolkit