需要审查、检查、审计或提交前验证 Qt6 QML 代码时…

适用于对 Qt6 QML 代码做只读、结构化、高置信度的提交前或代码库级审查。

适用场景

解决思路

1. 根据用户语言判断审查范围：若出现 diff/commit 类窄范围语言（如 `this commit`、`these changes`、`the diff`、`what I changed`、`my changes`、`staged changes`、`outstanding changes`、`before I commit`），运行 `git diff`（未暂存）和 `git diff --cached`（已暂存）获取变更集；若用户说 `this commit`，使用 `git diff HEAD~1..HEAD`；仅审查变更行及足够理解所需的 ±50 行上下文；只报告变更行中的问题，不报告未变上下文中的问题。
2. 根据用户语言判断审查范围：若出现宽范围语言（如 `review the codebase`、`audit the project`、`check the repository`、`review src/`），或给出具体文件/目录路径且无提交语言，则按指定范围 Glob 查找 `*.qml` 文件并审查所有匹配文件。
3. 审查按三阶段执行，绝不跳过任一阶段。
4. Phase 1 确定性 linting：对目标文件运行统一 Python linter；要求 Python 3.6+（无外部依赖）；若 Python 不可用，警告用户并跳到 Phase 1b。
5. 运行 `python3 references/lint-scripts/qt_qml_lint.py <files...>`；若找不到 `python3`，回退运行 `python references/lint-scripts/qt_qml_lint.py <files...>`。
6. 该单遍扫描器编码 QML 审查清单中所有可机械检查规则；每个文件读取一次，逐行评估所有规则，并做块级结构检查；输出确定且可重复；linter 是权威，不要二次猜测其输出；继续前收集所有输出。
7. Phase 1 规则类别（47+ 检查）：IMP（Imports）——导入顺序、版本、冗余、弃用；ORD（Ordering）——QML 属性顺序约定；BND（Bindings）——property var、命令式 `=`、`Qt.binding` 风格；LAY（Layout）——anchors/Layout 混用、布局中尺寸；LDR（Loader）——状态守卫、`createComponent`、`createQmlObject`；DEL（Delegates）——required properties、复用安全、`connect()`；STA（States）——`PropertyChanges` 语法、transitions、`StateGroup`；IMG（Images）——`sourceSize`、异步加载；PRF（Performance）——透明 rect、opacity、clip、layer；STY（Style）——`id: root`、camelCase、group notation；SIG（Signals）——`Connections` target、handler 语法；ERR（Error/Security）——硬编码 `http://`、不可移植路径；JS（JavaScript）——`var`/`let`/`const`、松散相等。
8. Phase 1b 系统 `qmllint`（可选）：尝试运行系统可用的 `qmllint`；检测顺序：`$QT_HOST_PATH/bin/qmllint`；`which qmllint` / `where qmllint`；若未找到则跳过并警告用户。
9. 若找到 `qmllint`，运行 `qmllint --json - -I <import-paths> <files...>`；解析 JSON 输出并与 Python linter 发现合并；按 file+line+issue 去重；`qmllint` 对类型级检查权威（未解析类型、不兼容赋值、alias 循环）；Python linter 对 qmllint 不覆盖的样式、顺序和性能模式权威。
10. Phase 2 Agent 驱动深度分析：并行启动六个聚焦审查 agent；启动时给每个 agent 描述性名称（如 `Agent 1: Bindings & Properties`）以提供进度可见性；每个 agent 有严格范围和具体清单；agent 只读，绝不能编辑或写文件。
11. 工具无关 agent 契约：每个 agent 是自包含审查任务；在 Claude Code 中作为 general-purpose subagents 启动；在其他工具中实现为工具支持的任何子进程、prompt chain 或分析 pass；关键要求：对范围内所有源文件有读权限；能 search/grep 代码库追踪符号；按下方结构化格式报告发现；应用置信度阈值：>80 = 已确认发现，60-79 = investigation target（所有 agent 合计最多 10 个），<60 = 抑制；不得重复 Phase 1 lint 输出中的发现（将 lint 输出作为上下文传给每个 agent）。
12. Phase 3 合并与报告：合并 lint 脚本输出、qmllint 输出（如有）和所有 agent 发现；去重（相同 file+line+issue = 一个发现）；应用置信度评分；按输出格式生成最终报告。
13. 启动所有六个 agent 时，传给每个 agent：范围内文件列表；Phase 1 lint 输出（使其跳过已标记问题）；Phase 1b qmllint 输出（如有）；其具体任务。每个 agent 应读取范围内所有文件，然后聚焦分配类别。
14. Agent 1 Bindings & Properties：范围包括绑定正确性、属性类型、alias 链、限定查找、绑定循环。检查：多周期绑定循环（A 通过 handler 改变 B，B 的绑定更新 A）——运行时只检测单周期；property alias 链（alias 到 alias）其中中间组件可能未初始化；未限定属性访问（裸 `someProperty` 而非 `root.someProperty`）——用语义上下文补充 qmllint `unqualified` 警告；`Qt.binding()` 闭包按引用捕获循环变量（用 `let` 而非 `var`）；访问外部作用域 id 的 delegates 文件缺少 `pragma ComponentBehavior: Bound`；被绑定但从未命令式赋值的属性缺少 `readonly`。参考 `references/qt-qml-review-checklist.md` 第 3 节（Bindings & Properties）。
15. Agent 2 Layout & Anchoring：范围包括 anchoring 正确性、布局尺寸、视觉树结构。检查：锚定到 `visible: false` 的 item（解析目标 id，检查其 `visible` 属性）；跨不相关视觉树分支锚定（不共享共同 parent）；Layout 中的 item 使用 `implicitWidth`/`implicitHeight` 绑定可能产生反馈循环；应拉伸的 item 缺少 `Layout.fillWidth`/`Layout.fillHeight`；嵌套 Layout 没有清晰 sizing policy（模糊尺寸协商）。参考 `references/qt-qml-review-checklist.md` 第 4 节。
16. Agent 3 Component Loading & Lifecycle：范围包括 Loader 模式、动态对象创建、Connections 生命周期、C++ 集成。检查：`Component.createObject()` 返回值未跟踪或销毁（内存泄漏）；Loader 在运行时在 `source` 和 `sourceComponent` 之间切换（不支持）；动态/网络源 Image 缺少 `Image.status` 错误处理；`Connections` 的 `target` 动态变化时未处理 `null` target 状态；C++ 集成代码中的 context properties（`rootContext()->setContextProperty()`）；QML/C++ 边界对象所有权问题（invokable 函数返回的无 parent 对象）。参考 `references/qt-qml-review-checklist.md` 第 5、8、13 节。
17. Agent 4 ListView & Delegate Correctness：范围包括 model-view 模式、delegate 生命周期、复用安全、required properties。检查：在声明其他 required properties 的 delegate 中使用 `index` 却缺少 `required property int index`；delegate 访问 `model.roleName` 但角色未在模型 `roleNames()` 中定义；复杂 delegates（嵌套 Repeaters、多个 Loaders、重绑定）会降低滚动性能；`currentIndex` 使用未针对已知 Qt bug 加守卫（QTBUG-48633、QTBUG-93293）；`DelegateChooser` 模式可能在非 QAbstractItemModel 上失败（choice 创建时做一次，不会重新评估）；池化 delegates 保持可见（缺少 `onPooled: visible = false` 模式）。参考 `references/qt-qml-review-checklist.md` 第 6 节。
18. Agent 5 States, Transitions & Structure：范围包括状态机正确性、迁移模式、组件结构。检查：`PropertyChanges.restoreEntryValues` 意外（状态退出时属性回退，而开发者期望保留）；Qt 5 迁移导致 `Binding.restoreMode` 不匹配（默认从 `RestoreNone` 改为 `RestoreBindingOrValue`）；迁移代码中弃用的 `Connections` handler 语法（`onFoo:`）与现代 `function onFoo()`；应迁移到 `MultiEffect`（Qt 6.5+）的 `QtGraphicalEffects` imports；应使用 `StateGroup` 以提升可复用性的顶层组件状态；transitions 缺少 `from`/`to`，新增状态时可能意外触发。参考 `references/qt-qml-review-checklist.md` 第 7、14 节。
19. Agent 6 Performance & Code Quality：范围包括性能反模式、渲染成本、JavaScript 质量、样式一致性。检查：属性绑定中的昂贵表达式（应缓存为 `readonly property` 的函数调用）；循环中的 `QRegularExpression` 或复杂计算；不需要富文本时缺少 `Text.PlainText`（默认 `textFormat` 产生解析开销）；`font.preferShaping: false` 机会（未使用文本 shaping 功能时）；向下通信的 signals（应为 functions）或向上通信的 functions（应为 signals）；从未引用的对象上不必要的 `id` 赋值；自定义属性分散在各 item 而非合并到 `QtObject { id: privates }`；用于数据的 singletons（应使用 property injection 以便测试）；pointer handler 机会（MouseArea 应改为 TapHandler/DragHandler 以支持多点触控）；可复用组件使用显式 `width`/`height` 而非 `implicitWidth`/`implicitHeight`（阻止消费者调整大小）；delegates 或 Loader items 中使用 `parent` 未做 null-check（创建/销毁期间可能为 null）；访问外部作用域 id 的 delegates 文件缺少 `pragma ComponentBehavior: Bound`。参考 `references/qt-qml-review-checklist.md` 第 9、10、11、12、13 节。
20. 置信度评分：90-100 确定：直接规则违规且完整追踪，报告为 finding；80-89 高：规则违规确认但可能边缘情况，报告为 finding；60-79 中：可能问题但无法完全验证，作为 investigation target；<60 低：仅怀疑，完全抑制。
21. Investigation targets：agent 认为真实但无法完全验证的发现；单独章节供人工验证；每份报告最多 10 个，按 60-79 置信度带内优先级排序。
22. 最终报告格式：严格使用如下结构：`## 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)`；`**qmllint**: [ran / not available]`。
23. Lint findings：每个 lint 发现使用 `#### [L-NNN] <Short title>`，包含 `- **File**: `path/to/file.qml:42``、`- **Rule**: <rule ID from checklist>`、`- **Finding**: <what the script detected>`、`- **Mitigation**: <what to do, in prose -- no code patches>`。
24. Deep analysis findings：每个 agent 发现使用 `#### [D-NNN] <Short title>`，包含 `- **File**: `path/to/file.qml:42``、`- **Category**: <agent name: Bindings & Properties | Layout & Anchoring | Component Loading & Lifecycle | ListView & Delegates | States & Structure | Performance & Quality>`、`- **Confidence**: NN/100`、`- **Finding**: <description of the issue>`、`- **Trace**: <how the issue was confirmed -- which symbols were followed, what was checked>`、`- **Mitigation**: <what to do, in prose -- no code patches>`。
25. Investigation targets 格式：`#### [I-NNN] <Short title>`，包含 `- **File**: `path/to/file.qml:42``、`- **Category**: <agent name>`、`- **Confidence**: NN/100`、`- **Finding**: <what the agent suspects>`、`- **Unverified because**: <what the agent could not confirm>`、`- **How to verify**: <specific action for the reviewer>`。
26. Summary 表格：| Category | Lint | Deep | Investigate | Total |；含表头和总计行；置信度低于 60 的发现完全抑制。
27. 使用参考文件：`references/qt-qml-review-checklist.md`（完整 QML 审查规则，lint + agent 规则，始终加载）；`references/lint-scripts/qt_qml_lint.py`（单遍 Python linter，<1s 运行所有 47+ 检查）。

适用边界 · 注意事项

• 不适用于非 Qt6 QML 代码或与 QML 无关的代码审查。
• 需要自动修改、修复或重写代码时不适用，因为该技能只读，从不修改代码。
• 环境没有 Python 且需要完整 47+ 条确定性 lint 规则时不适用；Phase 1 无法执行，只能跳过到 Phase 1b 或深度分析。