代理配置文件

AggRoot 的代理系统通过 JSON 配置文件定义代理的行为、工具权限、人设等。本章详细介绍代理配置的各个字段。

配置文件结构

代理配置是一个 JSON 文件，包含代理的所有定义信息：

{
  "name": "agent-coder",
  "version": "1.0.0",
  "description": "通用编码代理",
  "agent_type": "task_oriented",
  "approval_mode": "safe_only",
  "tools": ["Read", "Write", "Edit", "Glob", "Grep", "Shell", "DirectoryTree"],
  "loop": {
    "max_iterations": 50,
    "on_error": "ask"
  },
  "identity": "你是一个专业的编程助手...",
  "personality": ["严谨", "高效", "注重代码质量"],
  "speaking_style": ["简洁", "技术性", "不啰嗦"],
  "behavior_guidelines": [
    "优先使用专用工具而非 Shell 命令",
    "修改代码前先读取理解现有代码",
    "每次修改后运行测试验证"
  ],
  "prohibited_actions": [
    "不要删除 .env 文件",
    "不要修改 package-lock.json"
  ],
  "thinking_examples": [
    {
      "task": "修复 Bug",
      "reasoning": "先分析错误信息，定位相关代码，理解上下文，再应用最小修复",
      "action": "使用 /debug 技能分析错误，然后用 Edit 工具修复"
    }
  ],
  "examples": [
    {
      "user": "帮我修复这个 TypeError",
      "assistant": "我来分析这个错误。首先让我找到相关的代码文件..."
    }
  ]
}

字段详解

name — 代理名称

类型: string
必填: 是
说明: 代理的唯一标识符，用于选择和切换代理

"name": "agent-coder"

命名建议使用小写字母和连字符，如 explore、code-reviewer、plan-agent。

version — 版本号

类型: string
格式: 语义化版本 X.Y.Z
必填: 否

"version": "1.0.0"

description — 描述

类型: string
必填: 否
说明: 代理的简要描述，用于在代理列表中展示

"description": "通用编码代理，擅长代码编写、重构和调试"

agent_type — 代理类型

类型: string
必填: 否
可选值:

类型	说明
`task_oriented`	任务导向型，专注于完成特定任务
`conversational`	对话型，适合自由交流和问答

"agent_type": "task_oriented"

task_oriented — 适合编码、修复 Bug、重构等需要多步操作的任务。代理会主动使用工具、规划步骤、验证结果。

conversational — 适合问答、解释、讨论等对话场景。代理更注重交互体验，减少不必要的工具调用。

approval_mode — 审批模式

类型: string
必填: 否
可选值:

模式	说明
`auto`	自动执行所有操作（YOLO 模式）
`safe_only`	低风险自动执行，中高风险需确认
`always_ask`	所有操作都需要确认

"approval_mode": "safe_only"

tools — 工具列表

类型: string[]
必填: 否
说明: 代理可以使用的工具列表

"tools": ["Read", "Write", "Edit", "Glob", "Grep", "Shell", "DirectoryTree"]

可选工具包括：

类别	工具
文件操作	`Read`, `Write`, `Edit`, `Glob`, `Grep`, `DirectoryTree`
代码工具	`CodeExecute`, `CodeValidate`, `CodeFormat`, `CodeAnalyze`, `CodeSearch`, `CodeRefactor`
Shell	`Shell`
Git	`GitStatus`, `GitDiff`, `GitLog`, `GitBranch`, `GitAdd`, `GitCommit`, `GitPush`, `GitPull`
网络	`WebSearch`, `WebFetch`, `HttpRequest`
技能	`Skill`, `ListSkills`
用户交互	`AskUser`

loop — 循环配置

类型: object
必填: 否
说明: 控制代理循环（Agent Loop）的行为

"loop": {
  "max_iterations": 50,
  "maxCallHistory": 100,
  "loopThreshold": 3,
  "loopTimeWindowMs": 60000,
  "on_error": "ask",
  "hooks": []
}

字段	类型	说明
`max_iterations`	integer	最大迭代次数（默认 50）
`maxCallHistory`	integer	最大调用历史记录数
`loopThreshold`	integer	循环检测阈值
`loopTimeWindowMs`	integer	循环检测时间窗口（毫秒）
`on_error`	string	错误处理策略：`retry`（重试）/ `abort`（中止）/ `ask`（询问）
`hooks`	string[]	循环钩子

identity — 身份/人设

类型: string
必填: 否
说明: 代理的系统提示词主体，定义代理的核心身份和行为准则

"identity": "你是一个专业的编码助手。你的目标是帮助用户高效地完成编程任务。\n\n核心原则：\n1. 先理解需求，再动手实现\n2. 保持代码简洁可读\n3. 修改前先读取理解现有代码\n4. 每次修改后验证结果"

这是代理配置中最重要的字段，直接影响代理的行为质量。

personality — 性格特征

类型: string[]
必填: 否
说明: 定义代理的性格标签

"personality": ["严谨", "高效", "注重代码质量", "善于分析"]

speaking_style — 说话风格

类型: string[]
必填: 否
说明: 定义代理的沟通风格

"speaking_style": ["简洁", "技术性", "不啰嗦", "中文为主"]

behavior_guidelines — 行为指导

类型: string[]
必填: 否
说明: 具体的行为规则，代理在执行任务时应遵循

"behavior_guidelines": [
  "优先使用专用工具而非 Shell 命令",
  "修改代码前先读取理解现有代码",
  "每次修改后运行测试验证",
  "使用 Edit 而非 Write 修改现有文件",
  "不要一次性修改超过 3 个文件"
]

prohibited_actions — 禁止操作

类型: string[]
必填: 否
说明: 明确禁止代理执行的操作

"prohibited_actions": [
  "不要删除 .env 文件",
  "不要修改 package-lock.json",
  "不要执行 git push --force",
  "不要在生产环境执行破坏性操作"
]

thinking_examples — 思考示例

类型: array
必填: 否
说明: 展示代理在面对任务时的思考过程，帮助模型学习推理方式

"thinking_examples": [
  {
    "task": "修复 Bug",
    "reasoning": "先分析错误信息，定位相关代码，理解上下文，再应用最小修复",
    "action": "使用 /debug 技能分析错误，然后用 Edit 工具精确修复"
  },
  {
    "task": "重构代码",
    "reasoning": "先全面理解代码结构，制定重构计划，逐步修改并持续测试",
    "action": "进入 Plan Mode，制定步骤，逐步用 Edit 修改"
  }
]

examples — 对话示例

类型: array
必填: 否
说明: 提供用户与代理的对话示例，帮助模型理解期望的交互方式

"examples": [
  {
    "user": "帮我修复这个 TypeError",
    "assistant": "我来分析这个错误。首先让我找到相关的代码文件..."
  },
  {
    "user": "重构这个模块",
    "assistant": "好的，让我先了解这个模块的结构和依赖关系..."
  }
]

memory — 记忆配置

类型: object
必填: 否
说明: 控制代理的记忆管理

"memory": {
  "sensorySize": 10,
  "shortTermSize": 50,
  "enableVectorSearch": false
}

示例：agent-coder.json 完整解析

以下是一个完整的编码代理配置，逐字段解析：

{
  // 基本信息
  "name": "agent-coder",           // 代理标识，用于 /switch 或 # 选择
  "version": "1.0.0",              // 语义化版本
  "description": "通用编码代理，擅长代码编写、重构和调试",

  // 行为类型 — task_oriented 适合需要多步操作的任务
  "agent_type": "task_oriented",

  // 安全模式 — 低风险自动执行，中高风险需确认
  "approval_mode": "safe_only",

  // 允许使用的工具
  "tools": [
    "Read", "Write", "Edit", "Glob", "Grep",
    "Shell", "DirectoryTree", "CodeExecute",
    "GitStatus", "GitDiff", "GitLog", "GitCommit",
    "WebSearch", "AskUser", "Skill"
  ],

  // 循环控制
  "loop": {
    "max_iterations": 50,          // 最多 50 轮工具调用
    "on_error": "ask"              // 出错时询问用户
  },

  // 系统提示词 — 定义代理的核心身份
  "identity": "你是一个专业的编码助手。你的目标是帮助用户高效地完成编程任务。\n\n核心原则：\n1. 先理解需求，再动手实现\n2. 保持代码简洁可读\n3. 修改前先读取理解现有代码\n4. 每次修改后验证结果",

  // 性格标签
  "personality": ["严谨", "高效", "注重代码质量"],

  // 说话风格
  "speaking_style": ["简洁", "技术性", "不啰嗦"],

  // 行为指导 — 具体的规则
  "behavior_guidelines": [
    "优先使用专用工具而非 Shell 命令",
    "使用 Edit 而非 Write 修改现有文件",
    "修改代码前先读取理解现有代码",
    "每次修改后运行测试验证"
  ],

  // 禁止操作 — 绝对不能做的事
  "prohibited_actions": [
    "不要删除 .env 文件",
    "不要执行 git push --force"
  ],

  // 思考示例 — 教模型如何推理
  "thinking_examples": [
    {
      "task": "修复 Bug",
      "reasoning": "先分析错误信息，定位相关代码，理解上下文，再应用最小修复",
      "action": "使用 /debug 技能分析错误，然后用 Edit 修复"
    }
  ],

  // 对话示例 — 展示期望的交互方式
  "examples": [
    {
      "user": "帮我修复这个 TypeError",
      "assistant": "我来分析这个错误。首先让我找到相关的代码文件..."
    }
  ]
}

自定义代理

除了 JSON 配置，AggRoot 还支持通过 Markdown 文件创建自定义代理。

代理文件目录

层级	路径	作用
项目级	`.aggroot/agents/*.md`	仅对当前项目生效
全局级	`~/.aggroot/agents/*.md`	对所有项目生效

Markdown 代理格式

在 .aggroot/agents/ 目录下创建 Markdown 文件，使用 YAML frontmatter：

---
name: my-custom-agent
description: 自定义代理描述
whenToUse:
  - 当需要执行特定类型的任务时
whenNotToUse:
  - 不适合的场景
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
preferredModel: deepseek-v4-flash
approvalMode: safe_only
personality:
  - 严谨
  - 高效
behaviorGuidelines:
  - 先理解需求再动手
  - 保持代码简洁
prohibitedActions:
  - 不要删除重要配置文件
---

## 代理身份

你是一个专注于 [特定领域] 的编程助手。

## 核心原则

1. 原则一
2. 原则二
3. 原则三

## 工作流程

1. 接收任务
2. 分析需求
3. 制定计划
4. 逐步执行
5. 验证结果

Frontmatter 字段

字段	类型	说明
`name`	string	代理名称
`description`	string	代理描述
`whenToUse`	string[]	推荐使用场景
`whenNotToUse`	string[]	不推荐使用场景
`tools`	string[]	允许使用的工具
`preferredModel`	string	偏好的模型
`approvalMode`	string	审批模式
`personality`	string[]	性格特征
`behaviorGuidelines`	string[]	行为指导
`prohibitedActions`	string[]	禁止操作

Markdown 正文部分即为代理的系统提示词（identity）。

内置代理

AggRoot 预装以下内置代理：

代理名	类型	说明
`coding`	task_oriented	通用编码代理（默认）
`explore`	task_oriented	代码探索，快速扫描结构
`plan`	task_oriented	制定执行计划
`code-reviewer`	task_oriented	代码审查
`risk-control`	task_oriented	安全风险控制
`verification`	task_oriented	验证测试结果

← 上一篇

CLI 参考

跨平台支持