diff --git a/.agents/skills/unidesk-sub2api/SKILL.md b/.agents/skills/unidesk-sub2api/SKILL.md index 963de900..74c6001a 100644 --- a/.agents/skills/unidesk-sub2api/SKILL.md +++ b/.agents/skills/unidesk-sub2api/SKILL.md @@ -35,6 +35,11 @@ bun scripts/cli.ts platform-infra sub2api image-prepull --target PK01 --confirm - “修复”“恢复”“部署”或排查 Sub2API/Artificer 不自动构成 PK01 变更授权; - 发现根因位于 PK01 时,先保留只读证据并请求明确授权。 - YAML 是 source of truth;target、public exposure、Secret sourceRef、Codex pool 和 sentinel 配置都从 YAML 进入 CLI。 +- 单目标纯版本滚动使用运行面优先快速通道: + - 先完成受控 `rollout` 和既有消费配置 smoke 验收; + - 成功后再补 MDTODO、报告和 commit; + - 直接 push `master`,不创建 PR; + - 该通道只允许目标镜像字段和对应记录变更,源码、CLI、runtime、代理、Secret、多 target 或其他配置变更必须走独立分支和 PR。 - Secret 只输出对象名、key 名、presence、fingerprint 或 redacted prefix;禁止打印完整 token/key。 - 默认 active target 以 YAML `defaults.targetId` 和 target role 为准;当前 `api.pikapython.com` 对应 PK01 host-Docker target。 - 原生运维快照统一走 `ops diagnosis|channels`:默认输出紧凑文本,显式 `--json` 输出结构化结果;命令只读且不在前台模拟自动刷新。 diff --git a/.agents/skills/unidesk-sub2api/references/operations.md b/.agents/skills/unidesk-sub2api/references/operations.md index ef1234d1..202daade 100644 --- a/.agents/skills/unidesk-sub2api/references/operations.md +++ b/.agents/skills/unidesk-sub2api/references/operations.md @@ -107,6 +107,15 @@ proxy secret/config 文件只允许放在受控 Secret/state 路径,输出只 ## 镜像升级 +- 快速通道边界: + - 只适用于单 target 的纯版本滚动; + - 允许变更目标的 `image.repository`、`image.tag`、`pullPolicy` 和对应 MDTODO 报告; + - 不允许夹带 Sub2API 源码、UniDesk CLI、账号池 runtime、代理、Secret、多 target 或其他配置变更; + - 超出边界时使用独立分支和 PR,不得直接 push `master`。 +- 开始前同步: + - 固定主 worktree 保持在 `master`; + - 落后 remote 且存在脏改时,按主 worktree 规范执行 `git stash push -u`、`git pull --ff-only` 和 `git stash apply`; + - 精确保护和处理并行改动,禁止 reset、覆盖式 checkout 或把无关文件带入版本提交。 - 目标 patch: - 只修改目标 target 的 `image.repository`、`image.tag` 或 `pullPolicy`; - 使用 target 附近的上下文 patch; @@ -115,21 +124,21 @@ proxy secret/config 文件只允许放在受控 Secret/state 路径,输出只 - 只调用一次 `sub2api rollout --target --dry-run`; - 默认摘要同时披露当前镜像、目标镜像、presence、plan 和 apply dry-run; - 摘要完整时不再分别调用 `status`、`plan`、`image-prepull` 和 `apply --dry-run`。 -- PR 身份: - - 提交并推送 YAML source truth,创建 draft PR; - - 创建后立即回读准确 PR: - - `bun scripts/cli.ts gh pr view --repo pikasTech/unidesk --json number,state,draft,head,base,headRefName,baseRefName`; - - 核对 PR number、head branch 和 head SHA 与当前分支完全一致; - - 禁止通过“最新 PR”、列表顺序或相邻编号推断操作对象。 - 发布确认: - 只调用一次 `sub2api rollout --target --confirm`; - - 按返回的唯一 `job status` 命令观察终态; + - 按返回的唯一 `job status` 命令等待终态; - job 内顺序完成预拉和 apply,并行完成 status、validate 与既有消费配置 smoke; - 不在外部重复逐阶段轮询。 -- 报告与合并: - - 把 job 终态和分阶段耗时写入同一 PR 的 MDTODO 报告; - - 推送后将准确 PR 标记 ready,再通过 guarded merge 合入; - - 运行面成功但 PR 身份或 source truth 不一致时,先恢复准确分支,不重复 rollout。 +- 运行面验收: + - 以 job 终态中的 status、validate 和既有消费配置 smoke 为标准证据; + - 只有终态缺少 smoke 证据时,补一次 `sub2api smoke --target `; + - rollout 或 smoke 未成功时不得提交和推送目标版本。 +- 成功后收尾: + - rollout 与 smoke 成功后再创建或补全 MDTODO 和任务报告; + - 把目标镜像 YAML、MDTODO 和报告放入同一精确提交; + - 直接执行 `git push origin master`,不创建 draft PR、正式 PR 或 guarded merge; + - 推送失败时先解决远端快进关系,不重复 rollout; + - push 后核对远端 `master` 已包含该提交和目标镜像声明。 - 精确下钻: - 只有 rollout 终态缺少某项证据时,才使用输出给出的下钻命令; - 不固定重复执行 status、validate、public health 或 smoke。 diff --git a/docs/MDTODO/details/sub2api-upstream-reliability/R2.15_Task_Report.md b/docs/MDTODO/details/sub2api-upstream-reliability/R2.15_Task_Report.md new file mode 100644 index 00000000..a3ac6ec4 --- /dev/null +++ b/docs/MDTODO/details/sub2api-upstream-reliability/R2.15_Task_Report.md @@ -0,0 +1,22 @@ +# R2.15 任务报告 + +## 结论 + +- 单目标纯版本滚动改为运行面优先快速通道:先执行受控 `rollout --dry-run`、`rollout --confirm`,按唯一 job 等待终态并完成既有消费配置 smoke 验收。 +- 只有 rollout 与 smoke 成功后才补 MDTODO、报告和 commit,并直接 push `master`;不创建 draft PR、正式 PR 或 guarded merge。 +- 快速通道只允许目标 `image.repository`、`image.tag`、`pullPolicy` 及对应记录变更。 +- Sub2API 源码、UniDesk CLI、账号池 runtime、代理、Secret、多 target 或其他配置变更继续使用独立分支和 PR。 + +## 实现 + +- 更新 Sub2API skill 顶层边界和镜像升级参考流程,删除纯滚动中的 PR 身份、ready 和 guarded merge 步骤。 +- 更新 rollout 成功提示,直接提示后补 MDTODO/报告、提交目标镜像并 push `master`,同时明确 no PR。 +- 保留单次 dry-run、单次 confirm、唯一 job 终态和缺证据才下钻的 5 分钟最短路径。 + +## 验证 + +- `bun --check scripts/src/platform-infra/options.ts`:通过。 +- Sub2API skill `quick_validate.py`:通过。 +- `git diff --check`:通过。 +- `bun scripts/cli.ts platform-infra sub2api rollout --target PK01 --dry-run`:通过;当前镜像与目标镜像均为 `docker.1panel.live/weishaw/sub2api:0.1.156`,plan、current、prepull 和 apply dry-run 均为 `ok`,总耗时 3238 ms。 +- 本次未执行 `rollout --confirm`,未修改 PK01 版本、runtime、代理、Secret 或外部哨兵。 diff --git a/docs/MDTODO/sub2api-upstream-reliability.md b/docs/MDTODO/sub2api-upstream-reliability.md index 99470396..e756292f 100644 --- a/docs/MDTODO/sub2api-upstream-reliability.md +++ b/docs/MDTODO/sub2api-upstream-reliability.md @@ -222,6 +222,9 @@ ### R2.14 [completed] 复盘 PK01 Sub2API v0.1.156 升级耗时 44 分钟的根因,并将同类版本升级优化为预期 5 分钟内可完成的通用流程:修复镜像预拉假异步与 60 秒超时、减少重复 status/plan/job/validate 调用、提供单一语义化发布和验收入口、在 skill 固化 PR 身份校验与最短路径;不修改 Sub2API 源码、账号池 runtime 或外部哨兵,完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.14_Task_Report.md)。 +### R2.15 [completed] + +固化 Sub2API 单目标纯版本滚动快速通道:先完成受控 rollout 与 smoke 验收,成功后再补 MDTODO、报告和 commit,并直接 push master,不创建 PR;该通道仅允许目标镜像 repository、tag、pullPolicy 及对应记录变更,涉及源码、CLI、runtime、代理、Secret、多 target 或其他配置时仍走独立分支与 PR,同时更新 rollout CLI 收尾提示和运维 skill,完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.15_Task_Report.md)。 ## R3 [completed] 增加 Sub2API 客户余额精准批量充值 CLI:支持从原生最近24小时用量提取活跃用户并生成每人增加20美元的补偿计划,也支持显式用户ID或账号 selector;默认 dry-run 输出完整账号、用户ID、当前余额、增额和目标余额,写入必须显式 --confirm 并自动回读对账。本轮只实现并验证 dry-run,禁止实际充值,必须等待用户再次明确授权,完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R3_Task_Report.md)。 diff --git a/scripts/src/platform-infra/options.ts b/scripts/src/platform-infra/options.ts index a845ecd0..3c0c6cb3 100644 --- a/scripts/src/platform-infra/options.ts +++ b/scripts/src/platform-infra/options.ts @@ -478,7 +478,7 @@ function renderSub2ApiRollout(result: Record): RenderedCliResul "", "NEXT", result.ok === true - ? ` source-truth: verify the merged branch still declares ${stringValue(result.desiredImage)}` + ? ` closeout: add MDTODO/report, commit ${stringValue(result.desiredImage)}, then push master directly (no PR)` : ` inspect: bun scripts/cli.ts platform-infra sub2api rollout --target ${targetId} ${mode === "confirmed" ? "--confirm --wait" : "--dry-run"} --full`, "Disclosure: account runtime, Codex pool, proxy, and sentinel configuration are not synchronized by rollout.", );