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/facade/representative_cases.py

View on GitHub
"""Verilog facade 的 representative corpus 运行入口。"""

# future annotations 避免注解在导入期求值。
from __future__ import annotations

# json 用于把阶段状态和摘要稳定写成 UTF-8 文本。
import json

# Path 负责统一 representative 样例与运行目录路径。
from pathlib import Path

# Any 用于兼容旧 facade 的自由配置字典。
from typing import Any

# formatter AST 负责读取 RTL 文本并保留源编码信息。
from scripts.python.quality.formatter_ast import read_verilog_source

# formatter backend 负责生成 governed RTL 副本。
from scripts.python.quality.formatter_config import create_formatter_backend

# existing-RTL verify-repair 用于 representative 坏例验证。
from .existing_rtl_api import verify_existing_verilog

# quality gate 负责 governed RTL 的 strict 质量检查。
from .quality_api import check_verilog_quality

# workflow facade 的兼容配置合并逻辑在 run-cases 中复用。
from .workflow_api import _merged_option_dict

# 仓库根路径用于定位 tests/cases 与默认 runs 合同。
REPO_ROOT = Path(__file__).resolve().parents[5]  # 当前 skill 仓库根目录

# representative 坏例文本保持稳定顺序,便于 run-cases 结果对比。
str_bad_case_ids_text = (
    "missing_reset_fail bad_instance_shape_fail always_split_case_fail "
    "complex_case_slice_fail part_select_split_fail"
)  # representative 坏例的稳定 case_id 文本

# 把坏例文本切分成公共常量,供目录构造和顺序控制复用。
REPRESENTATIVE_BAD_CASE_IDS = tuple(str_bad_case_ids_text.split())  # representative 坏例 case_id 顺序

# representative 理想样例文本保持稳定顺序,便于治理回归比对。
str_ideal_case_ids_text = (
    "Sync_Reset_Interface Core_Tim_Ctrl_Interface Core_Ptp_Ctrl_Interface "
    "AXIS_ClockConverter_Interface AXIS_Buffer_Interface"
)  # representative 理想样例的稳定 case_id 文本

# 把理想样例序列固化为常量,便于回归时锁定好样例顺序。
REPRESENTATIVE_IDEAL_CASE_IDS = tuple(str_ideal_case_ids_text.split())  # representative 理想样例 case_id 顺序

# representative run-cases 的默认输出目录保持旧合同不变。
DEFAULT_CASE_RUN_DIR = Path("runs") / "representative-10"  # representative corpus 的默认运行目录

# _case_spec 把单个 case 元信息封装成稳定字典结构。
def _case_spec(str_case_id: str, str_cohort: str, path_source: Path) -> dict[str, Any]:
    """构造单个 representative case 的元信息字典。

    参数:
        str_case_id: representative case 的稳定标识。
        str_cohort: 当前样例所属的 cohort,例如 bad 或 ideal。
        path_source: 当前样例对应的源 RTL 文件路径。

    返回:
        返回包含 case_id、cohort 和 source 三个字段的元信息字典。
    """

    # 返回统一字典结构,便于后续目录选择和摘要序列化复用。
    return {
        "case_id": str_case_id,  # representative case 的稳定标识
        "cohort": str_cohort,  # 当前样例所属的 cohort
        "source": path_source,  # 当前样例对应的源 RTL 路径
    }

# _build_case_catalog 构造 case_id 到元信息的稳定映射。
def _build_case_catalog() -> dict[str, dict[str, Any]]:
    """构造 representative corpus 的 case_id 元信息索引。

    参数:
        无额外业务参数;函数直接读取模块级 case_id 常量。

    返回:
        返回按 case_id 建立索引的 representative 元信息字典。
    """

    # 目录字典负责承接 bad 与 ideal 两个 cohort 的统一索引。
    dict_case_catalog: dict[str, dict[str, Any]] = {}  # 按 case_id 建立索引的 representative 目录

    # 先登记 bad cohort,确保失败样例始终按固定顺序出现。
    for str_case_id in REPRESENTATIVE_BAD_CASE_IDS:

        # 当前坏例的源 RTL 固定落在 tests/cases/bad/rtl/fixtures。
        path_bad_case_source = REPO_ROOT / "tests" / "cases" / "bad" / "rtl" / "fixtures" / f"{str_case_id}.v"  # 当前坏例的源 RTL 文件路径

        # 把坏例登记进目录映射,便于后续按 case_id 直接取样例元信息。
        dict_case_catalog[str_case_id] = _case_spec(str_case_id, "bad", path_bad_case_source)  # 当前坏例的 representative 元信息

    # 再登记 ideal cohort,保持好样例顺序与既有合同一致。
    for str_case_id in REPRESENTATIVE_IDEAL_CASE_IDS:

        # 当前理想样例的 RTL 固定落在 tests/cases/ideal/rtl。
        path_ideal_case_source = REPO_ROOT / "tests" / "cases" / "ideal" / "rtl" / f"{str_case_id}.v"  # 当前理想样例的源 RTL 文件路径

        # 把理想样例登记进目录映射,便于后续保持好样例执行顺序稳定。
        dict_case_catalog[str_case_id] = _case_spec(str_case_id, "ideal", path_ideal_case_source)  # 当前理想样例的 representative 元信息

    # 返回按 case_id 建立索引的 representative 元信息目录。
    return dict_case_catalog

# representative 目录在导入期生成,主要服务 case_id 到样例元信息的快速查询。
REPRESENTATIVE_CASE_CATALOG = _build_case_catalog()  # 供 run-cases 按 case_id 快速查询样例元信息的目录表

# representative 默认执行顺序沿用坏例在前、理想样例在后的历史合同。
REPRESENTATIVE_CASE_ORDER = REPRESENTATIVE_BAD_CASE_IDS + REPRESENTATIVE_IDEAL_CASE_IDS  # representative corpus 的稳定执行顺序

# 公共导出名称文本保持 facade 稳定接口合同。
str_public_names_text = (
    "DEFAULT_CASE_RUN_DIR REPRESENTATIVE_BAD_CASE_IDS "
    "REPRESENTATIVE_CASE_CATALOG REPRESENTATIVE_CASE_ORDER "
    "REPRESENTATIVE_IDEAL_CASE_IDS run_verilog_cases"
)  # facade 公共导出名称文本

# 把公共导出名称文本切分成 __all__ 所需列表。
__all__ = str_public_names_text.split()  # representative facade 对外公开的符号列表

# _selected_representative_cases 把调用方 case 选择解析成元信息列表。
def _selected_representative_cases(raw_case_selection: Any) -> list[dict[str, Any]]:
    """把 run-cases 的 case 选择解析成 representative 元信息列表。

    参数:
        raw_case_selection: 调用方传入的 case 选择,可以是 None、字符串或字符串列表。

    返回:
        返回按请求顺序去重后的 representative 元信息列表。

    异常:
        ValueError: 当 case 选择为空或包含未知 case_id 时抛出。
    """

    # None 表示运行全部 representative 样例,并沿用稳定默认顺序。
    if raw_case_selection is None:

        # 复制默认顺序列表,避免调用方后续修改模块级常量。
        list_requested_case_ids = list(REPRESENTATIVE_CASE_ORDER)  # 本次请求的 representative case_id 列表

    # 单字符串输入表示只运行一个 case。
    elif isinstance(raw_case_selection, str):

        # 单 case 输入也统一包装成列表,便于后续去重和校验。
        list_requested_case_ids = [raw_case_selection]  # 单 case 输入对应的 case_id 列表

    # 列表和元组输入表示显式指定执行序列。
    elif isinstance(raw_case_selection, (list, tuple)):

        # 所有 case_id 都先转成字符串,保持旧接口宽松输入行为。
        list_requested_case_ids = [str(item) for item in raw_case_selection]  # 调用方显式指定的 case_id 列表

    # 其他输入类型不属于受支持的 case 选择合同。
    else:

        # 直接抛出输入合同错误,阻止未知类型继续进入 run-cases。
        raise ValueError(
            "> ERR: [Python] run_verilog_cases expects `case` to be None, a string, "
            "or a list of strings.",
        )

    # 空选择列表无法构成任何 representative 执行计划。
    if not list_requested_case_ids:

        # 阻止空选择进入下游,避免生成无意义的 run 目录。
        raise ValueError("> ERR: [Python] run_verilog_cases received an empty case selection.")

    # 已知 case_id 集合负责校验调用方输入是否合法。
    set_known_case_ids = set(REPRESENTATIVE_CASE_CATALOG)  # 当前 representative 目录中的全部合法 case_id

    # 去重后的顺序列表保持调用方第一次出现时的稳定顺序。
    list_unique_case_ids: list[str] = []  # 去重后的 representative case_id 列表

    # seen 集合用于识别重复 case_id,避免同一样例被重复执行。
    set_seen_case_ids: set[str] = set()  # 已经登记过的 representative case_id 集合

    # 逐项去重,保持调用方第一次出现时的稳定顺序。
    for str_case_id in list_requested_case_ids:

        # 已经登记过的 case 不再重复加入执行计划。
        if str_case_id in set_seen_case_ids:

            # 跳过重复样例,保持执行计划只含唯一 case。
            continue

        # 首次出现的 case_id 需要进入最终执行列表。
        list_unique_case_ids.append(str_case_id)

        # 记录已经登记过的 case_id,供后续重复检测复用。
        set_seen_case_ids.add(str_case_id)

    # 未知 case_id 会在这里统一收集,便于一次性向用户报告。
    list_unknown_case_ids: list[str] = []  # 本次请求里无法在 representative 目录找到的 case_id 列表

    # 再扫一遍去重后的请求列表,单独收集不存在于目录中的 case_id。
    for str_case_id in list_unique_case_ids:

        # 只有目录里不存在的样例才需要进入未知列表。
        if str_case_id not in set_known_case_ids:

            # 记录无法识别的 case_id,便于后续一次性报错。
            list_unknown_case_ids.append(str_case_id)

    # 只要存在未知 case_id,就不能继续进入实际执行阶段。
    if list_unknown_case_ids:

        # 可用样例文本用于提示调用方当前支持的 representative case 范围。
        str_available_cases = ", ".join(REPRESENTATIVE_CASE_ORDER)  # representative 目录支持的全部 case_id 文本

        # 未知样例文本用于把错误原因稳定呈现给调用方。
        str_unknown_cases = ", ".join(list_unknown_case_ids)  # 本次请求中无法识别的 case_id 文本

        # 把未知样例和可用样例一起返回,便于调用方立即修正输入。
        raise ValueError(
            f"> ERR: [Python] Unknown representative case(s): {str_unknown_cases}. "
            f"Available cases: {str_available_cases}.",
        )

    # 返回去重后的 representative 元信息列表,供实际执行阶段消费。
    return [dict(REPRESENTATIVE_CASE_CATALOG[str_case_id]) for str_case_id in list_unique_case_ids]

# _case_artifact_paths 生成单个 case 的固定产物路径合同。
def _case_artifact_paths(path_case_dir: Path, path_source_reference: Path) -> dict[str, Path]:
    """生成单个 representative case 的固定工件路径集合。

    参数:
        path_case_dir: 当前 case 的独立运行目录。
        path_source_reference: 当前 case 的源 RTL 参考路径。

    返回:
        返回包含 source、governed、报告和 verify 目录的路径字典。
    """

    # 源文件后缀优先沿用参考 RTL 的原始后缀,缺省时退回 .v。
    str_case_suffix = path_source_reference.suffix or ".v"  # 当前 case 源文件副本使用的 RTL 后缀

    # 返回单 case 运行期间全部固定产物路径。
    return {
        "source": path_case_dir / f"source{str_case_suffix}",  # 原始样例副本路径
        "governed": path_case_dir / f"governed{str_case_suffix}",  # governed RTL 副本路径
        "stage_status": path_case_dir / "stage_status.json",  # 单 case 阶段状态报告路径
        "strict_report_json": path_case_dir / "strict_report.json",  # strict 质量门 JSON 报告路径
        "strict_report_md": path_case_dir / "strict_report.md",  # 供人工查看 strict 结论的 Markdown 报告路径
        "verify_existing_dir": path_case_dir / "verify_existing",  # verify-existing 运行目录
    }

# _write_json 把字典稳定写成 UTF-8 JSON 文件。
def _write_json(path_output: Path, dict_payload: dict[str, Any]) -> None:
    """把结构化字典稳定写入 UTF-8 JSON 文件。

    参数:
        path_output: 目标 JSON 文件路径。
        dict_payload: 待序列化的字典载荷。

    返回:
        无业务返回值;结果直接落盘到 path_output。
    """

    # 父目录在写文件前必须存在,避免 JSON 落盘因目录缺失失败。
    path_output.parent.mkdir(parents=True, exist_ok=True)

    # 把结构化字典稳定写成 UTF-8 JSON 文本,并保留换行结尾。
    path_output.write_text(
        json.dumps(dict_payload, indent=2, ensure_ascii=False) + "\n",
        encoding="utf-8",
    )

# _quality_issue_count 统计 strict 质量门指定严重级别的发现项数量。
def _quality_issue_count(dict_report: dict[str, Any], str_severity: str) -> int:
    """统计质量门报告中指定严重级别的发现项数量。

    参数:
        dict_report: 质量门返回的报告字典。
        str_severity: 待统计的 issue 严重级别名称。

    返回:
        返回匹配指定严重级别的 issue 数量。
    """

    # issue 列表只在报告字典形状正确时才继续统计。
    list_issues = dict_report.get("issues", []) if isinstance(dict_report, dict) else []  # 当前质量门报告中的 issue 列表

    # 返回匹配指定严重级别的 issue 数量。
    return sum(
        1
        for dict_issue in list_issues
        if isinstance(dict_issue, dict) and dict_issue.get("severity") == str_severity
    )

# _strict_quality_stage_payload 生成 strict 质量门阶段的稳定摘要字典。
def _strict_quality_stage_payload(
    bool_strict_ok: bool,
    dict_strict_report: dict[str, Any],
    path_report_json: Path,
    path_report_md: Path,
) -> dict[str, Any]:
    """生成 strict 质量门阶段的稳定摘要字典。

    参数:
        bool_strict_ok: 当前 strict 质量门是否通过。
        dict_strict_report: strict 质量门返回的完整报告字典。
        path_report_json: strict JSON 报告的落盘路径。
        path_report_md: strict Markdown 报告的落盘路径。

    返回:
        返回供 stage_status 记录的 strict 阶段摘要字典。
    """

    # 返回供 stage_status 持久化的 strict 质量门阶段摘要。
    return {
        "status": "passed" if bool_strict_ok else "reported",  # 当前 strict 阶段对外呈现的状态文本
        "profile": "formatter-normalize",  # 本轮 strict 检查实际使用的 formatter profile
        "ok": bool_strict_ok,  # strict 质量门是否满足通过条件
        "errors": _quality_issue_count(dict_strict_report, "error"),  # strict 报告里的 error 级问题数量
        "warnings": _quality_issue_count(dict_strict_report, "warning"),  # strict 报告里需要人工关注的 warning 数量
        "report_json": str(path_report_json),  # 自动化读取的 strict JSON 报告路径
        "report_md": str(path_report_md),  # 人工审阅的 strict Markdown 报告路径
    }

# _existing_path_str 把已存在工件路径转换为摘要可消费的字符串。
def _existing_path_str(path_value: Path) -> str | None:
    """把已存在的文件或目录路径转换成可选字符串。

    参数:
        path_value: 待检查的文件或目录路径。

    返回:
        如果路径已经存在则返回其字符串形式,否则返回 None。
    """

    # 已存在的路径需要写进摘要,便于上层直接定位工件。
    if path_value.exists():

        # 返回可直接放入 JSON 摘要的稳定字符串路径。
        return str(path_value)

    # 缺失工件在摘要中保持 None,表示当前产物尚未生成。
    return None

# _case_summary_payload 把单个 case 的运行结果裁剪成稳定摘要字段。
def _case_summary_payload(
    dict_case_spec: dict[str, Any],
    dict_case_paths: dict[str, Path],
    dict_stage_status: dict[str, Any],
    bool_strict_ok: bool,
    str_verify_status: str | None,
) -> dict[str, Any]:
    """把单个 representative case 的运行结果裁剪成稳定摘要字段。

    参数:
        dict_case_spec: 当前 representative case 的元信息字典。
        dict_case_paths: 当前 case 的固定工件路径字典。
        dict_stage_status: 当前 case 的阶段状态字典。
        bool_strict_ok: 当前 case 的 strict 质量门是否通过。
        str_verify_status: 当前 case 的 verify-existing 结果状态文本。

    返回:
        返回供 summary.json 和 summary.md 复用的稳定摘要字典。
    """

    # source 副本路径只在文件真实存在时才写进摘要。
    str_source_path = _existing_path_str(dict_case_paths["source"])  # source 副本的可选字符串路径

    # governed RTL 路径只在 formatter-preserve 真实落盘后才写进摘要。
    str_governed_path = _existing_path_str(dict_case_paths["governed"])  # governed RTL 的可选字符串路径

    # strict JSON 报告只在质量门真实写出后才回填到摘要中。
    str_strict_report_json = _existing_path_str(dict_case_paths["strict_report_json"])  # strict JSON 报告的可选字符串路径

    # strict Markdown 报告只在人工审阅文件真实写出后才回填到摘要中。
    str_strict_report_md = _existing_path_str(dict_case_paths["strict_report_md"])  # 供人工回看 strict 细节的 Markdown 报告路径

    # verify-existing 目录存在时要把目录位置回填进单 case 摘要。
    if dict_case_paths["verify_existing_dir"].is_dir():

        # 目录已生成时把路径转成摘要可直接展示的字符串。
        str_verify_existing_dir = str(dict_case_paths["verify_existing_dir"])  # verify-existing 工件目录的字符串路径

    # verify-existing 没有执行或没有生成目录时,摘要显式保持空值。
    else:

        # 用 None 明确表达 verify-existing 工件目录当前不存在。
        str_verify_existing_dir = None  # verify-existing 工件目录尚未生成

    # 返回供全局 summary 复用的稳定单 case 摘要结构。
    return {
        "case_id": str(dict_case_spec["case_id"]),  # summary 中用于唯一标识样例的 case_id
        "cohort": str(dict_case_spec["cohort"]),  # summary 中用于区分坏例和理想样例的 cohort
        "status": str(dict_stage_status["status"]),  # 单 case 主流程最终落下的完成状态
        "source_path": str_source_path,  # 复制后的 source RTL 文件路径,缺失时为空
        "governed_path": str_governed_path,  # formatter-preserve 生成的 governed RTL 路径,缺失时为空
        "stage_status_path": str(dict_case_paths["stage_status"]),  # 可直接回放阶段细节的 stage_status 文件路径
        "strict_ok": bool_strict_ok,  # strict 质量门对当前样例给出的通过标记
        "strict_report_json": str_strict_report_json,  # 自动化消费的 strict JSON 报告路径,缺失时为空
        "strict_report_md": str_strict_report_md,  # 人工查看的 strict Markdown 报告路径,缺失时为空
        "verify_existing_status": str_verify_status,  # verify-existing 阶段汇报的状态文本
        "verify_existing_dir": str_verify_existing_dir,  # verify-existing 工件目录路径,未生成时为空
    }

# _run_single_representative_case 负责执行一个 representative case。
def _run_single_representative_case(
    dict_case_spec: dict[str, Any],
    path_case_dir: Path,
) -> dict[str, Any]:
    """执行单个 representative case,并写出固定合同要求的产物。

    参数:
        dict_case_spec: 当前 representative case 的元信息字典。
        path_case_dir: 当前 case 的独立运行目录。

    返回:
        返回当前 case 的稳定摘要字典。

    异常:
        ValueError: 当代表样例源 RTL 缺失时抛出,并在 stage_status 中记录失败信息。
    """

    # 源参考路径在进入执行逻辑前先归一化成 Path。
    path_source_reference = Path(dict_case_spec["source"])  # 当前 representative 样例的参考 RTL 路径

    # 当前 case 的固定工件路径在执行前一次性展开。
    dict_case_paths = _case_artifact_paths(path_case_dir, path_source_reference)  # 当前 case 的固定工件路径字典

    # strict 质量门结果默认视为未通过,只有执行成功后才覆盖。
    bool_strict_ok = False  # 当前 case 的 strict 质量门是否通过

    # verify-existing 结果默认留空,只有坏例路径真正跑完才回填状态。
    str_verify_status: str | None = None  # 当前 case 的 verify-existing 状态文本

    # 单 case 阶段状态从 running 起步,便于异常时仍能留下轨迹。
    dict_stage_status = {
        "case_id": dict_case_spec["case_id"],  # 供阶段回放重新定位样例的 stable case_id
        "cohort": dict_case_spec["cohort"],  # 标明当前样例属于 bad 还是 ideal cohort
        "source_reference": str(path_source_reference),  # 记录 tests/cases 下原始 RTL 参考路径
        "status": "running",  # 当前单 case 主流程开始执行时的阶段状态
        "stages": {},  # 单 case 内部 copy、quality 与 verify 的阶段结果容器
    }  # 当前 representative case 的阶段状态字典

    # stages 子字典集中承接 copy、quality 和 verify 的分阶段结果。
    dict_stages = dict_stage_status["stages"]  # 当前 case 的分阶段执行记录字典

    # 单 case 的主流程使用 try/finally,确保 stage_status 始终落盘。
    try:

        # 当前 case 目录需要在执行前就创建,避免后续工件写出失败。
        path_case_dir.mkdir(parents=True, exist_ok=True)

        # 缺失源 RTL 时不能继续运行 representative case。
        if not path_source_reference.is_file():

            # 直接抛出缺失源文件错误,阻止无效 case 继续执行。
            raise ValueError(
                f"> ERR: [Python] Representative case source is missing: {path_source_reference}",
            )

        # source 副本路径会被后续 governed RTL 和报告阶段反复复用。
        path_case_source = dict_case_paths["source"]  # 当前 case 的 source RTL 副本路径

        # governed 路径承接 formatter-preserve 输出的 RTL 文本。
        path_case_governed = dict_case_paths["governed"]  # formatter-preserve 准备写入的 governed RTL 目标路径

        # strict JSON 报告路径供自动化读取和回归比较复用。
        path_report_json = dict_case_paths["strict_report_json"]  # 当前 case 的 strict JSON 报告路径

        # strict Markdown 报告路径供人工检查 representative 结果复用。
        path_report_md = dict_case_paths["strict_report_md"]  # 供人工检查 representative 结果的 strict Markdown 报告路径

        # verify-existing 目录只在坏例路径下真正执行并承接工件。
        path_verify_existing_dir = dict_case_paths["verify_existing_dir"]  # 当前 case 的 verify-existing 工件目录

        # 先复制源 RTL,确保后续 governed 处理不改动 tests/cases 原件。
        path_case_source.write_bytes(path_source_reference.read_bytes())

        # copy_source 阶段记录复制后的副本位置,便于后续回放。
        dict_stages["copy_source"] = {
            "status": "completed",  # source 副本复制已经完成
            "path": str(path_case_source),  # source 副本的落盘路径
        }

        # formatter-preserve 需要先读取源 RTL 并返回源编码信息。
        str_source_text, str_source_encoding = read_verilog_source(path_case_source)  # source 副本读取得到的 RTL 文本与编码

        # preserve backend 保证 governed RTL 尽量贴近原始结构与编码语义。
        process_formatter_backend = create_formatter_backend(profile="formatter-preserve")  # 生成 governed RTL 时使用的 preserve formatter 后端

        # governed RTL 文本由 preserve backend 基于 source 副本生成。
        str_governed_text = process_formatter_backend.format_text(  # preserve backend 产出的 governed RTL 文本
            str_source_text,  # formatter-preserve 的源 RTL 文本输入
            path_case_source,  # formatter-preserve 诊断时引用的 source 副本路径
        )

        # 把 governed RTL 文本稳定写到单 case 合同要求的位置。
        path_case_governed.write_text(str_governed_text, encoding="utf-8")

        # formatter-preserve 阶段记录生成结果与命中的源编码。
        dict_stages["formatter_preserve"] = {
            "status": "completed",  # preserve 格式化阶段已经完成
            "profile": "formatter-preserve",  # 当前使用的 formatter profile
            "source_encoding": str_source_encoding,  # 读取源 RTL 时命中的编码名称
            "path": str(path_case_governed),  # governed RTL 的落盘路径
        }

        # strict 质量门配置固定为 normalize profile,并同时写 JSON/Markdown 报告。
        dict_strict_config = {
            "strict": True,  # 当前 representative case 以严格模式运行质量门
            "formatter_profile": "formatter-normalize",  # strict 质量门使用的 formatter profile
            "report_json": path_report_json,  # strict 阶段要写给自动化读取的 JSON 报告路径
            "report_md": path_report_md,  # strict 阶段要写给人工查看的 Markdown 报告路径
        }  # 当前 case 的 strict 质量门配置字典

        # governed RTL 在这里进入 strict 质量门检查。
        dict_strict_report = check_verilog_quality(  # strict 质量门返回的完整报告字典
            path_case_governed,  # 当前 governed RTL 的待检路径
            config=dict_strict_config,  # 当前样例的 strict 质量门固定配置
        )

        # strict 质量门的通过状态直接取自报告字典中的 ok 字段。
        bool_strict_ok = bool(dict_strict_report.get("ok"))  # strict 质量门从报告里读出的通过标记

        # strict 质量门阶段摘要在这里统一整理,减少主流程里的字面量噪声。
        dict_stages["strict_quality_gate"] = _strict_quality_stage_payload(  # 当前样例的 strict 质量门阶段摘要
            bool_strict_ok,  # strict 质量门是否通过
            dict_strict_report,  # strict 质量门返回的完整报告
            path_report_json,  # strict JSON 报告的落盘路径
            path_report_md,  # 供人工浏览 strict 结论的 Markdown 文件路径
        )

        # 只有 bad cohort 才需要继续进入 verify-existing 验证路径。
        if dict_case_spec["cohort"] == "bad":

            # verify-existing 复用 conservative + static 的固定 representative 合同。
            dict_verify_config = {
                "out_dir": path_verify_existing_dir,  # 坏例 verify-existing 工件要落到的目录
                "automation_mode": "conservative",  # 坏例路径只允许保守自动化策略
                "readiness": "static",  # 坏例 verify-existing 固定运行在 static 档位
                "run_external": False,  # 坏例 representative 路径默认不触发外部验证链
            }  # 当前坏例的 verify-existing 配置字典

            # 坏例 governed RTL 在这里进入 verify-existing 流程。
            dict_verify_result = verify_existing_verilog(  # verify-existing 返回的完整结果字典
                path_case_governed,  # 当前坏例对应的 governed RTL 路径
                config=dict_verify_config,  # 当前坏例的 verify-existing 固定配置
            )

            # verify-existing 状态文本优先沿用 runtime 返回字段。
            str_verify_status = str(dict_verify_result.get("status") or "completed")  # 当前坏例的 verify-existing 状态文本

            # verify-existing 阶段记录结果状态与运行目录。
            dict_stages["verify_existing"] = {
                "status": "completed",  # verify-existing 阶段已经执行完成
                "result_status": str_verify_status,  # verify-existing 产出的最终状态文本
                "run_dir": str(path_verify_existing_dir),  # verify-existing 工件目录路径
            }

        # ideal cohort 不需要进入 verify-existing,仅记录跳过原因。
        else:

            # 跳过记录明确说明 verify-existing 只服务 representative 坏例。
            dict_stages["verify_existing"] = {
                "status": "skipped",  # 当前 ideal case 不执行 verify-existing
                "reason": "verify-existing only runs for representative bad cases.",  # verify-existing 跳过原因
            }

        # 所有阶段都正常完成后,把整体状态标记为 completed。
        dict_stage_status["status"] = "completed"  # 当前单 case 主流程已经完整走完

    # 任何异常都需要转成 failed 状态并记录错误文本。
    except Exception as exc:

        # 当前 case 进入 failed 状态,便于 summary 聚合失败数量。
        dict_stage_status["status"] = "failed"  # 当前单 case 主流程因为异常转为 failed

        # 错误文本直接写入阶段状态,供后续 handoff 与排障复用。
        dict_stage_status["error"] = str(exc)  # 当前异常文本会写入 stage_status 供排障复用

    # 无论成功还是失败,都必须把 stage_status 稳定落盘。
    finally:

        # 单 case 阶段状态写出后,后续 summary 才能稳定引用该文件。
        _write_json(dict_case_paths["stage_status"], dict_stage_status)

    # 返回当前 representative case 的稳定摘要字典。
    return _case_summary_payload(
        dict_case_spec,
        dict_case_paths,
        dict_stage_status,
        bool_strict_ok,
        str_verify_status,
    )

# _representative_summary_payload 负责构造全局 run-cases 摘要字典。
def _representative_summary_payload(
    path_run_dir: Path,
    list_case_results: list[dict[str, Any]],
    int_completed_cases: int,
) -> dict[str, Any]:
    """构造 representative run-cases 的全局摘要字典。

    参数:
        path_run_dir: 当前 representative run 的根目录。
        list_case_results: 全部单 case 摘要列表。
        int_completed_cases: 当前 run 中状态为 completed 的 case 数量。

    返回:
        返回供 summary.json 和 summary.md 复用的全局摘要字典。
    """

    # 全部完成时把状态标记为 completed,否则保持 failed。
    str_status = "completed" if int_completed_cases == len(list_case_results) else "failed"  # representative run 的整体状态文本

    # 返回 representative run 的稳定摘要结构。
    return {
        "status": str_status,  # representative run 的整体状态
        "run_dir": str(path_run_dir),  # 当前 representative run 的根目录
        "case_count": len(list_case_results),  # 当前 run 包含的总 case 数量
        "completed_cases": int_completed_cases,  # 当前 run 中成功完成的 case 数量
        "failed_cases": len(list_case_results) - int_completed_cases,  # 当前 run 中失败的 case 数量
        "cases": list_case_results,  # 全部单 case 的稳定摘要列表
    }

# _representative_summary_lead_lines 生成 summary.md 固定不变的头部行。
def _representative_summary_lead_lines(dict_summary: dict[str, Any]) -> list[str]:
    """生成 summary.md 固定不变的标题、计数和表头行。

    参数:
        dict_summary: representative run 的全局摘要字典。

    返回:
        返回 summary.md 在追加 case 行之前的固定头部行列表。
    """

    # 返回 summary.md 开头固定不变的标题、计数摘要和表头行。
    return [
        "# representative-10",  # Markdown 标题行
        "",  # 标题与摘要字段之间的空行
        f"- status: {dict_summary['status']}",  # 代表当前 run 的整体状态
        f"- case_count: {dict_summary['case_count']}",  # 代表当前 run 的样例总数
        f"- completed_cases: {dict_summary['completed_cases']}",  # 代表当前 run 的完成样例数
        f"- failed_cases: {dict_summary['failed_cases']}",  # 代表当前 run 的失败样例数
        "",  # 摘要字段与表头之间的空行
        "| case_id | cohort | status | strict_ok | verify_existing |",  # representative 结果表头
        "| --- | --- | --- | --- | --- |",  # representative 结果表格分隔线
    ]

# _representative_summary_markdown 把全局摘要转换为 Markdown 文本。
def _representative_summary_markdown(dict_summary: dict[str, Any]) -> str:
    """把 representative 全局摘要转换为 Markdown 文本。

    参数:
        dict_summary: representative run 的全局摘要字典。

    返回:
        返回可直接写入 summary.md 的 Markdown 文本。
    """

    # 先拿到 summary.md 固定不变的标题和表头行,后续只追加每个 case 的表格行。
    list_lines = _representative_summary_lead_lines(dict_summary)  # summary.md 头部固定行的逐行文本列表

    # 逐个样例追加表格行,保持 summary.md 与 summary.json 一致。
    for dict_case in dict_summary.get("cases", []):

        # verify 状态缺失时统一显示 n/a,便于理想样例阅读。
        str_verify_display = str(dict_case.get("verify_existing_status") or "n/a")  # 当前 case 的 verify-existing 展示文本

        # strict_ok 在 Markdown 中统一转成 yes 或 no。
        str_strict_display = "yes" if dict_case.get("strict_ok") else "no"  # 当前 case 的 strict 质量门展示文本

        # 把当前 case 的摘要追加到 Markdown 表格。
        list_lines.append(
            f"| {dict_case['case_id']} | {dict_case['cohort']} | {dict_case['status']} | "
            f"{str_strict_display} | {str_verify_display} |",
        )

    # 返回带换行结尾的 Markdown 文本,便于文件对比和追加查看。
    return "\n".join(list_lines) + "\n"

# run_verilog_cases 提供 representative corpus 的公共 facade 入口。
def run_verilog_cases(
    *,
    config: dict[str, Any] | None = None,
    **legacy_options: Any,
) -> dict[str, Any]:
    """运行 representative existing-RTL corpus,并写出固定摘要与报告。

    参数:
        config: 新式 facade 配置字典;缺省时只使用 legacy_options。
        legacy_options: 旧调用方传入的兼容关键字参数。

    返回:
        返回 representative run 的全局稳定摘要字典。
    """

    # run-cases 白名单文本先单独命名,避免集合定义行过长。
    str_allowed_keys_text = "out_dir case"  # run-cases 入口允许的兼容键文本

    # 再把白名单文本切分成集合,供兼容配置合并逻辑复用。
    set_allowed_keys = set(str_allowed_keys_text.split())  # run-cases 入口允许的兼容配置键集合

    # 合并 config 与 legacy_options,得到统一的 run-cases 配置视图。
    dict_options = _merged_option_dict(  # run-cases 入口合并后的统一配置字典
        "run_verilog_cases",  # 当前 facade 入口名称
        config,  # 新式调用方传入的配置字典
        legacy_options,  # 旧式关键字参数载荷
        allowed_keys=set_allowed_keys,  # run-cases 允许透传的字段集合
    )

    # run 根目录缺省落在 representative-10,保持旧合同不变。
    path_run_dir = Path(dict_options.get("out_dir") or DEFAULT_CASE_RUN_DIR)  # representative run 的根目录

    # run 根目录需要提前创建,便于后续按 case 落盘工件。
    path_run_dir.mkdir(parents=True, exist_ok=True)

    # 当前请求的 case 选择在这里统一解析成元信息列表。
    list_selected_cases = _selected_representative_cases(dict_options.get("case"))  # 本次要执行的 representative 元信息列表

    # case 级摘要列表承接每个 representative 样例的稳定结果。
    list_case_results: list[dict[str, Any]] = []  # 本次 representative run 的单 case 摘要列表

    # completed 计数用于汇总全局状态和失败数量。
    int_completed_cases = 0  # 当前 representative run 中完成的 case 数量

    # cases 子目录承接每个 representative 样例的独立运行目录。
    path_cases_root = path_run_dir / "cases"  # 本次 representative run 的 case 根目录

    # 逐个执行选中的 representative 样例,并保持请求顺序稳定。
    for dict_case_spec in list_selected_cases:

        # 当前 case 目录以 case_id 命名,便于人工定位对应工件。
        path_case_dir = path_cases_root / str(dict_case_spec["case_id"])  # 当前 representative case 的独立运行目录

        # 运行单个 representative case,并返回其稳定摘要。
        dict_case_result = _run_single_representative_case(dict_case_spec, path_case_dir)  # 当前 representative case 的稳定摘要结果

        # 把当前 case 的稳定摘要追加到全局结果列表。
        list_case_results.append(dict_case_result)

        # 只有 completed 状态才计入完成数量。
        if dict_case_result["status"] == "completed":

            # completed 计数用于最终 summary 的状态与计数统计。
            int_completed_cases += 1  # 本次 representative run 的完成计数加一

    # 全局摘要在这里统一汇总,供 JSON 和 Markdown 双出口复用。
    dict_summary = _representative_summary_payload(  # 汇总整个 representative run 的最终摘要
        path_run_dir,  # 把摘要绑定到当前 run 的根目录
        list_case_results,  # 汇总所有单样例执行后的稳定结果列表
        int_completed_cases,  # 告诉摘要里有多少样例真正走完主流程
    )

    # summary.json 作为自动化消费入口,始终稳定写出。
    _write_json(path_run_dir / "summary.json", dict_summary)

    # summary.md 作为人工检查入口,始终稳定写出。
    (path_run_dir / "summary.md").write_text(
        _representative_summary_markdown(dict_summary),
        encoding="utf-8",
    )

    # 返回 representative run 的全局稳定摘要字典。
    return dict_summary
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