Skip to content

Eriemon/verilog-generator

readable-verilog-generator

Verified

Use when creating, writing, reviewing, annotating, repairing, refactoring, or validating readable Verilog RTL, including synthesizable Verilog-2001 .v files, existing-RTL analysis, semantic comment annotation, testbench scaffold planning, ASIC-quality review, local or remote Vivado/xsim validation, evidence-backed repair, and workflow trace diagnosis.

FileKindSize
SKILL.mdskill md21.3 KB
agents/openai.yamlconfig363 B
assets/examples/existing_rtl/fsm_without_default.vother761 B
assets/examples/existing_rtl/fsm_without_default_spec.mdmarkdown311 B
assets/examples/existing_rtl/leaf_counter.vother314 B
assets/examples/existing_rtl/missing_output_register.vother423 B
assets/examples/existing_rtl/missing_output_register_spec.mdmarkdown331 B
assets/examples/existing_rtl/ready_valid_slice.vother967 B
assets/examples/existing_rtl/ready_valid_slice_spec.mdmarkdown420 B
assets/examples/existing_rtl/reset_gap_counter.vother319 B
assets/examples/existing_rtl/reset_gap_counter_spec.mdmarkdown212 B
assets/examples/existing_rtl/tb_ready_valid_slice.vother846 B
assets/examples/existing_rtl/top_counter.vother271 B
assets/examples/existing_rtl/traffic_light.vother2.5 KB
assets/examples/existing_rtl/traffic_light_spec.mdmarkdown585 B
assets/examples/readme/axis_packet_meter.vother10.2 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/generated/rtl/comb_hierarchy_budget.vother1.9 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/generated/tb/tb_comb_hierarchy_budget.vother2.5 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_child_loop.vother447 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_over_budget.vother527 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_q_cut.vother467 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_within_budget.vother450 B
assets/examples/remote_fixtures/comb_hierarchy_budget/spec.jsonconfig1.7 KB
assets/examples/remote_fixtures/comb_operation_budget/comb_operation_budget_bad.vother187 B
assets/examples/remote_fixtures/comb_operation_budget/generated/rtl/comb_operation_budget.vother6.1 KB
assets/examples/remote_fixtures/comb_operation_budget/generated/tb/tb_comb_operation_budget.vother5.7 KB
assets/examples/remote_fixtures/comb_operation_budget/spec.jsonconfig2.9 KB
assets/examples/remote_fixtures/comb_parity_mux/generated/rtl/comb_parity_mux.vother2.1 KB
assets/examples/remote_fixtures/comb_parity_mux/generated/tb/tb_comb_parity_mux.vother2.8 KB
assets/examples/remote_fixtures/comb_parity_mux/spec.jsonconfig1.9 KB
assets/examples/remote_fixtures/pipeline_delay/generated/rtl/pipeline_delay.vother4.5 KB
assets/examples/remote_fixtures/pipeline_delay/generated/tb/tb_pipeline_delay.vother2.6 KB
assets/examples/remote_fixtures/pipeline_delay/spec.jsonconfig2.2 KB
assets/examples/remote_fixtures/ready_valid_slice/generated/rtl/ready_valid_slice.vother5.2 KB
assets/examples/remote_fixtures/ready_valid_slice/generated/tb/tb_ready_valid_slice.vother2.9 KB
assets/examples/remote_fixtures/ready_valid_slice/spec.jsonconfig2.6 KB
assets/examples/rtl_erie_verilog_spec.jsonconfig2.1 KB
assets/examples/use_case_templates/jesd_adc.jsonconfig2.4 KB
assets/examples/use_case_templates/jesd_dac.jsonconfig2.5 KB
assets/examples/use_case_templates/mxfe_mixed.jsonconfig2.7 KB
assets/examples/use_case_templates/spi_adc.jsonconfig2.8 KB
assets/examples/use_case_templates/spi_dac.jsonconfig2.7 KB
assets/examples/verilog_pattern_templates/axi4_lite_csr.jsonconfig2.1 KB
assets/examples/verilog_pattern_templates/axi_interconnect_dma.jsonconfig2.3 KB
assets/examples/verilog_pattern_templates/axis_ready_valid.jsonconfig2.3 KB
assets/examples/verilog_pattern_templates/conv_load_store.jsonconfig1.8 KB
assets/external_interface_catalog.jsonconfig2.9 KB
assets/ideal_bad_style_metrics.jsonconfig17.5 KB
assets/installer/manifest.projection.jsonconfig2.8 KB
assets/installer/platforms.jsonconfig1.3 KB
assets/interface_templates/ahb_lite_config.vincother2.3 KB
assets/interface_templates/apb_config.vincother861 B
assets/interface_templates/axi4_full_master.vincother1.8 KB
assets/interface_templates/axi4_full_slave.vincother1.8 KB
assets/interface_templates/axi4_lite_config.vincother1.6 KB
assets/interface_templates/axi_stream_duplex.vincother1.1 KB
assets/interface_templates/catalog.jsonconfig2.6 KB
assets/project_ip_interface_manifest.template.jsonconfig9.4 KB
assets/readme-workflow.pngbinary1.4 MB
assets/readme/design-profile-cn.pngbinary1.4 MB
assets/readme/design-profile.pngbinary1.4 MB
assets/readme/evidence-guard-cn.pngbinary1.4 MB
assets/readme/evidence-guard.pngbinary1.4 MB
assets/readme/hero-overview-cn.pngbinary1.5 MB
assets/readme/hero-overview.pngbinary1.5 MB
assets/readme/project-facts-cn.pngbinary1.2 MB
assets/readme/project-facts.pngbinary1.3 MB
assets/readme/rule-rendering-cn.pngbinary1.4 MB
assets/readme/rule-rendering.pngbinary1.2 MB
assets/style_templates/header_prompt_none_mode.txtmarkdown2.1 KB
assets/style_templates/header_prompt_table_mode.txtmarkdown2.5 KB
assets/style_templates/rtl_bus_grouping.tplother1.0 KB
assets/style_templates/rtl_fsm.tplother832 B
assets/style_templates/rtl_header_bilingual.tplother1.6 KB
assets/style_templates/rtl_instantiation.tplother496 B
assets/style_templates/rtl_region_order.tplother987 B
assets/use_case_templates/catalog.jsonconfig2.8 KB
assets/use_case_templates/jesd_adc/README.mdmarkdown699 B
assets/use_case_templates/jesd_adc/constraints/system_constr.xdcother454 B
assets/use_case_templates/jesd_adc/manifest.jsonconfig1.7 KB
assets/use_case_templates/jesd_adc/tcl/common_bd.tclother4.0 KB
assets/use_case_templates/jesd_adc/tcl/system_bd.tclother920 B
assets/use_case_templates/jesd_adc/tcl/system_project.tclother1.0 KB
assets/use_case_templates/jesd_adc/verilog/system_top.vother2.9 KB
assets/use_case_templates/jesd_dac/README.mdmarkdown745 B
assets/use_case_templates/jesd_dac/constraints/system_constr.xdcother299 B
assets/use_case_templates/jesd_dac/manifest.jsonconfig1.7 KB
assets/use_case_templates/jesd_dac/tcl/common_bd.tclother4.8 KB
assets/use_case_templates/jesd_dac/tcl/system_bd.tclother923 B
assets/use_case_templates/jesd_dac/tcl/system_project.tclother1.1 KB
assets/use_case_templates/jesd_dac/verilog/system_top.vother2.9 KB
assets/use_case_templates/mxfe_mixed/README.mdmarkdown739 B
assets/use_case_templates/mxfe_mixed/constraints/system_constr.xdcother380 B
assets/use_case_templates/mxfe_mixed/manifest.jsonconfig1.8 KB
assets/use_case_templates/mxfe_mixed/tcl/common_bd.tclother5.4 KB
assets/use_case_templates/mxfe_mixed/tcl/system_bd.tclother1.2 KB
assets/use_case_templates/mxfe_mixed/tcl/system_project.tclother1.2 KB
assets/use_case_templates/mxfe_mixed/verilog/system_top.vother3.4 KB
assets/use_case_templates/spi_adc/README.mdmarkdown925 B
assets/use_case_templates/spi_adc/constraints/system_constr.xdcother635 B
assets/use_case_templates/spi_adc/manifest.jsonconfig1.7 KB
assets/use_case_templates/spi_adc/tcl/common_bd.tclother6.3 KB
assets/use_case_templates/spi_adc/tcl/system_bd.tclother1.6 KB
assets/use_case_templates/spi_adc/tcl/system_project.tclother982 B
assets/use_case_templates/spi_adc/verilog/system_top.vother4.2 KB
assets/use_case_templates/spi_dac/README.mdmarkdown757 B
assets/use_case_templates/spi_dac/constraints/system_constr.xdcother546 B
assets/use_case_templates/spi_dac/manifest.jsonconfig1.6 KB
assets/use_case_templates/spi_dac/tcl/common_bd.tclother5.7 KB
assets/use_case_templates/spi_dac/tcl/system_bd.tclother1.0 KB
assets/use_case_templates/spi_dac/tcl/system_project.tclother981 B
assets/use_case_templates/spi_dac/verilog/system_top.vother3.5 KB
assets/verilog_formatter_config/defaults.jsonconfig6.2 KB
assets/verilog_formatter_config/profiles/conservative.jsonconfig283 B
assets/verilog_formatter_config/profiles/example_compat.jsonconfig484 B
assets/verilog_formatter_config/profiles/formatter-lint.jsonconfig121 B
assets/verilog_formatter_config/profiles/formatter-normalize.jsonconfig182 B
assets/verilog_formatter_config/profiles/formatter-preserve.jsonconfig385 B
assets/verilog_formatter_config/profiles/formatting.jsonconfig270 B
assets/verilog_formatter_config/profiles/lint.jsonconfig269 B
assets/verilog_formatter_config/profiles/migration.jsonconfig239 B
assets/verilog_formatter_config/profiles/stress_cases_compat.jsonconfig484 B
assets/verilog_formatter_config/profiles/vitis-wrapper.jsonconfig486 B
assets/verilog_formatter_config/schema.jsonconfig13.7 KB
assets/verilog_formatter_config/templates/task-batch.jsonconfig212 B
assets/verilog_formatter_config/templates/task-inplace.jsonconfig221 B
assets/verilog_formatter_config/templates/task-single-file.jsonconfig220 B
assets/verilog_pattern_templates/axi4_lite_csr_shell.vincother562 B
assets/verilog_pattern_templates/axi_interconnect_port_groups.vincother592 B
assets/verilog_pattern_templates/axis_ready_valid_slice.vincother494 B
assets/verilog_pattern_templates/catalog.jsonconfig2.2 KB
assets/verilog_pattern_templates/conv_load_store_pipeline.vincother457 B
assets/verilog_pattern_templates/counter_state_bridge.vincother443 B
assets/verilog_pattern_templates/equivalence_wrapper_probe.vincother306 B
assets/verilog_pattern_templates/fsm_state_transition.vincother1.0 KB
assets/verilog_pattern_templates/phase_output_registering.vincother404 B
assets/verilog_pattern_templates/wrapper_top_stitching.vincother608 B
assets/verilog_quality_gates.jsonconfig38.2 KB
assets/verilog_style_rules.jsonconfig11.8 KB
assets/xilinx_primitive_semantics.jsonconfig21.4 KB
references/checklists/capability-distillation-checklist.mdmarkdown3.0 KB
references/checklists/lint-checklist.mdmarkdown3.6 KB
references/checklists/verilog-readability-gate.mdmarkdown3.5 KB
references/corpus/verilog-style-observations.mdmarkdown4.6 KB
references/integration/configuration.mdmarkdown19.9 KB
references/integration/host-integration.mdmarkdown10.6 KB
references/rules/asic-verilog-quality.mdmarkdown3.9 KB
references/rules/erie-style.mdmarkdown6.3 KB
references/rules/testbench-patterns.mdmarkdown3.2 KB
references/rules/verilog-code-comment-naming-standard.mdmarkdown55.6 KB
references/rules/verilog-comment-placement.mdmarkdown8.4 KB
references/rules/verilog-pattern-templates.mdmarkdown1.1 KB
references/rules/verilog-quality-gates.mdmarkdown21.4 KB
references/rules/xilinx-primitive-exemptions.mdmarkdown10.6 KB
references/skill/installation.mdmarkdown6.1 KB
references/skill/script-guide.mdmarkdown7.5 KB
references/skill/skill-standards.mdmarkdown2.1 KB
references/workflows/verilog_dispatcher.mdmarkdown6.4 KB
references/workflows/workflow-contracts.mdmarkdown15.1 KB
scripts/__init__.pyscript53 B
scripts/python/__init__.pyscript55 B
scripts/python/corpus/analyze_verilog_style_corpus.pyscript25.3 KB
scripts/python/existing_rtl/existing_rtl.pyscript81.1 KB
scripts/python/existing_rtl/existing_rtl_improvement.pyscript109.9 KB
scripts/python/existing_rtl/intervention.pyscript8.3 KB
scripts/python/existing_rtl/optimizer.pyscript25.8 KB
scripts/python/existing_rtl/reflection.pyscript86.7 KB
scripts/python/existing_rtl/semantic_contract.pyscript45.6 KB
scripts/python/existing_rtl/verifier.pyscript15.3 KB
scripts/python/existing_rtl/verify_repair.pyscript4.6 KB
scripts/python/existing_rtl/verify_repair_core.pyscript45.7 KB
scripts/python/existing_rtl/verify_repair_patch_apply.pyscript23.5 KB
scripts/python/existing_rtl/verify_repair_patch_categories.pyscript35.5 KB
scripts/python/existing_rtl/verify_repair_patch_plan.pyscript25.1 KB
scripts/python/existing_rtl/verify_repair_patching.pyscript2.4 KB
scripts/python/existing_rtl/verify_repair_support.pyscript25.6 KB
scripts/python/existing_rtl/verify_repair_testbench.pyscript45.9 KB
scripts/python/existing_rtl/verify_reporting.pyscript16.1 KB
scripts/python/facade/__init__.pyscript45 B
scripts/python/facade/existing_rtl_api.pyscript14.0 KB
scripts/python/facade/quality_api.pyscript19.9 KB
scripts/python/facade/representative_cases.pyscript38.3 KB
scripts/python/facade/verilog_api.pyscript6.5 KB
scripts/python/facade/workflow_api.pyscript63.2 KB
scripts/python/generation/tb_generator.pyscript54.9 KB
scripts/python/header_contract.pyscript21.1 KB
scripts/python/installation/__init__.pyscript52 B
scripts/python/installation/bundle.pyscript16.3 KB
scripts/python/installation/catalog.pyscript16.6 KB
scripts/python/installation/cli.pyscript26.4 KB
scripts/python/installation/projection.pyscript14.2 KB
scripts/python/installation/receipt.pyscript13.4 KB
scripts/python/installation/transaction.pyscript29.0 KB
scripts/python/quality/clock_name_roles.pyscript1.0 KB
scripts/python/quality/comment_placement.pyscript49.5 KB
scripts/python/quality/declaration_region_policy.pyscript8.0 KB
scripts/python/quality/deliverable_gate.pyscript51.9 KB
scripts/python/quality/external_interface_stubs.pyscript41.5 KB
scripts/python/quality/formatter_ast.pyscript85.0 KB
scripts/python/quality/formatter_ast_instances.pyscript5.4 KB

scripts/python/existing_rtl/reflection.py

View on GitHub
"""根据验证报告生成 staged Verilog 反思诊断与修复提示。"""

# 启用更直接的前向引用标注写法。
from __future__ import annotations

# 标准库依赖负责 JSON 文本序列化。
import json
from typing import Any

# 工件图摘要负责补充可疑产物定位信息。
from scripts.python.workflow.artifact_graph import suspect_artifacts_from_graph

# 计划分解器负责把输入计划收敛成统一结构。
from scripts.python.workflow.planning import decompose_spec

# 用例模板接口负责补充场景化生成上下文。
from scripts.python.workflow.use_case_templates import select_use_case_template, summarize_use_case_template

# 错误来源顺序同时决定分类与修复动作的优先级。
ERROR_SOURCES = (
    "spec_issue",  # 规格本身冲突、缺项或输出契约不一致
    "dependency_issue",  # 依赖子函数、接口或上游模块存在问题
    "testbench_issue",  # 验证激励、对拍逻辑或参考向量异常
    "current_module_issue",  # 当前模块实现或注释可审查性存在缺陷
    "toolchain_issue",  # 工具链、环境或配置导致执行失败
    "insufficient_debug",  # 调试证据不足,暂时无法定位根因
    "needs_human_intervention",  # 自动化证据不足,需要人工决策
)  # 反思流程允许识别的错误来源顺序表

# 默认动作映射为每一种来源提供首选修复策略。
ACTION_BY_SOURCE = {
    "spec_issue": "revise_plan",  # 先修规格和输出契约
    "dependency_issue": "fix_dependency",  # 先修依赖链路
    "testbench_issue": "fix_testbench",  # 先修验证资产
    "current_module_issue": "regenerate_current",  # 回到当前模块重生成
    "toolchain_issue": "fix_toolchain",  # 先修工具环境
    "insufficient_debug": "augment_tests",  # 先补调试与测试证据
    "needs_human_intervention": "ask_human",  # 直接切换人工决策
}  # 错误来源到默认修复动作的映射表

# 自由文本报告通过这组关键词映射到结构化错误来源。
SOURCE_KEYWORDS = {
    "toolchain_issue": (  # 工具链类文本命中的关键词集合
        "toolchain_issue",  # 工具不可用、超时或启动失败
        "required tool",  # 工具缺失通常意味着环境未就绪
        "failed to start",  # 工具启动失败通常说明运行环境不可用
        "timed out",  # 工具执行超时通常说明环境或调用路径异常
    ),
    "spec_issue": (  # 规格缺项或期望输出路径异常
        "spec_issue",  # validation/stage 已明确把失败归类为规格歧义
        "expected output file is missing",  # 期望产物缺失通常说明输出契约不完整
        "generated path does not exist",  # 生成路径不存在通常说明计划路径约定失效
    ),
    "dependency_issue": (  # 上游模块、声明或依赖链异常
        "dependency_issue",  # 报告已直接指出依赖链异常
        "undefined module",  # 实例化的下游模块没有可解析定义
        "undefined reference",  # 外部引用缺失通常来自依赖对象未生成
        "not declared",  # 标识符未声明时常见于接口或依赖遗漏
        "previous subfunction",  # 前序子函数失败会阻断当前阶段继续验证
        "dependency",  # 文本显式出现 dependency 时优先归到依赖问题
    ),
    "testbench_issue": (  # 验证基准、testbench 或行为检查异常
        "testbench_issue",  # 报告已直接指出 testbench 资产问题
        "testbench",  # 文本直接提到 testbench 时通常是验证资产异常
        "main() entry point",  # 入口函数缺失会导致测试脚本无法驱动
        "pass behavior",  # pass 行为异常代表对拍或断言逻辑失真
        "fail behavior",  # fail 行为异常代表失败分支验证方式不正确
        "verification case",  # 验证用例本身异常时应先回到测试资产
    ),
    "current_module_issue": (  # 当前模块实现质量或综合约束异常
        "current_module_issue",  # 报告已直接指出当前模块本体异常
        "placeholder",  # 占位实现未替换意味着当前模块未真正落地
        "not synthesizable",  # 不可综合问题通常需要回改当前 RTL
        "top module",  # top module 相关报错通常落在当前模块边界
        "failed:",  # 通用 failed 前缀常用于当前模块静态或行为失败
        "pragma",  # pragma 不兼容往往需要修改当前模块实现细节
        "cfg",  # cfg 相关文本常反映当前模块配置或生成内容不匹配
        "reviewability",  # 可审查性问题说明当前模块结构或注释失衡
        "comment",  # comment 相关失败通常要回到当前模块的可读性治理
        "fsm",  # FSM 相关失败多半来自当前模块时序或状态机实现
    ),
    "insufficient_debug": (  # 证据不足,暂时无法精确定位
        "insufficient_debug",  # 报告已直接说明调试证据不足
        "cannot pinpoint",  # 无法精确定位时需要先补定位证据
        "limited test cases",  # 用例过少意味着当前回归覆盖不足
    ),
}  # 文本关键词到错误来源的匹配表

# 语义执行摘要只关心这一组核心字段。
SEMANTIC_KEYS = (
    "semantic_ready",  # 语义执行是否达到可判定状态
    "mismatched_cases",  # 失配用例详情
    "checkpoint_drift",  # 检查点漂移明细
    "failed_cases",  # 失败用例编号列表
    "localization_confidence",  # 定位置信度
)  # 语义摘要允许透传的字段集合

# 轨迹摘要默认只保留最近若干次事件,避免 prompt 膨胀。
MAX_TRAJECTORY_EVENTS = 12  # 轨迹摘要保留的最近事件数量

# 工件回溯只读取最近若干次事件,避免把陈旧路径带回修复提示。
MAX_TRACE_ARTIFACT_EVENTS = 8  # 回溯可疑工件时读取的最近事件数量

# 仅在目标列表中追加未出现过的字符串,保证顺序去重。
def _append_unique_str(list_target: list[str], str_value: str) -> None:
    """按首次出现顺序向列表追加唯一字符串。

    参数:
        list_target: 需要原位追加的目标字符串列表。
        str_value: 当前候选字符串值。

    返回:
        None。
    """

    # 只有尚未出现的新值才需要追加。
    if str_value not in list_target:

        # 把新的唯一值追加到结果末尾。
        list_target.append(str_value)

# 判断文本中是否包含指定关键词集合。
def _contains_any_keyword(str_text: str, tuple_keywords: tuple[str, ...]) -> bool:
    """判断文本是否命中任一关键词。

    参数:
        str_text: 已统一大小写的待匹配文本。
        tuple_keywords: 当前来源对应的关键词元组。

    返回:
        命中任一关键词时返回 True,否则返回 False。
    """

    # 逐个关键词检查文本是否存在匹配片段。
    for str_keyword in tuple_keywords:

        # 一旦命中任一关键词即可提前返回。
        if str_keyword in str_text:

            # 返回命中结果,避免继续做无意义匹配。
            return True

    # 关键词全部落空后,说明当前来源没有命中文本证据。
    return False

# 把任意 JSON 兼容对象序列化成缩进文本。
def _to_pretty_json(json_compatible_value: Any) -> str:
    """把 JSON 兼容对象序列化成易读文本。

    参数:
        json_compatible_value: 需要序列化的 JSON 兼容对象。

    返回:
        适合直接嵌入提示词的缩进 JSON 文本。
    """

    # 统一使用 UTF-8 友好的格式输出诊断对象。
    str_pretty_json = json.dumps(  # 供提示词嵌入的格式化 JSON 文本
        json_compatible_value,  # 需要序列化的原始对象
        indent=2,  # 统一使用两空格缩进提升嵌入可读性
        ensure_ascii=False,  # 保留中文而不是转成 ASCII 转义
    )  # 带缩进且保留中文的 JSON 文本

    # 返回序列化后的 JSON 文本。
    return str_pretty_json

# 根据文本报告与执行轨迹归类错误来源。
def classify_report(
    report_text: str,
    trace_events: list[dict[str, Any]] | None = None,
) -> list[str]:
    """从报告文本和轨迹事件推断错误来源列表。

    参数:
        report_text: 原始验证报告文本。
        trace_events: 反思与验证阶段记录的轨迹事件列表。

    返回:
        按优先级和首次出现顺序去重后的错误来源列表。
    """

    # 统一转成小写文本,避免关键词匹配受大小写影响。
    str_lowered_report = report_text.lower()  # 用于关键词匹配的报告文本

    # 轨迹事件缺省时按空列表处理,避免后续反复判空。
    list_trace_events: list[dict[str, Any]] = trace_events or []  # 当前轨迹事件列表

    # 结果列表按首次命中顺序记录错误来源。
    list_sources: list[str] = []  # 推断得到的错误来源列表

    # 先吸收轨迹事件中已经结构化标注过的错误来源。
    for dict_event in list_trace_events:

        # 当前事件可能携带若干结构化来源标签。
        list_event_sources = (
            dict_event.get("error_sources", []) or []  # 当前事件携带的错误来源标签列表
        )

        # 逐个检查事件来源是否属于受支持枚举。
        for raw_source in list_event_sources:

            # 统一把来源项转换成字符串,避免异常类型干扰判断。
            str_source = str(raw_source)  # 当前事件来源的字符串形式

            # 非受支持的 source 对当前反思器没有解释力。
            if str_source in ERROR_SOURCES:

                # 事件来源需要按首次出现顺序追加到结果。
                _append_unique_str(list_sources, str_source)

    # 再基于自由文本关键词补齐遗漏的错误来源。
    for str_source_name, tuple_keywords in SOURCE_KEYWORDS.items():

        # 关键词命中时,把对应来源加入结果。
        if _contains_any_keyword(str_lowered_report, tuple_keywords):

            # 文本推断出的来源同样按首次出现顺序追加。
            _append_unique_str(list_sources, str_source_name)

    # 仍无法定位来源时,明确标记需要人工介入。
    if not list_sources:

        # 用统一的人机协同来源兜底,避免结果为空。
        _append_unique_str(list_sources, "needs_human_intervention")

    # 返回按优先级去重后的错误来源列表。
    return list_sources

# 为 staged Verilog 修复流程生成完整提示词。
def generate_repair_prompt(
    report_text: str,
    plan: dict[str, Any],
    trace_events: list[dict[str, Any]] | None = None,
    validation_json: dict[str, Any] | None = None,
    artifact_graph: dict[str, Any] | None = None,
    stage_verification: dict[str, Any] | None = None,
) -> str:
    """生成包含诊断、计划与验证证据的修复提示词。

    参数:
        report_text: 原始验证报告文本。
        plan: 当前阶段对应的实现计划。
        trace_events: 历史反思与验证轨迹事件列表。
        validation_json: 结构化 validation 报告对象。
        artifact_graph: 当前阶段的工件依赖图摘要。
        stage_verification: stage verifier 输出的结构化 gate 结果。

    返回:
        供修复器直接消费的完整修复提示词。
    """

    # 先把输入计划规范化,避免不同入口结构影响后续逻辑。
    dict_normalized_plan = decompose_spec(plan)  # 规范化后的实现计划

    # 轨迹事件缺省时统一按空列表处理。
    list_trace_events: list[dict[str, Any]] = trace_events or []  # 当前修复上下文中的轨迹事件

    # 修复计划负责给出错误来源、动作与上下文需求。
    dict_repair_plan = build_repair_plan(  # 后续修复动作与上下文约束
        report_text,  # 原始验证报告文本
        dict_normalized_plan,  # 规范化后的计划骨架
        list_trace_events,  # 用来追溯可疑工件的近期轨迹窗口
        validation_json,  # validation JSON 提供的结构化报告对象
        artifact_graph,  # 当前阶段的工件依赖图摘要
        stage_verification,  # 用 stage issue 文本筛第一批可疑子函数
    )  # 结构化修复计划

    # repair plan 先复用诊断快照,再决定动作和上下文。
    dict_diagnosis = build_diagnosis(  # 先产出定位快照,再决定修复动作
        dict_normalized_plan,  # 提供计划骨架,便于诊断器识别候选子函数与依赖
        list_trace_events,  # 回放最近尝试序列,判断哪些自动路线已经走过
        validation_json,  # 补入 metrics 与 issue 细节,支撑失败类型归因
        stage_verification,  # 复用 stage gate 已算出的来源、ready 与推荐动作
    )  # 当前问题的结构化诊断结果

    # 计划 JSON 会直接嵌入 prompt,供后续修复器引用。
    str_plan_json = _to_pretty_json(dict_normalized_plan)  # 规范化计划的 JSON 文本

    # 分类结果 JSON 用来解释主要错误来源与行动建议。
    str_classification_json = _to_pretty_json(dict_repair_plan)  # 修复计划的 JSON 文本

    # 差分诊断 JSON 负责补足定位与下一步动作推理。
    str_diagnosis_json = _to_pretty_json(dict_diagnosis)  # 差分诊断的 JSON 文本

    # 轨迹摘要帮助修复器理解最近尝试过什么。
    str_trace_json = _to_pretty_json(  # 最近轨迹摘要的 JSON 文本
        _trajectory_summary(list_trace_events)  # 最近若干次轨迹事件的轻量摘要
    )

    # 结构化验证 JSON 直接保留原始字段,避免丢失诊断上下文。
    str_validation_json = _to_pretty_json(validation_json or {})  # 验证报告的 JSON 文本

    # 工件图摘要帮助修复器理解当前失败波及的产物范围。
    str_graph_json = _to_pretty_json(  # 工件图轻量摘要的 JSON 文本
        _graph_summary(artifact_graph)  # 适合嵌入 prompt 的工件图摘要
    )

    # Stage verifier 结果比纯文本报告更适合作为高置信门禁证据。
    str_gate_json = _to_pretty_json(  # stage gate 序列化后的 JSON 文本
        stage_verification or {}  # stage verifier 输出的原始结构化结果
    )  # stage verifier 门禁结果的 JSON 文本

    # 用例模板上下文用于保留场景约束与板级信息。
    str_use_case_template_json = _to_pretty_json(  # 用例模板约束与场景摘要
        _use_case_template_context(dict_normalized_plan)  # 当前计划匹配到的模板上下文摘要
    )

    # 报告正文在嵌入前去掉尾部多余空白,减少 prompt 噪音。
    str_trimmed_report = report_text.rstrip()  # 去尾空白后的原始验证报告

    # 组装最终提示词,保持诊断证据与行动说明的节顺序稳定。
    str_repair_prompt = (
        "# Repair prompt\n\n"
        "You are repairing a staged Verilog generation result. Use the implementation plan,\n"
        "validation report, and error-source classification below.\n\n"
        "## Error-source classification\n\n"
        "```json\n"
        f"{str_classification_json}\n"
        "```\n\n"
        "## Differential diagnosis\n\n"
        "```json\n"
        f"{str_diagnosis_json}\n"
        "```\n\n"
        "## Implementation plan\n\n"
        "```json\n"
        f"{str_plan_json}\n"
        "```\n\n"
        "## Generation trajectory summary\n\n"
        "```json\n"
        f"{str_trace_json}\n"
        "```\n\n"
        "## Structured validation report\n\n"
        "```json\n"
        f"{str_validation_json}\n"
        "```\n\n"
        "## Artifact graph summary\n\n"
        "```json\n"
        f"{str_graph_json}\n"
        "```\n\n"
        "## Verifier gate result\n\n"
        "```json\n"
        f"{str_gate_json}\n"
        "```\n\n"
        "## Use-case template context\n\n"
        "```json\n"
        f"{str_use_case_template_json}\n"
        "```\n\n"
        "## Validation report\n\n"
        "```text\n"
        f"{str_trimmed_report}\n"
        "```\n\n"
        "## Repair instructions\n\n"
        "- If the source is `spec_issue`, revise the implementation plan or requested outputs\n"
        "  before regenerating code.\n"
        "- If the source is `dependency_issue`, inspect dependent subfunctions and interface\n"
        "  compatibility before editing the current module.\n"
        "- If the source is `testbench_issue`, repair the self-checking testbench and\n"
        "  reference-vector comparison before changing design logic.\n"
        "- If the source is `current_module_issue`, regenerate only the failing module or\n"
        "  testbench when possible.\n"
        "- If the source is `toolchain_issue`, fix tool availability/configuration first; do\n"
        "  not rewrite code unless the tool output points to code errors.\n"
        "- If a Verifier gate result is present, prioritize its `recommended_action`,\n"
        "  interface-drift issues, vector-hash issues, and dependency mismatches over\n"
        "  textual guesses.\n"
        "- If a use-case template is selected, preserve its family-specific board-level\n"
        "  guidance, parameterization points, and provenance unless the repair explicitly\n"
        "  proves they caused the failure.\n"
        "- If semantic drift is visible but localization is weak, strengthen cases or\n"
        "  checkpoints before escalating to a human.\n"
        "- If the source is `needs_human_intervention`, summarize the unresolved ambiguity\n"
        "  and ask a precise hardware-design question.\n"
        "- Preserve the original output contract: manifest JSON first, then exact\n"
        "  `path=<relative/path>` code fences.\n"
        "- Keep the repaired output verifiable, executable, and implementable.\n"
    )  # 最终输出给修复器的完整提示词

    # 返回完整修复提示词。
    return str_repair_prompt

# 从计划中提取用例模板上下文,便于 prompt 保留场景约束。
def _use_case_template_context(plan: dict[str, Any]) -> dict[str, Any]:
    """返回当前计划对应的用例模板摘要。

    参数:
        plan: 已规范化的当前实现计划。

    返回:
        适合嵌入修复提示词的用例模板摘要字典。
    """

    # 先根据计划内容选择最合适的用例模板。
    dict_use_case_template = select_use_case_template(plan)  # 当前计划匹配到的用例模板

    # 再把模板收敛成适合 prompt 的轻量摘要。
    dict_template_summary = summarize_use_case_template(  # prompt 需要的模板轻量摘要
        dict_use_case_template  # select_use_case_template 选中的模板对象
    )

    # 返回模板摘要上下文。
    return dict_template_summary

# 根据首个错误来源推断默认修复动作。
def resolution_action(sources: list[str]) -> str:
    """返回错误来源对应的默认修复动作。

    参数:
        sources: 已按优先级排序的错误来源列表。

    返回:
        当前来源列表对应的默认修复动作字符串。
    """

    # 没有来源时直接要求人工介入。
    if not sources:

        # 返回人工介入动作,避免误判自动修复方向。
        return "ask_human"

    # 先取最高优先级的首个来源。
    str_primary_source = sources[0]  # 当前错误来源列表中的主来源

    # 根据主来源查默认动作,不存在时仍回退到 ask_human。
    str_action = ACTION_BY_SOURCE.get(  # 首个来源映射出的默认动作
        str_primary_source,  # 当前来源列表中的首要来源
        "ask_human",  # 缺省动作始终回退到人工确认
    )

    # 返回解析出的默认修复动作。
    return str_action

# 判断轨迹中是否已经做过 augment_tests 尝试。
def _has_prior_augment_tests(trace_events: list[dict[str, Any]]) -> bool:
    """判断轨迹是否已经出现过 augment_tests 动作。

    参数:
        trace_events: 当前阶段可用的轨迹事件列表。

    返回:
        轨迹中出现过 reflect + augment_tests 时返回 True。
    """

    # 顺序检查所有轨迹事件,寻找增强测试的历史动作。
    for dict_event in trace_events:

        # 当前事件名决定它是否属于反思阶段。
        str_event_name = str(dict_event.get("event", ""))  # 当前轨迹事件名称

        # 当前动作名用于判断是否已经尝试过增强测试。
        str_action_name = str(dict_event.get("action", ""))  # 当前轨迹动作名称

        # 一旦发现 reflect + augment_tests 组合即可返回真。
        if str_event_name == "reflect" and str_action_name == "augment_tests":

            # 返回已经尝试过增强测试的结果。
            return True

    # 遍历结束仍未发现对应动作时返回假。
    return False

# 根据语义摘要判断是否属于弱测试预言机场景。
def _has_weak_test_oracle(dict_semantic: dict[str, Any]) -> bool:
    """判断是否存在失配用例但缺少定位漂移。

    参数:
        dict_semantic: 当前阶段提取出的语义执行摘要。

    返回:
        有失配用例且没有 checkpoint 漂移时返回 True。
    """

    # 是否存在语义失配用例决定是否真的有失败证据。
    bool_has_mismatched_cases = bool(  # 是否存在失配用例证据
        dict_semantic.get("mismatched_cases")  # 语义摘要里的失配用例列表
    )

    # 是否缺少 checkpoint 漂移决定是否无法定位根因。
    bool_has_checkpoint_drift = bool(  # 是否已经具备 checkpoint 级定位线索
        dict_semantic.get("checkpoint_drift")  # 语义摘要里的 checkpoint 漂移列表
    )

    # 返回弱测试预言机判断结果。
    return bool_has_mismatched_cases and not bool_has_checkpoint_drift

# 根据结构化来源与上下文推断下一步建议动作。
def _recommended_next_action(
    dict_semantic: dict[str, Any],
    bool_prior_augments: bool,
    list_structured_sources: list[str],
) -> str:
    """返回诊断阶段建议的下一步动作。

    参数:
        dict_semantic: 当前阶段提取出的语义执行摘要。
        bool_prior_augments: 是否已经尝试过 augment_tests。
        list_structured_sources: 来自 gate 或 validation JSON 的结构化来源列表。

    返回:
        诊断阶段建议执行的下一步动作字符串。
    """

    # 规格规则含糊时优先请人确认,而不是盲目自动修复。
    if "spec_issue" in list_structured_sources:

        # 返回人工确认动作,避免继续放大规格歧义。
        return "ask_human"

    # 先根据语义摘要判断是否存在弱测试预言机场景。
    bool_weak_test_oracle = _has_weak_test_oracle(  # 当前是否属于弱测试预言机场景
        dict_semantic  # 当前门禁结果提炼出的语义定位摘要
    )

    # 首次遇到弱测试预言机时,应优先补测试和检查点。
    if bool_weak_test_oracle and not bool_prior_augments:

        # 返回增强测试动作,先补足定位证据。
        return "augment_tests"

    # 已经补过测试仍无法定位时,自动化价值已经有限。
    if bool_weak_test_oracle and bool_prior_augments:

        # 返回人工介入动作,避免重复消耗自动化轮次。
        return "ask_human"

    # 结构化来源明确指向依赖问题时优先修依赖。
    if "dependency_issue" in list_structured_sources:

        # 返回依赖修复动作,先处理上游问题。
        return "fix_dependency"

    # 仍存在失配用例时,默认继续局部重生成当前模块。
    if dict_semantic.get("mismatched_cases"):

        # 返回当前模块重生成动作。
        return "regenerate_current"

    # 没有额外线索时,仍优先回到当前模块做一次保守重生成。
    return "regenerate_current"

# 收集语义摘要里的失败用例编号。
def _collect_failing_cases(dict_semantic: dict[str, Any]) -> list[str]:
    """返回去重后的失败用例编号列表。

    参数:
        dict_semantic: 当前阶段提取出的语义执行摘要。

    返回:
        适合后续修复器引用的失败用例编号字符串列表。
    """

    # 结果列表按首次出现顺序记录失败用例编号。
    list_failing_cases: list[str] = []  # 对拍失败后需要回归的 case_id 字符串列表

    # 先吸收带 case_id 的失配用例。
    for dict_case in dict_semantic.get("mismatched_cases", []) or []:

        # 仅处理字典结构的失配项,避免异常对象影响流程。
        if isinstance(dict_case, dict):

            # 把 case_id 统一转成字符串,便于后续去重。
            str_case_id = str(dict_case.get("case_id"))  # 失配用例中的 case_id

            # 只有非空 case_id 才值得加入结果。
            if str_case_id:

                # 失配 case_id 需要按首次出现顺序收集。
                _append_unique_str(list_failing_cases, str_case_id)

    # 再补充 failed_cases 字段中的失败用例编号。
    for raw_case_id in dict_semantic.get("failed_cases", []) or []:

        # 把失败用例统一转成字符串,避免类型不一致。
        str_case_id = str(raw_case_id)  # failed_cases 中的 case_id 字符串

        # 失败 case_id 也需要按首次出现顺序收集。
        _append_unique_str(list_failing_cases, str_case_id)

    # 返回去重后的失败用例编号列表。
    return list_failing_cases

# 汇总语义摘要中暴露出来的漂移键信息。
def _collect_drift_keys(dict_semantic: dict[str, Any]) -> list[str]:
    """返回排序后的 checkpoint 漂移键列表。

    参数:
        dict_semantic: 当前阶段提取出的语义执行摘要。

    返回:
        去重并排序后的 checkpoint 漂移键字符串列表。
    """

    # 先用集合去重,再在最后统一排序。
    set_drift_keys: set[str] = set()  # 采集到的漂移键集合

    # 两类字段都可能携带 drift_keys,需要统一扫描。
    list_semantic_sources = [  # 需要统一扫描 drift_keys 的语义条目来源
        dict_semantic.get("mismatched_cases", []) or [],  # 语义失配条目列表
        dict_semantic.get("checkpoint_drift", []) or [],  # checkpoint 漂移条目列表
    ]

    # 逐组遍历语义来源,收集每个条目的 drift_keys。
    for list_semantic_items in list_semantic_sources:

        # 再逐个检查语义条目是否包含 drift_keys。
        for semantic_item in list_semantic_items:

            # 条目 helper 隔离类型判断和键规范化,主流程只负责跨来源聚合。
            set_drift_keys.update(_semantic_item_drift_keys(semantic_item))

    # 对去重后的漂移键排序,保证输出稳定。
    list_drift_keys = sorted(set_drift_keys)  # 已去重且按字典序稳定输出的漂移键列表

    # 返回排序后的漂移键列表。
    return list_drift_keys

# 单条语义记录 helper 负责规范化并去重漂移键。
def _semantic_item_drift_keys(semantic_item: Any) -> set[str]:
    """规范化单个语义条目携带的 drift_keys。

    参数:
        semantic_item: mismatched_cases 或 checkpoint_drift 中的单个条目。

    返回:
        已转成字符串并移除空值的漂移键集合。
    """

    # 非字典条目没有约定的 drift_keys 字段。
    if not isinstance(semantic_item, dict):

        # 空集合允许调用方直接执行 set.update。
        return set()

    # 集合推导同时完成字符串规范化、空值过滤和条目内去重。
    return {
        str(raw_drift_key)
        for raw_drift_key in semantic_item.get("drift_keys", []) or []
        if str(raw_drift_key)
    }

# 计算诊断结果中应该聚焦的可疑目标列表。
def _diagnosis_targets(
    plan: dict[str, Any],
    list_suspect_subfunctions: list[str],
    list_dependencies: list[str],
) -> list[str]:
    """返回诊断结果中的主可疑目标列表。

    参数:
        plan: 当前阶段对应的实现计划。
        list_suspect_subfunctions: 已定位到的可疑子函数列表。
        list_dependencies: 计划中声明的依赖名称列表。

    返回:
        供诊断结果使用的主可疑目标列表。
    """

    # 已经定位到具体子函数时,优先使用子函数集合。
    if list_suspect_subfunctions:

        # 返回已定位的可疑子函数列表。
        return list_suspect_subfunctions

    # 尚未定位到子函数但能看出依赖链时,回退到依赖列表。
    if list_dependencies:

        # 返回依赖名列表,提示先检查上游模块。
        return list_dependencies

    # 默认把当前计划名作为最后的定位兜底。
    str_plan_name = str(plan.get("name"))  # 当前计划名称字符串

    # 返回包含计划名的单元素列表作为兜底目标。
    return [str_plan_name]

# 根据漂移与疑点数量评估是否已经命中定位。
def _localization_hit(
    dict_semantic: dict[str, Any],
    list_suspect_subfunctions: list[str],
) -> bool:
    """判断诊断是否已经取得足够明确的定位线索。

    参数:
        dict_semantic: 当前阶段提取出的语义执行摘要。
        list_suspect_subfunctions: 已定位到的可疑子函数列表。

    返回:
        已具备 checkpoint 漂移或唯一可疑子函数时返回 True。
    """

    # 存在 checkpoint 漂移时,说明语义定位已经命中一部分路径。
    if dict_semantic.get("checkpoint_drift"):

        # checkpoint 漂移已经给出直接的定位信号。
        return True

    # 仅命中单个可疑子函数时,也视为较高置信度定位。
    if len(list_suspect_subfunctions) == 1:

        # 只有一个候选子函数时,定位已经足够聚焦。
        return True

    # 其他场景仍视为定位不充分。
    return False

# 构建差分诊断结果,供 repair plan 与 prompt 共享。
def build_diagnosis(
    plan: dict[str, Any],
    trace_events: list[dict[str, Any]] | None = None,
    validation_json: dict[str, Any] | None = None,
    stage_verification: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """根据计划、轨迹与验证结果构建差分诊断。

    参数:
        plan: 当前阶段对应的实现计划。
        trace_events: 历史反思与验证轨迹事件列表。
        validation_json: 结构化 validation 报告对象。
        stage_verification: stage verifier 输出的结构化 gate 结果。

    返回:
        供修复计划与提示词复用的结构化差分诊断结果。
    """

    # 诊断阶段先把缺失轨迹收敛成空列表,避免历史状态分支散落。
    list_trace_events: list[dict[str, Any]] = trace_events or []  # 当前诊断阶段可用的轨迹事件列表

    # 语义摘要负责承接语义执行、漂移与定位相关证据。
    dict_semantic = _semantic_summary(  # 汇总后续定位要依赖的语义证据
        validation_json,  # 从 validation 结果读取 semantic_execution 与失配线索
        stage_verification,  # 若 gate 已给出 ready/drift,就直接沿用其判定
    )

    # 可疑子函数列表帮助诊断定位当前最值得排查的模块。
    list_suspect_subfunctions = _suspect_subfunctions(  # 给修复器圈出首批排查目标
        plan,  # 提供计划里的子函数清单与依赖关系作为候选空间
        stage_verification,  # 直接读取 stage issue 文本里已经命中的子函数名
        dict_semantic,  # 再用 drift key 与置信度补充文本定位不足的部分
    )

    # 历史上是否已经尝试过 augment_tests 会影响下一步建议。
    bool_prior_augments = _has_prior_augment_tests(  # 判断补测试路线是否已尝试过
        list_trace_events  # 只需看历史事件序列就能判断是否做过 augment_tests
    )

    # 弱测试预言机场景表示已有失败证据但定位仍不够。
    bool_weak_test_oracle = _has_weak_test_oracle(  # 识别“有失败但还定不准”的局面
        dict_semantic  # 联合 mismatch、drift 与定位置信度做判定
    )

    # 结构化来源优先于文本猜测,用于建议下一步动作。
    list_structured_sources = (
        _sources_from_stage_verification(stage_verification)  # stage gate 已标注的错误来源
        or _sources_from_validation_json(validation_json)  # gate 缺失时再用 validation JSON 补来源
    )  # Stage gate 或 validation JSON 中的结构化来源

    # 规格歧义是优先级最高的人工确认条件。
    bool_ambiguous_spec_rule = "spec_issue" in list_structured_sources  # 是否存在规格歧义

    # 下一步动作需要综合语义线索、历史动作与结构化来源。
    str_recommended_next_action = _recommended_next_action(  # 当前诊断建议执行的下一步动作
        dict_semantic,  # 用于判断定位是否充分的语义摘要
        bool_prior_augments,  # 是否已经尝试过 augment_tests
        list_structured_sources,  # 已按优先级收集的结构化错误来源
    )

    # 失败用例编号用于提示修复器补足针对性验证。
    list_failing_cases = _collect_failing_cases(  # 抽出后续回归必须覆盖的失败 case
        dict_semantic  # 失败编号已经沉淀在语义摘要里,直接复用即可
    )

    # 漂移键信息用于定位最值得补充的检查点与依赖。
    list_drift_keys = _collect_drift_keys(  # 收集最能暴露偏移位置的 drift 键
        dict_semantic  # 漂移键既能回推子函数,也能提示该补哪些 checkpoint
    )

    # 依赖名列表用于缺少子函数定位时的上游回退。
    list_dependencies = _dependency_names(plan)  # 计划中声明的依赖名称列表

    # 诊断目标列表按子函数、依赖、计划名三级优先级选择。
    list_diagnosis_targets = _diagnosis_targets(  # 生成最终建议先看的定位目标
        plan,  # 必要时可从计划名回退,避免完全失去检索锚点
        list_suspect_subfunctions,  # 有明确命中的子函数时优先沿子函数层面排查
        list_dependencies,  # 子函数没有线索时,再退回到依赖链层面追根
    )

    # 自动调试是否已经耗尽,用于判断是否该切换人工介入。
    bool_auto_debug_exhausted = (
        bool_weak_test_oracle and bool_prior_augments  # 弱测试预言机且已补过测试时视为自动调试耗尽
    )  # 当前自动调试是否已经耗尽

    # 定位命中结果用于修复器评估是否继续本地化修复。
    bool_localization_hit = _localization_hit(  # 判断证据是否足以支撑定点修复
        dict_semantic,  # 结合 ready、drift 与失败样本看定位是否站得住
        list_suspect_subfunctions,  # 若连候选子函数都没有,就不能算定位命中
    )

    # 汇总结构化诊断结果,供 repair plan 与 prompt 共用。
    dict_diagnosis = {
        "version": 1,  # build_diagnosis 输出的固定版本号
        "semantic_ready": dict_semantic.get("semantic_ready"),  # 当前诊断看到的语义就绪位
        "failing_cases": list_failing_cases,  # 当前诊断汇总出的失败用例编号
        "checkpoint_drift": dict_semantic.get("checkpoint_drift", []),  # 当前诊断看到的 checkpoint 漂移明细
        "drift_keys": list_drift_keys,  # 从漂移明细抽取出的 checkpoint 键名
        "suspect_subfunctions": list_diagnosis_targets,  # 诊断阶段建议优先排查的目标集合
        "localization_confidence": dict_semantic.get("localization_confidence"),  # 语义摘要给出的定位置信度
        "weak_test_oracle": bool_weak_test_oracle,  # 失败存在但定位仍弱时的告警标记
        "ambiguous_spec_rule": bool_ambiguous_spec_rule,  # 是否已经命中规格歧义优先规则
        "recommended_next_action": str_recommended_next_action,  # 诊断阶段建议采取的下一步动作
        "suggested_case_ids": list_failing_cases,  # 后续回归必须优先覆盖的失败用例编号
        "suggested_checkpoints": list_drift_keys or list_dependencies,  # 优先补充的 checkpoint 或依赖线索
        "auto_debug_exhausted": bool_auto_debug_exhausted,  # 自动调试路径是否已经基本耗尽
        "auto_debug_before_human": bool_auto_debug_exhausted,  # 人工介入前是否已尝试完自动调试
        "localization_hit": bool_localization_hit,  # 诊断证据是否已经收敛到可直接下手的落点
    }  # 供 repair_plan 与 prompt 复用的诊断快照

    # 返回差分诊断结果。
    return dict_diagnosis

# 综合诊断与 gate 推荐,决定最终修复动作。
def _repair_action(
    sources: list[str],
    diagnosis: dict[str, Any],
    stage_verification: dict[str, Any] | None,
) -> str:
    """返回当前修复计划应执行的最终动作。

    参数:
        sources: 已按优先级排序的错误来源列表。
        diagnosis: 当前问题的结构化诊断结果。
        stage_verification: stage verifier 输出的结构化 gate 结果。

    返回:
        修复计划最终采用的动作字符串。
    """

    # 诊断已经明确要求人工介入时,直接返回 ask_human。
    if diagnosis.get("recommended_next_action") == "ask_human":

        # 返回人工介入动作,避免后续逻辑覆盖诊断结论。
        return "ask_human"

    # 诊断已经明确要求增强测试时,直接保留该动作。
    if diagnosis.get("recommended_next_action") == "augment_tests":

        # 返回增强测试动作,优先补足定位证据。
        return "augment_tests"

    # 只有 stage_verification 真的是字典时才读取 gate 建议。
    if isinstance(stage_verification, dict):

        # gate 推荐动作可能比默认映射更贴近当前失败场景。
        str_gate_action = str(  # stage gate 推荐的动作字符串
            stage_verification.get("recommended_action", "")  # gate 推荐的动作字段
        )

        # gate 给出明确且非 ask_human 的动作时优先采用。
        if str_gate_action and str_gate_action != "ask_human":

            # 返回 gate 推荐动作,优先使用更强证据。
            return str_gate_action

    # 其余场景回退到来源驱动的默认修复动作。
    return resolution_action(sources)

# 构建后续修复器消费的结构化修复计划。
def build_repair_plan(
    report_text: str,
    plan: dict[str, Any],
    trace_events: list[dict[str, Any]] | None = None,
    validation_json: dict[str, Any] | None = None,
    artifact_graph: dict[str, Any] | None = None,
    stage_verification: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """返回错误来源、动作与上下文需求组成的修复计划。

    参数:
        report_text: 原始验证报告文本。
        plan: 当前阶段对应的实现计划。
        trace_events: 历史反思与验证轨迹事件列表。
        validation_json: 结构化 validation 报告对象。
        artifact_graph: 当前阶段的工件依赖图摘要。
        stage_verification: stage verifier 输出的结构化 gate 结果。

    返回:
        供 prompt 与人工介入逻辑复用的结构化修复计划。
    """

    # 修复计划阶段同样先把缺失轨迹规整为空列表,避免来源回退逻辑分叉。
    list_trace_events: list[dict[str, Any]] = trace_events or []  # 当前修复计划可用的轨迹事件列表

    # 修复动作判定先共享同一份诊断快照,避免来源分析与行动建议脱节。
    dict_diagnosis = build_diagnosis(  # 先统一诊断,再做动作分流
        plan,  # 提供计划骨架,便于诊断结果引用同一批子函数与依赖
        list_trace_events,  # 让动作决策知道哪些自动尝试已经失败过
        validation_json,  # 把 issue、metrics 与 message 一并纳入动作判断
        stage_verification,  # 沿用 gate 已给出的来源判断与推荐结论
    )  # 当前修复计划依赖的结构化诊断结果

    # 错误来源按 gate、validation JSON、自由文本三层证据逐级回退。
    list_sources = (
        _sources_from_stage_verification(stage_verification)  # 首选 gate 已结构化排序的来源
        or _sources_from_validation_json(validation_json)  # gate 缺证时改读 validation issues
        or classify_report(report_text, list_trace_events)  # 只有结构化来源都缺失时才回退文本推断
    )  # 当前修复计划识别出的错误来源列表

    # 主错误来源决定了后续 scope、上下文和人工问题模板。
    str_primary_source = (
        list_sources[0] if list_sources else "needs_human_intervention"  # 首个来源缺失时回退到人工介入
    )  # 当前修复计划的主错误来源

    # 修复动作会综合诊断结论与 gate 推荐做最终选择。
    str_action = _repair_action(  # 产出本轮真正执行的修复动作
        list_sources,  # 来源顺序决定动作分流优先级
        dict_diagnosis,  # 诊断快照补充定位强弱与自动调试耗尽状态
        stage_verification,  # 若 gate 已推荐动作,则把它作为重要参考
    )  # 当前修复计划的最终动作

    # 可疑工件列表帮助修复器聚焦到最值得修改的输出。
    list_suspect_artifacts = _suspect_artifacts(  # 汇总最值得优先检查的工件路径
        validation_json,  # 先读取 validation issue 里自带 path 的失败工件
        list_trace_events,  # 再从最近轨迹补输出目录、报告名与派生路径
        artifact_graph,  # 工件图能补 target 与节点关系,帮助串起上下游
        stage_verification,  # gate 若已点名失败工件,应直接并入候选列表
    )  # 当前失败最可疑的工件路径列表

    # augment_tests 场景固定只扩增测试与检查点,不直接改设计。
    if str_action == "augment_tests":

        # 在增强测试模式下,重生成范围固定为 tests_and_checkpoints。
        str_regeneration_scope = "tests_and_checkpoints"  # augment_tests 场景下的固定 scope

    # 其他动作按主来源和工件上下文推断重生成范围。
    else:

        # 常规动作根据主来源与可疑工件推断重生成范围。
        str_regeneration_scope = _regeneration_scope(  # 常规修复动作对应的重生成范围
            str_primary_source,  # 人工提问要围绕当前阻塞主因展开
            list_suspect_artifacts,  # 由图、报告与轨迹汇总出的可疑工件列表
        )

    # 所需上下文用于约束修复器必须读取哪些证据。
    list_required_context = _required_context(  # 修复器必须读取的证据上下文清单
        str_primary_source  # 当前动作推导所依据的主错误来源
    )

    # ask_human 场景需要向用户提出更精确的问题。
    if str_action == "ask_human":

        # 只在 ask_human 场景下构造具体的人机协同问题。
        str_human_question = _human_question(  # 生成需要用户补决策的定向问题
            str_primary_source,  # 主来源决定问题该落到规格、依赖还是验证维度
            validation_json,  # 优先复用结构化 issue 里最具体的报错措辞
            report_text,  # 结构化信息不够时再借原始报告补上下文
        )

    # 其他动作不需要额外的人机问题。
    else:

        # 非 ask_human 场景显式置空 human_question。
        str_human_question = None  # 非 ask_human 动作时无需额外构造人工问题

    # stage_ready 只在 stage_verification 为字典时才允许读取。
    if isinstance(stage_verification, dict):

        # 透传 stage gate 的 ready 标记,便于后续策略判断。
        bool_stage_ready = stage_verification.get("ready")  # 当前 stage gate 是否已判定 ready

    # 缺少 stage gate 时,ready 字段保持为空。
    else:

        # 没有 stage gate 结果时显式置空。
        bool_stage_ready = None  # 当前轮次没有 stage gate,因此 ready 状态未知

    # 汇总结构化修复计划,供 prompt 与人工介入逻辑复用。
    dict_repair_plan = {
        "error_sources": list_sources,  # 当前修复计划识别出的全部错误来源
        "primary_source": str_primary_source,  # 当前修复计划识别出的主错误来源
        "action": str_action,  # 当前修复计划最终采用的动作
        "suspect_artifacts": list_suspect_artifacts,  # 由报告、轨迹和工件图共同收敛出的高优先级产物
        "regeneration_scope": str_regeneration_scope,  # 本轮重生成或补修应聚焦的范围
        "required_context": list_required_context,  # 修复器必须先读取的证据清单
        "human_question": str_human_question,  # 留给人工补足关键决策的最终提问文本
        "needs_human_intervention": str_action == "ask_human",  # 当前动作是否已经切换到人工协同
        "plan_name": plan.get("name"),  # 当前 repair plan 对应的计划名称
        "stage_ready": bool_stage_ready,  # stage gate 是否认为当前阶段已经 ready
        "diagnosis": dict_diagnosis,  # 修复动作决策时复用的差分诊断快照
    }  # 当前问题的结构化修复计划

    # 返回结构化修复计划。
    return dict_repair_plan

# 从报告文本中提炼最多若干条可读观察。
def _report_observations(report_text: str) -> list[str]:
    """返回从文本报告中截取的非空观察行。

    参数:
        report_text: 原始验证报告文本。

    返回:
        按原始顺序截取的前若干条非空观察行列表。
    """

    # 结果列表按报告顺序保留非空观察行。
    list_observations: list[str] = []  # 从报告中提炼出的观察行

    # 逐行扫描文本报告,提炼前若干条非空观察。
    for str_line in report_text.splitlines():

        # 去掉首尾空白后再判断该行是否有效。
        str_stripped_line = str_line.strip()  # 当前报告行的去空白版本

        # 非空报告行才值得保留下来作为观察。
        if str_stripped_line:

            # 先记录当前有效观察行。
            list_observations.append(str_stripped_line)

            # 最多保留前八条观察,避免输出过长。
            if len(list_observations) >= 8:

                # 达到上限后立即停止扫描。
                break

    # 返回截取后的观察行列表。
    return list_observations

# 生成需要人工介入时的结构化提问对象。
def build_intervention(
    repair_plan: dict[str, Any],
    report_text: str,
    validation_json: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """生成 ask_human 场景使用的人工介入请求对象。

    参数:
        repair_plan: 当前问题的结构化修复计划。
        report_text: 原始验证报告文本。
        validation_json: 结构化 validation 报告对象。

    返回:
        供上层直接展示或转发的人工介入请求对象。
    """

    # 先尝试从结构化验证结果中提炼 issue 文本。
    list_issue_messages = _issue_messages(  # 结构化 issue 文本优先作为人工观察项
        validation_json  # 让结构化 issue 文本优先成为人工观察项
    )

    # 缺少结构化 issue 文本时,再回退到自由文本观察。
    if list_issue_messages:

        # 优先使用结构化 issue 文本作为 observations。
        list_observations = list_issue_messages  # 人工介入对象中的 observations 列表

    # 没有结构化 issue 时,从纯文本报告中截取观察行。
    else:

        # 回退到纯文本报告的前若干条观察。
        list_observations = _report_observations(  # 从纯文本报告截取的兜底观察项
            report_text  # 当结构化 issue 缺失时回退到原始报告文本
        )

    # 汇总人工介入请求对象,保持输出结构稳定。
    dict_intervention = {
        "version": 1,  # ask_human 载荷的固定 schema 版本
        "action": "ask_human",  # 当前人工介入请求的固定动作
        "primary_source": repair_plan.get("primary_source"),  # 当前最需要人工裁决的阻塞来源
        "question": repair_plan.get("human_question")  # repair plan 已生成的定向澄清问题
        or "Please clarify the unresolved hardware-design ambiguity.",  # 缺省时退回通用硬件歧义澄清语句
        "observations": list_observations,  # 需要先呈现给人工的失败观察列表
        "attempted_actions": repair_plan.get("required_context", []),  # 已要求修复器读取过的上下文清单
        "expected_answer_format": {  # 建议人工回复时遵循的字段骨架
            "decision": "one concise design decision or debugging direction",  # 需要用户给出的核心决策
            "evidence": "spec section, waveform observation, or tool report line when available",  # 支撑该决策的证据形式
            "constraints": "any new interface/timing/resource constraints",  # 新增约束应明确写出的类别
        },  # 人工回答建议采用的结构
    }  # ask_human 场景输出的结构化人工介入请求

    # 返回人工介入请求对象。
    return dict_intervention

# 把最近若干次轨迹事件压缩成 prompt 友好的摘要。
def _trajectory_summary(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
    """返回最近轨迹事件的轻量摘要。

    参数:
        events: 当前阶段可用的完整轨迹事件列表。

    返回:
        只保留关键调试字段的最近轨迹摘要列表。
    """

    # 结果列表按事件顺序记录轻量化后的轨迹摘要。
    list_summary: list[dict[str, Any]] = []  # 轨迹事件的轻量摘要列表

    # 只保留最近若干次事件,避免 prompt 膨胀。
    list_recent_events = events[-MAX_TRAJECTORY_EVENTS:]  # 限制 prompt 膨胀后的最近轨迹窗口

    # 逐个把事件裁剪成 prompt 需要的字段。
    for dict_event in list_recent_events:

        # 当前事件的轻量摘要只保留关键调试字段。
        dict_event_summary = {
            "event": dict_event.get("event"),  # 轨迹事件名称
            "attempt_id": dict_event.get("attempt_id"),  # 当前尝试轮次标识
            "stage": dict_event.get("stage"),  # 当前轨迹记录所处的阶段名称
            "readiness": dict_event.get("readiness"),  # 当前尝试记录的就绪度状态
            "ok": dict_event.get("ok"),  # 本次事件是否走到成功出口
            "errors": dict_event.get("errors"),  # 事件里记录的错误摘要集合
            "warnings": dict_event.get("warnings"),  # 事件里记录的警告摘要集合
            "error_sources": dict_event.get("error_sources", []),  # 该事件归档过的结构化来源标签
            "action": dict_event.get("action"),  # 事件当时实际执行的修复或验证动作
        }  # 单条轨迹事件的轻量摘要

        # 把当前事件摘要追加到结果列表。
        list_summary.append(dict_event_summary)

    # 返回轻量化后的轨迹摘要列表。
    return list_summary

# 从 validation JSON 中提取并排序错误来源。
def _sources_from_validation_json(
    validation_json: dict[str, Any] | None,
) -> list[str]:
    """从 validation JSON 中提取错误来源列表。

    参数:
        validation_json: 结构化 validation 报告对象。

    返回:
        先 error 后 warning 的去重错误来源列表。
    """

    # 缺少 validation JSON 时直接返回空列表。
    if not validation_json:

        # 返回空来源列表,表示没有结构化 validation 证据。
        return []

    # error 级来源优先于 warning 级来源进入最终列表。
    list_error_sources: list[str] = []  # severity 为 error 的来源列表

    # 其他来源延后追加,保留较低优先级提示。
    list_other_sources: list[str] = []  # 非 error severity 的来源列表

    # 逐个检查 validation issues,提取受支持的 source 字段。
    for issue_item in validation_json.get("issues", []) or []:

        # 这里只接受字典 issue,保证 source 与 severity 可安全读取。
        if not isinstance(issue_item, dict):

            # 结构异常的 stage issue 既不可信也无法稳定分类。
            continue

        # 这里直接取 validation issue 自带的 source 标签,不再做文本猜测。
        str_source = str(issue_item.get("source", ""))  # 当前 validation issue 的 source 字符串

        # 未纳入 ERROR_SOURCES 的标签,说明当前模块还不会基于它做动作分流。
        if str_source not in ERROR_SOURCES:

            # 未知来源不参与当前模块的结构化分类。
            continue

        # validation issue 的 severity 只影响主来源桶与次级来源桶的归属。
        str_severity = str(  # 先把等级标签收敛成统一比较格式,避免大小写混用
            issue_item.get("severity", "")  # issue 上报的原始 severity 文本
        ).lower()  # 统一后的 stage issue severity 文本

        # error 级来源优先进入高优先级来源桶。
        if str_severity == "error":

            # 只在首次出现时把来源放入 error 桶。
            _append_unique_str(list_error_sources, str_source)

        # 其他 severity 的来源放入次级来源桶。
        else:

            # 只在首次出现时把来源放入次级来源桶。
            _append_unique_str(list_other_sources, str_source)

    # 先复制 error 桶,后续再补充未出现过的次级来源。
    list_sources = list(list_error_sources)  # 合并前的高优先级来源副本

    # 把未进入 error 桶的其他来源追加到结果末尾。
    for str_source in list_other_sources:

        # 次级来源只有尚未出现在结果中时才追加。
        if str_source not in list_sources:

            # 把次级来源追加到结果列表末尾。
            list_sources.append(str_source)

    # 返回合并后的来源列表。
    return list_sources

# 从 stage verifier 结果中提取并排序错误来源。
def _sources_from_stage_verification(
    stage_verification: dict[str, Any] | None,
) -> list[str]:
    """从 stage verifier 结果中提取错误来源列表。

    参数:
        stage_verification: stage verifier 输出的结构化 gate 结果。

    返回:
        综合 error_sources 与 issues 的去重错误来源列表。
    """

    # 缺少 stage verifier 结果时直接返回空列表。
    if not stage_verification:

        # 返回空来源列表,表示没有 stage gate 证据。
        return []

    # 显式 error_sources 字段拥有最高优先级。
    list_sources: list[str] = []  # stage verifier 中的主来源列表

    # warning 级来源在主来源之后追加。
    list_warning_sources: list[str] = []  # stage verifier 中的 warning 来源列表

    # 先读取 verifier 直接给出的 error_sources 字段。
    for raw_source in stage_verification.get("error_sources", []) or []:

        # 统一把来源项转换成字符串,避免异常类型影响判断。
        str_source = str(raw_source)  # stage verifier 显式给出的 source 字符串

        # 只保留受支持且尚未出现过的来源项。
        if str_source in ERROR_SOURCES:

            # 显式来源按首次出现顺序加入主来源列表。
            _append_unique_str(list_sources, str_source)

    # 再扫描 issue 明细,补充 error 与 warning 来源。
    for issue_item in stage_verification.get("issues", []) or []:

        # 先做结构检查,避免后面读取 source/severity 时碰到脏数据。
        if not isinstance(issue_item, dict):

            # 非字典条目没有稳定字段可读,直接跳过即可。
            continue

        # 这里只接受 stage verifier 显式上报的 source,不额外猜测文本含义。
        str_source = str(issue_item.get("source", ""))  # 当前 stage verifier issue 的 source 字段

        # 非受支持来源不参与当前模块的结构化分类。
        if str_source not in ERROR_SOURCES:

            # 跳过当前不受支持的来源类型。
            continue

        # severity 会影响该来源能否进入高优先级来源列表。
        str_severity = str(  # 统一 severity 大小写,便于后续一致比较
            issue_item.get("severity", "")  # stage issue 随条目携带的原始等级标签
        ).lower()  # 归一化后的 severity 文本

        # error 级来源需要提升到主来源列表。
        if str_severity == "error":

            # 错误级来源必须立即提升到主来源列表。
            _append_unique_str(list_sources, str_source)

        # 非 error 级来源延后追加为 warning 来源。
        else:

            # warning 来源只在尚未出现在主列表时才记录。
            if str_source not in list_sources:

                # 把 warning 来源记录到次级列表。
                _append_unique_str(list_warning_sources, str_source)

    # 先复制主来源,再补充 warning 来源。
    list_combined_sources = list(list_sources)  # 合并前的主来源副本

    # 把未进入主列表的 warning 来源补到结果末尾。
    for str_source in list_warning_sources:

        # warning 来源只有尚未出现时才追加。
        if str_source not in list_combined_sources:

            # 把 warning 来源追加到结果列表末尾。
            list_combined_sources.append(str_source)

    # stage gate 的 error 与 warning 来源已经按优先级合并完成。
    return list_combined_sources

# 结合多类证据汇总最可疑的工件路径。
def _suspect_artifacts(
    validation_json: dict[str, Any] | None,
    trace_events: list[dict[str, Any]],
    artifact_graph: dict[str, Any] | None = None,
    stage_verification: dict[str, Any] | None = None,
) -> list[str]:
    """返回当前失败最可疑的工件路径列表。

    参数:
        validation_json: 结构化 validation 报告对象。
        trace_events: 当前阶段可用的轨迹事件列表。
        artifact_graph: 当前阶段的工件依赖图摘要。
        stage_verification: stage verifier 输出的结构化 gate 结果。

    返回:
        按证据优先级去重后的可疑工件路径列表。
    """

    # 结果列表按证据强度与出现顺序记录可疑工件。
    list_artifacts: list[str] = []  # 汇总后的可疑工件路径列表

    # 图推断出的可疑工件优先进入结果。
    for raw_artifact in suspect_artifacts_from_graph(artifact_graph):

        # 工件路径统一转成字符串,便于比较与输出。
        str_artifact = str(raw_artifact)  # 工件图提供的工件路径字符串

        # 图推断出的工件按首次出现顺序追加。
        _append_unique_str(list_artifacts, str_artifact)

    # validation JSON 中的 issues 也可能直接指向问题路径。
    for issue_item in (validation_json or {}).get("issues", []) or []:

        # stage gate 只有显式给出 path,才能把失败直接落到具体产物。
        if isinstance(issue_item, dict) and issue_item.get("path"):

            # 把 issue path 统一转换成字符串。
            str_issue_path = str(issue_item["path"])  # validation issue 指向的工件路径

            # validation issue 指向的路径按首次出现顺序追加。
            _append_unique_str(list_artifacts, str_issue_path)

    # stage verifier issues 同样可能直接标明失败工件。
    for issue_item in (stage_verification or {}).get("issues", []) or []:

        # 没有 path 的 issue 只能说明失败类型,无法直接落到具体工件。
        if isinstance(issue_item, dict) and issue_item.get("path"):

            # 这里抽取的是 stage gate 已明确指出的失败工件路径。
            str_issue_path = str(issue_item["path"])  # stage gate 已定位出的工件路径

            # 让 gate 指出的路径优先进入可疑工件集合。
            _append_unique_str(list_artifacts, str_issue_path)

    # 再从最近若干次轨迹事件中补充输出、路径与报告文件线索。
    for dict_event in trace_events[-MAX_TRACE_ARTIFACT_EVENTS:]:

        # 逐个扫描轨迹事件中可能承载工件路径的字段。
        for str_key in ("output", "path", "report"):

            # 当前字段值可能就是产物路径或报告路径。
            raw_value = dict_event.get(str_key)  # 当前轨迹字段对应的原始值

            # 只有字段非空时才值得作为可疑工件线索。
            if raw_value:

                # 把轨迹字段统一转换成字符串路径。
                str_value = str(raw_value)  # 轨迹事件中的工件线索字符串

                # 把轨迹字段值按首次出现顺序追加。
                _append_unique_str(list_artifacts, str_value)

    # 图、报告和轨迹三路证据已经汇总完成。
    return list_artifacts

# 从完整工件图中裁剪 prompt 需要的轻量摘要。
def _graph_summary(artifact_graph: dict[str, Any] | None) -> dict[str, Any]:
    """返回适合嵌入 prompt 的工件图摘要。

    参数:
        artifact_graph: 当前阶段的完整工件依赖图对象。

    返回:
        只保留关键统计与可疑工件的轻量摘要字典。
    """

    # 缺少工件图时直接返回空摘要。
    if not artifact_graph:

        # 返回空字典,表示当前没有可用工件图上下文。
        return {}

    # 先提取工件图里推断出的可疑工件列表。
    list_suspect_artifacts = suspect_artifacts_from_graph(  # 工件图直接推断出的可疑产物
        artifact_graph  # 当前阶段的完整工件依赖图对象
    )

    # 汇总适合 prompt 的轻量工件图摘要。
    dict_graph_summary = {
        "name": artifact_graph.get("name"),  # 工件图名称
        "target": artifact_graph.get("target"),  # 工件图指向的当前目标名称
        "node_count": len(artifact_graph.get("nodes", []) or []),  # 工件图节点数量
        "edge_count": len(artifact_graph.get("edges", []) or []),  # 工件图边数量
        "suspect_artifacts": list_suspect_artifacts,  # 工件图单独推断出的可疑产物集合
    }  # 工件图的轻量摘要结果

    # 返回轻量工件图摘要。
    return dict_graph_summary

# 根据主来源与可疑工件推断合适的重生成范围。
def _regeneration_scope(
    primary_source: str,
    suspect_artifacts: list[str],
) -> str:
    """返回当前修复动作建议的重生成范围。

    参数:
        primary_source: 当前修复计划识别出的主错误来源。
        suspect_artifacts: 当前失败最可疑的工件路径列表。

    返回:
        对应修复动作建议采用的重生成范围字符串。
    """

    # 规格问题必须先回到计划与输出契约层面修正。
    if primary_source == "spec_issue":

        # 返回计划与请求输出级别的重生成范围。
        return "plan_and_requested_outputs"

    # 依赖问题优先回到依赖子函数链路进行修复。
    if primary_source == "dependency_issue":

        # 该问题更像是上游子函数接口或实现异常。
        return "dependency_subfunctions"

    # testbench 问题应聚焦在验证资产与参考向量。
    if primary_source == "testbench_issue":

        # 该问题更像是验证资产而非设计逻辑本身。
        return "testbench_and_reference_vectors"

    # 工具链问题需要先修复环境与配置,而不是改设计。
    if primary_source == "toolchain_issue":

        # 该问题首先需要恢复工具链、cfg 或环境可用性。
        return "toolchain_configuration"

    # 自动定位不足或明确要求人工时,不应继续自动重生成。
    if primary_source in {"insufficient_debug", "needs_human_intervention"}:

        # 继续自动重生成的价值不高,应等待新的人工指令。
        return "blocked_until_human_guidance"

    # 已经有明确可疑工件时,只需局部重生成当前模块。
    if suspect_artifacts:

        # 返回局部当前模块范围,避免扩大修改面。
        return "current_module_only"

    # 其余情况默认回到当前阶段整体重跑。
    return "current_stage"

# 为不同错误来源给出必须携带的上下文清单。
def _required_context(primary_source: str) -> list[str]:
    """返回当前主来源对应的必需上下文列表。

    参数:
        primary_source: 当前修复计划识别出的主错误来源。

    返回:
        修复器必须优先读取的上下文清单。
    """

    # 把各类来源映射到后续修复器必须读取的上下文集合。
    dict_context_by_source = {
        "spec_issue": ["evidence.json", "plan.json", "audit.md"],  # 规格冲突时必须回看的证据清单
        "dependency_issue": [  # 依赖链问题要求带上的关键上下文
            "upstream manifests",  # 上游工件与依赖声明摘要
            "subfunction interfaces",  # 子函数接口契约与端口定义
            "failing case ids",  # 最近失败用例编号与触发条件
        ],  # 依赖链问题需要回看的上下文集合
        "testbench_issue": [  # 验证资产异常时必须先核对的材料
            "semantic vectors",  # 参考向量与黄金数据来源
            "testbench file",  # 自检 testbench 或驱动脚本正文
            "validation report",  # 最近一次失败时的验证日志
        ],  # testbench 问题对应的上下文集合
        "current_module_issue": [  # 当前模块本体异常时必须对照的材料
            "current source file",  # 当前生成出的 RTL 或脚本正文
            "prior-stage artifact",  # 上一阶段稳定产物或中间导出物
            "tool output",  # 工具侧报出的综合、lint 或仿真信息
        ],  # 当前模块问题对应的上下文集合
        "toolchain_issue": ["tool path", "cfg file", "environment setup"],  # 工具链问题要求回看的环境材料
        "insufficient_debug": [  # 调试证据不足时需要额外补齐的材料
            "waveform/logs",  # 波形、日志等运行期观测证据
            "failing vectors",  # 触发失败的关键输入向量
            "suspect dependency list",  # 当前怀疑会传染故障的依赖列表
        ],  # 调试证据不足时需要补齐的上下文集合
        "needs_human_intervention": [  # 进入人工协同时必须附带的说明材料
            "spec evidence",  # 需要人工决策时必须附带的规格证据
            "attempt history",  # 已尝试路线与失败历史摘要
            "precise open question",  # 需要人工直接回答的精确问题
        ],  # 人工介入场景对应的上下文集合
    }  # 错误来源到必需上下文清单的映射

    # 读取当前主来源对应的上下文清单,缺失时回退到通用集合。
    list_required_context = dict_context_by_source.get(  # 当前来源对应的上下文清单
        primary_source,  # 缺失映射时回退到通用报告与轨迹上下文
        ["validation report", "trace"],  # 未命中映射时回退到通用报告与轨迹上下文
    )

    # 返回上下文清单。
    return list_required_context

# 在 ask_human 场景下构造最有针对性的问题。
def _human_question(
    primary_source: str,
    validation_json: dict[str, Any] | None,
    report_text: str,
) -> str:
    """返回 ask_human 场景下应抛给用户的问题。

    参数:
        primary_source: 当前修复计划识别出的主错误来源。
        validation_json: 结构化 validation 报告对象。
        report_text: 原始验证报告文本。

    返回:
        最适合当前阻塞原因的人机协同问题文本。
    """

    # 测试覆盖不足时,优先向用户请求额外波形或检查点。
    if primary_source == "insufficient_debug":

        # 返回缺少定位证据时的标准追问。
        return (
            "The current tests cannot pinpoint the failing subfunction. "
            "Which additional waveform, intermediate signal, or reference "
            "checkpoint should be used?"
        )

    # 规格冲突时,优先要求用户明确约束优先级。
    if primary_source == "spec_issue":

        # 返回规格歧义场景下的标准追问。
        return (
            "Which source requirement or interface constraint should take "
            "precedence for the missing or conflicting spec item?"
        )

    # 先尝试从结构化 issue 文本中挑选最具体的 blocker。
    list_messages = _issue_messages(validation_json)  # issue 文本候选列表

    # 存在结构化 issue 文本时,直接基于首条 issue 追问。
    if list_messages:

        # 返回基于首条 issue 的人工追问。
        return f"Please resolve this blocker: {list_messages[0]}"

    # 默认回退到报告中的第一条非空文本。
    list_report_observations = _report_observations(  # 从自由文本报告提炼的观察候选
        report_text  # 从原始报告里抽取第一条可读观察
    )

    # 报告中存在有效观察时,优先使用第一条作为追问。
    if list_report_observations:

        # 返回来自文本报告首条观察的人工追问。
        return list_report_observations[0]

    # 其余情况统一回退到通用硬件设计歧义追问。
    return "Please clarify the unresolved hardware-design ambiguity."

# 提取 validation JSON 中的可读 issue 文本。
def _issue_messages(validation_json: dict[str, Any] | None) -> list[str]:
    """返回 validation JSON 中的 issue message 列表。

    参数:
        validation_json: 结构化 validation 报告对象。

    返回:
        按原始顺序抽取出的 issue message 字符串列表。
    """

    # 结果列表按 issues 原始顺序保留 message 文本。
    list_messages: list[str] = []  # 供人工问题与 observations 复用的 issue 文本列表

    # 逐个检查 validation issues,抽取 message 字段。
    for issue_item in (validation_json or {}).get("issues", []) or []:

        # 只有包含 message 的字典 issue 才值得保留。
        if isinstance(issue_item, dict) and issue_item.get("message"):

            # 把 message 统一转换成字符串,避免类型不一致。
            str_message = str(issue_item["message"])  # 当前 issue 的 message 文本

            # 把当前 issue 文本追加到结果列表。
            list_messages.append(str_message)

    # 返回按原始顺序收集的 issue 文本列表。
    return list_messages

# 从 stage gate 或 validation JSON 中提取语义执行摘要。
def _semantic_summary(
    validation_json: dict[str, Any] | None,
    stage_verification: dict[str, Any] | None,
) -> dict[str, Any]:
    """返回语义执行相关的统一摘要。

    参数:
        validation_json: 结构化 validation 报告对象。
        stage_verification: stage verifier 输出的结构化 gate 结果。

    返回:
        统一字段名后的语义执行摘要字典。
    """

    # stage verifier 一旦显式提供语义字段,应优先采用它。
    if isinstance(stage_verification, dict):

        # 逐个检查关键语义字段是否出现在 stage gate 中。
        for str_key in SEMANTIC_KEYS:

            # 命中任一语义字段后,就以 stage gate 结果为准。
            if str_key in stage_verification:

                # 汇总 stage gate 提供的语义摘要字段。
                dict_stage_semantic = {
                    "semantic_ready": stage_verification.get("semantic_ready"),  # stage gate 是否给出可判定语义结果
                    "mismatched_cases": stage_verification.get("mismatched_cases", []),  # stage gate 上报的失配用例列表
                    "checkpoint_drift": stage_verification.get("checkpoint_drift", []),  # stage gate 识别到的 checkpoint 漂移列表
                    "failed_cases": stage_verification.get("failed_cases", []),  # stage gate 记录的失败用例编号
                    "localization_confidence": stage_verification.get("localization_confidence"),  # stage gate 给出的定位置信度
                }  # 来自 stage verifier 的语义摘要

                # 返回来自 stage gate 的语义摘要。
                return dict_stage_semantic

    # validation JSON 里的 metrics 节点承接离线语义执行摘要。
    if isinstance(validation_json, dict):

        # 先取出 metrics 节点,准备继续读取语义执行摘要。
        dict_metrics = validation_json.get("metrics", {})  # validation JSON 中的 metrics 节点

    # 缺少 validation JSON 时,metrics 退回为空字典。
    else:

        # 没有 validation JSON 时显式使用空 metrics。
        dict_metrics = {}  # 缺少 validation JSON 时的 metrics 占位

    # 只有 metrics 真的是字典时,才继续读取 semantic_execution。
    if isinstance(dict_metrics, dict):

        # 再从 metrics 中读取 semantic_execution 摘要。
        dict_semantic_execution = dict_metrics.get(  # metrics 节点中的语义执行摘要对象
            "semantic_execution",  # validation metrics 下的语义执行节点名
            {},
        )

    # 非字典 metrics 无法稳定读取字段,回退为空对象。
    else:

        # metrics 结构异常时,语义摘要直接回退为空对象。
        dict_semantic_execution = {}  # metrics 异常时使用的空语义摘要对象

    # 只有语义摘要节点确实是字典时才值得继续透传。
    if not isinstance(dict_semantic_execution, dict):

        # 返回空字典,表示当前没有可用语义摘要。
        return {}

    # 汇总 validation JSON 中真正与语义定位相关的字段。
    dict_semantic = {
        "semantic_ready": dict_semantic_execution.get("semantic_ready"),  # validation metrics 中的语义就绪位
        "mismatched_cases": dict_semantic_execution.get("mismatched_cases", []),  # validation metrics 中的失配用例列表
        "checkpoint_drift": dict_semantic_execution.get("checkpoint_drift", []),  # validation metrics 里的 checkpoint 漂移列表
        "failed_cases": dict_semantic_execution.get("failed_cases", []),  # validation metrics 里的失败用例编号
        "localization_confidence": dict_semantic_execution.get("localization_confidence"),  # 离线语义执行对定位稳定性的自评等级
    }  # 从 validation metrics 归一化出的语义摘要

    # 返回 validation JSON 提供的语义摘要。
    return dict_semantic

# 从计划中收集所有依赖名称。
def _dependency_names(plan: dict[str, Any]) -> list[str]:
    """返回计划中声明过的依赖名称列表。

    参数:
        plan: 当前阶段对应的实现计划。

    返回:
        按首次出现顺序收集的依赖名称字符串列表。
    """

    # 结果列表直接服务于依赖修复与 suggested_checkpoints 回退逻辑。
    list_dependency_names: list[str] = []  # 供 suggested_checkpoints 和依赖修复共用的依赖名列表

    # 逐个扫描子函数定义,提取 dependencies 字段。
    for subfunction_item in plan.get("subfunctions", []) or []:

        # 只处理字典结构的子函数定义。
        if not isinstance(subfunction_item, dict):

            # 非字典子函数定义无法稳定读取字段,直接跳过。
            continue

        # 再逐个读取当前子函数声明的依赖名称。
        for raw_dependency in subfunction_item.get("dependencies", []) or []:

            # 依赖名统一转成字符串,避免类型不一致。
            str_dependency_name = str(raw_dependency)  # 当前依赖名称字符串

            # 依赖名称按首次出现顺序收集。
            _append_unique_str(list_dependency_names, str_dependency_name)

    # 返回依赖名称列表。
    return list_dependency_names

# 从计划中收集所有具名子函数名称。
def _subfunction_names(plan: dict[str, Any]) -> list[str]:
    """返回计划中所有具名子函数名称。

    参数:
        plan: 当前阶段对应的实现计划。

    返回:
        按首次出现顺序收集的具名子函数名称列表。
    """

    # 结果列表按计划中的原始顺序保留子函数名称。
    list_subfunction_names: list[str] = []  # 计划中的具名子函数名称列表

    # 逐个扫描子函数定义,收集 name 字段。
    for subfunction_item in plan.get("subfunctions", []) or []:

        # 只有带 name 的字典子函数定义才参与收集。
        if isinstance(subfunction_item, dict) and subfunction_item.get("name"):

            # 把子函数名统一转成字符串。
            str_subfunction_name = str(  # 把子函数名称规范成可匹配的字符串
                subfunction_item["name"]  # 当前循环命中的子函数 name 字段
            )  # 当前子函数名称字符串

            # 子函数名称按首次出现顺序收集。
            _append_unique_str(list_subfunction_names, str_subfunction_name)

    # 返回具名子函数名称列表。
    return list_subfunction_names

# 从 stage verifier issue 文本中收集命中的子函数名。
def _suspects_from_stage_issues(
    list_plan_subfunction_names: list[str],
    stage_verification: dict[str, Any] | None,
) -> list[str]:
    """从 stage verifier issue 文本中提取可疑子函数。

    参数:
        list_plan_subfunction_names: 计划中所有具名子函数名称。
        stage_verification: stage verifier 输出的结构化 gate 结果。

    返回:
        在 issue message 中命中的子函数名称列表。
    """

    # 结果列表按首次命中顺序记录文本命中的子函数。
    list_stage_suspects: list[str] = []  # 由 stage issue message 命中的子函数列表

    # 缺少 stage gate 时无需继续扫描 issue 文本。
    if not isinstance(stage_verification, dict):

        # 返回空列表,表示当前没有可扫描的 stage issue 文本。
        return []

    # 顺序扫描 stage issues 的 message 字段,寻找子函数名命中。
    for issue_item in stage_verification.get("issues", []) or []:

        # 非字典 issue 无法稳定读取 message 字段。
        if not isinstance(issue_item, dict):

            # 跳过结构异常的 issue 条目。
            continue

        # 把 message 统一转成字符串,便于做包含匹配。
        str_issue_message = str(issue_item.get("message", ""))  # 当前 stage issue 的 message 正文

        # 逐个检查子函数名是否出现在当前 issue 文本中。
        for str_subfunction_name in list_plan_subfunction_names:

            # 文本命中子函数名时,说明该子函数值得优先排查。
            if str_subfunction_name in str_issue_message:

                # 把当前命中的子函数加入结果列表。
                _append_unique_str(list_stage_suspects, str_subfunction_name)

    # 返回 issue 文本命中的子函数列表。
    return list_stage_suspects

# 从子函数定义中收集 checkpoint 信号名集合。
def _checkpoint_signals(subfunction_item: dict[str, Any]) -> set[str]:
    """从单个子函数定义中提取 checkpoint 信号集合。

    参数:
        subfunction_item: 单个子函数的计划定义字典。

    返回:
        当前子函数声明过的 checkpoint 信号名称集合。
    """

    # 结果集合用于和 drift key 做高效的包含匹配。
    set_checkpoint_signals: set[str] = set()  # 当前子函数声明的 checkpoint 信号名称集合

    # 顺序扫描 semantic_checkpoints,提取其中声明的信号名。
    for checkpoint_item in subfunction_item.get("semantic_checkpoints", []) or []:

        # 非字典 checkpoint 无法安全读取 signals 列表。
        if not isinstance(checkpoint_item, dict):

            # 结构异常的 checkpoint 条目不参与信号回推。
            continue

        # 当前 checkpoint 中显式声明的信号列表可能为空。
        list_signals = checkpoint_item.get("signals", []) or []  # 当前 checkpoint 定义的信号列表

        # 把所有非空信号名统一加入集合,供 drift 匹配复用。
        for raw_signal in list_signals:

            # 信号名统一转成字符串,避免类型不一致。
            str_signal = str(raw_signal)  # 当前 checkpoint 信号名字符串

            # 非空信号名才值得作为 drift 匹配线索。
            if str_signal:

                # 记录当前 checkpoint 信号名,便于稍后匹配 drift key。
                set_checkpoint_signals.add(str_signal)

    # 返回当前子函数声明的 checkpoint 信号集合。
    return set_checkpoint_signals

# 判断单个子函数是否命中了任一 drift key。
def _matches_drift_keys(
    str_subfunction_name: str,
    set_checkpoint_signals: set[str],
    list_drift_keys: list[str],
) -> bool:
    """判断子函数名或其 checkpoint 信号是否命中任一 drift key。

    参数:
        str_subfunction_name: 当前被检查的子函数名称。
        set_checkpoint_signals: 当前子函数声明的 checkpoint 信号集合。
        list_drift_keys: 已去重并排序的 drift key 列表。

    返回:
        子函数名或任一 checkpoint 信号命中 drift key 时返回 True。
    """

    # 逐个扫描 drift key,寻找名称或信号级命中。
    for str_drift_key in list_drift_keys:

        # 子函数名直接命中 drift key 时,可视为高置信定位。
        if str_subfunction_name in str_drift_key:

            # 返回命中结果,避免继续扫描其他 drift key。
            return True

        # 再逐个检查 checkpoint 信号是否命中当前 drift key。
        for str_signal in set_checkpoint_signals:

            # 信号命中 drift key 时,同样说明该子函数值得优先排查。
            if str_signal and str_signal in str_drift_key:

                # 返回命中结果,避免继续做重复判断。
                return True

    # 所有 drift key 都未命中时返回假。
    return False

# 根据 issue 文本与 checkpoint 漂移推断可疑子函数。
def _suspect_subfunctions(
    plan: dict[str, Any],
    stage_verification: dict[str, Any] | None,
    semantic: dict[str, Any],
) -> list[str]:
    """返回最值得优先排查的可疑子函数列表。

    参数:
        plan: 当前阶段对应的实现计划。
        stage_verification: stage verifier 输出的结构化 gate 结果。
        semantic: 当前阶段提取出的语义执行摘要。

    返回:
        按定位证据优先级去重后的可疑子函数名称列表。
    """

    # 子函数名称清单会被 issue 文本扫描和 drift 匹配共同复用。
    list_plan_subfunction_names = _subfunction_names(  # 计划里所有具名子函数名称
        plan  # 先收集计划里所有具名子函数
    )  # 当前计划中所有具名子函数名称

    # 先利用 stage issue 文本拿到一批直观命中的候选子函数。
    list_suspects = _suspects_from_stage_issues(  # 先从 stage issue 文本抽第一批命中项
        list_plan_subfunction_names,  # 用计划里的子函数名逐个匹配 issue 文本
        stage_verification,  # stage gate 的 issue 列表是最直接的文本定位入口
    )  # 由 stage issue 文本直接命中的可疑子函数列表

    # checkpoint 漂移键用于做更细粒度的定位回推。
    list_drift_keys = _collect_drift_keys(  # 再利用 drift 键把候选范围继续收窄
        semantic  # drift 键通常能把问题指向更具体的检查点或子函数
    )  # 当前语义摘要暴露出的 drift key 列表

    # 存在漂移键时,再逐个对子函数做信号级匹配。
    if list_drift_keys:

        # 顺序扫描计划中的子函数定义,寻找和 drift key 最相关的对象。
        for subfunction_item in plan.get("subfunctions", []) or []:

            # 只有带 name 的字典子函数定义才值得继续匹配。
            if not isinstance(subfunction_item, dict) or not subfunction_item.get("name"):

                # 缺少名字或结构异常的子函数定义无法参与定位。
                continue

            # 统一字符串形式后,才能稳定和 drift key 做包含匹配。
            str_subfunction_name = str(  # 当前候选子函数的规范化名称
                subfunction_item["name"]  # 读取计划里声明的子函数 name 字段
            )  # 用于与 drift key 比对的子函数名

            # 先收集该子函数声明过的 checkpoint 信号集合。
            set_checkpoint_signals = _checkpoint_signals(  # 当前子函数声明过的 checkpoint 信号集合
                subfunction_item  # 当前子函数的计划定义字典
            )  # 该子函数声明过的 checkpoint 信号集合

            # 命中 drift key 时,把当前子函数加入可疑列表。
            if _matches_drift_keys(
                str_subfunction_name,
                set_checkpoint_signals,
                list_drift_keys,
            ):

                # 把 drift 证据回推到当前子函数,便于后续优先修复。
                _append_unique_str(list_suspects, str_subfunction_name)

    # 已定位到具体子函数时,直接返回收集结果。
    if list_suspects:

        # 返回按首次命中顺序收集的可疑子函数列表。
        return list_suspects

    # 没有具体子函数但存在漂移时,回退到当前计划名。
    if semantic.get("checkpoint_drift"):

        # 先把计划名统一转成字符串,用作最低粒度的定位兜底。
        str_plan_name = str(plan.get("name"))  # checkpoint 漂移存在但子函数未命中时的计划名兜底

        # 返回仅包含计划名的单元素列表。
        return [str_plan_name]

    # 缺少足够定位线索时返回空列表。
    return []
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall