# 配置文件

项目使用 YAML 配置文件，配置文件为启动时的必传参数，支持通过 JSON Schema 编辑器提示和显式变量引用。配置中的相对路径均基于配置文件所在目录解析，绝对路径保持不变。

## 配置文件

复制 config.example.yaml 为 config.yaml（或任意名称），根据需要修改：

```yaml
# yaml-language-server: $schema=./config.schema.json
server:
  listen:
    host: "127.0.0.1"
    port: 3000
  storage:
    dataDir: ./data
  logging:
    level: info
    console:
      level: info
    file:
      level: info
      path: "./logs/alfred.log"
      rotation:
        size: 50MB
        frequency: daily
        maxFiles: 14
```

## server.listen

| 字段 | 类型   | 说明                     |
| ---- | ------ | ------------------------ |
| host | string | 监听地址，默认 127.0.0.1 |
| port | number | 监听端口，默认 3000      |

## server.storage

| 字段    | 类型   | 说明                                                                                                                |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| dataDir | string | 数据目录，默认 ./data，相对路径基于配置文件目录解析。目录下存储 alfred.db（SQLite 数据库）和 backups/（数据库备份） |

## server.logging

| 字段  | 类型   | 说明                                                         |
| ----- | ------ | ------------------------------------------------------------ |
| level | string | 全局日志级别（trace/debug/info/warn/error/fatal），默认 info |

### server.logging.console

| 字段  | 类型   | 说明                                              |
| ----- | ------ | ------------------------------------------------- |
| level | string | 控制台日志级别，未设置时继承 server.logging.level |

### server.logging.file

| 字段  | 类型   | 说明                                            |
| ----- | ------ | ----------------------------------------------- |
| level | string | 文件日志级别，未设置时继承 server.logging.level |
| path  | string | 日志文件路径，默认 <dataDir>/logs/alfred.log    |

### server.logging.file.rotation

| 字段      | 类型   | 说明                                          |
| --------- | ------ | --------------------------------------------- |
| size      | string | 按大小轮转，支持 B/KB/MB/GB 单位，默认 50MB   |
| frequency | string | 按时间轮转（hourly/daily/weekly），默认 daily |
| maxFiles  | number | 最大归档文件数，默认 14                       |

## JSON Schema

根目录 config.schema.json 为配置文件的 JSON Schema，支持 IDE 自动补全和校验。

```bash
bun run schema        # 重新生成 config.schema.json
bun run schema:check  # 校验 config.schema.json 是否同步
```

## 变量语法

YAML 配置中支持显式变量引用：

```text
${KEY}        引用变量，未定义时报错
${KEY|value}  引用变量，未定义时使用默认值
${KEY|}       引用变量，未定义时使用空字符串
$${KEY}       转义，输出 ${KEY} 原文字面量
```

变量解析优先级：variables 字段 > process.env > 默认值 > unresolved 报错

完整变量引用（整个值只有 ${...}）保留原始类型：${PORT|3000} 解析为 number 3000。部分拼接统一转为 string。

## 配置优先级

```
variables 字段 > 环境变量 > 默认值 > unresolved 报错
```

环境变量不会隐式覆盖配置，只有通过 ${KEY} 显式引用时才生效。

## 使用自定义配置

```bash
bun run dev custom-config.yaml
```