给 AI Agent 的说明

本文件面向在本仓库里工作的 AI 助手。人类贡献者请看 CONTRIBUTING.md。

这个仓库是什么

一个 Agent Skill：SKILL.md 是主文件（十二阶段流水线与十二条铁律），references/ 放细则， scripts/ 放可执行的检查工具。它不是普通的 Python 项目 —— 技能能被正确安装、能被人读懂，与代码能跑同样重要。

动手前后各做一件事

python scripts/selfcheck.py . --quiet
python .github/lint_workflows.py
python -m unittest discover -s tests

改之前跑一遍确认基线是绿的；改之后跑一遍确认没有新问题。三条都离线可跑。 第二条专管工作流：uses: 引用是否固定到完整 SHA、权限是否在顶层收敛。 （写「第几条」的句子最容易随命令顺序过期 —— 排序一变，它就在说另一条命令。）

必须守住的五条

1. 不写某台机器的实测值。 绝对路径、IP 字面量、某工具装没装 —— 一律改写为 「如何探测出该值」。自检器的三条可移植性规则正是守这条。
2. 不把凭据与个人信息带进发布物。 发布前隐私扫描守这条，而且它必须在打 tag 之前跑： 推到公开仓库就按已泄露处理（存档、索引、别人的 fork 都去不掉），事后撤回治不了本。
3. 检查字面量的代码，自身不得含有该字面量的完整形态。 规则常量用字符串拼接构造。
4. 断言打在内容层（Git 对象指纹），不要打在 zip 的哈希上。
5. 「跳过」不等于「通过」。 缺条件时显式报告，不要让它从「失败数 0」里蒙混过去。

改文件时的具体注意

• 所有文本文件用 LF，.gitattributes 已对每种文件类型显式声明 eol=lf。 新增一种文件类型时，在同一个提交里补上对应的 eol 规则 —— 否则 git archive 会按平台转换行尾，同一个 tag 会打出两个内容不同的包。
• 相对链接与锚点会被校验，写完顺手跑一遍自检。
• 文档里的数字要在同一个提交里现算（文件数、测试数、条目数），并把命令附在变更记录里。
• 不要为了让 CI 变绿而放宽规则。 CI 报「目录名与 name 不一致」时， 正解是让 CI 把内容放进以 name 命名的目录，而不是关掉那条检查。
• 改判据或数字时，在提交信息里说明它原来错在哪。