Coding 工具 · 05

Pi

使用 Pi extension 的 agent_settled 事件，在自动重试、自动压缩和排队续跑都结束后，再把一次完成交给 bluebell。

当前官方生命周期

使用 agent_settled，不使用 agent_end

agent_end 只表示一次底层运行结束，Pi 之后仍可能自动重试、压缩后重试，或继续处理排队消息。agent_settled 会等到这些自动动作都不再继续，更适合作为状态提醒候选。

步骤 1

创建 bluebell extension

bluebell.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { execFile } from "node:child_process";
import { basename } from "node:path";

const CLI = "/Applications/bluebellMac.app/Contents/Helpers/bluebellctl";

export default function (pi: ExtensionAPI) {
  pi.on("agent_settled", (_event, ctx) => {
    const sessionID = ctx.sessionManager.getSessionId();
    const leafID = ctx.sessionManager.getLeafId();
    if (!sessionID || !leafID) return;

    execFile(CLI, [
      "emit",
      "--source", "Pi",
      "--workspace-name", basename(ctx.cwd) || "Pi",
      "--session-id", sessionID,
      "--turn-id", leafID,
      "--dedupe-key", `pi:${sessionID}:${leafID}`,
      "--local",
    ], { timeout: 3000 }, () => {});
  });
}

把 CLI 替换为客户端复制出的真实路径。示例使用 Pi 的 session UUID 与当前 leaf entry ID 作为稳定身份，不读取会话正文；execFile 的失败也不会阻止 Pi。

步骤 2

选择一个安装位置

位置作用范围
~/.pi/agent/extensions/bluebell.ts当前用户的所有 Pi 项目。
.pi/extensions/bluebell.ts只对当前项目生效，项目需要被信任。
pi -e /absolute/path/bluebell.ts只用于一次临时测试。

不要同时安装全局版和项目版。保存到自动发现目录后可使用 /reload 重新加载 extension。

步骤 3

测试普通完成与自动续跑

  1. 保持 bluebell Mac 运行，完成一轮没有重试的短任务，确认只出现一条 Pi 本机事件。
  2. 在同一 session 发出第二个 prompt，确认 leaf ID 改变并产生一条新事件。
  3. 测试一次会触发自动重试、压缩或排队 follow-up 的工作流，确认只有最终 settled 后提醒。
  4. 重复触发同一 session 与 leaf 身份，确认 bluebell 返回 duplicate 而不是新增提醒。
  5. 验证后删除 extension 中的 --local，再检查 Mac 总推送与真实设备。

来源

Pi 官方资料