@llryiop/avatar-boot-cli 1.0.0 → 1.0.2

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

@@ -1,243 +1,71 @@
 ---
 name: avatar-boot-starter-feign
-description: 当使用 avatar-boot-starter-feign 模块时使用此技能 - 为 Spring Boot 3.5.3 应用提供全面的 openfeign开发，包括自动配置、TraceId 传播、日志配置、指标集成。
+description: Avatar Boot Feign 模块使用指南。当用户询问 OpenFeign 客户端配置、TraceId 传播、请求日志、性能指标监控、慢请求检测，或需要接入 avatar-boot-starter-feign 时触发。
 ---
 
-Avatar Boot 的 OpenFeign 客户端集成模块，提供开箱即用的 openfeign功能，包含自动日志记录和性能指标监控。
+# Avatar Boot Starter Feign 使用指南
 
-## 功能特性
+你是 Avatar Boot Feign 模块的使用顾问与开发助手。
 
-- ✅ **自动配置** - 基于 Spring Boot 自动配置机制，零配置即可使用
-- ✅ **请求日志** - 自动记录 Feign 客户端的请求参数和响应数据
-- ✅ **TraceId 传播** - 自动传播分布式追踪 ID 到下游服务
-- ✅ **性能指标** - 集成 Micrometer，记录调用次数、执行时间、成功/失败率
-- ✅ **慢请求检测** - 自动检测并警告超过阈值的慢请求
-- ✅ **灵活配置** - 支持细粒度的功能开关和参数配置
+## 交互流程（必须遵守）
 
-## 快速开始
+**每次被触发时，先通过 AskUserQuestion 工具询问用户意图：**
 
-### 1. 添加依赖
+问题："您好！我是 Avatar Boot Feign 模块助手，请问您需要哪方面的帮助？"
+选项：
+1. **快速接入** - 添加依赖、定义 FeignClient、启用日志
+2. **功能使用** - TraceId 传播、详细日志、性能指标、慢请求检测
+3. **配置调整** - 日志开关、慢请求阈值、请求体长度限制
+4. **使用场景** - 只要 TraceId / 需要详细日志 / 自定义配置
 
-在项目的 `pom.xml` 中添加依赖：
+**根据用户选择，用 Read 工具按下方「文档读取路由」加载对应文档，然后给出具体指导。**
 
-```xml
-<dependency>
-    <groupId>com.iflytek.avatar.boot</groupId>
-    <artifactId>avatar-boot-starter-feign</artifactId>
-</dependency>
-```
-
-### 2. 定义 Feign 客户端
-
-在 Spring Boot 应用主类上添加 `@EnableFeignClients` 注解：
-
-```java
-@SpringBootApplication
-@EnableFeignClients
-public class Application {
-    public static void main(String[] args) {
-        SpringApplication.run(Application.class, args);
-    }
-}
-```
-
-然后定义 Feign 客户端接口：
-
-```java
-import com.iflytek.avatar.boot.config.FeignLoggingConfiguration;
-
-// 使用 FeignLoggingConfiguration 启用详细日志记录
-@FeignClient(name = "user-service", url = "http://localhost:8080",
-             configuration = FeignLoggingConfiguration.class)
-public interface UserServiceClient {
-
-    @GetMapping("/api/users/{id}")
-    User getUserById(@PathVariable("id") Long id);
-
-    @PostMapping("/api/users")
-    User createUser(@RequestBody User user);
-}
-```
-
-**重要说明：**
-- `FeignLoggingConfiguration` 不是默认启用的，需要在 `@FeignClient` 的 `configuration` 属性中显式指定
-- 如果不指定 `configuration`，则只会启用 TraceId 传播功能，不会打印详细日志
-- 这样设计是为了让你可以灵活控制哪些 Feign 客户端需要详细日志
-
-### 3. 使用 Feign 客户端
-
-```java
-@Service
-@RequiredArgsConstructor
-public class UserService {
-
-    private final UserServiceClient userServiceClient;
-
-    public User getUser(Long id) {
-        return userServiceClient.getUserById(id);
-    }
-}
-```
-
-## 配置说明
-
-### 基础配置
-
-```yaml
-avatar:
-  feign:
-    logging:
-      enabled: true                      # 启用日志拦截器（TraceId 传播）
-      request-enabled: true              # 记录请求参数
-      response-enabled: true             # 记录响应数据
-      print-request-details: true        # 打印请求详情（URI、Method、Params）
-      print-response-details: true       # 打印响应详情（包含响应体）
-      print-stack-trace: true            # 打印异常堆栈信息
-      slow-request-threshold: 3000       # 慢请求阈值（毫秒）
-      max-body-length: 1000              # 最大请求体长度
-      trace-id-header: X-Trace-Id        # TraceId 请求头名称
-    metrics:
-      enabled: true                      # 启用指标记录
-```
-
-### 完整配置示例
-
-参考 `src/main/resources/application-example.yml` 查看完整配置示例。
-
-## 功能详解
-
-### 1. 详细日志记录
-
-当在 FeignClient 中配置 `FeignLoggingConfiguration` 后，会自动记录详细的请求和响应信息：
-
-**成功请求日志：**
-```
-Feign Request => URI: http://localhost:8080/api/users/1, Method: GET, Params: N/A
-Feign Response => Method: getUserById, URI: http://localhost:8080/api/users/1, Params: N/A, Response: {"id":1,"name":"John"}, Status: 200, Time: 125ms
-```
-
-**失败请求日志：**
-```
-Feign Error => Method: getUserById, URI: http://localhost:8080/api/users/1, Params: N/A, Error: Connection refused, Time: 50ms, StackTrace:
-java.net.ConnectException: Connection refused
-    at ...
-```
-
-**配置控制：**
-- `print-request-details: false` - 不打印请求详情
-- `print-response-details: false` - 不打印响应体（只打印状态和耗时）
-- `print-stack-trace: false` - 不打印异常堆栈信息
-- `max-body-length: 500` - 限制请求体/响应体的最大长度
-
-### 2. TraceId 传播
-
-自动从 `ContextManager` 获取 TraceId 并添加到请求头，实现分布式追踪：
-
-```java
-// 在上游服务中设置 TraceId
-ContextManager.get().setTraceId("trace-123");
-
-// Feign 客户端会自动将 TraceId 添加到请求头
-// X-Trace-Id: trace-123
-```
-
-**注意：** TraceId 传播是全局启用的，不需要在 FeignClient 中配置 `FeignLoggingConfiguration`。
-
-### 3. 性能指标
-
-集成 Micrometer，自动记录以下指标：
-
-- `feign.client.invocation.count` - 调用次数（标签：client, method, status）
-- `feign.client.execution.time` - 执行时间（标签：client, method, status）
-
-查看指标：
-
-```bash
-# 访问 Actuator 端
-curl http://localhost:8080/actuator/metrics/feign.client.invocation.count
-curl http://localhost:8080/actuator/metrics/feign.client.execution.time
-```
-
-### 4. 慢请求检测
-
-当请求执行时间超过配置的阈值时，自动记录警告日志：
-
-```
-WARN: Slow Feign Request Detected: getUserById took 3500ms (threshold: 3000ms)
-```
-
-## 使用场景
-
-### 场景 1：只需要 TraceId 传播，不需要详细日志
-
-```java
-// 不指定 configuration，只会启用 TraceId 传播
-@FeignClient(name = "simple-service", url = "http://localhost:8080")
-public interface SimpleServiceClient {
-    @GetMapping("/api/data")
-    String getData();
-}
-```
+---
 
-### 场景 2：需要详细日志记录和性能监控
+## 行为准则
 
-```java
-// 指定 FeignLoggingConfiguration，启用详细日志
-@FeignClient(name = "important-service", url = "http://localhost:8080",
-             configuration = FeignLoggingConfiguration.class)
-public interface ImportantServiceClient {
-    @PostMapping("/api/process")
-    Result processData(@RequestBody Data data);
-}
-```
+1. **回答要具体**：引用具体的注解、配置项、类名
+2. **主动提醒**：`FeignLoggingConfiguration` 需要显式指定，不是默认启用
+3. **使用中文回答**
+4. **版本说明**：Spring Boot 3.5.3 + Spring Cloud 2025.0.0 + Java 21
 
-### 场景 3：自定义日志配置
+---
 
-```yaml
-avatar:
-  feign:
-    logging:
-      # 只打印错误日志，不打印成功请求
-      print-request-details: false
-      print-response-details: false
-      # 但保留异常堆栈信息
-      print-stack-trace: true
-      # 降低慢请求阈值
-      slow-request-threshold: 1000
-```
+## 文档读取路由
 
-## 高级配置
+> 所有路径相对于 skill 目录 `docs/skills/avatar-boot-starter-feign-skill/`
 
-### 针对特定客户端的配置
+| 用户需求 | 需读取的文件 |
+|:--|:--|
+| 快速接入 | `references/快速接入指南.md` |
+| 功能使用 / 使用场景 | `references/功能详解.md` |
+| 配置调整 | `references/配置参考.md` |
 
-```yaml
-feign:
-  client:
-    config:
-      user-service:
-        connectTimeout: 3000
-        readTimeout: 5000
-        loggerLevel: FULL
-```
+---
 
-### 禁用日志或指标
+## 通用参考信息
 
-```yaml
-avatar:
-  feign:
-    logging:
-      enabled: false  # 禁用日志
-    metrics:
-      enabled: false  # 禁用指标
-```
+### 核心类速查
 
-## 依赖版本
+| 类/注解 | 用途 |
+|:--|:--|
+| `@EnableFeignClients` | 启动类上启用 Feign |
+| `@FeignClient` | 定义 Feign 客户端接口 |
+| `FeignLoggingConfiguration` | 启用详细请求/响应日志（需显式指定） |
 
-- Spring Boot: 3.5.3
-- Spring Cloud: 2025.0.0
-- Java: 21
+### 默认配置值
 
-## 许可证
+| 配置项 | 默认值 |
+|:--|:--|
+| `avatar.feign.logging.enabled` | `true` |
+| `avatar.feign.logging.slow-request-threshold` | `3000`（ms） |
+| `avatar.feign.logging.max-body-length` | `1000` |
+| `avatar.feign.logging.trace-id-header` | `X-Trace-Id` |
+| `avatar.feign.metrics.enabled` | `true` |
 
-Copyright © 2024 iFLYTEK Co., Ltd.
+### 可用指标
 
+| 指标名 | 标签 |
+|:--|:--|
+| `feign.client.invocation.count` | `client`, `method`, `status` |
+| `feign.client.execution.time` | `client`, `method`, `status` |

package/templates/.claude/skills/avatar-boot-starter-feign/references//345/212/237/350/203/275/350/257/246/350/247/243.md

@@ -0,0 +1,65 @@
+# Feign 功能详解
+
+## 1. TraceId 传播
+
+自动从 `ContextManager` 获取当前请求的 TraceId，添加到 Feign 请求头，实现跨服务链路追踪。
+
+- **全局生效**：无需配置 `FeignLoggingConfiguration`，所有 FeignClient 自动传播
+- **请求头名称**：默认 `X-Trace-Id`，可通过 `avatar.feign.logging.trace-id-header` 修改
+
+```
+上游服务 [TraceId: abc123] → Feign 自动添加 X-Trace-Id: abc123 → 下游服务 [TraceId: abc123]
+```
+
+## 2. 详细日志记录
+
+需要在 `@FeignClient` 中显式指定 `FeignLoggingConfiguration`：
+
+```java
+@FeignClient(name = "service", url = "http://...",
+             configuration = FeignLoggingConfiguration.class)
+public interface MyClient { ... }
+```
+
+**成功请求日志**：
+```
+Feign Request  => URI: http://localhost:8080/api/users/1, Method: GET, Params: N/A
+Feign Response => Method: getUserById, Status: 200, Time: 125ms, Response: {"id":1,"name":"张三"}
+```
+
+**失败请求日志**：
+```
+Feign Error => Method: getUserById, URI: ..., Error: Connection refused, Time: 50ms
+java.net.ConnectException: Connection refused ...
+```
+
+## 3. 性能指标（Micrometer）
+
+自动记录以下指标，通过 Actuator 查询：
+
+```bash
+# 调用次数
+curl http://localhost:8080/actuator/metrics/feign.client.invocation.count
+
+# 执行时间
+curl http://localhost:8080/actuator/metrics/feign.client.execution.time
+
+# 按标签过滤（某个方法的成功调用）
+curl "http://localhost:8080/actuator/metrics/feign.client.invocation.count?tag=status:success"
+```
+
+## 4. 慢请求检测
+
+请求超过阈值（默认 3000ms）时自动输出 WARN 日志：
+
+```
+WARN: Slow Feign Request Detected: getUserById took 3500ms (threshold: 3000ms)
+```
+
+## 5. 使用场景对比
+
+| 场景 | 配置方式 |
+|:--|:--|
+| 只需 TraceId 传播 | 不指定 `configuration`（默认） |
+| 需要详细日志 + 指标 | 指定 `configuration = FeignLoggingConfiguration.class` |
+| 关闭某个客户端的日志 | 不指定 `configuration` |

package/templates/.claude/skills/avatar-boot-starter-feign/references//345/277/253/351/200/237/346/216/245/345/205/245/346/214/207/345/215/227.md

@@ -0,0 +1,75 @@
+# Feign 快速接入指南
+
+## 1. 添加依赖
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-feign</artifactId>
+</dependency>
+```
+
+## 2. 启用 Feign
+
+在启动类上添加 `@EnableFeignClients`：
+
+```java
+@SpringBootApplication
+@EnableFeignClients
+public class Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}
+```
+
+## 3. 定义 Feign 客户端
+
+### 只需要 TraceId 传播（不打印详细日志）
+
+```java
+@FeignClient(name = "user-service", url = "http://localhost:8080")
+public interface UserServiceClient {
+
+    @GetMapping("/api/users/{id}")
+    User getUserById(@PathVariable("id") Long id);
+
+    @PostMapping("/api/users")
+    User createUser(@RequestBody User user);
+}
+```
+
+### 需要详细请求/响应日志
+
+```java
+import com.iflytek.avatar.boot.config.FeignLoggingConfiguration;
+
+@FeignClient(name = "order-service", url = "http://localhost:8081",
+             configuration = FeignLoggingConfiguration.class)
+public interface OrderServiceClient {
+
+    @PostMapping("/api/orders")
+    Result<Order> createOrder(@RequestBody OrderRequest request);
+}
+```
+
+> `FeignLoggingConfiguration` 需要显式指定，不是默认启用的。
+
+## 4. 注入使用
+
+```java
+@Service
+@RequiredArgsConstructor
+public class UserService {
+
+    private final UserServiceClient userServiceClient;
+
+    public User getUser(Long id) {
+        return userServiceClient.getUserById(id);
+    }
+}
+```
+
+## 5. 验证 TraceId 传播
+
+启动后调用接口，查看下游服务日志中是否包含相同的 TraceId，确认链路追踪生效。

package/templates/.claude/skills/avatar-boot-starter-feign/references//351/205/215/347/275/256/345/217/202/350/200/203.md

@@ -0,0 +1,70 @@
+# Feign 配置参考
+
+## 完整配置项
+
+```yaml
+avatar:
+  feign:
+    logging:
+      enabled: true                    # 启用日志拦截器（含 TraceId 传播，默认 true）
+      request-enabled: true            # 记录请求参数
+      response-enabled: true           # 记录响应数据
+      print-request-details: true      # 打印请求详情（URI、Method、Params）
+      print-response-details: true     # 打印响应详情（含响应体）
+      print-stack-trace: true          # 打印异常堆栈
+      slow-request-threshold: 3000     # 慢请求阈值（毫秒）
+      max-body-length: 1000            # 请求体/响应体最大长度（超出截断）
+      trace-id-header: X-Trace-Id      # TraceId 请求头名称
+    metrics:
+      enabled: true                    # 启用 Micrometer 指标
+```
+
+## 常用场景配置
+
+### 生产环境（只记录错误，不打印响应体）
+
+```yaml
+avatar:
+  feign:
+    logging:
+      print-request-details: false
+      print-response-details: false
+      print-stack-trace: true
+      slow-request-threshold: 2000
+```
+
+### 调试模式（打印所有详情）
+
+```yaml
+avatar:
+  feign:
+    logging:
+      request-enabled: true
+      response-enabled: true
+      print-request-details: true
+      print-response-details: true
+      max-body-length: 5000
+```
+
+### 关闭日志和指标
+
+```yaml
+avatar:
+  feign:
+    logging:
+      enabled: false
+    metrics:
+      enabled: false
+```
+
+### 针对特定客户端配置超时
+
+```yaml
+feign:
+  client:
+    config:
+      user-service:           # FeignClient 的 name
+        connectTimeout: 3000
+        readTimeout: 10000
+        loggerLevel: FULL
+```