pi-subagents 配置完全指南12个核心选项详解与实战示例【免费下载链接】pi-subagentsPi extension for async subagent delegation with truncation, artifacts, and session sharing项目地址: https://gitcode.com/GitHub_Trending/pi/pi-subagentspi-subagents 是一个强大的异步子代理委托系统支持截断、工件和会话共享功能。这个扩展让 AI 代理能够并行执行复杂任务实现高效的多代理协作工作流。对于新手和普通用户来说掌握配置文件选项是充分发挥 pi-subagents 潜力的关键。 配置文件位置与格式pi-subagents 的配置文件位于~/.pi/agent/extensions/subagent/config.json采用标准的 JSON 格式。如果该文件不存在系统会使用默认配置。⚙️ 12个核心配置选项详解1. asyncByDefault - 默认异步执行{ asyncByDefault: true }作用让顶层调用默认使用后台执行模式。即使调用者没有明确设置async参数也会在后台运行。使用场景当你希望大部分任务都在后台执行不阻塞主代理的工作流。示例配置此选项后/run scout 分析代码库会自动在后台执行让你可以继续其他工作。2. forceTopLevelAsync - 强制顶层异步{ forceTopLevelAsync: true }作用强制深度为 0 的单次、并行和链式运行进入后台模式并绕过澄清 UI。注意事项嵌套调用会保持它们自己的继承设置此设置仅影响顶层调用。3. parallel - 并行任务控制{ parallel: { maxTasks: 12, concurrency: 6 } }参数说明maxTasks最大任务数默认 8concurrency并发数默认 4优先级每次调用的concurrency参数会覆盖此配置。4. defaultSessionDir - 默认会话目录{ defaultSessionDir: ~/.pi/agent/sessions/subagent/ }会话目录优先级params.sessionDir参数指定config.defaultSessionDir配置文件从父会话派生的目录特点会话功能始终启用确保每个子代理都有独立的执行环境。5. maxSubagentDepth - 最大嵌套深度{ maxSubagentDepth: 1 }作用控制嵌套委托的深度。当没有继承的PI_SUBAGENT_MAX_DEPTH环境变量时生效。重要规则每个代理的maxSubagentDepth可以为其子运行设置更严格的限制但不能放宽继承的更严格限制。6. intercomBridge - 通信桥接配置{ intercomBridge: { mode: always, instructionFile: ./intercom-bridge.md } }模式选项always始终注入默认fork-only仅对分叉运行注入off禁用桥接指令文件可自定义的 Markdown 模板支持{orchestratorTarget}变量插值。7. worktreeSetupHook - 工作树设置钩子{ worktreeSetupHook: ./scripts/setup-worktree.mjs, worktreeSetupHookTimeoutMs: 45000 }输入参数JSON 对象包含repoRoot、worktreePath、agentCwd、branch、index、runId和baseCommit。输出要求必须返回一个 JSON 对象例如{ syntheticPaths: [.venv, .env.local] } 参数参考速查表参数类型默认值描述agentstring-单次模式下的代理名称taskstring-单次模式下的任务字符串actionstring-管理动作list、get、create 等outputModestringinline输出模式inline 或 file-onlyskillstring/array/false代理默认覆盖技能或禁用所有技能tasksarray-顶层并行任务数组concurrencynumber4并行任务并发数worktreebooleanfalse为并行任务创建隔离的 git 工作树chainarray-链式执行步骤contextstringfresh会话上下文fresh 或 forkasyncbooleanfalse后台执行模式 实战配置示例示例1开发环境配置{ asyncByDefault: true, parallel: { maxTasks: 8, concurrency: 4 }, maxSubagentDepth: 2, intercomBridge: { mode: always } }示例2生产环境配置{ asyncByDefault: false, forceTopLevelAsync: false, parallel: { maxTasks: 16, concurrency: 8 }, defaultSessionDir: /var/log/pi/subagents/, worktreeSetupHook: /opt/scripts/setup-worktree.js, worktreeSetupHookTimeoutMs: 60000 }示例3测试环境配置{ asyncByDefault: true, parallel: { maxTasks: 4, concurrency: 2 }, maxSubagentDepth: 1, intercomBridge: { mode: fork-only } } 配置最佳实践1. 根据工作负载调整并行度轻量级任务concurrency: 4-6中等负载concurrency: 6-8重型任务concurrency: 8-122. 会话管理策略开发环境使用默认会话目录生产环境指定固定目录便于日志收集定期清理旧会话文件3. 错误处理配置{ worktreeSetupHookTimeoutMs: 30000, maxSubagentDepth: 3 } 快速上手步骤创建配置文件mkdir -p ~/.pi/agent/extensions/subagent/ nano ~/.pi/agent/extensions/subagent/config.json添加基础配置{ asyncByDefault: true, parallel: { maxTasks: 8, concurrency: 4 } }测试配置/subagents-doctor验证运行状态subagent({ action: status }) 高级技巧与提示动态配置覆盖在运行时可以通过参数覆盖配置文件subagent({ agent: scout, task: 分析项目结构, concurrency: 6, // 覆盖配置文件 async: false // 强制前台执行 })条件配置根据环境变量动态调整配置const config { asyncByDefault: process.env.NODE_ENV production, parallel: { maxTasks: process.env.CI ? 4 : 8, concurrency: process.env.CI ? 2 : 4 } }监控与调试配置正确的日志目录后可以轻松监控子代理的执行情况查看会话日志~/.pi/agent/sessions/subagent/检查工作树临时目录中的chain-runs/{runId}/监控进度使用subagent({ action: status }) 常见问题解答Q: 配置文件修改后需要重启吗A: 不需要pi-subagents 会在每次运行时重新加载配置。Q: 如何调试配置问题A: 使用/subagents-doctor命令检查配置和依赖。Q: 多个配置选项冲突时如何处理A: 运行时参数 配置文件 系统默认值。Q: 如何备份配置文件A: 配置文件是纯 JSON可以直接复制备份。 性能优化建议根据硬件调整并发数CPU 核心数 × 1.5合理设置超时避免任务卡死启用工作树隔离防止并行任务冲突使用文件输出模式处理大输出时减少内存占用通过合理配置 pi-subagents你可以构建高效、可靠的 AI 代理协作系统大幅提升自动化任务的执行效率。提示更多技术细节请参考 src/extension/config.ts 和 src/extension/schemas.ts 源码文件。【免费下载链接】pi-subagentsPi extension for async subagent delegation with truncation, artifacts, and session sharing项目地址: https://gitcode.com/GitHub_Trending/pi/pi-subagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考