# pi-durable-book

**Repository Path**: NovemberRain/pi-durable-book

## Basic Information

- **Project Name**: pi-durable-book
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 《pi-durable：持久化智能体运行时》中文手册

> 本书记录了 [`@earendil-works/pi-durable`](https://github.com/earendil-works/pi/tree/main/packages/durable) 的全部文档与示例内容，由英文原版翻译、整理而成。全书内容基于 **v1.3.0**（2026-10-15，当前 npm `latest`）。
>
> **原文声明**：该项目为实验性（Experimental）项目，API 可能在版本间不经通知即发生变更。

## 这是什么

`pi-durable` 是一个**持久化智能体运行框架（durable agent harness）**：对话、模型轮次、工具调用以及你自己的应用状态，在任何内容被展示之前都会先提交到存储。如果进程在某一轮执行中途崩溃，重新打开存储即可从上次中断的地方继续工作。

它构建在两个基础库之上：

- [`@earendil-works/pi-ai`](https://github.com/earendil-works/pi/tree/main/packages/ai) —— 模型访问层；
- [`@earendil-works/chord`](https://github.com/earendil-works/pi/tree/main/packages/chord) —— 文档状态层。

## 全书结构

本书分四篇，与原始仓库的内容一一对应：

| 篇章 | 内容 | 对应原文 |
|---|---|---|
| **第一篇 概述与快速上手** | README 全文中文版：安装、快速上手、27 个主题的使用指南 | `README.md` |
| **第二篇 规范说明书** | Durable 规范全文中文版（13 章，5352 行），按主题拆为 6 节 | `docs/spec.md` |
| **第三篇 设计文档（存档）** | 实现计划、Chord 使用方式、Chord 差异调研 | `docs/pico-v5-handoff.md` 等 3 篇（上游已于 v1.2.0 移除，本篇为 v1.1.0 存档翻译） |
| **第四篇 示例教程** | 32 个可运行示例的中文逐段解读，从会话基础到完整编码智能体 | `test/examples/` |

原仓库的源码与测试未收录在本书中，可在上游仓库 [earendil-works/pi · packages/durable](https://github.com/earendil-works/pi/tree/main/packages/durable) 查阅；书中各篇的「本篇译自」引用块均已链接到对应的英文原文。

## 如何阅读

- **想快速了解能做什么**：读第一篇的"快速上手"，再浏览第四篇的示例 14-19（聊天、流式、打印模式、JSON 模式）。
- **想理解设计原理**：读第二篇规范说明书，配合第三篇实现计划（注意：第三篇为上游已移除的历史文档存档） 。
- **想动手实践**：按第四篇示例教程逐个运行，示例 00-13 讲底层机制（会话、文档、分叉、监听、Harness），示例 14-31 讲完整用法（子代理、压缩、编码智能体、计划模式等）。

## 运行示例

克隆上游仓库后，在其 `packages/durable` 目录下执行：

```bash
node --conditions=source --experimental-strip-types test/examples/14-chat.ts
```

调用 OpenAI 的示例需要设置 `OPENAI_API_KEY` 环境变量；其余示例默认使用 faux（假）模型提供方。

## 目录

### 第一篇 · 概述与快速上手

- [简介与使用指南（README 全译）](book/01-概述与快速上手.md)

### 第二篇 · 规范说明书

- [第 1-2 章 · 术语、不变量与核心记录](book/02-规范说明书/01-术语与核心记录.md)
- [第 3-4 章 · 文档、事务与存储所有权](book/02-规范说明书/02-文档与事务.md)
- [第 5-6 章 · 任务、提交与收件箱](book/02-规范说明书/03-任务与提交.md)
- [第 7 章 · 扩展、钩子、工具与系统提示](book/02-规范说明书/04-扩展与工具系统.md)
- [第 8-9 章 · 内置任务与文档观察](book/02-规范说明书/05-内置任务与文档观察.md)
- [第 10-13 章 · 存储契约、后端与 API 陷阱](book/02-规范说明书/06-存储契约与后端.md)

### 第三篇 · 设计文档

- [实现计划（pico-v5-handoff）](book/03-设计文档/01-实现计划.md)
- [Chord 使用方式（pico-v5-chord-usage）](book/03-设计文档/02-Chord使用方式.md)
- [Chord 差异调研（chord-delta-findings）](book/03-设计文档/03-Chord差异调研.md)

### 第四篇 · 示例教程

**底层机制（示例 00–13）**

- [示例 0 · 会话与对话](book/04-示例教程/00-会话与对话.md)
- [示例 1 · 文档](book/04-示例教程/01-文档.md)
- [示例 2 · 分叉](book/04-示例教程/02-分叉.md)
- [示例 3 · 归属对话](book/04-示例教程/03-归属对话.md)
- [示例 4 · Chord状态](book/04-示例教程/04-Chord状态.md)
- [示例 5 · 监听](book/04-示例教程/05-监听.md)
- [示例 6 · Harness入门](book/04-示例教程/06-Harness入门.md)
- [示例 7 · 配置](book/04-示例教程/07-配置.md)
- [示例 8 · Harness对话](book/04-示例教程/08-Harness对话.md)
- [示例 9 · 上下文](book/04-示例教程/09-上下文.md)
- [示例 10 · 注册表与重载](book/04-示例教程/10-注册表与重载.md)
- [示例 11 · 扩展状态](book/04-示例教程/11-扩展状态.md)
- [示例 12 · 任务](book/04-示例教程/12-任务.md)
- [示例 13 · 恢复](book/04-示例教程/13-恢复.md)

**实战用法（示例 14–31）**

- [示例 14 · 聊天](book/04-示例教程/14-聊天.md)
- [示例 15 · 系统提示](book/04-示例教程/15-系统提示.md)
- [示例 16 · 真实模型](book/04-示例教程/16-真实模型.md)
- [示例 17 · 编码工具](book/04-示例教程/17-编码工具.md)
- [示例 18 · 打印模式](book/04-示例教程/18-打印模式.md)
- [示例 19 · JSON模式](book/04-示例教程/19-JSON模式.md)
- [示例 20 · 收件箱](book/04-示例教程/20-收件箱.md)
- [示例 21 · 中途加入](book/04-示例教程/21-中途加入.md)
- [示例 22 · 前台子代理](book/04-示例教程/22-前台子代理.md)
- [示例 23 · 后台子代理](book/04-示例教程/23-后台子代理.md)
- [示例 24 · 子任务](book/04-示例教程/24-子任务.md)
- [示例 25 · 压缩](book/04-示例教程/25-压缩.md)
- [示例 26 · 编码智能体](book/04-示例教程/26-编码智能体.md)
- [示例 27 · 计划模式](book/04-示例教程/27-计划模式.md)
- [示例 28 · 审查者](book/04-示例教程/28-审查者.md)
- [示例 29 · 每对话沙箱](book/04-示例教程/29-每对话沙箱.md)
- [示例 30 · 工具覆盖](book/04-示例教程/30-工具覆盖.md)
- [示例 31 · 重载与重启](book/04-示例教程/31-重载与重启.md)

> 每个条目对应一个 markdown 文件；完整章节结构另见 [SUMMARY.md](SUMMARY.md)。


## 许可

原项目采用 MIT 许可证。