@optima-chat/dev-skills 0.13.0 → 0.14.0

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
 
@@ -14,7 +14,7 @@ Prefer the installed CLI tools over reimplementing long shell workflows:
 - `optima-product <create|update|add-channel|toggle-channel|show> [options]` — manage paid-plugin marketplace Products + Stripe channels (Wave 1.5 admin endpoints; stage default)
 - `optima-entitlement <grant|revoke|list> [options]` — admin-grant / revoke / list paid-plugin entitlements (refuses revoke of PAYMENT / PARTNER source)
 - `optima-cn-deploy <service> [--branch feat/xxx] [--no-wait]` — 云效 Flow 发布到 cn-stage(mirror 同步→构建→DB 迁移→SAE 发布→sha 校验;20 服务,凭证由云效变量组供给零配置)
-- `optima-plugin <show|set-paid|set-default> [options]` — flip a plugin's skills-side paid/free state (isPaid) + defaultForUser (the user-facing gate; pairs with optima-product for the billing side)
+- `optima-plugin <show|set-paid|set-default|set-status> [options]` — flip a plugin's skills-side paid/free state (isPaid) + defaultForUser (the user-facing gate; pairs with optima-product for the billing side) + lifecycle status (ACTIVE|BETA|DEPRECATED — retire/restore a marketplace plugin)
 
 For code-reading tasks across Optima repositories, use `gh` commands against `Optima-Chat/<repo>`.
 
@@ -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/plugin/set-status.ts

@@ -0,0 +1,90 @@
+import { callSkills, validateEnvCnProd } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+export const VALID_PLUGIN_STATUSES = ['ACTIVE', 'BETA', 'DEPRECATED'] as const;
+export type PluginStatus = (typeof VALID_PLUGIN_STATUSES)[number];
+
+// Aligned with agent-runtime skill-sync-handler's isValidSlug (and the
+// deprecate-plugin workflow guard in optima-default-skills#40).
+const SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+export interface SetStatusArgs {
+  slug: string;
+  status: PluginStatus;
+  yes: boolean;
+  env: string;
+}
+
+export function parseSetStatusArgs(argv: string[]): SetStatusArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-plugin set-status --slug <slug> --status ACTIVE|BETA|DEPRECATED [options]
+
+Required:
+  --slug <slug>
+  --status <status>    Sets Plugin.status (marketplace lifecycle gate).
+                       DEPRECATED retires the plugin: registry sync stops
+                       serving it and agents unload it on their next sync
+                       (in-flight sessions keep it until then). ACTIVE
+                       restores it. Fully reversible.
+
+Optional:
+  --yes                Skip prod confirmation prompt (no-op on stage)
+  --env <env>          stage|prod|cn-prod|cn-stage (default: stage)
+
+Note: this PATCH's 404 is the authoritative "slug has no marketplace row in
+this env" signal. Don't use 'optima-plugin show' to check existence — it reads
+the public endpoint, which also 404s for non-ACTIVE (e.g. already-DEPRECATED)
+plugins.`);
+    process.exit(0);
+  }
+  const out: Partial<SetStatusArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--slug': out.slug = next; i++; break;
+      case '--status': {
+        const upper = (next ?? '').toUpperCase();
+        if (!(VALID_PLUGIN_STATUSES as readonly string[]).includes(upper)) {
+          throw new Error(`--status must be one of: ${VALID_PLUGIN_STATUSES.join('|')}`);
+        }
+        out.status = upper as PluginStatus; i++; break;
+      }
+      case '--yes': out.yes = true; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.slug) throw new Error('--slug required');
+  if (!SLUG_RE.test(out.slug)) throw new Error(`--slug must match ${SLUG_RE} (lowercase slug, e.g. onboarding-research)`);
+  if (!out.status) throw new Error(`--status required (${VALID_PLUGIN_STATUSES.join('|')})`);
+  return out as SetStatusArgs;
+}
+
+export async function runSetStatus(argv: string[]): Promise<void> {
+  const args = parseSetStatusArgs(argv);
+  validateEnvCnProd(args.env);
+
+  await confirmIfProd(
+    args.env,
+    `Action: set status=${args.status} on plugin '${args.slug}' (${args.env.toUpperCase()})`,
+    args.yes,
+  );
+
+  console.log(`\n🚦 Setting status=${args.status} on ${args.slug} (${args.env.toUpperCase()})...`);
+  const res = await callSkills(
+    args.env,
+    'PATCH',
+    `/api/admin/plugins/${encodeURIComponent(args.slug)}`,
+    { status: args.status },
+  );
+  console.log(`✓ Updated plugin (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+  if (args.status === 'DEPRECATED') {
+    console.log(`\nℹ️  Takes effect on each user's next skill sync (new session / billing event): registry stops serving the plugin and agents unload its skills. In-flight sessions keep it until then. Restore anytime with --status ACTIVE. Verify retirement end-to-end by confirming an agent session no longer loads the plugin's skills.`);
+  } else if (args.status === 'ACTIVE') {
+    console.log(`\nℹ️  Plugin restored: registry serves it again on each user's next skill sync.`);
+  } else if (args.status === 'BETA') {
+    console.log(`\n⚠️  BETA is NOT served either: registry sync / system load / user install all filter status='ACTIVE' (optima-skills internal.ts & user-plugins.ts). Users lose the plugin on their next sync, same as DEPRECATED — it's a pre-GA gate, not a soft-launch channel.`);
+  }
+}

package/bin/helpers/plugin.ts

@@ -3,6 +3,7 @@
 import { runShow } from './plugin/show';
 import { runSetPaid } from './plugin/set-paid';
 import { runSetDefault } from './plugin/set-default';
+import { runSetStatus } from './plugin/set-status';
 
 function printHelp() {
   console.log(`Usage: optima-plugin <subcommand> [options]
@@ -11,6 +12,7 @@ Subcommands:
   show          Show a plugin's marketplace state (isPaid, salesUrl, ... ACTIVE plugins only)
   set-paid      Flip a plugin's isPaid flag (the user-facing paid/free gate)
   set-default   Flip a plugin's defaultForUser flag
+  set-status    Set a plugin's lifecycle status (ACTIVE|BETA|DEPRECATED — retire/restore)
 
 Run 'optima-plugin <subcommand> --help' for subcommand-specific options.`);
 }
@@ -22,6 +24,7 @@ async function main() {
     case 'show': await runShow(rest); break;
     case 'set-paid': await runSetPaid(rest); break;
     case 'set-default': await runSetDefault(rest); break;
+    case 'set-status': await runSetStatus(rest); break;
     default:
       console.error(`Unknown subcommand: ${subcommand}`);
       printHelp();

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/plugin/set-status.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_PLUGIN_STATUSES = void 0;
+exports.parseSetStatusArgs = parseSetStatusArgs;
+exports.runSetStatus = runSetStatus;
+const billing_http_1 = require("../billing-http");
+const confirm_prompt_1 = require("../confirm-prompt");
+exports.VALID_PLUGIN_STATUSES = ['ACTIVE', 'BETA', 'DEPRECATED'];
+// Aligned with agent-runtime skill-sync-handler's isValidSlug (and the
+// deprecate-plugin workflow guard in optima-default-skills#40).
+const SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+function parseSetStatusArgs(argv) {
+    if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+        console.log(`Usage: optima-plugin set-status --slug <slug> --status ACTIVE|BETA|DEPRECATED [options]
+
+Required:
+  --slug <slug>
+  --status <status>    Sets Plugin.status (marketplace lifecycle gate).
+                       DEPRECATED retires the plugin: registry sync stops
+                       serving it and agents unload it on their next sync
+                       (in-flight sessions keep it until then). ACTIVE
+                       restores it. Fully reversible.
+
+Optional:
+  --yes                Skip prod confirmation prompt (no-op on stage)
+  --env <env>          stage|prod|cn-prod|cn-stage (default: stage)
+
+Note: this PATCH's 404 is the authoritative "slug has no marketplace row in
+this env" signal. Don't use 'optima-plugin show' to check existence — it reads
+the public endpoint, which also 404s for non-ACTIVE (e.g. already-DEPRECATED)
+plugins.`);
+        process.exit(0);
+    }
+    const out = { env: 'stage', yes: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = argv[i + 1];
+        switch (a) {
+            case '--slug':
+                out.slug = next;
+                i++;
+                break;
+            case '--status': {
+                const upper = (next ?? '').toUpperCase();
+                if (!exports.VALID_PLUGIN_STATUSES.includes(upper)) {
+                    throw new Error(`--status must be one of: ${exports.VALID_PLUGIN_STATUSES.join('|')}`);
+                }
+                out.status = upper;
+                i++;
+                break;
+            }
+            case '--yes':
+                out.yes = true;
+                break;
+            case '--env':
+                out.env = next;
+                i++;
+                break;
+            default: throw new Error(`Unknown arg: ${a}`);
+        }
+    }
+    if (!out.slug)
+        throw new Error('--slug required');
+    if (!SLUG_RE.test(out.slug))
+        throw new Error(`--slug must match ${SLUG_RE} (lowercase slug, e.g. onboarding-research)`);
+    if (!out.status)
+        throw new Error(`--status required (${exports.VALID_PLUGIN_STATUSES.join('|')})`);
+    return out;
+}
+async function runSetStatus(argv) {
+    const args = parseSetStatusArgs(argv);
+    (0, billing_http_1.validateEnvCnProd)(args.env);
+    await (0, confirm_prompt_1.confirmIfProd)(args.env, `Action: set status=${args.status} on plugin '${args.slug}' (${args.env.toUpperCase()})`, args.yes);
+    console.log(`\n🚦 Setting status=${args.status} on ${args.slug} (${args.env.toUpperCase()})...`);
+    const res = await (0, billing_http_1.callSkills)(args.env, 'PATCH', `/api/admin/plugins/${encodeURIComponent(args.slug)}`, { status: args.status });
+    console.log(`✓ Updated plugin (HTTP ${res.status}):`);
+    console.log(JSON.stringify(res.body, null, 2));
+    if (args.status === 'DEPRECATED') {
+        console.log(`\nℹ️  Takes effect on each user's next skill sync (new session / billing event): registry stops serving the plugin and agents unload its skills. In-flight sessions keep it until then. Restore anytime with --status ACTIVE. Verify retirement end-to-end by confirming an agent session no longer loads the plugin's skills.`);
+    }
+    else if (args.status === 'ACTIVE') {
+        console.log(`\nℹ️  Plugin restored: registry serves it again on each user's next skill sync.`);
+    }
+    else if (args.status === 'BETA') {
+        console.log(`\n⚠️  BETA is NOT served either: registry sync / system load / user install all filter status='ACTIVE' (optima-skills internal.ts & user-plugins.ts). Users lose the plugin on their next sync, same as DEPRECATED — it's a pre-GA gate, not a soft-launch channel.`);
+    }
+}

package/dist/bin/helpers/plugin.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const show_1 = require("./plugin/show");
 const set_paid_1 = require("./plugin/set-paid");
 const set_default_1 = require("./plugin/set-default");
+const set_status_1 = require("./plugin/set-status");
 function printHelp() {
     console.log(`Usage: optima-plugin <subcommand> [options]
 
@@ -11,6 +12,7 @@ Subcommands:
   show          Show a plugin's marketplace state (isPaid, salesUrl, ... ACTIVE plugins only)
   set-paid      Flip a plugin's isPaid flag (the user-facing paid/free gate)
   set-default   Flip a plugin's defaultForUser flag
+  set-status    Set a plugin's lifecycle status (ACTIVE|BETA|DEPRECATED — retire/restore)
 
 Run 'optima-plugin <subcommand> --help' for subcommand-specific options.`);
 }
@@ -30,6 +32,9 @@ async function main() {
         case 'set-default':
             await (0, set_default_1.runSetDefault)(rest);
             break;
+        case 'set-status':
+            await (0, set_status_1.runSetStatus)(rest);
+            break;
         default:
             console.error(`Unknown subcommand: ${subcommand}`);
             printHelp();

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.14.0",
   "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"
   }
-}
+}