5. 演进时间线¶
5.1 概要¶
| 维度 | 事实 |
|---|---|
| 仓库寿命 | 12 天（2025-08-09 → 2026-08-11） |
| 总 commit | 5,650（含 merges 5333 不含） |
| Release 数 | v0.5.3–v0.84.1（≈ 100 个 minor 方向） |
| 关键说明 | 用户取消"找 MVP"任务；本节只回答"它怎么走到现在" |
历史全部来自：
git log --unshallow+git log解析。 数据采集于 2026-08-11（/tmp/pi-snap受控副本，HEAD =2a9b4eb）。
5.2 大版节点¶
| Release | 时间 | SHA (first commit) | 备注 |
|---|---|---|---|
| v0.5.3 | 2025-08-09 | 3a9c3a2ed |
仓库首发 commit 时的版本号——继承自单仓库前身 |
| v0.5.4 | 2025-08-09 | f579a3f11 |
修 lockstep versioning |
| v0.5.5 | 2025-08-09 | db86195dd |
添加 tool call metrics ⚒ counter |
| v0.5.6 / 0.5.7 | 2025-08-09 | 9fee30607 / 832b20b1 |
修全局安装与符号间距 |
| v0.7.16 | 2025-11-17 | (略) | ⚠️ 间隔 ≈ 3 个月空白——从单包迁到 monorepo 后又长时间未发布 |
| v0.10.0 | 2025-11-27 | 932f48b0e |
进入"重新活跃"周期 |
| v0.20.0 | 2025-12-12 | a5268d2aa |
大约半个月密集迭代 → v0.20 |
| v0.30.0 | 2025-12-26 | cb6310e15 |
自动 session migration |
| v0.40.0 | 2026-01-09 | 070ef9c77 |
持续小步快跑 |
| v0.50.0 | 2026-01-26 | 453e104d3 |
进入第二季度 |
| v0.60.0 | 2026-03-18 | b0026866b |
三个月跨越 |
| v0.70.0 | 2026-04-24 | 612be54c2 |
|
| v0.80.0 | 2026-06-23 | f08e968c8 |
第一次出现 Armin Ronacher 作为 release commit 作者 |
| v0.84.0 | 2026-08-06 | a5f43bf8a |
|
| v0.84.1 | 2026-08-07 | (release commit) | 当前 |
| main HEAD | 2026-08-11 | 2a9b4ebc6 |
工作前沿 |
5.3 各包首次出现¶
| 包 | 第一次 commit 涉及它 | 备注 |
|---|---|---|
tui |
2025-08-09T17:18:38 (a74c5da1) | monorepo 创即刻存在 |
agent (旧 pi-agent) |
2025-08-09T17:18:38 | 紧接着 cli 出现 |
telemetry |
2025-08-10+ | 几乎立刻 |
ai |
2025-08-17T20:18:45 | ⏱ 晚了 8 天才独立成包 |
protocol / client / server |
较晚才出现 | 在 RPC 化阶段引入 |
session-backends |
较晚才出现 | 用于 session 持久化 |
evals |
较晚才出现 | 用于 benchmark |
你可能想知道的："pi-ai 是后建独立包的"——这意味着早期版本里 LLM 适配代码是埋在
pi-agent内的。这是一个值得被记住的演化事实。
5.4 关键事件线¶
Phase I：单包 → monorepo 整合（2025-08-09）¶
a74c5da1 2025-08-09 17:18 Mario Zechner
"Initial monorepo setup with npm workspaces and dual TypeScript configuration"
这是历史第一笔——同时把所有 package 一次创建出来（前 5 个包）。
Phase II：早期 bug 修复（2025-08-09 当天）¶
c615f3f0 17:27 Fix npm publishing warnings and clean up package.json files
d304f377d 18:02 Fix pi-agent CLI execution issue when installed globally
42dc46a51 18:05 Fix process.cwd() error when running from deleted directory
3a9c3a2ed 19:26 v0.5.3 - Fix missing scripts directory in published package
典型过程：拆库 → 暴露问题 → 立即修 → 发版。
Phase III：reasoning token 支持（2025-08-10）¶
2025-08-10 00:32 agent: Add reasoning token support for OpenAI reasoning models
2025-08-10 01:46 feat(agent): Comprehensive reasoning token support across providers
2025-08-10 01:56 docs: Fix outdated Gemini thinking content notes
2025-08-10 02:13 docs: Improve reasoning support table clarity
叙事：OpenAI o1 系列的 reasoning_effort 在 PR 前两天刚被公开，Pi 团队 "一天之内" 把 reasoning token 普及到所有 provider。
Phase IV：TUI 差分渲染成熟（2025-08-10~11）¶
2025-08-10 22:33 tui-double-buffer: Implement smart differential rendering with terminal abstraction
2025-08-11 00:57 tui: Fix differential rendering to preserve scrollback buffer
2025-08-11 01:13 tui: Implement surgical differential rendering for minimal redraws
2025-08-11 01:34 fix(tui): Trigger initial render when start() is called
2025-08-11 02:31 fix(tui): Container change detection for proper differential rendering
2025-08-11 14:17 fix(tui): Fix garbled output when content exceeds viewport
叙事：他们重写了 TUI 渲染核心——从"全量重绘"变成"外科手术式最小重绘"，保留 scrollback buffer。这是个大且完整的重构。
Phase V：3 个月停顿（2025-08 ~ 2025-11）¶
仓库仍然在 commit（agent / tool / fix / refactor 等），但 没有 release commit。这暗示一个"持续打磨、没有用户可用 release"的状态。 这种模式在 OSS 早期是常见的——是开发者内部用，等到某个里程碑才公开发布。
Phase VI：再次活跃（2025-11-17+）¶
2025-11-17 14:12 Release v0.7.16 ← 第一个新 release
2025-11-21 03:12 Release v0.8.0
2025-11-21 21:58 Release v0.9.0
2025-11-27 01:33 Release v0.10.0
...
从此进入了"每日多个 release"的状态。
Phase VII：arm 加入 release（2026-06+）¶
叙事：Armin Ronacher（著名 Python / Rust / Flask 贡献者）开始接管 release。Mario Zechner 仍是主开发者，但 release 操作转移到 Armin。
Phase VIII：最近 2 周——agent 文档大重构（2026-08）¶
2026-08-11 13:21 Mario Zechner docs(agent): introduce the three stores before the worked examples
2026-08-11 13:27 ... restructure build order into parallel storage and runtime tracks
2026-08-11 13:35 ... fix broken code fence in crash example
2026-08-11 13:49 ... resolve providers and tools at dispatch, drop lease machinery
2026-08-11 13:50 ... drop historical placement-payload rationale
2026-08-11 13:51 ... clarify register references vs immutable snapshots
2026-08-11 13:53 ... re-mint legacy ids at import, drop redundant register paragraph
2026-08-11 13:55 ... tighten identity section
2026-08-11 14:01 ... reword cancellation triage note
2026-08-11 14:03 ... drop historical changes appendix
2026-08-11 14:11 ... replace historical rationale with direct statements
2026-08-11 14:25 ... consolidate harness spec into harness.md
2026-08-11 14:32 ... one sqlite file per session, search becomes external
2026-08-11 14:43 ... add seq-ranged usage ledger scan
2026-08-11 14:53 ... specify optional pull-based search service
2026-08-11 14:58 ... make search a standalone service, open metadata-filter question
2026-08-11 15:21 ... add table of contents
2026-08-11 15:29 ... consolidate harness spec into harness.md
2026-08-11 14:57 Michael Renner docs: document terminal-specific fullscreen mouse behavior (#7965)
叙事：8月11日一整天，Mario 把 docs(agent) 大规模重构——"one sqlite file per session, search becomes external"、"drop historical rationale"、"drop lease machinery"，这是一个写文档的过程，但其中暗含架构变更（如 sqlite 单文件化、search 外部化）。注意：这些 commit 的真实影响我目前未做深入 diff 阅读。
5.5 贡献者分布¶
| 贡献者 | commit 数 | 角色判定 |
|---|---|---|
| Mario Zechner | 3,292 | 主创 + 主开发者 |
| Armin Ronacher | 515 | release 主导（v0.80 起） |
| github-actions[bot] | 172 | CI 自动化 |
| Christian Klotz | 111 | contributor |
| David Brailovsky | 107 | contributor |
| Cristina Poncela Cubeiro | 107 | contributor |
| Vegard Stikbakke | 95 | contributor |
| Helmut Januschka | 66 | contributor |
| Aliou Diallo | 56 | contributor |
| Sviatoslav Abakumov | 44 | contributor |
5.6 演进总结¶
- ✅ 持续小步快跑：v0.10 之后大致 0.5–2 天一个 release
- ✅ 稳定版本策略：所有子包 lockstep 升号（
scripts/sync-versions.js） - ✅ 无 git tag 范式：所有 version 通过 GitHub Releases；本地 git tag 列表为空
- ✅ TUI 大重构：8/10–11 完成外科手术式 differential rendering
- ✅ agent-core → pi-ai 拆分：第 8 天后独立 ai 包
- ✅ Armin 加入 release：v0.80 起 release 由 Armin Ronacher 提交
- ⚠️ 8 月 11 日 agent 文档大重构：含潜在架构改动，未核实
- ⚠️ 3 个月空白（2025-08 → 2025-11）：仓库活跃、无 release，模式待解释
5.7 未完成的演进问题（建议作为 Phase 9 deep dive 后续）¶
- v0.30 的 "Add automatic session migration for v0.30.0 bug" 实际解决了什么？
- v0.40 → v0.50 → v0.60 → v0.70 的每个 minor 之间的"破坏性变更"具体是什么？
- 最近的 docs(agent) 重构实际涉及哪些代码变更？是否引入新模块？
- "scoped transport" 何时被引入、与什么 GitHub Issue 相关？
- 是不是从 Pi 进入 armature 化？v0.70–0.80 之间是否发生过 RPC 优先 vs Local 优先的架构决策？