implementation-strategy

实现策略

工作流

1. 确定你要修改或审查的范围：已发布的公共 API、未发布的分支内 API、内部辅助函数、持久化 schema、线协议、命令行/配置/环境变量接口，或仅文档/示例。
2. 当涉及已发布版本的兼容性时，优先从 origin 确定最新发布标签，只有在远程标签不可用时才退回使用本地标签。在同一任务内可以复用已验证的基线，除非出现新的发布证据或范围发生变化导致其过时：

   BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*' 2>/dev/null || git tag -l 'v*' --sort=-v:refname | head -n1)"
   echo "$BASE_TAG"
   

   使用本地标签作为退路时，应注明其可能已过时。
3. 编码前，先在下方的实现范围约定中记录范围。
4. 找出最接近的现有实现流水线，以及每个受影响关注点的权威函数、类型或模块。优先将所需输入适配到该流水线中，而不是另建平行的 schema、元数据、校验、命名或执行机制。
5. 依据核心决策规则，选择最小而连贯的改动。仅在确有必要支持的边界上添加兼容性机制。
6. 当反馈改变了受支持的行为、兼容性、所有权、协议路径、实现形态或测试组合，或触发复杂度重置时，需重新审视评审关口。否则保留范围约定，继续推进聚焦的修复。
7. 交付前，执行有效性检查。若任一答案为否，则修改设计。

实现范围约定

在现有计划或工作笔记中记录以下四项，并在扩大或缩小实现范围之前更新它们。局部修复可以只用一段简洁的文字；对于不受影响的维度，标注为不适用，而不要臆造不受支持的情形，也不要另建文档：

1. 必需行为： 必须能够运行的最小用户可见场景。
2. 兼容性要求： 必须保持可用的、受支持的已发布行为或持久边界。
3. 有意不支持的情形： 需要拒绝的相近输入或形态，包括何时以及如何拒绝。
4. 受支持的替代方案： 现有的包装器、覆盖、适配器、配置或更底层的 API；若不存在，则写明 none。

如果无法清晰地说明有意不支持的情形，不要一开始就添加通用解析器。应先定义更窄的行为约定。若不存在充分的受支持替代方案，仅在任务确实需要时才添加一个；不要凭空臆造。

已发布版本的复现示例只能证明该形态可以被触达，并不构成支持。只有在公共文档、示例、测试或类型声明中有意涵盖该具体形态，或持久边界要求它，或有具体用户依赖或维护者意图作为依据时，才将其视为兼容性要求。否则，应记录风险，并倾向于尽早拒绝，同时提供现有的受支持替代方案。

评审反馈关卡

仅当反馈改变了范围契约或实现形态时，才使用此检查点。复用未变化的证据，不要重新构建：

Review checkpoint:
- Root cause and required behavior:
- Compatibility evidence and unsupported cases:
- Source of truth:
- Behavior-space change: narrows / unchanged / widens
- Action: focused patch / complexity reset / reject as unsupported

将每个发现归类为：必需行为缺陷、受支持的兼容性要求、同一实现维度的其他组合，或无关问题。扩大行为空间需要新的契约证据。

如果第二个相关发现会向同一抽象中再添加一个条件、协议跳转、兼容性情况或测试排列，则停止打补丁，并执行复杂度重置。只有当具体证据表明该确切情况属于必需或受支持的契约时，才继续。

冻结重置后的规范后，将之后的每个发现归类为：对该规范的违反、有证据支持的修订理由、有意不支持的情况，或无关问题。不要仅因为新发现可以局部修复就恢复增量打补丁。

示例：如果连续的发现要求遍历直接包装器、partial、嵌套包装器、描述符和绑定方法，则不要再添加一跳。除非支持任意包装器图，否则应保留所需的普通可调用行为，并在调用前拒绝有歧义的包装器。

核心决策规则

• 保留已发布的公共 API、已记录的行为以及受支持的持久化边界，或提供明确的迁移路径。
• 对于 main 上的分支本地接口、内部辅助函数、同分支测试以及发布后新增的内容，直接重写，除非它们已经定义了受支持的持久化边界。
• 如果中间快照有意不受支持，未发布的持久化模式版本可以重新编号或压缩；同时更新支持集合和测试。
• 不要将宽泛的 Python 或第三方协议等同于支持所有可表示的形态。
• 优先使用最近的现有流水线，并为模式、文档、验证、标识和调用提供唯一的事实来源。
• 将接口视为调用方正确使用该行为所需了解的全部内容，包括相关时的顺序、错误、生命周期、配置和性能约束；不要仅凭签名判断其大小。
• 在保留新抽象之前应用删除测试：若移除它会将必要的复杂度分散到各调用方，则保留；若移除后复杂度本身随之消失，则删除。
• 只有在存在已说明的变化需求、所有权或可测试性需求时，才添加可替换的边界。当现有流水线已经提供稳定边界时，一个假设性的适配器或仅用于测试的间接层是不够的。
• 只为已说明的需求、受支持的契约或已验证的风险，添加抽象、状态、分类、分支、配置、依赖或并行路径。
• 对于未发布的代码，优先删除或直接替换。将分支本地的实现和测试视为可随时丢弃。
• 优先采用可执行的构造期或验证期错误，并提供现有替代方案，而不是部分模拟协议。
• 将无关重构和已存在的失败排除在补丁之外。
• 测试必需行为、最近的受支持路径，以及每个不受支持类别中的一个代表性情况，而不是测试每一种可构造的排列。
• 在计划和交接说明中明确指出对已支持的已发布行为或持久化格式的更改。

复杂度重置

当出现以下任一情况时，停止继续扩展当前设计：

• 相关发现反复涉及同一组维度，例如包装器、描述符、泛型、绑定、上下文注入、同步/异步分类或提供方变体。
• 补丁对宿主语言或第三方协议做了自行解释，或另行推断可能相互偏离的表示形式。
• 一个范围较窄的需求却需要递归解析、缓存模式、新状态或无关子系统的改动。
• 测试在枚举机制细节，或完整 diff 持续增长，而所需场景仍然很小。

触发任一信号时：

1. 停止编辑，冻结当前版本以便分析，而不是逐条处理评审意见。
2. 按根因对发现进行分组，并重新审视原始需求、范围约定以及受支持的发布版本或持久化边界。
3. 基于上述输入，撰写一份由发现推导出的候选重置规格。不要把累积的评审解释、分支本地机制或同一分支上的测试当作需求。
4. 针对每个受影响的入口点以及最接近的既有受支持路径，审核候选规格。必要时修订，然后在恢复编辑前冻结该规格。
5. 将完整 diff 与预期的合并基准或最新发布标签进行比较，并将每个抽象、分支和测试映射到已冻结的规格，分别标记为 retain、replace 或 delete。
6. 删除没有对应映射的机制，收窄约定，并在产生副作用之前拒绝不受支持的情况。
7. 围绕所需行为、受支持的兼容性、跨入口点一致性以及具有代表性的不受支持类别重建测试。
8. 依据已冻结的规格评估后续发现。在修改规格或扩大行为空间之前，停止并记录新的约定证据。

在计划或工作笔记中使用以下精简重置规格：

Finding-derived reset spec:
- Original required outcome:
- Supported release or durable boundaries:
- Grouped findings and common root cause:
- Invariants across affected entry points:
- Allowed states and behavior:
- Rejected states, failure timing, and side-effect boundary:
- Trusted and untrusted boundaries:
- Single sources of truth:
- Persistence, resume, cleanup, or other lifecycle semantics:
- Non-goals and supported alternatives:
- Representative test categories:
- Diff reset: retain / replace / delete:

候选规格是可被证伪的设计假设，而不是对当前实现的记录。在冻结之前，审核可以对其进行修正。冻结之后，修订规格需要明确的证据，并且在任何修订之后都必须重新运行完整的 diff 映射。

当这些信号已经出现时，不要等待用户或评审者提出重置要求。

有效性检查

在宣布设计完成之前，请用具体证据回答以下所有问题：

• 能否在不提及内部辅助类型或反射机制的情况下描述所需行为？
• 实现是否复用了最接近的既有流水线，而不是维护一套并行的解释逻辑？
• 每个新增抽象和分支是否都对应范围约定或已验证的风险？
• 删除每个新增抽象是否只会把必要的复杂度转移到多个调用方？每个新增边界是否对应已证明的变化、所有权或可测试性需求？
• 相邻的不受支持情况是否在产生副作用之前被拒绝，并且已指明既有的替代方案？
• 测试是否通过能够复现所需行为的最高稳定调用方边界来执行，且预期值独立于实现逻辑？
• 完整 diff 和测试是否覆盖了约定，同时没有使每种可构造的排列组合都成为受支持的情况？
• 最新的评审版本是在收窄或保持行为空间，还是在缺乏证据的情况下扩大了它？
• 如果发生过复杂度重置，每个保留的抽象、分支和测试是否都映射到已冻结的重置规格，且后续发现是否已依据该规格进行分类？

SDK 特定的决策规则

• 对于已发布的 RunState、会话持久化以及其他明确持久化的序列化状态，应视为跨提交、进程和机器时都需要保持兼容的内容。
• 当不受支持的 OpenAI API 或提供方适配器行为已有已发布的默认路径时，除非最新发布边界证明这一破坏性变更是合理的，否则不要将其变为默认的硬错误。优先采用显式开启的严格模式，例如 strict_feature_validation=True，同时通过警告、忽略不受支持的数据或使用明确非空的占位值来保持默认路径的兼容性。
• 对于 OpenAI API 的功能缺口，应同时评估流式和非流式路径。自定义工具调用、多选项 Chat Completions 数据块、非文本工具输出以及类似的提供方载荷差异，不得在一条路径上严格、在另一条路径上宽松或格式错误。
• 当变更引入新的公共 SDK 行为时，不要仅通过硬编码的模块全局变量暴露它。优先使用显式的公共配置对象或参数，在涉及兼容性时保留现有默认行为，并明确说明可选开启的 SDK 默认值。
• 对于 SDK 自有的公共配置，在公共输入边界接受现有的类型化对象和等价字典，同时保留内部的类型化表示。遵循所属模型的校验和额外字段策略，而不是重新构造任意的第三方 schema 语义。
• 将模型相关的设置保留在现有的 model_settings 参数中。添加字典支持时，应保留已发布的构造函数参数、类型化对象的行为以及提供方的请求载荷。
• 将新的可选字段或构造函数参数追加到公共数据类和构造函数的末尾。除非同时提供兼容层并为旧的位置参数调用形式补充回归测试，否则不要将其插入到现有公共字段之前。
• 当阈值和配额值会影响运行时行为时，应将其视为 API 设计的一部分。区分源自 OpenAI 平台配额的值与 SDK 的防御性默认值；如果某个值没有锚定在有文档记录的平台限制上，就不要将其设为无条件默认开启的行为。
• 为公共配置明确定义 None 的语义。例如，应分别用于表示"功能禁用或无 SDK 限制"、"使用 SDK 默认限制"以及"仅禁用该特定限制"，而不是依赖隐式的真值判断。

何时停止并确认

仅当用户请求或已批准的范围约定中未解决下列重要决策时，才需要确认。在该约定范围内的常规修复应继续通过审查和验证完成。

• 该变更会改变最新发布标签中已交付的受支持行为，或有具体证据表明用户实质性依赖了该版本偶然接受的行为。
• 该变更会修改持久化的外部数据、协议格式或序列化状态。
• 正确的解决方案会实质性超出所请求的结果范围，或需要无关的架构工作。
• 复杂性重置触发条件被触发，且较窄的替代方案会改变已发布的受支持契约，而不仅仅是分支内的代码。
• 用户明确要求向后兼容、弃用或迁移支持。

输出要求

当此 skill 对实现方式产生实质影响时，请在推理过程或交接说明中简要说明该决策，例如：

• 兼容性边界：最新发布标签 v0.x.y；仅在分支内重写接口，无需兼容层。
• 实现范围约定：支持 X；保留 Y；在产生副作用之前拒绝 Z；改用受支持的替代方案 W，若不存在则无。
• 复杂度重置：反复出现的边界情况组合表明方案过于宽泛；应从原始需求重新设计，而不是继续增加分支。
• 基于审查发现的重置规格：发现 F1-F3 暴露了跨入口 A-C 的不变量 X；冻结该约定，删除无法对应到需求的机制，并依据该约定评审后续发现。