TiKV Deep Review 实战指南生产级代码评审工作流、静态校验与维护文档联动【免费下载链接】tikvDistributed transactional key-value database, originally created to complement TiDB项目地址: https://gitcode.com/GitHub_Trending/ti/tikv导读本文完整解读 TiKV 仓库内置的deep-review 评审工作流见 .agents/skills/deep-review/SKILL.md如何在评审一个 PR、分支、提交区间或 diff 时产出生产级的 Markdown 评审报告。你会掌握评审输入的默认规则、TiKV 特有的静态校验命令make format/make clippy、与doc/maintenance-guides维护文档的联动检查、以及可直接复用的评审报告模板。这套工作流适用于 TiKV 这类分布式事务 KV 数据库改动往往横跨src/storage、components/raftstore、components/cdc等并发密集、正确性敏感的子系统普通看 diff式的评审远远不够。1. Deep Review 是什么为生产关键路径设计的评审Deep Review 的目标是产出面向生产环境关键路径的评审而不是泛泛的代码走查。按 SKILL.md 的定义它需要做到解释变更试图解决的具体问题problem being solved用具体的代码语言解释变更如何工作how the change works in concrete code terms识别正确性、安全性、性能与可运维性风险correctness, safety, performance, operability遵守 AGENTS.md 中定义的 TiKV 仓库规则检查受影响的文件是否需要同步更新 doc/maintenance-guides 下的维护文档将评审结果写入目标目录下的 Markdown 文件运行仓库规定的格式化与 Lint 检查./Makefile中的规则。与普通评审最大的区别在于生产级三个字TiKV 的改动一旦出错可能影响 Raft 一致性、事务隔离、快照语义、备份/CDC 数据流等底层契约因此评审不仅要看 diff 本身还要顺着变更进入所属子系统的完整上下文。1.1 输入与默认值输入项默认值 / 规则仓库根目录先确定仓库根所有命令都从根目录执行目标输出目录未指定时使用./target输出文件名未指定时使用review-report-YYYYMMDD-summary.md已存在的报告不得覆盖选择不同的文件名评审范围diff未显式指定时优先使用当前分支与其配置的 upstream tracking 分支的 diff而不是盲目使用origin/HEAD最后一条值得强调origin/HEAD可能指向一个与本分支毫无关系的基线用它做 diff 会产生误导性结果正确的做法是先解析当前分支的 upstream 分支例如origin/master再基于该分支计算变更集。2. TiKV 特有的评审规则2.1 权威静态检查make format与make clippy而非裸cargo clippyDeep Review 工作流把make format和make clippy视为权威静态检查理由写得很明确TiKV 的 Makefile 补充了必要的环境准备和仓库专属脚本直接运行裸cargo clippy无法复现仓库要求的检查组合。除非用户明确要求更窄范围的检查否则不要用cargo clippy替代make clippy。从 Makefile 的源码可以看到这两条规则的真实构成pre-format: unset-override rustup component add rustfmt if ! command -v cargo-sort /dev/null 21 || ! cargo-sort --version 2/dev/null | grep -q ^cargo-sort $(CARGO_SORT_VERSION)$$; then \ cargo nightly install -q cargo-sort$(CARGO_SORT_VERSION); \ fi format: pre-format cargo fmt cargo sort -w -c /dev/null || cargo sort -w /dev/nullmake format的pre-format会先安装rustfmt并引导安装固定版本的cargo-sort版本由CARGO_SORT_VERSION ? 1.0.9定义见 Makefile然后才执行cargo fmt和cargo sort。这就是Makefile 补充必要环境准备的具体体现——裸cargo fmt不会管Cargo.toml的依赖排序规范。make clippy会依次运行 scripts/check-redact-log、scripts/check-log-style、scripts/check-dashboards、scripts/check-docker-build、scripts/check-license、scripts/deny最后才执行 scripts/clippy-all。这些是纯 Rust lint 之外的仓库级检查日志风格、监控面板一致性、Docker 构建、License、依赖安全。其中值得展开的两个脚本日志脱敏检查scripts/check-redact-log检查源码中是否出现未脱敏的encode_upper调用。它强制要求把用户数据打印进日志时必须使用log_wrappers::Value()尊重security.redact-info-log配置否则使用log_wrappers::hex_encode_upper绕过。这属于安全/隐私合规类检查是 TiKV 评审特有的关注点。依赖安全审计scripts/deny用独立 Rust 版本RUST_VERSION1.92.0安装固定版本cargo-deny0.18.9执行deny fetch all与deny check --show-stats。Deep Review 工作流特别提醒如果make clippy在scripts/deny阶段失败要在报告中单独记录因为此时clippy-all可能还没运行不能把依赖审计失败误报为 Rust lint 失败。clippy 本体scripts/clippy-all 最终调用 scripts/clippy后者以--workspace方式运行cargo clippy并携带一套 TiKV 定制的 lint 白名单/黑名单见 scripts/clippy要点包括默认放宽-Alarge_enum_variantraftstore peer 消息、result_large_errprotobuf 消息、too_many_arguments、type_complexity等——这些在分布式系统中往往是必要取舍严格要求-Dclippy::upper_case_acronyms、clippy::disallowed_methods、rust-2018-idioms、clippy::assertions_on_result_states对异步代码的专项约束-D clippy::redundant_async_block、clippy::unused_async、clippy::manual_async_fn、clippy::large_futuresTiKV 对异步代码格外挑剔因为容易写出次优甚至臃肿的实现。2.2 工程规则检查先读 AGENTS.md开始判断工程合规性之前必须先读 AGENTS.md。这份文件定义了 TiKV 的 Agent 协作规范评审时需要重点核对仓库专属的构建/测试入口make build、make test、make dev、make format、make clippy才是标准入口AGENTS.md 的 Building / Testing / Code Quality 三节PR 提交门槛make dev必须在提交 PR 前通过它等价于format clippy FAIL_POINT1 的 test见 MakefilePR 标题规范必须采用module [, module2, module3]: whats changed或*: whats changed两种格式之一AGENTS.md 的 Pull Request Instructions 一节PR 描述要求必须有Issue Number:行close #xxx/ref #xxx、按模板填写commit-message代码块、勾选测试类型与副作用、填写release-note提交签名所有 commit 必须带Signed-off-byDCO例如git commit -s -m ...。2.3 maintenance guides 是必需评审上下文Deep Review 明确要求在开始阅读受影响子系统之前先读 doc/maintenance-guides/README.md 和对应的子系统指南并把维护指南当作非平凡改动的必需上下文而不是可选的补充材料。doc/maintenance-guides/README.md 描述了一套维护者契约Maintainer Contract开发者与评审者在做非平凡改动前应先阅读相关指南如果改动修改了所有权边界、启动顺序、数据契约、不变量、可观测信号或推荐阅读地图匹配的指南应在同一个改动中同步更新一个让指南失效却未同步更新的代码改动应被视为不完整的维护变更incomplete maintenance change。同时每个子系统指南都要遵守标准章节契约覆盖 10 个领域目的与范围、架构视图、进程生命周期与启动时序、数据模型与元数据契约、可观测性与运维信号、变更管理指导、阅读地图与配套文档、术语表、必读文件顺序、变更影响矩阵。当前指南集覆盖两类复制路径见 doc/maintenance-guides/README.md 的 Guide Index经典 raftstore 路径components/raftstore、components/batch-system、components/server、components/service、components/resource_control、components/hybrid_engine、components/in_memory_engine与RaftKv2/ tablet 路径components/raftstore-v2以及src/下的coprocessor、coprocessor_v2、server、storage。跨组件改动时还应先读 doc/maintenance-guides/repo-overview.md。3. 十步评审工作流Deep Review 把评审拆成 10 个明确的步骤每个步骤都有可执行的判据。第 1 步确认输入确定仓库根、目标输出目录与输出文件名。评审范围未显式给出时先找出当前分支的 upstream tracking 分支并用该 diff如果连 upstream 分支都不存在只有在origin/HEAD明显是预期基线时才回退使用它否则停下来向用户确认而不是评审一个很可能错误的 diff。第 2 步收集变更集优先使用用户提供的 diff否则在仓库根执行git diff upstream...HEAD。如果 upstream 分支不可用或回退基线有歧义同样停下来询问而不是猜测。第 3 步理解变更意图尽量阅读 PR 描述、Issue 链接、commit message 或周边代码注释然后用一句话陈述变更要解决的具体系统问题。如果意图仍不清晰允许从代码推断但必须把推断明确标注为 assumption。第 4 步阅读受影响的 TiKV 子系统跟随被改动代码进入其所属模块而不要只看 diff hunk。SKILL.md 列出的典型子系统包括src/storage、src/storage/mvcc、src/storage/txn事务与 MVCCsrc/servergRPC、Raft transport、status servercomponents/raftstore、components/raftstore-v2复制与 region 状态机components/cdc变更数据捕获components/pd_clientPD 客户端tests/集成测试需要阅读足够多的周边代码以理解不变量invariants、并发假设、错误传播路径与测试覆盖。SKILL.md 有一条原则遇到不熟悉的代码应阅读周边子系统而不是仅凭符号名推断语义——这是分布式系统评审中最容易出错的地方。第 5 步检查 maintenance-guide 影响判断被改动文件是否映射到doc/maintenance-guides下已覆盖的指南跨组件改动必须先读 doc/maintenance-guides/repo-overview.md对已覆盖子系统阅读匹配指南中的目的与范围、数据/模型契约、可观测性指导、必读文件顺序、变更影响矩阵判断代码改动是否应同步更新指南。SKILL.md 给出了通常必须更新指南的情形清单——改动改变了以下任一内容时指南必须跟着改所有权或子系统边界启动/关闭时序元数据或 API 契约不变量或排序规则运维信号、指标、日志或健康面阅读地图、必读文件顺序或变更影响指导如果同一改动已经更新了指南评审这份指南更新的准确性与完整性如果应该更新却没更新必须在评审输出中显式记录并告诉用户对应的指南文件应被更新而不是默默接受。第 6 步解释变更如何工作逐一走读每个非平凡的逻辑改动用平实的语言说明控制流、数据流、状态转移与失败路径并在讨论发现时引用具体的文件、符号与行号。这一节是评审报告的主体目标是让任何读者不看 diff 也能理解变更的机制。第 7 步评估成本与负面影响显式评估以下维度SKILL.md 将其固化进输出模板正确性correctness安全性security健壮性与失败模式robustness and failure modes兼容性与行为偏移compatibility and behavioral shiftsCPU 成本内存成本日志量 / 日志信号质量可运维性与可调试性认知负荷与可维护性第 8 步运行 Makefile 静态校验这是 deep-review 与普通评审最可感知的区别之一。docs-only 快速路径如果评审目标仅包含文档diff 限定在doc/、.agents/或仓库文档文件如README.md、CONTRIBUTING.md则跳过make format和make clippy并把两项检查标记为因 docs-only 范围跳过不得声称代码路径通过了静态校验。否则按顺序执行在仓库根运行make format等价于pre-format引导 rustfmt 与固定版本 cargo-sort 后执行cargo fmtcargo sort在仓库根运行make clippy依次运行 redact-log、log-style、dashboards、docker-build、license、deny 检查最后scripts/clippy-all。如果两项检查在工作树中报出代码问题检查失败文件判断失败属于评审目标本身还是无关的脏工作树状态并把结果记录进评审输出。SKILL.md 有两个明确的边界不要静默编辑被评审代码评审流程不修改被评审的变更除非用户明确要求 review-plus-fix不要回滚无关的用户改动修复评审发现的问题时不得 revert 用户在工作树中的其他未提交修改。若make clippy失败在scripts/deny需将其与 Rust lint 结果分开记录此时clippy-all可能尚未运行若失败是环境性的toolchain 问题、外部依赖不可用在报告中记录确切的阻塞原因且不得声称代码通过检查。第 9 步检查工程规则核对与 AGENTS.md 的一致性重点是仓库专属构建/测试入口、make dev等必需验证、以及与评审相关的 PR 标题 / Issue 链接 / release note 要求同时核对与 doc/maintenance-guides/README.md 维护者契约的一致性。第 10 步写评审输出将报告写入目标目录下的 Markdown 文件遵守第 1 步的文件名默认值与不覆盖已有报告规则。报告结构直接复用下一节的模板。4. 评审报告模板详解SKILL.md 提供了一个可直接复用的评审报告模板。各节含义如下### Deep Review #### Problem Summary - [Explain the concrete problem the change targets] #### Solution Walkthrough - [Explain how the change solves the problem; cover all non-obvious logic] #### Findings (ordered by severity) - [Issue or risk with file/line references] #### Maintenance Guide Check - Relevant guides: - Guide update required: - Updated in change: - If missing, which files should be updated: #### Costs and Negative Impacts - Correctness: - Security: - Compatibility: - Robustness: - Operability: - Cognitive Load: - CPU: - Memory: - Log Volume: #### Static Validation - make format: - make clippy: #### Engineering Rules Check - [List code or process mismatches against AGENTS.md, or None] - [List maintenance-guide contract mismatches from doc/maintenance-guides/README.md, or None] #### Questions and Assumptions - [List unknowns or assumptions made] #### Suggested Tests / Validation - [Targeted tests or checks to validate behavior]几个容易忽略的填写要点Findings 按严重程度排序每条必须带 file/line 引用——这是模板要求的最低证据标准Maintenance Guide Check 是必填项且要回答四个问题相关指南是哪些、是否需要更新、变更是否已更新、如果缺失应更新哪些文件没有发现no findings时要明说但同时仍要记录残余风险、假设与验证缺口residual risks, assumptions, validation gapsStatic Validation 两行如实填写make format/make clippy的实际结果docs-only 场景填skipped due to docs-only scopeSuggested Tests / Validation给出针对性的测试建议——例如指出应使用哪个 failpoint、哪套集成测试框架components/test_raftstore、components/test_storage、components/test_coprocessor见 doc/maintenance-guides/README.md 的 Cross-Cutting Review Checklist来验证行为。5. 从模板到实战与仓库维护地图的配合Deep Review 的价值很大程度上来自与仓库维护地图的联动。评审一个横跨多个组件的改动时doc/maintenance-guides/repo-overview.md 提供了现成的分析框架可直接嵌入第 47 步写路径锚点经典路径从 src/server/service/kv.rs → src/storage/txn/scheduler.rs → src/server/raftkv/mod.rs → components/raftstore/src/router.rs → components/raftstore/src/store/peer.rsRaftKv2路径则换为 src/server/raftkv2/mod.rs 与components/raftstore-v2下的 router / fsm / raft 模块。评审存储到复制的桥接或回调语义时两条路径都要审。启动/关闭时序启动与关闭顺序是正确性问题跨线程/跨 worker 的所有权 bug 往往在这里暴露代码锚点包括 components/server/src/common.rs、components/server/src/server.rs、src/server/server.rs、src/server/raft_server.rs。热元数据契约metapb::Store/metapb::Region与 region epoch 转换、RaftCmdRequest/RaftCmdResponse的 region error 语义、kvrpcpb::Context与资源组标签、src/storage/config.rs 中的存储 API 版本与 TTL 期望——改动这些契约必须触发对应指南的复查。变更影响矩阵repo-overview 的 Change-Impact Matrix 给出了改了什么 → 应该一起读哪些指南的映射。例如缓存引擎或 hybrid snapshot 改动要同时读components/in_memory_engine、components/hybrid_engine、src/coprocessor与复制 observer 接线公平性/准入/RU 记账改动要读components/resource_control、src/server/service/kv.rs、src/storage与components/batch-system。可观测性评审涉及运维信号时优先打开 components/raftstore/src/store/metrics.rs、src/storage/metrics.rs、src/coprocessor/metrics.rs、src/server/metrics.rs、components/resource_control/src/metrics.rs 等指标模块判断新日志/指标是否廉价、是否尊重脱敏配置。6. 评审中的常见陷阱与纪律把 SKILL.md 中的隐性纪律显式化是写出高质量 Deep Review 报告的关键基线选错不检查 upstream tracking branch 就默认origin/HEAD可能评审到错误范围。基线有歧义时停下来问不要猜。只见 diff 不见子系统只看改动 hunk 无法理解不变量与并发假设要顺着代码进入所属模块。用裸cargo clippy冒充make clippy会漏掉 redact-log、deny、dashboards 等仓库专属检查。docs-only 改动声称通过了静态校验正确做法是如实标注 skipped。静默修改被评审代码 / 回滚用户未提交改动review-only 流程只读不改即使用户要求 review-plus-fix也只修复评审发现的问题本身。漏掉 maintenance-guide 更新要求指南未同步更新是评审发现项不是可忽略项。环境性失败被误报为代码失败toolchain 或外部依赖导致的失败要记录确切 blocker且不得声称代码通过。7. 总结把 Deep Review 变成你的评审默认流程Deep Review 的本质是把 TiKV 这种生产级分布式系统的评审经验沉淀为一套可重复、可核对、可交付的流程明确的输入约定upstream diff 优先、权威的静态校验入口make format/make clippy、强制的维护文档联动doc/maintenance-guides、以及一份让读者不看 diff 也能复现判断的报告模板。无论你是 TiKV 的 reviewer 还是想深入理解 TiKV 架构的开发者都可以从 .agents/skills/deep-review/SKILL.md 出发配合 Makefile、AGENTS.md、doc/maintenance-guides/README.md 与 doc/maintenance-guides/repo-overview.md 四份仓库级文档把看懂变更升级为审清变更的生产级影响。【免费下载链接】tikvDistributed transactional key-value database, originally created to complement TiDB项目地址: https://gitcode.com/GitHub_Trending/ti/tikv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TiKV Deep Review 实战指南：生产级代码评审工作流、静态校验与维护文档联动
TiKV Deep Review 实战指南生产级代码评审工作流、静态校验与维护文档联动【免费下载链接】tikvDistributed transactional key-value database, originally created to complement TiDB项目地址: https://gitcode.com/GitHub_Trending/ti/tikv导读本文完整解读 TiKV 仓库内置的deep-review 评审工作流见 .agents/skills/deep-review/SKILL.md如何在评审一个 PR、分支、提交区间或 diff 时产出生产级的 Markdown 评审报告。你会掌握评审输入的默认规则、TiKV 特有的静态校验命令make format/make clippy、与doc/maintenance-guides维护文档的联动检查、以及可直接复用的评审报告模板。这套工作流适用于 TiKV 这类分布式事务 KV 数据库改动往往横跨src/storage、components/raftstore、components/cdc等并发密集、正确性敏感的子系统普通看 diff式的评审远远不够。1. Deep Review 是什么为生产关键路径设计的评审Deep Review 的目标是产出面向生产环境关键路径的评审而不是泛泛的代码走查。按 SKILL.md 的定义它需要做到解释变更试图解决的具体问题problem being solved用具体的代码语言解释变更如何工作how the change works in concrete code terms识别正确性、安全性、性能与可运维性风险correctness, safety, performance, operability遵守 AGENTS.md 中定义的 TiKV 仓库规则检查受影响的文件是否需要同步更新 doc/maintenance-guides 下的维护文档将评审结果写入目标目录下的 Markdown 文件运行仓库规定的格式化与 Lint 检查./Makefile中的规则。与普通评审最大的区别在于生产级三个字TiKV 的改动一旦出错可能影响 Raft 一致性、事务隔离、快照语义、备份/CDC 数据流等底层契约因此评审不仅要看 diff 本身还要顺着变更进入所属子系统的完整上下文。1.1 输入与默认值输入项默认值 / 规则仓库根目录先确定仓库根所有命令都从根目录执行目标输出目录未指定时使用./target输出文件名未指定时使用review-report-YYYYMMDD-summary.md已存在的报告不得覆盖选择不同的文件名评审范围diff未显式指定时优先使用当前分支与其配置的 upstream tracking 分支的 diff而不是盲目使用origin/HEAD最后一条值得强调origin/HEAD可能指向一个与本分支毫无关系的基线用它做 diff 会产生误导性结果正确的做法是先解析当前分支的 upstream 分支例如origin/master再基于该分支计算变更集。2. TiKV 特有的评审规则2.1 权威静态检查make format与make clippy而非裸cargo clippyDeep Review 工作流把make format和make clippy视为权威静态检查理由写得很明确TiKV 的 Makefile 补充了必要的环境准备和仓库专属脚本直接运行裸cargo clippy无法复现仓库要求的检查组合。除非用户明确要求更窄范围的检查否则不要用cargo clippy替代make clippy。从 Makefile 的源码可以看到这两条规则的真实构成pre-format: unset-override rustup component add rustfmt if ! command -v cargo-sort /dev/null 21 || ! cargo-sort --version 2/dev/null | grep -q ^cargo-sort $(CARGO_SORT_VERSION)$$; then \ cargo nightly install -q cargo-sort$(CARGO_SORT_VERSION); \ fi format: pre-format cargo fmt cargo sort -w -c /dev/null || cargo sort -w /dev/nullmake format的pre-format会先安装rustfmt并引导安装固定版本的cargo-sort版本由CARGO_SORT_VERSION ? 1.0.9定义见 Makefile然后才执行cargo fmt和cargo sort。这就是Makefile 补充必要环境准备的具体体现——裸cargo fmt不会管Cargo.toml的依赖排序规范。make clippy会依次运行 scripts/check-redact-log、scripts/check-log-style、scripts/check-dashboards、scripts/check-docker-build、scripts/check-license、scripts/deny最后才执行 scripts/clippy-all。这些是纯 Rust lint 之外的仓库级检查日志风格、监控面板一致性、Docker 构建、License、依赖安全。其中值得展开的两个脚本日志脱敏检查scripts/check-redact-log检查源码中是否出现未脱敏的encode_upper调用。它强制要求把用户数据打印进日志时必须使用log_wrappers::Value()尊重security.redact-info-log配置否则使用log_wrappers::hex_encode_upper绕过。这属于安全/隐私合规类检查是 TiKV 评审特有的关注点。依赖安全审计scripts/deny用独立 Rust 版本RUST_VERSION1.92.0安装固定版本cargo-deny0.18.9执行deny fetch all与deny check --show-stats。Deep Review 工作流特别提醒如果make clippy在scripts/deny阶段失败要在报告中单独记录因为此时clippy-all可能还没运行不能把依赖审计失败误报为 Rust lint 失败。clippy 本体scripts/clippy-all 最终调用 scripts/clippy后者以--workspace方式运行cargo clippy并携带一套 TiKV 定制的 lint 白名单/黑名单见 scripts/clippy要点包括默认放宽-Alarge_enum_variantraftstore peer 消息、result_large_errprotobuf 消息、too_many_arguments、type_complexity等——这些在分布式系统中往往是必要取舍严格要求-Dclippy::upper_case_acronyms、clippy::disallowed_methods、rust-2018-idioms、clippy::assertions_on_result_states对异步代码的专项约束-D clippy::redundant_async_block、clippy::unused_async、clippy::manual_async_fn、clippy::large_futuresTiKV 对异步代码格外挑剔因为容易写出次优甚至臃肿的实现。2.2 工程规则检查先读 AGENTS.md开始判断工程合规性之前必须先读 AGENTS.md。这份文件定义了 TiKV 的 Agent 协作规范评审时需要重点核对仓库专属的构建/测试入口make build、make test、make dev、make format、make clippy才是标准入口AGENTS.md 的 Building / Testing / Code Quality 三节PR 提交门槛make dev必须在提交 PR 前通过它等价于format clippy FAIL_POINT1 的 test见 MakefilePR 标题规范必须采用module [, module2, module3]: whats changed或*: whats changed两种格式之一AGENTS.md 的 Pull Request Instructions 一节PR 描述要求必须有Issue Number:行close #xxx/ref #xxx、按模板填写commit-message代码块、勾选测试类型与副作用、填写release-note提交签名所有 commit 必须带Signed-off-byDCO例如git commit -s -m ...。2.3 maintenance guides 是必需评审上下文Deep Review 明确要求在开始阅读受影响子系统之前先读 doc/maintenance-guides/README.md 和对应的子系统指南并把维护指南当作非平凡改动的必需上下文而不是可选的补充材料。doc/maintenance-guides/README.md 描述了一套维护者契约Maintainer Contract开发者与评审者在做非平凡改动前应先阅读相关指南如果改动修改了所有权边界、启动顺序、数据契约、不变量、可观测信号或推荐阅读地图匹配的指南应在同一个改动中同步更新一个让指南失效却未同步更新的代码改动应被视为不完整的维护变更incomplete maintenance change。同时每个子系统指南都要遵守标准章节契约覆盖 10 个领域目的与范围、架构视图、进程生命周期与启动时序、数据模型与元数据契约、可观测性与运维信号、变更管理指导、阅读地图与配套文档、术语表、必读文件顺序、变更影响矩阵。当前指南集覆盖两类复制路径见 doc/maintenance-guides/README.md 的 Guide Index经典 raftstore 路径components/raftstore、components/batch-system、components/server、components/service、components/resource_control、components/hybrid_engine、components/in_memory_engine与RaftKv2/ tablet 路径components/raftstore-v2以及src/下的coprocessor、coprocessor_v2、server、storage。跨组件改动时还应先读 doc/maintenance-guides/repo-overview.md。3. 十步评审工作流Deep Review 把评审拆成 10 个明确的步骤每个步骤都有可执行的判据。第 1 步确认输入确定仓库根、目标输出目录与输出文件名。评审范围未显式给出时先找出当前分支的 upstream tracking 分支并用该 diff如果连 upstream 分支都不存在只有在origin/HEAD明显是预期基线时才回退使用它否则停下来向用户确认而不是评审一个很可能错误的 diff。第 2 步收集变更集优先使用用户提供的 diff否则在仓库根执行git diff upstream...HEAD。如果 upstream 分支不可用或回退基线有歧义同样停下来询问而不是猜测。第 3 步理解变更意图尽量阅读 PR 描述、Issue 链接、commit message 或周边代码注释然后用一句话陈述变更要解决的具体系统问题。如果意图仍不清晰允许从代码推断但必须把推断明确标注为 assumption。第 4 步阅读受影响的 TiKV 子系统跟随被改动代码进入其所属模块而不要只看 diff hunk。SKILL.md 列出的典型子系统包括src/storage、src/storage/mvcc、src/storage/txn事务与 MVCCsrc/servergRPC、Raft transport、status servercomponents/raftstore、components/raftstore-v2复制与 region 状态机components/cdc变更数据捕获components/pd_clientPD 客户端tests/集成测试需要阅读足够多的周边代码以理解不变量invariants、并发假设、错误传播路径与测试覆盖。SKILL.md 有一条原则遇到不熟悉的代码应阅读周边子系统而不是仅凭符号名推断语义——这是分布式系统评审中最容易出错的地方。第 5 步检查 maintenance-guide 影响判断被改动文件是否映射到doc/maintenance-guides下已覆盖的指南跨组件改动必须先读 doc/maintenance-guides/repo-overview.md对已覆盖子系统阅读匹配指南中的目的与范围、数据/模型契约、可观测性指导、必读文件顺序、变更影响矩阵判断代码改动是否应同步更新指南。SKILL.md 给出了通常必须更新指南的情形清单——改动改变了以下任一内容时指南必须跟着改所有权或子系统边界启动/关闭时序元数据或 API 契约不变量或排序规则运维信号、指标、日志或健康面阅读地图、必读文件顺序或变更影响指导如果同一改动已经更新了指南评审这份指南更新的准确性与完整性如果应该更新却没更新必须在评审输出中显式记录并告诉用户对应的指南文件应被更新而不是默默接受。第 6 步解释变更如何工作逐一走读每个非平凡的逻辑改动用平实的语言说明控制流、数据流、状态转移与失败路径并在讨论发现时引用具体的文件、符号与行号。这一节是评审报告的主体目标是让任何读者不看 diff 也能理解变更的机制。第 7 步评估成本与负面影响显式评估以下维度SKILL.md 将其固化进输出模板正确性correctness安全性security健壮性与失败模式robustness and failure modes兼容性与行为偏移compatibility and behavioral shiftsCPU 成本内存成本日志量 / 日志信号质量可运维性与可调试性认知负荷与可维护性第 8 步运行 Makefile 静态校验这是 deep-review 与普通评审最可感知的区别之一。docs-only 快速路径如果评审目标仅包含文档diff 限定在doc/、.agents/或仓库文档文件如README.md、CONTRIBUTING.md则跳过make format和make clippy并把两项检查标记为因 docs-only 范围跳过不得声称代码路径通过了静态校验。否则按顺序执行在仓库根运行make format等价于pre-format引导 rustfmt 与固定版本 cargo-sort 后执行cargo fmtcargo sort在仓库根运行make clippy依次运行 redact-log、log-style、dashboards、docker-build、license、deny 检查最后scripts/clippy-all。如果两项检查在工作树中报出代码问题检查失败文件判断失败属于评审目标本身还是无关的脏工作树状态并把结果记录进评审输出。SKILL.md 有两个明确的边界不要静默编辑被评审代码评审流程不修改被评审的变更除非用户明确要求 review-plus-fix不要回滚无关的用户改动修复评审发现的问题时不得 revert 用户在工作树中的其他未提交修改。若make clippy失败在scripts/deny需将其与 Rust lint 结果分开记录此时clippy-all可能尚未运行若失败是环境性的toolchain 问题、外部依赖不可用在报告中记录确切的阻塞原因且不得声称代码通过检查。第 9 步检查工程规则核对与 AGENTS.md 的一致性重点是仓库专属构建/测试入口、make dev等必需验证、以及与评审相关的 PR 标题 / Issue 链接 / release note 要求同时核对与 doc/maintenance-guides/README.md 维护者契约的一致性。第 10 步写评审输出将报告写入目标目录下的 Markdown 文件遵守第 1 步的文件名默认值与不覆盖已有报告规则。报告结构直接复用下一节的模板。4. 评审报告模板详解SKILL.md 提供了一个可直接复用的评审报告模板。各节含义如下### Deep Review #### Problem Summary - [Explain the concrete problem the change targets] #### Solution Walkthrough - [Explain how the change solves the problem; cover all non-obvious logic] #### Findings (ordered by severity) - [Issue or risk with file/line references] #### Maintenance Guide Check - Relevant guides: - Guide update required: - Updated in change: - If missing, which files should be updated: #### Costs and Negative Impacts - Correctness: - Security: - Compatibility: - Robustness: - Operability: - Cognitive Load: - CPU: - Memory: - Log Volume: #### Static Validation - make format: - make clippy: #### Engineering Rules Check - [List code or process mismatches against AGENTS.md, or None] - [List maintenance-guide contract mismatches from doc/maintenance-guides/README.md, or None] #### Questions and Assumptions - [List unknowns or assumptions made] #### Suggested Tests / Validation - [Targeted tests or checks to validate behavior]几个容易忽略的填写要点Findings 按严重程度排序每条必须带 file/line 引用——这是模板要求的最低证据标准Maintenance Guide Check 是必填项且要回答四个问题相关指南是哪些、是否需要更新、变更是否已更新、如果缺失应更新哪些文件没有发现no findings时要明说但同时仍要记录残余风险、假设与验证缺口residual risks, assumptions, validation gapsStatic Validation 两行如实填写make format/make clippy的实际结果docs-only 场景填skipped due to docs-only scopeSuggested Tests / Validation给出针对性的测试建议——例如指出应使用哪个 failpoint、哪套集成测试框架components/test_raftstore、components/test_storage、components/test_coprocessor见 doc/maintenance-guides/README.md 的 Cross-Cutting Review Checklist来验证行为。5. 从模板到实战与仓库维护地图的配合Deep Review 的价值很大程度上来自与仓库维护地图的联动。评审一个横跨多个组件的改动时doc/maintenance-guides/repo-overview.md 提供了现成的分析框架可直接嵌入第 47 步写路径锚点经典路径从 src/server/service/kv.rs → src/storage/txn/scheduler.rs → src/server/raftkv/mod.rs → components/raftstore/src/router.rs → components/raftstore/src/store/peer.rsRaftKv2路径则换为 src/server/raftkv2/mod.rs 与components/raftstore-v2下的 router / fsm / raft 模块。评审存储到复制的桥接或回调语义时两条路径都要审。启动/关闭时序启动与关闭顺序是正确性问题跨线程/跨 worker 的所有权 bug 往往在这里暴露代码锚点包括 components/server/src/common.rs、components/server/src/server.rs、src/server/server.rs、src/server/raft_server.rs。热元数据契约metapb::Store/metapb::Region与 region epoch 转换、RaftCmdRequest/RaftCmdResponse的 region error 语义、kvrpcpb::Context与资源组标签、src/storage/config.rs 中的存储 API 版本与 TTL 期望——改动这些契约必须触发对应指南的复查。变更影响矩阵repo-overview 的 Change-Impact Matrix 给出了改了什么 → 应该一起读哪些指南的映射。例如缓存引擎或 hybrid snapshot 改动要同时读components/in_memory_engine、components/hybrid_engine、src/coprocessor与复制 observer 接线公平性/准入/RU 记账改动要读components/resource_control、src/server/service/kv.rs、src/storage与components/batch-system。可观测性评审涉及运维信号时优先打开 components/raftstore/src/store/metrics.rs、src/storage/metrics.rs、src/coprocessor/metrics.rs、src/server/metrics.rs、components/resource_control/src/metrics.rs 等指标模块判断新日志/指标是否廉价、是否尊重脱敏配置。6. 评审中的常见陷阱与纪律把 SKILL.md 中的隐性纪律显式化是写出高质量 Deep Review 报告的关键基线选错不检查 upstream tracking branch 就默认origin/HEAD可能评审到错误范围。基线有歧义时停下来问不要猜。只见 diff 不见子系统只看改动 hunk 无法理解不变量与并发假设要顺着代码进入所属模块。用裸cargo clippy冒充make clippy会漏掉 redact-log、deny、dashboards 等仓库专属检查。docs-only 改动声称通过了静态校验正确做法是如实标注 skipped。静默修改被评审代码 / 回滚用户未提交改动review-only 流程只读不改即使用户要求 review-plus-fix也只修复评审发现的问题本身。漏掉 maintenance-guide 更新要求指南未同步更新是评审发现项不是可忽略项。环境性失败被误报为代码失败toolchain 或外部依赖导致的失败要记录确切 blocker且不得声称代码通过。7. 总结把 Deep Review 变成你的评审默认流程Deep Review 的本质是把 TiKV 这种生产级分布式系统的评审经验沉淀为一套可重复、可核对、可交付的流程明确的输入约定upstream diff 优先、权威的静态校验入口make format/make clippy、强制的维护文档联动doc/maintenance-guides、以及一份让读者不看 diff 也能复现判断的报告模板。无论你是 TiKV 的 reviewer 还是想深入理解 TiKV 架构的开发者都可以从 .agents/skills/deep-review/SKILL.md 出发配合 Makefile、AGENTS.md、doc/maintenance-guides/README.md 与 doc/maintenance-guides/repo-overview.md 四份仓库级文档把看懂变更升级为审清变更的生产级影响。【免费下载链接】tikvDistributed transactional key-value database, originally created to complement TiDB项目地址: https://gitcode.com/GitHub_Trending/ti/tikv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考