参数说明¶

参数与选项¶

UCAgent 的使用方式为：

1

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

输入¶

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

输出¶

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

对输出的详细解释可以参考快速开始的结果分析

位置参数¶

执行与交互¶

--web-console 与 --web-terminal 区别¶

使用建议： - 如果只需要通过浏览器远程访问 Agent，使用 --web-console - 如果需要在本地终端操作的同时提供 Web 访问入口，使用 --web-terminal

示例：

1
2
3
4
5
6
7

# 仅 Web 访问（无本地交互）
ucagent --web-console
ucagent --web-console 0.0.0.0:8000:mysecret

# 同时提供 Web 和本地交互
ucagent ./output Adder --web-terminal
ucagent ./output Adder --web-terminal '0.0.0.0:8818 mysecret'

配置与模板¶

计划与 ToDo¶

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

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

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

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

工具总览

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

1
2
3
4

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

1

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

1

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

1

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

1

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

外部与嵌入工具¶

日志¶

MCP Server¶

阶段控制与安全¶

Master API 与分布式¶

上下文管理¶

版本与检查¶

示例¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

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,'\
             'conversation_summary.max_summary_tokens=2048,'\
             'conversation_summary.context_management_strategy=TrimAndSummaryMiddleware,lang="zh",openai.model_name="gpt-4o-mini"' \
  --gen-instruct-file GEMINI.md \
  --guid-doc-path ./output/Guide_Doc \
  \
  --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
  • --web-console：启用浏览器 Web Console；可写 --web-console 0.0.0.0:18000[:password]
  • --web-terminal：启用 Web Terminal；可写 --web-terminal '0.0.0.0:8818 mysecret'
  • -l：启动后立即进入循环
  • --loop/--loop-msg：进入循环注入首条消息
  • --seed 12345：固定随机种子
  • --sys-tips：自定义系统提示
  • --icmd：启动时执行的初始命令
  • --no-history：禁用历史记录加载
  • --exit-on-completion：任务完成后自动退出
• 配置与模板
  • --config config.yaml：从config.yaml加载项目配置
  • --template-dir ./templates：指定模板目录为./templates
  • --template-overwrite：渲染模板时允许覆盖
  • --template-cfg-override：从 YAML 文件覆盖模板配置
  • --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
  • --use-skill：启用技能 SKILL
  • --backend：指定后端
  • --emulate-config：仅模拟配置过程
• 计划与 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路径可写
  • --ref：指定阶段参考文件
  • --append-py-path：添加 Python 路径
• Master API 与分布式
  • --as-master：作为 Master API 服务器启动
  • --master：连接到 Master API 服务器
  • --as-master-key：设置访问密钥
  • --as-master-password：设置 HTTP Basic Auth 密码
  • --export-cmd-api：导出 CMD API
• 上下文管理
  • --enable-context-manage-tools：启用上下文管理工具
• 版本与检查
  • --check 与 --version 会直接退出，未与运行组合使用
  • --upgrade：升级 UCAgent

环境变量说明¶

UCAgent 支持通过环境变量配置各类参数，环境变量优先级高于配置文件设置。

模型配置¶

嵌入模型配置¶

Langfuse 监控配置¶

对话摘要配置¶

LLM 限流配置¶

LLM 辅助建议配置¶

流程控制配置¶

测试工具配置¶