企业官网建设流程全解析

Pi-Bolt 是把 coding agent（Pi）通过 AOT（提前）编译成单个原生可执行文件的项目，启动快 10 倍、CPU 少 7 倍、内存省 4.5 倍。它的插件系统最大的特点：Pi 的插件（extensions）无需任何修改就能运行，而且可以用一条pi-bolt compile命令把插件编译进可执行文件，让热代码比默认构建下的解释执行快24 倍。本文带你从零理解 3 种插件运行方式，并动手完成编译提速。

一、Pi-Bolt 插件系统是什么？

Pi-Bolt 的插件就是 Pi 的extension：一个 TypeScript 模块，默认导出一个 factory 函数，负责向 Pi 注册工具（tools）、斜杠命令（commands）和事件处理器。Pi-Bolt 在启动时会按固定顺序加载并列出所有扩展，你可以直接在界面顶部的[Extensions]区块看到它们：

插件可以从 4 个位置被发现和加载，规则与原生 Pi 完全一致：

• ~/.pi/agent/extensions/：用户级扩展目录
• 项目里的.pi/extensions/：项目级扩展（需在受信任项目中）
• pi --extension <路径>：临时加载单个文件
• pi install <包名>：从 npm 等来源安装的 Pi 包

完整规则可查阅官方文档 docs/PLUGINS.md。

二、3 种运行方式：如何为你的插件选择最快方案

同一个插件，运行方式不同，速度天差地别。Pi-Bolt 提供3 种运行方式，按场景对号入座：

怎么选？

• 每天必用、有密集计算的插件→ 方式①，编译进二进制；
• 正在开发或只是试试看的插件→ 方式②，改完即生效；
• 装了十几个第三方插件、不想逐个编译→ 换-jit构建（如pi-bolt-linux-x64-jit），运行时加载的代码预热后同样快。

官方文档 docs/PLUGINS.md 中有完整对比。

三、24 倍提速从何而来：pi-bolt compile 的真实数字

这是本文的核心。Pi-Bolt 默认构建关闭 JIT——Pi 自身的全部代码在构建期就编译成了机器码，所以运行时不需要 JIT。但用jiti在运行时加载的插件代码不在其中，只能由 JavaScriptCore 的解释器执行。解释器跑紧循环比编译后的代码慢 20~30 倍，这就是 24 倍差距的来源。

实测数据（Pi-Bolt 0.7.3 / Linux x86-64，用示例插件的/words命令逐字符扫描 16.8 MB 文件）：

1315 ÷ 55 ≈ 24——这就是标题里24 倍提速的出处。编译进二进制的插件还附带两个收益：

• 启动零成本：同样的插件用 jiti 加载要耗 39 ms（Bun 上要 95 ms），编译进去后完全消失；
• 无需预热：性能与 JIT 全速运行保持在 1.25 倍以内，但没有 JIT 的预热、编译线程和额外内存。

原始数据见 bench/results/2026-10-10-pi-bolt-0.7.3/summary.md，方法说明见 docs/BENCHMARKS.md。

四、pi-bolt compile 快速上手：把插件编译进可执行文件

在 Linux 和 macOS 上（安装器安装的版本），只需一条命令：

pi-bolt compile # 把本机已安装的扩展全部编译进 pi-bolt pi-bolt compile --list # 查看将编译哪些扩展（不下载、不构建） pi-bolt compile --status # 查看当前已编译进哪些扩展 pi-bolt compile --off # 恢复为官方发布版的可执行文件

常用参数速查：

• --only a,b：只编译指定插件；
• --exclude 大插件：排除某插件，且之后的编译和pi-bolt update都继续排除；--include可重新纳回，--no-exclude全部纳入；
• --out 路径：输出到新位置，不覆盖已安装的版本。

你需要知道的行为细节：

1. 首次编译会下载该版本的 runtime 和编译工具包（macOS 约 37 MB、Linux 约 51 MB），校验签名后缓存在~/.pi-bolt/cache，之后离线也能重复编译。
2. 耗时约 20 秒（JIT 构建约 40 秒），过程会实时打印每个阶段。
3. 项目级扩展（.pi/extensions）不会被编译进去——编译进去的代码对所有项目生效，项目扩展仍按原方式从文件加载。
4. 插件文件在编译后发生变化（改代码、升级依赖）时，Pi 会自动回退为从文件加载并提示你重新执行pi-bolt compile；插件自己写入的状态、日志、缓存不算"变化"。
5. 新可执行文件会替换已安装版本，旧版本自动保留，可用pi-bolt update --rollback回滚。

Windows、Termux 和 npm 安装方式下，pi-bolt compile暂不可用，可在源码检出中用构建脚本达到同样效果：

scripts/build-pi.sh --plugins-from-installed --out out/pi-bolt-plugins

详见 scripts/build-pi.sh 与文档中的 Compile in the plugins you already have 一节。

进阶：手动编写插件清单（manifest）

如果你维护自己的插件集合，可以写一个 manifest 文件（默认导出插件列表），然后构建：

scripts/build-pi.sh --plugins my-plugins/plugins.ts --out out/pi-bolt-plugins

仓库自带完整示例：清单 examples/plugins/plugins.ts 和一个普通 Pi 扩展 examples/plugins/extensions/word-count.ts（提供word_count工具与/words命令），构建后运行/words README.md即可体验。

五、3 条让插件被 AOT 编译器"偏爱"的写法

默认构建下，JIT 会帮你把慢代码优化快；AOT 编译器没有类型反馈，只能靠代码本身的可预测性走快速路径。只在热代码（逐 token 的流处理、事件处理器、每帧渲染、大输入循环）上注意这 3 点即可：

1. 热点辅助函数放在模块顶层，按名字直接调用（function isSpace(c) {...}），不要用方法调用helpers.isSpace(c)——实测热循环里方法调用比模块级函数慢约 50%；
2. 正则用字面量（/^\s*([\w-]+):/）：构建期直接编译成机器码；必须动态构造的模式请构建一次、存到模块级变量复用；
3. factory 保持轻量：注册工具/命令/事件就够了，启动子进程、监听、定时器这类动作推迟到session_start或具体命令触发时——factory 里每慢 1 ms，每次启动都多等 1 ms。

完整规则（对象形状、标准对象冻结、文件内嵌、Workers 等）见 docs/PLUGINS.md 的 Performance guide 与 Compatibility checklist。

六、验证与测量：如何确认插件真的编译进去了

pi-bolt compile --status # 哪些扩展已编译进、哪些因变化仍从文件加载 pi-bolt doctor # 健康检查（不执行任何编译进扩展的代码） PI_TIMING=1 pi -p "hello" # 打印启动各阶段耗时，含每个插件 factory

三个信号说明一切正常：

• 启动日志的[Extensions]区出现<inline:name>形式的条目；
• --status显示该扩展"compiled in"且无 changed 标记；
• PI_TIMING=1中插件加载耗时接近 0。

想端到端对比两个构建，可用基准工具（见 bench/README.md）：

python3 bench/benchmark.py --runs 10 --build plugins=out/pi-bolt-plugins/pi --build plain=out/pi-bolt/pi

七、常见问题排查：插件编译失败怎么办

完整表格见 docs/PLUGINS.md。

八、什么时候不值得编译？

官方用 9 个真实 npm 插件（pi-lens、pi-subagents 等）在 Windows 上做了横评（bench/results/2026-10-10-plugins-real/summary.md），结论很务实：

• 多数插件的动作耗时主要在 I/O、子进程和 MCP 网络上，解释执行与否差别不大——这类插件用运行时加载即可，JIT off 构建反而启动最快、内存最低；
• 真正值得编译的是"自己跑大量 JavaScript"的插件，如 pi-lens 的module_report：JIT off 下 838 ms，JIT on 下 154 ms，编译进去后回到 55 ms 量级；
• 编译进去省的是加载开销（10 个运行时插件合计约 20 ms），省不掉 factory 本身要做的网络等待等真实工作。

先跑一次PI_TIMING=1，看每个插件 factory 的实际耗时，再决定编译谁——数据比感觉可靠。

总结

Pi-Bolt 的插件系统把"性能"和"生态兼容"做到了兼得：插件一行不改就能跑，而当你想榨出最后一倍性能时，一条pi-bolt compile就是全部成本。更多细节见官方文档 docs/PLUGINS.md 与基准报告 docs/BENCHMARKS.md。