better-dsh 0.2.4 → 0.2.5-b

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/creative/creative-ascii-art.md

@@ -0,0 +1,338 @@
+---
+title: "Ascii Art — ASCII art: pyfiglet, cowsay, boxes, image-to-ascii"
+sidebar_label: "Ascii Art"
+description: "ASCII art：pyfiglet、cowsay、boxes、image-to-ascii"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Ascii Art
+
+ASCII art：pyfiglet、cowsay、boxes、image-to-ascii。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/creative/ascii-art` |
+| 版本 | `4.0.0` |
+| 作者 | 0xbyt4, Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `ASCII`, `Art`, `Banners`, `Creative`, `Unicode`, `Text-Art`, `pyfiglet`, `figlet`, `cowsay`, `boxes` |
+| 相关 skill | [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# ASCII Art Skill
+
+多种工具，满足不同的 ASCII art 需求。所有工具均为本地 CLI 程序或免费 REST API——无需 API 密钥。
+
+## 工具 1：文字横幅（pyfiglet——本地）
+
+将文本渲染为大型 ASCII art 横幅。内置 571 种字体。
+
+### 安装
+
+```bash
+pip install pyfiglet --break-system-packages -q
+```
+
+### 用法
+
+```bash
+python3 -m pyfiglet "YOUR TEXT" -f slant
+python3 -m pyfiglet "TEXT" -f doom -w 80    # Set width
+python3 -m pyfiglet --list_fonts             # List all 571 fonts
+```
+
+### 推荐字体
+
+| 风格 | 字体 | 适用场景 |
+|-------|------|----------|
+| 简洁现代 | `slant` | 项目名称、标题 |
+| 粗体块状 | `doom` | 标题、Logo |
+| 大而易读 | `big` | 横幅 |
+| 经典横幅 | `banner3` | 宽屏显示 |
+| 紧凑 | `small` | 副标题 |
+| 赛博朋克 | `cyberlarge` | 科技主题 |
+| 3D 效果 | `3-d` | 启动画面 |
+| 哥特风 | `gothic` | 戏剧性文字 |
+
+### 提示
+
+- 预览 2-3 种字体，让用户选择喜欢的
+- 短文本（1-8 个字符）与 `doom` 或 `block` 等精细字体搭配效果最佳
+- 长文本更适合 `small` 或 `mini` 等紧凑字体
+
+## 工具 2：文字横幅（asciified API——远程，无需安装）
+
+将文本转换为 ASCII art 的免费 REST API。支持 250+ 种 FIGlet 字体。直接返回纯文本——无需解析。当 pyfiglet 未安装时使用，或作为快速替代方案。
+
+### 用法（通过终端 curl）
+
+```bash
+# Basic text banner (default font)
+curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello+World"
+
+# With a specific font
+curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Slant"
+curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Doom"
+curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Star+Wars"
+curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=3-D"
+curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Banner3"
+
+# List all available fonts (returns JSON array)
+curl -s "https://asciified.thelicato.io/api/v2/fonts"
+```
+
+### 提示
+
+- 在 text 参数中将空格 URL 编码为 `+`
+- 响应为纯文本 ASCII art——无 JSON 包装，可直接显示
+- 字体名称区分大小写；使用 fonts 端点获取精确名称
+- 在任何带有 curl 的终端中均可使用——无需 Python 或 pip
+
+## 工具 3：Cowsay（消息艺术）
+
+经典工具，将文本包裹在带有 ASCII 角色的对话气泡中。
+
+### 安装
+
+```bash
+sudo apt install cowsay -y    # Debian/Ubuntu
+# brew install cowsay         # macOS
+```
+
+### 用法
+
+```bash
+cowsay "Hello World"
+cowsay -f tux "Linux rules"       # Tux the penguin
+cowsay -f dragon "Rawr!"          # Dragon
+cowsay -f stegosaurus "Roar!"     # Stegosaurus
+cowthink "Hmm..."                  # Thought bubble
+cowsay -l                          # List all characters
+```
+
+### 可用角色（50+）
+
+`beavis.zen`, `bong`, `bunny`, `cheese`, `daemon`, `default`, `dragon`,
+`dragon-and-cow`, `elephant`, `eyes`, `flaming-skull`, `ghostbusters`,
+`hellokitty`, `kiss`, `kitty`, `koala`, `luke-koala`, `mech-and-cow`,
+`meow`, `moofasa`, `moose`, `ren`, `sheep`, `skeleton`, `small`,
+`stegosaurus`, `stimpy`, `supermilker`, `surgery`, `three-eyes`,
+`turkey`, `turtle`, `tux`, `udder`, `vader`, `vader-koala`, `www`
+
+### 眼睛/舌头修饰符
+
+```bash
+cowsay -b "Borg"       # =_= eyes
+cowsay -d "Dead"       # x_x eyes
+cowsay -g "Greedy"     # $_$ eyes
+cowsay -p "Paranoid"   # @_@ eyes
+cowsay -s "Stoned"     # *_* eyes
+cowsay -w "Wired"      # O_O eyes
+cowsay -e "OO" "Msg"   # Custom eyes
+cowsay -T "U " "Msg"   # Custom tongue
+```
+
+## 工具 4：Boxes（装饰性边框）
+
+在任意文本周围绘制装饰性 ASCII art 边框/框架。内置 70+ 种设计。
+
+### 安装
+
+```bash
+sudo apt install boxes -y    # Debian/Ubuntu
+# brew install boxes         # macOS
+```
+
+### 用法
+
+```bash
+echo "Hello World" | boxes                    # Default box
+echo "Hello World" | boxes -d stone           # Stone border
+echo "Hello World" | boxes -d parchment       # Parchment scroll
+echo "Hello World" | boxes -d cat             # Cat border
+echo "Hello World" | boxes -d dog             # Dog border
+echo "Hello World" | boxes -d unicornsay      # Unicorn
+echo "Hello World" | boxes -d diamonds        # Diamond pattern
+echo "Hello World" | boxes -d c-cmt           # C-style comment
+echo "Hello World" | boxes -d html-cmt        # HTML comment
+echo "Hello World" | boxes -a c               # Center text
+boxes -l                                       # List all 70+ designs
+```
+
+### 与 pyfiglet 或 asciified 组合使用
+
+```bash
+python3 -m pyfiglet "HERMES" -f slant | boxes -d stone
+# Or without pyfiglet installed:
+curl -s "https://asciified.thelicato.io/api/v2/ascii?text=HERMES&font=Slant" | boxes -d stone
+```
+
+## 工具 5：TOIlet（彩色文字艺术）
+
+类似 pyfiglet，但支持 ANSI 颜色效果和视觉滤镜。非常适合终端视觉效果。
+
+### 安装
+
+```bash
+sudo apt install toilet toilet-fonts -y    # Debian/Ubuntu
+# brew install toilet                      # macOS
+```
+
+### 用法
+
+```bash
+toilet "Hello World"                    # Basic text art
+toilet -f bigmono12 "Hello"            # Specific font
+toilet --gay "Rainbow!"                 # Rainbow coloring
+toilet --metal "Metal!"                 # Metallic effect
+toilet -F border "Bordered"             # Add border
+toilet -F border --gay "Fancy!"         # Combined effects
+toilet -f pagga "Block"                 # Block-style font (unique to toilet)
+toilet -F list                          # List available filters
+```
+
+### 滤镜
+
+`crop`、`gay`（彩虹）、`metal`、`flip`、`flop`、`180`、`left`、`right`、`border`
+
+**注意**：toilet 输出带颜色的 ANSI 转义码——在终端中正常显示，但在某些场景下可能无法渲染（例如纯文本文件、部分聊天平台）。
+
+## 工具 6：图片转 ASCII Art
+
+将图片（PNG、JPEG、GIF、WEBP）转换为 ASCII art。
+
+### 方案 A：ascii-image-converter（推荐，现代化）
+
+```bash
+# Install
+sudo snap install ascii-image-converter
+# OR: go install github.com/TheZoraiz/ascii-image-converter@latest
+```
+
+```bash
+ascii-image-converter image.png                  # Basic
+ascii-image-converter image.png -C               # Color output
+ascii-image-converter image.png -d 60,30         # Set dimensions
+ascii-image-converter image.png -b               # Braille characters
+ascii-image-converter image.png -n               # Negative/inverted
+ascii-image-converter https://url/image.jpg      # Direct URL
+ascii-image-converter image.png --save-txt out   # Save as text
+```
+
+### 方案 B：jp2a（轻量级，仅支持 JPEG）
+
+```bash
+sudo apt install jp2a -y
+jp2a --width=80 image.jpg
+jp2a --colors image.jpg              # Colorized
+```
+
+## 工具 7：搜索预制 ASCII Art
+
+从网络搜索精选 ASCII art。使用 `terminal` 配合 `curl`。
+
+### 来源 A：ascii.co.uk（推荐用于预制艺术）
+
+大量按主题分类的经典 ASCII art 合集。艺术内容位于 HTML `<pre>` 标签内。使用 curl 获取页面，再用简短的 Python 代码提取艺术内容。
+
+**URL 格式：** `https://ascii.co.uk/art/{subject}`
+
+**第一步——获取页面：**
+
+```bash
+curl -s 'https://ascii.co.uk/art/cat' -o /tmp/ascii_art.html
+```
+
+**第二步——从 pre 标签中提取艺术内容：**
+
+```python
+import re, html
+with open('/tmp/ascii_art.html') as f:
+    text = f.read()
+arts = re.findall(r'<pre[^>]*>(.*?)</pre>', text, re.DOTALL)
+for art in arts:
+    clean = re.sub(r'<[^>]+>', '', art)
+    clean = html.unescape(clean).strip()
+    if len(clean) > 30:
+        print(clean)
+        print('\n---\n')
+```
+
+**可用主题**（用作 URL 路径）：
+- 动物：`cat`、`dog`、`horse`、`bird`、`fish`、`dragon`、`snake`、`rabbit`、`elephant`、`dolphin`、`butterfly`、`owl`、`wolf`、`bear`、`penguin`、`turtle`
+- 物品：`car`、`ship`、`airplane`、`rocket`、`guitar`、`computer`、`coffee`、`beer`、`cake`、`house`、`castle`、`sword`、`crown`、`key`
+- 自然：`tree`、`flower`、`sun`、`moon`、`star`、`mountain`、`ocean`、`rainbow`
+- 角色：`skull`、`robot`、`angel`、`wizard`、`pirate`、`ninja`、`alien`
+- 节日：`christmas`、`halloween`、`valentine`
+
+**提示：**
+- 保留艺术家签名/缩写——这是重要的礼仪
+- 每个页面包含多件艺术作品——为用户挑选最合适的
+- 通过 curl 可靠运行，无需 JavaScript
+
+### 来源 B：GitHub Octocat API（有趣的彩蛋）
+
+返回一个带有智慧语录的随机 GitHub Octocat。无需认证。
+
+```bash
+curl -s https://api.github.com/octocat
+```
+
+## 工具 8：有趣的 ASCII 实用工具（通过 curl）
+
+这些免费服务直接返回 ASCII art——非常适合作为有趣的附加内容。
+
+### QR 码转 ASCII Art
+
+```bash
+curl -s "qrenco.de/Hello+World"
+curl -s "qrenco.de/https://example.com"
+```
+
+### 天气转 ASCII Art
+
+```bash
+curl -s "wttr.in/London"          # Full weather report with ASCII graphics
+curl -s "wttr.in/Moon"            # Moon phase in ASCII art
+curl -s "v2.wttr.in/London"       # Detailed version
+```
+
+## 工具 9：LLM 生成自定义艺术（兜底方案）
+
+当上述工具无法满足需求时，直接使用以下 Unicode 字符生成 ASCII art：
+
+### 字符调色板
+
+**方框绘制：** `╔ ╗ ╚ ╝ ║ ═ ╠ ╣ ╦ ╩ ╬ ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼ ╭ ╮ ╰ ╯`
+
+**块元素：** `░ ▒ ▓ █ ▄ ▀ ▌ ▐ ▖ ▗ ▘ ▝ ▚ ▞`
+
+**几何与符号：** `◆ ◇ ◈ ● ○ ◉ ■ □ ▲ △ ▼ ▽ ★ ☆ ✦ ✧ ◀ ▶ ◁ ▷ ⬡ ⬢ ⌂`
+
+### 规则
+
+- 最大宽度：每行 60 个字符（终端安全）
+- 最大高度：横幅 15 行，场景 25 行
+- 仅限等宽字体：输出必须在等宽字体下正确渲染
+
+## 决策流程
+
+1. **将文本作为横幅** → 若已安装 pyfiglet 则使用，否则通过 curl 调用 asciified API
+2. **将消息包裹在有趣的角色艺术中** → cowsay
+3. **添加装饰性边框/框架** → boxes（可与 pyfiglet/asciified 组合使用）
+4. **特定事物的艺术**（猫、火箭、龙）→ 通过 curl + 解析使用 ascii.co.uk
+5. **将图片转换为 ASCII** → ascii-image-converter 或 jp2a
+6. **QR 码** → 通过 curl 使用 qrenco.de
+7. **天气/月相艺术** → 通过 curl 使用 wttr.in
+8. **自定义/创意内容** → 使用 Unicode 调色板进行 LLM 生成
+9. **任何工具未安装** → 安装它，或回退到下一个选项

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/creative/creative-ascii-video.md

@@ -0,0 +1,261 @@
+---
+title: "Ascii Video — ASCII 视频：将视频/音频转换为彩色 ASCII MP4/GIF"
+sidebar_label: "Ascii Video"
+description: "ASCII 视频：将视频/音频转换为彩色 ASCII MP4/GIF"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Ascii Video
+
+ASCII 视频：将视频/音频转换为彩色 ASCII MP4/GIF。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/creative/ascii-video` |
+| 平台 | linux, macos, windows |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# ASCII 视频生产流水线
+
+## 使用时机
+
+当用户请求以下内容时使用：ASCII 视频、文字艺术视频、终端风格视频、字符艺术动画、复古文字可视化、ASCII 音频可视化器、将视频转换为 ASCII 艺术、矩阵风格特效，或任何动态 ASCII 输出。
+
+## 内容概述
+
+用于 ASCII 艺术视频的生产流水线——支持任意格式。将视频/音频/图像/生成式输入转换为彩色 ASCII 字符视频输出（MP4、GIF、图像序列）。涵盖：视频转 ASCII、音频响应式音乐可视化器、生成式 ASCII 艺术动画、视频+音频混合响应、文字/歌词叠加、实时终端渲染。
+
+## 创作标准
+
+这是视觉艺术。ASCII 字符是媒介；电影是标准。
+
+**在写下任何一行代码之前**，先阐明创作概念。氛围是什么？这讲述了怎样的视觉故事？是什么让这个项目与其他所有 ASCII 视频不同？用户的 prompt（提示词）只是起点——以创作野心去诠释它，而非字面转录。
+
+**首次渲染即达到卓越水准，不可妥协。** 输出必须在无需修改的情况下具有视觉冲击力。如果看起来平庸、单调，或像"AI 生成的 ASCII 艺术"，那就是错的——在交付前重新思考创作概念。
+
+**超越参考词汇表。** 参考资料中的特效目录、shader（着色器）预设和调色板库只是起点词汇。每个项目都应组合、修改并发明新的模式。目录是颜料——你来作画。
+
+**主动发挥创造力。** 当项目需要时，扩展 skill 的词汇表。如果参考资料无法满足创作愿景，就自己构建。至少加入一个用户没有要求但会欣赏的视觉时刻——一个过渡、一个特效、一个提升整体作品的色彩选择。
+
+**整体美学优先于技术正确性。** 视频中的所有场景必须通过统一的视觉语言相互关联——共同的色温、相关的字符调色板、一致的运动词汇。一个技术上正确但每个场景随机使用不同特效的视频，在美学上是失败的。
+
+**密集、分层、深思熟虑。** 每一帧都应值得细看。绝不使用纯黑背景。始终使用多网格构图。始终保持逐场景变化。始终使用有意为之的色彩。
+
+## 模式
+
+| 模式 | 输入 | 输出 | 参考 |
+|------|-------|--------|-----------|
+| **视频转 ASCII** | 视频文件 | 源素材的 ASCII 重现 | `references/inputs.md` § Video Sampling |
+| **音频响应式** | 音频文件 | 由音频特征驱动的生成式视觉效果 | `references/inputs.md` § Audio Analysis |
+| **生成式** | 无（或种子参数） | 程序化 ASCII 动画 | `references/effects.md` |
+| **混合式** | 视频 + 音频 | 带音频响应叠加层的 ASCII 视频 | 两个输入参考 |
+| **歌词/文字** | 音频 + 文字/SRT | 带视觉特效的定时文字 | `references/inputs.md` § Text/Lyrics |
+| **TTS 旁白** | 文字引用 + TTS API | 带打字文字效果的旁白证言/引用视频 | `references/inputs.md` § TTS Integration |
+
+## 技术栈
+
+每个项目使用单一自包含 Python 脚本。无需 GPU。
+
+| 层级 | 工具 | 用途 |
+|-------|------|---------|
+| 核心 | Python 3.10+, NumPy | 数学运算、数组操作、向量化特效 |
+| 信号 | SciPy | FFT、峰值检测（音频模式） |
+| 图像 | Pillow (PIL) | 字体光栅化、帧解码、图像 I/O |
+| 视频 I/O | ffmpeg (CLI) | 解码输入、编码输出、混合音频 |
+| 并行 | concurrent.futures | N 个 worker 用于批量/片段渲染 |
+| TTS | ElevenLabs API（可选） | 生成旁白片段 |
+| 可选 | OpenCV | 视频帧采样、边缘检测 |
+
+## 流水线架构
+
+每种模式遵循相同的 6 阶段流水线：
+
+```
+INPUT → ANALYZE → SCENE_FN → TONEMAP → SHADE → ENCODE
+```
+
+1. **INPUT** — 加载/解码源素材（视频帧、音频采样、图像，或无输入）
+2. **ANALYZE** — 提取逐帧特征（音频频段、视频亮度/边缘、运动向量）
+3. **SCENE_FN** — 场景函数渲染到像素画布（`uint8 H,W,3`）。通过 `_render_vf()` + 像素混合模式组合多个字符网格。参见 `references/composition.md`
+4. **TONEMAP** — 基于百分位数的自适应亮度归一化。参见 `references/composition.md` § Adaptive Tonemap
+5. **SHADE** — 通过 `ShaderChain` + `FeedbackBuffer` 进行后处理。参见 `references/shaders.md`
+6. **ENCODE** — 将原始 RGB 帧通过管道传输至 ffmpeg 进行 H.264/GIF 编码
+
+## 创作方向
+
+### 美学维度
+
+| 维度 | 选项 | 参考 |
+|-----------|---------|-----------|
+| **字符调色板** | 密度渐变、块状元素、符号、文字（片假名、希腊字母、符文、盲文）、项目专属 | `architecture.md` § Palettes |
+| **色彩策略** | HSV、OKLAB/OKLCH、离散 RGB 调色板、自动生成和声、单色、色温 | `architecture.md` § Color System |
+| **背景纹理** | 正弦场、fBM 噪声、域扭曲、voronoi、反应扩散、元胞自动机、视频 | `effects.md` |
+| **主要特效** | 环形、螺旋、隧道、漩涡、波浪、干涉、极光、火焰、SDF、奇异吸引子 | `effects.md` |
+| **粒子** | 火花、雪花、雨滴、气泡、符文、轨道、群集 boid、流场跟随者、轨迹 | `effects.md` § Particles |
+| **Shader 风格** | 复古 CRT、简洁现代、故障艺术、电影感、梦幻、工业、迷幻 | `shaders.md` |
+| **网格密度** | xs(8px) 到 xxl(40px)，每层可混合使用 | `architecture.md` § Grid System |
+| **坐标空间** | 笛卡尔、极坐标、平铺、旋转、鱼眼、Möbius、域扭曲 | `effects.md` § Transforms |
+| **Feedback** | 缩放隧道、彩虹轨迹、幽灵回声、旋转曼陀罗、色彩演化 | `composition.md` § Feedback |
+| **遮罩** | 圆形、环形、渐变、文字模板、动态虹膜/擦除/溶解 | `composition.md` § Masking |
+| **过渡** | 交叉淡化、擦除、溶解、故障切换、虹膜、基于遮罩的揭示 | `shaders.md` § Transitions |
+
+### 逐段变化
+
+绝不对整个视频使用相同配置。对每个段落/场景：
+- **不同的背景特效**（或组合 2-3 种）
+- **不同的字符调色板**（匹配氛围）
+- **不同的色彩策略**（或至少使用不同色调）
+- **变化 shader 强度**（高潮时更多泛光，安静时更多颗粒感）
+- **不同的粒子类型**（如果粒子处于激活状态）
+
+### 项目专属创新
+
+每个项目至少发明以下之一：
+- 匹配主题的自定义字符调色板
+- 自定义背景特效（组合/修改现有构建块）
+- 自定义色彩调色板（匹配品牌/氛围的离散 RGB 集合）
+- 自定义粒子字符集
+- 新颖的场景过渡或视觉时刻
+
+不要只从目录中挑选。目录是词汇——你来写诗。
+
+## 工作流程
+
+### 第一步：创作愿景
+
+在任何代码之前，阐明创作概念：
+
+- **氛围/气氛**：观众应该感受到什么？充满活力、冥想感、混沌、优雅、不祥？
+- **视觉故事**：在整个时长内发生了什么？积累张力？转变？消解？
+- **色彩世界**：暖色/冷色？单色？霓虹？大地色调？主色调是什么？
+- **字符质感**：密集数据？稀疏星点？有机点阵？几何块状？
+- **与众不同之处**：是什么让这个项目独一无二？
+- **情感弧线**：场景如何推进？以能量开场，积累至高潮，然后解决？
+
+将用户的 prompt 映射到美学选择。"轻松 lo-fi 可视化器"与"故障赛博朋克数据流"在各方面都要求截然不同的处理。
+
+### 第二步：技术设计
+
+- **模式** — 上述 6 种模式中的哪一种
+- **分辨率** — 横屏 1920x1080（默认）、竖屏 1080x1920、方形 1080x1080 @ 24fps
+- **硬件检测** — 自动检测核心数/内存，设置质量配置文件。参见 `references/optimization.md`
+- **段落** — 将时间戳映射到场景函数，每个场景有其自己的特效/调色板/色彩/shader 配置
+- **输出格式** — MP4（默认）、GIF（640x360 @ 15fps）、PNG 序列
+
+### 第三步：构建脚本
+
+单一 Python 文件。组件（含参考）：
+
+1. **硬件检测 + 质量配置文件** — `references/optimization.md`
+2. **输入加载器** — 依模式而定；`references/inputs.md`
+3. **特征分析器** — 音频 FFT、视频亮度，或合成
+4. **网格 + 渲染器** — 带位图缓存的多密度网格；`references/architecture.md`
+5. **字符调色板** — 每个项目多个；`references/architecture.md` § Palettes
+6. **色彩系统** — HSV + 离散 RGB + 和声生成；`references/architecture.md` § Color
+7. **场景函数** — 每个返回 `canvas (uint8 H,W,3)`；`references/scenes.md`
+8. **Tonemap** — 自适应亮度归一化；`references/composition.md`
+9. **Shader 流水线** — `ShaderChain` + `FeedbackBuffer`；`references/shaders.md`
+10. **场景表 + 调度器** — 时间 → 场景函数 + 配置；`references/scenes.md`
+11. **并行编码器** — N worker 片段渲染，使用 ffmpeg 管道
+12. **Main** — 编排完整流水线
+
+### 第四步：质量验证
+
+- **先测试帧**：在完整渲染前，在关键时间戳渲染单帧
+- **亮度检查**：所有 ASCII 内容的 `canvas.mean() > 8`。如果偏暗，降低 gamma
+- **视觉连贯性**：所有场景是否感觉属于同一个视频？
+- **创作愿景检查**：输出是否与第一步的概念相符？如果看起来平庸，请返回重做
+
+## 关键实现注意事项
+
+### 亮度——使用 `tonemap()`，而非线性乘数
+
+这是第一大视觉问题。黑色背景上的 ASCII 本质上偏暗。**绝不使用 `canvas * N` 乘数**——它们会截断高光。使用自适应 tonemap：
+
+```python
+def tonemap(canvas, gamma=0.75):
+    f = canvas.astype(np.float32)
+    lo, hi = np.percentile(f[::4, ::4], [1, 99.5])
+    if hi - lo < 10: hi = lo + 10
+    f = np.clip((f - lo) / (hi - lo), 0, 1) ** gamma
+    return (f * 255).astype(np.uint8)
+```
+
+流水线：`scene_fn() → tonemap() → FeedbackBuffer → ShaderChain → ffmpeg`
+
+逐场景 gamma：默认 0.75，日晒效果 0.55，色调分离 0.50，明亮场景 0.85。暗层使用 `screen` 混合（而非 `overlay`）。
+
+### 字体单元高度
+
+macOS Pillow：`textbbox()` 返回错误高度。使用 `font.getmetrics()`：`cell_height = ascent + descent`。参见 `references/troubleshooting.md`。
+
+### ffmpeg 管道死锁
+
+长时间运行的 ffmpeg 绝不使用 `stderr=subprocess.PIPE`——缓冲区在 64KB 时填满并死锁。重定向到文件。参见 `references/troubleshooting.md`。
+
+### 字体兼容性
+
+并非所有 Unicode 字符都能在所有字体中渲染。在初始化时验证调色板——渲染每个字符，检查是否有空白输出。参见 `references/troubleshooting.md`。
+
+### 逐片段架构
+
+对于分段视频（引用、场景、章节），将每段渲染为独立的片段文件，以支持并行渲染和选择性重渲染。参见 `references/scenes.md`。
+
+## 性能目标
+
+| 组件 | 预算 |
+|-----------|--------|
+| 特征提取 | 1-5ms |
+| 特效函数 | 2-15ms |
+| 字符渲染 | 80-150ms（瓶颈） |
+| Shader 流水线 | 5-25ms |
+| **总计** | ~100-200ms/帧 |
+
+## 参考资料
+
+| 文件 | 内容 |
+|------|----------|
+| `references/architecture.md` | 网格系统、分辨率预设、字体选择、字符调色板（20+）、色彩系统（HSV + OKLAB + 离散 RGB + 和声生成）、`_render_vf()` 辅助函数、GridLayer 类 |
+| `references/composition.md` | 像素混合模式（20 种）、`blend_canvas()`、多网格构图、自适应 `tonemap()`、`FeedbackBuffer`、`PixelBlendStack`、遮罩/模板系统 |
+| `references/effects.md` | 特效构建块：值场生成器、色调场、噪声/fBM/域扭曲、voronoi、反应扩散、元胞自动机、SDF、奇异吸引子、粒子系统、坐标变换、时间连贯性 |
+| `references/shaders.md` | `ShaderChain`、`_apply_shader_step()` 调度、38 种 shader 目录、音频响应式缩放、过渡、色调预设、输出格式编码、终端渲染 |
+| `references/scenes.md` | 场景协议、`Renderer` 类、`SCENES` 表、`render_clip()`、节拍同步剪切、并行渲染、设计模式（层级结构、方向弧线、视觉隐喻、构图技法）、各复杂度级别的完整场景示例、场景设计检查清单 |
+| `references/inputs.md` | 音频分析（FFT、频段、节拍）、视频采样、图像转换、文字/歌词、TTS 集成（ElevenLabs、声音分配、音频混合） |
+| `references/optimization.md` | 硬件检测、质量配置文件、向量化模式、并行渲染、内存管理、性能预算 |
+| `references/troubleshooting.md` | NumPy 广播陷阱、混合模式陷阱、多进程/pickling、亮度诊断、ffmpeg 问题、字体问题、常见错误 |
+
+---
+
+## 创意发散（仅在用户请求实验性/创意性/独特输出时使用）
+
+如果用户要求创意性、实验性、令人惊喜或非常规的输出，选择最适合的策略，并在生成代码**之前**推理其步骤。
+
+- **强制关联** — 当用户想要跨领域灵感时（"让它看起来有机感"、"工业美学"）
+- **概念融合** — 当用户命名两个要组合的事物时（"海洋遇见音乐"、"太空 + 书法"）
+- **斜向策略** — 当用户完全开放时（"给我惊喜"、"我从未见过的东西"）
+
+### 强制关联
+1. 选择一个与视觉目标无关的领域（天气系统、微生物学、建筑、流体动力学、纺织编织）
+2. 列出其核心视觉/结构元素（侵蚀 → 逐渐揭示；有丝分裂 → 分裂复制；编织 → 交错图案）
+3. 将这些元素映射到 ASCII 字符和动画模式
+4. 综合——"侵蚀"或"结晶"在字符网格中看起来是什么样的？
+
+### 概念融合
+1. 命名两个不同的视觉/概念空间（例如，海浪 + 乐谱）
+2. 映射对应关系（波峰 = 高音，波谷 = 休止，浪花 = 断奏）
+3. 选择性融合——保留最有趣的映射，舍弃牵强的
+4. 发展只存在于融合中的涌现属性
+
+### 斜向策略
+1. 抽取一张："将错误视为隐藏的意图" / "使用一个旧想法" / "你最亲密的朋友会怎么做？" / "强调缺陷" / "颠倒过来" / "只取一部分，而非全部" / "反转"
+2. 将该指令对照当前 ASCII 动画挑战进行诠释
+3. 在编写代码之前，将这一横向洞见应用于视觉设计