enterprise-agent-designer 0.34.1

package/skills/design-enterprise-agent/scripts/finalize_agent_delivery.py

@@ -0,0 +1,748 @@
+#!/usr/bin/env python3
+"""Validate and package a designed Agent as portable UTF-8 source assets.
+
+This tool checks deterministic delivery facts only. It does not score professional
+design, prompt quality, model behavior, platform assembly, or business value.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+import zipfile
+from pathlib import Path
+from urllib.parse import unquote
+
+MARKDOWN_LINK = re.compile(r"(?<!!)\[[^\]]+\]\(([^)]+)\)")
+DECLARED_SKILL = re.compile(r"(?<![\w.-])(skills/[A-Za-z0-9._-]+/SKILL\.md)")
+SKILL_NAME = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+DYNAMIC_README_STATUS = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?(?:package_status|handoff_status|"
+    r"source_review_status|grounding_review_status)\s*[:：]"
+)
+DYNAMIC_GATE_STATUS = re.compile(
+    r"(?im)^\s*(?:[-*]\s*)?(?:source-gate|grounding-gate)\s*[:：]\s*"
+    r"(?:pass|通过|失败|未运行|not[-_ ]?run|pending|revision_required)"
+)
+REVIEW_RECEIPT_FIELDS = {
+    "review_mode",
+    "review_scope",
+    "review_round",
+    "verdict",
+    "lowest_failed_layer",
+    "decisive_reason",
+    "evidence",
+    "preserve",
+    "return_to",
+    "next_action",
+    "change_condition",
+    "reviewed_snapshot_id",
+    "grounding_audit",
+    "source_audit",
+    "materiality_audit",
+    "authority_audit",
+}
+SOURCE_AUDIT_FIELDS = {
+    "normal_case_replay",
+    "highest_risk_case_replay",
+    "finding_classification_consistent",
+    "unsupported_scope_expansion_found",
+    "skill_dependency_closure",
+}
+MATERIALITY_AUDIT_FIELDS = {
+    "overall_goal",
+    "consumer_decision",
+    "first_release_boundary",
+    "material_blocker_found",
+    "material_effect",
+    "same_failure_family_scope",
+    "deferred_non_blocking",
+    "late_round_blocking_justification",
+}
+LATE_ROUND_BLOCKING_JUSTIFICATIONS = {
+    "not_applicable",
+    "new-independent-failure-class",
+    "material-same-family-missed-instance",
+    "patch-introduced-failure",
+    "previously-unobservable-failure",
+}
+LOWEST_FAILED_LAYERS = {
+    "requirements",
+    "professional-task",
+    "role",
+    "principles",
+    "skill-topology",
+    "tool-knowledge",
+    "output-handoff",
+    "trace-runtime",
+    "none",
+}
+RETURN_TARGETS = {
+    "grilling",
+    "grill-with-docs",
+    "design-enterprise-agent",
+    "delivery-finalizer",
+    "user",
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Validate source assets and optionally create a portable UTF-8 ZIP."
+    )
+    parser.add_argument("target_root", type=Path, help="Root directory of the delivered Agent")
+    parser.add_argument(
+        "--entry", default="SYSTEM_PROMPT.md", help="Entrypoint relative to target_root"
+    )
+    parser.add_argument(
+        "--input-material",
+        action="append",
+        default=[],
+        type=Path,
+        help="Input artifact path; repeat to ensure it was not reused as the output entry",
+    )
+    parser.add_argument(
+        "--output-zip",
+        type=Path,
+        help="Create this ZIP after source validation, then reopen and verify it",
+    )
+    parser.add_argument(
+        "--prepare-source-review",
+        type=Path,
+        metavar="MANIFEST",
+        help="Validate and freeze the current source into an external review manifest",
+    )
+    parser.add_argument(
+        "--source-review-manifest",
+        type=Path,
+        help="Frozen manifest produced by --prepare-source-review",
+    )
+    parser.add_argument(
+        "--source-review-receipt",
+        type=Path,
+        help="External JSON receipt returned by an isolated source-gate reviewer",
+    )
+    parser.add_argument(
+        "--delivery-receipt",
+        type=Path,
+        help="Write the deterministic packaging receipt to this external JSON path",
+    )
+    parser.add_argument(
+        "--require-evaluation",
+        action="store_true",
+        help="Require actual evaluation artifacts in a conventional or declared path",
+    )
+    parser.add_argument(
+        "--evaluation-path",
+        action="append",
+        default=[],
+        type=Path,
+        help="Evaluation artifact or directory relative to target_root; repeat for custom layouts",
+    )
+    parser.add_argument(
+        "--forbid-evaluation-term",
+        action="append",
+        default=[],
+        help="Literal term explicitly forbidden by the user or authoritative brief in runtime evaluation assets; repeat as needed",
+    )
+    parser.add_argument(
+        "--require-path",
+        action="append",
+        default=[],
+        type=Path,
+        help="Required source file relative to target_root; repeat for committed Skills or contracts",
+    )
+    return parser.parse_args()
+
+
+def is_within(path: Path, root: Path) -> bool:
+    return path == root or root in path.parents
+
+
+def local_target(raw: str) -> str | None:
+    target = raw.strip().strip("<>")
+    if target.startswith(("http://", "https://", "mailto:", "#")):
+        return None
+    target = unquote(target.split("#", 1)[0])
+    return target or None
+
+
+def read_utf8(path: Path, root: Path, errors: list[str]) -> str | None:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        errors.append(f"文件不是有效 UTF-8：{path.relative_to(root)} ({exc})")
+        return None
+
+
+def parse_frontmatter(text: str) -> dict[str, str] | None:
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    try:
+        end = next(index for index, line in enumerate(lines[1:], start=1) if line.strip() == "---")
+    except StopIteration:
+        return None
+
+    values: dict[str, str] = {}
+    for line in lines[1:end]:
+        if not line.strip() or line.lstrip().startswith("#") or ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        values[key.strip()] = value.strip().strip('"\'')
+    return values
+
+
+def validate_skill(path: Path, root: Path, text: str, errors: list[str]) -> None:
+    relative = path.relative_to(root)
+    folder_name = path.parent.name
+    metadata = parse_frontmatter(text)
+    if metadata is None:
+        errors.append(f"Skill 缺少完整 YAML frontmatter：{relative}")
+        return
+
+    name = metadata.get("name", "")
+    description = metadata.get("description", "")
+    if not name:
+        errors.append(f"Skill frontmatter 缺少 name：{relative}")
+    elif not SKILL_NAME.fullmatch(name):
+        errors.append(f"Skill name 必须使用 hyphen-case：{relative} -> {name}")
+    elif folder_name != name:
+        errors.append(f"Skill 文件夹名必须与 name 一致：{relative} -> folder={folder_name}, name={name}")
+    if not description:
+        errors.append(f"Skill frontmatter 缺少 description：{relative}")
+
+
+def discover_evaluations(root: Path, declared: list[Path], errors: list[str]) -> list[Path]:
+    files: list[Path] = []
+    if declared:
+        candidates = [(root / path).resolve() for path in declared]
+    else:
+        candidates = [
+            root / dirname
+            for dirname in ("evaluation", "evaluations", "eval", "evals", "tests", "fixtures")
+            if (root / dirname).exists()
+        ]
+
+    for path in candidates:
+        if root not in path.parents and path != root:
+            errors.append(f"评测路径越出源码根目录：{path}")
+        elif path.is_file() and path.stat().st_size > 0:
+            files.append(path)
+        elif path.is_dir():
+            files.extend(item for item in path.rglob("*") if item.is_file() and item.stat().st_size > 0)
+        else:
+            errors.append(f"评测资产不存在或为空：{path}")
+    return sorted(set(files))
+
+
+def count_evaluation_cases(files: list[Path], root: Path, errors: list[str]) -> int:
+    """Count executable case artifacts without treating README/holdout as tests."""
+    count = 0
+    for path in files:
+        if path.name.lower() == "readme.md":
+            continue
+        if path.suffix.lower() == ".md":
+            text = read_utf8(path, root, errors)
+            if text is not None and "NOT_FOR_RUNTIME_REFERENCE" not in text:
+                count += 1
+            continue
+        if path.suffix.lower() == ".json":
+            text = read_utf8(path, root, errors)
+            if text is None:
+                continue
+            try:
+                payload = json.loads(text)
+            except json.JSONDecodeError as exc:
+                errors.append(f"评测 JSON 无法解析：{path.relative_to(root)} ({exc})")
+                continue
+            if isinstance(payload, dict) and isinstance(payload.get("cases"), list):
+                count += len(payload["cases"])
+            elif isinstance(payload, dict) and (
+                "business_claims" in payload
+                or "load_bearing_facts" in payload
+                or payload.get("registry_scope") == "current_task"
+            ):
+                # Non-behavior support fixtures are not target-model cases.
+                continue
+            elif isinstance(payload, (dict, list)) and payload:
+                count += 1
+            continue
+        count += 1
+    return count
+
+
+def validate_forbidden_evaluation_terms(
+    files: list[Path], root: Path, terms: list[str], errors: list[str]
+) -> None:
+    for path in files:
+        if path.name.lower() == "readme.md":
+            continue
+        text = read_utf8(path, root, errors)
+        if text is None or "NOT_FOR_RUNTIME_REFERENCE" in text:
+            continue
+        for term in terms:
+            if term in text:
+                errors.append(
+                    f"评测资产包含明确禁区词：{path.relative_to(root)} -> {term}"
+                )
+
+
+def normalize_forbidden_evaluation_terms(terms: list[str]) -> list[str]:
+    """Return the single canonical term list used by scanning and snapshot identity."""
+    return sorted({term.strip() for term in terms if term and term.strip()})
+
+
+def source_files(root: Path, output_zip: Path | None) -> list[Path]:
+    excluded = {"Thumbs.db", ".DS_Store"}
+    result: list[Path] = []
+    resolved_zip = output_zip.resolve() if output_zip else None
+    for path in root.rglob("*"):
+        if not path.is_file() or path.name in excluded or "__pycache__" in path.parts:
+            continue
+        if resolved_zip and path.resolve() == resolved_zip:
+            continue
+        result.append(path)
+    return sorted(result)
+
+
+def create_zip(root: Path, output_zip: Path, files: list[Path]) -> None:
+    output_zip.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(output_zip, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for path in files:
+            relative = path.relative_to(root).as_posix()
+            archive.write(path, arcname=f"{root.name}/{relative}")
+
+
+def validate_zip(
+    root: Path,
+    output_zip: Path,
+    files: list[Path],
+    entry: str,
+    errors: list[str],
+) -> None:
+    if not output_zip.is_file():
+        errors.append(f"ZIP 未生成：{output_zip}")
+        return
+
+    expected = {path.relative_to(root).as_posix() for path in files}
+    prefix = f"{root.name}/"
+    try:
+        with zipfile.ZipFile(output_zip) as archive:
+            corrupt = archive.testzip()
+            if corrupt:
+                errors.append(f"ZIP 条目损坏：{corrupt}")
+            items = [item for item in archive.infolist() if not item.is_dir()]
+            actual: set[str] = set()
+            for item in items:
+                normalized = item.filename.replace("\\", "/")
+                if any(ord(char) > 127 for char in normalized) and not (item.flag_bits & 0x800):
+                    errors.append(f"ZIP 非 ASCII 路径未标记 UTF-8：{normalized}")
+                if not normalized.startswith(prefix):
+                    errors.append(f"ZIP 条目不在唯一源码根目录下：{normalized}")
+                    continue
+                relative = normalized[len(prefix) :]
+                actual.add(relative)
+                source = root / relative
+                if source.is_file() and archive.read(item) != source.read_bytes():
+                    errors.append(f"ZIP 内容与源码不一致：{relative}")
+            if expected != actual:
+                missing = sorted(expected - actual)
+                extra = sorted(actual - expected)
+                if missing:
+                    errors.append(f"ZIP 缺少源码文件：{missing}")
+                if extra:
+                    errors.append(f"ZIP 存在源码目录外的额外文件：{extra}")
+            if entry not in actual:
+                errors.append(f"ZIP 中找不到入口：{entry}")
+    except zipfile.BadZipFile as exc:
+        errors.append(f"ZIP 无法读取：{exc}")
+
+
+def validate_readme_status(root: Path, texts: dict[Path, str], errors: list[str]) -> None:
+    readme = root / "README.md"
+    text = texts.get(readme)
+    if text is None:
+        return
+    if DYNAMIC_README_STATUS.search(text) or DYNAMIC_GATE_STATUS.search(text):
+        errors.append(
+            "README 不得保存会在评审／打包后失真的动态门禁或交付状态；"
+            "这些状态只写入外部复审／交付收据"
+        )
+
+
+def build_manifest(
+    root: Path,
+    entry: str,
+    files: list[Path],
+    evaluation_count: int,
+    forbidden_evaluation_terms: list[str],
+) -> dict[str, object]:
+    records: list[dict[str, object]] = []
+    snapshot = hashlib.sha256()
+    for path in files:
+        relative = path.relative_to(root).as_posix()
+        content = path.read_bytes()
+        digest = hashlib.sha256(content).hexdigest()
+        records.append({"path": relative, "bytes": len(content), "sha256": digest})
+        snapshot.update(relative.encode("utf-8"))
+        snapshot.update(b"\0")
+        snapshot.update(digest.encode("ascii"))
+        snapshot.update(b"\0")
+    snapshot.update(b"forbidden_evaluation_terms\0")
+    for term in forbidden_evaluation_terms:
+        snapshot.update(term.encode("utf-8"))
+        snapshot.update(b"\0")
+    return {
+        "manifest_version": "1.2",
+        "target_root": str(root),
+        "entry": entry,
+        "source_snapshot_id": f"sha256:{snapshot.hexdigest()}",
+        "evaluation_count": evaluation_count,
+        "forbidden_evaluation_terms": forbidden_evaluation_terms,
+        "files": records,
+    }
+
+
+def write_json(path: Path, payload: dict[str, object]) -> 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 read_json(path: Path, label: str, errors: list[str]) -> dict[str, object] | None:
+    if not path.is_file():
+        errors.append(f"{label}不存在：{path}")
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        errors.append(f"{label}不是有效 UTF-8 JSON：{path} ({exc})")
+        return None
+    if not isinstance(payload, dict):
+        errors.append(f"{label}必须是 JSON 对象：{path}")
+        return None
+    return payload
+
+
+def validate_review_chain(
+    root: Path,
+    current_manifest: dict[str, object],
+    manifest_path: Path,
+    receipt_path: Path,
+    errors: list[str],
+) -> None:
+    if is_within(manifest_path, root) or is_within(receipt_path, root):
+        errors.append("送审清单与隔离复审收据必须位于目标源码根目录之外")
+        return
+
+    frozen = read_json(manifest_path, "送审清单", errors)
+    receipt = read_json(receipt_path, "隔离 source-gate 收据", errors)
+    if frozen is None or receipt is None:
+        return
+
+    if frozen.get("manifest_version") != "1.2":
+        errors.append("送审清单版本不受支持")
+    if frozen.get("target_root") != str(root):
+        errors.append("送审清单绑定的源码根目录与当前目标不一致")
+    if frozen.get("source_snapshot_id") != current_manifest.get("source_snapshot_id"):
+        errors.append("源码在 source-gate 送审后发生变化；旧复审收据失效")
+    if frozen.get("files") != current_manifest.get("files"):
+        errors.append("当前源码文件集合或内容与送审清单不一致")
+    if frozen.get("forbidden_evaluation_terms") != current_manifest.get(
+        "forbidden_evaluation_terms"
+    ):
+        errors.append("最终打包使用的评测禁区与冻结送审清单不一致")
+
+    missing = REVIEW_RECEIPT_FIELDS - set(receipt)
+    if missing:
+        errors.append(f"隔离 source-gate 收据缺少字段：{sorted(missing)}")
+        return
+    if receipt.get("review_mode") != "source-gate":
+        errors.append("复审收据 review_mode 不是 source-gate")
+    if receipt.get("review_scope") != "isolated-subagent":
+        errors.append("复审收据不是隔离子智能体范围")
+    review_round = receipt.get("review_round")
+    if not isinstance(review_round, int) or isinstance(review_round, bool) or review_round < 1:
+        errors.append("复审收据 review_round 必须是从 1 开始的正整数")
+    if receipt.get("verdict") != "pass":
+        errors.append("source-gate 未通过，禁止打包")
+    if receipt.get("lowest_failed_layer") not in LOWEST_FAILED_LAYERS:
+        errors.append("复审收据 lowest_failed_layer 不在允许枚举中")
+    elif receipt.get("verdict") == "pass" and receipt.get("lowest_failed_layer") != "none":
+        errors.append("source-gate pass 的 lowest_failed_layer 必须为 none")
+    if receipt.get("return_to") not in RETURN_TARGETS:
+        errors.append("复审收据 return_to 不在允许枚举中")
+    elif receipt.get("verdict") == "pass" and receipt.get("return_to") != "delivery-finalizer":
+        errors.append("source-gate pass 必须返回 delivery-finalizer")
+    if receipt.get("reviewed_snapshot_id") != frozen.get("source_snapshot_id"):
+        errors.append("复审收据没有绑定本次冻结源码快照")
+
+    authority = receipt.get("authority_audit")
+    if not isinstance(authority, dict):
+        errors.append("复审收据 authority_audit 必须是对象")
+    else:
+        unresolved = authority.get("unresolved_or_unauthorized")
+        reviewed = authority.get("stable_rules_reviewed")
+        if not isinstance(unresolved, list):
+            errors.append("authority_audit.unresolved_or_unauthorized 必须是数组")
+        elif unresolved:
+            errors.append("source-gate 仍发现无权或未解决的稳定规则，禁止打包")
+        if not isinstance(reviewed, list):
+            errors.append("authority_audit.stable_rules_reviewed 必须是数组")
+
+    source_audit = receipt.get("source_audit")
+    if not isinstance(source_audit, dict):
+        errors.append("source-gate pass 收据缺少 source_audit")
+    else:
+        missing_source_audit = SOURCE_AUDIT_FIELDS - set(source_audit)
+        if missing_source_audit:
+            errors.append(f"source_audit 缺少字段：{sorted(missing_source_audit)}")
+        if source_audit.get("normal_case_replay") != "pass":
+            errors.append("source-gate 未确认正常案例回放通过")
+        if source_audit.get("highest_risk_case_replay") != "pass":
+            errors.append("source-gate 未确认最高风险案例回放通过")
+        if source_audit.get("finding_classification_consistent") is not True:
+            errors.append("source-gate 未确认评测发现分类一致")
+        if source_audit.get("unsupported_scope_expansion_found") is not False:
+            errors.append("source-gate 仍发现或未排除未经依据的范围扩张")
+        if source_audit.get("skill_dependency_closure") != "pass":
+            errors.append("source-gate 未确认 Skill 数据依赖闭合")
+    materiality = receipt.get("materiality_audit")
+    if not isinstance(materiality, dict):
+        errors.append("source-gate pass 收据缺少 materiality_audit")
+    else:
+        missing_materiality = MATERIALITY_AUDIT_FIELDS - set(materiality)
+        if missing_materiality:
+            errors.append(f"materiality_audit 缺少字段：{sorted(missing_materiality)}")
+        if materiality.get("material_blocker_found") is not False:
+            errors.append("source-gate pass 仍声明存在 material blocker")
+        for name in (
+            "overall_goal",
+            "consumer_decision",
+            "first_release_boundary",
+            "material_effect",
+        ):
+            if not isinstance(materiality.get(name), str) or not str(
+                materiality.get(name)
+            ).strip():
+                errors.append(f"materiality_audit.{name} 必须是非空字符串")
+        for name in ("same_failure_family_scope", "deferred_non_blocking"):
+            if not isinstance(materiality.get(name), list):
+                errors.append(f"materiality_audit.{name} 必须是数组")
+        if materiality.get("late_round_blocking_justification") not in LATE_ROUND_BLOCKING_JUSTIFICATIONS:
+            errors.append(
+                "materiality_audit.late_round_blocking_justification 不在允许枚举中"
+            )
+        elif materiality.get("late_round_blocking_justification") != "not_applicable":
+            errors.append(
+                "source-gate pass 的 late_round_blocking_justification 必须为 not_applicable"
+            )
+
+
+def main() -> int:
+    args = parse_args()
+    root = args.target_root.resolve()
+    errors: list[str] = []
+    if args.prepare_source_review and args.output_zip:
+        errors.append("--prepare-source-review 与 --output-zip 不能在同一次调用中使用")
+    if args.output_zip and not (args.source_review_manifest and args.source_review_receipt):
+        errors.append("生成最终 ZIP 必须同时提供冻结送审清单和隔离 source-gate 收据")
+    if args.delivery_receipt and not args.output_zip:
+        errors.append("--delivery-receipt 只可与 --output-zip 一起使用")
+    if not root.is_dir():
+        return report([f"目标源码根目录不存在：{root}"])
+
+    output_zip = args.output_zip.resolve() if args.output_zip else None
+    entry = (root / args.entry).resolve()
+    if not entry.is_file() or root not in entry.parents:
+        errors.append(f"独立入口不存在或越出源码根目录：{args.entry}")
+
+    inputs = {path.resolve() for path in args.input_material}
+    if entry in inputs or root in inputs:
+        errors.append("目标入口／源码根目录与输入材料是同一对象")
+
+    markdown_files = sorted(root.rglob("*.md"))
+    if not markdown_files:
+        errors.append("目标目录没有 Markdown 源码")
+
+    texts: dict[Path, str] = {}
+    for path in markdown_files:
+        text = read_utf8(path, root, errors)
+        if text is not None:
+            texts[path] = text
+
+    for path, text in texts.items():
+        for raw in MARKDOWN_LINK.findall(text):
+            target = local_target(raw)
+            if target is None:
+                continue
+            resolved = (path.parent / target).resolve()
+            if root not in resolved.parents and resolved != root:
+                errors.append(f"相对引用越出源码根目录：{path.relative_to(root)} -> {target}")
+            elif not resolved.exists():
+                errors.append(f"相对引用不存在：{path.relative_to(root)} -> {target}")
+
+        for declared in DECLARED_SKILL.findall(text.replace("\\", "/")):
+            skill_path = (root / declared).resolve()
+            if not skill_path.is_file():
+                errors.append(f"声明的 Skill 不存在：{path.relative_to(root)} -> {declared}")
+
+    validate_readme_status(root, texts, errors)
+
+    skill_files = sorted(root.glob("skills/*/SKILL.md"))
+    if (root / "skills").is_dir() and not skill_files:
+        errors.append("skills 目录存在但没有可装载的 skills/<name>/SKILL.md")
+    for path in skill_files:
+        text = texts.get(path)
+        if text is not None:
+            validate_skill(path, root, text, errors)
+
+    for relative in args.require_path:
+        path = (root / relative).resolve()
+        if root not in path.parents:
+            errors.append(f"必需资产越出源码根目录：{relative}")
+        elif not path.is_file() or path.stat().st_size == 0:
+            errors.append(f"必需资产不存在或为空：{relative}")
+
+    forbidden_evaluation_terms = normalize_forbidden_evaluation_terms(
+        args.forbid_evaluation_term
+    )
+    evaluation_count = 0
+    if args.require_evaluation:
+        evaluation_files = discover_evaluations(root, args.evaluation_path, errors)
+        evaluation_count = count_evaluation_cases(evaluation_files, root, errors)
+        validate_forbidden_evaluation_terms(
+            evaluation_files, root, forbidden_evaluation_terms, errors
+        )
+        if evaluation_count < 2:
+            errors.append("完整 Agent 至少需要一个正常任务和一个最高风险压力事件评测资产")
+
+    files = source_files(root, output_zip)
+    if errors:
+        return report(errors)
+
+    current_manifest = build_manifest(
+        root,
+        args.entry,
+        files,
+        evaluation_count,
+        forbidden_evaluation_terms,
+    )
+
+    if args.prepare_source_review:
+        manifest_path = args.prepare_source_review.resolve()
+        if is_within(manifest_path, root):
+            return report(["送审清单必须写在目标源码根目录之外"])
+        write_json(manifest_path, current_manifest)
+        return report(
+            [], root=root, file_count=len(files), skill_count=len(skill_files),
+            evaluation_count=evaluation_count, output_zip=None,
+            prepared_manifest=manifest_path,
+            snapshot_id=str(current_manifest["source_snapshot_id"]),
+        )
+
+    if output_zip:
+        validate_review_chain(
+            root,
+            current_manifest,
+            args.source_review_manifest.resolve(),
+            args.source_review_receipt.resolve(),
+            errors,
+        )
+        if errors:
+            return report(errors)
+        create_zip(root, output_zip, files)
+        validate_zip(root, output_zip, files, args.entry, errors)
+        if errors:
+            return report(errors)
+        delivery_receipt = args.delivery_receipt.resolve() if args.delivery_receipt else None
+        if delivery_receipt:
+            if is_within(delivery_receipt, root):
+                return report(["交付收据必须写在目标源码根目录之外"])
+            write_json(
+                delivery_receipt,
+                {
+                    "receipt_version": "1.0",
+                    "package_status": "packaged_verified",
+                    "handoff_status": "ready_for_handoff",
+                    "target_root": str(root),
+                    "source_snapshot_id": current_manifest["source_snapshot_id"],
+                    "source_files": len(files),
+                    "skills": len(skill_files),
+                    "evaluation_cases": evaluation_count,
+                    "forbidden_evaluation_terms": current_manifest[
+                        "forbidden_evaluation_terms"
+                    ],
+                    "output_zip": str(output_zip),
+                },
+            )
+        return report(
+            [], root=root, file_count=len(files), skill_count=len(skill_files),
+            evaluation_count=evaluation_count, output_zip=output_zip,
+            snapshot_id=str(current_manifest["source_snapshot_id"]),
+            delivery_receipt=delivery_receipt,
+        )
+
+    return report(
+        [], root=root, file_count=len(files), skill_count=len(skill_files),
+        evaluation_count=evaluation_count, output_zip=None,
+    )
+
+
+def report(
+    errors: list[str],
+    root: Path | None = None,
+    file_count: int = 0,
+    skill_count: int = 0,
+    evaluation_count: int = 0,
+    output_zip: Path | None = None,
+    prepared_manifest: Path | None = None,
+    snapshot_id: str | None = None,
+    delivery_receipt: Path | None = None,
+) -> int:
+    if errors:
+        print(f"DELIVERY_FAIL：{len(errors)} 个确定性资产问题")
+        for error in errors:
+            print(f"- {error}")
+        print("source_status=written_unverified")
+        print("说明：该结果不评价职业设计、模型行为、平台装配或业务效果。")
+        return 1
+
+    if prepared_manifest:
+        print("SOURCE_REVIEW_PREPARED：源码已校验并冻结为送审快照")
+        print("source_review_status=prepared")
+        print(f"source_review_manifest={prepared_manifest}")
+        print(f"source_snapshot_id={snapshot_id}")
+    elif output_zip:
+        print("DELIVERY_PASS：源码校验、Skill 可装载性、UTF-8 打包和 ZIP 回读通过")
+        print("package_status=packaged_verified")
+        print("handoff_status=ready_for_handoff")
+        print(f"output_zip={output_zip}")
+        print(f"source_snapshot_id={snapshot_id}")
+        if delivery_receipt:
+            print(f"delivery_receipt={delivery_receipt}")
+    else:
+        print("SOURCE_PASS：源码与 Skill 可装载性检查通过，未生成 ZIP")
+        print("source_status=source_verified")
+    if root:
+        print(f"target_root={root}")
+    print(f"source_files={file_count}")
+    print(f"skills={skill_count}")
+    print(f"evaluation_cases={evaluation_count}")
+    if prepared_manifest:
+        print("说明：该结果只证明源码送审快照已生成，不表示 source-gate 已通过或 ZIP 已打包。")
+    elif output_zip:
+        print("说明：该收据只证明确定性资产事实和 ZIP 已准备交接；最终回答可以提供此处验证的可访问路径，但不得把收据改写为 complete。它不评价职业设计、模型行为、平台装配或业务效果。")
+    else:
+        print("说明：该结果只证明源码结构事实，未生成 ZIP；不评价职业设计、模型行为、平台装配或业务效果。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())