Jyotisha/docs/benchmark/README.md

准确率基线、外部 Oracle 闭环与 Benchmark 看板

本文从根 README 拆出（2026-09-03），内容原样保留。这里是所有"本机现在能跑什么、哪些指标可测、哪些能力还缺外部 oracle 证据"的命令入口；看板产物就在本目录。所有看板固定输出 can_claim_global_first: false 与 production_tuning_allowed: false，直到外部样本达到生产调参标准。

真实案例复验与准确率边界

一条命令查看本机当前技能覆盖与准确率基线：

python3 scripts/local_accuracy_report.py --format markdown

如需给副手、CI 或后续自动化读取，使用 JSON：

python3 scripts/local_accuracy_report.py --format json

当前总控报告会聚合 technique registry、BPHS invariants、公开人物真实案例复验、Yoga precision/recall/F1、Dasha/Shadbala oracle readiness、Ashtakoot API parity。它用于回答“本机现在能跑什么、哪些指标已经可测、哪些能力还缺外部 oracle 证据”；它不把本地回归测试包装成最终人生事件预测准确率。

公开人物样本复验命令：python3 tests/run_real_case_revalidation.py。

当前复验口径是公开人物样本的出生盘星座级一致率，并对部分带有来源矛盾、时区争议或边界度数的参考行标记为 controversial_reference。这个指标用于验证排盘计算是否稳定，不等同于人生事件预测准确率，也不应被当作个人命运判断的命中率。

Dasha 参考差异审计

对照外部 PDF 或第三方软件时，先运行 Dasha 参考差异审计，而不是直接改生产常数：

python3 scripts/dasha_reference_audit.py \
  --year YYYY --month MM --day DD \
  --hour HH --minute mm --second ss \
  --lat LAT --lon LON --tz TZ \
  --target-start-date 1986-05-18 \
  --target-source third_party_chart.pdf

该工具会输出当前 Vimshottari 起点、秒级出生时间敏感性、年长常数敏感性，以及对齐目标日期所需的 Moon sidereal longitude 偏移量。不要为单份 PDF 直接调生产常数；应先建立更大的 oracle 样本集，比较 ayanamsa、Moon sidereal longitude、Nakshatra 边界与 Vimshottari 起算口径。

也可以运行合并版外部 oracle 边界审计，同时查看 Dasha、外部黄经与 Shadbala 的校准状态：

python3 scripts/oracle_boundary_audit.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json

该报告会明确标出 production_tuning_recommended: false：当前目标集已有外部验证行，但差异审计仍会拒绝单样本或全局倍率调参；VedAstro SDK 黄经样本已纳入 longitude_cases，用户盘最大差异约 26.23 角秒、D1/D9 落点一致，但这只能说明基础黄经接近，不能把当前目标集闭合夸大成生产级全局校准。

三方官方/外部 oracle sanity 总控命令：

python3 scripts/external_oracle_sanity_closure.py --format markdown

该报告同时检查 VedAstro official precision sanity、PyJHora black-box artifacts、jyotishganit MIT reference layer。默认命令为非阻塞 sanity，总控质量门可运行；需要真实触发 VedAstro official full snapshot 细算时，加 --live-official-full-snapshot。当前允许声明的是“高严谨带 blocked 行”：PyJHora 黑盒证据与 jyotishganit 参考层可审计；VedAstro 黄经 sanity 通过但 official full snapshot 细算仍需显式 live probe 且可能因前台预算或官方快照合同 blocked，不能声称三方 fully closed。

外部真值采集队列用于把缺失目标值拆成可执行任务，而不是直接调生产参数：

python3 scripts/oracle_collection_queue.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format markdown

如需给自动化或副手读取，可改用 JSON 输出：

python3 scripts/oracle_collection_queue.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format json

如需让真人或 Antigravity AI 副手直接填写证据包，可一次性导出每个 case 的 draft JSON：

python3 scripts/prepare_oracle_capture_packets.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --output-dir references/oracle/artifacts/pending_packets

该命令会生成 capture_manifest.json、OPERATOR_NEXT_STEPS.md 和 5 个 external_*.json。这些导出包只是人工复核/再采集入口；当前主 oracle 文件的目标集状态以 closure dashboard 和 validator 输出为准。

如果只想优先准备当前最短闭环链路的三条首包，而不是一次性导出整批 pending packets，可直接生成统一 blank kit：

python3 scripts/generate_blank_oracle.py \
  --output-dir references/oracle/artifacts/first_packet_blank_kit

该命令会按当前推荐顺序导出 dasha、tajika_sahams、shadbala 三条 front 的首包草稿、blank_oracle_kit_manifest.json 和 BLANK_ORACLE_KIT_NEXT_STEPS.md。它只复制当前首包模板，不会猜测真值，也不会把本地引擎输出伪装成 external oracle。

填完某个 external_*.json 后，必须把 status 改为 external_verified，补齐 metadata、具体 source_artifact 文件路径以及所有 target_placeholders。再把该包合并回 oracle 文件：

python3 scripts/oracle_collection_queue.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_dasha_lahiri.json \
  --format json

这一步只负责把人工填写的外部证据写回 template_cases；它不会自动认可证据，也不会允许生产调参。合并后仍必须重新生成 queue 并运行 validator。

该 JSON 的 scope 是 external_oracle_collection_queue。当前目标集可以出现 external_verified 与 ready_for_calibration 已闭合的状态，但 production_tuning_allowed 仍保持 false；这表示只能把外部黑盒目标值作为审计证据，不能直接用这些样本做 Dasha/Shadbala 生产调参。

Ashtakoot 外部合婚 oracle 使用同一个队列生成器，但独立样本文件是 references/oracle/ashtakoot_oracle_cases.json：

python3 scripts/oracle_collection_queue.py \
  --oracle-file references/oracle/ashtakoot_oracle_cases.json \
  --format json

该队列同样保持 ready_for_calibration: 0，用于采集 ashtakoot_36_point 外部合婚目标值，而不是重写现有 scripts/ashtakoot.py 算法。每条样本要补齐 target.total_score、target.varna、target.vashya、target.tara、target.yoni、target.graha_maitri、target.gana、target.bhakoot、target.nadi、target.kuja_status，并保留 JHora/VedAstro/AstroSage 等外部截图或 API artifact。

每个队列任务还包含 evidence_packet.capture_id 草稿证据包。人工或副手录入外部真值时，必须至少填写 tool_name、tool_version_or_url、capture_date、source_artifact、ayanamsa、node_mode、timezone、operator_note，并保留截图、API 响应或 stdout 等外部 artifact；不得把本仓库本地计算输出当作 source_artifact。

外部截图和 stdout 片段统一存入 references/oracle/artifacts/，证据包里的 source_artifact 必须使用该目录下的 repo-relative 路径或明确标注的外部审阅位置。所有私人截图必须打码；不得提交私人 PDF 原件、不得提交完整出生报告，也不得提交浏览器 scratch 目录或含账号会话/cookie/token/桌面通知的截图。

第一条 JHora/PyJHora 黑盒证据采集按 docs/user_jhora_capture_guide.md 执行：优先使用 Steve Jobs 或合成样本，采集 Moon sidereal longitude、Vimshottari start date 与 Shadbala 七曜六分量，保存到 references/oracle/artifacts/ 后再运行 evidence validator。

外部目标字段采用 target_fields + target_placeholders 双层结构：target_fields 固定记录该案例需要校验的目标，例如 target.moon_sidereal_longitude_deg、target.vimshottari_start_date、target.shadbala_components；当这些字段被真实外部来源填入并且证据包状态升为 external_verified 后，队列生成器会保留这些值，不会再把它们降级成 draft。这保证了“人工/JHora/PyJHora/VedAstro 采集 → JSON 填写 → 队列生成 → validator 复核”的路径可复验。

当外部证据包被填写回队列 JSON 后，用证据验证器做第二层防线：

python3 scripts/oracle_evidence_validator.py \
  --queue-file /path/to/filled_external_oracle_collection_queue.json

该验证器输出 external_oracle_evidence_validation，会检查 evidence_packet 必填元数据、target_placeholders 是否已填、是否覆盖 target_fields、是否包含外部 artifact，以及是否错误使用本仓库本地引擎输出。只有状态为 external_verified 且证据完整的包才会进入可复核状态；通过 validator 不等于允许生产调参。

证据包通过 validator 之后，再运行边界差异审计，比较本地引擎与外部 Dasha/Shadbala 目标值：

python3 scripts/oracle_boundary_audit.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json

审计报告中的 template_comparisons 会列出 external-verified template 的 Dasha 起点差异、Shadbala 七曜分量/总分差异、每个分量的 Rupa 容差、单位说明和 global_scaling_check.recommendation: reject_global_scaling，并继续保持 production_tuning_recommended: false，防止用单个样本或全局倍率调生产常数。

公开 benchmark 看板用于长期展示能力状态、oracle readiness 和“是否可宣称全球第一”的诚实边界：

python3 scripts/public_benchmark_dashboard.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/public_jyotish_benchmark_dashboard.md

当前看板固定输出 can_claim_global_first: false，直到外部 oracle 样本、差异审计和长期公开 benchmark 都达到生产调参标准。

外部 oracle 总控 closure 看板会合并 Dasha、Shadbala 与 Tajika/Sahams 三条硬闭环战线，给出总任务数、已验证数、第一优先级和下一条执行命令：

python3 scripts/oracle_closure_master_dashboard.py \
  --dasha-oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --tajika-oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/jyotish_external_oracle_closure_master_dashboard.md

当前总控看板输出 total_tasks: 12、external_verified_tasks: 12、can_claim_current_target_set_closure: true，但 can_claim_global_oracle_closure: false 与 production_tuning_allowed: false 仍保持锁定。含义是当前目标集已闭合，不能夸大成全球 oracle、预测准确率或生产调参闭环。

Dasha 外部 oracle 最短闭环状态板用于把“大运外部真值”从 Shadbala 绝对值大包中拆出来，优先推进第一条可验证边界日期：

python3 scripts/dasha_oracle_closure_status.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/dasha_external_oracle_closure_status.md

当前第一优先级是 external_template_steve_jobs_dasha_lahiri。该状态板只要求 target.vimshottari_start_date 和外部证据 metadata，不要求同时填完 Shadbala 七曜六分量；这样可以先完成 Dasha oracle 的第一条闭环，再单独推进 Shadbala 绝对值闭环。

第一条外部证据包的交互辅助命令：

python3 scripts/first_oracle_packet_assistant.py \
  --front dasha \
  --format markdown \
  --output docs/benchmark/first_dasha_oracle_packet_assistant.md

同一个助手也支持：

python3 scripts/first_oracle_packet_assistant.py --front tajika_sahams --format markdown --output docs/benchmark/first_tajika_oracle_packet_assistant.md
python3 scripts/first_oracle_packet_assistant.py --front shadbala --format markdown --output docs/benchmark/first_shadbala_oracle_packet_assistant.md

该助手不会生成或猜测 JHora/PyJHora 真值，只会列出当前 packet 还缺哪些字段、可用外部来源、apply 命令和 validator 命令。

如需先看三条硬闭环 front 的统一排序入口，而不是分别运行三个助手：

python3 scripts/oracle_packet_assistant_index.py \
  --format markdown \
  --output docs/benchmark/first_oracle_packet_assistant_index.md

该索引会固定列出 dasha、tajika_sahams、shadbala 三条 front 的首包 case、缺失字段数、operator card 与推荐执行顺序，方便直接判断当前最短闭环路径。

Shadbala 外部绝对值闭环使用独立状态板，专门追踪七曜的六分量与总 Rupa：

python3 scripts/shadbala_oracle_closure_status.py \
  --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/shadbala_external_absolute_value_closure_status.md

当前第一优先级是 external_template_synthetic_north_china_shadbala_raman。除了同一 oracle 行里的 target.moon_sidereal_longitude_deg，还必须填写 Sun/Moon/Mars/Mercury/Jupiter/Venus/Saturn 的 sthana、dig、kala、chesta、naisargika、drik、total_rupa；验证器会检查分量和总分，不允许用一个全局倍率把本地输出硬缩放成外部值。

Tajika/Sahams 年运系统使用独立的外部 oracle 队列，专门追踪 Varshaphala、太阳回归、Muntha、Year Lord、Mudda Dasha、Sahams 与 Tajika Yogas 的外部验证状态：

python3 scripts/tajika_annual_oracle_queue.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --format markdown

公开年运看板可这样生成：

python3 scripts/tajika_annual_benchmark_dashboard.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/tajika_sahams_annual_benchmark_dashboard.md

当前 Tajika/Sahams 看板固定输出 can_claim_tajika_sahams_closure: false：本地 skill 已有年运计算与解释骨架，但太阳回归精确时刻、Varsha Lagna、Muntha、Mudda Dasha、Punya/Rajya/Vivah Saham 和 Tajika Yogas 仍需 JHora/PyJHora/书例级外部证据后，才能宣称年运闭环。

年运第一条最短闭环状态板：

python3 scripts/tajika_annual_closure_status.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --format markdown \
  --output docs/benchmark/tajika_sahams_annual_closure_status.md

如需导出可填写的年运证据包：

python3 scripts/tajika_annual_oracle_queue.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --write-packet-dir references/oracle/artifacts/pending_packets \
  --format json

填完 external_template_steve_jobs_varshaphala_1984_lahiri.json 后，可合并回年运 oracle：

python3 scripts/tajika_annual_oracle_queue.py \
  --oracle-file references/oracle/tajika_annual_oracle_cases.json \
  --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_varshaphala_1984_lahiri.json \
  --format json

full-reading 也会输出 ai_prompt_pack：这是给网页/app、skill 或后端 AI 代理使用的结构化 Prompt/RAG 上下文包。它不会硬编码断语，而是携带 D1/D9/Dasha/Shadbala/Ashtakavarga 的证据快照、推荐检索文档和边界提示，要求大模型基于计算证据交叉验证，避免单一配置下结论。