[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83046":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":9,"languages":9,"totalLinesOfCode":9,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":14,"stars7d":15,"stars30d":16,"stars90d":13,"forks30d":13,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":13,"starSnapshotCount":13,"syncStatus":14,"lastSyncTime":26,"discoverSource":27},83046,"pi-docs-playbook","enderzcx\u002Fpi-docs-playbook","enderzcx","A docs navigator and agent-readable playbook for building on earendil-works\u002Fpi",null,126,11,99,0,2,13,27,8,3.24,false,"main",true,[],"2026-06-12 02:04:30","# pi-docs-playbook\n\n一个给人和 coding agent 用的 [`earendil-works\u002Fpi`](https:\u002F\u002Fgithub.com\u002Fearendil-works\u002Fpi) 文档导航器。\n\n它不是 pi 教程，也不是 pi 的 fork。\n\n它更像一个 **documentation harness \u002F docs navigator**：把 pi 的 Markdown 文档镜像下来，重新分类，并告诉 Codex、Claude、Cursor 或 Claude Code 在不同开发问题下应该读哪些文档。\n\n核心目标很简单：\n\n> 在让 AI 基于 pi 写 agent 之前，先让它把 pi 文档读对。\n\n## 来源\n\n- 上游仓库：[`earendil-works\u002Fpi`](https:\u002F\u002Fgithub.com\u002Fearendil-works\u002Fpi)\n- 当前镜像 commit：[`f429ddb`](https:\u002F\u002Fgithub.com\u002Fearendil-works\u002Fpi\u002Ftree\u002Ff429ddb)\n- 镜像日期：2026-06-01\n\n## 这个 repo 解决什么问题\n\npi 文档不是没有，而是密度很高。\n\n如果你直接把 pi repo 扔给 coding agent，它很容易：\n\n- 凭记忆猜 pi 的行为\n- 漏读关键文档\n- 把 SDK、RPC、extension、session、compaction 混在一起\n- 分不清 “pi 已经提供什么” 和 “你的应用必须自己设计什么”\n\n所以这个 repo 做的事情不是替代官方文档，而是给官方文档加一层可导航的阅读路线。\n\n## 目录结构\n\n- [`AGENTS.md`](AGENTS.md)：给 coding agent 的使用规则。Agent 进入这个 repo 后应该先读它。\n- [`PROMPT.md`](PROMPT.md)：可以直接复制给 Codex \u002F Claude \u002F Cursor 的提示词。\n- [`source\u002F`](source\u002F)：原样镜像上游 pi 文档相关 Markdown 文件，保留原始路径。\n- [`catalog\u002F`](catalog\u002F)：按主题和用途整理的文档索引。\n- [`usage\u002F`](usage\u002F)：说明如何把这个 repo 当成 pi 文档参考库使用。\n- [`examples\u002F`](examples\u002F)：可以直接问 agent 的示例问题。\n- [`skill-draft\u002F`](skill-draft\u002F)：未来 skill 的草案，不是可安装 skill。\n\n`source\u002F` 目录刻意保留上游路径，方便精确引用。除非你明确要更新镜像，否则不要手动修改 `source\u002F` 里的文件。\n\n## 文档分类\n\n- [Official coding-agent docs](catalog\u002Fofficial-coding-agent-docs.md)\n- [Core runtime and harness docs](catalog\u002Fcore-runtime-and-harness.md)\n- [Examples and reusable patterns](catalog\u002Fexamples-and-patterns.md)\n- [Upstream prompts and skills](catalog\u002Fupstream-prompts-and-skills.md)\n- [Validation fixtures and changelogs](catalog\u002Fvalidation-fixtures-and-changelogs.md)\n\n## 怎么用\n\n先读：\n\n- [usage\u002Fhow-to-use-this-repo.md](usage\u002Fhow-to-use-this-repo.md)\n- [usage\u002Ftask-reading-matrix.md](usage\u002Ftask-reading-matrix.md)\n\n如果你是人类使用者：\n\n1. 打开 [PROMPT.md](PROMPT.md)\n2. 把这个 repo 交给你的 coding agent\n3. 从 [examples\u002F](examples\u002F) 里挑一个问题开始问\n\n如果你是 coding agent：\n\n1. 先读 [AGENTS.md](AGENTS.md)\n2. 再读 [usage\u002Ftask-reading-matrix.md](usage\u002Ftask-reading-matrix.md)\n3. 根据用户问题判断任务类型\n4. 只读取相关的 `source\u002F` 文件\n5. 回答时引用本地 `source\u002F...` 路径\n6. 不要把 `skill-draft\u002F` 当成正式规范\n\n## 典型问题\n\n你可以这样问你的 agent：\n\n- “我要基于 pi 做一个应用，SDK 和 RPC 应该选哪个？”\n- “我要写一个会修改业务数据的 tool wrapper，应该先读哪些 pi docs？”\n- “我想写一个 pi extension 拦截危险 tool call，怎么开始？”\n- “pi session JSONL 已经记录了 trace，我还需要自己的 application audit log 吗？”\n- “这个 repo 未来怎么整理成一个真正的 skill？”\n\n对应模板在 [examples\u002F](examples\u002F)。\n\n## 更新镜像\n\n```bash\ngit clone --depth 1 https:\u002F\u002Fgithub.com\u002Fearendil-works\u002Fpi.git \u002Ftmp\u002Fpi-docs-read\ncd pi-docs-playbook\nrsync -a --prune-empty-dirs \\\n  --include='*\u002F' \\\n  --include='*.md' \\\n  --include='*.mdx' \\\n  --include='packages\u002Fcoding-agent\u002Fdocs\u002Fdocs.json' \\\n  --include='packages\u002Fcoding-agent\u002Fdocs\u002Fimages\u002F***' \\\n  --exclude='*' \\\n  \u002Ftmp\u002Fpi-docs-read\u002F source\u002F\n```\n\n更新后记得刷新 README 里的 commit hash，以及 catalog 里的链接。\n\n## 推荐阅读顺序\n\n如果你想基于 pi 开发 agent application，优先读：\n\n1. `source\u002Fpackages\u002Fcoding-agent\u002Fdocs\u002Fextensions.md`\n2. `source\u002Fpackages\u002Fcoding-agent\u002Fdocs\u002Fsdk.md`\n3. `source\u002Fpackages\u002Fcoding-agent\u002Fdocs\u002Fsession-format.md`\n4. `source\u002Fpackages\u002Fcoding-agent\u002Fdocs\u002Fcompaction.md`\n5. `source\u002Fpackages\u002Fcoding-agent\u002Fdocs\u002Frpc.md`\n6. `source\u002Fpackages\u002Fagent\u002Fdocs\u002Fagent-harness.md`\n7. `source\u002Fpackages\u002Fagent\u002Fdocs\u002Fdurable-harness.md`\n8. `source\u002Fpackages\u002Fagent\u002Fdocs\u002Fhooks.md`\n9. `source\u002Fpackages\u002Fagent\u002Fdocs\u002Fobservability.md`\n\n## 设计提醒\n\npi session JSONL 是 agent trace，不是你的 application domain audit truth。\n\npi 可以帮你处理 agent loop、tool calling、session、extension、RPC、TUI 等底层能力。\n\n但业务状态机、审批、幂等、审计、异常补偿、domain rules，仍然必须由你的应用自己设计。\n\n这也是为什么需要这个 repo：让 agent 先读对文档，再开始设计你的 harness。\n","pi-docs-playbook 是一个文档导航器，旨在帮助开发者和编码代理更有效地理解和使用 earendil-works\u002Fpi 项目。其核心功能包括将 pi 项目的 Markdown 文档进行镜像、重新分类，并为 Codex、Claude 等 AI 编码助手提供详细的阅读指南。通过这种方式，它确保了这些工具在基于 pi 构建应用前能够准确地理解相关文档。特别适用于需要深入掌握 pi 项目特性的场景，比如开发基于 pi 的应用程序或扩展时，可以帮助用户避免常见的误解和遗漏，从而提高开发效率。","2026-06-11 04:10:00","CREATED_QUERY"]