类 PlannerAgent

可选lastTokenUsage

setToolRegistry

• setToolRegistry(registry: ToolRegistry | null): void

  设置共享的 ToolRegistry 实例

  参数

  • registry: ToolRegistry | null

  返回 void

on

• on(eventName: string, listener: (payload: unknown) => void): () => void

  订阅 Agent 事件总线（Phase D — 事件流与可观测性）。 UI / 遥测 / 日志层可通过此方法订阅 agent.* 事件，与 Agent 主流程解耦。

  参数

  • eventName: string

    事件名（见 AGENT_EVENT 常量）

  • listener: (payload: unknown) => void

    事件载荷监听器

  返回 () => void

  unsubscribe 函数

once

• once(eventName: string, listener: (payload: unknown) => void): () => void

  一次性订阅：触发一次后自动注销

  参数

  • eventName: string
  • listener: (payload: unknown) => void

  返回 () => void

getEventBus

• getEventBus(): EventEmitter

  暴露事件总线实例，供 llm-service agentLoopStream 回调注入时直接 emit

  返回 EventEmitter

use

• use(hook: AgentHooks): this

  注册一个钩子。钩子按注册顺序串行执行。 链式调用：agent.use(hook1).use(hook2)。

  参数

  • hook: AgentHooks

  返回 this

withContext

• withContext(ctx: Partial<AgentContext>): () => void

  设置当前 Agent 上下文，供钩子读取 runId/testId/sessionId。 返回一个 restore 函数，调用后恢复原上下文（用于 try/finally）。

  Phase D：同时触发 agent.start 事件，携带完整上下文。

  参数

  • ctx: Partial<AgentContext>

  返回 () => void

interrupt

• interrupt(
      reason: string,
      payload?: Record<string, unknown>,
  ): Promise<Record<string, unknown>>

  暂停当前 Agent 执行，进入 interrupted 态等待人工 continue。

  设计借鉴 anything-llm AIbitat 的 interrupt(route) + shouldAgentInterrupt。 与 AIbitat 不同的是，本实现把"等待"语义交给调用方： interrupt 仅 emit agent.interrupt 事件并返回一个 Promise<decision>， 该 Promise 的 resolve 函数挂到 this.continueResolvers 上， 由 continue(decision) 唤醒。

  典型用法（HealerAgent）：

  const decision = await this.interrupt('patch-awaiting-approval', {
    round, patches, testFile,
  });
  if (decision.approved) { fs.writeFileSync(testFile, patched); }
  复制

  参数

  • reason: string

    中断原因标识（如 'patch-awaiting-approval'）

  • 可选payload: Record<string, unknown>

    中断上下文（供 UI 渲染）

  返回 Promise<Record<string, unknown>>

  人工 continue 时传入的 decision 对象

continue

• continue(decision: Record<string, unknown>): boolean

  人工恢复被 interrupt 暂停的 Agent。

  参数

  • decision: Record<string, unknown>

    用户/调用方提供的恢复决策

  返回 boolean

  true 表示成功唤醒等待中的 interrupt；false 表示无等待中的 interrupt

isAwaitingContinue

• isAwaitingContinue(): boolean

  当前是否有等待 continue 的 interrupt

  返回 boolean

addPendingCitation

• addPendingCitation(citation: PendingCitation): void

  向引用缓冲区追加一项（工具执行过程中调用）。 缓冲内容将在响应最终化时随 done 事件统一 flush，不逐条 emit。

  参数

  • citation: PendingCitation

  返回 void

addPendingAttachment

• addPendingAttachment(attachment: PendingAttachment): void

  向附件缓冲区追加一项（工具执行过程中调用）。 缓冲内容将在响应最终化时随 done 事件统一 flush，不逐条 emit。

  参数

  • attachment: PendingAttachment

  返回 void

getPendingCitations

• getPendingCitations(): readonly PendingCitation[]

  获取当前引用缓冲区的快照（不消耗）

  返回 readonly PendingCitation[]

getPendingAttachments

• getPendingAttachments(): readonly PendingAttachment[]

  获取当前附件缓冲区的快照（不消耗）

  返回 readonly PendingAttachment[]

clearPendingBuffers

• clearPendingBuffers(): {
      citations: PendingCitation[];
      attachments: PendingAttachment[];
  }

  清空缓冲区。 通常在响应最终化、缓冲内容已随 done 事件 flush 后调用。

  返回 { citations: PendingCitation[]; attachments: PendingAttachment[] }

  清空前的快照（citations + attachments），供调用方一次性 flush

setLLMService

• setLLMService(service: LLMService | null): void

  设置共享的 LLMService 实例

  参数

  • service: LLMService | null

  返回 void