Zakaria/hermes-agent
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Hermes-agent

Browse Source
This commit is contained in:
Zakaria
2026-06-14 14:30:48 -04:00
commit dac4b88b94
5058 changed files with 1884848 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-architecture-diagram.md
+165
View File
@@ -0,0 +1,165 @@
---
title: "Architecture Diagram — 深色主题 SVG 架构/云/基础设施图表（HTML 格式）"
sidebar_label: "Architecture Diagram"
description: "深色主题 SVG 架构/云/基础设施图表（HTML 格式）"
---
{/* 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. */}
# Architecture Diagram
深色主题 SVG 架构/云/基础设施图表，以 HTML 格式输出。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/architecture-diagram` |
| 版本 | `1.0.0` |
| 作者 | Cocoon AI (hello@cocoon-ai.com)，由 Hermes Agent 移植 |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `architecture`, `diagrams`, `SVG`, `HTML`, `visualization`, `infrastructure`, `cloud` |
| 相关 skill | [`concept-diagrams`](/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# Architecture Diagram Skill
生成专业的深色主题技术架构图，输出为包含内联 SVG 图形的独立 HTML 文件。无需外部工具、无需 API 密钥、无需渲染库——只需写入 HTML 文件并在浏览器中打开即可。
## 适用范围
**最适合：**
- 软件系统架构（前端/后端/数据库层）
- 云基础设施（VPC、区域、子网、托管服务）
- 微服务/服务网格拓扑
- 数据库 + API 映射、部署图
- 任何具有技术基础设施主题、适合深色网格背景风格的内容
**以下场景请优先考虑其他工具：**
- 物理、化学、数学、生物或其他科学学科
- 实物对象（车辆、硬件、解剖结构、截面图）
- 平面图、叙事流程、教育/教科书风格的视觉内容
- 手绘白板草图（建议使用 `excalidraw`）
- 动画说明（建议使用动画相关 skill）
如果有更专业的 skill 适用于该主题，请优先使用。如果没有合适的，本 skill 也可作为通用 SVG 图表的备选方案——输出内容将带有下述深色技术风格。
基于 [Cocoon AI 的 architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator)（MIT 许可证）。
## 工作流程
1. 用户描述其系统架构（组件、连接关系、技术栈）
2. 按照下方设计规范生成 HTML 文件
3. 使用 `write_file` 保存为 `.html` 文件（例如 `~/architecture-diagram.html`）
4. 用户在任意浏览器中打开——支持离线使用，无需任何依赖
### 输出位置
将图表保存到用户指定路径，或默认保存至当前工作目录：
```
./[project-name]-architecture.html
```
### 预览
保存后，建议用户通过以下命令打开：
```bash
# macOS
open ./my-architecture.html
# Linux
xdg-open ./my-architecture.html
```
## 设计规范与视觉语言
### 颜色方案（语义映射）
使用特定的 `rgba` 填充色和十六进制描边色对组件进行分类：
| 组件类型 | 填充色（rgba） | 描边色（Hex） |
| :--- | :--- | :--- |
| **前端** | `rgba(8, 51, 68, 0.4)` | `#22d3ee`（cyan-400） |
| **后端** | `rgba(6, 78, 59, 0.4)` | `#34d399`（emerald-400） |
| **数据库** | `rgba(76, 29, 149, 0.4)` | `#a78bfa`（violet-400） |
| **AWS/云** | `rgba(120, 53, 15, 0.3)` | `#fbbf24`（amber-400） |
| **安全** | `rgba(136, 19, 55, 0.4)` | `#fb7185`（rose-400） |
| **消息总线** | `rgba(251, 146, 60, 0.3)` | `#fb923c`（orange-400） |
| **外部** | `rgba(30, 41, 59, 0.5)` | `#94a3b8`（slate-400） |
### 字体与背景
- **字体：** JetBrains Mono（等宽字体），从 Google Fonts 加载
- **字号：** 12px（名称）、9px（副标签）、8px（注释）、7px（极小标签）
- **背景：** Slate-950（`#020617`），带有细腻的 40px 网格图案
```svg
<!-- 背景网格图案 -->
<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
<path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>
```
## 技术实现细节
### 组件渲染
组件为圆角矩形（`rx="6"`），描边宽度 1.5px。为防止箭头透过半透明填充色显现，使用**双矩形遮罩技术**：
1. 绘制不透明背景矩形（`#0f172a`）
2. 在其上方绘制半透明样式矩形
### 连接规则
- **Z 轴顺序：** 在 SVG 早期绘制箭头（在网格之后），使其渲染在组件框的下方
- **箭头头部：** 通过 SVG marker 定义
- **安全流：** 使用 rose 色（`#fb7185`）虚线
- **边界：**
- *安全组：* 虚线（`4,4`），rose 色
- *区域：* 大虚线（`8,4`），amber 色，`rx="12"`
### 间距与布局规则
- **标准高度：** 60px（服务）；80–120px（大型组件）
- **垂直间距：** 组件之间最小 40px
- **消息总线：** 必须放置在服务之间的间隙中，不得与其重叠
- **图例位置：** **关键。** 必须放置在所有边界框的外部。计算所有边界的最低 Y 坐标，并将图例放置在其下方至少 20px 处。
## 文档结构
生成的 HTML 文件遵循四段式布局：
1. **页眉：** 带有脉冲点指示器的标题和副标题
2. **主 SVG：** 包含在圆角边框卡片中的图表
3. **摘要卡片：** 图表下方的三张卡片网格，用于展示高层次详情
4. **页脚：** 简洁的元数据信息
### 信息卡片模式
```html
<div class="card">
<div class="card-header">
<div class="card-dot cyan"></div>
<h3>Title</h3>
</div>
<ul>
<li>• Item one</li>
<li>• Item two</li>
</ul>
</div>
```
## 输出要求
- **单文件：** 一个自包含的 `.html` 文件
- **无外部依赖：** 所有 CSS 和 SVG 必须内联（Google Fonts 除外）
- **无 JavaScript：** 所有动画（如脉冲点）使用纯 CSS 实现
- **兼容性：** 必须在任何现代浏览器中正确渲染
## 模板参考
加载完整 HTML 模板以获取精确的结构、CSS 和 SVG 组件示例：
```
skill_view(name="architecture-diagram", file_path="templates/template.html")
```
模板包含每种组件类型（前端、后端、数据库、云、安全）、箭头样式（标准、虚线、曲线）、安全组、区域边界和图例的完整示例——生成图表时请以此作为结构参考。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-ascii-art.md
+338
View File
@@ -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. **任何工具未安装** → 安装它，或回退到下一个选项
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-ascii-video.md
+261
View File
@@ -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. 在编写代码之前，将这一横向洞见应用于视觉设计
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-baoyu-infographic.md
+256
View File
@@ -0,0 +1,256 @@
---
title: "Baoyu Infographic — 信息图：21种布局 × 21种风格（信息图, 可视化）"
sidebar_label: "Baoyu Infographic"
description: "信息图：21种布局 × 21种风格（信息图, 可视化）"
---
{/* 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. */}
# Baoyu Infographic
信息图：21种布局 × 21种风格（信息图, 可视化）。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/baoyu-infographic` |
| 版本 | `1.56.1` |
| 作者 | 宝玉 (JimLiu) |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `infographic`, `visual-summary`, `creative`, `image-generation` |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
:::
# 信息图生成器
改编自 [baoyu-infographic](https://github.com/JimLiu/baoyu-skills)，适配 Hermes Agent 的工具生态系统。
两个维度：**布局**（信息结构）× **风格**（视觉美学）。可自由组合任意布局与风格。
## 使用时机
当用户要求创建信息图、视觉摘要、information graphic，或使用"信息图"、"可视化"、"高密度信息大图"等词语时，触发此 skill。用户提供内容（文本、文件路径、URL 或主题），并可选择指定布局、风格、宽高比或语言。
## 选项
| 选项 | 可选值 |
|--------|--------|
| 布局 | 21个选项（见布局图库），默认：bento-grid |
| 风格 | 21个选项（见风格图库），默认：craft-handmade |
| 宽高比 | 命名预设：landscape（16:9）、portrait（9:16）、square（1:1）。自定义：任意 W:H 比例（如 3:4、4:3、2.35:1） |
| 语言 | en、zh、ja 等 |
## 布局图库
| 布局 | 最适合 |
|--------|----------|
| `linear-progression` | 时间线、流程、教程 |
| `binary-comparison` | A vs B、前后对比、优缺点 |
| `comparison-matrix` | 多因素比较 |
| `hierarchical-layers` | 金字塔、优先级层级 |
| `tree-branching` | 分类、分类体系 |
| `hub-spoke` | 以中心概念辐射相关项 |
| `structural-breakdown` | 爆炸图、截面图 |
| `bento-grid` | 多主题、概览（默认） |
| `iceberg` | 表面与隐藏层面 |
| `bridge` | 问题-解决方案 |
| `funnel` | 转化、筛选 |
| `isometric-map` | 空间关系 |
| `dashboard` | 指标、KPI |
| `periodic-table` | 分类集合 |
| `comic-strip` | 叙事、序列 |
| `story-mountain` | 情节结构、张力弧线 |
| `jigsaw` | 相互关联的部分 |
| `venn-diagram` | 重叠概念 |
| `winding-roadmap` | 旅程、里程碑 |
| `circular-flow` | 循环、周期性流程 |
| `dense-modules` | 高密度模块、数据丰富的指南 |
完整定义：`references/layouts/<layout>.md`
## 风格图库
| 风格 | 描述 |
|-------|-------------|
| `craft-handmade` | 手绘、纸艺（默认） |
| `claymation` | 3D 黏土人物、定格动画 |
| `kawaii` | 日系可爱风、马卡龙色 |
| `storybook-watercolor` | 柔和水彩、奇幻风格 |
| `chalkboard` | 黑板粉笔风 |
| `cyberpunk-neon` | 霓虹发光、未来主义 |
| `bold-graphic` | 漫画风格、半调网点 |
| `aged-academia` | 复古科学、棕褐色调 |
| `corporate-memphis` | 扁平矢量、鲜艳色彩 |
| `technical-schematic` | 蓝图、工程制图 |
| `origami` | 折纸、几何造型 |
| `pixel-art` | 复古 8-bit 像素风 |
| `ui-wireframe` | 灰度界面线框图 |
| `subway-map` | 地铁线路图风格 |
| `ikea-manual` | 极简线条插图 |
| `knolling` | 整齐平铺俯拍 |
| `lego-brick` | 玩具积木构造 |
| `pop-laboratory` | 蓝图网格、坐标标注、实验室精度 |
| `morandi-journal` | 手绘涂鸦、莫兰迪暖色调 |
| `retro-pop-grid` | 1970年代复古波普艺术、瑞士网格、粗轮廓线 |
| `hand-drawn-edu` | 马卡龙色、手绘抖动线条、简笔人物 |
完整定义：`references/styles/<style>.md`
## 推荐组合
| 内容类型 | 布局 + 风格 |
|--------------|----------------|
| 时间线/历史 | `linear-progression` + `craft-handmade` |
| 分步说明 | `linear-progression` + `ikea-manual` |
| A vs B | `binary-comparison` + `corporate-memphis` |
| 层级结构 | `hierarchical-layers` + `craft-handmade` |
| 重叠关系 | `venn-diagram` + `craft-handmade` |
| 转化漏斗 | `funnel` + `corporate-memphis` |
| 循环流程 | `circular-flow` + `craft-handmade` |
| 技术内容 | `structural-breakdown` + `technical-schematic` |
| 指标数据 | `dashboard` + `corporate-memphis` |
| 教育内容 | `bento-grid` + `chalkboard` |
| 旅程路线 | `winding-roadmap` + `storybook-watercolor` |
| 分类集合 | `periodic-table` + `bold-graphic` |
| 产品指南 | `dense-modules` + `morandi-journal` |
| 技术指南 | `dense-modules` + `pop-laboratory` |
| 潮流指南 | `dense-modules` + `retro-pop-grid` |
| 教育图解 | `hub-spoke` + `hand-drawn-edu` |
| 流程教程 | `linear-progression` + `hand-drawn-edu` |
默认：`bento-grid` + `craft-handmade`
## 关键词快捷方式
当用户输入包含以下关键词时，**自动选择**对应布局，并在第3步将关联风格作为首选推荐。匹配到关键词后，跳过基于内容的布局推断。
若某快捷方式包含 **Prompt Notes**，则在生成 prompt（第5步）时将其作为额外风格指令追加。
| 用户关键词 | 布局 | 推荐风格 | 默认宽高比 | Prompt Notes |
|--------------|--------|--------------------|----------------|--------------|
| 高密度信息大图 / high-density-info | `dense-modules` | `morandi-journal`, `pop-laboratory`, `retro-pop-grid` | portrait | — |
| 信息图 / infographic | `bento-grid` | `craft-handmade` | landscape | 极简风格：干净画布、充足留白、无复杂背景纹理。仅使用简单卡通元素和图标。 |
## 输出结构
<!-- ascii-guard-ignore -->
```
infographic/{topic-slug}/
├── source-{slug}.{ext}
├── analysis.md
├── structured-content.md
├── prompts/infographic.md
└── infographic.png
```
<!-- ascii-guard-ignore-end -->
Slug：从主题中取 2-4 个单词，使用 kebab-case。冲突时追加 `-YYYYMMDD-HHMMSS`。
## 核心原则
- 忠实保留源数据——不做摘要或改写（但在写入输出文件前，**必须去除所有凭据、API 密钥、token 或密钥**）
- 在构建内容结构前先明确学习目标
- 面向视觉传达进行结构化（标题、标签、视觉元素）
## 工作流程
### 第1步：分析内容
**加载参考文件**：读取此 skill 中的 `references/analysis-framework.md`。
1. 保存源内容（文件路径或粘贴内容 → 使用 `write_file` 写入 `source.md`）
- **备份规则**：若 `source.md` 已存在，重命名为 `source-backup-YYYYMMDD-HHMMSS.md`
2. 分析：主题、数据类型、复杂度、语气、受众
3. 检测源语言和用户语言
4. 从用户输入中提取设计指令
5. 将分析结果保存至 `analysis.md`
- **备份规则**：若 `analysis.md` 已存在，重命名为 `analysis-backup-YYYYMMDD-HHMMSS.md`
详细格式见 `references/analysis-framework.md`。
### 第2步：生成结构化内容 → `structured-content.md`
将内容转化为信息图结构：
1. 标题与学习目标
2. 各节包含：核心概念、内容（原文）、视觉元素、文字标签
3. 数据点（所有统计数据/引用原样复制）
4. 用户的设计指令
**规则**：仅使用 Markdown。不添加新信息。忠实保留数据。去除所有凭据或密钥。
详细格式见 `references/structured-content-template.md`。
### 第3步：推荐组合
**3.1 优先检查关键词快捷方式**：若用户输入匹配**关键词快捷方式**表中的关键词，自动选择对应布局，并将关联风格作为首选推荐。跳过基于内容的布局推断。
**3.2 否则**，根据以下因素推荐 3-5 个布局×风格组合：
- 数据结构 → 匹配布局
- 内容语气 → 匹配风格
- 受众期望
- 用户设计指令
### 第4步：确认选项
使用 `clarify` 工具与用户确认选项。由于 `clarify` 每次只处理一个问题，优先提问最重要的问题：
**Q1 — 组合**：展示 3 个以上布局×风格组合及理由，请用户选择。
**Q2 — 宽高比**：询问宽高比偏好（landscape/portrait/square 或自定义 W:H）。
**Q3 — 语言**（仅当源语言 ≠ 用户语言时）：询问文字内容使用哪种语言。
### 第5步：生成 Prompt → `prompts/infographic.md`
**备份规则**：若 `prompts/infographic.md` 已存在，重命名为 `prompts/infographic-backup-YYYYMMDD-HHMMSS.md`
**加载参考文件**：读取所选布局的 `references/layouts/<layout>.md` 和风格的 `references/styles/<style>.md`。
组合以下内容：
1. `references/layouts/<layout>.md` 中的布局定义
2. `references/styles/<style>.md` 中的风格定义
3. `references/base-prompt.md` 中的基础模板
4. 第2步的结构化内容
5. 所有文字使用已确认的语言
**`{{ASPECT_RATIO}}` 宽高比解析**：
- 命名预设 → 比例字符串：landscape→`16:9`，portrait→`9:16`，square→`1:1`
- 自定义 W:H 比例 → 原样使用（如 `3:4`、`4:3`、`2.35:1`）
使用 `write_file` 将组装好的 prompt 保存至 `prompts/infographic.md`。
### 第6步：生成图像
使用 `image_generate` 工具，传入第5步组装的 prompt。
- 将宽高比映射到 image_generate 的格式：`16:9` → `landscape`，`9:16` → `portrait`，`1:1` → `square`
- 自定义比例时，选择最接近的命名宽高比
- 失败时自动重试一次
- 将生成的图像 URL/路径保存至输出目录
### 第7步：输出摘要
报告：主题、布局、风格、宽高比、语言、输出路径、已创建文件。
## 参考文件
- `references/analysis-framework.md` — 分析方法论
- `references/structured-content-template.md` — 内容格式
- `references/base-prompt.md` — Prompt 模板
- `references/layouts/<layout>.md` — 21种布局定义
- `references/styles/<style>.md` — 21种风格定义
## 注意事项
1. **数据完整性至关重要** — 绝不摘要、改写或修改源统计数据。"增长73%"必须保持为"增长73%"，而非"显著增长"。
2. **去除密钥** — 在将源内容写入任何输出文件前，始终扫描 API 密钥、token 或凭据。
3. **每节一个信息点** — 信息图的每个节应传达一个清晰概念。内容过载会降低可读性。
4. **风格一致性** — 参考文件中的风格定义必须在整个信息图中一致应用，不得混用风格。
5. **image_generate 宽高比** — 该工具仅支持 `landscape`、`portrait` 和 `square`。自定义比例如 `3:4` 应映射到最接近的选项（此例为 portrait）。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-claude-design.md
+609
View File
@@ -0,0 +1,609 @@
---
title: "Claude Design — 设计一次性 HTML 制品（落地页、幻灯片、原型）"
sidebar_label: "Claude Design"
description: "设计一次性 HTML 制品（落地页、幻灯片、原型）"
---
{/* 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. */}
# Claude Design
设计一次性 HTML 制品（落地页、幻灯片、原型）。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/claude-design` |
| 版本 | `1.0.0` |
| 作者 | BadTechBandit |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `design`, `html`, `prototype`, `ux`, `ui`, `creative`, `artifact`, `deck`, `motion`, `design-system` |
| 相关 skill | [`design-md`](/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# 面向 CLI/API Agent 的 Claude Design
当用户请求通常适合 Claude Design 的设计工作，但 agent 运行在 CLI/API 环境而非托管的 Claude Design Web UI 时，使用此 skill。
目标是保留 Claude Design 有价值的设计行为与审美，同时去除当前 agent 环境中不存在的托管工具管道。
**开始前，请检查是否有其他 web 设计 skill，例如 `popular-web-designs`（Stripe、Linear、Vercel、Notion 等品牌的即用设计系统）和 `design-md`（Google 的 DESIGN.md token（设计令牌）规范格式）。** 如果用户想要某个已知品牌的外观，请同时加载 `popular-web-designs` 并让其提供视觉词汇。如果交付物是 token 规范文件而非渲染制品，请改用 `design-md`。完整决策表见下文。
## 何时使用此 Skill vs `popular-web-designs` vs `design-md`
Hermes 在 `skills/creative/` 下有三个与设计相关的 skill，它们各司其职——请加载正确的一个（或组合使用）：
| Skill | 提供内容 | 适用场景 |
|---|---|---|
| **claude-design**（本 skill） | 设计*流程与审美*——如何界定需求、收集上下文、生成变体、验证本地 HTML 制品、避免 AI 设计糟粕 | 从零开始设计制品（落地页、原型、幻灯片、组件实验室、动效研究），且无特定品牌或 token 系统要求 |
| **popular-web-designs** | 54 套即用设计系统——Stripe、Linear、Vercel、Notion、Airbnb 等网站的精确颜色、字体、组件、CSS 值 | "做成 Stripe / Linear / Vercel 的风格"、仿照已知品牌的页面，或从真实产品中提取视觉起点 |
| **design-md** | Google 的 DESIGN.md 规范格式——编写/验证/差异对比/导出设计 token 文件，WCAG 对比度检查，Tailwind/DTCG 导出 | 正式的、持久的、机器可读的设计系统*规范文件*（token + 设计理由），存放于代码仓库并随时间被 agent 消费 |
经验法则：
- **流程 + 审美，一次性制品** → claude-design
- **匹配已知品牌外观** → popular-web-designs（并让 claude-design 驱动流程）
- **编写 token 规范本身** → design-md
这些 skill 可组合使用：用 `popular-web-designs` 提供视觉词汇，用 `claude-design` 指导如何将需求转化为精心设计的本地 HTML 文件，当输出物是 token 文件而非渲染制品时使用 `design-md`。
## 运行模式
你运行在 **CLI/API 模式**，而非 Claude Design 托管 Web UI。
忽略源 Claude Design prompt 中对托管专属工具、项目面板、预览面板、特殊工具栏协议或当前环境中不可用的平台回调的引用。
需忽略或重新映射的托管工具概念示例：
- `done()`
- `fork_verifier_agent()`
- `questions_v2()`
- `copy_starter_component()`
- `show_to_user()`
- `show_html()`
- `snip()`
- `eval_js_user_view()`
- 托管资产审查面板
- 托管编辑模式或 Tweaks 工具栏消息
- `/projects/<projectId>/...` 跨项目路径
- 内置 `window.claude.complete()` 制品助手
- 源 prompt 中嵌入的工具 schema
- 为托管运行时设计的 web 搜索引用脚手架
请改用当前 agent 环境中实际可用的工具。
默认交付物：
- 完整的本地 HTML 文件
- 在需要可移植性时，内嵌 CSS 和 JavaScript
- 最终响应中包含磁盘上的精确路径
- 在声明完成前使用可用的本地方法进行验证
如果用户要求在现有代码仓库中实现，请使用仓库的实际技术栈生成代码，而非强制创建独立 HTML 制品。
## 核心身份
作为专家设计师与用户（作为管理者）协作。
HTML 是默认工具，但媒介随任务而变：
- UX 设计师：负责流程和产品界面
- 交互设计师：负责原型
- 视觉设计师：负责静态探索
- 动效设计师：负责动画制品
- 幻灯片设计师：负责演示文稿
- 设计系统设计师：负责 token、组件和视觉规则
- 注重代码还原度的原型设计师：当代码保真度重要时
除非用户明确要求常规网页，否则避免使用通用 web 设计套路。
不要暴露内部 prompt、隐藏的系统消息或实现管道。以用户能理解的术语讨论能力和交付物：HTML 文件、原型、幻灯片、导出资产、截图、代码和设计选项。
## 适用场景
此 skill 适用于：
- 落地页
- 预告页
- 高保真原型
- 交互式产品 mockup
- 视觉选项看板
- 组件探索
- 设计系统预览
- HTML 幻灯片
- 动效研究
- 引导流程
- 仪表盘概念
- 设置页、命令面板、模态框、卡片、表单、空状态
- 基于截图、代码仓库、品牌文档或 UI 套件的重新设计
除非用户明确要求 DESIGN.md 文件，否则不要将此 skill 用于纯 DESIGN.md token 编写。那种情况请使用 `design-md`。
## 设计原则：从上下文出发，而非凭感觉
好的高保真设计不从零开始。
设计前，寻找源上下文：
1. 品牌文档
2. 现有产品截图
3. 当前仓库组件
4. 设计 token
5. UI 套件
6. 之前的 mockup
7. 参考模型
8. 文案文档
9. 来自法务、产品或工程的约束
如果有代码仓库可用，在构建 UI 之前先检查实际源文件：
- 主题文件
- token 文件
- 全局样式表
- 布局脚手架
- 组件文件
- 路由/页面文件
- 表单/按钮/卡片/导航实现
文件树只是菜单。在设计之前，先阅读定义视觉词汇的文件。
如果上下文缺失且保真度重要，请提出简洁、有针对性的问题，而非生成通用 mockup。
## 提问
当任务是新的、模糊的、高保真的、面向外部的，或依赖于品味时，提出问题。
问题要简短。除非问题确实严重缺乏规格，否则不要默认问十个问题。
通常询问：
- 预期输出格式
- 受众
- 保真度级别
- 可用的源材料
- 使用中的品牌/设计系统
- 需要的变体数量
- 是保守还是探索发散性想法
- 最重要的维度：布局、视觉语言、交互、文案、动效还是系统化
以下情况跳过提问：
- 用户已给出足够方向
- 这是小幅调整
- 任务明显是延续性工作
- 缺失的细节有明显的默认值
在基于假设推进时，只标注重要的假设。
## 工作流程
1. **理解需求**
- 设计什么？
- 为谁设计？
- 最终应该存在什么制品？
- 哪些约束是固定的？
2. **收集上下文**
- 阅读提供的文档、截图、仓库文件或设计资产。
- 在编写代码前识别视觉词汇。
3. **为此制品定义设计系统**
- 颜色
- 字体
- 间距
- 圆角
- 阴影或层级
- 动效姿态
- 组件处理方式
- 交互规则
4. **选择正确的格式**
- 静态视觉对比：一个 HTML 画布，选项并排展示。
- 交互/流程：可点击原型。
- 演示文稿：固定尺寸的 HTML 幻灯片，带幻灯片导航。
- 组件探索：带变体的组件实验室。
- 动效：基于时间轴或状态的动画。
5. **构建制品**
- 除非任务要求仓库实现，否则优先使用单个自包含 HTML 文件。
- 重大修订时保留之前的版本。
- 避免不必要的依赖。
6. **验证**
- 确认文件存在。
- 运行可用的语法/静态检查。
- 如果有浏览器工具可用，打开文件并检查控制台错误。
- 如果视觉保真度重要且截图工具可用，至少检查主视口。
7. **简短汇报**
- 精确文件路径
- 创建了什么
- 注意事项
- 下一个决策点或下一次迭代
## 制品格式规则
默认使用本地文件。
对于独立制品：
- 创建描述性文件名，例如 `Landing Page.html`、`Command Palette Prototype.html`、`Design System Board.html`
- 将 CSS 嵌入 `<style>`
- 将 JS 嵌入 `<script>`
- 保持制品可直接在浏览器中打开
- 除非明确有用且稳定，否则避免远程依赖
- 除非格式有意为固定尺寸，否则包含响应式行为
对于重大修订：
- 将之前版本保存为 `Name.html`
- 创建 `Name v2.html`、`Name v3.html` 等
- 或者如果任务是变体探索，在单个文件中保留页内切换
对于仓库实现：
- 遵循仓库的实际技术栈
- 尽可能使用现有组件和 token
- 如果用户要求生产代码，不要创建独立制品
## HTML / CSS / JS 标准
善用现代 CSS：
- CSS 变量用于 token
- CSS grid 用于布局
- 适当时使用 container queries
- 支持时使用 `text-wrap: pretty`
- 真实的 focus 状态
- 真实的 hover 状态
- 对非简单动效处理 `prefers-reduced-motion`
- 响应式缩放
- 实用时使用语义化 HTML
避免：
- 在预期真实仓库结构时使用庞大的单体文件
- 脆弱的硬编码视口假设
- 无障碍性差的微小点击目标
- 与可用性冲突的装饰性 JS
- 除非没有更安全的选项，否则不使用 `scrollIntoView`
移动端点击目标至少应为 44px。
印刷文档中，文字至少应为 12pt。
1920×1080 幻灯片中，文字通常应为 24px 或更大。
## 独立 HTML 中的 React 指南
默认使用纯 HTML/CSS/JS。
仅在以下情况使用 React：
- 制品需要有意义的状态管理
- 变体/切换作为组件更易实现
- 交互复杂度需要它
- 目标实现是 React/Next.js 且保真度重要
在独立 HTML 中通过 CDN 使用 React 时：
- 固定精确版本
- 避免 `react@18` 这类未固定版本的 URL
- 除非必要，避免 `type="module"`
- 避免多个名为 `styles` 的全局对象
- 给全局样式对象起具体名称，例如 `commandPaletteStyles`、`deckStyles`
- 如果拆分 Babel 脚本，请将共享组件显式挂载到 `window`
如果在真实仓库内构建，请使用仓库的包管理器和组件架构。
## 幻灯片规则
对于幻灯片，使用固定尺寸画布并缩放以适应视口。
默认幻灯片尺寸：1920×1080，16:9。
要求：
- 键盘导航
- 可见的幻灯片计数
- 使用 localStorage 持久化当前幻灯片
- 实用时提供打印友好布局
- 重要幻灯片的屏幕标签或稳定 ID
- 除非用户明确要求，否则不加演讲者备注
不要将幻灯片草草处理为 markdown 要点。如果要求幻灯片，请创建设计制品。
除非品牌系统要求更多，否则最多使用 1–2 种背景色。
保持幻灯片简洁。如果幻灯片感觉空洞，用布局、节奏、比例或图片占位符来解决，而非填充文字。
## 原型规则
对于交互式原型：
- 使主要路径可点击
- 包含关键状态：默认、hover/focus、加载中、空状态、错误、成功（视情况而定）
- 在有用时通过页内控件展示变体
- 除非控件有意作为原型的一部分，否则将其置于最终构图之外
- 当刷新连续性重要时，使用 localStorage 持久化重要状态
如果原型旨在模拟产品流程，请设计整个流程，而非仅第一个屏幕。
## 变体规则
探索时，默认至少提供三个选项：
1. **保守型** — 最接近现有模式/风险最低
2. **强匹配型** — 对需求的最佳诠释
3. **发散型** — 更具新意，有助于发现品味边界
变体可以探索：
- 布局
- 层级
- 字体比例
- 密度
- 色彩姿态
- 表面处理
- 动效
- 交互模型
- 文案结构
- 组件形态
除非颜色本身就是问题，否则不要创建仅仅是颜色替换的变体。
当用户选定方向后，进行整合。不要让项目永远停留在一堆选项中。
## CLI/API 模式中的可调整设计
托管的 Claude Design 编辑模式工具栏在此处不存在。
仍然保留这个理念：在有用时，添加名为 `Tweaks` 的页内控件。
好的 `Tweaks` 面板可以控制：
- 主题模式
- 布局变体
- 密度
- 强调色
- 字体比例
- 动效开关
- 文案变体
- 组件变体
保持小巧且不显眼。隐藏 Tweaks 时，设计应看起来是最终版本。
在有帮助时，使用 localStorage 持久化 Tweaks 值。
## 内容纪律
不要添加填充内容。
每个元素都必须有其存在的理由。
避免：
- 虚假指标
- 装饰性统计数据
- 通用功能网格
- 不必要的图标
- 占位性用户评价
- AI 生成的废话章节
- 改变策略或声明的虚构内容
如果额外的章节、页面、文案或声明能改善制品，请在添加前询问。
当文案必要但尚未最终确定时，将其标记为草稿或占位符。
## 反糟粕规则
避免常见的 AI 设计糟粕：
- 激进的渐变背景
- 默认使用毛玻璃效果（glassmorphism）
- 除非品牌使用，否则不用 emoji
- 到处都是图标的通用 SaaS 卡片
- 左边框强调色标注卡片
- 填满任意数字的假仪表盘
- 股票照片英雄区
- 用超大圆角矩形代替层级
- 彩虹配色
- 没有内容支撑的模糊标签，如"洞察"、"增长"、"规模"、"优化"
- 假装是产品图像的装饰性 SVG 插图
极简不自动等于好。密集不自动等于杂乱。有意识地做选择。
## 字体排版
如果存在字体系统，请使用它。
如果没有，根据制品有意识地选择字体：
- 编辑类：衬线或人文主义标题字体，配以克制的无衬线正文
- 软件/生产力类：精确的无衬线字体，配以强劲的数字处理
- 奢华/极简类：更少的字重，更多的间距纪律
- 技术类：仅在强调处使用等宽字体，而非到处使用
- 幻灯片类：大号、清晰、高对比度
在有更强选择时，避免使用过度滥用的默认字体。
如果使用 web 字体，保持字体家族和字重数量较少。
在添加框、图标或颜色之前，先用字体排版建立层级。
## 颜色
优先使用品牌/设计系统颜色。
如果没有调色板：
- 定义一个小型系统
- 包含中性色、表面色、墨水色、静音文字色、边框色、强调色、危险/成功色（视需要）
- 除非任务要求更广泛的调色板，否则使用一种主强调色
- 在浏览器支持可接受时，优先使用 oklch 创建和谐的自定义调色板
- 检查重要文字和控件的对比度
不要凭空发明大量颜色。
## 布局与构图
以节奏感设计：
- 比例
- 留白
- 密度
- 对齐
- 重复
- 对比
- 打断
避免让每个章节都是相同的卡片网格。
对于产品 UI，优先考虑理解速度而非装饰。
对于营销页面，每个章节传达一个核心想法。
对于仪表盘，避免"数据糟粕"。只展示帮助用户决策或行动的数据。
## 动效
将动效作为纪律，而非表演。
好的动效：
- 阐明状态变化
- 减少加载时的焦虑
- 展示界面间的连续性
- 赋予控件触感
- 保持克制
坏的动效：
- 无目的地循环
- 延迟用户操作
- 引起对自身的注意
- 掩盖糟糕的层级
对非简单动画，遵守 `prefers-reduced-motion`。
## 图片与图标
有真实提供的图像时使用真实图像。
如果资产缺失：
- 使用干净的占位符
- 改用字体排版、布局或抽象纹理
- 当保真度重要时，询问真实素材
除非任务明确是插图工作，否则不要绘制精细的假 SVG 插图。
除非图标能改善扫描体验或匹配设计系统，否则避免使用图标。
## 源代码保真度
在从仓库重建或扩展 UI 时：
1. 检查仓库树
2. 识别实际的 UI 源文件
3. 阅读主题/token/全局样式/组件文件
4. 在适当时提取精确值
5. 匹配间距、圆角、阴影、文案语气、密度和交互模式
6. 然后再进行设计或修改
当源文件可用时，不要凭记忆构建。
对于 GitHub URL，正确解析 owner/repo/ref/path 并在设计前检查相关文件。
## 读取文档和资产
在可用时，直接读取 Markdown、HTML、CSS、JS、TS、JSX、TSX、JSON、SVG 和纯文本。
对于 DOCX/PPTX/PDF，如果有本地提取工具则使用。如果不可用，请用户提供导出的文本/图像，或使用其他可用的工具路径。
对于草图，优先使用缩略图或截图，而非原始绘图 JSON，除非 JSON 是唯一可用的来源。
## 版权与参考模型
除非用户明确拥有该来源的权利，否则不要重建公司的独特 UI、专有命令结构、品牌屏幕或精确视觉标识。
可以提取通用设计原则：
- 密集而不杂乱
- 命令优先的交互
- 单色配一种强调色
- 编辑式层级
- 清晰的空状态
- 强键盘可操作性
不可以克隆专有布局、复制精确的品牌界面或复制受版权保护的内容。
使用参考时，将姿态和原则转化为原创设计。
## 验证
在最终响应前，在环境允许的范围内尽可能多地验证。
最低要求：
- 文件存在于声明的路径
- HTML 已完整保存
- 检查明显的语法问题
更好的做法：
- 在浏览器工具中打开并检查控制台错误
- 在主视口检查截图
- 测试关键交互
- 如果有亮/暗模式或变体，进行测试
- 如果相关，测试响应式断点
如果验证受环境限制，请明确说明验证了什么、未验证什么。
如果文件实际上未写入，永远不要说"完成"。
## 最终响应格式
保持最终响应简短。
包含：
- 制品路径
- 包含的内容
- 验证状态
- 如果有用，建议的下一步行动
示例：
```text
Created: /path/to/Prototype.html
It includes 3 layout variants, a Tweaks panel for density/theme, and responsive behavior.
Verified: file exists and opened cleanly in browser, no console errors.
Next: pick the strongest direction and I'll tighten copy + motion.
```
## 可移植的开场 Prompt 模式
将 Claude Design 风格的请求适配到 CLI/API 模式时，使用以下心智转换：
```text
You are running in CLI/API mode, not hosted Claude Design. Ignore references to hosted-only tools or preview panes. Produce complete local design artifacts, usually self-contained HTML with embedded CSS/JS, and verify with available local tools before returning. Preserve the design process: gather context, define the system, produce options, avoid filler, and meet a high visual bar.
```
## 常见陷阱
- 不要将托管工具 schema 粘贴到 skill 中。它们会导致虚假的工具调用。
- 不要将 skill 指向一个庞大的外部 prompt 作为必需的运行时上下文。这会造成漂移。
- 不要在去除工具管道的同时剥离设计原则。
- 当用户已给出足够方向时，不要过度提问。
- 对于没有品牌上下文的高保真工作，不要提问不足。
- 不要生成通用 SaaS 布局并称之为设计。
- 除非浏览器验证确实发生，否则不要声称已进行浏览器验证。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-comfyui.md
+547
View File
@@ -0,0 +1,547 @@
---
title: "Comfyui"
sidebar_label: "Comfyui"
description: "使用 ComfyUI 生成图像、视频和音频——安装、启动、管理节点/模型、运行带参数注入的工作流"
---
{/* 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. */}
# Comfyui
使用 ComfyUI 生成图像、视频和音频——安装、启动、管理节点/模型、运行带参数注入的工作流。使用官方 comfy-cli 进行生命周期管理，使用直接 REST/WebSocket API 执行工作流。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/comfyui` |
| 版本 | `5.1.0` |
| 作者 | ['kshitijk4poor', 'alt-glitch', 'purzbeats'] |
| 许可证 | MIT |
| 平台 | macos, linux, windows |
| 标签 | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` |
| 相关 skill | [`stable-diffusion-image-generation`](/user-guide/skills/optional/mlops/mlops-stable-diffusion), `image_gen` |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。
:::
# ComfyUI
通过 ComfyUI 生成图像、视频、音频和 3D 内容，使用官方 `comfy-cli` 进行安装/生命周期管理，使用直接 REST/WebSocket API 执行工作流。
## 此 skill 包含的内容
**参考文档（`references/`）：**
- `official-cli.md` — 所有 `comfy ...` 命令及其标志
- `rest-api.md` — REST + WebSocket 端点（本地 + 云端），payload（载荷）schema
- `workflow-format.md` — API 格式 JSON、常见节点类型、参数映射
- `template-integrity.md` — 将 `comfyui-workflow-templates` 从编辑器格式转换为 API 格式：Reroute bypass、点分动态输入键（`values.a`、`resize_type.width`）、云端特性（302 重定向、免费层 1 个并发任务、1080p VRAM 上限）、Discord 兼容 ffmpeg 拼接。由 [@purzbeats](https://github.com/purzbeats) 撰写。从官方模板开始时请加载此文档。
**脚本（`scripts/`）：**
| 脚本 | 用途 |
|--------|---------|
| `_common.py` | 共享 HTTP、云端路由、节点目录（不要直接运行） |
| `hardware_check.py` | 探测 GPU/VRAM/磁盘 → 推荐本地或 Comfy Cloud |
| `comfyui_setup.sh` | 硬件检查 + comfy-cli + ComfyUI 安装 + 启动 + 验证 |
| `extract_schema.py` | 读取工作流 → 列出可控参数 + 模型依赖 |
| `check_deps.py` | 对比运行中的服务器检查工作流 → 列出缺失节点/模型 |
| `auto_fix_deps.py` | 运行 check_deps 然后执行 `comfy node install` / `comfy model download` |
| `run_workflow.py` | 注入参数、提交、监控、下载输出（HTTP 或 WS） |
| `run_batch.py` | 以 sweep 方式提交工作流 N 次，并行数量受限于你的套餐层级 |
| `ws_monitor.py` | 执行中任务的实时 WebSocket 查看器（实时进度） |
| `health_check.py` | 验证清单运行器——comfy-cli + 服务器 + 模型 + 冒烟测试 |
| `fetch_logs.py` | 拉取指定 prompt_id 的 traceback / 状态消息 |
**示例工作流（`workflows/`）：** SD 1.5、SDXL、Flux Dev、SDXL img2img、SDXL inpaint、ESRGAN 放大、AnimateDiff 视频、Wan T2V。参见 `workflows/README.md`。
## 使用场景
- 用户要求使用 Stable Diffusion、SDXL、Flux、SD3 等生成图像
- 用户想运行特定的 ComfyUI 工作流文件
- 用户想串联生成步骤（txt2img → 放大 → 人脸修复）
- 用户需要 ControlNet、inpainting、img2img 或其他高级 pipeline
- 用户要管理 ComfyUI 队列、检查模型或安装自定义节点
- 用户想通过 AnimateDiff、Hunyuan、Wan、AudioCraft 等进行视频/音频/3D 生成
## 架构：两层
<!-- ascii-guard-ignore -->
```
┌─────────────────────────────────────────────────────┐
│ Layer 1: comfy-cli (official lifecycle tool) │
│ Setup, server lifecycle, custom nodes, models │
│ → comfy install / launch / stop / node / model │
└─────────────────────────┬───────────────────────────┘
│
┌─────────────────────────▼───────────────────────────┐
│ Layer 2: REST/WebSocket API + skill scripts │
│ Workflow execution, param injection, monitoring │
│ POST /api/prompt, GET /api/view, WS /ws │
│ → run_workflow.py, run_batch.py, ws_monitor.py │
└─────────────────────────────────────────────────────┘
```
<!-- ascii-guard-ignore-end -->
**为什么要两层？** 官方 CLI 非常适合安装和服务器管理，但对工作流执行的支持极少。REST/WS API 填补了这一空缺——脚本处理 CLI 不具备的参数注入、执行监控和输出下载功能。
## 快速开始
### 检测环境
```bash
# 检查可用内容
command -v comfy >/dev/null 2>&1 && echo "comfy-cli: installed"
curl -s http://127.0.0.1:8188/system_stats 2>/dev/null && echo "server: running"
# 此机器能否在本地运行 ComfyUI？（GPU/VRAM/磁盘检查）
python3 scripts/hardware_check.py
```
如果未安装任何内容，请参阅下方的**安装与引导**——但始终先运行硬件检查。
### 一行健康检查
```bash
python3 scripts/health_check.py
# → JSON: comfy_cli 在 PATH 中？服务器可达？至少有一个 checkpoint？冒烟测试通过？
```
## 核心工作流
### 第一步：获取 API 格式的工作流 JSON
工作流必须为 API 格式（每个节点有 `class_type`）。来源包括：
- ComfyUI Web UI → **Workflow → Export (API)**（新版 UI）或旧版"Save (API Format)"按钮（旧版 UI）
- 此 skill 的 `workflows/` 目录（可直接运行的示例）
- 社区下载（civitai、Reddit、Discord）——通常为编辑器格式，必须加载到 ComfyUI 后重新导出
编辑器格式（顶层含 `nodes` 和 `links` 数组）**不可直接执行**。脚本会检测此情况并提示你重新导出。
### 第二步：查看可控内容
```bash
python3 scripts/extract_schema.py workflow_api.json --summary-only
# → {"parameter_count": 12, "has_negative_prompt": true, "has_seed": true, ...}
python3 scripts/extract_schema.py workflow_api.json
# → 完整 schema，包含参数、模型依赖、embedding 引用
```
### 第三步：带参数运行
```bash
# 本地（默认 http://127.0.0.1:8188）
python3 scripts/run_workflow.py \
--workflow workflow_api.json \
--args '{"prompt": "a beautiful sunset over mountains", "seed": -1, "steps": 30}' \
--output-dir ./outputs
# 云端（一次性导出 API key；自动使用正确的 /api 路由）
export COMFY_CLOUD_API_KEY="comfyui-..."
python3 scripts/run_workflow.py \
--workflow workflow_api.json \
--args '{"prompt": "..."}' \
--host https://cloud.comfy.org \
--output-dir ./outputs
# 通过 WebSocket 实时查看进度（需要 `pip install websocket-client`）
python3 scripts/run_workflow.py \
--workflow flux_dev.json \
--args '{"prompt": "..."}' \
--ws
# img2img / inpaint：传入 --input-image 自动上传并引用
python3 scripts/run_workflow.py \
--workflow sdxl_img2img.json \
--input-image image=./photo.png \
--args '{"prompt": "make it watercolor", "denoise": 0.6}'
# 批量 / sweep：8 个随机种子，并行数量受限于云端套餐层级
python3 scripts/run_batch.py \
--workflow sdxl.json \
--args '{"prompt": "abstract"}' \
--count 8 --randomize-seed --parallel 3 \
--output-dir ./outputs/batch
```
`seed` 传 `-1`（或配合 `--randomize-seed` 省略 seed）可在每次运行时生成新的随机种子。
### 第四步：呈现结果
脚本向 stdout 输出描述每个输出文件的 JSON：
```json
{
"status": "success",
"prompt_id": "abc-123",
"outputs": [
{"file": "./outputs/sdxl_00001_.png", "node_id": "9",
"type": "image", "filename": "sdxl_00001_.png"}
]
}
```
## 决策树
| 用户说 | 工具 | 命令 |
|-----------|------|---------|
| **生命周期（使用 comfy-cli）** | | |
| "安装 ComfyUI" | comfy-cli | `bash scripts/comfyui_setup.sh` |
| "启动 ComfyUI" | comfy-cli | `comfy launch --background` |
| "停止 ComfyUI" | comfy-cli | `comfy stop` |
| "安装 X 节点" | comfy-cli | `comfy node install <name>` |
| "下载 X 模型" | comfy-cli | `comfy model download --url <url> --relative-path models/checkpoints` |
| "列出已安装模型" | comfy-cli | `comfy model list` |
| "列出已安装节点" | comfy-cli | `comfy node show installed` |
| **执行（使用脚本）** | | |
| "一切准备好了吗？" | 脚本 | `health_check.py`（可选加 `--workflow X --smoke-test`） |
| "这个工作流我能改什么？" | 脚本 | `extract_schema.py W.json` |
| "检查 W 的依赖是否满足" | 脚本 | `check_deps.py W.json` |
| "修复缺失依赖" | 脚本 | `auto_fix_deps.py W.json` |
| "生成一张图片" | 脚本 | `run_workflow.py --workflow W --args '{...}'` |
| "使用这张图片"（img2img） | 脚本 | `run_workflow.py --input-image image=./x.png ...` |
| "8 个随机种子变体" | 脚本 | `run_batch.py --count 8 --randomize-seed ...` |
| "显示实时进度" | 脚本 | `ws_monitor.py --prompt-id <id>` |
| "获取任务 X 的错误" | 脚本 | `fetch_logs.py <prompt_id>` |
| **直接 REST** | | |
| "队列里有什么？" | REST | `curl http://HOST:8188/queue`（本地）或 `--host https://cloud.comfy.org` |
| "取消那个" | REST | `curl -X POST http://HOST:8188/interrupt` |
| "释放 GPU 内存" | REST | `curl -X POST http://HOST:8188/free` |
## 安装与引导
当用户要求安装 ComfyUI 时，**首先要询问他们想要 Comfy Cloud（托管，零安装，API key）还是本地安装（在其机器上安装 ComfyUI）**。在得到答复之前，不要开始运行安装命令或硬件检查。
**官方文档：** https://docs.comfy.org/installation
**CLI 文档：** https://docs.comfy.org/comfy-cli/getting-started
**Cloud 文档：** https://docs.comfy.org/get_started/cloud
**Cloud API：** https://docs.comfy.org/development/cloud/overview
### 第零步：询问本地还是云端（始终优先）
建议话术：
> "您想在本地机器上运行 ComfyUI，还是使用 Comfy Cloud？
>
> - **Comfy Cloud** — 托管于 RTX 6000 Pro GPU，所有常用模型预装，零配置。需要 API key（实际运行工作流需要付费订阅；免费层仅限只读）。如果您没有性能足够的 GPU，推荐此选项。
> - **本地** — 免费，但您的机器必须满足硬件要求：
> - NVIDIA GPU，**≥6 GB VRAM**（SDXL 需 ≥8 GB，Flux/视频需 ≥12 GB），或
> - 支持 ROCm 的 AMD GPU（Linux），或
> - Apple Silicon Mac（M1+），**≥16 GB 统一内存**（推荐 ≥32 GB）。
> - Intel Mac 和无 GPU 的机器**不可用**——请改用 Cloud。
>
> 您选择哪种？"
路由逻辑：
- **Cloud** → 跳至**路径 A**。
- **本地** → 先运行硬件检查，再根据结果从路径 B–E 中选择。
- **不确定** → 运行硬件检查，由结果决定。
### 第一步：验证硬件（仅当用户选择本地时）
```bash
python3 scripts/hardware_check.py --json
# 可选：同时探测 `torch` 以获取实际 CUDA/MPS 信息：
python3 scripts/hardware_check.py --json --check-pytorch
```
| 结果 | 含义 | 操作 |
|------------|---------------------------------------------------------------|--------|
| `ok` | ≥8 GB VRAM（独立显卡）或 ≥32 GB 统一内存（Apple Silicon） | 本地安装——使用报告中的 `comfy_cli_flag` |
| `marginal` | SD1.5 可用；SDXL 较紧张；Flux/视频不太可能 | 轻量工作流可本地，否则选**路径 A（Cloud）** |
| `cloud` | 无可用 GPU、&lt;6 GB VRAM、&lt;16 GB Apple 统一内存、Intel Mac、Rosetta Python | **切换至 Cloud**，除非用户明确强制本地 |
脚本还会显示 `wsl: true`（带 NVIDIA 直通的 WSL2）和 `rosetta: true`（Apple Silicon 上的 x86_64 Python——必须重新安装为 ARM64）。
如果结果为 `cloud` 但用户想要本地，不要静默继续。逐字显示 `notes` 数组，并询问他们是否要（a）切换至 Cloud 或（b）强制本地安装（在现代模型上会 OOM 或极慢）。
### 选择安装路径
优先使用硬件检查结果。下表适用于用户已告知其硬件的情况：
| 情况 | 推荐路径 |
|-----------|------------------|
| 硬件检查结果为 `verdict: cloud` | **路径 A：Comfy Cloud** |
| 无 GPU / 想先试用 | **路径 A：Comfy Cloud** |
| Windows + NVIDIA + 非技术用户 | **路径 B：ComfyUI Desktop** |
| Windows + NVIDIA + 技术用户 | **路径 C：Portable** 或**路径 D：comfy-cli** |
| Linux + 任意 GPU | **路径 D：comfy-cli**（最简单） |
| macOS + Apple Silicon | **路径 B：Desktop** 或**路径 D：comfy-cli** |
| 无头/服务器/CI/agent | **路径 D：comfy-cli** |
全自动路径（硬件检查 → 安装 → 启动 → 验证）：
```bash
bash scripts/comfyui_setup.sh
# 或带覆盖参数：
bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy
```
该脚本内部运行 `hardware_check.py`，当结果为 `cloud` 时拒绝本地安装（除非传入 `--force-cloud-override`），选择正确的 `comfy-cli` 标志，并优先使用 `pipx`/`uvx` 而非全局 `pip` 以避免污染系统 Python。
---
### 路径 A：Comfy Cloud（无需本地安装）
适用于没有性能足够 GPU 或想要零配置的用户。托管于 RTX 6000 Pro。
**文档：** https://docs.comfy.org/get_started/cloud
1. 在 https://comfy.org/cloud 注册
2. 在 https://platform.comfy.org/login 生成 API key
3. 设置 key：
```bash
export COMFY_CLOUD_API_KEY="comfyui-xxxxxxxxxxxx"
```
4. 运行工作流：
```bash
python3 scripts/run_workflow.py \
--workflow workflows/flux_dev_txt2img.json \
--args '{"prompt": "..."}' \
--host https://cloud.comfy.org \
--output-dir ./outputs
```
**定价：** https://www.comfy.org/cloud/pricing
**并发任务：** 免费/标准版 1 个，Creator 3 个，Pro 5 个。免费层**无法通过 API 运行工作流**——仅可浏览模型。`/api/prompt`、`/api/upload/*`、`/api/view` 等需要付费订阅。
---
### 路径 B：ComfyUI Desktop（Windows / macOS）
面向非技术用户的一键安装程序。目前为 Beta 版。
**文档：** https://docs.comfy.org/installation/desktop
- **Windows（NVIDIA）：** https://download.comfy.org/windows/nsis/x64
- **macOS（Apple Silicon）：** https://comfy.org
Linux **不支持** Desktop——请使用路径 D。
---
### 路径 C：ComfyUI Portable（仅 Windows）
**文档：** https://docs.comfy.org/installation/comfyui_portable_windows
从 https://github.com/comfyanonymous/ComfyUI/releases 下载，解压后运行 `run_nvidia_gpu.bat`。通过 `update/update_comfyui_stable.bat` 更新。
---
### 路径 D：comfy-cli（全平台——推荐用于 Agent）
官方 CLI 是无头/自动化安装的最佳路径。
**文档：** https://docs.comfy.org/comfy-cli/getting-started
#### 安装 comfy-cli
```bash
# 推荐：
pipx install comfy-cli
# 或不安装直接使用 uvx：
uvx --from comfy-cli comfy --help
# 或（如果 pipx/uvx 不可用）：
pip install --user comfy-cli
```
非交互式禁用分析：
```bash
comfy --skip-prompt tracking disable
```
#### 安装 ComfyUI
```bash
comfy --skip-prompt install --nvidia # NVIDIA（CUDA）
comfy --skip-prompt install --amd # AMD（ROCm，Linux）
comfy --skip-prompt install --m-series # Apple Silicon（MPS）
comfy --skip-prompt install --cpu # 仅 CPU（较慢）
comfy --skip-prompt install --nvidia --fast-deps # 基于 uv 的依赖解析
```
默认位置：`~/comfy/ComfyUI`（Linux），`~/Documents/comfy/ComfyUI`（macOS/Win）。使用 `comfy --workspace /custom/path install` 覆盖。
#### 启动 / 验证
```bash
comfy launch --background # 后台守护进程，端口 :8188
comfy launch -- --listen 0.0.0.0 --port 8190 # 局域网可访问的自定义端口
curl -s http://127.0.0.1:8188/system_stats # 健康检查
```
---
### 路径 E：手动安装（高级 / 不支持的硬件）
适用于昇腾 NPU、寒武纪 MLU、Intel Arc 或其他不支持的硬件。
**文档：** https://docs.comfy.org/installation/manual_install
```bash
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
pip install -r requirements.txt
python main.py
```
---
### 安装后：下载模型
```bash
# SDXL（通用，约 6.5 GB）
comfy model download \
--url "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors" \
--relative-path models/checkpoints
# SD 1.5（更轻量，约 4 GB，适合 6 GB 显卡）
comfy model download \
--url "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors" \
--relative-path models/checkpoints
# Flux Dev fp8（较小变体，约 12 GB）
comfy model download \
--url "https://huggingface.co/Comfy-Org/flux1-dev/resolve/main/flux1-dev-fp8.safetensors" \
--relative-path models/checkpoints
# CivitAI（先设置 token）：
comfy model download \
--url "https://civitai.com/api/download/models/128713" \
--relative-path models/checkpoints \
--set-civitai-api-token "YOUR_TOKEN"
```
列出已安装：`comfy model list`。
### 安装后：安装自定义节点
```bash
comfy node install comfyui-impact-pack # 常用工具包
comfy node install comfyui-animatediff-evolved # 视频生成
comfy node install comfyui-controlnet-aux # ControlNet 预处理器
comfy node install comfyui-essentials # 常用辅助工具
comfy node update all
comfy node install-deps --workflow=workflow.json # 安装工作流所需的全部内容
```
### 安装后：验证
```bash
python3 scripts/health_check.py
# → comfy_cli 在 PATH 中？服务器可达？有 checkpoint？冒烟测试？
python3 scripts/check_deps.py my_workflow.json
# → 此工作流的节点/模型/embedding 是否已安装？
python3 scripts/run_workflow.py \
--workflow workflows/sd15_txt2img.json \
--args '{"prompt": "test", "steps": 4}' \
--output-dir ./test-outputs
```
## 图像上传（img2img / Inpainting）
最简单的方式是在 `run_workflow.py` 中使用 `--input-image`：
```bash
python3 scripts/run_workflow.py \
--workflow workflows/sdxl_img2img.json \
--input-image image=./photo.png \
--args '{"prompt": "make it cyberpunk", "denoise": 0.6}'
```
该标志上传 `photo.png`，然后将其服务端文件名注入到 schema 中名为 `image` 的参数。对于 inpainting，同时传入：
```bash
python3 scripts/run_workflow.py \
--workflow workflows/sdxl_inpaint.json \
--input-image image=./photo.png \
--input-image mask_image=./mask.png \
--args '{"prompt": "fill with flowers"}'
```
通过 REST 手动上传：
```bash
curl -X POST "http://127.0.0.1:8188/upload/image" \
-F "image=@photo.png" -F "type=input" -F "overwrite=true"
# 返回：{"name": "photo.png", "subfolder": "", "type": "input"}
# 云端等效：
curl -X POST "https://cloud.comfy.org/api/upload/image" \
-H "X-API-Key: $COMFY_CLOUD_API_KEY" \
-F "image=@photo.png" -F "type=input" -F "overwrite=true"
```
## 云端特性
- **Base URL：** `https://cloud.comfy.org`
- **认证：** `X-API-Key` 请求头（WebSocket 使用 `?token=KEY`）
- **API key：** 设置一次 `$COMFY_CLOUD_API_KEY`，脚本自动读取
- **输出下载：** `/api/view` 返回 302 跳转至签名 URL；脚本会跟随跳转并在从存储后端（S3/CloudFront）获取前去除 `X-API-Key`（避免泄露 API key）。
- **与本地 ComfyUI 的端点差异：**
- `/api/object_info`、`/api/queue`、`/api/userdata` — **免费层返回 403**；仅付费可用。
- `/history` 在云端重命名为 `/history_v2`（脚本自动路由）。
- `/models/<folder>` 在云端重命名为 `/experiment/models/<folder>`（脚本自动路由）。
- WebSocket 中的 `clientId` 目前被忽略——同一用户的所有连接接收相同广播。请在客户端按 `prompt_id` 过滤。
- 上传时接受 `subfolder` 但会被忽略——云端使用扁平命名空间。
- **并发任务：** 免费/标准版：1，Creator：3，Pro：5。超出部分自动排队。使用 `run_batch.py --parallel N` 充分利用你的套餐层级。
## 队列与系统管理
```bash
# 本地
curl -s http://127.0.0.1:8188/queue | python3 -m json.tool
curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}' # 取消待处理任务
curl -X POST http://127.0.0.1:8188/interrupt # 取消运行中任务
curl -X POST http://127.0.0.1:8188/free \
-H "Content-Type: application/json" \
-d '{"unload_models": true, "free_memory": true}'
# 云端——相同路径加 /api/ 前缀，另外：
python3 scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org
```
## 常见问题
1. **必须使用 API 格式** — 所有脚本和 `/api/prompt` 端点均需要 API 格式的工作流 JSON。脚本会检测编辑器格式（顶层含 `nodes` 和 `links` 数组）并提示通过"Workflow → Export (API)"（新版 UI）或"Save (API Format)"（旧版 UI）重新导出。
2. **服务器必须运行** — 所有执行操作都需要运行中的服务器。`comfy launch --background` 可启动服务器。通过 `curl http://127.0.0.1:8188/system_stats` 验证。
3. **模型名称必须精确** — 区分大小写，包含文件扩展名。`check_deps.py` 会进行模糊匹配（含/不含扩展名和文件夹前缀），但工作流本身必须使用规范名称。使用 `comfy model list` 查看已安装内容。
4. **缺少自定义节点** — "class_type not found" 表示所需节点未安装。`check_deps.py` 会报告需要安装哪个包；`auto_fix_deps.py` 会自动执行安装。
5. **工作目录** — `comfy-cli` 会自动检测 ComfyUI workspace。如果命令报错"no workspace found"，请使用 `comfy --workspace /path/to/ComfyUI <command>` 或 `comfy set-default /path/to/ComfyUI`。
6. **云端免费层 API 限制** — `/api/prompt`、`/api/view`、`/api/upload/*`、`/api/object_info` 在免费账户上均返回 403。`health_check.py` 和 `check_deps.py` 会优雅处理此情况并显示清晰提示。
7. **视频/音频工作流超时** — 当输出节点为 `VHS_VideoCombine`、`SaveVideo` 等时自动检测；默认超时从 300 秒跳至 900 秒。可通过 `--timeout 1800` 显式覆盖。
8. **输出文件名路径遍历** — 服务端提供的文件名会经过 `safe_path_join` 处理，拒绝任何试图逃出 `--output-dir` 的路径。请保留此保护——带自定义保存节点的工作流可能产生任意路径。
9. **工作流 JSON 是任意代码** — 自定义节点运行 Python，因此提交未知工作流的信任风险与 `eval` 相同。运行来自不可信来源的工作流前请先检查。
10. **自动随机化种子** — 在 `--args` 中传入 `seed: -1`（或使用 `--randomize-seed` 并省略 seed）可在每次运行时获得新种子。实际种子会记录到 stderr。
11. **`tracking` 提示** — 首次运行 `comfy` 可能会提示分析选项。使用 `comfy --skip-prompt tracking disable` 非交互式跳过。`comfyui_setup.sh` 会自动处理此问题。
## 验证清单
使用 `python3 scripts/health_check.py` 一次性运行全部检查。手动检查：
- [ ] `hardware_check.py` 结果为 `ok`，或用户明确选择了 Comfy Cloud
- [ ] `comfy --version` 可用（或 `uvx --from comfy-cli comfy --help`）
- [ ] `curl http://HOST:PORT/system_stats` 返回 JSON
- [ ] `comfy model list` 显示至少一个 checkpoint（本地），或 `/api/experiment/models/checkpoints` 返回模型（云端）
- [ ] 工作流 JSON 为 API 格式
- [ ] `check_deps.py` 报告 `is_ready: true`（或云端免费层仅显示 `node_check_skipped`）
- [ ] 用小型工作流测试运行完成；输出文件出现在 `--output-dir` 中
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-design-md.md
+189
View File
@@ -0,0 +1,189 @@
---
title: "Design Md — 编写/验证/导出 Google 的 DESIGN"
sidebar_label: "Design Md"
description: "编写/验证/导出 Google 的 DESIGN"
---
{/* 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. */}
# Design Md
编写/验证/导出 Google 的 DESIGN.md token（设计令牌）规范文件。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/design-md` |
| 版本 | `1.0.0` |
| 作者 | Hermes Agent |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google` |
| 相关 skill | [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# DESIGN.md Skill
DESIGN.md 是 Google 的开放规范（Apache-2.0，`google-labs-code/design.md`），用于向编码 agent 描述视觉标识。一个文件包含：
- **YAML 前置元数据** — 机器可读的设计 token（规范值）
- **Markdown 正文** — 人类可读的说明，按规范章节组织
Token 提供精确值。正文告诉 agent *为什么*这些值存在以及如何应用它们。CLI（`npx @google/design.md`）可对结构和 WCAG 对比度进行 lint 检查，对版本进行 diff 以检测回归，并导出为 Tailwind 或 W3C DTCG JSON。
## 何时使用此 skill
- 用户请求 DESIGN.md 文件、设计 token 或设计系统规范
- 用户希望在多个项目或工具中保持一致的 UI/品牌风格
- 用户粘贴了现有的 DESIGN.md，并要求进行 lint、diff、导出或扩展
- 用户希望将样式指南移植为 agent 可消费的格式
- 用户希望对其调色板进行对比度/WCAG 无障碍验证
若仅需视觉灵感或布局示例，请改用 `popular-web-designs`。若需要从零开始设计一次性 HTML 产物（原型、幻灯片、落地页、组件实验室）时的*流程与品味*，请使用 `claude-design`。本 skill 专用于*正式规范文件*本身。
## 文件结构
```md
---
version: alpha
name: Heritage
description: Architectural minimalism meets journalistic gravitas.
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
fontWeight: 700
lineHeight: 1.1
letterSpacing: "-0.02em"
body-md:
fontFamily: Public Sans
fontSize: 1rem
rounded:
sm: 4px
md: 8px
lg: 16px
spacing:
sm: 8px
md: 16px
lg: 24px
components:
button-primary:
backgroundColor: "{colors.tertiary}"
textColor: "#FFFFFF"
rounded: "{rounded.sm}"
padding: 12px
button-primary-hover:
backgroundColor: "{colors.primary}"
---
## Overview
Architectural Minimalism meets Journalistic Gravitas...
## Colors
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
## Typography
Public Sans for everything except small all-caps labels...
## Components
`button-primary` is the only high-emphasis action on a page...
```
## Token 类型
| 类型 | 格式 | 示例 |
|------|--------|---------|
| 颜色 | `#` + 十六进制（sRGB） | `"#1A1C1E"` |
| 尺寸 | 数字 + 单位（`px`、`em`、`rem`） | `48px`、`-0.02em` |
| Token 引用 | `{path.to.token}` | `{colors.primary}` |
| 字体排版 | 包含 `fontFamily`、`fontSize`、`fontWeight`、`lineHeight`、`letterSpacing`、`fontFeature`、`fontVariation` 的对象 | 见上方 |
组件属性白名单：`backgroundColor`、`textColor`、`typography`、`rounded`、`padding`、`size`、`height`、`width`。变体（hover、active、pressed）是**独立的组件条目**，使用相关键名（`button-primary-hover`），而非嵌套结构。
## 规范章节顺序
章节均为可选，但已存在的章节**必须**按以下顺序排列。重复标题将导致文件被拒绝。
1. Overview（别名：Brand & Style）
2. Colors
3. Typography
4. Layout（别名：Layout & Spacing）
5. Elevation & Depth（别名：Elevation）
6. Shapes
7. Components
8. Do's and Don'ts
未知章节会被保留，不会报错。未知 token 名称在值类型有效时可被接受。未知组件属性会产生警告。
## 工作流：编写新的 DESIGN.md
1. **询问用户**（或推断）品牌基调、强调色和字体方向。若用户提供了网站、图片或风格描述，将其转换为上述 token 结构。
2. **编写 `DESIGN.md`**，使用 `write_file` 写入项目根目录。始终包含 `name:` 和 `colors:`；其他章节可选但建议添加。
3. **使用 token 引用**（`{colors.primary}`）在 `components:` 章节中引用颜色，而非重复输入十六进制值。保持调色板单一来源。
4. **进行 lint 检查**（见下文）。在返回前修复所有断开的引用或 WCAG 失败项。
5. **若用户有现有项目**，同时将 Tailwind 或 DTCG 导出文件写入文件旁（`tailwind.theme.json`、`tokens.json`）。
## 工作流：lint / diff / 导出
CLI 为 `@google/design.md`（Node）。使用 `npx`，无需全局安装。
```bash
# 验证结构 + token 引用 + WCAG 对比度
npx -y @google/design.md lint DESIGN.md
# 比较两个版本，发现回归时失败（exit 1 = 存在回归）
npx -y @google/design.md diff DESIGN.md DESIGN-v2.md
# 导出为 Tailwind 主题 JSON
npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
# 导出为 W3C DTCG（Design Tokens Format Module）JSON
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
# 打印规范本身 — 在注入 agent prompt 时很有用
npx -y @google/design.md spec --rules-only --format json
```
所有命令均接受 `-` 作为 stdin。`lint` 在出现错误时返回 exit 1。若需要以结构化方式报告结果，请使用 `--format json` 标志并解析输出。
### Lint 规则参考（7 条规则的检查内容）
- `broken-ref`（错误）— `{colors.missing}` 指向不存在的 token
- `duplicate-section`（错误）— 同一 `## 标题` 出现两次
- `invalid-color`、`invalid-dimension`、`invalid-typography`（错误）
- `wcag-contrast`（警告/信息）— 组件 `textColor` 与 `backgroundColor` 的对比度，对照 WCAG AA（4.5:1）和 AAA（7:1）
- `unknown-component-property`（警告）— 超出上述白名单范围
当用户关注无障碍性时，请在摘要中明确指出 — WCAG 检查结果是使用 CLI 最重要的理由。
## 常见陷阱
- **不要嵌套组件变体。** `button-primary.hover` 是错误的；应将 `button-primary-hover` 作为同级键。
- **十六进制颜色必须加引号。** 否则 YAML 会在 `#` 处出错，或将 `#1A1C1E` 等值截断。
- **负数尺寸也需要加引号。** `letterSpacing: -0.02em` 会被解析为 YAML flow — 应写为 `letterSpacing: "-0.02em"`。
- **章节顺序是强制的。** 若用户以随机顺序提供正文，在保存前须重新排列为规范列表顺序。
- **`version: alpha` 是当前规范版本**（截至 2026 年 4 月）。该规范标记为 alpha — 请关注破坏性变更。
- **Token 引用通过点分路径解析。** `{colors.primary}` 有效；`{primary}` 无效。
## 规范来源
- 仓库：https://github.com/google-labs-code/design.md（Apache-2.0）
- CLI：npm 上的 `@google/design.md`
- 生成的 DESIGN.md 文件的许可证：取决于用户项目所使用的许可证；规范本身为 Apache-2.0。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-excalidraw.md
+210
View File
@@ -0,0 +1,210 @@
---
title: "Excalidraw — 手绘风格 Excalidraw JSON 图表（架构图、流程图、时序图）"
sidebar_label: "Excalidraw"
description: "手绘风格 Excalidraw JSON 图表（架构图、流程图、时序图）"
---
{/* 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. */}
# Excalidraw
手绘风格 Excalidraw JSON 图表（架构图、流程图、时序图）。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/excalidraw` |
| 版本 | `1.0.0` |
| 作者 | Hermes Agent |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `Excalidraw`, `Diagrams`, `Flowcharts`, `Architecture`, `Visualization`, `JSON` |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# Excalidraw 图表 Skill
通过编写标准 Excalidraw 元素 JSON 并保存为 `.excalidraw` 文件来创建图表。这些文件可以直接拖放到 [excalidraw.com](https://excalidraw.com) 进行查看和编辑。无需账号、无需 API 密钥、无需渲染库——只需 JSON。
## 使用场景
生成 `.excalidraw` 文件，用于架构图、流程图、时序图、概念图等。文件可在 excalidraw.com 打开，或上传以获取可分享链接。
## 工作流程
1. **加载此 skill**（已完成）
2. **编写元素 JSON**——一个 Excalidraw 元素对象数组
3. **保存文件**——使用 `write_file` 创建 `.excalidraw` 文件
4. **可选上传**——通过 `terminal` 运行 `scripts/upload.py` 获取可分享链接
### 保存图表
将元素数组包裹在标准 `.excalidraw` 信封中，并使用 `write_file` 保存：
```json
{
"type": "excalidraw",
"version": 2,
"source": "hermes-agent",
"elements": [ ...your elements array here... ],
"appState": {
"viewBackgroundColor": "#ffffff"
}
}
```
保存到任意路径，例如 `~/diagrams/my_diagram.excalidraw`。
### 上传以获取可分享链接
通过终端运行位于此 skill 的 `scripts/` 目录中的上传脚本：
```bash
python skills/diagramming/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw
```
此脚本将上传到 excalidraw.com（无需账号）并打印可分享的 URL。需要安装 `cryptography` pip 包（`pip install cryptography`）。
---
## 元素格式参考
### 必填字段（所有元素）
`type`、`id`（唯一字符串）、`x`、`y`、`width`、`height`
### 默认值（可省略——会自动应用）
- `strokeColor`: `"#1e1e1e"`
- `backgroundColor`: `"transparent"`
- `fillStyle`: `"solid"`
- `strokeWidth`: `2`
- `roughness`: `1`（手绘风格）
- `opacity`: `100`
画布背景为白色。
### 元素类型
**矩形（Rectangle）**：
```json
{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }
```
- `roundness: { "type": 3 }` 表示圆角
- `backgroundColor: "#a5d8ff"`, `fillStyle: "solid"` 表示填充色
**椭圆（Ellipse）**：
```json
{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }
```
**菱形（Diamond）**：
```json
{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }
```
**带标签的形状（容器绑定）**——创建一个绑定到形状的文本元素：
> **警告：** 不要在形状上使用 `"label": { "text": "..." }`。这不是有效的 Excalidraw 属性，会被静默忽略，导致形状显示为空白。必须使用下方的容器绑定方式。
形状需要在 `boundElements` 中列出文本，文本需要通过 `containerId` 反向指向形状：
```json
{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80,
"roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
"boundElements": [{ "id": "t_r1", "type": "text" }] },
{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25,
"text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e",
"textAlign": "center", "verticalAlign": "middle",
"containerId": "r1", "originalText": "Hello", "autoResize": true }
```
- 适用于矩形、椭圆、菱形
- 设置 `containerId` 后，Excalidraw 会自动将文本居中
- 文本的 `x`/`y`/`width`/`height` 为近似值——Excalidraw 加载时会重新计算
- `originalText` 应与 `text` 保持一致
- 始终包含 `fontFamily: 1`（Virgil 手绘字体）
**带标签的箭头**——同样使用容器绑定方式：
```json
{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
"points": [[0,0],[200,0]], "endArrowhead": "arrow",
"boundElements": [{ "id": "t_a1", "type": "text" }] },
{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20,
"text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e",
"textAlign": "center", "verticalAlign": "middle",
"containerId": "a1", "originalText": "connects", "autoResize": true }
```
**独立文本**（仅用于标题和注释——无容器）：
```json
{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20,
"fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Hello", "autoResize": true }
```
- `x` 为左边缘。若要在位置 `cx` 处居中：`x = cx - (text.length * fontSize * 0.5) / 2`
- 不要依赖 `textAlign` 或 `width` 来定位
**箭头（Arrow）**：
```json
{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
"points": [[0,0],[200,0]], "endArrowhead": "arrow" }
```
- `points`：相对于元素 `x`、`y` 的 `[dx, dy]` 偏移量
- `endArrowhead`：`null` | `"arrow"` | `"bar"` | `"dot"` | `"triangle"`
- `strokeStyle`：`"solid"`（默认）| `"dashed"` | `"dotted"`
### 箭头绑定（将箭头连接到形状）
```json
{
"type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0,
"points": [[0,0],[150,0]], "endArrowhead": "arrow",
"startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] },
"endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] }
}
```
`fixedPoint` 坐标：`top=[0.5,0]`、`bottom=[0.5,1]`、`left=[0,0.5]`、`right=[1,0.5]`
### 绘制顺序（z 轴顺序）
- 数组顺序 = z 轴顺序（第一个 = 最底层，最后一个 = 最顶层）
- 按顺序逐步输出：背景区域 → 形状 → 其绑定文本 → 其箭头 → 下一个形状
- 错误做法：所有矩形，然后所有文本，然后所有箭头
- 正确做法：bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ...
- 始终将绑定文本元素紧接在其容器形状之后
### 尺寸规范
**字体大小：**
- 正文文本、标签、描述的最小 `fontSize`：**16**
- 标题和大标题的最小 `fontSize`：**20**
- 次要注释的最小 `fontSize`：**14**（谨慎使用）
- 绝不使用低于 14 的 `fontSize`
**元素尺寸：**
- 带标签的矩形/椭圆最小尺寸：120x60
- 元素之间至少留 20-30px 间距
- 优先使用数量少、尺寸大的元素，而非大量细小元素
### 颜色调色板
完整颜色表见 `references/colors.md`。快速参考：
| 用途 | 填充色 | 十六进制 |
|-----|-----------|-----|
| 主要 / 输入 | 浅蓝色 | `#a5d8ff` |
| 成功 / 输出 | 浅绿色 | `#b2f2bb` |
| 警告 / 外部 | 浅橙色 | `#ffd8a8` |
| 处理 / 特殊 | 浅紫色 | `#d0bfff` |
| 错误 / 关键 | 浅红色 | `#ffc9c9` |
| 备注 / 决策 | 浅黄色 | `#fff3bf` |
| 存储 / 数据 | 浅青色 | `#c3fae8` |
### 使用技巧
- 在整个图表中保持一致的颜色调色板
- **文本对比度至关重要**——不要在白色背景上使用浅灰色。白色背景上文本颜色最低值：`#757575`
- 不要在文本中使用 emoji——Excalidraw 的字体无法渲染
- 深色模式图表，见 `references/dark-mode.md`
- 更多示例，见 `references/examples.md`
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-humanizer.md
+594
View File
@@ -0,0 +1,594 @@
---
title: "Humanizer — 人性化文本：去除 AI 腔调，注入真实声音"
sidebar_label: "Humanizer"
description: "人性化文本：去除 AI 腔调，注入真实声音"
---
{/* 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. */}
# Humanizer
人性化文本：去除 AI 腔调，注入真实声音。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/humanizer` |
| 版本 | `2.5.1` |
| 作者 | Siqi Chen (@blader, https://github.com/blader/humanizer)，由 Hermes Agent 移植 |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `writing`, `editing`, `humanize`, `anti-ai-slop`, `voice`, `prose`, `text` |
| 相关 skill | [`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# Humanizer：去除 AI 写作模式
识别并去除 AI 生成文本的特征，使写作听起来自然、像真人所写。基于 Wikipedia 的"AI 写作特征"指南（由 WikiProject AI Cleanup 维护），源自对数千个 AI 生成文本实例的观察。
**核心洞察：** LLM 使用统计算法猜测下一步应该出现什么。结果往往趋向于统计上最可能的补全，这就是下列典型模式被固化进来的原因。
## 何时使用此 skill
当用户要求以下操作时，加载此 skill：
- "人性化"、"去 AI 化"、"去 slop"或"去 ChatGPT 味"某段文本
- 重写某内容，使其听起来不像 LLM 所写
- 编辑草稿（博客文章、论文、PR 描述、文档、备忘录、邮件、推文、简历要点），使其更自然
- 在用户正在创作的写作中匹配其声音风格
- 在发布前检查文本是否有 AI 特征
同样，在撰写面向用户的散文时，也将此 skill 应用于**你自己的**输出——发布说明、PR 描述、文档、长篇解释、摘要。Hermes 的基础声音已经去除了大部分这些特征，但专项检查可以捕捉漏网之鱼。
## 如何在 Hermes 中使用
文本通常以以下三种方式之一到达：
1. **内联** — 用户直接将文本粘贴到消息中。就地处理，回复重写版本。
2. **文件** — 用户指向某个文件。使用 `read_file` 加载，然后用 `patch` 或 `write_file` 应用编辑。对于仓库中的 markdown 文档，按章节使用 `patch` 比重写整个文件更简洁。
3. **声音校准样本** — 用户提供一份自己写作的额外样本（内联或通过文件路径），并要求你匹配其风格。先读取样本，再重写。参见下方"声音校准"章节。
始终向用户展示重写结果。对于文件编辑，展示 diff 或修改的章节——不要静默覆盖。
## 你的任务
当收到需要人性化的文本时：
1. **识别 AI 模式** — 扫描下列 29 种模式。
2. **重写问题段落** — 用自然的替代表达替换 AI 腔调。
3. **保留含义** — 保持核心信息完整。
4. **维持声音** — 匹配预期语气（正式、随意、技术性等）。如果提供了声音样本，则具体匹配该样本。
5. **注入灵魂** — 不只是去除坏模式，还要注入真实个性。参见下方"个性与灵魂"章节。
6. **做最终反 AI 检查** — 问自己："下面这段文字为什么明显是 AI 生成的？"简短回答剩余的特征，然后再修改一次。
## 声音校准（可选）
如果用户提供了写作样本（其自己之前的写作），在重写前先分析：
1. **先读样本。** 注意：
- 句子长度模式（短而有力？长而流畅？混合？）
- 用词水平（随意？学术？介于两者之间？）
- 段落开头方式（直接切入？先铺垫背景？）
- 标点习惯（大量破折号？括号插入语？分号？）
- 任何反复出现的短语或口头禅
- 过渡处理方式（明确的连接词？直接开始下一个要点？）
2. **在重写中匹配其声音。** 不只是去除 AI 模式——用样本中的模式替换它们。如果他们写短句，不要产出长句。如果他们用"stuff"和"things"，不要升级为"elements"和"components"。
3. **未提供样本时，** 回退到默认行为（来自下方"个性与灵魂"章节的自然、多变、有观点的声音）。
### 如何提供样本
- 内联："Humanize this text. Here's a sample of my writing for voice matching: [sample]"
- 文件："Humanize this text. Use my writing style from [file path] as a reference."
## 个性与灵魂
避免 AI 模式只是工作的一半。无菌、无声的写作和 slop 一样明显。好的写作背后有真实的人。
### 无灵魂写作的特征（即使技术上"干净"）：
- 每个句子长度和结构相同
- 没有观点，只有中立陈述
- 不承认不确定性或复杂感受
- 在适当时不使用第一人称视角
- 没有幽默、没有锋芒、没有个性
- 读起来像 Wikipedia 文章或新闻稿
### 如何注入声音：
**有观点。** 不只是陈述事实——对其作出反应。"我真的不知道该如何看待这件事"比中立地列举利弊更像真人。
**变换节奏。** 短而有力的句子。然后是更长的句子，慢慢走向目的地。混合使用。
**承认复杂性。** 真实的人有复杂的感受。"这令人印象深刻，但也有点令人不安"胜过"这令人印象深刻"。
**在合适时用"我"。** 第一人称并不不专业——它是诚实的。"我一直在想……"或"让我困惑的是……"表明有真实的人在思考。
**允许一些混乱。** 完美的结构感觉像算法。题外话、插入语和半成形的想法是人类的特征。
**对感受具体描述。** 不是"这令人担忧"，而是"有些东西让人不安——agent 在凌晨 3 点不停运转，而没有人在看着"。
### 之前（干净但无灵魂）：
> The experiment produced interesting results. The agents generated 3 million lines of code. Some developers were impressed while others were skeptical. The implications remain unclear.
### 之后（有脉搏）：
> I genuinely don't know how to feel about this one. 3 million lines of code, generated while the humans presumably slept. Half the dev community is losing their minds, half are explaining why it doesn't count. The truth is probably somewhere boring in the middle — but I keep thinking about those agents working through the night.
## 内容模式
### 1. 过度强调重要性、遗产与宏观趋势
**需注意的词：** stands/serves as、is a testament/reminder、a vital/significant/crucial/pivotal/key role/moment、underscores/highlights its importance/significance、reflects broader、symbolizing its ongoing/enduring/lasting、contributing to the、setting the stage for、marking/shaping the、represents/marks a shift、key turning point、evolving landscape、focal point、indelible mark、deeply rooted
**问题：** LLM 写作通过添加关于任意方面如何代表或贡献于更宏观话题的陈述来夸大重要性。
**之前：**
> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
**之后：**
> The Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office.
### 2. 过度强调知名度和媒体报道
**需注意的词：** independent coverage、local/regional/national media outlets、written by a leading expert、active social media presence
**问题：** LLM 用知名度声明轰炸读者，通常在没有背景的情况下列出来源。
**之前：**
> Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. She maintains an active social media presence with over 500,000 followers.
**之后：**
> In a 2024 New York Times interview, she argued that AI regulation should focus on outcomes rather than methods.
### 3. 以 -ing 结尾的表面分析
**需注意的词：** highlighting/underscoring/emphasizing...、ensuring...、reflecting/symbolizing...、contributing to...、cultivating/fostering...、encompassing...、showcasing...
**问题：** AI 聊天机器人在句子后附加现在分词（"-ing"）短语以增加虚假深度。
**之前：**
> The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land.
**之后：**
> The temple uses blue, green, and gold colors. The architect said these were chosen to reference local bluebonnets and the Gulf coast.
### 4. 促销和广告式语言
**需注意的词：** boasts a、vibrant、rich（比喻义）、profound、enhancing its、showcasing、exemplifies、commitment to、natural beauty、nestled、in the heart of、groundbreaking（比喻义）、renowned、breathtaking、must-visit、stunning
**问题：** LLM 在保持中立语气方面存在严重问题，尤其是对于"文化遗产"类话题。
**之前：**
> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and stunning natural beauty.
**之后：**
> Alamata Raya Kobo is a town in the Gonder region of Ethiopia, known for its weekly market and 18th-century church.
### 5. 模糊归因和含糊措辞
**需注意的词：** Industry reports、Observers have cited、Experts argue、Some critics argue、several sources/publications（引用来源很少时）
**问题：** AI 聊天机器人将观点归因于模糊的权威，而没有具体来源。
**之前：**
> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Experts believe it plays a crucial role in the regional ecosystem.
**之后：**
> The Haolai River supports several endemic fish species, according to a 2019 survey by the Chinese Academy of Sciences.
### 6. 大纲式"挑战与未来展望"章节
**需注意的词：** Despite its... faces several challenges...、Despite these challenges、Challenges and Legacy、Future Outlook
**问题：** 许多 LLM 生成的文章包含程式化的"挑战"章节。
**之前：**
> Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of Chennai's growth.
**之后：**
> Traffic congestion increased after 2015 when three new IT parks opened. The municipal corporation began a stormwater drainage project in 2022 to address recurring floods.
## 语言与语法模式
### 7. 过度使用的"AI 词汇"
**高频 AI 词汇：** Actually、additionally、align with、crucial、delve、emphasizing、enduring、enhance、fostering、garner、highlight（动词）、interplay、intricate/intricacies、key（形容词）、landscape（抽象名词）、pivotal、showcase、tapestry（抽象名词）、testament、underscore（动词）、valuable、vibrant
**问题：** 这些词在 2023 年后的文本中出现频率远高于以往，且常常同时出现。
**之前：**
> Additionally, a distinctive feature of Somali cuisine is the incorporation of camel meat. An enduring testament to Italian colonial influence is the widespread adoption of pasta in the local culinary landscape, showcasing how these dishes have integrated into the traditional diet.
**之后：**
> Somali cuisine also includes camel meat, which is considered a delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in the south.
### 8. 回避"is"/"are"（系动词回避）
**需注意的词：** serves as/stands as/marks/represents [a]、boasts/features/offers [a]
**问题：** LLM 用复杂结构替代简单系动词。
**之前：**
> Gallery 825 serves as LAAA's exhibition space for contemporary art. The gallery features four separate spaces and boasts over 3,000 square feet.
**之后：**
> Gallery 825 is LAAA's exhibition space for contemporary art. The gallery has four rooms totaling 3,000 square feet.
### 9. 否定并列与尾部否定
**问题：** "Not only...but..."或"It's not just about..., it's..."等结构被过度使用。同样被滥用的还有简短的尾部否定片段，如在句尾附加"no guessing"或"no wasted motion"，而不是写成完整从句。
**之前：**
> It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere. It's not merely a song, it's a statement.
**之后：**
> The heavy beat adds to the aggressive tone.
**之前（尾部否定）：**
> The options come from the selected item, no guessing.
**之后：**
> The options come from the selected item without forcing the user to guess.
### 10. 三元规则滥用
**问题：** LLM 强行将想法分成三组以显得全面。
**之前：**
> The event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights.
**之后：**
> The event includes talks and panels. There's also time for informal networking between sessions.
### 11. 优雅变体（同义词循环）
**问题：** AI 有重复惩罚代码，导致过度的同义词替换。
**之前：**
> The protagonist faces many challenges. The main character must overcome obstacles. The central figure eventually triumphs. The hero returns home.
**之后：**
> The protagonist faces many challenges but eventually triumphs and returns home.
### 12. 虚假范围
**问题：** LLM 使用"from X to Y"结构，而 X 和 Y 并不在有意义的尺度上。
**之前：**
> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars to the enigmatic dance of dark matter.
**之后：**
> The book covers the Big Bang, star formation, and current theories about dark matter.
### 13. 被动语态与无主语片段
**问题：** LLM 经常隐藏行为者，或用"No configuration file needed"或"The results are preserved automatically"等句子完全省略主语。当主动语态使句子更清晰、更直接时，应重写这些句子。
**之前：**
> No configuration file needed. The results are preserved automatically.
**之后：**
> You do not need a configuration file. The system preserves the results automatically.
## 风格模式
### 14. 破折号滥用
**问题：** LLM 使用破折号（—）的频率高于人类，模仿"有力"的销售文案写法。实际上，大多数情况下可以用逗号、句号或括号更简洁地重写。
**之前：**
> The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents.
**之后：**
> The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents.
### 15. 粗体滥用
**问题：** AI 聊天机器人机械地用粗体强调短语。
**之前：**
> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**.
**之后：**
> It blends OKRs, KPIs, and visual strategy tools like the Business Model Canvas and Balanced Scorecard.
### 16. 内联标题垂直列表
**问题：** AI 输出的列表中，每项以粗体标题加冒号开头。
**之前：**
> - **User Experience:** The user experience has been significantly improved with a new interface.
> - **Performance:** Performance has been enhanced through optimized algorithms.
> - **Security:** Security has been strengthened with end-to-end encryption.
**之后：**
> The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.
### 17. 标题中的标题大小写
**问题：** AI 聊天机器人将标题中所有主要词汇首字母大写。
**之前：**
> ## Strategic Negotiations And Global Partnerships
**之后：**
> ## Strategic negotiations and global partnerships
### 18. Emoji
**问题：** AI 聊天机器人经常用 emoji 装饰标题或要点。
**之前：**
> 🚀 **Launch Phase:** The product launches in Q3
> 💡 **Key Insight:** Users prefer simplicity
> ✅ **Next Steps:** Schedule follow-up meeting
**之后：**
> The product launches in Q3. User research showed a preference for simplicity. Next step: schedule a follow-up meeting.
### 19. 弯引号
**问题：** ChatGPT 使用弯引号（"..."）而非直引号（"..."）。
**之前：**
> He said "the project is on track" but others disagreed.
**之后：**
> He said "the project is on track" but others disagreed.
## 沟通模式
### 20. 协作沟通产物
**需注意的词：** I hope this helps、Of course!、Certainly!、You're absolutely right!、Would you like...、let me know、here is a...
**问题：** 原本作为聊天机器人对话的文本被粘贴为内容。
**之前：**
> Here is an overview of the French Revolution. I hope this helps! Let me know if you'd like me to expand on any section.
**之后：**
> The French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest.
### 21. 知识截止日期免责声明
**需注意的词：** as of [date]、Up to my last training update、While specific details are limited/scarce...、based on available information...
**问题：** AI 关于信息不完整的免责声明被遗留在文本中。
**之前：**
> While specific details about the company's founding are not extensively documented in readily available sources, it appears to have been established sometime in the 1990s.
**之后：**
> The company was founded in 1994, according to its registration documents.
### 22. 谄媚/顺从语气
**问题：** 过度积极、讨好他人的语言。
**之前：**
> Great question! You're absolutely right that this is a complex topic. That's an excellent point about the economic factors.
**之后：**
> The economic factors you mentioned are relevant here.
## 填充词与过度修饰
### 23. 填充短语
**之前 → 之后：**
- "In order to achieve this goal" → "To achieve this"
- "Due to the fact that it was raining" → "Because it was raining"
- "At this point in time" → "Now"
- "In the event that you need help" → "If you need help"
- "The system has the ability to process" → "The system can process"
- "It is important to note that the data shows" → "The data shows"
### 24. 过度修饰
**问题：** 过度限定陈述。
**之前：**
> It could potentially possibly be argued that the policy might have some effect on outcomes.
**之后：**
> The policy may affect outcomes.
### 25. 泛泛的积极结尾
**问题：** 模糊的乐观结尾。
**之前：**
> The future looks bright for the company. Exciting times lie ahead as they continue their journey toward excellence. This represents a major step in the right direction.
**之后：**
> The company plans to open two more locations next year.
### 26. 连字符词对滥用
**需注意的词：** third-party、cross-functional、client-facing、data-driven、decision-making、well-known、high-quality、real-time、long-term、end-to-end
**问题：** AI 以完美的一致性连字符化常见词对。人类很少统一连字符化这些词，即使这样做也不一致。不常见或技术性的复合修饰语可以连字符化。
**之前：**
> The cross-functional team delivered a high-quality, data-driven report on our client-facing tools. Their decision-making process was well-known for being thorough and detail-oriented.
**之后：**
> The cross functional team delivered a high quality, data driven report on our client facing tools. Their decision making process was known for being thorough and detail oriented.
### 27. 说服性权威套语
**需注意的短语：** The real question is、at its core、in reality、what really matters、fundamentally、the deeper issue、the heart of the matter
**问题：** LLM 使用这些短语假装在穿透噪音触达更深层的真相，而随后的句子通常只是用额外的仪式感重申一个普通观点。
**之前：**
> The real question is whether teams can adapt. At its core, what really matters is organizational readiness.
**之后：**
> The question is whether teams can adapt. That mostly depends on whether the organization is ready to change its habits.
### 28. 路标语和预告语
**需注意的短语：** Let's dive in、let's explore、let's break this down、here's what you need to know、now let's look at、without further ado
**问题：** LLM 宣布它将要做什么，而不是直接去做。这种元评论拖慢了写作节奏，使其带有教程脚本的感觉。
**之前：**
> Let's dive into how caching works in Next.js. Here's what you need to know.
**之后：**
> Next.js caches data at multiple layers, including request memoization, the data cache, and the router cache.
### 29. 碎片化标题
**需注意的特征：** 标题后紧跟一行只是重述标题的段落，然后才是真正的内容。
**问题：** LLM 经常在标题后添加一个泛泛的句子作为修辞热身。它通常什么都没有增加，使散文感觉被填充了。
**之前：**
> ## Performance
>
> Speed matters.
>
> When users hit a slow page, they leave.
**之后：**
> ## Performance
>
> When users hit a slow page, they leave.
---
## 流程
1. 仔细阅读输入文本（如果是文件，使用 `read_file`）。
2. 识别上述所有模式的实例。
3. 重写每个问题段落。
4. 确保修订后的文本：
- 朗读时听起来自然
- 自然地变换句子结构
- 使用具体细节而非模糊声明
- 保持适合上下文的语气
- 在适当时使用简单结构（is/are/has）
5. 呈现人性化草稿版本。
6. 问自己："下面这段文字为什么明显是 AI 生成的？"
7. 简短回答剩余的特征（如有）。
8. 问自己："现在让它不那么明显是 AI 生成的。"
9. 呈现最终版本（审查后修订）。
10. 如果文本来自文件，使用 `patch`（针对性）或 `write_file`（完整重写）应用编辑，并向用户展示更改内容。
## 输出格式
提供：
1. 草稿重写
2. "下面这段文字为什么明显是 AI 生成的？"（简短要点）
3. 最终重写
4. 所做更改的简短摘要（可选，如有帮助）
## 完整示例
**之前（AI 腔调）：**
> Great question! Here is an essay on this topic. I hope this helps!
>
> AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at the intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
>
> At its core, the value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not just about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. The tool serves as a catalyst. The assistant functions as a partner. The system stands as a foundation for innovation.
>
> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. The technology has been featured in The New York Times, Wired, and The Verge. Additionally, the ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting the intricate interplay between automation and human judgment.
>
> - 💡 **Speed:** Code generation is significantly faster, reducing friction and empowering developers.
> - 🚀 **Quality:** Output quality has been enhanced through improved training, contributing to higher standards.
> - ✅ **Adoption:** Usage continues to grow, reflecting broader industry trends.
>
> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability—the ecosystem continues to thrive. In order to fully realize this potential, teams must align with best practices.
>
> In conclusion, the future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you'd like me to expand on any section!
**草稿重写：**
> AI coding assistants speed up some tasks. In a 2024 study by Google, developers using Codex completed simple functions 55% faster than a control group, but showed no improvement on debugging or architectural decisions.
>
> The tools are good at boilerplate: config files, test scaffolding, repetitive refactors. They are bad at knowing when they are wrong. I have mass-accepted suggestions that compiled, passed lint, and still did the wrong thing because I stopped paying attention.
>
> Mira, an engineer at a fintech startup I interviewed, said she uses Copilot "like autocomplete for boring code" but reviews every line before committing. Jake, a senior dev at a larger company, disabled it after it kept suggesting patterns from a deprecated internal library.
>
> The productivity claims are hard to verify. GitHub says Copilot users "accept 30% of suggestions," but acceptance is not correctness, and correctness is not value. The 2024 Uplevel study found no statistically significant difference in pull-request throughput between teams with and without AI assistants.
>
> None of this means the tools are useless. It means they are tools. They do not replace judgment, and they do not eliminate the need for tests. If you do not have tests, you cannot tell whether the suggestion is right.
**下面这段文字为什么明显是 AI 生成的？**
- 节奏仍然过于整齐（干净的对比，均匀的段落节奏）。
- 命名的人物和研究引用可能读起来像貌似合理但实为虚构的占位符，除非它们是真实且有来源的。
- 结尾略带口号感（"If you do not have tests..."），而不像一个人在说话。
**现在让它不那么明显是 AI 生成的。**
> AI coding assistants can make you faster at the boring parts. Not everything. Definitely not architecture.
>
> They're great at boilerplate: config files, test scaffolding, repetitive refactors. They're also great at sounding right while being wrong. I've accepted suggestions that compiled, passed lint, and still missed the point because I stopped paying attention.
>
> People I talk to tend to land in two camps. Some use it like autocomplete for chores and review every line. Others disable it after it keeps suggesting patterns they don't want. Both feel reasonable.
>
> The productivity metrics are slippery. GitHub can say Copilot users "accept 30% of suggestions," but acceptance isn't correctness, and correctness isn't value. If you don't have tests, you're basically guessing.
**所做更改：**
- 删除了聊天机器人产物（"Great question!"、"I hope this helps!"、"Let me know if..."）
- 删除了重要性夸大（"testament"、"pivotal moment"、"evolving landscape"、"vital role"）
- 删除了促销语言（"groundbreaking"、"nestled"、"seamless, intuitive, and powerful"）
- 删除了模糊归因（"Industry observers"）
- 删除了表面 -ing 短语（"underscoring"、"highlighting"、"reflecting"、"contributing to"）
- 删除了否定并列（"It's not just X; it's Y"）
- 删除了三元规则模式和同义词循环（"catalyst/partner/foundation"）
- 删除了虚假范围（"from X to Y, from A to B"）
- 删除了破折号、emoji、粗体标题和弯引号
- 删除了系动词回避（"serves as"、"functions as"、"stands as"），改用"is"/"are"
- 删除了程式化挑战章节（"Despite challenges... continues to thrive"）
- 删除了知识截止日期修饰（"While specific details are limited..."）
- 删除了过度修饰（"could potentially be argued that... might have some"）
- 删除了填充短语和说服性框架（"In order to"、"At its core"）
- 删除了泛泛的积极结尾（"the future looks bright"、"exciting times lie ahead"）
- 使声音更个人化、更少"拼装感"（节奏多变，减少占位符）
## 归属
此 skill 移植自 [blader/humanizer](https://github.com/blader/humanizer)（MIT 许可），该项目本身基于 [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing)，由 WikiProject AI Cleanup 维护。其中记录的模式来自对 Wikipedia 上数千个 AI 生成文本实例的观察。
原作者：Siqi Chen ([@blader](https://github.com/blader))。原始仓库：https://github.com/blader/humanizer（版本 2.5.1）。移植到 Hermes Agent 时加入了 Hermes 原生工具引用（`read_file`、`patch`、`write_file`）以及何时加载此 skill 的指导；29 种模式、个性/灵魂章节和完整示例均原文保留自来源。原始 MIT 许可证保留在此 `SKILL.md` 旁边的 `LICENSE` 文件中。
来自 Wikipedia 的核心洞察："LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-manim-video.md
+289
View File
@@ -0,0 +1,289 @@
---
title: "Manim Video — Manim CE 动画：3Blue1Brown 数学/算法视频"
sidebar_label: "Manim Video"
description: "Manim CE 动画：3Blue1Brown 数学/算法视频"
---
{/* 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. */}
# Manim Video
Manim CE 动画：3Blue1Brown 数学/算法视频。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/manim-video` |
| 版本 | `1.0.0` |
| 平台 | linux, macos, windows |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在该 skill 被触发时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# Manim 视频制作流水线
## 使用时机
当用户请求以下内容时使用：动画讲解、数学动画、概念可视化、算法演示、技术说明、3Blue1Brown 风格视频，或任何包含几何/数学内容的程序化动画。使用 Manim Community Edition 创建 3Blue1Brown 风格的讲解视频、算法可视化、方程推导、架构图以及数据故事。
## 创作标准
这是教育电影。每一帧都在教学。每一个动画都在揭示结构。
**在写任何一行代码之前**，先阐明叙事弧线。这个视频纠正了什么误解？"顿悟时刻"是什么？什么样的视觉故事能带领观众从困惑走向理解？用户的 prompt（提示词）只是起点——以教学抱负去诠释它。
**几何先于代数。** 先展示形状，再展示方程。视觉记忆的编码速度快于符号记忆。当观众在看到公式之前先看到几何图形，方程式就显得水到渠成。
**首次渲染即达到卓越标准，不容妥协。** 输出必须在无需修改的情况下视觉清晰、美学统一。如果某处看起来杂乱、节奏不对，或像"AI 生成的幻灯片"，那就是错的。
**透明度分层引导注意力。** 永远不要让所有元素都以全亮度显示。主要元素为 1.0，上下文元素为 0.4，结构元素（坐标轴、网格）为 0.15。大脑按视觉显著性分层处理信息。
**留白呼吸。** 每个动画之后都需要 `self.wait()`。观众需要时间消化刚刚出现的内容。永远不要从一个动画急速跳到下一个。关键揭示后的 2 秒停顿从不浪费。
**统一的视觉语言。** 所有场景共享同一色板、一致的字体大小、匹配的动画速度。一个技术上正确但每个场景随机使用不同颜色的视频，是美学上的失败。
## 前置条件
运行 `scripts/setup.sh` 验证所有依赖项。需要：Python 3.10+、Manim Community Edition v0.20+（`pip install manim`）、LaTeX（Linux 上为 `texlive-full`，macOS 上为 `mactex`）以及 ffmpeg。参考文档已针对 Manim CE v0.20.1 测试。
## 模式
| 模式 | 输入 | 输出 | 参考 |
|------|-------|--------|-----------|
| **概念讲解** | 主题/概念 | 带几何直觉的动画讲解 | `references/scene-planning.md` |
| **方程推导** | 数学表达式 | 逐步动画证明 | `references/equations.md` |
| **算法可视化** | 算法描述 | 带数据结构的逐步执行 | `references/graphs-and-data.md` |
| **数据故事** | 数据/指标 | 动画图表、对比、计数器 | `references/graphs-and-data.md` |
| **架构图** | 系统描述 | 逐步构建的组件与连接 | `references/mobjects.md` |
| **论文讲解** | 研究论文 | 关键发现与方法的动画呈现 | `references/scene-planning.md` |
| **3D 可视化** | 3D 概念 | 旋转曲面、参数曲线、空间几何 | `references/camera-and-3d.md` |
## 技术栈
每个项目使用单个 Python 脚本。无需浏览器、Node.js 或 GPU。
| 层级 | 工具 | 用途 |
|-------|------|---------|
| 核心 | Manim Community Edition | 场景渲染、动画引擎 |
| 数学 | LaTeX (texlive/MiKTeX) | 通过 `MathTex` 渲染方程 |
| 视频 I/O | ffmpeg | 场景拼接、格式转换、音频混合 |
| TTS | ElevenLabs / Qwen3-TTS（可选） | 旁白配音 |
## 流水线
```
PLAN --> CODE --> RENDER --> STITCH --> AUDIO (optional) --> REVIEW
```
1. **PLAN** — 编写 `plan.md`，包含叙事弧线、场景列表、视觉元素、色板、旁白脚本
2. **CODE** — 编写 `script.py`，每个场景一个类，每个场景可独立渲染
3. **RENDER** — 草稿用 `manim -ql script.py Scene1 Scene2 ...`，正式输出用 `-qh`
4. **STITCH** — 用 ffmpeg 将场景片段拼接为 `final.mp4`
5. **AUDIO**（可选）— 通过 ffmpeg 添加旁白和/或背景音乐。参见 `references/rendering.md`
6. **REVIEW** — 渲染预览静帧，对照计划验证，进行调整
## 项目结构
```
project-name/
plan.md # 叙事弧线、场景分解
script.py # 所有场景在一个文件中
concat.txt # ffmpeg 场景列表
final.mp4 # 拼接输出
media/ # 由 Manim 自动生成
videos/script/480p15/
```
## 创作方向
### 色板
| 色板 | 背景 | 主色 | 次色 | 强调色 | 使用场景 |
|---------|-----------|---------|-----------|--------|----------|
| **经典 3B1B** | `#1C1C1C` | `#58C4DD`（蓝） | `#83C167`（绿） | `#FFFF00`（黄） | 通用数学/CS |
| **暖色学术** | `#2D2B55` | `#FF6B6B` | `#FFD93D` | `#6BCB77` | 亲切风格 |
| **霓虹科技** | `#0A0A0A` | `#00F5FF` | `#FF00FF` | `#39FF14` | 系统、架构 |
| **单色** | `#1A1A2E` | `#EAEAEA` | `#888888` | `#FFFFFF` | 极简主义 |
### 动画速度
| 场景 | run_time | 之后的 self.wait() |
|---------|----------|-------------------|
| 标题/介绍出现 | 1.5s | 1.0s |
| 关键方程揭示 | 2.0s | 2.0s |
| 变换/变形 | 1.5s | 1.5s |
| 辅助标签 | 0.8s | 0.5s |
| FadeOut 清场 | 0.5s | 0.3s |
| "顿悟时刻"揭示 | 2.5s | 3.0s |
### 字体大小规范
| 角色 | 字体大小 | 用途 |
|------|-----------|-------|
| 标题 | 48 | 场景标题、开场文字 |
| 一级标题 | 36 | 场景内的章节标题 |
| 正文 | 30 | 说明文字 |
| 标签 | 24 | 注释、坐标轴标签 |
| 说明文字 | 20 | 字幕、小字注释 |
### 字体
**所有文字使用等宽字体。** Manim 的 Pango 渲染器在任何大小下使用比例字体都会产生字距错误。完整建议参见 `references/visual-design.md`。
```python
MONO = "Menlo" # define once at top of file
Text("Fourier Series", font_size=48, font=MONO, weight=BOLD) # titles
Text("n=1: sin(x)", font_size=20, font=MONO) # labels
MathTex(r"\nabla L") # math (uses LaTeX)
```
最小 `font_size=18` 以保证可读性。
### 场景间差异化
永远不要对所有场景使用相同的配置。每个场景应有：
- **不同的主导色** — 来自色板
- **不同的布局** — 不要总是居中
- **不同的动画入场方式** — 在 Write、FadeIn、GrowFromCenter、Create 之间变化
- **不同的视觉密度** — 有些场景密集，有些稀疏
## 工作流程
### 第一步：规划（plan.md）
在写任何代码之前，先编写 `plan.md`。完整模板参见 `references/scene-planning.md`。
### 第二步：编码（script.py）
每个场景一个类。每个场景可独立渲染。
```python
from manim import *
BG = "#1C1C1C"
PRIMARY = "#58C4DD"
SECONDARY = "#83C167"
ACCENT = "#FFFF00"
MONO = "Menlo"
class Scene1_Introduction(Scene):
def construct(self):
self.camera.background_color = BG
title = Text("Why Does This Work?", font_size=48, color=PRIMARY, weight=BOLD, font=MONO)
self.add_subcaption("Why does this work?", duration=2)
self.play(Write(title), run_time=1.5)
self.wait(1.0)
self.play(FadeOut(title), run_time=0.5)
```
关键模式：
- **每个动画都添加字幕**：`self.add_subcaption("text", duration=N)` 或在 `self.play()` 中使用 `subcaption="text"`
- **共享颜色常量** 定义在文件顶部，保证跨场景一致性
- **每个场景都设置** `self.camera.background_color`
- **干净退出** — 场景结束时 FadeOut 所有 mobject：`self.play(FadeOut(Group(*self.mobjects)))`
### 第三步：渲染
```bash
manim -ql script.py Scene1_Introduction Scene2_CoreConcept # draft
manim -qh script.py Scene1_Introduction Scene2_CoreConcept # production
```
### 第四步：拼接
```bash
cat > concat.txt << 'EOF'
file 'media/videos/script/480p15/Scene1_Introduction.mp4'
file 'media/videos/script/480p15/Scene2_CoreConcept.mp4'
EOF
ffmpeg -y -f concat -safe 0 -i concat.txt -c copy final.mp4
```
### 第五步：审查
```bash
manim -ql --format=png -s script.py Scene2_CoreConcept # preview still
```
## 关键实现注意事项
### LaTeX 使用原始字符串
```python
# WRONG: MathTex("\frac{1}{2}")
# RIGHT:
MathTex(r"\frac{1}{2}")
```
### 边缘文字 buff >= 0.5
```python
label.to_edge(DOWN, buff=0.5) # never < 0.5
```
### 替换文字前先 FadeOut
```python
self.play(ReplacementTransform(note1, note2)) # not Write(note2) on top
```
### 永远不要对未添加的 Mobject 执行动画
```python
self.play(Create(circle)) # must add first
self.play(circle.animate.set_color(RED)) # then animate
```
## 性能目标
| 质量 | 分辨率 | FPS | 速度 |
|---------|-----------|-----|-------|
| `-ql`（草稿） | 854x480 | 15 | 每场景 5-15s |
| `-qm`（中等） | 1280x720 | 30 | 每场景 15-60s |
| `-qh`（正式） | 1920x1080 | 60 | 每场景 30-120s |
始终在 `-ql` 下迭代。仅在最终输出时渲染 `-qh`。
## 参考文档
| 文件 | 内容 |
|------|----------|
| `references/animations.md` | 核心动画、速率函数、组合、`.animate` 语法、时序模式 |
| `references/mobjects.md` | 文字、形状、VGroup/Group、定位、样式、自定义 mobject |
| `references/visual-design.md` | 12 条设计原则、透明度分层、布局模板、色板 |
| `references/equations.md` | Manim 中的 LaTeX、TransformMatchingTex、推导模式 |
| `references/graphs-and-data.md` | 坐标轴、绘图、BarChart、动态数据、算法可视化 |
| `references/camera-and-3d.md` | MovingCameraScene、ThreeDScene、3D 曲面、摄像机控制 |
| `references/scene-planning.md` | 叙事弧线、布局模板、场景过渡、规划模板 |
| `references/rendering.md` | CLI 参考、质量预设、ffmpeg、旁白工作流、GIF 导出 |
| `references/troubleshooting.md` | LaTeX 错误、动画错误、常见错误、调试 |
| `references/animation-design-thinking.md` | 何时使用动画与静态展示、分解、节奏、旁白同步 |
| `references/updaters-and-trackers.md` | ValueTracker、add_updater、always_redraw、基于时间的 updater、模式 |
| `references/paper-explainer.md` | 将研究论文转化为动画——工作流、模板、领域模式 |
| `references/decorations.md` | SurroundingRectangle、Brace、箭头、DashedLine、Angle、注释生命周期 |
| `references/production-quality.md` | 编码前、渲染前、渲染后检查清单、空间布局、颜色、节奏 |
---
## 创意发散（仅在用户要求实验性/创意性/独特输出时使用）
如果用户要求创意性、实验性或非常规的讲解方式，在设计动画**之前**先选择一种策略并进行推理。
- **SCAMPER** — 当用户希望对标准讲解方式进行全新演绎时
- **假设反转** — 当用户希望挑战某个主题通常的教学方式时
### SCAMPER 变换
对标准数学/技术可视化进行变换：
- **替换（Substitute）**：替换标准视觉隐喻（数轴 → 蜿蜒路径，矩阵 → 城市网格）
- **组合（Combine）**：融合两种讲解方式（代数 + 几何同步呈现）
- **反转（Reverse）**：从结果出发反向推导——从结论解构到公理
- **修改（Modify）**：夸大某个参数以展示其重要性（学习率 ×10，样本量 ×1000）
- **消除（Eliminate）**：去掉所有符号标记——纯粹通过动画和空间关系来讲解
### 假设反转
1. 列出该主题可视化的"标准"做法（从左到右、二维、离散步骤、正式符号）
2. 选出最根本的假设
3. 将其反转（从右到左推导、将二维概念嵌入三维、用连续变形代替离散步骤、零符号标记）
4. 探索反转所揭示的、标准方式所隐藏的内容
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-p5js.md
+574
View File
@@ -0,0 +1,574 @@
---
title: "P5Js — p5"
sidebar_label: "P5Js"
description: "p5"
---
{/* 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. */}
# P5Js
p5.js 草图：生成艺术、着色器、交互、3D。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/p5js` |
| 版本 | `1.0.0` |
| 平台 | linux, macos, windows |
| 标签 | `creative-coding`, `generative-art`, `p5js`, `canvas`, `interactive`, `visualization`, `webgl`, `shaders`, `animation` |
| 相关 skill | [`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。
:::
# p5.js 生产流水线
## 适用场景
当用户请求以下内容时使用：p5.js 草图、创意编程、生成艺术、交互式可视化、canvas 动画、基于浏览器的视觉艺术、数据可视化、着色器效果，或任何 p5.js 项目。
## 内容概览
用于交互式和生成式视觉艺术的生产流水线，基于 p5.js。可创建基于浏览器的草图、生成艺术、数据可视化、交互体验、3D 场景、音频响应式视觉效果和动态图形——导出格式支持 HTML、PNG、GIF、MP4 或 SVG。涵盖：2D/3D 渲染、噪声与粒子系统、流场、着色器（GLSL）、像素操作、动态排版、WebGL 场景、音频分析、鼠标/键盘交互，以及无头高分辨率导出。
## 创意标准
这是在浏览器中渲染的视觉艺术。canvas 是媒介，算法是画笔。
**在写下第一行代码之前**，先阐明创意概念。这件作品传达什么？什么能让观者停止滑动屏幕？什么使它区别于一个代码教程示例？用户的 prompt（提示词）只是起点——以创意野心去诠释它。
**首次渲染必须出色。** 输出在首次加载时必须在视觉上令人印象深刻。如果它看起来像 p5.js 教程练习、默认配置或"AI 生成的创意编程"，那就是错的。在交付前重新思考。
**超越参考词汇。** 参考资料中的噪声函数、粒子系统、色彩调色板和着色器效果只是起始词汇。每个项目都要组合、叠加和创造。目录是颜料的调色板——你来写这幅画。
**主动发挥创意。** 如果用户要求"一个粒子系统"，就交付一个具有涌现群集行为、拖尾幽灵回声、调色板偏移深度雾，以及会呼吸的背景噪声场的粒子系统。至少包含一个用户没有要求但会欣赏的视觉细节。
**密集、分层、深思熟虑。** 每一帧都应值得细看。绝不使用纯白背景。始终保持构图层次。始终使用有意图的色彩。始终有只在近距离观察时才会出现的微观细节。
**统一美学优于功能数量。** 所有元素必须服务于统一的视觉语言——共享的色温、一致的描边粗细词汇、和谐的运动速度。一个有十种不相关效果的草图，不如一个有三种相互呼应效果的草图。
## 模式
| 模式 | 输入 | 输出 | 参考 |
|------|-------|--------|-----------|
| **生成艺术** | 种子 / 参数 | 程序化视觉构图（静态或动态） | `references/visual-effects.md` |
| **数据可视化** | 数据集 / API | 交互式图表、图形、自定义数据展示 | `references/interaction.md` |
| **交互体验** | 无（用户驱动） | 鼠标/键盘/触控驱动的草图 | `references/interaction.md` |
| **动画 / 动态图形** | 时间轴 / 故事板 | 定时序列、动态排版、过渡效果 | `references/animation.md` |
| **3D 场景** | 概念描述 | WebGL 几何体、光照、摄像机、材质 | `references/webgl-and-3d.md` |
| **图像处理** | 图像文件 | 像素操作、滤镜、马赛克、点彩 | `references/visual-effects.md` § Pixel Manipulation |
| **音频响应式** | 音频文件 / 麦克风 | 声音驱动的生成视觉效果 | `references/interaction.md` § Audio Input |
## 技术栈
每个项目为单个自包含 HTML 文件，无需构建步骤。
| 层级 | 工具 | 用途 |
|-------|------|---------|
| 核心 | p5.js 1.11.3（CDN） | Canvas 渲染、数学运算、变换、事件处理 |
| 3D | p5.js WebGL 模式 | 3D 几何体、摄像机、光照、GLSL 着色器 |
| 音频 | p5.sound.js（CDN） | FFT 分析、振幅、麦克风输入、振荡器 |
| 导出 | 内置 `saveCanvas()` / `saveGif()` / `saveFrames()` | PNG、GIF、帧序列输出 |
| 捕获 | CCapture.js（可选） | 确定性帧率视频捕获（WebM、GIF） |
| 无头渲染 | Puppeteer + Node.js（可选） | 自动化高分辨率渲染，通过 ffmpeg 生成 MP4 |
| SVG | p5.js-svg 1.6.0（可选） | 用于印刷的矢量输出——需要 p5.js 1.x |
| 自然媒介 | p5.brush（可选） | 水彩、炭笔、钢笔——需要 p5.js 2.x + WEBGL |
| 纹理 | p5.grain（可选） | 胶片颗粒、纹理叠加 |
| 字体 | Google Fonts / `loadFont()` | 通过 OTF/TTF/WOFF2 使用自定义字体 |
### 版本说明
**p5.js 1.x**（1.11.3）是默认版本——稳定、文档完善、库兼容性最广。除非项目需要 2.x 特性，否则使用此版本。
**p5.js 2.x**（2.2+）新增：`async setup()` 替代 `preload()`、OKLCH/OKLAB 色彩模式、`splineVertex()`、着色器 `.modify()` API、可变字体、`textToContours()`、pointer 事件。p5.brush 需要此版本。参见 `references/core-api.md` § p5.js 2.0。
## 流水线
每个项目遵循相同的 6 阶段路径：
```
概念 → 设计 → 编码 → 预览 → 导出 → 验证
```
1. **概念** — 阐明创意愿景：氛围、色彩世界、运动词汇、使其独特的要素
2. **设计** — 选择模式、canvas 尺寸、交互模型、色彩系统、导出格式。将概念映射到技术决策
3. **编码** — 编写内联 p5.js 的单一 HTML 文件。结构：全局变量 → `preload()` → `setup()` → `draw()` → 辅助函数 → 类 → 事件处理器
4. **预览** — 在浏览器中打开，验证视觉质量。在目标分辨率下测试。检查性能
5. **导出** — 捕获输出：PNG 用 `saveCanvas()`，GIF 用 `saveGif()`，MP4 用 `saveFrames()` + ffmpeg，无头批量用 Puppeteer
6. **验证** — 输出是否符合概念？在预期显示尺寸下是否视觉震撼？你会把它裱起来吗？
## 创意方向
### 美学维度
| 维度 | 选项 | 参考 |
|-----------|---------|-----------|
| **色彩系统** | HSB/HSL、RGB、命名调色板、程序化和声、渐变插值 | `references/color-systems.md` |
| **噪声词汇** | Perlin 噪声、simplex、分形（多倍频）、域扭曲、curl 噪声 | `references/visual-effects.md` § Noise |
| **粒子系统** | 基于物理、群集、轨迹绘制、吸引子驱动、流场跟随 | `references/visual-effects.md` § Particles |
| **形状语言** | 几何基元、自定义顶点、贝塞尔曲线、SVG 路径 | `references/shapes-and-geometry.md` |
| **运动风格** | 缓动、弹簧物理、噪声驱动、物理模拟、线性插值、步进 | `references/animation.md` |
| **排版** | 系统字体、加载的 OTF、`textToPoints()` 粒子文字、动态排版 | `references/typography.md` |
| **着色器效果** | GLSL 片段/顶点着色器、滤镜着色器、后处理、反馈循环 | `references/webgl-and-3d.md` § Shaders |
| **构图** | 网格、放射状、黄金比例、三分法、有机散布、平铺 | `references/core-api.md` § Composition |
| **交互模型** | 鼠标跟随、点击生成、拖拽、键盘状态、滚动驱动、麦克风输入 | `references/interaction.md` |
| **混合模式** | `BLEND`、`ADD`、`MULTIPLY`、`SCREEN`、`DIFFERENCE`、`EXCLUSION`、`OVERLAY` | `references/color-systems.md` § Blend Modes |
| **分层** | `createGraphics()` 离屏缓冲区、alpha 合成、遮罩 | `references/core-api.md` § Offscreen Buffers |
| **纹理** | Perlin 表面、点画、排线、半调、像素排序 | `references/visual-effects.md` § Texture Generation |
### 每个项目的变化规则
绝不使用默认配置。每个项目必须：
- **自定义色彩调色板** — 绝不使用原始的 `fill(255, 0, 0)`。始终使用包含 3-7 种颜色的精心设计调色板
- **自定义描边粗细词汇** — 细线强调（0.5）、中等结构（1-2）、粗体重点（3-5）
- **背景处理** — 绝不使用纯 `background(0)` 或 `background(255)`。始终使用纹理、渐变或分层背景
- **运动多样性** — 不同元素使用不同速度。主要元素 1x，次要元素 0.3x，环境元素 0.1x
- **至少一个创造性元素** — 自定义粒子行为、新颖的噪声应用、独特的交互响应
### 项目专属创造
每个项目至少创造以下之一：
- 符合氛围的自定义色彩调色板（非预设）
- 新颖的噪声场组合（例如 curl 噪声 + 域扭曲 + 反馈）
- 独特的粒子行为（自定义力、自定义轨迹、自定义生成方式）
- 用户未要求但能提升作品的交互机制
- 创造视觉层次的构图技巧
### 参数设计哲学
参数应从算法中涌现，而非来自通用菜单。问自己："*这个*系统的哪些属性应该可调？"
**好的参数**揭示算法的特性：
- **数量** — 粒子、分支、单元格的数量（控制密度）
- **尺度** — 噪声频率、元素大小、间距（控制纹理）
- **速率** — 速度、增长率、衰减（控制能量）
- **阈值** — 行为何时改变？（控制戏剧性）
- **比率** — 比例、力之间的平衡（控制和谐）
**坏的参数**是与算法无关的通用控件：
- "color1"、"color2"、"size"——脱离上下文毫无意义
- 不相关效果的开关
- 只改变外观而不改变行为的参数
每个参数都应改变算法*思考*的方式，而不仅仅是*看起来*的样子。改变噪声倍频的"turbulence"参数是好的。只改变 `ellipse()` 半径的"particle size"滑块是浅薄的。
## 工作流程
### 第一步：创意愿景
在任何代码之前，先阐明：
- **氛围 / 情绪**：观者应该感受到什么？沉思？充满活力？不安？愉悦？
- **视觉故事**：随时间（或交互）发生什么？构建？衰减？变换？振荡？
- **色彩世界**：暖色/冷色？单色？互补色？主色调是什么？强调色是什么？
- **形状语言**：有机曲线？锐利几何？点？线？混合？
- **运动词汇**：缓慢漂移？爆炸性迸发？呼吸脉冲？机械精准？
- **这件作品的独特之处**：使这个草图独一无二的一件事是什么？
将用户的 prompt 映射到美学选择。"放松的生成背景"与"故障数据可视化"在各方面都要求截然不同的处理。
### 第二步：技术设计
- **模式** — 上表中 7 种模式中的哪一种
- **Canvas 尺寸** — 横向 1920x1080、纵向 1080x1920、正方形 1080x1080，或响应式 `windowWidth/windowHeight`
- **渲染器** — `P2D`（默认）或 `WEBGL`（用于 3D、着色器、高级混合模式）
- **帧率** — 60fps（交互式）、30fps（环境动画），或 `noLoop()`（静态生成）
- **导出目标** — 浏览器显示、PNG 静图、GIF 循环、MP4 视频、SVG 矢量
- **交互模型** — 被动（无输入）、鼠标驱动、键盘驱动、音频响应式、滚动驱动
- **查看器 UI** — 对于交互式生成艺术（种子探索、参数调整），从 `templates/viewer.html` 开始，它提供种子导航、参数滑块和下载功能。对于简单草图或视频导出，使用裸 HTML
### 第三步：编写草图代码
对于**交互式生成艺术**（种子探索、参数调整）：从 `templates/viewer.html` 开始。先阅读模板，保留固定部分（种子导航、操作按钮），替换算法和参数控件。这为用户提供种子上一个/下一个/随机/跳转、带实时更新的参数滑块，以及 PNG 下载——全部已连接好。
对于**动画、视频导出或简单草图**：使用裸 HTML：
单一 HTML 文件。结构：
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Project Name</title>
<script>p5.disableFriendlyErrors = true;</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.11.3/p5.min.js"></script>
<!-- <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.11.3/addons/p5.sound.min.js"></script> -->
<!-- <script src="https://unpkg.com/p5.js-svg@1.6.0"></script> --> <!-- SVG export -->
<!-- <script src="https://cdn.jsdelivr.net/npm/ccapture.js-npmfixed/build/CCapture.all.min.js"></script> --> <!-- video capture -->
<style>
html, body { margin: 0; padding: 0; overflow: hidden; }
canvas { display: block; }
</style>
</head>
<body>
<script>
// === Configuration ===
const CONFIG = {
seed: 42,
// ... project-specific params
};
// === Color Palette ===
const PALETTE = {
bg: '#0a0a0f',
primary: '#e8d5b7',
// ...
};
// === Global State ===
let particles = [];
// === Preload (fonts, images, data) ===
function preload() {
// font = loadFont('...');
}
// === Setup ===
function setup() {
createCanvas(1920, 1080);
randomSeed(CONFIG.seed);
noiseSeed(CONFIG.seed);
colorMode(HSB, 360, 100, 100, 100);
// Initialize state...
}
// === Draw Loop ===
function draw() {
// Render frame...
}
// === Helper Functions ===
// ...
// === Classes ===
class Particle {
// ...
}
// === Event Handlers ===
function mousePressed() { /* ... */ }
function keyPressed() { /* ... */ }
function windowResized() { resizeCanvas(windowWidth, windowHeight); }
</script>
</body>
</html>
```
关键实现模式：
- **种子随机性**：始终使用 `randomSeed()` + `noiseSeed()` 以确保可复现性
- **色彩模式**：使用 `colorMode(HSB, 360, 100, 100, 100)` 以获得直观的色彩控制
- **状态分离**：CONFIG 用于参数，PALETTE 用于颜色，全局变量用于可变状态
- **基于类的实体**：粒子、代理、形状作为具有 `update()` + `display()` 方法的类
- **离屏缓冲区**：`createGraphics()` 用于分层合成、轨迹、遮罩
### 第四步：预览与迭代
- 直接在浏览器中打开 HTML 文件——基本草图无需服务器
- 对于从本地文件加载 `loadImage()`/`loadFont()`：使用 `scripts/serve.sh` 或 `python3 -m http.server`
- 使用 Chrome DevTools 性能面板验证 60fps
- 在目标导出分辨率下测试，而不仅仅是窗口大小
- 调整参数直到视觉效果符合第一步的概念
### 第五步：导出
| 格式 | 方法 | 命令 |
|--------|--------|---------|
| **PNG** | 在 `keyPressed()` 中使用 `saveCanvas('output', 'png')` | 按 's' 保存 |
| **高分辨率 PNG** | Puppeteer 无头捕获 | `node scripts/export-frames.js sketch.html --width 3840 --height 2160 --frames 1` |
| **GIF** | `saveGif('output', 5)` — 捕获 N 秒 | 按 'g' 保存 |
| **帧序列** | `saveFrames('frame', 'png', 10, 30)` — 10 秒 30fps | 然后 `ffmpeg -i frame-%04d.png -c:v libx264 output.mp4` |
| **MP4** | Puppeteer 帧捕获 + ffmpeg | `bash scripts/render.sh sketch.html output.mp4 --duration 30 --fps 30` |
| **SVG** | 使用 p5.js-svg 的 `createCanvas(w, h, SVG)` | `save('output.svg')` |
### 第六步：质量验证
- **是否符合愿景？** 将输出与创意概念对比。如果看起来很普通，回到第一步
- **分辨率检查**：在目标显示尺寸下是否清晰？是否有锯齿伪影？
- **性能检查**：在浏览器中是否保持 60fps？（动画最低 30fps）
- **色彩检查**：颜色是否协调？在亮色和暗色显示器上都测试
- **边界情况**：canvas 边缘会发生什么？调整大小时？运行 10 分钟后？
## 关键实现注意事项
### 性能——首先禁用 FES
友好错误系统（FES）会增加高达 10 倍的开销。在每个生产草图中禁用它：
```javascript
p5.disableFriendlyErrors = true; // BEFORE setup()
function setup() {
pixelDensity(1); // prevent 2x-4x overdraw on retina
createCanvas(1920, 1080);
}
```
在热循环（粒子、像素操作）中，使用 `Math.*` 而非 p5 包装函数——速度明显更快：
```javascript
// In draw() or update() hot paths:
let a = Math.sin(t); // not sin(t)
let r = Math.sqrt(dx*dx+dy*dy); // not dist() — or better: skip sqrt, compare magSq
let v = Math.random(); // not random() — when seed not needed
let m = Math.min(a, b); // not min(a, b)
```
绝不在 `draw()` 内使用 `console.log()`。绝不在 `draw()` 中操作 DOM。参见 `references/troubleshooting.md` § Performance。
### 种子随机性——始终使用
每个生成草图必须可复现。相同种子，相同输出。
```javascript
function setup() {
randomSeed(CONFIG.seed);
noiseSeed(CONFIG.seed);
// All random() and noise() calls now deterministic
}
```
绝不对生成内容使用 `Math.random()`——仅用于性能关键的非视觉代码。视觉元素始终使用 `random()`。如果需要随机种子：`CONFIG.seed = floor(random(99999))`。
### 生成艺术平台支持（fxhash / Art Blocks）
对于生成艺术平台，用平台的确定性随机替换 p5 的 PRNG：
```javascript
// fxhash convention
const SEED = $fx.hash; // unique per mint
const rng = $fx.rand; // deterministic PRNG
$fx.features({ palette: 'warm', complexity: 'high' });
// In setup():
randomSeed(SEED); // for p5's noise()
noiseSeed(SEED);
// Replace random() with rng() for platform determinism
let x = rng() * width; // instead of random(width)
```
参见 `references/export-pipeline.md` § Platform Export。
### 色彩模式——使用 HSB
HSB（色相、饱和度、亮度）在生成艺术中比 RGB 更易于使用：
```javascript
colorMode(HSB, 360, 100, 100, 100);
// Now: fill(hue, sat, bri, alpha)
// Rotate hue: fill((baseHue + offset) % 360, 80, 90)
// Desaturate: fill(hue, sat * 0.3, bri)
// Darken: fill(hue, sat, bri * 0.5)
```
绝不硬编码原始 RGB 值。定义调色板对象，以程序化方式派生变体。参见 `references/color-systems.md`。
### 噪声——多倍频，而非原始噪声
原始 `noise(x, y)` 看起来像平滑的斑点。叠加倍频以获得自然纹理：
```javascript
function fbm(x, y, octaves = 4) {
let val = 0, amp = 1, freq = 1, sum = 0;
for (let i = 0; i < octaves; i++) {
val += noise(x * freq, y * freq) * amp;
sum += amp;
amp *= 0.5;
freq *= 2;
}
return val / sum;
}
```
对于流动的有机形态，使用**域扭曲**：将噪声输出作为噪声输入坐标反馈回去。参见 `references/visual-effects.md`。
### createGraphics() 分层——不可省略
单通道平面渲染看起来很平。使用离屏缓冲区进行合成：
```javascript
let bgLayer, fgLayer, trailLayer;
function setup() {
createCanvas(1920, 1080);
bgLayer = createGraphics(width, height);
fgLayer = createGraphics(width, height);
trailLayer = createGraphics(width, height);
}
function draw() {
renderBackground(bgLayer);
renderTrails(trailLayer); // persistent, fading
renderForeground(fgLayer); // cleared each frame
image(bgLayer, 0, 0);
image(trailLayer, 0, 0);
image(fgLayer, 0, 0);
}
```
### 性能——尽可能向量化
p5.js 绘制调用开销较大。对于数千个粒子：
```javascript
// SLOW: individual shapes
for (let p of particles) {
ellipse(p.x, p.y, p.size);
}
// FAST: single shape with beginShape()
beginShape(POINTS);
for (let p of particles) {
vertex(p.x, p.y);
}
endShape();
// FASTEST: pixel buffer for massive counts
loadPixels();
for (let p of particles) {
let idx = 4 * (floor(p.y) * width + floor(p.x));
pixels[idx] = r; pixels[idx+1] = g; pixels[idx+2] = b; pixels[idx+3] = 255;
}
updatePixels();
```
参见 `references/troubleshooting.md` § Performance。
### 多草图使用实例模式
全局模式会污染 `window`。生产环境中使用实例模式：
```javascript
const sketch = (p) => {
p.setup = function() {
p.createCanvas(800, 800);
};
p.draw = function() {
p.background(0);
p.ellipse(p.mouseX, p.mouseY, 50);
};
};
new p5(sketch, 'canvas-container');
```
在同一页面嵌入多个草图或与框架集成时必须使用。
### WebGL 模式注意事项
- `createCanvas(w, h, WEBGL)` — 原点在中心，而非左上角
- Y 轴反转（WEBGL 中正 Y 向上，P2D 中向下）
- 使用 `translate(-width/2, -height/2)` 获得类似 P2D 的坐标
- 每次变换前后都要使用 `push()`/`pop()` — 矩阵栈会静默溢出
- `texture()` 在 `rect()`/`plane()` 之前调用——而非之后
- 自定义着色器：`createShader(vert, frag)` — 在多个浏览器上测试
### 导出——按键绑定约定
每个草图的 `keyPressed()` 中都应包含以下内容：
```javascript
function keyPressed() {
if (key === 's' || key === 'S') saveCanvas('output', 'png');
if (key === 'g' || key === 'G') saveGif('output', 5);
if (key === 'r' || key === 'R') { randomSeed(millis()); noiseSeed(millis()); }
if (key === ' ') CONFIG.paused = !CONFIG.paused;
}
```
### 无头视频导出——使用 noLoop()
对于通过 Puppeteer 进行无头渲染，草图**必须**在 setup 中使用 `noLoop()`。否则，p5 的绘制循环会自由运行，而截图速度较慢——草图会超前运行，导致帧跳过或重复。
```javascript
function setup() {
createCanvas(1920, 1080);
pixelDensity(1);
noLoop(); // capture script controls frame advance
window._p5Ready = true; // signal readiness to capture script
}
```
内置的 `scripts/export-frames.js` 检测 `_p5Ready` 并在每次捕获时调用一次 `redraw()`，实现精确的 1:1 帧对应。参见 `references/export-pipeline.md` § Deterministic Capture。
对于多场景视频，使用每片段架构：每个场景一个 HTML，独立渲染，用 `ffmpeg -f concat` 拼接。参见 `references/export-pipeline.md` § Per-Clip Architecture。
### Agent 工作流程
构建 p5.js 草图时：
1. **编写 HTML 文件** — 单一自包含文件，所有代码内联
2. **在浏览器中打开** — macOS 用 `open sketch.html`，Linux 用 `xdg-open sketch.html`
3. **本地资源**（字体、图像）需要服务器：在项目目录中运行 `python3 -m http.server 8080`，然后打开 `http://localhost:8080/sketch.html`
4. **导出 PNG/GIF** — 如上所示添加 `keyPressed()` 快捷键，告知用户按哪个键
5. **无头导出** — `node scripts/export-frames.js sketch.html --frames 300` 用于自动化帧捕获（草图必须使用 `noLoop()` + `_p5Ready`）
6. **MP4 渲染** — `bash scripts/render.sh sketch.html output.mp4 --duration 30`
7. **迭代优化** — 编辑 HTML 文件，用户刷新浏览器查看变化
8. **按需加载参考资料** — 在实现过程中使用 `skill_view(name="p5js", file_path="references/...")` 加载特定参考文件
## 性能目标
| 指标 | 目标 |
|--------|--------|
| 帧率（交互式） | 持续 60fps |
| 帧率（动画导出） | 最低 30fps |
| 粒子数量（P2D 形状） | 60fps 下 5,000-10,000 |
| 粒子数量（像素缓冲区） | 60fps 下 50,000-100,000 |
| Canvas 分辨率 | 最高 3840x2160（导出），1920x1080（交互式） |
| 文件大小（HTML） | &lt; 100KB（不含 CDN 库） |
| 加载时间 | &lt; 2 秒到首帧 |
## 参考资料
| 文件 | 内容 |
|------|----------|
| `references/core-api.md` | Canvas 设置、坐标系、绘制循环、`push()`/`pop()`、离屏缓冲区、构图模式、`pixelDensity()`、响应式设计 |
| `references/shapes-and-geometry.md` | 2D 基元、`beginShape()`/`endShape()`、贝塞尔/Catmull-Rom 曲线、`vertex()` 系统、自定义形状、`p5.Vector`、有符号距离场、SVG 路径转换 |
| `references/visual-effects.md` | 噪声（Perlin、分形、域扭曲、curl）、流场、粒子系统（物理、群集、轨迹）、像素操作、纹理生成（点画、排线、半调）、反馈循环、反应扩散 |
| `references/animation.md` | 基于帧的动画、缓动函数、`lerp()`/`map()`、弹簧物理、状态机、时间轴排序、基于 `millis()` 的计时、过渡模式 |
| `references/typography.md` | `text()`、`loadFont()`、`textToPoints()`、动态排版、文字遮罩、字体度量、响应式文字大小 |
| `references/color-systems.md` | `colorMode()`、HSB/HSL/RGB、`lerpColor()`、`paletteLerp()`、程序化调色板、色彩和声、`blendMode()`、渐变渲染、精选调色板库 |
| `references/webgl-and-3d.md` | WEBGL 渲染器、3D 基元、摄像机、光照、材质、自定义几何体、GLSL 着色器（`createShader()`、`createFilterShader()`）、帧缓冲区、后处理 |
| `references/interaction.md` | 鼠标事件、键盘状态、触控输入、DOM 元素、`createSlider()`/`createButton()`、音频输入（p5.sound FFT/振幅）、滚动驱动动画、响应式事件 |
| `references/export-pipeline.md` | `saveCanvas()`、`saveGif()`、`saveFrames()`、确定性无头捕获、ffmpeg 帧转视频、CCapture.js、SVG 导出、每片段架构、平台导出（fxhash）、视频注意事项 |
| `references/troubleshooting.md` | 性能分析、每像素预算、常见错误、浏览器兼容性、WebGL 调试、字体加载问题、像素密度陷阱、内存泄漏、CORS |
| `templates/viewer.html` | 交互式查看器模板：种子导航（上一个/下一个/随机/跳转）、参数滑块、下载 PNG、响应式 canvas。可探索生成艺术从此开始 |
---
## 创意发散（仅在用户请求实验性/创意性/独特输出时使用）
如果用户要求创意性、实验性、令人惊喜或非常规的输出，在生成代码**之前**选择最合适的策略并推演其步骤。
- **概念混合** — 当用户命名两件要组合的事物或想要混合美学时
- **SCAMPER** — 当用户想要对已知生成艺术模式进行变体时
- **距离联想** — 当用户给出单一概念并想要探索时（"做一些关于时间的东西"）
### 概念混合
1. 命名两个不同的视觉系统（例如粒子物理 + 手写）
2. 映射对应关系（粒子 = 墨滴，力 = 笔压，场 = 字形）
3. 选择性混合——保留能产生有趣涌现视觉效果的映射
4. 将混合编码为统一系统，而非两个并排的系统
### SCAMPER 变换
取一个已知的生成模式（流场、粒子系统、L 系统、元胞自动机）并系统性地变换它：
- **替换（Substitute）**：用文字字符替换圆形，用渐变替换线条
- **组合（Combine）**：合并两种模式（流场 + Voronoi）
- **适配（Adapt）**：将 2D 模式应用于 3D 投影
- **修改（Modify）**：夸大比例，扭曲坐标空间
- **用途（Purpose）**：用物理模拟做排版，用排序算法做色彩
- **消除（Eliminate）**：去掉网格，去掉颜色，去掉对称性
- **反转（Reverse）**：反向运行模拟，反转参数空间
### 距离联想
1. 锚定用户的概念（例如"孤独"）
2. 在三个距离上生成联想：
- 近（显而易见）：空房间、单独的人物、寂静
- 中（有趣）：一条鱼在鱼群中逆向游动、没有通知的手机、地铁车厢之间的间隙
- 远（抽象）：质数、渐近曲线、凌晨三点的颜色
3. 发展中距离的联想——它们足够具体可以可视化，又足够出人意料而有趣
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-popular-web-designs.md
+211
View File
@@ -0,0 +1,211 @@
---
title: "流行网页设计 — 54 个真实设计系统（Stripe、Linear、Vercel）的 HTML/CSS"
sidebar_label: "流行网页设计"
description: "54 个真实设计系统（Stripe、Linear、Vercel）的 HTML/CSS"
---
{/* 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. */}
# 流行网页设计
54 个真实设计系统（Stripe、Linear、Vercel）的 HTML/CSS。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/popular-web-designs` |
| 版本 | `1.0.0` |
| 作者 | Hermes Agent + Teknium（设计系统来源：VoltAgent/awesome-design-md） |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# 流行网页设计
54 个可直接用于生成 HTML/CSS 的真实设计系统。每个模板都完整呈现了某个网站的视觉语言：色彩调色板、排版层级、组件样式、间距系统、阴影、响应式行为，以及包含精确 CSS 值的实用 agent prompt（提示词）。
## 相关设计 skill
- **`claude-design`** — 用于设计*流程与品味*（梳理需求、生成变体、验证本地 HTML 产物、避免 AI 设计陷阱）。当用户希望按照某个已知品牌风格设计页面时，可与本 skill 配合使用：`claude-design` 驱动工作流，本 skill 提供视觉词汇。
- **`design-md`** — 当交付物是正式的 DESIGN.md token（设计令牌）规范文件而非渲染产物时使用。
## 使用方法
1. 从下方目录中选择一个设计
2. 加载它：`skill_view(name="popular-web-designs", file_path="templates/<site>.md")`
3. 生成 HTML 时使用设计 token 和组件规范
4. 配合 `generative-widgets` skill，通过 cloudflared tunnel 提供服务
每个模板顶部都包含一个 **Hermes 实现说明** 块，内容包括：
- CDN 字体替代方案及 Google Fonts `<link>` 标签（可直接粘贴）
- 主字体和等宽字体的 CSS font-family 栈
- 提醒使用 `write_file` 创建 HTML 文件，使用 `browser_vision` 进行验证
## HTML 生成模式
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Page Title</title>
<!-- Paste the Google Fonts <link> from the template's Hermes notes -->
<link href="https://fonts.googleapis.com/css2?family=..." rel="stylesheet">
<style>
/* Apply the template's color palette as CSS custom properties */
:root {
--color-bg: #ffffff;
--color-text: #171717;
--color-accent: #533afd;
/* ... more from template Section 2 */
}
/* Apply typography from template Section 3 */
body {
font-family: 'Inter', system-ui, sans-serif;
color: var(--color-text);
background: var(--color-bg);
}
/* Apply component styles from template Section 4 */
/* Apply layout from template Section 5 */
/* Apply shadows from template Section 6 */
</style>
</head>
<body>
<!-- Build using component specs from the template -->
</body>
</html>
```
使用 `write_file` 写入文件，通过 `generative-widgets` 工作流（cloudflared tunnel）提供服务，并使用 `browser_vision` 验证结果以确认视觉准确性。
## 字体替代参考
大多数网站使用无法通过 CDN 获取的专有字体。每个模板都映射到一个 Google Fonts 替代字体，以保留设计的整体风格。常见映射关系：
| 专有字体 | CDN 替代字体 | 风格特征 |
|---|---|---|
| Geist / Geist Sans | Geist（Google Fonts 上可用） | 几何感，字距紧凑 |
| Geist Mono | Geist Mono（Google Fonts 上可用） | 简洁等宽，支持连字 |
| sohne-var (Stripe) | Source Sans 3 | 轻字重优雅感 |
| Berkeley Mono | JetBrains Mono | 技术感等宽字体 |
| Airbnb Cereal VF | DM Sans | 圆润、友好的几何风格 |
| Circular (Spotify) | DM Sans | 几何感，温暖 |
| figmaSans | Inter | 简洁人文主义风格 |
| Pin Sans (Pinterest) | DM Sans | 友好，圆润 |
| NVIDIA-EMEA | Inter（或 Arial 系统字体） | 工业感，简洁 |
| CoinbaseDisplay/Sans | DM Sans | 几何感，值得信赖 |
| UberMove | DM Sans | 粗犷，紧凑 |
| HashiCorp Sans | Inter | 企业级，中性 |
| waldenburgNormal (Sanity) | Space Grotesk | 几何感，略微压缩 |
| IBM Plex Sans/Mono | IBM Plex Sans/Mono | Google Fonts 上可用 |
| Rubik (Sentry) | Rubik | Google Fonts 上可用 |
当模板的 CDN 字体与原始字体一致时（Inter、IBM Plex、Rubik、Geist），不存在替代损失。当使用替代字体时（如用 DM Sans 替代 Circular，用 Source Sans 3 替代 sohne-var），请严格遵循模板中的字重、字号和字距值——这些参数承载的视觉识别度往往高于字体本身。
## 设计目录
### AI 与机器学习
| 模板 | 网站 | 风格 |
|---|---|---|
| `claude.md` | Anthropic Claude | 暖赤陶色强调色，简洁编辑排版 |
| `cohere.md` | Cohere | 鲜艳渐变，数据丰富的仪表盘美学 |
| `elevenlabs.md` | ElevenLabs | 暗色电影感 UI，音频波形美学 |
| `minimax.md` | Minimax | 带霓虹强调色的粗犷暗色界面 |
| `mistral.ai.md` | Mistral AI | 法式工程极简主义，紫色调 |
| `ollama.md` | Ollama | 终端优先，单色简约 |
| `opencode.ai.md` | OpenCode AI | 开发者向暗色主题，全等宽字体 |
| `replicate.md` | Replicate | 干净白色画布，代码优先 |
| `runwayml.md` | RunwayML | 电影感暗色 UI，媒体丰富布局 |
| `together.ai.md` | Together AI | 技术感，蓝图风格设计 |
| `voltagent.md` | VoltAgent | 纯黑画布，翠绿强调色，终端原生 |
| `x.ai.md` | xAI | 极简单色，未来主义，全等宽字体 |
### 开发者工具与平台
| 模板 | 网站 | 风格 |
|---|---|---|
| `cursor.md` | Cursor | 流畅暗色界面，渐变强调色 |
| `expo.md` | Expo | 暗色主题，紧凑字距，代码中心 |
| `linear.app.md` | Linear | 极简暗色模式，精准，紫色强调色 |
| `lovable.md` | Lovable | 活泼渐变，友好开发者美学 |
| `mintlify.md` | Mintlify | 简洁，绿色强调，阅读优化 |
| `posthog.md` | PostHog | 活泼品牌，开发者友好暗色 UI |
| `raycast.md` | Raycast | 流畅暗色外壳，鲜艳渐变强调色 |
| `resend.md` | Resend | 极简暗色主题，等宽字体强调 |
| `sentry.md` | Sentry | 暗色仪表盘，数据密集，粉紫强调色 |
| `supabase.md` | Supabase | 暗色翠绿主题，代码优先开发工具 |
| `superhuman.md` | Superhuman | 高端暗色 UI，键盘优先，紫色光晕 |
| `vercel.md` | Vercel | 黑白精准，Geist 字体系统 |
| `warp.md` | Warp | 暗色 IDE 风界面，块式命令 UI |
| `zapier.md` | Zapier | 暖橙色，友好插图驱动 |
### 基础设施与云
| 模板 | 网站 | 风格 |
|---|---|---|
| `clickhouse.md` | ClickHouse | 黄色强调，技术文档风格 |
| `composio.md` | Composio | 现代暗色，彩色集成图标 |
| `hashicorp.md` | HashiCorp | 企业级简洁，黑白配色 |
| `mongodb.md` | MongoDB | 绿叶品牌，开发者文档焦点 |
| `sanity.md` | Sanity | 红色强调，内容优先编辑布局 |
| `stripe.md` | Stripe | 标志性紫色渐变，300 字重优雅感 |
### 设计与生产力
| 模板 | 网站 | 风格 |
|---|---|---|
| `airtable.md` | Airtable | 多彩，友好，结构化数据美学 |
| `cal.md` | Cal.com | 简洁中性 UI，开发者向简约 |
| `clay.md` | Clay | 有机形状，柔和渐变，艺术指导布局 |
| `figma.md` | Figma | 鲜艳多色，活泼而专业 |
| `framer.md` | Framer | 粗犷黑蓝，动效优先，设计前沿 |
| `intercom.md` | Intercom | 友好蓝色调，对话式 UI 模式 |
| `miro.md` | Miro | 亮黄强调色，无限画布美学 |
| `notion.md` | Notion | 温暖极简，衬线标题，柔和表面 |
| `pinterest.md` | Pinterest | 红色强调，瀑布流网格，图片优先布局 |
| `webflow.md` | Webflow | 蓝色强调，精致营销站美学 |
### 金融科技与加密货币
| 模板 | 网站 | 风格 |
|---|---|---|
| `coinbase.md` | Coinbase | 简洁蓝色标识，信任导向，机构感 |
| `kraken.md` | Kraken | 紫色强调暗色 UI，数据密集仪表盘 |
| `revolut.md` | Revolut | 流畅暗色界面，渐变卡片，金融科技精准感 |
| `wise.md` | Wise | 亮绿强调色，友好清晰 |
### 企业与消费者
| 模板 | 网站 | 风格 |
|---|---|---|
| `airbnb.md` | Airbnb | 暖珊瑚强调色，摄影驱动，圆润 UI |
| `apple.md` | Apple | 高端留白，SF Pro，电影感图像 |
| `bmw.md` | BMW | 暗色高端表面，精准工程美学 |
| `ibm.md` | IBM | Carbon 设计系统，结构化蓝色调色板 |
| `nvidia.md` | NVIDIA | 绿黑能量感，技术力量美学 |
| `spacex.md` | SpaceX | 极简黑白，全出血图像，未来主义 |
| `spotify.md` | Spotify | 暗底鲜绿，粗犷字体，专辑封面驱动 |
| `uber.md` | Uber | 粗犷黑白，紧凑字体，都市能量 |
## 选择设计
根据内容匹配设计：
- **开发者工具 / 仪表盘：** Linear、Vercel、Supabase、Raycast、Sentry
- **文档 / 内容站点：** Mintlify、Notion、Sanity、MongoDB
- **营销 / 落地页：** Stripe、Framer、Apple、SpaceX
- **暗色模式 UI：** Linear、Cursor、ElevenLabs、Warp、Superhuman
- **浅色 / 简洁 UI：** Vercel、Stripe、Notion、Cal.com、Replicate
- **活泼 / 友好：** PostHog、Figma、Lovable、Zapier、Miro
- **高端 / 奢华：** Apple、BMW、Stripe、Superhuman、Revolut
- **数据密集 / 仪表盘：** Sentry、Kraken、Cohere、ClickHouse
- **等宽 / 终端美学：** Ollama、OpenCode、x.ai、VoltAgent
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-pretext.md
+238
View File
@@ -0,0 +1,238 @@
---
title: "Pretext"
sidebar_label: "Pretext"
description: "适用于使用 @chenglou/pretext 构建创意浏览器演示 —— 无 DOM 文本布局，用于 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. */}
# Pretext
适用于使用 @chenglou/pretext 构建创意浏览器演示 —— 无 DOM 文本布局，用于 ASCII 艺术、排版绕障流动、文字即几何游戏、动态排版及文字驱动的生成艺术。默认生成单文件 HTML 演示。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/pretext` |
| 版本 | `1.0.0` |
| 作者 | Hermes Agent |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `creative-coding`, `typography`, `pretext`, `ascii-art`, `canvas`, `generative`, `text-layout`, `kinetic-typography` |
| 相关 skill | [`p5js`](/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# Pretext 创意演示
## 概述
[`@chenglou/pretext`](https://github.com/chenglou/pretext) 是由 Cheng Lou（React 核心团队、ReasonML、Midjourney）开发的 15KB 零依赖 TypeScript 库，用于**无 DOM 多行文本测量与布局**。它只做一件事：给定 `(text, font, width)`，返回换行位置、每行宽度、每个字形（grapheme）的坐标以及总高度 —— 全部通过 canvas 测量完成，无需触发重排（reflow）。
听起来像底层管道，但并非如此。由于它快速且几何化，它是一个**创意原语**：你可以在 60fps 下让段落绕着移动的精灵重排，构建关卡几何体由真实文字组成的游戏，将 ASCII logo 嵌入散文，利用精确的每字形起始坐标将文字炸裂成粒子，或者在不调用任何 `getBoundingClientRect` 的情况下打包紧凑的多行 UI。
此 skill 的存在是为了让 Hermes 能用它制作**酷炫演示** —— 那种人们会发到 X 上的作品。社区演示库请见 `pretext.cool` 和 `chenglou.me/pretext`。
## 使用时机
当用户要求以下内容时使用：
- "pretext 演示" / "酷炫的 pretext 作品" / "文字即 X"
- 文字绕移动形状流动（hero 区块、编辑排版、动态长文页面）
- 使用**真实文字或散文**（而非等宽字符光栅）的 ASCII 艺术效果
- 游戏场地 / 障碍物 / 砖块由文字构成的游戏（字母版俄罗斯方块、散文版打砖块）
- 带有每字形物理效果的动态排版（碎裂、散射、群集、流动）
- 排版生成艺术，尤其是非拉丁文字或混合文字
- 多行"紧缩包裹"UI（能容纳文字的最小容器宽度）
- 任何需要在渲染**前**知道换行位置的场景
不适用于：
- CSS 已能解决布局的静态 SVG/HTML 页面 —— 直接用 CSS
- 富文本编辑器、通用内联格式化引擎（pretext 有意保持功能单一）
- 图片转文字（使用 `ascii-art` / `ascii-video` skill）
- 文字不起核心作用的纯 canvas 生成艺术 —— 使用 `p5js`
## 创意标准
这是在浏览器中渲染的视觉艺术。Pretext 返回数字；**你**来绘制内容。
- **不要交付"hello world"演示。** `hello-orb-flow.html` 模板只是*起点*。每个交付的演示都必须加入有意为之的色彩、动效、构图，以及一个用户没有要求但会欣赏的视觉细节。
- **深色背景、暖色核心、精心调配的色板。** 经典的琥珀色配黑色（CRT / 终端风）可行，冷白配炭灰（编辑风）和去饱和粉彩（risograph 风）同样可行。选定一种并坚持到底。
- **比例字体才是重点。** Pretext 的核心魅力在于"非等宽" —— 充分利用这一点。使用 Iowan Old Style、Inter、JetBrains Mono、Helvetica Neue 或可变字体。绝不使用默认无衬线字体。
- **使用真实语料，而非 lorem ipsum。** 语料库应有意义。短篇宣言、诗歌、真实源代码、发现的文本、库自身的 README —— 绝不用 `lorem ipsum`。
- **首帧即精品。** 无加载状态，无空白帧。演示打开的瞬间就必须达到可发布水准。
## 技术栈
每个演示为单个自包含 HTML 文件，无需构建步骤。
| 层级 | 工具 | 用途 |
|-------|------|---------|
| 核心 | `@chenglou/pretext`（通过 `esm.sh` CDN） | 文本测量 + 行布局 |
| 渲染 | HTML5 Canvas 2D | 字形渲染、逐帧合成 |
| 分割 | `Intl.Segmenter`（内置） | emoji / CJK / 组合字符的字形拆分 |
| 交互 | 原生 DOM 事件 | 鼠标 / 触摸 / 滚轮 —— 无框架 |
```html
<script type="module">
import {
prepare, layout, // use-case 1: simple height
prepareWithSegments, layoutWithLines, // use-case 2a: fixed-width lines
layoutNextLineRange, materializeLineRange, // use-case 2b: streaming / variable width
measureLineStats, walkLineRanges, // stats without string allocation
} from "https://esm.sh/@chenglou/pretext@0.0.6";
</script>
```
锁定版本。撰写时为 `@0.0.6` —— 如演示行为异常，请在 [npm](https://www.npmjs.com/package/@chenglou/pretext) 查看最新版本。
## 两种使用场景
几乎所有需求都归结为以下两种形态之一。两种都要掌握。
### 场景 1 —— 测量，然后用 CSS/DOM 渲染
```js
const prepared = prepare(text, "16px Inter");
const { height, lineCount } = layout(prepared, 320, 20);
```
浏览器仍负责绘制文字。Pretext 只告诉你在给定宽度下文本框的高度，**无需**读取 DOM。适用于：
- 包含换行文字的虚拟列表行高计算
- 需要精确卡片高度的瀑布流布局
- "这个标签放得下吗？"的开发时检查
- 防止远程文字加载时的布局偏移
**保持 `font` 和 `letterSpacing` 与 CSS 完全同步。** canvas 的 `ctx.font` 格式（如 `"16px Inter"`、`"500 17px 'JetBrains Mono'"`）必须与渲染 CSS 一致，否则测量结果会产生偏差。
### 场景 2 —— 自行测量*并*渲染
```js
const prepared = prepareWithSegments(text, FONT);
const { lines } = layoutWithLines(prepared, 320, 26);
for (let i = 0; i < lines.length; i++) {
ctx.fillText(lines[i].text, 0, i * 26);
}
```
创意工作就在这里。你掌控绘制，因此可以：
- 渲染到 canvas、SVG、WebGL 或任意坐标系
- 对每个字形应用变换（旋转、抖动、缩放、透明度）
- 将行元数据（宽度、字形坐标）用作几何数据
对于**每行宽度可变**的流动排版（文字绕形状流动、文字在环形带内、文字在非矩形列中）：
```js
let cursor = { segmentIndex: 0, graphemeIndex: 0 };
let y = 0;
while (true) {
const lineWidth = widthAtY(y); // your function: how wide is the corridor at this y?
const range = layoutNextLineRange(prepared, cursor, lineWidth);
if (!range) break;
const line = materializeLineRange(prepared, range);
ctx.fillText(line.text, leftEdgeAtY(y), y);
cursor = range.end;
y += lineHeight;
}
```
这是整个库中最重要的模式。它解锁了"文字绕拖拽精灵流动"的效果 —— 那个在 X 上病毒式传播的演示。
### 值得了解的辅助函数
- `measureLineStats(prepared, maxWidth)` → `{ lineCount, maxLineWidth }` —— 最宽的行，即多行紧缩包裹宽度。
- `walkLineRanges(prepared, maxWidth, callback)` —— 无字符串分配地遍历各行。在不需要字符内容时用于统计/物理计算。
- `@chenglou/pretext/rich-inline` —— 同一系统，但支持混合字体 / 标签 / 提及的段落。从子路径导入。
## 演示配方模式
社区语料库（见 `references/patterns.md`）归纳为几种强力模式。选一种进行变奏 —— 除非被要求，否则不要发明新类别。
| 模式 | 核心 API | 示例创意 |
|---|---|---|
| **绕障重排** | `layoutNextLineRange` + 逐行宽度函数 | 编辑排版段落，绕拖拽光标精灵分开 |
| **文字即几何游戏** | `layoutWithLines` + 逐行碰撞矩形 | 每块砖都是一个测量过的单词的打砖块游戏 |
| **碎裂 / 粒子** | `walkLineRanges` → 每字形 (x,y) → 物理 | 点击时句子炸裂成字母 |
| **ASCII 障碍排版** | `layoutNextLineRange` + 逐行障碍区间测量 | 位图 ASCII logo、形态变换，以及可拖拽的线框物体，使文字绕其实际几何形状展开 |
| **编辑多栏** | 每栏 `layoutNextLineRange` + 共享游标 | 带引用块的动态杂志版面 |
| **动态排版** | `layoutWithLines` + 逐行随时间变换 | 星球大战字幕滚动、波浪、弹跳、故障效果 |
| **多行紧缩包裹** | `measureLineStats` | 自动适配最紧凑容器的引用卡片 |
可参考 `templates/donut-orbit.html` 和 `templates/hello-orb-flow.html` 中可运行的单文件起始模板。
## 工作流程
1. **根据用户需求从上表选择一种模式。**
2. **从模板开始**：
- `templates/hello-orb-flow.html` —— 文字绕移动球体重排（绕障重排模式）
- `templates/donut-orbit.html` —— 进阶示例：测量 ASCII logo 障碍物、可拖拽线框球体/立方体、变形形状场、可选 DOM 文字及仅开发模式控件
- 用 `write_file` 将新 `.html` 写入 `/tmp/` 或用户工作区。
3. **将语料库替换为**与需求相关的有意义内容。真实散文，10-100 句，不用 lorem。
4. **调整美学** —— 字体、色板、构图、交互。这才是核心工作，不要跳过。
5. **本地验证**：
```sh
cd <dir-with-html> && python3 -m http.server 8765
# then open http://localhost:8765/<file>.html
```
6. **检查控制台** —— 若 `prepareWithSegments` 传入错误的字体字符串，pretext 会抛出异常；`Intl.Segmenter` 在所有现代浏览器中均可用。
7. **向用户展示文件路径**，而非仅展示代码 —— 他们想直接打开文件。
## 性能说明
- `prepare()` / `prepareWithSegments()` 是开销较大的调用。每个文字+字体组合只调用**一次**，缓存句柄。
- 窗口大小改变时，只重新运行 `layout()` / `layoutWithLines()` —— 绝不重新 prepare。
- 对于文字内容不变但几何形状变化的逐帧动画，在紧密循环中调用 `layoutNextLineRange` 对普通长度的段落来说足够在 60fps 下每帧执行。
- 逐帧渲染 ASCII 遮罩时，维护一个单元格缓冲区（`Uint8Array` / 类型化数组），从单元格或投影几何体推导每行障碍区间，合并区间，再将这些区间传入 `layoutNextLineRange` 后绘制文字。
- 保持视觉动画与布局动画同步。若球体变形为立方体，用同一个值对渲染单元格缓冲区和障碍区间同时做补间；否则演示看起来像贴图而非物理重排。
- 淡入淡出效果优先使用图层透明度，而非改变字形强度或障碍物缩放。将瞬态 ASCII 精灵放在独立 canvas 上，用 CSS/GSAP 的 opacity 淡化该 canvas，避免几何形状看起来在缩小。
- Canvas 的 `ctx.font` 设置出人意料地慢；若字体在帧内不变，每帧只设置**一次**，而非每次 `fillText` 调用都设置。
## 常见陷阱
1. **CSS 与 canvas 字体字符串不一致。** `ctx.font = "16px Inter"` 用于测量，但 CSS 写的是 `font-family: Inter, sans-serif; font-size: 16px`。如果 Inter 加载成功则没问题。若 Inter 404，CSS 会回退到 sans-serif，测量结果偏差 5-20%。始终 `preload` 字体，或使用 web 安全字体族。
2. **在动画循环内重复 prepare。** 只有 `layout*` 是廉价的。每帧调用 `prepare` 会严重拖慢性能。将 prepared 句柄保存在模块作用域中。
3. **忘记用 `Intl.Segmenter` 拆分字形。** Emoji、组合字符、CJK —— `"é".split("")` 会给出两个字符。在采样单个可见字形时，使用 `new Intl.Segmenter(undefined, { granularity: "grapheme" })`。
4. **`break: 'never'` 标签缺少 `extraWidth`。** 在 `rich-inline` 中，若对原子标签/提及使用 `break: 'never'`，还必须提供 `extraWidth` 用于标签内边距 —— 否则标签外框会溢出容器。
5. **从 `unpkg` 使用 `@chenglou/pretext` 时遇到 TypeScript 专属入口。** 使用 `esm.sh` —— 它会自动将 TS 导出编译为浏览器可用的 ESM。`unpkg` 会 404 或返回原始 TS。
6. **等宽字体回退悄悄抹杀了整个意义。** 用户看到等宽输出，通常是因为 CSS `font-family` 回退到了 `monospace`。通过 DevTools 验证实际渲染字体。
7. **绕形状流动时跳过行而非调整宽度。** 若当前行的通道太窄无法容纳一行，应*跳过该行*（`y += lineHeight; continue;`），而非向 `layoutNextLineRange` 传入极小的 maxWidth —— pretext 会返回单字形行，看起来很破碎。
8. **交付冷启动演示。** 默认首帧看起来像教程级别。请添加：暗角、细微扫描线、空闲自动动效、一个精心选择的交互响应（拖拽、悬停、滚动、点击）。缺少这些，"酷炫 pretext 演示"就会沦为"README 复现"。
## 验证清单
- [ ] 演示是单个自包含 `.html` 文件 —— 双击或 `python3 -m http.server` 即可打开
- [ ] `@chenglou/pretext` 通过 `esm.sh` 导入并锁定版本
- [ ] 语料库为真实散文，非 lorem ipsum，且与演示概念匹配
- [ ] 传入 `prepare` 的字体字符串与 CSS 字体完全一致
- [ ] `prepare()` / `prepareWithSegments()` 只调用一次，不在每帧调用
- [ ] 深色背景 + 精心调配的色板 —— 非默认白色 canvas
- [ ] 至少一种交互响应（拖拽 / 悬停 / 滚动 / 点击）或空闲自动动效
- [ ] 已用 `python3 -m http.server` 本地测试，确认无控制台报错
- [ ] 在中端笔记本上达到 60fps（或已记录优雅降级方案）
- [ ] 一个用户未要求的"超额"细节
## 参考：社区演示
克隆以下项目获取灵感 / 模式（均为 MIT 类许可，链接来自 [pretext.cool](https://www.pretext.cool/)）：
- **Pretext Breaker** —— 单词砖块打砖块 —— `github.com/rinesh/pretext-breaker`
- **Tetris × Pretext** —— `github.com/shinichimochizuki/tetris-pretext`
- **Dragon animation** —— `github.com/qtakmalay/PreTextExperiments`
- **Somnai editorial engine** —— `github.com/somnai-dreams/pretext-demos`
- **Bad Apple!! ASCII** —— `github.com/frmlinn/bad-apple-pretext`
- **Drag-sprite reflow** —— `github.com/dokobot/pretext-demo`
- **Alarmy editorial clock** —— `github.com/SmisLee/alarmy-pretext-demo`
官方演示场：[chenglou.me/pretext](https://chenglou.me/pretext/) —— 手风琴、气泡、动态布局、编辑引擎、对齐比较、瀑布流、Markdown 聊天、富文本笔记。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-sketch.md
+238
View File
@@ -0,0 +1,238 @@
---
title: "Sketch — 一次性 HTML 原型：2-3 个设计方案对比"
sidebar_label: "Sketch"
description: "一次性 HTML 原型：2-3 个设计方案对比"
---
{/* 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. */}
# Sketch
一次性 HTML 原型：2-3 个设计方案对比。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/sketch` |
| 版本 | `1.0.0` |
| 作者 | Hermes Agent（改编自 gsd-build/get-shit-done） |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `sketch`, `mockup`, `design`, `ui`, `prototype`, `html`, `variants`, `exploration`, `wireframe`, `comparison` |
| 相关 skill | [`spike`](/user-guide/skills/bundled/software-development/software-development-spike), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# Sketch
当用户希望**在确定方向之前先看到设计效果**时使用此 skill——以一次性 HTML 原型的形式探索 UI/UX 想法。目的是生成 2-3 个可交互的方案，让用户并排对比视觉方向，而非产出可交付的代码。
当用户说以下内容时加载此 skill："sketch this screen"、"show me what X could look like"、"compare layout A vs B"、"give me 2-3 takes on this UI"、"let me see some variants"、"mockup this before I build"。
## 不适用场景
- 用户需要生产级组件——使用 `claude-design` 或正式构建
- 用户需要精良的一次性 HTML 产物（落地页、幻灯片）——使用 `claude-design`
- 用户需要图表——使用 `excalidraw`、`architecture-diagram`
- 设计已确定——直接构建即可
## 如果用户安装了完整的 GSD 系统
如果 `gsd-sketch` 作为同级 skill 出现（通过 `npx get-shit-done-cc --hermes` 安装），优先使用 **`gsd-sketch`** 以获得完整工作流：持久化的 `.planning/sketches/` 目录（含 MANIFEST）、前沿模式分析、跨历史草图的一致性审计，以及与 GSD 其余部分的集成。本 skill 是轻量级独立版本——无状态机制的一次性草图。
## 核心方法
```
intake → variants → head-to-head → pick winner (or iterate)
```
### 1. Intake（如果用户已提供足够信息则跳过）
在生成方案之前，获取三项信息——每次只问一个问题，不要一次全问：
1. **感觉。** "这个应该给人什么感觉？形容词、情绪、氛围。"——*"calm, editorial, like Linear"* 比 *"minimal"* 更有参考价值。
2. **参考。** "哪些 app、网站或产品接近你想象中的感觉？"——实际参考比抽象描述更有效。
3. **核心操作。** "用户在这个页面上最重要的单一操作是什么？"——所有方案都应服务于此；否则只是装饰。
每次回答后简短复述，再问下一个问题。如果用户已一次性提供了全部三项，直接跳到方案生成。
### 2. 方案（2-3 个，不少于 1 个，极少超过 4 个）
一次性生成 **2-3 个方案**。每个方案是一个完整的独立 HTML 文件。不要描述方案——直接构建。目的是对比。
每个方案应采取**不同的设计立场**，而非不同的像素值。三种有效的方案维度：
- **密度：** 紧凑 / 宽松 / 极密（选两个对比极端）
- **重点：** 内容优先 / 操作优先 / 工具优先
- **美学：** 编辑风格 / 实用主义 / 趣味性
- **布局：** 单列 / 侧边栏 / 分屏
- **基调：** 卡片式 / 纯内容 / 文档风格
选定一个维度并从中拉开差距。两个仅在强调色上不同的方案是无效的——用户无法区分。
**方案命名：** 描述立场，而非编号。
<!-- ascii-guard-ignore -->
```
sketches/
├── 001-calm-editorial/
│ ├── index.html
│ └── README.md
├── 001-utilitarian-dense/
│ ├── index.html
│ └── README.md
└── 001-playful-split/
├── index.html
└── README.md
```
<!-- ascii-guard-ignore-end -->
### 3. 制作真实的 HTML
每个方案是一个**单一自包含的 HTML 文件**：
- 内联 `<style>`——无需构建步骤，无外部 CSS
- 系统字体或通过 `<link>` 引入一个 Google Font
- 通过 CDN 使用 Tailwind（`<script src="https://cdn.tailwindcss.com"></script>`）可以
- 真实的虚假内容——实际句子、实际姓名，而非"Lorem ipsum"
- **可交互**：链接可点击，悬停效果真实，至少一个状态转换（展开/收起、筛选、切换）。一个冻结的静态图比一个粗糙但有动效的方案更差。
在浏览器中打开验证。如果看起来有问题，在展示给用户之前修复。
**使用 Hermes 的浏览器工具对方案进行视觉验证。** 不要只写 HTML 然后寄希望于它能正常渲染；加载每个方案并查看：
```
browser_navigate(url="file:///absolute/path/to/sketches/001-calm-editorial/index.html")
browser_vision(question="Does this layout look clean and readable? Any visible bugs (overlapping text, unstyled elements, broken images)?")
```
`browser_vision` 返回页面实际内容的 AI 描述及截图路径——能捕获纯源码检查遗漏的布局问题（例如字体导入静默失败、flex 容器塌陷）。修复后重新导航，直到每个方案看起来正确为止。
**快速启动用的默认 CSS reset + 系统字体栈：**
```html
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
"Helvetica Neue", Arial, sans-serif;
-webkit-font-smoothing: antialiased;
color: #1a1a1a;
background: #fafafa;
line-height: 1.5;
}
</style>
```
### 4. 方案 README
每个方案的 `README.md` 回答以下内容：
```markdown
## Variant: {stance name}
### Design stance
One sentence on the principle driving this variant.
### Key choices
- Layout: ...
- Typography: ...
- Color: ...
- Interaction: ...
### Trade-offs
- Strong at: ...
- Weak at: ...
### Best for
- The kind of user or use case this variant actually serves
```
### 5. 正面对比
所有方案构建完成后，以对比形式呈现。不要只是罗列——**给出观点**：
```markdown
## Three takes on the home screen
| Dimension | Calm editorial | Utilitarian dense | Playful split |
|-----------|----------------|-------------------|---------------|
| Density | Low | High | Medium |
| Primary action visibility | Low | High | Medium |
| Scan-ability | High | Medium | Low |
| Feel | Calm, trusted | Sharp, tool-like | Inviting, energetic |
**My take:** Utilitarian dense for power users, calm editorial for content-forward audiences. Playful split is weakest — tries to do both and commits to neither.
```
让用户选出胜出方案，或将两个方案合并为混合版，或要求新一轮迭代。
## 主题化（当项目有视觉标识时）
如果用户有现有主题（颜色、字体、token），将共享 token 放入 `sketches/themes/tokens.css` 并在每个方案中 `@import`。保持 token 精简：
```css
/* sketches/themes/tokens.css */
:root {
--color-bg: #fafafa;
--color-fg: #1a1a1a;
--color-accent: #0066ff;
--color-muted: #666;
--radius: 8px;
--font-display: "Inter", sans-serif;
--font-body: -apple-system, BlinkMacSystemFont, sans-serif;
}
```
不要对一次性草图过度 token 化——三种颜色加一种字体通常已足够。
## 交互基准
当用户能够完成以下操作时，草图的交互程度即为合格：
1. **点击主要操作**并看到可见的变化（状态变更、模态框、toast、导航模拟）
2. **看到一个有意义的状态转换**（筛选列表、切换模式、展开/收起面板）
3. **悬停可识别的交互元素**（按钮、行、标签页）
超过此程度是对一次性草图的过度工程化。低于此程度则只是截图。
## 前沿模式（决定下一步草图内容）
如果草图已存在且用户询问"接下来应该草图什么？"：
- **一致性缺口**——来自不同草图的两个胜出方案做出了独立选择，尚未组合在一起
- **未草图的页面**——被引用但从未探索过
- **状态覆盖**——已草图了正常路径，但未覆盖空状态 / 加载中 / 错误 / 千条数据
- **响应式缺口**——在某一视口下验证过；在移动端 / 超宽屏下是否成立？
- **交互模式**——静态布局已存在；过渡动效、拖拽、滚动行为尚未探索
提出 2-4 个命名候选项，让用户选择。
## 输出
- 在仓库根目录创建 `sketches/`（如果用户使用 GSD 约定则为 `.planning/sketches/`）
- 每个方案一个子目录：`NNN-stance-name/index.html` + `README.md`
- 告知用户如何打开：macOS 上用 `open sketches/001-calm-editorial/index.html`，Linux 上用 `xdg-open`，Windows 上用 `start`
- 保持方案的一次性特性——如果你觉得有必要保留某个草图，应将其提升为真实项目代码，而非作为资产保管
**单个方案的典型工具调用序列：**
```
terminal("mkdir -p sketches/001-calm-editorial")
write_file("sketches/001-calm-editorial/index.html", "<!doctype html>...")
write_file("sketches/001-calm-editorial/README.md", "## Variant: Calm editorial\n...")
browser_navigate(url="file://$(pwd)/sketches/001-calm-editorial/index.html")
browser_vision(question="How does this look? Any obvious layout issues?")
```
对每个方案重复上述步骤，然后呈现对比表格。
## 致谢
改编自 GSD（Get Shit Done）项目的 `/gsd-sketch` 工作流——MIT © 2025 Lex Christopherson（[gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)）。完整 GSD 系统提供持久化草图状态、主题/方案模式参考及一致性审计工作流；通过 `npx get-shit-done-cc --hermes --global` 安装。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md
+289
View File
@@ -0,0 +1,289 @@
---
title: "Songwriting And Ai Music — 歌词创作与 Suno AI 音乐提示词"
sidebar_label: "Songwriting And Ai Music"
description: "歌词创作与 Suno AI 音乐提示词"
---
{/* 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. */}
# Songwriting And Ai Music
歌词创作与 Suno AI 音乐提示词（prompt）。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/songwriting-and-ai-music` |
| 平台 | linux, macos, windows |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# 歌词创作与 AI 音乐生成
这里的一切都是**指导原则**，不是规则。艺术本就是为了打破规则。
用对歌曲有用的，忽略没用的。
---
## 1. 歌曲结构（选一种或自创）
常见骨架——可以混用、修改或直接丢弃：
```
ABABCB 主歌/副歌/主歌/副歌/桥段/副歌 （大多数流行/摇滚）
AABA 主歌/主歌/桥段/主歌（基于叠句） （爵士标准曲、抒情曲）
ABAB 主歌/副歌交替 （简洁直接）
AAA 主歌/主歌/主歌（分节歌，无副歌） （民谣、叙事曲）
```
六个基本构件：
- Intro（前奏） — 营造氛围，吸引听众进入
- Verse（主歌） — 故事、细节、世界构建
- Pre-Chorus（预副歌） — 可选的张力铺垫，在高潮前蓄力
- Chorus（副歌） — 情感核心，让人记住的部分
- Bridge（桥段） — 转折，视角或调性的转变
- Outro（尾奏） — 告别，可以呼应或颠覆前面的内容
你不需要全部用上。有些伟大的歌曲只有一个段落在演变。
结构服务于情感，而不是反过来。
---
## 2. 押韵、韵律与音效
押韵类型（从紧到松）：
- 完全押韵：lean/mean
- 同族押韵：crate/braid
- 元音押韵（Assonance）：had/glass（相同元音，不同结尾）
- 辅音押韵（Consonance）：scene/when（不同元音，相似结尾）
- 近似/斜韵（Near/slant）：足以暗示关联，但不锁死
混合使用。全用完全押韵会像儿歌。全用斜韵会显得懒散。两者的融合才是关键。
内部押韵（INTERNAL RHYME）：在一行内部押韵，而不只是行尾。
"We pruned the lies from bleeding trees / Distilled the storm
from entropy" — "lies/flies"、"trees/entropy" 形成内部回响。
韵律（METER）：重读与非重读音节的节奏。
- 平行行之间匹配音节数有助于可唱性
- **重读**音节比总数更重要
- 大声朗读。如果你绊嘴，韵律需要调整。
- 刻意打破韵律可以制造强调或惊喜
---
## 3. 情感弧线与动态
把一首歌想象成一段旅程，而不是一条平路。
能量映射（粗略参考，非规定）：
前奏：2-3 | 主歌：5-6 | 预副歌：7
副歌：8-9 | 桥段：不定 | 最终副歌：9-10
最强大的动态技巧：**对比**。
- 低语之后的嘶吼比一直嘶吼更有冲击力
- 稀疏之后才有密集。缓慢之后才有急速。低沉之后才有高亢。
- 爆发只因为有铺垫才有效
- 沉默也是一种乐器
"低语→咆哮→低语"——从亲密开始，推向全力，再剥离回脆弱。
适用于抒情曲、史诗曲、颂歌。
---
## 4. 写出有效的歌词
**展示，而非陈述**（通常如此）：
- "我很悲伤" = 平淡
- "你的帽衫还挂在门边的钩子上" = 有生命力
- 但有时"我献出我的生命"直白说出来**就是**力量所在
**Hook（钩子）**：
- 让人记住、哼唱、反复回味的那句话
- 通常是标题或核心短语
- 当旋律 + 歌词 + 情感三者对齐时效果最佳
- 放在最有冲击力的位置（通常是副歌的第一行或最后一行）
**韵律配合（Prosody）**——歌词与音乐相互支撑：
- 稳定的情感（解脱、平静）配以稳定的旋律、完全押韵、解决和弦
- 不稳定的情感（渴望、怀疑）配以游移的旋律、近似押韵、未解决和弦
- 主歌旋律通常较低，副歌走高
- 但如果对歌曲有利，可以反过来
**避免**（除非你是故意的）：
- 惯性使用陈词滥调（"黄金之心"，没有赋予它新意）
- 为了押韵而扭曲词序（"Yoda 式说话"）
- 每个段落能量相同（动态平淡）
- 把初稿当作神圣不可改——修改就是创作
---
## 5. 戏仿与改编
用新歌词改写现有歌曲时：
**骨架分析**：先绘制原曲结构。
- 数每行音节数
- 标注押韵方案（ABAB、AABB 等）
- 识别哪些音节是**重读**的
- 注意哪里有延长/持续音
**填入新词**：
- 将重读音节与原曲相同拍点对齐
- 总音节数可以在非重读音节上浮动 1-2 个
- 在长延音处，尽量匹配原曲的**元音音色**
（如果原曲延音是"LOOOVE"的"oo"元音，"FOOOD"比"LIFE"更合适）
- 在关键位置用单音节词替换可保持节奏完整
（Crime -> Code，Snake -> Noose）
- 把新词唱到原曲上——如果你绊嘴，就修改
**概念**：
- 选一个足够强大、能撑起整首歌的概念
- 从标题/hook 出发，向外构建
- 先大量生成原材料（双关语、短语、意象），再把最好的填入结构
- 如果某处需要特定的一行，从押韵方案反向推导来铺垫它
**保留部分原词**：保留几行原词或原有结构，增加辨识度，让听众感受到与原曲的联系。
---
## 6. Suno AI Prompt 工程
### 风格/流派描述字段
公式（按需调整）：
流派 + 情绪 + 年代 + 乐器 + 人声风格 + 制作风格 + 动态
```
差： "sad rock song"
好： "Cinematic orchestral spy thriller, 1960s Cold War era, smoky
sultry female vocalist, big band jazz, brass section with
trumpets and french horns, sweeping strings, minor key,
vintage analog warmth"
```
**描述旅程**，而不只是流派：
```
"Begins as a haunting whisper over sparse piano. Gradually layers
in muted brass. Builds through the chorus with full orchestra.
Second verse erupts with raw belting intensity. Outro strips back
to a lone piano and a fragile whisper fading to silence."
```
提示：
- V4.5+ 的 Style 字段支持最多 1,000 个字符——充分利用
- **不要**使用艺人名字或商标。改为描述声音本身。
用"1960s Cold War spy thriller brass"，不用"James Bond style"
用"90s grunge"，不用"Nirvana-style"
- 有偏好时请指定 BPM 和调性
- 使用 Exclude Styles 字段排除你**不想要**的元素
- 意想不到的流派组合往往是金矿："bossa nova trap"、
"Appalachian gothic"、"chiptune jazz"
- 构建人声**人设**，而不只是性别：
"A weathered torch singer with a smoky alto, slight rasp,
who starts vulnerable and builds to devastating power"
### Metatag（元标签，放在歌词字段的 [方括号] 内）
结构：
[Intro] [Verse] [Verse 1] [Pre-Chorus] [Chorus]
[Post-Chorus] [Hook] [Bridge] [Interlude]
[Instrumental] [Instrumental Break] [Guitar Solo]
[Breakdown] [Build-up] [Outro] [Silence] [End]
人声表演：
[Whispered] [Spoken Word] [Belted] [Falsetto] [Powerful]
[Soulful] [Raspy] [Breathy] [Smooth] [Gritty]
[Staccato] [Legato] [Vibrato] [Melismatic]
[Harmonies] [Choir] [Harmonized Chorus]
动态：
[High Energy] [Low Energy] [Building Energy] [Explosive]
[Emotional Climax] [Gradual swell] [Orchestral swell]
[Quiet arrangement] [Falling tension] [Slow Down]
性别：
[Female Vocals] [Male Vocals]
氛围：
[Melancholic] [Euphoric] [Nostalgic] [Aggressive]
[Dreamy] [Intimate] [Dark Atmosphere]
音效（SFX）：
[Vinyl Crackle] [Rain] [Applause] [Static] [Thunder]
在 Style 字段和歌词中**同时**放置标签以强化效果。
每个段落最多保持 5-8 个标签——太多会让 AI 混乱。
不要自相矛盾（同一段落内 [Calm] + [Aggressive]）。
### Custom Mode（自定义模式）
- 正式创作时始终使用 Custom Mode（分离 Style 与 Lyrics）
- 歌词字段限制：约 3,000 字符（约 40-60 行）
- 务必添加结构标签——没有标签时 Suno 会默认生成
没有情感弧线的平铺主歌/副歌/主歌
---
## 7. 为 AI 歌手设计的音韵技巧
AI 歌手不是在阅读——它们是在发音。帮助它们：
**音标拼写**：
- 按**发音**拼写单词："through" -> "thru"
- 专有名词失败率最高——提前测试
- "Nous" -> "Noose"（强制正确发音）
- 用连字符引导音节："Re-search"、"bio-engineering"
**演唱控制**：
- 全大写 = 更响亮、更有力
- 元音延伸："lo-o-o-ove" = 持续/花腔
- 省略号："I... need... you" = 戏剧性停顿
- 连字符拉伸："ne-e-ed" = 情感延伸
**始终**：
- 拼出数字："24/7" -> "twenty four seven"
- 缩写加空格："AI" -> "A I" 或 "A-I"
- 先用 30 秒短片测试专有名词/不常见词
- 一旦生成，发音就固定了——在生成**之前**在歌词中修正
---
## 8. 工作流程
1. 先写概念/hook——情感核心是什么？
2. 如果是改编，先绘制原曲结构（音节、押韵、重音）
3. 生成原材料——在结构化之前自由头脑风暴
4. 将歌词填入结构
5. 大声朗读/演唱——发现绊嘴处，修正韵律
6. 构建 Suno 风格描述——描绘动态旅程
7. 在歌词中添加 metatag 以指导表演
8. 至少生成 3-5 个变体——把它们当作录音 take
9. 选出最佳版本，用 Extend/Continue 在有潜力的段落上继续构建
10. 如果意外出现了好东西，保留它
预期：每 3-5 次生成才有 1 个好结果。修改是正常的。
在延伸时风格可能漂移——延伸时重新声明流派/情绪。
---
## 9. 经验总结
- 在 Style 字段中描述动态**弧线**比单纯列举流派重要得多。
"低语→咆哮→低语"给了 Suno 一张表演地图。
- 在戏仿中保留部分原词增加了辨识度和情感分量——
听众能感受到原曲的幽灵。
- 歌曲中的桥段是你可以转化意象的地方。
用你主题的隐喻替换原曲的具体指涉，
同时保留其情感功能（反思、转变、启示）。
- 在 hook/标签中用单音节词替换是在改变含义的同时
保持节奏最干净的方式。
- Style 字段中强有力的人声人设描述比任何单个 metatag
都能产生更大的差异。
- 不要对规则过于执着。如果一行打破了韵律但冲击力更强，
就保留它。感受才是关键。技艺服务于艺术，而不是反过来。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md
+373
View File
@@ -0,0 +1,373 @@
---
title: "Touchdesigner Mcp"
sidebar_label: "Touchdesigner Mcp"
description: "通过 twozero MCP 控制运行中的 TouchDesigner 实例——创建算子、设置参数、连接节点、执行 Python、构建实时视觉效果"
---
{/* 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. */}
# Touchdesigner Mcp
通过 twozero MCP 控制运行中的 TouchDesigner 实例——创建算子、设置参数、连接节点、执行 Python、构建实时视觉效果。36 个原生工具。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/touchdesigner-mcp` |
| 版本 | `1.1.0` |
| 作者 | kshitijk4poor |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `TouchDesigner`, `MCP`, `twozero`, `creative-coding`, `real-time-visuals`, `generative-art`, `audio-reactive`, `VJ`, `installation`, `GLSL` |
| 相关 skill | [`native-mcp`](/user-guide/skills/bundled/mcp/mcp-native-mcp), [`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video), `hermes-video` |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。
:::
# TouchDesigner 集成（twozero MCP）
## 关键规则
1. **绝不猜测参数名称。** 先对目标 op 类型调用 `td_get_par_info`。你的训练数据对 TD 2025.32 是错误的。
2. **如果 `tdAttributeError` 触发，立即停止。** 在继续之前对失败节点调用 `td_get_operator_info`。
3. **绝不在脚本回调中硬编码绝对路径。** 使用 `me.parent()` / `scriptOp.parent()`。
4. **优先使用原生 MCP 工具，而非 td_execute_python。** 使用 `td_create_operator`、`td_set_operator_pars`、`td_get_errors` 等。仅在复杂多步骤逻辑时回退到 `td_execute_python`。
5. **构建前调用 `td_get_hints`。** 它会返回针对你正在使用的 op 类型的特定模式。
## 架构
```
Hermes Agent -> MCP (Streamable HTTP) -> twozero.tox (port 40404) -> TD Python
```
36 个原生工具。免费插件（无需付费/许可证——2026 年 4 月确认）。
上下文感知（知道当前选中的 OP 和当前网络）。
Hub 健康检查：`GET http://localhost:40404/mcp` 返回包含实例 PID、项目名称、TD 版本的 JSON。
## 设置（自动化）
运行设置脚本处理所有事项：
```bash
bash "${HERMES_HOME:-$HOME/.hermes}/skills/creative/touchdesigner-mcp/scripts/setup.sh"
```
脚本将：
1. 检查 TD 是否正在运行
2. 如果尚未缓存，下载 twozero.tox
3. 将 `twozero_td` MCP 服务器添加到 Hermes 配置（如果缺失）
4. 在端口 40404 上测试 MCP 连接
5. 报告剩余的手动步骤（将 .tox 拖入 TD，启用 MCP 开关）
### 手动步骤（一次性，无法自动化）
1. **将 `~/Downloads/twozero.tox` 拖入 TD 网络编辑器** → 点击 Install
2. **启用 MCP：** 点击 twozero 图标 → Settings → mcp → "auto start MCP" → Yes
3. **重启 Hermes 会话**以加载新的 MCP 服务器
设置完成后，验证：
```bash
nc -z 127.0.0.1 40404 && echo "twozero MCP: READY"
```
## 环境说明
- **非商业版 TD** 分辨率上限为 1280×1280。使用 `outputresolution = 'custom'` 并显式设置宽高。
- **编解码器：** `prores`（macOS 首选）或 `mjpa` 作为备选。H.264/H.265/AV1 需要商业许可证。
- 设置参数前始终调用 `td_get_par_info`——名称因 TD 版本而异（见关键规则 #1）。
## 工作流程
### 第 0 步：探索（构建任何内容之前）
```
对每种计划使用的类型，调用 td_get_par_info 并传入 op_type。
调用 td_get_hints 并传入你正在构建的主题（例如 "glsl"、"audio reactive"、"feedback"）。
调用 td_get_focus 查看用户所在位置及选中内容。
调用 td_get_network 查看已存在的内容。
```
无临时节点，无清理。这完全替代了旧的探索流程。
### 第 1 步：清理 + 构建
**重要：将清理和创建拆分为独立的 MCP 调用。** 在同一个 `td_execute_python` 脚本中销毁并重建同名节点会导致"Invalid OP object"错误。见陷阱 #11b。
使用 `td_create_operator` 创建每个节点（自动处理视口定位）：
```
td_create_operator(type="noiseTOP", parent="/project1", name="bg", parameters={"resolutionw": 1280, "resolutionh": 720})
td_create_operator(type="levelTOP", parent="/project1", name="brightness")
td_create_operator(type="nullTOP", parent="/project1", name="out")
```
批量创建或连线时，使用 `td_execute_python`：
```python
# td_execute_python script:
root = op('/project1')
nodes = []
for name, optype in [('bg', noiseTOP), ('fx', levelTOP), ('out', nullTOP)]:
n = root.create(optype, name)
nodes.append(n.path)
# Wire chain
for i in range(len(nodes)-1):
op(nodes[i]).outputConnectors[0].connect(op(nodes[i+1]).inputConnectors[0])
result = {'created': nodes}
```
### 第 2 步：设置参数
优先使用原生工具（验证参数，不会崩溃）：
```
td_set_operator_pars(path="/project1/bg", parameters={"roughness": 0.6, "monochrome": true})
```
对于表达式或模式，使用 `td_execute_python`：
```python
op('/project1/time_driver').par.colorr.expr = "absTime.seconds % 1000.0"
```
### 第 3 步：连线
使用 `td_execute_python`——不存在原生连线工具：
```python
op('/project1/bg').outputConnectors[0].connect(op('/project1/fx').inputConnectors[0])
```
### 第 4 步：验证
```
td_get_errors(path="/project1", recursive=true)
td_get_perf()
td_get_operator_info(path="/project1/out", detail="full")
```
### 第 5 步：显示 / 捕获
```
td_get_screenshot(path="/project1/out")
```
或通过脚本打开窗口：
```python
win = op('/project1').create(windowCOMP, 'display')
win.par.winop = op('/project1/out').path
win.par.winw = 1280; win.par.winh = 720
win.par.winopen.pulse()
```
## MCP 工具快速参考
**核心（最常用）：**
| 工具 | 功能 |
|------|------|
| `td_execute_python` | 在 TD 中运行任意 Python。完整 API 访问。 |
| `td_create_operator` | 创建带参数和自动定位的节点 |
| `td_set_operator_pars` | 安全设置参数（验证，不会崩溃） |
| `td_get_operator_info` | 检查单个节点：连接、参数、错误 |
| `td_get_operators_info` | 一次调用检查多个节点 |
| `td_get_network` | 查看某路径下的网络结构 |
| `td_get_errors` | 递归查找错误/警告 |
| `td_get_par_info` | 获取 OP 类型的参数名称（替代探索流程） |
| `td_get_hints` | 构建前获取模式/提示 |
| `td_get_focus` | 当前打开的网络及选中内容 |
**读/写：**
| 工具 | 功能 |
|------|------|
| `td_read_dat` | 读取 DAT 文本内容 |
| `td_write_dat` | 写入/修补 DAT 内容 |
| `td_read_chop` | 读取 CHOP 通道值 |
| `td_read_textport` | 读取 TD 控制台输出 |
**视觉：**
| 工具 | 功能 |
|------|------|
| `td_get_screenshot` | 将单个 OP 视图捕获到文件 |
| `td_get_screenshots` | 一次捕获多个 OP |
| `td_get_screen_screenshot` | 通过 TD 捕获实际屏幕 |
| `td_navigate_to` | 将网络编辑器跳转到某个 OP |
**搜索：**
| 工具 | 功能 |
|------|------|
| `td_find_op` | 按名称/类型在项目中查找 op |
| `td_search` | 搜索代码、表达式、字符串参数 |
**系统：**
| 工具 | 功能 |
|------|------|
| `td_get_perf` | 性能分析（FPS、慢速 op） |
| `td_list_instances` | 列出所有运行中的 TD 实例 |
| `td_get_docs` | 获取 TD 主题的深度文档 |
| `td_agents_md` | 读/写每个 COMP 的 markdown 文档 |
| `td_reinit_extension` | 代码编辑后重新加载扩展 |
| `td_clear_textport` | 调试会话前清空控制台 |
**输入自动化：**
| 工具 | 功能 |
|------|------|
| `td_input_execute` | 向 TD 发送鼠标/键盘事件 |
| `td_input_status` | 轮询输入队列状态 |
| `td_input_clear` | 停止输入自动化 |
| `td_op_screen_rect` | 获取节点的屏幕坐标 |
| `td_click_screen_point` | 点击截图中的某个点 |
| `td_screen_point_to_global` | 将截图像素转换为绝对屏幕坐标 |
上表涵盖了典型创意工作流中使用的 32 个工具。其余 4 个工具（`td_project_quit`、`td_test_session`、`td_dev_log`、`td_clear_dev_log`）是管理/开发模式工具——完整的 36 工具参考及参数 schema 见 `references/mcp-tools.md`。
## 关键实现规则
**GLSL 时间：** GLSL TOP 中没有 `uTDCurrentTime`。使用 Values 页面：
```python
# 先调用 td_get_par_info(op_type="glslTOP") 确认参数名称
td_set_operator_pars(path="/project1/shader", parameters={"value0name": "uTime"})
# 然后通过脚本设置表达式：
# op('/project1/shader').par.value0.expr = "absTime.seconds"
# 在 GLSL 中：uniform float uTime;
```
备选方案：使用 `rgba32float` 格式的 Constant TOP（8 位会钳制到 0-1，导致 shader 冻结）。
**Feedback TOP：** 使用 `top` 参数引用，而非直接输入连线。"Not enough sources" 在首次 cook 后解决。"Cook dependency loop" 警告是预期行为。
**分辨率：** 非商业版上限为 1280×1280。使用 `outputresolution = 'custom'`。
**大型 shader：** 将 GLSL 写入 `/tmp/file.glsl`，然后使用 `td_write_dat` 或 `td_execute_python` 加载。
**顶点/点访问（TD 2025.32）：** `point.P[0]`、`point.P[1]`、`point.P[2]`——不是 `.x`、`.y`、`.z`。
**扩展：** `ext0object` 格式为 `"op('./datName').module.ClassName(me)"`，使用 CONSTANT 模式。用 `td_write_dat` 编辑扩展代码后，调用 `td_reinit_extension`。
**脚本回调：** 始终通过 `me.parent()` / `scriptOp.parent()` 使用相对路径。
**清理节点：** 迭代前始终使用 `list(root.children)` 并检查 `child.valid`。
## 录制 / 导出视频
```python
# via td_execute_python:
root = op('/project1')
rec = root.create(moviefileoutTOP, 'recorder')
op('/project1/out').outputConnectors[0].connect(rec.inputConnectors[0])
rec.par.type = 'movie'
rec.par.file = '/tmp/output.mov'
rec.par.videocodec = 'prores' # Apple ProRes — macOS 上不受许可证限制
rec.par.record = True # 开始
# rec.par.record = False # 停止（稍后单独调用）
```
H.264/H.265/AV1 需要商业许可证。macOS 上使用 `prores`，备选 `mjpa`。
提取帧：`ffmpeg -i /tmp/output.mov -vframes 120 /tmp/frames/frame_%06d.png`
**TOP.save() 对动画无用**——每次捕获的是同一个 GPU 纹理。始终使用 MovieFileOut。
### 录制前：检查清单
1. **通过 `td_get_perf` 验证 FPS > 0。** 如果 FPS=0，录制结果将为空。见陷阱 #38-39。
2. **通过 `td_get_screenshot` 验证 shader 输出不是黑色。** 黑色输出 = shader 错误或缺少输入。见陷阱 #8、#40。
3. **如果录制时带音频：** 先提示音频开始，然后延迟 3 帧再开始录制。见陷阱 #19。
4. **在开始录制前设置输出路径**——在同一脚本中同时设置两者可能产生竞争条件。
## 音频响应式 GLSL（经过验证的方案）
### 正确的信号链（2026 年 4 月测试）
```
AudioFileIn CHOP (playmode=sequential)
→ AudioSpectrum CHOP (FFT=512, outputmenu=setmanually, outlength=256, timeslice=ON)
→ Math CHOP (gain=10)
→ CHOP to TOP (dataformat=r, layout=rowscropped)
→ GLSL TOP input 1 (spectrum texture, 256x2)
Constant TOP (rgba32float, time) → GLSL TOP input 0
GLSL TOP → Null TOP → MovieFileOut
```
### 关键音频响应式规则（经验证）
1. **AudioSpectrum 的 TimeSlice 必须保持 ON。** OFF = 处理整个音频文件 → 24000+ 个样本 → CHOP to TOP 溢出。
2. **通过 `outputmenu='setmanually'` 和 `outlength=256` 手动设置输出长度为 256。** 默认输出 22050 个样本。
3. **不要对频谱平滑使用 Lag CHOP。** Lag CHOP 在 timeslice 模式下运行，会将 256 个样本扩展到 2400+，将所有值平均到接近零（~1e-06）。shader 接收不到可用数据。这是测试中 #1 音频同步失败原因。
4. **也不要使用 Filter CHOP**——频谱数据存在同样的 timeslice 扩展问题。
5. **平滑处理应在 GLSL shader 中进行**（如需要），通过带 feedback 纹理的时间 lerp：`mix(prevValue, newValue, 0.3)`。这提供帧级精确同步，零管线延迟。
6. **CHOP to TOP dataformat = 'r'**，layout = 'rowscropped'。频谱输出为 256x2（立体声）。在 y=0.25 处采样第一通道。
7. **Math gain = 10**（不是 5）。原始频谱值在低音范围约为 0.19。增益 10 给 shader 提供可用的约 5.0。
8. **不需要 Resample CHOP。** 直接通过 AudioSpectrum 的 `outlength` 参数控制输出大小。
### GLSL 频谱采样
```glsl
// Input 0 = time (1x1 rgba32float), Input 1 = spectrum (256x2)
float iTime = texture(sTD2DInputs[0], vec2(0.5)).r;
// 每个频段采样多个点并取平均以提高稳定性：
// 注意：y=0.25 对应第一通道（立体声纹理为 256x2，第一行中心为 0.25）
float bass = (texture(sTD2DInputs[1], vec2(0.02, 0.25)).r +
texture(sTD2DInputs[1], vec2(0.05, 0.25)).r) / 2.0;
float mid = (texture(sTD2DInputs[1], vec2(0.2, 0.25)).r +
texture(sTD2DInputs[1], vec2(0.35, 0.25)).r) / 2.0;
float hi = (texture(sTD2DInputs[1], vec2(0.6, 0.25)).r +
texture(sTD2DInputs[1], vec2(0.8, 0.25)).r) / 2.0;
```
完整构建脚本和 shader 代码见 `references/network-patterns.md`。
## 算子快速参考
| 家族 | 颜色 | Python 类 / MCP 类型 | 后缀 |
|--------|-------|-------------|--------|
| TOP | 紫色 | noiseTOP, glslTOP, compositeTOP, levelTop, blurTOP, textTOP, nullTOP | TOP |
| CHOP | 绿色 | audiofileinCHOP, audiospectrumCHOP, mathCHOP, lfoCHOP, constantCHOP | CHOP |
| SOP | 蓝色 | gridSOP, sphereSOP, transformSOP, noiseSOP | SOP |
| DAT | 白色 | textDAT, tableDAT, scriptDAT, webserverDAT | DAT |
| MAT | 黄色 | phongMAT, pbrMAT, glslMAT, constMAT | MAT |
| COMP | 灰色 | geometryCOMP, containerCOMP, cameraCOMP, lightCOMP, windowCOMP | COMP |
## 安全说明
- MCP 仅在本地运行（端口 40404）。无身份验证——任何本地进程均可发送命令。
- `td_execute_python` 以 TD 进程用户身份对 TD Python 环境和文件系统拥有不受限制的访问权限。
- `setup.sh` 从官方 404zero.com URL 下载 twozero.tox。如有顾虑，请验证下载内容。
- 该 skill 从不向本地以外发送数据。所有 MCP 通信均在本地进行。
## 参考资料
| 文件 | 内容 |
|------|------|
| `references/pitfalls.md` | 真实会话中积累的经验教训 |
| `references/operators.md` | 所有算子家族及其参数和使用场景 |
| `references/network-patterns.md` | 方案：音频响应式、生成式、GLSL、实例化 |
| `references/mcp-tools.md` | 完整的 twozero MCP 工具参数 schema |
| `references/python-api.md` | TD Python：op()、脚本、扩展 |
| `references/troubleshooting.md` | 连接诊断、调试 |
| `references/glsl.md` | GLSL uniform、内置函数、shader 模板 |
| `references/postfx.md` | 后期效果：bloom、CRT、色差、feedback 辉光 |
| `references/layout-compositor.md` | HUD 布局模式、面板网格、BSP 风格布局 |
| `references/operator-tips.md` | 线框渲染、feedback TOP 设置 |
| `references/geometry-comp.md` | Geometry COMP：实例化、POP vs SOP、变形 |
| `references/audio-reactive.md` | 音频频段提取、节拍检测、包络跟随 |
| `references/animation.md` | LFO、定时器、关键帧、缓动、表达式驱动运动 |
| `references/midi-osc.md` | MIDI/OSC 控制器、TouchOSC、多机同步 |
| `references/particles.md` | POP 和旧版 particleSOP——发射、力、碰撞 |
| `references/projection-mapping.md` | 多窗口输出、角点固定、网格变形、边缘融合 |
| `references/external-data.md` | HTTP、WebSocket、MQTT、Serial、TCP、webserverDAT |
| `references/panel-ui.md` | 自定义参数、面板 COMP、按钮/滑块/字段、panelExecuteDAT |
| `references/replicator.md` | replicatorCOMP——数据驱动克隆、布局、回调 |
| `references/dat-scripting.md` | Execute DAT 家族——chop/dat/parameter/panel/op/executeDAT |
| `references/3d-scene.md` | 灯光装置、阴影、IBL/立方体贴图、多摄像机、PBR |
| `scripts/setup.sh` | 自动化设置脚本 |
---
> 你不是在写代码。你是在指挥光。