目标就一个：一句话出结果。
🌐 语言 / Language: 🇺🇸 English | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇹🇼 繁體中文 | 🇧🇷 Português (BR) | 🇪🇸 Español | 🇩🇪 Deutsch | 🇫🇷 Français | 🇷🇺 Русский | 🇮🇹 Italiano | 🇵🇱 Polski | 🇺🇦 Українська | 🇻🇳 Tiếng Việt | 🇮🇩 Indonesia | 🇹🇭 ไทย | 🇮🇳 हिन्दी | 🇳🇱 Nederlands | 🇹🇷 Türkçe | 🇸🇪 Svenska | 🇬🇷 Ελληνικά | 🇭🇺 Magyar | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇳🇴 Norsk | 🇫🇮 Suomi | 🇷🇴 Română | 🇸🇦 العربية | 🇮🇱 עברית | 🇧🇩 বাংলা | 🇵🇰 اردو | 🇵🇹 Português (PT)
本项目采用 Apache-2.0 许可协议，明确允许个人使用、团队协作、二次开发和商业使用。
- 允许商用、分发、修改和私有部署。
- 保留原始许可与版权声明即可。
- 项目名称、品牌标识和商标本身不随许可证自动授权。
仓库地址：MaiHHConnect/claude-whiteboard
- 发布为精简后的公开版本，移除了内部任务记录、Wiki 沉淀、修复过程文档和本地运行产物。
- 保留可运行的核心代码：调度器 CLI、MCP 服务、云端
cloud-server、Web UI、测试与示例配置。 - 补齐发布边界：新增
.gitignore，避免把工作区数据、自动沉淀内容、私有过程文档一并提交。 - 当前版本聚焦白板式多 Agent 协作与任务调度能力，便于直接部署、二次开发和对外展示。
- Web 首页更新为荧光绿 + 白卡片的新视觉风格，统一品牌氛围与操作层级。
- 创建任务时的“操作文件夹 / 资料路径”支持系统文件夹选择器，不再只能手动输入路径。
- 项目目录结构
- 调度器核心模块 (TypeScript)
- 状态管理 (
src/scheduler/state.ts) - 看板逻辑 (
src/scheduler/kanban.ts) - MCP 工具定义 (
src/scheduler/mcpTools.ts) - 任务路由 (
src/scheduler/taskRouter.ts) - 循环保护 (
src/scheduler/loopProtection.ts) - 心跳检测 (
src/scheduler/heartbeat.ts)
- 状态管理 (
- 云端 API 服务器
- Koa 服务器 (
cloud-server/src/index.js) - 数据持久化 (JSON 文件)
- Agent 管理 API
- 任务管理 API
- 看板视图 API
- Koa 服务器 (
- CLI 工具 (
src/cli.js)-
board- 查看看板 -
tasks- 查看任务列表 -
create- 创建任务 -
claim- 认领任务 -
status- 更新状态 -
bug- 报告 Bug -
agents- 查看 Agent -
register- 注册 Agent -
stats- 统计信息
-
- MCP Server (
src/mcp/server.js)- kanban_register_task
- kanban_get_board
- kanban_get_tasks
- kanban_claim_task
- kanban_update_status
- kanban_report_bug
- kanban_register_agent
- kanban_heartbeat
- kanban_get_agents
- kanban_get_stats
- Claude Code Agent 配置 (
.claude/agents/)- pm-agent.json
- dev-agent.json
- qa-agent.json
- deploy-agent.json
- API 客户端 (
src/scheduler/client.ts) - 调度器运行器 (
src/scheduler/runner.ts) - 自动 Agent Runner (
src/auto-runner.js)- DevRunner - 自动认领并处理开发任务
- QARunner - 自动测试并报告 Bug
- DeployRunner - 自动部署完成任务
- 钉钉集成 - 消息推送 (Webhook)
- 钉钉集成 - Stream 连接与命令处理
- Web UI 看板界面
- Docker 部署配置
- Web UI 看板界面
- Docker 部署配置
- 云端同步机制
- 单元测试
cd cloud-server
npm install # 已完成
npm startnode src/mcp/server.js打开浏览器访问 http://localhost:8085 即可看到可视化的看板界面。
# 配置钉钉机器人（群机器人 -> 高级设置 -> 启用加签）
export DINGTALK_WEBHOOK_URL="https://oapi.dingtalk.com/robot/send?access_token=xxx"
export DINGTALK_SECRET="SECxxx"
# 如果使用 Stream 模式（需要企业内部应用）
export DINGTALK_APP_KEY="dingxxx"
export DINGTALK_APP_SECRET="xxx"
# 测试钉钉连接
curl -X POST http://localhost:8085/api/dingtalk/test在钉钉群中 @机器人 发送以下命令：
# 查看看板
/board
# 查看任务列表
/tasks
# 创建任务
/task 实现登录功能
# 认领任务
/claim <任务ID>
# 更新状态
/status <任务ID> ReadyForTest
# 报告 Bug
/bug <任务ID> 按钮点击无反应
# 查看统计
/stats
# 查看在线 Agent
/agents
# 获取帮助
/help# 查看看板
node src/cli.js board
# 创建任务
node src/cli.js create "实现登录功能" --skills=frontend,backend
# 注册 Agent
node src/cli.js register "Dev-1" developer --skills=frontend,backend
# 认领任务
node src/cli.js claim <taskId> <agentId>
# 更新状态
node src/cli.js status <taskId> ReadyForTest
# 报告 Bug
node src/cli.js bug <taskId> "按钮点击无反应"┌──────────────────────────────────────────────────────────────────┐
│ Claude Code CLI │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 看板调度中心 (Scheduler) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Backlog │ │ InDev │ │ReadyTest│ │ InFix │ ... │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │ PM Agent │ Dev Agent │ QA Agent │ Deploy Agent │ │
└──────────────────────────────────────────────────────────────────┘
│ HTTP / MCP
▼
┌──────────────────────────────────────────────────────────────────┐
│ 云服务器 (端口 8085) │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Koa API Server │ │
│ │ - 看板数据持久化 (JSON 文件存储) │ │
│ │ - Agent 注册与心跳 │ │
│ └────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
| 状态 | 描述 | 可流转到 |
|---|---|---|
| Backlog | 待处理 | InDev |
| InDev | 开发中 | ReadyForTest, InFix |
| ReadyForTest | 待测试 | ReadyForDeploy, InFix |
| InFix | 待修复 | InDev, ReadyForTest |
| ReadyForDeploy | 待部署 | Done |
| Done | 已完成 | - |
| Blocked | 被阻塞 | InDev, Backlog |
当 QA 报告同一个任务的 Bug 超过 3 次时，该任务会自动进入 Blocked 状态。
claude-code/
├── .claude/
│ └── agents/ # Claude Code Agent 配置
│ ├── pm-agent.json
│ ├── dev-agent.json
│ ├── qa-agent.json
│ └── deploy-agent.json
│
├── src/
│ ├── cli.js # CLI 工具
│ ├── mcp/
│ │ └── server.js # MCP Server
│ └── scheduler/
│ ├── client.ts # API 客户端
│ ├── runner.ts # Agent 运行器
│ ├── heartbeat.ts
│ ├── index.ts
│ ├── kanban.ts
│ ├── loopProtection.ts
│ ├── mcpTools.ts
│ ├── state.ts
│ └── taskRouter.ts
│
├── cloud-server/ # 云端服务器
│ ├── src/
│ │ └── index.js # Koa 服务器入口
│ ├── package.json
│ └── data/ # 数据存储
│ └── scheduler.json
│
└── docs/
└── SCHEDULER.md # 详细文档
- 完成云端服务器 (端口 8085)
- 完成 CLI 工具
- 完成 MCP Server (端口 6667)
- 完成 Claude Code Agent 配置
- 完成 API 客户端和运行器
- 在钉钉群中添加"群机器人"
- 选择"自定义机器人"
- 复制 Webhook URL 和加签密钥
export DINGTALK_WEBHOOK_URL="https://oapi.dingtalk.com/robot/send?access_token=xxx"
export DINGTALK_SECRET="SECxxx"- 在钉钉开放平台创建企业内部应用
- 配置机器人能力
- 获取 AppKey 和 AppSecret
export DINGTALK_APP_KEY="dingxxx"
export DINGTALK_APP_SECRET="xxx"- 后端: Koa, Node.js
- CLI: Node.js 原生 HTTP
- MCP: 自定义 MCP 协议实现
- 数据存储: JSON 文件
- Agent 配置: Claude Code 原生 agents
- 钉钉集成: Webhook + Stream 双重模式