仓库说明

该 AGENTS.md 是本仓库的 Skill 开发规则说明，适用于整个仓库的 Skill，规则冲突时，以更具体的规则为准。

本仓库存放个人使用的 Agent Skills，Skill 应记录 Agent 默认未必知道的行为：个人工作流、反复纠正过的问题、领域特定知识、偏好的边界，以及实践中观察到的失败模式，它们用于扩展 Agent 的能力边界，设计为被 Agent 而不是人类用户直接使用。

本仓库的 Skill 不做成中立的通用模板；它们记录了仓库所有者对 Agent 如何协作、编辑、审查和验证工作的明确个人偏好。

已有的 Skill 及其职责说明统一维护在 README.md 及它的其它语言版本中。

代码规则

• 项目中的脚本语言使用 Python，统一使用 uv 作为包管理工具。
• 脚本的终端输出应该语义明确，便于 Agent 理解，并过滤无关的繁杂工具输出。
• 使用 Ruff 和 Pyright 做静态检查和格式化检查，Pytest 作为测试框架。
• 使用 .bat 脚本调用 uv 完成 Windows 下的虚拟环境配置。

测试执行环境

在 Windows/Codex 环境运行本仓库的 Pytest 测试时，直接在沙箱外执行。已验证当前 unelevated 沙箱无法访问 Python/Pytest 通过 mkdir(mode=0o700) 创建的私有临时目录，会出现 WinError 5；不要把这类错误判断为项目业务代码的测试失败。

• 使用工具的 sandbox_permissions="require_escalated" 执行测试；沙箱外运行不等同于 Windows 管理员提权，不修改全局沙箱配置。
• 在对应 Skill 目录使用现有环境运行 uv run --no-sync python -m pytest，按需指定测试范围，不因运行测试自动同步依赖。
• 每次在仓库 .cache/test-runs/<run-id>/<skill>/ 下使用独立目录，通过 --basetemp 和 -o cache_dir=... 分别指定测试临时目录与缓存；uv 缓存也放在本次运行目录内，避免复用已有的权限失败目录。
• 在同一沙箱外执行上下文中完成运行和清理，保留测试结果与必要日志。清理前确认目标的绝对路径位于本次运行目录内，且目标及路径不包含链接或 junction；不清理历史样本或无关文件。

Skill 文档规则

本章节内容是针对单个 Skill 文档的规则，文档路径均为相对于特定 Skill 根目录的路径

• 保证文档单一职责和内容的单源性，同一内容优先使用引用而不是在多个文档重复维护。
• 当内容较长、会被独立复用，或属于架构、错误处理等稳定主题时，拆分为 reference 下的引用文档，短规则和单次说明允许保留在所属文档中。

语言规则

• SKILL.md 正文、references/ 文档、面向 Agent 的自然语言指令、README.md 和 AGENTS.md 使用中文；README.en.md 等英文用户文档和明确指定为英文的模板保持英文。
• name、路径、文件名、命令、代码、模块名、函数名、配置键、协议字段、状态值等机器标识符保持原样，不得翻译。
• 代码块、命令、JSON、终端输出、技术术语、输入输出示例以准确维护技术语义为先，允许中英混用，禁止为了语言统一强行翻译。

SKILL.md

• Skill 根目录的必需文档，面向使用 Skill 的 Agent，必须具有至少包含 name，description 两个字段的 YAML 头。
• 正文使用结构化组织方式，至少包含 Skill 的适用范围、核心规则、脚本运行环境配置（若有脚本）等 Skill 正常使用的必需信息。
• 使用简洁明确的可执行指令，优先使用“具体情景-正确行为”的描述方式。
• 优先写具体情景下的具体行为规则，不写冗长的背景或通用知识说明。
• YAML 头中的 name 保持原有标识符，description 使用自然中文，不使用为英文主体补充中文释义的中英括注格式。

README.md

• Skill 根目录的可选文档，面向人类，包含 Skill 的概述、使用边界、运行环境、隐私安全和进一步阅读资料等用户关心的问题。
• 不要在其中详细描述 Skill 的触发条件、执行流程、输入输出和能力边界等技术或实现细节，这些内容都有专门的文档记录，README 中只需要引用这些文档。

AGENTS.md

• 根目录的可选文档，面向 Agents 和开发者，包含 Skill 代码的常用命令、规则约束和风格偏好。

references/ARCHITECTURE.md

• 可选的代码架构说明文档，在此说明 Skill 的架构设计。
• 应当说明各逻辑模块的职责和边界、Skill 执行的控制流程、数据流向。
• 不应当锁定代码内部的实现细节。

references/ERROR-HANDLING.md

• 可选的常见错误处理方式说明文档，在此说明 Skill 使用中可能遇到的问题及其一般处理方法。

assets

• 可选的文件夹，统一存放 Skill 需要的模板、图片、字体、指令等资源。

编辑规则

• 已实现的 Skill 行为以仓库中的代码为第一可信状态源，而不是记忆中的状态、已安装 Skill 的状态或文档的描述。
• 删除或废弃功能时，同时删除对应说明、示例和引用。
• 保留无关的本地修改和未跟踪文件，保留代码中的正确注释。
• 禁止仅追加新规则来覆盖旧规则，存在冲突时，应修改或删除旧规则，使当前有效规则唯一且明确。
• 修改一个 Skill 时，除非用户明确要求，否则不要修改其他 Skill。
• 完成 Skill 的触发条件、输入输出、配置格式、目录结构、命令或执行流程等用户可见行为修改后，必须检查并同步相关文档。
• 代码或脚本修改后，运行 Skill 规定的测试和代码规范检查。
• 修改文档后，检查链接、路径、YAML 头和示例是否有效。

数据版本策略

• 只在数据会长期保存、生产者与消费者不能同步升级且旧数据不能安全重建的兼容边界保留显式 schema version。
• 内部 policy 和 resolved configuration 记录实际生效字段；当这些字段已经参与 identity digest 时，不再增加独立版本号。
• 临时或可再生的 workspace、cache、benchmark 和诊断数据使用严格的当前结构校验；不兼容数据应失效并重建，不维护迁移链。
• 删除已发布 schema 中的字段或改变其语义时，必须通过新的外层公共 schema 明确隔离，不得在原 schema version 下修改。

提交信息

编写提交信息时，遵循 Conventional Commits 1.0.0 规范：

<type>(<scope>): <简短描述>

[可选的详细说明]