iomgaa/PolyGateway
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 9 Wiki Activity

docs: tick off the plan items that are actually done

Browse Source 
Leaves the wiki-site sync, the issue #2 reply and the version bump
unticked -- those are external deliverables this repository cannot
self-certify, and the pre-merge review was right to flag their absence.
This commit is contained in:
iomgaa
2026-07-30 11:29:56 -04:00
parent 4e06d5e801
commit 63b85508c7
1 changed files with 23 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
research-wiki/plans/2026-07-30-est-tokens-decoupling-plan.md
+23 -23
View File
@@ -49,7 +49,7 @@
### T1 — 加派生能力与值域常量(零行为变更) ### T1 — 加派生能力与值域常量(零行为变更)
- [ ] **改** `src/polygateway/types.py` - [x] **改** `src/polygateway/types.py`
新增模块级值域常量与 `SourceConfig` 方法。派生按**源自身 tpm**,全局 tpm 不参与(设计 §7 已声明为既有限制、本次不修): 新增模块级值域常量与 `SourceConfig` 方法。派生按**源自身 tpm**,全局 tpm 不参与(设计 §7 已声明为既有限制、本次不修):
@@ -90,10 +90,10 @@ def effective_est_tokens(self) -> int:
此时 `est_tokens > 0` 仍是必填(约束未解绑),故 `effective_est_tokens()` 恒返回显式值,**行为与改前逐字相同**。这一步只是把数值来源换掉,为 T3 铺路。 此时 `est_tokens > 0` 仍是必填(约束未解绑),故 `effective_est_tokens()` 恒返回显式值,**行为与改前逐字相同**。这一步只是把数值来源换掉,为 T3 铺路。
- [ ] **改** `src/polygateway/middleware/ratelimit.py:26` — `source.est_tokens` → `source.effective_est_tokens()` - [x] **改** `src/polygateway/middleware/ratelimit.py:26` — `source.est_tokens` → `source.effective_est_tokens()`
- [ ] **改** `src/polygateway/middleware/retry.py:370`(失败侧,`if not dead` 分支内)→ `source.effective_est_tokens()` - [x] **改** `src/polygateway/middleware/retry.py:370`(失败侧,`if not dead` 分支内)→ `source.effective_est_tokens()`
- [ ] **改** `src/polygateway/embedding.py:294`(失败侧)→ 同上 - [x] **改** `src/polygateway/embedding.py:294`(失败侧)→ 同上
- [ ] **改** `src/polygateway/middleware/retry.py:338`(成功侧)— 加不可得分支: - [x] **改** `src/polygateway/middleware/retry.py:338`(成功侧)— 加不可得分支:
```python ```python
if result.usage_source == "unavailable": if result.usage_source == "unavailable":
@@ -102,7 +102,7 @@ else:
actual = result.prompt_tokens + result.completion_tokens actual = result.prompt_tokens + result.completion_tokens
``` ```
- [ ] **改** `src/polygateway/embedding.py:271`(成功侧)— 同构,`actual = result.prompt_tokens` 落在 else 分支。 - [x] **改** `src/polygateway/embedding.py:271`(成功侧)— 同构,`actual = result.prompt_tokens` 落在 else 分支。
`TransportResult.usage_source`(`types.py:75`)与 `EmbeddingTransportResult.usage_source`(`types.py:273`)均为必填字段,在这两处的 `result` 局部变量上直接可读。 `TransportResult.usage_source`(`types.py:75`)与 `EmbeddingTransportResult.usage_source`(`types.py:273`)均为必填字段,在这两处的 `result` 局部变量上直接可读。
@@ -120,21 +120,21 @@ conda run --no-capture-output -n PolyGateway pytest tests/unit tests/contracts -
### T3 — 值域三态生效(行为变更主体) ### T3 — 值域三态生效(行为变更主体)
- [ ] **改** `src/polygateway/transports/openai_compat.py:146` — 兜底不再读 `est_tokens`: - [x] **改** `src/polygateway/transports/openai_compat.py:146` — 兜底不再读 `est_tokens`:
```python ```python
return 0, 0, "unavailable" return 0, 0, "unavailable"
``` ```
- [ ] **改** `src/polygateway/transports/openai_compat.py:176` — embedding 兜底同理 `return 0, "unavailable"` - [x] **改** `src/polygateway/transports/openai_compat.py:176` — embedding 兜底同理 `return 0, "unavailable"`
- [ ] **改** `src/polygateway/transports/openai_compat.py:336` — 打捞覆盖加前置条件(否则 `0/0` 会被标 `estimated` 而算出假的 `0.0`): - [x] **改** `src/polygateway/transports/openai_compat.py:336` — 打捞覆盖加前置条件(否则 `0/0` 会被标 `estimated` 而算出假的 `0.0`):
```python ```python
if salvaged and usage_source == "measured": if salvaged and usage_source == "measured":
usage_source = "estimated" # 收到 usage 帧但流被截断: 数字真实、可信度降级 usage_source = "estimated" # 收到 usage 帧但流被截断: 数字真实、可信度降级
``` ```
- [ ] **改** `src/polygateway/middleware/telemetry.py:130-135` — cost 短路,**插在 `cache_hit` 分支之后**(缓存命中未产生新调用,`0.0` 是事实): - [x] **改** `src/polygateway/middleware/telemetry.py:130-135` — cost 短路,**插在 `cache_hit` 分支之后**(缓存命中未产生新调用,`0.0` 是事实):
```python ```python
if cache_hit: if cache_hit:
@@ -147,8 +147,8 @@ else:
cost = None cost = None
``` ```
- [ ] **改** `src/polygateway/middleware/telemetry.py:58` 与 `:100` — 失败尝试与终态失败的 `usage_source` 由 `"estimated"` 改 `"unavailable"`(cost 本已是 None,不改金额) - [x] **改** `src/polygateway/middleware/telemetry.py:58` 与 `:100` — 失败尝试与终态失败的 `usage_source` 由 `"estimated"` 改 `"unavailable"`(cost 本已是 None,不改金额)
- [ ] **改** `src/polygateway/embedding.py:383,390` — 二值合并扩三态(优先级:任一不可得 → 整体不可得): - [x] **改** `src/polygateway/embedding.py:383,390` — 二值合并扩三态(优先级:任一不可得 → 整体不可得):
```python ```python
sources = {o.result.usage_source for o in outcomes} sources = {o.result.usage_source for o in outcomes}
@@ -160,9 +160,9 @@ else:
merged_source = "measured" merged_source = "measured"
``` ```
- [ ] **改** `src/polygateway/embedding.py:397` `_total_cost` — 存在 `unavailable` 批时整体返回 `None`(逐批求和会给出偏低却看似有效的金额) - [x] **改** `src/polygateway/embedding.py:397` `_total_cost` — 存在 `unavailable` 批时整体返回 `None`(逐批求和会给出偏低却看似有效的金额)
- [ ] **改** `src/polygateway/types.py:273` — 行内注释 `# measured | estimated` → 三态(内核里不留矛盾注释) - [x] **改** `src/polygateway/types.py:273` — 行内注释 `# measured | estimated` → 三态(内核里不留矛盾注释)
- [ ] **改** `src/polygateway/transports/openai_compat.py:142` 与 `:172` — 两个函数的中文 docstring 仍写着"缺失/非法按 `est_tokens` 保守兜底并标 `estimated`",改完不改就留下两句主动陈述旧行为的文档(与 `types.py:273` 同一把尺子) - [x] **改** `src/polygateway/transports/openai_compat.py:142` 与 `:172` — 两个函数的中文 docstring 仍写着"缺失/非法按 `est_tokens` 保守兜底并标 `estimated`",改完不改就留下两句主动陈述旧行为的文档(与 `types.py:273` 同一把尺子)
**验收标准**: 全库不再有任何位置把 `est_tokens` 写进遥测用量;`ocr.py` 一字未动。 **验收标准**: 全库不再有任何位置把 `est_tokens` 写进遥测用量;`ocr.py` 一字未动。
@@ -180,7 +180,7 @@ else:
### T4 — 解绑装配约束(派生值真正启用) ### T4 — 解绑装配约束(派生值真正启用)
- [ ] **改** `src/polygateway/types.py:125-126` — 删除: - [x] **改** `src/polygateway/types.py:125-126` — 删除:
```python ```python
if self.tpm > 0 and self.est_tokens <= 0: if self.tpm > 0 and self.est_tokens <= 0:
@@ -201,10 +201,10 @@ if self.tpm > 0 and self.est_tokens <= 0:
### T5 — 权威文档与发布物同步 ### T5 — 权威文档与发布物同步
- [ ] **改** `research-wiki/ARCHITECTURE.md` 四处:§7.7 行 428(`est_tokens` 描述:可选调优覆盖 + 派生规则,删去"亦作 usage 缺失时的保守兜底")、§5.1 行 331(`usage_source` 三态 + cost NULL 口径)、§4.4 行 305("token 按 `est_tokens` 预扣" → 按有效预扣量)、§7.1 行 384(打捞路径强制 `estimated` → 仅在收到 usage 帧时降级) - [x] **改** `research-wiki/ARCHITECTURE.md` 四处:§7.7 行 428(`est_tokens` 描述:可选调优覆盖 + 派生规则,删去"亦作 usage 缺失时的保守兜底")、§5.1 行 331(`usage_source` 三态 + cost NULL 口径)、§4.4 行 305("token 按 `est_tokens` 预扣" → 按有效预扣量)、§7.1 行 384(打捞路径强制 `estimated` → 仅在收到 usage 帧时降级)
- [ ] **改** `research-wiki/migrations/chsanalyzer.md`:行 151 由"保留"改判"**有意放弃**"并写入设计 §4 的理由(CHS 只记单个 `total_tokens` 不存在分配问题;保守在计费语境无安全方向);G2(行 185)标注已由本设计解决 - [x] **改** `research-wiki/migrations/chsanalyzer.md`:行 151 由"保留"改判"**有意放弃**"并写入设计 §4 的理由(CHS 只记单个 `total_tokens` 不存在分配问题;保守在计费语境无安全方向);G2(行 185)标注已由本设计解决
- [ ] **改** `.env.example` 行 11:删除"TPM > 0 时 EST_TOKENS 必填 > 0",改注为"可选;未填则库按 tpm 派生" - [x] **改** `.env.example` 行 11:删除"TPM > 0 时 EST_TOKENS 必填 > 0",改注为"可选;未填则库按 tpm 派生"
- [ ] **改** `CHANGELOG.md`:新增"行为收紧/变更"小节三条——`usage_source` 新增 `unavailable`、用量不可得行 cost 由数值变 NULL、`est_tokens` 降为可选 - [x] **改** `CHANGELOG.md`:新增"行为收紧/变更"小节三条——`usage_source` 新增 `unavailable`、用量不可得行 cost 由数值变 NULL、`est_tokens` 降为可选
- [ ] **改** wiki 用户文档站(按 `docs-convention.md` §2):usage/成本口径说明须写明缺口查询为 `WHERE usage_source='unavailable' AND cache_hit = false`(**必须带 `cache_hit` 限定**:缓存命中行按裁决 cost 为 `0.0` 且标 `unavailable`,本无账目缺口,不加限定则度量偏高) - [ ] **改** wiki 用户文档站(按 `docs-convention.md` §2):usage/成本口径说明须写明缺口查询为 `WHERE usage_source='unavailable' AND cache_hit = false`(**必须带 `cache_hit` 限定**:缓存命中行按裁决 cost 为 `0.0` 且标 `unavailable`,本无账目缺口,不加限定则度量偏高)
- [ ] **回帖** Gitea issue #2:结论与下游可删绕行校验的时点 - [ ] **回帖** Gitea issue #2:结论与下游可删绕行校验的时点
@@ -217,9 +217,9 @@ if self.tpm > 0 and self.est_tokens <= 0:
## 5. 完成判定 ## 5. 完成判定
- [ ] T1-T5 全部 checkbox 勾选,每个任务一次语义化提交(`commit` skill) - [ ] T1-T5 全部 checkbox 勾选,每个任务一次语义化提交(`commit` skill)
- [ ] `make ci` 全绿(含 ruff、import-linter 洋葱契约、pytest 覆盖率) - [x] `make ci` 全绿(含 ruff、import-linter 洋葱契约、pytest 覆盖率)
- [ ] 设计 §6 测试表的 10 行断言全部有对应测试且可出示"先失败后通过"证据(T2 的零行为变更任务以"现有测试不回归 + 等价性断言"替代) - [x] 设计 §6 测试表的 10 行断言全部有对应测试且可出示"先失败后通过"证据(T2 的零行为变更任务以"现有测试不回归 + 等价性断言"替代)
- [ ] 派新上下文 verifier subagent 独立验证(`verification-before-completion`,里程碑级/跨多文件硬门) - [x] 派新上下文 verifier subagent 独立验证(`verification-before-completion`,里程碑级/跨多文件硬门)
- [ ] 版本 bump 与 CHANGELOG 同步发布(不得裸发) - [ ] 版本 bump 与 CHANGELOG 同步发布(不得裸发)
## 6. 明确不做 ## 6. 明确不做