ln-812-query-optimizer

路径： 文件路径（shared/、references/、../ln-*）均相对于技能仓库根目录。如果在 CWD 中找不到，请定位此 SKILL.md 所在目录，并向上一级查找仓库根目录。

ln-812-query-optimizer

类型： L3 Worker 类别： 8XX 优化 父级： ln-810-performance-optimization-coordinator

修复 ln-651-query-efficiency-auditor 发现的查询效率问题。每项修复都会通过测试验证，并采用保留/丢弃模式。指标：查询次数减少（而非运行时基准测试）。

---

概述

方面	详情
输入	docs/project/persistence_audit.md 中的审计发现（ln-651 部分），或目标文件
输出	优化后的查询、验证报告
配套工具	ln-651-query-efficiency-auditor（发现问题）→ ln-812（修复问题）

---

工作流

阶段： 预检 → 加载发现 → 排定优先级 → 修复循环 → 报告

---

阶段 0：预检

检查项	必需	缺失时的操作
审计发现或目标文件	是	阻止优化
测试基础设施	是	阻止（验证需要测试）
Git 工作区干净	是	阻止（回滚需要干净的基线）

必须阅读： 加载 shared/references/ci_tool_detection.md — 使用其中的测试框架部分检测测试。

工作树与分支隔离

必须阅读： 加载 shared/references/git_worktree_fallback.md — 使用 ln-812 对应行。

---

阶段 1：加载发现

从审计报告加载

读取 docs/project/persistence_audit.md，提取 ln-651 的发现：

发现类型	优化方式
N+1 查询	批量加载 / 预加载 / .Include() / prefetch_related
冗余获取	传递对象而非 ID，缓存结果
过量获取	选择特定字段 / 投影 / .Select()
缺少索引提示	添加索引注解 / 迁移
无界查询	添加 .Take() / LIMIT / 分页

从目标文件加载

如果没有审计报告：扫描目标文件，查找与上表匹配的查询模式。

---

阶段 2：确定修复优先级

优先级	标准
1（最高）	热路径中的 N+1（每次请求都会调用）
2	冗余获取（同一实体被多次加载）
3	过量获取（只需少数列却使用 SELECT *）
4	面向用户的端点缺少分页

---

阶段 3：修复循环（保留/丢弃）

单项修复周期

FOR each finding (F1..FN):
  1. APPLY: Edit query code (surgical change)
  2. VERIFY: Run tests
     IF tests FAIL → DISCARD (revert) → next finding
  3. VERIFY: Tests PASS → KEEP
  4. LOG: Record fix for report

保留/丢弃决策

条件	决策
没有测试覆盖受影响的文件/函数	跳过该发现 — 记录为“未覆盖，已跳过”
测试通过	保留
测试失败	丢弃 + 记录失败原因
修复引入新的 N+1	丢弃

注意： 无需基准测试 — 查询优化指标是正确性（测试通过）+ 结构改进（查询更少）。审计已经识别出低效之处。

---

阶段 4：报告结果

报告架构

字段	描述
source	审计报告路径或目标文件
findings_total	审计发现总数
fixes_applied	成功保留的修复
fixes_discarded	因失败而丢弃的修复及原因
fix_details[]	每项修复：发现类型、文件、修复前后说明

---

配置

Options:
  # Source
  audit_report: "docs/project/persistence_audit.md"
  target_file: ""               # Alternative to audit report

  # Verification
  run_tests: true

  # Scope
  fix_types:                    # Filter which types to fix
    - n_plus_one
    - redundant_fetch
    - over_fetching
    - unbounded_query

---

错误处理

错误	原因	解决方案
没有审计发现	未运行 ln-651 或未发现问题	报告“没有可优化的发现”
ORM 专属语法	未知 ORM	查询 Context7/Ref 获取 ORM 文档
需要迁移	添加索引需要迁移	记录为手动步骤，并跳过

---

参考

• ../ln-651-query-efficiency-auditor/SKILL.md（配套工具：发现问题）
• shared/references/ci_tool_detection.md（测试检测）

---

完成定义

• 已从审计报告或目标文件扫描中加载发现的问题
• 已按优先级处理修复（先处理 N+1，然后是冗余、过度获取和无界查询）
• 每项修复均已应用，并通过保留或丢弃进行处理：测试通过 → 保留；测试失败 → 丢弃
• 修复未引入新的查询低效问题
• 已返回报告，其中包含发现的问题总数、已应用的修复数和已丢弃的修复数

---

版本： 1.0.0 最后更新： 2026-03-08