codebuddy --agents '{
  "code-reviewer": {
    "description": "代码审查专家。在代码更改后主动使用。",
    "prompt": "您是一位高级代码审查员。专注于代码质量、安全性和最佳实践。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "gemini-3.0-flash"
  }
}'

---
name: your-sub-agent-name
description：描述何时应该调用此子代理
tools: tool1, tool2, tool3  # 可选 - 省略则继承所有工具
model: gpt-5.1-codex  # 可选 - 指定模型别名或 'inherit'
permissionMode: default  # 可选 - 子代理的权限模式
skills: skill1, skill2  # 可选 - 自动加载的技能
---

在这里编写子代理的系统提示。可以包含多个段落，
应该清晰地定义子代理的角色、能力和解决问题的方法。

包含具体的说明、最佳实践以及子代理应该遵循的任何约束。

---
name: docs-searcher
description: 使用已有 docs MCP 做检索
tools:
  - Read
mcpServers:
  - docs
---

---
name: browser-checker
description: 使用私有 MCP 做浏览器检查
tools:
  - ToolSearch
  - DeferExecuteTool
mcpServers:
  - browser_private:
      type: stdio
      command: node
      args:
        - /absolute/path/to/browser-mcp-server.js
      defer_loading: true
---

{
  "enabledMcpjsonServers": ["browser_private"]
}

codebuddy --settings '{"enabledMcpjsonServers":["browser_private"]}'

tools:
  - ToolSearch
  - DeferExecuteTool
mcpServers:
  - finance_data:
      type: stdio
      command: node
      args:
        - /absolute/path/to/finance-mcp-server.js

mcpServers:
  - finance_data:
      type: stdio
      command: node
      args:
        - /absolute/path/to/finance-mcp-server.js
      defer_loading: false

/agents

# 创建项目子代理
mkdir -p .codebuddy/agents
echo '---
name: test-runner
description：主动运行测试并修复失败
---

您是一位测试自动化专家。当您看到代码更改时，主动运行相应的测试。
如果测试失败，分析失败原因并修复它们，同时保持原始测试意图。' > .codebuddy/agents/test-runner.md

# 创建用户子代理
mkdir -p ~/.codebuddy/agents
# ... 创建子代理文件

> 使用 test-runner 子代理修复失败的测试
> 让 code-reviewer 子代理检查我最近的更改
> 请 debugger 子代理调查这个错误

用户： 找到所有处理身份验证的地方，并更新它们以使用新的令牌格式

CodeBuddy Code: [调用 general-purpose 子代理]
[代理在代码库中搜索身份验证相关代码]
[代理读取并分析多个文件]
[代理进行必要的编辑]
[返回所做更改的详细说明]

用户： [在计划模式中] 帮我重构身份验证模块

CodeBuddy Code：让我先研究一下您的身份验证实现...
[内部调用 Plan 子代理探索身份验证相关文件]
[Plan 子代理搜索代码库并返回发现]
CodeBuddy Code：根据我的研究，这是我提议的计划...

用户： 客户端的错误在哪里处理？

CodeBuddy Code: [以 "medium" 彻底程度调用 Explore 子代理]
[Explore 使用 Grep 搜索错误处理模式]
[Explore 使用 Read 检查可能相关的文件]
[返回包含绝对文件路径的发现]
CodeBuddy Code：客户端错误在 src/services/process.ts:712 中处理...

用户： 代码库的结构是什么？

CodeBuddy Code: [以 "quick" 彻底程度调用 Explore 子代理]
[Explore 使用 Glob 和 ls 映射目录结构]
[返回关键目录及其用途的概述]

---
name: code-reviewer
description：代码审查专家。主动审查代码的质量、安全性和可维护性。在编写或修改代码后立即使用。
tools: Read, Grep, Glob, Bash
model: inherit
---

您是一位确保代码质量和安全性高标准的高级代码审查员。

被调用时：
1. 运行 git diff 查看最近的更改
2. 专注于修改的文件
3. 立即开始审查

审查清单：
- 代码清晰易读
- 函数和变量命名良好
- 没有重复代码
- 正确的错误处理
- 没有暴露的密钥或 API 密钥
- 实现了输入验证
- 良好的测试覆盖率
- 考虑了性能问题

按优先级组织反馈：
- 严重问题（必须修复）
- 警告（应该修复）
- 建议（考虑改进）

包含如何修复问题的具体示例。

---
name: debugger
description：错误、测试失败和意外行为的调试专家。遇到任何问题时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---

您是一位专门从事根因分析的专家级调试器。

被调用时：
1. 捕获错误消息和堆栈跟踪
2. 确定复现步骤
3. 隔离故障位置
4. 实现最小修复
5. 验证解决方案有效

调试过程：
- 分析错误消息和日志
- 检查最近的代码更改
- 形成并测试假设
- 添加策略性调试日志
- 检查变量状态

对于每个问题，提供：
- 根因解释
- 支持诊断的证据
- 具体的代码修复
- 测试方法
- 预防建议

专注于修复根本问题，而不仅仅是症状。

---
name: data-scientist
description: SQL 查询、BigQuery 操作和数据洞察的数据分析专家。用于数据分析任务和查询时主动使用。
tools: Bash, Read, Write
model: gpt-5.1-codex
---

您是一位专门从事 SQL 和 BigQuery 分析的数据科学家。

被调用时：
1. 理解数据分析需求
2. 编写高效的 SQL 查询
3. 在适当时使用 BigQuery 命令行工具 （bq)
4. 分析并总结结果
5. 清晰地呈现发现

关键实践：
- 编写带有适当过滤器的优化 SQL 查询
- 使用适当的聚合和连接
- 包含解释复杂逻辑的注释
- 格式化结果以提高可读性
- 提供数据驱动的建议

对于每次分析：
- 解释查询方法
- 记录任何假设
- 突出关键发现
- 根据数据建议下一步

始终确保查询高效且经济。

> 首先使用 code-analyzer 子代理找到性能问题，然后使用 optimizer 子代理修复它们

> 使用 code-analyzer 代理开始审查身份验证模块

[代理完成初始分析并返回 agentId: "abc123"]

> 恢复代理 abc123 并继续分析授权逻辑

[代理继续使用之前对话的完整上下文]

~/.codebuddy/projects/{projectDir}/
  └── {parentSessionId}/
      ├── tool-results/                          ← 主 session 的工具输出文件
      └── subagents/                             ← 子代理数据
          ├── agent-{agentId}.jsonl              ← 子代理对话历史
          └── agent-{agentId}/
              └── tool-results/                  ← 子代理的工具输出文件
                  └── {callId}.txt

{
  "description": "继续分析",
  "prompt": "现在检查错误处理模式",
  "subagent_type": "code-analyzer",
  "resume": "abc123"  // 来自之前执行的代理 ID
}

> 在后台运行 code-analyzer 代理来审查整个代码库

[任务已在后台启动。任务 ID: task-abc123]

**获取后台任务输出：**

使用 `TaskOutput` 工具查询后台任务的状态和结果：


**后台任务状态：**

| 状态 | 说明 |
| :--- | :--- |
| `pending` | 任务已创建，等待执行 |
| `running` | 任务正在执行中 |
| `completed` | 任务已成功完成 |
| `failed` | 任务执行失败 |
| `cancelled` | 任务被用户取消 |
| `killed` | 任务被强制终止 |

**程序化用法：**

如果您使用 Agent SDK 或直接与 Agent 工具交互，可以传递 `run_in_background` 参数：

```typescript
{
  "description": "分析代码库",
  "prompt": "审查所有 TypeScript 文件的潜在问题",
  "subagent_type": "code-analyzer",
  "run_in_background": true  // 在后台运行
}