String AI Pi Provider

为官方 Pi 增加 string-ai 提供商。本版为 0.1.0-beta.10，增加 Percho 用户级零会话激活契约；必须搭配本文说明的宿主补丁，不能仅升级 npm 获得旧宿主冷启动修复。

安装

pi install npm:pi-provider-string-ai@0.1.0-beta.10
pi list

需要 Node.js >=22.19.0 和官方 Pi 1.4.0。安装后启动 pi；已打开的窗口执行 /reload 或重启。

已从本地目录安装过同名插件时，先执行 pi remove <原本地插件路径>，再安装 npm 版本。

登录和选模

在 https://www.string.ink/ 创建普通 API Key。不要使用 WebChat 内部 Key 或浏览器登录态。

/login string-ai
/model

Key 只在 Pi 提示中输入。默认地址是 https://www.string.ink/v1，新安装不需要 string-ai.json。

在 /model 中选择 string-ai 下当前 Key 返回的模型。Ctrl+S 保存默认模型，Enter 只切换当前会话，Esc 取消。

可用命令：

• /string-ai-help：查看登录和选模步骤。
• /string-ai-model：查看可用模型数量。
• /string-ai-status：查看认证、模型和价卡状态。
• /string-ai-refresh：刷新模型、余额和价格。
• /string-ai-balance：查询当前账户余额。

模型和价格

模型必须与服务目录中的 ID 完全一致。OpenAI、Claude、Grok 使用对应的 Pi 参考模板。deepseek-v4-pro、deepseek-v4-flash、deepseek-v4.1-flash 使用 /v1/responses。

状态栏显示账户积分余额。/model 中显示输入、输出和缓存价格，单位是积分/百万 token。价格已包含倍率。

DeepSeek 当前价卡返回 account_dependent，因此没有可显示的固定单价。已打开的 /model 不会自动刷新，价卡变化后重新打开。

配置

配置文件是当前 Pi agent 目录中的 string-ai.json，不要写入 Key。修改后执行 /reload。

models: [] 会禁用参考模型。需要恢复时删除该字段，或写入：

{
  "version": 1,
  "useBuiltinModels": true
}

备用地址是 https://ai.qpcmqam.cn/v1。使用时同时设置 baseUrl 和 useBuiltinModels: true，然后执行 /reload 和 /string-ai-refresh。插件不会自动切换地址。

自定义远程地址必须使用 HTTPS。只有显式设置 allowInsecureLocalhost: true 时，才允许本地回环使用 HTTP。

常见问题

• 401：Key 无效或已撤销，重新执行 /login string-ai。
• 403：当前 Key 没有该模型或协议的权限。
• 429：达到限流、并发或额度限制。
• 没有模型：执行 /string-ai-status。目录返回但没有匹配模型时，检查 useBuiltinModels。
• 离线：PI_OFFLINE 存在时不会联网刷新。恢复时删除该变量。
• Windows 找不到 Bash：把 Git 的 bin 目录加入当前 PowerShell 的 PATH。

卸载和更新

pi remove npm:pi-provider-string-ai@0.1.0-beta.10

固定版本不会自动升级。更新时安装新的明确版本，或执行：

pi update npm:pi-provider-string-ai@beta

更新插件后执行 /reload 或重启。/logout 只清除本机 Pi 凭据，不撤销服务端 Key。

Percho 多会话修复与边界

本版包含以下多会话目录修复。 普通扩展工厂不再逐会话覆盖 Provider；session_start 在首个异步边界前查找同运行时实例，完整配置、实现与认证模式兼容才复用，不兼容明确报冲突且不覆盖。已有暖目录在新会话推理前保持可选；请求前目录确认仅作保留的独立防线，不能代替选择器验收。 同实例、同身份的并发目录 GET 合并，等待受 timeoutMs 限制；单个请求取消不取消其他等待者。 不会跨实例缓存授权、自动切换模型/Key/地址或重发推理。Key/端点发生切换或目录被 401/403 撤销后，需显式刷新。

allowNetwork: false 只禁止该次宿主刷新联网，不永久禁用后续请求确认。 PI_OFFLINE 只要存在（包括空串和 0），就禁止目录确认和刷新；它不是整个推理传输的防火墙。 插件无法读取宿主创建时捕获的私有联网设置；要求完全离线的宿主应保持 PI_OFFLINE 或阻止请求。 状态、刷新、余额和选模命令读取当前原生 Provider；关闭一个会话只解除自己的 UI 订阅，不清其他会话的账户数据。 账户接口 401 也撤销目录；目录 403 只撤销目录及价卡，独立钱包结果保留。

原版 Pi 1.4.0 的 models.json 组合分发仍可能在空目录/不同 API 时绕过基础 Provider，走全局适配器。 该宿主边界不由插件单独修复；本地已有的 opt-in 宿主补丁会等待准入钩子，插件仍在真正发送前同步终检。 beta.9 的历史验证使用公开 SDK、manifest 与 Percho v0.6.6 提取路径；beta.10 候选另外使用真实 Percho Backend、实际 npm pack 解包入口与回环模拟服务验证零会话激活和首次 SSE 请求。两者都不代表完整 Electron 桌面、安装器或真实服务验收。

配套宿主是必要条件。 插件通过 percho:provider-activation:v1 发布版本化契约；它不是 Pi SDK 的通用 startup 钩子。配套 Percho 补丁在用户级资源发现后、初始选模和无会话草稿查询前建立共享 Provider 与目录屏障，不创建隐藏会话、不执行未信任项目 factory。未修补的 Percho/官方 Pi 仍只走 session_start 等原有路径；单独安装本 npm 包不能修复旧宿主零会话冷启动，也不承诺自动采用默认模型。

宿主维护者需从同版插件源码仓库取得 host-patch/percho-provider-startup/README.md、percho-provider-startup.patch 与 manifest.json。补丁固定宿主基线 b56f2121782f78211e5e02b7fa1c8999feaddbf6，含新增 provider-startup/model-refresh 源码与测试；这些维护者材料不在 npm 包内，不要对未知宿主版本直接套用。

配套补丁对启动/设置页的宿主调用协调刷新，启动使用全 Provider 刷新保留其他 Provider 的过滤；不修改 SDK 通用刷新为 FIFO。目录 503 保留工作台并输出警告，普通读取不隐式重试，用户显式刷新仍会报告失败。卸载/禁用/不兼容重载先撤销旧 Provider，需重启，不覆盖其他会话的实例。shutdown 先撤销并取消，再等待宿主自身启动/重载完成；第三方 factory 无强制取消接口，可能无界等待。

/string-ai-refresh 显式委托宿主全量模型刷新（可能查询其他已配置 Provider），避免 Pi 1.4.0 局部刷新复活其他 Provider 被过滤模型；不强制 allowNetwork:true，遵守宿主创建时捕获的联网策略。删除 PI_OFFLINE 后应重启原离线运行时。未修补宿主的并发离线 listModels 仍可能废弃冷目录在线发布；配套补丁仅协调 Percho 拥有的调用，不覆盖第三方直接 SDK 刷新。插件不冒报成功、不自动重试或切模。

最终独立复审结论是 PASS_SCOPED，只覆盖该插件与受审补丁组合的四项阻断，不是全量全绿。受审相关测试记录为插件 303 项 / 299 通过 / 4 项既有 SEC-01 失败，宿主 66 项 / 57 通过 / 9 项既有 settings 失败，renderer 52/52；此前全量仍有 29 失败 / 2 跳过，不以专项结果抹去。原版 Pi 的 SEC-01 组合器绕过风险仍存在；该冷启动补丁不声称修复原版 SDK 的所有请求准入问题。