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 在线文档

[!TIP] RISC-V Summit Europe 2026 上 UCAgent workshop 的幻灯片、代码和环境已经全部开源在官方仓库中：https://github.com/XS-MLVP/tutorial-records

---

系统要求

• Python 3.11，如果最新版本Python遇到依赖问题请降级
• 支持的操作系统: 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. 安装 OpenCode

请参考 https://opencode.ai/ 安装opencode。 其他 Code Agent 请参考对应文档，例如 claude code, copilot-cli, kilo-cli, iflow, qwen-code 等。

4. 配置 LLM API

export OPENAI_MODEL=<model_name>              # 例如 glm-5.3-flash
export OPENAI_API_KEY=<your_key>              # API key
export OPENAI_API_BASE=<base_url>             # 类似 http://my_base_url/v1
export OPENAI_CONTEXT_SIZE=<max_context_size> # 可选，例如 819200 （800k上下文）
export OPENAI_OUTPUT_SIZE=<max_output_size>   # 可选，例如 131072 （128k最大输出）

也可以把上述内容写入 ~/.ucagent_env，然后：

source ~/.ucagent_env

如果未配置 LLM API，opencode 会自动选择一个免费模型。也可以通过环境变量显式指定模型（该变量会作为额外参数追加到 opencode 的启动命令中）：

export UC_ENV_CMD_BACKEND_EX_ARGS="-m opencode/deepseek-v4.1-flash-free"

可用免费模型可通过 opencode models | grep free 查看。

5. 开始验证

以 example 中的 Adder 为例。

# backend can be: langchain, claude, opencode, copilot, kilo, qwen, iflow, etc.
make mcp_Adder ARGS="--loop --backend=opencode"

该命令会创建工作目录、启动 MCP Server，并自动调用 opencode 执行验证任务；opencode 使用的模型即上一步配置的 LLM API。

已经支持的后端请参考 ucagent/setting.yaml 中的backend部分。

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

6. 如何提升验证质量(可选)

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

1. 开启LLM阶段结果检查

2. 开启人工阶段结果检查

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

7. 验证交付

如果验证结果需要交付，建议：

• 基于Spec和验证要求，通过Vibe coding生成高质量README.md
• 基于Spec和RTL源码，分析是否需要开启参考模型和Mock组件支持（NEED_REF_MODEL=true，IGNORE_MOCK_COMPONENT=false）
• 跑默认工作流直到不能发现bug，如果是误报需要修复Spec文档
• 跑formal工作流直到不能发现bug（例如 make formal_mcp_Adder ARGS="--loop --backend=opencode"）
• 跑覆盖率工作流把RTL覆盖率提升至99%以上

---

通过Web界面交互

UCAgent提供了Master模式，基于它可以通过Web界面进行Agent集中管理、创建任务、查看状态、在线终端等操作。

本地启动

1. 配置环境变量

环境变量与快速开始的配置 LLM API一节相同（OPENAI_MODEL、OPENAI_API_KEY、OPENAI_API_BASE 等）。若已持久化到 ~/.ucagent_env，启动前加载即可：

source ~/.ucagent_env

2. 启动 UCAgent Master

make as_master_persist
# 或者，如果安装了ucagent，也可以直接运行ucagent启动master模式
ucagent --as-master-persist  --as-master

然后在浏览器中访问 http://localhost:8800 即可。

容器启动

容器启动时通过 -e 传入相同的 LLM API 环境变量：

docker run -it --rm \
  -e OPENAI_API_BASE=<your_openai_api_base> \
  -e OPENAI_API_KEY=<your_openai_api_key> \
  -e OPENAI_MODEL=<your_openai_model> \
  -p 8800:8800 \
  ghcr.io/xs-mlvp/ucagent:latest ucagent --as-master-persist  --as-master

也可以通过 docker 的 --env-file 指定环境变量文件，用一份文件替代多个 -e 参数：

docker run -it --rm \
  --env-file ~/.ucagent_docker_env \
  -p 8800:8800 \
  ghcr.io/xs-mlvp/ucagent:latest ucagent --as-master-persist --as-master

~/.ucagent_docker_env 内容示例如下。注意与 ~/.ucagent_env 不同：这里不写 export，且 # 注释必须独占一行（写在行内会被当作变量值的一部分）：

# 模型名称，例如 glm-5.3-flash
OPENAI_MODEL=<model_name>
# API key
OPENAI_API_KEY=<your_key>
# API 基础 URL，例如 http://my_base_url/v1
OPENAI_API_BASE=<base_url>
# 可选：上下文窗口大小（token 数），例如 819200（800k 上下文）
OPENAI_CONTEXT_SIZE=<max_context_size>
# 可选：单次最大输出（token 数），例如 131072（128k 最大输出）
OPENAI_OUTPUT_SIZE=<max_output_size>

如果 ghcr.io 无法访问，可以直接替换其为 ghcr.nju.edu.cn 等镜像地址。

启动成功后，在浏览器中访问 http://localhost:8800 即可。

基本操作

1. 在Web界面中，点击+按钮（或者launch按钮），创建一个新的任务。
2. 在Agent列表中，点击API按钮，连接到具体Agent的控制页面。
3. 在Agent控制页面中，点击web terminal按钮，打开在线终端。
4. 本地启动ucagent 通过 –master 参数连接到已有的Master服务。

更多功能

1. Launch 页面：可在浏览器内完成工作区创建、文件导入/上传、模块解析、编译与启动参数预览。
2. Task 页面：支持托管任务筛选、分页、详情与日志查看，以及停止/删除操作。
3. Agent 页面增强：支持阶段多选与批量开关（HM/Skip/LFail/LPass），并支持阶段产物文件内容与 Diff 复盘。
4. 统一代理访问：Master 可统一代理 task/agent 的 cmd、terminal、web-console 路径，减少跨地址跳转。
5. Web Terminal 增强：支持多会话访问（不同 URL）。

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

---

基本操作

TUI 快捷键

• ctrl + 上/下/左/右：调节界面布局（Console 高度 / Mission 面板宽度）
• ctrl + h/j/k/l：Vim 风格调节界面布局（等同于 ctrl+左/下/上/右）
• ctrl + c：取消运行中的命令；无命令运行时退出 TUI
• ctrl + t：打开主题选择器
• ctrl + / 或 f1：显示/隐藏快捷键帮助面板
• shift + 右：清空控制台输出
• shift + 左：清空输入行
• tab：命令补全；连续按 Tab 循环浏览候选项
• pageup / pagedown：Console 输出区翻页
• esc：退出滚动/分页/帮助面板，或清空输入行

阶段颜色提示

• 白色：待执行
• 红色：正在执行
• 绿色：执行通过
• *：
  • 蓝色表示该阶段启用了LLM Fail检查，当阶段检查Fail次数大于3时，让LLM给出修改建议
  • 绿色表示该阶段启用了LLM Pass检查，阶段任务完成时，让LLM检查是否满足阶段任务要求
  • 红色表示该阶段需要强制人工检查，输入命令 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/ucagent_info.json 文件，来加载上次执行信息接着执行。如果不需要历史信息，请删除该文件或者使用参数 --no-history 忽略加载历史。

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

A: 请参考 CodeAgent 的自定义后端 examples/CustomBackend/README.md。

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 可随版本发布分发。

---

获取更多帮助

• 📚 UCAgent 在线文档
• 🚀 快速开始指南
• 🔧 自定义配置
• 🛠️ 工具列表
• 💬 GitHub Issues

贡献指南

欢迎提交 Issue 和 Pull Request！