Pi Agent 扩展：为 Aether 添加工具与命令

Pi 扩展接入驱动 Aether 的 agent 执行引擎。它们添加 agent 在回合中可调用的自定义工具、用户可直接调用的斜杠命令，以及会话生命周期钩子 — 全部在 Pi 框架的 agent 循环内运行。

什么是 Pi 扩展？

Aether 运行在 Pi agent 框架（@earendil-works/pi-agent-core、@earendil-works/pi-coding-agent）之上。Pi 扩展是标准的 Pi 框架扩展，可完整访问在 Aether 内运行的 agent 循环。由于它们在 Node.js 桥接进程中执行，因此拥有完整的 Node.js 运行时，以及 Pi 框架的工具调用与命令分发基础设施。

声明 Pi 扩展

在 package.json 中添加 pi.extensions 数组，指向一个或多个入口文件：

package.json

{
  "name": "my-pi-extension",
  "version": "1.0.0",
  "pi": {
    "extensions": ["./agent.ts"]
  }
}

扩展激活时，Pi 框架会加载每个入口文件。

Pi 扩展工厂

入口文件必须导出一个 默认函数，由 Pi 框架以 ExtensionAPI 实例调用：

agent.ts

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function activate(pi: ExtensionAPI) {
  // Register tools, commands, and hooks here
}

工厂可以是同步的，也可以是 async。使用 pi 参数注册扩展提供的一切。

Pi 与 Aether 扩展对比

单个包可同时包含 Pi 扩展与 Aether Script Mod。它们承担不同角色：

	Pi extension	Aether Script Mod
运行时	Node.js 桥接进程	Android 应用进程（JS 桥接）
主要职责	Agent 工具、命令、agent 循环钩子	Android UI surface、组件替换、宿主 API 访问
入口导出	默认导出（`activate`）	命名导出（`activateAether` 或 `aether`）
重载	触发扩展重载时重载	触发扩展重载时重载

当你需要在同一包中同时具备 agent 循环能力与 Android UI 定制时，将 Pi 工厂保留为默认导出，并将 Aether 工厂导出为 activateAether。组合示例见工具与命令。

Pi 框架 API（ExtensionAPI）由 @earendil-works/pi-coding-agent 包定义。完整 API 表面（含会话钩子、流式传输与高级工具选项）请参阅 Pi 框架文档。

概览

Script Mod API

UI 参考

Native Mods

Pi 扩展

示例

Pi Agent 扩展：为 Aether 添加工具与命令

什么是 Pi 扩展？

声明 Pi 扩展

Pi 扩展工厂

Pi 与 Aether 扩展对比

​什么是 Pi 扩展？

​声明 Pi 扩展

​Pi 扩展工厂

​Pi 与 Aether 扩展对比

什么是 Pi 扩展？

声明 Pi 扩展

Pi 扩展工厂

Pi 与 Aether 扩展对比