Paperang

Paperang 2 (喵喵机2) 打印 Skill

IRON LAW: 执行打印前必须确认串口已配置（config.json 存在且有效）。绝不猜测串口号；首次使用必须引导用户完成串口配置。检查方法：uv run python -m paperang config。

FEED RULE: 单次打印（只打一条）→ 必须加 --feed 250 把内容推到可见区域。连续打印（多条）→ 中间不加 feed，最后一条命令 && uv run python -m paperang feed 250。打印完看不到内容就是忘了走纸。

Workflow checklist

每次打印任务按以下步骤执行：

• Step 1: 确认串口已配置 — uv run python -m paperang config 有 serial_port 则跳过，否则走首次设置流程
• Step 2: 确认打印意图与参数 — text / image / qrcode / selftest / feed / config？收集必要参数
• Step 3: 构建并执行命令 — 所有命令使用 uv run python -m paperang <subcommand>
• Step 4: 反馈结果 — 向用户报告执行结果或错误信息

Quick reference

All commands use uv run for isolated venv execution.

Text size recommendations

Image processing modes

Setup flow

Check existing configuration

Always start here. Before any print command, verify the port is configured:

uv run python -m paperang config

• Already has serial_port → skip to printing.
• serial_port is null or missing → first-time setup below.

First-time setup

The user helps ONCE. After setup the port is persisted to config.json and saved to your persistent memory — subsequent sessions just work.

1. Install dependencies:

   uv sync
   

   If uv is not installed: pip install uv or https://docs.astral.sh/uv/

2. Guide the user to pair via Windows Bluetooth:

   • Long-press Paperang power button until LED blinks
   • Settings → Bluetooth & devices → Add device → Bluetooth
   • Find and pair the Paperang

3. Guide the user to add a Bluetooth COM port:

   • Windows: Settings → Bluetooth & devices → More Bluetooth options
   • Switch to the "COM Ports" tab
   • Click "Add..." → "Outgoing (your computer initiates the connection)"
   • Browse and select the device with PAPERANG in its name
   • Windows will assign a COM port number (e.g. COM10), note it down

4. List ports and ask the user:

   uv run python -m paperang config --list
   

   Show output, ask: "哪个是你的喵喵机串口？" User answers e.g. COM10.

5. Save the port and write to memory:

   uv run python -m paperang config --set-port COM10
   

   Then write to persistent memory:

   Paperang printer uses COM10 on this machine. Check: uv run python -m paperang config. Change: uv run python -m paperang config --set-port COM<number>.

Print test page (first-time only)

After configuring the port, verify the connection with a single quick print first. If it succeeds, chain the rest together:

# Step 1: 快速探路 — 只打一行确认连接正常
uv run python -m paperang text --font-size 32 "测试打印中...\nTesting..."

If the above succeeds (no error) → chain the remaining prints with &&:

uv run python -m paperang text --font-size 36 "项目地址" && \
uv run python -m paperang qrcode "https://github.com/createskyblue/paperang-miaomiaoji-tool-gen2" && \
uv run python -m paperang text --font-size 24 "github.com/createskyblue/paperang-miaomiaoji-tool-gen2" && \
uv run python -m paperang text --font-size 36 "作者博客" && \
uv run python -m paperang qrcode "https://createskyblue.github.io/" && \
uv run python -m paperang text --font-size 24 "createskyblue.github.io" && \
uv run python -m paperang image assets/test_image.jpg && \
uv run python -m paperang text --font-size 42 "欢迎使用喵喵机!\nWelcome to Paperang!" && \
uv run python -m paperang feed 250

If the first command fails, stop and troubleshoot — don't run the chain.

Subsequent sessions

Config already has serial_port → go straight to printing. Do NOT re-ask.

If the printer doesn't respond

1. uv run python -m paperang config --list — check port still exists
2. Port changed? Ask user, --set-port the new one, update memory
3. Port correct but fails? Ask user to check printer is on and paired

Anti-patterns

• ❌ 不要硬编码 COM10 或其他串口号
• ❌ 不要跳过 config 检查，首次启动必须引导用户从列表中选择串口
• ❌ 不要在未确认文件存在的情况下直接打印图片
• ❌ 不要用全局 pip 安装依赖，始终用 uv sync

Interactive mode (for human users)

Interactive REPL for direct human use:

uv run python -m paperang interactive

Commands: /selftest, /qrcode <text>, /fontsize <N>, /imgmode <mode>, /help. Enter text or image path directly to print.