Task Master AI 完整使用指南

项目地址：https://github.com/eyaltoledano/claude-task-master

官方文档：https://tryhamster.com/docs/taskmaster

npm 包：task-master-ai

适用工具：Codex App / Codex CLI / OpenCode / Claude Code / Cursor 等

阅读指南

Task Master 的内容分成两类：一类是一次性的安装配置与核心概念，另一类是日常开发时真正要复制执行的操作流程。原页面把规范工作流、进阶操作和完整命令参考都展开在同一层，阅读负担偏重；本版把重复内容合并到「开发执行操作手册」中，让用户按节点操作即可。

两种操作方式

仅终端命令（无 MCP 工具对应）：tm init、tm migrate、tm loop、tm autopilot、tm clusters——这些属于安装配置和自动化循环，不是日常任务操作。

本文结构

第一部分  安装与配置      ──── 一次性接入 Task Master、MCP、模型与项目目录
第二部分  核心概念        ──── 理解 PRD、Task、Subtask、Tag、依赖和模型角色
第三部分  开发执行操作手册 ──── 按 A-O 节点完成 PRD、任务、会话恢复、执行与变更
第四部分  FAQ 与 PRD 模板 ──── 保留常见故障处理和可直接复用的 PRD 模板

第一部分：安装与配置

1. 前置要求

2. 安装 Task Master

安装配置是一次性操作，只能在终端完成。

2.1 安装 npm 包

npm install -g task-master-ai

2.2 设置 tm 别名

安装后只有 task-master 命令，需要手动添加 tm 别名：

echo 'alias tm="task-master"' >> ~/.zshrc    # zsh
echo 'alias tm="task-master"' >> ~/.bashrc   # bash
source ~/.zshrc

验证：

tm --version   # 输出版本号即成功

3. 配置 AI 工具

本章把 Task Master 注册为 MCP 服务，让 AI 工具能调用它的工具。项目初始化在第 4 章进行。

3.1 Codex 配置

3.1.1 Codex 入口说明

三种入口共用同一份配置文件 ~/.codex/config.toml，配置一次全部生效：

3.1.2 安装并登录 Codex CLI（可选）

npm install -g @openai/codex
# 或：curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex login   # 浏览器 OAuth

只用 Codex App 不用 CLI 时，此步可跳过，直接手动创建 ~/.codex/config.toml。

3.1.3 注册 Task Master 为 MCP 服务

方式一：CLI 自动注册

codex mcp add task-master-ai -- npx -y task-master-ai

方式二：手动编辑 ~/.codex/config.toml

mkdir -p ~/.codex && touch ~/.codex/config.toml

写入：

[mcp_servers.task-master-ai]
enabled = true
command = "npx"
args    = ["-y", "task-master-ai"]

[mcp_servers.task-master-ai.env]
TASK_MASTER_TOOLS = "standard"

3.1.4 验证 MCP 是否生效

codex
/mcp
# 应看到 task-master-ai 及工具列表（standard 模式 15 个工具）

Codex App：Settings → MCP Servers → 确认 task-master-ai 已连接。

3.1.5 关于 AGENTS.md

AGENTS.md 是 Codex 的 AI 指令文件，Task Master 的集成指南会写入其中，告诉 AI 如何理解自然语言并调用对应的 MCP 工具。没有这个文件，自然语言触发 MCP 工具将不可靠。

Codex 按以下层级加载：

tm init --rules codex 执行后，Task Master 集成指南自动写入 ~/.codex/AGENTS.md，所有项目全局生效。

3.2 OpenCode 配置

3.2.1 注册 Task Master 为 MCP 服务

全局配置文件：~/.config/opencode/opencode.json

mkdir -p ~/.config/opencode
echo '{}' > ~/.config/opencode/opencode.json

写入（command 必须是数组格式）：

{
  "mcp": {
    "task-master-ai": {
      "type": "local",
      "command": ["npx", "-y", "task-master-ai"],
      "enabled": true,
      "env": {
        "TASK_MASTER_TOOLS": "standard"
      }
    }
  }
}

已有其他内容时，将 "mcp" 块合并进去，不要整个替换。

3.2.2 验证 MCP 是否生效

启动 OpenCode 后在对话中输入 /mcp，确认 task-master-ai 在工具列表中（standard 模式 15 个工具）。

3.3 其他工具（Claude Code / Cursor 等）

Claude Code 和 Cursor 都支持 Task Master，通过 tm init --rules claude-code 或 tm init --rules cursor 生成对应的 rules 文件。Rules 文件的作用与 AGENTS.md 相同：告诉 AI 如何把自然语言映射到 Task Master 的 MCP 工具调用。

tm init --rules cursor      # Cursor
tm init --rules claude-code # Claude Code

3.4 配置中转站（.env 文件）

在每个项目的根目录创建 .env 文件：

OPENAI_API_KEY=你的中转站Key
OPENAI_BASE_URL=https://你的中转站地址/v1

加入 .gitignore：

echo ".env" >> .gitignore

task-master-ai 自动读取项目根目录的 .env，终端 tm 命令和 MCP 调用均生效，无需在配置文件中重复填写。

4. 初始化项目

初始化是一次性操作，只能在终端完成。

4.1 新项目初始化

mkdir my-project && cd my-project
git init   # 可选但推荐

tm init --rules codex          # Codex 用户
tm init --rules opencode       # OpenCode 用户
tm init --rules codex,opencode # 同时使用两个

执行后按提示回答四个问题：

最后出现模型选择界面时选 Cancel 跳过，用中转站的用户必须手动编辑 config.json（见 4.3 节）。

4.2 已有项目接入

cd your-existing-project
tm init --rules codex

如果是旧版格式（tasks 文件在根目录而非 .taskmaster/），先迁移：

tm migrate

已有代码库的完整接入流程：

接入后，项目代码已经存在，部分功能可能已经实现了。推荐这样处理：

AI 对话：

我有一个已有的项目，刚接入了 Task Master，现在 tasks.json 里有一批任务。
请扫描项目的现有代码库，找出哪些任务描述的功能已经实现了，
把它们标记为 done，然后告诉我还有哪些任务需要做。

这样可以避免 AI 重新实现已有代码，让任务列表精确反映当前状态。

4.3 配置 AI 模型（.taskmaster/config.json）

交互界面不支持中转站配置，必须手动编辑 .taskmaster/config.json。

不要使用 codex-cli provider

codex-cli provider 尝试调用本地 codex 二进制命令，不支持自定义 API URL，中转站用户使用时必定报错：

Error: Codex CLI API error: Codex CLI exited with code 1

中转站用户必须使用 openai provider。

配置示例

{
  "models": {
    "main": {
      "provider": "openai",
      "modelId": "你的主模型ID",
      "maxTokens": 128000,
      "temperature": 0.2
    },
    "research": {
      "provider": "openai",
      "modelId": "你的调研模型ID（建议支持联网搜索）",
      "maxTokens": 128000,
      "temperature": 0.1
    },
    "fallback": {
      "provider": "openai",
      "modelId": "你的备用模型ID",
      "maxTokens": 128000,
      "temperature": 0.2
    }
  },
  "global": {
    "logLevel": "info",
    "debug": false,
    "defaultNumTasks": 10,
    "defaultSubtasks": 5,
    "defaultPriority": "medium",
    "projectName": "My Project",
    "responseLanguage": "Chinese",
    "enableCodebaseAnalysis": true,
    "anonymousTelemetry": true
  }
}

关键字段说明

⚠️ 修改 config.json 后必须重启 MCP 服务才能生效：

- Codex App：Settings → MCP Servers → 断开并重连

- OpenCode：Ctrl+C 退出后重新启动

4.4 初始化后的目录结构

your-project/
├── .taskmaster/
│   ├── config.json          # 模型配置（你手动编辑的）
│   ├── state.json           # 当前激活的 Tag（自动维护，勿改）
│   ├── tasks/
│   │   ├── tasks.json       # 默认 Tag 的任务数据
│   │   └── tasks_feature-auth.json  # 各 Tag 的任务文件
│   ├── docs/
│   │   └── prd.txt          # 放 PRD 文件
│   ├── reports/             # analyze-complexity 生成的复杂度报告
│   └── templates/
│       └── example_prd.txt  # PRD 格式参考
├── AGENTS.md / .cursor/rules/  # AI rules 文件（根据工具不同）
├── .env                     # API Keys（不提交 Git）
└── .gitignore

各文件作用说明：

4.5 .gitignore 配置

.env
.taskmaster/tasks/tasks.json.bak

应该提交到 Git 的文件：

.taskmaster/config.json
.taskmaster/docs/
.taskmaster/tasks/tasks.json
AGENTS.md

4.6 验证是否正常

终端：

tm list
# 返回空列表（无报错）说明正常

AI 对话：

查看当前所有任务，验证 Task Master 是否正常工作

第二部分：核心概念

5. Task Master 工作原理

5.1 它解决什么问题

AI 编程助手的核心问题：上下文丢失。写一个大项目时，AI 在长对话后会忘记之前的决策，开始产生矛盾的代码。

Task Master 的解法：把项目需求结构化为带依赖关系的任务图，每次会话让 AI 专注一个任务，任务完成后状态持久化到文件。上下文不在对话里，而在任务文件里。

5.2 核心组件

PRD 文件
   ↓ parse-prd 解析
任务列表（tasks.json）
   ↓ expand 拆解
子任务
   ↓ 执行
状态更新（done / blocked / in-progress）

5.3 三种模型的角色

.taskmaster/config.json 中配置了三个模型，各有不同用途：

如果只有一个 API Key，三个 modelId 填同一个模型也完全没问题，只是没有降级保护。

5.4 任务粒度参考

任务的大小直接影响 AI 的执行质量：

参考标准： 一个任务应该在 1 到 4 小时内可以完成实现和测试。如果你估计超过 4 小时，使用 expand 拆解它。

5.5 TASK_MASTER_TOOLS 工具集模式

控制 Task Master 向 AI 暴露多少工具，影响每次会话的 token 消耗：

配置方法：在 MCP 配置文件中设置环境变量 TASK_MASTER_TOOLS（见第 3 章的配置示例）。

Tag 上下文管理

Tag 用于任务上下文隔离，适合多功能分支并行开发、按阶段管理大项目、维护 backlog，以及隔离实验性探索。默认 Tag 是 master；切换 Tag 后，tm list、tm next、tm parse-prd 等命令都只作用于当前 Tag。独立分支功能的详细操作放在第三部分的 [M3] 节。

第三部分：开发执行操作手册

Task Master AI 开发执行操作手册（终极版）

核心理念：Task Master 解决的是 AI 的「会话失忆」问题。它把所有决策、进度、上下文都持久化到 .taskmaster/tasks/tasks.json，让任何新会话都能精确恢复，而不依赖对话历史。

使用方式：按节点顺序操作。每个节点都提供「AI 对话版」（直接粘贴，填 [方括号] 内容）和「终端命令版」，二选一。

完整执行链路

[A] 一次性初始化
        ↓
[B] 编写 PRD ──────────────────────────────────────────────┐
        ↓                                                  │
[C] 生成任务列表                                            │ 新功能/需求变更时
        ↓                                                  │ 重新进入对应节点
[D] 复杂度分析（必做，不要跳过）                              │
        ↓                                                  │
[E] 拆解子任务                                              │
        ↓                ┌──────────────────────────────────┘
[F] 会话开始 / 恢复上下文
        ↓
[G] 找下一个可执行任务
        ↓
[H] 开始执行任务
        ↓
[I] 实现中：持续记录进度（关键步骤）
        ↓
[J] 遇到阻塞？ ──→ 记录原因，跳到 [G] 找其他任务
        ↓ 未阻塞
[K] 标记完成，还有任务？──→ 回到 [G]
        ↓ 全部完成
[L] 会话收尾 & 生成恢复快照
        ↓
[下次会话] → 回到 [F]

                    ↕ 随时触发
[M] 新增功能        [N] 修改单任务      [O] 批量架构调整

[A] 一次性初始化（只做一次）

终端命令：

npm install -g task-master-ai
echo 'alias tm="task-master"' >> ~/.zshrc && source ~/.zshrc

# 进入项目目录后初始化（根据你使用的 AI 工具选一个）
tm init --rules codex          # Codex App / Codex CLI
tm init --rules opencode       # OpenCode
tm init --rules claude-code    # Claude Code

# 验证
tm list   # 返回空列表、无报错 = 成功

初始化后手动编辑 .taskmaster/config.json，填入 modelId（provider 用 openai，填中转站 Key），重启 MCP 服务。

[B] 编写 PRD

AI 对话：

你是一位资深产品经理和系统架构师。请根据我下方的需求描述，
参考 .taskmaster/templates/example_prd.txt 的格式规范，
为我生成一份高质量的 PRD 文档，写入 .taskmaster/docs/prd.txt。

PRD 必须满足以下质量标准：
1. 技术决策必须具体（例：JWT 需写明 Access Token 15分钟/Refresh Token 7天/存储在 HttpOnly Cookie 中）
2. 每个功能模块必须包含：功能列表、业务规则、完整的异常场景和错误码
3. 数据模型必须包含完整的字段定义、类型、约束和实体关系
4. 接口概览必须包含所有端点、方法、鉴权要求
5. 必须有「超出范围」章节，明确列出不实现的功能
6. 必须有「技术约束」章节，列出 AI 必须严格遵守的技术限制
7. 全文控制在 400-500 行，避免冗余

项目需求描述：
[详细描述你的项目，包括主要功能、用户角色、核心业务逻辑]

技术栈偏好：
[例：Next.js 15 + TypeScript + PostgreSQL + Prisma + TailwindCSS]

已知技术约束：
[例：不使用 ORM 直接写 SQL / 只用 REST 不用 GraphQL / 金额用整数分计算]

不需要实现的功能：
[例：移动端 App / 第三方登录 / 实时推送]

生成完成后，请告诉我 PRD 的结构摘要和你认为描述不够清晰、可能导致任务质量差的地方。

[C] 生成任务列表

AI 对话：

请执行以下操作：

1. 读取 .taskmaster/docs/prd.txt 的完整内容
2. 使用 parse_prd 工具解析该 PRD，生成任务列表，需要按照功能点进行拆分，任务数量控制在 10 个之内
3. 任务粒度要求：
   - 每个任务必须是独立可测试的功能单元
   - 每个任务预计实现时间在 2-8 小时之间
4. 生成完成后，用表格展示所有任务，包含：ID、标题、优先级、依赖关系

如果发现 PRD 中有模糊或矛盾的地方，先告诉我，等我确认后再执行。

终端命令：

tm parse-prd .taskmaster/docs/prd.txt --num-tasks=8
tm list

[D] 复杂度分析（必做，不要跳过）

AI 对话：

请对当前所有任务执行复杂度分析：

1. 使用 analyze_complexity 工具分析所有任务
2. 分析维度包括：技术复杂度、依赖链长度、不确定性、测试难度
3. 给每个任务打 1-10 的复杂度分数
4. 对评分 ≥ 7 的任务，明确说明：复杂的原因 + 建议拆成几个子任务，子任务拆分需要保持在 5 个之内
5. 用复杂度报告工具查看并输出完整报告

最后给我一个总结表：哪些任务评分 ≥ 7 需要拆解，哪些可以直接执行。

终端命令：

tm analyze-complexity
tm complexity-report

[E] 拆解子任务

AI 对话：

根据刚才的复杂度报告，请对所有评分 ≥ 7 的任务执行拆解：

1. 按照复杂度报告推荐的子任务数量进行 expand
2. 每个子任务必须满足：
   - 有明确的完成标准（Definition of Done）
   - 包含具体的实现细节和技术要求
   - 包含测试策略（单元测试/集成测试的具体场景）
3. 拆解完成后，列出所有子任务，让我确认粒度是否合适

如果某个任务评分 < 7 但我认为需要拆解，我会单独告诉你。

终端命令：

# 全部拆解
tm expand --all

# 或只拆指定任务
tm expand --id=4 --num=5

# 对拆解结果不满意时，清空重拆
tm clear-subtasks --id=4
tm expand --id=4 --num=6

[F] 会话开始 / 恢复上下文

F1：当天首次会话（新开始或跨天继续）

AI 对话：

我们开始新的开发会话。请执行以下操作帮我恢复完整上下文：

1. 使用 get_tasks 工具读取当前所有任务的完整状态
2. 统计并告诉我：
   - 总任务数 / 已完成数 / 进行中数 / 待开始数 / 被阻塞数
   - 整体完成进度百分比
3. 列出所有 in-progress 状态的任务和子任务，以及它们最近的 update-subtask 记录
4. 列出所有 blocked 状态的任务，以及阻塞原因
5. 使用 next_task 工具推荐下一个可执行的任务，说明推荐原因（基于优先级和依赖关系）

[如有上次会话结尾生成的摘要，粘贴在这里：]

终端命令：

tm list
tm list --ready       # 只看依赖已满足、可立即开始的任务
tm list --blocking    # 看正在阻塞其他任务的高优先级任务
tm next

F2：会话中途上下文压缩后恢复（对话被自动压缩）

AI 对话：

我们的对话上下文刚被压缩，我需要你重新同步项目状态。请立即执行：

1. 调用 get_tasks 工具，读取 .taskmaster/tasks/tasks.json 的完整内容
2. 找出所有 in-progress 状态的任务，读取这些任务的 subtask notes 字段，
   这里记录了我们在这次会话中做的所有操作和决策
3. 告诉我：当前正在进行的是哪个任务/子任务，上次记录的进度是什么
4. 直接从那个断点继续，不要重新开始

不要基于对话历史推断，要从 tasks.json 中的实际状态读取。

[G] 找下一个任务

AI 对话：

使用 next_task 工具，根据以下优先级规则推荐下一个任务：

优先顺序：
1. 当前有 in-progress 且未完成的任务/子任务（继续未完成的工作）
2. 依赖全部满足、优先级为 high 的 pending 任务
3. 被其他多个任务依赖的「阻塞型」任务（优先解锁后续任务）
4. 优先级 medium 的 pending 任务

告诉我：推荐任务的 ID、标题、推荐原因、预计工作量、所有子任务列表。

终端命令：

tm next

[H] 开始执行一个任务

AI 对话：

开始执行任务 [X]。请依次完成以下步骤：

1. 使用 set_task_status 工具将任务 [X] 标记为 in-progress
2. 使用 get_task 工具读取任务 [X] 的完整详情，包括：
   - 任务描述和实现要求
   - 所有子任务列表（按顺序）
   - 测试策略
   - 依赖的上游任务（确认它们确实已完成）
3. 分析当前代码库结构，找到与该任务相关的现有文件和代码
4. 告诉我实现方案和你准备从哪个子任务/步骤开始

在开始写代码前，先确认你对任务要求的理解，等我确认无误后再动手。

终端命令：

tm start --id=X       # 标记为 in-progress 并显示详情
tm show X             # 只查看详情不改状态
tm show X.1,X.2,X.3   # 同时查看多个子任务详情

[I] 实现过程中持续记录进度（核心步骤，务必执行）

这是解决跨会话记忆丢失的关键。 每完成一个关键步骤、做了重要决策、遇到问题时，立即记录到子任务的 notes 中。这些记录是跨会话恢复上下文的唯一可靠来源。

每完成一个子步骤后执行：

AI 对话：

子任务 [X.Y] 有进展，请使用 update_subtask 工具追加以下记录：

完成内容：[描述做了什么，具体到函数名/文件名/关键逻辑]
实现方案：[选择了什么技术方案，为什么选这个而不是其他]
涉及文件：[修改或新建了哪些文件，具体路径]
关键决策：[有什么架构决策或重要取舍]
注意事项：[后续任务需要知道的约束或前提]
下一步：[子任务 [X.Y] 完成后，下一步是 [X.Z]]

终端命令：

tm update-subtask --id=X.Y --prompt="完成内容：实现了 JWT 生成函数 generateAccessToken()，位于 src/auth/jwt.service.ts。方案：使用 jsonwebtoken@9.x，Access Token 15分钟，Refresh Token 7天，存储在 HttpOnly Cookie。关键决策：Refresh Token 用 Redis 存储而非数据库，性能更好。涉及文件：src/auth/jwt.service.ts（新建），src/config/redis.config.ts（修改）。下一步：子任务 X.3 实现登录端点。"

遇到问题时记录（不要只标记 blocked，要写清楚原因）：

AI 对话：

子任务 [X.Y] 遇到阻塞，请使用 update_subtask 工具记录，然后用 set_task_status 标记为 blocked：

阻塞描述：[具体是什么问题]
已尝试方案：[试过哪些方法，为什么不行]
需要的信息/资源：[需要什么才能解除阻塞]
临时绕过方案：[有没有可以先绕过的方式]
影响范围：[这个阻塞会影响哪些后续任务]

记录完成后，帮我用 next_task 找其他可以先做的任务。

[K] 标记完成，推进下一个

AI 对话（推荐一步到位）：

任务 [X] 的所有子任务都已完成，请执行：

1. 确认所有子任务的 status 都是 done，如果有遗漏帮我批量更新
2. 将任务 [X] 整体标记为 done
3. 在任务 [X] 的最终 update_subtask 记录中写入：
   - 任务完成摘要（最终实现了什么）
   - 关键技术决策汇总
   - 对后续任务的影响（后续任务需要知道的前提条件）
4. 使用 next_task 工具推荐下一个任务

不要重置任何已有记录，只追加完成摘要。

终端命令：

tm set-status --id=X.Y --status=done   # 完成子任务
tm set-status --id=X --status=done     # 完成整个任务
tm next

[L] 会话结束前收尾（必须执行，保障下次会话能无缝恢复）

AI 对话（直接复制，不需要修改）：

本次开发会话即将结束。请执行完整的收尾流程，确保下次会话可以无缝恢复：

第一步：更新任务状态
- 把本次会话中已完成的所有任务和子任务标记为 done
- 把还在进行中但未完成的任务保持 in-progress 状态
- 把本次发现的新问题或遗漏事项用 add_task 创建为新任务

第二步：写入断点记录
对每个 in-progress 的子任务，使用 update_subtask 追加一条断点记录，内容包括：
- 当前完成到哪个步骤（具体描述，不要模糊）
- 下次继续需要从哪里开始（具体的下一个操作）
- 当前文件状态（修改了哪些文件，是否有未保存/未提交的内容）
- 本次会话的关键决策（架构选择、技术方案等）
- 需要注意的坑或约束

第三步：生成恢复快照
生成一份结构化的「下次会话启动提示词」，格式如下：

---
【下次会话恢复提示词】

当前项目状态：[X个任务已完成 / Y个进行中 / Z个待开始]

正在进行的任务：
- 任务[ID]「[标题]」：已完成[具体步骤]，下次从[具体断点]继续

本次会话关键决策：
- [决策1：选择了XX方案，原因是YY]
- [决策2：...]

待处理的问题：
- [问题1]
- [问题2]

下次会话第一步：[明确的第一个操作]
---

把上面这段提示词完整输出，我会保存备用。

[F→恢复] 下次会话恢复

AI 对话（粘贴上次生成的恢复提示词，或直接用通用版本）：

我们继续上次的开发工作。

上次会话结束时的状态摘要：
[粘贴上次生成的「下次会话恢复提示词」内容]

请执行以下步骤：
1. 使用 get_tasks 工具读取当前所有任务的实际状态（以 tasks.json 为准，不以我的描述为准）
2. 找出所有 in-progress 任务的最新 update-subtask 记录，确认断点位置
3. 告诉我确认后的当前状态（如果 tasks.json 的状态和我的描述有出入，以 tasks.json 为准并告诉我差异）
4. 直接从断点处继续执行，不要重新开始

如果没有上次摘要，直接读取 tasks.json 并给我一个状态总结。

[M] 新增功能

M1：新增独立小功能（不影响现有任务）

AI 对话：

我需要新增一个功能，请按以下步骤处理：

新功能描述：[详细描述功能需求，包括业务逻辑和技术要求]
技术方案（如有想法）：[描述实现思路，或让 AI 提供建议]
优先级：[high / medium / low]
依赖关系：[这个任务需要在哪些已有任务完成后才能开始？]

请执行：
1. 使用 add_task 工具创建这个新任务，任务描述要包含完整的实现细节和测试策略
2. 设置正确的优先级和依赖关系
3. 分析这个新任务的复杂度，如果 > 6 分，拆解成子任务
4. 用 validate_dependencies 检查依赖关系是否有效
5. 告诉我新任务已插入任务列表的哪个位置，以及对整体计划的影响

终端命令：

tm add-task --prompt="[任务描述，包含完整实现细节]" --priority=medium
tm add-dependency --id=新任务ID --depends-on=X
tm validate-dependencies

M2：新增较大功能（需要写 PRD 追加）

AI 对话：

我需要新增一个较大的功能模块，需要独立 PRD 和任务列表。请按步骤执行：

功能模块名称：[功能名]
核心需求：[功能的核心业务逻辑和技术要求]

第一步：生成功能 PRD
参考 .taskmaster/templates/example_prd.txt 的格式，
为这个功能生成一份 PRD，写入 .taskmaster/docs/[功能名]-prd.txt。
PRD 需要考虑与现有系统的集成点和接口依赖。

第二步：追加任务（重要：使用 append 模式，不要覆盖现有任务）
使用 parse_prd 工具以追加模式解析该 PRD，生成 5-8 个新任务。

第三步：建立依赖关系
分析新任务与现有任务的依赖关系，正确设置 depends-on。

第四步：复杂度分析 + 拆解
对新任务执行复杂度分析，拆解评分 ≥ 6 的任务。

最后告诉我：新增了哪些任务，它们插入到整体计划的哪里，对现有任务的时间线有什么影响。

终端命令：

tm parse-prd .taskmaster/docs/新功能-prd.txt --append
tm analyze-complexity

M3：新增独立分支功能（需要 Tag 隔离）

AI 对话：

我需要在一个独立分支上开发新功能，要与主线任务隔离。请执行：

功能分支名：[feature/功能名]
功能描述：[功能需求]

执行步骤：
1. 使用 add_tag 工具，根据当前 git 分支名创建对应 Tag
2. 使用 use_tag 切换到该 Tag
3. 生成功能 PRD 写入 .taskmaster/docs/[功能名]-prd.txt
4. 解析 PRD 生成任务列表（在当前 Tag 下，不影响主线）
5. 执行复杂度分析和拆解
6. 告诉我当前激活的 Tag 是什么，以及主线任务是否受到任何影响

完成后提示我：切回主线时需要用 tm use-tag master。

终端命令：

git checkout -b feature/功能名
tm add-tag --from-branch
tm use-tag feature-功能名
tm parse-prd .taskmaster/docs/功能名-prd.txt
tm use-tag master    # 切回主线

[N] 修改功能

N1：修改单个子任务的实现方案（追加记录，保留历史）

AI 对话：

子任务 [X.Y] 的实现方案需要调整，请使用 update_subtask 工具追加一条变更记录：

变更原因：[为什么需要修改，例如：发现原方案存在性能问题/需求理解有误]
原方案：[原来打算怎么做]
新方案：[改用什么方案]
影响的文件：[哪些文件需要修改]
是否影响其他子任务：[如果有影响，具体是哪些，如何处理]

注意：只追加记录，不要删除原有内容。原有内容保留作为历史记录。

终端命令：

tm update-subtask --id=X.Y --prompt="[变更记录：原方案/新方案/原因/影响文件]"

N2：修改整个任务的定义（覆盖重写）

AI 对话：

任务 [X] 的整体定义需要重新描述，请使用 update_task 工具覆盖重写：

修改原因：[为什么需要重新定义，例如：需求理解有偏差/技术方案彻底变了]
新的任务描述：[完整的新定义，包含：
  - 任务目标
  - 具体实现要求（技术细节）
  - 完成标准
  - 测试策略
  - 与其他任务的接口约定
]

注意：这会完全替换原有内容，请确认后再执行。
执行后，请检查该任务的子任务是否也需要更新，如需要请告诉我。

终端命令：

tm update-task --id=X --prompt="[完整的新任务描述]"

[O] 批量架构调整（影响多个后续任务）

AI 对话：

项目架构/技术方向发生了重大变化，需要批量更新后续任务。请按步骤执行：

变化描述：[具体描述架构变化，例如：从 REST API 改为 GraphQL / 从单体改为微服务 / 更换数据库]
影响起点：[从任务 [X] 开始受影响，任务 [X] 之前已完成的不受影响]
变化原因：[为什么需要做这个调整]
需要遵守的新约束：[调整后必须遵守的技术规范]

执行步骤：
1. 先联网查一下 [相关技术] 的当前最佳实践（如有必要）
2. 使用 update 工具，从任务 [X] 开始，批量重写所有待做任务
3. 已完成（done）的任务不要改动
4. 重写后，使用 validate_dependencies 检查依赖关系是否仍然有效
5. 重新执行复杂度分析，看哪些任务需要重新拆解
6. 给我一个变更摘要：修改了哪些任务，每个任务的主要变化是什么

请在开始之前先列出会受影响的任务列表，等我确认后再执行批量重写。

终端命令：

tm update --from=X --prompt="[架构变化描述和新的技术约束]" --research
tm validate-dependencies
tm fix-dependencies    # 如果有无效依赖
tm analyze-complexity  # 重新分析

长会话中途刷新上下文（超过 1 小时的会话建议执行）

AI 对话：

我们已经工作了一段时间，请快速同步一下当前状态，防止上下文漂移：

1. 使用 get_tasks 读取当前任务状态，确认哪些任务/子任务的状态已更新
2. 检查我们在本次会话中做的代码修改，是否与任务的实现要求一致
3. 确认当前遵循的技术约束和架构决策是否发生了变化
4. 如果发现任何状态不一致，告诉我

一句话总结：我们在哪里，下一步是什么。

快速参考：三类 update 命令如何选择（update 三种命令）

需要更新任务时，选哪个命令？
│
├─ 记录实现过程中发生的事（追加，不覆盖历史）
│   └─ update-subtask --id=X.Y --prompt="[进度记录]"
│
├─ 某个任务的定义错了/方向变了（覆盖单任务）
│   └─ update-task --id=X --prompt="[新任务定义]"
│
└─ 项目架构/技术栈方向性调整（影响多个后续任务）
    └─ update --from=X --prompt="[架构变化描述]"

快速参考：会话开始必说的话

查看当前所有任务的状态，告诉我整体进度（已完成/进行中/待开始/阻塞），
列出所有 in-progress 任务的最新进度记录，
然后推荐我下一个应该做什么任务。

快速参考：任务完成后必说的话

任务 [X] 全部子任务已完成，
把任务 [X] 标记为 done，写入完成摘要和关键决策记录，
然后告诉我下一个应该做什么任务。

快速参考：会话结束前必说的话

本次会话结束，请：
1. 更新所有任务状态（已完成的标 done，未完成的保持 in-progress 并写入断点记录）
2. 将本次的关键决策和注意事项写入对应子任务的 update-subtask 记录
3. 生成下次会话的恢复提示词（包含当前状态摘要、正在进行的任务、下次第一步操作）

任务状态速查

第四部分：高级操作

Task Master AI 进阶操作手册

与基础手册的分工：本手册是 taskmaster-ultimate-guide.md 的配套文档，不重复基础操作。

本手册专注于：依赖精细化管理、结构重组、自动化执行、Tag 全生命周期、research 深度使用、已有项目接入、任务清理维护、Token 优化。

使用方式：每个节点提供「AI 对话版」（直接复制粘贴，填 [方括号] 内容）和「终端命令版」，二选一。

一、已有项目接入

已有代码库不从零开始，先扫描现有代码标记已完成任务，再执行剩余任务。

1.1 接入并识别已完成任务

AI 对话：

我有一个已有的代码库，刚接入了 Task Master，tasks.json 里已生成一批任务。
请执行以下操作，避免 AI 重新实现已有代码：

第一步：读取任务列表
使用 get_tasks 工具获取当前所有任务和子任务的完整列表。

第二步：扫描现有代码库
逐一检查每个任务描述的功能是否已在代码中实现，判断标准：
- 对应的文件/函数/模块是否存在
- 实现逻辑是否与任务描述一致（不要求完全一致，核心功能实现即可）
- 如有测试，测试是否通过

第三步：批量更新状态
- 功能已完整实现 → 标记为 done，并用 update_subtask 写入一条记录：
  「已有代码实现，文件路径：[具体路径]，主要函数/类：[名称]」
- 功能部分实现 → 保持 pending，用 update_subtask 写入：
  「已有部分实现（[具体说明]），还需完成：[剩余工作]」
- 功能未实现 → 保持 pending，不做修改

第四步：输出接入报告
用表格展示：已标记 done 的任务数、部分实现的任务数、完全未实现的任务数，
以及建议的下一步起始任务。

终端命令：

tm list          # 查看全部任务
tm next          # 获取第一个可执行任务

1.2 旧版项目结构迁移（tasks 文件在根目录而非 .taskmaster/）

终端命令：

tm migrate       # 自动迁移旧版目录结构
tm list          # 验证迁移成功

二、依赖关系精细化管理

依赖图的质量决定了 tm next 推荐的准确性。设计不合理的依赖会导致可并行的任务被串行化，或出现循环依赖死锁。

2.1 设计合理的依赖图（添加依赖前先分析）

AI 对话：

在添加依赖关系之前，我需要先验证设计是否合理。
请分析当前所有任务，检查以下几点：

1. 找出所有真正存在前后置关系的任务对：
   「任务 A 必须在任务 B 完成后才能开始」的充分条件是：
   - A 需要调用 B 暴露的接口/函数
   - A 需要 B 创建的数据库表/数据结构
   - A 是 B 功能的扩展，依赖 B 的核心逻辑
   
2. 找出可以并行执行的任务（无真实依赖关系），不应设置依赖

3. 检查现有依赖配置中是否存在：
   - 循环依赖（A→B→C→A）
   - 过度依赖（把所有任务串成一条链，导致无法并行）
   - 缺失依赖（任务实际上依赖另一个任务但没有设置）

4. 以依赖图的形式展示当前任务关系（用文字表示），
   标出哪些任务可以立即开始、哪些在等待

基于分析结果，列出需要添加或移除的依赖关系，等我确认后再执行。

2.2 添加、移除依赖

AI 对话（添加依赖）：

请为以下任务设置依赖关系：

需要设置的依赖：任务 [A] 依赖任务 [B]
依赖原因：[说明为什么 A 必须在 B 完成后才能开始，例如：A 需要调用 B 实现的 getUserById() 函数]

执行步骤：
1. 先确认任务 [B] 当前状态是否为 done 或 in-progress（如果已完成，这个依赖设置没有实际阻塞意义）
2. 使用 add_dependency 工具设置 A 依赖 B
3. 使用 validate_dependencies 确认依赖链没有产生循环
4. 告诉我：设置后，任务 A 的可执行条件变成了什么

注意：不要盲目添加依赖。只有 A 真正需要 B 的输出才应设置依赖。

AI 对话（移除依赖）：

请移除任务 [A] 对任务 [B] 的依赖关系。

移除原因：[说明为什么这个依赖不再需要，例如：A 已经不再调用 B 的接口，改用独立实现]

执行：
1. 使用 remove_dependency 工具移除该依赖
2. 用 tm list --ready 检查移除后是否有新的任务变为可执行状态
3. 告诉我移除后受影响的任务列表（哪些任务因此解锁）

终端命令：

tm add-dependency --id=A --depends-on=B      # 任务 A 依赖任务 B
tm remove-dependency --id=A --depends-on=B   # 移除依赖

2.3 依赖验证与修复全流程

AI 对话：

请对当前所有依赖关系执行完整的验证和修复流程：

第一步：运行验证
使用 validate_dependencies 工具检查以下问题：
- 循环依赖（会导致任务永远无法开始）
- 引用了不存在的任务 ID（任务被删除后遗留的无效依赖）
- 自引用（任务依赖自己）

第二步：展示问题
用列表展示所有发现的问题，每个问题说明：
- 问题类型（循环/无效引用/自引用）
- 涉及的任务 ID
- 问题的影响（哪些任务因此无法开始）

第三步：修复方案
对每个问题给出建议的修复方案，而不是直接自动修复。
让我确认修复方案后再执行 fix_dependencies。

如果没有问题，告诉我依赖图验证通过，当前有多少个任务可以立即开始。

终端命令：

tm validate-dependencies   # 检查所有问题
tm fix-dependencies        # 自动修复（执行前先手动验证一遍）

2.4 识别和处理阻塞链

AI 对话：

我需要了解当前项目的任务阻塞情况，帮我做一次全面的阻塞分析：

1. 使用 get_tasks 获取所有任务状态
2. 找出所有 blocked 状态的任务：
   - 列出每个被阻塞任务的阻塞原因（从 update-subtask notes 中读取）
   - 判断阻塞是否可以解除（技术问题已解决？外部依赖已到位？）
3. 找出正在阻塞多个后续任务的「关键路径任务」：
   - 如果完成这个任务，会同时解锁哪些其他任务
4. 给出优先级建议：
   - 哪个任务完成后能解锁最多后续工作（关键路径优先）
   - 哪些 blocked 任务现在可以重新开始（阻塞原因已消除）

以树状结构展示阻塞链：
[阻塞任务] → [被阻塞任务1] → [进一步被阻塞的任务]

终端命令：

tm list --blocking   # 显示正在阻塞其他任务的关键任务
tm list --ready      # 显示所有依赖已满足、可立即开始的任务

三、任务结构重组（move）

move 用于调整任务的层级结构和顺序。适用于：任务粒度发现不对、子任务实际上应该独立、父子关系需要重新归类等场景。

3.1 何时需要重组（使用前先判断）

需要用 move 吗？
│
├─ 某个顶级任务太大，更适合作为另一个任务的子任务？
│   └─ move --from=任务ID --to=父任务ID
│
├─ 某个子任务变得很重要，应该独立成顶级任务？
│   └─ move --from=父任务ID.子任务N --to=新任务ID（空位）
│
├─ 子任务执行顺序有误，需要调整？
│   └─ move --from=父.旧位置 --to=父.新位置
│
├─ 某个任务应该放到不同的 Tag 下执行？
│   └─ move --from=ID --from-tag=源Tag --to-tag=目标Tag
│
└─ 以上都不是 → 不需要 move，考虑用 update-task 修改描述

3.2 顶级任务 → 变为子任务（任务降级）

AI 对话：

任务 [X] 目前是一个独立的顶级任务，但我认为它更适合作为任务 [Y] 的子任务，
因为 [说明原因：例如：任务 X 只是任务 Y 的一个实现步骤，而不是独立功能]。

请执行以下操作：
1. 先用 get_task 读取任务 [X] 和任务 [Y] 的完整详情，确认层级关系合理
2. 检查任务 [X] 是否有自己的子任务——如果有，告诉我移动后这些子任务的归属
3. 检查其他任务是否依赖任务 [X]——移动后这些依赖关系需要更新
4. 使用 move 工具将任务 [X] 移动为任务 [Y] 的子任务
5. 确认移动后运行 validate_dependencies 检查依赖关系是否仍然有效
6. 告诉我移动后任务 [Y] 的完整子任务列表

终端命令：

tm move --from=X --to=Y          # 任务 X 变为任务 Y 的子任务
tm validate-dependencies          # 验证依赖关系

3.3 子任务 → 提升为顶级任务（子任务升级）

AI 对话：

子任务 [X.Y] 目前归属于任务 [X]，但我认为它应该独立成一个顶级任务，
因为 [说明原因：例如：这个子任务的工作量远超其他任务，涉及的技术面完全独立]。

请执行以下操作：
1. 读取子任务 [X.Y] 的完整详情，确认它适合独立
2. 确认新的顶级任务 ID（当前任务列表中的空位）
3. 使用 move 工具将 [X.Y] 提升为独立顶级任务
4. 评估需要为这个新独立任务添加哪些依赖关系（它依赖哪些任务？哪些任务依赖它？）
5. 设置正确的依赖关系
6. 如有必要，用 analyze_complexity 分析这个新任务是否需要拆解子任务

移动完成后告诉我：新任务的 ID、标题，以及对整体任务图的影响。

终端命令：

tm move --from=X.Y --to=Z        # 子任务 X.Y 变为独立的顶级任务 Z

3.4 调整子任务内部执行顺序

AI 对话：

任务 [X] 的子任务执行顺序需要调整，目前的顺序不合理。

当前顺序（有问题的）：
[列出当前子任务顺序]

期望顺序（合理的）：
[列出期望的子任务顺序]

调整原因：[说明为什么需要调整顺序，例如：需要先实现数据库层再实现业务层]

请执行：
1. 使用 move 工具调整子任务的位置
2. 调整完成后，展示任务 [X] 的完整子任务列表，确认顺序正确
3. 如果子任务之间存在依赖关系，确认顺序调整后依赖关系仍然合理

终端命令：

tm move --from=X.2 --to=X.4      # 把第2个子任务移到第4个位置

3.5 批量移动多个任务

AI 对话：

我需要批量重新组织任务结构。以下任务需要移动：

移动列表：
- 任务 [A] → 移到任务 [B] 的子任务下（原因：[...]）
- 任务 [C] → 移到任务 [D] 的子任务下（原因：[...]）
- 任务 [E] → 移到任务 [F] 的子任务下（原因：[...]）

执行前请：
1. 先分析这些移动操作之间是否有冲突（例如 A 依赖 C，但 A 要移到 C 的父任务下）
2. 确定正确的执行顺序
3. 逐一执行 move 操作，每步执行后告诉我结果
4. 全部完成后运行 validate_dependencies 验证整体依赖图

如果发现任何移动会产生问题，先告诉我再执行。

终端命令：

tm move --from=10,11,12 --to=16,17,18   # 批量移动，按顺序一一对应

3.6 跨 Tag 移动任务

AI 对话：

我需要将任务从一个 Tag 移动到另一个 Tag：

源 Tag：[来源 Tag 名称，例如：backlog]
目标 Tag：[目标 Tag 名称，例如：feature-payment]
任务 ID：[要移动的任务 ID]

移动原因：[例如：这个积压任务现在要纳入支付功能分支一起开发]

执行前：
1. 用 get_task 读取该任务的完整信息，确认移动目标正确
2. 检查该任务在源 Tag 中是否有依赖关系——
   如果有，这些依赖在目标 Tag 中不一定存在，需要特殊处理
3. 确认是否需要携带依赖关系一起移动（--with-dependencies 选项）

请告诉我携带依赖和不携带依赖的利弊，等我决定后再执行。

终端命令：

tm move --from=5 --from-tag=backlog --to-tag=feature-payment
# 如果需要携带依赖关系
tm move --from=5 --from-tag=backlog --to-tag=feature-payment --with-dependencies

四、自动化执行全指南

自动化模式均为仅终端命令，在对话框内无法触发真正的循环进程。

4.1 自动化执行前的准备检查

AI 对话：

我准备启动自动化执行（tm loop），在开始之前请帮我做一次完整的预检：

1. 任务状态检查
   - 是否所有 pending 任务的依赖关系都是有效的（运行 validate_dependencies）
   - 是否有足够多的可立即执行的任务（tm list --ready 输出几个？）
   - 是否有任何 blocked 任务可能影响整体执行链

2. 任务质量检查
   - 随机抽取 3 个待执行任务，检查它们的描述是否足够具体、测试策略是否清晰
   - 如果任务描述过于模糊，自动化执行质量会很差

3. 环境检查
   - 项目是否有 package.json 或构建脚本（loop 需要能运行测试）
   - 是否已配置代码格式化和 lint 工具（如要用 --preset linting）

4. 风险评估
   - 当前有多少待执行任务？自动化会一次性全部执行。
   - 是否有高风险任务（涉及数据库 Schema 变更、安全相关）建议手动执行？

给我一个「可以启动自动化」或「建议先处理以下问题再启动」的结论。

4.2 tm loop 顺序循环

自动按优先级和依赖顺序执行：取任务 → 实现 → 标记完成 → 取下一个，直到队列为空或遇到阻塞。

终端命令（根据场景选择）：

# 首次使用，建立信任——实时查看每个任务的执行过程
tm loop --verbose

# 日常无监督运行——后台执行，不打扰
tm loop

# 安全隔离运行——在 Docker 容器内执行，失败不影响主机环境（需 Docker 运行中）
tm loop --sandbox

# 只执行特定 Tag 的任务——适合功能分支开发
tm loop --tag=feature-auth

选择指南：

4.3 tm loop 质量预设模式

预设模式在每个任务执行后自动运行额外的质量检查，牺牲速度换取代码质量。

终端命令：

# TDD 模式：先写测试（Red），再实现（Green），再重构
tm loop --preset test-coverage

# Lint 模式：每个任务完成后自动运行代码格式检查和静态分析
tm loop --preset linting

# 去重模式：每个任务完成后检查是否引入了重复代码
tm loop --preset duplication

# 组合使用（不同预设可叠加）
tm loop --preset test-coverage --preset linting

AI 对话（选择预设前的建议）：

我要启动 tm loop，在选择质量预设之前请帮我分析：

1. 当前项目是否已配置测试框架（jest/vitest/pytest 等）？
   如果没有，--preset test-coverage 会失败。

2. 当前项目是否已配置 ESLint/Prettier 或其他 lint 工具？
   如果没有，--preset linting 效果很差。

3. 当前待执行任务中，有多少是纯功能实现？有多少是基础设施/配置任务？
   基础设施任务通常不适合 TDD 预设。

基于以上情况，推荐我使用哪种预设（或不使用预设）？

4.4 监控循环进度

终端命令：

# 循环运行中，在另一个终端窗口查看进度
cat .taskmaster/loop-progress.txt

# 实时追踪进度文件变化
tail -f .taskmaster/loop-progress.txt

# 查看循环执行日志
tm list    # 看哪些任务已被标记为 done

4.5 中断和恢复循环

终端命令：

# 中断循环
Ctrl+C

# 下次恢复——tm loop 自动从中断处继续，不会重复执行已完成的任务
tm loop

# 如果中断后发现有任务执行了一半（in-progress 但未完成）
tm list           # 找到未完成的任务
tm show <id>      # 查看该任务当前状态
# 选择：继续完成这个任务，或重置为 pending 重新执行
tm set-status --id=X --status=pending   # 重置为待执行
tm loop                                  # 重新启动循环

AI 对话（循环结束后的检查）：

tm loop 刚刚执行完毕（或被中断），请帮我做一次执行后检查：

1. 读取当前所有任务的状态
2. 列出本次循环执行期间完成的任务（由 pending → done）
3. 找出任何仍处于 in-progress 但未完成的任务（循环中途失败的）
4. 找出仍处于 blocked 状态的任务（loop 遇到阻塞后跳过的）
5. 评估代码质量：自动执行的任务是否有明显的实现问题需要手动审查

给我一个执行摘要，以及建议下一步手动处理的任务。

4.6 tm autopilot TDD 自动驾驶

对单个任务执行完整 TDD 循环：创建 Git 分支 → 写测试（Red）→ 实现（Green）→ 重构 → 自动提交。失败时自动重试，适合对测试覆盖率要求高的核心模块。

终端命令：

# 对任务 5 启动 TDD 自动驾驶
tm autopilot start 5

AI 对话（启动前评估）：

我准备对任务 [X] 使用 tm autopilot（TDD 自动驾驶模式），在启动前请帮我评估：

1. 读取任务 [X] 的完整详情，评估它是否适合 TDD：
   - 纯业务逻辑（适合）vs 外部 IO 操作（需要 mock）vs UI 组件（不推荐）
   - 任务的测试策略是否已经描述清楚？

2. 检查项目的测试框架配置：
   - package.json 里有没有 jest/vitest 配置？
   - 测试文件命名规范是什么（*.test.ts / *.spec.ts）？

3. 这个任务是否已有部分代码实现？
   如果已有代码，autopilot 会先写测试，可能与已有实现产生冲突。

给我一个启动 autopilot 的风险评估。

4.7 tm clusters 并行执行

自动识别无相互依赖的任务组，同时启动多个 AI Agent 并行实现，适合任务间依赖较少、希望加速执行的场景。

终端命令：

tm clusters start

AI 对话（启动前分析）：

我想使用 tm clusters 并行执行，在启动前请帮我分析：

1. 当前有哪些任务可以并行执行（相互之间没有依赖关系）？
   把它们分组展示，每组内的任务可以同时进行。

2. 并行执行的潜在风险：
   - 是否有多个任务会修改同一个文件？（可能产生冲突）
   - 是否有任务会修改共享配置（package.json、环境变量等）？
   - 是否有任务涉及数据库 Schema 变更？（并发 migration 风险）

3. 建议哪些任务适合并行、哪些任务应该保持串行执行？

给我并行执行的安全分组建议，等我确认后再启动 clusters。

五、Tag 全生命周期管理

Tag 的核心价值：让同一个项目的不同功能分支、不同开发阶段拥有完全独立的任务列表，互不干扰。

5.1 查看所有 Tag 的全局进度

AI 对话：

请给我一个所有 Tag 的全局视图：

1. 使用 tags 工具列出所有 Tag 的统计信息：
   - 每个 Tag 的名称
   - 总任务数 / 已完成数 / 进行中数 / 待开始数
   - 完成百分比
   - 当前有多少个任务可以立即开始

2. 标出哪个 Tag 是当前激活的（当前会话正在操作的）

3. 告诉我哪个 Tag 进度最落后，哪个 Tag 最接近完成

用一个汇总表展示，让我一眼看出各分支的开发状态。

终端命令：

tm tags            # 查看所有 Tag 的统计信息
tm tags --ready    # 只显示有可立即开始任务的 Tag

5.2 切换 Tag 的完整工作流

AI 对话：

我需要切换到 Tag [目标Tag名称] 继续工作。请按以下步骤执行：

第一步：保存当前 Tag 状态
在切换前，确认当前 Tag 中没有遗漏的 in-progress 任务——
如果有，请用 update_subtask 写入断点记录（参考基础手册的会话收尾流程）。

第二步：切换 Tag
使用 use_tag 工具切换到 [目标Tag名称]。

第三步：恢复目标 Tag 的上下文
切换完成后：
- 列出目标 Tag 中所有任务的状态
- 找出所有 in-progress 任务的最新 update_subtask 记录
- 使用 next_task 推荐下一个应该执行的任务
- 告诉我切换前后的对比：原 Tag 进度 vs 目标 Tag 进度

切换完成后，所有 tm 命令（list、next、start 等）都只操作新 Tag 的任务。

终端命令：

tm use-tag feature-payment   # 切换到指定 Tag
tm list                      # 查看当前 Tag 的任务列表

5.3 从主线复制任务（派生新 Tag）

当新功能分支需要基于主线的任务列表进行扩展时，复制 master Tag 作为起点。

AI 对话：

我需要基于主线任务列表创建一个新的功能分支 Tag：

新 Tag 名称：[feature-xxx]
原因：[说明为什么需要从主线复制，例如：这个功能需要在主线所有基础任务完成后才开始，但我想提前规划]

执行步骤：
1. 先查看 master Tag 的当前状态（有多少已完成、多少待做）
2. 使用 copy_tag 工具将 master Tag 的任务复制到 [feature-xxx]
3. 切换到新 Tag
4. 解析功能专属 PRD，将新功能的任务追加到这个 Tag 中：
   tm parse-prd .taskmaster/docs/[功能名]-prd.txt --append
5. 为新任务设置正确的依赖关系（新功能的任务可能依赖从 master 复制来的基础任务）

注意：复制的是任务定义，不是任务状态——复制后 master 的已完成任务
在新 Tag 中仍是 pending，这是正常的，新 Tag 有自己独立的执行进度。

终端命令：

tm copy-tag master feature-xxx    # 复制 master 任务到新 Tag
tm use-tag feature-xxx            # 切换到新 Tag

5.4 Tag 重命名

AI 对话：

需要将 Tag [旧名称] 重命名为 [新名称]。

重命名原因：[例如：功能分支名称调整了 / 发现原名称含义不清晰]

执行前请确认：
1. 当前是否有任何会话正在使用 [旧名称] 这个 Tag？
2. 重命名后，原来通过 --tag=[旧名称] 触发的 loop 命令需要更新

确认无误后，使用 rename_tag 工具执行重命名，
并告诉我重命名后需要更新的地方。

终端命令：

tm rename-tag old-name new-name

5.5 Tag 合并完成后清理（删除 Tag）

AI 对话：

功能分支 [Tag名称] 的开发工作已经合并到主线，需要清理这个 Tag：

执行前检查：
1. 确认该 Tag 中所有任务都已标记为 done 或 cancelled
   - 如果有未完成的任务，告诉我是否需要迁移到 master Tag 还是直接放弃
2. 确认该 Tag 的 git 分支是否已经合并和删除

如果以上检查通过，使用 delete_tag 工具删除该 Tag。

注意：删除操作不可恢复。如果不确定，可以先 rename 为 archived-[Tag名称] 而不是直接删除。

终端命令：

tm delete-tag feature-xxx    # 删除 Tag（不可恢复）

5.6 多 Tag 并行开发的协调策略

AI 对话：

我现在同时在多个 Tag 下开发，需要协调它们的优先级和进度：

当前活跃的 Tag：
- [Tag1]：[简单描述这个分支在做什么]
- [Tag2]：[简单描述这个分支在做什么]
- [Tag3]：[简单描述这个分支在做什么]

请帮我：
1. 查看每个 Tag 的完成度和可执行任务数
2. 识别跨 Tag 的依赖关系：
   - 某个 Tag 的任务是否依赖另一个 Tag 中任务的完成？
3. 给出并行开发的优先级建议：
   - 哪个 Tag 应该优先推进？（关键路径）
   - 哪些 Tag 的任务可以并行开发而不互相干扰？
4. 识别风险：
   - 多个 Tag 是否在修改同一批核心文件？（合并冲突风险）

给我一个多 Tag 并行开发的执行顺序建议。

六、research 联网查询深度使用

research 模式让 Task Master 在执行操作前先查询当前最佳实践，需要在 config.json 中配置支持联网的 research 模型（如 Perplexity Sonar）。

6.1 独立技术选型研究

在做技术决策之前，先用 research 查询对比，再把决策结果写入任务记录，作为后续会话的上下文依据。

AI 对话：

在开始实现之前，我需要做一个技术选型决策，请用 research 模式帮我研究：

研究问题：[具体的技术选型问题，例如：Node.js 项目中，Prisma vs Drizzle vs 原生 pg 驱动，哪个更适合高并发读写场景？]

项目背景约束：
- 技术栈：[例如：Node.js 20 + TypeScript + PostgreSQL]
- 并发要求：[例如：峰值 1000 QPS]
- 团队熟悉度：[例如：团队熟悉 SQL，不熟悉 ORM]
- 其他约束：[例如：需要支持复杂的多表联查]

研究完成后：
1. 给出 2-3 个可选方案的对比（性能、复杂度、社区支持、学习成本）
2. 给出明确的推荐方案和推荐理由
3. 把这个决策结果用 update_subtask 写入到相关任务的记录中（任务 ID：[X]）

这样即使跨会话，AI 也能从 tasks.json 中读取到这个技术决策背景。

终端命令：

tm research "Node.js ORM vs 原生 SQL 高并发场景性能对比 2025"
tm research "Prisma vs Drizzle ORM TypeScript 生产环境选型"

6.2 在任务拆解前使用 research

AI 对话：

在拆解任务 [X] 之前，我想先用 research 查询这类功能的最佳实现路径：

任务标题：[任务名称]
任务描述：[任务的核心要求]
我不确定的技术点：[例如：不清楚 WebSocket 断线重连的最佳实践 / 不熟悉 Redis 队列的实现方式]

请先联网查询：[明确的查询问题]
查询重点：
- 当前业界推荐的实现步骤（按顺序）
- 常见的踩坑点和注意事项
- 推荐的技术依赖和版本

查询完成后，基于研究结果将任务 [X] 拆解成子任务，
子任务的顺序和描述要体现研究结论。

终端命令：

tm expand --id=X --research

6.3 在更新任务前使用 research（方案过时时）

AI 对话：

任务 [X] 的描述是几个月前写的，我担心技术方案可能已经过时。
请用 research 模式重新验证并更新：

当前任务描述中的技术方案：[描述原来的方案，例如：使用 jsonwebtoken v8 实现 JWT]
我的疑虑：[例如：jsonwebtoken 好像有新版本，不确定 API 是否有变化]

请：
1. 联网查询最新的 [相关技术] 最佳实践（重点查询版本兼容性和 API 变化）
2. 对比原方案与当前最佳实践的差异
3. 如果有必要，用 update_task 覆盖重写任务 [X] 的实现描述
4. 如果差异不大，用 update_subtask 追加一条「方案验证记录」即可，不用重写整个任务

终端命令：

tm update-task --id=X --prompt="[新的实现描述]" --research
# 或只追加验证记录
tm update-subtask --id=X.Y --prompt="[方案验证结果]" --research

6.4 安全和性能审查类 research

AI 对话：

在即将完成任务 [X] 的实现之前，请用 research 模式做一次安全/性能审查：

审查类型：[安全 / 性能 / 两者都要]
涉及的技术场景：[例如：用户认证模块，JWT 存储和传输 / 高并发数据库写入 / 文件上传处理]
当前的实现方案简述：[例如：JWT 存在 localStorage，前端每次请求时读取并放在 Authorization header]

请联网查询：
- 当前方案是否存在已知的安全漏洞或性能风险
- 业界标准的最佳实践是什么
- 需要额外添加哪些防护措施（CSRF、Rate Limit、SQL 注入等）

查询结果作为 update_subtask 追加记录写入任务 [X.Y]，
并告诉我：当前实现是否需要调整，调整的优先级是什么。

七、任务清理与维护

7.1 安全删除任务（删除前必须检查依赖）

AI 对话：

我需要删除任务 [X]，因为 [说明原因，例如：这个需求已经取消/功能已经合并到其他任务中]。

删除前请执行安全检查：
1. 检查是否有其他任务依赖任务 [X]（谁 depends-on 了 X）
   - 如果有，删除 X 会让这些依赖关系变为无效引用，需要先处理
   - 处理方案选择：
     a. 移除其他任务对 X 的依赖（如果那些任务的依赖关系本来就不合理）
     b. 先把 X 标记为 cancelled 而不是删除（保留记录但不影响执行）
     c. 把 X 的功能合并到另一个任务后再删除

2. 检查任务 [X] 是否有 in-progress 状态的子任务（有正在进行中的工作尚未完成）

3. 告诉我删除的影响，等我确认后再执行 remove_task。

终端命令：

tm validate-dependencies      # 先检查依赖
tm remove-task --id=X         # 确认后再删除
tm validate-dependencies      # 删除后再验证一遍

7.2 延期和取消任务的使用场景

AI 对话（延期）：

任务 [X] 需要延期处理，原因：[例如：等待第三方 API 文档 / 本期版本不做这个功能]

请执行：
1. 将任务 [X] 状态改为 deferred
2. 用 update_subtask 追加一条记录：
   延期原因：[具体原因]
   预计恢复时间：[例如：等待 API 文档到位后 / 下个迭代]
   恢复条件：[满足什么条件才能重新开始]
3. 检查依赖任务 [X] 的其他任务——它们是否也需要调整状态或优先级？

延期后，tm next 不会推荐这个任务，但任务数据保留。

AI 对话（取消）：

任务 [X] 需要永久取消，原因：[例如：需求变更，这个功能不再需要]

请执行：
1. 先检查是否有其他任务依赖任务 [X]
2. 如果有依赖任务，先处理它们（移除依赖或一并取消）
3. 将任务 [X] 状态改为 cancelled
4. 用 update_subtask 追加取消记录：
   取消原因：[具体原因]
   决策时间：[日期]
   决策依据：[需求变更？技术限制？]

注意：cancelled 比 remove-task 更好，它保留历史记录，
未来可以查看为什么这个任务被取消了。

终端命令：

tm set-status --id=X --status=deferred    # 延期
tm set-status --id=X --status=cancelled   # 取消

7.3 任务文件异常恢复

AI 对话：

任务文件出现异常，请帮我诊断和恢复：

异常描述：[例如：tasks.json 打开后内容损坏 / tm list 报错 / 任务数量突然减少]

请执行：
1. 尝试用 generate 命令从 tasks.json 重新生成任务文件
2. 如果 tasks.json 本身损坏，检查是否有备份文件（tasks.json.bak）
3. 如果没有备份，最后的手段是重新解析 PRD：
   - 先备份当前损坏的文件
   - 重新运行 parse-prd（会生成新的任务列表，但之前的进度记录会丢失）

告诉我当前的异常状态，再决定使用哪种恢复方式。

终端命令：

tm generate    # 从 tasks.json 重新同步任务文件

# 如果 tasks.json 损坏，先备份再重建
cp .taskmaster/tasks/tasks.json .taskmaster/tasks/tasks.json.bak
tm parse-prd .taskmaster/docs/prd.txt

八、TASK_MASTER_TOOLS 工具集模式优化

工具集模式控制 Task Master 向 AI 暴露多少 MCP 工具，直接影响每次会话的 Token 消耗。

8.1 三种模式的对比与选择

core 模式包含的 7 个核心工具： get_tasks / next_task / get_task / set_task_status / update_subtask / parse_prd / expand_task

8.2 切换工具集模式

Codex 配置 (~/.codex/config.toml)：

[mcp_servers.task-master-ai.env]
TASK_MASTER_TOOLS = "core"      # 或 "standard" 或 "all"

OpenCode 配置 (~/.config/opencode/opencode.json)：

{
  "mcp": {
    "task-master-ai": {
      "env": {
        "TASK_MASTER_TOOLS": "standard"
      }
    }
  }
}

修改后必须重启 MCP 服务才能生效：

- Codex App：Settings → MCP Servers → 断开并重连

- OpenCode：Ctrl+C 退出后重新启动

8.3 大型项目的 Token 优化策略

AI 对话（切换模式前的建议）：

我的项目任务数量较多（超过 30 个任务），每次会话 Token 消耗很高，
请帮我分析当前阶段应该使用哪种工具集模式：

当前开发阶段：[例如：项目初始化阶段 / 日常功能迭代 / 项目收尾]

分析以下问题：
1. 当前阶段是否需要 Tag 管理功能？（all 模式才有）
2. 当前阶段是否需要依赖管理和 move 功能？（all 模式才有完整的）
3. 当前阶段的主要操作是什么？（只是执行已拆解好的任务 → core 或 standard 足够）

如果当前只是在执行任务、记录进度，推荐切换到 core 模式，
可节省约 70% 的 MCP 相关 Token 消耗。

给我一个模式切换建议和具体的配置步骤。

快速决策速查

这个操作在哪个手册里？
│
├─ 写 PRD / 生成任务 / 拆解子任务 → 基础手册 [B][C][E]
├─ 会话开始/恢复/结束 → 基础手册 [F][L]
├─ 找任务 / 开始任务 / 记录进度 → 基础手册 [G][H][I]
├─ 完成任务 / 标记进度 → 基础手册 [K]
├─ 新增功能 → 基础手册 [M]
├─ 修改单任务 / 批量架构调整 → 基础手册 [N][O]
│
├─ 已有项目接入 → 进阶手册 第一章
├─ 依赖添加/验证/修复/阻塞分析 → 进阶手册 第二章
├─ 任务升级/降级/换 Tag → 进阶手册 第三章
├─ 自动化执行（loop/autopilot/clusters）→ 进阶手册 第四章
├─ Tag 创建/切换/复制/删除 → 进阶手册 第五章
├─ 技术选型研究 / 联网验证方案 → 进阶手册 第六章
├─ 删除任务 / 取消 / 延期 / 文件恢复 → 进阶手册 第七章
└─ Token 优化 / 工具集模式 → 进阶手册 第八章

第五部分：FAQ 与 PRD 模板

常见问题

安装与配置问题

tm 命令找不到（command not found）

echo 'alias tm="task-master"' >> ~/.zshrc && source ~/.zshrc

codex mcp add 报错 unexpected argument '--command'

# 错误
codex mcp add task-master-ai --command npx --args "-y" --args "task-master-ai"
# 正确
codex mcp add task-master-ai -- npx -y task-master-ai

tm init 无响应

node $(npm root -g)/task-master-ai/scripts/init.js

MCP 连接问题

MCP 显示 0 tools / 工具列表为空

1. Codex 用 TOML 格式，OpenCode 用 JSON 格式，command 必须是数组
2. Node.js >= 20：node --version
3. 重启编辑器或重新打开终端

修改了 config.json 但错误依然存在

MCP 是常驻后台进程，修改配置后必须重启：

• Codex App：Settings → MCP Servers → 断开并重连
• OpenCode：Ctrl+C 退出后重启

parse-prd 超时（大型 PRD）

# ~/.codex/config.toml
[mcp_servers.task-master-ai]
startup_timeout_sec = 300
tool_timeout_sec    = 300

或将 PRD 按模块拆分，配合 Tag 分多次执行。

任务操作问题

parse-prd 报错：Codex CLI API error / exited with code 1

.taskmaster/config.json 中有 "provider": "codex-cli"，改为 "provider": "openai"，在 .env 配置中转站，重启 MCP。

tm rules add codex 执行成功但找不到 AGENTS.md

v0.43.x 中 Codex profile 写入全局路径 ~/.codex/AGENTS.md，不在项目目录：

tm rules add --setup    # 改用交互式安装
cat ~/.codex/AGENTS.md  # 验证全局规则文件

tm loop --sandbox 报错 "Docker not running"

docker ps   # 验证 Docker 是否运行

未运行时去掉 --sandbox 直接用 tm loop。

数据恢复

任务数据损坏

cp .taskmaster/tasks/tasks.json .taskmaster/tasks/tasks.json.bak
tm parse-prd .taskmaster/docs/prd.txt

任务文件与实际不同步

tm generate   # 从 tasks.json 重新生成文件

附录：PRD 模板

将以下内容保存为 .taskmaster/docs/prd.txt，让 AI 填写后执行 tm parse-prd。

# 项目名称：[项目名]

## 一、项目概述

### 1.1 背景与目标
[描述项目背景、要解决的问题、核心目标，2-4 句话]

### 1.2 核心用户
[描述使用者是谁，有哪些角色，各自的使用场景]

---

## 二、技术栈

| 层级 | 技术选型 | 版本 |
|------|----------|------|
| 前端框架 | [React / Vue / Next.js] | [版本] |
| 前端语言 | [TypeScript] | [版本] |
| 前端样式 | [TailwindCSS / SCSS] | [版本] |
| 后端框架 | [Express / Fastify / NestJS] | [版本] |
| 后端语言 | [Node.js / Python / Go] | [版本] |
| 数据库 | [PostgreSQL / MySQL / MongoDB] | [版本] |
| 缓存 | [Redis / 无] | [版本] |
| 认证方案 | [JWT / Session / OAuth2] | — |
| 文件存储 | [S3 / OSS / 本地 / 无] | — |
| 部署方式 | [Docker / Vercel / 裸机] | — |

---

## 三、功能需求

> 每个模块按：功能列表 → 业务规则 → 异常场景 描述。

### 3.1 [模块名，如：用户认证]

**功能列表：**
- [邮箱+密码注册]
- [登录并返回 JWT Token，Access Token 15 分钟，Refresh Token 7 天]
- [Token 刷新接口]
- [邮件验证码重置密码]

**业务规则：**
- [密码最少 8 位，必须包含数字和字母]
- [Token 存储在 HttpOnly Cookie 中，防止 XSS]

**异常场景：**
- [邮箱已存在 → 返回 409]
- [密码错误连续 5 次 → 锁定 30 分钟]
- [Token 过期 → 返回 401，客户端刷新]

### 3.2 [继续添加模块...]

---

## 四、数据模型

### [实体名，如：User]
| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID | 主键 |
| email | string | 唯一，用于登录 |
| password_hash | string | bcrypt 加密 |
| status | enum | active / banned / unverified |
| created_at | timestamp | 注册时间 |

### 实体关系
- [User 1:N Order]
- [Order N:N Product（通过 OrderItem）]

---

## 五、接口概览

| 方法 | 路径 | 说明 | 需认证 |
|------|------|------|--------|
| POST | /api/v1/auth/register | 注册 | 否 |
| POST | /api/v1/auth/login | 登录 | 否 |
| GET  | /api/v1/users/me | 当前用户信息 | 是 |

---

## 六、非功能需求

### 性能
- [列表接口响应 < 200ms（P95）]
- [支持并发 500 用户]

### 安全
- [所有接口启用 HTTPS]
- [SQL 查询全部参数化]
- [API 限流：同 IP 每分钟 60 次]

### 测试
- [所有 Service 层必须有单元测试]
- [核心流程需要集成测试]

---

## 七、约束与限制

### 技术约束（AI 必须严格遵守）
- [不使用 ORM，直接写 SQL]
- [不使用 GraphQL，只用 REST]

### 业务约束
- [订单 paid 状态后不可直接取消，必须走退款]
- [用户数据使用软删除]
- [金额用整数（分）计算，不用浮点数]

---

## 八、超出范围（不实现）

- [ ] [移动端 App]
- [ ] [国际化 / 多语言]
- [ ] [第三方登录]
- [ ] [实时消息推送]

---

## 九、完成标准

- [ ] 所有功能需求均已实现
- [ ] 所有接口可正常调用
- [ ] 单元测试覆盖率 >= [X]%
- [ ] 无已知高优先级 Bug