@optima-chat/dev-skills 0.14.0 → 0.16.0

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

@@ -1,6 +1,6 @@
 ---
 name: cn-deploy
-description: 当用户请求把服务发布/部署/构建到 cn-stage、跑云效流水线、cn-stage 发版、部署某个分支到 cn-stage、触发 cn 构建、yunxiao 部署、"把 xx 发到 cn"时，使用此技能。覆盖 cn-stage 全部 20 个服务（构建→DB迁移→SAE 发布一条龙）。
+description: 当用户请求把服务发布/部署/构建到 cn-stage、跑云效流水线、cn-stage 发版、部署某个分支到 cn-stage、触发 cn 构建、yunxiao 部署、"把 xx 发到 cn"时，使用此技能。覆盖 cn-stage 全部 21 个服务（构建→DB迁移→SAE 发布一条龙；含 build-only 的 agent-runtime）。
 ---
 
 # cn-deploy - 云效 cn-stage 流水线发布
@@ -21,12 +21,13 @@ optima-cn-deploy --list                       # 列出全部可发服务
 
 ## 使用要点
 
-1. **先 `--list` 确认服务名**（20 个服务，含 commerce-backend / optima-scout）。
+1. **先 `--list` 确认服务名**（21 个服务，含 commerce-backend / optima-scout / build-only 的 agent-runtime）。
 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。只看流水线绿不算完成。
+7. **build-only 服务（`agent-runtime`）**：非 SAE 常驻（gateway-core 按 session 拉起的镜像）。成功标准不是 SAE ImageUrl，而是流水线绿即可——release 段自动把 ACR digest 回写 Infisical `/services/gateway-core/ALIYUN_AGENT_RUNTIME_IMAGE`(#807) 并滚动重启 gateway-core（任一步失败即 exit 非 0）。工具最后一行为 `✓ 流水线 SUCCESS(build-only)…` —— CLI 以流水线终态为准，未独立校验 Infisical/gateway-core（digest 与重启变更单见 run『发版』段日志）。
 
 
 ## cn-prod vtag 发版（⚠️ 待 svenyang 首次验证通过后再日常使用）

package/.claude/skills/gateway-admin/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: gateway-admin
+description: 当用户请求操作 gateway 管理面时使用——COO kill/软杀某用户的协调官、查看或调整 warm-pool、credits adjust、provider key 管理、gateway config/llm-rates/models 的读写，或任何 gateway-core /admin/* 端点调用。支持 cn-stage、cn-prod 两个环境。
+---
+
+# Gateway Admin — gateway-core /admin/* 操作
+
+当用户要求「杀掉某用户的 COO / 软杀容器 / drain warm pool / 查 gateway 配置 / 调 llm 费率 / 管理 provider key」等 gateway 管理面操作时，使用 `optima-gateway-admin` CLI。
+
+## 用法
+
+```bash
+optima-gateway-admin <METHOD> </admin/...> [jsonBody] [--env cn-stage|cn-prod] [--yes]
+```
+
+- 默认环境 `cn-stage`；`cn-prod` 是生产，谨慎。
+- GET/HEAD 直通；**POST/PUT/PATCH/DELETE 会回显完整请求并要求输入 yes 确认**（所有环境，不只 prod）。脚本化传 `--yes`。
+- path 必须以 `/admin/` 开头（硬约束，防 token 误用于其它面）。
+- 凭证自动走 dev-skills OAuth client（client_credentials，scope=gateway:admin，#70 方向 1）；cn-stage 需要 `INFISICAL_CN_EMAIL/PASSWORD` 环境变量（与 query-db cn 同一前提）。
+
+## 常用例子
+
+```bash
+# 查 llm 费率表
+optima-gateway-admin GET /admin/llm-rates --env cn-stage
+
+# 软杀某用户的 COO（#1681 止血这类场景——不再手写 DB UPDATE）
+optima-gateway-admin POST /admin/coo/users/<userId>/kill --env cn-stage
+
+# 改 gateway 动态配置
+optima-gateway-admin PUT /admin/config/<KEY> '{"value":"..."}' --env cn-stage
+```
+
+## 注意
+
+- 403 且提示 scope 为空 → 该环境 dev-skills client 的 `allowed_scopes` 缺 `gateway:admin`（见 optima-dev-skills#70）。
+- 写操作打的是运行中的 gateway 管理面，stage 上也可能打断在跑会话——确认提示不要盲敲 yes。
+- AWS stage 未接（AWS prod gateway 已关停）；需要时见 #70。

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

@@ -1,6 +1,6 @@
 ---
 name: cn-deploy
-description: 当用户请求把服务发布/部署/构建到 cn-stage、跑云效流水线、cn-stage 发版、部署某个分支到 cn-stage、触发 cn 构建、yunxiao 部署、"把 xx 发到 cn"时，使用此技能。覆盖 cn-stage 全部 20 个服务（构建→DB迁移→SAE 发布一条龙）。
+description: 当用户请求把服务发布/部署/构建到 cn-stage、跑云效流水线、cn-stage 发版、部署某个分支到 cn-stage、触发 cn 构建、yunxiao 部署、"把 xx 发到 cn"时，使用此技能。覆盖 cn-stage 全部 21 个服务（构建→DB迁移→SAE 发布一条龙；含 build-only 的 agent-runtime）。
 ---
 
 # cn-deploy - 云效 cn-stage 流水线发布
@@ -21,12 +21,13 @@ optima-cn-deploy --list                       # 列出全部可发服务
 
 ## 使用要点
 
-1. **先 `--list` 确认服务名**（20 个服务，含 commerce-backend / optima-scout）。
+1. **先 `--list` 确认服务名**（21 个服务，含 commerce-backend / optima-scout / build-only 的 agent-runtime）。
 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。只看流水线绿不算完成。
+7. **build-only 服务（`agent-runtime`）**：非 SAE 常驻（gateway-core 按 session 拉起的镜像）。成功标准不是 SAE ImageUrl，而是流水线绿即可——release 段自动把 ACR digest 回写 Infisical `/services/gateway-core/ALIYUN_AGENT_RUNTIME_IMAGE`(#807) 并滚动重启 gateway-core（任一步失败即 exit 非 0）。工具最后一行为 `✓ 流水线 SUCCESS(build-only)…` —— CLI 以流水线终态为准，未独立校验 Infisical/gateway-core（digest 与重启变更单见 run『发版』段日志）。
 
 
 ## cn-prod vtag 发版（⚠️ 待 svenyang 首次验证通过后再日常使用）

package/bin/cli.js

@@ -37,6 +37,7 @@ switch (command) {
     log('  optima-grant-credits <email|phone|userId> --credits <n> [--env] Grant credits (bonus, 30d)', 'cyan');
     log('  optima-grant-subscription <email|phone|userId> --plan <p> [--env] Grant subscription', 'cyan');
     log('  optima-logs <service> [--env] [--since] [--grep] [-n]  View logs (cn=SLS 直连/aws=CloudWatch)', 'cyan');
+    log('  optima-gateway-admin <METHOD> </admin/path> [body] [--env cn-stage|cn-prod]  Gateway /admin/* passthrough (#70)', 'cyan');
     log('  /restart-ecs <service> [env]                         Restart ECS service (skill)', 'cyan');
 
     log('\nSupported Services:', 'yellow');

package/bin/helpers/billing-http.ts

@@ -107,8 +107,13 @@ function getSkillsUrl(env: string): string {
   return url;
 }
 
-export function getServiceToken(env: string): string {
-  if (tokenCache[env]) return tokenCache[env];
+export function getServiceToken(env: string, scope?: string): string {
+  // Cache key includes scope: the same env can mint tokens with different
+  // scopes (default internal:users:write vs gateway:admin for gateway-admin,
+  // #70) and user-auth issues request∩allowed_scopes — mixing them up would
+  // hand a wrongly-scoped token to the caller.
+  const cacheKey = scope ? `${env}:${scope}` : env;
+  if (tokenCache[cacheKey]) return tokenCache[cacheKey];
 
   // cn-prod 与 cn-stage 都用 client_credentials M2M token，scope=internal:users:write。
   // 凭证来源不同：
@@ -141,7 +146,8 @@ export function getServiceToken(env: string): string {
   const authUrl = USER_AUTH_URLS[env];
   if (!authUrl) throw new Error(`Unknown env: ${env}`);
 
-  const scopeParam = isCn ? `&scope=${encodeURIComponent(CN_PROD_TOKEN_SCOPE)}` : '';
+  const effectiveScope = scope ?? (isCn ? CN_PROD_TOKEN_SCOPE : undefined);
+  const scopeParam = effectiveScope ? `&scope=${encodeURIComponent(effectiveScope)}` : '';
   const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}${scopeParam}`;
   const response = execSync(
     `curl -s -X POST '${authUrl}/api/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' -d '${body}'`,
@@ -157,7 +163,7 @@ export function getServiceToken(env: string): string {
   if (!parsed.access_token) {
     throw new Error(`user-auth token mint failed (${env}): ${response.slice(0, 200)}`);
   }
-  tokenCache[env] = parsed.access_token;
+  tokenCache[cacheKey] = parsed.access_token;
   return parsed.access_token;
 }
 

package/bin/helpers/cn-deploy.ts

@@ -34,9 +34,13 @@ 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; }
+interface Svc { pipelineId: number; repo: string; saeAppId?: string; prodSaeAppId?: string; buildOnly?: boolean; }
 const SERVICES: Record<string, Svc> = {
   'agent-portal':             { pipelineId: 5118519, repo: 'optima-portals',     saeAppId: 'fe757f78-d18d-4480-9402-fe59d4721055', prodSaeAppId: '9211db38-a255-4393-ae92-7a7bb41b583d' },
+  // build-only:非 SAE 常驻(gateway-core 按 session 拉起的镜像)。release 段=解析 ACR digest
+  // → 回写 Infisical /services/gateway-core/ALIYUN_AGENT_RUNTIME_IMAGE(#807)→ 滚动重启 gateway-core。
+  // 无自身 saeAppId;prod 流水线(agent-runtime-cn-prod,5124970)按名实时解析(见下方 ListPipelines 逻辑)。
+  'agent-runtime':            { pipelineId: 5124962, repo: 'optima-gateway',     buildOnly: true },
   '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' },
@@ -116,7 +120,10 @@ async function main() {
   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 });
+    // vtag 发版时 ref 是 tag,不是 branch —— GetBranchInfo 查不到 tag 会恒超时,改用 tag 接口。
+    const b = vtag
+      ? devops('GetRepositoryTag', { repositoryId: String(repoId), tagName: ref })
+      : devops('GetBranchInfo', { repositoryId: String(repoId), branchName: ref });
     if (b?.result?.commit?.id === ghSha) { synced = true; break; }
     await sleep(10000);
   }
@@ -161,7 +168,17 @@ async function main() {
   console.log(`${status === 'SUCCESS' ? '✅' : '❌'} ${svcName} run#${runId}: ${status}`);
   if (status !== 'SUCCESS') process.exit(1);
 
-  // 4. SAE ImageUrl 校验(空返回重试守卫)。prod 是 digest 寻址,校验含 @sha256 即部署成功。
+  // 4. 成功标准。build-only(agent-runtime)无自身 SAE app 可查:digest 回写 Infisical +
+  //    滚动重启 gateway-core 都在流水线 release 段内完成(任一步失败即 exit 非 0)。CLI 不碰
+  //    Infisical 凭证,只以流水线终态为准、不独立校验回写是否真落地——故措辞用「应已」而非「已」;
+  //    真实 digest / 重启变更单在 run『发版』段日志里(见上方链接)。
+  if (svc.buildOnly) {
+    const infEnv = envName === 'prod' ? 'prod' : 'staging';
+    console.log(`✓ 流水线 SUCCESS(build-only)。release 段应已回写 ${infEnv} Infisical ALIYUN_AGENT_RUNTIME_IMAGE(@sha256 digest)并滚动重启 gateway-core;CLI 未独立校验,digest 见上方 run『发版』段日志`);
+    return;
+  }
+
+  // SAE ImageUrl 校验(空返回重试守卫)。prod 是 digest 寻址,校验含 @sha256 即部署成功。
   const appId = envName === 'prod' ? svc.prodSaeAppId : svc.saeAppId;
   if (appId) {
     let img = '';

package/bin/helpers/gateway-admin.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+// optima-gateway-admin — 通用透传型 gateway-core /admin/* 操作 CLI（#70）。
+//
+// 定位：dev-skills 现有 admin 技能（account/grant-credits/entitlement）打的都是
+// user-auth 与 billing；gateway 自身的 /admin/*（COO kill、warm-pool drain、
+// credits adjust、provider key CRUD、config CRUD、llm-rates、models 等）此前只能
+// 手写 curl + 手拼 token（#1681 止血即被迫手写 DB UPDATE + aliyun CLI）。本命令
+// 把「铸 gateway:admin token → 调端点 → 展示结果」收敛成一条命令。
+//
+// 凭证（#70 方向 1）：复用 dev-skills 各环境既有 OAuth client（client_credentials），
+// 其 allowed_scopes 已加 gateway:admin（cn-stage/cn-prod 2026-07-23 提权）；
+// token 铸造显式带 scope=gateway:admin（user-auth 发 request∩allowed_scopes，
+// 不显式带则 scope 为空 → gateway 403，见 #70 技术现状）。
+//
+// 安全门：GET/HEAD 直通；写方法（POST/PUT/PATCH/DELETE）一律回显完整
+// method+URL+body 后要求交互确认（所有环境，非仅 prod——admin 面写操作在
+// stage 也可能打断在跑会话），--yes 跳过（脚本化用）。
+//
+// v1 支持 cn-stage / cn-prod（AWS prod gateway 已关停 2026-06-26；AWS stage
+// 需要时再接 domain-urls，见 #70 讨论）。
+
+import * as readline from 'readline';
+import { getServiceToken } from './billing-http';
+
+const GATEWAY_ADMIN_SCOPE = 'gateway:admin';
+
+// 与 verify-health.ts 的 gateway-core 域名同源（cn 域名稳定、硬编码，与
+// billing-http 的 cn URL 处理同一 rationale）。
+const GATEWAY_URLS: Record<string, string> = {
+  'cn-prod': 'https://gw.yzsgo.com',
+  'cn-stage': 'https://gw.stage.optima.chat',
+};
+
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+interface Parsed {
+  method: string;
+  path: string;
+  body: string | null;
+  env: string;
+  yes: boolean;
+}
+
+function usage(): never {
+  console.log(`Usage: optima-gateway-admin <METHOD> <path> [jsonBody] [options]
+
+Call a gateway-core /admin/* endpoint with a gateway:admin service token (#70).
+
+Arguments:
+  METHOD                GET | POST | PUT | PATCH | DELETE
+  path                  Endpoint path, must start with /admin/
+  jsonBody              JSON request body (write methods only)
+
+Options:
+  --env <env>           cn-stage (default) | cn-prod
+  --yes                 Skip the write-confirmation prompt (scripting)
+  -h, --help            Show this help
+
+Safety:
+  GET/HEAD run directly. POST/PUT/PATCH/DELETE echo the full request and
+  require typing "yes" — on EVERY env, not just prod (admin writes can
+  disrupt live sessions on stage too). Use --yes to skip.
+
+Examples:
+  optima-gateway-admin GET /admin/llm-rates --env cn-stage
+  optima-gateway-admin GET /admin/coo/instances --env cn-prod
+  optima-gateway-admin POST /admin/coo/users/<userId>/kill --env cn-stage
+  optima-gateway-admin PUT /admin/config/SOME_KEY '{"value":"x"}' --env cn-stage`);
+  process.exit(0);
+}
+
+function parseArgs(args: string[]): Parsed {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') usage();
+
+  let env = 'cn-stage';
+  let yes = false;
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--env' || a === '-e') {
+      env = args[++i] ?? '';
+    } else if (a.startsWith('--env=')) {
+      env = a.slice('--env='.length);
+    } else if (a === '--yes' || a === '-y') {
+      yes = true;
+    } else if (a.startsWith('--')) {
+      console.error(`❌ Unknown flag: ${a}`);
+      process.exit(1);
+    } else {
+      positional.push(a);
+    }
+  }
+
+  if (!GATEWAY_URLS[env]) {
+    console.error(`❌ --env must be "cn-stage" or "cn-prod" (got: ${env}). AWS stage 未接（prod gateway 已关停），需要时见 #70。`);
+    process.exit(1);
+  }
+
+  const method = (positional[0] ?? '').toUpperCase();
+  if (!['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+    console.error(`❌ METHOD must be GET/HEAD/POST/PUT/PATCH/DELETE (got: ${positional[0] ?? '(missing)'})`);
+    process.exit(1);
+  }
+
+  const path = positional[1] ?? '';
+  // 硬约束 /admin/ 前缀：本命令的 token 只该用于 admin 面；防拼错路径把
+  // gateway:admin token 打到任意端点（最小暴露面）。
+  if (!path.startsWith('/admin/')) {
+    console.error(`❌ path must start with /admin/ (got: ${path || '(missing)'})`);
+    process.exit(1);
+  }
+
+  let body: string | null = null;
+  if (positional[2] !== undefined) {
+    if (!WRITE_METHODS.has(method)) {
+      console.error(`❌ ${method} does not take a body`);
+      process.exit(1);
+    }
+    try {
+      JSON.parse(positional[2]);
+    } catch {
+      console.error(`❌ jsonBody is not valid JSON: ${positional[2].slice(0, 120)}`);
+      process.exit(1);
+    }
+    body = positional[2];
+  }
+
+  return { method, path, body, env, yes };
+}
+
+async function confirmWrite(p: Parsed, url: string): Promise<void> {
+  if (!WRITE_METHODS.has(p.method) || p.yes) return;
+  const prodMark = p.env === 'cn-prod' ? '  🔴 PRODUCTION' : '';
+  console.log(`\n⚠️  About to ${p.method} on ${p.env.toUpperCase()}${prodMark}:\n  ${p.method} ${url}${p.body ? `\n  body: ${p.body}` : ''}\n`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise<string>((resolve) => {
+    rl.question('Type "yes" to confirm: ', (a) => { rl.close(); resolve(a.trim()); });
+  });
+  if (answer !== 'yes') {
+    console.error('❌ Aborted by user.');
+    process.exit(1);
+  }
+}
+
+async function main(): Promise<void> {
+  const p = parseArgs(process.argv.slice(2));
+  const url = `${GATEWAY_URLS[p.env]}${p.path}`;
+
+  await confirmWrite(p, url);
+
+  const token = getServiceToken(p.env, GATEWAY_ADMIN_SCOPE);
+
+  const res = await fetch(url, {
+    method: p.method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(p.body ? { 'Content-Type': 'application/json' } : {}),
+    },
+    ...(p.body ? { body: p.body } : {}),
+  });
+
+  const text = await res.text();
+  const statusLine = `${res.status} ${res.statusText}`;
+  if (!res.ok) {
+    console.error(`❌ [${statusLine}] ${p.method} ${p.path} (${p.env})`);
+    if (res.status === 403) {
+      console.error('   403 提示：token scope 可能为空——确认该环境 dev-skills client 的 allowed_scopes 已含 gateway:admin（#70）。');
+    }
+  } else {
+    console.log(`✓ [${statusLine}] ${p.method} ${p.path} (${p.env})`);
+  }
+  if (text) {
+    try {
+      console.log(JSON.stringify(JSON.parse(text), null, 2));
+    } catch {
+      console.log(text.slice(0, 4000));
+    }
+  }
+  process.exit(res.ok ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error(`\n❌ Error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/dist/bin/helpers/billing-http.js

@@ -114,9 +114,14 @@ function getSkillsUrl(env) {
     skillsUrlCache[env] = url;
     return url;
 }
-function getServiceToken(env) {
-    if (tokenCache[env])
-        return tokenCache[env];
+function getServiceToken(env, scope) {
+    // Cache key includes scope: the same env can mint tokens with different
+    // scopes (default internal:users:write vs gateway:admin for gateway-admin,
+    // #70) and user-auth issues request∩allowed_scopes — mixing them up would
+    // hand a wrongly-scoped token to the caller.
+    const cacheKey = scope ? `${env}:${scope}` : env;
+    if (tokenCache[cacheKey])
+        return tokenCache[cacheKey];
     // cn-prod 与 cn-stage 都用 client_credentials M2M token，scope=internal:users:write。
     // 凭证来源不同：
     //  · cn-prod —— 镜像在 AWS Infisical prod 环境（CN_PROD_ 前缀键），复用既有 AWS 访问。
@@ -148,7 +153,8 @@ function getServiceToken(env) {
     const authUrl = USER_AUTH_URLS[env];
     if (!authUrl)
         throw new Error(`Unknown env: ${env}`);
-    const scopeParam = isCn ? `&scope=${encodeURIComponent(CN_PROD_TOKEN_SCOPE)}` : '';
+    const effectiveScope = scope ?? (isCn ? CN_PROD_TOKEN_SCOPE : undefined);
+    const scopeParam = effectiveScope ? `&scope=${encodeURIComponent(effectiveScope)}` : '';
     const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}${scopeParam}`;
     const response = (0, child_process_1.execSync)(`curl -s -X POST '${authUrl}/api/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' -d '${body}'`, { encoding: 'utf-8' });
     let parsed;
@@ -161,7 +167,7 @@ function getServiceToken(env) {
     if (!parsed.access_token) {
         throw new Error(`user-auth token mint failed (${env}): ${response.slice(0, 200)}`);
     }
-    tokenCache[env] = parsed.access_token;
+    tokenCache[cacheKey] = parsed.access_token;
     return parsed.access_token;
 }
 function formatServiceError(status, statusText, body) {

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

@@ -35,6 +35,10 @@ 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' },
+    // build-only:非 SAE 常驻(gateway-core 按 session 拉起的镜像)。release 段=解析 ACR digest
+    // → 回写 Infisical /services/gateway-core/ALIYUN_AGENT_RUNTIME_IMAGE(#807)→ 滚动重启 gateway-core。
+    // 无自身 saeAppId;prod 流水线(agent-runtime-cn-prod,5124970)按名实时解析(见下方 ListPipelines 逻辑)。
+    'agent-runtime': { pipelineId: 5124962, repo: 'optima-gateway', buildOnly: true },
     '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' },
@@ -133,7 +137,10 @@ async function main() {
     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 });
+        // vtag 发版时 ref 是 tag,不是 branch —— GetBranchInfo 查不到 tag 会恒超时,改用 tag 接口。
+        const b = vtag
+            ? devops('GetRepositoryTag', { repositoryId: String(repoId), tagName: ref })
+            : devops('GetBranchInfo', { repositoryId: String(repoId), branchName: ref });
         if (b?.result?.commit?.id === ghSha) {
             synced = true;
             break;
@@ -191,7 +198,16 @@ async function main() {
     console.log(`${status === 'SUCCESS' ? '✅' : '❌'} ${svcName} run#${runId}: ${status}`);
     if (status !== 'SUCCESS')
         process.exit(1);
-    // 4. SAE ImageUrl 校验(空返回重试守卫)。prod 是 digest 寻址,校验含 @sha256 即部署成功。
+    // 4. 成功标准。build-only(agent-runtime)无自身 SAE app 可查:digest 回写 Infisical +
+    //    滚动重启 gateway-core 都在流水线 release 段内完成(任一步失败即 exit 非 0)。CLI 不碰
+    //    Infisical 凭证,只以流水线终态为准、不独立校验回写是否真落地——故措辞用「应已」而非「已」;
+    //    真实 digest / 重启变更单在 run『发版』段日志里(见上方链接)。
+    if (svc.buildOnly) {
+        const infEnv = envName === 'prod' ? 'prod' : 'staging';
+        console.log(`✓ 流水线 SUCCESS(build-only)。release 段应已回写 ${infEnv} Infisical ALIYUN_AGENT_RUNTIME_IMAGE(@sha256 digest)并滚动重启 gateway-core;CLI 未独立校验,digest 见上方 run『发版』段日志`);
+        return;
+    }
+    // SAE ImageUrl 校验(空返回重试守卫)。prod 是 digest 寻址,校验含 @sha256 即部署成功。
     const appId = envName === 'prod' ? svc.prodSaeAppId : svc.saeAppId;
     if (appId) {
         let img = '';

package/dist/bin/helpers/gateway-admin.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+"use strict";
+// optima-gateway-admin — 通用透传型 gateway-core /admin/* 操作 CLI（#70）。
+//
+// 定位：dev-skills 现有 admin 技能（account/grant-credits/entitlement）打的都是
+// user-auth 与 billing；gateway 自身的 /admin/*（COO kill、warm-pool drain、
+// credits adjust、provider key CRUD、config CRUD、llm-rates、models 等）此前只能
+// 手写 curl + 手拼 token（#1681 止血即被迫手写 DB UPDATE + aliyun CLI）。本命令
+// 把「铸 gateway:admin token → 调端点 → 展示结果」收敛成一条命令。
+//
+// 凭证（#70 方向 1）：复用 dev-skills 各环境既有 OAuth client（client_credentials），
+// 其 allowed_scopes 已加 gateway:admin（cn-stage/cn-prod 2026-07-23 提权）；
+// token 铸造显式带 scope=gateway:admin（user-auth 发 request∩allowed_scopes，
+// 不显式带则 scope 为空 → gateway 403，见 #70 技术现状）。
+//
+// 安全门：GET/HEAD 直通；写方法（POST/PUT/PATCH/DELETE）一律回显完整
+// method+URL+body 后要求交互确认（所有环境，非仅 prod——admin 面写操作在
+// stage 也可能打断在跑会话），--yes 跳过（脚本化用）。
+//
+// v1 支持 cn-stage / cn-prod（AWS prod gateway 已关停 2026-06-26；AWS stage
+// 需要时再接 domain-urls，见 #70 讨论）。
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const readline = __importStar(require("readline"));
+const billing_http_1 = require("./billing-http");
+const GATEWAY_ADMIN_SCOPE = 'gateway:admin';
+// 与 verify-health.ts 的 gateway-core 域名同源（cn 域名稳定、硬编码，与
+// billing-http 的 cn URL 处理同一 rationale）。
+const GATEWAY_URLS = {
+    'cn-prod': 'https://gw.yzsgo.com',
+    'cn-stage': 'https://gw.stage.optima.chat',
+};
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+function usage() {
+    console.log(`Usage: optima-gateway-admin <METHOD> <path> [jsonBody] [options]
+
+Call a gateway-core /admin/* endpoint with a gateway:admin service token (#70).
+
+Arguments:
+  METHOD                GET | POST | PUT | PATCH | DELETE
+  path                  Endpoint path, must start with /admin/
+  jsonBody              JSON request body (write methods only)
+
+Options:
+  --env <env>           cn-stage (default) | cn-prod
+  --yes                 Skip the write-confirmation prompt (scripting)
+  -h, --help            Show this help
+
+Safety:
+  GET/HEAD run directly. POST/PUT/PATCH/DELETE echo the full request and
+  require typing "yes" — on EVERY env, not just prod (admin writes can
+  disrupt live sessions on stage too). Use --yes to skip.
+
+Examples:
+  optima-gateway-admin GET /admin/llm-rates --env cn-stage
+  optima-gateway-admin GET /admin/coo/instances --env cn-prod
+  optima-gateway-admin POST /admin/coo/users/<userId>/kill --env cn-stage
+  optima-gateway-admin PUT /admin/config/SOME_KEY '{"value":"x"}' --env cn-stage`);
+    process.exit(0);
+}
+function parseArgs(args) {
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h')
+        usage();
+    let env = 'cn-stage';
+    let yes = false;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--env' || a === '-e') {
+            env = args[++i] ?? '';
+        }
+        else if (a.startsWith('--env=')) {
+            env = a.slice('--env='.length);
+        }
+        else if (a === '--yes' || a === '-y') {
+            yes = true;
+        }
+        else if (a.startsWith('--')) {
+            console.error(`❌ Unknown flag: ${a}`);
+            process.exit(1);
+        }
+        else {
+            positional.push(a);
+        }
+    }
+    if (!GATEWAY_URLS[env]) {
+        console.error(`❌ --env must be "cn-stage" or "cn-prod" (got: ${env}). AWS stage 未接（prod gateway 已关停），需要时见 #70。`);
+        process.exit(1);
+    }
+    const method = (positional[0] ?? '').toUpperCase();
+    if (!['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+        console.error(`❌ METHOD must be GET/HEAD/POST/PUT/PATCH/DELETE (got: ${positional[0] ?? '(missing)'})`);
+        process.exit(1);
+    }
+    const path = positional[1] ?? '';
+    // 硬约束 /admin/ 前缀：本命令的 token 只该用于 admin 面；防拼错路径把
+    // gateway:admin token 打到任意端点（最小暴露面）。
+    if (!path.startsWith('/admin/')) {
+        console.error(`❌ path must start with /admin/ (got: ${path || '(missing)'})`);
+        process.exit(1);
+    }
+    let body = null;
+    if (positional[2] !== undefined) {
+        if (!WRITE_METHODS.has(method)) {
+            console.error(`❌ ${method} does not take a body`);
+            process.exit(1);
+        }
+        try {
+            JSON.parse(positional[2]);
+        }
+        catch {
+            console.error(`❌ jsonBody is not valid JSON: ${positional[2].slice(0, 120)}`);
+            process.exit(1);
+        }
+        body = positional[2];
+    }
+    return { method, path, body, env, yes };
+}
+async function confirmWrite(p, url) {
+    if (!WRITE_METHODS.has(p.method) || p.yes)
+        return;
+    const prodMark = p.env === 'cn-prod' ? '  🔴 PRODUCTION' : '';
+    console.log(`\n⚠️  About to ${p.method} on ${p.env.toUpperCase()}${prodMark}:\n  ${p.method} ${url}${p.body ? `\n  body: ${p.body}` : ''}\n`);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+        rl.question('Type "yes" to confirm: ', (a) => { rl.close(); resolve(a.trim()); });
+    });
+    if (answer !== 'yes') {
+        console.error('❌ Aborted by user.');
+        process.exit(1);
+    }
+}
+async function main() {
+    const p = parseArgs(process.argv.slice(2));
+    const url = `${GATEWAY_URLS[p.env]}${p.path}`;
+    await confirmWrite(p, url);
+    const token = (0, billing_http_1.getServiceToken)(p.env, GATEWAY_ADMIN_SCOPE);
+    const res = await fetch(url, {
+        method: p.method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...(p.body ? { 'Content-Type': 'application/json' } : {}),
+        },
+        ...(p.body ? { body: p.body } : {}),
+    });
+    const text = await res.text();
+    const statusLine = `${res.status} ${res.statusText}`;
+    if (!res.ok) {
+        console.error(`❌ [${statusLine}] ${p.method} ${p.path} (${p.env})`);
+        if (res.status === 403) {
+            console.error('   403 提示：token scope 可能为空——确认该环境 dev-skills client 的 allowed_scopes 已含 gateway:admin（#70）。');
+        }
+    }
+    else {
+        console.log(`✓ [${statusLine}] ${p.method} ${p.path} (${p.env})`);
+    }
+    if (text) {
+        try {
+            console.log(JSON.stringify(JSON.parse(text), null, 2));
+        }
+        catch {
+            console.log(text.slice(0, 4000));
+        }
+    }
+    process.exit(res.ok ? 0 : 1);
+}
+main().catch((err) => {
+    console.error(`\n❌ Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {
@@ -18,7 +18,8 @@
     "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-cn-deploy": "dist/bin/helpers/cn-deploy.js"
+    "optima-cn-deploy": "dist/bin/helpers/cn-deploy.js",
+    "optima-gateway-admin": "dist/bin/helpers/gateway-admin.js"
   },
   "scripts": {
     "postinstall": "node scripts/install.js",