From bd95a05c3032a631b27420efdc033dc5dc5a1c42 Mon Sep 17 00:00:00 2001 From: iomgaa Date: Wed, 26 Aug 2026 00:57:22 -0400 Subject: [PATCH] docs: retract a plan item that was wrong and would have broken deploys MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README's production template does not hand-write its columns; it derives them with LIKE from the seed table, and the prose right above it says so. Telling an executor to add a column there would have made Postgres reject a duplicate, turned TestProductionTemplate red, and broken deployment for anyone following it. The claim came from another task's report and went into the plan without opening the README. A finding relayed across tasks is a lead to verify, not a fact. What replaces it is a shape assertion — the template must derive via LIKE and must not inline any column name — which pins the real risk of someone copying columns in later. Also adds the Gitea wiki sync the plan had missed: docs-convention makes a version bump commit illegal on its own. --- .../plans/2026-08-25-thinking-observability-plan.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/research-wiki/plans/2026-08-25-thinking-observability-plan.md b/research-wiki/plans/2026-08-25-thinking-observability-plan.md index c3f161d..3a8f6e8 100644 --- a/research-wiki/plans/2026-08-25-thinking-observability-plan.md +++ b/research-wiki/plans/2026-08-25-thinking-observability-plan.md @@ -443,7 +443,13 @@ conda run -n PolyGateway pytest tests/unit/test_thinking.py -q **`README.md:21`**：`必录 24 字段` → `25 字段`。数字取 Task 6 验证步骤里 `inspect.signature` 的实测输出，**不凭记忆**（发布清单第 1 步点名的失败模式）。同时核对安装命令的版本约束是否需要跟进，以及能力表是否要提及推理裁定这一新行为。 -**`README.md` 的 `` 生产部署 DDL 模板**（Task 6 实施时发现，计划原本完全没覆盖）：那段 SQL 是**独立于 `schema.py` 手写的另一份**，而 `TestProductionTemplate` 只跑它建表与权限/RLS/分区行为，**从不拿它与 `COLUMNS` 比对**——少一列照样全绿。照该模板部署的下游会得到一张没有 `thinking_observation` 的表，manual 档下库会静默裁掉这一列，正是本 issue 要消灭的那种静默。补上该列，**并加一条同源断言**（模板里的列集合必须等于 `COLUMNS`）把这个缺口机械化堵住——它不是顺手清理，是本次改动直接暴露的风险，且没有断言就一定会再次漂移。 +**`README.md` 的 `` 生产部署 DDL 模板**——**本条计划原文是错的,已订正**。 + +原文断言该模板是"独立于 `schema.py` 手写的另一份 SQL",要求补上 `thinking_observation TEXT`。**事实相反**:该模板不含任何列定义,它是 `CREATE TABLE llm_calls (LIKE llm_calls_seed INCLUDING DEFAULTS, PRIMARY KEY (call_id, created_at)) PARTITION BY RANGE (created_at)`,列全部从上一步 `telemetry_schema_sql('postgres')` 建出的 seed 表派生,README 正文原本就写着"列不在这里重抄一份——抄了就会漂移"。照原文补列会让 PG 报列重复、`TestProductionTemplate` 全红、下游部署直接失败。 + +（这条错误的来路值得记下来: 它出自另一个任务的实施报告,写进计划时**没有自己打开 README 核实**。跨任务转述的"发现"必须当作待验证的线索,不是事实。） + +正确的做法是加一条**形态断言**: 模板必须靠 `LIKE` 派生,且不得内联任何 `COLUMNS` 里的列名。它钉住的是"日后有人把列抄进模板"这个真实风险——比原计划想堵的缺口更贴合实际。断言落在 `tests/integration/test_postgres_telemetry.py` 的 `TestProductionTemplate`（**不在** `tests/unit/test_telemetry.py`,计划原文也指错了文件）。 **`research-wiki/ARCHITECTURE.md`**：§8 模块结构树补 `thinking.py` 一行并说明职责；§8 依赖纪律段补 `thinking.py` 的层位；D11 段说明推理决策已从 `providers.py` 拆出；§5.1 响应字段表补 `thinking_observation`；§7.8 遥测字段补新列。 @@ -487,6 +493,8 @@ grep -rn '22 字段' research-wiki/schemas/llm-calls.md # 预期无输出 **第一段：分支内可自主完成的验证**——CHANGELOG 定版为 `## 1.3.1(2026-08-25)`；版本号两处改 `1.3.1`；`verification-before-completion` 派**全新上下文** verifier subagent 独立验证（跨 20+ 文件，属强制档）；`requesting-code-review` 整分支审查；在分支上跑 `make ci` 与 `pytest -m slow`（约 20-40 分钟——四个 e2e 文件与 Redis 时间语义变体默认被 `-m 'not slow'` 排除，不显式跑等于没跑）。 +**Gitea Wiki 文档站同步**（计划原本漏了,Task 9 实施时发现）：`research-wiki/docs-convention.md` §2 明写"新公共 API / 新能力 → 对应指南页 + `参考-公共API` + 侧边栏 + CHANGELOG"、"发版(任何版本号) → `Home.md` 版本号与安装命令",且该文件第 26 行是一道门——**版本 bump 的提交不允许单独存在**。本版有 6 个新包根导出、1 个新公共字段、1 个端口签名变更,wiki 必须同步。wiki 是**独立 git 仓库**(需 clone),故拆成两半：**内容在第一段写好待推**，`git push` 归第二段(外发动作)。 + **人类确认门**：以上全绿后停下，把验证结果交给人类，**取得明确同意后**才执行第二段。 **第二段：外发且难以撤销的动作，一律等确认**——合并 main（`--no-ff`）+ push → 打 tag 并 push → 构建 → 上传 registry → `pip download` 验证并解包确认新代码在内 → 建 Release + 挂仓库 + 核对包页面 → 关闭 issue #16 / #17 并附修复说明（诊断纠正 + 三层根因 + 落地形态）。顺序按 CLAUDE.md §4.4.1**不得跳步**：包上传与 tag 一旦推出去就收不回，registry 里的版本号也不能复用。