修改共享库或SDK时，不破坏公共API

## 宣布完成前，运行全部测试和构建 当变更会影响运行时代码、测试或构建/测试行为时，在宣布任何变更完成之前，运行项目完整的验证流程。以下情况需要进行验证： - 修改核心库代码或共享工具函数。 - 修改测试，包括快照测试。 - 修改示例项目。 - 修改构建或测试配置（依赖清单、任务运行器文件、文档构建配置、CI 工作流）。 对于仅涉及文档或仓库元数据的变更（文档、贡献者指南、元数据文件），可以跳过完整验证，除非用户明确要求执行完整流程。是否需要验证应根据实际改动的文件来判断，而不是凭对变更规模大小的主观感觉。应用任何修复后都要重新运行整个验证流程——只运行部分流程会掩盖修复本身引入的回归问题。 在与外部平台的 API 集成时，应查阅该平台的权威文档，而不是依赖对 API 的一般性假设，同时检查本地代码路径以了解库自身的行为。 ## 未经用户许可，不切换Git分支或工作树 默认情况下，应在用户当前的检出目录和当前分支中进行工作。如果任务已经在一个已选定的工作树内运行，则直接使用该工作树，无需额外申请权限。 除非用户在当前对话中明确要求或批准这一确切操作，否则不要创建或切换到另一个工作树，也不要创建或切换分支。要求实现、调查、审查、测试或验证变更的请求，本身并不构成更改当前活动工作树或分支的授权。 如果确实需要隔离环境或不同的检出目录，应先说明原因，并在更改任何 Git 状态之前征求同意。即使其他规则或工作流建议使用关联的工作树，这一原则依然适用：应停下来请求批准，而不是自动选择或创建工作树。 ## 新的公共API参数加在末尾，不破坏现有调用 导出的运行时 API 的参数和字段顺序是一种契约，而不是实现细节。 - 保留现有公共构造函数参数和数据类字段的位置含义。切勿在现有公共顺序的中间插入新的参数或字段。 - 将新的可选公共字段或参数追加到末尾，保持现有字段的原有顺序不变。 - 如果重新排序不可避免，需添加明确的兼容层，并配以针对旧的按位置调用方式的回归测试。 - 在调用处优先使用关键字参数以减少意外破坏，但绝不能以此为由破坏按位置传参的兼容性。 - 将预期的导入路径和公共导出列表视为契约。新增或移动公共符号时，需同步更新所属模块、预期的顶层或子包重导出，以及导入回归测试。 - 确保顶层导入不会因可选依赖缺失而失败，也不产生运行时副作用；必要时使用惰性导出。 ## 以最新发布版本判断兼容性，并为较大的工作制定计划 判断是否属于破坏性变更时，应以最新发布版本为基准，而不是以尚未发布的分支本地改动为基准。在最新发布版本之后引入或更改的接口，只要没有定义一个已发布或明确支持的持久化外部状态边界，且用户没有明确要求提供迁移路径，就可以直接重写而无需兼容层。当中间快照被有意设定为不支持时，尚未发布的持久化格式可以在发布前重新编号或合并压缩。对于发布后分支中的改动，优先直接替换，而不是添加兼容层。 及早指出兼容性风险——但仅限于该变更会影响最新发布版本中已上线的行为，或已发布且受支持的持久化状态边界——并在实施前确认方案。 当工作涉及多个步骤、跨越多个文件、包含新功能或重构，或预计耗时超过约一小时时，应制定执行计划。在执行过程中及时更新计划中的动态部分（进度、发现、决策记录、成果），如果范围发生变化则重写计划。如果针对复杂任务有意跳过制定计划，需说明原因，以便审阅者理解这一选择。 ## 先读子系统参考文档，再更新变更波及的每一处 库的运行时由一组相互作用的子系统组成——运行循环、工具执行、模型与提供方适配器、追踪、会话与持久化、实时与语音管线、沙箱，以及序列化的运行状态。在修改其中任何一个子系统之前，先阅读其专门的架构参考文档，并确认自己理解所涉及的边界。 当新增或更改一个会波及整个系统的变体时——例如新的模型输出、工具调用、审批或运行项类型——需要更新所有相关层面：处理逻辑、事件、回放、持久化、追踪和序列化。遗漏其中任何一个层面都会导致难以察觉、难以追踪的数据损坏。 确保流式与非流式路径在行为上保持一致。对于拥有连接、任务或其他资源所有权的子系统，需要在正常路径和失败路径上都验证资源所有权。当序列化的运行状态结构发生变化时，需遵循该格式相应的发布边界、模式版本、向后读取兼容性和回归测试规则。 ## 让文档与实际代码一致，不在日志中留下敏感数据 - 文档通常会发布到线上站点，因此需要谨慎协调行为变更与文档的关系。如果文档将描述尚未发布的行为，应推迟文档变更，直到相应版本发布，或将其拆分为后续任务处理。 - 将可运行的文档示例代码视为 API 兼容性检查的一部分。在添加构造函数或 API 示例之前，需核对示例中展示的参数和调用形式与实际实现是否一致。 - 不允许不受信任的沙箱或清单数据自行绕过宿主文件系统或基础目录的边界限制。用于本地落盘的逃逸出口，必须由调用处受信任的应用代码控制，绝不能由序列化的清单数据来控制。 - 在记录某项安全授权或边界时，需验证实际代码路径确实执行了该授权。除非某条落盘路径（本地目录、本地文件、归档解压）确实查询了该授权，否则不要声称该授权适用于这条路径。 - 在对敏感数据进行脱敏处理时，需要考虑到错误回溯（traceback）显示、异常链、保留的异常上下文、日志和遥测数据。如果原始异常对象仍然携带敏感输入，仅仅隐藏错误回溯是不够的。 ## 通过格式化和测试检查，再写好PR交接说明 只要改动了代码，就要相应扩展测试，并在提交前确保相关检查全部通过。 - 运行完整的测试套件；在迭代过程中可以按模式运行有针对性的测试。 - 运行静态类型检查；类型提示必须通过检查。 - 对于基于快照的测试，需有意识地重新生成快照，并在之后重新运行整个测试套件。 - 覆盖率必须保持在项目设定的阈值之上。 - 运行格式化工具和代码检查工具（linter）；保持导入语句排序整齐；注释应写成以句号结尾的完整句子。 - 按照项目规定的强制顺序运行各项检查——先格式化，再代码检查，然后类型检查，最后测试。 对于拉取请求（pull request）和提交（commit）： - 使用项目的 PR 模板：包含摘要、测试计划，并在适用时关联相关 issue。 - 提交信息应使用祈使语气简洁书写；保持每次提交小而聚焦。 - 为新增行为添加测试，并针对任何面向用户的变更更新文档。 - 对于符合条件的变更，在给出最终回复之前，需生成一个 PR 交接信息块（摘要、建议的分支名称、标题、草稿描述）。生成这个交接信息块本身并不构成创建分支、提交、推送或发起拉取请求的授权；只有在任务琐碎或仅限于对话、属于不影响行为的元信息或纯文档任务，或用户明确说明不需要时，才可以跳过它。 审查者会关注以下几点：检查是否全部通过；测试是否覆盖了新增行为和边界情况；代码是否可读且风格一致；公共 API 和面向用户的变更是否已在文档中记录；行为变化时是否更新了示例；以及提交历史是否清晰整洁、描述明确。