@optima-chat/dev-skills 0.11.0 → 0.13.0

package/.claude/skills/cn-deploy/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: cn-deploy
+description: 当用户请求把服务发布/部署/构建到 cn-stage、跑云效流水线、cn-stage 发版、部署某个分支到 cn-stage、触发 cn 构建、yunxiao 部署、"把 xx 发到 cn"时，使用此技能。覆盖 cn-stage 全部 20 个服务（构建→DB迁移→SAE 发布一条龙）。
+---
+
+# cn-deploy - 云效 cn-stage 流水线发布
+
+## 用途
+
+把服务的 GitHub 代码经云效 Flow 流水线发布到阿里云 cn-stage（SAE）。一条命令完成：
+Codeup mirror 同步 → 构建（含 NEXT_PUBLIC 自动烤/境内镜像源改写）→ DB 迁移 → SAE 滚动发布 → 部署 sha 校验。
+
+## 命令
+
+```bash
+optima-cn-deploy <service>                    # main 全链发布
+optima-cn-deploy <service> --branch feat/xxx  # 非 main 分支构建+部署
+optima-cn-deploy <service> --no-wait          # 只触发不等待
+optima-cn-deploy --list                       # 列出全部可发服务
+```
+
+## 使用要点
+
+1. **先 `--list` 确认服务名**（20 个服务，含 commerce-backend / optima-scout）。
+2. 全链约 3-8 分钟（agentic-chat 最重）。触发后会输出云效 run 链接，可发给用户自行围观。
+3. **凭证零配置**：构建凭证由云效变量组 `cn-stage-build-credentials`(41970) 供给，不需要注入任何 secret。
+4. 分支构建会把该分支代码部署到 cn-stage（替换现运行版本）——用户明确要求部署分支时才用。
+5. 失败排查：命令输出的 flow.aliyun.com 链接里看具体 step 日志；常见原因是该分支/仓的 Codeup mirror 凭证问题（命令会在 mirror 步就报错并中止，不会构建旧代码）。
+6. 成功标准：最后一行 `✓ SAE ImageUrl tag=<sha>` —— 流水线绿且 SAE 真的钉到了目标 commit。只看流水线绿不算完成。
+
+
+## cn-prod vtag 发版（⚠️ 待 svenyang 首次验证通过后再日常使用）
+
+```bash
+optima-cn-deploy <service> --vtag cn-v1.2.3               # 先 stage 同 tag 验证
+optima-cn-deploy <service> --env prod --vtag cn-v1.2.3    # prod 发版
+```
+
+- prod 是 vtag 制：必须先 `git tag cn-vX.Y.Z && git push`，工具拒绝无 vtag / 裸 v* / 带 --branch 的 prod 请求
+- prod 流水线构建后**停在人工卡点**（xbfool/svenyang 在云效控制台审批），之后 DB 迁移 + digest 钉死部署自动走完
+- 成功标准：prod SAE ImageUrl 为 `@sha256:` digest 寻址（工具最后一行校验）
+- 用户请求发 cn-prod 时：确认已有 stage 验证过的 cn-v tag；没有则先引导走 stage
+
+## 前置依赖
+
+- `aliyun` CLI 已配置（profile 默认 `aliyun-optima`，可用环境变量 `OPTIMA_ALIYUN_PROFILE` 覆盖为自己的 RAM 用户 profile）
+- `gh` 已登录（mirror 同步需要 GitHub token）
+
+## 边界
+
+- cn-prod 仅走 vtag 制（见上），且有人工卡点闸门；日常无 vtag 的构建只发 cn-stage。
+- 服务注册表是 optima-terraform `alicloud/stacks/cn-prod-buildbox/yunxiao/` 的快照；新增服务先在那边 gen-pipelines 建好流水线，再同步本工具的 SERVICES 表。

package/.codex/skills/cn-deploy/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: cn-deploy
+description: 当用户请求把服务发布/部署/构建到 cn-stage、跑云效流水线、cn-stage 发版、部署某个分支到 cn-stage、触发 cn 构建、yunxiao 部署、"把 xx 发到 cn"时，使用此技能。覆盖 cn-stage 全部 20 个服务（构建→DB迁移→SAE 发布一条龙）。
+---
+
+# cn-deploy - 云效 cn-stage 流水线发布
+
+## 用途
+
+把服务的 GitHub 代码经云效 Flow 流水线发布到阿里云 cn-stage（SAE）。一条命令完成：
+Codeup mirror 同步 → 构建（含 NEXT_PUBLIC 自动烤/境内镜像源改写）→ DB 迁移 → SAE 滚动发布 → 部署 sha 校验。
+
+## 命令
+
+```bash
+optima-cn-deploy <service>                    # main 全链发布
+optima-cn-deploy <service> --branch feat/xxx  # 非 main 分支构建+部署
+optima-cn-deploy <service> --no-wait          # 只触发不等待
+optima-cn-deploy --list                       # 列出全部可发服务
+```
+
+## 使用要点
+
+1. **先 `--list` 确认服务名**（20 个服务，含 commerce-backend / optima-scout）。
+2. 全链约 3-8 分钟（agentic-chat 最重）。触发后会输出云效 run 链接，可发给用户自行围观。
+3. **凭证零配置**：构建凭证由云效变量组 `cn-stage-build-credentials`(41970) 供给，不需要注入任何 secret。
+4. 分支构建会把该分支代码部署到 cn-stage（替换现运行版本）——用户明确要求部署分支时才用。
+5. 失败排查：命令输出的 flow.aliyun.com 链接里看具体 step 日志；常见原因是该分支/仓的 Codeup mirror 凭证问题（命令会在 mirror 步就报错并中止，不会构建旧代码）。
+6. 成功标准：最后一行 `✓ SAE ImageUrl tag=<sha>` —— 流水线绿且 SAE 真的钉到了目标 commit。只看流水线绿不算完成。
+
+
+## cn-prod vtag 发版（⚠️ 待 svenyang 首次验证通过后再日常使用）
+
+```bash
+optima-cn-deploy <service> --vtag cn-v1.2.3               # 先 stage 同 tag 验证
+optima-cn-deploy <service> --env prod --vtag cn-v1.2.3    # prod 发版
+```
+
+- prod 是 vtag 制：必须先 `git tag cn-vX.Y.Z && git push`，工具拒绝无 vtag / 裸 v* / 带 --branch 的 prod 请求
+- prod 流水线构建后**停在人工卡点**（xbfool/svenyang 在云效控制台审批），之后 DB 迁移 + digest 钉死部署自动走完
+- 成功标准：prod SAE ImageUrl 为 `@sha256:` digest 寻址（工具最后一行校验）
+- 用户请求发 cn-prod 时：确认已有 stage 验证过的 cn-v tag；没有则先引导走 stage
+
+## 前置依赖
+
+- `aliyun` CLI 已配置（profile 默认 `aliyun-optima`，可用环境变量 `OPTIMA_ALIYUN_PROFILE` 覆盖为自己的 RAM 用户 profile）
+- `gh` 已登录（mirror 同步需要 GitHub token）
+
+## 边界
+
+- cn-prod 仅走 vtag 制（见上），且有人工卡点闸门；日常无 vtag 的构建只发 cn-stage。
+- 服务注册表是 optima-terraform `alicloud/stacks/cn-prod-buildbox/yunxiao/` 的快照；新增服务先在那边 gen-pipelines 建好流水线，再同步本工具的 SERVICES 表。

package/AGENTS.md

@@ -13,6 +13,7 @@ Prefer the installed CLI tools over reimplementing long shell workflows:
 - `optima-grant-credits <email|phone|userId> --credits <n> [options]`
 - `optima-product <create|update|add-channel|toggle-channel|show> [options]` — manage paid-plugin marketplace Products + Stripe channels (Wave 1.5 admin endpoints; stage default)
 - `optima-entitlement <grant|revoke|list> [options]` — admin-grant / revoke / list paid-plugin entitlements (refuses revoke of PAYMENT / PARTNER source)
+- `optima-cn-deploy <service> [--branch feat/xxx] [--no-wait]` — 云效 Flow 发布到 cn-stage(mirror 同步→构建→DB 迁移→SAE 发布→sha 校验;20 服务,凭证由云效变量组供给零配置)
 - `optima-plugin <show|set-paid|set-default> [options]` — flip a plugin's skills-side paid/free state (isPaid) + defaultForUser (the user-facing gate; pairs with optima-product for the billing side)
 
 For code-reading tasks across Optima repositories, use `gh` commands against `Optima-Chat/<repo>`.
@@ -30,6 +31,7 @@ After `npm install -g @optima-chat/dev-skills`, this package installs skills und
 - `grant-credits`
 - `restart-ecs`
 - `use-commerce-cli`
+- `cn-deploy`
 
 ## Tooling Assumptions
 

package/README.md

@@ -88,6 +88,7 @@ Claude:
 | `/query-db` | 查询数据库 | `/query-db user-auth "SELECT COUNT(*) FROM users"` | ✅ |
 | `/generate-test-token` | 生成测试 token | `/generate-test-token` | 🔧 Development |
 | `/read-code` | 阅读代码 | `/read-code commerce-backend app/main.py` | - |
+| `/cn-deploy` | 发布服务到 cn-stage（云效流水线一条龙） | 「把 billing 发到 cn-stage」 | cn-stage |
 
 **说明**：
 - 命令支持 CI、Stage、Prod 三个环境
@@ -109,6 +110,7 @@ Claude:
 | `optima-grant-credits` | 赠送积分 | `optima-grant-credits user@example.com --credits 10000 --env prod`（`optima-grant-balance` 为废弃别名）|
 | `optima-entitlement` | 产品权益 grant/revoke/list | `optima-entitlement grant 18898654855 --product-key scout-gift --justification "..." --env cn-prod` |
 | `optima-account` | 账号 status/ban/unban | `optima-account ban user@example.com --reason "abuse" --env prod` |
+| `optima-cn-deploy` | 云效 Flow 发布到 cn-stage（构建→DB迁移→SAE 发布→sha 校验，20 服务） | `optima-cn-deploy billing` / `optima-cn-deploy user-auth --branch feat/xxx` |
 
 > **4 环境 + 标识符**：`grant-subscription` / `grant-credits` / `entitlement` / `account` 均支持 `stage` / `prod` / `cn-prod` / `cn-stage`。标识符 `<email\|phone\|userId>`——**cn-prod / cn-stage 用户多为手机号注册**，三种均可；AWS stage/prod 仅 email。`ban`/`unban` 及 `account status` 的禁用态读取需 admin-用户凭证（Infisical `/shared-secrets/credentials`；cn 另需 `INFISICAL_CN_EMAIL/PASSWORD`）。
 

package/bin/helpers/cn-deploy.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * optima-cn-deploy —— 云效 Flow cn-stage 流水线一条龙触发器(团队版)。
+ *
+ * 对应 optima-terraform alicloud/stacks/cn-prod-buildbox/yunxiao/ 的 cn-run.py,
+ * 去掉 buildbox SSH 依赖(凭证由云效变量组 41970 供给,2026-07-13 起控制台/API 裸跑均可)。
+ *
+ * 做四件事(每件都是踩过的坑):
+ *   1. 触发服务仓 Codeup mirror 同步并等目标分支追平 GitHub —— mirror 不新鲜=构建旧代码。
+ *      GitHub token 用 `gh auth token`(需本机 gh 已登录)。
+ *   2. StartPipelineRun;--branch 时带 runningBranchs 覆盖服务仓 source 分支。
+ *   3. 轮询到终态,给出云效 run 链接。
+ *   4. SUCCESS 后校验 SAE ImageUrl tag == 目标分支 HEAD short-sha(防"流水线绿但没部上");
+ *      aliyun API 偶发空返回,带重试守卫。
+ *
+ * 用法:
+ *   optima-cn-deploy billing                      # main 全链(构建→迁移→SAE 发布)
+ *   optima-cn-deploy user-auth --branch feat/xxx  # 非 main 分支构建+部署到 cn-stage
+ *   optima-cn-deploy gateway-core --no-wait       # 只触发不等待
+ *   optima-cn-deploy --list                       # 列出全部可发服务
+ *   optima-cn-deploy billing --vtag cn-v1.2.3     # stage 按版本 tag 构建(发版前验证)
+ *   optima-cn-deploy billing --env prod --vtag cn-v1.2.3
+ *       # cn-prod vtag 发版:构建→停在人工卡点(云效控制台审批)→迁移→digest 钉死部署
+ *
+ * 前置: aliyun CLI(profile 默认 aliyun-optima,可用 OPTIMA_ALIYUN_PROFILE 覆盖)+ gh 已登录。
+ * 流水线定义的单一信源在 optima-terraform yunxiao/(gen-pipelines.py);本表为其快照,
+ * 新增服务后同步(pipelineId 稳定,不常变)。
+ */
+import { execFileSync } from 'node:child_process';
+
+const ORG = '6a17b6282bf8b1184fc0e0c6';
+const ENDPOINT = 'devops.cn-hangzhou.aliyuncs.com';
+const PROFILE = process.env.OPTIMA_ALIYUN_PROFILE || 'aliyun-optima';
+const CODEUP_BASE = `https://codeup.aliyun.com/${ORG}`;
+
+// 服务注册表(快照自 optima-terraform services.stage.env + gen-pipelines.py,2026-07-13)
+interface Svc { pipelineId: number; repo: string; saeAppId?: string; prodSaeAppId?: string; }
+const SERVICES: Record<string, Svc> = {
+  'agent-portal':             { pipelineId: 5118519, repo: 'optima-portals',     saeAppId: 'fe757f78-d18d-4480-9402-fe59d4721055', prodSaeAppId: '9211db38-a255-4393-ae92-7a7bb41b583d' },
+  'agentic-chat':             { pipelineId: 5118520, repo: 'agentic-chat',       saeAppId: '6aea1ce1-f813-4e1c-8e97-d1ecb5398e37', prodSaeAppId: '6e290c73-a646-43ef-9da5-ad0b2e7eff73' },
+  'billing':                  { pipelineId: 5118521, repo: 'optima-billing',     saeAppId: '09d8e292-dc64-4af8-bce5-0a56cb666921', prodSaeAppId: '6c31cf82-8802-4d45-b6a2-e9d7c83ccce9' },
+  'browser-backend':          { pipelineId: 5118522, repo: 'optima-browser-use', saeAppId: '1fced3f6-a80a-41a4-8f23-e4d5a467f8eb', prodSaeAppId: 'eb782ed9-c468-4e81-a0fe-87e5b4264192' },
+  'commerce-backend':         { pipelineId: 5107005, repo: 'commerce-backend',   saeAppId: '49d09808-508c-471a-9560-553c49a67f72', prodSaeAppId: 'd40597b6-a98c-4063-9297-8b9fdfa8add4' },
+  'commerce-rq-scheduler':    { pipelineId: 5118523, repo: 'commerce-backend',   saeAppId: '1d2810ef-889e-4675-b6e6-a299e4722e68', prodSaeAppId: '762dd7a5-7fe8-41ed-9332-cfd31b0e087e' },
+  'commerce-rq-worker':       { pipelineId: 5118524, repo: 'commerce-backend',   saeAppId: 'd661da87-6d24-40b8-93ed-e1c967d8abe2', prodSaeAppId: '2c9ee19a-5062-4205-9f5b-6ae3f8062a23' },
+  'gateway-core':             { pipelineId: 5118525, repo: 'optima-gateway',     saeAppId: '9326b7ff-da52-48d6-86db-9c4a884be108', prodSaeAppId: 'a08ce23f-3d3e-4d89-a2cf-53c8adba614e' },
+  'gw-admin':                 { pipelineId: 5118526, repo: 'optima-gateway',     saeAppId: '90e0daf7-7910-46b8-b5bf-a0b8bcc60859', prodSaeAppId: 'c6bc5a78-b27f-46e2-825a-eaa338c23645' },
+  'kb-backend':               { pipelineId: 5118527, repo: 'kb-skills',          saeAppId: 'c7f65160-9d9e-416e-9e36-5439010d2b2d', prodSaeAppId: '732dfc8c-ed78-43f7-a722-c614359ff1a1' },
+  'ops-portal':               { pipelineId: 5118529, repo: 'optima-portals',     saeAppId: '41d0ee66-8402-4e72-bfda-8eba75d1270c', prodSaeAppId: '69e513fd-29bf-4355-a275-5eba82b21136' },
+  'optima-generation':        { pipelineId: 5118530, repo: 'optima-gen',         saeAppId: '327856d5-8b18-4e15-bfd8-b8bd3b807ffa', prodSaeAppId: '868d1a69-12c9-4bb7-868b-3e89c26784b5' },
+  'optima-generation-worker': { pipelineId: 5118531, repo: 'optima-gen',         saeAppId: 'ad75b3b0-9ff4-443d-b0ef-81886bc7aa60', prodSaeAppId: '2adc941e-374b-406a-9863-e53d40bc9500' },
+  'optima-scout':             { pipelineId: 5117336, repo: 'optima-scout',       saeAppId: 'bac2c3a4-90ce-49a6-81d5-caa38cb5c807', prodSaeAppId: 'f5bb7e82-e57c-4bd4-83ae-2c25f8d38647' },
+  'optima-sentinel':          { pipelineId: 5118532, repo: 'optima-sentinel',    saeAppId: '3759db7b-4640-4a04-8436-4f241f0ec9d9', prodSaeAppId: 'e120e70c-b2c1-49ef-a66c-9016fd2d807d' },
+  'optima-sentinel-worker':   { pipelineId: 5118533, repo: 'optima-sentinel',    saeAppId: '7c975caf-ebfb-4bb3-91c4-2a8c83d1d2e5', prodSaeAppId: 'e0f9b92c-00af-4ade-9b07-15bba48c14cc' },
+  'optima-skills':            { pipelineId: 5118534, repo: 'optima-skills',      saeAppId: '90457be3-5eb3-4efc-a362-1788dcc51921', prodSaeAppId: '55a63ee7-fb75-46e4-99f3-20854a699237' },
+  'user-auth':                { pipelineId: 5118510, repo: 'user-auth',          saeAppId: '36efc3a6-5b42-49fa-8db2-0865aa0c25d2', prodSaeAppId: 'd6fbf9de-fed6-4165-978f-7b3a0a456acc' },
+  'user-auth-admin':          { pipelineId: 5118535, repo: 'user-auth',          saeAppId: '7feb9cc3-4731-4ea8-964c-4870a9e63afb', prodSaeAppId: '54093f99-37bf-4354-abd7-f6e76abdbcb6' },
+  'yzsgo-api':                { pipelineId: 5118536, repo: 'yzsgo',              saeAppId: 'd0af7f66-ef66-4587-9e93-250d01ee3cf6', prodSaeAppId: '5a820992-e11b-404a-9e58-8f607d8e0c5f' },
+};
+
+function sh(cmd: string, args: string[]): string {
+  try {
+    return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (e: any) {
+    return '';
+  }
+}
+
+function devops(action: string, kv: Record<string, string>, retries = 3): any {
+  const args = ['devops', action, '--organizationId', ORG, '--endpoint', ENDPOINT, '--profile', PROFILE];
+  for (const [k, v] of Object.entries(kv)) args.push(`--${k}`, v);
+  for (let i = 0; i < retries; i++) {
+    const out = sh('aliyun', args);
+    try { return JSON.parse(out); } catch { /* aliyun 偶发空返回/超时,重试 */ }
+  }
+  return {};
+}
+
+const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--list') || argv.length === 0) {
+    console.log('可发服务(cn-stage):\n  ' + Object.keys(SERVICES).sort().join('\n  '));
+    console.log('\n用法: optima-cn-deploy <service> [--branch feat/xxx] [--no-wait]');
+    process.exit(argv.includes('--list') ? 0 : 1);
+  }
+  const svcName = argv[0];
+  const svc = SERVICES[svcName];
+  if (!svc) { console.error(`✗ 未知服务 ${svcName}(--list 看全量)`); process.exit(1); }
+  const bIdx = argv.indexOf('--branch');
+  const branch = bIdx >= 0 ? argv[bIdx + 1] : 'main';
+  const noWait = argv.includes('--no-wait');
+  const eIdx = argv.indexOf('--env');
+  const envName = eIdx >= 0 ? argv[eIdx + 1] : 'stage';
+  const vIdx = argv.indexOf('--vtag');
+  const vtag = vIdx >= 0 ? argv[vIdx + 1] : '';
+  if (!['stage', 'prod'].includes(envName)) { console.error('✗ --env 只支持 stage|prod'); process.exit(1); }
+  if (vtag && !/^cn-v\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(vtag)) {
+    console.error(`✗ vtag 格式必须 cn-vX.Y.Z(得到 ${vtag});裸 v* 会误触 AWS prod,绝不放行`); process.exit(1);
+  }
+  if (envName === 'prod') {
+    // prod = vtag 制:先 stage 同 tag 验证,再发 prod;流水线内还有人工卡点
+    if (!vtag) { console.error('✗ --env prod 必须带 --vtag cn-vX.Y.Z(先 stage 同 tag 验证)'); process.exit(1); }
+    if (branch !== 'main') { console.error('✗ prod 发布按 vtag,不接受 --branch'); process.exit(1); }
+  }
+  const ref = vtag || branch;
+
+  // 1. GitHub HEAD + mirror 同步
+  const ghSha = sh('gh', ['api', `repos/Optima-Chat/${svc.repo}/commits/${ref}`, '--jq', '.sha']);
+  if (!ghSha) { console.error(`✗ GitHub 上无 ${svc.repo}@${ref}(或 gh 未登录,tag 需已 push)`); process.exit(1); }
+  const repos = devops('ListRepositories', { perPage: '100' });
+  const repoId = (repos.result || []).find((r: any) => r.name === svc.repo)?.Id;
+  if (!repoId) { console.error(`✗ Codeup 无 mirror 仓 ${svc.repo}`); process.exit(1); }
+  const ghTok = sh('gh', ['auth', 'token']);
+  devops('TriggerRepositoryMirrorSync', { repositoryId: String(repoId), account: 'xbfool', token: ghTok });
+  let synced = false;
+  for (let i = 0; i < 30; i++) {
+    const b = devops('GetBranchInfo', { repositoryId: String(repoId), branchName: ref });
+    if (b?.result?.commit?.id === ghSha) { synced = true; break; }
+    await sleep(10000);
+  }
+  if (!synced) { console.error('✗ 300s 内 Codeup mirror 未追平 GitHub,中止(检查 mirror 凭证)'); process.exit(1); }
+  console.log(`✓ mirror 已追平 ${svc.repo}@${ref} = ${ghSha.slice(0, 10)}`);
+
+  // 2. 触发(凭证由云效变量组供给,无需注入)。prod 流水线 id 按名实时解析(不硬编码)。
+  let pipelineId = svc.pipelineId;
+  if (envName === 'prod') {
+    const lp = devops('ListPipelines', { maxResults: '100' });
+    const hit = (lp.pipelines || []).find((p: any) => p.pipelineName === `${svcName}-cn-prod`);
+    if (!hit) { console.error(`✗ 云效无 ${svcName}-cn-prod 流水线`); process.exit(1); }
+    pipelineId = hit.pipelineId;
+  }
+  const kv: Record<string, string> = { pipelineId: String(pipelineId) };
+  if (vtag) {
+    kv.params = JSON.stringify({
+      runningTags: { [`${CODEUP_BASE}/${svc.repo}.git`]: vtag },
+      envs: { VTAG: vtag },
+    });
+  } else if (branch !== 'main') {
+    kv.params = JSON.stringify({ runningBranchs: { [`${CODEUP_BASE}/${svc.repo}.git`]: branch } });
+  }
+  const start = devops('StartPipelineRun', kv);
+  const runId = start.pipelineRunId;
+  if (!runId) { console.error(`✗ 启动失败: ${JSON.stringify(start).slice(0, 150)}`); process.exit(1); }
+  console.log(`▶ ${svcName} run#${runId} 已启动 (ref=${ref}, env=${envName})`);
+  console.log(`  https://flow.aliyun.com/pipelines/${pipelineId}/current`);
+  if (envName === 'prod') {
+    console.log('⏸ 构建完成后会停在『发布审批』人工卡点 —— 需 xbfool/svenyang 在云效控制台通过,之后迁移+digest 部署自动走完');
+  }
+  if (noWait) return;
+
+  // 3. 轮询
+  let status = '';
+  for (;;) {
+    const d = devops('GetPipelineRun', { pipelineId: String(pipelineId), pipelineRunId: String(runId) });
+    status = d?.pipelineRun?.status || status;
+    if (['SUCCESS', 'FAIL', 'CANCELED', 'ERROR'].includes(status)) break;
+    await sleep(45000);
+  }
+  console.log(`${status === 'SUCCESS' ? '✅' : '❌'} ${svcName} run#${runId}: ${status}`);
+  if (status !== 'SUCCESS') process.exit(1);
+
+  // 4. SAE ImageUrl 校验(空返回重试守卫)。prod 是 digest 寻址,校验含 @sha256 即部署成功。
+  const appId = envName === 'prod' ? svc.prodSaeAppId : svc.saeAppId;
+  if (appId) {
+    let img = '';
+    for (let i = 0; i < 3; i++) {
+      const raw = sh('aliyun', ['sae', '--profile', PROFILE, '--region', 'cn-beijing',
+        'DescribeApplicationConfig', '--AppId', appId]);
+      try { img = JSON.parse(raw)?.Data?.ImageUrl || ''; break; } catch { await sleep(3000); }
+    }
+    if (!img) { console.log('⚠️ SAE 配置查询连续空返回,跳过 ImageUrl 校验(流水线本身已 SUCCESS)'); return; }
+    if (envName === 'prod') {
+      const ok = img.includes('@sha256:');
+      console.log(`${ok ? '✓' : '✗'} SAE ImageUrl(prod 应为 digest 寻址): ${img.split('/').pop()}`);
+      if (!ok) process.exit(1);
+    } else {
+      const tag = img.split(':').pop() || '';
+      const ok = ghSha.startsWith(tag);
+      console.log(`${ok ? '✓' : '✗'} SAE ImageUrl tag=${tag} vs 目标 ${ghSha.slice(0, 10)}`);
+      if (!ok) process.exit(1);
+    }
+  }
+}
+
+main().catch(e => { console.error('✗', e?.message || e); process.exit(1); });

package/dist/bin/helpers/cn-deploy.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * optima-cn-deploy —— 云效 Flow cn-stage 流水线一条龙触发器(团队版)。
+ *
+ * 对应 optima-terraform alicloud/stacks/cn-prod-buildbox/yunxiao/ 的 cn-run.py,
+ * 去掉 buildbox SSH 依赖(凭证由云效变量组 41970 供给,2026-07-13 起控制台/API 裸跑均可)。
+ *
+ * 做四件事(每件都是踩过的坑):
+ *   1. 触发服务仓 Codeup mirror 同步并等目标分支追平 GitHub —— mirror 不新鲜=构建旧代码。
+ *      GitHub token 用 `gh auth token`(需本机 gh 已登录)。
+ *   2. StartPipelineRun;--branch 时带 runningBranchs 覆盖服务仓 source 分支。
+ *   3. 轮询到终态,给出云效 run 链接。
+ *   4. SUCCESS 后校验 SAE ImageUrl tag == 目标分支 HEAD short-sha(防"流水线绿但没部上");
+ *      aliyun API 偶发空返回,带重试守卫。
+ *
+ * 用法:
+ *   optima-cn-deploy billing                      # main 全链(构建→迁移→SAE 发布)
+ *   optima-cn-deploy user-auth --branch feat/xxx  # 非 main 分支构建+部署到 cn-stage
+ *   optima-cn-deploy gateway-core --no-wait       # 只触发不等待
+ *   optima-cn-deploy --list                       # 列出全部可发服务
+ *   optima-cn-deploy billing --vtag cn-v1.2.3     # stage 按版本 tag 构建(发版前验证)
+ *   optima-cn-deploy billing --env prod --vtag cn-v1.2.3
+ *       # cn-prod vtag 发版:构建→停在人工卡点(云效控制台审批)→迁移→digest 钉死部署
+ *
+ * 前置: aliyun CLI(profile 默认 aliyun-optima,可用 OPTIMA_ALIYUN_PROFILE 覆盖)+ gh 已登录。
+ * 流水线定义的单一信源在 optima-terraform yunxiao/(gen-pipelines.py);本表为其快照,
+ * 新增服务后同步(pipelineId 稳定,不常变)。
+ */
+const node_child_process_1 = require("node:child_process");
+const ORG = '6a17b6282bf8b1184fc0e0c6';
+const ENDPOINT = 'devops.cn-hangzhou.aliyuncs.com';
+const PROFILE = process.env.OPTIMA_ALIYUN_PROFILE || 'aliyun-optima';
+const CODEUP_BASE = `https://codeup.aliyun.com/${ORG}`;
+const SERVICES = {
+    'agent-portal': { pipelineId: 5118519, repo: 'optima-portals', saeAppId: 'fe757f78-d18d-4480-9402-fe59d4721055', prodSaeAppId: '9211db38-a255-4393-ae92-7a7bb41b583d' },
+    'agentic-chat': { pipelineId: 5118520, repo: 'agentic-chat', saeAppId: '6aea1ce1-f813-4e1c-8e97-d1ecb5398e37', prodSaeAppId: '6e290c73-a646-43ef-9da5-ad0b2e7eff73' },
+    'billing': { pipelineId: 5118521, repo: 'optima-billing', saeAppId: '09d8e292-dc64-4af8-bce5-0a56cb666921', prodSaeAppId: '6c31cf82-8802-4d45-b6a2-e9d7c83ccce9' },
+    'browser-backend': { pipelineId: 5118522, repo: 'optima-browser-use', saeAppId: '1fced3f6-a80a-41a4-8f23-e4d5a467f8eb', prodSaeAppId: 'eb782ed9-c468-4e81-a0fe-87e5b4264192' },
+    'commerce-backend': { pipelineId: 5107005, repo: 'commerce-backend', saeAppId: '49d09808-508c-471a-9560-553c49a67f72', prodSaeAppId: 'd40597b6-a98c-4063-9297-8b9fdfa8add4' },
+    'commerce-rq-scheduler': { pipelineId: 5118523, repo: 'commerce-backend', saeAppId: '1d2810ef-889e-4675-b6e6-a299e4722e68', prodSaeAppId: '762dd7a5-7fe8-41ed-9332-cfd31b0e087e' },
+    'commerce-rq-worker': { pipelineId: 5118524, repo: 'commerce-backend', saeAppId: 'd661da87-6d24-40b8-93ed-e1c967d8abe2', prodSaeAppId: '2c9ee19a-5062-4205-9f5b-6ae3f8062a23' },
+    'gateway-core': { pipelineId: 5118525, repo: 'optima-gateway', saeAppId: '9326b7ff-da52-48d6-86db-9c4a884be108', prodSaeAppId: 'a08ce23f-3d3e-4d89-a2cf-53c8adba614e' },
+    'gw-admin': { pipelineId: 5118526, repo: 'optima-gateway', saeAppId: '90e0daf7-7910-46b8-b5bf-a0b8bcc60859', prodSaeAppId: 'c6bc5a78-b27f-46e2-825a-eaa338c23645' },
+    'kb-backend': { pipelineId: 5118527, repo: 'kb-skills', saeAppId: 'c7f65160-9d9e-416e-9e36-5439010d2b2d', prodSaeAppId: '732dfc8c-ed78-43f7-a722-c614359ff1a1' },
+    'ops-portal': { pipelineId: 5118529, repo: 'optima-portals', saeAppId: '41d0ee66-8402-4e72-bfda-8eba75d1270c', prodSaeAppId: '69e513fd-29bf-4355-a275-5eba82b21136' },
+    'optima-generation': { pipelineId: 5118530, repo: 'optima-gen', saeAppId: '327856d5-8b18-4e15-bfd8-b8bd3b807ffa', prodSaeAppId: '868d1a69-12c9-4bb7-868b-3e89c26784b5' },
+    'optima-generation-worker': { pipelineId: 5118531, repo: 'optima-gen', saeAppId: 'ad75b3b0-9ff4-443d-b0ef-81886bc7aa60', prodSaeAppId: '2adc941e-374b-406a-9863-e53d40bc9500' },
+    'optima-scout': { pipelineId: 5117336, repo: 'optima-scout', saeAppId: 'bac2c3a4-90ce-49a6-81d5-caa38cb5c807', prodSaeAppId: 'f5bb7e82-e57c-4bd4-83ae-2c25f8d38647' },
+    'optima-sentinel': { pipelineId: 5118532, repo: 'optima-sentinel', saeAppId: '3759db7b-4640-4a04-8436-4f241f0ec9d9', prodSaeAppId: 'e120e70c-b2c1-49ef-a66c-9016fd2d807d' },
+    'optima-sentinel-worker': { pipelineId: 5118533, repo: 'optima-sentinel', saeAppId: '7c975caf-ebfb-4bb3-91c4-2a8c83d1d2e5', prodSaeAppId: 'e0f9b92c-00af-4ade-9b07-15bba48c14cc' },
+    'optima-skills': { pipelineId: 5118534, repo: 'optima-skills', saeAppId: '90457be3-5eb3-4efc-a362-1788dcc51921', prodSaeAppId: '55a63ee7-fb75-46e4-99f3-20854a699237' },
+    'user-auth': { pipelineId: 5118510, repo: 'user-auth', saeAppId: '36efc3a6-5b42-49fa-8db2-0865aa0c25d2', prodSaeAppId: 'd6fbf9de-fed6-4165-978f-7b3a0a456acc' },
+    'user-auth-admin': { pipelineId: 5118535, repo: 'user-auth', saeAppId: '7feb9cc3-4731-4ea8-964c-4870a9e63afb', prodSaeAppId: '54093f99-37bf-4354-abd7-f6e76abdbcb6' },
+    'yzsgo-api': { pipelineId: 5118536, repo: 'yzsgo', saeAppId: 'd0af7f66-ef66-4587-9e93-250d01ee3cf6', prodSaeAppId: '5a820992-e11b-404a-9e58-8f607d8e0c5f' },
+};
+function sh(cmd, args) {
+    try {
+        return (0, node_child_process_1.execFileSync)(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    }
+    catch (e) {
+        return '';
+    }
+}
+function devops(action, kv, retries = 3) {
+    const args = ['devops', action, '--organizationId', ORG, '--endpoint', ENDPOINT, '--profile', PROFILE];
+    for (const [k, v] of Object.entries(kv))
+        args.push(`--${k}`, v);
+    for (let i = 0; i < retries; i++) {
+        const out = sh('aliyun', args);
+        try {
+            return JSON.parse(out);
+        }
+        catch { /* aliyun 偶发空返回/超时,重试 */ }
+    }
+    return {};
+}
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--list') || argv.length === 0) {
+        console.log('可发服务(cn-stage):\n  ' + Object.keys(SERVICES).sort().join('\n  '));
+        console.log('\n用法: optima-cn-deploy <service> [--branch feat/xxx] [--no-wait]');
+        process.exit(argv.includes('--list') ? 0 : 1);
+    }
+    const svcName = argv[0];
+    const svc = SERVICES[svcName];
+    if (!svc) {
+        console.error(`✗ 未知服务 ${svcName}(--list 看全量)`);
+        process.exit(1);
+    }
+    const bIdx = argv.indexOf('--branch');
+    const branch = bIdx >= 0 ? argv[bIdx + 1] : 'main';
+    const noWait = argv.includes('--no-wait');
+    const eIdx = argv.indexOf('--env');
+    const envName = eIdx >= 0 ? argv[eIdx + 1] : 'stage';
+    const vIdx = argv.indexOf('--vtag');
+    const vtag = vIdx >= 0 ? argv[vIdx + 1] : '';
+    if (!['stage', 'prod'].includes(envName)) {
+        console.error('✗ --env 只支持 stage|prod');
+        process.exit(1);
+    }
+    if (vtag && !/^cn-v\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(vtag)) {
+        console.error(`✗ vtag 格式必须 cn-vX.Y.Z(得到 ${vtag});裸 v* 会误触 AWS prod,绝不放行`);
+        process.exit(1);
+    }
+    if (envName === 'prod') {
+        // prod = vtag 制:先 stage 同 tag 验证,再发 prod;流水线内还有人工卡点
+        if (!vtag) {
+            console.error('✗ --env prod 必须带 --vtag cn-vX.Y.Z(先 stage 同 tag 验证)');
+            process.exit(1);
+        }
+        if (branch !== 'main') {
+            console.error('✗ prod 发布按 vtag,不接受 --branch');
+            process.exit(1);
+        }
+    }
+    const ref = vtag || branch;
+    // 1. GitHub HEAD + mirror 同步
+    const ghSha = sh('gh', ['api', `repos/Optima-Chat/${svc.repo}/commits/${ref}`, '--jq', '.sha']);
+    if (!ghSha) {
+        console.error(`✗ GitHub 上无 ${svc.repo}@${ref}(或 gh 未登录,tag 需已 push)`);
+        process.exit(1);
+    }
+    const repos = devops('ListRepositories', { perPage: '100' });
+    const repoId = (repos.result || []).find((r) => r.name === svc.repo)?.Id;
+    if (!repoId) {
+        console.error(`✗ Codeup 无 mirror 仓 ${svc.repo}`);
+        process.exit(1);
+    }
+    const ghTok = sh('gh', ['auth', 'token']);
+    devops('TriggerRepositoryMirrorSync', { repositoryId: String(repoId), account: 'xbfool', token: ghTok });
+    let synced = false;
+    for (let i = 0; i < 30; i++) {
+        const b = devops('GetBranchInfo', { repositoryId: String(repoId), branchName: ref });
+        if (b?.result?.commit?.id === ghSha) {
+            synced = true;
+            break;
+        }
+        await sleep(10000);
+    }
+    if (!synced) {
+        console.error('✗ 300s 内 Codeup mirror 未追平 GitHub,中止(检查 mirror 凭证)');
+        process.exit(1);
+    }
+    console.log(`✓ mirror 已追平 ${svc.repo}@${ref} = ${ghSha.slice(0, 10)}`);
+    // 2. 触发(凭证由云效变量组供给,无需注入)。prod 流水线 id 按名实时解析(不硬编码)。
+    let pipelineId = svc.pipelineId;
+    if (envName === 'prod') {
+        const lp = devops('ListPipelines', { maxResults: '100' });
+        const hit = (lp.pipelines || []).find((p) => p.pipelineName === `${svcName}-cn-prod`);
+        if (!hit) {
+            console.error(`✗ 云效无 ${svcName}-cn-prod 流水线`);
+            process.exit(1);
+        }
+        pipelineId = hit.pipelineId;
+    }
+    const kv = { pipelineId: String(pipelineId) };
+    if (vtag) {
+        kv.params = JSON.stringify({
+            runningTags: { [`${CODEUP_BASE}/${svc.repo}.git`]: vtag },
+            envs: { VTAG: vtag },
+        });
+    }
+    else if (branch !== 'main') {
+        kv.params = JSON.stringify({ runningBranchs: { [`${CODEUP_BASE}/${svc.repo}.git`]: branch } });
+    }
+    const start = devops('StartPipelineRun', kv);
+    const runId = start.pipelineRunId;
+    if (!runId) {
+        console.error(`✗ 启动失败: ${JSON.stringify(start).slice(0, 150)}`);
+        process.exit(1);
+    }
+    console.log(`▶ ${svcName} run#${runId} 已启动 (ref=${ref}, env=${envName})`);
+    console.log(`  https://flow.aliyun.com/pipelines/${pipelineId}/current`);
+    if (envName === 'prod') {
+        console.log('⏸ 构建完成后会停在『发布审批』人工卡点 —— 需 xbfool/svenyang 在云效控制台通过,之后迁移+digest 部署自动走完');
+    }
+    if (noWait)
+        return;
+    // 3. 轮询
+    let status = '';
+    for (;;) {
+        const d = devops('GetPipelineRun', { pipelineId: String(pipelineId), pipelineRunId: String(runId) });
+        status = d?.pipelineRun?.status || status;
+        if (['SUCCESS', 'FAIL', 'CANCELED', 'ERROR'].includes(status))
+            break;
+        await sleep(45000);
+    }
+    console.log(`${status === 'SUCCESS' ? '✅' : '❌'} ${svcName} run#${runId}: ${status}`);
+    if (status !== 'SUCCESS')
+        process.exit(1);
+    // 4. SAE ImageUrl 校验(空返回重试守卫)。prod 是 digest 寻址,校验含 @sha256 即部署成功。
+    const appId = envName === 'prod' ? svc.prodSaeAppId : svc.saeAppId;
+    if (appId) {
+        let img = '';
+        for (let i = 0; i < 3; i++) {
+            const raw = sh('aliyun', ['sae', '--profile', PROFILE, '--region', 'cn-beijing',
+                'DescribeApplicationConfig', '--AppId', appId]);
+            try {
+                img = JSON.parse(raw)?.Data?.ImageUrl || '';
+                break;
+            }
+            catch {
+                await sleep(3000);
+            }
+        }
+        if (!img) {
+            console.log('⚠️ SAE 配置查询连续空返回,跳过 ImageUrl 校验(流水线本身已 SUCCESS)');
+            return;
+        }
+        if (envName === 'prod') {
+            const ok = img.includes('@sha256:');
+            console.log(`${ok ? '✓' : '✗'} SAE ImageUrl(prod 应为 digest 寻址): ${img.split('/').pop()}`);
+            if (!ok)
+                process.exit(1);
+        }
+        else {
+            const tag = img.split(':').pop() || '';
+            const ok = ghSha.startsWith(tag);
+            console.log(`${ok ? '✓' : '✗'} SAE ImageUrl tag=${tag} vs 目标 ${ghSha.slice(0, 10)}`);
+            if (!ok)
+                process.exit(1);
+        }
+    }
+}
+main().catch(e => { console.error('✗', e?.message || e); process.exit(1); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {
@@ -17,7 +17,8 @@
     "optima-product": "dist/bin/helpers/product.js",
     "optima-query-db": "dist/bin/helpers/query-db.js",
     "optima-show-env": "dist/bin/helpers/show-env.js",
-    "optima-verify-health": "dist/bin/helpers/verify-health.js"
+    "optima-verify-health": "dist/bin/helpers/verify-health.js",
+    "optima-cn-deploy": "dist/bin/helpers/cn-deploy.js"
   },
   "scripts": {
     "postinstall": "node scripts/install.js",
@@ -62,4 +63,4 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   }
-}
+}