complexity-optimizer

复杂度优化器

核心原则

只有在理解当前行为且能够保留该行为时，才进行优化。相比范围广泛、正确性不明确的重写，优先选择经过测试的小幅改进。

默认行为

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

报告默认包含以下内容：

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

只有当用户要求实现、修复、优化、应用、修改、重构或以其他明确方式要求修改代码时，才编辑文件。如果用户只要求分析或报告，则不要修改文件。

工作流

1. 确定基线：

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

2. 排序优化机会：

   • 优先关注热点路径、大输入路径、渲染循环、数据库/API 循环和共享工具。
   • 区分算法复杂度优化与常数因子层面的清理。
   • 不要处理每一条警告。将扫描器输出视为线索，而非证明。
   • 对于仅要求报告的请求，应检查足够多的上下文代码，以估算当前和建议方案的复杂度；不要只停留在原始扫描器输出。

3. 验证行为：

   • 为要修改的函数或组件找到或添加有针对性的测试。
   • 覆盖边界情况：空输入、重复项、顺序稳定性、null/缺失值、错误、权限、分页、时区和副作用。
   • 如果缺少测试且行为不明确，应采用最小幅度的重构，或在改变语义前询问预期行为。

4. 谨慎优化：

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

5. 验证：

   • 运行相关测试以及类型检查、lint 和构建命令。
   • 如果复杂度改进不明显或对性能至关重要，则添加微基准测试或进行测量。
   • 报告原始复杂度、新复杂度、修改的文件、运行的测试以及任何残余风险。

第一轮扫描器

使用技能目录中附带的扫描器：

python3 scripts/analyze_complexity.py /path/to/repo --format markdown
python3 scripts/analyze_complexity.py /path/to/repo --format json

扫描器会标记 Python、JavaScript、TypeScript、JSX/TSX、Java、Go、C、C++、C#、Ruby、PHP 和 Swift 文件中的常见模式。它有意优先提供易读的线索，而非追求完美的静态分析。

如果扫描器没有报告任何问题，仍应手动检查已知热点路径。渲染频繁变动、数据库查询模式和框架生命周期问题，往往需要结合代码库的具体上下文进行分析。

优化安全检查清单

编辑前：

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

编辑后：

• 先运行针对性测试，再运行最广泛的相关测试或构建命令。
• 如果已有或新增基准测试，对比优化前后的基准数据。
• 将补丁限制在相关范围内。避免对无关文件进行格式调整。

参考资料

• 阅读 references/optimization-playbook.md，了解常见的 O(n^2) 到 O(n log n) / O(n) 转换，以及特定框架的模式。
• 准备最终分析或审计输出时，阅读 references/report-template.md。