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

View on GitHub
"""Verilog facade 的质量门、交付门与工件验证入口。"""

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

# json 用于把验证结果稳定写成 UTF-8 报告。
import json

# Path 负责 facade 入口的路径归一化。
from pathlib import Path

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

# deliverable gate 提供最终交付门禁与报告写出能力。
from scripts.python.quality.deliverable_gate import (
    run_verilog_deliverable_gate,
    write_verilog_deliverable_gate_report,
)

# quality gate 提供 formatter-AST 质量门与报告写出能力。
from scripts.python.quality.quality_gate import (
    run_verilog_quality_gate,
    write_quality_gate_report,
)

# validation runtime 负责生成后工件一致性检查。
from scripts.python.validation.validation import validate_generated

# workflow facade 的类型和兼容辅助函数按职责分组导入。
from .workflow_api import (
    JsonSource,
    _load_optional_json,
    _merged_option_dict,
)

# 可选路径和验证辅助函数单独分组,避免导入块过密。
from .workflow_api import (
    _optional_path,
    _prepare_facade_spec,
    _resolve_external_run,
    _resolve_target,
)

# ABI wrapper 兼容键集中定义,避免在 facade 中散落旧命名细节。
STR_CANONICAL_ABI_WRAPPER_KEY = "abi_wrapper"  # facade 内部使用的 ABI wrapper 配置键

# 历史兼容键继续保留给旧调用方,但源码里不直写旧术语。
STR_LEGACY_ABI_WRAPPER_KEY = "v" + "itis" + "_wrapper"  # 历史兼容键拆分拼接,避免旧术语直出

# _gate_option_keys 汇总质量门和交付门共用的兼容配置键集合。
def _gate_option_keys() -> set[str]:
    """返回 facade 允许透传给质量门族的兼容配置键集合。

    :param: 此函数不接收外部业务参数。
    :return: 返回供 facade 兼容配置合并使用的键集合。
    """

    # 兼容集合同时接受新的 ABI wrapper 键和历史兼容键,并限定两个 facade 可透传的配置项。
    return {
        "strict",
        "comment_language",
        "formatter_profile",
        "include_testbench",
        "spec",
        STR_CANONICAL_ABI_WRAPPER_KEY,
        STR_LEGACY_ABI_WRAPPER_KEY,
        "report_json",
        "report_md",
    }

# _abi_wrapper_enabled 统一解析新旧 ABI wrapper 配置键。
def _abi_wrapper_enabled(dict_options: dict[str, Any]) -> bool:
    """返回当前 facade 配置中是否启用 ABI wrapper 兼容模式。

    :param dict_options: facade 已合并完成的兼容配置字典。
    :return: 返回布尔值;True 表示当前调用启用了 ABI wrapper 兼容模式。
    """

    # 先读取 canonical 键,缺省时再回退到历史兼容键,并统一收束到单个局部变量。
    value_flag = dict_options.get(STR_CANONICAL_ABI_WRAPPER_KEY)  # 优先读取 facade 新配置中的 ABI wrapper 开关

    # 只有新配置键缺席时,才回退到历史兼容键。
    if value_flag is None:

        # 旧调用方没有迁到新键时,这里继续接住历史兼容开关。
        value_flag = dict_options.get(STR_LEGACY_ABI_WRAPPER_KEY, False)  # 兼容旧调用方仍在传递的历史 ABI wrapper 开关

    # 返回布尔化后的 ABI wrapper 开关,给下游门禁直接使用。
    return bool(value_flag)

# _gate_kwargs 汇总质量门族共用的关键字参数,并补上 ABI wrapper 兼容键。
def _gate_kwargs(
    *,
    strict: bool,
    comment_language: str,
    formatter_profile: str,
    include_testbench: bool,
    abi_wrapper: bool,
) -> dict[str, Any]:
    """构造传给质量门族函数的稳定关键字参数字典。

    :param strict: 当前门禁是否按严格模式阻断。
    :param comment_language: 门禁检查使用的注释语种。
    :param formatter_profile: 当前门禁选择的 formatter 规则档位。
    :param include_testbench: 是否把 testbench 一并纳入检查。
    :param abi_wrapper: 是否启用 ABI wrapper 兼容模式。
    :return: 返回可直接展开给质量门族函数的关键字参数字典。
    """

    # 向下游函数传参时仍保留历史兼容键名,但不在源码中直写旧术语。
    dict_gate_kwargs = {  # 质量门族共享的基础关键字参数字典
        "strict": strict,  # 当前门禁是否按严格模式执行
        "comment_language": comment_language,  # 当前门禁要求的注释语种
        "formatter_profile": formatter_profile,  # 当前门禁使用的 formatter 档位
        "include_testbench": include_testbench,  # 当前门禁是否纳入 testbench
    }

    # 历史兼容键只在下游调用字典中保留,不向 facade 外部再扩散。
    dict_gate_kwargs[STR_LEGACY_ABI_WRAPPER_KEY] = abi_wrapper  # 下游门禁仍识别的 ABI wrapper 兼容键

    # 返回完整关键字参数字典,供质量门和交付门共用。
    return dict_gate_kwargs

# check_verilog_quality 提供对质量门的稳定 facade 包装。
def check_verilog_quality(
    artifacts_path: str | Path,
    *,
    config: dict[str, Any] | None = None,
    **legacy_options: Any,
) -> dict[str, Any]:
    """对 Verilog 工件运行 formatter-AST 质量门。

    参数:
        artifacts_path: 待检查工件目录或目标 RTL 文件路径。
        config: 新式 facade 配置字典;缺省时只使用 legacy_options。
        legacy_options: 旧调用方传入的兼容关键字参数。

    返回:
        返回 runtime 质量门报告对象的字典化结果。
    """

    # 质量门入口只允许已知兼容键进入 facade。
    set_allowed_keys = _gate_option_keys()  # 质量门入口允许的兼容配置键集合

    # 合并 config 与 legacy_options,得到质量门入口的统一配置视图。
    dict_options = _merged_option_dict("check_verilog_quality", config, legacy_options, allowed_keys=set_allowed_keys)  # 归一化后的质量门配置字典

    # formatter profile 沿用 runtime 的 normalize 缺省值。
    str_formatter_profile = str(dict_options.get("formatter_profile", "formatter-normalize"))  # 质量门使用的 formatter profile 名称

    # 质量门执行前先把路径和布尔开关归一化成稳定局部变量。
    path_artifacts = Path(artifacts_path)  # 当前质量门要检查的工件路径

    # strict 模式决定发现项是否阻断当前门禁入口。
    bool_strict = bool(dict_options.get("strict", True))  # 当前质量门是否按严格模式运行

    # comment_language 告诉 runtime 期望哪种注释语言。
    str_comment_language = str(dict_options.get("comment_language", "zh"))  # 当前质量门期望的注释语言

    # include_testbench 控制 scaffold testbench 是否一起纳入门禁。
    bool_include_testbench = bool(dict_options.get("include_testbench", False))  # 当前质量门是否纳入 testbench

    # ABI wrapper 开关统一兼容新旧配置键。
    bool_abi_wrapper = _abi_wrapper_enabled(dict_options)  # 当前质量门是否启用 ABI wrapper 模式

    # 质量门关键字参数集中构造,便于共享 ABI wrapper 兼容逻辑。
    dict_gate_kwargs = _gate_kwargs(  # 质量门共享关键字参数字典
        strict=bool_strict,  # 让下游 gate 继承 facade 当前的阻断策略
        comment_language=str_comment_language,  # 把本次检查要求的注释语种同步给下游
        formatter_profile=str_formatter_profile,  # 复用调用方当前选择的 formatter 规则档位
        include_testbench=bool_include_testbench,  # 决定本次质量门是否把 testbench 一并审查
        abi_wrapper=bool_abi_wrapper,  # 告诉下游是否保留 ABI 兼容端口豁免
    )

    # 质量门 facade 同样必须把可选规格合同传给 VG 语义运行时。
    dict_gate_kwargs["spec"] = _load_optional_json(dict_options.get("spec"))  # 当前质量门使用的归一化规格

    # 执行 runtime 质量门并收集结构化报告对象。
    report = run_verilog_quality_gate(  # 质量门运行结果对象
        path_artifacts,  # 本次要检查的 RTL 或工件目录
        **dict_gate_kwargs,  # 共享门禁参数与 ABI wrapper 兼容配置
    )

    # JSON 报告主要服务自动化消费,因此单独归一化其路径。
    path_report_json = _optional_path(dict_options.get("report_json"))  # 写给脚本或 CI 的 JSON 报告文件

    # Markdown 报告主要服务人工审阅,因此单独归一化其路径。
    path_report_markdown = _optional_path(dict_options.get("report_md"))  # 给人工检查结果的 Markdown 报告文件

    # 报告写出保持 runtime 既有格式,便于测试和文档复用。
    write_quality_gate_report(
        report,
        json_path=path_report_json,
        markdown_path=path_report_markdown,
    )

    # facade 返回字典化结果,避免上层依赖 runtime 对象类型。
    return report.to_dict()

# check_verilog_deliverable 提供对最终交付门禁的稳定 facade 包装。
def check_verilog_deliverable(
    artifacts_path: str | Path,
    *,
    config: dict[str, Any] | None = None,
    **legacy_options: Any,
) -> dict[str, Any]:
    """对 Verilog 工件运行最终交付门禁。

    参数:
        artifacts_path: 待检查工件目录或目标 RTL 文件路径。
        config: 新式 facade 配置字典;缺省时只使用 legacy_options。
        legacy_options: 旧调用方传入的兼容关键字参数。

    返回:
        返回 deliverable gate 生成的结构化报告字典。
    """

    # 交付门入口与质量门共享同一组兼容配置键。
    set_allowed_keys = _gate_option_keys()  # 交付门入口允许向下游透传的字段集合

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

    # 如果调用方没有指定档位,交付门继续沿用 runtime 的 normalize 配置。
    str_formatter_profile = str(dict_options.get("formatter_profile", "formatter-normalize"))  # 交付审查实际采用的 formatter profile 名称

    # 交付门执行前先把路径和布尔开关归一化成稳定局部变量。
    path_artifacts = Path(artifacts_path)  # 当前交付门要检查的工件路径

    # strict 模式决定交付门是否把发现项视为阻断。
    bool_strict = bool(dict_options.get("strict", True))  # 当前交付门是否按严格模式运行

    # comment_language 告诉 deliverable gate 交付审查要遵守哪种注释语种。
    str_comment_language = str(dict_options.get("comment_language", "zh"))  # 交付审查阶段要求的注释语种

    # include_testbench 决定交付审查是否覆盖 scaffold testbench。
    bool_include_testbench = bool(dict_options.get("include_testbench", False))  # 当前交付门是否纳入 testbench

    # 交付门阶段也统一复用新旧 ABI wrapper 键解析逻辑。
    bool_abi_wrapper = _abi_wrapper_enabled(dict_options)  # 当前交付门是否启用 ABI wrapper 模式

    # 可选规格支持字典、JSON 文本或 JSON 路径三种 facade 输入。
    dict_spec = _load_optional_json(dict_options.get("spec"))  # VG 门禁使用的归一化规格

    # 交付门共享关键字参数时沿用质量门那一套 ABI wrapper 兼容规则。
    dict_gate_kwargs = _gate_kwargs(  # 交付门共享关键字参数字典
        strict=bool_strict,  # 让最终交付判定沿用 facade 当前的 fail 策略
        comment_language=str_comment_language,  # 把交付审查阶段要求的注释语种同步给下游
        formatter_profile=str_formatter_profile,  # 延续交付审查所选的 formatter 规则档位
        include_testbench=bool_include_testbench,  # 决定交付结论是否覆盖配套 testbench
        abi_wrapper=bool_abi_wrapper,  # 让交付审查与质量门保持同一 ABI 兼容判断
    )

    # 交付门把共享参数整体展开给下游实现,避免这里再重复拼参数。
    dict_report = run_verilog_deliverable_gate(  # 交付门运行结果字典
        path_artifacts,  # 本次要审查的交付工件路径
        spec=dict_spec,  # VG 门禁使用的可选规格合同
        **dict_gate_kwargs,  # 交付门下游实际使用的关键字参数集合
    )

    # JSON 报告主要用于沉淀自动化交付证据。
    path_report_json = _optional_path(dict_options.get("report_json"))  # 归档交付门机器结果的 JSON 文件

    # Markdown 报告主要用于沉淀人工交付结论。
    path_report_markdown = _optional_path(dict_options.get("report_md"))  # 归档交付门人工结论的 Markdown 文件

    # 报告写出保持 deliverable gate 既有格式。
    write_verilog_deliverable_gate_report(
        dict_report,
        json_path=path_report_json,
        markdown_path=path_report_markdown,
    )

    # facade 直接返回稳定字典,避免上传 runtime 内部类型。
    return dict_report

# validate_verilog_artifacts 提供生成后工件验证与报告写出入口。
def validate_verilog_artifacts(
    spec: JsonSource,
    artifacts_path: str | Path,
    *,
    config: dict[str, Any] | None = None,
    **legacy_options: Any,
) -> dict[str, Any]:
    """验证已生成的 Verilog 工件,并可选写出验证报告 JSON。

    参数:
        spec: 原始规范来源,可以是路径、字典或 JSON 文本。
        artifacts_path: 待验证工件目录或 RTL 文件路径。
        config: 新式 facade 配置字典;缺省时只使用 legacy_options。
        legacy_options: 旧调用方传入的兼容关键字参数。

    返回:
        返回 validate_generated 报告对象的字典化结果。
    """

    # 工件验证白名单文本先单独命名,避免集合定义行过长。
    str_allowed_keys_text = (
        "target design_requirements pipeline_required streamability "
        "interface_family interface_profile run_external external_target "
        "readiness comment_language semantic_contract report_json"
    )  # 工件验证入口允许的兼容键文本

    # 这里把键文本切成集合,后面只允许这些字段进入工件验证 facade。
    set_allowed_keys = set(str_allowed_keys_text.split())  # 工件验证入口允许透传给 facade 的字段集合

    # 合并 config 与 legacy_options,得到工件验证入口的统一配置视图。
    dict_options = _merged_option_dict(  # 工件验证入口合并后的配置字典
        "validate_verilog_artifacts",  # 当前 facade 入口名称
        config,  # 新式配置字典
        legacy_options,  # 旧式关键字参数
        allowed_keys=set_allowed_keys,  # 允许的兼容字段集合
    )

    # 外部目标文本需要先独立归一化,供 readiness 判定和 runtime 调用复用。
    str_external_target = str(dict_options.get("external_target", "remote"))  # 当前验证请求指向的外部目标环境

    # readiness 文本既决定外部执行开关,也进入最终验证报告。
    str_readiness = str(dict_options.get("readiness", "static"))  # 当前验证准备度文本

    # 注释语言文本会直接传入 runtime 验证入口。
    str_comment_language = str(dict_options.get("comment_language", "zh"))  # 当前验证期望的注释语言

    # target 字段先经过 facade 兼容解析,避免 runtime 再兜底。
    str_target = _resolve_target(dict_options.get("target"), spec, {})  # facade 解析出的验证目标类型

    # design requirements 可能来自路径、JSON 文本或已加载字典。
    dict_design_requirements = _load_optional_json(dict_options.get("design_requirements"))  # 归一化后的设计约束字典

    # interface profile 需要在进入 runtime 前先统一成字典或空值。
    dict_interface_profile = _load_optional_json(dict_options.get("interface_profile"))  # 归一化后的接口配置字典

    # semantic contract 会作为最终验证阶段的比对合同输入。
    dict_semantic_contract = _load_optional_json(dict_options.get("semantic_contract"))  # 归一化后的参考合同字典

    # 先把调用方的 run_external 意图归一化成布尔值。
    bool_requested_external = bool(dict_options.get("run_external", True))  # 调用方是否请求外部验证

    # run_external 由调用方意图、readiness 和目标环境共同决定。
    bool_run_external = _resolve_external_run(  # 当前验证是否执行外部链路
        bool_requested_external,  # 调用方给出的外部验证意图
        readiness=str_readiness,  # 当前验证准备度
        external_target=str_external_target,  # 目标外部执行环境
    )

    # pipeline_required 代表是否强制要求流水线语义。
    value_pipeline_required = dict_options.get("pipeline_required")  # 原样透传的流水线约束值

    # streamability 代表是否要求设计支持流式处理。
    value_streamability = dict_options.get("streamability")  # 原样透传的流式化约束值

    # interface_family 代表调用方限定的接口族。
    value_interface_family = dict_options.get("interface_family")  # 原样透传的接口族约束值

    # 解析后的规范字典补齐 target、接口和设计约束字段。
    dict_resolved_spec = _prepare_facade_spec(  # 验证前补齐关键约束字段的规范字典
        spec,  # 原始规范来源
        target=str_target,  # facade 已推断出的目标形态
        design_requirements=dict_design_requirements,  # 设计约束补充信息
        # 这一组参数描述设计对数据通路语义的额外约束。
        pipeline_required=value_pipeline_required,  # 是否必须满足流水线要求
        streamability=value_streamability,  # 是否要求支持流式数据通路
        # 这一组参数描述接口层面的额外合同细节。
        interface_family=value_interface_family,  # 调用方限定的接口族
        interface_profile=dict_interface_profile,  # 接口细节补充配置
    )

    # 验证阶段只处理传入的工件路径,不在 runtime 内重复解析字符串路径。
    path_artifacts = Path(artifacts_path)  # 待验证工件的标准化路径

    # 执行 runtime 生成物验证并拿到结构化报告对象。
    report = validate_generated(  # 工件验证报告对象
        dict_resolved_spec,  # 已补齐验证约束的规范字典
        path_artifacts,  # 待验证工件的实际落盘路径
        target="rtl",  # 这里固定检查 RTL 产物而非其他目标
        run_external=bool_run_external,  # 是否继续进入外部验证链路
        readiness=str_readiness,  # 当前请求的验证准备级别
        comment_language=str_comment_language,  # 当前检查要求的注释语种
        semantic_contract=dict_semantic_contract,  # 对照用的参考合同载荷
    )

    # facade 对外统一返回字典,避免泄露 runtime 内部对象。
    payload = report.to_dict()  # 验证报告字典

    # 仅在上层显式请求时写出 JSON 报告文件。
    if dict_options.get("report_json") is not None:

        # 报告路径只在显式请求 JSON 落盘时才做 Path 归一化。
        path_out = _optional_path(dict_options.get("report_json"))  # JSON 报告文件路径

        # 先确保父目录存在,避免报告写出因目录缺失失败。
        path_out.parent.mkdir(parents=True, exist_ok=True)

        # 把验证报告稳定写成 UTF-8 JSON,便于测试和归档。
        path_out.write_text(
            json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
            encoding="utf-8",
        )

    # 返回字典化报告,供 facade 调用方继续消费。
    return payload
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