claude-visual

name

claude-visual

description

为"Claude Code/AI技术原理"系列小红书视频制作内嵌HTML演示页（数据可视化或概念示意图），把抽象机制变成屏幕上能直接看懂的图。每个演示是 self-contained HTML，录屏时浏览器打开+切tab+zoom展示。触发示例："帮我做一个演示xx原理的网页"、"做一个xx的可视化/示意图"、"把xx拆解画成图"、"为这期视频做一个visual"、需要新建或编辑 NNN_topic/visual.html / NNN_topic/xxx_demo.html、为052/053系列等技术拆解视频脚本配演示页。即使用户没明说"做HTML"，只要是为Claude/AI原理拆解视频确定"屏幕上要展示什么"都触发。不触发：视频封面图（用xhscover-claude）、脚本口播词（用xiaohongshu-claude）、与Claude/AI原理无关的通用Web开发或前端任务（用frontend-design）、装饰性插图。

Claude技术原理可视化演示页

这个skill做什么

为"Claude Code/AI技术原理"系列小红书视频做内嵌HTML演示页，目的是把脚本里抽象的机制（缓存、工具调用、上下文管理、消息结构、tokenization等）变成屏幕上一眼就懂的图。每个演示是一个 self-contained HTML 文件（CSS+JS全部内联），录屏时用浏览器打开，作者在视频里切tab/缩放/解说。

核心目标（按优先级排序）

1. 屏幕上看一眼就懂 — 演示页是给观众第一次看的，不是给开发者读代码的。文字要少、关键词要黑底白字、对比要强烈
2. 录屏可读 — 关键内容靠中间，宽度1240-1280px方便录屏zoom，颜色压缩后仍可区分，所有字号 ≥ 14px
3. 同概念跨视图一致 — 同一个东西在多tab里出现时，颜色/标签/位置必须严格一致
4. 传达"变化"和"累积" — 用长度差/颜色变化承载机制叙事，不是堆数字
5. 不偏题 — 这期视频讲什么就只讲什么，相关但不同的概念放下一期

核心心法（默念三遍再下笔）

写每个 label、配每个色、定每个段宽度时，问自己一个问题：

这是给"5 秒完播率下扫一眼的小红书路人观众"看的，不是给"工程师视角的我自己"看的。

这两个视角的 default 偏好正好相反：

• 工程师爱完整、爱精确、爱术语 → 路人爱省力、爱直白、爱熟字
• 工程师觉得"锚点/游标"专业 → 路人觉得"这词没听过要翻译"
• 工程师觉得灰色冷静 → 路人觉得"啥都看不出"
• 工程师觉得 R1/R2/R3 简洁 → 路人要在脑里翻译 Round
• 工程师觉得"两万多字"传达大小 → 路人压根没读那行小字

当你纠结"这样够不够清楚"时，不是字号/对比/颜色不够好，而是你又站到工程师视角去了。每条具体规则都是这条心法的派生。

工作流

1. 拿主题 — 看视频脚本，找出哪一段需要"屏幕上要展示什么"的可视化
2. 选范式 — 数据型(dark) vs 概念型(warm)，见下文决策树
3. 加载对应range参考 — 读 references/style-dark.md 或 references/style-warm.md 里的骨架和配色
4. 写第一稿 — 直接遵守本skill里的硬规则，不要让用户再提醒第二遍
5. playwright截图自验证 — 改完用 playwright-cli 截图，自己看一遍。不要让用户每次手动截图
6. 集成进脚本 — 在视频脚本的录屏步骤里指明"打开 NNN_topic/xxx.html"

选范式：数据型 vs 概念型

数据型（dark主题） — 用 references/style-dark.md

• 主题里有数字、有累积、有"前后对比"、有多状态演变
• 例：缓存命中率、token分布、调用次数、上下文增长
• 视觉骨干：tab切换 + 横向条形图 + 对比表格 + 公式盒
• 参考成品：052_claude_cache/prefix_cache_demo.html

概念型（warm主题） — 用 references/style-warm.md

• 主题里讲"是什么"、"谁负责什么"、"流程怎么走"
• 例：Tool Use契约、Agent循环、消息流向、角色分工
• 视觉骨干：白卡片 + 顶部hero quote + 二分对仗 + pill术语 + 箭头协议
• 参考成品：053_tool_use/visual_section2.html

两种都不像？ — 默认选 dark 数据型，因为它的tab结构能装下更多变化。如果实在是单一静态概念图，warm 更克制。

视觉硬规则（每条都解释为什么）

1. 内容宽度 1240-1280px，关键内容居中

为什么：多tab+bar累积+末端bp label居中，宽度900px会撑爆。1240-1280在常见录屏viewport（1920或屏幕宽）下舒适，关键内容仍在视觉中心。注意：bar width: fit-content 自然超出 view 宽时，要么扩 view，要么用 lblLeft 让末端 label 反向偏移（见规则11）。

2. 同概念在不同视图里必须用同一标签、同一颜色、同一位置规则

为什么：观众在多tab之间切换，靠视觉一致性建立"啊这是同一个东西"的认知。前缀结构里的"用户注入上下文"格子，在消息1/2/3里也必须叫"用户注入上下文"，颜色也要一样。

3. 用长度差表达"累积/滚雪球"

为什么：当主题是"东西在变多"（如缓存累积），相同部分宽度要严格相等，新增部分追加在右侧。禁止让消息1/2/3的总长度一样宽——那会让观众以为没变化。

4. 比例不必精确，但相对大小要直观

为什么：48654 vs 6 这种悬殊比例，如果严格等比"6"那一格就完全看不见。用"差不多大小"的视觉权重让用户输入也能被看到。

5. 严格垂直对齐

为什么：多色块并排时baseline错1px观众都会觉得"哪里不对"。用 display: flex; align-items: center + 各seg内层结构完全一致来保证。

6. 留白克制

为什么：上下边距太大显得空，太小显得挤。卡片到外边缘60-80px、card内padding 24-32px 是经验值。色块内文字两侧至少留8-12px。

7. 多个图就用多个图例

为什么：把"前缀结构"和"token分布"的图例挤一行很丑，观众不知道每个色对应哪个图。

8. 导航栏在标题下方

为什么：录屏时点tab按钮要顺手，放标题下方的位置肌肉记忆最稳。

9. 字号底线 14px（图里所有字都不能更小）

为什么：录屏给路人看，不是给开发者读的代码。Tab 1 的 JSON 主字号 14px 是参考锚点——bar segment 主文字、副文字（token-count）、bp label、entry 条目、tooltip、turn-tag、legend、write-tag 全部要 ≥14px。这个规则反过来约束 segment 宽度：bar 段需要装下 14px 中文字 + padding，常见 segment 100-220px 起。底线靠外部锚点（JSON 主字号），不靠"我觉得够用"。

10. 承担"角色对立"的元素必须用饱和色对照，灰色只做装饰底

为什么：dark theme 里灰色（#aaa, #888）跟正文白色文字会"混淆"——不是亮度问题，是没颜色的元素无法担当语义。当主题有对立角色（静vs动、错vs对、冷vs热），必须用饱和色对照（如天青蓝 #38bdf8 vs 暖橙 #ff8a3d 的冷暖对）。颜色本身就成了语义载体，观众看一眼就分清角色。灰色只能给"装饰底色 / 注释字 / dim 默认状态"。

11. 末端 label 必须能反向偏移，避免 view 边界裁切

为什么：bp dot label 默认 left: 50%; transform: translateX(-50%) 居中在 dot 上方。但 bar 末端的 dot label 居中向右延伸时会超出 view 边界被截。在 seg() 函数加 lblLeft 选项：{left: auto; right: 0; transform: translateX(0)} 让 label 向 dot 左侧（bar 内侧）展开。同样，bp 之间距离 < label 宽时（如 R1 hello 段 90px 而 label 95px）必然重叠 — 要么加宽 segment、要么换 lblLeft 让相邻 label 错开方向。理论上"差不多够"在实际渲染里会重叠/裁切，必须 playwright 截图确认。

文案硬规则

1. 中文优先，拒绝英文哲学引言

为什么：观众是中文用户，"The model never executes anything on its own."这种引言看着很怪。直接用中文口语概括："模型负责说，客户端负责做"。

2. 关键术语黑底白字 pill

为什么：核心概念词（Tool Use、Prompt Cache、Cache Read 等）需要从正文里"跳出来"。用 background:#1a1a1a; color:#fff; font-family: JetBrains Mono 的圆角块。

3. 对仗结构二分法

为什么：当主题有清晰对立角色（模型 vs 客户端、写入 vs 读取、冷启动 vs 命中），用左右对称布局 + 配对动词 + 协议箭头。每边动词数量、检查点数量、字数都要对仗。

4. 标签缩写到一眼能读完

为什么：hook/MCP/skills/CLAUDE.md 在小色块里挤成一团，缩成 .../CLAUDE.md 抓住核心文件名即可。完整列表放在第一个介绍tab里。

5. 用户输入用真实情境，不要占位符

为什么："hello"比"hi"更像真用户会输入的，"thank you"比"text 3"更有真实对话感。占位符让观众觉得是教程不是真实数据。

6. 删元数据，留内容

为什么：(35字符) 这种字符数没意义，不如直接显示 "Hi! What would you like to work on?" 的真内容。数字不会教学，内容才会。

7. 不要装饰性副标题/引言

为什么：什么"一份契约"、"探索AI的内部"这种副标题不传达信息，删掉让主标题更突出。

8. 标题反差感 + 黑话

为什么：小红书5秒完播率靠hook。"hello就三万token了?还有提示词缓存"比"Prompt Cache原理"留人。

9. 术语只能从口播脚本里找，不能自创

为什么：UI label 是观众"眼睛看的"，口播是"耳朵听的"，两者必须严丝合缝。如果脚本说"永远钉在 system 末尾"，UI 就用"钉"或派生词；如果自创"锚点/游标"这种听着专业的词，观众视频里听一套、屏幕看一套，要做"翻译"才能对上。写 label 前先翻一遍口播脚本，把反复出现的核心动词作为词根。

10. 单字 label 太抽象，用含字根的双字词

为什么："静"/"动"两个单字虽然简洁，但脱离上下文时观众不知道指什么。换成"静止"/"移动"既保留字根（跟 tab 名"两静一动"呼应），又够具象。Tab 标题可以用 4 字短语（"两静一动"）做高度概括，但 dot label / 内嵌标签必须双字以上才有"所指"。

11. 中文界面里用中文序号，不用 R1/R2 缩写

为什么：英文缩写 "R1/R2/R3" 对工程师自然，但中文观众要在脑里翻译"Round 1"。改用"第 1 轮 / 第 2 轮 / 第 3 轮"——多 3 个字符宽度，但消除认知翻译成本。同理：用"第 N 次 / 第 N 步"代替 "Step N / N-th"。

信息密度规则

1. 删冗余统计卡片

有了视觉条形图就别再列一遍数字卡片，重复信息浪费屏幕。

2. 删多余图例

颜色已经在bar segments里直接标了文字标签的，下面就不要再列图例。

3. 多tab整合相关视图

三轮对比、成本影响、公式盒这种延伸数据应该放进同一HTML的多tab，而不是开新文件。但不能塞与本期主题无关的tab（如这期讲prefix cache就不要塞cache_control解释）。

4. 表格行结构对齐

当多个表格出现在同一HTML里（比如三轮对比表+成本表），行的顺序和命名要对齐，让观众用眼扫的时候能匹配。

5. 同义不同形 ≠ 补充信息，是冗余

典型反面：AUTOMATIC tag + Automatic 大字 + 自动模式·副标题 + 3 条规则——同一件事说了四遍。section-label "3 个 breakpoint：2 个钉死 · 1 个跟着最新 user 移动" + 下方 note-box 详细解释——note 已经讲完了，section-label 多余。图里展示三轮 lookback 的 ✓×箭头 + note 文字逐句复述三轮——文字在解说图，不是讲新东西。判断方法：每段文字问一句"删了观众还能看懂吗？"，能看懂就删。只保留图传达不了的结论。

6. 装饰性数据没承担信息就删

典型反面：在 sys[2] 段标"行为准则·两万多字"——但 sys[2] segment 比 sys[1] 长本身已经传达"很大"，"两万多字"是装饰。(35字符) 这种字符数计数也属于此类。视觉本身能传达的量级，不要用文字再标一遍。

自验证（硬规则，已在memory里）

改完任何视觉调整必须自己用 playwright-cli 截图验证：

playwright-cli open file:///full/path/to/visual.html
playwright-cli screenshot

不要让用户每次手动截图。截图后自己看一遍，特别检查：

• 留白是否合适（上、下、左、右、内padding）
• 多色块是否垂直对齐
• 同一概念跨tab是否一致
• 录屏zoom区域内是否有被裁掉的元素
• 所有字号 ≥ 14px（图里最小的字不能比 JSON 主字号小）
• bp dot label 之间是否重叠（间距 < label 宽就重叠 — 用浏览器 inspect 量一下两个相邻 label 的中心距离 vs label 实际宽度）
• bar 末端的 label / write-tag / tooltip 是否被 view 边界裁切（特别是 R3 那种最长的 bar；解决：扩 view 宽 / 用 lblLeft 反向偏移 / 缩短文字三选一）
• 承担"角色对立"的元素是否用了饱和色对照（如果你看到灰色 dot 担当"静止"角色，立刻换饱和色）

技术准确性（硬规则，已在memory里）

视觉里说出来的任何技术结论都要有出处：

• 文档原文链接（platform.claude.com/docs/...）
• 实际运行的API响应数据（带timestamp截图）
• 不能凭直觉合理化"为什么这样设计"

如果不确定，用中性表述（"就是你的hello"）而不是断言（"6 tokens不走缓存"）。

反模式清单（用户明确反对过的）

• ❌ 严格等比例 → 关键元素看不见
• ❌ 多视图长度一样 → 看不出"在累积"
• ❌ 图例一行挤完 → 不知道哪个图对哪个图例
• ❌ 长名全写 → 在小色块里挤成一团
• ❌ 占位文字（hi、placeholder、test） → 不像真实数据
• ❌ 字符数计数 → 不如直接显示内容
• ❌ 英文引言副标题 → 跟视频整体气质不符
• ❌ 装饰性术语（"一份契约"、"探索奥秘"） → 不传达信息
• ❌ 静态截图依赖用户 → 改完自己用playwright看
• ❌ 凭感觉解释技术原理 → 必须有文档/实证支撑
• ❌ 偏题塞相关概念 → 一期视频一个主题
• ❌ 自创术语听着专业但脱离口播（如"锚点/游标"） → 用脚本里反复出现的核心动词
• ❌ 单字 label（"静"、"动"）抽象 → 用含字根双字词（"静止"、"移动"）
• ❌ 灰色担当语义角色（如静止 dot 用 #aaa） → 饱和色对照（蓝 vs 橙）
• ❌ 英文缩写做轮次/序号（R1、R2、R3） → 中文序号（第 1 轮）
• ❌ 装饰性数据细节（"两万多字"） → 让 segment 长度本身传达
• ❌ 同义不同形重复（tag + 大字 + 副标题 + 规则四遍同义） → 一种表达即可
• ❌ 字号 < 14px（图里最小的字比 JSON 主字号小） → 录屏给路人看不清

配色与字体（共用）

字体栈：

• 中文：-apple-system, "PingFang SC", "Helvetica Neue", sans-serif
• 等宽（代码/数据/术语）："JetBrains Mono", "SF Mono", Menlo, monospace

通用色板（具体色值见各范式参考）：

• 橙系（主/cache_creation/角色A "动/写/暖"）：#c75a1f / #d97706 / #ff8a3d / #f59e0b
• 天青蓝（角色B "静/读/冷"，跟橙形成冷暖对比）：#38bdf8 (sky-400) / #60a5fa (blue-400)
• 蓝系（input/客户端，区别于天青）：#2c5d8c / #2563eb / #3b82f6
• 绿系（cache_read/正面/省钱/✓命中）：#059669 / #10b981 / #2d8f5a
• 红系（miss/×/冷启动/警告）：#dc2626 / #f87171 / #5a1f1a
• 黑（关键术语 pill 背景）：#1a1a1a
• 灰只做装饰底（dim 注释字、默认底色）：#888 / #aaa — 不能担当语义角色

每种色在一个HTML里要有固定语义，不要随机换。如绿色一旦代表"cache hit"就不能在另一个图里代表别的东西。

冷暖对比的典型搭配：

• 角色对立（静vs动、读vs写、客户端vs服务端、冷启动vs命中）→ 天青蓝 #38bdf8 vs 暖橙 #ff8a3d
• 状态成败（命中vs错过）→ 绿 #10b981 vs 红 #f87171
• 灰色不参与"对立"，只做不重要的背景元素（dot 默认底、注释字）

集成进脚本

完成HTML后在视频脚本的录屏步骤里写：

📹 [N]. 浏览器打开 NNN_topic/xxx.html
📹 [N+1]. 切到"消息2：缓存命中"tab，zoom到token分布条

文件命名：

• 数据型：{topic}_demo.html（如 prefix_cache_demo.html）
• 概念型：visual_section{N}.html 或 visual_{topic}.html