From f898df5505e79275347748a2ce80cabb4a9b6902 Mon Sep 17 00:00:00 2001 From: Jesse_Chen Date: Wed, 30 Sep 2026 09:41:38 +0800 Subject: [PATCH] docs(tasks): implementation brief for varga-resolution (chart-type) rectification delivery (BUG-1115..1117 reserved) Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017eEAG8HD3mm8gsKXgk8uU8 --- docs/tasks/README.md | 1 + ...rectification-varga-resolution-20260930.md | 103 ++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 docs/tasks/TASK-rectification-varga-resolution-20260930.md diff --git a/docs/tasks/README.md b/docs/tasks/README.md index ef95ca0a..690c8a23 100644 --- a/docs/tasks/README.md +++ b/docs/tasks/README.md @@ -258,6 +258,7 @@ | `TASK-rectification-holdout-expansion-20260929.md` | `PROGRESS-rectification-holdout-expansion-20260929.md` | **开放评价集扩到 ≥60 例（v5）**：所有打分判定都在 20 例上做，1 例 = 5pp，KP / 精度闸 / V1n 的 no_benefit 都只差 1–3 例。只用 Rodden AA 公开名人，事件人工核对出处，分层（年代 / 纬度 / 南半球 / 跨午夜 / UTC+8），v4 不动；基线成绩单 v4 子集须与已发布数字逐格一致。研究单的判定以 v5 为准 | 已验收（Claude 09-29：77 例、v4 子集数字逐格一致、抽样 6 例来源一致、冻结文件零改动；UTC+8 5/6 为数据可得性缺口，接受；已合入 staging）→ 研究单判定可开工 | 分支 `codex/rectification-holdout-expansion-20260929`（BUG-1090） | | `TASK-rectification-scoring-research-20260929.md` | `PROGRESS-rectification-scoring-research-20260929.md` | **打分方法研究（离线）**：R-A 似然比校准权重（leave-one-case-out，KP / Pranapada / D60 作为特征由数据定权重、允许负权重）、R-B 缺席证据（口述时间线覆盖时段内的空白年扣分，必测漏说稳健性）、R-C 精度追问可行性（对已说事件追问月份，算在定向追问 2 条额度内）。判定必须在 v5 上做；有收益才立实现单并按 ERR-110 重冻结 | 已验收关单（Claude 09-30：v5 77 例三项全部不过硬红线 1，稳定特征 0 个；BUG-1091 closed_by_design；打分路线关闭，后续走产品口径「盘型选择」研究） | 分支 `codex/rectification-scoring-research-20260929`（BUG-1091 closed_by_design） | | `TASK-rectification-varga-resolution-research-20260930.md` | `PROGRESS-rectification-varga-resolution-research-20260930.md` | **「盘型口径」研究（离线）**：打分层关闭后，把校正目标从分钟改为分盘上升段。v5 实测：±10 六题后 D1 单一 75/77，D9/D10 ≤2 种 68/63，多数=真值 88%/84%；±30 起分盘分不开。M0 入库段扫描与区间脚本、M1 段级汇总与阈值-准确率（留一法）、M2 按段选题、M3 按问题域取盘 + 「不用校正」比例、M4 实现单要点。不改引擎 / 常数 / 冻结文件；红线：真值段不被排除 ≥ 现在真值在区间比例 | 已验收（Claude 09-30：M0–M3 + 稳健性完整执行，复跑逐字节一致，红线逐格核对；盘型口径成立——±10 D9/D10 头段=真值 88%/86%、占比≥0.6 留一法 92%/90%，±30 约 1/4–1/3 用户可信，±60 分盘 blocked；提前停不过门；「不用校正」只对 D1 成立。另一会话 08:49 部分归档 bedb4d7b 已被取代并移除）→ 实现单待写 | 分支 `codex/rectification-varga-resolution-research-20260930`（BUG-1105） | +| `TASK-rectification-varga-resolution-20260930.md` | — | **「盘型口径」实现单**：交付改为「每张目标盘的上升 + 可信度档位」（≤±10：≥0.6 较可信 / 0.5–0.6 倾向 / <0.5 分不开；≤±30 只有较可信或分不开；>±30 只给 D1）；按问题域取盘（婚恋 D1+D9 / 事业 D1+D10 / 综合三张）；段扫描端点 + 「盘型一致不用校正」出口；按段选题仅 ≤±30；不得用占比提前停；采用落库头段交集中点。不改引擎 / 常数 / 冻结文件。红线：回放 ±10/±30 真值段保留 76/76、头段命中不低于研究「按段」列；段级汇总与研究 JSON golden 逐格一致 | 待领取 | — | | `TASK-rectification-typed-event-scoring-research-20260929.md` | `PROGRESS-rectification-typed-event-research-20260929.md` | **打字经历按选择题规则计分（离线研究，不上线）**：计分通道不对称 + 已入账年份挡题；R0 学业质量题措辞 / 年精度显示成 1 月（冻结文件，需重新冻结） | 已验收（Claude 2026-09-29 合并验收：全量前端 4302/24 与基线同 24 条环境失败、tsc 0、lint 0 error、`/` Static、gzip +0.16%、快速门 pytest 1001 passed、两份回放复跑一致），待部署核对 | BUG-1088、1089 | | `TASK-report-reader-polish-20260929.md` | `PROGRESS-report-reader-polish-20260929.md` | **报告页打磨**：生成入口挪进页面主体（删标题栏按钮）、详情页到底部按钮（懒渲染一次到底）、导出按钮带文字、目录一级/二级分层、去掉「字段」与 RL/NL 缩写表头、状态列同义重复去重、报告表格淡底色、分块导出显示真实文件大小 | Claude 直接执行并自验（tsc 0、lint 0 error、全量 fail 与基线同 24 条、`/` Static、gzip +7 B、快速门 Python 1000 passed），已部署 staging `d7772011`，真机欠 | BUG-1092～1094 | | `TASK-report-english-edition-20260929.md` | `PROGRESS-report-english-edition-20260929.md` | **报告中英两版**：同一次引擎计算渲染 zh/en 两遍（不用模型翻译），瑜伽库 477 条补英文、模板与前端表头英文化；中文逐字节不变、英文零汉字、两版数字序列一致；阅读页 `?lang=en` 切换，导出当前语言 + 「问 AI 建议导出英文版」提示；旧报告不补英文 | Claude 直接执行（含两个 fork 子代理）并自验（tsc 0、lint 0 error、全量 fail 与基线同 24 条、`/` Static、gzip +0.06%、Python 定向全绿），已部署 staging `d7772011`，真机欠 | — | diff --git a/docs/tasks/TASK-rectification-varga-resolution-20260930.md b/docs/tasks/TASK-rectification-varga-resolution-20260930.md new file mode 100644 index 00000000..6c29d50b --- /dev/null +++ b/docs/tasks/TASK-rectification-varga-resolution-20260930.md @@ -0,0 +1,103 @@ +# TASK · 生时校正「盘型口径」实现：以分盘上升段为目标交付（2026-09-30） + +## 基线 + +- `origin/staging` @ `c2c5140d`（写作时 head；开工时以最新 `origin/staging` 为准）。 +- 分支 `codex/rectification-varga-resolution-20260930`，工作树 `.worktrees/rectification-varga-resolution-20260930`。 +- **前置**：研究单 `TASK-rectification-varga-resolution-research-20260930.md`（BUG-1105，已验收合入）。数字与实现要点见 `docs/research/rectification_varga_resolution_2026_09_30.md` §1、§7；研究脚本 `scripts/research/varga_resolution_probe.py` 是本单的验收回放器。 +- **串行**：本单改 `frontend/src/lib/rectification-agentic/{core,v9}/*`、`user-copy.ts`、`components/rectification-range-delivery.tsx`、`rectification-timeline.tsx`。同日报告 / 首页各单不重叠；若另有校正单开工，本单先合。 +- **冻结**：不动 `scripts/research/sealed_holdout_rerun.py::PRODUCTION_FILES` 的 10 个文件（含 `event_probes.py`、`decision_policy.py`、`candidate_contrast.py`、`refinement_packet.py`、`api_service.py`）、`active_rectification_event_engine.py`、任何打分常数（ERR-110）。新后端逻辑放**新文件**并从 `jyotish_api_server.py` 薄注册（§6 增长冻结）。 + +## 先读 + +- `docs/research/rectification_varga_resolution_2026_09_30.md`（全文，尤其 §1 出口表、§4 提前停不过门、§7 改 / 不改清单） +- `docs/research/rectification_scoring_research_2026_09_29.md` §1（打分层为何关闭） +- `docs/tasks/TASK-rectification-futile-collect-stop-20260929.md` D1–D4（门开只问点选卡、交付正文口径——本单沿用） +- `frontend/docs/VOICE.md`、`frontend/DESIGN.md` 校正相关段 + +## 事故实证 + +产品 2026-09-29 真机：31 分钟窗答完题范围不动，「最可能的分钟」在 v5 上头名只有 64%；用户追问「那用户信息没用了？业务怎么成这样」。研究单在 77 例上量出： + +| 窗口 | D1 头段 = 真值 | D9 / D10 头段 = 真值 | 占比 ≥ 0.6 留一法准确率 | 结论 | +| --- | --- | --- | --- | --- | +| ≤ ±10 | 76/77 | 88% / 86% | 92% / 90% | 分盘可分档给可信度 | +| ±30 | 75/77 | 57% / 64% | 92–94%（约 1/4–1/3 用户达标） | 多数用户只能给 D1 | +| ±60 | 69/77 | ≤ 47% | 真值段保留 74 < 基线 75 | 分盘 **blocked** | + +同一题库按「段级信息增益」重排：≤ ±30 头段命中 +3～+7、宽度 −2、真值段保留不降；±60 更差。**提前停（占比达 0.7 / 0.8 即停）丢真值段，不过红线。** 「不用校正」只对只需 D1 的问题成立（±10 64/77），D9 / D10 为 0/77。 + +## 根因（产品层） + +1. 目标函数是分钟：选题按分开候选分钟排序、交付按分钟区间与「最可能分钟」、并列按分钟数（`core/rectification-decision.ts`、`credible-range.ts::unionStillValidRange`、`user-copy.ts::deliveryTurnNarration`）。用户要的是「用哪张盘解读」。 +2. 不按问题域取盘：`ConversationFocus.domain`（`v9/tool-service.ts:155`）只用于采集，不决定目标分盘。 +3. 没有「分盘不可判」的诚实出口：±30 以上仍给分钟区间。 +4. 候选行已带 D1 / D9 / D10 层（`candidate_contrast.py:181` `signature`，`SIGNATURE_LAYERS = (d1, d9, d10, d24, d4, d12, md)`；`refinement_packet.py:198`），前端 `tool-service.ts` 行映射未解析，段级信息一直没被用。 + +## 决策记录（产品 2026-09-30） + +- **D1 目标改为分盘上升段。** 交付物是「每张目标盘的上升星座 + 可信度档位」，分钟区间降为次要信息（仍展示，不再作主结论）。 +- **D2 按问题域取盘。** 婚恋 → D1 + D9；事业 → D1 + D10；综合 / 报告 / 未指明 → D1 + D9 + D10。D12 等其他分盘不作目标、不展示推荐。 +- **D3 可信度档位（研究单校准，raw 口径，头段占比 s）**： + - 窗口 ≤ ±10（≤ 21 分钟）：s ≥ 0.6「较可信」；0.5 ≤ s < 0.6「倾向，备选也要看」；s < 0.5「按现有信息分不开」。 + - 窗口 ≤ ±30：s ≥ 0.6「较可信」，否则「分不开」（不出「倾向」档）。 + - 窗口 > ±30：D9 / D10 一律不给推荐，文案「只能确定 D1 上升 X；分盘解读需要更准的出生时间」。 + - D1：头段 = 全窗唯一 → 「确定」；否则同上分档。 +- **D4 不得用占比提前停。** 出题与停止条件不变：训练门开后只问点选卡，`refreshExhausted` 即出卡（沿用 BUG-1084 D1）。占比只决定档位。 +- **D5 按段选题只在窗口 ≤ ±30 启用**；> ±30 沿用线上顺序。 +- **D6 「不用校正」出口**：只有当目标盘集合里每张盘在全窗都只有 1 种上升时才触发（实际只会发生在只需 D1 的问题上）；触发时直接出「盘型一致，不用校正」卡，不进采集。 +- **D7 采用（adopt）落库分钟**：目标盘头段的交集中点；交集为空则按优先级 D1 > 领域盘 取头段中点；该分钟必须落在交付区间内，否则取区间内最近的分钟。采用 / 确认门、来源标签（BUG-690）不变。 +- **不改**：引擎、11 张计分分盘、`MIN_SEPARATION_LEAD`、45 天闸门、七条采集线、卡片 ±2 与三次淘汰、训练门、留一件对照、`event_probes.py` 出题。 +- **推翻**：`TASK-rectification-candidate-compare-columns`（交付卡一行三列定稿）与 `TASK-rectification-delivery-ui-simplify`（时间卡逐行直选）中以分钟为主的交付卡形态，本单起交付卡以盘型为主；分钟区间保留为折叠 / 次行。执行方在相关 BUG 防复发条下追加「2026-09-30 产品修订：见本任务书 D1」，不删原文。 + +## 硬红线 + +1. **回放红线**：实现后用 `scripts/research/varga_resolution_probe.py --stages m0,m1,m2` 对接生产段级汇总（T2 合同测试保证同口径），±10 / ±30 真值段保留 ≥ 76 / 76，头段 = 真值不低于研究文档 §4「按段」列（±10 D9 71 / D10 66；±30 D9 48 / D10 56）；> ±30 交付卡不得出现 D9 / D10 推荐。任何一格变差即停，写 PROGRESS。 +2. **段级汇总与研究脚本逐格一致**：前端 `core/segment-summary.ts` 对 ≥ 10 个 v5 案例的 golden 输入（真实引擎候选行 + 六题后分数）输出的头段 / 占比 / 段数与 `docs/research/varga_resolution_research_2026_09_30.json` `m1.by_radius.*.raw.per_case` 逐格相等。fixture 必须来自真实引擎响应（§7.4）。 +3. 不放宽任何置信度边界；档位阈值只能取 D3 的值。 +4. 前端：`tsc --noEmit` 0 错、`npm run lint` 0 error、`npm test`（Node 22，`/exec-daemon/node`）失败清单与基线逐条一致、新增失败 0；`next build` 后 `/` 仍 Static、首屏 gzip ±2%；`page.tsx` 不增长；改既有断言写「原值 / 新值 / 原因」。 +5. Python：新端点模块有定向测试；`run_quality_gate.py --profile quick` 与基线逐条一致；`test_api_server_growth_contract.py` 绿；完整性门禁绿（冻结文件哈希不变）。 +6. Skill / Agent 提示文本改动按 CHANGELOG 规则 bump，bump 后验证旧校正会话仍能打开（BUG-621）。 +7. 隐私：fixture 只用 v5 公开名人或虚构盘；文档不写真机会话内容。 + +## 任务分解 + +- **T1 段扫描端点（BUG-1115，后端）** + - 新文件 `scripts/rectification_varga_segments_api.py`：输入出生日期 / 地点 / 时区 / 窗口 / 目标盘集合，逐分钟算 D1 / D9 / D10 上升（复用 `domain_calculation_service.compute_chart` + `varga.calc_all_vargas`，口径同研究 lib），输出各盘段表（段起止分钟、星座、长度）与「全窗唯一」标志；结果按窗口键缓存到 `api_scratch`。`jyotish_api_server.py` 只加一处薄注册。 + - 验收：`tests/test_varga_segments_api.py`（跨午夜、±10/±30/±60、与 `varga_resolution_lib` 段切分逐分钟一致）；api_server 行数不超 growth contract。 +- **T2 段级汇总（BUG-1116，前端）** + - `tool-service.ts` 行映射解析 `signature` 的 d1 / d9 / d10（候选级，2 分钟步长）；新增 `core/segment-summary.ts`：在 `buildInferenceState` 的分钟分数之上按段求和（raw：有效簇分数 ≥ 0、簇内均摊，与研究 lib 同算法），输出每张目标盘的段列表、头段、占比、剩余段数、真值段保留所需字段；`rectification-decision.ts` 的交付判断读取它给档位（D3），**不改**出卡时机（D4）。 + - 验收：硬红线 2 的 golden 合同测试；单测覆盖 D3 三档 × 三档窗口 × D1「确定」；并列（两段占比相等）按先出现段并标 tie。 +- **T3 按域取盘 + 「不用校正」出口（BUG-1116）** + - `ConversationFocus.domain` → 目标盘集合（D2）；录入 / 开案后调 T1，D6 成立时直接出「盘型一致」卡（新卡，走 `finalizeSuccessfulTurnExit` 单一写入方，不得再造第二条出口），并把该判定写进案例 `checks`。 + - 验收：表驱动测试七个领域 → 目标盘集合；D6 触发 / 不触发各一例；触发后不发采集题。 +- **T4 交付卡与采用卡（BUG-1117，前端 + 文案）** + - `rectification-range-delivery.tsx`：主区按目标盘逐行「D9 上升：金牛（较可信 / 倾向 / 分不开），备选：白羊」；D1 行「确定」时不出备选；> ±30 只出 D1 行 + 一句诚实说明；分钟区间移到次行。`rectification-timeline.tsx` 的范围小字同步。 + - `user-copy.ts`：`deliveryTurnNarration` / `rangeDeliveryIndistinct` 改为盘型口径；删除「最可能的分钟」主句；Agent 提示（`frontend/src/mastra/agentic-rectification.ts`）第二句改为「用了 M 道选择题，D9 上升较可信是 X」类句式；`VOICE.md`、`DESIGN.md` 同提交。 + - 采用：按 D7 计算落库分钟；采用卡文案「改用 X 盘解读」；确认门不变。 + - 验收：文案合同测试断言交付气泡不含「最可能」「吻合率」「补一件」；三档窗口 × 三种取盘策略的快照测试；采用分钟落在交付区间内的断言。 +- **T5 按段选题（BUG-1116，前端，仅 ≤ ±30）** + - 新模块对 `event_probes` 返回的题池按段级信息增益重排（算法同研究 lib：中性候选按 ½ / ½），只改顺序不改题；> ±30 不启用。 + - 验收：以 v5 golden 题池比对研究 JSON `m2` 的前六题顺序（≥ 10 例逐格一致）；线上顺序回退开关（环境变量或 case 标志）。 +- **T6 记录与回放** + - 回放：把生产段级汇总接到 `varga_resolution_probe.py`（`--posterior production` 之类开关，研究脚本可改），跑硬红线 1 六格，JSON 进 `docs/research/varga_resolution_impl_replay_2026_09_30.json`。 + - `CHANGELOG.md`（用户可感知：交付改为「用哪张盘」+ 可信度；窗口过宽时诚实说明）；`docs/BUG_HISTORY.md` 三条；`docs/testing/rectification-varga-resolution-20260930.md` 真机清单（至少：±10 窗口婚恋问题 → D1 + D9 两行；±60 窗口 → 只有 D1 行；只需 D1 且全窗一种 → 「不用校正」卡；采用后报告页盘型与卡片一致；旧校正会话可打开）；`docs/tasks/PROGRESS-rectification-varga-resolution-20260930.md`；`docs/tasks/README.md` 状态板。 + +## 让步顺序 + +T2 > T4 > T1 > T3 > T5 > T6 之外的截图。**T2 + T4 + 回放红线缺一不可合入**；T5 可延后（延后时 PROGRESS 写明，研究文档 §4 的收益不计入本单验收）；T1 / T3 延后时「不用校正」出口不上线、目标盘按综合三张。 + +## 开工前置命令 + +```bash +git fetch origin --prune +export PATH=/exec-daemon:$PATH && node -v # 22.x +git worktree add -b codex/rectification-varga-resolution-20260930 .worktrees/rectification-varga-resolution-20260930 origin/staging +cd .worktrees/rectification-varga-resolution-20260930/frontend && npm ci && ./node_modules/.bin/tsc --noEmit && npm run lint && npm test 2>&1 | tee /tmp/varga-impl-baseline.log +cd .. && export PYTHONHASHSEED=0 && python3 scripts/run_quality_gate.py --profile quick 2>&1 | tee /tmp/varga-impl-quick-baseline.log +python3 scripts/research/varga_resolution_probe.py --help +``` + +## BUG 编号 + +开工时核对 `docs/BUG_HISTORY.md` 最大号（写作时 `BUG-1105`；`1106`–`1114` 已被其他任务书预留）。本单：**BUG-1115**（段扫描端点 / 「不用校正」出口缺失）、**BUG-1116**（段级汇总、按域取盘、按段选题——目标函数是分钟）、**BUG-1117**（交付卡与采用卡以分钟为主、±30 以上无诚实出口）。号冲突顺延并在 PROGRESS 说明。关联 BUG-1084、BUG-1090、BUG-1091、BUG-1105。