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

View on GitHub
"""根据 workflow trace 生成下一轮 prompt 补丁和可复用记忆。"""

# 延迟注解解析,避免运行期求值嵌套泛型。
from __future__ import annotations

# 标准库提供路径对象和 JSON-like 负载类型标注。
from pathlib import Path
from typing import Any

# 运行时模块提供计划规范化和 trace 读取能力。
from scripts.python.workflow.planning import decompose_spec
from scripts.python.workflow.trace import read_trace

# trace 文本约束规则保持旧版顺序,确保 prompt patch 输出稳定。
CONSTRAINT_RULES: tuple[tuple[tuple[str, ...], str], ...] = (  # trace 关键词到 prompt 约束的映射表
    (
        ("dependency_issue", "undefined module", "undefined reference", "not declared"),  # 依赖或声明缺失迹象
        (
            "Re-check subfunction interface compatibility, dimensions, and dependency outputs "
            "before regenerating the failing module."
        ),  # 依赖失败后复核上下游接口的 prompt 约束
    ),
    (
        ("testbench", "main() entry point"),  # 测试平台或入口函数相关诊断
        (
            "Generate or repair a self-checking testbench with explicit PASS/FAIL behavior "
            "and coverage for every behavior item."
        ),  # testbench 失败后要求补齐自检覆盖的 prompt 约束
    ),
    (
        ("toolchain_issue", "required tool", "failed to start", "timed out"),  # 外部工具不可用或超时迹象
        (
            "Separate toolchain availability/configuration failures from code edits; "
            "only rewrite code when the tool output identifies code errors."
        ),  # 工具链异常和代码错误分流的 prompt 约束
    ),
    (
        ("placeholder", "todo", "fixme", "ellipsis"),  # 未完成代码占位痕迹
        "Remove all placeholders and produce complete executable code for every manifest file.",  # 完整实现约束
    ),
    (
        ("spec_issue", "expected output file is missing"),  # 规格或产物覆盖缺口
        (
            "Audit the plan outputs and evidence before code regeneration; "
            "missing requested files indicate a plan or manifest coverage issue."
        ),  # 缺失产物先回查计划覆盖的 prompt 约束
    ),
    (
        ("reviewability", "comment"),  # 注释可审查性相关信号
        (
            "Preserve the requested comment language and add same-line semantic comments for "
            "ports, signals, always blocks, assigns, testbench checks, and construct end lines."
        ),  # RTL 可审查性不足时使用的注释补强约束
    ),
    (
        ("fsm", "state register", "next-state"),  # 状态机结构缺口
        (
            "For RTL regeneration, use a three-block FSM with explicit state register, "
            "next-state logic, and output logic sections."
        ),  # 状态机结构失败后的 RTL 分块约束
    ),
    (
        ("semantic model", "run_tests"),  # Python 参考模型合同信号
        (
            "Preserve the Python semantic model API and mirror its deterministic "
            "verification vectors in the downstream testbench."
        ),  # 参考模型合同漂移时的向量同步约束
    ),
    (
        ("semantic output drift", "wrong_final_output"),  # 最终输出语义漂移
        (
            "When a final output mismatches the Python oracle, restate the exact output contract "
            "and regenerate only the logic responsible for those drift keys."
        ),  # 最终输出漂移时限制重生成范围的约束
    ),
    (
        ("checkpoint drift", "checkpoint_divergence"),  # 中间检查点漂移
        (
            "Preserve and compare intermediate checkpoints so the next attempt can localize "
            "the mismatch before the final output stage."
        ),  # 中间检查点漂移后的定位约束
    ),
    (
        ("case order drift", "case_order_drift"),  # 用例顺序漂移
        "Keep case ids and transcript order stable across Python oracle, vectors, and Verilog testbench output.",  # 用例顺序稳定约束
    ),
    (
        ("weak_test_oracle", "augment_tests"),  # 测试 oracle 覆盖不足
        "Strengthen boundary cases, negative cases, and checkpoint coverage before escalating to human debugging.",  # 测试增强约束
    ),
    (
        ("ambiguous_spec_rule",),  # 规格规则冲突
        (
            "Call out the conflicting spec rule explicitly and preserve the ambiguity "
            "for structured human resolution instead of guessing."
        ),  # 规格冲突进入人工确认前的保留约束
    ),
    (
        ("needs_human_intervention", "ask_human"),  # 人工介入信号
        (
            "Summarize the unresolved ambiguity as a precise hardware-design question "
            "before another generation attempt."
        ),  # 人工介入后收敛问题描述的约束
    ),
)

# 记忆签名规则保持旧版优先级,避免历史 trace 产出的 memory 顺序漂移。
SIGNATURE_RULES: tuple[dict[str, Any], ...] = (  # 供_memory_entries把失败事件转换为可复用prompt记忆约束的规则序列
    {
        "source_terms": ("dependency_issue",),  # 依赖失败事件来源匹配词
        "text_terms": ("undefined module", "interface"),  # 接口或未定义模块文本
        "signature": "interface_or_dependency_mismatch",  # 接口依赖签名
        "constraint": (  # 接口依赖签名对应的 prompt memory 约束
            "Reconfirm upstream/downstream port names, dimensions, and subfunction dependency "
            "outputs before code generation."
        ),  # 接口依赖失败写入 memory 的复核提醒
    },
    {
        "source_terms": ("testbench_issue",),  # 测试平台失败事件来源匹配词
        "text_terms": ("testbench", "pass behavior", "fail behavior"),  # 自检行为文本
        "signature": "testbench_or_reference_vector_gap",  # testbench 覆盖签名
        "constraint": (  # testbench 覆盖签名对应的 prompt memory 约束
            "Generate self-checking PASS/FAIL tests that mirror the semantic model vectors "
            "and mention required verification cases."
        ),  # testbench 覆盖缺口写入 memory 的自检提醒
    },
    {
        "source_terms": (),  # 该规则只依赖 trace 文本
        "text_terms": ("semantic model", "run_tests"),  # 参考模型 API 文本
        "signature": "reference_model_contract_gap",  # 参考模型合同签名
        "constraint": "Preserve `run_tests()` and the Python CLI entrypoint, then mirror its vectors downstream.",  # 参考模型入口缺口写入记忆的保持约束
    },
    {
        "source_terms": (),  # 注释可审查性来自文本线索
        "text_terms": ("reviewability", "comment"),  # 注释质量相关文本
        "signature": "comment_reviewability_gap",  # 注释审查签名
        "constraint": (  # 注释可审查签名对应的 prompt memory 约束
            "Use the requested comment language and add same-line semantic comments for every "
            "RTL declaration, block, assign, construct end, and testbench case check."
        ),  # 注释审查失败写入 memory 的 RTL 注释提醒
    },
    {
        "source_terms": (),  # FSM 结构来自 trace 描述
        "text_terms": ("fsm", "state register", "next-state"),  # 状态机结构文本
        "signature": "rtl_fsm_structure_gap",  # FSM 结构签名
        "constraint": (  # FSM 结构签名对应的 prompt memory 约束
            "Use three-block RTL FSM style with state register, next-state logic, "
            "and output logic labels."
        ),  # FSM 结构缺口写入 memory 的样式提醒
    },
    {
        "source_terms": ("toolchain_issue",),  # 工具链类 error_sources
        "text_terms": ("required tool",),  # 缺少工具文本
        "signature": "toolchain_unavailable_or_failed",  # 工具链失败签名
        "constraint": (  # 工具链失败签名对应的 prompt memory 约束
            "Separate tool availability failures from code edits and rerun with "
            "the required readiness tool installed."
        ),  # 工具链失败写入 memory 的执行边界提醒
    },
    {
        "source_terms": ("spec_issue",),  # 规格失败事件来源匹配词
        "text_terms": ("evidence",),  # 证据覆盖文本
        "signature": "spec_or_evidence_gap",  # 规格证据签名
        "constraint": "Audit evidence coverage and requested outputs before regenerating implementation files.",  # 证据覆盖记忆
    },
    {
        "source_terms": (),  # 输出漂移来自语义报告文本
        "text_terms": ("semantic output drift", "wrong_final_output"),  # 最终输出不匹配文本
        "signature": "wrong_final_output",  # 最终输出漂移签名
        "constraint": (  # 最终输出漂移签名对应的 prompt memory 约束
            "Reconfirm case outputs against the Python oracle and focus regeneration "
            "on the drift keys reported by semantic validation."
        ),  # 最终输出漂移写入 memory 的重生成范围提醒
    },
    {
        "source_terms": (),  # checkpoint 漂移来自语义报告文本
        "text_terms": ("checkpoint drift", "checkpoint_divergence"),  # checkpoint 不一致文本
        "signature": "checkpoint_divergence",  # checkpoint 漂移签名
        "constraint": (  # checkpoint 漂移签名对应的 prompt memory 约束
            "Preserve intermediate checkpoints and use them to localize where the Verilog "
            "behavior diverges from the Python oracle."
        ),  # checkpoint 漂移写入 memory 的定位提醒
    },
    {
        "source_terms": (),  # case 顺序漂移来自 trace 文本
        "text_terms": ("case order drift", "case_order_drift"),  # 用例顺序不一致文本
        "signature": "case_order_drift",  # 用例顺序签名
        "constraint": (  # case 顺序漂移签名对应的 prompt memory 约束
            "Keep case ordering and case ids stable between the semantic contract "
            "and the Verilog transcript."
        ),  # 用例顺序漂移写入 memory 的排序提醒
    },
    {
        "source_terms": (),  # oracle 强度来自 trace 文本
        "text_terms": ("weak_test_oracle", "augment_tests"),  # 测试增强文本
        "signature": "weak_test_oracle",  # 测试 oracle 签名
        "constraint": "Add stronger boundary, negative, and checkpoint cases before escalating to a human.",  # 测试增强记忆
    },
    {
        "source_terms": (),  # 规格歧义来自结构化文本
        "text_terms": ("ambiguous_spec_rule",),  # 歧义规则文本
        "signature": "ambiguous_spec_rule",  # 规格歧义签名
        "constraint": (  # 规格歧义签名对应的 prompt memory 约束
            "Preserve the spec conflict explicitly and route it into structured human intervention "
            "rather than inferring behavior."
        ),  # 规格歧义写入 memory 的人工介入提醒
    },
)

# optimize_prompt_from_trace 将 trace 诊断整理成下一轮 prompt patch。
def optimize_prompt_from_trace(trace_path: Path, plan: dict[str, Any]) -> str:
    """根据历史 trace 为下一轮 staged generation 构造 prompt patch。

    参数:
        trace_path: workflow trace JSONL 或 JSON 文件路径。
        plan: 已有 codegen plan 或规格字典。

    返回:
        可追加到下一轮 prompt 的 Markdown 补丁文本。
    """

    # trace 事件提供失败模式和恢复线索。
    list_events = read_trace(trace_path)  # 历史 workflow 事件

    # 规范化计划用于稳定读取设计名和子功能列表。
    dict_normalized_plan = decompose_spec(plan)  # 规范化后的 RTL 生成计划

    # 约束列表按规则顺序去重,保持 prompt patch 可预测。
    list_constraints = _derive_constraints(list_events)  # 下一轮 prompt 约束

    # 子功能摘要在 Context 区域显示,帮助人工确认覆盖范围。
    str_subfunctions = _subfunction_summary(dict_normalized_plan)  # 子功能名称摘要

    # prompt patch 头部保持旧版 Markdown wire shape。
    list_lines = [  # 供optimize_prompt_from_trace拼接返回Markdown补丁正文的行序列
        f"# Prompt patch: {dict_normalized_plan['name']}",  # 标识目标设计名称的补丁标题行
        "",  # 标题和正文之间的 Markdown 空行
        "Apply these incremental constraints to the next staged generation prompt.",  # 固定说明文本
        "",  # 说明和约束标题之间的 Markdown 空行
        "## Targeted Constraints",  # 约束章节标题
        "",  # 约束标题后的 Markdown 空行
    ]

    # 有具体约束时逐条追加,空约束时保留旧版兜底文本。
    if list_constraints:

        # 约束条目必须保持规则匹配顺序。
        list_lines.extend(f"- {str_constraint}" for str_constraint in list_constraints)

    # trace 没有命中失败模式时不强行发明 prompt 约束。
    else:

        # 兜底约束明确要求保留既有 staged prompt 合同。
        list_lines.append(
            "- No concrete failure pattern was found; keep the existing staged prompt contract unchanged."
        )

    # Context 区域汇总 trace 数量、子功能和输出合同边界。
    list_lines.extend(
        [
            "",  # 约束列表和 Context 标题之间的 Markdown 空行
            "## Context",  # 上下文章节标题
            "",  # Context 标题后的 Markdown 空行
            f"- Trace events analyzed: {len(list_events)}",  # trace 事件数量
            f"- Subfunctions: {str_subfunctions}",  # 子功能摘要
            "- Preserve exact manifest/code-fence output contract.",  # 输出合同保护提醒
        ]
    )

    # 返回带末尾换行的 Markdown 文本,保持旧版 CLI 输出习惯。
    return "\n".join(list_lines) + "\n"

# build_prompt_memory 将 trace 诊断转换为 workflow 可复用记忆。
def build_prompt_memory(trace_path: Path, plan: dict[str, Any]) -> dict[str, Any]:
    """根据 trace 和计划生成 prompt memory 结构。

    参数:
        trace_path: workflow trace JSONL 或 JSON 文件路径。
        plan: 已有 codegen plan 或规格字典。

    返回:
        包含版本、目标和记忆条目的字典。
    """

    # prompt memory 只读取能复用到后续生成的失败线索。
    list_events = read_trace(trace_path)  # prompt memory 签名抽取的输入事件

    # 顶层 memory 字段从规范化计划读取,避免原始 spec 形态差异。
    dict_normalized_plan = decompose_spec(plan)  # memory 顶层名称和目标来源

    # 返回结构保持旧版 prompt memory wire shape。
    return {
        "version": 1,  # memory 结构版本
        "name": dict_normalized_plan["name"],  # 设计或计划名称
        "target": dict_normalized_plan["target"],  # 生成目标类型
        "entries": _memory_entries(list_events, dict_normalized_plan),  # 去重后的 trace 记忆条目
    }

# _derive_constraints 负责从 trace 文本中抽取 prompt 约束。
def _derive_constraints(list_events: list[dict[str, Any]]) -> list[str]:
    """从历史事件文本中提取下一轮 prompt 约束。

    参数:
        list_events: read_trace 返回的 workflow 事件列表。

    返回:
        按规则顺序去重后的英文 prompt 约束列表。
    """

    # 所有事件统一转成小写文本,兼容旧逻辑的字符串匹配方式。
    str_joined_events = "\n".join(str(dict_event).lower() for dict_event in list_events)  # trace 拼接文本

    # prompt patch 约束按 CONSTRAINT_RULES 命中顺序累积。
    list_constraints: list[str] = []  # 下一轮生成 prompt 中追加的约束条目

    # 逐条匹配历史规则,保持旧版约束文本和顺序。
    for tuple_keywords, str_constraint in CONSTRAINT_RULES:

        # 当前关键词组命中时追加对应约束。
        if _contains_any(str_joined_events, tuple_keywords):

            # 去重追加避免多个关键词命中同一约束时重复输出。
            _append_unique(list_constraints, str_constraint)

    # 返回 prompt patch 使用的约束列表。
    return list_constraints

# _memory_entries 负责把 trace 事件展开成去重记忆条目。
def _memory_entries(list_events: list[dict[str, Any]], dict_plan: dict[str, Any]) -> list[dict[str, Any]]:
    """把 trace 事件转换为按子功能和阶段索引的记忆条目。

    参数:
        list_events: read_trace 返回的 workflow 事件列表。
        dict_plan: decompose_spec 输出的规范化计划。

    返回:
        去重后的 prompt memory entries 列表。
    """

    # 子功能列表缺省为星号,保留旧版全局记忆语义。
    list_subfunctions = _plan_subfunctions(dict_plan)  # prompt memory 适用的子功能名称

    # entries 先完整收集,再按 subfunction/stage/signature 去重。
    list_entries: list[dict[str, Any]] = []  # 原始记忆条目列表

    # 每个 trace 事件可能贡献多个签名。
    for dict_event in list_events:

        # 事件文本沿用旧版 str(event).lower() 匹配语义。
        str_joined_event = str(dict_event).lower()  # 单个事件小写文本

        # 事件签名规则输出错误签名和约束文本。
        list_signatures = _event_signatures(dict_event, str_joined_event)  # 当前事件命中的签名

        # 每个签名生成一条 memory entry。
        for str_signature, str_constraint in list_signatures:

            # 记忆条目保持 workflow state 使用的字段形状。
            list_entries.append(
                {
                    "subfunction": dict_event.get("subfunction") or list_subfunctions[0],  # 事件归属子功能
                    "stage": _event_stage(dict_event),  # 事件归属阶段或 readiness
                    "attempt_id": dict_event.get("attempt_id"),  # 原始尝试标识
                    "error_signature": str_signature,  # 可复用错误签名
                    "constraint": str_constraint,  # 下一轮 prompt 约束文本
                }
            )

    # 去重后返回给 prompt memory 写出流程。
    return _dedupe_entries(list_entries)

# _event_signatures 根据单个事件匹配可复用错误签名。
def _event_signatures(dict_event: dict[str, Any], str_joined_event: str) -> list[tuple[str, str]]:
    """提取单个 trace 事件命中的记忆签名。

    参数:
        dict_event: 单条 workflow trace 事件。
        str_joined_event: 事件字典转成小写后的文本。

    返回:
        由 error_signature 和 constraint 组成的二元组列表。
    """

    # error_sources 只有列表形态时才参与源分类匹配。
    set_sources = set(dict_event.get("error_sources", []) or [])  # 当前事件错误来源集合

    # 签名输出按 SIGNATURE_RULES 顺序累积。
    list_signatures: list[tuple[str, str]] = []  # 当前事件命中的签名列表

    # 逐条匹配来源和文本关键词,保持旧版优先级。
    for dict_rule in SIGNATURE_RULES:

        # 规则命中后生成一条 prompt memory 签名。
        if _signature_rule_matches(dict_rule, set_sources, str_joined_event):

            # 签名和约束文本来自静态规则表,不做运行时改写。
            tuple_signature = (dict_rule["signature"], dict_rule["constraint"])  # 记忆签名和约束

            # 当前事件命中的签名进入返回列表。
            list_signatures.append(tuple_signature)

    # 返回当前事件贡献的所有签名。
    return list_signatures

# _signature_rule_matches 判断签名规则是否命中当前事件。
def _signature_rule_matches(dict_rule: dict[str, Any], set_sources: set[Any], str_joined_event: str) -> bool:
    """判断一条签名规则是否匹配当前 trace 事件。

    参数:
        dict_rule: SIGNATURE_RULES 中的一条规则。
        set_sources: 当前事件的 error_sources 集合。
        str_joined_event: 当前事件的小写文本。

    返回:
        来源或文本关键词任一命中时返回 True。
    """

    # source_terms 为空时只依赖文本关键词。
    tuple_source_terms = tuple(dict_rule.get("source_terms", ()))  # 规则错误来源关键词

    # text_terms 为空时只依赖 error_sources。
    tuple_text_terms = tuple(dict_rule.get("text_terms", ()))  # 规则事件文本关键词

    # 来源命中沿用旧逻辑中的 error_sources 判断。
    bool_source_matched = bool(tuple_source_terms) and any(  # error_sources 是否命中该签名规则
        str_source in set_sources  # 当前来源是否在事件来源集合中
        for str_source in tuple_source_terms  # 规则要求的来源关键词
    )

    # 文本命中沿用旧逻辑中的 str(event).lower() 判断。
    bool_text_matched = _contains_any(str_joined_event, tuple_text_terms)  # 文本是否命中

    # 来源或文本任一路径命中即可生成签名。
    return bool_source_matched or bool_text_matched

# _plan_subfunctions 解析计划中的子功能名称列表。
def _plan_subfunctions(dict_plan: dict[str, Any]) -> list[str]:
    """从规范化计划中提取 prompt memory 适用的子功能名称。

    参数:
        dict_plan: decompose_spec 输出的规范化计划。

    返回:
        子功能名称列表;没有可用名称时返回 ``["*"]``。
    """

    # 子功能名只从 dict 条目提取,兼容旧版过滤逻辑。
    list_names = [
        str(dict_item.get("name"))  # 子功能名称
        for dict_item in dict_plan.get("subfunctions", [])  # 规范化计划子功能列表
        if isinstance(dict_item, dict) and dict_item.get("name")  # 只保留具名子功能
    ]  # 已解析子功能名称

    # 没有子功能时返回全局星号,保持旧版默认行为。
    return list_names or ["*"]

# _subfunction_summary 生成 prompt patch 中展示的子功能摘要。
def _subfunction_summary(dict_plan: dict[str, Any]) -> str:
    """生成 prompt patch Context 区域使用的子功能摘要文本。

    参数:
        dict_plan: decompose_spec 输出的规范化计划。

    返回:
        以逗号分隔的子功能名称字符串。
    """

    # 子功能摘要复用 memory 的解析规则,避免两个路径默认值不一致。
    list_subfunctions = _plan_subfunctions(dict_plan)  # prompt patch 展示的子功能名称

    # 返回 Markdown 列表项中使用的逗号分隔摘要。
    return ", ".join(list_subfunctions)

# _event_stage 解析 memory entry 的阶段字段。
def _event_stage(dict_event: dict[str, Any]) -> Any:
    """解析 trace 事件所属阶段或 readiness。

    参数:
        dict_event: 单条 workflow trace 事件。

    返回:
        事件中的 stage、readiness、event 或 ``unknown``。
    """

    # stage/readiness/event 按旧版优先级依次兜底。
    return dict_event.get("stage") or dict_event.get("readiness") or dict_event.get("event") or "unknown"

# _contains_any 统一处理小写文本的关键词匹配。
def _contains_any(str_text: str, tuple_keywords: tuple[str, ...]) -> bool:
    """判断文本是否包含任一关键词。

    参数:
        str_text: 已按调用方需要归一化的待检索文本。
        tuple_keywords: 需要依次匹配的关键词集合。

    返回:
        任一关键词出现在文本中时返回 True。
    """

    # any 保持短路匹配,避免无意义地扫描后续关键词。
    return any(str_keyword in str_text for str_keyword in tuple_keywords)

# _append_unique 保持约束列表的稳定去重追加语义。
def _append_unique(list_values: list[str], str_value: str) -> None:
    """向字符串列表追加不存在的值。

    参数:
        list_values: 需要原地更新的字符串列表。
        str_value: 候选字符串值。

    返回:
        无。
    """

    # 只有首次命中才写入,保持旧版 add helper 的去重行为。
    if str_value not in list_values:

        # 原地追加让调用方持有的列表保持同步。
        list_values.append(str_value)

# _dedupe_entries 按子功能、阶段和错误签名去重。
def _dedupe_entries(list_entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
    """去除重复的 prompt memory entry。

    参数:
        list_entries: 原始 prompt memory 条目列表。

    返回:
        保留首次出现顺序的去重条目列表。
    """

    # seen 记录已经输出过的 memory 业务键。
    set_seen: set[tuple[Any, Any, Any]] = set()  # 已出现的记忆去重键

    # 去重结果按输入顺序保存首次出现的条目。
    list_deduped: list[dict[str, Any]] = []  # 保留首次出现顺序的 memory 条目

    # 逐条检查 memory entry 的业务唯一键。
    for dict_entry in list_entries:

        # memory 去重仍使用旧版的三字段业务键。
        tuple_key = (  # 子功能、阶段和签名组成 memory 去重键
            dict_entry.get("subfunction"),  # 记忆适用子功能
            dict_entry.get("stage"),  # workflow 阶段或 readiness 名称
            dict_entry.get("error_signature"),  # 触发 prompt 记忆复用的错误签名
        )

        # 已见过的业务键直接跳过,保留首次条目。
        if tuple_key in set_seen:

            # 跳过重复条目,不改变输出顺序。
            continue

        # 记录当前业务键,避免后续重复输出。
        set_seen.add(tuple_key)

        # 首次出现的条目保留原字段内容。
        list_deduped.append(dict_entry)

    # 返回去重后的 memory 条目。
    return list_deduped
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