跳转至

Worker 管线

Inklet 后端使用三个基于 SQS 的 Worker 异步处理用户内容。每个 Worker 负责管线的一个独立阶段：理解上传内容、决定推送内容、以及渲染最终位图。

概览

flowchart LR
    A[上传确认] --> B[Summary Worker]
    B --> C[Analyze Worker]
    C --> D[Render Worker]
    D --> E[Push QUEUE]
    E --> F[设备下载]

用户通过内容上传 API 上传内容后，管线会经过三个阶段处理，然后结果才可供设备显示。

Summary Worker

SQS 队列： inklet-raw-upload-item

在上传确认后触发。该 Worker 使用 AI 来理解上传的内容并生成结构化摘要。

触发条件： 上传确认（内容上传流程的最后一步）

处理流程：

  1. 从数据库读取原始上传内容
  2. 对于文本笔记：使用 GPT-4o-mini 理解并总结内容
  3. 对于图片附件：使用 GPT-4o vision 解读图片并生成文字描述
  4. 将 summary_content JSON 对象写回数据库

输出： 存储在上传项上的 summary_content JSON 记录，包含 AI 生成的内容理解。

Analyze Worker

SQS 队列： inklet-analyzer

按计划定时触发。该 Worker 运行一个自主 AI 代理，决定将什么内容推送到哪些设备。

触发条件： 定时调度（reason: SCHEDULED）或 API 手动触发（reason: MANUAL）

手动触发： POST /api/analyze/trigger（需要认证）— 为当前用户加入分析队列。

响应： {"status": "queued"}

代理架构：

该 Worker 使用 OpenAI Agents SDK 运行代理循环。代理被赋予一组工具，并根据用户的内容和设备自主决定操作。

可用工具：

工具 描述
list_notes 列出用户上传的笔记
read_note_content 读取特定笔记的完整内容和摘要
list_templates 列出可用的渲染模板
get_template_detail 获取模板的元数据和预览
get_template_schema 获取模板输入变量的 JSON schema
list_devices 列出用户绑定的设备
get_push_history 获取设备的最近推送历史
create_push 创建一条指向特定设备的新推送记录

行为：

代理自主完成以下操作：

  1. 查看用户最近的笔记及其摘要
  2. 检查可用模板及其 schema
  3. 确认有哪些设备可用及其推送历史
  4. 决定使用哪个模板将哪些内容推送到哪个设备
  5. 调用 create_push，传入选定的模板、输入变量和目标设备

create_push 工具创建一条 PREPARE 状态的推送记录，并向 Render Worker 发送一条消息入队。

Render Worker

SQS 队列： inklet-render

当 Analyze Worker 的 create_push 工具创建推送记录时触发。该 Worker 将内容渲染为适合电子墨水屏显示的位图图片。

触发条件： Analyze Worker 的 create_push，或通过 POST /api/devices/{id}/custom-push/confirm 创建的自定义图片推送

处理流程：

  1. 获取源像素：
    • HTML 模板： 加载 Jinja2 模板，用 task 的 params 渲染为 HTML，再 HTML → PDF（WeasyPrint）→ PNG
    • __custom_image__ 模板： 从 S3 下载用户上传的图片（根据 render task params 中的 fileId）——不做 HTML 渲染
  2. 缩放到设备分辨率（800×480），生成三种位图变体：
    • image.png — 1-bit Floyd–Steinberg 抖动 PNG
    • image2.raw — 1 bpp 打包位图（48000 字节）
    • image4.raw — 2 bpp 打包位图，4 级灰度（96000 字节）
  3. 将三个文件上传到 S3 的 render/{userId}/{deviceId}/{pushId}/ 下
  4. 创建指向 image.png 的文件记录
  5. 将推送状态从 PREPARE 更新为 QUEUE

输出： S3 中的三种渲染位图，以及处于 QUEUE 状态的推送记录，设备可按需下载对应格式。

推送生命周期

每条推送记录经历四个状态转换：

stateDiagram-v2
    [*] --> PREPARE : create_push
    PREPARE --> QUEUE : 渲染完成
    QUEUE --> PUBLISHED : 设备请求推送
    PUBLISHED --> CONFIRMED : 设备确认显示
状态 描述
PREPARE 推送记录已创建；渲染进行中
QUEUE 渲染完成；位图已就绪，可供设备下载
PUBLISHED 推送 URL 已发送给设备（通过 API 或 MQTT）
CONFIRMED 设备已确认推送已在屏幕上显示

设备通过 GET /api/devices/{id}/push 接口或 IoT 协议页面中的 get_push / refresh_push MQTT 主题获取推送。