@ilikexiaoni/pi-task-list

通用 Pi 任务清单扩展，用于替代简单的平面 todo 快照。安装本包即可使用，不依赖其他第三方 Pi 插件；运行时仅依赖 Pi 提供的官方 Extension API。

能力

• task_list 工具支持 create、update、list、get 和 clear。
• 任务有 pending、in_progress、blocked、completed、cancelled 状态。
• 每项任务可以记录动作短语、说明、完成条件、证据、优先级、负责人、标签和进度记录。
• blockedBy 表示硬依赖；工具会检查不存在的依赖和循环依赖，并自动阻塞或解除由依赖产生的阻塞；人工阻塞不会被自动解除。
• 每条完成条件至少需要一条 evidence，证据数量不足时不能标记为 completed。
• 普通任务变更只在工具结果中保存紧凑 operation；完整状态仅在 compaction 时写入 task-list-state checkpoint，且按完整状态指纹去重，支持 session reload、tree/fork 和 compaction 后恢复，不会因不同分支 revision 相同而漏写 checkpoint。
• list/get 的工具详情使用有界任务投影，不把完整 evidence、notes 和长字段重复写入 session；完整内容仍通过模型文本输出和 /tasks 查看。task-context-bridge 通过 Pi 标准 context 事件注入短只读摘要，让上下文压缩后仍能看到当前、阻塞和下一步任务；它不修改 Magic Context，也不维护第二份状态。摘要按状态和总长度设上限，不注入完整证据。
• TUI 中显示固定 5 行的紧凑任务 Widget、Footer 状态，以及 /tasks 可展开详细面板。
• 紧凑 Widget 只挂载一次；任务变化时原地更新，内容未变化时不请求重绘。所有行按终端宽度截断，任务再多也不会扩高或换行。
• /tasks 详情使用有界居中面板，窗口大小变化时自动重算视口；fullscreen 模式接收 Pi 归一化鼠标滚轮事件，regular 模式使用跨终端键盘导航，避免依赖 Linux/Windows 各自的原始鼠标序列。
• 工具执行模式为 sequential，避免多个并行调用互相覆盖任务状态。

使用

启动 Pi 后，模型可以直接调用 task_list：

先建立 6 个原子任务，分别写明完成条件；开始第一个任务。

也可以人工查看：

/tasks
/tasks active
/tasks blocked
/tasks 3
/tasks 关键词

未展开时保持固定 5 行：

┌─ TASKS  6/7  ━━━━━━━━─ 86%  进行中 1  阻塞 0
│ ▶ 当前   #7 [H] 正在汇总文件污染与提取建议
│ ○ 下一步 暂无可开始任务
│ ✓ 最近   #6 逐文件归类未提交改动 · 另 5 项已完成
└─ /tasks 完整清单 · 验收条件 · 证据

当存在阻塞时，第三行优先显示最高优先级的阻塞任务及原因；没有阻塞时才显示下一项可执行任务。完整任务、依赖、备注和全部证据仍通过 /tasks 查看。

详情面板导航：

↑↓ / j / k       上下滚动
u / d / Space     上下翻页
Home / End / g/G  跳到开头或结尾
Esc               关闭面板
鼠标滚轮          仅 fullscreen TUI 可用

需要鼠标滚轮时启动 fullscreen TUI：

pi --tui-mode fullscreen

regular TUI 中终端会保留鼠标滚轮用于自己的 scrollback，这是 Pi 宿主的设计边界；插件不会拦截或伪造原始平台鼠标序列。

典型更新：

{
  "action": "update",
  "id": 3,
  "status": "completed",
  "addEvidence": ["定向测试通过：test-command"],
  "completionNote": "已完成并核验"
}

安全和边界

这个 Package 只管理任务状态，不读取数据库、不修改源代码，也不执行部署。clear 要求显式 confirm: true。任务状态的唯一可写来源是 task_list；上下文桥接只读消费摘要。它不修改 coding-agent 宿主层的工具集合；宿主是否额外注入其他任务工具由运行环境决定。安装本 Package 后，支持它的 Pi 会话应使用 task_list 作为唯一任务状态来源。

安装

从 npm 安装：

pi install npm:@ilikexiaoni/pi-task-list

固定版本安装：

pi install npm:@ilikexiaoni/pi-task-list@0.4.3

项目级安装：

pi install -l npm:@ilikexiaoni/pi-task-list@0.4.3

本地开发安装：

pi install "path/to/pi-task-list"

安装后新建会话，或在 Pi 中执行 /reload。如需只使用任务工具而不注入上下文摘要，可在启动 Pi 前设置 PI_TASK_LIST_CONTEXT=0；默认建议保持启用。关闭桥接不会删除任务，只是不再向模型上下文注入摘要。

发布

包名为 @ilikexiaoni/pi-task-list，使用 pi-package keyword，可被 Pi Package Gallery 发现。当前发布版本为 0.4.3。发布前先执行 npm pack --dry-run 检查 tarball 内容，再由已登录的 npm 账号执行 npm publish --access public。

本包不包含测试目录、会话数据或本机配置；发布动作不会由开发脚本自动执行。

验证

运行核心状态机回归测试：

cd "path/to/pi-task-list"
npm test