炼金炉

执行代码或数据的四阶段炼金术嬗变——分解原始材料、净化其精华、照亮其目标形态、合成精炼的输出。炼金炉（athanor）是在所有阶段维持稳定热量的熔炉。

适用场景

• 将遗留代码转化为现代、结构良好的等价物
• 重构渐进式修复不断失败的深度纠缠模块
• 将代码库从一种范式转换为另一种（过程式到函数式、单体到模块化）
• 将原始、混乱的数据处理成干净的分析数据集
• 当更简单的重构方法已停滞，需要全周期转化时

输入

• 必需：要转化的材料（文件路径、模块名称或数据源）
• 必需：期望的最终状态（目标架构、范式或格式）
• 可选：已知约束（必须保留 API、不能更改数据库模式等）
• 可选：先前失败的转化尝试及其停滞原因

步骤

第 1 步：黑化（Nigredo）——分解

将原始材料分解为其组成元素。没有什么是神圣的；一切都需要编目。

1. 完整清点材料：
   • 列出每个函数、类、模块或数据实体
   • 映射所有依赖关系（导入、调用、数据流）
   • 识别隐藏的耦合（共享全局变量、隐式状态、副作用）
2. 浮现隐藏的假设：
   • 代码依赖哪些未记录的行为？
   • 哪些错误条件被静默吞噬？
   • 存在哪些排序依赖？
3. 编目反模式和技术债务：
   • 上帝对象、循环依赖、复制粘贴重复
   • 死代码路径、不可达分支、残余功能
   • 硬编码值、魔术数字、嵌入式配置
4. 产出黑化清单：每个元素、依赖关系、假设和反模式的结构化目录

预期结果： 一份完整、毫不留情的材料清单。清单应该令人不适——如果不是，分解就不够彻底。每个隐藏的假设现在都是显式的。

失败处理： 如果材料太大无法完全清点，按模块边界分解，将每个模块作为单独的炼金炉运行。如果依赖关系过于纠缠无法映射，使用

grep

/

Grep

追踪实际调用点，而不是依赖文档。

第 2 步：冥想（Meditate）——煅烧检查点

运行

meditate

技能以清除黑化阶段积累的假设。

1. 放下黑化清单，清除心理上下文
2. 锚定在输入中声明的转化目标
3. 观察黑化引入了什么偏见——分解是否使某些方法看起来不可避免？
4. 将任何过早的解决方案想法标记为"切线"并回到目标

预期结果： 一种清晰、无偏见的状态，准备在不被锚定到当前形态的情况下评估材料。目标感觉新鲜而非被发现所约束。

失败处理： 如果黑化的发现持续吸引注意力（一个特别糟糕的反模式、一个诱人想要保留的巧妙技巧），写下来并明确搁置。只有当目标比当前形态更清晰时才继续。

第 3 步：白化（Albedo）——净化

将本质的与偶然的分离。剥离一切不服务于目标形态的东西。

1. 从黑化清单中，对每个元素分类：
   • 本质的：核心业务逻辑、不可替代的算法、关键数据转换
   • 偶然的：框架样板代码、旧错误的变通方案、兼容性垫片
   • 有毒的：反模式、安全漏洞、死代码
2. 将本质元素提取到隔离状态：
   • 从框架包装器中提取核心逻辑
   • 将数据转换与 I/O 分离
   • 从实现中提取接口
3. 完全移除有毒元素——记录什么被移除以及原因
4. 对于偶然元素，确定目标形态中是否存在等价物
5. 产出白化提取物：具有干净接口的净化本质逻辑

预期结果： 一组代表原始材料核心价值的纯净、隔离的函数/模块。每个部分都可以独立测试。提取物应明显小于原始材料。

失败处理： 如果本质与偶然过于交织无法分离，先引入接缝点（接口）。如果材料抗拒净化，可能需要先用

dissolve-form

处理后才能继续炼金炉流程。

第 4 步：修复（Heal）——净化评估

运行

heal

技能以评估净化是否彻底。

1. 分诊白化提取物：是否还有任何东西携带有毒残留？
2. 检查偏移：净化是否偏离了原始转化目标？
3. 评估完整性：所有本质元素是否都已计入，还是有些被过早丢弃？
4. 如需要则重新平衡：恢复被错误分类为偶然的本质元素

预期结果： 确信白化提取物是完整、干净的，且已准备好进入照明阶段。没有本质逻辑丢失；没有有毒模式残留。

失败处理： 如果评估揭示出重大缺口，带着具体缺口返回第 3 步。不要在材料不完整的情况下进入黄化阶段。

第 5 步：黄化（Citrinitas）——照明

看见目标形态。将净化的元素映射到其最优结构。

1. 模式识别：识别哪些设计模式服务于净化的元素
   • 数据流是否暗示管道/过滤器、事件溯源、CQRS？
   • 接口是否暗示策略、适配器、外观模式？
   • 模块结构是否暗示六角形、分层、微内核？
2. 设计目标架构：
   • 将每个本质元素映射到其新位置
   • 定义组件间的接口
   • 指定数据通过新结构的流动方式
3. 识别必须新创建的内容（在原始材料中没有等价物）：
   • 统一重复逻辑的新抽象
   • 替代隐式耦合的新接口
   • 替代静默失败的新错误处理
4. 产出黄化蓝图：从白化提取物到目标形态的完整映射

预期结果： 一份清晰、详细的蓝图，其中每个本质元素都有归属，每个接口都有定义。蓝图应该感觉不可避免——给定净化的元素，这个结构是自然的匹配。

失败处理： 如果多个有效架构相互竞争，根据输入中的约束评估每个。如果没有明确的赢家，优先选择最简单的方案并将替代方案记录为未来选项。

第 6 步：冥想（Meditate）——合成前检查点

运行

meditate

技能以准备最终合成。

1. 清除黄化阶段的分析上下文
2. 锚定在黄化蓝图作为合成指南
3. 观察对转化的任何焦虑——有什么被赶着做吗？
4. 确认准备就绪：蓝图清晰，材料已净化，约束已知

预期结果： 对需要构建什么的平静清晰。合成阶段应该是执行，而非设计。

失败处理： 如果对蓝图的疑虑持续存在，带着具体关切重访第 5 步。精炼蓝图好于在不确定中开始合成。

第 7 步：赤化（Rubedo）——合成

将净化的元素组合为其目标形态。贤者之石：运行的、优化的代码。

1. 按黄化蓝图构建新结构：
   • 按指定创建文件、模块和接口
   • 将每个本质元素迁移到其新位置
   • 实现新的抽象和接口
2. 连接组件：
   • 按设计连接数据流
   • 通过新路径实现错误传播
   • 配置依赖注入或模块加载
3. 验证合成：
   • 每个组件是否独立工作？（单元测试）
   • 组件是否正确组合？（集成测试）
   • 完整系统是否产生与原始相同的输出？（回归测试）
4. 移除脚手架：
   • 删除临时兼容性垫片
   • 移除迁移辅助工具
   • 清理对旧结构的任何剩余引用
5. 产出赤化输出：嬗变后的代码，在新形态中完全运行

预期结果： 可衡量地优于原始代码的可工作代码：更少的行数、更清晰的结构、更好的测试覆盖率、更少的依赖。转化完成，旧形态可以退役。

失败处理： 如果合成揭示了蓝图中的缺口，不要打补丁——返回第 5 步（黄化）修改设计。如果个别组件失败，在尝试全面集成之前隔离并修复它们。赤化不能产出一个半转化的嵌合体。

验证清单

• 黑化清单完整（所有元素、依赖关系、假设已编目）
• 黑化/白化之间通过了冥想检查点（假设已清除）
• 白化提取物仅包含具有干净接口的本质元素
• 修复评估确认了净化的完整性
• 黄化蓝图将每个本质元素映射到目标形态
• 黄化/赤化之间通过了冥想检查点（已准备好合成）
• 赤化输出通过了与原始行为的回归测试
• 赤化输出可衡量地改进了（复杂度、耦合度、测试覆盖率）
• 没有有毒元素存活到最终输出
• 输入中的转化约束已满足

常见问题

• 跳过黑化深度：仓促的分解意味着隐藏的耦合会在合成期间浮现。要充分投入清点工作
• 保留偶然复杂性：对巧妙变通方案或"能用就别动"代码的依恋。如果不是本质的，就去掉
• 跳过冥想检查点：从一个阶段到下一个阶段的认知惯性会产生偏见。暂停是结构性的，不是可选的
• 无蓝图的合成：在黄化完成之前开始编码会产生拼凑物，而不是嬗变
• 不完整的回归测试：赤化必须重现原始行为。未测试的路径会静默中断
• 黄化期间的范围蔓延：照明阶段揭示了超出原始目标的改进机会。记下它们但不要追求——炼金炉服务于声明的转化，而不是假设的理想

相关技能

• transmute

  — 用于单个函数或小模块的更轻量级转化

• chrysopoeia

  — 价值提取和优化（将基础代码变成黄金）

• meditate

  — 作为阶段门检查点使用的元认知清理

• heal

  — 用于净化验证的子系统评估

• dissolve-form

  — 当材料对炼金炉来说过于刚性时，先溶解

• adapt-architecture

  — 系统级迁移模式的互补方法

• review-software-architecture

  — 合成后的架构审查