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

- 日期：2026-08-04
- 状态：in-progress
- 优先级：P0/P1/P2
- 范围：generic
- 目标版本：待实施验收后确定

## 目录

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：工作台布局、排序和主题

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

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

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

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

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

### 迁移与仓库治理

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

## 安全与产品决策

| 场景 | 通用默认 | 约束 |
| --- | --- | --- |
| 未知私聊 | `allowlist_only`，忽略 | 不创建会话、不写消息、不外发 |
| 自动纳入审核 | `auto_enroll_review` | 只生成草稿，强制 review |
| 自动纳入自动回复 | 默认关闭 | 管理员二次确认后才允许 |
| 未知群聊 | 拒绝 | 不因私聊接入策略放宽 |
| 欢迎语 | draft/review | 账号 + 联系人幂等，失败可重试 |
| 人工关闭监听 | 保持关闭 | 后台启动不得覆盖人工选择 |
| 工具参数 | 脱敏 | UI、日志和审计均不显示凭据 |

## 验收清单

### 功能和安全

- [ ] 私聊最新消息排序：含空时间末尾和相同时间稳定性。
- [ ] 群聊最新消息排序：含空时间末尾和相同时间稳定性。
- [ ] strict/allowlist 模式未知联系人仍被忽略。
- [ ] `auto_enroll_review` 新私聊只生成草稿，不自动外发。
- [ ] 未知群聊不被自动纳入。
- [ ] 欢迎语一次性、重启幂等、失败可重试。
- [ ] 人工关闭监听后不会被自动拉起。
- [ ] 活动轨迹参数和结果已脱敏。

### UI

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

### 包与发布

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

## 实施进度

| 节点 | 状态 | 当前结果 |
| --- | --- | --- |
| A 现状审计 | verified | 已确认复用能力、私聊错序根因、群聊稳定排序缺口、API 字段和安全模式 |
| B P0 实施 | in-progress | 业务 `app.js`、两份 DB 与 poller policy 语法通过；业务/通用排序专项均 6/6；布局、主题与三视口验收继续进行 |
| C P1/P2 实施 | in-progress | 接入策略、欢迎语、轨迹与安全回归进行中 |
| D 联调复核 | blocked | 等待 B/C 完成后执行 |
| E 独立仓库迁移 | triaged | 待通用包验收后迁入并推送 master |

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

- 独立仓库和 `todolist/` 基线已建立并推送 `master`，提交 `c463bbb`。
- P0/P1 实施过程中执行节点出现临时 503；已落盘修改保留，未回滚或重复开发。
- 当前语法检查通过，排序专项在业务副本和通用包分别通过 6/6。
- 当前通用包只同步排序、策略和 DB 底层；UI/API/Skill/测试待业务专项通过后再按通用边界同步。