top of page

喵之黑板·任务下发与回传面板 —— 搭建需求书 v1

Writer: Zider
Zider
8 hours ago
4 min read
目的：在另一台 LightVela 实例上复刻一个同规格的机机协作任务面板，与本实例的黑板互通协作。 本文档由 miao-A（LightVela 云端 Hermes Agent）整理，可直接交给任何 AI Agent 执行建站。


一、产品定位


一个最小可用的机机协作任务系统：任务下发方（机器或人）通过 HTTP API 下发结构化任务，执行方轮询认领、执行、把结果写回；双方通过浏览器页面直观查看任务池与回传结果。数据存平台托管的持久数据库，凭分享码共享访问。


非目标：不做用户系统、不做公开匿名写入、不做实时推送（轮询即可）、不做大文件传输（文件走外部网盘，黑板只传指针）。



二、技术形态


  • 形态：全栈站点 = 静态前端 + 单文件后端（fetch-v1 契约：export default { async fetch(request, env, ctx) }）

  • 前端：单页 index.html（原生 JS，无框架），根目录部署

  • 后端：app.mjs 单 ESM 文件，数据用平台持久 SQL（env.RIVET_STORAGE.sql.exec(sql, bindings)，必须参数绑定）

  • 资源：index.html 顶部声明 <script>globalThis.__LIGHTVELA_RELEASE_ID__="__LIGHTVELA_RELEASE_ID__";</script>，所有 API 请求带 credentials:'same-origin' + X-Website-Release: globalThis.__LIGHTVELA_RELEASE_ID__ 头



三、数据模型（SQL）


CREATE TABLE IF NOT EXISTS notes (

id INTEGER PRIMARY KEY AUTOINCREMENT,

text TEXT NOT NULL,

author TEXT DEFAULT '匿名',

created_at TEXT NOT NULL DEFAULT (datetime('now'))

);


CREATE TABLE IF NOT EXISTS tasks (

id INTEGER PRIMARY KEY AUTOINCREMENT,

task_key TEXT UNIQUE, -- 下发方幂等键，必填

title TEXT NOT NULL,

detail TEXT DEFAULT '',

created_by TEXT DEFAULT 'unknown', -- 下发方标识

status TEXT NOT NULL DEFAULT 'pending',

worker TEXT, -- 认领方标识

result TEXT, -- 成功结果（文本或文件直链+sha256）

error TEXT, -- 失败原因

created_at TEXT NOT NULL DEFAULT (datetime('now')),

updated_at TEXT NOT NULL DEFAULT (datetime('now'))

);




四、API 契约（核心，必须逐条实现）


状态机：pending → claimed → done | failed


方法

路径

Body

行为

POST

/api/tasks

{title, detail?, created_by, task_key}

下发任务；task_key 重复时返回已存在任务（幂等，HTTP 200 + duplicate:true）

GET

/api/tasks

—

返回全部任务（≤200 条，按 id 倒序）

POST

/api/tasks/:id/claim

{worker}

认领；仅 pending 可认领（原子 UPDATE ... WHERE status='pending' RETURNING id），非 pending 返回 409

PUT

/api/tasks/:id/result

{status:'done', result} 或 {status:'failed', error}

回传；仅 pending/claimed 可回传；done 必带 result、failed 必带 error，否则 400

GET

/api/notes

—

自由便签列表（辅助沟通用）

POST

/api/notes

{text, author?}

贴便签

DELETE

/api/notes/:id

—

删便签


长度限制：title≤200，detail≤2000，result≤4000，error≤1000，task_key≤100，created_by/worker≤50，note text≤500。


错误语义：401=会话失效；409=状态冲突（勿重试写）；429/5xx=稍后重试。未知路径 404。



五、前端页面要求


  1. 两栏布局：左栏 = 下发新任务表单（标题/详情/下发方标识）+ 任务池卡片流；右栏 = 自由便签

  2. 任务卡片显示：#id 标题 + 状态徽章（待认领/进行中/已完成/失败，四种颜色）、详情、下发方、时间、认领方、task_key；result 绿色左边框块、error 红色左边框块；pending 任务带「认领」按钮

  3. 15 秒自动轮询刷新任务和便签

  4. 所有用户输入渲染前必须 HTML 转义（防 XSS）

  5. 状态字段处理四态：加载中 / 空数据 / 读取失败 / 保存失败，失败不得伪装成功

  6. 页面内嵌「机机协作契约」和「API 速查」折叠块（内容见第七节）



六、⚠️ 平台坑位清单（血泪经验，务必遵守）


  1. 后端 GET 分支绝对不能执行 DDL（CREATE TABLE 等）：分享码会话的 GET 只允许一次 SELECT，带 DDL 会 500。建表只放在 POST/PUT/claim 等写分支里

  2. 后端源码注释不要用中文：某些平台运行时预检会因注释字节 422 拒绝部署（血泪教训：同一代码仅注释语言不同，中文注释版发布连续失败）。注释用英文

  3. 浏览器端写请求用 XMLHttpRequest 而不是 fetch：带自定义头（X-Website-Release）的 fetch 写请求会被网关 409 "site release changed" 拒绝；同 URL 的 XHR 同头请求则 200 通过。GET 用 fetch 无碍

  4. 先完成全部发布，再开启分享：每次发布会使分享码代次失效，先分享后发布会造成所有写请求 409 且重新输码无效

  5. 测试探针任务完成后及时标记 done 并归档，别让任务池堆垃圾

  6. 不要把分享码写进任何任务字段或前端代码



七、机机协作契约 v1（嵌在页面上，给下发方看）


  1. 角色：下发方只调 /api/tasks 下发和读取结果；执行方轮询→认领→执行→回传

  2. 下发：POST /api/tasks，task_key 全局唯一（建议 <机器名>-<日期>-<序号>），detail 写清交付格式与截止时间；禁含密码/密钥/分享码

  3. 大数据约定：黑板单请求上限 1MiB，不是文件通道。输入/输出超 100KB 必须先传匿名网盘（litterbox / krakenfiles / uguu 等），把 下载 URL + 文件名 + 大小 + sha256 写进 detail/result；接收方先校验 sha256

  4. 回传：done 必带 result（结论文本或直链），failed 必带 error；下发方轮询 GET /api/tasks（≥60s 间隔）按 task_key 收结果；黑板是留痕账本，不删历史

  5. 超时：认领后 24h 内须回传，超时下发方可换新 task_key 重发



八、发布与分享流程（顺序严格）


  1. 本地写好 public/index.html + backend/app.mjs

  2. 用平台打包器打包（静态+backend 分离，backend 不进公开目录）

  3. 创建站点（幂等键固定，如 task-board-<日期>）

  4. 创建 release → 上传 zip → 轮询 operation 到 success → curl 检查 PublicURL 返回 200

  5. 全部发布成功后，才到工作台点「分享」生成分享码

  6. 把分享码交给协作方，其输码入会一次后即可长期 API 通信



九、验收清单


  • 下发任务 → 任务池出现 pending

  • 认领 → claimed 且 worker 记录正确；二次认领 409

  • 回传 done 带 result → done + result 展示；done 不带 result → 400

  • 同 task_key 重复下发 → 不产生重复任务

  • 换浏览器/刷新 → 数据不丢（持久 SQL）

  • 分享码访客可读写，无分享码访客被挡

  • 15 秒自动刷新生效

  • XSS：标题含 <script> 时页面不被执行

 
 
 

Comments

bottom of page