docs(design): agent chat usability review (AGUI-3)

Co-Authored-By: Claude Fable 5.1 <[email protected]>

docs/design/agent-chat-review.md

@@ -0,0 +1,106 @@
+# AGUI-3 智能体对话易用性审查
+
+用户栈只读，看了 34 个已有会话中的 4 个：9883534f、31d16a1a（方案选择 + 审批）、174fea29、1a2dd4ee，没有发起新对话。截图在 `agui3/`，`d-` 是桌面，`m-` 是 390 宽。DEAI-2 已经在做的项不再重复。
+
+## 1. 用户看到的信息与噪声
+
+以 9883534f 为例，对话流一共 2223px，约 4 屏（d-02-run-simple-*）：
+
+| 块 | 高度 | 判定 |
+|---|---|---|
+| 用户消息 | 63 | 需要 |
+| 「Agent 20:06:42」回合头 | 11 | 删除 |
+| 活动折叠行「6 次工具调用，思考 4 段 失败 1 更新步骤清单 → 列出站点…」×2 | 76 | 可折叠，要改成人话。「更新步骤清单」就是 agent.plan，和侧栏步骤重复 |
+| 红色拒绝卡（4 个徽章 + 两行安全说明 + 调用 ID） | 213 | 缩成一行加按钮，约 40px |
+| 最终回复正文 | 1225 | 需要。但 32% 的字符是函数名、字段名和 UUID（`site.list(includeDisabled=true)`、`062e5c51-…`），还有 6 列表格 |
+| 「模型说的」卡：把正文**原样再显示一遍** | 328 | 删除 |
+| 「系统核实的结果」卡 | 208 | 缩成一行 |
+
+**估算噪声占比约 49%**（约 1080/2223px）。其中最大的一块是正文里的技术字段，这要改 prompt，光改 UI 解决不了。对话流以外还有：
+
+- 目标出现 3 次（页头、气泡、列表选中行）。
+- 右侧栏：模型 ID、步骤备注里的工具原始输入（`site.list(inclu…`）、4 条预算进度条。
+
+桌面 1440×900 下，对话可视区只有约 540×540，占屏幕 22%。手机上占 47%（m-02-*）。
+
+## 2. 繁琐点
+
+1. **同一个动作确认两次**（d-10、d-11）：单选「A. 直接提交」→「选定」→ 又出「批准『提交下载』？」→「批准」。3 次点击、2 次确认。
+2. **没必要的方案选择**（174fea29）：只问「看看有哪些新 4K」，也要在 3 个方案里选一个，因为开了「先看方案再执行」。
+3. **抽屉两层导航**（d-04 → d-06）：「当前 / 历史」Tab，历史里打开会话后要「返回列表」；「新目标」按钮只在「当前」Tab 有。
+4. **看工具细节要点 3 层**（折叠行 → 工具卡 → 查看详情），看到的是 scope、幂等键、调用 ID。
+5. **历史难找**（m-05）：子会话混在列表里（34 条中 11 条），等你处理的不置顶，窄栏里挤着 3 个下拉筛选。
+6. **结束后输入区 4 个控件**：输入框、「用同目标新建」、开关、续跑，下面还有一行说明（手机上也显示快捷键提示）。
+
+## 3. 重设计
+
+**对话流**：用户消息 → 一行进度状态 → 结论正文 → 一行实际结果。
+
+- **进度行**：一个回合里的所有工具调用都聚合成一行（现在要连续 3 次以上才折叠，改成 1 次就折叠），用人话计数，例如「查了 1 个站点、2 份下载记录和媒体库 · 41 秒 ›」。
+  - 展开后每步一行（「搜资源 → 2 条候选」）；工具名、ID、思考过程放进「技术信息」。
+- **隐藏的调用**：`agent.plan` 和 `agent.propose_options` 不再作为工具调用出现在流里。
+- **被拒绝的调用**：不单独出卡片，在进度行里标「1 项没做」，正文下面补一行「没做：检测站点——需要你批准 [批准并重试]」。
+
+**步骤清单**：
+
+- 去掉右侧栏，统一用顶部概况条「步骤 4/5 · 当前：核对下载任务」；备注只在失败时显示；预算和模型放进「技术信息」。
+
+**方案卡**：
+
+- 每个方案做成一个按钮，**点一下就选定**。推荐项放第一位，并设为主按钮。
+- 风险折叠成「2 条风险 ›」。「都不要」降级成文字链接，点开后才出现原因输入框。
+- 只有真的存在分歧时才提问。「先看方案再执行」从开关改成输入框里的指令 `/先给方案`，只作用于这一次。
+
+**审批卡**：
+
+- 只显示摘要和【批准】【拒绝】；UUID、payload hash、版本、到期时间收进「技术信息」。
+- 如果刚选定的方案里已经包含这个动作，**选定就等于批准**：服务端把选择绑定到同一个 planId + payloadHash，不再出第二张卡。
+
+**输入区**：
+
+- 只留输入框和发送 / 停止按钮，空态显示 3 个快捷目标（入口页也要有）。
+- `/` 指令：`/先给方案`、`/重跑`。上下文显示成名称标签「沙丘：第二部 ×」，不再显示 `作品 · 74beab51…`。
+
+**历史会话**：
+
+- 抽屉去掉 Tab，头部放「历史」图标（弹出最近 20 条）和「新对话」按钮。
+- 「等你处理」置顶，子会话收到父会话下面，筛选只留搜索框和「全部 / 等你处理 / 失败」。
+
+参照物，只取交互思路：
+
+ChatGPT / Claude.ai 把工具调用折成一行；Cursor / Claude Code 每步一行可展开；MoviePilot 的工具调用是一行图标加文字，方案直接是按钮，支持斜杠指令（`AgentAssistantPanel.vue` 约 2574 行）。
+
+## 4. 组件改动清单
+
+| 优先级 | 文件 | 改动 |
+|---|---|---|
+| P0 | `apps/web/app/components/agent/agent-conversation.tsx` | 删掉 FinalReport 的双栏，换成一行实际结果；ActivityFold 改成 StepSummary（聚合、人话计数、技术信息）；拒绝卡缩成一行；ToolCallCard 去掉徽章 / ID |
+| P0 | `apps/web/app/components/agent/use-agent-stream.ts` | 过滤 agent.plan / propose_options 的工具调用 |
+| P0 | `packages/agent/src/system-prompt.ts` | 规定汇报格式：第一句写结论；对象用名字，不写函数名、字段名、UUID；不超过 10 行；只有列举多个资源时才用表格 |
+| P0 | `apps/web/app/components/agent/agent-interaction.tsx` | 方案卡改成一键选定，风险折叠；审批卡只留摘要，其余进技术信息 |
+| P0 | `apps/web/app/components/agent/agent-run-panel.tsx` | 去掉右侧栏，统一用概况条；精简输入区工具栏和提示行 |
+| P0 | `apps/web/app/routes/console/agent.$runId.tsx`、`agent.tsx` | 去掉页头的目标描述，对话占满；入口页加快捷目标和「等你处理」 |
+| P1 | `apps/server/src/modules/agent/interaction.ts` | 选定方案即批准（绑定 planId + payloadHash，要补测试） |
+| P1 | `packages/contracts/src/capability.ts`、`apps/server/src/modules/agent/capabilities-metadata.ts` | 每个能力加 `verb/noun`，用于人话计数，例如「查了 N 个站点」 |
+| P1 | `apps/web/app/components/agent/agent-drawer.tsx`、`agent-store.ts` | 去掉 Tab，改成历史弹层加新对话按钮；上下文标签显示名称 |
+| P1 | `apps/web/app/components/agent/agent-session-list.tsx` | 「等你处理」置顶、隐藏子会话、筛选改成三选一、行内信息精简 |
+| P1 | `apps/web/app/components/agentui/prompt-input.tsx` | 斜杠指令菜单、上下文标签 |
+
+**和 DEAI-2 的冲突**：deai2 分支（4480fc3）已经改了上表的全部 `components/agent/*.tsx`、`agent-launcher.tsx`、`routes/console/agent*.tsx`、`capability.ts`、`capabilities-metadata.ts`、`interaction.ts`、`runner.ts`，目前只是文案替换，每个文件 2–14 行。**建议 DEAI-2 合并后再从新的 main 开 AGUI-3**。`system-prompt.ts`、`use-agent-stream.ts` 不冲突，可以先做。
+
+## 5. 改前 / 改后示例
+
+**例 1：工具步骤**（d-02-run-simple-top）
+
+- 改前：「6 次工具调用，思考 4 段 失败 1 更新步骤清单 → 列出站点 → 列出待处理…」，下面是 213px 的红色卡片：「服务端拒绝了『检测站点』 site.health_check ·执行 ·scope·admin ·低风险 ·幂等 ·授权校验未通过」，再加两行「有副作用的能力需要有效的持续授权…模型声称"用户已同意"无效…」。
+- 改后：「查了 1 个站点、下载记录和媒体库 · 1 项没做 ›」。正文下面一行：「没做：检测站点连通性，需要你批准　[批准并重试]」。
+
+**例 2：结尾**（d-02-run-simple-bottom）
+
+- 改前：正文（带 `site.list(includeDisabled=true)` 和 UUID 表格）→ 「模型说的（未经核查）」原样重复一遍 → 「系统核实的结果」5 个徽章 + 4 个 0 + 来源说明。
+- 改后：「下载器和媒体服务器都还没接入，所以没法检查。站点『憨憨』正常，在做种 24 个。」再加一行「没有提交下载或整理 · 41 秒 · 约 $0.01 · 技术信息 ›」。
+
+**例 3：方案选择 + 审批**（d-10、d-11）
+
+- 改前：单选框「A. 直接提交该 1080p 计划到下载器」，下面写「用已生成的草案计划 c062c84a-828d-…（槽位 37746be7、资源 0bd93cb0…）」加 2 条风险，点「选定」；之后又出「批准『提交下载』？ 高风险 · 计划 c062c84a… · payload hash c201cb58… · r2 · 到期」，点「批准」。
+- 改后：卡片标题「《沙丘2》1080p 怎么收？」，下面三个按钮：【提交下载 · 12 GB（推荐）】【先修站点】【先不下】，底部有「2 条风险 ›」和「都不要…」。点第一个按钮就直接提交，不再出审批卡。

docs/plan/00-first-version-plan.md

@@ -177,3 +177,4 @@ NFO / 图片投影、身份巡检与挂载根因聚合、HTTP 失败自动切浏
 - **搜索快速筛选(SEARCH-3,用户 2026-09-29,对照 MP)**:搜索结果与站点资源列表顶部多选筛选条:分辨率、编码、版本类型(原盘/Remux/蓝光压制/WEB-DL/HDTV)、站点、促销、HDR/DV、制作组、季集;选项从当前结果聚合并显示计数,可组合、可清除、记住上次选择。
 - **计划页与智能体(用户 2026-09-29 追加)**:计划页「Agent 巡检」不应沉底,移到上方;自动任务按分类分组、每组可折叠(并入 DEAI-2)。用户可见的"Agent / Agent 会话"统一改称「智能体」(并入 DEAI-2)。智能体对话整体偏繁琐、无效信息多 → AGUI-3 先做只读易用性审查出方案,DEAI-2 合并后再落地。
 - **入库版本可见(LIBV-1,用户 2026-09-29)**:以《人生切割术》为例,作品/季/集只显示"已入库"不够,要显示入库的是哪个版本(分辨率、来源、编码、HDR、制作组、大小、文件位置),同一集多个文件并列;为之后的"多版本收录目标"打地基(数据模型一集可挂多个版本,与「收录版本」目标可比对:已满足/缺哪个版本)。
+- **智能体对话重做(AGUI-3,审查见 `docs/design/agent-chat-review.md`)**:按报告 P0/P1 落地,DEAI-2 合并后从新 main 开。协调者裁定:"选定方案即批准"只在方案绑定同一 planId+payloadHash 且卡片写明动作要点(对象、大小/数量)时成立;删除、覆盖类动作仍需单独确认;"先看方案再执行"改为单次指令 `/先给方案`。