Jyotisha/docs/tasks/PROGRESS-consultation-external-evidence-cache-20260915.md

# PROGRESS · 普通聊天外网证据缓存（2026-09-15 / 2026-09-16）

工作树：`.worktrees/consultation-external-evidence-cache-20260915`
分支：`codex/consultation-external-evidence-cache-20260915`
任务书基线：`origin/staging` @ `6b3248bf`（任务书写）
开工时远端：`origin/staging` @ `11893c7f973573da78d6dbb48db89cde8b373ecc`
预占 BUG：**727 / 728**（基线最大号 720；721–726 为同日其它单预占，未冲突）
交付 commit：`d49bd9cd`

## 串行基线偏离（产品授权）

`TASK-api-server-decomposition-20260916` **未合入** staging。任务书要求以拆分后的 `scripts/jyotish_api_server.py` 为基线；产品负责人要求本单现在就做。因此：

- **没有增长** `scripts/jyotish_api_server.py`。新逻辑在 `scripts/vedastro_snapshot_cache.py`、`scripts/vedastro_foreground.py`；主文件只做薄导入、把 submit/join 换成 `start_foreground_vedastro` / `finish_foreground_vedastro`、按需挂 `western_evidence_packet`。
- 冻结合同：`wc -l` 口径开工 **11334** 行，交付 **11291** 行（少 43）；上限 11063+300=**11363**。

未改 context-memory 的前端会话文件，未改 session-capacity 的 SQL 迁移。

## 任务对照

| 任务 | 状态 | BUG |
| --- | --- | --- |
| 5.1 盘 + UTC 日期缓存 | 完成 | BUG-727 |
| 5.2 超时 cancel + join/budget/workers 成组，`budget ≤ 2×join` | 完成 | BUG-727 |
| 5.3 `western_evidence_packet` 按需返回 | 完成 | BUG-728 |
| 5.4 staging 单域耗时清单 | 完成（环境缺口：无 staging 登录） | — |
| 5.5 BUG-727 / 728 | 完成 | — |

## 实现要点

- 缓存键：`sha256(年月日时分秒 + lat + lon + tz + ayanamsa + node + UTC reference_date)`，文件名只有哈希。目录 `scratch/local/vedastro_snapshot_cache`，与 `_api_chart_cache` 分开。
- 同日命中：直接用，不 submit。1–7 天：先用旧的（网关包上标 `snapshot_reference_date`），后台刷新只写缓存。`entrypoint=daily_starlanguage` 只接受当天。未命中才走 1.5 s join。
- 只缓存 `official_verified` 且带 raw 的包；超时/blocked 不落盘，避免把未交付层标成 executed（BUG-301）。
- `_join_foreground_vedastro` 超时 `cancel_event.set()` + `future.cancel()`。budget 默认改为 `2×join`（1.5 s → 3 s），不再默认跑满 8 s。
- 非前台路径（报告/高严谨）仍同步跑网关、不受 join 上限，成功后同样写缓存。
- 前台响应默认去掉 `western_evidence_packet`，仍算、仍投影 `consumer_context.western_spectrum`。MCP / 高严谨 / `include_western_evidence_packet` / `western_oracle_payload` 仍返回整包。
- 前端 `runConsultationWorkflow` 把 `entrypoint` 传给 Python，供 daily 入口拒绝隔日缓存。

## `western_evidence_packet` 检索

| 位置 | 处理 |
| --- | --- |
| `frontend/src` | **零命中**，按「无人读」从咨询响应去掉 |
| `scripts/jyotish_api_server.py` | 仍计算；默认不进响应 |
| `scripts/vedastro_foreground.py` | `should_include_western_evidence_packet` |
| `scripts/western_evidence_packet.py` / `western_chart_engine.py` / `western_oracle_adapter.py` | 保留计算 |
| `scripts/unified_consultation_orchestrator.py` | 仍传入做审计日志 |
| `scripts/cross_system_arbitrator.py` | 保留 |
| `mcp_server.py` | 保留；`surface=skill_mcp` 仍返回整包 |
| `tests/` | oracle / MCP / 按需返回的断言保留 |

## 响应体积

| | 字符 |
| --- | ---: |
| 任务书基线（career 同参第二轮） | 523 k，其中 `western_evidence_packet` 122 k |
| 本机改后（stub 工作流，默认响应） | 该键不存在 |
| 显式 `include_western_evidence_packet` | 键在，体积 ≥ 默认响应 |

未在 staging 重测 523 k 真包（无登录）。按基线，每域少约 122 k 字符。

## 测试

本机无 `G:\Ferti\Jyotisha\.venv`，用 `C:\Users\74082\anaconda3\python.exe`（3.11.7）。任务书写的是 Python 3.13 + swisseph。

| 命令 | 结果 |
| --- | --- |
| `pytest tests/test_vedastro_snapshot_cache.py` | **10 passed** |
| 上项 + 前台赶上/超时/oracle/growth | **18 passed** |
| `pytest tests/test_consultation_consumer_context.py tests/test_vedastro_runtime_ops.py tests/test_vedastro_snapshot_cache.py tests/test_api_server_growth_contract.py tests/test_consultation_workflow_domains.py` | **pass**（1 skip：本机未装 vedastro pin） |
| `pytest tests/test_api_server_security.py` + 上列相关 | **169 passed / 6 failed / 1 skipped**。6 条失败在 **HEAD 无本单改动时同样失败**（thematic `relationship_strict_evidence` / `月度主状态`；`shadbala` advanced：`timezone inference dependency unavailable`）。不是本单引入。 |
| `frontend`：`consultation-workflow-contract` + `consultation-spectrum-parity` | **13 passed / 0 failed** |
| `scripts/run_quality_gate.py --profile quick` | **compile 通过**（含新模块）。停在 `interpretation_source_inventory_gate.py`：`ModuleNotFoundError: No module named 'mcp'`（Anaconda 无 FastMCP）。未改依赖。 |

## 开工预检

`python scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45`：**fail**。`remote_visibility=verified`，fragment/external engine 扫描通过；`tests/test_preflight_fragment_scan.py` 在本机找不到 `.workbuddy/skills/jyotish-vedic-astrology`（Windows 工作树无该镜像）。属 ERR-007 同类环境，未新开台账。不得把 `.workbuddy` 当运行主仓。

## 5.4 staging 耗时

清单：`docs/testing/consultation-external-evidence-cache-20260915.md`。无 staging 登录，**环境缺口**。改前数字用任务书本机表（career 928/865 ms）。改后 staging 两轮 `consultationToolDurationMs` 待产品回填。本单不改三域上限 3。

## 观察项（本单不修）

`reference_date` 缺省 UTC 当天，与 UTC+8「今天」早上八点前后会错开一天。

## 既有断言改动

| 文件 | 原值 | 新值 | 原因 |
| --- | --- | --- | --- |
| 咨询工作流默认响应 | 总有 `western_evidence_packet` | 默认无该键 | BUG-728 无读取点 |
| `_foreground_vedastro_budget_seconds` 默认 | 8 s（2–12） | `min(env, 2×join)`，join 默认 1.5 → budget 3 | 5.2 让步：预算不超过 join 两倍 |
| `tests/conftest.py` | 无缓存隔离 | autouse 把 snapshot cache 指到 tmp | 避免测试互相命中磁盘缓存 |