tower-do — 同项目共享看板 + 跨 session 消息（Pi 扩展）

一个 todo 风格的 Pi 扩展：同一项目里的每个 session 共享一块任务看板，并可以给项目里的其他 session 发消息。

English README

两个功能

并行 coding agent 的问题出在协作，而不是写代码。tower-do 给同一项目里的每个 session 和 subagent 两样东西：

1. 共享 todo 看板。 计划、认领、更新、完成、阻塞任务，带 owner 和依赖。所有 session 读写同一块看板——没有 daemon、没有数据库、没有服务端，只有每个项目一个文件。
2. 跨 session 消息。 给另一个 session 发定向消息（或广播 all），并读取自己的收件箱。消息存在同一块看板上，对方下次查看就能看到，tower_do_status 也会显示未读数。

外加一行编辑器上方 widget（TowerDo 3 open · 1 msg）。

三个工具：

工具	用途
tower_do	一次原子看板更新。tasks 是 upsert 列表（新建或合并补丁），remove 显式删除。用 owner + in_progress 认领，status: "completed" 完成，status: "blocked" + blockedBy 阻塞。baseRevision 会拒绝过期写入，而不是覆盖他人。
tower_do_talk	send 发定向消息（收件人须为 all、tower、当前 task owner，或近期有看板活动的身份；禁止发给自己）；inbox 列出并确认自己的消息。
tower_do_status	共享看板：全部未完成任务（按最近更新）、completed 行的键账目、发给你的消息、活动尾部。taskKey 返回单个任务详情；把它返回的 revision 作为 baseRevision 传回。

安装

方式一 —— npm（推荐）

pi install npm:tower-do

方式二 —— git

pi install git:https://github.com/wweir/tower-do.git@main

方式三 —— 手动复制到全局扩展目录

mkdir -p ~/.pi/agent/extensions && cp -r tower-do ~/.pi/agent/extensions/

Pi 启动时自动发现该扩展；已有 session 用 /reload 生效。

快速上手

一个 session + subagent（典型）。 父 session 在看板上计划任务并指定 owner；把 tower_do_status 返回的看板路径交给 subagent（file-as-state）；它们回报；父 session 收尾。

多个 session、同一项目。 双方读写同一个 ~/.pi/tower-do/<project>/board.jsonl。用 tower_do_talk 发消息，对方在 inbox 里看到（widget / status 里也会显示未读数）。

Upsert，不是重放。 一次写入只列出它新建或改动的行——没提到的 key 保持原样，所以部分写入永远不会删掉别人的任务。删除要显式 remove: ["key"]。

身份解析：as 参数 > config identity > session name > session id。替 subagent 记录工作时传它的 id（例如 as: "coder-1"）。

配置

只有一个可选键——~/.pi/agent/tower-do/config.json（全局，对所有项目生效）。没有环境变量。

{ "identity": "team-orchestrator" }

字段与校验规则见 docs/OPERATIONS.md。

工作原理

每个项目一个 append-only JSONL 文件（~/.pi/tower-do/<project>/board.jsonl）是唯一事实来源——状态与通信是同一份存储。每次读取都重新 fold；写入带单调 revision，因此对方的并发更新会被拒绝而不是被静默覆盖。系统边界、事件语义与派生读取见 docs/ARCHITECTURE.md。

文档

文档	内容
docs/PRODUCT.md	产品范围与高层体验
docs/ARCHITECTURE.md	系统边界、事件日志与 fold、源码布局
docs/CONTRACTS.md	任务模型不变量、owner 守卫、消息契约、revision 门禁、测试门禁
docs/DECISIONS.md	为什么：file-as-state、upsert 写入、owner 守卫、单时钟接管
docs/OPERATIONS.md	安装、配置、发布流程（tag → CI → npm）、排障

质量门禁：bunx tsc --noEmit 加上 docs/CONTRACTS.md 里列出的测试套件，在每次 release tag 上由 CI 强制执行。

License

MPL-2.0。