docs(provider): 补充模型服务商配置说明

2026-09-18 16:48:30 +08:00
parent 6b365d9953
commit 3000274c77
7 changed files with 71 additions and 3 deletions
@@ -34,6 +34,7 @@ replacedBy: null
 erDiagram
    AUTH_USER ||--o| USER_PROFILE : has
    AUTH_USER ||--o{ AGENT_RUN : owns
+    AUTH_USER ||--o{ MODEL_PROVIDER_CONFIG : owns
    AGENT_RUN ||--o{ AGENT_RUN_EVENT : contains
    AGENT_RUN ||--o{ TOOL_CALL : contains
    AGENT_RUN ||--o{ HUMAN_APPROVAL : requests
@@ -89,6 +90,21 @@ erDiagram
 - `lock_version >= 0`。
 - token、耗时和费用非负。

+### 4.2.1 `agent_runtime_model_provider_config`
+
+| 字段 | 类型建议 | 说明 |
+| --- | --- | --- |
+| `owner_id` | `ForeignKey(PROTECT)` | 用户私有归属 |
+| `provider_code` | `CharField` | 对应代码中的服务商稳定编码 |
+| `encrypted_api_key` | `TextField` | Fernet 密文，禁止通过页面或 Admin 展示 |
+| `key_hint` | `CharField` | 仅保存末四位提示 |
+| `status`、`enabled`、`is_default` | 状态字段 | 连接状态和当前默认选择 |
+| `default_model_id` | `CharField` | 用户选择或预设推荐模型 |
+| `available_models` | `JSONField` | 最近一次验证取得的模型标识快照 |
+| `last_verified_at`、`last_error_code` | 审计字段 | 验证时间和稳定错误码 |
+
+唯一约束为 `(owner_id, provider_code)`。API Key 加密主密钥只从部署环境读取，不进入数据库；主密钥轮换必须先完成密文重加密，不能直接替换后重启。
+
 跨字段状态不变量仍由服务层验证，因为 SQLite 与 PostgreSQL 对复杂检查约束和时间语义的行为需要保持一致。

 ### 4.3 `agent_runtime_agent_run_event`
@@ -49,6 +49,7 @@ replacedBy: null
 | 个人资料 | `/accounts/profile/` | 普通用户、管理员 | 查看和修改自己的资料 |
 | 运行列表 | `/runs/` | 普通用户、管理员 | 查看当前用户的运行记录 |
 | 运行详情 | `/runs/<uuid>/` | 记录所属用户、管理员 | 查看状态、事件和工具调用摘要 |
+| API 服务商 | `/runs/providers/` | 普通用户、管理员 | 搜索、筛选并配置自己的模型服务商 |
 | 管理后台 | `/admin/` | 管理员 | 管理用户和审计记录 |

 登录成功默认进入运行列表；退出成功返回登录页。详情页返回列表时保留原分页参数，非法或越权的运行编号统一展示 404 页面。
@@ -114,6 +115,15 @@ replacedBy: null

 详情页不展示 API Key、Cookie、密码、完整工具参数或原始模型敏感内容。

+### 4.6 API 服务商页
+
+- 使用服务商卡片目录展示官方直连、国内平台、聚合平台和云平台。
+- 卡片明确区分“仅 API Key”和“需要额外配置”，未完成专用适配的平台不开放保存操作。
+- 配置抽屉只接收 API Key、可选模型标识和是否设为默认服务商；Base URL 与协议由服务端预设。
+- 页面只显示密钥末四位提示，保存后不可读取完整密钥。
+- 连接测试通过后才替换已有配置；失败输入不得破坏原有可用密钥。
+- 搜索与分类使用 GET 查询参数，保存和移除使用 POST、CSRF 与重定向。
+
 ## 5. 模板复用边界

 建议模板层级：
@@ -94,6 +94,24 @@ replacedBy: null
 - 事件和完成的工具调用设置为只读或限制修改。
 - 人工确认处理必须调用领域服务，不能只修改单个状态字段。

+### 3.7 模型服务商配置
+
+`GET /runs/providers/`
+
+- 返回内置服务商目录、当前用户连接状态、搜索和分类结果。
+- 不返回密文 API Key，已配置密钥只显示末四位提示。
+
+`POST /runs/providers/<provider_code>/configure/`
+
+- 输入：API Key、可选默认模型、是否设为默认服务商。
+- 服务端按固定预设端点请求模型目录；验证成功后才加密保存。
+- 验证失败返回安全错误说明，不透传上游正文，不覆盖旧密钥。
+
+`POST /runs/providers/<provider_code>/disconnect/`
+
+- 只删除当前用户对应配置；删除默认配置后自动选择一个剩余可用配置。
+- GET 请求不得删除或修改配置。
+
 ## 4. 表单契约

 ### 4.1 登录表单