claude-task-master 单任务精准更新指南update-single-task 命令的语法、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本指南围绕 claude-task-mastertm项目中的 update-single-task 命令讲解如何以自然语言对单个任务做精准、增量式的信息更新。你将掌握该命令的参数解析约定、三类更新场景、字段级快捷语法以及底层update-task-by-id的执行链路与数据保护机制可直接在 Cursor、Windsurf、Roo 等支持 Claude Code 的 Agent 环境中落地使用。命令定位从/taskmaster:update家族说起在 claude-task-master 的 Claude Code 插件中任务更新能力由一组以/taskmaster:update开头的斜杠命令承载。tm-main.md 中列出了三个分工明确的入口update-task—— 用自然语言更新任务支持智能字段检测与批量操作见 update-task.mdupdate-tasks-from-id—— 从某个起点批量更新多个任务update-single-task——精准更新单个指定任务即本文主题。update-single-task 的核心目标是用 AI 协助精确更新一个任务同时维持任务库的整体一致性既不让 AI 的过度发挥破坏已有内容也不遗漏用户要求的新增信息。该命令对应的 CLI 底层命令是task-master update-task在 scripts/modules/commands.js 中注册内部由 update-task-by-id.js 完成全部执行逻辑。基础用法与 CLI 参数文档定义的标准调用形式为task-master update-task --idid --promptcontext对应到 commands.js 中的命令定义update-task支持位置参数与选项参数两种写法全部参数如下参数说明示例[id]位置要更新的任务 ID支持整数1、子任务 ID1.1与标签式 IDTAS-123tm update-task 1 Added implementation details[prompt...]位置更新说明多词无需引号tm update-task 1 Added implementation details-i, --id id任务 ID不使用位置参数时的回退写法--id23-p, --prompt text更新说明回退写法--promptUpdate with new information-f, --file filetasks 文件路径默认取TASKMASTER_TASKS_FILE-f tasks/custom.json-r, --research使用 Perplexity AI 做研究增强型更新未配置 API Key 时自动回退到主 AI-r--append追加模式向任务 details 追加带时间戳的信息而非整体替换--append--tag tag指定标签上下文用于多标签任务库--tag backend从源码看参数解析遵循位置参数优先于选项的规则commands.jstaskId idArg || options.idprompt 则将多个单词以空格拼接后作为整体。命令还会对任务 ID 做合法性校验只接受正整数^\d$或ham-123这类前缀-数字格式commands.js不合法的 ID 会直接报错并提示用法示例。参数解析用自然语言表达更新意图update-single-task 的参数解析面向自然语言文档给出了四种典型句式其中任务编号与更新内容可以灵活组织5: add caching requirement update 5 to include error handling task 5 needs rate limiting 5 change priority to high这些 prompt 并不会被规则解析器拆解而是原样传给 AI见下文执行链路由模型理解哪个任务、改什么、怎么改。正因如此位置参数中的[prompt...]才设计成多词免引号——例如tm update-task 5 change priority to high会被完整拼接为更新说明。三类更新场景文档将单任务更新归纳为内容、元数据与战略三层覆盖任务生命周期中的绝大多数变更诉求1. 内容更新Content Updates聚焦任务描述与验收层面的增强增强描述Enhance description添加需求Add requirements澄清细节Clarify details更新验收标准Update acceptance criteria2. 元数据更新Metadata Updates不触碰正文只调整任务的调度与权重属性修改优先级Change priority调整时间估算Adjust time estimates更新复杂度Update complexity修改依赖关系Modify dependencies3. 战略更新Strategic Updates面向实现方案与执行策略的调整修订实现思路Revise approach更换测试策略Change test strategy更新实现笔记Update implementation notes调整子任务规划Adjust subtask needs源码层面更新任务响应结构 规定 AI 必须返回一个包含task属性的 JSON 对象task遵循 UpdatedTaskSchema在BaseTaskSchema基础上扩展subtasks数组并启用strict()严格模式。执行端在写回前会补齐默认值dependencies缺省为空数组、priority/details/testStrategy缺省为nullupdate-task-by-id.js并强制校验title与description非空从结构上保证更新结果完整可用。字段级快捷语法对于只改单个字段的场景文档定义了紧凑的快速语法把任务编号 字段操作写在一行5 priority:high → 只更新优先级 5 add-time:4h → 在时间估算上追加 4 小时 5 status:review → 修改状态 5 depends:3,4 → 添加依赖任务 3、4这类语法同样作为自然语言 prompt 交给 AI 解析其价值在于用最短输入表达明确意图配合下文提到的状态保护机制可以安全地完成只改状态不动正文的操作。AI 驱动的三阶段更新流程文档将 AI 的更新过程划分为三个环节与源码实现一一对应1. 理解上下文Understands ContextAI 在生成更新前需要读取任务当前状态、识别更新意图、保持与既有内容一致、保留关键信息。源码中这一阶段由 ContextGatherer 支撑它会将任务库展平用FuzzyTaskSearch以任务标题 描述 用户 prompt为查询词检索最多 5 个相关任务把相关任务的上下文一并注入 promptformat: research让 AI 的更新不孤立于项目语境。2. 应用更改Applies ChangesAI 根据 update-task.json 中的系统提示更新相关字段、保持风格一致、只增不减、增强可读性。提示模板有两条硬性约束值得注意绝不改动任务标题且除 prompt 明确提及外维持相同的 ID、状态与依赖update-task.json对于已完成子任务禁止直接修改其内容而是新增一个子任务来标注需要变更的部分。3. 验证结果Validates ResultsAI 输出后执行端会做多轮校验与修复详见下一节检查输出对象结构合法性、恢复被 AI 篡改的 ID/状态、修正子任务 ID 编号、还原被误改的已完成子任务并合并原有元数据——即文档所说检查一致性、验证完整性、维护关系。源码级执行链路与保护机制update-task命令的完整调用链为CLI 参数解析 (commands.js) → updateTaskById (update-task-by-id.js) → tryUpdateViaRemote (packages/tm-bridge/src/update-bridge.ts) // Hamster/API 存储优先 → readJSON 任务定位与状态检查 → ContextGatherer FuzzyTaskSearch可选 → getPromptManager().loadPrompt(update-task, params, variant) → generateObjectService / generateTextService统一 AI 服务 → 结果校验/修复 → writeJSON 写回 tasks.json其中 update-task-by-id.js 会先尝试通过tm/bridge的远程更新路径API 存储场景失败则回退到本地文件存储逻辑。prompt 模板按append/research/default三个变体加载update-task-by-id.js默认走结构化对象输出generateObjectService追加模式走纯文本输出generateTextService。以下五条保护机制是单任务更新的可靠性关键均来自 update-task-by-id.js已完成任务锁定任务状态为done/completed时直接拒绝更新并提示先改回pending/in-progress再执行L152-L180。这是保持一致性的最强约束。ID 与状态回写保护若 AI 改动了任务 ID执行端强制恢复原 ID只有 prompt 中明确出现 status 时才允许状态变更否则恢复原状态L482-L496。子任务 ID 修正AI 可能返回字符串 ID 或以父任务 ID 为前缀的编号执行端会统一重排为从 1 开始的连续整数并过滤掉指向自身或未来子任务的非法依赖L497-L539。已完成子任务保全若 AI 修改或删除了done/completed子任务执行端会将其还原新需求应通过新增子任务表达L541-L584。元数据合并AI 输出不含metadata字段执行端将原任务元数据与本次提供的 metadata 合并后写回避免丢失L587-L596。完整示例一次带反馈的更新会话文档给出了一个端到端的交互示例展示自然语言输入、AI 处理与结果反馈的完整形态/taskmaster:update/single 5: add rate limiting → Updating Task #5: Implement API endpoints Current: Basic CRUD endpoints Adding: Rate limiting requirements Updated sections: ✓ Description: Added rate limiting mention ✓ Details: Added specific limits (100/min) ✓ Test Strategy: Added rate limit tests ✓ Complexity: Increased from 5 to 6 ✓ Time Estimate: Increased by 2 hours Suggestion: Also update task #6 (API Gateway) for consistency?值得注意的是示例中复杂度从 5 提到 6、时间估算增加 2 小时这类联动调整正是 AI 依据 update-task.json 中在保证基本结构前提下将变更深思熟虑地应用到任务上的指导原则完成的末尾是否同时更新任务 #6的建议则对应源码中将相关任务上下文注入 promptContextGatherer的设计——AI 在更新时已经看到了关联任务的上下文因此能主动提示联动影响。智能特性与增量更新文档总结了单任务更新的三项智能能力前两项在源码中有明确对应实现增量更新Incremental Updates核心是只增不改、保留历史。对应--append追加模式AI 仅生成新增内容执行端将其封装为info added on {ISO 时间戳}.../info added on ...标签块追加到任务 details 末尾update-task-by-id.js每次变更都带时间戳天然形成可追溯的更新历史。一致性检查Consistency Checks包括关联任务对齐FuzzyTaskSearch 上下文注入、子任务兼容已完成子任务保全、依赖有效性依赖过滤与去重、时间线影响时间估算联动全部在写回前完成。更新历史Update History以时间戳标签、description 中追加的[Updated: 日期]标记prompt 短于 100 字符时触发L417-L421等形式记录何时、因何更新配合 git 版本管理即可追溯任务演进。更新后的收尾动作命令执行成功后CLI 会输出更新后的任务摘要ID/标题/状态表格、AI 用量统计displayAiUsageSummary并在追加模式下展示新增内容片段。文档建议的 post-update 检查清单为展示更新后的任务、高亮变更点、检查关联任务、给出后续更新建议、评估时间线影响。对于多标签任务库可通过--tag指定操作范围文件存储场景要求任务 ID 为纯数字1.2这类子任务 ID 请改用update-subtask-by-id命令处理update-task-by-id.js。相关资源批量/智能更新对照update-task.md命令总览tm-main.mdCLI 命令定义scripts/modules/commands.js核心执行实现scripts/modules/task-manager/update-task-by-id.js提示模板default/append/research 变体src/prompts/update-task.json输出结构校验src/schemas/update-task.js、src/schemas/update-tasks.js【免费下载链接】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），仅供参考
claude-task-master 单任务精准更新指南update-single-task 命令的语法、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本指南围绕 claude-task-mastertm项目中的 update-single-task 命令讲解如何以自然语言对单个任务做精准、增量式的信息更新。你将掌握该命令的参数解析约定、三类更新场景、字段级快捷语法以及底层update-task-by-id的执行链路与数据保护机制可直接在 Cursor、Windsurf、Roo 等支持 Claude Code 的 Agent 环境中落地使用。命令定位从/taskmaster:update家族说起在 claude-task-master 的 Claude Code 插件中任务更新能力由一组以/taskmaster:update开头的斜杠命令承载。tm-main.md 中列出了三个分工明确的入口update-task—— 用自然语言更新任务支持智能字段检测与批量操作见 update-task.mdupdate-tasks-from-id—— 从某个起点批量更新多个任务update-single-task——精准更新单个指定任务即本文主题。update-single-task 的核心目标是用 AI 协助精确更新一个任务同时维持任务库的整体一致性既不让 AI 的过度发挥破坏已有内容也不遗漏用户要求的新增信息。该命令对应的 CLI 底层命令是task-master update-task在 scripts/modules/commands.js 中注册内部由 update-task-by-id.js 完成全部执行逻辑。基础用法与 CLI 参数文档定义的标准调用形式为task-master update-task --idid --promptcontext对应到 commands.js 中的命令定义update-task支持位置参数与选项参数两种写法全部参数如下参数说明示例[id]位置要更新的任务 ID支持整数1、子任务 ID1.1与标签式 IDTAS-123tm update-task 1 Added implementation details[prompt...]位置更新说明多词无需引号tm update-task 1 Added implementation details-i, --id id任务 ID不使用位置参数时的回退写法--id23-p, --prompt text更新说明回退写法--promptUpdate with new information-f, --file filetasks 文件路径默认取TASKMASTER_TASKS_FILE-f tasks/custom.json-r, --research使用 Perplexity AI 做研究增强型更新未配置 API Key 时自动回退到主 AI-r--append追加模式向任务 details 追加带时间戳的信息而非整体替换--append--tag tag指定标签上下文用于多标签任务库--tag backend从源码看参数解析遵循位置参数优先于选项的规则commands.jstaskId idArg || options.idprompt 则将多个单词以空格拼接后作为整体。命令还会对任务 ID 做合法性校验只接受正整数^\d$或ham-123这类前缀-数字格式commands.js不合法的 ID 会直接报错并提示用法示例。参数解析用自然语言表达更新意图update-single-task 的参数解析面向自然语言文档给出了四种典型句式其中任务编号与更新内容可以灵活组织5: add caching requirement update 5 to include error handling task 5 needs rate limiting 5 change priority to high这些 prompt 并不会被规则解析器拆解而是原样传给 AI见下文执行链路由模型理解哪个任务、改什么、怎么改。正因如此位置参数中的[prompt...]才设计成多词免引号——例如tm update-task 5 change priority to high会被完整拼接为更新说明。三类更新场景文档将单任务更新归纳为内容、元数据与战略三层覆盖任务生命周期中的绝大多数变更诉求1. 内容更新Content Updates聚焦任务描述与验收层面的增强增强描述Enhance description添加需求Add requirements澄清细节Clarify details更新验收标准Update acceptance criteria2. 元数据更新Metadata Updates不触碰正文只调整任务的调度与权重属性修改优先级Change priority调整时间估算Adjust time estimates更新复杂度Update complexity修改依赖关系Modify dependencies3. 战略更新Strategic Updates面向实现方案与执行策略的调整修订实现思路Revise approach更换测试策略Change test strategy更新实现笔记Update implementation notes调整子任务规划Adjust subtask needs源码层面更新任务响应结构 规定 AI 必须返回一个包含task属性的 JSON 对象task遵循 UpdatedTaskSchema在BaseTaskSchema基础上扩展subtasks数组并启用strict()严格模式。执行端在写回前会补齐默认值dependencies缺省为空数组、priority/details/testStrategy缺省为nullupdate-task-by-id.js并强制校验title与description非空从结构上保证更新结果完整可用。字段级快捷语法对于只改单个字段的场景文档定义了紧凑的快速语法把任务编号 字段操作写在一行5 priority:high → 只更新优先级 5 add-time:4h → 在时间估算上追加 4 小时 5 status:review → 修改状态 5 depends:3,4 → 添加依赖任务 3、4这类语法同样作为自然语言 prompt 交给 AI 解析其价值在于用最短输入表达明确意图配合下文提到的状态保护机制可以安全地完成只改状态不动正文的操作。AI 驱动的三阶段更新流程文档将 AI 的更新过程划分为三个环节与源码实现一一对应1. 理解上下文Understands ContextAI 在生成更新前需要读取任务当前状态、识别更新意图、保持与既有内容一致、保留关键信息。源码中这一阶段由 ContextGatherer 支撑它会将任务库展平用FuzzyTaskSearch以任务标题 描述 用户 prompt为查询词检索最多 5 个相关任务把相关任务的上下文一并注入 promptformat: research让 AI 的更新不孤立于项目语境。2. 应用更改Applies ChangesAI 根据 update-task.json 中的系统提示更新相关字段、保持风格一致、只增不减、增强可读性。提示模板有两条硬性约束值得注意绝不改动任务标题且除 prompt 明确提及外维持相同的 ID、状态与依赖update-task.json对于已完成子任务禁止直接修改其内容而是新增一个子任务来标注需要变更的部分。3. 验证结果Validates ResultsAI 输出后执行端会做多轮校验与修复详见下一节检查输出对象结构合法性、恢复被 AI 篡改的 ID/状态、修正子任务 ID 编号、还原被误改的已完成子任务并合并原有元数据——即文档所说检查一致性、验证完整性、维护关系。源码级执行链路与保护机制update-task命令的完整调用链为CLI 参数解析 (commands.js) → updateTaskById (update-task-by-id.js) → tryUpdateViaRemote (packages/tm-bridge/src/update-bridge.ts) // Hamster/API 存储优先 → readJSON 任务定位与状态检查 → ContextGatherer FuzzyTaskSearch可选 → getPromptManager().loadPrompt(update-task, params, variant) → generateObjectService / generateTextService统一 AI 服务 → 结果校验/修复 → writeJSON 写回 tasks.json其中 update-task-by-id.js 会先尝试通过tm/bridge的远程更新路径API 存储场景失败则回退到本地文件存储逻辑。prompt 模板按append/research/default三个变体加载update-task-by-id.js默认走结构化对象输出generateObjectService追加模式走纯文本输出generateTextService。以下五条保护机制是单任务更新的可靠性关键均来自 update-task-by-id.js已完成任务锁定任务状态为done/completed时直接拒绝更新并提示先改回pending/in-progress再执行L152-L180。这是保持一致性的最强约束。ID 与状态回写保护若 AI 改动了任务 ID执行端强制恢复原 ID只有 prompt 中明确出现 status 时才允许状态变更否则恢复原状态L482-L496。子任务 ID 修正AI 可能返回字符串 ID 或以父任务 ID 为前缀的编号执行端会统一重排为从 1 开始的连续整数并过滤掉指向自身或未来子任务的非法依赖L497-L539。已完成子任务保全若 AI 修改或删除了done/completed子任务执行端会将其还原新需求应通过新增子任务表达L541-L584。元数据合并AI 输出不含metadata字段执行端将原任务元数据与本次提供的 metadata 合并后写回避免丢失L587-L596。完整示例一次带反馈的更新会话文档给出了一个端到端的交互示例展示自然语言输入、AI 处理与结果反馈的完整形态/taskmaster:update/single 5: add rate limiting → Updating Task #5: Implement API endpoints Current: Basic CRUD endpoints Adding: Rate limiting requirements Updated sections: ✓ Description: Added rate limiting mention ✓ Details: Added specific limits (100/min) ✓ Test Strategy: Added rate limit tests ✓ Complexity: Increased from 5 to 6 ✓ Time Estimate: Increased by 2 hours Suggestion: Also update task #6 (API Gateway) for consistency?值得注意的是示例中复杂度从 5 提到 6、时间估算增加 2 小时这类联动调整正是 AI 依据 update-task.json 中在保证基本结构前提下将变更深思熟虑地应用到任务上的指导原则完成的末尾是否同时更新任务 #6的建议则对应源码中将相关任务上下文注入 promptContextGatherer的设计——AI 在更新时已经看到了关联任务的上下文因此能主动提示联动影响。智能特性与增量更新文档总结了单任务更新的三项智能能力前两项在源码中有明确对应实现增量更新Incremental Updates核心是只增不改、保留历史。对应--append追加模式AI 仅生成新增内容执行端将其封装为info added on {ISO 时间戳}.../info added on ...标签块追加到任务 details 末尾update-task-by-id.js每次变更都带时间戳天然形成可追溯的更新历史。一致性检查Consistency Checks包括关联任务对齐FuzzyTaskSearch 上下文注入、子任务兼容已完成子任务保全、依赖有效性依赖过滤与去重、时间线影响时间估算联动全部在写回前完成。更新历史Update History以时间戳标签、description 中追加的[Updated: 日期]标记prompt 短于 100 字符时触发L417-L421等形式记录何时、因何更新配合 git 版本管理即可追溯任务演进。更新后的收尾动作命令执行成功后CLI 会输出更新后的任务摘要ID/标题/状态表格、AI 用量统计displayAiUsageSummary并在追加模式下展示新增内容片段。文档建议的 post-update 检查清单为展示更新后的任务、高亮变更点、检查关联任务、给出后续更新建议、评估时间线影响。对于多标签任务库可通过--tag指定操作范围文件存储场景要求任务 ID 为纯数字1.2这类子任务 ID 请改用update-subtask-by-id命令处理update-task-by-id.js。相关资源批量/智能更新对照update-task.md命令总览tm-main.mdCLI 命令定义scripts/modules/commands.js核心执行实现scripts/modules/task-manager/update-task-by-id.js提示模板default/append/research 变体src/prompts/update-task.json输出结构校验src/schemas/update-task.js、src/schemas/update-tasks.js【免费下载链接】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），仅供参考
)
)
