Skip to content

docs: explain pi built-in subagents and how to disable them - #2380

Merged
ranxianglei merged 2 commits into
ranxianglei:masterfrom
xiaozhu1337:2026-10-08_docs-pi-subagents
Oct 8, 2026
Merged

ranxianglei merged 2 commits into
ranxianglei:masterfrom
xiaozhu1337:2026-10-08_docs-pi-subagents

Conversation

@xiaozhu1337

Copy link
Copy Markdown
Contributor

Closes #2379

pi 用户在 README 安装入口看不到默认内置的子代理功能,容易继续启用其他 subagent 插件,也不容易找到只关闭子代理、保留上下文压缩的方法。

本 PR 在中英文 README 的客户端选择表后同步增加说明:

  • bili pi 和 pi 原生插件默认自带 acp_delegate、acp_delegate_wait、acp_delegate_cancel。
  • 建议只启用一套子代理实现:使用内置功能时,在用户级和项目级配置中移除或禁用其他子代理插件;保留其他插件时,关闭内置功能。说明项目级 pi-subagents 的自动让位保护与仅有用户级安装时的区别。
  • 给出合并 {"pi":{"subagents":false}} 的完整配置示例、配置文件位置、BILI_CONFIG_FILE 覆盖方式,以及重启 pi 并开启新会话的生效条件。说明上下文压缩继续启用,独立插件需要分别处理。

仅修改 README.md 和 README.zh-CN.md,共新增 36 行;链接现有中英文配置参考,不改变运行行为或配置结构。

验证:

  • 文档检查通过:UTF-8 无 BOM、JSON 示例可解析、相对链接及 #pi 锚点存在、代码块闭合、git diff --check。
  • TypeScript 类型检查通过;内核构建、主包构建和 dist import annotations 检查通过。
  • 全量测试运行:4,903 通过、25 跳过、1 失败。唯一失败为 tests/web-routing.test.ts 中 Web 代理设置测试:本机继承的 BILI_UPSTREAM_PROXY 按既有优先级覆盖了测试设置的地址。在复测子进程中移除该变量后,该文件的 8 项测试全部通过;未修改任何源码或测试。
  • 提交前重新获取上游 master,基线仍为 1716212。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #2380 审查结论(docs-only,纯插入 +36 行,基线即当前 master 1716212,无需 rebase)

逐条事实核对(全部对源码验证过):

  • 三个内置工具名 acp_delegate / acp_delegate_wait / acp_delegate_cancel:✅ tests/pi-subagents-wiring.test.ts:85、CONFIGURATION.md:694 一致。
  • 「默认启用」:✅ src/config.ts:1308 — "Master switch, default true"。
  • "pi": {"subagents": false} 关闭三工具 + 系统提示词段 + fleet 快捷键、需新会话:✅ 与 src/config.ts:1309-1310 注释逐字对应(removes the three tools, the system-prompt section and the fleet shortcut (new session required));代码路径 src/agent/pi-subagents.ts:179-195(工具/快捷键注册都 gated 在 policy.enabled && !stoodDown)、:203-204(禁用后不再注入系统提示词)。
  • 「项目级 pi-subagents 让位、仅用户级不让位」:✅ src/agent/pi-subagents.ts:157-172 — 仅 scopes.project[0] !== undefined 触发 stand-down,user-only 保持启用,文档措辞准确且正确提醒了「不能把这项保护当作所有安装方式的保障」。
  • 配置文件位置 ~/.config/billion-context/billion-context.json + BILI_CONFIG_FILE 覆盖:✅ 与 README 既有 Config file 节一致。
  • 链接锚点:✅ CONFIGURATION.md:689 与 CONFIGURATION.zh-CN.md:689 均为 ### \pi`,GitHub slug 恰为 #pi`,中英文链接都有效。
  • 「上下文压缩仍然启用 / 不影响独立安装的子代理插件」:✅ 该开关只作用于 delegate 面,压缩是代理侧机制;stand-down 守卫只检测不卸载第三方插件。
  • 放置位置:客户端选择表后的 "Which do I need?" 节内新增 ### 小节,层级正确;中英文对称。

diff 整洁度:2 文件、36 插入 0 删除,git diff --check 干净,无无关改动,与 PR 描述完全一致。

重复筛查:无重复的开放 PR;相关已合并工作(#2221 内联、#2230 配置家)是功能本身,本 PR 补的是入口文档缺口(#2379),方向正确。

CI:已完成的全部检查绿(docs-sync、docs-coverage、kernel-guard、lane-guard、build-artifact、version-guard、unused-exports、全部 real-client e2e lane、hermetic registry e2e);4 个 test 矩阵作业仍在跑,完成后应全绿(作者本地唯一失败为环境继承 BILI_UPSTREAM_PROXY 覆盖 web-routing 测试目标,移除变量后通过,与本 docs 变更无关,CI 干净环境不受影响)。


结构化八问

  1. 是什么问题:README 安装入口没有说明 bili pi 默认自带子代理功能,用户容易叠加其他子代理插件或找不到「只关子代理、保留压缩」的开关。
  2. 什么原因导致的:纯文档缺口 —— 功能本身([pi] 内置 billion-context-pi-subagents(acp_delegate)进 Pi lane:官方自有 subagents 支持 #2186 内联、Built-in pi sub-agents config: move acp.json delegate keys to billion-context.json (pi.subagents) #2230 配置家)早已完整落地,但 README 入口层说明没跟上。
  3. 影响范围与严重程度:仅文档可发现性,零运行行为影响;属体验/文档瑕疵。
  4. 怎么修复的:中英文 README 选择表后同步新增「Pi: built-in subagents」小节,列出工具清单、单实现建议、让位守卫边界、完整 JSON 示例与生效条件,并链接到既有配置参考而非重述细节。
  5. 是否有回归问题:无 —— 纯插入(0 删除),未触碰任何源码/测试/配置,既有文档内容逐字未动。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:无 —— pi.subagents 字段为 Built-in pi sub-agents config: move acp.json delegate keys to billion-context.json (pi.subagents) #2230 已有,本 PR 只做文档化,无新 env/字段/默认值。

判定:可合(待 4 个 in-progress test 作业跑完转绿;合并由人工执行)。

@ranxianglei

Copy link
Copy Markdown
Owner

是不是放错了位置?可以在 pi 安装插件的地方提一嘴 然后详情放到后面 不影响主要流程

Per review feedback: keep the entry flow (client table -> Install ->
Quickstart) uninterrupted. One-line mention with anchor link in the
Option 1 native-plugin notes where pi installs are documented; full
details moved to a 'Pi built-in subagents' subsection at the end of
the Configuration section. Content unchanged, en/zh mirrored.
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 已按意见调整并推送到 PR 分支(增量提交 732ef05d3,保留原作者署名):

调整内容(en/zh 对称):

  1. 「该选哪个 / Which do I need?」里的详情小节整段移除——客户端选择表 → Install → Quickstart 主流程不再被打断。
  2. pi 安装插件的地方提一嘴:Option 1(原生插件)bili plugin install pi 的 Notes 列表加一行 ——「原生安装默认自带子代理功能(acp_delegate 三件套)—— 如何关闭它们并保留上下文压缩:锚点链接」。
  3. 详情放到后面:完整小节原样移到 ## Configuration 节末尾,标题 ### Pi built-in subagents(zh:### Pi 内置子代理)。选这里是因为内容主体就是配置文件指引({"pi":{"subagents":false}}、文件位置、BILI_CONFIG_FILE、生效条件),与配置节主题一致且远离安装主流程。若你想放别处(如 FAQ),说一声我再挪。

验证:git diff --check 干净;代码块闭合;两个 JSON 示例均可解析;无 BOM;新增锚点与目标标题 slug 逐一核对有效(#pi-built-in-subagents / #pi-内置子代理);相对链接不变。对 master 净增 19 行/文件(原 18 行移动 + 1 行提及)。内容零改动,纯位置调整。


结构化八问

  1. 是什么问题:按 owner 反馈,新文档小节放在客户端选择表后打断了「选客户端 → 安装」的主阅读流程。
  2. 什么原因导致的:初稿把详情放在了最显眼的入口位置,可发现性与阅读流畅性没平衡好。
  3. 影响范围与严重程度:纯文档排版,零运行行为影响;体验优化项。
  4. 怎么修复的:入口只留一行带锚点链接的提及(pi 原生插件 Notes 处),详情整体后移到 Configuration 节末,正文逐字未动。
  5. 是否有回归问题:无 —— 既有文档内容全部保留,仅移位;锚点链接已验证可达。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:无。

PR 现为 mergeable(behind 的仅是 v0.1.188 release 提交,未触碰 README,无需 rebase);CI 在新 head 上重跑中。判定:待 CI 转绿后可合(合并人工执行)。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 补充:新 head 732ef05d3 的 CI 已全部跑完 —— 23/23 检查全绿(含 docs-sync、docs-coverage、kernel-guard、lane-guard、build-artifact、全部 real-client e2e lane、hermetic registry e2e、4 个 test 矩阵)。PR 处于 mergeable 状态,可合。

@ranxianglei
ranxianglei merged commit 0812344 into ranxianglei:master Oct 8, 2026
23 checks passed
@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.135-master.0812344 (rolling master tag).

npm install -g billion-context@0.0.135-master.0812344  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs][Pi] README 说明内置子代理、插件冲突规避及关闭方式

2 participants