WorkBoard

<div align="center"> # 工作面板 ### 用户和代理的实时工作面板 **观察你的工作成果 — 永不丢失创意，永不丢失工作流程。**       </div> --- ## 快速开始 在 Claude Code 中从插件市场安装： ``` /plugin marketplace add malcolm1232/WorkBoard /plugin install board-steward@workboard ``` 更喜欢从源代码安装？使用 `git clone` 并运行 `./install.sh` — 相同的结果，无需市场步骤： ```bash git clone https://github.com/malcolm1232/WorkBoard cd WorkBoard ./install.sh # 设置 + 自动检测项目并启动面板 ``` **要求：** Claude Code · Python 3.9+（仅标准库，无需 `pip install`）· macOS / Linux / Windows。 **无需账户，无需云，无需 API 密钥。** （历史重放的可选启动使用 Claude Haiku — 最便宜的层级 — 作为一次性、独立的子进程。） --- ## 问题 | # | 问题 | WorkBoard 如何解决它 | |---|---|---| | 1 | **代理内存仅对代理可见 — 对你不可见。** | WorkBoard 是一个 **用户和代理的视觉知识图谱** — 你可以将工作实时显示为面板；代理会遍历相同的图谱。 | | 2 | 我们 **无法跟踪代码。** | WorkBoard **实时跟踪 Claude 的工作** 以及它刚刚交付的内容 — 无需你输入任何内容。 | | 3 | 你 **产生想法的速度** 快于你能实施的速度。 | 立即创建卡片 — 作为卡片或子任务。稍后，只需说 *"执行 #426"* — 或链接它们： *"执行 #426、#123 和 #99。"* 每个卡片都从其停止的地方继续。 | | 4 | 你完成的工作比以往任何时候都多 — 但 **你如何记住交付了什么，为什么，哪些文件？** | 每个卡片都有一个 **标题** （概要）和 **简短描述**；更深入的工作（子任务、编写、文件、提交）作为叶节点悬挂。未来的 Claude 读取一个小摘要，然后 **仅遍历它需要的叶节点** — 回答 "五月在 OAuth 上做了什么？" 只需花费几个代币，而不是重新阅读每条聊天记录。 | ## 工作流程 1. **每个任务都被捕获。** 在开始任何工作之前，请求被捕获为 **任务** 列中的卡片。 2. **立即了解 Claude 正在处理的内容。** 当 Claude 开始处理时，卡片会立即进入 **进行中** 并闪烁 — 这样你可以在一 glance 上看到 Claude 当前正在处理哪个卡片。 *同时处理多个项目？WorkBoard 知道哪个面板属于哪个项目，并相应地更新每个面板。* <img src="docs/assets/inprogress-pulsating.gif" width="360" alt="卡片在进行中列中闪烁 — 一 glance 上可以看到 Claude 当前正在处理哪个任务，即使运行多个会话"> 3. **交付 → 完成，并附带说明。** 完成后，Claude 编写 **交付内容**、**问题原因** 和 ✓ **解决方法** 的说明。卡片飞到完成。 4. **错误？返回进行中。** 如果出现问题 — 或需要更多更改 — 卡片会动画 **返回进行中**，并带有 `🐞 错误` 标签，或添加子任务。 5. **重新交付 → 完成。** 修复后，卡片返回完成 — 保留完整的交付 → 错误 → 修复 → 交付历史记录 **，可供遍历。** --- ## 功能 ### 1. 🏷️ 按标签筛选 — 快速找到所需内容 创建卡片时，它会自动标记为所属的工作类型（例如 `UI`、`安全`、`错误`、`重构`）。单击任何标签芯片即可将面板筛选为仅该部分 — 回答 *"当前 UI 方面有什么问题？"* 只需单击一下。 <img src="docs/assets/tags-filter.gif" width="320" alt="单击标签芯片将面板筛选为仅包含带有该标签的卡片 — UI、安全、错误等"> ### 2. 📅 日历视图 查看交付的内容 — 以及 **仍未完成** 的内容 — 按日期排列。可以查看昨天遗漏的工作，找出生产力激增的日子，或回顾一周的工作成果！您还可以使用它向老板展示您是一个多么尽职尽责的学生（或不是）。  ### 3. ✅ 子任务跟踪实际工作，逐步完成 **实时勾选。** 每个卡片分解为代理实际采取的步骤。子任务会随着进度逐一勾选 — 因此，即使在任务中途，您也可以看到 Claude 的进度（例如 *2/4*），而不仅仅是 *"进行中"。*  **卡片解剖。** 子任务只是其中一个槽。以下是从标题悬挂的每个字段： - **来源** — 用户用自己的话解释为什么存在该卡片。 - **子任务** — Claude 将采取（或已经采取）的具体步骤，逐一勾选。 - **备注** — 过程中记录的任何内容（推理、死胡同、决定）。 - **标签** — 工作类型芯片（`UI`、`安全`、`性能`、`基础设施`、`文档`、`错误`、`重构`…）— 单击任意芯片进行筛选。 - **优先级** — 角落里的 `C` / `M` / `L` 芯片（关键 / 中 / 低，或未设置）。 - **链接文件** — 卡片创建时自动附加到 Claude 编辑的文件。双向遍历：从卡片 → 哪些文件，从文件 → 哪些卡片触摸它。 - **链接卡片** — 相关工作之间的显式 `card.py link <a> <b>` 边。 - **说明** — 当卡片飞到完成时添加：交付了什么，为什么，以及如何验证（提交、文件、测试）。  ### 4. `🐞 错误` — 卡片飞回完成，保留完整的历史记录 **调试？** 当您（或 Claude）工作时，它会动画返回进行中，并带有 `🐞 错误` 标签和新的子任务用于修复。卡片的历史记录显示整个交付 → 错误 → 修复 → 交付弧线，**因此故事永远不会丢失。** <img src="docs/assets/bug-to-and-fro.gif" width="480" alt="卡片从完成移动到进行中，带有错误标签，修复后返回完成"> --- ## 📊 代币效率总结 — WorkBoard 与 mem0 · claude-mem · Letta · graphify ### 为什么 WorkBoard 更便宜？ 1. **卡片记录是内联的 — 零额外模型调用。** WorkBoard 在您的正常回合期间编写卡片：代理运行确定性 `card.py` 命令，说明是它已经生成的文本 — **无需单独的会话，无需额外的推理传递。** mem0、claude-mem 和 Letta 相比之下会启动一个 **专用模型调用** 来记住（claude-mem 压缩 **每个** 会话，通过约 5K 代币调用）— 纯粹的开销在您的正常使用之上。 2. **它不适用于每个回合。** 与 Letta（每个回合重新发送内存）和每个会话的提取器不同，WorkBoard 仅在有内容记录时写入 **。 3. **没有“完整转储”。** 即使在记录时，它也从不转储您的整个历史记录 — 它仅写入 **需要的内容**，因此它永远不会烧掉额外的代币。 4. **它保存的内容是有结构的，而不是一个 blob** — 每个卡片都带有： - **标题** — 一个单行概述，用于快速未来检索 - **来源 / 原因** （+ **备注**）— 背后的上下文 - **✓ 说明** — 完成后， *如何* 完成（提交、文件） 5. **回忆是一种廉价的树遍历。** 代理通过遍历图找到过去的工作流程 — 先读取 **标题**，然后仅在需要时读取描述 → **来源 / 原因** → **如何完成** — 几代代币，从不重新阅读所有内容。 *[**在此阅读完整研究报告 →**](Research/token_comparison/MASTER_SUMMARY.md)* **工作原理：** WorkBoard 的数字是 **测量的** （其真实回忆 + 真实启动，对抗真实 Claude-Code 历史的冻结快照）；每个同行来自其自己的发布数字或真实的沙盒运行。 **行代表什么：** - **构建内存** — 将您的 **过去** 历史记录转为内存的一次性成本。 - **持久化 / 会话** — 持续保存每个新会话工作的成本。 - **实时循环 *(100 会话 × 3 次回忆)* ** — 持久化 **+** 召回在项目生命周期中的组合；实际的稳态成本。 - **单个召回** — 代币用于回答 **一个** 问题。 - **与完整上下文 *(26K)* 的回忆对比** — 与粘贴整个 ~26,000 代币历史记录到每个提示的节省（mem0 的 *"90%"* 是针对的基准） - *(Letta)* **上下文内存 / 回合** — 每个回合 **都会发送** 内存 · *(graphify)* **始终在线 / 提示** + **SKILL.md 启用** — 每个提示和启用时的加载。 ### WorkBoard 与 mem0 | 轴 | WorkBoard (WB) | mem0 | 获胜者 | |---|--:|--:|:--| | 构建内存 | 64,162 代币 | 5,095,769 代币 | 🟢 **WB 98.7% 更便宜** | | 持久化 / 会话 | **0 模型调用** | 1 个 LLM 提取调用（~5,462 代币）+ 嵌入 | 🟢 **WB（免费）** | | 实时循环 *(100 会话 × 3)* | 719,700 代币 | 1,086,200 代币 | 🟢 **WB 便宜 33.7%** | | 单次召回 | 2,399 代币 | 1,800 代币 | mem0 *(更轻量)* | | 回忆 vs 完整上下文 *(26K)* | 90.8% 更少 | 93.1% 更少 | 约等于 | ### WorkBoard 与 claude-mem | 轴 | WorkBoard (WB) | claude-mem | 获胜者 | |---|--:|--:|:--| | 构建内存 | ~10,546 代币 | 5,095,769 代币 | 🟢 **WB ~99% 更便宜** | | 持久化 / 会话 | **0 模型调用** | 1 次压缩调用 *(完整层级)* | 🟢 **WB（免费）** | | 实时循环 *(100 会话 × 3)* | 719,700 代币 | 1,517,300 代币 | 🟢 **WB 便宜 52.6%** | | 单次召回 | 2,399 代币 | 3,237 代币 | 🟢 **WB 便宜 25.9%** | | 回溯过去的历史 | 挖掘您的历史记录 | 仅向前 *(无批量命令)* | 🟢 **WB** | ### WorkBoard 与 Letta（MemGPT） | 轴 | WorkBoard (WB) | Letta | 获胜者 | |---|--:|--:|:--| | 上下文内存 / 回合 | 306 代币 *(0 携带)* | 3,444 代币 *(块 + 工具模式 + 提示)* | 🟢 **WB** | | 持久化 / 会话 | **0 模型调用** | LLM 工具调用 + 压缩 | 🟢 **WB** | | 实时循环 *(100 × 50 × 3)* | 2,259,400 代币 *(929,400 修剪)* | 11,909,200 代币 | 🟢 **WB 便宜 81.0%** | | 单次召回 | 2,399 代币 | 1,064 代币 | Letta *(更轻量)* | ### WorkBoard 与 graphify *(代码知识图谱 — 不同领域)* | 轴 | WorkBoard (WB) | graphify | 获胜者 |---|--:|--:|:--| | 始终在线 / 提示 | 306 代币 | 61 代币 *(缓存)* | graphify | | SKILL.md 启用 | 5,898 代币 | 8,245 代币 *(+9,704 引用)* | 🟢 **WB 便宜 28.5%** | | 召回 | 2,399 代币 *(工作问题)* | 1,374 代币 *(代码问题)* | 不同问题 | | 编写 / 保持当前 | 0 | 0 | 平局 | > *WorkBoard 的“构建内存”数字根据收集配置（每小时桶大小）而变化 — 两者显示的都是 **低于 1.3% 的同行** 会话压缩总计，因此 **减少 %** 是稳健的数字。 130KB+ `board.json` **永远不会自动加载** — 上下文保持干净，无论面板增长多大。 --- ## ⚖️ 但缺点是什么？ WorkBoard 更便宜，因为它 **只记录记录的内容** — 结构化 **结果** （交付了什么，为什么，如何）， **不是您的整个原始对话**。这是一个真正的权衡: - **它无法回忆从未记录的内容。** 如果详细信息仅在聊天中存在，从未写入卡片，则面板不保留。在我们的 20 个问题测试中，**1 是面板外事实** WorkBoard 无法回答 — 向量存储可以。 - **对于模糊或单个事实召回，向量存储可以胜出。** mem0 / Letta 注入每个查找的小型包，而向量存储可以浮现那些从未明确记录的内容。WorkBoard 胜利的是 **循环** 和 **多卡生命周期** 问题， **不是每个单独的查找**。 - **它需要卡片记录的流程，它需要一个项目范围的范围** — 不是跨项目的内存。 **所以运行两者。** WorkBoard 是结构化的项目分类账；将它与向量内存（mem0、claude-mem、Letta）配对，用于模糊的 *"我曾经对 X 说过什么？"* 回忆它不试图涵盖的内容。它们是互补的，而不是替代品。 --- ## 底层 ### 🔒 钩子强制执行 — 板块实际上不会漂移 四个 Claude Code 钩子让代理在实时情况下保持诚实，因此跟踪不是代理应该做的事情 — 而是发生的事情： | 钩子 | 触发 | 做什么 | |---|---|---| | **会话启动** | 会话启动 | 注入约 220 个代币的板块摘要；如果端口已死，则重新生成服务器。 | | **用户提示提交** | 每个提示 | 重新注入实时生命周期协议，以便在发生时记录工作，而不是在结尾批量处理。 | | **预工具使用** | 在编辑/写入之前 | 非阻塞提示 — 即将编辑没有正在进行的卡片的文件？“先声明一个卡片。” | | **停止** | 代理结束其回合 | 已实际编辑但未运行 `card.py`？它记录空白，以便下一个会话协调。 默认情况下提供建议（0 代币，不可见）；选择加入严格模式强制执行相同的回合记录。 | 净效应：**用户永远不必询问“您是否更新了板块？”** — 这个问题正是 WorkBoard 存在的失败模式。 ### 核心组件 - **`127.0.0.1:7891` 上的本地板块服务器** — 纯 Python 标准库，无框架，无依赖。提供动画 UI、实时 SSE 事件流（`/events`）和微小的 REST 表面（`/progress`、`/health`、`/rev`）。由 `launchd`（macOS）/ `systemd`（Linux）/ 任务计划器（Windows）自动管理；如果服务器崩溃，会话启动钩子会重启它。 - **`board.json` — JSON 中的知识图谱，而不是向量数据库** — 单个文件，每个项目；卡片（节点）+ 历史记录/子任务/链接（有类型的边）。原子写入通过跨进程 `flock`，滚动的 `.backups/` 目录每次写入时都会滚动。故意选择而不是 SQLite/Chroma：它可读、可区分、可复制粘贴到不同机器，并且 git 友好。 130KB+ 文件 **永远不会自动加载** — Claude 读取约 220 代币的摘要，然后仅遍历它需要的卡片。 - **`card.py` — 单一规范写入路径** — `add`、`fly`、`subtask`、`bug`、`improve`、`show`、`list`、`query`、`digest`。钩子强制执行其使用；尝试直接编辑 `board.json` 的代理会被停止后备措施捕获并在下一个会话中显示。 - **实时 SSE 更新** — 每次写入都会广播类型化的事件（`card-added`、`card-updated`、`card-removed`、`card-flash`、`column-*`、`rev-bumped`）。所有打开的浏览器标签页和 Claude 会话都会实时同步，**无需轮询**。 - **多 Claude、多板块、多标签页** — 每个 Claude 会话打开一个绑定 `?sid=` 的标签页。每个标签页都会脉动其 **自己的** 活动卡片（`state.activeWork = {sid: {cardId, ts}}`）：N 个并发会话 = N 个并发脉动，无需争夺单个“当前任务”。端口注册表跟踪哪个板块属于哪个项目；**修订版 CAS** (`#609`) 防止两个会话同时写入同一张卡片时发生更新丢失。 - **强化：建议默认，严格按需** — 停止钩子的签收后备措施是无声和免费的（0 代币，仅写入备注）。高级用户可以选择 `BOARD_STEWARD_STRICT=1` — 相同的回合执行，循环代理返回卡片以确保在回合结束前记录。 - **历史重放 — 将过去的工作飞速加载到板块上** — 在第一次运行期间，一个分离的 **Haiku** 子进程（最便宜的层级）挖掘您的过去 Claude Code 会话记录，并将它们重建为卡片，按照 `task → in-progress → done` 飞速加载到板块上，并带有 bug-bounces。独立运行，因此它永远不会进入交互式会话的上下文。 - **崩溃安全** — 通过 `flock` + 滚动备份 + `recover` CLI 恢复任何备份；`repair-links` 修复损坏的跨卡片引用；`migrate` 演化模式。三个月后，您的板块自我修复。 - **代币廉价** — 设计为 **构建和维护中最便宜的**：**0 模型调用** 来持久化您的工作，以及 130KB+ `board.json` **永远不会自动加载** 到上下文中。参见 [`docs/TOKEN_BUDGET.md`](docs/TOKEN_BUDGET.md) 了解测量结果，以及 [`docs/COMPARISON.md`](docs/COMPARISON.md) 了解知识图谱与内存存储框架。 --- ## 可选安装 **首次运行时**，WorkBoard 会读取您最近的 Claude Code 会话历史，以确定您正在处理的内容，然后 **提示您选择要构建的板块**。默认情况下，**它会回溯 2 天**。您可以要求更广泛的窗口 — 例如 *"从过去 7 天构建一个板块"* — 来提取 N 天的历史记录。 > ⚠️ **不建议深入挖掘。** 您深入挖掘的越多，它找到的工作就越多 — 而且您可能会最终 **卡片泛滥**。默认情况下保持保守的 **2 天**，因为有这个原因；如果您确实想要更大的回溯，请将其拓宽。 --- ## 了解更多 - [`docs/KEY_FEATURES.md`](docs/KEY_FEATURES.md) — 完整的特性介绍 - [`docs/TOKEN_BUDGET.md`](docs/TOKEN_BUDGET.md) — 测量的代币成本 vs. 对等内存工具 - [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) — 仓库布局、内部结构和贡献 - [`CHANGELOG.md`](CHANGELOG.md) — 版本历史记录 --- ## 许可 WorkBoard 采用 **Apache 许可 2.0**。 Apache-2.0 是有意选择的。WorkBoard 不是一个独立的应用程序 — 它嵌入到您的开发工作流中，位于其他人的存储库中，作为 Claude Code 插件运行，这些生产工具可能依赖于它。对于这样的基本功能，像 MIT 缺乏的 **专利授予** 这样的显式专利授予（Apache-2.0 提供）是更负责任的默认选择：贡献者不能稍后声称他们发布的代码的专利，对下游用户来说是明确的、企业友好的许可，在开发工具生态系统中被广泛接受（MCP 服务器、IDE 插件、代理套件）。 它仍然是一个宽容的许可 — 允许商业使用、修改和重新分配，同时保留属性。 参见 [`LICENSE`](LICENSE) 了解完整文本。WorkBoard 在您的机器上运行 100%；您的板块和聊天记录永远不会离开它。