billion-context-pi-subagents

English | 中文

Pi coding agent 的 acp_delegate 子代理工具 — 从 billion-context-pi 中拆分而来（#612）。将一个自包含的任务交给一个运行在干净上下文中的全新 pi 进程；结果以文件路径的形式返回，保持主会话的轻量。

pi install npm:billion-context-pi-subagents

与其他包的关系

包	职责
billion-context-pi	上下文压缩（compress / decompress / search_context / acp_status）
billion-context-pi-subagents（本包）	子代理委派（acp_delegate* + 集群检查器）
billion-context	多主机代理启动器（opencode/omp/…）— 与本包无代码共享；其"subagent"支持仅跟踪 opencode 原生任务会话

billion-context-pi 已内置本包。 拆分（#612）之后，billion-context-pi 将本包以精确版本钉死为 devDependency，并在构建时内联进其 dist（与内联 acp-kernel 同一机制）。如果你在使用 billion-context-pi，就已经拥有 acp_delegate —— 请勿再单独安装本包。若两者同时被加载，独立副本会在会话开始时检测到内置副本并自动让位（不会重复注册工具或提示词段落）。

只有当你想不装 billion-context-pi 而单独使用委派功能时才直接安装本包：此时委派的子进程依赖 Pi 的原生上下文管理而非 ACP 压缩，且没有 /acp-subagents 命令可用。

两包同时运行时共存于同一个 Pi 进程中：相同的 acp.json 约定（各自只读取自己的键）和同一个日志文件（~/.pi/acp.log）。

安装

billion-context-pi 用户：跳过此步 —— 已内置。 此安装仅适用于不装 billion-context-pi 的独立使用：

pi install npm:billion-context-pi-subagents

无需配置 — 委派功能默认启用。安装后重启 Pi。

⚠️ v0.1.x 没有自动更新。 独立安装需手动升级（pi install npm:billion-context-pi-subagents@latest 或重新安装）；内置于 billion-context-pi 的副本随 billion-context-pi 发版更新。

面向模型的工具

工具	功能
acp_delegate	为任务（审查 / 调研 / 实现 / 规划 / 咨询）生成一个干净上下文的子代理
acp_delegate_wait	阻塞直到委派运行完成（返回其结果；超时则返回超时信息）
acp_delegate_cancel	按 runId 取消正在运行的委派

角色

五个内置角色，每个角色都有系统提示词和软性工具护栏：

角色	工具	适用场景
reviewer	read, bash, grep, find, ls + ACP	只读代码审查（缺陷、风险、file:line）
researcher	read, bash, grep, find, ls + ACP	只读代码库调研
worker	read, edit, write, bash	进行代码修改
planner	read, bash, grep, find, ls + ACP	分析并提出分步计划
oracle	read, bash, grep, find, ls + ACP	回答问题 / 提供建议

只读角色会收到受限的工具允许列表加上 ACP 上下文工具，以便管理自身上下文。这可以防止意外的文件修改，但 bash 可以绕过它 — 它是护栏，不是安全边界。Worker 使用 Pi 的完整默认工具集（任何已加载的扩展或自定义工具仍然可用）。

执行模型

• 交互模式（TUI）& RPC 模式：async:true（默认）在后台运行子进程；完成时会向聊天注入一条简短的完成通知 — 除非模型在运行结束后已经读取了结果文件（通过 read 工具或引用该文件的 bash 命令检测到），此时通知会被跳过：模型已有结果，再次注入只会浪费上下文。在 acp.json 中设置 delegate: { notifyIfRead: "always" } 可恢复始终注入的行为。
• Print / JSON 模式（pi -p、SDK）：async:true 自动降级为同步 — 结果在同一轮次中作为工具结果返回。
• 失败必须显式可见，绝不静默。 失败的运行（非零退出码、spawn 错误、看门狗超时）会注入一条携带简短错误摘要的 FAILED ⚠️ 通知。如果通知完全无法送达，一条恢复提示会附加到下一条委派通知或工具结果上。
• 结果投递：完整的委派输出保存到 $TMPDIR/acp-delegate/<runId>.out；工具结果和通知仅携带任务标题 + 文件路径（无预览）— 使用 read 查看详情。
• 实时可见性（TUI）：异步运行会在编辑器下方显示状态组件，并在底部栏显示累计 token/费用用量。/acp-fleet（或 ctrl+alt+d 快捷键）打开交互式集群检查器：实时列表 + 转录叠加层。在 RPC/print/JSON 模式下自动禁用。
• 可恢复的运行：运行可以从其保存的会话（结果文件旁的 .session.jsonl）中恢复 — 之前的工具调用会被还原而非重放。

配置

与 billion-context-pi 相同的文件约定：~/.pi/acp.json（全局）和 <project>/.pi/acp.json（项目覆盖全局）。本包只读取以下键；同一文件中的所有其他键属于其他包，在此被忽略。

{ "delegate": false }

或对象形式：

{
  "delegate": {
    "enabled": true,
    "maxDepth": 2,
    "maxConcurrent": 3,
    "syncTimeoutMinutes": 5,
    "idleTimeoutMinutes": 5,
    "asyncTimeoutMinutes": 30,
    "thinkingLevel": "medium",
    "notifyIfRead": "skip",
    "displayUsage": "separate",
    "forceEnable": false,
    "fleetShortcut": "ctrl+alt+d",
    "agents": {
      "reviewer": { "model": "anthropic/claude-sonnet-4-5", "thinkingLevel": "high" },
      "worker":   { "model": "zhipu/glm-4.7" }
    }
  }
}

键	类型	默认值	说明
delegate	boolean | object	enabled	主开关。设为 false 将移除三个工具、系统提示词段落及 fleet 快捷键（需新开会话）。
delegate.enabled	boolean	true	同上，对象形式。
delegate.forceEnable	boolean	false	即使项目级 pi-subagents 安装本应使其停用，仍保持 acp_delegate 激活（#415）。环境变量 PI_ACP_DELEGATE_FORCE_ENABLE=true/false 可覆盖。
delegate.displayUsage	"separate" | "merged"	"separate"	"separate"：委托 token 在主会话总量之外单独统计（独立页脚块）。"merged"：合并到工具结果的 usage 字段中。旧版扁平别名：顶层 "displayUsage"。
delegate.maxDepth	number	2	最大嵌套深度（主 → 子 → 孙）。1 = 不允许嵌套委托。通过 PI_ACP_DELEGATE_MAX_DEPTH 传递给子代理。环境变量覆盖：PI_ACP_DELEGATE_MAX_DEPTH。
delegate.syncTimeoutMinutes	number | null	5	同步委托的硬性超时。0/null 表示禁用。环境变量：PI_ACP_DELEGATE_SYNC_TIMEOUT_MINUTES。
delegate.idleTimeoutMinutes	number | null	5	异步委托的空闲看门狗（无输出时终止）。0/null 表示禁用（会发出警告——挂起的子代理此后必须通过 acp_delegate_cancel 手动取消）。环境变量：PI_ACP_DELEGATE_IDLE_TIMEOUT_MINUTES。
delegate.asyncTimeoutMinutes	number | null	30	异步委托的硬性时间上限。0/null 表示禁用。环境变量：PI_ACP_DELEGATE_ASYNC_TIMEOUT_MINUTES。
delegate.maxConcurrent	number	unlimited	并发后台委托数量上限（1 = 严格串行；超出部分排队）。无效值回退为无限制并发并给出警告。环境变量：PI_ACP_DELEGATE_MAX_CONCURRENT。
delegate.thinkingLevel	string	unset	全局默认思考级别（off|minimal|low|medium|high|xhigh|max）。优先级：单次调用 > 角色 > 全局 > Pi 默认值。
delegate.agents	object	unset	按角色设置默认值：{ "<role>": { "model": "provider/id", "thinkingLevel": "…" } }。无效模型回退到父模型并给出警告（不会导致失败）。
delegate.notifyIfRead	"skip" | "always"	"skip"	若模型在运行结束后已读取结果文件，则跳过完成通知。
delegate.fleetShortcut	string	"ctrl+alt+d"	fleet 检查器的 TUI 快捷键。"" 禁用键盘注册（/acp-fleet 仍然可用）。已从 ctrl+alt+f 移开，因为 pi-subagents 也占用了该组合键（#412）。
delegatePrompt	string | null	built-in	替换（字符串）或移除（null）系统提示词附录中的 ACP_DELEGATE NOTIFICATIONS 部分。
debug	boolean	false	在 ~/.pi/acp.log 中记录调试级别事件（与 billion-context-pi 共享）。也可通过环境变量 ACP_DEBUG=1 开启。

无效值永远不会导致会话失败——它们会在 ~/.pi/acp.log 中发出警告并回退到默认值。优先级：环境变量 > 项目 acp.json > 全局 acp.json > 默认值。

任何 delegate.* 键的修改在新会话中生效（工具在会话启动时注册）。

使用自己的子代理替代

如果你同时运行了 pi-subagents（或类似插件），两套重叠的子代理系统会使模型的选择更加混乱。检测发生在会话启动时：

• 项目级安装（<cwd>/.pi/npm/node_modules/pi-subagents 或 <cwd>/.pi/extensions/pi-subagents）→ acp_delegate 对该项目自动停用（跳过工具、快捷键和提示词段落）；会有一条提醒指向 /acp-subagents（来自 billion-context-pi），使第三方代理仍能获得 ACP 压缩。
• 仅用户级安装（~/.pi/npm、用户扩展目录）→ acp_delegate 保持激活；改为记录一条警告。
• 两者都保留：{ "delegate": { "forceEnable": true } }。
• 完全移除本包：pi remove npm:billion-context-pi-subagents。

Pi 的 --exclude-tools acp_delegate,acp_delegate_wait,acp_delegate_cancel 不能替代 delegate: false：它只是隐藏了工具，但模型仍会收到描述其无法调用的工具的 ACP_DELEGATE NOTIFICATIONS 段落。

宿主支持

专为 Pi（@earendil-works/pi-coding-agent >= 0.83）构建。在不具备 Pi 的 buildContextEntries() 会话 API 的宿主上（如 OMP），不会注册任何内容，每个进程仅打印一次警告；兼容 Pi 的分支可通过 PI_ACP_FORK_HOST=1 选择加入（与 billion-context-pi 的 docs/host-adapter.md 相同契约）。

日志

写入共享 ACP 日志 ~/.pi/acp.log（可用 ACP_LOG_FILE 覆盖），格式与 billion-context-pi 相同：

tail -f ~/.pi/acp.log                 # 实时查看会话日志
grep '\[error\]' ~/.pi/acp.log        # 列出所有记录的失败

委托生命周期事件（spawn/done/fail/cancel、停用决策、配置警告）始终开启；debug: true 增加详细诊断信息。

许可证

MIT。