ai-engineering-init 1.6.0 → 1.8.0

package/.cursor/skills/loki-log-query/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: loki-log-query
+description: |
+  通过 Grafana Loki 查询线上日志，支持多环境切换、traceId 链路追踪、接口路径查询、关键词搜索。
+
+  触发场景：
+  - 需要查看线上日志排查问题
+  - 通过 traceId 查询完整请求链路
+  - 通过接口路径查询该接口的所有日志
+  - 搜索特定错误日志或异常堆栈
+  - 切换不同日志服务环境
+
+  触发词：查日志、traceId、链路追踪、Loki、日志查询、线上日志、生产日志、错误日志、异常堆栈、日志排查、切换环境、monitor
+---
+
+# Loki 日志查询技能
+
+## 概述
+
+通过 Grafana Loki API 查询线上日志。支持：
+1. **多环境管理**：5 个 Grafana 日志服务，按需切换
+2. **traceId 查询**：通过日志ID获取完整请求链路
+3. **接口路径查询**：通过 API 接口路径查询相关日志
+4. **关键词搜索**：错误信息、类名、自定义关键词
+
+## 多环境配置
+
+配置文件：`.claude/skills/loki-log-query/environments.json`
+
+### 环境列表
+
+| 环境别名 | 名称 | URL | 快捷词 |
+|----------|------|-----|--------|
+| `test13` | 测试13（主测试环境） | `https://test13.xnzn.net/grafana` | test13, 13 |
+| `monitor-test` | Monitor 测试环境 | `https://monitor-test.xnzn.net/grafana` | mtest |
+| `monitor-dev` | Monitor 开发环境 | `https://monitor-dev.xnzn.net/grafana` | mdev, dev |
+| `monitor02-dev` | Monitor02 开发环境 | `https://monitor02-dev.xnzn.net/grafana` | m02, monitor02 |
+| `monitor-tyy-dev` | Monitor 体验园开发环境 | `https://monitor-tyy-dev.xnzn.net/grafana` | tyy, 体验园 |
+
+### 环境匹配规则
+
+用户说的话 → 匹配环境：
+- "查 test13 的日志" → `test13`
+- "去 monitor-dev 查" → `monitor-dev`
+- "切到体验园" → `monitor-tyy-dev`
+- "去 m02 查一下" → `monitor02-dev`
+- 未指定环境 → 使用 `active` 字段指定的默认环境
+
+### 读取配置
+
+```bash
+SKILL_DIR="$CLAUDE_PROJECT_DIR/.claude/skills/loki-log-query"
+ENV_FILE="${SKILL_DIR}/environments.json"
+
+# 读取指定环境（参数: 环境别名）
+read_env() {
+  local ENV_KEY="${1:-$(python3 -c "import json; print(json.load(open('${ENV_FILE}'))['active'])")}"
+  GRAFANA_URL=$(python3 -c "import json; print(json.load(open('${ENV_FILE}'))['environments']['${ENV_KEY}']['url'])")
+  TOKEN=$(python3 -c "import json; print(json.load(open('${ENV_FILE}'))['environments']['${ENV_KEY}']['token'])")
+  API="${GRAFANA_URL}/api/datasources/proxy/uid/loki/loki/api/v1"
+  echo "Environment: ${ENV_KEY} → ${GRAFANA_URL}"
+}
+
+# 通过别名查找环境 key
+find_env() {
+  python3 -c "
+import json
+data = json.load(open('${ENV_FILE}'))
+alias = '${1}'.lower()
+for key, env in data['environments'].items():
+    if alias == key or alias in env.get('aliases', []):
+        print(key)
+        break
+else:
+    print(data['active'])
+"
+}
+```
+
+### 切换活跃环境
+
+```bash
+# 切换默认环境为 monitor-dev
+python3 -c "
+import json
+data = json.load(open('${ENV_FILE}'))
+data['active'] = 'monitor-dev'
+json.dump(data, open('${ENV_FILE}', 'w'), indent=2, ensure_ascii=False)
+print('Switched to:', data['active'])
+"
+```
+
+### 更新 Token
+
+```bash
+# 为某个环境设置 Token
+python3 -c "
+import json
+data = json.load(open('${ENV_FILE}'))
+data['environments']['monitor-dev']['token'] = 'glsa_新的token值'
+json.dump(data, open('${ENV_FILE}', 'w'), indent=2, ensure_ascii=False)
+print('Token updated for monitor-dev')
+"
+```
+
+## API 基础
+
+| 项目 | 值 |
+|------|-----|
+| 数据源 | Loki（uid: `loki`） |
+| **API 路径** | `{GRAFANA_URL}/api/datasources/proxy/uid/loki/loki/api/v1/query_range` |
+| 认证 | `Authorization: Bearer {TOKEN}` |
+| 默认标签 | `app="yunshitang"` |
+
+> **重要**：Loki API 必须通过 Grafana datasource proxy 访问，直接 `/loki/api/v1/` 会返回 404。
+> 查询时不限 project 标签（`{app="yunshitang"}`），可覆盖该 Grafana 下所有环境。
+
+## 日志格式
+
+```
+2026-03-07 09:16:53.039,bcf6d955-fa26-45a5-9628-748f7ac4eed2,,,  INFO 1 --- [线程名] 类名 : 行号 : 消息内容
+```
+
+| 位置 | 字段 | 示例 |
+|------|------|------|
+| 第1段 | 时间戳 | `2026-03-07 09:16:53.039` |
+| 第2段 | traceId | `bcf6d955-fa26-45a5-9628-748f7ac4eed2` 或 `a53dd0b0cc62bf4a79a63e77444f6f3f` |
+| 第3段 | 商户ID | `553722740746489856` |
+| 第4段 | 用户ID | `553723188689768448` |
+| 第5段 | 日志内容 | `INFO 1 --- [thread] Class : 123 : msg` |
+
+> traceId 可能是 UUID 格式（带横线）或 32位hex（不带横线），都支持。
+
+## 查询场景
+
+### 场景 1：按 traceId 查完整链路（最常用）
+
+用户说："用 `a53dd0b0cc62bf4a79a63e77444f6f3f` 查日志"
+
+```bash
+TRACE_ID="a53dd0b0cc62bf4a79a63e77444f6f3f"
+END=$(date +%s)000000000
+START=$(( $(date +%s) - 86400 ))000000000
+
+curl -s "${API}/query_range" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  --data-urlencode "query={app=\"yunshitang\"} |= \"${TRACE_ID}\"" \
+  --data-urlencode "start=${START}" \
+  --data-urlencode "end=${END}" \
+  --data-urlencode "limit=500" \
+  --data-urlencode "direction=forward" \
+  | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+if data.get('status') == 'success':
+    for stream in data['data']['result']:
+        labels = stream.get('stream', {})
+        print(f'--- {labels.get(\"app\",\"?\")}/{labels.get(\"project\",\"?\")} ---')
+        for ts, line in stream['values']:
+            print(line)
+else:
+    print('Error:', data)
+"
+```
+
+### 场景 2：按接口路径查日志
+
+用户说："查 `/security/summary/order/mealtime/classify/page` 这个接口的日志"
+
+接口路径出现在请求日志的 `RequestLoggingFilter` 中（`>>> POST /xxx` 或 `>>> GET /xxx`）。
+
+```bash
+API_PATH="/security/summary/order/mealtime/classify/page"
+END=$(date +%s)000000000
+START=$(( $(date +%s) - 3600 ))000000000  # 最近1小时
+
+curl -s "${API}/query_range" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  --data-urlencode "query={app=\"yunshitang\"} |= \"${API_PATH}\"" \
+  --data-urlencode "start=${START}" \
+  --data-urlencode "end=${END}" \
+  --data-urlencode "limit=200" \
+  --data-urlencode "direction=forward" \
+  | python3 -c "
+import sys, json, re
+data = json.load(sys.stdin)
+if data.get('status') != 'success':
+    print('Error:', data); sys.exit()
+
+# 从匹配的请求日志中提取 traceId
+trace_ids = set()
+all_lines = []
+for stream in data['data']['result']:
+    for ts, line in stream['values']:
+        all_lines.append(line)
+        # 提取 traceId（第2个逗号分隔字段）
+        parts = line.split(',')
+        if len(parts) >= 2:
+            tid = parts[1].strip()
+            if len(tid) >= 32:
+                trace_ids.add(tid)
+
+print(f'Found {len(all_lines)} lines, {len(trace_ids)} unique traceIds')
+print()
+for tid in list(trace_ids)[:10]:
+    print(f'  traceId: {tid}')
+print()
+for line in all_lines[:30]:
+    print(line)
+if len(all_lines) > 30:
+    print(f'... and {len(all_lines)-30} more lines')
+"
+```
+
+**进阶**：找到 traceId 后，再用场景 1 查该 traceId 的完整链路。
+
+### 场景 3：关键词搜索
+
+用户说："搜一下 LeException" 或 "查 ERROR 日志"
+
+```bash
+KEYWORD="LeException"
+END=$(date +%s)000000000
+START=$(( $(date +%s) - 3600 ))000000000
+
+curl -s "${API}/query_range" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  --data-urlencode "query={app=\"yunshitang\"} |= \"${KEYWORD}\"" \
+  --data-urlencode "start=${START}" \
+  --data-urlencode "end=${END}" \
+  --data-urlencode "limit=100" \
+  --data-urlencode "direction=backward"
+```
+
+**常用关键词组合**：
+
+```logql
+# 所有 ERROR 日志
+{app="yunshitang"} |= "ERROR"
+
+# 业务异常
+{app="yunshitang"} |= "LeException"
+
+# SQL 错误
+{app="yunshitang"} |~ "SQLSyntaxError|DataAccessException|BadSqlGrammar"
+
+# 空指针
+{app="yunshitang"} |= "NullPointerException"
+
+# 按类名搜索
+{app="yunshitang"} |= "OrderInfoService"
+
+# 组合：ERROR + 特定类
+{app="yunshitang"} |= "ERROR" |= "OrderInfoService"
+
+# 排除健康检查噪音
+{app="yunshitang"} |= "ERROR" != "health" != "actuator"
+```
+
+### 场景 4：按接口查完整链路（组合查询）
+
+用户说："查 `/api/v2/web/order/list` 接口的全链路日志"
+
+**两步走**：
+1. 先按接口路径搜索，拿到 traceId
+2. 再按 traceId 查完整链路
+
+```bash
+# Step 1: 找 traceId
+API_PATH="/api/v2/web/order/list"
+END=$(date +%s)000000000
+START=$(( $(date +%s) - 3600 ))000000000
+
+TRACE_IDS=$(curl -s "${API}/query_range" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  --data-urlencode "query={app=\"yunshitang\"} |= \"${API_PATH}\" |= \">>>\"" \
+  --data-urlencode "start=${START}" \
+  --data-urlencode "end=${END}" \
+  --data-urlencode "limit=10" \
+  --data-urlencode "direction=backward" \
+  | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for stream in data.get('data',{}).get('result',[]):
+    for ts, line in stream['values']:
+        parts = line.split(',')
+        if len(parts) >= 2 and len(parts[1].strip()) >= 32:
+            print(parts[1].strip())
+")
+
+echo "Found traceIds:"
+echo "${TRACE_IDS}" | head -5
+
+# Step 2: 用第一个 traceId 查完整链路
+FIRST_TID=$(echo "${TRACE_IDS}" | head -1)
+if [ -n "${FIRST_TID}" ]; then
+  curl -s "${API}/query_range" \
+    -H "Authorization: Bearer ${TOKEN}" \
+    --data-urlencode "query={app=\"yunshitang\"} |= \"${FIRST_TID}\"" \
+    --data-urlencode "start=${START}" \
+    --data-urlencode "end=${END}" \
+    --data-urlencode "limit=500" \
+    --data-urlencode "direction=forward" \
+    | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for stream in data.get('data',{}).get('result',[]):
+    for ts, line in stream['values']:
+        print(line)
+"
+fi
+```
+
+### 场景 5：指定 project 环境查询
+
+如果用户指定了具体的 project（如 test20）：
+
+```logql
+{app="yunshitang",project="test20"} |= "traceId值"
+```
+
+## LogQL 语法速查
+
+### 流选择器
+
+| 操作 | 语法 | 示例 |
+|------|------|------|
+| 精确匹配 | `=` | `{app="yunshitang"}` |
+| 不等于 | `!=` | `{app!="test"}` |
+| 正则匹配 | `=~` | `{project=~"test2.*"}` |
+
+### 行过滤
+
+| 操作 | 语法 | 示例 |
+|------|------|------|
+| 包含 | `\|=` | `\|= "ERROR"` |
+| 不包含 | `!=` | `!= "DEBUG"` |
+| 正则匹配 | `\|~` | `\|~ "Exception\|Error"` |
+| 正则排除 | `!~` | `!~ "health\|ping"` |
+
+### 查看可用标签值
+
+```bash
+# 列出所有 project
+curl -s "${API}/label/project/values" -H "Authorization: Bearer ${TOKEN}"
+
+# 列出所有 app
+curl -s "${API}/label/app/values" -H "Authorization: Bearer ${TOKEN}"
+```
+
+## Bug 修复工作流
+
+```
+1. 获取线索（traceId / 接口路径 / 错误关键词）
+   ↓
+2. 确定环境（哪个 Grafana？读取 environments.json）
+   ↓
+3. 查询日志（场景 1-4 选择合适的查询方式）
+   ↓
+4. 分析日志（ERROR/异常堆栈/SQL 错误/耗时）
+   ↓
+5. 定位代码（类名:行号 → 项目搜索）
+   ↓
+6. 修复 + 更新云效任务状态
+```
+
+### 日志分析重点
+
+1. **ERROR 级别日志** — 异常根因
+2. **异常堆栈** — `at net.xnzn.core.xxx` 开头的行
+3. **SQL 错误** — `SQLSyntaxErrorException`、`DataAccessException`
+4. **业务异常** — `LeException` 抛出的位置
+5. **耗时** — `Completed xxx in Nms`，识别慢请求
+6. **请求/响应** — `RequestLoggingFilter` 的 `>>>` 和 `<<<` 日志
+
+### 联动技能
+
+| 场景 | 联动技能 |
+|------|---------|
+| 排查 Bug | `bug-detective` |
+| 查询云效任务 | `yunxiao-task-management` |
+| 查数据库 | `mysql-debug` |
+| 性能问题 | `performance-doctor` |
+
+## Grafana Service Account Token 创建
+
+每个 Grafana 环境需要独立创建 Token：
+
+1. 登录对应 Grafana URL
+2. 左侧菜单 → Administration → Service accounts
+3. Add service account（名称：`claude-loki-reader`），角色：`Viewer`
+4. Add service account token → 复制
+5. 更新 `environments.json` 中对应环境的 `token` 字段
+
+## 注意
+
+- 如果 Token 为空会报 `invalid API key`，需要先为该环境创建 Token
+- 查询默认不限 project，可覆盖该 Grafana 下所有项目环境
+- `direction=forward` 按时间正序，`direction=backward` 按时间倒序（最新优先）
+- 如果是 Bug 排查完整流程，同时使用 `bug-detective`

package/.cursor/skills/loki-log-query/environments.json

@@ -0,0 +1,45 @@
+{
+  "_comment": "Loki 多环境配置。每个环境需要独立的 Grafana Service Account Token。",
+  "_usage": "用户说'查 test13 的日志'或'去 monitor-dev 查'时，匹配对应环境。",
+  "_setup": "Token 创建：Grafana → Administration → Service accounts → Add（Viewer 角色）→ Add token → 复制到对应环境的 token 字段。",
+
+  "active": "test13",
+
+  "environments": {
+    "test13": {
+      "name": "测试13（主测试环境）",
+      "url": "https://test13.xnzn.net/grafana",
+      "token": "",
+      "aliases": ["test13", "13"],
+      "projects": ["test13", "test14", "test15", "test16", "test17", "test18", "test19", "test20", "test21", "test22", "test23", "test24", "test25", "test26", "test27", "test28", "test31", "ywcs"]
+    },
+    "monitor-test": {
+      "name": "Monitor 测试环境",
+      "url": "https://monitor-test.xnzn.net/grafana",
+      "token": "",
+      "aliases": ["monitor-test", "mtest"],
+      "projects": ["test01", "test02", "test03", "test04", "test05", "test06", "test07", "test08", "test09", "test10", "test11", "test12"]
+    },
+    "monitor-dev": {
+      "name": "Monitor 开发环境",
+      "url": "https://monitor-dev.xnzn.net/grafana",
+      "token": "",
+      "aliases": ["monitor-dev", "mdev", "dev"],
+      "projects": ["dev01", "dev02", "dev03", "dev04", "dev05", "dev06", "dev07", "dev08", "dev09", "dev10", "dev11", "dev12", "dev13", "dev14", "dev15"]
+    },
+    "monitor02-dev": {
+      "name": "Monitor02 开发环境",
+      "url": "https://monitor02-dev.xnzn.net/grafana",
+      "token": "",
+      "aliases": ["monitor02-dev", "m02", "monitor02"],
+      "projects": ["dev16", "dev17", "dev19", "dev21", "dev22", "dev23", "dev24", "dev25", "dev26", "dev28", "dev29", "dev30", "dev31", "dev32", "dev33", "dev34", "dev35", "dev36", "dev37", "dev38", "dev39", "dev40", "dev41", "dev42"]
+    },
+    "monitor-tyy-dev": {
+      "name": "Monitor 体验园开发环境",
+      "url": "https://monitor-tyy-dev.xnzn.net/grafana",
+      "token": "",
+      "aliases": ["monitor-tyy", "tyy", "体验园"],
+      "projects": ["dev44", "dev45", "dev46", "dev47", "dev48", "dev49", "dev50", "dev51", "dev52", "dev53", "dev54", "dev55", "dev56", "dev57", "dev58", "dev60", "dev61", "dev63", "dev64", "grafana"]
+    }
+  }
+}

package/.cursor/skills/mysql-debug/SKILL.md

@@ -27,41 +27,73 @@ description: |
 
 ---
 
-## 首次使用引导（必须执行）
+## 连接信息获取（三级降级，自动查找）
 
-当本技能被激活时，**必须先执行以下两项检查**，任一不通过则输出引导提示并停止查库操作：
+当本技能被激活时，**按以下优先级获取数据库连接信息**：
 
-### 检查 1：配置文件是否就绪
+### 优先级 1：用户对话中指定（最高优先级）
 
-读取 `.claude/mysql-config.json`，确定当前环境（用户指定 或 `default` 字段），检查该环境的 password 是否仍为占位符 `YOUR_PASSWORD`：
+用户直接给出连接信息，或指定环境名：
+- "连 dev 环境查一下" → 使用 `.claude/mysql-config.json` 中 dev 环境的配置
+- 直接给出 host/port/user/password → 直接使用
 
+### 优先级 2：`.claude/mysql-config.json`（显式配置，可选）
+
+如果文件存在且当前环境的 password 不是占位符 `YOUR_PASSWORD`，使用该配置。
+**此文件为可选**，主要用于连接非本地环境（dev/prod 远程数据库）。
+
+### 优先级 3：工程配置文件（零配置，本地开发默认）
+
+从项目的 `bootstrap-dev.yml` 中自动提取连接信息：
+
+**搜索路径**：
 ```
-如果文件不存在 或 当前环境的 password == "YOUR_PASSWORD"：
-  → 输出引导提示（见下方模板），不执行查库
+**/bootstrap-dev.yml
+**/bootstrap*.yml（降级）
 ```
 
-### 检查 2：mysql CLI 是否可用
-
-执行 `which mysql`，检查是否返回有效路径：
+**解析位置**：`spring.dataset.system.master` 节点
 
+**解析规则**：
+```yaml
+# 从以下字段提取：
+jdbcUrl: jdbc:mysql://127.0.0.1:3306/system_xxx
+username: root
+password: xxx
 ```
-如果 mysql 命令不存在：
-  → 输出引导提示（见下方模板），不执行查库
+
+**提取结果**：
+- host = `127.0.0.1`（从 jdbcUrl 解析）
+- port = `3306`（从 jdbcUrl 解析）
+- user = `root`（username 字段）
+- password = `xxx`（password 字段）
+- 注意：jdbcUrl 中的数据库名（`system_xxx`）为系统库，**不作为查询目标数据库**。查询目标数据库 = 租户ID（从日志提取或用户指定）
+
+### mysql CLI 查找（多路径）
+
+按顺序查找 mysql 客户端：
+
+```bash
+which mysql \
+  || ls /usr/local/mysql/bin/mysql \
+  || ls /opt/homebrew/bin/mysql \
+  || ls /opt/homebrew/opt/mysql-client/bin/mysql
 ```
 
-### 引导提示模板
+找到任一即可使用。如果全部不存在，输出安装提示：
+```
+brew install mysql-client
+```
 
-当检查不通过时，输出以下提示：
+### 引导提示（仅当连接信息和 mysql CLI 都无法获取时）
 
 ```
 ⚠️ 数据库查询功能需要先完成配置：
 
-1. 编辑 .claude/mysql-config.json，填入你的 MySQL 连接信息：
-   配置文件支持多环境（local / dev / prod），至少配置一个环境：
-   - host: 数据库地址
-   - port: 端口（默认 3306）
-   - user: 用户名
-   - password: 数据库密码（替换 YOUR_PASSWORD）
+1. 连接信息获取失败：
+   - 未找到 bootstrap-dev.yml 工程配置文件
+   - 未找到 .claude/mysql-config.json 配置文件
+   → 请创建 .claude/mysql-config.json 或确保项目中存在 bootstrap-dev.yml
 
 2. 安装 MySQL 客户端：
    brew install mysql-client
@@ -209,11 +241,15 @@ mysql -h 127.0.0.1 -P 3306 -u root -p'password' 546198574447230976 -e "SELECT ..
 
 ### 连接方式
 
-读取 `.claude/mysql-config.json` 获取 host/port/user/password，数据库名从日志提取或用户指定：
+按"连接信息获取"章节的优先级获取 host/port/user/password，数据库名从日志提取或用户指定：
 
 ```bash
-# 从配置读取连接信息 + 动态数据库名
-mysql -h {host} -P {port} -u {user} -p'{password}' {database_from_log} -e "{SQL}"
+# 连接信息来源：用户指定 > mysql-config.json > bootstrap-dev.yml 自动提取
+# 数据库名来源：用户指定 > 日志提取的租户ID
+mysql -h {host} -P {port} -u {user} -p'{password}' {database_from_log_or_user} -e "{SQL}"
+
+# mysql 路径：如果 which mysql 失败，尝试绝对路径
+/opt/homebrew/opt/mysql-client/bin/mysql -h {host} ...
 ```
 
 ### 常用排查查询模板