参数说明

参数与选项

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 吃掉引号（示例写法已处理）