参考

这一节是由代码生成的全表。它的存在意义是让「文档和代码不一致」在 CI 里失败，而不是等读者踩到。

生成机制

bash

go run ./tools/docsgen

生成器读代码，写出 docs/reference/*.md。每个生成文件顶部都有标记：

html

<!-- GENERATED BY tools/docsgen — DO NOT EDIT BY HAND -->
<!-- source: internal/config/config.go -->

不要手工编辑生成文件 —— CI 会跑一遍生成器，然后 git diff --exit-code；代码改了而文档没重新生成，构建就红。

页面	内容	生成源
环境变量全表	启动时读取的每一个环境变量、类型、默认值	`internal/config/config.go`
运行设置全表	控制台可热改的设置项	`internal/runtimeconfig/runtimeconfig.go`
管理 API 全表	`/admin` 下的全部端点，按资源分组	`internal/httpapi` 的路由注册
公开接口全表	`/v1` 下的全部已登记端点	`internal/httpapi/relay*.go`
错误码与分类	原始分类、面向操作员的错误类，以及两者的差集	后端分类字面量 + `web/src/errorCatalog.ts`
数据表与迁移	实际迁移出来的表、列、索引	迁移一个临时库后读回 schema
连接类型全表	控制台可选类型、后端认可的兼容品牌	`adapters.OpenAICompatibleBrands()` + `web/src/connectionTypes.ts`
供应商 profile	非 OpenAI 供应商的端点与字段映射	`proxy.Profiles()` 注册表

文档腐烂的根因是「代码变了，没人想起来改文档」。上面每张表都有一个机器可读的唯一真相源，所以：

新增一个环境变量、一个端点、一个错误分类，只要没重新生成，CI 就失败；
表里的值不可能是手抄错的，因为它没被手抄过；
两张表之间的差集本身就是要暴露的缺陷。例如生成器第一次运行时就发现转发层产出的 4 个错误分类在控制台分类表里没有对应项——那会让操作员只看到通用兜底文案。

这套思路与仓库里既有的两道同类闸门一致：i18n 的 parity.test.ts 强制中英键一一对应，channel_projection_test.go 钉死三处投影的列一致。

生成器只覆盖有唯一真相源的事实。下面这些仍然要手写，也更容易腐烂，写它们时务必回代码核对：