@optima-chat/dev-skills 0.15.0 → 0.16.1

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/.claude/skills/query-db/SKILL.md

@@ -212,6 +212,8 @@ optima-query-db gateway-core "SELECT key, value FROM app_configs" cn-prod
 | `INFISICAL_CN_EMAIL` + `INFISICAL_CN_PASSWORD` | 登录 cn Infisical 取数据库凭证 | 1Password「Infisical cn-prod admin (secrets-cn.optima.chat)」 |
 | `OPTIMA_CN_BUILDBOX_PASSWORD` | 经 buildbox 跳板建 RDS 隧道（本机已有健康隧道时可省） | 1Password「Aliyun cn-prod buildbox ECS (root)」 |
 
+> **两条独立路径**：① 从上表的 1P 取值 `export` 到当前 session（不落盘，推荐；有 `op` CLI 更佳）；或 ② 若你**自己**维护本地明文文件 `~/.infisical_cn_creds`（每行 `export KEY=val`）和 `~/.buildbox_pw`（纯密码一行），工具会自动读取、免手动 `export`/`source`（路径分别可用 `INFISICAL_CN_CREDS_FILE` / `OPTIMA_CN_BUILDBOX_PW_FILE` 覆盖）。②是明文落盘的便捷取舍（`chmod 600`，权限宽于 600 工具会打警告），非默认做法、别把 1P 密码抄进文件；没放这些文件时回退走 env（①）。creds 文件解析**不是 shell**：只认最朴素的 `KEY=值` 与成对引号，无引号值别写行尾注释。
+
 ## 🔧 技术架构
 
 ### Infisical 配置（v0.7.0+）

package/.claude/skills/show-env/SKILL.md

@@ -77,8 +77,10 @@ optima-show-env agentic-chat stage
 - `shopify-backend` - Shopify 店铺管理服务
 
 **支持的环境**：
-- `stage` - Stage 预发布环境
-- `prod` - Prod 生产环境
+- `stage` - Stage 预发布环境（AWS Infisical）
+- `prod` - Prod 生产环境（AWS Infisical）
+- `cn-stage` - 阿里云 cn-stage（读 cn Infisical，需凭据，见「故障排查 · 问题 2b」）
+- `cn-prod` - 阿里云 cn-prod（同上）
 
 ### 3. 使用过滤和选项
 
@@ -198,6 +200,17 @@ npm install -g @optima-chat/dev-skills@latest
 - 运行 `gh auth login` 登录 GitHub
 - 确认有仓库访问权限
 
+### 问题 2b：cn-stage / cn-prod 报「需要 INFISICAL_CN_EMAIL / PASSWORD」
+
+`cn-stage` / `cn-prod` 读的是**阿里云 cn Infisical**（`secrets-cn.optima.chat`，与 AWS 那套完全独立），需要 admin 账密两个环境变量。**两条独立路径，按你的安全取向二选一**：
+
+- **走 1Password（推荐，密码不落盘）**：从「Infisical cn-prod admin (secrets-cn.optima.chat)」取值，`export INFISICAL_CN_EMAIL=... INFISICAL_CN_PASSWORD=...` 到当前 session（装了 `op` CLI 可 `op run` / `op read` 注入，用完即散）。
+- **本地凭据文件（便捷，安全性较弱）**：若你**自己**维护 `~/.infisical_cn_creds`（每行 `export KEY=val`），本工具会自动读取、免手动 `source`；路径用 `INFISICAL_CN_CREDS_FILE` 覆盖。⚠️ 明文落盘（务必 `chmod 600`），是「省事 vs 暴露面」的取舍——**不是让你把 1P 密码抄进文件当默认做法**，只是给已经这么存的人一个自动读取入口。
+
+> 两者互不依赖：有本地文件就自动用，没有就回退读 env（即走 1P 那条）。`optima-query-db cn-stage/cn-prod` 的 buildbox 密码同理——`export OPTIMA_CN_BUILDBOX_PASSWORD=...`，或本地 `~/.buildbox_pw`（纯密码一行，自动读取；`OPTIMA_CN_BUILDBOX_PW_FILE` 可覆盖路径）；密码在 1P「Aliyun cn-prod buildbox ECS (root)」。
+>
+> ⚠️ creds 文件的解析**不是 shell**：只认每行一条最朴素的 `KEY=值`（可带 `export `），值要么整体用成对引号包住、要么不含空格；引号值后的内容（如行尾注释）会被忽略，**无引号值别写行尾注释**（`#` 会被当成值的一部分）。文件权限宽于 600 时工具会打警告。
+
 ### 问题 3：服务不存在
 
 **错误信息**: "Unknown service 'xxx'"

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

@@ -120,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);
   }

package/bin/helpers/db-utils.ts

@@ -109,15 +109,75 @@ function curlJson(args: string[]): any {
   catch { throw new Error(`cn Infisical: non-JSON response: ${String(out).slice(0, 200)}`); }
 }
 
+/** 明文密码文件权限比 600 宽（组/其他用户可读）时往 stderr 警告一行。Windows 无此语义，跳过。 */
+function warnIfLoosePerms(file: string): void {
+  if (process.platform === 'win32') return;
+  try {
+    const mode = fs.statSync(file).mode & 0o777;
+    if (mode & 0o077) console.error(`⚠️  ${file} 权限 ${mode.toString(8).padStart(3, '0')}（同机其他用户可读）——建议 chmod 600 ${file}`);
+  } catch { /* stat 失败不阻塞主流程 */ }
+}
+
+/**
+ * 若 creds 文件存在，把其中 `export KEY=val` / `KEY=val` 行注入 process.env（已存在的键不覆盖）。
+ * 免去每次手动 `source ~/.infisical_cn_creds`；文件不存在则静默跳过，回退到调用方的 env 检查。
+ * ⚠️ 不是 shell：只认最朴素的每行一条 `KEY=值`。值以引号开头时取到配对引号为止（其后内容
+ * 忽略，行尾注释因此无害）；引号未闭合的行警告并跳过（真 shell 会语法错，静默注入 `"abc`
+ * 这类错值只会换来下游 401、更难查）；无引号值取到行尾原样保留（别写行尾注释，`#` 会进值）。
+ * 导出仅供测试。
+ */
+const loadedCredsFiles = new Set<string>(); // 同一文件只加载/警告一次（getCnInfisicalToken 与 setupCnSSHTunnel 都会调）
+export function loadCredsFileIntoEnv(file: string): void {
+  if (loadedCredsFiles.has(file)) return;
+  loadedCredsFiles.add(file);
+  let content: string;
+  try { content = fs.readFileSync(file, 'utf-8'); }
+  catch { return; } // 文件不存在/不可读 = 无操作，保持原有「读 env」行为
+  warnIfLoosePerms(file);
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!m) continue;
+    const key = m[1];
+    if (process.env[key] !== undefined) continue; // 已有 env 优先，不覆盖
+    let val = m[2].trim();
+    const q = val[0];
+    if (q === '"' || q === "'") {
+      const close = val.indexOf(q, 1);
+      if (close === -1) {
+        console.error(`⚠️  ${file} 第 ${i + 1} 行（${key}=）引号未闭合，已跳过该行`);
+        continue;
+      }
+      val = val.slice(1, close); // 配对引号截取，忽略其后（如行尾注释）
+    }
+    process.env[key] = val;
+  }
+}
+
+/**
+ * 读 buildbox 密码文件（纯密码一行；默认 ~/.buildbox_pw，OPTIMA_CN_BUILDBOX_PW_FILE 可覆盖）。
+ * 文件不存在/为空 → undefined，回退到调用方报错。导出仅供测试。
+ */
+export function readBuildboxPwFile(): string | undefined {
+  const file = process.env.OPTIMA_CN_BUILDBOX_PW_FILE || `${os.homedir()}/.buildbox_pw`;
+  let pw: string;
+  try { pw = fs.readFileSync(file, 'utf-8').trim(); }
+  catch { return undefined; }
+  warnIfLoosePerms(file); // 读到文件就查权限，空文件也警告
+  if (!pw) return undefined;
+  return pw;
+}
+
 /**
  * 认证 cn Infisical（admin email/password → org-scoped token）。
  * ⚠️ 字段名坑：login 返回 `accessToken`（不是 token），select-organization 才返回 `token`。
  */
 export function getCnInfisicalToken(): string {
+  loadCredsFileIntoEnv(process.env.INFISICAL_CN_CREDS_FILE || `${os.homedir()}/.infisical_cn_creds`);
   const email = process.env.INFISICAL_CN_EMAIL;
   const password = process.env.INFISICAL_CN_PASSWORD;
   if (!email || !password) {
-    throw new Error('cn Infisical 需要 INFISICAL_CN_EMAIL + INFISICAL_CN_PASSWORD 环境变量（admin user，1P "Infisical cn-prod admin (secrets-cn.optima.chat)"）。见 optima-dev-skills#21。');
+    throw new Error('cn Infisical 需要 INFISICAL_CN_EMAIL + INFISICAL_CN_PASSWORD。① 从 1Password "Infisical cn-prod admin (secrets-cn.optima.chat)" 取值 export（不落盘）；或 ② 本工具自动读取本地文件 ~/.infisical_cn_creds（每行 `export KEY=val`，INFISICAL_CN_CREDS_FILE 可覆盖）。见 optima-dev-skills#21。');
   }
   const login = curlJson([
     '-X', 'POST', `${CN_INFISICAL_URL}/api/v3/auth/login`,
@@ -318,8 +378,10 @@ function setupSSMTunnel(dbHost: string, localPort: number): void {
  * 密码经 SSHPASS 环境变量传给 `sshpass -e`：不进命令行（ps 不可见）、不经 shell 引号展开。
  */
 function setupCnSSHTunnel(dbHost: string, localPort: number): void {
-  const pw = process.env.OPTIMA_CN_BUILDBOX_PASSWORD;
-  if (!pw) throw new Error('cn DB 隧道需要 OPTIMA_CN_BUILDBOX_PASSWORD 环境变量（buildbox root 密码，1P "Aliyun cn-prod buildbox ECS (root)"）。见 optima-dev-skills#21。');
+  // creds 文件里也可能放 OPTIMA_CN_BUILDBOX_PASSWORD——自己加载一次（幂等），不依赖 getCnInfisicalToken 恰好先跑
+  loadCredsFileIntoEnv(process.env.INFISICAL_CN_CREDS_FILE || `${os.homedir()}/.infisical_cn_creds`);
+  const pw = process.env.OPTIMA_CN_BUILDBOX_PASSWORD || readBuildboxPwFile();
+  if (!pw) throw new Error('cn DB 隧道需要 OPTIMA_CN_BUILDBOX_PASSWORD。① 从 1Password "Aliyun cn-prod buildbox ECS (root)" 取值 export；或 ② 本工具自动读取本地文件 ~/.buildbox_pw（纯密码一行，OPTIMA_CN_BUILDBOX_PW_FILE 可覆盖路径）。见 optima-dev-skills#21。');
   try { execSync('command -v sshpass', { stdio: 'ignore' }); }
   catch { throw new Error('sshpass not found — cn buildbox 隧道需要（apt install sshpass / brew install esolitos/ipa/sshpass）。Windows 用 WSL。'); }
 

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

@@ -137,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;

package/dist/bin/helpers/db-utils.js

@@ -43,6 +43,8 @@ exports.getGitHubVariable = getGitHubVariable;
 exports.getInfisicalConfig = getInfisicalConfig;
 exports.getInfisicalToken = getInfisicalToken;
 exports.getInfisicalSecrets = getInfisicalSecrets;
+exports.loadCredsFileIntoEnv = loadCredsFileIntoEnv;
+exports.readBuildboxPwFile = readBuildboxPwFile;
 exports.getCnInfisicalToken = getCnInfisicalToken;
 exports.getCnSecrets = getCnSecrets;
 exports.parseDatabaseUrl = parseDatabaseUrl;
@@ -137,15 +139,87 @@ function curlJson(args) {
         throw new Error(`cn Infisical: non-JSON response: ${String(out).slice(0, 200)}`);
     }
 }
+/** 明文密码文件权限比 600 宽（组/其他用户可读）时往 stderr 警告一行。Windows 无此语义，跳过。 */
+function warnIfLoosePerms(file) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        const mode = fs.statSync(file).mode & 0o777;
+        if (mode & 0o077)
+            console.error(`⚠️  ${file} 权限 ${mode.toString(8).padStart(3, '0')}（同机其他用户可读）——建议 chmod 600 ${file}`);
+    }
+    catch { /* stat 失败不阻塞主流程 */ }
+}
+/**
+ * 若 creds 文件存在，把其中 `export KEY=val` / `KEY=val` 行注入 process.env（已存在的键不覆盖）。
+ * 免去每次手动 `source ~/.infisical_cn_creds`；文件不存在则静默跳过，回退到调用方的 env 检查。
+ * ⚠️ 不是 shell：只认最朴素的每行一条 `KEY=值`。值以引号开头时取到配对引号为止（其后内容
+ * 忽略，行尾注释因此无害）；引号未闭合的行警告并跳过（真 shell 会语法错，静默注入 `"abc`
+ * 这类错值只会换来下游 401、更难查）；无引号值取到行尾原样保留（别写行尾注释，`#` 会进值）。
+ * 导出仅供测试。
+ */
+const loadedCredsFiles = new Set(); // 同一文件只加载/警告一次（getCnInfisicalToken 与 setupCnSSHTunnel 都会调）
+function loadCredsFileIntoEnv(file) {
+    if (loadedCredsFiles.has(file))
+        return;
+    loadedCredsFiles.add(file);
+    let content;
+    try {
+        content = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return;
+    } // 文件不存在/不可读 = 无操作，保持原有「读 env」行为
+    warnIfLoosePerms(file);
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (process.env[key] !== undefined)
+            continue; // 已有 env 优先，不覆盖
+        let val = m[2].trim();
+        const q = val[0];
+        if (q === '"' || q === "'") {
+            const close = val.indexOf(q, 1);
+            if (close === -1) {
+                console.error(`⚠️  ${file} 第 ${i + 1} 行（${key}=）引号未闭合，已跳过该行`);
+                continue;
+            }
+            val = val.slice(1, close); // 配对引号截取，忽略其后（如行尾注释）
+        }
+        process.env[key] = val;
+    }
+}
+/**
+ * 读 buildbox 密码文件（纯密码一行；默认 ~/.buildbox_pw，OPTIMA_CN_BUILDBOX_PW_FILE 可覆盖）。
+ * 文件不存在/为空 → undefined，回退到调用方报错。导出仅供测试。
+ */
+function readBuildboxPwFile() {
+    const file = process.env.OPTIMA_CN_BUILDBOX_PW_FILE || `${os.homedir()}/.buildbox_pw`;
+    let pw;
+    try {
+        pw = fs.readFileSync(file, 'utf-8').trim();
+    }
+    catch {
+        return undefined;
+    }
+    warnIfLoosePerms(file); // 读到文件就查权限，空文件也警告
+    if (!pw)
+        return undefined;
+    return pw;
+}
 /**
  * 认证 cn Infisical（admin email/password → org-scoped token）。
  * ⚠️ 字段名坑：login 返回 `accessToken`（不是 token），select-organization 才返回 `token`。
  */
 function getCnInfisicalToken() {
+    loadCredsFileIntoEnv(process.env.INFISICAL_CN_CREDS_FILE || `${os.homedir()}/.infisical_cn_creds`);
     const email = process.env.INFISICAL_CN_EMAIL;
     const password = process.env.INFISICAL_CN_PASSWORD;
     if (!email || !password) {
-        throw new Error('cn Infisical 需要 INFISICAL_CN_EMAIL + INFISICAL_CN_PASSWORD 环境变量（admin user，1P "Infisical cn-prod admin (secrets-cn.optima.chat)"）。见 optima-dev-skills#21。');
+        throw new Error('cn Infisical 需要 INFISICAL_CN_EMAIL + INFISICAL_CN_PASSWORD。① 从 1Password "Infisical cn-prod admin (secrets-cn.optima.chat)" 取值 export（不落盘）；或 ② 本工具自动读取本地文件 ~/.infisical_cn_creds（每行 `export KEY=val`，INFISICAL_CN_CREDS_FILE 可覆盖）。见 optima-dev-skills#21。');
     }
     const login = curlJson([
         '-X', 'POST', `${CN_INFISICAL_URL}/api/v3/auth/login`,
@@ -357,9 +431,11 @@ function setupSSMTunnel(dbHost, localPort) {
  * 密码经 SSHPASS 环境变量传给 `sshpass -e`：不进命令行（ps 不可见）、不经 shell 引号展开。
  */
 function setupCnSSHTunnel(dbHost, localPort) {
-    const pw = process.env.OPTIMA_CN_BUILDBOX_PASSWORD;
+    // creds 文件里也可能放 OPTIMA_CN_BUILDBOX_PASSWORD——自己加载一次（幂等），不依赖 getCnInfisicalToken 恰好先跑
+    loadCredsFileIntoEnv(process.env.INFISICAL_CN_CREDS_FILE || `${os.homedir()}/.infisical_cn_creds`);
+    const pw = process.env.OPTIMA_CN_BUILDBOX_PASSWORD || readBuildboxPwFile();
     if (!pw)
-        throw new Error('cn DB 隧道需要 OPTIMA_CN_BUILDBOX_PASSWORD 环境变量（buildbox root 密码，1P "Aliyun cn-prod buildbox ECS (root)"）。见 optima-dev-skills#21。');
+        throw new Error('cn DB 隧道需要 OPTIMA_CN_BUILDBOX_PASSWORD。① 从 1Password "Aliyun cn-prod buildbox ECS (root)" 取值 export；或 ② 本工具自动读取本地文件 ~/.buildbox_pw（纯密码一行，OPTIMA_CN_BUILDBOX_PW_FILE 可覆盖路径）。见 optima-dev-skills#21。');
     try {
         (0, child_process_1.execSync)('command -v sshpass', { stdio: 'ignore' });
     }

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.15.0",
+  "version": "0.16.1",
   "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",