feat(oracle): add first packet blank kit

2026-06-26 19:19:57 +08:00
parent e88d8a754a
commit 9232f0e140
3 changed files with 218 additions and 0 deletions
@@ -154,6 +154,15 @@ python3 scripts/prepare_oracle_capture_packets.py \

 该命令会生成 `capture_manifest.json`、`OPERATOR_NEXT_STEPS.md` 和 5 个 `external_*.json`，并在输出中确认 draft 队列仍是 `valid_packets: 0` / `ready_for_calibration: 0`。

+如果只想优先准备当前最短闭环链路的三条首包，而不是一次性导出整批 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
@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Generate a practical blank kit for the first external-oracle packets."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT / "scripts") not in sys.path:
+    sys.path.insert(0, str(ROOT / "scripts"))
+
+from first_oracle_packet_assistant import build_report  # noqa: E402
+
+
+FRONTS = ["dasha", "tajika_sahams", "shadbala"]
+
+
+def _load_json(path: str) -> dict[str, Any]:
+    return json.loads((ROOT / path).read_text(encoding="utf-8"))
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def _write_next_steps(path: Path, manifest: dict[str, Any]) -> None:
+    lines = [
+        "# Blank Oracle Kit Next Steps",
+        "",
+        "This kit prepares the current shortest external-oracle closure path.",
+        "",
+        "不得把本仓库本地输出当作 external oracle。",
+        "",
+        "## Recommended Order",
+        "",
+    ]
+    for front in manifest["recommended_front_order"]:
+        item = manifest["fronts"][front]
+        lines.extend(
+            [
+                f"### {front}",
+                "",
+                f"- case_id: `{item['case_id']}`",
+                f"- packet: `{item['packet_path']}`",
+                f"- missing_field_count: `{item['missing_field_count']}`",
+                f"- operator_card: `{item['operator_card']}`",
+                f"- metadata_missing: `{item['missing_groups']['metadata']['count']}`",
+                f"- target_missing: `{item['missing_groups']['target']['count']}`",
+                "",
+            ]
+        )
+        if item["missing_groups"]["bodies"]:
+            lines.append("Body breakdown:")
+            lines.append("")
+            for body, payload in item["missing_groups"]["bodies"].items():
+                lines.append(f"- {body}: `{payload['count']}`")
+            lines.append("")
+        lines.extend(
+            [
+                "Apply after filling:",
+                "",
+                "```bash",
+                item["apply_command"],
+                "```",
+                "",
+                "Validate after applying:",
+                "",
+                "```bash",
+                item["validate_command"],
+                "```",
+                "",
+            ]
+        )
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def generate_blank_oracle_kit(output_dir: str) -> dict[str, Any]:
+    output_path = Path(output_dir)
+    if not output_path.is_absolute():
+        output_path = ROOT / output_path
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    fronts: dict[str, Any] = {}
+    for front in FRONTS:
+        report = build_report(front)
+        packet = _load_json(report["packet_template"])
+        front_dir = output_path / front
+        packet_path = front_dir / f"{report['capture_id']}.json"
+        _write_json(packet_path, packet)
+        fronts[front] = {
+            "case_id": report["case_id"],
+            "capture_id": report["capture_id"],
+            "packet_path": str(packet_path),
+            "operator_card": report["operator_card"],
+            "missing_field_count": len(report["missing_fields"]),
+            "missing_groups": report["missing_groups"],
+            "apply_command": report["apply_command"],
+            "validate_command": report["validate_command"],
+        }
+
+    recommended_front_order = sorted(FRONTS, key=lambda front: fronts[front]["missing_field_count"])
+    manifest = {
+        "scope": "first_oracle_blank_kit_manifest",
+        "front_count": len(FRONTS),
+        "recommended_front_order": recommended_front_order,
+        "fronts": fronts,
+        "boundary": (
+            "These packets are blank external-oracle drafts only. They must be filled from JHora, PyJHora, "
+            "VedAstro, or documented printed examples, never from this repository's local engine output."
+        ),
+    }
+    manifest_path = output_path / "blank_oracle_kit_manifest.json"
+    _write_json(manifest_path, manifest)
+    next_steps_path = output_path / "BLANK_ORACLE_KIT_NEXT_STEPS.md"
+    _write_next_steps(next_steps_path, manifest)
+    return {
+        "scope": "first_oracle_blank_kit",
+        "front_count": len(FRONTS),
+        "recommended_front_order": recommended_front_order,
+        "manifest": str(manifest_path),
+        "next_steps": str(next_steps_path),
+        "fronts": {front: fronts[front]["packet_path"] for front in FRONTS},
+    }
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Generate the first external-oracle blank kit")
+    parser.add_argument("--output-dir", required=True)
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    report = generate_blank_oracle_kit(args.output_dir)
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Tests for generating the unified first-packet oracle kit."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_generate_blank_oracle_writes_first_packet_kit(tmp_path: Path) -> None:
+    completed = subprocess.run(
+        [
+            sys.executable,
+            "scripts/generate_blank_oracle.py",
+            "--output-dir",
+            str(tmp_path),
+        ],
+        cwd=ROOT,
+        text=True,
+        capture_output=True,
+        timeout=60,
+        check=False,
+    )
+
+    assert completed.returncode == 0, completed.stderr or completed.stdout
+    report = json.loads(completed.stdout)
+    assert report["scope"] == "first_oracle_blank_kit"
+    assert report["front_count"] == 3
+    assert report["recommended_front_order"] == ["dasha", "tajika_sahams", "shadbala"]
+
+    manifest = tmp_path / "blank_oracle_kit_manifest.json"
+    checklist = tmp_path / "BLANK_ORACLE_KIT_NEXT_STEPS.md"
+    assert manifest.exists()
+    assert checklist.exists()
+
+    manifest_data = json.loads(manifest.read_text(encoding="utf-8"))
+    assert manifest_data["scope"] == "first_oracle_blank_kit_manifest"
+    assert manifest_data["front_count"] == 3
+    assert manifest_data["fronts"]["dasha"]["missing_field_count"] == 6
+    assert manifest_data["fronts"]["tajika_sahams"]["missing_field_count"] == 15
+    assert manifest_data["fronts"]["shadbala"]["missing_field_count"] == 55
+
+    dasha_packet = tmp_path / "dasha" / "external_template_steve_jobs_dasha_lahiri.json"
+    tajika_packet = tmp_path / "tajika_sahams" / "external_template_steve_jobs_varshaphala_1984_lahiri.json"
+    shadbala_packet = tmp_path / "shadbala" / "external_template_redacted_place_shadbala_raman.json"
+    assert dasha_packet.exists()
+    assert tajika_packet.exists()
+    assert shadbala_packet.exists()
+
+    dasha_data = json.loads(dasha_packet.read_text(encoding="utf-8"))
+    assert dasha_data["status"] == "draft"
+    assert dasha_data["target_placeholders"]["target.vimshottari_start_date"] is None
+
+    guide = checklist.read_text(encoding="utf-8")
+    assert "dasha" in guide
+    assert "tajika_sahams" in guide
+    assert "shadbala" in guide
+    assert "不得把本仓库本地输出当作 external oracle" in guide