SuperAPI AI 工具集

factory-runbook

部署与运维

查看项目

更新于 11-02 00:54

技能介绍

factory-runbook 是软件工厂的共享运行机制,主要分为两半:发布流程与运行契约。

用途 它定义每次工厂运行结束时都会执行的确定性发布序列:分支 → 提交 → 推送 → 草稿 MR/PR。工厂编排器在发布步骤调用此技能,也可直接用于发布一次运行的改动。它明确不负责批准或合并——引擎在该步骤之后的门禁即为审批环节。

主要能力

  1. 检出运行分支:通过 scripts/bash/run-branch.sh(Windows 下有对应的 PowerShell 版本)在项目根目录检出运行分支。意图运行(默认)使用 factory/intent/<repo>-<iid>,来自 ADLC_ISSUE_REF;传入 --kind code 时为 mission 代码运行,使用 factory/mission/<repo>-<iid>。可复用已有分支或从 origin 继续,意图泳道与重新派发共用。没有 ADLC_RUN_ID 时为空操作。
  2. 按步骤提交:每次有文件变更的步骤后运行 commit-step.sh,指定 --orchestrator、--step、--output-type(draft|decision|artifact-ref|findings)、--summary、--records 以及该步骤写入、移动或删除的路径。它只暂存白名单内的路径,并输出 sha: <sha> 或 sha: none 作为该步骤的总线标记。
  3. 打开草稿 MR:返回前始终运行 open-mr.sh(代码 mission 传 --kind code)。它只推送运行分支,查找或打开一个草稿 MR(合并提交、不压缩;内联应用 Issue 里程碑与指派人,归属解析器 resolve-mr-ownership.sh 在调用方/完成时运行,而非在 open-mr.sh 内;代理署名标记同样在完成阶段生成,不在此辅助脚本内)。它将 mr_url 写入 ADLC_STEP_OUTPUT。无论结果如何都应调用——空运行不会打开任何内容,门禁不显示链接。同时应在同一 JSON 对象中写入一行结论并保留已有键。

使用方式 直接调用需要运行上下文:来自工厂运行的 ADLC_RUN_ID(通常还有 ADLC_ISSUE_REF 与 ADLC_STEP_OUTPUT),或编排器显式提供的参数(编排器名称、步骤 id、输出类型、路径)。不得凭空编造分支名、步骤或要提交的路径;缺少运行上下文且无显式参数时,应说明缺失内容并停止。此过程不请求批准、不等待回答;辅助脚本非零退出(路径被拒、缺少提交者身份、追踪器范围问题)会终止运行,应报告而非绕过。在工厂运行之外,辅助脚本默认什么都不做,除非用户显式选择加入(.adlc/init-options.json 中 adlc.commit_steps: true,或向 commit-step.sh 传入 --commit);run-branch.sh 与 open-mr.sh 在没有 ADLC_RUN_ID 时永不执行。只有编排器调用的 runbook 才通过这些辅助脚本提交、推送并打开 MR,生命周期技能从不这样做。

运行契约(references/) executor.md 供每个 Kind-A 编排器借用(步骤模式、运行状态、泳道、门禁、收敛);tracker-integration.md 供追踪器集成技能借用(评论总线、标签、租约、提供方操作、MR 归属);lanes.md 供基于泳道的派发消费者使用;mission-brief-template.md 供简报/里程碑作者使用;issues-provider.yml 为提供方解析模板(由 setup 写入仓库副本);run-context.md 说明运行模式与本地会话规则;mission-template.yml 为运行策略默认值(执行、监督、预算)。

适用场景 适用于工厂编排器在每一步骤发布改动、需要按白名单提交并统一打开草稿 MR/PR 的自动化工序;也适用于需要借用共享运行契约的工厂技能。

限制 不批准、不合并;不在缺少运行上下文时动作;不编造分支、步骤或路径;不通过生命周期技能执行发布;辅助脚本失败即终止运行而非绕过。具体依赖项、平台细节与配置项在资料中未完全展开的部分暂未提供。