ai-engineering-init 1.10.0 → 1.11.0

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

@@ -0,0 +1,166 @@
+---
+name: fix-bug
+description: |
+  Bug 修复全流程编排。强制使用并行 Agent 模式进行排查，修复后走 git-workflow 提交。
+
+  触发场景：
+  - 修复 Bug（含日志/traceId/数据库信息）
+  - 线上问题排查与修复
+  - 报表数据不正确需排查修复
+  - 接口返回异常需定位修复
+
+  触发词：修复bug、fix bug、修复、排查修复、线上修复、bug修复
+---
+
+# Bug 修复全流程
+
+## 核心原则
+
+**先判断复杂度，简单 Bug 直接修，复杂 Bug 走并行 Agent。修复后必须走 git-workflow 提交。**
+
+## 步骤 0：复杂度判断（必须先做）
+
+```
+用户提供 Bug 线索
+  │
+  ├─ 简单 Bug？ ──→ 快速路径（直接读代码修复）
+  │   - 明显的代码错误（NPE、空判断遗漏、拼写错误）
+  │   - 用户已明确指出问题和修改方案
+  │   - 单文件改动，逻辑清晰
+  │   - 不需要查数据库/日志验证
+  │
+  └─ 复杂 Bug？ ──→ Agent 路径（并行排查）
+      - 需要查日志确认线上行为（提供了 traceId）
+      - 需要查数据库验证数据正确性（提供了 DB 信息）
+      - 问题根因不明确，需要多维度分析
+      - 涉及多模块/多表关联的数据问题
+```
+
+## 快速路径（简单 Bug）
+
+```
+读代码 → 定位问题 → 修复 → 走 git-workflow 提交
+```
+
+不启动 Agent，直接在主对话中完成。
+
+## Agent 路径（复杂 Bug）
+
+```
+步骤 1：收集信息（从用户消息中提取）
+  - traceId / 错误日志
+  - 数据库环境（host/port/库名）
+  - Loki 日志环境
+  - Bug 描述 / 期望行为
+
+步骤 2：并行启动 Agent（必须同时启动，不串行）
+  ├── bug-analyzer Agent: 读代码分析根因，给出修复方案
+  ├── mysql-runner Agent: 查数据库验证数据（如提供了DB信息）
+  └── loki-runner Agent: 查 Loki 日志验证线上行为（如提供了traceId）
+
+步骤 3：汇总 Agent 结果 → 确认修复方案
+
+步骤 4：修复代码
+
+步骤 5：走 git-workflow 提交
+```
+
+## Agent 启动规则
+
+### 必须并行（单条消息多个 Agent tool call）
+
+```
+# 正确：一条消息同时启动 3 个 Agent
+Agent(bug-analyzer, "分析 xxx 代码的 bug...")
+Agent(mysql-runner, "查询 xxx 数据库验证...")
+Agent(loki-runner, "查询 traceId xxx 的日志...")
+
+# 错误：串行启动（等一个完再启动下一个）
+```
+
+### 各 Agent 职责
+
+| Agent | subagent_type | 职责 | 输入 |
+|-------|---------------|------|------|
+| 代码分析 | `bug-analyzer` | 读代码、分析根因、给修复方案 | Bug 描述 + 相关文件路径 |
+| 数据库验证 | `mysql-runner` | 查数据验证业务逻辑 | DB 连接信息 + 验证 SQL |
+| 日志查询 | `loki-runner` | 查 Loki 日志看线上行为 | Loki 环境 + traceId |
+
+### Agent 信息来源
+
+**配置文件优先**，不存在时自动创建模板并提示用户填写：
+
+| 配置 | 文件路径 |
+|------|---------|
+| MySQL | `.claude/mysql-config.json` |
+| Loki | `.claude/skills/loki-log-query/environments.json` |
+
+**配置获取流程**：
+```
+需要连 MySQL/Loki？
+  │
+  ├─ 配置文件存在且有有效凭证？ → 直接使用
+  │
+  ├─ 配置文件存在但是占位符？ → 提示用户填写敏感信息，等用户确认后继续
+  │
+  └─ 配置文件不存在？ → 创建模板文件（占位符） → 提示用户填写 → 等确认后继续
+```
+
+**创建 MySQL 模板**：
+```json
+{
+  "environments": {
+    "test21": {
+      "name": "test21 测试环境",
+      "host": "YOUR_HOST",
+      "port": 3306,
+      "user": "YOUR_USER",
+      "password": "YOUR_PASSWORD",
+      "db_prefix": "testcore_",
+      "aliases": ["test21", "21"]
+    }
+  },
+  "default": "test21",
+  "mysql_path": "/opt/homebrew/opt/mysql-client/bin/mysql"
+}
+```
+
+**创建 Loki 模板**：
+```json
+{
+  "active": "test13",
+  "environments": {
+    "test13": {
+      "name": "测试13（主测试环境）",
+      "url": "https://test13.xnzn.net/grafana",
+      "token": "YOUR_TOKEN",
+      "aliases": ["test13", "13"]
+    }
+  }
+}
+```
+
+**敏感信息由用户手动填写，禁止 AI 将对话中的密码/token 写入配置文件。**
+
+### 按信息量决定启动哪些 Agent
+
+| 用户提供的信息 | 启动的 Agent |
+|---------------|-------------|
+| 只有 Bug 描述 | bug-analyzer |
+| Bug 描述 + traceId | bug-analyzer + loki-runner |
+| Bug 描述 + DB 信息 | bug-analyzer + mysql-runner |
+| Bug 描述 + traceId + DB 信息 | bug-analyzer + mysql-runner + loki-runner（全部） |
+
+## 提交规则
+
+修复完成后，**必须调用 `Skill(git-workflow)` 再执行 git 操作**。
+
+禁止：
+- 直接 `git commit && git push` 跳过技能
+- 在 Agent 内部执行 git 操作
+
+## 注意
+
+- 简单 Bug 不要过度编排，直接修就行
+- 如果用户没提供 DB/Loki 信息但 Bug 涉及数据问题，主动询问
+- 与 `bug-detective` 技能的区别：`bug-detective` 是排查指南，`fix-bug` 是全流程编排（包含排查+修复+提交）

package/.codex/skills/next/SKILL.md

@@ -1,8 +1,22 @@
+---
+name: next
+description: |
+  当需要获取项目开发的下一步建议、规划开发方向时自动使用此 Skill。
+
+  触发场景：
+  - 不知道下一步应该做什么
+  - 需要获取开发优先级建议
+  - 需要分析当前项目状态并给出建议
+  - 需要规划开发工作方向
+
+  触发词：下一步、next、建议、做什么、开发方向、优先级、工作建议、开发建议
+---
+
 # /next - 下一步建议
 
 作为项目开发顾问，根据当前项目状态，为您建议下一步应该做什么。
 
-## 执行流程
+## 🎯 执行流程
 
 ### 第一步：快速扫描项目状态
 
@@ -11,55 +25,39 @@
 git log -5 --oneline
 
 # 扫描所有业务模块中的 TODO/FIXME
-Grep pattern: "TODO:|FIXME:" path: sys-canteen/,sys-kitchen/,sys-drp/,sys-common/ glob: "*.java" output_mode: content -B 2
-
-# 检查代码规范问题
-Grep pattern: "package org\.dromara\.|package com\.ruoyi\." path: sys-canteen/,sys-kitchen/,sys-drp/ glob: "*.java" output_mode: files_with_matches
-Grep pattern: "MapstructUtils|ServiceException" path: sys-canteen/,sys-kitchen/,sys-drp/ glob: "*.java" output_mode: files_with_matches
+Grep pattern: "TODO:|FIXME:" path: ruoyi-modules/ glob: "*.java" output_mode: content -B 2
 
-# 扫描 OpenSpec 活跃变更（如果存在 openspec 目录）
-Glob pattern: "openspec/changes/*/tasks.md"
-# 对每个找到的 tasks.md，读取内容检查任务完成状态（[ ] 未完成 / [x] 已完成）
+# 检查代码规范和问题
+Grep pattern: "package com\.ruoyi\.|BeanUtil\.copy" path: ruoyi-modules/ glob: "*.java" output_mode: files_with_matches
 ```
 
 ### 第二步：分析开发阶段
 
-根据代码完整性和功能数量判断：
-
 | 阶段 | 特征 | 功能完成率 |
 |------|------|----------|
 | 🟢 初期 | 基础框架搭建，功能模块较少 | < 30% |
 | 🟡 中期 | 核心功能开发中，模块逐步完善 | 30-70% |
 | 🔴 后期 | 功能基本完成，处于优化阶段 | > 70% |
 
-### 第三步：分析 OpenSpec 变更状态（如有）
-
-如果发现 `openspec/changes/` 下有活跃变更：
-
-1. 读取每个变更的 `tasks.md`，统计未完成任务
-2. 读取 `proposal.md` 获取变更概述
-3. 将未完成的 OpenSpec 任务纳入建议优先级
-
-### 第四步：分类问题和建议
+### 第三步：分类问题和建议
 
 - **紧急问题**：安全漏洞、严重 Bug、编译错误
-- **OpenSpec 待实现**：已拆解但未完成的变更任务
 - **重要问题**：功能缺陷、设计问题、规范问题
 - **优化建议**：性能优化、代码重构、文档完善
 
 ---
 
-## 输出格式
+## 📊 输出格式
 
 ```markdown
-# 下一步建议
+# 🎯 下一步建议
 
 **分析时间**：YYYY-MM-DD HH:mm
 **分析范围**：全量后端代码
 
 ---
 
-## 当前状态
+## 📌 当前状态
 
 ### Git 提交分析
 - **最近一次提交**：[commit message] ([commit hash])
@@ -68,197 +66,64 @@ Glob pattern: "openspec/changes/*/tasks.md"
 
 ### 代码状态
 - **开发阶段**：🟡 中期（核心功能开发中）
-- **代码质量**：良好（包名符合 net.xnzn.core.*）
-- **规范问题**：3 个接口缺少 @RequiresAuthentication 注解
+- **代码质量**：良好（无 com.ruoyi 包名问题）
+- **规范问题**：3 个接口缺少 @SaCheckPermission 注解
 
 ### 代码待办统计
 - **TODO 项**：X 个
 - **FIXME 项**：X 个
 - **编译/运行错误**：无
 
-### OpenSpec 变更状态（如有活跃变更）
-- **活跃变更**：X 个
-- **待实现任务**：X 个
-- **变更列表**：
-  - `[变更名]`：X/Y 任务完成（[proposal 概述]）
-
 ---
 
-## 建议优先级
+## 🚀 建议优先级
 
 ### 🔴 高优先级（必须立即处理）
 
 1. **修复 FIXME 问题**
-   - 位置：sys-canteen/.../service/impl/XxxService.java:156
-   - 问题：业务逻辑存在已知错误
-   - 原因：影响核心业务正确性
-   - 影响：可能导致数据异常
+   - 位置：ruoyi-demo/PaymentService.java:156
+   - 问题：退款金额计算错误
    - **快速修复**：`/check` 找出所有 FIXME 并逐一解决
 
 2. **补充缺失的权限注解**
-   - 位置：sys-canteen 模块 3 个接口
-   - 问题：缺少 @RequiresAuthentication 或 @RequiresGuest 注解
-   - 原因：权限控制不完整
-   - 影响：系统存在未授权访问风险
-   - **快速修复**：`/check canteen` 查出所有问题接口
-
-3. **完善代码规范**
-   - 问题：部分接口 POST 请求未使用 LeRequest<T> 封装
-   - 原因：请求封装规范不一致
-   - 影响：后续维护成本高
-   - **快速修复**：`/check` 全量检查
+   - 位置：ruoyi-demo 模块 3 个接口
+   - **快速修复**：`/check demo` 查出所有问题接口
 
 ### 🟡 中优先级（近期应该做）
 
 1. **补充缺失功能模块**
-   - 建议模块：[根据扫描结果列出未完成的业务模块]
-   - 完成率：目前 X%，建议提升到 80%
-   - **快速开发**：`/crud [表名]` 快速生成 CRUD 代码
+   - **快速开发**：`/crud Payment` 快速生成 CRUD 代码
 
 2. **优化 Service 查询层**
-   - 建议模块：[根据扫描结果列出查询不完善的模块]
-   - 问题：buildWrapper 查询条件需要完善
-   - 价值：提升查询效率，支持更复杂的搜索
-   - **参考代码**：`sys-canteen/.../order/common/service/impl/OrderInfoService.java`
-
-3. **补充接口文档注释**
-   - 建议范围：所有 Controller 接口
-   - 目标：添加 @Api、@ApiOperation Swagger 文档注解、JavaDoc 方法注释
-   - 价值：便于接口文档自动生成
+   - **参考代码**：ruoyi-system/SysNoticeServiceImpl.java
 
 ### 🟢 低优先级（可以考虑）
 
 1. **性能优化**
-   - 建议项：添加查询缓存、分页优化
-   - 触发条件：数据量大时
-
 2. **代码重构**
-   - 建议项：提取通用工具类、统一错误处理
-
 3. **单元测试**
-   - 建议项：为核心 Service 添加单元测试
-   - 触发条件：功能稳定后
 
 ---
 
-## 具体行动建议
-
-### 如果有未完成的 OpenSpec 变更：
-
-**推荐：继续实现已拆解的任务**
-- 变更名称：`[change-name]`
-- 未完成任务：[列出 tasks.md 中 [ ] 的任务]
-- **快速开始**：
-  ```bash
-  /opsx:apply [change-name]   # 自动实现下一个任务
-  /dev [任务描述]              # 手动实现特定任务
-  ```
+## 💡 具体行动建议
 
 ### 如果您想继续开发新功能：
 
-**推荐 1：完善业务模块**
-- 建议实现：[根据扫描结果列出未完成的功能]
-- 所属模块：[sys-canteen / sys-kitchen / sys-drp / sys-common]
-- **快速开始**：
-  ```bash
-  /crud [表名]          # 快速生成 CRUD 代码
-  /check [模块名]       # 检查并修复规范问题
-  ```
-
-**推荐 2：开发新的业务功能**
-- 建议实现：[根据项目进展推荐下一个业务功能]
-- **快速开始**：
-  ```bash
-  /dev 功能名称   # 使用向导开发新功能（含表设计）
-  ```
+```bash
+/crud Payment        # 快速生成 Payment 模块
+/check business      # 检查并修复规范问题
+```
 
 ### 如果您想优化代码质量：
 
-**推荐 1：规范检查和修复**
-- 建议优化：修复所有代码规范问题
-- **快速检查**：
-  ```bash
-  /check               # 全量检查
-  /check canteen       # 按模块检查
-  ```
-
-**推荐 2：Service 层优化**
-- 建议优化：完善 buildWrapper 实现，支持更复杂的查询
-- **参考代码**：`sys-canteen/.../order/common/service/impl/OrderInfoService.java`
-
-**推荐 3：注释和文档**
-- 建议优化：添加 JavaDoc 注释
-- 位置：所有 Controller 接口和关键 Service 方法
-
-### 如果您想修复现存问题：
-
-**按严重程度排序的问题列表**：
-
-#### 🔴 严重问题（立即修复）
-- **FIXME 问题**：[根据扫描结果列出 FIXME 位置和内容]
-- **权限注解缺失**：[根据扫描结果列出缺少 @RequiresAuthentication 的接口]
-- **命令**：`/check [模块名]`
-
-#### 🟡 重要问题（本周修复）
-- **LeRequest 封装缺失**：[根据扫描结果列出未使用 LeRequest<T> 的 POST 接口]
-- **del_flag 值错误**：[扫描是否有 delFlag=0 的设置]
-- **命令**：`/check [模块名]`
-
-#### 🟢 建议问题（择机修复）
-- **缺少接口文档**：所有 Controller
-- **缺少业务注释**：部分 Service 方法
-- **命令**：逐一完善
-
----
-
-## 开发建议
-
-### 开发流程建议
-
-1. **明确需求**：使用 `/start` 快速了解项目结构
-2. **检查规范**：使用 `/check` 检查代码质量
-3. **分析进度**：使用 `/progress` 了解完成情况
-4. **开始开发**：使用 `/dev` 或 `/crud` 快速生成代码
-5. **添加待办**：使用 `/add-todo` 跟踪任务
-6. **获取建议**：使用 `/next` 确定下一步方向
-
-### 最佳实践
-
-| 实践 | 说明 |
-|------|------|
-| 四层职责清晰 | Controller 路由 → Business 编排 → Service 单表 → Mapper ORM |
-| 查询构建 | 在 Service 层用 LambdaQueryWrapper 构建，禁止在 Controller 层 |
-| 对象转换 | 使用 BeanUtil.copyProperties()，禁止 MapstructUtils |
-| 权限管理 | 所有接口必须有 @RequiresAuthentication 或 @RequiresGuest |
-| 请求封装 | POST 请求体统一使用 LeRequest<T>，通过 request.getContent() 获取参数 |
-| 注释完整 | 关键方法必须有 JavaDoc 注释 |
-| 定期检查 | 每周至少一次运行 `/check` 和 `/progress` |
-
-### 技术选型建议
-
-| 场景 | 推荐方案 | 理由 |
-|------|--------|------|
-| 快速生成 CRUD | `/crud` 命令 | 已有表结构时最快 |
-| 从零开发功能 | `/dev` 命令 | 包含数据库设计和代码生成 |
-| 代码规范检查 | `/check` 命令 | 及时发现问题 |
-| 项目进度追踪 | `/progress` 命令 | 定期了解完成情况 |
-
----
-
-## 需要确认的问题
-
-### 如果不确定下一步方向，请回答：
-
-- [ ] **您更希望继续开发功能，还是优化现有代码？**
-  - 选项 A：继续开发新功能（推荐 `/crud` 或 `/dev` 命令）
-  - 选项 B：优化现有代码（推荐 `/check` 和 `/progress` 命令）
-
-- [ ] **是否需要为新开发的功能添加到待办列表中？**
-  - 可使用 `/add-todo` 快速添加
+```bash
+/check               # 全量检查
+/check business      # 按模块检查
+```
 
 ---
 
-## 相关命令
+## 🔗 相关命令
 
 | 命令 | 用途 | 何时使用 |
 |------|------|---------|
@@ -269,13 +134,4 @@ Glob pattern: "openspec/changes/*/tasks.md"
 | `/dev` | 开发新功能 | 从零开始开发 |
 | `/crud` | 快速生成代码 | 表已存在时 |
 | `/add-todo` | 添加待办任务 | 跟踪任务 |
-
----
-
-## 说明
-
-- 本建议基于对当前项目代码的分析生成
-- 建议具体且可执行，不空泛
-- 会考虑开发的连贯性和代码质量
-- 如发现紧急问题会明确标注
-- 如不确定用户意图会主动询问
+```