@optima-chat/dev-skills 0.2.0 → 0.3.0

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

@@ -0,0 +1,238 @@
+# /query-db - 查询数据库
+
+执行 SQL 查询，支持 CI/Stage/Prod 三个环境。
+
+**版本**: v0.3.0
+
+## 使用场景
+
+**开发者**: 快速查询数据验证功能
+**调试**: 检查数据库状态、排查数据问题
+**运维**: 查看生产数据、统计分析
+
+## 用法
+
+```
+/query-db <service> <sql> [environment]
+```
+
+## 参数
+
+- `service` (必需): 服务名称
+  - `commerce-backend` - 电商后端数据库
+  - `user-auth` - 用户认证数据库
+  - `mcp-host` - MCP 协调器数据库
+  - `agentic-chat` - AI 聊天服务数据库
+- `sql` (必需): SQL 查询语句（用引号包裹）
+- `environment` (可选): 环境，默认 ci
+  - `ci` - CI 持续集成环境（开发环境，默认）
+  - `stage` - Stage 预发布环境
+  - `prod` - Prod 生产环境（⚠️ 谨慎使用）
+
+## 示例
+
+```bash
+/query-db commerce-backend "SELECT COUNT(*) FROM products"                    # CI 环境（默认）
+/query-db user-auth "SELECT email FROM users LIMIT 5"                        # CI 环境
+/query-db commerce-backend "SELECT * FROM orders WHERE status='pending'" ci  # CI 环境
+/query-db user-auth "SELECT COUNT(*) FROM users" stage                       # Stage 环境
+/query-db commerce-backend "SELECT * FROM products LIMIT 10" prod            # Prod 环境（只读）
+```
+
+## 特殊参数处理
+
+如果用户输入 `/query-db` 或 `/query-db --help`，显示此帮助文档，不执行查询。
+
+## Claude Code 执行步骤
+
+**重要提示**：根据用户指定的 `environment` 参数选择执行方式：
+- `ci` 或未指定 → 通过 SSH 连接 Docker Postgres（第 0 节，默认）
+- `stage` → 通过 AWS RDS 端点连接（第 1 节）
+- `prod` → 通过 AWS RDS 端点连接（第 2 节，⚠️ 只读）
+
+### 0. CI 环境（environment = "ci" 或默认）
+
+**访问方式**: SSH + Docker Exec
+
+**步骤**:
+```bash
+# IMPORTANT: 使用单行命令
+
+# 获取 CI 服务器配置
+CI_USER=$(gh variable get CI_SSH_USER -R Optima-Chat/optima-dev-skills)
+CI_HOST=$(gh variable get CI_SSH_HOST -R Optima-Chat/optima-dev-skills)
+CI_PASSWORD=$(gh variable get CI_SSH_PASSWORD -R Optima-Chat/optima-dev-skills)
+
+# 执行查询（根据服务选择不同的数据库）
+sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "docker exec commerce-postgres psql -U commerce -d commerce -c \"SELECT COUNT(*) FROM products\""
+```
+
+**数据库配置映射**：
+- `commerce-backend`:
+  - 容器: `commerce-postgres`
+  - 用户: `commerce`
+  - 密码: `commerce123`
+  - 数据库: `commerce`
+
+- `user-auth`:
+  - 容器: `user-auth-postgres-1`
+  - 用户: `userauth`
+  - 密码: `password123`
+  - 数据库: `userauth`
+
+- `mcp-host`:
+  - 容器: `mcp-host-db-1`
+  - 用户: `mcp_user`
+  - 密码: `mcp_password`
+  - 数据库: `mcp_host`
+
+- `agentic-chat`:
+  - 容器: `optima-postgres`
+  - 用户: `postgres`
+  - 密码: `postgres123`
+  - 数据库: `optima_chat`
+
+**完整命令示例**:
+```bash
+# 获取配置
+CI_USER=$(gh variable get CI_SSH_USER -R Optima-Chat/optima-dev-skills)
+CI_HOST=$(gh variable get CI_SSH_HOST -R Optima-Chat/optima-dev-skills)
+CI_PASSWORD=$(gh variable get CI_SSH_PASSWORD -R Optima-Chat/optima-dev-skills)
+
+# commerce-backend
+sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "docker exec commerce-postgres psql -U commerce -d commerce -c \"SELECT COUNT(*) FROM products\""
+
+# user-auth
+sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "docker exec user-auth-postgres-1 psql -U userauth -d userauth -c \"SELECT COUNT(*) FROM users\""
+
+# mcp-host
+sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "docker exec mcp-host-db-1 psql -U mcp_user -d mcp_host -c \"SELECT COUNT(*) FROM sessions\""
+
+# agentic-chat
+sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "docker exec optima-postgres psql -U postgres -d optima_chat -c \"SELECT COUNT(*) FROM conversations\""
+```
+
+### 1. Stage 环境（environment = "stage"）
+
+**访问方式**: AWS RDS 直连（需要配置）
+
+**步骤**:
+```bash
+# IMPORTANT: 使用单行命令
+
+# 从 GitHub Variables 获取 RDS 配置
+STAGE_DB_HOST=$(gh variable get STAGE_DB_HOST -R Optima-Chat/optima-dev-skills)
+STAGE_DB_PASSWORD=$(gh variable get STAGE_DB_PASSWORD -R Optima-Chat/optima-dev-skills)
+
+# 执行查询
+PGPASSWORD="$STAGE_DB_PASSWORD" psql -h "$STAGE_DB_HOST" -U commerce -d commerce -c "SELECT COUNT(*) FROM products"
+```
+
+**数据库配置**（需要设置 GitHub Variables）：
+- `STAGE_DB_HOST` - RDS 端点
+- `STAGE_DB_PASSWORD` - 数据库密码
+- 每个服务可能有独立的数据库
+
+### 2. Prod 环境（environment = "prod"）
+
+**访问方式**: AWS RDS 直连（⚠️ 只读用户）
+
+**步骤**:
+```bash
+# IMPORTANT: 使用单行命令
+# ⚠️ 生产环境只允许只读查询
+
+# 从 GitHub Variables 获取 RDS 配置
+PROD_DB_HOST=$(gh variable get PROD_DB_HOST -R Optima-Chat/optima-dev-skills)
+PROD_DB_PASSWORD=$(gh variable get PROD_DB_PASSWORD -R Optima-Chat/optima-dev-skills)
+
+# 执行查询（只读）
+PGPASSWORD="$PROD_DB_PASSWORD" psql -h "$PROD_DB_HOST" -U commerce_readonly -d commerce -c "SELECT COUNT(*) FROM products"
+```
+
+**⚠️ 生产环境安全规则**：
+1. **只使用只读用户** (`commerce_readonly`, `userauth_readonly`)
+2. **禁止 INSERT/UPDATE/DELETE**
+3. **谨慎使用 SELECT***，优先指定列名
+4. **添加 LIMIT** 防止查询过多数据
+
+## 安全注意事项
+
+### SQL 注入防护
+
+**❌ 危险示例**:
+```bash
+# 不要直接拼接用户输入
+/query-db commerce-backend "SELECT * FROM products WHERE id=$USER_INPUT"
+```
+
+**✅ 安全示例**:
+```bash
+# 使用参数化查询或明确的值
+/query-db commerce-backend "SELECT * FROM products WHERE id=123"
+```
+
+### 生产环境规则
+
+1. **只读查询**: 生产环境只允许 SELECT
+2. **限制返回行数**: 使用 LIMIT
+3. **避免全表扫描**: 使用 WHERE 条件
+4. **敏感数据**: 不查询密码、密钥等敏感字段
+
+### 常见安全查询
+
+```bash
+# ✅ 统计查询
+/query-db commerce-backend "SELECT COUNT(*) FROM orders WHERE created_at > NOW() - INTERVAL '1 day'" prod
+
+# ✅ 限制行数
+/query-db user-auth "SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 10" prod
+
+# ✅ 聚合查询
+/query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY status" prod
+
+# ❌ 危险：全表查询
+# /query-db commerce-backend "SELECT * FROM orders" prod
+
+# ❌ 危险：敏感字段
+# /query-db user-auth "SELECT password_hash FROM users" prod
+```
+
+## 常见错误处理
+
+### 错误：Connection refused
+
+**原因**: 数据库未运行或网络不通
+
+**解决**:
+```bash
+# CI: 检查容器状态
+sshpass -p "$CI_PASSWORD" ssh ${CI_USER}@${CI_HOST} "docker ps | grep postgres"
+
+# Stage/Prod: 检查安全组和网络配置
+```
+
+### 错误：Authentication failed
+
+**原因**: 用户名或密码错误
+
+**解决**: 检查 GitHub Variables 配置是否正确
+
+### 错误：Permission denied
+
+**原因**: 生产环境使用了写操作
+
+**解决**: 使用只读查询，移除 INSERT/UPDATE/DELETE
+
+## 最佳实践
+
+1. **默认使用 CI**: 开发调试优先用 CI 环境
+2. **生产只读**: Prod 环境只用于查看数据，不修改
+3. **添加 LIMIT**: 避免返回过多数据
+4. **使用聚合**: COUNT/SUM/AVG 比 SELECT * 更安全
+5. **索引查询**: 使用主键或索引字段提高性能
+
+## 相关资源
+
+- PostgreSQL 文档: https://www.postgresql.org/docs/
+- AWS RDS 最佳实践: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/

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

@@ -0,0 +1,163 @@
+---
+name: "query-db"
+description: "当用户请求查询数据库、执行SQL、查看数据、统计数据、检查数据库、查询表、数据库查询时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、mcp-host、agentic-chat 服务的数据库查询。"
+allowed-tools: ["Bash", "SlashCommand"]
+---
+
+# 查询数据库
+
+当你需要执行 SQL 查询检查数据时，使用这个场景。
+
+## 🎯 适用情况
+
+- 验证数据是否正确插入/更新
+- 统计数据（用户数、订单数等）
+- 排查数据问题
+- 检查数据库状态
+- 开发调试时查看数据
+
+## 🚀 快速操作
+
+### 1. 查询 CI 环境数据库（默认）
+
+```
+/query-db commerce-backend "SELECT COUNT(*) FROM products"
+/query-db user-auth "SELECT email FROM users LIMIT 5"
+```
+
+**说明**：
+- 查询 CI 开发环境数据库
+- 默认环境，不需要指定 `ci` 参数
+- 通过 SSH + Docker Exec 访问
+- 可以执行任何 SQL 语句
+
+### 2. 查询 Stage 环境数据库
+
+```
+/query-db commerce-backend "SELECT COUNT(*) FROM orders" stage
+```
+
+**说明**：
+- 查询 Stage 预发布环境
+- 通过 AWS RDS 直连
+
+### 3. 查询 Prod 环境数据库
+
+```
+/query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY status" prod
+```
+
+**说明**：
+- 查询生产环境数据库
+- ⚠️ **只读查询**，不能修改数据
+- 使用只读用户连接
+
+**常用服务**：
+- `commerce-backend` - 电商数据库
+- `user-auth` - 用户认证数据库
+- `mcp-host` - MCP 协调器数据库
+- `agentic-chat` - AI 聊天数据库
+
+### 4. 常用查询示例
+
+```
+# 统计查询
+/query-db commerce-backend "SELECT COUNT(*) FROM products WHERE status='active'"
+
+# 查看最新数据
+/query-db user-auth "SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 10"
+
+# 聚合统计
+/query-db commerce-backend "SELECT status, COUNT(*) as count FROM orders GROUP BY status"
+
+# 检查特定记录
+/query-db user-auth "SELECT * FROM users WHERE email='user@example.com'"
+```
+
+## 📋 常见使用场景
+
+### 场景 1：验证新功能
+
+**步骤**：
+1. 创建数据后查询：`/query-db commerce-backend "SELECT * FROM products WHERE title='新商品'"`
+2. 检查关联数据：`/query-db commerce-backend "SELECT * FROM product_variants WHERE product_id=123"`
+
+### 场景 2：数据统计
+
+**步骤**：
+1. 统计总数：`/query-db user-auth "SELECT COUNT(*) FROM users"`
+2. 分组统计：`/query-db commerce-backend "SELECT DATE(created_at), COUNT(*) FROM orders GROUP BY DATE(created_at)"`
+
+### 场景 3：排查问题
+
+**步骤**：
+1. 查找异常数据：`/query-db commerce-backend "SELECT * FROM orders WHERE status IS NULL"`
+2. 检查重复数据：`/query-db user-auth "SELECT email, COUNT(*) FROM users GROUP BY email HAVING COUNT(*) > 1"`
+
+## ⚠️ 安全提示
+
+### 生产环境规则
+
+1. **只读查询**: 只使用 SELECT，不能 INSERT/UPDATE/DELETE
+2. **限制返回**: 使用 LIMIT 限制返回行数
+3. **避免全表**: 使用 WHERE 条件
+4. **不查敏感数据**: 避免查询密码、密钥等
+
+### 安全查询示例
+
+```
+# ✅ 好的查询
+/query-db commerce-backend "SELECT COUNT(*) FROM orders WHERE created_at > NOW() - INTERVAL '1 day'" prod
+/query-db user-auth "SELECT id, email FROM users LIMIT 10" prod
+
+# ❌ 不好的查询
+# /query-db commerce-backend "SELECT * FROM orders" prod  (全表扫描)
+# /query-db user-auth "SELECT password_hash FROM users" prod  (敏感数据)
+```
+
+## 💡 最佳实践
+
+1. **开发用 CI**: 调试和验证优先用 CI 环境
+2. **生产只读**: Prod 环境只查看，不修改
+3. **使用聚合**: COUNT/SUM/AVG 比 SELECT * 更好
+4. **添加限制**: 总是使用 LIMIT
+5. **指定列名**: 避免 SELECT *
+
+## 🌐 环境对比
+
+### CI 环境
+
+```
+/query-db commerce-backend "SELECT COUNT(*) FROM products"
+```
+
+**特点**：
+- 开发环境，可以任意查询和修改
+- 数据可以随时重置
+- 通过 Docker 容器访问
+
+### Stage 环境
+
+```
+/query-db commerce-backend "SELECT COUNT(*) FROM orders" stage
+```
+
+**特点**：
+- 预发布环境
+- 数据接近生产
+- 通过 AWS RDS 访问
+
+### Prod 环境
+
+```
+/query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY status" prod
+```
+
+**特点**：
+- 生产环境，只读访问
+- 真实用户数据
+- ⚠️ 谨慎使用
+
+## 🔗 相关命令
+
+- `/query-db` - 查询数据库（详细使用方法请查看 `/query-db --help`）

package/README.md

@@ -12,30 +12,7 @@ npm install -g @optima-chat/dev-skills@latest
 
 安装后会自动将 skills 复制到 `~/.claude/` 目录。
 
-### 方式 2：验证安装
-
-```bash
-# 查看版本
-optima-dev-skills --version
-
-# 查看帮助
-optima-dev-skills --help
-
-# 检查文件
-ls ~/.claude/commands/
-ls ~/.claude/skills/logs/
-```
-
-### 已安装的能力
-
-- ✅ `/logs` 命令 - 查看 Stage/Prod 环境日志
-- ✅ `logs` skill - 自动识别日志查看需求
-
-### 更新
-
-```bash
-npm update -g @optima-chat/dev-skills@latest
-```
+安装后，`/logs` 命令和 `logs` skill 会自动可用。
 
 ## 🎯 核心理念
 
@@ -46,11 +23,12 @@ Optima Dev Skills 让 Claude Code 能够直接在 **CI、Stage、Prod** 三个
 - **任务驱动** - 基于具体任务场景（查看日志、调用 API），不是抽象分类
 - **跨环境协作** - 统一的命令在 CI、Stage、Prod 三个环境中使用
 
-## 📋 任务场景（1 个）
+## 📋 任务场景（2 个）
 
 当 Claude Code 识别到以下任务时，会自动加载对应的 Skill：
 
 - **logs** - 查看 CI/Stage/Prod 的服务器日志
+- **query-db** - 查询 CI/Stage/Prod 的数据库
 
 ## 👤 用户故事
 
@@ -92,12 +70,13 @@ Claude:
 
 | 命令 | 说明 | 示例 | 跨环境 |
 |------|------|------|--------|
-| `/logs` | 查看服务日志 | `/logs commerce-backend 100 stage` | ✅ |
+| `/logs` | 查看服务日志 | `/logs commerce-backend 100` | ✅ |
+| `/query-db` | 查询数据库 | `/query-db user-auth "SELECT COUNT(*) FROM users"` | ✅ |
 
 **说明**：
 - 命令支持 CI、Stage、Prod 三个环境
-- Claude Code 会根据上下文自动选择环境
-- 命令提供信息和入口，具体操作由 Claude Code 智能完成
+- 默认使用 CI 环境，适合日常开发
+- Claude Code 会根据上下文自动选择环境和执行方式
 
 ## 🏗️ 项目结构
 
@@ -105,10 +84,13 @@ Claude:
 optima-dev-skills/
 ├── .claude/
 │   ├── commands/
-│   │   └── logs.md              # /logs - 查看服务日志
+│   │   ├── logs.md              # /logs - 查看服务日志
+│   │   └── query-db.md          # /query-db - 查询数据库
 │   │
 │   └── skills/
-│       └── logs/                # 日志查看 skill
+│       ├── logs/                # 日志查看 skill
+│       │   └── SKILL.md
+│       └── query-db/            # 数据库查询 skill
 │           └── SKILL.md
 │
 └── docs/
@@ -180,14 +162,15 @@ Claude:
 
 ## 🛠️ 开发状态
 
-**当前版本**: 0.2.0
+**当前版本**: 0.3.0
 
 **已完成**:
-- ✅ 1 个跨环境命令：`/logs`
-- ✅ 1 个任务场景：`logs` skill
+- ✅ 2 个跨环境命令：`/logs`、`/query-db`
+- ✅ 2 个任务场景：`logs` skill、`query-db` skill
 - ✅ 支持 CI、Stage、Prod 三个环境
-- ✅ CI 环境通过 SSH + Docker Compose 访问
-- ✅ Stage/Prod 通过 AWS CloudWatch Logs 访问
+- ✅ CI 环境通过 SSH + Docker 访问
+- ✅ Stage/Prod 通过 AWS 服务访问
+- ✅ 数据库查询支持只读模式（Prod）
 
 **设计原则**:
 - 命令提供信息（URL、路径、凭证位置），不实现复杂逻辑

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {

package/scripts/install.js

@@ -7,7 +7,8 @@ const os = require('os');
 const CLAUDE_DIR = path.join(os.homedir(), '.claude');
 const SKILLS_SOURCE = path.join(__dirname, '..', '.claude');
 const COMMANDS_DEST = path.join(CLAUDE_DIR, 'commands');
-const SKILLS_DEST = path.join(CLAUDE_DIR, 'skills', 'logs');
+const LOGS_SKILL_DEST = path.join(CLAUDE_DIR, 'skills', 'logs');
+const QUERY_DB_SKILL_DEST = path.join(CLAUDE_DIR, 'skills', 'query-db');
 
 // 颜色输出
 const colors = {
@@ -50,34 +51,47 @@ function install() {
   }
 
   // 安装命令
-  const commandsSource = path.join(SKILLS_SOURCE, 'commands', 'logs.md');
-  const commandsDest = path.join(COMMANDS_DEST, 'logs.md');
-  if (fs.existsSync(commandsSource)) {
-    if (!fs.existsSync(COMMANDS_DEST)) {
-      fs.mkdirSync(COMMANDS_DEST, { recursive: true });
-    }
-    fs.copyFileSync(commandsSource, commandsDest);
-    log(`✓ Installed /logs command to ${commandsDest}`, 'green');
-  } else {
-    log(`✗ Commands not found at ${commandsSource}`, 'red');
+  if (!fs.existsSync(COMMANDS_DEST)) {
+    fs.mkdirSync(COMMANDS_DEST, { recursive: true });
   }
 
-  // 安装 skills
-  const skillsSource = path.join(SKILLS_SOURCE, 'skills', 'logs');
-  if (fs.existsSync(skillsSource)) {
-    copyRecursive(skillsSource, SKILLS_DEST);
-    log(`✓ Installed logs skill to ${SKILLS_DEST}`, 'green');
-  } else {
-    log(`✗ Skills not found at ${skillsSource}`, 'red');
+  // 安装 /logs 命令
+  const logsCommandSource = path.join(SKILLS_SOURCE, 'commands', 'logs.md');
+  const logsCommandDest = path.join(COMMANDS_DEST, 'logs.md');
+  if (fs.existsSync(logsCommandSource)) {
+    fs.copyFileSync(logsCommandSource, logsCommandDest);
+    log(`✓ Installed /logs command`, 'green');
+  }
+
+  // 安装 /query-db 命令
+  const queryDbCommandSource = path.join(SKILLS_SOURCE, 'commands', 'query-db.md');
+  const queryDbCommandDest = path.join(COMMANDS_DEST, 'query-db.md');
+  if (fs.existsSync(queryDbCommandSource)) {
+    fs.copyFileSync(queryDbCommandSource, queryDbCommandDest);
+    log(`✓ Installed /query-db command`, 'green');
+  }
+
+  // 安装 logs skill
+  const logsSkillSource = path.join(SKILLS_SOURCE, 'skills', 'logs');
+  if (fs.existsSync(logsSkillSource)) {
+    copyRecursive(logsSkillSource, LOGS_SKILL_DEST);
+    log(`✓ Installed logs skill`, 'green');
+  }
+
+  // 安装 query-db skill
+  const queryDbSkillSource = path.join(SKILLS_SOURCE, 'skills', 'query-db');
+  if (fs.existsSync(queryDbSkillSource)) {
+    copyRecursive(queryDbSkillSource, QUERY_DB_SKILL_DEST);
+    log(`✓ Installed query-db skill`, 'green');
   }
 
   log('\n✨ Installation complete!\n', 'green');
   log('Available commands:', 'blue');
   log('  /logs <service> [lines] [environment]', 'yellow');
+  log('  /query-db <service> <sql> [environment]', 'yellow');
   log('\nExamples:', 'blue');
-  log('  /logs commerce-backend              # Stage, 50 lines', 'yellow');
-  log('  /logs user-auth 100                 # Stage, 100 lines', 'yellow');
-  log('  /logs mcp-host 200 prod             # Prod, 200 lines', 'yellow');
+  log('  /logs commerce-backend                                    # CI logs', 'yellow');
+  log('  /query-db commerce-backend "SELECT COUNT(*) FROM orders"  # CI query', 'yellow');
   log('\nDocumentation: https://github.com/Optima-Chat/optima-dev-skills\n', 'blue');
 }