claude-task-master 的 TypeScript 核心库 tm-core任务编排架构、模块化设计与开发指南【免费下载链接】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-masterpackages/tm-core是 Task Master AI本仓库 claude-task-master 的 AI 驱动任务管理系统的核心 TypeScript 库负责任务创建、管理与 AI 编排能力。本文将以 packages/tm-core/README.md 为主线结合仓库内源码统一门面TmCore、存储接口、错误体系、ID 生成器与架构文档系统讲解 tm-core 的设计目标、安装使用、模块划分、底层原理与开发流程帮助你理解并上手这一可嵌入 Cursor、Lovable、Windsurf、Roo 等环境的任务管理基础设施。tm-core 是什么Task Master 体系中的地基tm-core 是支撑 Task Master AI 任务管理系统的核心库其定位在源码中写得很明确Core library for Task Master - TypeScript task management system —— package.json它提供了创建、管理、编排任务的完整工具集并面向 AI 集成设计。仓库中 CLIapps/cli、MCP Servermcp-server与 VS Code 扩展apps/extension等上层应用都可通过统一的 TypeScript API 复用其能力。从目录结构看tm-core 已从初始骨架演进为包含 auth、briefs、config、git、loop、prompts、reports、storage、tasks、workflow、execution、integration 等十余个功能模块的成熟核心库完整实现可查看 src/modules 目录。核心特性一览README 定义了 tm-core 的八项核心特性它们在当前源码中均有对应实现特性说明仓库依据TypeScript-first全 TypeScript 实现严格类型检查tsconfig.json、全量.ts源码双格式支持同时支持 ESM 与 CommonJS自动检测格式package.json 的exports字段模块化架构职责清晰分离按功能划分独立模块src/modules 下 135 个模块文件AI Provider 集成可插拔的 AI Provider 系统src/modules/ai灵活存储抽象存储层支持多种持久化策略src/modules/storage任务解析面向多种任务定义格式的解析能力src/modules/tasks/parser错误处理带具体错误类型的完整错误体系src/common/errors/task-master-error.ts测试覆盖Jest/Vitest TypeScript 的测试体系tests 与各.spec.ts/.test.ts文件需要说明的是README 中的Jest描述对应早期规划当前仓库实际已迁移到 Vitest见 package.json 的test: vitest run脚本以及 POC-STATUS.md 中的说明。安装与快速上手安装npm install task-master/tm-core依赖环境要求 Node.js 20.0.0README 明确要求。tm-core 自身的运行时依赖包括supabase/supabase-jsSupabase 客户端、date-fns日期处理、fs-extra、proper-lockfile文件锁、simple-gitGit 操作、steno与zod校验见 package.json。基本用法README 中的最小示例展示了任务 ID 生成与任务对象创建import { generateTaskId, PlaceholderTask } from task-master/tm-core; // 生成唯一任务 ID const taskId generateTaskId(); // 创建任务README 标注 full implementation coming soon const task: PlaceholderTask { id: taskId, title: My Task, status: pending, priority: medium };这里需要注意一个命名与实现差异README 中描述的是规划期的 API 形态task-master/tm-core包名、PlaceholderTask占位类型。在当前仓库中包名实际为tm/core且入口 API 已升级为统一的createTmCore门面。当前推荐写法如下出自 src/index.ts 的 JSDoc 示例import { createTmCore } from tm/core; const tmcore await createTmCore({ projectPath: process.cwd() // 必须是绝对路径 }); // 通过领域门面访问各类能力 await tmcore.auth.login({ ... }); const tasks await tmcore.tasks.list(); await tmcore.workflow.start({ taskId: 1 }); await tmcore.git.commit(feat: add feature); const config tmcore.config.get(models.main);模块化导入与包导出映射README 给出了按需引入子模块以减少打包体积的方式// 仅引入类型 import type { TaskId, TaskStatus } from task-master/tm-core/types; // 引入工具函数 import { generateTaskId, formatDate } from task-master/tm-core/utils; // 引入存储 import { PlaceholderStorage } from task-master/tm-core/storage; // 引入解析器 import { PlaceholderParser } from task-master/tm-core/parser; // 引入错误类 import { TmCoreError, TaskNotFoundError } from task-master/tm-core/errors;对照当前实现模块化导入的机制已由 package.json 的exports字段落地实际暴露的子路径为tm/core→ 主入口 src/index.tstm/core/testing→ 测试夹具 src/testing/index.tstm/core/auth、tm/core/storage、tm/core/config、tm/core/providers、tm/core/services、tm/core/errors、tm/core/logger、tm/core/types、tm/core/interfaces、tm/core/utils例如 MCP 集成场景可通过tm/core/logger单独引入日志能力。使用前建议以当前仓库实际的exports字段为准README 中的规划路径parser等为演进前的目标形态。统一门面 TmCore唯一入口的设计哲学当前 tm-core 最重要的架构决策是createTmCore是使用 tm-core 的唯一方式。这在 src/tm-core.ts 中被反复强调This is the ONLY way to create TmCore / This is the ONLY entry point for using tm-coreTmCoreOptions支持三个配置项export interface TmCoreOptions { /** 项目根目录绝对路径 */ projectPath: string; /** 可选的配置覆盖 */ configuration?: PartialIConfiguration; /** 可选日志配置用于 MCP 集成与调试 */ loggerConfig?: LoggerConfig; }构造函数为私有强制通过静态工厂TmCore.create(options)创建从而保证实例总是经过完整初始化。initialize()的初始化顺序揭示了整个库的依赖关系src/tm-core.ts#L164-L208先创建 logger保证后续任何日志可用创建ConfigManager配置单一事实来源管理 active tag 与存储设置若传入configuration覆盖项则写入配置管理器初始化七个领域门面AuthDomain、TasksDomain、WorkflowDomain、GitDomain、ConfigDomain、IntegrationDomain、LoopDomain异步初始化TasksDomain并将TasksDomain注入WorkflowDomain工作流需要任务领域更新状态通过close()释放文件锁等资源。createTmCore的构造函数还会校验projectPath缺失或非绝对路径都会抛出带MISSING_CONFIGURATION/INVALID_INPUT错误码的TaskMasterError。初始化失败时统一包装为INTERNAL_ERROR并保留原始错误作为cause。loggerConfig的典型使用场景是 MCP 集成——将日志回调直接注入使库内部所有日志实时转发到 MCPimport { createTmCore, LogLevel } from tm/core; const tmcore await createTmCore({ projectPath: args.projectRoot, loggerConfig: { level: LogLevel.INFO, mcpMode: true, logCallback: log // MCP 的 log 函数 } }); tmcore.logger.info(Operation completed);架构分层从六模块规划到领域化实现规划中的六模块划分README 将库划分为六个关键模块types/TypeScript 类型定义与接口providers/AI Provider 实现用于任务生成storage/不同持久化策略的存储适配器parser/多种格式的任务解析工具utils/通用工具函数errors/自定义错误类与错误处理当前源码的领域化演进从实际源码结构看模块划分已按领域驱动思路扩展为src/modules/下的功能域auth、briefs、config、git、loop、prompts、reports、storage、tasks、workflow、execution、integration、ai、commands、dependencies、ui公共类型与基础设施下沉到src/common/constants、errors、interfaces、logger、mappers、schemas、types、utils。listTasks 的五层架构佐证packages/tm-core/docs/listTasks-architecture.md 以listTasks为例给出了更细的分层设计这一 POC 直接验证了 README 描述的模块化与职责分离CLI 层只负责 UI 渲染表格、进度条、json/text/markdown/compact 输出格式不做业务逻辑Facade 层TaskMasterCore / TasksDomain对外提供listTasks(options)支持 tag 过滤、状态过滤、子任务包含/排除Service 层TaskService核心业务逻辑协调 ConfigManager 与 StorageDomain 层TaskEntity封装业务逻辑、校验、状态迁移与依赖检查canComplete()Infrastructure 层StorageIStorage接口抽象FileStorage处理本地文件正确映射mastertag 到 tasks.jsonApiStorage对接 HamsterStorageFactory依据配置自动选择后端存储层不含任何业务逻辑。数据流为CLI 请求 → ConfigManager 确定 active tag 与存储类型 → Storage 按 tag 读取 → TaskEntity 应用业务逻辑与过滤 → 返回结构化结果。典型调用const result await core.listTasks({ tag: feature-branch, filter: { status: [pending, in-progress], priority: high, search: authentication }, includeSubtasks: true });存储抽象IStorage 契约与配置参数README 强调灵活的存储层支持不同持久化策略其底层契约定义在 src/common/interfaces/storage.interface.ts。IStorage接口包含 20 余个方法覆盖任务全生命周期读取loadTasks(tag?, options?)、loadTask(taskId, tag?)、loadMetadata(tag?)、exists(tag?)写入saveTasks、appendTasks、updateTask、updateTaskWithPrompt支持useResearch与mode: append | update | rewrite、updateTaskStatus、deleteTaskAI 扩展expandTaskWithPrompt支持numSubtasks、useResearch、additionalContext、forceTag 管理getAllTags、createTag、deleteTag、renameTag、copyTag、getTagsWithStats、getCurrentBriefName基础设施initialize、close、getStats、getStorageType、watch监听任务变更支持debounceMs防抖抽象基类BaseStorage提供三个公共工具方法protected generateBackupPath(originalPath: string): string; // 生成带时间戳的备份文件名 protected validateTask(task: Task): void; // 校验 id/title/description/status 必填 protected sanitizeTag(tag: string): string; // tag 名文件系统安全化转小写、非法字符替换为 -StorageConfig的完整参数如下可在创建存储时按需配置参数默认值说明basePath必填存储基础路径enableBackupfalse是否创建备份maxBackups未设保留的最大备份数enableCompressionfalse是否启用压缩encodingutf8文件编码atomicWritesfalse是否启用原子写入FileStorage 相关实现细节可继续阅读 src/modules/storage/adapters/file-storage含file-operations.ts、format-handler.ts、path-resolver.ts存储工厂见 src/modules/storage/services/storage-factory.ts。POC 文档还提到性能侧的设计文件锁保证并发访问安全、临时文件原子写入、指数退避重试与请求超时处理。错误体系TaskMasterError 与 ERROR_CODESREADME 强调带具体错误类型的完整错误体系。核心实现是 src/common/errors/task-master-error.ts 中的TaskMasterError它与ERROR_CODES常量30 个错误码覆盖文件、解析、校验、API/网络、任务、存储、配置、Provider 等类别配合使用throw new TaskMasterError( Failed to parse task file, ERROR_CODES.PARSE_ERROR, { details: { filename: tasks.json, line: 42 }, operation: parseTaskFile, userMessage: There was an error reading your task file } );TaskMasterError提供的核心能力错误码与上下文code字段支持编程式处理context携带operation、resource、operationStack、userMessage、errorId等元数据错误链cause属性支持错误包装wrap()与上下文追加withContext()hasCode()可沿 cause 链递归判断错误码序列化toJSON()输出可传输的SerializableError嵌套 cause 递归序列化安全输出getSanitizedDetails()会过滤 password、token、key、secret、auth、credential 等敏感键后再返回用户可见信息调试友好toString()输出TaskMasterError[CODE]: message (operation: xxx) (resource: xxx)格式并附带Caused by链。工具函数任务 ID 生成与校验README 提到generateTaskId与formatDate等工具其实现位于 src/common/utils/id-generator.ts。任务 ID 使用TASK-{时间戳}-{随机串}格式随机部分通过node:crypto的randomBytes生成保证密码学级随机性const taskId generateTaskId(); // 形如: TASK-1704067200000-A7B3 isValidTaskId(TASK-1704067200000-A7B3); // true配套函数还包括generateSubtaskId(parentId, existingSubtasks)按父ID.序号递增生成子任务 IDisValidTaskId/isValidSubtaskId正则/逐段校验 ID 格式子任务 ID 支持嵌套如TASK-xxx.1.2getParentTaskId(subtaskId)从子任务 ID 提取父任务 IDnormalizeDisplayId(id)将ham31、HAM31、ham-31等显示 ID 归一化为HAM-31兼容子任务格式与纯数字。ID 校验的 Zod schema 与测试见 src/common/schemas/task-id.schema.ts 及其.spec.ts。更多工具路径规范化、项目根目录查找、Git 工具、run ID 生成位于 src/common/utils。开发指南环境、脚本与双格式支持环境与设置# 安装依赖 npm install # 构建库 npm run build # 运行测试 npm test # 覆盖率测试 npm run test:coverage # 代码检查 npm run lint # 格式化 npm run format完整脚本表脚本说明build同时构建 ESM 与 CJS 两种格式build:watch监听模式构建test运行测试套件当前为vitest runtest:watch监听模式运行测试test:coverage带覆盖率报告运行测试lint/lint:fix代码检查 / 自动修复Biomeformat/format:check格式化 / 检查格式Biometypechecktsc --noEmit仅类型检查clean清理构建产物dev监听模式开发当前 package.json 中测试脚本细分为test:unit**/*.spec.ts与test:integration**/*.test.ts可分别运行单元与集成测试。ESM 与 CommonJS 双格式README 强调包自动支持两种模块格式// ESM import { generateTaskId } from task-master/tm-core; // CommonJS const { generateTaskId } require(task-master/tm-core);当前包通过exports字段指向./src/index.ts等 TypeScript 源文件与构建配置实现双格式消费main指向./dist/index.jstype为module。路线图与实现状态README 将开发拆解为任务编号明确的路线图并给出了实现清单Implementation Checklist✅ Task 115已完成初始化 tm-core 包结构——目录结构、构建/测试基础设施、barrel 导出文件、开发工具链与文档、结构校验。 待实现任务Task 116完整类型定义任务/项目/配置、Zod schema 校验、泛型工具Task 117AI Provider 系统基类接口、Anthropic/OpenAI/Perplexity 集成、Provider 工厂与注册表Task 118存储层文件系统与内存适配器、存储接口与工厂Task 119任务解析器PRD、Markdown、JSON 格式解析与校验工具Task 120工具函数任务 ID 生成、日期格式化、校验辅助、文件系统工具Task 121错误处理任务/存储/Provider/校验错误Task 122配置系统配置 schema、默认配置、环境变量支持Task 123测试基础设施单元/集成测试、Mock 工具Task 124文档API 文档、使用示例、迁移指南Task 125包最终化最终测试与校验、发布准备、CI/CD 集成注意该路线图反映 README 撰写时的规划状态。从当前源码看其中多项任务已有相当进展——例如 Zod 校验 schemasrc/common/schemas、src/modules/tasks/validation、文件系统存储适配器src/modules/storage/adapters/file-storage、AI Provider 基类src/modules/ai/providers/base-provider.ts、完整错误体系、配置管理器src/modules/config/managers/config-manager.ts以及包含 auth、loop、workflow、git 等领域的大量实现均已落地。若需了解当前各模块的具体进度建议以 src/modules 目录源码与 tests 集成测试为准。结语tm-core 通过统一门面 领域模块 抽象存储的三层设计为 Task Master 生态提供了类型安全、可测试、可扩展的核心底座。无论是作为上层 CLI/MCP/扩展的依赖还是作为独立任务管理库集成进自己的工具链理解createTmCore门面、IStorage契约与TaskMasterError错误体系这三个核心概念就掌握了使用它的关键。后续可继续阅读 POC-STATUS.mdlistTasks 端到端验证报告、listTasks-architecture.md分层架构详解以及 tests 下的集成测试深入理解各模块的协作方式。【免费下载链接】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），仅供参考