From 30d7ffd94ac6864c16faae61aab450298d0fe77c Mon Sep 17 00:00:00 2001 From: iomgaa Date: Fri, 31 Jul 2026 07:11:52 -0400 Subject: [PATCH] docs: register the implementation plan in the research wiki --- research-wiki/graph/edges.json | 12 ++++++++ research-wiki/index.md | 6 ++-- research-wiki/log.md | 4 +++ .../plans/response-observability-fields.md | 30 +++++++++++++++++++ 4 files changed, 50 insertions(+), 2 deletions(-) create mode 100644 research-wiki/plans/response-observability-fields.md diff --git a/research-wiki/graph/edges.json b/research-wiki/graph/edges.json index 4763fce..d044ef8 100644 --- a/research-wiki/graph/edges.json +++ b/research-wiki/graph/edges.json @@ -115,6 +115,11 @@ "id": "design:response-observability-fields", "label": "响应可观测字段扩展(Issue #3)", "type": "design" + }, + { + "id": "plan:response-observability-fields", + "label": "响应可观测字段扩展实现计划", + "type": "plan" } ], "links": [ @@ -194,6 +199,13 @@ "relation": "implements", "evidence": "5 任务实现设计 §3.2 的 11 条改动项;任务排序经中间态破窗分析(先加能力→切调用点→三态生效→解绑约束)", "added": "2026-07-30T09:39:26.442986+00:00" + }, + { + "source": "plan:response-observability-fields", + "target": "design:response-observability-fields", + "relation": "implements", + "evidence": "计划 T1-T7 逐条实现设计的 A2/B1/C1/D1 四个决策", + "added": "2026-07-31T11:10:03.872049+00:00" } ] } \ No newline at end of file diff --git a/research-wiki/index.md b/research-wiki/index.md index d250a69..5be9bbf 100644 --- a/research-wiki/index.md +++ b/research-wiki/index.md @@ -1,6 +1,6 @@ # Research Wiki 索引 -> 自动生成，更新时间：2026-07-31 08:37 UTC +> 自动生成，更新时间：2026-07-31 11:11 UTC ## design (18) - [2026-07-20-m1-core-design](designs/2026-07-20-m1-core-design.md) `design:2026-07-20-m1-core-design` @@ -35,19 +35,21 @@ - [P6 混合浸泡首跑基线与记分板三重伪击穿修复](findings/p6-soak-baseline.md) `finding:p6-soak-baseline` - [P7 OCR soak 验收: 99.73% 与 13 不变量全 PASS](findings/p7-ocr-soak.md) `finding:p7-ocr-soak` -## plan (12) +## plan (14) - [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` - [2026-07-21-m3-ocr-plan](plans/2026-07-21-m3-ocr-plan.md) `plan:2026-07-21-m3-ocr-plan` - [2026-07-22-m4-migration-plan](plans/2026-07-22-m4-migration-plan.md) `plan:2026-07-22-m4-migration-plan` - [2026-07-30-est-tokens-decoupling-plan](plans/2026-07-30-est-tokens-decoupling-plan.md) `plan:2026-07-30-est-tokens-decoupling-plan` +- [2026-07-31-response-observability-fields](plans/2026-07-31-response-observability-fields.md) `plan:2026-07-31-response-observability-fields` - [est_tokens 解耦实施计划](plans/est-tokens-decoupling.md) `plan:est-tokens-decoupling` - [M1 核心里程碑实现计划](plans/m1-core-plan.md) `plan:m1-core-plan` - [M2 分布式实现计划](plans/m2-distributed.md) `plan:m2-distributed` - [M2.5 治理韧性实现计划](plans/m25-resilience.md) `plan:m25-resilience` - [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` ## schema (1) - [表结构: llm_calls(遥测 18 字段)](schemas/llm-calls.md) `schema:llm-calls` diff --git a/research-wiki/log.md b/research-wiki/log.md index 38a49a4..21209e7 100644 --- a/research-wiki/log.md +++ b/research-wiki/log.md @@ -59,3 +59,7 @@ - [2026-07-30 09:39 UTC] 重建索引: 42 篇页面 - [2026-07-31 08:35 UTC] 新增 design: 响应可观测字段扩展(Issue #3) (design:response-observability-fields) - [2026-07-31 08:37 UTC] 重建索引: 44 篇页面 +- [2026-07-31 11:10 UTC] 新增 plan: 响应可观测字段扩展实现计划 (plan:response-observability-fields) +- [2026-07-31 11:10 UTC] 新增边: plan:response-observability-fields --implements--> design:response-observability-fields +- [2026-07-31 11:10 UTC] 重建索引: 46 篇页面 +- [2026-07-31 11:11 UTC] 重建索引: 46 篇页面 diff --git a/research-wiki/plans/response-observability-fields.md b/research-wiki/plans/response-observability-fields.md new file mode 100644 index 0000000..f1ec576 --- /dev/null +++ b/research-wiki/plans/response-observability-fields.md @@ -0,0 +1,30 @@ +--- +type: plan +node_id: plan:response-observability-fields +title: 响应可观测字段扩展实现计划 +date: 2026-07-31 +--- + +# 响应可观测字段扩展实现计划 + +全文见 `2026-07-31-response-observability-fields.md`。实现 [[response-observability-fields]] 设计(A2/B1/C1/D1)。 + +## 任务序列 + +| 任务 | 内容 | 提交 | +|---|---|---| +| T1 | `types.py` 两个类型各 +2 字段;`cache_hit` docstring 消歧 | 独立 | +| T2 | `openai_compat.py` 防御解析 + SSE sink 采集 `model` + 两处构造填值 | 独立 | +| T3 | `retry.py` 搬运;`cache.py` 零改动但用测试固化 B1 回放语义 | 独立 | +| T4 | `pricing.py` 可选缓存单价档 + 夹取防负 | 独立 | +| T5+T6 | 端口 18→20、两后端 DDL 加列与幂等补列、emitter 搬运、契约测试 | **必须合一次提交** | +| T7 | ARCHITECTURE §7.8 / CHANGELOG / `.env.example:56` / 6 处「18 字段」措辞 / 版本 1.1.0 / Gitea Wiki 站 | 独立 | + +## 独立审查抓出的四个坑(已折回计划) + +1. **DDL 新列必须放在 `created_at` 之后**(表末尾)。旧表走 `ALTER ADD COLUMN` 只能追加到末尾,若新建库把新列插在 `created_at` 前,两条路径列序分叉 —— 而 `test_schema_has_frozen_columns_in_order` 按 `ordinal_position` 逐位断言,且该 PG 表与真实批跑共享、严禁 DROP,分叉后无合规修法。 +2. **SQLite 补列块首行必须守卫 `if self._conn is None: return`**。否则初始化失败时补列块抛 `AttributeError`/`NameError`(不被 `sqlite3.Error` 捕获)逃出 `__init__`,打破「初始化失败静默降级」契约。 +3. **T5 与 T6 不得分开提交**。中间状态下 emitter 只传 18 键,后端抛 `KeyError` 被吞成 warning，该 commit 全量遥测静默丢失。 +4. **天然拦截点是四处而非三处**:两个 `_record_minimal` + 两个 `_EXPECTED_COLUMNS`;`test_ports.py:96` 的全签名 fake **不会**红(Protocol 的 isinstance 不校验签名),不能当作覆盖保证。 + +相关: [[response-observability-fields]]、[[est-tokens-decoupling]]