wehub-resource-sync
12 KiB
团队运行体验优化 · PRD
本次聚焦「创建团队之后、在团队详情页协作」的体验，不改团队的创建流程。目标是让用户在多成员并行协作时，能一眼分清谁是谁、清楚当前在跟谁对话、并在团队初始化期间得到明确的引导而非静默卡顿。
全部改动限定在渲染层（前端），不改动 aioncore 后端与团队数据结构。涉及的持久化一律走浏览器本地存储（localStorage），不落库。
写在前面
名词
- 成员实例（slot）：团队里的一个成员位，以
slot_id唯一标识。同一个助手可以被拉进团队多次，每次是一个独立的成员实例（不同slot_id），各自拥有独立会话。 - Leader：团队里
role === 'leader'的成员，恒为成员列表第一个，不可移除、不可拖拽。 - 身份色：团队详情页里为区分成员而临时赋予的颜色，仅在团队详情页生效。
- Warmup：进入团队后，后端拉起各成员运行时 + 注入协作环境（MCP）的初始化阶段。
设计基调
- 配色取自 AionUi 既有 token（品牌色
#7583b2及其低饱和邻近色系），冷静不扎眼。 - 颜色只作「身份标识」，不做整格彩底，保持界面灰白干净的基调。
1. 成员身份色系统
想解决的问题
多成员并行、且同一助手可被拉多次时，用户看着并排的多列会话 / 多条 teammate 消息，分不清「这条到底是哪一个成员实例发的」。
方案
为每个成员实例分配一个身份色，一致地用于三处：
- 顶部成员胶囊的浅底色；
- 该成员消息气泡的左侧色条 + 彩色发送者名（不做整格彩底）；
- 选中该成员时，其对话列的四周色边 border + 列头淡底。
不作用于头像——头像保持原样（整图圆形，不加描边、不换底色）。
分配与稳定性规则
- 身份色按一套固定顺序色板从左到右分配。
- 颜色绑定成员实例（slot_id），一经分配即钉死：其他成员的新增 / 删除 / 重排都不改变一个成员已有的颜色。
- 新增成员：追加到列表末尾，取一个当前未被占用的颜色（优先复用被移除成员释放出的颜色）。
- 移除成员：释放其颜色，不影响其余成员。
- 色板准备较多的舒适色，尽量覆盖常见团队规模；成员数超出色板时循环复用。
边界
- 身份色是纯展示辅助，不是业务数据；仅团队详情页使用，团队之外（左侧列表、设置里的助手等）不受影响。
2. 顶部成员列表
想解决的问题
现有顶部 tab 形态区分度弱、操作隐蔽；成员多到超出时用户不易发现可以横向查看更多，也就找不到末尾的添加入口。
方案
- 成员呈现为横向单行胶囊（省纵向空间，把高度留给对话面板）：头像 + 名称 + 状态点 + 身份色浅底。
- 选中态明显：选中胶囊身份色底加深 + 一圈身份色 border；对应对话列四周色边 + 列头淡底；未选中的列降饱和以聚焦当前对话。
- 成员操作 hover 才出现：hover 胶囊时显示重命名 / 移除的小图标，平时不占位、不杂乱。
- 点击胶囊 = 切换到该成员（选中态，见第 3 节）。
- 横向滚动：成员超出宽度时列表横向滚动，两侧以渐隐提示「还有更多」。
- 添加成员入口固定可见：见第 5 节。
3. 选中与高亮
想解决的问题
当前选中态只有一条细线，太弱，一眼看不出「现在选中的是谁、正在跟谁对话」。
方案
- 选中态载体：成员胶囊高亮（身份色底加深 + border）+ 对应对话列四周身份色 border + 列头身份色淡底；其余列降饱和。
- 默认选中：进入团队默认选中 Leader（列表第一个）。
- 选中态共享：并行视图与单聊视图共用同一份选中状态（当前成员），两视图切换时保持连贯。
- 选中成员被移除：自动回退到 Leader。
4. 协作视图：并行 / 单聊
想解决的问题
成员多时并排列会被压窄；用户有时只想专注跟某一个成员（尤其 Leader）对话、有时想纵览全员。
方案
提供两个可切换的视图，切换控件位于标题行右侧：
- 并行视图（默认）：所有成员对话列并排。
- 单聊视图：全屏显示当前选中的成员对话。单聊 + 切换成员 = 切换全屏对象。
持久化与边界
- 视图是团队整体的属性 → 按团队记忆：key
team-view-mode-${team_id}，各团队各自记住上次视图；默认并行。 - 单聊视图下当前成员被移除 → 回退到 Leader，仍留在单聊视图。
- Warmup 期间允许切换视图（纯前端布局变化，不改团队状态）。
5. 添加成员入口与「找 Leader 拉人」引导
想解决的问题
- 添加入口藏在滚动列表末尾，成员多时用户不知道右滑能看到它。
- 一个显眼的「添加成员」按钮会隐性传递「加人只有 GUI 这一条路」，而实际上更强的能力是：直接让 Leader 帮忙安排，尤其当现有助手都不合适时。
方案
- 添加入口固定在成员栏最右侧（虚线胶囊样式，与实心成员胶囊形成「实=已有 / 虚=可加」对照），不随成员列表滚动，永远可见。
- 点击展开助手选择下拉（复用现有的助手选择器：搜索 + 列表，选中即关，助手随即出现在成员列表——即「加成功」反馈）。
- 下拉底部常驻一句引导：
没有合适的？也可以直接让 Leader 帮你安排。告诉 Leader →
- 点击「告诉 Leader →」：切换到 Leader 会话（单聊全屏 Leader），并在输入框预填「帮我在团队里加一个擅长 ___ 的成员」，不自动发送，光标定位让用户补全后自行发出。
- 不做空状态——用户一定有可添加的助手。
6. Leader 问候语
想解决的问题
新建团队进入 Leader 会话时，空状态没有明确的自我介绍，用户不清楚 Leader 是什么、能做什么。
方案
改现有 Leader 空状态：把问候语显示为
你好，我是 Leader，负责理解你的目标并协调团队。描述你想做的事，我来安排。
替换现有的 subtitle 文案，保留下方已有的 3 个提示词快捷卡片。纯前端文案改动（走 i18n）。
7. Warmup 初始化状态
想解决的问题
进入团队时后端在拉起成员运行时、注入协作环境，这段时间现在是静默禁用若干操作，没有任何反馈，用户只觉得「卡了一下」，还可能去做无效操作（发消息、加成员）。
方案
进度表现：整界面磨砂遮罩 + 成员头像从左到右逐个「点亮」（Leader 先亮）+「唤醒中 N/M」文案 + 品牌色进度条，呼应 App 既有的柔和光晕元素。
结束闸门 = Leader ready：
- 遮罩在 Leader 运行时就绪时即撤除，不等全体成员——用户进团队第一件事是跟 Leader 说目标，Leader 一好就能开工。
- 这也从根本上规避「一个成员起不来就卡死整个团队」：某个 teammate 还在初始化或失败，不阻塞用户开始使用。
遮罩期间禁止的行为：添加成员、移除成员、重命名成员、发消息（遮罩盖住输入区，天然禁用）。
遮罩期间允许的行为：切换视图、切换 / 浏览成员、滚动。
失败与超时兜底：
- 某 teammate 失败：遮罩早已撤除（Leader 已好），该成员在自己的胶囊 / 列上显示「启动失败 · 可重试」，不影响其他成员。
- Leader 失败：遮罩转为错误态（重试 / 返回），不无限转圈。
- 超时兜底：Leader 在超时时限内仍未就绪，遮罩转为错误态（准备超时，重试 / 返回），防止后端未发事件等极端情况下无限等待。
技术前置确认
本方案依赖「前端能单独判断 Leader 的运行时就绪信号」（而非只有当前的全员聚合忙碌标志）。实现前需在代码中确认该信号可从现有运行时状态事件（带 slot_id）中取到；确认后方案成立，仍为纯前端。
8. 后续单独专题（不在本次范围）
- 全 App 头像容器统一：现状各处头像的容器形状 / 尺寸 / 背景不一致，期望统一为左侧对话列表那种圆形头像。本次团队优化不做，后续单独拉专题梳理全 App 头像现状后统一。
- 确认型弹窗轻量统一：删除助手 / 删除技能 / 工作区重命名删除 / 粘贴确认 / 关闭预览等确认弹窗保持轻量，作为独立线后续处理。
附录 A：前端技术方案
A.1 存储与状态归属
| 状态 | 归属 | 存储位置 |
|---|---|---|
| 视图模式（并行/单聊） | 团队整体 | localStorage: team-view-mode-${team_id} |
| 成员身份色映射 | 成员实例 | localStorage: team-member-colors-${team_id}，内容为 { slot_id: colorIndex } |
| 当前选中成员 | 团队整体 | 复用现有 team-active-slot-${team_id} |
| 成员排序 | 团队整体 | 复用现有 team-assistant-order-${team_id} |
身份色映射与视图模式均复用现有 TeamTabsProvider（已是每团队一实例，已有按 team_id 分键的 localStorage 先例：active-slot、assistant-order）。
A.2 身份色分配逻辑
- 维护
{ slot_id → colorIndex }映射（内存 + localStorage 持久化）。 - 渲染成员时：已有映射的直接取色；新出现的 slot 取「当前未占用的最小色号」（优先复用被移除释放的色号），写入映射。
- 移除成员：从映射删除该 slot，释放色号。
- 超出色板容量：色号对色板长度取模循环。
- 色板取 AionUi 品牌 slate 邻近的低饱和色，Leader 固定用品牌主色。
A.3 视图切换
- 复用现有
fullscreenSlotId的单列全屏能力，升级为显式、按团队持久化的viewMode状态。 - 单聊显示当前
activeSlotId对应成员；两视图共享activeSlotId。
A.4 Warmup 状态机
- 现有
membershipMutationBusy是「是否有成员 runtime pending 或 MCP 注入中」的聚合布尔值，不区分 Leader。 - 新增：从运行时状态事件（
agentRuntimeStatusChanged，带slot_id）中单独取 Leader 的就绪状态，作为撤遮罩闸门（实现前先确认该粒度可取）。 - teammate 级失败状态映射到各自胶囊 / 列的表现；不参与撤遮罩判断。
- 超时兜底：进入团队后启动计时，Leader 超时未就绪则进入错误态。
A.5 「告诉 Leader」
- 切换
activeSlotId到 Leader + 视图切单聊 + 向 Leader 会话的输入框预填提示词（复用现有 send box 预填能力，不自动发送）。
A.6 i18n
本次新增 / 改动的文案（多语言）：视图切换标签、warmup 各态文案（唤醒中 / 准备超时 / 启动失败 · 重试）、「找 Leader 拉人」引导句、Leader 问候语。均新增 key 并覆盖各 locale。
附录 B：实施阶段建议
| 阶段 | 内容 | 独立验收点 |
|---|---|---|
| 1 | 身份色系统 + 胶囊成员栏 + 气泡区分 + 选中态高亮 | 多成员下颜色区分清晰、选中态明显、增删成员颜色稳定 |
| 2 | 并行 / 单聊视图切换（按团队记忆） | 两视图切换连贯、按团队记忆、选中态共享 |
| 3 | Warmup loading 态 + 禁用清单 + 失败/超时兜底 | Leader 就绪即可用、失败不卡死、超时有兜底 |
| 4 | 添加成员虚线胶囊 + 「找 Leader 拉人」引导 + Leader 问候语 | 入口常驻可见、引导可切 Leader 预填、问候语到位 |
每阶段完成后起 dev 自测（白盒 + 黑盒 + 类型 + lint 全绿）并交产品验收，验收通过后按聚焦提交。