文档组织与维护约定(Gitea Wiki)

定位: 用户文档站 = Gitea Wiki(https://gitea.iomgaa.online/iomgaa/PolyGateway/wiki);本文规定它的结构、更新时机与写作纪律。研发知识(设计/决策/验收)仍归 research-wiki/,两者职责不重叠。

1. 结构:Diátaxis 四区(2026-07-23 建站,17 页)

区	页面	职责(读者此刻要干什么)	禁止
教程	`教程-十分钟接入`	新手被领着走通一遍	塞选项枚举与原理论述
指南(How-to)	`指南-{多源与选源,限流与熔断,响应缓存,遥测与成本,结构化输出,OCR,Embedding,迁移既有项目}`	一页一任务:配置片段+行为+坑	重复参考区的全量表
参考	`参考-{公共API,配置键,异常}`	查表:签名/字段/键,以源码实测为准	叙述与劝导
解释	`解释-{架构,错误四分类,治理行为,降级与取消}`	讲为什么;机制挂回压测病灶	写成使用说明

导航:Home.md(按意图分流表)+ _Sidebar.md(全页目录);页间互链用 Gitea [[双括号]] 语法。

变更类型	必须同步的页
新公共 API / 新能力	对应指南页(新增或扩写)+ `参考-公共API` + 侧边栏 + CHANGELOG
新增/改名配置键	`参考-配置键` + 相关指南页的配置片段 + 主仓库 `.env.example`
治理行为变更(重试/熔断/选源语义)	`解释-治理行为` + 受影响指南页;若改公共承诺另走 brainstorming 流程
新异常/分类语义调整	`参考-异常` + `解释-错误四分类`
发版(任何版本号)	`Home.md` 版本号与安装命令 + 主仓库 `CHANGELOG.md` + `README.md` 版本相关处;过一遍上面各行

门: 版本 bump 的提交不允许单独存在——同一次交付里必须包含对应的 wiki/CHANGELOG 同步(发布检查清单第一项)。

中文;表格优先;单个代码块 ≤ 15 行;每个配置片段可直接复制运行。
事实以源码为准:参考区改动前先对照 __init__.py 导出面、client.py/ocr.py/embedding.py 签名与 .env.example;不确定就实测,不凭记忆写。
深度内容(决策论证、迁移全文、验收数字)只放指针指向主仓库 research-wiki/,不复制——避免双处维护同一事实。
API 参考坚持手写精选(公共面小 + 只增不删承诺,手写比自动生成可读且低维护);若公共面显著膨胀再评估 mkdocstrings。

Wiki 是独立 git 仓库,两种改法:

git clone https://gitea.iomgaa.online/iomgaa/PolyGateway.wiki.git   # 批量改: clone→编辑→push
# 或在 Gitea 网页 Wiki 页面上直接编辑(单页小改)

文件名即页名(中文文件名);Home.md 是落地页,_Sidebar.md 是导航,新增页必须同步进侧边栏与 Home 分流表。凭据在本机 osxkeychain(git)与 ~/.pypirc(twine)。