Team Run 与团队协作（2.1.0+）

以前是"一个员工带子任务"。现在是"一个团队围着一块任务板"。

子员工委派（delegateToAgent）解决的是"一个人临时叫帮手"：同步等结果、一对一、过程黑盒。但真实的复杂交付不长这样——它长得像一个项目：拆任务、标依赖、并行推进、卡点审批、交付物归档、随时能看谁在干什么。

团队协作把这套项目机制搬进 MateClaw：你建一个团队，指定一个 Lead 员工、若干成员员工；对 Lead 说一句目标，它把目标拆成任务落到共享任务板上；派发引擎把任务自动分给成员并行执行；成员完成后结果自动通报回 Lead，由它汇总、补派、直到整件事干完。你全程在 Teams 页旁观——或者直接往板上投任务。

2.1.0 在任务之上增加一等对象 Team Run：一条用户请求只对应一轮运行，一个 runId 串起原始目标、任务 DAG、成员子会话、事件、最终汇总与交付物。你看到的不再是一堆叫“子任务”的会话，而是一份结果优先、可以下钻的完整工作记录。

2.1.0 的统一 Team Run 体验

页面	职责	默认看到什么
Chat	成果交付面	一张稳定的运行卡片：统一状态与进度、最终摘要、交付物、失败或待审批事项；任务过程按需展开
Agents · Live	实时观察面	同一 `runId` 下的成员按运行分组，显示当前任务、phase、工具、耗时和异常；普通非团队运行保持独立
Teams	历史与治理面	团队运行历史、运行详情、任务证据、审批、取消与成员执行记录，不再把所有历史任务平铺成主视图

Team Run 状态由服务端统一投影：

text

planning → running → awaiting_review → finalizing → completed
                                      ↘ partial / failed
planning / running / awaiting_review → cancelled

一事一身份：SSE 事件、页面路由、日志、任务和最终消息都携带 runId；
成果优先：中间任务完成只更新运行进度，不为每个任务制造一条面向用户的最终回复；
子会话治理：team_worker 会话不进入普通会话侧栏；深链接仍可打开，但以只读执行记录呈现并提供返回 Team Run 的入口；
刷新可恢复：页面只消费后端 TeamRunView，标题、状态、进度、摘要和文件不会因前端重算而漂移；
历史兼容：2.0.0 创建、没有 runId 的任务继续可查，但不会按时间窗口被错误拼成一次运行。

运行协议固定为 start_run → create* → seal_run：Lead 先建立运行，再创建显式归属该运行的任务，最后封板开始派发。来源消息参与幂等约束，重连或重复提交不会再造出第二轮相同运行。

核心概念

概念	说明
团队（Team）	一组员工 + 一块任务板。一个员工可以加入多个团队。
角色（Role）	`lead` / `member` / `reviewer` 三种。Lead 负责拆解与汇总，成员负责执行，reviewer 参与审阅。
任务（Task）	板上的一条工作项：标题、描述、指派人、依赖（`blockedBy`）、进度、结果、交付物、评论、时间线。
任务板（Board）	按状态分列的看板。状态机由数据库条件更新守卫——并发场景下谁先改成功谁算数，不会出现双重状态。

任务状态一共八种：

pending → in_progress → completed / failed / cancelled
                ↘ in_review（要求人工审批的任务）
blocked（等前置任务）   stale（租约过期，可重试）

failed 与 stale 的任务可以重试；completed / cancelled 会放行依赖它的下游任务。

一次典型协作长什么样

你对 Lead 说目标：“做一份竞品分析：先各自调研 A、B 两家，再汇总成一份报告。”
Lead 拆任务上板：调用 team_tasks 工具建三条任务——“调研 A”“调研 B”并行，“汇总报告”声明 blockedBy 前两条，自动进入 blocked。
派发引擎接手：常驻扫描（30 秒一轮，工具/REST 动作后立即加扫）把 pending 任务派给指派成员——每个任务开一个独立子会话，成员在里面跑完整的 Agent 图。每个成员同时只吃一个任务，其余排队。
前置结果自动传递：“调研 A/B”完成后，“汇总报告”被放行，派发信封里自动带上两条前置任务的结果与交付物链接——成员 C 不需要 Lead 人肉转述成员 A 干了什么。
结果通报唤醒 Lead：任务落定（完成/失败）后合批通报给 Lead，Lead 被唤醒发起真实新一轮——检查结果、补派任务或宣布收工。
你全程可见：Teams 页的看板实时刷新（SSE 事件驱动，不靠轮询），活动横幅滚动播报“#3 已派发给内容工作室”；点开任务能看时间线、进度、评论、交付物，还能跳进成员子会话看它逐字执行的全过程——运行中打开就是打字机直播。

Lead 手里的工具：`team_tasks`

Lead（和成员）通过 team_tasks 工具操作任务板，动作按角色门禁：

动作	谁能用	干什么
`list`	所有成员	渲染当前任务板（Lead 每轮还会自动收到实时看板快照，见下）
`get`	所有成员	查看单个任务详情
`create`	Lead	建任务：标题、描述、指派成员、`blockedBy` 依赖、`requireApproval` 是否需人工审批
`complete`	执行成员	提交结果完成任务（要求审批的任务转入 `in_review` 等人批）
`progress`	执行成员	上报进度百分比与当前步骤（同时给执行租约续期并广播到看板）
`comment`	所有成员	在任务下留言
`attach`	执行成员	给任务挂交付物（文件名 + 下载链接）
`cancel`	Lead	取消任务——会真的中断正在执行的成员会话，不是只改个状态
`retry`	Lead	重试 `failed` / `stale` 的任务

团队上下文注入：加入团队的员工，system prompt 会注入团队名册与协作行为准则；Lead 每轮对话还会动态注入实时看板快照——它不需要先调 list 才知道板上有什么，多轮对话也不会因为"忘了看板"重复建任务。

为长任务而生的执行加固

团队面向的是深度研究、长文档处理这类一跑几十分钟起步的任务，执行链路按此加固：

执行租约 + 运行期心跳。任务派发即持有 60 分钟执行租约，成员运行期间后台自动续期；真正失联的任务（进程崩溃、重启）租约到期被判 stale，可安全重派——不会出现"任务还在跑就被重派、两个实例互相覆盖"的双重执行。
取消即中断。cancel 不只是状态转移：成员子会话注册进流跟踪器，图节点每轮检查停止位，取消后运行中的成员会话在下一个节点边界停下——不再有"取消了还在烧 token 到自然结束"。
人工审批卡点。建任务时声明 requireApproval，成员提交后任务停在 in_review，由你在 Teams 页 approve / reject——敏感产出离开团队前先过人。
手动投任务。任务不非得 Lead 建：Teams 页可以直接建任务指派给某个成员，结果落板上由你查看（没有 Lead 会话要唤醒时，通报自动降级为 no-op）。

交付物与执行过程可见性

复杂任务的产出不是一段文本，是文件 + 摘要：

成员用文档渲染工具（docx / pptx / xlsx / pdf）或技能产出文件后，通过 attach 把交付物登记到任务上；任务详情渲染可下载附件列表，结果通报也会带上附件——链接不再埋在被截断的长文本里。
每个任务详情都有**"查看执行过程"**入口：跳进成员子会话的完整转写——派发信封、逐轮思考、工具调用、中间产物一览无余。任务运行中打开，就是实时打字机直播（断线重连自动回放缓冲）。
任务时间线：谁在什么时候创建/派发/上报进度/挂附件/审批/取消，逐条落 mate_team_task_event 审计表，任务详情按时间线渲染——协同过程有史可查。

Plan-Execute Lead：计划直接变任务板

Lead 不限定 Agent 类型。ReAct 型 Lead 用 team_tasks 逐条建任务；Plan-Execute 型 Lead 更进一步——规划节点产出的计划整体移交任务板：

计划步骤逐条映射为看板任务，步骤依赖链变成 blockedBy——原本严格串行的计划从此能并行的并行；
移交后计划停靠（delegated），Lead 回合正常结束，等待由派发/通报闭环接管；
全部任务落定后，通报唤醒经停靠计划恢复门确定性地路由到计划汇总节点，从任务结果与交付物重建上下文、产出总结——与工具审批"落库停靠、新一轮续跑"同构，不引入检查点机制。

移交是全有或全无：只有当计划的每一步都能落到某个团队成员头上时才整体上板；有任何一步指不到成员，整个计划回落到原有的串行委派管线，行为与从前完全一致。

一句话：会规划的 Lead，规划能力直接变成团队编排能力。

Teams 页

管理控制台新增 Teams 页（/teams）：

团队管理：建团队、加/减成员、指定角色；
看板：按状态分列，事件驱动实时刷新，列内分页加载且列头显示数据库侧统计的真实总数——千条任务的板也拖不垮页面；
活动横幅：滚动播报派发、完成、失败等团队事件；
任务详情：时间线、进度、评论、交付物下载、执行过程入口、approve / reject；
手动建任务：直接往板上投活。

REST API

管理面 API 全部挂在 /api/v1/teams 下：

端点	说明
`GET /api/v1/team-runs/{runId}`	读取完整运行投影
`GET /api/v1/teams/{teamId}/runs` · `GET …/runs/page`	列出 / 按游标读取团队运行历史
`GET /api/v1/conversations/{conversationId}/team-runs` · `GET …/team-runs/page`	列出 / 按游标读取父对话中的 Team Run
`POST /api/v1/team-runs/{runId}/cancel`	取消运行及其未终态任务
`GET / POST /api/v1/teams`	列出 / 创建团队
`GET / PUT / DELETE /api/v1/teams/{id}`	团队详情 / 更新 / 删除
`POST /api/v1/teams/{id}/members` · `DELETE …/members/{agentId}`	成员增删
`GET / POST /api/v1/teams/{id}/tasks`	任务列表（窗口化分页）/ 建任务
`GET /api/v1/teams/{id}/tasks/stats`	各状态任务数（数据库侧统计）
`GET /api/v1/teams/{id}/tasks/{taskId}`	任务详情
`POST …/tasks/{taskId}/approve · reject · retry · cancel`	审批 / 重试 / 取消
`POST …/tasks/{taskId}/comments`	评论
`GET …/tasks/{taskId}/events`	任务时间线
`GET /api/v1/teams/{id}/events`	团队级 SSE 事件流（看板实时刷新的数据源）

所有校验失败都以可读错误返回——不是裸 500。

数据在原有五张团队表之上新增 mate_team_run，mate_team_task.run_id 与成员会话索引负责把任务、运行和执行记录关联起来。所有 Snowflake id 在 JSON 边界按字符串返回。

与子员工委派（delegateToAgent）怎么选

	`delegateToAgent`	团队任务板
形态	一对一临时叫帮手	常设团队 + 共享看板
并行	单点异步	成员级并行 + 依赖编排
过程	黑盒等结果	时间线 + 实时旁观 + 交付物
中断/恢复	随父会话	租约、取消中断、重试
适合	单个子问题外包	多角色多步骤的项目型交付

两者共存：团队成员在自己的任务里照样可以再 delegateToAgent 叫帮手。

接下来读什么

Agent 引擎——ReAct 与 Plan-Execute 图的工作方式
持久化目标——单个员工的跨轮任务跟进
工作流——确定性步骤编排（流程固定时用工作流，流程要临场拆解时用团队）
安全与审批——工具审批与团队任务审批的关系

Team Run 与团队协作（2.1.0+） ​

2.1.0 的统一 Team Run 体验 ​

核心概念 ​

一次典型协作长什么样 ​

Lead 手里的工具：team_tasks ​

为长任务而生的执行加固 ​

交付物与执行过程可见性 ​

Plan-Execute Lead：计划直接变任务板 ​

Teams 页 ​

REST API ​

与子员工委派（delegateToAgent）怎么选 ​

接下来读什么 ​