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

View on GitHub
"""Verilog facade 的 workflow、prompt 与规格辅助逻辑。"""

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

# json 用于读取和落盘 workflow 相关的结构化文件。
import json

# deepcopy 用于保护调用方传入的内存态 spec 字典。
from copy import deepcopy

# Path 负责统一 spec、run_dir 与工件路径。
from pathlib import Path

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

# settings runtime 负责读取默认 workflow 配置。
from scripts.python.workflow.config import load_settings, workflow_defaults

# prompt runtime 负责渲染最终 Verilog 生成提示词。
from scripts.python.workflow.prompt import render_prompt

# requirements runtime 负责补齐 RTL 规格中的需求确认与 codegen 计划。
from scripts.python.workflow.requirements import (
    RequirementConfirmation,
    apply_requirement_defaults,
    build_codegen_plan,
    build_requirements_payload,
    validate_requirement_confirmation,
)

# spec runtime 负责规范化与读写 workflow 使用的 spec 文件。
from scripts.python.workflow.spec import normalize_spec, read_spec, write_spec

# validation runtime 提供 readiness 档位比较能力。
from scripts.python.validation.validation import readiness_at_least

# workflow runtime 负责 staged workflow 的实际运行。
from scripts.python.workflow.workflow import run_workflow

# workspace runtime 负责把相对路径绑定到指定 run_dir。
from scripts.python.workflow.workspace import use_workspace_root

# JsonSource 表示 facade 接受的 JSON 风格输入来源。
JsonSource = str | Path | dict[str, Any]  # spec、evidence、decision 等 JSON 风格输入来源

# PathCollectionSource 表示 facade 接受的单路径或多路径集合来源。
PathCollectionSource = str | Path | list[str | Path]  # host-facing facade 暴露的路径集合输入类型

# workflow runtime 结果需要固定字段顺序,便于测试与报告做稳定对比。
WORKFLOW_RUNTIME_OPTION_KEYS = tuple(  # workflow runtime 参数的稳定字段顺序
    "target readiness max_attempts stop_on_human run_external "
    "comment_language provider_name model_timeout_s generation_mode stream".split()
)

# load_default_workflow_config 提供默认 workflow 配置读取入口。
def load_default_workflow_config() -> dict[str, Any]:
    """读取随包默认 workflow 配置。

    参数:
        无额外业务参数;函数直接读取 runtime settings。

    返回:
        返回 workflow 默认配置的字典副本。
    """

    # 直接返回 runtime 提供的 workflow 默认配置字典。
    return workflow_defaults(load_settings())

# load_workflow_result 负责读取已有 run 目录里的 workflow_result.json。
def load_workflow_result(run_dir: str | Path) -> dict[str, Any]:
    """读取已有 workflow 运行目录中的 workflow_result.json。

    参数:
        run_dir: 已有 workflow 运行目录路径。

    返回:
        返回 workflow_result.json 的字典化内容。
    """

    # workflow_result.json 路径在这里基于 run_dir 一次性展开。
    path_result = Path(run_dir) / "workflow_result.json"  # 当前 run_dir 对应的 workflow_result.json 路径

    # 返回 workflow_result.json 的字典化内容。
    return json.loads(path_result.read_text(encoding="utf-8"))

# _option_value 按显式参数、默认配置和兜底值顺序解析单项配置。
def _option_value(
    dict_options: dict[str, Any],
    str_option_key: str,
    dict_defaults: dict[str, Any],
    default_value: Any,
) -> Any:
    """按显式参数、默认配置和兜底值顺序解析单项配置。

    参数:
        dict_options: 调用方已经归一化好的配置字典。
        str_option_key: 当前要解析的配置键名。
        dict_defaults: runtime 提供的默认配置字典。
        default_value: 当显式参数和默认配置都缺失时使用的兜底值。

    返回:
        返回当前配置键最终应该采用的值。
    """

    # 显式传入的非空值优先级最高,直接覆盖默认配置。
    if dict_options.get(str_option_key) is not None:

        # 返回调用方显式提供的配置值。
        return dict_options[str_option_key]

    # 返回默认配置或硬编码兜底值。
    return dict_defaults.get(str_option_key, default_value)

# _optional_path 把可选路径输入统一转换成 Path 或 None。
def _optional_path(value: str | Path | None) -> Path | None:
    """把可选路径输入统一转换成 Path 或 None。

    参数:
        value: 可能为空的路径输入。

    返回:
        如果 value 为空则返回 None,否则返回对应的 Path 对象。
    """

    # 空值要保留为 None,避免误造出当前目录 Path。
    if value is None:

        # 返回空值语义,供上层判断是否省略该路径参数。
        return None

    # 返回标准化后的 Path 对象。
    return Path(value)

# _merged_option_dict 合并新式 config 与旧式兼容关键字参数。
def _merged_option_dict(
    option_name: str,
    config: Any | None,
    dict_legacy_options: dict[str, Any],
    *,
    allowed_keys: set[str],
) -> dict[str, Any]:
    """合并新式 config 与旧式兼容关键字参数,并拒绝未知字段。

    参数:
        option_name: 当前 facade 入口名称,用于错误信息展示。
        config: 新式配置对象,可以为 None、字典或具备属性的对象。
        dict_legacy_options: 旧式关键字参数字典。
        allowed_keys: 当前入口允许透传的字段集合。

    返回:
        返回合并后的统一配置字典。

    异常:
        TypeError: 当 legacy_options 中出现不被允许的字段时抛出。
    """

    # 缺省 config 需要先归一化为空字典,便于后续 update。
    if config is None:

        # 空配置输入在这里落成新的可变字典。
        dict_options: dict[str, Any] = {}  # 当前入口合并后的统一配置字典

    # 字典配置可以直接复制,避免原对象被下游修改。
    elif isinstance(config, dict):

        # 复制字典配置,保护调用方传入对象不被原地修改。
        dict_options = config.copy()  # 从字典 config 复制出的统一配置字典

    # 其余对象配置通过 vars() 提取属性字典。
    else:

        # 把对象属性复制成新字典,兼容 argparse namespace 等输入。
        dict_options = vars(config).copy()  # 从对象 config 复制出的统一配置字典

    # 未知 legacy key 会在这里统一收集,便于一次性报错。
    set_unknown_keys = set(dict_legacy_options) - allowed_keys  # 当前入口不允许透传的 legacy 字段集合

    # 只要存在未知字段,就不能继续进入 facade 主流程。
    if set_unknown_keys:

        # 未知字段文本会直接写进错误信息,帮助调用方修正入参。
        str_unknown_keys = ", ".join(sorted(set_unknown_keys))  # 当前入口收到的未知字段文本

        # 直接抛出兼容关键字参数错误,阻止未知字段继续下传。
        raise TypeError(
            "> ERR: [Python] Unexpected keyword arguments: "
            f"{option_name} -> {str_unknown_keys}.",
        )

    # 旧式关键字参数在这里覆盖到统一配置视图上。
    dict_options.update(dict_legacy_options)

    # 返回合并后的统一配置字典。
    return dict_options

# _load_raw_spec 读取原始 spec,并保护调用方传入的内存态字典。
def _load_raw_spec(spec: JsonSource) -> dict[str, Any]:
    """读取原始 spec,并保护调用方传入的内存态字典。

    参数:
        spec: 路径形式或字典形式的原始规格输入。

    返回:
        返回可安全修改的原始 spec 字典副本。
    """

    # 内存态字典在这里深拷贝,避免默认值补齐影响调用方对象。
    if isinstance(spec, dict):

        # 返回与调用方对象解耦的 spec 深拷贝。
        return deepcopy(spec)

    # 路径形式的 spec 在这里统一转成 Path。
    path_spec = Path(spec)  # 当前原始 spec 文件路径

    # 返回从 spec 文件读取并解析得到的字典。
    return json.loads(path_spec.read_text(encoding="utf-8"))

# _load_optional_json 把可选 JSON 输入统一读取成字典。
def _load_optional_json(value: str | Path | dict[str, Any] | None) -> dict[str, Any] | None:
    """把可选 JSON 输入统一读取成字典,同时保留空值语义。

    参数:
        value: 可选 JSON 输入,可以是 None、路径或已加载字典。

    返回:
        如果 value 为空则返回 None,否则返回字典化内容。
    """

    # 空值要保留为 None,供上层明确判断该输入是否缺席。
    if value is None:

        # 返回空值语义,避免误造空字典掩盖缺席状态。
        return None

    # 已经是字典的输入直接复用,不额外落盘或读取文件。
    if isinstance(value, dict):

        # 返回原始字典对象,保持调用方已经准备好的结构。
        return value

    # 路径形式的 JSON 输入在这里统一转成 Path。
    path_value = Path(value)  # 当前可选 JSON 文件路径

    # 最后从 JSON 文件中读取并返回字典化内容。
    return json.loads(path_value.read_text(encoding="utf-8"))

# _resolve_target 把目标类型收敛到 facade 支持的唯一 rtl。
def _resolve_target(
    target: str | None,
    spec: JsonSource | None,
    dict_config: dict[str, Any],
) -> str:
    """把目标类型收敛到 facade 支持的唯一 rtl。

    参数:
        target: 调用方显式提供的 target 值。
        spec: 可选 spec 输入,用于回看 spec 自带的 target 字段。
        dict_config: workflow 默认配置或合并后的配置字典。

    返回:
        返回 facade 允许的唯一目标值 rtl。

    异常:
        ValueError: 当最终解析出的 target 不是 rtl 时抛出。
    """

    # raw target 缺省为空,只有 spec 存在时才继续回看 spec 字段。
    raw_target: Any | None = None  # 从 spec 中回看的原始 target 值

    # spec 存在时要先读取其原始 target 字段,参与目标解析。
    if spec is not None:

        # 从原始 spec 中回看 target 字段,保持旧入口兼容行为。
        raw_target = _load_raw_spec(spec).get("target")  # spec 自带的原始 target 值

    # target 解析顺序保持显式参数、spec、默认配置、最终兜底值不变。
    str_resolved_target = str(target or raw_target or dict_config.get("target") or "rtl").lower()  # facade 解析出的最终目标值

    # 当前 facade 只允许 rtl 目标继续进入主流程。
    if str_resolved_target != "rtl":

        # 直接阻止非 rtl 目标进入 facade 主路径。
        raise ValueError("> ERR: [Python] Only target 'rtl' is supported.")

    # 返回 facade 唯一允许的目标值。
    return "rtl"

# _workflow_overrides 兼容 workflow 配置嵌套在 workflow 字段下的旧结构。
def _workflow_overrides(dict_value: dict[str, Any]) -> dict[str, Any]:
    """兼容 workflow 配置嵌套在 workflow 字段下的旧结构。

    参数:
        dict_value: 已经字典化的 workflow 配置输入。

    返回:
        如果检测到嵌套 workflow 字典则返回该子字典,否则返回原字典。
    """

    # 嵌套 workflow 字段在这里单独提取,兼容旧配置形状。
    dict_nested_workflow = dict_value.get("workflow")  # 旧配置中嵌套的 workflow 字段

    # 旧结构存在嵌套 workflow 字典时,优先返回该子字典。
    if isinstance(dict_nested_workflow, dict):

        # 返回嵌套 workflow 子字典,保持旧配置兼容行为。
        return dict_nested_workflow

    # 否则直接返回原配置字典。
    return dict_value

# _write_json_object 把字典稳定写成 UTF-8 JSON 文件并返回路径。
def _write_json_object(path_output: Path, dict_payload: dict[str, Any]) -> Path:
    """把字典稳定写成 UTF-8 JSON 文件并返回路径。

    参数:
        path_output: 目标 JSON 文件路径。
        dict_payload: 待落盘的结构化字典。

    返回:
        返回已经写出的 JSON 文件路径。
    """

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

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

    # 返回已经写出的 JSON 文件路径。
    return path_output

# _materialize_optional_json 把可选 JSON 输入统一收敛成 runtime 可读取的路径。
def _materialize_optional_json(
    value: str | Path | dict[str, Any] | None,
    path_output: Path,
) -> Path | None:
    """把可选 JSON 输入统一收敛成 runtime 可读取的路径。

    参数:
        value: 可选 JSON 输入,可以是 None、路径或已加载字典。
        path_output: 当 value 是字典时用于承接落盘结果的目标路径。

    返回:
        如果 value 为空则返回 None,否则返回 runtime 可读取的路径。
    """

    # 空值要保留为 None,避免生成伪造的空文件路径。
    if value is None:

        # 返回空值语义,表示当前 JSON 输入没有提供。
        return None

    # 已经是路径的输入直接转成 Path,避免重复落盘。
    if isinstance(value, (str, Path)):

        # 返回 runtime 可直接读取的现有路径。
        return Path(value)

    # 字典输入需要先准备父目录,再落盘成 JSON 文件。
    path_output.parent.mkdir(parents=True, exist_ok=True)

    # 把内存态 JSON 字典稳定写成 runtime 可读取的文件。
    path_output.write_text(
        json.dumps(value, indent=2, ensure_ascii=False) + "\n",
        encoding="utf-8",
    )

    # 返回内存态 JSON 字典落盘后的目标路径。
    return path_output

# _prepare_facade_spec 准备 workflow 与 prompt 共用的标准化 RTL 规格。
def _prepare_facade_spec(
    spec: JsonSource,
    *,
    target: str | None,
    design_requirements: dict[str, Any] | None, pipeline_required: bool | None,
    streamability: str | None, interface_family: str | None,
    interface_profile: dict[str, Any] | None,
) -> dict[str, Any]:
    """准备 workflow 与 prompt 共用的标准化 RTL 规格。

    参数:
        spec: 原始 spec 输入,可以是路径或内存态字典。
        target: 调用方显式提供的目标类型。
        design_requirements: 可选设计约束字典。
        pipeline_required: 可选流水线约束。
        streamability: 可选流式化约束。
        interface_family: 可选接口族约束。
        interface_profile: 可选接口细节约束字典。

    返回:
        返回补齐默认值并通过验证的标准化 RTL 规格字典。

    异常:
        ValueError: 当 rtl_dialect 不是 Verilog-2001 兼容值时抛出。
    """

    # 先复制原始 spec,避免默认值补齐回写到调用方对象。
    dict_raw_spec = _load_raw_spec(spec)  # 当前调用使用的原始 spec 副本

    # facade 入口先把 target 收敛到唯一允许的 rtl。
    _resolve_target(target, dict_raw_spec, {})

    # dialect 不兼容时要尽早阻断,避免错误规格继续下传。
    if dict_raw_spec.get("rtl_dialect") not in (None, "", "verilog"):

        # 这里只接受 Verilog-2001 兼容的方言标识。
        raise ValueError("> ERR: [Python] Only Verilog-2001 is supported.")

    # 统一写回 facade 固定支持的 target。
    dict_raw_spec["target"] = "rtl"  # facade 固定支持的目标类型

    # 同时锁定 runtime 侧消费的 RTL 方言。
    dict_raw_spec["rtl_dialect"] = "verilog"  # facade 固定支持的 RTL 方言

    # 只要显式给出任一需求覆盖,就视为用户已经确认方向。
    tuple_confirmation_overrides = (  # 用来判断用户是否显式给出过确认信号的覆盖项
        design_requirements,  # 当前调用显式给出的设计约束覆盖
        pipeline_required,  # 当前调用显式给出的流水线约束覆盖
        streamability,  # 当前调用显式给出的流式化约束覆盖
        interface_family,  # 当前调用显式给出的接口族约束覆盖
        interface_profile,  # 当前调用显式给出的接口细节约束覆盖
    )

    # 任一覆盖项非空时,都视为用户已经确认需求方向。
    bool_user_confirmed = any(item is not None for item in tuple_confirmation_overrides)  # 当前调用是否收到显式需求确认信号

    # 把确认状态单独组装给 defaults 层复用。
    requirement_confirmation_state = RequirementConfirmation(confirmed_by_user=True if bool_user_confirmed else None)  # apply_requirement_defaults 需要的确认状态

    # 这里补齐需求确认、接口约束和设计约束默认值。
    dict_enriched_spec = apply_requirement_defaults(  # 补齐需求确认、接口与设计约束默认值
        dict_raw_spec,  # 作为 defaults 输入的基础 spec
        design_requirements=design_requirements,  # 透传显式设计约束
        pipeline_required=pipeline_required,  # 透传显式流水线约束
        streamability=streamability,  # 透传显式流式化约束
        interface_family=interface_family,  # 透传显式接口族约束
        interface_profile=interface_profile, confirmation=requirement_confirmation_state,  # 透传接口细节约束和确认状态
    )

    # defaults 处理后的 spec 还要再收敛成 runtime 约定形状。
    dict_normalized_spec = normalize_spec(dict_enriched_spec, target="rtl")  # 当前调用可直接交给 runtime 的规范化 spec

    # 最后执行需求确认校验,确保约束载荷完整。
    validate_requirement_confirmation(dict_normalized_spec)

    # 返回补齐默认值并通过校验的标准化 RTL spec。
    return dict_normalized_spec

# _materialize_spec 把路径或字典形式的 spec 物化成 workflow 可读取的文件。
def _materialize_spec(
    spec: JsonSource,
    path_output: Path,
    *,
    target: str | None,
) -> Path:
    """把路径或字典形式的 spec 物化成 workflow 可读取的文件。

    参数:
        spec: 路径形式或字典形式的 spec 输入。
        path_output: 规范化 spec 的目标落盘路径。
        target: 当前调用已经解析出的目标类型。

    返回:
        返回落盘后的 spec 文件路径。
    """

    # 路径形式的 spec 在这里交给 runtime 读并规范化。
    if isinstance(spec, (str, Path)):

        # 从现有 spec 文件读取并规范化得到 runtime 可消费的字典。
        dict_normalized_spec = read_spec(Path(spec), target=target)  # 从文件读取并规范化后的 spec 字典

    # 内存态 spec 在这里直接进入 normalize_spec。
    else:

        # 从内存态字典规范化得到 runtime 可消费的 spec 字典。
        dict_normalized_spec = normalize_spec(spec, target=target)  # 从字典规范化后的 spec 字典

    # spec 输出父目录在写文件前必须存在。
    path_output.parent.mkdir(parents=True, exist_ok=True)

    # 把规范化 spec 稳定写成 workflow 后续阶段可读取的文件。
    write_spec(path_output, dict_normalized_spec)

    # 返回规范化 spec 的落盘路径。
    return path_output

# _resolve_external_run 根据 readiness 与目标策略裁决是否执行外部验证。
def _resolve_external_run(
    run_external: bool,
    *,
    readiness: str,
    external_target: str,
    allow_static_external: bool = False,
) -> bool:
    """根据 readiness 与目标策略裁决是否执行外部验证。

    参数:
        run_external: 调用方是否请求外部验证。
        readiness: 当前验证准备度文本。
        external_target: 调用方请求的外部目标环境标识。
        allow_static_external: 是否允许 static 档位继续执行外部验证。

    返回:
        返回当前调用最终是否应该执行外部验证。

    异常:
        ValueError: 当外部验证目标不是 local 且策略不允许继续时抛出。
    """

    # 调用方没有请求外部验证时,直接关闭该链路。
    if not run_external:

        # 返回 False,表示当前调用不进入外部验证。
        return False

    # static 以下的准备度在默认策略下不能继续进入外部验证。
    if not allow_static_external and not readiness_at_least(readiness, "compile"):

        # 返回 False,表示当前准备度不足以执行外部验证。
        return False

    # 当前 facade 的本地外部验证必须显式落到 local 目标。
    if external_target != "local":

        # 阻止 remote-first 情况被错误地当成本地外部验证执行。
        raise ValueError(
            "> ERR: [Python] External validation is remote-first. Use the remote "
            "validation flow, or pass external_target='local' only after the user "
            "explicitly approves local external validation."
        )

    # 返回 True,表示当前调用允许执行外部验证。
    return True

# _workflow_runtime_payload 按固定字段顺序返回 workflow runtime 参数字典。
def _workflow_runtime_payload(dict_runtime_values: dict[str, Any]) -> dict[str, Any]:
    """按固定字段顺序返回 workflow runtime 参数字典。

    参数:
        dict_runtime_values: 已经解析完成的 runtime 参数字典。

    返回:
        返回字段顺序稳定的 workflow runtime 参数字典。
    """

    # 最终按固定字段顺序回放 runtime 参数字典。
    return {str_key: dict_runtime_values[str_key] for str_key in WORKFLOW_RUNTIME_OPTION_KEYS}

# _resolved_workflow_runtime_options 解析 workflow 运行时最终采用的参数。
def _resolved_workflow_runtime_options(
    spec: JsonSource | None,
    dict_options: dict[str, Any],
) -> dict[str, Any]:
    """解析 workflow 运行时最终采用的参数。

    参数:
        spec: 当前 workflow 调用收到的 spec 输入,可以为空。
        dict_options: 当前 workflow 入口合并后的统一配置字典。

    返回:
        返回字段顺序稳定的 workflow runtime 参数字典。
    """

    # 先读取仓库默认 workflow 配置,后面逐项做回退。
    dict_defaults = load_default_workflow_config()  # runtime 提供的 workflow 默认配置字典

    # 再展开调用方传来的 workflow_config 覆盖。
    dict_workflow_payload = _load_optional_json(dict_options.get("workflow_config")) or {}  # 当前调用附带的 workflow 配置覆盖字典

    # 如果还在使用旧结构,这里抽出嵌套 workflow 段。
    dict_overrides = _workflow_overrides(dict_workflow_payload)  # 当前调用实际生效的 workflow 覆盖字典

    # 默认值与覆盖值在这里拼成同一张视图。
    dict_merged = {**dict_defaults, **dict_overrides}  # workflow 默认配置与覆盖配置合并后的统一视图

    # 目标类型必须先收敛到 facade 唯一支持的 rtl。
    str_resolved_target = _resolve_target(dict_options.get("target"), spec, dict_merged)  # 当前 workflow 最终采用的 target

    # readiness 档位缺省时回退到 static。
    str_resolved_readiness = str(_option_value(dict_options, "readiness", dict_merged, "static"))  # 当前 workflow 真正执行的 readiness 档位

    # 最大尝试次数在这里收敛成整数。
    int_resolved_attempts = int(_option_value(dict_options, "max_attempts", dict_merged, 3))  # 当前 workflow 最终采用的最大尝试次数

    # stop_on_human 决定需要人工时是否暂停链路。
    bool_resolved_stop_on_human = bool(_option_value(dict_options, "stop_on_human", dict_merged, True))  # 当前 workflow 是否在需要人工时暂停

    # 先单独解析调用方的外部验证意图。
    bool_requested_run_external = bool(_option_value(dict_options, "run_external", dict_merged, True))  # 当前 workflow 是否收到外部验证请求

    # 再读取本次请求指向的外部目标环境。
    str_resolved_external_target = str(dict_options.get("external_target", "remote"))  # 当前 workflow 请求的外部目标环境

    # readiness 与目标策略会共同裁决最终是否跑外部验证。
    bool_resolved_run_external = _resolve_external_run(  # readiness 与目标策略共同裁决后的外部验证开关
        bool_requested_run_external,  # 调用方是否发出了外部验证请求
        readiness=str_resolved_readiness,  # 裁决时使用的 readiness 档位
        external_target=str_resolved_external_target,  # 裁决时使用的外部目标环境
    )

    # 注释语种沿用 workflow 默认值或本次覆盖值。
    str_resolved_comment_language = str(_option_value(dict_options, "comment_language", dict_merged, "zh"))  # 当前 workflow 最终采用的注释语种

    # provider 名称会影响后续模型调用后端。
    str_resolved_provider_name = str(_option_value(dict_options, "provider_name", dict_merged, "command"))  # 当前 workflow 最终采用的 provider 名称

    # 模型超时统一换算成秒级整数。
    int_resolved_timeout = int(_option_value(dict_options, "model_timeout_s", dict_merged, 120))  # 当前 workflow 最终采用的模型超时时间

    # generation_mode 决定 workflow 的执行形态。
    str_resolved_generation_mode = str(_option_value(dict_options, "generation_mode", dict_merged, "regular"))  # 当前 workflow 最终采用的生成模式

    # stream 开关单独保留给 provider 层使用。
    bool_resolved_stream = bool(_option_value(dict_options, "stream", dict_merged, False))  # 当前 workflow 是否启用流式输出

    # 先准备一个可按固定顺序填充的 runtime 参数视图。
    dict_runtime_values: dict[str, Any] = {}  # run_workflow 最终消费的参数视图

    # 目标类型写入最终 runtime 参数视图。
    dict_runtime_values["target"] = str_resolved_target  # 目标类型

    # readiness 档位写入最终 runtime 参数视图。
    dict_runtime_values["readiness"] = str_resolved_readiness  # 准备度档位

    # 最大尝试次数写入最终 runtime 参数视图。
    dict_runtime_values["max_attempts"] = int_resolved_attempts  # 最大尝试次数

    # stop_on_human 写入最终 runtime 参数视图。
    dict_runtime_values["stop_on_human"] = bool_resolved_stop_on_human  # 人工确认暂停开关

    # run_external 这一项记录的是裁决后的最终执行开关。
    dict_runtime_values["run_external"] = bool_resolved_run_external  # 外部验证执行开关

    # 注释语种写入最终 runtime 参数视图。
    dict_runtime_values["comment_language"] = str_resolved_comment_language  # 注释语种

    # provider 名称写入最终 runtime 参数视图。
    dict_runtime_values["provider_name"] = str_resolved_provider_name  # 生成 provider 名称

    # 模型超时写入最终 runtime 参数视图。
    dict_runtime_values["model_timeout_s"] = int_resolved_timeout  # 模型超时秒数

    # 生成模式写入最终 runtime 参数视图。
    dict_runtime_values["generation_mode"] = str_resolved_generation_mode  # 生成模式

    # 流式输出开关写入最终 runtime 参数视图。
    dict_runtime_values["stream"] = bool_resolved_stream  # 流式输出开关

    # 最后按固定字段顺序导出 runtime 参数字典。
    return _workflow_runtime_payload(dict_runtime_values)

# _resume_workflow_run 恢复已有 workflow 目录并返回稳定 facade 结果。
def _resume_workflow_run(
    dict_options: dict[str, Any],
    dict_runtime_options: dict[str, Any],
) -> dict[str, Any]:
    """恢复已有 workflow 目录并返回稳定 facade 结果。

    参数:
        dict_options: 当前 workflow 入口合并后的统一配置字典。
        dict_runtime_options: 当前 workflow 最终采用的 runtime 参数字典。

    返回:
        返回恢复运行后的稳定 facade 结果字典。
    """

    # 先把恢复目标目录标准化成 Path。
    path_run_dir = Path(dict_options["resume_dir"])  # 当前要恢复的 workflow 运行目录

    # 恢复态如果带了 decision,这里统一物化成 runtime 可读取的文件。
    path_decision = _materialize_optional_json(  # 恢复态需要复用的 decision 文件路径
        dict_options.get("decision"),  # 调用方显式给出的 decision 输入
        path_run_dir / "_adapter_inputs" / "decision.json",  # 恢复态 decision 文件的落盘位置
    )

    # 恢复运行时要把 workspace 根切到既有 run_dir。
    with use_workspace_root(path_run_dir):

        # runtime 在这里继续推进已有 workflow 目录。
        dict_workflow_result = run_workflow(  # runtime 返回的恢复执行结果
            resume_dir=path_run_dir,  # 已存在的 workflow 运行目录
            decision_path=path_decision,  # 恢复态继续复用的 decision 文件
            generation_mode=dict_options.get("generation_mode"),  # 恢复态沿用的生成模式
            stream=dict_options.get("stream"),  # 恢复态沿用的流式输出开关
            stop_on_human=dict_runtime_options["stop_on_human"],  # 人工确认时是否暂停流程
            run_external=dict_runtime_options["run_external"],  # 恢复态是否继续执行外部验证
            comment_language=dict_runtime_options["comment_language"],  # 恢复态继续使用的注释语种
            model_timeout_s=dict_runtime_options["model_timeout_s"],  # 恢复态继续使用的模型超时
        )

    # 恢复态同样只对外 surfaced 已解析过的最终 artifact 目录。
    path_artifact_dir = _resolved_latest_artifact_dir(  # 恢复态最终 surfaced artifact 根目录
        path_run_dir,  # 当前 workflow 运行根目录
        dict_workflow_result,  # runtime 返回的完整 workflow 结果字典
    )

    # 对外只返回 facade 约定的稳定恢复结果结构。
    return {
        "status": dict_workflow_result["status"],
        "run_dir": str(path_run_dir),
        "artifact_dir": path_artifact_dir.as_posix() if path_artifact_dir is not None else None,
        "result_path": str(path_run_dir / "workflow_result.json"),
        "workflow_result": dict_workflow_result,
    }

# _new_workflow_result_payload 组装新运行 facade 的稳定结果字典。
def _new_workflow_result_payload(
    dict_workflow_result: dict[str, Any],
    path_run_dir: Path,
    path_requirements: Path,
    path_codegen_plan: Path,
    dict_requirements_payload: dict[str, Any],
    dict_codegen_plan_payload: dict[str, Any],
) -> dict[str, Any]:
    """组装新运行 facade 的稳定结果字典。

    参数:
        dict_workflow_result: runtime 返回的完整 workflow 结果字典。
        path_run_dir: 当前 workflow 运行根目录。
        path_requirements: requirements.json 的落盘路径。
        path_codegen_plan: codegen_plan.json 的落盘路径。
        dict_requirements_payload: requirements.json 对应的内存载荷。
        dict_codegen_plan_payload: codegen_plan.json 对应的内存载荷。

    返回:
        返回新运行 facade 的稳定结果字典。
    """

    # 顶层 facade 结果统一 surfaced 已解析过的最终 artifact 目录。
    path_artifact_dir = _resolved_latest_artifact_dir(  # 新运行最终 surfaced artifact 根目录
        path_run_dir,  # 供 artifact 相对路径回映到本地目录的 run 根
        dict_workflow_result,  # 新运行阶段产出的 attempts 与工件记录
    )

    # 新运行的结果字段在这里统一收口成 facade 合同。
    return {
        "status": dict_workflow_result["status"],
        "run_dir": str(path_run_dir),
        "artifact_dir": path_artifact_dir.as_posix() if path_artifact_dir is not None else None,
        "result_path": str(path_run_dir / "workflow_result.json"),
        "requirements_path": str(path_requirements),
        "codegen_plan_path": str(path_codegen_plan),
        "requirements_payload": dict_requirements_payload,
        "codegen_plan_payload": dict_codegen_plan_payload,
        "workflow_result": dict_workflow_result,
    }

# _start_new_workflow_run 启动新的 spec-first workflow 运行。
def _start_new_workflow_run(
    spec: JsonSource,
    dict_options: dict[str, Any],
    dict_runtime_options: dict[str, Any],
) -> dict[str, Any]:
    """启动新的 spec-first workflow 运行。

    参数:
        spec: 当前 workflow 调用收到的 spec 输入。
        dict_options: 当前 workflow 入口合并后的统一配置字典。
        dict_runtime_options: 当前 workflow 最终采用的 runtime 参数字典。

    返回:
        返回新 workflow 运行的稳定 facade 结果字典。
    """

    # 新 workflow 的根目录先在这里标准化。
    path_run_dir = Path(dict_options["out_dir"])  # 当前新 workflow 的运行根目录

    # 中间输入统一放进 _adapter_inputs,便于和产物目录分层。
    path_inputs_dir = path_run_dir / "_adapter_inputs"  # 当前 workflow 的 adapter 输入目录

    # 写任何中间文件之前先确保 adapter 输入目录已经存在。
    path_inputs_dir.mkdir(parents=True, exist_ok=True)

    # 设计约束先统一读取成字典或空值。
    dict_design_requirements = _load_optional_json(dict_options.get("design_requirements"))  # 当前 workflow 的设计约束字典

    # 接口细节覆盖也在这里做同样的归一化。
    dict_interface_profile = _load_optional_json(dict_options.get("interface_profile"))  # 当前 workflow 的接口细节字典

    # target 已经在 runtime 选项阶段解析完成,这里直接复用。
    str_workflow_target = dict_runtime_options["target"]  # 当前 workflow 已解析出的目标类型

    # pipeline_required 原样保留给 spec 默认值补齐逻辑。
    bool_pipeline_required = dict_options.get("pipeline_required")  # 当前 workflow 是否要求流水线语义

    # streamability 约束同样延后交给 spec 规范化逻辑。
    str_streamability = dict_options.get("streamability")  # 当前 workflow 的流式化约束文本

    # interface_family 约束也要带进 spec 预处理阶段。
    str_interface_family = dict_options.get("interface_family")  # 当前 workflow 的接口族约束文本

    # 先准备 workflow 与 prompt 共用的规范化 spec。
    dict_prepared_spec = _prepare_facade_spec(  # workflow 与 prompt 共用的规范化 spec
        spec,  # 调用方传入的原始 spec 输入
        target=str_workflow_target,  # 锁定本次 workflow 的目标类型
        design_requirements=dict_design_requirements, pipeline_required=bool_pipeline_required,  # 透传设计要求和流水线约束
        streamability=str_streamability, interface_family=str_interface_family,  # 透传流式化约束和接口族约束
        interface_profile=dict_interface_profile,  # 透传接口细节约束
    )

    # requirements.json 的载荷从 prepared spec 中提取。
    dict_requirements_payload = build_requirements_payload(dict_prepared_spec)  # 从 prepared spec 提取出的 requirements 载荷

    # requirements.json 在这里稳定落盘,供后续阶段直接复用。
    path_requirements = _write_json_object(path_inputs_dir / "requirements.json", dict_requirements_payload)  # requirements.json 的落盘路径

    # codegen plan 也从 prepared spec 统一生成。
    dict_codegen_plan = build_codegen_plan(dict_prepared_spec)  # 从 prepared spec 生成的 codegen 计划字典

    # codegen plan 文件单独落盘,便于人工复查生成计划。
    path_codegen_plan = _write_json_object(path_inputs_dir / "codegen_plan.json", dict_codegen_plan)  # 提供人工复查的 codegen 计划文件

    # 先把 plan 路径转成 run_dir 相对文本,保持产物可搬运。
    str_codegen_plan_path = path_codegen_plan.relative_to(path_run_dir).as_posix()  # codegen plan 相对 run_dir 的路径文本

    # 再把相对 plan 路径挂回 prepared spec。
    dict_prepared_spec["codegen_plan_path"] = str_codegen_plan_path  # 供 workflow 后续阶段引用的 codegen plan 相对路径

    # spec 最终要物化成 runtime 可以直接读取的文件。
    path_spec = _materialize_spec(dict_prepared_spec, path_inputs_dir / "spec.json", target=str_workflow_target)  # workflow runtime 最终读取的 spec 文件路径

    # evidence 输入若存在,也在这里转成文件路径。
    path_evidence = _materialize_optional_json(dict_options.get("evidence"), path_inputs_dir / "evidence.json")  # 当前 workflow 复用的 evidence 文件路径

    # decision 输入也要单独落成 adapter 输入文件。
    path_decision = _materialize_optional_json(dict_options.get("decision"), path_inputs_dir / "decision.json")  # 新运行阶段复用的人审决策文件

    # 启动新运行前把 workspace 根绑定到目标 run_dir。
    with use_workspace_root(path_run_dir):

        # runtime 在这里执行新的 staged workflow。
        dict_workflow_result = run_workflow(  # runtime 返回的新执行结果
            spec_path=path_spec,  # 本次运行使用的规范化 spec 文件
            target=str_workflow_target,  # 明确 staged workflow 只生成 RTL 目标
            out_dir=path_run_dir,  # 指向当前 workflow 的运行目录
            decision_path=path_decision,  # 透传本次要复用的 decision 文件
            evidence_path=path_evidence,  # 挂接本次可追溯的验证证据文件
            provider_name=dict_runtime_options["provider_name"],  # 选择本次调用的 provider 名称
            provider_command=dict_options.get("provider_command"),  # 允许调用方覆盖 provider 命令
            generation_mode=dict_runtime_options["generation_mode"],  # 指定本次 workflow 的生成模式
            stream=dict_runtime_options["stream"],  # 控制 provider 是否启用流式输出
            readiness=dict_runtime_options["readiness"],  # 传入当前 workflow 的 readiness 档位
            max_attempts=dict_runtime_options["max_attempts"],  # 限制本次 workflow 的最大尝试次数
            stop_on_human=dict_runtime_options["stop_on_human"],  # 控制人工确认时是否暂停
            run_external=dict_runtime_options["run_external"],  # 控制是否执行外部验证
            comment_language=dict_runtime_options["comment_language"],  # 约束生成注释的语言
            model_timeout_s=dict_runtime_options["model_timeout_s"],  # 约束模型调用的超时秒数
        )

    # 最后回到 facade 的稳定返回结构。
    return _new_workflow_result_payload(
        dict_workflow_result,
        path_run_dir,
        path_requirements,
        path_codegen_plan,
        dict_requirements_payload,
        dict_codegen_plan,
    )

# run_verilog_workflow 提供 staged workflow 的公共 facade 入口。
def run_verilog_workflow(
    spec: JsonSource | None = None,
    *,
    config: dict[str, Any] | None = None,
    **legacy_options: Any,
) -> dict[str, Any]:
    """启动或恢复 Verilog workflow,兼容旧关键字参数调用。

    参数:
        spec: 可选 spec 输入;恢复运行时可以为空,新运行时必须提供。
        config: 新式 facade 配置字典;缺省时只使用 legacy_options。
        legacy_options: 旧调用方传入的兼容关键字参数。

    返回:
        返回 workflow 运行或恢复后的稳定 facade 结果字典。

    异常:
        ValueError: 当新运行缺少 spec 或 out_dir 时抛出。
    """

    # workflow 入口允许的字段文本先单独命名,避免集合定义块过密。
    str_workflow_keys_text = (
        "out_dir resume_dir workflow_config evidence decision "
        "provider_name provider_command generation_mode stream target "
        "design_requirements pipeline_required streamability interface_family interface_profile "
        "readiness max_attempts run_external external_target "
        "stop_on_human comment_language model_timeout_s"
    )  # run_verilog_workflow 入口允许的兼容键文本

    # workflow 入口允许的字段集合在这里由文本切分得到。
    set_allowed_keys = set(str_workflow_keys_text.split())  # run_verilog_workflow 入口允许的兼容字段集合

    # config 与 legacy_options 会在这里合并成统一配置字典。
    dict_options = _merged_option_dict("run_verilog_workflow", config, legacy_options, allowed_keys=set_allowed_keys)  # run_verilog_workflow 入口合并后的统一配置字典

    # workflow 运行参数会在这里统一解析成稳定字典。
    dict_runtime_options = _resolved_workflow_runtime_options(spec, dict_options)  # 当前 workflow 最终采用的 runtime 参数字典

    # resume_dir 存在时优先进入恢复路径,而不是新建运行路径。
    if dict_options.get("resume_dir") is not None:

        # 返回恢复已有 run_dir 得到的稳定 facade 结果。
        return _resume_workflow_run(dict_options, dict_runtime_options)

    # 新 workflow 运行必须同时提供 spec 和 out_dir。
    if spec is None or dict_options.get("out_dir") is None:

        # 直接阻止缺失关键输入的新 workflow 运行。
        raise ValueError("> ERR: [Python] New workflow runs require both `spec` and `out_dir`.")

    # 返回新 workflow 运行得到的稳定 facade 结果。
    return _start_new_workflow_run(spec, dict_options, dict_runtime_options)

# _batch_case_id 根据规格输入和序号生成稳定的批量 case 标识。
def _batch_case_id(spec: JsonSource, index: int) -> str:
    """根据规格输入和序号生成稳定的批量 case 标识。

    参数:
        spec: 当前批量 case 对应的 spec 输入。
        index: 当前批量 case 的一基序号。

    返回:
        返回当前批量 case 的稳定标识文本。
    """

    # 内存态 spec 优先复用其 name 字段,保持批量 case 命名可读。
    if isinstance(spec, dict):

        # 返回 name 字段或基于序号生成的兜底 case 标识。
        return str(spec.get("name") or f"case_{index}")

    # 路径形式的 spec 直接复用文件 stem,缺失时退回序号兜底值。
    return Path(spec).stem or f"case_{index}"

# _resolve_result_path 解析 workflow_result 中可能出现的本地路径字段。
def _resolve_result_path(path_run_dir: Path, value: Any) -> Path | None:
    """解析 workflow_result 中可能出现的本地路径字段。

    参数:
        path_run_dir: 当前 workflow run 的根目录。
        value: workflow_result 中读取到的原始路径值。

    返回:
        返回已解析的本地路径;对于无效值或 external 占位路径返回 None。
    """

    # 空值或非字符串值不能被解释成有效的本地路径。
    if not value or not isinstance(value, str):

        # 返回 None,表示当前字段不对应本地路径。
        return None

    # 原始路径文本在这里统一转成 Path。
    path_value = Path(value)  # workflow_result 中读取到的原始路径对象

    # 绝对路径可以直接复用,不需要再拼 run_dir。
    if path_value.is_absolute():

        # 返回原始绝对路径。
        return path_value

    # external 占位路径代表该工件不在本地文件系统下。
    if value.startswith("<external>/"):

        # 返回 None,表示当前字段不对应可访问的本地路径。
        return None

    # 相对路径若在当前工作目录已存在,优先解析成真实绝对路径。
    if path_value.exists():

        # 返回已解析的绝对路径,便于后续直接读取文件。
        return path_value.resolve()

    # 其余相对路径按 run_dir 下的工件路径处理。
    return path_run_dir / path_value

# _resolved_latest_artifact_dir 统一解析 facade 顶层需要 surfaced 的最终 artifact 目录。
def _resolved_latest_artifact_dir(
    path_run_dir: Path,
    dict_workflow_result: dict[str, Any],
) -> Path | None:
    """统一解析 facade 顶层需要 surfaced 的最终 artifact 目录。

    参数:
        path_run_dir: 当前 workflow run 的根目录。
        dict_workflow_result: runtime 返回的完整 workflow 结果字典。

    返回:
        返回已解析的最终 artifact 目录;无法映射到本地路径时返回 None。
    """

    # attempts 只在 workflow_result 是字典时才允许继续读取。
    if not isinstance(dict_workflow_result, dict):

        # 坏形状的 workflow_result 直接视为没有可 surfaced 的本地 artifact。
        return None

    # attempts 列表缺失时回退为空列表,避免越界访问。
    list_attempts = dict_workflow_result.get("attempts") or []  # runtime 记录的所有 workflow attempts

    # 没有 attempt 时,说明当前 workflow 还没有最终 artifact 可以对外 surfaced。
    if not list_attempts:

        # 直接返回 None,保持 facade 顶层结果稳定。
        return None

    # 最后一次 attempt 才代表当前 workflow 对外 surfaced 的最终 artifact。
    dict_latest_attempt = list_attempts[-1]  # 当前 workflow 的最后一次 attempt 记录

    # 坏形状 attempt 不参与路径解析,避免把非字典对象误当成工件信息。
    if not isinstance(dict_latest_attempt, dict):

        # 直接返回 None,表示当前 surfaced artifact 不可解析。
        return None

    # 最终 artifact_dir 统一按 attempt 布局解析,兼容 external 脱敏占位值。
    return _resolved_attempt_artifact_dir(path_run_dir, dict_latest_attempt)

# _resolved_attempt_artifact_dir 兼容 external 占位值并重建 attempt 的本地 artifact 目录。
def _resolved_attempt_artifact_dir(
    path_run_dir: Path,
    dict_attempt: dict[str, Any],
) -> Path | None:
    """兼容 external 占位值并重建 attempt 的本地 artifact 目录。

    参数:
        path_run_dir: 当前 workflow run 的根目录。
        dict_attempt: 单个 workflow attempt 的结果字典。

    返回:
        返回已解析的 attempt artifact 目录;无法映射到本地目录时返回 None。
    """

    # artifact_dir 原始值优先按通用路径解析规则处理。
    raw_artifact_dir = dict_attempt.get("artifact_dir")  # attempt 记录里的 artifact_dir 原始值

    # 非 external 路径直接沿用现有解析结果。
    path_direct = _resolve_result_path(path_run_dir, raw_artifact_dir)  # artifact_dir 的直接解析结果

    # 已经拿到本地目录时,无需再走 attempt 布局重建。
    if path_direct is not None:

        # 返回已解析的本地 artifact 目录。
        return path_direct

    # 非字符串或非 external 占位值无法继续重建。
    if not isinstance(raw_artifact_dir, str) or not raw_artifact_dir.startswith("<external>/"):

        # 返回 None,保持 external 之外的坏形状显式暴露。
        return None

    # attempt_id 决定最终 artifact 所在的 attempt 子目录。
    value_attempt_id = dict_attempt.get("attempt_id")  # attempt 记录里的稳定编号

    # stage 决定最终 artifact 所在的最终阶段目录。
    value_stage = dict_attempt.get("stage")  # attempt 记录里的最终阶段名称

    # attempt_id 或 stage 缺失时不能可靠重建最终 artifact 目录。
    if (
        not isinstance(value_attempt_id, str)
        or not value_attempt_id
        or not isinstance(value_stage, str)
        or not value_stage
    ):

        # 返回 None,避免拼出没有证据支持的伪路径。
        return None

    # safe_path 的 external 占位只保留 basename,这里按固定 stage 布局回推真实目录。
    path_candidate = path_run_dir / value_attempt_id / value_stage / Path(raw_artifact_dir).name  # 按 stage 固定布局回推的本地 artifact 目录

    # 目录真实存在时,说明 external 占位已成功映射回本地目录。
    if path_candidate.exists():

        # 返回重建成功的本地 artifact 目录。
        return path_candidate

    # 目录不存在则说明当前 attempt 记录无法映射到本地可访问工件。
    return None

# _batch_case_summary 从单 case workflow 结果中提取批量摘要字段。
def _batch_case_summary(
    case_id: str,
    path_case_run_dir: Path,
    dict_result: dict[str, Any],
) -> dict[str, Any]:
    """从单 case workflow 结果中提取批量摘要字段。

    参数:
        case_id: 当前批量 case 的稳定标识。
        path_case_run_dir: 当前批量 case 的运行目录。
        dict_result: run_verilog_workflow 返回的稳定结果字典。

    返回:
        返回供 batch summary 复用的单 case 摘要字典。
    """

    # 先抽出 workflow_result 子字典,坏形状时回退为空。
    dict_workflow_result = dict_result.get("workflow_result", {}) if isinstance(dict_result, dict) else {}  # 单 case 的 workflow_result 子字典

    # attempts 列表只在 workflow_result 是字典时才继续读取。
    list_attempts: list[dict[str, Any]] = (
        dict_workflow_result.get("attempts", []) if isinstance(dict_workflow_result, dict) else []  # 当前单 case 的 attempts 列表
    )

    # 最新一次 attempt 单独提取出来,缺失时回退为空字典。
    dict_latest_attempt: dict[str, Any] = list_attempts[-1] if list_attempts else {}  # 最新一次 workflow attempt

    # validation 默认先记为未通过,只有文件存在时再覆盖。
    bool_validation_ok = False  # 当前单 case 的 validation 结果

    # semantic gate ready 状态默认留空,后面按文件结果补齐。
    value_semantic_gate_ready: bool | str | None = None  # 当前单 case 的 semantic gate ready 状态

    # validation.json 路径会在这里解析成本地可读路径。
    path_validation = _resolve_result_path(path_case_run_dir, dict_latest_attempt.get("validation_json"))  # validation.json 的本地路径

    # validation.json 存在时,继续提取其中的 ok 结果。
    if path_validation is not None and path_validation.exists():

        # validation.json 会先被读取成字典。
        dict_validation_payload = json.loads(path_validation.read_text(encoding="utf-8"))  # validation.json 的字典化内容

        # 再把 ok 字段收敛成布尔值。
        bool_validation_ok = bool(dict_validation_payload.get("ok"))  # validation 的布尔结果

    # 先确认最新 attempt 仍然是字典,避免读取 contract_paths 时越界。
    bool_has_attempt_dict = isinstance(dict_latest_attempt, dict)  # contract_paths 解析前的字典形状判断

    # 再抽出最新 attempt 里的 contract_paths,缺失时回退为空字典。
    dict_contract_paths = dict_latest_attempt.get("contract_paths") or {} if bool_has_attempt_dict else {}  # 最新 attempt 记录的 contract_paths 字典

    # 再从 contract_paths 中解析 stage_verification 的本地路径。
    path_stage_verification = _resolve_result_path(path_case_run_dir, dict_contract_paths.get("stage_verification"))  # 指向 stage_verification 证据文件的本地路径

    # stage_verification 存在时,再读取 ready 字段。
    if path_stage_verification is not None and path_stage_verification.exists():

        # stage_verification 文件同样先解析成字典。
        dict_stage_verification_payload = json.loads(path_stage_verification.read_text(encoding="utf-8"))  # stage_verification 文件的结构化内容

        # 最后把 ready 字段收进 batch 摘要。
        value_semantic_gate_ready = dict_stage_verification_payload.get("ready")  # 语义门 ready 状态

    # artifact_dir 在这里解析成本地路径,external 占位值则按 attempt 布局回推。
    path_artifact_dir = _resolved_attempt_artifact_dir(path_case_run_dir, dict_latest_attempt)  # artifact_dir 解析后的本地目录

    # 返回供 batch summary 复用的稳定摘要结构。
    return {
        "case_id": case_id,
        "status": str(dict_result.get("status") or "failed"),
        "run_dir": str(path_case_run_dir),
        "artifact_dir": path_artifact_dir.as_posix() if path_artifact_dir is not None else None,
        "validation_ok": bool_validation_ok,
        "semantic_gate_ready": value_semantic_gate_ready,
        "result_path": str(path_case_run_dir / "workflow_result.json"),
    }

# run_verilog_batch 提供多个 spec-to-RTL workflow 的批量执行入口。
def run_verilog_batch(
    specs: list[JsonSource],
    *,
    config: dict[str, Any] | None = None,
    **legacy_options: Any,
) -> dict[str, Any]:
    """批量运行多个 spec-to-RTL workflow,兼容旧关键字参数调用。

    参数:
        specs: 待批量运行的 spec 输入列表。
        config: 新式 facade 配置字典;缺省时只使用 legacy_options。
        legacy_options: 旧调用方传入的兼容关键字参数。

    返回:
        返回批量 workflow 的全局稳定摘要字典。

    异常:
        ValueError: 当 specs 为空或 out_dir 缺失时抛出。
    """

    # 先列出 batch 入口允许透传的兼容字段。
    str_batch_keys_text = (  # batch 入口允许透传的兼容键文本
        "out_dir workflow_config evidence "
        "provider_name provider_command generation_mode stream target "
        "design_requirements pipeline_required streamability interface_family interface_profile "
        "readiness max_attempts run_external external_target "
        "stop_on_human comment_language model_timeout_s"
    )

    # 再把字段文本转成查验 legacy 参数的集合。
    set_allowed_keys = set(str_batch_keys_text.split())  # run_verilog_batch 接收的兼容关键字集合

    # batch 配置在这里统一合并成一个字典视图。
    dict_options = _merged_option_dict("run_verilog_batch", config, legacy_options, allowed_keys=set_allowed_keys)  # run_verilog_batch 的统一配置视图

    # 空 spec 列表无法构成任何 batch 执行计划。
    if not specs:

        # 这里直接阻止空批量调用继续执行。
        raise ValueError("> ERR: [Python] run_verilog_batch requires at least one spec.")

    # batch 运行必须显式提供 out_dir 来承接子目录。
    if dict_options.get("out_dir") is None:

        # 缺失 out_dir 时无法为各 case 分配运行空间。
        raise ValueError("> ERR: [Python] run_verilog_batch requires `out_dir`.")

    # batch 根目录先在这里标准化。
    path_batch_root = Path(dict_options["out_dir"])  # 当前 batch workflow 的根目录

    # 写 case 子目录之前先确保 batch 根目录存在。
    path_batch_root.mkdir(parents=True, exist_ok=True)

    # 这个列表承接每个 case 的稳定摘要结果。
    list_case_results: list[dict[str, Any]] = []  # 当前 batch workflow 的单 case 摘要列表

    # 通过计数单独维护,便于最后汇总整体状态。
    int_passed_cases = 0  # 当前 batch workflow 中通过的 case 数量

    # 逐个 spec 进入 workflow,并保留输入顺序。
    for index, spec_item in enumerate(specs, start=1):

        # 当前 case_id 由 spec 与序号共同生成。
        str_case_id = _batch_case_id(spec_item, index)  # 当前批量 case 的稳定标识

        # case 运行目录采用序号加 case_id 的稳定命名。
        path_case_run_dir = path_batch_root / f"{index:03d}-{str_case_id}"  # 当前批量 case 的运行目录

        # 单 case 配置从 batch 配置复制,并改写 out_dir。
        dict_case_config = {**dict_options, "out_dir": path_case_run_dir, "resume_dir": None}  # 传给单 case workflow 的配置字典

        # 先执行单 case workflow,再从结果中提取摘要。
        dict_case_result = run_verilog_workflow(spec_item, config=dict_case_config)  # 当前批量 case 的 workflow 运行结果

        # 单 case 结果在这里转成稳定摘要结构。
        dict_case_summary = _batch_case_summary(str_case_id, path_case_run_dir, dict_case_result)  # 当前批量 case 的稳定摘要字典

        # 当前 case 摘要随后追加到 batch 汇总列表。
        list_case_results.append(dict_case_summary)

        # 只有 passed case 才计入最终通过数量。
        if dict_case_summary["status"] == "passed":

            # 这里单独累加 batch 的通过计数。
            int_passed_cases += 1  # 当前 case 通过时累加 batch 通过计数

    # 只有全部 case 通过时,batch 才记为 passed。
    str_status = "passed" if int_passed_cases == len(list_case_results) else "failed"  # 当前 batch workflow 的整体状态文本

    # 返回 batch 入口约定的全局稳定摘要结构。
    return {
        "status": str_status,
        "run_dir": str(path_batch_root),
        "summary": {
            "case_count": len(list_case_results),
            "passed_cases": int_passed_cases,
            "failed_cases": len(list_case_results) - int_passed_cases,
            "generation_mode": dict_options.get("generation_mode") or "regular",
        },
        "cases": list_case_results,
    }

# render_verilog_prompt 提供 Verilog 生成提示词渲染入口。
def render_verilog_prompt(
    spec: JsonSource,
    out_path: str | Path,
    *,
    config: dict[str, Any] | None = None,
    **legacy_options: Any,
) -> dict[str, Any]:
    """渲染 Verilog 生成 prompt,并写入调用方指定路径。

    参数:
        spec: 原始 spec 输入,可以是路径或内存态字典。
        out_path: prompt 文本的目标输出路径。
        config: 新式 facade 配置字典;缺省时只使用 legacy_options。
        legacy_options: 旧调用方传入的兼容关键字参数。

    返回:
        返回包含 prompt 输出路径和 prompt 文本的结果字典。
    """

    # 先把 prompt 入口允许透传的 legacy 键整理成稳定白名单文本。
    str_prompt_keys_text = (  # 用于生成 prompt legacy 白名单的键串
        "target design_requirements pipeline_required "
        "streamability interface_family interface_profile "
        "stage context_manifest context_dir evidence memory decision "
        "comment_language vector_contract subfunction budget"
    )

    # 再把字段文本切分成 legacy 参数校验集合。
    set_allowed_keys = set(str_prompt_keys_text.split())  # prompt legacy 参数校验使用的键集合

    # prompt 配置在这里合并成统一字典视图。
    dict_options = _merged_option_dict("render_verilog_prompt", config, legacy_options, allowed_keys=set_allowed_keys)  # prompt 渲染前整理出的统一配置视图

    # target 先在这里收敛到 facade 唯一支持的 rtl。
    str_target = _resolve_target(dict_options.get("target"), spec, {})  # render_verilog_prompt 解析出的 target

    # design_requirements 输入先统一读取成字典或空值。
    dict_design_requirements = _load_optional_json(dict_options.get("design_requirements"))  # prompt 渲染使用的设计约束字典

    # interface_profile 也在这里做同样的归一化。
    dict_interface_profile = _load_optional_json(dict_options.get("interface_profile"))  # prompt 渲染使用的接口细节字典

    # prompt 与 codegen plan 共用同一份规范化 spec。
    dict_resolved_spec = _prepare_facade_spec(  # prompt 阶段要消费的默认化 spec 视图
        spec,  # 保留调用方提交的原始 spec
        target=str_target,  # 锁定 prompt 阶段使用的目标类型
        design_requirements=dict_design_requirements, pipeline_required=dict_options.get("pipeline_required"),  # 把设计要求和流水线偏好带进 prompt
        streamability=dict_options.get("streamability"), interface_family=dict_options.get("interface_family"),  # 把流式化要求和接口族选择带进 prompt
        interface_profile=dict_interface_profile,  # 把接口细节约定带进 prompt
    )

    # codegen plan 在这里从规范化 spec 中派生。
    dict_resolved_codegen_plan = build_codegen_plan(dict_resolved_spec)  # prompt 渲染使用的 codegen 计划字典

    # context_manifest 会告诉 prompt 还需要显式展开哪些上下文条目。
    dict_context_manifest = _load_optional_json(dict_options.get("context_manifest"))  # prompt 需要显式展开的上下文清单

    # context_dir 会在这里标准化成 Path 或 None。
    path_context_dir = _optional_path(dict_options.get("context_dir"))  # prompt 补充上下文目录的根路径

    # evidence 会把已有验证证据拼接进 prompt 上下文。
    dict_evidence = _load_optional_json(dict_options.get("evidence"))  # prompt 追加的验证证据片段

    # memory 会把历史经验片段挂回当前 prompt。
    dict_memory = _load_optional_json(dict_options.get("memory"))  # prompt 复用的历史记忆片段

    # vector_contract 会补充向量接口在 prompt 阶段的约束。
    dict_vector_contract = _load_optional_json(dict_options.get("vector_contract"))  # prompt 追加的向量接口契约

    # decision 会把既有人审决策重新注入本轮 prompt。
    dict_decision = _load_optional_json(dict_options.get("decision"))  # prompt 复用的人审决策输入

    # comment_language 会影响最终 prompt 里的注释语种。
    str_comment_language = str(dict_options.get("comment_language", "zh"))  # prompt 渲染使用的注释语种

    # stage 缺省回落到 rtl,保持既有 prompt 合同不变。
    str_stage = str(dict_options.get("stage") or "rtl")  # prompt 渲染使用的阶段名称

    # budget 缺省回落到 normal,保持既有预算档位合同。
    str_budget = str(dict_options.get("budget", "normal"))  # prompt 渲染使用的预算档位

    # 最终 prompt 文本在这里一次性渲染完成。
    str_prompt_text = render_prompt(  # 最终 prompt 文本
        dict_resolved_spec,  # prompt 渲染使用的规范化 spec
        target="rtl", stage=str_stage,  # 锁定 prompt 的目标类型和阶段
        context_manifest=dict_context_manifest, context_dir=path_context_dir,  # 透传上下文清单和上下文目录
        evidence=dict_evidence, memory=dict_memory,  # 透传验证证据和历史记忆
        comment_language=str_comment_language, vector_contract=dict_vector_contract,  # 约束注释语种和向量接口契约
        codegen_plan=dict_resolved_codegen_plan, subfunction=dict_options.get("subfunction"),  # 透传代码计划和子功能提示
        budget=str_budget, decision=dict_decision,  # 透传预算档位和人审决策输入
    )

    # 输出路径会在这里标准化成 Path。
    path_output = Path(out_path)  # prompt 文本的目标输出路径

    # 写文件之前先保证目标父目录已经存在。
    path_output.parent.mkdir(parents=True, exist_ok=True)

    # 把渲染好的 prompt 文本稳定写入目标路径。
    path_output.write_text(str_prompt_text, encoding="utf-8")

    # 返回包含路径与文本的稳定渲染结果。
    return {
        "path": str(path_output),
        "prompt": str_prompt_text,
    }
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