@kernaut/kernaut-resources 0.1.17-beta.1 → 0.1.18

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/agent/kernaut-experience-ledger/scripts/ledger_tools.py

@@ -1,1540 +0,0 @@
-#!/usr/bin/env python3
-"""Deterministic post-processing for Kernaut experience ledgers."""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import re
-import sys
-from collections import Counter, defaultdict
-from pathlib import Path
-from typing import Any, Iterable
-
-
-ATTEMPT_ARTIFACT_TYPE = "kernaut_attempt_v1"
-LEDGER_ARTIFACT_TYPE = "kernaut_experience_ledger_v1"
-AGGREGATE_ARTIFACT_TYPE = "kernaut_operator_ledger_v1"
-CANDIDATE_ARTIFACT_TYPE = "kernaut_knowledge_candidate_v1"
-KNOWLEDGE_MATCH_ARTIFACT_TYPE = "kernaut_knowledge_match_v1"
-
-RECORD_TYPES = {"measurement", "lesson", "pitfall", "usage"}
-EVIDENCE_ORIGINS = {"measured", "source-reported", "observed", "inferred"}
-VERIFICATION_STATUSES = {"unverified", "triaged", "reproduced", "retest-blocked", "human-approved"}
-ATTRIBUTION_STATUSES = {"attributed", "unattributed", "incomplete"}
-OUTCOMES = {
-    "worked",
-    "compile_error",
-    "correctness_fail",
-    "no_gain",
-    "regressed",
-    "resource_limit",
-    "env_blocked",
-    "tooling_blocked",
-    "reverted",
-    "incomplete",
-    "unknown",
-}
-TECHNICAL_FAILURES = {"compile_error", "correctness_fail", "no_gain", "regressed", "resource_limit"}
-ADDRESS_KEYS = ("vendor", "language", "operator", "data_type", "hardware")
-MISSING_REASON_KEYS = {"problem", "before", "after", "mechanism", "summary"}
-CONTEXT_KEYS = (
-    "shape_signature",
-    "data_scale",
-    "implementation",
-    "pipeline",
-    "baseline",
-    "environment_fingerprint",
-    "bottleneck_condition",
-)
-CONFIDENCE_ORDER = {
-    "verified": 0,
-    "source-reported": 1,
-    "inferred": 2,
-    "experimental": 3,
-    "unknown": 4,
-}
-CONFIDENCE_LABELS = {
-    "verified": "已复测验证",
-    "source-reported": "原始实测，尚未复测",
-    "inferred": "观察、推断或 Agent 自报",
-    "experimental": "旧版实验性标记",
-    "unknown": "证据状态未知",
-}
-EVIDENCE_CLASS_INFO = {
-    "verified": {
-        "name": "已复测验证",
-        "key": "reproduced_measurement",
-        "evidence_level": "measured",
-    },
-    "source-reported": {
-        "name": "原始实测，尚未复测",
-        "key": "trace_measurement",
-        "evidence_level": "measured",
-    },
-    "inferred": {
-        "name": "观察、推断或 Agent 自报",
-        "key": "observed_or_inferred",
-        "evidence_level": "inferred",
-    },
-    "unknown": {
-        "name": "未知",
-        "key": "unknown",
-        "evidence_level": "unknown",
-    },
-}
-
-
-def load_jsonl(path: Path) -> list[dict[str, Any]]:
-    rows: list[dict[str, Any]] = []
-    with path.open("r", encoding="utf-8") as handle:
-        for line_number, line in enumerate(handle, 1):
-            if not line.strip():
-                continue
-            value = json.loads(line)
-            if not isinstance(value, dict):
-                raise ValueError(f"{path}:{line_number}: row is not an object")
-            rows.append(value)
-    return rows
-
-
-def write_jsonl(path: Path, rows: Iterable[dict[str, Any]]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with path.open("w", encoding="utf-8") as handle:
-        for row in rows:
-            handle.write(json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n")
-
-
-def stable_id(prefix: str, value: Any) -> str:
-    serialized = json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
-    digest = hashlib.sha256(serialized.encode("utf-8")).hexdigest()[:16]
-    return f"{prefix}-{digest}"
-
-
-def non_empty(value: Any) -> bool:
-    return value not in (None, "", [], {})
-
-
-def non_empty_values(value: Any) -> list[str]:
-    values = value if isinstance(value, list) else [value]
-    return [str(item).strip() for item in values if non_empty(item) and str(item).strip()]
-
-
-def address_from_entry(entry: dict[str, Any]) -> dict[str, Any]:
-    context = entry.get("context") if isinstance(entry.get("context"), dict) else {}
-    existing = entry.get("address") if isinstance(entry.get("address"), dict) else {}
-    return {
-        "vendor": existing.get("vendor") or context.get("vendor"),
-        "language": existing.get("language") or context.get("language"),
-        "operator": existing.get("operator") or context.get("operator"),
-        "data_type": existing.get("data_type") or context.get("data_type"),
-        "hardware": existing.get("hardware") or context.get("hardware"),
-    }
-
-
-def context_group_from_entry(entry: dict[str, Any]) -> dict[str, Any]:
-    context = entry.get("context") if isinstance(entry.get("context"), dict) else {}
-    bottleneck = entry.get("bottleneck") if isinstance(entry.get("bottleneck"), dict) else {}
-    environment = context.get("environment")
-    if isinstance(environment, dict):
-        environment_fingerprint = stable_id("env", environment)
-    else:
-        environment_fingerprint = environment
-    return {
-        "shape_signature": context.get("shape_signature") or context.get("shape"),
-        "data_scale": context.get("data_scale"),
-        "implementation": context.get("implementation"),
-        "pipeline": context.get("pipeline"),
-        "baseline": context.get("baseline"),
-        "environment_fingerprint": environment_fingerprint,
-        "bottleneck_condition": bottleneck.get("hypothesis"),
-    }
-
-
-def evidence_confidence(entry: dict[str, Any]) -> tuple[str, int | None, list[dict[str, Any]]]:
-    origin = entry.get("evidence_origin")
-    verification = entry.get("verification_status")
-    measurements = entry.get("measurements") if isinstance(entry.get("measurements"), list) else []
-    breakdown: list[dict[str, Any]] = []
-    if origin == "measured" and measurements and verification == "reproduced":
-        breakdown.append({"reason": "实验室重放已复现", "score": 100})
-        return "verified", 100, breakdown
-    if origin == "measured" and measurements:
-        breakdown.append({"reason": "来自可回链评测输出，但尚未独立复测", "score": 65})
-        return "source-reported", 65, breakdown
-    if origin == "source-reported":
-        breakdown.append({"reason": "只有 Agent 或来源自报，没有直接评测输出", "score": 40})
-        return "inferred", 40, breakdown
-    if origin in {"observed", "inferred"}:
-        breakdown.append({"reason": "非数字观察或原因推断", "score": None})
-        return "inferred", None, breakdown
-    return "unknown", None, [{"reason": "证据来源无法识别", "score": None}]
-
-
-def normalize_entry(entry: dict[str, Any]) -> dict[str, Any]:
-    normalized = dict(entry)
-    address = address_from_entry(entry)
-    context_group = context_group_from_entry(entry)
-    confidence, score, breakdown = evidence_confidence(entry)
-    normalized["address"] = address
-    normalized["address_id"] = stable_id("address", address)
-    normalized["address_complete"] = all(non_empty(address.get(key)) for key in ADDRESS_KEYS)
-    normalized["context_group"] = context_group
-    normalized["context_group_id"] = stable_id("context", {"address": address, **context_group})
-    evidence_class = EVIDENCE_CLASS_INFO[confidence]
-    normalized["evidence_class"] = evidence_class["key"]
-    normalized["evidence_class_name"] = evidence_class["name"]
-    normalized["confidence"] = confidence
-    normalized["evidence_level"] = evidence_class["evidence_level"]
-    normalized["confidence_score"] = score
-    normalized["score_breakdown"] = breakdown
-    normalized.setdefault("attribution_status", "attributed")
-    normalized.setdefault("field_provenance", {})
-    normalized.setdefault("supersedes", [])
-    return normalized
-
-
-def validate_attempts(rows: list[dict[str, Any]]) -> list[str]:
-    errors: list[str] = []
-    seen: set[str] = set()
-    required = {
-        "artifact_type",
-        "attempt_id",
-        "session_id",
-        "source_turns",
-        "base_revision",
-        "diff_digest",
-        "environment_fingerprint",
-        "events",
-        "outcome",
-        "attribution_status",
-        "source_records",
-    }
-    for index, row in enumerate(rows, 1):
-        missing = sorted(required - row.keys())
-        if missing:
-            errors.append(f"line {index}: missing {', '.join(missing)}")
-        if row.get("artifact_type") != ATTEMPT_ARTIFACT_TYPE:
-            errors.append(f"line {index}: invalid artifact_type")
-        attempt_id = row.get("attempt_id")
-        if not isinstance(attempt_id, str) or not attempt_id:
-            errors.append(f"line {index}: attempt_id must be a non-empty string")
-        elif attempt_id in seen:
-            errors.append(f"line {index}: duplicate attempt_id {attempt_id}")
-        else:
-            seen.add(attempt_id)
-        if row.get("outcome") not in OUTCOMES:
-            errors.append(f"line {index}: invalid outcome")
-        if row.get("attribution_status") not in ATTRIBUTION_STATUSES:
-            errors.append(f"line {index}: invalid attribution_status")
-        events = row.get("events")
-        if not isinstance(events, dict):
-            errors.append(f"line {index}: events must be an object")
-        else:
-            for event_type in ("patch", "build", "correctness", "benchmark"):
-                if not isinstance(events.get(event_type), list):
-                    errors.append(f"line {index}: events.{event_type} must be a list")
-        if not isinstance(row.get("source_turns"), list):
-            errors.append(f"line {index}: source_turns must be a list")
-        if not isinstance(row.get("source_records"), list) or not row.get("source_records"):
-            errors.append(f"line {index}: source_records must be a non-empty list")
-    return errors
-
-
-def validate_ledger(rows: list[dict[str, Any]]) -> list[str]:
-    errors: list[str] = []
-    seen: set[str] = set()
-    required = {
-        "artifact_type",
-        "entry_id",
-        "attempt_id",
-        "session_id",
-        "record_type",
-        "evidence_origin",
-        "verification_status",
-        "context",
-        "technique",
-        "observations",
-        "measurements",
-        "bottleneck",
-        "outcome",
-        "scope",
-        "uncertainties",
-        "source_records",
-    }
-    for index, row in enumerate(rows, 1):
-        missing = sorted(required - row.keys())
-        if missing:
-            errors.append(f"line {index}: missing {', '.join(missing)}")
-        if row.get("artifact_type") != LEDGER_ARTIFACT_TYPE:
-            errors.append(f"line {index}: invalid artifact_type")
-        entry_id = row.get("entry_id")
-        if not isinstance(entry_id, str) or not entry_id:
-            errors.append(f"line {index}: entry_id must be a non-empty string")
-        elif entry_id in seen:
-            errors.append(f"line {index}: duplicate entry_id {entry_id}")
-        else:
-            seen.add(entry_id)
-        if row.get("record_type") not in RECORD_TYPES:
-            errors.append(f"line {index}: invalid record_type")
-        if row.get("evidence_origin") not in EVIDENCE_ORIGINS:
-            errors.append(f"line {index}: invalid evidence_origin")
-        if row.get("verification_status") not in VERIFICATION_STATUSES:
-            errors.append(f"line {index}: invalid verification_status")
-        if row.get("outcome") not in OUTCOMES:
-            errors.append(f"line {index}: invalid outcome")
-        if row.get("attribution_status", "attributed") not in ATTRIBUTION_STATUSES:
-            errors.append(f"line {index}: invalid attribution_status")
-        for key in ("context", "technique", "bottleneck"):
-            if not isinstance(row.get(key), dict):
-                errors.append(f"line {index}: {key} must be an object")
-        technique = row.get("technique")
-        if isinstance(technique, dict) and "missing_reasons" in technique:
-            missing_reasons = technique.get("missing_reasons")
-            if not isinstance(missing_reasons, dict):
-                errors.append(f"line {index}: technique.missing_reasons must be an object")
-            else:
-                for key, value in missing_reasons.items():
-                    if key not in MISSING_REASON_KEYS:
-                        errors.append(f"line {index}: invalid technique.missing_reasons key {key}")
-                    if not non_empty_values(value):
-                        errors.append(
-                            f"line {index}: technique.missing_reasons.{key} must contain a non-empty reason"
-                        )
-        for key in ("observations", "measurements", "uncertainties", "source_records"):
-            if not isinstance(row.get(key), list):
-                errors.append(f"line {index}: {key} must be a list")
-        if row.get("evidence_origin") == "measured" and not row.get("measurements"):
-            errors.append(f"line {index}: measured evidence requires measurements")
-    return errors
-
-
-def aggregate_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    normalized = [normalize_entry(row) for row in rows]
-    groups: dict[tuple[str, str, str], list[dict[str, Any]]] = defaultdict(list)
-    for row in normalized:
-        technique = row.get("technique") if isinstance(row.get("technique"), dict) else {}
-        family = str(technique.get("family") or "<unknown>")
-        groups[(row["address_id"], row["context_group_id"], family)].append(row)
-
-    aggregates: list[dict[str, Any]] = []
-    for (_, _, family), entries in sorted(groups.items()):
-        attempts = {str(entry.get("attempt_id")) for entry in entries if entry.get("attribution_status") == "attributed"}
-        worked = {
-            str(entry.get("attempt_id"))
-            for entry in entries
-            if entry.get("outcome") == "worked"
-            and entry.get("confidence") in {"verified", "source-reported"}
-            and entry.get("attribution_status") == "attributed"
-        }
-        failures = {
-            str(entry.get("attempt_id"))
-            for entry in entries
-            if entry.get("outcome") in TECHNICAL_FAILURES
-            and entry.get("confidence") in {"verified", "source-reported"}
-            and entry.get("attribution_status") == "attributed"
-        }
-        outcomes = Counter(str(entry.get("outcome")) for entry in entries)
-        repeated_failure = len(failures) >= 3 and not worked
-        direct_bottleneck = any(
-            non_empty((entry.get("bottleneck") or {}).get("hypothesis"))
-            and bool((entry.get("bottleneck") or {}).get("evidence"))
-            for entry in entries
-        )
-        scoped = any(non_empty(entry.get("scope")) for entry in entries)
-        conflict = bool(worked and failures)
-        confidence_counts = Counter(str(entry.get("confidence")) for entry in entries)
-        best_speedup = max(
-            (
-                float(measurement["speedup_x"])
-                for entry in entries
-                for measurement in entry.get("measurements", [])
-                if isinstance(measurement, dict) and isinstance(measurement.get("speedup_x"), (int, float))
-            ),
-            default=None,
-        )
-        first = entries[0]
-        aggregates.append(
-            {
-                "artifact_type": AGGREGATE_ARTIFACT_TYPE,
-                "aggregate_id": stable_id(
-                    "aggregate",
-                    {
-                        "address_id": first["address_id"],
-                        "context_group_id": first["context_group_id"],
-                        "technique_family": family,
-                    },
-                ),
-                "address": first["address"],
-                "address_id": first["address_id"],
-                "address_complete": first["address_complete"],
-                "context_group": first["context_group"],
-                "context_group_id": first["context_group_id"],
-                "technique_family": family,
-                "entry_ids": sorted(str(entry.get("entry_id")) for entry in entries),
-                "attempt_ids": sorted(attempts),
-                "independent_attempts": len(attempts),
-                "worked_attempts": len(worked),
-                "failed_attempts": len(failures),
-                "outcomes": dict(outcomes),
-                "confidence_counts": dict(confidence_counts),
-                "evidence_classes": {
-                    EVIDENCE_CLASS_INFO[confidence]["key"]: count
-                    for confidence, count in confidence_counts.items()
-                    if confidence in EVIDENCE_CLASS_INFO
-                },
-                "best_speedup_x": best_speedup,
-                "conflict": conflict,
-                "repeated_failure": repeated_failure,
-                "conditional_dead_end_candidate": bool(repeated_failure and direct_bottleneck and scoped and not conflict),
-                "dead_end_blockers": [
-                    reason
-                    for condition, reason in (
-                        (direct_bottleneck, "缺少直接瓶颈证据"),
-                        (scoped, "缺少适用范围"),
-                        (not conflict, "存在有效反例"),
-                    )
-                    if not condition
-                ],
-                "source_records": sorted({source for entry in entries for source in entry.get("source_records", [])}),
-            }
-        )
-    return aggregates
-
-
-def yaml_scalar(value: Any) -> str:
-    if value is None:
-        return '""'
-    return json.dumps(str(value), ensure_ascii=False)
-
-
-def yaml_list(values: list[Any]) -> str:
-    return json.dumps(values, ensure_ascii=False)
-
-
-def architecture_scope(hardware: Any) -> tuple[list[str], list[str]]:
-    value = re.sub(r"[^a-z0-9]+", "", str(hardware or "").lower())
-    if value.startswith("ascend910b") or value == "ascend910c":
-        return ["ascend910b"], [value] if value != "ascend910b" else []
-    if value in {"ascend310p", "ascend950", "sm90", "sm90a", "sm100", "sm100a", "sm120"}:
-        return [value], []
-    return ["*"], []
-
-
-def safe_filename(value: str) -> str:
-    cleaned = re.sub(r"[^a-zA-Z0-9._-]+", "-", value).strip("-")
-    return cleaned[:80] or "candidate"
-
-
-def condition_from_entry(entry: dict[str, Any]) -> dict[str, Any]:
-    address = entry["address"]
-    context = entry["context_group"]
-    condition = {
-        "vendor": address.get("vendor"),
-        "language": address.get("language"),
-        "operator": address.get("operator"),
-        "data_type": address.get("data_type"),
-        "hardware": address.get("hardware"),
-        "shape_signature": context.get("shape_signature"),
-        "data_scale": context.get("data_scale"),
-        "implementation": context.get("implementation"),
-        "pipeline": context.get("pipeline"),
-        "environment_fingerprint": context.get("environment_fingerprint"),
-        "bottleneck_condition": context.get("bottleneck_condition"),
-    }
-    return {
-        "condition_id": stable_id("condition", condition),
-        **condition,
-        "baseline": context.get("baseline"),
-        "outcome": entry.get("outcome"),
-        "evidence_entry_id": entry.get("entry_id"),
-    }
-
-
-def enrich_candidate_identifiers(
-    candidates: list[dict[str, Any]], normalized: list[dict[str, Any]]
-) -> list[dict[str, Any]]:
-    by_entry = {str(entry["entry_id"]): entry for entry in normalized}
-    for candidate in candidates:
-        candidate_entries = [
-            by_entry[entry_id] for entry_id in candidate.get("evidence_entry_ids", []) if entry_id in by_entry
-        ]
-        operators = sorted(
-            {
-                str(by_entry[entry_id]["address"].get("operator"))
-                for entry_id in candidate.get("evidence_entry_ids", [])
-                if entry_id in by_entry and non_empty(by_entry[entry_id]["address"].get("operator"))
-            }
-        )
-        signatures = sorted(str(value) for value in candidate.get("technique_signatures", []) if non_empty(value))
-        technique_key: Any = signatures or str(candidate.get("technique_family") or "<unknown>")
-        identity = {
-            "vendor": candidate.get("vendor"),
-            "languages": sorted(candidate.get("languages", [])),
-            "technique": technique_key,
-        }
-        if signatures:
-            # A stable mechanism makes a candidate eligible for a reusable
-            # theme page, but one operator is not cross-operator validation.
-            candidate["knowledge_scope"] = "conditional-general"
-            candidate["knowledge_page_role"] = "theme-candidate"
-        else:
-            candidate["knowledge_scope"] = "operator-local"
-            candidate["knowledge_page_role"] = "operator-instance"
-            identity["operators"] = operators or ["*"]
-            blocker = "缺少稳定做法标识 technique_signature，不能跨算子匹配"
-            if blocker not in candidate.get("publication_blockers", []):
-                candidate.setdefault("publication_blockers", []).append(blocker)
-            candidate["publication_ready"] = False
-        linked_knowledge_ids = sorted(
-            {
-                str((entry.get("technique") or {}).get("knowledge_id"))
-                for entry in candidate_entries
-                if non_empty((entry.get("technique") or {}).get("knowledge_id"))
-            }
-        )
-        provisional_id = stable_id("knowledge", identity)
-        candidate["provisional_knowledge_id"] = provisional_id
-        if len(linked_knowledge_ids) == 1:
-            candidate["knowledge_id"] = linked_knowledge_ids[0]
-            candidate["knowledge_id_source"] = "agent-semantic-link"
-        else:
-            candidate["knowledge_id"] = provisional_id
-            candidate["knowledge_id_source"] = "provisional-fingerprint"
-            blocker = "knowledge_id 仍是临时指纹，需由当前 Agent 检索知识库并完成语义去重"
-            if blocker not in candidate.get("publication_blockers", []):
-                candidate.setdefault("publication_blockers", []).append(blocker)
-            candidate["publication_ready"] = False
-        if len(linked_knowledge_ids) > 1:
-            candidate.setdefault("publication_blockers", []).append("同一候选关联了多个正式 knowledge_id")
-        candidate["verified_operators"] = operators
-        conditions_by_id: dict[str, dict[str, Any]] = {}
-        for entry_id in candidate.get("evidence_entry_ids", []):
-            if entry_id not in by_entry:
-                continue
-            condition = condition_from_entry(by_entry[entry_id])
-            conditions_by_id[condition["condition_id"]] = condition
-        candidate["verified_conditions"] = [conditions_by_id[key] for key in sorted(conditions_by_id)]
-        candidate["condition_ids"] = sorted(conditions_by_id)
-        candidate["verification_outcomes"] = sorted(str(key) for key in candidate.get("outcomes", {}))
-    return candidates
-
-
-def parse_frontmatter_value(value: str) -> Any:
-    value = value.strip()
-    try:
-        return json.loads(value)
-    except json.JSONDecodeError:
-        return value.strip('"\'')
-
-
-def read_knowledge_pages(knowledge_root: Path) -> list[dict[str, Any]]:
-    if not knowledge_root.exists() or not knowledge_root.is_dir():
-        raise ValueError(f"knowledge root is not a directory: {knowledge_root}")
-    pages: list[dict[str, Any]] = []
-    for path in sorted(knowledge_root.rglob("*.md")):
-        lines = path.read_text(encoding="utf-8").splitlines()
-        if not lines or lines[0].strip() != "---":
-            continue
-        frontmatter: dict[str, Any] = {}
-        for line in lines[1:]:
-            if line.strip() == "---":
-                break
-            if ":" not in line or line[:1].isspace():
-                continue
-            key, value = line.split(":", 1)
-            frontmatter[key.strip()] = parse_frontmatter_value(value)
-        knowledge_id = frontmatter.get("knowledge_id")
-        if not non_empty(knowledge_id):
-            continue
-        condition_ids = frontmatter.get("condition_ids")
-        if not isinstance(condition_ids, list):
-            condition_ids = []
-        verified_operators = frontmatter.get("verified_operators")
-        if not isinstance(verified_operators, list):
-            verified_operators = []
-        pages.append(
-            {
-                "path": str(path),
-                "id": frontmatter.get("id"),
-                "title": frontmatter.get("title"),
-                "type": frontmatter.get("type"),
-                "knowledge_id": str(knowledge_id),
-                "condition_ids": [str(value) for value in condition_ids],
-                "verified_operators": [str(value) for value in verified_operators],
-            }
-        )
-    return pages
-
-
-def match_existing_knowledge(
-    candidates: list[dict[str, Any]], knowledge_root: Path | None
-) -> list[dict[str, Any]]:
-    pages = read_knowledge_pages(knowledge_root) if knowledge_root else []
-    by_knowledge_id: dict[str, list[dict[str, Any]]] = defaultdict(list)
-    for page in pages:
-        by_knowledge_id[page["knowledge_id"]].append(page)
-    matches: list[dict[str, Any]] = []
-    for candidate in candidates:
-        existing = by_knowledge_id.get(candidate["knowledge_id"], [])
-        current_conditions = set(candidate.get("condition_ids", []))
-        current_operators = set(candidate.get("verified_operators", []))
-        existing_operators = {
-            operator for page in existing for operator in page.get("verified_operators", [])
-        }
-        same_condition_pages = [
-            page for page in existing if current_conditions.intersection(page.get("condition_ids", []))
-        ]
-        if knowledge_root is None:
-            status = "not_checked"
-            action = "history_check_required"
-        elif candidate.get("knowledge_id_source") != "agent-semantic-link":
-            status = "semantic_match_required"
-            action = "agent_compare_and_link_knowledge"
-        elif not existing:
-            status = "new_knowledge"
-            action = "create_page"
-        elif not same_condition_pages and current_operators and existing_operators.isdisjoint(current_operators):
-            status = "extends_operators"
-            action = "add_operator_verification"
-        elif not same_condition_pages:
-            status = "extends_conditions"
-            action = "add_verified_condition"
-        elif any(page.get("type") != candidate.get("candidate_type") for page in same_condition_pages):
-            status = "conflicts_existing"
-            action = "register_conflict"
-        else:
-            status = "confirms_existing"
-            action = "append_verification"
-        match = {
-            "artifact_type": KNOWLEDGE_MATCH_ARTIFACT_TYPE,
-            "candidate_id": candidate["candidate_id"],
-            "knowledge_id": candidate["knowledge_id"],
-            "knowledge_id_source": candidate.get("knowledge_id_source"),
-            "condition_ids": candidate.get("condition_ids", []),
-            "verified_operators": candidate.get("verified_operators", []),
-            "match_status": status,
-            "recommended_action": action,
-            "existing_pages": existing,
-            "same_condition_pages": same_condition_pages,
-        }
-        candidate["knowledge_match"] = match
-        matches.append(match)
-    return matches
-
-
-def write_knowledge_matches(output_dir: Path, matches: list[dict[str, Any]], knowledge_root: Path | None) -> None:
-    write_jsonl(output_dir / "existing-knowledge-matches.jsonl", matches)
-    status_labels = {
-        "not_checked": "未检查正式知识库",
-        "new_knowledge": "未发现同一做法知识",
-        "semantic_match_required": "临时指纹不能证明知识相同，需要 Agent 做语义匹配",
-        "extends_operators": "同一做法已存在，本次由新算子提供验证",
-        "extends_conditions": "已有同一做法，但当前条件尚未验证",
-        "confirms_existing": "同一做法和条件已在知识库中验证",
-        "conflicts_existing": "同一条件下与既有结论冲突",
-    }
-    lines = [
-        "# 历史知识条件对比",
-        "",
-        f"- 知识库目录：{knowledge_root if knowledge_root else '未提供'}",
-        "- 本报告按稳定知识标识和条件标识比较，不使用标题相似度代替精确匹配。",
-        "",
-    ]
-    for match in matches:
-        lines.extend(
-            [
-                f"## {match['candidate_id']}",
-                "",
-                f"- 稳定知识标识：`{match['knowledge_id']}`",
-                f"- 当前条件：{', '.join(match['condition_ids']) or '无'}",
-                f"- 判断：{status_labels[match['match_status']]}",
-                f"- 建议动作：`{match['recommended_action']}`",
-                *[f"- 已有页面：`{page['path']}`" for page in match["existing_pages"]],
-                "",
-            ]
-        )
-    (output_dir / "condition-comparison.md").write_text("\n".join(lines), encoding="utf-8")
-    proposal_dir = output_dir / "knowledge-update-proposals"
-    proposal_dir.mkdir(parents=True, exist_ok=True)
-    write_jsonl(proposal_dir / "index.jsonl", matches)
-
-
-def candidate_content_errors(candidate: dict[str, Any]) -> list[str]:
-    errors: list[str] = []
-    gaps = candidate.get("content_gap_reasons") if isinstance(candidate.get("content_gap_reasons"), dict) else {}
-    gap_values = {key: non_empty_values(value) for key, value in gaps.items()}
-    if not (
-        candidate.get("target_overheads")
-        or candidate.get("bottleneck_hypotheses")
-        or candidate.get("intended_effects")
-        or gap_values.get("problem")
-    ):
-        errors.append("缺少问题或目标说明")
-    for key, gap_key, reason in (
-        ("before_states", "before", "缺少修改前实现说明"),
-        ("after_states", "after", "缺少修改后实现说明"),
-        ("mechanisms", "mechanism", "缺少作用机制说明"),
-    ):
-        if not candidate.get(key) and not gap_values.get(gap_key):
-            errors.append(reason)
-    if not candidate.get("technique_summaries") and not gap_values.get("summary"):
-        errors.append("缺少具体做法说明")
-    return errors
-
-
-def content_gap_lines(candidate: dict[str, Any], key: str, label: str) -> list[str]:
-    gaps = candidate.get("content_gap_reasons") if isinstance(candidate.get("content_gap_reasons"), dict) else {}
-    return [f"- {label}：{value}" for value in non_empty_values(gaps.get(key, []))]
-
-
-def write_regeneration_requests(output_dir: Path, candidates: list[dict[str, Any]]) -> None:
-    legacy_rejections = output_dir / "knowledge-candidates" / "rejected.jsonl"
-    if legacy_rejections.exists():
-        legacy_rejections.unlink()
-    rows = [
-        {
-            "artifact_type": "kernaut_knowledge_regeneration_request_v1",
-            "candidate_id": candidate.get("candidate_id"),
-            "title": candidate.get("title"),
-            "candidate_type": candidate.get("candidate_type"),
-            "evidence_entry_ids": candidate.get("evidence_entry_ids", []),
-            "source_records": candidate.get("source_records", []),
-            "missing_content": candidate_content_errors(candidate),
-            "required_action": "回到 source_records 重新分析并补写账本；证据确实不存在时，在 technique.missing_reasons 中逐项注明原因",
-        }
-        for candidate in candidates
-    ]
-    write_jsonl(output_dir / "knowledge-candidates" / "regeneration-required.jsonl", rows)
-
-
-def retest_requests(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    return [
-        {
-            "artifact_type": "kernaut_retest_request_v1",
-            "entry_id": row.get("entry_id"),
-            "attempt_id": row.get("attempt_id"),
-            "session_id": row.get("session_id"),
-            "current_verification_status": row.get("verification_status"),
-            "context": row.get("context", {}),
-            "technique": row.get("technique", {}),
-            "measurements": row.get("measurements", []),
-            "source_records": row.get("source_records", []),
-            "required_action": (
-                "在兼容硬件和软件环境中重建同一代码、基线、输入与评测命令；"
-                "复测成功后设为 reproduced，无法复测时设为 retest-blocked 并在 uncertainties 写明原因"
-            ),
-        }
-        for row in rows
-        if row.get("evidence_origin") == "measured"
-        and bool(row.get("measurements"))
-        and row.get("verification_status") not in {"reproduced", "retest-blocked"}
-    ]
-
-
-def candidate_rows(ledger: list[dict[str, Any]], aggregates: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    candidates: list[dict[str, Any]] = []
-    normalized = [normalize_entry(row) for row in ledger]
-    by_entry = {row["entry_id"]: row for row in normalized}
-
-    for aggregate in aggregates:
-        aggregate_entries = [by_entry[entry_id] for entry_id in aggregate["entry_ids"]]
-        conclusion_entries = [
-            entry
-            for entry in aggregate_entries
-            if entry.get("confidence") in {"verified", "source-reported", "inferred"}
-            and entry.get("evidence_origin") != "source-reported"
-        ]
-        direct_pitfall = any(
-            entry.get("record_type") == "pitfall"
-            and non_empty(entry.get("scope"))
-            and bool(entry.get("source_records"))
-            for entry in conclusion_entries
-        )
-        direct_failure = any(
-            entry.get("outcome") in TECHNICAL_FAILURES
-            and non_empty(entry.get("scope"))
-            and non_empty((entry.get("bottleneck") or {}).get("hypothesis"))
-            and bool((entry.get("bottleneck") or {}).get("evidence"))
-            for entry in conclusion_entries
-        )
-        if not (aggregate["repeated_failure"] or direct_pitfall or direct_failure):
-            continue
-        candidate_id = stable_id("pitfall", aggregate["aggregate_id"])
-        address = aggregate["address"]
-        architectures, soc = architecture_scope(address.get("hardware"))
-        language = str(address.get("language") or "")
-        pitfall_entries = conclusion_entries
-        technique_summaries = sorted(
-            {
-                str((entry.get("technique") or {}).get("summary"))
-                for entry in pitfall_entries
-                if non_empty((entry.get("technique") or {}).get("summary"))
-            }
-        )
-        technique_signatures = sorted(
-            {
-                str((entry.get("technique") or {}).get("signature"))
-                for entry in pitfall_entries
-                if non_empty((entry.get("technique") or {}).get("signature"))
-            }
-        )
-        intended_effects = sorted(
-            {
-                str((entry.get("technique") or {}).get("intent"))
-                for entry in pitfall_entries
-                if non_empty((entry.get("technique") or {}).get("intent"))
-            }
-        )
-        before_states = sorted(
-            {
-                str((entry.get("technique") or {}).get("before"))
-                for entry in pitfall_entries
-                if non_empty((entry.get("technique") or {}).get("before"))
-            }
-        )
-        after_states = sorted(
-            {
-                str((entry.get("technique") or {}).get("after"))
-                for entry in pitfall_entries
-                if non_empty((entry.get("technique") or {}).get("after"))
-            }
-        )
-        mechanisms = sorted(
-            {
-                str((entry.get("technique") or {}).get("mechanism"))
-                for entry in pitfall_entries
-                if non_empty((entry.get("technique") or {}).get("mechanism"))
-            }
-        )
-        target_overheads = sorted(
-            {
-                str((entry.get("technique") or {}).get("target"))
-                for entry in pitfall_entries
-                if non_empty((entry.get("technique") or {}).get("target"))
-            }
-        )
-        content_gap_reasons: dict[str, list[str]] = defaultdict(list)
-        for entry in pitfall_entries:
-            missing_reasons = (entry.get("technique") or {}).get("missing_reasons")
-            if not isinstance(missing_reasons, dict):
-                continue
-            for key, value in missing_reasons.items():
-                content_gap_reasons[str(key)].extend(non_empty_values(value))
-        observations = [
-            str(observation)
-            for entry in pitfall_entries
-            for observation in entry.get("observations", [])
-            if non_empty(observation)
-        ]
-        bottleneck_hypotheses = sorted(
-            {
-                str((entry.get("bottleneck") or {}).get("hypothesis"))
-                for entry in pitfall_entries
-                if non_empty((entry.get("bottleneck") or {}).get("hypothesis"))
-            }
-        )
-        bottleneck_evidence = [
-            str(evidence)
-            for entry in pitfall_entries
-            for evidence in (entry.get("bottleneck") or {}).get("evidence", [])
-            if non_empty(evidence)
-        ]
-        scope_statements = sorted(
-            {str(entry.get("scope")) for entry in pitfall_entries if non_empty(entry.get("scope"))}
-        )
-        recommended_actions = sorted(
-            {
-                str(entry.get("recommended_action"))
-                for entry in pitfall_entries
-                if non_empty(entry.get("recommended_action"))
-            }
-        )
-        related_entry_ids = sorted(
-            {
-                str(entry_id)
-                for entry in pitfall_entries
-                for entry_id in entry.get("related_entry_ids", [])
-                if non_empty(entry_id)
-            }
-        )
-        measurements = [
-            measurement
-            for entry in pitfall_entries
-            for measurement in entry.get("measurements", [])
-            if isinstance(measurement, dict)
-        ]
-        first_context = pitfall_entries[0].get("context") if isinstance(pitfall_entries[0].get("context"), dict) else {}
-        context_summary = {
-            "operator": address.get("operator"),
-            "hardware": address.get("hardware"),
-            "language": language,
-            "data_type": address.get("data_type"),
-            "shape": first_context.get("shape_signature") or first_context.get("shape"),
-            "data_scale": first_context.get("data_scale"),
-            "implementation": first_context.get("implementation"),
-            "pipeline": first_context.get("pipeline"),
-            "baseline": first_context.get("baseline"),
-        }
-        technique_label = technique_summaries[0] if technique_summaries else aggregate["technique_family"]
-        publication_blockers = []
-        if not address.get("vendor"):
-            publication_blockers.append("缺少硬件平台 vendor")
-        if not address.get("hardware"):
-            publication_blockers.append("缺少硬件或架构")
-        if not language:
-            publication_blockers.append("缺少实现语言")
-        if architectures == ["*"]:
-            publication_blockers.append("硬件无法映射到 KernelWiki 架构词表")
-        publication_blockers.append("尚未对照 KernelWiki data/tags.yaml 校验受控词表")
-        candidates.append(
-            {
-                "artifact_type": CANDIDATE_ARTIFACT_TYPE,
-                "candidate_id": candidate_id,
-                "candidate_type": "pitfall",
-                "review_status": "review-required",
-                "confidence": "inferred",
-                "evidence_level": "inferred",
-                "title": f"{aggregate['address'].get('operator') or '未知算子'}：{technique_label} 的失败边界",
-                "vendor": address.get("vendor") or "generic",
-                "architectures": architectures,
-                "soc": soc,
-                "languages": [language] if language else [],
-                "address_ids": [aggregate["address_id"]],
-                "technique_family": aggregate["technique_family"],
-                "technique_summaries": technique_summaries,
-                "technique_signatures": technique_signatures,
-                "intended_effects": intended_effects,
-                "before_states": before_states,
-                "after_states": after_states,
-                "mechanisms": mechanisms,
-                "target_overheads": target_overheads,
-                "content_gap_reasons": {
-                    key: sorted(set(values)) for key, values in content_gap_reasons.items()
-                },
-                "observations": observations,
-                "measurements": measurements,
-                "bottleneck_hypotheses": bottleneck_hypotheses,
-                "bottleneck_evidence": bottleneck_evidence,
-                "scope_statements": scope_statements,
-                "recommended_actions": recommended_actions,
-                "related_entry_ids": related_entry_ids,
-                "outcomes": aggregate["outcomes"],
-                "context_summary": context_summary,
-                "scope": aggregate["context_group"],
-                "evidence_entry_ids": aggregate["entry_ids"],
-                "tags": [language] if language and language != "*" else [],
-                "publication_ready": not publication_blockers,
-                "publication_blockers": publication_blockers,
-                "conditional_dead_end_candidate": aggregate["conditional_dead_end_candidate"],
-                "conflict": aggregate["conflict"],
-                "source_records": aggregate["source_records"],
-            }
-        )
-
-    for entry in normalized:
-        if entry.get("outcome") != "worked" or entry.get("confidence") not in {"verified", "source-reported"}:
-            continue
-        if not entry.get("address_complete"):
-            continue
-        address = entry["address"]
-        architectures, soc = architecture_scope(address.get("hardware"))
-        language = str(address.get("language") or "")
-        technique = entry.get("technique") if isinstance(entry.get("technique"), dict) else {}
-        summary = str(technique.get("summary") or technique.get("family") or "有效优化做法")
-        candidate_id = stable_id("experience", entry["entry_id"])
-        publication_blockers = ["尚未对照 KernelWiki data/tags.yaml 校验受控词表"]
-        if architectures == ["*"]:
-            publication_blockers.append("硬件无法映射到 KernelWiki 架构词表")
-        if not language:
-            publication_blockers.append("缺少实现语言")
-        for field, reason in (
-            (technique.get("before"), "缺少优化前实现说明"),
-            (technique.get("after"), "缺少优化后实现说明"),
-            (technique.get("mechanism"), "缺少作用机制说明"),
-        ):
-            if not non_empty(field):
-                publication_blockers.append(reason)
-        context = entry.get("context") if isinstance(entry.get("context"), dict) else {}
-        environment = context.get("environment") if isinstance(context.get("environment"), dict) else {}
-        bottleneck = entry.get("bottleneck") if isinstance(entry.get("bottleneck"), dict) else {}
-        technique_missing_reasons = (
-            technique.get("missing_reasons") if isinstance(technique.get("missing_reasons"), dict) else {}
-        )
-        candidates.append(
-            {
-                "artifact_type": CANDIDATE_ARTIFACT_TYPE,
-                "candidate_id": candidate_id,
-                "candidate_type": "experience",
-                "review_status": "review-required",
-                "confidence": entry["confidence"],
-                "evidence_level": entry["evidence_level"],
-                "title": f"{address.get('operator') or '未知算子'}：{summary}",
-                "vendor": address.get("vendor") or "generic",
-                "architectures": architectures,
-                "soc": soc,
-                "languages": [language] if language else [],
-                "probe_slug": candidate_id.removeprefix("experience-"),
-                "measured_on": {"device": address.get("hardware") or "unknown"},
-                "source": f"offline-ledger:{entry['entry_id']}",
-                "cann_version": environment.get("cann"),
-                "address_ids": [entry["address_id"]],
-                "technique_family": str(technique.get("family") or "<unknown>"),
-                "technique_summaries": [summary],
-                "technique_signatures": [str(technique.get("signature"))] if non_empty(technique.get("signature")) else [],
-                "intended_effects": [str(technique.get("intent"))] if non_empty(technique.get("intent")) else [],
-                "before_states": [str(technique.get("before"))] if non_empty(technique.get("before")) else [],
-                "after_states": [str(technique.get("after"))] if non_empty(technique.get("after")) else [],
-                "mechanisms": [str(technique.get("mechanism"))] if non_empty(technique.get("mechanism")) else [],
-                "target_overheads": [str(technique.get("target"))] if non_empty(technique.get("target")) else [],
-                "content_gap_reasons": {
-                    str(key): non_empty_values(value)
-                    for key, value in technique_missing_reasons.items()
-                    if non_empty_values(value)
-                },
-                "observations": [str(value) for value in entry.get("observations", []) if non_empty(value)],
-                "measurements": entry.get("measurements", []),
-                "bottleneck_hypotheses": [str(bottleneck.get("hypothesis"))] if non_empty(bottleneck.get("hypothesis")) else [],
-                "bottleneck_evidence": [str(value) for value in bottleneck.get("evidence", []) if non_empty(value)],
-                "scope_statements": [str(entry.get("scope"))] if non_empty(entry.get("scope")) else [],
-                "recommended_actions": [str(entry.get("recommended_action"))] if non_empty(entry.get("recommended_action")) else [],
-                "related_entry_ids": [str(value) for value in entry.get("related_entry_ids", []) if non_empty(value)],
-                "outcomes": {"worked": 1},
-                "context_summary": {
-                    "operator": address.get("operator"),
-                    "hardware": address.get("hardware"),
-                    "language": language,
-                    "data_type": address.get("data_type"),
-                    "shape": context.get("shape_signature") or context.get("shape"),
-                    "data_scale": context.get("data_scale"),
-                    "implementation": context.get("implementation"),
-                    "pipeline": context.get("pipeline"),
-                    "baseline": context.get("baseline"),
-                },
-                "scope": entry["context_group"],
-                "evidence_entry_ids": [entry["entry_id"]],
-                "tags": [language] if language and language != "*" else [],
-                "publication_ready": not publication_blockers,
-                "publication_blockers": publication_blockers,
-                "conditional_dead_end_candidate": False,
-                "conflict": False,
-                "source_records": entry.get("source_records", []),
-            }
-        )
-
-    worked_by_family: dict[tuple[str, str], list[dict[str, Any]]] = defaultdict(list)
-    for row in normalized:
-        technique = row.get("technique") if isinstance(row.get("technique"), dict) else {}
-        if row.get("outcome") == "worked" and row.get("confidence") in {"verified", "source-reported"}:
-            vendor = str(row["address"].get("vendor") or "generic")
-            family = str(technique.get("family") or "<unknown>")
-            worked_by_family[(vendor, family)].append(row)
-    for (vendor, family), entries in sorted(worked_by_family.items()):
-        addresses = {entry["address_id"] for entry in entries if entry["address_complete"]}
-        if len(addresses) < 2:
-            continue
-        candidate_id = stable_id("exp", {"vendor": vendor, "family": family, "addresses": sorted(addresses)})
-        architecture_values: set[str] = set()
-        soc_values: set[str] = set()
-        for entry in entries:
-            entry_architectures, entry_soc = architecture_scope(entry["address"].get("hardware"))
-            architecture_values.update(entry_architectures)
-            soc_values.update(entry_soc)
-        architectures = sorted(architecture_values)
-        languages = sorted({str(entry["address"].get("language")) for entry in entries if entry["address"].get("language")})
-        publication_blockers = ["尚未对照 KernelWiki data/tags.yaml 校验受控词表"]
-        if not architectures or architectures == ["*"]:
-            publication_blockers.append("硬件无法映射到 KernelWiki 架构词表")
-        if not languages or languages == ["*"]:
-            publication_blockers.append("缺少实现语言")
-        candidates.append(
-            {
-                "artifact_type": CANDIDATE_ARTIFACT_TYPE,
-                "candidate_id": candidate_id,
-                "candidate_type": "experience",
-                "review_status": "review-required",
-                "confidence": (
-                    "verified" if all(entry.get("confidence") == "verified" for entry in entries) else "source-reported"
-                ),
-                "evidence_level": "measured",
-                "title": f"{family}：跨算子有效做法候选",
-                "vendor": vendor,
-                "architectures": architectures or ["*"],
-                "soc": sorted(soc_values),
-                "languages": languages or ["*"],
-                "probe_slug": candidate_id.removeprefix("exp-"),
-                "measured_on": {"device": ", ".join(architectures) if architectures else "unknown"},
-                "source": f"offline-ledger:{candidate_id}",
-                "address_ids": sorted(addresses),
-                "technique_family": family,
-                "scope": [entry.get("scope") for entry in entries],
-                "evidence_entry_ids": sorted(entry["entry_id"] for entry in entries),
-                "tags": languages,
-                "cann_version": "unknown" if vendor == "ascend" else None,
-                "publication_ready": not publication_blockers,
-                "publication_blockers": publication_blockers,
-                "conditional_dead_end_candidate": False,
-                "conflict": False,
-                "source_records": sorted({source for entry in entries for source in entry.get("source_records", [])}),
-            }
-        )
-    for candidate in candidates:
-        gap_reasons = candidate.get("content_gap_reasons")
-        if not isinstance(gap_reasons, dict) or not any(
-            non_empty_values(value) for value in gap_reasons.values()
-        ):
-            continue
-        blocker = "原始证据存在无法补全的内容缺口，已在页面注明原因"
-        if blocker not in candidate["publication_blockers"]:
-            candidate["publication_blockers"].append(blocker)
-        candidate["publication_ready"] = False
-    return enrich_candidate_identifiers(candidates, normalized)
-
-
-def write_candidate_pages(
-    output_dir: Path, candidates: list[dict[str, Any]], regeneration_count: int = 0
-) -> None:
-    candidate_dir = output_dir / "knowledge-candidates"
-    pages = candidate_dir / "pages"
-    pages.mkdir(parents=True, exist_ok=True)
-    for old_page in pages.glob("*.md"):
-        old_page.unlink()
-    write_jsonl(candidate_dir / "index.jsonl", candidates)
-    for candidate in candidates:
-        knowledge_id = candidate.get("knowledge_id") or stable_id(
-            "knowledge",
-            {
-                "vendor": candidate.get("vendor"),
-                "languages": candidate.get("languages", []),
-                "title": candidate.get("title"),
-            },
-        )
-        condition_ids = candidate.get("condition_ids", [])
-        filename = safe_filename(candidate["candidate_id"]) + ".md"
-        page = [
-            "---",
-            f"id: {yaml_scalar(candidate['candidate_id'])}",
-            f"knowledge_id: {yaml_scalar(knowledge_id)}",
-            f"knowledge_id_source: {yaml_scalar(candidate.get('knowledge_id_source', 'provisional-fingerprint'))}",
-            f"provisional_knowledge_id: {yaml_scalar(candidate.get('provisional_knowledge_id', knowledge_id))}",
-            f"knowledge_scope: {yaml_scalar(candidate.get('knowledge_scope', 'operator-local'))}",
-            f"knowledge_page_role: {yaml_scalar(candidate.get('knowledge_page_role', 'operator-instance'))}",
-            f"verified_operators: {yaml_list(candidate.get('verified_operators', []))}",
-            f"condition_ids: {yaml_list(condition_ids)}",
-            f"type: {yaml_scalar(candidate['candidate_type'])}",
-            f"title: {yaml_scalar(candidate['title'])}",
-            f"vendor: {yaml_scalar(candidate['vendor'])}",
-            f"architectures: {yaml_list(candidate['architectures'])}",
-            f"languages: {yaml_list(candidate['languages'])}",
-            *([f"soc: {yaml_list(candidate['soc'])}"] if candidate.get("soc") else []),
-            f"confidence: {yaml_scalar(candidate['confidence'])}",
-            f"evidence_level: {yaml_scalar(candidate['evidence_level'])}",
-            f"scope: {yaml_scalar(json.dumps(candidate['scope'], ensure_ascii=False, sort_keys=True))}",
-            f"tags: {yaml_list(candidate['tags'])}",
-            f"technique_signatures: {yaml_list(candidate.get('technique_signatures', []))}",
-            f"verification_outcomes: {yaml_list(candidate.get('verification_outcomes', []))}",
-            *(["sources: []"] if candidate["candidate_type"] == "pitfall" else []),
-            *(
-                [
-                    f"probe_slug: {yaml_scalar(candidate['probe_slug'])}",
-                    f"measured_on: {json.dumps(candidate['measured_on'], ensure_ascii=False)}",
-                    f"source: {yaml_scalar(candidate['source'])}",
-                    *([f"cann_version: {yaml_scalar(candidate['cann_version'])}"] if candidate.get("cann_version") else []),
-                ]
-                if candidate["candidate_type"] == "experience"
-                else []
-            ),
-            "---",
-            "",
-            f"# {candidate['title']}",
-            "",
-            "## 适用场景",
-            "",
-            *[
-                f"- {label}：{candidate.get('context_summary', {}).get(key)}"
-                for key, label in (
-                    ("operator", "算子"),
-                    ("hardware", "硬件"),
-                    ("language", "实现语言"),
-                    ("data_type", "数据类型"),
-                    ("shape", "问题形状"),
-                    ("data_scale", "数据规模"),
-                    ("implementation", "实现方式"),
-                    ("baseline", "对比基线"),
-                )
-                if non_empty(candidate.get("context_summary", {}).get(key))
-            ],
-            "",
-            "## 证据置信度",
-            "",
-            (
-                f"- `{candidate['confidence']}`"
-                f"（{CONFIDENCE_LABELS.get(str(candidate['confidence']), '未定义')}）"
-            ),
-            "",
-        ]
-        if candidate["candidate_type"] == "pitfall":
-            page.extend(
-                [
-                    "## 问题与目标",
-                    "",
-                    *[f"- 当前问题：{value}" for value in candidate.get("target_overheads", [])],
-                    *[f"- 原始目标：{value}" for value in candidate.get("intended_effects", [])],
-                    *[f"- 观察到的风险：{value}" for value in candidate.get("bottleneck_hypotheses", [])],
-                    *content_gap_lines(candidate, "problem", "问题或目标无法确认，原因"),
-                    "",
-                    "## 尝试的做法",
-                    "",
-                    *[f"- 修改前：{value}" for value in candidate.get("before_states", [])],
-                    *[f"- 修改后：{value}" for value in candidate.get("after_states", [])],
-                    *content_gap_lines(candidate, "before", "修改前实现无法确认，原因"),
-                    *content_gap_lines(candidate, "after", "修改后实现无法确认，原因"),
-                    *[f"- {value}" for value in candidate.get("technique_summaries", [])],
-                    *[f"- 目的：{value}" for value in candidate.get("intended_effects", [])],
-                    *[f"- 实现标识：`{value}`" for value in candidate.get("technique_signatures", [])],
-                    "",
-                    "## 验证结果",
-                    "",
-                    *[f"- {value}" for value in candidate.get("observations", [])],
-                    *[
-                        f"- 测量 {index}：`{json.dumps(value, ensure_ascii=False, sort_keys=True)}`"
-                        for index, value in enumerate(candidate.get("measurements", []), 1)
-                    ],
-                    f"- 结果分类：`{json.dumps(candidate.get('outcomes', {}), ensure_ascii=False, sort_keys=True)}`",
-                    "",
-                    "## 原因与证据",
-                    "",
-                    *[f"- 作用机制：{value}" for value in candidate.get("mechanisms", [])],
-                    *content_gap_lines(candidate, "mechanism", "作用机制无法确认，原因"),
-                    *[f"- {value}" for value in candidate.get("bottleneck_hypotheses", [])],
-                    *[f"- 依据：{value}" for value in candidate.get("bottleneck_evidence", [])],
-                    "",
-                    "## 可复用边界",
-                    "",
-                    *[f"- {value}" for value in candidate.get("recommended_actions", [])],
-                    *[f"- 适用范围：{value}" for value in candidate.get("scope_statements", [])],
-                    *[f"- 相关成功或反例账本：`{value}`" for value in candidate.get("related_entry_ids", [])],
-                    "",
-                ]
-            )
-        else:
-            page.extend(
-                [
-                    "## 问题与目标",
-                    "",
-                    *[f"- 当前问题：{value}" for value in candidate.get("target_overheads", [])],
-                    *[f"- 需要解决的瓶颈：{value}" for value in candidate.get("bottleneck_hypotheses", [])],
-                    *[f"- 目标：{value}" for value in candidate.get("intended_effects", [])],
-                    *content_gap_lines(candidate, "problem", "问题或目标无法确认，原因"),
-                    "",
-                    "## 采用的做法",
-                    "",
-                    *[f"- 修改前：{value}" for value in candidate.get("before_states", [])],
-                    *[f"- 修改后：{value}" for value in candidate.get("after_states", [])],
-                    *content_gap_lines(candidate, "before", "修改前实现无法确认，原因"),
-                    *content_gap_lines(candidate, "after", "修改后实现无法确认，原因"),
-                    *[f"- {value}" for value in candidate.get("technique_summaries", [])],
-                    *[f"- 实现标识：`{value}`" for value in candidate.get("technique_signatures", [])],
-                    "",
-                    "## 验证结果",
-                    "",
-                    *[f"- {value}" for value in candidate.get("observations", [])],
-                    *[
-                        f"- 测量 {index}：`{json.dumps(value, ensure_ascii=False, sort_keys=True)}`"
-                        for index, value in enumerate(candidate.get("measurements", []), 1)
-                    ],
-                    "",
-                    "## 为什么有效",
-                    "",
-                    *[f"- 作用机制：{value}" for value in candidate.get("mechanisms", [])],
-                    *content_gap_lines(candidate, "mechanism", "作用机制无法确认，原因"),
-                    *[f"- {value}" for value in candidate.get("bottleneck_hypotheses", [])],
-                    *[f"- 依据：{value}" for value in candidate.get("bottleneck_evidence", [])],
-                    "",
-                    "## 使用边界",
-                    "",
-                    *[f"- 适用范围：{value}" for value in candidate.get("scope_statements", [])],
-                    *[f"- 建议：{value}" for value in candidate.get("recommended_actions", [])],
-                    "",
-                ]
-            )
-        pipeline = candidate.get("context_summary", {}).get("pipeline")
-        if non_empty(pipeline):
-            page.extend(["## 复现入口", "", f"- `{pipeline}`", ""])
-        page.extend(
-            [
-                "## 历史知识匹配",
-                "",
-                f"- 稳定知识标识：`{knowledge_id}`",
-                f"- 标识来源：`{candidate.get('knowledge_id_source', 'provisional-fingerprint')}`",
-                f"- 已验证算子：{', '.join(candidate.get('verified_operators', [])) or '未知'}",
-                *[f"- 已验证条件标识：`{condition_id}`" for condition_id in condition_ids],
-                f"- 匹配状态：`{candidate.get('knowledge_match', {}).get('match_status', 'not_checked')}`",
-                f"- 建议更新动作：`{candidate.get('knowledge_match', {}).get('recommended_action', 'history_check_required')}`",
-                *[
-                    f"- 已有知识页：`{page_info['path']}`"
-                    for page_info in candidate.get("knowledge_match", {}).get("existing_pages", [])
-                ],
-                "",
-                "## 审核状态",
-                "",
-                "- 当前状态：待审核，不得直接作为正式经验或自动阻止后续尝试。",
-                f"- 条件性死端候选：{'是' if candidate['conditional_dead_end_candidate'] else '否'}",
-                f"- 存在正反冲突：{'是' if candidate['conflict'] else '否'}",
-                f"- 可进入发布审核：{'是' if candidate['publication_ready'] else '否'}",
-                *[f"- 发布阻断：{reason}" for reason in candidate["publication_blockers"]],
-                f"- 证据账本：{', '.join(candidate['evidence_entry_ids'])}",
-                "",
-                "## 证据回链",
-                "",
-                *[f"- `{source}`" for source in candidate["source_records"]],
-                "",
-            ]
-        )
-        (pages / filename).write_text("\n".join(page), encoding="utf-8")
-    overview = [
-        "# 待沉淀知识候选",
-        "",
-        "这里集中列出本批轨迹准备沉淀的内容。页面仍处于审核阶段，不等于已经写入 KernelWiki。",
-        "",
-        "## 有效经验",
-        "",
-        *[
-            f"- [{candidate['title']}](pages/{safe_filename(candidate['candidate_id'])}.md)"
-            for candidate in candidates
-            if candidate["candidate_type"] == "experience"
-        ],
-        "",
-        "## 条件性避坑",
-        "",
-        *[
-            f"- [{candidate['title']}](pages/{safe_filename(candidate['candidate_id'])}.md)"
-            for candidate in candidates
-            if candidate["candidate_type"] == "pitfall"
-        ],
-        "",
-        "## 机器索引",
-        "",
-        "结构化字段和审核状态见 `index.jsonl`。",
-        f"需要回到原始证据重新生成的记录：{regeneration_count}，详见 `regeneration-required.jsonl`。",
-        "",
-    ]
-    (candidate_dir / "README.md").write_text("\n".join(overview), encoding="utf-8")
-
-
-def review_report(
-    attempts: list[dict[str, Any]],
-    ledger: list[dict[str, Any]],
-    aggregates: list[dict[str, Any]],
-    candidates: list[dict[str, Any]],
-    input_summary: dict[str, Any] | None = None,
-) -> str:
-    normalized = [normalize_entry(row) for row in ledger]
-    outcomes = Counter(str(row.get("outcome")) for row in normalized)
-    confidences = Counter(str(row.get("confidence")) for row in normalized)
-    evidence_classes = Counter(str(row.get("evidence_class_name")) for row in normalized)
-    record_types = Counter(str(row.get("record_type")) for row in normalized)
-    unattributed = sum(row.get("attribution_status") != "attributed" for row in normalized)
-    incomplete_addresses = sum(not row.get("address_complete") for row in normalized)
-    repeated = sum(bool(row.get("repeated_failure")) for row in aggregates)
-    dead_end = sum(bool(row.get("conditional_dead_end_candidate")) for row in aggregates)
-    conflicts = sum(bool(row.get("conflict")) for row in aggregates)
-    blocked_candidates = sum(not candidate.get("publication_ready", False) for candidate in candidates)
-    pending_retests = len(retest_requests(normalized))
-    input_summary = input_summary or {}
-    lines = [
-        "# Kernaut 离线经验账本复核报告",
-        "",
-        "## 处理规模",
-        "",
-        f"- 输入文件：{input_summary.get('source_files', '未知')}",
-        f"- 原始记录：{input_summary.get('source_records', '未知')}",
-        f"- 原始会话：{input_summary.get('source_sessions', '未知')}",
-        f"- 候选证据：{input_summary.get('evidence_candidates', '未知')}",
-        f"- 候选会话：{input_summary.get('candidate_sessions', '未知')}",
-        f"- 隔离测量：{input_summary.get('isolated_measurements', '未知')}",
-        f"- 解析错误：{input_summary.get('parse_errors', '未知')}",
-        f"- 尝试：{len(attempts)}",
-        f"- 账本条目：{len(ledger)}",
-        f"- 算子上下文聚合：{len(aggregates)}",
-        f"- 知识候选：{len(candidates)}",
-        "",
-        "## 结果分布",
-        "",
-        f"- 结果：`{json.dumps(dict(outcomes), ensure_ascii=False, sort_keys=True)}`",
-        f"- 记录类型：`{json.dumps(dict(record_types), ensure_ascii=False, sort_keys=True)}`",
-        f"- 置信度：`{json.dumps(dict(confidences), ensure_ascii=False, sort_keys=True)}`",
-        f"- 证据类型：`{json.dumps(dict(evidence_classes), ensure_ascii=False, sort_keys=True)}`",
-        f"- 未归因或不完整：{unattributed}",
-        f"- 门牌号待补全：{incomplete_addresses}",
-        f"- 待自动复测：{pending_retests}",
-        "",
-        "## 聚合风险",
-        "",
-        f"- 重复失败软提示：{repeated}",
-        f"- 条件性死端候选：{dead_end}",
-        f"- 正反证据冲突：{conflicts}",
-        f"- 缺字段、不可发布的候选：{blocked_candidates}",
-        "",
-        "## 人工审核重点",
-        "",
-        "- 检查条件性死端是否确有直接瓶颈证据和明确适用范围。",
-        "- 检查跨算子经验候选是否来自彼此独立的实测尝试。",
-        "- 检查门牌号、环境指纹、基线和问题形状是否错误合并。",
-        "- 检查隔离区中的未识别评测格式，决定是否新增解析器。",
-        "- 检查候选页是否包含敏感路径、私有代码或内部地址。",
-        "- 兼容环境可用时必须处理 `retest-required.jsonl`；不能复测时标记 `retest-blocked` 并写明缺失的硬件、软件、代码或命令条件。",
-        "- 当前白名单测量解析器未自动识别的评测格式，只能由 Agent 从可回链工具输出中结构化录入，并标为 `source-reported`；只有独立复测成功后才能标为 `verified`。",
-        "- 候选页在对照 KernelWiki `data/tags.yaml` 前保持发布阻断。",
-        "",
-    ]
-    return "\n".join(lines)
-
-
-def count_jsonl(path: Path) -> int | None:
-    if not path.exists():
-        return None
-    with path.open("r", encoding="utf-8") as handle:
-        return sum(1 for line in handle if line.strip())
-
-
-def load_input_summary(root: Path) -> dict[str, Any]:
-    summary: dict[str, Any] = {}
-    progress = root / "progress.json"
-    if progress.exists():
-        value = json.loads(progress.read_text(encoding="utf-8"))
-        if isinstance(value, dict):
-            summary.update(value)
-    candidate_count = count_jsonl(root / "evidence-candidates.jsonl")
-    isolated_count = count_jsonl(root / "isolated-measurements.jsonl")
-    if candidate_count is not None:
-        summary["evidence_candidates"] = candidate_count
-    if isolated_count is not None:
-        summary["isolated_measurements"] = isolated_count
-    return summary
-
-
-def print_validation(kind: str, errors: list[str], rows: int) -> int:
-    print(json.dumps({"kind": kind, "rows": rows, "errors": errors, "valid": not errors}, ensure_ascii=False, indent=2))
-    return 0 if not errors else 1
-
-
-def command_validate_attempts(args: argparse.Namespace) -> int:
-    rows = load_jsonl(args.file)
-    return print_validation("attempts", validate_attempts(rows), len(rows))
-
-
-def command_validate_ledger(args: argparse.Namespace) -> int:
-    rows = load_jsonl(args.file)
-    return print_validation("ledger", validate_ledger(rows), len(rows))
-
-
-def command_finalize(args: argparse.Namespace) -> int:
-    attempts = load_jsonl(args.attempts)
-    ledger = load_jsonl(args.ledger)
-    errors = validate_attempts(attempts) + validate_ledger(ledger)
-    if errors:
-        return print_validation("finalize", errors, len(attempts) + len(ledger))
-    normalized = [normalize_entry(row) for row in ledger]
-    pending_retests = retest_requests(normalized)
-    aggregates = aggregate_rows(normalized)
-    generated_candidates = candidate_rows(normalized, aggregates)
-    regeneration_candidates = [candidate for candidate in generated_candidates if candidate_content_errors(candidate)]
-    candidates = [candidate for candidate in generated_candidates if not candidate_content_errors(candidate)]
-    knowledge_root = getattr(args, "knowledge_root", None)
-    matches = match_existing_knowledge(candidates, knowledge_root)
-    args.output.mkdir(parents=True, exist_ok=True)
-    write_jsonl(args.output / "ledger.normalized.jsonl", normalized)
-    write_jsonl(args.output / "retest-required.jsonl", pending_retests)
-    write_jsonl(args.output / "operator-ledgers.jsonl", aggregates)
-    write_knowledge_matches(args.output, matches, knowledge_root)
-    write_regeneration_requests(args.output, regeneration_candidates)
-    write_candidate_pages(args.output, candidates, len(regeneration_candidates))
-    (args.output / "review.md").write_text(
-        review_report(attempts, normalized, aggregates, candidates, load_input_summary(args.attempts.parent)),
-        encoding="utf-8",
-    )
-    result = {
-        "attempts": len(attempts),
-        "ledger_entries": len(normalized),
-        "operator_ledgers": len(aggregates),
-        "knowledge_candidates": len(candidates),
-        "knowledge_regeneration_required": len(regeneration_candidates),
-        "retest_required": len(pending_retests),
-        "workflow_complete": not regeneration_candidates and not pending_retests,
-        "knowledge_matches": dict(Counter(match["match_status"] for match in matches)),
-        "output": str(args.output),
-    }
-    print(json.dumps(result, ensure_ascii=False, indent=2))
-    return 0
-
-
-def command_query(args: argparse.Namespace) -> int:
-    rows = [normalize_entry(row) for row in load_jsonl(args.file)]
-    selected = []
-    for row in rows:
-        if args.operator and row["address"].get("operator") != args.operator:
-            continue
-        if args.address_id and row.get("address_id") != args.address_id:
-            continue
-        if args.technique and (row.get("technique") or {}).get("family") != args.technique:
-            continue
-        if args.outcome and row.get("outcome") != args.outcome:
-            continue
-        if args.confidence and row.get("confidence") != args.confidence:
-            continue
-        selected.append(row)
-    selected.sort(
-        key=lambda row: (CONFIDENCE_ORDER.get(str(row.get("confidence")), 99), str(row.get("entry_id")))
-    )
-    for row in selected[: args.limit or None]:
-        print(json.dumps(row, ensure_ascii=False))
-    return 0
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description=__doc__)
-    commands = parser.add_subparsers(dest="command", required=True)
-    validate_attempts_parser = commands.add_parser("validate-attempts")
-    validate_attempts_parser.add_argument("file", type=Path)
-    validate_attempts_parser.set_defaults(func=command_validate_attempts)
-    validate_ledger_parser = commands.add_parser("validate-ledger")
-    validate_ledger_parser.add_argument("file", type=Path)
-    validate_ledger_parser.set_defaults(func=command_validate_ledger)
-    finalize_parser = commands.add_parser("finalize")
-    finalize_parser.add_argument("--attempts", required=True, type=Path)
-    finalize_parser.add_argument("--ledger", required=True, type=Path)
-    finalize_parser.add_argument("--output", required=True, type=Path)
-    finalize_parser.add_argument(
-        "--knowledge-root",
-        type=Path,
-        help="KernelWiki wiki/ directory used for stable knowledge and condition matching",
-    )
-    finalize_parser.set_defaults(func=command_finalize)
-    query_parser = commands.add_parser("query")
-    query_parser.add_argument("file", type=Path)
-    query_parser.add_argument("--operator")
-    query_parser.add_argument("--address-id")
-    query_parser.add_argument("--technique")
-    query_parser.add_argument("--outcome")
-    query_parser.add_argument(
-        "--confidence",
-        choices=["verified", "source-reported", "inferred", "experimental", "unknown"],
-    )
-    query_parser.add_argument("--limit", type=int)
-    query_parser.set_defaults(func=command_query)
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
-    try:
-        return args.func(args)
-    except (OSError, json.JSONDecodeError, ValueError) as error:
-        print(json.dumps({"error": str(error), "command": args.command}, ensure_ascii=False), file=sys.stderr)
-        return 2
-
-
-if __name__ == "__main__":
-    sys.exit(main())