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

View on GitHub
"""共享 readable-verilog-generator 的双语 Verilog 文件头字面合同。"""

# 延迟类型注解求值,避免导入阶段提前解析复杂联合类型。
from __future__ import annotations

# copy 只用于返回可修改副本,避免调用方污染全局合同常量。
from copy import deepcopy

# Path 只用于定位 repo 内的 header 合同文本资产。
from pathlib import Path

# HEADER_TIMESCALE_LINE 固定标准 header 的首行 timescale 文本。
HEADER_TIMESCALE_LINE = "`timescale 1ns / 1ps"  # 标准双语 header 的固定 timescale 行

# HEADER_ENGLISH_BANNER 固定英文横幅的逐字符文本。
HEADER_ENGLISH_BANNER = "////////////////////////////////////English///////////////////////////////////////"  # 英文横幅完整文本

# HEADER_CHINESE_BANNER 固定中文横幅的逐字符文本。
HEADER_CHINESE_BANNER = "///////////////////////////////////Chinese////////////////////////////////////////"  # 中文横幅完整文本

# HEADER_ENGLISH_SEPARATOR 供质量门和解析器做横幅锚点匹配。
HEADER_ENGLISH_SEPARATOR = "/" * 36 + "English"  # 英文横幅匹配锚点

# HEADER_CHINESE_SEPARATOR 专门匹配中文横幅,避免和英文锚点说明重复。
HEADER_CHINESE_SEPARATOR = "/" * 35 + "Chinese"  # 中文横幅匹配锚点

# HEADER_PATH_TEMPLATES 固定英中文段的说明文档与仿真工程路径模板。
HEADER_PATH_TEMPLATES = {  # 双语 header 的固定路径模板集合
    "english": {  # 英文段固定路径模板
        "description": "description/{module_name}_Design.pdf",  # 英文段固定说明文档路径模板
        "simulations": "testbench/vivado/2021.1/{module_name}",  # 英文段固定仿真工程路径模板
    },
    "chinese": {  # 中文段固定路径模板
        "description": "Description/{module_name}_Design.pdf",  # 中文段固定说明文档路径模板
        "simulations": "TestBench/Vivado/2021.1/{module_name}",  # 中文段固定仿真工程路径模板
    },
}

# HEADER_LAYOUT 固定双语 header 的字段顺序、前缀、列头和横幅文本。
HEADER_LAYOUT = {  # 双语 header 的共享版式合同
    "english": {  # 英文段固定版式
        "banner": HEADER_ENGLISH_BANNER,  # 英文段横幅完整文本
        "separator": HEADER_ENGLISH_BANNER,  # 英文段横幅匹配时复用的完整分隔文本
        "company_prefix": "// Company:         ",  # 英文段公司字段前缀
        "engineer_prefix": "// Engineer:        ",  # 英文段开发人员字段前缀
        "blank_after_identity": "//",  # 身份字段后的固定注释空行
        "create_date_prefix": "// Create Date:     ",  # 英文段创建日期字段前缀
        "design_name_prefix": "// Design Name:     ",  # 英文段 Design Name 固定前缀
        "module_name_prefix": "// Module Name:     ",  # 英文段模块名称字段前缀
        "description_prefix": "// Description:     ",  # 英文段说明文档字段前缀
        "simulations_prefix": "// Simulations:     ",  # 英文段仿真工程字段前缀
        "blank_before_references": "//",  # 英文段进入 Referrences 前的固定空白注释行
        "references_prefix": "// Referrences:     ",  # 英文段参考资料字段前缀
        "references_line_none": "// Referrences:     None",  # 英文段 none_mode 参考资料整行
        "references_line_table": "// Referrences:",  # 英文段 table_mode 参考资料标题行
        "references_table_header": "File Format      File Name",  # 英文段参考资料表格列头
        "dependencies_prefix": "// Dependencies:    ",  # 英文段依赖字段前缀
        "dependencies_line_none": "// Dependencies:    None",  # 英文段 none_mode 依赖整行
        "dependencies_line_table": "// Dependencies:",  # 英文段 table_mode 依赖标题行
        "dependencies_table_header": "Module Name      Version",  # 英文段依赖表格列头
        "section_blank": "//",  # 英文段内部区块之间的固定空白注释行
        "version_prefix": "// Version:         ",  # 英文段版本字段前缀
        "revision_date_prefix": "// Revision Date:   ",  # 英文段修订日期字段前缀
        "history_title": "// History:",  # 英文段修订历史标题行
        "history_header": "// Time             Version     Revised by        Contents",  # 英文段修订历史表头行
    },
    "chinese": {  # 中文段固定版式
        "banner": HEADER_CHINESE_BANNER,  # 中文段横幅完整文本
        "separator": HEADER_CHINESE_BANNER,  # 中文段横幅匹配时复用完整中文横幅文本
        "company_prefix": "// 版权归属:        ",  # 中文段公司字段前缀
        "engineer_prefix": "// 开发人员:        ",  # 中文段开发人员字段前缀
        "blank_after_identity": "//",  # 中文段身份字段后的固定注释空行
        "create_date_prefix": "// 创建日期:        ",  # 中文段创建日期字段前缀
        "design_name_prefix": "// 设计名称:        ",  # 中文段设计名称字段前缀
        "module_name_prefix": "// 模块名称:        ",  # 中文段模块名称字段前缀
        "description_prefix": "// 模块说明:        ",  # 中文段说明文档字段前缀
        "simulations_prefix": "// 仿真工程:        ",  # 中文段仿真工程字段前缀
        "blank_before_references": "//",  # 中文段进入参考资料前的固定空白注释行
        "references_prefix": "// 参考资料:        ",  # 中文段参考资料字段前缀
        "references_line_none": "// 参考资料:        None",  # 中文段 none_mode 参考资料整行
        "references_line_table": "// 参考资料:",  # 中文段 table_mode 参考资料标题行
        "references_table_header": "文件格式         文件名称",  # 中文段参考资料表格列头
        "dependencies_prefix": "// 依赖文件:        ",  # 中文段依赖字段前缀
        "dependencies_line_none": "// 依赖文件:        None",  # 中文段 none_mode 依赖整行
        "dependencies_line_table": "// 依赖文件:",  # 中文段 table_mode 依赖标题行
        "dependencies_table_header": "模块名称         版本",  # 中文段依赖表格列头
        "section_blank": "//",  # 中文段内部区块之间的固定空白注释行
        "version_prefix": "// 当前版本:        ",  # 中文段版本字段前缀
        "revision_date_prefix": "// 修订日期:        ",  # 中文段修订日期字段前缀
        "history_title": "// 修订历史:",  # 中文段修订历史标题行
        "history_header": "// 时间             版本        修订人            修订内容",  # 中文段修订历史表头行
    },
}

# HEADER_CONTRACT_ASSET_DIR 固定指向 header 合同文本资产目录。
HEADER_CONTRACT_ASSET_DIR = Path(__file__).resolve().parents[2] / "assets" / "style_templates"  # header 合同文本资产目录

# _read_contract_asset_text 统一读取 header 合同文本资产并裁掉尾随换行。
def _read_contract_asset_text(file_name: str) -> str:
    """
    读取指定的 header 合同文本资产,并裁掉尾随换行。

    参数:
        file_name: 需要读取的合同文本资产文件名。
    返回:
        返回裁掉尾随换行后的合同文本。
    """

    # path_asset 指向当前要读取的合同文本资产文件。
    path_asset = HEADER_CONTRACT_ASSET_DIR / file_name  # 当前合同文本资产路径

    # 读取资产文本后裁掉尾随换行,避免 prompt 包装时多出空白行。
    return path_asset.read_text(encoding="utf-8").rstrip("\n")

# HEADER_PROMPT_NONE_MODE_TEXT 直接从文本资产读取 none_mode 合同样例。
HEADER_PROMPT_NONE_MODE_TEXT = _read_contract_asset_text("header_prompt_none_mode.txt")  # none_mode prompt 样例完整文本

# HEADER_PROMPT_TABLE_MODE_TEXT 直接读取带参考资料表格的 table_mode 合同样例。
HEADER_PROMPT_TABLE_MODE_TEXT = _read_contract_asset_text("header_prompt_table_mode.txt")  # table_mode 表格合同样例文本

# header_layout_config 返回共享 layout 的深拷贝,供调用方安全修改。
def header_layout_config() -> dict[str, dict[str, str]]:
    """
    返回可安全修改的双语 header 布局副本。

    参数:
        本函数没有业务参数,固定返回共享常量的深拷贝。
    返回:
        返回英中文段的共享布局副本。
    """

    # 返回深拷贝副本,避免调用方直接污染全局合同常量。
    return deepcopy(HEADER_LAYOUT)

# render_header_template_text 统一替换 header 模板中的模块名占位。
def render_header_template_text(template: str, module_name: str) -> str:
    """
    把 header 模板中的模块名占位替换成目标模块名。

    参数:
        template: 需要执行占位替换的 header 模板文本。
        module_name: 要写入模板的目标模块名。
    返回:
        返回完成占位替换后的模板文本。
    """

    # 先兼容 `$module$` 与 `{module}` 两种旧模板占位写法。
    str_template = str(template).replace("$module$", module_name).replace("{module}", module_name)  # 完成兼容占位预替换后的模板文本

    # 再尝试处理 `{module_name}` 风格的标准 format 占位。
    try:

        # 标准 format 占位统一复用同一个 module 名称。
        return str_template.format(module_name=module_name, module=module_name)

    # 模板若包含其他花括号,则保守回退到预替换结果。
    except (IndexError, KeyError, ValueError):

        # 发生 format 失败时仍返回已完成兼容占位替换的文本。
        return str_template

# default_header_paths 根据模块名生成英中文段的固定路径。
def default_header_paths(module_name: str) -> dict[str, dict[str, str]]:
    """
    返回目标模块在英中文段落中的固定说明文档与仿真工程路径。

    参数:
        module_name: 需要写入固定路径模板的目标模块名。
    返回:
        返回按语言分组的固定路径映射。
    """

    # dict_paths 汇总英中文段最终要写入 header 的固定路径。
    dict_paths: dict[str, dict[str, str]] = {}  # 目标模块的双语固定路径集合

    # 逐个语言展开模板并完成模块名占位替换。
    for str_language, dict_templates in HEADER_PATH_TEMPLATES.items():

        # dict_language_paths 单独累积当前语言段的字段路径。
        dict_language_paths: dict[str, str] = {}  # 当前语言的固定路径映射

        # 逐个字段渲染最终说明文档和仿真工程路径。
        for str_field, str_template in dict_templates.items():

            # 当前字段路径统一复用模板渲染 helper 生成。
            dict_language_paths[str_field] = render_header_template_text(str_template, module_name)  # 当前字段的最终固定路径

        # 当前语言段的固定路径回填到总结果里。
        dict_paths[str_language] = dict_language_paths  # 当前语言段的路径集合

    # 返回目标模块的完整双语固定路径映射。
    return dict_paths

# reference_dependency_blocks 统一构造 none/table 两种合法区块形态。
def reference_dependency_blocks(
    *,
    mode: str,
    reference_rows: tuple[str, ...] | list[str] | None = None,
    dependency_rows: tuple[str, ...] | list[str] | None = None,
) -> dict[str, object]:
    """
    返回双语 header 共享的 Referrences/Dependencies 结构化区块。

    参数:
        mode: 只能是 `none` 或 `table` 的总模板模式名。
        reference_rows: table_mode 下要写入的参考资料数据行集合。
        dependency_rows: table_mode 下要写入的依赖数据行集合。
    返回:
        返回供 formatter、workflow 和测试共用的结构化区块字典。
    异常:
        ValueError: `mode` 不是 `none` 或 `table` 时抛出。
    """

    # 非法 mode 必须立即阻断,避免第三种混合形态静默流入主链。
    if mode not in {"none", "table"}:

        # 非法模式统一抛出带项目前缀的错误消息。
        raise ValueError("> ERR: [Python] Header reference/dependency mode must be `none` or `table`.")

    # 返回结构化区块,供各入口统一消费同一份合法模式描述。
    return {
        "mode": mode,
        "reference_rows": list(reference_rows or []),
        "dependency_rows": list(dependency_rows or []),
    }

# render_bilingual_header 按共享合同渲染完整双语 header 行列表。
def render_bilingual_header(
    *,
    english_values: dict[str, str],
    chinese_values: dict[str, str],
    english_history_lines: list[str] | tuple[str, ...], chinese_history_lines: list[str] | tuple[str, ...],
    reference_dependency_block: dict[str, object],
    include_timescale: bool,
) -> list[str]:
    """
    按共享合同渲染完整双语 header。

    参数:
        english_values: 英文段字段值映射。
        chinese_values: 中文段字段值映射。
        english_history_lines: 英文修订历史正文行集合。
        chinese_history_lines: 中文修订历史正文行集合。
        reference_dependency_block: Referrences/Dependencies 的统一结构化区块。
        include_timescale: 是否在 header 最前面补上固定 timescale 行。
    返回:
        返回可直接 join 成最终 RTL 文本的双语 header 行列表。
    """

    # list_header_lines 顺序累积最终要写回的完整 header 行。
    list_header_lines: list[str] = []  # 双语 header 的最终物理行列表

    # 需要完整 header 时,先补固定 timescale 行和一条空行。
    if include_timescale:

        # timescale 行和后续空行必须与用户样例逐字一致。
        list_header_lines.extend([HEADER_TIMESCALE_LINE, ""])

    # list_english_section 单独承接英文段,便于保持英文在前的固定顺序。
    list_english_section = _render_language_section(  # 英文段完整 header 行列表
        english_values,  # 英文段字段值映射
        english_history_lines,  # 英文段修订历史正文集合
        reference_dependency_block,  # 共享的 references/dependencies 区块
        "english",  # 当前语言键
    )

    # 先把英文段按固定顺序并入总 header。
    list_header_lines.extend(list_english_section)

    # list_chinese_section 单独承接中文段,便于保持中文紧跟英文的固定顺序。
    list_chinese_section = _render_language_section(  # 中文段完整 header 行列表
        chinese_values,  # 中文段字段值映射
        chinese_history_lines,  # 中文段修订历史正文集合
        reference_dependency_block,  # 中文段沿用同一份 references/dependencies 区块
        "chinese",  # 中文段语言键
    )

    # 再把中文段按固定顺序并入总 header。
    list_header_lines.extend(list_chinese_section)

    # 返回完整双语 header 行列表。
    return list_header_lines

# prompt_header_contract_text 返回 prompt 侧逐字注入的两种合法合同样例。
def prompt_header_contract_text() -> str:
    """
    返回 prompt 侧需要逐字注入的两种合法 header 合同样例。

    参数:
        本函数没有业务参数,固定返回 none_mode 与 table_mode 两段样例文本。
    返回:
        返回带 Markdown 代码块包裹的双模式合同样例文本。
    """

    # 返回 prompt 直接拼接使用的两段合法合同示例文本。
    return (
        "None-mode header:\n"
        f"```verilog\n{HEADER_PROMPT_NONE_MODE_TEXT}\n```\n\n"
        "Table-mode header:\n"
        f"```verilog\n{HEADER_PROMPT_TABLE_MODE_TEXT}\n```"
    )

# _render_header_section 渲染单个语言段的固定 header 物理行。
def _render_header_section(
    section_values: dict[str, str],
    history_lines: list[str],
    reference_dependency_block: dict[str, object],
    language_key: str,
) -> list[str]:
    """
    渲染单个语言段的固定 header 合同。

    参数:
        section_values: 当前语言段的字段值映射。
        history_lines: 当前语言段的修订历史正文行集合。
        reference_dependency_block: 当前 header 使用的结构化 references/dependencies 区块。
        language_key: 当前语言键,只允许 `english` 或 `chinese`。
    返回:
        返回单个语言段按固定顺序展开后的物理行列表。
    """

    # dict_layout 读取当前语言段的共享布局副本,避免原地污染全局常量。
    dict_layout = header_layout_config()[language_key]  # 当前语言段的共享布局副本

    # list_history_block 把历史正文统一补成 `// ` 注释行。
    list_history_block = [f"// {str_line}" for str_line in history_lines]  # 当前语言段的历史注释行集合

    # list_section 先写入横幅、身份、路径和固定字段顺序的前半段。
    list_section = [  # 当前语言段的前半段固定字段行列表
        str(dict_layout["banner"]),  # 当前语言段横幅
        f"{dict_layout['company_prefix']}{section_values['copyright_owner']}",  # 当前语言段公司字段
        f"{dict_layout['engineer_prefix']}{section_values['developer']}",  # 当前语言段开发人员字段
        str(dict_layout["blank_after_identity"]),  # 身份字段后的固定空白注释行
        f"{dict_layout['create_date_prefix']}{section_values['create_date']}",  # 当前语言段创建日期字段
        f"{dict_layout['design_name_prefix']}{section_values['design_name']}",  # 当前语言段设计名称字段
        f"{dict_layout['module_name_prefix']}{section_values['module_name']}",  # 当前语言段模块名称字段
        f"{dict_layout['description_prefix']}{section_values['description']}",  # 当前语言段说明文档路径字段
        f"{dict_layout['simulations_prefix']}{section_values['simulations']}",  # 当前语言段仿真工程路径字段
        str(dict_layout["blank_before_references"]),  # References 之前的固定空白注释行
    ]

    # str_mode 收敛当前区块模式,避免 `if` 条件里重复展开取值逻辑。
    str_mode = str(reference_dependency_block.get("mode", "none"))  # 当前 references/dependencies 总模板模式

    # none_mode 只允许单行 None,不得继续夹带表头或自由文本。
    if str_mode == "none":

        # none_mode 直接补入 Referrences 和 Dependencies 的单行占位。
        list_section.extend(
            [
                str(dict_layout["references_line_none"]),
                str(dict_layout["section_blank"]),
                str(dict_layout["dependencies_line_none"]),
            ]
        )

    # table_mode 必须补齐段标题、列头和真实数据行。
    else:

        # table_mode 直接补入列头和真实数据行,保持用户样例的固定顺序。
        list_section.extend(
            [
                str(dict_layout["references_line_table"]),
                f"// {dict_layout['references_table_header']}",
                *[f"// {str_line}" for str_line in reference_dependency_block["reference_rows"]],
                str(dict_layout["section_blank"]),
                str(dict_layout["dependencies_line_table"]),
                f"// {dict_layout['dependencies_table_header']}",
                *[f"// {str_line}" for str_line in reference_dependency_block["dependency_rows"]],
            ]
        )

    # 最后把版本、修订日期和历史表头统一接到语言段尾部。
    list_section.extend(
        [
            str(dict_layout["section_blank"]),
            f"{dict_layout['version_prefix']}{section_values['version']}",
            f"{dict_layout['revision_date_prefix']}{section_values['revision_date']}",
            str(dict_layout["history_title"]),
            str(dict_layout["history_header"]),
            *list_history_block,
        ]
    )

    # 返回单个语言段的完整物理行列表。
    return list_section

# _render_language_section 负责把历史序列先规整成列表,再交给底层语言段渲染 helper。
def _render_language_section(
    section_values: dict[str, str],
    history_lines: list[str] | tuple[str, ...],
    reference_dependency_block: dict[str, object],
    language_key: str,
) -> list[str]:
    """
    把单语言段输入规整后交给 `_render_header_section` 渲染。

    参数:
        section_values: 当前语言段的字段值映射。
        history_lines: 当前语言段的修订历史正文行集合。
        reference_dependency_block: 当前 header 使用的结构化 references/dependencies 区块。
        language_key: 当前语言键,只允许 `english` 或 `chinese`。
    返回:
        返回单个语言段按固定顺序展开后的物理行列表。
    """

    # list_history_lines 把 tuple 或其他序列统一收敛成列表,便于下游遍历和补前缀。
    list_history_lines = list(history_lines)  # 当前语言段的历史正文列表

    # 把规整后的字段和值交给底层 renderer 执行固定合同渲染。
    return _render_header_section(section_values, list_history_lines, reference_dependency_block, language_key)
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