TaskBoardAI

TaskBoardAI

一款为 AI Agent 打造的轻量级文件式看板。 包含用于 HIL 协作的 Web 界面。

AIX 功能：

• 使用 JSON 看板文件，提供完整的项目上下文
• MCP 服务，可用于创建、删除、更新和读取看板

HIL 功能：

• 拖放卡片和列以进行排序
• 添加／删除卡片和列
• 下拉选择可用看板

注意
TaskBoardAI 没有自己的大模型集成。
你需要使用项目上下文来更新看板。

• 查看“使用外部看板位置”
• 查看“使用 MCP”

功能

• Markdown 支持：使用完整的 Markdown 语法编写丰富的卡片内容
• 子任务：在卡片中跟踪并标记完成状态
• 标签和依赖项：整理并关联相关卡片
• 拖放：直观地管理卡片
• 后续步骤：在看板层级跟踪即将处理的优先事项
• Webhook：通过 webhook 与其他服务集成
• AI 集成：通过 MCP 与 Claude 桌面版连接

安装

选项 1：通过 npm 安装（推荐）

全局安装，即可在任何位置通过命令行使用：

npm install -g taskboardai

或在项目中本地安装：

npm install taskboardai

选项 2：克隆仓库（开发）

1. 克隆仓库：

git clone https://github.com/TuckerTucker/TaskBoardAI.git
cd TaskBoardAI

2. 安装依赖项：

npm install

使用方法

使用通过 npm 安装的版本

通过 npm 全局安装后，可以使用以下命令：

1. 列出可用看板：

taskboard --list

2. 创建新看板：

taskboard --new my-project

3. 打开现有看板：

taskboard my-project

4. 启动 MCP 服务：

taskboard-mcp

5. 同时启动看板服务和 MCP 服务：

taskboard-all

使用仓库版本

如果你克隆了仓库，请使用其中包含的脚本：

1. 列出可用看板：

./_start_kanban --list

2. 创建新看板：

./_start_kanban --new my-project

3. 打开现有看板：

./_start_kanban my-project

4. 通过 http://localhost:3001 访问看板（默认端口）

使用外部看板位置

*目前尚不支持通过 MCP 使用

1. 在项目仓库中创建新的看板目录

2. 复制示例看板：

   如果通过 npm 安装：

   # First, create an example board in your home directory
   taskboard --new example
   
   # Then copy it to your desired location
   cp ~/.taskboardai/boards/example.json /your/board/location/board_name.json
   

   如果使用仓库版本：

   cp /path/to/TaskBoardAI/boards/_kanban_example.json /your/board/location/board_name.json
   

3. 使用外部看板位置启动服务：

   如果通过 npm 安装：

   taskboard --external /your/board/location/board_name.json
   

   如果使用仓库版本：

   ./_start_kanban --external /your/board/location/board_name.json
   

看板结构

看板由一个 JSON 文件定义，结构如下： 这样 Agent 就能获得完整的项目上下文

{
  "projectName": "Project Name",
  "id": "unique-board-id",
  "columns": [
    {
      "id": "column-id",
      "name": "Column Name"
    }
  ],
  "cards": [
    {
      "id": "card-id",
      "title": "Card Title",
      "content": "Markdown supported content",
      "columnId": "column-id",
      "position": 0,
      "collapsed": false,
      "subtasks": [
        "✓ Completed task",
        "Pending task"
      ],
      "tags": ["feature", "frontend"],
      "dependencies": ["other-card-id"],
      "created_at": "2025-01-18T10:00:00.000Z",
      "updated_at": "2025-01-19T12:30:00.000Z",
      "completed_at": "2025-01-19T18:12:35.604Z"
    }
  ],
  "next-steps": [
    "Next priority task",
    "Future focus area"
  ],
  "last_updated": "2025-01-19T19:20:14.802Z"
}

注意：看板结构已更新为以卡片为先的架构，卡片存储在顶层数组中，而不是嵌套在列内。

用于 AI 集成的 MCP 服务

什么是模型上下文协议（MCP）？
TaskBoardAI 包含一个 MCP（模型上下文协议）服务，可让你使用任何支持 MCP 的工具（例如 Claude Code、Cursor、Windsurf ...）创建和管理看板。

启动 MCP 服务

如果通过 npm 安装：

# Start only the MCP server
taskboard-mcp

# Or start both the board server and MCP server
taskboard-all

如果使用仓库版本：

# Start only the MCP server
./_start_mcp

# Or start both servers
./_start_all

MCP 服务默认在端口 3002 上运行。

请参阅 IDE 或命令行工具的文档，了解如何添加 MCP 服务。

与 Agent 配合使用

配置完成后，你可以向 Agent 提出以下请求：

• 列出所有看板：“显示我的所有看板”
• 创建新看板：“创建一个名为‘Project X’的新看板”
• 按名称获取特定看板：“显示 Project X 的详细信息”
• 更新看板：“根据我们的进度更新 Project X 看板”
• 删除看板：“删除 Project X 看板”

Webhook 集成

TaskBoardAI 支持通过 webhook 与其他服务集成：

1. 创建 webhook 配置，以便在看板更新等事件发生时触发
2. 通过 API 测试 webhook 连接
3. 看板发生更改时接收实时更新

运行测试

1. 运行所有测试：

npm test

2. 生成覆盖率报告：

npm run test:coverage

3. 以监视模式运行测试（用于开发）：

npm run test:watch

4. 运行特定类别的测试：

# Run MCP server tests
npm test -- --testPathPattern 'tests/.*mcp'

# Run only unit tests
npm test -- tests/unit

# Run only integration tests
npm test -- tests/integration

生成文档

生成文档：

# Install dependencies (if not already installed)
npm install

# Generate docs (docs/api directory)
npm run docs

数据目录

通过 npm 安装时，TaskBoardAI 会将用户数据存储在以下位置：

• Linux/macOS：~/.taskboardai/
• Windows：C:\Users\<username>\.taskboardai\

数据目录包含：

• boards/：看板 JSON 文件
• config/：配置文件
• webhooks/：Webhook 配置

如有需要，你可以直接访问或备份这些文件。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

许可证

Apache License 2.0 - 详情请参阅 LICENSE。