UCAgent（UnityChip verification Agent）

基于大模型进行自动化 UT 验证 AI 代理

English Introduction | UCAgent 在线文档

项目简介

UCAgent 是一个基于大语言模型的自动化硬件验证 AI 代理，专注于芯片设计的单元测试(Unit Test)验证工作。通过 AI 技术自动分析硬件设计，生成测试用例，执行验证任务并生成测试报告，从而提高验证效率。

核心特点：

自动化芯片验证工作流
支持功能覆盖率与代码覆盖率分析
文档、代码、报告一致性保障
支持 MCP 协议与主流 Code Agent（OpenHands、Copilot、Claude Code、Gemini-CLI、Qwen-Code 等）深度协同
提供三种智能交互模式（standard、enhanced、advanced）

更多详细介绍请参考 UCAgent 在线文档

系统要求

Python 3.11+
支持的操作系统: Linux, macOS
内存: 建议 4GB 以上
网络: 需要访问 AI 模型 API（OpenAI 兼容）
picker: https://github.com/XS-MLVP/picker

快速开始

1. 下载源码

git clone https://github.com/XS-MLVP/UCAgent.git
cd UCAgent

2. 安装依赖

pip3 install -r requirements.txt

3. 清空环境

make clean

4. 启动 MCP-Server

以 example 中的 Adder 为例（依赖 picker）：

默认地址为：http://127.0.0.1:5000

make mcp_Adder  # workspace 设置为当前目录下的 output
# 调用了如下命令：
#   picker export Adder/Adder.v --rw 1 --sname Adder --tdir output/ -c -w output/Adder/Adder.fst
#   ucagent output/ Adder -s -hm --tui --mcp-server-no-file-tools --no-embed-tools

5. 安装配置 Qwen Code CLI

请参考：https://qwenlm.github.io/qwen-code-docs/en/

由于测试用例多了后运行时间较长，建议 timeout 值设置大一些，例如 300 秒。

~/.qwen/settings.json 配置文件示例：

{
    "mcpServers": {
        "unitytest": {
            "httpUrl": "http://localhost:5000/mcp",
            "timeout": 300000
        }
    }
}

6. 开始验证

cd output
qwen

注意：

需要在工作目录（如上述例子中的 output）中启动 Code Agent，否则可能会出现文件路径不匹配问题。
如果DUT比较复杂，有外围组件依赖，需要通过ucagent交互命令打开默认skip的阶段。

输入任务提示词：

请通过工具RoleInfo获取你的角色信息和基本指导，然后完成任务。请使用工具ReadTextFile读取文件。你需要在当前工作目录进行文件操作，不要超出该目录。

提示：

请根据任务需要编写验证 Prompt
当 Code Agent 中途停止时，可输入 继续，请通过工具Check和Complete判断是否完成所有任务

💡 更多使用方式： 除了 MCP 协同模式，UCAgent 还支持直接接入 LLM、人机协同等多种模式，详见使用文档

7. 如何提升效果(可选)

默认情况下，UCAgent只是启用内部的Python Checker进行阶段结果检查，属于启发式。如果需要验证效果提升，可以引入 LLM 阶段结果检查，如果需要达到“交付级”，还需要进一步引入人工阶段检查。

阶段默认检查顺序：Python Checker -> LLM -> 人工

基本操作

TUI 快捷键

ctrl + 上/下/左/右：调节界面布局
shift + 上/下：调节状态面板高度
shift + 右：清空控制台
shift + 左：清空输入
alt + 上/下：滚动 Message 界面内容
alt + 左/右：滚动 Console 界面内容
esc: 强制刷新界面/退出滚动

阶段颜色提示

白色：待执行
红色：正在执行
绿色：执行通过
*：表示该阶段需要强制人工检查，输入命令 hmcheck_pass [msg] 后 AI 才能继续
黄色：跳过该阶段

常用交互命令

q：退出 TUI（或退出 UCAgent）
tui：进入 TUI
tab: 命令补全
tool_list：列出所有可用工具
help：查看所有命令帮助
loop [prompt]：继续当前任务

📖 详细操作说明： 查看 TUI 使用文档

常见问题 (FAQ)

Q: 如何配置不同的 AI 模型？

A: 在 config.yaml 中修改 openai.model_name 字段，支持任何 OpenAI 兼容的 API。详见配置文档。

Q: 验证过程中出现错误怎么办？

A: 使用 Ctrl+C 进入交互模式，通过 status 查看当前状态，使用 help 获取调试命令。

Q: MCP 服务器无法连接？

A: 检查端口是否被占用，确认防火墙设置，可以通过 --mcp-server-port 指定其他端口。

Q: 为何有上次执行信息残留？

A: UCAgent 默认会从工作目录中查找 .ucagent_info.json 文件，来加载上次执行信息接着执行。如果不需要历史信息，请删除该文件或者使用参数 --no-history 忽略加载历史。

Q: 如何运行长时间验证？

A: 请参考 CodeAgent 的无头模式以及脚本 tests/test_nohead_loop.bash。

Q: 可以自定义验证阶段吗？

A: 可以，详见自定义文档。

Q: 如何添加自定义工具？

A: 在 ucagent/tools/ 目录下创建新的工具类，继承 UCTool 基类，并通过 --ex-tools 参数加载。详见工具列表文档。

🔍 更多问题： 查看完整 FAQ 文档

文档构建与预览（MkDocs）

Makefile 提供文档相关辅助目标（MkDocs + Material）：

目标	作用	使用场景
`make docs-help`	显示文档相关目标帮助	查看可用命令
`make docs-install`	从 `docs/requirements-docs.txt` 安装构建依赖	首次使用或依赖更新时
`make docs-serve`	本地预览（默认 127.0.0.1:8030）	开发和预览文档时
`make docs-build`	构建静态站点到 `docs/site`	本地生成生产版本
`make docs-clean`	删除 `docs/site` 目录	清理构建产物时

使用流程

第一次使用（安装依赖）：

make docs-install    # 安装 mkdocs 和 material 主题等依赖

日常开发（预览文档）：

make docs-serve      # 启动本地服务器，访问 http://127.0.0.1:8030 查看
# 修改文档后浏览器会自动刷新

本地生成和查看（构建生产版本）：

make docs-build      # 生成静态网站到 docs/site 目录
# 在本地浏览器中打开 docs/site/index.html 查看
make docs-clean      # 清理构建产物（可选）

完整工作流示例

# 1. 首次设置：安装依赖
make docs-install

# 2. 开发阶段：预览文档（可反复执行）
make docs-serve      # 在浏览器中访问 http://127.0.0.1:8030
# ...编辑文档...
# 按 Ctrl+C 停止服务

# 3. 本地生成：构建生产版本
make docs-build      # 生成 docs/site 目录
# 在本地浏览器中打开 docs/site/index.html 查看

# 4. 清理（可选）
make docs-clean      # 删除 docs/site 目录

说明

端口与地址目前写死于 docs/Makefile 中，可自行修改。
make docs-serve 适合开发时使用，支持热重载
make docs-build 生成完整的静态网站文件，输出到 docs/site 目录，可本地预览最终效果（打开 docs/site/index.html）

PDF 手册构建（Pandoc + XeLaTeX）

用于生成较高排版质量开发者 PDF 手册：

目标	作用
`make pdf`	从有序 Markdown 源生成 `ucagent-doc.pdf`
`make pdf-one`	与 `pdf` 等价（方便 CI 调用）
`make pdf-clean`	清理生成的 PDF 与 LaTeX 临时文件

示例

make pdf
make MONO="JetBrains Mono" pdf      # 覆盖等宽字体
make TWOSIDE=1 pdf                   # 双面排版（文件名添加 -twoside）
make pdf-clean

依赖

pandoc
XeLaTeX (TexLive)
中文字体 “Noto Serif CJK SC”
等宽字体（默认 DejaVu Sans Mono）
可选过滤器 pandoc-crossref

自定义变量

MONO 更换等宽字体
TWOSIDE 非空启用双面模式

常见问题

字体缺失： 安装 CJK 字体包（如 fonts-noto-cjk）。
LaTeX 报错： 确保安装完整 XeLaTeX 套件（必要时 texlive-full）。
交叉引用缺失： 确认 pandoc-crossref 在 PATH 中。

输出：ucagent-doc.pdf 可随版本发布分发。

获取更多帮助

贡献指南

欢迎提交 Issue 和 Pull Request！