Production Upgrade 是一个安全优先的生产化升级工作流，用于将既有的技能、插件、智能体、MCP 集成或智能体系统包升级到生产标准。其质量基准来自 Databricks 重建经验：理解真实操作者痛点、在实现前决定架构、将承重逻辑移入确定性代码、有意保留兼容性，并用负向与对抗性证据证明安全性。深度应与风险匹配，而不是与另一个项目的文档数量匹配。
适用场景
适用于遗留制品、大规模重写、破坏性迁移、不安全集成或生产就绪声明。不适用于小错别字、孤立缺陷修复、常规依赖升级或只读状态查询，除非用户明确要求完整的升级工作流。
前置条件
需要目标仓库或制品及其项目说明；具备研究和准备本地更改的权限。发布、部署、合并、破坏性清理和外部消息传递仍需单独批准。需要外部定义契约的当前一手来源。预授权的 Read、Write 和 Edit 能力仅适用于本地、限定范围的实现文件。网络、shell、任务跟踪器、子智能体、安装和发布能力仍受宿主和项目批准约束。
编排
使用五个专注角色。当宿主支持隔离子智能体时，在 references/roles 下分派角色包，并由协调者核对证据。否则在主上下文中顺序执行相同角色包。同一身份或内联审查属于自审，永远不是独立审查。
角色与权限：
- 研究员：无变更权限，输出来源台账、痛点目录、明确缺口。
- 架构师：无变更权限，输出范围综合、决策记录、迁移计划。
- 实现工程师：仅限本地限定范围写入，输出最小实现和聚焦测试。
- 验证工程师：无变更权限，输出复现命令、结果和哈希。
- 安全对手：无变更权限，输出威胁驱动的发现和漏洞利用尝试。
操作步骤
-
恢复上下文并建立权限：阅读仓库说明、架构负责人、生成文件规则、当前状态、工作树、活跃审查和现有任务状态。如果仓库使用 Beads，遵循 references/beads-workflow.md：prime、search、create 或 reuse、claim before mutation、attach receipts。项目政策可将 Beads 设为强制。保留脏工作和贡献者署名。在可用时于分支或工作树中隔离大范围更改。记录确切的初始修订和当前授权的操作。
-
设计前先研究：审计现有制品、每个活跃和已退役能力、消费者、包标识、安装路径和已知缺陷。研究产品、API、协议、安全和运行时契约的当前一手来源。在可访问且适当时，添加社区或问题证据以反映真实操作者痛点。构建痛点目录：症状、触发条件、根本原因、影响范围、当前变通方法、证据和正确的智能体原语。记录来源缺口，而不是用假设填补。至少比较一个相关生产基准的方法论，然后解释风险如何证明更窄或更深的处理是合理的。
-
决定范围与安全：围绕不同的操作者成果整合能力，而非配额。编写架构决策，涵盖采纳、修改和拒绝的替代方案；权限边界；兼容性；迁移；回滚；以及明确的非目标。对输入、输出、凭据、网络目的地、文件路径、依赖、重试、变更、审查者、证据和发布进行威胁建模。默认离线或只读行为。未知契约、状态、字段、目的地或权限应失败关闭。将确定性分类、算术、验证、转换和政策决策放入经过审查的脚本。模型推理用于综合和模糊性，而非承重计算。
-
计划与实现：在编辑前定义可衡量的验收门。包括结构、行为、安全、迁移、来源和发布证据。实现最小的完整设计。保持可移植核心独立于宿主适配器，避免不增加已验证能力的基础设施。保留 ID 或提供机器可读的迁移映射。破坏性行为需要明确的主版本决策和面向用户的迁移路径。绝不生成明文密钥、远程管道安装程序、无界重试、静默破坏性操作、伪造的提供者响应或一揽子扫描器豁免。
-
按比例验证：先运行最窄的聚焦测试，然后运行仓库要求的门。覆盖正向、负向、边缘、对抗、失败和回滚路径。当声称认证时，故意破坏的变体必须使同一门失败。验证生成的投影、打包文件列表、从一次性路径安装以及在这些表面更改时的移除或回滚。独立复现每个重要的自动审查发现。审查者沉默或计费失败是不可用证据，不是批准。使用 references/evidence-contract.md 记录证据，并在不执行记录命令的情况下审计：python3 scripts/audit_evidence.py upgrade-evidence.json --root <repository>
-
在批准边界停止：报告确切的候选修订、更改的表面、测试结果、未解决风险、审查者状态、迁移影响、回滚和发布状态。除非用户和项目政策授权，否则不要提交、推送、打开或更新 PR、合并、打标签、发布、部署、删除或对外发消息。高风险发布批准绑定到确切修订；修订更改需要重新批准。
输出
返回简洁的执行状态，以及研究、决策、威胁模型、迁移映射、测试和证据清单的链接。使用以下声明级别：
- BLOCKED：必需的安全或权限边界失败。
- CANDIDATE：实现和本地证据存在；独立审查或批准仍待完成。
- REVIEWED：独立审查绑定到确切修订；发布尚未授权。
- RELEASE-READY：所有必需门和确切修订授权均存在。
错误处理
项目政策要求 Beads 但缺失时：在变更前停止。缺少子智能体时：内联执行角色包并标记审查为自审。缺少当前一手来源时：约束或移除受影响的能力。权限冲突时：停止并在指定负责人处解决冲突。测试失败或未知审查者发现时：保持 BLOCKED 或 CANDIDATE；绝不将其平均为分数。无关的脏工作时：保留并隔离；不要重置或覆盖。
示例
一个窄 API 包可能比 Databricks 需要更少文档，但仍需要官方契约审计、威胁模型、迁移映射、对抗性测试、确切修订证据和明确的研究缺口。具有破坏性方法的 MCP 服务器比离线只读技能需要更强的输入、授权、回滚和实时边界证据。模型中立的技能可由任何有能力的模型手动使用，而命名的原生支持仍限于具有注册表支持回执的测试框架。
资源
Beads 工作流、证据契约、运行时可移植性、专家角色包、痛点目录模板、决策记录模板。