openai-compatible-task-master/README.md

使用MCP解析PRD文档并生成任务列表

# 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 等）：

```bash
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` 选项临时覆盖环境配置：

```bash
npx octm-cli parse-files --input example.md --log-level debug
```

## 输出格式

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

```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 文档
```

## 安装

```bash
npm install -g openai-compatible-task-master
```

## 特性

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