PlanTask

💡 本中间件在 v0.8.0 版本引入。包路径：github.com/cloudwego/eino/adk/middlewares/plantask

概述

plantask 是一个任务管理中间件，通过 BeforeAgent 钩子向 Agent 注入四个工具，使其具备结构化任务规划能力：

TaskCreate

TaskGet

TaskUpdate

TaskList

核心用途：将复杂请求拆解为可跟踪的小任务，管理任务间依赖关系，让用户看到执行进度。

架构

┌─────────────────────────────────────────────────────────────────────────┐
│                              Agent                                      │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │  BeforeAgent: 注入任务工具 (带 sync.Mutex 保证并发安全)             │  │
│  │    - TaskCreate                                                    │  │
│  │    - TaskGet                                                       │  │
│  │    - TaskUpdate                                                    │  │
│  │    - TaskList                                                      │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                             Backend                                     │
│                                                                         │
│  存储结构:                                                               │
│    baseDir/                                                             │
│    ├── .highwatermark    # 已分配的最大 ID（纯数字文本）                  │
│    ├── 1.json            # 任务 #1                                      │
│    ├── 2.json            # 任务 #2                                      │
│    └── ...                                                              │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

API

构造函数

// 泛型版本，支持 *schema.Message 和 *schema.AgenticMessage
func NewTyped[M adk.MessageType](ctx context.Context, config *Config) (adk.TypedChatModelAgentMiddleware[M], error)

// 非泛型版本，等价于 NewTyped[*schema.Message]
func New(ctx context.Context, config *Config) (adk.ChatModelAgentMiddleware, error)

Config

type Config struct {
    Backend Backend  // 存储后端，必填
    BaseDir string   // 任务文件存储目录，必填
}

💡 Backend 应该是 session 维度隔离的——不同会话对应不同的 Backend 实例（即不同的任务列表）。

Backend 接口

Backend 定义在 plantask 包内，是 filesystem.Backend 的精简子集，仅保留任务存储所需的四个方法：

type Backend interface {
    LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
    Read(ctx context.Context, req *ReadRequest) (*filesystem.FileContent, error)
    Write(ctx context.Context, req *WriteRequest) error
    Delete(ctx context.Context, req *DeleteRequest) error
}

其中类型别名关系：

type FileInfo = filesystem.FileInfo        // Path, IsDir, Size, ModifiedAt
type LsInfoRequest = filesystem.LsInfoRequest  // Path string
type ReadRequest = filesystem.ReadRequest       // FilePath, Offset, Limit
type WriteRequest = filesystem.WriteRequest     // FilePath, Content string

// DeleteRequest 是 plantask 包自定义的（filesystem 包无此类型）
type DeleteRequest struct {
    FilePath string
}

💡 注意 Read 返回 *filesystem.FileContent（含 Content string 字段），不是裸 string。导入路径为 github.com/cloudwego/eino/adk/filesystem。

任务结构

type task struct {
    ID          string         `json:"id"`
    Subject     string         `json:"subject"`
    Description string         `json:"description"`
    Status      string         `json:"status"`
    Blocks      []string       `json:"blocks"`
    BlockedBy   []string       `json:"blockedBy"`
    ActiveForm  string         `json:"activeForm,omitempty"`
    Owner       string         `json:"owner,omitempty"`
    Metadata    map[string]any `json:"metadata,omitempty"`
}

状态

pending

in_progress

completed

deleted

状态流转：pending → in_progress → completed；任何状态均可直接设为 deleted。

工具参数

TaskCreate

工具名常量：TaskCreateToolName = "TaskCreate"

subject

description

activeForm

metadata

创建后任务 ID 自动递增（基于 .highwatermark 文件），状态初始为 pending。

TaskGet

工具名常量：TaskGetToolName = "TaskGet"

taskId

返回任务的完整信息：subject、description、status、blocks、blockedBy、owner。

TaskUpdate

工具名常量：TaskUpdateToolName = "TaskUpdate"

taskId

subject

description

activeForm

status

pending

in_progress

completed

deleted

addBlocks

addBlockedBy

owner

metadata

关键行为：

• status: "deleted" 会物理删除任务文件，并从所有其他任务的 blocks/blockedBy 中移除该 ID
• 添加依赖时会进行循环依赖检测，若形成环则报错
• 当所有任务均为 completed 时，自动删除全部任务文件（清理机制）

TaskList

工具名常量：TaskListToolName = "TaskList"

无参数。返回所有任务的摘要列表（按 ID 排序），每条格式为：

#ID [status] subject [owner: xxx] [blocked by #x, #y]

使用示例

ctx := context.Background()

// Backend 应该是 session 维度隔离的
middleware, err := plantask.New(ctx, &plantask.Config{
    Backend: myBackend,
    BaseDir: "/tasks",
})
if err != nil {
    return err
}

agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Model:    myModel,
    Handlers: []adk.ChatModelAgentMiddleware{middleware},
})

典型流程

1. 收到复杂任务
       │
       ▼
2. TaskCreate 创建多个子任务
   - #1: 分析需求
   - #2: 实现代码
   - #3: 编写测试
       │
       ▼
3. TaskUpdate 设置依赖
   - #2 addBlockedBy: ["1"]
   - #3 addBlockedBy: ["2"]
       │
       ▼
4. TaskList 查看可用任务
       │
       ▼
5. TaskUpdate #1 → in_progress
       │
       ▼
6. 完成后 TaskUpdate #1 → completed
       │
       ▼
7. 循环 4-6 直到全部完成
       │
       ▼
8. 全部 completed → 自动清理所有文件

依赖管理

• blocks: “我完成了，这些任务才能开始”
• blockedBy: “这些任务完成了，我才能开始”

依赖写入是双向的：对 Task A 执行 addBlocks: ["2"]，会同时在 Task #2 的 blockedBy 中写入 A 的 ID。

Task #1 (blocks: ["2"])  ────►  Task #2 (blockedBy: ["1"])

#1 完成后 #2 才能开始

循环依赖检测通过 DFS 可达性判断实现：

#1 blocks #2
#2 blocks #1  ← 报错：would create a cyclic dependency

实现细节

.highwatermark

sync.Mutex

{id}.json

sonic

^\d+$

多语言支持

工具的 description 支持中英文双语，通过全局设置切换：

// 使用中文 description
adk.SetLanguage(adk.LanguageChinese)

// 使用英文 description（默认）
adk.SetLanguage(adk.LanguageEnglish)

此设置影响所有 ADK 内置的 prompt 和工具 description。