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

View on GitHub
"""verify-repair 流程的输入规整、验证规格和日志诊断辅助函数。"""

# 延迟类型求值让 helper 之间可以保持轻量导入。
from __future__ import annotations

# 文件操作和路径类型用于 staging workspace。
import shutil
from pathlib import Path
from typing import Any

# 现有 RTL 分析入口负责加载用户规格文本。
from .existing_rtl import load_spec_text

# spec 名称净化和验证入口保持原有 wire contract。
from scripts.python.workflow.spec import sanitize_name
from scripts.python.validation.validation import READINESS_LEVELS, require_readiness

# 自动化模式定义写回权限边界。
AUTOMATION_MODES = ("conservative", "semi_auto", "auto_apply")  # verify-repair 允许的自动化模式

# testbench 模式定义 generate/augment 两条受控路径。
TB_MODES = ("generate", "augment")  # testbench 处理模式

# testbench 语言限定为 Verilog-2001。
TB_LANGUAGES = ("verilog",)  # testbench 输出语言集合

# automation mode 是越权保护边界,必须在入口处收敛。
def require_automation_mode(str_value: str) -> str:
    """规范化 verify-repair 的自动化模式。

    参数:
        str_value: CLI 或 facade 传入的自动化模式文本。

    返回:
        返回可写入验证计划和策略判断的标准小写模式。

    异常:
        ValueError: 当模式不属于保守、半自动或自动应用集合时抛出。
    """

    # 小写模式值用于兼容 CLI 和 facade 传入的大小写差异。
    str_normalized = str_value.lower()  # 规范化后的自动化模式

    # 未声明模式不能继续进入可能写文件的修复流程。
    if str_normalized not in AUTOMATION_MODES:

        # 明确列出允许值,保持旧错误消息可读。
        raise ValueError(f"> ERR: [Python] automation_mode must be one of {', '.join(AUTOMATION_MODES)}.")

    # 返回稳定模式文本供下游策略判断。
    return str_normalized

# tb_mode 决定 testbench 是生成还是增强既有文件。
def require_tb_mode(str_value: str) -> str:
    """规范化 testbench 处理模式。

    参数:
        str_value: CLI 或 facade 传入的 testbench 处理模式。

    返回:
        返回 `generate` 或 `augment` 的标准小写文本。

    异常:
        ValueError: 当模式不属于受支持的 testbench 处理路径时抛出。
    """

    # 小写模式值匹配内部常量。
    str_normalized = str_value.lower()  # 规范化后的 testbench 模式

    # 只允许受控的生成和增强两条路径。
    if str_normalized not in TB_MODES:

        # 入口错误必须阻断后续文件操作。
        raise ValueError(f"> ERR: [Python] tb_mode must be one of {', '.join(TB_MODES)}.")

    # 返回可直接写入报告的模式文本。
    return str_normalized

# tb_language 控制 Verilog testbench 生成边界。
def require_tb_language(str_value: str) -> str:
    """规范化 testbench 语言选择。

    参数:
        str_value: CLI 或 facade 传入的 testbench 语言文本。

    返回:
        返回验证流程可识别的标准 testbench 语言标签。

    异常:
        ValueError: 当语言不属于 Verilog 支持集合时抛出。
    """

    # 内部语言分支统一使用小写字符串。
    str_normalized = str_value.lower()  # 规范化后的 testbench 语言

    # 只允许本 skill 声明支持的 testbench 语言。
    if str_normalized not in TB_LANGUAGES:

        # 语言越界会影响验证合同,必须提前失败。
        raise ValueError(f"> ERR: [Python] tb_language must be one of {', '.join(TB_LANGUAGES)}.")

    # 返回标准语言标签。
    return str_normalized

# 入口参数规整集中在一个函数里,避免主流程重复校验。
def normalize_verify_options(
    *,
    str_automation_mode: str,
    str_tb_mode: str,
    str_tb_language: str,
    str_readiness: str,
) -> tuple[str, str, str, str]:
    """规范化 verify-repair 的四个策略型入口参数。

    参数:
        str_automation_mode: 控制自动写回权限的模式文本。
        str_tb_mode: 控制 testbench 生成或增强的模式文本。
        str_tb_language: 控制 testbench 后端语言的文本。
        str_readiness: 控制静态、编译或执行阶段的 readiness 文本。

    返回:
        返回自动化模式、testbench 模式、语言和 readiness 的标准化四元组。
    """

    # 自动化模式决定是否允许自动写回 RTL/TB。
    str_checked_automation_mode = require_automation_mode(str_automation_mode)  # 安全后的自动化模式

    # testbench 模式决定 generate/augment 分支。
    str_checked_tb_mode = require_tb_mode(str_tb_mode)  # 安全后的 testbench 模式

    # testbench 语言当前固定生成 `.v` 语义。
    str_checked_tb_language = require_tb_language(str_tb_language)  # 安全后的 testbench 语言

    # readiness 复用 validation 模块的层级规则。
    str_checked_readiness = require_readiness(str_readiness)  # 安全后的 readiness 级别

    # 返回固定顺序供 core 解包。
    return (
        str_checked_automation_mode,
        str_checked_tb_mode,
        str_checked_tb_language,
        str_checked_readiness,
    )

# 用户规格文本可能来自 markdown、JSON 或调用方已组装对象。
def load_optional_spec_text(spec_source: str | Path | dict[str, Any] | None) -> str | None:
    """读取可选规格文本,缺失时保持 None。

    参数:
        spec_source: 用户传入的规格路径、文本、结构化字典或空值。

    返回:
        返回 loader 解析后的规格文本;输入缺失时返回 None。
    """

    # 复用既有 loader,保证 dict/path/string 三种输入兼容。
    str_spec_text = load_spec_text(spec_source)  # 供分析和验证计划使用的规格文本

    # 返回 None 或文本,不在这里做语义解释。
    return str_spec_text

# RTL staging 复制源文件到验证 workspace,避免直接在源目录跑验证。
def stage_sources(list_source_paths: list[Path], path_target_dir: Path) -> list[Path]:
    """复制 RTL 源文件到验证 workspace。

    参数:
        list_source_paths: 待复制的原始 RTL 源文件路径列表。
        path_target_dir: verify-repair workspace 中接收 staged RTL 的目录。

    返回:
        返回复制后供 validation 读取的 workspace 内路径列表。
    """

    # staging 目录必须存在,后续 validation 使用相对路径。
    path_target_dir.mkdir(parents=True, exist_ok=True)

    # 收集复制后的 workspace 路径。
    list_staged_paths: list[Path] = []  # validation workspace 中的 RTL 路径

    # 逐个复制源文件,保留文件名以匹配 include 和报告展示。
    for path_source in list_source_paths:

        # 目标路径只改变目录,不改变文件名。
        path_target = path_target_dir / path_source.name  # 当前源文件的 staging 目标

        # 复制到隔离 workspace。
        shutil.copyfile(path_source, path_target)

        # 记录 validation 后续读取的路径。
        list_staged_paths.append(path_target)

    # 返回所有 staged RTL 文件。
    return list_staged_paths

# 行为规格摘要写入 verification_plan,便于人工复核目标。
def spec_summary(str_spec_text: str | None) -> str:
    """生成外部行为说明的短摘要。

    参数:
        str_spec_text: 用户提供的外部行为说明文本,允许为空。

    返回:
        返回 verification_plan 中展示的单行规格摘要。
    """

    # 缺失规格时给出显式说明,避免空字符串误读为已覆盖。
    if not str_spec_text:

        # 英文文本保持既有报告契约。
        return "No external behavioral note was provided."

    # 压平换行,报告里只保留短摘要。
    str_compact = " ".join(line.strip() for line in str_spec_text.splitlines() if line.strip())  # 单行规格摘要

    # 保持旧摘要长度边界。
    return str_compact[:240]

# 日志 excerpt 只用于报告摘要,不参与真实日志保存。
def excerpt(str_text: str, int_limit: int = 320) -> str:
    """压缩日志文本为报告摘要。

    参数:
        str_text: 原始编译或仿真日志文本。
        int_limit: 摘要允许保留的最大字符数。

    返回:
        返回压平换行后的截断日志摘要。
    """

    # 去掉空行并压成单行,便于 JSON 报告展示。
    str_compact = " ".join(line.strip() for line in str_text.splitlines() if line.strip())  # 单行日志摘要

    # 按旧逻辑截断,避免报告膨胀。
    return str_compact[:int_limit]

# 文件名约定用于从多源输入里自动识别 testbench。
def is_testbench(path_source: Path) -> bool:
    """判断路径是否像 testbench 文件。

    参数:
        path_source: 待识别的源文件路径。

    返回:
        返回文件名是否符合 testbench 命名启发式。
    """

    # stem 小写后匹配常见 TB 命名。
    str_stem = path_source.stem.lower()  # 不含后缀的文件名

    # 保持旧启发式:tb_、_tb 或 testbench。
    return str_stem.endswith("_tb") or str_stem.startswith("tb_") or "testbench" in str_stem

# 多源输入拆成 RTL 源和可选 testbench。
def split_sources(
    list_source_paths: list[Path],
    *,
    path_explicit_testbench: Path | None,
) -> tuple[list[Path], Path | None]:
    """拆分 RTL 源文件和 testbench 源文件。

    参数:
        list_source_paths: 用户传入的所有 RTL/testbench 候选源文件。
        path_explicit_testbench: 用户显式指定的 testbench 路径。

    返回:
        返回 RTL 源文件列表和最终选择的 testbench 路径。
    """

    # 显式 testbench 优先于文件名自动识别。
    if path_explicit_testbench is not None:

        # 显式 TB 场景下,剩余文件逐个确认后进入 RTL 源集合。
        list_rtl_sources: list[Path] = []  # 显式 TB 分离后的 RTL 源

        # 逐个排除用户指定的 testbench。
        for path_source in list_source_paths:

            # 显式 TB 本身不参与 RTL 分析。
            if path_source.resolve() == path_explicit_testbench.resolve():

                # 跳过 testbench 文件。
                continue

            # 保留真实 RTL 源文件。
            list_rtl_sources.append(path_source)

        # 返回调用方指定的 TB。
        return list_rtl_sources, path_explicit_testbench

    # 未显式传入时使用命名启发式寻找第一个 TB。
    path_detected_tb = next((path_source for path_source in list_source_paths if is_testbench(path_source)), None)  # 自动识别的 TB

    # 自动识别 TB 场景下,逐个源文件决定是否保留为 RTL。
    list_rtl_sources = []  # 自动识别 TB 后的 RTL 源

    # 排除自动检测到的 testbench。
    for path_source in list_source_paths:

        # 命中自动 TB 时不加入 RTL 源。
        if path_detected_tb is not None and path_source.resolve() == path_detected_tb.resolve():

            # 跳过自动识别的 testbench。
            continue

        # 保留用于 RTL 分析的源文件。
        list_rtl_sources.append(path_source)

    # 返回拆分结果。
    return list_rtl_sources, path_detected_tb

# verification_plan 是 verify-repair 的核心人读计划工件。
def build_verification_plan(
    dict_analysis: dict[str, Any],
    *,
    str_spec_text: str | None,
    str_tb_mode: str,
    str_tb_language: str,
    str_automation_mode: str,
) -> dict[str, Any]:
    """根据 RTL 分析结果生成验证计划。

    参数:
        dict_analysis: existing RTL 分析阶段产出的模块、端口和验证目标。
        str_spec_text: 用户提供的外部规格说明文本。
        str_tb_mode: 已标准化的 testbench 处理模式。
        str_tb_language: 已标准化的 testbench 语言。
        str_automation_mode: 已标准化的自动化修复模式。

    返回:
        返回可写入 `verification_plan.json` 的兼容旧 schema 字典。
    """

    # focus signals 让诊断报告能指出最值得看波形的端口。
    list_focus_signals: list[str] = []  # 验证计划关注信号

    # 按分析顺序保留信号,重复信号只出现一次。
    for dict_mapping in dict_analysis.get("feature_mappings", []):

        # 每个 mapping 可能有多个 pin assignment。
        for dict_assignment in dict_mapping.get("pin_assignments", []):

            # pin_name 为空时跳过。
            str_signal = str(dict_assignment.get("pin_name") or "")  # 当前候选关注信号

            # 保留首次出现的有效信号。
            if str_signal and str_signal not in list_focus_signals:

                # 追加供报告和波形诊断使用的信号名。
                list_focus_signals.append(str_signal)

    # 返回保持旧 schema 的 verification plan。
    return {
        "version": 1,
        "top_module": dict_analysis["module_info"]["name"],
        "tb_mode": str_tb_mode,
        "tb_language": str_tb_language,
        "automation_mode": str_automation_mode,
        "focus_signals": list_focus_signals,
        "verification_targets": dict_analysis.get("verification_targets", []),
        "user_focus_summary": spec_summary(str_spec_text),
    }

# validation spec 把 existing RTL workspace 伪装成生成结果供统一 validator 复用。
def validation_spec(
    dict_analysis: dict[str, Any],
    list_staged_sources: list[Path],
    str_testbench_rel_path: str,
) -> dict[str, Any]:
    """构造 validate_generated 可消费的规格对象。

    参数:
        dict_analysis: existing RTL 分析阶段产出的模块、端口和验证目标。
        list_staged_sources: 已复制到 workspace 的 RTL 源文件路径。
        str_testbench_rel_path: validation spec 中记录的 testbench 相对路径。

    返回:
        返回 `validate_generated` 可消费的生成结果兼容规格字典。
    """

    # outputs 先放 RTL 源文件,再补 testbench。
    list_outputs: list[dict[str, str]] = []  # validation spec 的输出文件列表

    # staged source 用 workspace 相对路径描述。
    for path_source in list_staged_sources:

        # 每个 RTL 文件保持 Verilog 源文件类型。
        list_outputs.append(
            {
                "path": f"rtl/{path_source.name}",
                "kind": "source",
                "language": "verilog",
            }
        )

    # testbench 作为验证入口交给 validator。
    list_outputs.append(
        {
            "path": str_testbench_rel_path,
            "kind": "testbench",
            "language": "verilog",
        }
    )

    # semantic checkpoints 逐项投影,保留分析阶段推断的 check_id。
    list_semantic_checkpoints: list[dict[str, Any]] = []  # validation 用于语义比较的 checkpoint 列表

    # 将每个 verification target 转成 validator 所需字段。
    for int_index, dict_item in enumerate(dict_analysis.get("verification_targets", [])):

        # 单个 checkpoint payload 保持 validator 字段名。
        dict_checkpoint = {
            "id": dict_item.get("check_id", f"checkpoint_{int_index + 1}"),  # validator 语义点稳定标识
            "category": dict_item.get("category", "behavior"),  # validator 语义点归类
            "signals": dict_item.get("signals", []),  # 参与语义比对的信号集合
            "verification_hint": dict_item.get("description", ""),  # 修复判断面向人的提示文本
            "text": dict_item.get("description", ""),  # 语义比对复用的目标描述
        }  # 单个语义 checkpoint payload

        # 追加到 validation spec 的 checkpoint 列表。
        list_semantic_checkpoints.append(dict_checkpoint)

    # 返回统一 validator 的输入结构。
    return {
        "name": sanitize_name(str(dict_analysis["module_info"]["name"])),
        "target": "rtl",
        "rtl_dialect": "verilog",
        "description": "Existing RTL verify-repair staged validation workspace.",
        "interfaces": {"ports": dict_analysis.get("ports", [])},
        "behavior": [
            dict_item.get("description", dict_item.get("name", ""))
            for dict_item in dict_analysis.get("verification_targets", [])
        ],
        "clock": {
            "name": next(
                (dict_item["name"] for dict_item in dict_analysis.get("ports", []) if dict_item.get("role") == "clock"),
                "clk",
            )
        },
        "reset": {
            "name": next(
                (dict_item["name"] for dict_item in dict_analysis.get("ports", []) if dict_item.get("role") == "reset"),
                "rst_n",
            )
        },
        "constraints": ["Preserve existing RTL behavior while validating staged testbench coverage."],
        "outputs": list_outputs,
        "semantic_checkpoints": list_semantic_checkpoints,
    }

# validation report 的 issue 列表转成诊断日志输入。
def diagnostic_inputs(
    obj_validation_report: Any,
    *,
    str_readiness: str,
    bool_run_external: bool,
) -> tuple[str, str, bool]:
    """从 validation report 提取编译日志、仿真日志和执行状态。

    参数:
        obj_validation_report: validator 返回的报告对象,需提供 issues 和 ok()。
        str_readiness: 当前 verify-repair 允许推进到的验证阶段。
        bool_run_external: 是否允许执行外部编译或仿真。

    返回:
        返回编译日志文本、仿真日志文本和外部仿真是否执行的布尔值。
    """

    # compile stage issue 组成编译日志。
    list_compile_lines: list[str] = []  # validator 记录的编译阶段问题

    # 逐条提取 compile issue,保持 issue.format() 的旧格式。
    for obj_issue in obj_validation_report.issues:

        # 只收集 compile 阶段问题。
        if obj_issue.stage == "compile":

            # 编译问题保留验证器标准人读文本。
            list_compile_lines.append(obj_issue.format())

    # execute stage issue 组成仿真日志。
    list_simulation_lines: list[str] = []  # validator 记录的仿真阶段问题

    # 逐条提取 execute issue,避免把 compile 诊断混进仿真日志。
    for obj_issue in obj_validation_report.issues:

        # 仿真阶段问题单独汇入 simulation transcript。
        if obj_issue.stage == "execute":

            # format() 保留验证报告中的 stage/code/message。
            list_simulation_lines.append(obj_issue.format())

    # 只有外部验证被允许时才解析 readiness,保持旧短路异常语义。
    if bool_run_external:

        # 当前 readiness 在固定阶段表中的位置。
        int_readiness_index = READINESS_LEVELS.index(str_readiness)  # 当前验证准备阶段序号

        # execute 是允许写入仿真执行 transcript 的最低阶段。
        int_execute_index = READINESS_LEVELS.index("execute")  # execute 阶段序号

        # readiness 达到 execute 及以上才视为外部执行发生。
        bool_readiness_allows_execute = int_readiness_index >= int_execute_index  # readiness 是否允许执行

    # 未请求外部验证时不能把 validator 状态记为仿真执行。
    else:

        # 禁止外部执行路径生成 PASS transcript。
        bool_readiness_allows_execute = False  # 未运行外部验证时的执行状态

    # execute readiness 及以上才允许把外部仿真状态记为已执行。
    bool_executed = bool_run_external and bool_readiness_allows_execute  # 外部仿真是否真实完成执行阶段

    # 执行且 validator 通过时补充标准 PASS transcript。
    if bool_executed and obj_validation_report.ok():

        # 保持旧测试依赖的完成标签。
        list_simulation_lines.append(" > INFO: [Verilog] [TB_INFO] Simulation Finished!")

        # 保持机器可读 PASS 结果。
        list_simulation_lines.append('VERILOG-GEN-RESULT {"case_id":"nominal","status":"PASS","outputs":{}}')

    # 返回三元组供诊断分类。
    return "\n".join(list_compile_lines), "\n".join(list_simulation_lines), bool_executed

# 日志文本规则集中到私有 helper,主诊断函数只负责组装报告。
def _classify_log_outcome(
    *,
    str_compile_lower: str,
    str_simulation_lower: str,
    bool_executed: bool,
) -> str:
    """按旧优先级分类编译和仿真日志。

    参数:
        str_compile_lower: 已转成小写的编译日志。
        str_simulation_lower: 已转成小写的仿真日志。
        bool_executed: 外部仿真是否真实执行。

    返回:
        返回 verify-repair 诊断报告使用的 outcome 文本。
    """

    # 未执行外部仿真时不能推断真实 pass/fail。
    if not bool_executed:

        # 静态验证不提供真实仿真日志,因此只标记未运行。
        return "not_run"

    # 编译错误优先级最高。
    if any(token in str_compile_lower for token in ("syntax error", "** error", "fatal", "compile error")):

        # 编译失败优先提示修复语法或文件组织。
        return "compile_error"

    # testbench 错误标签代表 assertion 或显式检查失败。
    if "[tb_error]" in str_simulation_lower:

        # TB_ERROR 表示 testbench 检查明确失败。
        return "assertion_fail"

    # protocol violation 是协议/握手类诊断。
    if "protocol violation" in str_simulation_lower:

        # 协议违例需要优先查看握手或时序关系。
        return "protocol_violation"

    # timeout 文本代表活性或收敛问题。
    if "timeout" in str_simulation_lower:

        # timeout 暗示仿真活性或结束条件异常。
        return "timeout"

    # 标准完成标签和机器 PASS 同时出现才算 pass。
    if "[tb_info] simulation finished!" in str_simulation_lower and '"status":"pass"' in str_simulation_lower.replace(
        " ",
        "",
    ):

        # PASS 必须同时有完成标记和机器结果。
        return "pass"

    # unknown 保守交给人工复核,不触发自动补丁。
    return "unknown"

# 日志诊断是 verify-repair 的轻量分类器。
def diagnose_log_texts(*, compile_log: str, simulation_log: str, executed: bool) -> dict[str, Any]:
    """根据编译和仿真日志分类 verify-repair 结果。

    参数:
        compile_log: validator 或外部工具提供的编译日志文本。
        simulation_log: validator 或外部工具提供的仿真日志文本。
        executed: 外部仿真是否真实执行。

    返回:
        返回包含 outcome、日志摘要和 finding 的诊断报告字典。
    """

    # 小写日志用于大小写无关的模式匹配。
    str_compile_lower = compile_log.lower()  # 编译日志小写视图

    # 仿真日志同样转为小写视图。
    str_simulation_lower = simulation_log.lower()  # 仿真日志小写视图

    # 复用私有 helper 保持分类优先级集中。
    str_outcome = _classify_log_outcome(  # 日志分类 outcome
        str_compile_lower=str_compile_lower,  # 分类用编译日志
        str_simulation_lower=str_simulation_lower,  # 分类用仿真日志
        bool_executed=executed,  # 外部执行状态
    )

    # 诊断 finding 由 outcome 映射成人读说明。
    list_findings = _finding_for_outcome(str_outcome)  # 报告使用的诊断说明

    # 返回旧 schema 兼容的诊断 payload。
    return {
        "version": 1,
        "executed": executed,
        "outcome": str_outcome,
        "compile_log_excerpt": excerpt(compile_log),
        "simulation_log_excerpt": excerpt(simulation_log),
        "findings": list_findings,
    }

# outcome 文本映射为中文 finding,报告层不重复写分支。
def _finding_for_outcome(str_outcome: str) -> list[str]:
    """返回日志分类对应的人读诊断说明。

    参数:
        str_outcome: `_classify_log_outcome` 产出的诊断分类文本。

    返回:
        返回 verify-repair 报告中展示的人读 finding 列表。
    """

    # 编译错误需要先修正语法或文件组织。
    if str_outcome == "compile_error":

        # 返回单条 finding 保持旧 payload shape。
        return ["编译阶段发现错误,需要先修复语法或文件组织问题。"]

    # assertion 失败通常来自 TB 检查或显式错误。
    if str_outcome == "assertion_fail":

        # 返回仿真错误说明。
        return ["仿真期间出现断言或显式 TB 错误。"]

    # 协议违例要提示握手或时序关系。
    if str_outcome == "protocol_violation":

        # 返回协议违例说明。
        return ["日志显示握手或协议行为违例。"]

    # timeout 表示仿真没有收敛。
    if str_outcome == "timeout":

        # 返回超时说明。
        return ["仿真未按预期收敛,出现超时。"]

    # pass 只在机器结果和完成标签都存在时出现。
    if str_outcome == "pass":

        # 返回成功说明。
        return ["日志显示仿真收敛并给出 PASS 结果。"]

    # not_run 是静态验证路径。
    if str_outcome == "not_run":

        # 返回未执行外部仿真的说明。
        return ["当前流程未执行外部仿真,仅完成静态验证和工件生成。"]

    # unknown 交给人工复核。
    return ["日志未能归类到已知模式,需要人工复核。"]
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