@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/ascii-video/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: ascii-video
+description: "ASCII 视频：将视频/音频转换为彩色 ASCII MP4/GIF。"
+platforms: [linux, macos, windows]
+---
+
+# ASCII 视频制作流水线
+
+## 适用场景
+
+当用户请求以下内容时使用：ASCII 视频、文本艺术视频、终端风格视频、字符艺术动画、复古文本可视化、ASCII 音频可视化器、将视频转换为 ASCII 艺术、matrix 风格效果，或任何动画 ASCII 输出。
+
+## 包含内容
+
+ASCII 艺术视频的制作流水线——支持任何格式。将视频/音频/图像/生成式输入转换为彩色 ASCII 字符视频输出（MP4、GIF、图像序列）。涵盖：视频转 ASCII 转换、音频响应型音乐可视化器、生成式 ASCII 艺术动画、视频+音频混合响应、文本/歌词叠加、实时终端渲染。
+
+## 创意标准
+
+这是视觉艺术。ASCII 字符是媒介；电影是标准。
+
+**在编写任何一行代码之前**，请先阐明创意概念。氛围是什么？讲述了怎样的视觉故事？是什么让“这个”项目与其他所有 ASCII 视频截然不同？用户的提示词只是一个起点——用创作野心去诠释它，而不是进行字面转录。
+
+**首次渲染即必须出色，这一点不容妥协。** 输出必须在无需多轮修改的情况下就具备视觉冲击力。如果看起来效果大众化、平淡无奇，或者像“AI 生成的 ASCII 艺术”，那就是错的——在交付之前要重新思考创意概念。
+
+**超越参考词汇库。** 参考资料中的效果目录、shader 预设和调色板库只是一个基础词汇库。对于每个项目，都要组合、修改并创造新的模式。目录是你的颜料——而由你来作画。
+
+**主动发挥创造力。** 当项目需要时，扩展该技能的词汇库。如果参考资料中没有视觉愿景所要求的内容，那就去构建它。至少加入一个用户没有要求但会欣赏的视觉瞬间——一个转场、一种效果、一种能提升整个作品层次的颜色选择。
+
+**追求整体美学的连贯，而非单纯的正确性。** 视频中的所有场景都必须通过统一的视觉语言让人感觉是相连的——共同的色温、相关的字符调色板、一致的运动词汇。如果一段技术上正确的视频在每个场景中都使用了随机且不同的效果，那就是美学上的失败。
+
+**高密度、多层次、深思熟虑。** 每一帧都值得细细品味。绝对不要平淡的纯黑背景。始终使用多重网格构图。始终包含逐场景的变化。始终保持有意的色彩运用。
+
+## 模式
+
+| 模式 | 输入 | 输出 | 参考 |
+| ------ | ------- | -------- | ----------- |
+| **视频转 ASCII (Video-to-ASCII)** | 视频文件 | 源镜头的 ASCII 重塑 | `references/inputs.md` § Video Sampling |
+| **音频响应型** | 音频文件 | 由音频特征驱动的生成式视觉效果 | `references/inputs.md` § Audio Analysis |
+| **生成式** | 无（或 seed 参数） | 程序化 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 帧通过 pipe 传输给 ffmpeg 进行 H.264/GIF 编码
+
+## 创意指导
+
+### 美学维度
+
+| 维度 | 选项 | 参考 |
+| ----------- | --------- | ----------- |
+| **字符调色板** | 密度梯度、块元素、符号、脚本（假名、希腊字母、符文、盲文）、项目特定 | `architecture.md` § Palettes |
+| **色彩策略** | HSV, OKLAB/OKLCH, 离散 RGB 调色板, 自动生成的和谐色, 单色, 温度 | `architecture.md` § Color System |
+| **背景纹理** | 正弦场, fBM 噪声, domain warp, voronoi, reaction-diffusion, 元胞自动机, 视频 | `effects.md` |
+| **主要效果** | 环形、螺旋、隧道、漩涡、波浪、干涉、极光、火焰、SDFs、奇异吸引子 | `effects.md` |
+| **粒子** | 火花、雪、雨、气泡、符文、轨道、群集 boids、流场跟随者、拖尾 | `effects.md` § Particles |
+| **Shader 风格** | 复古 CRT、简洁现代、故障艺术、电影感、梦幻、工业风、迷幻 | `shaders.md` |
+| **网格密度** | xs(8px) 到 xxl(40px)，按层混合 | `architecture.md` § Grid System |
+| **坐标空间** | 笛卡尔、极坐标、平铺、旋转、鱼眼、Möbius、domain-warped | `effects.md` § Transforms |
+| **反馈** | 缩放隧道、彩虹拖尾、幽灵重影、旋转曼陀罗、色彩演化 | `composition.md` § Feedback |
+| **遮罩** | 圆形、环形、渐变、文本镂空、动画光圈/擦除/溶解 | `composition.md` § Masking |
+| **转场** | 交叉淡入淡出、擦除、溶解、故障切换、光圈、基于遮罩的展现 | `shaders.md` § Transitions |
+
+### 逐片段变化
+
+绝对不要在整个视频中从头到尾使用相同的配置。对于每个片段/场景：
+- **不同的背景效果**（或组合 2-3 种）
+- **不同的字符调色板**（契合氛围）
+- **不同的色彩策略**（或至少使用不同的色调）
+- **改变 Shader 强度**（高潮处增加 bloom，安静处增加颗粒感）
+- **如果启用了粒子，请使用不同类型的粒子**
+
+### 项目专属创造
+
+对于每个项目，至少创造以下一项：
+- 符合主题的自定义字符调色板
+- 自定义背景效果（组合/修改现有的构建模块）
+- 自定义调色板（符合品牌/氛围的离散 RGB 集合）
+- 自定义粒子字符集
+- 新颖的场景转场或视觉瞬间
+
+不要仅仅从目录中挑选。目录只是词汇——而由你来作诗。
+
+## 工作流程
+
+### 第一步：创意愿景
+
+在编写任何代码之前，清晰表述你的创意概念：
+
+- **氛围/基调**：观众应该感受到什么？充满活力、引人沉思、混乱无序、优雅、不祥？
+- **视觉故事**：在这段时间里会发生什么？制造紧张感？发生转变？逐渐溶解？
+- **色彩世界**：暖色/冷色？单色？霓虹？大地色系？主色调是什么？
+- **字符纹理**：高密度数据？稀疏的星星？有机的圆点？几何块？
+- **独特之处**：是什么让“这个”项目独一无二？
+- **情感弧线**：场景如何推进？以活力开场，推向高潮，然后收尾？
+
+将用户的提示词映射为美学选择。一个“放松的 lo-fi 可视化器”与“赛博朋克故障数据流”在各个方面的要求都截然不同。
+
+### 第二步：技术设计
+
+- **模式** — 上述 6 种模式中的哪一种
+- **分辨率** — 横屏 1920x1080（默认），竖屏 1080x1920，方形 1080x1080 @ 24fps
+- **硬件检测** — 自动检测核心数/RAM，设置质量配置。参见 `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. **并行编码器** — 使用 ffmpeg 管道的 N 个 worker 片段渲染
+12. **Main** — 协调整个流水线
+
+### 第四步：质量验证
+
+- **先测试帧**：在进行完整渲染之前，先渲染关键时间戳处的单帧
+- **亮度检查**：对于所有 ASCII 内容 `canvas.mean() > 8`。如果太暗，则降低 gamma
+- **视觉连贯性**：所有场景看起来是否像属于同一个视频？
+- **创意愿景检查**：输出是否与第一步中的概念相符？如果看起来普通大众化，请返回上一步
+
+## 关键实现说明
+
+### 亮度 — 使用 `tonemap()`，不要使用线性乘数
+
+这是头号视觉问题。黑底 ASCII 本质上很暗。**绝对不要使用 `canvas * N` 乘数** —— 它们会丢失高光细节。请使用自适应色调映射：
+
+```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，solarize 为 0.55，posterize 为 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/frame |
+
+## 参考资料
+
+| 文件 | 内容 |
+| ------ | ---------- |
+| `references/architecture.md` | 网格系统、分辨率预设、字体选择、字符调色板 (20+)、颜色系统 (HSV + OKLAB + 离散 RGB + 和谐色生成)、`_render_vf()` 辅助程序、GridLayer 类 |
+| `references/composition.md` | 像素混合模式 (20 种模式)、`blend_canvas()`、多网格合成、自适应 `tonemap()`、`FeedbackBuffer`、`PixelBlendStack`、遮罩/镂空系统 |
+| `references/effects.md` | 效果构建块：值场生成器、色相场、噪声/fBM/domain warp、voronoi、reaction-diffusion、元胞自动机、SDFs、奇异吸引子、粒子系统、坐标变换、时间连贯性 |
+| `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 广播陷阱、混合模式缺陷、多进程/序列化、亮度诊断、ffmpeg 问题、字体问题、常见错误 |
+
+---
+
+## 创意发散（仅在用户要求实验性/创意性/独特输出时使用）
+
+如果用户要求提供创意、实验性、令人惊喜或非传统的输出，请选择最合适的策略，并在生成代码之前推演其步骤。
+
+- **强制连接** — 当用户想要跨领域灵感时（“让它看起来有机一些”、“工业美学”）
+- **概念融合** — 当用户点名要结合两件事物时（“海洋遇见音乐”、“空间 + 书法”）
+- **斜向策略** — 当用户的开放度达到最大化时（“给我个惊喜”、“给我看些我没见过的”）
+
+### 强制连接
+1. 选择一个与视觉目标无关的领域（天气系统、微生物学、建筑学、流体力学、纺织编织）
+2. 列出其核心视觉/结构元素（侵蚀 → 逐渐展现；有丝分裂 → 分裂复制；编织 → 互锁模式）
+3. 将这些元素映射到 ASCII 字符和动画模式上
+4. 进行综合分析 —— 在字符网格中，“侵蚀”或“结晶化”看起来是什么样的？
+
+### 概念融合
+1. 命名两个不同的视觉/概念空间（例如，海浪 + 乐谱）
+2. 映射对应关系（波峰 = 高音，波谷 = 休止符，泡沫 = 断奏）
+3. 选择性地融合 —— 保留最有趣的映射，丢弃牵强附会的部分
+4. 开发仅存在于融合体中的涌现属性
+
+### 斜向策略
+1. 抽取一张：“将你的错误视为隐藏的意图而加以尊重” / “使用一个旧点子” / “你最亲密的朋友会怎么做？” / “强调瑕疵” / “将其颠倒过来” / “只是一部分，而不是全部” / “反转”
+2. 针对当前的 ASCII 动画挑战来解读指令
+3. 在编写代码之前，将这种横向思维的洞察应用于视觉设计