# PROGRESS · 普通对话上下文窗口与模型缓存（2026-09-06）

工作树：`.worktrees/consultation-context-and-cache-20260906`
分支：`codex/consultation-context-and-cache-20260906`
基线：任务书写 `origin/staging` @ `d8a0f615`；开工时 `origin/staging` 已到 `9ce7a374`（含 BUG-551/552/553），以当时远端为准。修复提交：`bf8ad0d1`。

未改 `page.tsx`、生时校正链路、Skill 正文、引擎。客户端零改动。迁移只加 `chat_sessions.context_summary`。未 bump Skill。

| 任务 | 状态 | BUG |
| --- | --- | --- |
| 5.1 摘要 + 尾巴历史 + 按模型预算 + 溢出重试 | 完成 | BUG-555 |
| 5.2 后台缓存可见 | 完成 | BUG-556 |
| 5.3 Anthropic 历史断点 | 完成 | BUG-556 |
| 5.4 共享方法段搬进系统块 | 完成 | BUG-556 |
| 5.5 BUG_HISTORY / CHANGELOG / testing | 完成 | — |

## 实现要点

- 历史 = `context_summary` 之后的全部消息。超 `historyBudgetChars` 时从最旧整条丢；单条 12,000 字截断并写省略标记。
- 摘要在最后一条用户消息、时间行之后、问题之前。检查点在 `complete_consultation_response` 成功后异步触发，不扣点，15 秒 ref 超时，乐观并发。
- 溢出识别后同一请求把历史缩到摘要 + 最后一对再 `stream` 一次。咨询公共事件是封闭联合，不能发 rectification 的 `attempt.reset`，所以重试留在服务端。
- 用量聚合按 `actual_model_id` 给出 7/30 天缓存命中；列表加 `cacheReadTokens`。`costMicrousd` 计价口径未改。

## 系统块 / 工具结果字节

| 块 | 之前 | 之后 | 变化 |
| --- | --- | --- | --- |
| `jyotishSkillMethodBlock` | 28,877 B | 35,323 B | +6,446 B（任务预期 +6.4 KB） |
| `<jyotish-shared-method>` | 无 | 6,396 B | Full-spectrum + Event judgment skeleton |
| 单领域 career `methodology.sections` 正文 | 约 13.4 KB（含上述两段） | 7,043 B | 只留 baseline + 领域两段 |
| 三领域 career/marriage/wealth 正文 | 约 25.3 KB | 18,914 B | 同上 |

9 段运行时节选与 `providesSkillDiscovery: "on-demand"` 未回退。

## 既有断言改动

| 文件 | 原值 | 新值 | 原因 |
| --- | --- | --- | --- |
| `consultation-session-history` | 最近 12 条 × 头部 4000 字 | 按模型预算从最旧丢整条；单条 12,000 + 省略标记 | BUG-555 静默砍结论 |
| `consultation-methodology` | sections 含 Full-spectrum / Event judgment skeleton | 这两段在系统块；领域清单仍随工具结果 | 工具结果不在缓存前缀里 |
| `chat-session-authority` / consult select | `...,chart_profile_role` | 另加 `context_summary` | 检查点读写 |
| `application-billing-contract` | 三处 `usages.push(result.totalUsage)` | 一处，在 `streamWithOverflowRetry` | 溢出重试共用首次 stream |
| `admin-usage-aggregate-contract` | 只有 30 天功能用量 | 另加 cache 7/30 天窗口 | BUG-556 命中率不可见 |

## 测试

| 命令 | 结果 |
| --- | --- |
| 本单相关 `npx tsx --test`（history / summary / cache contract / methodology / skill-binding / generation-settings / admin usage / onboarding-route） | 58 pass / 0 fail / cancelled 0；摘要超时用例 cancelled 0 |
| `./node_modules/.bin/tsc --noEmit`（先删 `.next`） | 0 错 |
| 改动文件 eslint `--quiet` | 0 error |
| `page.tsx` | 未改 |
| `npm run build -- --webpack` | 编译通过；类型检查停在既有 `dossierResponse` 路由导出（与 BUG-551/553 相同），未打印 `○ /` |
| 全量 `npx tsx --test tests/*.test.ts`（排除 `tests/database-*.test.ts`） | 2726 tests / 2712 pass / 14 fail：Docker 地址池耗尽 + 1 条 onboarding 超时竞态（单跑通过） |
| `npm run test:db` | **blocked**：见 `BLOCKED.md`。迁移在一次性 Postgres 上经 stub 表语法检查通过 |

## 收尾限制

- 溢出重试只包住 `agent.stream()` 抛错；流开始之后供应商才报超窗时不会第二次缩窗（咨询公共事件不能发 `attempt.reset`）。
- 摘要失败只 `console.warn("session context summary failed", error)`，不打印摘要正文。
- `costMicrousd` 仍按全价输入单价。

## 验收（Claude，2026-09-06，对照 `TASK-consultation-context-and-cache-20260906.md`）

共用门禁见 `PROGRESS-session-list-title-and-order-20260906.md` 验收段（`e2f4b55c`：tsc 0 错、lint 0 error、2770 项测试 29 条环境失败、`next build` `/` Static、首屏 gzip +0.61%）。

| 项 | 结论 | 依据 |
| --- | --- | --- |
| 5.1 迁移 `20260906010000_chat_session_context_summary.sql`（`context_summary jsonb null` + 列级 grant） | 通过（`test:db` 环境缺口） | 本机无 Docker；执行方 `BLOCKED.md` 已记 Docker 地址池耗尽；**部署前必须先跑 Migrate Staging Database** |
| 5.1 历史 = 摘要之后 append-only 尾巴；单条 12,000 + 省略标记；按 `context_window` 预算 `clamp((cw−60k)×1.5, 4k, 40k)` 从最旧丢整条；null → 128k | 通过 | `consultation-session-history.ts::consultationHistoryWindow / historyBudgetChars / clipConsultationHistoryText`；`model-catalog.ts` 现读 `v.context_window` |
| 5.1 检查点摘要：尾巴 >16,000 字才触发、最后一对不进摘要、`complete_consultation_response` 成功后异步、不扣点、ref 计时器 15 s、默认模型、正则清洗、乐观并发 | 通过 | `session-context-summary.ts`；`checkpointConsultationContext` 的 update 带 `context_summary->>updatedAt = seen` / `is null` 守卫；`messages` 数组只追加不删（RPC 全部核过），`throughMessageIndex` 稳定 |
| 5.1 摘要放最后一条用户消息、时间行之后、问题之前 | 通过 | `consultationUserTurnContent`；三条路径（agentic / general / legacy）同一函数 |
| 5.1 溢出识别 + 同请求一次降级重试 | 通过（有边界） | `isContextOverflowError` 覆盖 OpenAI / Anthropic 文案与 400；`streamWithOverflowRetry` 只包 `agent.stream()` 抛错，流开始后的供应商报错不再缩窗——执行方已在「收尾限制」写明，接受 |
| 5.2 后台缓存可见 | 通过 | `api/admin/usage/aggregate` 按 `actual_model_id` × 7/30 天给 `runsWithCache / hitRate / readTokens / writeTokens / noCacheTokens / cacheShare`；列表 `cacheReadTokens` |
| 5.3 Anthropic 最后一条历史加第二断点 | 通过 | `agent-generation-settings.ts::cachedHistoryMessage` 仅 anthropic 生效 |
| 5.4 Full-spectrum + Event judgment skeleton 进系统块、工具结果只剩领域段 | 通过 | `skill-binding.ts` `<jyotish-shared-method>`（+6,446 B）；`consultation-methodology.ts::sharedConsultationMethodMarkdown`；9 段节选未回退 |
| 5.5 BUG-555 / 556、CHANGELOG、testing 清单 | 通过 | — |

**结论：通过**（`test:db` 为环境缺口）。修复 SHA `bf8ad0d1`。部署顺序：先 Migrate Staging Database（本迁移 + `bab07187` 的 `5010000_personal_report_longform_appendices.sql`），再 deploy，再核 `/api/health`。