UCAgent 架构与工作原理¶

在开始定制自己的工作流之前，了解 UCAgent 的整体架构和工作原理至关重要。本章将为您揭示 UCAgent 的内部运作机制，帮助您建立全局认知。

UCAgent 是什么？¶

UCAgent 是一个基于大语言模型（LLM）的智能验证代理系统。它通过工作流（Workflow）定义验证任务，利用工具（Tools）执行操作，通过检查器（Checkers）验证质量，参考模板（Templates）保证规范，最终实现自动化的验证流程。

核心架构¶

UCAgent 由三大核心组件构成，它们相互协作完成验证任务：

┌─────────────────────────────────────────────────────────────┐
│                        UCAgent 系统                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│                      ┌──────────────┐                       │
│                      │    Stage     │                       │
│                      │   Manager    │                       │
│                      │  (阶段管理器) │                       │
│                      └──────┬───────┘                       │
│                             │                                │
│                             │                                │
│                             ▼                                │
│                 ┌───────────────────────┐                   │
│                 │   Stage 1: 分析项目    │                   │
│                 │   - Task 列表          │                   │
│                 │   - Reference Files   │                   │
│                 │   - Tools             │                   │
│                 │   - Checkers          │                   │
│                 └───────────────────────┘                   │
│                             │                                │
│         ┌───────────────────┼───────────────────────┐       │
│         │                   │                       │       │
│         ▼                   ▼                       ▼       │
│  ┌─────────────┐    ┌─────────────┐        ┌─────────────┐ │
│  │  Templates  │    │    Tools    │        │  Checkers   │ │
│  │  (模板文件)  │    │   (工具集)   │        │  (检查器)    │ │
│  │             │    │             │        │             │ │
│  │ - 指导文档   │    │ - 文件操作   │        │ - 格式检查   │ │
│  │ - 规范定义   │    │ - 自定义工具 │        │ - 业务验证   │ │
│  └─────────────┘    └─────────────┘        └─────────────┘ │
│                                                              │
└─────────────────────────────────────────────────────────────┘

1. Stage Manager（阶段管理器）¶

作用：管理工作流的执行流程，负责阶段（Stage）的推进和状态追踪。

核心职责：

加载和解析工作流配置
按顺序执行各个阶段
管理阶段间的数据共享
控制阶段的跳过和重试

2. Tools（工具）¶

作用：为 Agent 提供执行能力，完成具体的操作任务。

💡 详细说明：关于内置工具的完整列表，请参考工具列表；关于自定义工具开发，请参考定制工具

工具类型：

内置工具：文件读写、文本搜索、目录操作等通用功能
自定义工具：领域专用的工具，如 RTL 解析、仿真执行等

工具调用时机：Agent 在执行任务时，根据需要主动调用工具。

3. Checkers（检查器）¶

作用：验证阶段输出的质量，确保符合预期标准。

💡 详细说明：关于检查器的完整说明，请参考检查器

检查器类型：

格式检查器：验证文件格式、文档结构等
业务检查器：验证特定业务规则和逻辑正确性

检查器执行时机：阶段任务完成后，自动执行配置的检查器。

4. Templates（模板）¶

💡 详细说明：关于模板文件系统的完整介绍，请参考模板文件与生成产物

作用：为 Agent 提供参考规范，指导生成符合要求的输出。

模板用途：

定义文档结构和格式要求
提供示例和最佳实践
说明命名规范和约定

模板使用方式：在阶段配置中通过 reference_files 字段引用。

配置文件体系¶

UCAgent 采用三层配置体系，支持灵活的配置管理：

┌──────────────────────────────────────────────────────┐
│  1. 系统默认配置 (ucagent/setting.yaml)              │
│     - 提供所有配置项的默认值                           │
│     - 定义内置工具和检查器                             │
├──────────────────────────────────────────────────────┤
│  2. 用户配置 (~/.ucagent/setting.yaml)               │
│     - 用户全局配置，对所有项目生效                     │
│     - 配置 Backend、API Key 等个人信息                │
├──────────────────────────────────────────────────────┤
│  3. 项目配置 (项目根目录的 config.yaml)                │
│     - 项目特定的配置，优先级最高                       │
│     - 定义工作流、自定义工具、模板变量等               │
└──────────────────────────────────────────────────────┘

配置优先级：项目配置 > 用户配置 > 系统默认配置

示例：如果三层配置都定义了 backend.key_name，最终使用项目配置中的值。

工作流程详解¶

现在让我们通过计算器文档生成器这个实际场景，详细了解 UCAgent 的完整执行流程：

场景描述¶

我们要为一个计算器项目自动生成文档，工作流包含两个阶段（Stage）：

阶段1：分析计算器项目，提取功能点
阶段2：生成完整的项目文档

执行流程（7个步骤）¶

graph TD
    %% 全局样式定义
    classDef step fill:#f9f9f9,stroke:#333,stroke-width:2px;
    classDef highlight fill:#e1f5fe,stroke:#01579b;

    Start((启动 ucagent)) --> Step1

    subgraph Initialization [初始化阶段]
        Step1["【步骤1：加载配置】<br/>读取 mini.yaml<br/>解析工作流 & 模板变量"]:::step
        Step2["【步骤2：初始化组件】<br/>启动 LangChain<br/>注册内置/自定义工具"]:::step
    end

    Step1 --> Step2
    Step2 --> Step3

    subgraph LoopSection [阶段循环]
        Step3["【步骤3：进入阶段循环】<br/>Stage Manager 设定当前阶段任务"]:::step
        Step4["【步骤4：读取参考文件】<br/>获取分析指南 & 输出格式模板"]:::step
        Step5["【步骤5：Agent 执行任务】<br/>调用工具: Read/Edit/Count"]:::step
        Step6["【步骤6：执行检查器验证】<br/>字数检查 & 格式验证"]:::step

        Step3 --> Step4
        Step4 --> Step5
        Step5 --> Step6
    end

    Step6 --> Step7{"【步骤7：推进】<br/>检查通过?"}

    Step7 -- "未完成/失败" --> Step3
    Step7 -- "所有阶段完成" --> Finish((任务完成！)):::highlight

    %% 连线注释
    style Start fill:#ececff,stroke:#9370db

关键机制说明¶

阶段（Stage）推进机制¶

阶段的推进遵循以下规则：

任务执行：Agent 根据 task 列表执行任务
主动检查：Agent 调用 Check 工具检查当前阶段状态（不推进）
完成推进：Agent 调用 Complete 工具，执行检查器并尝试推进
检查器验证：所有配置的检查器都返回 True 才能推进
循环执行：推进到下一阶段，重复步骤3-7

工具调用机制¶

Agent 自主决定何时调用哪些工具
工具通过 ex_tools 在配置中注册
工具接收参数，执行操作，返回结果给 Agent

检查器验证机制¶

检查器在阶段的 checker 列表中配置
检查器返回 (bool, dict)：
- True 表示检查通过
- False 表示检查失败，阻止阶段推进
失败时，Agent 会根据错误信息修正输出并重试

模板引用机制¶

模板通过 reference_files 字段引用
Agent 在执行任务前会读取模板内容
模板中的变量（如 {PROJECT}）会自动替换为实际值

数据流示意¶

配置文件 (mini.yaml)
    │
    ├──> Backend 配置 ──> 连接 LLM
    ├──> ex_tools ──> 注册自定义工具
    ├──> template_overwrite ──> 定义变量
    │
    └──> stage 列表
            │
            ├──> Stage 1
            │     ├─> task ──> Agent 执行任务
            │     ├─> reference_files ──> Agent 读取模板
            │     ├─> skill_list ──> 阶段必用技能
            │     ├─> output_files ──> 预期输出
            │     └─> checker ──> 验证输出质量
            │
            └──> Stage 2
                  └─> ...（同上）

与传统脚本的区别¶

维度	传统脚本	UCAgent
任务定义	写死的代码逻辑	自然语言描述的任务列表
执行方式	顺序执行固定步骤	Agent 智能决策和工具调用
灵活性	修改需要改代码	修改配置文件即可
容错能力	遇错即停	Agent 可根据检查器反馈自动修正
适应性	针对特定场景	通过模板适应不同项目

小结¶

通过本章，您应该已经理解了：

✅ UCAgent 的四大核心组件及其职责
✅ 配置文件的三层体系和优先级
✅ 从启动到完成的完整执行流程
✅ 阶段推进、工具调用、检查器验证的机制

下一步：继续阅读工作流配置

延伸阅读¶

定制工具 - 了解如何开发自定义工具
快速开始 - 快速创建自己的工作流
Mini 示例 - 完整的可运行示例

工作流详细文档 - 深入了解工作流机制
模板文件详细文档 - 学习如何编写模板