complexity-optimizer

复杂度优化器

查找代码库中的算法复杂度热点，并生成结构化报告。征得明确同意后，可选择实施低风险优化。

适用场景

当用户要求以下操作时，使用此技能：

• 分析、审计、扫描或审查代码库中的性能热点或算法复杂度
• 查找低效循环、嵌套迭代、N+1 查询、循环内排序、渲染路径重复计算
• 降低复杂度（例如，从 O(n^2) 降至 O(n log n) 或 O(n)）
• 获取代码库复杂度概况的报告

以下情况不要使用此技能：

• 对冷代码路径进行微优化
• 内存调优（此技能关注时间复杂度，而非分配情况）
• 与复杂度无关的代码风格重构

工作流概览

Baseline → Rank → Prove behavior → Optimize (opt-in) → Verify
   ↓           ↓                       ↓
 scanner   prioritize hot          rollback if
 + manual  paths & large I/O       tests regress

步骤	操作	工具	风险
1	建立基线：检测技术栈、测试命令和热点路径	scripts/analyze_complexity.py + 手动检查	只读
2	按影响排序机会，区分算法层面的收益与常数因子优化	推理	只读
3	定位或添加覆盖该函数/组件的测试	阅读 + 测试框架	只读
4	应用优化（仅限用户明确提出请求时）	Edit/Write	破坏性
5	运行测试、lint、类型检查；必要时运行基准测试，并报告优化前后的复杂度	Bash 测试命令	只读

核心规则

只有在了解当前行为并能够保持行为不变时才进行优化。相比范围较广且正确性不明确的重写，应优先选择经过测试的小幅可靠改进。

默认行为

当用户要求分析、扫描、审计、审查代码库，或“给我一份报告”时，自动生成完整的复杂度报告。不要要求用户指定报告字段。

默认报告内容（见 references/report-template.md）：

• 分析范围以及检测到的技术栈/测试命令
• 按可能影响排序的主要发现
• 每项发现对应的文件和行号
• 当前模式及其可能造成高开销的原因
• 估算的当前复杂度
• 建议的改动及改动后的估算复杂度
• 风险级别
• 所需测试、基准测试或手动检查
• 明确说明未修改任何文件，除非用户明确要求实施

只有当用户使用明确的编辑动词时，才编辑文件：implement、fix、optimize、apply、change、refactor。如果请求仅涉及分析或报告，则不要修改文件。

工作流详情

1. 建立基线

• 确定语言、框架、测试命令、构建命令以及对性能敏感的路径。
• 修改代码前检查现有测试。
• 扫描代码库时，运行 python3 scripts/analyze_complexity.py <repo> 获取第一轮热点列表。

2. 排序

• 优先关注热点路径、大输入路径、渲染循环、数据库/API 循环及共享工具。
• 区分算法复杂度优化与常数因子优化。
• 将扫描器输出视为线索，而非结论。
• 对于仅需报告的请求，应检查足够多的上下文代码，以估算当前复杂度和建议改动后的复杂度。不要止步于原始扫描器输出。

3. 验证行为

• 定位或添加针对待修改函数/组件的专门测试。
• 覆盖边缘情况：空输入、重复项、顺序稳定性、空值/缺失值、错误、权限、分页、时区和变更副作用。
• 如果缺少测试且行为存在歧义，应进行尽可能小的重构，或在改变语义前询问预期行为。

4. 优化（仅在明确要求时）

• 当键的相等性稳定时，用映射／集合替换重复的线性查找。
• 仅当数据形态支持时，用索引、分组、双指针扫描、扫描线逻辑、二分查找、记忆化、批处理或预计算替换嵌套扫描。
• 在 UI 代码中，使用稳定的属性、记忆化的派生数据、虚拟化、去抖处理，并将开销大的工作移出渲染路径，以减少不必要的渲染。
• 在数据访问代码中，使用批量获取、联接、预加载、缓存或批处理消除 N+1 查询，同时保留授权和筛选逻辑。

5. 验证

• 运行相关测试以及类型检查、lint 和构建命令。
• 当复杂度提升不明显或性能至关重要时，添加微基准测试或测量。
• 报告原始复杂度、新复杂度、变更文件、运行的测试以及任何剩余风险。

首轮扫描器

python3 scripts/analyze_complexity.py /path/to/repo --format markdown
python3 scripts/analyze_complexity.py /path/to/repo --format json
python3 scripts/analyze_complexity.py /path/to/repo --changed-only --base origin/main

--changed-only 会将扫描范围限制为相对于 --base（默认为 HEAD~1）发生变更的文件。用于针对 PR 的复杂度审查。

语言分析深度：

• Python（.py）——基于 AST 的分析。精度高：使用 Python ast 模块，按函数追踪嵌套循环、循环中的排序／成员检查、循环中的查询／I/O。
• 所有其他受支持的语言（.js、.ts、.jsx、.tsx、.java、.go、.rb、.php、.cs、.c、.cpp、.swift、.vue、.svelte、.kt、.rs、.dart、.scala）——使用基于正则表达式的模式匹配，并结合缩进和函数边界启发式规则。将发现结果视为线索；在建议修复前，先阅读周边代码进行核实。

如果扫描器没有报告任何结果，仍应手动检查已知的热点路径。渲染抖动、数据库查询模式和框架生命周期问题，通常需要扫描器无法获取的仓库上下文。

退出代码：0 = 扫描成功，2 = 输入无效（路径不存在／输入的是文件而非目录／Git 错误），3 = 匹配到 0 个文件，130 = 已中断。

**报告前进行分类：**查看 references/false-positives.md，排除已知的噪声模式（单次调用的谓词、Redux 选择器、SQL 构建器的链式方法、对小型静态数组执行的渲染派生工作），然后再建议修复。

测试扫描器：python3 scripts/test_analyze_complexity.py 会运行 13 项回归测试，以固定误报修复。修改扫描器后请运行此测试。

优化安全检查清单

编辑前：

• 确认数据量足够大，复杂度问题确实重要。
• 确认优化能保留调用方可能依赖的输出顺序。
• 确认对象标识、可变性和引用共享不属于公开行为的一部分。
• 确认缓存具有有效的失效策略。
• 确认去重不会合并显示标签相同但实际不同的记录。
• 确认数据库批处理能保留租户、权限、软删除、分页和排序约束。

编辑后：

• 先运行范围最小的相关测试，再运行更广泛的构建／lint／类型检查。
• 如果已有或新增了基准测试，请比较修改前后的数据。
• 保持补丁范围集中，避免无关文件出现格式变更。

回滚

如果优化导致测试失败或改变了可观察行为：

1. 立即还原已变更的文件：

   git restore <file>           # restore a single file
   git restore -SW <file>       # restore both index and working tree
   

   如果修改了多个文件：git restore -SW .（仅在受影响的目录中执行）。

2. 重新运行失败的测试，确认已还原。

3. 向用户报告失败情况，包括：

   • 失败的确切测试／断言
   • 出现差异的语义（顺序、变更、键相等性等）
   • 是使用不同的转换方式重试，还是保留原始代码

4. 不要稍作改动后再次尝试相同的优化。如果某种转换破坏了行为，说明数据形态不适合该转换，或者存在未说明的不变量——再次尝试前请重新阅读代码。

参考资料

• references/optimization-playbook.md — 常见的 O(n^2) → O(n log n) / O(n) 转换、框架特定模式，以及“不要做什么”。
• references/report-template.md — 最终分析或审计输出的结构。
• references/false-positives.md — 扫描器发现的看似真实但实际并非如此的问题目录。建议修复前请先查阅。
• scripts/_sections.md — 扫描器调用方式、标志、退出代码和限制。