> 内容来源：Onevium 官方文档
> 文章: 创建边界清楚的专门 Agent
> 原文: https://onevium.com/zh/docs/agents
> 语言：简体中文
> 更新于: 2026-09-09
> 适用版本: 1.1.22
> 功能状态: 已发布

---

# 创建边界清楚的专门 Agent

定义角色、工具范围与交付标准，并验证一次委派任务。

## 给重复工作一个专门角色

Agent 把职责说明、模型、工具范围和指令组合起来。本教程创建 `docs-reviewer`：读取 Markdown、报告问题，不直接修改文件。

## 选择项目和创建方式

先选择项目。**@Agent**会在输入框插入创建标签，发送后才开始创建；右侧 **Agents → 创建 Agent**快捷入口也是同一对话流程。

项目定义位于 `.claude/agents/名称.md`，个人定义位于 `~/.claude/agents/名称.md`。完整 Agent 管理页还提供空白、代码审查、测试运行、文档编写模板。下面直接给出配置，让工具权限与练习任务一致。

## 创建文档审查 Agent

1. 选择 **@Agent**，要求：“按下方定义创建项目文件 `.claude/agents/docs-reviewer.md`；已有同名文件时先展示差异，不直接覆盖。”
2. 附上完整定义：

```markdown
---
name: docs-reviewer
description: 检查指定 Markdown 中含糊的操作步骤和失效的本地链接。
model: inherit
tools: Read, Grep, Glob
disallowedTools: Write, Edit, Bash
permissionMode: default
maxTurns: 12
---
只读取本次指定的文件。
报告不清楚的操作说明，以及找不到目标的本地链接。
每项包含文件、位置和依据；列出无法检查的内容。
不要修改文件。
```

3. 检查生成文件。从右侧 **Agents**列表打开它，可修改配置和指令正文；编辑后点击**保存**。
4. 尚未加载时新建会话，再对一份已有 Markdown 发起审查。

## 配置字段怎么填

| 字段               | 作用与选择方法                                                        |
| ---------------- | -------------------------------------------------------------- |
| 名称               | 对应定义文件名，使用字母、数字、连字符或下划线                                        |
| 描述               | 说明何时应委派给它，写具体任务                                                |
| 模型               | `inherit` 跟随主会话；指定模型别名时仍受提供商配置影响                               |
| Tools            | 允许的工具，逗号分隔；本例只需 Read、Grep、Glob                                 |
| Disallowed Tools | 明确禁用项；本例不用 Write、Edit、Bash                                     |
| Permission Mode  | SDK 字段，使用 `default`、`plan` 等值，不填写聊天标签 `code/ask`；本例用 `default` |
| Max Turns        | 限制 Agent 迭代轮数，按文件数量调整                                          |
| Memory           | 可选 `user` 或 `project` 记忆范围；首次练习留空                              |
| Skills           | 预加载的现有 Skill 名称；没有需要时留空                                        |

编辑器提供**编辑、预览、分屏**。预览用于检查排版，不会运行 Agent。

## 委派并核对结果

```text
把 README.md 委派给 docs-reviewer。
报告含糊的安装步骤和失效相对链接，并给出位置。
先不要修复；无法检查的目标请说明。
```

查看实际委派记录，再抽查一个问题和一个正常链接。预期结果是基于文件的报告，文件保持不变。独立 Agent 上下文不会自动复制或隔离项目文件。

## 常见问题

- 找不到 Agent：检查 `.claude/agents/`、文件名、作用域和保存结果，再试新会话。
- 工具被拒绝：对照 Tools 与禁用项；本例不能执行终端命令是预期行为。
- 模型不可用：改为 `inherit`，或使用该提供商实际可选的模型。
- 提前结束：先缩小文件清单，核对未完成项后再增加 Max Turns。

## 下一步

把重复审查步骤写成 [Skill](https://onevium.com/zh/docs/skills)，比较[扩展方式](https://onevium.com/zh/docs/skills-and-agents)，添加写入工具前了解[权限](https://onevium.com/zh/docs/permissions)。