# Hagicode 配置文件理解指南 (LLM 提示词)

## 目的

本文档为 AI/LLM 系统提供统一的配置文件理解和修改指导。LLM 应根据本文档提供的内容，帮助用户理解 Hagicode 应用程序的配置结构并提供配置修改指导。

## 配置文件说明

Hagicode 应用程序使用以下配置文件：

| 文件 | 用途 | 说明 |
|------|------|------|
| `appsettings.yml` | 实际配置文件 | 应用程序启动时加载的配置，由用户根据实际环境修改 |
| `appsettings.default.yml` | 默认配置参考 | 带有详细注释的原始配置文件，用于参考和理解配置项 |

## 配置加载机制

应用程序启动时，按以下顺序加载配置：

1. **读取主配置文件**：应用程序读取 `config/appsettings.yml`
2. **加载默认值**：从程序内部加载配置项的默认值
3. **环境变量覆盖**：支持通过环境变量覆盖配置值
4. **命令行参数**：支持通过命令行参数覆盖配置值

**重要**：用户应通过修改 `appsettings.yml` 来更改应用程序行为，而不是直接修改 `appsettings.default.yml`。

## 配置理解流程

当用户询问配置相关问题时，按以下步骤进行：

1. **读取默认配置**：首先读取 `appsettings.default.yml` 获取完整的配置结构和注释
2. **对比实际配置**：读取 `appsettings.yml` 了解当前的实际配置值
3. **分析配置差异**：比较两个文件，识别哪些配置项已被修改
4. **提供解释**：根据默认配置中的注释解释每个配置项的含义

## 提供配置修改指导

当用户请求配置修改指导时：

1. **识别相关配置项**：从 `appsettings.default.yml` 中找到对应的配置部分
2. **解释配置用途**：使用注释内容解释该配置项的作用
3. **提供修改建议**：指导用户如何在 `appsettings.yml` 中修改该配置项
4. **警告关键配置**：对于可能影响系统稳定性的配置项，给出明确警告

## 配置文件结构

`appsettings.default.yml` 通常包含以下主要配置部分：

- **Logging**：日志配置，控制日志级别和输出方式
- **Serilog**：结构化日志配置，支持多种日志输出方式
- **Server**：服务器配置，包括端口、证书等
- **Database**：数据库连接配置
- **Application**：应用程序特定配置
- **其他组件配置**：如 Orleans、前端配置等

## 注意事项

1. **配置优先级**：命令行参数 > 环境变量 > appsettings.yml > 默认值
2. **配置热更新**：部分配置项支持热更新，无需重启应用程序
3. **敏感信息**：生产环境应使用环境变量或机密管理服务存储敏感配置
4. **配置验证**：应用程序启动时会验证必需的配置项

## 故障排除

### 配置文件不存在

**症状**：应用程序无法启动或提示配置缺失

**解决方案**：
1. 检查 `config/appsettings.yml` 是否存在
2. 如果不存在，从 `appsettings.default.yml` 复制并重命名
3. 根据实际环境修改配置值

### 配置格式错误

**症状**：应用程序启动失败，提示 YAML 解析错误

**解决方案**：
1. 检查 YAML 缩进是否正确（使用空格，不使用 Tab）
2. 检查引号是否配对
3. 使用 YAML 验证工具检查格式

### 配置项未生效

**症状**：修改配置后未看到预期效果

**解决方案**：
1. 确认修改的是 `appsettings.yml` 而非 `appsettings.default.yml`
2. 重启应用程序以加载新配置
3. 检查是否有环境变量覆盖了该配置项