OpenAI Compatible Task Master (OCTM)

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

🚧 开发说明： 目前我们专注于完善和优化命令行（CLI）模式的功能。MCP（Model Context Protocol）模式的支持将在后续版本中重新引入，以提供更好的 AI IDE 集成体验。

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

主要优势

• 结构化任务: 将模糊的需求或设计转化为具体的、可操作的开发任务。
• 依赖管理: 自动分析并确定任务间的执行依赖顺序。
• AI 开发伴侣: 为 AI IDE (如 Cursor, Roo Code 等) 提供清晰的上下文和执行计划，避免生成无效或混乱的代码。
• 与 Roo Code 的完美结合:
  • OCTM 负责从文档生成宏观的任务规划和依赖。
  • Roo Code 强大的子任务执行能力可以利用 OCTM 生成的任务列表，实现任务的自主追踪、执行与状态反馈。
  • 通过 OCTM-BOOMERANG 模式，可以实现任务的自动分配和进度追踪。
  • 这种组合可以在弱人工监管下，实现高效、有序的 AI 辅助开发流程，显著提升开发效率和项目质量。
  • 补充说明：Roo Code 的 Orchestrator（原 Boomerang）模式现已成为原生模式。我们通过在项目 Scope 下创建自定义 boomerang-octm 模式，可以打开默认 Orchestrator 下不允许的操作（如读取命令行），实现更灵活的任务编排与自动化。

功能

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

快速开始

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

npx octm-cli init

这个命令会：

1. 引导您选择对应的 AI IDE/助手（如 Cursor, Roo Code, Cline）
2. 基于您的选择，创建优化的配置文件和 专属规则文件
3. 自动设置 .gitignore（如果是 Git 仓库）
4. 生成详细的使用文档 (usage.md)
5. 对于 Roo Code，自动配置 OCTM-BOOMERANG 模式，实现任务自动分配和追踪

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

• 指导 Agent: 清晰地告诉 Agent 如何理解和使用 OCTM 的各项功能。
• 优化集成: 确保 OCTM 能更好地融入您选择的开发环境的工作流。
• 提升效率: 让 Agent 更准确、高效地利用 OCTM 进行任务规划和管理。
• Roo Code 增强: 对于 Roo Code，额外提供了任务执行和追踪的增强功能，可以：
  • 自动分配和追踪子任务
  • 实时反馈任务执行状态
  • 智能调度任务执行顺序
  • 自动更新任务完成状态

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

主要功能说明 (octm-cli)

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

parse-files

将文件解析为结构化的开发任务列表。

参数：

• --input: 输入文件路径，多个文件用"|"分隔
• --output: 任务输出文件路径（可选，默认：tasks/tasks.json）
• --tasks: 生成任务数量（可选，默认：5）
• --additional-prompts: 额外的提示信息，将优先于其他冲突的指令（可选）

update-tasks

更新现有任务列表的内容。通过调用 AI 模型来智能更新指定任务及其后续任务的内容。

参数：

• --tasks-path: 任务文件路径（可选，默认：tasks/tasks.json）
• --prompt: 更新提示内容
• --from-id: 起始任务ID（可选，默认：1，支持数字或字符串格式如"1.2"）

list-tasks

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

参数：

• --tasks-path: 任务文件路径（可选，默认：tasks/tasks.json）
• -d, --detail: 显示所有未完成任务的详细信息（可选）

set-status

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

参数：

• --tasks-path: 任务文件路径（可选，默认：tasks/tasks.json）
• --task-id: 要更新状态的任务ID
• --status: 新的任务状态，可选值：
  • pending: 待处理
  • in-progress: 进行中
  • done: 已完成
• --summary: 当状态为done时的任务完成总结（状态为done时必填）。总结应包含已实现的功能、解决的问题、实现细节和注意事项

read-task

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

参数：

• --tasks-path: 任务文件路径（可选，默认：tasks/tasks.json）
• --task-id: 要读取的任务ID

breakup-task

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

参数：

• --tasks-path: 任务文件路径（可选，默认：tasks/tasks.json）
• --task-id: 要分解的父任务ID
• --prompt: 分解任务的提示内容（可选）

配置

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

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

日志级别说明：

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

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

npx octm-cli parse-files --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/
  ├── command.ts        # 命令行工具入口 (npx octm-cli)
  ├── services/         # 核心服务实现
  │   ├── 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 的完美结合: 实现自动化任务追踪与执行。
• 灵活的 LLM 支持: 支持多种 OpenAI 兼容的 API 端点。
• 高效多文档处理: 智能合并分析多个输入文件。
• 精细化任务管理: 提供创建、更新、分解、查询、状态修改等全方位 CLI 管理能力。
• 流式处理: 支持流式响应，实时获取 LLM 输出。
• 测试策略生成: 在任务中包含初步的测试策略建议。
• 日志系统: 完整的日志记录，便于调试。