使用

• 1: MCP集成模式（推荐）
• 2: 直接使用模式
• 3: 人机协同验证
• 4: 参数说明
• 5: TUI
• 6: FAQ

1 - MCP集成模式（推荐）

MCP 集成（推荐）集成Code Agent

基于 MCP 的外部编程 CLI 协作方式。该模式能与所有支持 MCP-Server 调用的 LLM 客户端进行协同验证，例如：Cherry Studio、Claude Code、 Gemini-CLI、VS Code Copilot、Qwen-Code等。 平常使用是直接使用make命令的，要看详细命令可参考快速开始，也可以直接查看项目根目录的Makefile文件。

• 准备RTL和对应的SPEC文档放入examples/{dut}文件夹。{dut}是模块的名称，比如Adder，如果是Adder，目录则为examples/Adder。

• 打包RTL，将文档放入工作目录并且启动 MCP server：make mcp_{dut}，{dut}为对应的模块。此处如果使用的Adder，则命令为make mcp_Adder

• 在支持 MCP client 的应用中配置 JSON：

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

• 启动应用：此处使用的Qwen Code，在UCAgent/output启动qwen,然后输入提示词。

• 输入提示词：

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

2 - 直接使用模式

直接使用

基于本地 CLI 和大模型的使用方式。需要准备好 OpenAI 兼容的 API 和嵌入模型 API。

使用环境变量配置（推荐）

配置文件内容：

# OpenAI兼容的API配置
openai:
  model_name: "$(OPENAI_MODEL: Qwen/Qwen3-Coder-30B-A3B-Instruct)" # 模型名称
  openai_api_key: "$(OPENAI_API_KEY: YOUR_API_KEY)" # API密钥
  openai_api_base: "$(OPENAI_API_BASE: http://10.156.154.242:8000/v1)" # API基础URL
# 向量嵌入模型配置
# 用于文档搜索和记忆功能，不需要可通过 --no-embed-tools 关闭
embed:
  model_name: "$(EMBED_MODEL: Qwen/Qwen3-Embedding-0.6B)" # 嵌入模型名称
  openai_api_key: "$(EMBED_OPENAI_API_KEY: YOUR_API_KEY)" # 嵌入模型API密钥
  openai_api_base: "$(EMBED_OPENAI_API_BASE: http://10.156.154.242:8001/v1)" # 嵌入模型API URL
  dims: 4096 # 嵌入维度

UCAgent 的配置文件支持 Bash 风格的环境变量占位：$(VAR: default)。加载时会用当前环境变量 VAR 的值替换；若未设置，则使用 default。

• 例如在内置配置 vagent/setting.yaml 中：
  • openai.model_name: "$(OPENAI_MODEL: <your_chat_model_name>)"
  • openai.openai_api_key: "$(OPENAI_API_KEY: [your_api_key])"
  • openai.openai_api_base: "$(OPENAI_API_BASE: http://<your_chat_model_url>/v1)"
  • embed.model_name: "$(EMBED_MODEL: <your_embedding_model_name>)"
  • 也支持其他提供商：model_type 可选 openai、anthropic、google_genai（详见 vagent/setting.yaml）。

你可以仅通过导出环境变量完成模型与端点切换，而无需改动配置文件。

示例：设置聊天模型与端点

# 指定聊天模型（OpenAI 兼容）
export OPENAI_MODEL='Qwen/Qwen3-Coder-30B-A3B-Instruct'

# 指定 API Key 与 Base（按你的服务商填写）
export OPENAI_API_KEY='你的API密钥'
export OPENAI_API_BASE='https://你的-openai-兼容端点/v1'

# 可选：嵌入模型（若使用检索/记忆等功能）
export EMBED_MODEL='text-embedding-3-large'
export EMBED_OPENAI_API_KEY="$OPENAI_API_KEY"
export EMBED_OPENAI_API_BASE="$OPENAI_API_BASE"

然后按前述命令启动 UCAgent 即可。若要长期生效，可将上述 export 追加到你的默认 shell 启动文件（例如 bash: ~/.bashrc，zsh: ~/.zshrc，fish: ~/.config/fish/config.fish），保存后重新打开终端或手动加载。

使用 config.yaml 来配置

• 在项目根目录创建并编辑 config.yaml 文件，配置 AI 模型和嵌入模型：

# OpenAI兼容的API配置
openai:
  openai_api_base: <your_openai_api_base_url> # API基础URL
  model_name: <your_model_name> # 模型名称，如 gpt-4o-mini
  openai_api_key: <your_openai_api_key> # API密钥

# 向量嵌入模型配置
# 用于文档搜索和记忆功能，不需要可通过 --no-embed-tools 关闭
embed:
  model_name: <your_embed_model_name> # 嵌入模型名称
  openai_api_base: <your_openai_api_base_url> # 嵌入模型API URL
  openai_api_key: <your_api_key> # 嵌入模型API密钥
  dims: <your_embed_model_dims> # 嵌入维度，如 1536

开始使用

• 第一步和 MCP 模式相同，准备 RTL 和对应的 SPEC 文档放入examples/{dut}文件夹。{dut}是模块的名称，如果是Adder，目录则为examples/Adder。
• 第二步开始就不同了，打包 RTL，将文档放入工作目录并启动 UCAgent TUI：make test_{dut}，{dut}为对应的模块。若使用 Adder，命令为 make test_Adder（可在 Makefile 查看全部目标）。该命令会：
  • 将 examples/{dut} 下文件拷贝到 output/{dut}（含 .v/.sv/.md/.py 等）
  • 执行 python3 ucagent.py output/ {dut} --config config.yaml -s -hm --tui -l
  • 启动带 TUI 的 UCAgent，并自动进入任务循环（loop）

提示：验证产物默认写入 output/unity_test/，若需更改可通过 CLI 的 --output 参数指定目录名。

直接用 CLI 启动（不经 Makefile）

• 未安装命令时（项目内运行）：
  • python3 ucagent.py output/ Adder --config config.yaml -s -hm --tui -l
• 安装为命令后：
  • ucagent output/ Adder --config config.yaml -s -hm --tui -l

参数对齐 vagent/cli.py：

• workspace：工作区目录（此处为 output/）
• dut：DUT 名称（工作区子目录名，如 Adder）
• 常用可选项：
  • --tui 启动终端界面
  • -l/--loop --loop-msg "..." 启动后立即进入循环并注入提示
  • -s/--stream-output 实时输出
  • -hm/--human 进入人工可干预模式（在阶段间可暂停）
  • --no-embed-tools 如不需要检索/记忆工具
  • --skip/--unskip 跳过/取消跳过阶段（可多次传入）

常用 TUI 命令速查（直接使用模式）

• 列出工具：tool_list
• 阶段检查：tool_invoke Check timeout=0
• 查看日志：tool_invoke StdCheck lines=-1（-1 表示所有行）
• 终止检查：tool_invoke KillCheck
• 阶段完成：tool_invoke Complete timeout=0
• 运行用例：
  • 全量：tool_invoke RunTestCases target='' timeout=0
  • 单测函数：tool_invoke RunTestCases target='tests/test_checker.py::test_run' timeout=120 return_line_coverage=True
  • 过滤：tool_invoke RunTestCases target='-k add or mul'
• 阶段跳转：tool_invoke GoToStage index=2（索引从 0 开始）
• 继续执行：loop 继续修复 ALU754 的未命中分支并重试用例

建议的最小可写权限（只允许生成验证产物处可写）：

• 仅允许 unity_test/ 与 unity_test/tests/ 可写：
  • add_un_write_path *
  • del_un_write_path unity_test
  • del_un_write_path unity_test/tests

常见问题与提示

• 检查卡住/无输出：
  • 先 tool_invoke StdCheck lines=-1 查看全部日志；必要时 tool_invoke KillCheck；修复后重试 tool_invoke Check。
• 没找到工具名：
  • 先执行 tool_list 确认可用工具；若缺失，检查是否在 TUI 模式、是否禁用了嵌入工具（通常无关）。
• 产物位置：
  • 默认在 workspace/output_dir，即本页示例为 output/unity_test/。

相关文档

• 人机协同的完整流程与示例，见人机协同验证
• MCP 集成（如 gemini-cli / qwen code），见MCP集成模式
• TUI 界面与操作详解，见TUI

3 - 人机协同验证

UCAgent 支持在验证过程中进行人机协同，允许用户暂停 AI 执行，人工干预验证过程，然后继续 AI 执行。这种模式适用于需要精细控制或复杂决策的场景。

协同流程：

1. 暂停 AI 执行：

   • 在直接接入 LLM 模式下：按 Ctrl+C 暂停。
   • 在 Code Agent 协同模式下：根据 Agent 的暂停方式（如 Gemini-cli 使用 Esc）暂停。

2. 人工干预：

   • 手动编辑文件、测试用例或配置。
   • 使用交互命令进行调试或调整。

3. 阶段控制：

   • 使用 tool_invoke Check 检查当前阶段状态。
   • 使用 tool_invoke Complete 标记阶段完成并进入下一阶段。

4. 继续执行：

   • 使用 loop [prompt] 命令继续 AI 执行，并可提供额外的提示信息。
   • 在 Code Agent 模式下，通过 Agent 的控制台输入提示。

5. 权限管理：

   • 可使用 add_un_write_path，del_un_write_path 等命令设置文件写权限，控制 AI 是否可以编辑特定文件。
   • 适用于直接接入 LLM 或强制使用 UCAgent 文件工具。

4 - 参数说明

参数与选项

UCAgent 的使用方式为：

ucagent <workspace> <dut_name> {参数与选项}

输入

• workspace：工作目录：
  • workspace/<DUT_DIR>: 待测设计（DUT），即由 picker 导出的 DUT 对应的 Python 包 <DUT_DIR>，例如：Adder
  • workspace/<DUT_DIR>/README.md: 以自然语言描述的该 DUT 验证需求与目标
  • workspace/<DUT_DIR>/*.md: 其他参考文件
  • workspace/<DUT_DIR>/*.v/sv/scala: 源文件，用于进行 bug 分析
  • 其他与验证相关的文件（例如：提供的测试实例、需求说明等）
• dut_name: 待测设计的名称，即 <DUT_DIR>，例如：Adder

输出

• workspace：工作目录：
  • workspace/Guide_Doc：验证过程中所遵循的各项要求与指导文档
  • workspace/uc_test_report： 生成的 Toffee-test 测试报告
  • workspace/unity_test/tests： 自动生成的测试用例
  • workspace/*.md： 生成的各类文档，包括 Bug 分析、检查点记录、验证计划、验证结论等

对输出的详细解释可以参考快速开始的9

位置参数

执行与交互

配置与模板

计划与 ToDo

ToDo 工具概览与示例 给模型规划的，小模型关闭，大模型自行打开

说明：ToDo 工具是用于提升模型规划能力的工具，用户可以利用它来自定义模型的ToDo列表。目前该功能对模型能力要求较高，默认处于关闭状态。

启用条件：任意模式下使用 --use-todo-tools；或在 standard 模式用 --force-todo 强制启用并在每轮提示中附带 ToDo 信息。

约定与限制：步骤索引为 1-based；steps 数量需在 2~20；notes 与每个 step 文本长度 ≤ 100；超限会拒绝并返回错误字符串。

工具总览

调用示例（以 MCP/内部工具调用为例，参数为 JSON 格式）：

{
	"tool": "CreateToDo",
	"args": {
		"task_description": "为 Adder 核心功能完成验证闭环",
		"steps": [
			"阅读 README 与规格，整理功能点",
			"定义检查点与通过标准",
			"生成首批单元测试",
			"运行并修复失败用例",
			"补齐覆盖率并输出报告"
		]
	}
}

{
	"tool": "CompleteToDoSteps",
	"args": { "completed_steps": [1, 2], "notes": "初始问题排查完成，准备补充用例" }
}

{ "tool": "UndoToDoSteps", "args": { "steps": [2], "notes": "第二步需要微调检查点" } }

{ "tool": "ResetToDo", "args": {} }

{ "tool": "GetToDoSummary", "args": {} }

{ "tool": "ToDoState", "args": {} }

外部与嵌入工具

日志

MCP Server

阶段控制与安全

版本与检查

示例

python3 ucagent.py ./output Adder \
  \
  -s \
  -hm \
  -im enhanced \
  --tui \
  -l \
  --loop-msg 'start verification' \
  --seed 12345 \
  --sys-tips '按规范完成Adder的验证' \
  \
  --config config.yaml \
  --template-dir ./templates \
  --template-overwrite \
  --output unity_test \
  --override 'conversation_summary.max_tokens=16384,...' \
  \
  --use-todo-tools \
  \
  --ex-tools 'SqThink,AnotherTool' \
  --no-embed-tools \
  \
  --log \
  --log-file ./output/ucagent.log \
  --msg-file ./output/ucagent.msg \
  \
  --mcp-server-no-file-tools \
  --mcp-server-host 127.0.0.1 \
  --mcp-server-port 5000 \
  \
  --force-stage-index 2 \
  --skip 5 --skip 7 \
  --unskip 6 \
  --nw ./output/Adder ./output/unity_test

• 位置参数
  • ./output：workspace 工作目录
  • Adder：dut 子目录名
• 执行与交互
  • -s：流式输出
  • -hm：启动即人工可介入
  • -im enhanced：交互模式为增强（含规划与记忆）
  • --tui：启用 TUI
  • --loop/–loop-msg：启动后立即进入循环并注入首条消息
  • --seed 12345：固定随机种子
  • --sys-tips：自定义系统提示
• 配置与模板
  • --config config.yaml：从config.yaml加载项目配置
  • --template-dir ./templates：指定模板目录为./templates
  • --template-overwrite：渲染模板时允许覆盖
  • --output unity_test：输出目录名unity_test
  • --override ‘…’: 覆盖配置键值（点号路径=值，多项用逗号分隔；字符串需内层引号，整体用单引号包裹以保留引号），示例里设置了会话摘要上限、启用裁剪、文档语言为“中文”、模型名为 gpt-4o-mini
  • -gif/--gen-instruct-file GEMINI.md：在 <workspace>/GEMINI.md 下生成外部协作引导文件
  • --guid-doc-path ./output/Guide_Doc：自定义 Guide_Doc 目录为./output/Guide_Doc
• 计划与 ToDo
  • --use-todo-tools：启用 ToDo 工具及强制附带 ToDo 信息
• 外部与嵌入工具
  • --ex-tools ‘SqThink,AnotherTool’：启用外部工具SqThink,AnotherTool
  • --no-embed-tools：禁用内置嵌入检索/记忆工具
• 日志
  • --log：开启日志文件
  • --log-file ./output/ucagent.log：指定日志输出文件为./output/ucagent.log
  • --msg-file ./output/ucagent.msg：指定消息日志文件为./output/ucagent.msg
• MCP Server
  • --mcp-server-no-file-tools：启动 MCP（无文件操作工具）
  • --mcp-server-host：Server 监听地址为127.0.0.1
  • --mcp-server-port：Server 监听端口为5000
• 阶段控制与安全
  • --force-stage-index 2：从阶段索引 2 开始
  • --skip 5 --skip 7：跳过阶段5和阶段7
  • --unskip 7：取消跳过阶段7
  • --nw ./output/Adder ./output/unity_test：限制仅./output/Adder和./output/unity_test路径可写
• 说明
  • --check 与 --version 会直接退出，未与运行组合使用
  • --mcp-server 与 --mcp-server-no-file-tools 二选一；此处选了后者带路径参数（如 --template-dir/--guid-doc-path/–nw 的路径）需实际存在，否则会报错
  • --override 字符串值务必带引号，并整体用单引号包住以避免 shell 吃掉引号（示例写法已处理）

5 - TUI

TUI（界面与操作）

UCAgent 自带基于 urwid 的终端界面（TUI），用于在本地交互式观察任务进度、消息流与控制台输出，并直接输入命令（如进入/退出循环、切换模式、执行调试命令等）。

界面组成

• Mission 面板（左侧）

  • 阶段列表：显示当前任务的阶段（索引、标题、失败数、耗时）。颜色含义：
    • 绿色：已完成阶段
    • 红色：当前进行阶段
    • 黄色：被跳过的阶段（显示“skipped”）
  • Changed Files：近期修改文件（含修改时间与相对时间，如“3m ago”）。较新的文件以绿色显示。
  • Tools Call：工具调用状态与计数。忙碌中的工具会以黄色高亮（如 SqThink(2)）。
  • Deamon Commands：后台运行的 demo 命令列表（带开始时间与已运行时长）。

• Status 面板（右上）

  • 显示 API 与代理状态摘要，以及当前面板尺寸参数（便于调节布局时参考）。

• Messages 面板（右上中）

  • 实时消息流（模型回复、工具输出、系统提示）。
  • 支持焦点与滚动控制，标题会显示“当前/总计”的消息定位。例如：Messages (123/456)。

• Console（底部）

  • Output：命令与系统输出区域，支持分页浏览。
  • Input：命令输入行（默认提示符 “(UnityChip) ”）。提供历史、补全、忙碌提示等。

提示：界面每秒自动刷新一次（不影响输入）。当消息或输出过长时，会进入分页或手动滚动模式。

操作与快捷键

• Enter：执行当前输入命令；若输入为空会重复上一次命令；输入 q/Q/exit/quit 退出 TUI。
• Esc：
  • 若正在浏览 Messages 的历史，退出滚动并返回末尾；
  • 若 Output 正在分页查看，退出分页；
  • 否则聚焦到底部输入框。
• Tab：命令补全；再次按 Tab 可分批显示更多可选项。
• Shift+Right：清空 Console Output。
• Shift+Up / Shift+Down：在 Messages 中向上/向下移动焦点（浏览历史）。
• Ctrl+Up / Ctrl+Down：增/减 Console 输出区域高度。
• Ctrl+Left / Ctrl+Right：减/增 Mission 面板宽度。
• Shift+Up / Shift+Down（另一路径）：调整 Status 面板高度（最小 3，最大 100）。
• Up / Down：
  • 若 Output 在分页模式，Up/Down 用于翻页；
  • 否则用于命令历史导航（将历史命令放入输入行，可编辑后回车执行）。

分页模式提示：当 Output 进入分页浏览时，底部标题会提示 “Up/Down: scroll, Esc: exit”，Esc 退出分页并返回输入状态。

命令与用法

• 普通命令：直接输入并回车，例如 loop、tui、help 等（由内部调试器处理）。
• 历史命令：在输入行为空时按 Enter，将重复执行上一条命令。
• 清屏：输入 clear 并回车，仅清空 Output（不影响消息记录）。
• 演示/后台命令：命令末尾添加 & 将在后台运行，完成后会在 Output 区域提示结束；当前后台命令可通过 list_demo_cmds 查看。
• 直接执行系统/危险命令：以 ! 前缀执行（例如 !loop），该模式执行后优先滚动到最新输出。
• 列出后台命令：list_demo_cmds 显示正在运行的 demo 命令列表与开始时间。

消息配置（message_config）

• 作用：在运行中查看/调整消息裁剪策略，控制历史保留与 LLM 输入 token 上限。
• 命令：
  • message_config 查看当前配置
  • message_config 设置配置项
• 可配置项：
  • max_keep_msgs：保留的历史消息条数（影响会话记忆窗口）
  • max_token：进入模型前的消息裁剪 token 上限（影响开销/截断）
• 示例：
  • message_config
  • message_config max_keep_msgs 8
  • message_config max_token 4096

其他说明

• 自动补全：支持命令名与部分参数的补全；候选项过多时分批显示，可多次按 Tab 查看剩余项。
• 忙碌提示：命令执行期间，输入框标题会轮转显示 (wait.), (wait..), (wait…)，表示正在处理。
• 消息焦点：当未手动滚动时，消息焦点自动跟随最新消息；进入手动滚动后，会保持当前位置，直至按 Esc 或滚动至末尾。
• 错误容错：若某些 UI 操作异常（如终端不支持某些控制序列），TUI 会尽量回退到安全状态继续运行。

6 - FAQ

FAQ

• 模型切换：在 config.yaml 改 openai.model_name
• 验证过程中出现错误怎么办：使用 Ctrl+C 进入交互模式，通过 status 查看当前状态，使用 help 获取调试命令。
• Check 失败：先 ReadTextFile 阅读 reference_files；再按返回信息修复，循环 RunTestCases → Check
• 自定义阶段：修改 vagent/lang/zh/config/default.yaml 的 stage；或用 --override 临时覆盖
• 添加工具：vagent/tools/ 下新建类，继承 UCTool，运行时 --ex-tools YourTool
• MCP 连接失败：检查端口/防火墙，改 --mcp-server-port；无嵌入可加 --no-embed-tools
• 只读保护：通过 --no-write/--nw 指定路径限制写入（必须位于 workspace 内）

为什么快速启动找不到config.yaml/定制流程时找不到config.yaml?

• 使用pip 安装后并没有config.yaml那个文件，所以在快速启动的启动 MCP Server没有加--config config.yaml这个选项。
• 可以通过在工作目录添加config.yaml文件并且加上--config config.yaml参数来启动；也可以使用克隆仓库来使用UCAgent的方式来解决。

运行中如何调整消息窗口与 token 上限？

• 在 TUI 输入：message_config 查看当前配置；
• 设置：message_config max_keep_msgs 8 或 message_config max_token 4096；
• 作用范围：影响会话历史裁剪与送入 LLM 的最大 token 上限（通过 Summarization/Trim 节点生效）。

文档中的 “CK bug” 要改吗？

• 是。术语统一为 “TC bug”。同时确保 bug 文档里的 <TC-*> 能匹配失败用例（文件/类/用例名）。

为什么找不到 WriteTextFile 工具？

• 该工具已移除。请改用 EditTextFile（支持 overwrite/append/replace 三种模式）或其他文件工具（Copy/Move/Delete 等）。