# Clavue 内容反馈层升级规划：复刻 Grok CLI 交互体验

> Status: **已 superseded**（2026-06-09）  
> **请使用统一版**：[clavue-grokcli-content-feedback-interaction-plan.md](./clavue-grokcli-content-feedback-interaction-plan.md)（v2 合并稿）  
> 本文档仅保留作历史参考。

---

## 1. 背景与目标

### 1.1 为什么要做

当前阶段的最佳实践已经明确：**用户主要看结果，不看过程**。  
Grok CLI 和 Codex 的共同优势不是「少做事」，而是把复杂工程过程**组织成高信号、低噪音、可扫读的反馈层**。

Clavue 已在 v8.20+ 吸收了大量 Grok CLI DNA（Live Directives & Monitors、工具摘要、`ctrl+o` 展开、思考块压缩等），但**内容反馈仍不统一**：

- 有的 turn 像 Grok CLI（任务板 + 折叠输出 + 当前动作高亮）
- 有的 turn 仍像传统 Agent CLI（长 Bash 输出、双栏探索日志、过程性叙述淹没结果）
- Assistant 最终回复与工具轨迹之间**缺少稳定的「结果优先」契约**

### 1.2 本规划要回答的问题

1. Grok CLI 体验的核心到底是什么？（不是抄 UI，是抄**信息分层**）
2. Clavue 现在差在哪？
3. 如何在不牺牲模型能力的前提下，把用户面收敛到「结果 + 态势 + 可展开细节」？
4. 分几期做、改哪些模块、怎么验收？

### 1.3 非目标

- 不重写主循环或工具执行语义
- 不删除 verbose / transcript 能力（给高级用户和调试保留）
- 不把 `/mao` 等内部运行时重新暴露给用户
- 本文档阶段**不直接改代码**，只定义方案与优先级

---

## 2. 参考样本拆解（来自你提供的截图）

### 2.1 Grok CLI 目标态（`image.png` / `image copy 2.png` / `image copy 3.png`）

| 层级 | 用户看到什么 | 默认隐藏什么 |
|------|-------------|-------------|
| **态势层** | 任务清单（■ 完成 / □ 待办）、`+N pending, M completed`、当前 running 动作 | 历史已完成任务的细节 |
| **动作层** | `Update(path)`、`Added 1 line, removed 1 line`、`Bash(label)` | 完整命令、完整 stdout |
| **进度层** | `Cooked for 2m 48s`、`Running… (3m 54s · ↓ 194 tokens)` | 中间每行日志 |
| **结果层** | `Verification passed: npm run check · 15 tests`、新增 docs 列表、next steps 一段话 | diff 全文、探索推理 |
| **异常层** | 人话结论 + `---` 分隔后才出现 GC/stack | 平时不展示 runtime 噪音 |
| **控制层** | `▶ accept edits on · esc to interrupt · ctrl+t to hide tasks` | — |

**核心洞见**：Grok CLI 的舒服来自 **认知外骨骼** —— 用户永远知道「现在在干什么、完成了什么、还差什么」，细节按需展开。

### 2.2 Codex 对齐点

- 工具调用默认**一行摘要**（`ctrl+o to expand`）
- 文件变更显示 **delta 规模** 而非全文
- 长任务用 **heartbeat + token/耗时** 证明「还在干活」
- 最终交付以 **可验证结果** 收束（tests passed / build ok / blockers）

### 2.3 Clavue 已接近目标态（`image copy 7.png` v8.23.14）

已有：

- 绿色步骤轨迹：`Skill` / `Bash(label)` / `Searched for N pattern`
- 折叠：``+42 lines (ctrl+o to expand)``
- 顶部 **Live Directives & Monitors** 高亮当前动作
- Running 行：`* Running … (22m 12s • 469 tokens)`

说明方向正确，需要**系统化、默认化、全覆盖**。

### 2.4 需要远离的旧态（`claude-code-source/docs/image.png`）

- 主区堆满 Bash 原始输出
- 副栏暴露长篇内部推理 / `icc read-screen` 探索链
- 用户要自己从日志里找「到底完没完成」

**结论**：不是去掉工具能力，而是把「探索过程」从默认视图降级为 **L2 可展开层**。

---

## 3. 目标体验定义（用户契约）

### 3.1 默认视图只回答四个问题

1. **现在在做什么？** → Overview 层 + 当前 running 标签  
2. **刚刚完成了什么？** → 一行工具结果 / 一行变更摘要  
3. **整体进展如何？** → 任务板计数 + 耗时/token  
4. **我下一步该知道什么？** → Assistant 结果卡（Outcome Card）

### 3.2 信息分层模型（L0–L4）

```
L0 态势   Live Directives & Monitors（持久、吸顶）
L1 轨迹   工具调用一行摘要（默认折叠）
L2 细节   ctrl+o 展开：完整输出 / diff / 思考全文
L3 结果   Turn Outcome Card：变更、验证、阻塞、next step
L4 原始   verbose / transcript / SDK 全量事件（高级 & 机器）
```

**默认用户停在 L0–L3；L4 不主动打扰。**

### 3.3 单轮对话的标准叙事结构（Grok CLI 式）

```
[可选] L0 态势更新
[多条] L1 工具摘要轨迹
[一条] L3 结果卡
[一行] 耗时 · token · 子代理完成数
```

Assistant 自然语言也应服从同一骨架，而不是先写 3 段过程再写结论。

---

## 4. 现状盘点（Clavue 代码映射）

### 4.1 已具备（保持并强化）

| 能力 | 代码落点 | 符合 Grok CLI 的程度 |
|------|---------|---------------------|
| 顶部任务/监控概览 | `REPL.tsx` `unifiedTopOverview`、`TaskListV2` `isTopDashboard` | 中高（尚非真吸顶） |
| 工具非 verbose 摘要 | `GrepTool/UI.tsx`、`FileReadTool/UI.tsx`、`BashTool/UI.tsx` | 中（覆盖不均） |
| 折叠展开 | `CtrlOToExpand`、`Tool.isResultTruncated` | 高 |
| 思考块压缩 | `AssistantThinkingMessage.tsx` | 高 |
| 长任务心跳 | `ShellProgressMessage`、`MonitorTool` 批处理 | 中高 |
| Turn 耗时 | `createTurnDurationMessage`、`TURN_COMPLETION_VERBS` | 高 |
| 错误降噪 | v8.22.12「quieter errors」 | 中 |

### 4.2 主要差距

| 差距 | 表现 | 风险 |
|------|------|------|
| **无统一 Turn Outcome Card** | 结果散落在 assistant 散文里 | 用户无法 5 秒判断本轮交付 |
| **工具 UI 标准不一致** | 部分工具仍泄长输出 | 体验漂移、噪音回流 |
| **Assistant 输出未分层** | 模型仍倾向「过程报告体」 | 与 UI 折叠策略打架 |
| **Overview 非真持久层** | 滚动后态势消失 | 长 session 迷失 |
| **模型对 Overview 感知弱** | 见符合度评审 P5 | 重复轮询、态势不一致 |
| **子代理/并行完成摘要弱** | Grok 有 `2 agents finished` | 多代理时用户不知谁完成了什么 |
| **异常未分级** | OOM/stack 与业务失败混在一起 | 恐慌感、难定位 |

---

## 5. 方案总览：Content Feedback Stack

建议在现有 Overview Layer 之上，新增 **Content Feedback Stack**（内容反馈栈），与工具渲染正交：

```
┌─────────────────────────────────────────────┐
│ L0 Overview Chrome（Directives + Monitors） │ 已有，需吸顶强化
├─────────────────────────────────────────────┤
│ L1 Tool Trace Renderer（统一摘要协议）       │ 部分已有，需全覆盖
├─────────────────────────────────────────────┤
│ L2 Expandable Detail（ctrl+o / verbose）    │ 已有
├─────────────────────────────────────────────┤
│ L3 Turn Outcome Card（新增，结果优先）       │ 缺失，本期核心
├─────────────────────────────────────────────┤
│ L4 Transcript / SDK / verbose               │ 保留
└─────────────────────────────────────────────┘
```

---

## 6. 分项设计

### 6.1 L0：Overview Chrome 强化（延续 v8.20 路线）

**目标**：任何有 active directive/monitor 的 session，态势层**永远可见**。

| 动作 | 说明 |
|------|------|
| 真吸顶布局 | Overview 移出 transcript 滚动区，进入 `topChrome` 固定区 |
| 点击展开 | 已有 `isDashboardExpanded`，统一交互文案 |
| Monitor ↔ Directive 关联 | 模型可选声明归属，面板轻分组 |
| 模型可读快照 | 每 turn 注入结构化 overview snapshot（评审文档 P5 缺口） |

**验收**：30 秒内新接手者能说出「当前最重要任务 + 关键 monitor 状态」，且无需翻历史消息。

### 6.2 L1：Tool Trace 统一摘要协议

为所有内置工具定义统一的 **Non-Verbose Contract**：

```ts
// 概念协议（非最终实现）
type ToolSurfaceSummary = {
  label: string          // 人类可读动作名，优先用 description/comment label
  delta?: string         // "Added 2 lines" / "13 matches in 3 files"
  status: 'ok' | 'fail' | 'running'
  expandable: boolean    // 是否显示 ctrl+o
  hiddenLines?: number
}
```

**规则**：

| 工具类型 | 默认显示 | 禁止默认显示 |
|---------|---------|-------------|
| Bash | `Bash(label)` 或 comment label | 完整脚本、>20 行 stdout |
| Read | `Read path` 或 `Read path L10-40` | 文件全文 |
| Write/Edit | `Update(path)` + 行数 delta | 全文 diff |
| Grep | `Search "pat" (N matches in M files)` | 命中全文 |
| Agent/Parallel | `audit X · 15 tool uses · Done` | 子代理内部 transcript |
| Skill | `Skill(name)` + loaded/ failed | skill 正文 |

**落地抓手**：

- 扩展 `Tool.isResultTruncated` + `extractSearchText` 覆盖率（已有 fidelity test）
- `BashTool`: 强制推广 `description` / comment label（已有 `extractBashCommentLabel`）
- 新增 `tools/shared/summaryContract.ts` 收敛重复逻辑
- CI：`transcriptSearch.renderFidelity.test.tsx` + 快照测试覆盖所有内置工具

### 6.3 L3：Turn Outcome Card（本期最高杠杆）

在每轮 assistant 回复**之前或之后**（推荐：**之后、作为 turn 收束**）渲染结构化结果卡。

**字段模板**（对齐 Grok `image copy 3`）：

```markdown
### 本轮结果
- **做了什么**：…
- **变更**：`path/a`, `path/b`（+2 −1）
- **验证**：`npm run check` passed · 15 tests
- **阻塞**：无 / 列出 blocker
- **下一步**：一句话

Worked for 4m 36s · 2 agents finished (ctrl+o)
```

**数据来源**（尽量确定性，少靠模型自觉）：

| 字段 | 来源 |
|------|------|
| 变更列表 | 本轮 Edit/Write/Bash git 工具结果聚合 |
| 验证 | 本轮 Bash 中 `test|check|verify|build` 命令 + exit code |
| agents finished | `AgentTool` / `/parallel` 完成事件 |
| 阻塞 | supervisor delivery gate / failed tool / non-zero exit |
| 文案总结 | 模型 assistant 最后一段，经 **Outcome Extractor** 抽取 |

**实现路径**：

1. **Phase A（纯 UI）**：`PostTurnSummary` 组件，从 transcript 元数据拼装，不新增模型调用  
2. **Phase B（提示词）**：system/reminder 要求模型按 Outcome 模板收尾  
3. **Phase C（可选）**：轻量 `postTurnSummary` 侧车（`forkedAgent.ts` 已预留注释）

**配置**：

- `showTurnOutcomeCard: true`（默认开）
- `showTurnDuration` 合并进 Outcome Card 页脚

### 6.4 Assistant 文本：从「过程报告」到「结果优先」

UI 折叠了工具细节后，模型若仍写过程，会造成**双重信息损失**。需要提示词层配合：

**写入 `sessionWorkflowContinuity` / 主系统提示的 Outcome Discipline**：

- 默认回复结构：`结论 → 证据 → 下一步`（不超过 3 段）
- 禁止复述已折叠的工具输出（「我运行了 npm test 并看到……」→ 改为 「验证：npm test passed」）
- 长任务进行中：只更新 Overview 与一行 status，不写散文
- 中文/英文与用户输入语言一致（截图中的混排体验）

### 6.5 异常分级（对齐 Grok `--- Last few GCs ---`）

| 级别 | 用户看到 | 场景 |
|------|---------|------|
| E0 静默 | 无 | 成功工具 |
| E1 行内 | `● File not found` + path | 可恢复错误 |
| E2 卡片 | 人话原因 + 建议下一步 | 命令失败、gate blocked |
| E3 诊断 | `---` 后 GC/stack | OOM、崩溃、内部错误 |

**规则**：E3 永远默认折叠；E2 永不直接贴 raw stderr。

落点：`FallbackToolUseErrorMessage`、Bash OOM 检测、`maoDeliveryGatePermission` 文案已部分符合，需统一入口。

### 6.6 子代理 / 并行反馈（Grok `N agents finished`）

当 `/parallel`、AgentTool、companion handoff 完成时：

```
2 agents finished (ctrl+o to expand)
  audit backend hardening · 15 tool uses · Done
  audit sdk hardening · 16 tool uses · Done
```

落点：`parallelDevelopment.ts` 已有 supervisor proof；扩展为 **AgentCompletionRollup** 组件，挂到 L3 Outcome Card。

### 6.7 控制条与心智模型（底部 chrome）

统一底部状态语义（截图中 `▶ accept edits on · esc to interrupt · ctrl+t to hide tasks`）：

| 元素 | 含义 |
|------|------|
| `▶ accept edits on` | 自动接受编辑模式 |
| `esc to interrupt` | 中断当前 turn |
| `ctrl+t` | 隐藏/显示任务板 |
| `ctrl+o` | 展开当前焦点详情 |
| `shift+tab` | 模式循环 |

**原则**：快捷键提示跟着**当前最重要动作**走，不重复刷屏。

---

## 7. 分阶段路线图

### Phase 0 — 对齐基线（1 周，低风险）

- [ ] 审计所有内置工具 `renderToolResultMessage` 的 non-verbose 行为，出差距表
- [ ] 统一 Bash `description` / comment label 推广指南（提示词 + 示例）
- [ ] 文档化 L0–L4 分层，写入 AGENTS 贡献者说明
- [ ] 用截图样本建立 **golden transcript fixtures**（回归用）

**验收**：选 3 条真实 session 回放，默认视图行数比基线减少 ≥40%。

### Phase 1 — Turn Outcome Card（2 周，最高 ROI）

- [ ] 新增 `PostTurnSummary` / `TurnOutcomeCard` 组件
- [ ] 从工具结果聚合 changes / verification / blockers
- [ ] 合并 `showTurnDuration` 与 agent 完成计数
- [ ] 提示词增加 Outcome Discipline 段落
- [ ] 测试：`post-turn-summary.test.mjs`

**验收**：用户不看 verbose 也能回答「这轮改了什么、测过吗、能继续吗」。

### Phase 2 — Tool Trace 全覆盖（2–3 周）

- [ ] `summaryContract.ts` 共享层
- [ ] 补齐薄弱工具 UI（LSP、WebFetch、MCP、PowerShell…）
- [ ] `renderFidelity` 测试扩至全工具
- [ ] Agent/Parallel 完成 rollup

**验收**：任意 turn 的工具轨迹在 non-verbose 下每行 ≤1 屏宽、可预测格式。

### Phase 3 — Overview 真持久 + 模型感知（3–4 周）

- [ ] Overview 移入固定 `topChrome`（不随 transcript 滚走）
- [ ] 每 turn 注入 overview snapshot 给模型
- [ ] Monitor ↔ Directive 关联
- [ ] 智能预览「最近有意义变化」

**验收**：符合度评审 P1/P5 从「中高/低」提升到「高」。

### Phase 4 — 异常分级 & 体验抛光（持续）

- [ ] 错误分级渲染统一
- [ ] OOM/stack 默认折叠
- [ ] 多语言 outcome 模板
- [ ] 可选「极简模式」：仅 L0+L3，隐藏 L1 轨迹

---

## 8. 关键文件与模块映射

| 模块 | 路径 | Phase |
|------|------|-------|
| Overview 持久层 | `src/screens/REPL.tsx` | 3 |
| 任务板 | `src/components/TaskListV2.tsx` | 0–3 |
| 工具摘要 | `src/tools/**/UI.tsx` | 1–2 |
| 工具契约 | `src/Tool.ts` | 2 |
| Bash 折叠 | `src/tools/BashTool/UI.tsx`, `BashToolResultMessage.tsx` | 1–2 |
| 思考压缩 | `src/components/messages/AssistantThinkingMessage.tsx` | 0 |
| Turn 耗时 | `src/components/messages/SystemTextMessage.tsx` | 1 |
| Outcome 卡 | **新建** `src/components/messages/TurnOutcomeCard.tsx` | 1 |
| 聚合器 | **新建** `src/utils/turnOutcomeAggregator.ts` | 1 |
| 并行/代理 | `src/utils/parallelDevelopment.ts`, `src/tools/AgentTool/` | 2 |
| 提示词纪律 | `src/utils/sessionWorkflowContinuityCore.ts`, `src/constants/prompts.ts` | 1 |
| 配置项 | `src/utils/config.ts`, `ConfigTool/supportedSettings.ts` | 1 |
| 回归测试 | `tests/transcript*`, **新建** `tests/turn-outcome-card.test.mjs` | 0–2 |

---

## 9. 衡量指标

| 指标 | 目标 | 测量方式 |
|------|------|---------|
| 默认视图行数/轮 | ↓ 40%+ | golden session diff |
| 结果可判读时间 | < 5s | 可用性走查（5 人） |
| 工具摘要一致率 | 100% 内置工具 | render fidelity tests |
| Overview 可见性 | 长 session 无需翻找 | 任务板曝光率 |
| 用户展开率 | 10–25%（健康） | ctrl+o 触发统计 |
| 异常误报感 | ↓ | 用户反馈 / E2 vs E3 比例 |

---

## 10. 风险与边界

| 风险 | 缓解 |
|------|------|
| 过度隐藏导致不信任 | 保留 ctrl+o / verbose；Outcome Card 必须含「验证证据」 |
| 模型不遵守 Outcome 模板 | Phase A 用确定性聚合补足；Phase B 提示词 + 回归测试 |
| 调试困难 | transcript 模式与 SDK 全量事件不变 |
| 与 Overview 重复 | 明确分工：Overview=现在进行时，Outcome=刚完成的结果 |
| 多客户端不一致 | SDK schema 增加 `turn_outcome` 事件（`SDKPostTurnSummaryMessageSchema` 可扩展） |

---

## 11. 与 Codex / Grok CLI 的关系（定位）

Clavue 不应追求「看起来像 Grok CLI」，而应追求：

> **同样的信息经济学** —— 默认给用户态势与结果，把过程变成可展开的凭证。

差异化优势可保留：

- 更强的 supervisor / delivery gate（内部）
- Live Directives & Monitors 与模型协同（做好后超越 Grok 单面板）
- 多代理 / `/parallel` 的工程化深度

---

## 12. 建议的下一步（可立即开工）

1. **确认默认策略**：新用户默认 `verbose=false` + `showTurnOutcomeCard=true`  
2. **立项 Phase 1**：实现 `TurnOutcomeCard` + `turnOutcomeAggregator`（不改主循环）  
3. **选 2 条 golden session**（一张 Grok 目标图 + 一张 Clavue 旧态图）作 CI 回归  
4. **并行**：提示词加 Outcome Discipline（低成本、即时收益）

---

## 附录 A：截图对照索引

| 文件 | 角色 |
|------|------|
| `image.png` | Grok CLI 任务板 + 折叠 + running 心跳（**目标**） |
| `image copy 2.png` | Grok CLI diff delta + task board + auto mode（**目标**） |
| `image copy 3.png` | Grok CLI 结果优先 + agents finished（**目标**） |
| `image copy 7.png` | Clavue v8.23.14 已对齐片段（**基线**） |
| `claude-code-source/docs/image.png` | 双栏+log 泛滥（**反模式**） |
| `image copy 4.png` | Clavue `/init` 高信号输出（**应保留风格**） |

---

**维护**：本规划随 Phase 0 审计结果更新；Phase 1 启动时可拆为 `/design` 实施 DAG。