@optima-chat/dev-skills 0.7.5 → 0.7.6

package/.claude/commands/logs.md

@@ -2,7 +2,7 @@
 
 快速查看服务日志，支持 CI/Stage/Prod 三个环境。
 
-**版本**: v0.2.0
+**版本**: v0.3.0
 
 ## 使用场景
 
@@ -19,25 +19,32 @@
 ## 参数
 
 - `service` (必需): 服务名称
-  - `commerce-backend` - 电商后端
-  - `user-auth` - 用户认证
-  - `mcp-host` - MCP 协调器
+  - `commerce-backend` - 电商后端 API
+  - `user-auth` - 用户认证服务
+  - `user-auth-admin` - 用户认证管理后台
   - `agentic-chat` - AI 聊天服务
-  - `commerce-mcp` - 电商 MCP 服务
-  - `comfy-mcp` - ComfyUI MCP 服务
+  - `bi-backend` - BI 后端
+  - `bi-dashboard` - BI 仪表板
+  - `session-gateway` - AI Shell 网关
+  - `ai-shell-web-ui` - Shell Web UI
+  - `optima-scout` - 产品研究工具
+  - `optima-store` - 商城前端（仅 Stage）
+  - `commerce-rq-worker` - RQ 后台任务
+  - `commerce-rq-scheduler` - RQ 定时调度
 - `lines` (可选): 显示行数，默认 50
 - `environment` (可选): 环境，默认 ci
   - `ci` - CI 持续集成环境（开发环境，默认）
-  - `stage` - Stage 预发布环境
-  - `prod` - 生产环境
+  - `stage` - Stage 预发布环境（ECS Fargate）
+  - `prod` - 生产环境（ECS Fargate）
 
 ## 示例
 
 ```bash
 /logs commerce-backend           # 查看 CI 环境最近 50 行（默认）
 /logs user-auth 100              # 查看 CI 环境最近 100 行（默认）
-/logs mcp-host 200 stage         # 查看 Stage 环境最近 200 行
+/logs agentic-chat 200 stage     # 查看 Stage 环境最近 200 行
 /logs user-auth 100 prod         # 查看 Prod 环境最近 100 行
+/logs session-gateway 50 prod    # 查看 Prod AI Shell 网关日志
 ```
 
 ## 特殊参数处理
@@ -49,7 +56,7 @@
 **重要提示**：根据用户指定的 `environment` 参数选择执行方式：
 - `ci` 或未指定 → 使用 SSH + Docker Compose（第 0 节，默认）
 - `stage` → 使用 AWS CloudWatch Logs - ECS（第 1 节）
-- `prod` → 使用 AWS CloudWatch Logs - EC2（第 2 节）
+- `prod` → 使用 AWS CloudWatch Logs - ECS（第 2 节）
 
 ### 0. CI 环境（environment = "ci" 或默认）
 
@@ -71,10 +78,7 @@ sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST}
 **服务映射**（路径 + docker compose 服务名）:
 - `commerce-backend` → `/data/xuhao/commerce-backend` → `commerce-backend`
 - `user-auth` → `/data/xuhao/user-auth` → `user-auth`
-- `mcp-host` → `/data/xuhao/mcp-host` → `app`
 - `agentic-chat` → `/data/xuhao/agentic-chat` → `optima-ai-chat`
-- `commerce-mcp` → `/data/xuhao/actions-runner/_work/commerce-mcp/commerce-mcp` → `commerce-mcp`
-- `comfy-mcp` → `/data/xuhao/actions-runner/_work/comfy-mcp/comfy-mcp` → `comfy-mcp`
 
 **完整命令示例**（先获取配置）:
 ```bash
@@ -89,21 +93,13 @@ sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST}
 # user-auth
 sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "cd /data/xuhao/user-auth && docker compose logs --tail 50 user-auth"
 
-# mcp-host
-sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "cd /data/xuhao/mcp-host && docker compose logs --tail 50 app"
-
 # agentic-chat
 sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "cd /data/xuhao/agentic-chat && docker compose logs --tail 50 optima-ai-chat"
-
-# commerce-mcp (via actions-runner)
-sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "cd /data/xuhao/actions-runner/_work/commerce-mcp/commerce-mcp && docker compose logs --tail 50 commerce-mcp"
-
-# comfy-mcp (via actions-runner)
-sshpass -p "$CI_PASSWORD" ssh -o StrictHostKeyChecking=no ${CI_USER}@${CI_HOST} "cd /data/xuhao/actions-runner/_work/comfy-mcp/comfy-mcp && docker compose logs --tail 50 comfy-mcp"
 ```
 
 ### 1. Stage 环境（environment = "stage"）
 
+**部署方式**: ECS Fargate（Fargate Spot 降低成本）
 **日志路径格式**: `/ecs/{service}-stage`
 
 **步骤**:
@@ -120,54 +116,56 @@ aws logs get-log-events --log-group-name /ecs/commerce-backend-stage --log-strea
 **服务映射**:
 - `commerce-backend` → `/ecs/commerce-backend-stage`
 - `user-auth` → `/ecs/user-auth-stage`
-- `mcp-host` → `/ecs/mcp-host-stage`
+- `user-auth-admin` → `/ecs/user-auth-admin-stage`
 - `agentic-chat` → `/ecs/agentic-chat-stage`
-- `commerce-mcp` → `/ecs/commerce-mcp-stage`
-- `comfy-mcp` → `/ecs/comfy-mcp-stage`
+- `bi-backend` → `/ecs/bi-backend-stage`
+- `bi-dashboard` → `/ecs/bi-dashboard-stage`
+- `session-gateway` → `/ecs/session-gateway-stage`
+- `ai-shell-web-ui` → `/ecs/ai-shell-web-ui-stage`
+- `optima-scout` → `/ecs/optima-scout-stage`
+- `optima-store` → `/ecs/optima-store-stage`
+- `commerce-rq-worker` → `/ecs/commerce-rq-worker-stage`
+- `commerce-rq-scheduler` → `/ecs/commerce-rq-scheduler-stage`
 
 ### 2. Prod 环境（environment = "prod"）
 
-**日志路径格式**: `/optima/prod/{service}` 或 `/optima/prod/ec2-1az/{service}`
+**部署方式**: ECS Fargate（核心服务标准 Fargate，非核心服务 Fargate Spot）
+**日志路径格式**: `/ecs/{service}-prod`
 
 **IMPORTANT**: Prod 环境必须指定 `--region ap-southeast-1`
 
 **推荐方式（使用 aws logs tail）**:
 ```bash
-# 查看最近 1 小时的日志
-aws logs tail /optima/prod/commerce-backend --since 1h --region ap-southeast-1
+# 查看最近日志（实时跟踪）
+aws logs tail /ecs/commerce-backend-prod --since 1h --region ap-southeast-1
 
-# 查看 MCP 服务日志（ec2-1az 路径）
-aws logs tail /optima/prod/ec2-1az/commerce-mcp --since 1h --region ap-southeast-1
+# 过滤错误日志
+aws logs tail /ecs/user-auth-prod --filter-pattern "ERROR" --region ap-southeast-1
 ```
 
 **备用方式（使用 get-log-events）**:
 ```bash
-# 获取日志内容（纯文本）
-# IMPORTANT: 必须使用单行命令，不要使用反斜杠换行
-aws logs get-log-events --log-group-name /optima/prod/commerce-backend --log-stream-name backend --limit 50 --no-start-from-head --region ap-southeast-1 | jq -r '.events[] | .message'
+# 1. 获取最新的 log stream（ECS Task ID 是动态的）
+STREAM=$(aws logs describe-log-streams --log-group-name /ecs/commerce-backend-prod --order-by LastEventTime --descending --max-items 1 --region ap-southeast-1 | jq -r '.logStreams[0].logStreamName')
+
+# 2. 获取日志内容（纯文本）
+aws logs get-log-events --log-group-name /ecs/commerce-backend-prod --log-stream-name "$STREAM" --limit 50 --region ap-southeast-1 | jq -r '.events[] | .message'
 ```
 
 **服务映射**:
-- `commerce-backend` → `/optima/prod/commerce-backend`
-- `user-auth` → `/optima/prod/user-auth`
-- `mcp-host` → `/optima/prod/mcp-host`
-- `agentic-chat` → `/optima/prod/agentic-chat`
-- `commerce-mcp` → `/optima/prod/ec2-1az/commerce-mcp`
-- `comfy-mcp` → `/optima/prod/ec2-1az/comfy-mcp`
-- `fetch-mcp` → `/optima/prod/ec2-1az/fetch-mcp`
-- `shopify-mcp` → `/optima/prod/ec2-1az/shopify-mcp`
-- `perplexity-mcp` → `/optima/prod/ec2-1az/perplexity-mcp`
-- `google-ads-mcp` → `/optima/prod/ec2-1az/google-ads-mcp`
-
-**Log Stream 名称**:
-- `backend` - 主服务日志
-- `rq-worker` - 后台任务日志
-- `rq-scheduler` - 调度器日志
-
-**注意**:
-- MCP 服务部署在 EC2 (ec2-1az)，日志路径为 `/optima/prod/ec2-1az/{service}`
-- 核心服务（commerce-backend、user-auth 等）日志路径为 `/optima/prod/{service}`
-- **必须指定 `--region ap-southeast-1`**
+- `commerce-backend` → `/ecs/commerce-backend-prod`
+- `user-auth` → `/ecs/user-auth-prod`
+- `user-auth-admin` → `/ecs/user-auth-admin-prod`
+- `agentic-chat` → `/ecs/agentic-chat-prod`
+- `bi-backend` → `/ecs/bi-backend-prod`
+- `bi-dashboard` → `/ecs/bi-dashboard-prod`
+- `session-gateway` → `/ecs/session-gateway-prod`
+- `ai-shell-web-ui` → `/ecs/ai-shell-web-ui-prod`
+- `optima-scout` → `/ecs/optima-scout-prod`
+- `commerce-rq-worker` → `/ecs/commerce-rq-worker-prod`
+- `commerce-rq-scheduler` → `/ecs/commerce-rq-scheduler-prod`
+
+**注意**: `optima-store` 仅在 Stage 环境部署
 
 ## 完整示例脚本
 
@@ -185,14 +183,13 @@ aws logs get-log-events --log-group-name /ecs/${SERVICE}-stage --log-stream-name
 ### Prod 环境
 ```bash
 # 推荐方式：使用 aws logs tail
-# 核心服务
-aws logs tail /optima/prod/commerce-backend --since 1h --region ap-southeast-1
-
-# MCP 服务（ec2-1az 路径）
-aws logs tail /optima/prod/ec2-1az/commerce-mcp --since 1h --region ap-southeast-1
+aws logs tail /ecs/commerce-backend-prod --since 1h --region ap-southeast-1
 
-# 备用方式：使用 get-log-events
-aws logs get-log-events --log-group-name /optima/prod/commerce-backend --log-stream-name backend --limit 50 --no-start-from-head --region ap-southeast-1 | jq -r '.events[] | .message'
+# 备用方式：使用 get-log-events（获取指定行数）
+SERVICE="commerce-backend"
+LINES=50
+STREAM=$(aws logs describe-log-streams --log-group-name /ecs/${SERVICE}-prod --order-by LastEventTime --descending --max-items 1 --region ap-southeast-1 | jq -r '.logStreams[0].logStreamName')
+aws logs get-log-events --log-group-name /ecs/${SERVICE}-prod --log-stream-name "$STREAM" --limit $LINES --region ap-southeast-1 | jq -r '.events[] | .message'
 ```
 
 ## 常见错误处理
@@ -204,8 +201,7 @@ aws logs get-log-events --log-group-name /optima/prod/commerce-backend --log-str
 **解决**:
 ```bash
 # 列出所有可用的日志组
-aws logs describe-log-groups --log-group-name-prefix /ecs
-aws logs describe-log-groups --log-group-name-prefix /optima/prod
+aws logs describe-log-groups --log-group-name-prefix /ecs --region ap-southeast-1
 ```
 
 ### 错误：No log streams found
@@ -222,10 +218,10 @@ aws logs describe-log-streams \
 
 ## 注意事项
 
-1. **Stage 环境**: log stream 名称是动态的（ECS Task ID），需要先查询最新的 stream
-2. **Prod 环境**: log stream 通常是固定的 `backend`、`rq-worker` 等
-3. **日志延迟**: CloudWatch Logs 可能有 1-2 秒延迟
-4. **权限要求**: 需要 AWS CLI 配置了正确的凭证和权限
+1. **Stage/Prod 环境**: log stream 名称是动态的（ECS Task ID），需要先查询最新的 stream
+2. **日志延迟**: CloudWatch Logs 可能有 1-2 秒延迟
+3. **权限要求**: 需要 AWS CLI 配置了正确的凭证和权限
+4. **日志保留**: Stage 和 Prod 环境日志保留 7 天
 
 ## 相关资源
 

package/.claude/settings.local.json

@@ -0,0 +1,41 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:code.claude.com)",
+      "WebFetch(domain:platform.claude.com)",
+      "WebFetch(domain:github.com)",
+      "Bash(gh repo view:*)",
+      "Bash(gh repo clone:*)",
+      "Bash(gh repo list:*)",
+      "Read(//private/tmp/optima-docs/**)",
+      "Read(//tmp/optima-docs/**)",
+      "Bash(git init:*)",
+      "Bash(gh repo create:*)",
+      "Read(//private/tmp/optima-workspace/**)",
+      "Read(//tmp/optima-workspace/**)",
+      "Read(//tmp/optima-workspace/.claude/commands/**)",
+      "Bash(git add:*)",
+      "Bash(git push:*)",
+      "Bash(find:*)",
+      "Bash(git commit:*)",
+      "Bash(aws logs get-log-events:*)",
+      "Bash(npm install:*)",
+      "Bash(optima-dev-skills:*)",
+      "Bash(optima-generate-test-token:*)",
+      "Bash(optima-query-db:*)",
+      "Bash(gh variable set:*)",
+      "Bash(npm publish:*)",
+      "Bash(python3:*)",
+      "Bash(gh api:*)",
+      "Bash(curl -s http://auth.optima.chat/openapi.json)",
+      "Bash(curl -s https://auth.optima.chat/openapi.json)",
+      "Bash(cat:*)",
+      "Bash(node /Users/verypro/optima-dev-skills/scripts/install.js:*)",
+      "Bash(aws logs tail:*)",
+      "Bash(grep:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.claude/skills/logs/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: "logs"
+description: "当用户请求查看日志、查看服务日志、排查问题、看看日志、检查日志、商品服务日志、后端日志、API日志、正式环境日志、生产环境日志、CI环境日志、开发环境日志时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway 等服务。"
+allowed-tools: ["Bash", "SlashCommand"]
+---
+
+# 查看服务器日志
+
+当你需要查看服务日志排查问题时，使用这个场景。
+
+## 适用情况
+
+- API 返回错误，需要查看详细错误信息
+- 服务行为异常，需要查看运行日志
+- 监控服务状态，查看日志输出
+- 排查数据库连接、配置问题
+
+## 快速操作
+
+### 1. 查看 CI 环境日志（默认）
+
+```
+/logs commerce-backend
+/logs user-auth 100
+```
+
+**说明**：
+- 查看 CI 开发环境（dev.optima.chat）
+- 默认环境，不需要指定 `ci` 参数
+- 通过 SSH + Docker Compose 访问
+- 从 GitHub Variables 获取认证信息
+
+### 2. 查看 Stage 环境日志
+
+```
+/logs commerce-backend 50 stage
+```
+
+**说明**：
+- 查看 Stage 预发布环境
+- 使用 AWS CloudWatch Logs（ECS Fargate）
+
+**常用服务**：
+- `commerce-backend` - 电商 API
+- `user-auth` - 用户认证
+- `agentic-chat` - AI 聊天服务
+- `bi-backend` - BI 后端
+- `session-gateway` - AI Shell 网关
+
+### 3. 查看更多日志行数
+
+```
+/logs commerce-backend 200
+```
+
+查看最近 200 行日志，用于排查历史问题。
+
+### 4. 查看 Prod 环境日志
+
+```
+/logs commerce-backend 100 prod
+```
+
+查看生产环境日志（通过 AWS CloudWatch，ECS Fargate）。
+
+## 常见问题排查
+
+### 问题 1：API 返回 500 错误
+
+**步骤**：
+1. 查看日志：`/logs commerce-backend 100`
+2. 搜索 ERROR 关键字
+3. 查看完整错误堆栈
+4. 定位问题代码或数据
+
+**示例日志**：
+```
+ERROR - 2025-01-23 10:30:45 - Exception in /products endpoint
+Traceback:
+  File "app/routes/products.py", line 45
+    merchant = db.query(Merchant).filter(id == product.merchant_id).first()
+  MerchantNotFound: Merchant with id 'xxx' not found
+```
+
+### 问题 2：服务启动失败
+
+**步骤**：
+1. 查看启动日志：`/logs commerce-backend 200`
+2. 查找启动错误信息
+3. 检查环境变量、数据库连接
+
+**常见错误**：
+- 数据库连接失败
+- Redis 连接失败
+- 环境变量缺失
+
+**示例日志**：
+```
+redis.exceptions.ConnectionError: Error connecting to localhost:8285.
+Multiple exceptions: [Errno 111] Connection refused
+ERROR:    Application startup failed. Exiting.
+```
+
+### 问题 3：性能问题（响应慢）
+
+**步骤**：
+1. 查看日志：`/logs commerce-backend`
+2. 查找 "response_time" 或包含毫秒数的日志
+3. 识别慢查询或慢接口
+
+**示例**：
+```
+INFO - GET /products - response_time: 3500ms (SLOW)
+INFO - Database query took 3200ms: SELECT * FROM products WHERE...
+```
+
+## 日志分析技巧
+
+### 过滤关键信息
+
+查看日志后，可以使用 grep 过滤：
+
+```bash
+# 只看错误
+/logs commerce-backend 200 | grep -i error
+
+# 只看特定 API
+/logs commerce-backend 200 | grep "GET /products"
+
+# 查看 Redis 相关日志
+/logs commerce-backend 200 | grep -i redis
+```
+
+### 日志级别
+
+日志级别说明：
+- **ERROR** - 错误，需要立即处理
+- **WARNING** - 警告，可能有问题
+- **INFO** - 信息，正常运行日志
+- **DEBUG** - 调试信息，详细输出
+
+## 环境对比
+
+### CI 环境
+
+```
+/logs user-auth 100 ci
+```
+
+**特点**：
+- CI 开发环境，适合开发调试
+- 实时性最好
+- 查看 Docker Compose 日志
+
+### Stage 环境
+
+```
+/logs commerce-backend 100 stage
+```
+
+**特点**：
+- 预发布环境
+- AWS ECS Fargate 运行（Fargate Spot）
+- 通过 CloudWatch Logs 查看
+
+### Prod 环境
+
+```
+/logs commerce-backend 100 prod
+```
+
+**特点**：
+- 生产环境
+- AWS ECS Fargate 运行
+- 通过 CloudWatch Logs 查看
+- 日志保留 7 天
+
+## 支持的服务列表
+
+| 服务 | 说明 | CI | Stage | Prod |
+|------|------|:--:|:-----:|:----:|
+| `commerce-backend` | 电商后端 API | ✓ | ✓ | ✓ |
+| `user-auth` | 用户认证服务 | ✓ | ✓ | ✓ |
+| `user-auth-admin` | 认证管理后台 | - | ✓ | ✓ |
+| `agentic-chat` | AI 聊天服务 | ✓ | ✓ | ✓ |
+| `bi-backend` | BI 后端 | - | ✓ | ✓ |
+| `bi-dashboard` | BI 仪表板 | - | ✓ | ✓ |
+| `session-gateway` | AI Shell 网关 | - | ✓ | ✓ |
+| `ai-shell-web-ui` | Shell Web UI | - | ✓ | ✓ |
+| `optima-scout` | 产品研究工具 | - | ✓ | ✓ |
+| `optima-store` | 商城前端 | - | ✓ | - |
+| `commerce-rq-worker` | RQ 后台任务 | - | ✓ | ✓ |
+| `commerce-rq-scheduler` | RQ 定时调度 | - | ✓ | ✓ |
+
+## 最佳实践
+
+1. **先查日志，再动手修** - 不要猜测，看日志确认问题
+2. **查足够多的行数** - 有时错误原因在更早的日志里
+3. **关注启动日志** - 服务启动时的错误最关键
+4. **保留错误日志** - 复制错误信息，方便分享讨论
+5. **对比环境差异** - Stage 出错、Prod 正常？对比日志差异
+
+## 相关命令
+
+- `/logs` - 查看服务日志（详细使用方法和技术细节请查看 `/logs --help`）

package/package.json

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