pic-gen

Unified Image Generation Tool - Cover (cover), Mermaid (mermaid), Card (card), and Terminal (terminal) Generation

Features

• Cover Image Generation (cover): Generate cover images/videos (PNG/SVG/APNG/GIF/WebP/MP4/WebM) based on HTML templates with Playwright; SVG is pure vector for built-in templates
• Mermaid Diagram Generation (mermaid): Render Mermaid text to PNG/SVG/APNG/GIF/WebP/MP4/WebM, with default optimization for dynamic edges and branch-differentiated colors (can be disabled)
• Card Image Generation (card): Generate card images/videos in unified formats (PNG/SVG/APNG/GIF/WebP/MP4/WebM)
• Terminal Animation Generation (terminal): Generate terminal images/videos (SVG/PNG/APNG/GIF/WebP/MP4/WebM)
• REST API: REST API with OpenAPI specification
• Docker Deployment: One-click Docker Compose deployment

Quick Start

Install Dependencies

npm install
npx playwright install chromium

CLI Usage

# Show help
node cli.js --help

# Cover image generation
node cli.js cover templates                               # List all templates
node cli.js cover gen --primary "Title" --secondary "Subtitle" -f png -o cover.png
node cli.js cover gen --primary "Title" -f svg -o cover.svg    # Pure vector SVG

# Mermaid diagram generation
node cli.js mermaid gen input.mmd -o output.png           # Generate PNG
node cli.js mermaid gen input.mmd -o output.svg           # Default optimize: dynamic edges + diversified branch colors
node cli.js mermaid gen input.mmd --no-optimize -o output.svg
node cli.js mermaid optimize input.mmd -o optimized.mmd   # Output optimized Mermaid source
node cli.js mermaid check input.mmd                       # Syntax check

# Card image generation
node cli.js card gen -i card.json -f svg -o card.svg      # Render card to SVG
node cli.js card gen -i card.json -f webp -o card.webp

# Terminal image/video generation
node cli.js terminal gen -i terminal.json -f svg -o terminal.svg
node cli.js terminal parse -i session.txt -o terminal.json
node cli.js terminal parse -i session.txt | node cli.js terminal gen -i - -f svg -o terminal.svg

API Server

# Start server
npm run api

# Access Swagger documentation
open http://localhost:3000/docs

Docker Deployment

# 自动串联构建 base + app，并启动服务
npm run docker:up:build

# 查看日志
npm run docker:logs

# 停止服务
npm run docker:down

仓库现在拆成两个镜像：

• Dockerfile.base：基础运行时镜像，包含 curl、ffmpeg、生产依赖和 Chromium
• Dockerfile：业务镜像，只叠加当前仓库代码和启动入口

日常开发推荐使用自动串联构建：

npm run docker:build:all
docker compose up -d

如果只是普通代码、模板或启动配置变更，只需要重建业务镜像：

npm run docker:build:app
docker compose up -d

只有以下情况才需要重建 base 镜像：

• 更新了 package-lock.json
• 更新了 playwright 版本
• 更换了 Playwright 基础镜像 tag
• 需要重新安装或校验 Chromium

手动两步构建命令：

PIC_GEN_BASE_IMAGE=pic-gen-base:local npm run docker:build:base
PIC_GEN_BASE_IMAGE=pic-gen-base:local PIC_GEN_APP_IMAGE=pic-gen:local npm run docker:build:app
docker compose up -d

CI 或发布到远端镜像仓库时，可以直接注入镜像 tag：

PIC_GEN_BASE_IMAGE=ghcr.io/example/pic-gen-base:2026-03-24 npm run docker:build:base
docker push ghcr.io/example/pic-gen-base:2026-03-24

PIC_GEN_BASE_IMAGE=ghcr.io/example/pic-gen-base:2026-03-24 \
PIC_GEN_APP_IMAGE=ghcr.io/example/pic-gen:2026-03-24 \
npm run docker:build:app
docker push ghcr.io/example/pic-gen:2026-03-24

默认会同时启动：

• REST API：宿主机 3000 -> 容器 3000
• MCP HTTP：宿主机 40201 -> 容器 3000

相关环境变量：

• PIC_GEN_BASE_IMAGE：基础镜像 tag，默认 pic-gen-base:local
• PIC_GEN_APP_IMAGE：业务镜像 tag，默认 pic-gen:local
• API_PORT：REST API 对外端口，默认 3000
• MCP_PORT：MCP HTTP 对外端口，默认 40201

MCP HTTP Server

# Start MCP HTTP server locally
npm run mcp:http

# Start MCP HTTP server and force the external base URL used in artifact links
npm run mcp:http -- --public-base-url https://mcp.example.com

# Health check
curl http://localhost:3000/health

# MCP endpoint
curl http://localhost:3000/mcp

MCP 工具默认返回 JSON 结果。生成类工具除了在 structuredContent.artifacts 中提供产物元数据（如 path、uri、mimeType、bytes、format）外，还会在 content 中直接附带可消费的内联内容：

• 图片产物使用 type: "image"，内含 base64 data
• 其他二进制产物使用 type: "resource"，内含 base64 blob

当前仅支持 HTTP MCP，并且 artifacts 只返回 uri，值为当前 MCP 服务可直接访问的 http(s)://.../artifacts/:id 链接。

如果 HTTP MCP 部署在容器、反向代理或端口映射后面，且自动探测到的是容器内地址，可显式指定外部基址。 支持两种方式，优先级为：命令行参数 --public-base-url > 环境变量 PUBLIC_BASE_URL。

node mcp/http-server.js --public-base-url https://your-public-host
PUBLIC_BASE_URL=https://your-public-host npm run mcp:http

工具结果默认会附带 resource_link。

generate_terminal 同时支持两种输入：

• data：已解析好的 terminal animation JSON
• text：原始终端会话文本，由服务端内部先解析再渲染

在 MCP 场景下，禁止传 outputPath。服务端会自动生成临时产物路径，并通过 artifacts[].uri 返回可访问地址。

典型返回结构示例：

{
  "ok": true,
  "module": "terminal",
  "artifacts": [
    {
      "uri": "http://localhost:3000/artifacts/xxxx",
      "mimeType": "image/svg+xml",
      "bytes": 12345,
      "format": "svg"
    }
  ],
  "format": "svg"
}

API Endpoints

| Method | Path | Description | | ------ | ------------------------ | ----------------------------- | | GET | /health | Health check | | GET | /api/cover/templates | Get cover template list | | POST | /api/cover/generate | Generate cover image | | POST | /api/mermaid/render | Render Mermaid diagram | | POST | /api/mermaid/validate | Validate Mermaid syntax | | GET | /api/card/layouts | Get card layouts/presets | | POST | /api/card/generate | Generate card image/video | | GET | /api/terminal/schema | Get terminal JSON schema | | GET | /api/terminal/styles | Get terminal styles | | GET | /api/terminal/formats | Get terminal formats | | POST | /api/terminal/generate | Generate terminal image/video | | POST | /api/terminal/parse | Parse text to terminal JSON |

Example Requests

Generate Cover Image

curl -X POST http://localhost:3000/api/cover/generate \
  -H "Content-Type: application/json" \
  -d '{"template":"black-yellow","primary":"Title","secondary":"Subtitle"}' \
  --output cover.png

Render Mermaid Diagram

curl -X POST http://localhost:3000/api/mermaid/render \
  -H "Content-Type: application/json" \
  -d '{"code":"flowchart LR\n  A-->B","format":"png","optimize":true,"backgroundMotion":"dots"}' \
  --output diagram.png

Generate Card Image

curl -X POST http://localhost:3000/api/card/generate \
  -H "Content-Type: application/json" \
  -d '{"layout":"table-2col","ratio":"9:16","theme":"dark","format":"png","title":"Card","header":["Key","Value"],"rows":[["name","pic-gen"]],"backgroundMotion":"grid"}' \
  --output card.png

Generate Terminal Image

curl -X POST http://localhost:3000/api/terminal/generate \
  -H "Content-Type: application/json" \
  -d '{"format":"svg","style":"bash","theme":"dark","steps":[{"type":"input","text":"echo hi"},{"type":"output","text":"hi"}]}' \
  --output terminal.svg

MCP Terminal Tool

generate_terminal 可直接传入原始终端文本：

{
  "text": "$ echo hello\nhello\n",
  "format": "svg"
}

也可继续传入已解析的 data：

{
  "data": {
    "style": "bash",
    "theme": "dark",
    "steps": [
      { "type": "input", "text": "echo hello" },
      { "type": "output", "text": "hello" }
    ]
  },
  "format": "svg"
}

LLM Tool Directory Conventions

All tools in this directory are designed to assist Large Language Models (LLMs) in safely and predictably executing tasks within automated workflows. Tool designs should follow these general conventions for stable LLM invocation:

• Target Audience: Tools are designed for programmatic/unattended scenarios, not human interaction.
• Composability: Support non-interactive invocation through parameters; do not enter interactive mode by default.
• Standard IO:
  • Input supports two methods: -i <file> for file input or read from STDIN (using -i -).
  • Text results default to STDOUT; binary results (e.g., PNG) must be explicitly saved to disk via -o <path>.
• Discoverability: Provide -h/--help with parameter descriptions and examples; provide --version if applicable.
• Determinism: Same input and parameters produce same output; avoid implicit network requests or unstable dependencies.
• Idempotency and Retryability: Multiple executions should not cause unexpected side effects; failures return non-zero exit codes and provide parseable error messages on STDERR.
• Paths and Permissions: Avoid writing to parent directories of relative paths; only write files when user explicitly specifies -o/--output.
• Compatibility: Be cross-platform (Windows/Linux/macOS); avoid interactive TTY dependencies.
• Performance and Resources: Minimize unnecessary logging; write necessary logs to STDERR and support suppression via --quiet.

Unified Parameter Conventions (recommended, tools may declare deviations in README):

• -i, --input <file>: Input file; - means read from STDIN.
• -o, --output <path>: Output file or directory; defaults to STDOUT if not provided (for text results).
• -h, --help: Show help and exit.
• --version: Show version and exit (if applicable).
• --quiet: Reduce unnecessary log output (logs to STDERR).

Directory Structure Recommendations:

• Each tool in its own subdirectory, containing:
  • Executable entry point (e.g., bin/<tool>.js).
  • package.json (if using Node.js).
  • Tool-specific README.md (with examples and common error explanations).
  • Optional: examples/ directory for quick validation.

Quality and Testing:

• Provide minimal runnable examples for LLM verification.
• Define clear error codes and messages; avoid vague descriptions (e.g., "failed").
• Once published, external interfaces should remain backward compatible or document changes in help.

Tool Index (brief description):

• mermaid-gen: Generate Mermaid images/videos (PNG/SVG/APNG/GIF/WebP/MP4/WebM), supports gen/check/optimize, and can output Markdown with ```mermaid code blocks via --md-output.
• cover-gen: Generate cover images/videos (PNG/SVG/APNG/GIF/WebP/MP4/WebM) based on HTML templates with Playwright; supports single/batch rendering and template listing; covers should be strongly related to article themes (see usage below).
  • Built-in templates (black-yellow / blue-tech / dark-minimal / red-black / pornhub) support pure vector SVG.
  • Animation defaults: svg/apng/gif/webp/mp4/webm animate by default, png is always static. CLI 不再提供动画参数开关，需在 JSON/API 中设置。
• terminal-gen: Generate terminal typing animation outputs in SVG/PNG/APNG/GIF/WebP/MP4/WebM; supports text parsing and style switching.

Unified Directory Requirements (in progress):

• Each tool must have:
  • bin/<tool>.js (CLI entry point, providing -h/--help)
  • package.json (with bin field)
  • README.md (including purpose, parameters, examples, and notes)
  • Optional: examples/ (example inputs)

Testcase Schema Conventions:

• Each generator type has a dedicated schema under project-root schemas/:
  • cover-gen.schema.json
  • mermaid-gen.schema.json
  • card-gen.schema.json
  • terminal-gen.schema.json
• Every JSON file under testcase/<module>/ should include a $schema field pointing to the corresponding file in ../../schemas/.

Remote Image Specifications (for all articles)

• Images in article body must use remote absolute URLs (OSS/S3, etc.); local relative paths are prohibited.
• Use standard Markdown image syntax in body: ![Description](https://...), e.g., ![spec-kit-arch](https://share.jqknono.com/articles/gh-spec-kit/images/spec-kit-arch.gif).
• Use npm run dist:sync to sync dist/ to remote during distribution, overwriting with local version.

Image Output and Storage Paths (unified convention)

• All article-related images (including covers) are saved to ./dist/<slug>/images/ directory.
• Cover images output to ./dist/<slug>/images/cover.png.
• Example:
  • Mermaid rendering (export PNG/GIF/WebP/SVG simultaneously; prioritize remote GIF links in published body; use vertical layout when horizontal elements exceed 8, e.g., flowchart TD/TB; animations show data flow, set as needed but prefer animated versions):
    • node tools/mermaid-gen/cli.js input.mmd -o dist/<slug>/images/arch.png
    • node tools/mermaid-gen/cli.js input.mmd -o dist/<slug>/images/arch.gif
    • node tools/mermaid-gen/cli.js input.mmd -o dist/<slug>/images/arch.webp
    • node tools/mermaid-gen/cli.js input.mmd -o dist/<slug>/images/arch.svg

Common Pitfalls and Fixes (must read)

• Do not use Python entry for Mermaid rendering (e.g., python -m tools.mermaid_gen.cli or tools.mermaid_gen.cli do not exist); only use Node version: node tools/mermaid-gen/cli.js.
• cover-gen regarding --output and directories:
  • If --output is a relative path, final file is written to tools/cover-gen/out/<relative path>, and tool only pre-creates outputDir, not deeper subdirectories.
  • Recommended safe approaches:
    1. Use absolute path: --output "$PWD/dist/gh-<slug>/images/cover.png", and run mkdir -p dist/gh-<slug>/images first.
    2. Use --output-dir "$PWD/dist/gh-<slug>/images" --output cover.png, also after mkdir -p dist/gh-<slug>/images.
  • Default --device both outputs -desktop/-mobile versions; desktop preset is 1920x1080, mobile preset is 1080x1920. For single cover.png, use --size 1920x1080 to limit size and generate only cover.png.
• Node/Chromium dependencies: Both cover-gen and mermaid-gen depend on headless browsers (Playwright/Puppeteer). If browser is not found at runtime, run npm i --omit=dev in tool subdirectory and retry.

Mermaid Flowchart Animation (enabled by default)

When generating Mermaid flowcharts, animations should be added to connection lines by default to enhance readability and visual guidance. If you need raw rendering without preprocessing, use CLI --no-optimize or API optimize: false.

• Animation options only support fast and slow; medium is prohibited.
• Color guidelines: Different blocks should use different fill colors for better readability. For example, use blue tones for clients, green tones for servers, orange tones for network devices, etc.
• Reference documentation:
  • Turning an animation on: https://mermaid.js.org/syntax/flowchart.html#turning-an-animation-on
  • Selecting type of animation: https://mermaid.js.org/syntax/flowchart.html#selecting-type-of-animation
  • Using classDef statements for animations: https://mermaid.js.org/syntax/flowchart.html#using-classdef-statements-for-animations
• Recommended examples (Mermaid v11 syntax):

flowchart LR
  A e1@==> B
  e1@{ animate: true }

flowchart LR
  A e1@--> B
  e1@{ animation: fast }

Mermaid Sequence Diagram 规则（建议）

• sequenceDiagram 建议使用 autonumber。
• 提示：Mermaid 原生仅 flowchart/graph 支持 eN@{ ... } 连接线动画语法；sequenceDiagram 不支持，避免写 eN@{ ... } 以免解析报错。

Cover Generation (cover-gen) Usage

• Installation: Run npm i --omit=dev in tools/cover-gen directory, then run node cli.js -h to view help.
• Single generation:

node cli.js cover gen \
  --template blue-tech \
  --primary "<Article title or repo name + theme>" \
  --secondary "<One-sentence value proposition/key feature>" \
  --desc "<Optional: supplementary context or version>" \
  --format svg \
  --output dist/<slug>/images/cover.svg

• Animation controls:

  • Default: svg/apng/gif/webp/mp4/webm are animated, png is static.
  • 相关参数仅支持 JSON/API 设置：noAnimation、fps、duration、loop、backgroundMotion、backgroundMotionOptions、watermark、watermarkText。
  • cover gen 额外支持 CLI 快捷参数：--bg-icons <csv>（用于 dots 图标列表，iconCount 会按图标数量自动推导，最多 4）。
  • backgroundMotion 默认 dots，可在 JSON 里改为 none|lines|grid|gradient。
  • 当 backgroundMotion='dots' 且未配置 icons 时，默认图标为 circle（圆点）。
  • backgroundMotionOptions 支持：iconCount(1-4)、icons[]、DotsIconSizes{primary,secondary}(1-64)、DotsIconSpacing(1-12, integer multiple, default 2 for multi-icons)、moveMode(diagonal|direction|stagger-row|stagger-col)、angle(0-360)。未显式提供 iconCount 时会按 icons 数量自动推导（最多 4）。

• Devices and dimensions:

  • When --size/--device are not specified, defaults to output both desktop and mobile versions: cover-desktop.png, cover-mobile.png.
  • Default device presets: desktop=1920x1080, mobile=1080x1920.
  • Use --device desktop|mobile|both to control exports.
  • Specify --size WIDTHxHEIGHT to output only that size file.

• Batch tasks (JSON):

node cli.js --input examples/tasks.json

• Template selection: Match the article theme (engineering/technical feel: blue-tech/dark-minimal; emphasis on contrast: black-yellow/red-black).
• Article integration: Place cover.png in ./dist/<slug>/images/ (path: ./dist/<slug>/images/cover.png), ensuring the text matches the article title/summary and is relevant.

flowchart LR
  A e1@--> B
  classDef animate stroke-dasharray: 9,5,stroke-dashoffset: 900,animation: dash 25s linear infinite;
  class e1 animate