使用 ditherlab 创作 ASCII 艺术
手工输入艺术存在固有缺陷：密度估算不准、忽略 1:2 的字符单元宽高比、缺乏光照方向。ditherlab 将真实像素抖动为字符（确保艺术效果从构造上就正确），渲染 3D 图元，将艺术解码回图像，并支持主题 —— 具名样式的设置与手绘规则，可应用与扩展。图形部分用工具生成；创作部分参考文档；好的效果保存下来。
持久性
一旦触发，每次助手回复都保持激活状态。即便不确定时仍保持激活。仅当用户说 "stop ascii-art" 或 "normal mode" 时关闭。
安装与配置
ditherlab --help。如果不在 PATH 中：node <克隆目录>/bin/ditherlab.js，或克隆 https://github.com/daronthedragon/ditherlab（零依赖，Node 18+，npm link）。使用 MCP 而非 Shell：ditherlab agents mcp <客户端> 会为任意 MCP 客户端打印配置（cursor、windsurf、cline、roo、vscode、zed、gemini、codex、claude——对于 Claude：claude mcp add ditherlab -- node <克隆目录>/src/mcp.js）；ditherlab agents install <名称|all> 将这些指令写入其他智能体读取的位置（AGENTS.md、.cursor/rules、.github/copilot-instructions.md 等）。工具包括：render_text_art render_3d draw_scene auto_tune banner figlet diagram table tree box lint_art gallery decode_art render_art_image dither_image list_themes save_theme info，资源包括：ditherlab://references/*、ditherlab://themes、ditherlab://gallery、ditherlab://figlet-fonts。支持 PNG、JPEG（基线+渐进式）、GIF、BMP、PGM/PPM 解码（零依赖）；若 ffmpeg 在 PATH 上，则额外支持 WebP/TIFF 和视频。
处理流程
每次按顺序执行。在解决任务的第一步后停止。
- 是否指定或暗示了风格？（"蓝图"、"Game Boy"、"素描"、"用于我的 README"）：运行
ditherlab themes。找到匹配主题 → 后续所有命令中使用--theme <名称>。无匹配 → 从参考文档中组合设置，渲染，等待用户批准后运行ditherlab theme save <名称> …并添加--use-when指定用户提到的短语（参考 docs/references/themes.md）。 - 根据图像创作艺术（照片、截图、徽标）：不确定时先运行
ditherlab inspect photo.jpg—— 它会报告色调、色彩丰富度、透明度、边缘密度，以及适合 24/40 行的宽度，并提供建议标志。然后从下表选择模式并运行——或让工具自动选择：ditherlab auto photo.jpg --mode braille -w 70会搜索约 100 种设置，根据结构保留度评分，输出最佳艺术效果及其命令。逐字粘贴输出。当结果值得保留时，添加--save-theme <名称> --use-when "…"。 - 横幅文字：经典 FIGlet 样式（README、CLI 标题、MOTD）：
ditherlab figlet "ship it" -f slant（--list显示 15 个内置字体——标准、倾斜、小号、大号、横幅、阴影、脚本、迷你、块、lean、digital、bubble、term、smslant、smscript；-f path.flf加载任意 FIGlet 字体；--width 80 --center换行/居中）。像素字体横幅：ditherlab text "SHIP IT"（--style block|shadow|half|braille|quadrant、--frame round --title …）；小写字母/真实字体外观：--font mono（8×16 字形；搭配--style half或braille以保持简短）。绝不要手工输入块状字母或 FIGlet 字母。 - 3D / 旋转 / "甜甜圈" / 3D 徽标：
ditherlab 3d torus --rx 0.9 --ry 0.6 -w 70 --mode braille；--spin --frames 24 -o spin.gif生成动画；--mode shape绘制草图；ditherlab 3d --text "GO" --ry 0.4挤出字母；--extrude logo.png挤出位图；--scene "sphere s=1.1; box op=subtract s=0.8 ry=0.6; torus y=-1.4 s=0.5"使用 CSG 组合对象（op=union|subtract|intersect|smooth、x= y= z= rx= ry= rz= s=）。其他形式：编写脚本像素（PGM）然后编码——请参考 docs/references/3d-and-shading.md 中的十行球体示例。 - "做点酷的/抽象的/海报/屏幕保护程序"：
ditherlab gen attractor --seed 42 -w 70（也支持 plant、maze --solve、truchet、plasma、automaton --rule 110、rose）——带种子的可重复生成；提供两个种子。对于需要看起来像手工制作的图像：--mode flow（笔画包裹形状）、hatch（雕刻风格）、stipple（点画风格）。参考 docs/references/generative.md。 - 没有图像的主题（"画一座房子"、"一枚火箭"、"一张脸"）：不要凭空想象输入。使用场景 DSL 将其描述为几何体并渲染：
ditherlab draw scene.txt --mode braille -w 60（图元：rect circle ellipse line poly text，单位 0–100，fill=stroke=shade=sphere|cylinder；ditherlab draw --help-dsl和--example house|rocket|face|cup|planet显示可工作的场景）。如果存在该主题的真实图像，则优先使用。对于极小图形（≤ 8 行），查看ditherlab gallery <名称|标签>中的示例并调整。最后的手段：按照 docs/references/freehand.md 和主题的freehand规则手绘，并注明是手绘作品。 - 按需生成动画（"让它动起来"、"放大"、"矩阵式揭示"、README 英雄区域）：
ditherlab fx photo.jpg --preset crash-zoom -o out.gif——摄像机运动（ken-burns、crash-zoom、dolly-in、pull-back、vertigo、handheld、关键帧路径）、揭示效果（typewriter、scan、dissolve、matrix）、图层效果（glitch、rain、snow、stars、fireworks）、--crt荧光输出；.cast用于终端，.gif用于 README（参考 docs/references/motion.md）。MCP：animate_art。 - 视频、摄像头、GIF → 动画：
ditherlab play clip.mp4 -w 80 --mode braille --fps 12 -o out.gif（不带-o则在终端中播放；--demo用于测试）。Web UI：拖入视频/摄像头 → 录制 GIF。 - 识别或重新格式化粘贴的艺术：
ditherlab decode art.txt -o out.png --scale 4（自动检测 ascii / braille / quadrant / sextant / ANSI；经典的.ans/.nfoCP437 文件可透明读取），查看 PNG，然后使用新选项重新编码。ditherlab render art.txt -o art.png生成艺术的图片。 - 抖动图像文件：
ditherlab dither in.png -p gb -o out.png（-p auto:8从图像构建调色板；undither逆向操作）。 - 人眼交互探索（人类正在观看）：
ditherlab tui photo.jpg——按键可实时切换模式/宽度/算法/色调/调色板/主题；e打印等效命令，q退出并打印命令。ditherlab side a.txt b.txt --titles "before|after"并列两部艺术作品以供比较。 - 任意图表——流程图、时序图、状态机、时间线、思维导图、架构图：编写为 Mermaid 格式并运行
ditherlab diagram d.mmd——类型自动检测（graph TD、sequenceDiagram含 notes / loop / alt / activations / autonumber、stateDiagram-v2含[*]、timeline、mindmap），或使用纯文本a -> b: label行。subgraph … end绘制带标签的容器。样式：rounded double heavy ascii+shadow（▒ 深度效果）+sketch（手绘风格）+--color（每节点 ANSI 颜色，仅限终端）。柱状图/柱状图/迷你图来自数据：ditherlab chart data.csv [--dir TB|--spark|--sorted]——精确的八分之一块比例。对于超过三个方框的情况，绝不要手工绘制箭头；绝不要目测柱状图长度（参考 docs/references/diagrams.md）。 - 表格、树形图、带框的注释：
ditherlab table data.csv|t.md|data.json [--style rounded|double|markdown|minimal]（数字右对齐，宽字符正确测量，--max-width自动换行）；ditherlab tree outline.txt|dir|data.json（├──/└──）；ditherlab box "text" --title … --style … --align center。 - 在交付任何手绘或粘贴的作品前：运行
ditherlab lint art.txt——检查制表符、行尾空格、BOM、零宽度字符、双宽度字符、不齐的边框行、未连接的制表符连接点。--fix应用安全修复（--pad统一宽度，--junctions重新计算角落/三通连接）；--unicode/--ascii在线条艺术字符+-|和制表符之间转换。退出码为 1 时，必须在粘贴前修复。 - 无任务可做：
ditherlab demo [mode]。
模式与宽度选择指南
| 目标 / 意图 | 模式 | 宽度 |
|---|---|---|
| README / markdown | ascii --theme readme（如果 Unicode 没问题则用 braille） | ≤ 80 |
| 终端，人类观看 | ditherlab show（若 ditherlab term 显示支持，则通过 kitty/iTerm2/sixel 使用真实像素），否则用 symbols | 终端宽度 |
| 终端、MOTD、需要纯文本 | symbols（最高保真度：每单元形状 + 前景/背景颜色）、braille（单色细节）、symbols --mono | 80–140 |
| 聊天 | braille 或 quadrant | 40–70 |
| 仅纯文本 | ascii -c classic | ≤ 72 |
| 素描 / 线条艺术 | shape（笔画匹配）或 edge；ascii --edges | 60–100 |
| 复古 / 像素风 | quadrant，或 `ansi -p gb | pico8 |
| 可分享的文字图片 | 任意模式 + `-o art.svg | .html |
| 终端录制 / README 嵌入 | play … -o out.cast（asciinema）或 -o out.gif | 60–100 |
| 根据描述生成主题 | draw（2D 场景）或 3d --scene/--text → 任意模式 | 50–90 |
| 小图标 / 吉祥物 | gallery <名称> 示例，调整后使用 | ≤ 12 |
| 流程图 / 流水线 / 状态图 | diagram（Mermaid 或 a -> b），--style ascii 用于纯文本 | ≤ 100 |
| 表格 / 树形图 / 带框注释 | table / tree / box；--style markdown 用于 GitHub 渲染文档 | ≤ 100 |
| CLI / README 标题 | `figlet -f slant | small |
徽标和图标：--trim 移除均匀的填充，--bg #fff 在渲染前将透明度叠加到页面颜色上。旧终端和 CI 日志：--colors 256 或 --colors 16 重新量化真彩色转义码。高度预算：--rows N 缩小宽度直到艺术作品适应 N 行——当目标容器有已知高度（如 24 行终端、聊天气泡、README 分区）时使用。按顺序调整：--levels 处理模糊或昏暗照片（自动色阶）；--clahe 0.4 增强阴影/天空中的细节；--contrast 0.2 令平淡画面更鲜明；--sharpen 0.6 模糊变清晰；--invert 反转色调；--paper 浅色背景；-a atkinson 稀疏/干净，-a bayer4 复古风格，-a bluenoise 无图案颗粒感；--strength 0.5 缓和繁忙的抖动；--frame round --title 当艺术作品嵌入段落时使用；--linear（伽马校正：中灰色约为 21% 墨量——真实亮度——而非 50%）当色调看起来过暗或过亮时使用；--oklab 用于调色板工作（-p gb|cga|auto:N），使颜色按感知距离映射。在进行任何手动调整前阅读 docs/references/ascii-fundamentals.md；关于光影与形态请阅读 docs/references/3d-and-shading.md。
规则
- 绝不要把手工输入的艺术作品展示为工具输出。任何超过 4 行的涂鸦都必须由对话中展示的 ditherlab 命令生成，或者明确标注为手绘作品，遵循 docs/references/freehand.md 的规则，并且在粘贴前已通过
ditherlab lint（退出码 0）检查。 - 流程图、表格、树形图和横幅都必须来源于
diagram、table、tree、figlet——而不是手工对齐字符。 - 逐字粘贴工具输出；绝不要润色字符。
- 发送前查看结果并测量：
ditherlab score art.txt image.png（或 MCP 的score_art）返回 0..1 之间的结构保留度——低于 0.75 表示需要重新运行auto、更宽的宽度或使用symbols/braille。此方法也适用于对照参考图像的手绘作品。 - ANSI 转义码仅用于终端；文件和 markdown 使用
ascii、braille、blocks，或导出.svg/.html/.png。 - 遵守宽度列规定；超出介质宽度会变成杂乱无章的换行。
- 用户认可的外观必须在本次对话回合结束前保存为主题。
- 当设置不确定时，在手动调整前先运行
auto；当主题不确定时，在输入字符前先使用几何描述（draw、3d --scene）。 - 精确字体输出：如果目标字体很重要，从 Web UI 导出字形图集（下载 ▾ → 字形图集）并运行
ditherlab font <文件>；之后shape和render将匹配该字体的真实字符形状。
示例
不要这样做：
这里为您准备了一个球体用于 README：
___
/ \
| ( ) |
\ ___ /
应该这样做：
$ ditherlab 3d sphere -w 46 --theme readme
[粘贴实际命令的输出]
参考文档（按需阅读，不必一次性全部读完）
docs/references/ascii-fundamentals.md——字符单元比例、测量的字符密度、笔画词汇、Unicode 系列、介质限制、构图。docs/references/3d-and-shading.md——ditherlab 3d、PGM 先计算再编码的方法、等距/透视规则、着色顺序、材质、动画。docs/references/freehand.md——网格辅助、块状字母、边框、小图标、示意图、失败场景处理表。docs/references/themes.md——模式、解析优先级、theme save命令、配置默认值、按名称使用风格的工作流程。docs/references/terminal-graphics.md——term/show：kitty、iTerm2、sixel 协议，何时像素胜过字符，读取 CP437 ANSI 艺术。docs/references/generative.md——flow/hatch/stipple 模式、gen种类、种子、海报与纹理的制作配方。docs/references/motion.md——fx：摄像机、揭示效果、粒子图层、CRT、关键帧路径、不同介质的时长选择、Director 标签页。docs/references/diagrams.md——diagram：支持的 Mermaid 子集和a -> b语法、样式、方向、布局与布线原理、图表过宽时的处理方法；table、tree、box、figlet、lint。gallery.json（ditherlab gallery）——30 个示例作品及其比例/笔画说明：动物、物体、符号、UI 集合、着色球体、等距立方体。scenes：ditherlab draw --example …——五个可运行的场景文件供复制。
可观察效果
回复中的每件艺术品前都有生成它的 ditherlab 命令（或 MCP 调用）——auto（设置不确定时）、draw/3d（主题无图像时）、diagram/table/tree/figlet（结构化文本时）——或者标注为手绘作品，并附上参考的 gallery 作品/主题/参考文档和 lint 结果；有疑问的结果附带 score；粘贴的艺术品经过 decode；用户喜欢的风格以 theme save 结束。评估将精确检查这一点。