子代理

版本说明

子代理从 1.11.0 起提供。

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

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

子代理分为两种：

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

使用方法

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

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

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

侧边栏中的位置与管理

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

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

上下文与信息传递

上下文独立与双向同步

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

• 任务派发：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）与正文提示词组成：

---
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	记忆支持：注入全局与项目长期记忆摘要，见 记忆与项目规则
projectRules	项目规则：注入全局（~/.aicode）与工作区内的 AGENTS.md 或 CLAUDE.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 看到改动。