# @aliou/pi-ts-aperture 中文文档 规范地址：https://npmcn.com/package/%40aliou/pi-ts-aperture/ 版本：0\.20\.2 npm 元数据更新时间：2026-11-07T14:22:15.155Z 中文译文更新时间：2026-11-07T02:12:34.445Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40aliou/pi-ts-aperture 原文对照：https://npmcn.com/package/%40aliou/pi-ts-aperture/?lang=original 项目主页：https://github.com/aliou/pi-ts-aperture#readme 源码仓库：https://github.com/aliou/pi-ts-aperture ## 关键信息（来自 npm 元数据） - 包体积（解压后）：311 kB，59 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：@earendil-works/pi-ai \>=1\.5\.0，@earendil-works/pi-tui \>=1\.5\.0，@earendil-works/pi-coding-agent \>=1\.5\.0 - 首次发布：2026-02-17T17:16:57.971Z - 最新版本发布：2026-11-07T14:22:14.920Z - 近 30 天下载量：2075（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：55（近 12 个月 55 个） ## 中文简介 途径 Pi LLM 提供方通过 tailscale 孔径 ## 安装 ```sh npm install @aliou/pi-ts-aperture ``` 也可以使用：`pnpm add @aliou/pi-ts-aperture`、`yarn add @aliou/pi-ts-aperture`、`bun add @aliou/pi-ts-aperture` ## README ![banner](https://assets.aliou.me/github/aliou/pi-ts-aperture/banner.png) # 针孔 通过 Pi LLM 提供者和 MCP 工具 [尾端孔径](https://tailscale.com/docs/features/aperture)在你的尾网有一个管理好的AI网关. Aperture hands API密钥注入并请求路由服务器侧,因此Pi从来不需要上游供应商的认证. 这一扩展提供了三种能力: - **专门** (默认):一个独立的 `aperture` 提供商的模型来自网关. - **代理服务器**:通过Aperture将现有的Pi供应商(人类,Openai,Openai-codex,.)改道. - **MCP工具**: 在 Pi 本地的 MCP 支持下, 注册网关的 MCP 服务器, 将其上浮为 `mcp__aperture__*`。 。 。 . ## 安装 ```bash pi install npm:@aliou/pi-ts-aperture ``` ## 首发 安装后, 运行登入向导 : ``` /aperture:onboarding ``` [![Onboarding walkthrough](https://assets.aliou.me/pi-extensions/demos/aperture/v0.8.0/onboarding.gif)](https://assets.aliou.me/pi-extensions/demos/aperture/v0.8.0/onboarding.mp4) 向导请求您的 Aperture URL( 带有健康检查) , 让您选择能力、 提供者, 以及是否注册网关的 MCP 工具( 默认关闭), 然后保存并重新加载 Pi 。 您可以稍后更改所有 `/aperture:settings`。 。 。 . ## 能力 ### 专职提供者(违约) [![Dedicated provider walkthrough](https://assets.aliou.me/pi-extensions/demos/aperture/v0.8.0/dedicated-provider.gif)](https://assets.aliou.me/pi-extensions/demos/aperture/v0.8.0/dedicated-provider.mp4) 独立注册 `aperture` 提供者列出您网关所曝光的模型 。 包含所有网关提供者或过滤器到特定的网关提供者,每个模型都会通过符合其Aperture相容性的Pi API进行路由. 能力(视觉输入,推理,思维水平)来自了解模型的第一个来源: `~/.pi/agent/models.json`,然后Pi的模型注册,然后 [模式.dev](https://models.dev/),然后安全默认值。 成本,上下文窗口,以及输出限制都来自它报告它们的网关,因为他们描述的是路由Pi呼叫,而再发售器可以将一个模型封顶在它的本土容量以下. 解析的目录被缓存到Pi的模型商店,因此模型在启动时即时加载,甚至下线. ### 现有代理供应商 [![Proxy providers walkthrough](https://assets.aliou.me/pi-extensions/demos/aperture/v0.8.0/proxy-providers.gif)](https://assets.aliou.me/pi-extensions/demos/aperture/v0.8.0/proxy-providers.mp4) 通过 Aperture 重排已有的 Pi 提供者 。 每个提供商保留自己的模型定义和设置,会话恢复在同一模型上. Aperture注入服务器侧面的证书,或者转发了Pi本人对过关供应商的证书. OpenAI 响应通路支持 Pi **用 ChatGPT 签名**。 。 。 . 在代理标签中选择提供者 `/aperture:settings`。本地供应商可以瞄准不同的网关标识(例如, `anthropic` → `anthropic-oauth`),多个本地供应商可以共享一个网关目标. 可选的每个提供者核查在网关上缺失本地模型时发出警告; `keepGatewayModelsOnly: true` 把它们藏在取型机那里. ### MCP工具 [![MCP walkthrough](https://assets.aliou.me/pi-extensions/demos/aperture/v0.8.0/connectors.gif)](https://assets.aliou.me/pi-extensions/demos/aperture/v0.8.0/connectors.mp4) 光圈可以曝光 MCP 工具(GitHub,你自己的内部工具,.) at `/v1/mcp`当启用时,此扩展记录了以 Pi 内置的 MCP 支持的终点作为 `aperture` 服务器 `deferred` 暴露:工具表面为 `mcp__aperture__*` 离开系统,直到Pi `tool_search` 把它们装上. 启用 MCP 工具 `/aperture:settings`; 更改立即适用,不需要重新装入。 管理连接 `/mcp`。在标出工具(总是向模型申报)或隐藏工具时,添加一个同名条目 `~/.pi/agent/mcp.json` - 文件条目优先于扩展注册: ```json { "mcpServers": { "aperture": { "url": "http://ai.pango-lin.ts.net/v1/mcp", "exposure": "deferred", "toolExposure": { "github_list_repos": "direct", "github_delete_*": "hidden" } } } } ``` `toolExposure` 键是工具名或 `*` 模式; 值为 `direct` (单位:千美元), `hidden` (压力), `deferred` (工具 搜索发现,服务器默认),或 `codemode` (只写字). 见Pi的 [工具曝光文件](https://pi.dev/docs/latest/mcp#control-tool-exposure)。 。 。 . ## 图标 | 命令 | 说明 | | --- | --- | | `/aperture:onboarding` | 上座法师. 只能启用登入时可用 . | | `/aperture:settings` | 编辑连接、能力和提供者. | | `/aperture:proxy` | 快捷键 `/aperture:settings` 在代理标签. | | `/aperture:dedicated` | 快捷键 `/aperture:settings` 在专用的标签. | | `/aperture:mcp` | 快捷键 `/aperture:settings` 在MCP标签上. | ## 配置 配置全局保存到 `~/.pi/agent/extensions/aperture.json`。设置 UI 覆盖了一切,但您也可以直接编辑文件。 这个 `APERTURE_BASE_URL` 设置时,环境变量将覆盖配置 `baseUrl` (没有写回配置文件): ```json { "baseUrl": "http://ai.pango-lin.ts.net", "proxy": { "enabled": true, "upstreamProviders": [ { "id": "anthropic", "gatewayId": "anthropic-oauth", "shouldCheckGatewayModels": true } ] }, "dedicated": { "enabled": true, "providers": [ { "id": "anthropic", "name": "Anthropic", "enabled": true }, { "id": "openrouter", "name": "OpenRouter", "enabled": true, "api": "anthropic-messages" }, { "id": "google", "name": "Google", "enabled": false } ] }, "mcp": { "enabled": false } } ``` 注释: - `proxy.upstreamProviders[].id` 本地的Pi供应商; `gatewayId` 是目标网关提供者,需要。 现有配置收益 `gatewayId: id` 移民期间。 未知的网关目标会留下一条警告的路由. `aperture` 被保留,无法选择为配对目标. - 需要客户端认证的网关提供者转发本地提供者的证书(包括Pi OAuth);其他提供者使用服务器侧证书注射. - `keepGatewayModelsOnly` (按代理提供者计算,默认) `false`隐藏网关不服务的供应商本地模型,而不是在请求时让他们失败. - `api` (每个提供者,默认情况下未设置)迫使特定的 Pi API(`openai-completions`, (中文(简体) ), `anthropic-messages`, (中文(简体) ), `openai-responses`, (中文(简体) ), `google-generative-ai`, (中文(简体) ), `google-vertex`, (中文(简体) ), `bedrock-converse-stream`)而不是从网关的相容图中取出的一个. Aperture通过一个以上的API服务提供商使用. 如果网关停止服务于超接,提供商会倒回自动并带有警告. - 一个空的 `dedicated.providers` 列表表示包含所有网关提供者。 通道提供者被排除在外:专用提供者从不转发客户端证书. - 模拟仅服务于系统一端点的网关(`/v1/systemone`)出现在 `aperture` 提供者作为分类器,可通过 `models.classify`,而不是作为聊天模式。 每个模型配置它们 `model_compatibility` 在孔径配置. - 模型元数据属于 `~/.pi/agent/models.json`,不在扩展配置中. - 请求包括: `Referer` 财务报告和审定财务报表 `x-session-id` (目前的Pi会话)所以Aperture仪表板可以将它们分组. 把它们关掉 `"shouldSendProvenanceHeaders": false` 或证据头 切换。 当 Pi 遥测功能被禁用时也会跳过(`PI_TELEMETRY=0` 或者说 `enableInstallTelemetry: false`) (中文(简体) ). - 不存储 API 密钥: Aperture 注入上游证书服务器侧. 在获得Pi OAuth证书时仍然优先. ## 图书馆的使用 套件还装有独立的供Pi外用提供商,没有编码代理或任何配置文件. 它造就了同样的 `aperture` 提供扩展注册:模式目录从网关取出,每个模式通过匹配其Aperture相容性的pi-ai API进行路由,网关注入证书服务器侧(提供商自己的API密钥为占位符). ```bash pnpm add @aliou/pi-ts-aperture @earendil-works/pi-ai ``` ```ts import { createModels } from "@earendil-works/pi-ai/models"; import createApertureProvider from "@aliou/pi-ts-aperture/provider"; const models = createModels(); models.setProvider( createApertureProvider({ baseUrl: "https://ai..ts.net", provenance: { referer: "https://yourapp.example" }, }), ); await models.refresh(); ``` 网关 `baseUrl` 需要并且必须设定。 校验信头( I)`Referer` 加上每个请求 `x-session-id`默认为 ;通过 `provenance: { enabled: false }` 把他们丢掉 刷新是Pi -ai的驱动 `Models.refresh()` 页:1 `provider.refreshModels(context)` 带有 `ModelsStore`)),因此目录持续存在并经由主店恢复. 过 `registryModels` 合并主机侧模型目录:网关模型继承元数据(名称、推理、视觉输入、思维水平、上下文窗口, `compat`)和来自匹配条目的原生上游基站URL,同样的方式扩展合并了Pi的注册. 没有它,元数据来自模型. 安全隐患 过 `providers` 仅包括选定的网关提供者,并设置每个提供者的 api 覆盖; 将其留出以自动 api 选择方式运行每个可调用提供者. ## 所需资源 - Aperture 配置的尾网尾图 . - 运行 Pi 的设备必须能够到达您的 Aperture 端点 . - 使用匹配您的部署的 URL/ 方案( S)`http://` 或者说 `https://`) (中文(简体) ). ## 常见问题 ### @aliou/pi-ts-aperture 是什么？ 途径 Pi LLM 提供方通过 tailscale 孔径 ### 如何安装 @aliou/pi-ts-aperture？ 在项目目录运行 npm install @aliou/pi-ts-aperture，或使用 pnpm add / yarn add / bun add。 ### @aliou/pi-ts-aperture 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @aliou/pi-ts-aperture 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @aliou/pi-ts-aperture 可以商用吗？ @aliou/pi-ts-aperture 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @aliou/pi-ts-aperture 的下载量有多少？ 根据 npm 官方下载统计，@aliou/pi-ts-aperture 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,075 次，日均约 69 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @aliou/pi-ts-aperture 还在维护吗？ 最新版本 0\.20\.2 发布于 2026/11/07（今天）；至今共发布 55 个版本，其中过去 12 个月发布了 55 个；首次发布于 2026/02/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。