xianyan/docs/toolsapi/docs/API_READLATER_FONT_PLUGIN_DOC.md

闲言APP — 稍后读/字体同步/插件更新 API 接口文档

• 创建时间: 2026-06-01
• 更新时间: 2026-06-01
• 作用: 稍后读同步+协作+AI摘要、字体同步、插件更新 REST API接口文档
• 上次更新: v10.0.0 新建文档，包含Readlater/FontSync/PluginUpdate三个模块
• 关联文档: API_ADMIN_DOC.md

---

一、概述

本文档包含三个独立模块的API接口：

模块	基础URL	说明
稍后读(Readlater)	https://tools.wktyl.com/api/readlater/	稍后读消息同步、共享协作、AI摘要
字体同步(FontSync)	https://tools.wktyl.com/api/font_sync/	在线字体列表获取
插件更新(PluginUpdate)	https://tools.wktyl.com/api/plugin_update/	插件版本检查与状态同步

通用约定:

项目	说明
协议	HTTPS
字符编码	UTF-8
时间格式	Unix时间戳(毫秒)
响应格式	JSON
认证	部分接口需登录(Token)

通用请求头:

Header	必填	说明
Content-Type	是	application/json
token	部分	用户登录Token(需登录接口必填)

通用响应格式:

{
    "code": 1,
    "msg": "ok",
    "time": "1715234567",
    "data": { ... }
}

字段	类型	说明
code	int	1=成功, 0=失败
msg	string	消息
time	string	服务器时间戳
data	object/array	业务数据

---

模块一：稍后读同步+协作+AI摘要 (Readlater)

• 基础URL: https://tools.wktyl.com/api/readlater/
• 认证: 同步/协作/AI摘要接口需登录，安装接口无需登录

二、安装数据库表

POST /api/readlater/install

首次部署时调用，创建稍后读相关表（tool_readlater_messages、tool_readlater_shared_lists、tool_readlater_shared_members、tool_readlater_shared_messages）。

请求参数: 无

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "tables": [
            "tool_readlater_messages",
            "tool_readlater_shared_lists",
            "tool_readlater_shared_members",
            "tool_readlater_shared_messages"
        ],
        "created": true
    }
}

字段	类型	说明
tables	array	创建的表名列表
created	bool	是否创建成功

---

三、同步接口（需登录）

3.1 上传稍后读消息

POST /api/readlater/upload

上传一条稍后读消息至云端。

请求参数:

字段	类型	必填	说明
message_id	string	是	客户端消息唯一ID(UUID)
type	string	是	消息类型(text/url/image/note/article)
content	string	是	消息内容
meta_json	string	否	元数据JSON(标题/来源/封面等)
tags	string	否	标签(逗号分隔)
created_at	long	否	客户端创建时间(毫秒)，默认当前时间

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "message_id": "rl_a1b2c3d4e5f6",
        "server_id": 1001,
        "synced_at": 1715234567000
    }
}

字段	类型	说明
message_id	string	消息唯一ID
server_id	int	服务端记录ID
synced_at	long	同步时间(毫秒)

错误响应 (消息已存在):

{
    "code": 409,
    "msg": "消息已存在",
    "data": null
}

---

3.2 下载所有稍后读消息

GET /api/readlater/download

下载当前用户的所有稍后读消息。

请求参数:

参数	类型	必填	说明
since	long	否	增量同步时间戳(毫秒)，不传则返回全部
limit	int	否	每页条数，默认100，最大500
offset	int	否	偏移量，默认0

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "total": 25,
        "has_more": false,
        "items": [
            {
                "message_id": "rl_a1b2c3d4e5f6",
                "type": "url",
                "content": "https://example.com/article/123",
                "meta_json": "{\"title\":\"示例文章\",\"source\":\"web\"}",
                "tags": "技术,前端",
                "created_at": 1715234567000,
                "updated_at": 1715234567000,
                "is_deleted": false
            }
        ]
    }
}

字段	类型	说明
total	int	总消息数
has_more	bool	是否还有更多数据
items	array	消息列表
items[].message_id	string	消息唯一ID
items[].type	string	消息类型
items[].content	string	消息内容
items[].meta_json	string	元数据JSON
items[].tags	string	标签
items[].created_at	long	创建时间(毫秒)
items[].updated_at	long	更新时间(毫秒)
items[].is_deleted	bool	是否已删除(软删除标记)

---

3.3 删除指定消息

POST /api/readlater/delete

删除指定的稍后读消息（软删除）。

请求参数:

字段	类型	必填	说明
message_id	string	是	消息唯一ID

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "message_id": "rl_a1b2c3d4e5f6",
        "deleted_at": 1715234999000
    }
}

字段	类型	说明
message_id	string	已删除的消息ID
deleted_at	long	删除时间(毫秒)

错误响应 (消息不存在):

{
    "code": 404,
    "msg": "消息不存在",
    "data": null
}

---

3.4 全量同步

POST /api/readlater/fullSync

客户端上传本地所有消息，服务端对比后返回差异，实现双向同步。

请求参数:

字段	类型	必填	说明
messages	array	是	本地所有消息列表
messages[].message_id	string	是	消息唯一ID
messages[].type	string	是	消息类型
messages[].content	string	是	消息内容
messages[].meta_json	string	否	元数据JSON
messages[].tags	string	否	标签
messages[].created_at	long	否	创建时间(毫秒)
messages[].updated_at	long	否	更新时间(毫秒)
messages[].is_deleted	bool	否	是否已删除
last_sync_time	long	否	上次同步时间(毫秒)

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "sync_time": 1715234999000,
        "server_only": [
            {
                "message_id": "rl_x1y2z3",
                "type": "text",
                "content": "服务端新增消息",
                "meta_json": "",
                "tags": "",
                "created_at": 1715234800000,
                "updated_at": 1715234800000,
                "is_deleted": false
            }
        ],
        "need_upload": [
            "rl_a1b2c3d4e5f6",
            "rl_d5e6f7g8h9i0"
        ],
        "conflicts": []
    }
}

字段	类型	说明
sync_time	long	本次同步时间(毫秒)，客户端需保存
server_only	array	服务端有但客户端没有的消息(需下载)
need_upload	array	客户端有但服务端没有的消息ID(需上传)
conflicts	array	冲突消息列表(两端都修改了同一条)

---

四、协作接口（需登录）

4.1 创建共享列表

POST /api/readlater/createSharedList

创建一个稍后读共享列表，创建者自动成为列表拥有者。

请求参数:

字段	类型	必填	说明
name	string	是	列表名称
description	string	否	列表描述
icon_emoji	string	否	列表图标emoji，默认📚

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "list_id": "sl_abc123def456",
        "name": "前端技术文章",
        "description": "团队共享的前端技术文章",
        "icon_emoji": "📖",
        "owner_id": 1001,
        "member_count": 1,
        "created_at": 1715234567000
    }
}

字段	类型	说明
list_id	string	共享列表唯一ID
name	string	列表名称
description	string	列表描述
icon_emoji	string	列表图标
owner_id	int	拥有者用户ID
member_count	int	当前成员数
created_at	long	创建时间(毫秒)

---

4.2 邀请成员

POST /api/readlater/inviteMember

邀请其他用户加入共享列表。

请求参数:

字段	类型	必填	说明
list_id	string	是	共享列表ID
user_id	int	是	被邀请用户ID
role	string	否	角色(member/admin)，默认member

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "list_id": "sl_abc123def456",
        "user_id": 2002,
        "role": "member",
        "joined_at": 1715234567000
    }
}

字段	类型	说明
list_id	string	共享列表ID
user_id	int	被邀请用户ID
role	string	成员角色
joined_at	long	加入时间(毫秒)

错误响应 (已是成员):

{
    "code": 409,
    "msg": "该用户已是列表成员",
    "data": null
}

---

4.3 分享消息到共享列表

POST /api/readlater/shareMessage

将一条稍后读消息分享到指定共享列表。

请求参数:

字段	类型	必填	说明
list_id	string	是	共享列表ID
message_id	string	是	稍后读消息ID
note	string	否	分享备注

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "shared_message_id": "sm_xyz789",
        "list_id": "sl_abc123def456",
        "message_id": "rl_a1b2c3d4e5f6",
        "shared_by": 1001,
        "shared_at": 1715234567000
    }
}

字段	类型	说明
shared_message_id	string	共享消息记录ID
list_id	string	共享列表ID
message_id	string	原始消息ID
shared_by	int	分享者用户ID
shared_at	long	分享时间(毫秒)

---

4.4 获取共享列表消息

GET /api/readlater/listMessages

获取指定共享列表的所有消息。

请求参数:

参数	类型	必填	说明
list_id	string	是	共享列表ID
limit	int	否	每页条数，默认50
offset	int	否	偏移量，默认0

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "total": 12,
        "has_more": false,
        "items": [
            {
                "shared_message_id": "sm_xyz789",
                "message_id": "rl_a1b2c3d4e5f6",
                "type": "url",
                "content": "https://example.com/article/123",
                "meta_json": "{\"title\":\"示例文章\"}",
                "shared_by": 1001,
                "shared_by_name": "张三",
                "note": "这篇不错",
                "shared_at": 1715234567000
            }
        ]
    }
}

字段	类型	说明
total	int	总消息数
has_more	bool	是否还有更多
items	array	消息列表
items[].shared_message_id	string	共享消息记录ID
items[].message_id	string	原始消息ID
items[].shared_by	int	分享者用户ID
items[].shared_by_name	string	分享者昵称
items[].note	string	分享备注
items[].shared_at	long	分享时间(毫秒)

---

4.5 获取我参与的共享列表

GET /api/readlater/myLists

获取当前用户参与的所有共享列表。

请求参数: 无

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": [
        {
            "list_id": "sl_abc123def456",
            "name": "前端技术文章",
            "description": "团队共享的前端技术文章",
            "icon_emoji": "📖",
            "owner_id": 1001,
            "owner_name": "张三",
            "member_count": 5,
            "message_count": 12,
            "role": "owner",
            "created_at": 1715234567000,
            "last_active_at": 1715234999000
        }
    ]
}

字段	类型	说明
list_id	string	共享列表ID
name	string	列表名称
description	string	列表描述
icon_emoji	string	列表图标
owner_id	int	拥有者ID
owner_name	string	拥有者昵称
member_count	int	成员数
message_count	int	消息数
role	string	当前用户角色(owner/admin/member)
created_at	long	创建时间(毫秒)
last_active_at	long	最后活跃时间(毫秒)

---

4.6 退出共享列表

POST /api/readlater/leaveList

退出指定的共享列表。拥有者不可退出，需先转让或删除列表。

请求参数:

字段	类型	必填	说明
list_id	string	是	共享列表ID

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "list_id": "sl_abc123def456",
        "left_at": 1715234999000
    }
}

字段	类型	说明
list_id	string	退出的列表ID
left_at	long	退出时间(毫秒)

错误响应 (拥有者不可退出):

{
    "code": 403,
    "msg": "拥有者不可退出，请先转让或删除列表",
    "data": null
}

---

五、AI摘要接口（需登录）

5.1 生成单条摘要

POST /api/readlater/generateSummary

为指定稍后读消息生成AI摘要。

请求参数:

字段	类型	必填	说明
message_id	string	是	稍后读消息ID
force	bool	否	是否强制重新生成，默认false

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "message_id": "rl_a1b2c3d4e5f6",
        "summary": "本文介绍了Flutter状态管理的最佳实践，包括Provider、Riverpod和Bloc的对比分析。",
        "key_points": [
            "Provider适合中小型项目",
            "Riverpod是Provider的进化版",
            "Bloc适合大型复杂项目"
        ],
        "generated_at": 1715234567000
    }
}

字段	类型	说明
message_id	string	消息ID
summary	string	AI生成的摘要
key_points	array	关键要点列表
generated_at	long	生成时间(毫秒)

---

5.2 批量摘要

POST /api/readlater/batchSummarize

批量生成多条消息的摘要。

请求参数:

字段	类型	必填	说明
message_ids	array	是	消息ID列表(最多20条)
force	bool	否	是否强制重新生成，默认false

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "total": 3,
        "results": [
            {
                "message_id": "rl_a1b2c3d4e5f6",
                "summary": "Flutter状态管理最佳实践...",
                "key_points": ["要点1", "要点2"],
                "generated_at": 1715234567000
            },
            {
                "message_id": "rl_d5e6f7g8h9i0",
                "summary": "iOS 26设计规范解读...",
                "key_points": ["要点1", "要点2"],
                "generated_at": 1715234567000
            }
        ],
        "failed": []
    }
}

字段	类型	说明
total	int	成功生成摘要数
results	array	摘要结果列表
failed	array	生成失败的消息ID列表

---

5.3 每日摘要

POST /api/readlater/dailySummary

生成指定日期的稍后读消息汇总摘要。

请求参数:

字段	类型	必填	说明
date	string	否	日期(YYYY-MM-DD)，默认今天
category	string	否	按类型筛选(text/url/image/note/article)

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "date": "2026-06-01",
        "total_messages": 8,
        "summary": "今日收藏了8条内容，主要集中在前端技术(3条)、产品设计(2条)、杂项(3条)。",
        "categories": [
            {
                "type": "url",
                "count": 5,
                "highlights": ["Flutter状态管理", "iOS 26设计规范", "CSS Grid布局"]
            },
            {
                "type": "text",
                "count": 3,
                "highlights": ["会议纪要", "灵感记录"]
            }
        ],
        "generated_at": 1715234567000
    }
}

字段	类型	说明
date	string	摘要日期
total_messages	int	当日消息总数
summary	string	AI生成的每日汇总
categories	array	按类型分类统计
categories[].type	string	消息类型
categories[].count	int	该类型消息数
categories[].highlights	array	该类型重点内容
generated_at	long	生成时间(毫秒)

---

5.4 标签建议

POST /api/readlater/suggestTags

为指定消息生成AI标签建议。

请求参数:

字段	类型	必填	说明
message_id	string	是	稍后读消息ID
max_tags	int	否	最多返回标签数，默认5

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "message_id": "rl_a1b2c3d4e5f6",
        "suggested_tags": ["Flutter", "状态管理", "前端开发", "Provider", "Riverpod"],
        "generated_at": 1715234567000
    }
}

字段	类型	说明
message_id	string	消息ID
suggested_tags	array	AI建议的标签列表
generated_at	long	生成时间(毫秒)

---

六、Readlater 错误码

HTTP状态码	code	说明
200	1	成功
400	0	参数错误
401	0	未登录/Token无效
403	0	无权限(如拥有者不可退出列表)
404	0	消息/列表不存在
409	0	冲突(消息已存在/已是成员)
429	0	请求过于频繁(AI接口限流)
500	0	服务器内部错误

---

模块二：字体同步 (FontSync)

• 基础URL: https://tools.wktyl.com/api/font_sync/
• 认证: 所有接口无需登录

七、安装数据库表

POST /api/font_sync/install

首次部署时调用，创建 tool_fonts 表。

请求参数: 无

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "table": "tool_fonts",
        "created": true,
        "exists": false
    }
}

字段	类型	说明
table	string	创建的表名
created	bool	是否创建成功
exists	bool	表是否已存在

---

八、获取在线字体列表

GET /api/font_sync/list

获取所有可用的在线字体列表。

请求参数:

参数	类型	必填	说明
category	string	否	按分类筛选(sans/serif/mono/display/handwriting)
platform	string	否	按平台筛选(android/ios/web/ohos)
is_active	int	否	是否只返回启用的字体(1)，默认1

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": [
        {
            "id": 1,
            "name": "思源黑体",
            "font_family": "Noto Sans SC",
            "download_url": "https://cdn.example.com/fonts/NotoSansSC-Regular.ttf",
            "icon_emoji": "🔤",
            "author": "Google",
            "license": "SIL Open Font License 1.1",
            "category": "sans",
            "tags": "中文,黑体,无衬线",
            "file_size": 8388608,
            "sort_order": 1,
            "is_active": 1,
            "created_at": 1715234567000,
            "updated_at": 1715234567000
        }
    ]
}

字段	类型	说明
id	int	字体ID
name	string	字体名称
font_family	string	字体族(CSS font-family)
download_url	string	字体下载地址
icon_emoji	string	图标emoji
author	string	作者
license	string	许可证
category	string	分类(sans/serif/mono/display/handwriting)
tags	string	标签(逗号分隔)
file_size	int	文件大小(字节)
sort_order	int	排序
is_active	int	是否启用(1/0)
created_at	long	创建时间(毫秒)
updated_at	long	更新时间(毫秒)

---

九、FontSync 错误码

HTTP状态码	code	说明
200	1	成功
400	0	参数错误
500	0	服务器内部错误

---

模块三：插件更新 (PluginUpdate)

• 基础URL: https://tools.wktyl.com/api/plugin_update/
• 认证: check/checkAll/install无需登录，syncState/loadState需登录

十、安装数据库表

POST /api/plugin_update/install

首次部署时调用，创建 tool_plugin_meta 和 tool_plugin_user_settings 表。

请求参数: 无

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "tables": [
            "tool_plugin_meta",
            "tool_plugin_user_settings"
        ],
        "created": true
    }
}

字段	类型	说明
tables	array	创建的表名列表
created	bool	是否创建成功

---

十一、检查单个插件更新

GET /api/plugin_update/check

检查指定插件是否有新版本。

请求参数:

参数	类型	必填	说明
plugin_id	string	是	插件ID
current_version	string	是	当前版本号
platform	string	是	平台(android/ios/web/ohos)

响应示例 (有更新):

{
    "code": 1,
    "msg": "ok",
    "data": {
        "plugin_id": "com.xianyan.readlater",
        "has_update": true,
        "latest_version": "2.1.0",
        "current_version": "2.0.0",
        "name": "稍后读",
        "description": "稍后读消息同步与AI摘要",
        "icon_url": "https://cdn.example.com/plugins/readlater/icon.png",
        "preview_urls": [
            "https://cdn.example.com/plugins/readlater/preview1.png",
            "https://cdn.example.com/plugins/readlater/preview2.png"
        ],
        "download_url": "https://cdn.example.com/plugins/readlater-2.1.0.apk",
        "changelog": "1. 新增AI摘要功能\n2. 修复同步问题\n3. 优化性能",
        "min_app_version": "10.0.0",
        "file_size": 5242880,
        "released_at": 1715234567000
    }
}

响应示例 (无更新):

{
    "code": 1,
    "msg": "ok",
    "data": {
        "plugin_id": "com.xianyan.readlater",
        "has_update": false,
        "latest_version": "2.0.0",
        "current_version": "2.0.0"
    }
}

字段	类型	说明
plugin_id	string	插件ID
has_update	bool	是否有更新
latest_version	string	最新版本号
current_version	string	当前版本号
name	string	插件名称(仅has_update=true时返回)
description	string	插件描述(仅has_update=true时返回)
icon_url	string	图标URL(仅has_update=true时返回)
preview_urls	array	预览图URL列表(仅has_update=true时返回)
download_url	string	下载地址(仅has_update=true时返回)
changelog	string	更新日志(仅has_update=true时返回)
min_app_version	string	最低应用版本(仅has_update=true时返回)
file_size	int	文件大小(字节，仅has_update=true时返回)
released_at	long	发布时间(毫秒，仅has_update=true时返回)

---

十二、检查所有插件更新

GET /api/plugin_update/checkAll

批量检查多个插件是否有更新。

请求参数:

参数	类型	必填	说明
plugins	string	是	JSON数组，包含插件信息
platform	string	是	平台(android/ios/web/ohos)

plugins 参数格式示例:

[
    {"plugin_id": "com.xianyan.readlater", "current_version": "2.0.0"},
    {"plugin_id": "com.xianyan.fontsync", "current_version": "1.0.0"}
]

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "updates": [
            {
                "plugin_id": "com.xianyan.readlater",
                "has_update": true,
                "latest_version": "2.1.0",
                "current_version": "2.0.0",
                "name": "稍后读",
                "changelog": "1. 新增AI摘要功能",
                "download_url": "https://cdn.example.com/plugins/readlater-2.1.0.apk",
                "file_size": 5242880
            }
        ],
        "no_updates": [
            {
                "plugin_id": "com.xianyan.fontsync",
                "has_update": false,
                "latest_version": "1.0.0",
                "current_version": "1.0.0"
            }
        ]
    }
}

字段	类型	说明
updates	array	有更新的插件列表
no_updates	array	无更新的插件列表

---

十三、同步插件状态（需登录）

POST /api/plugin_update/syncState

将客户端插件安装状态同步至云端，用于跨设备同步。

请求参数:

字段	类型	必填	说明
states	array	是	插件状态列表
states[].plugin_id	string	是	插件ID
states[].installed_version	string	是	已安装版本号
states[].is_enabled	bool	否	是否启用，默认true
states[].installed_at	long	否	安装时间(毫秒)

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "synced": 3,
        "sync_time": 1715234567000
    }
}

字段	类型	说明
synced	int	同步的插件数量
sync_time	long	同步时间(毫秒)

---

十四、加载插件状态（需登录）

GET /api/plugin_update/loadState

从云端加载用户所有插件的安装状态，用于跨设备恢复。

请求参数: 无

响应示例:

{
    "code": 1,
    "msg": "ok",
    "data": {
        "sync_time": 1715234567000,
        "states": [
            {
                "plugin_id": "com.xianyan.readlater",
                "installed_version": "2.1.0",
                "is_enabled": true,
                "installed_at": 1715230000000
            },
            {
                "plugin_id": "com.xianyan.fontsync",
                "installed_version": "1.0.0",
                "is_enabled": true,
                "installed_at": 1715220000000
            }
        ]
    }
}

字段	类型	说明
sync_time	long	最后同步时间(毫秒)
states	array	插件状态列表
states[].plugin_id	string	插件ID
states[].installed_version	string	已安装版本号
states[].is_enabled	bool	是否启用
states[].installed_at	long	安装时间(毫秒)

---

十五、PluginUpdate 错误码

HTTP状态码	code	说明
200	1	成功
400	0	参数错误
401	0	未登录/Token无效
404	0	插件不存在
500	0	服务器内部错误

---

十六、验证状态

验证项	结果	验证时间	备注
Readlater安装 /install	⏳ 待验证	-	tool_readlater_messages等4表
上传消息 /upload	⏳ 待验证	-
下载消息 /download	⏳ 待验证	-
删除消息 /delete	⏳ 待验证	-
全量同步 /fullSync	⏳ 待验证	-
创建共享列表 /createSharedList	⏳ 待验证	-
邀请成员 /inviteMember	⏳ 待验证	-
分享消息 /shareMessage	⏳ 待验证	-
列表消息 /listMessages	⏳ 待验证	-
我的列表 /myLists	⏳ 待验证	-
退出列表 /leaveList	⏳ 待验证	-
生成摘要 /generateSummary	⏳ 待验证	-
批量摘要 /batchSummarize	⏳ 待验证	-
每日摘要 /dailySummary	⏳ 待验证	-
标签建议 /suggestTags	⏳ 待验证	-
FontSync安装 /install	⏳ 待验证	-	tool_fonts表
字体列表 /list	⏳ 待验证	-
PluginUpdate安装 /install	⏳ 待验证	-	tool_plugin_meta等2表
检查更新 /check	⏳ 待验证	-
批量检查 /checkAll	⏳ 待验证	-
同步状态 /syncState	⏳ 待验证	-
加载状态 /loadState	⏳ 待验证	-

关联文档: 管理员端接口详见 API_ADMIN_DOC.md