b52tot/workbuddy-board

> **WorkBuddy 写的 WorkBuddy 看板 —— 让英雄查英雄。不耽误打游戏了。**
给 MCP Agent 用的桌面任务看板。四列任务常驻桌面，agent 干到哪一步、有没有卡住，
抬眼就能看到 —— 不用切窗口，也不用点开浏览器。
零第三方依赖（只用 Python 标准库），单文件 exe，双击即用。
---
快速开始
1. **打开 exe** —— 下载 BoardWidget.exe，双击运行。
2. **注册 MCP** —— 挂件右下角点 **⚙**，在 **MCP** 那一行点「注册」。
3. **重启 WorkBuddy** —— MCP 配置只在客户端启动时读一次；重启后到**连接器管理页**点「信任」。
4. **开始用** —— agent 干到哪一步、有没有卡住，实时出现在桌面上。
> 不用装 Python、不用部署服务 —— 看板后端和 MCP 端点都打包在这一个 exe 里。
---
特性
| 能力 | 说明 |
|---|---|
| 桌面挂件 | 无边框常驻 + 置顶，可拖动 / 缩放 / 调透明度，收起后变 62px 条形 |
| 任务卡片 | 标题、说明、标签、优先级、自定义字段 |
| 进度条 | 声明 type: "progress" 字段即可，卡片上直接画；进度**只增不减** |
| 停滞检测 | 非终态列 + 超过阈值无任何上报 ⇒ 卡片标黄，顶部给计数 |
| 列分组 | 栏目顺序 / 标题 / 颜色 / WIP 上限全部可配 |
| 状态流转 | 白名单约束，非法流转会报错并提示合法目标 |
| 变更流水 | 每次改动自动记事件，随时可查「谁在何时把什么从哪移到哪」 |
| 存储 | SQLite 单文件，WAL 模式 |
| MCP 工具 | 15 个，agent 可直接读写看板 |
| 网页看板 | 单端口 HTTP，1 秒轮询，深浅色主题 |
---
接入 WorkBuddy
挂件自带「注册 MCP」按钮（上面的第 2 步）。手工接入的话：
**第一步** 准备配置：
**第二步** 编辑 ~/.workbuddy/mcp.json，在 mcpServers 里加一项：
command / args 都用绝对路径，**不需要 cwd** —— 配置文件与 db_path 都按
**代码位置**定位，不由进程 CWD 决定，所以宿主从哪个目录拉起都一样。
> **不要往 env 里塞项目配置。** WorkBuddy 的 MCP 连接指纹把 env 的 key 集合算在内，
> 加 key 会让已授信的 server 退回待授信、下次启动重新弹授权。
**第三步** 重启客户端 → 到**连接器管理页**右上角的「自定义」入口点「信任」。
工具（15 个）
宿主会自动加 mcp__board__ 前缀。
| 工具 | 用途 |
|---|---|
| board_snapshot | 读看板完整快照（列、任务、统计、进度、停滞） |
| board_config | 读当前生效的配置 |
| create_task / update_task / delete_task / get_task | 任务增删改查 |
| list_tasks / list_columns | 按列或标签筛选 / 列出栏目 |
| move_task | 状态流转 |
| update_progress | 推进进度（只增不减、传绝对值所以幂等） |
| list_stalled | 疑似停滞的任务（非终态列 + 超阈值无上报） |
| list_events | 变更流水（支持 since_seq 增量拉取） |
| archive_done / restore_archived | 归档出主视图 / 还原回看板 |
| board_reset | 清空看板（**需显式 confirm=true**） |
---
配置
复制 config.example.json 为 config.json 后修改。**所有键都可省略，省略即用默认值**
（一个配置文件都没有也能跑）。
查找顺序：--config 参数 → 环境变量 WBB_CONFIG → ./config.json。
board
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
| title | string | WorkBuddy Board | 看板标题 |
| db_path | string | ./data/board.db | SQLite 路径，自动建目录 |
| columns | array | 待办/进行中/阻塞/已完成 | 栏目定义，见下 |
| transitions | object | 见示例 | 状态流转白名单 |
| fields | array | [] | 自定义字段 schema |
| enforce_wip | bool | true | 是否强制 WIP 上限 |
| refresh_ms | int | 1000 | 前端轮询间隔 |
| hide_empty_columns | bool | false | 隐藏空列 |
**columns** 每一项：
- id —— 稳定标识。**改了等于换了一列**，旧任务会找不到列，定好别动
- color —— gray / blue / amber / green / red / purple / teal / pink / coral
- wip_limit —— 在制品上限，null 表示不限；超限时迁入会被拒绝
- is_terminal —— 终态列，用于统计完成率。**至少要有一个**
**transitions** —— 未列出的流转会被拒绝，报错里会列出该列允许的目标：
**fields** —— 未在此定义的键不允许写入：
type 取 text / number / enum / bool / progress；
enum 必须给 values，progress 必须给 label。
web
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
| host | string | 127.0.0.1 | 监听地址（默认仅本机） |
| port | int | 8791 | 端口 |
| open_browser | bool | false | 启动时自动开浏览器 |
| allow_write | bool | false | 网页端是否允许写操作 |
> 以 _ 开头的键视为注释、会被忽略；**其余未知键会报错** ——