iomgaa
e9607b2f0c
CHANGELOG gets all five breaking changes, not the one the draft had: ThinkingCapability's constructor, two ports that grew a parameter with no default, resolve_thinking's new return type, and ProviderProfile's single wire field. Behaviour changes get their own section, including the one that is easy to miss — the openai fallback segment no longer refuses an unknown shape, so a downstream that parks a foreign model there and asks for thinking used to fail at assembly and now sends nothing at all. minimax is called out as the exception it is: the gateway proved M3 does not think without a parameter, so that segment keeps its medium and its downstreams see no change this release. The capability table is reported as it stands — 17 of 24 rows measured, 7 still on documentation, with the reason each one went unmeasured, so nobody reads "measured" into a row that is a guess. The auto limitation and its deliberate MiniMax-M3 inconsistency are written down rather than left for someone to trip over; issue #21 holds the real fix. ARCHITECTURE had five claims that measurement showed had gone false: the cache key formula, the field count, the reconcile predicate and its throttle key, and two field lists. README's FIELD set was missing the two new keys it calls exhaustive. docs-convention still opened by announcing a 17-page site that has not existed since August. It now says what is actually there — one placeholder page pointing at .env.example, CHANGELOG and the source docstrings — and says which four files carry the sync gate while the site is down.
52 lines
4.3 KiB
Markdown
52 lines
4.3 KiB
Markdown
# 文档组织与维护约定(Gitea Wiki)
|
|
|
|
> **定位**: 用户文档站 = Gitea Wiki(`https://gitea.iomgaa.online/iomgaa/PolyGateway/wiki`);本文规定它的结构、更新时机与写作纪律。研发知识(设计/决策/验收)仍归 `research-wiki/`,两者职责不重叠。
|
|
|
|
> [!CRITICAL]
|
|
> **现状(2026-08-02 起):文档站已全量下线,当前只剩 `Home` 一页占位。** 八轮审查累计确认 93 处与源码不一致,近半落在参考区(手工镜像源码里已有的事实,必然漂移),且修正本身在引入次生偏差,逐轮修补不收敛——过期文档比没有文档更危险,它看起来权威。
|
|
> Home 页现在做的唯一一件事是**把下游指向真实事实源**:签名/字段/参数语义 → 源码 docstring;全量环境变量键 → `.env.example`;版本变更与下游注意事项 → `CHANGELOG.md`;架构决策与行为论证 → `research-wiki/ARCHITECTURE.md`;快速上手 → `README.md`。
|
|
> 历史内容未丢失,全在 wiki 仓库的 git 历史里(`git checkout e78bfb9 -- .`)。**本文以下各节描述的是重建时的目标结构与纪律,不是当前站点的现状**;在文档站重建之前,下面凡指向具体 wiki 页面的条目一律**不可执行**。
|
|
|
|
## 1. 结构:Diátaxis 四区(重建目标;2026-07-23 建站 17 页,2026-08-02 全量下线)
|
|
|
|
| 区 | 页面 | 职责(读者此刻要干什么) | 禁止 |
|
|
|---|---|---|---|
|
|
| 教程 | `教程-十分钟接入` | 新手被领着走通一遍 | 塞选项枚举与原理论述 |
|
|
| 指南(How-to) | `指南-{多源与选源,限流与熔断,响应缓存,遥测与成本,结构化输出,OCR,Embedding,迁移既有项目}` | 一页一任务:配置片段+行为+坑 | 重复参考区的全量表 |
|
|
| 参考 | `参考-{公共API,配置键,异常}` | 查表:签名/字段/键,**以源码实测为准** | 叙述与劝导 |
|
|
| 解释 | `解释-{架构,错误四分类,治理行为,降级与取消}` | 讲为什么;机制挂回压测病灶 | 写成使用说明 |
|
|
|
|
导航:`Home.md`(按意图分流表)+ `_Sidebar.md`(全页目录);页间互链用 Gitea `[[双括号]]` 语法。
|
|
|
|
## 2. 更新时机(与代码变更绑定,发版检查清单)
|
|
|
|
| 变更类型 | 必须同步的页 |
|
|
|---|---|
|
|
| 新公共 API / 新能力 | 对应指南页(新增或扩写)+ `参考-公共API` + 侧边栏 + CHANGELOG |
|
|
| 新增/改名配置键 | `参考-配置键` + 相关指南页的配置片段 + 主仓库 `.env.example` |
|
|
| 治理行为变更(重试/熔断/选源语义) | `解释-治理行为` + 受影响指南页;若改公共承诺另走 brainstorming 流程 |
|
|
| 新异常/分类语义调整 | `参考-异常` + `解释-错误四分类` |
|
|
| **发版(任何版本号)** | `Home.md` 版本号与安装命令 + 主仓库 `CHANGELOG.md` + `README.md` 版本相关处;过一遍上面各行 |
|
|
|
|
**门**: 版本 bump 的提交不允许单独存在——同一次交付里必须包含对应的 wiki/CHANGELOG 同步(发布检查清单第一项)。
|
|
|
|
**站点下线期间(2026-08-02 至文档站重建)本表如何执行**: 上表左列的判据照旧,右列中指向具体 wiki 页面的项**全部落空,不必也无法执行**;仍然必须做的是 `CHANGELOG.md`、`README.md`、`.env.example` 与 `research-wiki/ARCHITECTURE.md` 四处。这道门因此**没有放松**——只是承接方从 wiki 换成了这四个文件,漏改它们与从前漏改 wiki 是同一性质的失败。
|
|
|
|
## 3. 写作纪律
|
|
|
|
- 中文;表格优先;单个代码块 ≤ 15 行;每个配置片段可直接复制运行。
|
|
- **事实以源码为准**:参考区改动前先对照 `__init__.py` 导出面、`client.py`/`ocr.py`/`embedding.py` 签名与 `.env.example`;不确定就实测,不凭记忆写。
|
|
- 深度内容(决策论证、迁移全文、验收数字)**只放指针**指向主仓库 `research-wiki/`,不复制——避免双处维护同一事实。
|
|
- API 参考坚持**手写精选**(公共面小 + 只增不删承诺,手写比自动生成可读且低维护);若公共面显著膨胀再评估 mkdocstrings。
|
|
|
|
## 4. 更新操作
|
|
|
|
Wiki 是独立 git 仓库,两种改法:
|
|
|
|
```bash
|
|
git clone https://gitea.iomgaa.online/iomgaa/PolyGateway.wiki.git # 批量改: clone→编辑→push
|
|
# 或在 Gitea 网页 Wiki 页面上直接编辑(单页小改)
|
|
```
|
|
|
|
文件名即页名(中文文件名);`Home.md` 是落地页,`_Sidebar.md` 是导航,新增页必须同步进侧边栏与 Home 分流表。凭据在本机 osxkeychain(git)与 `~/.pypirc`(twine)。
|