自定义提供商

扩展可通过 pi.registerProvider() 注册自定义模型提供商。这使您能够：

代理 - 通过企业代理或 API 网关路由请求
自定义端点 - 使用自托管或私有模型部署
OAuth/SSO - 为提供商添加认证流程
自定义 API - 为非标准 LLM API 实现流式传输

示例扩展

查看完整的提供商示例：

快速参考

typescript

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

export default function (pi: ExtensionAPI) {
  // 覆盖现有提供商的 baseUrl
  pi.registerProvider("anthropic", {
    baseUrl: "https://proxy.example.com"
  });

  // 带模型的注册新提供商
  pi.registerProvider("my-provider", {
    name: "My Provider",
    baseUrl: "https://api.example.com",
    apiKey: "$MY_API_KEY",
    api: "openai-completions",
    models: [
      {
        id: "my-model",
        name: "My Model",
        reasoning: false,
        input: ["text", "image"],
        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
        contextWindow: 128000,
        maxTokens: 4096
      }
    ]
  });
}

扩展工厂也可以是 async。对于动态模型发现，在工厂中获取并注册模型，而不是在 session_start 中。Pi 在启动继续前等待工厂，因此提供商在交互式启动期间和 pi --list-models 时可用。

覆盖现有提供商

最简单的用例：通过代理重定向现有提供商。

typescript

// 所有 Anthropic 请求现在通过您的代理
pi.registerProvider("anthropic", {
  baseUrl: "https://proxy.example.com"
});

// 为 OpenAI 请求添加自定义标头
pi.registerProvider("openai", {
  headers: {
    "X-Custom-Header": "value"
  }
});

// baseUrl 和标头组合
pi.registerProvider("google", {
  baseUrl: "https://ai-gateway.corp.com/google",
  headers: {
    "X-Corp-Auth": "$CORP_AUTH_TOKEN"  // 环境变量或字面量
  }
});

当仅提供 baseUrl 和/或 headers（无 models）时，该提供商的所有现有模型都将保留新端点。

注册新提供商

要添加全新提供商，需指定 models 和必需配置。

如果模型列表来自远程端点，使用异步扩展工厂：

typescript

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

export default async function (pi: ExtensionAPI) {
  const response = await fetch("http://localhost:1234/v1/models");
  const payload = (await response.json()) as {
    data: Array<{
      id: string;
      name?: string;
      context_window?: number;
      max_tokens?: number;
    }>;
  };

  pi.registerProvider("local-openai", {
    baseUrl: "http://localhost:1234/v1",
    apiKey: "$LOCAL_OPENAI_API_KEY",
    api: "openai-completions",
    models: payload.data.map((model) => ({
      id: model.id,
      name: model.name ?? model.id,
      reasoning: false,
      input: ["text"],
      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
      contextWindow: model.context_window ?? 128000,
      maxTokens: model.max_tokens ?? 4096,
    })),
  });
}

这会在启动完成前注册获取的模型。

typescript

pi.registerProvider("my-llm", {
  baseUrl: "https://api.my-llm.com/v1",
  apiKey: "$MY_LLM_API_KEY",  // 环境变量引用
  api: "openai-completions",  // 使用哪个流式传输 API
  models: [
    {
      id: "my-llm-large",
      name: "My LLM Large",
      reasoning: true,        // 支持扩展思考
      input: ["text", "image"],
      cost: {
        input: 3.0,           // 每百万 token 美元数
        output: 15.0,
        cacheRead: 0.3,
        cacheWrite: 3.75
      },
      contextWindow: 200000,
      maxTokens: 16384
    }
  ]
});

当提供 models 时，它会替换该提供商的所有现有模型。

apiKey 和自定义标头值使用与 models.json 相同的配置语法：以 !command 开头执行整个值，$ENV_VAR 和 ${ENV_VAR} 插值环境变量，$$ 输出字面量 $，$! 输出字面量 !。

注销提供商

使用 pi.unregisterProvider(name) 移除先前通过 pi.registerProvider(name, ...) 注册的提供商：

typescript

// 注册
pi.registerProvider("my-llm", {
  baseUrl: "https://api.my-llm.com/v1",
  apiKey: "$MY_LLM_API_KEY",
  api: "openai-completions",
  models: [
    {
      id: "my-llm-large",
      name: "My LLM Large",
      reasoning: true,
      input: ["text", "image"],
      cost: { input: 3.0, output: 15.0, cacheRead: 0.3, cacheWrite: 3.75 },
      contextWindow: 200000,
      maxTokens: 16384
    }
  ]
});

// 稍后，移除它
pi.unregisterProvider("my-llm");

注销会移除该提供商的动态模型、API 密钥回退、OAuth 提供商注册和自定义流处理器注册。任何被覆盖的内置模型或提供商行为将恢复。

初始扩展加载阶段之后的调用会立即应用，因此无需 /reload。

API 类型

api 字段决定使用哪个流式传输实现：

API	用途
`anthropic-messages`	Anthropic Claude API 及兼容版本
`openai-completions`	OpenAI Chat Completions API 及兼容版本
`openai-responses`	OpenAI Responses API
`azure-openai-responses`	Azure OpenAI Responses API
`openai-codex-responses`	OpenAI Codex Responses API
`mistral-conversations`	Mistral SDK Conversations/Chat 流式传输
`google-generative-ai`	Google Generative AI API
`google-vertex`	Google Vertex AI API
`bedrock-converse-stream`	Amazon Bedrock Converse API

大多数 OpenAI 兼容提供商使用 openai-completions。为特定模型使用模型级别的 thinkingLevelMap，为提供商特性使用 compat。xhigh 和 max 级别需要显式启用，要求非空映射条目，并可能被不支持的空位分隔：

typescript

models: [{
  id: "custom-model",
  // ...
  reasoning: true,
  thinkingLevelMap: {              // 将 Pi 级别映射到提供商值；null 表示不支持
    minimal: null,
    low: null,
    medium: null,
    high: "default",
    xhigh: null,
    max: "max"
  },
  compat: {
    supportsDeveloperRole: false,   // 使用 "system" 而非 "developer"
    supportsReasoningEffort: true,
    maxTokensField: "max_tokens",   // 而非 "max_completion_tokens"
    requiresToolResultName: true,   // 工具结果需要 name 字段
    thinkingFormat: "qwen",        // top-level enable_thinking: true
    cacheControlFormat: "anthropic" // Anthropic 风格的 cache_control 标记
  }
}]

为 OpenRouter 风格的 reasoning: { effort } 控制使用 openrouter。为 Together 风格的 reasoning: { enabled } 控制使用 together；启用 supportsReasoningEffort 时，它还发送 reasoning_effort。为本地 Qwen 兼容服务器（读取 chat_template_kwargs.enable_thinking 且需要 preserve_thinking）使用 qwen-chat-template。

为通过 system_prompt、最后工具定义和最后用户/助手文本内容暴露 Anthropic 风格提示缓存的 OpenAI 兼容提供商，使用 cacheControlFormat: "anthropic"。

对于使用 api: "anthropic-messages" 的 Anthropic 兼容提供商，在需要自适应思考（thinking.type: "adaptive" 加上 output_config.effort）的上游模型上，设置 compat.forceAdaptiveThinking: true。内置自适应 Claude 模型会自动设置此选项。仅当提供商发出空思考签名且期望 signature: "" 重放时，才设置 compat.allowEmptySignature: true。

迁移说明：Mistral 已从 openai-completions 迁移到 mistral-conversations。原生 Mistral 模型使用 mistral-conversations。如果您有意将 Mistral 兼容/自定义端点通过 openai-completions 路由，请显式设置所需的 compat 标志。

Auth Header

如果您的提供商期望 Authorization: Bearer <key> 但使用非标准 API，设置 authHeader: true：

typescript

pi.registerProvider("custom-api", {
  baseUrl: "https://api.example.com",
  apiKey: "$MY_API_KEY",
  authHeader: true,  // 添加 Authorization: Bearer 标头
  api: "openai-completions",
  models: [...]
});

密钥对每个请求进行解析。显式的请求 Authorization 标头优先于生成的值。

OAuth 支持

添加与 /login 集成的 OAuth/SSO 认证：

typescript

import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";

pi.registerProvider("corporate-ai", {
  baseUrl: "https://ai.corp.com/v1",
  api: "openai-responses",
  models: [...],
  oauth: {
    name: "Corporate AI (SSO)",

    async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
      const method = await callbacks.onSelect({
        message: "选择登录方式：",
        options: [
          { id: "browser", label: "浏览器 OAuth" },
          { id: "device", label: "设备码" }
        ]
      });
      if (!method) throw new Error("登录已取消");

      let code: string;
      if (method === "device") {
        callbacks.onDeviceCode({
          userCode: "ABCD-1234",
          verificationUri: "https://sso.corp.com/device",
          intervalSeconds: 5,
          expiresInSeconds: 900
        });
        code = await pollDeviceCodeUntilComplete();
      } else {
        callbacks.onAuth({ url: "https://sso.corp.com/authorize?..." });
        code = await callbacks.onPrompt({ message: "输入 SSO 代码：" });
      }

      // 换取令牌（您的实现）
      const tokens = await exchangeCodeForTokens(code);

      return {
        refresh: tokens.refreshToken,
        access: tokens.accessToken,
        expires: Date.now() + tokens.expiresIn * 1000
      };
    },

    async refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
      const tokens = await refreshAccessToken(credentials.refresh);
      return {
        refresh: tokens.refreshToken ?? credentials.refresh,
        access: tokens.accessToken,
        expires: Date.now() + tokens.expiresIn * 1000
      };
    },

    getApiKey(credentials: OAuthCredentials): string {
      return credentials.access;
    }
  }
});

注册后，用户可通过 /login corporate-ai 进行认证。

OAuthLoginCallbacks

callbacks 对象提供提供商自有流程的中立 UI 交互：

typescript

interface OAuthLoginCallbacks {
  // 在浏览器中打开 URL（用于 OAuth 重定向）
  onAuth(params: { url: string }): void;

  // 显示设备码（用于设备授权流程）
  onDeviceCode(params: {
    userCode: string;
    verificationUri: string;
    intervalSeconds?: number;
    expiresInSeconds?: number;
  }): void;

  // 显示瞬态进度
  onProgress?(message: string): void;

  // 提示用户输入（用于手动令牌输入）
  onPrompt(params: { message: string }): Promise<string>;

  // 显示交互式选择器，例如选择浏览器 OAuth 还是设备码
  onSelect(params: {
    message: string;
    options: { id: string; label: string }[];
  }): Promise<string | undefined>;
}

OAuthCredentials

凭证持久化在 ~/.pi/agent/auth.json：

typescript

interface OAuthCredentials {
  refresh: string;   // 刷新令牌（用于 refreshToken()）
  access: string;    // 访问令牌（getApiKey() 返回）
  expires: number;   // 毫秒级过期时间戳
}

自定义流式传输 API

对于非标准 API 的提供商，实现 streamSimple。在编写自己的之前，先研究现有提供商实现：

参考实现：

anthropic.ts - Anthropic Messages API
mistral.ts - Mistral Conversations API
openai-completions.ts - OpenAI Chat Completions
openai-responses.ts - OpenAI Responses API
google.ts - Google Generative AI
amazon-bedrock.ts - AWS Bedrock

流模式

所有提供商遵循相同模式：

typescript

import {
  type AssistantMessage,
  type AssistantMessageEventStream,
  type Context,
  type Model,
  type SimpleStreamOptions,
  calculateCost,
  createAssistantMessageEventStream,
} from "@earendil-works/pi-ai";

function streamMyProvider(
  model: Model<any>,
  context: Context,
  options?: SimpleStreamOptions
): AssistantMessageEventStream {
  const stream = createAssistantMessageEventStream();

  (async () => {
    // 初始化输出消息
    const output: AssistantMessage = {
      role: "assistant",
      content: [],
      api: model.api,
      provider: model.provider,
      model: model.id,
      usage: {
        input: 0,
        output: 0,
        cacheRead: 0,
        cacheWrite: 0,
        totalTokens: 0,
        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
      },
      stopReason: "stop",
      timestamp: Date.now(),
    };

    try {
      // 推送开始事件
      stream.push({ type: "start", partial: output });

      // 发出 API 请求并处理响应...
      // 收到内容时推送事件...

      // 推送完成事件
      stream.push({
        type: "done",
        reason: output.stopReason as "stop" | "length" | "toolUse",
        message: output
      });
      stream.end();
    } catch (error) {
      output.stopReason = options?.signal?.aborted ? "aborted" : "error";
      output.errorMessage = error instanceof Error ? error.message : String(error);
      stream.push({ type: "error", reason: output.stopReason, error: output });
      stream.end();
    }
  })();

  return stream;
}

事件类型

按以下顺序通过 stream.push() 推送事件：

{ type: "start", partial: output } - 流已开始
内容事件（可重复，跟踪每个块的 contentIndex）：
- { type: "text_start", contentIndex, partial } - 文本块开始
- { type: "text_delta", contentIndex, delta, partial } - 文本块
- { type: "text_end", contentIndex, content, partial } - 文本块结束
- { type: "thinking_start", contentIndex, partial } - 思考开始
- { type: "thinking_delta", contentIndex, delta, partial } - 思考块
- { type: "thinking_end", contentIndex, content, partial } - 思考结束
- { type: "toolcall_start", contentIndex, partial } - 工具调用开始
- { type: "toolcall_delta", contentIndex, delta, partial } - 工具调用 JSON 块
- { type: "toolcall_end", contentIndex, toolCall, partial } - 工具调用结束
{ type: "done", reason, message } 或 { type: "error", reason, error } - 流已结束

每个事件中的 partial 字段包含当前的 AssistantMessage 状态。收到数据时更新 output.content，然后将 output 包含为 partial。

内容块

收到时向 output.content 添加内容块：

typescript

// 文本块
output.content.push({ type: "text", text: "" });
stream.push({ type: "text_start", contentIndex: output.content.length - 1, partial: output });

// 当文本到达时
const block = output.content[contentIndex];
if (block.type === "text") {
  block.text += delta;
  stream.push({ type: "text_delta", contentIndex, delta, partial: output });
}

// 当块完成时
stream.push({ type: "text_end", contentIndex, content: block.text, partial: output });

工具调用

工具调用需要累积 JSON 并解析：

typescript

// 开始工具调用
output.content.push({
  type: "toolCall",
  id: toolCallId,
  name: toolName,
  arguments: {}
});
stream.push({ type: "toolcall_start", contentIndex: output.content.length - 1, partial: output });

// 累积 JSON
let partialJson = "";
partialJson += jsonDelta;
try {
  block.arguments = JSON.parse(partialJson);
} catch {}
stream.push({ type: "toolcall_delta", contentIndex, delta: jsonDelta, partial: output });

// 完成
stream.push({
  type: "toolcall_end",
  contentIndex,
  toolCall: { type: "toolCall", id, name, arguments: block.arguments },
  partial: output
});

使用量和成本

从 API 响应更新使用量并计算成本：

typescript

output.usage.input = response.usage.input_tokens;
output.usage.output = response.usage.output_tokens;
output.usage.cacheRead = response.usage.cache_read_tokens ?? 0;
output.usage.cacheWrite = response.usage.cache_write_tokens ?? 0;
output.usage.totalTokens = output.usage.input + output.usage.output +
                           output.usage.cacheRead + output.usage.cacheWrite;
calculateCost(model, output.usage);

上下文溢出错误

当请求超过模型上下文窗口时，Pi 可通过压缩对话并自动重试来恢复。仅当 Pi 将失败识别为溢出时才触发此恢复。

检测在最终助手消息上运行：

stopReason === "error"
errorMessage 匹配 Pi 已知的溢出模式之一（参见 packages/ai/src/utils/overflow.ts）

如果您的提供商返回 Pi 无法识别的溢出错误，请在注册提供商的同一扩展中规范化错误。使用 message_end 处理器重写助手消息，使其 errorMessage 以 Pi 识别的短语开头。通用后备 context_length_exceeded 是最安全的选择。

typescript

const MY_PROVIDER_OVERFLOW_PATTERN = /your provider's overflow phrase/i;

export default function (pi: ExtensionAPI) {
  pi.registerProvider("my-provider", { /* ... */ });

  pi.on("message_end", (event, ctx) => {
    const message = event.message;
    if (message.role !== "assistant") return;
    if (message.stopReason !== "error") return;
    if (
      message.provider !== "my-provider" &&
      ctx.model?.provider !== "my-provider"
    )
      return;

    const errorMessage = message.errorMessage ?? "";
    if (errorMessage.includes("context_length_exceeded")) return;
    if (!MY_PROVIDER_OVERFLOW_PATTERN.test(errorMessage)) return;

    return {
      message: {
        ...message,
        errorMessage: `context_length_exceeded: ${errorMessage}`,
      },
    };
  });
}

message_end 在 Pi 跟踪助手消息进行自动压缩之前运行，因此重写的 errorMessage 是 Pi 检查的内容。有了这个设置，Pi 将：

从 errorMessage 检测到溢出。
从活动上下文中删除失败的助手消息。
运行压缩。
重试一次请求。

仔细保护重写：

限制在其提供商内（message.provider 和 ctx.model?.provider），以便不影响其他提供商的无关错误。
匹配提供商特定模式，而非 Pi 的通用溢出模式。重写速率限制或节流错误（rate limit、too many requests）会错误地触发压缩，而不是 Pi 的正常带退避重试路径。
当 errorMessage 已包含 context_length_exceeded 时跳过，使处理器幂等。

注册

注册流函数：

typescript

pi.registerProvider("my-provider", {
  baseUrl: "https://api.example.com",
  apiKey: "$MY_API_KEY",
  api: "my-custom-api",
  models: [...],
  streamSimple: streamMyProvider
});

测试您的实现

使用与内置提供商相同的测试套件测试您的提供商。从 packages/ai/test/ 复制并调整这些测试文件：

测试	目的
`stream.test.ts`	基本流式传输、文本输出
`tokens.test.ts`	Token 计数和使用量
`abort.test.ts`	AbortSignal 处理
`empty.test.ts`	空/最小响应
`context-overflow.test.ts`	上下文窗口限制
`image-limits.test.ts`	图像输入处理
`unicode-surrogate.test.ts`	Unicode 边缘情况
`tool-call-without-result.test.ts`	工具调用边缘情况
`image-tool-result.test.ts`	工具结果中的图像
`total-tokens.test.ts`	总 Token 计算
`cross-provider-handoff.test.ts`	提供商间上下文传递

使用您的提供商/模型对运行测试以验证兼容性。

配置参考

typescript

interface ProviderConfig {
  /** 在 UI（如 /login）中显示提供商的名称。 */
  name?: string;

  /** API 端点 URL。定义模型时必需。 */
  baseUrl?: string;

  /** API 密钥字面量、环境变量插值（$ENV_VAR 或 ${ENV_VAR}）或 !command。定义模型时必需（除非使用 oauth）。 */
  apiKey?: string;

  /** 流式传输的 API 类型。定义模型时在提供商或模型级别必需。 */
  api?: Api;

  /** 非标准 API 的自定义流式传输实现。 */
  streamSimple?: (
    model: Model<Api>,
    context: Context,
    options?: SimpleStreamOptions
  ) => AssistantMessageEventStream;

  /** 包含在请求中的自定义标头。值使用与 apiKey 相同的解析语法。 */
  headers?: Record<string, string>;

  /** 如果为 true，添加带有解析 API 密钥的 Authorization: Bearer 标头。 */
  authHeader?: boolean;

  /** 要注册的模型。如果提供，将替换该提供商的所有现有模型。 */
  models?: ProviderModelConfig[];

  /** 为 /login 支持的 OAuth 提供商。 */
  oauth?: {
    name: string;
    login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
    refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials>;
    getApiKey(credentials: OAuthCredentials): string;
  };
}

模型定义参考

typescript

interface ProviderModelConfig {
  /** 模型 ID（如 "claude-sonnet-4-20250514"）。 */
  id: string;

  /** 显示名称（如 "Claude 4 Sonnet"）。 */
  name: string;

  /** 此特定模型的 API 类型覆盖。 */
  api?: Api;

  /** 此特定模型的 API 端点 URL 覆盖。 */
  baseUrl?: string;

  /** 模型是否支持扩展思考。 */
  reasoning: boolean;

  /** 将 Pi 思考级别映射到提供商/模型特定值；null 标记不支持的级别。 */
  thinkingLevelMap?: Partial<Record<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", string | null>>;

  /** 支持输入类型。 */
  input: ("text" | "image")[];

  /** 每百万 token 的成本（用于使用量跟踪）。 */
  cost: {
    input: number;
    output: number;
    cacheRead: number;
    cacheWrite: number;
  };

  /** 最大上下文窗口大小（token 数）。 */
  contextWindow: number;

  /** 最大输出 token 数。 */
  maxTokens: number;

  /** 此特定模型的自定义标头。 */
  headers?: Record<string, string>;

  /** 所选 API 的兼容性设置。 */
  compat?: {
    // openai-completions
    supportsStore?: boolean;
    supportsDeveloperRole?: boolean;
    supportsReasoningEffort?: boolean;
    supportsUsageInStreaming?: boolean;
    maxTokensField?: "max_completion_tokens" | "max_tokens";
    requiresToolResultName?: boolean;
    requiresAssistantAfterToolResult?: boolean;
    requiresThinkingAsText?: boolean;
    requiresReasoningContentOnAssistantMessages?: boolean;
    thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling";
    chatTemplateKwargs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort"; omitWhenOff?: boolean }>;
    cacheControlFormat?: "anthropic";
    sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
    sendSessionAffinityHeaders?: boolean;

    // anthropic-messages
    supportsEagerToolInputStreaming?: boolean;
    supportsLongCacheRetention?: boolean;
    sendSessionAffinityHeaders?: boolean;
    supportsCacheControlOnTools?: boolean;
    forceAdaptiveThinking?: boolean;
    allowEmptySignature?: boolean;
  };
}

openrouter 发送 reasoning: { effort }。deepseek 发送 thinking: { type: "enabled" | "disabled" }，启用时还发送 reasoning_effort。together 发送 reasoning: { enabled }，在启用 supportsReasoningEffort 时还发送 reasoning_effort。qwen 用于 DashScope 风格的顶层 enable_thinking。使用 qwen-chat-template 用于本地 Qwen 兼容服务器（读取 chat_template_kwargs.enable_thinking 且需要 preserve_thinking）。使用 chat-template 用于可配置的 chat_template_kwargs，例如 DeepSeek V3.x 背后 vLLM，chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }。 cacheControlFormat: "anthropic" 对系统提示、最后工具定义和最后用户/助手文本内容应用 Anthropic 风格的 cache_control 标记。

自定义提供商 ​

示例扩展 ​

目录 ​

快速参考 ​

覆盖现有提供商 ​

注册新提供商 ​

注销提供商 ​

API 类型 ​

Auth Header ​

OAuth 支持 ​

OAuthLoginCallbacks ​

OAuthCredentials ​

自定义流式传输 API ​

流模式 ​

事件类型 ​

内容块 ​

工具调用 ​

使用量和成本 ​

上下文溢出错误 ​

注册 ​

测试您的实现 ​

配置参考 ​

模型定义参考 ​

自定义提供商

示例扩展

目录

快速参考

覆盖现有提供商

注册新提供商

注销提供商

API 类型

Auth Header

OAuth 支持

OAuthLoginCallbacks

OAuthCredentials

自定义流式传输 API

流模式

事件类型

内容块

工具调用

使用量和成本

上下文溢出错误

注册

测试您的实现

配置参考

模型定义参考