Jesse_Chen
8db71aaf81
- README.md is now the product/repo front door (architecture, repo map, local dev, test tiers, delivery flow, doc map). Engine positioning, VedAstro/Codex setup and the oracle/benchmark command reference move verbatim to docs/engine/README.md, docs/engine/vedastro-gateway.md and docs/benchmark/README.md. Capability badges realigned with the registry (91/78/8/0); tests/test_readme_badges.py was red on staging. - AGENTS.md: Part A (environment truth, delivery, worktrees, record placement, bug workflow, growth freeze, frontend red lines, privacy, pre-work check, test tiers) and Part B (reading-rigor constraints). GitHub issue-tracker/triage boilerplate removed: GitHub is a read-only mirror. All strings locked by tests/ are preserved. - CLAUDE.md added: roles, three working modes, task-brief sections, acceptance criteria, session discipline; imports AGENTS.md. - 50 tracked TASK-*/PROGRESS-* files and 3 never-committed briefs move to docs/tasks/ with an index; REPO_LAYOUT.md merged into README. Docs-only change (no gated path touched). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0193vBv6w5MV2cifdTUu9H5P
261 lines
15 KiB
Markdown
261 lines
15 KiB
Markdown
# 准确率基线、外部 Oracle 闭环与 Benchmark 看板
|
||
|
||
> 本文从根 README 拆出（2026-09-03），内容原样保留。这里是所有"本机现在能跑什么、哪些指标可测、哪些能力还缺外部 oracle 证据"的命令入口；看板产物就在本目录。所有看板固定输出 `can_claim_global_first: false` 与 `production_tuning_allowed: false`，直到外部样本达到生产调参标准。
|
||
|
||
### 真实案例复验与准确率边界
|
||
|
||
一条命令查看本机当前技能覆盖与准确率基线：
|
||
|
||
```bash
|
||
python3 scripts/local_accuracy_report.py --format markdown
|
||
```
|
||
|
||
如需给副手、CI 或后续自动化读取，使用 JSON：
|
||
|
||
```bash
|
||
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 参考差异审计，而不是直接改生产常数：
|
||
|
||
```bash
|
||
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 的校准状态：
|
||
|
||
```bash
|
||
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 总控命令：
|
||
|
||
```bash
|
||
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。
|
||
|
||
外部真值采集队列用于把缺失目标值拆成可执行任务，而不是直接调生产参数：
|
||
|
||
```bash
|
||
python3 scripts/oracle_collection_queue.py \
|
||
--oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
|
||
--format markdown
|
||
```
|
||
|
||
如需给自动化或副手读取，可改用 JSON 输出：
|
||
|
||
```bash
|
||
python3 scripts/oracle_collection_queue.py \
|
||
--oracle-file references/oracle/dasha_shadbala_oracle_cases.json \
|
||
--format json
|
||
```
|
||
|
||
如需让真人或 Antigravity AI 副手直接填写证据包，可一次性导出每个 case 的 draft JSON：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
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 文件：
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```bash
|
||
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 后，用证据验证器做第二层防线：
|
||
|
||
```bash
|
||
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 目标值：
|
||
|
||
```bash
|
||
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 和“是否可宣称全球第一”的诚实边界：
|
||
|
||
```bash
|
||
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 三条硬闭环战线，给出总任务数、已验证数、第一优先级和下一条执行命令：
|
||
|
||
```bash
|
||
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 绝对值大包中拆出来，优先推进第一条可验证边界日期：
|
||
|
||
```bash
|
||
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 绝对值闭环。
|
||
|
||
第一条外部证据包的交互辅助命令：
|
||
|
||
```bash
|
||
python3 scripts/first_oracle_packet_assistant.py \
|
||
--front dasha \
|
||
--format markdown \
|
||
--output docs/benchmark/first_dasha_oracle_packet_assistant.md
|
||
```
|
||
|
||
同一个助手也支持：
|
||
|
||
```bash
|
||
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 的统一排序入口，而不是分别运行三个助手：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
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 的外部验证状态：
|
||
|
||
```bash
|
||
python3 scripts/tajika_annual_oracle_queue.py \
|
||
--oracle-file references/oracle/tajika_annual_oracle_cases.json \
|
||
--format markdown
|
||
```
|
||
|
||
公开年运看板可这样生成：
|
||
|
||
```bash
|
||
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/书例级外部证据后，才能宣称年运闭环。
|
||
|
||
年运第一条最短闭环状态板：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
如需导出可填写的年运证据包：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
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 的证据快照、推荐检索文档和边界提示，要求大模型基于计算证据交叉验证，避免单一配置下结论。
|