. 两只手不够使。脑子也得清醒

使用者痛点 1：当需要同时分析多个独立的代码仓库时传统单体 Agent 只能串行处理，导致明显的时间延迟。

你让 catbuddy 同时分析三个开源仓库的架构，做个对比。主 Agent 老老实实地一个一个来：搜完 repo A。再搜 repo B，再搜 repo C。话说回来，每个仓库要调三四次工具，三个加起来十几轮迭代。不过，等你看到对比的时候。两分钟过去了——而这三件事本来毫无依赖可以同时干。

使用者痛点 2：AI 助手往往不知道自己的运行时信息，只能给出模糊或错误的回答。

再说第二个。你问它「你现在用的什么模型？最多还能跑几轮，不过，」——大多数 AI 助手这时候只能编一个数字。或者老实说「我不确定」，因为 LLM 根本不知道自己被装在一个什么样的运行时里。话说回来，它是个被蒙着眼睛干活的工人，连自己手上的工具清单都说不全。

这一篇就是给 Agent 补这两块短板：多开几只手再给它装一面镜子。这俩看着不相干，其实是一回事——都是让 Agent 从「被动的工具调用器」变成「知道自己在干嘛、还能调度自己」的主动玩家。

. 子代理：把一个完整 Agent，成一个普通工具

单个 Agent 的两个天花板

痛点表现：

• 串行瓶颈：Agent Loop 的每一轮——LLM 思考 → 调工具 → 再思考 → 再调工具——是顺序执行的。三个独立子任务，也只能排队。
• 上下文污染：每个子任务的工具结果全塞进同一个消息数组。三个任务搅在一起，LLM 很难分清「这段输出到底属于哪个任务」。

子代理如何解决上述痛点

子代理一招解决俩问题：独立上下文 + 并行执行.

子代理的技术特性

• 独立的消息历史：只装它自己那一个任务的对话，互不串味；
• 独立的工具注册表：它拥有自己的工具集合；
• 独立的 Provider / Runner：自行调 LLM 与循环，不受主 Agent 干扰。

再看透明化，spawn 工具背后其实是完整的 Agent 实例

spawn 对 LLM 来说就是普通工具调用。主 Agent 调用 {name: 'spawn',description: 'Spawn a subagent to handle a task in background.'},LLM 收到的是“请帮我启动一个后台任务”。根本感知不到背后启动了完整的 A​gentLoop.

SubagentManager：小猫的托管所

export class SubagentManager {
readonly runner: AgentRunner;其实，private readonly _running = new Map;不过，private readonly _statuses = new Map;private readonly _sessionTasks = new Map;maxConcurrentSubagents = /* configurable */;}

• : 跟踪所有正在运行的小猫，并发上限由其 size 决定；
• : 保存每只小猫当前状态；
• : 按会话分组，用于 /stop 时一次性撤销。

spawn的观点是，description 中那句 “in background” 是关键

L​LM 调用 {name:'spawn'。description:'... Use for complex or time‑consuming tasks that can run independently.'},会理解为“立即返回确认，不会阻塞”。实现上返回类似：

return `Subagent started . I'll notify you when it completes.`;

每只小猫内部实现要点

• SYSTEM Prompt 极简：
• SYSTEM Tools 受限：
• S​tate Isolation：FileStates,防止文件读取缓存相互污染。不过，

并发满了怎么办？直接如实报告

if >= this.maxConcurrentSubagents) {
return `Cannot spawn subagent: concurrency limit reached }/${this.maxConcurrentSubagents} running).`;}

L​LM 得到“并发已满”的明确答复后可以自行决定是等待还是改换策略，而不是卡死在 /spawn/await ….

说到结果回流，MessageBus 的角色

const msg: InboundMessage = {
channel: 'system',senderId: 'subagent'。chatId: `${origin.channel}:${origin.chatId}`,content,sessionKeyOverride: origin.sessionKey,metadata: { injected_event: 'subagent_result',subagent_task_id: taskId },};this.bus.publishInbound;

Main Agent 在下一轮取消息时自然会看到这条程序消息，实现“后台跑完自动回报”。前端通过 'injected_event'` 区分使用者输入与子代理结果，实现 UI 差异化展示。

说到实时状态监控，SubagentHook

class SubagentHook extends AgentHook {
override async afterIteration {
this.status.iteration = context.iteration;this.status.toolEvents =;if this.status.error = context.error;
}
}

The status object lives in ,enabling external dashboards or UI to read progress without等待完成。

. 自我认知：让 Agent 照见自己的运行时

my 工具 —— 给 Agent 一份体检报告

The tool resides at alert

.

• `check` ：返回模型名称、当前/最大迭代次数、剩余 token、已注册 tool 列表还有正在运行的小猫数量等信息。

return .join;

内部设计惊喜的观点是，AgentLoop 本身即 RuntimeState

// runtime_state.ts
export interface RuntimeState {
readonly model:string;readonly maxIterations:number;readonly currentIteration:number;readonly toolNames:string;readonly contextWindowTokens:number;readonly subagents:SubagentManager|null;setRuntimeValue?怎么说呢，:string;}

The main loop implements this interface directly:

export class AgentLoop implements RuntimeState {
get toolNames{ return this.tools.toolNames;}
get runtimeVars{ return this._runtimeVars;}
// ，}
const allowSet = opts.config.tools?.my，.allowSet?，false;this.tools.register);

No extra manager → zero sync cost,at price of intentional coupling.

至于修改受限，三层安全模型

安全等级	含义 & 示例
不可读不可改 例：bus,provider,runner 等内部对象	防止泄露跨会话信息或破坏主要执行流
ONLY: 仅可读不可改 例：subagents,currentIteration,execConfig	允许查询但禁止重置计数器或篡改结构
可读可改但有范围校验 例： 从{key来看。'maxIterations',type:'number',min:1,max:100} 再看{key，'contextWindowTokens',type:'number',min:1000,max:1000_000} 至于{key，'model',type:'string'} <\/ul>	只有经过类型+范围检查后才写入真实属性 <\/tr> <\/tbody> <\/table>

set 实现细节

setRuntimeValue:string{
if{
const n=Number;if||n<1||n>100) return 'Error…'，this.maxIterations=n;按理说，this.subagents?.setProvider;return maxIterations set to ${n};}
// contextWindowTokens / model 类似处理 …this._runtimeVars=value;return ${key} stored in runtime scratchpad;}
<\/c od e>
<\/pre>

The final fallback writes into a transient “scratchpad” ) – perfect for ad‑hoc跨轮共享数据.

说到自适应示例。当迭代快耗尽时自行提高上限

说到Agent，→ 当前 iteration/ maxiterations…其实，runningsubagents …再看Agent，→ my.set → 上限提高成功 → continue
<\/pre>

. 会话取消：知道自己在跑什么也能停下来

每个 turn 一个 AbortController

const controller=new AbortController;const existing=this.activeTasks.get||;
existing.push;
this.activeTasks.set;msg._abortSignal=controller.signal;<\/pre>

• The map allows multiple controllers per session。
• The signal is passed down to )`，实现从循环顶层直通到底层网络请求的“一根线”。<\/ul>

cancelSession：一次性 abort 全部任务

async cancelSession:Promise{
const ctrls=this.activeTasks.get;if return 0，话说回来，let cancelled=0;for{ if{ c.abort;cancelled++，} }
this.activeTasks.delete;return cancelled;}
<\/pre>

This is a **hard** interruption – Provider sees an AbortError\` and never retries.

信号异步传播，但必然在下一个 await 前生效

• Synchronous JS code continues until it hits next await.
• The vast majority of work in an agent is I/O。so “next await” is always imminent – giving a perceived “instant stop”. <\/ul>

至于.复盘，这两块为什么是“一回事”

• Packing whole agents into ordinary tools：spawn 把完整 AgentLoop 隐藏进普通 tool，让 LLM 零感知获得并行能力；

• Mirroring runtime state via a safe API：my 把运行时信息公开，却通过三层安全集合严格限定可写字段；

• Cancelling via AbortController：AbortController.abort 能直接终止所有正在进行中的网络请求和子代理，无需得到 agent 同意。

All three share a single design mantra:

The result is an agent that knows its model。iteration count and active sub‑agents and can stop itself on demand – completing self‑awareness loop.

。

---