From 03ca11e257c512bc3b67793459dc86709ea9dce7 Mon Sep 17 00:00:00 2001 From: ila Date: Wed, 26 Aug 2026 10:32:20 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=20extra=5Fbody=20?= =?UTF-8?q?=E7=99=BD=E5=90=8D=E5=8D=95=E5=8F=8C=E5=A4=84=E5=AE=9A=E4=B9=89?= =?UTF-8?q?=E4=B8=8E=E4=B8=8A=E6=B8=B8=E5=B0=BA=E5=AF=B8=E5=8F=82=E6=95=B0?= =?UTF-8?q?=E9=AA=8C=E8=AF=81=E7=BB=93=E8=AE=BA=20(#64)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5 --- docs/03-business-rules-and-glossary.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index 341555d..f4cf99d 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Business-Rules-and-Glossary wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Business-Rules-and-Glossary.- -wiki_revision: 8eecc350340b2e27bad9bdf4b365fc3057517ffe -synchronized_at: 2026-08-25T08:47:49Z +wiki_revision: dd1d0ceaddf4b5ba61b46a626a7e0d5135fb965e +synchronized_at: 2026-08-26T02:31:05Z # 业务规则与术语 @@ -66,6 +66,13 @@ synchronized_at: 2026-08-25T08:47:49Z - 数据库 route runtime 是跨 worker 的熔断排除依据，`gobreaker` 只作进程内快速保护；half-open 探测必须通过数据库租约限制并发。 - Provider 凭据按版本独立保存明文 `api_key`；新版本激活后退役旧版本，可重新激活历史版本。列表和普通详情不返回完整值，单条查看响应禁止缓存。 - `auth_type` 只允许 none、bearer、x-goog-api-key；禁止任意认证 header。extra_body 不得覆盖 URL、认证、model、Prompt、输入、超时、输出数量和响应上限。 + +`extra_body` 采用键白名单，当前允许 `temperature`、`max_tokens`、`size`、`quality`。两条必须记住的事实： + +1. **白名单在两处独立定义**：`internal/core/provider` 的运行时校验与管理端的表单校验。新增键必须同时改，只改管理端会造成"能保存但生成在毫秒内失败"（错误码 `upstream_unknown`、耗时几毫秒、无上游请求），只改核心域则管理端存不进去。 +2. **放开新键前必须先用受控请求验证上游真的接受它**，不能以"其他实现这么发"为依据。参数名对不上时上游通常静默忽略，表现为"配置了却不生效"，很容易被误读成参数生效但值不对。 + +已验证的上游行为（自定义 OpenAI 兼容 Provider 的 `gpt-image-2`，2026-08-26，见 #64）：`/images/generations` 端点**忽略 `size` 与 `resolution`**，输出像素总量固定在约 157 万；`resolution` 取 `1K` 与 `2K` 产出完全相同的 1536×1024。唯一能改变输出的是 `aspect_ratio`，它只改构图比例、不改像素总量。因此该 Provider 上不存在"调整分辨率"的能力，只有"调整构图"。 - 连通性检查只能由有独立权限的管理员主动触发；先原子预留检查和冷却，再使用服务端固定最小探针走生产 SSRF/认证链。冷却内返回 retry_after；保存配置、CI 和普通调试不得触发真实请求。 - image_generate 不接受输入图；image_edit 至少一张且恰好一个 primary。position 从 0 连续且唯一，role 仅 primary/reference，note 限长；Prompt 覆盖顺序为模板默认 role_rule → 非空用户 role_rule → 按 position 的图片 role/note。 - 历史使用带 HMAC 的 `(created_at,id)` 不透明游标和 user_id 作用域，不使用 offset；响应包含 items、next_cursor、has_more，游标篡改返回 400。