TaskWeaver项目库模式使用指南：深入理解核心概念与API调用-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00743/article/details/148490617

TaskWeaver项目库模式使用指南：深入理解核心概念与API调用

TaskWeaver A code-first agent framework for seamlessly planning and executing data analytics tasks. 项目地址: https://gitcode.com/gh_mirrors/ta/TaskWeaver

一、TaskWeaver库模式概述

TaskWeaver提供了灵活的库模式调用方式，允许开发者将这一强大的任务处理引擎集成到自己的应用程序中。与直接使用交互式界面不同，库模式通过编程接口提供了更精细的控制能力，适合需要深度集成的应用场景。

二、核心API使用详解

2.1 基础集成步骤

集成TaskWeaver到您的项目只需要几个简单的步骤：

from taskweaver.app.app import TaskWeaverApp

# 配置项目目录（包含taskweaver_config.json的目录）
app_dir = "./project/"  
# 创建应用实例
app = TaskWeaverApp(app_dir=app_dir)  
# 获取会话对象
session = app.get_session()  

# 发送用户查询并获取响应
user_query = "请帮我分析这份销售数据"
response_round = session.send_message(user_query)
print(response_round.to_dict())

2.2 关键对象解析

TaskWeaverApp：代表整个TaskWeaver应用实例，是库模式的入口点
Session：表示一次用户会话，维护对话的上下文状态
Round：单轮对话的完整记录，包含请求和响应
Post：对话中的单个消息单元
Attachment：消息的附加内容，如执行计划等

三、对话数据结构深度解析

3.1 Round对象结构

Round对象包含了完整的对话轮次信息，其JSON结构示例如下：

{
    "id": "round-20231201-043134-218a2681",
    "user_query": "hello, what can you do?",
    "state": "finished",
    "post_list": [...]
}

关键字段说明：

id：唯一标识符，包含时间戳和随机字符串
user_query：用户原始输入
state：对话状态（如进行中、已完成等）
post_list：包含所有消息的列表

3.2 Post对象详解

每个Post代表对话中的一个消息单元：

{
    "id": "post-20231201-043141-86a2aaff",
    "message": "I can help you with...",
    "send_from": "Planner",
    "send_to": "User",
    "attachment_list": [...]
}

字段说明：

send_from/send_to：标识消息的发送方和接收方
attachment_list：包含消息的附加信息

3.3 Attachment类型

附件系统是TaskWeaver的重要特性，常见类型包括：

init_plan：初始执行计划
plan：调整后的执行计划
current_plan_step：当前正在执行的步骤

四、高级功能：事件处理机制

对于需要实时监控对话过程的场景，TaskWeaver提供了事件处理机制：

class CustomEventHandler:
    def on_event(self, event_type: str, event_data: dict):
        print(f"收到事件 {event_type}: {event_data}")

# 使用自定义事件处理器
event_handler = CustomEventHandler()
session.send_message(user_query, event_handler=event_handler)

通过实现事件处理器，您可以：