PI BLUEBOOK

简体中文

繁體中文

简体中文

繁體中文

外观模式

RELEASE NOTES · 2026-10-21

Pi 1.2–1.4 更新要点 ​

Pi 在两周内连续发布了三个小版本：1.2.0（2026 年 10 月 12 日）、1.3.0（10 月 15 日）和 1.4.0（10 月 21 日）。本页依据官方 Changelog 与固定版本文档整理，核验日期为 2026-10-28。逐项英文变更保留在版本档案。

三个版本都没有改变本书课程的基本操作。只用内置功能、不写 Extension 的读者，升级后照常使用即可；写过 Extension、自定义主题或改过 models.json 的读者，需要看下面的「升级时要处理的变化」。

三个版本各改了什么 ​

版本值得关注的变化对使用者的影响
1.2.0配置文件可声明 $schema编辑 settings.json、models.json 时，编辑器能提示字段并检查写法
1.2.0before_agent_start 事件范围扩大Extension 作者需要检查，详见下文
1.2.0PI_CLIPBOARD_OSC52=1Pi 识别不出远程会话时（例如从另一台电脑接入 tmux），设置后复制的文字也能回到本地剪贴板
1.3.0恢复会话保留原来启用的工具中途启用的工具不会在 /resume 后消失
1.3.0--model 优先选择已有凭据的提供商多个提供商都有同名模型时，不再按目录顺序随机落到没登录的那一个
1.3.0切换模型时丢弃旧模型的思考内容新模型不再把上一个模型的推理当成自己的回复继续写
1.3.0/share 可选择上传位置新增 sessionShareDestination 设置，取值为 auto、gist 或 radius
1.4.0压缩摘要按模型输出上限生成长推理不再让压缩以「generation hit the token cap」失败
1.4.0中文标点旁的粗体和斜体正常显示终端和 HTML 导出中，**粗体**紧挨全角标点时不再显示成星号
1.4.0多项 Windows 修复PowerShell 5.1 改写安装标记后 pi update 失败、Windows 不装在 C 盘时找不到 shell 等问题已修复

给配置文件加上 $schema ​

1.2.0 起，官方在 https://pi.dev/schemas/ 发布了设置、模型、按键和主题四份 Schema。在配置文件第一行声明它，VS Code 等编辑器就能补全字段、提示说明，并标出拼错的名称：

json
{
  "$schema": "https://pi.dev/schemas/settings.schema.json",
  "quietStartup": "header"
}

models.json 对应 models.schema.json，按键配置对应 keybindings.schema.json。这一行只给编辑器使用，不会改变 Pi 的行为。本书在 Pi 1.4.0 的独立配置中加入这一行后启动，没有出现警告。

自定义主题的读者要多做一步：主题 Schema 已迁到 https://pi.dev/schemas/theme.schema.json，启动时加载的主题也会按 Schema 校验。旧主题需要更新 $schema 地址、把复用的颜色放进 vars，并删除不受支持的元数据。没写过主题可以忽略。

升级时要处理的变化 ​

版本变化需要做什么
1.2.0before_agent_start 也会在 Extension 发起的运行前触发：pi.sendMessage(..., { triggerTurn: true }) 在空闲时启动的运行，同样经过这个事件只想处理用户输入的处理函数，要先判断 event.messageType === "user"；"custom" 类型的事件没有 prompt
1.2.0运行启动期间视为忙碌：ctx.isIdle() 返回 false，pi.sendMessage() 排进正在启动的运行，pi.sendUserMessage() 必须指定 deliverAs检查依赖 isIdle() 判断时机的 Extension
1.2.0主题 Schema 迁移，启动时也做校验按上一节更新自定义主题
1.2.0pi mcp list --json 改为报告 resources: true，不再给出资源数量解析这项输出的脚本需要调整
1.3.0kimi-coding 改用 Chat Completions 协议在 models.json 覆盖了它的 Base URL 时，地址必须以 /v1 结尾
1.4.0GitHub Copilot 默认模型从已下线的 gpt-5.4 改为 gpt-6.1-sol；小米默认模型改为 mimo-v2.6-pro设置里写死旧模型名的，改成新名称或重新用 /model 选择
1.4.0Extension 的 before_provider_headers 不再看到 OpenRouter、NVIDIA NIM 与 OpenCode 的来源标识请求头只影响改写请求头的 Extension；返回 null 仍可删除对应请求头

前两项是官方标注的 Breaking Changes。本书提供的检查扩展和工具清单扩展只注册命令，不使用这些事件；检查扩展已在 Pi 1.4.0 下重新安装运行，通知正常。

恢复会话会保留哪些工具？ ​

1.3.0 之前，在会话中途启用的工具，恢复会话后可能消失。现在 /resume 或 pi --continue 会恢复会话当时启用的工具；启动时写的 --tools +名称／-名称 在此基础上增减。

下面三种写法仍会整套指定工具，不沿用会话记录：--tools 后面写普通工具名、--no-tools、--no-builtin-tools。这与 Pi 1.1.0 的工具加减写法规则一致。

做只读审阅这类练习时，继续在启动命令里写明完整的只读工具清单，不要依赖恢复会话的默认结果。

压缩为什么不再失败 ​

1.4.0 之前，压缩摘要和分支摘要有固定的输出上限。模型推理占用较多时，摘要还没写完就触顶，压缩随之失败。现在摘要请求改用模型自身的输出上限。

settings.json 中两个压缩设置的含义因此更清楚：

设置默认值含义
compaction.reserveTokens16384剩余上下文低于这个值时开始自动压缩；不再限制摘要长度
compaction.keepRecentTokens20000最近这部分内容原样保留，不进入摘要

两个默认值来自 Pi v1.4.0 固定设置文档。压缩的整体机制见上下文与压缩；本课的建议不变，日常使用保持默认值即可。

升级后怎样核对？ ​

先记录当前 pi --version，再按生命周期管理中与原安装方式一致的路径升级。升级后在普通终端执行：

bash
pi --version

复现本页对应版本时应显示 1.4.0；以后直接更新到最新版，可能显示更高版本，需要继续查对应日志。进入 Pi 后，按登录与模型设置做一次无工具连通测试，再确认常用 Extension 能加载、需要的 MCP 服务器能连接。

2026-10-28，本书在独立 npm 前缀与独立配置中，用 Pi 1.4.0 重新走了这些课程的实测步骤：

各页的具体范围和未实测部分，写在该页末尾的核验说明中。升级后若模型、扩展或 MCP 异常，先保留错误与原配置，再按故障排查一次检查一项。

官方来源 ​