第一次编译小智：固定源码、显式兼容补丁，只改一条日志

python tools/source_state.py verify-baseline
python tools/project.py configure
python tools/project.py build
python tools/project.py manifest

python tools/source_state.py diff
python tools/source_state.py change
python tools/source_state.py verify-changed
python tools/project.py build
python tools/project.py manifest

python tools/project.py flash --port /dev/cu.YOUR_BRIDGE_PORT
python tools/project.py monitor --port /dev/cu.YOUR_BRIDGE_PORT

python tools/source_state.py restore
python tools/source_state.py verify-baseline
python tools/project.py build

# ---- tools/source_state.py ----
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""One explicitly bounded log-text change, with whole tracked-tree verification."""
from pathlib import Path
import argparse
import difflib
import hashlib
import json

ROOT = Path(__file__).resolve().parents[1]
REL = "main/boards/bread-compact-wifi/compact_wifi_board.cc"
OLD = 'ESP_LOGI(TAG, "Install SSD1306 driver");'
NEW = 'ESP_LOGI(TAG, "A07 OLED driver: SSD1306");'


def expected_changed(original: str) -> str:
    if original.count(OLD) != 1:
        raise ValueError("Expected exactly one original log line")
    return original.replace(OLD, NEW)


def verify(state: str) -> None:
    meta = json.loads((ROOT / "UPSTREAM.json").read_text())
    compat = json.loads((ROOT / "COMPATIBILITY.json").read_text())
    audio = json.loads((ROOT / "AUDIO-COMPATIBILITY.json").read_text())
    for rel, expected_sha in meta["files"].items():
        data = (ROOT / "firmware" / rel).read_bytes()
        if state == "changed" and rel == REL:
            text = data.decode()
            if text.count(NEW) != 1 or OLD in text:
                raise ValueError("Selected file is not the single known change")
            data = text.replace(NEW, OLD).encode()
        if state != "upstream" and rel == REL:
            text = data.decode()
            if text.count(compat["patchedBlock"]) != 1:
                raise ValueError("Expected explicit IDF5.5.5 compatibility patch")
            data = text.replace(compat["patchedBlock"], compat["originalBlock"]).encode()
        if state != "upstream" and rel == audio["relativePath"]:
            text = data.decode()
            if text.count(audio["patchedLine"]) != 1:
                raise ValueError("Expected explicit MAX98357A supported16k output patch")
            data = text.replace(audio["patchedLine"], audio["originalLine"]).encode()
        if hashlib.sha256(data).hexdigest() != expected_sha:
            raise ValueError(f"Unexpected tracked source modification: {rel}")
    print(f"PASS {len(meta['files'])} original tracked files, state={state}")


def main() -> None:
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("action", choices=["verify-upstream", "apply-compat", "remove-compat", "verify-baseline", "change", "verify-changed", "restore", "diff"])
    args = p.parse_args()
    target = ROOT / "firmware" / REL
    if args.action in ["verify-upstream", "apply-compat"]:
        verify("upstream")
    elif args.action in ["verify-baseline", "change", "diff", "remove-compat"]:
        verify("baseline")
    else:
        verify("changed")
    if args.action in ["apply-compat", "remove-compat"]:
        compat = json.loads((ROOT / "COMPATIBILITY.json").read_text())
        audio = json.loads((ROOT / "AUDIO-COMPATIBILITY.json").read_text())
        before, after = compat["originalBlock"], compat["patchedBlock"]
        if args.action == "remove-compat":
            before, after = after, before
        text = target.read_text()
        if text.count(before) != 1:
            raise ValueError("Compatibility block differs; no file changed")
        audio_target = ROOT / "firmware" / audio["relativePath"]
        audio_before, audio_after = audio["originalLine"], audio["patchedLine"]
        if args.action == "remove-compat":
            audio_before, audio_after = audio_after, audio_before
        audio_text = audio_target.read_text()
        if audio_text.count(audio_before) != 1:
            raise ValueError("Audio compatibility line differs; no file changed")
        target.write_text(text.replace(before, after))
        audio_target.write_text(audio_text.replace(audio_before, audio_after))
        verify("baseline" if args.action == "apply-compat" else "upstream")
    elif args.action == "change":
        target.write_text(expected_changed(target.read_text()))
        verify("changed")
    elif args.action == "restore":
        target.write_text(target.read_text().replace(NEW, OLD))
        verify("baseline")
    elif args.action == "diff":
        original = target.read_text()
        print("".join(difflib.unified_diff(original.splitlines(True), expected_changed(original).splitlines(True), fromfile="a/"+REL, tofile="b/"+REL)), end="")


if __name__ == "__main__":
    main()

# ---- tools/project.py ----
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Use an already activated IDF5.5.5; record inputs and refuse stale-image manifests."""
from pathlib import Path
import argparse
import datetime
import hashlib
import json
import os
import subprocess
import sys

ROOT = Path(__file__).resolve().parents[1]
BUILD = ROOT / 'build'
SOURCE = ROOT / 'firmware'


def fingerprint(path: Path) -> dict:
    return {'path': str(path.resolve()), 'bytes': path.stat().st_size,
            'sha256': hashlib.sha256(path.read_bytes()).hexdigest()}


def inputs() -> list[dict]:
    # Includes generated language header and the resolver lock when present.
    files = [p for p in SOURCE.rglob('*') if p.is_file() and
             'managed_components' not in p.parts and '__pycache__' not in p.parts]
    files += [ROOT/'configs/lab.defaults', BUILD/'sdkconfig']
    if any(not p.is_file() for p in files):
        raise SystemExit('Configure first; missing configuration input')
    return [fingerprint(p) for p in sorted(set(files))]


def products() -> list[dict]:
    files = [p for p in BUILD.rglob('*') if p.is_file() and
             (p.suffix in ['.bin', '.elf', '.map'] or p.name in
              ['sdkconfig', 'flasher_args.json', 'flash_args', 'project_description.json',
               'compile_commands.json'])]
    return [fingerprint(p) for p in sorted(files)]


def run(command: list[str], label: str) -> dict:
    logs = ROOT/'local-logs'
    logs.mkdir(exist_ok=True)
    stamp = datetime.datetime.now(datetime.timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')
    output = logs/f'{stamp}-{label}.log'
    with output.open('wb') as stream:
        stream.write(('COMMAND '+json.dumps(command)+'\n').encode())
        stream.flush()
        process = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
        assert process.stdout is not None
        for line in process.stdout:
            stream.write(line)
            stream.flush()
            sys.stdout.buffer.write(line)
            sys.stdout.buffer.flush()
        code = process.wait()
        stream.write(f'\nEXIT {code}\n'.encode())
    record = {'command': command, 'exit': code, 'log': fingerprint(output)}
    output.with_suffix('.json').write_text(json.dumps(record, indent=2))
    if code:
        raise SystemExit(code)
    return record


def current_success() -> dict:
    record = ROOT/'local-last-success.json'
    if not record.is_file():
        raise SystemExit('No successful build recorded by this tool; existing bins are insufficient')
    value = json.loads(record.read_text())
    if value['inputs'] != inputs() or value['products'] != products():
        raise SystemExit('Inputs/products changed since the recorded build; rebuild before manifest/flash')
    for step in value['commands']:
        log = Path(step['log']['path'])
        if fingerprint(log) != step['log']:
            raise SystemExit('Recorded build log missing or changed')
    return value


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('action', choices=['configure', 'build', 'manifest', 'flash', 'monitor'])
    parser.add_argument('--port')
    args = parser.parse_args()
    sdk = os.environ.get('IDF_PATH')
    if not sdk or not (Path(sdk)/'tools/idf.py').is_file():
        raise SystemExit('Activate ESP-IDF5.5.5 first; this tool does not install an SDK')
    idf = [sys.executable, str(Path(sdk)/'tools/idf.py')]
    version = subprocess.check_output(idf+['--version'], text=True).strip()
    if version != 'ESP-IDF v5.5.5':
        raise SystemExit('Wrong SDK: '+version+'; expected ESP-IDF v5.5.5')
    base = idf+['-C', str(SOURCE.resolve()), '-B', str(BUILD.resolve()),
                '-D', 'SDKCONFIG='+str((BUILD/'sdkconfig').resolve())]
    if args.action == 'configure':
        run(base+['-D', 'IDF_TARGET=esp32s3', '-D',
                  'SDKCONFIG_DEFAULTS='+str(SOURCE/'sdkconfig.defaults')+';'+str(ROOT/'configs/lab.defaults'),
                  'reconfigure'], 'configure')
    elif args.action == 'build':
        # Fixed upstream ALL target lacks an explicit main-component dependency.
        language = run(base+['lang_header'], 'lang-header')
        before = inputs()
        build = run(base+['build'], 'build')
        if inputs() != before:
            raise SystemExit('Inputs changed during the build; no success record emitted')
        result = products()
        if not any(Path(p['path']).name == 'xiaozhi.bin' for p in result):
            raise SystemExit('Expected application image missing')
        (ROOT/'local-last-success.json').write_text(json.dumps({
            'version': version, 'inputs': before, 'products': result,
            'commands': [language, build], 'hardware': 'not executed by this tool'}, indent=2))
    elif args.action == 'manifest':
        value = current_success()
        value['upstream'] = json.loads((ROOT/'UPSTREAM.json').read_text())['commit']
        (ROOT/'local-products.json').write_text(json.dumps(value, indent=2))
        print(ROOT/'local-products.json')
    else:
        if not args.port:
            raise SystemExit('Provide the physical USB-UART bridge --port')
        if args.action == 'flash':
            current_success()
        run(base+['-p', args.port, args.action], args.action)


if __name__ == '__main__':
    main()