code-alchemy — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited code-alchemy (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
把项目代码炼成可迁移的智慧。不是注释，不是 README，而是一份让 AI（或人类）读完就能"学到功夫"的洞察文档。
>
核心信念：代码库天然不是为"第一次看到的人"设计的——它首先服务于项目本身的演进，其次才是外部读者的理解。炼金术的价值，正在于跨越这道鸿沟。
接收到任务时，首先判断调用模式，这决定了分析焦点和文档粒度：
| 调用形态 | 判断信号 | 分析策略 |
|---|---|---|
/code-Alchemy（无参数） | 无附加说明，或泛泛要求"分析/介绍项目" | 全项目鸟瞰 → 见模式 A |
/code-Alchemy <用户问题> | 斜杠命令后跟随具体问题 | 专题聚焦 → 见模式 B |
| 自动触发 | 用户分享代码并问"怎么做到的/有什么亮点/这部分怎么实现的" | 根据问题粒度判断 A 或 B |
不要跳过此判断直接开始分析。 模式决定后续一切策略。
炼金的本质不是"读懂代码"，而是"提炼可迁移的智慧"。
第一层：表象（What） → 这里做了什么？
第二层：机制（How） → 关键代码是怎么实现的？
第三层：哲学（Why） → 为什么这样设计？解决了什么深层问题？只停在第一层的文档是注释，停在第二层的是教程，三层兼备才是「智慧」。
每一个值得记录的亮点，都必须能回答：
"如果我在另一个项目里遇到同样的问题，这里的做法值得借鉴吗？为什么？"
适用：无参数调用，或用户想全面理解项目
在开始钻研任何代码细节之前，先用 10 分钟建立全局视角，强制回答以下 6 个问题：
① 项目核心目标
② 主入口定位
③ 关键模块 vs 配套设施
④ 一次请求/指令/任务的流动
⑤ 关键抽象与设计动机
⑥ 20% 高价值代码识别
references/analysis-strategies.md 的高价值代码清单⚠️ 这 6 个问题的答案，是后续分析的锚点。 全部回答后再进入下一阶段。
# 读懂项目自述
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 个库，说明选型理由]
代码规模: [行数量级，影响分析深度]最有效的理解方式不是按文件顺序读，而是追踪一次完整的任务流动。
选择项目最典型的一个用户操作/功能场景，追踪完整链路：
[用户触发点] → [接收/解析层] → [业务处理层] → [核心逻辑] → [外部调用/数据层] → [结果返回]追踪时，记录每个节点的：
这条调用链，将成为文档中 Mermaid sequenceDiagram 的直接素材。
优秀项目最值得学的不是语法技巧，而是背后的设计选择。
围绕以下设计维度，主动向代码提问（详细的提问策略见 references/analysis-strategies.md）：
| 设计维度 | 核心提问 |
|---|---|
| 信任模型 | 系统在多大程度上信任外部输入/LLM 输出？有哪些校验和兜底？ |
| 状态管理 | 上下文、会话、工具状态分别怎么管理？显式还是隐式？ |
| 扩展机制 | 新能力如何接入？插件化还是硬编码？注册表模式？ |
| 错误处理 | 各类错误（网络/逻辑/外部依赖）分别如何处理？fail-open 还是 fail-closed？ |
| 性能取舍 | 哪里用了缓存？哪里做了懒加载？成本和延迟如何权衡？ |
| 安全边界 | 权限模型是什么？默认策略允许还是拒绝？敏感数据怎么处理？ |
这一步是最容易被跳过但价值极高的环节。
成熟系统里，那些"不完美"的地方——补丁代码、防御性注释、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这些发现揭示：
使用 references/doc-template.md 中的模板 A，输出到：
mkdir -p docs
# 命名：docs/code-alchemy-{项目名}-{YYYYMMDD}.md适用：用户提出具体问题，如"项目是如何实现 X 的"、"提示词设计有什么亮点"
用 3W 框架拆解用户问题：
What → 用户想理解的技术现象是什么？（精确命名）
Where → 这个现象对应项目中哪些文件/模块？（先定位，再分析）
Why → 用户为什么想理解这个？学习/复现/改进？（影响洞察侧重）不要在没有明确 Where 的情况下开始分析。
专题分析最有效的切入方式：选定一个最典型的功能实例，跑完它的完整生命周期。
例如，想理解"工具调用机制"：
跑完一条功能链路，沿途经过的模块关系就自然理清了。 沿途暴露的模块，比"按目录扫描"更能说明设计意图。
# 按功能关键词搜索（先广后窄）
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触发点（用户操作 / API 调用 / 事件）
↓ [记录：文件:行号，函数名]
接收/路由层
↓ [记录：如何分发，为什么这样分发]
核心处理层
↓ [记录：关键算法或决策逻辑]
数据层 / 外部调用
↓ [记录：I/O 边界在哪里]
结果处理与返回使用 references/doc-template.md 中的模板 B，输出到：
mkdir -p docs
# 命名：docs/code-alchemy-{主题关键词}-{YYYYMMDD}.md一份合格的 Code Alchemy 文档，必须满足：
代码量巨大（核心文件 >50 个）： 激活"20% 策略"——只深入以下高价值位置：启动入口、核心调度循环、工具/插件机制、状态管理层、与外部系统的交互边界。其余文件一律跳过，文档中注明"未覆盖区域"。
项目无文档： 从测试文件逆向理解意图——测试往往比实现代码更直接说明"这个模块应该做什么"。
专题模式问题模糊（如"有什么亮点"）： 自动升级为模式 A，文档开头注明"基于全项目扫描的亮点提炼"。
遇到无法理解的代码： 诚实标注 > ⚠️ [待深入]，不猜，可注明"需运行时日志才能验证"。
加载此文件后，继续读取 references/doc-template.md 获取输出模板。 分析大型项目时，同步读取 references/analysis-strategies.md 获取详细策略。
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.