# 子代理

::: tip 版本说明
子代理从 1.11.0 起提供。
:::

子代理是由主会话派生出的独立工作会话。当你面临耗时较长的调研、多模块并行审查或架构对比等复杂任务时，可以让 AI 派发子代理并行处理，**不阻塞当前主对话**。

子代理拥有自己独立的上下文与工具能力。派发后它会在后台独立工作，你可以留在主会话继续讨论，也能随时点进子会话查看实时进度、补充提问或手动暂停。

子代理分为两种：
- **默认通用子代理**：自动继承父会话的模型配置与全部可用工具；
- **自定义子代理**：支持自由指定模型、工具白名单/黑名单以及专属提示词。

## 使用方法

在主会话中直接向 AI 提出派发需求即可，例如：

- 「派个子代理去审查 `app/build.gradle.kts`，把潜在问题列出来」
- 「同时派两个子代理，一个调研数据库迁移方案，一个调研 UI 组件库选型」
- 「派一个只读调研子代理查清当前的登录与鉴权流程」

AI 在派发前会弹窗向你确认授权；获得同意后子代理将在后台启动，主会话随即恢复空闲，可继续接收你的其它指令。

## 侧边栏中的位置与管理

侧边栏会话列表清晰展示了主会话与子代理的父子归属关系：

- **展开与收起**：派生过子代理的会话，行尾会显示子代理数量与展开折叠箭头。点击箭头可展开查看其下属的所有子代理；
- **状态指示**：正在运行中的子代理会显示绿色的运行状态指示灯；
- **独立交互**：点击子代理即可切换进入其会话页，界面与常规会话完全一致，可独立对话、暂停或重新生成；
- **会话操作**：长按子代理项可进行重命名、导出与删除；删除主会话时，其名下的所有子代理会随之一同清理。

## 上下文与信息传递

::: tip 上下文独立与双向同步
子代理与主会话的对话上下文完全隔离，它默认不会自动加载主会话的历史对话，保证轻量与专注：

- **任务派发**：AI 在派发子代理时，会自动提炼当前任务的明确目标、关键文件路径、已核实的背景以及约束条件，打包作为初始指令交给子代理。如果你在主会话中手动指示派发，也建议交代清楚关键背景与期望产出；
- **结果汇总**：子代理执行完毕后，主会话会自动收到完成通知，并读取其最终产出为你进行汇总；若主会话当时正在调用其它工具，卡片下方会提示子代理已就绪，并在当前操作后自动跟进处理；
- **全流程追溯**：主会话通常只读取子代理的最终结论，如果你想查看子代理完整的工具调用日志、推导轨迹或中间输出，直接在侧边栏点击进入该子会话即可查看全部详情。
:::

## 与主会话的双向通讯

子代理与主会话之间支持双向异步通讯，互不阻塞：

- **主会话 → 子代理**：主会话可以随时向某个子代理追加消息（补充指令、纠偏，或对已有结果继续追问），**可反复发送**。运行中的子代理会在下一轮操作里收到该消息；已完成或暂停的子代理会被重新唤醒并继续工作；
- **子代理 → 主会话**：子代理在运行中可以主动向主会话汇报关键进展、求助，或提交需要协调、决策的事项。主会话会收到一条系统通知，并可直接回复。

这些消息在界面上以轻量提示条呈现，不占用普通聊天气泡；主会话忙碌时消息会在当前操作结束后自动跟进处理，空闲时则立即触发新一轮。

## 自动派发与手动指定

主会话 AI 了解当前所有可用的子代理及其擅长领域：

- **自动匹配**：当你的需求与某个子代理的用途描述（`description`）相符时，AI 会主动选用该专属子代理；
- **手动指定**：你也可以在指令中明确指定，例如「使用 Explore 子代理检索所有网络请求的入口」。

## 内置子代理：Explore

初次启动时，系统会自动在全局目录释放内置的 **Explore** 只读探索子代理（位于 `~/.aicode/agents/explore.md`），开箱即用。

它的核心用途是只读的代码库探索与逻辑梳理：
- **纯只读安全**：仅开放了代码与文件检索工具（`readFile`、`list`、`search`、`websearch`、`webfetch`、`loadSkill`），**不包含任何写文件与执行终端命令的工具**，不会对项目造成改动，也不需要频繁弹窗授权；
- **模型定制**：默认继承当前会话的模型。如果想为它配置更经济的模型，只需在 `explore.md` 中填入对应的 `provider` 与 `model`；
- **持久保留**：此文件仅在首次不存在时释放，你所做的个性化修改在 App 升级时均会完整保留。

## 自定义子代理

创建自定义子代理有两种方式，效果完全等价（App 内保存后写出的就是同一份 `.md` 文件）：

- **在 App 内新建**（推荐）：「设置 → 子代理」右上角的「＋」，填表单即可，模型可以直接从已配置的供应商里选；
- **手写定义文件**：自行把 Markdown 文件放进对应目录，适合从其它项目拿现成定义或用 git 管理。

两个可选目录：

- **全局配置**：`~/.aicode/agents/<name>.md`，所有项目共享，升级不丢失。跟随执行环境：本地模式下是容器内 `/root/.aicode/agents/`（映射至手机 App 私有目录），远程模式下指**服务器**上的 `~/.aicode/agents/`，读写经由 SSH 完成；
- **项目级配置**：`<项目工作区>/.aicode/agents/<name>.md`，仅对当前工作区生效，可随代码库一同提交到版本控制中。远程模式下这里指的是**服务器上**的工作区，读写经由 SSH 完成。

同名定义时项目级优先。文件由顶部的 YAML 配置（frontmatter）与正文提示词组成：

```markdown
---
name: researcher
description: 只读代码与技术调研：广泛检索代码、查阅网络资料并汇总结论，不修改文件
provider: DeepSeek
model: deepseek-reasoner
reasoningEffort: high
mode: plan
tools: [readFile, list, search, websearch, webfetch]
disallowedTools: [Bash, terminal]
inject: [base, projectRules]
---
你是资深代码调研专家。请先使用 search 定位入口，再用 readFile 深入核实。
输出结论时请务必标注准确的 `文件路径:行号` 引用；未核实推断需如实注明。
```

### 配置项说明

| 字段 | 是否必填 | 说明 |
| --- | --- | --- |
| `name` | 否 | 子代理标识名称，省略时取文件名 |
| `description` | 建议填写 | 简述适用场景与专长，主会话 AI 依据此描述判断何时选用该子代理 |
| `provider` | 否 | AI 供应商名称，省略时继承父会话配置 |
| `model` | 否 | 模型名称，省略时继承父会话配置 |
| `reasoningEffort` | 否 | 思考强度：`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max` |
| `mode` | 否 | 默认运行模式：`build` / `plan` / `auto`，省略时继承父会话当前模式 |
| `tools` | 否 | 工具白名单。**省略时代表开放全部可用工具** |
| `disallowedTools` | 否 | 工具黑名单，优先级高于白名单，支持 `mcp__*` 前缀通配 |
| `inject` | 否 | 注入的系统规则片段，详见下表 |

### inject 规则片段

| 取值 | 含义 |
| --- | --- |
| `base` | 子代理专用轻量基线：包含工具使用规范与路径约定，轻量且省 token |
| `mainRules` | 完整通用规则：与主会话保持完全一致的行为准则与规则基线 |
| `skills` | 技能支持：注入可用技能清单，允许子代理加载并执行项目技能 |
| `memory` | 记忆支持：注入全局与项目长期记忆摘要，见 [记忆与项目规则](https://aicode.murk.top/md/guide/memory.md) |
| `projectRules` | 项目规则：注入全局（`~/.aicode`）与工作区内的 `AGENTS.md` 或 `CLAUDE.md` 约束，见 [记忆与项目规则](https://aicode.murk.top/md/guide/memory.md) |

`base` 与 `mainRules` 是同一套规则的简版与完整版，**正常只选一个**。两个同时开启不会报错，但会把相互重叠的规则文本注入两遍，徒增上下文占用。

若省略 `inject` 字段，默认等同于 `[base, skills, memory, projectRules]`。如果填写 `inject: [none]`，则仅使用你在 Markdown 正文中编写的提示词。

## 在设置中管理

进入「设置 → 子代理」，可以按「当前项目 / 全局」分组浏览所有已识别的子代理。

- **新建**：点右上角的「＋」。表单里可以填名称与用途描述、选作用域（当前项目 / 全局）、从已配置的供应商中**选定模型与思考强度**、勾选工具白名单与黑名单、开关要注入的提示词片段，最后写 agent 提示词正文；
- **编辑**：点击进入某个子代理的详情页，再点右上角的铅笔图标。修改名称会连带重命名它的定义文件；
- **启用 / 禁用**：详情页顶部的开关。禁用后它不再出现在主会话 AI 的可派发清单里，AI 也无法再指名派发它，但定义文件保留，已在运行的子会话也不受影响；
- **删除**：列表里左滑条目，会删掉对应的 `.md` 定义文件，不可恢复。

新建和编辑时，表单会避让软键盘；提示词正文较长时可以上下滚动，继续编辑末尾内容。

启停状态存在 `agents.json`，与技能的停用名单同一套约定：全局名单位于当前执行环境的 `~/.aicode/agents.json`，本地模式保存在手机 App 私有目录，远程模式保存在服务器上；两者独立，不会自动迁移或同步。项目级名单在本地模式位于 `<工作区>/.aicode/agents.json`，远程模式仍保存在手机 App 私有目录，按服务器和工作区隔离。两级取并集，任一作用域禁用即生效。

在 App 中切换启停状态后列表会刷新。本地模式下手工修改定义或名单，列表几秒内自动刷新；远程模式下不会监听服务器上的文件变化，手工修改后需退出并重新进入设置页刷新列表。

## 运行机制与限制

- **并发上限**：系统最多支持 **5 个子代理同时运行**，超出时需等待已有任务完成或手动暂停；
- **防嵌套**：子代理不能再派生下一级子代理；
- **双向通讯**：主会话可随时向运行中或已完成的子代理追加消息（可重复发送），子代理运行中也能主动向主会话汇报或求助；消息异步送达、互不阻塞。
- **默认模式**：子代理默认继承派发它时主会话的模式。在计划（PLAN）模式下派出的子代理同样只能只读探索，在自动（AUTO）模式下也和主会话一样不再逐次弹窗。自定义子代理可用 `mode` 字段覆盖这一默认值，例如给只读子代理固定 `mode: plan`，让它无论何时被派发都保持只读；
- **授权管控**：子代理与主会话遵循相同的工具授权安全机制。如果子代理尝试执行写文件或系统命令，同样会触发授权确认弹窗（弹窗会清晰标明来源于哪个子代理）；
- **你手动停止也会告知主会话**：在子会话里点停止、或直接删掉一个正在运行的子代理时，主会话会收到一条「已被手动终止」的通知（而不是执行失败），AI 不会自行重新派发；并发名额也会立即释放；
- **生命周期**：删除父会话时，其包含的所有子代理会话将一并级联清理；
- **定义改动的生效时机**：新增、改名或修改子代理定义后，已打开的会话仍沿用开场时的清单，**新开一个会话**才能让 AI 看到改动。