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

docs/agent-contract.md

@@ -39,6 +39,8 @@
 
 运行上下文至少包含 `user_id`、`agent_run_id`、`search_task_id`、个人画像版本、规则版本、评分配置版本和当前运行预算。上下文不包含网站明文密码、Cookie、模型 API Key 等敏感值；工具在服务端根据授权范围读取凭据。
 
+模型运行配置在 Gateway 调用前根据当前用户的默认服务商解析。Agent 上下文和持久化运行请求只记录服务商编码与模型标识，不携带可解密密文或明文 API Key。服务商配置缺失、密钥不可解密或默认模型为空时，应在真实调用前以配置错误终止，不影响登录、配置页和历史运行查询。
+
 ## 人工确认边界
 
 以下情况必须暂停或转人工处理：

docs/architecture.md

@@ -41,6 +41,15 @@ Agent 不是对岗位描述进行一次总结的接口，而是任务执行主
 - 保存 run、turn、tool call、tool result、trace、耗时、token 用量、异常和人工确认状态。
 - 第一版不使用 SandboxAgent；业务只需受控网络和数据库工具，不需要开放 Shell 或任意文件执行能力。
 
+## 模型服务商配置边界
+
+- 普通用户通过 Django 服务端页面维护自己的模型服务商配置，配置之间按用户归属隔离。
+- 服务商公开协议、基础地址和推荐模型由代码预设；页面不能提交或覆盖预设地址，避免形成任意网络请求入口。
+- OpenAI、Claude、DeepSeek、Gemini、阿里云百炼、智谱、硅基流动及常见聚合平台按各自协议验证模型目录；验证请求不发送对话内容，不产生模型推理调用。
+- API Key 使用独立部署主密钥进行可逆加密，数据库、页面、日志、Agent 上下文和运行摘要均不得出现明文。
+- Azure OpenAI、AWS Bedrock 及需要地域、部署、IAM 或业务空间参数的平台只展示接入状态，不得误标为只填 API Key 即可使用。
+- 真实 Gateway 在执行边界按当前用户解析默认服务商、模型和密钥；密钥不会进入 `AgentExecutionRequest`。
+
 ## 用户与权限边界
 
 - 使用 Django 内置认证、Session 和密码管理能力。

docs/roadmap.md

@@ -20,10 +20,11 @@ replacedBy: null
 - [x] 为用户私有业务数据建立统一归属边界。
 - [ ] 开发与测试默认使用SQLite，并建立可切换PostgreSQL的迁移基线。
 - [ ] 接入OpenAI Agents SDK。
+- [x] 建立用户级模型服务商目录、API Key 加密存储、连接验证和运行时配置解析。
 - [x] 建立Agent Run、运行事件、工具调用和人工确认模型。
 - [ ] 增加统一日志、测试和代码质量工具。
 
-当前状态：用户资料、数据归属、Agent 运行持久化、最小页面及 SDK 测试替身编排闭环已经落地；真实 Agents SDK 接入仍属于第二阶段。第一阶段剩余 PostgreSQL 集成验证、Ruff/pytest 环境同步、生产配置检查及人工页面验收。
+当前状态：用户资料、数据归属、Agent 运行持久化、模型服务商配置页及 SDK 测试替身编排闭环已经落地；真实 Agents SDK 接入仍属于第二阶段。第一阶段剩余 PostgreSQL 集成验证、生产配置检查及人工页面验收。
 
 验收条件：开发与生产配置隔离，用户可以安全登录，SQLite下迁移和测试通过，PostgreSQL空库迁移及核心模型测试通过，最小Agent运行数据可持久化。