Workbuddy Board

WorkBuddy Board

WorkBuddy 写的 WorkBuddy 看板 —— 让英雄查英雄。不耽误打游戏了。

给 MCP Agent 用的桌面任务看板。四列任务常驻桌面，agent 干到哪一步、有没有卡住， 抬眼就能看到 —— 不用切窗口，也不用点开浏览器。

零第三方依赖（只用 Python 标准库），单文件 exe，双击即用。

---

快速开始

1. 打开 exe —— 下载 BoardWidget.exe，双击运行。
2. 注册 MCP —— 挂件右下角点 ⚙，在 MCP 那一行点「注册」。
3. 重启 WorkBuddy —— MCP 配置只在客户端启动时读一次；重启后到连接器管理页点「信任」。
4. 开始用 —— agent 干到哪一步、有没有卡住，实时出现在桌面上。

不用装 Python、不用部署服务 —— 看板后端和 MCP 端点都打包在这一个 exe 里。

---

特性

---

接入 WorkBuddy

挂件自带「注册 MCP」按钮（上面的第 2 步）。手工接入的话：

第一步 准备配置：

cp config.example.json config.json

第二步 编辑 ~/.workbuddy/mcp.json，在 mcpServers 里加一项：

{
  "mcpServers": {
    "board": {
      "type": "stdio",
      "command": "C:\\绝对路径\\python.exe",
      "args": ["C:\\绝对路径\\workbuddy-board\\server\\mcp_server.py"],
      "timeout": 120000
    }
  }
}

command / args 都用绝对路径，不需要 cwd —— 配置文件与 db_path 都按 代码位置定位，不由进程 CWD 决定，所以宿主从哪个目录拉起都一样。

不要往 env 里塞项目配置。 WorkBuddy 的 MCP 连接指纹把 env 的 key 集合算在内， 加 key 会让已授信的 server 退回待授信、下次启动重新弹授权。

第三步 重启客户端 → 到连接器管理页右上角的「自定义」入口点「信任」。

工具（15 个）

宿主会自动加 mcp__board__ 前缀。

---

配置

复制 config.example.json 为 config.json 后修改。所有键都可省略，省略即用默认值 （一个配置文件都没有也能跑）。 查找顺序：--config 参数 → 环境变量 WBB_CONFIG → ./config.json。

board

columns 每一项：

{ "id": "doing", "title": "进行中", "color": "blue", "wip_limit": 5, "is_terminal": false }

• id —— 稳定标识。改了等于换了一列，旧任务会找不到列，定好别动
• color —— gray / blue / amber / green / red / purple / teal / pink / coral
• wip_limit —— 在制品上限，null 表示不限；超限时迁入会被拒绝
• is_terminal —— 终态列，用于统计完成率。至少要有一个

transitions —— 未列出的流转会被拒绝，报错里会列出该列允许的目标：

{ "todo": ["doing", "blocked", "done"], "doing": ["todo", "blocked", "done"] }

fields —— 未在此定义的键不允许写入：

[
  { "key": "version",  "type": "text",     "label": "版本号" },
  { "key": "risk",     "type": "enum",     "label": "风险等级", "values": ["低", "中", "高"] },
  { "key": "progress", "type": "progress", "label": "进度" }
]

type 取 text / number / enum / bool / progress； enum 必须给 values，progress 必须给 label。

web

以 _ 开头的键视为注释、会被忽略；其余未知键会报错 —— 避免「改了配置却没生效」这种最难排查的问题。

看板本身不含业务词汇。examples/config.custom-columns.json 演示了把它改成 发布流程看板（六个列 + 专属流转 + 五个字段），不用改一行代码。

---

从源码跑

需要 Python ≥ 3.10，无需安装依赖。

git clone https://github.com/b52tot/workbuddy-board.git
cd workbuddy-board
cp config.example.json config.json

python examples/demo_seed.py        # 可选：灌一份示例数据
python -m server.web_server         # 网页看板 → http://127.0.0.1:8791

让它常驻（前台进程关终端就停）：

python svc.py start | status | restart | stop

status 除了探活，还会核对「运行中的库」与「配置期望的库」是否一致 —— health 200 只证明有东西在监听，不证明用的是你要的那个库。

挂件本身（需要 pip install pywebview）：

python widget/host.py

跑测试：

python -m pytest tests -q                  # 数据层
python -m server.mcp_server --selftest     # MCP 协议自检（不碰数据库）
python widget/fulltest.py                  # 界面全功能测试（先跑 widget/make_inline.py）

用 Docker 跑 MCP server

零依赖，所以镜像里没有 pip install 这一步。主要给两类场景：跑在隔离环境里， 以及让 Glama 这类目录站自动做一次「能起来、能应答」的检查。

docker build -t workbuddy-board .
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
  | docker run -i --rm workbuddy-board

容器里的 config.json 直接来自 config.example.json（不另写一份，避免两处漂移）， 库落在 /app/data/board.db。要持久化就 -v wbb-data:/app/data。 网页界面不包含在这个镜像里 —— MCP server 用不到它。

---

项目结构

workbuddy-board/
├── board/                  数据层（唯一写入方，纯标准库）
│   ├── config.py           配置加载 + 校验
│   ├── models.py           数据模型与状态机校验
│   ├── store.py            ★ 所有写操作的唯一入口，自动登记事件
│   └── schema.sql          建表语句
├── server/
│   ├── mcp_server.py       MCP stdio 工具（手写 JSON-RPC，不依赖 mcp SDK）
│   └── web_server.py       HTTP 看板
├── web/                    展示层（无构建步骤）
├── widget/                 桌面挂件（pywebview）
│   ├── host.py             宿主进程：窗口 / 托盘 / 日志
│   ├── widget.js  widget.css
│   └── boardwidget.spec    PyInstaller 打包配置
├── examples/               最小配置 / 换业务示例 / 示例数据
├── tests/                  数据层 + HTTP 契约 + MCP 协议 + 挂件状态
└── svc.py                  服务管理：脱离会话启动 / 停止 / 探活

所有写操作都收敛到 board/store.py，且每次写都登记一条事件 —— 于是任何时刻都能回答「这个任务是怎么走到现在这一步的」。

---

常见问题

能看到页面但一直是空的？ 确认 db_path 指向的库和灌数据的库是同一个。

移动任务报「不允许从 X 流转到 Y」？ 流转规则在 board.transitions，报错信息会列出该列允许的目标。

报「不是合法的配置项」？ 拼写错误。看报错里的可用键列表；注释请用 _ 开头。

想看某个任务是怎么一步步走到现在的？ GET /api/events?task_id=<id>，或在网页上点开卡片看「变更流水」。

---

更新日志

见 CHANGELOG.md。

---

许可

MIT，见 LICENSE。