pi-zh-cn

把 pi 编码代理的界面变成简体中文。装上重启即可，不想要了随时卸载。

特性

• 零侵入：只是普通扩展，调用官方扩展 API 替换文案，不打补丁、不改安装目录里的任何文件，pi 正常升级后一般也能直接用
• 不改模型输入：发给模型的内容保持不变，工具 description 保留英文原文，避免影响模型行为
• 按需开启：grep、find、ls 或 powershell 没开就不会被偷偷打开
• 键位跟随：快捷键提示跟随你自己的键位配置
• 改词不改源码：settings.json 里写 pi-zh-cn.copy 就能覆盖任意字符串词条，/zh 查看生效情况，见改词

汉化范围

• 启动画面：标题、快捷键提示、引导语；按 ctrl+o（跟随你的键位）展开内置那张完整键位参考表。设了 quietStartup: true 时不显示，尊重该设置
• 底部状态栏：当前目录 / 分支 / 会话名、token 与缓存用量、费用、上下文占比、模型和思考等级
• 加载提示：「正在处理…」；thinking 折叠块的标签
• 八个内置工具的执行结果：读取、执行（bash）、编辑、写入、搜索内容、查找文件、列出目录、PowerShell——状态行都是中文，比如「完成」「退出码 N」「耗时 1.2s」，长命令执行中显示「运行中… 已用 1.2s」并每秒刷新，输出被截断时给出「完整输出：<路径>」与「已显示 N / 共 M 行」
• 搜索内容 / 查找文件 / 列出目录：折叠态就显示结果行（grep 15 行、find/ls 20 行，与内置渲染器一致），超出时提示「还有 N 行」
• 工具行里的文件路径：家目录缩成 ~/…；支持 OSC 8 的终端里可点击直接打开文件（终端不支持时自动退化为纯文本）
• 编辑、写入与读取的内容展示沿用 pi 内置渲染器（只有标题和展开提示是中文）：edit 显示行号 + 红绿 diff，write 预览文件内容（折叠 10 行，ctrl+o 展开全量），read 展开态保留内置的语法高亮
• 项目信任弹窗：信任/不信任选择，含「信任父文件夹」变体。defaultProjectTrust 设成 always/never 时不弹窗，尊重该设置
• 内置斜杠命令描述：core 全部 24 个命令

安装

pi install npm:pi-zh-cn

重启 pi 即生效。查看已安装的包：

pi list

卸载

pi remove npm:pi-zh-cn

临时切回英文

觉得中文状态栏不如原生好读，可以在会话里执行：

/footer

看看汉化状态

/zh

列出词条覆盖各层读到了什么、哪些条目生效、终端支持哪些能力。改了设置没反应时先跑它——最常见的两种原因是项目没受信任（整层被跳过）和键名拼错（只在启动时提示一次，容易被刷走）。

兼容性

peerDependencies 只设下限（>=0.84.0）不设上限，pi 出新版也不会被拦住。兼容性靠测试保证，不靠钉版本：

• push/PR：对着 lockfile 钉住的基线跑契约测试
• 每两天：上游金丝雀忽略 lockfile、拉最新版 pi 跑同一套测试
• 基线跟进：上游发版后用 npm run upstream 看变更，确认无碍再抬 devDependencies、重新生成 lockfile

三者的分工：金丝雀是真正的安全网——基线落后也照样用最新版 pi 验证，所以上游发版后两天内就会暴露问题；基线只决定 push/PR 那趟测的是哪一版。

基线跟进没有交给 Dependabot：它配了 @earendil-works/* 分组，但 2026-10-12 上游发 1.2.0 之后，它连着两趟（10-14）都判成「No update needed」——日志里甚至已经探到了 1.2.0 的 tarball，仍认为最新版是 1.1.0。历史上升级 PR 也只开出过一次（#6），还在 10-08 被手工升级顶掉了。所以基线以手工跟进为准；它真开出 PR 就当多一次验证，没开也不会漏，金丝雀兜底。

Node 版本要求跟随 pi，由 pi 自己声明和检查。

改词

某处译法不合口味，不用改源码、也不用 fork——在 pi 的 settings.json 里写 pi-zh-cn.copy，结构与 extensions/zh.ts 一致，叶子写字符串：

{
  "pi-zh-cn": {
    "copy": {
      "footer": { "cwdPrefix": "目录：" },
      "tools": { "bash": { "done": "跑完了" } }
    }
  }
}

不知道某个词对应哪个键？在会话里跑 /zh keys，按父级分组列出全部可覆盖的词条；/zh keys bash 可按子串过滤。分组名就是上面要写的嵌套结构。

• 全局设置在 ~/.pi/agent/settings.json；项目本地那份（.pi/settings.json）在该项目受信任时优先生效，与内置设置同一套信任边界
• 只覆盖字符串条目。zh.ts 里有一部分是函数（要拼数字，例如「N 行输出」），JSON 表达不了，那些保持原样（/zh keys 会告诉你有多少条属于这种）
• 键名拼错不会有反应——一条都没对上时会提示一次，免得你以为改完了其实没生效
• 删掉某一项后，新开会话或 /reload 即恢复默认译法，无需重启 pi

已知局限

• 内置菜单和其他硬编码在 pi 源码里的英文保持原样——扩展 API 够不到，除非 fork 上游重编译，不值得
• 全屏模式（pi 1.0 起为默认，tuiMode: "fullscreen"）文案写死在 pi-tui 里，同样够不到，例如 ↓ Jump to latest message · <键位>，以及搜索框的 Find in transcript / No matches
• read 折叠态对 SKILL.md、AGENTS.md/CLAUDE.md 以及 pi 自带文档的紧凑显示没有复刻（上游显示 read skill <名字>，不显示完整路径）：上游那套路径分类依赖包内未导出的助手，复刻要把 pi 自身的安装路径写死，而只在读这几类文件时才看得出差别，不值得
• edit 在结果返回前不显示行内 diff 预览（上游会在参数到齐后就先算出来展示）：预览依赖未导出的 computeEditsDiff，够不到；结果返回后的 diff 显示不受影响

开发

npm install
./node_modules/.bin/tsc -p .   # 类型检查

# 本地试跑（进 TUI 才看得到汉化）
pi --no-session -e ./extensions/index.ts

汉化只在 TUI 模式生效。-p（print）和 --json 是无 UI 模式——pi 给扩展绑定的 ctx.hasUI 为 false，扩展第一行就返回了，什么都不替换。拿 -p 试跑只能验证「能加载」，看不到中文，别误以为插件没生效。

所有文案都集中在 extensions/zh.ts，想改词只动这一个文件就够了。 只是不满意某几处译法、并不想接手维护的话，用改词那节的覆盖机制更省事—— 升级插件不会冲掉你的改动。

上游兼容性测试（契约测试）

汉化依赖 pi 内部结构（footer 统计行、工具 details 字段、trust.json 语义、 斜杠命令清单等），上游一变就可能静默失效。test/ 下的契约测试把这些 依赖点逐条断言：实际执行内置工具、实例化 ProjectTrustStore、探查内置 footer 的 dist 源码，任一结构变化都会失败并指明该核对哪个文案。

npm test   # tsc 类型检查 + 全部测试

CI 在每次 push/PR 时运行，并每两天定时跑一次「上游金丝雀」：本地开发 基线由 package-lock.json 钉住，而金丝雀那趟会忽略 lockfile、拉到最新 版 pi，所以上游发布后两天内即可自动暴露兼容性问题，不用等用户反馈。

上游跟进报告

契约测试只能回答「本地化有没有被上游改坏」，回答不了「上游新增了什么值得汉化的东西」。后者用这个脚本一次列出来：

npm run upstream          # 本地基线 → 上游最新
npm run upstream 1.1.0    # 与指定版本比（回溯某次跟进）

它直接问 registry 取 tarball（不装依赖、不改仓库任何文件，解压在临时目录），给出比基线新的 CHANGELOG 条目，以及 dist 的变更文件清单——已排除 bundle/ 与 sourcemap，那些文件名带内容哈希、每次发版全变，不排掉会淹没真正的变更。

这是脚本而不是测试，是有意的：变更清单里必然混着大量与界面无关的重构，要靠人判断；这种噪音混进断言会让金丝雀变得爱报警，而一个爱报警的金丝雀很快就会被忽略。

发布

推 tag 即发布：流水线会核对版本号、跑测试、发到 npm 并生成 provenance，认证走 npm Trusted Publishing（OIDC），仓库里没有 NPM_TOKEN。完整流程、发完怎么核对、 报 ENEEDAUTH 怎么查，见 RELEASING.md。

反馈

pi 大版本升级后如果出现错位或残留英文，欢迎提 issue。

改动记录见 GitHub Releases。

License

MIT