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/verifier.py

View on GitHub
"""校验 Verilog workflow 相邻阶段的契约一致性。"""

# 延迟注解解析,避免导入期处理嵌套 JSON 类型。
from __future__ import annotations

# 运行时契约由 JSON 字典承载,类型提示保持宽容。
from typing import Any

# 公开入口汇总阶段契约、计划接口和语义执行问题。
def verify_stage(
    plan: dict[str, Any],
    from_contract: dict[str, Any],
    to_contract: dict[str, Any],
) -> dict[str, Any]:
    """校验 workflow 相邻阶段之间的契约兼容性。

    参数:
        plan: codegen plan 或规范化计划,用于提供期望 top 和端口。
        from_contract: 上一阶段导出的契约。
        to_contract: 当前阶段导出的契约。

    返回:
        保持旧版字段形状的校验报告,包含 ready、issues 和语义执行摘要。
    """

    # issues 汇总原始契约问题、接口漂移和测试用例漂移。
    list_issues: list[dict[str, Any]] = []  # 阶段契约问题列表

    # 上一阶段问题保留原诊断内容,只附加来源侧。
    list_issues.extend(_contract_issues(from_contract, "from"))

    # 当前阶段问题同样附加来源侧,便于报告定位。
    list_issues.extend(_contract_issues(to_contract, "to"))

    # RTL 输出契约需要和 plan 中的 top/ports 对齐。
    list_issues.extend(plan_contract_interface_issues(plan, to_contract))

    # reference 和 RTL 阶段的 case_ids 不一致会降低验证闭环可信度。
    list_issues.extend(_check_cases(from_contract, to_contract))

    # 语义执行指标独立解析,供报告字段和 recommended_action 复用。
    dict_semantic = _semantic_execution_issues(to_contract)  # 当前阶段语义执行诊断

    # 语义问题加入统一 issues 列表。
    list_issues.extend(dict_semantic["issues"])

    # ready 只要存在 error 级问题就为 False。
    bool_ready = not any(item.get("severity") == "error" for item in list_issues)  # 阶段契约是否可继续

    # semantic_ready 显式布尔 False 时建议修复语义 testbench。
    semantic_ready_value = dict_semantic["semantic_ready"]  # 当前阶段语义 ready 原始值

    # 仅布尔 False 触发 repair_semantic_testbench,None 表示未检查。
    bool_requires_semantic_repair = isinstance(semantic_ready_value, bool) and not semantic_ready_value  # 是否建议修复语义 testbench

    # 默认没有语义修复建议。
    str_recommended_action = None  # 下一步建议动作

    # 语义执行明确失败时给出旧版建议动作。
    if bool_requires_semantic_repair:

        # 推荐动作字符串由旧版报告消费,不能改名。
        str_recommended_action = "repair_semantic_testbench"  # 语义 testbench 修复动作

    # error_sources 去重排序后供 workflow trace 和 repair plan 使用。
    list_error_sources = sorted({str(item.get("source")) for item in list_issues if item.get("source")})  # 问题来源集合

    # 返回字段保持旧版契约,避免上游报告解析变化。
    return {
        "version": 1,
        "target": plan.get("target", "rtl"),
        "ready": bool_ready,
        "issues": list_issues,
        "semantic_ready": dict_semantic["semantic_ready"],
        "mismatched_cases": dict_semantic["mismatched_cases"],
        "checkpoint_drift": dict_semantic["checkpoint_drift"],
        "failed_cases": dict_semantic["failed_cases"],
        "localization_confidence": dict_semantic["localization_confidence"],
        "error_sources": list_error_sources,
        "recommended_action": str_recommended_action,
        "summary": {
            "from_target": from_contract.get("target"),
            "to_target": to_contract.get("target"),
            "top": to_contract.get("top"),
        },
    }

# 公开接口校验器检查 plan 期望端口和 RTL 契约端口是否一致。
def plan_contract_interface_issues(plan: dict[str, Any], contract: dict[str, Any]) -> list[dict[str, Any]]:
    """检查 RTL 阶段契约是否保留计划中的 top 和端口定义。

    参数:
        plan: 提供期望模块名和 interfaces.ports 的计划字典。
        contract: 当前阶段导出的契约字典。

    返回:
        error 级接口漂移问题列表;非 RTL 契约返回空列表。
    """

    # 当前函数只验证 RTL 契约,其它阶段没有端口约束。
    list_issues: list[dict[str, Any]] = []  # RTL 接口契约问题

    # 非 RTL 目标不执行 top/ports 对齐检查。
    if contract.get("target") != "rtl":

        # 返回空问题,保持非 RTL 阶段宽容。
        return list_issues

    # plan.name 是期望的 RTL 顶层模块名。
    value_expected_top = plan.get("name")  # 计划中的期望 top 名称

    # contract.top 是当前阶段实际解析到的 RTL 顶层名。
    value_observed_top = contract.get("top")  # 当前契约中的 top 名称

    # 两侧都提供 top 且不一致时报告顶层漂移。
    if value_expected_top and value_observed_top and value_expected_top != value_observed_top:

        # 顶层不一致通常表示生成文件不是目标模块。
        list_issues.append(
            _issue("error", f"RTL top mismatch: expected {value_expected_top!r}, observed {value_observed_top!r}.")
        )

    # 期望端口按 name 建索引,便于后续逐个比较。
    dict_expected_ports = {
        str(item.get("name")): item  # 计划端口对象
        for item in plan.get("interfaces", {}).get("ports", [])  # 计划端口列表
        if isinstance(item, dict) and item.get("name")  # 只索引 RTL 契约中可命名匹配的端口
    }  # 计划端口索引

    # 观测端口同样按 name 建索引。
    dict_observed_ports = {
        str(item.get("name")): item  # 契约端口对象
        for item in contract.get("ports", [])  # RTL 契约端口列表
        if isinstance(item, dict) and item.get("name")  # 只保留具名端口
    }  # RTL 契约端口索引

    # 逐个计划端口检查是否缺失、方向漂移或位宽漂移。
    for str_port_name, dict_expected_port in dict_expected_ports.items():

        # observed 缺失说明 RTL 没有导出计划要求的端口。
        dict_observed_port = dict_observed_ports.get(str_port_name)  # 当前端口的 RTL 观测定义

        # 缺失端口直接记录 error,并跳过后续方向/位宽比较。
        if not dict_observed_port:

            # 端口缺失会破坏 testbench 和集成契约。
            list_issues.append(_issue("error", f"RTL port {str_port_name!r} is missing."))

            # 当前端口没有可比较的观测定义。
            continue

        # 两侧都声明 direction 时必须完全一致。
        if (
            dict_expected_port.get("direction")
            and dict_observed_port.get("direction")
            and dict_expected_port["direction"] != dict_observed_port["direction"]
        ):

            # 方向漂移会改变模块使用方式。
            list_issues.append(_issue("error", f"RTL port {str_port_name!r} direction changed."))

        # 期望宽度缺省按 1 处理,匹配旧版逻辑。
        int_expected_width = int(dict_expected_port.get("width", 1) or 1)  # 计划端口位宽

        # 观测位宽允许缺失;缺失时不报宽度漂移。
        value_observed_width = dict_observed_port.get("width")  # RTL 契约端口位宽

        # 观测位宽存在且和期望不同则报告 error。
        if value_observed_width is not None and int(value_observed_width) != int_expected_width:

            # 长错误消息拆分成变量,避免报告构造行过宽。
            str_message = (  # 位宽漂移诊断文本
                f"RTL port {str_port_name!r} width changed "  # 端口名和漂移类型
                f"from {int_expected_width} to {value_observed_width}."  # 期望位宽到观测位宽
            )

            # 记录当前端口位宽漂移。
            list_issues.append(_issue("error", str_message))

    # 返回 RTL 接口漂移问题列表。
    return list_issues

# 契约问题复制器给已有 issue 标注来源阶段。
def _contract_issues(contract: dict[str, Any], side: str) -> list[dict[str, Any]]:
    """复制契约内已有问题并标注来源侧。

    参数:
        contract: workflow 阶段导出的契约字典。
        side: 当前问题所属的阶段侧标识,通常为 from 或 to。

    返回:
        已补充 side 字段的契约问题列表。
    """

    # 复制后的问题列表不会反写原始 contract。
    list_issues: list[dict[str, Any]] = []  # 附加 side 后的契约问题

    # contract.issues 可能缺失,按空列表处理。
    for item in contract.get("issues", []) or []:

        # 只有 dict 形态问题才能安全附加 side 字段。
        if isinstance(item, dict):

            # side 字段帮助诊断问题来自 from 还是 to 阶段。
            list_issues.append({**item, "side": side})

    # 返回复制后的契约问题。
    return list_issues

# case_ids 检查器确认两阶段引用同一批参考用例。
def _check_cases(from_contract: dict[str, Any], to_contract: dict[str, Any]) -> list[dict[str, Any]]:
    """检查两阶段契约是否引用同一批 reference case。

    参数:
        from_contract: 上一阶段导出的契约字典。
        to_contract: 当前阶段导出的契约字典。

    返回:
        用例集合漂移问题列表;未漂移时返回空列表。
    """

    # from 阶段 case_ids 是参考契约期望覆盖的用例集合。
    set_expected_cases = {str(item) for item in from_contract.get("case_ids", []) or []}  # 参考阶段用例集合

    # to 阶段 case_ids 是当前契约实际覆盖的用例集合。
    set_observed_cases = {str(item) for item in to_contract.get("case_ids", []) or []}  # 当前阶段用例集合

    # 两侧都有用例且集合不一致时报告 warning。
    if set_expected_cases and set_observed_cases and set_expected_cases != set_observed_cases:

        # 用例集合漂移影响覆盖率,但不一定阻断生成。
        return [_issue("warning", "Reference case ids differ between stages.", source="testbench_issue")]

    # 没有发现用例集合漂移。
    return []

# 语义执行指标解析器把 transcript/checkpoint 失败转成契约问题。
def _semantic_execution_issues(contract: dict[str, Any]) -> dict[str, Any]:
    """把契约中的 semantic_execution 指标转换为统一诊断。

    参数:
        contract: 当前阶段导出的契约字典。

    返回:
        包含语义执行问题、ready 状态、漂移用例和定位置信度的摘要字典。
    """

    # metrics 只有 dict 形态时才可读取 semantic_execution。
    dict_metrics = contract.get("metrics") if isinstance(contract.get("metrics"), dict) else {}  # 当前契约指标对象

    # 原始 semantic_execution 可能缺失或不是对象,先以动态值承接。
    value_semantic_execution = dict_metrics.get("semantic_execution")  # 原始语义执行指标

    # semantic_execution 缺失时使用空字典表达当前阶段未运行语义用例。
    dict_semantic_execution = value_semantic_execution if isinstance(value_semantic_execution, dict) else {}  # 语义执行指标

    # 没有语义指标时返回空诊断,但保留字段形状。
    if not dict_semantic_execution:

        # None 表示未检查,而不是语义检查失败。
        return {
            "issues": [],
            "semantic_ready": None,
            "mismatched_cases": [],
            "checkpoint_drift": [],
            "failed_cases": [],
            "localization_confidence": None,
        }

    # 语义执行问题会附加到 verify_stage 的统一 issues。
    list_issues: list[dict[str, Any]] = []  # 语义执行问题列表

    # semantic_ready 是上游语义执行器的总体就绪判断。
    value_semantic_ready = dict_semantic_execution.get("semantic_ready")  # 语义执行总体状态

    # mismatched_cases 记录 reference/RTL 用例覆盖差异。
    mismatched_cases = dict_semantic_execution.get("mismatched_cases", []) or []  # 覆盖不一致的用例

    # checkpoint_drift 记录 checkpoint 名称或值的漂移。
    list_checkpoint_drift = dict_semantic_execution.get("checkpoint_drift", []) or []  # 语义检查点漂移列表

    # failed_cases 记录 transcript 中失败的用例。
    failed_cases = dict_semantic_execution.get("failed_cases", []) or []  # 语义执行失败用例

    # 显式布尔 False 表示语义用例或 checkpoint 尚未准备好。
    bool_semantic_failed = isinstance(value_semantic_ready, bool) and not value_semantic_ready  # 语义执行是否明确失败

    # 语义执行未就绪时给出阻断级问题。
    if bool_semantic_failed:

        # 长错误消息独立成变量,避免问题登记行过宽。
        str_message = (  # 语义执行未就绪诊断
            "Semantic execution is not ready; "  # 语义执行失败诊断前半句
            "reference cases or checkpoints are missing or mismatched."  # 缺失或不匹配原因
        )

        # 未就绪说明 testbench 语义闭环需要修复。
        list_issues.append(_issue("error", str_message, source="testbench_issue"))

    # 用例覆盖不一致时记录阻断级问题。
    if mismatched_cases:

        # case coverage 不一致会让 RTL 与 reference 不可比。
        list_issues.append(
            _issue("error", "Semantic case coverage differs from the semantic contract.", source="testbench_issue")
        )

    # checkpoint drift 表示语义观测点不一致。
    if list_checkpoint_drift:

        # checkpoint 漂移需要在 reference 或 RTL transcript 中修复。
        list_issues.append(_issue("error", "Semantic checkpoint drift was detected.", source="testbench_issue"))

    # transcript 中存在失败 case 时记录阻断级问题。
    if failed_cases:

        # failed_cases 表示语义执行已经跑通但用例结果失败。
        str_message = "Semantic transcript contains failed reference cases."  # transcript 失败用例诊断

        # 失败用例来自 testbench 语义执行链路。
        list_issues.append(_issue("error", str_message, source="testbench_issue"))

    # 返回字段保持旧版语义执行摘要形状。
    return {
        "issues": list_issues,
        "semantic_ready": value_semantic_ready,
        "mismatched_cases": mismatched_cases,
        "checkpoint_drift": list_checkpoint_drift,
        "failed_cases": failed_cases,
        "localization_confidence": dict_semantic_execution.get("localization_confidence"),
    }

# issue 构造器统一生成 severity/source/message 三字段诊断。
def _issue(severity: str, message: str, *, source: str = "current_module_issue") -> dict[str, Any]:
    """生成 workflow 报告使用的最小 issue 对象。

    参数:
        severity: 问题严重程度。
        message: 人类可读诊断文本。
        source: 问题来源分类,默认归入当前模块。

    返回:
        包含 severity、source 和 message 的 issue 字典。
    """

    # 返回最小 issue 结构,保持 workflow 报告兼容。
    return {"severity": severity, "source": source, "message": message}
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