Pi 1.5 新功能与升级
如果你从本书旧版的 Pi 0.83 升级,变化不只有一份 1.5 发布说明。内置 MCP、Codemode、虚拟模型、全屏界面和新版 OpenAI 登录是在更早版本陆续加入的;下面会把它们和 1.5.0 本次变化分开讲。
Pi 1.5.0 发布于 2026-11-02。本页依据 1.5.0 发布记录与固定版本 changelog。模型目录、供应商权限和计费会继续变化;遇到实际请求问题,以当前账号和供应商为准。
先看与你有关的变化
| 你关心什么 | 1.5.0 中的变化 | 怎么做 |
|---|---|---|
| 更新后的扩展改了什么 | 支持显示扩展包的更新日志 | 更新后重新启动 Pi;见扩展更新日志 |
| 自己管理 Pi 的安装 | pi update 可调用你配置的更新命令 | 见自定义更新命令 |
| 模型与搜索 | 支持 GPT-6.1 Terra;模型选择器显示有意义的额外名称 | /model 搜索;见模型与搜索 |
| 远程 MCP 登录 | 默认优先使用符合条件的 Client ID Metadata Document | 见 MCP OAuth |
| 供应商设备码登录 | 部分登录流程按 Enter 后自动打开验证页并复制代码 | 以登录界面提示为准,检查代码和目标网站 |
| 自己写工具或扩展 | 参数校验改为 pi-schema;pi.exec() 可限制输出 | 先检查破坏性变化,见扩展迁移 |
| 代码和大工具调用卡顿 | 流式参数增量解析,渲染复用高亮与 Markdown | 无需配置;见性能和可靠性 |
从 0.83 升级时,不要漏掉这些旧变化
| 版本 | 值得重新认识的能力 |
|---|---|
0.99.0 | 内置 MCP、Codemode、工具搜索、虚拟模型、分类器和 system 主题;OpenAI provider 加入 Sign in with ChatGPT。 |
1.0.0 | 默认全屏 TUI;Codemode 支持图片生成。需要普通终端滚动时可用 --tui-mode regular。 |
1.2.0 | 发布配置 JSON Schema;OpenRouter 可按 Key 返回可用模型;Codemode 增强。 |
1.3.0 | /share 可配置目的地;支持的 OpenAI GPT-6 API Key 请求在会话中更改思考级别时可保留提示缓存。 |
1.4.0 | 部分分类器支持图片;Codemode worker 满载时排队;模型配置参考更完整。 |
1.5.0 | 本页重点:扩展更新日志、自定义自更新、模型和登录变化、工具参数校验迁移等。 |
这些能力在 1.5 中可用,不等于都由 1.5 引入。继续学习 MCP、Codemode 和模型与思考。
安全升级步骤
- 先运行
pi --version,确认当前实际运行的二进制;必要时用which pi或 Windows 的Get-Command pi检查是否有多个安装。 - 确认自己是通过 npm、pi.dev 安装器、Nix 或其他工具安装的。升级是真实修改本机软件,优先使用原安装方式;不要盲目叠装。
- 检查项目与个人 Extension、MCP 配置及自定义工具的依赖,备份需要保留的设置和会话。不要把
auth.json或会话内容上传到公开位置。 - 在可回滚环境升级,并重启 Pi;运行
pi --version、/model、/thinking、/mcp与常用 Extension 的成功和失败路径。 - 如果需要限制能力,验证实际生效的工具和 MCP 暴露方式;升级不等于获得沙箱。
例如,原来使用 npm 全局安装时,可以使用官方推荐的安装形式更新:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.5.0pi --version这是固定到 1.5.0 的示例,不适用于所有安装方式。pi update 也能更新受支持的安装;其他包管理器通常应由其自身更新。参见 Pi CLI 更新文档。
扩展包更新日志
1.5.0 可以在扩展包更新后,下一次全新启动时显示 Extension Updates:
- 仅适用于加载了至少一个 Extension 的包;只有 Skill、模板或主题的包不会显示。
- 第一次见到包只记录版本,不展示历史;之后只显示比上次看到的版本新的条目。
- 默认读取包根目录
CHANGELOG.md;作者可用package.json的pi.changelogPath指向包内其他文件,设为空字符串则禁用。 - 条目版本与包的
package.json中version匹配;Git 包也需要提高该版本。 collapseChangelog: true会将更新提示压缩为每个包一行;/changelog不显示扩展包日志。
包作者示例:
{ "name": "my-pi-package", "version": "1.2.0", "pi": { "changelogPath": "./docs/CHANGELOG.md" }}日志使用 ## [1.2.0] 等版本标题。更多细节见 Pi Packages:Show a changelog。
自定义更新命令
对于通过包装器或其他包管理器提供的 Pi,1.5.0 允许将自身更新委托给你指定的命令。下面是在 ~/.pi/agent/settings.json 中的示例;合并到已有配置,不要覆盖其他字段:
{ "selfUpdateCommand": ["nix", "profile", "upgrade", "pi"]}另一个方式是在启动 pi update 的环境中设置 PI_SELF_UPDATE_COMMAND。它优先于设置项,按空格拆分;参数本身含空格时,用设置项的 argv 数组。命令支持 {packageName}、{version} 和 {installSpec} 占位符。
Pi 在 pi.dev 报告有新版本时才运行自定义命令。它会执行你配置的程序并修改安装,因此先核对命令和包管理器。包更新仍可单独使用 pi update --extensions,目录刷新用 pi update --models。
模型与搜索
- 1.5.0 增加 GPT-6.1 Terra,适用于 OpenAI、Azure OpenAI Responses 和 OpenAI Codex;支持工具搜索、会话中调整思考级别及
off。Changelog 为 Codex 路径标注 500K 上下文,不要据此推断其他 provider 或账号的额度。 - 使用设备码登录的供应商(例如 GitHub Copilot)可以在确认时打开验证页并复制代码;具体供应商可关闭其中任一行为。远程环境应检查 URL,并避免把验证码和回调写进日志。
- OpenAI 的内置默认模型改为
gpt-6.1-sol;已保存的默认值、恢复的会话和实际账号权限仍会影响最终选择。 - 内置模型目录更新到 models.dev v2;实时和仅图片模型不再作为聊天模型列出。图片模型仍可通过 Codemode使用。
/model与/scoped-models在模型名称比 ID 提供更多信息时同时显示名称;/model和/resume搜索也有匹配修复。- 工具搜索对中文、日文、泰文等非 ASCII 查询的支持得到修复。找到工具不代表你已经授权它执行副作用。
Pi 目录中出现模型并不保证你的账号能调用;模型、思考档位、主题颜色与虚拟路由见模型与思考。
扩展开发者:先检查参数校验
这是 1.5.0 的破坏性变化:工具参数统一按 JSON Schema 经 @earendil-works/pi-schema 校验,不再执行 TypeBox 独有、无法表达为 JSON Schema 的能力。
Type.Refine()不再运行;业务约束要在execute()中明确验证。Type.BigInt()、Type.Undefined()、Type.Void()不适合 JSON 工具参数;codec 不再自动解码。Format.Set()注册的自定义格式不参与校验;标准格式仍支持。- 数字字符串、
"true"、单个值转数组等可能被转换后再校验;不要假定原始类型一定原样到达。 - 错误消息格式改变。测试应验证路径、行为和业务约束,而不只依赖旧版 TypeBox 文案。
TypeBox 构造的普通 JSON Schema 仍可使用。新代码从 typebox 导入 Type;在 Pi 中从 @earendil-works/pi-ai 的兼容导入仍可用,但不应据此假设独立发布的 pi-ai 也导出 TypeBox。结合第一个 Extension 的迁移检查逐项验证。
pi.exec() 的输出上限
pi.exec() 不通过 shell 执行命令。1.5.0 增加 maxBuffer,按 stdout 与 stderr 的合计字节数限制输出,并返回 truncated。超限后 Pi 终止命令,结果包含 truncated: true、killed: true 和非零 code;取消和超时也可能导致 killed,不能仅凭它判断原因。
const result = await pi.exec("git", ["status", "--short"], { timeout: 5_000, maxBuffer: 64 * 1024,});if (result.truncated || result.code !== 0) { throw new Error("git status 失败或输出被截断");}超时或取消后若进程忽略 SIGTERM,Pi 会在 5 秒后发送 SIGKILL。工具本身的行为、子进程权限和外部副作用仍由调用者负责。
其他扩展与 SDK 变化
- 在工具渲染上下文中使用注入的
context.keyHint()/keyText(),在消息和条目渲染器中使用对应的options方法,以反映用户真实键位。 - 内联
ctx.ui.custom()可通过blocked报告等待question、permission或auth;overlay 不使用此选项。 MarkdownTransformContext为已保存条目提供messageId和 ISOtimestamp;实时渲染时可能为undefined。- 用量的
cost.totalFromProvider区分总价是否来自供应商;混合用量只有全部部分都由供应商报告时才标记。不能据此认为所有分项价格都来自账单。 - pi-messages provider 的消息可包含实际
responseModel;虚拟模型的所选模型和实际派发模型也要分开看。
完整类型与上下文见 Pi Extensions、TUI 和 Message Types。
性能和可靠性
1.5.0 对大工具调用使用增量解析,并复用代码高亮和流式 Markdown,长输出时减少重复计算;这不是模型推理速度的保证。其他值得注意的修复包括:
- 已保存的“不信任”决定不再被无受保护资源目录的自动信任覆盖。
- MCP OAuth 和登录链接拒绝不安全的非 HTTP(S) 地址;仍需审查你选择的服务和授权。
- HTML 导出修复超长会话空白页,并包含系统提示、工具及后续系统更新;分享前更要检查敏感内容。
- macOS 中止 shell 命令、UTF-8 流和
pi.exec()超大输出的处理得到修复。 - 未固定版本的
-e npm:包与 Git 分支会在启动及/reload时检查更新;离线或检查失败时使用缓存。需要可复现时固定 npm 版本或 Git 提交。 - 本地窗口选择器的 PageUp/PageDown、Apple Terminal 的 Shift+Enter,以及部分图片压缩与 CJK 文本渲染得到修复。
逐项变更与限制请查看固定版本 changelog。