@optima-chat/dev-skills 0.13.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/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/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/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/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.13.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"
   }
-}
+}