{"name":"knasync","description":"knasync 中继 API — 远程剪贴板 / 内容队列分发系统，基于 Cloudflare Workers + D1 数据库","baseUrls":["https://knasync.yuanguangshan.workers.dev","https://knasync.want.biz"],"authHeader":"X-Auth-Key","authExample":"X-Auth-Key: <your-secret-key>","authNote":"受保护接口支持 X-Auth-Key 请求头或 ?key= 查询参数两种鉴权方式","queues":[{"name":"zhihu","consumers":["Chrome 扩展"],"max":50,"desc":"知乎链接队列，供 Chrome 扩展消费"},{"name":"wechat","consumers":[],"max":50,"desc":"微信文章队列"},{"name":"general","consumers":["Knowly 守护进程"],"max":50,"desc":"通用队列，供 Knowly 消费"}],"endpoints":[{"section":1,"title":"提交内容","subtitle":"手机 / 外部来源 → 输入队列","path":"/submit","method":"POST","auth":true,"description":"将链接或文本提交至中继，自动识别知乎链接并分流至对应队列。","contentType":"application/json 或 text/plain","requestBody":[{"format":"JSON（推荐）","fields":[{"name":"content","type":"string","desc":"你要提交的内容"},{"name":"url","type":"string","desc":"也支持 url 字段，如 https://mp.weixin.qq.com/s/abc"},{"name":"queue","type":"string","desc":"可选，指定队列：zhihu / wechat / general"}],"example":"{ \"content\": \"https://www.zhihu.com/question/123456/answer/789012\" }"},{"format":"纯文本","fields":[],"example":"https://www.zhihu.com/question/123456/answer/789012"}],"example":"curl -X POST https://knasync.yuanguangshan.workers.dev/submit -H \"Content-Type: application/json\" -H \"X-Auth-Key: <your-secret-key>\" -d '{\"content\":\"https://zhuanlan.zhihu.com/p/123456\"}'","response":{"status":200,"body":"OK (zhihu)","note":"返回分流结果：OK (zhihu) 或 OK (general)"},"rules":["知乎链接 → 写入 zhihu 队列（供 Chrome 扩展消费）","其他链接或纯文本 → 写入 general 队列（供 Knowly 消费）","每个队列最多 50 条，超出时自动删除最旧记录","5 分钟内容去重（基于内容精确匹配）"],"errors":[{"status":400,"desc":"内容为空"}]},{"section":2,"title":"拉取待处理任务","subtitle":"消费者拉取输入队列","path":"/pull","method":"GET","auth":true,"description":"消费者轮询拉取属于自己的任务，读取后队列立即清空。","params":[{"name":"queue","type":"string","required":false,"desc":"队列名称：zhihu / wechat / general，也兼容带 queue_ 前缀的写法（如 queue_zhihu）。不传时按旧版逻辑（先拉知乎，再拉微信，再拉通用）"}],"example":"curl \"https://knasync.yuanguangshan.workers.dev/pull?queue=zhihu\" -H \"X-Auth-Key: <your-secret-key>\"","response":{"status":200,"body":["https://www.zhihu.com/question/...","https://zhuanlan.zhihu.com/p/..."],"note":"按提交时间升序排列的 JSON 数组"},"emptyResponse":{"status":204,"desc":"No Content — 队列为空"},"consumers":["Chrome 扩展：GET /pull?queue=zhihu","Knowly 守护进程：GET /pull?queue=general"],"errors":[{"status":400,"desc":"队列名称无效"}]},{"section":3,"title":"查看队列（只读）","subtitle":"浏览器查看待处理任务","path":"/peek","method":"GET","auth":true,"description":"只读查看队列内容，不删除任何记录。不传 queue 时返回所有队列。支持浏览器地址栏直接访问。","params":[{"name":"queue","type":"string","required":false,"desc":"队列名称：zhihu / wechat / general。不传时返回全部队列"}],"example":"https://knasync.yuanguangshan.workers.dev/peek?key=<your-secret-key>","response":{"status":200,"body":{"total":5,"queues":{"zhihu":[{"content":"https://...","queue_type":"zhihu","created_at":"2024-05-07 12:00:00"}],"wechat":[],"general":[{"content":"some text","queue_type":"general","created_at":"2024-05-07 12:05:05"}]}},"note":"按队列分组，每组按提交时间升序排列"},"emptyResponse":{"status":204,"desc":"No Content — 所有队列均为空"},"errors":[{"status":400,"desc":"队列名称无效"}]},{"section":4,"title":"推送处理结果","subtitle":"消费者 → 广播结果队列","path":"/push","method":"POST","auth":true,"description":"消费者将处理后的成品（如 Markdown 正文、AI 摘要）推送到结果队列，供其他客户端广播拉取。","contentType":"application/json 或 text/plain","requestBody":[{"format":"JSON","fields":[{"name":"content","type":"string","desc":"处理结果内容，如 Markdown 正文、AI 摘要"}],"example":"{ \"content\": \"# 文章标题\\n\\n正文内容（Markdown）...\" }"}],"example":"curl -X POST https://knasync.yuanguangshan.workers.dev/push -H \"Content-Type: application/json\" -H \"X-Auth-Key: <your-secret-key>\" -d '{\"content\":\"# 某篇文章\\n\\n正文...\"}'","response":{"status":200,"body":"OK"},"rules":["结果队列 results 最多 50 条，超出时自动删除最旧记录","支持多客户端通过 /results 游标拉取（广播效果）"],"errors":[{"status":400,"desc":"内容为空"}]},{"section":5,"title":"获取广播结果","subtitle":"所有客户端均可读取","path":"/results","method":"GET","auth":true,"description":"增量拉取处理后的结果内容，支持游标。","params":[{"name":"since","type":"number","required":false,"desc":"时间戳，只返回此时间之后的条目。作为游标使用，首次请求可不传"},{"name":"limit","type":"number","required":false,"desc":"最大返回条数，默认 50，上限 50"}],"example":"curl \"https://knasync.yuanguangshan.workers.dev/results?since=1715000000000&limit=10\" -H \"X-Auth-Key: <your-secret-key>\"","response":{"status":200,"body":{"cursor":1715000010000,"items":[{"t":1715000005000,"c":"# 某篇文章\n\n正文..."}]},"note":"cursor 是最新条目的时间戳，可作为下次请求的 since 值"},"emptyResponse":{"status":200,"body":{"cursor":0,"items":[]}},"consumers":["Knowly ResultPuller（持久化游标）","手机快捷指令（定期拉取查看结果）"],"errors":[]},{"section":6,"title":"清空所有队列","subtitle":"调试 / 维护","path":"/clear","method":"POST","auth":true,"description":"清空所有队列和结果记录。","example":"curl -X POST https://knasync.yuanguangshan.workers.dev/clear -H \"X-Auth-Key: <your-secret-key>\"","response":{"status":200,"body":"OK (all queues cleared)"}},{"section":7,"title":"健康检查","path":"/health","method":"GET","auth":false,"description":"检测 D1 数据库连接状态，无需鉴权。","example":"curl https://knasync.yuanguangshan.workers.dev/health","response":{"status":200,"body":{"ok":true,"ts":1715000000000,"db":"connected"}}}],"clientMapping":[{"client":"手机快捷指令","action":"提交链接/文本","endpoint":"POST /submit"},{"client":"Chrome 扩展","action":"拉取知乎任务","endpoint":"GET /pull?queue=zhihu"},{"client":"Chrome 扩展","action":"推送处理结果","endpoint":"POST /push"},{"client":"Knowly Relay","action":"拉取通用任务","endpoint":"GET /pull?queue=general"},{"client":"Knowly Relay","action":"推送处理结果","endpoint":"POST /push"},{"client":"Knowly ResultPuller","action":"拉取广播结果","endpoint":"GET /results?since=..."},{"client":"WeClaw","action":"推送 Q&A 对 / 断线通知","endpoint":"POST /push"}],"database":{"tables":[{"name":"queue","fields":["id","content","queue_type","created_at"],"desc":"工作队列"},{"name":"submitted","fields":["content (PK)","last_seen_at"],"desc":"去重表"},{"name":"results","fields":["id","content","created_at"],"desc":"广播结果队列"}]},"workflow":"手机/外部 → POST /submit → [D1 Queue] → Chrome/Knowly GET /pull → 处理 → POST /push → 所有客户端 GET /results","note":"两个 Base URL 功能完全一致，可根据可用性或网络选择任意一个使用。"}