给 Claude Code 配一块“会说人话”的副屏

Claude Code 很能干，问题也很明显：它太爱在终端里写长文了。

你让它分析项目结构，它回你一屏架构说明；你让它给重构方案，它列出十几条步骤；你让它排查 Bug，日志、推理、建议搅在一起。内容可能没问题，可读起来真的费劲。

这时候，副屏的价值就出来了。🖥️

它不负责替 Claude Code 思考，而是把 Claude Code 的输出，翻译成你一眼能看懂的页面：

架构方案变成流程图和模块卡片
重构计划变成可勾选的任务清单
数据分析变成表格、图表和关键结论
多个实现方案变成可点击对比项
你的点击、输入、选择，会回传给 Claude Code 继续执行

终端负责干活，副屏负责表达。两边分工后，整个开发过程顺眼多了。

这块副屏，到底解决什么痛点？

想象一个真实场景。

你在接手一个陌生项目，问 Claude Code：

帮我分析登录链路，并给出接入企业 SSO 的改造方案。

普通终端模式下，它可能吐出 100 多行内容。你得来回滚动，自己在脑中拼出调用关系，还要从一堆文字里找“改哪些文件”“风险在哪儿”“先做什么”。

副屏模式可以直接给你一张页面：

[登录链路概览]
浏览器 → /api/login → Auth Service → User DB → Token
                         └→ OAuth Provider

[需要修改]
☐ auth/login.ts
☐ middleware/session.ts
☐ config/oauth.ts

[接入方案]
( ) 保留旧登录，逐步灰度
( ) 直接切换到 SSO

[风险提示]
⚠ Token 刷新逻辑需要兼容旧客户端

[按钮] 生成改造代码

你点一下“保留旧登录，逐步灰度”，再补一句“旧客户端至少兼容两周”，Claude Code 就能拿到明确指令继续干活。

少看大段文字，多做判断。这才是副屏该干的事。

核心思路：把回答拆成「内容」和「界面」

别指望模型每次都自动产出好看的页面。稳定的做法，是让它输出一份结构化 UI 描述，再由浏览器负责渲染。

整个链路很简单：

Claude Code
   ↓
结构化数据（JSON / Markdown 标记）
   ↓
本地 Bridge 服务
   ↓
浏览器副屏页面
   ↓
点击、输入、选择
   ↓
回传 Claude Code

这里有三个关键角色：

| 角色 | 做什么 | | --- | --- | | Claude Code | 分析任务、生成内容、根据反馈继续执行 | | Bridge 服务 | 接收输出，推送给网页，接收网页事件 | | 副屏页面 | 把内容渲染成卡片、表格、图表、按钮等组件 |

别一上来就造一个复杂平台。做一个能跑通的最小版本，半天就够。

一个够用的最小版本

建议用这套组合：

Node.js + Express：本地起一个轻量服务
Socket.IO：实时把内容推到副屏
React / Vue / 原生 HTML：渲染页面
JSON Schema：约束 Claude Code 输出格式

如果你不想碰 React，原生 HTML 也完全能用。副屏的重点是信息展示，不是前端炫技。

1. 约定 Claude Code 的输出格式

让 Claude Code 在需要展示时，输出被标记包裹的 JSON：

<sidepanel>
{
  "title": "登录链路分析",
  "summary": "当前系统支持账号密码登录，SSO 接入点位于 Auth Service。",
  "cards": [
    {
      "type": "flow",
      "title": "调用流程",
      "items": ["Web", "API Gateway", "Auth Service", "User DB"]
    },
    {
      "type": "checklist",
      "title": "改造文件",
      "items": ["src/auth/login.ts", "src/middleware/session.ts"]
    }
  ],
  "actions": [
    {
      "id": "generate_plan",
      "label": "生成详细改造计划",
      "style": "primary"
    }
  ]
}
</sidepanel>

普通解释仍然留在终端。需要你看、需要你选、需要你确认的信息，再进入 <sidepanel>。

这个边界很重要。

什么都往副屏塞，只会把终端里的拥挤搬到网页里，换个地方继续乱。

2. 给 Claude Code 加一段固定指令

可以把下面这段放进项目的 CLAUDE.md，或者作为你自己的常用提示词：

当任务涉及方案对比、执行计划、架构说明、数据汇总、需要用户确认的选项时：

1. 在终端保留简短结论与必要的技术说明。
2. 额外输出 <sidepanel> 包裹的 JSON。
3. JSON 必须包含 title、summary、cards、actions。
4. 信息优先使用卡片、表格、清单、流程和选项，不要把长段落原样塞进 JSON。
5. actions 中的每个按钮都要有明确 id，方便接收用户反馈。
6. 没有需要展示或确认的内容时，不输出 sidepanel。

这段指令的效果很直接：Claude Code 会知道，什么内容该写成文字，什么内容该画成界面。

副屏页面应该长什么样？

别把它做成“第二个聊天窗口”。聊天窗口已经够多了。

一个好用的副屏，建议固定成四个区域：

┌──────────────────────────────────────┐
│ 任务标题 + 当前状态                   │
├──────────────────────────────────────┤
│ 一句话结论                            │
├──────────────────────────────────────┤
│ 卡片区：流程 / 表格 / 风险 / 文件清单 │
├──────────────────────────────────────┤
│ 操作区：确认、选择、输入、继续执行     │
└──────────────────────────────────────┘

常用组件不需要太多，下面这些已经覆盖大部分开发场景：

摘要卡片：告诉你目前结论，别超过三行
流程卡片：适合请求链路、部署流程、数据流
文件清单：显示要新增、修改、删除的文件
方案对比表：把成本、风险、工期摆在一起
待办清单：适合重构、迁移、排障步骤
风险提示：红黄绿标识，别让关键坑藏在正文第 27 行
确认按钮：如“按方案 A 执行”“先只生成补丁”
文本输入框：把你的补充要求回传给 Claude Code

页面不必花里胡哨。你半夜盯着 Bug 时，真正需要的是“哪里出错、怎么处理、点哪里继续”，不是渐变玻璃拟态。

让交互真正回传：副屏不是展示板

只展示答案，确实比终端好读，但还差一口气。

真正舒服的体验，是你在副屏上操作，Claude Code 能立刻收到事件。

比如你点击：

{
  "action": "choose_migration_strategy",
  "value": "gray_release",
  "note": "灰度期间保留旧接口两周"
}

Bridge 服务把这条事件转换成一段消息，写入 Claude Code 当前会话：

用户已选择方案：gray_release
补充要求：灰度期间保留旧接口两周
请基于这个决策更新实施计划，并列出准备修改的文件。暂时不要直接改代码。

这一步会让工作流从“我看 AI 说话”，变成“我和 AI 一起推进任务”。差别很大。

建议设计的回传事件

| 场景 | 回传内容 | | --- | --- | | 方案选择 | 选中的方案 ID、补充备注 | | 文件确认 | 勾选的文件列表 | | 风险处理 | 接受、忽略、延后处理 | | 代码生成 | 生成补丁、直接写入、只看 Diff | | 任务推进 | 开始下一步、暂停、重新分析 |

按钮文案一定要具体。

别写“确认”“继续”这种谜语按钮。过半小时回来，你自己都不知道确认了什么。

推荐这样写：

按灰度方案生成改造清单
仅生成 Diff，不写入文件
先修复鉴权问题
保留现有 API，继续分析

一个实战 Prompt：让方案展示更清楚

你可以直接这样对 Claude Code 下任务：

分析当前仓库的支付回调逻辑，找出可能导致重复扣款的风险。

请把结果输出到副屏：
- 顶部写一句最重要的结论
- 用流程卡片展示回调处理链路
- 用表格列出风险点、触发条件、影响范围、修复建议
- 把需要我决策的地方做成可选项
- 给出“仅生成修复方案”和“直接创建补丁”两个按钮

终端只保留简短说明，不要重复副屏内容。

你会发现，模型的回答立刻从“阅读理解题”变成“待处理事项面板”。

信息密度怎么控制？别把副屏也做成垃圾场

副屏最大的敌人，是贪心。

Claude Code 分析得很细，你就想全展示；页面做着做着，卡片越来越多；到头来，用户还是得滚半天。那就白忙了。

给自己定几条硬规则：

顶部摘要控制在 80 字以内
一次最多展示 3 个核心结论
风险点超过 5 个时，只露出最高优先级的 5 个
代码不要直接塞进卡片，提供“查看 Diff”入口
表格超过 8 行时，支持筛选或折叠
每个页面只放一个主操作按钮

副屏负责帮你做决策，不负责保存所有历史记录。

完整细节可以留在终端、Markdown 报告或项目文件里。

常见翻车点 ⚠️

1. 让模型直接输出 HTML

看起来省事，实际很容易失控。

模型可能输出不完整标签、混入脚本、样式乱飞。更麻烦的是，页面结构很难统一，后期维护像踩乐高。

更稳的做法： 模型输出 JSON，前端用固定组件渲染。

2. JSON 格式偶尔坏掉

大模型有时会多写一句解释，或者漏一个逗号。别装作这事不会发生。

可以这样兜底：

用 <sidepanel> 标签截取内容
解析失败时把原文展示为 Markdown
给模型返回格式错误提示，让它自动重试一次
用 JSON Schema 校验字段类型

3. 把敏感信息直接推到浏览器

副屏通常跑在本机，可也别掉以轻心。

数据库密码、Access Token、用户手机号、生产环境日志，默认应该脱敏。尤其是你演示、录屏、共享屏幕的时候，一次手滑就够你写事故复盘了。

4. 回传操作没有二次确认

“直接写入文件”“执行迁移”“删除无用模块”这类操作，必须加确认层。

建议把危险动作拆成两步：

点击：生成执行计划
   ↓
展示：预计修改 12 个文件，删除 3 个文件
   ↓
点击：确认执行

让 AI 自动化，不等于把方向盘焊死。

适合从哪些场景开始？

别急着给所有任务接副屏。下面几类最值得优先做：

代码库分析：模块关系、调用链、依赖风险，一张图比一屏字好懂。
重构计划：哪些文件要动、改动顺序、验证方式，适合做成任务面板。
Bug 排查：把现象、证据、猜测、下一步实验分栏展示，思路不会乱。
多方案决策：性能优先还是开发速度优先？直接点选，不用在对话里反复描述。
数据处理：CSV 汇总、接口返回分析、日志统计，表格和图表比文本强太多。
部署发布：环境检查、变更列表、回滚方案，放在一个面板里最安心。

如果你每天都要读 Claude Code 的长回答，这个副屏很值得做。它未必让模型更聪明，却能让你少在终端里迷路，少花时间翻记录，早点把事情做完。

给 Claude Code 配一块“会说人话”的副屏：把长回答变成可交互页面