@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

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

@@ -1,901 +1,62 @@
 ---
-name: avatar-boot-nacos-config
-description: Avatar Boot Nacos 配置完整参考 - 服务发现、配置中心和 Spring Cloud Alibaba 集成。当用户提到 Nacos、服务发现、配置中心、配置管理、Spring Cloud Alibaba、服务注册、动态配置时使用此技能，或当用户正在编辑涉及 Nacos 设置的 application.yml/application.properties 文件时触发。当用户询问微服务配置、环境隔离（使用命名空间的 dev/test/prod）、共享配置或排查 Nacos 连接问题时也应触发。此技能提供配置示例、生成完整配置文件、验证最佳实践并提供故障排查指导。
+name: avatar-boot-starter-nacos
+description: Avatar Boot Nacos 模块使用指南。当用户询问服务注册发现、动态配置管理、spring.config.import、配置热更新、多环境隔离、共享配置，或需要接入 avatar-boot-starter-nacos 时触发。
 ---
 
-# Avatar Boot Nacos 配置参考
+# Avatar Boot Starter Nacos 使用指南
 
-Avatar Boot 应用中配置 Nacos 服务发现和配置管理的完整指南。
+你是 Avatar Boot Nacos 模块的使用顾问与开发助手。
 
-## 快速开始
+## 交互流程（必须遵守）
 
-### ⚠️ 重要：Spring Cloud Alibaba 2023.x 配置要求
+**每次被触发时，先通过 AskUserQuestion 工具询问用户意图：**
 
-**Spring Cloud Alibaba 2023.x 强制要求**使用 `spring.config.import` 声明 Nacos 配置源，否则会报错：
-- `No spring.config.import property has been defined`
-- `dataId must be specified`
+问题："您好！我是 Avatar Boot Nacos 模块助手，请问您需要哪方面的帮助？"
+选项：
+1. **快速接入** - 添加依赖、配置 spring.config.import（必须）
+2. **服务注册与发现** - 自动注册、LoadBalanced 服务调用
+3. **动态配置管理** - @Value/@ConfigurationProperties + @RefreshScope 热更新
+4. **共享配置** - 多服务共享配置、扩展配置
+5. **故障排查** - 注册失败、配置加载失败、配置不刷新
 
-### 最小配置
+**根据用户选择，用 Read 工具按下方「文档读取路由」加载对应文档，然后给出具体指导。**
 
-**application.yml** (主配置):
-```yaml
-spring:
-  application:
-    name: my-service  # 必填：服务名称
-
-server:
-  port: 8080
-```
-
-**application-dev.yml** (环境配置):
-```yaml
-spring:
-  config:
-    import:
-      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
-
-  cloud:
-    nacos:
-      server-addr: 127.0.0.1:8848  # 必填：Nacos 服务器地址
-      namespace: ${NACOS_NAMESPACE:dev}
-      username: ${NACOS_USERNAME:nacos}
-      password: ${NACOS_PASSWORD:nacos}
-
-      config:
-        enabled: true
-        file-extension: yaml
-        group: DEFAULT_GROUP
-
-      discovery:
-        enabled: true
-        register-enabled: true
-        ephemeral: true
-```
-
-### 添加依赖
-
-```xml
-<dependency>
-    <groupId>com.iflytek.avatar.boot</groupId>
-    <artifactId>avatar-boot-starter-nacos</artifactId>
-</dependency>
-```
-
-版本由 `avatar-boot-dependency` BOM 管理 - 永远不要显式指定版本。
-
-## 配置方式
-
-### ⚠️ Spring Cloud Alibaba 2023.x 唯一推荐方式
-
-**必须使用 `spring.config.import`**，这是 Spring Cloud Alibaba 2023.x 的强制要求。
-
-#### 正确的配置格式
-
-```yaml
-spring:
-  application:
-    name: avatar-demo-service
-
-  config:
-    import:
-      # 应用配置
-      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
-      # 共享配置
-      - optional:nacos:common-database.yaml?group=SHARED_GROUP&refreshEnabled=true
-      - optional:nacos:common-redis.yaml?group=SHARED_GROUP&refreshEnabled=true
-
-  cloud:
-    nacos:
-      server-addr: 127.0.0.1:8848
-      namespace: ${NACOS_NAMESPACE:}
-      username: ${NACOS_USERNAME:nacos}
-      password: ${NACOS_PASSWORD:nacos}
-
-      config:
-        enabled: true
-        file-extension: yaml
-        group: DEFAULT_GROUP
-
-      discovery:
-        enabled: true
-        register-enabled: true
-        ephemeral: true
-        group: DEFAULT_GROUP
-        metadata:
-          version: 1.0.0
-          environment: ${spring.profiles.active:dev}
-```
-
-**格式说明**:
-- `optional:` - 配置不存在时不会导致启动失败（推荐）
-- `nacos:` - 指定配置源类型
-- `{dataId}` - 配置文件的 Data ID，可使用变量 `${spring.application.name}`
-- `?group=XXX` - 指定配置分组（必需）
-- `&refreshEnabled=true` - 启用配置自动刷新
-
-#### ❌ 常见错误
-
-```yaml
-# 错误 1: 缺少 spring.config.import
-spring:
-  cloud:
-    nacos:
-      config:
-        enabled: true  # ❌ 会报错: No spring.config.import property has been defined
-
-# 错误 2: 空的 dataId
-spring:
-  config:
-    import:
-      - "nacos:"  # ❌ 会报错: dataId must be specified
-
-# 错误 3: 变量未解析
-spring:
-  config:
-    import:
-      - "optional:nacos:${spring.applicyaml"  # ❌ 缺少 group 参数
-
-# 错误 4: 位置错误
-spring:
-  cloud:
-    nacos:
-      config:
-        import:  # ❌ 应该在 spring.config.import，不是这里
-          - "nacos:xxx"
-
-# 错误 5: spring.application.name 定义位置错误
-spring:
-  config:
-    activate:
-      on-profile: dev  # ❌ 不应该在主配置文件中
-  application:
-    name: my-service
-```
-
-#### ✅ 推荐的配置结构
-
-**application.yml** (主配置 - 所有环境共享):
-```yaml
-spring:
-  application:
-    name: avatar-demo-service  # 必须在主配置文件中定义
-
-server:
-  port: 8080
-```
-
-**application-dev.yml** (开发环境):
-```yaml
-spring:
-  config:
-    import:
-      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
-      - optional:nacos:common-database.yaml?group=SHARED_GROUP&refreshEnabled=true
-
-  cloud:
-    nacos:
-      server-addr: 172.29.242.247:8848
-      namespace: dev
-      username: ${NACOS_USERNAME:nacos}
-      password: ${NACOS_PASSWORD:nacos}
-      config:
-        enabled: true
-        file-extension: yaml
-        group: DEFAULT_GROUP
-      discovery:
-        enabled: true
-        register-enabled: true
-        ephemeral: true
-        group: DEFAULT_GROUP
-```
-
-**application-prod.yml** (生产环境):
-```yaml
-spring:
-  config:
-    import:
-      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
-      - optional:nacos:common-database.yaml?group=SHARED_GROUP&refreshEnabled=true
-
-  cloud:
-    nacos:
-      server-addr: nacos-prod.example.com:8848
-      namespace: prod
-      username: ${NACOS_USERNAME}  # 从环境变量读取
-      password: ${NACOS_PASSWORD}
-      config:
-        enabled: true
-        file-extension: yaml
-        group: DEFAULT_GROUP
-      discovery:
-        enabled: true
-        register-enabled: true
-        ephemeral: true
-        group: DEFAULT_GROUP
-```
-
-## 配置详解
-
-### 服务发现配置
-
-```yaml
-spring:
-  cloud:
-    nacos:
-      discovery:
-        enabled: true              # 启用服务发现
-        register-enabled: true     # 注册此服务
-        ephemeral: true           # 临时实例（推荐用于云原生）
-        group: DEFAULT_GROUP      # 服务分组
-        cluster-name: DEFAULT     # 集群名称
-        weight: 1.0              # 服务权重（0.01-100.0）
-
-        # 网络设置
-        prefer-ip-address: true   # 使用 IP 而非主机名
-        # ip: 192.168.1.100       # 手动指定 IP（未设置时自动检测）
-        # port: 8080              # 手动指定端口（未设置时使用 server.port）
-        # network-interface: eth0  # 多网卡场景
-
-        # 健康检查
-        heart-beat-interval: 5000      # 心跳间隔（毫秒）
-        heart-beat-timeout: 15000      # 心跳超时（毫秒）
-        ip-delete-timeout: 30000       # IP 删除超时（毫秒）
-
-        # 元数据 - 用于路由/监控的自定义标签
-        metadata:
-          version: 1.0.0
-          environment: ${spring.profiles.active:dev}
-          region: cn-east
-          team: backend
-```
-
-**实例类型：**
-- **临时实例（Ephemeral）**: `ephemeral: true` - 推荐用于云原生
-    - 下线时自动删除
-    - 维护成本低
-    - 适用于：容器、自动扩缩容
-
-- **持久化实例（Persistent）**: `ephemeral: false` - 传统部署
-    - 下线后仍保留
-    - 需要手动清理
-    - 适用于：虚拟机、固定 IP
-
-### 配置中心配置
-
-```yaml
-spring:
-  cloud:
-    nacos:
-      config:
-        enabled: true                    # 启用配置中心
-        file-extension: yaml             # 配置格式：yaml/properties/json/xml
-        group: DEFAULT_GROUP             # 配置分组
-        refresh-enabled: true            # 启用自动刷新
-
-        # 超时和重试
-        timeout: 3000                    # 连接超时（毫秒）
-        config-long-poll-timeout: 46000  # 长轮询超时（毫秒）
-        config-retry-time: 2000          # 重试间隔（毫秒）
-        max-retry: 10                    # 最大重试次数
-
-        # 远程同步
-        enable-remote-sync-config: false
-```
-
-### 多环境配置
-
-使用 **命名空间（namespaces）** 实现环境隔离：
-
-```yaml
 ---
-# 开发环境
-spring:
-  config:
-    activate:
-      on-profile: dev
-  cloud:
-    nacos:
-      server-addr: 127.0.0.1:8848
-      namespace: dev-namespace-id
-      config:
-        group: DEV_GROUP
-      discovery:
-        group: DEV_GROUP
-
----
-# 测试环境
-spring:
-  config:
-    activate:
-      on-profile: test
-  cloud:
-    nacos:
-      server-addr: nacos-test.example.com:8848
-      namespace: test-namespace-id
-      config:
-        group: TEST_GROUP
-      discovery:
-        group: TEST_GROUP
-
----
-# 生产环境
-spring:
-  config:
-    activate:
-      on-profile: prod
-  cloud:
-    nacos:
-      server-addr: nacos-prod.example.com:8848
-      namespace: prod-namespace-id
-      username: ${NACOS_USERNAME}  # 从环境变量读取
-      password: ${NACOS_PASSWORD}
-      config:
-        group: PROD_GROUP
-      discovery:
-        group: PROD_GROUP
-```
-
-## Nacos 配置文件命名规则
-
-Nacos 按以下顺序自动加载配置：
-
-1. **应用配置**: `${spring.application.name}.${file-extension}`
-    - 示例：`my-service.yaml`
-
-2. **应用+环境配置**: `${spring.application.name}-${profile}.${file-extension}`
-    - 示例：`my-service-dev.yaml`
-
-3. **扩展配置**: 通过 `extension-configs` 指定
-
-4. **共享配置**: 通过 `shared-configs` 指定
-
-**优先级（从高到低）：**
-1. 应用+环境配置
-2. 应用配置
-3. 扩展配置
-4. 共享配置
-
-## 代码使用模式
-
-### 使用 RestTemplate 进行服务发现
-
-```java
-@Configuration
-public class RestTemplateConfig {
-
-    @Bean
-    @LoadBalanced  // 启用服务名解析
-    public RestTemplate restTemplate() {
-        return new RestTemplate();
-    }
-}
-
-@Service
-public class UserService {
-
-    @Autowired
-    private RestTemplate restTemplate;
-
-    public User getUser(Long id) {
-        // 通过服务名调用（而非 IP:端口）
-        return restTemplate.getForObject(
-            "http://user-service/users/" + id,
-            User.class
-        );
-    }
-}
-```
-
-### 使用 @Value 实现动态配置
-
-```java
-@RestController
-@RefreshScope  // 配置热更新必需
-public class ConfigController {
-
-    @Value("${app.feature.enabled:false}")
-    private boolean featureEnabled;
-
-    @GetMapping("/config")
-    public String getConfig() {
-        return "Feature enabled: " + featureEnabled;
-    }
-}
-```
-
-### 使用 @ConfigurationProperties 实现动态配置
-
-```java
-@Component
-@ConfigurationProperties(prefix = "app")
-@RefreshScope  // 配置热更新必需
-@Data
-public class AppConfig {
-    private String name;
-    private String version;
-    private Feature feature;
-
-    @Data
-    public static class Feature {
-        private boolean enabled;
-        private int maxUsers;
-    }
-}
-```
-
-**对应的 Nacos 配置**（Data ID: `my-service.yaml`）：
-
-```yaml
-app:
-  name: My Service
-  version: 1.0.0
-  feature:
-    enabled: true
-    maxUsers: 100
-```
-
-### 监听配置变更
-
-```java
-@Component
-public class ConfigChangeListener {
-
-    @EventListener
-    public void onRefresh(RefreshScopeRefreshedEvent event) {
-        log.info("配置已刷新");
-    }
-
-    @EventListener
-    public void onEnvironmentChange(EnvironmentChangeEvent event) {
-        log.info("环境已变更: {}", event.getKeys());
-    }
-}
-```
-
-## 最佳实践
-
-### 1. 环境隔离策略
-
-**使用命名空间隔离环境：**
-- 开发环境：`dev-namespace`
-- 测试环境：`test-namespace`
-- 生产环境：`prod-namespace`
-
-**使用分组隔离业务域：**
-- 用户服务：`USER_GROUP`
-- 订单服务：`ORDER_GROUP`
-- 支付服务：`PAYMENT_GROUP`
 
-### 2. 配置管理策略
+## 行为准则
 
-- **公共配置**：使用 `shared-configs` 实现跨应用设置
-- **业务配置**：使用应用专属配置
-- **敏感配置**：使用环境变量或加密配置
+1. **回答要具体**：引用具体的配置项、注解
+2. **主动提醒**：Spring Cloud Alibaba 2023.x **必须**使用 `spring.config.import`，这是最常见的坑
+3. **使用中文回答**
+4. **版本说明**：Spring Cloud Alibaba 2023.0.3.2 + Spring Boot 3.5.3
 
-### 3. 元数据使用
-
-添加有用的元数据用于路由和监控：
-
-```yaml
-spring:
-  cloud:
-    nacos:
-      discovery:
-        metadata:
-          version: ${project.version}
-          environment: ${spring.profiles.active}
-          region: cn-east
-          team: backend
-          git-commit: ${git.commit.id.abbrev}
-```
-
-**使用场景：**
-- **灰度发布**：根据版本路由
-- **流量控制**：根据区域路由
-- **监控告警**：按团队分组
-
-### 4. 配置刷新策略
-
-- 对需要热更新的 Bean 使用 `@RefreshScope`
-- 监听 `RefreshScopeRefreshedEvent` 实现自定义刷新逻辑
-- 某些配置（如线程池大小）可能需要重启
-
-### 5. 健康检查配置
-
-```yaml
-management:
-  endpoints:
-    web:
-      exposure:
-        include: health,info,nacos-config,nacos-discovery
-  endpoint:
-    health:
-      show-details: always
-  health:
-    nacos:
-      enabled: true
-```
-
-访问健康检查：
-```bash
-curl http://localhost:8080/actuator/health
-```
-
-## 故障排查指南
-
-### 问题 0：Logback Appender 冲突错误
-
-**症状**：启动时出现以下错误：
-```
-|-ERROR in ch.qos.logback.core.rolling.RollingFileAppender[CONFIG_LOG_FILE] - 'File' option has the same value "C:\Users\xxx/logs/nacos/config.log" as that given for appender [CONFIG_LOG_FILE] defined earlier.
-|-ERROR in ch.qos.logback.core.rolling.RollingFileAppender[CONFIG_LOG_FILE] - Collisions detected with FileAppender/RollingAppender instances defined earlier. Aborting.
-```
-
-**原因**：Nacos 客户端会加载自己的 Logback 配置，创建文件日志 appender（CONFIG_LOG_FILE、NAMING_LOG_FILE、REMOTE_LOG_FILE），与应用的 Logback 配置冲突。
-
-**解决方案**：
-
-1. **在 Application 启动类中禁用 Nacos 文件日志**（推荐）：
-
-```java
-@SpringBootApplication
-public class Application {
-
-    public static void main(String[] args) {
-        // 禁用 Nacos 客户端的文件日志输出,解决 Logback appender 冲突问题
-        // 参考: https://github.com/alibaba/spring-cloud-alibaba/issues/4004
-        // 参考: https://github.com/alibaba/spring-cloud-alibaba/issues/3995
-        System.setProperty("nacos.logging.default.config.enabled", "false");
-        System.setProperty("nacos.logging.config", "");
-
-        SpringApplication.run(Application.class, args);
-    }
-}
-```
-
-2. **在 application.yml 中设置 Nacos 日志级别**（可选）：
-
-```yaml
-logging:
-  level:
-    com.alibaba.nacos: ERROR  # 减少 Nacos 日志输出
-```
-
-3. **不要引用不存在的 logback 配置文件**：
-
-```yaml
-# ❌ 错误：引用不存在的文件
-logging:
-  config: classpath:logback-spring.xml  # 如果文件不存在会导致问题
-
-# ✅ 正确：不指定或确保文件存在
-logging:
-  level:
-    com.alibaba.nacos: ERROR
-```
-
-**关键点**：
-- 必须在 `SpringApplication.run()` **之前**设置系统属性
-- 这会禁用 Nacos 的文件日志，Nacos 日志只会输出到控制台
-- 通过 `logging.level.com.alibaba.nacos` 控制 Nacos 日志级别
-
-**参考资料**：
-- [Spring Cloud Alibaba Issue #4004](https://github.com/alibaba/spring-cloud-alibaba/issues/4004)
-- [Spring Cloud Alibaba Issue #3995](https://github.com/alibaba/spring-cloud-alibaba/issues/3995)
-
-### 问题 1：服务未注册
-
-**症状**：服务未出现在 Nacos 控制台
-
-**诊断步骤：**
-1. 检查 Nacos 服务器地址：`telnet nacos-server 8848`
-2. 启用调试日志：
-   ```yaml
-   logging:
-     level:
-       com.alibaba.nacos: DEBUG
-       com.alibaba.cloud.nacos: DEBUG
-   ```
-3. 验证 `spring.cloud.nacos.discovery.register-enabled=true`
-4. 检查应用名称已设置：`spring.application.name`
-
-**常见原因：**
-- 服务器地址错误
-- 网络/防火墙阻止端口 8848
-- Nacos 服务器未运行
-- 认证失败（用户名/密码错误）
-
-### 问题 2：配置未加载
-
-**症状**：应用无法从 Nacos 加载配置
-
-**常见错误信息**：
-- `No spring.config.import property has been defined`
-- `dataId must be specified`
-- `illegal URI: http://${nacos.server-addr}/...`
-
-**诊断步骤：**
-1. ✅ **检查 spring.config.import 是否存在**
-   ```yaml
-   spring:
-     config:
-       import:
-         - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
-   ```
-
-2. ✅ **检查 spring.config.import 位置是否正确**
-    - 必须在顶层 `spring:` 下
-    - 不能在 `spring.cloud.nacos:` 下
-
-3. ✅ **检查 spring.application.name 是否在主配置文件中定义**
-   ```yaml
-   # application.yml (主配置)
-   spring:
-     application:
-       name: my-service  # 必须在这里定义
-   ```
-
-4. ✅ **检查 dataId 格式是否正确**
-   ```yaml
-   # ✅ 正确
-   - optional:nacos:my-service.yaml?group=DEFAULT_GROUP&refreshEnabled=true
-
-   # ❌ 错误
-   - "nacos:"  # 缺少 dataId
-   - "optional:nacos:${spring.application.name}.yaml"  # 缺少 group 参数
-   ```
-
-5. 验证 Data ID 在 Nacos 控制台中存在
-6. 检查命名空间 ID 正确
-7. 验证分组名称匹配
-8. 确认文件扩展名匹配：`file-extension: yaml`
-
-**解决方案示例：**
-
-```yaml
-# application.yml (主配置)
-spring:
-  application:
-    name: my-service
-
-# application-dev.yml (环境配置)
-spring:
-  config:
-    import:
-      - optional:nacos:${spring.application.name}.yaml?group=DEFAULT_GROUP&refreshEnabled=true
-
-  cloud:
-    nacos:
-      server-addr: 127.0.0.1:8848
-      namespace: dev
-      config:
-        enabled: true
-        file-extension: yaml
-        group: DEFAULT_GROUP
-```
-
-### 问题 3：配置未刷新
-
-**症状**：Nacos 中的配置更改未在应用中更新
-
-**诊断步骤：**
-1. 验证 `spring.cloud.nacos.config.refresh-enabled=true`
-2. 检查 Bean 上有 `@RefreshScope` 注解
-3. 在日志中查找刷新事件
-4. 先用 `@Value` 测试（比 `@ConfigurationProperties` 简单）
-
-**常见原因：**
-- 缺少 `@RefreshScope` 注解
-- 配置无法注入（静态字段、构造函数注入）
-- 某些配置不支持热更新（需要重启）
-
-### 问题 4：服务调用失败
-
-**症状**：`http://service-name/path` 返回错误
-
-**诊断步骤：**
-1. 验证目标服务已在 Nacos 中注册
-2. 检查 RestTemplate 上有 `@LoadBalanced` 注解
-3. 验证服务名称正确（区分大小写）
-4. 先测试直接 IP:端口调用
-5. 检查网络连接
-
-**常见原因：**
-- 缺少 `@LoadBalanced` 注解
-- 服务名拼写错误
-- 目标服务未注册
-- 网络/防火墙问题
-
-### 问题 5：认证失败
-
-**症状**："403 Forbidden" 或 "401 Unauthorized"
-
-**解决方案：**
-```yaml
-spring:
-  cloud:
-    nacos:
-      username: ${NACOS_USERNAME:nacos}
-      password: ${NACOS_PASSWORD:nacos}
-```
-
-在生产环境使用环境变量：
-```bash
-export NACOS_USERNAME=your-username
-export NACOS_PASSWORD=your-password
-```
-
-## 配置生成器
-
-生成 Nacos 配置时，遵循此模板结构：
-
-```yaml
-# 基础结构
-spring:
-  application:
-    name: <服务名称>
-
-  cloud:
-    nacos:
-      server-addr: <NACOS服务器>
-      namespace: <命名空间ID>
-      username: ${NACOS_USERNAME:nacos}
-      password: ${NACOS_PASSWORD:nacos}
-
-      config:
-        enabled: <true|false>
-        file-extension: <yaml|properties|json|xml>
-        group: <分组名称>
-        refresh-enabled: <true|false>
-
-      discovery:
-        enabled: <true|false>
-        register-enabled: <true|false>
-        ephemeral: <true|false>
-        group: <分组名称>
-        metadata:
-          version: <版本>
-          environment: <环境>
-
-# 健康检查
-management:
-  endpoints:
-    web:
-      exposure:
-        include: health,info,nacos-config,nacos-discovery
-  endpoint:
-    health:
-      show-details: always
-
-# 日志
-logging:
-  level:
-    com.alibaba.nacos: INFO
-    com.alibaba.cloud.nacos: INFO
-```
-
-## 验证清单
-
-审查 Nacos 配置时，检查：
-
-- [ ] 已设置 `spring.application.name`
-- [ ] `server-addr` 指向正确的 Nacos 服务器
-- [ ] 命名空间 ID 匹配环境（dev/test/prod）
-- [ ] 配置和发现的分组名称一致
-- [ ] 云原生部署使用 `ephemeral: true`
-- [ ] 生产环境的认证凭据使用环境变量
-- [ ] 需要动态配置时 `refresh-enabled: true`
-- [ ] 元数据包含有用标签（版本、环境）
-- [ ] 健康检查端点已暴露
-- [ ] 生产环境禁用调试日志
-
-## 版本兼容性
-
-- **Spring Boot**: 3.5.3
-- **Spring Cloud**: 2025.0.0
-- **Spring Cloud Alibaba**: 2023.0.3.2
-- **Java**: 21
-
-**重要**：Spring Boot 3.x 不再使用 `bootstrap.yml` - 所有配置都在 `application.yml` 中。
-
-## 参考文档
-
-- [Spring Cloud Alibaba Nacos](https://github.com/alibaba/spring-cloud-alibaba/wiki/Nacos-config)
-- [Nacos 官方文档](https://nacos.io/zh-cn/docs/what-is-nacos.html)
-- [Spring Cloud LoadBalancer](https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#spring-cloud-loadbalancer)
-
-## 常见场景
-
-### 场景 1：仅服务发现的简单服务
-
-```yaml
-spring:
-  application:
-    name: simple-service
-  cloud:
-    nacos:
-      server-addr: 127.0.0.1:8848
-      discovery:
-        enabled: true
-      config:
-        enabled: false  # 禁用配置中心
-```
-
-### 场景 2：仅配置中心（无服务注册）
-
-```yaml
-spring:
-  application:
-    name: config-consumer
-  cloud:
-    nacos:
-      server-addr: 127.0.0.1:8848
-      config:
-        enabled: true
-      discovery:
-        enabled: false  # 禁用服务发现
-```
-
-### 场景 3：多配置加载
-
-```yaml
-spring:
-  cloud:
-    nacos:
-      config:
-        extension-configs:
-          - data-id: database.yaml
-            group: COMMON_GROUP
-            refresh: true
-          - data-id: redis.yaml
-            group: COMMON_GROUP
-            refresh: true
-          - data-id: kafka.yaml
-            group: COMMON_GROUP
-            refresh: true
-```
-
-### 场景 4：使用元数据的灰度发布
-
-```yaml
-spring:
-  cloud:
-    nacos:
-      discovery:
-        metadata:
-          version: 2.0.0-beta
-          gray: true
-          canary-weight: 10
-```
+---
 
-然后使用自定义路由规则将 10% 的流量导向此版本。
+## 文档读取路由
 
-## 快速命令参考
+> 所有路径相对于 skill 目录 `docs/skills/avatar-boot-starter-nacos-skill/`
 
-```bash
-# 检查 Nacos 连接
-telnet nacos-server 8848
+| 用户需求 | 需读取的文件 |
+|:--|:--|
+| 快速接入 / spring.config.import | `references/快速接入与配置.md` |
+| 服务注册与发现 / 动态配置 / 共享配置 | `references/功能使用.md` |
+| 故障排查 | `references/故障排查.md` |
 
-# 查看健康状态
-curl http://localhost:8080/actuator/health
+---
 
-# 查看 Nacos 服务发现信息
-curl http://localhost:8080/actuator/nacos-discovery
+## 通用参考信息
 
-# 查看 Nacos 配置信息
-curl http://localhost:8080/actuator/nacos-config
+### 配置文件命名规则
 
-# 启用调试日志（添加到 application.yml）
-logging.level.com.alibaba.nacos=DEBUG
-```
+Nacos 自动加载（优先级从高到低）：
+1. `{appName}-{profile}.yaml`
+2. `{appName}.yaml`
+3. 扩展配置（extension-configs）
+4. 共享配置（shared-configs）
 
----
+### 关键注意事项
 
-**何时使用此技能：**
-- 配置新的 Avatar Boot 服务使用 Nacos
-- 排查 Nacos 连接或配置问题
-- 设置多环境配置
-- 实现服务发现
-- 设置动态配置管理
-- 审查 Nacos 配置的最佳实践
-- 从其他服务发现解决方案迁移
+- `spring.config.import` 必须配置，否则启动报错
+- `optional:` 前缀表示配置不存在时不报错（推荐）
+- `@RefreshScope` 注解才能支持配置热更新
+- 推荐用 `namespace` 隔离环境，用 `group` 隔离业务