Chrysopoeia

点金术

系统性地从现有代码中提取最大价值——识别什么是黄金（高价值、设计良好）、什么是铅（资源密集、优化不佳）、什么是渣滓（死代码）。然后放大黄金、转化铅块、清除渣滓。

适用场景

• 优化运行正常但缓慢的代码库以提升性能
• 精炼经过多次迭代积累了冗余的 API 表面
• 减少包体积、内存占用或启动时间
• 为开源发布准备代码（提取有价值的核心）
• 当代码正确运行但不够出色——需要打磨，而非重写

输入

• 必需：需要优化的代码库或模块（文件路径）
• 必需：价值度量标准（性能、API 清晰度、包体积、可读性）
• 可选：显示当前性能的分析数据或基准测试
• 可选：预算或目标（例如"减少 40% 的包体积"、"响应时间低于 100ms"）
• 可选：约束条件（不能更改公共 API、必须保持向后兼容）

步骤

第 1 步：化验——分类材料

系统性地按价值贡献对每个元素进行分类。

1. 从输入中定义价值度量标准（性能、清晰度、体积等）
2. 盘点代码库元素（函数、模块、导出、依赖）
3. 对每个元素进行分类：

Value Classification:
+--------+---------------------------------------------------------+
| Gold   | High value, well-designed. Amplify and protect.         |
| Silver | Good value, minor imperfections. Polish.                |
| Lead   | Functional but heavy — poor performance, complex API.   |
|        | Transmute into something lighter.                       |
| Dross  | Dead code, unused exports, vestigial features.          |
|        | Remove entirely.                                        |
+--------+---------------------------------------------------------+

4. 对于性能优化，先进行分析：
   • 识别热路径（时间花费在哪里）
   • 识别冷路径（很少执行的代码，可能是渣滓）
   • 测量内存分配模式
5. 生成化验报告：逐元素分类并附带证据

预期结果： 每个重要元素都有证据支持的分类。黄金元素已被识别，在优化过程中予以保护。铅元素按影响程度排列优先级。

失败处理： 如果没有可用的分析工具，使用静态分析：函数复杂度（圈复杂度）、依赖计数和代码体积作为替代指标。如果代码库太大，先关注关键路径。

第 2 步：精炼——放大黄金

保护和增强最高价值的元素。

1. 对每个黄金元素：
   • 确保它有全面的测试（这些是你最有价值的资产）
   • 如果尚未完成，清晰地记录其接口
   • 考虑是否可以将其提取为可复用模块
2. 对每个白银元素：
   • 应用有针对性的改进（更好的命名、更清晰的类型、微小的优化）
   • 将测试覆盖率提升到黄金级别
   • 解决轻微的代码异味，不进行重构
3. 不修改黄金/白银的行为——只改善其打磨和保护

预期结果： 黄金和白银元素经过更好的测试、文档和保护。没有行为变更，仅有质量改进。

失败处理： 如果"黄金"元素在更仔细检查后暴露出隐藏问题，重新分类它。诚实面对价值比保护有缺陷的代码更好。

第 3 步：转化——将铅变为金

将笨重、低效的元素转化为优化的等价物。

1. 按影响排列铅元素的优先级（最高资源消耗优先）
2. 对每个铅元素，选择转化策略：
   • 算法优化：用 O(n log n) 替换 O(n^2)，消除冗余计算
   • 缓存/记忆化：存储被重复请求的昂贵结果
   • 惰性求值：将计算推迟到结果实际需要时
   • 批处理：将许多小操作合并为更少的大操作
   • 结构简化：降低圈复杂度，展平深层嵌套
3. 应用策略并测量改进：
   • 性能变化的前后基准测试
   • 复杂度变化的前后行数统计
   • 耦合变化的前后依赖计数
4. 在每次转化后验证行为等价性

预期结果： 目标价值度量标准上的可测量改进。每个被转化的元素在保持相同行为的同时，性能优于其铅前身。

失败处理： 如果铅元素在其当前接口内抵抗优化，考虑接口本身是否是问题。有时转化需要改变元素的调用方式，而不仅仅是其实现方式。

第 4 步：清除——去除渣滓

系统性地消除死代码。

1. 对每个渣滓元素，验证它确实未被使用：
   • 搜索所有引用（grep、IDE 查找用法）
   • 检查动态引用（基于字符串的调度、反射）
   • 检查外部消费者（如果代码是库）
2. 移除确认的渣滓：
   • 删除死代码、未使用的导出、残留功能
   • 从包清单中移除未使用的依赖
   • 清理已移除功能的配置
3. 在每次移除后验证没有破坏（运行测试）
4. 记录移除了什么以及原因（在提交信息中，而非代码中）

预期结果： 代码库更轻量。包体积、依赖计数或代码量可测量地减少。所有测试仍然通过。

失败处理： 如果移除某个元素破坏了什么，它不是渣滓——重新分类它。如果动态引用使验证使用情况困难，在删除前添加临时日志以确认没有运行时访问。

第 5 步：验证——称量黄金

测量整体改进。

1. 运行与第 1 步相同的基准测试/指标
2. 比较目标价值度量标准的前后数据
3. 记录点金术的结果：
   • 精炼的元素（黄金/白银改进）
   • 转化的元素（铅到金的转换及测量数据）
   • 清除的元素（渣滓移除及体积/计数影响）
   • 整体指标改进（例如"快 47%"、"包体积小 32%"）

预期结果： 目标价值度量标准上可测量、有文档的改进。代码库明显比之前更有价值。

失败处理： 如果整体改进微乎其微，原始代码可能比假设的更好。记录学到了什么——知道代码已经接近最优本身就是有价值的。

验证清单

• 化验报告对所有重要元素进行了有证据的分类
• 黄金元素有全面的测试和文档
• 铅转化显示了可测量的前后改进
• 渣滓移除在删除前经过引用检查验证
• 每个阶段后所有测试通过
• 整体改进已测量和记录
• 未引入行为回归
• 满足输入中的约束条件

常见问题

• 过早优化：不分析就优化。始终先测量，优化热路径
• 打磨渣滓：花精力改进应该被删除的代码。先分类再精炼
• 破坏黄金：优化降级了最好的代码。黄金元素应该只变更好，绝不变差
• 未量化的声明："感觉更快了"不是点金术。每个改进都必须量化
• 优化冷路径：在启动时只运行一次的代码上花精力，而瓶颈在请求循环中

相关技能

• athanor — 当点金术揭示代码需要重构而非仅优化时的完整四阶段转化
• transmute — 当铅元素需要范式转变时的定向转换
• review-software-architecture — 架构级别的评估，与代码级别的点金术互补
• review-data-analysis — 数据流水线优化与代码优化并行