# @capdiem/pi-todo 中文文档

规范地址：https://npmcn.com/package/%40capdiem/pi-todo/

版本：0\.3\.2
npm 元数据更新时间：2026-09-01T08:11:03.804Z
中文译文更新时间：2026-11-09T05:56:50.824Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capdiem/pi-todo
原文对照：https://npmcn.com/package/%40capdiem/pi-todo/?lang=original
项目主页：https://github.com/capdiem/pi-extensions#readme
源码仓库：https://github.com/capdiem/pi-extensions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：47.9 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@earendil-works/pi-ai \*，@earendil-works/pi-coding-agent \*，@earendil-works/pi-tui \*，typebox \*
- 首次发布：2026-08-27T08:01:56.520Z
- 最新版本发布：2026-09-01T08:11:03.502Z
- 近 30 天下载量：5666（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

用于 Pi 编码器的轻量级原子待办工具: 单调快取计划, 三态, stale- write guard, 外加 TUI 部件和 Pi- agent-desktop 侧边栏面板

## 安装

```sh
npm install @capdiem/pi-todo
```

也可以使用：`pnpm add @capdiem/pi-todo`、`yarn add @capdiem/pi-todo`、`bun add @capdiem/pi-todo`

## README

# pi-todo (英语)

A 类 **轻型**原子待办工具 [Pi 编码代理](https://pi.dev/)。 。 。 . 模型用一个电话写完整的任务计划,而不是发布一个 `create` 调用每个任务.

它故意很小——只是基本的计划维持核心,没有 依赖性或设置菜单,没有倒塌/扩展,而且完全是一个轻量级 提醒( 前端调和微分, 参见 [特征](https://npmcn.com/package/%40capdiem/pi-todo/#readme-features)) (中文(简体) ). 现场计划 将 Pi 输入框上方作为只读的部件,当主机为 [pi - agent - 桌面](https://github.com/abcwyc/pi-agent-desktop) 也出现了 在桌面上 **左向侧边栏** 零额外配置的待办事宜面板 (桌面支持即将到来——见 [桌面集成](https://npmcn.com/package/%40capdiem/pi-todo/#readme-desktop-integration)) (中文(简体) ).

## 特征

-   一次性制定完整的计划(snapshot语义)
-   三种状态: `pending`, (中文(简体) ), `in_progress`, (中文(简体) ), `completed`
-   稳定任务密钥; 基于省略的删除( 否) `cancelled` 或者说 `archived` 状态)
-   `baseVersion` 禁止同时/不定期更新 stale-write
-   最多一个 `in_progress` 一次任务
-   原子验证——一个失败的书写永远不会变异状态
-   完成的待办事宜从不自动删除; 模型会浏览( 省略) 一旦全部工作内容完成
-   国家坚持工具成果细节和生存 `/reload` 财务报告和审定财务报表 `/tree`
-   Pi 输入框上方的仅读部件, 使用 mark- down- style glyphs (单位:千美元)`[ ]` 待定, `[-]` 进取, `[x]` ;无倒塌/扩展
-   **运行端调节提醒( 隐形)**: 当转弯时 (单位:千美元)`agent_settled`) 任务还在 `in_progress`,扩展记录 a 提醒并注入到 **下一回合的系统提示** 通过 `before_agent_start`。请提醒模型标记它们 `completed` 若为 实际工作已经完成—— **没有可见的聊天信息, 没有额外的代理运行, 无需切换**。每转弯最多发射一次,然后跳过 计划没有 `in_progress` 任务,且无法循环(没有向导消息可读) - 继续.
-   当由 pi- agent-desktop 主持时, 即时计划也会在桌面上制作 **左向侧边栏** 待办事宜面板(桌面拥有) `pi-agent-desktop:todo` 部件扩展点)——不需要额外配置

## 安装

此扩展注册 `todo` 工具。 删除任何其他扩展名 拥有同样的 `todo` 安装前的工具名称,例如:

```bash
pi remove <the-other-todo-extension>
pi install npm:@capdiem/pi-todo
```

在不安装的情况下尝试 :

```bash
pi -e ./extensions/pi-todo/index.ts
```

## 工具计划

这个 `todo` 工具接受完整权威的任务列表. 现有任务可能省略未修改的字段;需要新密钥 `subject` 财务报告和审定财务报表 `status`中省略的任何当前密钥 `tasks` 永久删除 :

```ts
todo({
  baseVersion?: number,
  tasks: Array<{
    key: string,
    subject?: string,
    status?: "pending" | "in_progress" | "completed",
  }>,
})
```

示例

```json
{
  "baseVersion": 0,
  "tasks": [
    { "key": "inspect", "subject": "Inspect the existing implementation", "status": "in_progress" },
    { "key": "implement", "subject": "Implement the optimized protocol", "status": "pending" },
    { "key": "verify", "subject": "Verify the implementation", "status": "pending" }
  ]
}
```

要手动工作, 包含每个当前键, 但只发送已更改的字段 :

```json
{
  "baseVersion": 1,
  "tasks": [
    { "key": "inspect", "status": "completed" },
    { "key": "implement", "status": "in_progress" },
    { "key": "verify" }
  ]
}
```

主题从上一个快照继承;两个状态变化都承诺 解剖论.

要取消或删除工作, 请在下一个完整计划中省略其密钥 . 删除是永久的状态去除——没有 `cancelled` 状态或 存档记录.

## 语义

-   `key` 是任务特性,而任务仍在计划中.
-   已存在的密钥继承了先前状态中省略的字段 .
-   新密钥需要 `subject` 财务报告和审定财务报表 `status`。 。 。 .
-   每张密钥 `tasks` 保留在计划中;省略当前键为 永久删除.
-   已完成的任务仍然可见( 穿透) , 直至模型完成 一旦全部工作内容完成,则省略其密钥.
-   `tasks: []` 清除计划.
-   `baseVersion`如果提供,则拒绝 stale 写作.
-   最多一个任务是 `in_progress` 在一个时候.
-   校验为全- 或- 无; 失败的写不突变状态 .
-   使计划不变的写作不会打乱版本.

每一个成功的结果包括目前的版本和完整的计划.

## 渲染

任务列表以 Pi 输入框上方的只读部件提供 。 总是这样 显示完整列表( 不崩溃/ 扩展): 进度头加每个任务 标志下式状态格莱弗. `in_progress` 标签为粗体并已完成的标签 被击中通过。 部件只在计划存在时出现 .

## 桌面集成

由 [pi - agent - 桌面](https://github.com/abcwyc/pi-agent-desktop) (单位:千美元) `rpc` 模式),在桌面中创建的活式计划 **左向侧边栏** 待办事宜面板 — 保留在视图中的聊天旁边的持久复选框列表 当你工作的时候.

计划被推到桌面上 **待办部件扩展点** (由 pi- agent-desktop 定义;参见其 `lib/todo-state.ts` 财务报告和审定财务报表 `docs/todo-widget.md`(单位:千美元) `setWidget` 使用桌面保留密钥请求 `"pi-agent-desktop:todo"`一个JSON `TodoTask` 每个线。 桌面路线 直接进入它的侧边栏待办事宜面板。 火和忘却; 当桌面打开会话时, 此扩展名是 `session_start` 恢复 重现当前计划, 因此面板显示最新的快照 。 图瓦卢 保留其自己的组件部件(见渲染)并保持不变.

> **状态: 桌面侧面板即将到来 .** 待办小组的支持 目前居住在 pi-agent-desktop 的地物分支上,没有 合并成一个发布. `@capdiem/pi-todo` 已经符合 `pi-agent-desktop:todo` 部件协议,所以一旦面板 船你得到 侧边栏渲染 **零额外配置**。 。 。 .

## 持久性

写入存储于工具结果 `details`打开 `session_start` 财务报告和审定财务报表 `/tree` 导航,扩展从活动方恢复最新的有效状态条目 树枝。 (对于后向相容性,它也承认隐藏的遗产) 自动删除的旧版本发布的自定义消息快照 任务。)

此最小扩展名确实 **没有** 处理收紧检查站:如果收紧 减少每个 `todo` 工具来自分支,计划重排为空( 模式本身的背景仍然包含计划文本). 添加压缩处理从 适合您工作流程的全功能待办事宜扩展.

## 许可证

麻省理工学院

## 常见问题

### @capdiem/pi-todo 是什么？

用于 Pi 编码器的轻量级原子待办工具: 单调快取计划, 三态, stale- write guard, 外加 TUI 部件和 Pi- agent-desktop 侧边栏面板

### 如何安装 @capdiem/pi-todo？

在项目目录运行 npm install @capdiem/pi-todo，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@earendil-works/pi-ai（\*）、@earendil-works/pi-coding-agent（\*）、@earendil-works/pi-tui（\*）、typebox（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capdiem/pi-todo 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/capdiem\_\_pi-todo 是否存在。

### @capdiem/pi-todo 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @capdiem/pi-todo 可以商用吗？

@capdiem/pi-todo 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capdiem/pi-todo 的下载量有多少？

根据 npm 官方下载统计，@capdiem/pi-todo 在 2026/10/09 – 2026/11/07 这 30 天内被下载 5,666 次，日均约 189 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capdiem/pi-todo 还在维护吗？

最新版本 0\.3\.2 发布于 2026/09/01（2 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/08/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。