VeriGen 是一个 Verilog 代码生成智能体，围绕需求理解 → 代码生成 → 仿真验证 → 调试优化的完整闭环，把自然语言规格转成可仿真、可综合、可调试的 RTL 设计。

本仓库以 pi agent harness 为底座，在其 TypeScript agent runtime、CLI/TUI、tool calling、多模型接入和扩展机制之上，加入以下 Verilog/RTL 专用能力：

• Spec-Anchored KG：用端口契约和模块关系约束生成，减少接口幻觉
• Verilog Playbook RAG：沉淀工程化知识和历史修复规则
• EDA ToolRunner：统一接入 iverilog/vvp、Verilator、Yosys、Himasim 等仿真与综合工具
• AST 波形追踪：仿真失败后的确定性定位步骤
• Graphify 上下文导航：模型可自主调用的仓库/文档导航
• 随 npm 分发的 Python Verilog analysis worker：基于魔改 pyverilog fork

VeriGen 面向需求理解 → 代码生成 → 仿真验证 → 调试优化的完整闭环：

                 ┌──────────────────────────────┐
                 │       需求 / 规格输入          │
                 │  (文本 / 时序图 / PDF / 图片)   │
                 └────────────┬─────────────────┘
                              ▼
                 ┌──────────────────────────────┐
                 │       Spec-Anchored KG        │
                 │    (端口契约 / 模块关系约束)    │
                 └────────────┬─────────────────┘
                              ▼
                 ┌──────────────────────────────┐
                 │         RTL 代码生成           │
                 │    (Planner + Coder Agent)     │
                 └────────────┬─────────────────┘
                              ▼
                 ┌──────────────────────────────┐
                  │    仿真 / 综合 / lint 验证      │
                  │  iverilog │ Verilator │ Yosys  │
                  │  Himasim │ Quartus (Tcl)       │
                 └────────────┬─────────────────┘
                              │
                ┌─────────────┴─────────────┐
                ▼                           ▼
         ┌──────────────┐          ┌──────────────┐
         │   通过        │          │   失败        │
         └──────┬───────┘          └──────┬───────┘
                │                         ▼
                │          ┌──────────────────────────┐
                │          │     失败定位与波形追踪      │
                │          │   AST 波形追踪 + Debugger  │
                │          └────────────┬─────────────┘
                │                         │
                │          ┌──────────────▼───────────┐
                │          │     定向修复 (Debugger)    │
                │          │  Playbook RAG + 历史规则   │
                │          └──────────────┬───────────┘
                │                         │
                └──────────┬──────────────┘
                           ▼
                 ┌──────────────────────────────┐
                 │          输出交付              │
                 │  可仿真、可综合、可调试的 RTL   │
                 └──────────────────────────────┘

核心原则：

• 闭环验证：RTL 不是生成出来就结束，必须经过仿真与综合验证。
• 结构化中间物：规格、KG、trace、修复建议都要机器可读。
• KG 锚定：用端口契约和模块关系约束生成，减少接口幻觉。
• 工程化知识：用 Verilog Playbook 和历史修复规则，而不是把原始规范全文塞进上下文。
• 极简常驻上下文：启动时只常驻 VeriGen system prompt 和 extension；Planner、Coder、Verifier、Debugger 与 Playbook 规则按需注入，最小化 token 消耗。
• 多模型适配：支持配置多种大模型，包括国产模型，支持私有化部署。

VeriGen TypeScript 主体
  pi-coding-agent / pi-agent-core / pi-ai / pi-tui
  ├─ Minimal system prompt + on-demand Planner/Coder/Verifier/Debugger context
  ├─ Spec-Anchored KG        (graphology + zod)
  ├─ Verilog Playbook RAG    (vectra)
  ├─ Graphify Context        (repo/docs context graph)
  ├─ Context Router          (裁剪 trace / graph / playbook 结果)
  └─ VerilogAnalysis client  (child_process + JSONL)

受管 Python Worker
  packages/verilog-analysis
  ├─ pyverilog 魔改 fork      (vendor/pyverilog)
  ├─ parse_ast
  ├─ build_controlflow
  ├─ trace_waveform
  └─ identify_seq_element

外部工具
  iverilog / vvp / verilator / yosys / himasim / quartus (Tcl) / FPGA vendor tools

两条设计约定：

• 波形追踪不是通用工具。它是仿真失败后的确定性步骤：Verifier 发现失败，编排器调用 trace，Context Router 裁剪结果，再交给 Debugger 生成修复建议。
• Graphify 是例外。它默认启用，作为模型可自主调用的仓库/文档导航工具，用来决定"该读哪些文件、prompt、规则和设计文档"。它不替代 pyverilog 的 RTL 语义分析。

基础依赖：

• Node.js >=22.19.0 和 npm
• iverilog / vvp

安装脚本会下载 bundled uv/uvx，并由 uv 自动拉取受管 Python 3.11；用户不需要预先安装 uv 或 Python。

推荐后续接入：Verilator、Yosys、Himasim，以及 FPGA vendor tools（Vivado、Quartus 或国产工具链）。

Windows PowerShell 一键安装：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned -Force
irm https://raw.githubusercontent.com/rongxinzy/VeriGen/main/packages/verigen/install.ps1 | iex

该脚本从 Node.js 冷启动开始：若缺少 Node.js/npm 或版本不满足，会自动安装 Chocolatey，再执行 choco install nodejs --version="24.16.0" -y；随后从 Astral 官方 release 下载并校验 uv.exe/uvx.exe，最后执行 npm install -g verigen@latest --registry https://registry.npmmirror.com。脚本也会提示安装 Git Bash，并在 npm 安装后预热 Python worker venv 和依赖。

通用 npm 安装：

npm install -g verigen@latest

verigen doctor          # 环境诊断
verigen worker-smoke    # 验证 Python worker 可用
verigen agent           # 进入 VeriGen agent

安装脚本会提前下载 bundled uv/uvx 并创建 Python worker cache venv；如果预热失败，首次运行时 CLI 仍会自动下载 bundled uv 并把包内 Python worker 自举到受管 cache venv，无需手动配置 Python 环境（详见 npm 分发策略）。

# 安装依赖
npm install --ignore-scripts

# 仓库门禁
npm run check

# VeriGen 子包测试
cd packages/verigen
node --test test/*.test.ts

# Python worker 本地运行
cd packages/verilog-analysis
uv sync --frozen
uv run verigen-verilog-analysis

# 生成本地 npm tarball
cd packages/verigen
npm pack --pack-destination /tmp/verigen-pack

# 临时安装
rm -rf /tmp/verigen-preview /tmp/verigen-preview-cache
npm install -g --prefix /tmp/verigen-preview /tmp/verigen-pack/verigen-0.79.2.tgz --ignore-scripts

# 验证安装
/tmp/verigen-preview/bin/verigen --help
VERIGEN_CACHE_DIR=/tmp/verigen-preview-cache /tmp/verigen-preview/bin/verigen doctor
VERIGEN_CACHE_DIR=/tmp/verigen-preview-cache /tmp/verigen-preview/bin/verigen worker-smoke

worker-smoke 成功表示 npm 包内 Python worker、vendored pyverilog 和 uv cache venv 已经跑通。

以下按功能分组（省略安装前缀路径）：

# Agent 入口与模式
verigen agent --dry-run            # 预览 VeriGen 专属 agent 启动参数
verigen mode                       # 查看 VeriGen mode/profile

# 诊断与冒烟
verigen doctor                     # 环境诊断（含修复建议）
verigen worker-smoke               # Python worker 冒烟
verigen release-smoke              # release checklist
verigen release-smoke --verify-local | --verify-dist | --pack-install-plan

# 质量评测
verigen quality-probe list
verigen quality-probe run --case l0-mux2 --live --run-tools
verigen quality-probe fix-loop --case l0-mux2
verigen eval-suite --suite smoke   # pass@1、收敛率、修复轮次等指标

# 波形追踪与 TUI
verigen trace-demo
verigen tui-preview trace-demo
verigen tui-preview quality-probe --case l0-mux2 --live

# Graphify
verigen graphify-status
verigen graphify-query "waveform debugger trace" --json
verigen graphify-path docs/PDD-VeriGen.md packages/verigen/src/spec-kg.ts --json

# 板级流程（mock/dry-run）
verigen board-smoke --smoke blink_led
verigen hardware-flow --template blink_led

# 状态面板 / dogfood workbench
verigen product-workbench                 # 内部 dogfood/debug dashboard
verigen product-preview --with-smoke [--tui]
verigen product-preview --provider-page | --profiles
verigen product-preview --report --output /tmp/verigen-preview-report.md
verigen product-template --id uart_loopback --output /tmp/verigen-uart-template

ToolRunner 支持 Quartus FPGA 工具链的 Tcl 自动化全流程：

# 工程创建 + 综合 + 布局布线 + 时序分析
verigen tool-runner quartus --rtl top.v

# 分阶段执行
verigen tool-runner quartus --rtl top.v --stage map       # 只综合
verigen tool-runner quartus --rtl top.v --stage fit       # 只布局布线
verigen tool-runner quartus --rtl top.v --stage sta       # 只时序分析
verigen tool-runner quartus --rtl top.v --stage compile   # 全流程

# 板级编程
verigen tool-runner quartus --stage pgm --sof output.sof --cable USB-Blaster

# 指定器件与版本
verigen tool-runner quartus --rtl top.v --family "Cyclone V" --device 5CGXFC7C7F23C8N \
  --rev PRODUCTION_1.0 --64bit --jvm-heap 4096M --lic 27000@license-server

quartus_sh 生成的 Tcl 脚本使用 project_new / project_open + execute_module -tool 驱动编译，输出标准 EdaToolRunResult，错误解析支持 Error (XXXXX): 和 Critical Warning 格式。

verigen agent 是进入 pi coding-agent 的 VeriGen 专属入口。它会加载：

• verigen-system.md 作为 system prompt
• VeriGen extension，提供模型配置、Graphify 工具、状态面板和按需上下文命令

它不会在启动时把 Planner/Coder/Verifier/Debugger prompt 或完整 Playbook skill 注入 system/context。需要专家 phase 时，在 TUI 内运行：

/verigen-phase planner|coder|verifier|debugger [task]
/verigen-rules <query>

对明显的 RTL/Verilog 任务，extension 会在模型调用前自动注入一个小型 phase/rule 上下文；/verigen-phase 用于显式指定或覆盖 phase，/verigen-rules 只检索并注入相关规则。

运行时委托给原 pi CLI，因此保留 pi 的交互式对话、工具调用、会话、输入框和 / 指令引用手感。默认会加载内置 VeriGen extension，但不会展示完整 workbench；只有无可用模型等关键状态，或用户显式运行 /verigen-workbench show 时，才会在 editor 下方显示只读状态面板。该面板默认只显示模型状态、Python/uv 状态、当前任务、最近问题和下一步命令；/verigen-workbench details 才展开 logs、replay、board 和 report 摘要。外部也可通过 verigen/coding-agent-extension 或 installVerigenCodingAgentExtension() 挂入 coding-agent widget/custom message renderer。

生成仓库上下文图：

uvx --from graphifyy graphify update . --no-cluster

缺少 graphify-out/graph.json 时，Graphify 命令会返回 stale_or_missing_index，这是可恢复状态，不阻断 worker 或 doctor。

Codegen Quality Probe 支持配置任意兼容的 LLM 端点测试 Verilog 生成质量：

export VERIGEN_TEST_LLM_PROVIDER=anthropic     # 或 openai-completions / openrouter 等
export VERIGEN_TEST_LLM_BASE_URL=http://<host>:<port>
export VERIGEN_TEST_LLM_MODEL=<model-id>
export VERIGEN_TEST_LLM_API_KEY=<local-secret>

兼容实现如果要求 OpenAI 风格路径，可把 base URL 加上 /v1 后缀。API key 不应写入 README、docs、测试 fixture 或 commit。

• quality-probe run --live 把 Coder prompt 发给配置的端点；--run-tools 用 ToolRunner 对生成 RTL 执行 iverilog/vvp compile/sim，返回结构化 tool result（含仿真通过性、测试覆盖率）。Verilator lint、Yosys synth 和 Himasim profile 已有统一结果 schema；缺工具时返回 missing_tool。
• quality-probe fix-loop 串起 Planner/Coder/Verifier/Debugger 四 Agent，最多 3 轮。默认 dry-run 用脚本化候选 RTL 先制造一次仿真失败，再由 Debugger repair prompt 驱动下一轮修复；--live 把每轮 Coder prompt 发给配置端点。

verigen 发布时包含 TypeScript 编译产物、verigen CLI、.pi prompt/rule 资产、Python worker 源码和 vendor/pyverilog 魔改 fork；不包含 bundled uv/uvx native tools、.venv、wheelhouse、Python cache、Dockerfile 或 PyPI 私有包。

安装脚本会从 Astral 官方 release 下载当前平台的 uv/uvx 到 dist/native-tools/<platform>/。如果用户绕过安装脚本直接运行 npm install -g verigen@latest，首次需要 Python worker 或 Graphify uvx 时，CLI 会自动补下载 bundled uv/uvx；之后使用该 bundled uv 从 npm 包内本地路径安装 worker 到受管 cache venv。第三方 Python 依赖从 PyPI 安装，pyverilog==1.3.0+verigen 从本地 vendor/pyverilog 安装。

当前已完成以下能力覆盖：

• 基础设施：魔改 pyverilog fork 独立运行、Python analysis worker（JSONL RPC）、TypeScript 客户端、Spec KG / Playbook RAG / Graphify 迁移、npm 打包与 uv 自举。
• Agent 闭环：VeriGen mode/profile 与 verigen agent 入口、EDA ToolRunner（iverilog/vvp、Verilator、Yosys、Himasim 统一 schema）、Quality Probe fix-loop（四 Agent、最多 3 轮）、统一 Context Router（按预算裁剪 KG/Playbook/Graphify/trace/tool results）。
• 板级与评测：board profile/schema、mock programmer backend、dry-run hardware flow（先真实仿真再 mock 上板）、release smoke checklist、evaluation suite（pass@1、3 轮收敛率、失败类型分布）。
• 产品化：agent 内按需 VeriGen 状态面板、内部 dogfood/debug product workbench TUI、onboarding、provider config、project templates、board profile 管理、layout persistence、报告导出和 session replay。

当前边界：

• 还没有接真实 FPGA 上板流程；无设备阶段先做 mock/dry-run board backend。后续可从固定 blink_led bring-up 开始，再接入 VeriGen 生成 RTL 的真正板级流程。
• 还没有把 Himasim/Vivado/Quartus/Yosys profile 做成完整 board profile，当前已有统一结果 schema 和 missing_tool 降级。

各阶段完整交付物和下一步计划见 VeriGen 产品化路线图。

• 产品设计文档
• 产品化路线图
• 技术改造文档
• 交接文档
• S0 可行性报告

MIT