会话协作
本页面向使用或配置协作的用户，说明模型工具、会话操作和等待结果。Agent 保存可复用配置；每个协作成员拥有独立 Thread、Input 队列、Turn/Run、消息历史和 checkpoint。创建关系组成协作树，树内成员共享同一 Project Workdir；同一用户和 APP 的不同协作树也可互相协作，跨项目任务使用目标自己的工作目录。同一用户的所有会话共用一个持久 Cube VM。输入调度的底层契约见输入队列与调度。
身份与创建
协作 middleware 在每个 Run 首次模型调用时按实际执行归属读取 Session，并在系统提示中注入当前名称、完整路径、会话 ID、父会话 ID、根会话 ID、根或子会话身份，以及 Input、Turn、Run ID。后续模型调用复用该 Run 的固定身份；动态进度通过 list_sessions 查询。子会话优先完成收到的任务，继承 Agent 配置不会把根会话的整体编排职责转交给子会话。
list_agents 返回当前执行用户可调用的 Agent 配置，每项只包含 id（配置 slug）、name 和 description。目录复用公开 Agent API 的运行权限：私有配置仅供所有者运行，APP 终端用户只使用凭据所有者有权访问的共享配置。
create_session(name, description, agent_id=None, mode="child") 默认创建当前 Session 的直属子会话并提交初始输入，返回 session_id、自动生成的树内路径和输入回执。指定 list_agents 返回的 id 时使用目标 Agent 配置；省略时继承派发方配置。name 只填写 1–64 位字母、数字、下划线或连字符组成的局部名称；同父节点下唯一，创建后固定。父节点由实际调用的 Run 所属 Session 决定，调用者不能指定父节点或完整路径。
mode="root" 创建独立顶层对话，继承当前项目、配置与审批选择，出现在项目会话列表中。它拥有自己的 /root、历史、执行容量和停止状态；创建来源 Run 不构成父子关系。同一工具调用重放不能更换名称、模式或 Agent。
根会话 /root 传入 name="aaa"，系统生成 /root/aaa；只有 /root/aaa 传入 name="bbb"，才会生成 /root/aaa/bbb。根传入 name="aaa/bbb" 或 name="/root/aaa/bbb" 会被拒绝。路径只用于在当前树内寻址已有成员；跨树必须使用稳定 session_id，避免不同对话的 /root 混淆。
省略 agent_id 时，新会话继承派发方实际模型和配置；指定时冻结目标 Agent 的提示词、Skills、工具、MCP、知识库等配置，模型按目标配置及系统默认值解析。审批模式始终沿用派发方当前运行选择。后端在创建前重新校验当前执行用户的目标 Agent 运行权限；目录结果不替代即时授权，同一工具调用重放不得更换 Agent。执行期间继续复查账号、Agent 与依赖权限。
聊天输入框输入 @ 后，可在“智能体”分组选择当前用户可运行的已创建智能体，并按名称、描述或 ID 搜索。选择后显示名称，消息中保存 @agent:<id> 引用；当前智能体根据任务需要使用该配置创建协作子会话。提及保持当前会话归属，实际调用仍由后端校验权限。
description 提供工作目标、必要资料和交付要求；会话独立保存历史、checkpoint 和附件上下文。共享目录文件可通过统一文件权限边界读取。角色分工写入描述，配置入口见配置智能体。
工具与用户操作
| 工具 | 行为 |
|---|---|
create_session | 创建关联会话并提交首个输入，立即返回身份与回执 |
submit_input | 按 FIFO 提交新工作；等待用户回答或审批时返回拒绝 |
send_message | 持久投递信息，运行中在模型边界读取，空闲时留待下次运行 |
list_sessions | 默认读取本项目会话；scope="all" 按更新时间倒序读取同用户、同 APP 的历史，每页最多 10 条，offset 从 0 开始翻页 |
list_agents | 列出当前用户可调用的 Agent 配置，用返回的 ID 选择新会话配置 |
get_result | 用 input_id 或 turn_id 精确读取任务状态、最终输出和错误；两个参数只能选择一个 |
wait_inputs | 等待 1–100 个已提交 input_id 全部结束；返回精确结果或带当前结果的超时响应，最长等待 1800 秒 |
wait_sessions | 从 after_cursor 等待指定其他成员任一更新，返回新游标或超时结果；空列表与当前会话自身明确拒绝 |
cancel_turn | 按 Session 与 Turn 身份取消指定轮次，保留历史和已有文件 |
list_sessions() 返回当前项目完整目录；list_sessions(scope="all", offset=10) 返回历史目录的第二页，历史目录包含本项目。offset 必须非负，仅在历史查询生效。回执标注查询范围，每项只提供会话标识、标题、路径、所属根和项目、当前 Turn 标识与状态、等待类型，不包含结果正文或内部 Run、队列字段。跨树操作使用返回的稳定 session_id。
系统设置中的“最大协作深度”默认 2，根会话为第 0 层，设为 0 可关闭新增子会话。创建直属子会话超过限制时返回明确的工具拒绝，Session 与 Input 均不创建；已提交创建的幂等重放保留原结果。限制在后端持久创建入口执行，协作提示词不拥有该约束。
create_session 和 submit_input 返回的 input_id 在排队时就已固定；消费后仍映射到同一个 Turn。等待任务交付使用 wait_inputs，等待成员消息使用 wait_sessions。排队输入取消也会结束任务等待。成员或其他顶层对话开始下一轮后，get_result 仍返回指定任务的结果；会话摘要只表达当前状态，不携带正文。
当前用户和 APP 的所有会话都可互相投递信息、追加输入、读取精确结果、等待更新或取消指定 Turn；后端按持久 Run 复核用户和 APP 授权，拒绝其他用户或 APP。会话路径仍只在本树内解析。完成、失败、取消和等待用户产生持久更新。协作文本作为模型参考，不替代用户授权或审批。
用户在状态面板选择会话即可进入其普通消息页，直接输入、steer、回答问题或审批。直接干预成员会话会通知父会话。父轮次结束或失败保留后代工作；“停止全部”明确停止整树在途工作和队列消费，“继续整树队列”重新消费待处理输入，已取消轮次保留终态。停止只暂停有待办的成员队列；全树停止和清理完成后，用户发送新消息优先恢复目标会话，其他成员旧待办保持暂停。
主会话是侧边导航中的协作入口。整树仍有执行、人工或协作等待、待处理输入或运行时清理时，归档主会话会被拒绝；全部结束后才可归档。归档不取消工作，也不删除成员历史或已有文件。
主会话输入框上方汇总其他协作成员的待回答和待审批请求。单项点击直接打开对应侧栏标签并聚焦人工操作卡片，多项点击展开待办列表；已打开的成员标签显示待办徽标。查看或关闭标签保留待办，处理完成或请求结束后随协作摘要刷新移除。状态查询失败时显示更新失败与重试入口，并保留最近已知待办；实际回答和审批始终在对应成员会话中提交。
执行、等待与环境
根与所有后代共用执行名额，由系统设置中的“协作树并发执行上限”控制，默认四个，并在 PostgreSQL 树锁内原子领取。排队、等待用户以及等待协作更新不占名额；协作等待保存 Input 目标或成员与事件游标，以及截止时间后退出当前 worker 执行，恢复时在同一 Turn 创建下一 Run 并重新领取名额。容量参数的区别与调整方式见Agent 并发容量。
协作等待期间，主会话保持进行中，显示“等待协作任务完成”并保留停止入口。公开 item 在 incomplete 状态外携带协作等待原因，工具以中性等待状态展示；恢复结果按原调用身份关联后显示完成。等待审批或用户回答仍由独立的用户操作界面处理。
侧边栏将当前 Turn 的活动状态与新回复的未读标记分开：运行和排队统一显示转动指示，不显示文字；等待协作、等待批准和等待回答分别显示标签。完成、取消和失败不常驻活动标签，失败原因在对话内展示。审批和回答使用醒目的提示，协作等待使用中性提示。查看会话不会清除仍在等待的活动状态；折叠项目沿用相同展示方式。
协作输入的消息上方显示可点击的创建来源；来源根会话打开主页面，来源成员在所属根页面的侧栏打开。定时任务和 API 事件显示实际来源类型，没有会话来源时不生成会话链接。连续同类协作调用合并为紧凑事件行，各操作目标可独立点击；会话查询只显示“查看了本项目会话”或“查看了历史会话”及本次返回条数，不展开名单。含会话列表但未标注范围的旧回执按历史查询展示。完整成员列表仍在协作状态面板查看。
消息、回执和终态事实先提交，再投递执行。同一 Turn 内跨 Run 重放的工具调用复用回执，新 Turn 的相同 tool call ID 可提交新工作；消息本身不创建 Turn，不自动唤醒空闲会话。事件发布顺序按同用户和 APP 串行分配，跨树等待不会越过尚未提交的事件。最终输出来自目标 Turn 的 result_run_id 所指向 Run，运行失败与 worker 失联都有持久终态通知。
等待恢复按记录隔离失败，坏记录保留错误日志并继续处理其他等待。worker 各恢复阶段独立处理错误；失败阶段不阻断后续派发，完整恢复成功后才续报健康。用户环境维护使用独立循环与用户生命周期锁；休眠或重建期间新执行暂缓领取，协作消息仍可提交。
同用户已安装软件、Home 配置与环境共享；不同 Project 仍有独立工作目录。单个 Run 结束需要确认所属命令清理；用户没有活动 Run、操作或待清理命令时，环境空闲五分钟休眠。下次使用恢复原 VM 和软件，后台进程连续运行不作保证。取消只终止所属命令及普通子进程组，已有文件副作用保留；共享文件并行修改由工作分工协调。
源码定位与验证
协作服务拥有创建、输入、通知与等待恢复，协作 repository拥有树范围与并发领取，leases拥有执行续租与空闲释放。持久结构由 Session、CooperationEvent 和 CooperationRuntime 的 Schema 约束。
真实 PostgreSQL 测试覆盖幂等、递归并发、跨用户和 APP 拒绝、跨树事件提交顺序、等待恢复及取消竞态；确定性 E2E回读公开 Turn、会话树与共享目录文件。取舍见统一 Session 决策与人工待办入口决策。