# 配置参考 / Configuration Reference

`config.toml` 是 dstalk 的唯一配置文件，放在项目根目录。本文档列出所有支持字段、类型、默认值与使用说明。

---

## 配置概览

配置分为两种模式：

| 模式 | 适用场景 | 核心 key |
|------|----------|----------|
| **单 Provider** | 只需一个 AI 后端 | `ai.provider`, `api.*` |
| **多 Endpoint** | 同时配置多个 AI 后端，运行时切换 | `endpoints.names`, `endpoint.<name>.*` |

两种模式可以同时配置，但 `ai_endpoint_mgr` 的 `chat` / `chat_stream` 调用优先走 `endpoints.*`。

---

## 一、单 Provider 模式 (Legacy)

直接在 `[global]` 下声明。这些 key 无默认值——不配置则无法启动 AI 对话。

### ai.provider

- **类型**: string
- **默认**: 无（必填）
- **值**: `"ai_openai"` 或 `"ai_anthropic"`
- **说明**: 指定要加载的 AI provider 插件。该名称对应插件 DLL 注册的服务名。

### api.base_url

- **类型**: string
- **默认**: 无（必填）
- **说明**: AI API 的基础 URL。例如:
  - OpenAI: `https://api.openai.com/v1`
  - Anthropic: `https://api.anthropic.com`
  - DeepSeek (OpenAI 兼容): `https://api.deepseek.com/v1`

### api.api_key

- **类型**: string
- **默认**: 无（必填）
- **说明**: API 密钥。注意保管，不要提交到版本控制。

### api.model

- **类型**: string
- **默认**: 无（必填）
- **说明**: 要使用的模型名称。例如 `gpt-4o`、`claude-sonnet-4-20250514`、`deepseek-chat`。

---

## 二、多 Endpoint 模式 (推荐)

由 `ai_endpoint_mgr` 插件管理。每个 endpoint 是一个命名的 AI 后端配置，运行时可通过 `/endpoint` 命令切换。

### endpoints.names

- **类型**: string (逗号分隔)
- **默认**: 无
- **说明**: 所有要启用的 endpoint 名称列表。例如 `"openai_main, anthropic_alt"`。重复名称会被跳过并输出警告。

### endpoints.active

- **类型**: string
- **默认**: 取 `endpoints.names` 中第一个成功加载的 endpoint
- **说明**: 启动时默认使用的 endpoint 名称。如果指定的名称不在 `endpoints.names` 中或对应配置无效，则回退到第一个成功加载的 endpoint。

---

### endpoint.\<name\>.provider

- **类型**: string
- **默认**: 无（必填）
- **值**: `"ai_openai"` 或 `"ai_anthropic"`
- **说明**: 该 endpoint 使用的 AI provider 服务名称。

### endpoint.\<name\>.base_url

- **类型**: string
- **默认**: 按 provider 自动推导
- **说明**: 
  - 未配置时，已知 provider 自动使用默认 base_url:
    - `ai_anthropic` → `https://api.anthropic.com`
    - `ai_openai` → `https://api.openai.com/v1`
  - 如果 provider 不在已知列表中，**必须**显式配置 `base_url`，否则该 endpoint 加载失败。
  - 显式配置的值优先于默认值，可用于自定义端点（如代理、DeepSeek 兼容 API 等）。

### endpoint.\<name\>.api_key

- **类型**: string
- **默认**: 无（必填）
- **说明**: 该 endpoint 的 API 密钥。

> **安全提示**: `api_key` **不会**出现在 `list_json()` 的输出中，也不进入日志。这是有意为之的安全策略。

### endpoint.\<name\>.model

- **类型**: string
- **默认**: 无（必填）
- **说明**: 该 endpoint 默认使用的模型名称。运行时可通过 `set_model()` 修改并同步回 `config.toml`。

### endpoint.\<name\>.max_tokens

- **类型**: integer
- **默认**: `4096`
- **范围**: `1` ~ `1000000`（超出范围的值视为无效，回退到默认值）
- **说明**: 每次请求的最大输出 token 数。

### endpoint.\<name\>.temperature

- **类型**: double
- **默认**: `0.7`
- **范围**: `0.0` ~ `2.0`（超出范围的值视为无效，回退到默认值）
- **说明**: 生成温度。越高随机性越强，越低越确定性。

---

## 三、ui 配置 (可选 / optional)

以下 key 目前为 CLI 前端预留，后续 GUI/Web 前端也会使用。

### ui.prompt

- **类型**: string
- **默认**: `"> "`
- **说明**: 命令行提示符字符串。

### ui.multiline

- **类型**: string
- **默认**: `"/"` （即不支持多行输入）
- **说明**: 多行输入结束符。发送该字符串结束多行输入模式。

---

## 四、完整配置示例

见项目根目录 `config.example.toml`。

---

## 五、运行时 endpoint 操作

`ai_endpoint_mgr` 服务提供以下接口（通过 C ABI）供前端调用:

| 操作 | 说明 |
|------|------|
| `count()` | 返回已加载的 endpoint 数量 |
| `list_json()` | 返回 JSON 数组，每项含 `name`, `provider`, `base_url`, `model`, `active` （不含 `api_key`） |
| `get_active()` | 返回当前激活的 endpoint 名称 |
| `set_active(name)` | 切换激活 endpoint；返回 0 成功，-2 表示不存在 |
| `set_model(name, model)` | 修改 endpoint 的模型并同步到 config；name 为 null 时作用于当前 active endpoint |
| `chat(ep, history, len, input, tools)` | 路由对话到指定 endpoint（ep 为 null 时用 active） |
| `chat_stream(ep, history, len, input, cb, userdata)` | 流式路由对话 |