Compare commits

...

375 Commits

Author SHA1 Message Date
snowluma-bot[bot]
5f01c6ab5f Merge pull request #198 from SnowLuma/dev
chore: promote dev → main (6cb7f2c)
2026-07-04 05:39:20 +00:00
DrSmoothl
6cb7f2c6d0 chore(release): v1.11.2 2026-07-04 13:39:00 +08:00
DrSmoothl
07c08ed74d feat(onebot): enrich group/member info fields (#197)
Round out the OneBot v11 group-profile fields the issue asked for.

Group (get_group_info / get_group_list, inherited by get_group_info_ex /
get_group_detail_info):
- group_create_time + group_memo come free from the 0xFE5_2 list
  (createdTime / announcement), verified live (createdTime=1729505343,
  announcement populated).
- group_level lives only in the 0x88D_0 detail; get_group_info fetches it
  (memoized 5min) so a joined group doesn't hit the detail every call.
  get_group_list leaves it 0 — a per-group detail fetch across the whole
  list would be far too costly.

Member (get_group_member_info / get_group_member_list):
- Add area / unfriendly / title_expire_time / card_changeable. QQ NT does
  not expose these, so they're fixed placeholders ('' / false / 0 / true),
  matching go-cqhttp / NapCat. sex/age stay unknown/0 (real values need a
  per-member profile fetch — out of scope here).

typecheck 12 packages; onebot 523 / core 472 green.
2026-07-04 13:04:32 +08:00
DrSmoothl
b20ed12761 fix(onebot): approve group requests from the filtered inbox too (#197)
set_group_add_request could fail with "matching group request not found"
for a request SnowLuma had itself just reported. handleGroupAddRequest only
fetched the main inbox (0x10C8 subCommand 1); a spam-filtered join/invite
lives in the filtered inbox (subCommand 2) and was never searched, so its
flag couldn't be resolved to a sequence.

Fetch both inboxes and search the union. Each request keeps the `filtered`
flag its approval subCommand needs, so a filtered request is approved
through subCommand 2. A failing inbox fetch degrades to the other instead
of aborting. Regular MSF invite pushes don't carry the approval msgseq
(only the private-card path does, #125), so the fetch is the only source.

Regression tests: filtered-only request is found + approved via subCommand
2; "not found" only when neither inbox has it.
2026-07-04 12:48:06 +08:00
DrSmoothl
c027161a64 fix(protocol): get_group_file_system_info returns real counts + space (#196)
file_count 恒为 0(且 used_space/limit_count/total_space 是占位/写死值)。根因:
0x6D8 view 命令分三个 subcommand(1=List, 2=Count, 3=Space),但 getCount 错发到
**subCommand 3(Space)** 且 busId=0,并从 pb<1>/pb<2> 读计数——服务端根本没返回
Count 块,于是恒 0。

真机 RE(bot 在测试群传/删文件核对):
- Count 走 **0x6D8_2 + busId=6**,响应 Count 块里 fileCount=**field 4**、maxCount(文件
  数上限,如 1500)=**field 6**(旧 pb<1>/pb<2> 全落空)。
- Space 走 **0x6D8_3**,响应 Space 块 totalSpace=**field 4**、usedSpace=**field 5**(64 位)。
- 实测:fileCount=4、limitCount=1500、usedSpace=20103729、totalSpace=10737418240。

修复:改 GetGroupFileCount 到 subCommand 2 + busId 6 + 正确 tag;新增 GetGroupFileSpace
(0x6D8_3);action 并发查两者,四个字段全返回**服务端实际值**(优于 NapCat 的写死占位)。
含 count/space 编解码回归测试。catalog regen。

typecheck 12 包;protocol 591 / onebot 521 / core 472 全绿。
2026-07-04 01:59:52 +08:00
DrSmoothl
95b5878456 feat(onebot): return new folder info from create_group_file_folder (#195)
create_group_file_folder 之前只回 data:null,拿不到新建文件夹的 folderId。现对齐
NapCat 返回结构,data 带回文件夹信息:
  { result: { retCode, retMsg }, groupItem: { folderInfo: { folderId, folderName,
    folderPath, createTime, modifyTime, createUin, modifyUin } } }

- 0x6D7_0 创建响应本就在 field 4 携带 folderInfo,SnowLuma 旧 proto 没解(只读
  retcode/retMsg/clientWording)。补上 OidbGroupFileFolderInfoResp 并让 create 的
  deserialize / bridge / action 一路把它带出来。
- 真机验证(bot 在测试群建夹→读回 folderId→删除清理):确认 folderInfo 存在,且
  **modifyUin 在 field 9 而非 Lagrange proto 标注的 field 7**——按真机 wire 修正。
- 新增两个解码回归测试(带 folderInfo / 缺 folderInfo 兜底)。catalog regen。

typecheck 12 包;protocol 587 / onebot 521 / core 472 全绿。
2026-07-04 01:25:14 +08:00
DrSmoothl
f127e3dc59 fix(webui): meet WCAG AA for log-level text on light theme
The log-level accent colors (info/success/warn/error) are tuned as fills;
as small text on the light canvas they fell below WCAG AA (info 2.6:1,
success 2.4:1, warn 2.0:1, error 4.3:1, trace 2.5:1). Add dedicated
--log-* text tokens that are darkened in light mode (>=4.5:1) while
keeping the bright, already-passing values in dark mode, so the app-wide
accent is untouched. trace moves from /60 to /90 to clear AA yet stay the
faintest level. Applied to both the logs page and overview RecentAlerts.
2026-07-04 00:08:30 +08:00
DrSmoothl
7b93eb2716 fix(webui): treat ?token= URL param as the login password (#194)
abef797 misread the request and seeded the value as a bearer session token
(which the operator would have to dig out of localStorage). The intent is
simpler: `?token=<你的WebUI登录密码>` — the value is the plain WebUI login
password, so the link is trivially constructable from something the operator
already knows.

- Revert the client-constructor bearer seeding from abef797.
- AuthBoundary: when no stored token already authed us and the URL carries
  ?token=, run it through client.login() (the normal password path). A correct
  password lands on the home page; a wrong one falls through to the login page
  (server-verified, no bypass). The password is carried into the forced
  change-password gate, matching the interactive login flow.
- The param is consumed once and stripped from the URL (replaceState) before
  the login call — a password in the address bar leaks via history / logs /
  Referer.

typecheck 12 包干净。
2026-07-03 19:41:25 +08:00
DrSmoothl
abef7973d9 feat(webui): auto-login via ?token= URL query param (#194)
登录页每次手输密码很繁琐。支持在 URL 带 `?token=<accessToken>` 直接免密进入:
API client 构造时读取该参数作为 bearer token,交由既有 /api/status 门校验——
有效则直达主页,无效/过期则照常落登录页(无安全降级,服务端仍校验)。

安全处理:token 读取后**立即从 URL 剥离**(history.replaceState)——凭据留在地址栏
会经浏览器历史 / 服务端访问日志 / Referer 头泄露。同时持久化到 tokenStore,
使随后刷新(URL 已无参数)仍保持登录。URL token 优先于已存 token。

只做 token(不做 password)——token 就是实际 bearer 凭据,无需额外登录往返、
也比明文密码更适合放链接。
2026-07-03 19:30:53 +08:00
DrSmoothl
7744e24af2 fix(protocol): make set_group_search actually apply search flags (#191)
旧实现走 OIDB 0x89a_0 但 settings 发空字节 → 服务端返 ok 却 no-op;action 也只收
group_id,没有设置搜索方式的参数(报告属实)。

真机 RE 定稿(tempserver,bot 为管理员的实群逐字段扫描 + GET 读回):
- 修改命令 = 0x89a_0(全量抓包确认,与 MuteAll 同命令,靠 body 形状区分)。结构
  = {1:groupUin, 2: 只含被改字段的 GroupDetailInfo modify 子消息}。这是与 0x88D_0
  群详情 GET **不同的消息域**(mute/shutUpTime 在此=tag17,在 GET 里却是字符串),
  所以标签不能照搬 GET。
- 在 modify 子消息里逐 tag 试写、经 0x88D_0 GET 读回效果,定位:
  noFingerOpen(关键词/群指纹搜索)=tag 35,noCodeFingerOpen(群号搜索/总开关)=tag 36;
  再对照客户端「被搜索方式」三选下拉(私密/群号/群号+关键词)核实语义与 0/1 取值。
- proto-defs:settings 改为 Oidb0x89a_0SearchSettings 子消息,两 flag 用 pb_optional
  (显式存在)——否则 proto3 丢 0 值,导致关闭(=0)被静默忽略。undefined 仍省略。
- set-search/bridge/action:透传 no_finger_open / no_code_finger_open;只下发提供的
  字段(同 NapCat filter 机制、与 modify-group-ext-info 一致)。catalog regen。
- 编码测试锁定:0 值必发 tag 35/36、未提供则省略、命令为 0x89a_0。

typecheck 12 包干净;protocol 585 / onebot 521 / core 472 全绿。
2026-07-03 17:37:55 +08:00
Airline233
884db940df feat(qzone): add set_qzone_msg_right to change a feed's visibility (#186)
* feat(qzone): add set_qzone_msg_right to change a feed's visibility

Add updateQzoneMsgRight in the protocol layer, porting php-qzone's
updateRight: fetch the feed via emotion_cgi_msgdetail_v6, rebuild the
full publish-shaped payload (richval/pic_bo/con), then override
ugc_right/allow_uins and POST to emotion_cgi_update. Expose it through
QzoneApi.updateRight and the OneBot set_qzone_msg_right action, with the
same ugc_right/target_uins validation as send_qzone_msg. Covered by
protocol, core and onebot tests.

* fix(qzone): make qzoneParse more stable and fixed a test example
2026-07-02 22:38:05 +08:00
DrSmoothl
3e99d3bb5a fix(webui): guard async polling against re-entrant overlap
三个 setInterval 轮询(列表 reconcile、systemInfo 快刷、6h 更新检查)调度的都是 async
tick,但 setInterval 不感知 Promise 完成——当某次请求慢于轮询间隔时,下一次 tick 会在
上一次未完成时又发起,导致同类请求并发堆叠、越积越慢。

每个 tick 加在途 running 互斥:上一次刷新还在飞就跳过本次,完成(try/finally,含出错)后
恢复调度。保留已有的 document.hidden 门控与变可见补刷。慢 tick 只是被跳过、完成后自愈,
不会永久停摆。

(引 non-overlapping-poll 工具 + 给 webui 新增测试基建对 3 个轮询点属过度工程,故就地加
互斥。)
2026-07-02 21:04:35 +08:00
DrSmoothl
b5ede95772 test(core): fake timers for group-history walk-back to skip send-gap waits
The walk-back loop enforces a real ~300ms gap between each SsoGetGroupMsg send
(a deliberate process-wide anti-flood throttle). The test paid that gap for
real — up to 300ms x 12 sends per case — making the file ~5.2s.

Install vitest fake timers and drain the queued send-gap timers via
runAllTimersAsync, so the loop/cursor logic runs instantly. The production
throttle is untouched (only the test file changes).

Walk-back test body ~5237ms -> ~4ms; full core suite ~21s -> ~4.4s.
2026-07-02 19:55:50 +08:00
DrSmoothl
1f2bf4d3f2 chore(deps): patch low-severity esbuild + @babel/core advisories
两个构建/测试期工具链的 transitive 依赖存在低危「任意文件读」告警(非运行时产物):
- esbuild 0.27.7 → 0.28.1(dev server 任意文件读,vite 接受 ^0.28.0,兼容)
- @babel/core 7.29.0 → 7.29.7(sourceMappingURL 任意文件读)

pnpm.overrides 钉住修复版下限(esbuild@<0.28.1 / @babel/core@<7.29.6),防止后续
lockfile 重生回退。全 12 包 typecheck 干净、webui vite build 通过、protocol 572 测试
全绿,工具链未受影响。
2026-07-02 15:16:40 +08:00
DrSmoothl
c85c510c0b perf(webui): trim debug-view rendering cost (json-tree, activity, tester)
- json-tree:折叠节点不再枚举子项(改用 count),整棵树的 JSON.stringify 从每次渲染
  改为点击复制时才算。
- live-activity:搜索命中串在入队时预生成,过滤不再对每行 JSON.stringify(300 行 ×
  每次击键)。
- action-tester:流式帧封顶 2000,长/失控流不再无限增长数组与 DOM。

均行为保持(或纯改善),对抗性 Agent 逐条核验无回归。
2026-07-02 15:02:13 +08:00
DrSmoothl
99547e847e perf(webui): gate list/system polling on tab visibility
两个兜底轮询(列表 reconcile、systemInfo 快轮询)的 tick 在 document.hidden 时跳过,
并监听 visibilitychange 在切回时立即补一次。后台标签页不再空转 fetch;实时状态本就
走 SSE(未门控),切回时立即刷新无空态闪烁。
2026-07-02 15:02:13 +08:00
DrSmoothl
d17381a221 perf(webui): batch log SSE into ~80ms flushes instead of per-line setState
日志页每收到一条日志就 setLogs(prev => [...prev.filter(id≠), entry].slice(-cap)),
高日志速率下是每条一次 O(n) 过滤+复制 + 一次 React commit。改为入队到 pending、
每 ~80ms 批量 flush:一次 O(n) 合并(Map 去重、last wins)+ 一次 commit。去重(重连
重放同 id)与 maxLines 上限语义保持不变,卸载时 dispose + 清 timer。
2026-07-02 15:02:13 +08:00
snowluma-bot[bot]
a11c684dfd Merge pull request #183 from SnowLuma/dev
chore: promote dev → main (72aedbc)
2026-07-01 14:15:29 +00:00
DrSmoothl
72aedbc612 chore(release): v1.11.1 2026-07-01 22:15:01 +08:00
DrSmoothl
63ab7a1846 fix(protocol): parse Qzone feeds without eval + stop getCookies hanging (#182)
真机抓包定位到 get_qzone_feeds 的两个问题:

1) feeds3_html_more 的响应体是**JS 对象字面量**(键无引号、单引号字符串、\xNN
   转义、数组含 undefined),不是 JSON → JSON.parse 报 "Expected property name
   at position 66"(报告者看到的「响应结构问题」)。实测调参数(outputhtmlfeed/
   format)改不掉这个格式,且 feeds 是纯远程 H5(native i64 里无相关 CGI),没有
   干净 JSON 端点。改用**非执行的递归下降解析器** parseJsLiteral 把它当数据解析——
   绝不 eval 远程内容(vm 沙箱不是安全边界,被篡改的响应可逃逸到 RCE)。解析器只认
   对象/数组/字符串/数字/true|false|null|undefined,丢弃 __proto__ 键防原型污染;
   mapFeeds 过滤数组尾部的 undefined 洞。

2) getCookies 卡死:HttpsGetCookies 无超时、无深度上限地递归跟随 302;当某跳目标
   不可达(数据中心/Docker 上 qzone.qq.com 裸域超时)→ 永久挂死所有 cookie-backed
   web 动作。加 8s 超时 + 深度上限(5) + 失败/超时保留已收集 cookie(不再 reject)。

两处修复均在 tempserver 真机验证:getCookies 从卡死 3 分钟变正常返回;抓到的真实
feeds 响应体做成测试 fixture,非执行解析器正确解出 uin/nickname/html(\x3C→<)。
读接口加了 TRACE 原始体日志 + 结构失败错误带响应片段,方便后续排查。
(msglist 的 -10000「使用人数过多」判定为 taotao 服务端风控——同 cookie 下 feeds
能成功、msglist 单独挂,非代码 bug,代码已正确透传。)

protocol 572 全绿、typecheck 干净;两轮对抗性 Agent:先揪出 vm 版可 RCE 逼我换非执行
解析器,再确认新解析器构造上不执行代码、无原型污染、真机数据解析正确。
2026-07-01 21:56:28 +08:00
DrSmoothl
3932958c39 fix(bridge,common,onebot): reject phantom hook UINs + never crash logging (#162)
注入的竞态窗口里,native hook 偶发上报 13 位垃圾 UIN(时间戳型,读到 QQ 尚未落定
的内存)。TS 层防御缺失,导致两个连锁问题:

1) 幽灵账号:isRealUin 只查「纯数字且 ≥5 位」、无上限,垃圾值通过后建会话并把
   config/onebot_<垃圾>.json 落盘 → OneBot 节点配置里出现随机幽灵账号(跨重启残留)。
2) 进程崩溃:logger 彩色路径 ' '.repeat(SLOT - tagLen),UIN tag(含方括号)超宽 →
   负数 → RangeError: Invalid count value → uncaughtException。

跨平台(Win DLL / Linux .so 同逻辑)+「更新 QQ 后消失」都印证是 native 读到那块内存
的偶发垃圾;根修在 SnowLumaNative,此处补齐 TS 防御:

- 抽出唯一的 @snowluma/common/uin::isRealUin = /^\d{5,10}$/(真实 QQ ≤ uint32 →
  10 位)。删除 bridge/core 两处重复副本(重复正是这次漏加上限的温床)。等价旧逻辑,
  仅新增拒 11+ 位。
- logger.ts 加 Math.max(0, …),日志永不崩进程(独立健壮化)。
- 收紧 WebUI UIN_REGEX /^\d{5,12}$/ → /^\d{5,10}$/ 保持一致。
- 启动时 cleanupInvalidPerUinConfigs() 清掉已落盘的幽灵 onebot_<uin>.json(只删
  UIN 不合法的,绝不碰合法账号/全局配置)。

测试:common +8(uin 6 / logger 2)、onebot +3(cleanup)。typecheck 12 包干净;
common 58 / onebot 519 / core 471 / bridge 73 全绿。对抗性 Agent 逐输入核验等价性、
三层 gate 堵死幽灵入口、cleanup 安全时序,无回归。
2026-07-01 20:37:02 +08:00
DrSmoothl
ade76d3d2f refactor(protocol): reuse tested Sha1Stream in video block-sha1 (drop dup)
video-upload.ts 有一份 ~110 行手写、**无测试**的流式 SHA1(Sha1StreamState),与
sha1-stream.ts 里已充分测试的 Sha1Stream 逐字节相同(transform 数学等价、中间 state
小端)。删掉该重复,computeVideoSha1Blocks 改用 Sha1Stream 做 1MB 块的中间 state、
Node crypto 做整文件 final(与受测的 computeSha1StateV 同一套路;已实测旧 final() ===
Node crypto 整文件 sha1)。

- 新增 video-sha1-blocks.test.ts(4 例):golden 值从**旧实现**抓取,锁定重写 byte-
  identical(两个 1MB 中间 state + overall),并给这个原本无测试的函数永久覆盖。
- 删掉的 tail-update 只影响旧自实现 final,不动任何中间块(tail<64B 不触发 1MB 边界)。

protocol 565 全绿、typecheck 干净;对抗性 Agent 独立复现旧实现确认 golden 逐字节
相同、transform 数学等价无精度问题、无残留引用。
2026-07-01 20:14:55 +08:00
DrSmoothl
c822c5dab6 refactor(webui): extract useFlashMessage hook for settings panels
三个 settings 面板各手写同一套 flash-message 状态机(msg state + setTimeout 自动
消失 + 卸载清 timer)。global-config / notifications 是完整版(逐字相同);
system-panel 是退化版(无 timer ref、无 cleanup、rapid flash 累积 timer、卸载后可能
stale setMsg)。抽 useFlashMessage(durationMs=2400) → { msg, flash, setMsg }。

- global-config / notifications:迁移后行为不变(2400ms;flash 瞬时 + setMsg 持久
  错误保留)。
- system-panel:保留 4000ms(useFlashMessage(4000)),顺带补上 prior-timer 取消 +
  卸载 cleanup(修 timer 泄漏,现代 React 里无害的小改善)。

webui typecheck(tsc -b) + vite build 干净;对抗性 Agent 逐行核对确认 hook 等价、
两面板行为不变、无依赖/import 回归。
2026-07-01 20:03:58 +08:00
DrSmoothl
a8f24b8f13 refactor(onebot): converge self-sent message tail into finalizeSend
send/forward 路径里「记录自发消息」的尾巴(hashMessageIdInt32 + cacheMessageMeta +
cacheSelfSentMessage)逐字复制 6 份(sendPrivate/sendGroup/两个 forward/forwardSingle
的 group+private 分支),每处独立手工配对 isGroup ↔ eventName ↔ hash 事件常量——
漏改一处会静默产生错 message_id / 错 event 归属。抽 finalizeSend(ref, isGroup,
targetId, receipt, elements),由 isGroup 单点派生 eventName + 常量。

6 处塌成 6 行调用;forwardSingle 的 group/private if/else 只剩 send API 本身不同。
receipt 用结构类型覆盖所有调用点(含 line 630 合成的 fallback)。

行为严格不变:onebot 516 全绿、typecheck 干净;对抗性 Agent 逐字对比 HEAD 确认
6 处等价、参数/返回正确。
2026-07-01 19:55:21 +08:00
DrSmoothl
f111ba7129 fix(core): resolve self uid instead of shipping an empty one (forward/flash)
阶段 2:修 self-uid 收口暴露的 2 处静默空串 bug。warmup 未完成时 identity.selfUid
为 null,原 `?? ''` 会把空 uid 放进出网包:

- forward.ts:154 responseHead.toUid(转发广播消息坏包)
- flash-transfer.ts:279 fileset uploader.uid(空 uid 会被服务端 drop fileset)

均改为 `await resolveSelfUid(...)`:正常路径(selfUid 有值,几乎总是)命中缓存、取值
完全不变;仅在身份未就绪的极端情况从「静默发坏包」变成「明确报错」(fail-loud)。
两处外层函数本就 async。group-admin.ts:64 的 ?? '' 是合成本地事件、best-effort、
非出网,保留不动。

core 471 全绿、typecheck 干净;对抗性 Agent 确认正常路径不变、无测试回归。
2026-07-01 19:18:10 +08:00
DrSmoothl
3db89d0bd0 refactor(protocol,core): converge self-uid resolution to one impl
「取自己 uid」原本散成 5 份、3 种错误文案:core/apis/shared.ts::resolveSelfUid、
group-file/message 各内联手抄一份、get-like 跨包再抄一份。收敛成 protocol 单一
resolveSelfUid(ctx: Pick<BridgeContext,'identity'|'resolveUserUid'>)。

阶段 1(行为不变):
- 新增 protocol/self-uid.ts(依赖方向 core→protocol 要求权威实现下沉 protocol;
  Bridge 与 OIDB service Deps 都满足 Pick 切片)。
- core/apis/shared.ts 改为 re-export 它(现有 resolveSelfUid(bridge) 调用点不变)。
- get-like/group-file/message 三处内联手抄 → 全调权威实现。
- 唯一副作用:message 的错误文案统一为 'self uid is unavailable'(无测试依赖旧文案)。

flash-transfer/forward 的 ?? '' 空串 bug 留待阶段 2;group-admin 合成本地事件保持不动。
全仓 12 包 typecheck Done、protocol/core(471)/onebot(516) 全绿;对抗性 Agent 确认
toInt/Number 边界无实际差异(identity.uin 恒为正整数串)、5 处等价。
2026-07-01 19:12:05 +08:00
DrSmoothl
298d174640 refactor(webui): extract openSseChannel for the three EventSource openers
stateStream / openLogStream / openDebugStream 三个 EventSource opener 近乎逐字重复
(token 守卫 → EventSource → onopen/onerror → onmessage try-parse-catch → close
disposer),token/reconnect/畸形帧-跳过 语义各写一遍、易漂。

- 新增私有 openSseChannel<T>(path, onMessage, onStatus?) 收敛骨架;各 opener 塌成
  一行调用,consumer 逻辑作为 onMessage 传入(保持「回调在 try 内、抛错当畸形帧
  吞掉」语义)。logs 的控制帧过滤(`'type' in parsed`)留在其 onMessage 回调里。
- StreamStatus 提到顶部 import,删掉 openDebugStream 的 inline import。

行为严格不变、对外签名不变:webui typecheck(tsc -b) + vite build 干净;对抗性 Agent
逐字对比 HEAD 确认三 opener 等价、onMessage-在-try-内 语义保留、无漏并入。
2026-07-01 18:58:22 +08:00
DrSmoothl
29a792cfdf refactor(core): extract sseResponse helper for the three WebUI SSE endpoints
/api/debug/stream、/api/state/stream、/api/logs/stream 各自逐字复制同一套 ~40 行
SSE 生命周期骨架(TextEncoder + closed 守卫 + 15s heartbeat + teardown + safe
enqueue + abort listener + event-stream headers);改一处 heartbeat 间隔/teardown
顺序/headers 要同步改三处,漏一处会 listener 泄漏。

- 新增 webui/sse-response.ts:sseResponse(c, start) 封装传输壳,给 start 回调一个
  channel { raw, encode, send, onClose, isClosed, desiredSize }。各端点特有的订阅/
  背压 framePusher/初始快照留在回调里。
- 三端点收敛:debug/state 用 createFramePusher(背压丢帧) + onClose 注册订阅;logs
  直接 ch.send;state 的 503 守卫留在 helper 外。
- 新增 sse-response.test.ts(4 例)为这三个原本无生命周期测试的端点建立安全网。

行为严格不变:core 471 全绿、typecheck 干净;对抗性 Agent 逐字对比 HEAD 确认
helper 骨架与三端点等价、无时序/守卫回归。
2026-07-01 18:53:34 +08:00
DrSmoothl
c1d27c5055 refactor(protocol): converge packet-pipeline dispatch tail into finishDispatch
process() 的 sync 分支、dispatchAfterIdentityRefresh、dispatchGroupInvite 三处逐字
重复同一段收尾(handleSideEffects → printEvent → emit);再加一种需 pre-dispatch
富化的入站事件就得原样抄这三行,漏一行会静默丢日志或丢事件发射。抽 finishDispatch
收敛为一处。

- finishDispatch(event, alreadyRefreshed=false):默认 false 使 sync/group-invite
  两路的 finishDispatch(event) 等价于原 handleSideEffects(event);identity-refresh
  路透传 refreshed。与 CONTEXT 里已做的 reconcilePipeUp/Down 收敛同构。

行为严格不变:protocol 561 + core 467 全绿、typecheck 干净;对抗性 Agent 逐字对比
HEAD 确认三处等价、透传正确、三条路径均有测试覆盖。
2026-07-01 18:43:20 +08:00
DrSmoothl
85ca207279 refactor(onebot): extract openSqliteDb helper for the three stores
message/media/reaction store 构造器各自逐字复制同一段引导(mkdir 父目录 + 打开
DatabaseSync + PRAGMA journal_mode=WAL + PRAGMA synchronous=NORMAL),改一处 PRAGMA
要改三处。抽 openSqliteDb(dbPath) 收敛,schema init 与路径改写留在各调用方。

- message-store 的 .json→.db 改写保留(改写后同目录,mkdir 目标不变,等价)。
- 三文件删掉不再使用的 fs/path import。

行为严格不变:onebot 516 全绿、typecheck 干净;对抗性 Agent 逐字对比 HEAD 确认
三处引导等价、路径细节无边角、无回归。
2026-07-01 18:37:42 +08:00
DrSmoothl
d89b095af5 refactor(protocol,proto-defs): fold 1:1 subpath exports into wildcards
protocol/package.json 有 273 行专给 91 个 oidb-service(每个 3 行 1:1);加一个
service 忘改 package.json → build 期解析失败。把所有严格 1:1 的目录组折叠成通配符
(moduleResolution:"bundler" 原生支持),消除永久手同步负担。

- protocol:./oidb-services/*(91) + ./highway/*(7) + ./web/*(7) + ./msg-push/*(3);
  bare ./msg-push / ./highway(exact)与单文件 export 原样保留。
- proto-defs:./oidb-actions/*(10)。
- 净 -467/+15 行;两包均 private:true,通配新暴露的少量内部文件无害(exports 只
  gate 跨包解析、无外部消费者、无副作用)。

零源码/import 改动。全套工具链验证:12 包 typecheck Done、protocol/onebot(516)/
core(467)/mcp(22) 测试全绿;对抗性 Agent 端到端解析 136 个真实深导入全部命中、
确认 exact/wildcard 共存正确。
2026-07-01 18:30:45 +08:00
DrSmoothl
15a6fe3785 refactor(onebot): make event converter dispatch an exhaustive registry
阶段 2(零行为改动):把 convertEvent 的 17-arm switch 换成
CONVERTERS: { [K in QQEventVariant['kind']]: ConverterFor<K> | null } 表。mapped
type 对事件类型联合 total——新增一个 kind 却漏写 converter 会**编译报错**,而非
像原 switch 那样静默走 default: return null。

- ptt_trans_result(内部语音转文字事件,不对外)在表里显式标 null,与原 default
  行为等价。
- 派发一次 localized cast 解 correlated-union,纯类型层、运行时等价。
- 护栏实测有效:删任一 kind 条目即 TS2741 编译失败。

onebot 516 全绿、typecheck 干净;对抗性 Agent 逐一核对 17 映射、独立复现护栏报错。
2026-07-01 18:03:02 +08:00
DrSmoothl
ae17bc0cf5 refactor(onebot): extract event envelope builders; collapse message triplets
阶段 1(零行为改动):消掉 17 个 converter 各手搓的 time/self_id/post_type 信封,
合并 message 三胞胎。

- 新增 event-converter/envelope.ts:notice/request/message 三个信封 builder,
  converter 只供应各自 post_type 的字段。
- to-notice(12)/to-request(2) 改用 notice()/request()。
- to-message:friend+temp 合成 convertPrivateMessage(subType)(仅 sub_type 差),
  group 独立;新增 toSegments 收敛 7 参 elementsToJson splat。导出名不变。

行为 byte 级不变(测试 toEqual 顺序无关,key 集合与值逐一保持):event-converter
48 + onebot 全量 516 全绿、typecheck 干净;对抗性 Agent 逐 converter 对比 HEAD 确认
16 个输出等价、无字段增减/值变、无运行时循环。
2026-07-01 17:58:49 +08:00
DrSmoothl
891a197335 refactor(onebot): collapse action registration into a single barrel
加一个 action 文件原本要同步改三处手写清单:ApiHandler 的 12 个 register import +
12 行构造调用、各文件的 register footer、action-docs 的 13 import + GROUPS。现收敛
成一个 actions/index.ts barrel 作为「文件→动作 + 分类」的单一真相。

- action-kit:抽 RegisteredActionSpec(describe+register),ActionSpec/
  StreamActionSpec extends 它,registerActions 参数放宽到 RegisteredActionSpec[]
  (它只调 .register),于是 stream 动作也能并入统一注册。
- 新增 actions/index.ts:ACTION_GROUPS(11 组含分类,stream 合并)+ ALL_ACTIONS。
- api-handler:12 import+12 调用 → registerActions(this, context, ALL_ACTIONS);
  .handle_quick_operation(唯一非 ActionSpec 的裸 handler,需要 h 本身)从
  extended 搬进构造器一处显式注册。
- action-docs:改用 barrel 的 ACTION_GROUPS,删本地 GROUPS + 13 import。
- 删 12 个 register footer + 清理因此变 unused 的 ApiHandler/ApiActionContext import。

行为严格不变:注册的动作集合、.handle_quick_operation、文档分类/计数均一致。
onebot 516 全绿、全仓 12 包 typecheck Done;对抗性 Agent 逐条对比 HEAD 确认等价。
2026-07-01 17:49:07 +08:00
DrSmoothl
b6cde5101d refactor(common,core): extract mapWithConcurrency util; use in forward enrich
阶段 2:把「限量+并发分批」的手写循环收进一个 common util。此形状已被复制进
私有 SLE(friend.ts),是已发生的复制漂移;抽出后堵住它、并给未来的富化点一个
现成原语(cap + 并发批 + best-effort 是防 Tencent 风控封号的标准配方)。

- 新增 common/concurrency.ts:mapWithConcurrency(items, concurrency, fn),批处理
  语义(每批 Promise.all 等齐再下一批,非 rolling pool,保持 forward 现有行为),
  结果按输入顺序返回。7 个单测覆盖顺序/绝对index/峰值≤limit+跨批serialize/
  不整除/单批/空/concurrency<1。
- 迁移 forward.ts residue 昵称富化的并发批循环;cap(slice MAX)/dedup(Set)/
  best-effort(fn 内 try/catch) 保留在 callsite。行为严格不变。

对抗性 Agent 逐条对比 HEAD 确认等价。common 50 / core 467 全绿、typecheck 干净。
2026-07-01 17:29:25 +08:00
DrSmoothl
9d67630396 refactor(common,core): extract single-flight+TTL cache primitive
阶段 1:把手写多份的「单飞+TTL 记忆化」收进一个 common 原语,消除各处
各自实现「TTL 判定 / inflight 去重 / finally 清理」的漂移风险(底层都是 Tencent
风控:忙碌客户端会为每条消息发一次未缓存 OIDB 拉取,持续爆发触发封号)。

- 新增 common/single-flight-cache.ts:createSingleFlightCache<K,V>({ ttlMs, load,
  shouldCache?, now? }).get(key, {force});shouldCache 容纳「错误结果不缓存以便
  重试」,now 可注入便于测 TTL。7 个单测覆盖新鲜命中/单飞去重/force/TTL 过期/
  shouldCache/错误传播/invalidate。
- 迁移 contacts.fetchGroupMemberList(key=groupId, ttl 60s, 默认 shouldCache)与
  update-check.getUpdateInfo(全局 key, ttl 6h, shouldCache=!error)。行为严格不变。

对抗性 Agent 逐条对比 HEAD 确认两处等价(含 update-check 时间戳来源毫秒级微差、
对 6h TTL 可忽略)。common 43 / core 467 全绿、typecheck 干净。
2026-07-01 17:25:04 +08:00
DrSmoothl
6f6f372337 refactor(onebot): drop 55 redundant ACTION_FAILED try/catch in extended actions
阶段 2b:从 extended.ts 删除 55 个「纯兜底」try/catch(catch 体恰为单条
return failedResponse(ACTION_FAILED, String(e)/e.message)),让抛错落到唯一 seam
runAction(已统一 100 + error.message)。retcode 不变(这些本就是 100),去的是
冗余包装。

- 保留:try/finally、带前缀的 catch(获取精华消息失败 / 语音转码失败)、
  download_file 保存失败的 BAD_REQUEST catch、fetchFilteredGroupRequests 的
  catch{return []} 吞值——均原样未动。
- 唯一文案变化:约 30 个原用 String(e) 的 catch,其 wording 由 "Error: X" 变为
  seam 的裸 "X"(丢类名前缀,retcode 不变;OidbError 的服务器码仍在 message 内)
  ——一致化改善,无测试/契约依赖该前缀。
- onebot 全量 516 全绿、typecheck 干净;对抗性 Agent 逐块比对 HEAD 确认等价、
  结构正确、无误删漏改。
2026-07-01 16:30:00 +08:00
DrSmoothl
5be852f394 refactor(onebot): drop redundant per-action try/catch in qzone/album/admin
阶段 2a:删除 qzone(7)、group-album(8)、group-admin(1) 共 16 个「纯兜底再包一层」
的 try/catch,让抛错自然落到唯一 seam runAction(阶段 1 已统一为 ACTION_FAILED 100
+ error.message)。qzone/album 原返回 1200 → 归一 100(本任务有意);group-admin
原本就是 100,仅去冗余包装。

- 保留:qzone helper uploadQzoneImages 的带前缀 re-throw catch、group-info 的
  honor-info 前缀 catch、message 的吞值 catch(best-effort 保留旧 URL)——均未动。
- 清理三文件不再使用的 RETCODE/failedResponse import。
- qzone-actions 测试断言 1200 → 100(wording 前缀经 seam 仍保留)。
- onebot 全量 516 全绿、typecheck 干净;对抗性 Agent 逐个对比 HEAD 确认纯兜底、
  无其它漂移、无误删漏改。
2026-07-01 16:20:26 +08:00
DrSmoothl
ab45667fdf refactor(onebot): unify action-error retcode at the runAction seam
将「动作抛错返回什么错误码」从各处不一致(100 / 1200 / 漏包→1200)收敛到唯一
兜底处 ApiHandler.runAction,统一为 ACTION_FAILED(100) + error.message。

阶段 1(改 seam 本身):
- runAction catch:默认码 1200 → 100;文案 'internal error' 兜底改为 String(error)。
  OidbError.message 本就含 QQ 服务端 code,无需特判。
- 新增 3 个测试锁定策略:抛 Error→100+message;抛 OidbError→100 且 wording 含
  code+server msg;抛非 Error→100+String()。
- rename_group_file 那个原断言 1200 的测试(未包裹动作、落 runAction)改为 100。

各 action 里多余的 try/catch(qzone/group-album 等仍返回 1200)留待后续阶段删除,
在此之前其失败不经此 seam。onebot 全量 516 全绿、typecheck 干净。
2026-07-01 16:11:49 +08:00
DrSmoothl
ab40f086ee refactor(protocol): dedup NTV2 record/video mediaNode builder in decoder
阶段 3(零行为改动):record(bizType 12/22) 与 video(bizType 11/21) 解码分支里
各写一份、逐字完全相同的 23 行 `mediaNode:{ fileUuid,storeId,uploadTime,ttl,
subType,info:{…} }` 块,抽成共享 helper buildMediaNode(idx, fi),消除这对并行拷贝
的漂移风险(改一处忘另一处)。

- VideoFile / Ptt 两处的 mediaNode 来源变量与 shape 不同,正确保持独立、未误并。
- 逐字提取,行为 byte 级不变:typecheck 干净、protocol 全量 561 全绿;对抗性
  Agent byte-diff 确认原两份完全相同、helper body 与之逐字一致。

注:计划中的 poke faceId→subType 字段对齐已主动撤销——poke 不能当消息段发送,
且自身消息回显路径会读 element.subType 使该改动可观测,违反"重构行为不变"。
2026-07-01 15:56:43 +08:00
DrSmoothl
8e173cf7d7 refactor(onebot): merge element toSegment/fromSegment into one codec table
阶段 2(零行为改动):把「同一种消息元素」的两个 onebot 方向——收·转
(to-segment) 与 发·解(message-parser)——从两个文件各写各的分支,合并到一张
按元素类型索引的 ELEMENT_CODECS 表,每种类型一条 { toSegment?, fromSegment? }。

- 新增 event-converter/element-codecs.ts:13 类 toSegment + 14 类 fromSegment
  逐字平移自原实现;私有 helper intOr/marketFaceElement/pickMediaSource 移来并导出。
- to-segment.ts:elementToSegment 改查表 + 保留原 default 透传兜底。
- message-parser.ts:segmentToElement 保留 9 个纯输入糖 case 作前置 normalize,
  真实类型改查表,末尾保留原 unsupported warn。
- onebot 对账测试升级为按表键核对 S/P(比正则更硬),并断言真实类型 case 不再
  残留于 parser、输入糖仍在。

行为 byte 级不变:onebot 全量 513 全绿、typecheck 干净;对抗性 Agent 逐字比对
确认无漂移、无运行时循环依赖。
2026-07-01 15:48:04 +08:00
DrSmoothl
f4170b014a refactor(protocol,onebot): add message-element four-direction reconciliation manifest
消息元素散在 4 处派发(收·解 / 收·转 / 发·解 / 发·打包),历史上各写各的、
无对账,导致字段名对不上、漏写方向走 default 静默失败。

阶段 1(零行为改动):立一份权威清单 element-manifest + 两道架构护栏测试。
- element-manifest.ts:每种元素类型 × 四向支持('yes'/'no'/'by-design-no')
  + 字段契约 + typesForDirection() + 输入糖白名单。清单逐字反映当前行为。
- 两道对账测试(因包边界拆两处、共用清单):正则扫 4 处派发代码,比对清单。
  谁增删一个方向却不同步清单,测试当场报红,不再运行时静默。
- 取值域用 [A-Za-z0-9_]+,避免未来驼峰/下划线类型名被静默漏抓致护栏失效。
- poke 的 W=by-design-no:QQ 不允许戳一戳当消息段发送,缺席正确。

对抗性 Agent 两轮复审通过。
2026-07-01 15:48:04 +08:00
囧囧JOJO
f424454422 fix(webui): align debug account picker styling (#181) 2026-07-01 14:43:29 +08:00
DrSmoothl
5d6ce86b66 refactor(onebot): give trans_group_file semantic param roles
Follow-up to #161: trans_group_file's group_id/file_id used plain
f.uint()/f.string(); switch them to f.groupId()/f.fileId() (identical
coercion) so the WebUI debug console renders a group picker + file-id
control for the new action and the catalog carries the roles. Catalog
regenerated.
2026-07-01 02:27:35 +08:00
Airline233
9ca64bed10 feat(core,onebot): implement trans_group_file action (#161) 2026-07-01 02:13:35 +08:00
Airline233
2f374ea8c9 feat(qzone): support post visibility rights when publishing qzone posts (#178)
Add ugc_right and target_uins to the qzone publish path across protocol,
bridge, and the send_qzone_msg OneBot action, regenerate the MCP catalog,
and cover restricted visibility (16/128) with validation tests.
2026-06-30 23:57:39 +08:00
DrSmoothl
c90a3954e4 fix(bridge): self-heal login detection when the hook misses the edge
Docker SnowLuma could hang forever at "等待登录" after QQ had already
logged in. Root cause: login detection is edge-triggered — it only learns
the state from a loginState frame the native hook PUSHES when it observes
the login transition. `getLoginState()` is a cached value read once at
connect; after that the session waits passively. Desktop attaches the
hook before the user logs in, so it catches the edge. In Docker, QQ
auto-logs-in from a persisted session — fast on startup — so the
transition lands before the recv pipe is connected (frames aren't
replayed) or via a silent restore path the hook doesn't intercept. The
edge is missed and the cached state stays not-logged-in.

Fix: while connected but not logged in, actively re-probe QQ's own
ptlogin/deeplink ports via probeQqLoginInfo (level-triggered, pipe-
independent — the same call the workaround used) and synthesize the login
once it reports a real uin. Immediate probe on connect + a 3s interval;
stopped on login / teardown / dispose, with an in-flight guard so a slow
port scan can't stack concurrent probes. Idempotent with the pushed-frame
path. 7 tests cover detect-via-probe, the later-interval case, the
not-logged-in / non-real-uin / throwing-probe guards, no double-emit, and
no concurrent stacking. probeLogin is injectable for tests.
2026-06-30 23:29:51 +08:00
DrSmoothl
397087dc74 test(core): hoist Bridge import to fix flaky 5s timeout
bridge-private-routing.test.ts loaded the Bridge dependency tree via
`await import(...)` INSIDE each `it`, so the first test paid the whole
~3.8s module-eval cost against its 5000ms per-test budget — fine locally
but tipping over on slower CI runners (surfaced as a timeout on an
unrelated PR). Moved the Bridge / IdentityService imports to top-level
statics (vi.mock is hoisted above them, so element-builder stays mocked):
the heavy load now happens once at file collection, not against a test
timeout. Per-test execution dropped from ~3.8s to ~7ms.
2026-06-30 23:09:21 +08:00
snowluma-bot[bot]
b807825a09 Merge pull request #175 from SnowLuma/dev
chore: promote dev → main (48e2777)
2026-06-30 12:39:05 +00:00
DrSmoothl
48e2777bc3 chore(release): v1.11.0 2026-06-30 20:38:37 +08:00
DrSmoothl
a8307891fa fix(core): backfill forward-msg sender nickname/card (#174)
get_forward_msg nodes came back with empty or "QQ用户" sender names: the
SsoRecvLongMsg payload doesn't always populate the member name, and the
sync decode only consulted the L1 identity cache. So a sender absent from
that cache (just-started bot, inactive member) had no name.

ForwardApi.enrichSenders() now backfills nameless nodes on both fetch
paths (wire + cache-hit, with write-back so seeded inner caches enrich on
first read):
- L3: one fetchGroupMemberList per distinct group (inflight+TTL cached)
  resolves every in-group sender at once; card preferred over nickname,
  matching the existing wire-decode convention.
- L4: per-uin fetchUserProfile only for the residue (members who left the
  group, private nodes).

Best-effort: a failed lookup keeps the placeholder, never failing fetch.

Adversarially reviewed — fixed the one High it found: the L4 fallback was
an unbounded Promise.all of un-cached OIDB 0xFE1_2 lookups, which a
high-churn group's historical forward (many since-left senders) or a
flaky member-list call could amplify into a rate-limit ban (the very risk
ContactsApi's own cache note warns about). Now: member-list failure keeps
the placeholder instead of fanning out, and the residue is capped
(FORWARD_PROFILE_MAX) and resolved in small concurrency-limited batches.
2026-06-30 20:32:49 +08:00
DrSmoothl
b6c476390f ci: auto-close non-template issues from non-write-access users
blank_issues_enabled: false only hides the chooser link — the CLI / API /
direct URLs still create template-less issues (e.g. #174 by a CONTRIBUTOR).
This workflow enforces the policy: an issue opened by someone without write
access that carries no template label (bug / enhancement) is commented on and
closed as not-planned. Proper bug reports / feature requests and write-access
users are unaffected.

Takes effect only once on the default branch (main).
2026-06-30 20:16:59 +08:00
DrSmoothl
fc4d3a9c5d fix(protocol): set_group_name body tag 3, not 1 (#173, OIDB 1006)
set_group_name (OIDB 0x89a_15) always failed with OIDB error 1006 even
with admin rights. The group name in the body sits at tag 3, but we had
it at tag 1 — so the server rejected the malformed request structure
before ever checking permission. Confirmed against Lagrange's
OidbSvcTrpcTcp0x89A_15Body (ProtoMember(3) TargetName).

The reporter had tried tag 1 and tag 2 (both still 1006) — the answer was
tag 3. Live-verified on tempserver: with the fix the error changes from
1006 (structure rejected) to 1328 (permission — the test bot is only a
member), proving the request structure is now accepted; an admin bot will
succeed.
2026-06-30 20:14:20 +08:00
DrSmoothl
1f23e6e9f0 fix(protocol): ptt-trans md5 must be a hex string, not raw bytes (#165)
fetch_ptt_text failed for every voice with QQ errCode -1079 ("ptt
translate failed"). RE'd the cause in wrapper.linux.node: EncodeTroopPtt /
EncodeC2CPtt (ptt_trans_worker.cc) run the md5 through a bytes→hex helper
(sub_7A02D80, the 000102…ff table) before putting it in the request — so
the md5 field is a 32-char lowercase HEX STRING, but we were sending the
raw 16 bytes (hexToBytes(md5Hex)). Wrong length + encoding → server reject.

All other fields matched QQ NT exactly (verified field-by-field against
the two encoders): group {1=msg,2=sender,3=group,4=fileId,5=md5,6=dur,
7=size,8=format,9=uuid,10=event}, c2c {…,9=md5}, type 1=group/2=c2c.

Fix: md5 field is `string` (the lowercased hex), not `bytes`. Live-
verified on tempserver — errCode -1079 is gone and a real voice now
returns ASR text. (The "Live-verified end to end" claim in the old
comment was wrong; c2c had the same latent bug.)
2026-06-30 20:02:07 +08:00
DrSmoothl
0cf9cdd0d7 chore(core): diagnose ptt translate failures (#165 备选)
When QQ's ASR returns a non-zero errCode, log the request fields we
sourced from cache (md5 length / format / uuid presence / duration /
size) alongside the errCode, so a server-side ASR failure can be told
apart from our own missing/zero field. Behaviour unchanged — still
throws. Helps diagnose the "ptt translate failed" instability reported
in #165 before deciding whether it's our bug.
2026-06-30 19:31:20 +08:00
DrSmoothl
90456def2e feat(onebot): get_record out_format — server-side voice transcode (#165)
#165: get_record gains an optional `out_format` (mp3/amr/wma/m4a/spx/ogg/
wav/flac, mirroring NapCat). When set, the QQ voice (SILK/AMR) is
transcoded server-side and the result is attached as `data.base64`; the
original info (file/url/file_size) is preserved. Absent ⇒ behaviour
unchanged. This spares ASR consumers from shipping a SILK decoder.

- protocol: convertAudioBytes(bytes, format, deps?) drives the bundled
  SILK-capable ffmpeg addon's convertFile through temp files (always
  cleaned up), with a format allowlist and an output-size cap. Pure/
  injectable, unit-tested with a fake addon (6 cases).
- core: ExtrasApi.convertRecord(source, format) = loadBinarySource (64 MiB
  cap) → convertAudioBytes.
- onebot: get_record wires out_format; transcode failure (incl. an addon
  lacking SILK decode) degrades to ACTION_FAILED, never crashes.

Adversarially reviewed: no path traversal (format allowlisted), no SSRF
(source is the cached CDN url, not user input), cleanup covers every path,
graceful degradation confirmed. Catalog regenerated. Real-machine e2e
(does the shipped .node actually decode SILK?) is Phase 2.
2026-06-30 19:25:40 +08:00
DrSmoothl
8fc5917b3b fix(webui): align message composer/builder (Apple-HIG)
Two alignment fixes in the 消息构建 tab:
- MessageBuilder is now a bounded "compose canvas" (always bordered) so the
  empty hint reads as an intentional empty state inside a defined input
  region, instead of a stray centered line floating in the left-aligned
  form.
- The 账号 / 目标 label rows are pinned to a fixed h-8 (== the 群聊/私聊
  segmented control's height) so both labels and the selectors beneath them
  share a baseline — min-h-7 wasn't enough since the segmented is ~32px.
2026-06-30 18:57:54 +08:00
DrSmoothl
65195abbe0 fix(mcp): add role/stream to Catalog types to match generated catalog
Phase 0 added `role` to FieldDoc and `stream` to ActionDoc and regenerated
catalog.ts, but the mcp package's own CatalogParam/CatalogAction types
(intentionally decoupled from onebot per ADR-0005) weren't updated — so
`tsc --noEmit` failed on the generated catalog.ts (TS2353, unknown
properties role/stream). The mcp vitest suite passed because esbuild
doesn't type-check the generated snapshot, which is why this slipped.

CatalogParam gains role?: string (loose, to stay decoupled from onebot's
FieldRole union); CatalogAction gains stream?: boolean. `pnpm typecheck`
is green across all packages.
2026-06-30 18:45:34 +08:00
DrSmoothl
d5fbd6fa06 feat(webui): multi-tab debug console + embedded API browser
Phase 6 of the debug-console expansion — the four pieces become one
console: 测试台 / 消息构建 / 实时活动 / API 浏览器, behind an Apple-HIG
sliding-indicator tab bar.

- ApiBrowser: a searchable, category-grouped reference for every
  declarative action (~520), straight from /api/debug/actions — params /
  returns / invariants / role + readOnly + stream badges. Each row's 试一下
  prefills the tester and switches to it (ActionTester gains a
  presetAction prop keyed by nonce).
- Tester / compose / activity stay MOUNTED and toggle via CSS, so the
  live feed's SSE never drops — it keeps capturing events fired while you
  invoke from the tester tab (the invoke-then-observe loop) — and
  in-progress params/messages survive a peek at another tab. The API
  browser, heavy and stateless, mounts on demand.

Adversarially reviewed: no crash / leak / mis-trigger; the review caught
that conditional-mounting silently dropped cross-tab live events and
discarded in-progress work — fixed by keeping the stateful panels mounted.
2026-06-30 17:40:04 +08:00
DrSmoothl
383ddb0a5d feat(webui): visual message builder + composer (nested forward)
Phase 5 of the debug-console expansion. A drag-reorderable segment
builder so you never hand-write a OneBot message array: common segments
first-class (text / @ / image / face / reply / record / video), advanced
folded (file / mface / poke / json / xml / markdown / forward-node), with
`node` nesting a full builder (merged forward, depth-capped). @ uses the
group member picker via the sibling group context; media via FileSource.
Each segment carries a stable `_id` key so editing a field never remounts
the row.

- MessageBuilder + toOneBot() serialise to the exact OneBot v11 shapes
  SnowLuma's parser reads (verified field-by-field).
- MessageComposer (the 消息构建 tab): pick target, build, preview, send —
  routing through send_*_forward_msg when the message has nodes, else
  send_*_msg. Refuses a mixed node/non-node forward (the backend would
  silently drop the stray segments) and validates incomplete segments
  before sending.
- ParamField renders the builder for message-type params in the tester
  (raw-text escape hatch kept), emitting the serialized array as the
  string value.

Adversarially reviewed: serialization contract and React key/focus both
verified clean (no _id leakage); fixed the mixed-forward silent-drop,
added pre-send segment validation, and made the drag boundary explicit.
2026-06-30 17:31:51 +08:00
DrSmoothl
11866caa2f feat(webui): role-driven action tester with streaming + history
Phase 4 of the debug-console expansion — the tester no longer makes you
hand-write JSON. Each param renders the right smart control from its
semantic role: group/friend/member pickers (member linked to the sibling
group_id), FileSource for media, FaceGrid, datetime for timestamps,
switch for bool, select for enum — with the raw-JSON escape hatch kept.

- Read-only actions badge green, side-effecting amber; a name-pattern set
  of destructive actions (kick/ban/recall/delete/…) confirms first.
- Stream API actions invoke over /api/debug/invoke-stream and render
  frames live, tracked in the app-level task registry with progress; a
  clean success requires the terminal response frame, and a failed frame
  shows its reason (not just the {type:'error'} marker).
- Every call lands in capped localStorage history with one-click replay;
  responses render in a collapsible JsonTree.
- Extracted LiveActivity (filter / search / export) and the Segmented
  control into their own components; debug-page is now a thin host.

Adversarially reviewed: stream terminal-frame judging, member/group
linkage, and contract shapes verified; fixed the failed-stream-frame
reason being hidden, a latent required-enum controlled-select trap, stale
member value on group change, and several low UX edges.
2026-06-30 17:17:15 +08:00
DrSmoothl
c5611ed622 feat(webui): debug-console shared primitives, data layer, task manager
Phase 3 of the debug-console expansion — the Apple-HIG foundation the
new tabs build on (reusing the existing ui kit; new controls match its
idiom, no browser-native widgets).

API client + types:
- debug.invokeStream() reads /api/debug/invoke-stream via fetch + a body
  reader, parsing data:<json> SSE frames (header auth, cancellable).
- debug.upload() streams a file via XHR for real upload progress.
- DebugActionParam.role, DebugActionDoc.stream/invariants, FieldRole,
  DebugStreamFrame, DebugUploadResult.

Primitives:
- Tabs (sliding indicator + roving tabindex), Picker (searchable,
  windowed combobox with a raw-value escape hatch), JsonTree (collapsible
  response viewer, image-url preview, copy w/ http fallback, node cap),
  FileSource (URL / server-path / browser-upload tri-state), FaceGrid.

Infra:
- DebugTaskProvider + TaskBadge: app-level registry of in-flight upload/
  stream tasks so they survive in-app tab switches, with a global
  progress chip and a beforeunload guard; eviction never drops a running
  task. Wired into App.
- use-debug-contacts: lazy friend/group/member data layer, shared module
  cache + localStorage (version-stamped, avatars stripped to dodge quota)
  + TTL + request-id race guard, degrading to raw input on error.

Adversarially reviewed (no automated component tests): virtualization
math and SSE framing verified correct; fixed the stale-contacts-on-switch
member-selection hazard, the quota-kills-persistence issue, and several
low UX edges (active-row clamp, filter scroll reset, copy fallback).
2026-06-30 16:53:43 +08:00
DrSmoothl
a7667f1cd5 feat(core,onebot): debug-console stream-invoke + upload endpoints
Phase 2 of the debug-console expansion. Two backend endpoints under the
existing /api/* bearer auth:

- POST /api/debug/invoke-stream — drive a Stream API action (#163) and
  relay every frame to the browser over an SSE body. The frontend reads
  it with fetch()+a stream reader (header auth), so it needs no SSE
  query-token allowlist entry. Frames are NEVER dropped: backpressure is
  handled by waiting for the consumer to drain, not by discarding (a lost
  chunk corrupts a transfer). Non-stream actions emit a single frame.
- POST /api/debug/upload — stream a browser-selected file to a temp path
  on THIS server (the bot runs server-side, not on the operator's
  machine), so the path can feed a send action's file/image/record/video
  param. Raw bytes in the body (no multipart buffering), ?filename= for a
  readable suffix, streamed to disk under os.tmpdir()/snowluma-debug-
  upload with a 4 GiB cap and a 24h TTL sweep.

instance.invokeStream() delegates to ApiHandler.processStreamRequest.

Pure logic (filename sanitisation, fenced size-capped disk sink, the
stream-invoke Response builder) lives in debug-tools.ts with 12 unit
tests. Adversarially reviewed: path traversal is robust (19 hostile
filenames all fenced), frames provably never dropped, auth runs before
any disk write. Fixed a High found in review — the write stream had no
'error' listener (an async ENOSPC/EIO during flush would crash the whole
process) and a late-open race could leak a partial file; both now raced
into the awaits and cleaned up after 'close'.
2026-06-30 16:19:59 +08:00
DrSmoothl
c839121fdb fix(protocol): send super/new faces with the right wire encoding (#168)
A face was always built as a legacy FaceElem (face.index). QQ-NT only renders
classic small faces that way; newer 'super'/animated faces sent as face.index
are silently remapped by the server (e.g. 424→168) or shown as a placeholder.

Classify each face id off QQ's own system-face catalog (0x9154_1, ported from
SLE/Lagrange) and pick the matching wire form:
  - super (animated, aniSticker pack ≠ (1,1)) → CommonElem 37 + QFaceExtra
  - other id ≥ 260                            → CommonElem 33 + QSmallFaceExtra
  - classic id < 260                          → legacy FaceElem

The catalog is fetched once (shared, lazy-warmed off the first face send) and
classify falls back to an id-range guess until it lands. Data-driven so all 66
non-(1,1) super faces encode correctly, not just a hardcoded few.

Verified on a live account: 424→424 (was 168), super 392→392, classic 14→14.
2026-06-30 16:09:28 +08:00
DrSmoothl
f9900053b0 feat(onebot): backfill semantic roles across action params
Phase 1 of the debug-console expansion. Sweeps the 8 action files,
swapping bare coercion primitives for the role-stamped equivalents from
Phase 0 (or appending `.role()` where a `.default()`/`.optional()` field
must keep its exact coercion). Coercion is byte-for-byte unchanged; the
only intentional bound change is face_id min 1→0 (QQ face 0 is valid).

Classification (verified against each run()):
- group_id → f.groupId() everywhere.
- user_id → f.userId() for any-user / friend / stranger / private-route
  targets (send_private, friend poke, friend add/remove, stranger info,
  private file transfer, forward-to-friend, share-contact).
- user_id → f.memberId() only when it's a member of a sibling group_id
  (batch kick elements; the groupUserAction preset already injects it).
- media file/image/record + file_id → f.file()/image()/record()/fileId()
  (or .role() when defaulted/optional); message_id/timestamp/duration via
  the constructor or .role() hatch as coercion requires.

Polymorphic ids left as bare uint on purpose (no single role can honestly
describe them): mark_msg_as_read.target_id (group# or uin), bot_appid,
msg_seq, fileset_id, folder_id, chunk indices, stream_id.

Catalog regenerated: 71 group_id / 25 user_id / 9 member_id / 19
message_id / 11 file_id / 7 image / 6 file roles surfaced. Done by 4
parallel agents; adversarially reviewed — zero coercion regressions,
zero member/user misclassifications.
2026-06-30 16:00:21 +08:00
DrSmoothl
14a61f4ce8 feat(onebot): add semantic role field + stream flag to action metadata
Phase 0 of the debug-console expansion. Introduces a closed `FieldRole`
union (group_id/user_id/member_id/message_id/file_id/file/image/record/
video/duration/timestamp/face_id) orthogonal to `type` (which governs
coercion), so the WebUI debug console can render semantic pickers instead
of forcing hand-written JSON.

- FieldDoc gains `role?`; Field gains a `.role()` modifier (survives
  optional/default/describe). toJsonSchema emits it as `x-role`.
- Semantic constructors f.groupId/userId/memberId/fileId/file/image/
  record/video/duration/timestamp/faceId wrap the coercion primitives and
  stamp a role (messageId backfilled). Media sources reject '' to preserve
  the empty-string guard they replace. faceId allows 0 (valid QQ face id).
- Extracted stringCore so f.string() and string-valued roles share it.
- ActionDoc gains `stream?`; defineStreamAction sets stream:true.
- Presets: groupAction injects f.groupId(); groupUserAction injects
  f.groupId() + f.memberId() (a group action's user_id is a member of
  that group). Backfills role onto 56 group_id / 7 member_id sites.
- Regenerated MCP catalog (79 x-role, 5 stream).

Adversarially reviewed: no coercion regression, member_id stamping has
zero false positives across all 7 groupUserAction sites, x-role is inert
to MCP consumers.
2026-06-30 15:42:25 +08:00
DrSmoothl
7285db1e37 feat(onebot,mcp): catalog the Stream API actions (#163 phase 4)
Surface the six Stream API actions in the self-generated docs catalog under
a new 流式接口 category: export each module's specs as an `actions` array
(register now iterates it) and widen the doc collector's spec type to anything
carrying describe() so defineStreamAction results qualify alongside
defineAction. Regenerated the MCP catalog snapshot.

End-to-end verified on a live account over HTTP: test_download_stream (10
frames + terminal), an upload_file_stream round-trip (200 KB chunked in →
sent as a c2c file → download_file_stream back out, byte- and sha256-exact),
and the SSRF guard rejecting a cloud-metadata URL.
2026-06-30 14:40:39 +08:00
DrSmoothl
369dea582c feat(onebot): download stream actions (#163 phase 3)
NapCat-compatible server-push download: one request answered by a file_info
header, N base64 file_chunk frames, then a terminal file_complete. Bytes come
from a local file under the stream temp root, an http(s) URL, or a cached
image/voice id resolved to its QQ CDN URL. test_download_stream pushes 10
canned frames so a client can validate the transport without touching QQ.

Actions: download_file_stream / download_file_image_stream /
download_file_record_stream / test_download_stream.

Hardened beyond the NapCat original (which streams any local path and follows
redirects to anywhere), per three adversarial review passes:
- arbitrary-file-read: local reads are fenced inside the stream temp root,
  realpath-resolved so a symlink can't point out.
- SSRF: every URL (incl. each redirect hop, followed manually) is guarded —
  http(s) only, and neither the literal host nor any resolved address may be
  private/loopback/link-local; IPv6 is byte-parsed so normalized v4-mapped
  literals (::ffff:a9fe:a9fe) can't slip past. (DNS rebinding remains a
  documented residual — needs connect-time peer-IP validation.)
- robustness: TTFB-only connect timeout (doesn't cut a large body mid-stream)
  plus a per-chunk idle watchdog that aborts a stalled source so a hung
  upstream can't pin a socket; total size capped; non-2xx bodies cancelled;
  client disconnect aborts via the sink.

501 onebot tests green.
2026-06-30 14:40:39 +08:00
DrSmoothl
4f0a0f89ae feat(onebot): upload_file_stream + clean_stream_temp_file (#163 phase 2)
NapCat-compatible chunked upload: a client pushes a file in base64 chunks
across repeated upload_file_stream calls keyed by stream_id; the bot
reassembles them into a local temp file and returns its path for a normal
send. Sidesteps the 2 MB HTTP body cap and the shared-filesystem assumption
of file:// sends.

Reassembly streams chunk-by-chunk to disk (no whole-file Buffer.concat) so
an arbitrarily large upload won't OOM. clean_stream_temp_file wipes only the
stream temp dirs.

Hardened well past the NapCat original (which has all of these holes), per
two adversarial review passes:
- stream_id is allowlist-validated + every derived path fenced inside the
  upload dir — no path traversal (the original lets stream_id write/delete
  arbitrary paths).
- total_chunks / concurrent streams / per-chunk + per-stream bytes are all
  bounded — no single-request OOM or disk/fd exhaustion.
- chunk indices are claimed synchronously and only counted complete once
  flushed — no double-count race, no truncated-read-on-concurrent-complete.
- state + temp dirs are namespaced per account.

494 onebot tests green.
2026-06-30 14:40:39 +08:00
DrSmoothl
01ef98abb6 feat(onebot): Stream API transport plumbing (#163 phase 1)
Foundation for NapCat-compatible Stream API actions (chunked file
upload/download): a single request answered by many response frames.

- streaming.ts: StreamSink + frame wrappers (wrapStreamFrame /
  wrapStreamTerminal) matching NapCat's wire — each frame an OB11 envelope
  with stream:'stream-action', data.type ∈ stream/response/error, and
  message mirrored into wording.
- ApiHandler: registerStreamAction / isStreamAction; handle() threads a
  sink; processStreamRequest drives WS multi-frame dispatch with optional
  liveness-based abort; dead processRequest removed.
- action-kit: defineStreamAction (sink-aware run, registers as a stream
  action) reusing defineAction's parse/describe.
- adapters: HTTP server streams chunked \r\n\r\n-delimited frames (no
  Content-Length, no false application/json), aborting on client
  disconnect; WS server/client use a backpressure-aware safeSendAsync and
  abort a stream once the socket closes.

No stream actions are registered yet — those land in the next phases.
Verified by two adversarial review passes. 480 onebot tests green.
2026-06-30 14:40:39 +08:00
Airline233
62eb8fd763 feat: Qzone支持上传图片(发说说、评论附图) (#152)
* feat(core,onebot,protocol): support publish shuoshuo and comment with image

* Fix: Accidentally changed notes
2026-06-30 01:47:21 +08:00
DrSmoothl
547640bbfd fix(onebot): route oversized videos to the file path up front (#145)
A video larger than MAX_VIDEO_SIZE (~100 MB, QQ's video-resource cap)
uploads "successfully" — the server accepts the Highway bytes — but the
receiver sees 视频已过期 because no valid video resource is ever produced.

The existing large-video → file fallback only fired from the send catch
block, i.e. when the upload threw. An oversized upload doesn't throw, so
the fallback never triggered. Add a proactive split before the send: any
video whose source size is known to exceed MAX_VIDEO_SIZE is re-routed to
the file pipeline up front (mirrored for private and group sends). Smaller
videos (verified up to ~49 MB) are unaffected and still send as videos.

This pairs with the c2c-file fix (f8caa92): the re-routed video now rides
the now-working offline-file path and downloads correctly.
2026-06-30 01:24:00 +08:00
DrSmoothl
f8caa92333 fix(core): make c2c files >5MiB downloadable — drop stale busId, fix md5-head magic
Private (c2c) files larger than a few MiB uploaded fine but the receiver
always got "download failed" (#157). Two independent bugs in the offline-
file upload (OidbSvcTrpcTcp.0xe37 + highway cmdId 95), both confirmed on a
live account and against a plaintext packet capture of the real QQ client:

1. FileUploadExt.busiBuff carried a stale `busId: 102`. NapCat, Lagrange and
   the QQ client all emit busiBuff with senderUin only. The extra busId let
   the server accept the highway upload but never finalise it as a
   downloadable offline file once the payload passed ~5 MiB.

2. md510MCheckSum used `10 * 1024 * 1024` (10485760) as the "first 10 MB"
   limit. QQ's magic number is 0x98A000 = 10002432. With the wrong limit the
   server's first-block verification failed for any file larger than
   0x98A000, so files >~10 MB uploaded but never finalised either.

With both fixed, c2c files of arbitrary size (verified up to ~20 MB; the
general highway path has no inherent size cap) download correctly.
2026-06-30 00:13:34 +08:00
DrSmoothl
57ff0e69d8 fix(core): make c2c file 0xE37_800 finalize best-effort, not fatal (#157)
Real-machine retest showed a plain c2c file send (NotOnlineFile only, no
field6) is already downloadable — the original #157 'fix' made the 0xE37_800
finalize a hard dependency, so any finalize error would now fail a send that
would otherwise succeed (a regression, same speculative-NapCat-parity trap as
the #145 force-full).

Wrap the finalize in try/catch: on success we still attach field6 (extra
download routing that mirrors NapCat and may help some receiver clients); on
failure we log and send without it. field6 is now enrichment, not a
requirement.

Adds a regression test: a failing 0xE37_800 still produces a PbSendMsg with
the file and no field6.
2026-06-29 16:08:20 +08:00
DrSmoothl
053137669a fix(protocol): drop the ineffective video force-full-on-fast-path retry (#145)
forceFullOnFastPath re-issued the NTV2 upload with tryFastUploadCompleted:
false to try to refresh a possibly-expired video resource. Real-machine
testing on a live account + RE of the QQ NT kernel (wrapper.node) proved it
never works:
- the server's fast-path is driven by md5-metadata existence and ignores
  the flag (proton omits a false bool anyway); the retry re-fast-paths
- the kernel itself does no validity check — HandleRspUploadV3 trusts the
  response's fileExist and goes straight to SendUploadSuccFTN

So an expired-but-still-indexed video resource is a platform-level
limitation, not something the upload flow can refresh. Removing the retry
drops two wasted OIDB round-trips per cached-video re-send. The underlying
#145 (receiver '资源已过期' for a server-expired resource) remains a
platform issue, tracked separately.

Tests updated to assert the single-request behaviour.
2026-06-29 15:32:57 +08:00
DrSmoothl
37f768dd33 fix(bridge): isolate process enumeration so a blocked native call can't freeze the loop (#158)
QQ's silent hot-update churns the process table; the watcher's synchronous
native getAllMainProcess() (/proc walk reading cmdline/maps) blocks while a
process is mid-exec(). Running on the main event loop, that froze the whole
bot — OneBot stopped responding, the watcher stopped ticking, the supervisor
saw it 'alive' so never restarted it (silent death until manual restart).

- run the native enumeration in a worker_threads worker, raced against a
  deadline on the main thread; a blocked call no longer stalls the loop
- on timeout/failure return an UNKNOWN sentinel (null); PipeWatcher keeps the
  prior process+pipe snapshot instead of treating missing data as 'all QQ
  gone' (which would dispose live sessions and tear down a healthy hook)
- graceful fallback to in-loop enumeration when the addon can't load in a
  worker or there's no addon (macOS); custom listers (tests) bypass the worker
- bounded orphan workers across a sustained hang

Tests: PipeWatcher null-sentinel (no false process-gone, recovers); enumerator
sync-fallback + broken-isolation paths. Native /proc-walk hardening rides in
the nnphook repo separately.
2026-06-28 23:30:10 +08:00
DrSmoothl
5dc3ec88d4 fix(webui): smooth sidebar collapse — no reflow, centered icons, pin button
The hover-rail flipped its content to a collapsed layout instantly while the
width animated, so on every expand/collapse icons jumped toward the top-left and
labels flashed in, wrapped super-tall, then settled — and the collapsed rail
leaked the first glyph of every label plus hard-clipped highlight bars.

Lay the rail content out at a fixed width and let the aside clip it: nothing
reflows during the width animation. Icons live in a fixed centered column (never
move); labels stay mounted with nowrap and just fade out when collapsed (no
wrap, no leak); the active pill and update banner render their background as an
absolute layer that becomes a centered squircle on the rail instead of a
hard-clipped bar.

Adds the promised pin toggle to the sidebar footer (desktop) — mirrors the
「钉住侧栏展开」 appearance setting: pinned keeps the rail open, unpinned returns
to hover-to-peek.
2026-06-28 23:29:25 +08:00
snowluma-bot[bot]
688402814c Merge pull request #159 from SnowLuma/dev
chore: promote dev → main (7ec74f2)
2026-06-28 14:48:25 +00:00
DrSmoothl
7ec74f2928 chore(release): v1.10.4 2026-06-28 22:48:00 +08:00
DrSmoothl
2b15bc6710 feat(webui): group Settings sidebar into 控制台 / SnowLuma / 平台
The flat tab strip mixed three domains — the dashboard itself, the all-accounts
SnowLuma protocol runtime, and the host/platform. Regroup into 3 labelled
sections (macOS System-Settings idiom): section headers show on the desktop
rail; the mobile strip stays a flat wrap via display:contents. Each group is a
role=group + aria-labelledby; the nav gains an aria-label.

This gives '全局配置' (and future global protocol knobs) a principled home and
ends the mixing. Phase 4 (final) of the global-settings split.
2026-06-28 22:25:39 +08:00
DrSmoothl
196f98e97c feat(webui): global-config settings tab + /api/global-config
Adds a '全局配置' Settings tab that edits config/snowluma.json — the rkey
fallback-server list and the deployment-wide musicSignUrl — backed by a new
bearer-gated GET/POST /api/global-config (load/saveGlobalSettings, then
oneBotManager.reloadGlobalSettings to hot-apply to live instances).

The panel reuses the established settings-panel idiom (Input/Button/Label,
debounced auto-save, flash); rkey servers are an inline add/remove list with
client-side http(s) validation hints. It deliberately does not reconcile inputs
from the server's normalized response (would erase a half-typed URL); a
load-failure shows an error+retry, and the save toast says '无效项已忽略' when
the server would drop an entry.

Removes the now-dead per-UIN musicSignUrl form (moved to global in Phase 2).
Phase 3 of the global-settings split (nav grouping is Phase 4).
2026-06-28 22:16:07 +08:00
DrSmoothl
ea1c5ff9eb feat(onebot): migrate musicSignUrl from per-UIN to global config
musicSignUrl is a deployment-wide signing-service endpoint (same for every
account), so it belongs in the global config/snowluma.json next to rkey, not in
per-UIN onebot_<uin>.json.

- GlobalSettings gains musicSignUrl (http(s)-validated, '' = built-in default);
  consumption switches to globalSettings.musicSignUrl and hot-reloads via
  applyGlobalSettings.
- One-shot copy-up at boot (migrateGlobalSettings, called first in main()):
  lifts the first VALID legacy value from any config/onebot*.json into the
  global store. Idempotent via a key-PRESENCE guard, so an intentional
  clear-to-'' is never reverted by a stale legacy value.
- Remove musicSignUrl from per-UIN OneBotConfig (type + parse/serialize).

Phase 2 of the global-settings split. (WebUI form follows in Phase 3.)
2026-06-28 21:38:32 +08:00
DrSmoothl
659970077a refactor(onebot): move rkey fallback from per-UIN to a global config store
The rkey fallback endpoint is deployment infra (one self-hosted server serves
all accounts; fallback rkeys are fungible), so it doesn't belong in per-UIN
onebot_<uin>.json. Introduce config/snowluma.json — a generic home for small
all-accounts SnowLuma settings — and move rkey.fallbackServers there.

- New onebot/global-config.ts: load/save/normalize with section-merge + atomic
  write; http(s)+host URL validation; default [] (off). Lives in onebot (not
  core) because the onebot manager constructs instances and must not depend on
  core.
- OneBotInstance takes globalSettings; manager loads it on session start and
  exposes reloadGlobalSettings() to hot-push edits to every live instance via
  applyGlobalSettings → RKeyCache.setFallbackServers.
- Remove rkey from per-UIN OneBotConfig + the WebUI per-UIN round-trip (never
  released, so no migration). Register snowluma.json in the backup allowlist.

Reworks the per-UIN rkey from 12b0190. Phase 1 of the global-settings split.
2026-06-28 20:52:07 +08:00
DrSmoothl
5d39cf5782 fix(core): finalize c2c file upload so the recipient can download (#157)
Private (c2c) file sends uploaded the bytes (apply 0xE37_1700 + Highway)
and PbSendMsg returned ok, but the receiver saw "文件传输失败": the message
carried only FileExtra.file (metadata) and not the server-issued download
routing. Group files use a different element, hence c2c-only.

Port NapCat's upload→finalize→send sequence:
- add 0xE37_800 (FinalizeOfflineFile) OIDB service, run after the Highway
  PUT to fetch the download metadata (field30)
- extend FileExtra with field6 (PrivateFileExtra.field2) and populate it
  from that metadata in sendC2cFile; covers both the url-upload and the
  file_id-resend send paths (both funnel through sendC2cFile)

Tests: byte-oracle locks the 0xE37_800 request + FileExtra.field6 tags;
core routing test now asserts finalize runs and field6 is populated.
Needs real-machine verification (send a private file, confirm download).
2026-06-28 20:11:17 +08:00
DrSmoothl
12b01907bc feat(onebot): opt-in remote rkey fallback server (#156)
On accounts where the native OIDB 0x9067_202 rkey fetch persistently returns
nothing, every image was served as a bare multimedia.nt.qq.com.cn URL the CDN
rejects with invalid rkey — SnowLuma had no fallback, unlike NapCat.

Add config.rkey.fallbackServers (default []: OFF; no third-party server is
contacted unless the operator configures one). When the native fetch leaves the
cache without a usable image rkey, each configured HTTP endpoint is tried in
turn for { group_rkey, private_rkey, expired_time } (NapCat rkey-server format;
an OneBot { retcode, data } wrapper is also accepted), populating the group/
private image rkey types. Values keep any leading &rkey=/?rkey= since
resolveImageUrl strips before re-appending.

WebUI has no form yet but round-trips rkey.fallbackServers verbatim so a hand-
edited value survives an unrelated config save. Part B of #156 (cooldown is A).
2026-06-28 01:37:58 +08:00
DrSmoothl
219d60410a fix(onebot): prefer real url over unresolvable file id in media segments
When a bot framework echoes a received image/voice/video, it resends the
original `file=<md5>.ext` (a QQ-internal media id) together with the
download `url`. The parser collapsed sources as `file ?? url ?? ...`, so
`file` won and the send path statSync'd the id as a local path → ENOENT
(retcode 1200). Reported in #155 for images via Yunzai复读.

Add pickMediaSource(): keep `file` when it is directly loadable (inline
base64/data bytes, a remote url, or a path with a separator); otherwise
fall back to a sibling http(s) `url`. Applied to image/record/video.

Tests cover the #155 echo case plus the path/base64-wins guards.
2026-06-28 01:33:07 +08:00
DrSmoothl
182df4b0e2 fix(onebot): retry rkey fetch eagerly while cache holds none (#156)
When the OIDB 0x9067_202 rkey fetch returns empty or fails, the cache stays
empty and resolveImageUrl hands out a bare multimedia.nt.qq.com.cn URL the CDN
rejects with {retcode:-5503010, invalid rkey}. The 30s refresh cooldown then
blacked out every image for 30s+ after each empty/failed fetch.

Use a short RKEY_EMPTY_COOLDOWN (10s) whenever no usable image rkey is cached,
keeping the 30s steady-state backoff only once we actually hold one — so a
transient empty fetch self-heals in seconds instead of 30s. (Part A of #156;
remote-server fallback follows.)
2026-06-28 01:25:19 +08:00
DrSmoothl
6c2a3fc325 fix(ci): strip ANSI before matching TRACE in needs-logs bot
The needs-logs workflow tested /\bTRACE\b/i against the raw issue body.
Pasted terminal logs wrap the level in ANSI color codes (\x1b[90mTRACE\x1b[0m);
the trailing 'm' of the color code abuts 'TRACE', so the leading \b never
matches and a log that clearly contains TRACE is wrongly flagged needs-logs
(e.g. #156). Strip ANSI escapes first, and measure the too-short heuristic on
the cleaned text too.
2026-06-28 01:25:03 +08:00
DrSmoothl
5eaac0870c feat(webui): scale notification-channel opt-in to large lists
The per-account 上下线通知渠道 picker rendered every global channel as a
flat toggle row, so 40+ channels produced an unbounded, messy wall inside
通用设置. Rework it into a collapsible control:

- collapsed: one-line summary — selected count badge + selected channels
  as removable chips (cap 8, then "+N 更多")
- expanded: description + name/url search filter + 全选/清空 bulk actions
  + a height-bounded ScrollArea list (max-h-64) so it never blows up
- globally-disabled channels stay locked off; data flow unchanged

Reuses Badge / ScrollArea / ToggleSwitch / Input.
2026-06-28 01:23:12 +08:00
DrSmoothl
04591517fa feat(webui): redesign adapter edit dialog (Apple-HIG) + custom dropdown
Rework the OneBot adapter create/edit modal into an iOS grouped-list
layout matching the debug-page language: captioned soft-card sections,
a per-kind icon chip, settings rows, and staggered motion entrance.

- reportSelfMessage: segmented control -> shared ToggleSwitch
- messageFormat (+ WS role): segmented/native select -> new custom
  DropdownSelect (accessible listbox, keyboard nav, spring popover)
- enable toggle promoted to a prominent top card
- new components/ui/dropdown-select.tsx (zero new deps, hand-rolled)

Presentation-only; draft/validation/data flow unchanged.
2026-06-28 01:14:37 +08:00
DrSmoothl
e1f5267764 fix(onebot): make group large-video file fallback actually fire
#153 added a video→file fallback but the group side was dead code: it
lived in element-builder behind `isGroup && element.fileId`, and a video
sent by url/path has no fileId, so oversize group videos just rethrew the
raw Highway error (real bot: `error_code=323` on a 1.4 GB group send).

Move the fallback to the OneBot layer for groups, mirroring the private
path: on a failed Highway send, re-route oversize videos through
groupFile.upload. Verified on a live bot — a 1.4 GB group video now lands
as `[文件:video.mp4]` instead of failing.

Extract the shared heuristic (isHighwaySizeError / videoNeedsFileFallback
/ splitVideoFileFallback) so private and group stay in sync, and drop the
now-unreachable element-builder video catch. Adds send-video-fallback
tests covering both the known-oversize and remote-error-heuristic paths.
2026-06-27 16:27:33 +08:00
stla
85182795b5 feat(protocol,onebot): raise video size limit with Highway-first fallback (#153)
Round 3: fix hardcoded 4096 MB in error messages
- Use MAX_VIDEO_SIZE_HARD constant instead of hardcoded 4096 MB
- Both throw sites now derive limit from the same constant
2026-06-27 16:10:25 +08:00
DrSmoothl
70fd40e34c chore(mcp): regenerate catalog after returnsSchema backfill 2026-06-26 23:08:38 +08:00
DrSmoothl
0e8a194d4f feat(onebot): backfill returnsSchema on remaining read-only actions (c2: source-proven only) 2026-06-26 23:05:52 +08:00
DrSmoothl
d2490787ae feat(onebot): backfill returnsSchema on info/group-info read-only actions 2026-06-26 22:44:10 +08:00
DrSmoothl
0163af979a fix(ci): robust catalog sync (untracked-file guard, mkdir, rebase) + stale-catalog gate 2026-06-26 22:03:42 +08:00
DrSmoothl
75f14540c8 ci: sync action catalog.json to SnowLumaDocs via bot on release 2026-06-26 22:03:42 +08:00
DrSmoothl
5e0d2db8b2 feat(mcp): emit catalog.json twin + carry returnsSchema in catalog 2026-06-26 22:03:42 +08:00
DrSmoothl
18014fb3c5 feat(onebot): backfill returnsSchema on representative read-only actions 2026-06-26 22:03:42 +08:00
DrSmoothl
355cce1e52 feat(onebot): add optional returnsSchema to action doc metadata 2026-06-26 22:03:42 +08:00
游手好闲的言柒
04a9016a7d fix(onebot): strip at segments from private messages (#151)
* fix(onebot): support inline file url/path in send_group/private_msg

* test(onebot): update file segment parser test for inline url/path support

* fix(onebot): strip at segments from private messages
2026-06-26 21:08:01 +08:00
DrSmoothl
cf7de9f7bd chore: update vite version to ^8.0.16 in pnpm-workspace.yaml 2026-06-26 19:59:58 +08:00
snowluma-bot[bot]
a60385c376 Merge pull request #150 from SnowLuma/dev
chore: promote dev → main (351db57)
2026-06-26 11:50:10 +00:00
DrSmoothl
351db573d8 chore(release): v1.10.3 2026-06-26 19:49:41 +08:00
DrSmoothl
3b023b3275 fix(protocol): collapse ark/card messages structurally, not by string match (#146)
Follow-up to the previous #146 fix, which dropped QQ's compat fallback text by
content-matching the "版本不支持 … 升级" family. RE of the QQ kernel
(wrapper.linux.node) showed that is not how QQ does it:
- the receiver binary contains NONE of these fallback strings, so QQ cannot be
  matching by content;
- the on-target wire is [lightApp, text(compat), generalFlags, extraInfo] and the
  text element has no distinguishing marker (no pbReserve / attr6Buf);
- QQ NT's kernel codec (msg_codec_mgr) collapses the message to a single ark
  element — the sibling text is never emitted. NapCat maps kernel elements 1:1
  with no ark-aware skip yet still surfaces only the card, confirming the kernel
  drops it upstream.

Switch to that structural rule: when a lightApp/richMsg card is present, drop
sibling plain text outright. It is version/locale-proof (won't break when Tencent
rewords the string) and matches QQ NT + NapCat output exactly. @ mentions /
replies / faces are not plain text and survive; QQ clients can't attach a caption
to a card anyway, so no QQ-origin message loses real text.

Verified live on a logged-in build: get_msg returns a single json segment.
2026-06-26 18:31:43 +08:00
DrSmoothl
319c7d607d fix(protocol): drop QQ ark-compat fallback text beside mini-app cards (#146)
A QQ mini-program / ark share (B站 video, QQ 小程序, …) arrives on the wire
as a lightApp/richMsg ark element followed by a plain text element carrying
QQ's graceful-degradation compat string "当前QQ版本不支持此应用,请升级". That
text is meant only for protocol-old clients that can't render the card; QQ NT
and the kernel-backed bridges (NapCat) surface just the card.

On-target capture (test group) confirmed the text element has no distinguishing
wire marker (no pbReserve / attr6Buf) — it is a bare text sibling of the ark.
SnowLuma was decoding both, so every mini-app card came through as the card
plus a spurious "当前QQ版本不支持" text segment.

Drop the compat string when it sits beside a card, matched narrowly (the
"版本不支持 … 升级/更新" family, <=40 chars) so genuine user captions sent
alongside a card are preserved.

Verified live on a logged-in build: get_msg now returns a single json segment.
2026-06-26 18:08:26 +08:00
DrSmoothl
9de12db447 fix(onebot): align file-url actions with NapCat param tolerance (#147)
get_private_file_url required file_hash (and user_id), but NapCat needs
only file_id — it re-derives the hash from its composite file_id. Make
user_id and file_hash optional; the empty hash is accepted on the wire
(SnowLuma's private file_id already carries the md5 prefix). Verified
live: only-file_id returns a working URL (148237B download matches).

get_group_file_url rejected a present non-numeric busid with
`expected an integer` after the f.int().default(102) refactor, while
NapCat/LLBot omit busid entirely and ignore any value. Restore the
legacy `asNumber(busid) || 102` tolerance via f.raw()+busidOr102.
Verified live: null/"102"/omitted/"abc" all return a working URL.
2026-06-26 17:34:16 +08:00
DrSmoothl
ecea72df40 test(onebot): expect forced full video upload retry on stale fast-path
The NTV2 fast-upload video test still asserted a single sendRawPacket
call, but #145 (forceFullOnFastPath) re-issues the OIDB request with
fast-upload disabled when a flagged main file carrying real bytes is
fast-pathed by the server. The stale assertion was never caught because
the dev push workflow doesn't run the suite — only the PR gate (ci.yml)
does, so it first surfaced on #149.

Assert two packets go out and that the second round drops
tryFastUploadCompleted, locking #145's behavior at the onebot layer.
2026-06-26 17:09:18 +08:00
DrSmoothl
214287da28 ci(issues): auto-close stale needs-logs reports
Daily stale sweep over issues still labeled needs-logs: mark stale after
7 days of inactivity, close (not_planned) after another 7. Issues that
get valid logs lose the needs-logs label and are skipped by only-labels.
PRs are excluded.
2026-06-26 17:05:50 +08:00
DrSmoothl
81969a4590 ci(issues): enforce TRACE logs on bug reports via github-script
Form validation can only force a field non-empty, not validate content.
On bug issue opened/edited, parse the TRACE-log section: if empty, missing
a TRACE marker, or too short, label needs-logs + post a one-time guide
comment; auto-remove the label once the reporter edits in valid logs.
2026-06-26 17:05:50 +08:00
DrSmoothl
860848a310 feat(issue-template): require TRACE-level logs in bug reports
- Make the logs textarea required so a bug report can't be submitted empty.
- Document how to enable TRACE: WebUI server log-level switch (+ '开发'
  preset so the export actually contains trace lines) or SNOWLUMA_LOG_LEVEL=trace.
- Add a required preflight checkbox attesting TRACE logs are attached.
2026-06-26 17:05:50 +08:00
Airline233
39338c3f1d fix(protocol,onebot): generate and send ark of contact cards correctly (#149) 2026-06-26 17:04:40 +08:00
Airline233
02de2acea4 fix(core): support file sources in forwarded messages (#144)
Pre-upload file/url/base64 segments for forwarded message nodes into the
target scope, re-upload cached file_ids when crossing private/group scope,
and suppress standalone file-message publishing during forward preparation.
2026-06-25 20:55:39 +08:00
DrSmoothl
3eba2a677c fix(highway): force full video upload when server fast-paths a stale resource (#145)
Group/c2c video resources expire server-side. When the bot re-sends a
video whose md5 the server already cached, the NTV2 OIDB returns no uKey
for the main file (fast-upload hit) and SnowLuma trusted it — the send
"succeeds" but the receiver sees 资源已过期, because the reused object had
expired. Confirmed by the reporter: same MP4 fast-paths and breaks, but
mutating one byte (new md5) forces a full upload and plays fine.

Add a per-sub `forceFullOnFastPath` flag on MediaSubFileUpload. When a
flagged sub-file (video main) carries real bytes but the server fast-paths
it, runNtv2Upload re-issues the OIDB request with tryFastUploadCompleted
disabled (proton drops a `false` bool, which the server reads as "no
fast-upload"), forcing a fresh resource + full PUT. The thumb stays
fast-path-OK so a cached thumb never re-pushes the main video; forwarding
paths carry no bytes so they never trigger the retry.

Also fixes the observability gap the reporter hit: the main file being
silently skipped on a fast-path now logs explicitly, and so does the
forced-retry, instead of only the thumb PUT showing up.

Note: the retry relies on the server treating an absent
tryFastUploadCompleted as "no fast-upload" — needs real-device
confirmation that the forced round actually returns a uKey.
2026-06-25 20:52:11 +08:00
stla
78b0e1a124 feat(webui): auto-compress per-core density grid to fixed container (#140) (#141)
Replace fixed grid-cols-8 per-core bar display with dynamically
computed square grid that fills a fixed-height (80px) container.

- Adds bestGrid() utility that finds optimal (cols,rows) partition
  by minimizing empty cells and aspect balance
- Grid uses grid-template-rows: repeat(N, 1fr) for equal row height
- Empty cells filled with hidden divs for stable layout
- Preserves existing color tokens (bg-muted, bg-primary/70, rounded-sm)
- No scrollbar regardless of core count (tested up to 256)

Closes #140

Co-authored-by: SnowLuma Dev <dev@snowluma.local>
2026-06-25 20:46:16 +08:00
DrSmoothl
feaa94bec7 build(core,runtime): native websocket-darwin-arm64.node + drop build hatch
WebSocket native is now built for darwin-arm64 — source is at
github.com/SnowLuma/snowluma-websocket (cmake-js + node-addon-api,
clones to dev/snowluma-websocket and builds with `npm install`).

  npm install in dev/snowluma-websocket → build/Release/snowluma_ws.node
  cp → packages/runtime/native/websocket-darwin-arm64.node (102 KB)

Reverts the SNOWLUMA_BUILD_SKIP_NATIVES escape hatch in vite.config.ts
that 67f8bf3 added — no longer needed; the darwin native binary is
present. Keeps `packages/core/config/.gitignore` (independently useful
runtime-state hygiene). vite build now runs clean on darwin with no
env overrides; the runtime SNOWLUMA_DEV_NO_NATIVE=1 stub also becomes
optional (only needed if the operator wants to bypass WebSocket I/O
specifically).

Existing native binaries unchanged. CI invariant restored: every
release build must include every platform's native set.
2026-06-25 16:25:56 +08:00
DrSmoothl
67f8bf3941 build(core): SNOWLUMA_BUILD_SKIP_NATIVES=1 escape hatch for darwin dev
Two architectural cleanups that complement the bridge darwin support in
7343ae6, both opt-in / default-safe:

1) `vite.config.ts` — gate the missing-native build error behind
   `SNOWLUMA_BUILD_SKIP_NATIVES=1`. Default behaviour (no env) still
   throws as before, so the CI invariant "release builds must carry the
   full native set" is untouched. Darwin developers without prebuilt
   `websocket-darwin-arm64.node` (source lives in a separate private
   build repo) can now run `SNOWLUMA_BUILD_SKIP_NATIVES=1 pnpm build`
   and pair it with the runtime `SNOWLUMA_DEV_NO_NATIVE=1` stub at
   `node dist/index.mjs` boot. The qq-hook path (separate addon) is
   independent and unaffected.

2) `packages/core/config/.gitignore` — `runtime.json` is the only
   tracked deploy-time override file in that dir; every other config
   file is per-instance runtime state written by the daemon/dev server
   (admin password hash, EULA consent, per-uin OneBot binding, WebUI
   layout). Previously they showed up as 5 untracked files after every
   `pnpm dev:mode`, polluting `git status` and risking accidental
   commit of local creds via `git add -A`. Pattern: ignore everything
   except `runtime.json` (and the .gitignore itself).

No code paths changed; both are operator-experience fixes for running
SnowLuma on darwin against the nnphook DYLD_INSERT hook.
2026-06-25 14:27:59 +08:00
DrSmoothl
7343ae6372 feat(bridge): darwin support — DYLD_INSERT-style hook discovery
Adds the missing macOS branch so HookManager + PipeWatcher discover QQ
processes when the dylib is injected via DYLD_INSERT_LIBRARIES (the
in-process injection model used by apps/qq/macos/qq_hook_dylib.cpp in
the nnphook private repo, vs Linux's out-of-process ptrace + N-API
addon model and Windows's manual-PE-loader injection).

Two small changes:

1. `linuxRuntimeDir()` (qq-hook-client.ts) — name kept for callsite
   stability; the function now applies to every non-win32 platform.
   New darwin branch prefers `$TMPDIR/snowluma-hook/` to match the
   dylib's `runtime_dir()` (apps/qq/macos/qq_hook_dylib.cpp). The
   Linux `/tmp/snowluma-<uid>` fallback stays as the last resort.
   $TMPDIR is per-user under /var/folders/ on stock macOS, which is
   the right place — /tmp/snowluma-<uid> doesn't exist by default.

2. `listSnowlumaPipePidsSync()` (qq-hook-client.ts) + darwin branch
   in `listHookProcesses()` (injector.ts) — on macOS there is no
   native enumerate-QQ-processes addon (DYLD_INSERT obviates the
   need; the dylib is already mapped in QQ when SnowLuma launches).
   The watcher's `listProcesses` dep is sync, so we provide a sync
   directory scan that returns the pids encoded in mojo.<pid>.control.sock
   filenames. The subsequent async `listLivePipes()` still gates the
   pipe-up emit via a real connect probe — a dangling socket file
   from a force-killed previous run can't drive a false connect.

Without these two changes, `pipe-watcher.tickOnce()` filtered out our
QQ pid at line 170 (`if (!newKnownPids.has(pid)) continue;`) because
`listProcessesNative()` returned []. The pipe stayed live (verified
by our nnphook recv hook firing), but the bridge never emitted
'pipe-up', HookManager never auto-loaded the session, and the WebUI
showed an empty process list.

Verified end-to-end against the resigned QQ 6.9.96-49738 + nnphook
gpt54 branch dylib on macOS 26.5.1 (Tahoe) arm64:

  * Direct HookManager harness picks up PID=16032 in <2.5s,
    fast-paths to 'reconnect' (the live-pipe-skip-injection branch
    in hook-session.ts:200), pipe connected, status=loaded
  * `pnpm dev` (SNOWLUMA_DEV_NO_NATIVE=1 for the websocket stub):
    /api/processes returns the live QQ entry with method=reconnect,
    connected=true, awaiting login

The websocket darwin-arm64.node native addon is still missing — set
SNOWLUMA_DEV_NO_NATIVE=1 to dev-mode boot with the existing stub
fallback. That's a separate runtime artifact and not in scope here.

`shouldAutoLoadPid()` returns true on non-linux without further checks
(no Electron-child-process scanning needed on darwin), and the
`hook-session.ts` "pipe already live → reconnect" fast path means
the bridge never tries to invoke the non-existent darwin native
injector. Auto-load on a freshly discovered macOS QQ is therefore
safe with or without `SNOWLUMA_HOOK_AUTOLOAD=1`.

Tests: bridge typecheck + 62 unit tests still pass.
2026-06-25 02:53:44 +08:00
stla
41bad7f24c feat: make #sl status command trigger configurable (exact match, max 32 char) (#138)
* feat: make #sl status command trigger configurable (exact match, max 32 char)

The trigger word for the built-in #sl status command is now configurable
via statusCommand.trigger, with exact case-insensitive matching preserved.

* chore: reject control chars in trigger + add sync assertion
2026-06-25 01:02:17 +08:00
DrSmoothl
19c03eb0ba chore(gitignore): ignore per-package runtime data dirs (**/data/)
The root /data/ rule is anchored to the repo root and missed
packages/<pkg>/data/<uin>/*.db that IdentityService writes to cwd during
tests. Add a recursive **/data/ so those test artifacts stay untracked.
2026-06-25 00:21:21 +08:00
DrSmoothl
fbc5a3c981 refactor(core): use @snowluma/common/coerce in config normalizers
Phase 2. notifications/config and webui/ui-config dropped their verbatim-
duplicated isObject/boolOr/clampInt (+ ui-config clampNum) in favor of the
shared @snowluma/common/coerce. Pure delete-and-import: the shared
primitives are byte-identical to the originals (adversarially verified),
so behavior is unchanged.

Kept local: strOr (notifications-only), oneOf/isFiniteNum/hexOr
(ui-specific). notifications-config suite green (21), core+common
typecheck clean.
2026-06-25 00:05:46 +08:00
DrSmoothl
1ce7385d1e feat(common): add zero-dep scalar coercion primitives (coerce)
Phase 1 of de-duplicating config normalization. isObject/boolOr/clampNum/
clampInt were copied verbatim across notifications/config and webui/
ui-config; give them a single home as @snowluma/common/coerce (new
per-file subpath export, zero deps — fits common's leaf-utility charter).

Byte-identical to both originals (adversarially verified), so the phase-2
migration is a pure delete-and-import. clampInt is clamp-then-trunc;
10 table tests pin types, numeric-string coercion, non-finite→fallback,
bounds, and the clamp/trunc order. Not yet wired into consumers.
2026-06-25 00:01:39 +08:00
DrSmoothl
3a4af38842 refactor(onebot): lift bootstrap-meta framing into the network adapter base
Phase 1. The connect/enable/heartbeat bootstrap triplet was built +
shaped + stringified + null-dropped identically in WsServerAdapter and
WsClientAdapter. Lift that into IOneBotNetworkAdapter:

- metaFrame(event, options): string|null  — shape via shapeEventForAdapter
  then JSON.stringify, or null when the shaper drops it
- bootstrapMetaFrames(options): string[]  — the 3 bootstrap events,
  framed and null-filtered

Both ws adapters' sendBootstrapMetaEvents become one-liners over
bootstrapMetaFrames (ws-client keeps its role guard at the call site);
ws-server's close() disable broadcast reuses metaFrame. Base now owns
the shape+serialize policy, adapters own only the transport — same
shape as ADR-0009's reload template method.

Behavior-preserving (adversarially verified byte-for-byte); the two ws
adapters drop their now-unused shapeEventForAdapter import. Safety net
(network-bootstrap-meta, 9 tests) green.
2026-06-24 23:40:31 +08:00
DrSmoothl
e11601bfec test(onebot): characterize network bootstrap-meta behavior (safety net)
Phase 0 of the bootstrap-meta deepening. No production code; pins the
observable behavior the phase-1 base-class lift must preserve:

- shapeEventForAdapter shaping policy (meta passthrough, message_sent
  drop under !reportSelfMessage, string-format raw collapse)
- ws-client emits [connect,enable,heartbeat] on open, role-guarded,
  and skips a frame that shapes to null (options genuinely threaded)
- ws-server sends the triplet to an Event connection and broadcasts a
  single disable on close(), skipping Api connections on both paths

Adversarially hardened: two gaps (null-drop/options-threading, close
Api-skip) were found via surviving mutations and closed. 9/9 green.
2026-06-24 23:35:07 +08:00
DrSmoothl
a305afbc76 fix(webui): observable projector wedge + tighten non-array fallback
Round-2 follow-up. Two small holes flagged by the adversarial review of
the connection-diff-loop projector:

- A projector that starts throwing only after a shape regression would
  wedge the diff baseline silently — no publishes, no log, the only
  symptom is the dashboard's connections card freezing until restart.
  Latch a one-shot console.error on the first throw so the failure is
  visible without re-running the loop locally.

- The non-array fallback at the projector site in server.ts returned
  `acc.adapters` verbatim, which would re-introduce volatile fields if
  the snapshot shape ever drifts. Tighten to `[]`.

Also documented the deliberate trade-off: per-second adapter `detail`
rotation (client count, last-delivery HH:MM:SS) refreshes on the next
SSE push or the 30s REST reconcile rather than in real time. The user's
original bugs were about process/account edges (which DO push
instantly); detail-string freshness was not in scope. If it becomes one,
surface client-count as a structured AdapterStatus field instead of
parsing the localised `detail`.

437/437 core green.
2026-06-24 23:17:26 +08:00
DrSmoothl
84cdd99868 fix(webui): dropped-frame reconcile + split systemInfo cadence + diff-loop unref
Three findings from the adversarial review, all in the WebUI integration:

D: SSE {kind:'dropped'} now triggers a one-shot REST refresh of
   qq-list/processes/connections instead of being silently ignored.
   Reasoning: when createFramePusher drops frames under backpressure, the
   NEXT delivered frame is per-resource (only the resource whose debounce
   timer next fires) — NOT a refresh of all 3. If the dropped frame was
   the only update for a slow-changing resource (e.g. connections stable
   afterwards), the WebUI stays stale until the 30s reconcile. The
   refresh is fire-and-forget; each refresh helper already swallows errors.

E: systemInfo gets its own fast useEffect on the user's pollInterval
   (default 3s). The earlier commit slowed it to 30s claiming the data was
   'daily cadence', but SystemInfo carries live values (uptime,
   cpu.loadAvg, memory.usagePercent, runtime.heapUsed) that the overview
   widget animates — 30s is a visible regression. The other 3 resources
   stay on the 30s SSE-reconcile fallback.

F: connection-diff-loop's setInterval is now .unref()'d (mirrors the
   tokenJanitor pattern at server.ts:462). The discarded handle is now
   commented as intentional — initWebUI has no shutdown path, so the
   handle has no consumer; unref is the right cleanup primitive.

WebUI typecheck clean. 437/437 core suite (no behavior change in core
tests — only the diff-loop file's timer.unref?.() call is new and is
optional-chained so vitest's fake timers don't crash).
2026-06-24 23:05:25 +08:00
DrSmoothl
bae9f8edb0 fix(webui): connection-diff-loop compares ONLY level — strip detail timestamps
Adversarial review caught: HttpPostAdapter.describeStatus() embeds
HH:MM:SS in 'detail' (e.g. "上次推送 14:53:01"). Every webhook delivery
rotates that string every second under any active push — and the diff
loop's raw JSON.stringify compared everything, so it published on every
500ms tick under any non-idle webhook. Net effect: SSE pushed a full
connections frame at 2 Hz, exactly the polling the loop was meant to
replace, just on the push channel.

Add an optional pickComparable projector. server.ts caller passes one
that returns { uin, nickname, adapters[{ name, kind, status }] } — the
LEVEL only, not the live-rendered detail string. The SSE handler still
ships the FULL snapshot (including detail) to the WebUI; only the diff
key is pruned.

2 new tests pin the invariant: 10 detail-only ticks → ZERO publishes; a
real status-level transition publishes exactly once. Plus a throwing-
projector isolation test. 7/7 diff-loop tests green.
2026-06-24 22:55:51 +08:00
DrSmoothl
f9ce49ac7e fix(webui): single-flight per resource in bindStateStream — ordering safety
Adversarial review caught: uneven snapshot latency can deliver a STALE
final frame. Concrete repro added as a test:
  - publish('processes') @ T=0 → flush A starts a slow snapshot (200ms)
  - publish('processes') @ T=60 → flush B fires at T=110 with a fast (10ms)
    snapshot → send B at T=120
  - flush A's slow snapshot resolves at T=250 → send A with snapshot data
    captured BEFORE B → client's LAST frame is stale.

Fix: at most one in-flight flush per resource. While a flush is pending,
new publishes set a  flag instead of starting an overlapping
flush; on completion the flag re-arms the debounce timer for exactly one
follow-up flush. Sustained publish streams therefore produce at most one
frame per (debounceMs + flushLatency).

Test 'serialises overlapping flushes' fails on the pre-fix code (last
frame = 'snap-T0' stale), passes on the fix (last frame = 'snap-T60'
fresh). Test 'coalesces N publishes during in-flight' verifies the
pending flag is set-like (5 publishes → 1 follow-up, not 5).

9/9 state-stream tests green; 432/432 core suite.
2026-06-24 22:44:09 +08:00
DrSmoothl
bb752b13a1 fix(webui): add /api/state/stream to SSE token-query allowlist
Adversarial review caught: EventSource cannot set custom headers, so every
SSE endpoint MUST appear in the TOKEN_QUERY_ALLOWLIST or the auth
middleware at server.ts:404 computes queryToken='' and 401s every connect.

Without this fix the entire phase-3 SSE endpoint is dead on arrival:
clients silently fall back to the 30s REST reconcile and the original
"WebUI must refresh to see new state" bug is unfixed.

Export the allowlist as SSE_TOKEN_QUERY_PATHS so a regression test can
lock the invariant — a missing entry has no error log, the only symptom
is the silent stream failure.
2026-06-24 22:36:40 +08:00
DrSmoothl
a9f5f277f1 feat(core): connection-status diff loop — publish 'connections' on change
Phase 4b. OneBot adapters expose no event-emitter for connection-state edges
(listening / connected / client-count / last-delivery), so the SSE handler
can't subscribe — without this loop a connection change would only reach the
WebUI on the 30s REST reconcile fallback.

startConnectionDiffLoop polls getConnectionStatuses() at 500ms, compares
JSON-serialised snapshots, and publishes 'connections' through the StateBus
when (and only when) it actually moves. The first SUCCESSFUL observation is
treated as a baseline (no publish): the SSE handler's sendAllInitial has
already shipped the initial snapshot to every connected client on connect.
Snapshot exceptions are isolated — the loop retries on the next tick without
clobbering the baseline.

Started once per initWebUI lifetime; lives until process exit (consistent
with the other heartbeat-style intervals like the SSE 15s keepalives).

431/431 core suite green (5 new tests cover stable=silent, change=publish,
first-observation=baseline, dispose stops, snapshot-throw isolation).
2026-06-24 22:09:13 +08:00
DrSmoothl
de3bb4817d feat(webui): subscribe to /api/state/stream — push-driven dashboard state
Phase 4 of the SSE migration. The dashboard's three live resources now
update the moment the backend sees a change instead of within 0-3000ms of
the next polling tick.

- New api.stateStream({ onEvent, onStatus }) in lib/api/client.ts mirrors
  the existing openLogStream / openDebugStream EventSource pattern: token in
  the query string (EventSource can't set headers), single onerror →
  'reconnecting' status, source.close() on dispose, JSON.parse with skip-
  malformed isolation. Browser-native EventSource auto-reconnect covers
  transport drops with no manual retry timer.

- StateStreamEvent union covers the three resource frames plus the two
  control frames ('ready' on connect, 'dropped' on backpressure). The
  resource frames carry typed HookProcessInfo[] / QQInfo[] /
  AccountConnections[] payloads.

- AppLayout now subscribes on mount, applies pushed snapshots to the same
  setProcessList / setQqList / setConnections React state slots the polling
  tick used to drive. The REST polling tick is RETAINED but slowed to
  max(pollInterval × 10, 10s) (default 3s → 30s) so it acts as a silent-
  drop reconcile rather than the primary update path. systemInfo isn't on
  the SSE feed — it stays on the slow REST loop.

Resolves the two reported bugs:
  1. new QQ.exe not showing in WebUI until manual refresh → process-
     discovered now publishes 'processes' through the StateBus → frame
     arrives within 50ms.
  2. injection panel stuck at "waiting for connection" after a successful
     hook (group messages arriving) → HookSession 'status-changed' now
     publishes 'processes' → 'online' status frame arrives within 50ms.

WebUI typecheck clean. No unit tests in packages/webui (consistent with the
existing openLogStream/openDebugStream which also have no client tests).
2026-06-24 21:51:35 +08:00
DrSmoothl
a7522deb82 feat(webui): /api/state/stream SSE — push processes/qq-list/connections
Phase 3 of switching the three dashboard resources from REST polling to
SSE push.

- New pure helper packages/core/src/webui/state-stream.ts owns the
  debounce/snapshot/fan-out logic, decoupled from Hono so it's unit-testable
  with fake timers (7 tests cover initial-snapshot, single-publish coalesce,
  per-resource independent debounce, dispose-cancels-pending, snapshot
  rejection isolation, send() throw isolation).

- /api/state/stream handler in server.ts mirrors the /api/debug/stream
  pattern: ReadableStream + createFramePusher (drop-under-backpressure with
  the same {kind:'dropped'} marker), 15s heartbeats, abort-signal teardown.
  On connect: one frame per resource. After: a fresh-snapshot frame per
  StateBus invalidation, 50ms per-resource debounce.

- The endpoint 503s when stateBus is absent (build without state-wiring),
  so clients can still fall back to the REST endpoints; the existing
  GET /api/processes etc remain in place for initial fetch + reconcile.

44 test files, 426/426 core suite green.
2026-06-24 21:44:28 +08:00
DrSmoothl
53f68b3945 feat(core): wire HookManager/BridgeManager edges into the StateBus
Phase 2 of switching processes/qq-list/connections from REST polling to SSE
push. Sinks the three publisher edges into a fresh StateBus:

- HookManager grows an OPTIONAL `onSessionsChanged: () => void` dep; called
  from pipe-watcher process-discovered/process-gone and from the previously
  unsubscribed HookSession 'status-changed' event (login/disconnected reach
  it transitively via applyStatus, so a single subscription covers every
  transition the WebUI processes view cares about). Throwing subscribers are
  caught + logged so the watcher loop is never aborted.

- New packages/core/src/webui/state-wiring.ts owns the coupling: produces the
  bus + the `onSessionsChanged` callback to feed HookManager, and registers
  BridgeManager session-started / session-closed listeners that publish
  'qq-list' + 'connections' (in source-of-truth order: account first, then
  adapters).

- index.ts threads stateWiring.bus into initWebUI so the phase-3 SSE handler
  has something to subscribe to; dispose runs on SIGINT/SIGTERM.

Bridge: 62/62 (was 57). Core: 419/419 (was 414). 10 new tests cover all
publish points + exception isolation + the optional-dep contract.
2026-06-24 21:35:27 +08:00
DrSmoothl
5302341dfc feat(core): StateBus — pure pub/sub for WebUI state invalidations
Phase 1 of switching processes/qq-list/connections from 3s REST polling to
SSE-pushed snapshots. The bus is a frozen-snapshot fan-out (subscribers added
during a publish() see only the next one, peer unsubscribes mid-fan-out don't
skip survivors) with exception isolation per listener.

Pure pub/sub by design — debounce and snapshot reads belong with the
subscriber (the /api/state/stream handler in phase 3) so different consumers
can coalesce on their own cadence.

8 unit tests, 414/414 core suite green.
2026-06-24 21:10:53 +08:00
DrSmoothl
fb7675f3cb test(bridge): lock HookSession refresh drift fix
Two tests pinning the one intended behavior change from the status-
machine deepening: refresh while the pipe is down on a connected-but-
never-logged-in session now reports 'connecting' (matching onPipeDown),
not the old spurious 'disconnected'; and a session that HAD logged in
still settles to 'disconnected' + emits disconnected(true), proving the
flip is scoped to the never-logged-in case.

Verified against the pre-refactor baseline: test (1) fails on old code
(produced 'disconnected'), so it locks the flip rather than restating it.
2026-06-24 19:49:21 +08:00
DrSmoothl
1d2a56bcdb refactor(bridge): wire HookSession status through statusFor + shared reconcilers
Phase 2. Migrate the ~6 hand-copied status ternaries to the pure
statusFor() and collapse the pipe up/down orchestration into two shared
private reconcilers:

- reconcilePipeUp  ← onPipeUp + refresh's pipe-up branch
- reconcilePipeDown ← onPipeDown + refresh's pipe-down branch + the
  client 'close' handler (4 call sites, all were near-duplicates)

applyStatus() pushes the statusFor-derived status; loading/error stay
explicit. refreshInternal collapses to a one-line pipe poll. Behavior-
preserving except the intended drift fix (refresh-while-down + never
logged in now reports 'connecting', matching onPipeDown, not the old
spurious 'disconnected').

reconcilePipeDown short-circuits when !connected so a pipe-down tick
can't clobber a diagnostic error or emit a spurious status-changed on a
failed-connect/failed-load session — covered by two new regression
tests (caught in adversarial review). 55/55 green.
2026-06-24 19:42:59 +08:00
DrSmoothl
74c7e086c7 refactor(bridge): extract pure statusFor for HookSession status derivation
Phase 1 of deepening the HookSession status machine. The 5 settled
HookProcessStatus values (available/connecting/loaded/online/disconnected)
were hand-derived from (injected,connected,loggedIn,wasLoggedIn) at ~6
call sites in hook-session.ts. Extract that truth table into a pure
statusFor() in hook-status.ts so it has one source of truth and a
mutation-tight exhaustive table test. loading/error stay out-of-band.

Not yet wired into hook-session (phase 2).
2026-06-24 19:23:00 +08:00
DrSmoothl
9ad37d4ada chore(github): add PR template, bug-report deploy field, feature-request willingness dropdown 2026-06-24 00:46:15 +08:00
DrSmoothl
1bdb8a40c4 fix(protocol): dedup duplicate system pushes (#137 official-robot double group_increase)
Inviting an official robot (e.g. 2854207029) into a group made QQ push the
group_member_increase notice twice, so SnowLuma emitted two
notice.group_increase events; a normal member produced one.

Root cause (RE of wrapper.linux.node): QQ NT dedups every received system
message in sys_msg_mgr.cc::ProcessRecvSysMsg (sub_37BADE0) by a global_key
`{peerUid}_{chatType}_{msg_seq}_{random}` (sub_37BC4E0) — an already-seen key
is dropped ("ignore dup msg") before any listener sees it. The per-message
discriminators msg_seq (attr 40003 = contentHead field 5) and random (attr
40002 = contentHead field 4) are exactly head.sequence and head.msgId
(msg_header_codec_helper.cc sub_37C8AD0). Kernel-based bots (NapCat/LLOneBot)
receive events after this dedup; SnowLuma reads the raw OlPush before it.

Mirror it: SysMsgDedup, a per-account bounded ring that drops a duplicate
system push by (msgType, subType, fromUin, sequence, msgId). Push-level (drops
the whole duplicate like NT), live path only (Bridge owns the tracker; the
forward re-parse passes none), system kinds only (chat messages excluded), and
never dedups a push lacking a server identity (sequence or msgId 0).
2026-06-23 20:36:24 +08:00
DrSmoothl
4e0ec92c23 fix(core): emit group_decrease + drop cache on set_group_leave (#133)
The server never pushes a member-decrease back to the member that left of its
own accord, so set_group_leave produced no notice.group_decrease — downstream
kept a 'zombie' group in its cache, and a later set_group_add_request failed
with 'matching group request not found'.

bridge.leave() now, after the 0x1097_1 OIDB succeeds, synthesizes a self
group_member_leave (user_id = operator_id = self, sub_type 'leave') through the
event bus — converted to notice.group_decrease by the existing path — and
calls identity.forgetGroup() so get_group_list / member lookups drop it
immediately (in-memory + DB inactive).

Kick / disband already arrive via the GroupMemberDecrease push (PkgType 34).
Limitation: a MANUAL leave in the NTQQ client isn't covered — SL is packet-
based with no kernel callback, and a voluntary self-leave isn't pushed back;
only kernel-based clients (NapCat/LLOneBot) catch that.

Validated by unit tests (bridge leave emits the event + forgets the group).
2026-06-22 23:07:44 +08:00
DrSmoothl
2b3d1c67c2 test(common): cover hex/log-summary/request-context; fix Utf8Validator dead code (#84, #85)
Reimplements PR #86 independently (author abandoned it after change-requests),
with the review feedback applied — the original tests asserted behavior the
code never had.

#84 — add @snowluma/common unit tests:
- hex: toHex/toHexUpper/hexPreview boundary + fromHex round-trip & odd-length throw
- log-summary: summarizeParams (top-level primitive is String()'d WITHOUT quotes;
  fields quoted; nested collapsed; total cap) and renderParamsVerbose (redaction,
  long-string marker is the Unicode ellipsis '…<N B>' not ASCII '...', circular guard)
- request-context: nextRequestId monotonic; runWithRequestId sync/async + nested scopes
- root scripts test:common/test:all/coverage; coverage/ gitignored

#85 — Utf8Validator: the second surrogate check was unreachable (within the
0x80–0xBF continuation-byte guard, 'b & 0x20' is true iff 'b >= 0xA0'); merge to
one check. No behavior change.

common suite green (26 tests).
2026-06-22 22:53:21 +08:00
DrSmoothl
b918450483 fix(protocol): set_group_special_title — send uinName so the title actually applies
The 0x8FC_2 body omitted uinName (tag 7), so the server accepted the request
(errorCode 0) but silently never applied the title — looking like the feature
was unsupported. Both NapCat (Oidb.0x8FC_2: uinName=title) and Lagrange
(0x8FC body @7 UinName=title) set it; mirror them by sending uinName = title.

No RE needed — two independent packet-based implementations agree on the field.

Note: setting a special title is group-owner-only, so on-target validation
requires a group the bot owns.
2026-06-22 21:53:33 +08:00
snowluma-bot[bot]
157cc90397 Merge pull request #132 from SnowLuma/dev
chore: promote dev → main (1bd1265)
2026-06-22 13:31:34 +00:00
DrSmoothl
1bd126562f chore(release): v1.10.2 2026-06-22 21:31:06 +08:00
DrSmoothl
e160837f8b feat(onebot): tiered reply backfill + quoted-file recovery for get_msg (#128)
Harvests the sound ideas from PR #128 while KEEPING origSeqs[0] as the c2c
reply sequence (on-target capture in #114/#124 proved origSeqs[0] == the quoted
message's head.sequence; pbReserve.friendSequence is a small unrelated counter
that makes reply.id miss). The PR's friendSequence override is intentionally
NOT taken.

- rich-body-decoder: enrich the reply element with replySenderUin/replyTime and
  the quoted message's own decoded elements (SrcMsg.elems, field 5); recover a
  c2c quoted FILE from sourceMsg (field 9 -> RichText.notOnlineFile) when elems
  carried none, so a quoted file survives into get_msg (#124).
- backfillReplyTarget: tiered fallback — Tier 0 local store, Tier 1 server fetch
  (correct seq = origSeqs[0]), Tier 2 reconstruct from the embedded quoted
  elements (no round-trip), Tier 3 minimal '[引用消息]' placeholder so get_msg
  never returns 'message not found'.
- to-segment: per-element try/catch (logged, not silent) so one bad element
  doesn't drop the whole message.
- actions/message: log get_msg misses.
- tests: fix request-actions getGroupInviteCardSequence mock (gap from #125);
  cover backfill Tier 2 (reconstruct) + Tier 3 (placeholder); flip the stale
  c2c reply test to assert origSeqs[0] (was asserting the disproven
  friendSequence).

Validated on-target (Docker): get_msg on group reply, private text reply, and a
private quoted FILE all return correct content (file with name/size/id); full
onebot + protocol suites green.
2026-06-22 21:25:05 +08:00
DrSmoothl
4593ba3340 fix(protocol): strip reply auto-mention on receive; align send to uin=0 (#127)
A QQ NT reply carries the replied sender as a structural auto-mention
(MentionExtra.type=2, uin=0) right after srcMsg, plus a blank separator
text. SnowLuma reported both as a real [CQ:at] + empty/space segment, so
downstreams saw a phantom @ (#127). A real user @ carries a non-zero
MentionExtra.uin, so it is preserved.

- receive (rich-body-decoder): after a reply, drop a type=2/uin=0 mention
  and the blank text that follows it; keep non-zero-uin mentions.
- send (element-builder, #129 follow-up): the reply auto-mention added for
  reply+@ now uses uin=0 (real uid stays in `uid`) to match QQ's native wire
  shape, so the bot's own replies are stripped the same way by receivers and
  don't surface a phantom @ either.

Validated on-target (Docker, group): reply w/o @ -> [reply, text] (no
phantom @/empty); reply w/ @ -> [reply, at(real), text]; bot reply+@ still
delivers the @ (uin=0).
2026-06-22 20:53:10 +08:00
DrSmoothl
45aae92af5 fix(protocol): group reply+at — emit replied-sender mention after srcMsg (#129)
When a group message combined a reply with a user @ , the @ showed but
never notified (no blue link, no ping). On-target capture showed SnowLuma
sent [srcMsg, @target(mention), text] — the @ lands directly in the reply's
mention slot right after srcMsg, which the QQ NT group server does not honor.

Mirror Lagrange's ForwardEntity.PackElement: when a reply and an @ coexist
in a group message, emit the replied sender as a trailing mention element
right after srcMsg, so the user's @ is no longer the first post-srcMsg
element and is honored. Gated to the reply+@ case so plain replies are
unchanged.

Validated on-target (Docker, group send): baseline reply+at -> @ not
delivered; fixed -> @ delivered (blue link + notification).
2026-06-22 20:37:19 +08:00
DrSmoothl
839de51519 fix(protocol): c2c reply uses origSeqs[0], not friendSequence (#114, #124)
A private (c2c) reply resolved to srcMsg.reserve.friendSequence, but a
received message's message_id is hashed from its head.sequence. On-target
capture showed origSeqs[0] == head.sequence (e.g. 12709) while friendSequence
is a small friend-relationship counter (e.g. 25) — so reply.id != the quoted
message_id. Downstream get_msg(reply_id) then missed:

- #114: reported reply id didn't match the quoted message's real id.
- #124: replying to a File message returned empty quoted content (AstrBot
  relies on get_msg(reply_id) to learn the quote was a file; text replies
  appeared fine because they read the inline follow-up text instead).

Drop the c2c friendSequence override (reverting cf8e62d's premise, which was
backwards) so both group and c2c replies use origSeqs[0].

Validated on-target (Docker): file message id == reply.id, and
get_msg(reply_id) -> retcode 0, message [{type:file}].
2026-06-22 16:07:36 +08:00
DrSmoothl
11e7584d1c fix(onebot): approve bot self-invite via private card msgseq (#125)
When the bot is invited to a group via a private-chat "qun.invite" ark
card, set_group_add_request failed: handleGroupAddRequest re-derived the
approval tuple from fetchGroupRequests (0x10c8_2), but for a self-invite the
only sequence the server accepts at 0x10c8_1 is the msgseq embedded in the
card's mqqapi://group/invite_join jumpUrl, applied with eventType=2 /
filtered=false. The MSF invite push (PkgType 87) never carries that msgseq,
so approval returned 120161001 'handle async message fail'.

- friend-message decoder: parse the private invite card's jumpUrl and stash
  groupUin -> msgseq on the per-instance IdentityService.
- ContactsApi.getGroupInviteCardSequence(groupId) exposes it.
- handleGroupAddRequest: for an invite flag, if a card msgseq is cached,
  approve with setAddRequest(groupId, msgseq, 2, approve, reason, false);
  otherwise fall back to the existing fetchGroupRequests path.

Validated on-target (Docker): private invite card -> set_group_add_request
approve -> 0x10c8_1 ok -> bot joined the group (get_group_member_info shows
role=member, fresh join_time); no 120161001.
2026-06-22 15:25:28 +08:00
snowluma-bot[bot]
f470b7a10c Merge pull request #122 from SnowLuma/dev
chore: promote dev → main (8b87f80)
2026-06-21 17:45:50 +00:00
DrSmoothl
8b87f80951 chore(release): v1.10.1 2026-06-22 01:45:25 +08:00
DrSmoothl
b135752577 fix(highway): retry chunk upload on transient transport errors (#118)
Large private files (e.g. 48 MB .flac via send_private_msg) failed with
"connection closed before response (received 0 bytes, headerSeen=false)".
uploadHighwayHttp sends one fresh TCP connection per 1 MB chunk with no
retry, so a 48 MB file is ~48 sequential connections and a single transient
peer-FIN / reset among them aborted the entire upload. Small files (1 chunk)
always worked; NapCat is unaffected because it delegates to QQ's native
highway client, which retries.

Wrap each chunk's connect + POST in a bounded retry (3 attempts, 300 ms ×
attempt backoff, fresh connection each time). Re-sending the same offset
range is idempotent server-side. Only transport failures retry; a decoded
highway error_code is a definitive server reject and is not retried.
2026-06-22 01:45:12 +08:00
snowluma-bot[bot]
fd2345b772 chore(native): replace native artifacts (native-latest) (#121)
Build: https://github.com/SnowLuma/SnowLumaNative/releases/tag/native-latest

Co-authored-by: snowluma-bot[bot] <283088347+snowluma-bot[bot]@users.noreply.github.com>
2026-06-22 01:41:50 +08:00
stla
907cfddfa3 fix:docker容器正确获取宿主机系统信息 (#119)
* Add function to detect operating system distribution

* Add 'distro' property to system types

* Update subtext in StatTile to show distro instead of platform

* Add Linux distribution detection and architecture normalization

* Add archLabel to SystemInfo interface

* Update subtext to use archLabel instead of arch

* Add distro summarization function and update StatTile

* Refactor distro summary to use tooltip for details

* Refactor host system info detection functions

* Enhance Linux distribution detection logic

* Improve Linux distro detection and version parsing

Enhanced Linux distribution detection logic by adding kernel version parsing and improved source handling for OS release information.

* Enhance kernel and distro version detection on Linux

Refactor kernel version extraction and improve distro version parsing logic.

* Enhance RHEL family detection and error handling

* Enhance distro name formatting in overview-page

* Extend RHEL family detection and supported distros

* Add support for additional Linux distributions

* Enhance OS detection for Armbian and DietPi

Added support for detecting Armbian and DietPi distributions from kernel release strings.

* Add support for Raspbian and DietPi in OS name formatting
2026-06-22 01:39:11 +08:00
snowluma-bot[bot]
7f391e065e Merge pull request #117 from SnowLuma/dev
chore: promote dev → main (9efe162)
2026-06-21 12:23:09 +00:00
DrSmoothl
9efe16237d chore(release): v1.10.0 2026-06-21 20:22:46 +08:00
snowluma-bot[bot]
c7b7c0b323 chore(native): replace native artifacts (native-1.10.0) (#116)
Build: https://github.com/SnowLuma/SnowLumaNative/releases/tag/native-1.10.0

Co-authored-by: snowluma-bot[bot] <283088347+snowluma-bot[bot]@users.noreply.github.com>
2026-06-21 20:20:43 +08:00
stla
e2415210cd Enhance OS detection and update StatTile for distribution display (#115)
* Add function to detect operating system distribution

* Add 'distro' property to system types

* Update subtext in StatTile to show distro instead of platform

* Add Linux distribution detection and architecture normalization

* Add archLabel to SystemInfo interface

* Update subtext to use archLabel instead of arch

* Add distro summarization function and update StatTile

* Refactor distro summary to use tooltip for details

* Refactor host system info detection functions
2026-06-21 19:45:23 +08:00
Qiao
127f2cd2d6 feat(flash-transfer): QQ flash transfer (fileset) upload, share, download (#113)
* feat(proto-defs): add flash-transfer OIDB proto types

QQ 闪传(FlashTransfer / fileset)的 protobuf 类型定义:
- FlashFileEntry(0x93d2/0x93d3 文件条目)
- 0x93cf 申请 fileSet / 0x93d0 commit / 0x93db 完成 / 0x93d1 设状态
- 0x93d3 文件集详情 / 0x93d4 下载 URL(含主文件 fileId + 缩略图)
- 0x12a9 sub=100/103/200 prepare/apply/get-download
- sliceupload body + Sha1StateV
- 0x9407 删除 / 0x9427 重命名 / 0x93d7 发送
注册到 oidb-actions/index.ts,package.json 加 exports。

* feat(protocol): add flash-transfer OIDB services + sha1-stream

闪传协议层(OIDB namespace,复用 invokeOidb/OidbCallSpec):
- apply-fileset / commit-file / complete-fileset / set-status(上传流程)
- prepare-upload (0x12a9_100) / apply-upload (0x12a9_103)(sliceupload 凭证)
- get-fileset-detail (0x93d3) / list-filesets (0x93d2) / get-download-url (0x93d4)
- get-flash-download (0x12a9_200,主文件下载直链)
- delete-file (0x9407) / rename-file (0x9427,sub=0+uinForm) / send-flash (0x93d7)
- sha1-stream:SHA1 中间 state 计算器(sliceupload f107.f6 需要,Node crypto 不支持)
- byte-oracle 单测(apply/prepare/get-download-url/send-flash)+ sha1-stream 单测
package.json 加 exports。

* feat(core): add FlashTransferApi facade

FlashTransferApi 编排闪传全流程,复用 OIDB 基础设施(invokeOidb)+
computeHashes/loadBinarySource/fetch:
- createFlashTask:统一走 sub=100/103+sliceupload(含缩略图),不走小文件 PUT
  (PUT 不上报主文件 sha1,fileset 卡在未完成;QQ 客户端小文件也走 sliceupload)
- buildFileId:主文件 appid=14901(进 f14.f1),缩略图 png=14903/jpg=14902
- uploadThumbnail:随机纯色 PNG 占位(手写编码,不引入图像库),关联主文件下载入口
- getFilesetInfo/getFlashFileList/getShareLink/getFlashFileUrl/downloadFileset
- sendFlashMsg(私聊 uid / 群聊 groupId)/ getFilesetIdByCode(网页解析)
- deleteFlashFile / renameFlashFile / listFilesets
注册到 ApiHub(flashTransfer 字段)+ export。

* feat(onebot): add flash-transfer actions

OneBot action(extended.ts)10 个:
create_flash_task / get_fileset_info / get_flash_file_list /
get_flash_file_url / get_share_link / download_fileset /
send_flash_msg(私聊 user_id / 群聊 group_id)/ get_fileset_id /
rename_flash_file / delete_flash_file
MCP catalog(生成文件)同步新增 action 元数据。
extended-actions 接线单测覆盖。

* fix(onebot): align flash file list field name with NapCat

flashFileInfoToJson 的文件大小字段从 file_size 改为 size,对齐 NapCat
get_flash_file_list 响应(NapCat 用 size)。get_fileset_info 的 file_list
复用同一映射,一并生效。便于 NapCat 客户端 drop-in 迁移。

* feat(proto-defs): support multi-file commit in flash-transfer

0x93d0 commit 的 f4 改为 repeated,一个请求携带 fileset 内全部文件条目。
FlashCommitFileInfo 的 f3/f5/f6/f7/f10/f12 用 pb_optional,强制 0 值上 wire
(服务端多文件时严格校验字段存在,省略 0 会导致后续文件不计入 fileset)。

* feat(protocol): parameterize flash-transfer upload for multi-file

CommitFile.Params 改为 entries 数组,serialize 输出 repeated f4,每条 f6=文件序号。
PrepareUpload/ApplyUpload 加 fileIndex + formatCode 参数:filesetWrap.f4 用 fileIndex
(与 commit f6 对齐),f7 用 formatCode(mp4=2 非 26),f9=1。

* feat(core): multi-file flash-transfer upload

createFlashTask 支持多文件共用一个 fileset。关键改动:
- ApplyFileset 多文件时 fileName 用「<首文件名>等N个文件」、fileSize 用总和,
  服务端据此判定 fileset 为多文件,commit 的后续 entry 才被计入
- 一次性 CommitFile 提交所有文件元数据(f4 repeated)
- 两阶段上传:先全部 prepare+apply 注册 fileId,再全部 sliceupload 落盘
- 拆分原 uploadLargeFile 为 prepareAndApply + sliceuploadFile
- fileTypeCode mp4 formatCode 26→2(与 commit f7/filesetWrap.f7 一致)

* feat(onebot): multi-file create_flash_task + list_filesets action

create_flash_task 的 files 参数支持 string 或 string[],多文件共用一个 fileset。
新增 list_filesets action(facade.listFilesets 之前未暴露)。MCP catalog 同步更新
files schema(anyOf string/array)与 list_filesets 条目。

* fix(flash-transfer): multi-file download by fileIndex

0x93d4 响应 f1.f3 是 repeated fileInfo(多文件 fileset 每个文件一条,f6=序号、
f14=主文件 fileId),之前定义成单个导致多文件只能拿到第一个文件。
FlashDownloadEntry.fileInfo 改 pb_repeated,GetDownloadUrl 返回所有文件元信息,
download_fileset 按 fileIndex 选中目标文件走 0x12a9 sub=200 拿直链。

* test(protocol): inline byte-oracle hex fixtures

两个 flash-transfer byte-oracle 测试原先用 readFileSync 读仓库外的
.claude/reverse/scripts/proto/*.hex(本地逆向笔记目录),CI 上不存在导致失败。
把 hex 内容内联成常量,测试自包含。

* fix(flash-transfer): address review feedback

1. get_flash_file_url 接 file_index 参数并在 action 透传(之前漏接,多文件永远返回首文件)
2. getFileDownload 越界 fileIndex 不再静默回退首文件,找不到返回 null
3. postSliceupload status 缺失不再当成功,非 success 一律抛错
4. computeSha1StateV 改 O(n) 增量 update(之前每片 reset 重算整个前缀,O(n²))
5. get_flash_file_url 找不到文件抛错(之前返回空串当成功)
6. create_flash_task files 数组拒绝空字符串
2026-06-21 14:24:51 +08:00
DrSmoothl
ebadfb968b feat(webui): replace 「侧栏默认折叠」 with 「钉住侧栏展开」 pin option
The old default-collapsed pref went inert once the sidebar became a
hover-expand rail with no collapse button. Repurpose it as an explicit
opt-out: when 「钉住侧栏展开」 is on, the sidebar stays permanently expanded
and no longer collapses to the rail or reacts to hover.

Renamed the appearance field sidebarDefaultCollapsed -> sidebarPinned across
the webui types/defaults/settings UI and the core ui-config interface,
defaults and validator (kept in lock-step so persistence round-trips). Wired
into main-layout: effectiveCollapsed = !editing && !sidebarPinned.
2026-06-20 23:37:21 +08:00
DrSmoothl
bba9b82ce9 feat(webui): hover-expand sidebar rail + borderless nested-canvas chrome
Reshape the desktop shell to feel less "boxed-in", keeping the original
visual design — boundaries now read via depth/tone, not hard borders.

- Sidebar rests as a 64px icon rail and auto-expands on hover (or keyboard
  focus-visible), pushing the content rather than overlaying it. Removes the
  explicit collapse button; resting state is the rail (`effectiveCollapsed =
  !editing`), so it always auto-collapses on mouse-leave.
- Drop hard region borders: sidebar border-r and topbar border-b/divider are
  gone; the rail blends into a sidebar-toned chrome.
- Sidebar internal cleanup: brand border, the footer Separator, the update
  card / edit-item / 完成 button borders removed; active nav indicator is now
  a soft pill + sliding 2px primary left bar (layoutId).
- Content is a nested canvas with a rounded top-left corner at the
  sidebar/topbar junction, lifted via a soft shadow; the corner slides with
  the rail since the canvas is its flex sibling.

Note: the 「侧栏默认折叠」 appearance toggle (settings-page) is now inert for
the main nav sidebar — to be repurposed as "pin open" or removed in a follow-up.
2026-06-20 23:30:08 +08:00
DrSmoothl
9d1e39f25f fix(highway): VP8X WebP canvas dims are little-endian, not big-endian (#112)
detectImageFormat read the VP8X (extended WebP) canvas width/height with a
big-endian readBE24, but the WebP spec stores them as 24-bit LITTLE-endian
(Minus-One). A 1920×1080 image was reported as 8324865×3605505, so the
fileInfo sent to highway was garbage and QQ cropped the thumbnail. VP8
(readLE16) and VP8L (readLE32) were already correct.

- Replace readBE24 with readLE24 in the VP8X branch; readBE24 had no other
  caller, so it's deleted (no dead code left).
- Add the previously-absent detectImageFormat regression suite (12 cases):
  PNG/GIF/BMP/VP8/VP8L/VP8X/JPEG + JPEG DHT-skip + truncated/unknown
  fallbacks. The VP8X cases pin little-endian byte order, including the
  exact bytes from the issue and an asymmetric 256×1 case that a BE misread
  would blow up to 16711681.

Verified TDD red→green: the 3 VP8X cases failed before the one-helper swap,
all 12 pass after.
2026-06-20 20:19:10 +08:00
DrSmoothl
b9d8247309 fix(qzone): complete re_feeds param set + correct qzreferrer/topicId honesty
Adversarial review (NEEDS-FIXES) — the high-risk parts (topicId base
hostUin_tid, uin/hostUin not swapped, format=fs, platformid=52) verified
correct against 3 community impls; the gaps:
- Added the re_feeds param family all 3 impls send and the publish sibling
  already sends for this CGI family: feedsType=100, private=0, paramstr=1,
  richtype/richval/isSignIn=''. Tests assert the load-bearing ones.
- qzreferrer used hostUin; all impls use the commenter's own uin → selfUin.
- topicId __1 suffix is impl-dependent (2/3 include it, 1 omits); kept as
  default but the comment now flags the suffix specifically as the
  unverified piece (base shape is confirmed), and the test no longer
  presents it as canonical.
2026-06-20 02:10:12 +08:00
DrSmoothl
95f24ffc4a feat(qzone): comment_qzone — comment on a 说说 via web API
commentQzoneMsg POSTs a form body to taotao.qzone.qq.com's
emotion_cgi_re_feeds (proxied through h5.qzone), keyed by topicId
<hostUin>_<tid>__1, as the bot (uin=self) on target_uin's feed (defaults
to the bot's own space). Returns the new comment id best-effort — the
response field name varies (commentid/commentId) so a missing id with
code 0 is still success. Throws on non-zero code/subcode; rejects empty
tid/content pre-flight. WRITE — rate-limit (风控).

topicId shape + comment-id field are extrapolated from community impls,
pending a live capture (labeled in the helper comment).

- core: QzoneApi.comment; onebot: comment_qzone action; regen catalog.
- tests: re_feeds form lock (topicId/uin/hostUin/content/format=fs),
  commentid + camelCase commentId fallback + missing-id success, empty
  tid/content preflight, non-zero code throw, bridge owner-defaulting.
2026-06-20 02:05:56 +08:00
DrSmoothl
870504ae3a fix(qzone): thread abstime into like, flag unlike endpoint as unverified
Adversarial review (NEEDS-FIXES) of the like/unlike slice:
- Missing abstime: every real dolike impl (QLiker.py, CSDN) sends the
  target feed's post time. Threaded abstime through setQzoneLike →
  QzoneApi.like → like_qzone/unlike_qzone actions (optional, default 0;
  pass the feed's real time for reliability). Test asserts it.
- internal_unlike_app is the conventional paired CGI but NO public bot
  impl exercises unlike, so it's best-guess. Labeled UNVERIFIED/pending a
  live capture in the helper comment, the unlike action summary, and the
  unlike test — instead of pinning it as confirmed truth (avoiding the
  re-codify-a-wrong-constant trap the last 3 slices hit).
- Documented the success-signal (code/subcode) as extrapolated from
  sibling CGIs (dolike may use a succ/fail token instead).

The confirmed mechanics (dolike CGI, opuin=liker, unikey/curkey mood
shape, appid=311, fid=tid) are noted as such.
2026-06-20 02:02:25 +08:00
DrSmoothl
d497f1e6c7 feat(qzone): like_qzone / unlike_qzone — like/unlike a 说说 via web API
setQzoneLike POSTs a form body to w.qzone.qq.com's internal_dolike_app
(like) or internal_unlike_app (unlike), proxied through h5.qzone, keyed by
the feed's mood unikey/curkey (http://user.qzone.qq.com/<uin>/mood/<tid>)
and fid=tid, as the bot (opUin). target_uin selects whose 说说 (defaults
to the bot's own); scope is 说说 (mood, appid 311). Throws on non-zero
code/subcode. Rejects empty tid pre-flight. WRITE — rate-limit (风控).

- core: QzoneApi.like(tid, targetUin?, like); onebot: like_qzone +
  unlike_qzone actions; regen catalog.
- tests: dolike vs unlike CGI selection, unikey/curkey/fid/opuin form
  lock, empty-tid preflight, code+subcode throws, and bridge owner-
  defaulting (self vs friend) + like-flag threading.
2026-06-20 01:56:23 +08:00
DrSmoothl
e406a3bc2b docs(qzone): delete header comment mentions subcode in the success contract
Trivial accuracy nit from re-review (verdict SHIP) — header said
throw-on-non-zero-code but the helper also throws on a non-zero subcode.
2026-06-20 01:54:19 +08:00
DrSmoothl
4d75dc9ae3 fix(qzone): delete_v6 uses format=fs, drop bogus json param, harden success check
Adversarial review (NEEDS-FIXES) — two wrong-constant defects (same family
as the publish t1_tid bug) + a destructive-write hardening:
- format=json → format=fs. Every working reference (silica-github/
  qq_zone_delete, zhihu, daimagongfang) uses fs for the delete CGI; the
  tests re-codified the wrong value.
- Removed the invented json=1 body param (no source includes it); test now
  asserts it's absent.
- Also throw on a non-zero subcode (not just code), and documented that the
  code/subcode success signal is EXTRAPOLATED from sibling CGIs pending a
  live capture (public delete impls only check HTTP 2xx). Added subcode-throw
  and code-absent-resolves tests to lock the branch.
2026-06-20 01:52:47 +08:00
DrSmoothl
a704f12945 feat(qzone): delete_qzone_msg — delete a 说说 by tid via web API
deleteQzoneMsg POSTs a form-urlencoded tid to taotao.qzone.qq.com's
emotion_cgi_delete_v6 (proxied through h5.qzone), on the bot's own space.
Success has no positive payload beyond code 0, so the contract is
throw-on-non-zero-code (foreign/unknown tid or auth failure); the server
only deletes feeds the hostUin owns. Rejects empty tid pre-flight.

- core: QzoneApi.delete; onebot: delete_qzone_msg action; regen catalog.
- tests: tid form-body/url/headers lock, empty-tid preflight, non-zero
  code throw, and bridge self-space threading.
2026-06-20 01:47:50 +08:00
DrSmoothl
9e21c3a7ef fix(qzone): read real t1_tid/t1_time publish fields — was false-throwing every success
Adversarial review (verdict NEEDS-FIXES, CRITICAL): emotion_cgi_publish_v6's
success envelope names the new feed id `t1_tid` and post time `t1_time`
(a STRING), NOT `tid`/`now`. So every successful publish hit the
'缺少 tid' guard and was reported as a failure (risking caller-retry
duplicate 说说). The tests passed only because they mocked the wrong field
names — they codified the bug.

- Read t1_tid (primary) with tid as a defensive fallback; t1_time||now
  via Number() (t1_time is a string on the wire). Verified against the
  Go reference lib starim00/AnimeAPI EmotionPublishVo.
- Added who=1 to the form body (both working references send it).
- Tests now encode the real contract (t1_tid/t1_time string), plus a
  tid/now fallback case and a no-feed-id throw case.
2026-06-20 01:44:50 +08:00
DrSmoothl
9f2eb37232 feat(qzone): send_qzone_msg — publish a text 说说 via web API
First Qzone WRITE path. publishQzoneMsg POSTs a form-urlencoded body to
taotao.qzone.qq.com's emotion_cgi_publish_v6 (proxied through h5.qzone),
g_tk in the query, on the bot's own space. Returns the server-assigned
tid (the handle for later delete/comment/like) + post time.

- Throws on transport failure, non-zero Qzone code (content rejected /
  rate-limited), or a success body with no tid — never reports a publish
  as succeeded without the feed id. Rejects empty content pre-flight.
- 带图 (image) publishing is a later slice (needs the upload CGI first).
- Action carries a风控/限流 caveat: publishing is an active action and
  high frequency is rate-limited by Qzone, same as sending messages.

- core: QzoneApi.publish; onebot: send_qzone_msg action; regen catalog.
- tests: form-body/url/headers lock, empty-content preflight, non-zero
  code throw, missing-tid throw, and bridge self-space threading.
2026-06-20 01:40:06 +08:00
DrSmoothl
b00f5ab759 test(qzone): align feeds JSONP fixture to requested _preloadCallback name
Cosmetic fidelity nit from re-review: the fixture used _Callback(...) while
the request pins callback=_preloadCallback. Parser is name-agnostic so
behavior is unchanged; this just makes the fixture mirror slice-1.
2026-06-20 01:37:55 +08:00
DrSmoothl
5164ba9e39 fix(qzone): route feeds3_html_more through proxy + pin JSONP format
Adversarial review of the get_qzone_feeds slice (verdict NEEDS-FIXES):
- Host: hit ic2.qzone.qq.com directly, bypassing the proxy gateway that
  slice-1/group-album use. The qzone.qq.com cookie jar only authenticates
  against the proxy origin, so the direct call would fail referer/origin.
  Now routed through h5.qzone.qq.com/proxy/domain/ic2.qzone.qq.com/...
- Format: requested format=json but the test fed a JSONP body, so the
  requested format was never pinned. Aligned to slice-1's
  format=jsonp + callback=_preloadCallback; the test now asserts format.
- Pagination: documented honestly that page_num is reliable only for the
  first page (deep paging needs a time cursor, deferred) — in the
  docstring and the action summary/param desc.
- Clarified the key/feedskey fallback is the per-feed handle, not a cursor.
2026-06-20 01:36:04 +08:00
DrSmoothl
094dc12f0c feat(qzone): get_qzone_feeds — read friend feeds (好友动态) via web API
Second read-only Qzone slice. getQzoneFeeds over ic2.qzone.qq.com's
feeds3_html_more CGI, same cookie/g_tk plumbing + JSONP-tolerant parse +
throw-on-auth-failure contract as get_qzone_msg_list. Surfaces the stable
structured fields (uin/nickname/time/appid/key) and passes the
pre-rendered html blob through verbatim — deep HTML→segment parsing is
left to callers. Paginated via page_num (1-based) + count.

- protocol/web/qzone.ts: getQzoneFeeds + mapFeeds.
- core: QzoneApi.getFeeds (always the bot's own identity).
- onebot: get_qzone_feeds action; regenerated MCP catalog.
- tests: feeds mapping, HTTP url/params, empty-feed→[], auth-throw,
  and bridge pageNum/count threading.

Exact CGI field names / pagination cursor to be re-confirmed against a
live capture (same posture as the msglist helper).
2026-06-20 01:31:36 +08:00
DrSmoothl
0083a8fb07 test(qzone): cover empty-space happy path + bridge target_uin defaulting
Adversarial review of the get_qzone_msg_list slice flagged two real
coverage gaps (verdict was SHIP, no correctness defects):
- protocol: empty space ({code:0,msglist:[]}) must return [] not throw —
  the exact distinction the throw-on-auth-failure contract promises.
- core: QzoneApi.getMsgList target_uin defaulting + the >0 guard, the
  only place the string(identity.uin)/number(param) boundary is crossed.
2026-06-20 01:28:57 +08:00
DrSmoothl
61b4bd04a6 feat(qzone): get_qzone_msg_list — read personal Qzone 说说 list via web API
First slice of personal QQ-Zone (个人空间) support, an exclusive feature
vs NapCat/SL (both only do group albums). Read-only to prove out the
auth+parse chain before write ops (publish/like/comment).

- protocol/web/qzone.ts: getQzoneMsgList over taotao.qzone.qq.com's
  emotion_cgi_msglist_v6 (h5.qzone proxy), reusing the same cookie/g_tk
  plumbing as group-album. JSONP-tolerant parse; throws on auth failure
  rather than swallowing to [] (mirrors group-signin contract).
- core: QzoneApi bridge class wired into ApiHub.
- onebot: get_qzone_msg_list action (target_uin/pos/num), regenerated
  MCP catalog + new 空间 doc category.
- HTTP-layer tests lock URL/params, JSONP stripping, field mapping, and
  the throw-on-auth-failure paths (9 cases, all green).

Exact CGI params/response fields to be re-confirmed against a live
capture when extending (same maintenance posture as group-album).
2026-06-20 01:11:07 +08:00
Qiao
d38a0a4c1b feat(protocol): modify/move custom face via OIDB 0x902e + 0x902f (#110)
modify(改备注)走 OIDB 0x902e_1 opType=3 单包;move(移动排序)走
0x902f_1 移动指令 + 0x902e_1 opType=2 上传新顺序两步流程。两者均带
envelope f12=1(uinForm),实测持久化(跨 QQ 重启保持)。

- proto-defs: CustomFaceModifyBody/Resp、CustomFaceOrderBody、CustomFaceMoveBody
- protocol: ModifyCustomFace、OrderCustomFace、MoveCustomFace 三个 namespace + wire byte-oracle 测试
- core: ProfileApi 加 modifyCustomFace / moveCustomFace(move 内部 fetch + 两步发包)
- onebot: modify_custom_face、move_custom_face action
2026-06-19 15:47:43 +08:00
DrSmoothl
258b7e1e72 docs: 添加免责声明和免责声明翻译 2026-06-19 02:36:43 +08:00
DrSmoothl
d0498de966 fix(webui): make the consent agree-checkbox clearly visible
The 16px faint-bordered box + muted label read as nearly invisible. Make it a
full-width bordered row: a larger (20px) border-2 checkbox with a white unchecked
fill, a checked primary tint on the whole row, and the primary label in
foreground weight (English subtitle stays muted).
2026-06-19 02:32:10 +08:00
DrSmoothl
67c99e1e32 feat(webui): EULA/PRIVACY consent gate — frontend
ConsentPage shown after login, before the forced password change: tabbed
EULA/PRIVACY rendered by an in-house, dependency-free markdown renderer
(React elements only, XSS-safe; single-pass bounded-class inline parser to
avoid ReDoS on large docs). App gate order is login -> consent -> password ->
app; api client gains agreements.get / recordConsent with a 409 stale-version
re-prompt that refetches the new text.
2026-06-19 02:27:04 +08:00
DrSmoothl
8c7efc34a9 feat(webui): EULA/PRIVACY consent gate — backend
Server-side consent gate: GET /api/agreements (texts + content-hash version +
consentRequired) and POST /api/agreements/record-consent, persisted to
config/consent.json. Enforced in the auth middleware (CONSENT_ALLOWLIST,
ordered before the must-change-password gate) so the gate is real, not just a
frontend convention. The version is content-derived, so consent is stable
across app upgrades and re-prompts only when the agreement text changes. The
EULA/PRIVACY docs are bundled into dist/ (build fails if they are missing).
2026-06-19 02:26:48 +08:00
DrSmoothl
f71ed2e4db chore(license): source-available non-commercial license
Switch from open-source to a NapCat-style source-available, NON-commercial
license so the free software cannot be resold / paid-deployed — which an OSI
license (AGPL included) cannot prevent. Source stays public for study and
non-commercial self-hosting; commercial use and public release of modifications
require written permission; the native addon (snowluma-*.node) is carved out as
proprietary. Explicitly NOT OSI open source.

- LICENSE: SnowLuma Source-Available Non-Commercial License v1.0 (bilingual)
- all 14 package.json: "license": "SEE LICENSE IN LICENSE"
- README license section; CONTRIBUTING contribution-licensing note + a grant
  letting the project relicense contributions under commercial terms
  (contributors keep copyright)
2026-06-19 02:26:33 +08:00
Qiao
552238fd04 feat(protocol): favorite emoji fetch/delete/add via Faceroam.OpReq + highway (#107)
* feat(protocol): fetch/delete favorite emoji via Faceroam.OpReq

First non-OIDB services in oidb-services/ — Faceroam.OpReq is a trpc
service, so these bypass invokeOidb and call sendRawPacket directly.

- proto-defs: reuse FaceroamOpReq/Inner/Resp, add field5 + FaceroamOpBody
- protocol: oidb-services/emoji/{shared,fetch-fav-list,delete-fav-emoji}
- core: EmojiApi facade + ApiHub registration
- onebot: fetch_fav_emoji_list + delete_fav_emoji actions

Request wire matches 9.9.26-44343 captures byte-for-byte; fetch response
decode + delete verified end-to-end against a live account.

* feat(protocol): add favorite emoji via BDHExpressionRoam + highway HTTP upload

Flow: BDHExpressionRoam (apply upload, get token) -> highway frame
(PicUp.DataUp commandId=9, serviceTicket = BDHExpressionRoam token) ->
HTTP POST httpconn?htcmd=0x6FF0087 -> fetch refresh.

- proto-defs: BDHExpressionRoamReq/Resp + FavEmojiHighwayHead types
- protocol: oidb-services/emoji/add-fav-emoji (fetchHighwaySession +
  BDHExpressionRoam + packHighwayFrame + HTTP POST)
- core: EmojiApi.addFavEmoji facade (reuses loadBinarySource)
- onebot: add_fav_emoji action
- mcp: regenerate catalog

End-to-end verified: new emoji_id appears in fetch list after upload.

* refactor(emoji): reuse fetchCustomFace for fetch_fav_emoji_list

Address review: Faceroam.OpReq had two call sites (profile.fetchCustomFace
+ the new FetchFavList service). Drop the duplicate service —
fetch_fav_emoji_list now reuses ProfileApi.fetchCustomFace and extracts
emoji_id from the returned image URL (qq_expression/<uin>/<id>/0).

delete/add unchanged (independent protocols).

* refactor: align custom-face naming with NapCat

Address review: 'fav_emoji' vs existing 'custom_face' named the same
thing two ways. Rename across the stack to match NapCat's custom_face:
- services: oidb-services/emoji/* -> oidb-services/custom-face/*
  (DeleteFavEmoji -> DeleteCustomFace, AddFavEmoji -> AddCustomFace)
- facade: EmojiApi dropped; delete/add moved to ProfileApi
  (deleteCustomFace / addCustomFace), next to fetchCustomFace
- actions: fetch_fav_emoji_list -> fetch_custom_face_ids,
  delete_fav_emoji -> delete_custom_face, add_fav_emoji -> add_custom_face
- package.json subpaths + catalog regenerated

* refactor(onebot): merge fetch_custom_face_ids into fetch_custom_face

Per review: merge fetch_custom_face_ids back into fetch_custom_face
with a return_type param ('url' default / 'id'). One action, one service,
no separate id-only variant.
2026-06-19 02:15:54 +08:00
DrSmoothl
e3a04858b4 add EULA 2026-06-19 02:15:54 +08:00
DrSmoothl
3428d37764 feat(onebot): get_qun_album_list (napcat-parity over existing web API)
NapCat's get_qun_album_list calls the kernel AlbumService (trpc, not
statically recoverable). SnowLuma already exposes the same qun_list_album_v2
web API as get_group_album_list (raw array); this adds the NapCat-named
action reshaping it into NapCat's {album_list, attach_info, has_more}
envelope with {album_id, album_name, create_time, pic_num} items. Web
endpoint pulls up to 1000 albums in one shot → attach_info/has_more are
''/false (no cursor); cover_url not returned by this endpoint. Reuses the
existing groupAlbum.list bridge call — no new wire.
2026-06-18 23:02:29 +08:00
DrSmoothl
7ea1ffb497 feat(onebot): TierB ③ followup — doubt-buddy reject path (delDoubtBuddyReq)
set_doubt_friends_add_request with approve:false now rejects/declines via
delDoubtBuddyReq instead of erroring. RE'd from QQNT wrapper.linux.node
(DoubtBuddyDelWorker ctor sub_3F3F320 → OIDB 0xd69_0; EncodeRequest
sub_3F3E860 body {1: varint const 3 (op discriminator; get uses 1),
3:{1: string uid}}, uid from kernel attr 21001). uin-form (reserved=1).
Adversarially IDA-verified; byte-oracle locks the tags. Split out as its
own commit because the approve-only 0xd69_0 work was already pushed.
2026-06-18 22:18:08 +08:00
DrSmoothl
43cd4a0b99 feat(onebot): TierB ③ — RE'd OIDB actions (ark share / doubt friends / robot-add)
All recovered from QQNT wrapper.linux.node via IDA — NapCat ships these as
kernel-only with no portable packet wire, so each cmd + protobuf was traced
from the binary (worker ctor cmd/subcmd via BaseOidbWorker::DoSendOidbReq;
field tags from the per-feature EncodeRequest). All uin-form OIDB (envelope
reserved=1, matching the NT worker flag=1). One commit for easy rollback.

New OIDB services + byte-oracle tests (fixed-wire, mutation-resistant):
- 0x9130_0 getBuddyRecommendContactArkJson → share_peer/send_ark_share (user)
- 0x8b7_5  getGroupRecommendContactArkJson → share_peer/send_ark_share (group),
           share_group_ex/send_group_ark_share (NapCat's getArkJsonGroupShare
           was NOT RE'd; routed to this confident equivalent — documented)
- 0xd69_0  getDoubtBuddyReq → get_doubt_friends_add_request
- 0xd69_0  approvalDoubtBuddyReq → set_doubt_friends_add_request (approve only)
- 0xf00_3  modifyGroupExtInfoV2 → set_group_robot_add_option (EXTInfo tags
           30/31; GroupExtFilter is client-side gating, not on the wire)

NOT shipped (kernel-.so-side, no static cmd recoverable from this binary —
honest, no guessed packets): get_robot_uin_range (trpc method-routed),
create_collection/get_collection_list (Weiyun multi-step), trans_group_file.

Doubt-list string field NAMES (nick/source/msg) are medium-confidence
(generic serializer); uid+reqTime are high. READ path, so a mislabel is
cosmetic, never a wire/ban risk. Wired through bridge friend/contacts/
groupAdmin apis; proto-defs + per-file subpath exports registered.
2026-06-18 21:12:29 +08:00
DrSmoothl
b9a015a4aa feat(onebot): TierB ② — get_recent_contact honest stub
QQ's recent-contact list is a kernel-local snapshot
(getRecentContactListSnapShot) with rich peer metadata
(peerName/remark/lastestMsg). SnowLuma has no SSO/packet wire for it, and
its own message store only covers observed sessions and lacks those
fields — so a faithful version isn't achievable app-layer. Rather than
ship a divergent approximation under a name implying QQ's native list,
register a documented stub returning [] (accepts count for compat),
matching how NapCat handles its own unobtainable get_online_clients.
The other ② stubs (online_clients/model_show/mark_all_as_read) were
finalized in P1; collection stays in the deferred deep-RE tier.
2026-06-18 19:32:43 +08:00
DrSmoothl
c572cd498f docs(core): fix stale getSignedList comment (propagates, not fail-soft []) 2026-06-18 19:30:32 +08:00
DrSmoothl
9b787dfdc1 fix(onebot): TierB ① — propagate signed-list errors instead of fail-soft []
Adversarial review: swallowing transport/auth errors to [] made an expired
cookie indistinguishable from a group with zero sign-ins, and left the
onebot action's try/catch as dead code. Now getDaySignedListWebAPI
propagates transport errors and throws on a page-less response (matches
NapCat, which throws on missing page) — so auth failure becomes a proper
'failed' OneBot response; a genuinely empty group still maps to [].

Also: cover the previously-untested HTTP layer (exact URL + g_tk + json
body + error propagation), harden the rank de-skew with Number(), and
document the deliberate local-date (vs NapCat UTC) choice for dayYmd.
2026-06-18 19:28:52 +08:00
DrSmoothl
36d557e5ea feat(onebot): TierB ① — get_group_signed_list via qun.qq.com web API
Group sign-in (打卡) list is NapCat's one kernel-free item here: it's a
plain HTTP POST to qun.qq.com/v2/signin/trpc/GetDaySignedList with g_tk
from p_skey, not OIDB. SnowLuma already has the cookie/bkn infra (same as
group notice/essence/honor), so this is a straight port — no RE.

- protocol/web/group-signin.ts: getDaySignedListWebAPI + pure
  mapDaySignedList (de-skews signInRank via (r-1)/2+1, [] when no page).
- core WebApi.getSignedList(groupId) wires the qun.qq.com cookie jar.
- onebot get_group_signed_list groupAction (readOnly), [] on no sign-ins.
- Tests pin the rank/field transform and the action wiring.
2026-06-18 19:24:42 +08:00
snowluma-bot[bot]
261d6596dc Merge pull request #109 from SnowLuma/dev
chore: promote dev → main (dfb6aa5)
2026-06-18 09:16:43 +00:00
DrSmoothl
dfb6aa54c7 chore(release): v1.9.13 2026-06-18 17:16:15 +08:00
DrSmoothl
a9f84a2aa0 fix(onebot): TierB P1 — honest compat-divergence comments + pin defaults
Adversarial review: code/test comments claimed napcat-surface parity while
get_online_clients ({clients:[]}) and _get_model_show (echoes model vs
NapCat's hardcoded 'napcat') deliberately diverge. Correct the comments to
state these are intentional OneBot-v11/spec choices, and strengthen the
default-model test to pin 'snowluma' literally + cover explicit empty
string. No behavior change.
2026-06-18 16:49:02 +08:00
DrSmoothl
fac51cd94d feat(onebot): TierB P1 — _get_model_show napcat-shaped compat return
NapCat ships model_show/online_clients/mark_all_as_read as kernel-only
mock/no-op with no packet wire, so SnowLuma can't RE a wire that doesn't
exist. Align _get_model_show to NapCat's response shape
([{variants:{model_show,need_pay}}]) and echo the requested model
(default 'snowluma'). online_clients keeps the OneBot-standard
{clients:[]} envelope; _set_model_show / _mark_all_as_read stay no-ops.
Pin all four shapes with tests.
2026-06-18 16:45:46 +08:00
DrSmoothl
aee543c7de fix(protocol): record inviter identity for uid-bearing group_invite
A group_invite carrying a fromUid is routed to the async dispatchGroupInvite
enrich path, which only resolved the requester profile when needsProfile
(uin missing/polluted) — so when the uin was already known it bypassed the
synchronous rememberRequestIdentity that friend_request uses, and the inviter's
uid↔uin was never stored. Record it up-front (mirrors the sync path), and
re-record after a profile resolve so a previously-unknown uin self-heals.
Fixes the long-standing bridge-member-identity test failure (core now fully
green: 387 passed).
2026-06-18 16:16:26 +08:00
渡辺鳩P
06c8954881 feat(notifications): default body template → Server酱 JSON (title/desp) (#108)
- Change DEFAULT_BODY_TEMPLATE from plaintext to Server酱-style JSON
- Add JSON-safe escaping in renderTemplate for backslashes and quotes
- Update frontend DEFAULT_TEMPLATE to match backend
- Add tests for JSON escaping behavior

Fixes #106 (targets dev branch)
2026-06-18 16:10:09 +08:00
DrSmoothl
c637329884 fix(webui): a11y for debug page controls (match project standard)
Adversarial pass (MINOR): the new Segmented/IconBtn regressed a11y vs the
project's existing Segmented. Add role=radiogroup/radio + aria-checked to the
segmented control, type="button" to all buttons (segmented, icon, execute,
row toggle), aria-label to icon buttons, aria-expanded to the row toggle.
2026-06-18 15:48:21 +08:00
DrSmoothl
f153781208 feat(webui): promote debug to a standalone page, Apple-style redesign
Move the debug console out of the Settings 调试 subtab into a dedicated
top-level /debug page (sidebar nav + route + AppPath), and redesign it in an
Apple-HIG flavour: translucent sticky header with title block + connection
pill, soft layered cards (rounded-2xl, hairline borders, blurred backdrop),
an iOS-style segmented control with a sliding active pill (params form/JSON,
stream all/event/action filter), refined timeline rows + empty state, calm
type hierarchy with tabular-nums. Logic (tester + live SSE) carried over
verbatim. Remove the old settings/debug-panel + the Settings 'debug' subtab.
2026-06-18 15:44:05 +08:00
DrSmoothl
3655f10a43 test(webui): extract + test debug SSE backpressure framing
Adversarial Wave A3 flagged the hand-rolled SSE drop/marker logic as the
untested weak point. Extract createFramePusher (drop under desiredSize<=0,
coalesced {kind:'dropped'} marker before the next delivered frame, null = no
backpressure) and unit-test it; the stream handler now uses it. Non-blocking
hardening — no behavior change.
2026-06-18 15:31:50 +08:00
DrSmoothl
fae2f75525 feat(webui): debug panel — action tester + live stream (Wave A3)
New Settings → 调试 tab (DebugPanel): an action tester (account picker +
schema-driven form from /api/debug/actions, with a raw-JSON escape hatch for
legacy actions, real-side-effect warning) and a live merged SSE view of OneBot
events + action calls (pause / clear / kind filter, expandable JSON, drop
marker). Typed debug API client domain (actions/invoke/stream over EventSource
with ?token=). View layer — verified by tsc + vite build.
2026-06-18 15:25:34 +08:00
DrSmoothl
39864f6e48 feat(webui): debug API — action schemas, invoke, live SSE (Wave A3)
GET /api/debug/actions (collectActionDocs for the tester form), POST
/api/debug/invoke {uin,action,params} (routes to that account's ApiHandler —
real side effects, /api/* auth, uin validated), GET /api/debug/stream (merged
SSE of OneBot events + action calls across accounts, tagged by uin+kind). Taps
attach only while a client is connected (on-demand); a slow client is dropped
with a periodic {kind:'dropped'} marker rather than buffering unbounded.
/api/debug/stream added to the ?token= allowlist for EventSource.
2026-06-18 15:20:06 +08:00
DrSmoothl
cde5a22ec8 feat(onebot): debug subscribe seams for NetworkManager + ApiHandler
Add NetworkManager.subscribeDebug (notified for every emitEvent, before the
adapter check, so the debug stream sees events even with no adapter) and
ApiHandler.setObserver (fires after every handled action with
{action,params,response,ms}, success or failure). Both Set-based, return an
unsubscribe, and swallow subscriber throws so they never break dispatch.
OneBotInstance exposes subscribeDebugEvents / observeActions / invokeAction.
Foundation for the Wave A3 debug stream + action tester.
2026-06-18 15:17:28 +08:00
DrSmoothl
d2e8222886 fix(webui): A2 backup — per-uin onebot config, no-store, atomic restore
Adversarial Wave A2 pass, 3 MAJORs:
- #3/#3b: the allowlist missed per-account config/onebot_<uin>.json (the file
  that actually carries each account's network config + OneBot access token).
  Add it via an /^onebot_\d+\.json$/ pattern; classify ALL onebot config
  (global + per-uin) as credential since it holds the access token — a
  no-credentials backup no longer leaks tokens. Export scans config/ for them.
- #6: GET export could carry the private key/hash; add Cache-Control: no-store
  + Pragma so the response is never cached.
- #4: refactor applyBackup → pure planRestore + a two-phase atomic restore in
  server.ts (snapshot → stage all .tmp → rename all), so a staging failure
  leaves the live config untouched; clean up stray tmp on failure.
2026-06-18 15:08:51 +08:00
DrSmoothl
0c20d58a8c feat(webui): backup/restore UI in system settings (Wave A2)
A '配置备份 / 恢复' card in the 服务 tab: export downloads the JSON bundle
(with an 包含登录凭据 toggle + red warning), restore picks a .json file and
calls importBackup with a 一并恢复登录凭据 toggle (default off). Shows
restored/skipped counts + restart-to-apply. Typed systemSettings.exportBackup/
importBackup client methods. View layer — verified by tsc + vite build.
2026-06-18 15:01:17 +08:00
DrSmoothl
c0e3bd0cff feat(webui): backup export/import API (Wave A2)
GET /api/system/backup/export?credentials=1 streams the JSON bundle (download
header); POST /api/system/backup/import validates then applies, snapshotting
current config to config/.restore-backup-<ts>/ first (recoverable), writing
atomically (tmp+rename), key.pem at 0600. Both behind /api/* auth; import body
capped at 32MB. Restore is restart-to-apply.
2026-06-18 14:57:46 +08:00
DrSmoothl
b71aedaa60 feat(webui): config backup/restore core (Wave A2)
Pure, tested backup module: buildBackup (allowlist → JSON bundle, credential
files gated), validateBackup (version/app/known-filename/no-traversal/entry
shape — rejects wholesale), applyBackup (snapshot-then-write, skips
credentials unless opted in). Credentials = webui.json + key.pem; cert.pem is
public and always travels. fs glue lands next in server.ts.
2026-06-18 14:56:12 +08:00
DrSmoothl
a38b33c8aa feat(webui): Select/Textarea UI components + hide installed TLS cert
Add reusable Select (styled native select + chevron) and Textarea components
matching Input's design language, and replace every native <select>/<textarea>
across the app (system-panel, node-edit-dialog, notification-channel-dialog,
settings customCss, widget note) with them.

TLS cert UX: once a cert is installed, the sensitive PEM is no longer rendered
on revisit — show an '已安装(未改变)' summary with 更改/删除 buttons; 更改
reveals the inputs again (with a 取消). Private key is never sent back to the
client. Verified by tsc + vite build.
2026-06-18 14:53:43 +08:00
DrSmoothl
675261691f fix(webui): make key.pem chmod best-effort (match auth.ts)
Wrap the post-write chmodSync in try/catch like auth.ts: the key is already
written with mode 0600, so a rare chmod failure shouldn't misreport a
successful write as a 500.
2026-06-18 14:45:09 +08:00
DrSmoothl
a4b226f1d0 fix(webui): write key.pem with 0600 (was world-readable)
Adversarial Wave A1 pass (MAJOR): the TLS private key was written with the
default umask mode (typically 0644 — world-readable). Write config/key.pem
with mode 0600 + an explicit chmodSync (writeFileSync's mode is ignored for an
existing file), mirroring auth.ts's webui.json handling. cert.pem stays public.
2026-06-18 14:43:27 +08:00
DrSmoothl
82d5f782a3 feat(webui): system settings panel (port/host/TLS/trust-proxy)
New Settings → 服务 tab (SystemPanel) over the /api/system/settings + TLS cert
API: edit port / bind host / trust-proxy, paste cert+key PEM to enable HTTPS,
delete cert. Flags env-overridden fields ('被环境变量覆盖') and shows a
restart-to-apply banner (no self-restart). Typed systemSettings API client
domain. View layer — verified by tsc + vite build (webui has no component-test
infra).
2026-06-18 14:39:35 +08:00
DrSmoothl
7faef1b7c0 feat(webui): system settings + TLS cert API (Wave A1)
GET/POST /api/system/settings (port/host/tlsEnabled/trustProxy) persisted via
updateRuntimeConfig — listener-level, restart-to-apply; response carries
restartRequiredToApply + the env-overridden field names so the panel can flag
edits that won't take effect. Enabling TLS is blocked unless a usable cert is
present. POST/DELETE /api/system/tls/cert validates a pasted PEM pair
(validateTlsPair) before writing config/cert.pem + key.pem. Adds read-only
readRuntimeConfig() and a tested pure coerceSettingsPatch validator. All routes
sit behind the existing /api/* auth middleware.
2026-06-18 14:32:24 +08:00
DrSmoothl
9a455b30c6 feat(common): updateRuntimeConfig(patch) for the WebUI settings panel
Persist a partial RuntimeConfig update, merging onto the on-disk config (not
the env-merged view) so an env override is never baked into runtime.json.
Tested: patch merge + the env-not-persisted invariant (chdir to a temp cwd).
2026-06-18 14:28:31 +08:00
DrSmoothl
ad21e19dc8 feat(webui): source trustProxy from runtime config (env still overrides)
Move the trust-proxy/client-ip resolver from a module-level direct read of
SNOWLUMA_WEBUI_TRUST_PROXY into initWebUI, fed by runtime.json's trustProxy
(loadRuntimeConfig already merges the env override on top). Default '' parses
identically to the old undefined (trust socket peer only), so behavior is
unchanged when unset.
2026-06-18 14:26:32 +08:00
DrSmoothl
64c10e2856 feat(webui): HTTPS serving + configurable bind host
initWebUI now takes { host, tlsEnabled }. When TLS is enabled, load+validate
config/cert.pem + key.pem (tls.ts: validateTlsPair / resolveTlsContext, both
unit-tested) and serve via @hono/node-server's https createServer; a missing
or invalid cert falls back to HTTP with a loud warning (never bricks the WebUI).
Bind host is now configurable (default 0.0.0.0). Wired from runtime.json
(webuiHost / webuiTls.enabled) in core/index.ts.
2026-06-18 14:24:51 +08:00
DrSmoothl
77b16faebb feat(common): extend RuntimeConfig for WebUI listener settings
Add webuiHost / webuiTls.enabled / trustProxy to RuntimeConfig as the shared
system-settings model for WebUI Wave A1 (HTTPS + self-config panel). Refactor
load into pure, tested normalizeRuntimeConfig + resolveRuntimeEnvOverrides
(env wins, in-memory only; SNOWLUMA_WEBUI_HOST added alongside the existing
PORT/TRUST_PROXY overrides). loadRuntimeConfig backfills older runtime.json
with the new defaults. Adds vitest to @snowluma/common (was typecheck-only).
2026-06-18 14:19:45 +08:00
DrSmoothl
90d3f7c0d6 test(protocol): real byte-oracle for ocr_image request wire
Adversarial Wave 3 pass: the prior 'round-trip locks pb tags' test was a
fake lock — symmetric encode/decode via the same proto would not catch a tag
swap. Replace with a fixed hex byte-oracle (hand-decoded in the comment) that
goes red on any tag change, plus an empty-ocr-body deserialize test. Note in
the action that a passed-in URL is used verbatim (not rkey re-signed).
2026-06-18 00:40:26 +08:00
DrSmoothl
e07090376a feat(onebot): implement ocr_image via OIDB 0xE07_0
Server-side image OCR ported from Lagrange.Core ([Service]
"OidbSvcTrpcTcp.0xe07_0") cross-checked with NapCat's Oidb.0xE07 proto
(NapCat's transformer cmd 0xEB7 is a typo; the proto name + Lagrange + the
wire name all say 0xE07_0). New ImageOcr service + proto types, misc.ocrImage
api, and the ocr_image/.ocr_image action. The cmd takes an image URL, so the
action accepts an http(s) url or a cached image file_id (resolved via
getImageInfo); base64/local input is unsupported (NapCat's path is a
Windows-only kernel OCR, not portable). Wire round-trip + response-parse
tests lock the pb tags.
2026-06-18 00:36:07 +08:00
DrSmoothl
f936515a59 fix(onebot): get_rkey_server fails on empty rkey set; document rename return
Adversarial Wave 2 pass (no blockers): get_rkey_server now returns
ACTION_FAILED instead of an 'expired_time=now, no keys' shell when no
download rkey is available, so a caching caller can't misread 'unavailable'
as 'valid-but-expired'. Added an empty-list test. Annotated rename_group_file's
{ok:true} body as a deliberate NapCat-parity deviation from sibling file ops.
2026-06-18 00:26:34 +08:00
DrSmoothl
7625c18768 feat(onebot): add get_rkey_server (NapCat server-shape rkey)
Reshape the download-rkey list (type 10=private, 20=group, same 0x9067
source) into NapCat's GetRkeyServer shape {private_rkey, group_rkey,
expired_time, name}, expired_time = now + min present ttl. get_rkey /
nc_get_rkey already existed (raw list) and are left unchanged.
2026-06-18 00:21:35 +08:00
DrSmoothl
07988629f1 feat(onebot): implement rename_group_file (OIDB 0x6D6_4)
Add the file-rename slot to the group-file OIDB envelope (req/resp field 5),
a RenameGroupFile service mirroring MoveGroupFile, a groupFile.rename() api
method, and the rename_group_file action (params group_id/file_id/
current_parent_directory/new_name, NapCat-aligned), replacing the stub.
Wire fields (busId=102, parentFolder=current dir, newFileName) verified
against NapCat's Oidb.0x6D6 transformer; subCommand 4 cross-checked against
the move op (sub 5 on both sides). Serialize + envelope round-trip test locks
the pb tags.
2026-06-18 00:19:00 +08:00
DrSmoothl
0ba5eba31c fix(onebot): neutral get_file cache-miss message, drop fake test
Second adversarial pass: the previous 'unsupported' wording over-corrected
— it mislabeled a genuinely-uncached image file_id as 'unsupported',
mirroring the original defect. A double cache miss is runtime-indistinguishable
between a group-file id and an evicted image/voice, so the message now states
the cache miss neutrally and offers get_group_file_url as guidance only. The
prior 'group-file id' test took the same code path as the cache-miss test
(a fake test); consolidated into one honest assertion.
2026-06-18 00:08:44 +08:00
DrSmoothl
dbb5160be7 fix(onebot): clarify get_file limitation + honest _mark_all_as_read summary
Adversarial review of Wave 1: get_file's 'file not found in cache' was
misleading for group-file file_ids (unsupported here, not uncached).
Distinguish the two in the error message, surface the limitation in the
summary, and lock the contract with a negative test. Also annotate
get_group_shut_list's ~60s cache-delay tradeoff and mark _mark_all_as_read
as an explicit no-op pending an RE'd one-shot read cmd.
2026-06-18 00:05:20 +08:00
DrSmoothl
84e5254c3a feat(onebot): implement get_file via media cache resolution
Resolve file_id against the image cache, then the record cache (both
already mint a fresh url + carry file_size/file_name), replacing the
not-yet-implemented stub. Document-type files have no id-resolvable
cache yet, so they are intentionally left uncovered rather than faked.
2026-06-17 23:58:00 +08:00
DrSmoothl
8144dd9c27 feat(onebot): implement get_group_shut_list via member shutUpTime
Derive the muted-member list from the TTL-cached group member list
(shutUpTime = absolute expiry epoch seconds), replacing the placeholder
that always returned []. NapCat-shaped output {user_id,nickname,shut_up_time}.
2026-06-17 23:57:12 +08:00
snowluma-bot[bot]
5d08fc8471 Merge pull request #103 from SnowLuma/dev
chore: promote dev → main (16920b4)
2026-06-16 14:00:12 +00:00
DrSmoothl
16920b4444 chore(release): v1.9.12 2026-06-16 21:59:31 +08:00
DrSmoothl
f014defd54 feat(notifications): node-config-style channel manager + lock disabled-channel opt-in
Settings → 通知 now mirrors the node-config UX: info-only channel cards
(name / id / url / template + an inline enable toggle), create + edit via a
dialog, and all changes debounced-auto-save (no save button). The save path
is generation-guarded so a superseded in-flight save can't clobber a newer
edit; the test action flushes the pending save first so it never hits an
unsaved channel. The channel id is locked while editing to keep per-account
channelIds references from orphaning.

Per-account opt-in: a globally-disabled channel's toggle is now locked +
forced off (it can never fire). The id is kept in channelIds — the backend
already filters disabled channels — so re-enabling globally restores the
prior selection.

New: notification-channel-dialog.tsx. webui typecheck + build green.
Adversarial review: 0 blockers / 0 should-fix (2 nits applied).
2026-06-16 21:54:19 +08:00
DrSmoothl
0b7fb0c69d feat(notifications): P4 WebUI — channel manager, per-account opt-in, deliveries widget
- API client: notifications surface (getConfig/saveConfig/recent/test) + types.
- Settings → 通知 tab: global channel CRUD (id/name/url/body-template/enabled) +
  global debounce window, per-channel test-send, dirty-tracked save; invalid
  channels (bad slug / non-http URL) are dropped server-side and surfaced.
- Per-account 通用设置: opt-in toggles bound to notifications.channelIds, riding
  the ConfigPage's existing debounced autosave; stale opt-ins preserved.
- Overview: opt-in 最近投递 widget (polls /api/notifications/recent, read-only).
  Hidden-by-default set is now DERIVED from the catalogue (defaultVisible) and
  shared by desktop + mobile reconcile — replaces the hardcoded STATIC_WIDGET_IDS
  so a new opt-in widget can't reappear unbidden on existing mobile dashboards.

Typecheck + build green. Adversarial review: 1 should-fix (mobile hidden-set) +
2 nits found, fixed/triaged, and re-verified clean.
2026-06-16 19:53:31 +08:00
DrSmoothl
c0af18e1c2 feat(notifications): P3 HTTP face — channel config CRUD + recent + test-send
Bearer-gated WebUI routes:
- GET/POST /api/notifications/config — read/normalize the global channel store
  (whole-config CRUD, mirroring the ui-config pattern).
- GET /api/notifications/recent?limit=N — in-memory delivery history (≤100).
- POST /api/notifications/test {channelId} — one-off test to a single channel
  (ignores enabled/opt-in, sample vars, reuses render+POST, not recorded).

NotificationManager.testSend() added; initWebUI takes the manager (optional).
Tests: testSend unit coverage. 16 manager tests green, typecheck clean.
Adversarial review: 0 blockers / 0 should-fix / 0 nits.
2026-06-16 19:30:54 +08:00
DrSmoothl
30bcd97a3f feat(notifications): P2 manager — debounce state machine + render/POST + history
Global singleton observing every account's online/offline edge:
- Pure per-UIN debounce state machine (debounce.ts): an offline surviving
  debounceSeconds fires "offline"; recovery fires the paired "online"; a
  self-heal within the window fires nothing; a cold online fires nothing.
- NotificationManager (manager.ts): renders each opted-in + enabled channel's
  body template and POSTs it (single attempt + timeout, JSON), recording the
  outcome in a bounded in-memory history (lost on restart). Side effects
  (config/channelIds/post/clock) are injected for testability.
- BridgeManager: single-callback setters → additive listeners so OneBotManager
  and NotificationManager observe independently; close edge now carries the
  bridge (read nickname before dispose); fire-all with per-listener try/catch.
- Wired into the composition root, bound after OneBotManager.

Tests: debounce machine (pure, all misfire sequences) + manager (selectChannels,
dispatch, history cap, fake-timer self-heal/pairing). 23 green, typecheck clean.
Adversarial review: 0 blockers / 0 should-fix (2 NITs applied).
2026-06-16 19:20:55 +08:00
DrSmoothl
34d05f41f5 feat(notifications): P1 config layer — global channel store + per-UIN opt-in
Global channel store at config/notifications.json, mirroring ui-config's
total-normalize + atomic-write + cached-load conventions: NotificationsConfig
(version, debounceSeconds clamp [0,3600] default 30, channels[]), a total
normalizeNotificationsConfig (drops malformed/non-http channels, dedupes by
id, strips unknown fields), and the pure renderTemplate ({key} substitution;
missing keys left as-is; no re-expansion of substituted values).

Per-UIN opt-in: OneBotConfig.notifications.channelIds (validated slugs,
last-write-wins merge across global+per-uin, deduped) in the onebot package.

Tests: 19 (core notifications-config) + 12 (onebot config), all green.
Adversarial review: 0 blockers / 0 should-fix.
2026-06-16 19:02:01 +08:00
DrSmoothl
bf5978fb51 chore(spike): remove KickNT body-capture probe — capture complete
The read-only push-body probe in Bridge has served its purpose; the KickNT
push body and its reason fields are captured for the upcoming notification
reason-enrichment. Bridge back to baseline.
2026-06-16 18:37:22 +08:00
DrSmoothl
652a817568 chore(spike): retire KickNT force-offline probes, keep read-only body capture
Conclude the spike on the inbound
`trpc.qq_new_tech.status_svc.StatusService.KickNT` push and remove its
throwaway instrumentation:

- Bridge: drop the outbound send probe.
- HookSession: drop the loggedIn-gate bypass; restore `if (!this.loggedIn) return;`.
- HookManager: drop the disconnect-timing log.

Keep one read-only `[KICK-BODY]` probe in Bridge that logs the KickNT push
body (hex + utf8) so the reason fields (tipsTitle / tipsDesc) can be reversed
for the upcoming notification reason-enrichment. Remove once captured.
2026-06-16 18:17:46 +08:00
DrSmoothl
fb567177b4 feat(webui): Apple-widgets dashboard editor — gallery drag in/out
Reworks the desktop overview edit UX from per-card show/hide toggles to an
Apple-widgets model:

- The grid shows only the widgets that are on it; hidden ones live in a new
  right-side 部件库 ("store") panel that slides in during edit mode.
- Add: drag a gallery tile onto the canvas (HTML5 DnD) — dropped at the cursor
  cell, driven entirely through React state.
- Remove ("hide"): drag a card back onto the gallery (gridstack `removable`).
  Move/resize/remove all funnel through one onChange writer that derives removal
  from a block's absence in the grid snapshot — no separate handler, no state
  race.
- Card affordance: the big top "notch" bar is gone. Edit mode now shows two
  small square corner icons — a subtle semi-transparent drag hint (top-left, the
  whole card stays draggable) and the settings gear (top-right, configurable
  widgets only). The eye toggle is removed.

Mobile is unchanged (single-column reorder panel) — the gallery drag UX is
desktop-only by design.
2026-06-16 14:57:39 +08:00
DrSmoothl
2913a7a19b test(webui): regression tests for ui-config normalizers (B4)
First test coverage for the WebUI config trust boundary + the B1–B3 schema
additions (22 cases in packages/core/tests):

- normalizeAppearance totality (garbage → defaults, clamps, bad enums); custom
  fonts accept free-form families but reject control chars/injection/over-length;
  cssVars keep only whitelisted tokens with break-out-proof colour values.
- normalizeLayout: overviewMobile/topbarItems order-preserving + de-duped +
  fallback; overviewBlocks coord clamping; per-widget config 4096-byte cap.
- normalizePages: logs preset oneOf (unknown → custom).
- sniffImageMime magic bytes; normalizeUiConfig never derives image fields from
  the value.
- fs-backed (isolated temp cwd + fresh module): saveUiConfig forces the
  server-managed image fields (client can't forge hasImage); publicAppearance
  strips customCss but keeps cssVars + other cosmetic fields.
2026-06-16 14:38:57 +08:00
DrSmoothl
7355fe9ea4 feat(webui): log buffer export + view presets (B3)
- 导出当前视图: a toolbar button dumps the current (filtered) log view to a
  client-side `.log` text file — no server endpoint, respects the active level
  filter + search.
- 视图预设: 开发 / 运维 / 精简 presets bundle the existing display prefs
  (visibleLevels / maxLines / autoScroll / wrap); a new `UiLogsPrefs.preset`
  field stores the active id. Any hand edit to those prefs drops to 自定义.
  The client owns the preset→prefs bundles; the server just stores + validates
  the id (oneOf, defaults custom). No non-chronological reordering, per plan.
2026-06-16 14:36:02 +08:00
DrSmoothl
1a0bc12ec0 feat(webui): kiosk (展示模式) for chrome-free wall displays (B2)
A session-sticky kiosk mode for showing the dashboard on a wall display:

- Entry: `?kiosk=1` URL param (stripped after read) or a top-bar button
  (toggleable via topbarItems 'kiosk').
- Hides the sidebar + top bar (MainLayout) and any in-content edit entry marked
  data-kiosk-hide (the overview 编辑布局 toolbar) via an html[data-kiosk] CSS rule.
- Exit: Esc key or a dim corner button.

Purely cosmetic — never touches auth and issues no token. A new KioskProvider
(sessionStorage-backed, mounted under LayoutProvider) owns the state.

Completes the B2 dashboard/components batch.
2026-06-16 14:32:57 +08:00
DrSmoothl
72e0d6bcca feat(webui): static note / link / account widgets (B2)
Three opt-in static widgets join the GRID_WIDGETS catalogue (hidden by default
— enabled from the layout editor), with content stored in block.config:

- 便签 (note): pre-wrap plain text, capped at 4000 chars (under the server's
  4096-byte config cap). No Markdown.
- 链接卡 (link): label + http(s)-only url (javascript:/data: rejected) + an
  icon from a curated lucide set; renders as a clickable card.
- 账号快捷卡 (account): a specified uin's avatar/nickname/online dot, with a
  datalist of connected accounts in the config form.

GridWidgetSpec gains `defaultVisible`, honored by defaultOverviewGrid/Mobile and
migrateOverviewBlocks; reconcileLayoutItems gains a `hiddenByDefault` set so the
mobile catalogue appends these hidden too. parse* validators keep config total
over corrupt input.
2026-06-16 14:28:56 +08:00
DrSmoothl
60d1f0b04f feat(webui): config forms for host + connections widgets (B2)
Adds the gear config form to two more overview widgets (stat tiles stay
form-less, per plan):

- 主机资源 (host): toggle which resource panels show (CPU / 内存 / 运行进程);
  the grid column count tracks the visible panel count, and an all-off config
  falls back to all-on (no empty card).
- OneBot 连接 (connections): filter by account nickname/uin, an "仅显示异常端点"
  toggle (drops healthy adapters and emptied accounts), and sort by 默认 /
  名称 / 异常优先 (worst status first).

Both register in CONFIGURABLE_WIDGETS with parse* validators, render via the
existing dialog, and surface on mobile through the same per-widget config map.
2026-06-16 14:24:21 +08:00
DrSmoothl
23048894b5 feat(webui): top-bar element show/hide (B2)
The top-bar's optional right-side elements (connection-status badge, theme
toggle) are now toggleable via `topbarItems`. Essential controls — the
menu/collapse button, page title, and logout — always render and aren't listed.

- A TOPBAR_CATALOGUE (id+label) drives both the render gating and the settings
  toggles; TopBar reconciles `topbarItems` against it so a new element defaults
  to shown.
- A 顶栏 group in settings → 外观 exposes one switch per catalogue element.
2026-06-16 14:20:23 +08:00
DrSmoothl
754621de04 feat(webui): independent single-column mobile overview (B2)
Phones now render the overview from the dedicated `overviewMobile` ordering
instead of deriving a 1-column view from the desktop grid — the two layouts are
fully disjoint, so reordering on a phone never touches grid coords and vice
versa.

- View mode reuses DashboardGrid (drag disabled, cols=1), stacking each widget
  at its catalogue height via a pure prefix-sum, so cards keep their cell
  sizing. Per-widget config is shared with the desktop blocks.
- Edit mode surfaces a motion `Reorder` drag-sort panel (grip + show/hide eye +
  config gear for configurable widgets) — no 2D drag on mobile, per plan.
- The 编辑布局 toggle now appears on mobile too, with a mobile-specific hint.

Order/visibility reconciles against the live widget catalogue, so a widget
added later just appears on phones as well.
2026-06-16 14:18:40 +08:00
DrSmoothl
45d651614b feat(webui): layout schema for mobile overview + topbar items (B2)
Schema foundation for the B2 dashboard batch, mirroring the navItems shape:

- `overviewMobile: UiLayoutItem[]` — a separate single-column (id+visible)
  ordering for phones, kept fully disjoint from the desktop 2D `overviewBlocks`
  grid so mobile ordering never pollutes grid coords.
- `topbarItems: UiLayoutItem[]` — show/hide list for toggleable top-bar
  elements (status badge, theme toggle, kiosk button); essential elements stay
  pinned in the consumer.

Server `normalizeLayout` round-trips both (idOr + dedup, total over corrupt
input); defaults seed first run. `LayoutContext` exposes them with
setOverviewMobile/setTopbarItems setters and reconcile-on-consume semantics, so
adding a widget/element later just appears. Old configs lacking the fields fall
back to defaults on load.

Consumers (mobile render, topbar render + config, drag-sort panel) land in
follow-up B2 commits.
2026-06-16 14:14:03 +08:00
DrSmoothl
6d4e8538ea fix(ui): add focus-visible ring to ToggleSwitch and Sheet close (B1)
Keyboard-a11y polish to match the codebase's standard
`focus-visible:ring-[3px] focus-visible:ring-ring/40` treatment:

- ToggleSwitch (role=switch, used across every settings/config surface) had
  no focus-visible ring — keyboard users got no focus indicator.
- Sheet's close button used a bare `focus:outline-none`; now mirrors the
  Dialog close button's ring.

Slider, Button, Input, Select, Tabs, Checkbox, Switch already carry the ring.
2026-06-16 14:10:04 +08:00
DrSmoothl
636189d7c9 feat(webui): CSS snippet templates + low-contrast accent advisory (B1)
- Custom-CSS editor stays a plain <textarea> (native Cmd/Ctrl+Z undo) but
  gains insert-at-cursor template buttons (string-constant snippets) and a
  best-effort on-blur validation that warns on unbalanced braces or CSS that
  parses to zero rules. Never blocks saving; ?safe-mode=1 remains the escape.

- Accent picker: choosing a custom colour whose contrast against the canvas
  falls below WCAG 3:1 surfaces a one-time (per-session) advisory offering to
  revert. Pure-advisory — applies immediately, no persistent banner, no nag.
2026-06-16 14:08:09 +08:00
DrSmoothl
5b07f518cc feat(webui): custom fonts + theme-variable override panel (B1)
Adds two appearance customizations from the WebUI plan's B1 batch:

- Custom fonts: new `fontSansCustom`/`fontMonoCustom` free-form family
  fields (mirroring accent's preset/custom dual-field). A "自定义" segment
  reveals a text input; on Chromium it gets a native <datalist> of installed
  fonts via `queryLocalFonts()`, feature-detected with a silent fallback to
  a plain text box on Firefox/Safari/mobile. No font-file uploads.

- Theme-variable panel: new `cssVars` map lets the operator override
  individual theme tokens (background/foreground/primary/…) with colour
  pickers, layered last over palette+accent. Both keys (token whitelist) and
  values (hex/named/functional colour) are validated, so — unlike customCss —
  this stays safe to serve to the unauthenticated login page.

Server `normalizeAppearance` gains `fontFamilyOr` (rejects control
chars/injection) and `normalizeCssVars` (whitelist keys + colour-only values,
total over corrupt input). Client `ThemeContext` re-validates defensively
(the localStorage cache is locally tamperable) before injecting into CSS.

Tests for the new normalizers land with the B4 batch.
2026-06-16 14:04:59 +08:00
DrSmoothl
e0d5b47488 feat(msg-push): filter C2C control pushes by c2c_cmd, matching QQ NT (#102)
Upgrades the blank-body heuristic to NT's exact discriminator. RE of
wrapper.linux.node (msg_header_codec_helper.cc::DecodeRoutingHead, sub_3B42650)
shows the official client classifies a C2C push by (svr_msg_type, c2c_cmd):
msgType ∈ {141,166,167} with c2c_cmd ∈ {1,73,75,129,131,133,135,192} is routed
through OnRecvSysMsg (long_cnn_msg_mgr.cc) as a system/control signal and never
shown as a chat bubble — the group-invite "[空消息]" phantom is one of these.

- proto-defs: ContentHead field 3 was mislabelled `divSeq`; it is `c2c_cmd`.
  Renamed (only other use was forward.ts, which zeroes it on a fake send).
- MsgPushHead now carries c2cCmd; new isC2cControlPush() in blank-filter.ts.
- parseMsgPush + both history fetches drop control pushes by (msgType, c2cCmd)
  regardless of body, so a control signal carrying stray content is caught too
  (not just the empty case). isBlankMessage stays as the fallback for
  content-less pushes we don't yet classify by cmd. Live path debug-logs a
  control push that carried elements, in case the table ever eats real content.

NOTE: the c2c_cmd set is taken from NT; we have not captured #24's actual cmd
(our diagnostic never logged field 3), so the blank fallback remains load-bearing
until a live capture confirms which cmd the invite phantom uses.
2026-06-16 01:34:38 +08:00
DrSmoothl
2ffb6192dd fix(msg-push): drop blank "[空消息]" pushes in c2c/group history too (#102)
The #102 fix dropped content-less control pushes only in parseMsgPush (live).
History fetches (fetchC2cMessageRange / fetchGroupMessageRange) decoded straight
into the result, so the same phantom resurfaced as "[空消息]" on backfill. RE of
wrapper.linux.node confirms QQ NT filters blanks on BOTH paths — live/roam C2C
via c2c_roam_msg_mgr.cc::FilterBlankMsgAndRetryFetch and group roam via
group_roam_msg_worker.cc::FilterBlankSeqsMsg.

Extracts the blank test into blank-filter.ts (bodyHasDecodableContent +
isBlankMessage) and applies it in all three message-producing paths. A message
that decoded to 0 elements but whose body carried content is a missing decoder,
not a blank — isBlankMessage returns false there so it's kept (live path still
warns).
2026-06-16 01:24:31 +08:00
DrSmoothl
d5af6b10ef fix(msg-push): drop genuinely-empty c2c push instead of surfacing "[空消息]" (#102)
A group invite makes QQ emit a content-less c2c message (msgType=166/0, body
richText.elems=[]) right after the invite card. The TRACE log from #102's
diagnostic confirmed the body is truly empty — no commonElem, no msgContent,
no ptt/file — so it's a phantom control push, not an element type we fail to
decode. It was reaching OneBot clients as a confusing "[空消息]".

parseMsgPush now drops a message-kind event that decodes to zero elements when
its body carries nothing decodable. When the body *did* carry content but still
decoded to nothing (a real missing decoder), the event is kept and a warning
fires so the gap gets noticed rather than silently swallowed — replacing the
temporary #102 diagnostic with the actual fix.
2026-06-16 00:54:28 +08:00
DrSmoothl
300fa70148 feat(spike): add logging and handling for KickNT command in bridge and session 2026-06-16 00:34:03 +08:00
DrSmoothl
6003acac56 chore(msg-push): log body of empty-decoded messages (#102 diagnostic)
A group invite surfaces a content-less "[空消息]" friend message (#102). Before
deciding whether to drop or decode it, we need to know what its body actually
carries — SnowLuma's decoder covers fewer element types than Lagrange, so an
empty decode may be a missing decoder (real content) rather than a genuinely
empty control push.

parseMsgPush now warns, on any message that decodes to zero elements, with a
summary of the body: each element's field names, every commonElem's
serviceType/businessType + payload hex, and any msgContent. One log line is
enough to identify the culprit element offline.

No behavior change — the message still dispatches as before. Temporary; remove
once the #102 culprit is identified and handled.
2026-06-15 22:07:50 +08:00
DrSmoothl
b0bfb9e6a7 feat(contacts): resolve non-member group name via 0x88D_0 (group invites)
A group invite push carries no group name (confirmed across SnowLuma / Lagrange
/ NapCat — all three invite protos only have groupUin + invitorUid), and
get_group_info only resolved joined groups (fetchGroupList → roster), so an
invited group rendered "未知群名". Add a by-id server lookup so the name
resolves even when the bot isn't a member.

- proto-defs: 0x88D_0 request (field1 + config.uin + a request-mask `flags`
  block) + response (groupInfo.results: name / member counts / owner / …),
  field tags transcribed from
  dev/Lagrange.Core/.../OidbSvcTrpcTcp0x88D_0{,Response}.cs.
- protocol: FetchGroupDetail oidb-service. Envelope reserved=0 (NO uinForm) —
  Lagrange's GetGroupInfoService builds it with isUid=false.
- core: ContactsApi.fetchGroupDetail(gid) → QQGroupInfo | null; deliberately
  NOT remembered into the joined-groups roster (mustn't pollute get_group_list).
- onebot: get_group_info falls back to fetchGroupDetail for non-member groups,
  behind a 5-min per-id TTL cache so a burst of invites for one group can't
  hammer 0x88D_0 (rate-limit / kick risk). noCache bypasses it.
- tests: request/envelope round-trip (reserved=0, uin, command), response
  decode; + non-member resolve / cache-hit / noCache-bypass at the onebot layer.

Live note: byte-identical to Lagrange's 0x88D_0, but not verified against a real
account on this host.
2026-06-15 14:33:06 +08:00
snowluma-bot[bot]
e5e6d50f2f Merge pull request #101 from SnowLuma/dev
chore: promote dev → main (7e59dbf)
2026-06-15 05:58:03 +00:00
DrSmoothl
7e59dbf79b chore(release): v1.9.11 2026-06-15 13:57:38 +08:00
DrSmoothl
28633f3c62 feat(onebot): back-fill a quoted message from the server when not stored
When an incoming reply quotes a message SnowLuma's store doesn't have (e.g. one
from before it was running, or never observed), the receive pipeline now fetches
just that message from the server and persists it before dispatch — so a
consumer's get_msg on the quote resolves instead of returning "message not
found". Works for both group and private (c2c).

- core: MessageApi.getGroupMessageBySeq / getC2cMessageBySeq — fetch a single
  message over a 1-wide [seq,seq] range, through the shared history throttle
  gate (same rate-limit as the bulk history APIs — no flood / kick risk).
- onebot: backfillReplyTarget — on a group/friend reply whose target isn't in
  the store, fetch (group SsoGetGroupMsg / c2c SsoGetC2cMsg, uid resolved for
  c2c) and persist under the EXACT id the reply resolves to, so get_msg hits
  regardless of who sent the quoted message (a bot self-sent c2c message
  converts with user_id=self but is keyed under the peer session). Awaited
  before dispatch so the consumer sees it; best-effort — a back-fill failure
  never blocks delivery of the live message.
- tests: gating (already-stored / no-reply / nothing-on-server) + keying
  (group, c2c, c2c self-sent under peer session).

Only fires on a store miss, so the common path (no reply, or quote already
stored) stays zero-cost.
2026-06-15 13:53:04 +08:00
DrSmoothl
cf8e62d2ac fix(onebot): resolve c2c reply target by srcMsg friendSequence, not origSeqs
Replying to a bot self-sent private message still failed get_msg on the quoted
id ("无法解析申请信息"). Root cause is the reply DECODE, not the keying: for a
c2c (friend) reply the canonical replied-to sequence is carried in
srcMsg.pbReserve.friendSequence (tag 8), while origSeqs[0] holds the per-sender
clientSequence. The decoder read origSeqs[0], so the reply resolved to a
sequence that never matches how the original message is keyed (by its server /
private sequence) — get_msg missed. Mirrors Lagrange's incoming-reply rule
`Sequence = reserve.FriendSequence ?? OrigSeqs[0]` (ForwardEntity.cs +
SourceMsg.PbPreserve.cs ProtoMember(8)).

- proto-defs: +SrcMsgPbReserve { receiverUid@7, friendSequence@8 }
- protocol: decodeRichBody reads friendSequence for c2c replies (group keeps
  origSeqs[0], the shared group seq); fall back to origSeqs[0] when absent
- tests: c2c→friendSequence, group→origSeqs[0], no-reserve→fallback

This supersedes the keying approach in 4571864 (self-sent c2c keyed by
clientSequence), which is fully reverted here: the message is keyed by its
private sequence as before, and the fix is purely on the decode side so it also
covers replies to *received* old c2c messages, not just self-sent ones.
2026-06-15 11:58:28 +08:00
DrSmoothl
457186419f fix(onebot): key self-sent c2c messages by clientSequence so replies resolve
A friend replying to a bot self-sent private message → bot get_msg(quoted id)
returned "message not found" (bot then answered "无法解析申请信息"). c2c replies
reference a message by the sender's clientSequence, not the server sequence
(Lagrange: OrigSeqs = ClientSequence || Sequence), but self-sent private
messages were keyed by the server (private) sequence — so the incoming reply's
resolved id hash(clientSequence, peer, private) never matched the stored event.

Reply-SENDING still worked because it only needs the meta row (resolveReplySequence
queries by hash, no data), not the full event (findEvent requires data IS NOT
NULL) — which is exactly why get_msg / "引用解析" failed but replying didn't.

Key self-sent c2c messages by clientSequence (fallback to sequence, mirroring
Lagrange's `||`) via a shared c2cSelfMessageId helper, across all three c2c
self-sent paths (send_private_msg, private forward, forward-single-to-user).
Group messages unchanged (their replies reference the shared group sequence).
2026-06-15 10:03:26 +08:00
DrSmoothl
9dfa31bdbc fix(onebot): allow negative message_id in get_{group,friend}_msg_history
message_id is a signed int32 hash (hashMessageIdInt32) and is frequently
NEGATIVE, but both history actions declared it as `f.int({min:0}).default(0)`
— so a real anchor like message_id=-497311472 was rejected at param
validation (retcode 1400, 0ms) before run() fired, and the server-side
history fetch never happened (the client then reports "未找到足够的群聊记录").

Drop the min:0 bound → `f.int().default(0)`: negatives pass, absent/present-0
still mean "fetch latest", count stays ≥0. Matches every other action, which
uses f.messageId() for signed message IDs.

Regression tests: negative group/friend anchors now reach the handler;
absent message_id still defaults to 0.
2026-06-14 23:45:59 +08:00
DrSmoothl
8dc4ff48f8 feat(onebot): unify market faces to image segments + add send support
Market faces (商城表情) now decode to an OneBot `image` segment carrying
NapCat-style markers (emoji_id/emoji_package_id/key/summary) plus a gxh
gif URL, so clients that don't special-case `mface` still render the
sticker while aware clients can reproduce it.

Adds the previously-missing send path: a dedicated `mface` segment OR an
`image` segment carrying `emoji_id` rebuilds the wire `marketFace`
(faceId=hex(emoji_id), itemType 6 / subType 3 / 300×300 /
pbReserve.field8=1) — byte-matched against NapCat and Lagrange.Core.

- proto-defs: MarketFace.key bytes→string; +MarketFacePbReserve{field8@8}
- protocol: decode faceId→emojiId(hex)/tabId/key; makeMarketFaceElem +
  buildSendElems 'mface' case; format preview keeps the sticker name
- onebot: to-segment mface→image; message-parser mface + image(emoji_id)
- tests: wire decode + full proton round-trip; parse→build; segment shape

Reply/forward round-trips preserved (element keeps type 'mface' + text).
2026-06-14 20:47:50 +08:00
DrSmoothl
58c02d415f feat(onebot): fetch real private (c2c) history from server (#99)
Mirror the group-history fetch for private chats via SsoGetC2cMsg
(trpc.msg.register_proxy.RegisterProxy.SsoGetC2cMsg, fields per Lagrange:
flat friendUid/start/end request, messages@7 response). get_friend_msg_history
now resolves the anchor sequence + the friend's UID, fetches real history from
the server, converts + persists each message, and falls back to the local
store on unknown anchor / no uid / empty / error.

- protocol: fetchC2cMessageRange (decodes via the friend decoder).
- core: the group + c2c fetch now share a generic walkBackHistory loop
  (same throttle gate + caps); added MessageApi.getC2cHistory.
- onebot: getFriendHistory + a generalized persistHistoryEvent (keys private
  by sender uin, exactly like the live path — so reply to old private
  messages resolves too).

Tests: SsoGetC2cMsg request/response round-trip + friend-decode reuse.
2026-06-14 20:15:38 +08:00
DrSmoothl
987ac09896 feat(onebot): fetch real group history from server (#99)
get_group_msg_history was served only from the local observed-message store,
so it could never return more than what SnowLuma saw live (the "only 100
messages" symptom). It now fetches real history from the server.

- protocol: new SsoGetGroupMsg packet (trpc.msg.register_proxy.RegisterProxy
  .SsoGetGroupMsg, sequence-range fetch; fields per Lagrange). Each returned
  PushMsgBody is decoded by the existing group decoder via a factored-out
  buildContextFromMessage.
- core: MessageApi.getGroupHistory walks backward in small sequence windows
  with rate-limiting + data-volume guards — a process-wide throttle (≥300ms
  between sends), 30-seq chunks, ≤12 requests, ≤200 messages per call — so a
  hammering client can't make us flood the server and get kicked.
- onebot: get_group_msg_history resolves the anchor sequence (requested
  message_id or latest observed), fetches from the server, converts + returns,
  and persists each fetched message. Falls back to the local store on
  unknown anchor / empty / error.

Persisting fetched history also fixes replying to pre-injection messages:
the reply path resolves message_id→sequence via the store, which now contains
the fetched messages.

Tests: SsoGetGroupMsg request/response round-trip + decode reuse (protocol);
walk-back chunking/dedup/cap/floor (core).
2026-06-14 19:11:03 +08:00
snowluma-bot[bot]
7d90820e19 Merge pull request #100 from SnowLuma/dev
chore: promote dev → main (ee8eb92)
2026-06-14 08:29:02 +00:00
DrSmoothl
ee8eb928b3 chore(release): v1.9.10 2026-06-14 16:28:39 +08:00
DrSmoothl
8f61b1486e feat(webui): Apple-style overview pass + roomier stat tiles
- Grid row height 80→108px so a 1-row stat tile's icon + 3 text lines clear
  the padding with real breathing room (the previous fix still clipped ~8px);
  stat tile gets an airier layout (size-10 icon, text-lg value, py-3.5).
- Carry the app's Apple language across the homepage: inner surfaces and
  empty-state containers round to xl, empty-state icons calm to size-8/opacity,
  edit hint + first-run nudge rounded consistently.
2026-06-14 16:20:19 +08:00
DrSmoothl
44a29c6ee4 feat(webui): OLED/accent/palette theming fixes + light-dark reveal
- OLED: toggle switch off-track is now a neutral foreground tint with a white
  knob (was invisible bg-muted + bg-background on pure black); the OLED sidebar
  override is scoped to sidebar-style=follow so panel/accent work in OLED too.
- Accent: the chosen accent now also tints the selected-state surfaces
  (--accent / --sidebar-accent) so the sidebar active item and settings nav
  rail follow it — default palette only, respecting accent scope.
- Palettes: add 6 more soft schemes (Rosé Pine / Moon / Dawn, Nord, Everforest
  dark + light) via a pal() builder; schema unions + normalizer + bootstrap
  light/dark classification updated to match.
- Light/dark switch now animates: a circular View Transitions reveal from the
  click (mode/palette/intensity changes only; gated off under reduced/disabled
  motion; instant fallback where the API is absent).
2026-06-14 16:20:05 +08:00
DrSmoothl
84021a19dc feat(webui): deep-link settings tabs via ?tab= and jump update banner to 关于
The settings sub-tab now lives in the URL (typed `?tab=` search param on the
/settings route, validated against the tab whitelist; default 外观 omits it).
The active tab is derived from the URL and tab clicks navigate (replace), so
tabs are shareable/back-button friendly. The sidebar "有新版本可用" banner now
links to /settings?tab=about, landing directly on 关于 (where 软件更新 lives)
instead of the default settings tab.
2026-06-14 15:45:42 +08:00
DrSmoothl
df0b79a87d feat(webui): restyle login page with Apple-style vibrancy
- Frosted "vibrancy" card (bg-card/65 + backdrop-blur-2xl) floating over the
  wavy background, with a centered brand focal point (logo tile, name,
  version, subtitle).
- Larger rounded fields/button (h-12, rounded-xl) for a calmer iOS feel.
- The "我觉得这个界面很卡怎么办?" help line becomes a 灵动岛-style frosted
  capsule (rounded-full, blur, float, spring on hover/tap).
- New entrance/hover motion gated on reduceMotion/disableMotion.
2026-06-14 00:47:56 +08:00
DrSmoothl
dc26cc93ba fix(webui): hide native Edge password reveal control on login
The login password field showed two eye icons — our custom show/hide
toggle plus Edge/IE's native ::-ms-reveal. Hide the native reveal/clear
pseudo-elements so only our toggle remains.
2026-06-14 00:46:46 +08:00
DrSmoothl
985dfd4705 feat(webui): animated login background + three independent motion settings
Login page now has a mouse-reactive wavy-line background (ported a-waves +
embedded Perlin noise, themed to the accent, rendered behind the card which
sits on a 95%-opaque blurred surface so content stays readable). A "我觉得这个
界面很卡怎么办?" link opens a dialog that toggles it off — a device-local
preference (localStorage, works pre-auth, defaults off when the OS prefers
reduced motion), independent of the system motion settings.

Motion settings are now three:
- 关闭登录页的动效 — the login background toggle above (device-local).
- 减弱动效 (reduceMotion) — soft: transforms/springs off, durations
  collapsed, page/sidebar instant; gentle entrance fades remain.
- 关闭全部动效 (disableMotion, NEW appearance field) — everything reduce does
  plus data-no-motion CSS (kills pulse dots; spinners excluded so "busy"
  stays legible) and the entrance opacity fades gated off across
  overview/processes/logs/config lists.
2026-06-14 00:41:18 +08:00
DrSmoothl
9dd46198cb feat(webui): custom scrollbars + sliders, stat-tile fit, reduce-motion
- Scrollbars: theme native scrollbars (thin, token-colored thumb) for plain
  overflow containers; Radix ScrollArea keeps its own custom bar (it hides
  the native one, so no double bar).
- Sliders: new <Slider> component + `.slider` CSS replaces the native range
  inputs (UI scale / mask opacity / blur). Filled track + ring-bordered
  thumb, themed; input height matches the track so the thumb centers in every
  engine; Firefox fills via ::-moz-range-progress.
- Stat tiles: tighten the h=1 tile (py-2 + mt-0.5) so the three text lines +
  padding fit the 80px cell without hugging the border.
- Reduce motion: gate the always-present sidebar-width + page-transition
  animations to instant when enabled (Framer's reducedMotion only suppresses
  transforms, so these needed an explicit opt-out); kill the slider thumb
  transition too.
2026-06-14 00:16:26 +08:00
DrSmoothl
7d647e0ed7 feat(webui): redesign settings About panel in the Apple style
Split the single centered card into a clean three-section stack consistent
with the rest of settings:

- Brand hero card: logo glow + name + version pill + tagline/description.
- "软件更新" grouped list (reuses Group/SettingRow): current-version row +
  check-update row (status dot/spinner + 重新检查); when an update exists, a
  tinted detail block with version, notes, platform asset hint and 前往下载.
- Support card: refined Star CTA + repo/releases/issues links.

UpdateStatus → UpdateGroup; all update states (checking/disabled/error/
latest) preserved.
2026-06-13 23:50:55 +08:00
DrSmoothl
e93a17de78 feat(webui): add Catppuccin Latte/Frappé/Macchiato/Mocha palettes
Add a "配色方案" picker offering the four Catppuccin flavors as full color
schemes alongside the default sky theme.

- Schema: new `palette` field on UiAppearance (core + client mirror),
  normalized to a 5-value whitelist defaulting to 'default'.
- Apply: each flavor's base/surface tokens are injected into the shared
  theme stylesheet over :root (Latte) or .dark (the three dark flavors);
  accent (--primary/--ring) stays separate so it composes. A flavor fixes
  light/dark (Latte→light, rest→dark), overriding `mode`, and forces
  dark-intensity to soft so the OLED "black" rule can't fight the palette.
  sidebar-style + high-contrast still compose (higher specificity).
- Pre-paint bootstrap is palette-aware (no light↔dark flash on reload).
- Settings: swatch-preview picker; mode + dark-intensity controls disable
  while a flavor is active. The top-bar ThemeToggle hides then (it would be
  inert under a fixed-scheme palette).
2026-06-13 23:42:16 +08:00
DrSmoothl
de598242ab feat(webui): apply Apple-style polish to processes + config pages
Carry the logs/settings visual language across the remaining pages:

- Processes: sort control becomes a segmented radiogroup; action banner
  gains a spinner; cards round to xl with a hover tint; calmer empty state.
- Config: save status collapses from bordered pills into one inline
  dot/spinner indicator; node summary rows round to xl with hover and
  fold the three flag badges into a single muted "数组 · 不上报自身 · 已设
  Token" line; empty states round to xl; account rail rounds to xl.

Presentational only — all state wiring and handlers unchanged.
2026-06-13 23:25:11 +08:00
DrSmoothl
3d480fb018 feat(webui): redesign settings page with macOS-style two-pane UX
Rework the settings page around the macOS System Settings layout, reusing
existing UI tokens (no new deps):

- Two-pane: a sticky left nav rail (w-52) on lg, a wrapping tab strip on
  mobile. Active section mirrors the app sidebar's selected style.
- Grouped inset lists: each Card is a header above a hairline-divided list
  of label-left / control-right rows (SettingRow: auto / inline / stack),
  replacing the stacked Field + Separator spam.
- Refined segmented control: recessed track with a raised pill on the
  selected segment (font-semibold + full ring so it survives high-contrast
  / OLED); exposed as a proper radiogroup (role=radio + aria-checked) and
  named via the row label through a small context + useId.
- Per-section fade transition; section heading anchors the detail pane.

Wide controls (时制, 深色强度, fonts, radius scale, poll interval, default
route) stack so they don't crowd their labels; password-saved confirmation
keeps its success color. All settings preserved 1:1.
2026-06-13 23:15:38 +08:00
DrSmoothl
5b253ea1d5 feat(webui): redesign logs page with Apple-style UX
Rework the run-log viewer around progressive disclosure and a calmer,
content-first hierarchy, reusing existing UI tokens (no new deps):

- Toolbar: live status dot (red when disconnected) replaces the badge;
  real search field with inline icon + clear; icon-only actions with
  tooltips, grouped (toggles in a track · divider · data actions).
- One always-visible segmented level filter (iOS-style raised pill +
  colored dot) instead of strikethrough pills.
- Collapse the server-level switch + highlight-rule editor into a single
  animated "选项" panel; server level also surfaced in the subtitle. The
  control area drops from three rows to one.
- Log stream: subtle sticky column header (时间/级别/模块/消息) aligned to
  rows via a sm:contents trick, dot-style level indicators, hairline row
  separators, and distinct empty / no-match states.

a11y: radiogroup on color swatches, aria-pressed on level toggles,
unique remove-button labels, focus rings on all controls.
2026-06-13 23:00:22 +08:00
DrSmoothl
a61e0a253d feat(webui): in-place dashboard edit overlays + inline sidebar reorder
Rework the layout edit mode from a separate panel to in-place affordances:
- Each dashboard widget gets a semi-transparent floating overlay in edit mode:
  a "拖动" grip bar (the whole card is the drag target — forgiving +
  discoverable), an eye to show/hide, and a gear that opens the per-widget
  settings in a dialog. Hidden widgets show as re-enableable "已隐藏" ghosts;
  the bottom-right resize grip is now clearly visible.
- The sidebar nav becomes a drag-to-reorder list directly in the sidebar
  (show/hide + locked pinned items + a 完成 button); editing force-expands the
  sidebar (and disables the collapse toggle). Edit mode is a shared
  LayoutContext flag so one "编辑布局" toggle drives both the grid and the nav.
- The separate editor panel (overview-layout-editor) is removed; the gear
  opens config in a dialog instead.

Also: stat-tile typography tightened (leading-tight, smaller value, overflow
clip) so text no longer hugs the edge on small/short tiles. Verified by an
adversarial review round (no MUST-FIX).
2026-06-13 21:45:41 +08:00
DrSmoothl
056fff415c feat(webui): per-page preferences (phase 7)
A `pages` section in config/ui.json (3rd section-merge alongside appearance +
layout):
- defaultRoute: the page to open after login (chosen in Settings → 数据与格式;
  DefaultRouteRedirect navigates there once, only from '/', respecting
  deep-links + later navigation).
- logs: persisted visible levels, max lines, auto-scroll, line-wrap, and
  keyword→colour highlight rules — edited live on the logs page; maxLines is
  read via a ref so it never re-subscribes the SSE.
- processes: pid / name / status sort (persisted, default from prefs).
- config: remembers the last-used tab.

"重置全部" now also clears pages. The server normalizer is total and caps the
logs fields (levels subset, maxLines 100-5000, <=20 highlight rules, trimmed
keywords). Verified by an adversarial review round (normalizePages total
against 30 adversarial inputs; zero MUST/SHOULD-FIX).
2026-06-13 21:17:24 +08:00
DrSmoothl
7c2923dd04 feat(webui): custom CSS + config export/import/reset (phase 6)
A "高级" Settings tab adds:
- Custom CSS (appearance.customCss, <=50KB) applied post-auth only, as the
  last <style> so it overrides everything. It never reaches the login page:
  the server strips it from /api/ui/public, applyAppearance gates injection on
  a bearer token (so the localStorage cache can't leak it pre-auth), and the
  login page clears any lingering <style> on mount. `?safe-mode=1` (sticky for
  the tab session) disables custom CSS so a broken rule can't lock the
  operator out.
- Export / import the whole UI config as JSON (import is normalized
  server-side, then reload); reset-all behind a confirm dialog.

POST /api/ui and the import file are size-capped (256KB) on top of the
per-field caps. Verified across 2 adversarial review rounds — the pre-auth
cached-CSS leak/lockout vector found in round 1 is closed across the boot /
logout / 401-expiry / re-login paths.
2026-06-13 21:17:23 +08:00
DrSmoothl
3258300539 feat(webui): per-widget config — alerts levels/count, sessions sort/filter (phase 5)
Overview widgets can carry an opaque `config` (stored per grid item). v1:
- alerts: how many entries + which log levels (was fixed at 5 warn/error);
  the alert row colour now uses the full 6-level palette instead of a
  warn/error binary.
- sessions: sort (recent / uin / nickname) + a nickname/uin filter.

A gear in the layout editor opens an inline config form per configurable
widget; edits apply live (no grid re-init — config isn't in the grid key) and
persist via the section-merge save. Config is parsed client-side with total,
clamping parsers (count 1-50, known levels only, filter <=100 chars); the
server stores it opaquely within a 4KB bound. Widgets with no config render
exactly as before. Verified across 2 adversarial review rounds.
2026-06-13 21:17:23 +08:00
DrSmoothl
f07f309c51 feat(webui): free-form draggable/resizable dashboard grid (phase 4)
The overview becomes a gridstack-backed free grid — drag, resize, and show/
hide 9 widgets (the 5 top stat tiles split out of the old single block, plus
connections/alerts/host/sessions), persisted to config/ui.json's
layout.overviewBlocks as {id,x,y,w,h,visible}.

- gridstack (zero-dep, vanilla; chosen over react-grid-layout whose
  react-draggable uses the React-19-removed findDOMNode). React renders each
  widget into a gridstack item via a portal (context flows through); gridstack
  owns layout/drag/resize. Per-widget minW/minH prevent content collapse.
- Desktop = editable in place; narrow screens = auto single-column, read-only.
  Fixed cellHeight => no ResizeObserver => the narrow column-clamp never
  persists over the desktop coords.
- Edit mode shows a panel: widget show/hide + nav reorder (the phase-3 motion
  list); the grid below is live-editable. Reset + empty-state preserved.
- Server UiLayoutItem gains optional x/y/w/h (clamped); the stats->5-tiles
  migration + default placement live client-side (lib/dashboard-layout.ts).

Verified across 2 adversarial review rounds (gridstack+React lifecycle traced
against the library source: StrictMode-safe, no mount-persist loop, no
re-init on coord change, no narrow-visit data loss).
2026-06-13 21:17:23 +08:00
DrSmoothl
a5335687ec fix(protocol): fetch group-join verify comment regardless of uin cache (#98)
The verify text a user types when requesting to join a group is never in the
push — it lives on the OIDB pending-request queue. The fetch
(resolveGroupJoinRequest) was gated behind the UID→UIN stranger-resolve, so
when the requester's uin was already cached the whole async path (and thus the
comment fetch) was skipped, leaving the OneBot request.group `comment` empty.

Decouple the two: every uid-bearing group_invite now goes through the async
enrich path (needsGroupInviteEnrich → dispatchGroupInvite), which ALWAYS
fetches the comment and resolves the UIN profile only when needed (the
fromUin === groupId cache-pollution self-heal is preserved). Matches
Lagrange's unconditional FetchGroupRequests and NapCat's notify.postscript.

Rewrites the cache-hit test (which had pinned the buggy behavior) into a
regression asserting the comment is fetched + applied on a cache hit.
346/346 protocol tests pass. Verified by adversarial review.
2026-06-13 12:03:04 +08:00
DrSmoothl
69ed8fc722 feat(webui): customizable dashboard + nav layout (phase 3)
The "C" half — reorder + show/hide the overview cards and the sidebar nav,
persisted to config/ui.json's layout section.

- LayoutContext loads the layout (authed GET /api/ui) and persists edits via
  the section-merge POST /api/ui {layout} (debounced). reconcileLayoutItems
  keeps stored order/visibility, appends new catalogue entries (forward-compat),
  and forces pinned items visible.
- Overview is refactored into a block registry (stats/connections/alerts/host/
  sessions). A 「编辑布局」 mode (motion Reorder — zero new deps) edits both the
  cards and the nav in place, with per-item show/hide and a reset; an all-hidden
  dashboard shows an empty state with 恢复默认.
- Anti-self-lock: PINNED_NAV = ['/', '/settings'] can be reordered but never
  hidden — the overview hosts the layout editor and settings hosts
  account/appearance, so the user can never strand themselves.
- api.ui.save now takes Partial<UiConfig> (the section-merge contract).

A late initial GET can't clobber an in-flight edit (dirtyRef); a pending edit
flushes on unmount. Verified across 2 adversarial review rounds.
2026-06-13 01:15:00 +08:00
DrSmoothl
ac1ffc46d3 feat(webui): appearance customization — theme/accent/background/fonts/a11y (phase 2)
Wires the Phase 1 store into a full appearance layer.

ThemeContext is rewritten to load/save UiAppearance from the server (with a
localStorage anti-flash cache + a one-time migration of the legacy per-browser
theme keys), apply ~12 dimensions to <html>, and theme the login page pre-auth.

New Settings controls (外观 / 数据与格式): free-hex accent (+ presets + apply
scope), dark intensity (soft / OLED black), sidebar style, background
(solid / gradient / uploaded image with opacity + blur), font presets, UI
scale, reduce-motion, high-contrast, default-collapsed sidebar, 12h/24h time
format (wired into logs + overview timestamps).

- index.html gains a pre-paint bootstrap script that applies the cached theme
  before the bundle mounts, eliminating the dark/OLED/scale FOUC.
- server saveUiConfig is now a section-level merge so appearance-only and
  layout-only saves never clobber each other.
- reduce-motion uses Framer MotionConfig; the background renders on a fixed
  layer revealed by transparent app roots; custom-accent hex and ui-scale are
  validated/clamped before use (localStorage-tamper hardening).

Verified across 2 adversarial review rounds (FOUC + CSS-injection + impure
state-updater + ref-staleness all fixed).
2026-06-13 01:15:00 +08:00
DrSmoothl
0b5087b410 feat(webui): UI customization config store + endpoints (phase 1)
Backend foundation for the WebUI appearance + layout customization feature.

- core/src/webui/ui-config.ts: config/ui.json store with TOTAL normalization
  (any input -> safe config), atomic write, lazy memoized cache, and the
  background-image lifecycle (magic-number sniff for PNG/JPEG/WebP).
- server.ts: GET/POST /api/ui (bearer), GET /api/ui/public (unauth cosmetic
  subset for pre-login theming), POST/DELETE /api/ui/background (upload with
  Content-Length pre-check + 5MB cap + magic-number validation), and unauth
  GET /ui-asset/background (serves the uploaded bytes with sniffed mime +
  nosniff). SPA fallback excludes /ui-asset/.
- webui: `ui` API-client namespace + mirror types (no UI wiring yet).

Server-managed background fields (hasImage/imageMime/imageVersion) are taken
from the trusted source per path — the file on load, the on-disk config on
save — so a client save can never forge them, and a wallpaper survives a
restart. Verified across 3 adversarial review rounds.
2026-06-13 01:15:00 +08:00
DrSmoothl
043ce779e6 fix(onebot): ignore close events from stale ws-client sockets (#97)
A hot reload that changes the binding signature (url / role / accessToken
/ reconnectIntervalMs) drives `await this.close()` then `await this.open()`
back-to-back. `WsClientAdapter.close()` is synchronous and `WebSocket.close()`
just schedules the close frame, so the OLD socket's `'close'` event fires
AFTER the new socket has already been assigned to `this.socket`.

The close handler did not check the event's origin, so it would null out
`this.socket`, drop `connected`, and schedule an unwanted reconnect against
the freshly-opened connection. Against a single-connection backend that
kicks duplicates this snowballed into a reconnect storm where the bot and
the backend repeatedly kicked each other off; against a permissive backend
it still left the new connection in a degraded state (events couldn't be
sent until the bogus reconnect rebuilt the socket).

Add a one-line identity guard at the top of the close handler — when the
event arrives from a socket that is no longer the current one, do nothing.
The explicitlyClosed / isEnabled checks are kept as the second line of
defence for the normal (current-socket) close path.

Add three regression tests under tests/ws-client-stale-close.test.ts that
mock `@snowluma/websocket` (same approach as adapter-reload-state-machine.
test.ts, which avoids the native addon dependency): the reload race
scenario from the issue, a real-current-socket close that MUST still drive
reconnect, and a close() race against an in-flight close event.
2026-06-12 21:55:32 +08:00
DrSmoothl
e9ae2ec751 feat(log): show ARK card title in JSON segment preview (#96)
The JSON segment preview was a fixed "[JSON]" placeholder, hiding both
real card titles and QQ's server-side fallback prompts (e.g. cardId
-896954183 "当前QQ版本不支持此应用,请升级", which is what #96 reported
seeing). Best-effort extract a title from the common ARK fields —
meta.{detail_1,detail,news,mannounce,music,video}.title, single-section
meta, then root.prompt / root.desc — and render as "[卡片:...]"; fall
back to "[JSON]" on parse failure or an unrecognised schema. Title is
truncated at 30 chars so a long prompt cannot blow up the log line.

OneBot segment shape is unchanged: downstream consumers still get the
full payload at data.data; this is purely a log-preview readability fix.
The helper is pure best-effort and never throws — every failure path
falls through to the existing "[JSON]" output.
2026-06-11 20:47:54 +08:00
snowluma-bot[bot]
69195ced93 Merge pull request #95 from SnowLuma/dev
chore: promote dev → main (a3a3671)
2026-06-11 08:42:47 +00:00
DrSmoothl
a3a36718d6 chore(release): v1.9.9 2026-06-11 16:42:23 +08:00
游手好闲的言柒
d2a67cb560 fix(onebot): add canonical fields to file segment and fix log rendering (#94)
* fix(onebot): support inline file url/path in send_group/private_msg

* test(onebot): update file segment parser test for inline url/path support

* fix(onebot): add canonical fields to file segment and fix log rendering
2026-06-11 15:40:47 +08:00
dependabot[bot]
d804a3b2e0 build(deps-dev): bump hono from 4.12.18 to 4.12.21 (#91)
Bumps [hono](https://github.com/honojs/hono) from 4.12.18 to 4.12.21.
- [Release notes](https://github.com/honojs/hono/releases)
- [Commits](https://github.com/honojs/hono/compare/v4.12.18...v4.12.21)

---
updated-dependencies:
- dependency-name: hono
  dependency-version: 4.12.21
  dependency-type: direct:development
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: snowluma-bot[bot] <283088347+snowluma-bot[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-06-09 17:04:41 +08:00
DrSmoothl
14e02bce3c fix(events): keep member role cache in sync on group admin change
get_group_member_info serves straight from the in-memory member cache
on its default no_cache=false path — a deliberate choice, since clients
like OlivaDice/MaiBot query it once per inbound message and a per-call
OIDB refetch trips Tencent risk-control. But the group-admin push
decoder only emitted the notice and never updated the cached role, so a
member promoted to admin kept reading back as `member` and permission
gates rejected their commands. Patch the cached role in the decoder on
set/unset, only touching members we already know and never downgrading
the owner.

Also fix promote/demote misdetection: proton materializes an absent
embedded-message field as an empty `{}` rather than undefined, so the
old `extraEnable !== undefined` test was always true — every demote was
reported as a promotion with a fallback userUin. Key off whichever
sub-message actually carries an adminUid instead.

Fixes #93
2026-06-09 16:30:10 +08:00
snowluma-bot[bot]
d2c56d565b Merge pull request #92 from SnowLuma/dev
chore: promote dev → main (d508814)
2026-06-09 06:23:12 +00:00
DrSmoothl
d508814dfa chore(release): v1.9.8 2026-06-09 14:22:43 +08:00
snowluma-bot[bot]
ac049e5cc1 chore(native): replace native artifacts (native-886e60a) (#90)
Source: SnowLuma/nnphook@886e60a271
Build:  https://github.com/SnowLuma/SnowLumaNative/releases/tag/native-886e60a

Co-authored-by: snowluma-bot[bot] <283088347+snowluma-bot[bot]@users.noreply.github.com>
2026-06-08 00:13:38 +08:00
snowluma-bot[bot]
cc27cd1f43 Merge pull request #89 from SnowLuma/dev
chore: promote dev → main (515bac4)
2026-06-07 14:30:05 +00:00
DrSmoothl
515bac4b3c chore(release): v1.9.7 2026-06-07 22:29:37 +08:00
DrSmoothl
6a2fd9e8f3 fix(bridge): don't crash the daemon when the hook pipe closes mid-send
When the control pipe drops while a send() is awaiting its ack,
rejectControlPending() rejects both the ack and the reply deferreds. The
reply is only awaited after the ack, so an ack-first rejection leaves the
reply promise rejected with NO awaiter — an unhandled rejection that, under
Node's default policy, kills the process. In Docker supervisor restarts it
(every session drops for ~1s); on a bare Windows run it just dies, surfacing
as "connection pipe closed" with the bot offline after hours of uptime.

Attach a no-op .catch() to each deferred at creation so a rejection can never
go unhandled (the real await still observes the value/rejection). Add a
regression test that drops the pipe mid-send and asserts no unhandled
rejection escapes — it fails without the guard.

Also install last-resort process guards (unhandledRejection / uncaughtException)
in the app entry: log and keep serving instead of exiting, so any other stray
rejection cannot take the daemon down and its stack is captured. The bridge's
watcher reconnects the dropped pipe on the next tick.
2026-06-07 22:15:07 +08:00
snowluma-bot[bot]
40c65c87bd Merge pull request #88 from SnowLuma/dev
chore: promote dev → main (174150c)
2026-06-07 13:20:48 +00:00
墨梓柒
ac39d04170 Merge branch 'main' into dev 2026-06-07 21:20:39 +08:00
DrSmoothl
174150c5e1 chore(release): v1.9.6 2026-06-07 21:19:00 +08:00
DrSmoothl
56dc934106 feat(webui): notify when a newer release is available
Advisory, read-only update check: the core polls GitHub's latest stable release, compares it against the running build, and surfaces a notice in the sidebar footer plus a detailed card (changelog + download link + platform-matched asset hint) in Settings → About.

SnowLuma never downloads or applies anything itself — cross-platform self-update is a minefield (Windows locks loaded .node/.dll, Docker bakes the app into image layers, bare installs have no supervisor), so the user downloads and applies manually.

The backend caches results for 6h to stay under GitHub's unauthenticated rate limit, degrades silently on failure, and can be disabled via SNOWLUMA_UPDATE_CHECK=0.
2026-06-05 16:08:38 +08:00
DrSmoothl
28db1d1079 fix(onebot): distinguish group disband from kick_me (#87)
group_decrease collapsed GroupChange.decreaseType into a single isKick boolean, so a group disband (decreaseType 129) was indistinguishable from the bot being kicked — both surfaced as kick_me.

Preserve the protocol reason as a leaveType discriminator (leave | kick | disband) on GroupMemberLeave: decreaseType 129 -> disband, 0/130 -> leave, otherwise kick. The OneBot converter emits disband, or splits kick into kick/kick_me by selfId as before. leave/kick/kick_me are unchanged.
2026-06-05 11:49:14 +08:00
DrSmoothl
966855469d ci: run the full test suite on pull requests
The repo had no PR test gate, so broken tests landed on dev unnoticed. Add a
pull_request workflow that runs `pnpm -r --no-bail --if-present test` across all
packages on ubuntu-latest (pnpm 10.28.0, Node 22), with per-PR concurrency.
2026-06-04 23:36:33 +08:00
DrSmoothl
9374b8ac64 fix(protocol): invokeOidb rejects on packet send failure (success=false)
invokeOidb only threw on success=false when an OIDB errorCode was set (the
block added in #69); a send failure with no errorCode silently resolved with an
undecoded result. Surface it — throw errorMessage || 'packet send failed',
matching runOidb and the oidb-service tests that were already red on dev.
2026-06-04 23:36:22 +08:00
ikun两年半
34ea2ce438 refactor(webui): 移除冗余的手动保存按钮喵,通用设置改为 debounce 自动保存喵 (#83)
* refactor(webui): 移除冗余的手动保存按钮喵,通用设置改为 debounce 自动保存喵

* fix(webui): 修复保存按钮状态喵,允许在自动保存时手动触发喵
2026-06-04 18:03:17 +08:00
墨梓柒
9dedcf93a8 Dev (#82)
* test(sdk): remove obsolete actions-sync guard

c49ae1c removed the SDK's hardcoded action-name list (src/actions.ts / SNOWLUMA_ACTIONS) and updated exports, but left the test that guarded it. The test imports SNOWLUMA_ACTIONS from ../src -- now undefined ("not iterable") -- and its registerAction('...') enumeration of onebot is itself stale after the declarative action-kit migration. Nothing else references SNOWLUMA_ACTIONS; the list it kept in sync no longer exists, so the guard is dead. Removing it makes the sdk suite green (16 tests).

* fix(mcp): add repository metadata so the provenance publish validates

npm publish --provenance rejected @snowluma/mcp@1.9.5 with E422 because package.json had no repository.url to match the GitHub repo asserted in the provenance statement. Add repository/homepage/bugs (mirroring @snowluma/sdk and @snowluma/ui, directory packages/mcp) and refresh the now-inaccurate 'read-only' description. 1.9.5 was never successfully published, so re-running the publish workflow will ship it.
2026-06-03 22:19:31 +08:00
DrSmoothl
0cc7ef2f30 fix(mcp): add repository metadata so the provenance publish validates
npm publish --provenance rejected @snowluma/mcp@1.9.5 with E422 because package.json had no repository.url to match the GitHub repo asserted in the provenance statement. Add repository/homepage/bugs (mirroring @snowluma/sdk and @snowluma/ui, directory packages/mcp) and refresh the now-inaccurate 'read-only' description. 1.9.5 was never successfully published, so re-running the publish workflow will ship it.
2026-06-03 22:17:58 +08:00
DrSmoothl
d2097f77c8 test(sdk): remove obsolete actions-sync guard
c49ae1c removed the SDK's hardcoded action-name list (src/actions.ts / SNOWLUMA_ACTIONS) and updated exports, but left the test that guarded it. The test imports SNOWLUMA_ACTIONS from ../src -- now undefined ("not iterable") -- and its registerAction('...') enumeration of onebot is itself stale after the declarative action-kit migration. Nothing else references SNOWLUMA_ACTIONS; the list it kept in sync no longer exists, so the guard is dead. Removing it makes the sdk suite green (16 tests).
2026-06-03 22:17:58 +08:00
snowluma-bot[bot]
46cbd29956 Merge pull request #81 from SnowLuma/dev
chore: promote dev → main (4fcaba2)
2026-06-03 13:56:10 +00:00
DrSmoothl
4fcaba2f3e chore(release): v1.9.5 2026-06-03 21:55:37 +08:00
DrSmoothl
4427ecd569 docs(mcp): document execution mode (modes, env, read/write safety)
Covers the docs vs execution split, the four SNOWLUMA_MCP_* env vars, the query_action / invoke_action tools, read/write-mode example client configs, and the per-action safety model (default-write classification, the enforced mode gate, unknown-action rejection, envelope passthrough, and the readOnly/destructive annotations).
2026-06-03 21:55:05 +08:00
DrSmoothl
6d92a28e2b feat(mcp): execution mode — query/invoke OneBot actions with a read/write safety gate
@snowluma/mcp gains execution alongside the read-only catalog: when SNOWLUMA_MCP_ENDPOINT is set it exposes query_action (read-only actions, readOnlyHint) and, in write mode, invoke_action (any known action, destructiveHint), proxied to a running OneBot instance over HTTP. Without an endpoint it degrades to docs-only. SNOWLUMA_MCP_MODE (docs|read|write) gates tool visibility AND is re-checked in execute(), so an unlisted tool cannot be called; unknown/legacy actions are non-invokable.

Read vs write is classified precisely at the source: defineAction/preset gain readOnly (default false = write, the safe default), flowed through describe() into the generated catalog snapshot. 58 actions are marked read-only by what their run() actually does -- name-traps like get_ai_record (publishes to the group), request_decrypt_key (returns a DB key), and download_file (arbitrary URL + disk write) stay writes.

The HTTP call is a ~20-line fetch bridge rather than @snowluma/sdk: the SDK's published dist is bundler-only ESM (extensionless imports) that native node cannot load, and the bin stays a plain tsc build.

onebot 332 tests pass (readOnly is metadata-only, no behavior change); mcp gains 21 tests for mode gating / read-write routing / envelope passthrough / error mapping. Full workspace typecheck clean; native node smoke verified.
2026-06-03 21:53:02 +08:00
DrSmoothl
18f7d847ac refactor(onebot): lift the network adapter reload state machine into the base class
The four NetworkAdapters each carried a byte-identical reload() state machine (sigChanged/wasEnabled -> Reopened/Closed/Opened/Normal). Lift it into IOneBotNetworkAdapter as a template method; per-adapter variation is now expressed via three hooks: bindingSignature(), willEnable() (default enabled!==false; clients add && !!url), and onConfigReplaced() (post-swap side effects).

Also delete four redundant 'override get isActive()' (identical to the base getter), lift the duplicated uin-logger setup into the base ctor, and drop http-post's now-redundant signature_ cache.

NetworkReloadType is a test-observability seam -- the sole production caller (instance.applyConfigDiff) discards it -- so a new base-level test exercises all transitions directly. Behaviour-preserving: +94/-157 in src, full workspace typecheck clean, 332 onebot tests pass.
2026-06-03 20:53:36 +08:00
游手好闲的言柒
d3092a1806 fix(onebot): support inline file url/path in send_group/private_msg (#80)
file 段现接受 file/url/path(无需先 upload_group_file/upload_private_file);群走 groupFile.upload()、私聊走 uploadPrivate()(内部已 publish/sendC2c),file_id 老路径不变。含 parser 与群/私聊文件发送测试。
2026-06-03 20:00:58 +08:00
DrSmoothl
69c8960ea9 feat(mcp): @snowluma/mcp — read-only MCP server for the OneBot action catalog
A new published package that exposes every OneBot action's docs + a ready-to-use
JSON Schema to LLM clients over stdio. Tools: list_actions / get_action /
search_actions / list_categories, plus the whole catalog as a resource.

The catalog is a build-time snapshot generated from @snowluma/onebot's live
action specs (collectActionDocs()) — so it auto-tracks action add/remove and the
published package carries zero runtime dependency on the private onebot package.

action-kit enrichment (the data source):
- Field.toJsonSchema() per coercer (uint→integer/minimum:1, messageId→integer/
  not-const-0, int→min/max, string→minLength/maxLength, array→items, enum→enum).
- describe() composes a per-action inputSchema; ActionDoc gains inputSchema +
  category. action-docs.ts tags each doc with its domain category.

Wiring: onebot exports ./action-kit + ./action-docs; root build:all includes mcp;
mcp-npm-publish.yml mirrors the sdk/ui publish workflows (triggers on changes
under packages/mcp/** or packages/onebot/**, since the catalog derives from it).

onebot typecheck + 318 tests green; mcp typecheck/build/smoke green; the 142
registered OneBot action names are unchanged.
2026-06-02 22:45:30 +08:00
DrSmoothl
fc21d87a9b feat(onebot): fetch_ptt_text via async 0x210/61 result push (#79)
Live testing showed the voice-to-text text is delivered by an async push
(Event 0x210 subType 61), not the request response — so the previous
poll-by-resend never got it. Captured a real push and decoded its protobuf:
outer { f1, f2:item }; the item echoes the request msgId at field 1 (the
correlation key) and the recognised text at field 8.

- proto-defs: PttTransPush / PttTransPushItem (live-verified).
- protocol: Event0x210SubType.PttTransResult = 61 + decoder → internal
  `ptt_trans_result` event { msgId, text } (replaces the temp hex dump).
- core: translatePttToText now sends ONE trigger and returns the inline text
  only if present (already-transcribed); empty = pending.
- onebot: ptt-trans-waiter (keyed by selfUin:msgId), event-pipeline subscribes
  `ptt_trans_result` to resolve it; fetch_ptt_text registers the waiter,
  fires the trigger, and awaits the push (20s timeout).

Decoded one real push as text "12311123。" end to end.
2026-06-02 22:01:07 +08:00
DrSmoothl
e036e70acc chore(protocol): temp-dump 0x210 subType-61 ptt-trans push body (#79)
Live testing showed the voice-to-text text is delivered via an async push
Event 0x210 subType 61 (0x3D), not the sync pttTrans.TransC2CPttReq response
(which is a fixed ~137B ack). That push has no static sys_msg_0x210_0x3d
handler — its protobuf is registered dynamically by the ptt-trans subsystem,
so RE through the std::function callback chain is impractical.

Dump the raw subType-61 body (fromUin + len + hex) once so the wire format
can be decoded from ground truth, then implement the real decoder +
request/await correlation. Temporary — to be replaced by the actual decoder.
2026-06-02 21:28:44 +08:00
DrSmoothl
92cfaf24b8 feat(log): trace the inbound receive chain (symmetric to outbound)
Sending got full-chain trace via the api-handler chokepoint; receiving had
none. Wrap convertAndDispatch — the single path every inbound message/notice
takes (decode → convert → dispatch) — as the receive-side mirror:

- When trace is live, run the chain inside a request id so the whole receive
  (incl. any rkey-fetch packets the conversion triggers) is correlated under
  one [req#N]; otherwise skip the wrap entirely (zero overhead).
- trace the raw inbound event on entry (deep render) and the converted
  post_type + elapsed on exit (or "dropped").

Reuses the existing trace/ALS/renderParamsVerbose machinery; no new mechanism.
2026-06-02 21:15:12 +08:00
DrSmoothl
15e4e261c5 feat(log): memory-only trace level + request correlation + chokepoint tracing
Debugging from user-supplied logs was impossible: a successful action left
one terse, over-summarized debug line and nothing about what it sent QQ or
what QQ returned. Add full-chain tracing that stays off disk so it scales to
hundreds of groups.

common:
- New `trace` level (below debug). Never written to file — it lives only in
  an in-memory ring + the WebUI stream, so the high-volume full chain costs no
  disk. `emit` early-returns for trace before format/render (and before any
  lazy producer) when trace isn't active → ~free at the default level.
- Dedicated O(1) circular ring for trace (default 5000, SNOWLUMA_TRACE_BUFFER),
  separate from the normal 1000-entry buffer (also switched off array .shift);
  getRecentLogs merges both by id.
- request-context.ts: AsyncLocalStorage request id. The logger auto-stamps
  `[req#N]` on every line in a request's async chain — across packages, zero
  signature threading — and records it on the entry.
- log-summary.renderParamsVerbose: deep render of params (nested structure,
  per-string cap, total budget, token/password/secret redaction).

chokepoints (auto-cover every action without touching 100+ handlers):
- onebot api-handler: wrap each action in a request id (only when trace is
  live); trace the full params on entry and status+elapsed on exit; the terse
  debug breadcrumb still persists to file, failures still warn.
- core bridge.sendRawPacket: trace on success (cmd, sizes, elapsed); warn on
  errorCode!=0 / no response (cmd, code, message) so disk keeps real problems.
- protocol highway: fold the bare console.log lines into the logger (trace).

webui: trace as the lowest filterable level; render the `[req#N]` tag and let
search match it. Server needs no change — LOG_LEVELS, getRecentLogs and the
SSE stream carry it through.
2026-06-02 21:01:19 +08:00
DrSmoothl
7336352cd3 feat(onebot): voice-to-text action fetch_ptt_text (#79)
Adds NapCat-compatible voice-to-text. New `fetch_ptt_text` action (aliases
`get_ptt_text` / `get_record_text`) takes a message_id, resolves the cached
`record` fingerprint (uuid + md5 + duration/size/format), drives QQ's native
`pttTrans.TransC2CPttReq` / `pttTrans.TransGroupPttReq`, and returns { text }.

The response carries the text inline once transcription is done; an empty
text means the server is still transcribing (there is no dedicated push
command — confirmed via RE), so the bridge re-sends with a short backoff
until the text lands, mirroring NapCat's fire-then-re-read shape.

Layers:
- proto-defs/ptt-trans: PttTransReq/Resp + per-scene items.
- core ExtrasApi.translatePttToText: encode -> sendRawPacket -> decode -> poll.
- onebot media-actions.fetchPttText + api-handler/instance-context wiring.
- onebot extended: register the action + aliases.

The commands + request/response field tags were reverse-engineered from
QQ-NT wrapper.node (im_core/msg/ptt/ptt_trans_worker.cc). The numeric tags
are solid; the length-delimited fields (uuid/md5) and the response text tag
are RE-derived and want one live capture to confirm before relying on them.
2026-06-02 20:47:06 +08:00
DrSmoothl
9b92f3825d refactor(onebot): declarative action-kit for param coercion + validation
Introduce packages/onebot/src/action-kit.ts — a zero-dependency,
type-inferring declarative layer for OneBot action params. Each action
declares its param contract (f.* coercers + optional cross-field rules)
and a `run` handler that receives typed, already-validated params.
Validation failures now return BAD_REQUEST naming the offending field
instead of falling through to ApiHandler's INTERNAL_ERROR catch.

- 141/142 actions migrated to defineAction/groupAction/groupUserAction
  across info/message/friend/group-*/request/extended; only
  .handle_quick_operation stays legacy (it needs the ApiHandler instance,
  which run() does not receive).
- f.messageId() distinguishes signed/non-zero message ids from positive
  group/user ids (f.uint()); int({min:0}).default(1800) fixes duration=0
  (unmute), which the old `|| 1800` silently swallowed.
- run(p, ctx, raw) exposes the raw params as an escape hatch for the
  irregular tail (alias-key fallbacks, arbitrary objects).
- action-docs.ts renders self-generated API docs from describe().
- ApiHandler dispatch / try-catch / response-wrapping unchanged (narrow seam).

Registered action name set is byte-identical before/after (142, verified
by runtime enumeration). Typecheck clean; onebot suite green (the
pre-existing websocket native-addon test failure is unrelated).
2026-06-02 15:21:46 +08:00
snowluma-bot[bot]
74c727b9e3 Merge pull request #77 from SnowLuma/dev
chore: promote dev → main (a1f372b)
2026-06-01 08:22:22 +00:00
DrSmoothl
a1f372bc9d chore(release): v1.9.4 2026-06-01 16:21:54 +08:00
DrSmoothl
b23607d51d feat(webui): add About tab to settings with Star CTA
New "关于" mini-tab in the settings page showcasing SnowLuma: logo +
name + version badge (__APP_VERSION__) + tagline, a short blurb, and a
prominent GitHub Star call-to-action linking to SnowLuma/SnowLuma, plus
secondary links (repo / releases / issues).

Static CTA — no GitHub API fetch, so no rate-limit / loading state.
Reuses /logo.png (same asset as sidebar/login) and the existing Card +
motion + accent-color design language; responsive centered layout.
2026-06-01 16:07:49 +08:00
墨梓柒
a51bf60d9a Merge pull request #76 from tt-P607/fix/highway-multi-chunk-keepalive
fix(protocol): one TCP connection per highway chunk
2026-06-01 15:04:05 +08:00
DrSmoothl
003e8c2deb feat(onebot): built-in #sl status command (toggleable, non-plugin)
A hardcoded `#sl` status command — deliberately NOT a plugin system.
Matched at the instance dispatch choke point: a pure-text message equal
to `#sl` (exact, trimmed, case-insensitive — no startsWith) replies with
SnowLuma version / platform / uptime in the same conversation.

- Anyone can trigger; the per-UIN `statusCommand.enabled` toggle is the
  only gate (default on). Per-conversation cooldown (default 5s,
  configurable) prevents flood/风控 from repeated triggers.
- `swallow` (default false / pass-through): when set, a matched `#sl` is
  not forwarded to downstream adapters — still cached, logged, replied.
- Config on OneBotConfig.statusCommand (per-UIN): defaulted + clamped in
  config.ts, mirrored/normalized in the WebUI; edits hot-reload via the
  shared instance context.
- WebUI: a "内置命令" section in the 通用设置 tab (enable / swallow /
  cooldown). Node enable toggle extracted into a shared ui/ToggleSwitch.

Pure matcher / cooldown / uptime / text helpers live in
modules/status-command with unit tests; config defaults + clamp covered.
2026-06-01 14:58:13 +08:00
tt-P607
118bcbe83c fix(protocol): one TCP connection per highway chunk
Highway 上传超过 1 MiB 的载荷(多 chunk 场景)会失败,OneBot 侧表现
为 retcode=1200 / `connection closed before response`。

根因:`uploadHighwayHttp` 用同一个 TCP socket,靠 HTTP keep-alive 把
每个 1 MiB chunk 依次 POST 出去。但 QQ highway 的边缘节点(以及链
路上的代理/NAT)经常在第一次响应之后立刻 FIN 关闭连接,第二个 chunk
的 POST 写到一个已被对端 close 的 socket 上,`readHttpResponseBody`
立刻收到 `close` 事件并抛出 `connection closed before response`。

为什么之前看起来像网络问题:≤1 MiB 的载荷(文本、PTT、小图)只发一
次 POST,永远不会触发;但凡跨过 `HIGHWAY_BLOCK_SIZE = 1 MiB`,第二
个 chunk 路径必然失败。改 Clash MTU、关 TUN、加直连规则都没用,因
为问题不在网络层。

改动:
- `uploadHighwayHttp`:每个 chunk 都新开一个 TCP 连接,`finally` 里
  `destroy()`。建连开销相对 1 MiB chunk 的传输时间可以忽略,行为也
  和 NapCat / Lagrange 在大文件上传时的连接生命周期一致。
- `readHttpResponseBody`:报错信息带上 `received=NB, headerSeen=
  true|false`,方便后续区分 “连接刚握手就被关” 和 “响应读到一半被
  截断” 两种情况。

测试:`packages/core/tests/highway/highway-client.test.ts` 三个用例
(0.5 MiB 单 chunk / 1.5 MiB 两 chunk —— 即本次 bug 复现 / 2.5 MiB
三 chunk),断言 `net.createConnection` 被调用的次数等于
`ceil(size / HIGHWAY_BLOCK_SIZE)`,并且每个用过的 socket 在下一次
建连之前都被 destroy。

线上验证:之前每次发 1 MB 以上图片必出 retcode=1200 的账号,打补丁
后通过 OneBot HTTP 已能正常发出图片。
2026-06-01 14:35:57 +08:00
DrSmoothl
0d63bf7415 fix(onebot): sign forward-msg media + pick image rkey by appid (#74)
/get_forward_msg returned raw, rkey-less image/media URLs because
getForwardMessage converted forward nodes WITHOUT the URL resolvers the
normal receive path (to-message.ts) uses. Wire imageUrlResolver +
mediaUrlResolver into it so forwarded images/voice/video get signed
download URLs — exactly issue #74 (image url 缺少 rkey).

Also derive the image rkey scene from the appid baked into the URL
(1406 -> private, 1407 -> group) instead of the carrying message's
group/private context, falling back to isGroup only when the URL has no
recognised appid. A c2c image forwarded into a group keeps its original
c2c appid, so the old isGroup-based pick signed it with the group rkey ->
`invalid rkey` on download. Mirrors NapCat's getImageUrlFromParsedUrl;
Lagrange/NapCat both reuse one unified converter so this never drifts.

Fix the self-contradictory `c2c images` rkey test (its fixture used the
group appid 1407) and add cross-tests asserting appid outranks isGroup
both ways, plus the no-appid fallback.
2026-05-31 23:50:08 +08:00
DrSmoothl
f9252fb26d fix(bridge): type Ptlogin probe + de-magic process threshold (PR #73 follow-up)
PR #73's login-state probe shipped with issues:
- `fetchPtlogin` returned `Promise<any[]>`, tripping the repo's
  `@typescript-eslint/no-explicit-any` (error) and breaking `pnpm lint`.
  Modelled the read fields as a `PtloginUin` interface and cast the parsed
  JSONP to it.
- `tryPtloginMethod` had a dead `if` whose two branches both returned
  'fallback'; collapsed to a single return with a comment.
- The `< 6` QQ-process-count heuristic was a bare magic number (one copy
  annotated only with "13579 5个端口全部用光"). Extracted to
  `LOGGED_OUT_PROCESS_COUNT_MAX` with an explanation and reused in all three
  sites (incl. the error fallback).

Behaviour-preserving: the probing logic (Ptlogin parse, deep-link fallback,
PID port discovery) is unchanged — only typing and the magic constant.
2026-05-31 22:33:22 +08:00
墨梓柒
e821080ca8 Merge pull request #73 from H3CoF6/fix/detect
New implement for QQ status detection
2026-05-31 15:43:19 +08:00
H3CoF6
b3749560c8 New implement for QQ status detection 2026-05-31 04:51:54 +08:00
DrSmoothl
c3803e4ba8 feat(proto): implement deflated payload for JSON and XML elements in message builder 2026-05-30 22:52:15 +08:00
snowluma-bot[bot]
f2840c7074 Merge pull request #71 from SnowLuma/dev
chore: promote dev → main (ad081e2)
2026-05-30 12:54:09 +00:00
DrSmoothl
ad081e2149 chore(release): v1.9.3 2026-05-30 20:53:45 +08:00
DrSmoothl
0e4b881f76 feat(webui): add live connection status for OneBot adapters in dashboard 2026-05-30 18:02:01 +08:00
DrSmoothl
90f26ca4f4 fix(proto): emit state=0 on whole-ban unmute via new pb_optional marker
set_group_whole_ban false (unmute) failed with `OIDB error 1007` while
enabling worked (issue #70). OIDB (0x89A, 0) is shared by several commands
(SetSearch / SetAddOption / mute-all) disambiguated by body shape. Unmute
sends muteState.state=0, but proton omits zero scalars (proto3), leaving an
empty `muteState` the server can't classify. Enable sends 0xFFFFFFFF, which
is non-zero and survives — hence the asymmetry.

Add a `pb_optional<N, T>` marker (proto3 explicit presence): a scalar so
marked serialises even at its zero/default value. It is opt-in per field via
a NEW `explicitPresence` flag set ONLY by this marker — never reused from the
TS-`?`-derived `isOptional` (true for nearly every field). The encoder routes
explicit-presence scalars to a dedicated block; every `pb<>` / `pb_repeated<>`
field takes the untouched branches, so existing wire output is byte-identical
(proton's 99 existing tests, incl. byte-level round-trips, stay green).

Mark OidbMuteAllState.state `pb_optional<17, uint_32>` so unmute now puts
field 17 (=0) on the wire. New tests: proton pb_optional encode/round-trip
(incl. that sibling pb<> fields still omit zero), and a byte-level assertion
that mute-all unmute carries the state field.

Note: proton ships as a built Vite plugin (dist, gitignored); rebuild it
(`pnpm --filter @snowluma/proton build`) for the change to reach consumers.
2026-05-30 17:55:23 +08:00
DrSmoothl
c4413dabb5 fix(proto): correct 0x8FC body/targetName field tags (set_group_card)
set_group_card always failed with `OIDB error 1007 on 0x8fc_3` (issue #70).
The 0x8FC request protos put the body wrapper at tag 2 and the member card
name at tag 2, but QQ-NT expects body at tag 3 and targetName at tag 8, so
the server found neither and rejected the request.

Cross-checked byte-for-byte against two working references:
  - Lagrange.Core OidbSvcTrpcTcp0x8FC: Body=ProtoMember(3), TargetName=8
  - NapCat Oidb.0x8FC_2: body=ProtoField(3), targetName=8

Fixes OidbRenameMember (0x8FC_3 set card) and the same latent bug in
OidbSpecialTitle (0x8FC_2 set special title), whose body was also at tag 2.
Send-only protos (empty deserialize); existing tests assert the command
name, not field tags, so they're unaffected.
2026-05-30 17:29:17 +08:00
DrSmoothl
71be3ae2e1 feat(webui): split overview into a processes page + mobile/ultrawide pass
The homepage was doing double duty — monitoring + injection control. Split it:

- New /processes page ("进程注入", sidebar #2) owns the QQ-process control
  surface (load / unload / refresh / probe-login + its dialogs). Overview is
  now a read-only dashboard: stats, host metrics, online accounts, plus a
  read-only injection-summary tile (online / loadable, links to /processes)
  and a first-run CTA that points at /processes while nothing is online.
  Route + AppPath + nav item wired; state/polling stay layout-owned.

Responsive + a11y pass:
- Mobile sidebar Sheet gets an sr-only title + description, fixing the Radix
  "DialogContent requires a DialogTitle" accessibility error.
- Log rows stack on phones (meta line + full-width message) instead of a
  ~40px column that broke every few chars; time parses defensively so a
  non-ISO value never renders "Invalid Date".
- Process cards stack on phones (info row + actions row) so name / PID / path
  stop collapsing to "Q.."; the status badge no longer wraps.
- Config tab strip scrolls horizontally on phones instead of wrapping to
  three rows; account strip defaults collapsed ≤lg; header buttons wrap.
- Dialogs keep a 1rem gutter on tiny screens via w-[calc(100vw-2rem)].
- Content widens to 1600px on ≥2xl; account/process grids gain a column at
  2xl so >1700px screens aren't mostly empty gutter.
2026-05-30 16:56:34 +08:00
手瓜一十雪
3cfac51811 Add SVG logo and update README
Add a new animated SVG logo at .github/logo.svg and embed it in README.md. Update the README content: refresh badges, simplify and translate the project intro and feature list into Chinese, add concise quickstart steps, adjust links (Releases → 发布版, RoadMap), and replace long/duplicated sections with a shorter overview and contributor badge. Overall this cleans up and modernizes the README and adds a branded logo for the project.
2026-05-30 16:06:29 +08:00
DrSmoothl
76c6ebc700 feat(webui): settings tabs, password dialog, instant node save, error pages
Five WebUI changes:

1. Settings page rebuilt around mini tabs (外观 / 数据刷新 / 账号安全)
   instead of three stacked cards; content and behaviour unchanged.

2. "修改访问密码" now opens an independent ChangePasswordDialog modal
   rather than swapping the whole page for the forced-change screen. The
   form is extracted to a shared ChangePasswordForm used by both the modal
   and the forced full-screen ChangePasswordPage — behaviour identical.

3. Node config: creating / editing / deleting / enable-toggling an
   HTTP/WS endpoint now persists immediately — clicking 保存 in the editor
   dialog IS the save. Previously it only marked the config dirty until you
   also hit the top-right 保存, which silently cost many users their token
   edits. `save()` takes an explicit config so it persists the freshly
   computed value, not the stale closed-over state. The general-settings
   tab keeps its explicit top-right save.

4. Forced first-time change-password no longer renders an old-password
   field: it carries the password the user just logged in with. Browsers
   (Edge/Chrome) were autofilling that field on upgrade, so users thought
   the old password was pre-filled correctly and could never save. A
   returning already-authed session (no fresh login) still shows the field.

5. Added default error + 404 screens (status-screens.tsx), wired into the
   TanStack router via defaultErrorComponent / defaultNotFoundComponent.
2026-05-30 13:34:41 +08:00
DrSmoothl
74b6fe97e5 build(core): externalize node:sqlite instead of SSR-bundling
Addresses MliKiowa's review on PR #68 ("单独排除 sqlite 就行了"). That PR
fixed the `DatabaseSync is not a constructor` crash by switching the core
bundle to SSR mode (build.ssr + ssr.noExternal + target node22 + a
catch-all isNodeBuiltin external fn). The root cause was narrower: on
Node 22.x `node:sqlite` is experimental and absent from `builtinModules`,
so the `nodeModules` sweep didn't externalize it and Vite swapped in a
browser shell. The SSR switch also self-inflicted the @hono/node-server
MODULE_NOT_FOUND it then had to paper over with noExternal — the original
config already bundled all non-builtin deps.

Revert vite.config.ts to the pre-PR state and just add 'node:sqlite'
(+ bare 'sqlite') to the external list. Verified: `SNOWLUMA_TARGET=linux-x64
vite build` succeeds and dist/index.mjs now carries a real
`import { DatabaseSync } from "node:sqlite"` rather than a shimmed shell.
2026-05-29 20:22:06 +08:00
DrSmoothl
4a0626f00b fix(onebot): re-sign image rkey on get_image / get_msg lookups
get_image and get_msg returned the URL baked into the message store when
the message first arrived. That URL's rkey expires, so a client fetching
it later (or re-querying after the original push) got
`{"retcode":-5503010,"retmsg":"invalid rkey"}`.

Re-sign at lookup time from the raw unsigned `imageUrl` the media store
already keeps alongside the signed `url` (plus `isGroup`): getImageInfo
now takes the image rkey resolver and mints a current rkey, and get_msg
walks its segment array refreshing each image URL through it. Both are
best-effort — a resolver miss/throw or a non-array message body falls
back to the stored URL untouched. Mirrors NapCat re-signing on every
getImageUrl call instead of handing back a stale baked URL.

The resolver is reused from converterCtx (no new rkeyCache wiring); a
cache-hit re-sign is a string concat, only an expired rkey awaits the
already-deduped/cooled-down/timeout-bounded refresh.
2026-05-29 20:14:21 +08:00
墨梓柒
ba19cee07d Merge pull request #68 from H3CoF6/Dev
Fix SSR bundle and node:sqlite resolution in Vite config
2026-05-29 20:14:11 +08:00
DrSmoothl
624959f099 fix(onebot): await a fresh rkey before signing media URLs
Image/video/record download URLs are signed at receive-time with an rkey
(OIDB 0x9067_202, TTL-bounded). RKeyCache resolved synchronously: on a
cache miss or inside the expiry skew it returned the URL *without* an
rkey and only kicked off a fire-and-forget refresh (plus a 30s cooldown).
So during the expire→refresh window — and whenever the OIDB hiccuped —
SnowLuma emitted unsigned URLs, which the CDN rejects with
`{"retcode":-5503010,"retmsg":"invalid rkey"}`. Intermittent by nature.

Mirror NapCat's getImageUrl (`if (isExpired()) await refreshRkey()`):
make resolveImageUrl/resolveMediaUrl async and block on one refresh when
the cache can't serve a still-valid rkey. The refresh coalesces
concurrent callers onto a single OIDB round-trip, backs off for 30s after
a failure, and is bounded by a 5s timeout so a stuck packet send never
wedges message conversion (it degrades to whatever the cache holds).

Widen ImageUrlResolver to `string | Promise<string>` and await it in
to-segment so the image path can resolve asynchronously like media.
2026-05-29 17:56:39 +08:00
DrSmoothl
0110b71dd3 fix(protocol): send browser UA + Referer retry on media downloads
loadBinarySource issued a header-less fetch(source) for remote media.
Anti-hotlink / anti-bot front-ends reset such requests, surfacing as
undici `TypeError: fetch failed` (not a clean 403) — so quoting a
command and sending an image/GIF whose source is a guarded URL bounced
with send_group_msg retcode 1200 "fetch failed".

Mirror NapCat's download path: send a browser User-Agent on every
request and retry once with a Referer pointing at the resource when the
first attempt is refused (network error or 403/4xx). Size-limit
rejections are tagged noRetry so an oversized body isn't re-downloaded.
Also route set_group_notice's image fetch through loadBinarySource so it
inherits the same hardening (plus http/file/base64 handling).
2026-05-29 17:37:10 +08:00
H3CoF6
00ca582f1a feat(protocol): implement OIDB 0xcde_2 (RequestDbKey) (#69) 2026-05-28 15:18:06 +08:00
H3CoF6
bf932477dd build(core): fix SSR bundle and node:sqlite resolution in Vite config 2026-05-28 02:02:29 +08:00
手瓜一十雪
f2b7ef0056 Switch from @snowluma/sqlite to node:sqlite (sync)
Remove the in-tree @snowluma/sqlite wrapper and vendored better-sqlite3 prebuilts; migrate consumers to node:sqlite's synchronous API. Replaced imports and types (Database/Statement -> DatabaseSync/StatementSync), updated PRAGMA calls to use exec, and adjusted code in onebot (media/message/reaction stores) and protocol (identity service). Vite config no longer bundles sqlite native binaries and references to the sqlite workspace were removed. Also delete the packages/sqlite package and its native prebuild artifacts, and add a couple of unrelated AST improvements in proton: use a module-level shared wrapper cache and add an inheritance cache to avoid repeated scans. Minor import reordering/cleanup applied where needed.
2026-05-27 20:02:40 +08:00
snowluma-bot[bot]
54c4641a0e Merge pull request #66 from SnowLuma/dev
chore: promote dev → main (5924346)
2026-05-24 10:02:15 +00:00
snowluma-bot[bot]
08b7ab7f15 Merge pull request #63 from SnowLuma/dev
chore: promote dev → main (ee0f159)
2026-05-21 09:50:31 +00:00
snowluma-bot[bot]
4a92dd71ad Merge pull request #62 from SnowLuma/dev
chore: promote dev → main (607a7b3)
2026-05-21 09:34:03 +00:00
snowluma-bot[bot]
1bd0cbc359 Merge pull request #57 from SnowLuma/dev
chore: promote dev → main (2de1ff4)
2026-05-20 06:21:32 +00:00
snowluma-bot[bot]
fe567caeec Merge pull request #50 from SnowLuma/dev
chore: promote dev → main (941e60d)
2026-05-18 07:04:16 +00:00
snowluma-bot[bot]
231d60411b Merge pull request #48 from SnowLuma/dev
chore: promote dev → main (b94775c)
2026-05-18 05:31:37 +00:00
snowluma-bot[bot]
bee1e67c60 Merge pull request #46 from SnowLuma/dev
chore: promote dev → main (c6f4d5c)
2026-05-17 16:11:03 +00:00
snowluma-bot[bot]
71b0bda8f4 Merge pull request #44 from SnowLuma/dev
chore: promote dev → main (90884df)
2026-05-17 11:29:18 +00:00
墨梓柒
133cfc0c0e Merge pull request #40 from SnowLuma/revert/pr-38-c2c-video-sceneType
Revert "fix(send): keep c2c video compatQMsgSceneType at 2 (#38)"
2026-05-16 16:44:38 +08:00
DrSmoothl
b959783ded Revert "fix(send): keep c2c video compatQMsgSceneType at 2 (#38)"
This reverts commit 463e0ffb5d.
2026-05-16 14:54:56 +08:00
时瑾
463e0ffb5d fix(send): keep c2c video compatQMsgSceneType at 2 (#38)
Commit 29f28d6 changed c2c video `compatQmsgSceneType` from 2 to 1
as a "symmetric asymmetry" cleanup, matching the image/ptt convention
where the field tracks the upload's sceneType (c2c=1, group=2). For
video this is wrong.

Image and ptt have *different* legacy compat elements per scene
(notOnlineImage vs customFace; ptt c2c vs group), so the server needs
to know which scene shape to emit. The legacy `videoFile` element
(packet element type 19) has no scene split — fromChatType /
toChatType live inside the element itself — so the QQ NT server
emits a single group-shaped compat payload regardless. NapCat
hardcodes `compatQMsgSceneType: 2` for *both* UploadGroupVideo and
UploadPrivateVideo for exactly this reason.

Setting it to 1 on c2c made the server emit a c2c-scene shaped
compat blob that older QQ clients failed to resolve, showing the
message as "视频已过期" on those receivers. Newer clients only read
the commonElem(48, 11) and displayed fine — which is why only "some
devices" saw the breakage.

Keep `commonElem.businessType = isGroup ? 21 : 11` untouched — that
piece of 29f28d6 is still correct and is what fixed PbSendMsg
result=79.
2026-05-16 14:22:49 +08:00
snowluma-bot[bot]
9d55e86b1c Merge pull request #37 from SnowLuma/dev
chore: promote dev → main (7da52bc)
2026-05-15 23:18:33 +08:00
snowluma-bot[bot]
07449788c6 Merge pull request #36 from SnowLuma/dev
chore: promote dev → main (85b59bc)
2026-05-15 01:48:08 +08:00
snowluma-bot[bot]
fe4af70562 Merge pull request #34 from SnowLuma/dev
chore: promote dev → main (564eec2)
2026-05-14 20:50:46 +08:00
snowluma-bot[bot]
545a732385 Merge pull request #30 from SnowLuma/dev
chore: promote dev → main (ada591b)
2026-05-13 16:55:55 +08:00
snowluma-bot[bot]
c2f22d8daf Merge pull request #29 from SnowLuma/dev
chore: promote dev → main (6abde40)
2026-05-13 16:23:42 +08:00
snowluma-bot[bot]
9216b54427 Merge pull request #28 from SnowLuma/dev
chore: promote dev → main (1b2dd83)
2026-05-12 22:06:52 +08:00
snowluma-bot[bot]
fd9a239241 Merge pull request #27 from SnowLuma/dev
chore: promote dev → main (8636222)
2026-05-11 15:32:46 +00:00
snowluma-bot[bot]
5a4028d5dc Merge pull request #25 from SnowLuma/dev
chore: promote dev → main (6f6ce11)
2026-05-10 10:17:23 +08:00
snowluma-bot[bot]
d02e7cc3ab Merge pull request #23 from SnowLuma/dev
chore: promote dev → main (bec23c4)
2026-05-10 01:32:20 +08:00
snowluma-bot[bot]
9938545788 Merge pull request #21 from SnowLuma/dev
chore: promote dev → main (a7b3809)
2026-05-09 19:40:04 +08:00
snowluma-bot[bot]
7149bc8689 Merge pull request #20 from SnowLuma/dev
chore: promote dev → main (c39b3f5)
2026-05-09 19:33:40 +08:00
snowluma-bot[bot]
9802128421 Merge pull request #19 from SnowLuma/dev
chore: promote dev → main (2af273b)
2026-05-09 16:40:37 +08:00
墨梓柒
a572d05c25 Merge pull request #18 from SnowLuma/dependabot/npm_and_yarn/hono-4.12.18
build(deps-dev): bump hono from 4.12.14 to 4.12.18
2026-05-09 16:03:21 +08:00
dependabot[bot]
cb06624d12 build(deps-dev): bump hono from 4.12.14 to 4.12.18
Bumps [hono](https://github.com/honojs/hono) from 4.12.14 to 4.12.18.
- [Release notes](https://github.com/honojs/hono/releases)
- [Commits](https://github.com/honojs/hono/compare/v4.12.14...v4.12.18)

---
updated-dependencies:
- dependency-name: hono
  dependency-version: 4.12.18
  dependency-type: direct:development
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-05-09 08:01:11 +00:00
snowluma-bot[bot]
7b93839186 Merge pull request #17 from SnowLuma/dev
chore: promote dev → main (1565749)
2026-05-09 15:37:22 +08:00
snowluma-bot[bot]
d0085ec052 Merge pull request #15 from SnowLuma/dev
chore: promote dev → main (c3b328f)
2026-05-09 15:04:19 +08:00
458 changed files with 67254 additions and 6395 deletions

View File

@@ -18,13 +18,15 @@ body:
required: true
- label: 我使用的是 [最新 Release](https://github.com/SnowLuma/SnowLuma/releases) 或当前 `dev` 分支构建
required: true
- label: 我已将日志级别调到 TRACE,并在下方「TRACE 日志」一栏附上了复现期间的完整日志
required: true
- type: input
id: snowluma-version
attributes:
label: SnowLuma 版本
description: 启动日志首行或 `package.json` 里的版本号
placeholder: "例如 1.8.5"
placeholder: "例如 1.10.2"
validations:
required: true
@@ -53,6 +55,19 @@ body:
validations:
required: true
- type: dropdown
id: deploy
attributes:
label: 部署方式
description: 如何运行 SnowLuma
options:
- 源码运行(pnpm dev / start)
- 预构建包
- Docker
- 其他 / 不确定
validations:
required: true
- type: input
id: node-version
attributes:
@@ -106,11 +121,21 @@ body:
- type: textarea
id: logs
attributes:
label: 相关日志 / 错误堆栈
label: TRACE 日志 / 错误堆栈
description: |
粘贴控制台日志、SSE 实时日志或错误堆栈。
请注意脱敏:移除 access token、账号密码、私聊内容等敏感信息。
**必须提供 TRACE 级别日志**,否则我们几乎无法定位问题。SnowLuma 默认日志级别是 `info`,TRACE 不会输出,请务必先开启再复现。
开启 TRACE 的两种方式(任选其一):
- **WebUI(推荐)**:进入「日志」页 →「服务端日志级别」切到 `TRACE` → 显示过滤切到「开发」预设(确保 TRACE 行可见,否则导出不含 trace)→ 复现问题 → 点「导出当前视图」得到 `snowluma-logs-*.log`,拖到本输入框上传。
- **环境变量**:启动前设置 `SNOWLUMA_LOG_LEVEL=trace` 再运行,复现后复制控制台输出。
贴出的日志里应当能看到 `TRACE` 字样。请注意脱敏:移除 access token、账号密码、私聊内容等敏感信息。
placeholder: |
[2026-06-26 12:00:00.000] TRACE [core] ...
[2026-06-26 12:00:00.001] DEBUG [bridge] ...
render: shell
validations:
required: true
- type: textarea
id: extra

View File

@@ -66,11 +66,13 @@ body:
- OneBot v11 规范: https://github.com/botuniverse/onebot-11/...
- 相关讨论: #xxx
- type: checkboxes
- type: dropdown
id: willingness
attributes:
label: 您是否愿意提交 PR 来实现这个功能?
options:
- label: 愿意,且需要维护者讨论方案后再动手
- label: 愿意,已有大致实现思路
- label: 暂时只提建议
- 愿意,但需要维护者讨论方案后再动手
- 愿意,已有大致实现思路
- 暂时只提建议
validations:
required: true

40
.github/logo.svg vendored Normal file
View File

@@ -0,0 +1,40 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 120" width="100%" height="100%" style="background-color: transparent;">
<defs>
<style>
@import url('https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@800&amp;display=swap');
.title-font {
font-family: 'Plus Jakarta Sans', sans-serif;
font-size: 48px;
font-weight: 800;
letter-spacing: -0.02em;
text-anchor: middle;
}
.star-fx {
animation: floatAnimation 4s ease-in-out infinite;
}
.star-top { transform-origin: 265px 25px; fill: #cec1e6; }
.star-bottom { transform-origin: 45px 95px; animation-delay: 0.5s; fill: #fad6e6; }
@keyframes floatAnimation {
0% { transform: translateY(0px) rotate(0deg); opacity: 0.9; }
50% { transform: translateY(-8px) rotate(10deg); opacity: 1; }
100% { transform: translateY(0px) rotate(0deg); opacity: 0.9; }
}
</style>
</defs>
<g transform="translate(160, 75)">
<text class="title-font" dx="2" dy="2">
<tspan fill="#f9d5e7">Snow</tspan><tspan fill="#a5c9ff">Luma</tspan>
</text>
<text class="title-font" dx="0" dy="0">
<tspan fill="#a5c9ff">Snow</tspan><tspan fill="#cec1e6">Luma</tspan>
</text>
</g>
<path class="star-fx star-top" d="M265,13 L267.8,21.1 L276,24 L267.8,26.9 L265,35 L262.2,26.9 L254,24 L262.2,21.1 Z"/>
<path class="star-fx star-bottom" d="M45,84 L47.1,90.2 L53.5,92.2 L47.1,94.2 L45,100 L42.9,94.2 L36.5,92.2 L42.9,90.2 Z"/>
</svg>

After

Width:  |  Height:  |  Size: 1.5 KiB

17
.github/pull_request_template.md vendored Normal file
View File

@@ -0,0 +1,17 @@
<!-- 感谢贡献。请填写以下内容,方便评审。 -->
## 关联 Issue
<!-- 例如 Closes #123。若无关联 issue,请说明这个 PR 解决什么问题、为何现在做。 -->
## 变更说明
<!-- 简述本 PR 做了什么、为什么这样做。 -->
## 提交前检查
- [ ] 本 PR 聚焦单一目标,未夹带无关改动
- [ ] 已通过 `pnpm lint` 与 `pnpm typecheck`
- [ ] 已补充/更新相关测试,且 `pnpm test` 通过
- [ ] 文件行尾为 LF(未引入 CRLF)
- [ ] PR 描述与实际实现一致

53
.github/workflows/ci.yml vendored Normal file
View File

@@ -0,0 +1,53 @@
# Run the full workspace test suite on every pull request.
#
# The repo previously had no PR test gate, so broken tests could land on `dev`
# unnoticed — and did (protocol's oidb-service rejection path, plus an external
# contributor PR). This gates every PR on the whole suite.
#
# `pnpm -r --no-bail --if-present test` runs each package's `test` script
# (skipping packages without one); --no-bail means one failing package still
# reports the rest, and the run as a whole still fails if any package fails.
name: CI
on:
pull_request:
permissions:
contents: read
# Cancel an in-flight run when the PR gets new commits.
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v6
with:
version: 10.28.0
run_install: false
- uses: actions/setup-node@v6
with:
node-version: '22'
cache: 'pnpm'
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Run all package tests
run: pnpm -r --no-bail --if-present test
# The MCP test suite regenerates the action catalog (catalog.ts + the
# catalog.json the docs site consumes). Fail if the committed snapshot
# drifted from the live specs — keeps the API docs from going stale.
- name: Verify generated action catalog is up to date
run: |
if ! git diff --exit-code -- packages/mcp/src/generated; then
echo '::error::Generated action catalog is stale. Run `pnpm --filter @snowluma/mcp gen` and commit packages/mcp/src/generated/.' >&2
exit 1
fi

View File

@@ -0,0 +1,94 @@
name: 校验 Bug 反馈日志
# 表单只能强制「非空」,强制不了「内容真的是 TRACE 级别」。
# 这个 workflow 在 bug issue 打开/编辑时解析正文里的 TRACE 日志小节,
# 缺日志就打 needs-logs 标签 + 评论,补齐后自动移除标签。
on:
issues:
types: [opened, edited]
permissions:
issues: write
jobs:
require-trace-logs:
runs-on: ubuntu-latest
# 只校验 Bug 反馈(表单会自动打 bug 标签)
if: contains(join(github.event.issue.labels.*.name, ','), 'bug')
steps:
- uses: actions/github-script@v7
with:
script: |
const NEEDS = 'needs-logs';
const MARKER = '<!-- needs-logs-bot -->';
const { owner, repo } = context.repo;
const issue = context.payload.issue;
const number = issue.number;
const body = issue.body || '';
// 抽取「TRACE 日志 / 错误堆栈」小节(issue form 渲染成 ### 标题)
const m = body.match(/###\s*TRACE 日志[^\n]*\n([\s\S]*?)(?:\n###\s|$)/);
const section = (m ? m[1] : '').trim();
// 粘贴的终端日志常带 ANSI 颜色码(如 \x1b[90mTRACE\x1b[0m),
// 颜色码结尾的 'm' 紧贴 TRACE 会吃掉 \b 单词边界,先剥掉再判定。
const clean = section.replace(/\x1b\[[0-9;]*m/g, '');
const empty = section === '' || /^_no response_$/i.test(section);
const hasTrace = /\bTRACE\b/i.test(clean);
// 去掉代码围栏后过短,基本等于没给
const stripped = clean.replace(/```[a-z]*|```|`/gi, '').trim();
const tooShort = stripped.length < 40;
const ok = !empty && hasTrace && !tooShort;
const hasLabel = (issue.labels || []).some((l) => (l.name || l) === NEEDS);
if (ok) {
if (hasLabel) {
try {
await github.rest.issues.removeLabel({ owner, repo, issue_number: number, name: NEEDS });
} catch (e) { /* 已被手动移除则忽略 */ }
}
return;
}
// 确保标签存在再添加(addLabels 不会自动建标签)
try {
await github.rest.issues.getLabel({ owner, repo, name: NEEDS });
} catch (e) {
try {
await github.rest.issues.createLabel({
owner, repo, name: NEEDS, color: 'd93f0b',
description: '缺少有效的 TRACE 日志',
});
} catch (e2) { /* 并发下可能已被建出 */ }
}
await github.rest.issues.addLabels({ owner, repo, issue_number: number, labels: [NEEDS] });
// 已经提示过就不再刷屏
const comments = await github.paginate(github.rest.issues.listComments, {
owner, repo, issue_number: number,
});
if (comments.some((c) => (c.body || '').includes(MARKER))) return;
const reasons = [];
if (empty) reasons.push('- 日志字段为空');
else if (!hasTrace) reasons.push('- 日志里没有 `TRACE` 字样(默认级别 `info` 不输出 TRACE,需先开启)');
else if (tooShort) reasons.push('- 日志内容过短,疑似未提供完整日志');
const comment = [
MARKER,
`@${issue.user.login} 这条反馈缺少有效的 **TRACE 级别日志**,已标记为 \`${NEEDS}\`:`,
'',
reasons.join('\n'),
'',
'请按以下任一方式开启 TRACE 后复现,再 **编辑本 issue** 把完整日志补到「TRACE 日志 / 错误堆栈」一栏:',
'',
'- **WebUI**:「日志」页 → 服务端日志级别切到 `TRACE` → 显示过滤用「开发」预设 → 复现 → 导出当前视图。',
'- **环境变量**:`SNOWLUMA_LOG_LEVEL=trace` 启动后复现。',
'',
'补齐后机器人会自动移除该标记。若你以附件形式上传了 `.log` 文件,请在正文里也贴一段关键日志(机器人只能识别正文)。',
].join('\n');
await github.rest.issues.createComment({ owner, repo, issue_number: number, body: comment });

View File

@@ -0,0 +1,65 @@
name: Issue template guard
# Blank / free-form issues bypass `blank_issues_enabled: false` (it only hides
# the chooser link — the CLI, API and direct URLs still create template-less
# issues). This guard enforces the policy after the fact: an issue opened by
# someone WITHOUT write access that did not go through a template (no template
# label) is commented on and closed. Properly-filed bug reports / feature
# requests (which carry `bug` / `enhancement`) and anyone with write access are
# left alone.
#
# Note: workflows for `issues` events run from the file on the DEFAULT branch,
# so this only takes effect once it lands on `main`.
on:
issues:
types: [opened]
permissions:
issues: write
jobs:
guard:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v7
with:
script: |
const issue = context.payload.issue;
// Write-access roles are exempt.
const privileged = ['OWNER', 'MEMBER', 'COLLABORATOR'];
if (privileged.includes(issue.author_association)) {
core.info(`author_association=${issue.author_association} — allowed`);
return;
}
// A template was used iff it stamped its label.
const TEMPLATE_LABELS = ['bug', 'enhancement'];
const labels = (issue.labels || []).map((l) => (typeof l === 'string' ? l : l.name));
if (labels.some((l) => TEMPLATE_LABELS.includes(l))) {
core.info('template label present — allowed');
return;
}
// Non-privileged + no template → guide and close.
const { owner, repo } = context.repo;
const chooser = `https://github.com/${owner}/${repo}/issues/new/choose`;
const body = [
'感谢你的反馈。',
'',
'本仓库的 issue 需要通过模板提交:请使用 **Bug 反馈** 或 **功能请求** 模板重新创建,',
'以便我们准确、高效地处理。直接创建的空白 / 自定义 issue 会被自动关闭。',
'',
`- 重新创建:${chooser}`,
'- 日常使用、快速交流类问题,可先到 README 中的 QQ 群',
'',
'本 issue 将自动关闭,感谢理解。',
].join('\n');
await github.rest.issues.createComment({ owner, repo, issue_number: issue.number, body });
await github.rest.issues.update({
owner, repo, issue_number: issue.number,
state: 'closed', state_reason: 'not_planned',
});
core.info(`closed #${issue.number} (author_association=${issue.author_association}, no template label)`);

109
.github/workflows/mcp-npm-publish.yml vendored Normal file
View File

@@ -0,0 +1,109 @@
name: Publish MCP to npm
on:
push:
branches: [main]
paths:
- 'packages/mcp/**'
# The action catalog is generated from @snowluma/onebot's specs, so an
# action change must republish the MCP snapshot.
- 'packages/onebot/**'
- 'package.json'
- 'pnpm-lock.yaml'
- 'pnpm-workspace.yaml'
- 'tsconfig.base.json'
workflow_dispatch:
permissions:
contents: read
id-token: write
concurrency:
group: mcp-npm-publish-${{ github.ref }}
cancel-in-progress: false
jobs:
publish:
name: Build, test, and publish MCP
runs-on: ubuntu-latest
environment: SnowLuma
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Setup pnpm
uses: pnpm/action-setup@v6
with:
version: 10.28.0
run_install: false
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: '22'
cache: 'pnpm'
registry-url: 'https://registry.npmjs.org'
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Type check MCP
run: pnpm --filter @snowluma/mcp typecheck
- name: Test MCP (regenerates + validates the action catalog)
run: pnpm --filter @snowluma/mcp test
- name: Build MCP
run: pnpm --filter @snowluma/mcp build
- name: Check npm package version
id: npm
working-directory: packages/mcp
shell: bash
run: |
set -euo pipefail
package_name="$(node -e "const fs = require('node:fs'); console.log(JSON.parse(fs.readFileSync('package.json', 'utf8')).name)")"
package_version="$(node -e "const fs = require('node:fs'); console.log(JSON.parse(fs.readFileSync('package.json', 'utf8')).version)")"
{
echo "package_name=${package_name}"
echo "package_version=${package_version}"
} >> "${GITHUB_OUTPUT}"
if npm view "${package_name}@${package_version}" version >/dev/null 2>&1; then
echo "already_published=true" >> "${GITHUB_OUTPUT}"
echo "::notice::${package_name}@${package_version} already exists on npm; skipping publish."
else
echo "already_published=false" >> "${GITHUB_OUTPUT}"
fi
- name: Validate npm token
if: steps.npm.outputs.already_published != 'true'
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
run: |
if [ -z "${NODE_AUTH_TOKEN}" ]; then
echo 'Missing NPM_TOKEN in the SnowLuma environment secrets.' >&2
exit 1
fi
- name: Publish MCP to npm
if: steps.npm.outputs.already_published != 'true'
working-directory: packages/mcp
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
run: npm publish --access public --provenance
- name: Summary
shell: bash
run: |
{
echo "## MCP npm publish"
echo
echo "| Key | Value |"
echo "| --- | --- |"
echo "| Package | \`${{ steps.npm.outputs.package_name }}\` |"
echo "| Version | \`${{ steps.npm.outputs.package_version }}\` |"
echo "| Already published | \`${{ steps.npm.outputs.already_published }}\` |"
echo "| Environment | \`SnowLuma\` |"
} >> "${GITHUB_STEP_SUMMARY}"

34
.github/workflows/stale-needs-logs.yml vendored Normal file
View File

@@ -0,0 +1,34 @@
name: 关闭长期缺日志的反馈
# needs-logs 的 issue 若长期不补 TRACE 日志,先标 stale,再自动关闭。
# 补齐日志后 issue-require-logs 会移除 needs-logs,这里 only-labels 过滤即跳过。
on:
schedule:
- cron: '0 2 * * *'
workflow_dispatch:
permissions:
issues: write
jobs:
stale:
runs-on: ubuntu-latest
steps:
- uses: actions/stale@v9
with:
only-labels: 'needs-logs'
days-before-stale: 7
days-before-close: 7
stale-issue-label: 'stale'
close-issue-reason: 'not_planned'
ascending: true
# 不处理 PR
days-before-pr-stale: -1
days-before-pr-close: -1
stale-issue-message: >
这条反馈因长期缺少有效的 TRACE 日志被标记为 `stale`。
若 7 天内仍未补充日志,将自动关闭。补充后请编辑 issue 贴上日志或留言。
close-issue-message: >
因长期缺少定位所需的 TRACE 日志,已自动关闭。
如果问题仍然存在,欢迎补齐 TRACE 日志后重新打开本 issue 或新开一个。

114
.github/workflows/sync-docs-catalog.yml vendored Normal file
View File

@@ -0,0 +1,114 @@
name: Sync action catalog to docs
# Regenerates the OneBot action catalog from @snowluma/onebot's specs and commits
# the plain-JSON twin (catalog.json) into the SnowLumaDocs repo, where the docs
# build turns it into the API Reference pages. Runs on main (the release/promote
# target) so the published docs always describe shipped behavior. Uses the same
# SnowLuma bot GitHub App as the promote-dev-to-main flow.
on:
push:
branches: [main]
paths:
- 'packages/onebot/src/actions/**'
- 'packages/onebot/src/action-kit.ts'
- 'packages/onebot/src/action-docs.ts'
workflow_dispatch:
permissions:
contents: read
concurrency:
group: sync-docs-catalog
cancel-in-progress: true
jobs:
sync:
runs-on: ubuntu-latest
steps:
- name: Checkout SnowLuma
uses: actions/checkout@v6
- name: Setup pnpm
uses: pnpm/action-setup@v6
with:
version: 10.28.0
run_install: false
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: '22'
cache: 'pnpm'
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Generate catalog.json
run: pnpm --filter @snowluma/mcp gen
- name: Validate GitHub App credentials
env:
APP_ID: ${{ secrets.SNOWLUMA_BOT_APP_ID }}
PRIVATE_KEY: ${{ secrets.SNOWLUMA_BOT_PRIVATE_KEY }}
run: |
if [ -z "${APP_ID}" ] || [ -z "${PRIVATE_KEY}" ]; then
echo 'Missing SNOWLUMA_BOT_APP_ID and/or SNOWLUMA_BOT_PRIVATE_KEY secrets.' >&2
echo 'Configure the same GitHub App used by the promote-dev-to-main flow.' >&2
exit 1
fi
- name: Mint GitHub App installation token (scoped to SnowLumaDocs)
id: app-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.SNOWLUMA_BOT_APP_ID }}
private-key: ${{ secrets.SNOWLUMA_BOT_PRIVATE_KEY }}
owner: ${{ github.repository_owner }}
repositories: SnowLumaDocs
- name: Resolve bot identity
id: bot
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
run: |
set -euo pipefail
bot_login="${APP_SLUG}[bot]"
bot_id="$(gh api "/users/${bot_login}" --jq .id)"
bot_email="${bot_id}+${bot_login}@users.noreply.github.com"
{
echo "login=${bot_login}"
echo "email=${bot_email}"
} >> "${GITHUB_OUTPUT}"
- name: Commit catalog.json to docs repo
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
BOT_LOGIN: ${{ steps.bot.outputs.login }}
BOT_EMAIL: ${{ steps.bot.outputs.email }}
OWNER: ${{ github.repository_owner }}
run: |
set -euo pipefail
src="$(pwd)/packages/mcp/src/generated/catalog.json"
tmp="$(mktemp -d)"
git clone --depth 1 \
"https://x-access-token:${GH_TOKEN}@github.com/${OWNER}/SnowLumaDocs.git" "$tmp"
mkdir -p "$tmp/docs/public/api"
cp "$src" "$tmp/docs/public/api/catalog.json"
cd "$tmp"
git config user.name "${BOT_LOGIN}"
git config user.email "${BOT_EMAIL}"
# Stage first: `git diff --quiet` ignores UNTRACKED files, so on the
# initial sync (catalog.json not yet in the docs repo) the index diff
# is the only reliable change check.
git add docs/public/api/catalog.json
if git diff --cached --quiet; then
echo "::notice::catalog.json unchanged; nothing to sync."
exit 0
fi
git commit -m "chore(api): sync action catalog from SnowLuma@${GITHUB_SHA::7}"
# Single writer, but guard against a concurrent docs commit racing the
# shallow clone: rebase onto the latest main before pushing.
git pull --rebase --depth 1 origin main
git push origin HEAD:main

6
.gitignore vendored
View File

@@ -11,7 +11,13 @@ dist/
/config/
/data/
# per-package runtime data dirs (e.g. packages/core/data/<uin>/*.db written by
# IdentityService during tests) — not just the root /data/
**/data/
logs/
# macOS metadata
.DS_Store
# test coverage output
coverage/

View File

@@ -285,3 +285,13 @@ git push origin v1.7.0 # → 仅触发 release.yml
- 如果只是想确认"我这么改 OK 吗",欢迎开 draft PR,先把代码亮出来再讨论。
感谢你愿意花时间贡献 SnowLuma —— 这个项目能走多远,取决于你们每一个人。❄️
## 贡献的许可 / Licensing of contributions
当你提交 PR,即表示你的贡献按本项目的 [`LICENSE`](LICENSE)(SnowLuma 源码可见非商业许可)授权,且你声明你有权这么做、贡献为你的原创(若含第三方材料,请在 PR 中显著标注其来源与许可证)。
**你保留对自己贡献的版权**,同时**授予 SnowLumaDevs 一项永久、全球、免费、不可撤销、可再许可(sublicensable)的许可**,可使用、复制、修改、分发你的贡献并基于其制作衍生作品,**包括以本项目非商业许可之外的其他条款(含商业条款)再许可与分发**——以便项目方无需逐一回头征求同意,即可在获授权的商业场景中使用社区贡献。
By opening a PR, you agree your contribution is licensed under the project's [`LICENSE`](LICENSE); you represent that you have the right to submit it and that it is your own work (clearly identify any third-party material in the PR).
**You retain copyright in your contribution** and additionally grant SnowLumaDevs a **perpetual, worldwide, royalty-free, irrevocable, sublicensable license** to use, reproduce, modify, distribute, and create derivative works of your contribution, **including the right to relicense and distribute it under terms other than this project's non-commercial license (including commercial terms)** — so the project can use community contributions in authorized commercial scenarios without seeking each contributor's consent again.

90
EULA.md Normal file
View File

@@ -0,0 +1,90 @@
# SnowLuma 最终用户许可协议(EULA)/ End-User License Agreement
- **生效日期 / Effective date:** 2026-06-19
- **版本 / Version:** 1.0
- **许可方 / Licensor:** SnowLumaDevs(联系方式 / Contact: motricseven@foxmail.com)
> 本协议以中文与英文两种语言提供。如两版本有冲突,**以中文版本为准**。
> This Agreement is provided in Chinese and English. **In case of any conflict, the Chinese version prevails.**
---
## 中文版
### 1. 定义与接受
1.1 "**本软件**"指 SnowLuma 软件及其官方发行包,包括可执行文件、原生模块(`snowluma-*.node`)、文档及相关组件。
1.2 "**您**"指下载、安装、运行或以其他方式使用本软件的个人或实体。
1.3 下载、安装、运行或使用本软件,即表示您已阅读、理解并同意受本协议约束。**若您不同意本协议,请勿使用本软件并删除其全部副本。**
### 2. 授权范围
2.1 本软件的**源代码**依据 GNU Affero General Public License 第 3 版(AGPL-3.0)及其第 7 条附加许可(原生模块链接例外)授权,详见随附的 `LICENSE` 文件。
2.2 本协议是针对**发行包(二进制)**的补充条款,就 AGPL 未涵盖之事项(接受方式、可接受使用、免责、专有组件、争议解决等)作出约定。
2.3 **本协议不减损 AGPL 授予您的任何权利。** 对于您依 AGPL 单独获取、使用、修改或分发源代码的行为,本协议不附加任何限制。
2.4 专有组件(见第 5 条)不属于 AGPL 授权范围,依其各自条款授权。
### 3. 免责声明
3.1 **非官方、无隶属**:本软件是独立的第三方互操作性项目,与腾讯公司(Tencent)及 QQ **无任何隶属、合作、授权或背书关系**。"QQ""腾讯"等名称及标识为其各自所有者的商标。
3.2 **用途**:本软件**仅供学习、研究与技术互操作之目的**提供。
3.3 **合规义务**:您须自行确保对本软件的使用符合一切适用法律法规,以及您所接入平台的规定(包括但不限于《QQ 用户协议》与相关服务条款)。
3.4 **按"现状"提供**:本软件按"**现状(AS-IS)**"及"**现有(AS-AVAILABLE)**"提供,不附带任何明示或默示的担保,包括但不限于对适销性、特定用途适用性、不侵权、可用性、准确性或不中断的担保。
3.5 **责任限制**:在适用法律允许的最大范围内,对于因使用或无法使用本软件而导致的任何直接、间接、偶然、特殊、惩罚性或后果性损害(包括但不限于账号封禁或限制、数据丢失、利润或业务损失、服务中断),SnowLumaDevs **概不承担责任**。
3.6 **风险自负**:您理解,使用非官方协议工具接入第三方平台**可能违反该平台条款并导致账号风险**,您**自愿承担**该等风险。
### 4. 可接受使用
您**不得**将本软件用于:(a) 任何违法犯罪活动;(b) 未经授权访问、干扰或破坏任何系统或网络;(c) 发送垃圾信息、实施骚扰、欺诈或传播恶意内容;(d) 侵犯他人隐私、知识产权或其他合法权益;(e) 任何违反所接入平台服务条款的行为。
### 5. 专有组件
5.1 本软件可能包含或依赖**非开源的专有组件**,包括但不限于 **SnowLuma 原生模块**(`snowluma-*.node`),以及其中可能包含的任何授权、激活或技术保护措施。
5.2 此类专有组件的**源代码不依 AGPL 提供**,受本条款约束。
5.3 除适用法律强制性规定明确允许外,您不得对专有组件进行逆向工程、反编译或反汇编,亦不得规避、破解或绕过其授权或激活机制。
5.4 `LICENSE` 第 7 条的链接例外仅允许将本软件与该原生模块**组合并分发**,**并不**向您授予该原生模块本身的源代码权利。
### 6. 终止
若您违反本协议任何条款,本协议项下授予您的权利(**不含**您依 AGPL 单独享有的权利)将自动终止。终止后,您应停止使用并删除发行包中的专有组件。
### 7. 适用法律与争议解决
本协议的订立、效力、解释、履行及争议解决,均适用**中华人民共和国大陆地区法律**(不含其冲突法规则)。因本协议引起或与之相关的任何争议,双方应首先友好协商解决;协商不成的,任何一方可向**有管辖权的人民法院**提起诉讼。
### 8. 协议的变更
SnowLumaDevs 可不时更新本协议。更新后的版本将随发行包发布并注明生效日期。在更新生效后继续使用本软件,即视为您接受更新后的条款。
---
## English Version
### 1. Definitions and Acceptance
1.1 "**Software**" means the SnowLuma software and its official distribution packages, including executables, native modules (`snowluma-*.node`), documentation, and related components.
1.2 "**You**" means the individual or entity that downloads, installs, runs, or otherwise uses the Software.
1.3 By downloading, installing, running, or using the Software, you acknowledge that you have read, understood, and agree to be bound by this Agreement. **If you do not agree, do not use the Software and delete all copies.**
### 2. Scope of License
2.1 The **source code** of the Software is licensed under the GNU Affero General Public License version 3 (AGPL-3.0) together with its Section 7 additional permission (the native-addon linking exception); see the accompanying `LICENSE` file.
2.2 This Agreement provides **supplemental terms for the binary distribution packages**, addressing matters not covered by the AGPL (acceptance, acceptable use, disclaimers, proprietary components, dispute resolution).
2.3 **This Agreement does not diminish any rights granted to you under the AGPL.** It imposes no additional restriction on your acquisition, use, modification, or distribution of the source code under the AGPL.
2.4 Proprietary Components (Section 5) are outside the scope of the AGPL and are licensed under their own terms.
### 3. Disclaimers
3.1 **Not official; no affiliation.** The Software is an independent, third-party interoperability project and has **no affiliation, partnership, authorization, or endorsement relationship** with Tencent or QQ. "QQ", "Tencent", and related marks belong to their respective owners.
3.2 **Purpose.** The Software is provided **solely for learning, research, and technical interoperability**.
3.3 **Compliance.** You are responsible for ensuring that your use complies with all applicable laws and with the terms of any platform you connect to (including the QQ User Agreement and related terms of service).
3.4 **AS-IS.** The Software is provided "**AS IS**" and "**AS AVAILABLE**", without warranties of any kind, express or implied, including merchantability, fitness for a particular purpose, non-infringement, availability, accuracy, or uninterrupted operation.
3.5 **Limitation of liability.** To the maximum extent permitted by law, SnowLumaDevs shall **not be liable** for any direct, indirect, incidental, special, punitive, or consequential damages (including account suspension or restriction, data loss, lost profits or business, or service interruption) arising from use of or inability to use the Software.
3.6 **Assumption of risk.** You understand that using an unofficial protocol tool to connect to a third-party platform **may violate that platform's terms and carry account risk**, which you **voluntarily assume**.
### 4. Acceptable Use
You shall **not** use the Software for: (a) any unlawful activity; (b) unauthorized access to, interference with, or disruption of any system or network; (c) spam, harassment, fraud, or malicious content; (d) infringement of others' privacy, intellectual-property, or other lawful rights; or (e) any conduct that violates the terms of service of a connected platform.
### 5. Proprietary Components
5.1 The Software may include or depend on **non-free proprietary components**, including but not limited to the **SnowLuma native addon** (`snowluma-*.node`) and any licensing, activation, or technical-protection measures it may contain.
5.2 The **source code of such components is not provided under the AGPL** and is governed by these terms.
5.3 Except to the extent expressly permitted by mandatory applicable law, you may not reverse engineer, decompile, or disassemble the Proprietary Components, nor circumvent, crack, or bypass their licensing or activation mechanisms.
5.4 The Section 7 linking exception in `LICENSE` permits only the **combination and distribution** of the Software with the SnowLuma native addon; it does **not** grant you rights to that addon's own source code.
### 6. Termination
If you breach any term of this Agreement, the rights granted to you hereunder (**excluding** rights you hold separately under the AGPL) terminate automatically. Upon termination you must cease use of and delete the Proprietary Components from the distribution package.
### 7. Governing Law and Disputes
This Agreement is governed by the laws of the **mainland of the People's Republic of China** (excluding its conflict-of-laws rules). Any dispute arising out of or relating to this Agreement shall first be resolved through good-faith negotiation; failing that, either party may bring an action before a **court of competent jurisdiction**.
### 8. Changes
SnowLumaDevs may update this Agreement from time to time. Updated versions will be published with the distribution package and bear an effective date. Continued use after an update takes effect constitutes acceptance of the updated terms.

131
LICENSE Normal file
View File

@@ -0,0 +1,131 @@
SnowLuma Source-Available Non-Commercial License
SnowLuma 源码可见非商业许可
Version 1.0 · 2026-06-19
Copyright (C) 2026 SnowLumaDevs
Contact: motricseven@foxmail.com
中英文如有冲突,以中文为准。
In case of any conflict between the Chinese and English text, the Chinese
version prevails.
This is NOT an open-source license as defined by the Open Source Initiative:
it restricts commercial use and the public release of modifications. The
source is published for transparency, study, and non-commercial self-hosting.
本许可不是 OSI 定义的开源许可:它限制商业用途与修改版的公开发布。源码公开
仅用于透明、学习与非商业的自托管。
===============================================================================
1. Definitions / 定义
===============================================================================
- "Software" / "本软件": the SnowLuma source code and assets in this
repository, excluding the Native Addon (defined below) and any third-party
components.
- "You" / "你": any individual or entity exercising rights under this License.
- "Commercial Use" / "商业用途": any use primarily intended for or directed
toward commercial advantage or monetary compensation. This includes, without
limitation, selling or reselling the Software; offering paid hosting,
deployment, setup, or operation services based on the Software; bundling it
into a paid product or service; or running it to provide a service for a fee.
包括但不限于:出售或转售本软件;提供基于本软件的付费托管、部署、代搭、代运营
服务;将其并入付费产品或服务;或以收费方式运行本软件对外提供服务。
- "Native Addon" / "原生附加组件": the SnowLuma native binary components shipped
with the Software (e.g. `snowluma-*.node`, `snowluma-*.dll`, `snowluma-*.so`).
These are a separate, proprietary component and are NOT licensed under this
License — see Section 5.
===============================================================================
2. Grant / 授权
===============================================================================
Subject to the conditions and restrictions below, the copyright holder grants
You a worldwide, royalty-free, non-exclusive, non-transferable, revocable
license to:
在下列条件与限制下,著作权人授予你一项全球、免费、非独占、不可转让、可撤销的
许可,允许你:
(a) view and study the Software; 查看与学习本软件;
(b) use and run the Software for personal or other Non-Commercial purposes;
为个人或其他非商业目的使用与运行本软件;
(c) modify the Software for Your own Non-Commercial use; 为自己的非商业使用
修改本软件;
(d) redistribute the Software under the conditions in Section 3.
在第 3 条的条件下再分发本软件。
===============================================================================
3. Redistribution Conditions / 再分发条件
===============================================================================
You may redistribute the Software (modified or unmodified) ONLY if ALL of the
following are met. 仅当同时满足以下全部条件时,你方可再分发本软件(无论是否修改):
(a) it is Non-Commercial; 属非商业性质;
(b) the complete text of this License is included; 附带本许可的完整文本;
(c) all copyright, attribution, and notices are retained unaltered;
保留全部著作权、署名与声明,且不得改动;
(d) PUBLIC release of a modified or derivative version requires the prior
written permission of the copyright holder. Private, non-public
modifications for Your own Non-Commercial use are permitted.
公开发布修改版或衍生版,须事先获得著作权人书面许可;为你自己非商业使用
而作的、不公开的修改则被允许。
===============================================================================
4. Restrictions / 限制
===============================================================================
(a) Commercial Use of the Software in any form is PROHIBITED without the
prior written authorization of the copyright holder.
未经著作权人事先书面授权,禁止以任何形式对本软件进行商业使用。
(b) You may not develop, publish, or distribute another project based on the
Software without the prior written authorization of the copyright holder.
未经著作权人事先书面授权,不得基于本软件开发、发布或分发另一个项目。
(c) You may not remove, obscure, or alter any copyright, attribution, license,
or notice. 不得移除、遮蔽或更改任何著作权、署名、许可或声明。
===============================================================================
5. Native Addon / 原生附加组件
===============================================================================
The Native Addon is proprietary and is NOT covered by this License. It is
distributed only as a precompiled binary bundled with the Software. No rights
are granted to it other than to run it as bundled for the Non-Commercial use
permitted above; in particular, no right to reverse engineer, reproduce,
modify, redistribute separately, or relicense it is granted.
原生附加组件为专有组件,不在本许可范围内,仅以随本软件分发的预编译二进制形式提供。
除按上文允许的非商业用途以其随附形式运行外,不授予任何权利;尤其不授予对其进行逆向、
复制、修改、单独再分发或再许可的权利。
===============================================================================
6. Additional Permissions / 额外授权
===============================================================================
Any use not granted by this License — including Commercial Use and the public
release of derivative works — requires prior written permission, which must be
requested from and granted by the copyright holder (Contact above).
本许可未授予的任何用途——包括商业使用及公开发布衍生作品——均须事先取得著作权人的
书面许可(见上方联系方式)。
===============================================================================
7. Third-Party Components / 第三方组件
===============================================================================
Third-party code and components retain their own original licenses, which
govern those parts. 第三方代码与组件遵循其各自的原始许可,并以其许可为准。
===============================================================================
8. Termination / 终止
===============================================================================
Any breach of this License automatically terminates the rights granted to You
under it. 任何违反本许可的行为将自动终止你依本许可获得的权利。
===============================================================================
9. Disclaimer / 免责声明
===============================================================================
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
本软件按“现状”提供,不附带任何明示或默示的担保,包括但不限于适销性、特定用途
适用性及不侵权的担保。在任何情况下,作者或著作权人均不对因本软件或其使用所引起
的任何索赔、损害或其他责任负责。
===============================================================================
10. Governing Law / 适用法律
===============================================================================
This License is governed by the laws of the mainland of the People's Republic
of China, excluding its conflict-of-laws rules.
本许可适用中华人民共和国大陆地区法律(不含其冲突法规则)。

149
PRIVACY.md Normal file
View File

@@ -0,0 +1,149 @@
# SnowLuma 隐私与数据处理说明 / Privacy & Data Handling Notice
- **生效日期 / Effective date:** 2026-06-19
- **版本 / Version:** 1.0
- **责任主体 / Provider:** SnowLumaDevs(联系方式 / Contact: motricseven@foxmail.com)
> 本说明以中文与英文两种语言提供。如有冲突,**以中文版本为准**。
> Provided in Chinese and English. **In case of conflict, the Chinese version prevails.**
---
## 中文版
### 1. 概述
SnowLuma 是一款**自托管**软件:它运行在**您自己的设备或服务器**上。**SnowLumaDevs(作者方)默认不收集、不接收、不存储您的任何个人数据**。本软件**不包含**任何需要联网激活、或向作者方回传信息的授权机制。
本说明唯一例外的数据外发情形,是第 4、5 条所述的两种,且其中遥测受严格限制(第 5 条)。
### 2. 本软件在您设备上存储的数据
为实现功能,本软件会在您的设备本地(如 SQLite 数据库、配置与日志文件)存储以下类别的数据。**这些数据保存在您本地、由您掌控,作者方无法访问:**
- **账号与登录凭据**:所登录的 QQ 账号信息、会话/令牌、WebUI 登录口令(以**加盐 scrypt 哈希**形式存储,不保存明文)。
- **关系数据**:好友、群组及成员的列表与资料。
- **消息数据**:为实现协议转换而处理或缓存的消息(视您的配置而定)。
- **运行配置与日志**:适配器配置、运行日志等。
> 说明:因 SnowLuma 是 QQ 协议工具,上述本地数据**必然**包含 QQ 账号及联系人信息。这与第 5 条"遥测绝不采集 QQ 账号/联系人"并不矛盾——本地存储 ≠ 对外传输。
### 3. 您作为数据控制者的责任
当您运行本软件处理您 QQ 联系人、群成员等他人的个人信息时,**您是该等个人信息的"数据控制者/处理者"**,须自行就该等处理承担合规责任(包括取得必要同意、保障安全、响应数据主体请求等)。作者方仅提供软件工具,不参与您的数据处理活动。
### 4. 数据离开您设备的唯一途径
除以下两种情形外,本软件不会将您的数据传输至任何外部目的地:
1. **您自行配置的通知 / Webhook**:当您主动配置通知渠道(如 Webhook)时,相应内容会按**您填写的地址与设置**外发。目的地与内容由您完全掌控,作者方不经手。
2. **匿名遥测**:见第 5 条。
### 5. 遥测(Telemetry)
**模式:默认开启(opt-out)。** 您可随时关闭(见 5.3)。
#### 5.1 采集内容(仅匿名、聚合,无法定位到个人)
- 应用版本、操作系统与 CPU 架构、Node.js 版本;
- 启动次数、功能使用计数(例如启用了哪些适配器/命令,**不含其参数或内容**);
- 匿名化的崩溃栈与错误类型。
#### 5.2 绝不采集(显式负面清单)
本遥测**在任何情况下都不会**采集或传输:
- **QQ 账号 / UIN,及好友、群、成员的身份信息**;
- **消息内容或其元数据**、昵称、头像;
- 手机号、邮箱或任何联系方式;
- 凭据、令牌、密码;
- 用于身份画像的精确 IP 地址(若服务端在传输层偶然可见 IP,将即时丢弃、不入库、不进行关联);
- 任何可直接或间接定位到自然人的标识。
#### 5.3 如何关闭与告知
- **首次运行提示**:软件首次运行时会在控制台与 WebUI 一次性告知遥测已默认开启及关闭方式。
- **一键关闭**:可通过环境变量 `SNOWLUMA_TELEMETRY=0`、配置项或 WebUI 开关随时关闭,关闭后即刻停止采集。
#### 5.4 用途、共享与保留
遥测数据**仅用于改进本软件**,**不向任何第三方出售或共享**,仅以匿名聚合形式保留必要期限。
#### 5.5 生效状态(重要)
本条款完整描述了 SnowLuma 的遥测机制,但**仅对实际包含遥测代码的发行版生效**。
> **当前生效状态(截至 2026-06-17)**:公开发行版**尚未包含**遥测代码,故本条款目前**处于未生效状态**。一旦某一发行版引入遥测,将在该版本的发布说明中明确告知,并使本条款对该版本生效。
### 6. 数据安全与保留
本地数据的安全与保留由您(运营者)控制。建议您妥善保护设备访问权限、定期更新 WebUI 口令。
### 7. 第三方组件
本软件可能捆绑第三方组件(如用于音视频处理的 FFmpeg)。此类组件**在您本地运行**、用于处理本地数据,**不向作者方或第三方外发**数据。
### 8. 未成年人
本软件面向开发者与技术用户,**不面向未成年人**,作者方不会有意收集未成年人信息。
### 9. 您的权利
由于作者方默认不持有您的任何个人数据,与您个人信息相关的访问、更正、删除等权利,应在**您本地的数据范围内**由您自行行使。如遥测启用且您有疑问,可通过第 10 条联系我们。
### 10. 联系方式
隐私相关问询:**motricseven@foxmail.com**。
### 11. 变更
本说明可不时更新,更新版本将注明生效日期。涉及遥测的重大变更将在发布说明中显著告知。
---
## English Version
### 1. Overview
SnowLuma is **self-hosted**: it runs on **your own device or server**. **By default, SnowLumaDevs (the authors) collect, receive, and store none of your data.** The Software contains **no** activation that requires network access or transmits information back to the authors. The only data that ever leaves your device is described in Sections 4 and 5, and telemetry is strictly limited (Section 5).
### 2. Data the Software Stores on Your Device
To function, the Software stores the following categories of data locally (e.g., in a SQLite database, configuration, and log files). **This data stays on your device under your control; the authors cannot access it:**
- **Account & credentials:** the signed-in QQ account, session/tokens, and the WebUI login password (stored as a **salted scrypt hash**, never in plaintext).
- **Relationship data:** lists and profiles of friends, groups, and members.
- **Message data:** messages processed or cached for protocol conversion (depending on your configuration).
- **Runtime configuration & logs.**
> Note: Because SnowLuma is a QQ protocol tool, this local data **necessarily** includes QQ account and contact information. This does not conflict with Section 5 ("telemetry never collects QQ account/contacts") — local storage ≠ outbound transmission.
### 3. You Are the Data Controller
When you run the Software to process the personal information of your QQ contacts, group members, or other individuals, **you are the data controller/processor** for that information and are responsible for compliance (obtaining any necessary consent, securing the data, responding to data-subject requests). The authors merely provide a software tool and take no part in your processing.
### 4. The Only Ways Data Leaves Your Device
The Software transmits your data to an external destination only in these two cases:
1. **Notifications / webhooks you configure:** when you set up a notification channel (e.g., a webhook), the relevant content is sent to **the address and settings you provide**. You fully control the destination and content; the authors are not involved.
2. **Anonymous telemetry:** see Section 5.
### 5. Telemetry
**Mode: ON by default (opt-out).** You can disable it at any time (see 5.3).
#### 5.1 What is collected (anonymous, aggregate, non-identifying only)
- Application version, OS and CPU architecture, Node.js version;
- Launch counts and feature-usage counts (e.g., which adapters/commands are enabled — **never their arguments or content**);
- Anonymized crash stacks and error types.
#### 5.2 Never collected (explicit negative list)
Telemetry will **never, under any circumstances**, collect or transmit:
- **QQ account / UIN, or the identity of any friend, group, or member**;
- **Message content or metadata**, nicknames, avatars;
- Phone numbers, emails, or any contact details;
- Credentials, tokens, passwords;
- Precise IP addresses used for profiling (any IP incidentally visible at the transport layer is discarded immediately, not stored, not correlated);
- Any identifier that could directly or indirectly identify a natural person.
#### 5.3 How to disable; notice
- **First-run notice:** on first run the Software gives a one-time notice in the console and WebUI that telemetry is on by default and how to disable it.
- **One switch off:** disable any time via the `SNOWLUMA_TELEMETRY=0` environment variable, a config option, or the WebUI toggle; collection stops immediately.
#### 5.4 Use, sharing, retention
Telemetry is used **only to improve the Software**, is **never sold or shared with any third party**, and is retained only in anonymous aggregate form for as long as necessary.
#### 5.5 Effective status (important)
This Section fully describes SnowLuma's telemetry mechanism but is **effective only for builds that actually contain telemetry code.**
> **Current status (as of 2026-06-17):** public releases **do not yet contain** telemetry code, so this Section is currently **not in effect**. If a release introduces telemetry, its release notes will say so and this Section will take effect for that release.
### 6. Security & Retention
Security and retention of local data are under your (the operator's) control. Protect device access and rotate the WebUI password regularly.
### 7. Third-Party Components
The Software may bundle third-party components (such as FFmpeg for media processing). These run **locally** on your device to process local data and **send nothing** to the authors or third parties.
### 8. Minors
The Software targets developers and technical users, is **not directed to minors**, and the authors do not knowingly collect minors' information.
### 9. Your Rights
Because the authors hold none of your personal data by default, rights of access, correction, and deletion are exercised by you **over the data on your own device**. If telemetry is enabled and you have questions, contact us (Section 10).
### 10. Contact
Privacy inquiries: **motricseven@foxmail.com**.
### 11. Changes
This Notice may be updated from time to time; updated versions bear an effective date. Material changes affecting telemetry will be prominently noted in release notes.

119
README.md
View File

@@ -1,4 +1,6 @@
<h1 align="center">❄️ SnowLuma</h1>
<h1 align="center">
<img src=".github/logo.svg" width="100%" alt="SnowLuma" />
</h1>
<p align="center">
<i>Next Remote Protocol Framework.</i>
@@ -7,8 +9,7 @@
<p align="center">
<a href="https://github.com/SnowLuma/SnowLuma/releases"><img alt="Release" src="https://img.shields.io/github/v/release/SnowLuma/SnowLuma?label=release&style=flat-square"></a>
<a href="https://github.com/SnowLuma/SnowLuma/actions"><img alt="Build" src="https://img.shields.io/github/actions/workflow/status/SnowLuma/SnowLuma/release.yml?branch=main&style=flat-square&label=build"></a>
<a href="https://www.npmjs.com/package/@snowluma/sdk"><img alt="@snowluma/sdk" src="https://img.shields.io/npm/v/%40snowluma%2Fsdk?style=flat-square&label=%40snowluma%2Fsdk&color=cb3837"></a>
<a href="https://www.npmjs.com/package/@snowluma/ui"><img alt="@snowluma/ui" src="https://img.shields.io/npm/v/%40snowluma%2Fui?style=flat-square&label=%40snowluma%2Fui&color=cb3837"></a>
<a href="https://www.npmjs.com/package/@snowluma/sdk"><img alt="NPM" src="https://img.shields.io/npm/v/%40snowluma%2Fsdk?style=flat-square&label=sdk&color=cb3837"></a>
<a href="https://github.com/SnowLuma/SnowLuma/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/SnowLuma/SnowLuma?style=flat-square"></a>
</p>
@@ -21,111 +22,39 @@
---
## 简介
SnowLuma 是一个基于 TypeScript 的协议转换框架,旨在为 QQ 客户端提供 [OneBot v11](https://github.com/botuniverse/onebot-11) 标准接口,支持 WebSocket/HTTP 适配、多账号并行及 WebUI 管理。
SnowLuma 在 QQ 客户端与生态侧之间承担协议转换工作,向上以 [OneBot v11](https://github.com/botuniverse/onebot-11) 标准协议暴露能力。Bridge 层负责会话与事件枢纽,再通过 WebSocket / HTTP / WebUI 等多种适配器对外提供接入。
项目持续迭代中,稳定版本通过 [Releases](https://github.com/SnowLuma/SnowLuma/releases) 发布。
> ⚠️ **免责声明**:SnowLuma 是独立的第三方互操作项目,**与腾讯 / QQ 无任何隶属或授权关系**。本项目**仅供学习与技术研究**,请遵守《QQ 用户协议》及适用法律;软件按"现状"提供、不附带任何担保,使用风险自负。详见 [`EULA.md`](EULA.md)。
>
> ⚠️ **Disclaimer**: SnowLuma is an independent, third-party interoperability project with **no affiliation with or endorsement by Tencent / QQ**, provided **for study and research only**, "as is" without warranty. Comply with the QQ User Agreement and applicable law; use at your own risk. See [`EULA.md`](EULA.md).
## 特性
- **OneBot v11 兼容** —— 涵盖文本、图片、视频、语音、合并转发、戳一戳、Markdown、JSON、XML 等常用消息段。
- **多账号并行** —— 同一进程可同时托管多个 QQ 账号,会话彼此独立。
- **多种适配器** —— WebSocket Server / WebSocket Client / HTTP Server / HTTP Post,HTTP 服务端同时支持 `application/json` 与 `application/x-www-form-urlencoded`。
- **WebUI 管理面板** —— 浏览器登录、密码强度校验、登录限流、SSE 实时日志、配置热更新。
- **TypeScript 全链路** —— Bridge / OneBot / SDK / UI 均使用 TypeScript,发布到 npm 的 `@snowluma/sdk` 与 `@snowluma/ui` 可直接供下游应用消费。
- **数据持久化** —— 好友、群、群成员等关系数据落 SQLite,跨重启可用。
- **OneBot v11 兼容**:支持文本、音视频、Markdown、JSON 等消息格式。
- **高性能架构**:TypeScript 全栈,基于 pnpm monorepo 管理,核心逻辑分离。
- **现代化管理**:内置 WebUI 面板,支持实时日志、密码热更、多账号管理。
- **多适配器支持**:WebSocket (Server/Client)、HTTP (Server/Post)。
- **数据持久化**:使用 SQLite 存储好友、群组等关系数据。
## 快速开始
下载预构建发布包:
1. 从 [Releases](https://github.com/SnowLuma/SnowLuma/releases) 下载最新发布包并解压。
2. 运行 `./launcher.bat` (Windows) 或 `./launcher.sh` (Linux)。
3. 访问 `http://localhost:5099` (初始账号 `admin`,密码见控制台输出)。
```bash
# 从 Releases 下载 zip,解压到任意目录
./launcher.bat # Windows
```
## 许可 / License
或从源码开发:
SnowLuma 采用 **源码可见非商业许可(SnowLuma Source-Available Non-Commercial License)**,见 [`LICENSE`](LICENSE)。**这不是 OSI 开源许可**:源码公开供查看、学习与非商业自托管,但**禁止任何商业使用**(出售、转售、付费托管 / 代搭 / 代运营等),公开发布修改版须事先书面授权。随附的原生附加组件(`snowluma-*.node` 等)为专有组件,不在本许可范围内。二进制发行包另受 [`EULA.md`](EULA.md) 约束;商业授权请联系 motricseven@foxmail.com。参与贡献请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
```bash
git clone https://github.com/SnowLuma/SnowLuma.git
cd SnowLuma
pnpm install
pnpm build
pnpm start
```
WebUI 默认监听 `5099` 端口。首次启动会在控制台打印 `initial credentials: user=admin password=<...>`,登录后请立即修改。
若未完成首次改密就关闭进程,下次启动会自动重新生成一个新的随机密码。
## 工作区
本仓库使用 pnpm monorepo 管理,各包职责如下:
| 包 | 说明 |
| --- | --- |
| [`@snowluma/core`](packages/core) | 核心:协议层 / Bridge / OneBot / WebUI 全部在此。 |
| [`@snowluma/sdk`](packages/sdk) | OneBot HTTP & WebSocket TypeScript SDK,发布到 npm。 |
| [`@snowluma/ui`](packages/ui) | Tailwind 4 共享组件库(shadcn 风格),发布到 npm。 |
| [`@snowluma/websocket`](packages/websocket) | OneBot WebSocket 适配器底层。 |
| [`@snowluma/proton`](packages/proton) | 编译期 protobuf 编/解码器生成器:TS interface 标注 `pb<N, T>`,Vite 插件在构建时把 `protobuf_encode<T>` / `protobuf_decode<T>` 替换为内联 codec,零运行时反射。 |
| [`@snowluma/runtime`](packages/runtime) | 运行时清单与发布包资源。 |
| [`webui`](packages/webui) | Web 管理面板前端。 |
## 架构
```mermaid
flowchart TD
A([QQ 客户端])
B["协议层<br/><sub>packet pipeline · cmd 分派</sub>"]
C["Bridge 层<br/><sub>会话调度 · 花名册缓存 · 消息发送</sub>"]
D["OneBot 层<br/><sub>Event Converter · Action Handler</sub>"]
E([WS / HTTP / WebUI])
A --> B --> C --> D --> E
```
## 文档
- [路线图](RoadMap.md)
- [贡献指南](CONTRIBUTING.md)
- [行为准则](CODE_OF_CONDUCT.md)
## 开发命令
```bash
pnpm dev # 启动 core dev server
pnpm dev:web # 启动 webui dev server
pnpm test # 运行 core 测试
pnpm typecheck # 全仓库 type check
pnpm build:all # 构建 core + sdk + webui
```
SnowLuma is under a **source-available, non-commercial** license (see [`LICENSE`](LICENSE)) — **NOT** an OSI open-source license. The source is published for study and non-commercial self-hosting; **commercial use is prohibited** without prior written permission, and the bundled native addon (`snowluma-*.node`) is proprietary and not covered by this license.
## 鸣谢
- [LagrangeV2](https://github.com/LagrangeDev/LagrangeV2) —— Proto 定义参考。
- [NapCatQQ](https://github.com/NapNeko/NapCatQQ) —— Scanner 与 Packet 处理实现参考。
参考了 [LagrangeV2](https://github.com/LagrangeDev/LagrangeV2) 的协议定义与 [NapCatQQ](https://github.com/NapNeko/NapCatQQ) 的实现思路。
## 贡献者
---
感谢每一位为 SnowLuma 提交过代码的伙伴。
<p align="center">
<a href="https://github.com/SnowLuma/SnowLuma/graphs/contributors"><img src="https://contrib.rocks/image?repo=SnowLuma/SnowLuma" /></a>
</p>
<a href="https://github.com/SnowLuma/SnowLuma/graphs/contributors">
<img src="https://contrib.rocks/image?repo=SnowLuma/SnowLuma" alt="Contributors" />
</a>
## Star 趋势
<a href="https://star-history.com/#SnowLuma/SnowLuma&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=SnowLuma/SnowLuma&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=SnowLuma/SnowLuma&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=SnowLuma/SnowLuma&type=Date" />
</picture>
</a>
## 社区
- QQ 群:[SnowLuma-QQ](https://qm.qq.com/q/g3UMLpWALe)
- Telegram:[SnowLuma-TG](https://t.me/napcatqq)
- 问题反馈:[GitHub Issues](https://github.com/SnowLuma/SnowLuma/issues)

View File

@@ -1,6 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "snowluma-monorepo",
"version": "1.9.2",
"version": "1.11.2",
"description": "SnowLuma monorepo workspace (pnpm)",
"private": true,
"type": "module",
@@ -8,12 +9,16 @@
"build": "pnpm --filter @snowluma/core build",
"build:sdk": "pnpm --filter @snowluma/sdk build",
"build:webui": "pnpm --filter webui build",
"build:all": "pnpm --filter @snowluma/core build:all && pnpm --filter @snowluma/sdk build && pnpm --filter webui build",
"build:mcp": "pnpm --filter @snowluma/mcp build",
"build:all": "pnpm --filter @snowluma/core build:all && pnpm --filter @snowluma/sdk build && pnpm --filter @snowluma/mcp build && pnpm --filter webui build",
"dev": "pnpm --filter @snowluma/core dev",
"dev:mode": "cd dist && cross-env SNOWLUMA_DEV_MODE=1 SNOWLUMA_DEV_WEBUI=1 node index.mjs",
"dev:web": "pnpm --filter webui dev",
"test": "pnpm --filter @snowluma/core test",
"test:watch": "pnpm --filter @snowluma/core test:watch",
"test:common": "pnpm --filter @snowluma/common test",
"test:all": "pnpm -r --if-present test",
"coverage": "pnpm --filter @snowluma/common test -- --coverage",
"typecheck": "pnpm -r --if-present typecheck",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
@@ -42,7 +47,11 @@
},
"onlyBuiltDependencies": [
"better-sqlite3"
]
],
"overrides": {
"esbuild@<0.28.1": "^0.28.1",
"@babel/core@<7.29.6": "^7.29.6"
}
},
"packageManager": "pnpm@10.28.0",
"engines": {

View File

@@ -1,6 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/bridge",
"version": "1.9.2",
"version": "1.11.2",
"private": true,
"type": "module",
"description": "SnowLuma bridge — QQ NT desktop client lifecycle: hook injection (via native addon), per-PID HookSession orchestration, pipe-watcher for process discovery, and the BridgeManagerSink interface that lets the hook layer call back into a UIN-keyed session router without depending on @snowluma/core. Consumed by the top-level app entry (which constructs the BridgeManager from @snowluma/core and injects it as the sink) and by the WebUI server (read-only HookProcessInfo views).",

View File

@@ -6,10 +6,12 @@ import { HookSession, type HookSessionDeps } from './hook-session';
import {
injectHookProcess,
listHookProcesses,
resolveHookNativePath,
unloadHookProcess,
type HookProcessBaseInfo,
} from './injector';
import { PipeWatcher } from './pipe-watcher';
import { createNativeProcessEnumerator, type ProcessEnumerator } from './process-enumerator';
import { QqHookClient } from './qq-hook-client';
import { probeQqLoginInfo, type QqPortLoginInfo } from './qq-port-probe';
import type { HookProcessInfo } from './types';
@@ -49,6 +51,13 @@ export type HookManagerDeps = {
* `loadProcess(pid)` from the watcher's 'process-discovered' handler).
* Failed loads are logged and leave the session in the 'error' state. */
autoLoadOnDiscovery?: boolean;
/** Optional hook fired whenever the set of HookProcessInfo observable to
* `listProcesses()` changes — new process discovered, process gone, or
* any session's status mutated. Used by the WebUI SSE wiring to push a
* fresh processes snapshot to connected clients without REST polling.
* Exceptions thrown by the callback are caught and logged; they do not
* break the watcher / session event loops. */
onSessionsChanged?: () => void;
log?: Logger;
};
@@ -74,8 +83,15 @@ export class HookManager {
private readonly makeClient: HookSessionDeps['makeClient'];
private readonly pipeWatcher: PipeWatcher;
private readonly ownsPipeWatcher: boolean;
private readonly listProcessesNative: () => HookProcessBaseInfo[];
/** Watcher/API process enumeration — isolated + timeout-bounded by default
* so a blocked native /proc walk can't freeze the loop (issue #158).
* Resolves to `null` (UNKNOWN) on timeout/failure. */
private readonly enumerate: () => Promise<HookProcessBaseInfo[] | null>;
/** The owned enumerator (worker lifecycle), or null when a custom lister was
* injected (tests) — nothing to tear down in that case. */
private readonly enumerator: ProcessEnumerator | null;
private readonly autoLoadOnDiscovery: boolean;
private readonly onSessionsChangedRaw?: () => void;
private readonly log: Logger;
private readonly sessions = new Map<number, HookSession>();
private readonly startPromise: Promise<void>;
@@ -85,6 +101,7 @@ export class HookManager {
constructor(deps: HookManagerDeps) {
this.bridgeManager = deps.bridgeManager;
this.onPacket = deps.onPacket ?? ((pkt) => deps.bridgeManager.onPacket(pkt));
this.onSessionsChangedRaw = deps.onSessionsChanged;
this.log = deps.log ?? createLogger('Hook');
this.injector = deps.injector ?? {
@@ -95,15 +112,38 @@ export class HookManager {
},
};
this.makeClient = deps.makeClient ?? ((pid: number) => new QqHookClient(pid));
this.listProcessesNative = deps.listProcesses ?? listHookProcesses;
this.autoLoadOnDiscovery = deps.autoLoadOnDiscovery ?? false;
// A custom lister (tests) is used directly — no worker, no isolation, just
// an async wrap that maps a throw to the UNKNOWN sentinel. The default path
// wraps the native enumerator in a worker with a timeout.
if (deps.listProcesses) {
const lister = deps.listProcesses;
this.enumerator = null;
this.enumerate = async () => {
try {
return await lister();
} catch (error) {
this.log.warn('listProcesses failed: %s', errMsg(error));
return null;
}
};
} else {
this.enumerator = createNativeProcessEnumerator({
addonPath: resolveHookNativePath('node'),
fallbackSync: listHookProcesses,
processName: defaultProcessName(),
log: this.log,
});
this.enumerate = () => this.enumerator!.enumerate();
}
if (deps.pipeWatcher) {
this.pipeWatcher = deps.pipeWatcher;
this.ownsPipeWatcher = false;
} else {
this.pipeWatcher = new PipeWatcher({
listProcesses: this.listProcessesNative,
listProcesses: this.enumerate,
listLivePipes: () => QqHookClient.listLivePipes(),
intervalMs: deps.watcherIntervalMs,
log: this.log,
@@ -119,12 +159,13 @@ export class HookManager {
async listProcesses(): Promise<HookProcessInfo[]> {
await this.startPromise;
let processes: HookProcessBaseInfo[];
try {
processes = this.listProcessesNative();
} catch (error) {
this.log.warn('listProcesses failed: %s', errMsg(error));
processes = [];
const processes = await this.enumerate();
if (processes === null) {
// Enumeration timed out / failed — report the last-known sessions rather
// than an empty list (which the WebUI would render as "no QQ").
return [...this.sessions.values()]
.map((s) => s.toInfo())
.sort((a, b) => a.pid - b.pid);
}
const result: HookProcessInfo[] = [];
for (const proc of processes) {
@@ -172,6 +213,7 @@ export class HookManager {
session.dispose();
}
this.sessions.clear();
this.enumerator?.dispose();
if (this.ownsPipeWatcher) {
this.pipeWatcher.dispose();
}
@@ -193,11 +235,13 @@ export class HookManager {
this.log.warn('auto-load failed: PID=%d err=%s', info.pid, errMsg(err));
});
}
this.notifySessionsChanged();
});
this.pipeWatcher.on('process-gone', (pid: number) => {
if (this.disposed) return;
const session = this.sessions.get(pid);
if (session) session.notifyProcessGone();
this.notifySessionsChanged();
});
this.pipeWatcher.on('pipe-up', (pid: number) => {
if (this.disposed) return;
@@ -253,6 +297,12 @@ export class HookManager {
session.on('disconnected', (wasLoggedIn: boolean) => {
if (wasLoggedIn) this.bridgeManager.onPidDisconnected(pid);
});
// status-changed fires on EVERY internal status mutation, including the
// ones reached via login / disconnected / refresh — subscribing here
// alone covers every transition the WebUI processes view cares about.
session.on('status-changed', () => {
this.notifySessionsChanged();
});
session.on('disposed', () => {
this.sessions.delete(pid);
});
@@ -261,6 +311,19 @@ export class HookManager {
return session;
}
/** Fire the optional sessions-changed hook with exceptions isolated.
* A throwing subscriber must not abort the watcher's emit loop or break
* a HookSession event handler in flight. */
private notifySessionsChanged(): void {
if (this.disposed) return;
if (!this.onSessionsChangedRaw) return;
try {
this.onSessionsChangedRaw();
} catch (err) {
this.log.warn('onSessionsChanged threw: %s', errMsg(err));
}
}
private assertValidPid(pid: number): void {
if (!Number.isInteger(pid) || pid <= 0) throw new Error('invalid pid');
}

View File

@@ -1,17 +1,29 @@
import { createLogger, type Logger } from '@snowluma/common/logger';
import type { PacketSink } from '@snowluma/common/protocol-types';
import { isRealUin } from '@snowluma/common/uin';
import { EventEmitter } from 'events';
import { HookPacketClient } from './hook-packet-client';
import type { HookInjectResult } from './injector';
import type { QqHookClient, QqHookLoginState, QqHookPacket } from './qq-hook-client';
import { probeQqLoginInfo, type QqPortLoginInfo } from './qq-port-probe';
import { statusFor } from './hook-status';
import type { HookProcessInfo, HookProcessStatus } from './types';
/** How often to actively re-probe QQ's login state while connected but not yet
* logged in — the safety net for a login the native hook never pushed (Docker
* auto-login races/bypasses the pushed loginState frame). */
const LOGIN_RECONCILE_INTERVAL_MS = 3000;
export type HookSessionDeps = {
injector: {
inject: (pid: number) => HookInjectResult;
unload: (pid: number, handle: HookInjectResult['handle']) => void;
};
makeClient: (pid: number) => QqHookClient;
/** Active, pipe-independent login probe (reads QQ's ptlogin/deeplink ports).
* Drives the login-reconcile safety net; injectable for tests. Defaults to
* `probeQqLoginInfo`. */
probeLogin?: (pid: number) => Promise<QqPortLoginInfo | null>;
/** Sync fast-path check used by load() to skip re-injection when a
* prior SnowLuma run left a working pipe behind. `tickNow` forces a
* fresh poll — used after unload to dodge the up-to-1500ms cache
@@ -49,6 +61,7 @@ export class HookSession extends EventEmitter {
private readonly injector: HookSessionDeps['injector'];
private readonly makeClient: HookSessionDeps['makeClient'];
private readonly probeLogin: (pid: number) => Promise<QqPortLoginInfo | null>;
private readonly pipeWatcher: HookSessionDeps['pipeWatcher'];
private readonly onPacket: PacketSink | null;
private readonly log: Logger;
@@ -69,12 +82,15 @@ export class HookSession extends EventEmitter {
private bound = false;
private opChain: Promise<unknown> = Promise.resolve();
private disposed = false;
private loginProbeTimer: ReturnType<typeof setInterval> | null = null;
private probing = false;
constructor(pid: number, deps: HookSessionDeps) {
super();
this.pid = pid;
this.injector = deps.injector;
this.makeClient = deps.makeClient;
this.probeLogin = deps.probeLogin ?? probeQqLoginInfo;
this.pipeWatcher = deps.pipeWatcher;
this.onPacket = deps.onPacket ?? null;
this.log = deps.log ?? createLogger('HookSession');
@@ -131,17 +147,7 @@ export class HookSession extends EventEmitter {
if (this.disposed) return;
void this.serialize(async () => {
if (this.disposed) return;
// Adopt a DLL that survived a SnowLuma restart.
if (!this.injected) {
this.injected = true;
if (!this._method) this._method = 'reconnect';
}
if (this.client?.isClosed) this.tearDownClient();
if (!this.connected) {
await this.attemptConnect();
} else {
this.setStatus(this.loggedIn ? 'online' : 'loaded', '');
}
await this.reconcilePipeUp();
}).catch(err => this.log.warn('onPipeUp failed: PID=%d err=%s', this.pid, errMsg(err)));
}
@@ -149,18 +155,7 @@ export class HookSession extends EventEmitter {
if (this.disposed) return;
void this.serialize(async () => {
if (this.disposed) return;
if (!this.connected) {
// Nothing to tear down; just keep status visible.
if (this.injected) this.setStatus('connecting', this._error);
return;
}
const wasLoggedIn = this.loggedIn;
this.tearDownClient();
this.setStatus(
this.injected ? (wasLoggedIn ? 'disconnected' : 'connecting') : 'available',
'',
);
if (wasLoggedIn) this.emit('disconnected', true);
this.reconcilePipeDown();
}).catch(err => this.log.warn('onPipeDown failed: PID=%d err=%s', this.pid, errMsg(err)));
}
@@ -227,10 +222,7 @@ export class HookSession extends EventEmitter {
this._method = this.injectResult.method;
}
}
this.setStatus(
this.connected ? (this.loggedIn ? 'online' : 'loaded') : 'connecting',
'',
);
this.applyStatus();
} catch (error) {
this._error = errMsg(error);
this.setStatus('error', this._error);
@@ -281,24 +273,14 @@ export class HookSession extends EventEmitter {
private async refreshInternal(): Promise<HookProcessInfo> {
this._error = '';
try {
const pipeUp = this.pipeWatcher.isPipeLive(this.pid);
if (pipeUp) {
// Adopt an unknown DLL the same way onPipeUp would.
if (!this.injected) {
this.injected = true;
this._method = this._method || 'reconnect';
}
if (this.client?.isClosed) this.tearDownClient();
if (!this.connected) {
await this.attemptConnect();
} else {
this.setStatus(this.loggedIn ? 'online' : 'loaded', '');
}
// Same pipe-up / pipe-down reconcilers the watcher drives, chosen by
// a fresh poll. This collapses what used to be a hand-copied pair of
// onPipeUp/onPipeDown bodies — and fixes the drift where the down
// branch reported 'disconnected' even for a never-logged-in session.
if (this.pipeWatcher.isPipeLive(this.pid)) {
await this.reconcilePipeUp();
} else {
const wasLoggedIn = this.loggedIn;
this.tearDownClient();
this.setStatus(this.injected ? 'disconnected' : 'available', '');
if (wasLoggedIn) this.emit('disconnected', true);
this.reconcilePipeDown();
}
} catch (error) {
this._error = errMsg(error);
@@ -308,6 +290,55 @@ export class HookSession extends EventEmitter {
return this.toInfo();
}
// ─────────────── settled-status reconcilers ───────────────
/** Push the settled status derived from the live flags. `wasLoggedIn`
* defaults to the current `loggedIn`; callers that just tore the client
* down pass the value captured *before* teardown (teardown clears it). */
private applyStatus(wasLoggedIn: boolean = this.loggedIn, error = ''): void {
this.setStatus(statusFor({
injected: this.injected,
connected: this.connected,
loggedIn: this.loggedIn,
wasLoggedIn,
}), error);
}
/** Pipe is up: adopt a DLL that survived a SnowLuma restart, drop a
* stale client, then (re)connect if needed or just settle the status.
* Shared by onPipeUp and refresh's pipe-up branch. */
private async reconcilePipeUp(): Promise<void> {
if (!this.injected) {
this.injected = true;
if (!this._method) this._method = 'reconnect';
}
if (this.client?.isClosed) this.tearDownClient();
if (!this.connected) {
await this.attemptConnect();
} else {
this.applyStatus();
}
}
/** Pipe is down (or the client closed): tear down, settle the status,
* and emit the disconnect notification iff we owed BridgeManager one
* (i.e. we had reached login). Shared by onPipeDown, refresh's pipe-down
* branch, and the client 'close' handler. */
private reconcilePipeDown(): void {
if (!this.connected) {
// Nothing live to tear down. A session that never connected can't owe
// a disconnect, and we must NOT clobber a diagnostic the failed
// connect/load already set — settle the status keeping `_error`, or
// (when not even injected) leave the status untouched entirely.
if (this.injected) this.applyStatus(this.loggedIn, this._error);
return;
}
const wasLoggedIn = this.loggedIn;
this.tearDownClient();
this.applyStatus(wasLoggedIn);
if (wasLoggedIn) this.emit('disconnected', true);
}
// ─────────────── client plumbing ───────────────
private async attemptConnect(): Promise<void> {
@@ -327,15 +358,26 @@ export class HookSession extends EventEmitter {
try {
await client.connectAll({ recv: true });
this.connected = true;
this.setStatus(client.isLoggedIn ? 'online' : 'loaded', '');
const loginState = client.getLoginState();
if (loginState.loggedIn) this.handleLoginState(loginState);
// handleLoginState owns the connected+loggedIn → 'online' (+ login
// emit) transition; defer to it so the status is set once. Otherwise
// we're connected-but-not-logged-in → 'loaded'.
if (loginState.loggedIn) {
this.handleLoginState(loginState);
} else {
this.applyStatus();
// The native hook only PUSHES a loginState frame on the login edge;
// if QQ logged in before/around connect (Docker auto-login) that edge
// is missed and we'd wait forever. Actively re-probe until logged in.
this.startLoginReconcile();
}
this.log.info('pipe connected: PID=%d', this.pid);
} catch (error) {
this._error = errMsg(error);
// Drop the client so the next attempt builds a fresh socket pair.
// A failed connect was never logged in → 'connecting' (or 'available').
this.tearDownClient();
this.setStatus(this.injected ? 'connecting' : 'available', this._error);
this.applyStatus(false, this._error);
}
}
@@ -355,21 +397,13 @@ export class HookSession extends EventEmitter {
void this.serialize(async () => {
if (this.disposed) return;
if (this.client !== client) return;
const wasLoggedIn = this.loggedIn;
this.tearDownClient();
if (!this.injected) {
this.setStatus('available', '');
} else if (wasLoggedIn) {
this.setStatus('disconnected', '');
} else {
this.setStatus('connecting', '');
}
if (wasLoggedIn) this.emit('disconnected', true);
this.reconcilePipeDown();
}).catch(err => this.log.warn('close reconcile failed: PID=%d err=%s', this.pid, errMsg(err)));
});
}
private tearDownClient(): void {
this.stopLoginReconcile();
const client = this.client;
if (client) {
client.removeAllListeners();
@@ -387,11 +421,18 @@ export class HookSession extends EventEmitter {
const previousUin = this._uin;
this._uin = state.uin || state.uinNumber.toString();
this.loggedIn = state.loggedIn && isRealUin(this._uin);
// However login was observed (pushed frame or the active probe), the
// safety net's job is done.
if (this.loggedIn) this.stopLoginReconcile();
if (this.loggedIn) {
this.setStatus('online', '');
} else if (this.connected) {
this.setStatus('loaded', this._error);
// Only the connected/logged-in states are ours to set here; when fully
// down we leave the status the teardown path already settled.
// Load-bearing invariant: `loggedIn ⇒ connected` (login can only be
// observed on a live client, and teardown clears `loggedIn` before
// `connected`), so statusFor lands 'online' here rather than the
// disconnected/connecting branch.
if (this.connected || this.loggedIn) {
this.applyStatus(wasLoggedIn, this.loggedIn ? '' : this._error);
}
if (!this.loggedIn || !this.sender) return;
@@ -401,6 +442,55 @@ export class HookSession extends EventEmitter {
this.log.success('login detected: PID=%d UIN=%s', this.pid, this._uin);
}
// ─────────────── login reconcile (Docker auto-login safety net) ───────────
// The hook's loginState frame is edge-triggered (pushed only when the native
// observes the login transition). When that edge is missed — QQ auto-logged
// in before connect, or a silent session-restore path the hook doesn't
// intercept — we'd sit at 'loaded'/'connecting' forever. So while connected
// but not logged in, actively re-probe QQ's own ports and synthesize the
// login once it reports a real uin. Idempotent with the pushed-frame path
// (handleLoginState's wasLoggedIn guard dedups the 'login' emit).
private startLoginReconcile(): void {
if (this.loginProbeTimer || this.disposed) return;
void this.probeLoginOnce(); // immediate — catch already-logged-in fast
this.loginProbeTimer = setInterval(() => void this.probeLoginOnce(), LOGIN_RECONCILE_INTERVAL_MS);
this.loginProbeTimer.unref?.();
}
private stopLoginReconcile(): void {
if (this.loginProbeTimer) {
clearInterval(this.loginProbeTimer);
this.loginProbeTimer = null;
}
}
private async probeLoginOnce(): Promise<void> {
// A port-scan probe can outlast the interval; skip overlapping ticks so a
// slow probe never stacks concurrent subprocess-spawning scans.
if (this.probing) return;
if (this.disposed || !this.connected || this.loggedIn) { this.stopLoginReconcile(); return; }
this.probing = true;
try {
let info: QqPortLoginInfo | null;
try {
info = await this.probeLogin(this.pid);
} catch {
return; // best-effort; the interval retries
}
// The await yielded — re-check we still want this before mutating state.
if (this.disposed || !this.connected || this.loggedIn) { this.stopLoginReconcile(); return; }
if (info?.loggedIn && isRealUin(info.uin)) {
this.log.info('login reconciled via active probe: PID=%d UIN=%s', this.pid, info.uin);
// isRealUin guarantees a pure non-empty digit string, so BigInt() here
// cannot throw (keep that contract if isRealUin's regex is ever changed).
this.handleLoginState({ loggedIn: true, uin: info.uin, uinNumber: BigInt(info.uin) });
}
} finally {
this.probing = false;
}
}
private handlePacket(packet: QqHookPacket): void {
if (!this.loggedIn) return;
const uin = packet.uin || this._uin;
@@ -429,11 +519,6 @@ export class HookSession extends EventEmitter {
}
}
function isRealUin(uin: string): boolean {
if (!uin || uin === '0') return false;
return /^\d+$/.test(uin) && uin.length >= 5;
}
function errMsg(value: unknown): string {
return value instanceof Error ? value.message : String(value);
}

View File

@@ -0,0 +1,31 @@
import type { HookProcessStatus } from './types';
/**
* The flags that fully determine a HookSession's *settled* status.
* `wasLoggedIn` carries the one bit of history the derivation needs:
* on ANY injected-but-not-connected path (connect failure, pipe close,
* refresh-while-down), the session reads `disconnected` only if it had
* reached login, otherwise it's still `connecting`. Capture it from
* `loggedIn` *before* tearing the client down, since teardown clears it.
*/
export interface HookFlags {
injected: boolean;
connected: boolean;
loggedIn: boolean;
wasLoggedIn: boolean;
}
/**
* Single source of truth for the five *settled* HookProcessStatus values
* — `available` / `connecting` / `loaded` / `online` / `disconnected`.
*
* Pure: status is a function of the flags alone. The two *out-of-band*
* states `loading` (injection in flight) and `error` (carries a message)
* are set explicitly by HookSession and are deliberately NOT derivable
* here.
*/
export function statusFor(flags: HookFlags): HookProcessStatus {
if (!flags.injected) return 'available';
if (flags.connected) return flags.loggedIn ? 'online' : 'loaded';
return flags.wasLoggedIn ? 'disconnected' : 'connecting';
}

View File

@@ -2,6 +2,8 @@ import { existsSync } from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
import { listSnowlumaPipePidsSync } from './qq-hook-client';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
export interface ManualMapHandle {
@@ -98,6 +100,17 @@ export function getNativeHookLoadError(): string | null {
}
export function listHookProcesses(): HookProcessBaseInfo[] {
// macOS: no native enumerate-QQ addon. The DYLD_INSERT injection model
// means QQ ran with our dylib already mapped, so the dylib's listener
// socket IS the discovery signal. Treat every `mojo.<pid>.control.sock`
// in the runtime dir as a known process (the watcher's subsequent
// connectable-probe gates the pipe-up emit, so a stale dangling socket
// here doesn't drive a false connect).
if (process.platform === 'darwin') {
return [...listSnowlumaPipePidsSync()]
.sort((a, b) => a - b)
.map(pid => ({ pid, name: defaultProcessName(), path: '' }));
}
const addon = getNativeHookAddon();
if (!addon) return [];
return [...new Set(addon.getAllMainProcess())]

View File

@@ -6,8 +6,11 @@ const DEFAULT_INTERVAL_MS = 1500;
const MIN_INTERVAL_MS = 250;
export type PipeWatcherDeps = {
/** Native: list QQ.exe processes currently running. */
listProcesses: () => HookProcessBaseInfo[];
/** Native: list QQ.exe processes currently running. May be async and may
* return `null` (UNKNOWN) when enumeration timed out / failed — in which
* case this tick keeps the prior process+pipe state instead of treating the
* missing data as "everything disappeared" (issue #158). */
listProcesses: () => HookProcessBaseInfo[] | null | Promise<HookProcessBaseInfo[] | null>;
/** Native: PIDs that currently have a live SnowLuma named pipe. */
listLivePipes: () => Promise<Set<number>>;
/** Polling interval in ms. Defaults to 1500, floored to 250. */
@@ -138,12 +141,22 @@ export class PipeWatcher extends EventEmitter {
}
this.ticking = true;
try {
let processes: HookProcessBaseInfo[];
let processes: HookProcessBaseInfo[] | null;
try {
processes = this.listProcesses();
processes = await this.listProcesses();
} catch (error) {
this.log.warn('listProcesses failed: %s', errMsg(error));
processes = [];
processes = null;
}
// UNKNOWN (timeout / failure): keep the prior process + pipe snapshot.
// Treating missing data as "everything disappeared" would fire
// process-gone for every live PID and dispose healthy sessions — the
// freeze-then-teardown footgun behind issue #158. Still emit 'tick' so
// the manager's per-tick reconnect retries keep running off last-known
// live pipes.
if (processes === null) {
this.emit('tick');
return;
}
let livePipes: Set<number>;
try {

View File

@@ -0,0 +1,238 @@
import { createLogger, type Logger } from '@snowluma/common/logger';
import { Worker } from 'worker_threads';
import type { HookProcessBaseInfo } from './injector';
/**
* Isolated, timeout-bounded wrapper around the native `getAllMainProcess()`
* enumeration.
*
* Why this exists (issue #158): the watcher polls QQ processes every ~1.5s by
* calling the synchronous native enumerator, which walks `/proc` and reads each
* candidate's `cmdline`/`maps`. Those reads go through the target's mm and
* BLOCK while a process is mid-`exec()` — exactly what happens when QQ runs a
* silent hot-update and the process table churns. A blocked synchronous native
* call freezes the whole Node event loop: OneBot stops responding, the watcher
* stops ticking, reconnect logic never runs. The process stays "alive" so the
* supervisor never restarts it — the bot just goes silent.
*
* The only way to put a real timeout on a synchronous native call is to run it
* off the main thread. We run it in a worker; the main thread races the result
* against a deadline. On timeout the main loop keeps going (it returns the
* UNKNOWN sentinel `null`, which the watcher treats as "no fresh data, keep
* prior state" — crucially NOT "all processes gone"). The blocked worker is
* abandoned (a fresh one is spawned next time); it exits on its own once the
* native call finally returns.
*
* Graceful degradation: if the native addon can't be loaded in a worker (e.g.
* it isn't context-aware) or there's no addon at all (macOS reads sockets, not
* `/proc`), we fall back to calling `fallbackSync` on the main thread — i.e.
* exactly today's behaviour, no worse.
*/
export interface ProcessEnumerator {
/** Resolve to the process list, or `null` (UNKNOWN) when enumeration timed
* out / failed and the caller should keep its prior state. */
enumerate(): Promise<HookProcessBaseInfo[] | null>;
dispose(): void;
}
export interface NativeEnumeratorDeps {
/** Resolved path to the hook `.node` addon, or null when there is none
* (macOS / missing) — in which case we never spawn a worker. */
addonPath: string | null;
/** Synchronous lister used when worker isolation is unavailable. Returns
* today's value (and may itself block — that's the no-worse-than-before
* fallback). */
fallbackSync: () => HookProcessBaseInfo[];
/** Display name stamped on each returned process (e.g. 'qq' / 'QQ.exe'). */
processName: string;
/** Per-enumeration deadline. Default 4000ms — comfortably above a healthy
* enumeration (single-digit ms) but well under a human "is it dead?". */
timeoutMs?: number;
/** Cap on abandoned (blocked) workers before we stop spawning more and just
* return UNKNOWN until they drain. Bounds thread growth across a long
* hot-update window. Default 4. */
maxOrphans?: number;
log?: Logger;
}
const DEFAULT_TIMEOUT_MS = 4000;
const DEFAULT_MAX_ORPHANS = 4;
// Worker body (CommonJS — eval workers default to CJS so `require` is available;
// `process.dlopen` is a global and needs no module system). Loads the addon
// handed in via workerData, then answers each 'enumerate' with the raw pid list
// from the blocking native call. All the cheap post-processing stays on main.
const WORKER_SOURCE = `
const { parentPort, workerData } = require('node:worker_threads');
let addon = null;
try {
const mod = { exports: {} };
process.dlopen(mod, workerData.addonPath);
addon = mod.exports;
} catch (e) {
parentPort.postMessage({ type: 'fatal', error: String((e && e.message) || e) });
}
if (addon) {
parentPort.on('message', (msg) => {
if (!msg || msg.type !== 'enumerate') return;
try {
const pids = addon.getAllMainProcess();
parentPort.postMessage({ type: 'result', id: msg.id, pids: Array.from(pids) });
} catch (e) {
parentPort.postMessage({ type: 'error', id: msg.id, error: String((e && e.message) || e) });
}
});
parentPort.postMessage({ type: 'ready' });
}
`;
function mapPids(pids: number[], processName: string): HookProcessBaseInfo[] {
return [...new Set(pids)]
.filter((pid) => Number.isInteger(pid) && pid > 0)
.sort((a, b) => a - b)
.map((pid) => ({ pid, name: processName, path: '' }));
}
export function createNativeProcessEnumerator(deps: NativeEnumeratorDeps): ProcessEnumerator {
const log = deps.log ?? createLogger('ProcessEnumerator');
const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
const maxOrphans = deps.maxOrphans ?? DEFAULT_MAX_ORPHANS;
// No addon to isolate (macOS / missing) → never spawn a worker; the sync
// fallback there is a cheap socket read, not a /proc walk.
if (!deps.addonPath) {
return {
async enumerate() {
try {
return deps.fallbackSync();
} catch (err) {
log.warn('enumerate fallback failed: %s', errMsg(err));
return null;
}
},
dispose() { /* nothing to tear down */ },
};
}
const addonPath = deps.addonPath;
let worker: Worker | null = null;
/** Set once we learn the addon can't load in a worker — permanent fallback. */
let isolationBroken = false;
let orphans = 0;
let seq = 0;
const pending = new Map<number, { resolve: (pids: number[] | null) => void }>();
let disposed = false;
const spawnWorker = (): void => {
const w = new Worker(WORKER_SOURCE, { eval: true, workerData: { addonPath } });
worker = w;
w.on('message', (msg: { type: string; id?: number; pids?: number[]; error?: string }) => {
if (msg.type === 'ready') return;
if (msg.type === 'fatal') {
// The addon won't load off-thread — give up on isolation for good and
// fall back to the synchronous path from here on. Resolve any in-flight
// request now (UNKNOWN) so it doesn't sit waiting for the timeout.
log.warn('process enumeration cannot be isolated (addon load failed in worker): %s — falling back to in-loop enumeration', msg.error ?? '');
isolationBroken = true;
for (const { resolve } of pending.values()) resolve(null);
pending.clear();
teardownWorker();
return;
}
if ((msg.type === 'result' || msg.type === 'error') && typeof msg.id === 'number') {
const entry = pending.get(msg.id);
if (!entry) return;
pending.delete(msg.id);
entry.resolve(msg.type === 'result' ? (msg.pids ?? []) : null);
}
});
w.on('error', (err) => {
log.warn('enumeration worker error: %s', errMsg(err));
if (worker === w) teardownWorker();
});
};
const teardownWorker = (): void => {
const w = worker;
worker = null;
if (!w) return;
// terminate() can't preempt a thread blocked in the native call; it takes
// effect once the call returns. Track it as an orphan until it actually
// exits so we can bound how many we let pile up.
orphans += 1;
w.once('exit', () => { orphans = Math.max(0, orphans - 1); });
void w.terminate().catch(() => { /* already gone */ });
};
const syncFallback = (): HookProcessBaseInfo[] | null => {
try {
return deps.fallbackSync();
} catch (err) {
log.warn('enumerate sync fallback failed: %s', errMsg(err));
return null;
}
};
return {
async enumerate(): Promise<HookProcessBaseInfo[] | null> {
if (disposed || isolationBroken) return syncFallback();
if (!worker) {
if (orphans >= maxOrphans) {
// Too many blocked workers already piling up (a sustained hang) —
// don't spawn more; report UNKNOWN and let them drain.
return null;
}
spawnWorker();
}
const w = worker;
if (!w) return syncFallback();
const id = ++seq;
const resultPromise = new Promise<number[] | null>((resolve) => {
pending.set(id, { resolve });
});
try {
w.postMessage({ type: 'enumerate', id });
} catch (err) {
pending.delete(id);
log.warn('failed to post enumerate request: %s', errMsg(err));
teardownWorker();
return syncFallback();
}
let timer: NodeJS.Timeout | undefined;
const timeout = new Promise<'timeout'>((resolve) => {
timer = setTimeout(() => resolve('timeout'), timeoutMs);
});
const outcome = await Promise.race([resultPromise, timeout]);
if (timer) clearTimeout(timer);
if (outcome === 'timeout') {
pending.delete(id);
log.warn('process enumeration timed out after %dms (worker abandoned) — keeping prior process set', timeoutMs);
teardownWorker();
return null;
}
if (outcome === null) {
// Native call threw inside the worker — treat as a transient failure,
// keep prior state rather than nuking every session.
return null;
}
return mapPids(outcome, deps.processName);
},
dispose() {
disposed = true;
for (const { resolve } of pending.values()) resolve(null);
pending.clear();
const w = worker;
worker = null;
if (w) void w.terminate().catch(() => { /* ignore */ });
},
};
}
function errMsg(value: unknown): string {
return value instanceof Error ? value.message : String(value);
}

View File

@@ -1,5 +1,5 @@
import { EventEmitter } from 'events';
import { promises as fs } from 'fs';
import { readdirSync, promises as fs } from 'fs';
import net from 'net';
import os from 'os';
import path from 'path';
@@ -85,12 +85,59 @@ interface PendingAck {
wantReply: boolean;
}
/**
* Sync directory scan for `mojo.<pid>.control.sock` socket files in the
* runtime dir, returning the pid set. Used by the darwin path of
* `listHookProcesses()` — on macOS the DYLD_INSERT injection model means
* there is no native enumerate-QQ-processes addon; the existence of our
* dylib's listener socket IS the proof that a QQ process is hooked. The
* sync variant is needed because the watcher's `listProcesses` dep is sync.
*
* Mirrors `listLiveLinuxPipePids` (the async + connectable-probe variant)
* but skips the connectable probe — the existence of the socket file is
* sufficient signal for "process exists with our dylib mapped". The async
* variant still gates the subsequent `pipe-up` emit via a real connect.
*/
export function listSnowlumaPipePidsSync(
runtimeDir = linuxRuntimeDir(),
): Set<number> {
const result = new Set<number>();
let names: string[];
try {
names = readdirSync(runtimeDir);
} catch {
return result;
}
for (const name of names) {
const m = /^mojo\.(\d+)\.control\.sock$/i.exec(name);
if (!m) continue;
const pid = Number(m[1]);
if (Number.isInteger(pid) && pid > 0) result.add(pid);
}
return result;
}
function linuxRuntimeDir(): string {
// Name kept for historical reasons (the function predates the macOS port);
// applies to every non-win32 platform. The fallback order mirrors each
// platform hook's runtime_dir(): explicit override first, then the OS-
// native ephemeral-dir convention.
const explicit = process.env.SNOWLUMA_HOOK_RUNTIME_DIR;
if (explicit && explicit.length > 0) return explicit;
const xdg = process.env.XDG_RUNTIME_DIR;
if (xdg && xdg.length > 0) return xdg;
// Mirrors hook_stub.cpp runtime_dir() fallback.
// macOS: dylib defaults to "$TMPDIR/snowluma-hook" (apps/qq/macos/
// qq_hook_dylib.cpp's runtime_dir()). $TMPDIR is per-user on macOS
// (under /var/folders/.../T) so this is the right place — Linux's
// /tmp/snowluma-<uid> doesn't exist on a stock Mac.
if (process.platform === 'darwin') {
const tmpdir = process.env.TMPDIR;
if (tmpdir && tmpdir.length > 0) {
const trimmed = tmpdir.endsWith('/') ? tmpdir.slice(0, -1) : tmpdir;
return path.join(trimmed, 'snowluma-hook');
}
}
// Linux fallback: mirrors hook_stub.cpp runtime_dir() last-resort.
// process.geteuid is POSIX-only; cast to allow non-Linux type checks.
const uid = typeof process.geteuid === 'function' ? process.geteuid() : os.userInfo().uid;
return `/tmp/snowluma-${uid}`;
@@ -465,6 +512,12 @@ export class QqHookClient extends EventEmitter {
});
const ackDeferred = createDeferred<{ requestId: number; wantReply: boolean }>();
// Always attach a handler so a rejection can never become "unhandled" (which
// crashes Node). When the pipe closes, rejectControlPending() rejects every
// pending deferred — but the reply is only `await`ed AFTER the ack, so if the
// ack fails first the reply promise is rejected with NO awaiter. The real
// `await` below still observes the value/rejection (a separate continuation).
ackDeferred.promise.catch(() => { /* observed by the await, or harmless */ });
this.pendingAcks.set(requestId, {
resolve: ackDeferred.resolve,
reject: ackDeferred.reject,
@@ -474,6 +527,7 @@ export class QqHookClient extends EventEmitter {
let replyDeferred: Deferred<QqHookSendReply> | null = null;
if (wantReply) {
replyDeferred = createDeferred<QqHookSendReply>();
replyDeferred.promise.catch(() => { /* see note above — prevents unhandled rejection */ });
this.pendingReplies.set(requestId, replyDeferred);
}

View File

@@ -1,5 +1,6 @@
import { exec } from 'child_process';
import net from 'net';
import https from 'https';
import { promisify } from 'util';
const execAsync = promisify(exec);
@@ -8,6 +9,13 @@ const PORT_RANGE_START = 9210;
const PORT_RANGE_END = 9219;
const PROBE_TIMEOUT_MS = 1000;
const CONNECTION_TIMEOUT_MS = 500;
// QQ's Ptlogin quick-login ports plus its main process mean a single
// logged-in client surfaces roughly this many processes. When no usable
// probe port is found, a count BELOW this implies the target PID is still at
// the login screen; AT/ABOVE it the environment is ambiguous (multiple or
// unrelated `qq` processes), so we fall through to deep-link probing rather
// than guess "logged out".
const LOGGED_OUT_PROCESS_COUNT_MAX = 6;
export interface QqPortLoginInfo {
port: number;
@@ -42,6 +50,7 @@ function decodeJwt(token: string): JwtPayload | null {
}
}
async function probePort(port: number): Promise<QqPortLoginInfo | null> {
return new Promise((resolve) => {
const client = new net.Socket();
@@ -108,6 +117,93 @@ async function probePort(port: number): Promise<QqPortLoginInfo | null> {
});
}
/** One entry of the Ptlogin `pt_get_uins` JSONP array. Only the fields the
* probe reads are modelled; QQ sends more but they're irrelevant here. */
interface PtloginUin {
uin?: string | number;
account?: string | number;
nickname?: string;
}
async function fetchPtlogin(port: number): Promise<PtloginUin[]> {
return new Promise((resolve) => {
const url = `https://127.0.0.1:${port}/pt_get_uins?callback=ptui_getuins_CB&pt_local_tk=0`;
const req = https.get(
url,
{
headers: {
Host: 'localhost.ptlogin2.qq.com',
Referer: 'https://xui.ptlogin2.qq.com/',
Cookie: 'pt_local_token=0',
},
rejectUnauthorized: false, // 忽略本地自签证书报错
timeout: CONNECTION_TIMEOUT_MS,
},
(res) => {
let text = '';
res.on('data', (chunk) => { text += chunk.toString(); });
res.on('end', () => {
try {
// 100% 复刻 Python 切片逻辑:获取两个方括号中间的字符串,再包装成数组
const inner = text.split('[')[1].split(']')[0];
const data = JSON.parse('[' + inner + ']') as PtloginUin[];
resolve(data);
} catch {
resolve([]);
}
});
}
);
req.on('error', () => resolve([]));
req.on('timeout', () => {
req.destroy();
resolve([]);
});
});
}
async function tryPtloginMethod(port: number): Promise<QqPortLoginInfo | 'fallback'> {
// 抽象的 QQNT
const res1 = await fetchPtlogin(port);
const res2 = await fetchPtlogin(port);
const target = res1.length < res2.length ? res1 : res2;
if (target.length === 1) {
const account = target[0];
return {
port,
uin: String(account.uin || account.account || ''),
nickName: account.nickname || '',
loggedIn: true,
};
}
// Any non-1 result — the 2+0 alternation, both-2, both-empty, etc. — is
// inconclusive; hand off to the deep-link / process-count fallback.
return 'fallback';
}
async function getQqProcessCount(): Promise<number> {
try {
if (process.platform === 'win32') {
const { stdout } = await execAsync('tasklist /fi "imagename eq QQ.exe" /nh');
return stdout.toLowerCase().split('\n').filter(line => line.includes('qq.exe')).length;
} else {
const { stdout } = await execAsync('pgrep -c qq');
return parseInt(stdout.trim(), 10) || 0;
}
} catch {
// On failure report the ambiguous threshold so we never falsely
// conclude "logged out".
return LOGGED_OUT_PROCESS_COUNT_MAX;
}
}
async function getProcessPorts(pid: number): Promise<number[]> {
try {
if (process.platform === 'win32') {
@@ -119,13 +215,11 @@ async function getProcessPorts(pid: number): Promise<number[]> {
if (parts.length < 5) continue;
const owningPid = parts[parts.length - 1];
if (owningPid !== String(pid)) continue;
const localAddr = parts[1];
const portMatch = localAddr.match(/:(\d+)$/);
if (!portMatch) continue;
const port = Number(portMatch[1]);
if (port >= PORT_RANGE_START && port <= PORT_RANGE_END) {
ports.add(port);
}
ports.add(Number(portMatch[1]));
}
return Array.from(ports);
} else {
@@ -135,10 +229,7 @@ async function getProcessPorts(pid: number): Promise<number[]> {
for (const line of lines) {
const match = line.match(/:(\d+)\s/);
if (match) {
const port = Number(match[1]);
if (port >= PORT_RANGE_START && port <= PORT_RANGE_END) {
ports.add(port);
}
ports.add(Number(match[1]));
}
}
return Array.from(ports);
@@ -148,18 +239,41 @@ async function getProcessPorts(pid: number): Promise<number[]> {
}
}
export async function probeQqLoginInfo(pid: number): Promise<QqPortLoginInfo | null> {
const ports = await getProcessPorts(pid);
if (ports.length === 0) {
for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
const info = await probePort(port);
if (info) return info;
const totalPids = await getQqProcessCount();
if (totalPids < LOGGED_OUT_PROCESS_COUNT_MAX) {
return { port: 0, uin: '', loggedIn: false };
}
return null;
}
for (const port of ports) {
const PT_PORTS = [4301, 4303, 4305, 4307, 4309];
const matchedPtPorts = ports.filter(p => PT_PORTS.includes(p));
if (matchedPtPorts.length > 0) {
for (const port of matchedPtPorts) {
const ptResult = await tryPtloginMethod(port);
if (ptResult !== 'fallback') {
return ptResult;
}
}
} else {
const totalPids = await getQqProcessCount();
if (totalPids < LOGGED_OUT_PROCESS_COUNT_MAX) {
return {
port: ports[0] || 0,
uin: '',
loggedIn: false,
};
}
}
const deepLinkPorts = ports.filter(p => p >= PORT_RANGE_START && p <= PORT_RANGE_END);
for (const port of deepLinkPorts) {
const info = await probePort(port);
if (info) return info;
}

View File

@@ -0,0 +1,173 @@
import { describe, it, expect, vi } from 'vitest';
import { EventEmitter } from 'events';
import { HookManager } from '../src/hook-manager';
import { PipeWatcher } from '../src/pipe-watcher';
import type { ManualMapHandle } from '../src/injector';
import type { BridgeManagerSink } from '../src/hook-manager';
import type { QqHookClient } from '../src/qq-hook-client';
// Regression cover for the WebUI SSE wiring: HookManager must call its
// optional `onSessionsChanged` callback every time the observable set of
// HookProcessInfo (what `listProcesses()` would return) changes, so the
// /api/state/stream handler can push a fresh processes snapshot to the
// browser without REST polling.
const DUMMY_HANDLE: ManualMapHandle = { base: 0n, entry: 0n, exceptionTable: 0n, size: 0 };
const flush = () => new Promise<void>(r => setImmediate(r));
interface Harness {
manager: HookManager;
pipeWatcher: PipeWatcher;
setProcesses: (next: number[]) => void;
setLivePipes: (next: number[]) => void;
onSessionsChanged: ReturnType<typeof vi.fn>;
clientFactory: ReturnType<typeof vi.fn>;
}
function makeManager(opts: { processes?: number[]; livePipes?: number[] } = {}): Harness {
let pids = opts.processes ?? [];
let live = new Set<number>(opts.livePipes ?? []);
const pipeWatcher = new PipeWatcher({
listProcesses: () => pids.map(pid => ({ pid, name: 'qq', path: '' })),
listLivePipes: async () => new Set(live),
intervalMs: 60_000,
});
const clientFactory = vi.fn(() => {
const c = new EventEmitter() as EventEmitter & Partial<QqHookClient>;
(c as any).isClosed = false;
(c as any).isLoggedIn = false;
(c as any).getLoginState = () => ({ loggedIn: false, uin: '0', uinNumber: 0n });
(c as any).connectAll = async () => { /* succeed without doing anything */ };
(c as any).close = () => { (c as any).isClosed = true; };
return c as unknown as QqHookClient;
});
const bridgeManager = {
onPacket: vi.fn(),
onHookLogin: vi.fn(),
onPidDisconnected: vi.fn(),
} as unknown as BridgeManagerSink;
const onSessionsChanged = vi.fn();
const manager = new HookManager({
bridgeManager,
pipeWatcher,
injector: {
inject: vi.fn(() => ({ method: 'loadModuleManual' as const, handle: DUMMY_HANDLE })),
unload: vi.fn(),
},
makeClient: clientFactory,
listProcesses: () => pids.map(pid => ({ pid, name: 'qq', path: '' })),
onSessionsChanged,
});
return {
manager,
pipeWatcher,
onSessionsChanged,
clientFactory,
setProcesses: (next) => { pids = next; },
setLivePipes: (next) => { live = new Set(next); },
};
}
describe('HookManager.onSessionsChanged', () => {
it('fires when the watcher discovers a new QQ process', async () => {
const ctx = makeManager({ processes: [] });
await ctx.pipeWatcher.start();
expect(ctx.onSessionsChanged).not.toHaveBeenCalled();
ctx.setProcesses([4242]);
await ctx.pipeWatcher.tickNow();
await flush();
expect(ctx.onSessionsChanged).toHaveBeenCalled();
ctx.manager.dispose();
});
it('fires when the watcher reports a process is gone', async () => {
const ctx = makeManager({ processes: [4242] });
await ctx.pipeWatcher.start();
await flush();
ctx.onSessionsChanged.mockClear();
ctx.setProcesses([]);
await ctx.pipeWatcher.tickNow();
await flush();
expect(ctx.onSessionsChanged).toHaveBeenCalled();
ctx.manager.dispose();
});
it('fires when the watcher reports the pipe came up (status: connecting → loaded)', async () => {
const ctx = makeManager({ processes: [4242] });
await ctx.pipeWatcher.start();
await flush();
// Inject so the session is in 'connecting' state; the next pipe-up
// makes attemptConnect succeed and status flips to 'loaded'.
await ctx.manager.loadProcess(4242);
await flush();
ctx.onSessionsChanged.mockClear();
ctx.setLivePipes([4242]);
await ctx.pipeWatcher.tickNow();
await flush();
await flush();
expect(ctx.onSessionsChanged).toHaveBeenCalled();
ctx.manager.dispose();
});
it('survives a throwing onSessionsChanged callback — the watcher loop keeps running', async () => {
const ctx = makeManager({ processes: [] });
ctx.onSessionsChanged.mockImplementation(() => { throw new Error('listener boom'); });
await ctx.pipeWatcher.start();
ctx.setProcesses([4242]);
await expect(ctx.pipeWatcher.tickNow()).resolves.not.toThrow();
await flush();
// A second tick still fires the callback — it wasn't unregistered by
// the prior throw.
ctx.onSessionsChanged.mockClear();
ctx.setProcesses([4242, 5555]);
await ctx.pipeWatcher.tickNow();
await flush();
expect(ctx.onSessionsChanged).toHaveBeenCalled();
ctx.manager.dispose();
});
it('is OPTIONAL — omitting it leaves the manager fully functional', async () => {
const pids = [4242];
const pipeWatcher = new PipeWatcher({
listProcesses: () => pids.map(pid => ({ pid, name: 'qq', path: '' })),
listLivePipes: async () => new Set(),
intervalMs: 60_000,
});
const manager = new HookManager({
bridgeManager: {
onPacket: vi.fn(),
onHookLogin: vi.fn(),
onPidDisconnected: vi.fn(),
} as unknown as BridgeManagerSink,
pipeWatcher,
injector: {
inject: vi.fn(() => ({ method: 'loadModuleManual' as const, handle: DUMMY_HANDLE })),
unload: vi.fn(),
},
makeClient: vi.fn(() => {
const c = new EventEmitter() as any;
c.isClosed = false; c.isLoggedIn = false;
c.getLoginState = () => ({ loggedIn: false, uin: '0', uinNumber: 0n });
c.connectAll = async () => undefined;
c.close = () => { c.isClosed = true; };
return c;
}),
listProcesses: () => pids.map(pid => ({ pid, name: 'qq', path: '' })),
// onSessionsChanged deliberately omitted
});
await pipeWatcher.start();
await pipeWatcher.tickNow();
await flush();
const list = await manager.listProcesses();
expect(list).toHaveLength(1);
expect(list[0].pid).toBe(4242);
manager.dispose();
});
});

View File

@@ -3,6 +3,7 @@ import { EventEmitter } from 'events';
import { HookSession } from '../src/hook-session';
import type { ManualMapHandle } from '../src/injector';
import type { QqHookClient, QqHookPacket } from '../src/qq-hook-client';
import type { QqPortLoginInfo } from '../src/qq-port-probe';
import type { PacketSink } from '@snowluma/common/protocol-types';
const DUMMY_HANDLE: ManualMapHandle = { base: 0n, entry: 0n, exceptionTable: 0n, size: 0 };
@@ -42,6 +43,7 @@ function makeSession(opts: {
pipeLive?: boolean;
clientFailsConnect?: boolean;
onPacket?: PacketSink;
probeLogin?: (pid: number) => Promise<QqPortLoginInfo | null>;
} = {}) {
const pid = opts.pid ?? 1234;
let pipeLive = opts.pipeLive ?? false;
@@ -50,6 +52,9 @@ function makeSession(opts: {
inject: vi.fn(() => ({ method: 'loadModuleManual' as const, handle: DUMMY_HANDLE })),
unload: vi.fn(),
};
// Default probe reports "not logged in" so the reconcile safety net is inert
// unless a test opts into a logged-in probe (never hits the real port scan).
const probeLogin = opts.probeLogin ?? (async () => ({ port: 0, uin: '', loggedIn: false }));
const session = new HookSession(pid, {
injector,
@@ -60,6 +65,7 @@ function makeSession(opts: {
// Cast: FakeClient mirrors only the surface HookSession touches.
return c as unknown as QqHookClient;
},
probeLogin,
pipeWatcher: { isPipeLive: () => pipeLive },
onPacket: opts.onPacket,
});
@@ -347,6 +353,95 @@ describe('HookSession — process gone', () => {
});
});
describe('HookSession — refresh drift fix', () => {
// refresh while the pipe is down on a connected-but-never-logged-in
// session now reports 'connecting' (matching what onPipeDown gives for the
// same state), not the old spurious 'disconnected'. Pre-refactor, refresh's
// down branch ignored wasLoggedIn and always reported 'disconnected'.
it('refresh-while-down + never logged in → connecting (not disconnected), no disconnect emit', async () => {
const ctx = makeSession({ pipeLive: true });
await ctx.session.load();
ctx.session.onPipeUp();
await flush();
expect(ctx.session.status).toBe('loaded'); // connected, never logged in
const discSpy = vi.fn();
ctx.session.on('disconnected', discSpy);
ctx.setPipeLive(false);
const info = await ctx.session.refresh();
expect(info.status).toBe('connecting'); // drift fix: was 'disconnected'
expect(discSpy).not.toHaveBeenCalled(); // never logged in ⇒ nothing owed
});
it('refresh-while-down after login still → disconnected + emits disconnected(true)', async () => {
// The flip is scoped to the never-logged-in case; a real session that
// had reached login must still settle to 'disconnected' and notify.
const ctx = makeSession({ pipeLive: true });
await ctx.session.load();
ctx.session.onPipeUp();
await flush();
ctx.currentClient().fireLogin('10001');
expect(ctx.session.status).toBe('online');
const discSpy = vi.fn();
ctx.session.on('disconnected', discSpy);
ctx.setPipeLive(false);
const info = await ctx.session.refresh();
expect(info.status).toBe('disconnected');
expect(discSpy).toHaveBeenCalledWith(true);
});
});
describe('HookSession — pipe-down must not clobber a settled error', () => {
// Regression net for the phase-2 reconcilePipeDown !connected short-circuit:
// a pipe-down tick on a session that never reached a live connection must
// not wipe a diagnostic error or emit a spurious status-changed.
it('onPipeDown after a failed connect keeps the error and does not re-emit', async () => {
const ctx = makeSession({ pipeLive: true, clientFailsConnect: true });
await ctx.session.load();
ctx.session.onPipeUp();
await flush();
expect(ctx.session.status).toBe('connecting');
expect(ctx.session.error).toBe('connect failed');
const statusSpy = vi.fn();
ctx.session.on('status-changed', statusSpy);
ctx.session.onPipeDown();
await flush();
expect(ctx.session.status).toBe('connecting');
expect(ctx.session.error).toBe('connect failed'); // not wiped to ''
expect(statusSpy).not.toHaveBeenCalled(); // no spurious emit
});
it('onPipeDown after a failed load leaves the error status intact', async () => {
const injector = {
inject: vi.fn(() => { throw new Error('inject boom'); }),
unload: vi.fn(),
};
const session = new HookSession(1234, {
injector,
makeClient: () => new FakeClient() as unknown as QqHookClient,
pipeWatcher: { isPipeLive: () => false },
});
await session.load();
expect(session.status).toBe('error');
expect(session.error).toBe('inject boom');
session.onPipeDown();
await flush();
expect(session.status).toBe('error'); // not flipped to 'available'
expect(session.error).toBe('inject boom'); // not wiped
});
});
describe('HookSession — packet forwarding', () => {
// These tests cover the field-rename + filter logic that used to live
// inside the deleted NtqqHandler.onHookPacket. Inlining it here means
@@ -444,3 +539,136 @@ describe('HookSession — packet forwarding', () => {
});
});
});
describe('HookSession — login reconcile (Docker auto-login safety net)', () => {
it('reconciles login via the active probe when the pushed frame is missed', async () => {
// Probe reports logged-in; the FakeClient never fires a loginState frame
// (the missed-edge Docker case). The immediate reconcile probe must detect
// it and emit "login".
const ctx = makeSession({
pipeLive: true,
probeLogin: async () => ({ port: 4301, uin: '10001', loggedIn: true }),
});
const loginSpy = vi.fn();
ctx.session.on('login', loginSpy);
await ctx.session.load();
ctx.session.onPipeUp();
await flush(); // connect (not logged in via frame) → starts reconcile
await flush(); // immediate probe resolves → handleLoginState
expect(loginSpy).toHaveBeenCalledOnce();
expect(loginSpy.mock.calls[0]![0]).toBe('10001');
expect(ctx.session.status).toBe('online');
expect(ctx.session.uin).toBe('10001');
});
it('does not log in when the probe reports not-logged-in', async () => {
const ctx = makeSession({
pipeLive: true,
probeLogin: async () => ({ port: 0, uin: '', loggedIn: false }),
});
const loginSpy = vi.fn();
ctx.session.on('login', loginSpy);
await ctx.session.load();
ctx.session.onPipeUp();
await flush(); await flush();
expect(loginSpy).not.toHaveBeenCalled();
expect(ctx.session.status).toBe('loaded');
});
it('ignores a probe with a non-real uin (0)', async () => {
const ctx = makeSession({
pipeLive: true,
probeLogin: async () => ({ port: 4301, uin: '0', loggedIn: true }),
});
const loginSpy = vi.fn();
ctx.session.on('login', loginSpy);
await ctx.session.load();
ctx.session.onPipeUp();
await flush(); await flush();
expect(loginSpy).not.toHaveBeenCalled();
});
it('tolerates a throwing probe (best-effort, no crash/login)', async () => {
const ctx = makeSession({
pipeLive: true,
probeLogin: async () => { throw new Error('port scan failed'); },
});
const loginSpy = vi.fn();
ctx.session.on('login', loginSpy);
await ctx.session.load();
ctx.session.onPipeUp();
await flush(); await flush();
expect(loginSpy).not.toHaveBeenCalled();
expect(ctx.session.status).toBe('loaded');
});
it('detects a login that lands on a LATER interval probe', async () => {
vi.useFakeTimers();
try {
let loggedIn = false;
const ctx = makeSession({
pipeLive: true,
probeLogin: async () => ({ port: 4301, uin: '10001', loggedIn }),
});
const loginSpy = vi.fn();
ctx.session.on('login', loginSpy);
await ctx.session.load();
ctx.session.onPipeUp();
await vi.advanceTimersByTimeAsync(0); // connect + immediate probe (not logged in yet)
expect(loginSpy).not.toHaveBeenCalled();
loggedIn = true; // QQ finishes auto-login
await vi.advanceTimersByTimeAsync(3000); // next interval probe picks it up
expect(loginSpy).toHaveBeenCalledOnce();
expect(ctx.session.status).toBe('online');
} finally {
vi.useRealTimers();
}
});
it('does not double-emit when the pushed frame logs in first', async () => {
// Pushed-frame login wins; a subsequent probe with the same uin must not
// re-emit (handleLoginState dedups), and the reconcile timer is stopped.
const probeLogin = vi.fn(async () => ({ port: 4301, uin: '10001', loggedIn: true }));
const ctx = makeSession({ pipeLive: true, probeLogin });
const loginSpy = vi.fn();
ctx.session.on('login', loginSpy);
await ctx.session.load();
ctx.session.onPipeUp();
await flush();
ctx.currentClient().fireLogin('10001'); // pushed-frame login first
await flush();
expect(loginSpy).toHaveBeenCalledOnce();
expect(ctx.session.status).toBe('online');
});
});
describe('HookSession — login reconcile does not stack concurrent probes', () => {
it('skips overlapping ticks while a slow probe is in flight', async () => {
vi.useFakeTimers();
try {
// A probe that never resolves — simulates a slow port scan spanning
// multiple intervals. The in-flight guard must call it only once.
const probeLogin = vi.fn(() => new Promise<never>(() => { /* pending */ }));
const ctx = makeSession({ pipeLive: true, probeLogin });
await ctx.session.load();
ctx.session.onPipeUp();
await vi.advanceTimersByTimeAsync(0); // connect + immediate probe (starts, stays pending)
await vi.advanceTimersByTimeAsync(9000); // 3 more interval ticks
expect(probeLogin).toHaveBeenCalledTimes(1); // not stacked
} finally {
vi.useRealTimers();
}
});
});

View File

@@ -0,0 +1,56 @@
import { describe, it, expect } from 'vitest';
import { statusFor, type HookFlags } from '../src/hook-status';
import type { HookProcessStatus } from '../src/types';
const F = (o: Partial<HookFlags>): HookFlags => ({
injected: false, connected: false, loggedIn: false, wasLoggedIn: false, ...o,
});
describe('statusFor — settled HookProcessStatus derivation', () => {
it('not injected → available (regardless of other flags)', () => {
expect(statusFor(F({ injected: false }))).toBe('available');
// !injected dominates: stale connected/loggedIn bits must not leak through.
expect(statusFor(F({ injected: false, connected: true, loggedIn: true, wasLoggedIn: true }))).toBe('available');
});
it('injected, connected, loggedIn → online', () => {
expect(statusFor(F({ injected: true, connected: true, loggedIn: true }))).toBe('online');
});
it('injected, connected, not loggedIn → loaded', () => {
expect(statusFor(F({ injected: true, connected: true, loggedIn: false }))).toBe('loaded');
});
it('injected, not connected, had logged in → disconnected', () => {
expect(statusFor(F({ injected: true, connected: false, wasLoggedIn: true }))).toBe('disconnected');
});
it('injected, not connected, never logged in → connecting', () => {
expect(statusFor(F({ injected: true, connected: false, wasLoggedIn: false }))).toBe('connecting');
});
it('disconnected vs connecting differ ONLY by wasLoggedIn (same injected+!connected)', () => {
const base = { injected: true, connected: false, loggedIn: false };
expect(statusFor(F({ ...base, wasLoggedIn: true }))).toBe('disconnected');
expect(statusFor(F({ ...base, wasLoggedIn: false }))).toBe('connecting');
});
it('covers exactly the five settled states across the flag space', () => {
const seen = new Set<HookProcessStatus>();
for (const injected of [false, true]) {
for (const connected of [false, true]) {
for (const loggedIn of [false, true]) {
for (const wasLoggedIn of [false, true]) {
seen.add(statusFor({ injected, connected, loggedIn, wasLoggedIn }));
}
}
}
}
expect([...seen].sort()).toEqual(
['available', 'connecting', 'disconnected', 'loaded', 'online'].sort(),
);
// The two out-of-band states are never produced by the pure derivation.
expect(seen.has('loading')).toBe(false);
expect(seen.has('error')).toBe(false);
});
});

View File

@@ -192,4 +192,40 @@ describe('PipeWatcher', () => {
expect(events).toEqual([['discovered', 1234], ['up', 1234]]);
watcher.stop();
});
it('UNKNOWN (null) enumeration keeps prior state — no false process-gone (issue #158)', async () => {
let result: HookProcessBaseInfo[] | null = [{ pid: 1234, name: 'qq', path: '' }];
let live = new Set<number>([1234]);
const watcher = new PipeWatcher({
listProcesses: () => result,
listLivePipes: async () => new Set(live),
intervalMs: 60_000,
});
await watcher.start();
expect(watcher.isProcessAlive(1234)).toBe(true);
expect(watcher.isPipeLive(1234)).toBe(true);
const events = captureEvents(watcher);
// Enumeration goes UNKNOWN (e.g. native /proc walk timed out during a QQ
// hot-update). Prior process + pipe state MUST be preserved — no teardown.
result = null;
await watcher.tickNow();
expect(events).toEqual([]);
expect(watcher.isProcessAlive(1234)).toBe(true);
expect(watcher.isPipeLive(1234)).toBe(true);
// Enumeration recovers with the same set → still no churn.
result = [{ pid: 1234, name: 'qq', path: '' }];
await watcher.tickNow();
expect(events).toEqual([]);
// A REAL disappearance (empty list, not null) still fires the teardown.
result = [];
live = new Set();
await watcher.tickNow();
expect(events).toEqual([['down', 1234], ['gone', 1234]]);
watcher.stop();
});
});

View File

@@ -0,0 +1,55 @@
import { describe, it, expect, vi } from 'vitest';
import { createNativeProcessEnumerator } from '../src/process-enumerator';
import type { HookProcessBaseInfo } from '../src/injector';
const QQ = (pid: number): HookProcessBaseInfo => ({ pid, name: 'qq', path: '' });
describe('createNativeProcessEnumerator', () => {
describe('no addon (macOS / missing) → synchronous fallback, never a worker', () => {
it('returns the sync lister result', async () => {
const en = createNativeProcessEnumerator({
addonPath: null,
fallbackSync: () => [QQ(10), QQ(20)],
processName: 'qq',
});
expect(await en.enumerate()).toEqual([QQ(10), QQ(20)]);
en.dispose();
});
it('maps a throwing sync lister to UNKNOWN (null), not an empty list', async () => {
const en = createNativeProcessEnumerator({
addonPath: null,
fallbackSync: () => { throw new Error('boom'); },
processName: 'qq',
});
expect(await en.enumerate()).toBeNull();
en.dispose();
});
});
describe('worker isolation that cannot load the addon → permanent fallback', () => {
it('falls back to the sync lister after the worker reports a fatal load error', async () => {
const fallback = vi.fn(() => [QQ(7)]);
const en = createNativeProcessEnumerator({
// A path that exists nowhere → process.dlopen throws in the worker →
// the worker posts 'fatal' → isolation is abandoned for good.
addonPath: '/nonexistent/snowluma-test.node',
fallbackSync: fallback,
processName: 'qq',
timeoutMs: 200,
});
// First call spawns the worker; the fatal message drains it to UNKNOWN.
const first = await en.enumerate();
expect(first).toBeNull();
// Give the 'fatal' message a moment to flip isolationBroken if it hadn't
// already, then subsequent calls take the synchronous fallback.
await new Promise((r) => setTimeout(r, 50));
const second = await en.enumerate();
expect(second).toEqual([QQ(7)]);
expect(fallback).toHaveBeenCalled();
en.dispose();
});
});
});

View File

@@ -1,8 +1,9 @@
import net from 'net';
import { mkdtemp, rm, writeFile } from 'fs/promises';
import os from 'os';
import path from 'path';
import { afterEach, describe, expect, it, vi } from 'vitest';
import { listLiveLinuxPipePids } from '../src/qq-hook-client';
import { listLiveLinuxPipePids, QqHookClient } from '../src/qq-hook-client';
let tmpDir: string | null = null;
@@ -42,3 +43,66 @@ describe('listLiveLinuxPipePids', () => {
expect(probe).toHaveBeenCalledTimes(2);
});
});
describe.skipIf(process.platform === 'win32')('QqHookClient — pipe close mid-send', () => {
// Regression: when the control pipe closes while a send() is awaiting its
// ack, rejectControlPending() rejects BOTH the ack and reply deferreds. The
// reply is only `await`ed after the ack, so if the ack rejects first the
// reply promise is rejected with NO awaiter — an UNHANDLED rejection that
// crashes the Node process (Docker: supervisor restarts it ~1s later; on
// Windows it just dies → "connection pipe closed", bot down). The .catch()
// guard on each deferred prevents it; without the guard this test trips the
// unhandledRejection assertion below.
it('does not raise an unhandled rejection', async () => {
const dir = await mkdtemp(path.join(os.tmpdir(), 'snowluma-pipe-'));
const prevRuntimeDir = process.env.SNOWLUMA_HOOK_RUNTIME_DIR;
process.env.SNOWLUMA_HOOK_RUNTIME_DIR = dir;
const PID = 778899;
const helloFrame = (): Buffer => {
const h = Buffer.alloc(40);
h.writeUInt32LE(0x31504851, 0); // PIPE_MAGIC
h.writeUInt16LE(1, 4); // PIPE_VERSION
h.writeUInt16LE(1, 6); // PipeOp.hello
h.writeBigUInt64LE(BigInt(PID), 32); // value0 = pid
return h;
};
let controlConn: net.Socket | null = null;
const controlServer = net.createServer((sock) => { controlConn = sock; sock.write(helloFrame()); });
const recvServer = net.createServer((sock) => { sock.write(helloFrame()); });
await new Promise<void>((r) => controlServer.listen(path.join(dir, `mojo.${PID}.control.sock`), () => r()));
await new Promise<void>((r) => recvServer.listen(path.join(dir, `mojo.${PID}.recv.sock`), () => r()));
const unhandled: unknown[] = [];
const onUnhandled = (reason: unknown): void => { unhandled.push(reason); };
process.on('unhandledRejection', onUnhandled);
const client = new QqHookClient(PID);
client.on('error', () => { /* socket reset on destroy — ignore */ });
try {
await client.connectAll({ recv: true });
// Start a reply-expecting send, let it reach the in-flight (awaiting-ack)
// state, then have the "hook" drop the pipe before it answers.
const sent = client.send('noop', null, { wantReply: true, ackTimeoutMs: 1000, replyTimeoutMs: 1000 })
.then(() => 'resolved' as const, (e: unknown) => e);
await new Promise((r) => setTimeout(r, 30));
controlConn?.destroy();
const outcome = await sent;
await new Promise((r) => setTimeout(r, 50)); // let Node surface any unhandled rejection
expect(outcome).toBeInstanceOf(Error);
expect(unhandled, `unhandled rejections leaked: ${unhandled.map(String).join(', ')}`).toHaveLength(0);
} finally {
process.off('unhandledRejection', onUnhandled);
client.close();
await new Promise<void>((r) => controlServer.close(() => r()));
await new Promise<void>((r) => recvServer.close(() => r()));
if (prevRuntimeDir === undefined) delete process.env.SNOWLUMA_HOOK_RUNTIME_DIR;
else process.env.SNOWLUMA_HOOK_RUNTIME_DIR = prevRuntimeDir;
await rm(dir, { recursive: true, force: true });
}
});
});

View File

@@ -1,6 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/common",
"version": "1.9.2",
"version": "1.11.2",
"private": true,
"type": "module",
"description": "SnowLuma shared infrastructure — leaf-package utilities with zero business dependencies. Logger / hex codec / log file transport / log line summariser / packet sender wire-protocol types / runtime config loader. Consumed by @snowluma/protocol, @snowluma/core, and @snowluma/onebot. Per-file subpath exports keep import sites unambiguous and let the bundler tree-shake aggressively (importing `@snowluma/common/hex` doesn't pull in `node:fs` from the logger transport).",
@@ -15,6 +16,18 @@
"types": "./src/logger.ts",
"default": "./src/logger.ts"
},
"./coerce": {
"types": "./src/coerce.ts",
"default": "./src/coerce.ts"
},
"./single-flight-cache": {
"types": "./src/single-flight-cache.ts",
"default": "./src/single-flight-cache.ts"
},
"./concurrency": {
"types": "./src/concurrency.ts",
"default": "./src/concurrency.ts"
},
"./hex": {
"types": "./src/hex.ts",
"default": "./src/hex.ts"
@@ -42,13 +55,19 @@
"./runtime": {
"types": "./src/runtime.ts",
"default": "./src/runtime.ts"
},
"./uin": {
"types": "./src/uin.ts",
"default": "./src/uin.ts"
}
},
"scripts": {
"typecheck": "tsc --noEmit"
"typecheck": "tsc --noEmit",
"test": "vitest run"
},
"devDependencies": {
"@types/node": "^24.12.2",
"typescript": "catalog:"
"typescript": "catalog:",
"vitest": "^4.1.4"
}
}

View File

@@ -0,0 +1,30 @@
// Scalar coercion primitives for normalizing untrusted JSON config into
// typed values with fallbacks. Zero dependencies — these were duplicated
// verbatim across notifications/config and webui/ui-config; this is their
// single home. Input tolerance is deliberate (numeric strings coerce), but
// validity is strict (a wrong type yields the caller's fallback, never a
// silent 0/'' — except where the primitive's contract says otherwise).
/** True only for a plain, non-null, non-array object. */
export function isObject(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
/** The value when it is a real boolean, else the fallback. Strings/numbers
* are NOT coerced — `'true'` and `1` both yield the fallback. */
export function boolOr(value: unknown, fallback: boolean): boolean {
return typeof value === 'boolean' ? value : fallback;
}
/** A finite number (numeric strings coerced) clamped to `[min, max]`, else
* the fallback. Fractional precision is preserved — use `clampInt` to floor. */
export function clampNum(value: unknown, min: number, max: number, fallback: number): number {
const n = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : NaN;
if (!Number.isFinite(n)) return fallback;
return Math.min(max, Math.max(min, n));
}
/** `clampNum` truncated toward zero — clamp first, then drop the fraction. */
export function clampInt(value: unknown, min: number, max: number, fallback: number): number {
return Math.trunc(clampNum(value, min, max, fallback));
}

View File

@@ -0,0 +1,27 @@
/**
* Map `items` through `fn` in sequential batches of at most `concurrency`
* items, awaiting each batch (`Promise.all`) before starting the next.
* Results come back in input order.
*
* Batched, not a rolling pool: every item in a batch must settle before the
* next batch starts. This caps peak parallelism — used to keep rate-limited
* fan-out (e.g. the per-uin OIDB profile fetches during forward-node
* enrichment) from bursting past a safe width and tripping Tencent
* risk-control. Pair it with a cap on `items` (slice) and per-item error
* handling inside `fn` for a fully bounded, best-effort enrichment — the
* shape that was previously hand-rolled at each such call site.
*/
export async function mapWithConcurrency<T, R>(
items: readonly T[],
concurrency: number,
fn: (item: T, index: number) => Promise<R>,
): Promise<R[]> {
const limit = Math.max(1, Math.trunc(concurrency));
const results = new Array<R>(items.length);
for (let i = 0; i < items.length; i += limit) {
const batch = items.slice(i, i + limit);
const settled = await Promise.all(batch.map((item, j) => fn(item, i + j)));
for (let j = 0; j < settled.length; j++) results[i + j] = settled[j]!;
}
return results;
}

View File

@@ -49,3 +49,70 @@ export function summarizeParams(params: unknown): string {
}
return out.join(' ');
}
const VERBOSE_STRING_MAX = 200;
const VERBOSE_TOTAL_MAX = 1500;
// Keys whose values must never be rendered — tokens, passwords, secrets.
const REDACT_KEY = /^(.*[-_])?(token|password|passwd|secret|access[-_]?token)([-_].*)?$/i;
/**
* Deep, debug-grade render of a params object for the `trace` level: shows the
* full nested structure (message segments, nested objects) so a reproduction
* is legible — unlike {@link summarizeParams}, which collapses nested values.
*
* Three guards keep it safe and bounded:
* - per-string cap (long values like base64 image data become `"…<N B>"`),
* - total output budget (so a giant payload can't flood the buffer),
* - key-based redaction (token / password / secret → `"***"`).
*/
export function renderParamsVerbose(params: unknown): string {
const seen = new WeakSet<object>();
let budget = VERBOSE_TOTAL_MAX;
const walk = (value: unknown, key?: string): string => {
if (budget <= 0) return '…';
if (key !== undefined && REDACT_KEY.test(key)) return '"***"';
if (value === null) return 'null';
if (value === undefined) return 'undefined';
switch (typeof value) {
case 'string': {
const truncated =
value.length > VERBOSE_STRING_MAX
? `${value.slice(0, VERBOSE_STRING_MAX)}…<${value.length}B>`
: value;
const out = JSON.stringify(truncated);
budget -= out.length;
return out;
}
case 'number':
case 'boolean':
case 'bigint': {
const out = String(value);
budget -= out.length;
return out;
}
case 'object': {
if (seen.has(value as object)) return '"[circular]"';
seen.add(value as object);
const parts: string[] = [];
if (Array.isArray(value)) {
for (const item of value) {
if (budget <= 0) { parts.push('…'); break; }
parts.push(walk(item));
}
return `[${parts.join(',')}]`;
}
for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
if (budget <= 0) { parts.push('…'); break; }
parts.push(`${k}:${walk(v, k)}`);
}
return `{${parts.join(',')}}`;
}
default:
return typeof value;
}
};
return walk(params);
}

View File

@@ -1,7 +1,8 @@
import { format } from 'util';
import { getFileTransport } from './log-file-transport';
import { currentRequestId } from './request-context';
type LogLevel = 'debug' | 'info' | 'success' | 'warn' | 'error';
type LogLevel = 'trace' | 'debug' | 'info' | 'success' | 'warn' | 'error';
export interface LogEntry {
id: number;
@@ -10,6 +11,8 @@ export interface LogEntry {
scope: string;
/** QQ uin, when the source logger was derived via `.child({ uin })`. */
uin?: number;
/** Correlation id, when emitted inside a `runWithRequestId(...)` scope. */
req?: number;
message: string;
line: string;
}
@@ -26,6 +29,7 @@ interface LogOptions {
const UIN_SLOT_WIDTH = 12;
const LEVEL_WEIGHT: Record<LogLevel, number> = {
trace: 5,
debug: 10,
info: 20,
success: 25,
@@ -34,6 +38,7 @@ const LEVEL_WEIGHT: Record<LogLevel, number> = {
};
const LEVEL_LABEL: Record<LogLevel, string> = {
trace: 'TRACE',
debug: 'DEBUG',
info: 'INFO',
success: 'OK',
@@ -42,6 +47,7 @@ const LEVEL_LABEL: Record<LogLevel, string> = {
};
const COLOR_CODE: Record<LogLevel, number> = {
trace: 90,
debug: 90,
info: 36,
success: 32,
@@ -53,13 +59,55 @@ const COLOR_SCOPE = 35;
const COLOR_DIM = 2;
const COLOR_RESET = '\x1b[0m';
const MAX_LOG_ENTRIES = 1000;
const logEntries: LogEntry[] = [];
/** Trace ring cap — env-tunable since trace is the high-volume stream. */
function resolveTraceBufferMax(): number {
const raw = Number.parseInt(process.env.SNOWLUMA_TRACE_BUFFER ?? '', 10);
return Number.isFinite(raw) && raw >= 100 ? raw : 5000;
}
const TRACE_BUFFER_MAX = resolveTraceBufferMax();
/**
* Fixed-capacity circular buffer. O(1) push + eviction (no array `.shift()`),
* so the high-throughput trace stream never pays an O(n) shift per overflow.
*/
class RingBuffer<T> {
private readonly buf: (T | undefined)[];
private start = 0;
private count = 0;
constructor(private readonly cap: number) {
this.buf = new Array<T | undefined>(cap);
}
push(item: T): void {
const end = (this.start + this.count) % this.cap;
this.buf[end] = item;
if (this.count < this.cap) this.count += 1;
else this.start = (this.start + 1) % this.cap; // full → overwrite oldest
}
/** Most recent `n` items, oldest→newest. */
recent(n: number): T[] {
const take = Math.max(0, Math.min(Math.trunc(n), this.count));
const out: T[] = new Array<T>(take);
const first = this.start + (this.count - take);
for (let i = 0; i < take; i += 1) out[i] = this.buf[(first + i) % this.cap]!;
return out;
}
toArray(): T[] {
return this.recent(this.count);
}
get size(): number {
return this.count;
}
}
const logRing = new RingBuffer<LogEntry>(MAX_LOG_ENTRIES);
const traceRing = new RingBuffer<LogEntry>(TRACE_BUFFER_MAX);
const logSubscribers = new Set<(entry: LogEntry) => void>();
let nextLogId = 1;
function resolveMinLevel(): LogLevel {
const raw = (process.env.SNOWLUMA_LOG_LEVEL ?? 'info').toLowerCase();
if (raw === 'debug' || raw === 'info' || raw === 'success' || raw === 'warn' || raw === 'error') {
if (raw === 'trace' || raw === 'debug' || raw === 'info' || raw === 'success' || raw === 'warn' || raw === 'error') {
return raw;
}
return 'info';
@@ -75,7 +123,7 @@ function shouldLog(level: LogLevel): boolean {
return LEVEL_WEIGHT[level] >= LEVEL_WEIGHT[currentLevel];
}
export const LOG_LEVELS: readonly LogLevel[] = ['debug', 'info', 'success', 'warn', 'error'];
export const LOG_LEVELS: readonly LogLevel[] = ['trace', 'debug', 'info', 'success', 'warn', 'error'];
export function getLogLevel(): LogLevel {
return currentLevel;
@@ -110,15 +158,16 @@ function currentTime(): string {
return `${hh}:${mm}:${ss}`;
}
function render(level: LogLevel, options: LogOptions, args: unknown[]): string {
function render(level: LogLevel, options: LogOptions, args: unknown[], reqId?: number): string {
const message = format(...args);
const ts = currentTime();
const label = LEVEL_LABEL[level].padEnd(5, ' ');
const uinTag = options.uin !== undefined ? `[${options.uin}]` : '';
const uinSlot = uinTag.padEnd(UIN_SLOT_WIDTH);
const reqTag = reqId !== undefined ? `[req#${reqId}]` : '';
if (!useColor()) {
return `${ts} ${label} ${uinSlot} [${options.scope}] ${message}`;
return `${ts} ${label} ${uinSlot} [${options.scope}] ${reqTag ? `${reqTag} ` : ''}${message}`;
}
const cTs = ansi(COLOR_DIM, ts);
@@ -126,31 +175,49 @@ function render(level: LogLevel, options: LogOptions, args: unknown[]): string {
// Pad first, then color only the visible tag so escape codes don't eat
// into the alignment width.
const cUin = uinTag
? ansi(COLOR_DIM, uinTag) + ' '.repeat(UIN_SLOT_WIDTH - uinTag.length)
? ansi(COLOR_DIM, uinTag) + ' '.repeat(Math.max(0, UIN_SLOT_WIDTH - uinTag.length))
: ' '.repeat(UIN_SLOT_WIDTH);
const cScope = ansi(COLOR_SCOPE, `[${options.scope}]`);
return `${cTs} ${cLabel} ${cUin} ${cScope} ${message}`;
const cReq = reqTag ? `${ansi(COLOR_DIM, reqTag)} ` : '';
return `${cTs} ${cLabel} ${cUin} ${cScope} ${cReq}${message}`;
}
function emit(level: LogLevel, options: LogOptions, args: unknown[]): void {
// Console / subscriber level filter. File output is debug-and-up always;
// see log-file-transport.ts.
const passesConsole = shouldLog(level);
const message = format(...args);
const line = render(level, options, args);
// `trace` never touches disk and is the high-volume full-chain stream. When
// it won't reach the console/memory buffer either (level not dialed to
// trace), bail BEFORE format/render AND before evaluating any lazy producer
// — this is what keeps full-chain tracing ~free at the default level even
// with hundreds of groups.
if (level === 'trace' && !passesConsole) return;
// Lazy trace form: `log.trace(() => ['…', deepRender(x)])`. The producer
// (and its expensive deep render) only runs now that trace is confirmed live.
let realArgs = args;
if (level === 'trace' && args.length === 1 && typeof args[0] === 'function') {
realArgs = (args[0] as () => unknown[])();
}
const reqId = currentRequestId();
const message = format(...realArgs);
const line = render(level, options, realArgs, reqId);
const entry: LogEntry = {
id: nextLogId++,
time: new Date().toISOString(),
level,
scope: options.scope,
...(options.uin !== undefined ? { uin: options.uin } : {}),
...(reqId !== undefined ? { req: reqId } : {}),
message,
line,
};
if (passesConsole) {
logEntries.push(entry);
if (logEntries.length > MAX_LOG_ENTRIES) logEntries.shift();
// Trace gets its own ring so its volume never evicts the normal log buffer.
(level === 'trace' ? traceRing : logRing).push(entry);
for (const subscriber of logSubscribers) subscriber(entry);
const stream = level === 'warn' || level === 'error' ? process.stderr : process.stdout;
// Strip ASCII control characters before writing to terminal to prevent
@@ -162,10 +229,11 @@ function emit(level: LogLevel, options: LogOptions, args: unknown[]): void {
stream.write(line.replace(/[\x00-\x08\x0B-\x1A\x1C-\x1F\x7F]/g, '') + '\n');
}
// File transport always sees every level (debug-and-up) for post-mortem
// value; ANSI stripping happens inside the transport. UIN routes the
// line to its per-account sub-file in addition to the shared one.
getFileTransport().write(line, options.uin);
// File transport sees debug-and-up for post-mortem value; `trace` is
// memory / WebUI only (omitted here to avoid huge on-disk volume). ANSI
// stripping happens inside the transport. UIN routes the line to its
// per-account sub-file in addition to the shared one.
if (level !== 'trace') getFileTransport().write(line, options.uin);
}
/**
@@ -179,8 +247,14 @@ export function closeLogger(): Promise<void> {
}
export function getRecentLogs(limit = 300): LogEntry[] {
const n = Math.max(1, Math.min(Math.trunc(limit), MAX_LOG_ENTRIES));
return logEntries.slice(-n);
const n = Math.max(1, Math.trunc(limit));
// Merge the normal + trace rings by id (ids are monotonic, so id order is
// chronological). The trace ring is empty unless trace level is/was active,
// so the common case is just the normal ring with no sort.
const merged = traceRing.size > 0
? [...logRing.toArray(), ...traceRing.toArray()].sort((a, b) => a.id - b.id)
: logRing.toArray();
return merged.slice(-n);
}
export function subscribeLogs(callback: (entry: LogEntry) => void): () => void {
@@ -191,6 +265,13 @@ export function subscribeLogs(callback: (entry: LogEntry) => void): () => void {
}
export interface Logger {
/**
* High-volume, memory-only diagnostic level (never written to disk). Pass a
* lazy producer — `trace(() => ['msg %s', expensiveRender(x)])` — so the
* arguments (and any costly rendering) are built only when trace is active.
* A plain `trace('msg', x)` works too but evaluates its args eagerly.
*/
trace: (...args: unknown[]) => void;
debug: (...args: unknown[]) => void;
info: (...args: unknown[]) => void;
success: (...args: unknown[]) => void;
@@ -207,6 +288,7 @@ export interface Logger {
function makeLogger(opts: LogOptions): Logger {
return {
trace: (...args: unknown[]) => emit('trace', opts, args),
debug: (...args: unknown[]) => emit('debug', opts, args),
info: (...args: unknown[]) => emit('info', opts, args),
success: (...args: unknown[]) => emit('success', opts, args),
@@ -226,3 +308,8 @@ function makeLogger(opts: LogOptions): Logger {
export function createLogger(scope: string): Logger {
return makeLogger({ scope });
}
// Request-correlation helpers live alongside the logger since `[req#N]`
// stamping is a logging concern. Re-exported here so callers import the
// whole logging surface from one place.
export { nextRequestId, runWithRequestId, currentRequestId } from './request-context';

View File

@@ -0,0 +1,35 @@
import { AsyncLocalStorage } from 'async_hooks';
interface RequestStore {
id: number;
}
const storage = new AsyncLocalStorage<RequestStore>();
let counter = 0;
/**
* Allocate the next per-process request id (monotonic). Wraps via uint32 so
* it never overflows to a non-integer; `0` is skipped so "no id" stays
* unambiguous.
*/
export function nextRequestId(): number {
counter = (counter + 1) >>> 0;
if (counter === 0) counter = 1;
return counter;
}
/**
* Run `fn` with `id` bound as the ambient request id for the entire async
* chain it spawns. Any logger call anywhere in that chain — across packages,
* across awaits — picks it up via {@link currentRequestId} with no signature
* threading. Used by the OneBot action handler to correlate a request's whole
* journey (entry → outbound packets → exit) under one `[req#N]` tag.
*/
export function runWithRequestId<T>(id: number, fn: () => T): T {
return storage.run({ id }, fn);
}
/** The request id bound to the current async context, or undefined outside one. */
export function currentRequestId(): number | undefined {
return storage.getStore()?.id;
}

View File

@@ -7,71 +7,102 @@ export interface RuntimeConfig {
* the HookManager. Also overridable at runtime via SNOWLUMA_HOOK_AUTOLOAD.
* Defaults to false; the Docker image flips it on in supervisord.conf. */
hookAutoLoad?: boolean;
/** WebUI listener bind address. '0.0.0.0' = all interfaces (default),
* '127.0.0.1' = localhost-only. Listener-level: change needs a restart. */
webuiHost?: string;
/** WebUI TLS. Cert/key live in config/cert.pem + config/key.pem; this
* only flips serving on/off. Listener-level: change needs a restart. */
webuiTls?: { enabled?: boolean };
/** Raw trust-proxy directive (same domain as SNOWLUMA_WEBUI_TRUST_PROXY),
* consumed by the WebUI's client-ip resolver. '' = trust nobody. */
trustProxy?: string;
}
const CONFIG_DIR = 'config';
const RUNTIME_CONFIG_PATH = path.join(CONFIG_DIR, 'runtime.json');
const DEFAULT_RUNTIME_CONFIG: RuntimeConfig = {
webuiPort: 5099,
hookAutoLoad: false,
};
const DEFAULT_WEBUI_PORT = 5099;
const DEFAULT_WEBUI_HOST = '0.0.0.0';
/**
* Pure on-disk-object → typed config normalization (defaults + validation,
* no fs / no env). Exported for testing; `loadRuntimeConfig` wraps it.
*/
export function normalizeRuntimeConfig(parsed: unknown): RuntimeConfig {
const obj = isObject(parsed) ? parsed : {};
return {
webuiPort: normalizePort(obj.webuiPort ?? DEFAULT_WEBUI_PORT, DEFAULT_WEBUI_PORT),
hookAutoLoad: normalizeBool(obj.hookAutoLoad, false),
webuiHost: normalizeHost(obj.webuiHost),
webuiTls: { enabled: isObject(obj.webuiTls) ? normalizeBool(obj.webuiTls.enabled, false) : false },
trustProxy: typeof obj.trustProxy === 'string' ? obj.trustProxy : '',
};
}
/**
* Pure SNOWLUMA_* env → override patch (no fs). Env wins over runtime.json
* (a trusted launcher like SnowLumaDesktop pins these per-launch without
* rewriting the file). Absent vars produce no key.
*/
export function resolveRuntimeEnvOverrides(env: NodeJS.ProcessEnv): Partial<RuntimeConfig> {
const out: Partial<RuntimeConfig> = {};
const port = parsePortString(env.SNOWLUMA_WEBUI_PORT);
if (port !== undefined) out.webuiPort = port;
const host = env.SNOWLUMA_WEBUI_HOST;
if (typeof host === 'string' && host.trim()) out.webuiHost = host.trim();
// Present-but-"0"/"off" is a deliberate override (trust nobody), distinct
// from "absent" — so gate on key presence, not truthiness.
const tp = env.SNOWLUMA_WEBUI_TRUST_PROXY;
if (typeof tp === 'string') out.trustProxy = tp;
return out;
}
export function loadRuntimeConfig(): RuntimeConfig {
fs.mkdirSync(CONFIG_DIR, { recursive: true });
const loaded = tryLoadRuntimeConfig();
let normalized: RuntimeConfig;
if (!loaded) {
saveRuntimeConfig(DEFAULT_RUNTIME_CONFIG);
normalized = { ...DEFAULT_RUNTIME_CONFIG };
} else {
normalized = {
webuiPort: normalizePort(loaded.webuiPort ?? 5099, 5099),
hookAutoLoad: normalizeBool(loaded.hookAutoLoad, false),
};
if (
normalized.webuiPort !== loaded.webuiPort
|| normalized.hookAutoLoad !== loaded.hookAutoLoad
) {
saveRuntimeConfig(normalized);
}
const parsed = tryLoadRuntimeConfig();
const normalized = normalizeRuntimeConfig(parsed ?? {});
// Persist when the file is absent or when normalization changed/backfilled
// anything (e.g. an older runtime.json lacking webuiHost/webuiTls).
if (parsed === null || !sameRuntimeConfig(parsed, normalized)) {
saveRuntimeConfig(normalized);
}
// SNOWLUMA_WEBUI_PORT overrides the on-disk value at runtime without
// rewriting runtime.json. Lets a trusted launcher (e.g. SnowLumaDesktop)
// pick a free port per-launch while CLI/Docker users continue to drive
// it from runtime.json.
const envPort = envPortOverride();
if (envPort !== undefined) {
normalized = { ...normalized, webuiPort: envPort };
}
return normalized;
// Env overrides apply in-memory only — never written back to disk.
return { ...normalized, ...resolveRuntimeEnvOverrides(process.env) };
}
function envPortOverride(): number | undefined {
const raw = process.env.SNOWLUMA_WEBUI_PORT;
if (!raw || typeof raw !== 'string') return undefined;
const n = Number(raw.trim());
if (!Number.isFinite(n)) return undefined;
const port = Math.trunc(n);
if (port <= 0 || port > 65535) return undefined;
return port;
/**
* Read the persisted config (normalized, no env overrides, no write). For the
* settings panel's GET — shows what's actually saved/editable on disk.
*/
export function readRuntimeConfig(): RuntimeConfig {
return normalizeRuntimeConfig(tryLoadRuntimeConfig() ?? {});
}
function tryLoadRuntimeConfig(): RuntimeConfig | null {
/**
* Persist a partial update. Merges onto the ON-DISK config (not the env-merged
* runtime view) so an env override (e.g. SNOWLUMA_WEBUI_PORT) is never baked
* into runtime.json. Returns the new persisted config (without env overrides).
*/
export function updateRuntimeConfig(patch: Partial<RuntimeConfig>): RuntimeConfig {
fs.mkdirSync(CONFIG_DIR, { recursive: true });
const onDisk = normalizeRuntimeConfig(tryLoadRuntimeConfig() ?? {});
const next = normalizeRuntimeConfig({ ...onDisk, ...patch });
saveRuntimeConfig(next);
return next;
}
function tryLoadRuntimeConfig(): Record<string, unknown> | null {
if (!fs.existsSync(RUNTIME_CONFIG_PATH)) return null;
try {
const raw = fs.readFileSync(RUNTIME_CONFIG_PATH, 'utf8');
const parsed = JSON.parse(raw) as unknown;
if (!isObject(parsed)) return null;
return {
webuiPort: normalizePort(parsed.webuiPort ?? 5099, 5099),
hookAutoLoad: normalizeBool(parsed.hookAutoLoad, false),
};
const parsed = JSON.parse(fs.readFileSync(RUNTIME_CONFIG_PATH, 'utf8')) as unknown;
return isObject(parsed) ? parsed : null;
} catch {
return null;
}
@@ -81,6 +112,33 @@ function saveRuntimeConfig(config: RuntimeConfig): void {
fs.writeFileSync(RUNTIME_CONFIG_PATH, JSON.stringify(config, null, 2), 'utf8');
}
/** True when the raw on-disk object already matches the normalized config
* on every known field (so we can skip a needless rewrite). */
function sameRuntimeConfig(parsed: Record<string, unknown>, n: RuntimeConfig): boolean {
const parsedTls = isObject(parsed.webuiTls) ? parsed.webuiTls.enabled : undefined;
return (
parsed.webuiPort === n.webuiPort
&& parsed.hookAutoLoad === n.hookAutoLoad
&& parsed.webuiHost === n.webuiHost
&& parsedTls === n.webuiTls?.enabled
&& parsed.trustProxy === n.trustProxy
);
}
function parsePortString(raw: unknown): number | undefined {
if (typeof raw !== 'string' || !raw.trim()) return undefined;
const n = Number(raw.trim());
if (!Number.isFinite(n)) return undefined;
const port = Math.trunc(n);
if (port <= 0 || port > 65535) return undefined;
return port;
}
function normalizeHost(value: unknown): string {
if (typeof value === 'string' && value.trim()) return value.trim();
return DEFAULT_WEBUI_HOST;
}
function normalizePort(value: unknown, fallback: number): number {
if (typeof value === 'number' && Number.isFinite(value)) {
const n = Math.trunc(value);

View File

@@ -0,0 +1,93 @@
/**
* Single-flight + TTL memoization.
*
* Concentrates the "don't refetch what's fresh, and don't stampede the same
* key with concurrent loads" pattern that was hand-rolled (slightly
* differently each time) across the codebase — e.g. `ContactsApi`'s group
* member-list cache and the WebUI update-check. Each copy re-implemented the
* same fiddly trio: a TTL freshness check, an in-flight promise map to
* de-dupe concurrent callers, and `finally`-cleanup of that map. Getting any
* of the three subtly wrong (forgetting the `finally`, caching an error,
* racing the timestamp) is a real hazard — so it lives in one place.
*
* The underlying concern is Tencent risk-control: a busy OneBot client can
* fan out one uncached OIDB fetch per inbound message, and sustained bursts
* trip a ban. TTL + single-flight collapse that fan-out.
*/
export interface SingleFlightCacheOptions<K, V> {
/** Freshness window in ms. A cached entry older than this is reloaded. */
ttlMs: number;
/** Load the value for a key. Rejections propagate and are never cached. */
load: (key: K) => Promise<V>;
/**
* Decide whether a resolved value should be cached. Default: always.
* Return `false` to leave an entry uncached (e.g. an error-shaped result the
* next call should retry) while still de-duping concurrent in-flight callers.
*/
shouldCache?: (value: V) => boolean;
/** Clock, injectable for tests. Defaults to `Date.now`. */
now?: () => number;
}
export class SingleFlightCache<K, V> {
private readonly ttlMs: number;
private readonly load: (key: K) => Promise<V>;
private readonly shouldCache: (value: V) => boolean;
private readonly now: () => number;
private readonly fresh = new Map<K, { at: number; value: V }>();
private readonly inflight = new Map<K, Promise<V>>();
constructor(opts: SingleFlightCacheOptions<K, V>) {
this.ttlMs = opts.ttlMs;
this.load = opts.load;
this.shouldCache = opts.shouldCache ?? (() => true);
this.now = opts.now ?? Date.now;
}
/**
* Get the value for `key`.
*
* - Returns a fresh cached value when the last load was within `ttlMs`.
* - Otherwise de-dupes concurrent callers onto a single `load()` and caches
* the result (subject to `shouldCache`). A rejected `load` propagates to
* every joined caller, clears the in-flight slot, and is not cached.
* - `force` bypasses the freshness check but still joins an in-flight load
* rather than starting a second one.
*/
get(key: K, opts: { force?: boolean } = {}): Promise<V> {
if (!opts.force) {
const hit = this.fresh.get(key);
if (hit && this.now() - hit.at < this.ttlMs) return Promise.resolve(hit.value);
}
const existing = this.inflight.get(key);
if (existing) return existing;
const task = (async () => {
try {
const value = await this.load(key);
if (this.shouldCache(value)) this.fresh.set(key, { at: this.now(), value });
return value;
} finally {
this.inflight.delete(key);
}
})();
this.inflight.set(key, task);
return task;
}
/** Drop a cached entry. Does not abort an in-flight load. */
invalidate(key: K): void {
this.fresh.delete(key);
}
/** Drop all cached entries. Does not abort in-flight loads. */
clear(): void {
this.fresh.clear();
}
}
export function createSingleFlightCache<K, V>(
opts: SingleFlightCacheOptions<K, V>,
): SingleFlightCache<K, V> {
return new SingleFlightCache(opts);
}

View File

@@ -0,0 +1,11 @@
// Shared QQ UIN validity check. A "real" UIN is a live QQ account number, not
// a garbage value the native hook can emit during the probe→inject race — e.g.
// a 13-digit millisecond timestamp read from not-yet-populated QQ memory
// (issue #162). No real QQ UIN exceeds 10 digits (they fit in uint32, max
// 4294967295), so a pure digit string of 5..10 chars is the accept window.
//
// Callers rely on a `true` result guaranteeing a BigInt()-safe pure-digit
// string. Keep that contract if the pattern ever changes.
export function isRealUin(uin: string): boolean {
return /^\d{5,10}$/.test(uin);
}

View File

@@ -0,0 +1,78 @@
import { describe, it, expect } from 'vitest';
import { isObject, boolOr, clampNum, clampInt } from '../src/coerce';
describe('isObject', () => {
it('is true only for plain non-null non-array objects', () => {
expect(isObject({})).toBe(true);
expect(isObject({ a: 1 })).toBe(true);
expect(isObject(null)).toBe(false);
expect(isObject([])).toBe(false);
expect(isObject('x')).toBe(false);
expect(isObject(42)).toBe(false);
expect(isObject(undefined)).toBe(false);
});
});
describe('boolOr', () => {
it('returns the value only when it is a real boolean, else the fallback', () => {
expect(boolOr(true, false)).toBe(true);
expect(boolOr(false, true)).toBe(false);
expect(boolOr('true', false)).toBe(false); // strings are NOT coerced
expect(boolOr(1, false)).toBe(false);
expect(boolOr(undefined, true)).toBe(true);
expect(boolOr(null, true)).toBe(true);
});
});
describe('clampNum', () => {
it('passes finite numbers through, clamped to [min,max]', () => {
expect(clampNum(5, 0, 10, -1)).toBe(5);
expect(clampNum(-3, 0, 10, -1)).toBe(0); // below min
expect(clampNum(99, 0, 10, -1)).toBe(10); // above max
});
it('coerces numeric strings', () => {
expect(clampNum('7', 0, 10, -1)).toBe(7);
expect(clampNum('7.5', 0, 10, -1)).toBe(7.5); // NOT truncated (that is clampInt)
});
it('falls back on non-finite / non-numeric input', () => {
expect(clampNum('abc', 0, 10, 3)).toBe(3);
expect(clampNum(NaN, 0, 10, 3)).toBe(3);
expect(clampNum(Infinity, 0, 10, 3)).toBe(3);
expect(clampNum(undefined, 0, 10, 3)).toBe(3);
expect(clampNum(null, 0, 10, 3)).toBe(3);
expect(clampNum({}, 0, 10, 3)).toBe(3);
});
it('preserves fractional precision within bounds', () => {
expect(clampNum(0.42, 0, 1, 0)).toBe(0.42);
});
});
describe('clampInt', () => {
it('is clampNum truncated toward zero', () => {
expect(clampInt(7.9, 0, 10, -1)).toBe(7);
expect(clampInt('7.9', 0, 10, -1)).toBe(7);
expect(clampInt(5, 0, 10, -1)).toBe(5);
});
it('clamps before truncating', () => {
expect(clampInt(99.9, 0, 10, -1)).toBe(10);
expect(clampInt(-3.5, 0, 10, -1)).toBe(0);
});
it('clamp-then-trunc ordering: a fractional lower bound is crossed by the clamp, not the trunc', () => {
// Distinguishes clamp→trunc (this contract) from trunc→clamp: input 2.4
// with min 2.5 → clamp lifts to 2.5, then trunc → 2. A trunc-first impl
// would floor to 2 then clamp up to 2.5. Pins the order for the shared
// primitive (future callers may use fractional bounds).
expect(clampInt(2.4, 2.5, 10, 0)).toBe(2);
});
it('falls back on non-finite input', () => {
expect(clampInt('abc', 0, 10, 4)).toBe(4);
expect(clampInt(NaN, 0, 10, 4)).toBe(4);
expect(clampInt(undefined, 0, 10, 4)).toBe(4);
});
});

View File

@@ -0,0 +1,68 @@
import { describe, it, expect } from 'vitest';
import { mapWithConcurrency } from '../src/concurrency';
const tick = () => new Promise<void>((r) => setTimeout(r, 0));
describe('mapWithConcurrency', () => {
it('returns results in input order', async () => {
const out = await mapWithConcurrency([1, 2, 3, 4, 5], 2, async (n) => n * 10);
expect(out).toEqual([10, 20, 30, 40, 50]);
});
it('passes the absolute index (across batch boundaries)', async () => {
const seen: Array<[number, number]> = [];
await mapWithConcurrency(['a', 'b', 'c', 'd', 'e'], 2, async (item, i) => {
seen.push([i, item.charCodeAt(0)]);
return i;
});
expect(seen.map(([i]) => i).sort((x, y) => x - y)).toEqual([0, 1, 2, 3, 4]);
});
it('never runs more than `concurrency` at once (batched), and serializes across batches', async () => {
let inFlight = 0;
let peak = 0;
const order: number[] = [];
await mapWithConcurrency([0, 1, 2, 3, 4, 5, 6], 3, async (n) => {
inFlight++;
peak = Math.max(peak, inFlight);
await tick();
order.push(n);
inFlight--;
return n;
});
expect(peak).toBeLessThanOrEqual(3);
// batched: first 3 (0,1,2) settle before the next batch (3,4,5) starts.
expect(order.slice(0, 3).sort((a, b) => a - b)).toEqual([0, 1, 2]);
expect(order.slice(3, 6).sort((a, b) => a - b)).toEqual([3, 4, 5]);
expect(order[6]).toBe(6);
});
it('handles a length not divisible by concurrency (short final batch)', async () => {
const out = await mapWithConcurrency([1, 2, 3, 4, 5], 3, async (n) => n);
expect(out).toEqual([1, 2, 3, 4, 5]);
});
it('runs everything in one batch when concurrency >= length', async () => {
let peak = 0, inFlight = 0;
const out = await mapWithConcurrency([1, 2, 3], 10, async (n) => {
inFlight++; peak = Math.max(peak, inFlight); await tick(); inFlight--; return n;
});
expect(out).toEqual([1, 2, 3]);
expect(peak).toBe(3);
});
it('returns [] for an empty input without calling fn', async () => {
let called = 0;
const out = await mapWithConcurrency([], 4, async (n) => { called++; return n; });
expect(out).toEqual([]);
expect(called).toBe(0);
});
it('treats concurrency < 1 as 1 (fully serial)', async () => {
let peak = 0, inFlight = 0;
await mapWithConcurrency([1, 2, 3], 0, async (n) => {
inFlight++; peak = Math.max(peak, inFlight); await tick(); inFlight--; return n;
});
expect(peak).toBe(1);
});
});

View File

@@ -0,0 +1,26 @@
import { describe, expect, it } from 'vitest';
import { fromHex, hexPreview, toHex, toHexUpper } from '../src/hex';
describe('hex', () => {
it('toHex / toHexUpper render bytes as zero-padded hex', () => {
const b = Uint8Array.from([0x00, 0x0f, 0xa0, 0xff]);
expect(toHex(b)).toBe('000fa0ff');
expect(toHexUpper(b)).toBe('000FA0FF');
expect(toHex(Uint8Array.of())).toBe('');
});
it('hexPreview appends "..." only past maxBytes', () => {
const b = Uint8Array.from([1, 2, 3, 4, 5]);
expect(hexPreview(b)).toBe('0102030405'); // under the default 64-byte cap
expect(hexPreview(b, 5)).toBe('0102030405'); // exactly at the cap → no ellipsis
expect(hexPreview(b, 2)).toBe('0102...'); // truncated
expect(hexPreview(b, 0)).toBe('...'); // nothing shown, but bytes remain
});
it('fromHex round-trips toHex and rejects odd-length input', () => {
const b = Buffer.from([0xde, 0xad, 0xbe, 0xef]);
expect(fromHex(toHex(b)).equals(b)).toBe(true);
expect(toHex(fromHex('00ffa0'))).toBe('00ffa0');
expect(() => fromHex('abc')).toThrow();
});
});

View File

@@ -0,0 +1,61 @@
import { describe, expect, it } from 'vitest';
import { renderParamsVerbose, summarizeParams } from '../src/log-summary';
describe('summarizeParams', () => {
it('renders null/undefined as {}', () => {
expect(summarizeParams(null)).toBe('{}');
expect(summarizeParams(undefined)).toBe('{}');
});
it('renders a top-level non-object via String() WITHOUT quotes', () => {
// The reported change-request: a top-level primitive is NOT JSON-quoted.
expect(summarizeParams('hello')).toBe('hello');
expect(summarizeParams(123)).toBe('123');
});
it('collapses a top-level array to [len=N]', () => {
expect(summarizeParams([1, 2, 3])).toBe('[len=3]');
});
it('quotes string fields, collapses nested values, truncates long strings', () => {
expect(summarizeParams({ a: 1, b: 'x', c: { d: 1 }, e: [1, 2] }))
.toBe('a=1 b="x" c={...} e=[len=2]');
expect(summarizeParams({ s: 'x'.repeat(50) }))
.toBe(`s="${'x'.repeat(40)}..."`);
});
it('caps total output and appends "..." on overflow', () => {
const big: Record<string, number> = {};
for (let i = 0; i < 60; i++) big['key' + i] = i;
const out = summarizeParams(big);
expect(out.startsWith('key0=0')).toBe(true);
expect(out.endsWith('...')).toBe(true);
});
});
describe('renderParamsVerbose', () => {
it('redacts token / password / secret keys at any depth', () => {
const out = renderParamsVerbose({ token: 'abc', password: 'p', nested: { secret: 's' }, ok: 'v' });
expect(out).toContain('token:"***"');
expect(out).toContain('password:"***"');
expect(out).toContain('secret:"***"');
expect(out).toContain('ok:"v"');
});
it('truncates long strings with a Unicode ellipsis + byte count (not ASCII dots)', () => {
// The reported change-request: the marker is `…<N B>` (U+2026), not `...<N B>`.
const out = renderParamsVerbose({ blob: 'a'.repeat(500) });
expect(out).toContain('…<500B>');
expect(out).not.toContain('...<500B>');
});
it('guards against circular references', () => {
const o: Record<string, unknown> = { a: 1 };
o.self = o;
expect(renderParamsVerbose(o)).toContain('"[circular]"');
});
it('renders nested structure with primitives intact', () => {
expect(renderParamsVerbose({ a: 1, b: [true, 'x'] })).toBe('{a:1,b:[true,"x"]}');
});
});

View File

@@ -0,0 +1,45 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
// The file transport writes to disk; stub it so the test has no side effects.
vi.mock('../src/log-file-transport', () => ({
getFileTransport: () => ({ write: () => {} }),
}));
import { createLogger } from '../src/logger';
// Regression for issue #162: a hook-reported garbage UIN (13-digit, timestamp
// shaped) produced a `[…]` tag wider than the fixed UIN slot, and the colored
// render path did `' '.repeat(slot - tagLen)` → RangeError: Invalid count value
// → uncaughtException. The padding must clamp at zero.
describe('logger UIN slot padding', () => {
let prevTTY: boolean | undefined;
let prevNoColor: string | undefined;
beforeEach(() => {
prevTTY = process.stdout.isTTY;
prevNoColor = process.env.NO_COLOR;
// Force the colored render path (the only one that used .repeat()).
(process.stdout as unknown as { isTTY: boolean }).isTTY = true;
delete process.env.NO_COLOR;
vi.spyOn(process.stdout, 'write').mockReturnValue(true);
vi.spyOn(process.stderr, 'write').mockReturnValue(true);
});
afterEach(() => {
(process.stdout as unknown as { isTTY: boolean | undefined }).isTTY = prevTTY;
if (prevNoColor === undefined) delete process.env.NO_COLOR;
else process.env.NO_COLOR = prevNoColor;
vi.restoreAllMocks();
});
it('does not throw when the UIN tag exceeds the slot width', () => {
const log = createLogger('Test').child({ uin: '1701414379536' }); // 13-digit → [..] = 15 chars
expect(() => log.info('phantom account line')).not.toThrow();
expect(() => log.error('phantom error line')).not.toThrow();
});
it('still renders a normal-width UIN and a no-UIN logger', () => {
expect(() => createLogger('Test').child({ uin: '10001' }).info('ok')).not.toThrow();
expect(() => createLogger('Test').info('no uin')).not.toThrow();
});
});

View File

@@ -0,0 +1,34 @@
import { describe, expect, it } from 'vitest';
import { currentRequestId, nextRequestId, runWithRequestId } from '../src/request-context';
describe('request-context', () => {
it('nextRequestId increments monotonically and stays a positive integer', () => {
const a = nextRequestId();
const b = nextRequestId();
expect(a).toBeGreaterThan(0);
expect(b).toBe(a + 1);
});
it('runWithRequestId binds the id across sync + async, with nested scopes restoring', async () => {
expect(currentRequestId()).toBeUndefined();
runWithRequestId(42, () => {
expect(currentRequestId()).toBe(42);
runWithRequestId(99, () => {
expect(currentRequestId()).toBe(99);
});
expect(currentRequestId()).toBe(42); // outer scope restored after the nested one
});
expect(currentRequestId()).toBeUndefined(); // cleared outside any scope
await runWithRequestId(7, async () => {
await Promise.resolve();
expect(currentRequestId()).toBe(7); // survives awaits in the same async chain
});
});
it('returns the callback result', () => {
expect(runWithRequestId(1, () => 'value')).toBe('value');
});
});

View File

@@ -0,0 +1,117 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { normalizeRuntimeConfig, resolveRuntimeEnvOverrides } from '../src/runtime';
describe('normalizeRuntimeConfig', () => {
it('applies all defaults for an empty object', () => {
expect(normalizeRuntimeConfig({})).toEqual({
webuiPort: 5099,
hookAutoLoad: false,
webuiHost: '0.0.0.0',
webuiTls: { enabled: false },
trustProxy: '',
});
});
it('passes through valid values', () => {
expect(normalizeRuntimeConfig({
webuiPort: 8080,
hookAutoLoad: true,
webuiHost: '127.0.0.1',
webuiTls: { enabled: true },
trustProxy: '1',
})).toEqual({
webuiPort: 8080,
hookAutoLoad: true,
webuiHost: '127.0.0.1',
webuiTls: { enabled: true },
trustProxy: '1',
});
});
it('falls back on invalid types', () => {
const out = normalizeRuntimeConfig({
webuiPort: 0, // out of range → default
webuiHost: 123, // non-string → default
webuiTls: 'yes', // non-object → default
trustProxy: 5, // non-string → default
});
expect(out.webuiPort).toBe(5099);
expect(out.webuiHost).toBe('0.0.0.0');
expect(out.webuiTls).toEqual({ enabled: false });
expect(out.trustProxy).toBe('');
});
it('coerces webuiTls.enabled loosely and trims a blank host to default', () => {
expect(normalizeRuntimeConfig({ webuiTls: { enabled: 1 } }).webuiTls).toEqual({ enabled: true });
expect(normalizeRuntimeConfig({ webuiHost: ' ' }).webuiHost).toBe('0.0.0.0');
});
it('rejects a non-object input back to full defaults', () => {
expect(normalizeRuntimeConfig(null).webuiPort).toBe(5099);
expect(normalizeRuntimeConfig('nope').webuiHost).toBe('0.0.0.0');
});
});
describe('resolveRuntimeEnvOverrides', () => {
it('returns empty when no SNOWLUMA_* vars are set', () => {
expect(resolveRuntimeEnvOverrides({})).toEqual({});
});
it('parses port / host / trustProxy from env', () => {
expect(resolveRuntimeEnvOverrides({
SNOWLUMA_WEBUI_PORT: '6700',
SNOWLUMA_WEBUI_HOST: '127.0.0.1',
SNOWLUMA_WEBUI_TRUST_PROXY: '1',
})).toEqual({ webuiPort: 6700, webuiHost: '127.0.0.1', trustProxy: '1' });
});
it('ignores an out-of-range / non-numeric port env', () => {
expect(resolveRuntimeEnvOverrides({ SNOWLUMA_WEBUI_PORT: '0' })).toEqual({});
expect(resolveRuntimeEnvOverrides({ SNOWLUMA_WEBUI_PORT: 'abc' })).toEqual({});
});
it('treats trustProxy="0"/"off" as a real override (not absent)', () => {
expect(resolveRuntimeEnvOverrides({ SNOWLUMA_WEBUI_TRUST_PROXY: '0' })).toEqual({ trustProxy: '0' });
});
});
describe('updateRuntimeConfig (fs)', () => {
let prevCwd: string;
let dir: string;
let prevPortEnv: string | undefined;
beforeEach(async () => {
const fs = await import('fs'); const os = await import('os'); const path = await import('path');
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sl-rt-'));
prevCwd = process.cwd();
process.chdir(dir);
prevPortEnv = process.env.SNOWLUMA_WEBUI_PORT;
delete process.env.SNOWLUMA_WEBUI_PORT;
});
afterEach(async () => {
const fs = await import('fs');
process.chdir(prevCwd);
if (prevPortEnv === undefined) delete process.env.SNOWLUMA_WEBUI_PORT;
else process.env.SNOWLUMA_WEBUI_PORT = prevPortEnv;
fs.rmSync(dir, { recursive: true, force: true });
});
it('merges a patch over on-disk values and persists normalized', async () => {
const { updateRuntimeConfig } = await import('../src/runtime');
const fs = await import('fs'); const path = await import('path');
const out = updateRuntimeConfig({ webuiHost: '127.0.0.1', webuiTls: { enabled: true } });
expect(out.webuiHost).toBe('127.0.0.1');
expect(out.webuiTls).toEqual({ enabled: true });
const onDisk = JSON.parse(fs.readFileSync(path.join('config', 'runtime.json'), 'utf8'));
expect(onDisk.webuiHost).toBe('127.0.0.1');
expect(onDisk.webuiTls).toEqual({ enabled: true });
});
it('does NOT bake an env-overridden port into the persisted file', async () => {
const { updateRuntimeConfig } = await import('../src/runtime');
const fs = await import('fs'); const path = await import('path');
process.env.SNOWLUMA_WEBUI_PORT = '9999';
updateRuntimeConfig({ webuiHost: '127.0.0.1' });
const onDisk = JSON.parse(fs.readFileSync(path.join('config', 'runtime.json'), 'utf8'));
expect(onDisk.webuiPort).toBe(5099); // default on-disk, NOT the env 9999
});
});

View File

@@ -0,0 +1,131 @@
import { describe, it, expect, vi } from 'vitest';
import { createSingleFlightCache } from '../src/single-flight-cache';
/** A promise whose resolve/reject is exposed, for driving single-flight races. */
function deferred<T>() {
let resolve!: (v: T) => void;
let reject!: (e: unknown) => void;
const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej; });
return { promise, resolve, reject };
}
describe('SingleFlightCache', () => {
it('caches within the TTL and reloads once expired', async () => {
let clock = 1000;
const load = vi.fn(async (k: string) => `${k}@${clock}`);
const cache = createSingleFlightCache<string, string>({ ttlMs: 100, load, now: () => clock });
expect(await cache.get('a')).toBe('a@1000');
clock = 1050; // still fresh (< 100)
expect(await cache.get('a')).toBe('a@1000');
expect(load).toHaveBeenCalledTimes(1);
clock = 1101; // 101ms since store → expired
expect(await cache.get('a')).toBe('a@1101');
expect(load).toHaveBeenCalledTimes(2);
});
it('de-dupes concurrent callers onto a single load (single-flight)', async () => {
const d = deferred<string>();
const load = vi.fn(() => d.promise);
const cache = createSingleFlightCache<string, string>({ ttlMs: 1000, load });
const p1 = cache.get('k');
const p2 = cache.get('k');
const p3 = cache.get('k');
expect(load).toHaveBeenCalledTimes(1); // only one load in flight
d.resolve('v');
expect(await Promise.all([p1, p2, p3])).toEqual(['v', 'v', 'v']);
expect(load).toHaveBeenCalledTimes(1);
});
it('keys independently — different keys load separately', async () => {
const load = vi.fn(async (k: number) => k * 2);
const cache = createSingleFlightCache<number, number>({ ttlMs: 1000, load });
expect(await cache.get(1)).toBe(2);
expect(await cache.get(2)).toBe(4);
expect(load).toHaveBeenCalledTimes(2);
});
it('force bypasses the freshness check but still joins an in-flight load', async () => {
let clock = 0;
const load = vi.fn(async (k: string) => `${k}@${clock}`);
const cache = createSingleFlightCache<string, string>({ ttlMs: 10_000, load, now: () => clock });
expect(await cache.get('a')).toBe('a@0'); // 1 load, cached fresh
clock = 5; // still fresh
expect(await cache.get('a', { force: true })).toBe('a@5'); // force → reload despite fresh
expect(load).toHaveBeenCalledTimes(2);
// force still single-flights: two concurrent forced gets share one load.
const d = deferred<string>();
load.mockImplementationOnce(() => d.promise);
const p1 = cache.get('a', { force: true });
const p2 = cache.get('a', { force: true });
expect(load).toHaveBeenCalledTimes(3); // not 4
d.resolve('shared');
expect(await Promise.all([p1, p2])).toEqual(['shared', 'shared']);
});
it('shouldCache=false leaves the entry uncached (next call reloads) but still de-dupes in-flight', async () => {
let n = 0;
const load = vi.fn(async () => ({ error: true as boolean, n: ++n }));
const cache = createSingleFlightCache({ ttlMs: 10_000, load, shouldCache: (v) => !v.error });
// concurrent callers still share one load...
const [a, b] = await Promise.all([cache.get('k'), cache.get('k')]);
expect(a).toEqual({ error: true, n: 1 });
expect(b).toEqual({ error: true, n: 1 });
expect(load).toHaveBeenCalledTimes(1);
// ...but nothing was cached, so the next call reloads.
expect(await cache.get('k')).toEqual({ error: true, n: 2 });
expect(load).toHaveBeenCalledTimes(2);
// a good result IS cached.
load.mockImplementationOnce(async () => ({ error: false, n: ++n }));
const good = await cache.get('k');
expect(good).toEqual({ error: false, n: 3 });
expect(await cache.get('k')).toEqual({ error: false, n: 3 }); // served from cache
expect(load).toHaveBeenCalledTimes(3);
});
it('a rejected load propagates to all joined callers, is not cached, and clears in-flight', async () => {
let attempt = 0;
const load = vi.fn(async () => {
attempt++;
if (attempt === 1) throw new Error('boom');
return 'ok';
});
const cache = createSingleFlightCache<string, string>({ ttlMs: 10_000, load });
const p1 = cache.get('k');
const p2 = cache.get('k');
await expect(p1).rejects.toThrow('boom');
await expect(p2).rejects.toThrow('boom'); // same in-flight, same rejection
expect(load).toHaveBeenCalledTimes(1);
// in-flight cleared + not cached → next call retries and succeeds.
expect(await cache.get('k')).toBe('ok');
expect(load).toHaveBeenCalledTimes(2);
});
it('invalidate drops a cached entry; clear drops all', async () => {
const load = vi.fn(async (k: string) => k.toUpperCase());
const cache = createSingleFlightCache<string, string>({ ttlMs: 10_000, load });
await cache.get('a');
await cache.get('b');
expect(load).toHaveBeenCalledTimes(2);
cache.invalidate('a');
await cache.get('a'); // reloads
await cache.get('b'); // still cached
expect(load).toHaveBeenCalledTimes(3);
cache.clear();
await cache.get('a');
await cache.get('b');
expect(load).toHaveBeenCalledTimes(5);
});
});

View File

@@ -0,0 +1,40 @@
import { describe, expect, it } from 'vitest';
import { isRealUin } from '../src/uin';
describe('isRealUin', () => {
it('accepts real QQ UINs (5..10 digits)', () => {
expect(isRealUin('10001')).toBe(true); // 5-digit floor
expect(isRealUin('123456789')).toBe(true);
expect(isRealUin('4294967295')).toBe(true); // uint32 max, 10 digits
});
it('rejects the empty string and "0"', () => {
expect(isRealUin('')).toBe(false);
expect(isRealUin('0')).toBe(false);
});
it('rejects too-short UINs (< 5 digits)', () => {
expect(isRealUin('1')).toBe(false);
expect(isRealUin('1234')).toBe(false);
});
it('rejects the garbage timestamp-shaped UINs from issue #162 (11+ digits)', () => {
expect(isRealUin('1701414379536')).toBe(false); // 13-digit ms timestamp
expect(isRealUin('1614019567632')).toBe(false);
expect(isRealUin('2014024115056')).toBe(false);
expect(isRealUin('12345678901')).toBe(false); // 11 digits — first rejected width
});
it('rejects non-digit strings (path traversal / injection guards)', () => {
expect(isRealUin('12345a')).toBe(false);
expect(isRealUin('12 345')).toBe(false);
expect(isRealUin('../etc')).toBe(false);
expect(isRealUin('123456\n')).toBe(false);
});
it('guarantees a BigInt-safe pure-digit string on accept', () => {
const uin = '123456789';
expect(isRealUin(uin)).toBe(true);
expect(() => BigInt(uin)).not.toThrow();
});
});

View File

@@ -0,0 +1,10 @@
// Vitest config for @snowluma/common. Pure-TS package (no proton), so a
// plain node-environment runner over tests/ is enough.
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
include: ['tests/**/*.test.ts'],
environment: 'node',
},
});

16
packages/core/config/.gitignore vendored Normal file
View File

@@ -0,0 +1,16 @@
# Per-instance runtime state written by the dev server / production daemon.
# `runtime.json` is the only tracked file (the deploy-time overrides for
# webuiPort, hookAutoLoad, etc); everything else here is operator-private:
# * webui.json — admin password hash + rotation state
# * consent.json — EULA/PRIVACY acceptance per agreement version
# * notifications.json — per-account webhook destinations
# * onebot_<uin>.json — per-uin OneBot transport binding (HTTP/WS ports etc)
# * ui.json — WebUI panel layout per operator
#
# Without this ignore file, every `pnpm dev:mode` / `node dist/index.mjs`
# leaves a 5-file untracked surface in `packages/core/config/` that pollutes
# `git status` and would accidentally commit local creds if `git add -A` is used.
*
!.gitignore
!runtime.json

View File

@@ -1,6 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/core",
"version": "1.9.2",
"version": "1.11.2",
"description": "SnowLuma core - NTQQ packet sniffer with Node.js native addon",
"private": true,
"type": "module",
@@ -46,7 +47,6 @@
"@snowluma/protocol": "workspace:*",
"@snowluma/proto-defs": "workspace:*",
"@snowluma/proton": "workspace:*",
"@snowluma/sqlite": "workspace:*",
"@snowluma/websocket": "workspace:*"
},
"devDependencies": {
@@ -54,7 +54,7 @@
"@rollup/plugin-node-resolve": "^16.0.3",
"@types/node": "^24.12.2",
"cross-env": "^10.1.0",
"hono": "^4.12.18",
"hono": "^4.12.25",
"tsx": "^4.21.0",
"typescript": "catalog:",
"vite": "catalog:",

View File

@@ -1,10 +1,14 @@
import { FetchDownloadRkeys } from '@snowluma/protocol/oidb-services/contacts/fetch-download-rkeys';
import { FetchFriendListPage } from '@snowluma/protocol/oidb-services/contacts/fetch-friend-list-page';
import { FetchGroupDetail } from '@snowluma/protocol/oidb-services/contacts/fetch-group-detail';
import { FetchGroupList } from '@snowluma/protocol/oidb-services/contacts/fetch-group-list';
import { FetchGroupMemberListPage } from '@snowluma/protocol/oidb-services/contacts/fetch-group-member-list-page';
import { FetchGroupRequests } from '@snowluma/protocol/oidb-services/contacts/fetch-group-requests';
import { FetchUserProfile } from '@snowluma/protocol/oidb-services/contacts/fetch-user-profile';
import { FetchUserProfileByUid } from '@snowluma/protocol/oidb-services/contacts/fetch-user-profile-by-uid';
import { GetBuddyRecommendArk } from '@snowluma/protocol/oidb-services/contacts/get-buddy-recommend-ark';
import { GetGroupRecommendArk } from '@snowluma/protocol/oidb-services/contacts/get-group-recommend-ark';
import { createSingleFlightCache, type SingleFlightCache } from '@snowluma/common/single-flight-cache';
import type {
FriendInfo,
GroupMemberInfo,
@@ -52,19 +56,32 @@ const MEMBER_LIST_TTL_MS = 60_000;
export class ContactsApi {
/**
* Per-group inflight + last-fetch cache for `fetchGroupMemberList`.
* Keyed by groupId, lives for the lifetime of the Bridge.
* Per-group TTL + single-flight cache for `fetchGroupMemberList`, keyed by
* groupId, living for the lifetime of the Bridge.
*
* Without this, a busy OneBot client (e.g. MaiBot calling
* `get_group_member_info` once per inbound message) triggers one
* OIDB 0xfe7_3 per chat message — sustained >1k/h, which trips
* Tencent risk-control and gets the account banned for 7 days.
*/
private memberListInflight = new Map<number, Promise<GroupMemberInfo[]>>();
private memberListLastFetch = new Map<number, { at: number; data: GroupMemberInfo[] }>();
private readonly memberListCache: SingleFlightCache<number, GroupMemberInfo[]> =
createSingleFlightCache({
ttlMs: MEMBER_LIST_TTL_MS,
load: (groupId) => this.fetchGroupMemberListUncached(groupId),
});
constructor(private readonly ctx: BridgeContext) { }
/** Server-built ARK share card (JSON string) recommending a friend. */
getBuddyRecommendArk(userId: number, phoneNumber = ''): Promise<string> {
return GetBuddyRecommendArk.invoke(this.ctx, { userId, phoneNumber });
}
/** Server-built ARK share card (JSON string) recommending a group. */
getGroupRecommendArk(groupId: number): Promise<string> {
return GetGroupRecommendArk.invoke(this.ctx, { groupId });
}
async fetchFriendList(): Promise<FriendInfo[]> {
const friends: FriendInfo[] = [];
let nextUin: number | null = null;
@@ -98,34 +115,48 @@ export class ContactsApi {
memberCount: raw.info?.memberCount ?? 0,
memberMax: raw.info?.memberMax ?? 0,
members: new Map(),
// #197: the list already carries these — no extra fetch needed. `level`
// is not in the list (0x88D_0 detail only), so it stays undefined here.
createTime: raw.info?.createdTime ?? 0,
memo: raw.info?.announcement || raw.info?.description || '',
});
}
this.ctx.identity.rememberGroups(groups);
return groups;
}
async fetchGroupMemberList(
/**
* Fetch a single group's public detail by id via `0x88D_0` — works even for a
* group the bot hasn't joined (used to resolve a group-invite's name). Returns
* null when the server has no such group / denies the lookup. Deliberately
* does NOT `rememberGroups` it — a non-member group must not pollute the
* joined-groups roster / get_group_list.
*/
async fetchGroupDetail(groupId: number): Promise<QQGroupInfo | null> {
if (!(groupId > 0)) return null;
const resp = await FetchGroupDetail.invoke(this.ctx, { groupUin: groupId });
const r = resp.groupInfo?.results;
if (!r) return null;
return {
groupId,
groupName: r.name ?? '',
remark: '',
memberCount: Number(r.memberCount ?? 0n),
memberMax: Number(r.maxMemberCount ?? 0n),
members: new Map(),
// #197: the detail is the only source of `level`; it also carries
// createTime + the notice preview (memo).
createTime: Number(r.createTime ?? 0n),
level: Number(r.level ?? 0n),
memo: r.noticePreview ?? '',
};
}
fetchGroupMemberList(
groupId: number,
options: { force?: boolean } = {},
): Promise<GroupMemberInfo[]> {
const now = Date.now();
const last = this.memberListLastFetch.get(groupId);
if (!options.force && last && now - last.at < MEMBER_LIST_TTL_MS) {
return last.data;
}
const inflight = this.memberListInflight.get(groupId);
if (inflight) return inflight;
const task = (async () => {
try {
const data = await this.fetchGroupMemberListUncached(groupId);
this.memberListLastFetch.set(groupId, { at: Date.now(), data });
return data;
} finally {
this.memberListInflight.delete(groupId);
}
})();
this.memberListInflight.set(groupId, task);
return task;
return this.memberListCache.get(groupId, { force: options.force });
}
private async fetchGroupMemberListUncached(groupId: number): Promise<GroupMemberInfo[]> {
@@ -197,6 +228,13 @@ export class ContactsApi {
return requests;
}
/** The approval msgseq captured from a private "qun.invite" card for this
* group, or undefined if none was seen. `set_group_add_request` uses it to
* approve a bot self-invite via 0x10c8 (eventType=2). See issue #125. */
getGroupInviteCardSequence(groupId: number): number | undefined {
return this.ctx.identity.getGroupInviteCardSequence(groupId);
}
async fetchDownloadRKeys(): Promise<DownloadRKeyInfo[]> {
const resp = await FetchDownloadRkeys.invoke(this.ctx);

View File

@@ -5,9 +5,32 @@ import {
} from '@snowluma/protocol/oidb-services/extras/fetch-ai-voice-list';
import { GetStrangerStatus, type StrangerStatus as NamespaceStrangerStatus } from '@snowluma/protocol/oidb-services/extras/get-stranger-status';
import { GroupTodo } from '@snowluma/protocol/oidb-services/extras/group-todo';
import { convertAudioBytes } from '@snowluma/protocol/highway/ffmpeg-addon';
import { loadBinarySource } from '@snowluma/protocol/highway/utils';
import { createLogger } from '@snowluma/common/logger';
import type { PttTransReq, PttTransResp } from '@snowluma/proto-defs/ptt-trans';
import { protobuf_decode, protobuf_encode } from '@snowluma/proton';
import type { BridgeContext } from '../bridge-context';
import type { MediaIndexNode } from './shared';
/** Inputs for a voice-to-text request, gathered from the received `record`
* element + its message meta. `uuid`/`md5Hex` come from the cached record;
* the uins + scene from the message meta. */
export interface PttTransInput {
isGroup: boolean;
msgId: number;
senderUin: number;
/** Receiver uin (c2c) or group uin (group). */
peerUin: number;
uuid: string;
md5Hex: string;
duration: number;
size: number;
format: number;
/** Group ptt numeric file id (group only; optional). */
fileId?: number;
}
// ─────────────── public types (re-exported from bridge.ts as before) ───
export type StrangerStatus = NamespaceStrangerStatus;
@@ -26,6 +49,8 @@ export interface AiVoiceItem {
voiceExampleUrl: string;
}
const log = createLogger('Bridge.Extras');
export class ExtrasApi {
constructor(private readonly ctx: BridgeContext) { }
@@ -88,4 +113,72 @@ export class ExtrasApi {
}
throw new Error(`AI voice synthesis did not complete after ${maxRetries} polls`);
}
// ─────────────── Voice-to-text (pttTrans.Trans{C2C,Group}PttReq) ───────────────
/**
* Send ONE `pttTrans.Trans{C2C,Group}PttReq` to trigger transcription and
* return the recognised text IF the response carries it inline (the
* already-transcribed case). For a freshly-received voice the response is an
* empty ack and the text is delivered later via the async Event 0x210
* subType-61 push — callers should treat `''` as "pending" and wait for the
* `ptt_trans_result` event (correlated by msgId).
*/
async translatePttToText(input: PttTransInput): Promise<string> {
// QQ NT sends the md5 as a 32-char lowercase HEX STRING, not the raw 16
// bytes (RE'd from wrapper.linux.node EncodeTroopPtt/EncodeC2CPtt: the md5
// field goes through a bytes→hex helper). Sending raw bytes → errCode -1079.
const md5 = input.md5Hex.toLowerCase();
const req: PttTransReq = input.isGroup
? {
type: 1,
groupItem: {
msgId: BigInt(input.msgId), senderUin: BigInt(input.senderUin), groupUin: BigInt(input.peerUin),
fileId: input.fileId ?? 0, md5, duration: input.duration, size: input.size,
format: input.format, uuid: input.uuid,
},
}
: {
type: 2,
c2cItem: {
msgId: BigInt(input.msgId), senderUin: BigInt(input.senderUin), receiverUin: BigInt(input.peerUin),
uuid: input.uuid, duration: input.duration, size: input.size, format: input.format, md5,
},
};
const cmd = input.isGroup ? 'pttTrans.TransGroupPttReq' : 'pttTrans.TransC2CPttReq';
const result = await this.ctx.sendRawPacket(cmd, protobuf_encode<PttTransReq>(req));
if (!result.success || !result.gotResponse || !result.responseData) {
throw new Error(result.errorMessage || 'ptt translate request failed');
}
const resp = protobuf_decode<PttTransResp>(result.responseData);
const item = input.isGroup ? resp?.groupResult : resp?.c2cResult;
if (item?.errCode) {
// Diagnostic (#165 备选): correlate QQ's errCode with the request fields we
// sourced from cache, to tell a server-side ASR failure apart from our own
// missing/zero field (md5/format/uuid). Behaviour unchanged — still throws.
log.warn(
'ptt translate errCode=%d isGroup=%s md5=%s format=%d uuid=%s dur=%d size=%d',
item.errCode, input.isGroup,
input.md5Hex ? `${input.md5Hex.length / 2}B` : 'EMPTY',
input.format, input.uuid ? 'set' : 'EMPTY', input.duration, input.size,
);
throw new Error(`ptt translate failed: error=${item.errCode}`);
}
return item?.text ?? ''; // '' = transcribing async; caller awaits the push
}
/**
* Transcode a voice record (`get_record out_format`, #165). `source` is a
* URL / local path / `base64://…` (the record's download URL in practice);
* it is loaded then transcoded to `format` via the bundled SILK-capable
* ffmpeg addon. Returns base64 + size. Throws on unsupported format or a
* failed conversion.
*/
async convertRecord(source: string, format: string): Promise<{ base64: string; size: number }> {
// Voices are tiny — cap the download well below loadBinarySource's 1 GiB
// default so a tampered/oversized source can't be pulled in.
const { bytes } = await loadBinarySource(source, 'record', 64 * 1024 * 1024);
return convertAudioBytes(bytes, format);
}
}

View File

@@ -0,0 +1,456 @@
// FlashTransferApi — 闪传(fileset)业务编排。
// 复用 OIDB 基础设施(invokeOidb),协议层在 @snowluma/protocol/oidb-services/flash-transfer/。
import type { BridgeContext } from '../bridge-context';
import { resolveSelfUid } from './shared';
import type { FlashFileEntry } from '@snowluma/proto-defs/oidb-actions/flash-transfer';
import { GetFilesetDetail } from '@snowluma/protocol/oidb-services/flash-transfer/get-fileset-detail';
import { ListFilesets } from '@snowluma/protocol/oidb-services/flash-transfer/list-filesets';
import { GetDownloadUrl } from '@snowluma/protocol/oidb-services/flash-transfer/get-download-url';
import { GetFlashDownload } from '@snowluma/protocol/oidb-services/flash-transfer/get-flash-download';
import { DeleteFlashFile } from '@snowluma/protocol/oidb-services/flash-transfer/delete-file';
import { RenameFlashFile } from '@snowluma/protocol/oidb-services/flash-transfer/rename-file';
import { ApplyFileset } from '@snowluma/protocol/oidb-services/flash-transfer/apply-fileset';
import { CommitFile } from '@snowluma/protocol/oidb-services/flash-transfer/commit-file';
import { CompleteFileset } from '@snowluma/protocol/oidb-services/flash-transfer/complete-fileset';
import { SetFilesetStatus } from '@snowluma/protocol/oidb-services/flash-transfer/set-status';
import { ApplyUpload } from '@snowluma/protocol/oidb-services/flash-transfer/apply-upload';
import { PrepareUpload } from '@snowluma/protocol/oidb-services/flash-transfer/prepare-upload';
import { SendFlashMsg } from '@snowluma/protocol/oidb-services/flash-transfer/send-flash';
import { loadBinarySource, computeHashes } from '@snowluma/protocol/highway/utils';
import { computeSha1StateV } from '@snowluma/protocol/highway/sha1-stream';
import { protobuf_encode, protobuf_decode } from '@snowluma/proton';
import type { FlashSliceUploadBody, FlashSliceUploadResp, FlashFileId } from '@snowluma/proto-defs/oidb-actions/flash-transfer';
import { randomUUID, randomBytes, createHash } from 'node:crypto';
import { deflateSync } from 'node:zlib';
/** 闪传文件信息(业务层,从 FlashFileEntry 转换)。 */
export interface FlashFileInfo {
filesetUuid: string;
fileName: string;
origName: string;
fileSize: number;
/** 上传/分享链接 qfile.qq.com/q/<code>。 */
shareUrl: string;
fileId: string;
/** 下载链接 multimedia.qfile.qq.com/download?...&rkey=... */
downloadUrl: string;
}
function entryToInfo(e: FlashFileEntry): FlashFileInfo {
return {
filesetUuid: e.filesetUuid ?? '',
fileName: e.fileName ?? '',
origName: e.origName ?? '',
fileSize: Number(e.fileSize ?? 0),
shareUrl: e.uploadUrlWrap?.uploadUrl ?? '',
fileId: e.fileIdWrap?.fileId ?? '',
downloadUrl: e.fileIdWrap?.download?.downloadUrl ?? '',
};
}
// 手写 PNG 编码(zlib 压缩,避免引入图像库)。缩略图用随机纯色,每次 SHA1 不同,
// 避免命中服务端秒传缓存。
const CRC_TABLE: Uint32Array = (() => {
const table = new Uint32Array(256);
for (let n = 0; n < 256; n++) {
let c = n;
for (let k = 0; k < 8; k++) c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
table[n] = c >>> 0;
}
return table;
})();
function crc32(buf: Buffer): number {
let c = 0xFFFFFFFF;
for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xFF] ^ (c >>> 8);
return (c ^ 0xFFFFFFFF) >>> 0;
}
function pngChunk(type: string, data: Buffer): Buffer {
const len = Buffer.alloc(4);
len.writeUInt32BE(data.length, 0);
const typeBuf = Buffer.from(type, 'ascii');
const crc = crc32(Buffer.concat([typeBuf, data]));
const crcBuf = Buffer.alloc(4);
crcBuf.writeUInt32BE(crc, 0);
return Buffer.concat([len, typeBuf, data, crcBuf]);
}
/** 生成 width×height 随机纯色 PNG(8-bit RGB)。每次随机颜色,SHA1 不同以避免秒传。 */
function generatePng(width: number, height: number): Buffer {
const r = Math.floor(Math.random() * 256);
const g = Math.floor(Math.random() * 256);
const b = Math.floor(Math.random() * 256);
const rowLen = 1 + width * 3;
const raw = Buffer.alloc(rowLen * height);
for (let y = 0; y < height; y++) {
const off = y * rowLen;
raw[off] = 0; // filter none
for (let x = 0; x < width; x++) {
raw[off + 1 + x * 3] = r;
raw[off + 1 + x * 3 + 1] = g;
raw[off + 1 + x * 3 + 2] = b;
}
}
const compressed = deflateSync(raw);
const sig = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
const ihdr = Buffer.alloc(13);
ihdr.writeUInt32BE(width, 0);
ihdr.writeUInt32BE(height, 4);
ihdr[8] = 8; // bit depth
ihdr[9] = 2; // color type RGB
ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;
return Buffer.concat([sig, pngChunk('IHDR', ihdr), pngChunk('IDAT', compressed), pngChunk('IEND', Buffer.alloc(0))]);
}
export class FlashTransferApi {
constructor(private readonly ctx: BridgeContext) { }
/** 获取文件集信息(get_fileset_info)。 */
async getFilesetInfo(filesetUuid: string): Promise<FlashFileInfo[]> {
const entries = await GetFilesetDetail.invoke(this.ctx, { filesetUuid });
return entries.map(entryToInfo);
}
/** 获取闪传文件列表(get_flash_file_list)。同 getFilesetInfo,返回文件数组。 */
async getFlashFileList(filesetUuid: string): Promise<FlashFileInfo[]> {
return this.getFilesetInfo(filesetUuid);
}
/**
* 拿指定文件的下载直链 + 元信息。0x93d4 返回 fileset 内所有文件(f3 repeated,
* 多文件时每条 f6=序号、f14=主文件 fileId),按 fileIndex 选中后走 0x12a9 sub=200
* 拿主文件直链。0x93d3/0x93d4 的 downloadUrl 字段是缩略图(appid=14903/14902),
* 主文件必须走 0x12a9 sub=200。
*/
private async getFileDownload(
filesetUuid: string, fileIndex: number = 1,
): Promise<{ url: string; fileName: string; fileSize: number } | null> {
const metas = await GetDownloadUrl.invoke(this.ctx, { filesetUuid });
const meta = metas.find((m) => m.fileIndex === fileIndex);
if (!meta || !meta.fileId) return null;
const url = await GetFlashDownload.invoke(this.ctx, {
filesetUuid: meta.filesetUuid,
fileUuid: meta.fileUuid,
fileId: meta.fileId,
fileName: meta.fileName,
});
if (!url) return null;
return { url, fileName: meta.fileName, fileSize: meta.fileSize };
}
/**
* 获取闪传文件下载链接(get_flash_file_url)。主文件直链走 0x12a9 sub=200
* (0x93d3 的 downloadUrl 是缩略图 appid=14903,非主文件)。多文件 fileset 用
* fileIndex 指定第几个文件(默认 1)。找不到文件或拿不到直链时抛错。
*/
async getFlashFileUrl(filesetUuid: string, fileIndex: number = 1): Promise<string> {
const dl = await this.getFileDownload(filesetUuid, fileIndex);
if (!dl || !dl.url) throw new Error('get_flash_file_url: no download url available');
return dl.url;
}
/**
* 解析闪传文件下载直链(download_fileset)。返回指定文件的下载 URL + 文件名/大小,
* 不下载文件内容(由调用方拉)。多文件 fileset 用 fileIndex 指定第几个文件(默认 1)。
*/
async downloadFileset(
filesetUuid: string,
opts?: { fileName?: string; fileIndex?: number },
): Promise<{ url: string; fileName: string; fileSize: number }> {
const dl = await this.getFileDownload(filesetUuid, opts?.fileIndex ?? 1);
if (!dl || !dl.url) throw new Error('download_fileset: no download url available');
return dl;
}
/** 获取分享链接(get_share_link)= qfile.qq.com/q/<code>。 */
async getShareLink(filesetUuid: string): Promise<string> {
const entries = await GetFilesetDetail.invoke(this.ctx, { filesetUuid });
return entries.find((e) => e.uploadUrlWrap?.uploadUrl)?.uploadUrlWrap?.uploadUrl ?? '';
}
/** 列出当前账号的所有 fileset(OneBot 标准未定义,QQ 面板有此入口)。 */
async listFilesets(): Promise<FlashFileInfo[]> {
const entries = await ListFilesets.invoke(this.ctx, {});
return entries.map(entryToInfo);
}
/** 删除闪传文件(delete_flash_file)。 */
async deleteFlashFile(filesetUuid: string): Promise<void> {
await DeleteFlashFile.invoke(this.ctx, { filesetUuid });
}
/** 重命名闪传文件(rename_flash_file)。 */
async renameFlashFile(filesetUuid: string, newName: string): Promise<void> {
await RenameFlashFile.invoke(this.ctx, { filesetUuid, newName });
}
/**
* 发送闪传文件(send_flash_msg,0x93d7)。私聊:user_id→uid;群聊:group_id 直接用。
* 0x93d7 响应无 message_id(分享 fileset,非传统消息),OneBot 层 message_id 由 action 返回 0。
*/
async sendFlashMsg(filesetUuid: string, target: { userId?: number; groupId?: number }): Promise<void> {
if (target.groupId) {
await SendFlashMsg.invoke(this.ctx, { groupId: target.groupId, filesetUuid });
return;
}
const userId = target.userId;
if (!userId) throw new Error('send_flash_msg: user_id or group_id is required');
const targetUid = await this.ctx.identity.resolveUid(userId);
await SendFlashMsg.invoke(this.ctx, { targetUid, filesetUuid });
}
/**
* 从分享码/链接获取 fileset_id(get_fileset_id)。code→UUID 不走 OIDB,QQ 客户端
* 走 trpc HTTP API;分享页 qfile.qq.com/q/<code> 的 HTML 内嵌了 fileset_id(trpc
* 接口数据),直接 GET + 正则提取即可,无需复刻带签名的 trpc 调用。
*/
async getFilesetIdByCode(shareCode: string): Promise<string> {
const url = /^https?:\/\//i.test(shareCode) ? shareCode : `https://qfile.qq.com/q/${shareCode}`;
const resp = await fetch(url);
if (!resp.ok) throw new Error(`get_fileset_id: HTTP ${resp.status}`);
const html = await resp.text();
// 网页里 fileset_id 以 JSON 嵌入(引号可能被转义为 \"),正则兼容两种形态。
const m = /fileset_id\\?"\s*:\s*\\?"([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/.exec(html);
if (!m) throw new Error('get_fileset_id: fileset_id not found in share page');
return m[1];
}
// ─────────────── 文件上传 ───────────────
/**
* 文件扩展名 → 闪传类型码映射。typeCode 用于 0x93cf f3,formatCode 用于
* 0x93d0 commit f7 与 0x12a9 filesetWrap.f7(两者同值)。mp4 → 2,rar/zip → 4。
* 未知扩展名按媒体类处理(formatCode=2),服务端按文件名扩展名判定。
*/
private static fileTypeCode(fileName: string): { typeCode: number; formatCode: number } {
const ext = fileName.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? '';
switch (ext) {
case 'rar': return { typeCode: 2, formatCode: 4 };
case 'zip': return { typeCode: 6, formatCode: 4 };
case '7z': case 'gz': case 'tar': case 'bz2': return { typeCode: 2, formatCode: 4 };
case 'png': case 'jpg': case 'jpeg': case 'bmp': case 'gif': case 'webp':
case 'mp4': case 'mov': case 'avi': case 'mkv':
return { typeCode: 7, formatCode: 2 };
default: return { typeCode: 7, formatCode: 2 };
}
}
/** 构造 sub=103 的 fileId(客户端生成的 protobuf,base64url 编码)。
* f2=SHA1, f3=filesize, f4=appid, f5=微秒时间戳, f6="prod",
* f10=TTL(1209600), f11=16B 会话ID, f15=3B, f16="gz"。
* f11/f15 随机生成,服务端不校验。
* appid 决定 fileId 落在哪个槽位:主文件用 14901(0x93d4 f14.f1),
* png 缩略图用 14903、jpg 缩略图用 14902(f13.f1)。主文件必须用 14901,
* 否则 fileId 不会被服务端采纳进 f14,对端无法拿到主文件下载入口。 */
private static buildFileId(sha1: Uint8Array, fileSize: number, appid: number = 14901): string {
const fileId: FlashFileId = {
sha1: new Uint8Array(sha1),
fileSize,
appid,
timestamp: BigInt(Date.now()) * 1000n, // 微秒时间戳
env: 'prod',
ttl: 1209600,
sessionId: randomBytes(16),
field15: randomBytes(3),
region: 'gz',
};
return Buffer.from(protobuf_encode<FlashFileId>(fileId)).toString('base64url');
}
/**
* 创建闪传任务(create_flash_task)。所有文件统一走 sub=100/103+sliceupload,
* 不走小文件 PUT——QQ 客户端即使几百 KB 的文件也走 sliceupload。只有 sliceupload
* 路径会上报主文件 sha1/size,服务端据此把 fileset 标记为完成(对端可下载);
* PUT 路径不上报 sha1,fileset 会卡在"上传中"无法被下载。
*
* 多文件:0x93d0 的 f4 是 repeated,一个 commit 请求同时携带 fileset 内所有文件
* 条目,每条 f6=文件序号(1,2,3...)。commit 在上传前只发一次,之后 complete →
* 逐个 prepare/apply/sliceupload。prepare/apply 的 filesetWrap.f4 必须与 commit
* 的 f6 一致,否则文件不计入 fileset。多文件时 ApplyFileset 的 fileName 用
* 「<首文件名>等N个文件」、fileSize 用总和——服务端据此判定 fileset 为多文件。
*/
async createFlashTask(files: string | string[], _name?: string, _thumbPath?: string): Promise<{ filesetId: string }> {
const fileList = Array.isArray(files) ? files : [files];
if (fileList.length === 0) throw new Error('create_flash_task: files is empty');
const uploader = {
uin: this.ctx.identity.uin,
nickname: this.ctx.identity.nickname,
// Resolve our own uid rather than ship an empty one — a blank uploader
// uid drops the fileset if this runs before warmup populated selfUid.
uid: await resolveSelfUid(this.ctx),
};
// 读取所有文件,每个分配 fileUuid + 序号 + formatCode
const items: { bytes: Uint8Array; fileName: string; fileUuid: string; fileIndex: number; formatCode: number }[] = [];
for (let i = 0; i < fileList.length; i++) {
const { bytes, fileName } = await loadBinarySource(fileList[i], 'flash-transfer');
const { formatCode } = FlashTransferApi.fileTypeCode(fileName);
items.push({ bytes: new Uint8Array(bytes), fileName, fileUuid: randomUUID(), fileIndex: i + 1, formatCode });
}
// 申请 fileset。多文件时 fileName 用「<首文件名>等N个文件」、fileSize 用总和,
// 服务端据此判定 fileset 为多文件,commit 的后续 entry 才会被计入。
const first = items[0];
const { typeCode } = FlashTransferApi.fileTypeCode(first.fileName);
const isMulti = items.length > 1;
const filesetName = isMulti ? `${first.fileName}等${items.length}个文件` : first.fileName;
const totalSize = items.reduce((s, it) => s + it.bytes.length, 0);
const apply = await ApplyFileset.invoke(this.ctx, {
fileName: filesetName, origName: filesetName,
fileSize: totalSize, typeCode, uploader,
});
const filesetUuid = apply.filesetUuid;
if (!filesetUuid) throw new Error('apply fileset failed: missing uuid');
// 一次性 commit 所有文件元数据(f4 repeated,每条 f6=序号)
const commitEntries = items.map((it) => ({
fileUuid: it.fileUuid, fileName: it.fileName, origName: it.fileName,
fileSize: it.bytes.length, formatCode: it.formatCode, fileIndex: it.fileIndex,
}));
await CommitFile.invoke(this.ctx, { filesetUuid, entries: commitEntries });
await CompleteFileset.invoke(this.ctx, { filesetUuid });
// 两阶段上传:先全部 prepare+apply 注册 fileId,再全部 sliceupload 落盘。
const prepared: { it: typeof items[0]; rkey: string; sha1StateV: Uint8Array[]; sliceCount: number }[] = [];
for (const it of items) {
const p = await this.prepareAndApply(filesetUuid, it.bytes, it.fileName, it.fileUuid, it.fileIndex, it.formatCode);
if (p) prepared.push({ it, ...p });
}
for (const p of prepared) {
await this.sliceuploadFile(p.it.bytes, p.rkey, p.sha1StateV, p.sliceCount, p.it.fileName);
}
// fileset 级缩略图(序号在主文件之后递增),主文件下载入口需要缩略图关联
await this.uploadThumbnail(filesetUuid, items[0].fileUuid, 'png', items.length + 1);
await this.uploadThumbnail(filesetUuid, items[0].fileUuid, 'jpg', items.length + 2);
await SetFilesetStatus.invoke(this.ctx, { filesetUuid });
return { filesetId: filesetUuid };
}
/**
* 阶段1:prepare(拿 rkey)+ apply(注册 fileId)。返回 sliceupload 所需的 rkey/sha1state。
* 秒传(rkey=null)返回 null,调用方跳过 sliceupload。
*/
private async prepareAndApply(
filesetUuid: string, bytes: Uint8Array, fileName: string, fileUuid: string, fileIndex: number, formatCode: number,
): Promise<{ rkey: string; sha1StateV: Uint8Array[]; sliceCount: number } | null> {
const fileSize = bytes.length;
const hashes = computeHashes(bytes);
const SLICE_SIZE = 1024 * 1024;
const sliceCount = Math.ceil(fileSize / SLICE_SIZE);
const sha1StateV = computeSha1StateV(bytes, sliceCount, SLICE_SIZE);
const rkey = await PrepareUpload.invoke(this.ctx, {
filesetUuid, fileUuid, fileName, fileSize, sha1: hashes.sha1Hex, fileIndex, formatCode,
});
if (rkey === null) return null; // 秒传
const fileId = FlashTransferApi.buildFileId(hashes.sha1, fileSize);
await ApplyUpload.invoke(this.ctx, {
filesetUuid, fileUuid, fileId, fileName, fileSize,
md5: hashes.md5Hex, sha1: hashes.sha1Hex, fileIndex, formatCode,
});
return { rkey, sha1StateV, sliceCount };
}
/**
* 阶段2:sliceupload 分片上传(所有文件 prepare+apply 完成后调用)。
*/
private async sliceuploadFile(
bytes: Uint8Array, rkey: string, sha1StateV: Uint8Array[], sliceCount: number, fileName: string,
): Promise<void> {
const fileSize = bytes.length;
const SLICE_SIZE = 1024 * 1024;
for (let i = 0; i < sliceCount; i++) {
const start = i * SLICE_SIZE;
const chunk = bytes.subarray(start, Math.min(start + SLICE_SIZE, fileSize));
const chunkLen = chunk.length;
const chunkSha1 = new Uint8Array(createHash('sha1').update(Buffer.from(chunk)).digest());
const body: FlashSliceUploadBody = {
field1: 0,
appid: 14901,
field3: 2,
payload: {
field1: {},
rkey,
start,
end: start + chunkLen - 1,
sha1: chunkSha1,
sha1StateV: { state: sha1StateV.map((s) => new Uint8Array(s)) },
chunk: new Uint8Array(chunk),
},
};
const bodyBytes = protobuf_encode<FlashSliceUploadBody>(body);
await this.postSliceupload(bodyBytes, `${fileName} slice ${i}`);
}
}
/**
* POST sliceupload 并校验响应。服务端即使 HTTP 200 也可能在业务体里返回错误,
* 所以必须解析 f5(status),非 "success" 视为失败。label 用于错误信息定位切片来源。
*/
private async postSliceupload(bodyBytes: Uint8Array, label: string): Promise<void> {
const resp = await fetch('https://multimedia.qfile.qq.com/sliceupload', {
method: 'POST', body: bodyBytes,
headers: {
Accept: '*/*', Connection: 'Keep-Alive',
'User-Agent': 'Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2)',
Pragma: 'no-cache', 'Cache-Control': 'no-cache',
'Content-Length': String(bodyBytes.length),
'X-Retried-Times': '1',
},
});
if (!resp.ok) {
const errBody = await resp.text().catch(() => '');
throw new Error(`${label} failed: HTTP ${resp.status} ${errBody.slice(0, 300)}`);
}
const respBuf = new Uint8Array(await resp.arrayBuffer());
const sliceResp = protobuf_decode<FlashSliceUploadResp>(respBuf);
if (sliceResp.status !== 'success') {
throw new Error(`${label} failed: ${sliceResp.status || 'no status in response'}`);
}
}
/**
* 上传占位缩略图(png+jpg)。主文件上传后调用——主文件下载入口(0x93d3 的下载
* fileId)需要缩略图关联才会被服务端填充,不传缩略图时 bot 自身上传的 fileset
* 无法被 download_fileset 解析。缩略图用随机纯色 PNG,无需 ffmpeg/sharp。
* fileIndex 为缩略图在 fileset 内的序号(主文件之后递增),与 commit f6 对齐。
*/
private async uploadThumbnail(
filesetUuid: string, mainFileUuid: string, thumbType: 'png' | 'jpg', fileIndex: number,
): Promise<void> {
// 526x360 是 QQ 客户端缩略图尺寸;1x1 会被服务端拒(HTTP 400,宽高太小)。
const width = 526, height = 360;
const thumbBytes = generatePng(width, height); // 随机纯色,SHA1 不同避免秒传
const appid = thumbType === 'png' ? 14903 : 14902; // png=14903, jpg=14902
const fileUuid = thumbType === 'png' ? randomUUID() : mainFileUuid; // png 独立,jpg 挂主文件
const fileName = thumbType === 'png'
? `${randomUUID().slice(0, 8)}_one.png`
: `${createHash('md5').update(thumbBytes).digest('hex').slice(0, 32)}.jpg`;
const hashes = computeHashes(new Uint8Array(thumbBytes));
const fileSize = thumbBytes.length;
const thumbFormatCode = thumbType === 'png' ? 26 : 2; // png缩略图=26, jpg缩略图=2
const rkey = await PrepareUpload.invoke(this.ctx, {
filesetUuid, fileUuid, fileName, fileSize, sha1: hashes.sha1Hex,
fileIndex, formatCode: thumbFormatCode, thumbType, width, height,
});
if (rkey === null) return; // 秒传
const fileId = FlashTransferApi.buildFileId(hashes.sha1, fileSize, appid);
await ApplyUpload.invoke(this.ctx, {
filesetUuid, fileUuid, fileId, fileName, fileSize,
md5: hashes.md5Hex, sha1: hashes.sha1Hex, fileIndex, formatCode: thumbFormatCode, thumbType, width, height,
});
// sliceupload(缩略图小,1 片,Sha1StateV=[标准 SHA1])
const sha1StateV = computeSha1StateV(new Uint8Array(thumbBytes), 1, fileSize);
const body: FlashSliceUploadBody = {
field1: 0, appid, field3: 2,
payload: {
field1: {}, rkey,
start: 0, end: fileSize - 1,
sha1: new Uint8Array(hashes.sha1),
sha1StateV: { state: sha1StateV.map((s) => new Uint8Array(s)) },
chunk: new Uint8Array(thumbBytes),
},
};
const bodyBytes = protobuf_encode<FlashSliceUploadBody>(body);
await this.postSliceupload(bodyBytes, 'thumbnail sliceupload');
}
}

View File

@@ -1,4 +1,5 @@
import type { PacketInfo } from '@snowluma/common/protocol-types';
import { mapWithConcurrency } from '@snowluma/common/concurrency';
import type {
LongMsgResult,
RecvLongMsgReq,
@@ -14,7 +15,7 @@ import { protobuf_decode, protobuf_encode } from '@snowluma/proton';
import { randomUUID } from 'crypto';
import { gunzipSync, gzipSync } from 'zlib';
import type { Bridge } from '../bridge';
import type { BridgeContext } from '../bridge-context';
import type { BridgeContext, UploadedFileMeta } from '../bridge-context';
import { resolveSelfUid, toInt } from './shared';
function asBridge(ctx: BridgeContext): Bridge { return ctx as unknown as Bridge; }
@@ -24,6 +25,17 @@ function asBridge(ctx: BridgeContext): Bridge { return ctx as unknown as Bridge;
// resolve a forward immediately after receiving the parent message.
const forwardResCache = new Map<string, ForwardNodePayload[]>();
/** QQ's placeholder when it doesn't hand back a real sender name — treated as
* "missing" so #174's enrichment resolves the real nickname. */
const FORWARD_NAME_PLACEHOLDER = 'QQ用户';
/** Bounds on the L4 (per-uin profile) fallback when enriching forward senders.
* Profile lookups are un-cached single-point OIDB calls Tencent rate-limits
* aggressively, so cap how many distinct uins one forward resolves and how
* many run at once — the rest keep the placeholder. */
const FORWARD_PROFILE_MAX = 20;
const FORWARD_PROFILE_CONCURRENCY = 4;
// Per-layer piggyback entry. Each level of a nested forward attaches
// its own msgBody under a uuid `actionCommand`, so when the receiver
// fetches the outermost res_id it gets every layer in one shot
@@ -139,7 +151,9 @@ async function buildForwardPushBody(
return {
responseHead: {
fromUin,
toUid: bridge.identity.selfUid ?? '',
// Resolve our own uid rather than ship an empty one — a blank toUid is a
// broken packet if this runs before warmup populated selfUid.
toUid: await resolveSelfUid(bridge),
forward: {
friendName: nickname,
},
@@ -150,7 +164,7 @@ async function buildForwardPushBody(
msgId: random,
sequence: seq,
timestamp: now,
divSeq: 0,
c2cCmd: 0,
},
body: {
richText: {
@@ -202,6 +216,46 @@ function previewFromElements(elements: MessageElement[]): string {
return '';
}
function cloneNodeWithElements(node: ForwardNodePayload, elements: MessageElement[]): ForwardNodePayload {
return {
userUin: node.userUin,
nickname: node.nickname,
elements,
time: node.time,
msgId: node.msgId,
msgSeq: node.msgSeq,
groupId: node.groupId,
senderCard: node.senderCard,
messageType: node.messageType,
innerForward: node.innerForward,
};
}
function stripFileSource(element: MessageElement): MessageElement {
const next: MessageElement = { ...element };
delete next.url;
return next;
}
function isCachedFileUsableInTarget(
cached: UploadedFileMeta | undefined,
groupId?: number,
userId?: number,
): boolean {
if (!cached) return true;
if (groupId !== undefined) {
return cached.scope === 'group' && cached.groupId === groupId;
}
if (userId !== undefined) {
return cached.scope === 'private' && cached.userId === userId;
}
return true;
}
function fileNameForUpload(element: MessageElement, cached?: UploadedFileMeta): string {
return (element.fileName ?? cached?.fileName ?? '').trim();
}
export class ForwardApi {
constructor(private readonly ctx: BridgeContext) { }
@@ -210,6 +264,101 @@ export class ForwardApi {
return resId;
}
private async downloadSourceFromCachedFile(cached: UploadedFileMeta): Promise<string> {
if (cached.scope === 'group' && cached.groupId !== undefined) {
return this.ctx.apis.groupFile.getUrl(cached.groupId, cached.fileId);
}
if (cached.scope === 'private' && cached.userId !== undefined && cached.fileHash) {
return this.ctx.apis.groupFile.getPrivateUrl(cached.userId, cached.fileId, cached.fileHash);
}
throw new Error('forward file_id belongs to another scope; pass file/base64/url so SnowLuma can re-upload it');
}
private async uploadForwardFileSource(
source: string,
name: string,
groupId?: number,
userId?: number,
): Promise<MessageElement> {
if (groupId !== undefined) {
const uploaded = await this.ctx.apis.groupFile.upload(groupId, source, name, '/', true, false);
if (!uploaded.fileId) throw new Error('forward group file upload returned no file_id');
const cached = this.ctx.recallUploadedFile(uploaded.fileId);
const element: MessageElement = {
type: 'file',
fileId: uploaded.fileId,
};
const fileName = cached?.fileName || name;
if (fileName) element.fileName = fileName;
if (cached?.fileSize !== undefined) element.fileSize = cached.fileSize;
return element;
}
if (userId !== undefined) {
const uploaded = await this.ctx.apis.groupFile.uploadPrivate(userId, source, name, true, false);
if (!uploaded.fileId) throw new Error('forward private file upload returned no file_id');
const cached = this.ctx.recallUploadedFile(uploaded.fileId);
const element: MessageElement = {
type: 'file',
fileId: uploaded.fileId,
};
const fileName = cached?.fileName || name;
const fileHash = uploaded.fileHash ?? cached?.fileHash ?? '';
if (fileName) element.fileName = fileName;
if (cached?.fileSize !== undefined) element.fileSize = cached.fileSize;
if (fileHash) element.fileHash = fileHash;
return element;
}
throw new Error('forward file source requires group_id or user_id');
}
private async prepareForwardFileElement(
element: MessageElement,
groupId?: number,
userId?: number,
): Promise<MessageElement> {
if (element.type !== 'file') return element;
const source = (element.url ?? '').trim();
if (source && !element.fileId) {
const uploaded = await this.uploadForwardFileSource(source, fileNameForUpload(element), groupId, userId);
return {
...stripFileSource(element),
...uploaded,
};
}
if (element.fileId) {
const cached = this.ctx.recallUploadedFile(element.fileId);
if (isCachedFileUsableInTarget(cached, groupId, userId)) return element;
const sourceFromCache = await this.downloadSourceFromCachedFile(cached!);
const uploaded = await this.uploadForwardFileSource(
sourceFromCache,
fileNameForUpload(element, cached),
groupId,
userId,
);
return {
...stripFileSource(element),
...uploaded,
};
}
return element;
}
private async prepareForwardFiles(
nodes: ForwardNodePayload[],
groupId?: number,
userId?: number,
): Promise<ForwardNodePayload[]> {
return Promise.all(nodes.map(async (node) => {
const elements = await Promise.all(node.elements.map(
element => this.prepareForwardFileElement(element, groupId, userId),
));
return cloneNodeWithElements(node, elements);
}));
}
/**
* Recursive upload with NapCat-style piggyback. Each invocation:
* 1. Walks `nodes`. For any node whose `innerForward` is set,
@@ -304,8 +453,10 @@ export class ForwardApi {
}
}
const uploadReadyNodes = await this.prepareForwardFiles(processedNodes, groupId, userId);
// Encode this level's msgBody.
const msgBody = await Promise.all(processedNodes.map(
const msgBody = await Promise.all(uploadReadyNodes.map(
node => buildForwardPushBody(bridge, node, groupId, userUid),
));
@@ -349,7 +500,7 @@ export class ForwardApi {
throw new Error('upload forward message response missing res_id');
}
forwardResCache.set(resId, processedNodes.map(node => ({
forwardResCache.set(resId, uploadReadyNodes.map(node => ({
userUin: node.userUin,
nickname: node.nickname,
elements: [...node.elements],
@@ -381,7 +532,7 @@ export class ForwardApi {
const bridge = asBridge(this.ctx);
const cached = forwardResCache.get(resId);
if (cached) {
return cached.map(node => ({
const nodes = cached.map(node => ({
userUin: node.userUin,
nickname: node.nickname,
elements: [...node.elements],
@@ -392,6 +543,10 @@ export class ForwardApi {
senderCard: node.senderCard,
messageType: node.messageType,
}));
// Inner nodes seeded by consumePiggybacks are cached un-enriched; enrich
// on read (a no-op once names are present) and persist so later hits skip.
if (await this.enrichSenders(nodes)) forwardResCache.set(resId, cloneNodes(nodes));
return nodes;
}
const selfUid = await resolveSelfUid(bridge);
@@ -451,12 +606,94 @@ export class ForwardApi {
this.consumePiggybacks(nodes, piggybackByUuid);
}
// Fill sender nickname/card for nodes the SsoRecvLongMsg payload left empty
// or stamped with the "QQ用户" placeholder (#174) — the long-msg member name
// isn't always populated, and the sync decode only consults the L1 cache.
await this.enrichSenders(nodes);
if (nodes.length > 0) {
forwardResCache.set(resId, cloneNodes(nodes));
}
return nodes;
}
/** A node whose display name the server didn't give us (empty or the QQ
* placeholder) and that we can resolve (has a uin). */
private needsName(n: ForwardNodePayload): boolean {
return !!n.userUin && (!n.nickname || n.nickname === FORWARD_NAME_PLACEHOLDER);
}
/** Backfill sender nickname/card on forward nodes the long-msg payload left
* nameless. Resolves group senders via one member-list fetch per group (L3,
* inflight+TTL cached in ContactsApi), then any residue + private nodes via
* the user-profile lookup (L4). Best-effort: a failed lookup keeps the
* placeholder rather than failing the whole forward. Returns true if any
* node was changed (so callers can persist the enriched cache). */
private async enrichSenders(nodes: ForwardNodePayload[]): Promise<boolean> {
const pending = nodes.filter(n => this.needsName(n));
if (pending.length === 0) return false;
let changed = false;
// L3 — group member lists (one fetch resolves every sender from that group).
const byGroup = new Map<number, ForwardNodePayload[]>();
const residue: ForwardNodePayload[] = [];
for (const n of pending) {
if (n.messageType === 'group' && n.groupId) {
const arr = byGroup.get(n.groupId) ?? [];
arr.push(n);
byGroup.set(n.groupId, arr);
} else {
residue.push(n);
}
}
for (const [groupId, groupNodes] of byGroup) {
let byUin: Map<number, { nickname: string; card: string }>;
try {
const members = await this.ctx.apis.contacts.fetchGroupMemberList(groupId);
byUin = new Map(members.map(m => [m.uin, { nickname: m.nickname, card: m.card }]));
} catch {
// Member list (one cheap, cached call) failed — keep the placeholder
// rather than fanning the whole group out to per-uin profile lookups.
// That error path is exactly what would amplify into a rate-limit ban.
continue;
}
for (const n of groupNodes) {
const m = byUin.get(n.userUin);
const name = m?.card || m?.nickname;
if (name) {
n.senderCard = m!.card || n.senderCard || '';
n.nickname = name;
changed = true;
} else {
residue.push(n); // in-group sender that left the group → profile fallback
}
}
}
// L4 — user profile for the residue (members who left the group, private
// nodes). fetchUserProfile is an un-cached single-point OIDB 0xFE1_2, and
// Tencent rate-limits these hard (see ContactsApi's member-list note), so:
// dedupe by uin, CAP the count (drop the rest to placeholder), and resolve
// in small concurrency-limited batches. Best-effort.
const uins = [...new Set(residue.filter(n => this.needsName(n)).map(n => n.userUin))]
.slice(0, FORWARD_PROFILE_MAX);
if (uins.length > 0) {
const byUin = new Map<number, string>();
const results = await mapWithConcurrency(uins, FORWARD_PROFILE_CONCURRENCY,
async (uin): Promise<readonly [number, string]> => {
try { return [uin, (await this.ctx.apis.contacts.fetchUserProfile(uin)).nickname] as const; }
catch { return [uin, ''] as const; }
});
for (const [uin, nick] of results) byUin.set(uin, nick);
for (const n of residue) {
if (!this.needsName(n)) continue;
const nick = byUin.get(n.userUin);
if (nick) { n.nickname = nick; changed = true; }
}
}
return changed;
}
/** Walk a list of PushMsgBody, run each through the regular msg-push
* pipeline, and shape the result into ForwardNodePayloads. Extracted
* so both the outer + piggyback decode paths share one implementation. */

View File

@@ -1,8 +1,13 @@
import { ApproveDoubtBuddyReq } from '@snowluma/protocol/oidb-services/friend/approve-doubt-buddy-req';
import { DeleteFriend } from '@snowluma/protocol/oidb-services/friend/delete-friend';
import { GetDoubtBuddyReq, type DoubtBuddyRequest } from '@snowluma/protocol/oidb-services/friend/get-doubt-buddy-req';
import { HandleFriendRequest } from '@snowluma/protocol/oidb-services/friend/handle-friend-request';
import { RejectDoubtBuddyReq } from '@snowluma/protocol/oidb-services/friend/reject-doubt-buddy-req';
import { SetFriendRemark } from '@snowluma/protocol/oidb-services/friend/set-friend-remark';
import type { BridgeContext } from '../bridge-context';
export type { DoubtBuddyRequest };
export class FriendApi {
constructor(private readonly ctx: BridgeContext) { }
@@ -26,4 +31,19 @@ export class FriendApi {
setRemark(userId: number, remark: string): Promise<void> {
return SetFriendRemark.invoke(this.ctx, { userId, remark });
}
/** List doubtful friend-add requests (可能认识的人). */
getDoubtRequests(count: number): Promise<DoubtBuddyRequest[]> {
return GetDoubtBuddyReq.invoke(this.ctx, { count });
}
/** Approve a doubtful friend-add request by its uid (the list item's flag). */
approveDoubtRequest(uid: string): Promise<void> {
return ApproveDoubtBuddyReq.invoke(this.ctx, { uid });
}
/** Reject (delete/decline) a doubtful friend-add request by its uid. */
rejectDoubtRequest(uid: string): Promise<void> {
return RejectDoubtBuddyReq.invoke(this.ctx, { uid });
}
}

View File

@@ -12,11 +12,17 @@ import { SetGroupRemark } from '@snowluma/protocol/oidb-services/group-admin/set
import { SetMemberCard } from '@snowluma/protocol/oidb-services/group-admin/set-member-card';
import { SetSearch } from '@snowluma/protocol/oidb-services/group-admin/set-search';
import { SetSpecialTitle } from '@snowluma/protocol/oidb-services/group-admin/set-special-title';
import { ModifyGroupExtInfo } from '@snowluma/protocol/oidb-services/group-admin/modify-group-ext-info';
import type { BridgeContext } from '../bridge-context';
export class GroupAdminApi {
constructor(private readonly ctx: BridgeContext) { }
/** Set the group's robot-add option (switch / examine) via group ext-info. */
setRobotAddOption(groupId: number, robotMemberSwitch?: number, robotMemberExamine?: number): Promise<void> {
return ModifyGroupExtInfo.invoke(this.ctx, { groupId, robotMemberSwitch, robotMemberExamine });
}
muteMember(groupId: number, userId: number, duration: number): Promise<void> {
return MuteMember.invoke(this.ctx, { groupId, userId, duration });
}
@@ -29,8 +35,8 @@ export class GroupAdminApi {
return SetAddOption.invoke(this.ctx, { groupId, addType });
}
setSearch(groupId: number): Promise<void> {
return SetSearch.invoke(this.ctx, { groupId });
setSearch(groupId: number, noFingerOpen?: number, noCodeFingerOpen?: number): Promise<void> {
return SetSearch.invoke(this.ctx, { groupId, noFingerOpen, noCodeFingerOpen });
}
setAddRequest(
@@ -48,8 +54,26 @@ export class GroupAdminApi {
return KickMembers.invoke(this.ctx, { groupId, userIds, reject });
}
leave(groupId: number): Promise<void> {
return LeaveGroup.invoke(this.ctx, { groupId });
async leave(groupId: number): Promise<void> {
await LeaveGroup.invoke(this.ctx, { groupId });
// The server doesn't push a member-decrease back to the member who left of
// its own accord, so synthesize the self group_member_leave here — otherwise
// downstream never sees notice.group_decrease and keeps a "zombie" group in
// its cache (#133). Also drop the group from our own roster.
const selfUin = Number(this.ctx.identity.uin) || 0;
const selfUid = this.ctx.identity.selfUid ?? '';
await this.ctx.events.emit({
kind: 'group_member_leave',
time: Math.floor(Date.now() / 1000),
selfUin,
groupId,
userUin: selfUin,
operatorUin: selfUin,
userUid: selfUid,
operatorUid: selfUid,
leaveType: 'leave',
});
this.ctx.identity.forgetGroup(groupId);
}
setAdmin(groupId: number, userId: number, enable: boolean): Promise<void> {

View File

@@ -12,6 +12,7 @@ import { CreateGroupFolder } from '@snowluma/protocol/oidb-services/group-file/c
import { DeleteGroupFile } from '@snowluma/protocol/oidb-services/group-file/delete-group-file';
import { DeleteGroupFolder } from '@snowluma/protocol/oidb-services/group-file/delete-group-folder';
import { GetGroupFileCount } from '@snowluma/protocol/oidb-services/group-file/get-group-file-count';
import { GetGroupFileSpace } from '@snowluma/protocol/oidb-services/group-file/get-group-file-space';
import { GetGroupFileUrl } from '@snowluma/protocol/oidb-services/group-file/get-group-file-url';
import { GetGroupPttUrl } from '@snowluma/protocol/oidb-services/group-file/get-group-ptt-url';
import { GetGroupVideoUrl } from '@snowluma/protocol/oidb-services/group-file/get-group-video-url';
@@ -21,7 +22,9 @@ import { GetPrivateVideoUrl } from '@snowluma/protocol/oidb-services/group-file/
import { ListGroupFilesPage } from '@snowluma/protocol/oidb-services/group-file/list-group-files-page';
import { MoveGroupFile } from '@snowluma/protocol/oidb-services/group-file/move-group-file';
import { PublishGroupFile } from '@snowluma/protocol/oidb-services/group-file/publish-group-file';
import { RenameGroupFile } from '@snowluma/protocol/oidb-services/group-file/rename-group-file';
import { RenameGroupFolder } from '@snowluma/protocol/oidb-services/group-file/rename-group-folder';
import { TransGroupFile, type TransGroupFileResult } from '@snowluma/protocol/oidb-services/group-file/trans-group-file';
import { UploadGroupFileRequest } from '@snowluma/protocol/oidb-services/group-file/upload-group-file-request';
import { UploadPrivateFileRequest } from '@snowluma/protocol/oidb-services/group-file/upload-private-file-request';
import { ensureRetCodeZero } from '@snowluma/protocol/oidb-services/shared';
@@ -99,8 +102,14 @@ function normalizeUploadFileName(name: string, fallback: string): string {
return safeFallback || 'file.bin';
}
// QQ's "first 10 MB" checksum uses the magic limit 0x98A000 (10002432) —
// NOT 10*1024*1024 and not 10^7. Using the wrong limit makes the server's
// first-block verification fail for files larger than 0x98A000, so the
// offline file uploads but never finalises as downloadable (#157).
const MD5_HEAD_LIMIT = 10002432;
function md5First10MB(bytes: Uint8Array): Uint8Array {
const limit = Math.min(bytes.length, 10 * 1024 * 1024);
const limit = Math.min(bytes.length, MD5_HEAD_LIMIT);
return computeMd5(bytes.subarray(0, limit));
}
@@ -176,7 +185,12 @@ function buildPrivateFileUploadExt(
unknown2: 1,
entry: {
busiBuff: {
busId: 102,
// #157: NapCat/Lagrange (and the QQ client, confirmed by packet
// capture) emit a busiBuff with ONLY senderUin — no busId. A stale
// busId:102 here made the offline-file server accept the highway
// upload but never finalise it as downloadable once the file got
// big (>5 MiB): the receiver saw the file but every download failed.
// (The other half of that bug was the wrong md5-head limit above.)
senderUin: BigInt(senderUin),
receiverUin: 0n,
groupCode: 0n,
@@ -226,12 +240,21 @@ export class GroupFileApi {
return PublishGroupFile.invoke(this.ctx, { groupId, fileId });
}
trans(groupId: number, fileId: string): Promise<TransGroupFileResult> {
if (!fileId) throw new Error('trans requires fileId');
return TransGroupFile.invoke(this.ctx, { groupId, fileId });
}
// ─────────────── count ───────────────
getCount(groupId: number): Promise<{ fileCount: number; maxCount: number }> {
return GetGroupFileCount.invoke(this.ctx, { groupId });
}
getSpace(groupId: number): Promise<{ usedSpace: number; totalSpace: number }> {
return GetGroupFileSpace.invoke(this.ctx, { groupId });
}
// ─────────────── upload (3-stage: OIDB preflight → highway → publish) ───────────────
async upload(
@@ -240,6 +263,7 @@ export class GroupFileApi {
name = '',
folderId = '/',
uploadFile = true,
publishFile = uploadFile,
): Promise<UploadFileResult> {
const bridge = asBridge(this.ctx);
// Group/private files may legitimately be up to 4 GiB on QQ's wire,
@@ -315,11 +339,11 @@ export class GroupFileApi {
// the chat shows nothing. The publish step goes via a dedicated OIDB
// call (0x6D9_4), NOT via `MessageSvc.PbSendMsg` with a transElem(24)
// payload — the QQ-NT server rejects that with `result=79`. Mirrors
// Lagrange.Core V2's `GroupSendFileService.cs`. Suppressed when the
// caller opts out via `uploadFile=false` (treat that as "I only
// wanted the slot allocated, hold the chat post"). Routes through
// `this.publish` so tests can mock at the same Api boundary.
if (uploadFile) {
// Lagrange.Core V2's `GroupSendFileService.cs`. Suppressed when a
// caller only needs a valid file_id embedded elsewhere, e.g. a
// forward-message long-msg payload. Routes through `this.publish` so
// tests can mock at the same Api boundary.
if (publishFile) {
try {
await this.publish(groupId, fileId);
} catch (err) {
@@ -340,20 +364,14 @@ export class GroupFileApi {
source: string,
name = '',
uploadFile = true,
publishFile = uploadFile,
): Promise<UploadFileResult> {
const bridge = asBridge(this.ctx);
const loaded = await loadBinarySource(source, 'file', FILE_UPLOAD_MAX_BYTES);
if (!loaded.bytes.length) throw new Error('private file is empty');
const targetUid = await this.ctx.resolveUserUid(userId);
let selfUid = this.ctx.identity.selfUid;
if (!selfUid) {
const selfUin = toInt(this.ctx.identity.uin);
if (selfUin > 0) {
selfUid = await this.ctx.resolveUserUid(selfUin);
}
}
if (!selfUid) throw new Error('self uid is unavailable');
const selfUid = await resolveSelfUid(this.ctx);
const senderUin = toInt(this.ctx.identity.uin);
if (senderUin <= 0) throw new Error('invalid self uin for private file upload');
@@ -481,7 +499,7 @@ export class GroupFileApi {
// which only knows about elems[]. NapCat does the same atomic
// upload+send dance — without it the file sits on the server and
// the recipient sees nothing.
if (uploadFile) {
if (publishFile) {
try {
await this.ctx.apis.message.sendC2cFile(userId, targetUid, {
fileId,
@@ -604,9 +622,13 @@ export class GroupFileApi {
return MoveGroupFile.invoke(this.ctx, { groupId, fileId, parentDirectory, targetDirectory });
}
rename(groupId: number, fileId: string, parentDirectory: string, newFileName: string): Promise<void> {
return RenameGroupFile.invoke(this.ctx, { groupId, fileId, parentDirectory, newFileName });
}
// ─────────────── folders ───────────────
createFolder(groupId: number, name: string, parentId = '/'): Promise<void> {
createFolder(groupId: number, name: string, parentId = '/'): Promise<CreateGroupFolder.Result> {
return CreateGroupFolder.invoke(this.ctx, {
groupId, parentId: normalizeDirectory(parentId), folderName: name,
});

View File

@@ -1,6 +1,7 @@
import type { BridgeContext } from '../bridge-context';
import { ContactsApi } from './contacts';
import { ExtrasApi } from './extras';
import { FlashTransferApi } from './flash-transfer';
import { ForwardApi } from './forward';
import { FriendApi } from './friend';
import { GroupAdminApi } from './group-admin';
@@ -10,6 +11,7 @@ import { InteractionApi } from './interaction';
import { MessageApi } from './message';
import { MiscApi } from './misc';
import { ProfileApi } from './profile';
import { QzoneApi } from './qzone';
import { WebApi } from './web';
export interface ApiHub {
@@ -23,12 +25,16 @@ export interface ApiHub {
readonly groupFile: GroupFileApi;
/** Group photo album: list/upload/comment/like/delete + media listing. */
readonly groupAlbum: GroupAlbumApi;
/** Personal QQ-Zone (个人空间): 说说 list + (future) publish/like/comment. */
readonly qzone: QzoneApi;
/** Interactive engagement: poke / like / reaction / essence / emoji-like-list. */
readonly interaction: InteractionApi;
/** Friend roster mutations: handleRequest / delete / setRemark. */
readonly friend: FriendApi;
/** Personal profile: status / avatar / nickname / likes / custom-faces. */
readonly profile: ProfileApi;
/** QQ 闪传(fileset 文件集): 上传/查询/分享/发送/删除/重命名。 */
readonly flashTransfer: FlashTransferApi;
/** Long-message (forward / 聊天记录) upload + retrieval with NapCat piggyback. */
readonly forward: ForwardApi;
/** Odds & ends: translate / mini-app ARK / inline-keyboard / group sign. */
@@ -54,9 +60,11 @@ export function buildApiHub(ctx: BridgeContext): ApiHub {
groupAdmin: new GroupAdminApi(ctx),
groupFile: new GroupFileApi(ctx),
groupAlbum: new GroupAlbumApi(ctx),
qzone: new QzoneApi(ctx),
interaction: new InteractionApi(ctx),
friend: new FriendApi(ctx),
profile: new ProfileApi(ctx),
flashTransfer: new FlashTransferApi(ctx),
forward: new ForwardApi(ctx),
misc: new MiscApi(ctx),
extras: new ExtrasApi(ctx),
@@ -78,5 +86,7 @@ export { InteractionApi } from './interaction';
export { MessageApi } from './message';
export { MiscApi } from './misc';
export { ProfileApi } from './profile';
export { QzoneApi } from './qzone';
export { FlashTransferApi, type FlashFileInfo } from './flash-transfer';
export { WebApi } from './web';

View File

@@ -9,9 +9,13 @@ import type {
SsoReadedReportReq,
} from '@snowluma/proto-defs/oidb-actions/base';
import { buildSendElems } from '@snowluma/protocol/element-builder';
import type { MessageElement } from '@snowluma/protocol/events';
import { FinalizeOfflineFile } from '@snowluma/protocol/oidb-services/group-file/finalize-offline-file';
import type { MessageElement, QQEventVariant } from '@snowluma/protocol/events';
import { fetchC2cMessageRange, fetchGroupMessageRange } from '@snowluma/protocol/msg-push';
import { protobuf_decode, protobuf_encode } from '@snowluma/proton';
import { createLogger } from '@snowluma/common/logger';
import type { BridgeContext } from '../bridge-context';
import { resolveSelfUid } from './shared';
// `Bridge` is imported as a type only so we can narrow `ctx` back to
// the concrete Bridge instance when passing it to `buildSendElems`
// (which still takes `Bridge` because the highway upload helpers it
@@ -24,6 +28,75 @@ import type { Bridge, SendMessageReceipt } from '../bridge';
const SEND_MSG_CMD = 'MessageSvc.PbSendMsg';
const log = createLogger('Bridge.Message');
type GroupMessage = Extract<QQEventVariant, { kind: 'group_message' }>;
type FriendMessage = Extract<QQEventVariant, { kind: 'friend_message' }>;
// ── Group-history fetch guards (the server frequency-limits / kicks abusive
// pulls, so keep each request small, bound the loop, and space the sends). ──
const HISTORY_MAX_COUNT = 200; // hard cap on messages returned per call
const HISTORY_CHUNK_SEQ = 30; // sequence span per server request (small packet)
const HISTORY_MAX_REQUESTS = 12; // bound the walk-back loop
const HISTORY_MIN_GAP_MS = 300; // minimum spacing between SsoGetGroupMsg sends
// Serialized throttle gate: chains so concurrent callers queue, and enforces
// at least HISTORY_MIN_GAP_MS between actual sends (the first send isn't
// penalized). Process-wide — shared across all groups AND accounts in this
// process — so no client can make us flood the server regardless of fan-out.
let historyLastSendAt = 0;
let historyGate: Promise<void> = Promise.resolve();
function throttleHistory(): Promise<void> {
const run = historyGate.then(async () => {
const wait = historyLastSendAt + HISTORY_MIN_GAP_MS - Date.now();
if (wait > 0) await new Promise<void>((resolve) => setTimeout(resolve, wait));
historyLastSendAt = Date.now();
});
historyGate = run.catch(() => undefined);
return run;
}
/**
* Shared walk-back loop for group + c2c history: pull HISTORY_CHUNK_SEQ-wide
* windows ending at `endSeq`, throttled, walking strictly backward (handling a
* server-side short cap via the oldest sequence actually returned), dedup by
* sequence, until `count` (capped) is gathered or the floor is reached. Returns
* the newest `want` items oldest→newest.
*/
async function walkBackHistory<T extends { msgSeq: number }>(
endSeq: number,
count: number,
fetchWindow: (startSeq: number, endSeq: number) => Promise<T[]>,
): Promise<T[]> {
if (!(endSeq > 0)) return [];
const want = Math.min(Math.max(1, Math.trunc(count) || 0), HISTORY_MAX_COUNT);
const collected = new Map<number, T>(); // dedup by sequence
let curEnd = endSeq;
for (let i = 0; i < HISTORY_MAX_REQUESTS && collected.size < want && curEnd >= 1; i++) {
const start = Math.max(1, curEnd - HISTORY_CHUNK_SEQ + 1);
await throttleHistory();
let batch: T[];
try {
batch = await fetchWindow(start, curEnd);
} catch {
break; // network/decode error — return whatever we have so far
}
if (batch.length > 0) {
let minSeq = curEnd;
for (const ev of batch) {
collected.set(ev.msgSeq, ev);
if (ev.msgSeq < minSeq) minSeq = ev.msgSeq;
}
curEnd = minSeq - 1; // strictly below the oldest returned (covers short caps)
} else {
curEnd = start - 1; // empty window (recalled/absent seqs) — skip past it
}
}
const all = [...collected.values()].sort((a, b) => a.msgSeq - b.msgSeq);
return all.slice(-want); // newest `want`, oldest→newest
}
export class MessageApi {
constructor(private readonly ctx: BridgeContext) { }
@@ -170,6 +243,12 @@ export class MessageApi {
* - `subcmd: 1` — c2c file send command code
* - `dangerEvel: 0` — virus-scan severity, always 0 client-side
* - `expireTime` — 7 days from now (Lagrange convention)
*
* `FileExtra.file` alone makes the file downloadable (verified on a live
* account). We ALSO attach `FileExtra.field6` — extra server-issued download
* routing from a best-effort 0xE37_800 finalize that mirrors NapCat and may
* help some receiver clients. The finalize is non-fatal: if it fails we send
* without field6 rather than failing the send (issue #157).
*/
async sendC2cFile(
userUin: number,
@@ -179,9 +258,35 @@ export class MessageApi {
const random = this.ctx.nextMessageRandom();
const clientSeq = this.ctx.nextClientSequence();
// Resolve our own uid — needed both for the 0xE37_800 finalize and the
// `field6` download-routing the receiver reads.
const selfUid = await resolveSelfUid(this.ctx);
// The file is already downloadable from the `NotOnlineFile` reference
// alone — verified on a live account: a plain c2c file send (no field6)
// downloads fine. `field6` is EXTRA server-issued download routing (from
// the 0xE37_800 finalize) that mirrors NapCat and may help some receiver
// clients. So fetch it BEST-EFFORT: if the finalize fails, send without
// field6 rather than failing the whole send. (issue #157 — the finalize
// was originally fatal, which could regress a send that would otherwise
// succeed.)
const fileHash = info.fileHash ?? '';
let meta: Awaited<ReturnType<typeof FinalizeOfflineFile.invoke>> | null = null;
try {
meta = await FinalizeOfflineFile.invoke(this.ctx, {
senderUid: selfUid,
receiverUid: userUid,
fileUuid: info.fileId,
fileHash,
});
} catch (err) {
log.warn('c2c file finalize (0xE37_800) failed, sending without field6: %s',
err instanceof Error ? err.message : String(err));
}
const nowSec = Math.floor(Date.now() / 1000);
const sevenDaysSec = 7 * 24 * 60 * 60;
const fileExtraBytes = protobuf_encode<FileExtra>({
const fileExtra: FileExtra = {
file: {
fileType: 0,
fileUuid: info.fileId,
@@ -191,9 +296,26 @@ export class MessageApi {
subcmd: 1,
dangerEvel: 0,
expireTime: nowSec + sevenDaysSec,
fileHash: info.fileHash ?? '',
fileHash,
},
});
};
if (meta) {
fileExtra.field6 = {
field2: {
field1: meta.field110,
fileUuid: info.fileId,
fileName: info.fileName,
field6: meta.field3,
field7: meta.field101,
field8: meta.field100,
timestamp1: meta.timestamp1,
fileHash,
selfUid,
destUid: userUid,
},
};
}
const fileExtraBytes = protobuf_encode<FileExtra>(fileExtra);
const request = protobuf_encode<SendMessageRequest>({
routingHead: {
@@ -328,5 +450,64 @@ export class MessageApi {
throw new Error(result.errorMessage || 'mark private message read failed');
}
}
/**
* Fetch real group history from the server (`SsoGetGroupMsg`), ending at and
* including `endSeq`, walking backward in small windows until `count`
* messages are gathered or the floor is reached. Rate-limited + capped so a
* hammering client can't make us flood the server (and get the account
* kicked). Returns decoded `group_message` events oldest→newest.
*/
async getGroupHistory(groupUin: number, endSeq: number, count: number, selfUin = 0): Promise<GroupMessage[]> {
if (!(groupUin > 0)) return [];
return walkBackHistory(endSeq, count, (start, end) =>
fetchGroupMessageRange(this.ctx, this.ctx.identity, selfUin, groupUin, start, end));
}
/**
* Fetch real private (c2c) history from the server (`SsoGetC2cMsg`), ending
* at and including `endSeq`. Same rate-limit + data-volume guards as the
* group variant (they share the throttle gate). `friendUid` is the
* conversation peer's UID. Returns decoded `friend_message` events
* oldest→newest.
*/
async getC2cHistory(friendUid: string, endSeq: number, count: number, selfUin = 0): Promise<FriendMessage[]> {
if (!friendUid) return [];
return walkBackHistory(endSeq, count, (start, end) =>
fetchC2cMessageRange(this.ctx, this.ctx.identity, selfUin, friendUid, start, end));
}
/**
* Fetch a single group message by its exact sequence — `SsoGetGroupMsg` over a
* 1-wide `[seq, seq]` range, through the shared history throttle gate. Used to
* back-fill a replied-to message the local store never saw. Returns the
* matching `group_message`, or null if absent / on error.
*/
async getGroupMessageBySeq(groupUin: number, seq: number, selfUin = 0): Promise<GroupMessage | null> {
if (!(groupUin > 0) || !(seq > 0)) return null;
await throttleHistory();
try {
const batch = await fetchGroupMessageRange(this.ctx, this.ctx.identity, selfUin, groupUin, seq, seq);
return batch.find((m) => m.msgSeq === seq) ?? null;
} catch {
return null;
}
}
/**
* Fetch a single c2c message by its exact sequence — `SsoGetC2cMsg` over a
* 1-wide `[seq, seq]` range, through the same throttle gate. `friendUid` is the
* conversation peer. Returns the matching `friend_message`, or null.
*/
async getC2cMessageBySeq(friendUid: string, seq: number, selfUin = 0): Promise<FriendMessage | null> {
if (!friendUid || !(seq > 0)) return null;
await throttleHistory();
try {
const batch = await fetchC2cMessageRange(this.ctx, this.ctx.identity, selfUin, friendUid, seq, seq);
return batch.find((m) => m.msgSeq === seq) ?? null;
} catch {
return null;
}
}
}

View File

@@ -9,6 +9,8 @@ import type { BridgeContext } from '../bridge-context';
import { ClickInlineKeyboardButton } from '@snowluma/protocol/oidb-services/misc/click-inline-keyboard-button';
import { SendGroupSign } from '@snowluma/protocol/oidb-services/misc/send-group-sign';
import { TranslateEnToZh } from '@snowluma/protocol/oidb-services/misc/translate-en-to-zh';
import { RequestDbKey } from '@snowluma/protocol/oidb-services/misc/request-decrypt-key';
import { ImageOcr, type OcrResult } from '@snowluma/protocol/oidb-services/misc/image-ocr';
export class MiscApi {
constructor(private readonly ctx: BridgeContext) { }
@@ -17,6 +19,10 @@ export class MiscApi {
return TranslateEnToZh.invoke(this.ctx, { words });
}
ocrImage(imageUrl: string): Promise<OcrResult> {
return ImageOcr.invoke(this.ctx, { imageUrl });
}
async getMiniAppArk(type: string, title: string, desc: string, picUrl: string, jumpUrl: string): Promise<JsonObject> {
let appid = '1109937557'; // default: bilibili
let iconUrl = 'http://miniapp.gtimg.cn/public/appicon/51f90239b78a2e4994c11215f4c4ba15_200.jpg';
@@ -75,4 +81,15 @@ export class MiscApi {
sendGroupSign(groupId: number): Promise<void> {
return SendGroupSign.invoke(this.ctx, { groupId });
}
async getDecryptKey(dbSalt: string): Promise<string> {
const result = await RequestDbKey.invoke(this.ctx, { db_salt: dbSalt });
if (!result.success) {
throw new Error(result.errorMsg || `Failed to get decrypt key (code: ${result.errorCode})`);
}
if (!result.dbKey) {
throw new Error('Decrypt key is empty');
}
return result.dbKey;
}
}

View File

@@ -5,6 +5,11 @@ import type {
SetStatusReq,
SetStatusResp,
} from '@snowluma/proto-defs/oidb-actions/base';
import { AddCustomFace } from '@snowluma/protocol/oidb-services/custom-face/add-custom-face';
import { DeleteCustomFace } from '@snowluma/protocol/oidb-services/custom-face/delete-custom-face';
import { ModifyCustomFace } from '@snowluma/protocol/oidb-services/custom-face/modify-custom-face';
import { MoveCustomFace } from '@snowluma/protocol/oidb-services/custom-face/move-custom-face';
import { OrderCustomFace } from '@snowluma/protocol/oidb-services/custom-face/order-custom-face';
import { fetchHighwaySession, uploadHighwayHttp } from '@snowluma/protocol/highway';
import { computeHashes, loadBinarySource } from '@snowluma/protocol/highway/utils';
import { GetLike, type LikeInfo } from '@snowluma/protocol/oidb-services/profile/get-like';
@@ -147,4 +152,73 @@ export class ProfileApi {
const faceIds = resp.item?.faceIds || [];
return faceIds.slice(0, count).map((id: string) => `https://p.qpic.cn/qq_expression/${this.ctx.identity.uin}/${id}/0`);
}
/** 删除一个收藏表情(custom face)。emoji_id 来自 fetchCustomFace 返回的 URL 路径段。 */
deleteCustomFace(emojiId: string): Promise<void> {
return DeleteCustomFace.invoke(this.ctx, { uin: this.ctx.identity.uin, emojiId });
}
/**
* 添加收藏表情(custom face)。imageSource 支持 file:///、base64://、http(s)://
* (复用 highway utils 的 loadBinarySource)。返回新 emoji_id。
*/
async addCustomFace(imageSource: string): Promise<string> {
const { bytes } = await loadBinarySource(imageSource, 'custom-face');
return AddCustomFace.invoke(this.ctx, { uin: this.ctx.identity.uin, imageBytes: bytes });
}
/**
* 修改收藏表情(custom face)备注。emoji_id 来自 fetchCustomFace 返回的
* URL 路径段;md5 从 emoji_id 中段解析,无需调用方单独提供。desc 为空串
* 则清空备注。
*/
modifyCustomFace(emojiId: string, desc: string): Promise<void> {
return ModifyCustomFace.invoke(this.ctx, {
emojiId,
md5: md5FromEmojiId(emojiId),
desc,
});
}
/**
* 收藏表情(custom face)移到最前。QQ 客户端只有"移动到最前",协议层
* (0x902f 的 f3=1)也只支持最前,不支持移到其他位置。两步流程:先 0x902f
* 移动指令,再 0x902e opType=2 上传新顺序(fetch 当前列表把目标挪到第一)。
* 两步都发才生效。
*/
async moveCustomFaceToFront(emojiId: string): Promise<void> {
// 1. fetch 当前完整列表(fetch 顺序即可,不需要 DB 显示顺序)
const urls = await this.fetchCustomFace(1000);
const ids = urls.map((url) => {
const m = /\/qq_expression\/[^/]+\/([^/]+)\//.exec(url);
return m ? m[1] : '';
}).filter(Boolean);
const idx = ids.indexOf(emojiId);
if (idx < 0) throw new Error(`emoji_id not in list: ${emojiId}`);
// 新顺序:目标挪到第一,其余按原顺序
const reordered = ids.slice();
reordered.splice(idx, 1);
reordered.unshift(emojiId);
// 2. 0x902f 移动指令(f3=1 = 移到最前)
await OrderCustomFace.invoke(this.ctx, { emojiId, position: 1 });
// 3. 0x902e opType=2 上传新顺序
await MoveCustomFace.invoke(this.ctx, {
emojis: reordered.map((id) => ({ emojiId: id, md5: md5FromEmojiId(id) })),
});
}
}
/**
* 从 emoji_id `<uin>_0_0_0_<MD5>_0_0` 提取中段 32 位大写 hex MD5。
* 格式固定(fetch/delete/move 共用),取第 5 段。解析失败抛错——比静默
* 传空串让服务端拒绝更早定位问题。
*/
function md5FromEmojiId(emojiId: string): string {
const parts = emojiId.split('_');
// 期望形如 `<uin>_0_0_0_<md5>_0_0`,共 7 段,md5 在 index 4。
const md5 = parts[4];
if (!md5 || md5.length !== 32 || !/^[0-9a-fA-F]{32}$/.test(md5)) {
throw new Error(`invalid emoji_id (cannot extract md5): ${emojiId}`);
}
return md5.toUpperCase();
}

View File

@@ -0,0 +1,117 @@
import {
commentQzoneMsg,
deleteQzoneMsg,
getQzoneFeeds,
getQzoneMsgList,
publishQzoneMsg,
setQzoneLike,
updateQzoneMsgRight,
uploadQzoneImageFromSource,
type QzoneCommentResult,
type QzoneFeedsResult,
type QzoneMsgListResult,
type QzonePublishResult,
type QzoneUpdateRightResult,
type QzoneUploadImageResult,
} from '@snowluma/protocol/web/qzone';
import type { BridgeContext } from '../bridge-context';
/**
* Personal QQ-Zone (个人空间) web API: 说说 (feed) read/write, likes,
* comments, image upload — all over the cookie-backed qzone.qq.com CGIs,
* reusing the same `getCookies('qzone.qq.com')` plumbing as GroupAlbumApi.
* Distinct from the group-album surface, which lives on GroupAlbumApi.
*/
export class QzoneApi {
constructor(private readonly ctx: BridgeContext) { }
/**
* 获取说说列表。`targetUin` 省略时取机器人自己的空间。
* `pos` 为起始偏移,`num` 为本页数量(服务端上限约 20/页)。
*/
async getMsgList(targetUin?: number, pos = 0, num = 20): Promise<QzoneMsgListResult> {
const uin = targetUin && targetUin > 0 ? targetUin.toString() : this.ctx.identity.uin;
const cookieObject = await this.ctx.apis.web.getCookies('qzone.qq.com');
return getQzoneMsgList(cookieObject, uin, pos, num);
}
/**
* 获取好友动态(feed)。`pageNum` 为 1 起的页码,`count` 为本页数量。
* 始终以机器人自己的身份拉取好友动态。
*/
async getFeeds(pageNum = 1, count = 10): Promise<QzoneFeedsResult> {
const cookieObject = await this.ctx.apis.web.getCookies('qzone.qq.com');
return getQzoneFeeds(cookieObject, this.ctx.identity.uin, pageNum, count);
}
/**
* 从来源上传图片到 QQ 空间。
* `source` 支持: file:// 本地路径 | http(s):// URL | base64:// base64数据
*/
async uploadImageFromSource(source: string): Promise<QzoneUploadImageResult> {
const cookieObject = await this.ctx.apis.web.getCookies('qzone.qq.com');
return uploadQzoneImageFromSource(cookieObject, this.ctx.identity.uin, source);
}
/**
* 发表说说,返回新说说的 tid。始终发到机器人自己的空间。
* `richType` / `richval`: 带图说说时传 richType=1 和 richval 字符串
* (多图用 `\t` 连接多个 richval)。纯文字说说省略这两个参数。
* `ugcRight` / `targetUins`: 查看权限及其作用名单(ugcRight=16/128 时必填)。
*/
async publish(
content: string,
richType?: number,
richval?: string,
ugcRight = 1,
targetUins?: string,
): Promise<QzonePublishResult> {
const cookieObject = await this.ctx.apis.web.getCookies('qzone.qq.com');
return publishQzoneMsg(cookieObject, this.ctx.identity.uin, content, richType, richval, ugcRight, targetUins);
}
/** 删除机器人自己空间的一条说说(按 tid)。 */
async delete(tid: string): Promise<void> {
const cookieObject = await this.ctx.apis.web.getCookies('qzone.qq.com');
await deleteQzoneMsg(cookieObject, this.ctx.identity.uin, tid);
}
/**
* 修改机器人自己空间一条已发说说的查看权限(按 tid)。
* `ugcRight` / `targetUins` 含义同 publish(16/128 时 targetUins 必填)。
*/
async updateRight(tid: string, ugcRight: number, targetUins?: string): Promise<QzoneUpdateRightResult> {
const cookieObject = await this.ctx.apis.web.getCookies('qzone.qq.com');
return updateQzoneMsgRight(cookieObject, this.ctx.identity.uin, tid, ugcRight, targetUins);
}
/**
* 给一条说说点赞/取消赞。`targetUin` 省略时点赞机器人自己空间的说说;
* 点赞好友说说时传好友 uin(tid 来自 get_qzone_feeds / get_qzone_msg_list)。
*/
async like(tid: string, targetUin: number | undefined, like: boolean, abstime = 0): Promise<void> {
const selfUin = this.ctx.identity.uin;
const owner = targetUin && targetUin > 0 ? targetUin.toString() : selfUin;
const cookieObject = await this.ctx.apis.web.getCookies('qzone.qq.com');
await setQzoneLike(cookieObject, selfUin, owner, tid, like, abstime);
}
/**
* 评论一条说说。`targetUin` 为说说所属 QQ 号(省略=机器人自己空间);
* 始终以机器人身份发表评论。返回新评论 id(尽力而为)。
* `richType` / `richval`: 带图评论时传 richType=1 和图片直链 URL
* (从 uploadImageFromSource 的 url 字段获取)。
*/
async comment(
tid: string,
content: string,
targetUin: number | undefined,
richType?: number,
richval?: string,
): Promise<QzoneCommentResult> {
const selfUin = this.ctx.identity.uin;
const owner = targetUin && targetUin > 0 ? targetUin.toString() : selfUin;
const cookieObject = await this.ctx.apis.web.getCookies('qzone.qq.com');
return commentQzoneMsg(cookieObject, selfUin, owner, tid, content, richType, richval);
}
}

View File

@@ -1,5 +1,3 @@
import type { Bridge } from '../bridge';
export function toInt(value: unknown): number {
if (typeof value === 'number' && Number.isFinite(value)) return Math.trunc(value);
if (typeof value === 'bigint') {
@@ -26,22 +24,10 @@ export function ensureRetCodeZero(operation: string, code: unknown, msg: unknown
throw new Error(`${operation} failed: code=${retCode} msg=${text}`);
}
/**
* Look up the bot's own UID. Cached on Identity once warmup populates
* `selfProfile`; forward/profile actions need this fast path before
* warmup completes.
*/
export async function resolveSelfUid(bridge: Bridge): Promise<string> {
let selfUid = bridge.identity.selfUid;
if (selfUid) return selfUid;
const selfUin = toInt(bridge.identity.uin);
if (selfUin <= 0) {
throw new Error('self uid is unavailable');
}
selfUid = await bridge.resolveUserUid(selfUin);
return selfUid;
}
// The bot's-own-UID resolver is the single source of truth in @snowluma/protocol
// (a Bridge satisfies its BridgeContext slice). Re-exported here so the existing
// `resolveSelfUid(bridge)` call sites in this package keep importing from shared.
export { resolveSelfUid } from '@snowluma/protocol/self-uid';
/**
* Index describing a server-side rich-media object (image / video /

View File

@@ -1,7 +1,9 @@
import { loadBinarySource } from '@snowluma/protocol/highway/utils';
import { ForceFetchClientKey, type ClientKeyInfo as NamespaceClientKeyInfo } from '@snowluma/protocol/oidb-services/web/force-fetch-client-key';
import { GetPskey } from '@snowluma/protocol/oidb-services/web/get-pskey';
import { getGroupEssenceMsg, getGroupEssenceMsgAll, type GroupEssenceMsgRet } from '@snowluma/protocol/web/group-essence';
import { getHonorListWebAPI, WebHonorType, type WebHonorItem } from '@snowluma/protocol/web/group-honor';
import { getDaySignedListWebAPI, type SignedListMember } from '@snowluma/protocol/web/group-signin';
import {
deleteGroupNotice as deleteGroupNoticeHttp,
getGroupNoticeWebAPI,
@@ -226,6 +228,16 @@ export class WebApi {
return honorInfo;
}
// ─────────────── group sign-in (打卡) ───────────────
/** Today's group sign-in list via qun.qq.com. [] when the group has no
* sign-ins; THROWS on transport / auth failure (caller maps to failed). */
async getSignedList(groupId: number): Promise<SignedListMember[]> {
const bridge = asBridge(this.ctx);
const cookieObject = await getCookies(bridge, 'qun.qq.com');
return getDaySignedListWebAPI(cookieObject, groupId.toString(), bridge.identity.uin.toString());
}
// ─────────────── group notice ───────────────
async sendNotice(
@@ -247,16 +259,11 @@ export class WebApi {
let imgHeight = 300;
if (options?.image) {
let imageBuffer: Buffer;
if (options.image.startsWith('http://') || options.image.startsWith('https://')) {
const response = await fetch(options.image);
if (!response.ok) throw new Error(`Failed to download image: ${response.status}`);
imageBuffer = Buffer.from(await response.arrayBuffer());
} else {
const { readFileSync } = await import('fs');
imageBuffer = readFileSync(options.image);
}
// Route through loadBinarySource so the group-notice image download
// gets the same browser-UA + Referer-retry hardening as every other
// media fetch — and http/file/base64 source handling for free.
const loaded = await loadBinarySource(options.image, 'group-notice image');
const imageBuffer = Buffer.from(loaded.bytes);
const picInfo = await uploadGroupNoticeImage(cookieObject, imageBuffer);
if (picInfo) {

View File

@@ -1,8 +1,9 @@
import { createLogger } from '@snowluma/common/logger';
import type { PacketSender, SendPacketResult } from '@snowluma/common/packet-sender';
import type { PacketInfo } from '@snowluma/common/protocol-types';
import { BridgeEventBus } from '@snowluma/protocol/event-bus';
import { IdentityService } from '@snowluma/protocol/identity-service';
import { MSG_PUSH_CMD, parseMsgPush } from '@snowluma/protocol/msg-push';
import { MSG_PUSH_CMD, parseMsgPush, SysMsgDedup } from '@snowluma/protocol/msg-push';
import { IncomingPacketPipeline, type CmdParser } from '@snowluma/protocol/packet-pipeline';
import { buildApiHub, type ApiHub } from './apis';
import {
@@ -12,6 +13,7 @@ import {
} from './apis/extras';
import type { BridgeInterface } from './bridge-interface';
const log = createLogger('Bridge');
export class Bridge implements BridgeInterface {
readonly identity: IdentityService;
@@ -24,6 +26,8 @@ export class Bridge implements BridgeInterface {
private uploadedFileMeta_ = new Map<string, UploadedFileMeta>();
private clientSeq_ = 100000000 + (Date.now() % 1000000000);
private msgRandom_ = (Date.now() & 0xFFFFFFFF) >>> 0;
// Per-account dedup for QQ NT's already-deduped system pushes (#137).
private readonly sysMsgDedup_ = new SysMsgDedup();
constructor(identity: IdentityService) {
this.identity = identity;
@@ -60,7 +64,7 @@ export class Bridge implements BridgeInterface {
}
},
});
this.pipeline.registerCmd(MSG_PUSH_CMD, parseMsgPush);
this.pipeline.registerCmd(MSG_PUSH_CMD, (pkt, identity) => parseMsgPush(pkt, identity, this.sysMsgDedup_));
}
dispose(): void {
@@ -129,12 +133,29 @@ export class Bridge implements BridgeInterface {
}
async sendRawPacket(serviceCmd: string, body: Uint8Array, timeoutMs = 15000): Promise<SendPacketResult> {
if (!this.packetClient_) {
log.warn('packet %s dropped: no packet sender attached', serviceCmd);
return {
success: false, gotResponse: false, errorCode: -1,
errorMessage: 'no packet sender attached', responseData: null,
};
}
return this.packetClient_.sendPacket(serviceCmd, Buffer.from(body), timeoutMs);
const startedAt = Date.now();
const result = await this.packetClient_.sendPacket(serviceCmd, Buffer.from(body), timeoutMs);
const elapsed = Date.now() - startedAt;
const respLen = result.responseData ? result.responseData.length : 0;
if (!result.success || result.errorCode !== 0) {
// QQ-side rejection or transport failure — the usual root cause when an
// action misbehaves. Warn (persisted) with cmd + code so a user's log
// shows exactly where the chain broke.
log.warn('packet %s failed: code=%d gotResponse=%s %s (uin=%s, %dB, %dms)',
serviceCmd, result.errorCode, result.gotResponse,
result.errorMessage ?? '', this.identity.uin, body.length, elapsed);
} else {
// Happy path — memory-only trace so the full chain shows under the
// request's [req#N] when debugging, without flooding disk.
log.trace(() => [`packet ${serviceCmd} ok (${body.length}B⇄${respLen}B, ${elapsed}ms)`]);
}
return result;
}
async resolveUserUid(uin: number, groupId?: number): Promise<string> {
return this.identity.resolveUid(uin, groupId);

View File

@@ -1,11 +1,12 @@
import { createLogger } from '@snowluma/common/logger';
import type { PacketSender } from '@snowluma/common/packet-sender';
import type { PacketInfo } from '@snowluma/common/protocol-types';
import { isRealUin } from '@snowluma/common/uin';
import { IdentityService } from '@snowluma/protocol/identity-service';
import { Bridge } from './bridge';
export type SessionStartedCallback = (uin: string, bridge: Bridge) => void;
export type SessionClosedCallback = (uin: string) => void;
export type SessionClosedCallback = (uin: string, bridge: Bridge) => void;
interface QQSession {
bridge: Bridge;
@@ -18,11 +19,40 @@ export class BridgeManager {
private pidToUin_ = new Map<number, string>();
private pidPacketClients_ = new Map<number, PacketSender>();
private onSessionStarted_: SessionStartedCallback | null = null;
private onSessionClosed_: SessionClosedCallback | null = null;
private sessionStartedListeners_: SessionStartedCallback[] = [];
private sessionClosedListeners_: SessionClosedCallback[] = [];
setSessionStartedCallback(cb: SessionStartedCallback): void { this.onSessionStarted_ = cb; }
setSessionClosedCallback(cb: SessionClosedCallback): void { this.onSessionClosed_ = cb; }
/** Additive subscription: every observer (OneBotManager, NotificationManager,
* …) receives every session edge. (Was a single `set*Callback` setter —
* converted to N listeners so a second observer can't clobber the first.)
* The close edge now carries the bridge too, since callers read the last
* nickname before it is disposed. */
addSessionStartedListener(cb: SessionStartedCallback): void {
this.sessionStartedListeners_.push(cb);
}
addSessionClosedListener(cb: SessionClosedCallback): void {
this.sessionClosedListeners_.push(cb);
}
private fireSessionStarted(uin: string, bridge: Bridge): void {
for (const cb of this.sessionStartedListeners_) {
try {
cb(uin, bridge);
} catch (err) {
log.warn('session-started listener threw: %s', err instanceof Error ? err.message : String(err));
}
}
}
private fireSessionClosed(uin: string, bridge: Bridge): void {
for (const cb of this.sessionClosedListeners_) {
try {
cb(uin, bridge);
} catch (err) {
log.warn('session-closed listener threw: %s', err instanceof Error ? err.message : String(err));
}
}
}
onPidDisconnected(pid: number): void {
this.pidPacketClients_.delete(pid);
@@ -37,18 +67,14 @@ export class BridgeManager {
if (session.bridge.empty) {
this.sessions_.delete(uin);
log.debug('session closed: UIN=%s', uin);
if (this.onSessionClosed_) this.onSessionClosed_(uin);
// Fire before dispose() so listeners can still read bridge.identity.
this.fireSessionClosed(uin, session.bridge);
session.bridge.dispose();
}
}
private static isRealUin(uin: string): boolean {
if (!uin || uin === '0') return false;
return /^\d+$/.test(uin) && uin.length >= 5;
}
onHookLogin(pid: number, uin: string, packetClient: PacketSender): void {
if (!BridgeManager.isRealUin(uin)) return;
if (!isRealUin(uin)) return;
this.pidPacketClients_.set(pid, packetClient);
@@ -59,14 +85,12 @@ export class BridgeManager {
if (created) {
log.debug('session started: UIN=%s', uin);
if (this.onSessionStarted_) {
this.onSessionStarted_(uin, session.bridge);
}
this.fireSessionStarted(uin, session.bridge);
}
}
onPacket(pkt: PacketInfo): void {
if (!pkt.uin || !BridgeManager.isRealUin(pkt.uin)) return;
if (!pkt.uin || !isRealUin(pkt.uin)) return;
const uin = pkt.uin;
// Ensure session exists
@@ -84,9 +108,7 @@ export class BridgeManager {
// Notify session started on first real packet
if (created) {
log.debug('session started: UIN=%s', uin);
if (this.onSessionStarted_) {
this.onSessionStarted_(uin, session.bridge);
}
this.fireSessionStarted(uin, session.bridge);
}
// Dispatch packet to bridge

View File

@@ -2,23 +2,66 @@ import { HookManager } from '@snowluma/bridge';
import { closeLogger, createLogger } from '@snowluma/common/logger';
import { loadRuntimeConfig } from '@snowluma/common/runtime';
import { OneBotManager } from '@snowluma/onebot/manager';
import { migrateGlobalSettings } from '@snowluma/onebot/global-config';
import { cleanupInvalidPerUinConfigs } from '@snowluma/onebot/config';
import { BridgeManager } from './bridge/manager';
import { createNotificationManager } from './notifications/manager';
import { createStateWiring } from './webui/state-wiring';
const runtimeConfig = loadRuntimeConfig();
const log = createLogger('App');
// Last-resort process guards. This is a long-running daemon: a hooked QQ pipe
// can drop at any moment, and a stray rejection on a detached callback (or a
// throw that escapes one) must NOT take the whole process down — otherwise
// Docker restarts it (dropping every session) and a bare Windows run just dies
// ("connection pipe closed", bot offline). Log and keep serving; the bridge's
// own watcher reconnects the dropped pipe. Targeted handlers still cover the
// known paths (e.g. the hook-client send deferreds) — these only catch what
// slips through, and surface its stack so the real source can be fixed.
process.on('unhandledRejection', (reason) => {
log.error('unhandledRejection (kept alive): %s',
reason instanceof Error ? (reason.stack ?? reason.message) : String(reason));
});
process.on('uncaughtException', (error) => {
log.error('uncaughtException (kept alive): %s', error.stack ?? error.message);
});
async function main() {
log.info('SnowLuma starting');
// One-shot: lift a legacy per-UIN musicSignUrl into the global store before
// any session (and thus any per-UIN config rewrite) can drop it.
migrateGlobalSettings();
// One-shot: purge any persisted phantom accounts (onebot_<garbage>.json) the
// native hook may have created with a timestamp-shaped UIN (issue #162).
cleanupInvalidPerUinConfigs();
const bridgeManager = new BridgeManager();
const oneBotManager = new OneBotManager();
const autoLoadOnDiscovery = resolveAutoLoad(runtimeConfig.hookAutoLoad);
const hookManager = new HookManager({ bridgeManager, autoLoadOnDiscovery });
// WebUI state-push wiring: HookManager + BridgeManager edges publish
// `processes` / `qq-list` / `connections` invalidations into a bus the
// /api/state/stream SSE handler subscribes to (no REST polling required).
const stateWiring = createStateWiring();
const hookManager = new HookManager({
bridgeManager,
autoLoadOnDiscovery,
onSessionsChanged: stateWiring.onSessionsChanged,
});
if (autoLoadOnDiscovery) {
log.info('hook auto-load enabled: every discovered QQ process will be injected');
}
oneBotManager.bind(bridgeManager);
stateWiring.bindBridgeManager(bridgeManager);
// Global notification subsystem (account up/down → webhook). Bound AFTER
// OneBotManager so the nickname fallback is already populated when it observes.
const notificationManager = createNotificationManager();
notificationManager.bind(bridgeManager);
if (
(typeof __BUILD_WEBUI__ !== 'undefined' && __BUILD_WEBUI__) ||
@@ -26,7 +69,12 @@ async function main() {
) {
try {
const { initWebUI } = await import('./webui/server');
await initWebUI(runtimeConfig.webuiPort || 5099, oneBotManager, hookManager);
await initWebUI(runtimeConfig.webuiPort || 5099, oneBotManager, hookManager, notificationManager, {
host: runtimeConfig.webuiHost,
tlsEnabled: runtimeConfig.webuiTls?.enabled,
trustProxy: runtimeConfig.trustProxy,
stateBus: stateWiring.bus,
});
} catch (err) {
log.error('Failed to start WebUI: ', err);
}
@@ -37,7 +85,9 @@ async function main() {
const shutdown = (signal: string) => async () => {
log.warn(`Shutting down (${signal})...`);
oneBotManager.dispose();
notificationManager.dispose();
hookManager.dispose();
stateWiring.dispose();
await closeLogger();
process.exit(0);
};

View File

@@ -0,0 +1,239 @@
// Global notification-channel store + the pure template renderer.
//
// Mirrors the conventions of `webui/ui-config.ts` (the plan calls for this
// explicitly): every `normalize*` is TOTAL — any unknown / corrupt input
// collapses to a safe default, numbers clamp, unknown keys are dropped — and
// persistence is an atomic write (tmp → rename) behind a module-level cache.
//
// Channels are GLOBAL (defined once here); each UIN opts into a subset via
// `OneBotConfig.notifications.channelIds` (see packages/onebot/src/config.ts).
import { boolOr, clampInt, isObject } from '@snowluma/common/coerce';
import { createLogger } from '@snowluma/common/logger';
import fs from 'fs';
import path from 'path';
const log = createLogger('Notifications.Config');
const CONFIG_DIR = 'config';
const NOTIFICATIONS_CONFIG_PATH = path.join(CONFIG_DIR, 'notifications.json');
export const NOTIFICATIONS_CONFIG_VERSION = 1 as const;
export const DEBOUNCE_SECONDS_MIN = 0;
export const DEBOUNCE_SECONDS_MAX = 3600;
export const DEFAULT_DEBOUNCE_SECONDS = 30;
/** A channel id is a slug: it is referenced by per-UIN `channelIds`, so it must
* be safe to use as a stable key. Kept in sync with `normalizeChannelIds` in
* packages/onebot/src/config.ts (cross-package; can't share without a circular
* dep — core depends on onebot, not the reverse). */
export const CHANNEL_ID_RE = /^[\w.-]+$/;
const CHANNEL_ID_MAX = 64;
const CHANNEL_NAME_MAX = 128;
const BODY_TEMPLATE_MAX = 8192;
/** event ∈ {offline, online}; rendered verbatim into `{event}`. */
export type NotificationEvent = 'offline' | 'online';
export interface NotificationChannel {
id: string;
name: string;
url: string;
bodyTemplate: string;
enabled: boolean;
}
export interface NotificationsConfig {
version: typeof NOTIFICATIONS_CONFIG_VERSION;
debounceSeconds: number;
channels: NotificationChannel[];
}
/** Default body template — Server酱-style JSON ({title}/{desp}). The WebUI
* ships additional per-vendor presets (钉钉/Discord/…) as frontend constants
* the operator can drop in. */
export const DEFAULT_BODY_TEMPLATE = `{
"title": "账号状态通知:{event}",
"desp": "您的账号状态发生了改变。\\n\\n**昵称**:{nickname}\\n**QQ号**:{uin}\\n**当前状态**:{event}\\n**时间**:{time}"
}`;
export function defaultNotificationsConfig(): NotificationsConfig {
return {
version: NOTIFICATIONS_CONFIG_VERSION,
debounceSeconds: DEFAULT_DEBOUNCE_SECONDS,
channels: [],
};
}
// ─── Template renderer ──────────────────────────────────────────────────────
/**
* Mechanical `{key}` substitution — no logic, no conditionals, no escaping.
* A key present in `vars` is replaced by its value; an unknown `{key}` is left
* untouched (原样) so a typo'd placeholder is visible rather than silently
* blanked. Pure + total (a non-string template yields '').
*
* **JSON safety**: When the template is valid JSON (parseable by JSON.parse),
* values are escaped to prevent breaking the JSON structure — backslashes
* become `\\` and double-quotes become `\"`.
*/
export function renderTemplate(template: string, vars: Record<string, string>): string {
if (typeof template !== 'string') return '';
let isJson = false;
try {
JSON.parse(template);
isJson = true;
} catch {
// not JSON — plain text mode
}
return template.replace(/\{(\w+)\}/g, (match, key: string) => {
if (!Object.prototype.hasOwnProperty.call(vars, key)) return match;
const val = vars[key];
return isJson ? val.replace(/\\/g, '\\\\').replace(/"/g, '\\"') : val;
});
}
// ─── Normalization helpers ──────────────────────────────────────────────────
// isObject / boolOr / clampInt come from @snowluma/common/coerce. strOr is
// notifications-only (string truncation to maxLen), so it stays here.
function strOr(value: unknown, fallback: string, maxLen: number): string {
return typeof value === 'string' ? value.slice(0, maxLen) : fallback;
}
function normalizeChannelId(value: unknown): string | null {
if (typeof value !== 'string') return null;
const v = value.trim();
if (v.length === 0 || v.length > CHANNEL_ID_MAX) return null;
if (!CHANNEL_ID_RE.test(v)) return null;
return v;
}
function isHttpUrl(value: string): boolean {
try {
const u = new URL(value);
return u.protocol === 'http:' || u.protocol === 'https:';
} catch {
return false;
}
}
/** A channel is usable only with a valid id AND an http(s) target — anything
* else is unusable, so the whole entry is dropped (total normalize). */
function normalizeChannel(raw: unknown): NotificationChannel | null {
if (!isObject(raw)) return null;
const id = normalizeChannelId(raw.id);
if (!id) return null;
const url = typeof raw.url === 'string' ? raw.url.trim() : '';
if (!isHttpUrl(url)) return null;
const name = strOr(raw.name, id, CHANNEL_NAME_MAX).trim() || id;
return {
id,
name,
url,
bodyTemplate: strOr(raw.bodyTemplate, DEFAULT_BODY_TEMPLATE, BODY_TEMPLATE_MAX),
enabled: boolOr(raw.enabled, true),
};
}
function normalizeChannels(value: unknown): NotificationChannel[] {
if (!Array.isArray(value)) return [];
const seen = new Set<string>();
const out: NotificationChannel[] = [];
for (const raw of value) {
const ch = normalizeChannel(raw);
if (!ch) continue;
if (seen.has(ch.id)) continue; // dedupe by id — first occurrence wins
seen.add(ch.id);
out.push(ch);
}
return out;
}
export function normalizeNotificationsConfig(value: unknown): NotificationsConfig {
const v = isObject(value) ? value : {};
return {
version: NOTIFICATIONS_CONFIG_VERSION,
debounceSeconds: clampInt(
v.debounceSeconds,
DEBOUNCE_SECONDS_MIN,
DEBOUNCE_SECONDS_MAX,
DEFAULT_DEBOUNCE_SECONDS,
),
channels: normalizeChannels(v.channels),
};
}
// ─── Persistence (atomic write + module-level cache) ────────────────────────
function ensureConfigDir(): void {
fs.mkdirSync(CONFIG_DIR, { recursive: true });
}
function atomicWrite(config: NotificationsConfig): void {
ensureConfigDir();
const tmp = NOTIFICATIONS_CONFIG_PATH + '.tmp';
fs.writeFileSync(tmp, JSON.stringify(config, null, 2), 'utf8');
fs.renameSync(tmp, NOTIFICATIONS_CONFIG_PATH);
}
let cached: NotificationsConfig | null = null;
/** Load + normalize the channel store, creating it from defaults if absent. */
export function loadNotificationsConfig(): NotificationsConfig {
if (cached) return cached;
ensureConfigDir();
if (!fs.existsSync(NOTIFICATIONS_CONFIG_PATH)) {
const fresh = defaultNotificationsConfig();
try {
atomicWrite(fresh);
} catch (err) {
log.warn('failed to write initial notifications.json: %s', err instanceof Error ? err.message : String(err));
}
cached = fresh;
return fresh;
}
try {
const raw = fs.readFileSync(NOTIFICATIONS_CONFIG_PATH, 'utf8');
const parsed = JSON.parse(raw) as unknown;
const normalized = normalizeNotificationsConfig(parsed);
// Self-heal on disk only if normalization changed something (corrupt/old).
if (JSON.stringify(parsed) !== JSON.stringify(normalized)) {
try {
atomicWrite(normalized);
} catch {
/* best-effort self-heal */
}
}
cached = normalized;
return normalized;
} catch (err) {
log.warn('notifications.json unreadable; using defaults: %s', err instanceof Error ? err.message : String(err));
const fresh = defaultNotificationsConfig();
cached = fresh;
return fresh;
}
}
/**
* Persist a (possibly partial) client-supplied config. A missing `channels` or
* `debounceSeconds` keeps the current on-disk value — section-level merge, same
* as `saveUiConfig`. Returns the stored, normalized config.
*/
export function saveNotificationsConfig(incoming: unknown): NotificationsConfig {
const current = loadNotificationsConfig();
const v = isObject(incoming) ? incoming : {};
const next: NotificationsConfig = {
version: NOTIFICATIONS_CONFIG_VERSION,
debounceSeconds:
v.debounceSeconds !== undefined
? clampInt(v.debounceSeconds, DEBOUNCE_SECONDS_MIN, DEBOUNCE_SECONDS_MAX, DEFAULT_DEBOUNCE_SECONDS)
: current.debounceSeconds,
channels: Array.isArray(v.channels) ? normalizeChannels(v.channels) : current.channels,
};
atomicWrite(next);
cached = next;
return next;
}

View File

@@ -0,0 +1,82 @@
// Per-UIN debounce state machine for online↔offline notifications.
//
// Uptime-Kuma semantics (grill-locked in the plan): an offline that SURVIVES
// `debounceSeconds` fires an "offline" notification; its later recovery fires
// the paired "online". An offline that self-heals within the window fires
// NOTHING (the blip is suppressed). A cold online — one with no prior fired
// offline — fires nothing (it is not a recovery).
//
// This module is PURE: no timers, no I/O, no clock. It only decides; the
// manager owns the timer + the side effects. That keeps the debounce logic
// fully unit-testable by driving a sequence of events.
import type { NotificationEvent } from './config';
export type DebounceDecision =
| { kind: 'none' }
| { kind: 'schedule'; delayMs: number }
| { kind: 'cancel' }
| { kind: 'emit'; event: NotificationEvent };
interface UinState {
/** An offline debounce timer is armed but has not yet fired. */
pending: boolean;
/** An "offline" notification has fired and is awaiting its recovery. */
firedOffline: boolean;
}
export class DebounceMachine {
private readonly states = new Map<string, UinState>();
private state(uin: string): UinState {
let s = this.states.get(uin);
if (!s) {
s = { pending: false, firedOffline: false };
this.states.set(uin, s);
}
return s;
}
/** Account went offline. `debounceSeconds` is read fresh from config so a
* reload takes effect on the next transition. */
onOffline(uin: string, debounceSeconds: number): DebounceDecision {
const s = this.state(uin);
if (s.firedOffline || s.pending) return { kind: 'none' }; // already down / already counting
// Non-finite / non-positive → no debounce, fire immediately. Stays total:
// never schedule a setTimeout(NaN|Infinity). Production config always
// clamps to a finite [0,3600]; this only hardens direct callers.
if (!Number.isFinite(debounceSeconds) || debounceSeconds <= 0) {
s.firedOffline = true;
return { kind: 'emit', event: 'offline' };
}
s.pending = true;
return { kind: 'schedule', delayMs: debounceSeconds * 1000 };
}
/** Account came online. */
onOnline(uin: string): DebounceDecision {
const s = this.state(uin);
if (s.pending) {
s.pending = false;
return { kind: 'cancel' }; // self-heal within the debounce window — nothing fired
}
if (s.firedOffline) {
s.firedOffline = false;
return { kind: 'emit', event: 'online' }; // recovery, paired with the fired offline
}
return { kind: 'none' }; // cold online / already up
}
/** The offline debounce window elapsed (the armed timer fired). */
onTimerElapsed(uin: string): DebounceDecision {
const s = this.state(uin);
if (!s.pending) return { kind: 'none' }; // cancelled before firing
s.pending = false;
s.firedOffline = true;
return { kind: 'emit', event: 'offline' };
}
/** Drop a UIN's state (e.g. on dispose). */
forget(uin: string): void {
this.states.delete(uin);
}
}

View File

@@ -0,0 +1,255 @@
// The global notification subsystem: one singleton watching ALL accounts.
//
// Subscribes to BridgeManager session online/offline edges, runs a per-UIN
// debounce state machine (see debounce.ts), and on a fired transition renders
// each opted-in + enabled channel's body template and POSTs it — recording the
// outcome in a bounded in-memory history (lost on restart, by design).
//
// Side-effecting collaborators (config load, per-UIN channel ids, the outbound
// POST, the clock) are injected so the class is fully unit-testable; the real
// wiring lives in `createNotificationManager()` at the bottom.
import { createLogger } from '@snowluma/common/logger';
import { loadOneBotConfig } from '@snowluma/onebot/config';
import type { BridgeManager } from '../bridge/manager';
import {
loadNotificationsConfig,
renderTemplate,
type NotificationChannel,
type NotificationEvent,
type NotificationsConfig,
} from './config';
import { DebounceMachine, type DebounceDecision } from './debounce';
const log = createLogger('Notifications');
const DEFAULT_HISTORY_LIMIT = 100;
const DEFAULT_POST_TIMEOUT_MS = 10_000;
const FALLBACK_DEBOUNCE_SECONDS = 30;
/** One delivery attempt; kept only in memory (the plan forbids persistence). */
export interface DeliveryRecord {
time: number;
uin: string;
event: NotificationEvent;
channelId: string;
ok: boolean;
status?: number;
error?: string;
}
export interface PostResult {
ok: boolean;
status?: number;
error?: string;
}
export interface NotificationManagerDeps {
/** Global channel store (channels + debounceSeconds). */
loadConfig: () => NotificationsConfig;
/** The channel ids a UIN has opted into. */
loadChannelIds: (uin: string) => string[];
/** Outbound delivery — never throws; failures come back as `{ ok: false }`. */
post: (url: string, body: string) => Promise<PostResult>;
now: () => number;
historyLimit?: number;
}
function errMsg(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
/**
* Pure: the channels a UIN should be notified through — globally enabled AND
* opted into by the UIN — preserving config order. Exported for unit tests.
*/
export function selectChannels(channels: NotificationChannel[], enabledIds: string[]): NotificationChannel[] {
const wanted = new Set(enabledIds);
return channels.filter((c) => c.enabled && wanted.has(c.id));
}
export class NotificationManager {
private readonly deps: NotificationManagerDeps;
private readonly machine = new DebounceMachine();
private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
private readonly nicknames = new Map<string, string>();
private readonly history: DeliveryRecord[] = [];
private readonly historyLimit: number;
constructor(deps: NotificationManagerDeps) {
this.deps = deps;
this.historyLimit = deps.historyLimit ?? DEFAULT_HISTORY_LIMIT;
}
/** Subscribe to the global session online/offline edges. Register AFTER
* OneBotManager so the nickname fallback is already populated. */
bind(bridgeManager: BridgeManager): void {
bridgeManager.addSessionStartedListener((uin, bridge) => this.handleOnline(uin, bridge.identity.nickname));
bridgeManager.addSessionClosedListener((uin, bridge) => this.handleOffline(uin, bridge.identity.nickname));
}
handleOnline(uin: string, nickname?: string): void {
if (nickname) this.nicknames.set(uin, nickname);
this.apply(uin, this.machine.onOnline(uin));
}
handleOffline(uin: string, nickname?: string): void {
if (nickname) this.nicknames.set(uin, nickname);
this.apply(uin, this.machine.onOffline(uin, this.debounceSeconds()));
}
private debounceSeconds(): number {
try {
return this.deps.loadConfig().debounceSeconds;
} catch {
return FALLBACK_DEBOUNCE_SECONDS;
}
}
private apply(uin: string, decision: DebounceDecision): void {
switch (decision.kind) {
case 'schedule': {
const existing = this.timers.get(uin);
if (existing) clearTimeout(existing);
const timer = setTimeout(() => {
this.timers.delete(uin);
this.apply(uin, this.machine.onTimerElapsed(uin));
}, decision.delayMs);
// Don't let a pending notification timer keep the process alive.
if (typeof (timer as { unref?: () => void }).unref === 'function') {
(timer as { unref: () => void }).unref();
}
this.timers.set(uin, timer);
break;
}
case 'cancel': {
const timer = this.timers.get(uin);
if (timer) {
clearTimeout(timer);
this.timers.delete(uin);
}
break;
}
case 'emit':
void this.notify(uin, decision.event);
break;
case 'none':
break;
}
}
/** Render + POST a transition to every opted-in, enabled channel and record
* the outcome. Never throws (a bad channel can't break the others). */
async notify(uin: string, event: NotificationEvent): Promise<void> {
let channels: NotificationChannel[];
try {
const cfg = this.deps.loadConfig();
channels = selectChannels(cfg.channels, this.deps.loadChannelIds(uin));
} catch (err) {
log.warn('notify(%s, %s) skipped — config load failed: %s', uin, event, errMsg(err));
return;
}
if (channels.length === 0) return;
const nickname = this.nicknames.get(uin) || uin;
const vars: Record<string, string> = {
uin,
nickname,
event,
time: new Date(this.deps.now()).toISOString(),
};
for (const ch of channels) {
const body = renderTemplate(ch.bodyTemplate, vars);
let result: PostResult;
try {
result = await this.deps.post(ch.url, body);
} catch (err) {
// The injected post is contracted not to throw, but guard anyway.
result = { ok: false, error: errMsg(err) };
}
this.record({
time: this.deps.now(),
uin,
event,
channelId: ch.id,
ok: result.ok,
status: result.status,
error: result.ok ? undefined : (result.error ?? (result.status ? `HTTP ${result.status}` : 'delivery failed')),
});
if (!result.ok) {
log.warn('notify %s→%s channel=%s failed: %s', uin, event, ch.id, result.error ?? `HTTP ${result.status ?? '?'}`);
}
}
}
/** Send a one-off test to a single channel by id — ignores `enabled` and the
* per-UIN opt-in (you test a channel before wiring it up), with sample
* variables. Reuses the real render+POST path; NOT recorded to history.
* `found:false` means the channel id is unknown. */
async testSend(channelId: string): Promise<PostResult & { found: boolean }> {
let channel: NotificationChannel | undefined;
try {
channel = this.deps.loadConfig().channels.find((c) => c.id === channelId);
} catch (err) {
return { ok: false, found: false, error: errMsg(err) };
}
if (!channel) return { ok: false, found: false };
const body = renderTemplate(channel.bodyTemplate, {
uin: '10000',
nickname: '测试账号',
event: 'offline',
time: new Date(this.deps.now()).toISOString(),
});
try {
return { ...(await this.deps.post(channel.url, body)), found: true };
} catch (err) {
return { ok: false, found: true, error: errMsg(err) };
}
}
private record(rec: DeliveryRecord): void {
this.history.push(rec);
if (this.history.length > this.historyLimit) {
this.history.splice(0, this.history.length - this.historyLimit);
}
}
/** Most-recent-first delivery history (capped at the buffer size). */
getRecent(limit = this.historyLimit): DeliveryRecord[] {
const n = Math.max(0, Math.min(Math.trunc(limit) || 0, this.history.length));
return this.history.slice(this.history.length - n).reverse();
}
dispose(): void {
for (const timer of this.timers.values()) clearTimeout(timer);
this.timers.clear();
}
}
/** Default outbound POST: a single attempt with a timeout, JSON content-type
* (the common case for 钉钉/Discord/飞书). Never throws. */
export function createDefaultPost(timeoutMs = DEFAULT_POST_TIMEOUT_MS): NotificationManagerDeps['post'] {
return async (url, body) => {
try {
const res = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body,
signal: AbortSignal.timeout(timeoutMs),
});
return { ok: res.ok, status: res.status, error: res.ok ? undefined : `HTTP ${res.status}` };
} catch (err) {
return { ok: false, error: errMsg(err) };
}
};
}
/** The real, fully-wired singleton. */
export function createNotificationManager(): NotificationManager {
return new NotificationManager({
loadConfig: loadNotificationsConfig,
loadChannelIds: (uin) => loadOneBotConfig(uin).notifications?.channelIds ?? [],
post: createDefaultPost(),
now: () => Date.now(),
});
}

View File

@@ -0,0 +1,128 @@
// WebUI config backup/restore (Wave A2). Format: a zero-dep JSON bundle
// { version, app, createdAt, files: { "<name>": { encoding, data } } }
// over an explicit allowlist (never a whole-dir sweep) so a stray/unknown file
// can't leak and an import can't path-traverse.
//
// Credentials are gated by a toggle on both export and import. The credential
// set is: webui.json (password hash), key.pem (TLS private key), AND every
// OneBot config (onebot.json + per-account onebot_<uin>.json) — those carry the
// OneBot access token, so a no-credentials backup must NOT include them.
// cert.pem is public so it always travels.
//
// Pure functions here (read/list/decode); the fs glue (atomic two-phase write,
// snapshot) lives in server.ts. Restore is restart-to-apply, like A1.
export const BACKUP_VERSION = 1;
export const BACKUP_APP = 'snowluma';
export interface BackupFileSpec {
/** Path relative to the config dir; also the bundle key. */
name: string;
binary: boolean;
/** Sensitive (private key / password hash / access token) — credential-gated. */
credential: boolean;
}
/** Static allowlist. Per-account `onebot_<uin>.json` are matched by pattern. */
export const BACKUP_FILES: readonly BackupFileSpec[] = [
{ name: 'runtime.json', binary: false, credential: false },
{ name: 'ui.json', binary: false, credential: false },
{ name: 'notifications.json', binary: false, credential: false },
// Global all-accounts SnowLuma settings (rkey fallback servers, …). Same
// class as notifications.json: global, opt-in, non-credential.
{ name: 'snowluma.json', binary: false, credential: false },
{ name: 'cert.pem', binary: false, credential: false },
{ name: 'ui-assets/background', binary: true, credential: false },
{ name: 'webui.json', binary: false, credential: true },
{ name: 'key.pem', binary: false, credential: true },
// OneBot config carries the access token → credential.
{ name: 'onebot.json', binary: false, credential: true },
];
const SPEC_BY_NAME = new Map(BACKUP_FILES.map((f) => [f.name, f]));
const PER_UIN_ONEBOT = /^onebot_\d+\.json$/;
/** Resolve a file name (static or per-uin onebot pattern) to its spec, or null. */
export function specFor(name: string): BackupFileSpec | null {
const s = SPEC_BY_NAME.get(name);
if (s) return s;
if (PER_UIN_ONEBOT.test(name)) return { name, binary: false, credential: true };
return null;
}
export interface BackupEntry { encoding: 'utf8' | 'base64'; data: string }
export interface Backup {
version: number;
app: string;
createdAt?: string;
files: Record<string, BackupEntry>;
}
/**
* Assemble a bundle from the allowlist plus any per-account onebot files.
* `readFile` returns null for missing.
*/
export function buildBackup(
readFile: (name: string) => Buffer | null,
perUinOnebotNames: readonly string[],
opts: { includeCredentials: boolean },
createdAt: string,
): Backup {
const files: Record<string, BackupEntry> = {};
const all: BackupFileSpec[] = [
...BACKUP_FILES,
...perUinOnebotNames.filter((n) => PER_UIN_ONEBOT.test(n)).map((n) => ({ name: n, binary: false, credential: true })),
];
for (const spec of all) {
if (spec.credential && !opts.includeCredentials) continue;
const buf = readFile(spec.name);
if (!buf) continue;
files[spec.name] = spec.binary
? { encoding: 'base64', data: buf.toString('base64') }
: { encoding: 'utf8', data: buf.toString('utf8') };
}
return { version: BACKUP_VERSION, app: BACKUP_APP, createdAt, files };
}
/** Validate a parsed bundle wholesale — any defect rejects the whole import. */
export function validateBackup(parsed: unknown): { ok: true; backup: Backup } | { ok: false; error: string } {
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
return { ok: false, error: 'backup must be an object' };
}
const b = parsed as Record<string, unknown>;
if (b.app !== BACKUP_APP) return { ok: false, error: 'not a SnowLuma backup' };
if (b.version !== BACKUP_VERSION) return { ok: false, error: `unsupported backup version ${String(b.version)}` };
if (typeof b.files !== 'object' || b.files === null || Array.isArray(b.files)) {
return { ok: false, error: 'backup.files must be an object' };
}
const files = b.files as Record<string, unknown>;
for (const [name, entry] of Object.entries(files)) {
if (!specFor(name)) return { ok: false, error: `unknown file in backup: ${name}` };
if (typeof entry !== 'object' || entry === null) return { ok: false, error: `malformed entry: ${name}` };
const e = entry as Record<string, unknown>;
if (e.encoding !== 'utf8' && e.encoding !== 'base64') return { ok: false, error: `bad encoding for ${name}` };
if (typeof e.data !== 'string') return { ok: false, error: `bad data for ${name}` };
}
return { ok: true, backup: { version: BACKUP_VERSION, app: BACKUP_APP, createdAt: typeof b.createdAt === 'string' ? b.createdAt : undefined, files: files as Record<string, BackupEntry> } };
}
/**
* Decide what a (validated) bundle would restore: decode each non-skipped file
* to bytes. Pure — the caller (server.ts) does the atomic two-phase fs write so
* a mid-restore failure can't leave a half-applied live config. Credential
* files are skipped unless `restoreCredentials`.
*/
export function planRestore(
backup: Backup,
opts: { restoreCredentials: boolean },
): { restore: Array<{ name: string; data: Buffer }>; skipped: string[] } {
const restore: Array<{ name: string; data: Buffer }> = [];
const skipped: string[] = [];
for (const [name, entry] of Object.entries(backup.files)) {
const spec = specFor(name);
if (!spec) { skipped.push(name); continue; } // validated, but be defensive
if (spec.credential && !opts.restoreCredentials) { skipped.push(name); continue; }
restore.push({ name, data: Buffer.from(entry.data, entry.encoding) });
}
return { restore, skipped };
}

View File

@@ -0,0 +1,104 @@
/**
* Connection-status diff loop. OneBot adapters don't have an internal
* event-emitter for connection state (listening / connected / client-count
* changes), so this loop polls `getConnectionStatuses()` and publishes
* `connections` to the StateBus when the JSON-serialised snapshot changes
* vs the previous tick.
*
* Cheap (500ms default cadence, 1-3 accounts, ~hundreds of bytes), only
* fires the StateBus when state actually moves — so the SSE handler only
* pushes a fresh `connections` frame when the user would actually see
* something update.
*/
import type { StateBus } from './state-bus';
export interface ConnectionDiffLoopOptions {
bus: StateBus;
/** Read the current adapter-status snapshot for every live UIN. */
getSnapshot: () => unknown;
/** Optional projector — return the "comparable" subset of the snapshot.
* The full snapshot is what the SSE handler ships to the WebUI; this
* projection is what the diff loop compares between ticks. Use it to
* strip volatile fields (e.g. HH:MM:SS timestamps embedded in adapter
* `detail` strings) that would otherwise produce a publish every tick
* under any active webhook — defeating the loop's whole purpose.
* Default: identity. */
pickComparable?: (snapshot: unknown) => unknown;
/** Poll cadence in milliseconds; default 500. */
intervalMs?: number;
}
export interface ConnectionDiffLoopHandle {
/** Stop the loop. Subsequent snapshot mutations produce nothing. */
dispose(): void;
}
export function startConnectionDiffLoop(opts: ConnectionDiffLoopOptions): ConnectionDiffLoopHandle {
const intervalMs = opts.intervalMs ?? 500;
let lastSerialized = '';
let haveBaseline = false;
let disposed = false;
// One-shot diagnostic latch: a projector that starts throwing only after
// a shape regression would otherwise wedge the baseline silently — no
// publishes, no log, no symptom besides "the dashboard's connections
// card stops updating". Surface it ONCE so the failure is visible.
let warnedProjectorThrew = false;
const tick = (): void => {
if (disposed) return;
let snap: unknown;
try {
snap = opts.getSnapshot();
} catch {
// Snapshot read failed (e.g. mid-shutdown). Skip this tick; the
// next one will retry. Don't reset the baseline so we don't
// spuriously republish when the snapshot starts working again.
return;
}
let comparable: unknown;
try {
comparable = opts.pickComparable ? opts.pickComparable(snap) : snap;
} catch (err) {
// A buggy projector must not crash the diff loop or wedge baseline.
// But silent wedge is its own bug class — log the FIRST occurrence
// so an operator can find it without re-running the loop locally.
if (!warnedProjectorThrew) {
warnedProjectorThrew = true;
// Static logger import avoided to keep the loop self-contained;
// stderr is good enough for a once-per-process latch.
// eslint-disable-next-line no-console
console.error('[connection-diff-loop] pickComparable threw — connections SSE diff will wedge until restart:', err);
}
return;
}
const serialized = JSON.stringify(comparable);
if (!haveBaseline) {
// First successful observation. The SSE handler's sendAllInitial
// already shipped a `connections` frame to every connected client
// on connect, so the baseline is what they already have — emitting
// it again would be a duplicate. Just store it.
lastSerialized = serialized;
haveBaseline = true;
return;
}
if (serialized === lastSerialized) return;
lastSerialized = serialized;
opts.bus.publish('connections');
};
const timer = setInterval(tick, intervalMs);
// Don't pin the Node event loop: the loop is permanent for the server
// lifetime by design, but tests / a future hot-reload scenario must be
// able to exit cleanly without an outstanding interval ref. Mirrors the
// tokenJanitor pattern in server.ts.
timer.unref?.();
return {
dispose(): void {
if (disposed) return;
disposed = true;
clearInterval(timer);
},
};
}

View File

@@ -0,0 +1,184 @@
import { createLogger } from '@snowluma/common/logger';
import { createHash } from 'crypto';
import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
const log = createLogger('WebUI.Consent');
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const CONFIG_DIR = 'config';
const CONSENT_CONFIG_PATH = path.join(CONFIG_DIR, 'consent.json');
// The two legal documents shown at the consent gate. Source of truth is the
// repo-root markdown; the build copies them next to the bundle (dist/) so the
// same lookup works in a packaged deploy. See vite.config.ts cp targets.
const AGREEMENT_FILES = [
{ id: 'eula' as const, file: 'EULA.md' },
{ id: 'privacy' as const, file: 'PRIVACY.md' },
];
export interface AgreementDoc {
id: 'eula' | 'privacy';
/** First markdown `# ` heading, for the tab/section title. */
title: string;
/** Declared "Version: x" from the doc — display only, NOT the consent key. */
declaredVersion: string;
/** Declared effective date (YYYY-MM-DD) — display only. */
effectiveDate: string;
/** Full markdown body the frontend renders. */
text: string;
}
export interface ConsentRecord {
/** The content-hash agreements version that was accepted. */
version: string;
/** ISO timestamp of acceptance. */
acceptedAt: string;
}
export interface AgreementsPayload {
/** Content-hash version of the current agreement set. */
version: string;
/**
* True when the operator must (re-)accept: the agreements carry real text
* AND the stored consent version differs from the current one. A missing or
* unreadable agreement set fails OPEN (no gate) so a broken bundle can never
* lock the admin out of their own panel.
*/
consentRequired: boolean;
documents: AgreementDoc[];
}
// ── Agreement loading (pure-ish; file read + parse, cached) ─────────────────
/**
* Resolve an agreement file across the dev and packaged layouts. In dev the
* server runs from source (`__dirname` = packages/core/src/webui); in a build
* it is the single bundled dist/index.mjs (`__dirname` = dist/) with the docs
* copied alongside. cwd is not reliable (dev cwd = packages/core, prod = repo
* root or dist/), so we probe a handful of candidates and take the first hit.
*/
function resolveAgreementFile(file: string): string | null {
const candidates = [
path.join(__dirname, file), // packaged: dist/<file>
path.resolve(__dirname, '..', '..', '..', '..', file), // dev tsx: repoRoot/<file>
path.resolve(process.cwd(), file), // started from repo root
path.resolve(process.cwd(), '..', '..', file), // dev cwd = packages/core
];
for (const candidate of candidates) {
try {
if (fs.existsSync(candidate)) return candidate;
} catch {
/* unreadable candidate, try next */
}
}
return null;
}
/** Extract title / declared version / effective date from a doc body. */
export function parseAgreementMeta(text: string): {
title: string;
declaredVersion: string;
effectiveDate: string;
} {
const title = text.match(/^#\s+(.+?)\s*$/m)?.[1]?.trim() ?? '';
// Matches both "Version: 1.0" / "版本 / Version:** 1.0" style lines.
const declaredVersion =
text.match(/(?:Version|版本)[^\n0-9]*([0-9][0-9A-Za-z.\-]*)/)?.[1]?.trim() ?? '';
const effectiveDate =
text.match(/(?:Effective date|生效日期)[^\n0-9]*(\d{4}-\d{2}-\d{2})/)?.[1] ?? '';
return { title, declaredVersion, effectiveDate };
}
/**
* Canonical agreements version = short sha256 over each doc's id + body.
* Deliberately content-derived, NOT app-version-derived: it stays stable when
* only the app is upgraded (so a one-time consent survives across versions),
* and changes the moment any agreement's TEXT changes (forcing re-consent).
*/
export function computeAgreementsVersion(docs: { id: string; text: string }[]): string {
const hash = createHash('sha256');
for (const doc of docs) {
hash.update(doc.id);
hash.update('\0');
hash.update(doc.text);
hash.update('\0');
}
return hash.digest('hex').slice(0, 16);
}
let cache: { docs: AgreementDoc[]; version: string } | null = null;
/** Load + parse both agreements and compute the version. Cached per process. */
export function loadAgreements(): { docs: AgreementDoc[]; version: string } {
if (cache) return cache;
const docs: AgreementDoc[] = AGREEMENT_FILES.map(({ id, file }) => {
const resolved = resolveAgreementFile(file);
let text = '';
if (resolved) {
try {
text = fs.readFileSync(resolved, 'utf8');
} catch (err) {
log.warn('failed to read %s: %s', file, err instanceof Error ? err.message : String(err));
}
} else {
log.warn('agreement file not found (looked for %s near the bundle and repo root)', file);
}
const meta = parseAgreementMeta(text);
return { id, title: meta.title, declaredVersion: meta.declaredVersion, effectiveDate: meta.effectiveDate, text };
});
cache = { docs, version: computeAgreementsVersion(docs) };
return cache;
}
// ── Consent persistence (config/consent.json, atomic) ───────────────────────
function ensureConfigDir(): void {
fs.mkdirSync(CONFIG_DIR, { recursive: true });
}
function isConsentRecord(value: unknown): value is ConsentRecord {
if (!value || typeof value !== 'object') return false;
const v = value as Record<string, unknown>;
return typeof v.version === 'string' && v.version.length > 0 && typeof v.acceptedAt === 'string';
}
export function loadConsentRecord(): ConsentRecord | null {
try {
if (!fs.existsSync(CONSENT_CONFIG_PATH)) return null;
const parsed = JSON.parse(fs.readFileSync(CONSENT_CONFIG_PATH, 'utf8')) as unknown;
return isConsentRecord(parsed) ? parsed : null;
} catch (err) {
log.warn('consent.json unreadable, treating as no consent: %s', err instanceof Error ? err.message : String(err));
return null;
}
}
function atomicWrite(record: ConsentRecord): void {
ensureConfigDir();
const tmp = CONSENT_CONFIG_PATH + '.tmp';
fs.writeFileSync(tmp, JSON.stringify(record, null, 2), { encoding: 'utf8' });
fs.renameSync(tmp, CONSENT_CONFIG_PATH);
}
/** Persist that the operator accepted `version`. Returns the stored record. */
export function recordConsent(version: string): ConsentRecord {
const record: ConsentRecord = { version, acceptedAt: new Date().toISOString() };
atomicWrite(record);
return record;
}
/** True when the agreements carry real text and the stored consent is stale. */
export function isConsentRequired(): boolean {
const { docs, version } = loadAgreements();
const hasContent = docs.some((d) => d.text.trim().length > 0);
if (!hasContent) return false; // fail open: never brick the panel on a broken bundle
return loadConsentRecord()?.version !== version;
}
/** Public payload for GET /api/agreements (texts + version + consentRequired). */
export function getAgreementsPayload(): AgreementsPayload {
const { docs, version } = loadAgreements();
return { version, consentRequired: isConsentRequired(), documents: docs };
}

View File

@@ -0,0 +1,28 @@
// SSE frame pusher for the debug stream (Wave A3). Drops frames under
// backpressure (consumer slow → desiredSize <= 0) instead of buffering
// unbounded into memory, and coalesces the drop count into a {kind:'dropped'}
// marker emitted just before the next delivered frame. Extracted from the route
// handler so this (easy-to-get-wrong) logic is unit-tested.
export interface FramePusherOptions {
/** The stream controller's current desiredSize (null = no backpressure info). */
desiredSize: () => number | null;
/** Deliver an encoded SSE chunk (the caller maps this to the controller). */
enqueue: (chunk: Uint8Array) => void;
encode?: (s: string) => Uint8Array;
}
/** Returns a `push(payload)` that frames + delivers with backpressure dropping. */
export function createFramePusher(opts: FramePusherOptions): (payload: unknown) => void {
const encode = opts.encode ?? ((s: string) => new TextEncoder().encode(s));
let dropped = 0;
return (payload: unknown): void => {
const d = opts.desiredSize();
if (d !== null && d <= 0) { dropped += 1; return; }
if (dropped > 0) {
opts.enqueue(encode(`data: ${JSON.stringify({ kind: 'dropped', count: dropped })}\n\n`));
dropped = 0;
}
opts.enqueue(encode(`data: ${JSON.stringify(payload)}\n\n`));
};
}

View File

@@ -0,0 +1,197 @@
// debug-tools — backend for the debug console's two heavier endpoints
// (Phase 2 of the debug-console expansion):
//
// • POST /api/debug/invoke-stream — drive a Stream API action and relay every
// frame to the browser over an SSE body. Unlike the live-activity stream
// (debug-stream.ts), this MUST NOT drop frames: a file transfer that loses a
// chunk is corrupt. So backpressure is handled by *waiting* for the consumer
// to drain, never by dropping.
// • POST /api/debug/upload — stream a browser-selected file to a temp path on
// the SERVER (the bot runs on the server, not the user's machine), so the
// returned path can be fed to a send action. Streamed straight to disk with a
// byte cap — never buffered whole, so large videos don't blow up memory.
//
// The pure pieces live here (path sanitisation, the size-capped disk sink, the
// stream-invoke Response builder) so they are unit-testable away from Hono.
import { createWriteStream } from 'fs';
import { mkdir, readdir, rm, stat } from 'fs/promises';
import os from 'os';
import path from 'path';
import { randomBytes } from 'crypto';
/** Temp dir for browser→server uploads. Siblings the Stream API's temp root but
* kept distinct so the two cleanup stories don't entangle. */
export const DEBUG_UPLOAD_DIR = path.join(os.tmpdir(), 'snowluma-debug-upload');
/** Hard ceiling on a single upload. Mirrors the Stream API's upload cap. */
export const MAX_UPLOAD_BYTES = 4 * 1024 * 1024 * 1024; // 4 GiB
/** Uploads older than this are swept on the next upload (best-effort). */
const UPLOAD_TTL_MS = 24 * 60 * 60 * 1000;
/** Reduce a client-supplied filename to a safe basename (extension preserved),
* with no path separators or traversal. The client path is NEVER trusted for
* placement — this is only used to keep the stored name human-readable. */
export function safeUploadName(raw: string | undefined): string {
// Treat both separators as path delimiters, then take the basename so any
// `../` / absolute prefix is discarded regardless of host platform.
const base = path.basename(String(raw ?? '').replace(/\\/g, '/'));
const cleaned = base
.replace(/[^\w.\-]+/g, '_') // collapse anything exotic to underscore
.replace(/^\.+/, '') // no leading dots (no hidden / '..' names)
.slice(0, 120);
return cleaned || 'file';
}
/** Unguessable destination path under DEBUG_UPLOAD_DIR for a sanitised name.
* Throws if the composed path would escape the dir (defence in depth — it
* can't, given the random id + basename, but we assert anyway). */
export function uploadDestPath(safeName: string): string {
const id = randomBytes(12).toString('hex');
const dest = path.join(DEBUG_UPLOAD_DIR, `${id}__${safeName}`);
const rel = path.relative(DEBUG_UPLOAD_DIR, dest);
if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
throw new Error('invalid upload path');
}
return dest;
}
/** Stream raw request-body bytes to a temp file under DEBUG_UPLOAD_DIR, enforcing
* a byte cap. Returns the final server path + byte size. On overflow or any
* error the partial file is removed and the call rejects. Never buffers the
* whole body. */
export async function streamUploadToDisk(
body: ReadableStream<Uint8Array> | null,
filename: string | undefined,
opts: { maxBytes?: number } = {},
): Promise<{ path: string; size: number }> {
if (!body) throw new Error('empty body');
const maxBytes = opts.maxBytes ?? MAX_UPLOAD_BYTES;
await mkdir(DEBUG_UPLOAD_DIR, { recursive: true });
void sweepOldUploads(); // fire-and-forget TTL cleanup
const dest = uploadDestPath(safeUploadName(filename));
const out = createWriteStream(dest, { mode: 0o600 });
// A WriteStream emits 'error' ASYNCHRONOUSLY (ENOSPC / EIO / quota) during a
// background flush — typically while we're parked at reader.read() or waiting
// on 'drain'. An unhandled 'error' event would crash the whole process, and a
// backpressured error would leave 'drain' to never fire (a forever-hung await
// + leaked fd). So turn it into a rejection and race it into every await; the
// catch below then destroys + unlinks the partial.
const errored = new Promise<never>((_, rej) => out.once('error', rej));
errored.catch(() => { /* swallow a late error after success (still raced below) */ });
let size = 0;
try {
const reader = body.getReader();
for (;;) {
const { done, value } = await Promise.race([errored, reader.read()]);
if (done) break;
if (!value || value.byteLength === 0) continue;
size += value.byteLength;
if (size > maxBytes) throw new Error('上传超出大小上限');
// Respect the write stream's backpressure (but never hang on an error).
if (!out.write(value)) {
await Promise.race([errored, new Promise<void>((res) => out.once('drain', res))]);
}
}
await Promise.race([errored, new Promise<void>((res, rej) => out.end((err?: Error | null) => (err ? rej(err) : res())))]);
if (size === 0) throw new Error('empty body');
return { path: dest, size };
} catch (err) {
// Wait for the stream to fully close BEFORE unlinking: createWriteStream
// opens the fd asynchronously, so a fast failure can reach `rm` before the
// file even exists on disk — then the late open would re-create it and leak
// the partial. 'close' guarantees the fd is settled and no more writes land.
out.destroy();
if (!out.closed) await new Promise<void>((res) => out.once('close', () => res()));
await rm(dest, { force: true }).catch(() => { /* best-effort */ });
throw err;
}
}
/** Remove upload temp files older than the TTL. Best-effort; never throws. */
export async function sweepOldUploads(now: number = Date.now()): Promise<number> {
let removed = 0;
try {
const names = await readdir(DEBUG_UPLOAD_DIR);
await Promise.all(
names.map(async (n) => {
const p = path.join(DEBUG_UPLOAD_DIR, n);
try {
const s = await stat(p);
if (now - s.mtimeMs > UPLOAD_TTL_MS) {
await rm(p, { force: true, recursive: true });
removed += 1;
}
} catch { /* racing cleanup / vanished file */ }
}),
);
} catch { /* dir absent yet */ }
return removed;
}
/** Drives a stream-capable action and relays its frames. The driver is the
* instance's `invokeStream` (which itself handles non-stream actions by emitting
* a single frame). */
export type StreamInvokeDriver = (
rawRequest: string,
emit: (json: string) => Promise<void>,
isAlive: () => boolean,
) => Promise<void>;
/** How long emit() will wait for a backed-up consumer to drain before it gives
* up waiting and enqueues anyway (the request abort / action idle-watchdog are
* the real stall guards). */
const DRAIN_WAIT_MS = 20;
const DRAIN_MAX_SPINS = 3000; // 3000 * 20ms ≈ 60s
/** Build the SSE `Response` for `/api/debug/invoke-stream`: each relayed frame
* is one `data: <json>\n\n` event; no frame is ever dropped. A driver error
* becomes a terminal `failed` frame. Closing the request (signal abort) stops
* delivery. `delay` is injectable for tests. */
export function buildStreamInvokeResponse(
driver: StreamInvokeDriver,
rawRequest: string,
signal: AbortSignal,
delay: (ms: number) => Promise<void> = (ms) => new Promise((r) => setTimeout(r, ms)),
): Response {
const encoder = new TextEncoder();
const stream = new ReadableStream<Uint8Array>({
async start(controller) {
let closed = false;
const onAbort = () => { closed = true; };
signal.addEventListener('abort', onAbort);
const isAlive = () => !closed && !signal.aborted;
const emit = async (json: string): Promise<void> => {
if (!isAlive()) throw new Error('stream transport closed');
// Backpressure WITHOUT dropping: wait for the consumer to catch up.
let spins = 0;
while (isAlive() && (controller.desiredSize ?? 1) <= 0 && spins < DRAIN_MAX_SPINS) {
await delay(DRAIN_WAIT_MS);
spins += 1;
}
if (!isAlive()) throw new Error('stream transport closed');
controller.enqueue(encoder.encode(`data: ${json}\n\n`));
};
try {
await driver(rawRequest, emit, isAlive);
} catch (err) {
if (isAlive()) {
const msg = err instanceof Error ? err.message : 'stream error';
try {
controller.enqueue(encoder.encode(`data: ${JSON.stringify({ status: 'failed', retcode: 1400, message: msg, wording: msg })}\n\n`));
} catch { /* controller already torn down */ }
}
} finally {
signal.removeEventListener('abort', onAbort);
try { controller.close(); } catch { /* already closed */ }
}
},
});
return new Response(stream, {
headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' },
});
}

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,69 @@
import { type Context } from 'hono';
/**
* The per-connection channel handed to an SSE endpoint's `start` callback.
* Everything the endpoint needs to talk to the client, without owning the
* transport lifecycle (heartbeat / teardown / abort / headers).
*/
export interface SseChannel {
/** Enqueue a raw chunk. Tears the stream down if the peer is already gone. */
raw(chunk: Uint8Array): void;
/** Encode a string to bytes (shared TextEncoder). */
encode(s: string): Uint8Array;
/** Convenience: enqueue one `data: <json>\n\n` frame. */
send(payload: unknown): void;
/** Register a cleanup to run once on teardown (unsubscribe / dispose). */
onClose(fn: () => void): void;
/** True after teardown — guard sends from late subscription callbacks. */
isClosed(): boolean;
/** Underlying controller backpressure signal, for `createFramePusher`. */
desiredSize(): number | null;
}
/**
* The SSE HTTP transport shell shared by the WebUI's live endpoints. Owns the
* TextEncoder, a `closed` guard, a 15s `: heartbeat` keep-alive, teardown
* (clear heartbeat → run registered cleanups → close the controller), safe
* enqueue (a throw means the peer dropped → teardown), the abort listener, and
* the `text/event-stream` headers. `start` wires up the endpoint-specific
* subscription + initial sends via the channel.
*
* Each of `/api/debug/stream`, `/api/state/stream`, `/api/logs/stream`
* previously hand-copied this ~40-line skeleton; a heartbeat-interval /
* teardown-order / header change had to be kept in sync across all three.
*/
export function sseResponse(c: Context, start: (ch: SseChannel) => void): Response {
const stream = new ReadableStream<Uint8Array>({
start(controller) {
const encoder = new TextEncoder();
let closed = false;
let heartbeat: ReturnType<typeof setInterval> | undefined;
const cleanups: Array<() => void> = [];
const teardown = () => {
if (closed) return;
closed = true;
if (heartbeat) clearInterval(heartbeat);
for (const fn of cleanups) { try { fn(); } catch { /* ignore */ } }
try { controller.close(); } catch { /* ignore */ }
};
const raw = (chunk: Uint8Array) => {
if (closed) return;
try { controller.enqueue(chunk); } catch { teardown(); }
};
const ch: SseChannel = {
raw,
encode: (s) => encoder.encode(s),
send: (payload) => raw(encoder.encode(`data: ${JSON.stringify(payload)}\n\n`)),
onClose: (fn) => { cleanups.push(fn); },
isClosed: () => closed,
desiredSize: () => controller.desiredSize,
};
start(ch);
heartbeat = setInterval(() => raw(encoder.encode(': heartbeat\n\n')), 15000);
c.req.raw.signal.addEventListener('abort', teardown);
},
});
return new Response(stream, {
headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' },
});
}

View File

@@ -0,0 +1,67 @@
/**
* StateBus — pure pub/sub for WebUI state-resource invalidations.
*
* Three resources are tracked: `processes`, `qq-list`, `connections`. A
* publisher (HookSession status change, BridgeManager session start/close,
* the connection-status diff loop) calls `publish(resource)` to signal "the
* snapshot for THIS resource is stale; whoever cares should re-read". The
* `/api/state/stream` SSE handler subscribes, debounces, and pushes fresh
* snapshots to connected WebUI clients.
*
* Intentionally pure pub/sub (no debounce, no snapshot caching): debounce
* and snapshot reads live with the subscriber so different consumers can
* coalesce on different cadences. Snapshot semantics on fan-out: the
* subscriber set is FROZEN at the start of each publish, so a listener
* that subscribes during the fan-out only sees the FOLLOWING publish, and
* a listener that unsubscribes mid-fan-out does not prevent its peers
* from completing.
*/
export type StateResource = 'processes' | 'qq-list' | 'connections';
export type StateListener = (resource: StateResource) => void;
export class StateBus {
private readonly listeners = new Set<StateListener>();
private disposed = false;
/** Subscribe to every publish; returns an unsubscribe handle. Calling
* the handle more than once is a no-op. */
subscribe(listener: StateListener): () => void {
if (this.disposed) return () => undefined;
this.listeners.add(listener);
let active = true;
return () => {
if (!active) return;
active = false;
this.listeners.delete(listener);
};
}
/** Notify every CURRENTLY-subscribed listener that `resource` is stale.
* Iterates a frozen snapshot of the subscriber set so add/remove during
* the emit don't change which listeners see THIS publish; subscriber
* exceptions are isolated and do not abort the fan-out. */
publish(resource: StateResource): void {
if (this.disposed) return;
// Snapshot the current subscribers — any subscribe()/unsubscribe()
// called by a listener during the fan-out takes effect only for the
// NEXT publish, not this one.
const snapshot = [...this.listeners];
for (const fn of snapshot) {
try {
fn(resource);
} catch {
// Subscriber-internal failure is its own problem. The bus's job
// is to keep delivery moving — surfacing an error here would
// partially abort the fan-out and create skip-the-listener bugs.
}
}
}
/** Drop every subscriber and refuse future subscribes / publishes. */
dispose(): void {
this.disposed = true;
this.listeners.clear();
}
}

View File

@@ -0,0 +1,128 @@
/**
* Bind a StateBus to an SSE-friendly `send` callback: every publish becomes
* a debounced fresh-snapshot frame, and `sendAllInitial()` primes a new
* connection with one frame per resource.
*
* Decoupled from the HTTP layer so the route handler in server.ts can drop
* its responsibility down to "open a ReadableStream, hand its enqueue to
* bindStateStream, abort tears it down". Pure logic = unit-testable with
* fake timers; no Response/controller mocking needed.
*
* Per-resource debounce, not global: an 'qq-list' churn during a slow
* 'processes' burst must not delay the qq-list frame, and a 'connections'
* diff loop running at 500ms must not coalesce 10 unrelated processes
* events into one. Each resource is its own timer.
*/
import type { StateBus, StateResource } from './state-bus';
export interface StateStreamFrame {
resource: StateResource;
data: unknown;
}
export interface BindStateStreamOptions {
bus: StateBus;
/** Read the current snapshot for one resource. May be sync or async. */
snapshot: (resource: StateResource) => unknown | Promise<unknown>;
/** Receive a fresh frame; called once per debounced publish.
* Exceptions are caught — a dead controller must not abort the bus
* subscription or break sibling resources. */
send: (frame: StateStreamFrame) => void;
/** Coalesce window in milliseconds; default 50. */
debounceMs?: number;
}
export interface StateStreamHandle {
/** Emit one frame per resource using the current snapshot. Use on connect. */
sendAllInitial(): Promise<void>;
/** Stop subscribing + cancel pending timers. Subsequent bus publishes
* produce nothing through this binding. */
dispose(): void;
}
const ALL_RESOURCES: readonly StateResource[] = ['processes', 'qq-list', 'connections'];
export function bindStateStream(opts: BindStateStreamOptions): StateStreamHandle {
const debounceMs = opts.debounceMs ?? 50;
const timers = new Map<StateResource, ReturnType<typeof setTimeout>>();
// Single-flight per resource: at most one in-flight flush per resource so
// an uneven snapshot latency cannot interleave sends out of order (a slow
// earlier snapshot landing AFTER a later one, leaving the client's last
// observed frame stale). Publishes arriving while a flush is in flight
// mark `pending` and rearm the debounce timer once the flush completes.
const inFlight = new Set<StateResource>();
const pending = new Set<StateResource>();
let disposed = false;
const flush = async (resource: StateResource): Promise<void> => {
if (disposed) return;
inFlight.add(resource);
try {
let data: unknown;
try {
data = await opts.snapshot(resource);
} catch {
// Per-resource snapshot failure (e.g. listProcesses threw): skip
// this frame so siblings keep flowing. The next publish for the
// same resource gets a fresh attempt.
return;
}
if (disposed) return;
try {
opts.send({ resource, data });
} catch {
// Downstream consumer (e.g. closed SSE controller) — same isolation
// contract as snapshot failures.
}
} finally {
inFlight.delete(resource);
// If a publish arrived during the in-flight window, schedule one
// follow-up flush. Re-uses the debounce so a sustained publish
// stream produces at most one frame per (debounceMs + flushLatency),
// not back-to-back frames.
if (!disposed && pending.has(resource)) {
pending.delete(resource);
schedule(resource);
}
}
};
const schedule = (resource: StateResource): void => {
if (disposed) return;
if (inFlight.has(resource)) {
// Defer to the post-flush re-arm; no new timer until the in-flight
// send completes. This is the load-bearing invariant for ordering.
pending.add(resource);
return;
}
const existing = timers.get(resource);
if (existing) clearTimeout(existing);
const t = setTimeout(() => {
timers.delete(resource);
void flush(resource);
}, debounceMs);
timers.set(resource, t);
};
const unsubscribe = opts.bus.subscribe(schedule);
return {
async sendAllInitial(): Promise<void> {
if (disposed) return;
// Fire all three in parallel. Each resource's snapshot is independent
// so a slow listProcesses() doesn't gate qq-list/connections. Each
// call goes through the single-flight gate so a concurrent bus
// publish during this initial fan-out coalesces correctly.
await Promise.all(ALL_RESOURCES.map((r) => flush(r)));
},
dispose(): void {
if (disposed) return;
disposed = true;
unsubscribe();
for (const t of timers.values()) clearTimeout(t);
timers.clear();
pending.clear();
},
};
}

View File

@@ -0,0 +1,73 @@
/**
* State-wiring — couples the publisher edges (HookManager session events,
* BridgeManager session-started / session-closed) to a fresh StateBus so the
* `/api/state/stream` SSE handler can push snapshot invalidations to the
* WebUI without REST polling.
*
* Decoupling rationale:
* - HookManager owns the per-process state-machine; it knows when a
* session's `listProcesses()` view changes. We feed it `onSessionsChanged`
* (callable from outside the bridge package) so this file is the ONLY
* place that imports both the bus and HookManager's dep shape.
* - BridgeManager fires `session-started` / `session-closed` listeners on
* account edges (the OneBot instance list mutates around these). We add
* listeners directly so `qq-list` + `connections` invalidate at the right
* moment without modifying BridgeManager.
*
* `dispose()` unwires everything so a test (or a future hot-reload) can
* recreate the wiring without leaking listeners.
*/
import { StateBus } from './state-bus';
import type { BridgeManager } from '../bridge/manager';
export interface StateWiring {
/** The bus the SSE handler subscribes to. */
readonly bus: StateBus;
/** Pass as the HookManager `onSessionsChanged` dep — publishes 'processes'. */
onSessionsChanged: () => void;
/** Hook into a BridgeManager so its session edges publish 'qq-list' and
* 'connections'. Can be called at most once per wiring (subsequent calls
* add duplicate listeners). */
bindBridgeManager(bm: BridgeManager): void;
/** Drop every listener + neuter the bus so further publishes do nothing. */
dispose(): void;
}
export function createStateWiring(): StateWiring {
const bus = new StateBus();
let disposed = false;
const publish = (resource: Parameters<StateBus['publish']>[0]): void => {
if (disposed) return;
bus.publish(resource);
};
return {
bus,
onSessionsChanged: () => publish('processes'),
bindBridgeManager(bm: BridgeManager): void {
// Account appeared: the qq-list response gains an entry and the
// connections response gains the new account's adapter row. Two
// distinct resource invalidations, in source-of-truth order
// (account exists → only then can adapters be enumerated for it).
bm.addSessionStartedListener(() => {
publish('qq-list');
publish('connections');
});
// Account disappeared: same two resources shrink, same order so a
// racy WebUI receiving both events independently sees the qq-list
// shrink before it tries to render connections for a uin that's
// about to vanish.
bm.addSessionClosedListener(() => {
publish('qq-list');
publish('connections');
});
},
dispose(): void {
if (disposed) return;
disposed = true;
bus.dispose();
},
};
}

View File

@@ -0,0 +1,52 @@
// Pure validator for the POST /api/system/settings body. Rejects clearly-bad
// input with a message (→ 400) rather than silently normalizing it, then hands
// a clean patch to updateRuntimeConfig. Wire field `tlsEnabled` maps to the
// nested `webuiTls.enabled`.
import type { RuntimeConfig } from '@snowluma/common/runtime';
export type SettingsPatch = Partial<Pick<RuntimeConfig, 'webuiPort' | 'webuiHost' | 'webuiTls' | 'trustProxy'>>;
export type CoerceResult =
| { ok: true; patch: SettingsPatch }
| { ok: false; error: string };
function isObject(v: unknown): v is Record<string, unknown> {
return typeof v === 'object' && v !== null && !Array.isArray(v);
}
export function coerceSettingsPatch(body: unknown): CoerceResult {
if (!isObject(body)) return { ok: false, error: 'body must be an object' };
const patch: SettingsPatch = {};
if ('webuiPort' in body) {
const p = body.webuiPort;
if (typeof p !== 'number' || !Number.isInteger(p) || p <= 0 || p > 65535) {
return { ok: false, error: 'webuiPort must be an integer in 1..65535' };
}
patch.webuiPort = p;
}
if ('webuiHost' in body) {
if (typeof body.webuiHost !== 'string' || !body.webuiHost.trim()) {
return { ok: false, error: 'webuiHost must be a non-empty string' };
}
patch.webuiHost = body.webuiHost.trim();
}
if ('tlsEnabled' in body) {
if (typeof body.tlsEnabled !== 'boolean') {
return { ok: false, error: 'tlsEnabled must be a boolean' };
}
patch.webuiTls = { enabled: body.tlsEnabled };
}
if ('trustProxy' in body) {
if (typeof body.trustProxy !== 'string') {
return { ok: false, error: 'trustProxy must be a string' };
}
patch.trustProxy = body.trustProxy;
}
return { ok: true, patch };
}

View File

@@ -0,0 +1,57 @@
// WebUI TLS helpers. Cert/key live as config/cert.pem + config/key.pem
// (NapCat-aligned, self-contained, travels in A2 backups). Two pure-ish
// helpers: validate a pasted pair (save path) and resolve the on-disk pair
// (boot path). Validation is `tls.createSecureContext` — it parses the PEM
// and checks the key matches the cert; expiry is NOT checked here.
import fs from 'fs';
import path from 'path';
import tls from 'tls';
export interface TlsValidation {
ok: boolean;
reason?: string;
}
export interface TlsResolution {
ok: boolean;
cert?: Buffer;
key?: Buffer;
reason?: string;
}
function errMsg(e: unknown): string {
return e instanceof Error ? e.message : String(e);
}
/** Parse-validate a cert/key pair (used by the save endpoint before writing). */
export function validateTlsPair(cert: string | Buffer, key: string | Buffer): TlsValidation {
if (!cert || !cert.toString().trim()) return { ok: false, reason: 'certificate is empty' };
if (!key || !key.toString().trim()) return { ok: false, reason: 'private key is empty' };
try {
tls.createSecureContext({ cert, key });
return { ok: true };
} catch (e) {
return { ok: false, reason: `invalid cert/key: ${errMsg(e)}` };
}
}
/** Load + validate config/cert.pem + config/key.pem from `configDir`. */
export function resolveTlsContext(configDir: string): TlsResolution {
const certPath = path.join(configDir, 'cert.pem');
const keyPath = path.join(configDir, 'key.pem');
if (!fs.existsSync(certPath) || !fs.existsSync(keyPath)) {
return { ok: false, reason: 'cert.pem or key.pem missing in config dir' };
}
let cert: Buffer;
let key: Buffer;
try {
cert = fs.readFileSync(certPath);
key = fs.readFileSync(keyPath);
} catch (e) {
return { ok: false, reason: `failed to read cert/key: ${errMsg(e)}` };
}
const valid = validateTlsPair(cert, key);
if (!valid.ok) return { ok: false, reason: valid.reason };
return { ok: true, cert, key };
}

View File

@@ -0,0 +1,767 @@
import { boolOr, clampInt, clampNum, isObject } from '@snowluma/common/coerce';
import { createLogger } from '@snowluma/common/logger';
import fs from 'fs';
import path from 'path';
// Server-side store for the WebUI customization config (`config/ui.json`).
//
// This is the single source of truth for appearance (A) + layout (C). The
// browser caches it in localStorage only to avoid a first-paint flash; the
// canonical copy lives here so a deployer's look + curated layout follow them
// across devices/browsers.
//
// Trust boundaries that this module enforces:
// * `normalizeAppearance` is total — any unknown/corrupt input collapses to
// safe defaults. This matters because the cosmetic subset is served to an
// UNAUTHENTICATED client (the login page) via `GET /api/ui/public`, so it
// must never echo attacker-controlled garbage.
// * The background-IMAGE lifecycle fields (`hasImage` / `imageMime` /
// `imageVersion`) are server-managed: a plain `POST /api/ui` cannot set
// them. Only the dedicated upload/delete endpoints mutate them. A client
// save preserves whatever is currently on disk.
const log = createLogger('WebUI.UiConfig');
const CONFIG_DIR = 'config';
const UI_CONFIG_PATH = path.join(CONFIG_DIR, 'ui.json');
/** Directory for operator-uploaded UI assets (currently just the background). */
export const UI_ASSETS_DIR = path.join(CONFIG_DIR, 'ui-assets');
/** Fixed path of the single background image (overwrite-on-upload). */
export const BACKGROUND_IMAGE_PATH = path.join(UI_ASSETS_DIR, 'background');
/** Reject uploads larger than this (bytes). */
export const MAX_BACKGROUND_BYTES = 5 * 1024 * 1024;
export const UI_CONFIG_VERSION = 1 as const;
// ─── Schema ──────────────────────────────────────────────────────────────
export type ThemeMode = 'light' | 'dark' | 'system';
export type AccentMode = 'preset' | 'custom';
export type AccentScope = 'sidebar' | 'global';
export type DarkIntensity = 'soft' | 'black';
export type SidebarStyle = 'follow' | 'panel' | 'accent';
export type BackgroundType = 'none' | 'solid' | 'gradient' | 'image';
export type Density = 'cozy' | 'compact';
export type TimeFormat = '12h' | '24h';
/** Full color scheme. 'default' keeps the sky theme (driven by `mode`); the
* Catppuccin flavors are complete palettes that also fix light/dark. */
export type Palette =
| 'default'
| 'catppuccin-latte' | 'catppuccin-frappe' | 'catppuccin-macchiato' | 'catppuccin-mocha'
| 'rose-pine' | 'rose-pine-moon' | 'rose-pine-dawn'
| 'nord'
| 'everforest-dark' | 'everforest-light';
export interface UiBackground {
type: BackgroundType;
/** Solid-fill colour (hex). Used when type === 'solid'. */
color: string;
/** Gradient preset id (frontend owns the catalogue). Used when type === 'gradient'. */
gradient: string;
/** Image readability overlay: 0 (image fully visible) … 1 (fully masked). */
imageOpacity: number;
/** Image blur in px (0…40). */
imageBlur: number;
// ── server-managed (upload/delete endpoints only) ──
hasImage: boolean;
imageMime: string;
/** Bumped on each successful upload so the browser can cache-bust. */
imageVersion: number;
}
export interface UiAppearance {
mode: ThemeMode;
accentMode: AccentMode;
/** Preset accent id (frontend catalogue: sky/blue/violet/…). */
accentPreset: string;
/** Custom accent colour (hex). Used when accentMode === 'custom'. */
accentCustom: string;
accentScope: AccentScope;
darkIntensity: DarkIntensity;
/** Full color scheme; 'default' = the built-in sky theme. */
palette: Palette;
sidebarStyle: SidebarStyle;
background: UiBackground;
/** Sans font preset id (frontend catalogue); 'custom' uses `fontSansCustom`. */
fontSans: string;
/** Free-form sans font-family stack, used when `fontSans === 'custom'`. */
fontSansCustom: string;
/** Mono font preset id (frontend catalogue); 'custom' uses `fontMonoCustom`. */
fontMono: string;
/** Free-form mono font-family stack, used when `fontMono === 'custom'`. */
fontMonoCustom: string;
/** Global UI scale, 0.9…1.2. */
uiScale: number;
/** Corner radius in rem, 0…2. */
radius: number;
density: Density;
/** Soften animations (transforms off, shorter durations). */
reduceMotion: boolean;
/** Hard-disable all UI animations (stronger than reduceMotion). */
disableMotion: boolean;
highContrast: boolean;
sidebarPinned: boolean;
timeFormat: TimeFormat;
/** Dashboard poll interval (ms); 0 = paused. */
pollInterval: number;
/**
* Operator custom CSS, applied AFTER auth only (never on the login page —
* `publicAppearance` strips it). Capped at 50 KB. The client injects it as
* the last <style> and skips it under `?safe-mode=1` so a broken rule can't
* lock the operator out.
*/
customCss: string;
/**
* Theme-token overrides from the variable panel. Keys are restricted to a
* fixed whitelist of `--token` names and values to colours / lengths, so
* (unlike `customCss`) this is safe to serve to the unauthenticated login
* page — `normalizeAppearance` drops unknown keys and invalid values.
*/
cssVars: Record<string, string>;
}
export interface UiLayoutItem {
id: string;
visible: boolean;
/**
* Grid position/size (overview blocks only; nav items omit them). The
* client owns the widget catalogue, per-widget min sizes, and the
* `stats`→tiles migration — the server just preserves + clamps these to
* sane integer bounds so a corrupt file can't store absurd coords.
*/
x?: number;
y?: number;
w?: number;
h?: number;
/**
* Per-widget settings (overview blocks only) — an opaque object the client
* interprets by widget type (e.g. alerts: count + levels). The server only
* checks it's a plain object within a size bound; it never reads the keys.
*/
config?: Record<string, unknown>;
}
export interface UiLayout {
/** Ordered overview blocks (desktop 2D grid). Frontend reconciles vs its set. */
overviewBlocks: UiLayoutItem[];
/** Ordered single-column mobile overview (id+visible only; the 2D grid is
* desktop-only). Kept separate so phone ordering never pollutes the grid. */
overviewMobile: UiLayoutItem[];
/** Ordered sidebar nav items, keyed by route path. */
navItems: UiLayoutItem[];
/** Top-bar element show/hide list (id+visible), mirroring navItems' shape. */
topbarItems: UiLayoutItem[];
}
export interface UiHighlightRule {
keyword: string;
color: string;
}
export type LogsPreset = 'dev' | 'ops' | 'minimal' | 'custom';
export interface UiLogsPrefs {
/** Log levels shown by default (client display filter). */
visibleLevels: string[];
/** Ring-buffer cap for the live view (100…5000). */
maxLines: number;
autoScroll: boolean;
wrap: boolean;
/** Keyword → colour row highlights. */
highlightRules: UiHighlightRule[];
/** Active view preset id; 'custom' = the operator hand-tuned the prefs. The
* client owns the preset → prefs bundles; the server just stores the id. */
preset: LogsPreset;
}
export interface UiPages {
/** Route the operator lands on after login (a nav path; '/' if unset). */
defaultRoute: string;
logs: UiLogsPrefs;
/** Default sort key for the processes page. */
processesSort: string;
/** Default tab id for the node-config page ('' = first). */
configTab: string;
}
export interface UiConfig {
version: typeof UI_CONFIG_VERSION;
appearance: UiAppearance;
layout: UiLayout;
pages: UiPages;
}
// ─── Defaults ────────────────────────────────────────────────────────────
// Mirror the pre-existing ThemeContext defaults so an upgrade is a no-op
// visually until the operator changes something.
const DEFAULT_BACKGROUND: UiBackground = {
type: 'none',
color: '#0ea5e9',
gradient: 'none',
imageOpacity: 0.15,
imageBlur: 0,
hasImage: false,
imageMime: '',
imageVersion: 0,
};
const DEFAULT_APPEARANCE: UiAppearance = {
mode: 'system',
accentMode: 'preset',
accentPreset: 'sky',
accentCustom: '#38bdf8',
accentScope: 'global',
darkIntensity: 'soft',
palette: 'default',
sidebarStyle: 'follow',
background: DEFAULT_BACKGROUND,
fontSans: 'default',
fontSansCustom: '',
fontMono: 'default',
fontMonoCustom: '',
uiScale: 1,
radius: 0.75,
density: 'cozy',
reduceMotion: false,
disableMotion: false,
highContrast: false,
sidebarPinned: false,
timeFormat: '24h',
pollInterval: 3000,
customCss: '',
cssVars: {},
};
const DEFAULT_OVERVIEW_BLOCKS: UiLayoutItem[] = [
{ id: 'stats', visible: true },
{ id: 'connections', visible: true },
{ id: 'alerts', visible: true },
{ id: 'host', visible: true },
{ id: 'sessions', visible: true },
];
// Single-column mobile order = the desktop grid catalogue's widgets, flattened
// (stat tiles, then the cards). The client reconciles against its real
// catalogue, so this just seeds first run; unknown ids are dropped on load.
const DEFAULT_OVERVIEW_MOBILE: UiLayoutItem[] = [
{ id: 'stat:status', visible: true },
{ id: 'stat:accounts', visible: true },
{ id: 'stat:processes', visible: true },
{ id: 'stat:host', visible: true },
{ id: 'stat:uptime', visible: true },
{ id: 'connections', visible: true },
{ id: 'alerts', visible: true },
{ id: 'host', visible: true },
{ id: 'sessions', visible: true },
];
const DEFAULT_NAV_ITEMS: UiLayoutItem[] = [
{ id: '/', visible: true },
{ id: '/processes', visible: true },
{ id: '/config', visible: true },
{ id: '/logs', visible: true },
{ id: '/settings', visible: true },
];
// Toggleable top-bar elements (essential ones — menu, page title, logout — are
// pinned in the client and never appear here). The client reconciles, so a new
// element (e.g. the kiosk button) just appears as visible.
const DEFAULT_TOPBAR_ITEMS: UiLayoutItem[] = [
{ id: 'status', visible: true },
{ id: 'theme', visible: true },
{ id: 'kiosk', visible: true },
];
const LOG_LEVELS = ['trace', 'debug', 'info', 'success', 'warn', 'error'];
const DEFAULT_PAGES: UiPages = {
defaultRoute: '/',
logs: {
visibleLevels: [...LOG_LEVELS],
maxLines: 1000,
autoScroll: true,
wrap: true,
highlightRules: [],
preset: 'custom',
},
processesSort: 'pid',
configTab: '',
};
export function defaultUiConfig(): UiConfig {
return {
version: UI_CONFIG_VERSION,
appearance: { ...DEFAULT_APPEARANCE, background: { ...DEFAULT_BACKGROUND }, cssVars: {} },
layout: {
overviewBlocks: DEFAULT_OVERVIEW_BLOCKS.map((b) => ({ ...b })),
overviewMobile: DEFAULT_OVERVIEW_MOBILE.map((b) => ({ ...b })),
navItems: DEFAULT_NAV_ITEMS.map((b) => ({ ...b })),
topbarItems: DEFAULT_TOPBAR_ITEMS.map((b) => ({ ...b })),
},
pages: defaultPages(),
};
}
function defaultPages(): UiPages {
return { ...DEFAULT_PAGES, logs: { ...DEFAULT_PAGES.logs, visibleLevels: [...LOG_LEVELS], highlightRules: [] } };
}
// ─── Normalization helpers ─────────────────────────────────────────────────
// isObject / boolOr / clampNum / clampInt come from @snowluma/common/coerce.
// oneOf (enum), isFiniteNum, and hexOr (CSS color) are ui-specific and stay.
function oneOf<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
return typeof value === 'string' && (allowed as readonly string[]).includes(value)
? (value as T)
: fallback;
}
function isFiniteNum(value: unknown): boolean {
if (typeof value === 'number') return Number.isFinite(value);
return typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value));
}
const HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
function hexOr(value: unknown, fallback: string): string {
return typeof value === 'string' && HEX_RE.test(value.trim()) ? value.trim() : fallback;
}
/** Bounded free-form id (frontend owns the actual catalogue). */
function idOr(value: unknown, fallback: string, maxLen = 64): string {
if (typeof value !== 'string') return fallback;
const v = value.trim();
if (v.length === 0 || v.length > maxLen) return fallback;
// Ids are slugs / route paths — refuse control chars and anything exotic.
if (!/^[\w./:-]+$/.test(v)) return fallback;
return v;
}
/**
* A free-form font-family value (a single family or a comma-separated stack),
* safe to interpolate into `--font-sans: <value>;`. Allows letters (incl. CJK),
* digits, spaces and the punctuation real font names use, but refuses anything
* that could break out of the declaration (`;`, `{`, `}`, control chars, etc.).
* Empty / over-long / invalid → fallback ('' = "no custom family set").
*/
const FONT_FAMILY_RE = /^[\p{L}\p{N}\s,'"._-]+$/u;
function fontFamilyOr(value: unknown, fallback: string, maxLen = 200): string {
if (typeof value !== 'string') return fallback;
const v = value.trim();
if (v.length === 0) return ''; // explicitly cleared
if (v.length > maxLen || !FONT_FAMILY_RE.test(v)) return fallback;
return v;
}
// ─── cssVars (theme-token override panel) ──────────────────────────────────
// Both the keys (which `--token` may be set) and the values (colour / length)
// are whitelisted so the result is safe to serve to the UNAUTHENTICATED login
// page — it shares the trust level of palette/accent, not of `customCss`.
/** The `--token` names the variable panel is allowed to override. Kept in sync
* with the surface/accent tokens `ThemeContext` actually injects. */
const CSS_VAR_WHITELIST = new Set<string>([
'--background', '--foreground',
'--card', '--card-foreground',
'--popover', '--popover-foreground',
'--primary', '--primary-foreground',
'--secondary', '--secondary-foreground',
'--muted', '--muted-foreground',
'--accent', '--accent-foreground',
'--destructive', '--destructive-foreground',
'--success', '--warning',
'--border', '--input', '--ring',
'--sidebar', '--sidebar-foreground',
'--sidebar-primary', '--sidebar-primary-foreground',
'--sidebar-accent', '--sidebar-accent-foreground',
'--sidebar-border', '--sidebar-ring',
]);
// A CSS colour value, restricted to forms that cannot break out of a `--token:
// <value>;` declaration. Hex, a named colour, or a single balanced functional
// notation (rgb/hsl/oklch/… and color-mix) over a safe char set — crucially no
// `;`, `{`, `}`, `:` or angle brackets are permitted anywhere.
const CSS_HEX_RE = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
const CSS_NAMED_RE = /^[a-zA-Z]{1,24}$/;
const CSS_FUNC_RE = /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix)\([a-zA-Z0-9.,%/\s#-]{1,120}\)$/;
function cssColorOrNull(value: unknown): string | null {
if (typeof value !== 'string') return null;
const v = value.trim();
if (v.length === 0 || v.length > 128) return null;
if (CSS_HEX_RE.test(v) || CSS_NAMED_RE.test(v) || CSS_FUNC_RE.test(v)) return v;
return null;
}
/** Keep only whitelisted token keys with valid colour values; drop the rest. */
function normalizeCssVars(value: unknown): Record<string, string> {
if (!isObject(value)) return {};
const out: Record<string, string> = {};
for (const key of Object.keys(value)) {
if (!CSS_VAR_WHITELIST.has(key)) continue;
const color = cssColorOrNull(value[key]);
if (color) out[key] = color;
}
return out;
}
function normalizeLayoutItems(value: unknown, fallback: UiLayoutItem[]): UiLayoutItem[] {
if (!Array.isArray(value)) return fallback.map((i) => ({ ...i }));
const seen = new Set<string>();
const out: UiLayoutItem[] = [];
for (const raw of value) {
if (!isObject(raw)) continue;
const id = idOr(raw.id, '');
if (!id || seen.has(id)) continue;
seen.add(id);
const item: UiLayoutItem = { id, visible: boolOr(raw.visible, true) };
// Grid coords are optional (overview blocks carry them; nav items don't).
// Preserve + clamp when any are present; missing ones get safe defaults
// and the client re-applies per-widget min sizes on load.
if (isFiniteNum(raw.x) || isFiniteNum(raw.y) || isFiniteNum(raw.w) || isFiniteNum(raw.h)) {
item.x = clampInt(raw.x, 0, 50, 0);
item.y = clampInt(raw.y, 0, 1000, 0);
item.w = clampInt(raw.w, 1, 12, 1);
item.h = clampInt(raw.h, 1, 100, 1);
}
// Opaque per-widget config: keep only a plain object within a size bound;
// the server never interprets the keys (the client does, per widget type).
if (isObject(raw.config)) {
try {
if (JSON.stringify(raw.config).length <= 4096) item.config = raw.config;
} catch { /* unserializable (cycles) → drop */ }
}
out.push(item);
}
// An array that parsed to nothing usable is indistinguishable from corrupt;
// fall back so the frontend always has a baseline to reconcile against.
return out.length > 0 ? out : fallback.map((i) => ({ ...i }));
}
/**
* The background-image fields are server-managed (only the upload/delete
* endpoints mutate them). Normalization NEVER derives them from the value
* being normalized — the caller supplies the trusted source:
* * LOAD path → the parsed-from-disk file IS the truth (`imageStateFromParsed`).
* * SAVE path → the current on-disk config is the truth (a client payload
* cannot forge `hasImage`).
*/
export interface ServerImageState {
hasImage: boolean;
imageMime: string;
imageVersion: number;
}
const DEFAULT_IMAGE_STATE: ServerImageState = { hasImage: false, imageMime: '', imageVersion: 0 };
const KNOWN_IMAGE_MIMES = ['image/png', 'image/jpeg', 'image/webp'];
/** Coerce a raw background-ish object into a coherent, trusted image state. */
function sanitizeImageState(value: unknown): ServerImageState {
const v = isObject(value) ? value : {};
const version = Math.trunc(clampNum(v.imageVersion, 0, Number.MAX_SAFE_INTEGER, 0));
if (!boolOr(v.hasImage, false)) return { hasImage: false, imageMime: '', imageVersion: version };
const mime = typeof v.imageMime === 'string' && KNOWN_IMAGE_MIMES.includes(v.imageMime) ? v.imageMime : '';
// "Has image" with no recognizable mime is incoherent on-disk state; treat
// it as no image so the serve path and the UI stay consistent.
if (!mime) return { hasImage: false, imageMime: '', imageVersion: version };
return { hasImage: true, imageMime: mime, imageVersion: version };
}
/** Trusted image state read FROM a parsed-from-disk config blob. */
function imageStateFromParsed(parsed: unknown): ServerImageState {
if (!isObject(parsed) || !isObject(parsed.appearance)) return DEFAULT_IMAGE_STATE;
return sanitizeImageState(parsed.appearance.background);
}
function normalizeBackground(value: unknown, imageState: ServerImageState): UiBackground {
const v = isObject(value) ? value : {};
let type = oneOf<BackgroundType>(v.type, ['none', 'solid', 'gradient', 'image'], DEFAULT_BACKGROUND.type);
// An image background is only valid when an image is actually stored —
// otherwise the serve route 404s and the UI shows a broken wallpaper.
if (type === 'image' && !imageState.hasImage) type = 'none';
return {
type,
color: hexOr(v.color, DEFAULT_BACKGROUND.color),
gradient: idOr(v.gradient, DEFAULT_BACKGROUND.gradient),
imageOpacity: clampNum(v.imageOpacity, 0, 1, DEFAULT_BACKGROUND.imageOpacity),
imageBlur: clampNum(v.imageBlur, 0, 40, DEFAULT_BACKGROUND.imageBlur),
// Server-managed — taken from the caller-supplied trusted source, never
// from the value being normalized.
hasImage: imageState.hasImage,
imageMime: imageState.imageMime,
imageVersion: imageState.imageVersion,
};
}
export function normalizeAppearance(value: unknown, imageState: ServerImageState = DEFAULT_IMAGE_STATE): UiAppearance {
const v = isObject(value) ? value : {};
return {
mode: oneOf<ThemeMode>(v.mode, ['light', 'dark', 'system'], DEFAULT_APPEARANCE.mode),
accentMode: oneOf<AccentMode>(v.accentMode, ['preset', 'custom'], DEFAULT_APPEARANCE.accentMode),
accentPreset: idOr(v.accentPreset, DEFAULT_APPEARANCE.accentPreset, 32),
accentCustom: hexOr(v.accentCustom, DEFAULT_APPEARANCE.accentCustom),
accentScope: oneOf<AccentScope>(v.accentScope, ['sidebar', 'global'], DEFAULT_APPEARANCE.accentScope),
darkIntensity: oneOf<DarkIntensity>(v.darkIntensity, ['soft', 'black'], DEFAULT_APPEARANCE.darkIntensity),
palette: oneOf<Palette>(v.palette, ['default', 'catppuccin-latte', 'catppuccin-frappe', 'catppuccin-macchiato', 'catppuccin-mocha', 'rose-pine', 'rose-pine-moon', 'rose-pine-dawn', 'nord', 'everforest-dark', 'everforest-light'], DEFAULT_APPEARANCE.palette),
sidebarStyle: oneOf<SidebarStyle>(v.sidebarStyle, ['follow', 'panel', 'accent'], DEFAULT_APPEARANCE.sidebarStyle),
background: normalizeBackground(v.background, imageState),
fontSans: idOr(v.fontSans, DEFAULT_APPEARANCE.fontSans),
fontSansCustom: fontFamilyOr(v.fontSansCustom, DEFAULT_APPEARANCE.fontSansCustom),
fontMono: idOr(v.fontMono, DEFAULT_APPEARANCE.fontMono),
fontMonoCustom: fontFamilyOr(v.fontMonoCustom, DEFAULT_APPEARANCE.fontMonoCustom),
uiScale: clampNum(v.uiScale, 0.9, 1.2, DEFAULT_APPEARANCE.uiScale),
radius: clampNum(v.radius, 0, 2, DEFAULT_APPEARANCE.radius),
density: oneOf<Density>(v.density, ['cozy', 'compact'], DEFAULT_APPEARANCE.density),
reduceMotion: boolOr(v.reduceMotion, DEFAULT_APPEARANCE.reduceMotion),
disableMotion: boolOr(v.disableMotion, DEFAULT_APPEARANCE.disableMotion),
highContrast: boolOr(v.highContrast, DEFAULT_APPEARANCE.highContrast),
sidebarPinned: boolOr(v.sidebarPinned, DEFAULT_APPEARANCE.sidebarPinned),
timeFormat: oneOf<TimeFormat>(v.timeFormat, ['12h', '24h'], DEFAULT_APPEARANCE.timeFormat),
pollInterval: clampNum(v.pollInterval, 0, 60_000, DEFAULT_APPEARANCE.pollInterval),
customCss: typeof v.customCss === 'string' ? v.customCss.slice(0, 50_000) : DEFAULT_APPEARANCE.customCss,
cssVars: normalizeCssVars(v.cssVars),
};
}
export function normalizeLayout(value: unknown): UiLayout {
const layout = isObject(value) ? value : {};
return {
overviewBlocks: normalizeLayoutItems(layout.overviewBlocks, DEFAULT_OVERVIEW_BLOCKS),
overviewMobile: normalizeLayoutItems(layout.overviewMobile, DEFAULT_OVERVIEW_MOBILE),
navItems: normalizeLayoutItems(layout.navItems, DEFAULT_NAV_ITEMS),
topbarItems: normalizeLayoutItems(layout.topbarItems, DEFAULT_TOPBAR_ITEMS),
};
}
function normalizeHighlightRules(value: unknown): UiHighlightRule[] {
if (!Array.isArray(value)) return [];
const out: UiHighlightRule[] = [];
for (const raw of value) {
if (!isObject(raw) || typeof raw.keyword !== 'string') continue;
const keyword = raw.keyword.trim().slice(0, 50);
if (!keyword) continue; // drop empty / whitespace-only (would match every row)
const color = typeof raw.color === 'string' ? raw.color.slice(0, 32) : '';
out.push({ keyword, color });
if (out.length >= 20) break; // cap the rule count
}
return out;
}
export function normalizePages(value: unknown): UiPages {
const v = isObject(value) ? value : {};
const logs = isObject(v.logs) ? v.logs : {};
const levels = Array.isArray(logs.visibleLevels)
? LOG_LEVELS.filter((l) => (logs.visibleLevels as unknown[]).includes(l))
: DEFAULT_PAGES.logs.visibleLevels;
return {
defaultRoute: idOr(v.defaultRoute, DEFAULT_PAGES.defaultRoute),
logs: {
visibleLevels: levels.length > 0 ? levels : [...LOG_LEVELS],
maxLines: clampInt(logs.maxLines, 100, 5000, DEFAULT_PAGES.logs.maxLines),
autoScroll: boolOr(logs.autoScroll, DEFAULT_PAGES.logs.autoScroll),
wrap: boolOr(logs.wrap, DEFAULT_PAGES.logs.wrap),
highlightRules: normalizeHighlightRules(logs.highlightRules),
preset: oneOf<LogsPreset>(logs.preset, ['dev', 'ops', 'minimal', 'custom'], 'custom'),
},
processesSort: idOr(v.processesSort, DEFAULT_PAGES.processesSort),
configTab: typeof v.configTab === 'string' ? v.configTab.slice(0, 64) : DEFAULT_PAGES.configTab,
};
}
export function normalizeUiConfig(value: unknown, imageState: ServerImageState = DEFAULT_IMAGE_STATE): UiConfig {
const v = isObject(value) ? value : {};
return {
version: UI_CONFIG_VERSION,
appearance: normalizeAppearance(v.appearance, imageState),
layout: normalizeLayout(v.layout),
pages: normalizePages(v.pages),
};
}
// ─── Persistence ────────────────────────────────────────────────────────────
function ensureConfigDir(): void {
fs.mkdirSync(CONFIG_DIR, { recursive: true });
}
function atomicWrite(config: UiConfig): void {
ensureConfigDir();
const tmp = UI_CONFIG_PATH + '.tmp';
fs.writeFileSync(tmp, JSON.stringify(config, null, 2), 'utf8');
fs.renameSync(tmp, UI_CONFIG_PATH);
}
let cached: UiConfig | null = null;
/** Load + normalize the UI config, creating it from defaults if absent. */
export function loadUiConfig(): UiConfig {
if (cached) return cached;
ensureConfigDir();
if (!fs.existsSync(UI_CONFIG_PATH)) {
const fresh = defaultUiConfig();
try {
atomicWrite(fresh);
} catch (err) {
log.warn('failed to write initial ui.json: %s', err instanceof Error ? err.message : String(err));
}
cached = fresh;
return fresh;
}
try {
const raw = fs.readFileSync(UI_CONFIG_PATH, 'utf8');
const parsed = JSON.parse(raw) as unknown;
// On load, the file itself is the source of truth for the server-managed
// image fields — so they survive restarts (don't reset to defaults).
const normalized = normalizeUiConfig(parsed, imageStateFromParsed(parsed));
// Re-persist only if normalization changed something (corrupt/old file),
// so we self-heal on disk without rewriting on every boot.
if (JSON.stringify(parsed) !== JSON.stringify(normalized)) {
try {
atomicWrite(normalized);
} catch {
/* best-effort self-heal */
}
}
cached = normalized;
return normalized;
} catch (err) {
log.warn('ui.json unreadable; using defaults: %s', err instanceof Error ? err.message : String(err));
const fresh = defaultUiConfig();
cached = fresh;
return fresh;
}
}
/**
* Persist a client-supplied config. The incoming appearance is normalized and
* its server-managed background-image fields are forced to the current on-disk
* truth (the client cannot fake `hasImage`). Returns the stored config.
*/
export function saveUiConfig(incoming: unknown): UiConfig {
const current = loadUiConfig();
const v = isObject(incoming) ? incoming : {};
// Section-level merge: a payload may carry just `appearance` (the theme
// editor) or just `layout` (the layout editor) without clobbering the
// other. A missing/non-object section keeps the current on-disk value.
// The current on-disk state is the truth for the server-managed image
// fields — a client payload cannot forge `hasImage` etc.
const next: UiConfig = {
version: UI_CONFIG_VERSION,
appearance: isObject(v.appearance)
? normalizeAppearance(v.appearance, current.appearance.background)
: current.appearance,
layout: isObject(v.layout) ? normalizeLayout(v.layout) : current.layout,
pages: isObject(v.pages) ? normalizePages(v.pages) : (current.pages ?? defaultPages()),
};
atomicWrite(next);
cached = next;
return next;
}
/** The appearance subset served unauthenticated to the login page. Strips
* `customCss` so a broken/hostile rule can never reach the pre-auth page
* (and so the operator can always log in to fix it). */
export function publicAppearance(): UiAppearance {
return { ...loadUiConfig().appearance, customCss: '' };
}
// ─── Background image lifecycle ─────────────────────────────────────────────
const IMAGE_MIME: Record<string, string> = {
png: 'image/png',
jpeg: 'image/jpeg',
webp: 'image/webp',
};
/**
* Identify an image by its magic bytes (never by a client-supplied filename or
* Content-Type). Returns the canonical MIME, or null if it isn't a supported
* image. Supported: PNG, JPEG, WebP.
*/
export function sniffImageMime(bytes: Uint8Array): string | null {
if (bytes.length >= 8 &&
bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 &&
bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) {
return IMAGE_MIME.png;
}
if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
return IMAGE_MIME.jpeg;
}
if (bytes.length >= 12 &&
bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 &&
bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50) {
return IMAGE_MIME.webp;
}
return null;
}
/** Write the uploaded image to disk and record its metadata. Returns the config. */
export function writeBackgroundImage(bytes: Uint8Array, mime: string): UiConfig {
fs.mkdirSync(UI_ASSETS_DIR, { recursive: true });
const tmp = BACKGROUND_IMAGE_PATH + '.tmp';
fs.writeFileSync(tmp, bytes);
fs.renameSync(tmp, BACKGROUND_IMAGE_PATH);
const current = loadUiConfig();
const next: UiConfig = {
...current,
appearance: {
...current.appearance,
background: {
...current.appearance.background,
// Default to showing the freshly-uploaded image unless the operator
// explicitly had a non-image background selected and we respect it;
// switching to 'image' here matches the natural "I just set a wallpaper"
// expectation.
type: 'image',
hasImage: true,
imageMime: mime,
imageVersion: current.appearance.background.imageVersion + 1,
},
},
};
atomicWrite(next);
cached = next;
return next;
}
/** Remove the background image (if any) and clear its metadata. Returns the config. */
export function clearBackgroundImage(): UiConfig {
try {
if (fs.existsSync(BACKGROUND_IMAGE_PATH)) fs.unlinkSync(BACKGROUND_IMAGE_PATH);
} catch (err) {
log.warn('failed to remove background image: %s', err instanceof Error ? err.message : String(err));
}
const current = loadUiConfig();
const next: UiConfig = {
...current,
appearance: {
...current.appearance,
background: {
...current.appearance.background,
// Fall back to 'none' if the image was the active background.
type: current.appearance.background.type === 'image' ? 'none' : current.appearance.background.type,
hasImage: false,
imageMime: '',
},
},
};
atomicWrite(next);
cached = next;
return next;
}
/** Read the background image bytes + MIME, or null if none is stored. */
export function readBackgroundImage(): { bytes: Buffer; mime: string } | null {
const { background } = loadUiConfig().appearance;
if (!background.hasImage) return null;
try {
const bytes = fs.readFileSync(BACKGROUND_IMAGE_PATH);
return { bytes, mime: background.imageMime || 'application/octet-stream' };
} catch {
return null;
}
}

View File

@@ -0,0 +1,164 @@
// Advisory update check against the public GitHub Releases API.
//
// Strictly read-only (T0): SnowLuma never downloads or applies anything
// itself — cross-platform self-update is a minefield (Windows locks loaded
// .node/.dll/node.exe, Docker bakes the app into image layers, bare installs
// have no supervisor). We only tell the WebUI that a newer *stable* release
// exists and link the user to it; they download and apply manually.
//
// The result is cached to stay well under GitHub's 60 req/hr unauthenticated
// rate limit, and every failure degrades silently (the UI just shows
// "无法检查更新" rather than nagging).
import { createLogger } from '@snowluma/common/logger';
import { createSingleFlightCache } from '@snowluma/common/single-flight-cache';
const log = createLogger('Update');
const LATEST_RELEASE_URL = 'https://api.github.com/repos/SnowLuma/SnowLuma/releases/latest';
const CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6h — comfortably under the rate limit
const FETCH_TIMEOUT_MS = 8_000;
const NOTES_MAX = 4_000; // cap the release-body we hand back to the client
export interface UpdateCheckResult {
/** The running build's version (no `v` prefix). */
current: string;
/** Latest stable release version, or null when the check did not complete. */
latest: string | null;
/** True only when `latest` is strictly newer than `current`. */
hasUpdate: boolean;
/** GitHub release page URL for the latest release. */
htmlUrl: string | null;
/** Release notes (markdown), truncated to {@link NOTES_MAX}. */
notes: string | null;
/** ISO timestamp the latest release was published. */
publishedAt: string | null;
/** When this result was produced (epoch ms). */
checkedAt: number;
/** Set when the check was skipped or failed; the UI degrades silently. */
error?: string;
}
interface GithubRelease {
tag_name?: string;
html_url?: string;
body?: string;
published_at?: string;
}
function currentVersion(): string {
return typeof __APP_VERSION__ === 'string' && __APP_VERSION__ ? __APP_VERSION__ : '0.0.0';
}
function isEnabled(): boolean {
const v = (process.env.SNOWLUMA_UPDATE_CHECK ?? '').trim().toLowerCase();
return v !== '0' && v !== 'false' && v !== 'off' && v !== 'no';
}
/**
* Compare two dotted versions. Returns >0 if `a` is newer than `b`, <0 if
* older, 0 if equal. The numeric core (major.minor.patch) compares
* numerically; a prerelease (`-rc.1`) ranks below its release. Good enough
* for "is the latest stable strictly newer than what we run" — and avoids
* pulling in a `semver` runtime dependency (the dist bundle ships none).
*/
export function compareVersions(a: string, b: string): number {
const parse = (v: string) => {
const [core = '', pre = ''] = v.replace(/^v/, '').split('-', 2);
const nums = core.split('.').map((n) => parseInt(n, 10) || 0);
while (nums.length < 3) nums.push(0);
return { nums, pre };
};
const pa = parse(a);
const pb = parse(b);
for (let i = 0; i < 3; i++) {
if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] - pb.nums[i];
}
if (pa.pre === pb.pre) return 0;
if (!pa.pre) return 1; // release > prerelease
if (!pb.pre) return -1;
return pa.pre < pb.pre ? -1 : 1;
}
// TTL + single-flight: cache good results for CACHE_TTL_MS (well under GitHub's
// 60 req/hr limit) and collapse concurrent checks onto one fetch. Error results
// are intentionally not cached (shouldCache) so the next check retries.
const updateCache = createSingleFlightCache<string, UpdateCheckResult>({
ttlMs: CACHE_TTL_MS,
shouldCache: (r) => !r.error,
load: async (current) => {
const result = await fetchLatest(current);
if (result.error) {
log.debug('update check failed: %s', result.error);
} else if (result.hasUpdate) {
log.info('a newer release is available: v%s (running v%s)', result.latest, current);
}
return result;
},
});
async function fetchLatest(current: string): Promise<UpdateCheckResult> {
const base: UpdateCheckResult = {
current,
latest: null,
hasUpdate: false,
htmlUrl: null,
notes: null,
publishedAt: null,
checkedAt: Date.now(),
};
try {
// `/releases/latest` already excludes drafts and prereleases, so this is
// stable-channel by construction.
const res = await fetch(LATEST_RELEASE_URL, {
headers: {
Accept: 'application/vnd.github+json',
'User-Agent': `SnowLuma/${current}`,
'X-GitHub-Api-Version': '2022-11-28',
},
signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
});
if (!res.ok) return { ...base, error: `github ${res.status}` };
const rel = (await res.json()) as GithubRelease;
const tag = (rel.tag_name ?? '').trim();
if (!tag) return { ...base, error: 'no tag' };
const latest = tag.replace(/^v/, '');
return {
current,
latest,
hasUpdate: compareVersions(latest, current) > 0,
htmlUrl: rel.html_url ?? null,
notes: rel.body ? rel.body.slice(0, NOTES_MAX) : null,
publishedAt: rel.published_at ?? null,
checkedAt: Date.now(),
};
} catch (e) {
return { ...base, error: e instanceof Error ? e.message : 'network error' };
}
}
/**
* Get the update-availability result. Cached for {@link CACHE_TTL_MS}; pass
* `force` to bypass the cache (the WebUI's "立即检查" button). Never throws —
* failures come back as a result with `error` set and `hasUpdate: false`, and
* are not cached so the next check retries.
*/
export async function getUpdateInfo(force = false): Promise<UpdateCheckResult> {
const current = currentVersion();
if (!isEnabled()) {
return { ...emptyResult(current), error: 'disabled' };
}
return updateCache.get(current, { force });
}
function emptyResult(current: string): UpdateCheckResult {
return {
current,
latest: null,
hasUpdate: false,
htmlUrl: null,
notes: null,
publishedAt: null,
checkedAt: Date.now(),
};
}

View File

@@ -65,6 +65,7 @@ export interface MockGroupFileApi {
upload: ReturnType<typeof vi.fn>;
uploadPrivate: ReturnType<typeof vi.fn>;
publish: ReturnType<typeof vi.fn>;
trans: ReturnType<typeof vi.fn>;
getCount: ReturnType<typeof vi.fn>;
list: ReturnType<typeof vi.fn>;
getUrl: ReturnType<typeof vi.fn>;
@@ -85,6 +86,7 @@ export function mockGroupFileApi(): MockGroupFileApi {
upload: vi.fn(async () => ({ fileId: 'stub-fid' })),
uploadPrivate: vi.fn(async () => ({ fileId: 'stub-pfid', fileHash: 'stub-hash' })),
publish: vi.fn(async () => undefined),
trans: vi.fn(async () => ({ saveBusId: 102, saveFilePath: '/stub-path' })),
getCount: vi.fn(async () => ({ fileCount: 0, maxCount: 10000 })),
list: vi.fn(async () => ({ files: [], folders: [] })),
getUrl: vi.fn(async () => 'stub://url'),
@@ -124,7 +126,9 @@ export interface MockBridge {
findUidByUin: ReturnType<typeof vi.fn>;
findUinByUid: ReturnType<typeof vi.fn>;
findGroupMember: ReturnType<typeof vi.fn>;
forgetGroup: ReturnType<typeof vi.fn>;
};
events: { emit: ReturnType<typeof vi.fn> };
apis: MockApiHub;
sendRawPacket: ReturnType<typeof vi.fn>;
fetchFriendList: ReturnType<typeof vi.fn>;
@@ -154,8 +158,10 @@ export function mockBridge(overrides: Partial<MockBridge> = {}): MockBridge {
findUidByUin: vi.fn(() => 'cached-uid'),
findUinByUid: vi.fn(() => 0),
findGroupMember: vi.fn(() => null),
forgetGroup: vi.fn(),
...(overrides.identity ?? {}),
} as MockBridge['identity'],
events: overrides.events ?? { emit: vi.fn(async () => undefined) },
apis: overrides.apis ?? mockApiHub(),
sendRawPacket: vi.fn(async () => defaultResp),
fetchFriendList: vi.fn(async () => []),

View File

@@ -24,6 +24,7 @@
// split.
import { describe, it, expect, vi } from 'vitest';
import { gunzipSync } from 'zlib';
vi.mock('@snowluma/protocol/bridge-oidb', () => ({
runOidb: vi.fn(async () => new Uint8Array()),
@@ -44,8 +45,9 @@ vi.mock('@snowluma/protocol/element-builder', () => ({
buildSendElems: buildSendElemsMock,
}));
import { protobuf_encode } from '@snowluma/proton';
import type { SendLongMsgResp } from '@snowluma/proto-defs/longmsg';
import { protobuf_decode, protobuf_encode } from '@snowluma/proton';
import type { LongMsgResult, SendLongMsgReq, SendLongMsgResp } from '@snowluma/proto-defs/longmsg';
import type { FileExtra } from '@snowluma/proto-defs/message';
import { ForwardApi } from '../../src/bridge/apis/forward';
import { mockBridge } from './_helpers';
@@ -60,6 +62,13 @@ function uploadResponseWithResId(resId: string) {
};
}
function decodeLongMsgRequest(rawBytes: Uint8Array): LongMsgResult {
const env = protobuf_decode<SendLongMsgReq>(rawBytes);
const payload = env.info?.payload;
if (!(payload instanceof Uint8Array)) throw new Error('payload missing on SendLongMsgReq');
return protobuf_decode<LongMsgResult>(gunzipSync(Buffer.from(payload)));
}
describe('actions/forward — file segment inside forward node', () => {
it('group forward sets forwardFake:true on the SendContext so transElem(24) is emitted', async () => {
// Group case: the file element rides on elems[] as transElem(24).
@@ -120,18 +129,19 @@ describe('actions/forward — file segment inside forward node', () => {
expect(ctx).toMatchObject({ forwardFake: true });
expect(ctx?.groupId).toBeUndefined();
// Spot-check that the upload body carries the file metadata. The
// payload is gzipped + protobuf-wrapped, so we just verify the
// raw filename string survived — that's enough to confirm the
// FileExtra branch ran (a "missing file" regression would drop
// these bytes entirely).
expect(captured).toBeDefined();
const flat = Buffer.from(captured!).toString('binary');
// The filename gets gzipped, so we can't substring-search; instead
// assert the body is large enough that the FileExtra wasn't elided.
// (A name-only forward with no msgContent runs ~80-100 bytes; with
// the FileExtra blob it's noticeably larger.)
expect(flat.length).toBeGreaterThan(80);
const longMsg = decodeLongMsgRequest(captured!);
const body = longMsg.action?.[0]?.actionData?.msgBody?.[0]?.body;
expect(body?.msgContent).toBeInstanceOf(Uint8Array);
expect(body?.richText?.notOnlineFile ?? undefined).toBeUndefined();
const fileExtra = protobuf_decode<FileExtra>(body!.msgContent as Uint8Array);
expect(fileExtra.file).toMatchObject({
fileUuid: 'pfid-1',
fileName: 'invoice.pdf',
fileHash: 'srv-hash-abc',
});
expect(fileExtra.file?.fileSize).toBe(4096n);
});
it('c2c forward falls back to the upload metadata cache when inline fields are missing', async () => {
@@ -165,4 +175,190 @@ describe('actions/forward — file segment inside forward node', () => {
expect(recallUploadedFile).toHaveBeenCalledWith('pfid-cached');
});
it('group forward pre-uploads file sources into the target group without publishing a separate file message', async () => {
buildSendElemsMock.mockClear();
const upload = vi.fn(async () => ({ fileId: 'gfid-from-base64' }));
const publish = vi.fn();
const bridge = mockBridge({
sendRawPacket: vi.fn(async () => uploadResponseWithResId('res-grp-source')) as any,
apis: {
...mockBridge().apis,
groupFile: {
...mockBridge().apis.groupFile,
upload,
publish,
},
},
recallUploadedFile: vi.fn((id: string) => id === 'gfid-from-base64' ? {
fileId: 'gfid-from-base64',
scope: 'group' as const,
groupId: 12345,
fileName: 'note.txt',
fileSize: 3,
fileMd5: new Uint8Array(16),
fileSha1: new Uint8Array(20),
rememberedAt: 0,
} : undefined),
});
await new ForwardApi(bridge as any).upload([{
userUin: 10001,
nickname: 'alice',
elements: [{ type: 'file', url: 'base64://AQID', fileName: 'note.txt' } as any],
}], 12345);
expect(upload).toHaveBeenCalledWith(12345, 'base64://AQID', 'note.txt', '/', true, false);
expect(publish).not.toHaveBeenCalled();
const [elements] = buildSendElemsMock.mock.calls[0]!;
expect(elements).toEqual([expect.objectContaining({
type: 'file',
fileId: 'gfid-from-base64',
fileName: 'note.txt',
fileSize: 3,
})]);
});
it('private forward pre-uploads file sources without sending a standalone c2c file message', async () => {
buildSendElemsMock.mockClear();
const uploadPrivate = vi.fn(async () => ({ fileId: 'pfid-from-base64', fileHash: 'phash' }));
const sendC2cFile = vi.fn();
const bridge = mockBridge({
sendRawPacket: vi.fn(async () => uploadResponseWithResId('res-c2c-source')) as any,
apis: {
...mockBridge().apis,
message: {
...mockBridge().apis.message,
sendC2cFile,
},
groupFile: {
...mockBridge().apis.groupFile,
uploadPrivate,
},
},
recallUploadedFile: vi.fn((id: string) => id === 'pfid-from-base64' ? {
fileId: 'pfid-from-base64',
scope: 'private' as const,
userId: 67890,
fileName: 'note.txt',
fileSize: 3,
fileMd5: new Uint8Array(16),
fileSha1: new Uint8Array(20),
fileHash: 'phash',
rememberedAt: 0,
} : undefined),
});
await new ForwardApi(bridge as any).upload([{
userUin: 10001,
nickname: 'alice',
elements: [{ type: 'file', url: 'base64://AQID', fileName: 'note.txt' } as any],
}], undefined, 67890);
expect(uploadPrivate).toHaveBeenCalledWith(67890, 'base64://AQID', 'note.txt', true, false);
expect(sendC2cFile).not.toHaveBeenCalled();
const [elements] = buildSendElemsMock.mock.calls[0]!;
expect(elements).toEqual([expect.objectContaining({
type: 'file',
fileId: 'pfid-from-base64',
fileName: 'note.txt',
fileSize: 3,
fileHash: 'phash',
})]);
});
it('private file forward keeps the long-msg upload under the self uid namespace', async () => {
buildSendElemsMock.mockClear();
let captured: Uint8Array | undefined;
const bridge = mockBridge({
sendRawPacket: vi.fn(async (_cmd: string, body: Uint8Array) => {
captured = body;
return uploadResponseWithResId('res-c2c-target-uid');
}) as any,
resolveUserUid: vi.fn(async () => 'target-uid'),
recallUploadedFile: vi.fn((id: string) => id === 'pfid-1' ? {
fileId: 'pfid-1',
scope: 'private' as const,
userId: 67890,
fileName: 'invoice.pdf',
fileSize: 4096,
fileMd5: new Uint8Array(16),
fileSha1: new Uint8Array(20),
fileHash: 'srv-hash',
rememberedAt: 0,
} : undefined),
});
await new ForwardApi(bridge as any).upload([{
userUin: 10001,
nickname: 'alice',
elements: [{ type: 'file', fileId: 'pfid-1' } as any],
}], undefined, 67890);
expect(bridge.resolveUserUid).not.toHaveBeenCalled();
expect(captured).toBeDefined();
const request = protobuf_decode<SendLongMsgReq>(captured!);
expect(request.info?.uid?.uid).toBe('self-uid');
});
it('group forward re-uploads a cached private file_id into the target group scope', async () => {
buildSendElemsMock.mockClear();
const getPrivateUrl = vi.fn(async () => 'https://download.test/private-file');
const upload = vi.fn(async () => ({ fileId: 'gfid-reuploaded' }));
const bridge = mockBridge({
sendRawPacket: vi.fn(async () => uploadResponseWithResId('res-cross-scope')) as any,
apis: {
...mockBridge().apis,
groupFile: {
...mockBridge().apis.groupFile,
getPrivateUrl,
upload,
},
},
recallUploadedFile: vi.fn((id: string) => {
if (id === 'pfid-cached') {
return {
fileId: 'pfid-cached',
scope: 'private' as const,
userId: 67890,
fileName: 'cached.txt',
fileSize: 5,
fileMd5: new Uint8Array(16),
fileSha1: new Uint8Array(20),
fileHash: 'cached-hash',
rememberedAt: 0,
};
}
if (id === 'gfid-reuploaded') {
return {
fileId: 'gfid-reuploaded',
scope: 'group' as const,
groupId: 12345,
fileName: 'cached.txt',
fileSize: 5,
fileMd5: new Uint8Array(16),
fileSha1: new Uint8Array(20),
rememberedAt: 1,
};
}
return undefined;
}),
});
await new ForwardApi(bridge as any).upload([{
userUin: 10001,
nickname: 'alice',
elements: [{ type: 'file', fileId: 'pfid-cached' } as any],
}], 12345);
expect(getPrivateUrl).toHaveBeenCalledWith(67890, 'pfid-cached', 'cached-hash');
expect(upload).toHaveBeenCalledWith(12345, 'https://download.test/private-file', 'cached.txt', '/', true, false);
const [elements] = buildSendElemsMock.mock.calls[0]!;
expect(elements).toEqual([expect.objectContaining({
type: 'file',
fileId: 'gfid-reuploaded',
fileName: 'cached.txt',
fileSize: 5,
})]);
});
});

View File

@@ -151,3 +151,71 @@ describe('actions/forward', () => {
expect(sendRawPacket).toHaveBeenCalledOnce();
});
});
describe('actions/forward — sender name enrichment (#174)', () => {
function apiWith(contacts: { fetchGroupMemberList: any; fetchUserProfile: any }) {
return new ForwardApi({ apis: { contacts } } as any);
}
it('fills empty / "QQ用户" names via the group member list (L3), card preferred', async () => {
const fetchGroupMemberList = vi.fn(async () => [
{ uin: 10001, nickname: 'AliceNick', card: 'AliceCard' },
{ uin: 10002, nickname: 'BobNick', card: '' },
]);
const fetchUserProfile = vi.fn(async (uin: number) => ({ uin, nickname: 'Stranger' }));
const api = apiWith({ fetchGroupMemberList, fetchUserProfile });
const nodes: any[] = [
{ userUin: 10001, nickname: '', groupId: 700, messageType: 'group', elements: [] },
{ userUin: 10002, nickname: 'QQ用户', groupId: 700, messageType: 'group', elements: [] },
{ userUin: 10003, nickname: '', groupId: 700, messageType: 'group', elements: [] }, // not in list
{ userUin: 10009, nickname: '', messageType: 'private', elements: [] }, // private
{ userUin: 10005, nickname: 'KeepMe', groupId: 700, messageType: 'group', elements: [] },
];
const changed = await (api as any).enrichSenders(nodes);
expect(changed).toBe(true);
expect(nodes[0].nickname).toBe('AliceCard'); // card preferred over nick
expect(nodes[0].senderCard).toBe('AliceCard');
expect(nodes[1].nickname).toBe('BobNick'); // card empty → nickname
expect(nodes[2].nickname).toBe('Stranger'); // not in member list → L4 profile
expect(nodes[3].nickname).toBe('Stranger'); // private node → L4 profile
expect(nodes[4].nickname).toBe('KeepMe'); // already named → untouched
expect(fetchGroupMemberList).toHaveBeenCalledTimes(1); // one fetch covers the whole group
});
it('is a no-op (no fetch) when every node already has a name', async () => {
const fetchGroupMemberList = vi.fn();
const fetchUserProfile = vi.fn();
const api = apiWith({ fetchGroupMemberList, fetchUserProfile });
const nodes: any[] = [{ userUin: 1, nickname: 'has-name', groupId: 7, messageType: 'group', elements: [] }];
expect(await (api as any).enrichSenders(nodes)).toBe(false);
expect(fetchGroupMemberList).not.toHaveBeenCalled();
});
it('keeps the placeholder and never throws when resolution fails', async () => {
const api = apiWith({
fetchGroupMemberList: vi.fn(async () => { throw new Error('net down'); }),
fetchUserProfile: vi.fn(async () => { throw new Error('net down'); }),
});
const nodes: any[] = [{ userUin: 10001, nickname: 'QQ用户', groupId: 700, messageType: 'group', elements: [] }];
await expect((api as any).enrichSenders(nodes)).resolves.toBe(false);
expect(nodes[0].nickname).toBe('QQ用户');
});
it('does NOT fan a member-list failure out to per-uin profile lookups (rate-limit guard)', async () => {
const fetchUserProfile = vi.fn(async (uin: number) => ({ uin, nickname: 'X' }));
const api = apiWith({
fetchGroupMemberList: vi.fn(async () => { throw new Error('net'); }),
fetchUserProfile,
});
// 5 distinct group senders whose member list errors → must keep placeholder,
// NOT trigger 5 profile calls.
const nodes: any[] = Array.from({ length: 5 }, (_, i) => ({
userUin: 20000 + i, nickname: '', groupId: 700, messageType: 'group', elements: [],
}));
expect(await (api as any).enrichSenders(nodes)).toBe(false);
expect(fetchUserProfile).not.toHaveBeenCalled();
expect(nodes.every((n) => n.nickname === '')).toBe(true);
});
});

View File

@@ -88,13 +88,24 @@ describe('apis/group-admin', () => {
expect(env.body?.rejectAddRequest ?? 0).toBe(0);
});
it('leave sends 0x1097_1 with the groupUin', async () => {
it('leave sends 0x1097_1, emits a self group_member_leave, and forgets the group (#133)', async () => {
const bridge = mockBridge();
await new GroupAdminApi(bridge as any).leave(12345);
const [cmd, bytes] = bridge.sendRawPacket.mock.calls[0]!;
expect(cmd).toBe('OidbSvcTrpcTcp.0x1097_1');
const env = protobuf_decode<OidbBase<OidbLeaveGroup>>(bytes);
expect(env.body).toMatchObject({ groupUin: 12345 });
// The server never pushes a member-decrease for our own voluntary leave, so
// the bridge synthesizes it (self user_id/operator_id) and drops the group.
expect(bridge.events.emit).toHaveBeenCalledWith(expect.objectContaining({
kind: 'group_member_leave',
groupId: 12345,
userUin: 10001,
operatorUin: 10001,
leaveType: 'leave',
}));
expect(bridge.identity.forgetGroup).toHaveBeenCalledWith(12345);
});
it('setAdmin resolves UID and sends 0x1096_1', async () => {

View File

@@ -8,6 +8,7 @@ import type {
OidbGroupFileViewResp,
OidbGroupFileFolderResp,
OidbGroupSendFileReq,
OidbGroupSendFileResp,
} from '@snowluma/proto-defs/oidb-actions/group-file';
import type {
OidbPrivateFileUploadResp,
@@ -170,6 +171,28 @@ describe('apis/group-file', () => {
expect(publishSpy).not.toHaveBeenCalled();
});
it('upload can PUT bytes without publishing a separate group file message', async () => {
const bridge = mockBridge();
bridge.sendRawPacket.mockResolvedValueOnce(packResponse(
protobuf_encode<OidbBase<OidbGroupFileResp>>({
body: {
upload: {
fileId: 'fid-forward',
uploadIp: '127.0.0.1',
uploadPort: 443,
fileKey: new Uint8Array([1]),
checkKey: new Uint8Array([2]),
} as any,
},
}),
));
const api = new GroupFileApi(bridge as any);
const publishSpy = vi.spyOn(api, 'publish').mockResolvedValue();
await api.upload(12345, 'base64://AQID', 'forward.txt', '/', true, false);
expect(highwayClient.uploadHighwayHttp).toHaveBeenCalledOnce();
expect(publishSpy).not.toHaveBeenCalled();
});
it('upload returns success even when the chat post fails (file is still uploaded)', async () => {
const bridge = mockBridge();
bridge.sendRawPacket.mockResolvedValueOnce(packResponse(
@@ -224,6 +247,26 @@ describe('apis/group-file', () => {
});
});
it('trans hits OIDB 0x6d9_0 and returns the saved path metadata', async () => {
const bridge = mockBridge();
bridge.sendRawPacket.mockResolvedValueOnce(packResponse(
protobuf_encode<OidbBase<OidbGroupSendFileResp>>({
body: { transFile: { saveBusId: 102, saveFilePath: '/saved/path' } },
}),
));
const out = await new GroupFileApi(bridge as any).trans(12345, 'fid-trans');
expect(out).toEqual({ saveBusId: 102, saveFilePath: '/saved/path' });
const [wire, bytes] = bridge.sendRawPacket.mock.calls[0]!;
expect(wire).toBe('OidbSvcTrpcTcp.0x6d9_0');
const env = protobuf_decode<OidbBase<OidbGroupSendFileReq>>(bytes);
expect(env.body?.transFile).toMatchObject({
groupUin: 12345n,
appId: 7,
busId: 102,
fileId: 'fid-trans',
});
});
it('uploadPrivate resolves both target + self UID before OIDB call', async () => {
const bridge = mockBridge({
identity: {
@@ -233,6 +276,7 @@ describe('apis/group-file', () => {
findUidByUin: vi.fn(() => 'cached-uid'),
findUinByUid: vi.fn(() => 0),
findGroupMember: vi.fn(() => null),
forgetGroup: vi.fn(),
},
});
vi.mocked(bridge.resolveUserUid)
@@ -297,6 +341,28 @@ describe('apis/group-file', () => {
expect(bridge.apis.message.sendC2cFile).not.toHaveBeenCalled();
});
it('uploadPrivate can PUT bytes without publishing a separate c2c file message', async () => {
const bridge = mockBridge();
vi.mocked(bridge.resolveUserUid).mockResolvedValueOnce('target-uid');
bridge.sendRawPacket.mockResolvedValueOnce(packResponse(
protobuf_encode<OidbBase<OidbPrivateFileUploadResp>>({
body: {
upload: {
uuid: 'pfid-forward',
fileAddon: 'phash-forward',
rtpMediaPlatformUploadAddress: [
{ outIP: 0, outPort: 0, inIP: 16885952, inPort: 8080, iPType: 1 },
],
mediaPlatformUploadKey: new Uint8Array([1, 2, 3]),
} as any,
},
}),
));
await new GroupFileApi(bridge as any).uploadPrivate(67890, 'base64://AQID', 'forward.txt', true, false);
expect(highwayClient.uploadHighwayHttp).toHaveBeenCalledOnce();
expect(bridge.apis.message.sendC2cFile).not.toHaveBeenCalled();
});
it('uploadPrivate reads host from rtpMediaPlatformUploadAddress[0].inIP when populated', async () => {
const bridge = mockBridge();
vi.mocked(bridge.resolveUserUid).mockResolvedValueOnce('target-uid');

View File

@@ -0,0 +1,174 @@
import { describe, it, expect, vi, afterEach } from 'vitest';
import * as qzoneWeb from '@snowluma/protocol/web/qzone';
import { QzoneApi } from '../../src/bridge/apis/qzone';
import { mockApiHub, mockBridge } from './_helpers';
// QzoneApi is the only place the string(identity.uin)/number(action param)
// boundary is crossed, so its target_uin defaulting + the `> 0` guard are
// worth locking. We stub the protocol-layer getQzoneMsgList and the web
// cookie fetch so the test asserts purely what the bridge passes down.
describe('apis/qzone', () => {
afterEach(() => vi.restoreAllMocks());
function bridgeWithWeb() {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const fetchSpy = vi
.spyOn(qzoneWeb, 'getQzoneMsgList')
.mockResolvedValue({ total: 0, msglist: [] });
return { bridge, getCookies, fetchSpy };
}
it('defaults target_uin to the bot\'s own uin and uses default pos/num', async () => {
const { bridge, getCookies, fetchSpy } = bridgeWithWeb();
await new QzoneApi(bridge as never).getMsgList();
expect(getCookies).toHaveBeenCalledWith('qzone.qq.com');
// identity.uin is '10001' (a string) — passed straight through.
expect(fetchSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', 0, 20);
});
it('treats target_uin 0 as absent and falls back to own uin', async () => {
const { bridge, fetchSpy } = bridgeWithWeb();
await new QzoneApi(bridge as never).getMsgList(0);
expect(fetchSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', 0, 20);
});
it('passes a real target_uin (stringified) plus pos/num through', async () => {
const { bridge, fetchSpy } = bridgeWithWeb();
await new QzoneApi(bridge as never).getMsgList(20002, 5, 50);
expect(fetchSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '20002', 5, 50);
});
it('getFeeds always uses the bot\'s own uin and threads pageNum/count', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const feedsSpy = vi.spyOn(qzoneWeb, 'getQzoneFeeds').mockResolvedValue({ feeds: [], has_more: false });
await new QzoneApi(bridge as never).getFeeds(3, 20);
expect(getCookies).toHaveBeenCalledWith('qzone.qq.com');
expect(feedsSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', 3, 20);
});
it('uploadImageFromSource uploads from file:// http:// base64:// and returns richval + url', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK', skey: 'SK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const uploadSpy = vi.spyOn(qzoneWeb, 'uploadQzoneImageFromSource').mockResolvedValue({
richval: ',12345,abc,abc,22,800,600,,800,600',
url: 'https://example.com/img.jpg',
albumid: '12345',
lloc: 'abc',
type: 22,
width: 600,
height: 800,
});
const out = await new QzoneApi(bridge as never).uploadImageFromSource('file:///path/to/image.jpg');
expect(getCookies).toHaveBeenCalledWith('qzone.qq.com');
expect(uploadSpy).toHaveBeenCalledWith({ p_skey: 'PSK', skey: 'SK' }, '10001', 'file:///path/to/image.jpg');
expect(out.richval).toBe(',12345,abc,abc,22,800,600,,800,600');
expect(out.url).toBe('https://example.com/img.jpg');
});
it('publish posts to the bot\'s own space with the given content (text-only)', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const pubSpy = vi.spyOn(qzoneWeb, 'publishQzoneMsg').mockResolvedValue({ tid: 'T', time: 1 });
const out = await new QzoneApi(bridge as never).publish('hello');
expect(getCookies).toHaveBeenCalledWith('qzone.qq.com');
expect(pubSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', 'hello', undefined, undefined, 1, undefined);
expect(out).toEqual({ tid: 'T', time: 1 });
});
it('publish posts with richtype and richval for image post', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const pubSpy = vi.spyOn(qzoneWeb, 'publishQzoneMsg').mockResolvedValue({ tid: 'T2', time: 2 });
const richval = ',12345,abc,abc,22,800,600,,800,600';
const out = await new QzoneApi(bridge as never).publish('look at this', 1, richval);
expect(getCookies).toHaveBeenCalledWith('qzone.qq.com');
expect(pubSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', 'look at this', 1, richval, 1, undefined);
expect(out).toEqual({ tid: 'T2', time: 2 });
});
it('publish posts with multiple images (richval joined with tab)', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const pubSpy = vi.spyOn(qzoneWeb, 'publishQzoneMsg').mockResolvedValue({ tid: 'T3', time: 3 });
const richval = ',12345,a,a,22,800,600,,800,600\t,12346,b,b,22,1024,768,,1024,768';
const out = await new QzoneApi(bridge as never).publish('two images', 1, richval);
expect(getCookies).toHaveBeenCalledWith('qzone.qq.com');
expect(pubSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', 'two images', 1, richval, 1, undefined);
expect(out).toEqual({ tid: 'T3', time: 3 });
});
it('publish threads qzone visibility params', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const pubSpy = vi.spyOn(qzoneWeb, 'publishQzoneMsg').mockResolvedValue({ tid: 'T', time: 1 });
await new QzoneApi(bridge as never).publish('hello', undefined, undefined, 16, '10002|10003');
expect(pubSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', 'hello', undefined, undefined, 16, '10002|10003');
});
it('delete removes a feed by tid from the bot\'s own space', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const delSpy = vi.spyOn(qzoneWeb, 'deleteQzoneMsg').mockResolvedValue();
await new QzoneApi(bridge as never).delete('TID9');
expect(getCookies).toHaveBeenCalledWith('qzone.qq.com');
expect(delSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', 'TID9');
});
it('updateRight changes a feed\'s visibility on the bot\'s own space', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const updSpy = vi.spyOn(qzoneWeb, 'updateQzoneMsgRight').mockResolvedValue({ ugc_right: 16 });
const out = await new QzoneApi(bridge as never).updateRight('TID9', 16, '10002|10003');
expect(getCookies).toHaveBeenCalledWith('qzone.qq.com');
expect(updSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', 'TID9', 16, '10002|10003');
expect(out).toEqual({ ugc_right: 16 });
});
it('like defaults the feed owner to self and passes opUin=self + like flag', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const likeSpy = vi.spyOn(qzoneWeb, 'setQzoneLike').mockResolvedValue();
await new QzoneApi(bridge as never).like('TIDX', undefined, true, 1700000000);
// opUin = self ('10001'), owner defaults to self when target_uin absent; abstime threaded
expect(likeSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', '10001', 'TIDX', true, 1700000000);
});
it('like targets a friend\'s space (owner = target_uin) and threads the unlike flag + abstime default', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const likeSpy = vi.spyOn(qzoneWeb, 'setQzoneLike').mockResolvedValue();
await new QzoneApi(bridge as never).like('TIDX', 20002, false);
// abstime defaults to 0 when omitted
expect(likeSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', '20002', 'TIDX', false, 0);
});
it('comment defaults the feed owner to self and posts as self', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const cmtSpy = vi.spyOn(qzoneWeb, 'commentQzoneMsg').mockResolvedValue({ comment_id: '1' });
const out = await new QzoneApi(bridge as never).comment('TIDX', 'nice', undefined);
// selfUin='10001' commenter; owner defaults to self
expect(cmtSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', '10001', 'TIDX', 'nice', undefined, undefined);
expect(out).toEqual({ comment_id: '1' });
});
it('comment targets a friend\'s feed (owner = target_uin), commenter stays self', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const cmtSpy = vi.spyOn(qzoneWeb, 'commentQzoneMsg').mockResolvedValue({ comment_id: '2' });
await new QzoneApi(bridge as never).comment('TIDX', 'nice', 20002);
expect(cmtSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', '20002', 'TIDX', 'nice', undefined, undefined);
});
it('comment with images (richType=1, richval=direct URLs joined with tab)', async () => {
const getCookies = vi.fn(async () => ({ p_skey: 'PSK' }));
const bridge = mockBridge({ apis: { ...mockApiHub(), web: { getCookies } } as never });
const cmtSpy = vi.spyOn(qzoneWeb, 'commentQzoneMsg').mockResolvedValue({ comment_id: '3' });
const richval = 'https://example.com/a.jpg\thttps://example.com/b.jpg';
await new QzoneApi(bridge as never).comment('TIDX', 'nice pic', undefined, 1, richval);
expect(cmtSpy).toHaveBeenCalledWith({ p_skey: 'PSK' }, '10001', '10001', 'TIDX', 'nice pic', 1, richval);
});
});

View File

@@ -3,15 +3,22 @@ import { protobuf_decode, protobuf_encode } from '@snowluma/proton';
import type { SendPacketResult } from '@snowluma/common/packet-sender';
import type { SendMessageRequest, SendMessageResponse } from '@snowluma/proto-defs/action';
import type { FileExtra } from '@snowluma/proto-defs/message';
import type { OidbBase } from '@snowluma/proto-defs/oidb';
import type { OidbOfflineFileFinalizeResp } from '@snowluma/proto-defs/oidb-actions/media';
vi.mock('@snowluma/protocol/element-builder', () => ({
buildSendElems: vi.fn(async () => [{ text: { str: 'stub media elem' } }]),
}));
// Imported statically (not via `await import` inside each `it`) so the heavy
// Bridge dependency-tree load happens once at file collection — not against a
// single test's 5s timeout, which tipped over on slower CI runners. vi.mock is
// hoisted above these by vitest, so element-builder is still mocked.
import { Bridge } from '../src/bridge/bridge';
import { IdentityService } from '@snowluma/protocol/identity-service';
describe('Bridge private media routing', () => {
it('includes resolved uid in the final c2c send request for media messages', async () => {
const { Bridge } = await import('../src/bridge/bridge');
const { IdentityService } = await import('@snowluma/protocol/identity-service');
class TestBridge extends Bridge {
capturedBody: Uint8Array | null = null;
@@ -59,12 +66,26 @@ describe('Bridge private media routing', () => {
// BuildPacketBase` + `FileEntity.PackMessageContent`. Previous
// implementation wrote c2c routing + richText.notOnlineFile +
// c2cCmd=11 — the QQ-NT server rejected every c2c file send.
const { Bridge } = await import('../src/bridge/bridge');
const { IdentityService } = await import('@snowluma/protocol/identity-service');
class TestBridge extends Bridge {
capturedBody: Uint8Array | null = null;
override async sendRawPacket(_cmd: string, body: Uint8Array): Promise<SendPacketResult> {
finalizeCmd: string | null = null;
override async resolveUserUid(uin: number): Promise<string> {
return uin === 10000 ? 'u_self' : `u_${uin}`;
}
override async sendRawPacket(cmd: string, body: Uint8Array): Promise<SendPacketResult> {
// The c2c file send first runs the 0xE37_800 finalize, then PbSendMsg.
if (cmd.includes('0xe37_800')) {
this.finalizeCmd = cmd;
return {
success: true, gotResponse: true, errorCode: 0, errorMessage: '',
responseData: Buffer.from(protobuf_encode<OidbBase<OidbOfflineFileFinalizeResp>>({
body: { body: { metadata: { field3: 11, field100: new Uint8Array([1]), field101: new Uint8Array([2]), field110: 22, timestamp1: 1710000123 } } },
})),
};
}
this.capturedBody = body;
return {
success: true, gotResponse: true, errorCode: 0, errorMessage: '',
@@ -118,9 +139,66 @@ describe('Bridge private media routing', () => {
// expireTime is now+7d; just sanity-check it landed (non-zero, plausible)
expect(fileExtra?.file?.expireTime).toBeGreaterThan(Math.floor(Date.now() / 1000));
// issue #157: when the 0xE37_800 finalize succeeds, its download routing
// rides along in field6 (best-effort enrichment on top of the always-
// present NotOnlineFile).
expect(bridge.finalizeCmd).toBe('OidbSvcTrpcTcp.0xe37_800');
expect(fileExtra?.field6?.field2).toMatchObject({
fileUuid: 'uuid-abc-123',
fileName: 'doc.txt',
fileHash: 'hash-xyz',
selfUid: 'u_self',
destUid: 'u_peer_xyz',
field1: 22, // ← finalize metadata.field110
field6: 11, // ← finalize metadata.field3
timestamp1: 1710000123,
});
expect(fileExtra?.field6?.field2?.field7).toEqual(new Uint8Array([2])); // ← metadata.field101
expect(fileExtra?.field6?.field2?.field8).toEqual(new Uint8Array([1])); // ← metadata.field100
// c2cCmd is left at 0 / undefined — the old `c2cCmd=11` was a
// stale go-cqhttp value the QQ-NT server doesn't recognise on the
// c2c-file path.
expect(request?.contentHead?.c2cCmd ?? 0).toBe(0);
});
it('c2c file send survives a failing 0xE37_800 finalize — sends without field6 (#157 best-effort)', async () => {
class TestBridge extends Bridge {
capturedBody: Uint8Array | null = null;
override async resolveUserUid(uin: number): Promise<string> {
return uin === 10000 ? 'u_self' : `u_${uin}`;
}
override async sendRawPacket(cmd: string, body: Uint8Array): Promise<SendPacketResult> {
// Finalize fails (server error → OidbError). The send must NOT fail
// because of it.
if (cmd.includes('0xe37_800')) {
return { success: false, gotResponse: true, errorCode: 9999, errorMessage: 'finalize boom', responseData: Buffer.alloc(0) };
}
this.capturedBody = body;
return {
success: true, gotResponse: true, errorCode: 0, errorMessage: '',
responseData: Buffer.from(protobuf_encode<SendMessageResponse>({
result: 0, errMsg: '', privateSequence: 88, timestamp1: 1710000000,
})),
};
}
}
const bridge = new TestBridge(IdentityService.memory('10000'));
// Should resolve (not throw) despite the finalize error.
await bridge.apis.message.sendC2cFile(67890, 'u_peer_xyz', {
fileId: 'uuid-abc-123', fileName: 'doc.txt', fileSize: 1024,
fileMd5: new Uint8Array([1, 2, 3, 4]), fileHash: 'hash-xyz',
});
// PbSendMsg still went out, carrying the file but NO field6.
expect(bridge.capturedBody).toBeInstanceOf(Uint8Array);
const request = protobuf_decode<SendMessageRequest>(bridge.capturedBody as Uint8Array);
const fileExtra = protobuf_decode<FileExtra>(request!.messageBody!.msgContent as Uint8Array);
expect(fileExtra?.file?.fileUuid).toBe('uuid-abc-123');
expect(fileExtra?.field6 ?? undefined).toBeUndefined();
});
});

View File

@@ -35,6 +35,43 @@ function commonElem(elem: any): { serviceType: number; businessType: number; pbE
return elem.commonElem;
}
function inflatePrefixedPayload(data: Uint8Array): string {
expect(data[0]).toBe(0x01);
return inflateSync(Buffer.from(data.subarray(1))).toString('utf8');
}
describe('element-builder / rich card encoding', () => {
it('encodes json segments as deflated LightApp payloads and preserves non-ASCII text', async () => {
const card = JSON.stringify({
app: 'com.tencent.structmsg',
view: 'music',
prompt: '[音乐]起风了',
meta: { music: { title: '起风了', desc: '买辣椒也用券' } },
});
const [elem] = await buildSendElems(
[{ type: 'json', text: card } as any],
{ bridge: fakeBridge, groupId: 12345 },
);
expect(elem.lightApp).toBeDefined();
expect((elem as any).richMsg).toBeUndefined();
expect(inflatePrefixedPayload(elem.lightApp!.data!)).toBe(card);
});
it('encodes xml richMsg payloads by UTF-8 bytes, not JavaScript string length', async () => {
const xml = '<msg serviceID="35" brief="[分享]中文卡片"></msg>';
const [elem] = await buildSendElems(
[{ type: 'xml', text: xml, subType: 35 } as any],
{ bridge: fakeBridge, groupId: 12345 },
);
expect(elem.richMsg?.serviceId).toBe(35);
expect(inflatePrefixedPayload(elem.richMsg!.template1!)).toBe(xml);
});
});
describe('element-builder / commonElem.businessType per scene', () => {
describe('image', () => {
it('c2c → businessType 10', async () => {
@@ -129,10 +166,7 @@ describe('element-builder / forward preview (com.tencent.multimsg LightApp)', ()
// the outer's LongMsgResult — without uniseq the QQ-NT client has
// no way to walk the tree and has to re-fetch each inner resId.
function decodeLightApp(elem: any): unknown {
const data: Uint8Array = elem.lightApp.data;
expect(data[0]).toBe(0x01); // deflate prefix
const inflated = inflateSync(Buffer.from(data.subarray(1))).toString('utf8');
return JSON.parse(inflated);
return JSON.parse(inflatePrefixedPayload(elem.lightApp.data));
}
it('emits a lightApp.data blob with prefix=0x01 (deflated JSON, not XML/serviceID=35)', async () => {

View File

@@ -110,6 +110,64 @@ describe('formatMessageSegments', () => {
expect(out).toBe('hi [图片] @12345 @全体成员 [回复:999] [表情] [视频] [语音]');
});
it('renders file segments using data.name (the OneBot field), with data.file fallback', () => {
expect(formatMessageSegments([{ type: 'file', data: { name: '20260606_151113.wav' } }]))
.toBe('[文件:20260606_151113.wav]');
expect(formatMessageSegments([{ type: 'file', data: { file: 'legacy.bin' } }]))
.toBe('[文件:legacy.bin]');
expect(formatMessageSegments([{ type: 'file', data: {} }]))
.toBe('[文件]');
});
it('renders json card segments by extracting the card title from common ARK fields', () => {
// mini-program share: meta.detail_1.title
const miniApp = JSON.stringify({
app: 'com.tencent.miniapp_01',
meta: { detail_1: { title: '哔哩哔哩', desc: '某个视频标题' } },
});
expect(formatMessageSegments([{ type: 'json', data: { data: miniApp } }]))
.toBe('[卡片:哔哩哔哩]');
// news share: meta.news.title
const news = JSON.stringify({ meta: { news: { title: '新闻标题' } } });
expect(formatMessageSegments([{ type: 'json', data: { data: news } }]))
.toBe('[卡片:新闻标题]');
// QQ server-side fallback (cardId -896954183): only `prompt` is present
const fallback = JSON.stringify({
app: 'com.tencent.structmsg',
prompt: '当前QQ版本不支持此应用,请升级',
});
expect(formatMessageSegments([{ type: 'json', data: { data: fallback } }]))
.toBe('[卡片:当前QQ版本不支持此应用,请升级]');
// generic single-section meta (no recognised key, but only one section)
const generic = JSON.stringify({ meta: { custom_section: { title: '通用卡片' } } });
expect(formatMessageSegments([{ type: 'json', data: { data: generic } }]))
.toBe('[卡片:通用卡片]');
// long titles are truncated
const long = JSON.stringify({ prompt: 'a'.repeat(100) });
expect(formatMessageSegments([{ type: 'json', data: { data: long } }]))
.toBe(`[卡片:${'a'.repeat(30)}...]`);
});
it('falls back to [JSON] when the card payload is unparseable or empty', () => {
// non-string data.data
expect(formatMessageSegments([{ type: 'json', data: {} }])).toBe('[JSON]');
// invalid JSON
expect(formatMessageSegments([{ type: 'json', data: { data: 'not-json{' } }]))
.toBe('[JSON]');
// JSON without any recognised title field
expect(formatMessageSegments([{ type: 'json', data: { data: '{"foo":1}' } }]))
.toBe('[JSON]');
// empty string
expect(formatMessageSegments([{ type: 'json', data: { data: '' } }])).toBe('[JSON]');
// JSON array (not an object)
expect(formatMessageSegments([{ type: 'json', data: { data: '[1,2,3]' } }]))
.toBe('[JSON]');
});
it('renders unknown segment types as [type]', () => {
expect(formatMessageSegments([{ type: 'something_new', data: {} }]))
.toBe('[something_new]');

View File

@@ -0,0 +1,93 @@
// MessageApi.getGroupHistory walk-back loop: chunking, dedup, server-short-cap
// handling, floor termination, slice(-want). fetchGroupMessageRange is mocked
// so this exercises the loop/cursor logic, not the wire decode (covered in
// packages/protocol/tests/msg-push/fetch-group-history.test.ts).
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
vi.mock('@snowluma/protocol/msg-push', async (importOriginal) => {
const actual = await importOriginal<typeof import('@snowluma/protocol/msg-push')>();
return { ...actual, fetchGroupMessageRange: vi.fn() };
});
import { fetchGroupMessageRange } from '@snowluma/protocol/msg-push';
import { MessageApi } from '../src/bridge/apis/message';
const mockFetch = vi.mocked(fetchGroupMessageRange);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
function gm(seq: number): any {
return {
kind: 'group_message', time: 0, selfUin: 0, senderUin: 1, msgSeq: seq,
msgId: seq, elements: [], groupId: 9999, senderNick: '', senderCard: '', senderRole: '',
};
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const ctx = { identity: {}, sendRawPacket: vi.fn() } as any;
describe('MessageApi.getGroupHistory walk-back', () => {
// The walk-back loop enforces a real ~300ms gap between each SsoGetGroupMsg
// send (a deliberate anti-flood throttle, unchanged in production). Fake the
// clock so the test exercises the loop/cursor logic instantly instead of
// waiting out 300ms × up-to-12 real sends.
beforeEach(() => {
mockFetch.mockReset();
vi.useFakeTimers();
});
afterEach(() => vi.useRealTimers());
// Drives a throttled getGroupHistory to completion under fake timers: kick it
// off, flush the queued send-gap timers, then await the result.
async function runHistory<T>(promise: Promise<T>): Promise<T> {
await vi.runAllTimersAsync();
return promise;
}
it('walks back across short-capped windows, dedups, returns newest `want` ascending', async () => {
// Server caps every window to its newest 10 sequences → forces walk-back.
mockFetch.mockImplementation(async (_s, _id, _self, _g, start, end) => {
const out = [];
for (let s = Math.max(start, end - 9); s <= end; s++) out.push(gm(s));
return out;
});
const res = await runHistory(new MessageApi(ctx).getGroupHistory(9999, 200, 50));
expect(res).toHaveLength(50);
expect(res[0].msgSeq).toBe(151); // newest 50 ending at 200 → 151..200
expect(res[res.length - 1].msgSeq).toBe(200);
for (let i = 1; i < res.length; i++) {
expect(res[i].msgSeq).toBeGreaterThan(res[i - 1].msgSeq); // strictly ascending, no dups
}
});
it('stops at the sequence floor when fewer messages exist than requested', async () => {
mockFetch.mockImplementation(async (_s, _id, _self, _g, start, end) => {
const out = [];
for (let s = start; s <= end; s++) out.push(gm(s));
return out;
});
const res = await runHistory(new MessageApi(ctx).getGroupHistory(9999, 20, 100)); // only seq 1..20 exist
expect(res.map((m) => m.msgSeq)).toEqual(Array.from({ length: 20 }, (_, i) => i + 1));
});
it('caps the request count and bounds the request loop', async () => {
let calls = 0;
mockFetch.mockImplementation(async (_s, _id, _self, _g, _start, end) => {
calls++;
return [gm(end)]; // one message per window → never reaches a large `want`
});
const res = await runHistory(new MessageApi(ctx).getGroupHistory(9999, 100_000, 9999));
expect(calls).toBeLessThanOrEqual(12); // HISTORY_MAX_REQUESTS
expect(res.length).toBeLessThanOrEqual(200); // HISTORY_MAX_COUNT
});
it('returns [] for an invalid anchor without sending', async () => {
expect(await new MessageApi(ctx).getGroupHistory(0, 100, 10)).toEqual([]);
expect(await new MessageApi(ctx).getGroupHistory(9999, 0, 10)).toEqual([]);
expect(mockFetch).not.toHaveBeenCalled();
});
});

View File

@@ -99,3 +99,81 @@ describe('loadBinarySource maxBytes enforcement', () => {
).rejects.toThrow(/too large: 128 > 64/);
});
});
describe('loadBinarySource HTTP header hardening', () => {
const originalFetch = globalThis.fetch;
afterEach(() => {
globalThis.fetch = originalFetch;
vi.restoreAllMocks();
});
it('sends a browser User-Agent on the first attempt, without a Referer', async () => {
const calls: Array<Record<string, string>> = [];
globalThis.fetch = vi.fn(async (_url: unknown, init?: RequestInit) => {
calls.push((init?.headers ?? {}) as Record<string, string>);
return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
}) as typeof fetch;
await loadBinarySource('https://example.test/a.png', 'image');
expect(calls).toHaveLength(1);
expect(calls[0]['User-Agent']).toMatch(/Mozilla\/5\.0/);
expect(calls[0]['Referer']).toBeUndefined();
});
it('retries with a Referer when the first fetch fails at the network level', async () => {
// Reproduces the reported bug: an anti-bot front-end resets the
// header-less request → undici `TypeError: fetch failed`. The retry
// carries a Referer pointing at the resource itself and succeeds.
const calls: Array<Record<string, string>> = [];
globalThis.fetch = vi.fn(async (_url: unknown, init?: RequestInit) => {
calls.push((init?.headers ?? {}) as Record<string, string>);
if (calls.length === 1) throw new TypeError('fetch failed');
return new Response(new Uint8Array([9, 9]), { status: 200 });
}) as typeof fetch;
const loaded = await loadBinarySource('https://img.example.test/x.gif', 'image');
expect(Array.from(loaded.bytes)).toEqual([9, 9]);
expect(calls).toHaveLength(2);
expect(calls[0]['Referer']).toBeUndefined();
expect(calls[1]['Referer']).toBe('https://img.example.test/x.gif');
});
it('retries with a Referer on a 403 (anti-hotlink)', async () => {
let n = 0;
globalThis.fetch = vi.fn(async () => {
n++;
if (n === 1) return new Response(new Uint8Array(0), { status: 403 });
return new Response(new Uint8Array([7]), { status: 200 });
}) as typeof fetch;
const loaded = await loadBinarySource('https://cdn.example.test/y.jpg', 'image');
expect(Array.from(loaded.bytes)).toEqual([7]);
expect(n).toBe(2);
});
it('does not retry a size-limit rejection (deterministic, no second download)', async () => {
const fetchMock = vi.fn(async () => new Response(new Uint8Array(0), {
status: 200,
headers: { 'content-length': String(10 * 1024 * 1024) },
}));
globalThis.fetch = fetchMock as typeof fetch;
await expect(
loadBinarySource('https://example.test/big.bin', 'image', 1024),
).rejects.toThrow(/too large/);
expect(fetchMock).toHaveBeenCalledTimes(1);
});
it('surfaces the first error when the Referer retry also fails', async () => {
let n = 0;
globalThis.fetch = vi.fn(async () => {
n++;
throw new TypeError('fetch failed');
}) as typeof fetch;
await expect(
loadBinarySource('https://example.test/z.png', 'image'),
).rejects.toThrow(/fetch failed/);
expect(n).toBe(2);
});
});

View File

@@ -0,0 +1,161 @@
// highway-client.uploadHighwayHttp 的连接生命周期测试。
//
// 回归覆盖:当上传数据 > HIGHWAY_BLOCK_SIZE (1 MiB) 时,旧实现会复用
// 同一个 TCP socket 在 keep-alive 模式下连续 POST,但 QQ highway 的
// 边缘节点经常在第一次响应后立刻 FIN 关闭,导致第二次 POST 报
// `connection closed before response`。用户上报的 1.19 MB 图片
// (onebot retcode=1200)就是这个分支。
//
// 修复方案:每个 chunk 独立建一个新的 TCP 连接。本测试通过 mock
// `net.createConnection` 计数建连次数,断言每个 chunk 一连接的不变量。
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { EventEmitter } from 'events';
// highway-client 解析响应只关心 errorCode === 0 —— 一个完全空的
// RespDataHighwayHead protobuf 体(0 字节)会被解为 ,errorCode
// 是 undefined,走 falsy 通过分支。
//
// HTTP body 是 highway frame:
// 0x28 | head_len(BE32) | body_len(BE32) | head | body | 0x29
function buildEmptyHighwayResponseFrame(): Buffer {
const frame = Buffer.alloc(10);
frame[0] = 0x28;
frame.writeUInt32BE(0, 1); // head_len
frame.writeUInt32BE(0, 5); // body_len
frame[9] = 0x29;
return frame;
}
function buildHttpResponse(frameBody: Buffer): Buffer {
const headers = [
'HTTP/1.1 200 OK',
`Content-Length: ${frameBody.length}`,
'Connection: close',
'',
'',
].join('\r\n');
return Buffer.concat([Buffer.from(headers, 'ascii'), frameBody]);
}
// FakeSocket 模拟 net.Socket 的最小子集。highway-client 用到:
// - 'data' / 'error' / 'close' 事件
// - .write(data, cb) cb 会被 socketWrite 等待
// - .destroy()
// - .setTimeout / .once / .removeListener (继承自 EventEmitter)
class FakeSocket extends EventEmitter {
destroyed = false;
// 每个 POST = 2 次 write(HTTP header + body)。第二次 write 落地后
// 异步回放响应并立刻 close —— 复现 QQ highway 真实行为:响应一发完
// 就 FIN,旧实现的下一次 POST 必然撞上已关闭的 socket。
private writeCount = 0;
private response: Buffer;
constructor(response: Buffer) {
super();
this.response = response;
}
setTimeout(_ms: number) { /* no-op */ }
write(_data: unknown, cb?: (err?: Error) => void): boolean {
this.writeCount += 1;
if (this.writeCount === 2) {
setImmediate(() => {
this.emit('data', this.response);
this.emit('close');
});
}
if (cb) cb();
return true;
}
destroy() {
this.destroyed = true;
}
}
// vitest 把 vi.mock 工厂 hoist 到文件顶部,所以工厂里不能引用普通的
// 顶层 const —— 那会触发 "Cannot access X before initialization"。
// 用 vi.hoisted 让这两个值跟着 mock 一起被 hoist。
const { createdSockets, createConnectionMock } = vi.hoisted(() => ({
createdSockets: [] as FakeSocket[],
createConnectionMock: vi.fn(),
}));
vi.mock('net', () => ({
default: { createConnection: createConnectionMock },
createConnection: createConnectionMock,
}));
import { uploadHighwayHttp, type HighwaySession } from '@snowluma/protocol/highway';
import type { BridgeContext } from '@snowluma/protocol/bridge-context';
const HIGHWAY_BLOCK_SIZE = 1024 * 1024;
function makeBridge(): BridgeContext {
return {
identity: { uin: '10001' } as unknown,
} as unknown as BridgeContext;
}
function makeSession(): HighwaySession {
return {
sigSession: new Uint8Array([0xAA]),
sessionKey: new Uint8Array([0xBB]),
host: '127.0.0.1',
port: 80,
};
}
describe('uploadHighwayHttp connection lifecycle', () => {
beforeEach(() => {
createdSockets.length = 0;
createConnectionMock.mockReset();
createConnectionMock.mockImplementation((_opts: unknown, listener?: () => void) => {
const sock = new FakeSocket(buildHttpResponse(buildEmptyHighwayResponseFrame()));
createdSockets.push(sock);
// net.createConnection 在握手成功后调用 listener。同步触发即可,
// tcpConnect 的 Promise 会立刻 resolve。
if (listener) setImmediate(listener);
return sock as unknown as ReturnType<typeof createConnectionMock>;
});
});
afterEach(() => {
vi.restoreAllMocks();
});
it('uses a single TCP connection for a sub-block payload', async () => {
// 0.5 MiB → 1 chunk。覆盖 PTT / 小图的常见场景。
const bytes = new Uint8Array(512 * 1024);
await uploadHighwayHttp(
makeBridge(), makeSession(), 1003, bytes, new Uint8Array(16), new Uint8Array(0),
);
expect(createConnectionMock).toHaveBeenCalledTimes(1);
expect(createdSockets[0]!.destroyed).toBe(true);
});
it('uses a fresh TCP connection per chunk for multi-block payloads', async () => {
// 1.5 MiB → ceil(1.5) = 2 chunks。这正是用户上报的 1.19 MB 图片
// 触发的代码路径:旧实现复用 socket 时第二次 POST 撞上 keep-alive
// 关闭,新实现必须为每个 chunk 各开一个 socket。
const bytes = new Uint8Array(Math.floor(1.5 * HIGHWAY_BLOCK_SIZE));
await uploadHighwayHttp(
makeBridge(), makeSession(), 1003, bytes, new Uint8Array(16), new Uint8Array(0),
);
expect(createConnectionMock).toHaveBeenCalledTimes(2);
expect(createdSockets).toHaveLength(2);
for (const sock of createdSockets) {
expect(sock.destroyed).toBe(true);
}
});
it('opens N connections for N chunks (3 chunks here)', async () => {
const bytes = new Uint8Array(Math.floor(2.5 * HIGHWAY_BLOCK_SIZE));
await uploadHighwayHttp(
makeBridge(), makeSession(), 1004, bytes, new Uint8Array(16), new Uint8Array(0),
);
expect(createConnectionMock).toHaveBeenCalledTimes(3);
});
});

View File

@@ -283,6 +283,11 @@ describe('pipeline — runNtv2Upload', () => {
}))).rejects.toThrow(/image fast-upload not available/);
});
// (Removed the forceFullOnFastPath retry tests with the feature itself — real-
// machine testing + kernel RE proved the tryFastUploadCompleted:false retry
// never forces a fresh upload; expired-but-indexed video resources are a
// platform limitation. See #145.)
it('silently skips a sub-file with empty bytes when no fastOnlyError is configured', async () => {
// This mirrors the video-thumb path where bytes are always synthesised
// (FALLBACK_THUMB) so we don't expect the check to fire even if the

Some files were not shown because too many files have changed in this diff Show More