贡献指南

感谢你参与改进这个 Codex 配置与 Skills 仓库。

开始之前

1. 阅读 AGENTS.md，了解当前仓库结构、开发约定和验证命令。
2. 每次变更只聚焦一个模型提供商、Skill、工作流或文档问题。
3. 如果提案会改变默认权限、认证方式、模型提供商行为，或同时影响多个 Skill 的公开接口，请先创建 Issue 讨论。

开发要求

• 不要把真实凭据或用户本地运行状态提交到仓库。
• 对重复、脆弱或需要确定性执行的逻辑，应在 Skill 的 scripts/ 目录中提供脚本，不要要求 Agent 每次临时生成。
• 为脚本、解析器、参数处理、文件行为和常见失败路径，在 skills/<name>/tests/ 下添加离线测试。
• SKILL.md 只保留 Skill 触发后 Agent 真正需要的核心流程；较长的参考资料应放在 references/ 中。
• 当 Skill 的用途、显示名称或默认调用方式发生变化时，同步更新 agents/openai.yaml。

验证

运行 AGENTS.md 中与改动相匹配的检查。至少应完成：

1. 解析所有修改过的 TOML 文件。
2. 对每个修改过的 Skill 运行 quick_validate.py。
3. 对修改过的脚本运行语法检查和离线测试。
4. 确认命令行脚本无需凭据也能显示 --help。
5. 提交前运行 git diff --check。

不要仅为了满足 Pull Request 检查而调用真实付费 API。如果确实需要集成测试，应使用权限最小的凭据、清理日志中的敏感信息，并记录可复现的人工步骤，但不要公开任何密钥。

Pull Request 要求

Pull Request 应包含：

• 问题与解决方案的简要说明
• 受影响的配置或 Skills
• 已执行的自动化和人工验证
• 有意跳过的集成测试及原因
• 对安全、权限或兼容性的影响

不要混入无关格式化、个人配置或其他工作区修改。

兼容性与发布

main 是滚动更新分支，目标是当前稳定版 Codex CLI。完整支持策略见 COMPATIBILITY.md。如果变更会主动放弃兼容性或改变公开工作流，应在 Pull Request 和发布说明中明确指出。