implementation-strategy

实现策略

工作流

1. 确定你要修改或审查的范围：已发布的公共 API、尚未发布的分支内 API、内部辅助工具、持久化架构、线协议、CLI/配置/环境变量范围，或仅文档/示例。
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. 找到最近的现有实现流程，以及每项受影响内容的事实来源函数、类型或模块。优先将所需输入适配到该流程，而不是创建并行的架构、元数据、验证、标识、转换或执行机制。
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

将每条发现归类为必需行为缺陷、受支持的兼容性要求、同一实现维度的另一种组合，或无关问题。扩大行为范围需要新的约定证据。

如果第二条相关发现会为同一抽象增加另一个条件、协议跳转、兼容性情形或测试排列，请停止修补并执行复杂度重置。只有具体证据表明精确情形属于必需或受支持的约定时，才继续。

重置规范冻结后，将后续每条发现归类为违反该规范、有证据支持的修订理由、有意不支持的情形，或无关问题。不要仅仅因为新发现可以局部修复，就恢复渐进式修补。

示例：如果接连出现的发现要求遍历直接包装器、嵌套包装器、泛型适配器、模块互操作边界和绑定方法，不要再增加一次跳转。除非支持任意包装器图，否则保留必需的普通可调用行为，并在调用前拒绝含糊不清的包装器。

核心决策规则

• 保留已发布的公共 API、文档说明的行为和受支持的持久化边界，或提供明确的迁移路径。
• 除非它们已定义受支持的持久化边界，否则直接重写分支内接口、内部辅助函数、同分支测试和 main 上发布后的新增内容。
• 如果有意不支持中间快照，则可以重新编号未发布的持久化架构版本，或将其合并到下一个架构版本；同时更新支持集和测试。
• 不要将宽泛的结构类型、重载、泛型、JavaScript 反射接口、模块边界或第三方接口等同于支持所有可表示的形态。
• 优先使用最接近的现有流水线，并让架构、文档、验证、身份、包导出、转换和调用各自只有一个事实来源。
• 将接口视为调用方为正确使用行为所必须了解的一切；相关时包括顺序、错误、生命周期、配置和性能约束。不要只根据签名判断接口大小。
• 保留新抽象前先进行删除测试：如果移除它会将必需的复杂性分散到调用方，就保留；如果复杂性本身会随之消失，就移除。
• 只有在已证明存在差异、所有权需求或可测试性需求时，才增加可替换边界。如果现有流水线已提供稳定边界，仅凭假设中的适配器或仅用于测试的间接层并不足够。
• 只有出于明确需求、受支持的约定或已验证的风险，才增加抽象、状态、分类、分支、配置、依赖项或并行路径。
• 对未发布的代码，优先删除或直接替换。将分支内的实现和测试视为可丢弃。
• 优先在构建或验证时提供可操作的错误，并给出已有替代方案，而不是部分模拟接口。
• 不要将无关重构和既有故障纳入补丁。
• 测试必需行为、最接近的受支持路径，以及每个不支持类别的一个代表性情形，而不是每一种可构造的排列。
• 在计划、变更说明和交接中指出对受支持的已发布行为或持久化格式所做的更改。

复杂度重置

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

• 相关问题不断组合相同维度，例如包装器、重载、联合成员、泛型、绑定、上下文注入、同步／异步或流式分类、运行时目标，或提供方变体。
• 补丁需要解释 TypeScript、JavaScript 反射、模块解析或第三方接口，或分别推断可能产生偏差的表示形式。
• 范围狭窄的需求需要递归解析、缓存模式、新状态，或无关的软件包或运行时适配器改动。
• 测试开始枚举实现机制，或完整差异不断扩大，而所需场景仍然很小。

触发上述任一情况时：

1. 停止编辑，冻结当前修订版本以供分析，而不是逐条处理意见。
2. 按根本原因归类问题，并重新阅读原始需求、范围契约以及受支持的发布版本或稳定边界。
3. 使用这些输入编写一份由问题推导出的候选重置规范。不要将累积的审查说明、分支内机制或同一分支的测试视为需求。
4. 对照每个受影响的入口点和最接近的现有受支持路径审核候选规范。按需修订，然后在恢复编辑前将其冻结。
5. 将完整差异与预期的合并基线或最新发布标签进行比较，并将每个抽象、分支和测试映射到已冻结的规范，标记为 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:

候选规范是一项可证伪的设计假设，而不是对当前实现的记录。审核时可以在冻结前修正它。冻结后，只有明确的证据才能支持修订；任何修订后都必须重新执行完整的差异映射。

如果相关信号已经出现，不要等待用户或审查者要求执行此重置。

SDK 专属决策规则

• 如果已发布的软件包导出映射、ESM/CJS 入口点、公共类型签名、RunState、会话持久化、沙箱状态，以及文档说明的模型／提供方配置支持跨进程、运行时或机器使用，则应将它们视为兼容性敏感项。
• 将持久化或恢复的状态视为不可信输入。不得允许 RunState、沙箱会话状态、提供方快照状态和序列化会话数据覆盖受信任的运行时配置，例如 baseUrl、凭据、secretRefs、launchParameters、environment、userParameters、清单根目录或提供方蓝图。
• 只有在可以安全地认定请求未在服务端被接受时，才进行重试或重放。如果服务端可能已收到请求后再进行重放，WebSocket 超时、MCP 重连、Realtime response.create、托管工具调用和沙箱操作都可能导致模型或工具副作用重复发生。
• 避免在 OpenAI API 的不同接口间进行有损转换。Responses 项目、Chat Completions 消息、Realtime 工具、压缩输出和 SDK 协议项目，应保留受支持的数据；在严格路径中，如果无法做到这一点，则应快速失败，而不是静默丢弃不受支持的内容、ID 或元数据。
• 在每条输入路径上应用策略决策，而不仅仅是在主要运行循环中。检查流式和非流式运行、会话回调、本地会话、OpenAI Conversations 会话、压缩会话、RunState 恢复和公共历史重放中的 reasoningItemIdPolicy、审批策略、严格验证和模型默认值等设置。
• 在执行破坏性存储更新前，先规范化并验证替换数据。只有在新载荷成功转换后，压缩、会话替换和恢复路径才能清除或替换持久化历史记录；如果部分清除失败，则应恢复原始快照，且不得重复添加项目。
• 当 undefined 有意义时，保留 API 默认值。除非 API 契约要求，否则不要将省略的 OpenAI 或提供方设置规范化为具体的 SDK 默认值；审批策略、生命周期默认值、模型设置和提供方选项尤其需要注意这一点。
• 根据权威来源验证提供方行为，并在可行时进行小规模的实时探测。提供方文档、生成的 SDK 类型和实时后端可能会在字段名称、超时单位、凭据刷新行为和生命周期语义方面存在差异。

有效性检查

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

• 能否在不提及内部辅助类型或反射机制的情况下描述所需行为？
• 实现是否复用了最接近的现有流程，而不是维护一个并行的解释逻辑？
• 每个新增抽象和分支是否都对应范围契约或已验证的风险？
• 删除每个新增抽象是否只会将必要的复杂性推给多个调用方？每个新边界是否都对应已证实的差异、所有权或可测试性需求？
• 对于不受支持的相邻情况，是否在产生副作用前予以拒绝，并指出现有替代方案？
• 测试是否在能够复现所需行为的最高层级、稳定调用边界进行，并且预期值独立于实现逻辑？
• 完整差异和测试是否覆盖了契约，同时没有让每种可构造的排列组合都受到支持？
• 最新的评审修订是否缩小或保持了行为范围，而非在缺乏证据的情况下扩大范围？
• 如果进行了复杂性重置，保留的每个抽象、分支和测试是否都对应冻结后的重置规范，之后发现的问题是否都按该规范进行了分类？

何时停止并确认

• 更改会影响最新发布标签中提供的受支持行为，或者有具体证据表明，用户实质上依赖了某项发布时偶然接受的行为。
• 更改会修改持久化的外部数据、协议格式或序列化状态。
• 正确的解决方案会大幅超出请求的结果，或需要进行无关的架构工作。
• 复杂度重置触发条件已满足，而更窄的替代方案会改变已发布的受支持契约，而非仅影响分支内代码。
• 用户明确要求向后兼容、弃用或迁移支持。

输出要求

当此技能实质性影响实现方案时，请在推理或交接中简要说明决定，例如：

• 兼容性边界：最新发布标签 v0.x.y；仅重写分支内接口，无需垫片。
• 实现范围契约：支持 X；保留 Y；在产生副作用前拒绝 Z；使用受支持的替代方案 W，或说明不存在替代方案。
• 复杂度重置：重复出现的边缘情况组合表明方案范围过广；应从原始需求重新设计，而非再添加一个分支。
• 基于发现的重置规范：发现 F1-F3 揭示了入口 A-C 中的不变量 X；固定该契约，删除无法映射的机制，并根据后续发现进行审查。