附录 VI：用户体验与彩蛋

# 附录 VI：用户体验与彩蛋

> 优秀的工具不只完成任务，它们还会让使用过程本身变得有趣。

---

## 附录 VI-A：Buddy 虚拟伴侣

### 功能描述

Buddy 是一个隐藏在输入框旁边的小动物伴侣——它偶尔会冒泡说话、对对话做出反应，甚至在被直接呼唤时用一句话回应。每位用户的伴侣由**用户 ID 哈希值确定性生成**，外观与属性不会随机变化，但可能随时间"成长"。

### 核心文件

| 文件 | 说明 |
|------|------|
| `src/buddy/companion.ts` | 伴侣生成逻辑（PRNG、属性摇骰） |
| `src/buddy/types.ts` | 类型定义（物种、稀有度、属性、帽子） |
| `src/buddy/sprites.ts` | ASCII art 精灵图（多帧动画） |
| `src/buddy/prompt.ts` | 注入 LLM 的伴侣介绍 Attachment |
| `src/buddy/CompanionSprite.tsx` | 精灵图渲染 React 组件 |
| `src/buddy/useBuddyNotification.tsx` | 通知气泡 Hook |

### 物种（18 种）

| 分组 | 物种 |
|------|------|
| 水生 | duck、goose、octopus、axolotl |
| 陆生 | cat、rabbit、turtle、snail、capybara |
| 奇幻 | dragon、ghost、blob、mushroom、robot |
| 胖乎 | chonk、penguin |
| 植物 | cactus、owl |

物种名称通过 `String.fromCharCode` 运行时构造，防止字面量出现在构建产物中（规避模型代号金丝雀检测）。

### 稀有度（5 级）

```typescript
type Rarity = 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary'

// 稀有度对应的最低属性基础值（floor）
const RARITY_FLOOR = { common: 5, uncommon: 15, rare: 25, epic: 35, legendary: 50 }
```

### 属性系统

```typescript
const STAT_NAMES = ['DEBUGGING', 'PATIENCE', 'CHAOS', 'WISDOM', 'SNARK']

// 生成规则：
// - 随机选一个"峰值属性"（满值附近）
// - 随机选一个"倒霉属性"（最低值）
// - 其余属性在 floor 以上随机散布
```

### 外观组合

- **眼睛**（6 种）：`·`、`✦`、`×`、`◉`、`@`、`°`
- **帽子**（8 种）：none、crown、tophat、propeller、halo、wizard、beanie、tinyduck
- **闪亮**（shiny）：罕见变体，颜色不同

### 确定性生成

```typescript
// Mulberry32 PRNG：以 hash(userId) 为种子
function mulberry32(seed: number): () => number

// 哈希函数：优先使用 Bun.hash，回退到 FNV-1a
function hashString(s: string): number

// 生成流程：hash(userId) → seed → PRNG → rollRarity + pick(species) + rollStats
```

### 与 LLM 集成

`getCompanionIntroAttachment()` 在每次新对话开始时，向 LLM 注入一个 `companion_intro` 类型的 Attachment，告知模型伴侣的名字和物种，让模型在对话中适当配合（但不扮演伴侣）。受 `feature('BUDDY')` 功能 gate 控制。

---

## 附录 VI-B：Effort Level（输出质量档位）

### 功能描述

Effort Level 允许用户（或自动化脚本）向 Claude 传达期望的"思考深度"，从快速草稿到全力以赴。背后对应 API 的 `budget_tokens` 参数，控制模型允许使用多少思考 token。

### 核心文件

| 文件 | 说明 |
|------|------|
| `src/utils/effort.ts` | 档位定义、模型兼容性检查、数值解析 |

### 档位定义

```typescript
const EFFORT_LEVELS = ['low', 'medium', 'high', 'max'] as const

// 等价形式：也支持 0-1 之间的浮点数（如 0.8）
type EffortValue = EffortLevel | number
```

### 模型支持矩阵

```typescript
// 支持 effort 参数的模型（modelSupportsEffort）
opus-4-6 ✓    sonnet-4-6 ✓    haiku ✗    旧版 sonnet/opus ✗

// 支持 'max' 档位的模型（modelSupportsMaxEffort）
opus-4-6 ✓    其他所有模型 ✗
// 注：'max' 档位仅 Opus 4.6 支持，其他模型传入会报 API 错误

// Anthropic 内部用户（USER_TYPE=ant）可解锁更多模型
```

### 关键常量/配置

```bash
# 强制所有模型支持 effort 参数（测试用）
export CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1
```

---

## 附录 VI-C：Claude in Chrome（浏览器集成）

### 功能描述

将 Claude Code 与 Chrome/Chromium 浏览器深度集成：Claude 可以读取当前网页内容、截图、执行 DOM 操作，实现"看网页 → 思考 → 操作浏览器"的自动化循环。通过 Native Messaging 或 Bridge（云端中继）与浏览器扩展通信。

### 核心文件

| 文件 | 说明 |
|------|------|
| `src/utils/claudeInChrome/common.ts` | 浏览器配置、socket 路径管理 |
| `src/utils/claudeInChrome/mcpServer.ts` | MCP Server 入口（集成 `@ant/claude-for-chrome-mcp`） |
| `src/utils/claudeInChrome/setup.ts` | Native Messaging Host 安装 |
| `src/utils/claudeInChrome/setupPortable.ts` | 多平台 Chromium 浏览器支持 |
| `src/utils/claudeInChrome/chromeNativeHost.ts` | 与浏览器扩展的 stdio 通信 |
| `src/commands/chrome/chrome.tsx` | `/chrome` 命令交互菜单 |

### 支持的浏览器（`ChromiumBrowser` 类型）

Chrome、Chromium、Edge、Brave、Opera、Vivaldi、Arc 等主流 Chromium 系浏览器，支持 macOS / Linux / Windows 三平台。

### 通信架构

```
浏览器扩展（chrome-extension://）
    │
    ├── Native Messaging（本地 stdio，低延迟）
    │       ↓
    │   chromeNativeHost.ts
    │
    └── Bridge（云端中继，可穿透防火墙）
            ↓
        mcpServer.ts → @ant/claude-for-chrome-mcp
```

Bridge 模式由功能 gate 控制；Anthropic 内部用户（`USER_TYPE=ant`）始终使用 Bridge。

### 权限模式

```typescript
const PERMISSION_MODES = ['ask', 'skip_all_permission_checks', 'follow_a_plan']
```

### 关键 URL

```typescript
const CHROME_EXTENSION_URL = 'https://claude.ai/chrome'
const CHROME_PERMISSIONS_URL = 'https://clau.de/chrome/permissions'
```

---

## 附录 VI-D：Desktop Handoff（桌面切换）

### 功能描述

`/desktop` 命令提供从 Claude Code CLI 到 Claude 桌面应用（macOS 原生 App）的无缝切换入口，允许用户将当前会话"传递"给桌面应用继续。

### 核心文件

| 文件 | 说明 |
|------|------|
| `src/commands/desktop/desktop.tsx` | 命令入口，渲染 `DesktopHandoff` 组件 |
| `src/components/DesktopHandoff.tsx` | 切换 UI 组件（显示切换选项/状态） |

### 工作机制

`/desktop` 命令仅渲染 `<DesktopHandoff>` 组件，具体的协议握手（URL scheme 或深度链接）在组件内处理。主要用于 macOS 用户在终端与桌面 App 之间平滑切换工作场景。

---

## 附录 VI-E：/btw 侧边提问

### 功能描述

`/btw <问题>` 命令允许用户在不中断当前主流对话的情况下，向 Claude 提出一个**侧边问题**。问题以独立的轻量 Agent 查询处理，答案以气泡形式展示，不会影响主对话的上下文。

### 核心文件

| 文件 | 说明 |
|------|------|
| `src/commands/btw/btw.tsx` | 侧边问题 UI 组件（`BtwSideQuestion`） |
| `src/utils/sideQuestion.ts` | `runSideQuestion()`：独立 Agent 查询封装 |
| `src/utils/forkedAgent.ts` | 获取 cache-safe 参数（`getLastCacheSafeParams()`） |

### 工作机制

```
用户输入 /btw 这段代码有没有 bug?
    │
    ├── 获取 getLastCacheSafeParams()（复用已有 prompt cache）
    ├── runSideQuestion(question, context)
    │       └── 调用 LLM，使用精简 system prompt
    └── 结果以 Markdown 气泡展示，不写入主对话历史
```

使用 `getLastCacheSafeParams()` 让侧边查询复用主对话的 prompt cache 前缀，避免额外 token 消耗。

---

## 附录 VI-F：颜色主题 (/color)

### 功能描述

`/color` 命令允许用户切换 Claude Code 界面的配色方案，改变 Agent 响应、工具调用、系统消息等 UI 元素的颜色风格。

### 核心文件

| 文件 | 说明 |
|------|------|
| `src/commands/color/color.ts` | 颜色主题选择逻辑 |

### 工作机制

可选主题列表存储在配置中，用户选择后写入 `~/.claude/settings.json`，下次启动时生效（无需重启）。

---

## 附录 VI-G：Bug Hunter（/bughunter）

### 功能描述

`/bughunter` 是一个专门为代码 bug 排查调优的模式，加载专用的 system prompt 和工具集，引导 Claude 系统性地检测、复现、定位并修复 bug。

### 核心文件

| 文件 | 说明 |
|------|------|
| `src/commands/bughunter/index.js` | 命令入口（内部实现，源码经编译） |

---

## 附录 VI-H：上下文可视化 (/ctx_viz)

### 功能描述

`/ctx_viz` 命令将当前对话的上下文使用情况以可视化方式展示，帮助用户了解 context window 的占用分布（工具定义、系统提示、对话历史各占多少 token）。

### 核心文件

| 文件 | 说明 |
|------|------|
| `src/commands/ctx_viz/index.js` | 命令入口（编译产物） |

---

## 附录 VI 源码快速导航

```
用户体验与彩蛋
├── Buddy 虚拟伴侣
│   └── src/buddy/                      ← 6 个文件
│       ├── companion.ts                ← PRNG 生成（Mulberry32）
│       ├── types.ts                    ← 18 种物种、5 档稀有度、5 种属性
│       ├── sprites.ts                  ← ASCII art 多帧动画
│       ├── prompt.ts                   ← companion_intro Attachment
│       ├── CompanionSprite.tsx         ← React 渲染
│       └── useBuddyNotification.tsx    ← 气泡通知 Hook
│
├── Effort Level
│   └── src/utils/effort.ts             ← 4 档（low/medium/high/max），模型兼容矩阵
│
├── Claude in Chrome
│   └── src/utils/claudeInChrome/       ← 7 个文件
│       ├── common.ts                   ← 浏览器配置（7+ 种 Chromium 浏览器）
│       ├── mcpServer.ts                ← @ant/claude-for-chrome-mcp 集成
│       ├── setup.ts                    ← Native Messaging Host 安装
│       └── chromeNativeHost.ts         ← 与扩展的 stdio 通信
│
├── Desktop Handoff
│   └── src/commands/desktop/           ← CLI → 桌面 App 无缝切换
│
├── /btw 侧边提问
│   └── src/commands/btw/               ← 不打断主流对话的快速提问
│
├── /color 颜色主题
│   └── src/commands/color/
│
├── /bughunter
│   └── src/commands/bughunter/         ← 专项 bug 排查模式
│
└── /ctx_viz 上下文可视化
    └── src/commands/ctx_viz/           ← Context window 使用分布展示
```

---

## 下一附录

→ [appendix-VII-testing.md](appendix-VII-testing)（测试基础设施与数据治理：VCR 录制回放、Tips 系统、Grove、Referral、Agent Summary）