# 客服工作台 WebUI 与 Evolva 竞品学习优化

- 日期：2026-08-04
- 状态：verified
- 优先级：P0/P1/P2
- 范围：generic
- 目标版本：`0.5.2` 后续开发基线（本轮未发布 npm）

## 目录

1. [来源](#来源)
2. [原始反馈归纳](#原始反馈归纳)
3. [竞品可借鉴能力](#竞品可借鉴能力)
4. [现状审计](#现状审计)
5. [实施计划](#实施计划)
6. [安全与产品决策](#安全与产品决策)
7. [验收清单](#验收清单)
8. [实施进度](#实施进度)

## 来源

- 客户反馈：`E:\新建文件夹\WXWork\1688855615758934\Cache\File\2026-08\20260804-webui-issue.md`
- Evolva 源码：[github.com/koppx/Evolva](https://github.com/koppx/Evolva)
- Evol 官网：[www.evolai.cn](https://www.evolai.cn/)

## 原始反馈归纳

1. 客户群和私聊会话应按最新消息稳定排序，便于快速找到刚收到消息的会话。
2. 新私聊联系人需要可配置地加入监听范围，而不是只能手动批量补采。
3. 新联系人可配置欢迎语，并避免重复发送。
4. 私聊详情需要“采集当前会话”，减少对白名单全部会话的无差别补采。
5. AI 监听默认开启，但用户人工关闭后不能被自动重新拉起。
6. 工作台顶部区域过高，主要会话区需要占满剩余视口，减少上下滚动。
7. Agent 工作台颜色需收敛到语义 CSS 变量，默认采用 Fmode 蓝紫与中性灰，并允许租户覆盖。

## 竞品可借鉴能力

### 借鉴

- 把聊天、工具、文件和任务状态放在统一工作空间，降低页面切换成本。
- 使用 `Plan -> Act -> Observe -> Evaluate -> Evolve` 表达 Agent 执行阶段。
- 工具活动日志可展开/收起，并显示状态、耗时、脱敏参数摘要、结果与失败。
- 支持会话续接、执行证据、checkpoint、artifact 和 metrics 等可恢复线索。
- 高风险工具操作具备一次、本会话、拒绝等清晰授权语义。

### 不照搬

- 不迁移 Evolva 的 Python/TUI 架构。
- 不新建与现有 `toolTrace`、审计或响应监控重复的数据存储。
- 底层没有可靠取消能力时，不展示虚假的取消按钮。
- 不把任意新联系人自动外发作为通用默认值。

## 现状审计

### 已具备，避免重复开发

- 私聊详情“采集当前会话”。
- 顶部“补采全部白名单”。
- AI 监听默认开启。
- 人工关闭监听后保持关闭。
- 群聊白名单拒绝与私聊白名单热更新基础能力。
- 群聊列表已有最新时间降序的基础逻辑。

### 已确认缺陷

- 私聊数据库查询虽按时间降序，但服务层重算公开展示时间后没有再次排序，实际大量会话存在错序。
- 群聊排序缺少“空时间末尾”和“相同时间稳定排序”的明确规则。
- Agent 工作台顶部信息区过高，主体不能稳定占满首屏。
- Agent 区域仍存在橙色根品牌变量和较多硬编码绿色，租户主题难以统一覆盖。

## 实施计划

### P0：工作台布局、排序和主题

- [x] 压缩顶部为 sticky 命令栏，只保留账号、在线/监听状态、全局模式、白名单数、待回复数和关键操作。
- [x] 将设置和提醒移入抽屉，三栏工作台使用 `100dvh`/`calc()` 占满剩余视口并独立滚动。
- [x] 私聊和群聊都采用最新消息降序、空时间末尾、相同时间稳定的规则。
- [x] 未回复/超时仅作为状态标识，不改变最新消息主排序。
- [x] Agent 工作台改用品牌、页面、面板、文字、边框、focus、success、warning、error 等语义 token。
- [x] 默认 Fmode 蓝紫 + 中性灰，租户通过 `data-theme` 或变量覆盖；不机械重写全站颜色。

### P1：新联系人接入与欢迎语

- [x] Workbench settings 作为运行真源。
- [x] 新增 `GET/POST /api/agent/intake-policy`。
- [x] 固定字段：`mode`、`welcomeEnabled`、`welcomeText`、`welcomeSendMode`。
- [x] 模式：`allowlist_only`、`auto_enroll_review`、`auto_enroll_autopilot`。
- [x] `auto_enroll_review` 强制会话为 review，不继承全局 autopilot。
- [x] `auto_enroll_autopilot` 必须由管理员显式选择并二次确认。
- [x] 未知群聊继续拒绝；仅通过群聊校验后的未知私聊可按策略纳入。
- [x] 欢迎语按账号 + 联系人幂等，失败状态可重试并保留审计。

### P2：活动与工具轨迹

- [x] 右侧洞察区增加可折叠活动轨迹。
- [x] 复用现有 tool trace、audit 和 response monitor。
- [x] 展示阶段、工具名、状态、耗时、脱敏参数摘要、结果、失败、重试和审计入口。
- [x] 仅在底层真实支持时开放取消/重试；否则保留已有 regenerate 能力。

### 迁移与仓库治理

- [x] 业务安装副本先验证，再把等价通用能力同步到通用技能包。
- [x] 当前任务验收完成后，把通用技能包迁入 `E:\workspace\QIWEI-skill`。
- [x] 迁移时保留本仓库 `.git` 和 `todolist/`，禁止整包覆盖。
- [x] 不迁入房源 Provider、小牛默认值、真实房源数据、凭据、`.env.local`、outputs、数据库、Session、日志或 `node_modules`。

## 安全与产品决策

| 场景 | 通用默认 | 约束 |
| --- | --- | --- |
| 未知私聊 | `allowlist_only`，忽略 | 不创建会话、不写消息、不外发 |
| 自动纳入审核 | `auto_enroll_review` | 只生成草稿，强制 review |
| 自动纳入自动回复 | 默认关闭 | 管理员二次确认后才允许 |
| 高置信自动 | `auto` | 仅达到置信度阈值且无需人工时发送 |
| 全自动接管 | `autopilot`，默认关闭 | 当前账号白名单私聊；全局/单会话固定二次确认；非空回复直接发送且不创建草稿 |
| 未知群聊 | 拒绝 | 不因私聊接入策略放宽 |
| 欢迎语 | draft/review | 账号 + 联系人幂等，失败可重试 |
| 人工关闭监听 | 保持关闭 | 后台启动不得覆盖人工选择 |
| 工具参数 | 脱敏 | UI、日志和审计均不显示凭据 |

## 验收清单

### 功能和安全

- [x] 私聊最新消息排序：含空时间末尾和相同时间稳定性。
- [x] 群聊最新消息排序：含空时间末尾和相同时间稳定性。
- [x] strict/allowlist 模式未知联系人仍被忽略。
- [x] `auto_enroll_review` 新私聊只生成草稿，不自动外发。
- [x] 未知群聊不被自动纳入。
- [x] 欢迎语一次性、重启幂等、失败可重试。
- [x] 人工关闭监听后不会被自动拉起。
- [x] 活动轨迹参数和结果已脱敏。
- [x] `auto` 与 `autopilot` 已分离；全自动接管直接发送且不创建待审草稿。
- [x] 全自动接管失败保留审计，旧数据库可幂等迁移。
- [x] 全局、单会话和新联系人全自动接入均需固定二次确认。

### UI

- [x] 1440x900 首屏可完成主要会话操作，无页面级上下拖动。
- [x] 1280x720 无重叠、按钮文字不溢出、三栏稳定。
- [x] 390x844 移动端无重叠且主要操作可达。
- [x] 设置/提醒抽屉与活动轨迹可正常展开收起。
- [x] 默认主题和租户变量覆盖均通过截图检查。

### 包与发布

- [x] 业务安装副本 `node --check`、agent/runtime/preview/package/property smoke 通过。
- [x] 通用包 `node --check`、agent/runtime/preview/package smoke 通过。
- [x] Playwright 截图与 DOM 尺寸记录齐全。
- [x] 独立仓库迁移后敏感信息扫描为 0。
- [x] 独立仓库完整测试通过并提交 `master`。
- [x] 本轮未发布 npm。

## 实施进度

| 节点 | 状态 | 当前结果 |
| --- | --- | --- |
| A 现状审计 | verified | 已确认复用能力、私聊错序根因、群聊稳定排序缺口、API 字段和安全模式 |
| B P0 实施 | verified | sticky 命令栏、抽屉、`100dvh` 三栏、语义主题和三视口布局均通过 |
| C P1/P2 实施 | verified | 三种接入策略、欢迎语幂等/重试、活动轨迹和账号隔离均通过 |
| D 联调复核 | verified | 业务版 20 Skills/98 Tools/215 entries；通用版 18 Skills/95 Tools/196 entries，完整矩阵通过 |
| E 独立仓库迁移 | verified | 通用包已迁入仓库根目录并直接提交 `master`；业务资产、凭据和运行输出均排除 |

### 2026-08-04 实施日志

- 独立仓库和 `todolist/` 基线已建立并推送 `master`，提交 `c463bbb`。
- P0/P1 实施过程中执行节点出现临时 503；已落盘修改保留，未回滚或重复开发。
- 当前语法检查通过，排序专项在业务副本和通用包分别通过 6/6。
- 通用包已完成排序、策略、DB、UI/API、Skill 和测试的字段级同步；业务专属房源链路未迁入。

### 2026-08-04 完成记录

- 账号隔离：A 账号手动白名单不进入 B，B 自动纳入不进入 A，切回 A 保留原状态；监听开关仅作用当前账号。
- 接入策略：通用默认 `allowlist_only`；`auto_enroll_review` 只生成草稿；自动回复模式要求固定二次确认；未知群聊始终拒绝。
- UI：1440x900、1280x720、390x844 无页面横向溢出、按钮溢出或会话子节点重叠；移动端设置抽屉边界为 `0,68,390,844`。
- 通用版：Agent 48、接入 5、排序 6、UI 11、Runtime 25、Preview 5 全部通过；`release:check` 18 组通过，npm 包为 18 Skills / 95 Tools / 196 entries。
- 业务版：Agent 40、接入 7、排序 6、UI 9、Runtime 25、Preview 5、房源专项全部通过，npm 包为 20 Skills / 98 Tools / 215 entries。
- 通用版已删除房源 Skill、房源数据、房源 API/UI、默认房地产画像字段与测试语料；业务安装副本继续保留业务能力。
- npm 保持 `0.5.2`，本轮只迁移源码仓库，未执行 `npm publish`。
- 私聊模式现为 `review`、`auto`、`autopilot`、`human`、`paused`；`autopilot` 已完成直发、失败审计、旧库迁移、接入策略映射与固定确认门禁。
- 真实浏览器复核 1440x900、1280x720、390x844 均无页面横向溢出或按钮文字溢出；全自动确认框可正常打开和取消。