KeLuoJun Code Alchemy · 代码炼金术
把项目代码炼成可迁移的智慧。不是注释，不是 README，而是一份让 AI（或人类）读完就能"学到功夫"的洞察文档。
核心信念：代码库天然不是为"第一次看到的人"设计的——它首先服务于项目本身的演进，其次才是外部读者的理解。炼金术的价值，正在于跨越这道鸿沟。
一、调用模式识别（必须先判断）
接收到任务时，首先判断调用模式，这决定了分析焦点和文档粒度：
| 调用形态 | 判断信号 | 分析策略 |
|---|---|---|
/code-Alchemy（无参数） |
无附加说明，或泛泛要求"分析/介绍项目" | 全项目鸟瞰 → 见模式 A |
/code-Alchemy <用户问题> |
斜杠命令后跟随具体问题 | 专题聚焦 → 见模式 B |
| 自动触发 | 用户分享代码并问"怎么做到的/有什么亮点/这部分怎么实现的" | 根据问题粒度判断 A 或 B |
不要跳过此判断直接开始分析。 模式决定后续一切策略。
二、分析策略哲学（三层炼金法）
炼金的本质不是"读懂代码"，而是"提炼可迁移的智慧"。
第一层：表象（What） → 这里做了什么？
第二层：机制（How） → 关键代码是怎么实现的？
第三层：哲学（Why） → 为什么这样设计？解决了什么深层问题？
只停在第一层的文档是注释，停在第二层的是教程，三层兼备才是「智慧」。
每一个值得记录的亮点，都必须能回答：
"如果我在另一个项目里遇到同样的问题，这里的做法值得借鉴吗？为什么？"
三、模式 A · 全项目鸟瞰
适用：无参数调用，或用户想全面理解项目
A-0：先理解，再分析（不可省略的前置步骤）
在开始钻研任何代码细节之前，先用 10 分钟建立全局视角，强制回答以下 6 个问题：
① 项目核心目标
- 解决什么问题？为谁解决？
- 核心价值主张是什么？（区别于同类项目的独特之处）
② 主入口定位
- 这是 CLI / API 服务 / 库 / 框架，哪种形态？
- 启动链路从哪里开始？
③ 关键模块 vs 配套设施
- 哪些目录是核心业务逻辑？哪些是工具层、适配层、测试层？
- 从目录结构可以反推出怎样的架构风格？
④ 一次请求/指令/任务的流动
- 用户操作如何被接收？如何被解析？
- 核心处理发生在哪一层？最终如何返回结果？
⑤ 关键抽象与设计动机
- 项目最核心的数据结构/接口是什么？
- 为什么要这样设计？（答案往往不在注释里，在代码组织方式里）
⑥ 20% 高价值代码识别
- 哪些位置决定了项目最有学习价值的部分？
- 参考
references/analysis-strategies.md的高价值代码清单
⚠️ 这 6 个问题的答案，是后续分析的锚点。 全部回答后再进入下一阶段。
A-1：建立项目地图
# 读懂项目自述
cat README.md CHANGELOG.md ARCHITECTURE.md DESIGN.md 2>/dev/null | head -200
# 感知规模（超过 30 个核心文件，触发"大型项目策略"）
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" \
-o -name "*.go" -o -name "*.rs" -o -name "*.java" \) \
| grep -v "node_modules\|\.git\|dist\|build\|__pycache__" | wc -l
# 2层目录结构（感知模块分布）
find . -maxdepth 2 -type d \
| grep -v "node_modules\|\.git\|dist\|__pycache__\|\.cache" | sort
# 找入口文件
find . \( -name "main.*" -o -name "index.*" -o -name "app.*" \
-o -name "cli.*" -o -name "server.*" \) \
| grep -v "node_modules\|\.git" | head -10
# 了解技术栈（依赖 = 技术选型的快照）
cat package.json requirements.txt Cargo.toml go.mod pyproject.toml 2>/dev/null | head -60
脑中构建项目地图（不用输出，但必须明确）：
入口: [文件路径]
核心层: [3-5 个最重要的模块/目录]
支撑层: [工具、配置、数据模型]
外部依赖: [最关键的 2-3 个库，说明选型理由]
代码规模: [行数量级，影响分析深度]
A-2：追踪核心调用链
最有效的理解方式不是按文件顺序读，而是追踪一次完整的任务流动。
选择项目最典型的一个用户操作/功能场景，追踪完整链路：
[用户触发点] → [接收/解析层] → [业务处理层] → [核心逻辑] → [外部调用/数据层] → [结果返回]
追踪时，记录每个节点的：
- 文件路径 + 关键函数名
- 该节点做了什么特殊处理
- 为什么流程在这里"转折"
这条调用链，将成为文档中 Mermaid sequenceDiagram 的直接素材。
A-3：解析设计决策维度
优秀项目最值得学的不是语法技巧，而是背后的设计选择。
围绕以下设计维度，主动向代码提问（详细的提问策略见 references/analysis-strategies.md）：
| 设计维度 | 核心提问 |
|---|---|
| 信任模型 | 系统在多大程度上信任外部输入/LLM 输出？有哪些校验和兜底？ |
| 状态管理 | 上下文、会话、工具状态分别怎么管理？显式还是隐式？ |
| 扩展机制 | 新能力如何接入？插件化还是硬编码？注册表模式？ |
| 错误处理 | 各类错误（网络/逻辑/外部依赖）分别如何处理？fail-open 还是 fail-closed？ |
| 性能取舍 | 哪里用了缓存？哪里做了懒加载？成本和延迟如何权衡？ |
| 安全边界 | 权限模型是什么？默认策略允许还是拒绝？敏感数据怎么处理？ |
A-4：挖掘工程智慧（补丁与注释）
这一步是最容易被跳过但价值极高的环节。
成熟系统里，那些"不完美"的地方——补丁代码、防御性注释、TODO、HACK 标记——恰恰是最有工程学习价值的：
# 寻找工程"疤痕"：有意识的补丁和权衡
grep -rn "TODO\|FIXME\|HACK\|XXX\|WORKAROUND\|fragile\|brittle" . \
--include="*.py" --include="*.ts" --include="*.go" \
| grep -v "node_modules\|\.git" | head -30
# 寻找防御性注释（往往藏着血泪教训）
grep -rn "NOTE:\|WARNING:\|IMPORTANT:\|DANGER:" . \
--include="*.py" --include="*.ts" --include="*.go" \
| grep -v "node_modules" | head -20
# 找注释最密集的文件（作者认为最需要解释的地方）
grep -rcn "^#\|^//" . --include="*.py" --include="*.ts" \
| grep -v "node_modules" | sort -t: -k2 -rn | head -10
这些发现揭示：
- 生产系统不是教科书里的理想模型
- 每个"补丁"背后都有一个真实的踩坑经历
- 技术债务是有意识的选择，不是无知的产物
A-5：文档撰写
使用 references/doc-template.md 中的模板 A，输出到：
mkdir -p docs
# 命名：docs/code-alchemy-{项目名}-{YYYYMMDD}.md
四、模式 B · 专题聚焦
适用：用户提出具体问题，如"项目是如何实现 X 的"、"提示词设计有什么亮点"
B-0：问题解构（先做这一步）
用 3W 框架拆解用户问题：
What → 用户想理解的技术现象是什么？（精确命名）
Where → 这个现象对应项目中哪些文件/模块？（先定位，再分析）
Why → 用户为什么想理解这个？学习/复现/改进？（影响洞察侧重）
不要在没有明确 Where 的情况下开始分析。
B-1：从一个小功能点出发
专题分析最有效的切入方式：选定一个最典型的功能实例，跑完它的完整生命周期。
例如，想理解"工具调用机制"：
- 找到一次真实工具调用的触发入口
- 追踪：指令解析 → 工具选择逻辑 → 参数拼装 → 执行调度 → 结果回填
- 在关键节点记录：做了什么 + 为什么在这里做
跑完一条功能链路，沿途经过的模块关系就自然理清了。 沿途暴露的模块，比"按目录扫描"更能说明设计意图。
B-2：定位相关代码
# 按功能关键词搜索（先广后窄）
grep -rn "{关键词}" . \
--include="*.py" --include="*.ts" --include="*.go" \
| grep -v "node_modules\|\.git" | head -30
# 按文件名/目录名搜索
find . -name "*{feature}*" -o -name "*{keyword}*" \
| grep -v "node_modules\|\.git" | head -15
# 找到最被引用的相关符号（高引用 = 高重要性）
grep -rn "{FunctionOrClass}" . --include="*.py" --include="*.ts" \
| grep -v "node_modules" | wc -l
B-3：调用链精确追踪
触发点（用户操作 / API 调用 / 事件）
↓ [记录：文件:行号，函数名]
接收/路由层
↓ [记录：如何分发，为什么这样分发]
核心处理层
↓ [记录：关键算法或决策逻辑]
数据层 / 外部调用
↓ [记录：I/O 边界在哪里]
结果处理与返回
B-4：文档撰写
使用 references/doc-template.md 中的模板 B，输出到：
mkdir -p docs
# 命名：docs/code-alchemy-{主题关键词}-{YYYYMMDD}.md
五、输出质量检查清单
一份合格的 Code Alchemy 文档，必须满足：
- 一句话定位：项目是什么、解决什么问题（全项目必须）
- Mermaid 图：架构图或核心调用链时序图（至少一张）
- 代码佐证：每个亮点附带代码片段（路径 + 行号范围）
- Why 解释：每个设计决策有"为什么"的解释，不只是 What/How
- 工程补丁：至少提及一处有价值的 TODO/HACK/注释（全项目必须）
- 可迁移洞察：明确写出"如何在新项目中复用这个思路"
- 长度适中：全项目 2000-4500 字；专题 800-2000 字
六、特殊场景处理
代码量巨大（核心文件 >50 个）： 激活"20% 策略"——只深入以下高价值位置：启动入口、核心调度循环、工具/插件机制、状态管理层、与外部系统的交互边界。其余文件一律跳过，文档中注明"未覆盖区域"。
项目无文档： 从测试文件逆向理解意图——测试往往比实现代码更直接说明"这个模块应该做什么"。
专题模式问题模糊（如"有什么亮点"）： 自动升级为模式 A，文档开头注明"基于全项目扫描的亮点提炼"。
遇到无法理解的代码：
诚实标注 > ⚠️ [待深入]，不猜，可注明"需运行时日志才能验证"。
加载此文件后，继续读取 references/doc-template.md 获取输出模板。
分析大型项目时，同步读取 references/analysis-strategies.md 获取详细策略。