ai-engineering-init 1.16.1 → 1.16.3

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

@@ -25,9 +25,35 @@ description: |
 
 ## 多环境配置
 
-配置文件：`.claude/skills/loki-log-query/environments.json`
+### 配置文件查找顺序
 
-### 环境列表
+```
+1. 本地项目：.claude/loki-config.json（新格式）
+2. 本地项目：.claude/skills/loki-log-query/environments.json（旧格式，兼容）
+3. 全局配置：~/.claude/loki-config.json（或 ~/.cursor/loki-config.json）
+```
+
+本地优先。全局配置用 `npx ai-engineering-init config --type loki --scope global` 创建。
+
+### 配置结构（支持 range 范围匹配）
+
+```json
+{
+  "active": "monitor-dev",
+  "environments": {
+    "monitor-dev": {
+      "name": "Monitor 开发环境",
+      "url": "https://monitor-dev.xnzn.net/grafana",
+      "token": "glsa_xxx",
+      "aliases": ["mdev", "dev"],
+      "range": "dev1~15",
+      "projects": ["dev01","dev02","...","dev15"]
+    }
+  }
+}
+```
+
+### 环境列表（默认）
 
 | 环境别名 | 名称 | URL | 快捷词 |
 |----------|------|-----|--------|
@@ -37,31 +63,34 @@ description: |
 | `monitor02-dev` | Monitor02 开发环境 | `https://monitor02-dev.xnzn.net/grafana` | m02, monitor02 |
 | `monitor-tyy-dev` | Monitor 体验园开发环境 | `https://monitor-tyy-dev.xnzn.net/grafana` | tyy, 体验园 |
 
-### 环境匹配规则
+### 环境匹配规则（含 range）
 
-用户说的话 → 匹配环境：
-- "查 test13 的日志" → `test13`
-- "去 monitor-dev 查" → `monitor-dev`
-- "切到体验园" → `monitor-tyy-dev`
-- "去 m02 查一下" → `monitor02-dev`
-- 未指定环境 → 使用 `active` 字段指定的默认环境
+| 用户说法 | 匹配方式 | 结果 |
+|---------|---------|------|
+| "查 test13 的日志" | 精确匹配 key/aliases | `test13` 环境 |
+| "去 dev10 查" | **range 匹配**：dev10 在 monitor-dev 的 projects 中 | `monitor-dev`，`project="dev10"` |
+| "去 monitor-dev 查" | 精确匹配 key | `monitor-dev` 环境 |
+| "切到体验园" | aliases 匹配 | `monitor-tyy-dev` 环境 |
+| 未指定环境 | 使用 `active` 字段 | 默认活跃环境 |
 
-### 读取配置
+### 读取配置（含全局降级 + range 匹配）
 
 ```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}"
+# 按优先级查找配置文件
+find_config() {
+  local PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+  for f in \
+    "${PROJECT_DIR}/.claude/loki-config.json" \
+    "${PROJECT_DIR}/.claude/skills/loki-log-query/environments.json" \
+    "${HOME}/.claude/loki-config.json" \
+    "${HOME}/.cursor/loki-config.json"; do
+    [ -f "$f" ] && echo "$f" && return
+  done
 }
 
-# 通过别名查找环境 key
+ENV_FILE=$(find_config)
+
+# 通过别名或 range 查找环境 key + project
 find_env() {
   python3 -c "
 import json
@@ -69,10 +98,11 @@ 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'])
+        print(f'{key}|'); exit()
+for key, env in data['environments'].items():
+    if alias in env.get('projects', []):
+        print(f'{key}|{alias}'); exit()
+print(f'{data[\"active\"]}|')
 "
 }
 ```

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

@@ -27,22 +27,28 @@ description: |
 
 ---
 
-## 连接信息获取（三级降级，自动查找）
+## 连接信息获取（四级降级，自动查找）
 
 当本技能被激活时，**按以下优先级获取数据库连接信息**：
 
 ### 优先级 1：用户对话中指定（最高优先级）
 
 用户直接给出连接信息，或指定环境名：
-- "连 dev 环境查一下" → 使用 `.claude/mysql-config.json` 中 dev 环境的配置
+- "连 dev 环境查一下" → 使用配置中 dev 环境
+- "去 dev10 查" → **范围匹配** dev 环境（range: "1~15"）
 - 直接给出 host/port/user/password → 直接使用
 
-### 优先级 2：`.claude/mysql-config.json`（显式配置，可选）
+### 优先级 2：本地项目 `.claude/mysql-config.json`
 
-如果文件存在且当前环境的 password 不是占位符 `YOUR_PASSWORD`，使用该配置。
-**此文件为可选**，主要用于连接非本地环境（dev/prod 远程数据库）。
+项目目录下的配置文件，优先于全局配置。
 
-### 优先级 3：工程配置文件（零配置，本地开发默认）
+### 优先级 3：全局配置（所有项目共享）
+
+全局配置文件（通过 `npx ai-engineering-init config --scope global` 创建）。
+查找路径：`~/.claude/mysql-config.json` 或 `~/.cursor/mysql-config.json`（取决于使用的工具）。
+**推荐**：公司统一的数据库连接信息放全局，项目特定的覆盖放本地。
+
+### 优先级 4：工程配置文件（零配置，本地开发默认）
 
 从项目的 `bootstrap-dev.yml` 中自动提取连接信息：
 

package/CLAUDE.md

@@ -219,6 +219,7 @@ CREATE TABLE [表名] (
 | **轻量** | 单表 CRUD、字段增删、简单查询 | `/dev` 或 `/crud` 直接开发 | 无需需求拆解 |
 | **中等** | 2-3 张表联动、跨 Service 调用、状态流转 | `/dev` 开发（可选 OpenSpec） | 建议先理清逻辑再编码 |
 | **复杂** | 多模块协作、复杂业务流程、需要设计评审 | OpenSpec → `/dev` | 先用 `/opsx:ff` 生成制品，再按 tasks 逐步实现 |
+| **大型项目** | 新项目从零开始、10+ 文件重构、多阶段里程碑 | `/gsd:new-project` 或 `/gsd:plan-phase` | GSD 编排 + Skills 执行 |
 
 ### 开发类型路由
 
@@ -249,3 +250,36 @@ tasks.md       ────→    /progress（跟踪进度）
 | `/check` | 代码规范检查 |
 | `/next` | 下一步建议（含 OpenSpec 变更扫描） |
 | `/progress` | 项目进度（含 OpenSpec 状态） |
+
+## GSD 集成（大型任务编排）
+
+本框架与 [GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done) 深度集成。GSD 负责项目编排，Skills 负责代码执行。
+
+### GSD + Skills 协作模式
+
+| GSD 阶段 | 自动激活的 Skills/Agents |
+|----------|------------------------|
+| `/gsd:debug` | 优先使用 `loki-runner` 查日志 + `mysql-runner` 查数据库 + `bug-analyzer` 根因分析 |
+| `/gsd:execute-phase` | 读取 `.claude/skills/` 自动应用项目编码规范（CRUD、API、数据库等） |
+| `/gsd:plan-phase` | 参考 Skills 中的架构设计和模块划分规范 |
+| `/gsd:verify-work` | 可调用 `auto-test-generator` 生成接口测试验证 |
+
+### 可用的领域 Agents（GSD 子 agent 可调用）
+
+| Agent | 能力 | 适用场景 |
+|-------|------|---------|
+| `loki-runner` | 查 Grafana Loki 线上日志 | debug 时查错误日志、traceId 链路 |
+| `mysql-runner` | 查 MySQL 数据库验证数据 | debug 时验证数据状态 |
+| `bug-analyzer` | 根因分析（含日志+数据库联动） | 复杂 Bug 的多维度排查 |
+| `code-scanner` | 快速扫描代码库定位文件 | 大型代码库的文件定位 |
+| `auto-test-generator` | 生成 Hurl 接口测试 | verify-work 阶段验证 |
+| `image-reader` | 读取 Axure 原型截图 | 需求分析阶段 |
+| `task-fetcher` | 获取云效任务信息 | 任务管理联动 |
+| `code-reviewer` | 代码审查（含 leniu 规范） | 执行完成后质量检查 |
+
+### 环境配置（GSD agent 共享）
+
+GSD 子 agent 可读取以下配置（全局或本地）：
+- `mysql-config.json` — 数据库连接（支持 range 环境匹配）
+- `loki-config.json` — Grafana Loki Token
+- 初始化：`npx ai-engineering-init config --type all --scope global`

package/README.md

@@ -27,6 +27,8 @@ npx ai-engineering-init --tool all      # 全部
 | `npx ai-engineering-init` | 交互式初始化到当前项目 |
 | `npx ai-engineering-init@latest update` | 更新已安装的框架文件 |
 | `npx ai-engineering-init@latest global` | 全局安装到 `~/.claude` 等，所有项目生效 |
+| `npx ai-engineering-init config` | 初始化数据库连接 / Loki 日志配置（支持全局/本地/追加） |
+| `npx ai-engineering-init mcp` | MCP 服务器管理（安装/卸载/状态） |
 | `npx ai-engineering-init sync-back` | 对比本地技能修改，反馈回源仓库 |
 
 > 所有命令均支持 `--tool <claude|cursor|codex|all>` 指定工具。运行 `--help` 查看全部选项。

package/bin/index.js

@@ -1350,12 +1350,23 @@ async function runMysqlConfig(ask, isGlobal) {
     _comment: '环境支持 range 字段（如 "1~15"），用户说"dev10"时自动匹配。查找顺序：本地 .claude/ > 全局 ~/.claude/',
   };
 
+  const configJson = JSON.stringify(config, null, 2) + '\n';
+  // 写入主路径
   const dir = path.dirname(configPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+  fs.writeFileSync(configPath, configJson, 'utf-8');
   console.log(`  ${fmt('green', '✔')} 已写入：${configPath}`);
 
-  if (!isGlobal) ensureGitignore(['mysql-config.json']);
+  // 全局模式：同时写入 ~/.cursor/（如果目录存在）
+  if (isGlobal) {
+    const cursorConfigPath = path.join(HOME_DIR, '.cursor', 'mysql-config.json');
+    if (fs.existsSync(path.join(HOME_DIR, '.cursor'))) {
+      fs.writeFileSync(cursorConfigPath, configJson, 'utf-8');
+      console.log(`  ${fmt('green', '✔')} 已同步：${cursorConfigPath}`);
+    }
+  } else {
+    ensureGitignore(['mysql-config.json']);
+  }
 
   console.log('');
   console.log(fmt('green', 'MySQL 数据库配置完成！'));
@@ -1540,11 +1551,22 @@ async function collectLokiEnvInput(ask, index, total) {
 }
 
 function writeLokiConfig(config, configPath, isGlobal) {
+  const configJson = JSON.stringify(config, null, 2) + '\n';
   const dir = path.dirname(configPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+  fs.writeFileSync(configPath, configJson, 'utf-8');
   console.log(`  ${fmt('green', '✔')} 已写入：${configPath}`);
-  if (!isGlobal) ensureGitignore(['loki-config.json', 'environments.json']);
+
+  // 全局模式：同时写入 ~/.cursor/（如果目录存在）
+  if (isGlobal) {
+    const cursorConfigPath = path.join(HOME_DIR, '.cursor', 'loki-config.json');
+    if (fs.existsSync(path.join(HOME_DIR, '.cursor'))) {
+      fs.writeFileSync(cursorConfigPath, configJson, 'utf-8');
+      console.log(`  ${fmt('green', '✔')} 已同步：${cursorConfigPath}`);
+    }
+  } else {
+    ensureGitignore(['loki-config.json', 'environments.json']);
+  }
   console.log('');
   console.log(fmt('green', 'Loki 日志查询配置完成！'));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-init",
-  "version": "1.16.1",
+  "version": "1.16.3",
   "description": "AI 工程化配置初始化工具 — 一键为 Claude Code、OpenAI Codex 等 AI 工具初始化 Skills 和项目规范",
   "keywords": [
     "claude-code",

package/src/skills/fix-bug/SKILL.md

@@ -197,6 +197,62 @@ Agent(mysql-runner, "根据日志发现涉及 order_info 表，查询 id=xxx 的
 | Bug 描述 + DB 信息 | bug-analyzer + mysql-runner | — |
 | Bug 描述 + traceId + DB 信息 | 全部 | 日志中有新表/ID → mysql-runner 追加查询 |
 
+## SQL 报表 Bug 专项流程
+
+当 Bug 涉及 **SQL 查询逻辑错误**（SUM/GROUP BY/CASE WHEN/金额计算等），启用以下验证流程：
+
+### 修复前：建立基线
+
+```
+1. 读取当前 Mapper XML，理解现有 SQL 逻辑
+2. 如果有已修复的参考查询（如同模块的明细查询），先读取其 SQL 逻辑作为正确参考
+3. 查库获取当前错误结果作为"修复前基线"（可选，用户提供 DB 时执行）
+```
+
+### 修复后：交叉验证（必须执行）
+
+**两步验证法**（以本项目销售汇总修复为典型案例）：
+
+```
+步骤 1：直接执行修改后的 SQL，验证基本逻辑
+  - 检查各记录类型是否正确处理（称重/按份、正向/逆向、入库/出库）
+  - 检查特殊值：NULL 处理、除零保护、边界条件
+
+步骤 2：交叉对比验证
+  - 方法 A：用已修复的明细查询做 SUM 汇总
+  - 方法 B：执行修改后的汇总查询
+  - 对比 A vs B：总计必须完全一致
+  - 按维度对比（按商品/按门店等）：逐行 MATCH/DIFF
+```
+
+### 验证 SQL 模板
+
+```sql
+-- 交叉验证：明细汇总 vs 汇总查询
+SELECT '明细汇总' as source, SUM(saleNum), SUM(cost), ...
+FROM (/* 明细查询逐行 */) detail
+UNION ALL
+SELECT '汇总查询' as source, ...
+FROM /* 汇总查询 */;
+
+-- 按维度逐行对比
+SELECT COALESCE(d.name, s.name) as name,
+       d.detail_value, s.summary_value,
+       CASE WHEN d.detail_value = s.summary_value THEN 'MATCH' ELSE 'DIFF' END as result
+FROM (/* 明细按维度 GROUP BY */) d
+LEFT JOIN (/* 汇总按维度 GROUP BY */) s ON d.id = s.id;
+```
+
+### SQL 修改注意事项
+
+| 规则 | 说明 |
+|------|------|
+| **保留 WHERE 条件** | 新增/修改查询必须包含与现有查询相同的过滤条件 |
+| **GROUP BY 优先** | 优先添加字段到 GROUP BY，不用 ANY_VALUE() |
+| **JOIN 一致性** | 主查询和合计查询的 JOIN 必须一致（如 drp_unit） |
+| **IFNULL 保护** | 除法运算中的分母必须用 IFNULL 防止除零 |
+| **业务类型分支** | CASE WHEN 必须覆盖所有业务类型（称重/按份、入库/出库等） |
+
 ## 提交规则
 
 修复完成后，**必须调用 `Skill(git-workflow)` 再执行 git 操作**。
@@ -210,3 +266,4 @@ Agent(mysql-runner, "根据日志发现涉及 order_info 表，查询 id=xxx 的
 - 简单 Bug 不要过度编排，直接修就行（但仍需先报告再修复）
 - 如果用户没提供 DB/Loki 信息但 Bug 涉及数据问题，主动询问
 - 与 `bug-detective` 技能的区别：`bug-detective` 是排查指南，`fix-bug` 是全流程编排（包含排查+修复+提交）
+- SQL 报表 Bug 修复后**必须执行交叉验证**，不能只看"能跑"就提交