pi-mono sdk中文文档

Pi (即 @mariozechner/pi-coding-agent) 的 SDK 允许开发者将 Pi 的核心能力（如模型调用、工具执行、文件编辑、Session 管理）直接嵌入到自己的 Node.js 或 TypeScript 应用中。

以下是关于 Pi SDK 的详细展开讲解：

1. 核心组件架构

要运行一个 Pi 代理实例，SDK 提供了四个核心支柱：

AuthStorage: 处理身份验证。它负责管理 API 密钥（如 Anthropic, OpenAI）和 OAuth 令牌。
ModelRegistry: 模型注册表。它定义了哪些模型可用、它们的 API 类型（OpenAI/Anthropic 等）以及它们是否支持工具调用（Tool Calling）。
SessionManager : 会话管理器。决定聊天历史记录如何存储。你可以使用 inMemory()（仅内存，重启即消失）或基于文件的存储。
AgentSession : 最核心的对象。你通过它发送 Prompt，并监听它的输出、工具调用过程和最终结果。

2. 快速起步示例

以下是一个最小化的 SDK 集成示例，用于在你的代码中创建一个可以执行终端命令和读写文件的智能体：

typescript 复制代码

import { 
  AuthStorage, 
  createAgentSession, 
  ModelRegistry, 
  SessionManager 
} from "@mariozechner/pi-coding-agent";

async function main() {
  // 1. 初始化身份验证存储（默认读取 ~/.pi/agent/ 目录下的配置）
  const authStorage = AuthStorage.create();

  // 2. 初始化模型注册表
  const modelRegistry = new ModelRegistry(authStorage);

  // 3. 创建 Agent 会话
  const { session } = await createAgentSession({
    sessionManager: SessionManager.inMemory(), // 使用内存存储会话历史
    authStorage,
    modelRegistry,
    // 可选：指定模型，如果不指定则使用默认配置
    model: "anthropic/claude-3-5-sonnet-latest" 
  });

  // 4. 发送 Prompt 并获取响应
  // prompt 方法会返回一个流式结果或等待最终完成
  const response = await session.prompt("分析当前目录下的 package.json 文件并告诉我依赖项。");
  
  console.log(response.content);
}

main();

3. SDK 的关键功能详解

A. 工具系统 (Tools)

SDK 默认集成了 Pi 的核心工具（read, write, edit, bash）。当你在 SDK 中运行 session.prompt() 时，如果模型决定调用工具，SDK 会自动在宿主环境下执行对应的操作。

安全性控制：在 SDK 中，你可以通过配置来限制 Agent 只能使用特定的工具。
自定义工具：你可以通过扩展 (Extensions) API 在 SDK 初始化时注入自定义的函数工具。

B. 事件监听 (Events)

与 CLI 不同，在 SDK 模式下，你通常需要实时获取 Agent 的状态。AgentSession 提供了丰富的事件钩子：

typescript 复制代码

session.on("text", (chunk) => {
  // 实时获取助手输出的文本流
  process.stdout.write(chunk);
});

session.on("tool_call", (call) => {
  // 当模型想要执行 bash 或读写文件时触发
  console.log(`正在执行工具: ${call.name}`, call.args);
});

session.on("thinking", (thought) => {
  // 获取深度思考模型（如 Claude 3.7 或 R1）的思考过程
  console.log("思考中...", thought);
});

C. 会话持久化

通过 SessionManager.file(path)，你可以轻松实现像 Pi CLI 那样支持断点续传的对话系统。

你可以加载旧的 Session ID 来恢复上下文。
SDK 支持分支 (Branching) 管理，允许你从 Session 历史中的任意一点"分叉"出新的对话路径。

4. 高级用法：集成扩展 (Extensions)

Pi 的强大之处在于其扩展系统。在 SDK 中，你可以手动加载这些扩展：

typescript 复制代码

import { MyCustomExtension } from "./my-extension";

const { session } = await createAgentSession({
  // ... 其他配置
  extensions: [
    (api) => MyCustomExtension(api), // 注入自定义逻辑
  ]
});

这允许你在自己的应用中添加特定的业务逻辑，例如：

权限网关 ：在执行 bash 命令前，通过 SDK 弹窗请求用户许可。
自定义 UI：如果你的应用有图形界面，可以拦截工具输出并将其渲染为图表。

5. 为什么选择使用 SDK 而不是 CLI？

构建自定义 UI：你想开发一个类似 Claude Dev (Cline) 的 VS Code 插件或网页版 Web IDE。
自动化工作流：在 CI/CD 流水中集成 Agent，自动根据测试失败结果修复 Bug 并提交 PR。
受控环境：你想在受限的沙盒环境（如 Docker）中运行 Pi，并严格限制其能执行的命令。
嵌入式 AI 助手：在现有的 Node.js 后台服务中添加一个"理解代码"的 API 接口。

总结

Pi 的 SDK 是将 "LLM -> 工具调用 -> 文件系统操作" 这一复杂循环封装好的高度抽象库。通过 createAgentSession，你不需要自己处理复杂的工具调用解析、上下文窗口管理（Compaction）和流式传输，只需关注你的业务逻辑即可。