TRMNL 私有插件技能提供构建与运维 TRMNL 电子墨水私有插件的实战知识，既包含官方文档内容，也补充文档未提及的坑点，例如渲染几何被裁切、MCP 的怪异行为、CSS 级联层以及载荷字节限制。
【用途与心智模型】 TRMNL 是服务端渲染的电子墨水设备，设备主动轮询，没有任何内容被推送到设备。数据流为：数据源经 Webhook POST 写入合并变量，标记编辑器或 MCP 提供 Liquid 模板，TRMNL 渲染 PNG，设备唤醒后下载图片再休眠。资料强调存在两条互相独立的更新路径，不可混淆：改变屏幕内容需生成 JSON 并 POST 到插件 Webhook，Webhook 只更新合并变量，永不改变标记；改变屏幕外观需编辑 Liquid 标记、保存、预览并强制刷新，标记编辑器本身不会获取新数据。Webhook 提交会在约 2 秒内触发服务端重新渲染，但物理设备只在下一次唤醒时显示（默认每 15 分钟一次）；服务端提交不会唤醒设备，也不消耗电量。
【密钥与标识符】 资料列出四类凭据并提醒不要混淆：设备 API 密钥为不透明令牌，在 Devices → Edit 获取，用于 /api/display 与 /api/current_screen 的 access-token 请求头；账户 API 密钥形如 user_…，在账户设置获取，用于账户 API（设备、播放列表）的 Authorization: Bearer；插件设置 UUID 出现在 Webhook URL 中，首次保存插件时生成，Webhook POST 到 /api/custom_plugins/<uuid>；插件 MCP 密钥形如 ps_mcp_…，在插件设置页保存后右侧显示，用于 https://trmnl.com/mcp?api_key=…。MCP 密钥是按插件隔离的，只能读写该插件的标记、设置与合并变量，不能控制设备、播放列表、电量、截图或预览，也不会泄露插件 UUID 或 Webhook URL；设备与播放列表相关工作应改用账户 API。所有真实值应保存在环境变量或操作系统钥匙串中，绝不写入提交文件；Webhook URL 本身也应视为机密，持有者即可写入屏幕。
【Webhook 数据更新】 载荷结构为所有内容位于顶层 merge_variables 之下，示例为 curl 向 https://trmnl.com/api/custom_plugins/${TRMNL_PLUGIN_UUID} 发送 JSON。标准档硬限制为 2 KB 请求体、每小时 12 次提交（TRMNL+ 为 5 KB、每小时 30 次），超频会返回 429；插件“Debug Logs”模式在开发期间可临时提高限制。规则包括：只发送精简后的展示文本（如 time、title），绝不发送上游 API 原始输出，否则会超出字节限制并泄露无意发送的数据；在真实限制之下设置本地护栏（例如 2 KB 档用 1900 字节），并让生成器降级而非失败，宁可削减行数并渲染诚实的“+ N more”标签，也不要抛错或静默裁切；模板循环上限应不低于生成器上限，否则会静默丢弃条目。有状态更新可用 merge_strategy: "deep_merge" 修补嵌套键，或用 merge_strategy: "stream" 加 stream_limit 向顶层数组追加并限制增长，但存储数据仍须符合大小限制。对同一 Webhook URL 发 GET 可获取当前存储的合并变量。
【标记要点】 始终以 800x480 创作。TRMNL X 以 4 位（16 级灰阶）渲染 1040x780，但框架会自动缩放 800x480 标记（scale_factor: 1.8），切勿硬编码原生分辨率。每个视图一个 <div class="layout">…</div>，可选同级 <div class="title_bar">，绝不嵌套 .layout，也不要把 .screen/.view 包装粘贴进 TRMNL 编辑器（它们仅用于离线预览）。框架将 .layout 尺寸设为 screen-h 减去两倍 gap（10 px 边框内为 460 px，有 title_bar 时更小）；若使用自定义根元素代替 .layout，必须复制该高度：height: calc(var(--screen-h, 480px) - var(--gap, 10px) * 2)，而 height: 100% 会在 460 px 盒子里渲染 480 px 并裁掉底部约 20 px。省略 title_bar 是合法且常常正确的（它约占 35 px），保存无 title_bar 的标记会触发“Missing title_bar include”警告，属预期，可忽略。plugins.css 使用 CSS 级联层，带层的 !important 会胜过无层的 !important 与内联样式，无法用更高优先级覆盖框架尺寸，应采纳其变量（--screen-h、--gap、--full-w）或类。私有插件标记允许自定义 <style> 块，但 TRMNL 应用内 AI 代理强制“无自定义样式”，若要求其“改进”会压平设计，应保留本地文件作为唯一事实来源。电子墨水可读性方面，应相信物理设备而非浏览器预览：拿不准时用更大字号、2 px 线条（1 px 细线远看会消失）、font-feature-settings: "tnum" 1 对齐时间，远距离阅读的屏幕正文字号不要低于约 19 px，改用两栏布局。
【每插件 MCP】 端点 https://trmnl.com/mcp?api_key=… 是无状态 HTTP JSON-RPC，可直接调用 tools/list 与 tools/call，无需 initialize 握手。工具名为 PascalCase 且带 Tool 后缀（如 MarkupsWriteTool），不是应用内代理的 snake_case 名称，用 snake_case 会返回 Tool not found。MarkupsWriteTool 接收 {size, content}，传 markup 而非 content 会返回无用的 -32603 Internal error。MCP 写入标记是盲写（不存在截图或预览工具），安全写入流程为：读取线上 → 备份 → 写入 → 读回 → 反转义 → 与本地源比较，再在编辑器预览器或离线工具中目视验证。
【离线预览】 可在 TRMNL 官方 CSS/JS 包装内用示例数据本地渲染 Liquid 模板，然后对 .screen 元素截图（精确 800x480），无需账户往返。应离线迭代到布局正确后再推送标记，并包含最坏情况示例载荷（最大行数、最长标题），因为繁忙日才是布局出问题的时候。
【电量与刷新节奏】 插件刷新（服务端）与设备唤醒（电量）是分开的：Webhook 提交免费，设备唤醒消耗电量（WiFi、抓取、电子纸刷新）。睡眠模式是最容易的优化：22:00–06:00 睡眠、15 分钟节奏可避免每天约 32 次唤醒。节奏应匹配内容：由每日或每小时数据驱动的仪表盘很少需要全天 15 分钟刷新，合理配置为早高峰 15–30 分钟、午间 60 分钟、傍晚 30–60 分钟、夜间睡眠。/api/display（设备密钥）会推进播放列表，不要用它做监控轮询，应少量使用 /api/current_screen。
【故障排查】 资料给出症状与修复对照：预览为空时先 POST 一个极小载荷，确认 strategy = Webhook、载荷位于 merge_variables 下、插件已保存过一次（UUID 存在）；屏幕底部被裁切时检查自定义根元素是否缺少 calc(var(--screen-h) - var(--gap)*2) 高度，或是否忘了为 title_bar 预留空间；物理设备比预览差时应相信设备，用更大字号、更少展示字体、显式网格列、更粗线条；Webhook 429 表示超出每小时提交上限，应批量更新并在开发时启用 Debug Logs；渲染缺少条目时检查模板 limit 是否低于载荷内容，或载荷超出字节上限导致生成器削减行数；MCP Tool not found 是用了 snake_case，应改用 PascalCase 加 Tool 后缀；MCP 写入 -32603 Internal error 是传了 markup，参数应为 content；MCP 读回与本地文件总不一致是因为信封转义了 \n/"/\，比较前需反转义；编辑器保存出现“Missing title_bar include”警告在有意省略标题栏时属预期，可忽略。
【文档链接】 文档索引：https://docs.trmnl.com/go/llms.txt；Webhooks：https://docs.trmnl.com/go/private-plugins/webhooks.md；模板：https://docs.trmnl.com/go/private-plugins/templates.md；Framework 3.1：https://trmnl.com/framework/docs/3.1/v3_overview.md；TRMNL X 指南：https://trmnl.com/framework/docs/3.1/trmnl_x_guide；原生插件标记示例：https://github.com/usetrmnl/plugins/。