@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-job/SKILL.md

@@ -1,437 +1,58 @@
 ---
 name: avatar-boot-starter-job
-description: 当使用 avatar-boot-starter-job 模块时使用此技能 - 为 Spring Boot 3.5.3 应用提供基于 XXL-Job 2.4.0 的分布式任务调度能力，包含自动配置、监控指标、AOP 拦截。
+description: Avatar Boot XXL-Job 模块使用指南。当用户询问分布式任务调度、XXL-Job 配置、@XxlJob 注解、任务处理器编写、监控指标，或需要接入 avatar-boot-starter-job 时触发。
 ---
 
-Avatar Boot 的 XXL-Job 分布式任务调度集成模块，提供开箱即用的任务调度能力和完善的监控指标。
+# Avatar Boot Starter Job 使用指南
 
-## 功能特性
+你是 Avatar Boot XXL-Job 模块的使用顾问与开发助手。
 
-- ✅ **零代码配置** - 基于 Spring Boot 自动配置机制，自动装配 XXL-Job 执行器
-- ✅ **原生配置兼容** - 使用 XXL-Job 原生配置属性（xxl.job.*），无需学习新配置
-- ✅ **条件装配** - 支持通过 `enabled` 开关控制是否启用
-- ✅ **AOP 监控** - 自动拦截 @XxlJob 方法，记录执行指标
-- ✅ **Micrometer 集成** - 内置任务执行和执行器状态监控指标
-- ✅ **优雅日志** - 清晰的启动和执行日志，便于问题排查
-- ✅ **完全兼容** - 100% 兼容 XXL-Job 原生注解和功能
+## 交互流程（必须遵守）
 
-## 快速开始
+**每次被触发时，先通过 AskUserQuestion 工具询问用户意图：**
 
-### 1. 添加依赖
+问题："您好！我是 Avatar Boot XXL-Job 模块助手，请问您需要哪方面的帮助？"
+选项：
+1. **快速接入** - 添加依赖、配置执行器、编写任务处理器
+2. **任务编写** - 简单任务、带参数任务、分片任务、结果回调
+3. **配置说明** - 必填/可选配置项、多环境配置、禁用 XXL-Job
+4. **监控指标** - Micrometer 指标、Prometheus 查询、Grafana 面板
+5. **常见问题** - 执行器注册失败、任务无法触发、日志无法查看
 
-在项目的 `pom.xml` 中添加依赖：
+**根据用户选择，用 Read 工具按下方「文档读取路由」加载对应文档，然后给出具体指导。**
 
-```xml
-<dependency>
-    <groupId>com.iflytek.avatar.boot</groupId>
-    <artifactId>avatar-boot-starter-job</artifactId>
-</dependency>
-```
-
-### 2. 配置文件
-
-在 `application.yml` 中添加配置：
-
-```yaml
-xxl:
-  job:
-    enabled: true  # 是否启用（默认 true）
-    admin:
-      addresses: http://localhost:8080/xxl-job-admin  # 调度中心地址
-    executor:
-      appname: your-app-name  # 执行器名称（必填）
-      port: 9999  # 执行器端口（默认 9999）
-      logpath: logs/xxl-job  # 日志路径（默认 logs/xxl-job）
-      logretentiondays: 30  # 日志保留天数（默认 30）
-    access-token: your-token  # 访问令牌（可选）
-```
-
-### 3. 编写任务处理器
-
-使用 `@XxlJob` 注解标记任务方法：
-
-```java
-package com.example.job;
-
-import com.xxl.job.core.context.XxlJobHelper;
-import com.xxl.job.core.handler.annotation.XxlJob;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.stereotype.Component;
+---
 
-@Slf4j
-@Component
-public class SampleJobHandler {
+## 行为准则
 
-    /**
-     * 简单任务示例
-     */
-    @XxlJob("demoJobHandler")
-    public void demoJobHandler() {
-        log.info("XXL-JOB, Hello World.");
-    }
+1. **回答要具体**：引用具体的配置项、注解、PromQL 语句
+2. **主动提醒**：`appname` 必须与调度中心配置一致
+3. **使用中文回答**
+4. **版本说明**：XXL-Job 2.4.0 + Spring Boot 3.5.3 + Java 21
 
-    /**
-     * 带参数的任务示例
-     */
-    @XxlJob("paramJobHandler")
-    public void paramJobHandler() {
-        String param = XxlJobHelper.getJobParam();
-        log.info("XXL-JOB, 接收参数: {}", param);
-    }
+---
 
-    /**
-     * 分片任务示例
-     */
-    @XxlJob("shardingJobHandler")
-    public void shardingJobHandler() {
-        int shardIndex = XxlJobHelper.getShardIndex();
-        int shardTotal = XxlJobHelper.getShardTotal();
-        log.info("分片参数：当前分片序号 = {}, 总分片数 = {}", shardIndex, shardTotal);
-    }
-}
-```
+## 文档读取路由
 
-**重要说明：**
-- 任务处理器类必须被 Spring 管理（添加 `@Component` 注解）
-- `@XxlJob` 注解的值必须与调度中心配置的 JobHandler 名称一致
-- 监控指标会自动记录所有 @XxlJob 方法的执行情况
+> 所有路径相对于 skill 目录 `docs/skills/avatar-boot-starter-job-skill/`
 
-### 4. 在调度中心配置任务
+| 用户需求 | 需读取的文件 |
+|:--|:--|
+| 快速接入 / 任务编写 / 配置说明 | `references/快速接入与配置.md` |
+| 监控指标 | `references/监控指标.md` |
+| 常见问题 | `references/常见问题.md` |
 
-1. 登录 XXL-Job 调度中心
-2. 执行器管理 -> 新增执行器（AppName 与配置文件中的 `appname` 一致）
-3. 任务管理 -> 新增任务
-    - JobHandler: `demoJobHandler`（与 @XxlJob 注解的值一致）
-    - 调度类型: CRON
-    - Cron: `0 0/1 * * * ?`（每分钟执行一次）
+---
 
-## 配置说明
+## 通用参考信息
 
 ### 必填配置
 
-| 配置项 | 说明 | 示例 |
-|--------|------|------|
-| `xxl.job.admin.addresses` | 调度中心地址 | `http://localhost:8080/xxl-job-admin` |
-| `xxl.job.executor.appname` | 执行器名称 | `my-app-executor` |
-
-### 可选配置
-
-| 配置项 | 说明 | 默认值 |
-|--------|------|--------|
-| `xxl.job.enabled` | 是否启用 XXL-Job | `true` |
-| `xxl.job.executor.port` | 执行器端口 | `9999` |
-| `xxl.job.executor.ip` | 执行器 IP（为空自动获取） | 空 |
-| `xxl.job.executor.address` | 执行器注册地址（优先使用） | 空 |
-| `xxl.job.executor.logpath` | 日志路径 | `logs/xxl-job` |
-| `xxl.job.executor.logretentiondays` | 日志保留天数 | `30` |
-| `xxl.job.access-token` | 访问令牌 | 空 |
-
-### 监控配置
-
-| 配置项 | 说明 | 默认值 |
-|--------|------|--------|
-| `xxl.job.metrics.enabled` | 是否启用所有监控指标 | `true` |
-| `xxl.job.metrics.execution-enabled` | 是否启用任务执行监控 | `true` |
-| `xxl.job.metrics.executor-enabled` | 是否启用执行器状态监控 | `true` |
-
-## 功能详解
-
-### 1. 自动配置机制
-
-模块使用 Spring Boot 自动配置机制，满足以下条件时自动装配：
-
-- Classpath 中存在 `XxlJobSpringExecutor` 类
-- 配置 `xxl.job.enabled=true`（默认为 true）
-- 未手动定义 `XxlJobSpringExecutor` Bean
-
-**启动日志：**
-```
->>>>>>>>>>> XXL-Job 执行器配置初始化
->>>>>>>>>>> XXL-Job 执行器配置完成: appname=my-app, adminAddresses=http://localhost:8080/xxl-job-admin
-```
-
-### 2. AOP 监控拦截
-
-使用 AspectJ 自动拦截所有 `@XxlJob` 注解的方法：
-
-- **执行前**：记录开始时间，增加活跃任务计数
-- **执行后**：记录执行时长、成功/失败状态
-- **异常时**：记录异常信息和执行时长
-- **最终**：减少活跃任务计数
-
-**日志输出：**
-```
-DEBUG: Job [demoJobHandler] executed successfully in 125ms
-ERROR: Job [failedJobHandler] failed after 50ms
-```
-
-### 3. 任务执行结果回调
-
-```java
-@XxlJob("callbackJobHandler")
-public void callbackJobHandler() {
-    try {
-        // 业务逻辑
-        XxlJobHelper.handleSuccess("任务执行成功");
-    } catch (Exception e) {
-        XxlJobHelper.handleFail("任务执行失败: " + e.getMessage());
-    }
-}
-```
-
-### 4. 任务日志输出
-
-```java
-@XxlJob("logJobHandler")
-public void logJobHandler() {
-    XxlJobHelper.log("这是一条任务日志");
-    XxlJobHelper.log("支持多行日志输出");
-}
-```
-
-## 监控指标
-
-本 Starter 内置了基于 Micrometer 的监控指标采集功能，可与 Prometheus、Grafana 等监控系统集成。
-
-### 启用监控
-
-监控功能默认启用，如需禁用可通过配置：
-
-```yaml
-xxl:
-  job:
-    metrics:
-      enabled: false  # 禁用所有监控指标
-      execution-enabled: true  # 仅启用任务执行监控（默认 true）
-      executor-enabled: true  # 仅启用执行器状态监控（默认 true）
-```
-
-### 可用指标
-
-#### 1. 任务执行指标
-
-| 指标名称 | 类型 | 标签 | 说明 |
-|---------|------|------|------|
-| `xxl.job.execution.count` | Counter | `job_handler`, `status` | 任务执行次数（status: success/failure） |
-| `xxl.job.execution.time` | Timer | `job_handler`, `status` | 任务执行耗时（毫秒） |
-| `xxl.job.execution.active` | Gauge | 无 | 当前正在执行的任务数 |
-
-#### 2. 执行器状态指标
-
-| 指标名称 | 类型 | 标签 | 说明 |
-|---------|------|------|------|
-| `xxl.job.executor.registered` | Gauge | `app_name` | 执行器注册状态（1=已注册，0=未注册） |
-| `xxl.job.executor.handlers.total` | Gauge | `app_name` | 已注册的 JobHandler 总数 |
-
-### Prometheus 查询示例
-
-```promql
-# 查询任务执行成功率
-sum(rate(xxl_job_execution_count_total{status="success"}[5m]))
-/
-sum(rate(xxl_job_execution_count_total[5m])) * 100
-
-# 查询任务平均执行时间（秒）
-rate(xxl_job_execution_time_seconds_sum[5m])
-/
-rate(xxl_job_execution_time_seconds_count[5m])
-
-# 查询特定任务的失败次数
-sum(xxl_job_execution_count_total{job_handler="demoJobHandler", status="failure"})
-
-# 查询当前活跃任务数
-xxl_job_execution_active
-
-# 查询执行器注册状态
-xxl_job_executor_registered{app_name="your-app-name"}
-
-# 查询已注册的 JobHandler 数量
-xxl_job_executor_handlers_total{app_name="your-app-name"}
-```
-
-### Grafana 面板配置
-
-推荐创建以下监控面板：
-
-#### 1. 任务执行概览
-- **总执行次数**：`sum(increase(xxl_job_execution_count_total[1h]))`
-- **成功率**：`sum(rate(xxl_job_execution_count_total{status="success"}[5m])) / sum(rate(xxl_job_execution_count_total[5m])) * 100`
-- **平均耗时**：`rate(xxl_job_execution_time_seconds_sum[5m]) / rate(xxl_job_execution_time_seconds_count[5m])`
-
-#### 2. 任务执行趋势
-- **执行次数趋势**：`rate(xxl_job_execution_count_total[5m])`（按 job_handler 分组）
-- **失败次数趋势**：`rate(xxl_job_execution_count_total{status="failure"}[5m])`
-
-#### 3. 执行器状态
-- **注册状态**：`xxl_job_executor_registered`
-- **Handler 数量**：`xxl_job_executor_handlers_total`
-- **活跃任务数**：`xxl_job_execution_active`
-
-#### 4. 性能分析
-- **P95 耗时**：`histogram_quantile(0.95, rate(xxl_job_execution_time_seconds_bucket[5m]))`
-- **P99 耗时**：`histogram_quantile(0.99, rate(xxl_job_execution_time_seconds_bucket[5m]))`
-
-### 集成 Prometheus
-
-在 `application.yml` 中启用 Prometheus 端点：
-
-```yaml
-management:
-  endpoints:
-    web:
-      exposure:
-        include: prometheus,health,info
-  metrics:
-    export:
-      prometheus:
-        enabled: true
-```
-
-访问 `http://localhost:8080/actuator/prometheus` 查看指标数据。
-
-## 使用场景
-
-### 场景 1：开发环境禁用任务调度
-
-```yaml
-# application-dev.yml
-xxl:
-  job:
-    enabled: false  # 开发环境禁用
-```
-
-### 场景 2：多环境配置
-
-```yaml
-# application-prod.yml
-xxl:
-  job:
-    enabled: true
-    admin:
-      addresses: http://prod-xxl-job:8080/xxl-job-admin
-    executor:
-      appname: prod-app-executor
-      port: 9999
-    access-token: ${XXL_JOB_TOKEN}  # 从环境变量读取
-```
-
-### 场景 3：只监控特定任务
-
-```yaml
-xxl:
-  job:
-    metrics:
-      execution-enabled: true  # 启用任务执行监控
-      executor-enabled: false  # 禁用执行器状态监控
-```
-
-## 高级用法
-
-### 1. 自定义执行器配置
-
-```yaml
-xxl:
-  job:
-    executor:
-      ip: 192.168.1.100  # 指定执行器 IP
-      address: http://192.168.1.100:9999  # 指定注册地址（优先级最高）
-      logpath: /data/logs/xxl-job  # 使用绝对路径
-```
-
-### 2. 多调度中心配置
-
-```yaml
-xxl:
-  job:
-    admin:
-      addresses: http://admin1:8080/xxl-job-admin,http://admin2:8080/xxl-job-admin
-```
-
-### 3. 禁用监控指标
-
-```yaml
-xxl:
-  job:
-    metrics:
-      enabled: false  # 完全禁用监控
-```
-
-## 常见问题
-
-### 1. 执行器无法注册到调度中心
-
-**原因**：网络不通或配置错误
-
-**解决**：
-- 检查 `xxl.job.admin.addresses` 是否正确
-- 检查调度中心是否启动
-- 检查执行器端口是否被占用
-- 查看启动日志中的错误信息
-
-### 2. 任务无法触发
-
-**原因**：JobHandler 名称不匹配
-
-**解决**：
-- 确保 `@XxlJob` 注解的值与调度中心配置的 JobHandler 一致
-- 确保任务处理器类被 Spring 管理（添加 `@Component` 注解）
-- 检查执行器是否成功注册
-
-### 3. 日志无法查看
-
-**原因**：日志路径权限不足
-
-**解决**：
-- 检查 `xxl.job.executor.logpath` 路径是否有写权限
-- 使用绝对路径或确保相对路径可写
-- 检查磁盘空间是否充足
-
-### 4. 监控指标不显示
-
-**原因**：Actuator 端点未暴露或监控被禁用
-
-**解决**：
-- 确保 `xxl.job.metrics.enabled=true`
-- 检查 Actuator 配置是否正确
-- 访问 `/actuator/prometheus` 验证指标是否存在
-
-### 5. 任务执行时间不准确
-
-**原因**：AOP 拦截可能包含框架开销
-
-**解决**：
-- 监控指标记录的是方法执行时间（包含 AOP 开销）
-- 如需精确业务逻辑耗时，在方法内部单独计时
-- AOP 开销通常在 1-5ms 范围内
-
-## 架构说明
-
-### 核心组件
-
-- **XxlJobAutoConfiguration**：自动配置类，创建 XxlJobSpringExecutor Bean
-- **XxlJobProperties**：配置属性类，映射 xxl.job.* 配置
-- **XxlJobMetricsAspect**：AOP 切面，拦截 @XxlJob 方法记录指标
-- **JobMetricsRecorder**：指标记录器，封装 Micrometer API
-- **ExecutorMetricsCollector**：执行器状态收集器，定期更新执行器指标
-
-### 自动配置条件
-
-```java
-@ConditionalOnClass(XxlJobSpringExecutor.class)  // 类路径存在 XXL-Job
-@ConditionalOnProperty(prefix = "xxl.job", name = "enabled",
-                       havingValue = "true", matchIfMissing = true)  // 配置启用
-@ConditionalOnMissingBean  // 未手动定义 Bean
-```
-
-## 依赖版本
-
-- XXL-Job: 2.4.0
-- Spring Boot: 3.5.3
-- Micrometer: 由 Spring Boot BOM 管理
-- Java: 21
+| 配置项 | 说明 |
+|:--|:--|
+| `xxl.job.admin.addresses` | 调度中心地址 |
+| `xxl.job.executor.appname` | 执行器名称（与调度中心一致） |
 
-## 参考文档
+### 延迟级别速查（sendDelayed 第4个参数）
 
-- [XXL-Job 官方文档](https://www.xuxueli.com/xxl-job/)
-- [XXL-Job GitHub](https://github.com/xuxueli/xxl-job)
-- [Micrometer 文档](https://micrometer.io/docs)
+1s / 5s / 10s / 30s / 1m / 2m / 3m / 4m / 5m / 6m / 7m / 8m / 9m / 10m / 20m / 30m / 1h / 2h

package/templates/.claude/skills/avatar-boot-starter-job/references//345/270/270/350/247/201/351/227/256/351/242/230.md

@@ -0,0 +1,55 @@
+# XXL-Job 常见问题
+
+## 1. 执行器无法注册到调度中心
+
+**原因**：网络不通或配置错误
+
+**排查步骤**：
+- 检查 `xxl.job.admin.addresses` 是否正确
+- 检查调度中心是否已启动
+- 检查执行器端口是否被占用：`netstat -an | grep 9999`
+- 开启 DEBUG 日志排查：`logging.level.com.xxl.job=DEBUG`
+
+## 2. 任务无法触发
+
+**原因**：JobHandler 名称不匹配
+
+**排查步骤**：
+- 确保 `@XxlJob` 注解的值与调度中心配置的 JobHandler 完全一致（区分大小写）
+- 确保任务处理器类被 Spring 管理（添加 `@Component` 注解）
+- 确认执行器已成功注册（在调度中心执行器管理页面查看）
+
+## 3. 日志无法查看
+
+**原因**：日志路径权限不足
+
+**排查步骤**：
+- 检查 `xxl.job.executor.logpath` 路径是否有写权限
+- 建议使用绝对路径，或确保相对路径可写
+- 容器部署时注意挂载日志目录
+
+## 4. 本地开发不想启动 XXL-Job
+
+```yaml
+# application-dev.yml
+xxl:
+  job:
+    enabled: false
+```
+
+## 5. 分片任务数据重复处理
+
+**原因**：分片索引使用不正确
+
+**正确用法**：
+```java
+@XxlJob("shardingJobHandler")
+public void shardingJobHandler() {
+    int shardIndex = XxlJobHelper.getShardIndex();
+    int shardTotal = XxlJobHelper.getShardTotal();
+
+    // 按分片索引过滤数据，例如按 ID 取模
+    List<Long> ids = dataMapper.selectIdsByMod(shardIndex, shardTotal);
+    ids.forEach(this::processData);
+}
+```

package/templates/.claude/skills/avatar-boot-starter-job/references//345/277/253/351/200/237/346/216/245/345/205/245/344/270/216/351/205/215/347/275/256.md

@@ -0,0 +1,124 @@
+# XXL-Job 快速接入与配置
+
+## 1. 添加依赖
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-job</artifactId>
+</dependency>
+```
+
+## 2. 配置文件
+
+```yaml
+xxl:
+  job:
+    enabled: true                                          # 是否启用（默认 true）
+    admin:
+      addresses: http://localhost:8080/xxl-job-admin       # 调度中心地址（必填）
+    executor:
+      appname: your-app-name                               # 执行器名称（必填，与调度中心一致）
+      port: 9999                                           # 执行器端口（默认 9999）
+      logpath: logs/xxl-job                                # 日志路径
+      logretentiondays: 30                                 # 日志保留天数
+    access-token: your-token                               # 访问令牌（与调度中心保持一致）
+```
+
+## 3. 编写任务处理器
+
+```java
+import com.xxl.job.core.handler.annotation.XxlJob;
+import com.xxl.job.core.context.XxlJobHelper;
+
+@Slf4j
+@Component
+public class SampleJobHandler {
+
+    // 简单任务
+    @XxlJob("demoJobHandler")
+    public void demoJobHandler() {
+        log.info("XXL-JOB, Hello World.");
+    }
+
+    // 带参数的任务
+    @XxlJob("paramJobHandler")
+    public void paramJobHandler() {
+        String param = XxlJobHelper.getJobParam();
+        log.info("接收参数: {}", param);
+    }
+
+    // 分片任务（多实例并行处理不同数据段）
+    @XxlJob("shardingJobHandler")
+    public void shardingJobHandler() {
+        int shardIndex = XxlJobHelper.getShardIndex();
+        int shardTotal = XxlJobHelper.getShardTotal();
+        log.info("当前分片: {}/{}", shardIndex, shardTotal);
+        // 根据分片索引处理对应数据
+    }
+
+    // 带结果回调的任务
+    @XxlJob("callbackJobHandler")
+    public void callbackJobHandler() {
+        try {
+            // 业务逻辑
+            XxlJobHelper.handleSuccess("任务执行成功");
+        } catch (Exception e) {
+            XxlJobHelper.handleFail("任务执行失败: " + e.getMessage());
+        }
+    }
+
+    // 任务日志
+    @XxlJob("logJobHandler")
+    public void logJobHandler() {
+        XxlJobHelper.log("这是一条任务日志");
+    }
+}
+```
+
+## 4. 在调度中心配置任务
+
+1. 登录 XXL-Job 调度中心
+2. **执行器管理** → 新增执行器（AppName 与配置文件中的 `appname` 一致）
+3. **任务管理** → 新增任务
+   - JobHandler：`demoJobHandler`（与 `@XxlJob` 注解值一致）
+   - 调度类型：CRON
+   - Cron：`0 0/1 * * * ?`（每分钟执行一次）
+
+## 5. 多环境配置
+
+```yaml
+# application-dev.yml
+xxl:
+  job:
+    enabled: false  # 开发环境禁用
+
+# application-prod.yml
+xxl:
+  job:
+    enabled: true
+    admin:
+      addresses: http://prod-xxl-job:8080/xxl-job-admin
+    executor:
+      appname: prod-app-executor
+```
+
+## 配置说明
+
+### 必填配置
+
+| 配置项 | 说明 |
+|:--|:--|
+| `xxl.job.admin.addresses` | 调度中心地址 |
+| `xxl.job.executor.appname` | 执行器名称（与调度中心一致） |
+
+### 可选配置
+
+| 配置项 | 说明 | 默认值 |
+|:--|:--|:--|
+| `xxl.job.enabled` | 是否启用 | `true` |
+| `xxl.job.executor.port` | 执行器端口 | `9999` |
+| `xxl.job.executor.ip` | 执行器 IP（空则自动获取） | 空 |
+| `xxl.job.executor.logpath` | 日志路径 | `logs/xxl-job` |
+| `xxl.job.executor.logretentiondays` | 日志保留天数 | `30` |
+| `xxl.job.access-token` | 访问令牌 | 空 |