[feat] 添加 LLM 供应商注册与扩展文档，更新指南以包含新功能链接

site/content/docs/guide/_index.md

@@ -10,6 +10,7 @@ description: "聚焦怎么开发、怎么协作、怎么接入前后端能力的
 - [后端说明](/docs/guide/backend/)
 - [OpenAPI](/docs/guide/openapi/)
 - [AI 工作流](/docs/guide/ai-workflow/)
+- [LLM 供应商注册与扩展](/docs/guide/llm-provider-registration/)
 
 相关文档已拆分到独立栏目：
 

site/content/docs/guide/llm-provider-registration.md

@@ -0,0 +1,84 @@
+---
+title: "LLM 供应商注册与扩展"
+weight: 12
+description: "如何在代码中注册内置供应商能力，并与异步任务执行器对齐。"
+---
+
+系统里与「供应商」相关的概念分两层，扩展时通常要同时考虑。
+
+## 两层注册分别解决什么
+
+1. **能力注册表（内置、进程内）**  
+   描述「我们认识哪些供应商 key、别名、支持哪些模型类别、默认 base URL」等。  
+   实现位于 `app/services/llm/provider_registry.py`，启动时通过 `app/services/llm/provider_bootstrap.py` 的 `bootstrap_builtin_providers()` 调用 `register_many(...)` 写入。  
+   对外只读入口：`GET /api/v1/llm/providers/supported`（可按 `category` 过滤），供前端展示可选能力与默认值提示。
+
+2. **任务执行器注册表（任务类型 × 供应商 key）**  
+   描述「某类异步任务（如图片生成、视频生成）在某个供应商 key 上由哪个工厂函数构造执行器」。  
+   实现位于 `app/core/tasks/registry.py`，启动时通过 `app/core/tasks/bootstrap.py` 的 `bootstrap_task_adapters()` 注册。  
+   Worker 或内联执行路径会按任务 payload 里的供应商信息解析到具体实现。
+
+3. **出站 HTTP 适配层（`app/core/integrations/`）**  
+   OpenAI / 火山等供应商的 URL、请求体、响应解析集中在 `app/core/integrations/openai/`与 `app/core/integrations/volcengine/`（图片、视频分文件）；`ImageGenerationTask` / `VideoGenerationTask` 只做生命周期与轮询节奏，**不**直接拼 httpx 细节。  
+   与任务输入输出共用的 Pydantic 模型放在 `app/core/tasks/image_generation_types.py`、`video_generation_types.py`，避免 `tasks` 与 `integrations` 循环导入。
+
+应用启动时由 `app/bootstrap.py` 的 `bootstrap_all_registries()` **先** bootstrap供应商能力，**再** bootstrap 任务适配器，保证解析供应商 key 时注册表已就绪。
+
+## 新增一个内置供应商时要改哪里
+
+按顺序检查并补齐下面几项（均以「新增 key `acme`」为例）。
+
+### 1. 能力规格在 `provider_bootstrap.py` 中为 `acme` 增加一条 `ProviderSpec`：
+
+- `key`：稳定小写 key，与任务注册、DB 里可选的命名约定一致。
+- `aliases`：兼容历史名称、中文名、常见拼写。
+- `supported_categories`：`ModelCategoryKey` 中本供应商实际接得住的类别（text / image / video）。
+- `default_base_url`：若 UI 或创建 Provider 时需要默认 endpoint，可填；纯网关型可置空。
+
+若 key 或别名与已有注册冲突，`register_provider` 会抛错，避免静默覆盖。
+
+### 2. 任务适配器
+
+在 `app/core/tasks/bootstrap.py` 中，对每一种需要跑在 `acme` 上的任务类型调用 `register_task_adapter`，例如：
+
+- `image_generation` + `acme` → 指向 `ImageGenerationTask` 上对应的 `_build_acme_impl`（或等价工厂）。
+- `video_generation` + `acme` → 指向 `VideoGenerationTask` 上对应的工厂。
+
+工厂未注册时，任务分派会在运行时报错，与「能力表里有 key」不是一回事：**能力表只说明「产品层面支持」；任务表说明「 worker 能执行」**。
+
+### 3. 具体实现类
+
+- 在 `app/core/integrations/` 下为 `acme` 增加图片/视频 API 适配类（httpx 调用与 JSON 映射）。  
+- 在 `image_generation_tasks.py` / `video_generation_tasks.py` 中增加 `_build_acme_impl`，构造 Task 并注入对应 adapter（或默认 adapter）。  
+- 在 `app/core/tasks/bootstrap.py` 中注册 `(task_kind, acme)` → 该工厂。  
+若 `provider_resolver` 或 manage 层有按供应商分支的逻辑，按需增加分支，保持 **api 薄、service 厚**。
+
+### 4. 验证
+
+- 跑与 LLM 路由相关的测试（例如 `backend/tests/test_llm_api_responses.py` 中对 `providers/supported` 的断言可按需扩展）。
+- 跑任务注册相关测试（如 `backend/tests/test_task_registry.py`）。
+- 适配层可补充 `backend/tests/core/integrations/` 下基于 `httpx.MockTransport` 的单测，无需真实网络。
+- 若暴露了新 API 或响应字段，按仓库约定执行 `pnpm run openapi:update` 并更新前端 generated client。
+
+## 与数据库里配置的 Provider 的关系
+
+- **内置注册表**：定义「系统认识哪些供应商 key、类别、默认 URL」，不替代数据库中的 `Provider` 实例（API Key、环境特定 base_url 等仍存 DB）。
+- **用户/运维在 UI 创建的 Provider**：通常应选用 `supported` 列表中的 key或与别名解析一致的名称，以便 `resolve_provider_key_from_name` 能落到统一 key；任务执行时再按 key 查找已注册的适配器。
+
+### Base URL 优先级（按类别解析）
+
+当前 `Provider` 支持三组 URL 字段：
+
+- `base_url`：文本/通用入口（默认建议配置 OpenAI-compatible 网关）。
+- `image_base_url`：图片能力覆盖入口（可选）。
+- `video_base_url`：视频能力覆盖入口（可选）。
+
+运行时解析优先级：
+
+- image：`image_base_url` > `base_url` > `ProviderSpec.default_base_url`
+- video：`video_base_url` > `base_url` > `ProviderSpec.default_base_url`
+- text：`base_url` > `ProviderSpec.default_base_url`
+
+## 测试提示
+
+完整 `app.main` 会加载含 Celery 依赖的路由链。仅验证 LLM 路由行为时，可使用测试辅助模块 `backend/tests/support/llm_api_app.py` 构建只挂载 `/api/v1/llm` 的应用，避免轻量环境缺少可选依赖导致导入失败。