Pi 异步子代理委托：截断策略、产物与会话管理的工程实践

在 AI 辅助编程工具链中，单一会话的上下文窗口与计算资源始终存在上限。当任务复杂度超出单代理的处理能力时，合理的策略是将工作拆分为多个专注的子代理并行或串行执行。pi-subagents 作为 Pi 编辑器的扩展，提供了一套完整的异步子代理委托机制，涵盖截断控制、产物管理、会话共享等核心能力。本文从工程实践角度，拆解其关键设计参数与可落地的配置策略。

异步委托的核心模式

pi-subagents 支持三种基本执行模式：单代理运行（single）、并行执行（parallel）和链式编排（chain）。每种模式在上下文继承、产物传递和错误处理上有不同的行为特征。

单代理模式适用于专注的独立任务，如代码审查或特定模块的侦察。并行模式通过 tasks 数组同时启动多个子代理，适合需要多视角验证的场景，如同时代码风格检查、安全审计和测试覆盖分析。链式模式则通过 chain 数组定义步骤间的依赖关系，前一个步骤的输出可通过 {previous} 或 {outputs.name} 变量传递给后续步骤。

背景执行（async: true）是 pi-subagents 的关键特性。前台运行会阻塞父会话直至子代理完成，而后台运行则立即返回控制权，子代理在独立进程中继续工作。后台任务完成后通过事件通知机制（subagent:async-complete）将结果推送回父会话，这种模式特别适合耗时较长的代码分析或批量处理任务。

截断策略与输出控制

子代理的输出可能包含大量日志、代码片段或分析结果，直接回传会迅速耗尽父会话的上下文容量。pi-subagents 通过 maxOutput 参数实现智能截断，默认限制为 200KB 或 5000 行。

截断行为遵循 "尾部优先" 原则：当输出超出阈值时，保留最近的内容并丢弃早期部分。这一设计基于合理的假设 —— 在大多数工作流中，结论和最终状态比初始探索更有价值。对于需要完整输出的场景，可通过 output 参数指定文件路径，将结果写入磁盘而非内联返回。

outputMode 参数进一步控制返回格式。inline 模式将完整内容嵌入对话（受 maxOutput 限制），file-only 模式则仅返回文件引用，如 "Output saved to: /abs/report.md (48.2 KB, 2847 lines)"。对于链式执行，当某步骤使用 file-only 模式时，后续步骤通过 {previous} 获取的也是文件引用而非内容，这种引用传递机制有效避免了中间产物的重复加载。

产物管理与结构化输出

产物（artifacts）是子代理执行过程中生成的持久化数据，包括输出文件、进度日志、会话快照和元数据。pi-subagents 为每次运行创建独立的产物目录，默认位于临时目录下，遵循 <tmpdir>/pi-subagents-<scope>/chain-runs/{runId}/ 的层级结构。

关键产物类型包括：

• 输出文件：通过 output 参数指定的 Markdown 或结构化数据文件
• 进度日志：progress.md 记录执行过程中的关键节点
• 会话文件：.jsonl 格式的完整会话记录，支持后续恢复或分享
• 元数据：包含执行时间、模型选择、回退尝试等运行时信息

结构化输出（structured output）通过 outputSchema 参数启用，要求子代理返回符合 JSON Schema 的验证数据。这一机制在动态扇出（dynamic fanout）场景中尤为重要：侦察代理返回结构化的审查目标列表，后续步骤基于该列表并行启动审查代理。Schema 验证失败会直接导致步骤失败，避免无效数据污染下游处理。

会话共享与上下文隔离

子代理的上下文模式分为 fresh 和 fork 两种。fresh 模式启动干净的子会话，仅接收显式传递的任务描述和 reads 文件；fork 模式则从父会话的当前状态创建分支，继承完整的对话历史和上下文状态。

内置代理 planner、worker 和 oracle 默认使用 fork 模式，因为它们通常需要理解父会话的决策背景。fork 操作要求父会话已持久化且存在有效的叶子节点，否则会快速失败而非静默降级。

会话共享还涉及安全边界的控制。子代理默认不接收 pi-subagents 技能，其上下文经过过滤，移除了父会话特有的编排指令、状态消息和工具调用历史。只有当代理的 tools 明确包含 subagent 时，才获得受限的子代理委托能力，且受 maxSubagentDepth 递归深度限制。

可落地的配置参数

以下是基于实际场景的配置建议：

代码审查流水线

{
  "chain": [
    { "agent": "scout", "task": "分析变更影响范围", "as": "context" },
    { "parallel": [
      { "agent": "reviewer", "task": "检查正确性", "label": "正确性审查" },
      { "agent": "reviewer", "task": "检查测试覆盖", "label": "测试审查" },
      { "agent": "reviewer", "task": "检查复杂度", "label": "重构审查" }
    ], "concurrency": 3 },
    { "agent": "worker", "task": "汇总审查意见并应用修复" }
  ]
}

后台长时间分析

{
  "agent": "researcher",
  "task": "调研第三方库兼容性",
  "async": true,
  "output": "research/compat-report.md",
  "outputMode": "file-only",
  "maxOutput": { "bytes": 100000, "lines": 2000 }
}

递归深度控制

{
  "maxSubagentDepth": 1,
  "agentOverrides": {
    "oracle": { "maxSubagentDepth": 0 }
  }
}

风险与限制 checklist

• 截断导致信息丢失：对于需要完整历史记录的任务，显式设置 output 文件而非依赖内联输出
• 递归深度超限：嵌套代理调用时确保工具链明确包含 subagent，并监控 maxSubagentDepth 配置
• 上下文污染：fork 模式会继承父会话的敏感信息，处理外部代码或数据时优先使用 fresh 模式
• 工作树冲突：并行编辑任务启用 worktree: true，确保每个代理在独立的 git 工作树中执行
• 接受门控绕过：生产环境任务显式配置 acceptance 参数，避免依赖默认的推断行为

结语

pi-subagents 通过异步委托、智能截断和产物管理，将单一会话的容量限制转化为多代理协作的架构优势。理解其上下文隔离机制、输出控制策略和递归安全边界，是构建可靠 AI 辅助工作流的基础。在实际部署中，建议从简单的单代理后台任务开始，逐步引入链式和并行模式，同时建立清晰的产物归档和会话清理策略。

资料来源

• pi-subagents GitHub 仓库

ai-systems