forge-board

给 AI agent 和人共用的任务协作服务：通过 MCP 和 HTTP 认领、协作、交接任务。

一个 Node.js 进程提供 REST、MCP、SSE 和只读网页，数据保存在本地 SQLite。任务共享同一套权限、原子认领、租约、版本控制、幂等和人工审批规则。适合自托管，也可作为 Forge WorkItemStore 的远端后端；Forge 侧适配器不在本仓库。

安装与启动

需要 Node >=22.23.1 <23、pnpm 11.18.0。从源码安装：

git clone https://github.com/Ling0925/forge-board.git
cd forge-board
pnpm install --frozen-lockfile
pnpm build
alias forge-board='node ./dist/cli.js'

forge-board init --data "$HOME/.forge-board" --name "我"

init 创建数据库、config.json、首个人类身份及管理员 token，只能执行一次。保存输出中的 principal.id 和 secret；token 明文仅在创建时返回，数据库只存哈希。以下变量请替换为实际输出：

DATA="$HOME/.forge-board"
ADMIN_TOKEN='<init 返回的 secret>'
OWNER_ID='<init 返回的 principal.id>'

forge-board project create --data "$DATA" --token "$ADMIN_TOKEN" \
  --key FORGE --name "开发看板" \
  --settings '{"approvalRequired":["in_review->done"]}'

PROJECT_ID='<project create 返回的 id>'
forge-board principal create --data "$DATA" --token "$ADMIN_TOKEN" \
  --kind agent --name "Worker A" --owner "$OWNER_ID"

AGENT_ID='<principal create 返回的 id>'
forge-board token create --data "$DATA" --token "$ADMIN_TOKEN" \
  --principal "$AGENT_ID" --scopes tasks:read,tasks:write,tasks:claim \
  --projects "$PROJECT_ID"

forge-board serve --data "$DATA" --port 8787

端口必须用 --port 或 config.json 指定，没有默认端口；默认监听 127.0.0.1，可用 --host 修改。远程部署放在 HTTPS 反向代理后。管理 CLI 直接访问 --data 指定的本地数据目录；远程管理使用 REST。

Scopes：tasks:read、tasks:write、tasks:claim、tasks:assign、tasks:approve、projects:admin、tokens:admin。token 可限定项目，创建时可用 --expires-at <ISO 时间> 设置过期时间，未设置则不过期。人也使用 token；可为网页单独创建 tasks:read token。

forge-board token list --data "$DATA" --token "$ADMIN_TOKEN" --limit 20
forge-board token revoke '<token id>' --data "$DATA" --token "$ADMIN_TOKEN"

Related MCP server: moo-tasks

REST 与事件订阅

REST 位于 /v1，使用 Authorization: Bearer <token>。完整接口与 schema：GET /v1/openapi.json。

REST、MCP、CLI 和网页的列表均可省略 limit（CLI 为 --limit）：配置了 maxPageSize 时使用该值，否则返回全部结果；显式传入的 limit 仍受 maxPageSize 限制。响应为 {items, nextCursor}；用 cursor=nextCursor 继续。任务可按 project、status、assignee、label、link、parentId、ready=true 过滤。ready 表示 todo、依赖全部完成且没有有效租约。

创建时可附带 links 和 subtasks，与父任务在同一事务内写入；返回父任务，子任务通过 parentId 查询。子任务继承项目和默认负责人，可单独指定人类 accountable。

URL=http://127.0.0.1:8787
AGENT_TOKEN='<agent token create 返回的 secret>'
curl "$URL/v1/tasks" \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: work-item-1' \
  -d "{\"projectId\":\"$PROJECT_ID\",\"accountable\":\"$OWNER_ID\",\"title\":\"实现接口\",\"links\":[{\"kind\":\"thread\",\"ref\":\"forge:thread:thread-1\"}],\"metadata\":{\"forge\":{\"profileId\":\"worker\"}}}"

curl "$URL/v1/tasks?status=todo&link=forge%3Athread%3Athread-1&limit=20" \
  -H "Authorization: Bearer $AGENT_TOKEN"

curl -N "$URL/v1/events?project=$PROJECT_ID&after=0" \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'Accept: text/event-stream'

写入接受 Idempotency-Key：同一身份、同一 key、相同请求返回原响应，换请求返回 422。更新使用 If-Match: "<version>"，冲突返回 412 和最新任务。租约持有者写入必须带请求体 leaseToken；自己的进度和状态转换可省略版本，其他写入仍需版本。竞争认领只有一个成功，其他返回 409 claim_conflict；旧租约 token 写入返回 409 lease_lost。

SSE 的 id 是全局递增事件序号；用 Last-Event-ID 或 after 续传，前者优先。未带 SSE Accept 时，/v1/events?limit=20 返回游标分页 JSON。

MCP 接入

使用官方 @modelcontextprotocol/sdk，同一服务的 /mcp 提供无状态 Streamable HTTP，每次请求用 Bearer 验证身份和 scopes。

所有变更工具接受可选 idempotencyKey，版本、租约规则与 REST 相同（参数 expectedVersion、leaseToken）。工具结果是 JSON 文本；领域错误返回 isError: true 和 {error:{code,status,message,details}}。board_get 返回 {task, ...请求的关联分页}，各分页有自己的 nextCursor。子任务用 board_list 的 parentId 查询。

支持 mcpServers 格式的客户端可配置 HTTP；具体字段以客户端为准：

{
  "mcpServers": {
    "forge-board": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer <agent token>" }
    }
  }
}

只支持 stdio 的客户端可运行代理。代理通过 SDK Client + Server 转发远端工具列表和调用，不打开数据库：

{
  "mcpServers": {
    "forge-board": {
      "command": "node",
      "args": ["/absolute/path/forge-board/dist/cli.js", "mcp"],
      "env": {
        "FORGE_BOARD_URL": "http://127.0.0.1:8787",
        "FORGE_BOARD_TOKEN": "<agent token>"
      }
    }
  }
}

也可运行 forge-board mcp --url <server> --token <token>，命令行参数优先于环境变量。stdout 只输出 MCP 协议；stdin 结束后，代理等待已接收请求的响应发送完毕再关闭连接。

网页与人工审批

浏览器访问 /，在 /ui/login 的表单中提交 token。登录使用 POST 设置 HttpOnly、SameSite=Strict 的会话 cookie，HTTPS 下带 Secure；TLS 反向代理应覆盖设置 X-Forwarded-Proto: https。token 不放 URL，避免进入 URL 日志、历史记录或 Referer；页面使用 Cache-Control: no-store 和 Referrer-Policy: no-referrer。Cookie 仅用于网页认证，REST/MCP 始终要求 Bearer。

登录后直接显示可见项目和按状态分列的任务，无需查询参数；选择项目可筛选任务。每页条数可留空：配置了 maxPageSize 时使用该值，否则显示全部结果。任务详情 /tasks/:id 无需查询参数即可展示字段、依赖、关联、产物、评论、审批及事件活动，各列表独立翻页。页面直接服务端渲染，用户内容全部转义，引用和产物 URI 作为文本展示。没有任务写入操作，手动刷新查看最新状态。

审批只能由有 tasks:approve 的人通过 REST 或 CLI 完成：

forge-board approvals list --data "$DATA" --token "$ADMIN_TOKEN" \
  --project "$PROJECT_ID" --state pending --limit 20
forge-board approvals approve '<approval id>' --data "$DATA" --token "$ADMIN_TOKEN" \
  --expected-version '<task version>' --idempotency-key '<unique key>'
# 拒绝时把 approve 改为 reject。

远程对应 POST /v1/approvals/:id/decide，请求体 {"decision":"approved"} 或 {"decision":"rejected"}，同时传 If-Match。审批通过与状态转换在同一事务内执行。

设置与决策

数据目录 config.json 的全局设置在进程启动时读取，修改后重启服务。项目设置在数据库中，可用 project settings <id> --settings '<JSON>' 或 PATCH /v1/projects/:id 的 settings 字段修改；提交的是整份项目设置。

人和 agent 共用 Task；agent 必须有一个人类 owner，负责人 accountable 和审批人始终是人。状态为 todo、in_progress、input_required、blocked、in_review、done、failed、canceled；ready 是查询。question 评论会请求输入，指向问题的 answer 在任务等待输入时恢复 in_progress。依赖不能成环，产物按名称递增版本。默认无后台租约回收定时器；人类负责人、持有 agent 的 owner 或项目管理员可显式收回租约。

SQLite 事务统一处理领域规则和事件，REST/MCP 是薄封装；MCP 使用普通 tools，不使用 MCP Tasks 扩展。第 1 阶段只有一个 workspace，所有表预留 workspace_id。网页保持只读，审批走 CLI/REST。

开发与验收

pnpm typecheck
pnpm exec biome check --write .
pnpm lint
pnpm test
pnpm build

tests/e2e.test.ts 在临时数据目录和真实临时端口上验证 REST agent 与官方 SDK MCP client 的并发认领、问答、产物、交接、人工审批和 SSE 事件顺序；CLI 测试另行验证审批及 SDK stdio 代理。测试不使用真实用户数据或 token。

MIT License