workerd 风格评审子代理规范review-style.md 的职责边界、工作流与输出约定【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd导读本文剖析 workerd 仓库The JavaScript / Wasm runtime that powers Cloudflare Workers中 AI 代码评审体系里负责风格与编码约定专项评审的子代理定义文件 .opencode/agent/review-style.md。该文件是一个单一评审轴Single-axis子代理的完整配置与提示词它定义了评审者只关注 KJ/C、Rust、TypeScript 三类语言的编码约定并规定了它的职责边界、评审方法、workerd 项目特有约定、输出格式与严重级别上限。读完本文你将掌握 workerd 评审 fan-out 架构中风格评审轴的完整工作方式包括如何按文件类型分派风格指南、如何撰写结构化 finding、以及空结果也是成功结果的输出纪律。一、定位fan-out 评审流水线中的风格专项在 workerd 仓库中代码评审由编排代理 .opencode/agent/code-review.md 负责默认采用平衡评审balanced review模式当变更同时命中多个评审轴safety、api、style时编排者会把各轴并行分派给独立的子代理而 review-style 就是其中负责风格的一路。三个评审轴的职责划分如下以 .opencode/agent/review-safety.md 与 .opencode/agent/review-api.md 为证子代理评审轴覆盖范围review-safety内存安全、线程安全、生命周期、V8/GCC 与 Rust 双方review-api性能、API 设计、向后兼容、安全、标准合规公开 API 表面review-styleKJ/C、Rust、TypeScript 编码约定按文件类型分派风格指南review-style 的 frontmatter 明确声明了它的两个核心属性mode: subagent——它是被编排代理调起的子代理脱离 fan-out 单独运行没有意义description 中原话not useful on its owntemperature: 0.1——低温设定保证评审输出严格、可复现避免发散权限上edit与task全部denybash仅放行只读的git log/show/diff/blame/rev-parse/merge-base、rg、wc以及需确认的just clang-tidy/clang-tidy——它被设计为只读评审者You are read-only. You never modify code.。二、评审方法拿到 diff、按类型装载指南、只读差异行review-style 的方法Method是围绕最少阅读原则设计的共三步获取变更使用编排代理传给它的命令获取 diff如git diff origin/main...HEAD、gh pr diff 1234不要让编排代理粘贴 diff 文本——子代理自己拉取比编排者重新输出成本低得多。按文件类型装载指南只装载变更中实际出现的文件类型对应的指南变更文件类型装载的指南.c、.hdocs/reference/kj-style.md并连带要求detail/review-checklist.mdsrc/rust/下的.rsdocs/reference/rust-review-checklist.md但剔除CXX Bridge Safety、Unsafe Code 两节、Error Handling 下的 FFI-panic 规则、JSG Resource Conventions 下的 GC-tracing 规则src/node/、src/cloudflare/、src/pyodide/或src/workerd/下测试中的.ts/.jsdocs/reference/ts-style.md一个值得注意的例外跨越.rs与其配套ffi.c/ffi.h的 CXX bridge 变更需要同时装载 Rust 与 C 两套指南因为桥接两侧的约定各自独立。逐行核对清单针对变更行逐一过检。文档特别强调风格评审是唯一一个细读 diff 比读周边代码结构更重要的评审轴Style review is the one axis where reading the diff closely matters more than reading the surrounding code-review agenture.并重申读得越少越好上下文被填满时你的 finding 质量会下降。这些被引用的指南文档均在仓库中存在KJ 风格指南 docs/reference/kj-style.md 明确KJ 类型优先于 STL如kj::String替代std::string、kj::OwnT替代std::unique_ptr、kj::MaybeT替代std::optional且必须在评审 workerd C 代码前阅读detail/review-checklist.mdTypeScript 清单 docs/reference/ts-style.md 覆盖严格模式exactOptionalPropertyTypes、noUncheckedIndexedAccess、verbatimModuleSyntax、erasableSyntaxOnly与分层导入约定node:*、cloudflare:*、node-internal:*、cloudflare-internal:*。三、workerd 风格指南假定的项目级规则review-style 在装载的通用清单之外补充了四条workerd 项目特有的、指南默认遵守的规则评审者不得违反绝不建议noexcept项目不声明noexcept显式析构函数使用noexcept(false)。不拆jsg::Lock与workerd::IoContext这两个类是有意为之的大型类intentional god classes禁止建议分解。优先协程在确实能提升可读性时优先使用协程而非显式kj::Promise链——但绝不提议大规模重写。先查src/workerd/util/再报重复造轮子在标记某个重新发明的工具之前必须先检查 src/workerd/util/ 并指名已存在的实现。文档点名了四个高频嫌疑对象weak-refs.h、state-machine.h、ring-buffer.h、small-weak-vector.h——这些头文件均已在本仓库确认存在。建议更新AGENTS.md在能帮助未来工具理解代码时提出更新对应目录的AGENTS.md。这些规则与编排代理 code-review.md 中的 workerd 专项规则一脉相承如liftKj的异常转换模式、kj::coCapture协程捕获、isolate 锁不得跨挂起点持有、KJ_TRY/JSG_TRY错误处理、成员排序兼顾缓存局部性等但风格轴只负责其中与编码约定相关的部分。四、输出格式共享 finding 结构 严格严重级别上限review-style 的输出要求是只返回 findings别无其他——没有开场白、不复述变更、不做收尾总结这些由编排代理负责。单个 finding 采用五个字段的标准结构**[SEVERITY]** Title - **Location**: file and line - **Problem**: what is wrong, and why it matters - **Evidence**: the code, data, or reasoning that establishes it - **Recommendation**: the specific fix这一结构与 review-safety、review-api 完全一致保证编排代理在汇总阶段可以无差异地合并三方结果。严重级别天花板最高只到 MEDIUM这是风格轴与安全轴、API 轴的关键差异——review-style 的严重级别封顶在 MEDIUMMEDIUM会误导未来读者的约定违反convention violation that will mislead a future reader、缺失版权头、STL 泄漏进 KJ 接口LOW其余一切。文档明确警告如果你认为自己发现了 CRITICAL 或 HIGH那几乎肯定是其他评审轴的领域——用一行标记为 out-of-scope范围外然后继续不要展开成完整 finding。这与 review-safety覆盖 CRITICAL 崩溃/数据丢失和 review-api覆盖 HIGH 性能回归/破坏性 API 变更形成互补的严重级别矩阵。合并重复项与数量上限同类违规合并为一个 finding12 处独立的[]捕获问题 1 个 finding 带 12 个位置列表Twelve separate[]-capture findings are one finding with twelve locations.上限 15 条超过 15 条只报最严重的 15 条并说明丢弃了多少。原因很实在全部输出都会进入编排代理的上下文长度直接增加汇总步骤的成本length here costs the synthesis step directly。收尾Cleared:行所有 findings 之后必须输出一行Cleared:列出已检查且干净无问题的清单区域。其语义与 review-safety 中的说明一致让编排代理区分那里没有 bug和根本没检查到The code-review agent needs to know the difference between no bugs there and did not get to it.。五、铁律格式归格式化器约定不靠个人品味review-style 的 Rules 一节给出了三条判断纪律用于防止评审者越界或制造噪音格式化归格式化器just format会运行 clang-format、prettier、ruff、buildifier 与 rustfmt。凡是格式化器能修复的空白、换行、花括号位置问题一律不报告。仓库 justfile 中确认format:配方实际调用python3 tools/cross/format.py即 tools/cross/format.py。约定而非偏好只报告指南中明确写明的条款。如果你发现自己是在凭个人品味taste争辩放弃这条 finding。没发现就是没发现空的 findings 列表 一行像样的Cleared:就是一次成功的评审。不要为了显得尽职而编造 findingDo not invent findings to look thorough.。这三条规则与 review-safety、review-api 的证据优先于猜测先假设再验证报假阳性比漏掉 LOW 更贵等纪律共同构成了 workerd 评审代理家族的行为准则确保 AI 评审输出真实、克制、可被编排层可靠消费。六、在 fan-out 中的协作方式结合编排代理理解 review-style 的最佳方式是看它如何被消费。编排代理 code-review.md 规定当两个及以上清单适用时平衡评审、安全审计把每个轴分派给独立评审者review-safety内存/线程/生命周期/V8-GC、review-api性能/API 设计/向后兼容/安全/标准、review-style按文件类型分派的 KJ/C、Rust、TypeScript 约定三个子代理在同一条消息中并行启动每个拿到的是产生变更的确切命令 变更意图 范围收窄要求而非 diff 文本本身编排代理的职责是汇总合并 findings、去重两个评审者从不同角度发现同一问题、裁决严重级别分歧当安全轴要拷贝、性能轴不要拷贝这类真实冲突时把权衡写进 finding 而不是替开发者选边某轴返回空结果也要记录——那是一种结果不是缺口。在特定情况下可以跳过 fan-out当评审只是单轴模式你只是在转述一个评审者的输出或变更小到亲自读比给三个 agent 开会还便宜时编排代理会自己装载清单直接评审。七、给构建或复用该评审体系的实践要点如果你要在自己的项目中复用这套风格评审子代理设计可以从 review-style.md 提炼以下可直接落地的要点用 frontmatter 固化边界mode: subagenttemperature: 0.1 全 deny 的edit/task权限 bash 白名单只读 git 命令 只读文本工具从机制上保证评审者只读、低温、不越权按文件类型装载清单避免让评审者一次性加载所有风格文档只加载变更中实际出现类型的指南并按文件类型做剪裁如 Rust 清单剔除安全轴负责的章节严重级别封顶单轴评审者只在自己轴内评级遇到跨轴问题用一行 out-of-scope 标记移交避免重复劳动与级别冲突结构化的 finding 模板SEVERITY / Location / Problem / Evidence / Recommendation 五字段 合并重复项 15 条上限 Cleared:收尾让编排层可以无损合成输出纪律明确空结果 成功格式化交给just format只报告指南写明的约定——这三条是防止 AI 评审注水、保持信噪比的关键。以上所有引用路径均可在本仓库中直接查看验证例如 .opencode/agent/review-style.md、.opencode/agent/code-review.md、.opencode/agent/review-safety.md、.opencode/agent/review-api.md、docs/reference/kj-style.md、docs/reference/ts-style.md 与 justfile。【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考