AggRoot
文档目录

代理系统

AggRoot 采用多代理架构，每个代理专注于特定领域。本文档介绍内置代理、子代理系统以及自定义代理的创建方法。

内置代理

代理名称 类型 定位 核心工具
code之神 task_oriented 专业编程助手 Read, Write, Edit, Glob, Grep, CodeExecute, Git 工具, Shell, WebSearch, SubagentExecutor
内容创作助手 conversational 文案创作、PPT、Word Read, Write, WebSearch, WebFetch, MCP 工具
运维大师 task_oriented 系统运维专家 Shell, Read, Write, Edit, Glob, Grep, WebSearch

代理类型

AggRoot 的代理分为两种类型：

task_oriented（任务导向）

  • 拥有完整的工具执行能力，包括 SubagentExecutor
  • 适合需要代码读写、命令执行等操作的任务
  • code之神 和 运维大师 属于此类型
  • 审批模式：auto（自动）或 safe_only（仅安全操作自动）

conversational（对话导向）

  • 以对话交互为核心，不创建子代理
  • 工具集更精简，专注于内容获取和创作
  • 内容创作助手 属于此类型
  • 更适合连续对话和内容生成场景

切换代理

快捷键切换

按下 # 键，从弹出的代理列表中选择。

命令切换

你> /agents

查看可用代理列表并切换。

Tips: 不同代理的上下文是独立的。切换代理后，之前的对话历史会保留在原代理的会话中。

子代理系统（SubagentExecutor）

子代理是主代理通过 SubagentExecutor 工具创建的临时代理，用于执行特定子任务。

可用子代理类型

类型 名称 工具 用途
explore Explore Glob, Grep, Read（只读） 快速探索代码库、搜索实现、了解架构
plan Plan Glob, Grep, Read（只读） 架构规划、设计方案
code-reviewer Code Reviewer Glob, Grep, Read（只读） 代码审查、质量分析、安全检测
verification Verification Read, Glob, Grep, Shell 对抗性验证、测试
general-purpose - 继承父代理全部工具 多步骤通用任务

工作流程

主代理 → SubagentExecutor({subagent_type: "explore", prompt: "探索认证模块"})
       → ForkSubagentService.fork()
       → 创建子代理（继承工具 + 共享缓存）
       → 子代理独立运行 AgentLoop
       → 返回精简摘要 + 缓存文件内容
       → 主代理使用结果继续工作
  1. 主代理的 LLM 决定调用 SubagentExecutor
  2. ForkSubagentService 创建子代理，继承父代理的工具实例
  3. 子代理拥有独立的 AgentLoop，自主运行（默认最多 10 轮迭代）
  4. 子代理完成后，返回完整的文本输出作为工具结果
  5. 主代理直接使用结果，不重复探索

使用示例

探索代码库：

你> 熟悉这个项目的认证模块

AggRoot → DirectoryTree(depth=2)
        → SubagentExecutor(subagent_type: 'explore', description: '探索认证模块',
                           prompt: '探索认证相关的代码文件和接口定义')

代码审查：

你> 审查最近修改的代码质量

AggRoot → SubagentExecutor(subagent_type: 'code-reviewer',
                           description: '代码审查',
                           prompt: '审查最近修改的代码，检查代码质量、潜在问题和改进建议')

复杂任务分解：

你> 帮我实现用户登录功能

AggRoot → SubagentExecutor(subagent_type: 'explore', prompt: '查找路由、认证、用户模块相关的代码')
        → SubagentExecutor(subagent_type: 'plan', prompt: '设计用户登录功能的实现方案')
        → [主代理执行代码修改]

并行执行

explore 和 plan 是只读子代理，可以安全地并行运行：

AggRoot → SubagentExecutor(subagent_type: 'explore', prompt: '探索领域层')
        + SubagentExecutor(subagent_type: 'explore', prompt: '探索基础设施层')
        [两个子代理同时运行，结果汇总后主代理继续]

Tips: 探索代码库时，先用 DirectoryTree 了解项目布局，再启动多个 explore agent 并行探索不同区域，效率最高。

子代理结果信任规则

子代理返回结果后，主代理应直接使用，不要重复探索：

正确做法：

  • 信任摘要中的发现，直接使用
  • 如需查看某文件的完整代码，用 Read 工具读取（缓存会直接返回）
  • 只有当子代理说"未找到"时，才继续探索

禁止的行为：

  • 不要重新搜索子代理已找到的内容
  • 不要用 Glob/Grep 重新定位子代理已发现的文件

专业子代理详解

Explore Agent（探索代理）

  • 工具：Glob, Grep, Read（只读）
  • 核心原则：先发现，再读取
  • 工作流：Glob 发现文件 → Grep 搜索内容 → Read 读取具体文件
  • 并行优化：尽量并行调用 Glob/Grep/Read
  • 三种深度：quick（1-2 个文件）、medium（2-3 个文件）、very thorough（多文件深入探索）

Plan Agent（规划代理）

  • 工具：Glob, Grep, Read（只读）
  • 角色：架构设计、方案规划
  • 输出格式：架构概述 → 关键文件 → 实现步骤 → 依赖关系
  • 适用场景：Plan Mode 的 Phase 2 组件

Code Reviewer Agent（代码审查代理）

  • 工具：Glob, Grep, Read（只读）
  • 审查维度：安全性、性能、可维护性、测试覆盖
  • 输出：问题列表 + 改进建议

Verification Agent（验证代理）

  • 工具：Read, Glob, Grep, Shell
  • 核心哲学：不是确认代码有效，而是尝试打破它
  • 两种失败模式：
    1. 验证回避：只读代码不运行，空口说"PASS"
    2. 被前 80% 诱惑：表面正常但深层有 Bug
  • 策略：针对不同变更类型采用不同验证方法（前端/后端/CLI/库/Bug修复/重构）

RiskControl Agent（风控代理）

  • 工具：SiteRecon, DomainWhois, DomainReputation, ContentAnalysis 等风控专用工具
  • 适用场景：网站支付风控分析
  • 工作流：侦察 → 内容审查 → 跳转追踪 → 支付审计 → 欺诈指标 → 模拟验证 → 安全扫描

自定义代理

你可以在项目的 .aggroot/agents/ 目录下创建自定义代理。

创建步骤

  1. 创建 .aggroot/agents/ 目录
  2. 添加代理配置文件，格式为 JSON，与内置代理配置相同
  3. 重启 AggRoot 或输入 /agents 刷新代理列表

配置文件格式

{
  "agent": {
    "name": "我的助手",
    "version": "1.0",
    "description": "自定义助手描述",
    "agent_type": "task_oriented",
    "approval_mode": "auto",
    "tools": ["Read", "Write", "Edit", "Glob", "Grep", "Shell"],
    "loop": {
      "max_iterations": 50,
      "on_error": "retry",
      "hooks": ["experience"]
    },
    "identity": "你是一个专业的前端开发助手...",
    "personality": [
      "注重代码规范",
      "重视用户体验"
    ],
    "speaking_style": [
      "简洁明了",
      "代码优先"
    ],
    "behavior_guidelines": [
      "【工具优先原则】文件操作使用核心工具",
      "【精确编辑】优先使用 edit 而非 write"
    ],
    "prohibited_actions": [
      "禁止删除用户文件",
      "禁止执行危险命令"
    ],
    "system_prompt_sections": []
  }
}

关键字段说明

字段 类型 说明
name string 代理显示名称
agent_type task_oriented / conversational 代理类型
approval_mode auto / safe_only 审批模式
tools string[] 可用工具列表
loop.max_iterations number 最大循环次数
identity string 核心身份描述（最重要的字段）
personality string[] 性格特征列表
behavior_guidelines string[] 行为准则列表
prohibited_actions string[] 禁止行为列表
system_prompt_sections object[] 额外系统提示词段落

Tips: identity 是自定义代理最重要的字段。它决定了代理的核心能力和行为方式。参考内置代理的 identity 编写风格，保持清晰具体。

← 上一篇
工作原理
下一篇 →
记忆与上下文