Skip to content

[pi] 内置 billion-context-pi-subagents(acp_delegate)进 Pi lane:官方自有 subagents 支持 #2186

Closed

Description

@ranxianglei

方向

billion-context-pi 已把自带 acp_delegate 子代理系统拆成独立包 billion-context-pi-subagents(billion-context-pi#612,owner 裁定"本项目行为不能变更,需要依赖回来"→ 主包 devDep 精确钉版 + tsup 内联,PR billion-context-pi#613)。本 issue 评估把同一包内置进 bili 的 Pi lane,让 pi install npm:billion-context 的用户直接获得官方子代理能力。

核心收益:delegate 的子代理是裸 pi CLI 子进程,正常加载已装扩展(没有 pi-subagents 的 noExtensions 问题)→ 每个子代理以自己的 sessionId 绑定具名 plugin 模式压缩会话——从根上绕开第三方 pi-subagents 在 native 模式的匿名/运气两格缺陷(与 #2063 修复轨道互补)。

可行性(已在 bili 仓库核对)

  • Pi lane 是 dist/agent/pi.js 自包含打包扩展(package.json pi manifest,宿主 duck-type),与 acp-kernel 同款内联模式可行:devDependency 精确钉版(NEVER caret,同 acp-kernel 纪律)+ tsup 打进 agent entry;dist/index.js 保持零依赖(delegate 只进 agent entry,zod 同款先例)。
  • 新包已具备嵌入面:building-blocks 再导出、markEmbedded() 双装保护(用户又单独安装时独立副本让位)、footer status 键参数化;fix: wire search_context to the kernel search engine (blocks + visible messages, CJK) #415 stand-down 守卫随迁(与第三方 pi-subagents 共存)。
  • ⚠️ omp 门控必须:src/agent/pi.ts 的工厂同时服务 pi 与 omp(dist/agent/omp.js),delegate 是 pi 专属(pi CLI spawn、--mode json、pi-tui)→ 需按宿主探测只在 pi 注册,omp lane 不得出现 delegate 工具。

硬阻塞(顺序)

billion-context-pi-subagents 尚未上 npm(核查时 404):需先在新仓库 Settings 配 NPM_TOKEN secret → 合并其 PR #1(release v0.1.0)→ npm 可见后 bili 才能钉版(CI npm ci 依赖,同 acp-kernel "内核先发版" 硬约束)。

验收

关联:billion-context-pi#612、billion-context-pi#613、billion-context-pi-subagents#1、#2063。

Activity

  1. ranxianglei commented on Oct 5, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    结论先行:硬阻塞核实成立,当前卡在一个我无法代劳的人为动作上——billion-context-pi-subagents 还没上 npm,而发版链上两步都需要 owner 手动完成。npm 可见后我可以立即开工实现 + PR。

    已核实的事实(带证据)

    1. npm registry:billion-context-pi-subagents 404(未发布)。
    2. subagents 仓库:PR fix: keep system prompt byte-stable for prefix cache #1(release v0.1.0)open、mergeable: clean;master 已带 version 0.1.0;release.yml/release-manual.yml 随该 PR 分支落地(master 目前只有 ci.yml)——即合并即触发发布流程。
    3. 该仓库 secrets 列表为空(API 实测零条)→ NPM_TOKEN 未配置。PR fix: keep system prompt byte-stable for prefix cache #1 正文自己也标注了这一点("BLOCKER before merge")。不配 secret 就合并,publish 步骤会在 pre-flight 通过后失败。
    4. 重复筛查:billion-context 仓库 open/closed issue/PR 中无同主题条目;本仓源码 grep 无任何 acp_delegate / billion-context-pi-subagents 引用——干净起点,无并行工作。

    可行性核对(bili 侧,逐条对照 issue 断言)

    • Pi lane 结构:确认 src/agent/pi.ts 的共享工厂 createBiliPlugin(agentOverride?) 同时服务 pi 与 omp——launcher 模式经 -e dist/agent/pi.js(launcher.ts:4346)、native 模式经 package.json pi manifest → dist/agent/pi-native.js,两者 agent 均为 "pi";omp 的两个 entry(omp.ts/omp-native.ts)显式传 "omp"。omp 门控有天然落点:delegate 注册接进工厂并以 agent === "pi" 门控,一次覆盖 pi 两条加载路径、排除 omp 两条。
    • 双保险:包自身在 session_start 用 isPiHost(ctx.sessionManager)(要求 Pi 的 buildContextEntries() API)门控,omp 天然不满足 → 不注册并一次性告警(PI_ACP_FORK_HOST=1 可 opt-in)。显式门控 + 宿主探测两层都在。
    • 构建链:tsup.config.ts 的 noExternal 已有 acp-kernel 等内联先例;把新包加入其中只影响 import 它的 agent entry,dist/index.js 保持零依赖(zod 同款先例成立)。devDep 精确钉 0.1.0,NEVER caret。
    • 嵌入面(已克隆包源码通读确认):markEmbedded()(globalThis Symbol.for 标记,用户单独安装的副本在 session_start 让位)、building-blocks 再导出(makeDelegateTool 三件套、resolveDelegate、delegateStatusWidget、openFleetInspector、fix: wire search_context to the kernel search engine (blocks + visible messages, CJK) #415 的 findPiSubagentsInstalls stand-down 检测等)齐备。
    • 一个新增考量(类型依赖):包的 d.ts 引用 @earendil-works/pi-coding-agent / @earendil-works/pi-tui / typebox 的类型(peerDeps 为 *)。bili tsconfig 有 skipLibCheck: true 不会硬炸,但为了让 typecheck 真正有效,devDependencies 需同步精确钉这三个类型源(@earendil-works/pi-coding-agent@0.83.0 等,与包 devDeps 对齐)。
    • 配置面:本改动不新增任何 bili 配置键/env var——delegate.* 继续由包从 ~/.pi/acp.json 读取,PI_ACP_DELEGATE_* env 也归包所有,bili 配置面零变化(PR 里会按规范声明)。

    顺带发现(供全局视角,不阻塞本 issue)

    billion-context-pi#613 的当前 diff 仍是"整体移除 delegate + README 引导用户单独安装"形态,没有加 devDep(package.json 不在其 diff 里)——与本 issue 引用的裁定("主包 devDep 精确钉版 + tsup 内联")不一致。subagents#1 正文称嵌入面是 "needed by billion-context-pi's follow-up",推测 #613 的钉版部分是后续再补;如果属实,#613 按现状合并会让 BCP 用户丢失内置 acp_delegate(行为变更)。不影响本 issue——bili 直接钉 npm 版本,与 BCP 侧解耦。

    计划(npm 可见后立即执行)

    1. 分支 2026-MM-DD_builtin-pi-subagents:devDep 精确钉版(+ 类型依赖)、tsup noExternal 加包名、工厂内 agent === "pi" 门控接线(load 期 markEmbedded())。
    2. 测试:定向单测(omp lane 无 delegate 注册、双装让位、stand-down 守卫)+ 扩展 tests/e2e/e2e-native-pi.test.ts 覆盖验收四条(delegate 子代理具名压缩生效 / omp 不注册 / 双装无重复 / 与 @gotgenes/pi-subagents 共存)。全量回归交 CI。
    3. 单个 PR,Closes #2186,正文含 config-surface 声明(零新增)。
    4. 不先推红分支:CI 只在 PR 上跑,发布前 npm ci 必然 404,所以等 npm 可见后 lockfile + push + PR 一步到位。

    需要 owner 的动作(顺序)

    1. 在 ranxianglei/billion-context-pi-subagents → Settings → Secrets 配 NPM_TOKEN(与 billion-context-pi 相同值);
    2. 合并 release v0.1.0 billion-context-pi-subagents#1(agent 无权合并 PR,这步只能人工);
    3. 确认 npm 上 v0.1.0 可见后在本 issue 评论触发我(如「继续」),我立即按上述计划交付。
  2. ranxianglei commented on Oct 5, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    补充一条本地验证发现的新硬约束(issue 可行性一节未预见),影响实现方案,请裁定。

    发现:包 dist 携带一个运行时宿主裸导入

    我把 subagents 包源码 clone 下来实际构建 + 做了 esbuild 内联探针(等价于 bili tsup noExternal 的打包路径):

    • dist/index.js 是 448KB 单文件 ESM:typebox、pi-tui(fleet-inspector 的运行时依赖)都已内联;唯一残留的运行时裸导入是 import * as piModule from "@earendil-works/pi-coding-agent",来自 src/config-dir.ts——读 CONFIG_DIR_NAME(带 ".pi" 兜底,fix: surface raw-dump failures and rate-limit telemetry path noise (#362) #364 的宿主特性探测)。其余两处引用均无害:delegate-tool.ts 对 pi-coding-agent 是纯 import type(编译擦除),fleet-inspector.ts 的 pi-tui 已打进 dist。
    • 内联探针本身成功(输出中 0 处包名残留),但那个裸导入让 esbuild 把整个 pi-coding-agent 连带拉进 bundle(输出 12.5MB),其 CJS 依赖(cross-spawn)在 ESM 下抛 Dynamic require of "child_process" is not supported(bili tsup 现有的 createRequire banner 能救,但代价是每个 entry +12MB 及宿主包 import-time 副作用风险)。
    • 影响面:若在共享工厂 src/agent/pi.ts 静态引入该包,四个 entry(pi.js / pi-native.js / omp.js / omp-native.js)都会带上这个裸导入。pi lane 有 billion-context-pi 的生产先例(BCP 的 dist 同样保留该裸导入且正常工作),但 omp lane 与混合安装前缀场景无保证,且直接违反 bili 明文不变量(src/agent/pi.ts 头部:"the bundled artifact imports NOTHING from the host at runtime")。

    三个选项

    方案 做法 代价
    A(推荐) subagents 包侧断根:config-dir.ts 改为 createRequire 探测 + try/catch(保留 #364 语义:宿主可解析时取 CONFIG_DIR_NAME,否则 ".pi"),diff 约 15 行、对独立安装/pi 用户零行为变化 → dist 零裸导入 → bili 按原计划 acp-kernel 同款内联,四个 entry 全干净、零新增运行时依赖 subagents 侧多一个极小 PR,随同一次发布落地
    B bili 把该包放 dependencies(真实运行时依赖)+ tsup 保持 external + 仅 pi 门控下动态 import dist 保持瘦(+448KB tarball),但破例引入首个非 zod 运行时依赖(agent entry 契约变更需显式声明),且该包 dist 里的宿主裸导入要靠 Node 从 npm-global 向上解析——混合前缀(pnpm/bun/多 node)下 pi lane 可能硬加载失败(可 catch 降级为「delegate 不可用」,但整个扩展加载路径变脆)
    C bili 直接 bundle pi-coding-agent 进 entry 12MB+/entry + 副作用风险,最重,仅列作排除项

    推荐 A:两边契约都不破,issue 原前提("acp-kernel 同款内联模式可行")恢复成立,修复面极小。注意 BCP#613 不受此发现影响(BCP 自身 dist 本就带同样的宿主裸导入,该修复对它只是去冗余)。

    修订后的动作清单(owner)

    1. (新增,建议) 批准我在 ranxianglei/billion-context-pi-subagents 准备 config-dir 修复 PR(先落 master,不发布);
    2. 配 NPM_TOKEN secret(不变);
    3. 合并 release PR(带上步骤 1 的修复后 rebase 一次即可,发一个版本,不必两次发布)。

    npm 可见后在本 issue 触发我,我按上一条回复的计划交付 bili 侧实现 + PR。未获批准前我不会向该仓库提交任何东西。

  3. ranxianglei commented on Oct 6, 2026

    @ranxianglei
    OwnerAuthor

    Implementation PR: #2221

    Embeds billion-context-pi-subagents (0.1.1, just published via package PR #2 + release PR #4) into the native pi extension through the package's embedder contract (markEmbedded() + manual building-block wiring + tsup inline). pi lane only; omp untouched; zero new config surface; dist/index.js/dist/mcp.js import graph unchanged.

  4. ranxianglei commented on Oct 6, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷

    PR #2221 review 完成。一句话:方向正确、实现扎实;CI 四腿红的根因是一个测试 fake 对宿主事件模型建模错误(已定位并修复),另有几处小缺陷顺手修掉。三个修复 commit 已推到分支 2026-10-05_pi-subagents-embed(bacabf434、59969fba1、78c5d6538)。

    ① 原 issue 方向:#2186 要求把官方 subagents 内置进 Pi lane。PR 用包内嵌契约(markEmbedded + building-blocks 手动接线 + tsup inline)精确实现,omp 门控排除、零新增配置面——方向与 issue 一致。实现路线(v0.1.1 补导出 + tsup alias stub 掉唯一宿主 import)不同于我在线程里建议的包侧切割,但效果等价且保持包独立形态,接受裁定。

    ② CI 四条测试腿全红的根因(每腿失败同一例:#2072 … timed out waiting for the acp_cache tool):tests/issue2072-native-caller-stamping.test.ts 的 fake 把 pi.on(event, handler) 建模成单槽 Map,而真实 pi 是多监听者广播(按注册顺序派发给所有 handler)。bili 工厂本身已有两个 session_start 注册(repin + registerTools——acp_cache 就是它注册的);本 PR 的接线加了第三个(最后注册)→ 单槽 fake 只剩最后一个 → registerTools 永不执行 → acp_cache 超时。wiring 代码无缺陷,是合法的第三注册暴露了 fake 对宿主的错误建模。你已修好这个文件(3e51990,数组模型,引 pi-coding-agent@0.83.0 runner.js emit()——比我最初的组合写法更忠实)。
    还有一颗孪生地雷:tests/plugin-agent.test.ts 的 fake 同样是单槽(且 ~20 个 fire-site)。今天能过只是因为它现有断言不依赖主 session_start 的副作用,未来一旦依赖会以同样方式炸。已在 commit 1 修(原地组合、最小 diff)。

    ③ 其他小缺陷(已直接修):

    • tests/pi-subagents-wiring.test.ts 的「fleet policy gate」测试从未真正调用过 handler(fake 不存 command options,注释自认)——假测试,且 PR body 把它宣称成了已测。重写为真实驱动 handler(delegate.enabled=false → 断言通知文案);并补上 fix: wire search_context to the kernel search engine (blocks + visible messages, CJK) #415 project-scope stand-down 测试(tools 不注册 + 一条 warning toast)(commit 2)。
    • src/agent/pi-subagents.ts 静默吞掉 acp.json 加载失败(catch {})——独立包装会 logThrow,嵌入版丢失全部诊断。改为 console.error(agent 模块 house style,同 opencode.ts/pi.ts)(commit 3)。
    • architecture.md 目录树缩进错位(commit 3)。

    ④ 回归清点(diff 触碰路径的既有行为):

    • dist/index.js 零依赖不变量:base vs head 字节尺寸一致(4,071,834 B),所有 dist entry 均无裸宿主 import ✓
    • dist/mcp.js import graph 不变 ✓
    • omp lane:omp/omp-native entry 不注册任何 delegate 工具(bundle 级验证,agent !== "pi" early return 门控)✓
    • 真实宿主 wire 行为不变:第三 session_start handler 为纯增量,真实 pi 广播给所有监听者 ✓
    • 双装保护(Symbol.for claim)与 fix: wire search_context to the kernel search engine (blocks + visible messages, CJK) #415 共存守卫:与独立工厂逐项 parity 核对一致,现已有测试钉住 ✓
    • Bundle 体积变化(披露):pi.js 763,835→1,131,232(+367KB 有效代码);omp.js 763,805→1,131,202(+367KB 死代码——静态 import 经 pi.ts 进入共享模块图;动态 import 被 dist-import-annotations 门禁禁止);pi-native.js 2,245,807→2,615,339;omp-native.js 2,236,632→2,606,159。index.js/mcp.js 不变。若在意 omp 白背的 ~367KB,需放宽 annotations 门禁或拆 entry——单独决策,不动本 PR。
    • 用户可见行为:pi lane 用户默认获得 /acp_delegate、_wait、_cancel 工具 + /acp-fleet 命令 + shortcut + prompt append(包默认 enabled=true)——即本 PR 的预期功能。

    ⑤ 缓存:不涉及(未触碰缓存/重试/游标/去重键)。
    ⑥ 设计方向:不变——按你裁定的 embedder contract 走,无架构转向。
    ⑦ 新配置:无。delegate 配置留在包既有的 ~/.pi/acp.json 面(env > project > global > default 优先级不变),未新增任何 bili 配置字段或 env var——符合 #1437 纪律。

    遗留一项缺口(建议本线程内后续做,不单拆 issue):验收标准 1「delegate 子代理各自具名压缩生效」目前没有自动化覆盖——CI 里过的「real pi package-native lane」只证明不回归(该套件不脚本化 delegate 调用)。建议后续加一条 hermetic e2e:驱动一次真实 acp_delegate 调用,断言子代理 sessionId 绑定具名 plugin-mode 压缩会话。

    结论(七问):是什么问题——PR review + CI 红腿定位;什么原因——测试 fake 单槽建模 vs 宿主多监听广播;怎么修的——fake 忠实化(owner 数组模型 + 我修孪生 fake)+ 假测试重写 + #415 覆盖 + 配置失败日志;是否回归——产品行为零回归(零依赖不变量字节级验证),bundle 体积变化已披露;缓存——不涉及;设计方向——不变;新配置——无。可合,待 78c5d6538 上 CI 转绿后由你合并:#2221

  5. ranxianglei commented on Oct 6, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷

    CI 在 78c5d6538 上全绿:四条测试腿(ubuntu/windows × node 22/24)✅、e2e-native-pi(真实 pi package-native lane)✅、lane-guard / kernel-guard / version-guard / docs ✅。之前红腿的 #2072 acp_cache timeout 已随 fake 修复消失。

    PR #2221 现在可以合并了(合并留给你):#2221

  6. added a commit that references this issue on Oct 6, 2026
  7. added a commit that references this issue on Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions