Task Master 命令参考指南：AI 驱动的任务管理 CLI 全命令详解-编程实验室

Task Master 命令参考指南：AI 驱动的任务管理 CLI 全命令详解

【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master

导读

Task Master 是一个可以直接嵌入 Cursor、Lovable、Windsurf、Roo 等 AI 编码环境中的 AI 驱动任务管理系统。本文以项目官方文档 docs/command-reference.md 为主体，系统梳理task-masterCLI 的全部命令族：从 PRD 解析、任务增删改查、依赖管理、复杂度分析，到标签隔离、模型配置与联网研究，并深入仓库源码验证各命令的真实行为与底层调用链。读完本文，你将掌握每个命令的完整参数、适用场景与最佳实践，能够独立上手完成从 PRD 到任务落地、从状态推进到跨标签协作的完整工作流。

一、命令总览与架构背景

Task Master 的命令体系分为任务管理、认证上下文、工具类与开发工作流四类。在 apps/cli/src/command-registry.ts 中，CommandRegistry以集中式注册表统一管理所有命令，并通过registerAll(program)一次性注册到 Commander 程序实例上：

任务类命令：list、show、next、start、set-status、export、export-tag、tags
开发类命令：autopilot（TDD 编排）、loop（循环批处理）
认证与上下文命令：auth、login、logout、context、briefs
工具类命令：generate

并非所有命令都会触发 AI 处理。在 src/constants/commands.js 中定义了一组AI_COMMAND_NAMES：add-task、analyze-complexity、expand-task、parse-prd、research、research-save、update-subtask、update-task、update-tasks。这些命令会调用底层 LLM 生成或改写任务内容，其余命令则多为纯本地文件操作。

二、任务生成：从 PRD 到结构化任务

Parse PRD：解析产品需求文档

parse-prd命令读取一个 PRD 文本文件，由 AI 自动提取出结构化任务列表，是任务流水线的起点：

# 解析 PRD 文件并生成任务 task-master parse-prd <prd-file.txt> # 限制生成的任务数量（默认 10 个） task-master parse-prd <prd-file.txt> --num-tasks=5 # 允许 Task Master 根据复杂度自行决定任务数量 task-master parse-prd <prd-file.txt> --num-tasks=0

关键参数--num-tasks：默认值为 10；设置为 0 时，系统将依据 PRD 内容的复杂度动态决定任务数量，适合大型需求文档。该命令由 scripts/modules/task-manager/parse-prd/ 目录下的模块实现，支持流式解析与进度跟踪。

List Tasks：列表查询

# 列出所有任务 task-master list # 按状态筛选 task-master list --status=<status> # 列出任务及子任务 task-master list --with-subtasks # 组合：按状态筛选并展开子任务 task-master list --status=<status> --with-subtasks

<status>的合法取值由 src/constants/task-status.js 中的TASK_STATUS_OPTIONS定义，共 6 种：pending（等待开始）、done（已完成）、in-progress（进行中）、review（已完成待评审）、deferred（延期/暂停）、cancelled（已取消）。

在 apps/cli/src/commands/list.command.ts 的实现中，list还支持更多筛选与展示选项：list all等价于"展开全部子任务"，--ready只显示依赖已满足的可执行任务，--blocking只显示阻塞其他任务的任务，--all-tags跨标签汇总，--json/--compact/-c切换输出格式，-w / --watch进入监听模式自动刷新，--no-header隐藏头部。命令内部通过buildBlocksMap构建任务阻塞关系，并基于filterReadyTasks、filterBlockingTasks实现就绪与阻塞过滤。

Show Next Task：推荐下一个任务

# 基于依赖关系和状态显示下一个待执行任务 task-master next

next的推荐逻辑并非随机：从 apps/cli/src/commands/list.command.ts 的findNextTask实现可见，其排序优先级为——先考虑进行中父任务内未完成的子任务，再回退到顶层任务；按优先级（critical>high>medium>low）降序、依赖数量升序、ID 升序综合排序，同时过滤掉依赖未满足的任务。这一逻辑与 scripts/modules/task-manager/find-next-task.js 保持一致。

Show Specific Task：查看任务详情

# 查看单个任务详情 task-master show <id> # 或 task-master show --id=<id> # 用逗号分隔查看多个任务 task-master show 1,3,5 task-master show 44,55 # 查看指定子任务（如任务 1 的子任务 2） task-master show 1.2 # 混合父任务与子任务 task-master show 44,44.1,55,55.2

多任务展示模式：

单个 ID：显示完整任务详情视图，含完整实现说明；
多个 ID：显示紧凑摘要表格，并附带交互式操作菜单；
操作菜单：提供可直接复制粘贴的批量操作命令——全部标记为 in-progress/done、显示下一个可用任务、展开所有任务（生成子任务）、查看依赖关系、生成任务文件。

三、任务更新与状态流转

Update Tasks：批量更新任务

# 从指定 ID 开始更新任务并提供上下文 task-master update --from=<id> --prompt="<prompt>" # 使用研究角色进行更新 task-master update --from=<id> --prompt="<prompt>" --research

Update a Specific Task：更新单个任务

# 用新信息更新单个任务 task-master update-task --id=<id> --prompt="<prompt>" # 研究支撑的更新 task-master update-task --id=<id> --prompt="<prompt>" --research

Update a Subtask：追加子任务信息

# 向指定子任务追加信息 task-master update-subtask --id=<parentId.subtaskId> --prompt="<prompt>" # 示例：向任务 5 的子任务 2 追加 API 限流细节 task-master update-subtask --id=5.2 --prompt="Add rate limiting of 100 requests per minute" # 研究支撑的更新 task-master update-subtask --id=<parentId.subtaskId> --prompt="<prompt>" --research

关键区别：与update-task的"替换"语义不同，update-subtask是追加语义——新信息会被追加到已有子任务详情中并打上时间戳。这对于在保留原始内容的前提下迭代增强子任务非常有用。

Set Task Status：设置任务状态

# 设置单个任务状态 task-master set-status --id=<id> --status=<status> # 批量设置多个任务状态 task-master set-status --id=1,2,3 --status=<status> # 设置子任务状态 task-master set-status --id=1.1,1.2 --status=<status>

级联规则：当把任务标记为done时，其所有子任务也会被自动标记为done。状态的合法性校验由 src/constants/task-status.js 中的isValidTaskStatus函数保证。

四、任务分解与复杂度管理

Expand Tasks：展开子任务

# 为指定任务生成子任务 task-master expand --id=<id> --num=<number> # 动态数量展开（忽略复杂度报告） task-master expand --id=<id> --num=0 # 携带额外上下文展开 task-master expand --id=<id> --prompt="<context>" # 展开所有 pending 任务 task-master expand --all # 对已有子任务的任务强制重新生成 task-master expand --all --force # 研究支撑的子任务生成（单任务） task-master expand --id=<id> --research # 研究支撑的全量生成 task-master expand --all --research

--num=0表示让系统基于复杂度报告动态决定子任务数量；--force用于覆盖已有子任务重新生成。对应的底层实现位于 scripts/modules/task-manager/expand-task.js，其 LLM 调用由 src/prompts/expand-task.json 定义的提示模板驱动。

Clear Subtasks：清空子任务

# 清空指定任务的子任务 task-master clear-subtasks --id=<id> # 清空多个任务的子任务 task-master clear-subtasks --id=1,2,3 # 清空所有任务的子任务 task-master clear-subtasks --all

Analyze Task Complexity：复杂度分析

# 分析所有任务的复杂度 task-master analyze-complexity # 将报告保存到自定义位置 task-master analyze-complexity --output=my-report.json # 指定 LLM 模型 task-master analyze-complexity --model=claude-3-opus-20240229 # 设置自定义复杂度阈值（1-10） task-master analyze-complexity --threshold=6 # 使用替代任务文件 task-master analyze-complexity --file=custom-tasks.json # 使用 Perplexity AI 进行研究支撑的复杂度分析 task-master analyze-complexity --research

--threshold取值范围 1-10，用于界定"高复杂度"任务的分界线，复杂度分析结果会作为后续expand动态决策的输入。报告默认路径由 src/constants/paths.js 中的COMPLEXITY_REPORT_FILE定义为.taskmaster/reports/task-complexity-report.json。

View Complexity Report：查看复杂度报告

# 显示复杂度分析报告 task-master complexity-report # 查看自定义位置的报告 task-master complexity-report --file=my-report.json

五、依赖管理

# 为任务添加依赖 task-master add-dependency --id=<id> --depends-on=<id> # 移除任务依赖 task-master remove-dependency --id=<id> --depends-on=<id> # 校验依赖（不修复） task-master validate-dependencies # 自动查找并修复无效依赖 task-master fix-dependencies

依赖是 Task Master 调度逻辑的核心：next命令只会推荐"依赖已全部完成"的任务，list --ready同理。依赖校验与修复的详细逻辑可在 scripts/modules/task-manager/is-task-dependent.js 与 scripts/modules/task-manager/validate-dependencies.js 中查看。

六、任务重排与新增

Move Tasks：移动任务

# 将任务或子任务移动到新位置 task-master move --from=<id> --to=<id> # 示例：将任务移动为另一个任务的子任务 task-master move --from=5 --to=7 # 将子任务提升为独立任务 task-master move --from=5.2 --to=7 # 将子任务迁移到另一个父任务下 task-master move --from=5.2 --to=7.3 # 在同一父任务内重排子任务顺序 task-master move --from=5.2 --to=5.4 # 移动到新的 ID 位置（若不存在则创建占位） task-master move --from=5 --to=25 # 批量移动（from 与 to 的 ID 数量必须相等） task-master move --from=10,11,12 --to=16,17,18

move支持四种典型场景：任务转子任务、子任务提升为顶层任务、子任务跨父级迁移、同级子任务重排。实现位于 scripts/modules/task-manager/move-task.js。

Add a New Task：新增任务

# 使用 AI（主角色）新增任务 task-master add-task --prompt="Description of the new task" # 使用研究角色新增任务 task-master add-task --prompt="Description of the new task" --research # 新增带依赖的任务 task-master add-task --prompt="Description" --dependencies=1,2,3 # 新增指定优先级的任务 task-master add-task --prompt="Description" --priority=high

--priority的合法取值定义在 src/constants/task-priority.js 中：high（需立即处理的关键任务）、medium（标准优先级，也是默认值）、low（可延后或锦上添花的任务）。新增任务的 AI 输出结构由 src/schemas/add-task.js 定义并校验。

七、标签管理：多上下文任务隔离

Task Master 支持带标签的任务列表，用于多上下文任务管理。每个标签代表一个独立、隔离的任务上下文，任务之间互不干扰。

# 列出所有标签（含任务数与状态） task-master tags # 带元数据详细列出标签 task-master tags --show-metadata # 创建新的空标签 task-master add-tag <tag-name> # 创建带描述的标签 task-master add-tag <tag-name> --description="Feature development tasks" # 基于当前 git 分支名创建标签 task-master add-tag --from-branch # 复制当前标签的任务创建新标签 task-master add-tag <new-tag> --copy-from-current # 从指定标签复制任务创建新标签 task-master add-tag <new-tag> --copy-from=<source-tag> # 切换到不同标签上下文 task-master use-tag <tag-name> # 重命名已有标签 task-master rename-tag <old-name> <new-name> # 复制整个标签以创建新标签 task-master copy-tag <source-tag> <target-tag> # 带描述复制标签 task-master copy-tag <source-tag> <target-tag> --description="Copied for testing" # 删除标签及其全部任务（带确认） task-master delete-tag <tag-name> # 跳过确认直接删除标签 task-master delete-tag <tag-name> --yes

标签上下文规则：

所有任务操作（list、show、add、update 等）都在当前激活标签内执行；
大多数命令支持--tag=<name>标志，可在指定标签上下文中操作；
标签提供完全隔离——不同标签中的任务互不干扰。

从 scripts/modules/task-manager/tag-management.js 的实现可以补充几个关键细节：

命名约束：标签名仅允许字母、数字、连字符和下划线（正则^[a-zA-Z0-9_-]+$）；
保留名称：master、main、default为保留标签名，不可创建、重命名或删除master；
删除保护：删除含任务的标签时，即使使用 CLI 也会先弹出黄色警告框，要求双重确认（先确认，再输入标签名）；删除当前激活标签后会自动切回master；
数据组织：带标签的tasks.json采用{ tagName: { tasks, metadata } }结构，metadata记录创建时间与描述；切换标签的状态保存在.taskmaster/state.json中。

八、项目初始化与规则管理

Initialize a Project：初始化项目

# 使用 Task Master 结构初始化新项目 task-master init # 初始化时应用指定规则 task-master init --rules cursor,windsurf,vscode

--rules标志用于指定一个或多个规则配置文件（如cursor、roo、windsurf、cline）在初始化时应用；
若省略该标志，默认安装全部可用规则配置（claude、cline、codex、cursor、roo、trae、vscode、windsurf）；
单个命令中可使用逗号分隔多个配置。

Manage Rules：规则管理

# 向项目添加规则配置（如 .roo/rules、.windsurf/rules） task-master rules add <profile1,profile2,...> # 从项目移除规则集 task-master rules remove <profile1,profile2,...> # 绕过安全检查移除规则集（危险操作） task-master rules remove <profile1,profile2,...> --force # 启动交互式规则选择 # （不会重新初始化项目或询问 shell 别名） task-master rules setup

添加规则会创建对应的配置与规则目录（如.roo/rules）并复制/初始化规则文件；
移除规则会删除配置、规则目录及关联的 MCP 配置；
安全检查：尝试移除规则配置时会触发严重警告并要求确认，使用--force可绕过；
单条命令可同时处理多个逗号分隔的规则；
setup动作启动交互式提示来选择要应用的规则，可选列表始终与可用配置保持同步，无需手动更新；该命令不会重新初始化项目或影响 shell 别名，只负责交互式管理规则。

示例：

task-master rules add windsurf,roo,vscode task-master rules remove windsurf task-master rules setup

交互式规则设置

task-master rules setup

该命令会打开提示界面，让你选择要向项目添加的规则配置（如 Cursor、Roo、Windsurf）。它不会重新初始化项目或询问 shell 别名，仅管理规则。适用于项目创建后的交互式补充，且init在未通过--rules指定配置时，也会复用同一个交互式提示。

九、AI 模型配置

Configure AI Models：配置 AI 模型

# 查看当前 AI 模型配置与 API key 状态 task-master models # 设置主模型（若已知则自动推断 provider） task-master models --set-main=claude-3-opus-20240229 # 设置研究模型 task-master models --set-research=sonar-pro # 设置回退模型 task-master models --set-fallback=claude-3-haiku-20240307 # 为主角色设置自定义 Ollama 模型 task-master models --set-main=my-local-llama --ollama # 为研究角色设置自定义 OpenRouter 模型 task-master models --set-research=google/gemini-pro --openrouter # 为主角色设置 Codex CLI 模型（通过 OAuth 使用 ChatGPT 订阅） task-master models --set-main=gpt-5-codex --codex-cli # 为回退角色设置 Codex CLI 模型 task-master models --set-fallback=gpt-5 --codex-cli # 运行交互式配置（含自定义模型） task-master models --setup

配置存储：配置保存在项目根目录的.taskmaster/config.json中（旧版.taskmasterconfig文件会自动迁移）。API key 仍通过.env或 MCP 配置管理。不带任何标志运行task-master models可查看内置可用模型；--setup提供引导式配置体验。

状态存储：状态保存在项目根目录的.taskmaster/state.json中，维护当前标签等关键信息。请勿手动编辑此文件。

从 scripts/modules/task-manager/models.js 的实现可以补充的细节：

三角色体系：main（生成/更新主模型）、research（研究模型，如 Perplexity 的 sonar-pro）、fallback（回退模型，在主模型不可用时兜底）；
自定义 provider 提示：--ollama、--openrouter、--codex-cli等标志本质上是在告诉系统跳过内置模型库匹配，直接走自定义校验流程——Ollama 会实时请求本地http://localhost:11434/api/tags验证模型是否已拉取，OpenRouter 会实时请求其公开模型列表验证 ID，Azure、Vertex、LM Studio、OpenAI-compatible 等则按各自约定处理（如 OpenRouter 的:free模型会有限流/上下文警告）；
回写行为：设置模型时会同步写入maxTokens（若内置模型数据中存在），并正确处理各 provider 的baseURL保留与清理；
角色校验：role必须是main、research、fallback三者之一，否则返回INVALID_ROLE错误。

所有路径常量（.taskmaster/config.json、.taskmaster/state.json、.taskmaster/tasks/tasks.json等）统一定义于 src/constants/paths.js，并兼容旧版布局（如tasks/tasks.json、scripts/prd.txt）。

十、Research：联网研究新鲜信息

# 执行 AI 研究，获取新鲜、最新的信息 task-master research "What are the latest best practices for JWT authentication in Node.js?" # 携带任务上下文进行研究 task-master research "How to implement OAuth 2.0?" --id=15,16 # 携带文件上下文进行代码感知建议 task-master research "How can I optimize this API implementation?" --files=src/api.js,src/auth.js # 携带自定义上下文与项目树 task-master research "Best practices for error handling" --context="We're using Express.js" --tree # 使用不同详细程度 task-master research "React Query v5 migration guide" --detail=high # 禁用交互式追问（适合脚本化，也是 MCP 的默认行为） # 使用自定义任务文件位置 task-master research "How to implement this feature?" --file=custom-tasks.json # 在指定标签上下文中研究 task-master research "Database optimization strategies" --tag=feature-branch # 将研究对话保存到 .taskmaster/docs/research/ 目录（供后续参考） task-master research "Database optimization techniques" --save-file # 将关键结论直接保存到任务或子任务（推荐用于可执行洞察） task-master research "How to implement OAuth?" --save-to=15 task-master research "API optimization strategies" --save-to=15.2 # 组合上下文收集与自动保存结论 task-master research "Best practices for this implementation" --id=15,16 --files=src/auth.js --save-to=15.3

research 命令是强大的探索工具，提供：

超出 AI 知识截止时间的新鲜信息；
来自任务与文件的项目感知上下文；
基于模糊搜索的自动任务发现；
多种详细程度（low、medium、high）；
Token 计数与成本追踪；
用于深入探索的交互式追问；
灵活的保存选项（将结论提交到任务或保留对话）；
通过持续提问与精炼实现的迭代式发现。

建议高频使用 research 的场景：

实现功能前获取当前最佳实践；
研究新技术与库；
为复杂问题寻找解决方案；
验证实现方案；
跟进最新的安全建议。

CLI 交互特性：

追问：保持对话上下文，支持深度探索；
保存菜单：研究过程中或结束后提供灵活选项：
- 保存到任务/子任务：提交关键结论与可执行洞察（推荐）；
- 保存到文件：保留完整对话供后续参考；
- 继续探索：提出更多追问以深入挖掘；
自动文件命名：保存对话时使用时间戳与基于查询的 slug 自动生成文件名。

十一、最佳实践小结

从 PRD 开始：task-master parse-prd是标准入口，先让 AI 把需求转化为结构化任务，再手动微调；
善用--num-tasks=0：不确定任务粒度时，让系统根据复杂度自行决策，避免人工拍脑袋；
依赖先行：add-dependency与next配合使用，让系统自动推荐"现在该做什么"，减少上下文切换成本；
标签做隔离：多个功能分支并行时，用add-tag --from-branch建立独立上下文，用list --all-tags --ready跨标签聚合可执行任务；
研究驱动实现：写代码前用research --save-to=<taskId>把关键结论落回任务，实现时直接参考；
定期复杂度巡检：analyze-complexity+complexity-report识别高风险任务，优先拆分与排期；
配置持久化：模型配置集中维护在.taskmaster/config.json，状态文件.taskmaster/state.json不要手动编辑。

Task Master 命令参考指南：AI 驱动的任务管理 CLI 全命令详解