SaaS Team Workbench 后端能力支持讨论 #739

potter-sun · 2026-05-20T07:01:57Z

potter-sun
May 20, 2026

背景

Aevatar Console 正在收敛成 SaaS 视角的 AI Team Workbench。在这个产品模型里，用户打开 Team Detail 时，首先关心的不是 actor、run、Envelope 或底层日志，而是：

这支 Team 现在在做什么？
哪些成员在工作？
最近发生了什么？
消息如何在成员、服务、连接器、LLM、工具之间流转？
Team 当前是健康、等待、失败、暂停，还是已归档？
我应该点哪里继续调试或继续构建？

当前前端已经可以展示 Team identity、lifecycle、member roster、member/service 提示和最近 run 摘要。但完整 Team Workbench 里有几类能力必须先由后端提供 Team-scoped 的权威事实，前端不应该在浏览器里临时拼出 Team 级事实。

这个 Discussion 的目的

这个 Discussion 用来和后端同学讨论：为了把 Team Detail 做成完整 SaaS Team Workbench，后端需要先支持哪些 Team-scoped 能力、这些能力的语义边界是什么、应该按什么顺序落地。

为方便逐条讨论，下面每个能力点已拆成独立 comment：

Team-scoped 事件流 / Team Activity
Team-scoped 事件拓扑 / Event Topology
Team pause/resume 生命周期
Team 运营指标
Team connector 可见性
共通实现原则与开放问题
Team Test / 测试 Team

当前后端已有能力

已有：

StudioTeamGAgent 和一等 Studio Team identity
Team API：create/list/get/patch/archive/list members
Team current-state readmodel：identity/lifecycle/member count
Member readmodel：包含可选 teamId
Service/member run API
Run audit API
Actor graph API，例如 /api/actors/{actorId}/graph-enriched
Workflow/chat run 能力：可通过 agentId + scopeId 测试某个 actor/workflow/member/service

重要限制：

现有 actor graph 是 run/root-actor scoped，适合做 run drilldown，不是 Team 事件拓扑。
现有 run/member/service API 可以支撑局部视图，但不等于 Team-scoped activity 或 topology。
现有 chat/run 入参没有 teamId，因此不支持一等 Team Test，只能测试某个选定 member/service。
前端不应通过查询所有 members/runs/audits 来临时拼出“Team 事件流”或“Team 拓扑”。

期望讨论结果

希望这轮讨论后可以明确：

哪个 Team Workbench 后端能力先做
Team Activity 的 API/readmodel 契约
Team Event Topology 是否和 Activity 同期做，还是后置
Team Test 是否先做 member/service selector 过渡版，还是新增 Team-scoped test command/API
pause/resume 是否进入 v1，以及它的准确语义
哪些 metrics 和 connector 数据可以安全暴露
前端开始实现前需要哪些测试和架构门禁

potter-sun · 2026-05-20T07:10:01Z

potter-sun
May 20, 2026
Author

1. Team-scoped 事件流 / Team Activity

关联 issue：#738

产品目标

Team Detail 需要一个 事件流 / Team Activity tab，用 SaaS 产品语言展示这支 Team 最近发生了什么。用户应该能快速看懂：哪个成员处理了请求、是否成功、是否失败、是否在等待人工介入，以及应该点哪里继续查看详情。

这不是 raw log viewer，也不是单个 run audit。它应该是 Team 维度的运营时间线。

为什么现有 API 不够

现有 listMemberRuns、listServiceRuns、getMemberRunAudit、getServiceRunAudit 都是 member/service/run 维度。前端可以临时查所有 member、所有 run、所有 audit 再拼一个列表，但那会变成 query-time 聚合出来的伪 Team 事件流。

Team Activity 应该由后端拥有 Team 归属、分页、过滤、版本/水位、脱敏和事件语义。

建议后端能力

新增 Team-scoped event stream endpoint，例如：

GET /api/scopes/{scopeId}/teams/{teamId}/events?take=50&pageToken=...&severity=...&memberId=...&eventKind=...

响应建议包含：

scopeId
teamId
readmodel stateVersion 或等价水位
updatedAt
events[]
nextPageToken

单条事件建议包含：

eventId
occurredAt
eventKind
severity
title
summary
memberId
serviceId
runId
actorId
connectorId
eventTypeUrl
correlationId
commandId
status
error

v1 事件类型建议

connector_message_received
team_routed
member_run_started
member_run_completed
member_run_failed
member_waiting
member_resumed
llm_call_started
llm_call_completed
tool_call_started
tool_call_completed
reply_sent
retry_scheduled
error_observed

实现约束

必须来自 committed/durable facts 或正式 projection/readmodel。
禁止 query-time replay。
禁止读 actor 内部状态拼结果。
禁止中间层维护 teamId -> events/context 进程内字典。
禁止前端 stitching 冒充 Team event stream。

需要后端一起确认

Team Activity 的权威输入源是什么：EventEnvelope observation、run audit projection、service run facts、connector facts，还是组合 projection？
后端是否提供 title/summary，还是只提供 typed fields 由前端格式化？
v1 需要哪些 filter：severity、eventKind、memberId、serviceId、runId、time range？
是否需要 live/SSE，还是 v1 用分页查询 + refresh 即可？

0 replies

potter-sun · 2026-05-20T07:10:33Z

potter-sun
May 20, 2026
Author

2. Team-scoped 事件拓扑 / Event Topology

关联 issue：#737

产品目标

Team Detail 需要一个 事件拓扑 tab，展示 EventEnvelope 如何在 Team 成员、服务、连接器、LLM、工具、外部端点之间流转。这个视图面向 SaaS Team Workbench：用户看的是“这支 Team 如何协作”，而不是“某个 actor 的执行图”。

和现有 `graph-enriched` 的区别

现有 /api/actors/{actorId}/graph-enriched 是 actor/run scoped，语义是 workflow execution graph：

根是 actorId
节点主要是 Actor / WorkflowRun / WorkflowStep
边主要是 OWNS / CONTAINS_STEP / CHILD_OF
适合做 run drilldown

Team 事件拓扑则应该是 Team-scoped：

根是 scopeId + teamId
节点是 member/service/connector/LLM/tool/external endpoint 等
边表示 EventEnvelope 或业务事件流转
展示 Team 长期/近期协作关系，而不是单次执行结构

建议后端能力

新增 Team-scoped topology endpoint，例如：

GET /api/scopes/{scopeId}/teams/{teamId}/event-topology?take=200

响应建议包含：

scopeId
teamId
stateVersion 或等价水位
lastEventId
updatedAt
nodes[]
edges[]

节点类型建议：

team
member
service
workflow_run
connector
llm
tool
external_endpoint

边类型建议：

event
reply
llm_call
tool_call
schedule
error
binding

边上建议提供：

fromNodeId
toNodeId
eventTypeUrl
routeKind
audience
count
lastSeenAt
lastStatus
lastError

实现约束

不要把 /api/actors/{actorId}/graph-enriched 包一层后叫 Team topology。
不要由前端把多个 run graph 拼成 Team topology。
Team topology 应该来自后端正式 readmodel/projection。
拓扑里的 Team 归属必须通过权威事实解析，例如 member teamId、published service、run registration、connector/binding association 等。

需要后端一起确认

Team topology 和 Team Activity 是否共用一套 projection/readmodel family？
connector、LLM、tool 是否作为节点进入 v1？还是先只做 member/service/run？
边的聚合窗口是什么：最近一次、24h、累计、还是按最新 readmodel 覆盖？
是否需要 live 动画流？如果需要，是单独 SSE，还是前端通过轮询 topology readmodel？

0 replies

potter-sun · 2026-05-20T07:11:25Z

potter-sun
May 20, 2026
Author

3. Team pause/resume 生命周期

当前状态

早期 preview 里有 暂停 操作，但当前后端已有的是 archive。Archive 是不可逆归档，不等价于 pause。前端不能简单把按钮文案从 Archive 改成 Pause。

产品目标

SaaS Team Workbench 中，用户可能需要临时停止一支 Team 处理外部流量，但不想删除或归档 Team。例如：

临时关闭客服 Team
维护 connector 或 member 配置
避免异常 Team 继续处理消息
暂停新请求，但保留历史、成员、服务和配置

需要定义的语义

Pause/Resume 必须是后端明确命令语义，而不是前端状态切换。需要讨论：

Team 是否新增 lifecycle stage：active / paused / archived？
Pause 作用在哪一层？
- Team router
- member/service invocation
- connector ingress
- all of the above
Pause 后新流量如何处理？
- reject
- queue
- ignore
- return maintenance response
已经运行中的 run 怎么办？
- 继续完成
- stop
- suspend
- drain then pause
Resume 的 ACK 表示什么？
- command accepted
- routing resumed
- connector resumed
- readmodel observed

可能 API

POST /api/scopes/{scopeId}/teams/{teamId}/pause
POST /api/scopes/{scopeId}/teams/{teamId}/resume

响应必须诚实表达 ACK 阶段，不要在 weak ACK 中暗示强一致完成。

前端期望

如果后端支持 pause/resume，前端可以：

Team header 展示 Active / Paused / Archived
Paused Team 上显示明确 banner
Team 列表卡片展示暂停状态
Test Team、connector ingress 或 member invoke 根据后端语义展示可用/不可用

需要后端一起确认

v1 是否需要 pause/resume，还是只保留 archive？
pause 是 Team 的领域生命周期，还是 connector/service 层运行开关？
是否需要 pause reason、operator、pausedAt/resumedAt？
pause/resume 是否进入 Team Activity 事件流？

0 replies

potter-sun · 2026-05-20T07:12:03Z

potter-sun
May 20, 2026
Author

4. Team 运营指标

产品目标

Team 列表和 Team Overview 需要一些 compact metrics，让 SaaS 用户快速理解 Team 状态。例如 preview 中出现过：

今日消息数
在线率
成功率
平均响应时间
运行中成员数
下一次计划动作

但这些指标必须有后端语义支撑，不能由前端猜。

为什么需要后端定义

同一个指标可能有多种含义：

“成功率”是按 run、message、reply、step，还是 connector delivery 计算？
“今日”按用户时区、UTC，还是租户区域？
“在线率”对 actor/member/service/connector 分别意味着什么？
“平均响应”从收到 connector 消息算到 reply sent，还是从 run started 到 completed？
“运行中成员”是 active lifecycle、最近有 run，还是 actor runtime live？

如果前端先展示这些数字，后续很容易变成产品债务。

建议后端能力

可以先提供一个 Team operational summary endpoint/readmodel，例如：

GET /api/scopes/{scopeId}/teams/{teamId}/operational-summary?window=24h

或把 summary 放入 Team Activity/Topology readmodel 的 companion API。

响应建议包含：

scopeId
teamId
window
stateVersion 或水位
updatedAt
messageCount
runCount
successRate
failureCount
waitingCount
averageResponseMs
activeMemberCount
lastActivityAt
nextScheduledAt

所有字段需要清楚定义统计口径。

需要后端一起确认

v1 哪些 metrics 是必须的？
每个 metric 的分母/分子是什么？
时间窗口如何定义？
metrics 是否从 Team Activity 派生，还是单独 readmodel？
是否需要 scope/team/member/service 多层 rollup？

0 replies

potter-sun · 2026-05-20T07:12:34Z

potter-sun
May 20, 2026
Author

5. Team connector 可见性

产品目标

Team Detail 可能需要 连接器 / Connectors 视图，让用户知道这支 Team 正在通过哪些外部入口或外部服务工作，例如 Telegram、Slack、Webhook、LLM provider、tool endpoint 等。

从 SaaS 用户角度，这不是全局 connector admin，而是回答：

这支 Team 接入了哪些渠道？
哪些成员或服务会处理这些渠道来的事件？
connector 当前是否健康？
最近是否有 connector error？
我能点到哪里配置或排查？

当前不清楚的地方

Connector 很可能是 scope-level 或 governance/binding-level 事实，而 Team 是 scope 下的一等聚合。需要明确 connector 如何归属 Team，否则前端无法决定应该展示：

scope 下所有 connectors
只展示 Team member/service 使用过的 connectors
只展示显式绑定到 Team 的 connectors
只展示最近 Team Activity 中观察到的 connectors

这些不是 UI 选择，而是后端事实归属问题。

建议后端能力

新增 Team-scoped connector/binding query，或在 Team Activity/Topology 中提供足够 connector 节点后，由前端链接到 connector 详情。

可能 endpoint：

GET /api/scopes/{scopeId}/teams/{teamId}/connectors

响应建议包含：

scopeId
teamId
updatedAt
connectors[]

connector item 建议包含：

connectorId
connectorType
displayName
bindingId
status
lastSeenAt
lastError
memberIds[]
serviceIds[]
policyIds[]
configurationHref 或相关 drilldown identifiers

v1 简化方案

如果 connector 归属暂时不明确，v1 可以先不做独立 Connectors tab，只在 Team Activity / Topology 的节点或事件中显示 connector，并提供跳转。

独立 Connectors tab 应等到后端能明确回答“这个 connector 属于/影响这支 Team”的时候再做。

需要后端一起确认

connector 是 scope-level、service-level、member-level，还是 Team-level？
Team connector view 应该展示显式绑定，还是观察到的使用关系？
connector 健康状态的权威来源是什么？
connector error 是否进入 Team Activity？
connector 是否作为 Team Topology 节点进入 v1？

0 replies

potter-sun · 2026-05-20T07:13:12Z

potter-sun
May 20, 2026
Author

6. 共通实现原则与开放问题

建议实现顺序

推荐后端优先顺序：

Team Activity readmodel/API（Add Team-scoped event stream for SaaS Team Activity #738）
Team Event Topology readmodel/API（Add Team-scoped EventEnvelope topology read model and API #737）
Team pause/resume 生命周期语义
基于 Activity/Topology/run facts 的最小 Team metrics
Team connector attribution 和 connector view API

原因：Activity 和 Topology 会先建立 Team 可观察事实。Metrics、Connectors、Pause 状态展示都应该建立在这些 Team 归属和事件语义之上，而不是各自发明一套归属逻辑。

共通原则

所有 Team Workbench 后端能力都应满足：

Team-scoped：每条返回数据都能归属到 scopeId + teamId。
Durable：基于 committed events、readmodels 或 durable observation feed。
Honest：需要一致性说明的结果暴露 version/watermark/updatedAt。
Typed：稳定业务语义用 typed fields，不塞进泛化 bag。
Drilldownable：尽量提供 member/service/run/actor/connector typed identifiers。
Runtime-neutral：不依赖本地进程运行态。
Query-safe：禁止 query-time replay 和 actor 内部状态侧读。
Projection-aligned：复用现有 projection/readmodel 架构，不新增第二套投影体系。

明确不希望出现的实现

前端查询所有 members/runs/audits 后拼 Team timeline。
后端 query 方法里临时 replay event store 构建 Team view。
中间层用 Dictionary<teamId, ...> 管 Team activity/topology 事实态。
把 /api/actors/{actorId}/graph-enriched 包装成 Team topology。
在 Team UI 上展示没有后端定义口径的 metrics。

开放问题

Team Activity 的权威 durable feed 是什么？
Team Activity 和 Team Topology 是否共用 projection/readmodel family？
service、connector、LLM、tool、child actor 的 Team 归属如何解析？
v1 稳定事件类型 taxonomy 是什么？
后端提供用户可读 title/summary，还是前端从 typed fields 格式化？
v1 pagination/filtering 最小集合是什么？
v1 是否需要 live/SSE，还是查询 + refresh 足够？
pause 的操作语义和 ACK 语义是什么？
哪些 metrics 足够稳定，可以进入 v1？
connector 是如何归属 Team 的，是否进入 v1？

期望讨论结论

这轮讨论结束后，希望能形成：

v1 后端先做哪个能力
对应 endpoint/readmodel/proto 契约
Team 归属解析规则
前端可以依赖的最小字段集
后端测试范围
前端开始实现的触发条件

0 replies

potter-sun · 2026-05-20T07:39:52Z

potter-sun
May 20, 2026
Author

7. Team Test / 测试 Team

当前状态

当前后端还不支持“直接测试 Team”的一等接口。

现有 Team API 覆盖：create/list/get/patch/archive/list members。现有 workflow/chat run 能力可以通过 agentId + scopeId 测试某个 actor、workflow、member/service 对应的能力，但入参里没有 teamId，后端不会把这次执行识别成 Team-scoped test。

因此，前端现在最多能做“在 Team 页面选择某个 member/service 去测试”。这可以作为临时交互，但它不是完整的 Team Test 后端语义，也不会天然进入 Team Activity / Event Topology。

产品目标

SaaS Team Workbench 里的 Test Team 应该让用户从 Team Detail 直接发起一次验证：

这支 Team 是否可以处理一条测试输入？
请求被路由到哪个成员或服务？
执行是否成功、失败、等待人工介入，还是被暂停/归档状态拦截？
测试结果是否能进入 Team Activity，后续是否能在 Event Topology 中看到这次流转？
用户是否可以从结果继续 drilldown 到 member、service、run、actor graph 或 audit？

这个能力面向的是 Team 维度的运营验证，而不是要求用户先知道底层 actorId。

v1 语义建议

建议把 Test Team 分成两个层次讨论：

前端可先做的过渡版：Header Test Team 打开 member/service selector，然后使用现有 member/service/chat run 能力测试选中的目标。这个版本不要求新增后端接口，但产品语义必须标注为“测试某个 Team member”，不是“Team 级测试”。
完整后端版：后端新增 Team-scoped test command/API。请求以 scopeId + teamId 为入口，由后端校验 Team、成员归属、目标可用性和生命周期状态，再创建可追踪的 test run，并把结果写入 Team Activity / Topology 所需的 durable facts。

建议后端 API

可以新增 Team-scoped test endpoint，例如：

POST /api/scopes/{scopeId}/teams/{teamId}/test-runs

请求体建议包含：

prompt 或 inputParts
targetMemberId 或 targetServiceId，是否必填需要讨论
sessionId
mode，例如 member_direct / team_route
commandId，用于幂等和追踪

响应建议采用 accepted receipt，不暗示强一致完成：

accepted
scopeId
teamId
targetMemberId
targetServiceId
actorId
runId
commandId
correlationId
activityEventId 或后续查询入口

如果需要流式返回，可以再讨论 SSE/WS 形态，但 ACK 语义仍应保持诚实。

后端需要支持的核心语义

teamId 必须是 typed command/API 字段或 path parameter，不应塞进 Metadata。
后端必须校验 targetMemberId/targetServiceId 确实属于 scopeId + teamId。
如果 Team 已 archived，应拒绝测试；如果未来支持 paused，需要明确 paused Team 是否允许 test。
如果不传 target，后端必须有明确 routing/default target 语义；不建议前端默认猜第一个成员。
test run 需要有 Team-scoped attribution，后续 Team Activity 能看到 team_test_started / team_test_completed / team_test_failed 等事件。
如果执行底层复用现有 workflow/chat/member run，也需要保留 Team 归属事实，而不是只返回 actor/run。

不建议的实现

前端把 teamId 放进 chat metadata，然后假装这是 Team Test。
前端选择第一个 member 自动测试，且没有后端默认路由语义。
后端 query path 临时拼接 member runs/audits 来生成 test 结果。
把“member test”在 UI 上宣传成完整 Team Test。

需要后端一起确认

Test Team v1 是否允许只做 member/service selector？
完整 Team Test 是否需要新增 POST /teams/{teamId}/test-runs？
不指定 target 时，是 reject、走 Team default route，还是后端选择默认测试目标？
Team paused/archived 状态下是否允许 test？
Team Test 的结果是否必须进入 Team Activity？是否作为 Topology 的事件边来源？
返回形态是 accepted receipt + Activity 查询，还是需要 SSE/WS 流式结果？
这个能力和现有 /api/chat、member binding、service run API 的边界如何划分？

0 replies

Navigation Menu

Uh oh!

SaaS Team Workbench 后端能力支持讨论 #739

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 7 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

SaaS Team Workbench 后端能力支持讨论 #739

Uh oh!

Uh oh!

potter-sun May 20, 2026

背景

这个 Discussion 的目的

当前后端已有能力

期望讨论结果

Replies: 7 comments

Uh oh!

potter-sun May 20, 2026 Author

1. Team-scoped 事件流 / Team Activity

产品目标

为什么现有 API 不够

建议后端能力

v1 事件类型建议

实现约束

需要后端一起确认

Uh oh!

potter-sun May 20, 2026 Author

2. Team-scoped 事件拓扑 / Event Topology

产品目标

和现有 graph-enriched 的区别

建议后端能力

实现约束

需要后端一起确认

Uh oh!

potter-sun May 20, 2026 Author

3. Team pause/resume 生命周期

当前状态

产品目标

需要定义的语义

可能 API

前端期望

需要后端一起确认

Uh oh!

potter-sun May 20, 2026 Author

4. Team 运营指标

产品目标

为什么需要后端定义

建议后端能力

推荐 v1 最小指标

需要后端一起确认

Uh oh!

potter-sun May 20, 2026 Author

5. Team connector 可见性

产品目标

当前不清楚的地方

建议后端能力

v1 简化方案

需要后端一起确认

Uh oh!

potter-sun May 20, 2026 Author

6. 共通实现原则与开放问题

建议实现顺序

共通原则

明确不希望出现的实现

开放问题

期望讨论结论

Uh oh!

potter-sun May 20, 2026 Author

7. Team Test / 测试 Team

当前状态

产品目标

v1 语义建议

建议后端 API

后端需要支持的核心语义

不建议的实现

需要后端一起确认

potter-sun
May 20, 2026

potter-sun
May 20, 2026
Author

potter-sun
May 20, 2026
Author

和现有 `graph-enriched` 的区别

potter-sun
May 20, 2026
Author

potter-sun
May 20, 2026
Author

potter-sun
May 20, 2026
Author

potter-sun
May 20, 2026
Author

potter-sun
May 20, 2026
Author