diff --git a/docs/designs/2026-04-08-console-web-ai-teams-preview.html b/docs/designs/2026-04-08-console-web-ai-teams-preview.html new file mode 100644 index 00000000..b1b16b76 --- /dev/null +++ b/docs/designs/2026-04-08-console-web-ai-teams-preview.html @@ -0,0 +1,471 @@ + + + + + +Aevatar Console — SaaS + Cloud Platform + + + +
+ + +
◆ Teams Layer — SaaS Product Experience
+ + +
+SaaS · /teams — 我的团队 +
+
+
v0.9
+
Teams
+
我的团队 2
+
组建团队
+
+
Platform
+
Governance 7
+
Services 7
+
Topology
+
Deployments 3
+
+
设置
+
Cluster: healthy
Region: ap-southeast-1
+
+
+
+
+
Aevatar / Teams
+
我的 AI 团队
+
+
+
+ 组建新团队
+
+
+
+ +
+
2
活跃团队
+
7
运行中成员
+
847
今日处理消息
+
99.7%
平均在线率
+
+ +
+ +
+
+
客服团队
处理 Telegram 客户咨询，24/7 自动接待与跟进
+
Running
+
+
+
接待员
+
处理专员
+
跟进员
+
+
+
612
今日消息
+
99.9%
在线率
+
94%
成功率
+
2.3s
平均响应
+
+
+ + + +
+
+ +
+
+
内容团队
监听群讨论，每日生成摘要简报，审核后自动分发
+
Running
+
+
+
群监听
+
编辑
+
审核
+
分发员
+
+
+
235
今日消息
+
99.5%
在线率
+
3
今日简报
+
18:00
下次发布
+
+
+ + + +
+
+
+
+
+
+
+ + +
+SaaS → Platform · /teams/:id — 团队详情 +
+
+
+
Teams
+
我的团队
+
组建团队
+
+
Platform
+
Governance
+
Services
+
Topology
+
Deployments
+
Cluster: healthy
+
+
+
+
+
Teams / 客服团队 scope-cs-001
+
客服团队 Running
+
+
+
测试对话
+
编辑
+
暂停
+
+
+
+
成员
3 agents
+
类型
2 workflow, 1 scripting
+
连接器
Telegram
+
消息 (24h)
612
+
在线率
99.9%
+
+
+
概览
+
事件拓扑
+
事件流
+
成员
+
连接器
+
高级编辑
+
+
+
+
EventEnvelope 流转拓扑 实时 · 点击节点查看详情
+
+ + + + + + + + +
Telegram
CONNECTOR
612 in / 590 out
+
接待员
workflow · svc-reception
312 processed
+
处理专员
workflow · svc-handler
198 processed
+
跟进员
scripting · svc-followup
102 scheduled
+
LLM
gpt-5.4
~1.2k tok/req
+
—— Event --- Reply ··· LLM
+
+
+
+
+
+
+ + +
◆ Platform Layer — Cloud Management
+ + +
+Platform · /teams/:id/events — 事件流 +
+
+
+
Teams
+
我的团队
+
组建团队
+
+
Platform
+
Governance
+
Services
+
Topology
+
Deployments
+
Cluster: healthy
Actors: 7 running · 0 faulted
+
+
+
+
+
Teams / 客服团队 / 事件流
+
客服团队 · EventEnvelope Stream
+
+
+
+
概览
+
事件拓扑
+
事件流
+
成员
+
连接器
+
高级编辑
+
+
+
+
+ EventEnvelope Stream +
+ + + +
+ ● Live · 12 events/min +
+
+
14:32:07MSG_INTelegram → 接待员"企业版定价方案是什么？"
+
14:32:08ROUTED接待员 → 处理专员Audience.CHILDREN · pricing · high
+
14:32:09LLM处理专员 → gpt-5.4GeneratePricingReply · 480→720 tok
+
14:32:11REPLY处理专员 → TelegramDirectRoute · 2.3s · delivered
+
14:32:11SCHED处理专员 → 跟进员Audience.CHILDREN · FollowupReminder · T+24h
+
14:30:12ERROR分发员 → TelegramRateLimit · retry=60s · 1/3 · evt-8f3a2
+
14:29:55MSG_INTelegram → 接待员"你们支持哪些支付方式？"
+
14:29:56ROUTED接待员 → 处理专员Audience.CHILDREN · faq · normal
+
14:29:57LLM处理专员 → gpt-5.4GenerateFaqReply · 320→410 tok
+
14:29:58REPLY处理专员 → TelegramDirectRoute · 1.8s · delivered
+
+
+
+
+
+
+ + +
+Platform · /teams/:id/members — 团队成员 +
+
+
+
Teams
+
我的团队
+
组建团队
+
+
Platform
+
Governance
+
Services
+
Topology
+
Deployments
+
Cluster: healthy
+
+
+
+
+
Teams / 客服团队 / 成员
+
客服团队 · Agents
+
+
+ 添加成员
+
+
+
概览
+
事件拓扑
+
事件流
+
成员
+
连接器
+
高级编辑
+
+
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StatusNameRoleTypeMsgs (24h)UptimeActor IDGovernance ServiceActions
Running接待员客户接待与分流workflow31299.9%actor-7f2a3bsvc-reception-001Edit · Logs · Graph
Running处理专员问题处理与 LLM 回复workflow19899.8%actor-a1c4e9svc-handler-001Edit · Logs · Graph
Running跟进员24h 跟进提醒调度scripting10299.9%actor-d5f8b2svc-followup-001Edit · Logs · Graph
+
+ ⓘ Governance Service ID 链接到 Platform → Services 页面。Actor ID 链接到 Platform → Topology 的 Actor 详情。 +
+
+
+
+
+ +
+ + diff --git a/docs/designs/2026-04-08-console-web-ai-teams.md b/docs/designs/2026-04-08-console-web-ai-teams.md new file mode 100644 index 00000000..172d1109 --- /dev/null +++ b/docs/designs/2026-04-08-console-web-ai-teams.md @@ -0,0 +1,228 @@ +--- +title: "Console Web 产品重构 — 你的 AI 团队" +status: APPROVED +owner: CEO +--- + +# Console Web 产品重构 — "你的 AI 团队" + +Generated by /office-hours + /plan-ceo-review + /plan-eng-review on 2026-04-08 +Branch: dev +Repo: aevatarAI/aevatar + +## 产品定义 + +"你的 AI 团队。你想要什么样的团队，我们就在云端帮你组建一个。" + +核心实体是**团队**（Team）。一个团队 = 一组 AI agent 分工协作。底层可以是 workflow/scripting/static GAgent 的组合，通过 Platform Governance 统一管理。 + +**后端映射：Scope = Team。** 一个 Scope 下所有 GAgent 消息互通，共享连接器和 Secrets。 + +## Problem Statement + +Console Web（`apps/aevatar-console-web/`，Potter 负责）有 14 个可见菜单项，分布在 5 个菜单组（build/chat/live/governance/settings）。所有命名使用工程术语：Studio、Capabilities、GAgents、Topology、Invoke Lab、Mission Control。 + +CEO 判断："完全没逻辑，东西都挤在一起，studio 跟栏目不知所云。" + +根本原因：前端按工程师的系统模型组织（actor 层、runtime 层、governance 层），而非按用户的心智模型组织。 + +## 双层架构：SaaS + Cloud Platform + +一个 Console，两种体验风格，通过导航分隔： + +``` +Teams（SaaS 产品体验）: 我的团队 | 组建团队 +────────────────────────────────────────────── +Platform（云平台管理后台）: Governance | Services | Topology | Deployments +``` + +### Teams 层 = SaaS 产品 +- **风格**：友好、简洁、面向业务用户（类似 Vercel 项目面板、Notion 工作区） +- **核心**：团队卡片、成员角色、一键操作 +- **目标用户**：飞书/Telegram 业务用户，不需要理解技术细节 + +### Platform 层 = 云平台管理后台 +- **风格**：信息密集、技术导向、面向管理员（类似 AWS Console、K8s Dashboard） +- **核心**：Governance 服务发现、全局 Topology、Deployments、Actor 状态 +- **目标用户**：平台管理员、DevOps、高级用户 + +### 映射关系 +- 一个 Team Member（SaaS 层）= Governance 下的一个 Service（Platform 层）= 底层的 workflow/scripting/GAgent +- Team 详情页是两层的桥梁：概览/成员是 SaaS 风格，事件拓扑/事件流是 Platform 风格 +- Chat 定位：辅助工具（创建流程中的对话创建 + 团队详情中的测试对话），不是一级导航 + +### 参照 +- **Vercel**：项目面板 = SaaS，Logs/Functions/Edge Config = 云平台 +- **Shopify**：商店管理 = SaaS，API/Webhooks/开发者工具 = 平台 +- **AWS Amplify**：前端部署 = SaaS 体验，底层 CloudFormation/Lambda = 云平台 + +## 核心认知（CEO Review 确认） + +### Agent 通信模型 +Agent 之间不是"群聊"。是事件驱动的协议通信： +- 通信载体：EventEnvelope +- 通信模式：树状传播（一个外部事件触发级联响应） +- 消息类型：不限于纯文本，是强类型 proto 消息 +- 可见性：团队详情页展示事件拓扑 + 事件流 + 事件树 + +### Governance 定位 +Governance 是平台级服务发现与治理层（服务注册、策略绑定、端点管理），不是团队级规则。归入平台层导航。 + +### Chat 定位 +Chat 是辅助工具（创建辅助 + 测试对话），不是产品核心形态。不作为一级导航。 + +### 渠道无关 +"AI 团队"概念跟具体渠道（飞书/Telegram）无关。先用已有 Telegram connector 跑通。 + +### Scope = Team +Scope 下所有 GAgent（workflow/scripting/static）共享消息路由和外部连接器/secrets。Scope 是 Team 的天然等价物。零后端变更。 + +## 与 Harness Theory 的对齐 + +- Team = Goal + Scope（团队目标 + 职责边界） +- Governance = 服务发现 + 策略绑定 + 治理层（平台级，不是团队级） +- Recursive Composition = 多 agent → 团队 → 多团队 → 公司 + +## 竞品参照 + +- AWS Console: 一个 console 两层视角的范式 +- Dify/Coze: 低代码 AI builder（Aevatar 不在 builder UX 上竞争，竞争力在 runtime） +- Heroku: 简化抽象的范式（但 Aevatar 不隐藏基础设施，而是综合它） + +## 路由变更 + +### 新路由结构 + +| 新路由 | 新名称 | 对应当前路由 | 层级 | +|-------|--------|------------|------| +| `/teams` | 我的团队 | `/scopes/overview` (Projects) | 用户层 | +| `/teams/new` | 组建团队 | **新建** | 用户层 | +| `/teams/:scopeId` | 团队详情 | **新建**（组合 topology + events + members） | 用户层 | +| `/governance` | Governance | 保留 | 平台层 | +| `/services` | Services | 保留 | 平台层 | +| `/runtime/explorer` | Topology | 保留 | 平台层 | +| `/deployments` | Deployments | 保留 | 平台层 | +| `/settings` | 设置 | 保留 | 底部 | + +### 隐藏（hideInMenu + redirect） + +| 当前路由 | redirect 到 | 原因 | +|---------|------------|------| +| `/scopes/overview` | `/teams` | 改名 | +| `/scopes/assets` | `/teams` | 工程概念 | +| `/studio` | 团队详情"高级编辑" Tab | 二级入口 | +| `/runtime/workflows` | `/teams` | 合并 | +| `/runtime/primitives` | `/teams` | 工程概念 | +| `/chat` | 团队详情"测试对话" | 辅助工具 | +| `/scopes/invoke` | `/teams` | 开发者工具 | +| `/runtime/runs` | `/teams/:id` 事件流 Tab | 合并 | +| `/runtime/gagents` | `/teams` | 合并 | +| `/runtime/mission-control` | `/teams/:id` | 合并 | + +### 命名对照表 + +| 当前 | 改为 | 原因 | +|------|------|------| +| Projects / Scopes | 我的团队 | 核心实体重定义 | +| GAgents | 团队成员 | 每个 GAgent 是团队的一个成员 | +| Runs | 事件流 / 团队活动 | 用户关心的是事件流转 | +| Capabilities / Primitives | (隐藏) | 用户不需要知道 | +| Topology | (平台层保留) | 全局拓扑仍有管理价值 | +| Invoke Lab | (隐藏) | 开发者调试工具 | +| Studio | (二级入口) | 从团队详情"高级编辑"进入 | +| Governance | (平台层保留) | 服务发现与治理 | + +## 团队详情页（核心新增页面） + +`/teams/:scopeId` 是本次重构最重要的新增页面，包含以下 Tab： + +### Tab: 概览 +- 团队状态、成员列表、关键指标 +- 快捷操作入口 + +### Tab: 事件拓扑 +- 复用现有 XYFlow (Topology/Explorer) 组件 +- 数据源：`runtimeActorsApi.getActorGraphEnriched(actorId)` +- 展示 EventEnvelope 在 agent 之间的流转路径 +- 节点区分：GAgent（实线） vs 外部服务（虚线，Telegram/LLM） +- 动画虚线表示实时事件流转 + +### Tab: 事件流 +- 复用现有 Runs 组件，改为 EventEnvelope 瀑布流 +- 数据源：`scopeRuntimeApi.getServiceRunAudit()` +- 每条显示：时间、类型（MSG_IN/ROUTED/LLM_CALL/REPLY/SCHEDULE/ERROR）、流转方向、TopologyAudience、详情 +- 错误事件高亮 + +### Tab: 团队成员 +- 成员表格：状态、名称、角色、实现类型（workflow/scripting/static）、消息数、在线率 +- 每个成员显示对应的 Governance Service ID（可跳转到平台层） +- 用户层与平台层的映射在此可见 + +### Tab: 连接器 +- 当前 Scope 绑定的连接器配置（Telegram 等） + +### Tab: 高级编辑 +- 跳转到 Studio，传入当前 Scope 上下文 +- 面向有经验的用户 + +## 数据源映射（全部已有 API） + +| 前端需求 | API | 文件 | +|---------|-----|------| +| 团队列表 | `scopesApi.listScopes()` | `src/shared/api/scopesApi.ts` | +| 团队成员 | `runtimeGAgentApi.listActors(scopeId)` | `src/shared/api/runtimeGAgentApi.ts` | +| 事件拓扑 | `runtimeActorsApi.getActorGraphEnriched(actorId)` | `src/shared/api/runtimeActorsApi.ts` | +| 事件流 | `scopeRuntimeApi.getServiceRunAudit()` | `src/shared/api/scopeRuntimeApi.ts` | +| 连接器 | 通过 Governance binding API | `src/shared/api/governanceApi.ts` | + +## Scope Decisions + +| # | Proposal | Effort | Decision | Reasoning | +|---|----------|--------|----------|-----------| +| 1 | 路由重组 14 → 2 用户层 + 4 平台层 | S | ACCEPTED | 核心产品逻辑 | +| 2 | 工程术语全替换 | S | ACCEPTED | CEO: "全是技术术语" | +| 3 | 团队首页（复用 Scope 列表） | S | ACCEPTED | 产品入口 | +| 4 | 团队详情（复用 XYFlow + Runs） | M | ACCEPTED | CEO 要求事件模型 + 消息流转 | +| 5 | 旧路由 redirect | S | ACCEPTED | 避免断裂 | +| 6 | 团队模板创建页 | S | DEFERRED | CEO 不接受硬编码，需后端模板 API | +| 7 | 对话创建（Chat 辅助） | M | DEFERRED | Chat 是辅助工具，后续做 | +| 8 | 飞书 connector | M | DEFERRED | 先用已有 Telegram connector | +| 9 | Agent 运行数据 projection | M | DEFERRED | 前端先用现有 API 拼接 | +| 10 | 多 agent 群聊 | M | SKIPPED | Agent 间是 EventEnvelope 事件协议，不是文本群聊 | + +## 实施文件清单 + +| 文件 | 变更 | +|------|------| +| `config/routes.ts` | 路由重组 + hideInMenu + redirect | +| `src/app.tsx` | postMenuData 菜单分组改为 Teams + Platform | +| `src/pages/scopes/overview/` | 标签改为"我的团队" | +| `src/pages/teams/` (新建) | 团队详情页，组合 topology + events + members Tab | +| `src/layouts/MainLayout.tsx` | 导航分组调整 | +| 各页面组件 | UI 标签替换 | + +## 约束 + +1. **不创建新项目**：在现有 Console Web 上重构 +2. **保留技术投资**：Ant Design、React Query、auth 流程、API 层保留 +3. **零后端变更**：Scope = Team 纯前端映射 +4. **语言规范**：UI 标签使用中文，路由路径和代码标识符保持英文 +5. **CLI Frontend 和 Desktop 暂不处理** + +## Success Criteria + +1. 新用户打开 Console 能在 10 秒内理解"这是 AI 团队管理平台" +2. 菜单可见项从 14 个降到 2 用户层 + 4 平台层 +3. 零工程术语出现在用户层界面 +4. 团队详情页能展示事件拓扑（XYFlow）和事件流（EventEnvelope 瀑布流） +5. 每个团队成员可见对应的 Governance Service ID（用户层到平台层的映射） + +## 预览 + +产品预览页面：[`docs/designs/2026-04-08-console-web-ai-teams-preview.html`](2026-04-08-console-web-ai-teams-preview.html) + +包含 4 个核心页面的完整线框图： +1. `/teams` — 我的团队（首页） +2. `/teams/:id` — 事件拓扑 Tab +3. `/teams/:id` — 事件流 Tab +4. `/teams/:id` — 团队成员 Tab diff --git a/docs/designs/2026-04-08-studio-redesign-preview.html b/docs/designs/2026-04-08-studio-redesign-preview.html new file mode 100644 index 00000000..b64e4ca5 --- /dev/null +++ b/docs/designs/2026-04-08-studio-redesign-preview.html @@ -0,0 +1,517 @@ + + + + + +Aevatar Studio — Agent Editor Preview + + + +
+ + + + +
+Studio · 行为定义 — Workflow 可视化编辑器 +
+ +
+
☷行为定义
+
✎脚本行为
+
◉Agent 角色
+
◆集成
+
+
▶测试运行
+
+
⚙设置
+
+ +
+ +
+ ← 客服团队 + / 处理专员 / 行为定义 + scope-cs-001 · svc-handler-001 +
+
▶ 测试运行
+
保存
+
+
+ + +
+ +
+
行为定义 3
+
+
接待流程
+
4 步骤 · 刚刚修改
+
+
+
处理流程
+
6 步骤 · 2h 前
+
+
+
跟进流程
+
3 步骤 · 1d 前
+
+
+
+ 新建定义
+
+
+ + +
+ + + + + + + + + + +
+
data
+
retrieve_context
+
→ 处理专员
+
+ +
+
control
+
classify_intent
+
→ 处理专员
+
+
+ pricing + faq + +
+
ai · llm_call
+
generate_pricing
+
→ 处理专员
+
+ +
+
ai · llm_call
+
generate_faq
+
→ 处理专员
+
+ +
+
integration
+
send_reply
+
→ Telegram
+
+ +
+
human
+
schedule_followup
+
→ 跟进员
+
+ +
+
自动布局
+
适应画面
+
+
+
−
+ 100% +
+
+ + +
+
+
步骤属性
+
角色
+
YAML
+
+
+
选中: classify_intent
+ +
+
步骤类型
+ +
+ +
+
目标角色
+ +
+ +
分支
+
+
条件 → 目标步骤
+ +
+ +
参数
+
+
参数 (JSON)
+ +
+ +
+
应用更改
+
+
+ 删除此步骤 +
+
+
+
+
+
+
+ + + + +
+Studio · 脚本行为 — C# 编辑器 +
+
+
☷
+
✎
+
◉
+
◆
+
+
▶
+
+
⚙
+
+
+
+ ← 客服团队 + / 跟进员 / 脚本行为 + scope-cs-001 · svc-followup-001 +
+
校验
+
▶ 测试
+
发布
+
保存
+
+
+
+ +
+
文件 3
+
+
FollowupBehavior.cs
+
入口文件
+
+
+
ReminderService.cs
+
+
+
models.proto
+
Proto 定义
+
+
+
+ 添加文件
+
+
+
草稿 v3
+
基于 v2 (已发布)
+
更新: 2 分钟前
+
+
+ + +
+
+
FollowupBehavior.cs
+
ReminderService.cs
+
+
+1public sealed class FollowupBehavior : +2 ScriptBehavior<FollowupReadModel, FollowupReadModel> +3{ +4 protected override void Configure( +5 IScriptBehaviorBuilder<...> builder) +6 { +7 builder +8 .OnCommand<ScheduleFollowup>(HandleSchedule) +9 .OnEvent<FollowupTriggered>(HandleTrigger) +10 .ProjectState(s => s); +11 } +12 +13 // 处理跟进调度命令 +14 private static Task HandleSchedule( +15 ScheduleFollowup cmd, +16 ScriptCommandContext<...> ctx, +17 CancellationToken ct) +18 { +19 // 创建延迟事件，24h 后触发 +20 ctx.ScheduleEvent( +21 new FollowupTriggered(cmd.CustomerId), +22 TimeSpan.FromHours(24)); +23 return Task.CompletedTask; +24 } +25} +
+
+ + +
+
+
脚本信息
+
诊断
+
+
+
+
脚本 ID
+
followup-behavior
+
+
+
版本
+
草稿 v3 基于 v2
+
+
+
入口类
+
FollowupBehavior
+
+
合约
+
+
输入类型
+
ScheduleFollowup
+
+
+
ReadModel
+
FollowupReadModel
+
+
操作
+
★ Ask AI
+
绑定到 Scope
+
+
+
+
+
+
+ + + + +
+Studio · 测试运行 — 执行追踪 +
+
+
☷
+
✎
+
◉
+
◆
+
+
▶
+
+
⚙
+
+
+
+ ← 客服团队 + / 处理专员 / 测试运行 +
+
▶ 重新运行
+
+
+ +
+ + 运行中 + 处理流程 · 已执行 4/6 步骤 · 耗时 2.8s + 输入: "企业版定价方案是什么？" +
+ +
+ +
+ + + + + + + +
+
data
+
retrieve_context
+
+
+
+
control
+
classify_intent
+
+
+
+
ai · llm_call
+
generate_pricing
+
+
+
+
ai · llm_call
+
generate_faq
+
+
+ + +
+
执行日志 4 个事件
+
+
14:32:07STARTEDretrieve_context · 获取客户上下文
+
14:32:07COMPLETEDretrieve_context · 上下文已加载 (customer_id=c-1234)
+
14:32:08COMPLETEDclassify_intent · 分类结果: pricing (confidence=0.94)
+
14:32:09STARTEDgenerate_pricing · 调用 gpt-5.4 · tokens_in=480...
+
+
+
+
+
+
+ +
+ + diff --git a/docs/designs/2026-04-08-studio-redesign.md b/docs/designs/2026-04-08-studio-redesign.md new file mode 100644 index 00000000..b5ba2c3b --- /dev/null +++ b/docs/designs/2026-04-08-studio-redesign.md @@ -0,0 +1,229 @@ +--- +title: "Studio 产品重构 — 团队构建器" +status: DRAFT +owner: CEO +--- + +# Studio 产品重构 — 团队构建器 + +Generated on 2026-04-08 +Repo: aevatarAI/aevatar +Related: [Console Web AI Teams 设计](2026-04-08-console-web-ai-teams.md) + +## 定位 + +Studio 是**团队构建器**。它针对 Scope（= Team）工作。用户在 Studio 里构建和打造整个团队：定义成员（workflow/scripting）、分配角色、配置集成、测试运行。 + +``` +Scope = Team +Studio = Scope 的编辑器 +∴ Studio = 团队构建器 +``` + +**在 Studio 中，用户可以**： +- 创建/编辑团队成员的行为定义（workflow 可视化编排） +- 编写脚本行为（C# scripting） +- 定义 Agent 角色（LLM prompt/model 配置） +- 配置集成（Telegram/HTTP/MCP 连接器） +- 测试运行整个团队的行为 + +**入口**： +- 团队详情页 → "高级编辑" Tab（进入当前 Scope 的 Studio） +- 团队成员表 → 单个成员的"编辑"链接（进入 Studio 并聚焦该成员的 workflow/script） +- "组建团队" → 进入空的 Studio 开始创建 + +## 当前状态 + +Studio 当前功能完整但缺乏产品语境： + +| 当前名称 | 功能 | 问题 | +|---------|------|------| +| Workflows | 工作流列表 | 没有"属于哪个团队"的上下文 | +| Studio (Editor) | XYFlow 可视化工作流编辑 | 独立页面，跟团队脱节 | +| Scripts | Monaco C# 脚本编辑器 | 同上 | +| Roles | LLM 角色定义（prompt/model） | 叫"Roles"用户不理解 | +| Connectors | 外部连接器（HTTP/CLI/MCP） | 同上 | +| Settings | 运行时和 Provider 配置 | 同上 | +| Executions | 执行追踪和回放 | 没有跟团队关联 | + +**核心问题**：Studio 作为独立页面存在，没有团队上下文。用户不知道自己在编辑"谁"。 + +## 重构方案 + +### 原则 + +1. **带上下文进入**：从团队/成员进入 Studio 时，自动加载该成员的 workflow/script +2. **术语重映射**：用团队语言重新包装，但不改底层功能 +3. **保留全部能力**：XYFlow 编辑器、Monaco 编辑器、角色管理、连接器管理、执行测试全部保留 +4. **不改底层代码**：只改导航入口和 UI 标签 + +### 术语重映射 + +| 当前 | 改为 | 原因 | +|------|------|------| +| Studio | 成员编辑器 / Agent Editor | 明确在编辑什么 | +| Workflows | 行为定义 | 工作流就是 agent 的行为逻辑 | +| Steps | 处理步骤 | 保留 | +| Roles | Agent 角色 | 每个 Role 定义一个 LLM 人格 | +| Connectors | 集成 / Integrations | 外部服务连接 | +| Executions | 测试运行 | 在编辑器内测试 agent 行为 | +| Settings | 编辑器设置 | 保留 | +| Scripts | 脚本行为 | C# 脚本定义 agent 行为 | + +### 导航结构（Studio 内部） + +从团队详情进入 Studio 后，Studio 内部保留独立的 Tab 导航： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ← 返回团队: 客服团队 [测试运行] [保存] │ +├─────────────────────────────────────────────────────────────┤ +│ 行为定义 │ 脚本行为 │ Agent 角色 │ 集成 │ 设置 │ +├─────────────┬───────────────────────────────────────────────┤ +│ 定义列表 │ XYFlow 画布 │ 属性面板 │ +│ ───────── │ ┌─────┐ ┌─────┐ │ ──────── │ +│ 接待流程 │ │step1│───→│step2│ │ 步骤类型: │ +│ 处理流程 ● │ └─────┘ └──┬──┘ │ llm_call │ +│ 跟进流程 │ │ │ 目标角色: │ +│ │ ┌───▼──┐ │ 处理专员 │ +│ │ │step3 │ │ 参数: │ +│ │ └──────┘ │ {...} │ +│ │ │ │ +│ [+ 新建] │ [自动布局] [缩放] [适应] │ [删除步骤] │ +└─────────────┴─────────────────────────────┴────────────────┘ +``` + +### 上下文传递 + +从团队详情进入 Studio 时传递： +- `scopeId` — 当前团队（Scope） +- `memberId` — 当前成员（GAgent Actor ID，可选） +- `workflowId` — 该成员绑定的 workflow（如果是 workflow 类型） +- `scriptId` — 该成员绑定的 script（如果是 scripting 类型） + +Studio 顶部显示上下文面包屑： +``` +← 客服团队 / 处理专员 / 行为定义 +``` + +### 页面详细设计 + +#### 1. 行为定义（Workflow Editor） + +**保留当前所有功能**： +- XYFlow 画布：步骤节点 + 连接边 +- 三栏布局：定义列表 | 画布 | 属性面板 +- 属性面板三 Tab：步骤属性 | Agent 角色 | YAML + +**改进**： +- 画布节点显示成员上下文（"此步骤由 处理专员 执行"） +- 步骤类型分类保留现有颜色编码： + - 蓝色: 数据（transform, assign） + - 紫色: 控制（guard, conditional, switch） + - 粉色: AI（llm_call, tool_call） + - 橙色: 组合（foreach, parallel） + - 绿色: 集成（connector_call, emit） + - 青色: 人工（human_input, human_approval） +- 执行状态覆盖：idle/active/waiting/completed/failed + +#### 2. 脚本行为（Scripts Editor） + +**保留当前所有功能**： +- Monaco C# 编辑器 + Proto 文件 +- 多文件支持（文件树） +- 实时诊断 +- AI 辅助生成（流式） +- Draft → Validate → Run → Promote 工作流 + +**改进**： +- 顶部显示"正在编辑: 跟进员 的脚本行为" +- 测试运行结果关联到成员的事件流 + +#### 3. Agent 角色（Roles） + +当前的 Role 定义就是 LLM 的人格配置： +- Role ID + Name +- System Prompt（核心：定义 agent 的行为指令） +- Provider + Model（选择 LLM） +- Connectors（可用的工具） + +**改进**： +- 重命名为"Agent 角色" +- 每个角色卡片显示关联的团队成员 +- 从团队成员表点击"编辑角色"直接跳到这里 + +#### 4. 集成（Connectors） + +三种连接器类型： +- **HTTP**：RESTful API 调用 +- **CLI**：命令行工具 +- **MCP**：Model Context Protocol 服务 + +**改进**： +- 重命名为"集成" +- 显示哪些团队成员使用了这个集成 +- Telegram connector 应该在这里可见（团队的外部连接） + +#### 5. 测试运行（Executions） + +**保留当前所有功能**： +- Draft Run 执行（SSE 流式） +- XYFlow 画布执行状态装饰（节点高亮、边高亮） +- 执行日志时间线 +- Human Input/Approval 交互 + +**改进**： +- 重命名为"测试运行" +- 测试结果与团队事件流关联 +- "在团队中查看"按钮跳回团队详情的事件流 Tab + +## 与团队详情的关系 + +``` +团队详情 (/teams/:scopeId) +├── 概览 Tab — SaaS 风格 +├── 事件拓扑 Tab — Platform 风格，只读查看 EventEnvelope 流转 +├── 事件流 Tab — Platform 风格，只读查看事件日志 +├── 成员 Tab — 表格，每个成员有"编辑"链接 +│ └── 编辑 → 进入 Studio（带 scopeId + workflowId/scriptId 上下文） +├── 连接器 Tab — 查看连接器绑定 +└── 高级编辑 Tab — 直接进入 Studio（带 scopeId 上下文） +``` + +**事件拓扑 vs Studio 画布**： +- 事件拓扑（团队详情）= 运行时视角，展示 EventEnvelope 在 agent 之间的实际流转 +- Studio 画布 = 定义时视角，展示 workflow 内部的步骤编排逻辑 +- 同样用 XYFlow，但数据源和语义不同 + +## 数据源 + +| 功能 | 现有 API | 文件 | +|------|---------|------| +| Workflow CRUD | `studioApi.*` | `src/shared/studio/api.ts` | +| Graph 构建 | `buildStudioGraphElements()` | `src/shared/studio/graph.ts` | +| 文档操作 | `insertStep*`, `connectStep*` 等 | `src/shared/studio/document.ts` | +| 执行流式 | `studioApi.startExecution()` (SSE) | `src/shared/studio/api.ts` | +| 脚本编辑 | `scriptsApi.*` | `src/shared/studio/scriptsApi.ts` | +| 角色 catalog | `studioApi.getRolesCatalog()` | `src/shared/studio/api.ts` | +| 连接器 catalog | `studioApi.getConnectorsCatalog()` | `src/shared/studio/api.ts` | + +**全部已有。** Studio 重构不需要新 API。 + +## 实施范围 + +**做**： +1. 术语替换（Workflows → 行为定义, Roles → Agent 角色, Connectors → 集成, Executions → 测试运行） +2. 从一级导航移除，改为从团队详情进入 +3. 顶部面包屑显示团队 + 成员上下文 +4. 进入时自动加载对应 scopeId 的 workflow/script + +**不做**： +- 不改 XYFlow 画布逻辑 +- 不改 Monaco 编辑器 +- 不改 API 层 +- 不改步骤类型系统 +- 不改执行/测试流程 + +## 预览 + +预览页面：[`2026-04-08-studio-redesign-preview.html`](2026-04-08-studio-redesign-preview.html)