Cherry Studio Agent Session 协作指南跨 Session 发现、委派与投递恢复【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本指南围绕 Cherry Studio 内置工具集mcp__cherry-tools__*中的五个 Session 工具session_list、session_search、session_create、session_send、session_deliveries展开讲解 Agent 如何发现其他 Session、将有界任务委派给另一个 Session、以及如何审计和恢复持久化的请求与结果。读完本文你将掌握跨 Agent Session 协作的标准流程先解析不可变 ID、再按意图选择建会或投递、理解异步结果投递模型并能在审批被拒、投递失败等场景下正确恢复。本文以 sessions.md 为骨架结合 cherryAutonomyTools.ts 中的工具注册与实现、agentSessionDelivery.ts 中的投递数据模型以及 cherry-tool-guide 路由表 中的全局规则给出既有实操价值又有源码依据的完整讲解。一、五个 Session 工具的角色总览在 Cherry Studio 中Agent Session 工具通过mcp__cherry-tools__前缀注入到 Agent 会话见 SKILL.md 工具注入说明。五个工具分别承担发现、建会、投递与审计职责工具职责典型时机session_list确定性枚举当前可见的 Session浏览最近 Session、按 Agent 筛选、用户按名字提及某个 Sessionsession_search基于词汇证据对 Session 排序检索只记得任务内容/报错文本需要按证据定位 Sessionsession_create为当前 Agent 新建 Session 并提交首条消息需要一个独立时间线的较大型任务session_send向已有 Session 投递消息可选异步回执委派有界任务并把结果带回session_deliveries审计/恢复持久化的请求与结果用户询问投递状态或需要恢复失败投递工具名常量定义在 agentSessionDelivery.ts五个工具统一注册在 cherryAutonomyTools.ts 的 AUTONOMY_TOOLS 数组 中由CherryAutonomyTools类统一分发call()方法按工具名路由到各自的私有实现。二、先解析不可变 ID再谈投递Session 名称和 Agent 名称只是展示标签display labels不是寻址地址。投递前必须先用只读工具解析出目标 Session 的不可变sessionId。这一点在源码层面有严格印证session_send的target_session_id参数描述明确写着由session_list返回或投递发送方给出cherryAutonomyTools.ts杜绝用名字猜测 ID。session_list确定性枚举session_list的参数与语义工具 Schemaagent_id可选按 Agent ID 过滤cursor可选上一页返回的不透明游标用于翻页limit可选最大返回条数默认 50上限 100。实现上listSessions通过agentSessionService.listAddressableByCursor分页取数limit 会被钳制到[1, 100]。返回结构为{ sessions, nextCursor }每个 Session 条目包含agentId、sessionId等寻址信息并带有isCurrent标记值为 true 表示该条目就是当前发起调用的 Session。session_search基于证据的排序检索session_search的参数工具 Schemaquery必填自然语言或关键词查询最大 4096 字符agent_id可选按 Agent 过滤在排序与截断之前应用limit可选最大返回条数默认 20上限 100。这不是 embedding 语义检索而是 trigram/BM25 词法检索——建议从任务中取聚焦的关键词、标识符、报错文本或精确短语作为 query。返回结果包含两个证据通道searchSessions 实现matches消息证据每条含messageId、snippet 摘要、createdAt时间戳metadataMatches命中 Session 的name或description字段的元数据证据。实现流程值得注意先通过agentSessionMessageService.searchRanked拿消息级匹配并聚合成 Session 级结果L536-L548再通过agentSessionService.searchWithMetadataEvidence补元数据命中L549-L571。两个通道的结果会按sessionId合并到同一个 Session 条目里。三条关键解读matches为空不代表结果无效——只要metadataMatches存在该命中就是可信的limit统计的是最终去重后的 Session 数而不是原始消息行数——一个 Session 的多条消息命中只算一个 Session可选的agent_id过滤发生在排序与截断之前。三、create 还是 send按任务边界选择session_create为新任务开启独立时间线session_create的参数工具 Schemamessage必填新 Session 的首条消息title可选Session 标题最大 255 字符。语义要点为当前 Agent 新建 Session并提交该 Session 的第一次 completion 请求适合需要独立时间线的较大型任务例如一个完整的功能实现新 Session继承当前 Agent 的模型与工作区策略——不要试图通过参数提供模型调用立即返回新 IDagentId、sessionId、requestId、delivery工作异步继续运行见 createSession 实现其内部调用AgentSessionDeliveryService.acceptWithNewSession。session_send向既有 Session 投递session_send的参数工具 Schematarget_session_id必填目标sessionId只能来自session_list/session_search/ 投递发送方绝不从名字猜message必填发给目标 Agent 的消息reply可选枚举none/completion默认none投递契约。投递契约按意图选择单向更新——使用reply: none只传递信息不需要结果回执委派任务且需要结果——使用reply: completion每次投递拥有独立的 FIFO 轮次其终态输出可归属到该次请求调用立即返回requestId运行时会异步把一份持久化、冻结的结果投送回调用方 Session。不要保持工具调用打开也不要轮询等待答案。reply策略枚举在 agentSessionDelivery.ts 定义为[none, completion]。sendSessionMessage的完整实现cherryAutonomyTools.ts通过AgentSessionDeliveryService.accept受理返回{ ok, requestId, status: accepted, delivery }。交互轮次与逐次审批的硬约束所有五个 Session 工具都要求交互式用户轮次。无头headless、定时、IM 频道、投递触发的轮次不能发现、查看、创建或消息 Session。源码约束位于 assertSessionToolsAuthorized当interaction.currentTurn headless或interaction.userResponse unavailable时抛出SESSION_TOOL_FORBIDDEN路由错误。此外assertCurrentSessionIdentityL482-L487会校验当前运行时仍拥有该 Session。在交互轮次中session_send与session_create额外要求逐次在线审批因为二者都会启动另一个 Agent Session 轮次SKILL.md 审批规则 将二者列为审批门控工具。若审批被拒立即停止——Cherry Studio 不提供无人值守的多跳委派。不要在审批被拒后用 shell 进程、定时任务或重复调用去模拟同样的效果SKILL.md 全局规则。四、用 session_deliveries 审计与恢复而非忙等session_deliveries用于审计或恢复持久化的请求与结果不要把它当作忙等轮询循环。参数工具 Schemadirection可选枚举incoming/outgoing默认incoming选择入向或出向投递request_id可选提供请求 ID 时无论方向都返回该请求及其关联结果status可选枚举accepted/delivering/consumed/failed按状态收窄limit可选最大返回条数默认 20上限 100。实现listSessionDeliveries对status与direction做枚举校验随后把每条携带delivery的消息折叠为{ id, envelope, content }其中content是该消息的文本部分拼接。投递生命周期状态枚举定义在 agentSessionDelivery.tsaccepted → delivering → consumed failed终态路由/执行失败accepted请求已被受理等待投递delivering正在投递/执行中consumed已消费完成failed终态表示路由或执行失败。每次reply: completion投递的终态结果都与请求 ID 关联。信封结构AgentSessionDeliveryEnvelopeSchema记录了version: 1、发送方/接收方身份、双方快照、replyPolicy、sourceMessageId、outcomesuccess/failed/interrupted见 L27、errorcodemessage与statusAt时间戳。持久性边界已受理的意图与终态结果在普通重启后仍然有效accepted/delivering被列为可恢复状态见 AGENT_SESSION_DELIVERY_RECOVERABLE_STATUSES。但需要明确外部工具执行期间发生崩溃无法保证任意副作用恰好一次exactly-once——对于恰好一次语义的诉求应如实向用户说明其限制。五、恢复指南常见失败场景的处置原文档给出四类恢复路径结合源码可以进一步细化1. 没有合适的目标 Session细化session_search的 query换更聚焦的关键词、标识符或报错文本按agent_id过滤收窄若意图边界本就是新开一条同 Agent 时间线直接用session_create。2. 只有元数据命中查看metadataMatches不要因为它没有matches就丢弃——Session 的name/description字段命中同样是有效证据源码层面两个通道独立聚合见 searchSessions。3. 审批被拒或不可用如实报告委派未执行禁止用 shell 进程、定时任务或重复调用模拟该效果——审批门控是安全边界的一部分绕过它就绕过了用户授权。4. 投递失败failed用session_deliveries按request_id查看关联请求向用户报告终态错误先询问用户再创建新请求——API 没有调用方幂等键重试是独立的新工作直接重发可能产生重复副作用若投递停滞在accepted/delivering且用户要求恢复可先审计确认状态再决策。六、端到端示例委派并异步取回结果以文档示例Have the implementation Session finish the auth fix and bring the result back here.让实现 Session 完成认证修复并把结果带回为例完整流程如下搜索定位调用mcp__cherry-tools__session_searchquery 使用聚焦的认证相关标识符如报错中的 token/error 文本得到候选 Session 及matches/metadataMatches证据确定目标从消息或元数据证据中选出预期的sessionId投递委派调用mcp__cherry-tools__session_send参数为target_session_idmessagereply: completion并接受弹出的逐次在线审批调用立即返回requestId继续其他工作不要保持工具调用打开也不要轮询运行时会异步把持久化、冻结的终态结果投送回调用方 Session按需审计仅当用户询问投递状态或需要恢复时才使用session_deliveries按request_id查看关联结果。七、最佳实践小结先解析、后投递一切寻址都基于session_list/session_search返回的不可变sessionId名字只是展示标签按边界选择工具独立时间线的大任务用session_create对既有 Session 委派用session_send需要结果时选reply: completion异步结果、按需审计completion结果是异步送达的session_deliveries是审计/恢复工具而非忙等循环尊重审批边界session_create/session_send每次都需要在线审批被拒即停不绕路模拟诚实报告限制普通重启不丢已受理投递但外部工具执行期间崩溃无法保证副作用恰好一次也不存在调用方幂等键重试需先询问用户。相关参考sessions.md 原文档、cherry-tool-guide 全局规则与路由表、工具实现 cherryAutonomyTools.ts、投递数据模型 agentSessionDelivery.ts以及同属该技能的其他领域参考autonomy.md、memory.md、skills.md。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio Agent Session 协作指南：跨 Session 发现、委派与投递恢复
Cherry Studio Agent Session 协作指南跨 Session 发现、委派与投递恢复【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本指南围绕 Cherry Studio 内置工具集mcp__cherry-tools__*中的五个 Session 工具session_list、session_search、session_create、session_send、session_deliveries展开讲解 Agent 如何发现其他 Session、将有界任务委派给另一个 Session、以及如何审计和恢复持久化的请求与结果。读完本文你将掌握跨 Agent Session 协作的标准流程先解析不可变 ID、再按意图选择建会或投递、理解异步结果投递模型并能在审批被拒、投递失败等场景下正确恢复。本文以 sessions.md 为骨架结合 cherryAutonomyTools.ts 中的工具注册与实现、agentSessionDelivery.ts 中的投递数据模型以及 cherry-tool-guide 路由表 中的全局规则给出既有实操价值又有源码依据的完整讲解。一、五个 Session 工具的角色总览在 Cherry Studio 中Agent Session 工具通过mcp__cherry-tools__前缀注入到 Agent 会话见 SKILL.md 工具注入说明。五个工具分别承担发现、建会、投递与审计职责工具职责典型时机session_list确定性枚举当前可见的 Session浏览最近 Session、按 Agent 筛选、用户按名字提及某个 Sessionsession_search基于词汇证据对 Session 排序检索只记得任务内容/报错文本需要按证据定位 Sessionsession_create为当前 Agent 新建 Session 并提交首条消息需要一个独立时间线的较大型任务session_send向已有 Session 投递消息可选异步回执委派有界任务并把结果带回session_deliveries审计/恢复持久化的请求与结果用户询问投递状态或需要恢复失败投递工具名常量定义在 agentSessionDelivery.ts五个工具统一注册在 cherryAutonomyTools.ts 的 AUTONOMY_TOOLS 数组 中由CherryAutonomyTools类统一分发call()方法按工具名路由到各自的私有实现。二、先解析不可变 ID再谈投递Session 名称和 Agent 名称只是展示标签display labels不是寻址地址。投递前必须先用只读工具解析出目标 Session 的不可变sessionId。这一点在源码层面有严格印证session_send的target_session_id参数描述明确写着由session_list返回或投递发送方给出cherryAutonomyTools.ts杜绝用名字猜测 ID。session_list确定性枚举session_list的参数与语义工具 Schemaagent_id可选按 Agent ID 过滤cursor可选上一页返回的不透明游标用于翻页limit可选最大返回条数默认 50上限 100。实现上listSessions通过agentSessionService.listAddressableByCursor分页取数limit 会被钳制到[1, 100]。返回结构为{ sessions, nextCursor }每个 Session 条目包含agentId、sessionId等寻址信息并带有isCurrent标记值为 true 表示该条目就是当前发起调用的 Session。session_search基于证据的排序检索session_search的参数工具 Schemaquery必填自然语言或关键词查询最大 4096 字符agent_id可选按 Agent 过滤在排序与截断之前应用limit可选最大返回条数默认 20上限 100。这不是 embedding 语义检索而是 trigram/BM25 词法检索——建议从任务中取聚焦的关键词、标识符、报错文本或精确短语作为 query。返回结果包含两个证据通道searchSessions 实现matches消息证据每条含messageId、snippet 摘要、createdAt时间戳metadataMatches命中 Session 的name或description字段的元数据证据。实现流程值得注意先通过agentSessionMessageService.searchRanked拿消息级匹配并聚合成 Session 级结果L536-L548再通过agentSessionService.searchWithMetadataEvidence补元数据命中L549-L571。两个通道的结果会按sessionId合并到同一个 Session 条目里。三条关键解读matches为空不代表结果无效——只要metadataMatches存在该命中就是可信的limit统计的是最终去重后的 Session 数而不是原始消息行数——一个 Session 的多条消息命中只算一个 Session可选的agent_id过滤发生在排序与截断之前。三、create 还是 send按任务边界选择session_create为新任务开启独立时间线session_create的参数工具 Schemamessage必填新 Session 的首条消息title可选Session 标题最大 255 字符。语义要点为当前 Agent 新建 Session并提交该 Session 的第一次 completion 请求适合需要独立时间线的较大型任务例如一个完整的功能实现新 Session继承当前 Agent 的模型与工作区策略——不要试图通过参数提供模型调用立即返回新 IDagentId、sessionId、requestId、delivery工作异步继续运行见 createSession 实现其内部调用AgentSessionDeliveryService.acceptWithNewSession。session_send向既有 Session 投递session_send的参数工具 Schematarget_session_id必填目标sessionId只能来自session_list/session_search/ 投递发送方绝不从名字猜message必填发给目标 Agent 的消息reply可选枚举none/completion默认none投递契约。投递契约按意图选择单向更新——使用reply: none只传递信息不需要结果回执委派任务且需要结果——使用reply: completion每次投递拥有独立的 FIFO 轮次其终态输出可归属到该次请求调用立即返回requestId运行时会异步把一份持久化、冻结的结果投送回调用方 Session。不要保持工具调用打开也不要轮询等待答案。reply策略枚举在 agentSessionDelivery.ts 定义为[none, completion]。sendSessionMessage的完整实现cherryAutonomyTools.ts通过AgentSessionDeliveryService.accept受理返回{ ok, requestId, status: accepted, delivery }。交互轮次与逐次审批的硬约束所有五个 Session 工具都要求交互式用户轮次。无头headless、定时、IM 频道、投递触发的轮次不能发现、查看、创建或消息 Session。源码约束位于 assertSessionToolsAuthorized当interaction.currentTurn headless或interaction.userResponse unavailable时抛出SESSION_TOOL_FORBIDDEN路由错误。此外assertCurrentSessionIdentityL482-L487会校验当前运行时仍拥有该 Session。在交互轮次中session_send与session_create额外要求逐次在线审批因为二者都会启动另一个 Agent Session 轮次SKILL.md 审批规则 将二者列为审批门控工具。若审批被拒立即停止——Cherry Studio 不提供无人值守的多跳委派。不要在审批被拒后用 shell 进程、定时任务或重复调用去模拟同样的效果SKILL.md 全局规则。四、用 session_deliveries 审计与恢复而非忙等session_deliveries用于审计或恢复持久化的请求与结果不要把它当作忙等轮询循环。参数工具 Schemadirection可选枚举incoming/outgoing默认incoming选择入向或出向投递request_id可选提供请求 ID 时无论方向都返回该请求及其关联结果status可选枚举accepted/delivering/consumed/failed按状态收窄limit可选最大返回条数默认 20上限 100。实现listSessionDeliveries对status与direction做枚举校验随后把每条携带delivery的消息折叠为{ id, envelope, content }其中content是该消息的文本部分拼接。投递生命周期状态枚举定义在 agentSessionDelivery.tsaccepted → delivering → consumed failed终态路由/执行失败accepted请求已被受理等待投递delivering正在投递/执行中consumed已消费完成failed终态表示路由或执行失败。每次reply: completion投递的终态结果都与请求 ID 关联。信封结构AgentSessionDeliveryEnvelopeSchema记录了version: 1、发送方/接收方身份、双方快照、replyPolicy、sourceMessageId、outcomesuccess/failed/interrupted见 L27、errorcodemessage与statusAt时间戳。持久性边界已受理的意图与终态结果在普通重启后仍然有效accepted/delivering被列为可恢复状态见 AGENT_SESSION_DELIVERY_RECOVERABLE_STATUSES。但需要明确外部工具执行期间发生崩溃无法保证任意副作用恰好一次exactly-once——对于恰好一次语义的诉求应如实向用户说明其限制。五、恢复指南常见失败场景的处置原文档给出四类恢复路径结合源码可以进一步细化1. 没有合适的目标 Session细化session_search的 query换更聚焦的关键词、标识符或报错文本按agent_id过滤收窄若意图边界本就是新开一条同 Agent 时间线直接用session_create。2. 只有元数据命中查看metadataMatches不要因为它没有matches就丢弃——Session 的name/description字段命中同样是有效证据源码层面两个通道独立聚合见 searchSessions。3. 审批被拒或不可用如实报告委派未执行禁止用 shell 进程、定时任务或重复调用模拟该效果——审批门控是安全边界的一部分绕过它就绕过了用户授权。4. 投递失败failed用session_deliveries按request_id查看关联请求向用户报告终态错误先询问用户再创建新请求——API 没有调用方幂等键重试是独立的新工作直接重发可能产生重复副作用若投递停滞在accepted/delivering且用户要求恢复可先审计确认状态再决策。六、端到端示例委派并异步取回结果以文档示例Have the implementation Session finish the auth fix and bring the result back here.让实现 Session 完成认证修复并把结果带回为例完整流程如下搜索定位调用mcp__cherry-tools__session_searchquery 使用聚焦的认证相关标识符如报错中的 token/error 文本得到候选 Session 及matches/metadataMatches证据确定目标从消息或元数据证据中选出预期的sessionId投递委派调用mcp__cherry-tools__session_send参数为target_session_idmessagereply: completion并接受弹出的逐次在线审批调用立即返回requestId继续其他工作不要保持工具调用打开也不要轮询运行时会异步把持久化、冻结的终态结果投送回调用方 Session按需审计仅当用户询问投递状态或需要恢复时才使用session_deliveries按request_id查看关联结果。七、最佳实践小结先解析、后投递一切寻址都基于session_list/session_search返回的不可变sessionId名字只是展示标签按边界选择工具独立时间线的大任务用session_create对既有 Session 委派用session_send需要结果时选reply: completion异步结果、按需审计completion结果是异步送达的session_deliveries是审计/恢复工具而非忙等循环尊重审批边界session_create/session_send每次都需要在线审批被拒即停不绕路模拟诚实报告限制普通重启不丢已受理投递但外部工具执行期间崩溃无法保证副作用恰好一次也不存在调用方幂等键重试需先询问用户。相关参考sessions.md 原文档、cherry-tool-guide 全局规则与路由表、工具实现 cherryAutonomyTools.ts、投递数据模型 agentSessionDelivery.ts以及同属该技能的其他领域参考autonomy.md、memory.md、skills.md。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考