# OCTM CLI 使用指南

## 📘 基本概念
OCTM CLI 是一个命令行工具，用于：解析PRD文档并生成任务、更新和管理已生成的任务、查看任务列表和进度、支持多文件处理、提供完整的日志记录

## 🔧 命令行工具功能

### 1. 初始化项目
**命令**: `npx octm-cli init` - 通过交互式提示帮助你设置开发工具规则。

### 2. parse-files - 解析文件并生成任务
**命令**: `npx octm-cli parse-files [选项]`

**选项**: 
- `--input <paths>` (PRD文件路径，多个文件用"|"分隔，必填)
- `--output <path>` (输出任务文件路径，可选)
- `--tasks <number>` (生成任务数量，可选)
- `--additional-prompts <text>` (额外的提示信息，将优先于其他冲突的指令，可选)

**示例**: 
- 基本使用: `npx octm-cli parse-files --input examples/prd-example.md --output tasks/tasks.json --tasks 10`
- 多文件: `npx octm-cli parse-files --input "docs/part1.md|docs/part2.md|docs/part3.md" --output planning/tasks.json --tasks 15`
- 带额外提示: `npx octm-cli parse-files --input examples/prd-example.md --additional-prompts "优先考虑安全性，每个任务都必须包含安全相关的测试用例"`

### 3. updateTasks - 更新任务
**命令**: `npx octm-cli update-tasks [选项]`

**选项**: `--prompt <text>` (更新任务的提示内容，必填，应包含详细上下文、领域知识、代码结构等能帮助大模型理解并更好更新任务的信息), `--from-id <number>` (起始任务ID，可选，默认为1)

**示例**:
- 更新所有任务: `npx octm-cli update-tasks --prompt "更新所有测试策略，添加性能测试要求"`
- 更新特定任务: `npx octm-cli update-tasks --prompt "提高任务优先级并添加集成测试" --from-id 3`
- 提供详细上下文: `npx octm-cli update-tasks --prompt "根据最新的代码库结构(src/目录包含models/、controllers/、services/三个模块，使用Express框架和MongoDB数据库)和RESTful API设计规范，更新任务实现细节，尤其关注数据模型设计和API路由定义"`

### 4. listTasks - 查看任务列表
**命令**: `npx octm-cli list-tasks [选项]`

**选项**: 
- `--tasks-path <path>` (任务文件路径, 可选, 默认: tasks/tasks.json)
- `-d, --detail` (显示所有未完成任务的详细信息)

**示例**:
- 基本使用: `npx octm-cli list-tasks`
- 显示未完成任务详情: `npx octm-cli list-tasks -d`

### 5. setStatus - 更新任务状态
**命令**: `npx octm-cli set-status [选项]`

**选项**: 
- `--task-id <number>` (要更新状态的任务ID，必填，可使用复合ID如"1.2"更新子任务)
- `--status <status>` (新的任务状态，必填，可选值：pending、in-progress、done)
- `--summary <text>` (当状态为done时的任务完成总结，**状态为done时必填**)

**示例**:
- 标记为进行中: `npx octm-cli set-status --task-id 1 --status in-progress`
- 标记为已完成: `npx octm-cli set-status --task-id 2 --status done --summary "实现了基本功能，包括数据验证和错误处理"`
- 更新子任务状态: `npx octm-cli set-status --task-id 1.2 --status in-progress`

**注意事项**: 
- 已完成(done)的任务状态不能改回其他状态
- 状态值必须是pending、in-progress或done之一
- 任务ID必须存在于任务文件中
- `--summary` 参数是在状态为done时的必填项，用于提供任务完成的简要总结

**如何写好完成总结**:
1. 简明扼要地描述已实现的功能和解决的问题
2. 提及重要的实现细节和采用的技术方案
3. 指出任何潜在的限制或需要注意的事项
4. 如有适用，提及后续可能的优化方向

**完成总结示例**:
- 简单示例: `"实现了用户注册功能，支持邮箱验证，使用了表单验证以确保数据有效性"`
- 详细示例: `"实现了用户认证功能，包括登录、注册和密码重置。采用JWT进行身份验证，使用bcrypt加密密码。添加了必要的输入验证和错误处理。目前尚未支持第三方登录，可作为后续优化方向。"`

### 6. readTask - 读取任务详情
**命令**: `npx octm-cli read-task [选项]`

**选项**: `--task-id <number>` (要读取的任务ID，必填，可使用复合ID如"1.2"查询子任务)

**示例**:
- 读取指定任务: `npx octm-cli read-task --task-id 1`
- 读取子任务详情: `npx octm-cli read-task --task-id 1.2`

**输出信息**: 
- 任务基本信息(ID、标题、描述)
- 当前状态和优先级
- 依赖任务列表
- 如果任务已完成且有完成总结，将显示完成总结
- 详细实现信息
- 测试策略

### 7. breakupTask - 分解任务
**命令**: `npx octm-cli breakup-task [选项]`

**选项**: `--task-id <id>` (要分解的任务ID，必填), `--prompt <text>` (用于分解任务的提示内容，可选，建议包含详细的上下文信息、领域知识、代码结构等能帮助大模型理解并更好拆分任务的元素)

**示例**:
- 基本使用: `npx octm-cli breakup-task --task-id 3`
- 使用自定义提示: `npx octm-cli breakup-task --task-id 3 --prompt "将此任务分解为前端和后端两部分，并详细说明每部分的实现步骤"`
- 提供详细上下文: `npx octm-cli breakup-task --task-id 3 --prompt "请考虑项目使用React+TypeScript前端技术栈(组件位于src/components/，状态管理使用Redux)和Node.js后端(Express框架，使用MVC架构)，将此任务分解为UI组件开发、状态管理、API接口实现和数据库交互等子任务，并为每个子任务提供具体实现细节"`

**子任务管理**:
- 子任务使用层级结构的复合ID，格式为"父任务ID.子任务序号"(如"1.2"表示主任务1的第2个子任务)
- 二级子任务格式为"祖父任务ID.父任务序号.子任务序号"，例如"1.2.1"
- 子任务可以有自己的标题、描述、优先级和状态，继承父任务的依赖关系
- 子任务可以独立更新状态，可以进一步分解为更小的子任务

## 📋 最佳实践

查看详细的最佳实践指南: [OCTM CLI 最佳实践指南](../octm-best-practice.md)