Add files via upload

2026-08-05 18:38:52 +02:00 · 2026-07-23 19:14:09 +08:00
parent 273d63413b
commit f285d47404
14 changed files with 209 additions and 72 deletions
@@ -12,9 +12,9 @@
 vision:
  enabled: true
  model: qwen-vl-max   # 必填
-  api_key:             # 留空 → openai.api_key
-  base_url:            # 留空 → openai.base_url
-  provider:            # 留空 → openai.provider
+  api_key:             # 留空 → 默认 AI 通道 api_key
+  base_url:            # 留空 → 默认 AI 通道 base_url
+  provider:            # 留空 → 默认 AI 通道 provider
  max_image_bytes: 5242880
  max_dimension: 2048
  jpeg_quality: 82
@@ -28,7 +28,7 @@ vision:

 ## Web 设置

-**系统设置 → 基本设置 → 视觉分析（analyze_image）** 可配置启用开关、视觉模型、API Key/Base URL（留空复用 OpenAI）、预处理参数；**保存并应用** 后写入 `config.yaml` 并重新注册 MCP 工具。
+**系统设置 → 基本设置 → 视觉分析（analyze_image）** 可配置启用开关、视觉模型、API Key/Base URL（留空复用默认 AI 通道）、预处理参数；**保存并应用** 后写入 `config.yaml` 并重新注册 MCP 工具。

 ## 路径

@@ -52,6 +52,18 @@ Content-Type: application/json
 - `plan_execute`
 - `supervisor`

+常用请求体字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `message` | 用户消息，必填。 |
+| `conversationId` | 继续已有对话；为空时创建新对话。 |
+| `projectId` | 新对话绑定项目；为空时可跟随 `config.project.default_project_id`。 |
+| `role` | 使用指定角色。 |
+| `aiChannelId` | 选择 `ai.channels` 中的通道 ID；为空时使用 `ai.default_channel`。 |
+| `reasoning` | 会话级推理覆盖，受通道 `reasoning.allow_client_reasoning` 控制。 |
+| `hitl` | 会话级人机协同配置。 |
+
 对话管理：

 - `POST /api/conversations`
@@ -29,26 +29,57 @@ log:
 - `auth.session_duration_hours`：登录会话有效期（小时）。登录密码由 RBAC 用户管理，首次启动时在控制台输出 `admin` 初始密码。
 - `log.output`：可以是 `stdout`、`stderr` 或文件路径。

-## 模型配置
+## AI 通道与模型配置

 ```yaml
-openai:
-  provider: openai
-  base_url: https://api.openai.com/v1
-  api_key: sk-...
-  model: gpt-4.1
-  max_total_tokens: 120000
-  reasoning:
-    mode: on
-    effort: high
-    allow_client_reasoning: true
-    profile: openai_compat
+ai:
+  default_channel: openai-main
+  channels:
+    openai-main:
+      name: OpenAI Main
+      provider: openai_compatible
+      base_url: https://api.openai.com/v1
+      api_key: sk-...
+      model: gpt-4.1
+      max_total_tokens: 120000
+      max_completion_tokens: 16384
+      reasoning:
+        mode: on
+        effort: high
+        allow_client_reasoning: true
+        profile: openai_compat
+    claude-main:
+      name: Claude Main
+      provider: claude
+      base_url: https://api.anthropic.com/v1
+      api_key: sk-ant-...
+      model: claude-sonnet-4-5
 ```

- `provider`：`openai` 表示 OpenAI 兼容接口；`claude` 会桥接到 Anthropic Claude Messages API。
- `base_url/api_key/model`：主模型配置。
- `max_total_tokens`：上下文压缩、攻击链构建、多代理摘要等共用的总预算。
- `reasoning`：控制推理扩展字段。不同网关支持差异较大，异常时先尝试 `mode: off`。
+`ai` 是推荐的模型配置入口。系统设置页对应路径是 **系统设置 → 基本设置 → AI 通道配置**，保存后写入 `ai.default_channel` 和 `ai.channels`。旧版 `openai` 字段仍保留为兼容运行时字段；加载配置时会确保至少有一个默认通道，并把 `ai.default_channel` 解析后的配置同步到运行时 `openai`。
+
+通道字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `ai.default_channel` | 默认通道 ID。新对话、机器人、批量任务和未显式选择通道的请求使用它。 |
+| `ai.channels.<id>` | 通道配置。ID 会归一化为小写、数字和短横线，例如 `Qwen_Max` 会变成 `qwen-max`。 |
+| `name` | Web UI 展示名。留空时使用通道 ID。 |
+| `provider` | `openai_compatible` 或 `claude`。`openai_compatible` 会在运行时映射为 `openai`；`claude` 会桥接到 Anthropic Messages API。 |
+| `base_url/api_key/model` | 必填。Base URL 通常需要包含版本路径，如 OpenAI/兼容网关的 `/v1`。 |
+| `max_total_tokens` | 上下文压缩、攻击链构建、多代理摘要等共用的总预算。 |
+| `max_completion_tokens` | 单次模型输出上限；未填时使用默认值。 |
+| `reasoning` | 该通道的默认推理扩展字段。不同网关支持差异较大，异常时先尝试 `mode: off`。 |
+
+对话页的“AI 通道”下拉框会读取已保存通道。请求体中的 `aiChannelId` 非空时仅对本次/本会话运行配置生效，不会把 API Key 发送给模型；为空时跟随 `ai.default_channel`。
+
+常用操作：
+
+- 新增：点击左侧 `+`，填写必填字段后保存。
+- 设默认：选中通道后点击“设为默认”，保存并应用后新请求生效。
+- 复制：以当前表单内容创建副本，适合为同一服务商配置不同模型。
+- 删除：默认通道不能作为批量删除目标；删除后需保留至少一个通道。
+- 探活：单通道“测试连接”或左侧“批量探活”会调用模型测试接口，适合验证 Key、Base URL 和模型名。

 ## Agent

@@ -213,7 +244,8 @@ project:

 | 配置段 | 应用后通常立即生效 | 需要额外动作 |
 | --- | --- | --- |
-| `openai` | 新请求使用新模型配置 | 旧的流式请求不会被强制切换 |
+| `ai.default_channel` / `ai.channels` | 新请求使用解析后的默认或选定通道 | 旧的流式请求不会被强制切换；前端通道列表需要重新读取配置 |
+| `openai` | 兼容字段；通常由默认 AI 通道同步 | 新配置优先维护 `ai.channels` |
 | `agent.max_iterations` | 新 Agent 任务生效 | 已运行任务按启动时状态继续 |
 | `security.tool_description_mode` | 工具重新暴露时生效 | 模型已有上下文不会回滚 |
 | `hitl.tool_whitelist` | 新工具调用审批判断生效 | 已挂起审批不自动重判 |
@@ -228,7 +260,7 @@ project:
 几个字段有“留空复用”的关系：

 - `vision.api_key/base_url/provider` 留空时复用 `openai`。
- `hitl.audit_model` 留空时复用 `openai`。
+- `hitl.audit_model` 留空时复用默认 AI 通道解析后的 `openai`。
 - `knowledge.embedding.base_url/api_key` 留空时复用主模型或 embedding 默认配置。
 - `knowledge.retrieval.rerank.base_url/api_key` 留空时复用 embedding/openai。
 - `database.knowledge_db_path` 留空时可以复用主会话数据库，但独立文件更利于备份。
@@ -10,7 +10,7 @@
 - Python：部分 MCP 服务或工具脚本需要 Python 运行环境。
 - SQLite：默认使用文件型数据库，无需单独服务。
 - 安全工具：`tools/` 中的 YAML 只是工具定义，实际命令如 `nmap`、`sqlmap`、`nuclei` 仍需安装到系统 PATH。
- 模型服务：需要 OpenAI 兼容 API，或配置 `openai.provider: claude` 走 Claude 桥接。
+- 模型服务：至少配置一个 `ai.channels` 通道；`provider: openai_compatible` 适用于 OpenAI 兼容 API，`provider: claude` 会走 Claude 桥接。

 建议目录：

@@ -23,12 +23,12 @@ hitl:
    provider: ""
    base_url: ""
    api_key: ""
-    model: "" # 可填小模型；留空复用 openai.model
+    model: "" # 可填小模型；留空复用默认 AI 通道的模型
  retention_days: 90
  tool_whitelist: [read_file, list_dir, glob, grep, tool_search]
 ```

-`audit_model` 的字段可以只填一部分。空字段会自动继承主 `openai` 配置，因此常见做法是只填 `model`，让审计 Agent 使用更便宜的小模型。
+`audit_model` 的字段可以只填一部分。空字段会自动继承默认 AI 通道解析后的模型配置，因此常见做法是只填 `model`，让审计 Agent 使用更便宜的小模型。

 ## 推荐审批策略

@@ -44,17 +44,20 @@ HASH=$(htpasswd -nBC 10 '' | cut -d: -f2 | tr -d '\n') && sqlite3 data/conversat

 检查：

- `openai.base_url` 是否包含正确路径，如 `/v1`。
- `openai.api_key` 是否有效。
- `openai.model` 是否存在。
- 服务商是否支持当前 `reasoning` 字段。
+- 当前对话选择的 AI 通道是否存在；为空时会使用 `ai.default_channel`。
+- `ai.channels.<id>.base_url` 是否包含正确路径，如 `/v1`。
+- `ai.channels.<id>.api_key` 是否有效。
+- `ai.channels.<id>.model` 是否存在。
+- 服务商是否支持当前通道的 `reasoning` 字段。

 可在系统设置中使用模型测试。若网关报 400，先尝试：

 ```yaml
-openai:
-  reasoning:
-    mode: off
+ai:
+  channels:
+    your-channel:
+      reasoning:
+        mode: off
 ```

 ## 流式输出中断