Merge branch 'feat/issue-10-error-body-retention'

test: make the 429 red line actually catch its violation
Verifier mutation test: flipping _translate_429 to parse the summary left all 824 tests green. The padding was one long string value, so the cut landed inside it - and head-and-tail retention kept the trailing error object, leaving the summary parseable. Many keys put the cut between structural tokens, where the summary stops being valid JSON. Mutation now fails as it should. Also splits OCR 429 out on its own.
2026-08-16 23:34:20 -04:00 · 2026-08-16 06:50:50 -04:00 · 2026-08-16 06:22:13 -04:00 · 2026-08-16 06:17:10 -04:00 · 2026-08-16 06:14:07 -04:00 · 2026-08-16 06:07:29 -04:00
28 changed files with 1536 additions and 59 deletions
@@ -1,5 +1,55 @@
 # Changelog

+## 1.2.0(2026-08-16)
+
+网关拒绝一次调用时,**它说的话不再丢失**(issue #10)。下游一轮 1050 张医学影像的批处理里,1 张在读表格这一步收到 400、被判确定性失败而放弃;事后想知道"这张图到底哪里不合规",无从查起——响应体在 transport 翻译层之后就不存在于进程任何位置了。
+
+根因是三条留存通道同时为空: `_status_to_error` 手上握着 `body_text` 却只用于 429 的类型细分,该模块没有任何 logger 调用,异常类也没有承载响应体的字段。而库的逐次遥测写的是 `str(exc)`,即 message——所以**只给异常加字段并不能让它进遥测表**,必须两者都做。
+
+### 新增
+
+- **四分类错误新增 `body_text` 字段**(加在 `PolyGatewayError` 基类): 非 2xx 响应体的摘要。与 `ResultInvalidError.raw_text` 分工明确——前者是"对方拒绝的理由"(非 2xx),后者是"2xx 但内容不可解析时的模型输出"。scope 级错误(`GatewayUnavailableError` 一族)恒为空串: 它们没有单一响应体可言。
+- **同一份摘要同时进入异常 message**,故 SQLite/Postgres 遥测的 `error` 列里直接可查,下游不必为此单独埋点。
+
+### 行为变更
+
+- **非 2xx 的 message 末尾追加 ` | {响应体摘要}`**,覆盖两个 transport 的**全部**分支: chat 的 400 / 401·403 / 4xx 兜底 / 5xx / 429 两支(含 `insufficient_quota`),以及 OCR 的全部分支。issue 只报告了 chat 的 400,但 401 会 `force_open` 整个源、OCR 侧 message 原本只有一个状态码,是同一个缺陷的其余分支。
+- 摘要口径: 先折叠空白(错误体常是缩进 JSON,原样拼进 message 会把一行日志炸成多行),再限长 **2048 字符**(对齐 Kubernetes client-go 同场景的 `maxUnstructuredResponseTextBytes`)。超长时**保留头 1400 + 尾 600**并记下省略字数——JSON 错误体的 `code` / `request_id` 收在尾部,头部硬切正好会切掉向网关方追查时唯一有用的那部分。
+- 遥测 `error` 列因此变长: 纯 ASCII 约 2KB/条,最坏(5xx 重试 3 次)一次调用约 6KB。
+
+### 不变
+
+- **状态码 → 错误分类的映射逐条未动**(ARCHITECTURE §6.2 表),`retry_after_s` 解析、429 免重试预算、`insufficient_quota` 细分全部保持——429 的类型判定仍解析**未截断的原文**,若改用摘要,超长 body 的配额耗尽会退化成普通限速、该源不再 `force_open`。
+- 异常类型树、`str(exc)` 之外的字段、遥测 22 字段与列序、DDL 全部未变。**错误面零变更**,下游 `except` 写法不受影响。
+- 400 仍按确定性失败处理(不重试不换源)。**但请注意**: 经第三方中转部署时,中转自身抖动也会回 400,从状态码上与"你的输入有问题"分不开(下游实测: 同一份字节 sha256 一致、重发 15 次全部成功,失败那次 `prompt_tokens=0` 且耗时远低于任何成功调用)。库不改默认语义——直连供应商时重试只会白烧配额——但 `body_text` 现在给了下游自行区分的判据。
+
+### 升级提示
+
+README 的安装 pin 由 `==1.1.*` 改为 `>=1.2,<2`。**仍按 `==1.1.*` 安装的下游会静默停在 1.1.2**,拿不到本次修复且没有任何报错,请同步改自己的依赖约束。
+
+- 打包元数据补齐: `readme` 与 `[project.urls]`。1.1.2 及之前的包在 registry 页面上**没有任何说明正文**(缺 `readme` 时 twine 只警告不阻塞),也没有仓库链接。代码零变更,自本版生效。
+
+## 1.1.2(2026-08-07)
+
+Postgres 遥测撞上建表权限就整体判死的问题(issue #9)。**最小权限部署会静默丢掉全部遥测**: 应用账号有表级 `INSERT`、表也已存在,但没有 schema 的 `CREATE` 权限时,初始化的 `CREATE TABLE IF NOT EXISTS` 被拒 → recorder 永久 no-op,业务调用一切正常,只留一行 warning。下游 CHSAnalyzer3 首次端到端跑的 150+ 次调用耗时/token/成本因此全部丢失,且事后无法补回。
+
+根因是 **PostgreSQL 对 schema 的 CREATE 权限检查早于 `IF NOT EXISTS` 的存在性判断**(PG 16.14 实测: 同一连接 `INSERT` 通过、`to_regclass` 看得见表,该 DDL 照样被拒)——与 issue #3 修过的 `ALTER TABLE` 是同一类问题,当时只修了补列那一半。
+
+### 行为变更
+
+- **PG 侧建表前先 `to_regclass` 探测,表已存在就一条 DDL 都不发**。探测不需要任何权限,且与 `INSERT` 走同一套 search_path 解析(比裸 DDL 更准: 裸 `CREATE TABLE` 落在首个**可建**的 schema,可能与写入命中的不是同一张表)。表不存在时才建,新建表列已齐全,顺带跳过补列。
+- **"结构性失能"的判据收窄为「确定写不进去」**,不再是「初始化时出过异常」。仅两种情形仍永久降级为 no-op: 建池失败(重试要在业务路径上内联吞掉连接超时)、表确定不存在且建不出来(后续 INSERT 必然全败)。探测失败、取连接失败改为**只跳过本条并 warning,下次调用重新准备**——初始化瞬间的一次抖动不再让整个进程失遥测。
+- 日志措辞随之细分: `建池失败` / `建表探测失败(跳过本条,下次重试)` / `建表失败(表不存在,记录无处可落)`,原先一律是 `初始化失败`。
+
+### 不变
+
+- SQLite 侧**一行未改**。实测其对已存在的表在解析期就把 `CREATE TABLE IF NOT EXISTS` 短路掉(另一连接持 `BEGIN EXCLUSIVE`、文件 `chmod 444` 时该语句均通过,而同条件的 `INSERT` 分别报 database is locked / readonly database),没有同款风险;加探测零收益,故有意不对称,只在 docstring 钉死实测结论。
+- 遥测端口签名、22 字段、列序、`ON CONFLICT DO NOTHING` 幂等、单条写失败逐行丢弃的降级方向全部未动。**错误面零变更**。
+
+### 升级提示
+
+若你的部署此前为了绕开本问题给应用账号授了 `CREATE ON SCHEMA`,现在可以收回——表存在时库不再需要该权限。
+
 ## 1.1.1(2026-08-06)

 stall 判定改为非生产性等待口径(issue #8)。`timeout_s ≥ stall_window_s` 时,**一次耗满超时的请求就会让整个 scope 被判死,配置的重试次数一次都用不上**——而且没有任何报错或 warning,配置方以为自己配了 3 次重试。`stall_window_s` 默认 300 恰是个很容易被 `TIMEOUT_S` 追平的值,"只配 timeout、不配 stall"这种最常见的写法正好踩中。
@@ -78,6 +78,31 @@ make ci        # 只读验证(check + test)
 ### 4.4 Git 工作流
 - 一切开发在 feature 分支,严禁直改 main;频繁语义化提交;提交**必须**调用 `commit` skill;大改动前先提交回滚点。

+### 4.4.1 发布流程(每步都是历史欠账换来的,不得跳步)
+
+> [!CRITICAL]
+> **发布 = 合并 + push + tag + 构建 + 上传 registry。只 bump 版本号不叫发布。**
+> 教训: 1.0.6 与 1.1.0 都完成了版本号 bump 与 CHANGELOG,却从未上传,registry 长期停在 1.0.5——下游 `pip install` 拿不到任何修复,且无人发现。
+
+按顺序执行,**构建之前**必须先改完所有文档:
+
+| # | 动作 | 要点 |
+|---|---|---|
+| 1 | **更新 README** | 打包会把当时的 README 固化进 sdist,**发布后再改就来不及了**(包里那份永远是旧的)。逐项核对: 安装命令的版本约束(`==1.1.*` 这类**极易漏改**,漏了下游就被锁在旧版)、能力表是否覆盖新行为、数字型断言是否仍成立(如遥测字段数,须用 `inspect.signature` 实测而非凭记忆) |
+| 2 | CHANGELOG 定版 | "未发布" → `## X.Y.Z(日期)` |
+| 3 | 版本号 | `pyproject.toml` + `src/polygateway/__init__.py` 两处必须一致 |
+| 4 | 合并 main + push | `--no-ff`;合并后在 main 上重跑 `make lint` 与全套件 |
+| 5 | **打 tag 并 push** | `git tag -a vX.Y.Z -m "..."` + `git push origin vX.Y.Z`。历史上多个版本漏打 |
+| 6 | 构建 | `rm -rf dist && python -m build && python -m twine check dist/*` |
+| 7 | **上传 registry** | 凭据在 `~/.config/tea/config.yml`(tea CLI 的 Gitea token,**不在** `~/.pypirc`);token 走 `TWINE_PASSWORD` 环境变量,不进命令行<br>`TWINE_USERNAME=iomgaa TWINE_PASSWORD=$TOKEN python -m twine upload --repository-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi dist/*` |
+| 8 | **验证已发布** | `pip download --no-deps --index-url .../pypi/simple/ "polygateway==X.Y.Z"`,并解包确认新代码在内。**不验证不算发布完成** |
+| 9 | **建 Release + 核对包页面** | `POST /api/v1/repos/iomgaa/PolyGateway/releases`(body 取 CHANGELOG 本版段;历史上只打 tag 不建 release,Releases 页长期为空);随后打开包页面确认有正文与仓库链接,**Link to a repository 只能在网页手动做**(该实例的 link API 返 404) |
+
+> [!CRITICAL]
+> **发布完成的判据是外部可见结果,不是本地步骤跑通**: 收尾必须以下游视角逐一打开产物页面(registry 包页面正文与仓库链接、仓库 Releases 页、`pip install` 后包内文件),看到什么算什么,缺的当场补进本清单——1.1.2 三步全绿却出现包页面空白(`pyproject` 缺 `readme`)、Releases 页 0 条、包未挂仓库。
+
+Gitea 包 registry 是 **owner 级**(`/iomgaa/-/packages/`)不是仓库级;PyPI 元数据不含仓库字段,故不会自动挂到 `PolyGateway/packages`,需在包页面手动 Link to a repository。
+
 ### 4.5 配置管理
 - 工程配置走 `pydantic-settings` + `.env`(模板 `.env.example`,敏感项不提交);严禁硬编码默认值;缺失关键配置直接报错。
 - 多源命名约定 `{SCOPE}__{PROVIDER}__{N}__{FIELD}`;韧性参数键名沿用三项目习惯(`LLM_TIMEOUT` 等),降低迁移成本。
@@ -15,9 +15,10 @@
 | 错误分类重试 | 一切失败落入四分类(见下),由分类决定重试/换源/熔断;429 属 pushback 不消耗重试预算;退避含 jitter 且尊重 Retry-After |
 | 熔断 | 双通道(连续失败 + 失败率窗口,健康证据抑制误熔);半开单探针带租约(持有者死亡自动回收);epoch fencing 拒绝迟到写回;开路时长指数递增 |
 | 自适应并发 | AIMD:429 削减、成功缓升,防止打爆上游 |
+| 背压与判死 | 配额满可选等待或快速失败;等待期按双条件判死(本地非生产性等待与全局无进展**同时**超窗)。stall 窗口只计**非生产性**等待(429 退避/配额轮询/熔断冷却),与 `TIMEOUT_S` 无耦合 |
 | 响应缓存 | Redis/内存;key 含 model + messages 摘要 + namespace/租户 + salt,多模态 content 先摘要再 hash(防毒化);可 per-call 绕过(科研重采样) |
 | 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token 刷活性不计结果;截断流(缺 `[DONE]`)判瞬时不入缓存 |
-| 遥测与成本 | 每次调用(含缓存命中与失败)必录 18 字段;SQLite / Postgres 后端;按价格表折算成本;多模态内容摘要落库不存原图 |
+| 遥测与成本 | 每次调用(含缓存命中与失败)必录 22 字段;SQLite / Postgres 后端(表已存在时**不需要** schema 建表权限,最小权限账号可直接用);按价格表折算成本落库(注意 `LLMResponse.cost` 本身恒为 `None`,成本只进遥测);多模态内容摘要落库不存原图 |
 | 结构化输出 | json_repair 修复 / 原生 schema 双策略 + 校验失败有界带反馈重问 |
 | OCR | MonkeyOCR 双端点(文本转录 + 版面解析),bbox 数值防御下沉,逐源健康预检 `check_health()` |
 | Embedding | 分批、维度校验、与 chat 同一治理栈 |
@@ -30,7 +31,7 @@

 ```bash
 pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
-    "polygateway[redis,postgres,structured]==1.0.*"
+    "polygateway[redis,postgres,structured]>=1.2,<2"
 ```

 核心仅依赖 `httpx` + `pydantic`;按需选 extras:
@@ -124,6 +125,8 @@ except RequestRejectedError:

 预算耗尽/全源熔断时抛 `GatewayUnavailableError` 族(`CircuitOpenError` / `AllSourcesExhausted`),携带 `scope` / `reason` / `retry_after_s` / `per_source_reasons`,供任务队列做延期重投。

+**网关拒绝的理由不会丢失**(1.2.0 起):非 2xx 的响应体经折叠与截断后同时进入异常 message 与 `exc.body_text`,故遥测表的 `error` 列里就能看到网关的原话——不必再为查一次 400 单独埋点。截断保头保尾(总长 2048 字符),JSON 错误体尾部的 `code` / `request_id` 不会被切掉。**经中转部署时请注意**:第三方中转服务自身抖动也会回 400,从状态码上与"你的输入有问题"无法区分;库仍按确定性失败处理(直连供应商时重试只会白烧配额),批处理下游宜据 `body_text` 自备兜底分类。
+
 ### 哪些异常会到达调用方

 上表的"库内行为"一列描述的是**治理动作**,不是调用方要处理的东西。四类里有两类**根本到不了调用方**——它们被重试循环接住,预算耗尽时统一包成 `AllSourcesExhausted`。这个区分只看类型树和 docstring 是读不出来的,曾让下游据此写错整段设计文档,故在此列明:
@@ -4,8 +4,11 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "polygateway"
-version = "1.1.1"
+version = "1.2.0"
 description = "PolyGateway：实验室统一的大语言模型（LLM/VLM/OCR）调度与中转库——多源、限流、重试、熔断、缓存、遥测"
+# registry 包页面的正文只认这一项:缺了页面就是一片空白(1.1.2 的教训,twine 会警告
+# long_description missing 但不阻塞上传)。README 在打包时被固化进产物,发布后再改无效。
+readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
    "httpx>=0.27",
@@ -31,6 +34,11 @@ dev = [
    "import-linter>=2.0",
 ]

+[project.urls]
+Homepage = "https://gitea.iomgaa.online/iomgaa/PolyGateway"
+Changelog = "https://gitea.iomgaa.online/iomgaa/PolyGateway/src/branch/main/CHANGELOG.md"
+Issues = "https://gitea.iomgaa.online/iomgaa/PolyGateway/issues"
+
 [tool.setuptools.packages.find]
 where = ["src"]

@@ -396,6 +396,10 @@ flowchart TB
 | **空补全**: 200 且流程完整([DONE]/usage 正常)但 content 为空(2026-07-20 M1 验证发现,人类裁决) | `TransientError`(服务抖动,重试/换源;绝不缓存空响应) |
 | 解析层失败(结构化输出/OCR ZIP) | `ResultInvalidError` |

+**响应体留存(2026-08-16,Gitea issue #10;设计 `designs/2026-08-16-issue10-error-body-retention-design.md`)**: 上表每一条 HTTP 翻译**都必须携带响应体摘要**——摘要同时进入异常 message 与 `PolyGatewayError.body_text`(1.2.0 新增基类字段)。两者都要,因为逐次遥测写的是 `str(exc)`,只加字段进不了遥测表,而"事后可查"正是这条要求的目的。摘要口径由 `transports/_http_errors.summarize_body` 单点实现(折叠空白 → 限长 2048 字符 → 超长保留头 1400 + 尾 600 并记省略字数),两个 transport 共用,**不得各写一份**——issue #10 的成因正是"只有 429 那一支用了响应体"。`body_text` 是旁路数据,不参与任何治理判定;`_translate_429` 的类型细分仍解析未截断原文(摘要会破坏 JSON,改用它会让超长 body 的 `insufficient_quota` 退化成普通限速)。
+
+**400 在中转拓扑下的语义提醒**(同上): 第三方 API 中转服务自身抖动时也会回 400,从状态码上与供应商的"输入非法"无法区分(下游实测: 同一份字节重发 15 次全成功,失败那次 `prompt_tokens=0`、耗时远低于任何成功调用,即请求在推理开始前被挡)。本表**不改** 400 → `RequestRejectedError` 的映射——直连供应商时重试只会白烧配额,且改默认语义等于让所有直连用户为一种部署形态买单;库改为把判据(`body_text`)交给下游自行区分。
+
 ### 6.3 "坏结果 ≠ 坏服务"(ResultInvalidError 语义,继承 CHSAnalyzer)

 由输入内容决定的**确定性失败**(这张图就是解析不出表格、这段输出就是修不成 JSON):服务是健康的,换源重试只会白烧配额。因此熔断器记成功、不换源、异常上抛消耗业务侧的失败预算。出处:`CHSAnalyzer governance.py:237-239`。
@@ -475,7 +479,7 @@ flowchart TB

 **`sampling` 列(2026-07-31,issue #4,端口 20 → 21)**: 列语义 = 「调用方采样意图 ⊎ 生效源 `extra_body`」的 canonical JSON,空则 NULL。**不含**结构化注入的 `response_format`——列名是采样参数,schema 不是,且数 KB schema 逐行落库会让审计表无谓膨胀。三个 emit 入口口径必须各自定死,否则同一列在不同行含义不同: `emit_attempt`(RetryMW 调用,**唯一**有生效源者)并上 `source.extra_body`;`emit_cache_hit` / `emit_terminal_failure`(TelemetryMW 最外层调用)无 source 可言,只记调用级——与 `model`/`source_name` 在终态行置空是同一先例,且缓存命中行无损(`sampling` 已进缓存 key,能命中即意味调用级参数与历史那次逐字相同)。三者统一读 `request.sampling` 而非 `request.overlay`(后者在 RetryMW 处已被结构化注入污染、在 TelemetryMW 处未被污染,直接用必然三行分叉)。OCR/embedding 路径因决策 G 剥离 `extra_body`,该列恒 NULL。

-(`cached_prompt_tokens`/`model_reported` 为 2026-07-31 issue #3 新增,端口由 18 字段扩为 20;两个后端在初始化期对已存在的旧表幂等补列——`CREATE TABLE IF NOT EXISTS` 不会给旧表加列,不补则每行写入都被逐行 warning 丢弃。补列一律**先探测缺列再 ALTER**(`ADD COLUMN IF NOT EXISTS` 即使列已存在也先取 ACCESS EXCLUSIVE 锁,而遥测内联 await,锁共享审计表会拖垮业务调用),且**失败只逐行降级、绝不置结构性失能标志**。新列在 DDL 里必须排在 `created_at` **之后**,与 `ALTER TABLE ADD COLUMN` 的追加位置一致,否则新建库与升级库的物理列序分叉)。链路: `session_id`/`parent_call_id` 由调用方传入贯穿(agent step → LLM call)。`messages` 落库前对多模态 part 先摘要(与缓存 key 共用同一摘要函数,§7.5)——Video-Tree 现状 base64 整段进 SQLite 导致 db 膨胀(`llm.py:330`),库内修复(2026-07-20,VT 迁移缺口 R12)。
+(`cached_prompt_tokens`/`model_reported` 为 2026-07-31 issue #3 新增,端口由 18 字段扩为 20;两个后端在初始化期对已存在的旧表幂等补列——`CREATE TABLE IF NOT EXISTS` 不会给旧表加列,不补则每行写入都被逐行 warning 丢弃。补列一律**先探测缺列再 ALTER**(`ADD COLUMN IF NOT EXISTS` 即使列已存在也先取 ACCESS EXCLUSIVE 锁,而遥测内联 await,锁共享审计表会拖垮业务调用),且**失败只逐行降级、绝不置结构性失能标志**。**建表同理(2026-08-07,issue #9)**: PG 对 schema 的 CREATE 权限检查早于 `IF NOT EXISTS` 的存在性判断(16.14 实测,只授表级 `SELECT, INSERT` 的角色写得进去却建不了表),故 PG 侧必须**先 `to_regclass` 探测、表在就不发 DDL**;SQLite 侧实测在解析期即短路(持排他锁/只读文件下该语句均通过),无同款风险,**有意不加探测**。由此把"结构性失能"的判据从「初始化时出过异常」收窄为「确定写不进去」——仅建池失败与"表确定不存在且建不出来"判死,探测/取连接失败只跳过本次并留待下次重试。新列在 DDL 里必须排在 `created_at` **之后**,与 `ALTER TABLE ADD COLUMN` 的追加位置一致,否则新建库与升级库的物理列序分叉)。链路: `session_id`/`parent_call_id` 由调用方传入贯穿(agent step → LLM call)。`messages` 落库前对多模态 part 先摘要(与缓存 key 共用同一摘要函数,§7.5)——Video-Tree 现状 base64 整段进 SQLite 导致 db 膨胀(`llm.py:330`),库内修复(2026-07-20,VT 迁移缺口 R12)。

 - 后端: `SQLiteRecorder`(默认;WAL + busy_timeout、`INSERT OR IGNORE` 幂等、`asyncio.to_thread` 桥接、初始化/写入失败全降级不冒泡)与 `PostgresRecorder`。
 - **单一 helper 铁律**: 遥测调用点收敛为一个内部函数/上下文管理器;Video-Tree 与 GovDoc 各有 4-5 处逐字复制的 `record_llm_call(15 个参数)` 是本条的直接教训。
@@ -0,0 +1,238 @@
+# HTTP 错误响应体留存设计(Issue #10)
+
+- **日期**: 2026-08-16
+- **来源**: Gitea Issue #10(下游 1050 张医学影像批处理,1 张收到 400 被判确定性失败;事后无从查证原因。基于 1.1.2 源码核查)
+- **状态**: **已批准(2026-08-16)**,待 `writing-plans`
+- **触发档位**: 强制(`errors.py` 属最内层内核,新增公共字段即变更库对下游的承诺)
+- **方案范围**: 人类明确要求单一方案(2026-08-16),故本文不列平行备选,仅在 §6 记录被否决路线及否决理由(体例沿用 Issue #7/#8 设计)
+
+## 1. 目标与非目标
+
+| | 内容 |
+|---|---|
+| **G1** | 网关拒绝一次调用时,**它说了什么必须可事后查证**——库自己的遥测表里就能查到,不依赖下游额外埋点 |
+| **G2** | 留存口径覆盖 transport 层**全部**非 2xx 分支与**全部** transport(chat / embedding / stream / OCR),杜绝"只修 400 → 下次 401 复发" |
+| **G3** | 摘要文本单点规范化(折叠空白 + 截断 + 截断标记),message 与结构化字段**取同一份串**,两处永不打架 |
+| **G4** | 不改变任何状态码 → 错误分类的映射(ARCHITECTURE §6.2 表原封不动),下游 `except` 写法零影响 |
+| **非目标** | 不改 400 的治理语义(不重试不换源,见 §5.2);不新增遥测列(见 §6.1);不新增配置项;不做错误分类可插拔(见 §6.4);不顺手修 `_status_to_error` 的 `operation` 硬编码缺陷(见 §5.4) |
+
+### 1.1 Issue 前提的两处修正(按 1.1.2 源码核实)
+
+| Issue 原文 | 实际情况 |
+|---|---|
+| 建议方向一「让异常带上截断后的响应体……就能让下游把它记进日志和遥测」 | **只做这一半解决不了 Issue 自己陈述的痛点**。库的逐次遥测写的是 `error=str(exc)`(`middleware/retry.py:558` → `middleware/telemetry.py:89` → `telemetry/sqlite.py:43` 的 `error TEXT` 列),即**异常 message**。新增字段不会进库的遥测表;下游说的"写进遥测表"是他们自己的埋点。故本设计**两件都做,且以 message 为主**(§3.3) |
+| 缺陷范围 = 400 分支 + 4xx 兜底 | 实为 **6 处同构**:`openai_compat._status_to_error` 的 400 / 4xx 兜底 / 401·403 / 5xx 四支,`_translate_429` 的两支(读了 body 判 `insufficient_quota`,但 message 仍不带),以及 `monkey_ocr._classify_status:74-88` 的**全部**分支(message 只有 `HTTP {status}`)。Issue 场景是"读表格",极可能正落在 OCR 路径 |
+
+## 2. 根因:诊断信息在翻译层被丢弃,而遥测只看 message
+
+`_status_to_error`(`transports/openai_compat.py:131-143`)手上握着 `body_text`,却只把它用于 429 的类型细分,翻出的异常与 message 都不携带它。响应体在这一层之后**不再存在于进程任何位置**:该模块无 logger(grep `logger|loguru` 零命中),异常类无字段,遥测只写 message。
+
+三条留存通道同时为空,是"永久查不到"的完整解释:
+
+| 通道 | 现状 | 本设计后 |
+|---|---|---|
+| 日志 | 模块无 logger | 仍无(§6.2:不加日志) |
+| 异常字段 | 无承载处 | `body_text`(§3.1) |
+| 库遥测 `error` 列 | 只有 `"{源名} 请求被拒: 400"` | message 携带摘要(§3.3) |
+
+## 3. 选定方案
+
+### 3.1 内核:`PolyGatewayError` 基类新增 `body_text`
+
+```python
+class PolyGatewayError(Exception):
+    def __init__(self, message, *, source_name=None, status_code=None,
+                 operation=None, body_text: str = "") -> None:
+```
+
+**加在基类而非 `RequestRejectedError`**:这些错误全部由同一个 HTTP 响应翻译而来,"对方说了什么"与"它属于哪一类"正交。只给一个子类加,下次给 `SourceDeadError` 加又是一次公共 API 变更 + 一次人类门。
+
+与既有 `ResultInvalidError.raw_text`(`errors.py:77`)的界限必须在 docstring 钉死,否则两个"原文字段"必然被混用:
+
+| 字段 | 语义 | 来源 |
+|---|---|---|
+| `body_text` | **非 2xx** 的 HTTP 错误响应体摘要——对方**拒绝**你的理由 | transport 翻译层 |
+| `raw_text` | **2xx** 但内容不可解析时的模型输出原文 | 结构化解析层 |
+
+`GatewayUnavailableError` 一族继承到一个恒空的 `body_text` 不是噪音:scope 级失败本就"没有单一响应体可言",空串是对这件事的如实表达。
+
+### 3.2 共享单元:`transports/_http_errors.py`(新建,~40 行)
+
+两个 transport 各有自己的状态码分类逻辑(OCR 无 429 细分,有意保留,见 `monkey_ocr.py:53-54`),但**摘要口径必须同一份**,否则就是下一个"只修一半"。两函数:
+
+| 函数 | 职责 | 关键防御 |
+|---|---|---|
+| `summarize_body(text) -> str` | 折叠空白 → 按 §3.4 的机械规则截断 | 空/空白入参返回 `""` |
+| `response_body(response) -> str` | 从 `httpx.Response` 取已缓冲文本 | `ResponseNotRead` → 返回 `""`,**绝不触发网络读** |
+
+- **折叠空白不是洁癖**:错误体常是缩进 JSON,直接拼进 message 会让一行日志炸成多行、遥测列不可读。
+- **截断必须留标记**:不标记,读的人分不清"网关只说了这么多"和"库切的"。
+- **`response_body` 的防御是硬要求**:`monkey_ocr._classify_status` 只拿得到 `httpx.HTTPStatusError`,若某天 OCR 走 stream 请求,`.text` 会抛 `ResponseNotRead`,把一次可分类的 4xx 变成泄漏的 httpx 异常——**违反"一切失败必须落入四分类"铁律**。诊断信息缺失绝不能升级为崩溃(降级方向,§4.2)。
+
+放在 `transports/` 私有模块而非 `errors.py`:职责是"HTTP 响应 → 领域错误"的工具,放内核会稀释 `errors.py` 的单一职责(P3)。两个 transport 同 import 一个私有模块,不构成 transport 之间的互相依赖,import-linter 的 layers 契约(同层 `|` 独立性)不受影响。
+
+### 3.3 翻译层:表驱动收口,message 与字段共用一份摘要
+
+`_status_to_error` 现在是五个分支各拼各的 message,新增摘要意味着五处重复。改为**分类表 + 单点拼装**,代码反而变短:
+
+```
+summary = summarize_body(body_text)          # 全函数只算一次
+ctx     = {..., "body_text": summary}        # 字段
+429 → _translate_429(source, body_text, headers, ctx)   # 需原文判 type,单列
+其余 → cls, label = _STATUS_MAP 查表 → cls(_compose(source, label, status, summary), **ctx)
+```
+
+message 形态:`"{源名} {标签}: {状态码} | {摘要}"`;**摘要为空时不拼后缀**,避免出现悬空的 ` | `。分隔符取 ` | ` 而非既有的 `: `,让"库的话"与"网关的话"一眼可分。
+
+**429 也拼,不设例外**:例外就是下一个复发点。`insufficient_quota` 那支尤其需要(配额细节全在 body 里);普通限速 body 通常很短。代价是高频限速场景遥测 `error` 列变长,由 `_ERROR_BODY_CAP` 兜住。
+
+`monkey_ocr._classify_status` 同款处理:`summary = summarize_body(response_body(exc.response))`,message 追加同一后缀,`ctx` 带上字段。
+
+### 3.4 常量取值
+
+**机械规则(实现与测试逐字照此)**:
+
+```
+_ERROR_BODY_CAP = 2048    # 字符(非字节),含省略标记在内的最终总长上限
+_HEAD_CHARS     = 1400
+_TAIL_CHARS     = 600
+
+折叠空白后 len ≤ 2048  →  原样返回
+否则                   →  s[:1400] + f"…(略 {len(s) - 2000} 字)…" + s[-600:]
+```
+
+> 规则必须写成算术而非叙述:"截断至 cap 并补标记"能同时被读成总长 2048 与 2049,两者会让测试断言与遥测长度承诺对不上(Codex 审查 2026-08-16 提出)。
+
+**头尾保留而非头部硬切**(2026-08-16 调研决策)。截断的对象是**结构化 JSON 错误体**,信息分布头重尾也重:人话(`message`)在前,机器可判的 `type` / `code` / `param` / `request_id` 在后。Issue 给出的真实样本即 `"code":"invalid_parameter_error"` 收尾——头部硬切正好切掉向网关方追查时唯一有用的那部分。省略标记记下**被省略的字符数**,读的人才知道自己丢了多少,不会误以为网关只说了这么多。
+
+按**字符**而非字节切:多字节字符不会被切成半个(Sentry 曾为按字节切开 issue #1691),且 `error TEXT` 列无定长约束,无需字节口径。
+
+### 3.4.1 取值依据:同场景开源实践
+
+| 项目 | 场景 | 上限 | 保留策略 |
+|---|---|---|---|
+| **Kubernetes client-go** `rest/request.go` | **读 HTTP 错误体生成错误信息**(与本设计同构) | `maxUnstructuredResponseTextBytes = 2048` | 头部硬切 |
+| OpenAI Python SDK `_exceptions.py` | 异常对象持有 body | **不截断**(内存对象,不落库) | — |
+| Sentry Python `strip_string` | 事件写入前 trim | `max_value_length`,2.34.0 前默认 1024 | 头部 + `...`,另用 metadata 记原长 |
+| Elastic APM | 长字段 | keyword 1024 / long field 10000 | 截断带省略号 |
+| Python 标准库 `reprlib` | 给人读的长字符串 | `maxstring` | **头 + 尾,中间省略** |
+
+**2048 对齐 k8s client-go**——它是唯一与本设计同场景(读 HTTP 错误体做诊断)的成熟先例。初稿的 500 仅以 issue 的单个样本(约 160 字符)为据,是拿一个样本定上限,已废弃。头部硬切在 k8s/Sentry 成立是因为它们截的是任意文本;本设计截的是结构化 JSON,故取 `reprlib` 的头尾策略。
+
+遥测代价:纯 ASCII 约 2KB/条,纯中文最多约 6KB/条;5xx 重试 3 次即一次调用最多约 18KB。批处理场景(1050 次调用、5% 失败)约 300KB,`TEXT` 列可忽略。
+
+message 与 `body_text` **共用同一变量**,不设两个长度:两份不同长度会让"遥测里看到的"与"下游 catch 到的"对不上,排查时反而多一层困惑。
+
+### 3.5 改动清单
+
+| 文件 | 改动 |
+|---|---|
+| `errors.py` | 基类新增 `body_text` 字段 + 与 `raw_text` 的界限 docstring |
+| `transports/_http_errors.py` | **新建**:`summarize_body` / `response_body` / `_ERROR_BODY_CAP` |
+| `transports/openai_compat.py` | `_status_to_error` 表驱动重写;`_translate_429` 收 `ctx` |
+| `transports/monkey_ocr.py` | `_classify_status` 带摘要 |
+| `errors.py` docstring + `ARCHITECTURE.md` §6.2 | 中转拓扑下 400 的提醒(§5.2) |
+| `README.md:34` | 安装 pin `==1.1.*` → `>=1.2,<2`(§5.3,发布前置,漏改则下游拿不到本修复) |
+
+三个调用点(`openai_compat.py:402` embed、`:417` stream、`:509` 非流式)**签名不变**,无需改动。
+
+## 4. 非功能维度
+
+### 4.1 并发与取消
+
+新增全部是纯函数与数据字段,无状态、无锁、无 IO、不引入 `await`。`response_body` 只读已缓冲字节,`ResponseNotRead` 时直接返回空串而**不发起网络读**——否则会在错误路径上凭空插入一次可能挂住的 IO。`CancelledError` 路径逐字不变。
+
+### 4.2 降级方向
+
+响应体不可得(未读缓冲 / 解码失败 / 空体)→ `body_text=""`,**静默降级,绝不报错**。诊断信息属可观测性,按库铁律与缓存/遥测同档:缺了降级,不得把一次本可正确分类的失败变成不可分类的崩溃。流式路径的 `(await resp.aread()).decode("utf-8", errors="replace")`(`:416`)已是这个口径,保持。
+
+### 4.3 幂等与重复
+
+纯函数,同输入同输出。`summarize_body` 对自身输出再调用一次是幂等的:输出总长恒为 `2000 + len(标记) ≤ 2048`(标记形如 `…(略 N 字)…`,8 + N 的位数,现实中远不足 48),且不含需折叠的空白,故第二次调用走"原样返回"分支,不会出现标记被反复嵌套。
+
+### 4.4 持久化与原子性
+
+不新增表、不改 DDL、不动遥测端口的 22 字段与列序。摘要经既有 `error TEXT` 列落盘,原子性由既有单行写入保证。
+
+### 4.5 安全与体积
+
+- **响应体可能回显请求内容**(部分网关的 `error.param` 会带违规字段值)。截断 + 空白折叠是主要止血手段;字段 docstring 须写明"可能包含请求回显,已截断"。库不做内容脱敏——库不知道下游哪些字段敏感,猜测式脱敏只会同时丢掉诊断价值与安全性。
+- **本设计不放大既有的读取风险**:`_complete_stream:416` 的 `aread()` 对错误响应体无大小上限(超大错误体可打爆内存),该风险今天已经存在(读完即丢),留存后只是更显眼。**不夹带修复**,见 §5.4。
+
+## 5. 错误处理、语义与边界
+
+### 5.1 错误分类
+
+不改任何映射。`body_text` 是**旁路数据**,不参与任何治理判定——不影响重试、换源、熔断计数、AIMD、限流结算。这是本设计能与 ARCHITECTURE §6.1/§6.2 零冲突的根本原因。
+
+### 5.2 400 语义:不改行为,补文档
+
+Issue 报告了一个有说服力的观察:同字节 15 次重发全部成功、`prompt_tokens=0`、耗时 2996ms 远低于同批 631 次成功调用的最快值 7366ms——说明那次 400 来自中转服务自身抖动,而非"你的输入有问题"。
+
+**仍不改分类**:400 重试对直连供应商是纯浪费(确定性坏输入,重试只烧配额并拖延失败);"中转也回 400"是**部署拓扑**引入的信息损失,库从状态码无从分辨。默认改为可重试 = 让所有直连用户为一种部署形态买单,且推翻已冻结的公共契约。
+
+**但本设计本身就是对这个观察最好的答复**:body 留存后,下游能自己区分——中转抖动的 400 体与供应商 `invalid_request_error` 体形态不同。库不替下游做判断,而是把判断所需的信息交出去。配套文档动作:`RequestRejectedError` docstring 与 ARCHITECTURE §6.2 各加一句"经中转部署时 400 可能源于中转自身抖动,批处理场景下游宜自备兜底分类"。
+
+### 5.3 兼容性
+
+`LLMResponse` 一族的"字段只增不删不改名"约束(ARCHITECTURE §5.1)同样适用于异常。本次是**纯新增关键字参数且带默认值**:既有构造点、既有 `except` 写法、既有 `str(exc)` 消费方全部不受影响。message 文本变化不构成破坏——现有测试对这些 message 无格式依赖(仅 `test_openai_compat.py:558` match 源名)。
+
+版本 **1.2.0**(公共类型新增字段属 minor;2026-08-16 人类定夺)。
+
+**发布时必须同步改 README 的安装 pin**:`README.md:34` 现为 `"polygateway[redis,postgres,structured]==1.1.*"`,发 1.2.0 后照此命令安装的下游会**静默停在 1.1.2**——无报错、无警告,与 CLAUDE.md §4.4.1 点名的"极易漏改"完全同款(registry 长期停在 1.0.5 即此类事故)。本次改为 **`>=1.2,<2`**,把"每发一个 minor 就要通知三个下游改 pin"这一反复出现的麻烦一次性消除。此项列入实现计划的发布前置步骤,不是发布日的临时动作。
+
+### 5.4 有意不夹带的两项(建议单开 issue)
+
+| 项 | 说明 |
+|---|---|
+| `_status_to_error` 的 `operation` 硬编码 `"chat"`(`:134`),而 `embed()` 也调它(`:402`) | embedding 的 HTTP 错误在遥测里被标成 `operation="chat"`,是既有数据正确性缺陷,与本 issue 无关 |
+| `_complete_stream:416` 的 `aread()` 无大小上限 | 恶意/故障网关的超大错误体可打爆内存,属独立的健壮性问题 |
+
+两项都在本次重构触及的函数附近,但修它们既不服务 G1-G4,也各自需要独立的行为讨论——按反 gold-plating 铁律留给独立 issue。
+
+## 6. 被否决的路线
+
+### 6.1 给遥测端口加一列(22 → 23 字段)
+
+最"正统"的结构化留存,但成本极不相称:端口 Protocol 签名变更 + SQLite/Postgres 双后端 DDL 迁移 + 下游已有表的 ALTER + 列序契约测试全线改动——为一个诊断串付出一次跨三项目的迁移。而复用既有 `error TEXT` 列可达成同样的可查证性。
+
+### 6.2 只在 `_status_to_error` 打一条 WARNING 日志(Issue 方向二)
+
+不采纳为**主**手段:日志与遥测是两套留存,日志轮转后仍然查不到,而 Issue 的痛点恰是"事后"。且库铁律要求库不擅自向下游日志流写入高频内容(4xx/5xx 在批处理下可能极高频)。message 携带摘要已让 loguru 侧的下游在捕获点自然拿到同一份信息,再加一条独立日志属重复留存。
+
+### 6.3 截断放在异常构造器内
+
+构造器自动规范化更"防遗漏",但会让下游自建异常时传入的文本被悄悄改写,违反 P4;且 message 里的摘要仍需在翻译层单独算一次,反而出现两条规范化路径。选定方案在翻译层算一次、两处共用,更简且更显式。
+
+### 6.4 错误分类映射可插拔(provider profile 注入 classifier)
+
+Issue 的中转 400 场景确实指向这个方向,但当前只有一个使用方且他们已用自己的兜底分类解决。`ProviderProfile`(`providers.py:17-45`)目前也没有这个扩展点,加它是新子系统级的设计。YAGNI:等第二个使用方提出。
+
+## 7. 测试策略(先失败后通过)
+
+**验收主张**:一次 400 调用后,注入的 recorder 收到的 `error` 串含网关响应体摘要。这条端到端断言直接对应 Issue 的痛点,是本设计成立与否的唯一硬判据;其余为覆盖性用例。
+
+| # | 用例 | 覆盖 |
+|---|---|---|
+| 1 | **端到端遥测**:mock transport 返回 400 + 真实样本体 → 断言 recorder 收到的 `error` 含摘要 | G1 |
+| 2 | 参数化状态码(400 / 401 / 404 兜底 / 429 普通 / 429 `insufficient_quota` / 500)→ 断言 message 含摘要且 `exc.body_text` 非空,**分类与既有断言逐一不变** | G2, G4 |
+| 3 | 超长体 → 前 1400 字符与原文头部逐字相同、**末 600 字符与原文尾部逐字相同**、中段为 `…(略 N 字)…` 且 N 等于实际省略数;`body_text` 与 message 中的摘要逐字相同 | G3 |
+| 3b | 长度恰为 2048 / 2049 的体 → 前者原样无标记,后者走头尾保留(边界) | §3.4 |
+| 3c | **尾部关键字段可见**:以 issue 的真实样本尾部 `"code":"invalid_parameter_error"}}` 构造超长体 → 断言该串出现在摘要中 | §3.4 头尾决策的验收 |
+| 3d | 摘要对自身幂等(再摘要一次不嵌套标记) | §4.3 |
+| 4 | 多行缩进 JSON → 折叠为单行 | G3 |
+| 5 | 空体 / 纯空白体 → 不拼悬空分隔符,`body_text == ""` | §3.3 |
+| 6 | 非 JSON 体、非 UTF-8 字节 → 不抛异常,分类不变 | §4.2 |
+| 7 | 流式错误路径(`_complete_stream` 415-417)同样带摘要 | G2 |
+| 8 | `monkey_ocr._classify_status` 同款(含 `ResponseNotRead` 时降级为空串而非抛出) | G2, §4.2 |
+| 9 | embedding 路径(`:402`)HTTP 错误带摘要 | G2 |
+
+`tests/unit/test_errors.py:29` 现有的"四类构造形态"参数化用例需扩展 `body_text` 默认值断言(默认 `""`、可传入、`GatewayUnavailableError` 一族恒空)。
+
+## 8. 人类定夺记录(2026-08-16)
+
+| 议题 | 定夺 |
+|---|---|
+| 摘要上限与保留策略 | 初稿 500 + 头部硬切被否:上限提至 **2048**(对齐 k8s client-go 同场景先例),策略改为**头 1400 + 尾 600 + 省略字数标记**——人类指出"有用的信息可能只在后半部分",经调研证实 JSON 错误体的 `code`/`request_id` 确实收尾(§3.4、§3.4.1) |
+| 429 是否设例外 | **不设**,一律拼摘要(§3.3) |
+| 版本 | **1.2.0**,并同步把 README pin 由 `==1.1.*` 改为 `>=1.2,<2`(§5.3) |
@@ -0,0 +1,62 @@
+---
+type: design
+node_id: design:issue10-error-body-retention
+title: "HTTP 错误响应体留存(Issue #10)"
+date: 2026-08-16
+---
+
+# HTTP 错误响应体留存(Issue #10)
+
+**来源**: Gitea issue #10(CHSAnalyzer3 现场,1050 张影像批处理中 1 张 400 被判确定性失败、事后无从查证)|**范围**: `errors.py` + 两个 transport|**全文**: `designs/2026-08-16-issue10-error-body-retention-design.md`|**相关**: [[design:issue8-stall-budget]](同为下游实测反馈驱动的治理修正)
+
+## 问题
+
+网关拒绝一次调用时,它说的话在 transport 翻译层被丢弃,进程中不再有任何副本:该模块无 logger、异常类无承载字段、库遥测只写 message。三条留存通道同时为空,故"永久查不到"。
+
+## 根因(Issue 前提的关键修正)
+
+Issue 建议"给异常加 `body_text` 字段,下游就能记进遥测"——**只做这一半解决不了它自己陈述的痛点**。库的逐次遥测写的是 `error=str(exc)`(`retry.py:552` → `telemetry.py` → `sqlite.py` 的 `error TEXT` 列),即**异常 message**;新增字段不进库的遥测表。下游说的"写进遥测表"是他们自己的埋点。
+
+缺陷范围也大于 issue 所述:实为 6 处同构——`_status_to_error` 的 400 / 4xx 兜底 / 401·403 / 5xx 四支,`_translate_429` 两支(读了 body 判类型却不带),以及 `monkey_ocr._classify_status` 全部分支(message 只有 `HTTP {status}`)。Issue 场景"读表格"极可能正落在 OCR 路径。
+
+## 选定方案
+
+**摘要在翻译层算一次,同一份串同时进 message 与新增的基类字段**——前者解决"事后可查"(走既有遥测列,零 DDL),后者解决下游结构化留存。
+
+| 决策 | 理由 |
+|---|---|
+| 字段加在 `PolyGatewayError` 基类,非 `RequestRejectedError` | 这些错误全由同一个 HTTP 响应翻译而来,"对方说了什么"与"属于哪一类"正交;只加子类,下次给 `SourceDeadError` 加又是一次公共 API 变更 + 人类门 |
+| 与 `ResultInvalidError.raw_text` 的界限写进 docstring | `body_text` = 非 2xx 的拒绝理由;`raw_text` = 2xx 但不可解析的模型输出。两个"原文字段"不钉死必被混用 |
+| 新建 `transports/_http_errors.py` 共用摘要口径 | 两 transport 各有分类逻辑(OCR 无 429 细分,有意保留),但摘要必须同一份,否则就是下一个"只修一半" |
+| `_status_to_error` 改表驱动 | 五分支各拼各的 message,加摘要即五处重复;查表 + 单点拼装后代码更短 |
+| 摘要 = 折叠空白 + 总长 ≤ 2048,超出则**保留头 1400 + 尾 600**,中段记省略字数 | 折叠是因错误体常是缩进 JSON,拼进 message 会炸成多行。2048 对齐 k8s client-go 的 `maxUnstructuredResponseTextBytes`(唯一同场景先例);**头尾保留取自 `reprlib`**——JSON 错误体的 `code`/`request_id` 收尾,头部硬切正好切掉向网关追查唯一有用的部分(人类质疑 + 2026-08-16 调研,初稿的 500 + 头部硬切已废) |
+| 429 不设例外 | 例外就是下一个复发点;`insufficient_quota` 那支的配额细节全在 body 里 |
+| 400 治理语义不动,只补文档 | 见下 |
+
+## 400 语义:不改行为,本次修复本身就是答复
+
+Issue 给出有力证据(同字节 15 次重发全成功、`prompt_tokens=0`、2996ms 远低于同批成功最快的 7366ms),说明那次 400 来自中转服务抖动而非坏输入。**仍不改分类**:400 重试对直连供应商是纯浪费,而"中转也回 400"是部署拓扑引入的信息损失,库从状态码无从分辨;默认改可重试 = 让所有直连用户为一种部署形态买单。
+
+但 body 留存后**下游能自己区分**——中转抖动体与供应商 `invalid_request_error` 体形态不同。库不替下游判断,把判断所需的信息交出去。配套在 docstring 与 ARCHITECTURE §6.2 加一句中转拓扑提醒。
+
+## 被否决的备选
+
+| 备选 | 否决理由 |
+|---|---|
+| 遥测端口加一列(22 → 23 字段) | 端口签名变更 + 双后端 DDL + 下游 ALTER + 列序契约全线改动,为一个诊断串付出跨三项目迁移;复用既有 `error` 列可达成同样可查证性 |
+| 只打一条 WARNING 日志(issue 方向二) | 日志轮转后仍查不到,而痛点恰是"事后";且 4xx/5xx 在批处理下可能极高频 |
+| 截断放进异常构造器 | 下游自建异常的文本被悄悄改写(违反 P4),且 message 侧仍需单独算一次,反出现两条规范化路径 |
+| 错误分类映射可插拔 | Issue 场景确实指向它,但当前只有一个使用方且已用自己的兜底分类解决;`ProviderProfile` 无此扩展点,加它是子系统级设计。YAGNI |
+
+## 有意不夹带(留独立 issue)
+
+- `_status_to_error` 的 `operation` 硬编码 `"chat"`,而 `embed()` 也调它 → embedding 的 HTTP 错误在遥测里被标成 chat。
+- `_complete_stream` 的 `aread()` 对错误响应体无大小上限,超大错误体可打爆内存(既有风险,留存后更显眼)。
+
+两项都在本次触及的函数附近,但均不服务本 issue 目标,且各需独立行为讨论。
+
+## 验收主张
+
+一次 400 调用后,注入的 recorder 收到的 `error` 串含网关响应体摘要——这条端到端断言是本设计成立与否的唯一硬判据,其余用例为覆盖性(状态码参数化、截断边界 2048/2049、**尾部关键字段可见**、空白折叠、空体不拼悬空分隔符、非 UTF-8 不炸、流式路径、OCR 路径含 `ResponseNotRead` 降级)。
+
+**发布约束**:版本 1.2.0,且 README 安装 pin 必须由 `==1.1.*` 改为 `>=1.2,<2`——否则照 README 安装的下游静默停在 1.1.2,拿不到本修复。
@@ -0,0 +1,62 @@
+---
+type: design
+node_id: design:issue9-telemetry-ddl-probe
+title: "建表前先探测,判死只认「确定写不进去」"
+date: 2026-08-07
+---
+
+# 建表前先探测,判死只认「确定写不进去」
+
+**来源**: Gitea issue #9(CHSAnalyzer3 现场)|**范围**: `telemetry/postgres.py` 单模块,无独立 plan(小改动自判)|**相关**: [[design:response-observability-fields]](issue #3 修的是同一个坑的另一半)
+
+## 问题
+
+应用账号有表级 `INSERT`、表也已存在,但没有 schema 的 `CREATE` 权限时,`_ensure_ready()` 的 `CREATE TABLE IF NOT EXISTS` 被拒 → `_failed = True` → **整个进程遥测永久 no-op**。业务调用一切正常,只留一行 warning,从外部完全看不出异常;下游 CHSAnalyzer3 首次端到端跑的 150+ 次调用数据因此全丢且无法补回。
+
+## 根因
+
+**PostgreSQL 对 schema 的 CREATE 权限检查早于 `IF NOT EXISTS` 的存在性判断**(`RangeVarGetAndCheckCreationNamespace()` 先 aclcheck 后查 relid)。这与 issue #3 里 `ALTER TABLE` 的 ownership 检查早于 `IF NOT EXISTS` 是同一类问题——当时只修了补列那一半,建表这一半原样留着,于是同一账号形态下"补列失败只丢一行日志接着干活,建表失败却把整个 recorder 判死"。
+
+**实测(PostgreSQL 16.14,临时角色只授 `SELECT, INSERT ON llm_calls`)**:
+
+| 语句 | 结果 |
+|---|---|
+| `SELECT to_regclass('llm_calls')` | 非 NULL(表就在那儿) |
+| `CREATE TABLE IF NOT EXISTS llm_calls (...)` | **被拒 InsufficientPrivilegeError: permission denied for schema** |
+| `INSERT INTO llm_calls ...` | 通过 |
+| `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` | 被拒 must be owner(即 issue #3 那条) |
+
+## 选定方案
+
+两条,第二条才是治本的那条:
+
+1. **表存在就绝不发 DDL**。探测走 `to_regclass`(不需要任何权限,且与 `INSERT` 走同一套 search_path 解析——裸 `CREATE TABLE` 落在首个**可建**的 schema,可能与写入命中的不是同一张表,故探测优先反而更准)。表不存在才建;新建表列已齐全,顺带跳过补列。
+2. **"结构性失能"的判据从「初始化时出过异常」收窄为「确定写不进去」**:
+
+| 情形 | 处置 | 理由 |
+|---|---|---|
+| 建池失败 | 永久 no-op | 重试要在业务调用路径上内联吞掉 connect 超时 |
+| 表存在 | 不发 DDL,只补列(失败仅 warning) | 本 issue 的直接修复 |
+| 表不存在 → 建表成功 | 就绪,跳过补列 | 新建表列已齐 |
+| 表不存在 → 建表失败 | 永久 no-op | 后续 INSERT 必然全败,重试无意义、日志纯噪音 |
+| 探测/取连接失败 | 只跳过本条,下次调用重试 | 瞬时抖动,判死代价远大于多一次往返 |
+
+**SQLite 侧有意不对称**:实测其对已存在的表在**解析期**就把 `CREATE TABLE IF NOT EXISTS` 短路掉——另一连接持 `BEGIN EXCLUSIVE`、或文件 `chmod 444` 时该语句均通过(同条件下 `INSERT` 与新表名建表分别报 database is locked / readonly database),既不抢写锁也不检查可写性。故 PG 侧的坑在此不存在,加探测零收益。**需要对称的是保证(表存在就不该因建表失败而失能),不是代码**;结论已钉进 `sqlite.py` 模块 docstring,防止后人为"对称"加回来。
+
+## 被否决的备选
+
+| 备选 | 否决理由 |
+|---|---|
+| 只加探测,`_failed` 语义不动(issue 原方案) | 治标。初始化瞬间的 DB 抖动、一次 `pool.acquire` 失败、search_path 配错仍会让整个进程永久失遥测——同一个开关,换个触发口 |
+| 除建池外一律不判死 | 方向最统一,但表真的不存在时每次调用都发一条注定失败的 INSERT + 一条 warning(150 次调用 = 150 行噪音),而这种情形是**可确定判定**的,没必要留活路 |
+| 捕获 `InsufficientPrivilegeError` 特判放行 | 按异常类型打补丁,漏一种错误码就复发;探测是把"该不该发这条 DDL"判断在前,与错误面无关 |
+| SQLite 侧同步加探测 | 实测证明零收益,属为对称而对称的 gold-plating |
+
+## 遗留
+
+**SQLite 的窄缝**:表不存在 + 构造瞬间库被排他锁(多进程共库)→ `__init__` 里的建表失败 → recorder 永久失能。修它要把 SQLite 也改成 lazy 重试结构,超出本 issue 范围,记此备查。
+
+## 测试证据
+
+- 单测 `TestPostgresTableProbe`(5 例,fake conn):表存在不发 DDL / DDL 被拒仍照常 INSERT 且 `_failed` 不置位 / 表缺失则建表且不补列 / 表缺失且建不出来才判死 / 探测失败下次重试。
+- 集成 `TestLeastPrivilegeDeployment`(真实 PG,临时 schema + 临时角色,teardown 删净):先钉死"该角色确实建不了表"这条库外事实,再验两行记录照常落库。**修复前该用例复现 issue 原文那行 warning 并失败**。
@@ -150,6 +150,16 @@
      "id": "plan:issue8-stall-budget-plan",
      "label": "issue #8 实施计划: stall 非生产性等待口径",
      "type": "plan"
+    },
+    {
+      "id": "design:issue10-error-body-retention",
+      "label": "HTTP 错误响应体留存(Issue #10)",
+      "type": "design"
+    },
+    {
+      "id": "plan:issue10-error-body-retention-plan",
+      "label": "实现计划: HTTP 错误响应体留存(Issue #10)",
+      "type": "plan"
    }
  ],
  "links": [
@@ -271,6 +281,13 @@
      "relation": "implements",
      "evidence": "T1-T6 实施该设计,含 §3.6 订正",
      "added": "2026-08-06T14:58:01.673693+00:00"
+    },
+    {
+      "source": "plan:issue10-error-body-retention-plan",
+      "target": "design:issue10-error-body-retention",
+      "relation": "implements",
+      "evidence": "7 任务覆盖设计 G1-G4 与 §7 全部验收用例",
+      "added": "2026-08-16T09:50:57.830855+00:00"
    }
  ]
 }
@@ -1,8 +1,8 @@
 # Research Wiki 索引

-> 自动生成，更新时间：2026-08-06 14:58 UTC
+> 自动生成，更新时间：2026-08-16 09:50 UTC

-## design (25)
+## design (28)
 - [2026-07-20-m1-core-design](designs/2026-07-20-m1-core-design.md) `design:2026-07-20-m1-core-design`
 - [2026-07-20-m2-distributed-design](designs/2026-07-20-m2-distributed-design.md) `design:2026-07-20-m2-distributed-design`
 - [2026-07-21-m25-resilience-design](designs/2026-07-21-m25-resilience-design.md) `design:2026-07-21-m25-resilience-design`
@@ -15,9 +15,11 @@
 - [2026-07-31-sampling-params-design](designs/2026-07-31-sampling-params-design.md) `design:2026-07-31-sampling-params-design`
 - [2026-08-06-governance-backend-error-design](designs/2026-08-06-governance-backend-error-design.md) `design:2026-08-06-governance-backend-error-design`
 - [2026-08-06-issue8-stall-budget-design](designs/2026-08-06-issue8-stall-budget-design.md) `design:2026-08-06-issue8-stall-budget-design`
+- [2026-08-16-issue10-error-body-retention-design](designs/2026-08-16-issue10-error-body-retention-design.md) `design:2026-08-16-issue10-error-body-retention-design`
 - [est_tokens 解耦: 拆分限流预扣与遥测用量兜底(issue #2)](designs/est-tokens-decoupling.md) `design:est-tokens-decoupling`
 - [GatewaySettings 装配校验补齐(第二轮)](designs/settings-invariants-round-2.md) `design:settings-invariants-round-2`
 - [GatewaySettings 跨字段不变量守卫的生效范围](designs/settings-invariant-guards.md) `design:settings-invariant-guards`
+- [HTTP 错误响应体留存(Issue #10)](designs/issue10-error-body-retention.md) `design:issue10-error-body-retention`
 - [M1 核心里程碑设计:公共签名冻结与治理栈落地](designs/m1-core-design.md) `design:m1-core-design`
 - [M2 分布式:Redis 治理后端+背压+Postgres 遥测+pricing+Embedding+压测 harness](designs/m2-distributed.md) `design:m2-distributed`
 - [M2.5 治理韧性: 半死源隔离与健康感知调度](designs/m25-resilience.md) `design:m25-resilience`
@@ -25,6 +27,7 @@
 - [M4 迁移验证设计(GovDoc→CHS,发 v1.0)](designs/m4-migration.md) `design:m4-migration`
 - [stall 判定改为非生产性等待口径](designs/issue8-stall-budget.md) `design:issue8-stall-budget`
 - [响应可观测字段扩展(Issue #3)](designs/response-observability-fields.md) `design:response-observability-fields`
+- [建表前先探测,判死只认「确定写不进去」](designs/issue9-telemetry-ddl-probe.md) `design:issue9-telemetry-ddl-probe`
 - [推理开关能力建模与 reasoning_tokens 采集(issue #5 + #6)](designs/2026-08-02-thinking-capability-design.md) `design:2026-08-02-thinking-capability-design`
 - [治理后端故障归位为 scope 级不可用(Issue #7)](designs/governance-backend-error.md) `design:governance-backend-error`
 - [采样参数透传设计(issue #4)](designs/sampling-params.md) `design:sampling-params`
@@ -43,7 +46,7 @@
 - [P7 OCR soak 验收: 99.73% 与 13 不变量全 PASS](findings/p7-ocr-soak.md) `finding:p7-ocr-soak`
 - [推理开关与 reasoning_tokens: 供应商实测与业界做法](findings/2026-08-02-thinking-switch-and-reasoning-tokens.md) `finding:2026-08-02-thinking-switch-and-reasoning-tokens`

-## plan (21)
+## plan (23)
 - [2026-07-20-m1-core-plan](plans/2026-07-20-m1-core-plan.md) `plan:2026-07-20-m1-core-plan`
 - [2026-07-20-m2-distributed-plan](plans/2026-07-20-m2-distributed-plan.md) `plan:2026-07-20-m2-distributed-plan`
 - [2026-07-21-m25-resilience-plan](plans/2026-07-21-m25-resilience-plan.md) `plan:2026-07-21-m25-resilience-plan`
@@ -54,6 +57,7 @@
 - [2026-07-31-sampling-params](plans/2026-07-31-sampling-params.md) `plan:2026-07-31-sampling-params`
 - [2026-08-06-governance-backend-error-plan](plans/2026-08-06-governance-backend-error-plan.md) `plan:2026-08-06-governance-backend-error-plan`
 - [2026-08-06-issue8-stall-budget](plans/2026-08-06-issue8-stall-budget.md) `plan:2026-08-06-issue8-stall-budget`
+- [2026-08-16-issue10-error-body-retention](plans/2026-08-16-issue10-error-body-retention.md) `plan:2026-08-16-issue10-error-body-retention`
 - [est_tokens 解耦实施计划](plans/est-tokens-decoupling.md) `plan:est-tokens-decoupling`
 - [issue #8 实施计划: stall 非生产性等待口径](plans/issue8-stall-budget-plan.md) `plan:issue8-stall-budget-plan`
 - [M1 核心里程碑实现计划](plans/m1-core-plan.md) `plan:m1-core-plan`
@@ -62,6 +66,7 @@
 - [M3 OCR 实现计划](plans/m3-ocr.md) `plan:m3-ocr`
 - [M4 迁移实现计划(T0-T14)](plans/m4-migration.md) `plan:m4-migration`
 - [响应可观测字段扩展实现计划](plans/response-observability-fields.md) `plan:response-observability-fields`
+- [实现计划: HTTP 错误响应体留存(Issue #10)](plans/issue10-error-body-retention-plan.md) `plan:issue10-error-body-retention-plan`
 - [实现计划: 治理后端故障归位为 scope 级不可用(Issue #7)](plans/governance-backend-error.md) `plan:governance-backend-error`
 - [推理开关能力建模与 reasoning_tokens 采集实施计划(issue #5 + #6)](plans/2026-08-02-thinking-capability.md) `plan:2026-08-02-thinking-capability`
 - [采样参数透传实现计划(issue #4)](plans/sampling-params-plan.md) `plan:sampling-params-plan`
@@ -94,3 +94,11 @@
 - [2026-08-06 14:58 UTC] 新增 plan: issue #8 实施计划: stall 非生产性等待口径 (plan:issue8-stall-budget-plan)
 - [2026-08-06 14:58 UTC] 新增边: plan:issue8-stall-budget-plan --implements--> design:issue8-stall-budget
 - [2026-08-06 14:58 UTC] 重建索引: 61 篇页面
+- [2026-08-07 15:20 UTC] 新增 design: 建表前先探测,判死只认「确定写不进去」 (design:issue9-telemetry-ddl-probe)
+- [2026-08-07 15:20 UTC] 重建索引: 62 篇页面
+- [2026-08-07 15:11 UTC] 重建索引: 62 篇页面
+- [2026-08-16 09:09 UTC] 新增 design: HTTP 错误响应体留存(Issue #10) (design:issue10-error-body-retention)
+- [2026-08-16 09:12 UTC] 重建索引: 64 篇页面
+- [2026-08-16 09:50 UTC] 新增 plan: 实现计划: HTTP 错误响应体留存(Issue #10) (plan:issue10-error-body-retention-plan)
+- [2026-08-16 09:50 UTC] 新增边: plan:issue10-error-body-retention-plan --implements--> design:issue10-error-body-retention
+- [2026-08-16 09:50 UTC] 重建索引: 66 篇页面
@@ -0,0 +1,259 @@
+# 实现计划: HTTP 错误响应体留存(Issue #10)
+
+- **设计**: `research-wiki/designs/2026-08-16-issue10-error-body-retention-design.md`(**已批准 2026-08-16**)
+- **分支**: `feat/issue-10-error-body-retention`
+- **目标**: 网关拒绝一次调用时,它说的话必须能在库自己的遥测表里被事后查到。
+- **方案概述**: transport 翻译层把 HTTP 错误响应体折叠空白并按头尾策略摘要,**同一份串**同时拼进异常 message(经既有 `error` 列落遥测)与新增的基类字段 `body_text`(供下游结构化留存)。覆盖两个 transport 的全部非 2xx 分支。不改任何状态码→分类的映射。
+- **涉及技术**: Python 3.11 / httpx / pytest。无新增依赖。
+- **保真校验**: 本计划**不涉及** `reference/` 参考实现迁移——错误分类映射逐条不变,保真体现为"既有分类断言全部保留、无一条被改写"(Task 3/4 验收项)。
+
+## 文件结构
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `src/polygateway/errors.py` | 改 | 基类 `PolyGatewayError` 新增 `body_text` 字段;与 `raw_text` 的界限 docstring;`RequestRejectedError` 补中转拓扑提醒 |
+| `src/polygateway/transports/_http_errors.py` | **新建** | 摘要口径单一实现:`summarize_body` / `compose_message` / `response_body` + 三个常量 |
+| `src/polygateway/transports/openai_compat.py` | 改 | `_status_to_error` 表驱动重写;`_translate_429` 收 `ctx` |
+| `src/polygateway/transports/monkey_ocr.py` | 改 | `_classify_status` 带摘要 |
+| `tests/unit/test_http_error_body.py` | **新建** | 摘要单元的纯函数用例(截断边界、头尾保留、折叠、幂等) |
+| `tests/unit/test_openai_compat.py` | 改 | 状态码参数化断言 message + 字段;超长 `insufficient_quota` 回归 |
+| `tests/unit/test_monkey_ocr.py` | 改 | OCR 分支同款 + `ResponseNotRead` 降级 |
+| `tests/unit/test_errors.py` | 改 | `body_text` 默认值与可传性 |
+| `tests/integration/test_governance_stack.py` | 改 | **端到端验收**:400 调用后 SQLite `error` 列含摘要 |
+| `README.md` / `CHANGELOG.md` / `pyproject.toml` / `src/polygateway/__init__.py` / `research-wiki/ARCHITECTURE.md` | 改 | 文档与 1.2.0 版本号 |
+
+## 关键接口(跨任务消费,必须逐字一致)
+
+```python
+# src/polygateway/transports/_http_errors.py
+from __future__ import annotations
+
+import httpx                      # response_body 的类型与 ResponseNotRead 都来自它
+
+_ERROR_BODY_CAP = 2048   # 字符(非字节),含省略标记在内的最终总长上限
+_HEAD_CHARS = 1400
+_TAIL_CHARS = 600
+
+
+def summarize_body(text: str) -> str:
+    """折叠空白后按头尾策略摘要;空/空白入参返回空串。"""
+    collapsed = " ".join(text.split())
+    if len(collapsed) <= _ERROR_BODY_CAP:
+        return collapsed
+    omitted = len(collapsed) - _HEAD_CHARS - _TAIL_CHARS
+    return f"{collapsed[:_HEAD_CHARS]}…(略 {omitted} 字)…{collapsed[-_TAIL_CHARS:]}"
+
+
+def compose_message(message: str, summary: str) -> str:
+    """摘要非空才拼后缀,避免悬空分隔符。"""
+    return f"{message} | {summary}" if summary else message
+
+
+def response_body(response: httpx.Response) -> str:
+    """取已缓冲的响应文本;未读缓冲一律降级空串,绝不触发网络读。"""
+    try:
+        return response.text
+    except httpx.ResponseNotRead:
+        return ""
+```
+
+```python
+# src/polygateway/errors.py
+class PolyGatewayError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        source_name: str | None = None,
+        status_code: int | None = None,
+        operation: str | None = None,
+        body_text: str = "",
+    ) -> None:
+```
+
+```python
+# src/polygateway/transports/openai_compat.py
+# 既有 errors 导入(:18-23)须补入 PolyGatewayError —— 当前只导了四个子类,
+# 直接写 _classify 的返回注解会让 ruff 报 F821 未定义名。
+from polygateway.errors import (
+    PolyGatewayError,          # ← 新增
+    RequestRejectedError,
+    ResultInvalidError,
+    SourceDeadError,
+    TransientError,
+)
+from polygateway.transports._http_errors import compose_message, summarize_body
+
+
+def _classify(status: int) -> tuple[type[PolyGatewayError], str]:
+    """状态码 → (错误类, message 标签);映射与 1.1.2 逐条相同。"""
+    if status in (401, 403):
+        return SourceDeadError, "凭据失效/欠费"
+    if status == 400:
+        return RequestRejectedError, "请求被拒"
+    if status >= 500:
+        return TransientError, "瞬时错误"
+    return RequestRejectedError, "客户端错误"
+
+
+def _status_to_error(
+    source: SourceConfig, status: int, body_text: str, headers: Mapping[str, str]
+) -> Exception:
+    summary = summarize_body(body_text)          # 全函数只算一次
+    ctx: dict[str, Any] = {
+        "source_name": source.name,
+        "status_code": status,
+        "operation": "chat",
+        "body_text": summary,
+    }
+    if status == 429:
+        return _translate_429(source, body_text, headers, ctx)   # 传**原文**,见下
+    cls, label = _classify(status)
+    return cls(compose_message(f"{source.name} {label}: {status}", summary), **ctx)
+```
+
+> **实现红线**:`_translate_429` 判 `insufficient_quota` 必须解析**未截断的原文** `body_text`,不得改用 `summary`。摘要会破坏 JSON 结构,超长体一旦改用摘要解析,配额耗尽的源将不再 `force_open`——那是把一个诊断改进变成治理 bug。Task 3 有专门的回归用例钉死这条。
+
+## 任务清单
+
+### - [ ] Task 1: 内核新增 `body_text` 字段
+
+**改**: `src/polygateway/errors.py`
+
+- `PolyGatewayError.__init__` 按上文签名新增 `body_text: str = ""`,存为实例属性。
+- 类 docstring 增补与 `ResultInvalidError.raw_text` 的界限:`body_text` = 非 2xx 的 HTTP 错误响应体摘要(对方拒绝的理由);`raw_text` = 2xx 但内容不可解析时的模型输出。并写明"可能包含请求回显,已截断"。
+- **不动** `TransientError` / `SourceDeadError` / `RequestRejectedError` / `ResultInvalidError` / `GatewayUnavailableError` 的任何既有签名与行为。
+
+**测试**(`tests/unit/test_errors.py`,扩展 `:29` 的四类构造形态参数化):
+- 四个 transport 错误类默认 `body_text == ""`;显式传入后可读回。
+- `GatewayUnavailableError` / `CircuitOpenError` / `AllSourcesExhausted` / `GovernanceBackendError` 的 `body_text` 恒为 `""`(它们不经 HTTP 响应翻译)。
+
+**验收**: 新增字段不改变任何既有异常的 `str()` 输出。
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_errors.py -v` → 全 PASS。
+
+### - [ ] Task 2: 共享摘要单元
+
+**新建**: `src/polygateway/transports/_http_errors.py`(按上文"关键接口"逐字实现,**含其中的 `import httpx`**,加中文模块/函数 docstring 解释**为什么**折叠空白、为什么头尾保留、为什么 `response_body` 必须降级)
+
+**新建测试**: `tests/unit/test_http_error_body.py`
+
+| 用例 | 断言 |
+|---|---|
+| 短体原样 | `summarize_body('{"a":1}') == '{"a":1}'` |
+| 空白折叠 | 多行缩进 JSON → 单行,无连续空格 |
+| 空 / 纯空白入参 | 返回 `""` |
+| 长度恰 2048 | 原样返回,无标记 |
+| 长度 2049 | 走头尾策略 |
+| 超长体头尾 | 前 1400 字符 == 原文前 1400;**末 600 字符 == 原文末 600**;中段标记内 N == `len(原文) - 2000` |
+| **尾部关键字段可见**(设计 §7 用例 3c) | 以 issue 真实样本尾部 `"code":"invalid_parameter_error"}}` 收尾构造超长体 → 断言该串出现在摘要中 |
+| 幂等 | `summarize_body(summarize_body(x)) == summarize_body(x)`(标记不嵌套) |
+| `compose_message` | 摘要为空时返回原 message 不变;非空时以竖线分隔符拼接 |
+| `response_body` 降级 | `httpx.Response(400, stream=<未读 SyncByteStream>)` → 返回 `""` 且不抛(构造法见下) |
+
+未读响应的构造(已实测可用):
+
+```python
+class _Unread(httpx.SyncByteStream):
+    def __iter__(self):
+        yield b"body"
+
+resp = httpx.Response(400, stream=_Unread())   # 未 read → .text 抛 ResponseNotRead
+```
+
+**验收**: 摘要总长恒 ≤ `2000 + len(标记)`;头尾各自与原文逐字对应。
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_http_error_body.py -v` → 全 PASS。
+
+### - [ ] Task 3: openai_compat 翻译层收口
+
+**改**: `src/polygateway/transports/openai_compat.py`
+
+- 新增 `_classify`,`_status_to_error` 按上文骨架重写(五分支各拼各的 message → 查表 + 单点拼装)。
+- `_translate_429` 签名改为 `(source, body_text, headers, ctx)`,两支 message 各自追加 `compose_message` 后缀,构造改用 `**ctx`;**`json.loads` 仍读原文 `body_text`**。
+- message 主体逐字保持 1.1.2 原样(`凭据失效/欠费: {status}` / `请求被拒: 400` / `瞬时错误: {status}` / `客户端错误: {status}` / `配额耗尽(insufficient_quota)` / `限速: 429`),只在末尾追加 ` | {摘要}`。
+- 三个调用点(`:402` embed、`:417` stream、`:509` 非流式)签名不变,**不改动**。
+- **补 import**:`PolyGatewayError`(errors)与 `compose_message` / `summarize_body`(`._http_errors`),见上文关键接口——漏补则 `make lint` 报 F821(Codex 审查 2026-08-16 提出)。
+- **不改** `operation` 硬编码 `"chat"`(设计 §5.4 有意留给独立 issue)。
+
+**测试**(`tests/unit/test_openai_compat.py`,沿用既有 `_transport_for(handler)` + `httpx.MockTransport`):
+
+| # | 用例 | 断言 |
+|---|---|---|
+| 3.1 | 状态码参数化 400 / 401 / 403 / 404 / 500 / 503,handler 返回带真实样本体 | 异常类型与 1.1.2 **逐条相同**;message 含摘要;`exc.body_text` == 摘要 |
+| 3.2 | 429 普通限速(body 无 `insufficient_quota`) | `TransientError`,message 含摘要,`retry_after_s` 解析不受影响 |
+| 3.3 | 429 + `insufficient_quota` | `SourceDeadError`,message 含摘要 |
+| 3.4 | **回归红线**:429 + `insufficient_quota` 且 body 长度 > 2048(前置大量填充字段) | 仍判 `SourceDeadError`——证明类型判定读的是原文而非摘要 |
+| 3.5 | 空 body 的 400 | message 无悬空分隔符,`body_text == ""` |
+| 3.6 | 非 JSON body、非 UTF-8 字节 body | 不抛额外异常,分类不变 |
+| 3.7 | 流式路径(handler 对 stream 请求返回 400 + body) | 经 `_complete_stream:415-417` 抛出的异常同样带摘要 |
+| 3.8 | embedding 路径(`transport.embed(...)` 遇 400) | 同样带摘要 |
+
+**验收**: 既有测试零修改通过(除 3.x 新增外);`test_openai_compat.py:558`(match 源名)仍 PASS。
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_openai_compat.py -v` → 全 PASS。
+
+### - [ ] Task 4: monkey_ocr 同款收口
+
+**改**: `src/polygateway/transports/monkey_ocr.py`
+
+- `_classify_status`:`summary = summarize_body(response_body(exc.response))`,三支 message 统一经 `compose_message` 追加后缀,`ctx` 带 `body_text=summary`。
+- message 主体保持 `f"{source_name} OCR {operation} HTTP {status}"` 不变。
+- 429/5xx → `TransientError`、401/403 → `SourceDeadError`、其余 → `RequestRejectedError` 的映射**逐条不变**(OCR 无 429 细分是设计有意保留,见模块 docstring `:53-54`)。
+
+**测试**(`tests/unit/test_monkey_ocr.py`):
+- 扩展 `:300` 的状态码参数化:各分支 message 含摘要且 `body_text` 非空,分类不变。
+- `ResponseNotRead` 降级:`exc.response` 为未读流 → `body_text == ""`,message 无悬空分隔符,**分类仍正确**(不得因取 body 失败而改变错误类型或抛出 httpx 异常)。
+
+**验收**: `:195` 与 `:300` 既有断言不被改写。
+**验证**: `conda run -n PolyGateway pytest tests/unit/test_monkey_ocr.py -v` → 全 PASS。
+
+### - [ ] Task 5: 端到端遥测验收(**本计划的硬判据**)
+
+**改**: `tests/integration/test_governance_stack.py`
+
+新增用例,沿用既有 `_full_client(handler, telemetry=SQLiteRecorder(...))` 与 `:135` 的 `SELECT error FROM llm_calls` 断言模式:
+
+- handler 对 chat 请求返回 `httpx.Response(400, content=<issue #10 真实样本体>)`。
+- `client.chat(...)` 抛 `RequestRejectedError`(400 不重试不换源,行为不变)。
+- `recorder.close()` 后查 `SELECT error FROM llm_calls`:该行 `error` 串**含样本体里的 `InvalidParameter` 与结尾的 `invalid_parameter_error`**。
+
+真实样本体(取自 issue #10 原文,一字不改):
+
+```json
+{"error":{"message":"<400> ***.***.InvalidParameter: The image format is illegal and cannot be opened","type":"invalid_request_error","param":"","code":"invalid_parameter_error"}}
+```
+
+**验收**: 这条断言在 Task 1-4 之前**必然失败**(1.1.2 的 `error` 列只有 `"qwen_1 请求被拒: 400"`),之后通过——这就是本 issue 的"先失败后通过"证据主体,执行时须保留失败输出截图/文本进提交说明。
+**验证**: `conda run -n PolyGateway pytest tests/integration/test_governance_stack.py -v` → 全 PASS。
+
+### - [ ] Task 6: 文档与版本
+
+**改**:
+
+| 文件 | 内容 |
+|---|---|
+| `src/polygateway/errors.py` | `RequestRejectedError` docstring 加一句:经中转部署时 400 可能源于中转自身抖动,批处理场景下游宜自备兜底分类(设计 §5.2) |
+| `research-wiki/ARCHITECTURE.md` §6.2 | 同一提醒 + 注明四分类错误自 1.2.0 起携带 `body_text` |
+| `CHANGELOG.md` | 新增 `## 1.2.0(2026-08-16)` 段:行为变更(message 追加摘要 → 遥测 `error` 列变长)、新增字段、不变项(分类映射零变更、错误面零变更) |
+| `README.md:34` | 安装 pin `==1.1.*` → **`>=1.2,<2`**(2026-08-16 人类定夺;漏改则下游静默停在 1.1.2) |
+| `pyproject.toml` + `src/polygateway/__init__.py` | 版本号 `1.1.2` → `1.2.0`,**两处必须一致** |
+
+**验收**: `grep -rn "1\.1\.\*" README.md` 零命中;两处版本号一致。
+**验证**: `conda run -n PolyGateway python -c "import polygateway; print(polygateway.__version__)"` → `1.2.0`。
+
+### - [ ] Task 7: 合并前全量门
+
+1. `make lint`(ruff + import-linter)→ 零违规,**重点确认新建 `transports/_http_errors.py` 未触发洋葱分层契约**。
+2. `make test` 全套件 → 全 PASS,覆盖率不低于既有水平。
+3. 派**全新上下文** verifier subagent 独立验证(CLAUDE.md §3 Phase 2 硬门):逐条核对 Task 1-6 验收项与本会话工具输出。
+4. `finishing-a-development-branch` 合并回 main(`--no-ff`),合并后在 main 上重跑 `make lint` 与全套件。
+
+**发布**(合并后)严格按 CLAUDE.md §4.4.1 九步执行,不在本计划展开;其中步骤 1(更新 README)已在 Task 6 前置完成,**构建前须再次确认 pin 已是 `>=1.2,<2`**。
+
+## 执行顺序与提交点
+
+```
+Task 1 ──┐
+         ├── Task 3 ──┐
+Task 2 ──┴── Task 4 ──┴── Task 5 ── Task 6 ── Task 7
+```
+
+Task 1 与 2 可并行(互不依赖);Task 3、4 都依赖 1+2;Task 5 依赖 3;Task 6 独立于代码但须在 Task 7 之前。每个 Task 一次语义化提交(`commit` skill),Task 5 的提交说明须附"修复前失败、修复后通过"的实际输出。
@@ -0,0 +1,37 @@
+---
+type: plan
+node_id: plan:issue10-error-body-retention-plan
+title: "实现计划: HTTP 错误响应体留存(Issue #10)"
+date: 2026-08-16
+---
+
+# 实现计划: HTTP 错误响应体留存(Issue #10)
+
+**全文**: `plans/2026-08-16-issue10-error-body-retention.md`|**实现**: [[design:issue10-error-body-retention]]|**分支**: `feat/issue-10-error-body-retention`
+
+## 任务分解
+
+| # | 任务 | 产出 |
+|---|---|---|
+| 1 | 内核字段 | `PolyGatewayError.body_text`(默认空串)+ 与 `raw_text` 的界限 docstring |
+| 2 | 共享摘要单元 | 新建 `transports/_http_errors.py`:`summarize_body` / `compose_message` / `response_body` |
+| 3 | openai_compat 收口 | `_status_to_error` 表驱动;429 判类型仍读原文 |
+| 4 | monkey_ocr 收口 | `_classify_status` 同款,含 `ResponseNotRead` 降级 |
+| 5 | **端到端验收** | 400 调用后 SQLite `error` 列含摘要——本计划的硬判据 |
+| 6 | 文档与版本 | 1.2.0、README pin `>=1.2,<2`、CHANGELOG、ARCHITECTURE §6.2 |
+| 7 | 合并前门 | lint + 全套件 + 全新上下文 verifier |
+
+依赖:1‖2 → 3‖4 → 5 → 6 → 7。
+
+## 计划期钉死的两条实现红线
+
+1. **429 判 `insufficient_quota` 必须解析未截断原文**,不得改用摘要——摘要会破坏 JSON,超长体一旦改用摘要解析,配额耗尽的源将不再 `force_open`,把诊断改进变成治理 bug。Task 3.4 有专门回归用例。
+2. **message 主体逐字保持 1.1.2 原样**,只在末尾追加摘要后缀;状态码→分类映射逐条不变,验收要求既有分类断言零改写。
+
+## 保真校验
+
+不涉及 `reference/` 迁移。错误分类映射不变,保真体现为"既有分类断言全部保留"。
+
+## 执行期观察
+
+Task 计划提交时 pre-commit 钩子的全套件跑出现一次 `tests/e2e/test_compat_projects.py::TestGovDocOnboarding::test_call_site_shape_runs_governed` 失败,单独跑与 e2e 全目录跑(7 passed / 23.30s,每例 2-3.5s)均通过,重跑全套件亦通过 → 判为真实网关抖动,非回归。该用例正是 [[design:issue8-stall-budget]] 当年记录的三个漂移用例之一,e2e 打真实网关的固有 flaky 面仍在。
@@ -32,7 +32,7 @@ from polygateway.types import (
    SourceConfig,
 )

-__version__ = "1.1.1"
+__version__ = "1.2.0"

 __all__ = [
    "DEFAULT_PROFILES",
@@ -35,7 +35,26 @@ SOURCE_REASONS = frozenset(


 class PolyGatewayError(Exception):
-    """库内一切领域错误的基类,携带来源上下文便于遥测与日志定位。"""
+    """库内一切领域错误的基类,携带来源上下文便于遥测与日志定位。
+
+    `body_text` 是**非 2xx 响应体的摘要**——网关拒绝这次调用时说的话(issue #10)。
+    它与 `ResultInvalidError.raw_text` 是两回事,严禁混用:
+
+    ==============  ==================================================
+    ``body_text``   **非 2xx** 的 HTTP 错误响应体: 对方**拒绝**的理由
+    ``raw_text``    **2xx** 但内容不可解析时的模型输出原文
+    ==============  ==================================================
+
+    加在基类而非某个子类,是因为这些错误全部由同一个 HTTP 响应翻译而来——
+    "对方说了什么"与"它属于哪一类"正交。scope 级错误(`GatewayUnavailableError`
+    一族)继承到的恒空值不是噪音,而是"没有单一响应体可言"的如实表达。
+
+    **内容已由 transport 层截断**(`transports/_http_errors.summarize_body`),
+    且可能包含网关对请求的回显——库不做脱敏: 它不知道下游哪些字段敏感,
+    猜测式脱敏只会同时丢掉诊断价值与安全性。
+
+    本字段是**旁路数据**,不参与任何治理判定(重试/换源/熔断计数/限流结算)。
+    """

    def __init__(
        self,
@@ -44,11 +63,13 @@ class PolyGatewayError(Exception):
        source_name: str | None = None,
        status_code: int | None = None,
        operation: str | None = None,
+        body_text: str = "",
    ) -> None:
        super().__init__(message)
        self.source_name = source_name
        self.status_code = status_code
        self.operation = operation
+        self.body_text = body_text


 class TransientError(PolyGatewayError):
@@ -64,7 +85,16 @@ class SourceDeadError(PolyGatewayError):


 class RequestRejectedError(PolyGatewayError):
-    """请求被拒(400/坏输入): 不重试不换源,直接上抛。"""
+    """请求被拒(400/坏输入): 不重试不换源,直接上抛。
+
+    **经中转部署时请注意**(issue #10 下游实测): 第三方 API 中转服务自身抖动
+    时也会回 400,从状态码上与供应商说"你的输入有问题"无法区分。下游曾观测到
+    同一份字节(sha256 一致)重发 15 次全部成功,且失败那次 `prompt_tokens=0`、
+    耗时远低于任何成功调用——请求在推理开始前就被挡了。本库仍按确定性失败处理
+    (对直连供应商而言重试只会白烧配额),批处理场景的下游宜自备兜底分类;
+    `body_text` 即为此提供判据: 中转抖动的响应体与供应商的 `invalid_request_error`
+    形态不同。
+    """


 class ResultInvalidError(PolyGatewayError):
@@ -245,7 +245,7 @@ class StructuredOutputStrategy(Protocol):

@runtime_checkable
 class TelemetryRecorder(Protocol):
-    """遥测后端;20 字段冻结(M1 设计 §4.4 + issue #3),唯一调用点是 TelemetryEmitter。
+    """遥测后端;22 字段冻结(M1 设计 §4.4 + issue #3/#4),唯一调用点是 TelemetryEmitter。

    新增参数不设默认值: 库外无第三方实现者(三项目迁移时删除了各自的同名
    Protocol),完整签名的成本为零,而少写一列会被 emitter 的降级吞成 warning。
@@ -1,12 +1,17 @@
 """Postgres 遥测后端(M2 设计 §5): asyncpg lazy 池 + 两级降级。

 参考仓无先例(三项目遥测全 SQLite);asyncpg 工程写法取 GovDoc
-`taskrun/postgres_store.py`($n 占位、`CREATE TABLE IF NOT EXISTS`、
-`ON CONFLICT DO NOTHING`),但其"失败冒泡"方向按遥测铁律**有意反转**:
-① 结构性失败(建池/建表)→ warning 一次后永久降级(池置 None 短路);
+`taskrun/postgres_store.py`($n 占位、`ON CONFLICT DO NOTHING`),但其
+"失败冒泡"方向按遥测铁律**有意反转**:
+① 结构性失败 → warning 一次后永久降级(所有写入短路);
 ② 运行时单条写失败 → 逐条 warning 丢弃,不降级不重试(连接抖动由
 asyncpg 池自恢复;避免浸泡开头一次抖动导致后续全程失遥测)。
-构造不连库(lazy),20 列 schema 与 SQLite 版同名同序。
+构造不连库(lazy),22 列 schema 与 SQLite 版同名同序。
+
+**"结构性"的判据是「确定写不进去」,不是「初始化时出过错」**(issue #9):
+只有建池失败(重试要在业务路径上内联吞掉 connect 超时)与"表确定不存在
+且建不出来"(后续 INSERT 必然全败)才判死;探测失败、补列失败、取连接
+失败一律只 warning,让写入照常尝试或下次调用重试。
 """

 from __future__ import annotations
@@ -55,6 +60,9 @@ _BACKFILL = (
    ("reasoning_tokens", "ALTER TABLE llm_calls ADD COLUMN reasoning_tokens INTEGER"),
 )

+# 探测表是否存在;不需要任何权限,且与 INSERT 走同一套 search_path 解析
+_TABLE_EXISTS = "SELECT to_regclass('llm_calls')"
+
 # 探测现有列;尊重 search_path(to_regclass 按当前 search_path 解析)
 _EXISTING_COLUMNS = (
    "SELECT attname FROM pg_attribute "
@@ -111,30 +119,81 @@ class PostgresRecorder:
        self._init_lock = asyncio.Lock()

    async def _ensure_ready(self) -> asyncpg.Pool | None:
-        """lazy 建池+建表;结构性失败 warning 一次后永久降级(设计 §5 两级之一)。"""
+        """lazy 建池+备表;判死只认「确定写不进去」(issue #9),其余失败都留活路。"""
        if self._failed:
            return None
        if self._schema_ready:
            return self._pool
        async with self._init_lock:
-            if self._failed or self._schema_ready:
-                return None if self._failed else self._pool
-            try:
-                if self._pool is None:
-                    import asyncpg
-
-                    self._pool = await asyncpg.create_pool(self._dsn, timeout=10)
-                async with self._pool.acquire() as conn:
-                    await conn.execute(_DDL)
-                    await self._backfill_columns(conn)
-                self._schema_ready = True
-                return self._pool
-            except asyncio.CancelledError:
-                raise
-            except Exception as exc:
-                self._failed = True
-                logger.warning("Postgres 遥测初始化失败,后续记录降级为 no-op: {}", exc)
+            if self._failed:
                return None
+            if self._schema_ready:
+                return self._pool
+            pool = await self._open_pool()
+            if pool is None:
+                return None
+            return await self._prepare_schema(pool)
+
+    async def _open_pool(self) -> asyncpg.Pool | None:
+        """建池;失败即永久降级(唯一一处「无条件判死」)。"""
+        if self._pool is not None:
+            return self._pool
+        try:
+            import asyncpg
+
+            self._pool = await asyncpg.create_pool(self._dsn, timeout=10)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            # 池建不出来 = 确定写不进去;且每次调用重试都要内联吞掉 connect
+            # 超时,而遥测是业务路径上的 await —— 此处必须永久降级
+            self._failed = True
+            logger.warning("Postgres 遥测建池失败,后续记录降级为 no-op: {}", exc)
+            return None
+        return self._pool
+
+    async def _prepare_schema(self, pool: asyncpg.Pool) -> asyncpg.Pool | None:
+        """备好表并交回可用的池;瞬时失败只跳过本次,确定写不进去才判死。"""
+        try:
+            async with pool.acquire() as conn:
+                writable = await self._prepare_table(conn)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            # 池已在手,取连接/探测失败多为瞬时抖动: 不判死也不标就绪,
+            # 只跳过本次记录,下次调用重新准备
+            logger.warning("Postgres 遥测建表探测失败(跳过本条,下次重试): {}", exc)
+            return None
+        if not writable:
+            self._failed = True
+            return None
+        self._schema_ready = True
+        return pool
+
+    async def _prepare_table(self, conn: object) -> bool:
+        """备好 `llm_calls`;**表存在就绝不发 DDL**。返回 False 仅表示表确定不存在。
+
+        `CREATE TABLE IF NOT EXISTS` 不能无条件发: PostgreSQL 对 schema 的
+        CREATE 权限检查**早于** `IF NOT EXISTS` 的存在性判断(PG 16.14 实测:
+        只授 `SELECT, INSERT ON llm_calls` 的角色,表明明在、也写得进去,这一句
+        照样被拒 `permission denied for schema`)。这与 `_backfill_columns` 撞的
+        是同一类问题(issue #3/#9),故守卫也必须同款: 先探测,后 DDL。
+        探测走 `to_regclass`,不需要任何权限,且与 INSERT 的 search_path 解析
+        口径一致——比裸 DDL 更准(裸 `CREATE TABLE` 落在首个**可建**的 schema,
+        可能与 INSERT 命中的不是同一张表)。
+        """
+        exists = await conn.fetchval(_TABLE_EXISTS) is not None  # type: ignore[attr-defined]
+        if exists:
+            await self._backfill_columns(conn)  # 旧表可能缺列;失败只逐行降级
+            return True
+        try:
+            await conn.execute(_DDL)  # type: ignore[attr-defined]
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.warning("Postgres 遥测建表失败(表不存在,记录无处可落): {}", exc)
+            return False
+        return True  # 新建表列已齐全,无需再走补列

    async def _backfill_columns(self, conn: object) -> None:
        """给已存在的旧表补新列(issue #3);**先探测再 ALTER,失败绝不置 `_failed`**。
@@ -3,6 +3,14 @@
 蓝本 VT `adapters/telemetry.py`: 构造期建连接与表,失败降级为 no-op
 (记录基础设施不得拖垮业务调用);`INSERT OR IGNORE` 幂等(call_id 主键);
 写入经 threading.Lock 串行化后由 `asyncio.to_thread` 执行,不阻塞事件循环。
+
+**这里不做 postgres.py 那样的建表前探测,是实测后的有意不对称**(issue #9):
+SQLite 对已存在的表在**解析期**就把 `CREATE TABLE IF NOT EXISTS` 短路掉,
+既不抢写锁也不检查可写性——实测同一时刻另一连接持 `BEGIN EXCLUSIVE`、或
+文件 `chmod 444`,该语句均通过,而同条件下的 `INSERT` 与新表名建表分别报
+database is locked / readonly database。故 PG 侧"权限检查早于存在性判断"
+的坑在此不存在,加探测零收益。**别为了代码对称把它加回来**;需要对称的是
+保证(表存在就不该因建表失败而失能),这一条两侧都已满足。
 """

 from __future__ import annotations
@@ -0,0 +1,63 @@
+"""HTTP 错误响应体的取用与摘要(issue #10 设计 §3.2)。
+
+两个 transport 各有自己的状态码分类逻辑(OCR 有意不做 429 细分),但**摘要口径
+必须是同一份**——issue #10 的教训正是"只有一个分支用了响应体",一处例外就是
+下一次事后查不到原因。故本模块是全库唯一的摘要实现,不得在别处复制。
+"""
+
+from __future__ import annotations
+
+import httpx
+
+_ERROR_BODY_CAP = 2048
+"""摘要总长上限(**字符**,含省略标记在内)。
+
+取值对齐 Kubernetes client-go `rest/request.go` 的 `maxUnstructuredResponseTextBytes
+= 2048`——它是唯一与本设计同场景(读 HTTP 错误体做诊断)的成熟先例。按字符而非
+字节切,多字节字符不会被切成半个;`error` 列是 TEXT,无定长约束,不需要字节口径。
+"""
+
+_HEAD_CHARS = 1400
+_TAIL_CHARS = 600
+
+
+def summarize_body(text: str) -> str:
+    """折叠空白后按头尾策略摘要;空/空白入参返回空串。
+
+    **折叠空白**不是洁癖: 错误体常是缩进 JSON,原样拼进 message 会把一行日志
+    炸成多行、把遥测列变得不可读。
+
+    **保头保尾**而非头部硬切: 截断的对象是结构化 JSON,信息分布头重尾也重——
+    人话(`message`)在前,机器可判的 `type`/`code`/`param`/`request_id` 在后。
+    k8s/Sentry 用头部硬切是因为它们截的是任意文本;本函数截的是错误 JSON,
+    头部硬切正好切掉向网关方追查时唯一有用的那部分。策略取自标准库 `reprlib`
+    对"给人读的长字符串"的处置。
+
+    **标记记下省略字数**,读的人才知道自己丢了多少,不会误以为网关只说了这么多。
+    """
+    collapsed = " ".join(text.split())
+    if len(collapsed) <= _ERROR_BODY_CAP:
+        return collapsed
+    omitted = len(collapsed) - _HEAD_CHARS - _TAIL_CHARS
+    return f"{collapsed[:_HEAD_CHARS]}…(略 {omitted} 字)…{collapsed[-_TAIL_CHARS:]}"
+
+
+def compose_message(message: str, summary: str) -> str:
+    """摘要非空才拼后缀,避免留下悬空的分隔符。
+
+    分隔符取 ` | ` 而非既有的 `: `,让"库说的话"与"网关说的话"一眼可分。
+    """
+    return f"{message} | {summary}" if summary else message
+
+
+def response_body(response: httpx.Response) -> str:
+    """取**已缓冲**的响应文本;未读缓冲一律降级空串。
+
+    绝不在此触发网络读: 那会在错误路径上凭空插入一次可能挂住的 IO。降级方向
+    与缓存/遥测同档(库铁律)——诊断信息缺失不得把一次本可正确分类的失败变成
+    不可分类的崩溃,那正是 `ResponseNotRead` 泄漏出四分类之外的后果。
+    """
+    try:
+        return response.text
+    except httpx.ResponseNotRead:
+        return ""
@@ -24,6 +24,11 @@ from polygateway.errors import (
    SourceDeadError,
    TransientError,
 )
+from polygateway.transports._http_errors import (
+    compose_message,
+    response_body,
+    summarize_body,
+)
 from polygateway.types import (
    OcrLayoutElement,
    OcrLayoutTransportResult,
@@ -74,13 +79,20 @@ def _translate_http_errors(source_name: str, operation: str) -> Iterator[None]:
 def _classify_status(
    exc: httpx.HTTPStatusError, source_name: str, operation: str
 ) -> TransientError | SourceDeadError | RequestRejectedError:
+    """HTTP 状态码 → 错误四分类,**全部分支**携带响应体摘要(issue #10)。
+
+    分类映射本身零变更;摘要口径与 chat 侧共用同一实现,不得在此另起一份——
+    "只有一个分支用了响应体"正是 issue #10 的成因。
+    """
    status = exc.response.status_code
+    summary = summarize_body(response_body(exc.response))
    ctx: dict[str, Any] = {
        "source_name": source_name,
        "status_code": status,
        "operation": operation,
+        "body_text": summary,
    }
-    message = f"{source_name} OCR {operation} HTTP {status}"
+    message = compose_message(f"{source_name} OCR {operation} HTTP {status}", summary)
    if status >= 500 or status == 429:
        return TransientError(message, **ctx)
    if status in (401, 403):
@@ -16,6 +16,7 @@ from typing import TYPE_CHECKING, Any
 import httpx

 from polygateway.errors import (
+    PolyGatewayError,
    RequestRejectedError,
    ResultInvalidError,
    SourceDeadError,
@@ -30,6 +31,7 @@ from polygateway.providers import (
    resolve_thinking,
 )
 from polygateway.streaming import StreamLivenessTimeout, stream_with_liveness_timeouts
+from polygateway.transports._http_errors import compose_message, summarize_body
 from polygateway.types import EmbeddingTransportResult, SourceConfig, TransportResult

 if TYPE_CHECKING:
@@ -107,40 +109,59 @@ def _parse_retry_after(raw: str | None) -> float | None:
    return seconds if seconds > 0 else None


-def _translate_429(source: SourceConfig, body_text: str, headers: Mapping[str, str]) -> Exception:
+def _translate_429(
+    source: SourceConfig, body_text: str, headers: Mapping[str, str], ctx: dict[str, Any]
+) -> Exception:
+    """429 细分。`body_text` 必须是**未截断的原文**——`ctx["body_text"]` 是摘要,
+    头尾保留会破坏 JSON 结构,拿它解析会让超长 body 的配额耗尽退化成普通限速
+    (该源不再 force_open),把一个诊断改进变成治理 bug(issue #10 实现红线)。
+    """
    try:
        err_type = json.loads(body_text).get("error", {}).get("type", "")
    except (json.JSONDecodeError, AttributeError):
        err_type = ""
+    summary = ctx["body_text"]
    if err_type == "insufficient_quota":
        return SourceDeadError(
-            f"{source.name} 配额耗尽(insufficient_quota)",
-            source_name=source.name,
-            status_code=429,
-            operation="chat",
+            compose_message(f"{source.name} 配额耗尽(insufficient_quota)", summary), **ctx
        )
    return TransientError(
-        f"{source.name} 限速: 429",
+        compose_message(f"{source.name} 限速: 429", summary),
        retry_after_s=_parse_retry_after(headers.get("retry-after")),
-        source_name=source.name,
-        status_code=429,
-        operation="chat",
+        **ctx,
    )


+def _classify(status: int) -> tuple[type[PolyGatewayError], str]:
+    """状态码 → (错误类, message 标签);映射与 ARCH §6.2 逐条相同,本次零变更。"""
+    if status in (401, 403):
+        return SourceDeadError, "凭据失效/欠费"
+    if status == 400:
+        return RequestRejectedError, "请求被拒"
+    if status >= 500:
+        return TransientError, "瞬时错误"
+    return RequestRejectedError, "客户端错误"
+
+
 def _status_to_error(
    source: SourceConfig, status: int, body_text: str, headers: Mapping[str, str]
 ) -> Exception:
-    ctx: dict[str, Any] = {"source_name": source.name, "status_code": status, "operation": "chat"}
-    if status in (401, 403):
-        return SourceDeadError(f"{source.name} 凭据失效/欠费: {status}", **ctx)
-    if status == 400:
-        return RequestRejectedError(f"{source.name} 请求被拒: 400", **ctx)
+    """非 2xx → 领域错误,**全部分支**携带响应体摘要(issue #10)。
+
+    摘要只算一次,message 与 `body_text` 共用同一份串: 两份不同长度会让"遥测里
+    看到的"与"下游 catch 到的"对不上,排查时反而多一层困惑。
+    """
+    summary = summarize_body(body_text)
+    ctx: dict[str, Any] = {
+        "source_name": source.name,
+        "status_code": status,
+        "operation": "chat",
+        "body_text": summary,
+    }
    if status == 429:
-        return _translate_429(source, body_text, headers)
-    if status >= 500:
-        return TransientError(f"{source.name} 瞬时错误: {status}", **ctx)
-    return RequestRejectedError(f"{source.name} 客户端错误: {status}", **ctx)
+        return _translate_429(source, body_text, headers, ctx)
+    cls, label = _classify(status)
+    return cls(compose_message(f"{source.name} {label}: {status}", summary), **ctx)


 def _strip_think(content: str) -> tuple[str, str]:
@@ -11,7 +11,12 @@ import sqlite3
 import httpx
 import pytest

-from polygateway import CircuitOpenError, GatewayClient, TransientError
+from polygateway import (
+    CircuitOpenError,
+    GatewayClient,
+    RequestRejectedError,
+    TransientError,
+)
 from polygateway.backends.memory.breaker import InMemoryGate
 from polygateway.backends.memory.cache import InMemoryCache
 from polygateway.backends.memory.limiter import InMemoryLimiter
@@ -173,6 +178,40 @@ class TestTelemetryAcrossPaths:
        assert len({cid for _, cid in rows}) == 2  # call_id 逐次独立


+class TestRejectionReasonIsQueryable:
+    """issue #10 的验收主张: 400 之后,网关说的话必须能在遥测表里查到。
+
+    下游一轮 1050 张影像的批处理里,1 张在读表格时收到 400 被判确定性失败,
+    事后"这张图到底哪里不合规"无从查起——响应体在 transport 翻译层就没了。
+    """
+
+    # issue #10 原文给出的真实响应体(一字不改)
+    _BODY = (
+        '{"error":{"message":"<400> ***.***.InvalidParameter: The image format is illegal '
+        'and cannot be opened","type":"invalid_request_error","param":"",'
+        '"code":"invalid_parameter_error"}}'
+    )
+
+    async def test_rejected_call_leaves_the_reason_in_telemetry(self, tmp_path):
+        recorder = SQLiteRecorder(tmp_path / "t.db")
+        client = _full_client(
+            lambda req: httpx.Response(400, content=self._BODY.encode()), telemetry=recorder
+        )
+
+        with pytest.raises(RequestRejectedError):
+            await client.chat([{"role": "user", "content": "hi"}])
+
+        recorder.close()
+        rows = sqlite3.connect(tmp_path / "t.db").execute("SELECT error FROM llm_calls").fetchall()
+        assert rows, "400 必须留下遥测行(遥测必录)"
+        errors = " ".join(r[0] or "" for r in rows)
+        # 修复前这里只有 "qwen_1 请求被拒: 400"——诊断信息一个字都不在
+        assert "InvalidParameter" in errors
+        assert "The image format is illegal" in errors
+        # 尾部的 code 才是向网关方追查的凭据,头部硬切正好会丢掉它
+        assert "invalid_parameter_error" in errors
+
+
 class TestStructuredThroughStack:
    async def test_feedback_reask_passes_through_governance(self):
        """重问经过内层治理: 第二次真实请求同样被限流/熔断记账。"""
@@ -13,6 +13,7 @@ from __future__ import annotations
 import asyncio
 import json
 import os
+import re
 from uuid import uuid4

 import pytest
@@ -299,3 +300,88 @@ class TestDegradation:
        await _record_minimal(recorder)
        await recorder.aclose()
        await recorder.aclose()
+
+
+_PROBE_PASSWORD = "pgw_issue9_probe"  # 临时角色,teardown 删除;非任何真实凭据
+
+
+@pytest.fixture
+async def least_privilege_dsn(dsn):
+    """临时 schema + 临时角色: 只授表级 SELECT/INSERT,**不授 schema CREATE**。
+
+    这是 issue #9 的现场——最小权限部署的标准形态。fixture 建的一切
+    (schema、表、角色)都在 teardown 里删净,共享的 public.llm_calls 不受影响;
+    连不上或无权建角色(非超级用户)时 skip,不让 CI 假绿。
+    """
+    import asyncpg
+
+    from polygateway.telemetry.postgres import _DDL
+
+    name = f"pgwtest_lp_{uuid4().hex[:8]}"
+    admin = await asyncpg.connect(dsn, timeout=10)
+    try:
+        if not await admin.fetchval(
+            "SELECT rolcreaterole OR rolsuper FROM pg_roles WHERE rolname = current_user"
+        ):
+            pytest.skip("当前账号无权建临时角色,跳过最小权限用例")
+        await admin.execute(f"CREATE ROLE {name} LOGIN PASSWORD '{_PROBE_PASSWORD}'")
+        await admin.execute(f"CREATE SCHEMA {name}")
+        await admin.execute(f"SET search_path = {name}")
+        await admin.execute(_DDL)  # 表由**别的账号**建好,与现场一致
+        await admin.execute(f"GRANT USAGE ON SCHEMA {name} TO {name}")
+        await admin.execute(f"GRANT SELECT, INSERT ON {name}.llm_calls TO {name}")
+        # 关键: 绝不 GRANT CREATE ON SCHEMA —— 缺的正是这一项
+    finally:
+        await admin.close()
+    low = re.sub(r"//[^@/]+@", f"//{name}:{_PROBE_PASSWORD}@", dsn, count=1)
+    sep = "&" if "?" in low else "?"
+    yield f"{low}{sep}options=-csearch_path%3D{name}", name
+    admin = await asyncpg.connect(dsn, timeout=10)
+    try:
+        await admin.execute(f"DROP SCHEMA IF EXISTS {name} CASCADE")
+        await admin.execute(f"DROP OWNED BY {name}")
+        await admin.execute(f"DROP ROLE IF EXISTS {name}")
+    finally:
+        await admin.close()
+
+
+class TestLeastPrivilegeDeployment:
+    """issue #9: 只有表级写权限的账号,遥测必须照常落库而不是整体判死。"""
+
+    async def test_create_table_if_not_exists_is_denied_for_this_role(self, least_privilege_dsn):
+        """库外事实先钉死: 表存在、写得进去,DDL 仍被拒——PG 的权限检查早于 IF NOT EXISTS。
+
+        修复依赖的是这条 PG 语义;若某天它变了,这里先红,而不是让下面那条
+        用例悄悄变成"永远通过"的空断言。
+        """
+        import asyncpg
+
+        low_dsn, _ = least_privilege_dsn
+        conn = await asyncpg.connect(low_dsn, timeout=10)
+        try:
+            assert await conn.fetchval("SELECT to_regclass('llm_calls')") is not None
+            with pytest.raises(asyncpg.exceptions.InsufficientPrivilegeError):
+                await conn.execute("CREATE TABLE IF NOT EXISTS llm_calls (call_id TEXT)")
+        finally:
+            await conn.close()
+
+    async def test_records_land_without_schema_create_privilege(self, least_privilege_dsn):
+        """修复前: 建表被拒 → _failed → 整个进程一条不落(下游 150 次调用全丢)。"""
+        low_dsn, schema = least_privilege_dsn
+        recorder = PostgresRecorder(low_dsn)
+        try:
+            await _record_minimal(recorder, call_id=_cid("lp1"))
+            await _record_minimal(recorder, call_id=_cid("lp2"), cost=1.5)
+            assert recorder._failed is False  # 判死开关不得被建表权限触发
+            rows = await _fetch(
+                low_dsn,
+                "SELECT call_id, cost FROM llm_calls WHERE call_id LIKE $1 ORDER BY call_id",
+                f"{_RUN_PREFIX}-lp%",
+            )
+            assert [(r["call_id"], r["cost"]) for r in rows] == [
+                (_cid("lp1"), None),
+                (_cid("lp2"), 1.5),
+            ]
+            assert schema  # teardown 会连表带角色删净
+        finally:
+            await recorder.aclose()
@@ -34,6 +34,43 @@ class TestBaseShape:
        assert TransientError("429", retry_after_s=2.5).retry_after_s == 2.5


+class TestBodyText:
+    """issue #10: 非 2xx 的响应体摘要必须有承载处,否则拒绝理由事后不可查。"""
+
+    @pytest.mark.parametrize(
+        "cls", (PolyGatewayError, TransientError, SourceDeadError, RequestRejectedError)
+    )
+    def test_defaults_empty_and_accepts_summary(self, cls):
+        assert cls("boom").body_text == ""
+        assert cls("boom", body_text='{"error":{"code":"bad"}}').body_text == (
+            '{"error":{"code":"bad"}}'
+        )
+
+    def test_result_invalid_keeps_both_fields_apart(self):
+        """`body_text`(非 2xx 的拒绝理由)与 `raw_text`(2xx 的不可解析输出)不得混用。"""
+        exc = ResultInvalidError("bad json", raw_text="{oops", body_text="")
+        assert exc.raw_text == "{oops"
+        assert exc.body_text == ""
+
+    @pytest.mark.parametrize(
+        "exc",
+        (
+            AllSourcesExhausted(scope="llm", reason="stalled", retry_after_s=1.0),
+            CircuitOpenError(scope="llm", retry_after_s=1.0),
+            GovernanceBackendError("redis down", scope="llm"),
+        ),
+    )
+    def test_scope_level_errors_carry_no_body(self, exc):
+        """scope 级失败没有单一响应体可言,空串是如实表达而非噪音。"""
+        assert exc.body_text == ""
+
+    def test_body_text_does_not_leak_into_str(self):
+        """字段是旁路数据: 加了它不得改变任何既有异常的 str() 输出。"""
+        assert str(RequestRejectedError("qwen_1 请求被拒: 400", body_text="whatever")) == (
+            "qwen_1 请求被拒: 400"
+        )
+
+
 class TestResultInvalid:
    def test_carries_diagnosis(self):
        exc = ResultInvalidError(
@@ -134,9 +171,7 @@ class TestGovernanceBackendReason:
        assert "governance_backend_down" in SCOPE_REASONS

    def test_gateway_unavailable_accepts_the_new_reason(self):
-        exc = AllSourcesExhausted(
-            scope="LLM", reason="governance_backend_down", retry_after_s=0.0
-        )
+        exc = AllSourcesExhausted(scope="LLM", reason="governance_backend_down", retry_after_s=0.0)
        assert exc.reason == "governance_backend_down"

    def test_retry_after_default_is_non_zero(self):
@@ -0,0 +1,89 @@
+"""HTTP 错误响应体摘要口径(issue #10 设计 §3.2/§3.4)。
+
+摘要是 message 与 `body_text` 共用的**同一份串**,故它的边界行为直接决定
+遥测里看到的与下游 catch 到的是否一致——本组用例把规则钉成算术。
+"""
+
+import httpx
+import pytest
+
+from polygateway.transports._http_errors import (
+    _ERROR_BODY_CAP,
+    _HEAD_CHARS,
+    _TAIL_CHARS,
+    compose_message,
+    response_body,
+    summarize_body,
+)
+
+# issue #10 原文给出的真实响应体(一字不改),关键在于 code 收尾
+_REAL_SAMPLE = (
+    '{"error":{"message":"<400> ***.***.InvalidParameter: The image format is illegal '
+    'and cannot be opened","type":"invalid_request_error","param":"",'
+    '"code":"invalid_parameter_error"}}'
+)
+
+
+class TestSummarizeBody:
+    def test_short_body_passes_through(self):
+        assert summarize_body(_REAL_SAMPLE) == _REAL_SAMPLE
+
+    def test_whitespace_collapsed(self):
+        """错误体常是缩进 JSON: 不折叠会把一行日志炸成多行、遥测列不可读。"""
+        assert (
+            summarize_body('{\n  "error": {\n    "code": "x"\n  }\n}')
+            == '{ "error": { "code": "x" } }'
+        )
+
+    @pytest.mark.parametrize("raw", ("", "   ", "\n\t  \n"))
+    def test_blank_yields_empty(self, raw):
+        assert summarize_body(raw) == ""
+
+    def test_exactly_at_cap_is_untouched(self):
+        body = "x" * _ERROR_BODY_CAP
+        assert summarize_body(body) == body
+
+    def test_one_over_cap_is_summarized(self):
+        summary = summarize_body("x" * (_ERROR_BODY_CAP + 1))
+        assert summary != "x" * (_ERROR_BODY_CAP + 1)
+        assert "略" in summary
+
+    def test_head_and_tail_both_survive(self):
+        """头部硬切会丢掉尾部,而 JSON 错误体的 code/request_id 正在尾部。"""
+        body = "H" * 5000 + "T" * 5000
+        summary = summarize_body(body)
+        assert summary[:_HEAD_CHARS] == body[:_HEAD_CHARS]
+        assert summary[-_TAIL_CHARS:] == body[-_TAIL_CHARS:]
+        assert f"…(略 {10000 - _HEAD_CHARS - _TAIL_CHARS} 字)…" in summary
+
+    def test_real_sample_tail_visible_in_oversized_body(self):
+        """设计 §7 用例 3c: 超长体里,追查网关方所需的 code 仍须可见。"""
+        summary = summarize_body("PADDING" * 1000 + _REAL_SAMPLE)
+        assert '"code":"invalid_parameter_error"}}' in summary
+
+    def test_idempotent(self):
+        """再摘要一次不得嵌套标记,否则重复经手的串会层层套娃。"""
+        once = summarize_body("y" * 9999)
+        assert summarize_body(once) == once
+
+
+class TestComposeMessage:
+    def test_empty_summary_leaves_message_intact(self):
+        assert compose_message("qwen_1 请求被拒: 400", "") == "qwen_1 请求被拒: 400"
+
+    def test_non_empty_summary_is_appended(self):
+        assert compose_message("qwen_1 请求被拒: 400", "{}") == "qwen_1 请求被拒: 400 | {}"
+
+
+class TestResponseBody:
+    def test_reads_buffered_text(self):
+        assert response_body(httpx.Response(400, content=b'{"e":1}')) == '{"e":1}'
+
+    def test_unread_stream_degrades_to_empty(self):
+        """取不到诊断信息绝不能升级为崩溃: 未读缓冲返回空串,且不触发网络读。"""
+
+        class _Unread(httpx.SyncByteStream):
+            def __iter__(self):
+                yield b"body"
+
+        assert response_body(httpx.Response(400, stream=_Unread())) == ""
@@ -19,7 +19,11 @@ from polygateway.errors import (
    SourceDeadError,
    TransientError,
 )
-from polygateway.transports.monkey_ocr import MonkeyOcrTransport, _parse_middle_json
+from polygateway.transports.monkey_ocr import (
+    MonkeyOcrTransport,
+    _classify_status,
+    _parse_middle_json,
+)
 from polygateway.types import SourceConfig


@@ -306,6 +310,45 @@ class TestErrorTranslation:
            await t.recognize_text(image=b"jpg", source=_source(), call_id="c1")
        assert ei.value.status_code == status

+    @pytest.mark.parametrize(
+        ("status", "exc_type"),
+        [
+            (502, TransientError),
+            (429, TransientError),  # 与 5xx 共用分支,但仍单列: 漏分支正是 issue #10 的成因
+            (401, SourceDeadError),
+            (404, RequestRejectedError),
+        ],
+    )
+    async def test_body_survives_every_branch(self, status, exc_type):
+        """issue #10: OCR 侧 message 原本只有 HTTP 状态码,拒绝理由同样丢失。"""
+        body = '{"detail":"unsupported image mode CMYK"}'
+        t = _transport_for(_routes(text_resp=httpx.Response(status, content=body.encode())))
+        with pytest.raises(exc_type) as ei:
+            await t.recognize_text(image=b"jpg", source=_source(), call_id="c1")
+        assert ei.value.body_text == body
+        assert str(ei.value).endswith(f" | {body}")
+
+    def test_unread_body_degrades_without_changing_class(self):
+        """取不到 body 时降级空串: 绝不能让 ResponseNotRead 逃出错误四分类。
+
+        直接测纯函数而非走 MockTransport——真实客户端对非 stream 请求总会读完
+        响应,未读态只可能在将来给 OCR 加 stream 时出现,而那正是要防的场景。
+        """
+
+        class _Unread(httpx.SyncByteStream):
+            def __iter__(self):
+                yield b"body"
+
+        exc = httpx.HTTPStatusError(
+            "404",
+            request=httpx.Request("POST", "http://ocr.example/ocr/text"),
+            response=httpx.Response(404, stream=_Unread()),
+        )
+        err = _classify_status(exc, "monkey_1", "text")
+        assert isinstance(err, RequestRejectedError)
+        assert err.body_text == ""
+        assert str(err) == "monkey_1 OCR text HTTP 404"
+
    async def test_connect_error_transient(self):
        def handler(request):
            raise httpx.ConnectError("refused", request=request)
@@ -16,6 +16,7 @@ from polygateway.errors import (
 )
 from polygateway.middleware.telemetry import TelemetryEmitter
 from polygateway.pricing import ModelPrice, PricingTable
+from polygateway.transports._http_errors import summarize_body
 from polygateway.transports.openai_compat import (
    OpenAICompatTransport,
    _iter_sse_deltas,
@@ -691,6 +692,125 @@ class TestErrorTranslation:
            await _complete(_transport_for(handler), _source())


+# issue #10 原文给出的真实响应体(一字不改): 关键在于 code 收尾
+_REJECT_BODY = (
+    '{"error":{"message":"<400> ***.***.InvalidParameter: The image format is illegal '
+    'and cannot be opened","type":"invalid_request_error","param":"",'
+    '"code":"invalid_parameter_error"}}'
+)
+
+
+class TestErrorBodyRetention:
+    """issue #10: 网关说了什么必须活着离开翻译层——message 与字段各留一份。"""
+
+    @pytest.mark.parametrize(
+        ("status", "exc"),
+        [
+            (400, RequestRejectedError),
+            (401, SourceDeadError),
+            (403, SourceDeadError),
+            (404, RequestRejectedError),
+            (500, TransientError),
+            (503, TransientError),
+        ],
+    )
+    async def test_every_non_2xx_branch_keeps_the_body(self, status, exc):
+        def handler(request):
+            return httpx.Response(status, content=_REJECT_BODY.encode())
+
+        with pytest.raises(exc) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert ei.value.body_text == _REJECT_BODY
+        # message 与字段共用同一份串: 遥测里看到的与下游 catch 到的不得打架
+        assert str(ei.value).endswith(f" | {_REJECT_BODY}")
+        assert "invalid_parameter_error" in str(ei.value)
+
+    async def test_rate_limited_429_keeps_body_and_retry_after(self):
+        def handler(request):
+            return httpx.Response(
+                429,
+                content=b'{"error":{"message":"per-minute cap 3"}}',
+                headers={"retry-after": "2.5"},
+            )
+
+        with pytest.raises(TransientError) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert "per-minute cap 3" in str(ei.value)
+        assert ei.value.retry_after_s == 2.5  # 摘要不得干扰既有解析
+
+    async def test_insufficient_quota_429_keeps_body(self):
+        body = json.dumps(
+            {"error": {"type": "insufficient_quota", "message": "daily budget spent"}}
+        )
+
+        def handler(request):
+            return httpx.Response(429, content=body.encode())
+
+        with pytest.raises(SourceDeadError) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert "daily budget spent" in str(ei.value)
+
+    async def test_oversized_insufficient_quota_still_classified_dead(self):
+        """实现红线: 类型判定必须读**原文**。
+
+        摘要会破坏 JSON 结构,若改用摘要解析,超长 body 的配额耗尽将退化成普通
+        限速——配额已耗尽的源不再 force_open,一个诊断改进就变成了治理 bug。
+
+        **填充必须是多个键**,不能是单个超长字符串值: 后者的截断点落在字符串
+        *内部*,省略标记成了合法的字符串内容,而头尾保留又让尾部的 error 对象
+        幸存——摘要照样解析得出 `insufficient_quota`,用例即告空转(2026-08-16
+        verifier 变异测试发现: 按错误写法实现,全套件 824 项依然全绿)。多键
+        填充让截断点落在结构记号之间,摘要才真正不可解析。
+        """
+        body = json.dumps(
+            {**{f"k{i}": "v" * 10 for i in range(300)}, "error": {"type": "insufficient_quota"}}
+        )
+        assert len(body) > 2048
+        with pytest.raises(json.JSONDecodeError):
+            # 判别力的前提: 摘要确实不再是合法 JSON,读它必然拿不到 type
+            json.loads(summarize_body(body))
+
+        def handler(request):
+            return httpx.Response(429, content=body.encode())
+
+        with pytest.raises(SourceDeadError):
+            await _complete(_transport_for(handler), _source())
+
+    async def test_empty_body_leaves_no_dangling_separator(self):
+        def handler(request):
+            return httpx.Response(400, content=b"")
+
+        with pytest.raises(RequestRejectedError) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert str(ei.value) == "qwen_1 请求被拒: 400"
+        assert ei.value.body_text == ""
+
+    @pytest.mark.parametrize("body", [b"<html>gateway down</html>", b"\xff\xfe not utf-8"])
+    async def test_non_json_and_non_utf8_bodies_do_not_explode(self, body):
+        def handler(request):
+            return httpx.Response(400, content=body)
+
+        with pytest.raises(RequestRejectedError) as ei:
+            await _complete(_transport_for(handler), _source())
+        assert ei.value.status_code == 400  # 分类不受 body 形态影响
+
+    async def test_non_stream_path_keeps_the_body(self):
+        def handler(request):
+            return httpx.Response(400, content=_REJECT_BODY.encode())
+
+        with pytest.raises(RequestRejectedError) as ei:
+            await _complete(_transport_for(handler), _source(), stream=False)
+        assert ei.value.body_text == _REJECT_BODY
+
+    async def test_embedding_path_keeps_the_body(self):
+        def handler(request):
+            return httpx.Response(400, content=_REJECT_BODY.encode())
+
+        with pytest.raises(RequestRejectedError) as ei:
+            await _transport_for(handler).embed(texts=["hi"], source=_source(), call_id="cid-embed")
+        assert ei.value.body_text == _REJECT_BODY
+
+
 class TestLifecycle:
    async def test_aclose_idempotent(self):
        def handler(request):
@@ -257,17 +257,41 @@ class TestSQLiteColumnBackfill:


 class _FakePgConn:
-    """记录执行过的语句;可让 ALTER 抛错以模拟权限不足。"""
+    """记录执行过的语句;可让 ALTER/CREATE/探测抛错以模拟权限不足与抖动。

-    def __init__(self, existing: list[str], *, fail_alter: bool = False):
+    `existing` 为空列表即表示**表不存在**(与真实 PG 一致: `to_regclass` 为 NULL
+    时列探测必然零行),故 `fetchval` 与 `fetch` 共用同一份事实。
+    """
+
+    def __init__(
+        self,
+        existing: list[str],
+        *,
+        fail_alter: bool = False,
+        fail_create: bool = False,
+        probe_errors: int = 0,
+    ):
        self.existing = existing
        self.fail_alter = fail_alter
+        self.fail_create = fail_create
+        self.probe_errors = probe_errors
        self.statements: list[str] = []

    async def execute(self, sql, *args):
        self.statements.append(sql)
        if sql.startswith("ALTER TABLE") and self.fail_alter:
            raise RuntimeError("must be owner of table llm_calls")
+        if sql.lstrip().startswith("CREATE TABLE"):
+            if self.fail_create:
+                raise RuntimeError("permission denied for schema public")
+            self.existing = list(_EXPECTED_COLUMNS)
+
+    async def fetchval(self, sql, *args):
+        self.statements.append(sql)
+        if self.probe_errors > 0:
+            self.probe_errors -= 1
+            raise RuntimeError("connection was closed in the middle of operation")
+        return "llm_calls" if self.existing else None

    async def fetch(self, sql, *args):
        self.statements.append(sql)
@@ -338,6 +362,76 @@ class TestPostgresBackfillDiscipline:
        assert all("IF NOT EXISTS" not in s for s in altered)  # 探测已确认缺列,无需再判


+class TestPostgresTableProbe:
+    """建表必须先探测,且"判死"只认"确定写不进去"(issue #9)。
+
+    实测(PostgreSQL 16.14,只有表级 SELECT/INSERT 的角色): `CREATE TABLE IF NOT
+    EXISTS` 被拒 permission denied for schema,而同一连接的 `INSERT` 通过——
+    PG 对 schema 的 CREATE 权限检查早于 `IF NOT EXISTS` 的存在性判断。无条件发
+    DDL 会让这类最小权限部署的整个进程静默失遥测。
+    """
+
+    _CURRENT = [
+        "call_id",
+        "cost",
+        "created_at",
+        "cached_prompt_tokens",
+        "model_reported",
+        "sampling",
+        "reasoning_tokens",
+    ]
+
+    def _recorder(self, conn):
+        from polygateway.telemetry.postgres import PostgresRecorder
+
+        return PostgresRecorder("postgresql://u:p@h:5432/polygateway", pool=_FakePgPool(conn))
+
+    def _created(self, conn):
+        return [s for s in conn.statements if s.lstrip().startswith("CREATE TABLE")]
+
+    async def test_existing_table_is_never_recreated(self):
+        """表已存在就一条 DDL 都不发——这是权限被拒的唯一根治办法。"""
+        conn = _FakePgConn(self._CURRENT)
+        await _record_minimal(self._recorder(conn))
+        assert not self._created(conn)
+
+    async def test_create_denied_on_existing_table_keeps_recording(self):
+        """就算 DDL 仍被发出并被拒,表存在时也不得判死整个 recorder。"""
+        conn = _FakePgConn(self._CURRENT, fail_create=True)
+        recorder = self._recorder(conn)
+        await _record_minimal(recorder)  # 不得抛
+        assert recorder._failed is False
+        assert any(s.startswith("INSERT INTO llm_calls") for s in conn.statements)
+
+    async def test_missing_table_is_created_and_not_backfilled(self):
+        """表不存在→建表;新建表列已齐全,不得再发补列 ALTER。"""
+        conn = _FakePgConn([])
+        recorder = self._recorder(conn)
+        await _record_minimal(recorder)
+        assert len(self._created(conn)) == 1
+        assert not [s for s in conn.statements if s.startswith("ALTER TABLE")]
+        assert recorder._failed is False
+        assert any(s.startswith("INSERT INTO llm_calls") for s in conn.statements)
+
+    async def test_create_failure_on_missing_table_degrades_to_noop(self):
+        """表确定不存在且建不出来 = 确定写不进去: 此时才允许永久 no-op。"""
+        conn = _FakePgConn([], fail_create=True)
+        recorder = self._recorder(conn)
+        await _record_minimal(recorder)  # 不得抛
+        assert recorder._failed is True
+        assert not [s for s in conn.statements if s.startswith("INSERT INTO llm_calls")]
+
+    async def test_probe_failure_is_transient_not_terminal(self):
+        """探测失败多为连接抖动: 跳过本次,下次调用必须重试,绝不永久判死。"""
+        conn = _FakePgConn(self._CURRENT, probe_errors=1)
+        recorder = self._recorder(conn)
+        await _record_minimal(recorder, call_id="first")  # 不得抛
+        assert recorder._failed is False
+        assert not [s for s in conn.statements if s.startswith("INSERT INTO llm_calls")]
+        await _record_minimal(recorder, call_id="second")
+        assert [s for s in conn.statements if s.startswith("INSERT INTO llm_calls")]
+
+
 class _MemoryRecorder:
    def __init__(self):
        self.rows = []
Author	SHA1	Message	Date
iomgaa	17dcff41c3	Merge branch 'feat/issue-10-error-body-retention'	2026-08-16 23:34:20 -04:00
iomgaa	fa4a7e220b	test: make the 429 red line actually catch its violation Verifier mutation test: flipping _translate_429 to parse the summary left all 824 tests green. The padding was one long string value, so the cut landed inside it - and head-and-tail retention kept the trailing error object, leaving the summary parseable. Many keys put the cut between structural tokens, where the summary stops being valid JSON. Mutation now fails as it should. Also splits OCR 429 out on its own.	2026-08-16 06:50:50 -04:00
iomgaa	658086e2c0	docs: release 1.2.0 and unpin downstream from the 1.1 series Issue #10 Task 6. The install pin moves from ==1.1.* to >=1.2,<2 - left alone, everyone following the README would have stayed silently on 1.1.2 without this fix and without a warning. Telemetry field count re-measured via inspect.signature: still 22.	2026-08-16 06:22:13 -04:00
iomgaa	9dada0be9d	test: prove a rejected call's reason reaches the telemetry table Issue #10 Task 5, the acceptance claim. Before the fix this asserted against 'qwen_1 请求被拒: 400' and failed on the first substring - which is exactly what the downstream batch was left with. Uses the real body from the issue, and checks the trailing code too, since a head-only cut would drop the one field you quote when chasing the provider.	2026-08-16 06:17:10 -04:00
iomgaa	a3f4cc323f	feat: keep the gateway's words on the OCR branches too Issue #10 Task 4: the OCR side said only 'HTTP 404'. The issue reported the chat path, but the batch that lost its 400 was reading tables - the same blind spot, one transport over. Reuses the shared summarizer.	2026-08-16 06:14:07 -04:00
iomgaa	0edb9d397a	feat: keep the gateway's words on every non-2xx chat branch Issue #10 Task 3: five branches each built their own message, so adding the summary would have meant five copies. Table-driven classification composes it in one place instead, and the 429 split still parses the untruncated body - reading the summary would demote an oversized insufficient_quota to a plain rate limit and stop force_open.	2026-08-16 06:07:29 -04:00
iomgaa	484900d300	feat: add the single summarizer for HTTP error bodies Issue #10 Task 2: head-and-tail rather than a head-only cut, because the code and request_id that let you chase the provider sit at the very end of a JSON error body. Cap 2048 follows k8s client-go for the same job.	2026-08-16 06:03:26 -04:00
iomgaa	e302247022	feat: let every gateway error carry what the gateway said Issue #10 Task 1: a rejected call's reason had nowhere to live. The field goes on the base class because these errors all come from one HTTP response - which class it is and what the peer said are orthogonal.	2026-08-16 06:01:38 -04:00
iomgaa	1489aab95d	docs: add the missing imports to the plan's key interfaces Codex review: the code blocks reference httpx and PolyGatewayError, but neither module imports them today. A zero-context implementer copying them verbatim would stall on F821.	2026-08-16 05:57:07 -04:00
iomgaa	c2dd4a1cf4	docs: plan the implementation for issue #10	2026-08-16 05:50:37 -04:00
iomgaa	1801289277	docs: mark the issue #10 design approved	2026-08-16 05:34:46 -04:00
iomgaa	7462cad166	docs: widen the body cap to 2048 and keep the tail The 500-char head-only rule came from a single sample. k8s client-go caps the same thing at 2048; reprlib keeps head and tail because the text is meant to be read. Gateway error bodies are JSON whose code and request_id sit at the very end, so a head-only cut drops exactly what you need to chase the provider. Version pinned at 1.2.0, which forces the README install pin off ==1.1.*.	2026-08-16 05:24:30 -04:00
iomgaa	3cbe8aab91	docs: register the issue #10 design in the research wiki	2026-08-16 05:12:14 -04:00
iomgaa	707f8f7317	docs: pin the truncation rule to arithmetic after Codex review "Truncate at cap and append the ellipsis" admits both 501 and 500 total length; the two would desync test assertions from the telemetry length promise. Cap is now the total including the marker.	2026-08-16 05:09:06 -04:00
iomgaa	10fbc5441e	docs: design how the gateway's refusal survives the transport layer Issue #10: the 400 body dies in _status_to_error, and telemetry only writes str(exc), so adding a field alone would not make the refusal queryable after the fact. Design keeps the summary in both the message and a new base-class body_text, across every non-2xx branch and both transports.	2026-08-16 05:03:33 -04:00
iomgaa	114fc8b1b3	Merge branch 'chore/packaging-metadata'	2026-08-07 21:48:15 -04:00
iomgaa	4f1ab21562	chore: give the package page a body and repo links 1.1.2 went out with an empty description on the registry page: without a readme field there is no long_description, and twine only warns about that -- it does not block the upload. Add readme and project.urls, and record the wider lesson in the release procedure: a release is done when the pages a downstream user actually opens look right, not when the local steps go green. Also adds the missing step for creating a Release, which is why the Releases page sat empty through eight tags.	2026-08-07 21:48:15 -04:00
iomgaa	2be89c47d8	Merge branch 'fix/issue-9-telemetry-ddl-probe'	2026-08-07 11:23:38 -04:00
iomgaa	7c60199680	chore: release 1.1.2 README first, per the release procedure: the 1.1.* pin still covers this version, the 22-field count re-checked with inspect.signature, and the telemetry row now states that an existing table needs no schema CREATE privilege.	2026-08-07 11:23:29 -04:00
iomgaa	2e028d38f2	fix: probe for the telemetry table before creating it PostgreSQL checks the schema CREATE privilege before the IF NOT EXISTS existence test, so an account with only table-level INSERT was denied on CREATE TABLE IF NOT EXISTS even though the table was right there and writable. The denial set _failed and the whole recorder went no-op for the process lifetime, silently: 150+ calls downstream lost their latency, token and cost rows with nothing but one warning to show for it. The probe is the direct fix. The larger fix is the criterion: structural degradation now means "provably cannot write" (pool creation failed, or the table is absent and cannot be created), not "something threw during init" -- a probe or acquire failure just skips the row and retries on the next call. SQLite stays as it is on purpose. Measured: it short-circuits the statement at parse time, so it passes even under another connection's EXCLUSIVE lock or on a read-only file. A probe there would buy nothing; the docstring now says so to keep symmetry-minded future edits away.	2026-08-07 11:21:33 -04:00
iomgaa	c2e9f5396c	docs: write down the release procedure that keeps getting skipped Bumping the version is not releasing. 1.0.6 and 1.1.0 both got a version bump and a changelog entry but were never uploaded, so the registry sat at 1.0.5 and downstream could not install any of those fixes. The ordering matters in one non-obvious way: README has to be correct before the build, because sdist freezes whatever is there at that moment. That is exactly how 1.1.1 shipped with a stale README. The install pin is called out by name since it is the easiest line to forget and the most damaging to leave wrong. Also records where the Gitea token actually lives — tea's config, not .pypirc — after that misreading led to a wrong "no credentials" claim.	2026-08-06 12:44:06 -04:00
iomgaa	d2cb8770df	docs: correct the telemetry field count and document backpressure Three README drifts, none of them about issue #8 alone: - the telemetry row said 18 fields; record_llm_call takes 22 (verified by inspect.signature). ports.py claimed 20 in its own docstring, so both records of the same fact were stale. - LLMResponse.cost is hardcoded to None on the chat path (retry.py:519). Cost only ever reaches telemetry. The old doc site named this as a known trap, so the capability row now says it outright. - backpressure had no row at all, which is what issue #8 was about.	2026-08-06 12:33:45 -04:00
iomgaa	80bc94c42d	docs: point the install pin at 1.1.x The pin still said ==1.0.*, which caps downstream at 1.0.5 and hides every fix since. Now that 1.1.1 is actually in the registry the pin can move; it was missed when 1.1.0 was tagged.	2026-08-06 12:24:44 -04:00
iomgaa	bb69ecf0da	Merge branch 'feat/issue-8-stall-budget' stall 判定改为非生产性等待口径(issue #8)并发布 1.1.1。	2026-08-06 12:12:42 -04:00