Skip to content

Eriemon/verilog-generator

readable-verilog-generator

Verified

Use when creating, writing, reviewing, annotating, repairing, refactoring, or validating readable Verilog RTL, including synthesizable Verilog-2001 .v files, existing-RTL analysis, semantic comment annotation, testbench scaffold planning, ASIC-quality review, local or remote Vivado/xsim validation, evidence-backed repair, and workflow trace diagnosis.

FileKindSize
SKILL.mdskill md21.3 KB
agents/openai.yamlconfig363 B
assets/examples/existing_rtl/fsm_without_default.vother761 B
assets/examples/existing_rtl/fsm_without_default_spec.mdmarkdown311 B
assets/examples/existing_rtl/leaf_counter.vother314 B
assets/examples/existing_rtl/missing_output_register.vother423 B
assets/examples/existing_rtl/missing_output_register_spec.mdmarkdown331 B
assets/examples/existing_rtl/ready_valid_slice.vother967 B
assets/examples/existing_rtl/ready_valid_slice_spec.mdmarkdown420 B
assets/examples/existing_rtl/reset_gap_counter.vother319 B
assets/examples/existing_rtl/reset_gap_counter_spec.mdmarkdown212 B
assets/examples/existing_rtl/tb_ready_valid_slice.vother846 B
assets/examples/existing_rtl/top_counter.vother271 B
assets/examples/existing_rtl/traffic_light.vother2.5 KB
assets/examples/existing_rtl/traffic_light_spec.mdmarkdown585 B
assets/examples/readme/axis_packet_meter.vother10.2 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/generated/rtl/comb_hierarchy_budget.vother1.9 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/generated/tb/tb_comb_hierarchy_budget.vother2.5 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_child_loop.vother447 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_over_budget.vother527 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_q_cut.vother467 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_within_budget.vother450 B
assets/examples/remote_fixtures/comb_hierarchy_budget/spec.jsonconfig1.7 KB
assets/examples/remote_fixtures/comb_operation_budget/comb_operation_budget_bad.vother187 B
assets/examples/remote_fixtures/comb_operation_budget/generated/rtl/comb_operation_budget.vother6.1 KB
assets/examples/remote_fixtures/comb_operation_budget/generated/tb/tb_comb_operation_budget.vother5.7 KB
assets/examples/remote_fixtures/comb_operation_budget/spec.jsonconfig2.9 KB
assets/examples/remote_fixtures/comb_parity_mux/generated/rtl/comb_parity_mux.vother2.1 KB
assets/examples/remote_fixtures/comb_parity_mux/generated/tb/tb_comb_parity_mux.vother2.8 KB
assets/examples/remote_fixtures/comb_parity_mux/spec.jsonconfig1.9 KB
assets/examples/remote_fixtures/pipeline_delay/generated/rtl/pipeline_delay.vother4.5 KB
assets/examples/remote_fixtures/pipeline_delay/generated/tb/tb_pipeline_delay.vother2.6 KB
assets/examples/remote_fixtures/pipeline_delay/spec.jsonconfig2.2 KB
assets/examples/remote_fixtures/ready_valid_slice/generated/rtl/ready_valid_slice.vother5.2 KB
assets/examples/remote_fixtures/ready_valid_slice/generated/tb/tb_ready_valid_slice.vother2.9 KB
assets/examples/remote_fixtures/ready_valid_slice/spec.jsonconfig2.6 KB
assets/examples/rtl_erie_verilog_spec.jsonconfig2.1 KB
assets/examples/use_case_templates/jesd_adc.jsonconfig2.4 KB
assets/examples/use_case_templates/jesd_dac.jsonconfig2.5 KB
assets/examples/use_case_templates/mxfe_mixed.jsonconfig2.7 KB
assets/examples/use_case_templates/spi_adc.jsonconfig2.8 KB
assets/examples/use_case_templates/spi_dac.jsonconfig2.7 KB
assets/examples/verilog_pattern_templates/axi4_lite_csr.jsonconfig2.1 KB
assets/examples/verilog_pattern_templates/axi_interconnect_dma.jsonconfig2.3 KB
assets/examples/verilog_pattern_templates/axis_ready_valid.jsonconfig2.3 KB
assets/examples/verilog_pattern_templates/conv_load_store.jsonconfig1.8 KB
assets/external_interface_catalog.jsonconfig2.9 KB
assets/ideal_bad_style_metrics.jsonconfig17.5 KB
assets/installer/manifest.projection.jsonconfig2.8 KB
assets/installer/platforms.jsonconfig1.3 KB
assets/interface_templates/ahb_lite_config.vincother2.3 KB
assets/interface_templates/apb_config.vincother861 B
assets/interface_templates/axi4_full_master.vincother1.8 KB
assets/interface_templates/axi4_full_slave.vincother1.8 KB
assets/interface_templates/axi4_lite_config.vincother1.6 KB
assets/interface_templates/axi_stream_duplex.vincother1.1 KB
assets/interface_templates/catalog.jsonconfig2.6 KB
assets/project_ip_interface_manifest.template.jsonconfig9.4 KB
assets/readme-workflow.pngbinary1.4 MB
assets/readme/design-profile-cn.pngbinary1.4 MB
assets/readme/design-profile.pngbinary1.4 MB
assets/readme/evidence-guard-cn.pngbinary1.4 MB
assets/readme/evidence-guard.pngbinary1.4 MB
assets/readme/hero-overview-cn.pngbinary1.5 MB
assets/readme/hero-overview.pngbinary1.5 MB
assets/readme/project-facts-cn.pngbinary1.2 MB
assets/readme/project-facts.pngbinary1.3 MB
assets/readme/rule-rendering-cn.pngbinary1.4 MB
assets/readme/rule-rendering.pngbinary1.2 MB
assets/style_templates/header_prompt_none_mode.txtmarkdown2.1 KB
assets/style_templates/header_prompt_table_mode.txtmarkdown2.5 KB
assets/style_templates/rtl_bus_grouping.tplother1.0 KB
assets/style_templates/rtl_fsm.tplother832 B
assets/style_templates/rtl_header_bilingual.tplother1.6 KB
assets/style_templates/rtl_instantiation.tplother496 B
assets/style_templates/rtl_region_order.tplother987 B
assets/use_case_templates/catalog.jsonconfig2.8 KB
assets/use_case_templates/jesd_adc/README.mdmarkdown699 B
assets/use_case_templates/jesd_adc/constraints/system_constr.xdcother454 B
assets/use_case_templates/jesd_adc/manifest.jsonconfig1.7 KB
assets/use_case_templates/jesd_adc/tcl/common_bd.tclother4.0 KB
assets/use_case_templates/jesd_adc/tcl/system_bd.tclother920 B
assets/use_case_templates/jesd_adc/tcl/system_project.tclother1.0 KB
assets/use_case_templates/jesd_adc/verilog/system_top.vother2.9 KB
assets/use_case_templates/jesd_dac/README.mdmarkdown745 B
assets/use_case_templates/jesd_dac/constraints/system_constr.xdcother299 B
assets/use_case_templates/jesd_dac/manifest.jsonconfig1.7 KB
assets/use_case_templates/jesd_dac/tcl/common_bd.tclother4.8 KB
assets/use_case_templates/jesd_dac/tcl/system_bd.tclother923 B
assets/use_case_templates/jesd_dac/tcl/system_project.tclother1.1 KB
assets/use_case_templates/jesd_dac/verilog/system_top.vother2.9 KB
assets/use_case_templates/mxfe_mixed/README.mdmarkdown739 B
assets/use_case_templates/mxfe_mixed/constraints/system_constr.xdcother380 B
assets/use_case_templates/mxfe_mixed/manifest.jsonconfig1.8 KB
assets/use_case_templates/mxfe_mixed/tcl/common_bd.tclother5.4 KB
assets/use_case_templates/mxfe_mixed/tcl/system_bd.tclother1.2 KB
assets/use_case_templates/mxfe_mixed/tcl/system_project.tclother1.2 KB
assets/use_case_templates/mxfe_mixed/verilog/system_top.vother3.4 KB
assets/use_case_templates/spi_adc/README.mdmarkdown925 B
assets/use_case_templates/spi_adc/constraints/system_constr.xdcother635 B
assets/use_case_templates/spi_adc/manifest.jsonconfig1.7 KB
assets/use_case_templates/spi_adc/tcl/common_bd.tclother6.3 KB
assets/use_case_templates/spi_adc/tcl/system_bd.tclother1.6 KB
assets/use_case_templates/spi_adc/tcl/system_project.tclother982 B
assets/use_case_templates/spi_adc/verilog/system_top.vother4.2 KB
assets/use_case_templates/spi_dac/README.mdmarkdown757 B
assets/use_case_templates/spi_dac/constraints/system_constr.xdcother546 B
assets/use_case_templates/spi_dac/manifest.jsonconfig1.6 KB
assets/use_case_templates/spi_dac/tcl/common_bd.tclother5.7 KB
assets/use_case_templates/spi_dac/tcl/system_bd.tclother1.0 KB
assets/use_case_templates/spi_dac/tcl/system_project.tclother981 B
assets/use_case_templates/spi_dac/verilog/system_top.vother3.5 KB
assets/verilog_formatter_config/defaults.jsonconfig6.2 KB
assets/verilog_formatter_config/profiles/conservative.jsonconfig283 B
assets/verilog_formatter_config/profiles/example_compat.jsonconfig484 B
assets/verilog_formatter_config/profiles/formatter-lint.jsonconfig121 B
assets/verilog_formatter_config/profiles/formatter-normalize.jsonconfig182 B
assets/verilog_formatter_config/profiles/formatter-preserve.jsonconfig385 B
assets/verilog_formatter_config/profiles/formatting.jsonconfig270 B
assets/verilog_formatter_config/profiles/lint.jsonconfig269 B
assets/verilog_formatter_config/profiles/migration.jsonconfig239 B
assets/verilog_formatter_config/profiles/stress_cases_compat.jsonconfig484 B
assets/verilog_formatter_config/profiles/vitis-wrapper.jsonconfig486 B
assets/verilog_formatter_config/schema.jsonconfig13.7 KB
assets/verilog_formatter_config/templates/task-batch.jsonconfig212 B
assets/verilog_formatter_config/templates/task-inplace.jsonconfig221 B
assets/verilog_formatter_config/templates/task-single-file.jsonconfig220 B
assets/verilog_pattern_templates/axi4_lite_csr_shell.vincother562 B
assets/verilog_pattern_templates/axi_interconnect_port_groups.vincother592 B
assets/verilog_pattern_templates/axis_ready_valid_slice.vincother494 B
assets/verilog_pattern_templates/catalog.jsonconfig2.2 KB
assets/verilog_pattern_templates/conv_load_store_pipeline.vincother457 B
assets/verilog_pattern_templates/counter_state_bridge.vincother443 B
assets/verilog_pattern_templates/equivalence_wrapper_probe.vincother306 B
assets/verilog_pattern_templates/fsm_state_transition.vincother1.0 KB
assets/verilog_pattern_templates/phase_output_registering.vincother404 B
assets/verilog_pattern_templates/wrapper_top_stitching.vincother608 B
assets/verilog_quality_gates.jsonconfig38.2 KB
assets/verilog_style_rules.jsonconfig11.8 KB
assets/xilinx_primitive_semantics.jsonconfig21.4 KB
references/checklists/capability-distillation-checklist.mdmarkdown3.0 KB
references/checklists/lint-checklist.mdmarkdown3.6 KB
references/checklists/verilog-readability-gate.mdmarkdown3.5 KB
references/corpus/verilog-style-observations.mdmarkdown4.6 KB
references/integration/configuration.mdmarkdown19.9 KB
references/integration/host-integration.mdmarkdown10.6 KB
references/rules/asic-verilog-quality.mdmarkdown3.9 KB
references/rules/erie-style.mdmarkdown6.3 KB
references/rules/testbench-patterns.mdmarkdown3.2 KB
references/rules/verilog-code-comment-naming-standard.mdmarkdown55.6 KB
references/rules/verilog-comment-placement.mdmarkdown8.4 KB
references/rules/verilog-pattern-templates.mdmarkdown1.1 KB
references/rules/verilog-quality-gates.mdmarkdown21.4 KB
references/rules/xilinx-primitive-exemptions.mdmarkdown10.6 KB
references/skill/installation.mdmarkdown6.1 KB
references/skill/script-guide.mdmarkdown7.5 KB
references/skill/skill-standards.mdmarkdown2.1 KB
references/workflows/verilog_dispatcher.mdmarkdown6.4 KB
references/workflows/workflow-contracts.mdmarkdown15.1 KB
scripts/__init__.pyscript53 B
scripts/python/__init__.pyscript55 B
scripts/python/corpus/analyze_verilog_style_corpus.pyscript25.3 KB
scripts/python/existing_rtl/existing_rtl.pyscript81.1 KB
scripts/python/existing_rtl/existing_rtl_improvement.pyscript109.9 KB
scripts/python/existing_rtl/intervention.pyscript8.3 KB
scripts/python/existing_rtl/optimizer.pyscript25.8 KB
scripts/python/existing_rtl/reflection.pyscript86.7 KB
scripts/python/existing_rtl/semantic_contract.pyscript45.6 KB
scripts/python/existing_rtl/verifier.pyscript15.3 KB
scripts/python/existing_rtl/verify_repair.pyscript4.6 KB
scripts/python/existing_rtl/verify_repair_core.pyscript45.7 KB
scripts/python/existing_rtl/verify_repair_patch_apply.pyscript23.5 KB
scripts/python/existing_rtl/verify_repair_patch_categories.pyscript35.5 KB
scripts/python/existing_rtl/verify_repair_patch_plan.pyscript25.1 KB
scripts/python/existing_rtl/verify_repair_patching.pyscript2.4 KB
scripts/python/existing_rtl/verify_repair_support.pyscript25.6 KB
scripts/python/existing_rtl/verify_repair_testbench.pyscript45.9 KB
scripts/python/existing_rtl/verify_reporting.pyscript16.1 KB
scripts/python/facade/__init__.pyscript45 B
scripts/python/facade/existing_rtl_api.pyscript14.0 KB
scripts/python/facade/quality_api.pyscript19.9 KB
scripts/python/facade/representative_cases.pyscript38.3 KB
scripts/python/facade/verilog_api.pyscript6.5 KB
scripts/python/facade/workflow_api.pyscript63.2 KB
scripts/python/generation/tb_generator.pyscript54.9 KB
scripts/python/header_contract.pyscript21.1 KB
scripts/python/installation/__init__.pyscript52 B
scripts/python/installation/bundle.pyscript16.3 KB
scripts/python/installation/catalog.pyscript16.6 KB
scripts/python/installation/cli.pyscript26.4 KB
scripts/python/installation/projection.pyscript14.2 KB
scripts/python/installation/receipt.pyscript13.4 KB
scripts/python/installation/transaction.pyscript29.0 KB
scripts/python/quality/clock_name_roles.pyscript1.0 KB
scripts/python/quality/comment_placement.pyscript49.5 KB
scripts/python/quality/declaration_region_policy.pyscript8.0 KB
scripts/python/quality/deliverable_gate.pyscript51.9 KB
scripts/python/quality/external_interface_stubs.pyscript41.5 KB
scripts/python/quality/formatter_ast.pyscript85.0 KB
scripts/python/quality/formatter_ast_instances.pyscript5.4 KB

scripts/python/existing_rtl/existing_rtl_improvement.py

View on GitHub
"""existing RTL 分析与受控精修辅助流程。"""

# 启用更直接的前向引用类型标注写法。
from __future__ import annotations

# dataclass 用来承接精修入口的可选配置。
from dataclasses import dataclass

# 标准库依赖负责 JSON 读写、文件复制和外部命令执行。
import json
import shutil
import subprocess
from pathlib import Path
from typing import Any

# 既有 RTL 分析逻辑负责生成结构化分析与变换计划。
from .existing_rtl import analyze_existing_rtl, build_transform_plan, load_spec_text

# 验证模块提供后端探测与仿真配置选择能力。
from scripts.python.validation.validation import _backend_tools, _select_simulator_backend, _simulator_config

# 工作区工具负责把报告与 JSON 工件写到目标目录。
from scripts.python.workflow.workspace import write_json, write_text

# 允许的精修目标列表决定了入口参数的合法范围。
IMPROVE_GOALS = (
    "tb_scaffold",  # 生成或补写 testbench 外壳
    "style_improve",  # 输出风格精修指导报告
    "partition_assist",  # 生成分区辅助 wrapper
    "optimize_assist",  # 生成 QoR/优化辅助计划
    "merge_assist",  # 生成候选合并辅助工件
)  # existing RTL 精修入口允许的目标类型

# 把 improve_existing_rtl 的可选输入收敛成配置对象,避免入口参数继续膨胀。
@dataclass(slots=True)
class ImproveExistingRtlOptions:
    """封装 existing RTL 精修辅助流程的可选输入。

    参数:
        analysis_source: 已存在的分析结果 JSON 路径,可选。
        spec_source: 规格说明来源,可为文本路径、字典或原始字符串。
        candidate_artifacts_dir: 候选设计工件目录,可选。
        baseline_artifacts_dir: 基线设计工件目录,可选。
        readiness: 当前验证准备度级别。
        tb_language: testbench 输出语言。

    返回:
        None。该对象只承载 improve_existing_rtl 的可选配置。
    """

    # 允许调用方直接复用已有分析 JSON。
    analysis_source: Path | None = None  # 外部传入的结构分析结果路径

    # 规格可来自文本路径、字典或原始字符串。
    spec_source: str | Path | dict[str, Any] | None = None  # 传给分析器或脚手架生成器的规格来源

    # merge/optimize 场景需要读取候选设计工件目录。
    candidate_artifacts_dir: Path | None = None  # 候选设计工件目录

    # 重新分析时优先从基线工件目录提取 RTL。
    baseline_artifacts_dir: Path | None = None  # 基线设计工件目录

    # readiness 控制是否允许继续走外部验证工具链。
    readiness: str = "static"  # 当前验证流程允许使用的执行深度

    # tb_scaffold 默认生成 Verilog 版本 testbench。
    tb_language: str = "verilog"  # testbench 生成默认采用的语言

# OptimizePreparedArtifacts 保存 optimize_assist 无条件生成的计划和工件索引。
@dataclass(slots=True)
class OptimizePreparedArtifacts:
    """承载 optimize_assist 固定生成的计划路径和工件索引。

    参数:
        path_transform_plan: 统一变换计划 JSON 路径。
        dict_artifacts: 优化建议、wrapper 与分区映射工件索引。

    返回:
        None。该对象只在 optimize_assist 内部传递已准备工件。
    """

    # path_transform_plan 指向调度器消费的统一变换计划。
    path_transform_plan: Path  # optimize 阶段变换计划路径

    # dict_artifacts 汇集调用方可访问的 optimize 工件路径。
    dict_artifacts: dict[str, str]  # optimize 阶段工件索引

# OptimizeEvidenceState 统一 compare 与 advisory 分支的验证证据形状。
@dataclass(slots=True)
class OptimizeEvidenceState:
    """承载 optimize_assist 的工件增量、问题和验证摘要。

    参数:
        dict_artifacts: compare 或 advisory 分支新增的工件路径。
        list_issues: 当前分支发现的问题列表。
        dict_verification_summary: 接口、检查点和 testbench 验证摘要。
        dict_qor_summary: QoR 可比性与工具状态摘要。

    返回:
        None。该对象只在 optimize_assist 内部传递分支证据。
    """

    # dict_artifacts 记录 equivalence 或 QoR 报告路径。
    dict_artifacts: dict[str, str]  # 分支新增工件索引

    # list_issues 保留 compare 阶段识别的阻断与提示问题。
    list_issues: list[dict[str, Any]]  # optimize 问题列表

    # dict_verification_summary 提供接口与 testbench 一致性结论。
    dict_verification_summary: dict[str, Any]  # optimize 验证摘要

    # dict_qor_summary 提供 QoR 可比性和 yosys 状态。
    dict_qor_summary: dict[str, Any]  # 决定可比性与工具状态的 QoR 字段

# 规范化并校验 improve_goal 参数,避免后续主流程分支走偏。
def require_improve_goal(goal: str) -> str:
    """校验并返回规范化后的精修目标名。

    参数:
        goal: 用户传入的精修目标字符串。

    返回:
        转成小写且通过合法性校验的精修目标名。

    异常:
        ValueError: 当目标不在支持列表中时抛出。
    """

    # 精修目标统一转成小写,避免大小写分支重复。
    str_normalized_goal = goal.lower()  # 规范化后的精修目标名

    # 入口目标非法时立即阻断,避免生成错误工件。
    if str_normalized_goal not in IMPROVE_GOALS:

        # 用统一错误前缀返回可读的参数错误信息。
        raise ValueError(
            f"> ERR: [Python] Improve goal must be one of {', '.join(IMPROVE_GOALS)}."
        )

    # 返回已通过校验的规范化目标名。
    return str_normalized_goal

# 把可选 improve 配置补齐成完整对象,避免主流程重复处理 None 分支。
def _resolve_improve_options(
    options: ImproveExistingRtlOptions | None,
) -> ImproveExistingRtlOptions:
    """返回带默认值补齐后的 improve 配置对象。

    参数:
        options: 调用方传入的可选 improve 配置。

    返回:
        总是可直接读取字段的 improve 配置对象。
    """

    # 调用方未显式传配置时,构造一份默认 refine 配置。
    if options is None:

        # 返回补齐默认值后的 improve 配置对象。
        return ImproveExistingRtlOptions()

    # 已传入配置对象时直接复用,避免复制现有调用方意图。
    return options

# 为已有 RTL 生成 testbench、分区建议、风格报告或优化辅助工件。
def improve_existing_rtl(
    source_path: Path,
    *,
    out_dir: Path,
    improve_goal: str,
    options: ImproveExistingRtlOptions | None = None,
) -> dict[str, Any]:
    """生成 existing RTL 精修辅助所需的计划和工件。

    参数:
        source_path: 原始 RTL 源文件路径。
        out_dir: 本轮辅助工件输出目录。
        improve_goal: 本轮希望执行的精修目标类型。
        options: 承载分析来源、规格、候选工件与 testbench 语言的可选配置对象。

    返回:
        包含计划路径、校验路径、工件路径和分析结果的字典。
    """

    # 先把 improve_goal 规范成受支持的目标名。
    str_goal = require_improve_goal(improve_goal)  # 当前执行的精修目标名

    # 统一补齐 improve 可选配置,后续各分支都按完整对象取值。
    improve_existing_rtl_options_config = _resolve_improve_options(options)  # 已补齐默认值的 improve 配置对象

    # 调用方可直接提供分析 JSON,避免重复跑结构分析。
    if improve_existing_rtl_options_config.analysis_source is not None:

        # 先读出外部分析文件中的 JSON 文本。
        str_analysis_text = improve_existing_rtl_options_config.analysis_source.read_text(encoding="utf-8")  # 外部分析文件中的 JSON 文本

        # 再把 JSON 文本解析成结构化分析结果。
        dict_analysis = json.loads(str_analysis_text)  # 从分析 JSON 载入的结构化结果

    # 未提供分析 JSON 时,基于参考工件或源文件现算分析结果。
    else:

        # 先收集基线工件目录中的 RTL 输入。
        list_analysis_sources = _artifact_sources(improve_existing_rtl_options_config.baseline_artifacts_dir)  # 基线工件目录解析出的 RTL 输入列表

        # 缺少参考工件时,退回当前 source_path 作为唯一分析输入。
        if not list_analysis_sources:

            # 回退为单文件输入,保证后续分析至少有一个 RTL 源。
            list_analysis_sources = [source_path]  # 回退后的 existing RTL 分析输入列表

        # 先把规格输入统一解析成文本,避免在调用行里堆叠逻辑。
        str_spec_text = load_spec_text(improve_existing_rtl_options_config.spec_source)  # 传给分析器的规格说明文本

        # 再基于 RTL 输入和规格文本执行结构分析。
        dict_analysis_result = analyze_existing_rtl(list_analysis_sources, spec_text=str_spec_text)  # 重新分析 existing RTL 后得到的完整结果字典

        # 仅提取 existing RTL 结构分析结果本体。
        dict_analysis = dict_analysis_result["analysis"]  # existing RTL 结构分析结果

    # optimize_assist 会走单独的优化辅助主流程。
    if str_goal == "optimize_assist":

        # 直接转交优化辅助分支处理。
        return _optimize_assist(
            source_path,
            out_dir=out_dir,
            analysis=dict_analysis,
            candidate_artifacts_dir=improve_existing_rtl_options_config.candidate_artifacts_dir,
            baseline_artifacts_dir=improve_existing_rtl_options_config.baseline_artifacts_dir,
            readiness=improve_existing_rtl_options_config.readiness,
        )

    # merge_assist 同样需要走独立的候选合并辅助分支。
    if str_goal == "merge_assist":

        # 直接转交合并辅助分支处理。
        return _merge_assist(
            source_path,
            out_dir=out_dir,
            analysis=dict_analysis,
            candidate_artifacts_dir=improve_existing_rtl_options_config.candidate_artifacts_dir,
            readiness=improve_existing_rtl_options_config.readiness,
        )

    # 这些分支共享一份期望输出列表和工件索引字典。
    list_expected_outputs: list[dict[str, Any]] = []  # 当前精修目标预期生成的输出工件列表

    # 工件索引会写进 transform_validation,便于后续流程消费。
    dict_artifacts: dict[str, str] = {}  # 当前精修目标生成的工件路径映射

    # tb_scaffold 目标输出可直接运行或补写的 testbench 外壳。
    if str_goal == "tb_scaffold":

        # testbench 路径绑定当前分析模块名,避免不同模块互相覆盖。
        str_module_name = dict_analysis["module_info"]["name"]  # 当前分析得到的模块名

        # 把输出文件名绑定到模块名,避免不同模块 testbench 互相覆盖。
        path_tb = out_dir / "tb" / f"tb_{str_module_name}.v"  # 当前模块 testbench 外壳输出路径

        # 根据结构分析结果写出 testbench 外壳。
        _write_tb_from_analysis(
            dict_analysis,
            path_tb,
            tb_language=improve_existing_rtl_options_config.tb_language,
        )

        # 记下 testbench 相对路径,让计划文件能引用生成物。
        list_expected_outputs.append(
            {
                "path": path_tb.relative_to(out_dir).as_posix(),  # 相对输出目录的 testbench 路径
                "kind": "testbench",  # 当前工件类型为 testbench
            }
        )

        # 记录 testbench 的绝对工件路径。
        dict_artifacts["testbench"] = str(path_tb)  # testbench 工件的绝对路径

    # partition_assist 目标输出顶层 wrapper 和分区辅助壳。
    elif str_goal == "partition_assist":

        # 先提取分区 wrapper 要复用的顶层模块名。
        str_module_name = dict_analysis["module_info"]["name"]  # 当前分区辅助要复用的顶层模块名

        # 让分区 wrapper 文件名与目标模块保持一一对应。
        path_wrapper = out_dir / "partition" / f"top_{str_module_name}.v"  # 分区辅助 wrapper 输出路径

        # 写出承接分区拆分的顶层 wrapper 草稿。
        _write_partition_wrapper(dict_analysis, path_wrapper)

        # 把分区 wrapper 写进预期输出清单,供后续计划引用。
        list_expected_outputs.append(
            {
                "path": path_wrapper.relative_to(out_dir).as_posix(),  # 分区 wrapper 在输出目录中的相对位置
                "kind": "wrapper",  # 该输出项对应的工件类别标签
            }
        )

        # 把分区 wrapper 路径暴露给调用方和后续校验摘要。
        dict_artifacts["wrapper"] = str(path_wrapper)  # 暴露给调用方和校验摘要的 wrapper 路径

    # style_improve 默认输出风格审查与精修引导报告。
    else:

        # 风格精修报告使用固定文件名,方便用户直接查阅。
        path_guide = out_dir / "style" / "style_improve_report.md"  # 风格精修报告输出路径

        # 输出可直接阅读的风格精修建议文档。
        _write_style_improve_guide(dict_analysis, path_guide)

        # 把风格精修文档登记到输出清单,供计划文件引用。
        list_expected_outputs.append(
            {
                "path": path_guide.relative_to(out_dir).as_posix(),  # 风格精修文档在输出目录中的相对位置
                "kind": "guide",  # 该输出项对应的指南类别标签
            }
        )

        # 把风格精修文档的绝对路径回填到工件索引。
        dict_artifacts["style_report"] = str(path_guide)  # 风格报告工件的绝对路径

    # 用结构分析和预期输出来构造本轮变换计划。
    dict_transform_plan = build_transform_plan(  # 当前精修目标的 RTL 变换计划
        dict_analysis,  # 当前既有 RTL 的结构分析结果
        transform_goal=str_goal,  # 本轮准备执行的精修目标
        expected_outputs=list_expected_outputs,  # 本轮预计生成的辅助工件清单
    )

    # 把变换计划落盘,供后续执行或人工审阅。
    path_transform_plan = write_json(out_dir / "rtl_transform_plan.json", dict_transform_plan)  # 变换计划 JSON 输出路径

    # 先提取模块级摘要字段,避免在摘要字典里堆叠长表达式。
    str_summary_module_name = dict_analysis["module_info"]["name"]  # 分析摘要中的模块名

    # 统计分析摘要里的端口数量,供 validation 快速查看。
    int_summary_port_count = dict_analysis["module_info"]["port_count"]  # 分析摘要中的端口数量

    # 计算可供拆分的候选数量,供 validation 直观看到复杂度。
    int_summary_decomposition_count = len(dict_analysis["decomposition_candidates"])  # 分析摘要中的分解候选数量

    # 组装供 validation 复用的分析摘要。
    dict_analysis_summary = {  # 本轮分析摘要,供 transform_validation 复用
        "module": str_summary_module_name,  # 摘要里的目标模块名
        "port_count": int_summary_port_count,  # 摘要里的端口数量
        "decomposition_candidates": int_summary_decomposition_count,  # 摘要里的分解候选数量
    }

    # transform_validation 汇总本轮辅助是否已准备好进入下一阶段。
    dict_transform_validation = dict(  # 本轮精修辅助的校验与工件摘要
        version=1,  # 校验摘要版本
        goal=str_goal,  # 当前精修目标名称
        ready=True,  # 当前辅助输出默认视为可进入下一阶段
        issues=[],  # 当前阶段暂未登记阻断问题
        artifacts=dict_artifacts,  # 当前阶段生成的工件路径映射
        analysis_summary=dict_analysis_summary,  # 当前阶段复用的分析摘要
    )

    # 把 transform_validation 一并落盘。
    path_validation = write_json(out_dir / "transform_validation.json", dict_transform_validation)  # 精修辅助校验摘要 JSON 输出路径

    # 返回本轮精修辅助的主结果字典。
    return {
        "status": "planned",
        "transform_plan_path": str(path_transform_plan),
        "transform_validation_path": str(path_validation),
        "artifacts": dict_artifacts,
        "analysis": dict_analysis,
    }

# 比较参考 RTL 与候选 RTL 在接口、检查点和 testbench 语义上的一致性。
def compare_semantics(
    reference_path: Path,
    candidate_path: Path,
    *,
    out_dir: Path,
    run_external: bool = True,
    readiness: str = "static",
) -> dict[str, Any]:
    """比较参考设计与候选设计的语义一致性。

    参数:
        reference_path: 参考 RTL 源文件路径。
        candidate_path: 候选 RTL 源文件路径。
        out_dir: 比较工件输出目录。
        run_external: 是否允许调用外部工具链。
        readiness: 当前验证准备度级别。

    返回:
        包含 equivalence、QoR 和 transform_validation 路径的结果字典。
    """

    # 先分别分析参考设计和候选设计的结构信息。
    dict_reference_result = analyze_existing_rtl([reference_path])  # 参考 RTL 的完整分析结果

    # 从完整分析结果中取出参考设计的 analysis 本体。
    dict_reference = dict_reference_result["analysis"]  # 参考 RTL 的结构分析结果

    # 候选设计使用同一分析流程,便于后续逐项比较。
    dict_candidate_result = analyze_existing_rtl([candidate_path])  # 候选 RTL 的完整分析结果

    # 从完整分析结果中取出候选设计的 analysis 本体。
    dict_candidate = dict_candidate_result["analysis"]  # 候选 RTL 的结构分析结果

    # 仿真后端尝试列表用于记录选中的后端与回退情况。
    list_backend_attempts = _simulator_backend_attempts(run_external=run_external)  # 语义比较阶段尝试过的仿真后端列表

    # 记录未被选中的后端,方便输出工具链回退轨迹。
    list_toolchain_fallbacks = [item["name"] for item in list_backend_attempts if item["status"] != "selected"]  # 语义比较阶段的工具链回退列表

    # 先比较接口层面的兼容性问题。
    list_issues = _interface_issues(dict_reference, dict_candidate)  # 参考设计与候选设计的接口问题列表

    # 再比较 checkpoint/特征映射层面的漂移问题。
    list_checkpoint_issues = _checkpoint_issues(dict_reference, dict_candidate)  # 参考设计与候选设计的检查点漂移问题列表

    # 把 checkpoint 问题并入总 issue 列表。
    list_issues.extend(list_checkpoint_issues)

    # testbench 一致性结果负责补足行为层面的观测信息。
    dict_testbench = _testbench_consistency(  # 参考设计与候选设计的 testbench 一致性结果
        dict_reference,  # 提供基准 checkpoint 序列的参考设计分析结果
        dict_candidate,  # 提供待比较 checkpoint 序列的候选设计分析结果
        run_external=run_external,  # 控制是否允许后续接外部仿真工具
        backend_attempts=list_backend_attempts,  # 沿用本轮 compare 已记录的后端探测轨迹
    )

    # QoR 报告负责补足资源与时序层面的比较信息。
    dict_qor_report = _qor_report(  # 参考设计与候选设计的 QoR 比较结果
        dict_reference,  # 参考设计的结构分析结果
        dict_candidate,  # 候选设计的结构分析结果
        run_external=run_external,  # 控制是否允许调用外部 QoR 工具
        reference_path=reference_path,  # QoR 报告绑定的参考 RTL 文件
        candidate_path=candidate_path,  # QoR 报告绑定的候选 RTL 文件
    )

    # testbench 不一致时,把 warning 补进统一问题列表。
    if not dict_testbench["consistent"]:

        # 记录 testbench 行为不一致的告警。
        list_issues.append(
            {
                "severity": "warning",
                "source": "testbench_issue",
                "message": dict_testbench["message"],
            }
        )

    # 先单独计算接口一致性,避免在结果字典里堆叠长生成式表达式。
    bool_has_interface_error = False  # compare 阶段是否存在 current_module_issue error

    # 逐项扫描问题列表,只要命中接口 error 就终止后续检查。
    for dict_issue in list_issues:

        # 只关心 current_module_issue 里的 error 级问题。
        if dict_issue["severity"] != "error" or dict_issue["source"] != "current_module_issue":

            # 非接口 error 时继续检查下一条问题。
            continue

        # 命中接口 error 后立即标记阻断状态。
        bool_has_interface_error = True  # compare 阶段已经发现接口 error

        # 首个接口 error 已足够决定结果,因此这里提前结束扫描。
        break

    # 没有接口 error 时,reference/candidate 才可视为接口一致。
    bool_interface_consistent = not bool_has_interface_error  # compare 阶段的接口一致性结论

    # equivalence 汇总接口、checkpoint、仿真与 QoR 的总比较结果。
    dict_equivalence = {  # 参考设计与候选设计的语义等价摘要
        "version": 1,  # 语义等价摘要版本
        "reference_top": dict_reference["module_info"]["name"],  # 参考设计顶层模块名
        "candidate_top": dict_candidate["module_info"]["name"],  # 候选设计顶层模块名
        "readiness": readiness,  # 当前验证准备度
        "interface_consistent": bool_interface_consistent,  # 接口是否保持一致
        "checkpoint_consistent": not list_checkpoint_issues,  # 检查点是否保持一致
        "testbench_consistent": dict_testbench["consistent"],  # testbench 行为是否一致
        "qor_comparable": dict_qor_report["qor_comparable"],  # QoR 是否具备可比性
        "simulator_backend_attempts": list_backend_attempts,  # 仿真后端尝试轨迹
        "toolchain_fallbacks": list_toolchain_fallbacks,  # 未命中的工具链回退记录
        "semantic_case_results": dict_testbench["semantic_case_results"],  # 行为级 case 结果
        "checkpoint_drift": list_checkpoint_issues,  # 检查点漂移清单
        "issues": list_issues,  # compare 阶段汇总问题列表
    }

    # 把 equivalence JSON 写入输出目录。
    path_equivalence = write_json(out_dir / "equivalence.json", dict_equivalence)  # compare 语义等价摘要 JSON 的最终输出路径

    # 把 QoR 报告 JSON 一并写入输出目录。
    path_qor = write_json(out_dir / "qor_report.json", dict_qor_report)  # QoR 比较报告 JSON 输出路径

    # 先把 compare 阶段是否可继续推进整理成布尔值。
    bool_compare_ready = not any(item["severity"] == "error" for item in list_issues)  # compare 阶段是否可继续推进

    # 再预先计算 compare 场景的推荐下一步动作。
    str_compare_next_action = _recommended_next_action(dict_equivalence, candidate_provided=True)  # compare 阶段推荐的下一步动作

    # transform_validation 为后续流程提供简洁的 compare 阶段结论。
    dict_compare_transform_validation_verification_summary_payload = dict(  # compare 返回结构里 transform_validation["verification_summary"] 字段的落盘内容
        interface_consistent=dict_equivalence["interface_consistent"],  # compare 接口一致性
        checkpoint_consistent=dict_equivalence["checkpoint_consistent"],  # compare 检查点一致性
        testbench_consistent=dict_equivalence["testbench_consistent"],  # compare 阶段 testbench 行为一致性结论
        selected_backend=dict_testbench["selected_backend"],  # compare 最终选中的仿真后端
    )

    # 把 compare 阶段的 QoR 三个核心状态压缩成小字典。
    dict_qor_summary_payload = dict(  # compare 阶段 QoR 摘要载荷
        qor_comparable=dict_qor_report["qor_comparable"],  # compare 阶段 QoR 可比性
        status=dict_qor_report["status"],  # compare 阶段 QoR 主状态
        yosys_stat=dict_qor_report.get("yosys_stat", {}).get("status"),  # compare 阶段 yosys stat 子状态
    )

    # 用 compare 证据生成 transform_validation 主摘要,供上游流程直接消费。
    dict_compare_transform_validation_payload = dict(  # compare 返回结构里 transform_validation.json 的全量门禁对象
        version=1,  # compare 阶段 validation 结果使用的版本号
        ready=bool_compare_ready,  # compare 阶段是否允许继续推进
        issues=list_issues,  # 传给调用方排查 compare 失败原因的问题清单
        verification_summary=dict_compare_transform_validation_verification_summary_payload,  # compare 验证摘要载荷
        qor_summary=dict_qor_summary_payload,  # compare QoR 摘要载荷
        recommended_next_action=str_compare_next_action,  # 驱动调用方下一步分支选择的 compare 建议动作
    )

    # 把 compare 阶段的 transform_validation 落盘。
    path_transform_validation = write_json(  # compare 阶段校验摘要 JSON 输出路径
        out_dir / "transform_validation.json",  # compare transform_validation 输出文件路径
        dict_compare_transform_validation_payload,  # compare transform_validation 正文载荷
    )

    # 返回 compare 阶段生成的主要工件路径。
    return {
        "status": "passed" if dict_compare_transform_validation_payload["ready"] else "failed",
        "equivalence_path": str(path_equivalence),
        "qor_report_path": str(path_qor),
        "transform_validation_path": str(path_transform_validation),
    }

# 汇总 optimize_assist 固定输出项,避免主流程里重复堆叠工件描述。
def _optimize_expected_outputs(
    out_dir: Path,
    *,
    path_optimization_plan: Path,
    path_candidate_wrapper: Path,
    path_partition_map: Path,
) -> list[dict[str, str]]:
    """返回 optimize_assist 阶段预期生成的输出描述。

    参数:
        out_dir: optimize_assist 阶段的工件输出目录。
        path_optimization_plan: 优化建议文档路径。
        path_candidate_wrapper: 候选 wrapper 路径。
        path_partition_map: 候选分区映射路径。

    返回:
        适合直接传给 build_transform_plan 的输出描述列表。
    """

    # 把固定工件统一整理成 expected_outputs 列表。
    return [
        {
            "path": path_optimization_plan.relative_to(out_dir).as_posix(),  # 优化建议文档相对路径
            "kind": "optimization_plan",  # 当前输出项类型为优化建议文档
        },
        {
            "path": path_candidate_wrapper.relative_to(out_dir).as_posix(),  # 候选 wrapper 相对路径
            "kind": "candidate_wrapper",  # 当前输出项类型为候选 wrapper
        },
        {
            "path": path_partition_map.relative_to(out_dir).as_posix(),  # 分区映射 JSON 相对路径
            "kind": "candidate_partition_map",  # 当前输出项类型为分区映射
        },
    ]

# 统一提供 optimize_assist 默认验证摘要,避免主流程重复展开占位字段。
def _default_optimize_verification_summary() -> dict[str, str | bool | None]:
    """返回 optimize_assist 在没有候选 RTL 时的默认验证摘要。

    参数:
        无业务参数;函数直接返回默认验证摘要。

    返回:
        optimize_assist 默认使用的验证摘要字典。
    """

    # 缺少候选 RTL 时,各项一致性结论都保持未知状态。
    return {
        "interface_consistent": None,  # 初始状态下接口一致性未知
        "checkpoint_consistent": None,  # 初始状态下检查点一致性未知
        "testbench_consistent": None,  # 初始状态下 testbench 一致性未知
        "selected_backend": None,  # 初始状态下尚未选中仿真后端
    }

# 统一提供 optimize_assist 默认 QoR 摘要,避免 advisory 分支重复造字典。
def _default_optimize_qor_summary() -> dict[str, str | bool]:
    """返回 optimize_assist 在 advisory 模式下的默认 QoR 摘要。

    参数:
        无业务参数;函数直接返回默认 QoR 摘要。

    返回:
        optimize_assist 默认使用的 QoR 摘要字典。
    """

    # 没有候选 RTL 时,QoR 只能给出 advisory 级别提示。
    return {
        "qor_comparable": False,  # 默认没有候选 RTL 时不能做 QoR 对比
        "status": "advisory_only",  # 默认仅输出 advisory 级别 QoR 建议
        "yosys_stat": "not_run",  # 默认尚未运行 yosys stat
    }

# 统一读取 JSON 工件,避免主流程在 read_text/json.loads 之间重复切换。
def _read_json_artifact(path_json: str | Path) -> dict[str, Any]:
    """读取 JSON 工件并返回解析后的字典。

    参数:
        path_json: 待读取的 JSON 工件路径。

    返回:
        解析后的 JSON 字典内容。
    """

    # 先把路径统一成 Path,便于调用 read_text。
    path_artifact = Path(path_json)  # 需要读取的 JSON 工件路径

    # 再读出 JSON 文本,便于后续统一解析。
    str_json_text = path_artifact.read_text(encoding="utf-8")  # JSON 工件原始文本

    # 最后把 JSON 文本解析成字典。
    return json.loads(str_json_text)

# 从 compare 结果里提取最终选中的后端名,避免主流程重复写 next(...) 逻辑。
def _selected_backend_name(dict_equivalence: dict[str, Any]) -> str | None:
    """返回 compare 阶段最终选中的仿真后端名称。

    参数:
        dict_equivalence: compare 阶段的语义等价摘要字典。

    返回:
        被标记为 selected 的后端名称;未命中时返回 None。
    """

    # 先筛出 compare 阶段被标记为 selected 的后端名称。
    list_selected_names: list[str] = []  # compare 阶段命中的后端名称列表

    # 按顺序扫描后端尝试结果,只收集 selected 状态对应的名称。
    for dict_attempt in dict_equivalence["simulator_backend_attempts"]:

        # 非 selected 后端不属于最终命中列表。
        if dict_attempt["status"] != "selected":

            # 当前后端未被选中时直接跳过。
            continue

        # 记录本轮真正命中的仿真后端名称。
        list_selected_names.append(dict_attempt["name"])

    # 返回首个命中的 selected 后端;完全未命中时返回 None。
    return list_selected_names[0] if list_selected_names else None

# 基线优先读取工件目录,候选仅在目录含 RTL 时参与 compare。
def _resolve_optimize_sources(
    source_path: Path,
    candidate_artifacts_dir: Path | None,
    baseline_artifacts_dir: Path | None,
) -> tuple[Path, Path | None]:
    """解析 optimize_assist 实际使用的基线和候选 RTL。

    参数:
        source_path: 缺少基线工件时使用的默认 RTL 路径。
        candidate_artifacts_dir: 可选候选 RTL 工件目录。
        baseline_artifacts_dir: 可选基线 RTL 工件目录。

    返回:
        基线 RTL 路径和可选候选 RTL 路径。
    """

    # 基线目录缺少 RTL 时退回调用方提供的原始源码。
    list_baseline_sources = _artifact_sources(baseline_artifacts_dir)  # 基线目录中的 RTL 路径

    # 空基线目录不能阻断 optimize 辅助计划生成。
    if not list_baseline_sources:

        # 原始输入作为唯一基线,保持旧流程的回退行为。
        list_baseline_sources = [source_path]  # 回退后的基线 RTL 列表

    # 候选目录为空或不含 RTL 时保持 planned/advisory 分支。
    list_candidate_sources = _artifact_sources(candidate_artifacts_dir)  # 候选目录中的 RTL 路径

    # 首个候选 RTL 是 compare 复用链路的稳定输入。
    path_candidate_source = list_candidate_sources[0] if list_candidate_sources else None  # 可选候选 RTL

    # 基线同样固定取工件目录解析出的首个 RTL。
    return list_baseline_sources[0], path_candidate_source

# 固定工件准备阶段写出建议、wrapper、分区映射和统一变换计划。
def _prepare_optimize_artifacts(
    out_dir: Path,
    analysis: dict[str, Any],
) -> OptimizePreparedArtifacts:
    """生成 optimize_assist 无条件产出的计划和辅助工件。

    参数:
        out_dir: optimize_assist 工件输出目录。
        analysis: 当前参考 RTL 的结构分析结果。

    返回:
        固定变换计划路径与主工件索引。
    """

    # 三类人工辅助工件沿用既有文件名和落盘顺序。
    path_optimization_plan = out_dir / "optimization_plan.md"  # 优化建议文档路径

    # wrapper 为后续人工分区重组提供稳定骨架。
    path_candidate_wrapper = out_dir / "candidate_wrapper.v"  # 候选 wrapper 路径

    # 分区映射固化分析阶段识别的 decomposition 候选。
    path_partition_map = out_dir / "candidate_partition_map.json"  # 分区映射路径

    # 先写优化建议,再写 wrapper 和分区映射,保持原有副作用顺序。
    _write_optimization_plan(analysis, path_optimization_plan)

    # wrapper 必须在分区映射前生成,保持历史工件写入顺序。
    _write_partition_wrapper(analysis, path_candidate_wrapper)

    # 分区候选最后写成 JSON,供 wrapper 人工细化时交叉核对。
    write_json(
        path_partition_map,
        {
            "version": 1,
            "decomposition_candidates": analysis["decomposition_candidates"],
        },
    )

    # transform plan 的 expected_outputs 继续引用三类固定工件。
    list_expected_outputs = _optimize_expected_outputs(  # transform plan 登记的固定输出清单
        out_dir,  # 解析每项工件相对路径的输出根目录
        path_optimization_plan=path_optimization_plan,  # 登记人工优化建议文档
        path_candidate_wrapper=path_candidate_wrapper,  # 登记候选重组 wrapper
        path_partition_map=path_partition_map,  # 登记候选分区映射 JSON
    )

    # 基础 transform plan 仍由共享 builder 生成。
    dict_transform_plan = build_transform_plan(  # optimize 统一变换计划
        analysis,  # 当前参考 RTL 分析结果
        transform_goal="optimize_assist",  # 固定优化辅助目标
        expected_outputs=list_expected_outputs,  # 固定工件描述
    )

    # optimize 专属约束保持接口、检查点、testbench 和 QoR 可比性要求。
    dict_transform_plan.update(
        {
            "optimization_targets": _optimization_targets(analysis),
            "qor_objectives": _qor_objectives(analysis),
            "equivalence_requirements": {
                "interface_consistent": True,
                "checkpoint_consistent": True,
                "testbench_consistent": True,
                "qor_comparable": True,
            },
            "allowed_mutation_scope": "assist_only_no_default_rtl_rewrite",
        }
    )

    # 统一变换计划是调度器消费 optimize 工件的入口。
    path_transform_plan = write_json(  # 调度器后续读取的 transform plan 路径
        out_dir / "rtl_transform_plan.json",  # 固定为 optimize 统一计划文件名
        dict_transform_plan,  # 写入 QoR 目标与等价约束正文
    )

    # 主工件索引只登记无条件生成的三个辅助文件。
    dict_artifacts = dict(  # optimize 固定工件索引
        optimization_plan=str(path_optimization_plan),  # 人工评审优化建议
        candidate_wrapper=str(path_candidate_wrapper),  # 人工补线 wrapper
        candidate_partition_map=str(path_partition_map),  # 人工核对分区边界
    )

    # 返回固定计划和主工件,compare/advisory 分支稍后追加证据。
    return OptimizePreparedArtifacts(path_transform_plan, dict_artifacts)

# 候选 RTL 存在时复用 compare_semantics 生成等价性和 QoR 证据。
def _candidate_optimize_evidence(
    path_baseline_source: Path,
    path_candidate_source: Path,
    out_dir: Path,
    readiness: str,
) -> OptimizeEvidenceState:
    """生成候选 RTL 的 compare、验证与 QoR 摘要。

    参数:
        path_baseline_source: compare 使用的基线 RTL。
        path_candidate_source: compare 使用的候选 RTL。
        out_dir: optimize_assist 工件输出目录。
        readiness: 当前验证准备度级别。

    返回:
        compare 分支新增工件、问题和验证摘要。
    """

    # compare 主流程继续负责接口、检查点、testbench 和 QoR 证据。
    dict_compare_result = compare_semantics(  # 后续回读 equivalence 与 QoR 的路径集合
        path_baseline_source,  # 作为语义和资源对比参考的 RTL
        path_candidate_source,  # 接受等价性与 QoR 检查的候选 RTL
        out_dir=out_dir / "optimize_compare",  # 隔离 compare 子流程的工件目录
        run_external=readiness != "static",  # 控制是否调用真实外部仿真工具
        readiness=readiness,  # 传递 compile 或 execute 验证深度
    )

    # 两份 compare JSON 分别提供语义等价和 QoR 正文。
    dict_equivalence = _read_json_artifact(dict_compare_result["equivalence_path"])  # 等价性摘要

    # QoR 报告裁剪后供 transform_validation 使用。
    dict_qor_report = _read_json_artifact(dict_compare_result["qor_report_path"])  # QoR 报告正文

    # compare 新增 equivalence 与 QoR 两项公开工件。
    dict_artifacts = dict(  # compare 分支工件索引
        equivalence=dict_compare_result["equivalence_path"],  # 语义等价报告
        qor_report=dict_compare_result["qor_report_path"],  # QoR 对比报告
    )

    # 验证摘要字段和 selected backend 选择逻辑保持不变。
    dict_verification_summary = dict(  # transform_validation 继承的 compare 一致性摘要
        interface_consistent=dict_equivalence["interface_consistent"],  # 公共端口契约是否保持一致
        checkpoint_consistent=dict_equivalence["checkpoint_consistent"],  # 检查点可观测性是否保持一致
        testbench_consistent=dict_equivalence["testbench_consistent"],  # 验证 testbench 是否保持一致
        selected_backend=_selected_backend_name(dict_equivalence),  # compare 最终采用的仿真后端名称
    )

    # QoR 摘要只保留 gating 消费的三个状态字段。
    dict_qor_summary = dict(  # transform_validation 继承的候选 QoR 摘要
        qor_comparable=dict_qor_report["qor_comparable"],  # 参考与候选资源结果是否可比
        status=dict_qor_report["status"],  # 当前 QoR 对比流程的主状态
        yosys_stat=dict_qor_report.get("yosys_stat", {}).get("status"),  # yosys 统计工具的执行状态
    )

    # compare 识别的问题原样交给 optimize ready 判定。
    list_issues = dict_equivalence.get("issues", [])  # 决定 optimize ready 的 compare 问题

    # 分支证据形状与 advisory 保持一致,主流程无需了解细节。
    return OptimizeEvidenceState(
        dict_artifacts,
        list_issues,
        dict_verification_summary,
        dict_qor_summary,
    )

# 无候选 RTL 时只生成参考设计一侧的 advisory QoR 报告。
def _advisory_optimize_evidence(
    analysis: dict[str, Any],
    path_baseline_source: Path,
    out_dir: Path,
) -> OptimizeEvidenceState:
    """生成无候选 RTL 场景的 advisory QoR 证据。

    参数:
        analysis: 当前参考 RTL 的结构分析结果。
        path_baseline_source: advisory QoR 使用的基线 RTL。
        out_dir: optimize_assist 工件输出目录。

    返回:
        advisory QoR 工件和默认验证摘要。
    """

    # 单参考场景禁止外部工具,只生成不可比的 advisory QoR 正文。
    dict_qor_report = _qor_report(  # 单边 advisory QoR 报告
        analysis,  # 参考 RTL 分析结果
        None,  # 当前没有候选 RTL 分析
        run_external=False,  # advisory 不调用外部工具链
        reference_path=path_baseline_source,  # 当前基线 RTL
        candidate_path=None,  # 当前没有候选 RTL 路径
    )

    # 报告文件名保持与旧 planned 分支一致。
    path_qor = write_json(out_dir / "qor_report.json", dict_qor_report)  # planned 分支公开的单边 QoR 报告

    # 默认验证摘要仍表示尚未比较接口、检查点和 testbench。
    dict_verification_summary = _default_optimize_verification_summary()  # 尚未比较候选时的三项验证占位

    # 单边 QoR 摘要沿用报告中的可比性、主状态和 yosys 状态。
    dict_qor_summary = dict(  # planned 分支写入 validation 的单边 QoR 摘要
        qor_comparable=dict_qor_report["qor_comparable"],  # 没有候选时资源结果不可比较
        status=dict_qor_report["status"],  # 单边 advisory 报告的主状态
        yosys_stat=dict_qor_report.get("yosys_stat", {}).get("status"),  # 单边报告记录的 yosys 状态
    )

    # advisory 没有 compare 问题,也不会生成 equivalence 工件。
    return OptimizeEvidenceState(
        {"qor_report": str(path_qor)},
        [],
        dict_verification_summary,
        dict_qor_summary,
    )

# transform_validation 汇总候选存在性、错误问题和下一步动作。
def _write_optimize_validation(
    out_dir: Path,
    evidence: OptimizeEvidenceState,
    *,
    bool_candidate_provided: bool,
) -> Path:
    """写出 optimize_assist 的 transform_validation 摘要。

    参数:
        out_dir: optimize_assist 工件输出目录。
        evidence: compare 或 advisory 分支证据。
        bool_candidate_provided: 当前是否存在候选 RTL。

    返回:
        transform_validation JSON 路径。
    """

    # 任一 error 级问题都会阻断 ready。
    bool_has_error_issue = any(  # 是否存在阻断 optimize ready 的错误问题
        dict_issue["severity"] == "error"  # 只把 error 级问题视为阻断项
        for dict_issue in evidence.list_issues  # 扫描当前 compare 或 advisory 问题
    )  # 当前证据是否含阻断问题

    # ready 必须同时具备候选 RTL 且不存在 error。
    bool_ready = bool_candidate_provided and not bool_has_error_issue  # 候选存在且无错误才允许继续

    # 推荐动作只读取四个原有状态字段。
    dict_next_action_state = dict(  # 决定补候选或继续验证的四项状态
        interface_consistent=evidence.dict_verification_summary["interface_consistent"],  # 接口是否允许继续优化
        checkpoint_consistent=evidence.dict_verification_summary["checkpoint_consistent"],  # 检查点是否允许继续优化
        testbench_consistent=evidence.dict_verification_summary["testbench_consistent"],  # testbench 是否允许继续优化
        qor_comparable=evidence.dict_qor_summary["qor_comparable"],  # 资源结果是否具备比较条件
    )

    # 下一步建议继续由共享 helper 按候选状态生成。
    str_next_action = _recommended_next_action(  # optimize 推荐动作
        dict_next_action_state,  # 四项聚合状态
        candidate_provided=bool_candidate_provided,  # 候选 RTL 存在性
    )

    # transform_validation 的键和值保持公开 JSON 契约不变。
    dict_transform_validation = {  # 调度器读取的 optimize 验证正文
        "version": 1,  # 固定 transform_validation schema 版本
        "ready": bool_ready,  # 候选与错误问题共同决定的门禁结论
        "issues": evidence.list_issues,  # compare 分支继承的问题清单
        "verification_summary": evidence.dict_verification_summary,  # 三项一致性与后端摘要
        "qor_summary": evidence.dict_qor_summary,  # QoR 可比性和工具状态摘要
        "recommended_next_action": str_next_action,  # 调用方下一步动作建议
    }

    # 固定文件名允许调用方按原路径读取验证摘要。
    return write_json(out_dir / "transform_validation.json", dict_transform_validation)

# 生成 optimize_assist 模式下的辅助工件,并在候选 RTL 存在时补充比对结果。
def _optimize_assist(
    source_path: Path,
    *,
    out_dir: Path, analysis: dict[str, Any],
    candidate_artifacts_dir: Path | None, baseline_artifacts_dir: Path | None,
    readiness: str,
) -> dict[str, Any]:
    """生成优化辅助工件,并在候选 RTL 存在时附带语义比对结果。

    参数:
        source_path: 默认基线 RTL 路径,在缺少基线工件目录时作为回退输入。
        out_dir: optimize_assist 阶段的工件输出目录。
        analysis: 当前 RTL 的结构化分析结果。
        candidate_artifacts_dir: 候选 RTL 工件目录,可为空。
        baseline_artifacts_dir: 基线 RTL 工件目录,可为空。
        readiness: 当前验证准备度级别。

    返回:
        包含 transform_plan、transform_validation 与辅助工件路径的结果字典。
    """

    # 源路径 helper 保留基线回退和首个候选选择策略。
    tuple_optimize_sources = _resolve_optimize_sources(  # 确定 compare 或 advisory 使用的两侧 RTL
        source_path,  # 基线目录为空时使用的原始 RTL
        candidate_artifacts_dir,  # 搜索首个候选 RTL 的工件目录
        baseline_artifacts_dir,  # 搜索首个基线 RTL 的工件目录
    )

    # 基线路径始终存在,供 compare 或 advisory QoR 使用。
    path_baseline_source = tuple_optimize_sources[0]  # optimize 实际基线 RTL

    # 候选路径为空时保持 planned/advisory 行为。
    path_candidate_source = tuple_optimize_sources[1]  # 非空时触发 compare_semantics

    # 固定工件 helper 保持优化建议、wrapper、分区映射和计划的落盘顺序。
    optimize_prepared_artifacts_prepared_artifacts = _prepare_optimize_artifacts(  # 固定计划与工件状态
        out_dir,  # 写入建议、wrapper 和计划的目录
        analysis,  # 生成优化目标与分区映射的分析结果
    )

    # 候选存在时运行 compare;否则保持单参考 advisory 行为。
    if path_candidate_source is not None:

        # compare 分支生成 equivalence、QoR 与问题摘要。
        optimize_evidence_state_evidence = _candidate_optimize_evidence(  # 候选 compare 证据
            path_baseline_source,  # 提供语义对比参考的基线 RTL
            path_candidate_source,  # 接受一致性检查的候选 RTL
            out_dir,  # 保存 compare 子工件的输出目录
            readiness,  # 决定是否调用外部工具的验证深度
        )

    # 空候选目录必须继续生成 planned 状态和 advisory QoR。
    else:

        # advisory 分支不生成 equivalence,也不调用外部工具链。
        optimize_evidence_state_evidence = _advisory_optimize_evidence(  # 单参考 advisory 证据
            analysis,  # 生成单边 QoR 的参考分析结果
            path_baseline_source,  # 作为 advisory 报告来源的基线 RTL
            out_dir,  # 保存单边 QoR 报告的输出目录
        )

    # 候选存在性同时决定 ready 和推荐动作。
    bool_candidate_provided = path_candidate_source is not None  # optimize 是否拿到候选 RTL

    # 验证 helper 统一处理 error 问题、ready 和推荐动作。
    path_validation = _write_optimize_validation(  # 调度器读取的 validation JSON 路径
        out_dir,  # 固定 transform_validation 的写入目录
        optimize_evidence_state_evidence,  # 当前分支问题和一致性摘要
        bool_candidate_provided=bool_candidate_provided,  # 决定 ready 的候选存在状态
    )

    # 固定工件与分支证据合并后保持原有 artifacts 键集合。
    dict_artifacts = dict(  # 返回值中的完整 optimize 工件索引
        optimize_prepared_artifacts_prepared_artifacts.dict_artifacts  # 复制固定工件避免修改状态对象
    )

    # compare 或 advisory 新增的报告最后并入公开 artifacts。
    dict_artifacts.update(optimize_evidence_state_evidence.dict_artifacts)

    # 返回 optimize_assist 阶段的核心工件与分析结果。
    return {
        "status": "planned",
        "transform_plan_path": str(optimize_prepared_artifacts_prepared_artifacts.path_transform_plan),
        "transform_validation_path": str(path_validation),
        "artifacts": dict_artifacts,
        "analysis": analysis,
    }

# 生成 merge_assist 模式下的计划、wrapper 与静态校验占位结果。
def _merge_assist(
    source_path: Path,
    *,
    out_dir: Path,
    analysis: dict[str, Any],
    candidate_artifacts_dir: Path | None,
    readiness: str,
) -> dict[str, Any]:
    """生成 merge 辅助计划,保持原始 RTL 只读并引导后续手工拼接。

    参数:
        source_path: 当前参考 RTL 路径,用于记录 merge 计划的来源。
        out_dir: merge_assist 阶段的工件输出目录。
        analysis: 当前 RTL 的结构化分析结果。
        candidate_artifacts_dir: 候选 RTL 工件目录,可为空。
        readiness: 当前验证准备度级别。

    返回:
        包含 transform_plan、transform_validation 与 merge 工件路径的结果字典。
    """

    # 把候选工件目录中的 RTL 路径转换成 merge 计划可直接序列化的字符串列表。
    list_candidate_sources: list[str] = []  # merge 模式下可直接序列化的候选 RTL 路径列表

    # 把候选工件目录里解析出的 RTL 路径顺序转成字符串形式。
    for path_item in _artifact_sources(candidate_artifacts_dir):

        # 记录 merge 计划中可直接写入 JSON 的候选 RTL 路径。
        list_candidate_sources.append(str(path_item))

    # 把 merge_assist 的策略、候选与边界写成一份可审阅计划。
    dict_merge_plan = dict(  # merge_assist 阶段计划摘要字典
        version=1,  # merge 计划版本
        mode="merge_assist",  # 当前 refine 模式
        target_module=analysis["module_info"]["name"],  # merge 目标模块名
        strategy="wrapper_first_recompose",  # merge 采用的拼接策略
        reference_source=str(source_path),  # merge 参考 RTL 路径
        merge_constraints=[  # merge 过程中必须遵守的边界约束
            "preserve the public port contract exactly",  # merge 后必须保持公共端口契约
            "preserve checkpoint visibility and semantic invariants",  # merge 后必须保留检查点可观测性
            "do not overwrite source RTL automatically",  # merge_assist 只生成辅助工件
        ],
        candidate_sources=list_candidate_sources,  # merge 计划里登记的候选 RTL 路径清单
        recommended_templates=[  # merge 计划推荐优先参考的辅助模板清单
            "wrapper_top_stitching",  # 顶层 wrapper 拼接模板
            "equivalence_wrapper_probe",  # 等价性探针 wrapper 模板
            "counter_state_bridge",  # 计数器状态桥接模板
            "phase_output_registering",  # 相位输出寄存模板
        ],
        decomposition_candidates=analysis.get("decomposition_candidates", []),  # merge 计划沿用的分解候选摘要
    )

    # 把 merge 计划写入输出目录。
    path_merge_plan = write_json(out_dir / "merge_plan.json", dict_merge_plan)  # merge 计划输出路径

    # 先给出 wrapper 模板和静态校验占位结果,避免直接改写用户 RTL。
    path_merge_wrapper = out_dir / "merge_wrapper.v"  # merge_assist 先交给人工补线的 wrapper 模板输出路径

    # 立即写出 merge wrapper 骨架,方便人工先补连接关系。
    _write_merge_wrapper(analysis, path_merge_wrapper)

    # 候选 RTL 还没真正比较前,先写一份 planned 状态的等价性占位结果。
    dict_merge_equivalence = dict(  # merge 阶段静态等价性占位摘要字典
        version=1,  # merge 等价占位结果版本
        status="planned",  # merge 当前仍处于计划态
        interface_consistent=True,  # merge 计划要求保持接口一致
        checkpoint_consistent=True,  # merge 计划要求保持检查点一致
        candidate_provided=bool(list_candidate_sources),  # 当前是否已经提供候选 RTL
        recommended_next_action="provide_candidate_rtl_or_review_plan",  # merge 阶段建议动作
    )

    # 把静态等价性占位结果写入输出目录。
    path_merge_equivalence = write_json(out_dir / "merge_equivalence.json", dict_merge_equivalence)  # merge 等价性占位结果输出路径

    # 汇总 merge 阶段当前的准备度与工件列表。
    dict_merge_artifacts = dict(  # merge validation 内嵌的工件索引字典
        merge_plan=str(path_merge_plan),  # merge 计划文档路径
        merge_wrapper=str(path_merge_wrapper),  # merge wrapper 模板路径
        merge_equivalence=str(path_merge_equivalence),  # merge 等价占位结果路径
    )

    # 把 merge 当前准备度、工件索引和下一步动作汇总成 validation 摘要。
    dict_merge_validation = {  # merge 场景写回 transform_validation.json 的占位门禁摘要
        "version": 1,  # merge validation 使用的 schema 版本
        "status": "planned",  # merge 阶段当前仍停留在计划态
        "ready": False,  # merge_assist 默认要求人工审阅后再继续
        "readiness": readiness,  # merge 阶段沿用的验证准备度级别
        "artifacts": dict_merge_artifacts,  # merge 阶段当前已经生成好的工件索引
        "recommended_next_action": "review_merge_plan_and_fill_wrapper_connections",  # 调用方下一步应先审计划再补 wrapper 连线
    }

    # 把 merge validation 结果写入输出目录。
    path_merge_validation = write_json(out_dir / "merge_validation.json", dict_merge_validation)  # merge validation 输出路径

    # 构建统一 transform plan,串联 merge 计划、wrapper 与 validation。
    dict_merge_transform_plan_payload = build_transform_plan(  # merge_assist 返回结果里 transform_plan_path 指向的计划正文
        analysis,  # 当前作为 merge 基线的参考 RTL 结构分析结果
        transform_goal="merge_assist",  # 明确把计划目标固定为 merge_assist
        expected_outputs=[  # 调度器后续需要消费的 merge 工件清单
            {"path": path_merge_plan.relative_to(out_dir).as_posix(), "kind": "merge_plan"},  # merge 计划文档输出项
            {"path": path_merge_wrapper.relative_to(out_dir).as_posix(), "kind": "merge_wrapper"},  # merge wrapper 模板输出项
            {"path": path_merge_validation.relative_to(out_dir).as_posix(), "kind": "merge_validation"},  # merge validation 摘要文件输出项
            {
                "path": path_merge_equivalence.relative_to(out_dir).as_posix(),  # merge 等价占位结果在输出目录中的相对路径
                "kind": "merge_equivalence",  # merge 等价占位工件类型
            },
        ],
    )

    # 把 merge 计划里推荐的模板提升到 transform plan 顶层,方便调度器直读。
    dict_merge_transform_plan_payload["recommended_templates"] = dict_merge_plan["recommended_templates"]  # merge 计划推荐的模板列表

    # 明确标注 merge_assist 只写辅助工件,不自动改写用户 RTL。
    dict_merge_transform_plan_payload["allowed_mutation_scope"] = "assist_only_no_default_rtl_rewrite"  # merge_assist 默认不直接改写用户 RTL

    # 把 merge 场景的统一 transform plan 落盘。
    path_transform_plan = write_json(out_dir / "rtl_transform_plan.json", dict_merge_transform_plan_payload)  # 供调度器消费的 merge transform plan JSON 文件路径

    # 返回 merge_assist 阶段的关键工件集合。
    return {
        "status": "planned",
        "transform_plan_path": str(path_transform_plan),
        "transform_validation_path": str(path_merge_validation),
        "artifacts": {
            "merge_plan": str(path_merge_plan),
            "merge_wrapper": str(path_merge_wrapper),
            "merge_validation": str(path_merge_validation),
            "merge_equivalence": str(path_merge_equivalence),
        },
        "analysis": analysis,
    }

# 规范化 testbench 语言名称,并在非法值时给出统一错误前缀。
def _require_tb_language(tb_language: str) -> str:
    """校验 testbench 语言选项,仅允许 verilog。

    参数:
        tb_language: 用户指定的 testbench 语言名称。

    返回:
        归一化后的 testbench 语言名称。

    异常:
        ValueError: 当语言名称不在允许集合内时抛出。
    """

    # 统一转成小写,便于后续做固定集合判断。
    str_normalized = tb_language.lower()  # 归一化后的 testbench 语言名称

    # 仅允许 Verilog-2001 testbench 方言。
    if str_normalized != "verilog":

        # 语言不在允许集合时,立即返回统一前缀的参数错误。
        raise ValueError(
            "> ERR: [Python] tb_language 仅支持 'verilog'。"
        )

    # 返回归一化后的语言名称。
    return str_normalized

# 基于分析结果生成最小可运行的自检 testbench 脚手架。
def _write_tb_from_analysis(
    analysis: dict[str, Any],
    output_path: Path,
    *,
    tb_language: str,
) -> None:
    """基于分析结果生成最小可运行的自检 testbench 脚手架。

    参数:
        analysis: RTL 结构化分析结果。
        output_path: 生成 testbench 文件的输出路径。
        tb_language: 目标 testbench 语言,当前仅支持 verilog。

    返回:
        None。函数会直接把 testbench 内容写入输出文件。
    """

    # 规范化 testbench 语言,避免大小写差异影响分支判断。
    str_tb_language = _require_tb_language(tb_language)  # 归一化后的 testbench 语言

    # 提取顶层模块名,供模块实例与日志输出复用。
    str_module_name = str(analysis["module_info"]["name"])  # 顶层模块名称

    # 读取端口定义列表,后续统一生成声明与连接。
    list_ports = analysis["ports"]  # 顶层端口定义列表

    # 仅截取前几个 checkpoint,避免脚手架日志过长。
    list_checkpoints = analysis.get("verification_targets", [])[:4]  # 截断后的 checkpoint 列表

    # 先搭出 testbench 的说明头、模块头和最小常量定义。
    list_lines = [  # 依次写出 testbench 说明头、模块头和默认时钟周期常量
        f"// Analysis-derived self-checking scaffold for {str_module_name}",  # testbench 说明头文本
        f"module tb_{str_module_name};",  # testbench 模块声明头
        "    localparam CLK_PERIOD = 10;",  # 默认时钟周期常量
        "",  # 头部常量区与后续声明区之间的空行
    ]

    # 追加端口驱动/观测声明。
    list_lines.extend(_tb_declaration_lines(list_ports))

    # 追加 DUT 实例化模板。
    list_lines.extend(_tb_instance_lines(str_module_name, list_ports))

    # 追加自动识别到的时钟翻转驱动。
    list_lines.extend(_tb_clock_driver_lines(list_ports))

    # 追加脚手架启动横幅,方便判断 testbench 是否被执行。
    list_lines.extend(_tb_startup_banner_lines())

    # 追加 initial 主激励序列与收尾日志。
    list_lines.extend(
        _tb_initial_sequence_lines(
            list_ports,
            list_checkpoints,
            tb_language=str_tb_language,
        )
    )

    # 把拼好的 testbench 文本一次性写到目标文件。
    write_text(output_path, "\n".join(list_lines))

# 根据端口方向生成 testbench 驱动/观测声明。
def _tb_declaration_lines(list_ports: list[dict[str, Any]]) -> list[str]:
    """为 testbench 生成 reg/wire 端口声明文本。

    参数:
        list_ports: 顶层端口定义列表。

    返回:
        适合直接拼接进 testbench 的 reg/wire 声明文本列表。
    """

    # 准备 testbench 端口声明文本缓冲区。
    list_lines: list[str] = []  # testbench 端口声明文本列表

    # 逐个端口生成 reg/wire 声明。
    for dict_port in list_ports:

        # 先把宽度归一化成整数。
        int_width = int(dict_port.get("width") or 1)  # 当前端口位宽

        # 再拼接 Verilog 位宽切片文本。
        str_width_text = "" if int_width <= 1 else f" [{int_width - 1}:0]"  # 当前端口位宽文本

        # 输出端口作为观测对象,其余端口默认用 reg 驱动。
        str_storage_kind = "wire" if dict_port["direction"] == "output" else "reg"  # 当前端口在 testbench 中的存储类型

        # 把当前端口对应的 reg/wire 声明追加到结果列表。
        list_lines.append(f"    {str_storage_kind}{str_width_text} {dict_port['name']};")

    # 返回端口声明文本列表。
    return list_lines

# 生成 DUT 例化片段,保持端口一一映射。
def _tb_instance_lines(
    str_module_name: str,
    list_ports: list[dict[str, Any]],
) -> list[str]:
    """生成 DUT 例化所需的文本行。

    参数:
        str_module_name: 顶层模块名称。
        list_ports: 顶层端口定义列表。

    返回:
        适合直接拼接进 testbench 的 DUT 例化文本列表。
    """

    # 先收集 `.port(signal)` 形式的端口映射片段,再统一拼接成多行文本。
    list_port_map_lines: list[str] = []  # DUT 例化里逐个端口的映射文本片段

    # 按端口顺序生成 `.port(signal)` 形式的映射文本。
    for dict_port in list_ports:

        # 记录当前端口对应的 DUT 命名映射片段。
        list_port_map_lines.append(f"        .{dict_port['name']}({dict_port['name']})")

    # 再把端口映射片段拼成逗号换行分隔的例化正文。
    str_port_map = ",\n".join(list_port_map_lines)  # DUT 例化使用的端口映射文本

    # 返回 DUT 实例化文本。
    return [
        "",
        f"    {str_module_name} DUT_Inst (",
        str_port_map,
        "    );",
        "",
    ]

# 为识别到的时钟端口生成自动翻转驱动。
def _tb_clock_driver_lines(list_ports: list[dict[str, Any]]) -> list[str]:
    """生成 testbench 的 always 时钟驱动文本。

    参数:
        list_ports: 顶层端口定义列表。

    返回:
        针对 role=clock 端口生成的 always 驱动文本列表。
    """

    # 准备时钟驱动文本缓冲区。
    list_lines: list[str] = []  # always 时钟驱动文本列表

    # 只为 role=clock 的端口生成翻转逻辑。
    for dict_port in list_ports:

        # 仅当端口被标记为 clock 时才追加翻转驱动。
        if dict_port.get("role") == "clock":

            # 把当前时钟端口的翻转驱动写入结果列表。
            list_lines.append(
                f"    always #(CLK_PERIOD/2) {dict_port['name']} = ~{dict_port['name']};"
            )

    # 返回时钟驱动文本。
    return list_lines

# 生成脚手架启动横幅,帮助人工确认 testbench 已执行。
def _tb_startup_banner_lines() -> list[str]:
    """返回固定的启动横幅文本。

    参数:
        无业务参数;函数直接返回固定启动横幅片段。

    返回:
        testbench 启动时打印的一组固定文本行。
    """

    # 返回脚手架启动 initial 块。
    return [
        "",
        "    initial begin",
        (
            '        $display(" > INFO: [Verilog] [TB_MONITOR] Time: %0t | '
            'Starting analysis-derived verification.", $time);'
        ),
        "    end",
        "",
    ]

# 按角色或方向挑选默认端口名,供 testbench 断言和日志片段共用。
def _tb_preferred_port_name(
    list_ports: list[dict[str, Any]],
    *,
    role: str | None = None,
    direction: str | None = None,
    default: str | None = None,
) -> str | None:
    """返回符合条件的首个端口名。

    参数:
        list_ports: 顶层端口定义列表。
        role: 期望匹配的角色标签,可为空。
        direction: 期望匹配的方向标签,可为空。
        default: 未匹配到端口时返回的默认名称。

    返回:
        命中的端口名称;未命中时返回 default。
    """

    # 逐个端口按 role/direction 过滤,命中后立即返回名称。
    for dict_port in list_ports:

        # role 已指定时,只保留角色与目标一致的端口。
        if role is not None and dict_port.get("role") != role:

            # 当前端口角色不匹配时,继续检查下一个端口。
            continue

        # direction 已指定时,只保留方向与目标一致的端口。
        if direction is not None and dict_port.get("direction") != direction:

            # 当前端口方向不匹配时,继续检查下一个端口。
            continue

        # 第一个同时满足条件的端口直接返回其名称。
        return str(dict_port["name"])

    # 没有命中时,回退到调用方提供的默认名称。
    return default

# 生成 Verilog 模式的占位检查片段,提醒用户补全模块专属期望。
def _tb_verilog_placeholder_lines() -> list[str]:
    """返回纯 Verilog 模式下的占位检查文本。

    参数:
        无业务参数;函数直接返回固定占位片段。

    返回:
        Verilog 模式追加到 initial 序列末尾的文本列表。
    """

    # 纯 Verilog 模式无法直接使用 SV assertion,因此只给出占位提醒。
    return [
        "        if (^1'b0 === 1'b1) begin",
        (
            '            $error("[TB_ERROR] Time: %0t | Replace scaffold checks with '
            'module-specific expectations.", $time);'
        ),
        '            $display(" > ERR: [Verilog] replace scaffold checks with module-specific expectations.");',
        "        end",
    ]

# 生成 testbench 的 initial 主激励、日志与收尾片段。
def _tb_initial_sequence_lines(
    list_ports: list[dict[str, Any]],
    list_checkpoints: list[dict[str, Any]],
    *,
    tb_language: str,
) -> list[str]:
    """生成 initial 主序列的所有文本行。

    参数:
        list_ports: 顶层端口定义列表。
        list_checkpoints: 需要打印的 checkpoint 摘要列表。
        tb_language: 目标 testbench 语言名称。

    返回:
        initial 主激励、日志与收尾阶段对应的文本行列表。
    """

    # 准备 initial 主序列文本缓冲区。
    list_lines = ["", "    initial begin"]  # initial 主序列文本列表

    # 先为所有输入端口写入零值初始态。
    for dict_port in list_ports:

        # 输出端口由 DUT 驱动,不在 initial 中赋初值。
        if dict_port["direction"] != "output":

            # 输入端口位宽决定零值字面量格式。
            int_width = int(dict_port.get("width") or 1)  # 当前输入端口位宽

            # 把位宽换算成匹配当前输入端口的零值字面量。
            str_zero_value = "1'b0" if int_width == 1 else f"{int_width}'b0"  # 当前输入端口的零值文本

            # 把当前输入端口的零值初始化写入 initial 块。
            list_lines.append(f"        {dict_port['name']} = {str_zero_value};")

    # 如果识别到复位端口,则自动给出最小复位脉冲。
    if any(dict_port.get("role") == "reset" for dict_port in list_ports):

        # 取首个 reset 角色端口作为脚手架复位对象。
        dict_reset_port = next(  # 识别到的复位端口定义
            dict_port for dict_port in list_ports if dict_port.get("role") == "reset"  # 脚手架使用的复位端口
        )

        # 先把复位端口名转成小写,便于按后缀推断有效电平。
        str_reset_name = str(dict_reset_port["name"]).lower()  # 小写化后的复位端口名

        # 再根据命名后缀推断复位有效电平。
        str_active_value = "1'b0" if str_reset_name.endswith("n") else "1'b1"  # 复位有效电平文本

        # 反向得到复位释放后的无效电平。
        str_inactive_value = "1'b1" if str_active_value == "1'b0" else "1'b0"  # 复位无效电平文本

        # 写入复位拉低/释放序列,形成最小复位脉冲。
        list_lines.extend(
            [
                f"        {dict_reset_port['name']} = {str_active_value};",
                "        #(CLK_PERIOD * 2);",
                f"        {dict_reset_port['name']} = {str_inactive_value};",
            ]
        )

    # 为 checkpoint 追加最小监视日志,帮助人工对齐观察点。
    for dict_target in list_checkpoints:

        # 先拼出当前 checkpoint 关心的信号列表。
        str_signal_list = ",".join(dict_target.get("signals", []))  # 当前 checkpoint 关心的信号列表文本

        # 再取出日志里要打印的 checkpoint 标识。
        str_check_id = str(dict_target["check_id"])  # 当前 checkpoint 标识

        # 把当前 checkpoint 的监视日志追加到 initial 序列。
        list_lines.append(
            f'        $display(" > INFO: [Verilog] [TB_MONITOR] Time: %0t | '
            f'{str_check_id} | signals={str_signal_list}", $time);'
        )

    # 抽取一个输出端口,供观测日志与未知态检查共用。
    str_output_signal = _tb_preferred_port_name(  # 脚手架默认观测的输出信号名称
        list_ports, direction="output", default=None  # 观测日志默认输出端口选择条件
    )

    # 找到输出端口时,补一条观测日志。
    if str_output_signal:

        # 输出当前默认观测信号的运行时数值。
        list_lines.append(
            f'        $display(" > INFO: [Verilog] [TB_DATA] Time: %0t | '
            f'Observed {str_output_signal}=%0h", $time, {str_output_signal});'
        )

    # 固定输出脚手架执行结果。
    str_result_banner = (  # 统一的 VERILOG-GEN-RESULT 输出文本
        '        $display("VERILOG-GEN-RESULT {\\"case_id\\":\\"analysis_scaffold\\",'
        '\\"status\\":\\"PASS\\",\\"outputs\\":{},\\"checkpoints\\":{\\"phase\\":\\"analysis\\"}}");'
    )

    # 先输出一条简洁 PASS 日志,提示脚手架主序列已跑通。
    list_lines.append('        $display(" > INFO: [Verilog] analysis-derived scaffold executed.");')

    # 再输出机器可解析的 VERILOG-GEN-RESULT 横幅。
    list_lines.append(str_result_banner)

    # Verilog 脚手架仅提示用户补全模块专属检查。
    list_lines.extend(_tb_verilog_placeholder_lines())

    # 最后追加统一的仿真收尾语句。
    list_lines.extend(
        [
            "        #(CLK_PERIOD * 4);",
            '        $display(" > INFO: [Verilog] [TB_INFO] Simulation Finished!");',
            "        $finish;",
            "    end",
            "endmodule",
            "",
        ]
    )

    # 返回 initial 主序列文本。
    return list_lines

# 统一生成 wrapper module 头中的端口声明文本,避免多个辅助模式重复拼装。
def _wrapper_port_lines(list_ports: list[dict[str, Any]]) -> list[str]:
    """返回 wrapper/module 头使用的端口声明文本列表。

    参数:
        list_ports: 顶层端口定义列表。

    返回:
        适合直接拼接进 module 头的端口声明文本列表。
    """

    # 这里缓存的是 wrapper 模块头最终会逐行展开的端口声明文本。
    list_port_lines: list[str] = []  # 按 module 头顺序累积的 wrapper 端口声明文本

    # 逐个端口生成 direction/width/name 形式的声明文本。
    for int_index, dict_port in enumerate(list_ports):

        # 端口未显式声明位宽时,默认按单比特端口生成 wrapper 声明。
        int_width = int(dict_port.get("width") or 1)  # 为当前端口规整出的数值位宽

        # 这里把整数位宽转换成 Verilog 端口声明可直接复用的切片前缀。
        str_width_text = "" if int_width <= 1 else f"[{int_width - 1}:0] "  # 当前端口在 module 头中的位宽切片文本

        # 这里负责控制 module 头每一行后面是否还需要继续拼接下一个端口。
        str_trailing = "," if int_index < len(list_ports) - 1 else ""  # 当前端口声明尾部分隔符

        # 把当前端口的 direction/width/name 声明压入 module 头文本列表。
        list_port_lines.append(
            f"    {dict_port['direction']} {str_width_text}{dict_port['name']}{str_trailing}"
        )

    # 返回 wrapper/module 头所需的端口声明文本。
    return list_port_lines

# 生成 partition-assist wrapper 骨架,帮助后续人工拆分边界信号。
def _write_partition_wrapper(analysis: dict[str, Any], output_path: Path) -> None:
    """根据分解候选生成 partition-assist wrapper 骨架。

    参数:
        analysis: RTL 结构化分析结果。
        output_path: wrapper 文件输出路径。

    返回:
        None。函数会把 partition-assist wrapper 骨架直接写入 output_path。
    """

    # 读取原始模块名,稍后会拼成 `top_<module>` 形式的 partition wrapper 标识。
    str_module_name = str(analysis["module_info"]["name"])  # 将被拼成 top_<module> 的原始模块名

    # 这些顶层端口稍后会原样透传到 partition wrapper 外围接口。
    list_ports = analysis["ports"]  # 需要透传到 partition wrapper 的顶层端口列表

    # 提前把顶层端口整理成 partition wrapper 模块头可直接复用的声明行。
    list_port_lines = _wrapper_port_lines(list_ports)  # 可直接写入 partition wrapper 头部的端口声明文本

    # 先搭出 wrapper 的模块头和内部信号注释区。
    list_lines = [  # partition wrapper 头部与内部边界提示文本
        f"// Partition-assist wrapper skeleton for {str_module_name}",  # partition wrapper 的英文说明头文本
        f"module top_{str_module_name}(",  # partition wrapper 模块头起始行
        "\n".join(list_port_lines),  # partition wrapper 顶层端口声明区
        ");",  # partition wrapper 模块头结束行
        "",  # 模块头与内部边界信号说明区之间的空行
        "    // Internal boundary signals inferred from structural analysis.",  # partition wrapper 内部边界信号说明头
    ]  # partition wrapper 文本行列表

    # 记录已经声明过的内部边界信号,避免重复定义。
    set_seen_internal: set[str] = set()  # 已声明内部边界信号集合

    # 顶层端口名称集合用于过滤无需重复声明的边界信号。
    set_port_names = {dict_port["name"] for dict_port in list_ports}  # 顶层端口名称集合

    # 为每个分解候选补充内部边界 wire 声明。
    for dict_candidate in analysis["decomposition_candidates"]:

        # 逐个检查该候选暴露出来的边界信号。
        for str_signal in dict_candidate["boundary_signals"]:

            # 已经是顶层端口或已声明过的信号不再重复生成 wire。
            if str_signal in set_port_names or str_signal in set_seen_internal:

                # 当前边界信号无需重复声明时,继续检查下一个信号。
                continue

            # 先记录这个内部边界信号,避免后续候选重复声明。
            set_seen_internal.add(str_signal)

            # 把当前边界信号生成为 wrapper 内部 wire。
            list_lines.append(f"    wire {str_signal};")

    # 内部信号声明之后留一行空白,再写各子块说明。
    list_lines.append("")

    # 为每个分解候选追加角色、行号和边界信号说明。
    for dict_candidate in analysis["decomposition_candidates"]:

        # 追加当前候选的职责、边界信号和人工跟进提示。
        list_lines.extend(
            [
                (
                    f"    // {dict_candidate['module_name']} handles {dict_candidate['role']} "
                    f"lines {dict_candidate['line_range'][0]}-{dict_candidate['line_range'][1]}."
                ),
                (
                    f"    // Boundary signals: "
                    f"{', '.join(dict_candidate['boundary_signals']) or 'none detected'}."
                ),
                "    // Human follow-up should preserve the semantic invariants recorded in rtl_transform_plan.json.",
                "",
            ]
        )

    # 结束 wrapper 模块并写回文件。
    list_lines.append("endmodule")

    # 把 partition wrapper 文本整体写入目标文件。
    write_text(output_path, "\n".join(list_lines) + "\n")

# 生成 merge-assist wrapper 骨架,提醒人工按 merge 计划做拼接。
def _write_merge_wrapper(analysis: dict[str, Any], output_path: Path) -> None:
    """根据分析结果生成 merge-assist wrapper 骨架。

    参数:
        analysis: RTL 结构化分析结果。
        output_path: wrapper 文件输出路径。

    返回:
        None。函数会把 merge-assist wrapper 骨架直接写入 output_path。
    """

    # merge wrapper 名称会直接派生自原始模块名。
    str_module_name = str(analysis["module_info"]["name"])  # 供 merge wrapper 命名与提示文本复用的原始模块名

    # merge wrapper 外部接口必须沿用原设计的同一组顶层端口。
    list_ports = analysis["ports"]  # merge wrapper 需要原样保留的顶层端口列表

    # 这里先准备 merge wrapper 模块头前半段,端口声明稍后再插入。
    list_lines = [  # merge wrapper 模块头起始文本与后续占位说明入口
        f"// Merge-assist wrapper skeleton for {str_module_name}",  # 写入 merge wrapper 文件首行的英文提示
        f"module merge_{str_module_name}(",  # merge wrapper 顶层 module 声明头
    ]

    # 提前把顶层端口整理成 merge wrapper 模块头可直接拼接的声明区。
    list_port_lines = _wrapper_port_lines(list_ports)  # 可直接插入 merge module 头的端口声明文本

    # 先把端口声明拼进 merge wrapper 的 module 头。
    list_lines.append("\n".join(list_port_lines))

    # 再追加人工拼接时需要关注的提示文本。
    list_lines.extend(
        [
            ");",
            "",
            "    // Stitch candidate sub-blocks here after reviewing merge_plan.json.",
            "    // Preserve public ports and semantic checkpoints while reconnecting partitions.",
            "",
            f"    // Original top-level reference: {str_module_name}",
            "endmodule",
            "",
        ]
    )

    # 把 merge wrapper 正文写入目标文件,供后续人工补全连接关系。
    write_text(output_path, "\n".join(list_lines))

# 生成 style improve 指南,提醒调用方只做风格层精修而不改语义。
def _write_style_improve_guide(analysis: dict[str, Any], output_path: Path) -> None:
    """根据分析结果生成 style improve 指南文档。

    参数:
        analysis: RTL 结构化分析结果。
        output_path: style improve 指南输出路径。

    返回:
        None。函数会直接把指南文档写入目标文件。
    """

    # 先构造 guide 的固定段落,明确需要保留的语义边界。
    list_lines = [
        "# Style Refine Guide",  # 指南标题
        "",  # 标题与正文之间的空行
        f"Target module: `{analysis['module_info']['name']}`",  # style improve 面向的目标模块名
        "",  # 模块名与保留项标题之间的空行
        "## Preserve",  # 保留约束标题
        "- Public port names, widths, and directions.",  # 端口契约保持不变
        "- Reset behavior and sequential state initialization.",  # 复位语义保持不变
        "- Verification targets captured in `rtl_analysis.json`.",  # 校验目标保持不变
        "",  # 保留项与建议项之间的空行
        "## Suggested style improvements",  # 风格建议标题
    ]  # style improve 指南正文行列表

    # 逐个 always block 追加风格隔离建议,避免后续精修时再次混叠职责。
    for dict_block in analysis["always_blocks"]:

        # 追加当前 always block 的风格精修建议行。
        list_lines.append(
            f"- `{dict_block['block_id']}`: keep `{dict_block['role']}` logic isolated and well-commented."
        )

    # 把拼装好的 style improve 指南写回目标文件。
    write_text(output_path, "\n".join(list_lines) + "\n")

# 生成 optimize_assist 的文本计划,帮助人工理解优化关注点。
def _write_optimization_plan(analysis: dict[str, Any], output_path: Path) -> None:
    """根据分析结果生成 optimization assist 计划文档。

    参数:
        analysis: RTL 结构化分析结果。
        output_path: optimization plan 输出路径。

    返回:
        None。函数会直接把计划文档写入目标文件。
    """

    # 先构造优化计划的标题与固定章节。
    list_lines = [
        "# Optimization Assist Plan",  # 计划标题
        "",  # 标题与模块名之间的空行
        f"Target module: `{analysis['module_info']['name']}`",  # optimize 计划关注的目标模块名
        "",  # 模块名与优化目标标题之间的空行
        "## Candidate optimization targets",  # 优化目标标题
    ]  # 优化计划正文行列表

    # 逐条写出结构分析阶段提取出的优化目标。
    for dict_target in _optimization_targets(analysis):

        # 追加当前优化目标的摘要行。
        list_lines.append(f"- `{dict_target['id']}`: {dict_target['text']}")

    # 在优化目标后追加 QoR 小节标题。
    list_lines.extend(["", "## QoR objectives"])

    # 逐条写出当前分析结果对应的 QoR 关注点。
    for dict_objective in _qor_objectives(analysis):

        # 追加当前 QoR 目标的摘要行。
        list_lines.append(f"- `{dict_objective['id']}`: {dict_objective['text']}")

    # 把优化计划文档写回目标文件。
    write_text(output_path, "\n".join(list_lines) + "\n")

# 比较参考设计与候选设计的接口契约差异,并输出问题列表。
def _interface_issues(
    reference: dict[str, Any],
    candidate: dict[str, Any],
) -> list[dict[str, Any]]:
    """收集参考 RTL 与候选 RTL 的接口差异问题。

    参数:
        reference: 参考 RTL 的结构化分析结果。
        candidate: 候选 RTL 的结构化分析结果。

    返回:
        接口差异问题列表;没有差异时返回空列表。
    """

    # 把参考设计端口表转成按名称索引的字典,便于逐项比较。
    dict_reference_ports = {item["name"]: item for item in reference["ports"]}  # 参考设计端口索引

    # 把候选设计端口表转成按名称索引的字典,便于快速定位对应端口。
    dict_candidate_ports = {item["name"]: item for item in candidate["ports"]}  # 候选设计端口索引

    # 初始化接口差异问题列表。
    list_issues: list[dict[str, Any]] = []  # 接口差异问题列表

    # 逐个参考端口检查候选实现是否保持同名、同方向、同位宽。
    for str_port_name, dict_reference_port in dict_reference_ports.items():

        # 读取当前参考端口在候选实现中的同名端口定义。
        dict_candidate_port = dict_candidate_ports.get(str_port_name)  # 当前端口在候选设计中的定义

        # 缺失同名端口时,直接登记阻断性接口问题。
        if dict_candidate_port is None:

            # 记录候选实现缺失端口的错误。
            list_issues.append(
                {
                    "severity": "error",  # 缺失端口属于阻断问题
                    "source": "current_module_issue",  # 当前问题来自候选设计缺失端口
                    "message": f"Missing candidate port `{str_port_name}`.",  # 缺失端口说明
                }
            )

            # 当前端口已无法继续做方向和位宽比较,直接进入下一项。
            continue

        # 当端口方向被改动时,登记接口方向漂移问题。
        if dict_reference_port.get("direction") != dict_candidate_port.get("direction"):

            # 记录端口方向变化导致的错误。
            list_issues.append(
                {
                    "severity": "error",  # 方向变化属于阻断问题
                    "source": "current_module_issue",  # 当前问题来自端口方向漂移
                    "message": f"Port `{str_port_name}` direction changed.",  # 方向变化说明
                }
            )

        # 当端口位宽被改动时,登记接口位宽漂移问题。
        if int(dict_reference_port.get("width") or 1) != int(
            dict_candidate_port.get("width") or 1
        ):

            # 记录端口位宽变化导致的错误。
            list_issues.append(
                {
                    "severity": "error",  # 位宽变化属于阻断问题
                    "source": "current_module_issue",  # 当前问题来自端口位宽漂移
                    "message": f"Port `{str_port_name}` width changed.",  # 位宽变化说明
                }
            )

    # 找出仅存在于候选实现中的新增端口。
    list_extra_ports = sorted(set(dict_candidate_ports) - set(dict_reference_ports))  # 候选实现新增端口列表

    # 对新增端口逐一登记 warning,提醒人工确认意图。
    for str_port_name in list_extra_ports:

        # 记录候选实现引入新增端口的告警。
        list_issues.append(
            {
                "severity": "warning",  # 新增端口先按告警处理
                "source": "current_module_issue",  # 当前问题来自候选设计新增端口
                "message": f"Candidate introduced extra port `{str_port_name}`.",  # 新增端口说明
            }
        )

    # 返回汇总后的接口差异问题列表。
    return list_issues

# 比较参考设计与候选设计的 checkpoint 覆盖是否发生漂移。
def _checkpoint_issues(
    reference: dict[str, Any],
    candidate: dict[str, Any],
) -> list[dict[str, Any]]:
    """收集参考 RTL 与候选 RTL 的 checkpoint 漂移问题。

    参数:
        reference: 参考 RTL 的结构化分析结果。
        candidate: 候选 RTL 的结构化分析结果。

    返回:
        checkpoint 漂移问题列表;没有漂移时返回空列表。
    """

    # 把参考设计 checkpoint 集合规范化为可比较的元组集合。
    set_reference_targets = {
        (item["category"], tuple(item["signals"]))  # 单个参考 checkpoint 的分类与信号元组
        for item in reference["verification_targets"]  # 遍历参考设计的全部验证目标
    }  # 参考设计 checkpoint 集合

    # 把候选设计 checkpoint 集合规范化为可比较的元组集合。
    set_candidate_targets = {
        (item["category"], tuple(item["signals"]))  # 单个候选 checkpoint 的分类与信号元组
        for item in candidate["verification_targets"]  # 遍历候选设计的全部验证目标
    }  # 候选设计 checkpoint 集合

    # 两侧集合一致时,不需要登记任何问题。
    if set_reference_targets == set_candidate_targets:

        # checkpoint 完全对齐时直接返回空问题列表。
        return []

    # 返回一条覆盖漂移告警,提示人工补查 checkpoint 对齐情况。
    return [
        {
            "severity": "warning",  # checkpoint 漂移先按告警处理
            "source": "testbench_issue",  # 问题来源于验证目标
            "message": "Verification target or checkpoint coverage drifted between reference and candidate RTL.",  # 覆盖漂移说明
        }
    ]

# 记录本次语义比较尝试过的仿真后端及其选中状态。
def _simulator_backend_attempts(*, run_external: bool) -> list[dict[str, Any]]:
    """构造语义比较阶段的仿真后端尝试列表。

    参数:
        run_external: 是否允许访问外部工具链。

    返回:
        按优先顺序排列的后端尝试列表。
    """

    # 允许外部工具时读取仿真器选择结果,否则构造静态占位结果。
    dict_selection = (
        _select_simulator_backend(_simulator_config())  # 允许外部工具时执行真实后端选择
        if run_external  # 仅在允许访问外部工具链时做探测
        else {"backend": None, "missing_preferred": []}  # 静态模式下返回空选择结果
    )  # 仿真器选择结果

    # 提取当前真正被选中的后端名称。
    str_selected_name = (
        dict_selection["backend"]["name"] if dict_selection.get("backend") else None  # 从选择结果里提取后端名称
    )  # 被选中的仿真后端名称

    # 初始化后端尝试结果列表。
    list_attempts: list[dict[str, Any]] = []  # 后端尝试结果列表

    # 按固定顺序登记各后端的工具信息与选中状态。
    for str_backend_name in ["xsim", "vcs_verdi", "iverilog"]:

        # 收集当前后端依赖的工具名称列表。
        list_tools = list(_backend_tools(str_backend_name))  # 当前后端声明依赖的工具列表

        # 查找当前后端缺失的首选工具列表。
        list_missing_tools: list[str] = []  # 当前后端在本轮探测里累计出的缺失首选工具列表

        # 在缺失首选工具清单里查找与当前后端同名的记录。
        for dict_missing_backend in dict_selection.get("missing_preferred", []):

            # 名称不匹配时继续检查下一个后端记录。
            if dict_missing_backend.get("name") != str_backend_name:

                # 当前缺失记录不属于正在处理的后端。
                continue

            # 命中后端名称时提取缺失工具集合。
            list_missing_tools = dict_missing_backend.get("missing_tools", [])  # 当前后端缺失的首选工具清单

            # 找到匹配记录后无需继续扫描其他后端条目。
            break

        # 按运行许可和缺失情况决定当前后端状态。
        str_status = (
            "selected"  # 当前后端就是最终选中的执行后端
            if str_backend_name == str_selected_name  # 与最终选中的后端名称一致
            else "unavailable" if list_missing_tools or not run_external else "not_selected"  # 否则按可用性给出状态
        )  # 当前后端状态

        # 把当前后端状态登记到尝试结果列表。
        list_attempts.append(
            {
                "name": str_backend_name,  # 当前后端名称
                "tools": list_tools,  # 当前后端对应的依赖工具清单
                "missing_tools": list_missing_tools,  # 当前后端实际缺失的工具清单
                "status": str_status,  # 当前后端在本轮探测中的选中状态
            }
        )

    # 返回完整的后端尝试结果列表。
    return list_attempts

# 对比参考设计和候选设计的 testbench checkpoint 一致性。
def _testbench_consistency(
    reference: dict[str, Any],
    candidate: dict[str, Any],
    *,
    run_external: bool,
    backend_attempts: list[dict[str, Any]],
) -> dict[str, Any]:
    """收集 testbench checkpoint 一致性摘要。

    参数:
        reference: 参考 RTL 的结构化分析结果。
        candidate: 候选 RTL 的结构化分析结果。
        run_external: 是否允许访问外部工具链。
        backend_attempts: 已登记的仿真后端尝试列表。

    返回:
        包含一致性结论、已选后端和语义用例结果的摘要字典。
    """

    # 提取参考设计中登记的 checkpoint 标识序列。
    list_reference_ids = [item["check_id"] for item in reference["verification_targets"]]  # 参考设计 checkpoint 标识列表

    # 提取候选设计中登记的 checkpoint 标识序列。
    list_candidate_ids = [item["check_id"] for item in candidate["verification_targets"]]  # 候选设计 checkpoint 标识列表

    # 用完全相同的标识序列判断 checkpoint 是否一致。
    bool_consistent = list_reference_ids == list_candidate_ids  # 参考与候选 checkpoint 序列是否完全一致

    # 提取真正被选中的仿真后端名称。
    str_selected_backend = next(  # 选出 compare 阶段真正采用的仿真后端
        (item["name"] for item in backend_attempts if item["status"] == "selected"),  # 找出状态为 selected 的后端名称
        None,  # 未选中任何后端时返回空值
    )  # 已选仿真后端名称

    # 提取已选后端对应的工具列表,缺失时保留空列表。
    list_available_tools = next(  # 提取已选后端实际可用的工具清单
        (item["tools"] for item in backend_attempts if item["status"] == "selected"),  # 读取已选后端关联的工具列表
        [],
    )  # 已选仿真后端工具列表

    # 为每个参考 checkpoint 生成一条 PASS/WARN 结果。
    list_semantic_case_results = [
        {
            "case_id": str_case_id,  # 当前语义检查结果对应的 checkpoint 标识
            "status": "PASS" if bool_consistent else "WARN",  # 当前 checkpoint 在 compare 阶段的语义状态
        }
        for str_case_id in list_reference_ids  # 遍历参考设计里的全部 checkpoint 标识
    ]  # checkpoint 语义结果列表

    # 根据一致性结果选择更贴切的摘要消息。
    str_message = (
        "Matched analysis-derived testbench checkpoints."  # checkpoint 全部对齐时返回成功摘要
        if bool_consistent  # 根据一致性结果选择摘要消息
        else "Analysis-derived testbench checkpoints differ."  # checkpoint 漂移时返回告警摘要
    )  # testbench 一致性摘要消息

    # 返回 testbench 一致性摘要。
    return {
        "consistent": bool_consistent,  # 本轮 checkpoint 是否保持完全一致
        "selected_backend": str_selected_backend,  # 当前 compare 阶段最终选中的仿真后端
        "available_tools": list_available_tools,  # 最终选中后端对应的工具清单
        "semantic_case_results": list_semantic_case_results,  # 基于 checkpoint 序列构造的语义结果列表
        "message": str_message,  # 对齐结果对应的简洁摘要文本
        "run_external": run_external,  # 本轮 compare 是否允许调用外部工具
    }

# 生成 QoR 对比摘要,必要时附带 yosys stat 结果。
def _qor_report(
    reference: dict[str, Any],
    candidate: dict[str, Any] | None,
    *,
    run_external: bool,
    reference_path: Path,
    candidate_path: Path | None,
) -> dict[str, Any]:
    """收集参考设计与候选设计的 QoR 摘要。

    参数:
        reference: 参考 RTL 的结构化分析结果。
        candidate: 候选 RTL 的结构化分析结果;缺失时仅输出参考摘要。
        run_external: 是否允许访问外部工具链。
        reference_path: 参考 RTL 源文件路径。
        candidate_path: 候选 RTL 源文件路径,可为空。

    返回:
        包含结构规模、接口代价与 yosys 状态的 QoR 摘要字典。
    """

    # 先构造不依赖外部工具的基础 QoR 摘要。
    dict_report = {  # QoR 结构化摘要
        "version": 1,  # QoR 报告版本
        "status": "skipped",  # 默认状态
        "qor_comparable": candidate is not None,  # 是否具备参考/候选对比条件
        "area_like_signals": {  # 参考设计与候选设计的面积近似信号指标
            "reference": _area_like_signals(reference),  # 参考设计面积近似指标
            "candidate": _area_like_signals(candidate) if candidate else None,  # 候选设计面积近似指标
        },
        "sequential_elements": {  # 参考设计与候选设计的时序元素数量
            "reference": len(reference["state_elements"]),  # 参考设计时序元素数量
            "candidate": len(candidate["state_elements"]) if candidate else None,  # 候选设计时序元素数量
        },
        "always_block_count": {  # 参考设计与候选设计的 always 块数量
            "reference": len(reference["always_blocks"]),  # 参考设计 always 块数量
            "candidate": len(candidate["always_blocks"]) if candidate else None,  # 候选设计 always 块数量
        },
        "interface_cost_markers": {  # 参考设计与候选设计的接口代价标记
            "reference": _interface_cost_markers(reference),  # 参考设计接口代价标记
            "candidate": _interface_cost_markers(candidate) if candidate else None,  # 候选设计接口代价标记
        },
        "yosys_stat": {"status": "not_run"},  # 默认不运行 yosys
    }  # QoR 摘要字典

    # 具备工具链和候选路径时,再补一轮 yosys stat 结果。
    if run_external and shutil.which("yosys") and candidate_path is not None:

        # 运行 yosys stat 并覆盖默认占位结果。
        dict_report["yosys_stat"] = _yosys_stat(reference_path, candidate_path)  # 实际执行后的 yosys 统计结果

    # 根据 yosys 结果决定 QoR 报告状态。
    dict_report["status"] = (
        "available"  # yosys 成功返回统计结果时标记为 available
        if dict_report["yosys_stat"]["status"] == "available"  # 仅当 yosys 状态可用时升级报告状态
        else "skipped"  # 其他情况仍保留 skipped 状态
    )

    # 返回完整的 QoR 摘要字典。
    return dict_report

# 调用 yosys stat 并把文本输出收敛为字典摘要。
def _yosys_stat(reference_path: Path, candidate_path: Path) -> dict[str, Any]:
    """运行 yosys stat 并收集结构化摘要。

    参数:
        reference_path: 参考 RTL 源文件路径。
        candidate_path: 候选 RTL 源文件路径。

    返回:
        包含 yosys 状态与原始摘要的结果字典。

    异常:
        无业务异常向外抛出;工具失败会转成状态字典返回。
    """

    # 把参考 RTL 和候选 RTL 拼成一条固定的 yosys `read_verilog ...; stat` 命令。
    list_yosys_stat_command_argv = [  # _yosys_stat 真正执行的 argv,会把参考 RTL 和候选 RTL 一起送进同一次 yosys stat
        "yosys",  # yosys 可执行文件
        "-q",  # 静默模式
        "-p",  # 传入脚本命令
        f"read_verilog {json.dumps(str(reference_path))} {json.dumps(str(candidate_path))}; stat",  # 用于读取双输入并执行 stat 的 yosys 脚本文本
    ]

    # 运行 yosys 子进程并保留 stdout/stderr 供后续解析。
    try:

        # 执行 yosys 子进程,并把 stdout/stderr 留给后续状态整理。
        completed_process = subprocess.run(  # 执行 yosys 子进程并捕获 stdout/stderr
            list_yosys_stat_command_argv,  # 当前 reference/candidate 组合对应的 yosys argv
            capture_output=True,  # 同时捕获 stdout/stderr 供后续状态整理
            text=True,  # 直接按文本模式读取 yosys 输出
            timeout=30,  # 给 yosys stat 设置固定超时上限
            check=False,  # 非零退出码由下方逻辑统一转成状态字典
        )

    # 系统错误或超时都归一化成 error 状态。
    except (OSError, subprocess.TimeoutExpired) as exc:

        # 工具调用异常时直接返回 error 状态摘要。
        return {
            "status": "error",  # yosys 调用失败
            "detail": str(exc),  # 工具失败细节
        }

    # yosys 返回非零退出码时,回传 stderr/stdout 摘要。
    if completed_process.returncode != 0:

        # yosys 非零退出时直接返回错误摘要,避免继续解析无效输出。
        return {
            "status": "error",  # yosys stat 执行失败
            "detail": (completed_process.stderr or completed_process.stdout).strip(),  # 工具错误摘要
        }

    # 先建立一个包含原始 stdout 的可用状态摘要,后面再逐项补字段。
    dict_yosys_stat_summary = {  # _yosys_stat 的返回对象,先收原始 stdout,后续解析出的统计字段都会累加到这里
        "status": "available",  # yosys stat 已成功可用的状态标记
        "raw": (completed_process.stdout or "").strip(),  # yosys 原始输出文本
    }

    # 逐行解析形如 key: value 的统计项。
    for str_line in (completed_process.stdout or "").splitlines():

        # 不含冒号的行不属于键值统计项,直接跳过。
        if ":" not in str_line:

            # 只保留符合 key: value 结构的统计行。
            continue

        # 拆分当前统计行的 key 与 value。
        str_key, str_value = str_line.split(":", 1)  # 当前统计项原始键值对

        # 归一化当前统计项的 key 名称。
        str_normalized_key = str_key.strip().lower().replace(" ", "_")  # 归一化后的统计项名称

        # 把当前统计项写入结构化摘要。
        dict_yosys_stat_summary[str_normalized_key] = str_value.strip()  # 当前统计项规整后的值

    # 返回解析后的 yosys stat 摘要。
    return dict_yosys_stat_summary

# 根据 compare/optimize 阶段摘要决定推荐的下一步动作。
def _recommended_next_action(summary: dict[str, Any], *, candidate_provided: bool) -> str:
    """根据校验摘要返回更具体的后续动作建议。

    参数:
        summary: compare 或 optimize 阶段的结构化摘要。
        candidate_provided: 是否已经提供候选 RTL。

    返回:
        供上层流程使用的推荐动作字符串。
    """

    # 缺少候选 RTL 时,优先提示补充候选实现或先审阅计划。
    if not candidate_provided:

        # 未提供候选 RTL 时,先返回补料/审计划指令。
        return "provide_candidate_rtl_or_review_plan"

    # 接口不一致时,先修接口漂移再谈后续验证。
    if not summary.get("interface_consistent"):

        # 接口漂移会直接破坏外部契约,必须优先修复。
        return "fix_interface_drift"

    # checkpoint 不一致时,优先修复观察点漂移。
    if not summary.get("checkpoint_consistent"):

        # 观察点漂移会影响语义核对与调试,因此单独拦截。
        return "fix_checkpoint_drift"

    # testbench 不一致时,优先补齐测试用例或参考行为。
    if not summary.get("testbench_consistent"):

        # 行为测试不一致时,优先修测试或参考行为基线。
        return "repair_testbench_or_reference_cases"

    # 前述关键条件都满足时,转入人工复查候选 RTL。
    return "review_candidate_manually"

# 提取 optimize_assist 阶段应关注的优化目标列表。
def _optimization_targets(analysis: dict[str, Any]) -> list[dict[str, Any]]:
    """根据分析结果生成 optimization target 列表。

    参数:
        analysis: RTL 结构化分析结果。

    返回:
        optimization target 列表,供优化计划与 transform plan 复用。
    """

    # 先写入始终成立的 IO 契约保持目标。
    list_targets = [
        {
            "id": "preserve_io_contract",  # 优化目标标识
            "text": "Preserve the existing public IO contract exactly.",  # IO 契约保持目标说明
        }
    ]  # optimization target 列表

    # 识别到可分解热点时,补充分区级优化目标。
    if analysis.get("decomposition_candidates"):

        # 追加分解热点相关的优化目标。
        list_targets.append(
            {
                "id": "partition_hotspots",  # 分区热点目标标识
                "text": "Use decomposition candidates as safe partition hotspots for assist planning.",  # 分区热点目标说明
            }
        )

    # 识别到计数器类状态时,补充可见性保持目标。
    if any(item.get("role") == "counter" for item in analysis.get("state_elements", [])):

        # 追加计数器/状态交互可见性目标。
        list_targets.append(
            {
                "id": "counter_fsm_visibility",  # 计数器可见性目标标识
                "text": "Keep counter/state interaction visible for timing and debug review.",  # 计数器可见性目标说明
            }
        )

    # 返回汇总后的优化目标列表。
    return list_targets

# 提取优化辅助阶段应保持的 QoR 目标列表。
def _qor_objectives(analysis: dict[str, Any]) -> list[dict[str, Any]]:
    """根据分析结果生成 QoR objective 列表。

    参数:
        analysis: RTL 结构化分析结果。

    返回:
        QoR objective 列表,供优化计划与 transform plan 复用。
    """

    # 预先记录当前设计的时序元素数量基线。
    int_state_element_count = len(analysis.get("state_elements", []))  # 当前设计时序元素数量

    # 返回优化辅助阶段的 QoR 目标列表。
    return [
        {
            "id": "reduce_area_like_signals",  # 面积近似信号目标标识
            "text": "Avoid increasing structural signal count unless the candidate clearly improves observability.",  # 面积近似信号目标说明
        },
        {
            "id": "preserve_sequential_footprint",  # 时序足迹目标标识
            "text": f"Keep sequential element count near the current baseline of {int_state_element_count}.",  # 时序足迹目标说明
        },
        {
            "id": "preserve_interface_cost_markers",  # 接口代价目标标识
            "text": "Do not add extra public ports or widen the existing interface without explicit intent.",  # 接口代价目标说明
        },
    ]

# 计算可粗略反映结构面积的信号数量指标。
def _area_like_signals(analysis: dict[str, Any] | None) -> int | None:
    """估算可类比面积规模的结构信号数量。

    参数:
        analysis: RTL 结构化分析结果;为空时表示当前没有可统计对象。

    返回:
        端口数与状态元素数之和;缺少分析结果时返回 None。
    """

    # 缺少分析结果时,不输出面积近似指标。
    if not analysis:

        # 缺少分析结果时,返回 None 让上游跳过该指标。
        return None

    # 分别统计端口与状态元素数量,避免返回式过长。
    int_port_count = len(analysis.get("ports", []))  # 当前设计端口数量

    # 单独记录状态元素数量,便于与端口规模合并统计。
    int_state_count = len(analysis.get("state_elements", []))  # 当前设计状态元素数量

    # 返回端口数量与状态元素数量之和。
    return int_port_count + int_state_count

# 统计接口规模相关的代价标记,供 QoR 摘要复用。
def _interface_cost_markers(analysis: dict[str, Any] | None) -> dict[str, Any] | None:
    """计算接口规模相关的代价标记。

    参数:
        analysis: RTL 结构化分析结果;为空时表示当前没有可统计对象。

    返回:
        包含端口数量、总位宽和输出数量的摘要字典;缺少分析结果时返回 None。
    """

    # 缺少分析结果时,不输出接口代价标记。
    if not analysis:

        # 缺少分析结果时,返回 None 让上游跳过该摘要。
        return None

    # 累加所有公共端口的总位宽。
    int_total_width = sum(  # 汇总全部公共端口的位宽总和
        int(item.get("width") or 1) for item in analysis.get("ports", [])  # 逐个累加公共端口位宽
    )  # 公共端口总位宽

    # 返回接口规模相关的统计摘要。
    return {
        "port_count": len(analysis.get("ports", [])),  # 公共端口数量
        "total_port_width": int_total_width,  # 所有公共端口累计位宽
        "output_count": sum(
            1 for item in analysis.get("ports", []) if item.get("direction") == "output"
        ),  # 输出端口数量
    }

# 从单文件或目录中提取可比较的 RTL 源文件列表。
def _artifact_sources(path: Path | None) -> list[Path]:
    """解析工件路径并返回可用 RTL 源文件列表。

    参数:
        path: 单个 RTL 文件路径或包含 RTL 文件的目录路径,可为空。

    返回:
        过滤 testbench 后的 RTL 源文件路径列表。
    """

    # 缺少工件路径时,直接返回空列表。
    if path is None:

        # 没有提供工件路径时,不再尝试解析任何 RTL 源文件。
        return []

    # 统一把输入转换成 Path 对象,便于后续判断。
    path_candidate = Path(path)  # 待解析的工件路径

    # 指向单个 Verilog 源文件时,直接返回该文件。
    if path_candidate.is_file() and path_candidate.suffix.lower() == ".v":

        # 单文件输入可以直接作为唯一 RTL 源。
        return [path_candidate]

    # 路径不存在时,不返回任何源文件。
    if not path_candidate.exists():

        # 路径不存在时,不再继续递归扫描。
        return []

    # 递归收集目录下所有非 testbench 的 Verilog 文件。
    return sorted(
        item for item in path_candidate.rglob("*.v") if not _is_testbench(item)
    )

# 判断给定 Verilog 文件是否属于 testbench。
def _is_testbench(path: Path) -> bool:
    """根据文件名规则判断当前 Verilog 文件是否为 testbench。

    参数:
        path: 待判断的 Verilog 文件路径。

    返回:
        命中 testbench 命名模式时返回 True,否则返回 False。
    """

    # 提取小写化后的文件 stem,便于统一匹配命名规则。
    str_stem = path.stem.lower()  # 小写化后的文件 stem

    # 返回当前文件是否命中常见 testbench 命名模式。
    return (
        str_stem.endswith("_tb")
        or str_stem.startswith("tb_")
        or "testbench" in str_stem
    )
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall