附录 VI：用户体验与彩蛋

Markdown

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

附录 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 级）

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

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

属性系统

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

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

外观组合

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

确定性生成

// 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 档位定义、模型兼容性检查、数值解析

档位定义

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

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

模型支持矩阵

// 支持 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）可解锁更多模型

关键常量/配置

# 强制所有模型支持 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。

权限模式

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

关键 URL

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（测试基础设施与数据治理：VCR 录制回放、Tips 系统、Grove、Referral、Agent Summary）