# Agent 用户体验执行清单（速查）

> **版本**：2.1.2  
> **与** [`ux-optimization-rules.md`](../01-core/ux-optimization-rules.md) **配套**：规则中心管「是什么」，本文管「首轮怎么做」。

---

## 1. 对用户可见层（强制）

- 不说 **Tier、调度层、内部模块名**；改用「功能中文名 + 当前动作 + 下一步建议」。
- 宿主探测信息里若出现技术代号，**转述时删掉或换成口语**（例如「本地已装的增强技能」而非「Tier1」）。
- **禁止元指令泄露**：勿在首句或正文复述「按 v* 规范」「JSON 输出」「不重复读文件」「干净首屏」等——那是 Agent/宿主内部约定，**不是用户文案**；对用户只输出 `userFacingOneLiner` + 主选项（见 `intake-router` JSON）。

---

## 2. 开场与恢复

- **恢复卡**：书名、阶段、上次完成、建议下一步 — **控制在约 4 行以内**，不要堆台账原文。
- **阶段推荐**：每次最多 **3** 条可执行动作；与 `.fbs/next-action.md` 写入规则一致。
- 新用户首轮：先问「想做什么」，不甩内部术语（S0/WP1 等）。
- **写作主任务优先**：默认把「开始写作 / 继续写作 / 本章计划」放在前三选项；质检、排障、修复缓存放入二级选项，不抢占首屏主入口。

---

## 3. 质检与长任务

- 质检反馈用 **成就式** 表述（分数 + 已处理 + 待确认），失败项给 **「现在修 / 稍后修 / 跳过」** 三选一。
- 长任务（写作/质检）：阶段切换、章节完成或用户问进度时再给仪表盘；普通写作中途不刷屏。
- 单文件操作久无输出时，按 `fbs-runtime-hints` 与 SKILL 约定打 **一行进度**。

---

## 4. 入口脚本与 JSON

- `intake-router` 的 **JSON** 含 `firstResponseContext`（含 **`userFacingOneLiner`**（给用户的一行）、`recommendedOneLiner`（Agent 细则）、**`openingGuidance`**）、`performance`：终端用户侧**只转述 `userFacingOneLiner` + 3 选项**，勿贴完整 JSON；**勿**把 `recommendedOneLiner` 或内部规范句再念给用户。
- **默认已快速开场**（等同旧版 `--fast`）；只有需要完整在线场景包时才加 **`--full`**（可能较慢，见 `anti-stall-guide.md`）。
- **`session-exit --json`** 的 `userMessage` 含**两行**：第一行为固定收束语，第二行为本次会话自然语言摘要（`userSummary`）；向用户复述时**两行都要带上**，勿只读第一行。
- **`exit` / `session-exit` 必须从技能包根目录调用**，或 `fbs-cli-bridge.mjs exit -- --book-root <绝对路径>`；勿在书稿子目录里用相对路径指向 `scripts/session-exit.mjs`（会解析失败）。

---

## 4.1 退出前软询问（WorkBuddy 实测 P0）

- 用户说「退出 / 先到这 / 收工 / 退出福帮手」时：**必须先**一句确认（「还需要别的吗？」或「进度会保存，确定退出？」），**再**运行 `session-exit`；**禁止**未确认直接执行 exit。
- `session-exit --json` 含 **`agentGuidance.beforeExit`**，供宿主提示 Agent；执行后仍须完整复述 **`userMessage`**（两行）。

---

## 4.2 意图分层（意图外输入，P1）

| 层级 | 示例 | 处理方式 |
|------|------|----------|
| **即时应答** | 乐包余额、当前阶段、文件位置 | 简短回答后回到主任务 |
| **先确认再进流程** | 新建书稿、打开项目、跑质检 | 一句「好的」+ 进入标准流程 |
| **探索/澄清** | 某工具是什么、与 WorkBuddy 区别 | 先问「想了解下概念」还是「本书里要用」再检索 |

---

## 4.3 脚本失败时的用户可见文案（P1）

- 不向用户粘贴整段 `CommandNotFoundException` 或英文栈。
- 用：**「当前环境缺某命令，已跳过或改用内置方案」**；需要时提示检查终端/PATH 或换 Git Bash/WSL。
- 细节给维护者或「需要完整日志再说」。

---

## 4.4 技术处理可见时的宜人性解释（P0）

- 当技术处理过程会被用户感知（安装依赖、刷新缓存、修复环境、重跑脚本）时，必须先给一句**为什么要做**与**对写作的价值**，再执行。
- 推荐固定四句模板（可精简，不可缺少价值说明）：
  1) 我先做什么（后台处理，不改你的正文内容）  
  2) 为什么（避免中断/误报/重复操作）  
  3) 对你有什么价值（让写作更稳、更快回到正文）  
  4) 失败兜底（若未完全成功，给最短替代路径，主流程继续）
- 禁止只给技术命令或报错原文，不解释意图与用户收益。

---

## 5. 相关文档

| 主题 | 路径 |
|------|------|
| 规则中心 | `references/01-core/ux-optimization-rules.md` |
| 对话层流畅度 | `references/03-product/07-ux-design.md` |
| CLI 联动 | `references/01-core/skill-cli-bridge-matrix.md` |
| 防卡顿 | `references/05-ops/anti-stall-guide.md` |
| 用户向价值一页纸 | `references/03-product/fbs-value-one-pager.md` |

---

## 6. 术语：对用户 vs 内部 / 日志（Tier 等）

**原则**：对用户**禁止**说 Tier、调度层、内部模块代号；宿主探测 JSON 或日志里若出现技术词，**转述时脱敏为口语**。

| 内部 / 日志可能出现 | 对用户可这样说 |
|---------------------|----------------|
| Tier1 / 本地市场 | 「本机已装的增强技能」「技能市场里可用的能力」 |
| Tier2 / 宿主插件 | 「当前编辑器/宿主里的插件能力」 |
| Tier3 / 远程发现 | 「在线发现的可选技能」 |
| `loadScenePack` / 场景包加载失败 | 「增强场景暂时不可用，先用通用规范继续」 |
| `intake-router` / 脚本名 | 「我先帮你同步一下书稿状态」 |
| `host-capability` | 「我查一下你当前环境能用什么能力」 |

**日志 / 集成方**：保留字段名便于排障；**复述给用户**时以上表为准，见 [`references/06-plugin/workbuddy-host-integration.md`](../06-plugin/workbuddy-host-integration.md) §6。
