Ascii Art

Operational Steps

1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

Pitfalls

-

-

Verification

-

-

-

-

1. 2. 3.

IO_CONTRACT

• input: description: str, dimensions: tuple — 用户请求描述、上下文信息
• output: ascii_output: str — ASCII艺术

对应原则：P2（机械原子暴露输入输出规范）

ASCII Art Skill

Multiple tools for different ASCII art needs. All tools are local CLI programs or free REST APIs — no API keys required.

Tool 1: Text Banners (pyfiglet — local)

Render text as large ASCII art banners. 571 built-in fonts.

Setup

pip install pyfiglet --break-system-packages -q

Usage

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

Recommended fonts

Tips

• Preview 2-3 fonts and let the user pick their favorite
• Short text (1-8 chars) works best with detailed fonts like doom or block
• Long text works better with compact fonts like small or mini

Tool 2: Text Banners (asciified API — remote, no install)

Free REST API that converts text to ASCII art. 250+ FIGlet fonts. Returns plain text directly — no parsing needed. Use this when pyfiglet is not installed or as a quick alternative.

Usage (via terminal curl)

# 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"

Tips

• URL-encode spaces as + in the text parameter
• The response is plain text ASCII art — no JSON wrapping, ready to display
• Font names are case-sensitive; use the fonts endpoint to get exact names
• Works from any terminal with curl — no Python or pip needed

Tool 3: Cowsay (Message Art)

Classic tool that wraps text in a speech bubble with an ASCII character.

Setup

sudo apt install cowsay -y    # Debian/Ubuntu
# brew install cowsay         # macOS

Usage

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

Available 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

Eye/tongue modifiers

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

Tool 4: Boxes (Decorative Borders)

Draw decorative ASCII art borders/frames around any text. 70+ built-in designs.

Setup

sudo apt install boxes -y    # Debian/Ubuntu
# brew install boxes         # macOS

Usage

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

Combine with pyfiglet or asciified

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

Tool 5: TOIlet (Colored Text Art)

Like pyfiglet but with ANSI color effects and visual filters. Great for terminal eye candy.

Setup

sudo apt install toilet toilet-fonts -y    # Debian/Ubuntu
# brew install toilet                      # macOS

Usage

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

Filters

crop, gay (rainbow), metal, flip, flop, 180, left, right, border

Note: toilet outputs ANSI escape codes for colors — works in terminals but may not render in all contexts (e.g., plain text files, some chat platforms).

Tool 6: Image to ASCII Art

Convert images (PNG, JPEG, GIF, WEBP) to ASCII art.

Option A: ascii-image-converter (recommended, modern)

# Install
sudo snap install ascii-image-converter
# OR: go install github.com/TheZoraiz/ascii-image-converter@latest

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

Option B: jp2a (lightweight, JPEG only)

sudo apt install jp2a -y
jp2a --width=80 image.jpg
jp2a --colors image.jpg              # Colorized

Tool 7: Search Pre-Made ASCII Art

Search curated ASCII art from the web. Use terminal with curl.

Source A: ascii.co.uk (recommended for pre-made art)

Large collection of classic ASCII art organized by subject. Art is inside HTML <pre> tags. Fetch the page with curl, then extract art with a small Python snippet.

URL pattern: https://ascii.co.uk/art/{subject}

Step 1 — Fetch the page:

curl -s 'https://ascii.co.uk/art/cat' -o /tmp/ascii_art.html

Step 2 — Extract art from pre tags:

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')

Available subjects (use as URL path):

• Animals: cat, dog, horse, bird, fish, dragon, snake, rabbit, elephant, dolphin, butterfly, owl, wolf, bear, penguin, turtle
• Objects: car, ship, airplane, rocket, guitar, computer, coffee, beer, cake, house, castle, sword, crown, key
• Nature: tree, flower, sun, moon, star, mountain, ocean, rainbow
• Characters: skull, robot, angel, wizard, pirate, ninja, alien
• Holidays: christmas, halloween, valentine

Tips:

• Preserve artist signatures/initials — important etiquette
• Multiple art pieces per page — pick the best one for the user
• Works reliably via curl, no JavaScript needed

Source B: GitHub Octocat API (fun easter egg)

Returns a random GitHub Octocat with a wise quote. No auth needed.

curl -s https://api.github.com/octocat

Tool 8: Fun ASCII Utilities (via curl)

These free services return ASCII art directly — great for fun extras.

QR Codes as ASCII Art

curl -s "qrenco.de/Hello+World"
curl -s "qrenco.de/https://example.com"

Weather as ASCII Art

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

Tool 9: LLM-Generated Custom Art (Fallback)

When tools above don't have what's needed, generate ASCII art directly using these Unicode characters:

Character Palette

Box Drawing: ╔ ╗ ╚ ╝ ║ ═ ╠ ╣ ╦ ╩ ╬ ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼ ╭ ╮ ╰ ╯

Block Elements: ░ ▒ ▓ █ ▄ ▀ ▌ ▐ ▖ ▗ ▘ ▝ ▚ ▞

Geometric & Symbols: ◆ ◇ ◈ ● ○ ◉ ■ □ ▲ △ ▼ ▽ ★ ☆ ✦ ✧ ◀ ▶ ◁ ▷ ⬡ ⬢ ⌂

Rules

• Max width: 60 characters per line (terminal-safe)
• Max height: 15 lines for banners, 25 for scenes
• Monospace only: output must render correctly in fixed-width fonts

Decision Flow

1. Text as a banner → pyfiglet if installed, otherwise asciified API via curl
2. Wrap a message in fun character art → cowsay
3. Add decorative border/frame → boxes (can combine with pyfiglet/asciified)
4. Art of a specific thing (cat, rocket, dragon) → ascii.co.uk via curl + parsing
5. Convert an image to ASCII → ascii-image-converter or jp2a
6. QR code → qrenco.de via curl
7. Weather/moon art → wttr.in via curl
8. Something custom/creative → LLM generation with Unicode palette
9. Any tool not installed → install it, or fall back to next option

验证清单 · VERIFICATION

• 已按决策流（Decision Flow）为请求选择正确的工具（文本横幅→pyfiglet/asciified；边框→boxes；图像转换→ascii-image-converter 等）
• 字体/角色选择适配文本长度（短文本用 doom/block 等细节字体，长文本用 small/mini 紧凑字体）
• 远程 API 请求正确编码（空格 URL-encode 为 +，字体名大小写敏感，通过 fonts 端点核实）
• 输出在等宽字体下渲染正确，无布局溢出（自定义艺术 ≤60 列宽、横幅 ≤15 行）
• LLM 兜底生成时仅使用文档中的 Unicode 字符集（box drawing / block elements / geometric）
• 工具未安装时按决策流降级到下一选项（本地→asciified API→curl），并给出明确提示

约束规则 · RULES

1. 输入约束: 参数类型、范围、格式必须校验
2. 输出约束: 返回值结构、编码、命名必须一致
3. 异常约束: 错误信息必须包含上下文和恢复建议
4. 安全约束: 不执行未验证的任意代码，不暴露内部状态

Golden 集合 · GOLDEN SET

• Golden Input: 标准输入样本（覆盖正常路径）
• Golden Output: 预期输出（精确匹配或格式校验）
• Golden Error: 预期错误信息（覆盖失败路径）

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反规则的操作视为不安全，必须拒绝或隔离。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

Ascii Art

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [ASCI-001] 文本长度短 (1-8 字符) → 优先使用细节丰富的大字体 (如 doom, block) 以增强视觉冲击力
• [ASCI-002] 文本长度长 → 优先使用紧凑字体 (如 small, mini) 以避免布局溢出并保持可读性
• [ASCI-003] 需要本地运行且未安装 Python 环境 → 使用 asciified REST API 通过 curl 生成，避免依赖 pip 安装
• [ASCI-004] 需要为文本添加装饰性边框 → 将文本流通过管道传入 boxes 工具并指定设计样式 (如 stone, parchment)
• [ASCI-005] 需要彩色或特殊视觉效果 (如彩虹、金属) → 使用 toilet 工具并应用 ANSI 滤镜 (如 --gay, --metal)，注意其输出包含转义码
• [ASCI-006] 需要将图像转换为 ASCII 艺术 → 使用 ascii-image-converter 并指定尺寸参数 (-d) 或启用 Braille 字符 (-b) 以优化细节
• [ASCI-007] 需要特定角色的对话气泡效果 → 使用 cowsay 并指定角色 (-f) 及眼睛/舌头修饰符 (如 -b, -w) 以定制表情