ECC Kiro Harness：rust-reviewer Agent 的 Rust 代码审查工作流深度解析

在 Everything Claude Code（ECC）仓库中，.kiro/agents/rust-reviewer.md 定义了 Kiro IDE/CLI 的专属 Rust 代码审查 Agent。本篇以该 Agent 定义文件为核心骨架，完整拆解其审查触发流程、按严重级别分层的检查清单、诊断命令集与审批判定标准，并结合仓库中的 JSON 镜像配置、配套 hook、steering 文件与 rust-patterns skill 源码，说明如何把这套"可执行清单"落地为一个可复制、可运行的 Rust 项目质量门禁方案。

rust-reviewer 是什么：Agent 定义与工具边界

.kiro/agents/rust-reviewer.md 是一个标准的 Kiro Agent 定义文件，由 YAML frontmatter 和提示词正文两部分组成。frontmatter 完整声明如下：

---
name: rust-reviewer
description: Expert Rust code reviewer specializing in ownership, lifetimes, error handling, unsafe usage, and idiomatic patterns. Use for all Rust code changes. MUST BE USED for Rust projects.
allowedTools:
  - read
  - shell
---

从这份元数据可以看出该 Agent 的三个设计要点：

• 职责定位：description 明确指出它是专精于所有权（ownership）、生命周期（lifetimes）、错误处理、unsafe 使用和惯用法模式的"资深 Rust 审查者"，并声明"所有 Rust 代码变更必须使用"——这是给上层 Agent 路由器的强制信号，确保 Rust 项目的 diff 不会被通用审查器草率放行。
• 最小工具权限：allowedTools 只授予 read 和 shell 两类能力。审查者需要 read 来读取源码与 diff，需要 shell 来运行 cargo check、clippy、test 等诊断命令，但不授予任何写文件工具——审查者只报告、不修改，这是"审查/实现职责分离"的典型设计。
• 无模型绑定：根据 .kiro/README.md 的说明，Kiro 中 Agent 使用的模型由当前会话的模型选择决定，而非 Agent 配置本身。这一点与根目录下的 Claude Code 版本形成对照，后文会展开。

Kiro 生态中 Agent 有两种分发格式，rust-reviewer 两者都提供了：

格式	文件	适用场景	访问方式
Markdown	.kiro/agents/rust-reviewer.md	Kiro IDE	自动选择或 /rust-reviewer 显式调用
JSON	.kiro/agents/rust-reviewer.json	kiro-cli	/agent swap 命令切换

JSON 镜像文件与 MD 文件共享同一份提示词正文（prompt 字段），差异在于工具声明方式：JSON 版写作 "allowedTools": ["fs_read", "shell"] 且 tools 为 "@builtin"，并带有空的 mcpServers、resources、hooks 字段。从源码结构看，fs_read 与 MD 版 frontmatter 中的 read 是同一语义在不同配置体系下的映射，而 JSON 结构额外预留了 CLI 侧的 MCP 与 hook 挂载点（CLI hook 格式可参考 .kiro/hooks/README.md 中的 postToolUse 示例）。

启动流程：先跑门禁，再看 diff

Agent 提示词开头定义了被调用时的五步固定流程（When invoked），这是整个审查工作流的"硬前置"：

1. 运行基础门禁命令：cargo check、cargo clippy -- -D warnings、cargo fmt --check、cargo test —— 任何一条失败，立即停止并报告，不进入逐行审查。
2. 获取审查范围：运行 git diff HEAD~1 -- '*.rs' 查看最近一次提交的 Rust 文件变更；PR 审查场景改用 git diff main...HEAD -- '*.rs'；若仓库是浅克隆或单提交历史导致 HEAD~1 失败，回退到 git show --patch HEAD -- '*.rs'。
3. 聚焦修改过的 .rs 文件，不扩散到未变更代码。
4. CI 前置检查：如果 CI 正在失败或存在合并冲突，停止审查并报告阻塞问题，在 CI 变绿、冲突解决之前不继续。
5. 开始审查，进入下文的分层检查清单。

这五步的设计逻辑值得注意：门禁命令放在 diff 之前，意味着 LLM 审查只在"机器可验证的基线是绿的"前提下才有意义——否则 clippy 的 200 条警告会淹没真正需要人工判断的所有权与安全问题。git diff 命令附带浅历史回退策略，也是针对真实仓库场景（CI 容器普遍使用 --depth 1 克隆）的工程化细节。

审查优先级：七层检查清单完整拆解

文档的主体是 Review Priorities，按 CRITICAL / HIGH / MEDIUM 三级共七个维度组织，总计 36 条检查项。完整继承如下，并补充每条背后的技术动机。

CRITICAL — 安全（Safety）

安全项是最高优先级，任何一条命中即构成 Block 理由：

• 生产代码路径中未检查的 unwrap()/expect() —— 应使用 ? 或显式处理。unwrap 在测试中合理，在生产路径中等于把 Result 契约换成了 panic。
• 无说明的 unsafe —— 每个 unsafe 块缺少记录不变量的 // SAFETY: 注释。注释是安全审计时证明"不变量成立"的唯一依据。
• SQL 注入 —— 用字符串插值拼接查询，应使用参数化查询（sqlx、diesel、sea-orm 等）。
• 命令注入 —— 未经验证的输入直接传入 std::process::Command。
• 路径穿越 —— 用户可控的路径未经 canonicalize 规范化和前缀校验。
• 硬编码密钥 —— 源码中的 API key、密码、token。
• 不安全反序列化 —— 对不可信数据反序列化时缺少大小/深度限制（Rust 侧典型风险是 serde 反序列化超深嵌套导致栈溢出）。
• 原始指针 use-after-free —— unsafe 指针操作缺少生命周期保证。

CRITICAL — 错误处理（Error Handling）

• 静默吞错：对 #[must_use] 类型使用 let _ = result;，编译器警告被人为压制。
• 错误丢失上下文：return Err(e) 直接透传而没有 .context() 或 .map_err() 补充发生位置。
• 用 panic 处理可恢复错误：生产路径出现 panic!()、todo!()、unreachable!()。
• 库中使用 Box<dyn Error>：库应使用 thiserror 定义类型化错误，anyhow 留给应用层——这条与仓库 steering 文件和 skill 的约定完全一致（见后文）。

HIGH — 所有权与生命周期（Ownership and Lifetimes）

• 不必要的克隆：为了绕过借用检查器而 .clone()，却不理解根因。
• 该用 &str 却收 String：函数参数在 &str 或 impl AsRef<str> 就够时索取所有权。
• 该用切片却收 Vec<T>：&[T] 足够时收 Vec<T> 增加了调用方负担。
• 缺少 Cow：本可用 Cow<'_, str> 避免分配的场景区区走了 Owned 分支。
• 生命周期过度标注：在省略规则（elision rules）适用的地方写显式生命周期，徒增阅读成本。

HIGH — 并发（Concurrency）

• 异步上下文中阻塞：std::thread::sleep、std::fs 出现在 async 任务中，应换用 tokio 等价物。
• 无界 channel：mpsc::channel() / tokio::sync::mpsc::unbounded_channel() 必须给出理由，优先使用有界 channel——无界缓冲是内存泄漏与背压失控的常见来源。
• 忽略 Mutex 毒化：不处理 .lock() 返回的 PoisonError。
• 缺少 Send/Sync 边界：跨线程共享的类型没有正确的 trait 约束。
• 死锁模式：嵌套获取锁时没有一致的加锁顺序。

HIGH — 代码质量（Code Quality）

• 超长函数：超过 50 行。
• 深层嵌套：超过 4 层。
• 业务枚举上的通配匹配：_ => 会掩盖未来新增的变体。
• 非穷尽匹配：需要显式处理的场景使用了 catch-all。
• 死代码：未使用的函数、导入或变量。

MEDIUM — 性能（Performance）

• 热路径上的不必要分配：to_string() / to_owned()。
• 循环内重复分配：循环体内反复创建 String 或 Vec。
• 缺少 with_capacity：已知大小却用 Vec::new()，应使用 Vec::with_capacity(n)。
• 迭代器中的过度克隆：借用语义足够时使用了 .cloned() / .clone()。
• N+1 查询：数据库查询出现在循环内。

MEDIUM — 最佳实践（Best Practices）

• 未处理的 Clippy 警告：用 #[allow] 压制却无说明理由。
• 缺少 #[must_use]：在忽略返回值很可能引发 bug 的返回类型上未标注。
• derive 顺序：应遵循 Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize。
• 公共 API 无文档：pub 项缺少 /// 文档。
• format! 滥用：简单拼接应使用 push_str、concat! 或 +。

检查清单与仓库规范的交叉印证

这份清单不是孤立的：.kiro/steering/rust-patterns.md 作为 inclusion: fileMatch、fileMatchPattern: "*.rs" 的 steering 文件，会在编辑任何 .rs 文件时自动加载，其中写下的规则与上面的 HIGH/CRITICAL 项逐条呼应——"接受 &str 优于 String、&[T] 优于 Vec<T>""不要为了绕过借用检查器而 clone""库用 thiserror、应用用 anyhow""生产代码永不 unwrap()"。也就是说，steering 文件在"写代码时"注入同一套约束，rust-reviewer 在"提交代码时"用同一套约束做验收，两者构成写前引导 + 写后门禁的闭环。

诊断命令集（Diagnostic Commands）

文档给出的完整诊断命令块如下，可直接复制到本地或 CI 中运行：

cargo clippy -- -D warnings
cargo fmt --check
cargo test
if command -v cargo-audit >/dev/null; then cargo audit; else echo "cargo-audit not installed"; fi
if command -v cargo-deny >/dev/null; then cargo deny check; else echo "cargo-deny not installed"; fi
cargo build --release 2>&1 | head -50

逐条说明：

• cargo clippy -- -D warnings：将 clippy 的所有 lint 提升为错误，对应清单中"MEDIUM — 未处理的 Clippy 警告"项的机器侧保障。
• cargo fmt --check：只检查不修改，保证 Agent 审查过程不产生副作用（与 allowedTools 只含 read/shell 的只读定位一致）。
• cargo test：全量测试基线。
• cargo audit / cargo deny check：依赖漏洞与供应链检查。注意命令中用 command -v 做了存在性探测，未安装时优雅降级为提示而非报错——这让命令块在非完整环境中也可安全运行。steering 文件 .kiro/steering/rust-patterns.md 也明确要求"在 CI 中运行 cargo audit 和 cargo deny check"。
• cargo build --release 2>&1 | head -50：截取 release 构建输出的前 50 行，用于观察优化相关警告，同时避免超大输出撑爆上下文窗口。

审批标准（Approval Criteria）

清单最终收敛为三值判定，这也是 Agent 输出必须遵循的结论格式：

判定	条件	含义
Approve	无 CRITICAL 或 HIGH 问题	变更可合入
Warning	仅存在 MEDIUM 问题	可合入但建议修复，通常记入后续任务
Block	发现任何 CRITICAL 或 HIGH 问题	阻断合入，必须先修复

这个三值模型让审查结论对 CI 友好：Block 可以映射为流水线失败，Warning 映射为非阻断的 annotation，Approve 放行——从文档结构看，它是为"Agent 输出直接驱动合入门禁"设计的。

配套生态：hook、skill 与跨平台镜像

rust-reviewer 在仓库中并非孤立文件，而是 Kiro harness 里 Rust 工具链的一环：

编辑期 hook：rust-check-on-edit

.kiro/hooks/rust-check-on-edit.kiro.hook 是一个 IDE hook，完整内容如下：

{
  "version": "1.0.0",
  "enabled": true,
  "name": "rust-check-on-edit",
  "description": "Prompts the agent to check for compilation errors, ownership issues, or lifetime problems when Rust files are edited.",
  "when": { "type": "fileEdited", "patterns": ["*.rs"] },
  "then": { "type": "askAgent", "prompt": "A Rust file was just saved. Check for any obvious compilation errors, ownership issues, or lifetime problems in the modified file and flag them if found." }
}

它监听 fileEdited 事件（*.rs 模式），动作类型为 askAgent——保存 Rust 文件后向 Agent 发一条提示，先做轻量级的编译错误/所有权/生命周期检查。与 rust-reviewer 的分工是：hook 负责保存时的即时轻检查，reviewer Agent 负责提交前/PR 时的全量分层审查。hook 的字段规范（version、enabled、name、description、when、then 六个必填项，以及 fileEdited/userTriggered/agentStop 等触发类型）详见 .kiro/hooks/README.md。

深度参考：rust-patterns skill

reviewer 文档末尾的 For detailed Rust code examples and anti-patterns, see 'skill: rust-patterns' 指向 .kiro/skills/rust-patterns/SKILL.md（499 行）。清单里的抽象条目在该 skill 中都有可运行的代码对照，例如：

// 来自 rust-patterns skill：Cow 用于灵活所有权（对应 HIGH — 缺少 Cow）
use std::borrow::Cow;

fn normalize(input: &str) -> Cow<'_, str> {
    if input.contains(' ') {
        Cow::Owned(input.replace(' ', "_"))
    } else {
        Cow::Borrowed(input) // Zero-cost when no mutation needed
    }
}

// 来自 rust-patterns skill：库错误用 thiserror，应用错误用 anyhow
// （对应 CRITICAL — Box<dyn Error> in libraries）
use thiserror::Error;

#[derive(Debug, Error)]
pub enum StorageError {
    #[error("record not found: {id}")]
    NotFound { id: String },
    #[error("connection failed")]
    Connection(#[from] std::io::Error),
    #[error("invalid data: {0}")]
    InvalidData(String),
}

skill 还给出了 Result/? 传播的反例对照（生产代码 unwrap 会 panic）、Option 组合子替代嵌套匹配等内容，是审查者判断"是否惯用"时的判例库。

跨平台镜像：Claude Code 版 rust-reviewer

仓库根目录的 agents/rust-reviewer.md 是同一 Agent 面向 Claude Code 的镜像版本。两者清单正文基本一致，关键差异在 frontmatter 与安全基线：

---
name: rust-reviewer
description: Expert Rust code reviewer ...
tools: Read, Grep, Glob, Bash
model: sonnet
---

• 工具集从 Kiro 版的 read/shell 扩展为 Read, Grep, Glob, Bash，并显式绑定 model: sonnet（Kiro 版则由会话模型决定）；
• 提示词前置了一段 Prompt Defense Baseline：不改变角色与身份、不泄露机密、不输出未经验证的可执行内容、将外部/URL/不可信数据视为不可信输入等。这段防御性指令是跨 harness 分发时注入的，属于 ECC 多平台 Agent 的通用安全层；
• 启动流程第 4 步的措辞略有不同：Kiro 版写的是"CI 失败或合并冲突存在时 STOP 并报告"，Claude Code 版改为"若 diff 暗示 CI 未绿或冲突未解，明确指出"。从源码结构看，两者是同一策略在不同工具能力下的表述适配。

另外，Kiro 版的启动流程还比 Claude Code 版多了一条 git diff 的浅克隆回退策略（git show --patch HEAD -- '*.rs'），可见各平台版本会根据实际运行环境做增量维护。

安装与调用方式

ECC 的 Kiro 组件通过 .kiro/install.sh 一键安装，采用非破坏性复制（目标文件已存在则跳过，不覆盖用户定制）：

cd .kiro

# 安装到指定项目
./install.sh /path/to/your/project

# 或安装到当前目录
./install.sh

# 或全局安装（作用于所有 Kiro 项目）
./install.sh ~

安装脚本按 agents、skills、steering、hooks、scripts、settings 六个子目录分别复制，rust-reviewer 的 .md 与 .json 两个文件都会进入 agents/。安装完成后：

• Kiro IDE：在会话中用 / 菜单选择 rust-reviewer 触发；rust-check-on-edit hook 会出现在 Agent Hooks 面板并可随时开关；编辑 *.rs 文件时 rust-patterns.md steering 文件自动加载。
• kiro-cli：/agent swap rust-reviewer 切换，或启动时指定 kiro-cli --agent rust-reviewer。

按 .kiro/README.md 的推荐工作流，rust-reviewer 处于"实现完成之后、提交之前"的位置：先用 planner 拆解功能、tdd-workflow 先行写测试，实现后切换到 rust-reviewer 审查，再触发 quality-gate hook 与 verification-loop skill 做最终验证。

小结

.kiro/agents/rust-reviewer.md 的价值在于把"资深 Rust 审查者"这一角色压缩为一份可执行、可门禁化的规格：五步启动流程保证审查永远建立在绿色基线与最小 diff 上；36 条检查项按 CRITICAL/HIGH/MEDIUM 三级收敛为 Approve/Warning/Block 三值结论；cargo 诊断命令块兼顾了完整性与环境探测降级。再配合 JSON 镜像、编辑期 hook、fileMatch steering 与 rust-patterns skill，ECC 的 Kiro harness 为 Rust 项目构建了"写前引导—保存轻检—提交分层审查—三值门禁"的完整质量回路。对于维护 Rust 代码库的团队，可以直接以该文件为模板，把团队自己的安全与性能约定追加进 Review Priorities，即可获得一个行为可预期的 Agent 审查器。