OpenAI Compatible Task Master (OCTM)

一个强大的 CLI 工具（同时支持 MCP），旨在将无序的产品需求文档 (PRD) 或技术设计文档转化为结构化、有依赖顺序的可执行任务列表。

核心目标: 解决在使用 AI IDE 或 Copilot 类工具进行开发时，常常因为代码生成顺序混乱、依赖未实现而导致项目复杂度和维护成本激增的问题。OCTM 通过预先规划和任务排序，为 AI 辅助开发提供清晰的蓝图。

主要优势

结构化任务: 将模糊的需求或设计转化为具体的、可操作的开发任务。
依赖管理: 自动分析并确定任务间的执行依赖顺序。
AI 开发伴侣: 为 AI IDE (如 Cursor, Roo Code 等) 提供清晰的上下文和执行计划，避免生成无效或混乱的代码。
与 Roo Code Boomerang 模式的完美结合:
- OCTM 负责从文档生成宏观的任务规划和依赖。
- Roo Code 的 Boomerang 模式可以利用 OCTM 生成的任务列表，实现任务的自主追踪、下发、执行与状态反馈。
- 这种组合可以在弱人工监管下，实现高效、有序的 AI 辅助开发流程，显著提升开发效率和项目质量。

功能

读取 PRD 或技术文档并智能分析内容
调用 OpenAI 兼容的 AI 模型 API 进行深度分析和任务生成
生成包含依赖关系、优先级、状态的结构化任务列表
支持多文件输入，整合多个文档信息
提供任务更新、状态修改、详情查看等管理功能 (通过 octm-cli)
完整的日志记录系统

快速开始

运行以下命令初始化您的项目，并根据指引选择 CLI 或 MCP 模式以及您使用的 AI IDE 规则（如 Roo Code, Cursor 等）：

npx octm-cli init

这个命令会：

引导您选择使用方式（MCP 工具模式或命令行模式）
引导您选择对应的 AI IDE/助手（如 Cursor, Roo Code, Cline）
基于您的选择，创建优化的配置文件和 专属规则文件
自动设置 .gitignore（如果是 Git 仓库）
生成详细的使用文档 (usage.md)

专属规则文件的重要性: 我们为不同的 AI IDE 和开发助手（Cursor, Roo Code, Cline）精心制作了规则文件。这些规则文件：

指导 Agent: 清晰地告诉 Agent 如何理解和使用 OCTM 的各项功能。
优化集成: 确保 OCTM 能更好地融入您选择的开发环境的工作流。
提升效率: 让 Agent 更准确、高效地利用 OCTM 进行任务规划和管理。

运行 init 后，您可以按照交互式提示进行配置，之后就可以开始使用 npx octm-cli 命令来管理您的项目任务了。

主要功能说明 (`octm-cli`)

注意: 以下命令均通过 npx octm-cli 执行。

parsePRD

将 PRD 或技术文档解析为结构化的开发任务列表。

参数：

projectDir: 项目根目录路径
prdPaths: PRD 文件路径，多个文件用"|"分隔
tasksPath: 任务输出文件路径（可选，默认：tasks/tasks.json）
numTasks: 生成任务数量（可选，默认：5）

updateTasks

更新现有任务列表的内容。

参数：

projectDir: 项目根目录路径
tasksPath: 任务文件路径（可选，默认：tasks/tasks.json）
prompt: 更新提示内容
fromId: 起始任务ID（可选，默认：1）

listTasks

展示当前任务列表并提示下一个待处理任务。

参数：

projectDir: 项目根目录路径
tasksPath: 任务文件路径（可选，默认：tasks/tasks.json）

setStatus

更新指定任务的状态，注意：已完成（done）的任务状态不能改回。

参数：

projectDir: 项目根目录路径
tasksPath: 任务文件路径（可选，默认：tasks/tasks.json）
taskId: 要更新状态的任务ID
status: 新的任务状态，可选值：
- pending: 待处理
- in-progress: 进行中
- done: 已完成

readTask

读取单个任务的详细信息。

参数：

projectDir: 项目根目录路径
tasksPath: 任务文件路径（可选，默认：tasks/tasks.json）
taskId: 要读取的任务ID

breakupTask

将一个指定的父任务分解为更小的子任务。

参数：

projectDir: 项目根目录路径
tasksPath: 任务文件路径（可选，默认：tasks/tasks.json）
taskId: 要分解的父任务ID
prompt: 分解任务的提示内容（可选）

配置

本工具支持两种使用方式：命令行 (CLI) 模式 和 模型上下文协议 (MCP) 模式。推荐使用 CLI 模式进行日常管理，MCP 模式则便于与支持 MCP 的 AI IDE (如 Claude Desktop) 集成。

CLI 模式配置 (推荐)

创建 .env.octm 文件并配置以下参数：

OPENAI_API_KEY=your_api_key_here
OPENAI_API_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4
# PRD_PATH=/examples/prd-example.md # parse-prd 命令会通过 --input 指定
TASKS_PATH=tasks/tasks.json       # 默认任务文件路径
NUM_TASKS=5                       # parse-prd 默认生成任务数
STREAM_MODE=true                  # 是否使用流式输出，部分模型需要
LOG_LEVEL=info                    # 日志级别: error/warn/info/debug

MCP 工具模式配置

如果您希望将 OCTM 作为 MCP 工具（例如在 Claude Desktop 中使用），请添加以下配置：

{
  "mcpServers": {
    "prd-parser": { // 您可以自定义服务名称
      "command": "npx",
      "args": ["octm"], // 使用 MCP 入口
      "env": {
        "OPENAI_API_KEY": "你的API密钥",
        "OPENAI_API_URL": "https://api.openai.com/v1",
        "OPENAI_MODEL": "gpt-4",
        "STREAM_MODE": "true",
        "LOG_LEVEL": "info"
      }
    }
  }
}

日志级别说明：

error: 只显示错误信息
warn: 显示警告和错误信息
info: 显示一般信息、警告和错误（默认）
debug: 显示所有信息，包括调试信息

你也可以在命令行中使用 --log-level 选项临时覆盖环境配置：

npx octm-cli parse-prd --input example.md --log-level debug

输出格式

生成的任务文件采用以下 JSON 格式：

{
  "tasks": [
    {
      "id": 1,
      "title": "任务标题",
      "description": "任务描述",
      "status": "pending",
      "dependencies": [2, 3],
      "priority": "high",
      "details": "详细信息",
      "testStrategy": "测试策略"
    }
  ],
  "metadata": {
    "projectName": "项目名称",
    "totalTasks": 10,
    "sourceFile": "prd.md",
    "generatedAt": "2023-01-01T00:00:00.000Z"
  }
}

项目结构

src/
  ├── index.ts          # MCP 服务器入口 (npx octm)
  ├── command.ts        # 命令行工具入口 (npx octm-cli)
  ├── services/         # 核心服务实现 (被 index.ts 和 command.ts 调用)
  │   ├── parse_prd.ts    # PRD 解析服务
  │   ├── update_tasks.ts # 任务更新服务
  │   ├── list_tasks.ts   # 任务列表服务
  │   ├── set_status.ts   # 任务状态更新服务
  │   ├── read_task.ts    # 任务详情读取服务
  │   └── breakup_task.ts # 任务分解服务
  ├── llm/              # LLM 相关功能 (被 services 调用)
  │   ├── llm_utils.ts     # LLM工具函数
  │   ├── llm_parse_prd.ts # PRD解析LLM调用
  │   └── llm_update_tasks.ts # 任务更新LLM调用
  └── logging/          # 日志系统
      └── logger.ts     # 日志管理器
examples/
  └── prd-example.md    # 示例 PRD 文档

安装

npm install -g openai-compatible-task-master

特性

结构化任务规划: 将无序文档转化为有序、依赖明确的任务列表。
解决 AI 开发痛点: 为 AI IDE 提供清晰执行蓝图，避免混乱。
Roo Code Boomerang 协同: 实现自动化任务追踪与执行。
灵活的 LLM 支持: 支持多种 OpenAI 兼容的 API 端点。
高效多文档处理: 智能合并分析多个输入文件。
精细化任务管理: 提供创建、更新、分解、查询、状态修改等全方位 CLI 管理能力。
流式处理: 支持流式响应，实时获取 LLM 输出。
测试策略生成: 在任务中包含初步的测试策略建议。
日志系统: 完整的日志记录，便于调试。