qt-cpp-review

Qt 代码审查

对 Qt6 C++ 代码进行只读审查：先运行确定性的 Python 代码检查器，再通过 Agent 对六个规则领域进行深入分析，最后生成一份汇总报告。

何时使用此技能

• 与审查相关的请求：“审查”、“检查”、“审核”、“看一下”、“代码审查”、“健全性检查”
• 建议在提交代码前使用

参数

• /qt-cpp-review — 通用 Qt6 C++ 规则
• /qt-cpp-review framework — 还会应用 Qt 框架／模块规则 （二进制兼容性、导出、d-pointer、qdoc、QML 版本管理）

框架模式

当 $ARGUMENTS 包含 "framework" 时启用。否则，如果 lint 运行或快速 Grep 显示以下信号中有两个或更多，请建议用户启用框架模式，但不要自行启用： QT_BEGIN_NAMESPACE、任何 Q_*_EXPORT 宏、<QtModule/private/*_p.h> 包含、Q_DECLARE_PRIVATE/Q_D()/Q_Q()、CMakeLists.txt 中的 qt_internal_add_module、仓库根目录下的 sync.profile 或 .qmake.conf。

启用后：向代码检查器传入 --framework，并在负责 A2 或 A4 的 Agent 提示词中注明 references/qt-framework-checklist.md（按 agent-rules.md 末尾的映射应用相关规则）。在差异范围内，还要自行根据 FW-CMT 规则检查提交信息；只使用 sed -n '/^## Commit Message/,$p' references/qt-framework-checklist.md 加载该部分。

范围检测

差异范围 — “此提交”、“这些更改”、“此差异”、“我更改的内容”、“暂存的更改”、“提交前”。范围为 HEAD （工作树和索引）、仅针对暂存更改的 --cached，或针对“此提交”的 HEAD~1..HEAD。不要加载差异本身：代码检查器的 --diff 模式（阶段 1）会列出已更改文件及其更改行数，并且只报告更改行上的问题。

代码库范围 — “审查代码库”、“审核 src/”，或没有提交相关表述的显式路径。对该路径下的 *.cpp、*.h、*.hpp 使用 Glob。

Token 预算规则

这些规则旨在降低审查成本。请遵守。

1. 不要将参考文件加载到主上下文中。 Agent 会自行读取 references/agent-rules.md；你只需传入其绝对路径和章节 ID。只有内联运行（阶段 2）才会在主上下文中读取它。Lint 消息会自我说明；检查清单供人工使用。
2. 以 --summary 格式传递 lint 结果（按规则分组，路径相对于仅打印一次的根目录），绝不传递原始逐行列表。
3. 向 Agent 提供内容所在位置，不要粘贴内容。 你写入提示词的每个 token 都由编排模型输出，是审查中成本最高的 token。提示词只包含路径、命令和章节 ID；Agent 会加载规则、文件和差异。在差异范围内，给 Agent 提供 git diff -U50 <range> -- <files> 命令，而不是差异块；只有为追踪特定符号时才读取其他文件。
4. 根据范围调整 Agent 数量（见阶段 2）。小范围不启动 Agent；大范围则拆分成行数大致相当的分片。
5. 在运行环境提供专用审查 Agent 时使用它。 如果有 cpp-review-agent 定义（通过插件安装时名为 qt-development-skills:cpp-review-agent，手动复制时名为 cpp-review-agent），就使用该定义启动 Agent（只读，工具仅限 Read、Grep、Glob 和只读 Bash）；否则使用运行环境的通用 Agent。该定义位于插件的 agents/ 目录中，不属于此技能；因此，单独复制技能或运行环境未安装 agents/ 时，该定义不可用。然后在每个提示词中添加一行：只读（Bash 仅用于 cat、grep、awk、git diff、git show）；使用打印的数字确定 file:line；差异范围内不要重新读取文件；仅为追踪符号而对其他文件使用 Grep 或 Read；宁可给出少量已确认的问题，也不要给出大量猜测。

执行顺序

绝不跳过任何阶段。

第 1 阶段：确定性 lint 检查

# codebase scope
python3 <skill>/references/lint-scripts/qt_review_lint.py --summary [--framework] <files...>
# diff scope, run inside the repository; no file arguments
python3 <skill>/references/lint-scripts/qt_review_lint.py --summary [--framework] --diff=<range>
# fall back to `python` if python3 is not found

Python 3.7+，无依赖。如果 Python 不可用，请发出警告并继续（在 diff 范围内，从 git diff --stat <range> 获取文件列表）。lint 检查器的结果具有权威性；不要质疑其输出。规则类别：INC、DEP、PAT、MDL、ERR、LCY、API、ENM、TMO、CND、VAL、HDR、TRN、VAR（60+ 项检查）。退出代码 1 仅表示存在问题；2 表示用法或 git 错误。

第 2 阶段：深入分析（内联执行，或每个分片分配一个 Agent）

references/agent-rules.md 中的六个部分就是分析依据。 Agent 会自行读取；仅在内联执行时才需要你自己读取：

部分	任务
A1	模型契约
A2	所有权与生命周期
A3	线程安全
A4	API、命名与 C++ 正确性
A5	错误处理与验证
A6	性能与代码质量

根据范围大小选择并行拆分方式。统计范围内文件的行数（diff 范围内统计变更行数），数据来自 lint 摘要或 wc -l。每个分片约 2,500 行；仅根据行数决定如何拆分，绝不根据文件数量。

范围	Agent 数量
不超过 2,500 行	0（内联执行）
超过 2,500 行	每个分片分配一个 Agent，分片数为 ceil(lines / 2500)

内联执行。 对于小范围，使用 Agent 不划算，因为每个 Agent 都要重新构建上下文，针对相同问题进行审查的 token 成本大约会翻倍。请自行分析：使用下方 Agent 提示词中展示的单次 Bash 调用，读取 references/agent-rules.md 和相关文件（或 diff），并按照相同的规则、置信度阈值和输出格式，一次性应用 A1-A6。不要重复报告 lint 结果，也不要因为代码看起来简单就超出限制内联执行。报告中写明：Agents: 0 (inline)。

分片执行。 按目录顺序将文件划分为 n = ceil(lines / 2500) 个分片，每个分片约含 lines / n 行；每个分片包含多少文件并不重要。如果目录能完整放入一个分片，就不要拆分；这样类的头文件和源文件，以及相互引用的模型和视图都能放在一起；较大的目录则按文件拆分。超过一个分片大小的文件单独占一个分片。每个分片 Agent 仅对自己的分片应用全部六个部分，并且可以 Grep 整个范围来追踪符号。每次最多并行运行六个分片 Agent，其余部分在第二轮运行。跨分片检查（所有权、模型契约、重复逻辑）尽力而为；请在报告标题中注明这一点。

并行启动 Agent，并以其分片命名（例如“Review shard 2/6: src/models”）。提示词保持简短，只包含以下内容：

1. references/agent-rules.md 的绝对路径及要应用的部分 ID（A1-A6）；框架模式下，A2 和 A4 Agent 还需提供 references/qt-framework-checklist.md 的绝对路径

2. lint 摘要中的根目录、相对于该目录的范围内文件；在 diff 范围内，还要提供这些文件对应的 git diff -U50 <range> -- <files> 命令

3. 仅包含该 Agent 自己负责文件的 lint 摘要行（分片 Agent 不需要其他分片的摘要行），并附上指令“不要重复报告这些行”

4. 指示 Agent 在分析前通过单次 Bash 调用加载所有内容，并按照规则文件顶部的格式返回问题。每次工具调用都会重新发送整个 Agent 上下文，因此批量读取一次比逐文件执行一次 Read 更节省资源。在大范围中，这是节省最多的方式。两种方式都会在 file:line 位置中显示每个文件的行号（对多个文件使用 cat -n 时会将它们的行号连续编号，而 git diff 不含行号）：

   # codebase scope
   cd <root> && cat <rules> && for f in <files...>; do echo "== $f"; cat -n "$f"; done
   # diff scope; numbers context and added lines with the new-file line
   cd <root> && cat <rules> && git diff -U50 <range> -- <files> | awk '/^@@/{split($3,a,/[+,]/);n=a[2];h=1;print;next} /^diff /{h=0} h&&/^[ +]/{printf "%5d %s\n",n++,$0;next} {print}'
   

Agent 只能读取内容，绝不能编辑文件。在不支持 Agent 的工具中，请使用该工具支持的提示词链或子进程来执行各项任务；要求相同。

阶段 3：汇总

合并 lint 和 Agent 的发现。按文件 + 行号 + 问题去重。如果重复项的置信度不一致，保留得分最高的项及其追踪记录；切勿对得分取平均值。按以下格式编写报告。

置信度评分

置信度	含义	操作
80-100	通过符号追踪确认违反规则	发现项
60-79	很可能，但无法完全验证（例如，需要全程序分析的 noexcept、可能存在外部调用者的死代码）	调查目标（最多 10 项）
<60	仅为疑点	忽略

输出格式

必须严格采用以下结构。Lint 发现项按规则分组，每项只提供一种缓解措施；只有深度分析的发现项才提供完整区块。

## Qt Code Review Report

**Scope**: [diff: `git diff HEAD~1..HEAD` | files: <paths>]
**Files reviewed**: N
**Issues found**: N (M from lint, K from deep analysis)
**Agents**: N (shards ... | inline)
**Framework mode**: [on / off]

---

### Lint findings

| Rule | Count | Locations | Mitigation |
|---|---|---|---|
| LCY-2 QObject created with new but no parent | 3 | `main.cpp:12,40`, `widget.cpp:88` | Pass a parent or hold in a smart pointer. |
| ... | | | |

---

### Deep analysis findings

#### [D-NNN] <Short title>
- **File**: `path/to/file.cpp:42`
- **Category**: <A1-A6 mission name>
- **Confidence**: NN/100
- **Finding**: <what is wrong>
- **Trace**: <symbols followed, what was checked>
- **Mitigation**: <what to do, in prose — no code patches>

---

### Investigation targets (human verification needed)

#### [I-NNN] <Short title>
- **File**: `path/to/file.cpp:42`
- **Category**: <A1-A6 mission name>
- **Confidence**: NN/100
- **Finding**: <what is suspected>
- **Unverified because**: <what could not be confirmed>
- **How to verify**: <specific action for the reviewer>

---

### Summary

| Category | Lint | Deep | Investigate | Total |
|---|---|---|---|---|
| ... | N | N | N | N |
| **Total** | **M** | **K** | **I** | **N** |

Findings below confidence 60 are suppressed.

参考资料

• references/agent-rules.md — Agent 任务 A1-A6 和 Agent 输出格式（由 Agent 阅读，而非编排器）
• references/qt-review-checklist.md — 通用规则 ID 和理由（供人工参考，审查期间不会加载）
• references/qt-framework-checklist.md — 框架规则（框架模式下由 A2 和 A4 Agent 阅读）
• references/qt-deprecated-classes.md — DEP lint 规则的背景资料（供人工参考）
• references/lint-scripts/qt_review_lint.py — 单次扫描的 linter，--summary 用于分组输出，--diff=<range> 仅针对更改的行，--framework 用于模块规则