Verificator

默认语言：中文 | English

Verificator 是一个面向 Verilog / SystemVerilog 的本地语义验证与分阶段修复工作台。它把确定性编译/仿真、结构化 LLM agent、仿真证据审阅、补丁生成和人工确认串成一个可回放的闭环，目标是让 RTL 修复过程有证据、有边界、可人工接管，而不是直接接受模型输出。

主要能力

• 语义分析：根据 RTL、端口、可选模块说明和静态检查结果推断设计意图、行为假设和行为契约。
• 自动 testbench 草稿：使用 LLM 生成自检查 testbench，并通过 iverilog / vvp 执行。
• 证据审阅：整理编译日志、运行日志、pass/fail marker、VCD 摘要和 checker 可信度。
• 分阶段修复：优先处理编译问题，再区分 TB / checker 问题和 DUT 功能问题。
• 人工门控：低风险 TB 补丁可自动应用；高风险 TB 补丁和 DUT 补丁保留人工确认。
• 运行历史：保存分析和 repair session 状态，便于回看证据、补丁和决策路径。

适用场景

• 快速检查 RTL 语法、组合/时序行为和常见协议风险。
• 为小型模块生成 directed checker 和仿真证据。
• 在 DUT 与 testbench 都可能有问题时，分阶段定位问题来源。
• 学习或复盘一个模块为什么失败、系统如何判断、补丁为什么被接受或暂停。

项目结构

• apps/api/：FastAPI 后端、agent/runtime、仿真适配器、存储和 API 测试。
• apps/web/：React + Vite 前端工作台。
• docs/architecture.md：英文架构文档。
• docs/user-guide.md：英文用户指南。
• testset/：示例 RTL 和设计意图数据，用于本地测试。

环境要求

• Python 3.11+
• Node.js 18+
• iverilog 和 vvp 已加入 PATH
• OpenAI 兼容模型服务的 API key，例如 OpenAI 或 OpenRouter

配置

复制示例配置：

Copy-Item apps/api/.env.example apps/api/.env

然后在 apps/api/.env 中填写自己的模型服务配置。后端会读取 VERIFICATOR_* 环境变量，来源可以是 apps/api/.env、仓库根目录 .env 或系统环境变量。不要提交真实 .env、API key、运行数据库或 .runs/ 目录。

常用配置：

• VERIFICATOR_LLM_PROVIDER
• VERIFICATOR_OPENAI_API_KEY
• VERIFICATOR_OPENROUTER_API_KEY
• VERIFICATOR_WORKSPACE_ROOT
• VERIFICATOR_RUN_DB_PATH

快速启动

启动后端：

cd apps/api
pip install -e .[dev]
python -m uvicorn app.main:app --host 127.0.0.1 --port 12378

启动前端：

cd apps/web
npm install
npm run dev

默认地址：

• 前端：http://localhost:5173
• 后端：http://127.0.0.1:12378

工作流程

RTL + 可选模块说明
        |
        v
Analyst：推断设计意图、行为假设和行为契约
        |
        v
TB Coder：生成自检查 testbench
        |
        v
Compile + Simulate：执行确定性编译和仿真
        |
        v
Simulation Reviewer：整理证据并判断 TB 可信度
        |
        v
Judge：决定 TB_REPAIR / FUNCTIONAL_REPAIR / INCONCLUSIVE
        |
        v
Fix：生成 TB 或 DUT 补丁建议
        |
        v
Critic：审查补丁风险和证据一致性

测试

后端：

cd apps/api
python -m pytest -q

前端：

cd apps/web
npm run test -- --run
npm run build

浏览器端到端测试（可选）：

cd apps/web
npx playwright test

文档

• Architecture
• User Guide

安全说明

不要提交真实 .env、API key、OpenRouter key、运行数据库、日志、.runs/、node_modules/ 或构建产物。敏感问题请优先私下报告，普通 bug 和改进建议可以通过 issue 或 pull request 讨论。

许可证

MIT。详见 LICENSE。