# Clavue 内容反馈交互统一规划（Grok CLI × Codex × Overview Layer）

> Status: **统一规划稿 v2**，2026-06-09  
> 来源：Codex《Content Feedback Interaction Plan》+ Clavue《GrokCLI Replication Plan》综合  
> 范围：默认对话面如何向用户展示**重要信息**、折叠**过程噪音**、按需展开**技术细节**  
> 配套：《Clavue Overview Layer 设计原则》《Overview Layer 原则符合度评审》

---

## 0. 执行摘要

Clavue 默认对话面应从 **「展示工作过程」** 升级为 **「展示工作状态与结果，过程细节按需展开」**。

用户不应为了判断「工具是否正常工作」而去读：原始 grep 列表、重复 file read、完整 diff、长 shell log、详细 thinking。  
默认视图应快速回答四个问题：

1. **现在在做什么？**（态势 / running）
2. **刚刚发生了什么关键动作或证据？**（一行轨迹）
3. **有没有改东西、测过、卡住？**（变更 + 验证 + blocker）
4. **最终结果是什么、我下一步该做什么？**（Outcome）

完整 transcript 永远保留。默认视图变成 **高信号操作日志（Operational Journal）**。

---

## 1. 两份方案如何合并

| 维度 | Codex 方案强项 | Clavue 方案强项 | **统一结论** |
|------|---------------|----------------|-------------|
| 架构 | `feedbackPresentation.ts` 展示策略层；`feedbackDetailMode` 三档 | L0–L4 内容反馈栈；与 Overview 分工 | **策略层驱动 L1–L2；Overview 仍是 L0** |
| 交互 | `◇` 视觉语言；分组时间线；`N more hidden`；逐条展开 | Turn Outcome Card；Agent rollup；异常分级 | **过程用时间线，收束用 Outcome Card** |
| 实施 | 明确 First PR（FileRead + Bash test）；5 Phase 工程顺序 | 截图对照；模块文件映射；Overview 吸顶 | **采用 Codex 实施顺序 + Clavue 模块落点** |
| 模型 | 结果优先 final answer 提示词 | Outcome Discipline；digest 喂模型 | **UI 管过程，模型管判断；双端一致** |

**废弃重复表述**：不再维护两份平行规划；以本文档为唯一实施依据。  
（旧稿 `clavue-content-feedback-grokcli-replication-plan.md` 仅作历史参考。）

---

## 2. 产品原则

### 2.1 默认视图（Focused）

只展示会改变用户**信任、决策、下一步行动**的信息。

### 2.2 展开视图（Per-Message Expand）

单击/键盘展开**单条**工具详情。不强迫全局 verbose。  
`ctrl+o` 保留为全局 verbose / transcript 快捷方式，但不是唯一细节入口。

### 2.3 Transcript 契约

重要信息**不消失**。低价值细节被折叠、分组、摘要或移到展开区。  
原始细节仍可通过：`verbose`、`feedbackDetailMode=verbose`、逐条展开、transcript 导出、SDK 全量事件访问。

### 2.4 与 Overview Layer 的分工

| 层 | 职责 | 时间态 |
|----|------|--------|
| **L0 Overview** | Directives + Monitors 态势 | 现在进行时 |
| **L1 轨迹** | 本轮工具一行摘要 / 分组时间线 | 刚发生 |
| **L2 展开** | diff、log、thinking 全文 | 按需 |
| **L3 Outcome** | 变更、验证、阻塞、next step | 本轮收束 |
| **L4 原始** | verbose / transcript / SDK | 审计 & 调试 |

Overview 回答「战场态势」；Content Feedback 回答「这一轮交付了什么」。

---

## 3. 信息分级（Tier 0–3 ↔ L0–L4）

### Tier 0 — 永远可见（不可折叠）

- 面向用户的**最终结果**与 **Outcome Card**
- Blocker、错误、权限等待、失败测试、跳过验证
- 文件写入/编辑/删除、生成产物
- 改变状态的命令：install、build、test、git、package、release、deploy
- Compact / context 压力、token 耗尽、rate limit（影响长 session 信任）
- 用户问题与审批请求
- 安全、secret、破坏性、push/publish 风险

### Tier 1 — 紧凑摘要（默认一行或分组）

- Search / Glob / Read
- 重复 read、grep
- 仅 pass/fail 重要的 shell 成功输出
- 超过数行的 diff
- Agent / subagent / parallel 活动
- 长后台任务进度
- Thinking 摘要（`◇ Thought for 0.8s`）

### Tier 2 — 默认隐藏，逐条可展开

- 无诊断价值的 raw stdout/stderr
- 完整 search 列表、file 全文、常规 edit 全 hunk
- 工具 JSON、路由策略内部名
- 重复 Waiting / Running 低信号进度
- 不影响用户的内部 prompt / 兼容名

### Tier 3 — 不应出现在用户反馈面

- 隐藏 prompt 机制
- 非产品概念的内部 gate 名（已在做 `/mao` 软下线）
- 用户要结果时仍复述实现细节
- 重复 reminder、自指 agent 指令

### 异常分级（补充）

| 级别 | 展示 |
|------|------|
| E0 | 成功 → 静默或一行 ✓ |
| E1 | `● File not found` + path |
| E2 | 人话原因 + 建议下一步 |
| E3 | `---` 后 GC/stack（仅崩溃，默认折叠） |

---

## 4. 目标体验（统一 mock）

### 4.1 正常用户视图（Focused）

```
◇ Thought for 0.2s
继续推进文案下线：保留内部 gate，清理用户可见引用。

◇ Search "/mao|mao gate" in src (69 matches in 20 files)
◇ Search "/mao|mao gate" in tests (139 matches in 17 files)
Context 86% full. Compacting...
Context compacted → 7.1k tokens (22.8s)

◇ Edit src/tools/shared/maoDeliveryGatePermission.ts
◇ Edit src/commands/commit-push-pr.ts
◇ Edit src/buddy/suggestionPolicy.ts
  4 files changed

◇ Verify node --test tests/permission-authorization-flow.test.mjs
  Passed: 18 tests

── Turn Outcome ──────────────────────────
变更：4 files · 验证：18 tests passed · 阻塞：无
下一步：跑 golden session 回归，确认默认行数下降
Worked for 4m 36s
```

默认保留：意图、进度、关键动作、验证、Outcome。  
不默认展示：每个命中路径、每次 read 范围全文、完整 diff、raw log。

### 4.2 分组展开视图

```
▾ Search group (2)
  Search "/mao|mao gate" in src → 69 matches in 20 files
  Search "/mao|mao gate" in tests → 139 matches in 17 files

▾ Edit src/utils/uiLocaleMessages.ts
  - mao: "通过当前 Clavue Provider 配置运行一方 /mao Codex 工作流"
  + mao: "内部 Mao 监督运行时（已隐藏，仅供兼容）"

  30 more hidden (click to expand)
```

### 4.3 与 Grok CLI 截图对齐

| 截图 | 对应层 |
|------|--------|
| 任务板 ■/□、`+N pending` | L0 Overview |
| `Update(path)` + line delta | L1 Edit 摘要 |
| `Running… (3m · N tokens)` | L0 Monitor + L1 progress |
| `Verification passed` / docs 列表 | L3 Outcome |
| `2 agents finished (ctrl+o)` | L3 Agent rollup |
| 双栏+log 泛滥（反模式） | 应压到 L2/L4 |

---

## 5. 视觉语言（Grok CLI 形状）

```
◇ Thought for 0.2s
◇ Search "query" in src (69 matches in 20 files)
◇ Read src/foo.ts (120-180)
◇ Edit src/foo.ts
◇ Verify npm test (passed)
  30 more hidden
```

规范：

- 紧凑动作用统一前缀 `◇`（或现有 bullet，全站一致即可）
- 低风险工具 **一行一事**
- 计数、耗时与动作同一行
- 普通活动不用色块；错误/警告/待审批/已改文件用强调色
- `N more hidden` 表示折叠的 routine 事件
- 底部 footer：waiting 耗时、context/token、当前 mode（已有 `GrokTokenBar`、footer waiting）

---

## 6. 内容模式（按工具类型）

### 6.1 Thinking

- 默认：`◇ Thought for 0.8s` + 一行决策摘要（非 token 估计）
- 展开：完整 thinking / provider reasoning
- 落点：`AssistantThinkingMessage.tsx`（已部分实现）

### 6.2 Search / Read

- 默认：`◇ Search "pat" in src (N matches in M files)` / `◇ Read path (L900-1040)`
- 隐藏：完整列表与文件正文
- 落点：`GrepTool/UI.tsx`、`FileReadTool/UI.tsx`

### 6.3 Edit

- 默认：`◇ Edit path` + 一行意图；批量：`◇ Edit 5 files` + 文件名片段
- 展开：condensed hunks；verbose/transcript 保留全 diff
- 落点：`FileEditToolUpdatedMessage` condensed style

### 6.4 Shell / Test

- 通过：`◇ Verify <cmd>` + `Passed: N tests (118ms)`
- 失败：`Failed: N tests` + **第一条可行动 diagnostic**
- 隐藏：runner boilerplate
- 落点：`BashTool/UI.tsx`、`BashToolResultMessage.tsx`

### 6.5 Compact / Context

- 始终 Tier 0：`Context 86% full. Compacting...` / `compacted → 7.1k tokens (22.8s)`

### 6.6 Agent / Subagent

- 默认：`◇ Agent explorer completed` + 一行结论
- 批量：`2 agents finished (ctrl+o)` + 子项列表
- 落点：`GroupedToolUseContent`、`parallelDevelopment.ts`

---

## 7. 实现架构（统一）

### 7.1 Presentation Policy Layer（Codex 核心 + Clavue 落点）

在工具事件已知之后、渲染之前，增加**纯 UI 展示分类器**（不改变执行、路由、权限）：

```ts
type FeedbackImportance = 'critical' | 'important' | 'routine' | 'debug'

type FeedbackPresentation = {
  importance: FeedbackImportance
  defaultVisibility: 'visible' | 'summary' | 'collapsed' | 'hidden'
  summary: string
  details?: React.ReactNode
  groupKey?: string   // 'search' | 'read' | 'edit' | 'verify' | 'agent'
  auditLabel?: string
}
```

**建议文件**：`src/components/messages/feedbackPresentation.ts`

**接线点**：

- `AssistantToolUseMessage.tsx`
- `UserToolResultMessage` / tool result 渲染链
- `GroupedToolUseContent.tsx`（扩展跨工具语义分组）
- `VirtualMessageList` 逐条展开状态

### 7.2 Tool Summary Contract（增量 opt-in）

在 `Tool.ts` 上可选扩展：

```ts
renderCompactToolUseMessage?
renderCompactToolResultMessage?
classifyToolFeedback?
```

优先覆盖高流量工具：**Bash、Grep/Glob、FileRead、FileEdit/FileWrite、Agent**。

共享收敛：`src/tools/shared/summaryContract.ts`（Clavue 方案）

### 7.3 Grouped Timeline

相邻 routine 事件合并：

- Search group / Read group / Edit group / Verify group / Agent group
- 折叠后显示 `N more hidden`
- 基于现有 `GroupedToolUseContent`，扩展到**跨工具名**语义分组

### 7.4 Turn Outcome Card（Clavue 核心）

每轮收束的结构化卡片（L3），字段尽量**确定性聚合**：

| 字段 | 来源 |
|------|------|
| 变更 | 本轮 Edit/Write/git 工具 |
| 验证 | Bash test/check/verify + exit code |
| 阻塞 | failed tool / gate / non-zero exit |
| agents | AgentTool / `/parallel` 完成事件 |
| 文案 | assistant 末段（可选 Outcome Extractor） |

**建议文件**：

- `src/components/messages/TurnOutcomeCard.tsx`
- `src/utils/turnOutcomeAggregator.ts`

与 `showTurnDuration` 合并页脚；配置项 `showTurnOutcomeCard`（默认 true）。

### 7.5 Result-Centric Final Answer（提示词）

模型负责 **判断与结论**；渲染器负责 **过程轨迹**。  
Final answer 模板：

```
Done. 改了 X 和 Y。

Verified with:
  node --test ...

Remaining risk:
  ...
```

落点：`src/constants/prompts.ts`、`sessionWorkflowContinuityCore.ts`

### 7.6 Model-Aware Digest（Phase 5）

每轮 emit 紧凑 `feedbackDigest`，供下轮模型与 Overview snapshot 使用；与 raw transcript 分离，避免 prompt 污染。  
对齐 Overview Layer 原则 5（双受众）。

---

## 8. 用户设置（统一为一档主开关）

```json
{
  "feedbackDetailMode": "focused"
}
```

| 值 | 行为 |
|----|------|
| `focused` | **默认**。结果优先 + 紧凑轨迹 + Outcome Card |
| `expanded` | 默认展示更多细节，仍分组降噪 |
| `verbose` | 等同现有全量过程视图 |

可选二级（后续再加，首版不加太多）：

```json
{
  "feedbackShowThinkingPreview": true,
  "feedbackCollapseSearchReads": true,
  "feedbackCollapsePassingTests": true,
  "showTurnOutcomeCard": true
}
```

落点：`src/utils/config.ts`、`ConfigTool/supportedSettings.ts`

---

## 9. 统一实施路线图

### Phase 0 — 基线（~1 周）

- [ ] 审计全工具 `renderToolResultMessage` non-verbose 行为 → 差距表
- [ ] golden transcript fixtures（Grok 目标图 + Clavue 反模式各 1 条）
- [ ] 文档化 Tier 0–3 / L0–L4 写入贡献者说明

**验收**：3 条真实 session 回放，focused 模式行数较基线 ↓≥40%（目标）。

### Phase 1 — 展示策略基础 + First PR（~1–2 周）⭐ 立即开工

Codex 推荐的最小有用实现：

1. [ ] `feedbackDetailMode` schema + ConfigTool
2. [ ] `feedbackPresentation.ts` 确定性分类器
3. [ ] `AssistantToolUseMessage` / result 链接入 policy
4. [ ] **FileRead**：focused 下仅 path/range/count
5. [ ] **Bash test**：通过时 command + pass summary（可解析时）
6. [ ] 测试：setting 暴露、两类工具契约、verbose 无回归

**验收**：`feedbackDetailMode=verbose` 无视觉回归；focused 下至少 2 类高流量工具可折叠。

### Phase 2 — 高流量工具压实（~2 周）

1. [ ] Search/Grep/Glob：query + scope + match/file count
2. [ ] FileEdit/Write：path + 一行变更摘要
3. [ ] Bash：comment label / description 优先（`extractBashCommentLabel`）
4. [ ] `summaryContract.ts` + `renderFidelity` 扩覆盖

**验收**：典型 edit+test session 在 final answer 前 **<15 行**过程反馈。

### Phase 3 — 分组时间线（~2 周）

1. [ ] 相邻 search/read 分组
2. [ ] 多文件 edit 批量行
3. [ ] `N more hidden` + 逐条展开（VirtualMessageList）
4. [ ] Agent group 雏形

**验收**：截图级可比 Grok CLI 紧凑时间线；Tier 0 事件不丢。

### Phase 4 — Outcome Card + 结果优先回复（~2 周）

1. [ ] `TurnOutcomeCard` + `turnOutcomeAggregator`
2. [ ] 合并 turn duration、agent finished 计数
3. [ ] Final answer 提示词纪律（不复述已可见轨迹）
4. [ ] `tests/turn-outcome-card.test.mjs`

**验收**：不展开即可回答「改了什么、测过吗、能继续吗」。

### Phase 5 — Overview 持久 + Model Digest（~3–4 周）

1. [ ] Overview 真吸顶（`REPL.tsx` topChrome）
2. [ ] Monitor ↔ Directive 关联
3. [ ] 每轮 `feedbackDigest` + overview snapshot 注入模型
4. [ ] 异常分级 E0–E3 统一入口

**验收**：Overview 符合度 P1/P5 提升到「高」；长 session 不迷失。

---

## 10. 推荐 First PR（Phase 1 切片）

```
PR-1: feedbackDetailMode + feedbackPresentation.ts（骨架）
PR-2: FileRead focused collapse + tests
PR-3: Bash passing-test summary + tests
PR-4: wire AssistantToolUseMessage to policy
```

**为何先 FileRead + Bash test**：高流量、仅渲染层、blast radius 小、可证明策略层无需一次改完全部工具。

---

## 11. 模块映射（实施索引）

| 模块 | 路径 | Phase |
|------|------|-------|
| 展示策略 | **新建** `feedbackPresentation.ts` | 1 |
| 工具消息 | `AssistantToolUseMessage.tsx` | 1 |
| 分组 | `GroupedToolUseContent.tsx` | 3 |
| 列表展开 | `VirtualMessageList` / `Message.tsx` | 3 |
| 工具 UI | `src/tools/**/UI.tsx` | 1–2 |
| 工具契约 | `src/Tool.ts` | 2 |
| Outcome 卡 | **新建** `TurnOutcomeCard.tsx` | 4 |
| 聚合器 | **新建** `turnOutcomeAggregator.ts` | 4 |
| Overview | `REPL.tsx`, `TaskListV2.tsx` | 5 |
| 思考 | `AssistantThinkingMessage.tsx` | 1–2 |
| 配置 | `config.ts`, `ConfigTool/supportedSettings.ts` | 1 |
| 提示词 | `constants/prompts.ts`, `sessionWorkflowContinuityCore.ts` | 4 |
| 测试 | `tests/feedback-presentation.test.mjs`, `tests/turn-outcome-card.test.mjs` | 1–4 |

---

## 12. 验收标准（合并）

### 用户体验

- [ ] 每个 routine 工具默认 ≤1 行
- [ ] 重复 search/read 合并为组
- [ ] 通过测试仅摘要，失败显示首条 diagnostic
- [ ] Edit 按文件+意图可见，全 diff 在展开区
- [ ] Compact/context 始终可见
- [ ] Final response 聚焦 outcome，不重复轨迹
- [ ] Outcome Card 回答「变更 / 验证 / 阻塞 / 下一步」
- [ ] 正常 coding 任务：**final answer 前过程反馈 ≤1 屏**

### 技术

- [ ] transcript 完整保留
- [ ] `verbose` / `feedbackDetailMode=verbose` 绕过折叠
- [ ] 逐条展开不 mutate 持久化消息
- [ ] 展示策略确定性、可单测
- [ ] **展示策略不复制 route policy / 权限 / 执行语义**

### 回归测试清单

- feedbackDetailMode schema + ConfigTool
- Search/read collapse contract
- Passing test summary / failed diagnostic visibility
- Edit visibility + diff expansion
- Compact event always visible
- Verbose bypass
- Turn Outcome Card aggregation

---

## 13. 风险（合并）

| 风险 | 缓解 |
|------|------|
| 藏太多 | Tier 0 清单；blocker/失败测试/编辑永不藏 |
| UI 策略变第二套 runtime policy | 仅决定 visibility/summary |
| 摘要错误 | 优先 tool metadata 确定性摘要，热路径不用 LLM 摘要 |
| 老用户要全 trace | `verbose` + `feedbackDetailMode` + export |
| 与 Overview 重复 | Overview=进行时，Outcome=本轮交付 |
| 模型仍写过程散文 | UI 折叠 + Outcome Card 确定性字段 + 提示词纪律 |

---

## 14. 非目标

- 不重做整个 TUI
- 不替换 Overview Layer（与之协同）
- 不为「看起来干净」而藏错误
- 不用 LLM 摘要每个 tool event（热路径）
- 不改变执行语义、route policy、权限行为

---

## 15. 成功指标

对一次典型 search → read → edit → test 任务：

| 指标 | 目标 |
|------|------|
| 默认过程行数 | final answer 前 ≤1 屏（Codex）；较基线 ↓40%（Clavue） |
| 结果可判读 | <5s 回答「改了什么、测过吗」 |
| 展开率 | 10–25%（健康） |
| 工具摘要一致率 | 100% 内置工具（逐步） |

**一句话**：默认冷静（calm by default），按需精确（precise on demand）—— 这就是 Clavue 要对齐的 Grok CLI / Codex 体验。

---

## 16. 下一步行动

1. **确认默认**：`feedbackDetailMode=focused`，`verbose=false`，`showTurnOutcomeCard=true`
2. **开工 Phase 1 First PR**：FileRead + Bash test + presentation policy 骨架
3. **并行**：选 2 条 golden session 作 CI fixture
4. **Phase 1 完成后**再开 Phase 3 分组时间线（避免未铺策略层就做大分组）

---

## 附录 A — 截图索引

| 文件 | 角色 |
|------|------|
| `/Users/lu/codebase/image.png` | Grok 任务板 + 折叠（目标） |
| `image copy 2.png` | diff delta + task board（目标） |
| `image copy 3.png` | 结果优先 + agents finished（目标） |
| `image copy 7.png` | Clavue v8.23 已对齐片段（基线） |
| `claude-code-source/docs/image.png` | 双栏 log 泛滥（反模式） |

## 附录 B — 文档 lineage

- v1 Codex：`clavue-grokcli-content-feedback-interaction-plan.md`（英文原稿逻辑）
- v1 Clavue：`clavue-content-feedback-grokcli-replication-plan.md`（中文 + Overview + Outcome Card）
- **v2 本文档**：二者合并后的唯一实施依据