Pi Extension 机制及工作原理

设计哲学：为什么用 Extension？

Pi is aggressively extensible so it doesn't have to dictate your workflow.

其他 AI 编码助手内置的特性（Plan Mode、Sub-agent、MCP、权限弹窗、待办列表、后台 Shell）， pi 全部不做。取而代之的是一套 Extension 机制，让用户按自己需要构建这些能力。

内核只做最小的事：四种基础工具（read、write、edit、bash）加上基本 TUI。 所有高级特性通过 Extension 实现，不侵入核心代码。

三层架构

一、加载层（loader.ts）

运行时依赖解析

Extension 是 TypeScript 文件，通过 jiti 在运行时直接加载，无需编译。模块别名保证扩展 import 的是 pi 内部打包实例：

扩展发现

discoverAndLoadExtensions() 按优先级扫描三处（不递归，只一层）：

extensions/
├── my-ext.ts          → 单文件扩展
├── my-package/        → 子目录
│   ├── package.json   → 优先读 pi.extensions
│   └── index.ts
└── with-deps/         → 可带 node_modules
    ├── package.json
    └── src/index.ts

Extension 对象模型

每个扩展加载后生成独立 Extension 对象，数据不共享：

interface Extension {
  sourceInfo: SourceInfo;
  handlers:         Map<string, Function[]>;
  tools:            Map<string, RegisteredTool>;
  commands:         Map<string, RegisteredCommand>;
  flags:            Map<string, ExtensionFlag>;
  shortcuts:        Map<string, ExtensionShortcut>;
  messageRenderers: Map<string, Function>;
  entryRenderers:   Map<string, Function>;
}

ExtensionAPI 的两层委托

ExtensionRuntime：延迟绑定

共享 Runtime 初始化时，所有 action 方法都是 throwing stub。 扩展加载期是纯声明阶段，不能发消息、改工具集。 bindCore() 后 stub 被替换为真实 AgentSession 实现。

二、运行层（runner.ts）

bindCore：连接真实世界

runner.bindCore(
  actions,         // sendMessage, appendEntry, ...
  contextActions,  // getModel, isIdle, abort, compact, ...
  providerActions, // registerProvider（可选）
);

1. 注入 actions → 替换 throwing stub
2. 保存 context 闭包（getModel、isIdle…）
3. 冲刷 provider 队列
4. 之后 registerProvider 立即生效

createContext：懒求值

ExtensionContext 用 getter，每次访问实时取值， 避免 session 切换后闭包快照过时：

return {
  get ui() { return runner.uiContext; },
  get cwd() { return runner.cwd; },
  get model() { return getModel(); },
  get signal() { return runner.getSignalFn(); },
  isIdle: () => runner.isIdleFn(),
  compact: (opts) => runner.compactFn(opts),
};

事件分发的三种模式

按扩展加载顺序串行；每个 handler 包 try-catch，异常绝不向上传播。

async emitToolResult(event) {
  const currentEvent = { ...event };
  for (const ext of this.extensions) {
    for (const handler of handlers) {
      const result = await handler(currentEvent, ctx);
      if (result?.content) currentEvent.content = result.content;
      if (result?.details) currentEvent.details = result.details;
      if (result?.isError) currentEvent.isError = result.isError;
    }
  }
  return { content, details, isError };
}

hashline 的 read hook 正是挂在 tool_result 链上， 把 [PATH#TAG] 快照头注入模型可见结果。

Stale Context 保护

Session 切换 / fork / reload 后，invalidate() 标记 stale， 旧 pi / ctx 上任何操作都抛异常， 防止扩展误用旧引用（最容易出 bug 的地方）。

三、包装层（wrapper.ts）

扩展工具经 wrapRegisteredTool() 变成 agent-core 的 AgentTool。 每次 execute 创建新 context；若执行期间动态 registerTool， 返回 addedToolNames 通知系统刷新工具集。

四、完整生命周期

五、设计要点总结