AI Agent 任务管理实践：用 task-manager skill 构建结构化工作流

最新推荐文章于 2025-12-21 16:12:16 发布

原创最新推荐文章于 2025-12-21 16:12:16 发布 · 674 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能 #prompt #上下文工程 #Skills

AI 探索专栏收录该内容

40 篇文章

订阅专栏

AgenticCoding·十二月创作之星挑战赛 10w+人浏览 451人参与

AI Agent 任务管理实践：用 task-manager skill 构建结构化工作流

在这里插入图片描述

Why - 为什么需要任务管理

标准 SOP 的自动化执行困境

许多团队已经沉淀了成熟的标准操作流程（SOP）：功能开发流程、Bug 修复流程、发布上线流程等。这些 SOP 通常以文档形式存在，描述了清晰的步骤、检查点和依赖关系。

核心问题：如何让 AI Agent 按照这些既定的 SOP 自动化执行？

// 典型的 SOP 文档
## 功能开发流程
1. 需求分析 -> 2. 技术设计 -> 3. 编码实现 -> 4. 代码审查 -> 5. 测试验收

// 理想状态：
// - AI Agent 读取 SOP，自动按步骤执行
// - 每个步骤完成后自动推进到下一步
// - 遇到阻塞时暂停并通知用户
// - 支持中断恢复，不丢失进度

// 现实困境：
// - SOP 是给人看的，AI 难以结构化理解
// - 步骤间的依赖关系是隐式的
// - 没有状态追踪机制
// - 每次对话都要重新"教" AI 流程

AI 编程助手的执行问题

在使用 AI Agent（如 Claude Code、Cursor Agent、Copilot 等）进行复杂项目开发时，即使有明确的 SOP，仍然面临这些问题：

SOP 无法被 AI 理解：文档化的流程对 AI 来说只是文本，难以完整可靠的自动解析步骤和依赖
上下文丢失：长对话中 AI 容易忘记之前约定的任务清单
执行顺序混乱：多个任务间存在依赖关系，AI 难以自动识别正确的执行顺序
进度不可见：不清楚哪些任务已完成、哪些正在进行、哪些被阻塞
缺乏可控性：AI 可能一次性执行过多任务，用户失去对流程的掌控

传统的做法是在对话中用自然语言描述任务列表，但这存在明显缺陷：

// 常见的"口头约定"方式
用户：按照我们的功能开发 SOP 帮我完成以下任务：
1. 初始化项目
2. 实现登录功能
3. 实现注册功能
4. 编写测试

// 问题：
// - AI 可能跳过某些步骤
// - 依赖关系（如 2 依赖 1）无法被机器理解
// - 无法持久化保存进度
// - 中断后难以恢复
// - 每个新项目都要重复描述相同的 SOP

task-manager 的设计理念

task-manager 的核心思路是：将人类可读的 SOP 转化为 AI 可执行的任务配置。

它采用配置驱动的方式，将任务管理从"隐式约定"变为"显式契约"：

维度	传统 SOP	task-manager
格式	文档/Wiki	JSON Schema
依赖关系	隐式（靠人理解）	显式（precondition 字段）
状态追踪	手动记录	6 种状态机自动管理
执行控制	人工推进	用户确认 + 自动推进
可复用性	每次重新描述	模板化，一次定义多次使用
可恢复性	依赖记忆	配置文件持久化

关键转变：SOP 从"指导人工作的文档"变为"指导 AI 工作的程序"。

What - task-manager 是什么

核心定位

task-manager 是一个零依赖的 Node.js 任务管理 Skill，设计目标是为各类 AI Agent 提供统一的任务编排能力。它不是一个通用的项目管理工具，而是一个AI-Human 协作的任务编排框架。

适用场景：

Claude Code Skill 系统
Cursor Agent（通过 AGENTS.md 集成）
任何支持执行 Shell 命令的 AI Agent

架构概览

task-manager/
├── SKILL.md                    # Skill 指令详情 
├── scripts/                    # 核心脚本
│   ├── create_from_template.mjs   # 从模板创建配置
│   ├── initialize_tasks.mjs       # 初始化/重置任务状态
│   ├── next_task.mjs              # 获取下一个可执行任务
│   ├── set_task_status.mjs        # 更新任务状态
│   └── utils.mjs                  # 共享工具函数
├── templates/                  # 预定义模板
│   └── task_templates.json
└── references/                 # 参考文档
    └── task_config_schema.md

核心概念

1. 任务层级结构

task-manager 支持两级任务结构：顶级任务（Task）和子任务（Subtask）。

{
  "tasks": [
    {
      "number": 1,
      "key": "project-setup",
      "title": "项目环境搭建",
      "description": "初始化项目结构和开发环境",
      "status": "pending",
      "priority": "high",
      "subtasks": [
        {
          "number": "1.1",
          "key": "setup-repo",
          "title": "初始化代码仓库",
          "description": "创建 Git 仓库并推送初始代码",
          "precondition": []
        },
        {
          "number": "1.2",
          "key": "setup-deps",
          "title": "安装项目依赖",
          "description": "安装所需的 npm 包和工具",
          "precondition": ["setup-repo"]
        }
      ]
    }
  ]
}

关键设计决策：

number：数字标识，顶级任务用整数（1, 2, 3），子任务用点分格式（1.1, 1.2）
key：语义化标识符，用于 precondition 引用，推荐 kebab-case 格式
subtasks：子任务数组，继承父任务的优先级（除非显式覆盖）

2. 依赖关系系统

通过 precondition 字段定义任务间的依赖关系：

{
  "number": 2,
  "key": "backend-api",
  "title": "后端 API 开发",
  "precondition": ["project-setup"]
}

{
  "number": "2.2",
  "key": "api-routes",
  "title": "实现 API 路由",
  "precondition": ["db-design"]
}

依赖解析流程：

构建 key -> number 映射表
收集所有已完成任务的 number
检查当前任务的所有 precondition 是否都在已完成集合中

3. 状态机

task-manager 定义了 6 种任务状态：

状态	含义	转换场景
`pending`	等待执行	初始状态、重置后
`in-progress`	正在执行	开始工作时
`done`	已完成	任务成功完成
`review`	待审核	需要人工审核
`deferred`	已延期	暂时跳过
`cancelled`	已取消	不再需要

状态转换的级联行为：

父任务设为 done -> 所有未完成的子任务自动标记为 done
父任务设为 pending -> 所有已完成的子任务重置为 pending

4. 执行控制策略

这是 task-manager 最核心的设计：用户确认制。

执行流程：
┌─────────────────────────────────────────────────────┐
│  获取顶级任务 -> 用户确认 -> 自动执行子任务 -> 完成 │
│       ↑                                       │     │
│       └───────── 用户确认下一个 <─────────────┘     │
└─────────────────────────────────────────────────────┘

关键规则：

顶级任务需要用户显式确认后才能开始
子任务在父任务执行过程中自动处理
顶级任务完成后必须停止，等待用户确认下一个

这种设计确保了用户始终保持对工作流的控制权。

预置模板

task-manager 提供了 6 种开箱即用的模板：

模板	用途	任务数
`placeholder`	占位符模板，需手动编辑	3
`minimal`	极简模板，快速开始	2
`web-app`	Web 应用开发工作流	5
`api-service`	RESTful API 服务开发	5
`feature-development`	标准功能开发流程	5
`bug-fix`	Bug 修复工作流	5

How - 在支持 Skills 的 Agent 中使用 task-manager

在 Claude Code 中，用户通过对话与 AI 交互，AI 会根据 skill 定义自动调用相应的脚本。用户无需直接执行命令，只需通过自然语言指令来控制任务流程。

激活 skill

在对话中告诉 Claude 使用 task-manager skill：

用户：skill: task-manager

Claude 会加载 skill 定义，进入任务管理模式。

工作流程

Step 1: 初始化项目

用户：帮我创建一个 web-app 类型的任务配置，项目名称是"用户中心重构"

Claude：好的，我来为你创建任务配置。
[Claude 调用 create_from_template.mjs 创建配置文件]

已创建任务配置文件 ./tasks.json，包含 5 个顶级任务：
1. 项目环境搭建
2. 后端 API 开发
3. 前端界面开发
4. 测试与质量保证
5. 部署上线

是否需要初始化任务状态？

用户：初始化

Claude：[Claude 调用 initialize_tasks.mjs]
任务状态已初始化，所有任务设为 pending 状态。

Step 2: 获取并执行任务

用户：next

Claude：[Claude 调用 next_task.mjs]

下一个任务：项目环境搭建
描述：初始化项目结构和开发环境
优先级：high
包含 3 个子任务

请选择操作：
- 输入 execute 开始执行当前顶级任务及其所有子任务
- 输入 skip 跳过此任务
- 输入 reset 重新初始化所有任务状态

用户：execute

Claude：开始执行「项目环境搭建」任务。
[Claude 将任务状态设为 in-progress]

当前子任务：初始化代码仓库
描述：创建 Git 仓库并配置基础结构

正在执行...
[Claude 执行具体的代码仓库初始化工作]

子任务「初始化代码仓库」已完成。

下一个子任务：安装项目依赖
描述：安装前后端所需的依赖包

正在执行...
[Claude 继续执行]

Step 3: 任务完成与推进

Claude：顶级任务「项目环境搭建」及其所有子任务已完成。

请选择操作：
- 输入 next 获取下一个待执行的顶级任务
- 输入 status 查看所有任务状态
- 输入 reset 重新初始化所有任务状态

用户：next

Claude：[Claude 调用 next_task.mjs]

下一个任务：后端 API 开发
描述：实现后端 API 接口和数据库设计
优先级：high
前置条件：项目环境搭建 (已完成)

请选择操作...

用户交互命令

命令	说明
`execute`	开始执行当前顶级任务及其所有子任务
`next`	获取下一个待执行的顶级任务
`skip`	跳过当前任务（设为 deferred）
`reset`	重置所有任务状态为 pending
`status`	查看当前任务状态概览

配置验证

当创建任务配置时，Claude 会自动验证配置的正确性：

key 唯一性：检测重复的 key
number 格式：确保子任务 number 与父任务匹配
依赖引用：验证 precondition 中的 key 是否存在
循环依赖：检测任务间的循环依赖

如果验证失败，Claude 会提示具体的错误信息：

Claude：配置验证失败：
- 发现重复的 key "setup-task"（任务 1 和任务 2）
- 任务 3 的 precondition "unknown-task" 不存在

请修正配置后重试。

在 Cursor 中使用

通过 cursor-skills-cli 工具，可以将 task-manager 集成到 Cursor Agent 中使用。

前置准备

将 task-manager 目录放置到项目的 Skills 目录：

# 复制到项目目录
cp -r /path/to/task-manager your-project/.cursor/skills/

安装 cursor-skills-cli：

# 本地链接（需要先获取 cursor-skills-cli 源码）
cd /path/to/cursor-skills-cli && npm link

核心流程

Step 1: 同步 Skill 到 AGENTS.md

cd your-project
cursor-skills sync

在交互式菜单中选择 task-manager，工具会自动将其同步到项目的 AGENTS.md 文件中。

Step 2: 让 Cursor Agent 读取 Skill

在 Cursor 中，Agent 会自动读取 AGENTS.md 获取可用的 Skills 列表。你可以通过以下方式让 Agent 加载 task-manager：

用户：请读取 task-manager skill 的内容

或者 Agent 可以通过命令行读取：

cursor-skills read task-manager

Step 3: 在对话中使用

Skill 加载后，Cursor Agent 会遵循 SKILL.md 中定义的工作流：

初始化阶段：创建/加载任务配置
任务获取：调用 next_task.mjs 获取下一个任务
用户确认：展示任务信息，等待用户指令（execute/skip/reset）
执行阶段：自动处理子任务，完成后停止
循环：返回步骤 2

管理命令速查

命令	说明
`cursor-skills list`	列出所有可用 Skills
`cursor-skills sync`	交互式同步 Skills 到 AGENTS.md
`cursor-skills read <name>`	读取指定 Skill 内容
`cursor-skills remove <name>`	从 AGENTS.md 移除 Skill

实战示例：功能开发流程

以开发一个"用户头像上传"功能为例，展示完整的对话式工作流。

任务配置

{
  "meta": {
    "projectName": "用户头像上传功能"
  },
  "tasks": [
    {
      "number": 1,
      "key": "avatar-analysis",
      "title": "需求分析",
      "priority": "high",
      "subtasks": [
        {
          "number": "1.1",
          "key": "analyze-requirements",
          "title": "分析产品需求",
          "description": "支持的图片格式、大小限制、裁剪功能"
        },
        {
          "number": "1.2",
          "key": "analyze-existing-code",
          "title": "分析现有上传模块",
          "precondition": ["analyze-requirements"]
        }
      ]
    },
    {
      "number": 2,
      "key": "avatar-backend",
      "title": "后端实现",
      "precondition": ["avatar-analysis"],
      "subtasks": [
        {
          "number": "2.1",
          "key": "backend-storage",
          "title": "实现文件存储服务",
          "description": "对接 OSS，实现上传、删除、获取 URL"
        },
        {
          "number": "2.2",
          "key": "backend-api",
          "title": "实现上传 API",
          "description": "POST /api/user/avatar",
          "precondition": ["backend-storage"]
        }
      ]
    },
    {
      "number": 3,
      "key": "avatar-frontend",
      "title": "前端实现",
      "precondition": ["avatar-backend"],
      "subtasks": [
        {
          "number": "3.1",
          "key": "frontend-upload-component",
          "title": "实现上传组件",
          "description": "支持拖拽、预览、裁剪"
        },
        {
          "number": "3.2",
          "key": "frontend-integration",
          "title": "集成到用户设置页",
          "precondition": ["frontend-upload-component"]
        }
      ]
    },
    {
      "number": 4,
      "key": "avatar-testing",
      "title": "测试验收",
      "precondition": ["avatar-frontend"],
      "priority": "medium"
    }
  ]
}

对话式执行过程

用户：skill: task-manager

Claude：已加载 task-manager skill。请问需要什么帮助？
- 创建新的任务配置
- 加载已有的任务配置
- 查看可用模板

用户：加载 ./avatar-tasks.json 并初始化

Claude：已加载任务配置「用户头像上传功能」
任务概览：4 个顶级任务，8 个子任务
所有任务已初始化为 pending 状态。

输入 next 获取第一个待执行任务。

用户：next

Claude：下一个任务：需求分析
描述：分析产品需求和现有代码
优先级：high
子任务：
  1.1 分析产品需求
  1.2 分析现有上传模块

请选择操作：execute / skip / reset

用户：execute

Claude：开始执行「需求分析」

--- 子任务 1.1：分析产品需求 ---
正在分析需求文档...

根据产品需求，头像上传功能需要支持：
- 图片格式：JPG、PNG、WebP
- 大小限制：最大 5MB
- 尺寸要求：裁剪为 200x200 正方形
- 交互方式：支持点击上传和拖拽上传

子任务 1.1 已完成。

--- 子任务 1.2：分析现有上传模块 ---
正在扫描代码库...

发现现有上传模块位于 src/utils/upload.ts，可复用：
- uploadFile() 基础上传方法
- validateFileType() 文件类型校验

需要新增：
- 图片裁剪功能
- 头像专用 API 封装

子任务 1.2 已完成。

---
顶级任务「需求分析」已完成。

请选择操作：next / status / reset

用户：next

Claude：下一个任务：后端实现
描述：实现后端 API 接口
优先级：high
前置条件：需求分析 (已完成)
子任务：
  2.1 实现文件存储服务
  2.2 实现上传 API

请选择操作：execute / skip / reset

用户：execute

Claude：开始执行「后端实现」...
[继续自动执行子任务]

中断与恢复

如果对话中断，可以随时恢复进度：

用户：skill: task-manager

Claude：已加载 task-manager skill。

用户：加载 ./avatar-tasks.json

Claude：已加载任务配置「用户头像上传功能」
当前进度：
- 需求分析：done
- 后端实现：in-progress (子任务 2.1 已完成)
- 前端实现：pending
- 测试验收：pending

检测到未完成的任务，是否继续执行「后端实现」？

用户：继续

Claude：继续执行「后端实现」

--- 子任务 2.2：实现上传 API ---
...

设计亮点与最佳实践

1. 零依赖设计

task-manager 使用纯 Node.js 实现，无需 npm install：

// utils.mjs - 仅使用 Node.js 内置模块
import fs from 'node:fs';
import path from 'node:path';

这带来了：

即开即用，无需安装
跨环境一致性
减少潜在的依赖冲突

2. JSON 输出格式

所有脚本输出统一的 JSON 格式，便于程序化处理：

// 成功
{ "status": "success", "data": { ... } }

// 错误
{ "status": "error", "error": "Error message" }

3. 最佳实践

任务粒度：

顶级任务代表一个完整的功能模块或阶段
子任务代表可在 15-30 分钟内完成的原子操作

key 命名：

使用 kebab-case：user-auth, db-migration
包含模块前缀：auth-login, auth-register

依赖设计：

避免过深的依赖链（建议不超过 3 层）
优先使用顶级任务作为依赖点

状态管理：

及时更新状态，避免状态与实际进度不一致
使用 deferred 而非 cancelled 来跳过暂时不需要的任务

总结

task-manager 通过配置化的任务定义、显式的依赖关系和用户确认制的执行控制，解决了 AI Agent 在复杂项目中的任务管理难题。

它的核心价值在于：

将隐式的"口头约定"转化为显式的"机器契约"
在 AI 自动化与人类控制之间找到平衡点
提供可持久化、可恢复的任务状态
Agent 无关性：适用于 Claude Code、Cursor、Copilot 等任何支持 Shell 命令的 AI Agent

对于前端开发者来说，task-manager 展示了如何用简洁的 Node.js 脚本构建一个实用的工作流编排系统，是 AI 辅助开发实践中值得借鉴的设计模式。

参考文章：

Cursor 中自动加载 Skill 的技术实现解析
用 MCP 驾驭任务流：task-manager-mcp 全自动执行
用 MCP 玩转任务管理：我的 task-manager-mcp 轻量方案