UCAgent 底层运行架构与文件调度原理¶

UCAgent 是面向芯片硬件形式化验证的 AI 调度框架，所有交互模式（MCP/TUI/Master Web）共享同一套底层验证引擎、31 阶段校验体系与文件调度机制。本章先拆解框架核心输入、多层调度文件、完整执行链路、自定义工作流规则，为后续三种交互模式实操提供理论支撑，让读者理解每一步操作背后的底层逻辑。

2.1 框架核心输入¶

启动任意验证任务，必须提供两类基础输入资源：

DUT（Design Under Test，被测设计） 待验证 Verilog RTL 硬件源码，是验证的核心对象，需通过 picker 工具编译导出为 Python 可调用动态库，框架才能完成自动化仿真、功能校验。
配置文件（默认 config.yaml） 全局运行参数载体，定义 AI 模型后端、工作目录、交互模式开关、启用的验证工作流、MCP 服务权限、各类工具超时参数；整套框架所有执行行为均由该配置驱动。

2.2 多层文件调度体系¶

UCAgent 任务调度由「工程启动层、框架配置层、任务资源层、运行产物层」四类文件协同驱动，各层级分工独立：

2.2.1 启动脚本 Makefile¶

项目根目录内置脚本，封装了简化启动命令，例如 make mcp_Adder、make as_master。执行 make 命令会自动拼接完整运行指令，同时传递自定义启动参数；命令行传入的参数会直接覆盖 config.yaml 中同名设置。

注意： - Makefile 仅存在于 git clone 得到的源码仓库中，通过 pip install 安装的包不包含该文件。 - 若不在 UCAgent 源码目录下执行 make 指令，需使用 make -C <源码目录路径> <目标> 指定源码路径，例如 make -C ~/work/UCAgent as_master。

2.2.2 各类配置文件¶

config.yaml：UCAgent 全局通用配置文件，会被各个交互模式读取，用于配置验证流程基础规则、MCP 服务相关权限。
~/.codex/config.yaml：Codex 客户端的配置文件，存放 MCP 连接相关参数，存放于用户家目录，与 UCAgent 本体配置相互独立。该文件由 Codex 客户端生成，UCAgent 本身不会创建该文件。未安装或未运行 Codex 客户端时，该目录及文件不会存在，属于正常现象。
setting.yaml：UCAgent 内置默认配置文件，位于 ucagent/setting.yaml，定义模型后端、验证阶段、工具等全部默认参数，是配置加载的第一层基底。
launch.default_env：环境变量模板文件，项目中常用来存放大模型相关的环境变量模板。

2.2.3 任务资源文件（手动上传/编写）¶

RTL 源码文件：硬件模块代码，程序通过标签区分该文件为待验证顶层设计；
README 需求文档：记录模块功能、验证目标与缺陷说明，AI 执行验证时会读取文档作为执行依据。

2.2.4 任务运行输出文件（自动生成，无需手动编辑）¶

验证结束后统一生成标准化文件夹，存放全部结果：

Guide_Doc：系统自带验证规范模板，供 AI 参考生成测试代码；
unity_test：自动产出的测试用例、缺陷分析文档；
uc_test_report：可视化覆盖率与缺陷网页报告；
.fst 波形文件：硬件仿真波形，用于人工定位代码 bug。

2.3 统一标准执行流程¶

无论选择 MCP、TUI、Web 可视化哪种操作方式，底层执行步骤完全一致：

执行启动命令，脚本加载全部配置参数；
程序读取硬件源码与验证需求文档；
调用 picker 工具编译硬件代码，生成可校验 DUT 库；
启动内置标准化验证流程，自动完成需求解析、用例生成、缺陷检测，运行过程支持人工介入调整；
全部阶段执行完成，自动输出完整验证结果文件夹。

2.4 验证工作流基础说明¶

框架内置一套完整 Formal 形式化验证流程，包含 31 个标准化校验阶段，所有新手案例均默认使用该流程。

基础使用：仅修改各类配置文件参数，调整流程运行规则；
进阶拓展：可自定义全新验证流程，需要新增流程定义文件并完成框架注册。

2.5 基础概念区分¶

交互模式：仅改变和程序对话、查看日志的操作界面，底层验证流程完全不变；
验证工作流：后台自动执行硬件校验的整套标准化步骤；
配置文件：控制程序运行规则；
Make 脚本：源码仓库内置的快捷启动脚本，简化复杂启动指令；仅在保留完整源码仓库时可用。