qt-qml-review

Qt QML 代码审查

以只读方式审查 Qt6 QML 代码：先运行确定性的 Python 检查器（如有可用，也会整合 qmllint），再由 Agent 对七个规则领域进行深入分析，最后生成一份汇总报告。建议在用户提交 QML 代码前运行审查。

范围检测

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

代码库范围——“审查代码库”“审计 src/”，或未提及提交的显式路径。在该路径下匹配 *.qml。

Token 预算规则

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

1. 不要将参考文件加载到主上下文中。 Agent 会自行读取 references/agent-rules.md；你只需传入其绝对路径和章节 ID。只有内联运行（阶段 2）会在主上下文中读取该文件。Lint 消息会说明自身含义；清单是供人阅读的。
2. 以 --summary 形式传递 lint 结果（按规则分组，路径相对于只打印一次的根目录），绝不要传递逐行原始列表或 qmllint 的 JSON。
3. 让 Agent 自行读取内容，不要粘贴内容。 你写入提示词的每个 Token 都由负责协调的模型生成，这是审查中成本最高的 Token。提示词应包含路径、命令和章节 ID；Agent 会加载规则、文件和差异。在差异范围内，向 Agent 提供 git diff -U50 <range> -- <files> 命令，而不是差异片段；只有为追踪特定符号时，才读取其他文件。
4. 根据范围调整 Agent 数量（见阶段 2）。范围较小时不启动 Agent；范围较大时，将其拆分为行数大致相等的分片。
5. 工具提供专用审查 Agent 时，请使用它。 如果此插件提供的 qt-development-skills:qml-review-agent 定义可用，请使用它启动 Agent（只读，工具仅限 Read、Grep、Glob 和只读 Bash）；否则使用该工具的通用 Agent。

执行顺序

绝不跳过任何阶段。

阶段 1：Lint（Python 检查器 + qmllint）

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

Python 3.7+，无依赖项。如果 Python 不可用，请发出警告并继续（在差异范围内，通过 git diff --stat <range> 获取文件列表）。检查器的结果具有权威性；不要质疑其输出。规则系列：IMP、ORD、BND、LAY、LDR、DEL、STA、IMG、PRF、STY、SIG、ERR、JS（48 项以上检查）。退出码 1 仅表示存在问题；2 表示用法错误或 git 错误。

--qmllint 也会运行 qmllint，并将其警告合并为 QL:<id> 行；若构建目录包含 QML 模块，请添加 --qmllint-args="-I <dir>"。检查器会在 $QT_HOST_PATH/bin、PATH、qtpaths 或 qmake 报告的主机 bin 目录，以及 ~/Qt、C:\Qt 或 /opt/Qt 下 Qt 在线安装程序的最新 Qt 6 工具包中查找 qmllint（路径为 <version>/<kit>/bin；工具包包括 gcc_64、macos、msvc2022_64、mingw_64）。如果检查器报告 not available，但 Qt 安装在其他位置（自定义安装程序路径，或项目 CMakeCache.txt 中的 CMAKE_PREFIX_PATH），请使用 --qmllint=<that kit>/bin 再运行一次；该选项接受二进制文件路径或其 bin 目录。不要继续搜索。将打印出的 qmllint: 状态复制到报告标题中。对于类型级问题，qmllint 具有权威性；对于风格、排序和性能模式，Python 检查器具有权威性。

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

references/agent-rules.md 的七个章节即为分析依据。 Agent 自行阅读；仅在内联执行时由你自行阅读：

章节	任务
A1	绑定与属性
A2	布局与锚定
A3	组件加载与生命周期
A4	ListView 与委托
A5	状态、过渡与迁移
A6	性能与代码质量
A7	逻辑与连线

根据范围大小选择分派方式。统计范围内文件的行数（diff 范围内则统计更改的行数），从 lint 摘要或 wc -l 获取。每个分片约 1,500 行；拆分只依据行数，绝不依据文件数量。

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

内联执行。 小范围不值得投入 Agent；每个 Agent 都要重新构建上下文，对于相同的发现，审查的 token 成本大致会翻倍。自行进行分析：使用下方 Agent 提示词中所示的一次 Bash 调用，读取 references/agent-rules.md 和文件（或 diff），并在同一套规则、置信度阈值和输出格式下，一次性应用 A1-A7。不要重复报告 lint 条目；也不要因为代码看起来简单，就在超出上限时内联执行。报告中写明 Agents: 0 (inline)。

分片。 按目录顺序将文件划分为 n = ceil(lines / 1500) 个分片，每个分片约含 lines / n 行；每个分片包含多少文件并不重要。在可行的情况下，将同一目录放入一个分片，使组件及其实例化文件放在一起；较大的目录则按文件拆分。超过一个分片大小的文件单独分配一个分片。每个分片 Agent 只对自己的分片应用全部七个章节，并可对整个范围运行 Grep，以追踪 id 或模型角色。每次最多并行运行六个分片 Agent，其余 Agent 在第二轮运行。跨分片检查（id、模型角色）尽力而为；在报告标题中说明这一点。

并行启动 Agent，并以对应分片命名（例如 “Review shard 2/6: qml/controls”）。提示词应尽量简短，只包含：

1. references/agent-rules.md 的绝对路径，以及要应用的章节 ID（A1-A7）

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

3. 仅属于该 Agent 自身文件的 lint 摘要行（包括 QL: 行；分片 Agent 不需要其他分片的行），并附上指示：“不要重复报告这些行”

4. 指示：先用一次 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 的发现。按文件、行号和问题去重；若重复项的置信度不一致，则保留分数最高的区块及其追踪记录，绝不对分数取平均。调查目标最多保留 10 个，并将 Agent 的 D-/I- 区块连续重新编号。置信度低于 60 的发现不予保留。按下方格式撰写报告。

输出格式

严格使用以下结构。Lint 和 qmllint 的发现按规则分组，每组仅提供一项缓解措施；只有深入分析的发现才使用完整区块，并从 Agent 的输出中逐字复制。

## QML 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)
**qmllint**: [ran / not available / failed]

---

### Lint findings

| Rule | Count | Locations | Mitigation |
|---|---|---|---|
| IMP-2 Versioned import | 3 | `Main.qml:1,2`, `Panel.qml:1` | Drop the version numbers. |
| ... | | | |

---

### Deep analysis findings

<[D-NNN] blocks from the agents>

---

### Investigation targets (human verification needed)

<[I-NNN] blocks from the agents, at most 10>

---

### 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-A7 及 Agent 输出格式（供 Agent 阅读，协调器不会读取）
• references/qt-qml-review-checklist.md —— 每条 检查规则的依据（供人参考，审查期间不会加载）
• references/lint-scripts/qt_qml_lint.py —— 单次扫描检查器， --summary 用于分组输出，--diff=<range> 仅检查更改的行， --qmllint 用于合并 qmllint，--json 用于工具集成

---

版权所有 (C) 2026 The Qt Company。