dsh-chat
Verified@yiarce/dsh-chat · v0.2.0 · MIT · Web UI
独立聊天插件:共享聊天页面、图片上传、表情搜索;可选桌面独立窗口。
Install
dsh plugin add @yiarce/dsh-chat Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Published to npm without a public repository. Inspect the package contents before installing.
Tags
Readme
@yiarce/dsh-chat
独立聊天插件。插件拥有页面、样式、登录、图片上传、表情搜索和图片代取;普通浏览器、Electron 和自有 Wails 桌面使用同一套业务能力。
页面与窗口
侧栏入口注册在 sidebar.footer.action。普通环境在主页面内挂载聊天;连接由插件 Node 后台维护,未打开、收起或关闭聊天窗口都不影响接收消息。环境判断沿用 window._wails / window.__wailsRuntimeInjected;自有桌面中点击入口请求打开或聚焦独立聊天窗口,失败时回到页内展示。
独立窗口直接加载同源 /api/yiarce-chat/page?window=desktop,脚本和样式由插件提供。桌面不再内嵌聊天页,也不代发登录、搜索、图片请求。Go 只负责创建、聚焦窗口、注入 Wails 运行时和最小化/关闭/最大化等窗口操作。环境检测没有改成另一套能力接口。
独立页使用插件中的 appearance.js,通过同源 BroadcastChannel 接收主页面的主题变量、字体和可识别的图片/视频背景;没有主页面时使用默认外观。所有同步和页面初始化代码均位于插件,不依赖 GitService.ReadTheme 或桌面主题接口。关闭独立窗口只释放该页面订阅和未完成的图片上传,不关闭后台连接;重复打开复用现有窗口。
登录与聊天
Node 后台优先注入可选账号插件的 yiarceAccount 服务,未安装时使用本插件的微信登录服务;通过账号状态事件处理登录、退出和切换,不轮询账号。凭据按 profile 隔离,业务 token 只保留在 Node 内存,不再交给聊天页面。后台 WebSocket 连接 CHAT_SERVER 指定的聊天服务,默认 http://101.35.239.136:34119;页面只调用同源后台接口。
房间及私聊都支持文字和图片。发送立即进入本地消息列表,等待服务端 client_message_id 回显;成功移除等待图标,失败显示重试,沿用原编号重发。消息、会话及文字草稿由插件 Node 后端写入 SQLite,按 profile、聊天服务地址及当前账号隔离;切换账号仅清除旧账号的页面内存,不删除其数据库记录。Enter 发送,Ctrl+Enter 换行,最多 1000 字。
后台连接与提醒
每个插件实例/profile 的当前账号只有一条后台连接。插件加载并恢复登录后连接,无需打开聊天窗口。前端不建立 WebSocket、不持有聊天 token,不承担重连或自动同步;通过 runtime 命令提交发送、分页、已读与设置,通过 runtime SSE 获取连接状态与在线名单事件,缓存事件合并到同一 runtime SSE,消息展示仍以SQLite缓存为准。为避免HTTP/1.1同源连接额度被长连接占满,缓存不再另开SSE;支持BroadcastChannel和Web Locks时,同源主界面及聊天窗口共用一条聊天事件连接,持有页面关闭后由其他页面接管。能力不可用时每个页面最多一条合并事件连接。缓存初始化及事件连接重连使用短请求恢复本地快照。主界面的聊天入口独立订阅后台事件,沿用现有红点、头像提示及 Wails 任务栏提醒;不创建隐藏聊天窗口,不增加系统弹窗、声音或托盘。
后台先落库再发布实时消息与提醒;历史同步不产生实时提醒。前端上报是否正在显示聊天及窗口焦点,并按可见消息上报已读位置,后台合并提交;无聊天页面时不自动已读。免打扰、广场本地屏蔽及自发消息过滤保持。打开多个页面共享连接,在线名单按各页面订阅映射到同一服务端订阅,最后一个面板关闭或页面离线时取消;默认只接收在线人数,不获取完整名单。
输入与图片预览仍在页面,图片上传沿用现有媒体接口。消息提交给后台后,由后台持有发送确认超时及待发送记录,关闭页面不将其标为失败;尚未提交或未完成上传的消息沿用页面销毁时的取消行为。手动断开影响共享连接。程序完全退出不接收消息;4001 连接替换仍停止重连,不改变服务端多设备策略。
迁移范围、接口和人工验收清单见 迁移工作单。本次只修改聊天插件,无需为迁移重新编译 Go 服务端或桌面程序;更新后需要重载插件 Host 并刷新主界面/重新打开聊天窗口,旧页面不能继续保留其旧 WebSocket。
稳定用户 ID
聊天身份统一使用账号接口 /user/info 返回的数据库主键 user_id。WebSocket self / online / message,以及 HTTP 好友、申请、黑名单、私聊会话中的用户 ID 均为正十进制字符串;username 不再参与鉴权映射、会话键、记录归属及消息去重。账号面板和聊天资料卡展示数字 ID,加好友输入框仅接受数字用户 ID。修改用户名不会改变聊天身份和好友关系。
WebSocket 使用子协议 yiarce.user-id.v1;Host 代理添加并检查 HTTP 身份版本头 X-Chat-Identity: user_id-v1。新旧协议不混用,版本不匹配提示更新并停止自动重连。必须同步部署聊天服务及重载插件 Host,账号插件客户端需要按既有流程构建后刷新。
本地缓存按 [聊天地址 + #identity=user_id-v1, 数字用户ID] 分区。版本标记防止旧纯数字用户名与新数字主键碰撞。旧测试分区保留,不自动迁移草稿、屏蔽名单或待发送消息,也不删除旧数据;新分区从服务端恢复会话和每个会话最新50条,较早历史通过向上滚动自动分页读取。服务端数据库已使用数字主键保存消息和关系,无需重建表。
头像路径仍通过资源域名补全;本次身份升级不增加资料实时推送。更改头像/昵称后,已连接聊天仍需断开再连接以获取新资料,已缓存消息的资料快照不做批量替换。
断线重连
异常断线后按1、2、5、10、30秒等待重试,之后每次等待30秒;这是每次尝试结束后的等待时间,不包含凭据请求和连接耗时。每次重试重新获取凭据,并通过认证HTTP接口校验,401/403停止重试。成功收到self身份帧后重置退避,重新同步所有会话列表及每个会话最新50条消息。连接建立超时仍为20秒。
主动断开、插件宿主退出、登录失效或服务端关闭码4001(账号连接被替换)停止自动重连;用户可手动点击连接/重试恢复。服务端必须同步更新以发出4001,否则旧版本直接断开无法区别连接替换与网络异常。
聊天与联系人
首次打开不默认选中广场或其他会话,右侧显示选择会话的空状态;点击左侧会话后才展示消息及编辑区。搜索栏下方使用聊天 / 联系人滑块,仅切换左侧列表,保留右侧当前内容;点击会话、联系人、新的朋友或黑名单时才切换右侧详情。联系人包含好友、新的朋友和黑名单;申请分收到的与发出的。支持资料、备注、删除好友和拉黑,陌生人可直接私聊。界面仅显示功能名及必要状态,不添加作用范围解释。
好友、申请、黑名单、已读和会话设置以服务端为准。POST /api/yiarce-chat/server 使用后台当前账号凭据,仅代理配置的CHAT_SERVER及白名单业务路由;请求绑定账号及连接编号,不落盘业务token。登录及重连先展示本地会话快照,再更新全部服务端会话列表,每个会话只拉取最新50条消息,不追补全部离线消息;服务端新出现的会话同样取最新50条。同步状态悬浮固定在左侧当前用户信息上方,所有会话同步成功后隐藏;失败保留重试入口。窗口聚焦、拖动、缩放及切换会话不触发消息同步,没有空闲轮询。普通连续消息增量更新缓存与会话,不逐条刷新列表;消息活动、已读成功及read状态通知合并到30秒后的会话校准,持续聊天时每个活动窗口最多安排一个校准计时器,完全空闲后不再循环。其他state_changed仍及时更新关系或会话状态;发现新会话或消息位置缺口时最多取一页最新消息,不连续补拉离线历史。
打开私聊使用POST /api/chat/conversations/private,在首条消息前取得历史。服务端与插件需一起更新。旧好友控制正文、本地关系表和聊天内申请卡片已移除,不提供兼容。
广场在线用户
广场标题显示广场 (人数),人数由服务端主动推送,不轮询。移除单独的在线按钮,点击标题展开或收起在线用户右栏,也支持Enter/空格。宽窗口右栏宽196px,从标题栏下方延伸到底部,消息区和发送区一起缩窄,发送按钮仍右对齐;窄窗口使用覆盖抽屉。右栏搜索仅过滤已加载用户。展开后先订阅名单增量并等待确认,再请求第一页;每页50人,后续点击加载更多,没有更多时隐藏按钮。未展开不取名单,关闭时取消订阅及分页请求,释放名单缓存;切换私聊或资料也关闭列表。
成员展示头像、昵称,左键无业务操作;右键只有添加好友及屏蔽/解除屏蔽。自己的行仅标记我。已加好友时禁用添加好友。本地屏蔽持久化在当前账号缓存库的local_blocks表,通过共享runtime SSE同步同机窗口,只过滤广场消息及提醒,不调用服务端黑名单,仍保留在线名单中的用户并支持右键解除。历史消息也经过同一过滤,私聊不受影响。
分页游标、HTTP页面版本与WebSocket增量共同处理上下线交错,按userId去重;旧分页响应不能复活已离线用户。订阅有独立编号,关闭后到达的旧事件不污染新列表。重连后丢弃旧名单,再次打开从第一页加载。服务端新增协议及online-users接口,插件和服务端需要一起更新。
「查看新消息」按钮固定在消息滚动区容器的右下角,随消息区高度和在线名单宽度变化定位;不再使用相对整个工作区的固定底部偏移,编辑区拖高或出现附件时不会覆盖按钮。
本地消息缓存
使用Node >=22.13的node:sqlite。新库为配置主目录的yiarce-chat//server-cache.sqlite,默认主目录为~/.dsh。旧库不读取、不迁移。仅保存消息、会话缓存、文字草稿、最新消息位置、连续缓存范围的起点、历史结束标记、删除标记及本地广场屏蔽名单。
每次自动同步最多取每个会话最新50条,整页在一个事务中保存并通过一次SSE事件更新页面。最新位置仅表示最近窗口已保存,不表示更早消息已全部缓存。新旧缓存不连续时重设展示边界,保留旧记录但不将其拼接成连续历史;向上滚动到距离顶部96px以内时,从当前展示窗口的起点向前读取50条并保持阅读位置;鼠标滚轮、自定义滚动条、方向键/PageUp/Home及触摸下拉都支持。首次进入、窗口缩放等程序性滚动不主动补页,加载中不重复请求;失败停止自动重试,在顶部提供「重试」。重开页面即使已有更多本地历史,也从当前显示的最近一页往前读取,避免跳过中间消息。确认没有更多消息后顶部显示「没有更早消息了」,实时消息继续通过WebSocket接收。64位编号和序号使用字符串及BigInt,按服务端seq排序;待发送消息在末尾,确认按client_message_id合并,失败沿用原编号重试。
已读根据可见消息与窗口焦点合并上报,不在点击会话时直接清零。隐藏会话收到新消息后恢复,免打扰不停止接收。清空携带明确序号,保留草稿及后到消息。删除标记阻止补拉恢复被删除的消息。
普通文字或已有远程图片在发送前只保存一次待发送记录并清空草稿,服务端回显再保存正式消息;本地图片上传完成后仍保存实际变化的URL及状态。连续实时消息与sync_seq在同一个事务中保存,不单独请求checkpoint;序号缺口不会跨越,并合并触发补同步,执行前重新检查缺口是否已被其他请求修复。已读成功直接应用返回状态,不立即刷新全部会话。普通会话元数据通过sessions事件同步,HTTP与SSE按revision去重,不重新核对所有已加载消息;只有缓存SSE建立或恢复时的snapshot核对已加载消息。清空边界、具体消息/删除事件及跨窗口草稿清空继续独立处理。
输入后的草稿保存事件只更新草稿及会话状态,不重绘消息区。消息渲染复用内容未变化的行与图片节点,仅对变化项增删、替换或调整顺序,避免草稿、已读和窗口尺寸变化导致历史图片反复加载。
SQLite使用WAL、事务和共享runtime SSE同步缓存。请求绑定提交时的账号;账号切换取消旧远端请求并清空界面。图片文件只保存在页面内存,刷新后的未完成图片需要重新选择。
插件媒体能力
全部接口由 ctx.connection.fetch 注册,沿用 DSH 同源认证。
| 接口 | 用途 |
|---|---|
| GET /api/yiarce-chat/page | 独立页面及页内模板 |
| GET /api/yiarce-chat/*.js、page.css | 显式注册的插件前端模块和样式 |
| GET/POST /api/yiarce-chat/login | 独立登录状态及操作 |
| POST /api/yiarce-chat/stickers | 搜索,JSON 参数 keyword、page |
| POST /api/yiarce-chat/sticker-image | 代取图片,JSON 参数 url,返回 dataURL |
| POST /api/yiarce-chat/upload-image | 二进制图片正文,返回 SSE 进度和最终 URL |
| POST /api/yiarce-chat/server | 绑定后台当前连接的聊天服务业务代理 |
| GET/POST /api/yiarce-chat/runtime | 后台状态及连接/发送/同步/已读命令 |
| GET /api/yiarce-chat/runtime/events | 连接状态、在线事件、未读与既有提醒 |
| POST /api/yiarce-chat/history | 消息缓存、游标、草稿和删除操作 |
表情搜索使用 https://h5api.sginput.qq.com/wxbq/search,key 为关键字、page 为页码、num 固定 40。提取 data[].indexUrl,根据 hasMore/endFlag 分页。输入去除首尾空白后为 2–4 个字符,停止输入 350ms 后触发,不限制中文。搜索和图片代取分别有 20 秒、45 秒超时。图片读取按文件头校验 JPG、PNG、GIF、WebP,最多 7MB;已知站点使用兼容 Referer,其他合法 HTTP/HTTPS 图片不按域名或路径限制。
本地选择或 Ctrl+V 粘贴图片后仅创建本地预览。点击发送后消息立即进入列表,插件 Node 后端向闪电图床上传:先请求 /api/v2/configs 建立本次上传的隔离 Cookie 会话,再以 X-XSRF-TOKEN 请求 /api/v2/upload,表单字段 file、storage_id=4、is_public=0。不保存图床凭据,不自动切换其他图床。
上传进度根据 Node 实际写出的图片字节数回传,SSE data JSON 的 type 为 progress/complete/error;progress 包含 loaded/total,complete 包含 url。传输到 100% 后显示处理中,图床业务成功才发送聊天消息,再等待聊天确认。客户端不能把上传至插件主机的传输进度当作插件到图床的进度。单图 7MB,Node 整个接收和上传限时 90 秒,前端等待上限 120 秒。
取消请求、删除消息、断线和关闭页面会中止对应的未完成上传;插件卸载也会取消所有请求。失败保留本地消息图片和错误状态。请求取消不能撤销图床已经保存的文件,不自动重试上传。编辑区不显示上传等待提示。
发布与验证
全部模块列入package.json,资源由host.js注册。更新后需要重新加载插件并同步更新聊天服务端。本轮未启动或替换当前GUI服务。
仅对修改的JavaScript执行node --check,对Go执行gofmt语法解析及格式检查,并解析发布清单JSON。未构建、启动、运行测试或验证CSS渲染与交互。效果由使用者运行验收。