Task Researcher

一个为 AI 驱动开发设计的 Python 任务管理系统，具有使用 knowledge-storm 库集成的、深入的研究能力。分解复杂项目，生成任务，并利用自动化研究来告知实现细节。

此软件包提供命令行界面 (CLI) 和模型上下文协议 (MCP) 服务器。

核心功能

• 解析输入: 从项目规范文件（functional_spec.md、technical_spec.md、plan.md、background.md）生成初始任务。
• 扩展任务:
  • 使用 AI（claude、gemini 等，通过 litellm）将任务分解为子任务。
  • STORM 驱动的研究 (--research 标志): 对于复杂任务，自动识别研究问题，将它们分组到主题中，为每个主题运行 knowledge-storm 引擎，并使用聚合的研究来生成高度知情的子任务。
• 更新任务: 根据新的提示或需求更改修改待处理的任务。
• 分析复杂性: 使用 AI 评估任务复杂性，生成包含建议和定制扩展提示的报告。（提供 --research-hint 标志）。
• 依赖管理: 验证并自动修复依赖问题（缺少引用、自依赖、简单循环）。
• 生成文件: 为每个任务和子任务创建单独的 .txt 文件。
• 独立研究 (research-topic): 使用 knowledge-storm 生成关于任何主题的详细研究报告。

要求

• Python 3.10+
• 至少一个受支持的 LLM 提供商（例如，Anthropic、Google Gemini、OpenAI）的 API 密钥，设置在 .env 文件中（用于任务生成、复杂性分析等）。
• knowledge-storm 库 (pip install knowledge-storm)。
• knowledge-storm 支持的搜索引擎（例如，Bing Search、You.com、Tavily）的 API 密钥，设置在 .env 中（expand 中的 --research 和 research-topic 命令需要）。
• （可选）mcp 库 (pip install mcp)，如果作为 MCP 服务器运行。

安装

1. 克隆存储库：

   git clone <repository-url>
   cd task-researcher
   

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

   pip install poetry
   poetry install
   

3. 配置环境：
   • 复制 .env.example 到 .env。
   • 填写您的主要 LLM 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。

# 显示帮助
task-researcher --help

# 从 ./scripts/ 中的 spec 文件生成初始任务
task-researcher parse-inputs --num-tasks 20

# 分析复杂性（使用主要 LLM 的知识）
task-researcher analyze-complexity --research-hint

# 查看复杂性报告
task-researcher complexity-report

# --- 扩展任务 ---

# 正常扩展任务 5（使用主要 LLM）
task-researcher expand --id 5 --num 4

# 使用 STORM 研究工作流程扩展任务 7（将要求确认）
# 生成问题 -> 分组主题 -> 运行 STORM -> 生成带有研究的子任务）
# 将显示研究计划和 token 估计，在运行 STORM 之前要求确认
task-researcher expand --id 7 --research

# 使用 STORM 研究工作流程扩展所有符合条件的任务
task-researcher expand --all --research

# 扩展任务 9，强制覆盖，使用 STORM，带有额外的用户上下文
task-researcher expand --id 9 --research --force --prompt "Ensure compatibility with React 19 features."

# --- 其他命令 ---

# 由于更改，从 ID 4 开始更新任务
task-researcher update --from 4 --prompt "Refactor authentication to use JWT instead of session cookies."

# 验证依赖项
task-researcher validate-deps

# 自动修复依赖项
task-researcher fix-deps

# 生成单独的 .txt 任务文件
task-researcher generate

# 使用 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 设置 -> 开发者 -> 编辑配置。
2. 在 claude_desktop_config.json 中添加一个 mcpServers 条目：

{
  "mcpServers": {
    "task-researcher": {
      // 根据您的环境调整命令（Poetry vs. 全局 python）
      // 选项 1：使用 Poetry
      "command": "poetry", // 或您的 poetry 可执行文件的完整路径
      "args": [
        "run",
        "task-researcher", // pyproject.toml 中的脚本名称
        "serve-mcp"
      ],
      // 确保 poetry run 在正确的项目目录中执行
      "options": {
          "cwd": "/absolute/path/to/your/task-researcher/project"
      }
      // 选项 2：假设 task-researcher 已全局安装或在 PATH 中
      // "command": "task-researcher",
      // "args": ["serve-mcp"]
      // 选项 3：直接 Python 执行
      // "command": "python", // 或 python3 或完整路径
      // "args": [
      //     "-m",
      //     "task_researcher.mcp.server",
      //      // 如果在配置中使用相对路径，请指定工作目录，
      //      // 或确保 .env 相对于 python 运行的位置找到
      // ],
      // "options": { // 如果需要，确保正确的工作目录
      //     "cwd": "/absolute/path/to/your/task-researcher/project"
      // }
    }
    // 在此处添加其他服务器...
  }
}

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

公开的 MCP 工具：

• parse_inputs: 从配置的 spec 文件生成初始任务。
• update_tasks: 根据提示更新给定 ID 之后的任务。
• generate_task_files: 创建单独的 phase_XX_task_YYY.txt 文件。
• expand_task: 将单个任务扩展为子任务（支持 research=True 用于 STORM）。
• 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 vs --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...",
        }
      ]
    },
    // ... 更多任务
  ]
}