核心功能
专业 Agents
Agents（智能体）是专门化的 AI 助手，主 Agent 可以将复杂任务委派给它们。每个 Agent 在自己的上下文窗口中运行，拥有独立的系统提示和专属工具权限，处理完成后将结果返回给父 Agent。
核心优势
| 优势 | 说明 |
|---|---|
| 上下文隔离 | 将探索和实现工作隔离在独立对话中，避免主对话上下文混乱 |
| 强制约束 | 限制 Agent 可使用的工具范围，确保操作安全可控 |
| 复用配置 | 跨项目共享 Agent 配置，提升团队协作效率 |
| 专业化行为 | 针对特定领域定制系统提示，提供专业级支持 |
| 控制成本 | 将任务路由到更快速、经济的模型，优化资源使用 |
使用方法
唤起 Agent
在对话框中输入 @ 可唤起智能体列表，选择目标 Agent 即可开始专业化协作。
调用方式
自动调用：Agent 会根据任务复杂度和 Agent 的描述自动委派匹配的任务。
显式调用：在对话中使用 @名称 语法直接指定：
@code-reviewer 审查支付模块
@bug-analyzer 调查这个报错
@dev-planner 拆解用户注册功能的开发计划
并行执行：可同时启动多个 Agent 并行处理不同任务：
并行审查 API 变更并更新文档
内置 Agents
Z Code 包含多个内置 Agent，可在适当场景自动调用：
| Agent | 说明 |
|---|---|
| bug-analyzer | 专业的调试专家，专注于深度代码执行流程分析和根因调查 |
| code-reviewer | 代码审查专家，擅长安全漏洞检测、性能优化和生产可靠性保障 |
| dev-planner | 开发规划师，将需求拆解为可执行的开发计划，包含任务分解、依赖分析和时间线估算 |
| story-generator | 用户故事生成专家，从 git diff、PRD 文档等生成包含验收标准的用户故事 |
| ui-sketcher | UI 蓝图工程师，将功能需求转化为可视化 ASCII 界面设计和交互规范 |
自定义 Agent
你可以通过两种方式创建自定义 Agent：设置界面或配置文件。
方式一：通过设置界面
从设置进入 智能体 管理界面，你可以查看所有可用的 Agents（内置、用户级、项目级），并进行编辑、删除或创建操作。
点击 添加新智能体，按照界面提示填写各字段即可：
方式二：通过配置文件
你也可以通过 Markdown 文件创建 Agent，支持两种作用域：
| 类型 | 位置 | 适用范围 |
|---|---|---|
| 项目级 | .zcode/agents/ | 仅当前项目 |
| 用户级 | ~/.zcode/agents/ | 所有项目 |
创建一个带有 YAML 前置信息的 .md 文件：
---
name: security-auditor
description: 安全专家。用于实现身份验证、支付或处理敏感数据时使用。
model: inherit
---
你是一位安全专家，负责审查代码漏洞。
执行时：
1. 识别安全敏感的代码路径
2. 检查常见漏洞（注入、XSS、身份验证绕过）
3. 验证密钥未硬编码
4. 审查输入验证和清理
按严重程度报告发现：
- 关键（部署前必须修复）
- 高（尽快修复）
- 中（有空时处理）
配置字段说明：
| 字段 | 必填 | 说明 |
|---|---|---|
| name | 否 | 唯一标识符，使用小写字母和连字符 |
| description | 否 | 描述何时使用此 Agent，决定自动调用时机 |
| model | 否 | 使用的模型：fast、inherit 或特定模型 ID |
常见 Agent 示例
验证器（Verifier）
---
name: verifier
description: 验证已完成的工作。在任务标记为完成后使用，确认实现确实可用。
model: fast
---
你是一个严谨的验证者。你的工作是验证声称已完成的工作是否真正可用。
执行时：
1. 识别声称已完成的内容
2. 检查实现是否存在且可用
3. 运行相关测试或验证步骤
4. 寻找可能被遗漏的边缘情况
调试器（Debugger）
---
name: debugger
description: 错误和测试失败的调试专家。遇到问题时使用。
---
你是根因分析方面的专家调试器。
执行时：
1. 捕获错误消息和堆栈跟踪
2. 识别重现步骤
3. 定位失败位置
4. 实施最小修复
5. 验证解决方案有效
测试运行器（Test Runner）
---
name: test-runner
description: 测试自动化专家。主动运行测试并修复失败。
---
你是测试自动化专家。
看到代码更改时，主动运行适当的测试。
如果测试失败：
1. 分析失败输出
2. 识别根本原因
3. 在保留测试意图的同时修复问题
4. 重新运行以验证
使用建议
| ✅ 推荐 | ❌ 避免 |
|---|---|
| 每个 Agent 专注于单一、明确的职责 | 模糊的描述（如「用于一般任务」） |
| 在 描述 字段投入时间——它决定自动调用时机 | 过长的提示词（2000+ 字） |
| 保持系统提示词简洁明了 | 创建太多通用 Agent |
将 .zcode/agents/ 加入版本控制 | 与 Commands 功能重复 |
| 从 2-3 个重点 Agent 开始，逐步扩展 |
主对话 vs Agents
| 使用主对话 | 使用 Agents |
|---|---|
| 需要频繁迭代和交互式优化 | 任务产生大量不需要保留在主对话中的输出 |
| 多个阶段共享大量上下文 | 需要强制特定的工具限制或权限 |
| 快速、针对性的修改 | 工作是自包含的，可返回摘要结果 |
| 延迟敏感的操作 | 需要跨多个步骤的专业知识 |
| 并行运行多个独立工作流 |