准备由人审核并提交的代码贡献

## 遵守代码库的规则，并等待维护者批准 将代码库的贡献指南、人工智能政策和目录专用的代理指令，视为变更相关文件时必须遵循的权威来源。 ### 确定适用规则 - 编辑前，阅读根目录的贡献政策与安全政策。 - 进入专用目录时，还应应用其中关于运行时行为、公开接口、集成、文档或测试的本地指令。 - 如果指令相互冲突，应停止并指出冲突，不得选择让实施更容易的规则。 - 只有在客户端支持且不会覆盖代码库政策时，才使用可选的代理技能。 ### 审批关卡 - 不得通过浏览器自动化、命令行托管工具或服务API提交议题、拉取请求或拉取请求草稿。 - 按照代码库模板起草提交文本，供人类审阅和发送，并使其可以直接粘贴。 - 在相关议题完成分类并分配给人类贡献者前，不得推送分支或准备公开提交材料。 - 没有记录在案的维护者指示时，不得实施非简单功能、公开接口变更、重构或行为变更。如果缺少指示，应停在提案阶段。 ## 不把秘密信息放进提交，测试不连接真实服务 在整个任务中保护凭据、证据质量、代码库历史和测试隔离。 ### 不可协商的规则 - 绝不能提交秘密、凭据、非公开的服务提供商数据或敏感的环境值。 - 绝不能编造测试结果、批准、引用、审查状态或兼容性声明。 - 单元测试不得连接正在运行的模型、服务提供商或外部应用服务。 - 使用确定性的替代组件，并让测试进程在不含在线服务凭据的环境中运行。 - 没有明确来源和维护者同意，不得添加生成媒体、大型生成资源或合成数据集。 - 如果代码库自动化负责插入许可证标头，不得手动添加许可证标头。 - 除非收到要求，否则不要添加注释；除非变更使现有注释、文档字符串或许可证标头变得不准确，否则应保留它们。 ### 受保护文件 除非任务明确要求执行代码库的重新生成工作流程，否则不得手动编辑变更日志、生成文件、锁文件、验证快照或其他由工具管理的产物。如果变更日志由工具生成，应将发布说明的背景写入提案或提交草稿。 ## 只在必要时改动依赖，并使用固定版本的工具 使用项目规范的锁定环境和任务命令，不得临时拼凑其他执行路径。 ### 依赖变更 - 除非任务需要，否则不得添加或更新依赖。 - 临时调查应使用不会修改已提交依赖状态的隔离环境。 - 必须变更依赖时，应将其放入范围最小且合适的依赖组或可选功能集。 - 添加明确的兼容性边界，并避免把可选集成移入默认安装路径。 - 将依赖和锁文件变更与无关编辑分开。 ### 工具使用 - 安装、测试、文档、格式化和静态分析应使用代码库固定的运行时与工具版本。 - 区分权威验证命令与诊断命令。单独运行代码检查器或类型检查器可以辅助诊断，但不能替代代码库要求的提交前检查或验证路径。 - 将执行大范围暂存、提交或全库检查的脚本视为高影响工具；只有在明确需要时才运行，并尽量在干净的工作树中执行。 ## 按变更类型选择需要运行的测试 根据实际变更类型选择最低限度但充分的验证，只有当共享行为或兼容性风险有充分理由时才扩大范围。 ### 验证矩阵 - 文档或代码库元数据：对变更文件运行检查；如果可能影响渲染、链接、示例或文档配置，应构建文档。 - 运行时缺陷修复：添加或运行针对性的回归测试，然后对变更文件运行必要检查。 - 公开接口、配置或语言行为：运行针对性测试并更新相关文档或示例；兼容性风险较大时，再添加范围更广的软件包测试。 - 服务器、流式处理、追踪、操作或生成路径：测试变更路径及其备用路径或不支持路径。 - 打包、依赖或锁文件变更：运行相关安装或打包检查，并保持依赖差异隔离。 ### 范围与隔离 - 了解规范的全套测试命令实际包含什么，不得假设它只涵盖最明显的测试目录。 - 优先使用会移除在线服务凭据并提供确定性替代组件的测试入口。 - 诊断与隔离有关的不稳定问题时，在相同环境保护措施下比较正常的并行运行与确定性的串行运行。 - 除非测试运行器实际强制执行，否则应将慢速或串行标记视为参考提示。 - 如果方便的替代测试命令可能保留在线凭据或绕过必需测试路径，不得使用该命令。 ### 交接证据 对于准备交付审查的变更，应在交接前运行权威的提交前检查，使格式、许可证和类型检查结果保持稳定。报告任何未运行的必需检查及其原因。 ## 先查有无重复工作，并回复每条审查意见 确保公开贡献活动可以追溯到已批准的工作，并避免重复劳动。 ### 实施前 - 确认议题已经分类和分配；对于非简单工作，还应确认已有一致同意的方案。 - 准备可供审查的工作前，使用只读搜索检查议题讨论、引用该议题的未合并变更，以及同一区域内的未合并变更。 - 如果已有变更涵盖该工作，不得准备重复变更。如果方案存在重大差异，应在用于议题讨论的草稿中说明区别。 - 对于探索性工作，应起草一条说明分支和相关文件的议题评论，而不是创建公开变更请求。 ### 提交与审查 - 遵循代码库的标题和提交规范。 - 不得在标题或提交消息中添加人工智能标记，也不得将工具或代理列为提交共同作者。 - 请求维护者审查前，处理或回复每一条尚未关闭的审查评论。 - 除非政策明确允许，否则不得代替其他审查者解决其讨论串，也不得为自己的变更添加准备就绪标签。 - 将自动审查和人工审查发现视为需要对照实际代码路径验证的主张，而不是自动正确的指令。 ## 用户可见的行为改变时更新文档 使文档与用户可见行为保持同步，并避免把范围有限的示例描述为普遍支持。 ### 文档职责 - 变更公开接口、配置语法、示例、安装要求或其他用户可见行为时，更新相关文档。 - 对于可选集成，应说明其可选性，指出所需软件包或功能组，在不暴露值的情况下列出所需凭据类型，并解释集成路径。 - 对于模型或服务提供商示例，应说明模型类型、路由模式、支持的模式和已知限制。 - 通过权威来源验证作为当前值展示的标识符通常可以使用。 - 不得仅因为更新文档而更改随产品交付的默认参数。 ### 重构与生成内容 - 对于已批准的重构，在改变细微行为前添加或更新特征测试。 - 如果现有测试没有覆盖重构路径，应保留用来证明行为不变的等价性检查。 - 不得手动编辑生成文档或生成产物；只有任务授权重新生成时，才使用项目工作流程。 - 除非明确要求并且与无关变更隔离，否则不得运行已知会暂存文件或触发大范围检查的文档构建工具。 ## 对照合并基准审查，只报告已核实的内容 对照正确基准审查已完成的变更，并在宣布可以交付前验证每项声明。 ### 审查顺序 1. 将分支与代码库配置的合并基准进行比较。 2. 检查实施代码和实际覆盖它的测试。 3. 在结构化审查前运行权威的格式化、代码规范检查、许可证检查和类型检查，以保持行位置稳定。 4. 执行结构化代码审查；对于身份验证、输入处理、反序列化或外部调用变更，还应增加安全检查。 5. 根据实际执行路径验证每项发现。 6. 修正确认的问题，重新运行受影响的验证，并重复审查，直到没有确认的问题为止。 ### 完成标准 报告变更文件、执行的验证、观察到的结果、跳过的检查、未解决风险，以及仍需人类执行的操作。没有直接证据时，不得声称已准备好接受审查、已获得批准、具备兼容性或验证成功。