@optima-chat/dev-skills 0.12.0 → 0.13.1

package/.claude/commands/query-db.md

@@ -200,13 +200,14 @@ print(f\"COMMERCE_DB_PASSWORD={secrets['COMMERCE_DB_PASSWORD']}\")
 " > /tmp/stage_db_config.sh && source /tmp/stage_db_config.sh
 
 # 4. 建立 SSH 隧道到 Shared EC2，通过隧道访问 Stage RDS
-ssh -i ~/.ssh/optima-ec2-key -f -N -L 15432:optima-stage-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com:5432 ec2-user@3.0.210.113
+# ⚠️ 先确认本地端口空闲(ss -ltn | grep 25432)——端口被本机 Docker PG 占用时,凭证会发给错误的库、报「密码错误」
+ssh -i ~/.ssh/optima-ec2-key -f -N -L 25432:optima-stage-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com:5432 ec2-user@3.0.210.113
 
-# 5. 通过本地端口 15432 连接到 RDS
-PGPASSWORD="${COMMERCE_DB_PASSWORD}" psql -h localhost -p 15432 -U "${COMMERCE_DB_USER}" -d optima_commerce -c "SELECT COUNT(*) FROM products"
+# 5. 通过本地端口 25432 连接到 RDS
+PGPASSWORD="${COMMERCE_DB_PASSWORD}" psql -h localhost -p 25432 -U "${COMMERCE_DB_USER}" -d optima_commerce -c "SELECT COUNT(*) FROM products"
 
 # 6. 关闭 SSH 隧道（可选）
-pkill -f "ssh.*15432:${DATABASE_HOST}:5432"
+pkill -f "ssh.*25432:${DATABASE_HOST}:5432"
 ```
 
 **完整示例（五个服务）**:
@@ -283,7 +284,7 @@ pkill -f "ssh.*15432:${DATABASE_HOST}:5432"
 - billing、ads-backend、amazon-backend、browser-backend、shopify-backend、optima-generation、optima-sentinel 的凭证存在各自服务路径的 `DATABASE_URL` 中
 - Stage RDS: `optima-stage-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com`
 - Shared EC2 IP: `3.0.210.113`
-- SSH 隧道: 本地端口 `15432` → Shared EC2 → Stage RDS `5432`
+- SSH 隧道: 本地端口 `25432` → Shared EC2 → Stage RDS `5432`
 - Stage 和 Prod 有独立的 RDS 实例
 - ⚠️ session-gateway 数据库名: Stage 用 `optima_shell`, Prod 用 `optima_ai_shell`
 
@@ -323,13 +324,14 @@ print(f\"COMMERCE_DB_PASSWORD={secrets['COMMERCE_DB_PASSWORD']}\")
 " > /tmp/prod_db_config.sh && source /tmp/prod_db_config.sh
 
 # 4. 建立 SSH 隧道到 Shared EC2，通过隧道访问 Prod RDS
-ssh -i ~/.ssh/optima-ec2-key -f -N -L 15433:optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com:5432 ec2-user@3.0.210.113
+# ⚠️ 先确认本地端口空闲(ss -ltn | grep 25433)——端口被本机 Docker PG 占用时,凭证会发给错误的库、报「密码错误」
+ssh -i ~/.ssh/optima-ec2-key -f -N -L 25433:optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com:5432 ec2-user@3.0.210.113
 
-# 5. 通过本地端口 15433 连接到 RDS
-PGPASSWORD="${COMMERCE_DB_PASSWORD}" psql -h localhost -p 15433 -U "${COMMERCE_DB_USER}" -d optima_commerce -c "SELECT COUNT(*) FROM products"
+# 5. 通过本地端口 25433 连接到 RDS
+PGPASSWORD="${COMMERCE_DB_PASSWORD}" psql -h localhost -p 25433 -U "${COMMERCE_DB_USER}" -d optima_commerce -c "SELECT COUNT(*) FROM products"
 
 # 6. 关闭 SSH 隧道（可选）
-pkill -f "ssh.*15433:${DATABASE_HOST}:5432"
+pkill -f "ssh.*25433:${DATABASE_HOST}:5432"
 ```
 
 **完整示例（五个服务）**:
@@ -394,8 +396,8 @@ pkill -f "ssh.*15433:${DATABASE_HOST}:5432"
 - billing、browser-backend、optima-generation 的凭证存在各自服务路径的 DATABASE_URL 中
 - Prod RDS: `optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com`
 - Shared EC2 IP: `3.0.210.113`
-- SSH 隧道: 本地端口 `15433` → Shared EC2 → Prod RDS `5432`
-- Stage 用端口 `15432`，Prod 用端口 `15433`
+- SSH 隧道: 本地端口 `25433` → Shared EC2 → Prod RDS `5432`
+- Stage 用端口 `25432`，Prod 用端口 `25433`
 - Stage 和 Prod 有独立的 RDS 实例
 - ⚠️ session-gateway 数据库名: Stage 用 `optima_shell`, Prod 用 `optima_ai_shell`
 

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

@@ -28,6 +28,19 @@ optima-cn-deploy --list                       # 列出全部可发服务
 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）
@@ -35,5 +48,5 @@ optima-cn-deploy --list                       # 列出全部可发服务
 
 ## 边界
 
-- 只发 **cn-stage**，不发 cn-prod（cn-prod 发布另走人工卡点流程）。
+- cn-prod 仅走 vtag 制（见上），且有人工卡点闸门；日常无 vtag 的构建只发 cn-stage。
 - 服务注册表是 optima-terraform `alicloud/stacks/cn-prod-buildbox/yunxiao/` 的快照；新增服务先在那边 gen-pipelines 建好流水线，再同步本工具的 SERVICES 表。

package/.claude/skills/query-db/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "query-db"
-description: "当用户请求查询数据库、执行SQL、查看数据、统计数据、检查数据库、查询表、数据库查询时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway、gateway-core、ads-backend、amazon-backend、shopify-backend、optima-sentinel 等服务的数据库查询。优先使用 optima-query-db CLI 工具。"
+description: "当用户请求查询数据库、执行SQL、查看数据、统计数据、检查数据库、查询表、数据库查询时，使用此技能。支持 CI、Stage、Prod、cn-prod、cn-stage（阿里云）五个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway、gateway-core、ads-backend、amazon-backend、shopify-backend、optima-sentinel 等服务的数据库查询。优先使用 optima-query-db CLI 工具。"
 allowed-tools: ["Bash", "SlashCommand"]
 ---
 
@@ -16,6 +16,8 @@ allowed-tools: ["Bash", "SlashCommand"]
 optima-query-db <service> "<sql>" [environment]
 ```
 
+**环境怎么传**：environment 取 `ci`（默认）/ `stage` / `prod` / `cn-prod` / `cn-stage`，作为**第 3 个位置参数**（`optima-query-db gateway-core "SELECT 1" cn-stage`）或 **`--env` 旗标**（`--env cn-stage`，短形式 `-e`、`--env=cn-stage` 也认，与 optima-logs 一致）。除 `--env`/`-e` 外没有其他旗标；未知旗标、多余参数、未知环境名、纯注释 SQL 都会硬报错并打印 usage，绝不静默空输出（背景见 issue #60）。
+
 **为什么使用 CLI 工具**：
 - ✅ 统一实现，避免重复代码
 - ✅ 自动处理所有环境差异
@@ -60,6 +62,12 @@ optima-query-db commerce-backend "SELECT COUNT(*) FROM orders" stage
 
 # Prod 环境
 optima-query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY status" prod
+
+# cn-stage 环境（阿里云预发；也可写成 --env cn-stage）
+optima-query-db gateway-core "SELECT COUNT(*) FROM conversations" cn-stage
+
+# cn-prod 环境（阿里云生产）
+optima-query-db billing "SELECT COUNT(*) FROM credit_ledger" cn-prod
 ```
 
 ### 使用 Slash 命令（备用）
@@ -184,6 +192,26 @@ optima-query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY s
 - 通过 SSH 隧道访问 RDS
 - ⚠️ 谨慎使用
 
+### cn-stage / cn-prod 环境（阿里云）
+
+```bash
+optima-query-db gateway-core "SELECT COUNT(*) FROM conversations" cn-stage
+optima-query-db gateway-core "SELECT key, value FROM app_configs" cn-prod
+```
+
+**特点**：
+- 阿里云侧独立部署：cn-stage（预发）与 cn-prod（生产）是**两个独立 RDS 实例**（共用 prod VPC 与 buildbox 跳板）
+- 独立 Infisical 实例（secrets-cn.optima.chat，单实例双环境：cn-prod→`prod`、cn-stage→`staging`），与 AWS 侧 Infisical 完全无关
+- 经 buildbox ECS 跳板自动建 SSH 隧道连内网 RDS
+- ⚠️ cn-prod 是生产真实用户数据，谨慎使用
+
+**前置环境变量**（缺失时命令会报错并提示，详见 https://github.com/Optima-Chat/optima-dev-skills/issues/21 ）：
+
+| 变量 | 用途 | 来源 |
+|------|------|------|
+| `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)」 |
+
 ## 🔧 技术架构
 
 ### Infisical 配置（v0.7.0+）
@@ -217,12 +245,14 @@ optima-query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY s
 
 ### RDS 连接
 
-| 环境 | RDS Host | 本地端口 |
-|------|----------|----------|
-| Stage | `optima-stage-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com` | 15432 |
-| Prod | `optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com` | 15433 |
+| 环境 | RDS Host | 跳板 |
+|------|----------|------|
+| Stage | `optima-stage-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com` | Shared EC2 `3.0.210.113` |
+| Prod | `optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com` | Shared EC2 `3.0.210.113` |
+| cn-stage | `pgm-2zem1u9zdh06boim.pg.rds.aliyuncs.com` | buildbox ECS `47.94.105.163` |
+| cn-prod | `pgm-2zexwx9eso9e4yla.pg.rds.aliyuncs.com` | buildbox ECS `47.94.105.163` |
 
-**跳板机**: `3.0.210.113` (Shared EC2)
+**本地端口**：动态分配（自 25432 起扫描空闲端口，记录在 `~/.cache/optima-dev-skills/tunnel-ports.json`，复用前校验隧道健康）；旧文档的固定 15432/15433 已废弃——固定端口会撞本机 Docker PG。
 
 ## 🔗 相关命令
 

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

@@ -28,6 +28,19 @@ optima-cn-deploy --list                       # 列出全部可发服务
 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）
@@ -35,5 +48,5 @@ optima-cn-deploy --list                       # 列出全部可发服务
 
 ## 边界
 
-- 只发 **cn-stage**，不发 cn-prod（cn-prod 发布另走人工卡点流程）。
+- cn-prod 仅走 vtag 制（见上），且有人工卡点闸门；日常无 vtag 的构建只发 cn-stage。
 - 服务注册表是 optima-terraform `alicloud/stacks/cn-prod-buildbox/yunxiao/` 的快照；新增服务先在那边 gen-pipelines 建好流水线，再同步本工具的 SERVICES 表。

package/.codex/skills/query-db/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "query-db"
-description: "Use when the user asks to query Optima databases, inspect rows, validate data, or run SQL in CI, Stage, or Prod."
+description: "Use when the user asks to query Optima databases, inspect rows, validate data, or run SQL in CI, Stage, Prod, cn-prod, or cn-stage."
 ---
 
 # Query Databases
@@ -15,6 +15,17 @@ Always prefer:
 optima-query-db <service> "<sql>" [environment]
 ```
 
+## Environments
+
+`ci` (default), `stage`, `prod`, `cn-prod` (Aliyun production), `cn-stage` (Aliyun staging).
+
+Pass the environment as the 3rd positional argument (`optima-query-db gateway-core "SELECT 1" cn-stage`) or via the `--env` flag (`--env cn-stage`, consistent with optima-logs). Any other flag, extra positional argument, unknown environment name, or comment-only SQL is rejected with a hard error instead of a silent empty result (see issue #60).
+
+For `cn-prod` / `cn-stage`, two extra env vars are required (the CLI prints an actionable error when missing; see https://github.com/Optima-Chat/optima-dev-skills/issues/21 ):
+
+- `INFISICAL_CN_EMAIL` + `INFISICAL_CN_PASSWORD` — cn Infisical login (1Password "Infisical cn-prod admin (secrets-cn.optima.chat)")
+- `OPTIMA_CN_BUILDBOX_PASSWORD` — buildbox ECS root password for the RDS tunnel (1Password "Aliyun cn-prod buildbox ECS (root)"); optional when a healthy tunnel already exists
+
 ## Services
 
 - `commerce-backend`

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Optima Dev Skills For Codex
 
-This repository provides shared development skills and CLI helpers for Optima engineers across `ci`, `stage`, and `prod`.
+This repository provides shared development skills and CLI helpers for Optima engineers across `ci`, `stage`, `prod`, `cn-stage`, and `cn-prod` (Aliyun).
 
 ## Primary Entry Points
 
@@ -51,9 +51,9 @@ Some flows also require:
 
 ## Safety Rules
 
-- Default to `ci` or `stage` when possible.
-- Treat `prod` as read-only unless the user explicitly asks for a write action.
-- For `prod`, prefer limited queries and targeted operational commands.
+- Default to `ci` or `stage` when possible; on the Aliyun side, default to `cn-stage`.
+- Treat `prod` and `cn-prod` as read-only unless the user explicitly asks for a write action — `cn-prod` holds real production user data.
+- For `prod` / `cn-prod`, prefer limited queries and targeted operational commands.
 - Do not expose secrets unless the user explicitly asks to inspect them.
 
 ## Platform Notes

package/bin/helpers/cn-deploy.ts

@@ -18,6 +18,9 @@
  *   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);本表为其快照,
@@ -31,28 +34,28 @@ 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; }
+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' },
-  'agentic-chat':             { pipelineId: 5118520, repo: 'agentic-chat',       saeAppId: '6aea1ce1-f813-4e1c-8e97-d1ecb5398e37' },
-  'billing':                  { pipelineId: 5118521, repo: 'optima-billing',     saeAppId: '09d8e292-dc64-4af8-bce5-0a56cb666921' },
-  'browser-backend':          { pipelineId: 5118522, repo: 'optima-browser-use', saeAppId: '1fced3f6-a80a-41a4-8f23-e4d5a467f8eb' },
-  'commerce-backend':         { pipelineId: 5107005, repo: 'commerce-backend',   saeAppId: '49d09808-508c-471a-9560-553c49a67f72' },
-  'commerce-rq-scheduler':    { pipelineId: 5118523, repo: 'commerce-backend',   saeAppId: '1d2810ef-889e-4675-b6e6-a299e4722e68' },
-  'commerce-rq-worker':       { pipelineId: 5118524, repo: 'commerce-backend',   saeAppId: 'd661da87-6d24-40b8-93ed-e1c967d8abe2' },
-  'gateway-core':             { pipelineId: 5118525, repo: 'optima-gateway',     saeAppId: '9326b7ff-da52-48d6-86db-9c4a884be108' },
-  'gw-admin':                 { pipelineId: 5118526, repo: 'optima-gateway',     saeAppId: '90e0daf7-7910-46b8-b5bf-a0b8bcc60859' },
-  'kb-backend':               { pipelineId: 5118527, repo: 'kb-skills',          saeAppId: 'c7f65160-9d9e-416e-9e36-5439010d2b2d' },
-  'ops-portal':               { pipelineId: 5118529, repo: 'optima-portals',     saeAppId: '41d0ee66-8402-4e72-bfda-8eba75d1270c' },
-  'optima-generation':        { pipelineId: 5118530, repo: 'optima-gen',         saeAppId: '327856d5-8b18-4e15-bfd8-b8bd3b807ffa' },
-  'optima-generation-worker': { pipelineId: 5118531, repo: 'optima-gen',         saeAppId: 'ad75b3b0-9ff4-443d-b0ef-81886bc7aa60' },
-  'optima-scout':             { pipelineId: 5117336, repo: 'optima-scout',       saeAppId: 'bac2c3a4-90ce-49a6-81d5-caa38cb5c807' },
-  'optima-sentinel':          { pipelineId: 5118532, repo: 'optima-sentinel',    saeAppId: '3759db7b-4640-4a04-8436-4f241f0ec9d9' },
-  'optima-sentinel-worker':   { pipelineId: 5118533, repo: 'optima-sentinel',    saeAppId: '7c975caf-ebfb-4bb3-91c4-2a8c83d1d2e5' },
-  'optima-skills':            { pipelineId: 5118534, repo: 'optima-skills',      saeAppId: '90457be3-5eb3-4efc-a362-1788dcc51921' },
-  'user-auth':                { pipelineId: 5118510, repo: 'user-auth',          saeAppId: '36efc3a6-5b42-49fa-8db2-0865aa0c25d2' },
-  'user-auth-admin':          { pipelineId: 5118535, repo: 'user-auth',          saeAppId: '7feb9cc3-4731-4ea8-964c-4870a9e63afb' },
-  'yzsgo-api':                { pipelineId: 5118536, repo: 'yzsgo',              saeAppId: 'd0af7f66-ef66-4587-9e93-250d01ee3cf6' },
+  '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 {
@@ -88,10 +91,24 @@ async function main() {
   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/${branch}`, '--jq', '.sha']);
-  if (!ghSha) { console.error(`✗ GitHub 上无 ${svc.repo}@${branch}(或 gh 未登录)`); process.exit(1); }
+  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); }
@@ -99,29 +116,44 @@ 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: branch });
+    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}@${branch} = ${ghSha.slice(0, 10)}`);
+  console.log(`✓ mirror 已追平 ${svc.repo}@${ref} = ${ghSha.slice(0, 10)}`);
 
-  // 2. 触发(凭证由云效变量组 41970 供给,无需注入)
-  const kv: Record<string, string> = { pipelineId: String(svc.pipelineId) };
-  if (branch !== 'main') {
+  // 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} 已启动 (branch=${branch})`);
-  console.log(`  https://flow.aliyun.com/pipelines/${svc.pipelineId}/current`);
+  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(svc.pipelineId), pipelineRunId: String(runId) });
+    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);
@@ -129,19 +161,26 @@ async function main() {
   console.log(`${status === 'SUCCESS' ? '✅' : '❌'} ${svcName} run#${runId}: ${status}`);
   if (status !== 'SUCCESS') process.exit(1);
 
-  // 4. SAE ImageUrl 校验(空返回重试守卫)
-  if (svc.saeAppId) {
+  // 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', svc.saeAppId]);
+        'DescribeApplicationConfig', '--AppId', appId]);
       try { img = JSON.parse(raw)?.Data?.ImageUrl || ''; break; } catch { await sleep(3000); }
     }
     if (!img) { console.log('⚠️ SAE 配置查询连续空返回,跳过 ImageUrl 校验(流水线本身已 SUCCESS)'); return; }
-    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);
+    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);
+    }
   }
 }
 

package/bin/helpers/query-db.ts

@@ -150,20 +150,111 @@ function queryDatabase(host: string, port: number, user: string, password: strin
   return result;
 }
 
+const USAGE = `Usage: optima-query-db <service> "<sql>" [environment]
+   or: optima-query-db <service> "<sql>" --env <environment>
+
+Services: commerce-backend, user-auth, agentic-chat, bi-backend, session-gateway, gateway-core, optima-logistics, billing, ads-backend, amazon-backend, browser-backend, shopify-backend, optima-generation, optima-sentinel
+Environments: ci (default), stage, prod, cn-prod (阿里云生产), cn-stage (阿里云预发)
+
+Example: optima-query-db user-auth "SELECT COUNT(*) FROM users" prod`;
+
+/** 参数用法错误（入口打印 message + usage 后退非零，区别于运行期错误）。 */
+export class QueryDbUsageError extends Error {}
+
+const VALID_ENVS = ['ci', 'stage', 'prod', 'cn-prod', 'cn-stage'];
+// 'cn' 是历史别名（isCnEnv 认作 cn-prod），继续放行但不在 usage 里宣传。
+const ENV_ALIASES = ['cn'];
+
+// 单 token 旗标形态，含 --flag=value / 下划线（--env=cn-stage、--dry_run）。
+// 带空白的 SQL 文本不会匹配；整段是注释的 SQL 由下方空语句检查兜住。
+const FLAG_RE = /^--?[A-Za-z][-A-Za-z0-9_]*(=.*)?$/;
+
+// SQL 去掉块注释、行注释、分号与空白后是否不剩任何语句（psql 对纯注释静默 no-op + exit 0）。
+// 已知残留：PostgreSQL 块注释可嵌套（/* a /* b …两层闭合… ），本检查非嵌套感知会放行——
+// 现实中几乎不出现，真出现也只是退回旧的空输出行为，不误伤合法 SQL。
+function isEffectivelyEmptySql(sql: string): boolean {
+  const stripped = sql
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .split('\n').map((l) => l.replace(/--.*/, '')).join('\n')
+    .replace(/[;\s]+/g, '');
+  return stripped.length === 0;
+}
+
+/**
+ * 解析 `<service> <sql> [environment]`，environment 也可经 --env/-e 旗标给
+ * （对齐 optima-logs 惯例）。历史 footgun（#60）：`--env cn-stage` 曾被吞成
+ * sql='--env'（SQL 注释 = no-op）+ 真 SQL 静默丢弃，空输出 + exit 0 被误判成
+ * 「环境读不到」。故未知旗标、多余参数、未知环境、纯注释 SQL 一律硬报错。
+ */
+export function parseQueryDbArgs(
+  args: string[],
+): { service: string; sql: string; environment: string } {
+  const positionals: string[] = [];
+  let envFromFlag: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--env' || arg === '-e' || arg.startsWith('--env=') || arg.startsWith('-e=')) {
+      let value: string | undefined;
+      if (arg.includes('=')) {
+        value = arg.slice(arg.indexOf('=') + 1);
+      } else {
+        value = args[i + 1];
+        i++;
+      }
+      if (!value || FLAG_RE.test(value)) {
+        throw new QueryDbUsageError('--env 需要环境名，如 --env cn-stage');
+      }
+      if (envFromFlag !== undefined) {
+        throw new QueryDbUsageError('--env 重复指定');
+      }
+      envFromFlag = value;
+      continue;
+    }
+    if (FLAG_RE.test(arg)) {
+      throw new QueryDbUsageError(`未知旗标 ${arg}（仅支持 --env <环境>，其余都是位置参数）`);
+    }
+    positionals.push(arg);
+  }
+
+  if (positionals.length < 2) {
+    throw new QueryDbUsageError('缺少参数：需要 <service> <sql>');
+  }
+  const maxPositionals = envFromFlag !== undefined ? 2 : 3;
+  if (positionals.length > maxPositionals) {
+    throw new QueryDbUsageError(
+      envFromFlag !== undefined && positionals.length === 3
+        ? `environment 同时以 --env 和位置参数给出：${envFromFlag} vs ${positionals[2]}`
+        : `多余参数已拒绝（绝不静默丢弃）：${positionals.slice(maxPositionals).join(' ')}。SQL 含空格时记得整体加引号`,
+    );
+  }
+
+  const [service, sql] = positionals;
+  const environment = envFromFlag ?? positionals[2] ?? 'ci';
+
+  if (!VALID_ENVS.includes(environment) && !ENV_ALIASES.includes(environment)) {
+    throw new QueryDbUsageError(`未知环境 ${environment}（可选 ${VALID_ENVS.join(' | ')}）`);
+  }
+
+  if (isEffectivelyEmptySql(sql)) {
+    throw new QueryDbUsageError(
+      'SQL 为空或全是注释/分号（psql 会静默 no-op）——检查参数顺序：<service> <sql> [environment]',
+    );
+  }
+
+  return { service, sql, environment };
+}
+
 async function main() {
-  const args = process.argv.slice(2);
-
-  if (args.length < 2) {
-    console.error('Usage: query-db.ts <service> <sql> [environment]');
-    console.error('');
-    console.error('Services: commerce-backend, user-auth, agentic-chat, bi-backend, session-gateway, gateway-core, optima-logistics, billing, ads-backend, amazon-backend, browser-backend, shopify-backend, optima-generation, optima-sentinel');
-    console.error('Environments: ci (default), stage, prod, cn-prod (阿里云生产), cn-stage (阿里云预发)');
-    console.error('');
-    console.error('Example: query-db.ts user-auth "SELECT COUNT(*) FROM users" prod');
-    process.exit(1);
+  const argv = process.argv.slice(2);
+  // help 只认第 1 个参数位：尾部混入的 -h 走未知旗标报错（exit 1），
+  // 不给「打 usage 后 exit 0 但没跑 SQL」的静默通道。
+  if (argv[0] === '--help' || argv[0] === '-h') {
+    console.log(USAGE);
+    return;
   }
 
-  const [service, sql, environment = 'ci'] = args;
+  const { service, sql, environment } = parseQueryDbArgs(argv);
 
   if (!SERVICE_DB_MAP[service as keyof typeof SERVICE_DB_MAP]) {
     console.error(`Unknown service: ${service}`);
@@ -273,7 +364,16 @@ async function main() {
   }
 }
 
-main().catch(error => {
-  console.error('\n❌ Error:', error.message);
-  process.exit(1);
-});
+// Only run the CLI flow when invoked directly — being require()'d (e.g. by the
+// unit tests for parseQueryDbArgs) must not trigger main().
+if (require.main === module) {
+  main().catch(error => {
+    if (error instanceof QueryDbUsageError) {
+      console.error(`❌ ${error.message}\n`);
+      console.error(USAGE);
+    } else {
+      console.error('\n❌ Error:', error.message);
+    }
+    process.exit(1);
+  });
+}

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

@@ -20,6 +20,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
  *   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);本表为其快照,
@@ -31,26 +34,26 @@ 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' },
-    'agentic-chat': { pipelineId: 5118520, repo: 'agentic-chat', saeAppId: '6aea1ce1-f813-4e1c-8e97-d1ecb5398e37' },
-    'billing': { pipelineId: 5118521, repo: 'optima-billing', saeAppId: '09d8e292-dc64-4af8-bce5-0a56cb666921' },
-    'browser-backend': { pipelineId: 5118522, repo: 'optima-browser-use', saeAppId: '1fced3f6-a80a-41a4-8f23-e4d5a467f8eb' },
-    'commerce-backend': { pipelineId: 5107005, repo: 'commerce-backend', saeAppId: '49d09808-508c-471a-9560-553c49a67f72' },
-    'commerce-rq-scheduler': { pipelineId: 5118523, repo: 'commerce-backend', saeAppId: '1d2810ef-889e-4675-b6e6-a299e4722e68' },
-    'commerce-rq-worker': { pipelineId: 5118524, repo: 'commerce-backend', saeAppId: 'd661da87-6d24-40b8-93ed-e1c967d8abe2' },
-    'gateway-core': { pipelineId: 5118525, repo: 'optima-gateway', saeAppId: '9326b7ff-da52-48d6-86db-9c4a884be108' },
-    'gw-admin': { pipelineId: 5118526, repo: 'optima-gateway', saeAppId: '90e0daf7-7910-46b8-b5bf-a0b8bcc60859' },
-    'kb-backend': { pipelineId: 5118527, repo: 'kb-skills', saeAppId: 'c7f65160-9d9e-416e-9e36-5439010d2b2d' },
-    'ops-portal': { pipelineId: 5118529, repo: 'optima-portals', saeAppId: '41d0ee66-8402-4e72-bfda-8eba75d1270c' },
-    'optima-generation': { pipelineId: 5118530, repo: 'optima-gen', saeAppId: '327856d5-8b18-4e15-bfd8-b8bd3b807ffa' },
-    'optima-generation-worker': { pipelineId: 5118531, repo: 'optima-gen', saeAppId: 'ad75b3b0-9ff4-443d-b0ef-81886bc7aa60' },
-    'optima-scout': { pipelineId: 5117336, repo: 'optima-scout', saeAppId: 'bac2c3a4-90ce-49a6-81d5-caa38cb5c807' },
-    'optima-sentinel': { pipelineId: 5118532, repo: 'optima-sentinel', saeAppId: '3759db7b-4640-4a04-8436-4f241f0ec9d9' },
-    'optima-sentinel-worker': { pipelineId: 5118533, repo: 'optima-sentinel', saeAppId: '7c975caf-ebfb-4bb3-91c4-2a8c83d1d2e5' },
-    'optima-skills': { pipelineId: 5118534, repo: 'optima-skills', saeAppId: '90457be3-5eb3-4efc-a362-1788dcc51921' },
-    'user-auth': { pipelineId: 5118510, repo: 'user-auth', saeAppId: '36efc3a6-5b42-49fa-8db2-0865aa0c25d2' },
-    'user-auth-admin': { pipelineId: 5118535, repo: 'user-auth', saeAppId: '7feb9cc3-4731-4ea8-964c-4870a9e63afb' },
-    'yzsgo-api': { pipelineId: 5118536, repo: 'yzsgo', saeAppId: 'd0af7f66-ef66-4587-9e93-250d01ee3cf6' },
+    '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 {
@@ -90,10 +93,34 @@ async function main() {
     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/${branch}`, '--jq', '.sha']);
+    const ghSha = sh('gh', ['api', `repos/Optima-Chat/${svc.repo}/commits/${ref}`, '--jq', '.sha']);
     if (!ghSha) {
-        console.error(`✗ GitHub 上无 ${svc.repo}@${branch}(或 gh 未登录)`);
+        console.error(`✗ GitHub 上无 ${svc.repo}@${ref}(或 gh 未登录,tag 需已 push)`);
         process.exit(1);
     }
     const repos = devops('ListRepositories', { perPage: '100' });
@@ -106,7 +133,7 @@ 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: branch });
+        const b = devops('GetBranchInfo', { repositoryId: String(repoId), branchName: ref });
         if (b?.result?.commit?.id === ghSha) {
             synced = true;
             break;
@@ -117,10 +144,26 @@ async function main() {
         console.error('✗ 300s 内 Codeup mirror 未追平 GitHub,中止(检查 mirror 凭证)');
         process.exit(1);
     }
-    console.log(`✓ mirror 已追平 ${svc.repo}@${branch} = ${ghSha.slice(0, 10)}`);
-    // 2. 触发(凭证由云效变量组 41970 供给,无需注入)
-    const kv = { pipelineId: String(svc.pipelineId) };
-    if (branch !== 'main') {
+    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);
@@ -129,14 +172,17 @@ async function main() {
         console.error(`✗ 启动失败: ${JSON.stringify(start).slice(0, 150)}`);
         process.exit(1);
     }
-    console.log(`▶ ${svcName} run#${runId} 已启动 (branch=${branch})`);
-    console.log(`  https://flow.aliyun.com/pipelines/${svc.pipelineId}/current`);
+    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(svc.pipelineId), pipelineRunId: String(runId) });
+        const d = devops('GetPipelineRun', { pipelineId: String(pipelineId), pipelineRunId: String(runId) });
         status = d?.pipelineRun?.status || status;
         if (['SUCCESS', 'FAIL', 'CANCELED', 'ERROR'].includes(status))
             break;
@@ -145,12 +191,13 @@ async function main() {
     console.log(`${status === 'SUCCESS' ? '✅' : '❌'} ${svcName} run#${runId}: ${status}`);
     if (status !== 'SUCCESS')
         process.exit(1);
-    // 4. SAE ImageUrl 校验(空返回重试守卫)
-    if (svc.saeAppId) {
+    // 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', svc.saeAppId]);
+                'DescribeApplicationConfig', '--AppId', appId]);
             try {
                 img = JSON.parse(raw)?.Data?.ImageUrl || '';
                 break;
@@ -163,11 +210,19 @@ async function main() {
             console.log('⚠️ SAE 配置查询连续空返回,跳过 ImageUrl 校验(流水线本身已 SUCCESS)');
             return;
         }
-        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);
+        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/query-db.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryDbUsageError = void 0;
+exports.parseQueryDbArgs = parseQueryDbArgs;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const db_utils_1 = require("./db-utils");
@@ -164,18 +166,95 @@ function queryDatabase(host, port, user, password, database, sql) {
     });
     return result;
 }
+const USAGE = `Usage: optima-query-db <service> "<sql>" [environment]
+   or: optima-query-db <service> "<sql>" --env <environment>
+
+Services: commerce-backend, user-auth, agentic-chat, bi-backend, session-gateway, gateway-core, optima-logistics, billing, ads-backend, amazon-backend, browser-backend, shopify-backend, optima-generation, optima-sentinel
+Environments: ci (default), stage, prod, cn-prod (阿里云生产), cn-stage (阿里云预发)
+
+Example: optima-query-db user-auth "SELECT COUNT(*) FROM users" prod`;
+/** 参数用法错误（入口打印 message + usage 后退非零，区别于运行期错误）。 */
+class QueryDbUsageError extends Error {
+}
+exports.QueryDbUsageError = QueryDbUsageError;
+const VALID_ENVS = ['ci', 'stage', 'prod', 'cn-prod', 'cn-stage'];
+// 'cn' 是历史别名（isCnEnv 认作 cn-prod），继续放行但不在 usage 里宣传。
+const ENV_ALIASES = ['cn'];
+// 单 token 旗标形态，含 --flag=value / 下划线（--env=cn-stage、--dry_run）。
+// 带空白的 SQL 文本不会匹配；整段是注释的 SQL 由下方空语句检查兜住。
+const FLAG_RE = /^--?[A-Za-z][-A-Za-z0-9_]*(=.*)?$/;
+// SQL 去掉块注释、行注释、分号与空白后是否不剩任何语句（psql 对纯注释静默 no-op + exit 0）。
+// 已知残留：PostgreSQL 块注释可嵌套（/* a /* b …两层闭合… ），本检查非嵌套感知会放行——
+// 现实中几乎不出现，真出现也只是退回旧的空输出行为，不误伤合法 SQL。
+function isEffectivelyEmptySql(sql) {
+    const stripped = sql
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .split('\n').map((l) => l.replace(/--.*/, '')).join('\n')
+        .replace(/[;\s]+/g, '');
+    return stripped.length === 0;
+}
+/**
+ * 解析 `<service> <sql> [environment]`，environment 也可经 --env/-e 旗标给
+ * （对齐 optima-logs 惯例）。历史 footgun（#60）：`--env cn-stage` 曾被吞成
+ * sql='--env'（SQL 注释 = no-op）+ 真 SQL 静默丢弃，空输出 + exit 0 被误判成
+ * 「环境读不到」。故未知旗标、多余参数、未知环境、纯注释 SQL 一律硬报错。
+ */
+function parseQueryDbArgs(args) {
+    const positionals = [];
+    let envFromFlag;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--env' || arg === '-e' || arg.startsWith('--env=') || arg.startsWith('-e=')) {
+            let value;
+            if (arg.includes('=')) {
+                value = arg.slice(arg.indexOf('=') + 1);
+            }
+            else {
+                value = args[i + 1];
+                i++;
+            }
+            if (!value || FLAG_RE.test(value)) {
+                throw new QueryDbUsageError('--env 需要环境名，如 --env cn-stage');
+            }
+            if (envFromFlag !== undefined) {
+                throw new QueryDbUsageError('--env 重复指定');
+            }
+            envFromFlag = value;
+            continue;
+        }
+        if (FLAG_RE.test(arg)) {
+            throw new QueryDbUsageError(`未知旗标 ${arg}（仅支持 --env <环境>，其余都是位置参数）`);
+        }
+        positionals.push(arg);
+    }
+    if (positionals.length < 2) {
+        throw new QueryDbUsageError('缺少参数：需要 <service> <sql>');
+    }
+    const maxPositionals = envFromFlag !== undefined ? 2 : 3;
+    if (positionals.length > maxPositionals) {
+        throw new QueryDbUsageError(envFromFlag !== undefined && positionals.length === 3
+            ? `environment 同时以 --env 和位置参数给出：${envFromFlag} vs ${positionals[2]}`
+            : `多余参数已拒绝（绝不静默丢弃）：${positionals.slice(maxPositionals).join(' ')}。SQL 含空格时记得整体加引号`);
+    }
+    const [service, sql] = positionals;
+    const environment = envFromFlag ?? positionals[2] ?? 'ci';
+    if (!VALID_ENVS.includes(environment) && !ENV_ALIASES.includes(environment)) {
+        throw new QueryDbUsageError(`未知环境 ${environment}（可选 ${VALID_ENVS.join(' | ')}）`);
+    }
+    if (isEffectivelyEmptySql(sql)) {
+        throw new QueryDbUsageError('SQL 为空或全是注释/分号（psql 会静默 no-op）——检查参数顺序：<service> <sql> [environment]');
+    }
+    return { service, sql, environment };
+}
 async function main() {
-    const args = process.argv.slice(2);
-    if (args.length < 2) {
-        console.error('Usage: query-db.ts <service> <sql> [environment]');
-        console.error('');
-        console.error('Services: commerce-backend, user-auth, agentic-chat, bi-backend, session-gateway, gateway-core, optima-logistics, billing, ads-backend, amazon-backend, browser-backend, shopify-backend, optima-generation, optima-sentinel');
-        console.error('Environments: ci (default), stage, prod, cn-prod (阿里云生产), cn-stage (阿里云预发)');
-        console.error('');
-        console.error('Example: query-db.ts user-auth "SELECT COUNT(*) FROM users" prod');
-        process.exit(1);
+    const argv = process.argv.slice(2);
+    // help 只认第 1 个参数位：尾部混入的 -h 走未知旗标报错（exit 1），
+    // 不给「打 usage 后 exit 0 但没跑 SQL」的静默通道。
+    if (argv[0] === '--help' || argv[0] === '-h') {
+        console.log(USAGE);
+        return;
     }
-    const [service, sql, environment = 'ci'] = args;
+    const { service, sql, environment } = parseQueryDbArgs(argv);
     if (!SERVICE_DB_MAP[service]) {
         console.error(`Unknown service: ${service}`);
         console.error('Available services:', Object.keys(SERVICE_DB_MAP).join(', '));
@@ -267,7 +346,17 @@ async function main() {
         console.log('\n' + result);
     }
 }
-main().catch(error => {
-    console.error('\n❌ Error:', error.message);
-    process.exit(1);
-});
+// Only run the CLI flow when invoked directly — being require()'d (e.g. by the
+// unit tests for parseQueryDbArgs) must not trigger main().
+if (require.main === module) {
+    main().catch(error => {
+        if (error instanceof QueryDbUsageError) {
+            console.error(`❌ ${error.message}\n`);
+            console.error(USAGE);
+        }
+        else {
+            console.error('\n❌ Error:', error.message);
+        }
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {
@@ -23,7 +23,9 @@
   "scripts": {
     "postinstall": "node scripts/install.js",
     "build": "tsc",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "pretest": "npm run build",
+    "test": "node --test tests/*.test.js"
   },
   "keywords": [
     "claude-code",
@@ -63,4 +65,4 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   }
-}
+}