Task Master update-task 命令统一迁移指南：策略模式重构任务与子任务更新架构

Task Master update-task 命令统一迁移指南策略模式重构任务与子任务更新架构【免费下载链接】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-master 仓库中的update-task-migration-plan.md迁移计划展开系统讲解如何将遗留的update-tasks.js批量更新与update-subtask-by-id.js单条子任务更新合并为统一的update-task命令并迁移到packages/tm-coreapps/cli的新架构。读者读完将掌握智能行为检测规则、策略模式 模板方法模式 工厂模式的具体落地方式、上下文采集与提示词构建的调用链以及分 11 个阶段的渐进式迁移与回滚策略。迁移背景为什么需要统一 update 命令在 claude-task-master 的旧架构中任务更新逻辑分散在两个独立文件中职责重叠且维护成本高旧模块职责输入格式AI 服务update-tasks.js从指定 ID 起批量更新多个任务--fromid --promptcontextgenerateObjectService结构化 schema 输出update-subtask-by-id.js向特定子任务追加带时间戳的信息--idparentId.subtaskId --promptnotesgenerateTextService自由文本输出两者共享大量相同逻辑任务加载、上下文采集、提示词构建、CLI 展示、错误处理却各自维护一份拷贝。迁移计划的核心目标是把它们合并为单一update-task命令并按照tm-core与apps/cli的既有模式完成面向对象重构——这一点可以从 packages/tm-core/src/modules/commands/index.ts 的占位注释得到印证该文件明确写着 Placeholder for future migration任务命令的执行编排正是计划中的待迁移内容。统一命令设计与智能行为检测迁移后的新命令语法如下# 更新单个任务替代 update-task task-master update-task --id3 --promptchanges # 更新单个子任务替代 update-subtask task-master update-task --id3.2 --promptimplementation notes # 从 ID 起批量更新多个任务替代 update --from task-master update-task --from3 --promptchanges命令不需要显式声明模式而是通过智能行为检测自动判定判定顺序如下ID 包含.→ 子任务模式subtask mode例如--id3.2存在--from标志→ 批量更新模式bulk mode默认→ 单任务更新模式single task mode这一检测逻辑在计划中由UpdateStrategyFactory.detectMode()实现代码骨架清晰地体现了判定优先级先判--from再判带点号的--id最后是普通--id三者均缺失则抛出TaskMasterError。结合旧实现可以验证该设计的一致性update-tasks.js 中批量筛选条件为task.id fromId task.status ! done而 update-subtask-by-id.js 通过parentId.subtaskId拆分字符串并校验两段均为正整数——这些规则全部被吸收进新设计的TaskIdValidator与各策略的validate()中。功能清单从输入校验到持久化的完整链路迁移计划给出了一个覆盖全流程的功能清单它实际上是对旧实现行为的逐条核对。以下结合源码逐层展开。输入校验与解析校验tasksPath文件存在旧实现中update-subtask-by-id.js通过fs.existsSync(tasksPath)显式检查校验id参数任务必须为整数子任务必须为parent.child格式校验fromId正整数校验prompt非空字符串子任务模式例外——见下文的 metadata-only 快速路径解析子任务 ID拆分parentId.subtaskId并分别校验项目根目录优先取上下文传入的projectRoot否则调用findProjectRoot()两者都拿不到则抛出Could not determine project root directory双模式支持通过mcpLog是否存在判定 MCP 模式isMCP !!mcpLog并据此选择mcpLog或consoleLog作为日志函数输出格式text或jsonMCP 模式下自动为jsonupdate-subtask-by-id.js中默认值即为context.mcpLog ? json : text。任务加载与过滤统一通过readJSON(tasksPath, projectRoot, tag)加载tasks.json三种模式过滤逻辑不同批量模式id fromId 且 status ! done若筛选结果为空则优雅地提示 No tasks to update 并直接返回单任务模式按 ID 精确查找子任务模式先按父 ID 找到父任务校验其subtasks数组存在再在数组中定位具体子任务。上下文采集ContextGatherer 与 FuzzyTaskSearch 的协作两种旧实现都使用同一套上下文采集流程迁移计划将其收敛到ContextBuilderService以projectRoot和tag初始化ContextGatherer——该类的构造器会从.taskmaster/tasks/tasks.json预加载全部任务见 contextGatherer.js用flattenTasksWithSubtasks()拍平所有任务与子任务初始化FuzzyTaskSearch按命令类型选择搜索配置批量/单任务模式用update子任务模式用update-subtask批量/单任务模式直接用 prompt 搜索最多 5 条结果并包含自身子任务模式用${parentTask.title} ${subtask.title} ${prompt}组合查询串搜索见 update-subtask-by-id.js将待更新任务 ID 集合与相关上下文任务 ID 集合合并去重以research格式调用gatherer.gather({ tasks, format: research })采集失败仅告警并继续Could not gather additional context。值得说明的是FuzzyTaskSearch的搜索算法见 fuzzyTaskSearch.js底层基于 Fuse.js按 title权重 2.0、description权重 1.5、details权重 1.0、dependencyTitles权重 0.5加权模糊匹配并按 relevance 阈值high 0.25、medium 0.4、low 0.6分层最后补充最多 5 条最近任务与类别匹配任务。计划中的ContextBuilderService.buildContext()骨架正是这套流程的封装且在 catch 中返回{ context: , taskIds: options.targetTaskIds }兜底。提示词构建PromptManager 双模板通过getPromptManager()获取PromptManager后加载模板两种模式参数不同批量/单任务模式update-tasks模板{ tasks: tasksToUpdate, // 待更新任务数组 updatePrompt: prompt, // 用户提示词 useResearch, // 是否使用 research AI 角色 projectContext: gatheredContext, // 采集到的上下文 hasCodebaseAnalysis: hasCodebaseAnalysis(useResearch, projectRoot, session), projectRoot }对应 update-tasks.js 的实际调用。子任务模式update-subtask模板额外传入parentTaskid、title、prevSubtask若存在含 id/title/status、nextSubtask若存在、currentDetails现有 details 或兜底文案并支持research/default变体键——旧实现通过const variantKey useResearch ? research : default传入loadPrompt第三参。AI 服务集成结构化对象 vs 自由文本计划要求根据useResearch决定服务角色research | main再按模式调用不同的统一 AI 服务批量/单任务模式generateObjectService({ role, session, projectRoot, systemPrompt, prompt, schema: COMMAND_SCHEMAS[update-tasks], objectName: tasks, commandName: update-tasks, outputType: isMCP ? mcp : cli })。旧实现随后对返回的mainResult.tasks做字段归一化为 dependencies、priority、details、testStrategy、subtasks 等字段填充默认值见 update-tasks.js子任务模式generateTextService({ prompt, systemPrompt, role, session, projectRoot, maxRetries: 2, commandName: update-subtask, outputType })并处理空/非法响应。两条服务都要求捕获telemetryData与tagInfo用于用量展示。数据更新与持久化批量/单任务模式的合并策略对应旧实现 update-tasks.js计划中移植到DataMergerService.mergeTasks()解析aiServiceResponse.mainResult.tasks数组并校验结构用Map按任务 ID 建立索引实现高效查找遍历原数据命中则{ ...task, ...updatedTask, subtasks: updatedTask.subtasks ! undefined ? updatedTask.subtasks : task.subtasks }——保留 AI 未返回的 subtasks 字段是关键防数据丢失点统计真实更新条数actualUpdateCount。子任务模式的追加策略对应 update-subtask-by-id.js移植到DataMergerService.mergeSubtask()提取mainResult文本生成 ISO 时间戳格式化为info added on ${timestamp}\n${content}\n/info added on ${timestamp}块追加到subtask.details不存在则创建并单独保存新增片段用于展示若 prompt 长度 100 字符向subtask.description追加[Updated: ${date}]日期标记。最后统一writeJSON(tasksPath, data, projectRoot, tag)写回并保留当前被注释的generateTaskFiles()调用点。此外旧实现还包含一个metadata-only 快速路径update-subtask-by-id.js当只传metadata而不传 prompt 时跳过 AI 直接合并 metadata 字段并写盘这一行为也应在新架构中保留。CLI 展示、日志与错误处理更新前展示仅 CLI text 模式用cli-table3生成 ID/Title/Status 三列表格任务标题截断 57 字符、子任务 52 字符状态通过getStatusWithColor()着色用boxen输出带边框的标题批量模式额外输出已完成子任务如何处理的信息框加载指示器AI 调用前startLoadingIndicator(Updating tasks with AI...)或Updating subtask...完成或出错时stopLoadingIndicator()research 变体有独立文案更新后展示批量模式输出成功条数子任务模式用绿色边框 boxen 展示子任务 ID、标题与 Newly Added Snippet时间戳内容最后通过displayAiUsageSummary(telemetryData, cli)展示 AI 用量日志与调试按mcpLog/consoleLog分流getDebugFlag(session)为真时输出子任务更新前后 details、writeJSON 调用、完整错误堆栈错误处理分级上下文采集失败告警继续、AI 服务失败停止并上报、一般错误CLI 打印红色错误并process.exit(1)MCP 直接 re-throw。CLI 模式下对常见错误API key 缺失、模型过载、任务/子任务不存在、ID 格式非法、空 prompt、空 AI 响应提供针对性排查提示——例如子任务未找到时建议运行task-master list --with-subtasks查看可用 ID返回值契约成功时批量/单任务返回{ success: true, updatedTasks, telemetryData, tagInfo }子任务返回{ updatedSubtask, telemetryData, tagInfo }失败时 CLI 退出码 1、MCP 抛错、子任务模式返回null。新架构设计tm-core 中的策略模式实现迁移计划为update-task在packages/tm-core下设计了完整的目录结构遵循 tm-core 的既有约定领域隔离、依赖注入、抽象基类、接口契约、服务层编排、工厂模式与单一职责原则。包结构总览packages/tm-core/ src/commands/update-task/ types.ts # 共享类型、枚举、接口 interfaces/ update-strategy.interface.ts # IUpdateStrategy 契约 update-context.interface.ts # IUpdateContext 契约 display.interface.ts # IDisplayManager 契约 update-task.service.ts # 主编排服务 context-builder.service.ts # 构建 AI 上下文 prompt-builder.service.ts # 构建提示词 >async execute(context: IUpdateContext): PromiseUpdateStrategyResult { await this.validate(context); const tasks await this.loadTasks(context); const prompts await this.buildPrompts(context, tasks); const aiResult await this.callAIService(context, prompts); const merged await this.mergeResults(context, aiResult, tasks); return merged; }子类只需实现validate()、loadTasks()、getMode()与受保护的getPromptParams()共享逻辑提示词构建、AI 调用、数据合并由基类与三个辅助服务完成。三种具体策略的分工BulkUpdateStrategy校验--from存在加载id fromId status ! done的任务调用generateObjectServiceSingleTaskUpdateStrategy通过TaskIdValidator.validateTaskId()校验整数 ID加载单个任务AI 调用与批量相同SubtaskUpdateStrategy通过TaskIdValidator.parseSubtaskId()校验点号格式定位父任务与子任务并携带前后子任务上下文调用generateTextServicemergeResults()中生成info added on ${timestamp}时间戳块追加到subtask.details。ContextBuilderService / PromptBuilderService / DataMergerService三个辅助服务分别封装上下文采集、模板加载与结果合并各自只依赖已有工具类ContextGatherer、FuzzyTaskSearch、PromptManager保证可独立单测。UpdateStrategyFactory的detectMode()实现了本文第二节的行为检测规则createStrategy(mode)按枚举创建对应策略并注入依赖未知模式抛出TaskMasterError。IDisplayManager接口定义showPreUpdate / startLoading / stopLoading / showPostUpdate / showTelemetry / showError六个方法CLIDisplayManager用 chalk、boxen、cli-table3 实现终端渲染JSONDisplayManager面向 MCP 输出结构化结果UpdateDisplayFactory按运行环境选择实现。依赖注入与初始化计划在packages/tm-core/src/commands/update-task/index.ts提供工厂函数createUpdateTaskService(configManager, storage)依次创建 logger、ContextBuilderService、PromptManager复用现有getPromptManager()、PromptBuilderService、DataMergerService、AIService对generateObjectService/generateTextService的包装组装UpdateStrategyFactory与UpdateDisplayFactory最后注入UpdateTaskService。CLI 侧apps/cli/src/commands/update-task.command.ts只需调用该工厂并执行——这与现有 CLI 命令的模式一致例如 next.command.ts 继承Commander.Command作为薄展示层、内部委托TmCore的做法。分阶段实施路线11 个 Phase迁移计划将实施拆分为 11 个阶段每阶段都有明确的新增文件、测试与复用对象可按序增量交付Phase内容关键产出1基础与核心类型types.ts、三个接口文件研究BaseExecutor、TaskService、IStorage的模式2校验器与工具UpdateInputValidator、TaskIdValidator移植两个旧文件的校验逻辑 对应 spec3服务层ContextBuilderService复用 ContextGatherer/FuzzyTaskSearch、PromptBuilderService复用 PromptManager、DataMergerService移植 update-tasks.js L250-273 与 update-subtask-by-id.js L291-332 的合并逻辑 spec4策略模式实现抽象基类 三种策略Bulk/Single 用generateObjectServiceCOMMAND_SCHEMAS[update-tasks]Subtask 用generateTextService spec5展示层CLIDisplayManager复用 chalk/boxen/cli-table3/getStatusWithColor、JSONDisplayManager、UpdateDisplayFactory spec6工厂模式UpdateStrategyFactorycreateStrategy()与detectMode() spec7主服务编排UpdateTaskService、index.ts导出类型 工厂 服务类集成 spec8CLI 集成update-task.command.tscommander 定义在 CLI 入口注册命令可选兼容别名9集成与测试三模式端到端、MCP vs CLI、全清单边界用例、性能对比10文档与弃用更新命令参考文档、JSDoc、为旧命令加弃用警告、changeset11清理未来版本删除旧文件与兼容垫片更新全部引用计划中提到的COMMAND_SCHEMAS来自 src/schemas/registry.js统一 AI 服务来自 scripts/modules/ai-services-unified.js这两处是策略层移植时的既有依赖。测试策略与边界用例单元测试覆盖模式检测逻辑、ID 解析与校验、上下文采集集成、各模式提示词构建、数据合并逻辑。集成测试覆盖批量/单任务/单子任务三条工作流、MCP 与 CLI 双模式运行。边界用例清单包括空tasks.json非法 ID 格式如负数、非数字、5.、.2不存在的 ID无子任务的任务空 AI 响应上下文采集失败应告警继续而非中断计划中的update-task.service.spec.ts集成测试与data-merger.service.spec.ts单元测试可直接对照旧实现的合并逻辑逐条断言。向后兼容、风险缓解与成功标准向后兼容采用渐进式弃用旧命令保持可用 → 添加弃用警告 → 更新文档 → 下个大版本移除。可选方案是保留旧命令名作为别名内部转发task-master update --from3 --prompt... # 仍可用实际调用 update-task task-master update-subtask --id3.2 --prompt... # 仍可用实际调用 update-task高风险区域与对策数据完整性——确保writeJSON不损坏既有数据保留 subtasks 字段、Map 合并、原子写AI 服务兼容性——generateObjectService与generateTextService必须同时工作子任务 details 格式——维持时间戳块格式一致性info added on ${timestamp}标签必须成对闭合上下文采集——各模式行为保持一致。回滚计划旧文件保留至新版本充分测试通过版本号升级支持回退发布前完成全量测试覆盖。成功标准清单全部核验通过、各模式测试通过、MCP 集成可用、CLI 展示与既有行为一致、文档更新、无功能回归、性能不劣于现有实现。结语这份迁移计划的价值在于它不是一次简单搬文件而是把两个行为相似、实现重复的遗留模块按照策略模式、模板方法模式、工厂模式和服务层模式重构成单一命令的完整工程蓝图。packages/tm-core的目录骨架、接口契约如 storage.interface.ts与apps/cli的 Commander 命令模式均已就绪迁移者只需按 11 个 Phase 顺序实施即可在保持 CLI 与 MCP 双模式行为一致的前提下把任务更新逻辑收敛到可单测、可扩展、可替换策略的新架构中。【免费下载链接】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），仅供参考