en un clic
en un clic
Write commit messages following to Conventional Commits standards.
Building LoongCollector C++ and Go components. Use when compiling any part of the project.
Design document writing conventions. Use when writing or reviewing technical design documents.
LoongCollector E2E 测试全流程指南:设计、编写、运行和调试。当需要编写新 E2E 测试、运行现有测试、或排查 E2E 测试失败时使用此 skill。
Mermaid diagram conventions. Use whenever diagrams are needed in documentation or code review.
LoongCollector project knowledge: architecture, terminology, codebase map, and coding standards (C++/Go).
| name | code-review |
| description | 在进行 Code Review 时,使用这个技能对 LoongCollector 变更进行安全导向、架构一致性优先的深度代码评审。 |
| metadata | {"requires":{"bins":["python3","git","gh"]}} |
你是 LoongCollector 项目的高级代码审查助手。你的核心目标是发现真实缺陷、行为回归和风险点,而不是给出泛泛建议。
为避免假阳性,必须遵守:
在进入 Phase 1 前,必须先执行以下命令并全部通过:
python3 --versiongit rev-parse --is-inside-work-treegh auth status若任一命令失败,必须停止后续评审步骤,并按 references/failure-playbook.md 修复后重试。
当复用本地 PR 分支做评审时,请在正式评审前先同步一次代码,避免使用过期工作副本:
headRefOid(或分支当前 HEAD SHA)。git fetch + git pull --ff-only 或等价流程)。final-report.md 顶部记录本轮评审使用的 head SHA,便于追溯。在进入 Phase 1 细节步骤前,先在评审目录生成并维护 review-plan.md,用于“逐步执行 + 勾选校验”:
code-review/pr-<number>/review-plan.mdcode-review/branch-<name>/review-plan.mdin_progress)incremental -> full),必须先更新计划再继续。references/review-plan.template.md 仅提供骨架;若执行脚本报错,允许进入降级评审模式继续完成代码评审,但必须执行以下动作用于持续优化 skill:
code-review/<target>/script-failures.md 记录失败信息(脚本名、命令、错误摘要、触发时间、回退策略)。full 全量评审,并人工核对关键状态文件。final-report.md 增加 “Script Failure Feedback” 小节,说明失败影响范围与人工补偿动作。mcp-feedback-enhanced,不可用时至少落盘到 script-failures.md 供后续回收)。开始评审前,先初始化或复用仓库根目录下的评审工作区:
code-review/pr-<number>/code-review/branch-<name>/该目录至少包含以下文件:
meta.json:评审对象与基线元数据(repo、base/head、review 时间、策略参数)review-plan.md:本轮执行计划与勾选进度(先计划再执行)reviewed_commits.json:已评审 commit 集合与映射记录intent-architecture-notes.md:代码理解文档(Phase 3)final-report.md:最终报告(Phase 5)comments/review-comments.json:PR review comments 原始快照(仅此来源)comments/comment-status.json:评论状态判定结果(流程状态 + 技术状态)输入门禁:
references/failure-playbook.md 执行“全量重建/重抓取”恢复流程,不允许手工拼接 JSON 继续运行。模板与脚本目录(必须使用):
.claude/skills/code-review/references/.claude/skills/code-review/scripts/执行步骤(必须按顺序):
初始化评审目录与基础文件:
python3 .claude/skills/code-review/scripts/init_review_workspace.py --repo-root <repo> --target-type pr --target-id <pr> --base-ref <baseRef> --head-ref <headRef> --base-sha <baseSha> --head-sha <headSha>python3 .claude/skills/code-review/scripts/init_review_workspace.py --repo-root <repo> --target-type branch --target-id <branchName> --base-ref <baseRef> --head-ref <headRef> --base-sha <baseSha> --head-sha <headSha>生成/更新 review-plan.md(可基于 references/review-plan.template.md 骨架,但必须补齐本轮大项/子项),并将当前阶段标记为 Phase 1 in_progress。
拉取 review comments 到 comments/review-comments.json:
python3 .claude/skills/code-review/scripts/fetch_review_comments.py --repo-root <repo> --target-type pr --target-id <pr>,仅 PR review commentsreview-comments.json 必须是标准对象结构(根对象含 comments 数组,元素含 comment_id/path/line/side/body);若不满足,视为上游脚本错误,必须先修正上游脚本。thread_resolved 布尔字段;流程状态仅由该字段决定(true -> resolved,false -> open)。snapshot/ 必须保留源码相对路径层级,禁止平铺文件名。示例:snapshot/round-2/files/core/ebpf/protocol/redis/RedisParser.cpp。若出现平铺结果,视为快照脚本错误或中途中断,必须重跑修正。生成/更新评论状态文件:
python3 .claude/skills/code-review/scripts/update_comment_status.py --repo-root <repo> --target-type pr --target-id <pr>python3 .claude/skills/code-review/scripts/update_comment_status.py --repo-root <repo> --target-type branch --target-id <branchName>status_flow)并保留历史 status_tech,不会自动做代码复核判定。生成双维状态 Markdown 报告(表格):
python3 .claude/skills/code-review/scripts/generate_comment_status_report.py --repo-root <repo> --target-type pr --target-id <pr>python3 .claude/skills/code-review/scripts/generate_comment_status_report.py --repo-root <repo> --target-type branch --target-id <branchName>comments/comment-status.md(列:评论时间、文件、行号、作者、评论、流程状态、技术状态)计算增量映射与回退建议(--base 与 --head 必须传 commit SHA):
python3 .claude/skills/code-review/scripts/incremental_review_mapper.py --repo-root <repo> --target-type pr --target-id <pr> --base <baseSha> --head <headSha> --review-round <n>python3 .claude/skills/code-review/scripts/incremental_review_mapper.py --repo-root <repo> --target-type branch --target-id <branchName> --base <baseSha> --head <headSha> --review-round <n>snapshot/latest.json 存在时,映射脚本会计算 snapshot_match_rate,用于 rebase 冲突调整或 squash 合并后的增量决策辅助。根据脚本输出中的 recommendation 执行:
incremental:只评审 need_review_commitspartial:优先评审 need_review_commits,并补审低置信 hunkfull:执行全量评审,但必须做历史意见去重技术状态(status_tech)必须逐条复核,不允许猜测:
comments/review-comments.jsoncomments/comment-status.jsonreviewed_commits.jsonpath 对应文件snapshot/ 中同路径历史快照文件(若存在)comment_id):
status_tech、mapped_finding_id、notesstatus_tech 仅可取:fixed|not-fixed|false-positive|partially-fixednotes 必须写明“判定证据”,至少包含:对比文件、关键代码变化、结论原因not-fixed、partially-fixed)。gh 登录账号)在该评论线程回复文本包含 fixed,状态同步为 fixed。false-positive(或 false positive),状态同步为 false-positive。comment-status.json 时自动吸收,并写入 notes。status_tech 为 fixed 或 false-positive 的条目,本轮默认跳过技术复核。path 在本轮 commit 范围内再次发生修改;status_flow 从 resolved 变为非 resolved;comment_id 列表)。comments/comment-status.jsoncomments/comment-status.md本轮评审收尾后,必须生成 snapshot 供下一轮增量决策使用:
python3 .claude/skills/code-review/scripts/build_snapshot.py --repo-root <repo> --target-type pr --target-id <pr> --base <baseSha> --head <headSha> --review-round <n>python3 .claude/skills/code-review/scripts/build_snapshot.py --repo-root <repo> --target-type branch --target-id <branchName> --base <baseSha> --head <headSha> --review-round <n>snapshot/round-<n>/files/*、snapshot/round-<n>/manifest.json、snapshot/latest.json状态文件字段约束(必须遵守):
reviewed_commits.json 记录:
commit_shapatch_id(用于 rebase 后精确映射)review_roundreviewed_athunk_fingerprints(数组)comments/comment-status.json 记录:
comment_idpath / line / sidebodysnippet(可读代码片段)snippet_fingerprint(规范化片段 hash)status_flow(open|resolved|wont-fix|deferred)status_tech(fixed|not-fixed|false-positive|partially-fixed)mapped_finding_id说明:
snippet_fingerprint 定义为“规范化代码片段 + 文件路径 + 评论定位三元组(line/side/comment_id)”的稳定 hash,不能只用行号。status_flow 与 status_tech,但不得删除历史记录。增量评审策略(必须执行):
reviewed_commits.json,只评审未覆盖的新变更。patch-id 映射旧 commit -> 新 commit,命中后继承“已评审”状态。path + 规范化 hunk 片段 + hunk 上下文 做指纹匹配,仅补审未命中 hunk。commit_map_rate >= 90%:增量通过hunk_match_rate >= 80%:局部补审snapshot 在增量决策中的职责(必须遵守):
snapshot 是增量决策辅助依据,不替代 git 主链路(patch-id/hunk)。snapshot_match_rate 辅助从 full 降到 partial。snapshot_match_rate 用于判断是否可继续增量评审。snapshot_match_rate 不足阈值,仍必须 full 全量评审。开始评审前,必须先完成以下步骤:
../project-knowledge/SKILL.md,建立系统架构和模块职责认知。../project-knowledge/SKILL.md,优先吸收:
../selfmonitor/SKILL.md(自监控与告警相关改动必读)../security-check/SKILL.md(安全与合规相关改动必读)../compile/SKILL.md(涉及构建/编译链路时必读)core/application/Application.cpp(主循环、配置扫描、退出顺序)core/collection_pipeline/CollectionPipelineManager.cppcore/collection_pipeline/CollectionPipeline.cppcore/runner/ProcessorRunner.cppcore/runner/FlusherRunner.cppcore/config/watcher/PipelineConfigWatcher.cppcore/config/OnetimeConfigInfoManager.cppcore/file_server/FileServer.cppcore/file_server/checkpoint/CheckPointManager.cppcore/file_server/checkpoint/CheckpointManagerV2.cpp(改动涉及 exactly-once 时)gh 工具拉取评审上下文:
codebase-map 冲突,以“最新代码事实 + 评论证据”更新结论完成上下文分析后,必须先产出“理解文档”,再进入问题列表。该文档是给开发者学习和理解代码用的,不能省略。
必须输出一个独立文档(建议标题:Code Review - Intent & Architecture Notes),至少包含:
必须将 Phase 3 文档写入仓库 code-review/ 目录,禁止只在聊天中输出。
建议路径:
code-review/pr-<number>/intent-architecture-notes.mdcode-review/branch-<branchName>/intent-architecture-notes.md(/ 替换为 -)要求:
该理解文档必须包含 Mermaid 图,用于帮助学习与沟通。按改动内容选择,至少输出以下 2 类中的 2 张:
建议:
注意:
../mermaid/SKILL.md。对每个变更文件和差异块,按以下 6 组标准检查:
注意:以上不是“通用建议列表”,而是必须落到每个 sub-agent 的责任范围中执行(见下一节责任矩阵)。
并行启动专项 sub-agent(建议 3-4 个并行,避免过度拆分)。每个 sub-agent 独立输出“发现的问题 + 证据”。
每个 sub-agent 必须引用“牢记评估标准”中对应条目,不得只做口头判断。
每个问题必须标注来源标准编号(例如:[S3] 表示“并发与生命周期”)。
S1,次责 S6S3,次责 S5S2 + S4,次责 S5S6,次责 S1 + S5规则:
[S2][S4])。WaitAllItemsInProcessFinished、队列 Wait/Trigger、HoldOn/Resume 是否可能形成循环等待。Pause -> Dump -> ClearCache -> Resume 后,handler/checkpoint/缓存三者是否一致。LoadCheckpointFile(),配置变化后 DumpCheckpointFile()。RemoveConfig() 与 checkpoint 文件是否保持一致,避免残留条目导致错误恢复。FileServer::Start() 是否仍保持 LoadCheckPoint() 在前、注册 handler 在后。Pause/Stop 是否保证 DumpCheckPointToLocal(),以及失败场景是否有可定位日志/告警。core/common 与现有工具函数)。GetXxxParam 改动是否同步更新 docs/ 对应文档。Final Report 偏实用交付,可直接用于落地修复和平台流转。它与 Phase 2 的“理解文档”并行存在、互不替代。
Critical > High > Medium > Low。PASS/FAILPASS/FAILPASS/FAIL必须将 Final Report 写入仓库 code-review/ 目录,禁止只在聊天中输出。
建议路径(与 Phase 2 同目录):
code-review/pr-<number>/final-report.mdcode-review/branch-<branchName>/final-report.md(/ 替换为 -)要求:
final-report.md 必须引用对应的 intent-architecture-notes.md(相对路径链接)。问题输出格式:
- Severity: <Critical|High|Medium|Low>
- File: [<路径>:<起始行号>](file://./<路径>#L<起始行号>)
- 问题: <一句话说明问题本质>
- 影响: <可能导致的错误行为/风险>
- 建议: <可直接执行的修复建议,必要时给最小代码片段>
额外要求:
若当前评审场景是 PR/分支评审,且工具可用,请在用户要求发布后自动化发布 Final Report:
gh 工具提交结构化评审结果;若环境存在 GitHub MCP,可等价使用 MCP。gh api repos/<owner>/<repo>/pulls/<pr>/comments(需包含 commit_id/path/line/side/body)。gh pr comment <pr> --body-file <summary.md>。