Task Researcher

任务研究器

一个面向 AI 驱动开发的 Python 任务管理系统，集成了使用 knowledge-storm 库进行深入研究的功能。拆解复杂项目、生成任务，并利用自动化研究为实现细节提供依据。

此软件包同时提供命令行界面（CLI）和模型上下文协议（MCP）服务。

核心功能

• 解析输入：从项目规范文件（functional_spec.md、technical_spec.md、plan.md、background.md）生成初始任务。
• 扩展任务：
  • 使用 AI（通过 litellm 调用 claude、gemini 等）将任务拆解为子任务。
  • 由 STORM 驱动的研究（--research 标志）：对于复杂任务，自动确定研究问题，将其归类为主题，为每个主题运行 knowledge-storm 引擎，并利用汇总后的研究结果生成信息充分的子任务。
• 更新任务：根据新的提示词或需求变更修改待处理任务。
• 分析复杂度：使用 AI 评估任务复杂度，生成包含建议和定制扩展提示词的报告。（可使用 --research-hint 标志。）
• 依赖管理：验证并自动修复依赖问题（缺失引用、自依赖、简单循环）。
• 生成文件：为每个任务和子任务创建单独的 .txt 文件。
• 独立研究（research-topic）：使用 knowledge-storm 针对任意主题生成详细研究报告。

要求

• Python 3.10+
• 至少一个受支持的大模型提供商（例如 Anthropic、Google Gemini、OpenAI）的 API 密钥，并将其设置在 .env 文件中（用于生成任务、分析复杂度等）。
• knowledge-storm 库（pip install knowledge-storm）。
• 设置在 .env 中、由 knowledge-storm 支持的搜索引擎 API 密钥（例如 Bing Search、You.com、Tavily）（使用 expand 命令的 --research 标志和 research-topic 命令时必需）。
• （可选）如果以 MCP 服务模式运行，则需要 mcp 库（pip install mcp）。

安装

1. 克隆仓库：

   git clone <repository-url>
   cd task-researcher
   

2. 安装依赖（推荐使用 Poetry）：

   pip install poetry
   poetry install
   

3. 配置环境：
   • 将 .env.example 复制为 .env。
   • 填入主要的大模型 API 密钥（例如 ANTHROPIC_API_KEY）。
   • 为主要任务设置 LLM_MODEL（例如 "claude-3-5-sonnet-20240620"）。
   • 设置 STORM_RETRIEVER（例如 "bing"）及其对应的 API 密钥（BING_SEARCH_API_KEY）。
   • （可选）设置 BIG_STORM_MODEL 和 SMALL_STORM_MODEL，以便在 STORM 研究中使用不同的模型（例如速度更快或成本更低的模型）。
   • （可选）调整其他设置，例如 MAX_TOKENS、TEMPERATURE、文件路径等。

命令行界面（CLI）用法

使用 task-researcher 命令（如果通过 Poetry 脚本安装），或运行 python -m task_researcher。

# Show help
task-researcher --help

# Generate initial tasks from spec files in ./scripts/
task-researcher parse-inputs --num-tasks 20

# Analyze complexity (using primary LLM's knowledge)
task-researcher analyze-complexity --research-hint

# View the complexity report
task-researcher complexity-report

# --- Expanding Tasks ---

# Expand task 5 normally (using primary LLM)
task-researcher expand --id 5 --num 4

# Expand task 7 using the STORM research workflow (will ask for confirmation)
# Generates questions -> groups topics -> runs STORM -> generates subtasks w/ research)
# Will show research plan & token estimate, ask for confirmation before running STORM
task-researcher expand --id 7 --research

# Expand all eligible tasks using STORM research workflow
task-researcher expand --all --research

# Expand task 9, forcing overwrite, using STORM, with extra user context
task-researcher expand --id 9 --research --force --prompt "Ensure compatibility with React 19 features."

# --- Other Commands ---

# Update tasks from ID 4 onwards due to a change
task-researcher update --from 4 --prompt "Refactor authentication to use JWT instead of session cookies."

# Validate dependencies
task-researcher validate-deps

# Fix dependencies automatically
task-researcher fix-deps

# Generate individual .txt task files
task-researcher generate

# Generate a standalone research report on a topic using STORM
task-researcher research-topic "Comparison of Vector Databases for RAG" -o "reports/vector_db_comparison.md" --retriever tavily # Requires TAVILY_API_KEY

MCP 服务

此软件包也可以作为 MCP 服务运行，为 Claude Desktop、Cursor 等 MCP 客户端或自定义应用提供工具和资源。

运行服务：

poetry run task-researcher serve-mcp
# OR
poetry run python -m task_researcher.mcp.server

默认情况下，此命令使用 stdio 传输启动服务。

从客户端连接（示例：Claude Desktop）：

1. 打开 Claude Desktop 设置 -> Developer -> Edit Config。
2. 在 claude_desktop_config.json 的 mcpServers 中添加一项：

{
  "mcpServers": {
    "task-researcher": {
      // Adjust command based on your environment (Poetry vs. global python)
      // Option 1: Using Poetry
      "command": "poetry", // Or the full path to your poetry executable
      "args": [
        "run",
        "task-researcher", // The script name from pyproject.toml
        "serve-mcp"
      ],
      // Make sure poetry run executes in the correct project directory
      "options": {
          "cwd": "/absolute/path/to/your/task-researcher/project"
      }
      // Option 2: Assuming task-researcher is installed globally or in PATH
      // "command": "task-researcher",
      // "args": ["serve-mcp"]
      // Option 3: Direct Python execution
      // "command": "python", // Or python3 or full path
      // "args": [
      //     "-m",
      //     "task_researcher.mcp.server",
      //      // Specify the working directory if needed relative paths are used in config
      //      // or ensure .env is found relative to where python is run
      // ],
      // "options": { // Ensure correct working directory if needed
      //     "cwd": "/absolute/path/to/your/task-researcher/project"
      // }
    }
    // Add other servers here...
  }
}

3. 将 /absolute/path/to/your/task-researcher/project 替换为克隆仓库的实际路径。
4. 重启 Claude Desktop。

暴露的 MCP 工具：

• parse_inputs：根据配置的规范文件生成初始任务。
• update_tasks：根据提示词，从给定 ID 开始更新任务。
• generate_task_files：创建单独的 phase_XX_task_YYY.txt 文件。
• expand_task：将单个任务扩展为子任务（支持 STORM 的 research=True）。
• expand_all_tasks：扩展所有符合条件的待处理任务（支持 research=True）。
• analyze_complexity：分析任务复杂度并保存报告。
• validate_dependencies：检查依赖项是否存在问题。
• fix_dependencies：尝试自动修复依赖项问题。
• research_topic：运行 STORM，生成关于某个主题的研究报告。

（注意：通过 MCP 使用 expand_* --research 会跳过确认步骤。）

暴露的 MCP 资源：

• tasks://current：主 tasks.json 文件的内容。
• report://complexity：task-complexity-report.json 文件的内容。
• research://{topic_name}：指定主题生成的 STORM 报告内容。
• taskfile://{task_id_str}：指定 phase_XX_task_YYY.txt 文件的内容。

（工具和资源的准确定义及参数请参阅 mcp/server.py）。

--research 与 --research-hint

• expand --research：触发完整的 基于 STORM 的工作流：AI 生成问题 -> AI 对问题进行分组 -> knowledge-storm 运行网络搜索并综合报告 -> AI 使用综合报告作为上下文生成子任务。需要 knowledge-storm 和已配置的检索器 API 密钥。
• analyze-complexity --research-hint：修改执行复杂度分析的主 LLM提示词，要求其像研究助手一样，进一步利用自身的知识库。不会使用 knowledge-storm，也不会执行实时网络搜索。
• update --research-hint：与 analyze-complexity 类似，提示主 LLM 在处理更新提示词时使用其内部知识。

配置（.env）

请参阅 .env.example。主要设置包括：

• LLM_MODEL：用于任务、分析和子任务生成（非 STORM）的主模型。
• ANTHROPIC_API_KEY、GOOGLE_API_KEY 等：主 LLM 的凭据。
• STORM_RETRIEVER：STORM 的搜索引擎（bing、you、tavily 等）。
• BING_SEARCH_API_KEY、YDC_API_KEY、TAVILY_API_KEY 等：所选 STORM 检索器的密钥。
• BIG_STORM_MODEL：（可选）用于 STORM 内部处理的大模型。
• SMALL_STORM_MODEL：（可选）用于 STORM 内部处理的小模型。
• STORM_SEARCH_TOP_K、STORM_MAX_TOKENS_*：控制 STORM 的深度。
• 文件路径（TASKS_FILE_PATH 等）。

任务结构（tasks/tasks.json）

该结构遵循 task_master_py/models.py 中定义的 Pydantic 模型，包括 Task、Subtask 和 TasksData。

{
  "meta": {
    "projectName": "Task Master Project",
    "projectVersion": "0.1.2",
    "sourceFiles": ["scripts/plan.md", "..."],
    "generatedAt": "...",
    "totalTasks": 15
  },
  "tasks": [
    {
      "id": 1,
      "title": "Setup Project Environment",
      "phase": 1,
      "description": "Initialize project structure, install dependencies, configure linters.",
      "details": "...",
      "status": "pending",
      "dependencies": [],
      "priority": "high",
      "testStrategy": "Verify environment setup by running basic commands.",
      "subtasks": []
    },
    {
      "id": 2,
      "title": "Implement Core Data Models",
      "phase": 1,
      "description": "Define Pydantic models for tasks and reports.",
      "details": "...",
      "status": "pending",
      "dependencies": [1], // Depends on task 1
      "priority": "high",
      "testStrategy": "Unit tests for model validation.",
      "subtasks": [
        {
            "id": 1, // Subtask ID is relative to parent
            "title": "Define Task Model",
            "description": "...",
            "details": "...",
            "status": "pending",
            "dependencies": [], // Dependencies relative to sibling subtasks (ints)
            "acceptanceCriteria": "Pydantic model passes validation...",
        },
        {
            "id": 2,
            "title": "Define Report Model",
            "description": "...",
            "details": "...",
            "status": "pending",
            "dependencies": [1], // Depends on subtask 1
            "acceptanceCriteria": "Pydantic model passes validation...",
        }
      ]
    },
    // ... more tasks
  ]
}