XiuChengWu
4745ce1f1c
Some checks failed
- Introduced `ai_endpoint_mgr` plugin to manage multiple AI provider endpoints. - Added configuration reference documentation for `config.toml`. - Implemented endpoint loading, active endpoint switching, and model mutation. - Included error handling for missing endpoints and configuration failures. - Developed unit tests covering various scenarios including error paths and concurrency.
5.0 KiB
5.0 KiB
配置参考 / 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
- OpenAI:
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.comai_openai→https://api.openai.com/v1
- 如果 provider 不在已知列表中，必须显式配置
base_url，否则该 endpoint 加载失败。 - 显式配置的值优先于默认值，可用于自定义端点（如代理、DeepSeek 兼容 API 等）。
- 未配置时，已知 provider 自动使用默认 base_url:
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) |
流式路由对话 |