Task Master 元开发脚本完全指南：用 `scripts/dev.js` 驾驭 AI 驱动的任务管理

Task Master 元开发脚本完全指南用scripts/dev.js驾驭 AI 驱动的任务管理【免费下载链接】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 仓库中 .taskmaster/docs/README.md 为骨架系统讲解其元开发脚本scripts/dev.js的完整用法从.env环境配置、PRD 解析、任务增删改查到子任务展开、复杂度分析、依赖校验修复再到next智能任务推荐与 Anthropic / Perplexity 双 AI 集成。读完本文你将掌握把任意 PRD 文本转成结构化tasks.json、并在 AI 编码工作流中持续维护任务清单的完整实战方案同时能从源码层面理解每个命令背后的数据流与校验逻辑。背景为什么需要一份任务的单一事实来源在 Cursor、Claude Code、Roo 等 AI 驱动开发流程中最头疼的问题之一是 Agent 对该做什么、做完了什么、接下来做什么缺乏统一认知。.taskmaster/docs/README.md给出的答案是维护一份tasks.json作为任务的单一事实来源single source of truth让脚本、AI Agent 与开发者都围绕同一份数据协同。这份脚本的定位是元开发脚本meta-development script——它本身不实现业务功能而是管理开发任务的生成与演进正好契合 Task Master 项目AI 驱动的任务管理系统的整体定位。tasks.json的结构脚本的核心数据文件位于项目根目录新版本约定为.taskmaster/tasks/tasks.json路径常量见 src/constants/paths.js。以仓库自带的 .taskmaster/tasks/tasks.json 为真实样本每个任务包含字段含义示例id任务编号数字1title任务标题Implement Task Data Structuredescription一句话描述Design and implement the core tasks.json structure...status状态done/pending/in-progress/deferred等donedependencies依赖的任务 ID 数组[1, 3]priority优先级high/medium/lowhighdetails详细实现要点多行文本testStrategy测试策略多行文本subtasks子任务数组子任务对象数组文档还提到meta字段可以存放项目名、版本或 PRD 引用。子任务 ID 采用父ID.子ID点号格式如3.1这是整个脚本系统处理层级关系的约定——在 scripts/modules/dependency-manager.js 中可以看到脚本按点号拆分并定位父任务与子任务的实现。注意路径演进本仓库已从旧版scripts/、tasks/tasks.json布局迁移到.taskmaster/新布局但为兼容旧项目源码仍保留了 LEGACY 路径回退见 src/constants/paths.js所以文档中提到的scripts/下各类文件在旧项目里依然可用。环境配置.env中的必选与可选参数脚本通过项目根目录的.env文件读取环境变量。入口脚本 scripts/dev.js 会先通过findProjectRoot()定位项目根再用dotenv.config()加载.env并保证不改变当前工作目录process.cwd()被存为TASKMASTER_ORIGINAL_CWD供依赖相对路径的命令使用。必选配置ANTHROPIC_API_KEYAnthropic API 密钥用于 Claude 的 PRD 解析、任务生成与子任务展开。格式要求为sk-ant-api03-...见 assets/env.example。可选配置环境变量默认值说明MODELclaude-3-7-sonnet-20250219指定使用的 Claude 模型MAX_TOKENS4000模型响应的最大 token 数TEMPERATURE0.7模型采样温度PERPLEXITY_API_KEY无Perplexity API 密钥用于 research 模式格式pplx-...PERPLEXITY_MODELsonar-medium-onlineresearch 模式使用的 Perplexity 模型DEBUGfalse开启调试日志设为1时还会在项目根写入dev-debug.logTASKMASTER_LOG_LEVELinfo日志级别debug/info/warn/errorDEFAULT_SUBTASKS3展开任务时默认生成的子任务数量DEFAULT_PRIORITYmedium生成任务的默认优先级PROJECT_NAME无覆盖tasks.json中的默认项目名PROJECT_VERSION无覆盖tasks.json中的默认版本号需要说明的是scripts/modules/config-manager.js 中的DEFAULTS是当前仓库实际生效的默认值如主模型claude-sonnet-4-20250514、maxTokens: 64000、defaultSubtasks: 5、responseLanguage: English等它代表脚本内部真实使用的配置基线而上表中的默认值来自原文档。两者的差异恰恰印证了文档描述的变量多数仍可通过.env覆盖实际行为以 scripts/modules/config-manager.js 的默认值与.env覆盖后的合并结果为准。配置合并遵循环境变量 .env文件 内置默认值的优先级。命令总览与通用入口所有命令统一通过以下方式执行node scripts/dev.js [command] [options]不带参数直接运行node scripts/dev.js会显示完整的使用帮助。原文档列出的核心命令如下命令用途parse-prd从 PRD 文档生成任务list展示所有任务及其状态update基于新信息批量更新任务update-task更新单个指定任务generate为每个任务生成独立的任务文件如task_001.txtset-status修改任务状态expand为任务添加子任务clear-subtasks清除指定任务的子任务add-subtask/remove-subtask增删子任务next依据依赖关系推荐下一个该做的任务show查看指定任务的详细信息add-dependency/remove-dependency管理任务依赖validate-dependencies/fix-dependencies校验与修复依赖analyze-complexity分析任务复杂度并给出展开建议从源码看CLI 基于 Commander.js 构建scripts/modules/commands.js命令的注册经由tm/cli包的registerAllCommands完成所有命令最终汇聚到runCLI(process.argv)统一分发scripts/dev.js。从 PRD 到任务parse-prd与generateparse-prd是流水线的起点它读取一份.txt格式的产品需求文档PRD借助 Claude 将需求解析为结构化的任务数组并写入tasks.json。解析过程内置了智能依赖推断根据任务内容与逻辑顺序推断先后关系、优先级分配识别基础/基础设施任务为 high以及大文档分块处理超出上下文窗口时按章节切分、跨块合并去重。这些能力在 .taskmaster/tasks/tasks.json 的Build PRD Parsing System任务子项中有完整的验收标准记录例如至少 3 套针对不同 PRD 风格的提示模板与防止依赖环。generate命令则负责把tasks.json中的任务渲染为独立的task_001.txt风格文件方便单个任务被 AI 或人工引用并且支持任务文件与tasks.json的双向同步——修改任务文件后可将变更回写 JSON该能力对应 tasks.json 中Implement Change Detection and Update Handling子任务的验收标准。任务文件命名约定为task_前缀加零填充编号src/constants/paths.js。列出任务list# 列出所有任务 node scripts/dev.js list # 只列出 pending 状态的任务 node scripts/dev.js list --statuspending # 列出任务并附带子任务 node scripts/dev.js list --with-subtasks # 组合过滤 node scripts/dev.js list --statuspending --with-subtaskslist输出中依赖会用状态指示符标注✅ 表示已完成⏱️ 表示等待中让进度一目了然。更新任务update与update-task当发现实现漂移implementation drift——即已完成工作的实际实现与最初规划不一致影响后续任务时——用update批量修正# 从 ID 4 开始用新提示重写后续任务 node scripts/dev.js update --from4 --promptRefactor tasks from ID 4 onward to use Express instead of Fastify # 更新所有任务默认 from1 node scripts/dev.js update --promptAdd authentication to all relevant tasks # 借助 Perplexity 做研究支持的更新 node scripts/dev.js update --from4 --promptIntegrate OAuth 2.0 --research # 指定自定义任务文件 node scripts/dev.js update --filecustom-tasks.json --from5 --promptChange database from MongoDB to PostgreSQL规则要点--prompt为必填只更新status不是done的任务仅更新 ID ≥--from的任务--research在可用时借助 Perplexity 提升更新质量。update-task则精确作用到单个任务并带有一组稳健性设计# 更新单个任务 node scripts/dev.js update-task --id4 --promptUse JWT for authentication # 研究支持模式 node scripts/dev.js update-task --id4 --promptUse JWT for authentication --research文档明确其行为只更新指定任务而非区间提供详细校验与友好错误提示research 模式会先检查 API KeyPerplexity 不可用时优雅回退已标记为done的任务保持不变。这与 .taskmaster/tasks/tasks.json 中 Develop Implementation Drift Handling 任务的保留已完成工作、只更新未完成工作目标完全一致。状态流转set-status# 标记任务 3 为 done node scripts/dev.js set-status --id3 --statusdone # 标记任务 4 为 pending node scripts/dev.js set-status --id4 --statuspending # 标记子任务 3.1 为 done node scripts/dev.js set-status --id3.1 --statusdone # 一次更新多个任务 node scripts/dev.js set-status --id1,2,3 --statusdone要点父任务标记为done时其全部子任务自动跟随为done状态值理论上接受任意字符串惯例为done/pending/deferred多个 ID 用逗号分隔子任务 ID 使用父ID.子ID格式。子任务体系expand、clear-subtasks、add-subtask、remove-subtaskexpand是拆解复杂任务的核心命令# 展开任务 3默认 3 个子任务 node scripts/dev.js expand --id3 # 指定生成 5 个子任务 node scripts/dev.js expand --id3 --num5 # 附带上下文提示 node scripts/dev.js expand --id3 --promptFocus on security aspects # 展开所有尚无子任务的 pending 任务 node scripts/dev.js expand --all # 强制重新生成所有 pending 任务的子任务 node scripts/dev.js expand --all --force # 用 Perplexity 做研究支持的子任务生成 node scripts/dev.js expand --id3 --research # 对全部 pending 任务做研究支持的展开 node scripts/dev.js expand --all --researchclear-subtasks用于清除后重新生成node scripts/dev.js clear-subtasks --id3 # 清除单个任务 node scripts/dev.js clear-subtasks --id1,2,3 # 清除多个 node scripts/dev.js clear-subtasks --all # 清除全部清除后任务文件会自动重新生成因此可与expand组合实现换一种拆解思路。在 .taskmaster/tasks/tasks.json 的 Implement Task Expansion with Claude 任务子项中还记录了regenerate按需重生成部分子任务与--context等更细的能力以及完成全部子任务后自动更新父任务状态父子关系在删除父任务时的孤儿处理等边界设计。add-subtask/remove-subtask提供精细化的子任务编辑# 为任务 5 新增一个子任务 node scripts/dev.js add-subtask --parent5 --titleImplement login UI --descriptionCreate login form # 把现有任务 8 转为任务 5 的子任务 node scripts/dev.js add-subtask --parent5 --task-id8 # 新增带依赖的子任务 node scripts/dev.js add-subtask --parent5 --titleAuthentication middleware --dependencies5.1,5.2 # 跳过任务文件再生成 node scripts/dev.js add-subtask --parent5 --titleLogin API route --skip-generate # 移除子任务 node scripts/dev.js remove-subtask --id5.2 # 批量移除 node scripts/dev.js remove-subtask --id5.2,5.3,5.4 # 将子任务转为独立任务不删除 node scripts/dev.js remove-subtask --id5.2 --convert依赖管理增删、校验与修复添加与移除依赖# 为任务添加依赖 node scripts/dev.js add-dependency --idid --depends-onid # 移除依赖 node scripts/dev.js remove-dependency --idid --depends-onid这一组命令在 scripts/modules/dependency-manager.js 中有完整实现添加依赖时会自动校验依赖目标存在taskExists、阻止自依赖任务依赖自身、阻止重复依赖并做循环依赖检测isCircularDependency沿依赖链回溯成功后按数字优先、再按父/子 ID 排序依赖数组并写回 JSON同时更新任务文件。校验与修复# 只扫描不修改 node scripts/dev.js validate-dependencies # 指定自定义任务文件 node scripts/dev.js validate-dependencies --filecustom-tasks.json # 主动修复所有非法依赖 node scripts/dev.js fix-dependencies # 指定文件修复 node scripts/dev.js fix-dependencies --filecustom-tasks.jsonvalidate-dependencies是审计工具扫描所有任务与子任务找出指向不存在任务的依赖、自我依赖输出综合摘要与统计但不修改任何文件。fix-dependencies则在校验基础上自动清除引用不存在任务/子任务的依赖与自依赖并同时修复tasks.json数据结构和重生成后的任务文件最后给出问题类型、受影响数量、修复位置与逐条修复清单的详细报告。当任务被删除或 ID 变更导致依赖链断裂时这两个命令尤其重要——这与仓库中validate-dependencies.js、fix-dependencies.js两个独立命令模块见 scripts/modules/task-manager/ 目录一一对应。复杂度分析analyze-complexity与expand的联动# 分析全部任务并生成展开建议 node scripts/dev.js analyze-complexity # 指定输出文件 node scripts/dev.js analyze-complexity --outputcustom-report.json # 覆盖分析模型 node scripts/dev.js analyze-complexity --modelclaude-3-opus-20240229 # 设置复杂度阈值1-10 node scripts/dev.js analyze-complexity --threshold6 # 使用 Perplexity 做研究支持的复杂度分析 node scripts/dev.js analyze-complexity --research核心机制实现见 scripts/modules/task-manager/analyze-task-complexity.jsClaude 对每个任务按 1-10 打分低于阈值默认 5的任务被认为无需展开每个任务会附带推荐子任务数受DEFAULT_SUBTASKS影响和一条可直接复制执行的expansionCommand默认输出路径为scripts/task-complexity-report.json新版为.taskmaster/reports/task-complexity-report.json本仓库 .taskmaster/reports/ 下即有多个真实报告样本。--research提供更贴合上下文的评估。报告 JSON 结构示例继承自原文档{ meta: { generatedAt: 2023-06-15T12:34:56.789Z, tasksAnalyzed: 20, thresholdScore: 5, projectName: Your Project Name, usedResearch: true }, complexityAnalysis: [ { taskId: 8, taskTitle: Develop Implementation Drift Handling, complexityScore: 9.5, recommendedSubtasks: 6, expansionPrompt: Create subtasks that handle detecting..., reasoning: This task requires sophisticated logic..., expansionCommand: node scripts/dev.js expand --id8 --num6 --prompt\Create subtasks...\ --research } ] }联动规则当复杂度报告存在时expand会优先采用报告推荐的子任务数与定制展开提示除非用--num/--prompt显式覆盖expand --all会按复杂度从高到低排序处理分析时的--research标记会延续到展开阶段。智能推荐下一个任务next# 展示下一个该做的任务 node scripts/dev.js next # 指定任务文件 node scripts/dev.js next --filecustom-tasks.json算法分两步源码见 scripts/modules/task-manager/find-next-task.js候选集找出所有pending或in-progress、且其依赖全部为done的任务排序优先级high medium low→ 依赖数量少者优先→ 任务 ID小者优先。从当前实现看findNextTask还会优先推荐属于in-progress父任务的待办子任务子任务按优先级、依赖数、父/子 ID 排序若没有合适子任务再回退到顶层任务——这是文档基础上的实现增强。命中后next会展示任务详情、描述、实现要点与子任务并给出情境化建议动作标记 in-progress、完成后标记 done、处理子任务更新状态或展开等命令。查看任务详情show# 查看任务 1 node scripts/dev.js show 1 # 等价写法 node scripts/dev.js show --id1 # 查看子任务 1.2 node scripts/dev.js show --id1.2 # 指定任务文件 node scripts/dev.js show 3 --filecustom-tasks.jsonshow输出任务的 ID、标题、优先级、依赖、状态、完整描述、实现细节、测试策略以及子任务列表对子任务会展示其父任务关系并附上查看父任务或修改状态的后续命令建议。在实现任务前用它核对细节是最推荐的检查姿势。AI 集成Anthropic Claude 与 Perplexity 的双引擎脚本集成两个 AI 服务原文档明示Anthropic Claude负责 PRD 解析、任务生成与子任务创建parse-prd、expand、update、analyze-complexity的默认引擎Perplexity AI在指定--research时提供研究支持的子任务生成与复杂度分析。Perplexity 集成通过OpenAI 客户端协议连接 Perplexity API利用其联网检索能力生成信息更充分的子任务当 Perplexity 不可用或出错时自动回退到 Claude。启用 research 的四步流程继承自原文档获取 Perplexity API Key在.env中加入PERPLEXITY_API_KEY可选在.env中配置PERPLEXITY_MODEL默认sonar-medium-online在expand等命令后加--research标志。这一Claude 为主、Perplexity 增强、失败回退的架构在 .taskmaster/tasks/tasks.json 的 Integrate Perplexity API 任务子项中可见其工程化设计重试逻辑采用指数退避exponential backoff、回退前先重试、回退事件全量记录日志并支持配置最大重试次数。日志与调试TASKMASTER_LOG_LEVEL控制四档日志debug详细调试信息适合排障info正常运行的确认信息默认warn不影响执行的告警error可能阻断执行的错误。当DEBUGtrue时debug 日志还会追加写入项目根目录的dev-debug.log文件。此外 scripts/dev.js 在DEBUG 1时会把收到的 argv 打到 stderr方便确认参数解析结果。仓库还集成了 Sentry 遥测初始化initializeSentry见 scripts/dev.js并且 scripts/modules/config-manager.js 的默认配置中提供了anonymousTelemetry: true的开关可按需在配置中关闭。增强的错误处理与版本检查增强错误处理文档强调脚本在各命令中内建了四级错误处理能力早期校验任务 ID、prompt 等必填参数提前验证文件存在性检查带场景化错误参数类型转换给出清晰提示上下文化错误信息任务未找到时建议运行listAPI Key 缺失时提醒检查环境变量ID 格式非法时展示预期格式命令级帮助校验失败时展示该命令的详细帮助含用法示例、参数说明并以色块框格式化输出错误恢复常见错误附排障步骤可选依赖缺失时优雅降级配置问题给出修复指引。从 scripts/modules/commands.js 的导入看错误展示统一走displayFormattedError/displayInfo/displaySuccess/displayWarning来自 scripts/modules/error-formatter.js保证输出风格一致。后台版本检查脚本会自动检查更新且不拖慢执行版本检查在后台非阻塞运行不延迟命令执行更新提示在命令完成后显示提示信息包含当前版本、最新版本与更新命令用醒目框体展示实现上采用语义化版本对比、从 npm registry 拉取版本信息并带超时网络异常时静默跳过不影响命令执行。实战一条完整的 AI 驱动任务工作流将上述命令串起来就是一个可落地的 AI 驱动开发闭环# 1. 配置 .envANTHROPIC_API_KEY 必填PERPLEXITY_API_KEY 可选 # 2. 从 PRD 初始化任务 node scripts/dev.js parse-prd --file.taskmaster/docs/prd.txt # 3. 查看任务全貌 node scripts/dev.js list # 4. 分析复杂度找出需要拆解的任务 node scripts/dev.js analyze-complexity --threshold5 # 5. 按报告建议展开子任务 node scripts/dev.js expand --all # 6. 让脚本推荐下一个该做的任务 node scripts/dev.js next # 7. 完成一项后更新状态 node scripts/dev.js set-status --id3.1 --statusdone # 8. 当实现偏离原计划时批量修正后续任务 node scripts/dev.js update --from4 --promptUse Express instead of Fastify # 9. 定期审计依赖健康度 node scripts/dev.js validate-dependencies node scripts/dev.js fix-dependencies配合 scripts/dev.js 的模块化实现命令注册、配置加载、依赖管理、复杂度分析各自独立成模块这份工作流既能被人类开发者手工驱动也能被 Cursor 等 AI Agent 通过命令输出解析后自动执行——这正是 Task Master 元开发脚本的设计初衷。深入源码入口与模块化架构想要理解脚本的完整脉络推荐按以下顺序阅读本仓库源码scripts/dev.js入口文件。加载.env、初始化 Sentry、检测登录态已认证时抑制本地配置告警、动态导入runCLI分发命令scripts/modules/commands.jsCLI 中枢基于 Commander.js 注册全部命令并串联各业务模块scripts/modules/config-manager.js配置加载与校验内置DEFAULTS与环境变量 .env 默认值的合并优先级scripts/modules/dependency-manager.jsadd-dependency/remove-dependency/ 校验 / 修复的完整实现含循环依赖检测与自依赖拦截scripts/modules/task-manager/find-next-task.jsnext的候选筛选与排序算法scripts/modules/task-manager/analyze-task-complexity.js复杂度评分、阈值过滤与报告生成src/constants/paths.js.taskmaster/目录体系与新旧路径兼容常量assets/env.example全部可用 API Key 环境变量模板Anthropic、Perplexity、OpenAI、Google、Mistral、xAI、Groq、OpenRouter、Azure 等.taskmaster/tasks/tasks.json真实任务的完整样本含details、testStrategy、subtasks、acceptanceCriteria的规范写法.taskmaster/reports/多个真实的复杂度分析报告样本可直接对照analyze-complexity的输出格式。从parse-prd到fix-dependencies脚本的每个命令都有对应的模块化实现与验收标准这份文档 源码 真实数据文件的组合使它既能作为开箱即用的 CLI也能作为二次开发与学习 AI 任务编排的参考实现。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考