# @aliou/pi-synthetic 中文文档

规范地址：https://npmcn.com/package/%40aliou/pi-synthetic/

版本：0\.31\.1
npm 元数据更新时间：2026-11-05T15:16:09.246Z
中文译文更新时间：2026-11-06T19:51:31.305Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aliou/pi-synthetic
原文对照：https://npmcn.com/package/%40aliou/pi-synthetic/?lang=original
项目主页：https://github.com/aliou/pi-synthetic#readme
源码仓库：https://github.com/aliou/pi-synthetic

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：237 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：typebox \*，@earendil-works/chord 1\.5\.0，@earendil-works/pi-ai 1\.5\.0，@earendil-works/pi-tui \>=1\.0\.0，@earendil-works/pi-durable 1\.5\.0，@earendil-works/pi-coding-agent \>=1\.5\.0
- 首次发布：2026-01-29T14:48:03.590Z
- 最新版本发布：2026-11-05T15:16:08.929Z
- 近 30 天下载量：2428（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：80（近 12 个月 80 个）

## 中文简介

![banner](https://assets.aliou.me/github/aliou/pi-synthetic/banner.png)

## 安装

```sh
npm install @aliou/pi-synthetic
```

也可以使用：`pnpm add @aliou/pi-synthetic`、`yarn add @aliou/pi-synthetic`、`bun add @aliou/pi-synthetic`

## README

![banner](https://assets.aliou.me/github/aliou/pi-synthetic/banner.png)

# Pi 合成扩展

添加的 Pi 扩展 [合成](https://gnldxt.link/ref-syn) 作为模型提供商,通过Synthetic的OpenAI兼容API,给你开源模型的访问权限.

## 安装

### 获取 API 密钥

报名 [这里](https://gnldxt.link/ref-syn) 要获取 API 密钥(参考链接).

### 配置证书

扩展使用Pi的证书存储. 将您的 API 密钥添加到 `~/.pi/agent/auth.json` (建议):

```json
{
  "synthetic": { "type": "api_key", "key": "your-api-key-here" }
}
```

或设置环境变量 :

```bash
export SYNTHETIC_API_KEY="your-api-key-here"
```

全权证书按下列顺序解决:

1.  国 际 `--api-key` 旗帜
2.  `auth.json` 条目 `synthetic`
3.  环境变量 `SYNTHETIC_API_KEY`

### 安装扩展

```bash
# From npm
pi install npm:@aliou/pi-synthetic

# From git
pi install git:github.com/aliou/pi-synthetic

# Local development
pi -e .
```

## 使用量

安装后, 选择 `synthetic` 作为您的提供者,并从可用的模型中选择:

```
/model synthetic hf:moonshotai/Kimi-K3
```

### 模型

模型出自Synthetic的模型API并被缓存了四个小时. 内置列表覆盖下线开始,并携带每个模型的推理和相容性覆盖API不曝光.

合成者分类的ID(`syn:large:text`, (中文(简体) ), `syn:small:text`, (中文(简体) ), `syn:large:vision`, (中文(简体) ), `syn:small:vision`) 总是通向目前该类最佳模型的路径,因此它们在模型自转而不重组的情况下存活.

### 网络搜索工具

延期登记册 `synthetic_web_search` ——零数据保留网页搜索工具. 在会话开始时,它会检查背景中的合成配额 API,即使选择了另一个提供者. 该工具只有在确认合成订阅后才能使用;它仍然被隐藏在现收现付账户、缺失的证书和配额API故障中.

### 提示缓存

合成缓存会提示每个推论节点的前缀. Pi 读取缓存点击 `prompt_tokens_details.cached_tokens` 字段并按缓存读取速率给它们定价 Synthetic的API报告. 在会话内重复使用是可靠的案例;跨会话重复使用得不到保证.

### 理由级别

接受的推理努力因模式而异。 所建的每款模型绘图将皮氏水平取取取器限制在了每个已知模型所接受的水平. 有些模型不能关闭推理;有些接受 `max`。 。 。 .

### 提供方 API

合成器为每个聊天模式服务两次: OpenAI 兼容器 `POST /openai/v1` 端点和与人类兼容 `POST /anthropic/v1/messages` 终点 完整目录`hf:` 模型和 `syn:` 等同别名)在两个表面都是有效的;配额,定价,以及网页搜索工具都是表面不可知的.

选择表面 `/synthetic:settings` 下级 **提供者 > API** (默认) `openai-completions`) (中文(简体) ). 更改在 `/reload`。 。 。 .

Anthropic地表溪流 真正的思考块, 使用本地 `tool_use`编号 :`tool_result`,则报告缓存直接读取和写出。 它的推理控制只是上或下:工作水平没有分级,以及 `syn:large:text` 财务报告和审定财务报表 `hf:zai-org/GLM-5.3-Flash` 不能关闭推理。 OpenAI地表保持了模型支持它的地方的分级努力.

### 配额命令

检查您的 API 使用情况 :

```
/synthetic:quotas
```

### 用户 API 代理

网页搜索和配额可以使用代理,而不是 `https://api.synthetic.new`。配置它与 `/synthetic:settings` 下级 **连接 > 用户 API 代理**。代理仅用于 `/v2/search` 财务报告和审定财务报表 `/v2/quotas`;模型提供者呼叫仍然直接使用Synthetic的OpenAI相容端点.

如果代理需要认证, pi- synthetic 仍然需要合成 API 密钥并发送 `Authorization: Bearer ...`。如果代理服务器不需要认证,则禁用 **需要认证** 和这些工具调用跳过 API 密钥检查并省略 `Authorization`。 。 。 .

### 使用状况

当一个合成模型活动时,脚步状态栏会显示活配额用法(例如. `week:82% (↺in 3d) 5h:95%`) (中文(简体) ). 颜色遵循与配额警告相同的严重性评估:默认情况下为绿色,仅在预计使用有风险时为黄色/红色. 状态自动更新每60秒一次,每转后一次.

### 配额警告

当您接近或超过合成API配额时,扩展自动通知您。 对严重性过渡和升级情况发出通知,而不是重复提醒同一级别。 收回的配额如果后来变得危险,可以再次通知.

每周的信用和5小时的要求窗口都来自最近的使用,因此短暂的爆发不会引发每周的警告. 没有足够的历史, 警告则使用当前使用 。 就预测而言,延长配额的历史最长为14天(5个米B) `$XDG_STATE_HOME/pi-synthetic/quota-history` 或者皮的代理状态目录。 当配额警告被禁用时, 没有存储 .

## 库使用

提供商也可以使用,没有皮作为 `@aliou/pi-synthetic/provider`。默认导出将构建 pi-ai `Provider`数字 :

```ts
import { createModels } from "@earendil-works/pi-ai";
import createSyntheticProvider from "@aliou/pi-synthetic/provider";

const models = createModels({ credentials, modelsStore });
models.setProvider(createSyntheticProvider({ api: "openai-completions" }));
await models.refresh();
```

基线目录总是列出. 在线刷新从合成中获取实时目录; `refresh({ allowNetwork: false })` 恢复主机存储目录 。 提供者在无证书的情况下保持可刷新:存储的密钥和 `SYNTHETIC_API_KEY` 首先,然后匿名访问公共目录.

耐用扩展可用,不包含 Pi `@aliou/pi-synthetic/durable`。默认导出将构建一个可持久 `Extension`数字 :

```ts
import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
import { createRegistry, Harness, MemoryStorage } from "@earendil-works/pi-durable";
import createSyntheticExtension from "@aliou/pi-synthetic/durable";

const registry = createRegistry();
registry.install(createSyntheticExtension());
```

耐用扩展舰只 `synthetic_web_search` 工具,带有固定的 `synthetic_` 前缀存储的对话依赖。 它没有读取设置: API 密钥来自主机 `Models` (单位:千美元)`getAuth("synthetic")`)或为: `apiKey` 选项,而工具 API 代理来自 `proxyUrl`编号 :`proxyRequiresAuth` 选项。 短结果在存在时通过主机的执行环境来保存;没有一个,则结果保持短线内行. 崩溃安全后再运行:工具是只读查询.

## 残疾特征

每个功能(提供者,网络搜索,配额命令,使用状态,配额警告)都是单独的Pi扩展. 通过 `pi config` TUI 或编辑 `~/.pi/agent/settings.json`。 。 。 .

运行 `pi config` 打开资源选择器并取消选择要禁用的扩展名。 按 Tab 在全局和项目本地范围之间切换.

直接在 `~/.pi/agent/settings.json`,列出您想要的扩展名 `+` (可执行)和 `-` 相对于软件包根的路径上(无法)前缀. 例如,在停止使用状态和配额警告的同时,保持其余活动:

```json
{
  "packages": [
    {
      "source": "npm:@aliou/pi-synthetic",
      "extensions": [
        "+extensions/command-quotas/index.ts",
        "-extensions/usage-status/index.ts",
        "-extensions/quota-warnings/index.ts",
        "+extensions/web-search/index.ts",
        "+extensions/provider/index.ts"
      ]
    }
  ]
}
```

扩展路径映射到下面的文件 `extensions/` 在此还原中: `provider`, (中文(简体) ), `web-search`, (中文(简体) ), `command-quotas`, (中文(简体) ), `usage-status`,以及 `quota-warnings`。 。 。 .

这个 **用户 API 代理** 设置不是一个可加载扩展功能。 这是一个正常的设置 控制通过 `/synthetic:settings`。 。 。 .

## 发展

```bash
git clone https://github.com/aliou/pi-synthetic.git
cd pi-synthetic
nix develop       # Node.js, pnpm 11, and pre-commit hooks
pnpm install
pnpm run typecheck
pnpm run lint
pnpm run test
pi -e .            # run Pi with the local checkout
```

Nix dev shell为Biome安装了预承诺钩,冷锁文件检查和打字检查. 内建模式条目 `extensions/provider/models.ts`· ; `AGENTS.md` 解释它们如何与API目录结合.

释放使用情况 [更改](https://github.com/changesets/changesets)在CI通过之后 `main`,出版工作流程打开一个发布PR;将其合并在npm上分级包进行手动推广.

## 所需资源

-   Pi 编码代理 v1. 0.0+( 需要 `ProviderConfig.refreshModels` 动态模型发现)
-   合成 API 密钥( 配置于 `~/.pi/agent/auth.json` 或经由 `SYNTHETIC_API_KEY`)用于模式提供者呼叫和认证的通用API呼叫

## 链接

-   [合成](https://gnldxt.link/ref-syn)
-   [合成模型](https://gnldxt.link/ref-syn)
-   [合成 API 文件](https://dev.synthetic.new/docs/api/overview)
-   [Pi 文档](https://buildwithpi.ai/)

## 常见问题

### 如何安装 @aliou/pi-synthetic？

在项目目录运行 npm install @aliou/pi-synthetic，或使用 pnpm add / yarn add / bun add。

### @aliou/pi-synthetic 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aliou/pi-synthetic 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aliou/pi-synthetic 可以商用吗？

@aliou/pi-synthetic 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aliou/pi-synthetic 的下载量有多少？

根据 npm 官方下载统计，@aliou/pi-synthetic 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,428 次，日均约 81 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aliou/pi-synthetic 还在维护吗？

最新版本 0\.31\.1 发布于 2026/11/05（2 天前）；至今共发布 80 个版本，其中过去 12 个月发布了 80 个；首次发布于 2026/01/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。