pi-durable-dev-rules

本技能是面向开发者的参考文档，用于在 Pi Durable 持久化智能体框架（@earendil-works/pi-durable）与 pi-ai 模型层上编写或评审代码。该框架将对话、模型轮次、工具调用、任务和自有文档在展示前提交到存储，进程中途死亡可从断点续跑。它位于 pi 单仓库，与 @earendil-works/pi-ai（模型访问、工具、消息）和 @earendil-works/chord（受跟踪 JSON 状态）并列。注意：该 API 为实验性，1.2.0 跟随单仓库，每次发布都可能有破坏性变更，应以所安装版本为准；它是用于构建智能体应用的库，不是编码智能体 CLI，Pi CLI 请用同系列 pi-dev-rules。适用场景包括：导入上述包的代码编写与评审、装配 harness（存储后端、HarnessOptions、设置、注册表、执行环境）、对话的提交/等待与忙碌收件箱、工具 TypeBox 模式与三种输出通道、持久化任务的阶段与检查点、子智能体与子任务、文档作用域与迁移、代码模式、钩子与守卫、压缩、运行时问题排查、扩展 harness（存储后端与执行环境一致性测试）。安装命令：npm install @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord；可用 node --conditions=source --experimental-strip-types app.ts 直接运行 TS。参考文件索引：durable-guide.md（快速开始与概念，建议先读）、durable-api.md（精确公开接口）、durable-runtime.md（实际执行方式）、durable-recipes.md（安装与 19 个配方）、durable-spec.md（Pico5 规范），以及 pi-ai-models.md、codemode-sandbox.md。核心硬规则：写入只经一条提交线，提交落库前不展示；提交回调内只经 tx 读取，先读后写，禁止在其中 await 慢操作；每次异步调用需 Context，取消它只取消该调用而非持久工作；先提交意图、执行副作用、再提交结果，步骤须幂等并用 runtime.memo()；工具的输出通道为 output、structuredOutput、details；每个工具调用都是归属调用者的持久任务；所有权决定生命周期，abort 向下流动；不要用裸 tx.appendEntry() 追加到有活跃运行的对话；pi. 前缀名称属于内建，不要复用；存储错误会终止 harness，需重开并复用 requestId 重新提交；文档按 kind 寻址，版本迁移限制见规范。提示：确切的 API 签名、默认值与运行示例，请以已安装版本和 references/ 内文件为准；本资料未提供价格、平台支持范围与效果承诺。