release: bump version to 0.50.0

docs/technical/zh/agents-aiprovider.md

@@ -23,11 +23,12 @@
 - 业务层请求整理
 - 稳定的 `/api/v1/ai/...` 接口
 - 面向 `aiprovider` 的内部服务认证
+- 读取配置中心保存的默认 provider、模型和每个 provider 的 key，并通过内部请求头覆盖 `aiprovider` 的 `.env` 默认值
 
 `aiprovider` 负责：
 
 - 模型协议适配
-- 基于 `.env` 选择 provider
+- 在没有后端覆盖头时基于 `.env` 选择 provider
 - 超时和轻量重试
 - 通过 `X-Request-ID` 串联请求追踪
 
@@ -85,6 +86,18 @@
 
 后端会把 `X-Request-ID` 透传给 `aiprovider`，并在响应中返回同一个 header。
 
+### 设置中心 API
+
+AI 配置页使用的接口：
+
+- `GET /api/v1/settings/integrations`
+- `PUT /api/v1/settings/integrations`
+- `POST /api/v1/settings/integrations/ai-provider/connect`
+- `GET /api/v1/settings/integrations/ai-provider/secrets`
+- `GET /api/v1/settings/integrations/ai-provider/presets`
+
+这些接口都需要用户登录。`secrets` 接口只用于配置页点击显示 key/token 时取回明文，隐藏时前端恢复为脱敏预览。
+
 ### AI Provider 内部 API
 
 仅供内部调用的接口：
@@ -172,6 +185,75 @@ curl -X POST http://localhost:8010/v1/analyze \
 
 ## 配置
 
+### 运行时配置链路
+
+LLM 的全局默认配置由后端配置中心统一决定。实际调用顺序是：
+
+1. 前端或业务代码调用 `backend` 的 `/api/v1/ai/...`。
+2. `backend` 从 PostgreSQL 的 `system_settings` 表读取 `category = external_integrations`。
+3. `payload.ai_provider.default_provider` 决定当前默认 provider。
+4. `payload.ai_provider.providers[provider]` 提供该 provider 的 `api_key`、`provider_api`、`base_url`、`model`、`max_tokens`、`anthropic_version`。
+5. `backend` 把这些值转换成 `X-AI-Provider`、`X-AI-Provider-API`、`X-AI-Base-URL`、`X-AI-API-Key`、`X-AI-Model` 等内部请求头。
+6. `aiprovider` 收到头后用这些值覆盖自己的 `.env`，再调用真实模型厂商。
+
+因此，只要 AI 设置页保存了新的默认 provider/model/key，Playground、告警摘要、数据源映射生成等所有后端 AI 调用都会使用同一个新默认配置。
+
+#### 持久化结构
+
+AI 配置仍保存在 PostgreSQL，不写入 JSON 文件。核心结构如下：
+
+```json
+{
+  "ai_provider": {
+    "service_url": "http://localhost:8010",
+    "service_token": "",
+    "default_provider": "openai",
+    "providers": {
+      "openai": {
+        "provider_api": "openai-completions",
+        "base_url": "https://api.openai.com/v1",
+        "model": "gpt-5.1",
+        "api_key": "<saved secret>",
+        "max_tokens": 4096,
+        "anthropic_version": "2023-06-01"
+      },
+      "minimax": {
+        "provider_api": "anthropic-messages",
+        "base_url": "https://api.minimaxi.com/anthropic",
+        "model": "MiniMax-M2.7",
+        "api_key": "<saved secret>",
+        "max_tokens": 1200,
+        "anthropic_version": "2023-06-01"
+      }
+    },
+    "timeout_seconds": 60,
+    "retry_attempts": 2
+  }
+}
+```
+
+历史单槽配置会在读取时兼容映射到当前 provider 的 `providers[provider]`，保存后写回新结构。
+
+#### Key fallback
+
+每个 provider 都有自己的 key 槽。解析顺序是：
+
+1. PostgreSQL 中 `providers[provider].api_key`
+2. `aiprovider/.env` 中 preset 对应的专属变量，例如 `OPENAI_API_KEY`、`MINIMAX_API_KEY`、`ANTHROPIC_API_KEY`
+3. `aiprovider/.env` 中的通用 `AI_API_KEY`
+
+`.env` 只是兜底。配置页保存或测试连接成功后，PostgreSQL 中的配置会成为全局默认。
+
+#### 配置页行为
+
+- Provider 下拉框决定当前默认 provider。
+- 模型下拉框保存当前 provider 的默认模型。
+- LLM API Key 输入框隐藏时显示脱敏预览；有 `-` 前缀的 key 会保留前缀，例如 `sk-********`，没有前缀的 key 全量脱敏。
+- 点击眼睛会从后端取回完整明文；再次隐藏会恢复脱敏预览。
+- “保存 AI 配置”直接保存当前表单为全局默认配置。
+- “测试连接”先用当前表单发起真实模型链路测试，成功后也会保存为全局默认配置；失败不会覆盖旧配置。
+- 清空输入框并保存表示保留旧 key，不表示删除 key。
+
 ### 后端
 
 推荐的后端 `.env`：
@@ -208,6 +290,18 @@ AI_HTTP_RETRY_ATTEMPTS=2
 AI_ANALYSIS_SYSTEM_PROMPT=你是态势感知分析助手。请基于输入的上下文、观测与约束，输出结构化、克制、可执行的分析。
 ```
 
+可选 provider 专属 key：
+
+```env
+MINIMAX_API_KEY=sk-cp-xxxxx
+OPENAI_API_KEY=sk-xxxxx
+ANTHROPIC_API_KEY=sk-ant-xxxxx
+DEEPSEEK_API_KEY=sk-xxxxx
+DASHSCOPE_API_KEY=sk-xxxxx
+MOONSHOT_API_KEY=sk-xxxxx
+OPENROUTER_API_KEY=sk-or-xxxxx
+```
+
 ### OpenAI 兼容示例
 
 ```env