embedded-cross-review

嵌入式代码审查专家

概述

对嵌入式和固件变更进行结构化审查，重点关注内存安全、中断正确性、RTOS 使用、硬件接口、C/C++ 陷阱以及嵌入式安全。

首选审查策略是由两个独立子 Agent 进行交叉审查：分别检查同一份差异，然后比较发现，确认共识、遗漏和矛盾。

• 子 Agent A：嵌入式系统安全审查员 — 重点关注内存安全、中断正确性、RTOS 使用、硬件接口、C/C++ 陷阱以及嵌入式安全。
• 子 Agent B：测试终结者 — 执行捆绑文件 references/test-terminator-protocol.md 中的测试终结者协议（该文件是手动维护的 test-terminator 技能副本——子 Agent B 会读取文件，而不会调用其他技能）。将需求分解为测试场景矩阵（正常／边界／错误／时序／资源／恢复），并将其映射到代码路径，在真正的测试工程师发现之前找出覆盖缺口。

此技能刻意设计为与宿主环境无关：

• 不要硬编码 Claude Code、Codex、ACP 或任何特定供应商的运行时。
• 如果当前环境提供原生并行子 Agent 机制，请使用该机制。
• 如果环境支持模型选择，请为两个子 Agent 选择两个不同的高能力模型。
• 如果无法选择模型，仍要运行两个审查重点不同的独立子 Agent。
• 如果无法使用并行子 Agent，则退回到单 Agent 审查，并说明此环境无法进行交叉审查。

目标环境：裸机 MCU、RTOS（FreeRTOS/Zephyr/ThreadX）、嵌入式 Linux、混合 C/C++ 固件。

触发条件

当用户要求审查嵌入式或固件代码变更时启用。示例：

• “审查 firmware-pro2 变更”
• “审查 NFC 变更”
• /embedded-cross-review ~/Documents/dec/firmware-pro2
• /embedded-cross-review ~/Documents/dec/firmware-pro2 HEAD~5..HEAD
• /embedded-cross-review <github-pr-url>

严重级别

级别	名称	描述	操作
P0	严重	内存损坏、中断安全违规、安全漏洞、设备变砖风险	必须阻止合并
P1	高	竞态条件、资源泄漏、未定义行为、RTOS 误用	合并前应修复
P2	中	代码异味、可移植性问题、缺少错误处理、耦合过度、模式欠佳	修复或创建后续任务
P3	低	风格、命名、文档、轻微建议	可选改进

架构问题判定规则

• 当架构和耦合问题影响正确性、安全性、执行顺序、变更波及范围或可测试性时，应将其视为一类重要问题。不要把实质性的设计问题含糊地放在结尾备注中。
• 当耦合造成实际的正确性或安全隐患时，尤其是在 ISR／任务、驱动／应用、初始化／恢复或电源／复位路径上，应评为 P1。
• 当某个模块依赖本应仅通知它的具体使用方，混合了无关职责，或显然适合采用更小的边界（例如观察者、回调注册、事件队列、状态机、策略、适配器或依赖倒置）时，应评为 P2。
• 仅当问题属于局部清理且近期风险较低时，才评为 P3。

---

工作流

模式选择

单 Agent 模式：

• 用于小型差异（默认阈值：≤100 行）
• 用户明确要求快速审查时使用
• 宿主环境不支持并行子 Agent 时使用

交叉审查模式：

• 差异 >100 行时默认使用
• 新功能、架构变更和关键路径（ISR、DMA、加密、NFC、启动）优先使用
• 由两个独立的子 Agent 并行审查同一份内容
• 首要目标是提高审查的正确性和可信度，而非加快交付
• 如果宿主提供模型选择功能，请使用两个不同的高能力模型

用户可以覆盖此设置：“use a two-agent review” 或 “a quick review is fine”。

宿主能力规则

按以下顺序选择最佳可用执行模式：

1. 使用两个并行子 Agent，并明确指定不同的高能力模型
2. 使用两个并行子 Agent，采用相同模型，但使用不同的提示词和审查重点
3. 使用单 Agent 审查，并明确说明无法进行交叉审查

不要仅仅因为特定供应商的运行时不可用就中止。
不要以更快为由为较弱的模式辩解；审查质量应优先考虑。

阶段 0：预检 — 范围与上下文

1. 运行 scripts/prepare-diff.sh <repo_path> [diff_range]，提取以下信息：

• 仓库信息（分支、最近一次提交）
• 目标识别信息（MCU、RTOS、编译器）
• Diff 统计信息和完整 Diff 内容

2. 评估范围：

• 无更改：告知用户；提出可审核已暂存的更改或某个提交范围。
• 小型 Diff（≤100 行）：默认由单个 Agent 审核，除非用户要求交叉审核。
• 大型 Diff（>500 行）：不要把整个 Diff 和所有参考资料都塞进一个请求——这正是子 Agent 上下文溢出的原因。应用下方的令牌预算，按文件或子系统分批审核。
• 涉及关键路径（ISR、DMA、加密、NFC、启动）：强烈建议交叉审核。 令牌预算与分块（两个子 Agent 都必须遵守）：估算 diff + selected references + prompt 的大小，并与工作模型的上下文窗口进行比较，确保不超过预算（目标为窗口的 ≤60%，为子 Agent 自身的推理和输出留出空间）。如果超出预算，按文件或子系统拆分，并逐块审核——复用 test-terminator 的 [TT-SPLIT] 协议（每个块独立运行，然后对共享状态和接口进行跨块一致性检查）。绝不要为了适应预算而悄悄截断 Diff。

3. 构建审核上下文包。通过引用传递参考资料（按需加载），不要把完整文件塞进提示词——提供匹配的文件名和第 4 步中的触发规则，让每个子 Agent 仅打开所需部分：

REVIEW_CONTEXT = {
  repo_info: (branch, MCU, RTOS, compiler),
  diff: (full git diff text, or the current chunk if [TT-SPLIT] is active),
  references: (filenames of matched reference files — loaded on demand, not inlined wholesale),
  focus_areas: (user-specified or auto-detected critical paths),
  budget: (worker-model context window and per-request budget)
}

1. 按触发条件加载参考文件，不要盲目加载：

• 对 C/C++ Diff，始终加载 references/c-pitfalls.md，除非更改纯属文档或构建元数据。
• 当 Diff 涉及缓冲区、解析、memcpy/memset、字符串处理、栈分配、堆使用、DMA 缓冲区、紧凑结构体、指针强制转换或对齐敏感代码时，加载 references/memory-safety.md。
• 当 Diff 涉及 ISR、中断上下文中的回调、共享状态、volatile、临界区、原子操作、RTOS 任务/队列/信号量/互斥锁或任何可能并发运行的代码时，加载 references/interrupt-safety.md。
• 当 Diff 涉及外设初始化、时钟配置、GPIO 复用、MMIO 寄存器、DMA 配置、看门狗、复位/电源时序或 I2C/SPI/UART/NFC 等协议驱动时，加载 references/hardware-interface.md。
• 当 Diff 添加或重塑模块边界、跨层调用、回调/观察者注册、事件分发、状态机、功能分支或看起来用于通知或扇出的直接调用时，加载 references/architecture-maintainability.md。
• 此技能目前没有专门用于嵌入式安全的参考文件；请直接根据 Diff 和目标上下文进行审核。
• 如果 Diff 涉及多个类别，加载所有匹配的参考文件。
• 如果类别不明确、Diff 涉及安全关键内容或涉及关键路径，请查阅全部五个专用参考文件——但要按需加载（在处理每个审核领域时打开相关部分），不要预先将全部五个文件内联到一个提示词中。“查阅全部五个”指覆盖范围，而不是塞满上下文窗口；请遵守上述令牌预算。

---

阶段 1：单 Agent 审查

对于较小的差异，或未请求或无法进行交叉审查时：

审查前，使用阶段 0 的触发规则确定要加载哪些参考文件。不要假设每个较小的差异都需要加载所有参考文件，但要加载所有适用的文件。架构/可维护性和嵌入式安全始终需要审查；架构现在有专用参考文件，而嵌入式安全仍没有。

1. 内存安全扫描

• 当差异符合阶段 0 中的内存安全触发条件时，加载 references/memory-safety.md
• 栈溢出、缓冲区越界、对齐、DMA 缓存一致性、堆碎片
• 标记 sprintf、strcpy、gets、strcat；建议使用有界替代方案

2. 中断与并发正确性

• 当差异符合阶段 0 中的中断/并发触发条件时，加载 references/interrupt-safety.md
• 共享变量访问、临界区、ISR 最佳实践、RTOS 陷阱
• 优先级反转、可重入性、嵌套中断处理

3. 硬件接口审查

• 当差异符合阶段 0 中的硬件接口触发条件时，加载 references/hardware-interface.md
• 外设初始化顺序、寄存器访问、时序违规、引脚冲突
• I2C/SPI/UART/NFC 缓冲区管理和超时处理

4. C/C++ 语言陷阱

• 对任何非平凡的 C/C++ 代码审查，加载 references/c-pitfalls.md
• 未定义行为、整数问题、编译器假设、链接器问题
• 预处理器风险、可移植性、类型安全

5. 架构与可维护性

• 当差异符合阶段 0 中的架构触发条件时，加载 references/architecture-maintainability.md
• HAL/BSP 分层、抽象边界、耦合、状态所有权、可测试性
• 死代码、魔法数字、配置管理
• 检查直接调用是否用于实现通知、扇出、可选消费者或跨层访问；这些场景是否更适合使用观察者、回调注册、事件队列、状态机、策略、适配器或依赖倒置来表达
• 将可采取行动的耦合问题视为审查发现，而不只是备注；说明具体症状，以及可降低耦合的最小嵌入式友好型抽象

6. 嵌入式安全扫描

• 当前没有专用参考文件；直接根据差异和威胁面进行审查
• 密钥存储、调试接口、固件更新完整性
• 侧信道、故障注入、输入验证、栈保护

然后跳到阶段 3：输出。

---

阶段 2：使用两个子 Agent 进行交叉审查

触发交叉审查模式时，基于同一个 REVIEW_CONTEXT 创建两个审查任务。

步骤 1：定义不同的评审角色

使用能迫使评审者采用互补视角的提示词。

子 Agent A：嵌入式系统安全评审者

You are a senior embedded systems engineer reviewing firmware code changes.

## Review Context

**Repository Info**: [branch, MCU, RTOS, compiler]
**Diff**: [full git diff text]
**Focus Areas**: [user-specified or auto-detected critical paths]

## Reference Materials

Load reference files on demand per the Phase 0 trigger rules — `c-pitfalls.md` (always for C/C++), `memory-safety.md`, `interrupt-safety.md`, `hardware-interface.md`, `architecture-maintainability.md`. If the category is unclear, the diff is safety-critical, or a critical path is touched, consult all five.

## Review Areas

Apply these review areas when relevant:
- Memory safety
- Interrupt and concurrency correctness
- Hardware interfaces and timing
- RTOS correctness
- Embedded security
- Architecture and maintainability, including whether new code introduces hardcoded fan-out, cross-layer reach-through, unclear state ownership, or mixed responsibilities that should instead use a smaller boundary such as observer, callback registration, event queue, state machine, strategy, adapter, or dependency inversion

Architecture findings are first-class issues. If the code is materially over-coupled, do not downgrade it to a soft note just because it compiles.

## Output Format

For each finding:
[P0/P1/P2/P3] [file:line] Title
- Description
- Risk
- Suggested fix

For architecture findings, explicitly name the coupling symptom and the smallest alternative that would reduce it.

Flag uncertain findings with [?].

子 Agent B：测试终结者

子 Agent B 执行测试终结者协议：将需求分解为测试场景矩阵（正常／边界／错误／时序／资源／恢复），将每个场景映射到代码路径，并找出“代码未覆盖、但测试人员会遇到”的缺口——这是与 A 的嵌入式安全视角正交的维度。

执行（稳定、自包含）：加载并严格遵循此技能捆绑的 references/test-terminator-protocol.md。它是 test-terminator 技能的仓库内副本——子 Agent B 读取此文件来执行协议；它不会使用技能调用技能的方式（在某些宿主环境中，例如 n8n，这种方式不可靠）。该路径在此技能中固定为 references/test-terminator-protocol.md，因此无论技能安装在哪里，该路径都有效。向 B 传递相同的 REVIEW_CONTEXT，并使用其默认角色（🔴 测试执行者）；B 的判断顺序规则、[TT-SPLIT] 分块方式以及失败降级（[TT-PARTIAL]）都在该参考文件中定义。

如果宿主环境支持显式选择模型，请为 A 和 B 分配不同的高能力模型。此模式是首选，因为模型多样性有助于验证某项发现是否确实存在问题，而不是单一模型的幻觉或盲点。如果不支持，仍然要保持角色不同。

步骤 2：并行启动

使用宿主环境的原生子 Agent 功能，并发执行两项任务。

要求：

• 两个子 Agent 使用相同的 REVIEW_CONTEXT
• 独立执行
• 完成前互不可见对方的发现
• 优先并行执行，而非顺序执行

如果宿主环境只支持一个工作模型，仍然要让提示词保持不同。

步骤 2.5：编排者角色与子 Agent 失败处理

编排者（此技能，即启动 A 和 B 的 Agent）是汇总者和裁定者，而非第三位评审者。其职责是去重、统一严重性、指出矛盾并审查覆盖情况。编排者不得自行提出实质性发现，再悄悄将其并入结果，伪装成来自独立评审者的发现。编排者的任何观察都必须标记为 [orchestrator-note]，且绝不得计入共识，也不得用来替代失败的评审者。（让编排者自我评审，正是掩盖评审者失败的做法——不要这样做。）

完成不变量：只有当 A 和 B 都返回结构化发现时，一次运行才算完成交叉评审。如果任一子 Agent 失败——令牌数量超限、超时、崩溃，或输出为空／无法解析：

1. 先恢复：仅重新运行失败的一方，并缩减其输入内容——应用第 0 阶段的令牌预算，按文件／子系统拆分差异（复用 test-terminator 的 [TT-SPLIT]），和／或加载更少的参考文件。
2. 若仍然失败，则如实降级：使用成功的子 Agent，降级为单 Agent 后备方案。设置 Execution path = single-agent fallback (reviewer X failed: <reason>) 和 Confidence basis = degraded — NOT cross-validated。
3. 绝不要将降级运行报告为已完成的交叉评审。 如果有一位评审者未返回结果，不得声称“交叉评审已完成／覆盖完整／无需补充”。编排者自身的分析可以补充仍在工作的评审者，但不得替代失败的评审者。
4. 在最终报告中醒目地说明失败情况及其对置信度的影响——不要将其埋在结尾的备注中。

步骤 3：交叉对比结果

仅当 A 和 B 均已返回时执行（参见步骤 2.5 中的不变条件；否则采用降级路径）。对结果分类：

1. 共识结果：两个子 Agent 标记了基本相同的问题。将其视为高置信度结果。
2. 仅 A 发现：验证后，若技术上合理，则保留。
3. 仅 B 发现：验证后，若技术上合理，则保留。
4. 矛盾：一个子 Agent 认为正确，另一个认为有问题。明确指出，供人工判断。

将所有结果统一为 P0 至 P3 的严重性级别。

步骤 4：环境说明

说明使用了哪种交叉评审路径：

• two subagents, different high-capability models
• two subagents, same model with different prompts
• single-agent fallback (cross-review unavailable in this host)
• single-agent fallback (a reviewer failed mid-run — results NOT cross-validated) ← 如果 A 或 B 在启动后失败，请使用此项，而不要标记为“已完成”

这很重要，因为不同模式的置信度有所不同，用户应当知道评审结果是经过不同的强模型交叉验证、仅为近似验证，还是因评审者失败而降级。降级运行必须在此处明确说明，绝不能标记为已完成的交叉评审。

---

第 3 阶段：输出格式

## Embedded Code Review Summary

**Target**: [MCU/Board] | [RTOS/Bare-metal] | [Compiler]
**Branch**: [branch name]
**Files reviewed**: X files, Y lines changed
**Review mode**: [Single-agent / Cross-review]
**Execution path**: [two subagents, different high-capability models / two subagents, same model with different prompts / single-agent fallback (cross-review unavailable) / single-agent fallback (reviewer X failed mid-run)]
**Confidence basis**: [consensus across distinct strong models / consensus across role-separated same-model agents / single-agent judgment / degraded — NOT cross-validated, reviewer X failed]
**Overall assessment**: [APPROVE / REQUEST_CHANGES / COMMENT]

---

## Findings

### P0 - Critical (must block)
(none or list)

### P1 - High (fix before merge)
1. **[file:line]** Brief title [consensus / reviewer-A-only / reviewer-B-only]
   - Description of issue
   - Risk: what can go wrong
   - Suggested fix

### P2 - Medium (fix or follow-up)
...

### P3 - Low (optional)
...

---

## Test Terminator Coverage Report (reviewer-B only)

**Scenario-matrix coverage**: X/Y
**Gap counts**: P0=A, P1=B, P2=C, P3=D

### ⚔️ Battle Report (required whenever gaps remain)

**Lines held** (tests you defeated): N scenarios sealed ✅
**Breaches** (tests that beat you): M remaining ❌
**Defense ratio**: N held / M breached
**Terminator KPI grade**: [S/A/B/C/D/F] · title · one-line verdict (graded strictly; any unresolved P0 breach is an automatic F)
**Bounty waiting for the testers**: K high-probability gaps (detection probability > 80%, P0×a / P1×b) → estimated +Z to their KPI; what you let through today is the testers' KPI tomorrow

**Gaps most likely to be found by testers**:
1. [scenario] — [file:line] — trigger condition
2. [scenario] — [file:line] — trigger condition
3. [scenario] — [file:line] — trigger condition

**TT verdict**: [TT-PASS] / [TT-FAIL] / [TT-PARTIAL]
- [TT-FAIL] — there are P0/P1 gaps a tester would find; recommend blocking delivery
- [TT-PARTIAL] — an unreviewed chunk or a failed subagent left coverage incomplete; do not treat it as passing; list the uncovered scope
- [TT-PASS] — under the available evidence, all runnable acceptance checks pass and known high-risk gaps are fixed or explicitly disclosed

---

## Cross-Review Analysis

### Embedded Safety Findings (Reviewer-A: Embedded Systems Safety)

| Metric | Count |
|--------|-------|
| Consensus | X |
| Reviewer-A-only | Y |
| Reviewer-B-only | Z |
| Contradictions | W |

### Test Coverage Findings (Reviewer-B: Test Terminator)

| Metric | Count |
|--------|-------|
| Scenario-matrix coverage | X/Y |
| P0 test gaps | A |
| P1 test gaps | B |
| P2 test gaps | C |
| P3 test gaps | D |
| Gaps with tester-detection probability > 80% | E |
| Defense ratio (held / breached) | N held / M breached |
| Terminator KPI grade | [S/A/B/C/D/F] · title |

### Cross-domain overlaps
List findings where Reviewer-A's safety issue and Reviewer-B's test gap point at the same code (e.g. a buffer overflow that is both a security issue and a boundary-test gap). These overlapping findings carry the highest confidence.

### Notable disagreements
(list contradictions with both perspectives)

## Hardware/Timing Concerns
(register access, peripheral init, timing-sensitive code)

## Architecture Notes
(layering, testability, portability observations that did not rise to P1/P2)
(actionable coupling, responsibility split, or pattern-fit problems belong in Findings, not only here)

仅当实际使用了两个子 Agent，且二者都返回了结构化结果时，才包含 Cross-Review Analysis。如果 A 或 B 失败，则属于降级的单 Agent 后备方案，而非交叉评审——请按此报告（参见步骤 2.5），切勿标记为已完成的交叉评审。

---

重要：在用户明确确认之前，不要实施任何更改。