"""Human-only annotation assistant with preserved source splits and a mixed GUI package.

Original val/test labels are allowed only in an explicitly scoped auxiliary manifest.
This branch never publishes independent research-test scores.
"""
from __future__ import annotations

import argparse
from collections import Counter, defaultdict
from copy import deepcopy
from datetime import datetime
import fcntl
import hashlib
import json
from pathlib import Path, PurePosixPath
import threading
import traceback
import zipfile
from zoneinfo import ZoneInfo

import numpy as np
from PIL import Image

from pallet.annotation import (FrameAnnotation, Provenance, SceneAttributes,
                               annotation_digest, load_jsonl)
from pallet.clean_intensity_review import safe_bytes, safe_copy, safe_json, reserve
from pallet.data.eligibility import require_eligible
from pallet.data.protocol import file_digest, load_protocol, write_json
from pallet.human_labeling import (AUXILIARY_SCOPE, _load_frame_index, _decode_rectangles,
    _validated_manual_partition, create_manual_validation_partition,
    train_manual_validation_assistant, calibrate_threshold, predict_remaining,
    package_candidates, audit_candidate_package)
from pallet.manual_update import validate_document

ROOT = Path(__file__).resolve().parents[1]
DEFAULT_CONFIG = ROOT/'configs/human_correction_7086.json'


def read(path):
    return json.loads(Path(path).read_text())


def rows(path):
    return [json.loads(line) for line in Path(path).read_text().splitlines() if line]


def now():
    return datetime.now(ZoneInfo('Asia/Shanghai')).isoformat()


def normalize_coordinate_roundoff(document, *, tolerance=1e-9):
    """Snap only floating-point noise at image edges, with an explicit change receipt."""
    corrected = deepcopy(document)
    changes = []
    limits = (document['imageWidth'], document['imageHeight'])
    for shape_index, shape in enumerate(corrected.get('shapes', [])):
        for point_index, point in enumerate(shape.get('points', [])):
            for axis, limit in enumerate(limits):
                value = point[axis]
                edge = 0 if -tolerance <= value < 0 else limit if limit < value <= limit+tolerance else None
                if edge is not None:
                    point[axis] = edge
                    changes.append({'shape': shape_index, 'point': point_index, 'axis': axis,
                                    'original': value, 'normalized': edge})
    return corrected, changes


def ingest(config_path):
    """Import exact returned identities; preserve original splits and every raw JSON."""
    config_path = Path(config_path).resolve()
    config = read(config_path)
    for key in ('all_frames_reviewed_by_user', 'unchanged_proposals_accepted_after_manual_review',
                'empty_frames_confirmed_negative_by_user'):
        if config.get(key) is not True:
            raise ValueError(f'Awaiting explicit user confirmation: {key}')
    if config.get('scope') != AUXILIARY_SCOPE or config.get('use_original_test_for_assistance') is not True:
        raise ValueError('cross-split import requires the explicit annotation-assistance scope')
    output, protocol = Path(config['output']), Path(config['protocol'])
    base, archive, source = map(Path, (config['base_output'], config['archive'], config['source_export']))
    paths = [config_path, protocol/'protocol.json', base/'inputs/annotations.jsonl',
             base/'inputs/all_checked_annotations.jsonl', base/'manual_partition.json',
             base/'inputs/checked_external_annotations.jsonl', base/'inputs/external_review_receipt.json',
             base/'inputs/reviewed_external_exclusion.json', archive,
             source/'frames.jsonl', source/'package_manifest.json']
    confirmation_path = config.get('confirmation_record')
    if confirmation_path:
        confirmation_path = Path(confirmation_path)
        if file_digest(confirmation_path) != config.get('confirmation_record_sha256'):
            raise ValueError('Human review convention record changed')
        paths.append(confirmation_path)
    binding = {str(path.resolve()): file_digest(path) for path in paths}
    completion = output/'manual_import_manifest.json'
    if completion.exists():
        imported = read(completion)
        if imported['input_binding'] != binding:
            raise ValueError('assistant import inputs changed; use a new output version')
        for name, digest in imported['artifact_sha256'].items():
            if file_digest(output/name) != digest:
                raise ValueError(f'Human snapshot changed: {name}')
        return imported
    records, assignments, _ = load_protocol(protocol)
    by_id = {r.frame_id: r for r in records}
    source_manifest, source_index, by_filename, manifest_sha, index_sha = _load_frame_index(source)
    if source_manifest.get('prediction_binding', {}).get('protocol_sha256') != file_digest(protocol/'protocol.json'):
        raise ValueError('returned corrections do not reference the active oriented protocol')
    eligible = load_jsonl(base/'inputs/annotations.jsonl').frames.copy()
    checked = load_jsonl(base/'inputs/all_checked_annotations.jsonl').frames.copy()
    partition = read(base/'manual_partition.json')
    for name, digest in partition.get('artifact_sha256', {}).items():
        if file_digest(base/name) != digest:
            raise ValueError(f'Parent human snapshot changed: {name}')
    base_entries = {**read(base/'inputs/human_training_manifest.json')['source_frames'],
                    **read(base/'inputs/human_validation_manifest.json')['source_frames']}
    incoming, incoming_entries, raw_json, differences = {}, {}, {}, []
    archive_sha = file_digest(archive)
    allowed_splits = set(config.get('allowed_source_splits', ['test']))
    if not allowed_splits or not allowed_splits <= {'train', 'val', 'test'}:
        raise ValueError('Invalid original source-split policy')
    with zipfile.ZipFile(archive) as z:
        if z.testzip() is not None:
            raise ValueError('ZIP CRC failed')
        members = [item for item in z.infolist() if not item.is_dir()]
        if len(members) != config['expected_new_frames']:
            raise ValueError('Unexpected number of returned corrections')
        names = set()
        for item in members:
            path = PurePosixPath(item.filename)
            if path.is_absolute() or '..' in path.parts or path.suffix.lower() != '.json' or item.filename in names:
                raise ValueError(f'Unsafe, duplicate or unexpected archive member: {item.filename}')
            names.add(item.filename)
            row = by_filename.get(path.name)
            if row is None:
                raise ValueError(f'Unknown returned image: {item.filename}')
            fid = row['frame_id']
            if fid in checked or fid in incoming or fid not in by_id:
                raise ValueError(f'Duplicate or inactive returned frame: {fid}')
            record = by_id[fid]
            require_eligible(record)
            split = assignments[record.group_id]
            if split not in allowed_splits or row['split'] != split:
                raise ValueError(f'Original source split is outside the allowed assistant inputs: {fid}')
            document = json.loads(z.read(item))
            baseline = read(source/row['annotation'])
            document, roundoff = normalize_coordinate_roundoff(document)
            boxes = validate_document(document, baseline, row, source, record)
            expected_rotation = record.sensor_config.get('pixel_rotation_degrees', 0)
            meta = document.get('pallet_prediction') or document.get('pallet_export') or {}
            prior_meta = baseline.get('pallet_prediction') or baseline.get('pallet_export') or {}
            for key, expected in [('group_id', record.group_id), ('original_split', split)]:
                if key in prior_meta and (prior_meta[key] != expected or meta.get(key) != expected):
                    raise ValueError(f'Correction {key} identity mismatch: {fid}')
            if meta.get('pixel_rotation_degrees', 0) != expected_rotation:
                raise ValueError(f'Correction orientation identity mismatch: {fid}')
            frame = FrameAnnotation(fid, record.group_id, row['image'], *row['size'],
                status='pos' if boxes else 'negative', boxes=boxes, split=split, domain=record.domain,
                scene=SceneAttributes(domain=record.domain), source_anchor_hash=record.source_sha256,
                provenance=[Provenance('human', actor='user_confirmed_archive_import',
                    note=f'user-reviewed correction from original {split}; archive={archive.name}; sha256={archive_sha}; auxiliary only')])
            frame.validate()
            incoming[fid] = frame
            unchanged = boxes == _decode_rectangles(baseline, *row['size'])
            incoming_entries[fid] = {'frame_id': fid, 'group_id': record.group_id, 'split': split,
                'source_anchor_hash': record.source_sha256, 'width': frame.width, 'height': frame.height,
                'domain': record.domain, 'status': frame.status, 'instances': len(boxes),
                'annotation_digest': annotation_digest(frame), 'archive': str(archive), 'archive_sha256': archive_sha,
                'source_export': str(source), 'source_json_sha256': hashlib.sha256(z.read(item)).hexdigest(),
                'baseline_source_json_sha256': file_digest(source/row['annotation']),
                'source_export_manifest_sha256': manifest_sha, 'geometry_unchanged_from_proposal': unchanged}
            raw_json[path.name] = z.read(item)
            differences.append({'frame_id': fid, 'group_id': record.group_id, 'domain': record.domain,
                'original_split': split, 'old_boxes': len(baseline['shapes']), 'human_boxes': len(boxes),
                'geometry_unchanged_after_review': unchanged, 'old_flags': baseline.get('flags'),
                'returned_flags': document.get('flags'), 'accepted_status': frame.status,
                'coordinate_roundoff_normalization': roundoff})
    eligible.update(incoming)
    checked.update(incoming)
    for frame in eligible.values():
        record = by_id.get(frame.frame_id)
        if (record is None or frame.split != assignments[record.group_id]
                or frame.group_id != record.group_id or frame.source_anchor_hash != record.source_sha256):
            raise ValueError('Base/new human identity or original split changed')
        require_eligible(record)
    summary = {'archive': str(archive), 'archive_sha256': archive_sha, 'frames': len(incoming),
        'status_counts': dict(Counter(f.status for f in incoming.values())),
        'boxes': sum(len(f.boxes) for f in incoming.values()),
        'geometry_unchanged': sum(d['geometry_unchanged_after_review'] for d in differences),
        'domains': dict(Counter(f.domain for f in incoming.values())),
        'source_splits': dict(Counter(f.split for f in incoming.values())), 'scope': AUXILIARY_SCOPE}
    output.mkdir(parents=True, exist_ok=True)
    inputs = output/'inputs'
    def snapshot(path, frames):
        # Keep partial imports recoverable without overwriting human edits.
        from dataclasses import asdict
        safe_bytes(path, ''.join(json.dumps(asdict(frame), ensure_ascii=False, sort_keys=True)+'\n'
                                  for frame in sorted(frames.values(), key=lambda f: f.frame_id)).encode())
    snapshot(inputs/'manual_annotations.jsonl', eligible)
    snapshot(inputs/'all_checked_annotations.jsonl', checked)
    safe_json(inputs/'manual_source_frames.json', {**base_entries, **incoming_entries})
    safe_json(inputs/'new_archive_summary.json', summary)
    safe_json(inputs/'correction_differences.json', differences)
    safe_copy(config_path, inputs/'corrections_config.json')
    safe_copy(archive, inputs/'source_archives'/archive.name)
    for name, payload in raw_json.items():
        safe_bytes(inputs/'raw_returned_json'/archive.stem/name, payload)
    for name in ('checked_external_annotations.jsonl', 'external_review_receipt.json', 'reviewed_external_exclusion.json'):
        safe_copy(base/'inputs'/name, inputs/name)
    digest = hashlib.sha256(json.dumps(binding, sort_keys=True).encode()).hexdigest()
    imported = {'kind': 'cross_split_user_confirmed_annotation_assistant_import', 'state': 'imported',
        'scope': AUXILIARY_SCOPE, 'original_splits_preserved': True, 'eligible_for_research_evaluation': False,
        'input_binding': binding, 'source_archive_set_sha256': digest,
        'protocol_sha256': file_digest(protocol/'protocol.json'), 'frame_count': len(eligible),
        'all_checked_frames': len(checked), 'external_checked_frames': len(checked)-len(eligible),
        'status_counts': dict(Counter(f.status for f in eligible.values())),
        'box_count': sum(len(f.boxes) for f in eligible.values()),
        'group_count': len({f.group_id for f in eligible.values()}),
        'sources': partition['source_archives']+[summary], 'new_source': summary,
        'all_frames_reviewed_by_user': True, 'empty_frames_confirmed_negative_by_user': True,
        'reviewer_count_claimed': 1,
        'artifact_sha256': {str(p.relative_to(output)): file_digest(p) for p in inputs.rglob('*') if p.is_file()}}
    safe_json(completion, imported)
    return imported


def proportional_order(items, key, *, seed=42):
    """Spread each source stratum through the queue, without duplicates or oversampling."""
    buckets = defaultdict(list)
    for item in items:
        buckets[key(item)].append(item)
    for values in buckets.values():
        values.sort(key=lambda row: hashlib.sha256(f'{seed}|{row["frame_id"]}'.encode()).hexdigest())
    totals = {k: len(v) for k, v in buckets.items()}
    taken = Counter()
    result = []
    while buckets:
        k = min(buckets, key=lambda x: ((taken[x]+.5)/totals[x], str(x)))
        result.append(buckets[k][taken[k]])
        taken[k] += 1
        if taken[k] == totals[k]:
            del buckets[k]
    return result


def mixed_order(items, *, seed=42):
    # First spread acquisition groups within each domain/source split, then spread
    # domains/source splits in proportion to the actual remaining population.
    strata = defaultdict(list)
    for item in items:
        strata[(item['split'], item['domain'])].append(item)
    queues = {k: proportional_order(v, lambda r: r['group_id'], seed=seed) for k, v in strata.items()}
    totals = {k: len(v) for k, v in queues.items()}
    taken, result = Counter(), []
    while queues:
        k = min(queues, key=lambda x: ((taken[x]+.5)/totals[x], str(x)))
        result.append(queues[k][taken[k]])
        taken[k] += 1
        if taken[k] == totals[k]:
            del queues[k]
    return result


def validate_zip_payload(archive, workspace):
    files = {str(p.relative_to(workspace)): p for p in Path(workspace).rglob('*') if p.is_file()}
    with zipfile.ZipFile(archive) as z:
        if z.testzip() is not None or len(z.namelist()) != len(files) or set(z.namelist()) != set(files):
            raise ValueError('mixed ZIP CRC or exact member coverage failed')
        for name, path in files.items():
            if hashlib.sha256(z.read(name)).hexdigest() != file_digest(path):
                raise ValueError(f'mixed ZIP payload differs: {name}')
    return {'crc': 'passed', 'member_payload_sha256': 'passed', 'members': len(files)}


def make_mixed_package(output, protocol):
    """Copy only predictions into a single ordered GUI folder, preserving original identity."""
    output, protocol = Path(output), Path(protocol)
    source, target = output/'anylabeling', output/'mixed_anylabeling'
    parent = read(source/'package_manifest.json')
    original = rows(source/'frames.jsonl')
    plan = {'source_manifest_sha256': file_digest(source/'package_manifest.json'),
            'source_index_sha256': file_digest(source/'frames.jsonl'),
            'algorithm': 'proportional_split_domain_then_group_v1', 'seed': 42}
    safe_json(output/'mixed_package_plan.json', plan)
    index = []
    for ordinal, row in enumerate(mixed_order(original), 1):
        reserve()
        item = deepcopy(row)
        key = f'{ordinal:06d}_{Path(row["image"]).stem}'
        doc = read(source/row['annotation'])
        for role, suffix, folder in [('image', '.png', 'images'), ('depth', '.depth.png', 'auxiliary'),
                                     ('validity', '.valid.png', 'auxiliary')]:
            item[role] = str(Path(folder)/'mixed'/f'{key}{suffix}')
            safe_copy(source/row[role], target/item[role])
        item['annotation'] = str(Path('images/mixed')/f'{key}.json')
        item['original_image'] = row['image']
        item['original_split'] = row['split']
        item['review_order'] = ordinal
        doc['imagePath'] = f'{key}.png'
        doc['pallet_prediction'].update(original_split=row['split'], review_order=ordinal,
                                       scope=AUXILIARY_SCOPE, independent_reference=False)
        # Prediction frames keep the native pixel orientation already in v7.
        safe_json(target/item['annotation'], doc)
        item['baseline_annotation_sha256'] = file_digest(target/item['annotation'])
        index.append(item)
    # This version is immutable once used for manual review.
    text = ''.join(json.dumps(row, ensure_ascii=False, sort_keys=True)+'\n' for row in index)
    safe_bytes(target/'frames.jsonl', text.encode())
    safe_copy(source/'labels.txt', target/'labels.txt')
    safe_copy(source/'anylabeling_config.yaml', target/'anylabeling_config.yaml')
    safe_json(target/'package_manifest.json', {**parent, 'presentation': 'single_mixed_review_folder',
        'original_splits_preserved': True, 'original_groups_preserved': True,
        'scope': AUXILIARY_SCOPE, 'mixing': plan,
        'frames_index_sha256': file_digest(target/'frames.jsonl')})
    safe_bytes(target/'README_人工修正.md', (
        f'本包含{len(index)}张尚未人工检查图像。只打开 images/mixed，按文件名顺序逐帧修正同名JSON。\n'
        '各原始划分、配置域及采集组按真实剩余数量交错排列；不复制或重划分帧。\n'
        '数字前缀仅为检查顺序；原始split/group_id/frame_id及源哈希保存在JSON和frames.jsonl。\n'
        '请保留文件名、尺寸及源身份字段。辅助图在auxiliary/mixed，坐标与主图一致。\n'
        '所有框是辅助模型建议，零检测仍待审，不能自动视为负例。\n'
        '该模型额外使用人工检查的原val/test帧训练，供人工标注使用，不作为正式独立测试结果。\n'
        '240×96方向已校正180度；148张不可恢复黑图及全部已检查人工帧不在本包。\n').encode())
    _load_frame_index(target)
    original_by_id = {row['frame_id']: row for row in original}
    for item in index:
        old = original_by_id[item['frame_id']]
        if any(item[k] != old[k] for k in ('frame_id', 'group_id', 'split', 'domain', 'source_anchor_hash')):
            raise ValueError('Mixed presentation changed acquisition identity')
        doc = read(target/item['annotation'])
        source_doc = read(source/old['annotation'])
        if doc['shapes'] != source_doc['shapes'] or doc['flags'] != source_doc['flags']:
            raise ValueError('Mixed presentation changed candidate labels')
        for role in ('image', 'depth', 'validity'):
            if file_digest(target/item[role]) != file_digest(source/old[role]):
                raise ValueError('Mixed presentation changed pixels')
        with Image.open(target/item['image']) as image:
            if np.asarray(image).max() == 0:
                raise ValueError('Unexpected black primary image')
        _decode_rectangles(doc, doc['imageWidth'], doc['imageHeight'])
    checked = set(load_jsonl(output/'inputs/all_checked_annotations.jsonl').frames)
    if {r['frame_id'] for r in index} & checked:
        raise ValueError('Human reviewed frame repeated in mixed package')
    archive = output/f'human_correction_remaining_{len(index)}_mixed_v1.zip'
    if not archive.exists():
        reserve()
        temporary = archive.with_suffix('.zip.tmp')
        with zipfile.ZipFile(temporary, 'w', zipfile.ZIP_DEFLATED, compresslevel=4) as z:
            for path in sorted(target.rglob('*')):
                if path.is_file():
                    z.write(path, str(path.relative_to(target)))
        temporary.replace(archive)
    audit = {'state': 'passed', 'frames': len(index), 'manual_overlap': 0,
        'original_splits_preserved': True, 'original_groups_preserved': True,
        'pixel_and_box_coordinates_unchanged': True, 'single_gui_folder': 'images/mixed',
        'split_counts': dict(Counter(r['split'] for r in index)), 'zip': validate_zip_payload(archive, target),
        'archive': str(archive), 'archive_sha256': file_digest(archive), 'archive_bytes': archive.stat().st_size}
    safe_json(output/'mixed_package_audit.json', audit)
    return audit


def status(output, stage, **extra):
    result = {'state': 'running', 'stage': stage, 'updated_at': now(), 'scope': AUXILIARY_SCOPE,
              'output': str(output), **extra}
    path = output/'training/metrics.jsonl'
    if path.exists():
        metrics = []
        for line in path.read_text().splitlines():
            try:
                metrics.append(json.loads(line))
            except json.JSONDecodeError:
                continue
        if metrics:
            best = max(metrics, key=lambda r: r['validation']['AP50_95'])
            result.update(completed_epochs=len(metrics), best_epoch=best['epoch'],
                          best_internal_validation_AP50_95=best['validation']['AP50_95'])
            if len(metrics) >= 10:
                seconds = float(np.median([r['epoch_seconds'] for r in metrics[:10]]))
                result.update(first_ten_epochs_median_seconds=seconds,
                              max_remaining_training_seconds=(300-len(metrics))*seconds)
    for filename, key in [('merge_summary.json', 'manual_merge'), ('prediction_manifest.json', 'prediction')]:
        if (output/filename).exists():
            result[key] = read(output/filename)
    write_json(output/'workflow_status.json', result)
    return result


def deliver(output, config):
    audit = read(output/'mixed_package_audit.json')
    completion = read(output/'training/completed.json')
    threshold = read(output/'confidence_threshold.json')
    partition = read(output/'manual_partition.json')
    prediction = read(output/'prediction_manifest.json')
    metrics = rows(output/'training/metrics.jsonl')
    best = max(metrics, key=lambda r: r['validation']['AP50_95'])
    if (prediction['state'] != 'complete' or prediction['errors'] != 0
            or prediction['completed_frames'] != audit['frames']
            or file_digest(output/'training/best.pt') != completion['best_checkpoint_sha256']
            or completion['best_checkpoint_sha256'] != threshold['checkpoint_sha256']
            or threshold['checkpoint_sha256'] != prediction['checkpoint_sha256']
            or set(partition['train_groups']) & set(partition['validation_groups'])):
        raise ValueError('Final assistant delivery checks failed')
    existing = read(output/'delivery_manifest.json') if (output/'delivery_manifest.json').exists() else None
    manifest = {'state': 'complete', 'completed_at': existing['completed_at'] if existing else now(), 'scope': AUXILIARY_SCOPE,
        'archive': audit['archive'], 'archive_sha256': audit['archive_sha256'], 'package_audit': audit,
        'training': completion, 'threshold': threshold, 'checkpoint': str(output/'training/best.pt'),
        'best_epoch': best['epoch'], 'best_internal_validation': best['validation'],
        'manual_merge': read(output/'merge_summary.json'), 'original_splits_preserved': True,
        'original_groups_preserved': True, 'eligible_for_research_evaluation': False}
    safe_json(output/'delivery_manifest.json', manifest)
    control_path = ROOT/'configs/active_dataset.json'
    control = read(control_path)
    if control['protocol'] != config['protocol']:
        raise ValueError('Active protocol changed while workflow was running')
    control.update(remaining_review_package=audit['archive'], latest_review_source=str(output/'mixed_anylabeling'),
        latest_assistant_checkpoint=str(output/'training/best.pt'), latest_assistant_delivery=str(output/'delivery_manifest.json'),
        human_training=str(output))
    write_json(control_path, control)
    write_json(ROOT/'outputs/anylabeling_latest.json', {'kind': 'mixed_annotation_assistant_delivery',
        'delivery': str(output/'delivery_manifest.json'), 'protocol': config['protocol'],
        'remaining_review_package': audit['archive'], 'review_source': str(output/'mixed_anylabeling')})
    report = (f'# 累计人工标签与混合修正包\n\n完成时间：{manifest["completed_at"]}。\n\n'
        f'原分组/划分不变；新增{config["expected_new_frames"]}张返回人工帧仅用于辅助标注分支，'
        f'原始来源为{manifest["manual_merge"]["new_source"]["source_splits"]}。'
        f'全部人工检查帧{manifest["manual_merge"]["all_checked_frames"]}张；辅助训练池{partition["expected_manual_frames"]}张，'
        f'按组分为{len(partition["train_frame_ids"])}训练、{len(partition["validation_frame_ids"])}内部验证。\n\n'
        f'训练实际{completion["completed_epochs"]}轮。最佳内部验证及阈值完整记录见`{output.relative_to(ROOT)}/delivery_manifest.json`。'
        '未见过的配置域若只有一个独立采集组，则全部用于训练，不能报告该域的独立验证准确率。\n\n'
        f'最佳为第{best["epoch"]+1}轮（日志epoch={best["epoch"]}）；内部人工验证AP50/AP75/AP50:95='
        f'{best["validation"]["AP50"]:.5f}/{best["validation"]["AP75"]:.5f}/{best["validation"]["AP50_95"]:.5f}。'
        f'候选阈值{threshold["selected_confidence"]:.2f}，验证召回{threshold["selected_validation_metrics"]["recall"]:.5f}。\n\n'
        f'[{audit["frames"]}帧混合修正ZIP](../{Path(audit["archive"]).relative_to(ROOT)})：只打开`images/mixed`。'
        '文件名前缀按原始划分、配置域与采集组交错，JSON/索引保留原身份。零预测仍待审。\n\n'
        f'ZIP SHA-256：`{audit["archive_sha256"]}`。CRC与逐成员内容哈希、全量图像/JSON/辅助图一致性通过。\n\n'
        '这些已辅助训练的原val/test帧及剩余候选不能作为本模型的独立研究测试参考；历史快照保持不变。\n')
    report_path = ROOT/config.get('report_path', 'docs/human_correction_7086_report.md')
    report_path.parent.mkdir(parents=True, exist_ok=True)
    report_path.write_text(report)
    marker = f'<!-- assistant-delivery:{output.name} -->'
    for name in ('training_log.md', 'debug_log.md', 'change_log.md', 'session_summary.md'):
        path = ROOT/'docs'/name
        text = path.read_text()
        if marker not in text:
            path.write_text(text+f'\n\n{marker}\n'+report)
    latest = ROOT/'docs/human_correction_latest_report.md'
    previous_report = Path(config.get('previous_report', 'docs/human_correction_6552_report.md')).name
    latest.write_text(report+f'\n\n历史报告见[上一轮]({previous_report})。\n')
    readme = ROOT/'README.md'
    text = readme.read_text()
    if marker not in text:
        readme.write_text(f'{marker}\n最新人工标注交付：[{audit["frames"]}帧混合修正包]({Path(audit["archive"]).relative_to(ROOT)})。'
                         '原分组不变，使用`images/mixed`继续检查。\n\n'+text)
    write_json(output/'workflow_status.json', {**manifest, 'stage': 'complete'})
    return manifest


def run(config_path, *, prepare_only=False):
    config = read(config_path)
    output, protocol = Path(config['output']), Path(config['protocol'])
    imported = ingest(config_path)
    partition = create_manual_validation_partition(source_output=output, output=output, protocol=protocol,
                                                  seed=42, validation_fraction=.15)
    _validated_manual_partition(output, protocol)
    records, assignments, _ = load_protocol(protocol)
    checked = set(load_jsonl(output/'inputs/all_checked_annotations.jsonl').frames)
    summary = {'eligible_manual_frames': imported['frame_count'], 'all_checked_frames': len(checked),
        'checked_external_excluded_from_fitting': imported['external_checked_frames'],
        'new_source': imported['new_source'], 'training_frames': len(partition['train_frame_ids']),
        'validation_frames': len(partition['validation_frame_ids']), 'status_counts': partition['status_counts'],
        'domain_counts': partition['domain_counts'], 'positive_boxes': partition['positive_boxes'],
        'remaining': dict(Counter(assignments[r.group_id] for r in records if r.frame_id not in checked)),
        'scope': AUXILIARY_SCOPE, 'original_splits_preserved': True}
    safe_json(output/'merge_summary.json', summary)
    if prepare_only:
        status(output, 'prepared', state='prepared')
        print(json.dumps(summary, ensure_ascii=False, indent=2), flush=True)
        return summary
    done = threading.Event()
    stage = ['training']
    def heartbeat():
        while not done.wait(30):
            try:
                status(output, stage[0])
            except Exception as error:
                print(f'Heartbeat retry: {error}', flush=True)
    monitor = threading.Thread(target=heartbeat, daemon=True)
    monitor.start()
    try:
        status(output, 'training')
        runtime = config['runtime']
        train_manual_validation_assistant(output=output, protocol=protocol, device=config['device'],
            epochs=300, batch_size=runtime['batch_size'], workers=runtime['workers'],
            validation_batch_size=runtime['validation_batch_size'])
        stage[0] = 'calibrating'
        status(output, stage[0])
        calibrate_threshold(output=output, protocol=protocol, device=config['device'])
        stage[0] = 'predicting'
        status(output, stage[0])
        predict_remaining(output=output, protocol=protocol, source_export=config['prediction_source_export'],
                          device=config['device'], batch_size=runtime['prediction_batch_size'])
        stage[0] = 'packaging'
        status(output, stage[0])
        package_candidates(output=output, protocol=protocol, source_export=config['prediction_source_export'],
                           include_zip=False)
        audit_candidate_package(output=output, protocol=protocol, source_export=config['prediction_source_export'])
        make_mixed_package(output, protocol)
        done.set()
        monitor.join()
        return deliver(output, config)
    except Exception as error:
        done.set()
        monitor.join()
        status(output, stage[0], state='failed_resumable', error=str(error))
        traceback.print_exc()
        raise


def main():
    parser = argparse.ArgumentParser(__doc__)
    parser.add_argument('--config', default=str(DEFAULT_CONFIG))
    parser.add_argument('--prepare-only', action='store_true')
    args = parser.parse_args()
    config = read(args.config)
    output = Path(config['output'])
    output.mkdir(parents=True, exist_ok=True)
    with (output/'workflow.lock').open('w') as lock:
        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
        print(json.dumps(run(args.config, prepare_only=args.prepare_only), ensure_ascii=False), flush=True)


if __name__ == '__main__':
    main()
