Posthorse

这是什么？适合谁？

Posthorse（作者 fitchmultz，MIT 开源）是 fitchmultz/pi 分叉（Pi 编码 Agent 的分支）的上下文窗口扩展。名字取自驿站的”换马”：信使和消息不变，马换新的。对应到模型上就是：全新上下文、同一任务、完整可恢复的转录。

它解决的问题：编码 Agent 跑长任务时上下文窗口耗尽，传统做法是”摘要压缩”（summarize compaction）——会丢细节、丢中间结论。Posthorse 提供原生（no-summary）方案：一次 rollover 把旧窗口从模型活跃上下文中移除，但 JSONL 转录保持只追加（append-only）且完整，配合 rollover 工具、durable notes 和窗口感知 history，任务可在新窗口里继续。

适合谁：用 fitchmultz/pi 分叉跑超长编码任务（大型重构、多阶段迁移）的重度用户；研究 Agent 上下文管理与 compaction 替代方案的开发者。

不适合谁：用官方未修改版 Pi 的用户（明确不支持，装上会报扩展错误——Pi 本身不受影响）；需要开箱即用商业 IDE 的用户。

使用前提：Node ≥22.19.0；必须运行 fitchmultz/pi 分叉（CI 基线 commit f9b0617，对应 Pi 0.85.0）；理解”上下文窗口耗尽”是怎么回事。

准备工作

1. 环境：Node ≥22.19.0，fitchmultz/pi 分叉源码
2. 安装：git clone https://github.com/fitchmultz/pi.git && cd pi && git checkout f9b0617 && npm install --ignore-scripts && npm run build
3. 成本：MIT 免费开源；模型 token 费用照常（rollover 反而常省 token——不重复摘要）
4. 时间：构建分叉 + 安装扩展约 15 分钟；理解窗口策略约 30 分钟
5. 前置知识：Pi Agent 用法、上下文窗口概念、npm/git 基本操作

快速上手（3 步）

第一步：构建 Pi 分叉

git clone https://github.com/fitchmultz/pi.git
cd pi
git checkout f9b06177e565f70cd243a785d088d1c491830dbd
npm install --ignore-scripts
npm run build

用 node packages/coding-agent/dist/bundle/cli.js 直接跑，或在 packages/coding-agent 里 npm link 变成 pi 命令。

预期产出：可运行的分叉版 Pi。注意 pi --version 读的是 checkout 的包元数据，不能证明源码已构建——更新分叉后必须重跑 install+build。

第二步：安装 Posthorse

pi install npm:pi-posthorse            # 从 npm 安装
# 或
pi install git:github.com/fitchmultz/pi-posthorse   # 从 Git，加 @<tag> 可锁版本
# 或试运行不安装：
pi -e git:github.com/fitchmultz/pi-posthorse

预期产出：扩展加载成功。若误装到官方 Pi 上，session 启动时会得到清晰的扩展错误（Pi 本身照常运行）。

第三步：长任务中触发 rollover

在长编码任务中按 Posthorse 的稳定窗口指引操作：new_context 开新窗口（旧窗口移出活跃上下文、转录仍完整），get_context_remaining 查余量，durable notes 沉淀跨窗口结论，窗口感知 history 恢复过程。

预期产出：任务跨多个窗口持续推进，无摘要丢失，完整 JSONL 转录可审计/恢复。

常见踩坑（症状 → 原因 → 解决）

1. 装在官方 Pi 上报错。原因：官方 Pi 缺少分叉的原生 context_window 条目、session_before_auto_compact hook 和 ctx.getCompactionSettings()。解决：换用 fitchmultz/pi 分叉——README 明确”官方未修改 Pi 不支持”。
2. 更新分叉后扩展行为异常/失效。原因：pi --version 显示新版本但源码没重新构建。解决：每次更新分叉后重跑 npm install && npm run build 再重启 Pi。
3. rollover 后”感觉模型失忆”。原因：新窗口天然没有旧上下文细节。解决：rollover 前把关键结论写进 durable notes——notes 设计目的就是跨窗口携带信息。
4. 误用 Codex 原型给 Codex 用户。原因：仓库里 adapters/codex-posthorse 看起来通用。解决：README 明确它是隔离的原型实验，“not ready for everyday use”，不在 Pi 包内。
5. 找不到更新命令。解决：pi update npm:pi-posthorse 或 pi update --extensions；锁了 Git 版本的按 README 指引移动 pin。

初级用法

• 余量监控：长任务开始前先用 get_context_remaining 心里有数，别等爆窗。
• notes 沉淀：每个阶段性结论（“模块 X 已迁移完毕，跳过 Y”）随手写 notes，rollover 后零损失。
• 试运行评估：pi -e git:... 单次运行试用，不影响现有安装。

高级玩法

• 多窗口长重构：超大重构拆成多窗口接力，每窗 rollover 一次，全程转录完整可审计。
• history 恢复：中断后用窗口感知 history 从 JSONL 恢复现场，继续同一 journey。
• 策略研究：Posthorse 拥有策略层（稳定窗口指引、一次性 checkpoint 提醒），可对照摘要压缩方案做 A/B 评估。

小技巧

1. 把 f9b0617 基线 commit 记下来，分叉更新后对照 CI 基线再决定是否升级。
2. npm 版和 Git 版二选一即可；要锁版本用 Git + @tag。
3. durable notes 内容写得”可独立理解”（不带上下文代词），跨窗口后才有用。
4. JSONL 转录是 append-only 的——直接翻文件审计，不依赖任何 UI。
5. Node 版本严格 ≥22.19.0，别用 20.x 硬跑。

常见问题 FAQ

Q1: 能用在官方 Pi 或其他编码 Agent 上吗？

A: 不能用于官方 Pi（明确不支持，会报清晰扩展错误）；对 Codex 有一个隔离原型 adapters/codex-posthorse，但 README 声明”not ready for everyday use”且不在 Pi 包内。

Q2: rollover 和摘要压缩（compaction）到底差在哪？

A: 摘要压缩把旧上下文提炼成摘要塞回窗口——有损；rollover 把旧窗口整个移出活跃上下文，转录完整保留在 JSONL，新窗口从 durable notes 恢复关键信息——无损且可审计。

Q3: 一定要自己构建分叉吗？

A: 是，Posthorse 依赖分叉的原生 context_window 机制和 hook，README 要求 clone + checkout 指定 commit + build。

Q4: 更新扩展会丢历史吗？

A: 不会——JSONL 转录 append-only，扩展更新不触碰转录文件。

Q5: 和 Claude Code 的 auto-compact 比呢？

A: Claude Code 的 auto-compact 是摘要式；Posthorse 代表 no-summary 路线。两者哲学不同，适合对”中间结论零丢失”要求高的场景。

免责声明

本文基于公开资料整理，AI 辅助生成，未实际构建分叉运行验证。功能行为以官方仓库 README 为准。

参考链接

• GitHub 仓库 fitchmultz/pi-posthorse
• Pi 分叉 fitchmultz/pi
• 上游 Pi 编码 Agent earendil-works/pi
• Codex 原型 adapters/codex-posthorse