什么时候需要设计说明
局部修复可用简短问题、触发条件、前后行为与验证说明。跨模块状态、公共 API、凭据、租户、生命周期或数据迁移变化先写设计:用户旅程、责任边界、替代方案、失败模式、迁移与回退、验证和文档影响。 修改行为前阅读架构、验收和代码地图。不能为通过当前测试删除用户要求;不能把 Provider 特例散入通用执行流程,或用原始凭据进入 guest 作为兼容回退。用真实改动解释提案
仓库的 E2B OCI 准备是一个跨模块例子:用户选择公开 OCI Harness 后,需要先准备 Session 自有 Template,再创建计算资源。设计必须说明 Template/build 回执、构建未知结果、恢复与 compute-before-template 清理,不能只给一个镜像拉取函数。其专项证据保留了模型输出失败与后续限定范围成功,可作为描述验证边界的范例,不是本次新运行结果。 建议设计稿结构:问题与成功旅程 → 当前限制 → 对象/API/状态变化 → 备选方案及取舍 → 凭据与租户边界 → 不确定结果和清理 → 迁移/回退 → 实际检查与未验证项。准备可审阅的变更
使用仓库实际 PR 模板:示例:把已验证的局部修复写成 PR 说明
下面根据2026-11-16 Fleet 配额诊断记录整理,展示说明方式;不是新建或已发布的 PR,也不是本轮重新运行的验证。 建议标题:让 Fleet 显示被拒绝创建操作的配额原因 Problem and resulting behavior 当 Provider 明确拒绝 Sandbox 创建时,数据库已保存sandbox_quota_exceeded,但 Fleet 只为 unknown 操作返回 reason,导致 Console 无法显示已有的配额说明。让 rejected 操作也返回安全的 reason;completed 操作继续省略该字段,使用户能区分明确拒绝与创建结果未知。
Affected contracts
修改 Fleet 资源操作投影及其回归断言。保持租户过滤,既不增加上游原始响应,也不改变创建或清理语义。Console 可使用已有中英文说明。
Verification actually run
历史记录报告了 54 个文件 / 154 项本地 PostgreSQL 回归通过;随后类型检查发现新增测试 fixture 缺少构造依赖,修正后 npm run check 和完整 worker 套件 8 项检查通过。另有 32 条保留旅程 / 64 个主 Run 的历史状态审计,范围包括已存回复、产物摘要和指定记录中的清理状态。
Remaining limitations
以上不是新一轮云执行,也不是账户全局资源盘点;不能据此认证其他新增连接器或全部 SaaS 账户。具体命令与历史范围保留在原证据中。
这个例子包含触发条件、用户可见变化、接口影响和真实验证边界。没有将修复前的失败删掉,也没有用“全部测试通过”掩盖不同检查的执行时间与范围。
跨模块提案应回答的具体问题
以 E2B OCI 准备为例,设计说明至少回答:
设计稿把方案与实际验证分开:尚未执行的步骤写入验收计划,执行后再追加有范围的结果。读者应能从提案判断哪里可能发生不可逆副作用、谁负责恢复、哪些旧 Session 或旧配置受影响,而不必从代码差异中猜测。