Board Planner

看板规划

一块看板，团队协作，Agent 也参与其中。

小团队真正用得起来的看板、冲刺和仪表盘——还提供 MCP 服务和 REST API，让编码 Agent 按照与所有人相同的规则领取相同的任务。

大多数任务跟踪工具都是后来才加上自动化：机器人发表评论，脚本移动卡片，而看板看不到的地方才是真正的工作状态。Board Planner 则从另一个方向出发。看板、REST API 和 MCP 服务是进入同一模型的三扇门，背后执行相同的权限检查。Agent 将任务移至 In Review 时，遵循的状态规则与手动拖动卡片的人相同，也会在同一历史记录中留下相同的轨迹。

云端或自托管

使用云端服务时，注册会在 board-planner.com 的专属子域名下创建一个新组织。新组织会获得 30 天 Pro 试用期，无需绑定银行卡；试用结束后转为 Free 方案——最多 10 名成员、无限项目和任务、REST API、MCP 服务，以及可在一台机器上运行的工作进程和 Agent；也可选择 Pro 方案，享有更多成员、不限机器数量、使用我们密钥的每月 AI 额度和 Coda 同步。Agent、工作进程和 API 令牌都不计为成员。

在自己的服务器上，运行 docker compose up 即可创建一个属于自己的组织。Community 版本采用 AGPL-3.0，没有成员或机器数量限制，AI 功能使用你自己的密钥；可自托管的 Pro 版本则增加了 Coda 同步和电子邮件支持。

所有方案均可免费使用自己的密钥运行 AI，且 Free 方案中提供的功能不会转为 Pro。价格和完整对比请见 board-planner.com/pricing。

将工作交给机器

如今有很多工具可以让机器编写代码。Board Planner 关注的是与之相关的一切：谁提出了工作、谁批准了工作、机器获准修改哪些内容、任何改动合入前必须通过哪些检查，以及机器何时停下并将工作交还给你。

这条流程的两端各有一个 Agent：负责提出建议并记录事项的 PM Agent，以及接手已批准任务并执行的工作进程。它们都不会擅自做出你未授权的决定。

PM Agent 是驻留在项目中的项目经理。它会查看看板，发现卡住、重复或缺失的内容，并直接给你带来决策，而不是创建一堆没人要求的工单。它擅长处理那些没人喜欢做的工作：为创建时缺少验收标准的任务编写标准、找出重复项，并说明冲刺的实际进展。

在该截图中，回复下方的徽标就是操作记录——消息和写入操作属于同一条记录，因此你可以看到回复同时修改了 ORB-9，而不只是谈论它。并且，它让任务留在原处，因为这是收到的指示。看板审查会禁用 change_status 和 create_task，因此自动执行流程可以告诉你哪里出了问题，而不会在一夜之间悄悄重新整理你的看板。

它默认关闭，且按项目设置；用量会计量，而不是盲目信任：每次调用都会按组织统计 Token 用量，包括自主执行轮次和你的调用，并计入实例可设定的额度；实例管理员还可以为某个项目锁定关闭此功能，且项目设置无法覆盖该限制。没有 OPENROUTER_API_KEY 时，页面会说明这一点，功能也会保持未启用；AI Assist 使用同一个密钥。

📖 PM Agent · 自主看板审查

像交接给真人一样把任务交给它

分配任务、指定 Agent，再将任务拖到你认可的列中。这两项合在一起就是交接——未指定 Agent 的任务不会执行，也不会退回到项目默认设置。别人分配给你的任务只是一个提议，并不是已排队等待在你的机器上执行的工作。

Agent 由步骤和关卡组成

Agent 是一个有序的区块列表，且恰好只有两种类型：

步骤无法拒绝执行，关卡无法写入，因此所有可能停止运行的区块都是关卡，你可以一目了然地查看它们。

每个步骤都是独立的模型会话。同一 Agent 中的两个步骤共享任务和工作树，除此之外互不共享，这就是为什么先分析，再实现不同于让一个模型同时完成两件事：第二个步骤读取第一个步骤写下的内容，而不是它当时的思考过程。

合并是一个步骤，而不是一个开关。 没有“自动合并”复选框，也没有将合并与审查设置绑定的规则。Agent 会合并，是因为它的执行顺序以 Merge 区块结束；不添加该区块，运行就会在拉取请求处停止。

它附带三个 Agent：默认、带安全审查和合并自己的工作。从未打开编辑器的项目会运行默认 Agent。

机器默认不可信

这是我们花最长时间才做对的部分，也是交接机制能够安全用于真实代码仓库的原因：

整个运行过程会实时记录到任务中，因此任务评论就是运行日志——分支、编辑内容、哪个关卡拒绝了操作、剩余的大模型配额。没有旁路，也不必切换到 CI 标签页。

📖 完整说明：Agents · Execution workers · worker/README.md

看板的其他功能

看板为先

列名由你指定，顺序由你选择。每列都会映射到自动化能够理解的角色 （backlog、approved、active、review、blocked、done），所以将 Up next 重命名为 Ready 不会影响任何功能。任何角色为 review 的列都是自动化的停止标志，工作会在这里等待人工处理。看板支持拖放、列表视图、冲刺、依赖项和子任务、循环任务，还能在应用的任何位置通过 ⌘K 搜索所有任务。

应用会遵循你的系统主题，并且整体采用以下两种模式设计：

一个任务包含工作所需的一切

可逐项勾选完成的验收标准、依赖项、关闭该任务的拉取请求、由你为每个项目定义的自定义字段，以及自任务创建以来的所有评论和更改。将分支命名为 bp-8/dark-mode，拉取请求就会自动找到对应任务。

你的 Agent 使用同一个看板

通过 HTTP 提供的 46 个 MCP 工具可将看板带到你的终端中，让 Claude Code 读取待办事项、认领任务并推进任务——使用的权限与团队成员相同。API 令牌可限定到特定项目，且访问范围由中央统一强制执行，因此 REST 和 MCP 都同样适用。

足以回答周一的问题

你的进展如何、积压了多少事情，以及完成任务的速度是否跟得上启动任务的速度。 六张图表，无需电子表格。

其他功能

可在应用内、通过电子邮件或发送到 Slack 和 Discord 的通知——按用户、项目和事件分别设置。项目 审计跟踪。已签名的 Webhook。关联 GitHub 和 GitLab PR。可在手机上使用。

快速开始

你需要 Docker 和 Compose 2.24 或更新版本——较旧的 Compose 会拒绝文件中的 env_file 条目，即使没有 .env 文件也一样。除此之外不需要任何东西：无需 Node、MongoDB，甚至无需克隆代码库。

curl -fsSLO https://raw.githubusercontent.com/rafalpodles/board-planner/main/docker-compose.yml
docker compose up -d

这会运行已发布的镜像 ghcr.io/rafalpodles/board-planner。自 1.1.0 起的每个版本都会构建适用于 linux/amd64 和 linux/arm64 的镜像；1.0.x 早于此版本，且没有镜像。:latest 指向最新版本；若要固定版本，请在 compose 文件旁的 .env 中设置 BOARD_PLANNER_VERSION=1.2.3。要升级，请运行 docker compose pull && docker compose up -d。

main 上的 compose 文件需要 1.1.2 或更高版本的镜像：它会传入 COOKIE_ALLOW_INSECURE=auto， 而 1.1.1 不识别此设置，因此使用 1.1.1 镜像时，除 localhost 以外的任何位置通过普通 HTTP 提供服务都会导致无法登录。若要搭配该文件运行 1.1.1，请在 .env 中设置 COOKIE_ALLOW_INSECURE=1。

从克隆的代码库运行 docker compose up -d --build。 单独运行 docker compose up -d 会拉取并运行最新的已发布版本，而不是你检出的代码；--build 会构建检出的代码并运行它。

打开 http://localhost:3000。在登录页面创建的第一个账户会成为此实例的管理员；此后的所有账户都通过设置 → 用户创建。

创建第一个账户时需要输入设置代码，以防其他人在你之前访问全新的实例并抢先注册。除非你设置了 BOOTSTRAP_TOKEN，否则应用会在启动且没有账户时生成一个代码，并将其打印到服务器日志中——docker compose logs app | grep "setup code"。代码保存在内存中，因此重启后会打印新的代码；如果有多个副本，每个副本都会打印各自的代码：请改为设置 BOOTSTRAP_TOKEN。

运行 docker compose down 可停止服务。数据库存放在 mongo-data 卷中，停止服务后仍会保留；docker compose down -v 会将其删除。

从早于已发布镜像的构建版本升级

在 .env 中将 NEXT_PUBLIC_APP_URL 重命名为 PUBLIC_ORIGIN。应用已不再读取旧名称；如果未设置 PUBLIC_ORIGIN，docker-compose.yml 仍会将旧变量作为 PUBLIC_ORIGIN 传入，因此不做修改的 .env 仍能保留链接。但此回退逻辑仅存在于 compose 文件中——通过其他方式运行镜像时，必须直接设置 PUBLIC_ORIGIN。

不使用 Docker

需要 Node 26 和你自行配置的 MongoDB 4.4+。

npm install
MONGODB_URI=mongodb://localhost:27017/boardplanner npm run build
MONGODB_URI=mongodb://localhost:27017/boardplanner npm start

运行 npm run dev 可启动开发服务器。将 .env.example 复制为 .env.local，用于存放下方的变量。npm start 会监听 PORT——先从环境变量读取，再依次从 .env.production.local、.env.local、.env.production 和 .env 读取，顺序与 Next 读取这些文件的顺序一致；如果这些位置都没有指定端口，则监听 3000。

连接 Agent

MCP 服务已内置于应用的 POST /api/mcp 端点中——无需克隆，也无需构建。在 设置 → API 令牌 下创建一个令牌，将其范围限定为 Agent 应操作的项目，然后让客户端连接到一个 URL：

{
  "mcpServers": {
    "boardplanner": {
      "type": "http",
      "url": "https://your-instance.example.com/api/mcp",
      "headers": { "Authorization": "Bearer cp_..." }
    }
  }
}

共有 46 个工具，按 Agent 常用的操作分组——完整列表以及每个工具的用途，请参阅 MCP 页面：

• 项目和任务： list_projects、get_project、list_tasks、get_task、create_task、update_task、change_task_status、reorder_tasks、search_tasks、my_tasks、archive_task、unarchive_task、delete_task（仅看板所有者可用）
• 批量操作： create_tasks、update_tasks、link_task_pairs（每次调用最多处理 30 或 60 项，并逐项返回结果）
• 关联和清单： link_tasks、unlink_tasks、add_checklist_item、set_checklist_item、remove_checklist_item
• 冲刺： list_sprints、get_sprint、create_sprint、update_sprint、delete_sprint
• 评论和历史记录： add_comment、list_comments、edit_comment、delete_comment、get_task_activity、watch_task、unwatch_task
• 人员和 Agent： list_members、whoami、list_agents
• 报告： get_project_stats、list_runs、list_notifications、mark_notifications_read
• 看板设置（仅添加）： add_custom_field、add_field_option、add_category（任何成员均可操作，与应用中相同）、add_column、rename_column（仅项目所有者可操作）。其他内容的移除或重命名仍需在应用中进行。
• 代码仓库： sync_repository 可刷新看板中的拉取或合并请求及其 CI 徽章，效果与“同步”按钮相同。

希望使用连接器而非粘贴令牌的客户端，可在同一 URL 上使用完整的 OAuth 2.1 with PKCE 和动态客户端注册——无需客户端密钥。

服务器会在连接时告知每个客户端如何操作看板。要使用完整工作流——挑选、认领、汇报、升级处理、关闭——请在 Claude Code 中安装 Agent 技能：

/plugin install board-planner --marketplace rafalpodles/board-planner

请参阅 Agent 技能。

配置

除数据库外，所有配置均为可选项。将覆盖项放入与 docker-compose.yml 同目录的 .env 文件；compose 文件会将其中的所有变量传递给应用，但 NODE_ENV、PORT 和 HOSTNAME 除外，它会将这三个变量固定为 production、3000 和 0.0.0.0。

A request arrived with X-Forwarded-For carrying 2 entries while TRUSTED_PROXY_HOPS=0, so the
header is ignored and the login throttle has no per-address key. …

重要

MongoDB 固定使用 4.4，且不会映射到主机端口——只有应用容器可以访问它。聚合操作会刻意避开仅从 5.0 开始提供的运算符，而固定版本正是确保这一点的关键。

构建方式

Next.js 16（App Router）和 TypeScript、Tailwind CSS 4、MongoDB 与 Mongoose。身份验证通过浏览器中的会话 Cookie 和 API 客户端及 OAuth 使用的 Bearer 令牌实现；浏览器从不持有密码。

src/
  app/api/          REST API — ~150 routes, plus the MCP endpoint at /api/mcp
  app/              board, task detail, sprints, dashboard, search, settings
  components/       kanban/, tasks/, search/, shell/, pm/, settings/, ui/
  lib/              auth, notifications, webhooks, custom fields, PM agent, force guard
  models/           Mongoose schemas
worker/             execution worker — claims tasks, runs an agent, enforces gates
menubar/            macOS menu bar app
e2e/                Playwright specs

开发

npm test           # unit tests (vitest)
npm run test:e2e   # end-to-end tests (playwright)
npx tsc --noEmit   # types

为 e2e 运行分配专属端口和数据库，因为 fixture 默认并非隔离：

E2E_PORT=3200 PM_STUB_PORT=3201 E2E_MONGODB_URI=mongodb://localhost:27017/local_e2e npx playwright test

网站和文档

board-planner.com 是产品导览：你可以实际拖动卡片的看板、可以尝试中断正在运行的工作进程，以及会拒绝请求的关卡。

board-planner.com/docs 是使用手册，共三十三页，也是唯一可信来源：文档位于 board-planner-site 仓库中，合并后即会发布，因此文档页面始终与产品同步。

许可证

Board Planner 是基于 GNU Affero General Public License v3 发布的自由软件。有一个目录例外：src/ee/ 是商业版 Enterprise Edition，依据其自身条款授权，可通过 Board Planner 订阅或许可证密钥使用。它包含付费连接器，目前有 Coda 同步功能；付费 AI 功能也将放在这里。欢迎为其他所有内容贡献代码，详见 CONTRIBUTING.md。