| name | trmnl-paper-screen |
| description | Use when the user wants to push, deploy, or update screen content on a TRMNL device via a LaraPaper instance. Builds the JSON payload with device credentials (MAC address + device API key) and sends to `/api/screens`. After an actual send, it can read back `image_url` from the current screen endpoint, review the rendered result, and route layout fixes back to `trmnl-paper-blade`. Also use when they say "send to device," "update the display," "deploy this screen," or need to construct the LaraPaper screen update request for already-prepared markup.
|
trmnl-paper-screen
概览
负责把已有 markup 通过 POST /api/screens 推送到 LaraPaper。实际发送成功后，再取回当前渲染图（路径见 references/api-screens.md），审查展示是否正常、是否适合 e-paper；若有问题，则把问题清单回传给 trmnl-paper-blade 做下一轮修正。
工作流
-
确认 markup 是否就绪
- 没有 → 先用
trmnl-paper-blade 生成，再回到这里
- 有 → 继续
-
收集参数（四个都必须）：
| 参数 | 说明 | 示例 |
|---|
base URL | LaraPaper 实例地址，必须带 scheme | https://larapaper.example.com |
mac_address | 设备 MAC，服务端会自动转大写 | AA:BB:CC:DD:EE:FF |
device API key | 设备级 API key（不是 APP_KEY） | abc123... |
| markup | 要推送的 Blade / HTML 内容 | <x-trmnl::screen>...</x-trmnl::screen> |
-
默认 dry-run：预览完整请求体（凭据已脱敏），用户明确要求时才实际 POST；如需查看原始凭据，仅 dry-run 可加 --show-secrets。
-
优先使用脚本：从仓库根目录运行 python3 skills/trmnl-paper-screen/scripts/push_screen.py ...，避免手写 JSON 转义错误；如果当前目录已在 skill 内，可用 python3 scripts/push_screen.py ...。
-
实际发送后读取渲染结果：使用 --send --current-screen，或在发送成功后调用当前屏幕接口（路径见 references/api-screens.md）。
-
需要视觉审查时下载图片：使用 --download-image <path> 把 image_url 下载到本地，再检查展示是否正常与美观；--download-image 会隐式触发 current_screen 读取。
-
若有问题，走修正闭环：整理问题清单 → 交回 trmnl-paper-blade 改 markup → validate_markup.py 校验 → 重新推送并复查。
推送后审查闭环
只在用户明确要求实际发送时进入这个闭环；dry-run 不做图片审查。
POST /api/screens 推送 markup- 取回当前渲染图
image_url（路径见 references/api-screens.md）
- 下载图片并做人工/多模态审查（审查标准见
references/review-checklist.md）
- 按问题类型回到
trmnl-paper-blade 修正
- 重新校验、推送、复查
默认先修最明显的 1-3 个问题，避免一次改太多导致回归。若两轮后仍存在明显取舍，再向用户说明并确认方向。
如果目标实例做了异步渲染或额外缓存，取回的图片可能短暂是上一版；此时等待片刻后重试即可，不要误判为新稿无效。
规则
- 不伪造
base URL、mac_address、device API key
- 只使用
POST /api/screens
- 取回渲染结果的路径见
references/api-screens.md
- 请求头固定为
id + access-token
- body 固定为
{"image":{"content":"...","file_name":"..."}}
file_name 可选，默认 screen.blade.markup- 默认把 markup 与请求体分开展示
- 只有用户明确要求时才实际发送
POST /api/screens 不返回 image_url；image_url 来自后续当前屏幕接口- 只有用户明确要求实际发送时，才执行"推送 → 取图 → 审查 → 优化"闭环
APP_KEY 不是这个 skill 的凭据- LaraPaper 会对
content 执行 Blade::render()，所以可以直接发送 <x-trmnl::...> 语法，前提是目标实例安装了 trmnl-blade
图片审查标准
详见 references/review-checklist.md。审查时先看"正常性"，再看"美观性"，最后参考"常见修正动作"回到 trmnl-paper-blade 修正。
错误处理
| HTTP 状态码 | 含义 | 处理方式 |
|---|
| 200 | 成功，返回 {"message":"success"} | — |
| 404 | MAC 或 API key 不匹配 | 检查 MAC 大小写和 API key 是否正确 |
| 422 | 请求体验证失败（缺 image.content） | 检查 JSON 结构是否符合规范 |
| 500 | 服务端渲染失败（Blade 语法错误等） | 检查 markup 是否合法 |
| 连接失败 | base URL 不可达 | 检查 URL scheme 和网络 |
| 取回渲染图失败 | 无法读取当前屏幕 | 检查 access-token、实例可达性，以及是否真的完成了发送 |
image_url 缺失或图片下载失败 | 无法做推送后审查 | 先确认 LaraPaper 当前屏幕已生成，再重试 |
发送前检查
与 trmnl-paper-blade 的边界
| trmnl-paper-blade | trmnl-paper-screen |
|---|
| 职责 | 生成 markup | 推送 markup |
| 输入 | 内容描述 / 数据 | 已完成的 markup |
| 输出 | Blade 模板代码 | API 请求或执行结果 |
| 验证 | 组件语法、结构规则 | 请求格式、凭据 |
管道衔接
trmnl-paper-blade 生成的 markup 通过以下方式传入本 skill：
- 文件：
--markup-file <path>（推荐，避免转义问题）
- 标准输入：
--markup-stdin，适合管道串联
交接格式
以下 YAML 是 trmnl-paper-screen 与 trmnl-paper-blade 共用的权威交接格式。
推送后如需回传问题给 trmnl-paper-blade，每条问题使用以下最小字段格式：
- issue: 文案在标题栏溢出
location: x-trmnl::title-bar title 属性
suggested_fix: 缩短标题文案，或加 data-clamp="1"
issue 描述问题现象，location 定位组件或属性，suggested_fix 给出最小修改方向。
参考资料
- 已验证请求格式与取图步骤：读
references/api-screens.md
- 推送后视觉审查标准：读
references/review-checklist.md
可用脚本
scripts/push_screen.py — 构造或发送 LaraPaper 屏幕更新请求（默认 dry-run），可在发送后获取 current_screen 并下载渲染图
输出约定
默认按以下顺序输出：
- endpoint：
POST /api/screens
- 请求头（凭据脱敏）
- 请求体（markup 单独展示）
- 如用户要求实际发送，再给发送结果
- 如用户要求发送后复查，再给
image_url、审查结论与修正建议
