commit 9465628f57fb4ab9813ee84bc85c074f52c630d4
Author: zice6688 <119166499+zice6688@users.noreply.github.com>
Date:   Mon Mar 30 16:38:00 2026 +0800

    first commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dfe5594
--- /dev/null
+++ b/README.md
@@ -0,0 +1,394 @@
+# TBgen_App - 自动化 Testbench 生成工具
+
+基于 CorrectBench 的多阶段自动化 Testbench 生成工具，支持根据 DUT 和项目描述生成 Verilog Testbench。
+
+## 功能特性
+
+- **多阶段流程**: TBgen → TBsim → TBcheck → CGA → TBeval
+- **多种模型支持**: Qwen, GPT, Claude 等主流 LLM
+- **自动化评估**: 支持覆盖率评估和 Mutant Kill 检测
+- **灵活配置**: 通过 YAML 配置文件自定义各项参数
+
+---
+
+## 目录结构
+
+```
+TBgen_App/
+├── config/                  # 配置文件夹
+│   ├── config.py            # 配置加载模块
+│   ├── default.yaml         # 默认配置
+│   └── key_API.json         # API密钥（需用户填写）
+├── autoline/                 # 核心流程模块
+│   ├── TB_autoline.py       # 主流程编排
+│   ├── TB1_gen.py           # TB生成
+│   ├── TB2_syncheck.py      # 语法检查
+│   ├── TB3_funccheck.py     # 功能检查
+│   ├── TB4_eval.py          # 评估
+│   └── TB_cga.py            # CGA优化
+├── prompt_scripts/           # Prompt脚本
+├── data/                    # 数据集管理
+├── utils/                   # 工具函数
+├── LLM_call.py              # LLM调用
+├── loader_saver.py          # 文件加载保存
+├── main.py                  # 命令行入口
+├── run_tbgen.py             # Python API
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## 使用前配置
+
+### 1. 安装依赖
+
+```bash
+cd TBgen_App
+pip install -r requirements.txt
+```
+
+或使用项目自带的虚拟环境（推荐）:
+```bash
+# 如果原项目有venv
+/path/to/venv/bin/python run_tbgen.py
+```
+
+### 2. 配置 API 密钥（必须）
+
+编辑 `config/key_API.json`，填入您的 API 密钥:
+
+```json
+{
+    "OPENAI_API_KEY": "your-openai-key",
+    "ANTHROPIC_API_KEY": "your-anthropic-key",
+    "dashscope": "your-dashscope-key"
+}
+```
+
+**注意**: 当前工具主要使用 `dashscope` (Qwen模型)，请确保填入有效的阿里云API密钥。
+
+### 3. 选择模型（可选）
+
+支持的模型:
+- **Qwen**: `qwen-max`, `qwen-plus`
+- **GPT**: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`
+- **Claude**: `claude-3-5-sonnet`, `claude-3-opus`
+
+默认使用 `qwen-max`。如需更改，修改代码中的 `model` 参数。
+
+---
+
+## 使用方法
+
+### 方法一：Python API（推荐）
+
+```python
+import sys
+sys.path.insert(0, '/path/to/TBgen_App')
+from run_tbgen import generate_tb
+
+# 定义DUT
+dut_code = """
+module multiplier(
+    input clk,
+    input rst,
+    input [7:0] a,
+    input [7:0] b,
+    output reg [15:0] y
+);
+    always @(posedge clk) begin
+        if (rst) begin
+            y <= 16'b0;
+        end else begin
+            y <= a * b;
+        end
+    end
+endmodule
+"""
+
+# 项目描述
+description = """
+一个8位乘法器，具有以下特性：
+1. 输入两个8位无符号数a和b
+2. 输出16位乘积y
+3. 同步复位信号rst
+4. 在时钟上升沿进行乘法运算
+"""
+
+# Module header（必须与DUT端口一致）
+header = "module multiplier(input clk, input rst, input [7:0] a, input [7:0] b, output reg [15:0] y);"
+
+# 生成TB
+tb_path, result = generate_tb(
+    dut_code=dut_code,
+    description=description,
+    header=header,
+    task_id="multiplier_test",
+    model="qwen-max",          # 可选: qwen-max, qwen-plus, gpt-4o等
+    enable_cga=True,            # 是否启用CGA优化
+    output_dir="./output"       # 输出目录
+)
+
+print(f"TB saved to: {tb_path}")
+print(f"Coverage: {result.get('cga_coverage', 0)}")
+print(f"Eval1 Pass: {result.get('run_info', {}).get('Eval1_pass')}")
+```
+
+### 方法二：命令行
+
+```bash
+# 准备输入文件
+cat > dut.v << 'EOF'
+module multiplier(
+    input clk,
+    input rst,
+    input [7:0] a,
+    input [7:0] b,
+    output reg [15:0] y
+);
+    always @(posedge clk) begin
+        if (rst) y <= 16'b0;
+        else y <= a * b;
+    end
+endmodule
+EOF
+
+cat > description.txt << 'EOF'
+一个8位乘法器：
+1. 输入两个8位无符号数a和b
+2. 输出16位乘积y
+3. 同步复位信号rst
+4. 在时钟上升沿进行乘法运算
+EOF
+
+# 运行生成
+python main.py \
+    -d dut.v \
+    -w description.txt \
+    --header "module multiplier(input clk, input rst, input [7:0] a, input [7:0] b, output reg [15:0] y);" \
+    -m qwen-max \
+    -o output/
+```
+
+---
+
+## 输入说明
+
+### 1. dut_code / -d DUT文件
+
+**必需**。DUT的完整Verilog代码，包括：
+- module声明
+- 所有端口定义
+- 实现逻辑
+
+### 2. description / -w 描述文件
+
+**必需**。项目需求描述，应该包含：
+- 功能说明
+- 输入输出规格
+- 端口定义
+- 特殊要求或边界条件
+
+**示例**:
+```
+一个8位无符号乘法器：
+- 输入: a[7:0], b[7:0] (8位无符号数)
+- 输出: y[15:0] (16位乘积)
+- 复位: rst (同步高有效)
+- 时钟: clk (上升沿触发)
+```
+
+### 3. header / --header
+
+**必需**。DUT的module声明行，用于提取端口信息。
+
+格式: `module module_name(端口列表);`
+
+示例:
+```verilog
+module multiplier(input clk, input rst, input [7:0] a, input [7:0] b, output reg [15:0] y);
+```
+
+---
+
+## 输出说明
+
+### 1. 主输出目录
+
+```
+output/{task_id}/
+└── {task_id}/
+    ├── final_TB.v          # 最终Verilog Testbench
+    ├── final_TB.py         # Python校验脚本
+    ├── run_info.json       # 运行信息
+    └── run_info_short.json # 简化运行信息
+```
+
+### 2. 完整输出目录（含中间文件）
+
+```
+output/{task_id}/{task_id}/
+├── final_TB.v              # 最终TB
+├── final_TB.py             # Python Checker
+├── run_info.json           # 详细运行信息
+├── 1_TBgen/                # TB生成阶段
+│   ├── stage_0.txt         # LLM对话 (Circuit Type检测)
+│   ├── stage_1.txt         # LLM对话 (Spec生成)
+│   ├── stage_2.txt         # LLM对话 (Scenario生成)
+│   ├── stage_3.txt         # LLM对话 (Python规则生成)
+│   ├── stage_4.txt         # LLM对话 (TB代码生成)
+│   ├── stage_4b.txt        # LLM对话 (SEQ优化)
+│   ├── stage_5.txt         # LLM对话 (Pychecker代码)
+│   ├── stage_checklist.txt # Checklist检查
+│   └── TBgen_codes/        # 生成的TB代码
+│       ├── {task_id}_tb.v  # TB Verilog代码
+│       └── {task_id}_tb.py # TB Python Checker
+└── ...
+```
+
+### 3. 返回结果字典
+
+```python
+{
+    "TB_code_v": "...",      # TB Verilog代码
+    "TB_code_py": "...",      # TB Python代码
+    "run_info": {...},        # 详细运行信息
+    "cga_coverage": 0.0,      # CGA覆盖率
+    "full_pass": None         # 是否全部通过
+}
+```
+
+---
+
+## 关键变量说明
+
+### run_tbgen.py
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `model` | 使用的LLM模型 | `"qwen-max"` |
+| `enable_cga` | 是否启用CGA优化 | `True` |
+| `cga_iter` | CGA最大迭代次数 | `10` |
+| `api_key_path` | API密钥文件路径 | `"config/key_API.json"` |
+
+### config/default.yaml
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `gpt.model` | 默认模型 | `"gpt-4o-2024-08-06"` |
+| `autoline.onlyrun` | 运行模式 | `null` (完整流程) |
+| `autoline.cga.enabled` | CGA开关 | `True` |
+| `autoline.cga.max_iter` | CGA迭代次数 | `10` |
+
+### 配置项详解
+
+#### onlyrun - 运行模式选择
+
+```yaml
+autoline:
+    onlyrun: null      # 完整流程 (gen→sim→check→cga→eval)
+    # onlyrun: "TBgen"           # 仅生成TB
+    # onlyrun: "TBgensim"         # 生成+语法检查
+    # onlyrun: "TBgensimeval"     # 生成+检查+评估(不含CGA)
+```
+
+#### cga - 覆盖率引导优化
+
+```yaml
+autoline:
+    cga:
+        enabled: True           # 是否启用
+        max_iter: 10            # 最大迭代次数
+        target_coverage: 100.0  # 目标覆盖率
+```
+
+---
+
+## 注意事项
+
+### 1. 必须配置项
+
+- [ ] `config/key_API.json` - API密钥
+- [ ] `model` - 选择合适的模型
+
+### 2. Header格式要求
+
+**必须**与DUT代码中的module声明一致:
+
+```verilog
+// 正确
+header = "module foo(input clk, output [7:0] y);"
+
+// 错误 - 缺少分号
+header = "module foo(input clk, output [7:0] y)"
+```
+
+### 3. 时序逻辑DUT
+
+如果DUT是时序逻辑（always块），header中**必须**使用 `output reg` 而非 `output wire`:
+
+```verilog
+header = "module foo(input clk, input rst, output reg [7:0] y);"
+```
+
+### 4. 关于CGA优化
+
+CGA (Coverage-Guided Agent) 优化可以提升测试覆盖率，但会增加运行时间。
+
+- 快速测试：设置 `enable_cga=False`
+- 完整测试：设置 `enable_cga=True`
+
+### 5. 运行时间
+
+完整流程运行时间取决于:
+- LLM模型响应速度
+- DUT复杂度
+- 是否启用CGA优化
+
+典型时间:
+- 简单组合逻辑: ~2-5分钟
+- 复杂时序逻辑: ~5-10分钟
+- 启用CGA优化: 额外增加2-5分钟
+
+### 6. 常见错误
+
+| 错误信息 | 原因 | 解决方法 |
+|----------|------|----------|
+| `API Key not found` | key_API.json配置错误 | 检查并填入有效密钥 |
+| `ModuleNotFoundError` | 依赖未安装 | `pip install -r requirements.txt` |
+| `timeout` | LLM响应超时 | 降低复杂度或切换模型 |
+
+---
+
+## 运行示例
+
+```bash
+# 进入目录
+cd /home/zhang/CorrectBench/TBgen_App
+
+# 使用venv运行
+/home/zhang/CorrectBench/venv/bin/python run_tbgen.py
+
+# 或直接运行
+python run_tbgen.py
+```
+
+输出示例:
+```
+Generating TB for example multiplier...
+ [LLM] Success. Time: 5.66s. Length: 270
+[INFO] [example_mul] [TBgen] stage_0 ends (5.68s used)
+ [LLM] Success. Time: 24.6s. Length: 1835
+[INFO] [example_mul] [TBgen] stage_1 ends (24.62s used)
+ ...
+TB saved to: ./output/example_mul_tb.v
+Coverage: 0.0
+Full Pass: None
+```
+
+---
+
+## License
+
+本项目基于 CorrectBench 构建。