Ephemera · 墨水屏纸条

Ephemera 让作者模型通过 MCP 投稿，由服务排成纸张，再送到墨水屏。人类用网页控制台查看稿件、预览版面、配置设备和排版工；墨水屏负责阅读、翻页、查看未读和纸匣。服务与设备固件的源码都在本仓库。

目前公开安装包针对 Windows x64 + LILYGO T5 4.7 S3 Pro Lite H752-01。如果你的板型不同，请不要直接刷入附件里的固件。

从零安装（跟着做即可）

1. 在电脑上安装 Node.js 24 或更新版本。准备可传数据的 USB 线、上述墨水屏、同一局域网内的 2.4 GHz Wi‑Fi，以及最新版 Chrome 或 Edge。首次运行需要联网下载排版用 Chromium。

2. 到本仓库的 Releases 下载最新的 ephemera-mcp-service-*-public-win32-x64.zip，完整解压到一个固定文件夹。不要只解压其中的 .exe 或 firmware.bin；安装包是一个完整目录。

3. 在 Windows 终端运行 ipconfig，记下电脑连接该 Wi‑Fi/局域网的 IPv4 地址，例如 192.168.1.25。请用你自己的地址替换下面示例。电脑和墨水屏必须能在局域网里互相访问。

4. 打开 PowerShell，切换到刚解压的安装包目录，运行：

   powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-public.ps1 -LanAddress 192.168.1.25

   首次运行会在安装包同级新建 ephemera-private，生成管理员与作者两把不同的密钥、保存数据，并安装匹配的 Chromium。以后重启用同一命令；窗口需要保持打开。请勿把 ephemera-private 上传到 GitHub 或分享给别人。

5. 在这台电脑的 Chrome/Edge 打开 http://127.0.0.1:8765/console。首次登录使用 ephemera-private\secrets\owner-bearer.txt 中的管理员 Bearer。这是给人类控制台用的，不要发给作者模型。控制台的“总览”应显示服务在线、排版可用。

6. 用 USB 数据线连接墨水屏。在控制台“设备 → 第一次配置”填写 Wi‑Fi 名称、密码和设备名称，确认服务器地址指向刚才电脑的局域网 IPv4，然后执行完整安装。浏览器会请求选择串口、写入正式固件、配置 Wi‑Fi 并配对。请在控制台显示“安装完成”以后再拔线；设备能通过 Wi‑Fi 独立接收纸条。USB 写入必须在本机 Chrome/Edge 的 localhost/127.0.0.1 页面操作，不要从另一台手机的普通 HTTP 页面刷机。

7. 给作者模型接 MCP：在控制台“MCP 配置”复制作者端点，使用 ephemera-private\secrets\author-bearer.txt 中的作者 Bearer。本机端点通常是 http://127.0.0.1:8765/mcp；同一局域网的另一台设备要换成电脑的局域网地址。作者可以先用 ephemera_peek 看当前、未读及近期作品，再用 ephemera_publish 投稿。不要把管理员 Bearer 当作者 Bearer。

8. 可选：在“排版工”设置模型和分步提示词；在“天气预报”设置和风天气 API、地点并获取实时天气与三日预报；在“版式与落款”设置各版式落款、主/小 Logo 与五种表情图。这些外部密钥和个性化数据只保存在本机私人目录。没有真实天气来源时，不应写成已取得真实天气。

投稿后可在控制台“投稿浏览”同时看纯文字和排版原图；在墨水屏阅读、翻页，返回主页后从“纸匣”找未读与最近记录。控制台“设备”可以看电量和最近回执。若作者端在手机上，需要自行提供可访问的 HTTPS MCP 地址；只转发 /mcp，不要将整个管理控制台直接暴露到公网，并继续使用独立、可撤销的作者 Bearer。

个性化图片怎么准备

公开版的主 Logo、小 Logo、角色/狐狸图位置现在都是同一张黑白玫瑰占位图，不是项目作者的私人图片，也不是上游狐狸图。 占位图见 assets/public/rose-placeholder.svg；它只是告诉你哪里可以换图。上传自己的图片后才会显示自己的视觉形象。五种状态分别是普通、高兴、悲伤、思考、困倦；你可以先上传一张通用图，再逐步替换。

上传格式为透明背景 PNG，单张不超过 2 MiB。以下是建议制作尺寸，不是服务器硬性尺寸限制；系统会按版面缩放：

墨水屏是灰度屏。建议用白、纯黑和一档中灰构图，并在小尺寸下检查眼睛、线条和透明边是否仍然清楚。控制台上传后可先看版式预览，再在实机上确认显示。各版式落款也在同一页单独配置；未填写的次要落款位可由排版工按规则补全，主要正文不会因此被改写。

Related MCP server: xiaozhi-mcp-bridge-template

现在能做什么

• 作者通过 MCP 回看与投稿；按内容选择适合的内置体裁，排版工可按配置审核和补齐允许的次要栏目，正文保留作者原文。

• 生成适合 540 × 960 屏幕的正式纸张；支持醒来纸附页、多页阅读和已读、未读、最近记录。

• 网页控制台浏览纯文字、最终排版图、设备回执和报错；配置版式落款、个性化图片、排版工、天气和 MCP。

• 浏览器一键写入指定板型的固件并配置 Wi‑Fi；设备离开 USB 后通过局域网工作。

• 可选接入和风天气，真实天气与三日预报在气象版式中使用；不开启时不伪造天气数据。

当前功能缺口与限制

• 续航仍在实机观察：不承诺一充可用几天。频繁刷新、Wi‑Fi 和电池状态都会影响实际结果。

• TF 卡阅读器未完成：固件里保留入口与软件基础，但读卡、中文书籍排版及卡相关验收尚未完成；不要把它当作已可用的阅读器。

• 周谱保留历史/预览但暂不接受新投稿；自制版式工作台仅预留接口，尚不能在控制台设计并提交新模板。

• 公开安装包只对上述 Windows x64 与指定板型做过本地启动和构建检查；公开包的首次 USB 刷写、跨设备局域网和长期续航仍需不同用户实机复验。其他操作系统、板型不宣称支持。

• 服务目前在前台运行；关闭 PowerShell 窗口即停止，不自带开机自启或云端托管。作者模型、和风天气、远程 HTTPS 隧道均需用户自行配置。

常见问题

从源码构建

安装包已包含对应的服务和固件源码。若只修改/运行服务端，可在本仓库执行 npm ci、npm run build，再按 QUICKSTART_PUBLIC.md 配置启动。firmware-source/ 是匹配的 PlatformIO 固件工程；请先确认自己使用的是 H752-01 板型。普通用户建议下载 Release 安装包，不需要自行编译。

来源、协议与隐私

本项目的纸张排版代码改编自 marikagura/kimi-room；改动与第三方字体见 THIRD_PARTY_NOTICES.md，本项目代码按 AGPL-3.0-only 发布。上游图片与私人鸢尾花、龙泡泡图片均未放入公开仓库或安装包；上游图片的 CC BY-NC 条款不因代码开源而自动变成可自由商用的图片许可。公开玫瑰是本项目另画的占位素材。

如你修改本服务并让别人通过网络使用，应按 AGPL 要求向这些用户显著提供对应源码。不要把数据库、Bearer、Wi‑Fi 密码、天气/模型 API Key、上传的私人图片或 ephemera-private 推送到公开仓库。

这个仓库的 Issues 欢迎报告可复现的问题；请去掉日志中的密钥、住址、稿件私人正文和设备标识后再提交。