Tasks Multi Server

任务多服务器

版本0.1.0-alpha -具有MCP服务器、REST API和React UI的多接口任务管理系统。

⚠️ 阿尔法释放警告 这是一个alpha版本，正在积极开发中。在稳定的1.0.0版本之前，API和功能可能会发生重大变化。在生产中使用，风险自负。 - alpha版本之间可能会发生重大变化 - API端点和响应格式可能会更改 - 数据库架构迁移可能不向后兼容 - 文件可能不完整或过时 对于稳定版本，请等待1.0.0或更高版本。

概述

TasksMultiServer通过多个界面提供分层任务管理，这些界面专为人类用户和人工智能代理而设计。将任务存储在PostgreSQL或文件系统中，通过MCP协议、REST API或web UI进行访问。

对于开发者：参见 贡献.md 用于开发设置和贡献指南。

特性

• 多接口访问：用于AI代理的MCP服务器，用于编程访问的REST API，用于可视化管理的React UI
• 可插拔存储：在文件系统或PostgreSQL之间进行选择
• 分层组织：项目→ 任务列表→ Tasks
• 依赖管理：具有循环依赖检测的基于DAG的任务依赖关系
• 基于模板的指令：生成特定于代理的任务说明
• 直接进入商店：无缓存可确保多个代理之间的一致性
• 代理友好功能：自动参数预处理，带有视觉指示器和示例的增强错误消息
• 标签和搜索：使用标签组织任务，根据多个条件（文本、状态、优先级、标签、项目）进行搜索和筛选
• 依赖性分析：分析关键路径，识别瓶颈，可视化依赖关系图（ASCII、DOT、Mermaid）
• 批量操作：在单个操作中高效地创建、更新、删除或标记多个任务
• 自动阻塞检测：任务会自动显示它们被依赖关系信息阻止的原因
• 健康监测：用于监控系统状态的内置健康检查端点

访问任务的三种方法MultiServer

TasksMultiServer为不同的用例提供了三个不同的接口：

1.MCP服务器（用于AI代理）

⚠️ 尚未发布：此项目尚未在PyPI或uvx上可用。要使用它，您必须克隆存储库并在本地构建。

本地构建和安装：

# Clone the repository
git clone https://github.com/YOUR_USERNAME/tasks-multiserver.git
cd tasks-multiserver

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run the MCP server
python -m src.interfaces.mcp.server

在AI代理的MCP设置中进行配置（例如。， .kiro/settings/mcp.json):

{
  "mcpServers": {
    "tasks-multiserver": {
      "command": "python",
      "args": ["-m", "src.interfaces.mcp.server"],
      "cwd": "/path/to/tasks-multiserver",
      "env": {
        "DATA_STORE_TYPE": "filesystem",
        "FILESYSTEM_PATH": "/path/to/tasks",
        "MULTI_AGENT_ENVIRONMENT_BEHAVIOR": "false"
      }
    }
  }
}

一旦发布，您将能够使用：

uvx tasks-multiserver
# or
pip install tasks-multiserver

2.REST API+React UI（通过Docker Compose）

使用Docker Compose可以同时运行REST API和web UI。

docker-compose up

访问权限：

• REST API: http://localhost:8000
• React用户界面: http://localhost:3000

通过配置 .env 文件（请参阅下面的配置部分）。

代理友好功能

TasksMultiServer旨在与AI代理无缝协作，提供智能参数处理和清晰的错误反馈。

自动参数预处理

该系统会自动将常见的输入模式转换为正确的类型，从而减少AI代理的摩擦：

• 字符串数字 → 数字： "5" → 5, "3.14" → 3.14
• JSON字符串 → 数组： '["tag1", "tag2"]' → ["tag1", "tag2"]
• 布尔字符串 → 布尔人： "true", "yes", "1" → True

这意味着代理不需要担心确切的类型格式化——系统会智能地处理它。

增强的错误消息

当发生验证错误时，系统会提供：

• 视觉指示器 (❌, 💡, 📝, 🔧) 用于快速扫描
• 字段名称 以及具体的问题描述
• 可操作的指导 关于如何修正错误
• 工作示例 正确使用
• 有效选项 对于枚举字段

错误消息示例：

❌ priority: Invalid value "urgent"
💡 Priority must be one of: CRITICAL, HIGH, MEDIUM, LOW, TRIVIAL
📝 Example: "priority": "HIGH"

标签和搜索

使用标签和强大的搜索功能高效地组织和查找任务。

业标

为任务添加标签以进行分类和筛选：

• 每个任务最多10个标签
• 支持unicode、表情符号、数字、连字符和下划线
• 每个标签最多50个字符
• 自动重复数据删除

MCP示例：

# Add tags to a task
add_task_tags(task_id="...", tags=["frontend", "urgent", "🚀"])

# Remove tags
remove_task_tags(task_id="...", tags=["urgent"])

REST API示例：

# Add tags
POST /tasks/{id}/tags
{"tags": ["frontend", "urgent", "🚀"]}

# Remove tags
DELETE /tasks/{id}/tags
{"tags": ["urgent"]}

统一搜索

在单个查询中按多个条件搜索和筛选任务：

• 文本搜索：与任务标题和描述匹配
• 状态筛选器：按任务状态筛选（NOT_STARTED、IN_PROGRESS、BLOCKED、COMPLETED）
• 优先级筛选器：按优先级过滤（临界、高、中、低、三）
• 标签过滤器：查找具有特定标签的任务
• 项目筛选器：按项目名称筛选
• 分页：使用限制和偏移控制结果大小
• 排序：按相关性、created_at、updated_at或优先级排序

MCP示例：

search_tasks(
    query="authentication",
    status=["IN_PROGRESS"],
    priority=["HIGH", "CRITICAL"],
    tags=["backend"],
    project_name="API Development",
    limit=20,
    sort_by="priority"
)

REST API示例：

POST /search/tasks
{
  "query": "authentication",
  "status": ["IN_PROGRESS"],
  "priority": ["HIGH", "CRITICAL"],
  "tags": ["backend"],
  "project_name": "API Development",
  "limit": 20,
  "sort_by": "priority"
}

依赖性分析和可视化

使用强大的依赖性分析工具了解项目结构并确定关键路径。

相关性分析

分析任务依赖关系以获得见解：

• 关键路径：确定最长的依赖任务链
• 瓶颈：查找阻止多个其他任务的任务
• 叶子任务：确定没有依赖关系的任务（准备开始）
• 进度跟踪：计算依赖关系图中的完成百分比
• 循环依赖检测：自动检测和报告周期

MCP示例：

analyze_dependencies(scope_type="project", scope_id="...")

REST API示例：

GET /projects/{id}/dependencies/analysis
GET /task-lists/{id}/dependencies/analysis

答复：

{
  "critical_path": ["task-id-1", "task-id-2", "task-id-3"],
  "critical_path_length": 3,
  "bottleneck_tasks": [["task-id-2", 5]],
  "leaf_tasks": ["task-id-1", "task-id-4"],
  "completion_progress": 45.5,
  "total_tasks": 10,
  "completed_tasks": 4,
  "circular_dependencies": []
}

依赖关系可视化

以多种格式可视化依赖关系图：

• 美国信息交换标准代码：树形结构，带方框图字符（用于终端显示）
• 点：Graphviz格式（用于使用Graphviz工具渲染）
• 美人鱼：Mermaid图语法（用于文档和web显示）

MCP示例：

# ASCII visualization
visualize_dependencies(scope_type="project", scope_id="...", format="ascii")

# DOT format for Graphviz
visualize_dependencies(scope_type="project", scope_id="...", format="dot")

# Mermaid diagram
visualize_dependencies(scope_type="project", scope_id="...", format="mermaid")

REST API示例：

GET /projects/{id}/dependencies/visualize?format=ascii
GET /projects/{id}/dependencies/visualize?format=dot
GET /projects/{id}/dependencies/visualize?format=mermaid

自动阻塞检测

当任务具有不完整的依赖关系时，任务会自动包含阻止信息：

{
  "id": "task-123",
  "title": "Deploy to production",
  "status": "BLOCKED",
  "block_reason": {
    "is_blocked": true,
    "blocking_task_ids": ["task-100", "task-101"],
    "blocking_task_titles": ["Run integration tests", "Security audit"],
    "message": "Blocked by 2 incomplete dependencies: Run integration tests, Security audit"
  }
}

这样就不需要额外的查询来了解任务无法继续的原因。

批量操作

使用批量操作（仅限REST API）同时高效管理多个任务。

支持的操作

• 批量创建：在一个请求中创建多个任务
• 批量更新：在一个请求中更新多个任务
• 批量删除：在一个请求中删除多个任务
• 批量标签操作：在多个任务中添加或删除标签

特性

• 应用前验证：在做出任何更改之前，所有输入都经过验证
• 部分故障报告：详细结果显示哪些操作成功，哪些操作失败
• 交易支持PostgreSQL操作使用事务；文件系统操作支持回滚

示例：

# Bulk create tasks
POST /tasks/bulk/create
{
  "tasks": [
    {"task_list_id": "...", "title": "Task 1", "description": "...", ...},
    {"task_list_id": "...", "title": "Task 2", "description": "...", ...}
  ]
}

# Bulk update tasks
PUT /tasks/bulk/update
{
  "updates": [
    {"id": "task-1", "status": "COMPLETED"},
    {"id": "task-2", "priority": "HIGH"}
  ]
}

# Bulk delete tasks
DELETE /tasks/bulk/delete
{
  "task_ids": ["task-1", "task-2", "task-3"]
}

# Bulk add tags
POST /tasks/bulk/tags/add
{
  "task_ids": ["task-1", "task-2"],
  "tags": ["urgent", "frontend"]
}

# Bulk remove tags
POST /tasks/bulk/tags/remove
{
  "task_ids": ["task-1", "task-2"],
  "tags": ["urgent"]
}

响应格式：

{
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "index": 0, "success": true, "task_id": "task-1" },
    { "index": 1, "success": true, "task_id": "task-2" },
    { "index": 2, "success": false, "error": "Task not found" }
  ],
  "errors": [{ "index": 2, "error": "Task not found" }]
}

测试数据生成器

TasksMultiServer包含一个测试数据生成器，可为开发、测试和演示目的创建逼真、全面的测试数据。

特性

• 数据库重置：自动将Docker数据库重置为干净状态
• 真实数据：创建15个项目、35个任务列表和数百个具有不同元数据的任务
• 依赖图：生成任务依赖关系，确保没有循环引用
• 状态分布：创建不同状态的任务（NOT_STARTED、in_PROGRESS、COMPLETED）
• 元数据：添加标签、优先级、注释、行动计划和退出条件
• 可复现的：使用可配置的随机种子获得一致的结果
• 已验证：根据22个正确性属性自动验证生成的数据

用法

先决条件：

• Docker和Docker Compose已安装并正在运行
• 可访问REST API（默认值：http://localhost:8000)

基本用法：

# Generate with default settings (seed=42)
python scripts/generate_test_data.py

# Generate with custom seed for different data
python scripts/generate_test_data.py --seed 123

# Generate with custom API URL
python scripts/generate_test_data.py --api-url http://localhost:9000

它产生了什么：

• 15个项目，任务列表数量各不相同（每个项目0-10个）
• 35个任务列表，每个列表包含0-25个任务
• 具有现实标题、描述和退出标准的任务
• 形成有效DAG的任务依赖关系（无循环依赖关系）
• 考虑依赖约束的混合任务状态
• 标签（每项任务1-5个）来自现实池
• 所有5个优先级（关键、高、中、低、三）
• 基于任务状态的注释（研究、执行、一般）
• 包含3-8个连续项目的行动计划（70%的任务）

输出示例：

Test Data Generator for TasksMultiServer
==================================================
Random seed: 42
API URL: http://localhost:8000

Phase 1: Resetting database...
✓ Database reset complete

Phase 2: Creating entities...
✓ Created 15 projects, 35 task lists, 247 tasks

Phase 3: Assigning dependencies...
✓ Dependencies assigned

Phase 4: Assigning statuses...
✓ Statuses assigned

Phase 5: Enriching metadata...
✓ Metadata enriched

Phase 6: Validating data...
======================================================================
Data Validation Report
======================================================================
Status: PASSED
Properties Passed: 22/22
Properties Failed: 0/22

Summary:
  Total Projects: 15
  Total Task Lists: 35
  Total Tasks: 247

No violations found!
======================================================================

✓ Data generation completed successfully!

何时使用

• 发展：用真实的测试数据填充本地数据库
• 测试：使用可重复的种子创建一致的测试场景
• 德莫斯：为演示生成令人印象深刻的样本数据
• CI/CD：使用全面的测试数据验证系统行为

备注

• 生成器需要运行Docker Compose
• 它将 完全重置 数据库，删除所有现有数据
• 使用不同的种子生成不同的数据集
• 所有生成的数据均按照规范进行验证

配置

TasksMultiServer支持两个后备存储和多代理协调设置。

环境变量

创建一个 .env 文件或设置这些环境变量：

# Storage Backend (required)
DATA_STORE_TYPE=filesystem  # Options: "filesystem" or "postgresql"

# Filesystem Configuration (when DATA_STORE_TYPE=filesystem)
FILESYSTEM_PATH=/path/to/tasks  # Default: /tmp/tasks

# PostgreSQL Configuration (when DATA_STORE_TYPE=postgresql)
POSTGRES_URL=postgresql://user:password@localhost:5432/dbname

# Multi-Agent Coordination (optional)
MULTI_AGENT_ENVIRONMENT_BEHAVIOR=false  # Options: "true" or "false"

存储后端选项

文件系统（默认）

• 简单的基于文件的存储
• 无需设置数据库
• 适合单用户或开发使用
• 配置为 FILESYSTEM_PATH

export DATA_STORE_TYPE=filesystem
export FILESYSTEM_PATH=/home/user/tasks

PostgreSQL

• 强大的数据库存储
• 更适合多用户或生产使用
• 需要PostgreSQL 14+
• 配置为 POSTGRES_URL

export DATA_STORE_TYPE=postgresql
export POSTGRES_URL=postgresql://user:pass@localhost:5432/tasks

多智能体环境行为

控制多个代理同时工作时任务在“就绪任务”查询中的显示方式：

• false （默认）：两者都有 NOT_STARTED 和 IN_PROGRESS 任务已准备就绪

- 允许代理恢复中断的工作 - 适用于单代理或顺序工作流

• true：只有 NOT_STARTED 任务已准备就绪

- 防止多个代理处理同一任务 - 适用于并发多代理环境

export MULTI_AGENT_ENVIRONMENT_BEHAVIOR=true

Docker编写配置

对于Docker部署，创建一个 .env 项目根目录中的文件：

# .env file for docker-compose
DATA_STORE_TYPE=postgresql
POSTGRES_URL=postgresql://postgres:postgres@db:5432/tasks
MULTI_AGENT_ENVIRONMENT_BEHAVIOR=false

这 docker-compose.yml 在需要时自动包含PostgreSQL容器。

使用示例

带文件系统的MCP服务器

{
  "mcpServers": {
    "tasks-multiserver": {
      "command": "python",
      "args": ["-m", "src.interfaces.mcp.server"],
      "cwd": "/path/to/tasks-multiserver",
      "env": {
        "DATA_STORE_TYPE": "filesystem",
        "FILESYSTEM_PATH": "/home/user/.tasks"
      }
    }
  }
}

带PostgreSQL的MCP服务器

{
  "mcpServers": {
    "tasks-multiserver": {
      "command": "python",
      "args": ["-m", "src.interfaces.mcp.server"],
      "cwd": "/path/to/tasks-multiserver",
      "env": {
        "DATA_STORE_TYPE": "postgresql",
        "POSTGRES_URL": "postgresql://user:pass@localhost:5432/tasks",
        "MULTI_AGENT_ENVIRONMENT_BEHAVIOR": "true"
      }
    }
  }
}

Docker与PostgreSQL的组合

创建 .env:

DATA_STORE_TYPE=postgresql
POSTGRES_URL=postgresql://postgres:postgres@db:5432/tasks

运行：

docker-compose up

贡献

我们欢迎捐款！请看 贡献.md 用于：

• 开发环境设置
• 编码标准和指南
• 测试要求
• 拉取请求流程
• 质量标准

文档

入门指南

• 入门指南 -安装和基本使用
• 部署指南 -Docker和生产部署
• 贡献指南 -开发设置和贡献指南

指南

• 代理最佳实践 -使用该系统的AI代理的最佳实践
• 故障排除 -常见问题和解决方案

api参考

• MCP工具参考 -完整的MCP工具文档
• REST API参考 -完整的REST API文档
• 批量操作 -批量操作端点和示例
• 错误处理 -错误格式和处理策略

例子

• 搜索和筛选 -搜索示例和模式
• 依赖工作流 -处理任务依赖关系
• 批量操作 -批量操作示例
• 标签管理 -有效使用标签

建筑

• 架构概述 -系统架构与设计
• 数据模型 -核心数据结构
• 相关性分析 -依赖性分析算法

有关完整的文档索引，请参阅 docs/README.md.

建筑

遵循数据流的分层架构：

Interfaces (MCP/REST/UI)
    ↓
Orchestration (Business Logic)
    ↓
Data Delegation (Abstract Interface)
    ↓
Data Access (PostgreSQL/Filesystem)
    ↓
Storage (Database/Files)

许可证

麻省理工学院

链接

• github：https://github.com/YOUR_USERNAME/tasks-multiserver
• 问题：https://github.com/YOUR_USERNAME/tasks-multiserver/issues

备注：PyPI包将在第一个稳定版本发布后提供。