AI Agent数据分析【免费下载链接】TaskWeaverThe first code-first agent framework for seamlessly planning and executing data analytics tasks.项目地址https://gitcode.com/gh_mirrors/ta/TaskWeaver点击查看免费下载Post消息是 TaskWeaver 会话系统中连接各角色Role的最小数据单元无论是用户的提问、Planner 的规划指令还是 CodeInterpreter 的执行结果最终都以 Post 的形式在角色之间传递并被组织进 Round 与 Conversation 供 LLM 提示词构造和历史记忆使用。本篇以 Post 官方概念文档 为骨架结合 post.py 等核心源码从数据结构、附件体系、消息持久性到提示词中的呈现方式完整剖析 Post 的设计原理与实战用法。一、Post 在 TaskWeaver 会话数据模型中的定位TaskWeaver 的记忆体系采用“会话Conversation→ 轮次Round→ 消息Post”三层递进结构Post 是最底层的消息载体Conversation一次与用户的完整交互包含若干 Round定义见 conversation.pyRound一次对话回合的基本单元是 Post 的有序集合同时记录user_query与statefinished/failed/created定义见 round.pyPost单条消息承载角色间的文本内容与非文本附件。用源码中的类注释可以概括 Post 的语义A post is the message used to communicate between two roles.Post 是用于在两个角色之间通信的消息。它应当始终携带一个文本message作为字符串消息而其他数据格式则应放入附件Attachment中发送角色可以是 User、Planner 或其他扩展角色。从数据关系看Post 是唯一直接面向角色Role的数据对象——角色的reply方法返回的就是一个 Post见 role.py 中def reply(self, memory: Memory, **kwargs) - Post因此理解 Post 是理解整个 TaskWeaver 消息流转的起点。二、Post 数据结构与字段详解Post 在 post.py 中定义为dataclass包含五个字段dataclass class Post: id: str # Post 的唯一 ID send_from: RoleName # 发送方角色 send_to: RoleName # 接收方角色 message: str # 文本消息内容 attachment_list: List[Attachment] # 附件列表各字段含义如下字段类型说明idstrPost 的唯一标识形如post-xxx由create_id()生成send_fromRoleName发送方角色名RoleName在 type_vars.py 中定义为str类型别名send_toRoleName接收方角色名messagestr文本消息始终存在允许为空字符串attachment_listList[Attachment]附件列表承载文本之外的结构化数据关于send_from与send_to官方文档特别指出在某些场景下两者可以相同用于表示角色的自我通信self-communication。例如 Planner 在自我思考、整理计划时会向自己发送 Post这是 TaskWeaver 规划流程中的常见用法。2.1 消息的创建Post.createpost.py 提供了静态工厂方法Post.createstaticmethod def create( message: Optional[str], send_from: RoleName, send_to: RoleName Unknown, attachment_list: Optional[List[Attachment]] None, ) - Post: return Post( idpost- create_id(), messagemessage is not None and message or , send_fromsend_from, send_tosend_to, attachment_listattachment_list if attachment_list is not None else [], )要点message为None时会被规范化为空字符串attachment_list缺省时为空列表send_to默认值为Unknown方便在不确定接收者时先创建再填充。2.2 序列化to_dict / from_dictPost 需要持久化到 YAML 文件中会话记录、经验沉淀因此实现了双向转换to_dict()将 Post 转为字典附件列表通过每个Attachment.to_dict()递归序列化from_dict()从字典还原 Post并重新生成新的id使用secrets.token_hex(6)保证从文件加载后的对象与原始对象区分开。2.3 附件操作接口Post 提供了三个附件操作接口post.pydef add_attachment(self, attachment: Attachment) - None: ... # 追加附件 def get_attachment(self, type: AttachmentType) - List[Attachment]: ... # 按类型取出全部附件 def del_attachment(self, type_list: List[AttachmentType]) - None: ... # 按类型列表批量删除附件其中get_attachment是角色消费附件的主要入口例如 Planner 通过post.get_attachment(typeAttachmentType.plan)[0]读取计划内容见 planner.pyCodeInterpreter 通过get_attachment(typeAttachmentType.reply_content)[0].content提取生成的代码。三、附件Attachment体系文本之外的载体Post 的attachment_list存放的是 Attachment 对象。官方文档强调附件用于存储文本消息之外的各种数据例如代码片段或工件artifact文件路径附件可能只被发送方角色使用也可能被接收方角色使用。Attachment 定义在 attachment.py核心字段为id、type、content和可选的extra。其中type是AttachmentType枚举完整枚举值可以从源码中看到该枚举即 TaskWeaver 各角色结构化输出的协议class AttachmentType(Enum): # Planner 相关 init_plan init_plan # 初始计划 plan plan # 计划 current_plan_step current_plan_step # 当前计划步骤 plan_reasoning plan_reasoning # 计划推理 stop stop # 停止信号 # CodeInterpreter 生成代码 thought thought # 思考过程 reply_type reply_type # 回复类型 reply_content reply_content # 生成的代码/回复内容 # 代码验证 verification verification # 代码执行 code_error code_error execution_status execution_status execution_result execution_result # 执行结果 artifact_paths artifact_paths # 工件文件路径 # 代码修订 revise_message revise_message # 函数调用 function function # WebExplorer web_exploring_plan web_exploring_plan web_exploring_screenshot web_exploring_screenshot web_exploring_link web_exploring_link # 其他 invalid_response invalid_response text text shared_memory_entry shared_memory_entry # 共享记忆条目 image_url image_url # 视觉输入图片可见附件类型覆盖了 Planner 计划、代码生成与验证、执行结果、函数调用、网页探索、视觉输入等全部角色间的结构化数据。附件通过Attachment.create(type, content, id, extra)创建反序列化时from_dict源码会显式拒绝python、sample、text这类已废弃的类型名并抛出ValueError提示用户参考官方博客修复旧数据。四、消息的持久性控制Temporal 分隔符机制这是 Post 设计中最重要的机制之一。官方文档指出通常情况下message会作为历史对话轮次出现在提示词中但有时消息过长只应在当前轮次保留下一轮起便从提示词中删除以避免提示词膨胀。典型例子是CodeInterpreter 生成的长执行结果——它只在当前轮次有意义。TaskWeaver 为此提供了时间性标注temporal annotation方式将消息或消息的一部分标记为仅当前轮次保留message PromptUtil.wrap_text_with_delimiter(message, delimiterPromptUtil.DELIMITER_TEMPORAL)4.1 底层实现PromptUtilPromptUtil位于 prompt_util.py其核心定义如下class PromptUtil: DELIMITER_TEMPORAL: Tuple[str, str] ({{DELIMITER_START_TEMPORAL}}, {{DELIMITER_END_TEMPORAL}}) staticmethod def wrap_text_with_delimiter(text, delimiter: Tuple[str, str]) - str: return f{delimiter[0]}{text}{delimiter[1]}被标注的内容会被包裹在一对特殊标记{{DELIMITER_START_TEMPORAL}} ... {{DELIMITER_END_TEMPORAL}}之间。get_all_delimiters()通过反射收集所有以DELIMITER_开头的分隔符对为后续清理做准备。4.2 提示词构造中的清理规则Memory.get_role_roundsPost 的当前轮次保留语义在 memory.py 的get_role_rounds中真正落地。该方法为某个角色提取其参与过的所有轮次以构造提示词并执行如下清理# 对除最后一轮之外的所有轮次删除被 temporal 标记包裹的内容 for round in rounds_from_role[:-1]: for post in round.post_list: post.message PromptUtil.remove_parts( post.message, delimiterPromptUtil.DELIMITER_TEMPORAL, ) # 对最后一轮仅剥离分隔符标记本身保留完整内容 for post in rounds_from_role[-1].post_list: post.message PromptUtil.remove_all_delimiters(post.message)remove_parts会循环查找起始标记与结束标记把二者之间的整段内容连同标记一起从文本中删除找不到配对标记时安全退出remove_all_delimiters则只移除所有分隔符标记而保留文本。这一设计保证了历史轮次中被 temporal 标注的冗长内容如长执行结果不再进入提示词控制上下文长度当前轮次中该内容仍完整可见供角色基于最新结果继续推理。五、Post 与提示词、结构化输出的双向转换Post 不仅在记忆层存储还承担着与 LLM 结构化输出互转的职责核心实现在 translator.py 的PostTranslatorraw_text_to_post解析 LLM 输出的流式 JSON{response: {message: ..., send_to: ..., thought: ..., plan: ...}}将各键值分别映射到 Post 的message、send_to及各类 Attachment通过post_proxy.update_attachment(...)边解析边组装post_to_raw_text反向将 Post 序列化为 LLM 输入格式的结构化文本附件按类型聚合后与send_to、message一起包装进{response: ...}。这说明 Post 的字段集合文本 结构化附件正是 TaskWeaver 与 LLM 交互的线协议角色输出的每一个结构化字段最终都会落到某个 Post 的附件中再作为下一角色的提示词上下文。此外会话执行过程中session.py 会在 Post 进出时记录in.attachments/out.attachments等 trace 属性便于链路追踪与观测详见 tracing.py。六、实战示例一个完整轮次中的 Post 流转结合仓库自带的示例 example-planner.yaml可以直观看到 Post 在真实会话中的形态该示例由 Conversation 加载rounds[0].post_list即为该轮次的所有 Postenabled: True rounds: - user_query: count the rows of /home/data.csv state: created post_list: - message: count the rows of /home/data.csv send_from: User send_to: Planner attachment_list: - message: Please load the data file /home/data.csv and count the rows of the loaded data send_from: Planner send_to: CodeInterpreter attachment_list: - type: init_plan content: |- 1. load the data file 2. count the rows of the loaded data narrow depend on 1 3. report the result to the user wide depend on 2 - type: plan content: |- 1. instruct CodeInterpreter to load the data file and count the rows of the loaded data 2. report the result to the user - type: current_plan_step content: 1. instruct CodeInterpreter to load the data file and count the rows of the loaded data - message: Load the data file /home/data.csv successfully and there are 100 rows in the data file send_from: CodeInterpreter send_to: Planner attachment_list: - message: The data file /home/data.csv is loaded and there are 100 rows in the data file send_from: Planner send_to: User attachment_list: - type: init_plan content: |- 1. load the data file 2. count the rows of the loaded data narrow depend on 1 3. report the result to the user wide depend on 2 - type: plan content: |- 1. instruct CodeInterpreter to load the data file and count the rows of the loaded data 2. report the result to the user - type: current_plan_step content: 2. report the result to the user该示例完整呈现了 Post 的几个典型特征消息链User → Planner → CodeInterpreter → Planner → User的 Post 序列构成一轮完整对话每个 Post 都带send_from与send_to文本为主、附件为辅Planner 发送给 CodeInterpreter 的 Post 在message中给出指令文本同时通过init_plan、plan、current_plan_step三类附件携带结构化计划附件更新随轮次推进最后一跳 Planner 回复用户时current_plan_step已推进到第 2 步反映规划状态的变化无需附件的 PostUser 提问、CodeInterpreter 汇报结果等 Post 的attachment_list为空列表。七、结语Post 是 TaskWeaver 消息体系的基石它以始终携带文本消息 可选结构化附件的简洁设计统一了 User、Planner、CodeInterpreter 以及 WebExplorer、DocumentRetriever 等扩展角色之间的通信协议配合 Round 与 Conversation 的组织层级、temporal 分隔符的上下文裁剪机制、以及PostTranslator与 LLM 结构化输出的双向转换构成了整套会话记忆与提示词构造的闭环。无论是阅读源码、编写自定义角色还是调试多角色协作流程从 Post 入手都是最快的切入路径。赞分享AI Agent数据分析【免费下载链接】TaskWeaverThe first code-first agent framework for seamlessly planning and executing data analytics tasks.项目地址https://gitcode.com/gh_mirrors/ta/TaskWeaver点击查看免费下载相关推荐Security-101 7.1 数据安全知识核心概念解析数据分类、数据生命周期管理与 DLPSecurity 101 7.1 数据安全知识核心概念解析数据分类、数据生命周期管理与 DLP 本文基于 Security 101Cybersecurity网络安全教程文档Security-101 数据安全核心概念数据分类、生命周期管理与 DLP 实战指南Security 101 数据安全核心概念数据分类、生命周期管理与 DLP 实战指南 本文是 Security 101面向初学者的网络安全课程第 7 章《网络安全教程文档DuiLib_Ultimate核心组件解析从按钮到列表的全面指南DuiLib_Ultimate核心组件解析从按钮到列表的全面指南 DuiLib_Ultimate是一款功能强大的UI开发框架提供了丰富的核心组件帮助开发者上一篇XHS-Downloader终极问题排查指南3分钟解决90%的使用难题下一篇小红书资源下载神器3步解锁无水印高清内容创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考