隐形机关解锁 · Skill Archaeologist
给开源技能做考古：从源码反推作者意图，把「隐形机关」写成说明书。
什么时候用
- 用户说「给这个技能写说明书」「这个技能到底能做什么」「为什么这个技能跑不对」
- 要接手一个别人写的、只有 SKILL.md 没有解说的技能
- 技能升级后想知道「这次改了什么隐性行为」
- 要批量盘点本机技能里有多少未文档化的参数 / 默认值 / 边界
核心判断
开源技能 80% 的能力藏在作者没写出来的地方：SKILL.md 里写的能力只是冰山一角，
真正的机关藏在 scripts 的参数、默认值、退出码、守卫、references 的孤儿文件里。
本技能把这层隐性知识显性化，方法上有两条硬纪律：
- 证据先行：每条结论必须锚定源码
文件:行号。没有证据的断言禁止进说明书。 - 两层分工：
scripts/做确定性证据采集（可复现、可回归）；LLM 只在证据之上补「为什么」。
裸脚本测不到的跨文件影响链，靠 LLM 在证据之间连线；裸 LLM 会编造的细节，靠脚本兜住。
三个命令
1. 扫描：出证据与机关卡片
python scripts/archaeo_scan.py <skill_dir> --out evidence.json --md report.md
输出十类证据（每条带 file:line）：未文档化参数 / 非平凡默认值 / 示例与默认值漂移 /
孤儿资源 / 退出码契约 / 参数关系 / 守卫与硬门槛 / 环境依赖 / 外部命令依赖 / 写盘副作用。
并给出「机关密度」分档（高度隐蔽 / 中度隐蔽 / 较透明）。
2. 出说明书：三层产物
python scripts/archaeo_doc.py <skill_dir> --out-dir out/
产出三层（对应 Reference / Getting Started / Troubleshooting 三类文档）：
- 机关卡片：代码有、文档没有的参数与默认值，逐条带
file:line - 5 分钟跑通卡：最小可跑命令，并标注「必须知道否则会踩坑」的隐性参数
- 别用清单：负向边界，全部来自真实守卫、退出码与命名陷阱
3. 比版本：机关 diff
python scripts/archaeo_diff.py v1/evidence.json v2/evidence.json --md diff.md
输出「本次升级改动了 N 条隐性行为」，分 新增 / 删除 / 变更 三类。
比对只发生在语义层（参数名 / 默认值 / 退出码 / 守卫原文），不比行号——
行号会随改动整体漂移，那不是隐性行为变化。
工作流
- 确认目标技能目录（含 SKILL.md）。
- 跑
archaeo_scan.py，先看机关密度与证据数量。 - 跑
archaeo_doc.py出三层产物。 - 反向验证：逐条回源码核对，剔除误报。这是本技能最关键的一步——
实测中扫描器的误报率一度高达六成，全部集中在「孤儿资源」与「平凡参数」两类。 - 若要比较版本，对两版各跑一次 scan，再用
archaeo_diff.py出 diff。
判据可靠性（重要）
扫描器的价值在于「每条都经得起点开源码核对」，因此判据是逐条踩坑补出来的。
已内置的九条判据修正（测试断言分离、调优建议不当默认值、全树文档比对、命名归一化、
孤儿四类误报排除、裸词误判、多别名参数、字符串退出、退出码排除测试文件）见
references/判据清单.md。换环境使用时，请先按该清单对新语料做一次反向验证。
产物示例
references/产物示例.md 给出一份真实技能的机关卡片样例。
数据与隐私
本技能只读取目标技能的文本文件（.md/.py/.txt/.json/.yaml/.yml/.html/.csv 等），
不联网、不上传、不修改被扫描的技能。扫描结果只写到调用者指定的输出路径。
方法论溯源
本技能的方法骨架参考了公开领域的三类方法与框架（未包含任何原文摘录）：
知识转化研究中的「外显化」、技术写作领域的文档分类学、以及遗留代码领域的特征测试方法。
详见 references/方法论溯源.md。
版权与授权
本技能为原创工具，可免费使用与二次分享；转载请注明出处「七仔的AI工具箱」。
内置的判据清单来自本技能的实测纠正记录（含误报案例），不涉及第三方内容。
方法论溯源文档仅记录公开领域的方法名称与作者署名，未包含任何受版权保护的原文摘录或近原文改写。
被扫描的技能源码版权归其各自作者所有；本技能只读取文本、不复制、不重新分发被扫描技能的代码。
作者与联系方式
本 skill 由「七仔的AI工具箱」维护。欢迎就技能使用、问题反馈与二次分享交流：
- 微信公众号：七仔的AI工具箱
- 抖音号：七仔的AI工具箱
- CSDN 博客：七仔的AI工具箱
本 skill 可免费使用与二次分享；转载请注明出处「七仔的AI工具箱」。
