From 9232f0e1403ca8c2b0c4788e315a0b7eb1de9c0e Mon Sep 17 00:00:00 2001 From: 732642856 <732642856@qq.com> Date: Fri, 26 Jun 2026 19:19:57 +0800 Subject: [PATCH] feat(oracle): add first packet blank kit --- README.md | 9 ++ scripts/generate_blank_oracle.py | 146 ++++++++++++++++++++++++++++ tests/test_generate_blank_oracle.py | 63 ++++++++++++ 3 files changed, 218 insertions(+) create mode 100644 scripts/generate_blank_oracle.py create mode 100644 tests/test_generate_blank_oracle.py diff --git a/README.md b/README.md index 5ca6cc18..88b41d3a 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/scripts/generate_blank_oracle.py b/scripts/generate_blank_oracle.py new file mode 100644 index 00000000..0a3efe1f --- /dev/null +++ b/scripts/generate_blank_oracle.py @@ -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()) diff --git a/tests/test_generate_blank_oracle.py b/tests/test_generate_blank_oracle.py new file mode 100644 index 00000000..35f1e257 --- /dev/null +++ b/tests/test_generate_blank_oracle.py @@ -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