Meituan Printer

---
name: meituan-printer
description: >
  美团热敏打印机技能。向美团热敏打印机发送格式化任务单、检查单或小票。
  支持通过预配置别名（中文）或直接指定 IP:端口来选择目标打印机。
  触发场景：用户要求打印、发送到打印机、打印任务单/检查单/小票、
  提到"打印机"、"后厨打印"、"前厅打单"、"素菜岗打印"、
  "配置打印机"、"管理打印机"、"添加打印机"、"新增打印机"、"删除打印机"、
  "定时打印"、"自动打印"等。
---

# 美团热敏打印机 (meituan-printer)

通过 TCP Socket + ESC/POS 协议，向美团热敏打印机发送带格式的任务单/检查单。

## 两种配置管理方式

> **推荐首选 Web 管理界面**，浏览器操作更直观；不方便时再通过对话方式。

### 方式一：Web 管理界面（推荐）

用户可通过浏览器管理所有打印机、定时任务和打印模板，无需终端操作。

**启动方式：**
1. **对话启动**：直接告诉 AI "启动打印机管理界面"或"打开 web 后台"，AI 会帮你启动
2. **终端命令**：macOS/Linux 执行 `python3 scripts/start_web_admin.py`，Windows 执行 `python scripts\start_web_admin.py`

启动后访问终端输出的地址，默认 `http://localhost:5000`；如果端口被占用，会自动选择 `5001` 起的可用端口。

**功能：**
- 打印机管理：添加/编辑/删除打印机、连通性测试、类型自定义
- 定时任务：创建/编辑/启停定时打印任务、立即执行、导出到系统级定时任务
- 模板管理：预设打印模板、自定义模板

> 💡 如果用户说"管理打印机"、"添加打印机"、"配置打印机"、"定时打印"、"打开管理界面"等，AI 应主动引导用户使用 Web 管理界面，或直接帮用户启动。

### 方式二：对话式配置

不方便打开浏览器时，AI 可直接通过对话完成打印机配置。

#### 对话式配置流程

AI 直接与用户对话，按以下步骤收集信息并完成配置：

```
meituan-printer/
├── SKILL.md                          # 本文件（AI 指引）
├── scripts/
│   ├── print_to_printer.py           # 核心打印脚本
│   ├── check_printer.py              # 连通性检测工具（非交互式）
│   ├── web_admin.py                  # Web 管理界面后端（Flask + APScheduler）
│   ├── platform_utils.py             # 跨平台工具层（macOS/Windows 兼容）
│   ├── start_web_admin.py            # 跨平台 Web 后台启动入口
│   ├── config.json                   # 打印机配置
│   ├── tasks.json                    # 定时任务配置
│   └── templates/
│       ├── index.html                # Web 管理界面前端
│       └── task_templates.json       # 预设打印模板
├── references/
│   ├── printer-config.md             # 打印机配置参考（IP/类型映射）
│   └── onboarding.md                 # 新手指南（面向用户）
└── config.json                       # 用户配置（运行时生成）
```

## 核心流程：两步走

### 第一步：配置打印机（对话式，一次性）

用户首次使用或需要添加/管理打印机时，**通过对话完成配置**，不需要用户运行任何脚本。

#### 对话式配置流程

AI 直接与用户对话，按以下步骤收集信息并完成配置：

**1. 询问基本信息**

向用户提问（自然语言即可，不需要一次性问完）：
- **IP 地址**：打印机的局域网 IP（如 `192.168.3.172`）
- **端口**：默认 `9100`，如果不是标准端口才需要用户说明
- **别名**：中文别名，方便日常称呼（如"后厨"、"素菜"、"前厅酒水"）
- **类型**：打印机用途（荤菜岗/备货岗/前台收银/其他）
- **备注**：选填，如"梅林店前厅"

> 💡 AI 可以根据 `references/printer-config.md` 中已有的信息主动提示，减少用户输入。

**2. 连通性检测（AI 后台执行）**

收集到 IP 和端口后，AI 在后台运行检测脚本：

```bash
python3 scripts/check_printer.py --ip <IP> --port <端口>
```

返回 JSON：`{"reachable": true/false, "ip": "...", "port": ..., "error": null/"错误信息"}`

根据结果告知用户：
- `reachable: true` → "✅ 打印机连接成功"
- `reachable: false` → "⚠️ 无法连接，请确认 IP/端口和打印机电源"

**3. 写入配置**

检测通过后，AI 直接将新打印机追加到 `scripts/config.json`：

```json
{
  "alias": "前厅",
  "ip": "192.168.3.172",
  "port": 9100,
  "type": "前厅收银",
  "remark": "梅林店"
}
```

config.json 完整格式：
```json
{
  "version": "1.0",
  "printers": [...],
  "created_at": "2026-04-24",
  "updated_at": "2026-04-24"
}
```

> ⚠️ 如果别名已存在，AI 应提示用户并确认是否覆盖。

#### 配置管理

用户也可以通过对话请求：
- **查看已配置打印机**：读取 config.json 并以表格形式展示
- **删除打印机**：确认别名后从 config.json 的 printers 数组中移除
- **修改打印机**：确认要修改的字段后更新对应条目

### 第二步：发起打印（日常使用）

```bash
python3 scripts/print_to_printer.py --name <别名> --title "<标题>" --content "<内容>"
```

## AI 工作流（当用户请求打印时）

### 步骤 1：确认打印目标

按以下优先级确定目标打印机：

| 用户说法 | 对应参数 |
|---------|---------|
| "后厨"、"素菜"、"前厅" | `--name 后厨` 等 |
| "荤菜岗"、"素菜岗"、"前台" | `--name <对应别名>` |
| "IP 是 xxx" / "地址是 xxx" | `--ip <IP>` |
| 未指定 | 查 config.json；无配置则引导用户先通过对话配置 |

### 步骤 2：确认任务类型

**必须询问用户**：

> "这个打印任务是**定时任务**还是**一次性打印**？"
> - **一次性**：立即发送到打印机
> - **定时任务**：记录下来，协助用户创建自动化（cron/任务计划程序）

### 步骤 3：确认内容

- **标题（title）**：任务单名称，如"早班A任务单"、"素菜岗检查单"
- **内容（content）**：具体工作事项，多行用 `\n` 分隔
  - 时间节点用 `-------HH:MM-------` 格式
  - 示例：`"-------09:30-------\\n打卡拍照\\n解冻冻货"`

### 步骤 4：执行打印

**立即打印**：调用 print_to_printer.py，捕获结果并告知用户

**定时打印**：
- 记录：打印机别名 + 标题 + 内容 + 触发时间
- 告诉用户定时任务的创建方式（crontab / 任务计划程序）
- 必要时协助生成 crontab 条目

### 步骤 5：输出确认

打印完成后，向用户反馈：
```
✅ 已发送至【后厨】(192.168.3.172:9100)
📄 标题：早班A任务单
⏰ 时间：2026-04-23 14:30
```

## 打印格式说明

打印输出包含：
1. **大标题**（居中 + 双倍大小）：任务单名称
2. **时间戳**（居中 + 倍高）：打印时间
3. **分隔线**：32 个 `=`
4. **正文**（倍高）：具体工作内容，时间节点加粗+倍宽
5. **结尾提示**："请按时完成各项工作"
6. **自动切纸**

## 注意事项

- **Python 环境**：使用 `python3`（macOS/Linux 默认）或 `python`（Windows 默认）
- **配置文件**：`scripts/config.json`（AI 直接读写，用户无需手动编辑）
- **默认端口**：`9100`（美团热敏打印机标准端口，99% 适用）
- **中文编码**：GB18030，确保打印机支持中文热敏纸
- **网络要求**：打印机与电脑在同一局域网内
- **超时设置**：连接超时 5 秒

## Web 管理界面

### 概述

提供一个本地 Web 管理界面，用户可通过浏览器管理打印机和定时任务，无需终端操作。

### 启动方式

**macOS/Linux**：`python3 scripts/start_web_admin.py`
**Windows**：`python scripts\start_web_admin.py`

启动入口会自动检测 Python 环境、安装依赖（flask, apscheduler），然后启动 Web 服务。

访问地址：终端输出的 `http://localhost:<端口>`，默认 `5000`；如果端口被占用，会自动选择 `5001` 起的可用端口。

### 功能模块

1. **打印机管理**：添加/编辑/删除打印机、连通性测试
2. **定时任务**：创建/编辑/启停定时打印任务、立即执行、导出到系统级定时任务
3. **模板管理**：预设打印模板（早班检查单、晚班收尾单、周报表、月度盘点单）、自定义模板

### 定时任务频率

支持三种频率：
- **每天**：每天固定时间执行（如每天 09:00）
- **每周**：每周几固定时间（如每周一 09:00）
- **每月**：每月几号固定时间（如每月 1 号 08:00）

### 系统级定时任务导出

定时任务默认在 Web 服务进程内调度（APScheduler）。支持导出为系统级定时任务：
- **macOS**：导出为 launchd plist，安装到 `~/Library/LaunchAgents/`
- **Windows**：通过 `schtasks /create` 注册到 Windows 任务计划程序

导出后即使 Web 服务关闭，定时任务仍会按时执行。