Refactor Hub to treat each UIN as a single active Channel: channelsByUin_ now maps UIN -> Channel (no Set of IDs), primary selection logic and primaryByUin_/pickPrimary were removed, and addChannel replaces any existing channel for a UIN (disposing the previous one). Updated add/remove flows to update channelsById_ and channelsByUin_ accordingly and to bring cores online/offline in the simplified model.
Also: removed extensive JSDoc/comment blocks from channel/adapter/channel-ctx/core/hub files to slim the public API surface, reordered/cleaned exports in packages/channel/src/index.ts, added a new hub-events.ts placeholder, and cleaned up a test helper comment. Disposal of replaced channels is wrapped with a try/catch and logged at debug level.
Pass the monorepo root to @snowluma/proton's Vite plugin so protobuf encode/decode call sites in transitive workspace packages are transformed during testing. Adds path/fileURLToPath imports and __dirname, and calls protobufVitePlugin({ root: path.resolve(__dirname, '../..') }) to mirror @snowluma/core's setup and avoid "was not transformed" errors in OneBot tests.
Update packages/channel/package.json test script to run `vitest run --passWithNoTests` so CI or local runs won't fail when the package has no tests. No other behavior changes.
Reorganize package layout and rename core/account types: - Move channel hook & socket sources/tests into packages/channel-hook and packages/channel-socket (many files renamed). - Remove ChannelManager from packages/channel and drop its export from package.json (multi-account host folded into Hub). - Update tests to use HookSink instead of BridgeManagerSink. - In @snowluma/core: move account/apis/* up to src/apis, rename account-context→core-context, account-interface→core-ctx, account→core, and add hub.ts; delete AccountManager. - Update constructors and type usages to accept CoreContext/CoreCtx and adapt identifiers accordingly. This is a refactor to clarify responsibilities (split transport implementations, fold multi-account manager into Hub, and rebrand the account layer as Core).
Move/rename the transport/bridge code into a new @snowluma/channel layout and extract hook implementations into channel-specific packages. Many bridge sources were deleted and equivalent channel files added (adapter/ctx/interface/channel/hook/socket pieces moved/renamed), along with tests and configs relocated under packages/channel. RoadMap.md replaced with a detailed v3 architecture plan describing Channel/ChannelCtx/Core/CoreCtx/Hub boundaries and migration steps. Also apply related core package updates (account/core reshaping and package.json adjustments) to match the new architecture.
Move transport-layer bridge code out of @snowluma/core into a dedicated @snowluma/bridge package and introduce a clear account layer in core. Adds Bridge, BridgeInterface, InjectBridge, ProtocolBridge (stub), adapters, and manager files under packages/bridge and updates package.json exports. In @snowluma/core the former bridge surface is replaced by Account, AccountContext, AccountInterface and AccountManager; apis were moved/renamed to account/apis and now consume AccountContext. Adjustments include packet handling plumbing (use deliverPacket / setPacketHandler), updated sendRawPacket wiring, uploaded-file cache and lifecycle changes (InjectBridge.dispose, ProtocolBridge returns a structured not-implemented result). Tests and imports were updated accordingly.
Introduce a transport-adapter layer and refactor the bridge abstractions to be transport-agnostic. Added BridgeAdapter and BridgeAdapterHost (packages/core/src/bridge/adapter.ts) plus concrete InjectBridge/InjectBridgeAdapter and ProtocolBridge/ProtocolBridgeAdapter implementations (new files). Made Bridge an abstract base exposing kind/id and abstract sendRawPacket, moved transport-specific PID/sender logic into InjectBridge. Reworked BridgeManager to register/start adapters, manage bridges by id/uin, pick a primary per-UIN (inject preferred over protocol), and provide a host API for adapters to add/remove bridges. Updated index bootstrapping to register adapters and wire the WebUI to the inject adapter's HookManager. Adjusted tests and OneBot code to remove PID tracking from OneBotInstance/OneBotManager and to instantiate InjectBridge in tests. Also exported new entry points in package.json for adapter/bridge modules. This decouples transports from manager logic and adds a stubbed protocol runtime for future pure-protocol support.
Add a cheap AST probe in file-pipeline to detect if a file contains extending classes (using fileHasExtendingClass) and return early to avoid the expensive resolveImports recursive descent when not needed.
Update subclass-wrapper tests to import beforeAll and cache the plugin transform output and its stripped JS once in a beforeAll hook, replacing repeated transform calls with reused transformedOutput/strippedJs to reduce test runtime.
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.
Refactor subclass-wrapper resolution to an AST-only pipeline and remove the TypeChecker-based program cache.
- Move subclass-wrapper logic from typecheck/ to ast/: add ast/file-pipeline.ts and ast/subclass-wrapper.ts, and update codegen/imports accordingly.
- Implement AST-only cross-file extends resolution using import-resolver's fileCache (findImportSourcePath) and a WrapperLookupCache; subclass methods must now have explicit type annotations (no TypeChecker inference).
- Remove TypeChecker-dependent program-cache and typecheck/file-pipeline; plugin no longer preloads a ts.Program or accepts tsconfig option.
- Simplify plugin cache startup and HMR handling in src/index.ts to use the AST pipeline and transform cache only.
- Update tests to use the new AST pipeline entrypoints and adjust expectations.
This eliminates the dependency on a baked ts.Program for wrapper resolution, simplifies startup, and relies on the existing import-resolver for cross-file traversal. Partial wrapper resolutions are still all-or-nothing; explicit annotations are required for AST-only resolution.
Consolidate and simplify import extraction and wrapper/typecheck internals. Introduce collectImportClauses that drives both type+value and value-only import extraction with per-file caching; reintroduce extractImports/extractValueImports as thin wrappers. Clean up BARE_SPECIFIER_COMPILER_OPTIONS comment. Replace the containsTypeParameter/firstTypeParameterIndex pair with a single findTypeParameterIndex helper. Remove collectExportedWrappers and call collectWrappers directly from parseFileForDefinitions; ensure imported wrapper collection skips type-only imports to avoid eager parsing.
Streamline static-wrapper representations: ClassWrapperInfo is now a Map<string, WrapperMethodInfo>, and related detection helpers updated and documented. Simplify subclass-wrapper/typechecker APIs: drop wrapperOwner and SourceFile parameters where unused, adjust function signatures (collectInheritedWrappers, resolveSubclassWrappers, resolveWrapperCodecCalls, extractSubclassMemberTypeNode) to operate with fewer arguments and return plain WrapperMethodInfo lists. Update file-pipeline to match reordered args.
Refactor plugin context creation: add buildContext helper, createPluginContext/createStandaloneContext now delegate to it; remove programPrepared flag and adjust prepareProgramForTsconfig invocation site. Update tests to reflect Map API changes and revised function signatures.
Overall this is an internal refactor to reduce duplication, avoid eager work for type-only imports, remove unused params, and clarify interfaces without changing behavior.
Export and centralize small utility helpers and remove duplicate implementations: identityImportedTypeName was exported from utils, and isVarint64/isFixed64BigInt were added to types and imported into encoder/decoder. Minor import reorders and formatting cleanups across collector, monomorphizer, import-resolver, static-wrapper, subclass-override and file-pipeline. Comments and JSDoc were tightened for clarity; behavior remains the same but common logic is now deduplicated and easier to maintain.
Strip the large one-shot release driver comment block at the top of tools/release.mjs and apply minor formatting cleanups (compact ok() logging line and adjust spacing for the `ahead` variable). No functional changes intended — just cleanup of comments and whitespace.
Introduce disk caching and startup program preparation for the Proton Vite plugin. Add ProtobufVitePluginOptions (root, tsconfig, cache) and configResolved hook to prebuild/prepare a TypeScript Program (program cache) and create a transform cache per-file (transform cache) keyed by source/config hashes and dependency mtimes. Track dependencyFiles in import-resolver so transform cache can validate mtimes. Update program-cache to support incremental tsbuildinfo and expose prepareProgramForTsconfig. Add cache read/write, hashing, path normalization and scope checks in the plugin; update tests and README to cover scope and cache behavior. Also add ts-morph dependency and update lockfile.
Introduce a TextEdit type and applyTextEdits utility for safe, reverse-ordered string edits and refactor replacer to produce and consume edit lists (collectReplacementEdits) instead of performing manual slicing. Propagate ts.SourceFile through ParsedFileEntry/ImportedDefinitions and use cached extraction of imports/exports to avoid repeated AST traversal when resolving imports; analyzer now prefers an imported sourceFile when available. Wire text edits into the plugin pipeline (compose replacement + override edits) and remove the previous applyOverrideInsertions helper. Add a tsconfig lookup cache in program-cache to speed up upward tsconfig searches and invalidate it when the program cache is cleared. README updated to list the new files.
Move instantiateWrapperTypePattern and the WrapperBinding type into a new wrapper-binding.ts module and register it for reuse. Update analyzer.ts and import-resolver.ts to import the function/type from the new module and simplify call-site/type-root collection logic (use entrySourceFile and a cached callable name). Also update README: add ast-helpers.ts and wrapper-binding.ts to the file list and bump test count in the example.
Avoid the expensive TypeChecker/program startup for files that don't declare extending classes by performing a cheap top-level scan first. index.ts now imports fileHasExtendingClass and a SubclassWrapperPipelineResult type and conditionally calls runSubclassWrapperPipeline only when a candidate is found, otherwise returning an empty result. Also updated comments to explain the optimization. subclass-wrapper.ts now imports isStaticMethod from ast-helpers.js (small import cleanup/usage update).
Add shared AST predicates in packages/proton/src/ast/ast-helpers.ts to centralize small structural checks used by the analyzer, callsite matcher, wrapper detector, and subclass resolver. Introduce a WeakMap cache in packages/proton/src/ast/utils.ts so createImportedTypeNameResolver is memoized per SourceFile to avoid repeated import-scans during transform() work. Update packages/proton/README.md with a Chinese translation and various clarifications/documentation tweaks.
Group rendered subclass overrides per class and emit them as position-tagged insertions instead of a single trailing string. Add SubclassOverrideInsertion and applyOverrideInsertions to splice overrides immediately after each subclass declaration (sorted in reverse to keep offsets valid). Update runSubclassWrapperPipeline to collect per-subclass rendered parts and return insertions + extra root names, and update the plugin transform to apply these insertions before producing final code. Update tests to expect insertions and verify placement and runtime behavior. This ensures user code sees overrides right after the class body so subsequent top-level calls dispatch to the override rather than an inherited abstract implementation.
Introduce per-subclass static-method wrapper support: detect wrapper-pattern methods in the AST, resolve concrete types via a TypeChecker, render per-subclass overrides, and append them into transformed output. Adds static-wrapper detector, subclass-override codegen, a typecheck file pipeline, a lazy ts.Program cache, and the subclass-wrapper resolver. Integrates the pipeline into the Vite plugin (including program cache invalidation on HMR) and threads extra root type names into registry selection so generated overrides get required codecs. Remove the runtime-map fallback feature and related types/logic (runtime-map module, dynamic runtime generation, and public API surface), simplifying runtime stubs and protobuf.d.ts. Update README and analyzer to document and support the new flow; add tests and fixtures for subclass-wrapper behavior.
Reorder and normalize imports, add missing type imports, and fix whitespace/formatting across multiple files. Notable updates: eslint.config.ts import ordering; core bridge APIs (group-album, misc, web) now import Json types; tests/highway pipeline import ordering and added type imports; protocol changes (element-builder, highway client/pipeline) reorganized imports and added proto type imports; many oidb service modules moved protobuf encode/decode imports for consistency; web group modules (album, essence, honor, notice, request-util) reordered imports, adjusted typings/indentation, and small whitespace fixes. These edits are stylistic and typing improvements and should not change runtime behavior.
Enable @typescript-eslint/no-explicit-any as an error in the ESLint config to tighten typing across the codebase, and add an override to disable this rule for test files. Also apply non-functional cleanup in packages/proton/src/runtime.ts: reorder/imports and adjust formatting/indentation and string alignment for readability — no behavioral changes.
Remove an unused Bridge import, the asBridge helper and a stale comment from group-album, and relocate the GroupAlbumMediaResult and GroupAlbumCommentResult interfaces to the end of the file. In the sqlite package, remove the inline eslint-disable-next-line for @typescript-eslint/no-explicit-any near the BetterSqlite3 constructor. These edits clean up dead/stale code and re-enable the lint rule; there are no behavioral changes.
Reorder and tidy imports, re-export types, and apply minor formatting fixes across the bridge package. Changes include:
- Reordered imports and grouped related imports in hook-manager, hook-session, pipe-watcher, qq-hook-client, qq-port-probe and others.
- Moved several type re-exports (HookProcessBaseInfo, QqPortLoginInfo, HookProcessInfo/Status) in hook-manager and consolidated exports in package entry index.ts.
- Minor whitespace/style tweaks: constructor spacing, for-loop formatting, empty catch handlers, and small refactors that do not change runtime behavior.
These are non-functional housekeeping changes to improve consistency and readability.
Move and standardize API implementations under bridge/apis, slim down the Bridge class (remove inline action implementations, caches and large comment blocks) and relocate related types/exports. Clean up and reorder imports across many bridge/api modules, normalize constructors, add logger imports where needed, and adjust WebUI routing/import ordering. These changes centralize API logic, reduce Bridge surface area, and tidy module boundaries and imports.
Remove extraneous comments, redundant explanatory notes and extra blank lines across onebot packages; reorder and normalize import lists in group-admin and group-album; remove unused comment blocks in event-converter. These are non-functional cleanup changes in packages/onebot/src/actions/extended.ts, packages/onebot/src/actions/group-admin.ts, packages/onebot/src/actions/group-album.ts and packages/onebot/src/event-converter/index.ts to improve readability and maintain consistent style.
Add JsonObject import and use it for handleSendPacket param typing; replace deprecated hex.substr with hex.slice; convert and consolidate many English docstrings/comments into Chinese for clarity; remove some JSDoc noise and minor formatting tweaks; improve explanatory comments around streaming download, base64 size checks, safe path resolution and async file writes. These are primarily documentation and small type/cleanup changes with no functional behavior changes.
Split the QQ NT client lifecycle / hook injection layer out of
@snowluma/core into its own self-contained package. The new bridge
package owns:
- native hook addon loader (injector)
- HookManager + per-PID HookSession orchestration
- PipeWatcher for QQ process discovery
- QqHookClient pipe protocol
- qq-port-probe for early UIN sniffing
The hook layer used to type its main collaborator as
`BridgeManager` directly. To keep the new package free of any
dependency on @snowluma/core, the cross-package coupling is now
expressed via a 3-method `BridgeManagerSink` interface that lives
in the bridge package. BridgeManager (in core) satisfies the
interface structurally with no source changes; the top-level
app/webui still inject it the same way.
Pure file relocation otherwise: git mv preserves history at 100%
on every file, the only logic edit is the interface introduction
in hook-manager.ts and an updated `nativeSearchDirs()` offset
(one fewer `..` since hook now lives at packages/bridge/src
instead of packages/core/src/hook).
The package previously named "bridge" houses the protocol-byte layer
(OIDB cmds, msg-push decoders, highway uploaders, element-builder,
event bus). The name "bridge" suggested transport/lifecycle, which it
isn't — that role lives in core/hook and core/bridge/manager. Rename
to match what's actually inside.
This is a pure rename: zero logic changes, all 73 import sites updated
mechanically and TS-verified. core/onebot dependencies key updated.
ESLint override path adjusted for the moved oidb-services directory.
Rename detection threshold: git log --find-renames=20% recommended
when following history across this commit — content-replacement
(@snowluma/bridge → @snowluma/protocol) dropped per-file similarity
below git's default 50% on import-heavy files.
User report:
SnowLuma's group_invite event renders to OneBot with empty
`comment`, so the bot's approval-prompt template shows nickname
+ uin + flag but loses the requester's verify message.
NapCat's same flow shows the verify text:
【进群申请】批准/驳回:
昵称:KitaIkuyo
QQ:1957003260
flag:1779543612823906
等级:7
你们好 ← only NapCat shows this line
Root cause:
The OIDB push (GroupRequestJoinNotice subType=84) only carries
`(groupUin, targetUid)` and a few opaque numeric fields — no
string for the verify text. NapCat doesn't use the push directly;
they poll `nodeIKernelGroupService.getGroupNotifies` (= our OIDB
0x10C0 pending-request queue at `FetchGroupRequests`) which
returns each pending row with `postscript` (the verify text) and
`seq` (server sequence id). Reference:
dev/NapCatQQ/packages/napcat-onebot/index.ts:483-498
(`flag = notify.seq`, `comment = notify.postscript`).
Our pipeline didn't enrich. The decoder set `message: ''` and
emitted, so OneBot's `comment` was empty.
Fix:
- Extend `PacketPipelineDeps` with a `resolveGroupJoinRequest(
groupId, uid, subType)` hook. Bridge.ts wires it to
`fetchGroupRequests` and matches on `(groupId, uid)` —
targetUid for `subType='add'`, invitorUid for
`subType='invite'`.
- `dispatchAfterStrangerResolve` now fires the profile + request
lookups in PARALLEL via `Promise.allSettled` so a flake on one
path doesn't kill the other. The request lookup's `comment`
lands on `event.message`; OneBot converts that to `comment`.
Decisions:
- Kept the existing `add:<groupId>:<uid>` flag format (consumer
bots already parse it). Switching to NapCat's sequence-form
flag would break callers and is a separate breaking change.
- Both lookups fail-open: if either rejects, the event still
emits with whatever info we did get, so the bot at least sees
the request and can render the bare nickname.
Regression tests:
- `populates event.message from the pending-request queue` — pins
the user-reported "你们好" case end-to-end through the pipeline.
- `runs lookups in parallel` — profile resolves, request fails;
event still ships with the resolved uin and an empty message.
- `invite subtype matches the request on invitorUid` — explicit
contract for the invite-forwarded-to-admin case where the
pending row's REQUESTER is `invitorUid`, not `targetUid`.
345 bridge tests pass (was 342 + 3 new); typecheck + lint clean.
User report: after [a4909ec], log STILL shows
群邀请 950929451 -> [bot group(950929451)]
get_stranger_info params=user_id=950929451 → 未知昵称
But NapCat and a sibling SnowLuma bot in the same group BOTH decoded
the same push as `QQ:1957003260 nickname:KitaIkuyo`. So the wire is
correct — our bot is just looking it up wrong.
Root cause: **legacy cache pollution**. The pre-fix decoder fallback
stored `<requester_uid> → <groupUin>` in the identity DB whenever
`resolveUidToUin` missed (because the fallback `ctx.fromUin` on a
group-scoped push IS the group's own uin). After upgrading to
[a4909ec], `decodeGroupJoinRequest` calls `resolveUidToUin` which
hits the polluted in-memory map (re-populated from SQLite at boot)
and returns the groupUin instead of 0. The new `needsStrangerResolve`
guard only fired on `fromUin <= 0` — so the polluted value flowed
straight through and re-emitted the bug.
Two-part heal:
1. `needsStrangerResolve` now ALSO fires when `fromUin === groupId`
— the pollution signature. A real requester's uin can never
equal the group's own uin, so this is a safe override that
forces the async UID-form FetchUserProfile lookup, which then
`rememberUidUin`s the correct mapping on success (eviction is
already wired in identity-service.ts:468-471).
2. `rememberEventIdentity` for group_invite now passes `uin: 0`
when `event.fromUin === event.groupId`, so future writes don't
re-pollute the cache (`rememberUidUin` short-circuits on
normalized uin ≤ 0).
Cache self-heals on first event after upgrade — no manual DB nuke
needed.
Regression test pins the legacy-pollution path: feeds an event
where `fromUin === groupId` (matching the user's log), verifies the
resolver fires and patches fromUin to the correct value.
User report: when a stranger requests to join a group, the bot
receives `user_id=<groupId>` (instead of the requester's actual
uin) and `get_stranger_info` returns no nickname → bot displays
"未知昵称".
Two layered bugs:
1. **Decoder fallback was wrong.** `decodeGroupJoinRequest` /
`decodeGroupInvitation` / `decodeGroupInvite` all passed
`ctx.fromUin` as the fallback uin when `resolveUidToUin` missed
the local cache. But for group-scoped pushes `ctx.fromUin` is
the GROUP's own uin — falling back to it produces the bogus
`fromUin === groupId` collision the user saw. Fix: pass 0.
2. **No async resolve for stranger UIDs.** The push only carries
the requester's UID string. When the UID isn't in our cache
(true for any stranger who isn't yet a group member), we have
no UIN — and our UIN-form `FetchUserProfile` can't help. The
pipeline never tried to look up the stranger by UID, so the
event went out with `fromUin=0` (or, with the old fallback,
the group's own uin).
Cross-checked against Lagrange.Core's flow:
dev/Lagrange.Core/.../MessagingLogic.cs:215-224
case GroupSysRequestJoinEvent join:
var fetchUidEvent = FetchUserInfoEvent.Create(join.TargetUid);
var results = await Collection.Business.SendEvent(fetchUidEvent);
uint targetUin = results.Count == 0 ? 0
: ((FetchUserInfoEvent)results[0]).UserInfo.Uin;
var joinArgs = new GroupJoinRequestEvent(join.GroupUin, targetUin);
dev/Lagrange.Core/.../OidbSvcTrpcTcp0xFE1_2.cs:9-26
— UID-form variant of the same OIDB 0xFE1_2: field 1 is `uid:
string`, envelope `reserved=0` (no uinForm flag).
dev/Lagrange.Core/.../FetchUserInfoService.cs:66-78
— picks UID vs UIN form based on which input is set.
Changes:
- `proto-defs/oidb-actions/base.ts`: add `OidbUserInfoByUidRequest`
(same shape as the UIN variant but field 1 is `uid: string`).
- `bridge/oidb-services/contacts/fetch-user-profile-by-uid.ts`:
new namespace at 0xFE1_2 with UID-form encoding, no `uinForm`.
- `bridge/msg-push/decoders/group-join-request.ts`: 3 decoders'
`resolveUidToUin` fallbacks change `ctx.fromUin` → 0.
- `bridge/packet-pipeline.ts`: new `resolveStrangerProfile(uid)`
dep + `needsStrangerResolve` check + async dispatch that fires
the lookup before emitting the event. Fail open if the lookup
rejects (event still ships with `fromUin=0` so the OneBot bot
can fall back to the uid in the flag).
- `core/bridge/apis/contacts.ts`: `fetchUserProfileByUid(uid)`
facade method.
- `core/bridge/bridge.ts`: wire `resolveStrangerProfile` into the
pipeline deps so it routes through the new namespace.
Tests:
- UID-form namespace: declares the right cmd/subcmd, packages uid
as field 1, decodes nickname + uin so the pipeline patch works.
- Pipeline stranger resolve: patches event.fromUin from the
resolver response; fails open on null / throw; skips the wire
call when fromUin is already populated or fromUid is empty.
All 655 tests pass (was 645 + 10 new); typecheck + lint clean.
Mobile QQ, Lagrange.Core, and NapCat all use the literal Chinese
bubble-preview strings `[图片]` / `[动画表情]`. SnowLuma was emitting
English `[image]` / `[sticker]` as fallback, so QQ clients showed
"[image]" in chat-list previews instead of the expected Chinese.
Cross-checked against:
dev/NapCatQQ/.../packet/message/element.ts:367-371
dev/Lagrange.Core/.../Message/Entity/ImageEntity.cs:186-192
Both branch the same way: subType=1 → `[动画表情]`, else → `[图片]`.
Changes:
- `bridge/highway/image-upload.ts`: both code paths (fingerprint +
load-from-source) now emit the Chinese defaults. Subtype branch
flipped to `subType === 1 ? '[动画表情]' : '[图片]'` to match the
upstream convention (our old check was `subType === 0` →
`[image]`, which would label any non-zero subType — not just
stickers — as `[sticker]`).
- `bridge/msg-push/rich-body-decoder.ts`: all three decode paths
(NotOnlineImage / CustomFace / commonElem image) now substitute
the Chinese default when the server omits `textSummary`. Empty-
string is also treated as missing (matches NapCat's `=== ''`).
- Tests updated to assert the Chinese defaults; new test pins
that a caller-supplied summary still overrides verdef.
The OneBot caller's `summary` field on the MessageElement still
wins when set, so downstream clients passing custom bubble text
(e.g. for accessibility) keep working.
User reported `highway upload error_code=921` when sending two images
in one OneBot message — image 1 fast-uploaded (server already had the
md5), image 2 (58 bytes) triggered the actual PUT and failed.
Verified the claim from code inspection vs NapCatQQ + Lagrange.Core:
- dev/NapCatQQ/.../highwayContext.ts:62-94 (checkAvailable + prepareUpload)
- dev/NapCatQQ/.../highwayHttpUploader.ts:8-43 (HTTP block upload)
- dev/NapCatQQ/.../highwayContext.ts:219-254 (uploadGroupImage)
- dev/Lagrange.Core/.../HighwayContext.cs:98-180 (UploadSrcByStreamAsync)
Findings:
1. The pipeline runs `runNtv2Upload` sequentially per image (await
inside `buildSendElems`); there's no concurrency or shared state.
2. Each call gets its own OIDB request, its own lazy session fetch,
its own buildHighwayExtend output. No aliasing.
3. The 921 comes from the highway PUT's response head (errorCode),
not from anything client-emitted being malformed.
Verdict: not reproducible from code inspection — almost certainly
server-side (most likely Tencent rejecting the 58-byte image as a
malformed payload; 58B is too small to even be a valid 1×1 PNG).
Hardening:
- Three regression tests pin the sequential two-image semantics so
a future state-leak bug fails loudly:
- extend bytes for image 2 must come from image 2's response,
not image 1's,
- each runNtv2Upload fetches its own non-null session,
- each OIDB request carries its own fileInfo + a unique
clientRandomId.
- The `error_code=N` message now carries segRetCode, cmdId, chunk
size, offset, and the first 8 bytes of the file md5 — without
these the user couldn't tell apart "image rejected" vs "session
expired" vs "rate-limited" on future reports.
If the user reports the same 921 again, the new diagnostic message
should show enough server-side context to triage server-vs-client.
Multi-layer 合并转发 was uploading correctly but the outer's
LongMsgResult piggyback was *unreachable* by the receiver because
two things were missing:
1. The forward preview element was emitted as the old XML
`richMsg serviceID=35 m_resid=…` shape, which carries the
inner resId but has NO uniseq field.
2. The piggyback `actionCommand: <uuid>` slot generated a fresh
UUID that was never reflected into the preview either.
Result: QQ-NT receivers saw the inner preview's resid, scanned the
outer's actions[] for a matching uniseq, found none, and either
fell back to a fresh server fetch per layer or dropped the layer
entirely.
Cross-checked against:
- dev/Lagrange.Core/Lagrange.Core/Message/Entity/MultiMsgEntity.cs:43-115
- dev/NapCatQQ/packages/napcat-core/helper/forward-msg-builder.ts:52-122
- dev/NapCatQQ/packages/napcat-onebot/action/msg/SendMsg.ts:208-347
Both upstream impls use the modern `com.tencent.multimsg` LightApp
JSON whose `meta.detail.uniseq` is the round-trip key that links
the inner preview to the matching `actionCommand` in the outer's
LongMsgResult — no separate fetch needed.
Changes:
- `element-builder.makeForwardElem` now emits a deflated
`com.tencent.multimsg` LightApp JSON (LightAppElem, field 51)
instead of the XML RichMsg (field 12). `forwardUuid` on the
MessageElement is baked into `meta.detail.uniseq` and
`extra.filename`. Auto-generates a UUID when absent.
- `MessageElement.forwardUuid?: string` added for the round-trip.
- `forward.uploadRecursive` threads `inner.uuid` into the outer's
preview element AND uses the same uuid for the outer's
piggyback actionCommand — closing the receiver-side lookup loop.
- `forward.fetch` now walks ALL actions (not just `MultiMsg`),
indexes piggybacks by uuid, and pre-populates the cache for
each inner resId discovered in the outer's preview bubbles.
Follow-up `fetch(innerResId)` hits the cache instead of the wire.
- `rich-body-decoder` parses LightApp JSON; when `app ===
com.tencent.multimsg`, emits `{type: 'forward', resId,
forwardUuid}` so the OneBot layer can walk in. Legacy XML
serviceID=35 path stays as a fallback for mobile QQ senders.
Wire-byte tests cover:
- send: lightApp.data is 0x01-prefixed deflated JSON with the
right meta + extra fields
- send/nested: outer LongMsgResult carries `MultiMsg` AND a
uuid-keyed piggyback; the piggyback uuid matches the
preview's `meta.detail.uniseq` baked into the same outer
msgBody
- send/3-deep: outermost action[] has 1 + 2 entries (own
MultiMsg + 2 piggybacks hoisted from deeper levels)
- recv: lightApp `com.tencent.multimsg` → forward element with
both resId and forwardUuid; non-multimsg LightApp falls
through to {type:'json'}; legacy XML path still emits
{type:'forward'}.
641 tests pass (was 628 + 13 new); typecheck clean; lint clean.
The first pass at namespace-per-cmd left a smell: namespaces that
needed identity/uid resolution had to declare `Deps` AND then rewrite
their own spec inside `invoke` via a closure-over-resolved-value:
// before
export const serialize = (p: Params, targetUid: string) => ({...});
export const invoke = async (deps, params) => {
const targetUid = await deps.resolveUserUid(params.userId);
return invokeOidb(deps, {
...Self,
serialize: p => serialize(p, targetUid), // ← escape hatch
}, params);
};
Reading "what does this cmd do on the wire?" required reading the
namespace AND the closure rewrite — the namespace wasn't really
self-contained, just a forwarder of two pure functions.
Fix: thread `ctx` (the namespace's full capability surface) into
`serialize` and `deserialize` directly. `serialize` may now return
`Promise<TReq>` so identity / uid lookups happen in place:
// after
export const serialize = async (ctx: Deps, p: Params) => ({
groupUin: p.groupId, type: 1,
body: {
targetUid: await ctx.resolveUserUid(p.userId, p.groupId),
duration: p.duration,
},
});
export const invoke = (deps, params) => invokeOidb(deps, Self, params);
OidbCallSpec gains a `TCtx extends OidbSender` generic; invokeOidb's
first arg becomes `ctx: TCtx` (the sender capability is just a slice
of ctx now). buildOidbRequest / parseOidbResponse follow the same
shape. Async serialize is awaited inside invokeOidb.
17 namespaces had closure rewrites; all 17 collapse to plain
`invokeOidb(deps, Self, params)` invokes. Only one closure remains —
`fetch-user-profile` binds `params.uin` into deserialize as a server-
echo fallback; kept as a documented exception (the rare case where
deserialize wants request context, not ctx).
Wire bytes preserved across all migrations. 326 bridge tests + 302
core tests pass; lint clean.
The namespace-per-cmd OIDB service layer was tripping
`@typescript-eslint/no-namespace` across 59 files; namespace IS
the OidbCallSpec by design (structural typing, one file per
(cmd, subcmd)) so disable the rule for that subtree only. Drop
four stale `eslint-disable-next-line @typescript-eslint/no-empty-
object-type` comments that aren't needed anymore (the empty
`Params {}` shape no longer triggers the rule), and fix an indent
nit in the get-unidirectional-friend-list test.
`npx eslint packages` now reports 0 errors. The 5 remaining
warnings are unused-vars / unused-eslint-disable in unrelated
pre-existing files.
Splits the 16 OIDB cmds from GroupFileApi into self-contained
namespaces under @snowluma/bridge/oidb-services/group-file/. Adds
@snowluma/bridge/oidb-services/shared with `toInt` / `ensureRetCodeZero`
helpers so namespaces can validate sub-responses without an
@snowluma/core dependency.
Boundaries:
- Single-OIDB methods (publish / getCount / list-page / *url /
delete / move / *folder) become one-line forwarders.
- 3-stage methods (`upload` / `uploadPrivate`) keep their
orchestration on the facade — OIDB preflight goes through the
new namespace, but highway PUT + publish/sendC2cFile + upload-
cache bookkeeping stay where they are.
- `list` keeps its pagination loop on the facade; the page-fetch
namespace is one call.
- The NTV2-rich-media URL fetchers (group/private × ptt/video)
share a deserialize helper (`parseNtv2DownloadUrl`) so all four
namespaces only differ in their scene block.
Wire-byte equivalence preserved. The 0x6D6 family shares one
OidbGroupFileReq envelope; each namespace populates a different
slot (file / download / delete / move) and proton monomorphizes
per call site as before.
Splits the 14 OIDB cmds from GroupAdminApi into self-contained
namespaces under @snowluma/bridge/oidb-services/group-admin/. The
facade becomes one-line forwarders; per-cmd capability is narrowed
to OidbSender (+ resolveUserUid / identity where the cmd actually
needs it).
Notes:
- 0x89A_0 hosts MuteAll, SetAddOption, SetSearch, SetGroupName —
same (cmd, subcmd) tuple, four different proto bodies; each gets
its own namespace so proton can monomorphize independently.
- 0x8A0_1 splits KickMember (single) and KickMembers (batch) for
the same reason.
- SetAddRequest carries uinForm=true and dynamic subCommand
(filtered ? 2 : 1) on the same namespace.
- GetAtAllRemain needs the bot's own uin → declares
Pick<BridgeContext, 'identity'> in its Deps.
Wire-byte equivalence preserved; corner case for getAtAllRemain
empty-envelope path now returns {false, 0, 0} instead of throwing —
the new infrastructure normalises empty bodies and the OneBot action
ergonomics are unchanged.
5 logical OIDB cmds → 4 namespace files (group todo's 3 sub-cmds
collapse into one namespace with a dynamic resolver):
- GroupTodo (0xF90_1/2/3) — set/complete/cancel via the
new `action` discriminator
- GetStrangerStatus (0xFE1_2) — uinForm=true; preserves the
(status*10, ext_status) decode
quirk verbatim
- FetchAiVoiceList (0x929D_0)
- FetchAiVoice (0x929B_0) — single poll; retry loop
stays on the facade so callers
can plug their own back-off
Facade keeps the 6 public methods (setGroupTodo / completeGroupTodo /
cancelGroupTodo / getStrangerStatus / fetchAiVoiceList / fetchAiVoice)
as one-line forwarders; only `getStrangerStatus` wraps in try/catch
to preserve its "return null on transport failure" contract, and
`fetchAiVoice` keeps the polling loop.
30 new namespace-level tests; extras.test.ts moved onto the
sendRawPacket assertion model.
Verification:
- typecheck green
- @snowluma/bridge: 24 files / 195 tests
- @snowluma/core: 302 tests
Wire bytes unchanged.
2 OIDB cmds moved (the only OIDB calls in this file — the rest are
HTTP cookie / qun.qq.com / qzone web requests):
- ForceFetchClientKey (0x102A_1) — used by ptlogin2 jump flow to
swap clientKey → cookie jar
- GetPskey (0x102A_0) — p_skey fallback when ptlogin2
omits it
The private `forceFetchClientKeyInner` / `getPSkey` helpers in
WebApi are now one-line forwarders into the namespaces. Facade
methods (`getCookies`, `getCsrfToken`, `getCredentials`, etc.) and
all HTTP-only cmds untouched.
12 new namespace-level tests covering deserialize edge cases
(empty server response, missing fields, dropped invalid items)
and e2e wire routing.
Verification:
- typecheck green
- @snowluma/bridge: 20 files / 165 tests
- @snowluma/core: 302 tests
Wire bytes unchanged.
3 OIDB cmds migrated; the 1 non-OIDB cmd (getMiniAppArk via
LightAppSvc) stays on the facade unchanged.
- TranslateEnToZh (0x990_2)
- ClickInlineKeyboardButton (0x112E_1)
- SendGroupSign (0xEB7_1) — preserves historic UPPERCASE
EB7 wire name via the new
`wireName` override (the only
cmd in the codebase with this
quirk; every other cmd uses
the default lowercase).
Tests:
- misc.test.ts moved to bridge.sendRawPacket assertion model
- 18 new namespace-level tests covering serialize, deserialize edge
cases, magic constants, BigInt widening, and the EB7 case quirk
Verification:
- typecheck green
- @snowluma/bridge: 18 files / 153 tests
- @snowluma/core: 302 tests
Wire bytes unchanged.
5 of profile.ts's methods were thin OIDB wrappers — migrated to the
new namespace pattern. The 5 non-OIDB methods (setOnlineStatus /
setDiyOnlineStatus / setAvatar / setGroupAvatar / fetchCustomFace)
stay on the facade unchanged — they hit `trpc.qq_new_tech.*`,
Highway, or `Faceroam.OpReq` directly and aren't in scope for the
OIDB-namespace refactor.
New namespaces (each with focused Pick<BridgeContext, …> deps):
- SetProfile (0x112A_2) — needs identity for uin
- SetSelfLongNick (0x112A_2) — same cmd different proto, ditto
- SetInputStatus (0xCD4_1) — needs resolveUserUid
- GetLike (0x7ED_12) — needs identity + resolveUserUid
- GetUnidirectionalFriendList (0xE17_0) — needs identity; non-standard
wire name handled via the new
wireName override on OidbCallSpec
Infrastructure tweak:
- OidbCallSpec gains an optional `wireName(cmd, sub) → string`. Most
cmds use the default `OidbSvcTrpcTcp.0xNNNN_N` scheme; 0xe17_0
routes through `MQUpdateSvc_com_qq_ti.web.OidbSvc.0xe17_0`.
Test mock updates:
- profile.test.ts moves the migrated cmds onto bridge.sendRawPacket
mock (the new path bypasses the bridge-oidb runOidb mock). Non-OIDB
cmds (setOnlineStatus, setAvatar, etc.) keep their existing mocks.
- 36 new namespace-level tests in @snowluma/bridge covering serialize
branches, deserialize edge cases, deps resolution, and e2e wire
routing.
Verification:
- pnpm -r typecheck: green
- @snowluma/bridge: 12 files / 118 tests
- @snowluma/core: 33 files / 302 tests
Wire shape unchanged across migrated cmds — same bytes produced.
Completes the InteractionApi facade — every method is now a one-line
forwarder. New namespaces:
- SendPoke (0xED3_1) — group + friend variants discriminated by
which of groupUin/friendUin is set
- SendLike (0x7E5_104) — thumbs-up to a target user
- SetEssence (0xEAC_1/_2) — set/unset essence message, dynamic subcmd
Facade methods reduced to thin forwarders, mirror-fixed comment block
removed (the namespaces now own the wire-shape commentary).
Tests: 28 new in @snowluma/bridge covering each namespace's serialize
edge cases + dynamic subcmd resolution + e2e wire name + envelope body
shape. Cleaned the legacy `vi.mock('bridge-oidb')` setup out of
interaction.test.ts — the post-migration path doesn't route through
the mocked symbols anymore.
Wire behavior unchanged: every cmd produces the same bytes as before,
verified by encode round-trip in the unit tests.
Introduce a new way to organise OIDB cmd implementations:
- one TypeScript namespace per (cmd, subcmd) tuple
- the namespace's exported members ARE the OidbCallSpec (structural
typing — no `implements` clause)
- a single invokeOidb() template method drives every call:
envelope build → encode → send → errorCode check → decode →
deserialize transformation
- each namespace declares its own minimal `Deps` capability via
Pick / intersection on BridgeContext (Interface Segregation):
most cmds need only OidbSender (the `sendRawPacket` method)
The facade Api classes (InteractionApi etc.) stay for now, with the
migrated methods reduced to one-line forwarders that hand off to the
namespace. Callers still write `bridge.apis.X.Y(...)`; the OIDB
wire-encoding work just moved to a self-contained file per cmd.
Vertical slice scope: 3 cmds (the reaction line)
- SetReaction (0x9082_1 / _2; dynamic subcmd)
- FetchReactionSummary (0x9084_1)
- GetEmojiLikes (0x9083_1; legacy stub)
Infrastructure:
- new packages/bridge/src/oidb-service.ts:
OidbSender (sendRawPacket-only capability),
OidbCallSpec<TReq, TResp, TParams, TResult>,
invokeOidb(), buildOidbRequest(), parseOidbResponse(), OidbError
- runOidb() refactored to accept OidbSender instead of BridgeContext
(structurally compatible — no caller changes anywhere)
- new OidbEmpty placeholder type in proto-defs/oidb.ts for cmds whose
response carries no body (proton needs a real message interface,
not `void` / `never`)
- empty-body responses substituted with {} in invokeOidb so
deserialize always receives a defined object
Tests (65 in @snowluma/bridge, all green):
- oidb-service.test.ts (20): every helper branch — static + dynamic
subcmd, uinForm flag, error code propagation as OidbError, empty
body substitution, sender failure modes (success=false /
gotResponse=false / both with and without errorMessage),
timeoutMs propagation
- set-reaction.test.ts: const declarations, dynamic subcmd both
ways, type=1/2 boundary on code length, e2e envelope inspection
- fetch-reaction-summary.test.ts: BigInt serialization, catalog-tail
filtering, default emojiId/Type/lastReactionTime
- get-emoji-likes.test.ts: BigInt serialization, default count /
emojiType, base64 cookie round-trip, uin=0 filtering, isLast
computation, e2e
Existing interaction.test.ts moved off the now-bypassed runOidb mock
onto sendRawPacket mock (the new invokeOidb path routes there).
Workspace-wide typecheck: green. Workspace test totals:
proton 99/99, bridge 65/65, core 302/302, onebot 257/257
(1 pre-existing onebot suite failure, network-manager native addon
load — unrelated to this change.)
Two rounds of production wire-level probing established that the OIDB
SSO path cannot surface the reactor user list for an emoji:
- 0x9083_1 → 4-byte ack `18 01 20 01` (no list)
- 0x9084_1 → per-emoji summary (count + timestamp,
still no user IDs)
- 0x9082_3..5, 0x9083_0/2/3, 0x9084_2..5, 0x9085_1/2, 0x9087_1
→ "no privilege" — the cmds exist but
aren't in NTQQ's client capability
bitmap, so the server blocks anything
not registered at login. NTQQ itself
serves getMsgEmojiLikesList from a
wrapper-internal cache, not SSO.
Mirror that wrapper-cache approach on the OneBot side. SnowLuma
already receives GroupMsgEmojiLikeEvent push events for every
reaction add/remove (with operator uin + uid + emoji + msgSeq); we
just weren't persisting them. Now we do.
Changes:
* proto-defs: add Oidb0x9084 Req/Resp schema for the summary call.
RespEntry's lastReactionTime/count are optional because the
"available reactions catalog" tail entries omit both — only the
"used" subset carries metadata.
* core InteractionApi: revert the 9-candidate probe loop, restore a
single 0x9083_1 call as a legacy stub (returns empty list, with a
debug-level hex dump on empty responses), and add
fetchReactionSummary() that calls 0x9084_1 and yields the per-emoji
summary (count + last-reaction timestamp).
* onebot ReactionStore: new SQLite-backed cache, schema
reactions(group_id, msg_seq, emoji_id, emoji_type, operator_uin,
operator_uid, set_at), PK on (group_id, msg_seq, emoji_id,
operator_uin). Mirrors MessageStore design — prepared statements at
construction, WAL journal.
* onebot event-pipeline: subscribe group_msg_emoji_like, call
reactionStore.recordAdd / recordRemove before convertAndDispatch so
a fetch_emoji_like racing with the push still sees the new row.
* onebot instance / instance-context: own the ReactionStore, expose
it on OneBotInstanceContext, close it on dispose. New
fetchEmojiLikeUsers helper on ApiActionContext combines local-cache
reads with a 0x9084_1 cross-check so callers can detect cache gaps
(events missed before bot boot, etc).
* onebot actions: get_emoji_likes and fetch_emoji_like now read from
the cache. fetch_emoji_like's NapCat-style cookie becomes a numeric
offset for cache pagination (no real cursor needed against local
SQLite).
* tests: 7 new ReactionStore unit tests (CRUD + pagination +
cross-key isolation + summarizeMessage). Existing event-pipeline
test harness picks up a no-op ReactionStore stub.
Round-1 wire dump revealed:
- 0x9083_1 returns a 4-byte ack (`18 01 20 01`), no user data
- 0x9082_3/_4, 0x9083_0/_2/_3 all return "no privilege" (server-side
deny linked to iwiki.woa.com permission docs)
- 0x9084_1 returns 932 bytes — a real reaction *summary* on the
message: first entry carries (timestamp, count, type, emoji_id)
for the used emoji ("76" with count=3 in our test), followed by
a 28-entry catalog of available reaction emojis. NOT a user list,
but proves 0x9084 family has live handlers.
The "fetch users who reacted with emoji X" sibling is almost
certainly another subcmd of 0x9084. Probe the immediate neighborhood:
0x9084_2..5 first-choice candidates (sibling subcmds)
0x9085_1..2 exploratory adjacent cmd
0x9086_1, 0x9087_1 wider probe
0x9084_1 kept at end so we still capture the summary baseline
Replace the env-driven probe with an unconditional round-robin across
the candidate list every fetch_emoji_like invocation:
0x9083_1 baseline (returns 4-byte ack, known not to be fetch)
0x9082_3 sibling of set/unset reaction
0x9082_4
0x9083_0
0x9083_2
0x9083_3
0x9084_1 exploratory
For each candidate the cmd, response length, parsed user count,
request hex, and response hex are dumped at debug level. The first
candidate that surfaces users wins and is returned; failures inside
runOidb (server-side error code, no handler) are caught + continued
so a bad cmd in the middle doesn't tank the whole probe.
fetch_emoji_like is user-triggered ("view who reacted"), so the
extra SSO traffic on each call is acceptable for a debug build —
we only need one production hit to identify the real cmd.
Wire dump from production confirmed 0x9083_1 is a real server endpoint
(routed, errorCode=0, trace string echoes "OidbSvcTrpcTcp.0x9083_1")
but its reply is always a 4-byte minimal ack `18 01 20 01` regardless
of message / emoji / whether the caller just set a reaction — so the
semantics of 0x9083_1 are not "fetch emoji-like users". The real cmd
must be a sibling (0x9082_3, 0x9082_4, 0x9083_2, 0x9083_3, …) but we
don't yet know which.
Rather than rebuild for each candidate, accept an env override
`SNOWLUMA_EMOJI_FETCH_CMD=0x9082_3`. Format is `0xNNNN_N`; a malformed
value warns and falls back to the historic 0x9083_1. Wire name is
recomputed from the parsed (cmd, subcmd) so the trpc routing matches
the OIDB envelope cmd field.
Also unconditionally dump req/resp hex at debug level while we're
probing — once we land on a working tuple the dump can be tightened
back to "only on empty users". The pre-existing log line is widened
to include the wire name and the result count so deployment can scan
multiple cmd values from a single log stream.
`fetchUserProfile` already requested key 105 in the keys[] array but
the decode pass never read it, so callers got nothing. NapCat exposes
the same value as `qq_level` on `get_stranger_info`; users coming from
NapCat noticed the field was missing on the SnowLuma side.
Cross-checked against LagrangeV2 Internal/Services/System/
FetchStrangerService.cs which explicitly labels key 105 = Level and
uses `numbers[105]` directly.
Changes:
- UserProfileInfo: add `level: number`.
- fetchUserProfile decode: `info.level = numMap.get(105) ?? 0`.
- getStrangerInfo: emit both `qq_level` (NapCat-compat) and `level`.
- Test/manager call sites updated for the new required field.
Two bugs collapsed fetch_emoji_like into a perma-empty list with status=ok
and no error output:
1. Req fields 4 and 5 were swapped (emojiType on field 4 / emojiId on
field 5). The sibling 0x9082 OidbGroupReaction has field 4 = code
(string) and field 5 = type (uint), and 0x9083 mirrors that layout —
verified against LagrangeDev/LagrangeV2
`Internal/Packets/Service/SetGroupReaction.cs`. With our swap the
wire types also mismatched (varint vs length-delim), so the server
protobuf decoder dropped both fields and returned an empty list
without ever surfacing an error.
2. Resp `inner.userInfo` was declared as a single message, but the
server emits one entry per liker (repeated). Even after fixing the
req, multi-user responses would have collapsed into the last entry.
Map the decoded array on the InteractionApi side and filter uin=0
placeholders. Test now mocks two users to exercise the repeated path.
The previous commit (ee0f159) regenerated the lockfile starting from
dev's pre-fix state, which diverged structurally from main's lockfile
(main carried dependabot's hono 4.12.18 bump that dev never inherited).
GitHub's auto-merger saw the two lockfiles as touching overlapping
hunks and marked PR #63 CONFLICTING, blocking the bot's auto-merge
flow into main.
Re-seed the lockfile from origin/main (`git show origin/main:pnpm-lock.yaml`)
then run `pnpm install` again — this time the regeneration starts from
main's already-bumped state, so the only delta is the 6 lines removed
from `packages/onebot`'s importer entry (no snapshot churn). PR #63
becomes a clean fast-forward for the bot to merge.
No code or package.json change here; this is purely a lockfile rebase.
Verified: `pnpm install --frozen-lockfile` passes locally against the
new lockfile.
`packages/onebot` declared `hono` and `@hono/node-server` as devDeps but
never imported either — they were leftover scaffolding from when onebot
was carved out of `@snowluma/core`. Combined with dependabot's hono
bump only landing on core's pin (4.12.14 → 4.12.18 in cb06624), this
left two distinct peer-dep resolutions of `@hono/node-server` in the
lockfile (`(hono@4.12.14)` for onebot, `(hono@4.12.18)` for core).
On the dev→main merge the auto-resolver kept main's snapshot list,
dropping the `(hono@4.12.14)` variant onebot still referenced — so
v1.9.1 shipped with an inconsistent lockfile and CI's
`pnpm install --frozen-lockfile` blew up with
`ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY: no entry for
'@hono/node-server@1.19.14(hono@4.12.14)'`.
Fix:
- Remove `hono` + `@hono/node-server` from onebot (verified zero source
imports — only matches were `honour` / `WebHonorType` false hits).
- Bump core's `hono` pin to `^4.12.18` so dev matches what dependabot
already landed on main (otherwise the drift comes back on next merge).
- Regenerate pnpm-lock.yaml — now resolves to a single
`@hono/node-server@1.19.14(hono@4.12.21)` snapshot.
better-sqlite3's JS wrapper is pure CJS — its `require('fs')` /
`require('path')` / `require('bindings')` calls get inlined into the
ESM bundle as `__require("fs")` shims by rolldown. The shim's
fast-path checks `typeof require !== "undefined"` (true in CJS, false
in our `.mjs` output) and otherwise throws "Calling `require` for
\"fs\" in an environment that doesn't expose the `require` function".
The launcher crashed at startup the moment `@snowluma/sqlite` resolved
its `import BetterSqlite3 from 'better-sqlite3'`.
Inject `const require = createRequire(import.meta.url)` via
`rollupOptions.output.banner` so every inlined CJS require routes to
Node's CJS loader. No call-site changes; the only diff in the emitted
bundle is two new top-of-file import/const lines.
Replaces "runtime npm dependency that gets `npm install`-ed into
dist/" with "TS wrapper that loads the native `.node` from
`dist/native/` like every other native binding in the project".
Why the change
--------------
The previous approach (better-sqlite3 declared in
packages/runtime/package.json, materialized by `npm install
--omit=dev` in dist/) worked but produced an artifact that needed
runtime npm install — a step the rest of SnowLuma's native bindings
don't need (websocket / snowluma-hook / ffmpeg are all standalone
`.node` files copied into `dist/native/` by vite-plugin-cp). The
asymmetry was friction: dev mode required `pnpm dist:install`,
build artifacts carried a `dist/node_modules/` tree the other
modules didn't need, and Docker images had to special-case the
glibc-vs-musl ABI lookup that prebuild-install runs.
The new shape:
- `@snowluma/sqlite` (packages/sqlite/) — TS wrapper. Has
`better-sqlite3` as a devDep (for the JS-layer types + the
actual JS wrapper code that vite inlines). At runtime, calls
`createRequire().require()` against
`<dist|repo>/native/better-sqlite3-v<abi>-<platform>-<arch>.node`
and passes the resolved addon to `new Database(path, {
nativeBinding })`.
- `packages/runtime/native/better-sqlite3-v<abi>-<triplet>.node`
— prebuilt binaries vendored into the repo. Two ABIs ship side-
by-side (v127 = Node 22 LTS used by CI, v137 = Node 24 used by
dev boxes) so `process.versions.modules` picks the matching one
at load time.
- `tools/fetch-sqlite-prebuilts.mjs` — fetches all 5 platforms ×
N ABIs from WiseLibs's GitHub releases. Idempotent: existing
`.node` files skip. Accepts extra ABI args:
`node tools/fetch-sqlite-prebuilts.mjs 12.10.0 v127 v137 v115`.
What was unwound
----------------
- packages/runtime/package.json — dependencies removed (runtime
artifact is now self-contained, no `npm install` step needed).
- root package.json — `dist:install` script removed (no node_modules
to install).
- .github/workflows/dev-build.yml — `Bundle runtime dependencies`
step removed.
- .github/workflows/release.yml — kept the `Bundle runtime
dependencies` step (was a no-op already, but harmless safety net
in case a future runtime dep shows up).
- packages/core/vite.config.ts — `better-sqlite3` no longer
external; vite inlines the JS wrapper (+~33 KB to bundle, ~2.84
MB → 2.87 MB total).
Naming
------
Mirrors the existing `websocket-${triplet}.node` convention (flat
dir under `runtime/native/`, dash-separated `<platform>-<arch>`).
Adds a `v<abi>` segment because better-sqlite3 is NOT N-API — one
binary per Node ABI. Naming:
better-sqlite3-v127-darwin-arm64.node Node 22 / macOS arm
better-sqlite3-v127-darwin-x64.node Node 22 / macOS intel
better-sqlite3-v127-linux-arm64.node Node 22 / Linux arm
better-sqlite3-v127-linux-x64.node Node 22 / Linux x64
better-sqlite3-v127-win32-x64.node Node 22 / Windows x64
better-sqlite3-v137-... (5) Node 24 / same 5 hosts
Total: 10 binaries × ~1.9 MB = ~19 MB committed. Aligned with the
existing native-vendoring footprint (websocket ~2 MB × 5, snowluma-
hook ~10 MB × Windows + Linux, ffmpeg ~10-30 MB × 4).
What changes for consumers
--------------------------
Source-side: nothing. `import Database, { type Database, type
Statement } from '@snowluma/sqlite'` is a drop-in for the previous
`import Database from 'better-sqlite3'`. The wrapper re-exports the
same types and the `Database` callable factory has the same
overload set.
Runtime: `node` finds the binding at
`<dist|repo>/native/better-sqlite3-v${process.versions.modules}-
${process.platform}-${process.arch}.node`. If the ABI doesn't
match a vendored binary, the wrapper throws a clear error pointing
at `tools/fetch-sqlite-prebuilts.mjs` with the missing ABI/triplet.
Bumped better-sqlite3 from 11.10.0 → 12.10.0 because v11 only had
prebuilt up to Node ABI v127 (no v137 = no Node 24). v12.10.0
ships both. Both versions are API-compat (the breaking changes
between v11 and v12 were either internal or in error-handling
paths SnowLuma doesn't exercise).
Verification
------------
- pnpm -r typecheck (12 projects): clean
- @snowluma/core test: 302/302
- @snowluma/onebot test: 250/250 (552/552 combined, unchanged from
the perf-series baseline)
- Bench numbers preserved — wrapper indirection is sub-μs:
storeMeta ~11 μs, storeEvent ~17 μs, findMeta hit ~1.1 μs (all
within noise of the post-RoadMap-#5 measurements).
- Vite build clean, bundle = 2.87 MB / 230 KB gzip
- `dist/index.mjs` no longer contains a `node:sqlite` import (it
did before — media-store hadn't migrated; now neither it nor
message-store reach into the Node builtin).
Bonus side-fix: `packages/onebot/src/media-store.ts` also moved
off `node:sqlite` (caught by the post-build bundle grep — the
file was using `DatabaseSync` + `StatementSync` from the builtin
even though it had already been written to cache its prepared
statements). Its hot paths now go through the same wrapper.
`pnpm install --frozen-lockfile` in CI rejected the lockfile after
998eba2 added `better-sqlite3` to packages/runtime/package.json
without bumping the lock. Running `pnpm install` regenerates the
`packages/runtime: { dependencies: { better-sqlite3: ... } }` block
plus the resolved version pin. No code change — purely the lockfile
catching up to the manifest.
Followup to 0b6541c. That commit added `better-sqlite3` as a
workspace dependency and marked it as a vite external — meaning
the bundled `dist/index.mjs` does `require('better-sqlite3')` at
runtime instead of inlining its JS wrapper. Without the binding
+ wrapper present in the production archive, every shipped
SnowLuma would crash on first SQLite op.
The fix is in three small pieces:
1. `packages/runtime/package.json` — declare `better-sqlite3` as a
runtime dep. `vite-plugin-cp` copies this manifest into
`dist/package.json` during build (see `runtimeDistFiles` in
`packages/core/vite.config.ts`), so the release workflow's
existing `npm install --omit=dev` step inside `dist/` picks it
up and compiles the native binding for the matrix target via
prebuild-install (with node-gyp fallback). This is the same
mechanism release.yml has used since v1.x — it was just empty
until now because the previous vite config bundled everything.
2. `.github/workflows/dev-build.yml` — mirror the
`Bundle runtime dependencies` step from release.yml. Dev-build
was packaging `dist/` straight after vite, which would have
shipped a broken artifact (no `dist/node_modules/`). Added the
`npm install --omit=dev` step before the tar/zip packaging
steps so dev-build archives carry the binding too.
3. `package.json` root — add `dist:install` script (just
`cd dist && npm install --omit=dev`) so local prod-mimic flows
work: `pnpm build && pnpm dist:install && pnpm dev:mode`. Not
chained into `pnpm build` itself to keep the watch-cycle fast
for users who only need the vite build output; the install
step adds ~17s.
Note on dev mode: `pnpm dev` continues to work unchanged — it
runs via tsx against workspace `node_modules/`, which already has
`better-sqlite3` compiled (from the workspace-level pnpm install).
Only the dist/-based prod-mimic path needed the explicit install.
Verification
------------
- `pnpm build` (with stubbed native binary): clean, dist/ has the
updated `dist/package.json` with the dependency declared
- `pnpm dist:install`: installs 38 packages, compiles
`dist/node_modules/better-sqlite3/build/Release/better_sqlite3.node`
- Smoke-test from `dist/`: `node -e "import('better-sqlite3')..."`
prints `OK: [ { id: 42 } ]`, confirming the binding loads + a
basic INSERT/SELECT roundtrip works.
CI matrix coverage: win-x64, linux-x64, linux-arm64 (release.yml +
dev-build.yml share the same matrix). Each builds its own native
binding during the install step — prebuild-install hits
better-sqlite3's prebuilt-binary registry for these three targets
(no source compile needed in the common case, falls back to
node-gyp if a prebuilt isn't available).
`PacketInfo.body` is typed as `Uint8Array` in `@snowluma/common/
protocol-types` and arrives as one — the `Buffer.from(uint8Array)`
wrap that fed it into `protobuf_decode<PushMsg>(...)` was a no-op
copy. `Buffer` is a `Uint8Array` subclass, and proton's decoder
accepts the parent type directly, so the wrap added one allocation
per incoming push packet without changing behavior.
Bench delta (parseMsgPush, pure decode):
group_message (text only) 0.29 μs/op → 0.25 μs/op (~1.2x)
group_message (5 mixed) 0.50 μs/op → 0.47 μs/op (~1.07x)
group_member_join 0.25 μs/op → 0.30 μs/op (within noise)
Small absolute gain — but `parseMsgPush` runs once per incoming
packet at the very front of the pipeline, so the saved allocation
compounds with the per-message GC churn. The text/mixed group-
message cases pick up cleanly; the join case sits in noise (it has
a smaller body so the Buffer wrap was cheap relative to total).
Verification: pnpm -r typecheck clean; 552/552 tests pass.
Replaces the experimental `node:sqlite` builtin with the stable
`better-sqlite3` wrapper across the two hot SQLite users — the
OneBot message-store and the bridge identity-service. While the API
surface is essentially identical (sync, prepared-statement-driven,
`Database`/`Statement` shape), better-sqlite3 (a) doesn't carry the
"ExperimentalWarning: SQLite is an experimental feature" baggage
that ships with `node:sqlite`, (b) has a more mature C++ binding
that consistently outperforms the builtin by ~30-50%, and (c)
encourages reusing `Statement` objects by design — exactly the win
the second half of this commit is after.
Why both at once
----------------
Caching prepared statements (was P1 in the RoadMap-#5 analysis) is
the largest single optimization opportunity on the SQLite path. The
old shape was the textbook SQLite anti-pattern:
// every call re-parsed the SQL
this.db.prepare(BIG_SQL_STRING).run(...);
Each `prepare(sql)` runs the full SQL parser + planner — for simple
inserts/updates/selects that dominates wall-clock cost. Doing both
the driver swap AND the statement caching in one commit lets the
benchmark numbers attribute the combined effect honestly; splitting
them would have double-charged the same disruption budget.
What changed code-wise
----------------------
**messageStore** — 8 distinct SQL templates, all now `readonly`
fields prepared once in the constructor:
- stmtStoreEvent — INSERT/UPDATE event row + JSON payload
- stmtStoreMeta — INSERT/UPDATE meta-only row
- stmtFindEvent — single-row SELECT by message_hash
- stmtFindMeta — single-row SELECT (full meta columns)
- stmtResolveReplyGroup, stmtResolveReplyPrivate
— 2 variants for the reply-id lookup
- stmtListEventsAnchored, stmtListEventsLatest
— 2 variants for /get_history_msg
**identity-service** — 25+ distinct statements. Used a Map-based
`pstmt(sql)` memoization helper rather than enumerating all 25 as
named fields (call sites stay readable; Map lookup is O(1) hash +
string-eq, negligible next to the SQL parse it replaces). The
helper short-circuits to the cached `Statement` on second-and-later
calls.
API differences from node:sqlite (handled in this commit):
- `import { DatabaseSync } from 'node:sqlite'`
→ `import Database from 'better-sqlite3'`
- `new DatabaseSync(path)` → `new Database(path)`
- `db.exec('PRAGMA journal_mode = WAL')`
→ `db.pragma('journal_mode = WAL')`
- `db.exec('BEGIN' / 'COMMIT' / 'ROLLBACK')` — kept as-is; both
drivers accept raw `exec()` for transaction control. The
`db.transaction()` higher-order wrapper is more idiomatic
but the existing manual control already works and changing
it would invalidate the `transaction()` helper's matched
try/catch shape.
vite build wiring:
- `node:sqlite` removed from the externals list
- `better-sqlite3` added — must stay external because it has a
native binding (`require('./build/Release/better_sqlite3.node')`)
that Vite can't bundle. Vendoring the prebuilt `.node` into
`packages/runtime/native/` is a follow-up packaging task; the
workspace `pnpm install` already places the binding under
`node_modules` so dev + tests work today.
Bench results (RoadMap #5 baseline → after)
-------------------------------------------
@snowluma/bridge — recv pipeline (with SQLite identity writes):
group_member_join 17.5 μs/op → 4.7 μs/op (~3.7x faster)
group_message text 0.42→0.42 μs (no path change)
group_message mixed 0.67→0.67 μs (no path change)
@snowluma/onebot — send pipeline:
messageStore.storeMeta 17.0 μs/op → 10.9 μs/op (~1.6x)
messageStore.storeEvent 23.2 μs/op → 18.2 μs/op (~1.3x)
messageStore.findMeta hit 5.4 μs/op → 1.3 μs/op (~4x)
messageStore.findMeta miss 3.7 μs/op → 0.7 μs/op (~5x)
messageStore.findEvent 3.8 μs/op → 1.7 μs/op (~2.3x)
Read paths gained the most because they're parse-bound (small SQL
+ short execution → the parser was most of the cost). Writes gained
less because the fsync/journal overhead on each commit still
dominates the parse savings. Combined send hot path (storeMeta +
storeEvent, called on every outbound message + the /get_msg-fix
self-event store) drops from ~40 μs to ~29 μs — about a 27%
reduction per message sent.
Verification
------------
- pnpm -r typecheck: all 11 projects clean
- @snowluma/onebot test suite: 250/250
- @snowluma/core test suite: 302/302
- Combined: 552/552 (unchanged baseline)
- Vite build (with stubbed native binary): clean, 2.84 MB / 223 KB
gzip (matches pre-Phase-2 envelope after removing the better-
sqlite3 inline-bundle attempt — externalizing it shaves the
~30 KB regression we saw mid-flight)
Follow-up (next commits in this series)
---------------------------------------
- Skip rememberGroupMemberIdentity DB write when the (uid, uin,
nickname, card) tuple is unchanged in the in-memory cache.
- Drop the `Buffer.from(pkt.body)` allocation in msg-push context.
- Synchronous fast-path for elementsToJson when no async resolver
is wired.
- Vendor `better-sqlite3` prebuilt `.node` into the runtime/native
layout for the production package step.
vitest-driven benches at `packages/bridge/bench/recv.bench.ts` and
`packages/onebot/bench/send.bench.ts`. Picks up proton's vite plugin
so call sites get the inlined codecs (running via tsx + proton
runtime-fallback would throw without a pre-built runtime map).
Run via `pnpm -F @snowluma/bridge bench` and
`pnpm -F @snowluma/onebot bench`.
What's measured
---------------
Receive chain:
- parseMsgPush: pure decode + dispatch (no SQLite, no event emit)
* group_message text ~ 0.29 μs/op (3.4M ops/sec)
* group_message 5 mixed ~ 0.50 μs/op (2.0M ops/sec)
* group_member_join ~ 0.25 μs/op (4.1M ops/sec)
- IncomingPacketPipeline.process: full pipeline (with SQLite via
rememberGroupMemberIdentity, BridgeEventBus emit)
* group_message text ~ 0.42 μs/op (2.4M ops/sec)
* group_message 5 mixed ~ 0.67 μs/op (1.5M ops/sec)
* group_member_join ~17.5 μs/op ( 57K ops/sec) ⚠
Send chain:
- parseMessage (OneBot input → MessageElement[])
* CQ string text ~ 0.31 μs/op
* CQ string mixed ~ 1.22 μs/op
* segment array text ~ 0.32 μs/op
* segment array 5 ~ 1.07 μs/op
- messageStore SQLite writes:
* storeMeta ~17.0 μs/op ( 59K ops/sec) ⚠
* storeEvent (~250B JSON) ~23.2 μs/op ( 43K ops/sec) ⚠
- messageStore reads:
* findMeta hit ~ 5.4 μs/op (186K ops/sec)
* findMeta miss ~ 3.7 μs/op (272K ops/sec)
* findEvent hit ~ 3.8 μs/op (262K ops/sec)
Headline finding
----------------
Pure decode/encode is already cheap (sub-μs). The real cost per
sent message is the SQLite write pair (storeMeta + storeEvent =
~40 μs). On receive, group_message itself does NOT trigger
identity writes; only join/leave/admin events do — but those go
through 4-6 db.prepare(sql).run/get(...) calls each, all re-parsing
SQL on every invocation (the canonical SQLite anti-pattern).
The follow-up commits in this series target:
1. Replace `node:sqlite` (experimental, API may shift) with
`better-sqlite3` (stable, sync, ~30-50% faster wire) + cache
prepared statements as readonly fields. Single commit, both
wins together — better-sqlite3's API encourages stmt caching
by design. Expected: storeMeta / storeEvent drop to ~3-5 μs,
group_member_join drops to ~3-5 μs.
2. Skip rememberGroupMemberIdentity DB write when the in-memory
uidByUin / uinByUid cache already has the mapping unchanged.
3. Drop the `Buffer.from(pkt.body)` allocation in msg-push
context (pkt.body is already Uint8Array; proton accepts it).
4. Make `elementsToJson` sync-fast-path when no async resolvers
are wired (saves per-element microtask overhead).
Each commit re-runs these benches and the message should quote the
before/after numbers so the deltas are auditable.
Note: tsx is NOT involved — vitest's bench mode owns the run, and
the proton vite plugin is configured in each `vitest.config.ts`.
Absolute numbers reflect the production code path.
Windows users reported "running a while then stops" with logs:
WARN [Hook] pipe error: PID=1312 err=read EPIPE
DEBUG [Bridge] session closed: UIN=752645868
INFO [OneBot] session closed: UIN=752645868
The user-side socket read fails with EPIPE (idle-timeout, transient
Windows named-pipe fault, or similar). The cascade:
1. hook-client's `socket.on('error')` → emits 'error'
→ hook-session logs "pipe error: PID=… err=read EPIPE"
2. socket then emits 'close' → bindClient's close handler runs
`tearDownClient()` and sets status to 'disconnected' (because
wasLoggedIn = true)
3. PipeWatcher's next tick polls `listLivePipes()` natively — and
the OS-level named pipe is STILL listed (DLL is still resident
in QQ.exe, it never closed its end). So no `pipe-down` →
`pipe-up` cycle ever fires.
4. hook-manager's `tick` reconcile loop only retried sessions
whose status was exactly 'connecting' (line 208 in
hook-manager.ts). A 'disconnected' session that should
reconnect was simply ignored.
Result: the session was stranded forever; QQ kept running, DLL
kept running, but SnowLuma never re-established its socket. The
only recovery was a full SnowLuma restart.
Fix: include `'disconnected'` in the retry predicate. `onPipeUp` is
idempotent (it checks `isClosed` / `!connected` internally and rebuilds
the socket pair from scratch) so we can safely call it from the
tick loop every ~1.5s until either the reconnect lands or the
watcher reports a genuine pipe-down.
No behavior change for sessions already in any other state — only
the 'disconnected' branch gains the auto-retry.
#6 was the "API层挂到ctx" item — Core side delivered the 13 typed
Api classes back in the e8d1af4...f4c6838 commit series; this turn
finished the OneBot side via the 4 ctx slim-down commits
(cb698d2 / 4c4ce60 / 8bf2ff3 / d983635).
ApiActionContext shrank from 90+ fields → ~30. Removed surfaces:
- groupAdmin / groupFile / groupAlbum / friend / interaction /
message / profile / web — all moved to direct
`ctx.bridge.apis.<area>.method()` invocations.
Kept surfaces (real composition, not pass-through):
- instance state: bridge / getLoginInfo / isOnline / getMessage*
- module helpers: sendXxxMessage / sendXxxForwardMsg / forwardSingle /
deleteMessage / setEssenceMsg / setMsgEmojiLike / handleGroupRequest
- cache-backed reads: getFriendList / getGroupList / getGroupInfo
/Member* / getStrangerInfo / getGroupFiles / get*MsgHistory /
handleGetGroupSystemMsg / getDownloadRKeys
- media store reads: getImageInfo / getRecordInfo
Full NapCat class-per-action conversion (TypeBox schemas / actionName
enum / auto-register decorator / 170 single-file classes) deliberately
not pursued — the metadata-driven design is meaningful only with
downstream doc/test tooling that consumes it, which SnowLuma doesn't
ship today. Marked as a follow-up under the same item if/when that
tooling appears.
Remove the remaining ~20 passthrough fields from ApiActionContext
spanning four Api areas — most were already dead (no caller) since
extended.ts had migrated to direct `ctx.bridge.apis.X` paths in
earlier #6 commits.
profile area:
- setProfile / setOnlineStatus / fetchCustomFace /
setGroupAvatar ── all already dead
- getProfileLike ── one live caller in extended.ts inlined
web area:
- getGroupHonorInfo / getGroupEssence / getGroupEssenceAll /
sendGroupNotice / getGroupNotice / deleteGroupNotice /
getCookiesStr / getCsrfToken / getCredentials /
forceFetchClientKey ── all already dead
groupAlbum area:
- getGroupAlbumList / uploadImageToGroupAlbum /
getGroupAlbumMediaList / commentGroupAlbumMedia /
deleteGroupAlbumMedia / likeGroupAlbumMedia ── all 7 live
callers in actions/group-album.ts inlined to
`ctx.bridge.apis.groupAlbum.<m>(...)`
friend area:
- setFriendRemark ── already dead
Behavior preserved: getProfileLike's `userId = 0 → self` semantics
keep working because ProfileApi.getLike uses `isSelf = !userId`
internally (0 and undefined are equivalent for that check); same
default args at the action site (`start = 0`, `count = 10`).
Group-album action handlers now wrap the typed Api return values
(GroupAlbumMediaResult, GroupAlbumCommentResult) with
`as unknown as JsonValue` for okResponse compatibility — the old
ctx wrapper was typed `Promise<any>` which silently hid the cast;
making the cast explicit doesn't change runtime.
Part 4 of the OneBot-side slim-down. 552/552 tests still green.
Remove 8 passthrough fields from ApiActionContext spanning three Api
areas:
friend area:
- handleFriendRequest (set_friend_add_request)
- handleDeleteFriend (delete_friend)
- setFriendRemark already kept the field name but now unused
interaction area:
- sendFriendPoke / sendGroupPoke (friend_poke, group_poke, send_poke)
- getEmojiLikes (was already dead — extended.ts used the direct
path; field removed)
message area:
- markGroupMsgAsRead / markPrivateMsgAsRead (already dead —
mark_msg_as_read sites use the module helper)
`handleGroupRequest` stays on ctx because `handleGroupAddRequest` is
a module helper that does the flag-parsing + group-request roster
lookup before routing to `bridge.apis.groupAdmin.setAddRequest` —
real composition, not a passthrough.
Behavior preserved: same flag parsing (`asString/asNumber/asBoolean`),
same `isGroup` flag flatten into `sendPoke(isGroup, peerUin, target?)`,
same default `block=false` for delete_friend.
Part 3 of the OneBot-side slim-down. 552/552 tests still green.
Remove 6 passthrough fields from ApiActionContext for the group-file
area (`uploadGroupFile / uploadPrivateFile / getGroupFileUrl /
createGroupFileFolder / getPrivateFileUrl / getGroupFileCount`).
Action sites (`actions/group-file.ts` and one site in
`actions/extended.ts`) now call `ctx.bridge.apis.groupFile.<method>`
directly.
`getGroupFiles` stays on the ctx because its module helper
(`getGroupFiles(bridge, groupId, folderId)` in `modules/contact-actions.ts`)
does identity-lookup enrichment of uploader/creator names — not a pure
passthrough.
Behavior preserved: same default values (`name = ''`, `folderId = '/'`,
`busId = 102`, `uploadFile = true`) — they were baked into the ctx
wrapper before, now they're explicit in the action site (`asString`
returns `''`, `... || '/'`, `... || 102`, `asBoolean(..., true)`).
The result-unwrap (`fileId` extraction from `UploadFileResult`) moves
from the ctx wrapper into the action handler.
Part 2 of the OneBot-side slim-down. 552/552 tests still green.
Remove the 6 pure pass-through fields from `ApiActionContext` for the
group-admin area (`setGroupKick / setGroupKickMembers / setGroupBan /
setGroupWholeBan / setGroupLeave / setGroupRemark`). All 5 call sites
in `actions/group-admin.ts` now invoke `ctx.bridge.apis.groupAdmin.<m>`
directly. `setGroupRemark` had zero remaining callers (extended.ts
was already on the direct path) so the field is simply deleted.
Part 1 of RoadMap #6 OneBot-side slim-down. Core side's typed Api
hub (bridge.apis.X) has been in place since the #6 commit series;
OneBot actions were still routing through a 90+ field bag-of-
functions on `ApiActionContext`. Most of those fields were 1:1
shims like `setGroupKick: (g,u,r) => bridge.apis.groupAdmin.kickMember(g,u,r)` —
pure indirection with no composition logic. This commit kills the
group-admin chunk; the friend / interaction / profile / web / album /
groupFile / message chunks land in follow-up commits.
Behavior preserved byte-for-byte: same parameter parsing
(`asNumber/asString/asBoolean`), same default values, same 1800s
mute fallback, same error responses. 552/552 tests still green.
Path follow-up to the 4-package split — the action registrations
moved from `packages/core/src/onebot/actions/` to
`packages/onebot/src/actions/` in Phase 3. The test was failing with
ENOENT on the old path before reaching the actual assertion. Note
that this test has a separate pre-existing failure (it imports a
non-exported `SNOWLUMA_ACTIONS` symbol from the SDK); the path fix
just clears the first of the two errors.
Phase 3 of the 4-package split (RoadMap #3). Moves the entire
`packages/core/src/onebot/` subtree (43 source files + 20 test files
spanning network adapters, action handlers, event converters, message
parser, message store, media store, instance + manager) into the new
`@snowluma/onebot` workspace package. The remaining `@snowluma/core`
now hosts only the api-layer (Bridge class + 13 Api classes), the
hook tooling, the WebUI server, and the runnable `index.ts`.
Why
---
- The OneBot adapter is the public-facing OneBot11 protocol surface;
it has its own version cadence and its own consumers (third-party
bots talking OneBot WS / HTTP). Splitting it lets that cadence move
independently of the Api-on-ctx layer.
- The two were sharing the `packages/core/` build pipeline only
because they happened to live in the same directory. Nothing in
the api-layer reaches into OneBot internals.
- Mirrors NapCat / Lagrange.OneBot's repo split (their OneBot adapter
is a separate assembly from the Core protocol library).
Layout
------
Moved via `git mv` (history preserved):
packages/core/src/onebot/* → @snowluma/onebot/src/<x>
packages/core/tests/onebot/* (6 files) → @snowluma/onebot/tests/
packages/core/tests/{message-parser,message-store,event-pipeline,
media-store,media-url-resolver,event-converter,
http-server-hot-reload,http-server-content-type,
api-handler-logging,message-id,group-msg-emoji-like,
config,media-indexer,network-manager}.test.ts (14 files)
→ @snowluma/onebot/tests/
What stays in @snowluma/core
----------------------------
- `bridge/{bridge,bridge-interface,bridge-context,manager}.ts`
- `bridge/apis/*` (the 13 typed Api classes)
- `hook/*` (debugger/injector — tooling for the core protocol layer)
- `webui/*` (admin UI server — application wiring, not the OneBot
adapter itself)
- `index.ts` (application entry that wires BridgeManager +
OneBotManager + HookManager + WebUI together)
Changes
-------
- New package `packages/onebot/` (package.json with subpath exports
mirroring legacy `core/src/onebot/<x>` 1:1, tsconfig.json,
vitest.config.ts with `SNOWLUMA_LOG_LEVEL=debug` env so the action-
dispatch logging tests see debug-level subscribers — copied verbatim
from core's vitest.config.ts).
- @snowluma/core grows new subpath exports for the api-layer files
OneBot's type-only imports need: `./bridge`, `./bridge-interface`,
`./bridge-context`, `./manager`, `./apis`.
- `@snowluma/onebot` depends on `@snowluma/bridge`, `@snowluma/common`,
`@snowluma/core`, `@snowluma/proto-defs`, `@snowluma/proton`,
`@snowluma/websocket`.
- `@snowluma/core` depends on `@snowluma/onebot` (for index.ts +
webui/server.ts wiring).
- 100+ import sites rewritten via sed:
* OneBot → core: `'../bridge/bridge'` → `'@snowluma/core/bridge'`,
`'../bridge/manager'` → `'@snowluma/core/manager'`,
`'../bridge/bridge-interface'` → `'@snowluma/core/bridge-interface'`,
`'@/bridge/bridge'` (vite path alias) → `'@snowluma/core/bridge'`.
* Core → OneBot: `'./onebot/manager'` → `'@snowluma/onebot/manager'`,
`'../onebot/config'` → `'@snowluma/onebot/config'`, etc.
* Test relative paths: `'../../src/onebot/<x>'` → `'../src/<x>'`
after the test file move (one level shallower).
- New `packages/onebot/src/env.d.ts` declaring `__APP_VERSION__` and
`__BUILD_WEBUI__` (the vite-injected globals `info.ts` reads).
Workspace cycle
---------------
core ↔ onebot is allowed by pnpm workspaces. The runtime direction
is one-way: core → onebot (index.ts constructs OneBotManager,
webui/server reads OneBot config). OneBot only reaches into core for
TYPES (Bridge, BridgeInterface, BridgeManager, ClientKeyInfo,
DownloadRKeyInfo); those imports use `import type` so they compile
out at runtime and don't introduce a real cycle.
Verification
------------
- Full workspace `pnpm -r typecheck`: all 11 projects clean.
- `@snowluma/core` test suite: 302/302 pass (33 test files).
- `@snowluma/onebot` test suite: 250/250 pass (20 test files;
pre-existing `network-manager.test.ts` native-addon failure
unchanged — same baseline as before the split).
- Combined: 552/552 — identical pass count to the pre-Phase-3
baseline.
- Vite build with stubbed native binary: clean, 2.84 MB bundle /
224 KB gzip (identical envelope).
Phase 2 of the 4-package split (RoadMap #3). Moves ~35 files —
events / event-bus / identity-service / packet-pipeline / element-
builder / bridge-oidb / qq-info / msg-push/* / highway/* / web/* +
the bridge-side formatters — out of `packages/core/src/bridge/`
into the new `@snowluma/bridge` workspace package. Everything that
translates QQ wire bytes ↔ typed events/elements now lives there.
Why
---
- `packages/core/src/bridge/` was actually two layers: a low-level
"protocol decoder + I/O" set (msg-push, highway, packet-pipeline,
identity, element-builder) AND the Api-class host (bridge.ts +
apis/*). The Api layer can't move without the protocol layer
moving first, but the two had grown into one directory.
- Bridge-internal consumers (highway uploaders, OIDB envelope
helper, element-builder, msg-push parsers) only ever needed
`bridge.identity` + `bridge.sendRawPacket` + the upload-metadata
cache. Splitting them out lets that minimal surface live in the
bridge package as `BridgeContext` while the api-layer's extended
context (with `apis: ApiHub`) stays in @snowluma/core.
What stays in @snowluma/core (apis layer):
- bridge.ts ── the god-class that composes the protocol
building blocks + mounts apis
- bridge-interface.ts ── public façade for OneBot consumers
- manager.ts ── per-uin BridgeManager hub
- apis/* ── the 13 typed Api classes
- bridge-context.ts (NEW) ── extends @snowluma/bridge's slim
BridgeContext with `apis: ApiHub` so
the 13 Api classes keep their typed
`this.ctx.apis.X.method()` access.
Layout
------
Moved via `git mv` (history preserved):
events / event-bus / identity-service / packet-pipeline /
element-builder / bridge-oidb / qq-info / msg-push/* /
highway/* / web/* → @snowluma/bridge/<sub>
utils/event-format.ts → @snowluma/bridge/format.ts
(the last one renamed because the destination directory only has
bridge-related files; `format.ts` reads cleaner than `event-format`.
Listed as a rename in git's `RM` output — content unchanged.)
Layering fixes (functionality preserved, just type signatures)
--------------------------------------------------------------
- `element-builder.SendContext.bridge` → typed as `BridgeContext`
instead of `Bridge`. Reads only `bridge.identity` and the
upload-cache (both on BridgeContext); the concrete `Bridge`
instance still passes via free upcast.
- `bridge-oidb.runOidb` signature widened from `Bridge` to
`BridgeContext` — same reason.
- `highway/{highway-client,pipeline,image-upload,ptt-upload,
video-upload}.ts` — same.
- `format.ts::formatReply` parameter typed as a new local
`ReplyEventLookup` structural type (`{ findEvent(id): JsonObject |
null }`) instead of `MessageStore` from @snowluma/onebot. The
OneBot `MessageStore` is a structural superset; consumers pass
it through unchanged.
- JSON value types moved to a new `@snowluma/common/json` subpath
(consumed by format.ts) — `onebot/types.ts` re-exports them so
external `import { JsonValue } from '<…>/onebot/types'` paths
keep working.
- `UploadedFileMeta` interface moved from `core/src/bridge/bridge.ts`
into `@snowluma/bridge/bridge-context.ts` — element-builder + the
forward-builder both read the upload cache through BridgeContext,
so the type has to live in @snowluma/bridge. `bridge.ts` keeps
its re-export for back-compat.
Changes
-------
- New package `packages/bridge/` (package.json with per-file subpath
exports mirroring legacy `core/src/bridge/<x>` layout 1:1,
tsconfig.json, typecheck script).
- 35 `.ts` files moved via `git mv` (3 files counted by git as
RM — rename + modify because Bridge → BridgeContext type swap).
- 150+ import sites rewritten across `packages/core/src` and
`packages/core/tests`: `'../bridge/<x>'`, `'../../bridge/<x>'`,
`'../src/bridge/<x>'`, `'@/bridge/web/<x>'`, and vitest
`vi.mock(...)` literals all collapse to `@snowluma/bridge/<x>`.
- `@snowluma/core` depends on `@snowluma/bridge` (workspace:*).
- `@snowluma/bridge` depends on `@snowluma/common`,
`@snowluma/proto-defs`, `@snowluma/proton`.
- `packages/core/src/utils/` directory removed (empty).
Verification
------------
- Full workspace `pnpm -r typecheck`: all 10 projects clean.
- core test suite: 552 passed / 552 total (pre-existing
websocket-darwin-arm64.node addon failure unchanged — same
baseline as the previous refactor commits).
- Vite build (with stubbed native binary): clean — 143 modules,
2.84 MB bundle / 224 KB gzip, identical envelope to the
pre-split build.
Phase 3 (next): OneBot + WebUI move into @snowluma/onebot. The
runnable `index.ts` stays in @snowluma/core as the application
entry, importing `OneBotManager` from `@snowluma/onebot`.
Phase 1 of the 4-package split called out in RoadMap #3. Moves the
"infrastructure" leaves — files with zero business dependencies that
@snowluma/bridge, @snowluma/core, and @snowluma/onebot all consume —
into a dedicated workspace package. Mirrors what #4 (proto-defs)
did for wire-protobuf definitions.
Why
---
- Cleaner layering: these were never bridge- or onebot-specific.
Logger / hex codec / runtime config sit at the bottom of every
module's import graph; giving them their own package makes that
graph readable and prevents future leaks the other direction.
- Sets up #3's bridge + onebot extractions: those need a clean leaf
to depend on. Without this, every cross-package import would have
to re-export through core, which defeats the split.
- Mirrors @snowluma/proto-defs layout — per-file subpath exports
(`@snowluma/common/logger`, `@snowluma/common/hex`, …) keep import
sites unambiguous and let bundlers tree-shake aggressively.
Layout
------
Moved (via `git mv` — history preserved):
packages/core/src/utils/logger.ts → @snowluma/common/logger
packages/core/src/utils/hex.ts → @snowluma/common/hex
packages/core/src/utils/log-file-transport.ts → @snowluma/common/log-file-transport
packages/core/src/utils/log-summary.ts → @snowluma/common/log-summary
packages/core/src/protocol/packet-sender.ts → @snowluma/common/packet-sender
packages/core/src/protocol/types.ts → @snowluma/common/protocol-types
packages/core/src/common/runtime.ts → @snowluma/common/runtime
Not moved (deferred to Phase 2): `packages/core/src/utils/event-format.ts`
— it has reverse imports on `bridge/events`, `bridge/identity-service`,
`onebot/message-store`, `onebot/types`. It moves into @snowluma/bridge
in Phase 2, with the MessageStore parameter decoupled via a structural
type so bridge doesn't end up depending on onebot.
Changes
-------
- New package `packages/common/` (package.json, tsconfig.json — no
src/index.ts barrel, callers use the subpath exports directly to
avoid pulling in `node:fs` when only the hex codec is needed).
- 7 `.ts` files moved via `git mv`.
- 50+ import sites rewritten via sed across `packages/core/src` and
`packages/core/tests`. Old shapes (`../utils/logger`,
`../../protocol/types`, `./common/runtime`, `../src/utils/hex`)
all collapse to `@snowluma/common/<sub>`.
- `@snowluma/core` depends on `@snowluma/common` (workspace:*).
- `packages/core/src/{protocol,common}/` directories removed (empty).
Verification
------------
- core typecheck: clean
- common typecheck: clean
- Full workspace `pnpm -r typecheck`: all 9 projects clean
- core test suite: 552 passed / 552 total (pre-existing
websocket-darwin-arm64.node addon failure unchanged — same baseline
as the previous refactor commits)
- Vite build with stubbed native binary: clean (143 modules, 2.84 MB
bundle, 224 KB gzip — same size envelope as before)
Note: `utils/event-format.ts` is the only file remaining under the
old `utils/` namespace. It moves into @snowluma/bridge alongside the
events / identity-service / packet-pipeline trio in Phase 2.
- #2 (Proton ts+map fallback for unbundled debug) — landed in
`994633e feat(proton): resolve bare specifiers via TypeScript module
resolution` + `6c7e56d refactor(proto-defs)`. Bare specifiers like
`@snowluma/proto-defs/oidb` now resolve to the original `.ts` source
through `ts.resolveModuleName` (Bundler mode), so tsx/node + vite
share the same import surface.
- #4 (proto definitions in their own package) — landed in
`6c7e56d refactor(proto-defs)`. Moved 13 proto `.ts` files (~3.3k
LOC) into the new `@snowluma/proto-defs` workspace package with
per-file subpath exports; 44 call sites across core/tests rewritten.
- #6 (NapCat-style Api on ctx) — half done. Core side fully landed
through 13 sequential commits (3e5dca1 → f4c6838) — `bridge.apis.<
area>.method()` covers all 13 areas, `BridgeInterface` is gone, the
`actions/*` directory is deleted. OneBot side is NOT done: actions
still receive an `ApiActionContext` (a flat bag of functions) and
call `ctx.bridge.apis.*` directly rather than going through a
dedicated OneBot Api class layer.
`set_msg_emoji_like` was failing with
"invalid ReqBody.EmojiType: value must be greater than 0" because
`OidbGroupReaction` had every field number off by one — `type` was at
field 4, but the server reads `EmojiType` at field 5. The mistake
covered all four fields:
field what was should be
───── ──────── ─── ─────────
2 groupUin 1 2
3 sequence 2 3
4 code 3 4
5 type 4 5
Cross-checked with Lagrange.Core V2's `OidbSvcTrpcTcp0x9082.cs` —
their definition starts at field 2 and runs through 7. The OIDB
envelope wraps the body at field 4, so the inner body's own fields
must start at 2 to avoid collision with the wrapper. (The previous
1..4 layout happened to encode SOMETHING wire-valid, just not what
the server's `OidbSvcTrpcTcp0x9082` validator expected.)
Also added the trailing `field6` and `field7` unused booleans that
Lagrange serialises as `false`. The server currently tolerates them
missing; including them keeps SnowLuma byte-identical with Lagrange
in case the validator gets stricter.
The reaction-type heuristic stays the same (`code.length > 3 ? 2 : 1`
— Lagrange uses the same `IsEmoji => Code.Length > 3` check in
`GroupAddReactionEvent.cs`).
`/get_msg` with a `message_id` returned by `send_*_msg` was failing
with "message not found" because the send-side only called
`cacheMessageMeta` (used by recall/delete), never `storeEvent`
(used by /get_msg lookup).
The QQ server sometimes echoes self-sent messages back through the
receive channel (which would populate `storeEvent` via the normal
event pipeline), but it's not reliable — Lagrange and NapCat both
work around this by persisting a local copy at send time. Lagrange
writes into Realm DB inside `SendMessageOperation.cs`; NapCat caches
in-memory via its msg service.
Mirror them: synthesise a `post_type: 'message_sent'` event from the
parsed `MessageElement[]` (converted back to OneBot segments via the
existing `elementsToOneBotSegments`) and write it directly into
`messageStore.storeEvent` — bypassing `dispatchEvent` so we don't
broadcast the synthetic event over the WS bridge (the QQ server's
own echo is the source of truth for that).
Wired into all five outbound paths:
- sendPrivateMessage (modules/message-actions.ts)
- sendGroupMessage
- sendGroupForwardMessage (the wrapping ARK card)
- sendPrivateForwardMessage
- forwardSingleMessage (both branches)
The helper is defensive: tests stub `messageStore` as
`{ findEvent: () => null } as any` without `storeEvent`, so the
helper checks for the function and bails quietly when absent.
Failure inside the helper is logged but never thrown — recall +
the send return value matter more than /get_msg lookup.
`send_forward_msg` with a `{type:'file', file_id}` segment to a GROUP
was sending a 0 B file (no name, no size, no md5/sha1) because
`makeGroupFileElem` read those fields directly off `MessageElement`
without falling back to `bridge.recallUploadedFile()`.
The c2c forward path in `apis/forward.ts::buildForwardPushBody`
already does this lookup (line ~126) — that's why forwarding to a
private chat worked but to a group didn't. Mirror it here.
OneBot11 callers typically thread only the file_id through (the
upload action returns just the id), so the cached metadata is the
only place size/md5/sha1/name come from. Without it the long-msg
payload encodes `GroupFileExtra { fileSize=0, fileName='', md5='',
fileSha='' }` and the receiver renders a "0 B" file bubble.
Final commit of the #6 NapCat-style Api refactor. Inlines the four
files under `web-actions/` (cookies / group-essence / group-honor /
group-notice) into `apis/web.ts::WebApi`. Both the `actions/` and
`web-actions/` directories are now empty and deleted from the tree.
Method renaming (Api namespace already says "web"):
forceFetchClientKey → forceFetchClientKey (kept — unique name)
getCookiesStr → getCookiesStr (kept — disambiguates from
the new public getCookies)
getCsrfToken → getCsrfToken
getCredentials → getCredentials
getGroupEssence → getEssence
getGroupEssenceAll → getEssenceAll
getGroupHonorInfo → getHonorInfo
sendGroupNotice → sendNotice
getGroupNotice → getNotice
deleteGroupNotice → deleteNotice
Plus a new public `getCookies(domain)` on WebApi so GroupAlbumApi can
reach the cookie-acquisition flow through `this.ctx.apis.web.getCookies`
rather than reaching into a private helper. Internal helpers
(`getPSkey` / `getSKey` / `getBknFromSKey`) remain file-private since
they're only used by the publicly-exposed methods above.
Cleanup performed in this same commit:
• `actions/shared.ts` → moved to `apis/shared.ts` (only file left in
actions/; it's a small helper module used by 4 Api classes).
• `actions/` directory deleted entirely.
• `web-actions/` directory deleted entirely.
• `BridgeInterface` slimmed to `BridgeContext + activePid` (the only
non-Api field OneBot consumers reach into). The 70-line list of
method signatures is gone — every method type now comes from the
`ApiHub` definition in `bridge-context.ts`.
• `bridge.ts` no longer imports/wraps any action functions. Its
public class is just the per-account state holder + `apis: ApiHub`.
Callers updated: `instance-context.ts`, `actions/extended.ts`,
`actions/group-info.ts`. Tests under `tests/web-actions/` deleted —
those tested file-private helpers (`getPSkey`/`getSKey`/`getBknFromSKey`)
that are no longer reachable from outside; the public WebApi surface
is exercised through OneBot integration tests in `extended-actions.test.ts`.
552/552 remaining tests pass. (Test count down 35 from the deleted
web-actions tests; production behaviour unchanged.)
This concludes the #6 refactor. The 12 Api hubs that the OneBot side
can reach via `bridge.apis.*`:
message / contacts / groupAdmin / groupFile / groupAlbum
interaction / friend / profile / forward / misc / extras / web
Inlines `actions/extras.ts` into `apis/extras.ts::ExtrasApi`. Covers
the napcat-parity Tier-2 surface: group todo CRUD (0xF90_1/2/3),
stranger online/ext status decode (0xFE1_2), and AI voice list +
synthesis (0x929D / 0x929B).
`StrangerStatus`, `AiVoiceChatType`, `AiVoiceCategory`, `AiVoiceItem`
are now exported from `apis/extras.ts` and re-exported through
`bridge.ts` for backwards compatibility (the OneBot side imports
them via `@snowluma/core`).
No renaming — the names already read cleanly under `apis.extras.X`.
The `fetchAiVoiceList` / `fetchAiVoice` chatType parameter is widened
to `AiVoiceChatType | number` because the OneBot side passes a raw
number from JSON. The wire encoder is happy with any integer; the
strict enum just gives autocompletion at call sites that have it.
Callers updated: `actions/extended.ts` (7 sites).
Tests rewritten:
- `extras.test.ts` → uses `new ExtrasApi(bridge as any).method(...)`
and the it.each dispatch switches to method-name strings.
- `extended-actions.test.ts` APIS_ROUTING gains the extras block.
587/587 tests pass.
Inlines `actions/misc.ts` into `apis/misc.ts::MiscApi`. The Api holds
the methods that didn't naturally group into any other area:
translation, mini-app ARK card builder, inline-keyboard callback,
group sign-in.
No renaming — these names are already descriptive at the call site
under `apis.misc.X`.
Callers updated: `actions/extended.ts` (4 sites).
Tests rewritten to use `new MiscApi(bridge as any).method(...)`.
587/587 tests pass.
Inlines `actions/forward.ts` into `apis/forward.ts::ForwardApi`. The
file is the largest unmoved one — 475 lines covering long-message
upload with NapCat-style piggyback for nested {type:"node"} chains,
plus the cached fetch side.
The module-scoped `forwardResCache` Map stays at file scope rather
than as an instance field. Forward res_ids are globally unique and
an outbound upload often gets queried back through `fetch` on a
different Bridge instance (different OneBot connection hitting the
same account) — NapCat's behaviour relies on the cache being shared
across the process.
Method renaming (Api namespace already says "forward"):
uploadForwardNodes → upload
fetchForwardNodes → fetch
The private `uploadForwardNodesRecursive` becomes
`this.uploadRecursive(...)` — same body, threads through `this.ctx`.
Callers updated: `modules/message-actions.ts` (4 sites).
Tests rewritten:
- `forward.test.ts` → `new ForwardApi(bridge as any).upload/fetch(...)`
- `forward-file.test.ts` → same pattern
- `forward-nested.test.ts` → mocks `apis.forward.upload` instead of
flat `bridge.uploadForwardNodes`
587/587 tests pass.
Inlines `actions/profile.ts` into `apis/profile.ts::ProfileApi`. The
file covers personal profile (nickname / long-nick / personal note),
online status (regular + DIY with custom face/wording), avatars
(personal + group via highway), input-status, likes (received from
others), unidirectional friend list, and custom face roaming.
Method renaming (Api namespace already says "profile"):
getProfileLike → getLike (only obvious shortening; rest keep
their `set*`/`fetch*` prefixes because
they're already minimal at the call
site under `apis.profile.X`)
Callers updated: `instance-context.ts`, `actions/group-admin.ts`,
`actions/extended.ts`. The extended-actions test gained a sizable
`APIS_ROUTING` block covering profile/interaction/friend (all of the
late-stage Api hubs need auto-promotion now), so legacy tests that
stub `setDiyOnlineStatus`/`setOnlineStatus`/`deleteFriend`/etc as flat
methods keep working.
Tests rewritten to use `new ProfileApi(bridge as any).method(...)`.
587/587 tests pass.
Inlines `actions/friend.ts` into `apis/friend.ts::FriendApi`. The
roster READ side (fetchFriendList) stays on ContactsApi where it
naturally lives next to fetchGroupList — the friend/group rosters
share the same pipeline.
Method renaming (Api namespace already says "friend"):
setFriendAddRequest → handleRequest (accept/reject UID-or-flag)
deleteFriend → delete (with cache refresh)
setFriendRemark → setRemark
`delete` still does the post-OIDB best-effort
`apis.contacts.fetchFriendList()` refresh to evict the stale entry.
Callers updated: `instance-context.ts`, `actions/extended.ts`.
Tests rewritten to use `new FriendApi(bridge as any).method(...)`.
587/587 tests pass.
Folds the entire `actions/interaction.ts` (sendPoke / sendLike /
setGroupReaction / getEmojiLikes) plus the lone-survivor
`setGroupEssence` from `actions/group-message.ts` into
`apis/interaction.ts::InteractionApi`. Both action files deleted —
the recall + markRead halves of group-message were already absorbed
into MessageApi back in commit 1.
Skipping the planned standalone GroupMessageApi commit: with only one
method left (`setGroupEssence`), giving it its own Api class would be
pure overhead. Essence is conceptually an "interaction" anyway (mark
a message as essence is parallel to "react with an emoji").
Method renaming (Api namespace already says "interaction"):
sendPoke → sendPoke (no rename — already minimal)
sendLike → sendLike
setGroupReaction → setReaction
setGroupEssence → setEssence
getEmojiLikes → getEmojiLikes (no rename — read-side, fine)
Callers updated: `instance-context.ts`, `modules/message-actions.ts`,
`actions/extended.ts`. Tests `interaction.test.ts` rewritten to use
`new InteractionApi(bridge as any).method(...)` and gained a
`setEssence` test. `group-message.test.ts` rewritten to target
MessageApi.recall* / markRead* methods that were already moved.
587/587 tests pass.
Inlines `actions/group-album.ts` (OIDB sendRawPacket via QunAlbum.trpc.*)
and `web-actions/group-album.ts` (HTTP cookie-based) into
`apis/group-album.ts::GroupAlbumApi`. Both action files deleted. Pure
HTTP helpers in `web/group-album.ts` stay where they are — they're
transport-layer code.
Method renaming follows the now-standard "drop the redundant suffix"
rule (the Api namespace already says `groupAlbum`):
getGroupAlbumList → list (HTTP)
uploadImageToGroupAlbum → upload (HTTP slice-upload)
getGroupAlbumMediaList → getMediaList
commentGroupAlbumMedia → comment
likeGroupAlbumMedia → like
deleteGroupAlbumMedia → delete
Callers updated: `instance-context.ts`. `web-actions/index.ts` no
longer re-exports the deleted album functions. No tests existed for
this surface area, so no test churn.
587/587 tests pass.
Inlines `actions/group-file.ts` into `apis/group-file.ts::GroupFileApi`,
deletes the old action file, removes the matching 17 facade methods
off `Bridge`, and slims `BridgeInterface` accordingly.
Method renaming follows the same "strip the redundant suffix" rule we
applied to GroupAdminApi:
uploadGroupFile → upload
uploadPrivateFile → uploadPrivate
sendGroupFileMessage → publish (OIDB 0x6d9_4)
fetchGroupFiles → list
fetchGroupFileCount → getCount
fetchGroupFileUrl → getUrl
fetchPrivateFileUrl → getPrivateUrl
fetchGroupPttUrlByNode → getPttUrl
fetchPrivatePttUrlByNode → getPrivatePttUrl
fetchGroupVideoUrlByNode → getVideoUrl
fetchPrivateVideoUrlByNode → getPrivateVideoUrl
deleteGroupFile → delete
moveGroupFile → move
createGroupFileFolder → createFolder
deleteGroupFileFolder → deleteFolder
renameGroupFileFolder → renameFolder
`upload`'s atomic upload+publish flow now calls `this.publish(...)`
directly instead of going through `bridge.sendGroupFileMessage`, and
`uploadPrivate` calls `this.ctx.apis.message.sendC2cFile(...)`.
Callers updated: `instance-context.ts`, `media-url-resolver.ts`,
`actions/group-file.ts` (onebot), `actions/extended.ts`,
`modules/{contact,media,message}-actions.ts`.
Tests: `group-file.test.ts` rewritten to use
`new GroupFileApi(bridge as any).method(...)`. The "verify publish was
called" assertions now use `vi.spyOn(api, 'publish').mockResolvedValue()`
since `publish` is an instance method on the same Api. `_helpers.ts`
gains `mockGroupFileApi()` for cross-Api callers and drops the flat
`sendGroupFileMessage` shim. `media-url-resolver.test.ts` and
`send-group-file.test.ts` switched to `bridge.apis.groupFile.*`; the
extended-actions `APIS_ROUTING` map now carries a `[area, newName]`
tuple so renamed methods auto-promote.
587/587 tests pass. The network-manager file remains as the only
failing test file (pre-existing infrastructure issue unrelated to #6).
Third of 13 commits. Folds the previous `actions/group-admin.ts`
plus the matching Bridge facade methods into a typed `apis.groupAdmin`
hub.
Methods (14, all renamed to drop the redundant `Group` prefix once
the `apis.groupAdmin` namespace makes it implicit):
muteGroupMember → apis.groupAdmin.muteMember
muteGroupAll → apis.groupAdmin.muteAll
setGroupAddOption → apis.groupAdmin.setAddOption
setGroupSearch → apis.groupAdmin.setSearch
setGroupAddRequest → apis.groupAdmin.setAddRequest
kickGroupMember → apis.groupAdmin.kickMember
kickGroupMembers → apis.groupAdmin.kickMembers
leaveGroup → apis.groupAdmin.leave
setGroupAdmin → apis.groupAdmin.setAdmin
setGroupCard → apis.groupAdmin.setCard
setGroupName → apis.groupAdmin.setName
setGroupSpecialTitle→ apis.groupAdmin.setSpecialTitle
setGroupRemark → apis.groupAdmin.setRemark
getGroupAtAllRemain → apis.groupAdmin.getAtAllRemain
actions/group-admin.ts deleted. The corresponding `*_` alias imports
and `async xxx() { return xxx_(this, …); }` delegate methods on
Bridge are gone.
Caller updates
--------------
* onebot/instance-context.ts — 6 sites (the multi-method binding for
the OneBot action layer).
* onebot/actions/extended.ts — 8 sites including `getAtAllRemain`.
* onebot/actions/group-admin.ts — all 6 onebot action handlers.
* onebot/modules/request-actions.ts — `setGroupAddRequest`.
Test updates
------------
* tests/actions/group-admin.test.ts — was importing the deleted
`* as admin` module and calling `admin.muteGroupMember(bridge, ...)`.
Switched to `new GroupAdminApi(bridge as any).muteMember(...)` —
same wire validation, just constructs the real Api class once per
call (the Api is stateless so it's effectively free).
* tests/onebot/request-actions.test.ts — was stubbing
`setGroupAddRequest` flat on bridge. Updated to
`apis: { groupAdmin: { setAddRequest } } as any`.
Tests: 587/587 pass (network-manager native-addon failure unchanged).
Second of 13 commits decomposing Bridge. Moves the six "fetch the
roster / a profile / outstanding requests / download rkeys" methods
off Bridge and onto a new `apis.contacts.*`.
Methods moved
-------------
* fetchFriendList — OIDB 0xfd4_1 + identity.rememberFriends
* fetchGroupList — OIDB 0xfe5_2 + identity.rememberGroups
* fetchGroupMemberList — OIDB 0xfe7_3 + identity.rememberGroupMembers
(includes the 60s TTL + per-group inflight
coalesce cache that prevents Tencent
risk-control from triggering)
* fetchUserProfile — OIDB 0xfe1_2 + identity.rememberUserProfile
* fetchGroupRequests — OIDB 0x10c0_{1,2}
* fetchDownloadRKeys — OIDB 0x9067_202
Cache fields moved
------------------
The two member-list throttle maps (`memberListInflight_`,
`memberListLastFetch_`) move from Bridge to `ContactsApi` as private
fields. Same TTL, same semantics — just owned by the Api class that
exposes the method.
Constructor ordering
--------------------
`buildApiHub(this)` now runs BEFORE `identity.setFetcher(...)` in the
Bridge constructor because the `fetchProfile` / `fetchGroupMemberList`
callbacks installed there reach into `this.apis.contacts.*`. With
eager construction this is safe; the alternative (pass a thunk that
forwards once apis is built) was strictly worse for readability.
bridge-contacts.ts removed
--------------------------
The file existed solely as the previous module-function delegate
target; ContactsApi inlines every function body so there's nothing
left to keep.
Caller-site updates
-------------------
* `bridge/actions/friend.ts` — `bridge.fetchFriendList()` →
`bridge.apis.contacts.fetchFriendList()`.
* `onebot/manager.ts`, `onebot/instance-rkey.ts`,
`onebot/modules/contact-actions.ts`, `modules/request-actions.ts`,
`actions/extended.ts` — same shape rewrite (6 method names).
Test plumbing
-------------
* `tests/actions/_helpers.ts` — `mockApiHub()` grows a `contacts`
field built by `mockContactsApi()`.
* `tests/bridge-member-identity.test.ts::RefreshingBridge` — was
`override async fetchGroupMemberList()`. After the move the method
lives on `this.apis.contacts`, not `this`. Switched to patching the
method on the constructed ContactsApi instance directly.
* `tests/actions/friend.test.ts` — `bridge.fetchFriendList` →
`bridge.apis.contacts.fetchFriendList`; the "refresh throws" branch
overrides via `bridge.apis.contacts.fetchFriendList = vi.fn(…)`.
* `tests/onebot/contact-actions.test.ts`, `extended-actions.test.ts`,
`request-actions.test.ts` — local `fakeBridge` helpers gained an
auto-promotion shim that rewrites flat method stubs (the pre-#6
test API) into the new `apis.<area>.method` shape. Keeps existing
test setup readable while the production code uses the new path.
Tests: 587/587 pass (same baseline; pre-existing network-manager
native-addon failure unchanged).
First of 13 commits decomposing the Bridge god-object into typed Api
classes following NapCat's `ctx.apis.XxxApi.method()` pattern. This
commit lays the foundation (BridgeContext, ApiHub, eager construction)
plus moves the message-send/recall/mark-read methods onto MessageApi.
Subsequent commits will move the other 12 areas (group admin, files,
profile, …) similarly.
Architecture
------------
* `bridge-context.ts` — new interface, the surface Api classes see.
Carries identity / events / apis / sendRawPacket / resolveUserUid /
next{Message,Client}Sequence helpers / upload meta cache. Replaces
the previous `BridgeInterface` for Api-class consumption (the
legacy interface still exists, just slimmed; full removal happens
in commit 13).
* `apis/index.ts` — `ApiHub` interface + `buildApiHub(ctx)` factory.
Each commit grows `ApiHub` by one entry; today only `message` is
populated.
* `apis/message.ts` — `MessageApi` with seven methods inlined from
the previous Bridge implementation:
sendGroup ← Bridge.sendGroupMessage
sendPrivate ← Bridge.sendPrivateMessage
sendC2cFile ← Bridge.sendC2cFileMessage
recallGroup ← actions/group-message.ts::recallGroupMessage
recallPrivate ← actions/group-message.ts::recallPrivateMessage
markGroupRead ← actions/group-message.ts::markGroupMessageRead
markPrivateRead ← actions/group-message.ts::markPrivateMessageRead
(Names trimmed: the `apis.message` prefix already signals the
context, so `apis.message.sendGroupMessage` would be redundant.)
Bridge changes
--------------
* Removed the 7 methods listed above (moved to MessageApi).
* Removed unused imports + `SEND_MSG_CMD` constant + `buildSendElems`
+ `protobuf_encode/decode` (now used only inside MessageApi).
* Added `readonly apis: ApiHub` field, built eagerly in constructor.
* Promoted `nextMessageRandom` / `nextClientSequence` from private →
public (Api classes need them to build SendMessageRequest packets).
* `BridgeInterface` now also lists `apis: ApiHub` + the two
generators; the 7 deleted method signatures are gone.
Caller-site updates (~9 files)
------------------------------
* `bridge/actions/group-file.ts` — `bridge.sendC2cFileMessage(...)`
→ `bridge.apis.message.sendC2cFile(...)`.
* `onebot/instance-context.ts` — markGroupMsgAsRead / markPrivateMsgAsRead
bindings now route through `apis.message.markGroup/PrivateRead`.
* `onebot/modules/message-actions.ts` — every send/recall site
rerouted; `typeof ref.bridge.sendXxx` type refs also updated.
* `onebot/actions/extended.ts` — same.
Tests (~5 files)
----------------
* `tests/actions/_helpers.ts` — `mockBridge()` grows an `apis` field
built by `mockApiHub()`; the previous flat `sendGroupMessage` etc.
vi.fn stubs are replaced with `mockMessageApi()`.
* All test files using direct `bridge.sendXxx` / `bridge.recallXxx` /
`bridge.markXxxAsRead` calls or stubs updated to `bridge.apis.message.*`.
* No behaviour changes — 587/587 pass (same baseline; pre-existing
network-manager native-addon failure unchanged).
The `markGroupMsgAsRead` / `markPrivateMsgAsRead` Bridge methods were
calling the wrong underlying implementations because the alias names
on the import line were swapped:
- `markPrivateMessageRead as markGroupMsgAsRead_` meant calling
`bridge.markGroupMsgAsRead(groupId, …)` actually fired the c2c
(private) read-report wire shape with `groupId` shoved into the
`userId` slot — the server then resolved a uid for what was
really a groupId and posted to the wrong route.
- `markGroupMessageRead as markPrivateMsgAsRead_` was the mirror:
`bridge.markPrivateMsgAsRead(userId, …)` fired the group read-
report shape with `userId` in the `groupUin` field.
Realigned to the intended pairing. The underlying implementations
in `actions/group-message.ts` are already covered by
`tests/actions/group-message.test.ts` (asserts both hit
`SsoReadedReport` with their proper wire shapes); they pass
unchanged because they always tested the action-layer functions
directly, never the Bridge facade where the swap lived.
Caught while planning the #6 Api-on-ctx refactor — preserving the
swap into the new MessageApi would have carried the bug forward.
Move `packages/core/src/bridge/proto/proton/*.ts` (13 files, ~3.3k
LOC) into a new `@snowluma/proto-defs` workspace package. The proton
spike landed in the previous commit means bare-specifier imports
(`@snowluma/proto-defs/oidb`, `…/message`, …) now resolve correctly
through proton's vite plugin, so call-site replacement still fires.
Why
---
- Lets downstream consumers share the same wire
definitions without copy-pasting them — multiple workspace packages
can now depend on `@snowluma/proto-defs` directly.
- Trims `@snowluma/core`'s surface: the bridge no longer owns the
protocol schema, only its consumers.
- Sets up future #5 (`message-parsing perf`) and #6 (`Api-on-ctx
refactor`) — both want a thinner core.
Layout
------
Per-file subpath exports (mirrors the legacy `proto/proton/<sub>`
shape 1:1). The barrel `index.ts` intentionally skips `highway` and
`oidb-actions/media` because the two files share six NTV2-prefixed
type names — `export *` would silently drop one side. Subpath imports
are unambiguous, which is also why every call site in core uses them.
Changes
-------
- New package `packages/proto-defs/` (package.json, tsconfig.json,
src/index.ts).
- 13 `.ts` files moved via `git mv` to preserve history.
- 44 import sites across 26 source files + 15 tests rewritten via sed
from `./[…/]proto/proton/<sub>` → `@snowluma/proto-defs/<sub>`.
- `@snowluma/core` depends on `@snowluma/proto-defs` (workspace:*).
Verification
------------
- proto-defs typecheck: clean
- core typecheck: clean
- core test suite: 587 passed (same baseline as before the refactor;
one failure is the pre-existing websocket native addon, unrelated)
- proton test suite: 99 passed (8 files including the new
cross-package.test.ts from the spike)
- Full workspace `pnpm -r typecheck`: all 8 projects clean
Note: proton's `dist/index.js` MUST be rebuilt for the vite plugin to
pick up the bare-specifier resolution. The previous commit's source
change is only effective after `pnpm -F @snowluma/proton build`.
`resolveModulePath` used to skip any specifier not starting with '.'
which meant proton's vite plugin only saw proto definitions that lived
in the same package as the call site. Trying to move definitions into
a sibling workspace package (e.g. `@snowluma/proto-defs`) caused those
imports to silently fail — the call-site type lookup found nothing
and the protobuf_encode<T> replacement never fired.
Add a bare-specifier branch that delegates to `ts.resolveModuleName`
with `moduleResolution: Bundler`. That covers monorepo workspaces,
npm packages, package.json `exports`, and tsconfig path aliases with
zero extra user configuration.
The relative-path branch is preserved byte-for-byte so existing
single-package consumers see identical behaviour. Resolution is
constrained to `.ts` source files (not `.d.ts`) because proton walks
interface AST to collect `pb<>` field tags, and generated declaration
files typically strip those generic arguments.
Per-process `ModuleResolutionCache` keeps the hot path (HMR rebuild)
from re-scanning node_modules every call.
Tests: new `cross-package.test.ts` builds a fake monorepo under
`os.tmpdir()` and exercises smoke / transform / round-trip / negative
paths. 99/99 proton tests pass; SnowLuma core regression unchanged
(587 baseline ⇄ 587 with change).
Delete an outdated comment block in fetchPrivateFileUrl that described receiverUid behavior (Lagrange.Core/NapCat and NTQQ fulllink timeout). No functional code changes were made aside from removing the explanatory comment; the surrounding logic (resolveSelfUid, void userId, and OIDB envelope creation) remains unchanged.
Update the debug optimization item to specify a Proton fallback plan: implement unpackaged debug with correct data directory and use TypeScript + map-based type extraction for tsx and Node.js, which will be stripped during normal Vite builds.
Standardize and reorganize imports, type usages and minor formatting across the bridge modules. This commit moves protobuf helpers, makeOidbEnvelope/runOidb, OidbBase and logger imports into consistent places, reorders and groups action/contacts exports in Bridge, removes or trims file-level comments, and fixes whitespace/logic ordering in several highway, element-builder and msg-push files. These are refactors and import/type adjustments across many files under packages/core/src (bridge, highway, msg-push, webui, utils, etc.) with no intended behavioral changes.
Add consistent indent rule to ESLint and normalize formatting/indentation across multiple files. Refactor RequestUtil: improve cookie extraction, redirect handling, and HttpGetJson/HttpGetText request flow; fix cookie string builder formatting. Fix uploadGroupNoticeImage promise/error handling and network request flow. Also apply minor style/refactor tweaks in bridge web APIs, onebot handlers, message-store SQL alignment, and Proton AST collector utilities to improve readability and correctness.
Add a repository .editorconfig and a root eslint.config.ts to standardize formatting and linting. Migrate packages/webui ESLint config to TypeScript (eslint.config.ts) with project-specific rules and tsconfigRootDir handling, and remove the old JS config. Update package.json to run ESLint directly (add lint and lint:fix) and add required ESLint/dev dependencies; also add jiti to packages/webui/package.json. Include a small formatting tweak to tsconfig.base.json.
Add support for resolving types re-exported with `export * from '...'`. Introduces extractExportAllSpecifiers and a new exportAllTypeSources map on ParsedFileEntry, populates it while parsing (recursively following export-all chains using the cache and an inProgress set to avoid cycles), and falls back to exportAllTypeSources when resolving imported type names. This allows types and generic templates exported through export-all declarations to be discovered and resolved.
Delete proto schema modules under packages/core/src/bridge/proto (action.ts, element.ts, highway.ts, longmsg.ts, message.ts, notify.ts, oidb-action.ts, oidb.ts) and the related test packages/core/tests/proton-parity.test.ts. These files contained protobuf schema definitions for the bridge layer; remove them as part of a cleanup/refactor. Update any imports or references to these modules to their new locations or replacements.
Import protobuf_decode from @snowluma/proton in packages/core/src/bridge/actions/interaction.ts to enable decoding of protobuf messages within interaction-related bridge actions. No other changes to logic in this diff.
Replace the encodeOidbEnv wrapper with direct protobuf_encode<OidbBase<T>> calls across bridge modules. Updated many bridge action files (extras, friend, group-admin, group-file, group-message, interaction, misc, profile, bridge-contacts, highway pipeline, etc.) to import protobuf_encode and OidbBase and to pass encoded OIDB envelopes via protobuf_encode. Removed the encodeOidbEnv implementation from bridge-oidb and restructured proton OIDB definitions by adding new proto/proton/oidb-actions modules (base, group-album, group-file, media, index) and adjusting proton proto usage. This centralizes envelope encoding for better monomorphization and simplifies the OIDB encoding flow.
Refine and clarify inline documentation across proton schema files (action.ts, element.ts, highway.ts, longmsg.ts, message.ts, notify.ts). Replaces verbose legacy preambles with concise comments, adds concrete notes about server expectations (e.g. Trans0x211 routing for C2C files, required NotOnlineFile fields on send, NTV2 upload extBizInfo video scene fields), and documents GroupFileExtra/GroupFileInfo field alignment and magic tags to explain past send/receive failures. Changes are purely comment and schema documentation updates to improve maintainability and explain interoperability pitfalls with the server; no runtime API/signature changes were introduced.
Remove long legacy/explanatory comment blocks and ASCII-art dividers, replacing them with shorter, consistent section headers (e.g. "Oidb.0xFD4_1 Friend list", "Oidb.0xFE5_2 Group list"). Trim redundant commentary about OidbBase/OidbBaseMeta while keeping all type/interface definitions unchanged. This cleans up the file for readability without altering the public types or runtime behavior.
fetchPrivateFileUrl now uses the current account UID (resolveSelfUid) as receiverUid instead of resolving the peer UID, matching Lagrange.Core/NapCat behavior and avoiding NTQQ fulllink handler timeouts. The userId parameter is intentionally unused. runOidb gained an optional timeoutMs argument and the private-file request uses a 5000ms timeout; bridge.sendRawPacket is forwarded this timeout.
CI tsc flagged two strict-mode issues in d1aade6:
* element-builder: `ctx?.forwardFake` doesn't carry the non-null
narrowing to a subsequent `ctx.groupId` access — replace with an
explicit `ctx && ctx.forwardFake` guard.
* forward-file.test: `vi.fn(async () => [])` infers `mock.calls`
as `[][]`, so `const [, ctx] = mock.calls[0]!` is "Tuple of length
'0' has no element at index '1'". Declare the mock's parameter
types (`unknown[], Record<string, unknown>?`) so the call tuple
has the right arity, and use `ctx?.groupId` since the ctx slot
is now typed as optional.
Previous fix split file segments off at the OneBot live-send layer
(c2c → sendC2cFileMessage, group → sendGroupFileMessage) and made
element-builder drop any `{type:'file'}` segment that reached it.
That broke forward messages: send_forward_msg encodes each node
through buildSendElems for the long-msg upload, so file segments
inside a forward node hit the drop-with-warn path and the forward
bubble shipped without the file.
Forward upload is NOT a live PbSendMsg — it stores the gzipped
protobuf verbatim through `trpc.group.long_msg_interface.MsgService.
SsoSendLongMsg`, and the recipient decodes file entities through the
normal msg-push path (transElem(24) → GroupFileExtra; msgContent →
FileExtra { file: NotOnlineFile }). So `result=79` doesn't apply here.
Add a `forwardFake?: true` flag on SendContext; when set:
* group file → element-builder emits transElem(24) again (restored
makeGroupFileElem, exactly the receive-side wire shape).
* c2c file → element-builder still skips; forward-builder pulls the
segment off the node and writes `body.msgContent` as
FileExtra { file: NotOnlineFile }, with file metadata hydrated
from the upload cache when inline fields are missing (same
pattern as send_private_msg).
Mirrors NapCat's PacketMsgFileElement.{buildElement,buildContent}
split (dev/napcatQQ/.../packet/message/element.ts:530-610) and
Lagrange.Core V2's MultiMsgUploadService.cs.
`vi.fn(async () => undefined)` infers `mock.calls: [][]`, so
destructuring `const [groupId, fileId] = ...mock.calls[0]!` fails
under TS strict tuple checks (`error TS2493: Tuple type '[]' of
length '0' has no element at index '0'`). Declare the param types
inline so the call-args tuple is `[number, string]`.
The chat-publish step after upload_group_file used to ship a PbSendMsg
with a transElem(elemType=24) — but that wire shape is RECEIVE-side
only, and current QQ-NT rejects it on send with `result=79`. Lagrange.
Core V2 uses a dedicated `OidbSvcTrpcTcp.0x6d9_4` for the publish
(`GroupSendFileService.cs`); mirror that. Send_group_msg with a
`{type:'file', file_id}` segment now routes through the same path
after the OneBot layer splits file segments out (matching the c2c
file split pattern).
Separately, send_private_msg with just `{file_id}` was shipping a 0 B
file because the wire packet for c2c file send needs fileSize/fileMd5/
fileName/fileHash but the OneBot caller only echoes the file_id from
upload_private_file. Add a bounded (1024-entry, FIFO) bridge cache
populated at upload time so the send-message path can rehydrate the
full tuple; inline segment fields still take precedence so callers
that track the metadata themselves can bypass the cache. Parser now
also accepts `file_hash`/`fileHash` on file segments.
Also: file segments no longer get a `[空消息]` log line — the format
string now shows `[文件:<name-or-id>]`.
Include optional element.subType and element.summary in the image segment payload (mapped to sub_type and summary) so custom emoji/sticker metadata is preserved. Adds a unit test to verify these fields are forwarded.
The c2c file send path was wrong on three independent axes — every
c2c file the bot tried to deliver was getting rejected by the QQ-NT
server. Aligned to `dev/Lagrange.Core` (V2 branch) which is the only
direct-protocol reference for c2c files; NapCat goes through QQ-NT
IPC and never builds this packet itself.
Three wire-shape fixes:
1. **Routing**: `routingHead.c2c { uin, uid }` → `routingHead.trans0x211
{ ccCmd: 4, uid }`. RoutingHead field 15 is the c2c-file scene's
slot. `MessagePacker.BuildPacketBase` makes this conditional on
`chain.HasTypeOf<FileEntity>()`: when a file is present, C2C goes
nil and Trans0X211 carries the routing.
2. **File payload location**: `messageBody.richText.notOnlineFile {...}`
→ `messageBody.msgContent = serialize(FileExtra{file: NotOnlineFile})`.
The server doesn't read c2c file metadata from `richText` at all —
`MessageBody.cs:12` even has the comment "Offline file is now put
here(?". Confirmed by `FileEntity.PackElement()` returning empty
and `PackMessageContent()` returning the FileExtra wrapper.
3. **contentHead.c2cCmd**: `11` → `0` (default/omitted). `11` was a
stale go-cqhttp value the QQ-NT server doesn't recognise on the
c2c-file dispatcher. Lagrange leaves it at the C# default (0).
Schema fixes (proton + legacy, both directions):
- `RoutingHead` gains `trans0x211?: pb<15, RoutingTrans0x211>`. The
new message has `toUin@1`, `ccCmd@2`, `uid@8`.
- `SendMessageBody` gains `msgContent?: pb<2, bytes>` (the receive-side
`MessageBody` already had it).
- `FileExtraInfo` deleted — was wrong on every tag (fileSize=1,
fileName=2, fileMd5=3, fileUuid=4, fileHash=5, none of which match
the wire). `FileExtra { file: pb<1, NotOnlineFile> }` now wraps the
same `NotOnlineFile` used on the receive path. This is why c2c file
PUSHES were also silently failing the four-field truthy check in
`extractMsgContent` — the schema couldn't decode anything.
- `NotOnlineFile` gains the three intake-validator fields the server
requires on send: `subcmd@9 = 1`, `dangerEvel@50 = 0`, `expireTime@55`
= now+7d.
Receive side (`rich-body-decoder.ts::extractMsgContent`): drop the
"all four fields must be truthy" guard (it was a workaround for the
broken schema) and accept any payload that decodes a fileUuid.
Tests:
- `bridge-private-routing.test.ts`: new regression that round-trips
`sendC2cFileMessage` through `protoDecode` and asserts trans0x211
routing, msgContent FileExtra wrapper, NotOnlineFile field tags,
c2cCmd=0. Catches each of the three wire-shape regressions
independently.
- `send-private-c2c-file.test.ts`: vi.fn arg signatures explicit for
CI typecheck.
647/647 tests pass.
User report: `send_private_msg` with a `{type:'file', file_id}` segment
fired `[ElemBuilder] file send via elems[] is group-only; use bridge.
sendC2cFileMessage for c2c` and the message went out as "[空消息]".
Root cause: c2c files live on `RichText.notOnlineFile` (parallel to the
elems array, see proto/proton/message.ts), not inside `elems[]`. The
element-builder explicitly drops c2c `{type:'file'}` elements with a
warning. `sendPrivateMessage` was passing the file straight to
`bridge.sendPrivateMessage(userId, [fileElement])` which then ran
through `buildSendElems`, lost the file at the drop, and shipped a
0-element wire send — rendered as "[空消息]" by every receiver.
Fix: split at the OneBot layer in `sendPrivateMessage`. Pull file
elements out of the batch and dispatch each via
`bridge.sendC2cFileMessage`; route the rest through the regular
elems[] path. Matches NapCat's `dev/NapCatQQ/.../SendMsg.ts:404-415`
where FILE / VIDEO / ARK / PTT each get their own sendMsg call and
never mix with the regular elems[] batch.
- File-only message: only the c2c file API is called (single roundtrip)
- Mixed text + file: two sends, text first then file
- File without file_id: dropped with a warn (was silently shipping
empty messages)
- UID resolution failure: surfaced as throw instead of empty send
Also rewrote the element-builder fallback warn from "use
sendC2cFileMessage for c2c" (now stale advice) to "BUG: c2c file
reached element-builder — should be split out at the OneBot layer".
Tests: 4 new regression cases under
`tests/onebot/send-private-c2c-file.test.ts`. 646/646 pass.
Cross-referenced `dev/NapCatQQ/.../SendMsg.uploadForwardedNodesPacket`
(208-347): every layer of a nested forward attaches its own msgBody to
the *outer* long-msg upload under a uuid `actionCommand` slot. Receiver
walks the whole tree from one server fetch instead of resolving each
layer's res_id separately.
`dev/Lagrange.Core` (V2 branch on `linwenxuan04/v2`,
`MultiMsgUploadService.cs:23-31`) only writes a single MultiMsg action
— that's why NapCat-style receivers couldn't follow our previous
nested-forward sends past the first level.
Refactor:
1. `ForwardNodePayload` gets an optional `innerForward?:
ForwardNodePayload[]` field. `parseForwardNodes` no longer eagerly
uploads inner chains — it just attaches them here.
2. `uploadForwardNodes` now drives the whole recursion. The new
`uploadForwardNodesRecursive`:
- walks each node, recursively uploads any `innerForward` first
- replaces that node's `elements` with a real `{type:'forward'}`
preview pointing at the inner res_id
- piggybacks the inner level's `{uuid, msgBody}` + every deeper
level it surfaced into this level's `myInnerActions`
- encodes the long-msg payload as
`[{MultiMsg, ownMsgBody}, ...innerActions.map(uuid+msgBody)]`
- returns `{resId, msgBody, uuid, innerActions}` so an outer call
can keep climbing
Top-level public signature unchanged: `Promise<string>`.
3. New `deriveInnerSource` / `previewLinesFromNodes` /
`previewFromElements` helpers synthesise the ARK preview metadata
the inner bubble shows before the user taps to expand. They handle
text/image/record/video/file/forward/face element previews.
4. `parseForwardNodes`: when `content` is an all-node array, attach
the parsed inner chain to `node.innerForward` and let the upload
pipeline take over. `elements = []` placeholder is replaced by
`uploadForwardNodes` once it has the real res_id.
Tests:
- `actions/forward.test.ts`:
- `uploadForwardNodes recursively uploads nested innerForward chains
(NapCat piggyback model)` — asserts two SsoSendLongMsg roundtrips
(inner first, then outer) and the outer res_id propagates up
- `flat sends still take a single roundtrip` — backwards-compat
- `onebot/forward-nested.test.ts`: rewritten — mock now sees exactly
one `uploadForwardNodes` call with `innerForward` attached, instead
of two sequential calls; depth-limit + mixed-content tests
unchanged.
The NTV2 upload request for video carried `time: 0` on the main mp4
sub-file, mirroring NapCat's transformer. But NapCat lives on top of
the desktop QQ-NT client's IPC layer, which patches the duration into
the resulting MsgInfo before the wire send — we don't have that layer,
so the `time: 0` we passed in ended up baked into the `VideoFile.
fileTime` field of every video the bot sent. Receivers then rendered
every video bubble as "00:00".
Cross-checked acidify's `RichMediaUpload.kt::buildVideoUploadInfoList`
(2026-04 refactor) — they're a protocol-direct client too and write
`time = payload.videoDuration` for exactly this reason. We already
have `video.duration` from `loadVideo` (probed via ffprobe), so it's
a one-liner.
Width/height kept at 0 deliberately — acidify fills them, NapCat
zeros them, and our earlier comment recorded "QQ NT server treats
non-zero values here as schema mismatch on c2c sends". Out of scope
for this fix; revisit if a c2c regression surfaces.
Test asserts `fileInfo.time === 10` for the main sub-file (matches
FINGERPRINT.duration) and stays 0 on the thumb.
Two off-by-one bugs in the group-file chat-post element that combined
to make the QQ-NT server reject every group file send with result=79
(visible as "group file uploaded but chat post failed" in the logs):
1. Inner GroupFileInfo fields were shifted one tag left:
- fileSha was field 5, should be field 6
- extInfo was field 6, should be field 7
- fileMd5 was field 7, should be field 8
Field 5 is actually a uint32 placeholder (`field5` in both NapCat
and acidify). With the bug, our fileSha bytes were landing where
the server expected a varint and the rest of the message got
skipped as garbage.
2. Outer GroupFileExtra was missing the magic field1=6 + fileName
slots that NapCat's encoder writes
(`packet/message/element.ts:589`). Acidify's schema also models
them as required even though it serialises with defaults. The
current server build rejects sends without these slots populated.
Cross-referenced:
- NapCat `GroupFileExtraInfo` (component.ts:146-155) — matches our
new field numbers exactly
- acidify `GroupFileExtra.Inner.Info` (proto/message/extra/GroupFileExtra.kt)
— same field numbers; their schema uses generic `field5`/`field7`
names but the wire layout is identical
Changes:
- Proton + legacy schemas: shift inner fields, add outer field1/
fileName/display
- `makeGroupFileElem`: write field1=6 + fileName on the outer wrapper
- Regression test asserts each inner tag lands at 50/58/66 (not the
old 42/50/58) and verifies the new outer field1 + fileName bytes
are present
The 2026 QQ-NT server has stopped populating *every* legacy host field
(uploadIp / uploadDomain / uploadIpList / uploadHttpsDomain / uploadDns).
The host now arrives in the new field 210 `rtpMediaPlatformUploadAddress`
— a repeated `IPv4` message carrying `inIP`/`inPort` (LAN) and
`outIP`/`outPort` (WAN). Coworker's debugging hint "host 好像是 fix64"
was the 8-12-byte length-delimited IPv4 message looking like a
fixed-width field on the wire.
Cross-referenced acidify (https://github.com/LagrangeDev/acidify) —
the only NT-protocol fork that's tracked this change (refactored in
their 2026-04 protobuf rewrite). They read `inIP`+`inPort` exclusively
because that's the address the highway PUT actually needs to reach
(same DC as the OIDB endpoint). LagrangeGo / Lagrange.Core / NapCat
still ship the old schema and would fail the same way against this
server build.
Changes:
- Proton schema: add `IPv4` message (fields 1-5: outIP/outPort/inIP/
inPort/iPType, all int32 varint) + field 210 on the upload response
- Consumer: prefer `rtpMediaPlatformUploadAddress[0].inIP`+`inPort`
before falling back through the legacy host chain
- New helper `int32ToIpv4Dotted` reverses acidify's `Int.toIpString()`
(little-endian byte order, `>>>` for unsigned shift so high-bit IPs
don't render as negative octets)
- Diagnostic warn-log now dumps the rtp address array too
- Regression test: 192.168.1.1 (LE-packed 0x0101A8C0 = 16885952) +
inPort=8080 should reach highway PUT
Surveyed Lagrange.Core (PushMessageService.cs), LagrangeGo
(client/listener.go), lagrange-python (server_push/msg.py), mania
(push_msg.rs), and the tsuzcx/qq_apk decompile — zero handlers for
380 / 0x17C across the lot. Pattern matches subType=38 (also a
QQ-client-internal state push with no OneBot mapping); drop it
through the same silent-acknowledge path so we stop spamming
`MsgPush.Unknown` at debug level on every push.
User report: `upload_private_file` was failing with "private file upload
host is invalid" on a fresh upload (boolFileExist=false). The OIDB call
succeeded but `uploadIp` (field 60) came back empty, and we treated
that single field as the only source of truth.
Cross-referenced LagrangeGo's `OidbSvcTrpcTcp0xE37_800.proto` + NapCat's
`Oidb.0XE37_800.ts`: the server has six parallel host slots on this
response (uploadIp / uploadDomain / uploadIpList[0] / uploadHttpsDomain
/ uploadDns / uploadLanip). LagrangeGo + Lagrange.Core only read field
60 and would hit the same dead-end — we walk the chain instead. Also
log the full slot set when we genuinely can't find a host so future
reports can name which field the server actually populated.
Adds two regression tests: one proves the fallback to `uploadDomain`
goes to highway successfully, one proves we still throw when every
slot is empty.
Delete the "Bundle runtime dependencies" step from .github/workflows/dev-build.yml. The removed step changed to working-directory: dist and ran npm install --omit=dev, so CI will no longer install runtime deps into dist during the dev build, reducing build time and avoiding bundling node modules into the dev artifacts.
Close three coverage gaps surfaced by the cross-Lagrange-family
audit (Lagrange V2 / LagrangeGo / acidify / lagrange-python):
- **0x210 subType 179 + 226 (NewFriend)** — mutual-accept friend
notice. 179 fires when bot sent a request and the other side
accepted; 226 fires for the opposite direction. Both decode
through the same wire shape. LagrangeGo handles the pair via a
`case 226: case 179:` fallthrough in `client/listener.go:248`.
We surface them as `kind: 'friend_add'`, which the existing
converter routes straight to OneBot `notice.friend_add` — bot
frameworks that wait for "auto-add a friend after they accept"
were previously stuck because nothing arrived.
- **0x210 subType 139 (self-recall)** — bot recalled its own
message sent to a friend. Same `FriendRecall` wire shape as 138
but the peer is on `toUid` instead of `fromUid` — acidify's
`parseFriendRecall:380` splits exactly this way. Without 139,
self-recalls disappeared and downstream `notice.friend_recall`
handlers thought the bot had never recalled anything.
- **PkgType 85 (bot self-joined a group)** — fires on the bot's
session once `set_group_add_request` is approved or an invite is
accepted, ported from lagrange-python's `server_push/msg.py:108`.
PkgType 33 (GroupMemberIncreaseNotice) only fires for *other*
members joining, so without 85 the bot never received its own
`notice.group_increase` until the first message arrived. We
decode `SelfJoinInGroup` and emit `kind: 'group_member_join'`
with `userUin = selfUin`; the existing converter picks
`sub_type: 'approve' | 'invite'` from the operator/user equality
so consumers see the standard OneBot shape.
While wiring 139, also fix a *pre-existing* prod bug spotted via
proton call-site analysis on the resulting bundle: `event-0x210.ts`
imported `FriendRecall` from both `proto/proton/notify` (as
`FriendRecallNotify`) *and* `events` (as the event interface).
Proton's import-resolver registers `importedTypeSources` keyed on
the *imported* name (last-write-wins), so the events.ts import
shadowed the proto one — `protobuf_decode<FriendRecall>(...)` lost
its codec, fell through to the runtime fallback throw, and was
silently swallowed by `MsgPushRegistry.decode`'s catch. Verified by
the substituted codec list in `dist/index.mjs`: pre-fix it had
`FriendRequest` / `GeneralGrayTipInfo` but no `FriendRecall`;
post-fix `FriendRecall` / `NewFriend` / `SelfJoinInGroup` are all
emitted as expected. Side-step the collision by importing the
proto types unaliased and re-deriving the colliding event type via
`Extract<QQEventVariant, { kind: 'friend_recall' }>`.
New proto interfaces in `proto/proton/notify.ts`:
- `NewFriend` + `NewFriendInfo` (uid/time/message/nickName fields,
fields 1-9; ported from
`LagrangeGo/.../notify.proto:25 NewFriend`)
- `SelfJoinInGroup` (groupUin / operatorUid + a few placeholder
fields; ported from
`lagrange-python/pb/status/group.py:170 PBSelfJoinInGroup`)
Regression coverage in `tests/msg-push-handler.test.ts`:
- subType 179/226 both produce identical friend_add events
- falls back to `routingHead.fromUin` when the new friend's uid
isn't in the local cache (matches LagrangeGo's
"emit-then-resolve" pattern)
- subType 138 keeps fromUid as the peer (other recalled their
own msg to us); subType 139 picks toUid (we recalled ours
sent to them)
- PkgType 85 emits group_member_join with userUin == selfUin,
operator resolved through identity when known
core: 635/635 tests pass (+7), typecheck clean. Production bundle
now contains substituted codecs for FriendRecall, NewFriend,
SelfJoinInGroup (cross-checked via `grep protobuf_decode_X` on
`dist/index.mjs`).
Earlier this commit acknowledged subType 38 as a placeholder
"FriendGrayTipInfo" because none of the LagrangeDev-family projects
(Lagrange V2 / lagrange-python / LagrangeGo / acidify) have a
handler for it — they all just fall through with a generic
"unknown subType" debug log. The "best guess" gray-tip framing was
wrong.
A contributor traced it through the decompiled stock QQ Android
client to `com.tencent.imcore.message.ext.codec.decoder.msgType0x210
.SubType0x26` (tsuzcx/qq_apk @ afe46ef). The payload is
`submsgtype0x26.MsgBody` dispatching on `uint32_sub_cmd`:
- 0x1 → `UpdateAppUnreadNum`: a list of
`{group_code, app_id, unread_num}` keeping group-internal
"mini-app" badge counts (e.g. `appId=101846662` / `101896870`
for the troop shortcut bar) in sync.
- 0x3 → `UpdateDiscussAppInfo`: `{conf_uin, app_tip_notify.text}`
discussion-group app tips, routed through `getGAudioHandler()`.
- 0x4 → delegated to the troop online-push handler.
None of these have a meaningful OneBot mapping — they're
QQ-client-UI state pushes (badge counts, in-app tips), not
conversation events. Rename the enum entry to `GroupAppStatePush`
to reflect the actual semantics, cite the decompiled source
inline, and keep the silent-drop behaviour from the previous
attempt. Tests + decoder routing follow the rename.
628/628 tests pass (unchanged), typecheck clean.
CI's `tsc --noEmit` was rejecting `forward-nested.test.ts` because the
`vi.fn(async () => 'RES')` mocks for `bridge.uploadForwardNodes` only
inferred zero or one arg from the lambda — so
`uploadForwardNodes.mock.calls[0]` came out typed as `[]` or
`[nodes: any[]]`, and indexing `[1]` / `[2]` for groupId / userId
hit `Tuple type ... has no element at index 'N'`.
Local `tsc --noEmit` happened to be looser about this in my version,
which is why the bad assertions slipped past `e637647`.
Declare the full 3-arg signature on every `uploadForwardNodes` mock
— `(_nodes, _groupId?, _userId?)` — matching the real
`Bridge.uploadForwardNodes` contract. `mock.calls[i]` now types as a
3-tuple, the index accesses check out, and the assertions stay
unchanged. No production code touched, no test behaviour change.
626/626 still passing, typecheck clean.
A custom forward node's `content` field can itself be a list of
`{type:'node'}` entries — that's the nested-forward case where one
forward bubble contains another. `parseForwardNodes` used to pass
the whole `content` straight into `parseMessage`, which routed
each inner `{type:'node'}` through `message-parser.ts:217 case
'node':` and turned them into opaque
`MessageElement{type:'node', resId: JSON.stringify(content)}`
placeholders. `element-builder.buildSendElems` then dropped those
at its default branch — so the outer forward shipped with either
zero elements (pure-nested → server rejects with "message is
empty") or text-only elements (mixed content → silently truncated
chat bubble). User-facing symptom: "嵌套转发解析后发不出去".
Add depth-aware recursion to `parseForwardNodes`, modelled on
NapCat's `SendMsg.uploadForwardedNodesPacket` (3-level cap):
- When a node's `content` is *all* `{type:'node'}` entries,
recurse: parse the inner chain into ForwardNodePayload[],
upload it via `bridge.uploadForwardNodes` to mint an
inner res_id, then embed a `{type:'forward', resId}` element
in the outer node. The receive-side rendering pipeline already
builds the ARK preview card for that element shape, so the
QQ client renders a tap-to-expand nested bubble.
- Mixed content (text + node siblings) deliberately stays on the
flat path — the meaning is ambiguous, and forcing a recursion
would silently drop the non-node siblings.
- Hard cap at depth 3; deeper attempts throw "depth exceeds 3".
Matches NapCat and prevents one slow inner upload from
aborting an unreasonably deep tree.
Threading: each forward send entry point passes its destination
into the parser (`{groupId}` from group-send, `{userId}` from
private-send) so the inner forward uploads against the same
res_id namespace.
Test coverage in `tests/onebot/forward-nested.test.ts`:
- group: inner uploads first, outer wraps inner res_id in a
forward element, both calls happen in order
- private: c2c path threads userId (not groupId) into the
inner uploadForwardNodes
- depth cap rejects 4-level nesting with /depth/
- flat (non-nested) content still uploads exactly once
- mixed content stays on the legacy parseMessage path
core: 626/626 tests pass (+5), typecheck clean, prod build clean.
The companion to `e637647`. That commit fixed
`upload_group_file` / `upload_private_file` to publish the file as
a chat message atomically (matching napcat). This one fixes the
OTHER half of the same bug: when a bot framework does
send_msg([{type:'file', file_id:'<previously uploaded>'}])
— attaching an already-uploaded file as a message segment — the
parser used to fall through to its default warn-and-drop branch
(`message-parser.ts:340`). The dropped segment then either:
- became "message is empty" if it was the only segment, or
- silently disappeared if it shared the payload with text,
producing a chat bubble missing the file.
Adds a `case 'file':` that maps the OneBot segment shape to the
existing `MessageElement{type:'file', fileId, fileName, fileSize,
md5Hex, sha1Hex}` that `element-builder` already knows how to
emit as `TransElem(24)`. Accepts the common alias spellings
(`file_id`/`fileId`, `name`/`filename`/`fileName`,
`size`/`fileSize`, `md5`/`md5Hex`, `sha1`/`sha1Hex`).
Deliberately rejects `{file: '/path'}` form — kicking off an
upload from inside the synchronous parser would either swallow
errors or restructure the whole parseMessage signature, neither
worth it. Callers wanting upload-and-send should keep using
`upload_group_file` / `upload_private_file`, which now does both
atomically.
core: 621/621 tests pass (+3), typecheck clean.
`upload_group_file` / `upload_private_file` used to do only the
upload half of the napcat-equivalent flow:
OIDB 0x6D6_0 alloc → highway PUT → return fileId
The fileId was real, the bytes were on QQ's CDN, the logs said
"uploaded" — but the chat showed nothing because no message was
ever sent referring to the upload. NapCat's `UploadGroupFile`
action (`dev/napcatQQ/.../UploadGroupFile.ts:54-58`) does the
upload AND immediately calls `MsgApi.sendMsg(peer, [fileElement])`
in the same action; that second step is what makes the file
visible in the chat.
Add the missing send step. Two paths because the wire shape
differs:
- **Group files** ride on `Elem.transElem` (type 24) in the
`RichText.elems` array. Add a `makeGroupFileElem()` helper +
`case 'file':` in `element-builder.buildSendElems`, then
`bridge.sendGroupMessage(groupId, [fileElement])` after a
successful upload. The TransElem wraps a `GroupFileExtra`
protobuf in `0x01 | BE16(len) | payload`, byte-symmetric with
the receive-side decoder at `rich-body-decoder.ts:171-185`.
- **C2C (private) files** live on `RichText.notOnlineFile`
(field 3 on RichText, parallel to `elems`), so they can't go
through `buildSendElems` at all. Add `Bridge.sendC2cFileMessage`
that builds the `SendMessageRequest` with `notOnlineFile`
directly and dispatches via `sendRawPacket`. The decoder side
that lifts these back to `{type:'file'}` segments has lived
at `rich-body-decoder.ts:425-433` the whole time.
Behavioural detail: both upload paths call the chat-publish step
*only* when `uploadFile=true` (the default). `uploadFile=false`
keeps the upload-only semantics for callers that just want a
fileId without dropping a message in the chat. If the chat post
fails for any reason (server rejection / network), the action
still returns the fileId with a warning log — the file is on QQ's
side, callers can re-publish if they want.
Regression coverage in `tests/actions/group-file.test.ts`:
- publishes the file as `{type:'file'}` via sendGroupMessage on
group upload
- skips the post when uploadFile=false
- returns success even when the chat post fails
- same trio for private upload going through sendC2cFileMessage
- and confirms private path does NOT route through the
`sendPrivateMessage` elems[] pipeline
core: 618/618 tests pass (+5), typecheck clean. Production build
contains 8 substituted call sites for the new GroupFileExtra +
SendMessageRequest paths under proton.
Vendored in 6294e29, used by every protobuf call site in `core`
since the OIDB migration landed (5b55f5b). Add a one-liner to the
workspace table next to the other infrastructure packages.
`vite build` was emitting a single ~606 kB chunk for the whole SPA
(Vite even printed its >500 kB warning). Every route — overview,
config (with its full edit-dialog form surface), logs, settings —
was eagerly imported in `router/index.tsx`, so users paid the full
parse + execute cost before the login redirect even resolved.
That's the most plausible cause of the "loading node config is
somewhat slow" report.
Switch each route to `lazyRouteComponent(() => import('…'), '<Name>')`
so the page chunk is fetched on demand, and wrap `<Outlet />` in
`AppLayout` with a `<Suspense>` boundary backed by a small skeleton
fallback. `defaultPreload: 'intent'` is already set on the router,
so hovering a sidebar link warms the next chunk before the click —
navigation still feels instant after the first idle moment.
Build now emits:
index.js 606 kB → 284 kB (-53%)
overview-page 15 kB
config-page 25 kB
logs-page 5.6 kB
settings-page 5.8 kB
button (shared primitives) 164 kB
+ smaller per-component chunks Vite shook out
And the >500 kB warning is gone.
Bonus: replace the per-render
`list.filter(...).map(...).includes(item.name)` O(n²) duplicate-name
check in `NetworkTabView` with a one-shot `Map<name, count>` —
matters every time the user types in the edit dialog and the tab
underneath re-renders.
The proton plugin was only in `vitest.config.ts`, so tests and
typecheck passed but the bundled `dist/index.mjs` shipped with the
unsubstituted generic shells — every `protobuf_encode<T>()` /
`protobuf_decode<T>()` call hit the runtime fallback and threw:
"protobuf_encode<T>() was not transformed by the
@snowluma/proton Vite plugin. …"
at every msg-push, rkey/friend/group/profile warmup, etc. on the
Win/Linux releases.
Add `protobufVitePlugin()` to the shared `BaseConfigPlugin` so the
transform runs in both dev (`vite build --mode development`) and
prod (`vite build`). Sanity-check on a fresh `vite build` shows the
bundle now contains 481 distinct monomorphized codecs (704 encode +
511 decode call-site replacements), and the only remaining
"was not transformed" string is the dead runtime fallback that no
longer has a caller.
`HttpServerAdapter.startServer` baked `accessToken` into the
`createServer` callback's closure, then relied on
`bindingSignature` including the token to trigger a
`close()`+`open()` round-trip on every change. Two problems:
1. The three sibling adapters (`ws-server`, `http-post`,
`ws-client`) all read `this.config.accessToken` inline at the
point of use, so the HTTP-server's closure-capture pattern was
the odd one out.
2. `server.close()` is asynchronous; the immediately-following
`server.listen()` on the same port can race with the OS
releasing it. When it loses, the new listener fails with
EADDRINUSE (logged via `server.on('error', …)` but not bubbled
up), the old server is gone, and the operator's `reload` looks
successful while the endpoint is actually broken — which lines
up with the "token didn't hot-reload" reports.
Drop the closure capture: `handleRequest` reads
`this.config.path` and `this.config.accessToken` fresh per request
(`reload()` already replaces `this.config` in place via
`structuredClone(next)`). Remove `accessToken` from
`bindingSignature` so a token change no longer triggers a port
re-bind. `host`/`port`/`path` stay in the signature because Node's
`Server.listen()` binds the socket on those.
Four hot-reload tests pin the new contract: token swap, clearing
to empty, setting from empty, and "token-only change returns
`NetworkReloadType.Normal`" (no Reopened/Closed). All four hit a
single OS-assigned port and verify the port is unchanged after
reload — a re-bind would either land on a different port or fail.
core: 613/613 tests pass (+4), typecheck clean.
PR #31 landed 4 TRPC group-album actions on the legacy runtime
schema encoder. Migrate them to the compile-time codec, matching
the pattern established by the OIDB migration: TS interfaces in
`proto/proton/oidb-action.ts` are monomorphized at build time and
each `protoEncode/Decode` call site now calls `protobuf_encode<T>` /
`protobuf_decode<T>` directly.
- Add 33 proton interfaces for the new TRPC envelopes (GetMediaList,
DoQunComment, DoQunLike, DeleteMedias, plus all nested types) —
inline anonymous schemas in legacy lifted to named interfaces.
- Migrate `actions/group-album.ts` to the proton API; drop the
`(resp as any)` casts now that decoded responses are typed.
- Add 4 wire-byte parity tests for the new envelopes; non-default
field values throughout so byte equivalence holds (proto3 omission
of defaults is the documented divergence).
- Drop dead `GroupAvatarUploadExtSchema` from `proto/highway.ts` and
unused `import * as console from "node:console"` in
`web/group-album.ts` — leftovers from the original PR review.
core: 609/609 tests pass, typecheck clean.
Closes the OIDB phase of the proton migration. Every consumer that
talked to the OIDB service through the old runtime
`makeOidbBaseSchema()` factory now goes through the compile-time
generic `OidbBase<T>` instead — proton monomorphizes the codec per
call-site instantiation.
@snowluma/proton — two analyzer fixes uncovered by the migration:
1. Skip queuing call-site type-args that reference an *enclosing
generic function's* type parameter for monomorphization. Before
this, a wrapper like
export function encodeOidbEnv<T>(env: OidbBase<T>): Uint8Array {
return protobuf_encode<OidbBase<T>>(env);
}
would cause the analyzer to mint a literal `OidbBase__T` registry
entry with `body.typeName = 'T'`, which the post-walk wire-type
guard then tripped on. The enclosing-scope type params are tracked
on a stack as the walker descends into FunctionDeclaration,
FunctionExpression, ArrowFunction, MethodDeclaration nodes; matching
call sites are skipped (the wrapper-binding path is still
responsible for materialising concrete codecs at downstream call
sites).
2. Register *explicitly* empty interfaces (`interface X {}`) as
zero-field proto messages. OIDB has a handful of these
('this call has no meaningful response body' placeholders —
Oidb0xeb7Resp, Oidb0xcd4Resp, Oidb0x112aResp, Oidb0x8a0Resp,
Oidb0xf16Resp, OidbClientKeyReq). Proto3 wire allows zero-field
messages, and downstream code does `protobuf_decode<OidbBase<X>>`
where X is one of these — the wire-type guard would otherwise trip
on the missing `X` registration. Interfaces that have members but
no pb-marked fields are still NOT registered.
@snowluma/core — the OIDB-layer refactor itself:
bridge-oidb.ts ditches the runtime ProtoSchema factory and exposes:
- makeOidbEnvelope<T>(oidbCmd, subCmd, body, isUid) pure helper
- encodeOidbEnv<T>(env) pass-through
- decodeOidbEnv<T>(bytes) pass-through
- runOidb(bridge, cmd, envelopeBytes) non-generic raw
`encodeOidbEnv` / `decodeOidbEnv` are pure pass-through generic
wrappers — proton wrapper-binds them and substitutes every call site
with the inlined `protobuf_encode_OidbBase__X` / `protobuf_decode_…`
function. `runOidb` is non-generic (proton leaves it alone) so it can
be mocked in tests. `makeOidbEnvelope` is plain TS — also mockable for
introspection.
56 `runOidb` call sites across 11 files migrated to the new API:
- bridge-contacts.ts, actions/extras.ts, actions/friend.ts,
actions/group-admin.ts, actions/group-file.ts,
actions/group-message.ts, actions/interaction.ts,
actions/misc.ts, actions/profile.ts, web-actions/cookies.ts,
highway/pipeline.ts
pipeline.ts also drops `makeOidbBaseSchema(NTV2UploadRichMediaReqSchema)`
and the residual `protoEncode({...}, EncodableMediaMsgInfoSchema)` —
both go through proton now.
Tests:
- 8 test files migrated from `vi.mocked(decodeOidbEnv).mockReturnValueOnce`
to `vi.mocked(runOidb).mockResolvedValueOnce(protobuf_encode<OidbBase<X>>({body: …}))`
— the proton substitution means the old mock layer is bypassed at
build time, so the only mockable point is the bytes layer at `runOidb`.
- 2 new parity tests pinning `OidbBase<T>` ↔ legacy
`makeOidbBaseSchema(InnerSchema)` byte equivalence.
Verification:
- @snowluma/proton: 95/95 tests pass, tsc --noEmit clean
- @snowluma/core: 605/605 tests pass (network-manager.test.ts
fails to load due to a missing darwin-arm64 native binary in this
environment — pre-existing), tsc --noEmit clean
Phase 2 of the OIDB migration: one-to-one mirror of every schema in
bridge/proto/oidb-action.ts as a proton interface. Purely additive —
the legacy `*Schema` constants stay in place; no call sites are
switched yet.
Translation is mechanical:
- export const XxxSchema = { ... } satisfies ProtoSchema;
→ export interface Xxx { ... }
- { field: N, type: 'uint32' as const } → pb<N, uint_32>
- { field: N, type: 'repeated_message',
schema: YSchema } → pb_repeated<N, Y>
- … (etc, for every primitive + message + repeated_*)
All section headers (`// --- 0x1253_1: Mute group member ---`) and
inline NTQQ-specific comments (the FE1_2 field-2 note, the NTV2
default-value note, the Lagrange-observed annotations on
GroupAvatarExtra, etc.) preserved verbatim.
Verification:
- 183 interfaces emitted, exact match to the legacy schema count
- tsc --noEmit clean
- 604/604 core test suite passes (no behaviour change — additive
only)
Phase 3 next: refactor runOidb to use protobuf_encode<OidbBase<TReq>>
and migrate the 67 runOidb call sites across 10 files + pipeline.ts.
Phase 1 of the OIDB migration: stages the proton-side type definitions
and pins their wire equivalence to the legacy makeOidbBaseSchema()
runtime factory. No call sites are switched yet — that lands in
phase 2 along with the proton/oidb-action.ts schema mirror and the
runOidb refactor.
The legacy bridge/proto/oidb.ts exports a `makeOidbBaseSchema(body)`
factory function that synthesizes the OidbSvcTrpcTcpBase envelope
ProtoSchema at runtime. Proton is compile-time, so the natural form
is the generic interface
OidbBase<T> { command, subCommand, errorCode, body: T, errorMsg,
properties, reserved }
which the plugin monomorphizes per-instantiation. This is exactly the
"generic template with generic-instantiated field" usage that this
package's earlier edge-case fixes#2 and #3 were designed to support,
and the new parity test pins that they actually work on the real
shape (a fully populated OidbSvcTrpcTcp0xFE5_2Response with nested
groupOwner/customInfo).
Also added:
- OidbProperty (for the envelope.properties repeated field)
- OidbBaseMeta — envelope-only view for fire-and-check OIDB calls
that just need to peek at errorCode without decoding the body
- All 8 concrete schemas from oidb.ts (FriendList, GroupList,
GroupMemberList, GroupRequest families)
Verification:
- 2 new parity tests
* OidbBase<OidbSvcTrpcTcp0xFE5_2Response> ↔ makeOidbBaseSchema
byte equivalence
* round-trip encode → decode preserves nested body
- 602+2 = 604 core tests pass (network-manager file still env-fails
on missing native binary)
- tsc --noEmit clean
Mirrors all 35 schemas in bridge/proto/highway.ts as proton interface
forms and switches the two non-OIDB-wrapped consumers
(highway/highway-client.ts and actions/group-file.ts) over to the new
compile-time API.
Migrated schemas (proton/highway.ts):
DataHighwayHead, SegHead, LoginSigHead, ReqDataHighwayHead,
RespDataHighwayHead, HighwayDomain, HighwayIPv4, HighwayNetwork,
HighwayHash, HighwayMsgInfoBody, NTV2RichMediaHighwayExt,
FileUploadUrl, FileUploadHost, FileUploadHostConfig,
FileUploadNameInfo, FileUploadClientInfo, FileUploadFileEntry,
FileUploadBusiInfo, FileUploadEntry, FileUploadExt,
EncodableMediaExtBizInfo, EncodableMediaMsgInfo, HttpConn,
HttpConn0x6FF501Request, ServerAddr, ServerInfo, HttpConnResponse,
HttpConn0x6FF501Response, NTV2FileType, NTV2FileInfo,
NTV2UploadInfo, NTV2ExtBizInfo, NTV2UploadReq, NTV2C2CUserInfo,
NTV2GroupInfo, NTV2UploadSceneInfo, NTV2CommonHead, NTV2ClientMeta,
NTV2UploadReqHead, NTV2UploadRichMediaReq, NTV2IPv4,
NTV2SubFileInfoResp, NTV2UploadRespMsgInfo, NTV2UploadRespBody,
NTV2UploadRespHead, NTV2UploadRichMediaResp
Consumer switches:
- highway/highway-client.ts: protobuf_encode/decode for HttpConn
session fetch, ReqDataHighwayHead frames, NTV2RichMediaHighwayExt
extend bytes, RespDataHighwayHead per-chunk responses
- actions/group-file.ts: protobuf_encode<FileUploadExt> for both
group + private file upload ext bytes
NOT migrated (depends on the OIDB factory pattern):
- highway/pipeline.ts — uses makeOidbBaseSchema(NTV2UploadRichMediaReqSchema)
to wrap the NTV2 upload in an OIDB envelope at runtime. Waits for
the oidb.ts migration to land a generic OidbBase<T> form.
Verification:
- 5 new parity tests for highway schemas (HttpConn0x6FF501 req+resp
with the high-numbered 0x501 tag, ReqDataHighwayHead with multiple
nested messages, NTV2RichMediaHighwayExt with repeated_bytes,
FileUploadExt with the 100/200/400/600/700 high-numbered tags)
- 602/602 core test suite passes — the existing image / ptt / video
upload tests implicitly validated wire format equivalence
- tsc --noEmit clean
Mirrors all 11 schemas in bridge/proto/action.ts as proton interface
forms and switches the two consumers (element-builder.ts and the
send-message paths in bridge.ts) over to the new compile-time API.
Migrated schemas (proton/action.ts):
RoutingC2C, RoutingGroup, RoutingHead, SendContentHead,
MessageControl, SendRichText, SendMessageBody, SendMessageRequest,
SendMessageResponse, MentionExtraSend, MarkdownData
Consumer switches:
- element-builder.ts: protobuf_encode<MentionExtraSend> for @ mention
pbReserve payload; protobuf_encode<MarkdownData> for markdown elem
- bridge.ts: protobuf_encode<SendMessageRequest> +
protobuf_decode<SendMessageResponse> for both sendGroupMessage and
sendPrivateMessage
The `ProtoElem` type alias in element-builder.ts (Partial<ProtoDecoded<typeof
ElemSchema>>) stays as-is — it's a pure TS type used internally for
building elem objects and doesn't affect runtime behaviour. Replacing
it with the proton Elem type is a larger refactor that can come later
when there's a reason to.
Verification:
- 6 new parity tests for action schemas (RoutingHead c2c+grp,
SendMessageRequest full shape, SendMessageResponse, MentionExtraSend,
MarkdownData)
- 591/591 core test suite passes — the existing send-message and
element-builder tests implicitly validated wire format equivalence
- tsc --noEmit clean
Completes the proton migration started in the previous PoC commit. All
schemas needed by actions/forward.ts are now mirrored as proton interface
forms, the legacy ProtoSchema constants stay in place for back-compat,
and forward.ts has been switched over to the new compile-time codecs.
Migrated schemas:
- element.ts (35 schemas: TextElem, FaceElem, OnlineImage, NotOnlineImage,
TransElem, MarketFace, CustomFace, RichMsg, GroupFileElem, ExtraInfo,
VideoFile, SrcMsg, LightAppElem, CommonElem, GeneralFlags, Elem,
MentionExtra, QFaceExtra, QSmallFaceExtra, FileType, FileInfo,
IndexNode, PicUrlExtInfo, PictureInfo, PicExtData, PicExtBizInfo,
VideoExtBizInfo, PttExtBizInfo, ExtBizInfo, C2cSource, TroopSource,
HashSum, MsgInfoBody, MsgInfo, GroupFileInfo, GroupFileExtraInner,
GroupFileExtra, Preserve, …)
- message.ts (PushMsg, PushMsgBody, ResponseHead, ContentHead, Ptt,
NotOnlineFile, RichText, MessageBody, FileExtra, …)
- longmsg.ts — the three remaining schemas (LongMsgContent / LongMsgAction
/ LongMsgResult) that depend on PushMsgBody
forward.ts now calls:
protobuf_encode<LongMsgResult>(...) // upload payload
protobuf_encode<SendLongMsgReq>(...)
protobuf_decode<SendLongMsgResp>(...)
protobuf_encode<RecvLongMsgReq>(...)
protobuf_decode<RecvLongMsgResp>(...)
protobuf_decode<LongMsgResult>(...) // download payload
protobuf_encode<PushMsg>(...) // re-wrap for parseMsgPush
The unused legacy schema constants are intentionally left in place — they
still back the existing forward.test.ts mock encoder and any other consumer
that hasn't been migrated yet. They will be removed in a follow-up once
every consumer is on the new API.
Verification:
- 18/18 parity tests pass (encode + decode equivalence for every
representative shape across element / message / longmsg)
- 585/585 core test suite passes (network-manager.test.ts fails to load
due to a missing native binary in this environment — pre-existing)
- tsc --noEmit clean
Standalone tsx script benchmarking the codecs generated by
@snowluma/proton against the existing src/protobuf/decode.ts runtime
implementation, using the actual long-message schemas already in the
codebase (the proton interface form + the legacy *Schema constants).
Proton codecs are materialised at bench startup via the public
analyzeSource + generateCode API — exactly what the Vite plugin does at
build time — so there is no chicken-and-egg dependency on a Vite build.
Headline numbers on Node 24 / darwin-arm64:
- simple 4×uint32 encode: ~8.5× speedup
- simple 4×uint32 decode: ~35× speedup
- deeply nested SendLongMsgReq encode: ~9.5×, decode: ~13×
- 64-byte payload RecvLongMsgResp encode: ~4.3×, decode: ~10×
Run with:
pnpm --filter @snowluma/core exec tsx bench/proton-vs-legacy.ts
Covers quick start, primitive types, generic templates, cross-file
wrapper bindings, the proto3 default-value divergence vs the legacy
runtime encoder, build-time diagnostics, and the optional runtime-map
fallback. Also lists every edge case fixed on top of upstream with a
pointer to the corresponding regression test.
Migrates a self-contained subset of bridge/proto/longmsg.ts to the new
@snowluma/proton compile-time DSL form and verifies wire-format parity
against the legacy runtime ProtoSchema encoder. End-to-end proof that
the toolchain works in core's vitest pipeline.
What's covered:
- LongMsgUid / LongMsgSettings / SendLongMsgInfo / SendLongMsgReq /
SendLongMsgResp / SendLongMsgRespResult / RecvLongMsgInfo /
RecvLongMsgReq / RecvLongMsgResp / RecvLongMsgRespResult
- The three schemas that pull in PushMsgBody (LongMsgContent /
LongMsgAction / LongMsgResult) stay on the legacy API for now, since
migrating them requires also migrating message.ts and element.ts.
Toolchain changes:
- @snowluma/proton gets a tsup build step. The ./vite subpath now
points at the built dist/index.js so it is loadable as plain Node
ESM from vite.config.ts / vitest.config.ts (the source-only .ts
layout can't be consumed from outside the Vite transform pipeline).
The . (runtime) subpath stays at TS source — it's only ever
imported from user code, which IS Vite-transformed.
- prepare script ensures dist/ exists after pnpm install.
- @snowluma/core depends on @snowluma/proton (workspace:*) and adds
protobufVitePlugin() to its vitest config so test files get
transformed.
Documented divergence:
proton follows proto3 semantics: fields equal to their default value
(0 / false / "" / empty bytes) are NOT emitted on the wire. The legacy
runtime encoder always emits them. Both forms are round-trippable
through a conforming proto3 reader. The parity test pins this
behaviour explicitly.
8/8 parity tests pass.
Vendors SnowLuma/protobuf-dsl into the monorepo as @snowluma/proton, with
edge-case fixes applied on top of the upstream source. Reference copy of
the unmodified upstream is kept under dev/protobuf-dsl/.
Edge cases fixed (each with a regression test):
- Aliased pb / pb_repeated marker imports (`import { pb as P }`)
— collector now resolves the marker name through the import resolver
- Concrete interface with a generic-instantiated message field
(`wrapped: pb<5, Wrapper<uint_32>>`) — field typeName now resolves
to the mangled form, and the inner instantiation is queued for
monomorphization
- Generic template with a generic-instantiated field
(`interface Outer<U> { x: pb<5, Wrapper<U>> }`) — the inner
instantiation is now re-substituted and re-monomorphized at outer
instantiation time
- Wrapper-binding synthetic SourceFile was empty-text — getText()
returned garbage, breaking mangled name computation downstream
- Cross-file forwarded wrappers (chain → imported base) were not
detected — parseFileForDefinitions now resolves imports recursively
(value imports only, with cycle protection)
- matchForwardedKnownWrapper did not propagate typePattern — chain
treated <X> as the encoded type instead of Wrapper<X>
- Synthetic-SF WeakMap was private to analyzer.ts — replacer could
not see it. Moved to utils.ts so typeNodeToMangledName picks it up
automatically.
Defensive guard: any field whose typeName resolves to neither a primitive
nor a known message now throws at analyze() time, instead of silently
leaking the WireType.Varint placeholder into codegen.
95/95 tests pass; tsc --noEmit clean.
Introduce a new @snowluma/protobuf package (v0.0.4) that provides a lightweight protobuf-ts wrapper (NapProto/NapProtoMsg) with type helpers, ProtoField factory, and encode/decode utilities. Adds package.json, tsconfig.json, and the implementation at src/NapProto.ts. pnpm-lock.yaml was updated to include the @protobuf-ts/runtime dependency resolution.
Adds structured YAML issue forms (bug + feature) and a config that
disables blank issues and links to the QQ group / Telegram channels
already in README.
Follow-up to c62f517. Dropping the obsolete field 2 from the body was
necessary but insufficient: newer QQ NT still rejects the request with
[oidb] one of uid/openid is invaild
The actual trigger is the OIDB envelope-level `reserved` flag.
Lagrange.Core's FetchStrangerByUin sets `Reserved = 1`, our call sent
`Reserved = 0`. The server uses that bit to pick its validation path:
- reserved=1 → UIN-form variant: server translates body.uin to the
internal uid itself
- reserved=0 → UID-form variant: server expects a uid/openid string
in the body and rejects when it can't find one
Our request body has only `uin` + `keys`, so the UID-form path was
always going to fail. Setting `isUid: true` (which is the existing
flag that flips envelope `reserved` to 1; the parameter name is
historical and misleading) puts the call onto the correct branch.
Applied to both call sites that target OidbSvcTrpcTcp.0xfe1_2:
- fetchUserProfile (bridge-contacts.ts) — fixes the
"failed to load self profile for UIN N" warmup warning.
- getStrangerStatus (actions/extras.ts) — same OIDB cmd; would
have failed identically if exercised against newer QQ NT.
Also updated the `isUid` JSDoc on OidbCall to spell out the actual
semantic (UIN-form variant marker, not "this call uses UID-keyed
data") since the name will keep tripping people otherwise.
The adapter edit dialog now ships a dedicated TokenField for the
access-token slot instead of reusing the plain text Field. It:
- defaults to a password-style input so the value stays out of
casual screen reads / screenshots,
- exposes an Eye / EyeOff button that flips the input type rather
than masking the string, so paste / autocomplete still behave like
a native password field,
- exposes a Copy button that pushes the current value to
navigator.clipboard, flashing a check icon for ~1.4 s on success,
and disables itself when the value is empty,
- falls back to a transient textarea + document.execCommand('copy')
for non-secure-context environments (LAN HTTP outside localhost),
routed through a local alias so the deprecation warning on the
live signature doesn't fire at the call site.
Follow-up to a07521d. The reporter's correction (895 friends / 221
groups account) was that turning off only field5003 + all of config2
wasn't enough — field5002 has to go too, otherwise QQ NT still emits
a response large enough to blow the named-pipe write buffer and
fetchGroupList dies with EPIPE.
The response decoder (OidbSvcTrpcTcp0xFE5_2GroupInfoSchema) only knows
about tag numbers 1/2/3/4/5/18/19/30, and fetchGroupList itself only
reads groupName / memberCount / memberMax / customInfo.remark off the
result. Tag 5002 isn't in the response schema and isn't consulted by
any caller, so silencing it on the request side is purely a payload
reduction with no observable behavior change.
A11y checkers (axe-core / jsx-a11y) flag the boolean form because the
ARIA spec defines aria-checked as the enum "true" | "false" | "mixed",
not a boolean. React serialized the boolean to the right wire value at
runtime, but the inspection layer keys off the JSX expression's static
type. Switching to the explicit ternary silences both.
The original page stacked four expanded network sections vertically with
inline editing, so the first view drowned in every field across every
adapter at once. Restructured to a sidebar + tabs + modal layout:
- Account sidebar collapses to a 56px avatar column with name/UIN
tooltips; expanded it keeps the original 260px nickname + UIN layout.
- Right pane swaps the stacked sections for a 5-tab strip (通用设置 /
HTTP API / HTTP 客户端 / WS 服务端 / WS 客户端) with a per-tab badge
count.
- Each network tab is a list of summary cards: name + projected key
info (host:port/path, url · role, etc.) + format/report/token badges
+ inline enable toggle + edit/delete buttons. No live-typed fields.
- Create and edit both route through a single NodeEditDialog with
kind-specific field strips; cancel truly discards the draft.
- Per-kind metadata (title, summary projector, defaultEntry factory)
lives in config/defaults.ts so adding a new adapter kind only needs
one descriptor entry.
Behavior preserved end-to-end: same per-UIN config payload, same
useOneBotInstanceConfig hook, same dirty-switch confirm flow, same
save endpoint.
QQ has been pushing Event0x2DC subType=16 every time someone tapped
an emoji on a message in a group, and we were dropping it silently
(only surfacing the PR5 [MsgPush.Unknown] debug line that prompted
this issue). Now we decode it into a first-class event and fan it
out to OneBot clients.
Wire details (cribbed from NapCat's GroupReactNotify transformer):
- body.msgContent has a 7-byte magic prefix; strip before decoding.
- GroupReactNotify { groupUin(4), field13(13), groupReactionData(44) }.
- field13 is a discriminator — same subType is reused for other
notify variants, only 35 means "emoji react". Other values now
fall through to MsgPush.Unknown so we still spot future variants.
- Inside groupReactionData (3-level nested data wrapper, ugh):
code emoji id (system face = numeric str, market = code)
count usually 1
operatorUid needs identity.findUinByUid to resolve to uin
type 1 = add, else = remove
target.seq msg_seq of the reacted-to message
New event kind `group_msg_emoji_like` flows through the standard
pipeline: bridge event → event-bus → converter → OneBot wire.
Converter emits the gocqhttp / NapCat extension shape:
notice_type: group_msg_emoji_like
sub_type: add | remove
group_id, user_id, operator_id, message_id, message_seq,
likes: [{ emoji_id, count }]
message_id is reconstructed via hashMessageIdInt32(msgSeq, groupId,
GROUP_MESSAGE_EVENT) so it matches whatever id the bot originally
handed out for the message being reacted to, even if it's no longer
in the message store.
formatEvent also gets a case so the [Event] log reads cleanly:
表情回应 [群名(123)] | [Alice(99999)] +[76] msgSeq=4242
7 new tests cover the happy path, type=2 (remove), field13!=35
(routed to MsgPush.Unknown), prefix-too-short edge, converter
shape both for add and remove, and the formatEvent string.
closes#42
On accounts with ~200+ groups, fetchGroupList was asking QQ to fill
in every config flag (all 32 bools in config1 plus all 8 in config2)
even though our response decoder reads only groupName / memberMax /
memberCount / customInfo.remark / a handful of named info fields.
QQ NT obligingly packs every requested field into the response. At
group counts >= ~200 the payload is large enough to blow the
named-pipe write buffer on the QQ side; SnowLuma reads EPIPE and
the entire session dies during warmup:
WARN [Hook] pipe error: PID=23928 err=read EPIPE
INFO [OneBot] session closed: UIN=...
WARN [OneBot] failed to load groups for UIN ...: qq_hook client closed
Issue #42 reporter (airline233) bisected the breakage to two
clusters of unused bool flags:
- config1.field5003 (a 5xxx-range expansive descriptor)
- the whole of config2 (per-group aux info we don't decode)
This commit applies exactly their verified safe combination and
inlines a comment so nobody flips them back on without context.
The decoded response shape (groupName, memberCount, memberMax,
remark, etc.) is unchanged.
QQ now rejects fetchUserProfile() with:
[oidb] one of uid/openid is invaild
The cause: SnowLuma's request schema declared field 2 as a
zero-valued uint32 (`field2: 0`) and our encoder doesn't skip 0
varints. Newer QQ NT versions reinterpret field 2 of OIDB 0xFE1_2 as
`uid: string` / `openid: string`, so a varint 0 there decodes as an
empty/invalid uid → server bounces the whole request.
NapCat's equivalent transformer (Oidb.0XFE1_2.ts) emits only `uin`
(field 1) and `key[]` (field 3) — nothing in field 2. Match that
shape exactly.
Effect: warmUpBridgeState's "self info via profile" fallback path
now succeeds for accounts that QQ omits from the friend list, so
the WebUI shows their nickname instead of leaving it blank.
Even the login page leaks "there's a SnowLuma admin panel at this
IP / hostname" to anyone scanning, and right now that page is
publicly indexable. Three overlapping signals so we don't depend on
any one being honoured:
1. Hono middleware on every response sends
X-Robots-Tag: noindex, nofollow, noarchive, nosnippet, noimageindex
Hardest for compliant bots to ignore — it's a header, not
content. noimageindex also covers logo.png / avatar/* from
showing up in image search.
2. A GET /robots.txt route returns "User-agent: * / Disallow: /"
for crawlers that read it before fetching pages. Sits before
the auth middleware so no token is required (otherwise the
crawler would get 401 here, which it'd then refuse to obey).
3. <meta name="robots"> (plus googlebot / bingbot) in index.html
as a fallback for the case where a reverse proxy strips the
X-Robots-Tag header.
The console / subscriber level was captured at module load
(`const MIN_LEVEL = resolveMinLevel()`), so any change to
SNOWLUMA_LOG_LEVEL after Node started had no effect — restart was
the only way to flip levels, which makes "go to debug for 30s to
see what's happening" pretty painful.
logger.ts now keeps `currentLevel` mutable and exports
setLogLevel() / getLogLevel(). The env var still seeds it on
startup; nothing about the boot-time behavior changes. File
transport remains unaffected — it always sees debug-and-up.
WebUI gets two new endpoints, both behind the existing auth
middleware:
GET /api/logs/level → { level, levels }
POST /api/logs/level body → { level: 'debug' } updates it
Logs page picks up a "服务端级别" row of pills next to the
existing client-side filter pills, so an operator can flip the
console firehose on/off in one click without touching env vars
or restarting the bot. The label clarifies that file logging
stays at debug regardless.
After native unload returns, the verification check
if (pipeWatcher.isPipeLive(pid)) { ... unload-failed message ... }
read PipeWatcher's cached snapshot, which is updated every 1500ms.
On Windows clicking "Unload" in WebUI almost always tripped this:
the native unload succeeded and the kernel pipe object was gone, but
the watcher's cached "live" state from the previous tick was still
fresh, so the session reported "DLL卸载失败:命名管道仍然存在" even
though the DLL was successfully unloaded. The user then sees the
status flip back to connecting and waits for a real (cached) refresh.
PipeWatcher already exposes tickNow() for exactly this situation —
the load path doesn't need it because injection's verification runs
async via onPipeUp, but unload verifies inline.
HookSessionDeps.pipeWatcher gains an optional `tickNow` and
unloadInternal awaits it before reading isPipeLive. Existing test
mocks that pass only `{ isPipeLive }` keep working (optional chain
is a no-op there). New regression test covers the production
scenario — stale-true cache flipped to false by tickNow.
The previous commit (257686e) widened printEvent's signature to take
IdentityService but only updated the synchronous call at line 97.
The async post-refresh dispatch path (line 127, called when a group
member join arrives without a resolved uin) still used the old
two-arg form, which CI caught as TS2554. Local tsc somehow didn't
flag it on the editing machine.
Both sites now pass this.deps.identity so the readable rendering
applies to both prompt and post-refresh dispatch paths.
Notice events (recall / join / leave / poke / admin / mute / essence
/ request / invite) and the received-message log now resolve group
IDs and user IDs against the Identity cache so output reads as
human names instead of raw QQ numbers.
Before:
[Event] 群撤回 12345 | 67890 被 99999 撤回
[Event] 群 12345 | NickName(67890): ID:42 你好 [图片]
After:
[Event] 群撤回 [SnowLuma群(12345)] | [Alice(67890)] 被 [Bob(99999)] 撤回
[Event] 群 [SnowLuma群(12345)] | [Alice(67890)]: ID:42 你好 [图片]
Reply segments now expand one level via messageStore.findEvent —
"[回复:42]" becomes "[回复 [Alice(100)]: 早安]" when the original
is still in the message store, falling back to the bare id when it
isn't.
New file utils/event-format.ts owns:
- formatGroup / formatUser identity-aware name resolution
- formatMessageSegments shared element preview (replaces
the inline switch in
logReceivedMessage)
- formatReply one-level reply chain expansion
- formatEvent notice-class event renderer
Every formatter wraps its lookup in try/catch and degrades to the
prior numeric form on cache miss / throw, so log formatting can
never crash the calling path. The QQ numeric ID is preserved
alongside the name so third-party parsers that scrape uids still
find them.
26 unit tests cover cache hit / miss, malformed input, throw
recovery, and per-event-kind rendering shapes.
Two related cleanups so unexpected failures stop being invisible:
void-promise wrappers
Every `void this.something()` fire-and-forget call now has a
.catch(err => log.warn(...)) attached. Affected sites:
- packet-pipeline.ts: dispatchAfterIdentityRefresh
- instance.ts: openAll / applyConfigDiff / closeAll / emitEvent
- http-post-adapter.ts: postEvent
- ws-client-adapter.ts: handleApiMessage
Most of the network-manager fan-outs already isolate per-adapter
errors, but the outer catches guard against future refactors and
surface stack traces immediately rather than as unhandled rejection
warnings.
silent-catch sweep (Bridge.Web)
bridge/web/group-honor.ts, group-essence.ts, group-notice.ts had
`} catch (e) { return undefined; }` patterns that turned every QQ
Web API failure into a silent empty response. Now log.warn with
the full stack first, then return the same fallback so behavior is
unchanged. The commented-out `// console.error(e)` debris is gone.
Plus one console → logger conversion in message-parser.ts (music
sign fallback path).
Highway upload path now emits per-type entry + shared pipeline ops:
DEBUG [Highway.Image] uploading 234567 bytes md5=abc12345... → group 12345
DEBUG [Highway] image OIDB requires bytes, PUT 234567 bytes (sub=top)
DEBUG [Highway] image PUT done in 1234ms
-- or --
DEBUG [Highway] image fast-upload hit (server already had bytes)
The three pipeline-side lines come from runNtv2Upload() and are
shared across image/video/ptt; the per-type entry log lives in each
*-upload.ts wrapper so the scope identifies the media kind. md5 is
truncated to its first 8 hex chars for line width; PUT latency is
reported in ms.
MsgPush silent dispatch defaults are now visible at debug:
DEBUG [MsgPush.Unknown] no decoder for PkgType=999 subType=0
DEBUG [MsgPush.Unknown] Event0x2DC unknown subType=42
DEBUG [MsgPush.Unknown] Event0x210 unknown subType=42
Captures protocol drift (new NT QQ subtypes) and "we forgot to
register this PkgType" oversights, neither of which used to leave
any trace in the log.
All new lines are debug-level so console output (default info) stays
unchanged; file transport sees them for post-mortem.
Every OneBot action call now emits a single debug line under
[Bridge.Action]:
DEBUG [Bridge.Action] send_group_msg group_id=12345 message=[len=3]
On failure, dispatch logs a warn with the full stack instead of
silently folding the error into the response. Unknown actions also
get a debug entry so "the bot is ignoring me" is no longer invisible.
Notes:
- New summarizeParams() helper caps each value at 40 chars / line at
200 chars to keep arrays / nested payloads from blowing the line
width. Lives in utils/log-summary.ts for reuse (highway will too).
- ApiHandler now takes an optional uin and binds a child logger so
per-account file routing works. OneBotInstance passes its parsed
uin.
- Control-char strip in logger/file-transport was exempting only ESC;
also exempt TAB (0x09) and LF (0x0A) so stack traces stay
multi-line in both console and file output.
- vitest.config sets SNOWLUMA_LOG_LEVEL=debug so the ring buffer
receives the new debug entries that tests assert on.
Switches the per-account classes from module-level loggers to
per-instance ones derived via Logger.child({ uin }) so their log
lines land in both the shared file and the account's logs/<uin>/
sub-file, and the [UIN] slot appears in console output:
- IdentityService (Identity scope)
- IncomingPacketPipeline (Bridge + Event scopes)
- OneBotInstance (Event scope)
- HttpServerAdapter (OneBot.HTTP)
- HttpPostAdapter (OneBot.POST)
- WsClientAdapter (OneBot.WS-Client)
- WsServerAdapter (OneBot.WS-Server)
The standalone printEvent() in packet-pipeline now takes a Logger
argument so it routes through this.eventLog instead of a captured
module-level reference. Behavior unchanged otherwise; bridge.ts,
bridge/manager.ts and process-level scopes (App / WebUI / Hook /
OneBot.Config) keep their module-level loggers since they aren't
bound to a single account.
Logger now supports deriving a UIN-bound child:
const log = createLogger('Bridge');
this.log = log.child({ uin: this.uin });
The child stamps a fixed-width [UIN] slot into rendered lines so the
[Scope] column stays vertically aligned, and routes the same line to
a per-UIN sub-file:
logs/snowluma-YYYY-MM-DD.log (shared, all UINs)
logs/<uin>/snowluma-YYYY-MM-DD.log (per-account)
Both pathways share daily rollover, size cap, and retention.
LogEntry now carries uin so SSE subscribers (WebUI) can filter later.
Other meta keys passed to child() are preserved in opts.meta for
forward compat (requestId / traceId etc.) but not rendered yet.
Module-level callers are unchanged; no callsites migrated in this PR.
SNOWLUMA_LOG_PER_UIN=0 disables the per-account sub-file while
keeping the shared one.
Adds a hand-rolled FileTransport that fans out every log line (debug
and up, regardless of console filter) to
./logs/snowluma-YYYY-MM-DD.log. When the current file exceeds the
configurable size cap it rolls into snowluma-YYYY-MM-DD.1.log, and
files older than the retention window are unlinked at startup and on
each day rollover.
Config (all env, no settings.json):
- SNOWLUMA_LOG_FILE 0 to disable file output (default: on)
- SNOWLUMA_LOG_DIR output directory (default: ./logs)
- SNOWLUMA_LOG_MAX_MB per-file cap, MB (default: 50)
- SNOWLUMA_LOG_RETAIN_DAYS retention window (default: 7)
closeLogger() awaits the WriteStream's finish event; SIGINT and
SIGTERM handlers now await it before process.exit so the buffer
makes it to disk.
vitest config sets SNOWLUMA_LOG_FILE=0 to keep the suite from
polluting cwd; the new tests under tests/log-file-transport.test.ts
flip it back on per-test against a tmpdir.
For a private send_private_forward_msg, the inner image/record/video
needs an OIDB upload scene — but uploadForwardNodes never received the
recipient, so the SendContext fell back to {bridge} only and the
element builder threw "private image target uid is missing".
Plumb userId through uploadForwardNodes → buildForwardPushBody and,
when the nodes contain media, resolve it to a uid via
bridge.resolveUserUid() once up-front. Group forwards are unchanged
(they already passed groupId). Mirrors NapCat's design where the
destination peer is threaded all the way down to createSendElements.
If the operator never completed the forced-change flow, the plaintext
bootstrap password was unrecoverable on the next start (only the hash
remained on disk, and the prior log line was likely gone). Now we
detect a persisted state with mustChangePassword=true at load time and
generate a fresh CSPRNG password so the operator can actually log in.
The initial-credentials log block is also wrapped with separators and
a bilingual notice so it stands out at boot. The
'initial credentials: user=admin password=%s' line is preserved
verbatim because third-party launchers parse it.
Mirror of sdk-npm-publish.yml for the UI package. Same triggers
(packages/ui/** + lockfile/workspace/tsconfig.base) and same
already-published guard via `npm view`, so reruns are idempotent.
Differences from the SDK workflow:
- Drops the `test` step (UI package has no Vitest suite yet).
- Filters and working-directory point at packages/ui.
Auth uses the same `NPM_TOKEN` secret in the SnowLuma environment.
Publishes with `--provenance` so the npm registry attests the build
came from this exact GitHub Actions run.
Desktop is switching from the native Windows titlebar to a custom one
rendered in the renderer (frameless BrowserWindow + custom Min/Max/Close).
The bar is 32px tall — the same height Windows draws its system
titlebar — so expose it as a token here for any future Desktop layout
that needs to subtract it.
Desktop's core-download dialog needs to show progress while the server
returns no Content-Length (some mirrors omit it; the SnowLuma core
release artifact does have it but GitHub's CDN sometimes strips it on
redirects). Hard-coded 50% was a placeholder.
Add an `indeterminate` boolean prop: when true, render a marquee bar
that animates left-to-right indefinitely. When false, render the
familiar bytes-done / bytes-total fill at `value%`. Hooked up via a new
`@keyframes progress-marquee` in theme.css.
Also dropped the bar's CSS transition from 500ms → 200ms so live
download updates feel responsive instead of laggy.
Polish pass that an earlier edit lost:
- Add `success` and `warning` button variants (semantic colour pairs
consumers can reach for in confirm dialogs / status actions).
- Outline gets a real card background + shadow so it pops on tinted
surfaces (previously bg-transparent looked invisible on muted/40 rows).
- Tighter motion: explicit transition list + `active:translate-y-px` so
clicks feel mechanical.
- New size `icon-xs` for inline action buttons that need to fit in a
log-row toolbar without ballooning the row height.
- Default radius bumped to `rounded-lg`; sm stays `rounded-md`.
CSS grid's default `min-width: auto` per track was letting long
selected-option text and file paths inside dialogs push the container
past its `max-w-lg` cap, which on Windows / smaller viewports clipped
the right edge of inputs and the Select chevron.
- DialogContent / AlertDialogContent: `grid-cols-[minmax(0,1fr)]` clamps
the single track to its container width; `w-[calc(100%-2rem)]` keeps
a 1 rem gutter to the viewport edge on small screens.
- SelectTrigger: `min-w-0` on the trigger itself plus a child-targeted
truncate (`[&>span:not([data-radix-select-icon])]:truncate`) so the
selected text shrinks before the chevron does; chevron gets `shrink-0`
for the same reason.
Both controls used `bg-muted` / `bg-background` for unchecked / thumb
which collapse to the same hue as the surrounding card in dark mode,
making them effectively invisible.
- Switch: unchecked track now bg-input (light) / bg-muted-foreground/25
(dark) with a shadow-inner; thumb uses bg-card (light) /
bg-foreground/95 (dark) so it pops in both states.
- Checkbox: explicit bg-card + hover:border-border/80; slightly larger
radius (5px) for visual rhythm with the rest of the surface.
Static JSON served from raw.githubusercontent.com/.../main/compat/qq.json
that SnowLumaDesktop polls (3-day cached fallback) to classify the local
QQ install as known-good / known-bad / unknown / too-old.
- compat/qq.json — initial allow-all manifest (policy.allowUnknown=true)
- compat/qq.schema.json — JSON Schema for the manifest shape
Editing this file is how we ship "QQ X.Y.Z breaks Hook" advisories
without cutting a Desktop release.
Two additions for trusted local launchers (notably SnowLumaDesktop) to
configure core without writing to disk-shared config:
- SNOWLUMA_WEBUI_PORT overrides runtime.json's webuiPort at startup
without persisting; CLI/Docker users continue to drive it from the
file. Mirrors the existing SNOWLUMA_HOOK_RUNTIME_DIR / *_TRUST_PROXY
conventions.
- SNOWLUMA_WEBUI_BOOTSTRAP_PASSWORD seeds the initial WebUI password on
first launch (when webui.json doesn't yet exist), with
mustChangePassword=false. After the file is persisted the env var is
ignored — password rotation continues through the UI.
PR #39 hardened most of the OneBot action surface but left download_file
on the original `await response.arrayBuffer()` path — an authenticated
client could still hand us a multi-GB URL (or a chunked response with no
Content-Length) and OOM the bot. The base64 branch had the same problem
in the other direction: `Buffer.from(huge, 'base64')` allocates the
decoded payload before any size check.
Match the loadBinarySource pattern that `0804351` introduced for
highway uploads:
* HTTP path runs through `fetchDownloadFile`: AbortSignal.timeout
(60s), Content-Length precheck, then a streaming reader that aborts
the moment the running total crosses the 1 GiB cap.
* Base64 path rejects before `Buffer.from` based on the
upper-bound `floor(len * 3 / 4)`, with a post-decode check for
safety.
* Writes go through `fs.promises.writeFile` so a multi-hundred-MB
download doesn't stall every other bot action on the event loop.
Also drop the `actionFailed` helper added in the same PR — it was
intended as a sanitized-error wrapper but never wired up. Wiring it
into the dozen-or-so `String(e)` sites is its own cleanup; for now
remove the dead code (and the no-longer-used createLogger import).
The previous commit tightened login rate-limiting to key off the real
TCP socket peer, which fixed the X-Forwarded-For bypass but had the
known caveat of collapsing every client into a single global bucket
when the WebUI runs behind nginx / Caddy / a SaaS CDN.
Give operators an explicit, audited way to opt back into per-client
keying without re-introducing the spoof:
* `SNOWLUMA_WEBUI_TRUST_PROXY` env var. Modes:
- unset / empty → keep socket peer (safe default, unchanged)
- "loopback" → trust X-Real-IP / X-Forwarded-For when the
immediate socket peer is 127.0.0.1 / ::1
(nginx + WebUI on the same host)
- "1" / "true" / → trust headers from any peer (only safe behind
"all" a SaaS proxy that strips client-set headers)
- comma-separated → trust headers only when the socket peer
IP list matches one of these (proxy on another box)
* When trusting headers we prefer X-Real-IP (single value the proxy
overwrites unconditionally) and fall back to the first hop of XFF.
We deliberately do NOT walk the full XFF chain — without a fully
trusted proxy chain the leftmost value is still spoofable; a
single-tier proxy is the only setup this app realistically sees.
* Boot log prints "login rate-limit keyed by: …" so operators can
verify the mode took effect, plus an extra WARN for "all" reminding
them it's only safe with header-stripping in front.
Logic lives in webui/client-ip.ts as a pure pickClientIp() that takes
a socket-IP resolver, so the trust-proxy matrix can be exercised
without standing up a server — see webui-client-ip.test.ts for the
11 new unit tests covering parse + dispatch + loopback / list / all /
none modes.
Smoke-tested with SNOWLUMA_WEBUI_TRUST_PROXY=loopback:
- 5× failed login w/ X-Forwarded-For: 1.1.1.1 → 401
- 6th attempt same XFF → 429 (locked, per-XFF)
- 6th attempt X-Forwarded-For: 2.2.2.2 → 401 (fresh bucket)
- X-Real-IP overrides XFF when both present
QQ's short-video element protocol hard-limits a single video at 100 MB
(NapCat enforces the same cap in highwayContext.uploadVideo with the
same threshold and tells operators to switch to file upload). Mirror
that hint so OneBot bot authors who hit the cap immediately see the
correct alternative — `upload_group_file` / `upload_private_file`,
which ride the FtnUpload path and go up to 4 GiB — instead of having
to read the docs to figure out why a send_msg with a 200 MB video
silently 'won't work'.
Follow-up on the previous highway commit, addressing two real holes the
Copilot review caught:
* loadBinarySource HTTP path was buffering the entire response via
`await resp.arrayBuffer()` BEFORE length-checking. A server that omits
or understates `Content-Length` (chunked transfer, malicious upstream,
proxy stripping headers) bypassed the cap entirely. Switch to a
streaming reader: accumulate chunks, abort + reject as soon as the
running total exceeds `maxBytes`. The Content-Length precheck still
short-circuits the obvious case before we read a byte.
* video-upload `stageVideoSource` has its own local-path fast-path that
never went through `loadBinarySource`, so the 100 MB MAX_VIDEO_SIZE
guard ran AFTER `fs.readFileSync` had already allocated the entire
file. A 10 GiB local-file pointer would OOM the bot before the check
fired. Add an `fs.statSync` precheck on the local branch, and pass
`MAX_VIDEO_SIZE` explicitly when the source falls through to
`loadBinarySource` so the HTTP / base64 cap matches the on-disk one.
Update the DEFAULT_MAX_BINARY_SIZE comment to stop claiming video paths
are bounded by it — they're bounded by the smaller MAX_VIDEO_SIZE,
enforced inside video-upload.
Adds five regression tests:
- chunked streamed download (no Content-Length) over cap → throws
- Content-Length over cap → throws before reading body
- streamed download inside cap → returns full bytes
- local file over cap (statSync precheck) → throws
- base64 over cap → throws
* highway/utils detectImageFormat: JPEG SOF marker check now excludes
0xC4 (DHT), 0xC8 (JPG), and 0xCC (DAC). The old `(marker & 0xFC) ===
0xC0` matched DHT et al. and then read Huffman table bytes as image
dimensions, producing junk width/height for many real JPEGs.
* loadBinarySource takes an optional maxBytes; defaults to 1 GiB to
defend against an authenticated client triggering a multi-GB load
into memory. Group/private file uploads pass FILE_UPLOAD_MAX_BYTES
(4 GiB) because QQ's file protocol legitimately supports that size.
HTTP fetches also pick up a 60s timeout and a Content-Length precheck.
* highway-client.tcpConnect detaches its error/timeout listeners after
a successful connect so subsequent upload IO errors don't reject an
already-resolved promise. readHttpResponseBody uses local listener
refs + a central detach(), eliminating MaxListenersExceededWarning
during multi-chunk uploads.
* hook/qq-hook-client.nextRequestId now wraps inside uint32 explicitly
and skips id 0 / in-flight ids. The previous `nextRequestId++ >>> 0`
loses precision past Number.MAX_SAFE_INTEGER (postfix increment
evaluates before the shift) and could collide live request ids on
very long-running processes.
* identity-service.rememberUidUin removes stale partner entries before
inserting a new (uid, uin) pair. The old code left orphan uidByUin /
uinByUid entries after a uid/uin re-bind, so the two maps could
disagree.
Action-layer fixes, all cross-checked against NapCat's reference
implementation in packages/napcat-onebot:
* download_file (extended.ts:539) now sanitizes `name` via
path.basename + resolve/relative containment check. Previously an
authenticated client could write `../../config/onebot_<uin>.json`
and replace access tokens / webhook URLs.
* mark_group_msg_as_read / mark_private_msg_as_read / mark_msg_as_read
fall back to meta.targetId when the optional group_id/user_id arg
is missing. The old code passed 0 to the Bridge. NapCat resolves the
peer from message_id alone in MarkMsgAsRead.ts; we now match that.
* set_friend_remark / set_group_remark refuse a missing `remark` field.
The previous `asString(...) ?? ''` silently CLEARED the remark for
any client that forgot the parameter. NapCat's typebox schema makes
`remark` required; we now do the same.
* upload_forward_msg threads `group_id` down to uploadForwardNodes so
the resulting resId lives in the correct namespace (type:3 + groupUin
vs type:1 + selfUid — see bridge/actions/forward.ts). NapCat passes
`peer.chatType === GROUP ? +peerUid : 0` for the same reason.
ApiActionContext.sendForwardMsg + uploadForwardMessage signatures
pick up an optional groupId.
* Private-message reply meta now resolves senderUin from the cached
event (real sender), with a self-id fallback when only meta exists
(bot's own outbound message — `cacheMessageMeta` does not populate
the event row). The old code used meta.targetId, which is the
conversation peer — wrong when the bot replies to its own message.
* message-parser:
- intOr(value, fallback) helper replaces parseInt(String(...)) at
face/at/reply/image/xml/poke/node sites so non-numeric input no
longer produces NaN downstream. Invalid face ids skip the
element rather than emit NaN.
- cqUnescape decodes `,` (escaped comma) — the OneBot 11 spec
requires it and clients in the wild emit it.
* Drop the dead Array.isArray(rawAuth) branch in onebot/network/utils
(Node's headers.authorization is `string | undefined`, never an
array) and the unused WebHonorType import in api-handler.
Stack of WebUI fixes prompted by an internal security/correctness pass:
* getClientIp now resolves the real socket peer via @hono/node-server's
getConnInfo helper instead of trusting `X-Forwarded-For`. The previous
behaviour let any client rotate that header to bypass the 5-attempts/
15-minute login lockout.
* `?token=` is restricted to /api/logs/stream (the only endpoint that
can't use the Authorization header, because EventSource lacks custom
headers). Other routes used to leak tokens via access logs / Referer
/ browser history.
* change-password now invalidates every session (including the current
one) and signals requireRelogin. Keeping the current token alive made
the rotation pointless if the old credentials were already in an
attacker's hands.
* GET /api/config/:uin no longer writes defaults to disk and no longer
doubles up the payload (`{config}` only, dropping the {…config, config}
legacy shape). Frontend's `data?.config ?? data` fallback still works.
* webui.json is moved to .bak.<ts> instead of being silently overwritten
when it fails to parse — losing the prior hash silently was rotating
operator credentials with no warning.
* Process load/unload/refresh routes are deduped into a single helper;
internal error messages are logged but no longer surfaced verbatim to
the client.
* SSE log stream tolerates a closed controller (try/catch around enqueue
+ central teardown) and runs an unref'd janitor to GC expired session
tokens + login attempt counters every minute.
GET on a load helper used to mint a fresh access_token and write it to
disk whenever the per-UIN file was missing or in legacy format. Reading
should not have side effects, and the WebUI's read-only GET handler in
particular was racing on concurrent requests and surprising operators
with materialized config files.
Introduce a `{ persistDefaults?: boolean }` option (default false). The
two boot-time call sites in `OneBotManager` (onSessionStarted, reloadConfig)
opt in explicitly; WebUI's GET path will rely on the new default once
that side of the patch lands.
Also stop reviving default 0.0.0.0 listeners when the operator has
explicitly emptied every adapter — only seed defaults on a true fresh
install (no per-uin and no global config on disk).
Drop the unused deepClone / deepMerge helpers; tryLoadJson now logs a
warning instead of silently swallowing JSON parse errors.
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.
- P0-1: restore customExt field in SetStatusReqSchema
- P0-2: remove duplicate setGroupAvatar implementation
- P1-3: add attach_info pagination support for get_group_album_media_list
- P1-5: clean up commented console.log statements
- P1-6: remove raw field from GroupAlbumMediaResult
OneBot clients commonly send [CQ:at,qq=12345] without a name field; we
were piping `@12345` into the text element so QQ rendered the bare uin
instead of the member's card/nickname (napcat resolves via getGroupMember
before encoding). Move the fallback into the element builder so it
consults the IdentityService roster and only falls back to the uin when
the roster has nothing.
The four-page switch lived as a string union (Page) plus an if/else
chain in AppInner, with TopBar reverse-importing Sidebar's NAV_ITEMS
to find the icon for the active tab. Adding a page touched four
places and there was no URL, no history, no deep-linking.
Move routing behind @tanstack/react-router with a layout route
(AppLayout) that owns the polling lists, processOps, selectedUin
and the unload-failed alert; child routes render through <Outlet/>
and read shared state from a new AppStateContext. AuthBoundary still
gates login / forced-password-change above the router. Sidebar uses
<Link> + useRouterState for active state; TopBar and MainLayout look
up the current path the same way.
Behaviour-preserving:
- LoginPage / ChangePasswordPage still mount above the router.
- AppLayout never unmounts during navigation, so selectedUin,
processOps state, the polling state and the unload-failed dialog
all survive page switches just like before.
- Logout calls history.replaceState('/') so the next login lands on
the overview page, matching pre-router behaviour.
- The sidebar-active-pill layoutId animation and the page-transition
AnimatePresence are preserved, keyed off pathname instead of the
removed `active` prop.
New URLs (/, /config, /logs, /settings) work on refresh because the
backend already had SPA fallback in core/src/webui/server.ts. Bundle
grows ~84KB (gzip +27KB) for the router runtime.
Two regressions slipped into the ApiClient/ConfigPage refactor:
1. api.config.save() ran the POST response through normalizeOneBotConfig
and used it to overwrite local state. But POST /api/config/:uin
returns { success, reloaded, message } — no config body — so the
normaliser produced an empty config and wiped the user's edits as
soon as the save succeeded. Honour the "save returns canonical view"
contract by following the POST with a GET inside the client; the
round-trip stays hidden behind the seam.
2. selectedUin lived inside useOneBotInstanceConfig, so navigating away
from ConfigPage unmounted the hook and lost the user's selection.
Lift selectedUin to AppInner and make the hook externally controlled
via { selectedUin, onSelectedUinChange }. Clear it on logout.
App.tsx held three copy-pasted handlers (load / unload / refresh) and
three parallel processXxxPid state slots that were mutually exclusive
but unenforced by the type system. The unload-failed alert was a
separate path, and OverviewPage needed 11 props to drive the table.
Extract useHookProcessOps: one inflight Set for dedup, one Map<pid,
OpKind> for view state, one run() that branches on kind via a
message table, and ownership of the unload-failed alert. OverviewPage
takes a single HookProcessOps prop and queries statusOf(pid).
App.tsx 270 → 216 LOC; OverviewPage props 11 → 7.
App.tsx was the single source of truth for token, fetch policy, 401
handling, and per-UIN config edit state — fetchApi was drilled into
every page and LogsPage read localStorage directly to build its SSE
URL, giving two parallel truths for the bearer token.
Promote the closure to a deep ApiClient module (domain methods +
request() escape hatch) injected via ApiProvider/useApi, and lift
selectedUin/config/saveStatus into useOneBotInstanceConfig so
ConfigPage is self-contained. normalizeOneBotConfig becomes a pure
function. ConfigPage now guards UIN switches when the editor is
dirty and refetches the server-normalised config after save.
ConfigPage prop count drops from 7 to 1; App.tsx from 421 to 270 LOC.
`actions-sync.test.ts` walks every `registerAction(...)` in
`@snowluma/core/src/onebot/actions/` and asserts the SDK's exported
list matches. The napcat-parity work (Tier 1 + Tier 2 + Tier 3 + AI
voice) added 14 actions to core without ever touching the SDK, so the
test caught the drift:
bot_exit cancel_group_todo
complete_group_todo delete_group_folder
get_ai_characters get_ai_record
get_group_ignore_add_request
nc_get_packet_status nc_get_rkey
nc_get_user_status
send_group_ai_record send_packet
set_diy_online_status set_group_todo
Added them to `SNOWLUMA_ACTIONS` and gave each one a typed
`SnowLumaActionMap` entry. Where the request body shape is non-trivial
(AI voice, group todo, DIY status, send_packet, nc_get_user_status),
introduced dedicated param types in `types/params.ts`; where the
response is structured (AI character list, user-status word),
introduced result types in `types/results.ts`. Everything else routes
through `JsonObject` / `EmptyData` so the SDK surface stays small.
Verified:
pnpm --filter @snowluma/sdk typecheck → clean
pnpm --filter @snowluma/sdk test → 17/17 pass
Private-chat video and voice sends were getting bounced by the QQ NT
server with `PbSendMsg result=79`. Highway upload logs said success,
but the final SendMsg the bot constructed used the group-scene tag
inside the outgoing commonElem, and the c2c routing path doesn't
recognise it.
The convention — verified against the receive-side decoder at
msg-push/rich-body-decoder.ts:261-330 which explicitly branches on the
pairs — is:
image : commonElem.businessType c2c=10 group=20
video : commonElem.businessType c2c=11 group=21
record : commonElem.businessType c2c=12 group=22
makeImageElem already honoured the split (`isGroup ? 20 : 10`).
makeVideoElem and makePttElem hardcoded the group value for both
scenes. Fix them to follow the same pattern.
Also fix a symmetric asymmetry inside the highway upload itself:
uploadVideoMsgInfo hardcoded `compatQmsgSceneType: 2` while
uploadImageMsgInfo and uploadPttMsgInfo both use `isGroup ? 2 : 1`.
Same root cause — group value leaking into the c2c path.
Regression test (tests/element-builder.test.ts) pins all six
businessType pairs by mocking the highway upload functions and
inspecting the proto element the builder returns; would have caught
the bug had it existed at the time element-builder.ts was written.
Port the Lagrange.Core protocol path for group avatar upload —
napcat's NTQQ GroupService.setHeader has no oidb wrapper, but
Lagrange.Core/Internal/Context/Logic/Implementation/OperationLogic.cs
spells out the wire shape: same highway HTTP endpoint as personal
avatar, but with cmdId=3000 and a GroupAvatarExtra proto carried as
the `extend` blob (type=101, groupUin, field3={field1=1}, field5=3,
field6=1 — all four are protocol-prescribed constants).
Adds:
- GroupAvatarExtraSchema in proto/oidb-action.ts
- bridge.setGroupAvatar(groupId, source) wrapping the highway upload
- BridgeInterface.setGroupAvatar
- OneBot set_group_portrait action (was a stub returning
'not yet implemented'; accepts the same file-source variants as
set_qq_avatar)
5 new tests: 3 bridge-action (cmdId, extra-blob round-trip, empty-file
guard) + 2 OneBot (forwarding, param validation) — also tightens the
existing setAvatar test to assert the extend blob stays empty.
DIY online status reuses the existing StatusService.SetStatus wire
call. napcat hardcodes status=10 / extStatus=2000 and threads the
faceId / wording / faceType through a customExt sub-message (field 4
of SetStatus, per napcat packet/transformer/proto/action/action.ts).
Implementation:
- Extend SetStatusReqSchema with optional customExt field. Encoder
skips undefined fields so the existing set_online_status path stays
byte-identical on the wire (verified by a new round-trip test).
- New bridge.setDiyOnlineStatus(faceId, wording, faceType) wraps the
same dispatchSetStatus helper as setOnlineStatus.
- OneBot action set_diy_online_status accepts napcat-style payloads
(face_id / face_type can be string or number; wording defaults to '').
9 new tests across actions/profile and onebot/extended-actions.
Wires 16 OneBot actions that napcat exposes but SnowLuma previously
either lacked or stubbed:
Tier 1 (pure glue over existing Bridge capabilities)
- send_packet / .send_packet: real impl over Bridge.sendRawPacket
- bot_exit, nc_get_packet_status, nc_get_rkey
- get_group_ignored_notifies / get_group_ignore_add_request: project
fetchGroupRequests(filtered=true) into napcat shapes (was empty stub)
- delete_group_folder alias for delete_group_file_folder
Tier 2 (new oidb proto + Bridge method)
- set_/complete_/cancel_group_todo (oidb 0xF90_1/2/3)
- nc_get_user_status (oidb 0xFE1_2 with napcat's status decode)
- get_ai_characters / get_ai_record / send_group_ai_record (oidb
0x929D / 0x929B; AI voice reuses the existing fetchGroupPttUrlByNode)
BridgeInterface now exposes sendRawPacket as the deliberate escape
hatch for send_packet — every other surface method already wraps it.
46 new tests: 13 bridge-action (mocked runOidb dispatch checks) + 33
OneBot-action (ApiHandler.handle end-to-end).
50 onPipeUp/onPipeDown cycles → at most 1 live FakeClient, zero
listeners on every torn-down client. E2E variant additionally asserts
BridgeManager.onHookLogin / onPidDisconnected / onPacket are never
called, so no Bridge / Identity / OneBotInstance is allocated.
These prove no leak exists at this layer. Investigated after a Docker
OOM report which turned out to be QQ Browser GC-thrashing while idle on
the login screen (75-second LongTask entries from PID 61 in the report).
The 885-line msg-push-handler.ts is replaced by bridge/msg-push/:
8 per-PkgType decoders plus MsgPushRegistry (single decoder per
PkgType, catch + log on error), MsgPushContext (header decoded
once at entry), and rich-body-decoder (one deep function hides
~400 lines of element conversion shared by all three message
types).
parseMsgPush(pkt, identity) signature preserved; existing tests
pass with an import-path change only.
Adds toHexUpper alongside toHex in utils/hex.ts. Routes
group-file's bytesToHexUpper through it so the incoming
msg-push split can share one implementation.
Refocus CONTRIBUTING.md on first-time contributor onboarding (setup,
PR flow, conventions) and move the release/auto-merge workflow into a
clearly labeled maintainer section. Adopt Contributor Covenant v2.1
as the project Code of Conduct, pointed at the QQ/TG channels.
instance-context.ts used to declare ~130 closures inside buildApiContext,
mirrored by ~130 method signatures on ApiActionContext. About 38 of
those were pure 1:1 pass-throughs — `setGroupAdmin: (gid, uid, en) =>
bridge.setGroupAdmin(gid, uid, en)`, `setOnlineStatus`, `setProfile`,
`setAvatar`, `markGroupMsgAsRead`, `getCookiesStr`, `getCsrfToken`,
`getCredentials`, the lot of them. Each was three places to edit (the
closure, the interface signature, the action call site) and zero added
value: the OneBot name matched the Bridge name and no defaults / rename
/ composition was happening.
Expose `bridge: BridgeInterface` on ApiActionContext and have action
handlers route through `ctx.bridge.<name>` for those cases. The 38
closure declarations go away; ApiActionContext shrinks from ~70 method
signatures to ~30; instance-context.ts loses ~50 lines of boilerplate.
The ~30 adapter closures stay — every one of them does real work:
- Renames: setGroupKick → bridge.kickGroupMember, sendFriendPoke →
bridge.sendPoke(false, …), handleDeleteFriend → bridge.deleteFriend
- Field extraction: uploadGroupFile returns result.fileId, not the
full {fileId} envelope
- Baked constants: setEssenceMsg passes `true`, deleteEssenceMsg
passes `false` to the shared setEssenceMessage module function
- Compositions: sendPrivateMessage / sendGroupMessage / setMsgEmojiLike
need messageStore + mediaStore + bridge wired together
- OneBot-specific defaults: getProfileLike defaults start=0 limit=10,
getGroupEssence defaults pageStart=0 pageLimit=50
Two small downstream nudges that fell out of the type changes:
- extended.ts:99 — `essenceDataAll.flatMap(res => …)` now needs an
explicit `(res: any)` since bridge.getGroupEssenceAll returns
`Promise<any>`, not the previously-asserted `GroupEssenceMsgRet[]`.
- extended.ts:835 — `okResponse(clientKeyInfo)` widened via spread to
`okResponse({ ...clientKeyInfo })` because `ClientKeyInfo` is a
named interface (no index signature) and okResponse expects
JsonValue/JsonObject. Behavior identical; the response shape is
unchanged.
402 tests pass (the OneBot contact-actions test added in PR6 doubles as
regression coverage for the seam).
First OneBot unit test that proves the BridgeInterface seam (PR4)
delivers real testability. The fake bridge is a Proxy over a tiny
override map — un-stubbed methods throw with a clear message, so each
test only spells out the surface it actually exercises, and a missing
stub never silently passes.
Covers the five contact-actions read paths users hit most through the
OneBot API: getLoginInfo / getFriendList / getGroupList / getGroupInfo
/ getGroupMemberList / getGroupMemberInfo / getStrangerInfo — 19 cases
spanning happy path, network-fail fallback to identity cache,
noCache=true forcing a refetch, and missing-data nulls. No SQLite, no
native packet sender, no BridgeManager — just BridgeInterface.
Bridge.onPacket previously inlined 5 distinct responsibilities (cmd
dispatch, identity-refresh decision, async member-roster refresh,
side-effect persistence, event emission) plus all the helper state
(cmdHandlers_, memberRefreshTasks_) and the per-event printer. Move
the whole stage chain into bridge/packet-pipeline.ts as
IncomingPacketPipeline, keeping the orchestration single-owned and
testable without booting Bridge.
The pipeline's public surface is three methods — registerCmd /
handlesCmd / process — plus a single constructor dep bag. Internally
the stage order is exactly as before:
parse → enrich identity (sync, or async refresh)
→ side-effects (rememberX on Identity + coalesced roster refresh)
→ log
→ emit on the typed event bus
Bridge keeps the protocol-layer methods (sendRawPacket,
fetchGroupList, fetchGroupMemberList, etc.) and injects
refreshMemberCache as the one pipeline dep that touches the wire.
Bridge.onPacket / registerCmd / handlesCmd are now thin pass-throughs
so the existing external test (RefreshingBridge extends Bridge,
bridge.onPacket(makePacket()) → expects forced member fetch) keeps
working unchanged.
Net diff: bridge.ts shrinks by ~245 lines; packet-pipeline.ts is
~225 lines; one dead helper (elementsToText) deleted on the way out.
Runtime behavior is byte-identical — verified by tests/bridge-member-identity.test.ts
covering the full async-refresh path.
OneBot used to depend on the concrete Bridge class — 778 lines, ~99
public methods including PID management, raw packet dispatch, and cmd
handler registration that no external consumer should touch. Add an
explicit BridgeInterface (bridge/bridge-interface.ts) enumerating only
the surface OneBot actually reads (verified by grepping every bridge.*
access in onebot/), and have Bridge `implements BridgeInterface` so the
compiler enforces alignment.
Net effect at runtime: zero — Bridge's methods, fields, and bodies are
unchanged; the interface is a TypeScript-only declaration. Net effect
for typing: the OneBot package (instance, instance-context,
instance-rkey, manager, media-url-resolver, and the modules under
onebot/modules/) now imports `BridgeInterface` instead of `Bridge`, so
tests / fakes can satisfy the interface without subclassing or pulling
in the SQLite/native bits.
In-tree bridge actions (actions/*, bridge-contacts, highway) keep their
concrete `Bridge` typing — they legitimately need sendRawPacket and
other low-level entry points that intentionally stay off the
interface.
bridge-oidb.ts used to expose three thin functions —
makeOidbRequest / sendOidbAndCheck / sendOidbAndDecode — and every
action file repeated the same five-step envelope assembly with long
positional argument lists. Collapse them into one `runOidb(bridge,
call)` taking an OidbCall object: cmd / oidbCmd / subCmd / request
{ schema, value, isUid? } / response? { schema }.
Behavioural contract is preserved:
- No `response`: verify success + gotResponse, peek envelope retCode
iff response data is present (fire-and-check semantics).
- With `response`: require responseData, decode through the base
schema, validate retCode, return the inner body typed as TResp.
Migration touches 51 call sites across 9 source files (bridge-contacts,
actions/{group-file, group-admin, profile, group-message, friend,
interaction, misc}, web-actions/cookies) plus 9 test files that used
to assert on positional `.mock.calls[0]![4]` indices and now read
through `.mock.calls[0]![1].request.value` / `.cmd` / `.oidbCmd`.
Net effect: callers now name what each piece is for, and adding
cross-cutting OIDB behaviour (retry / timeout / per-cmd logging) is a
single-site change inside runOidb instead of a sweep across 9 files.
QQInfo's in-memory state (self identity, friends, group rosters,
profile cache) and read methods (findFriend / findGroup /
findGroupMember / findUserProfile / nickname / uin / selfProfile) now
live directly on IdentityService. The QQInfo class is gone; its
interfaces stay in `qq-info.ts` as plain types shared across the
remember*/find* surface.
This eliminates a long-standing duplication: every observation used to
maintain both QQInfo's in-memory structures and IdentityService's
SQLite mirror in parallel, with the uidByUin/uinByUid Maps tracked
separately. With one Module owning all three layers, every remember*
hydrates one set of structures and `loadSnapshot` repopulates the
in-memory uid↔uin index from SQLite on startup — closing the cold-cache
gap that previously forced findUidByUin to fall through to a SQLite
query after every restart.
Knock-on changes:
- `Bridge` no longer holds a QQInfo; constructor takes an
`IdentityService`. The CmdParser signature on the cmd dispatch
table now passes `IdentityService` to parsers.
- `msg-push-handler.ts` drops its private `resolveUidToUin(qqInfo, …)`
helper that bypassed IdentityService's cascade — the parser hot
path now reads through `identity.findUinByUid(uid, groupId)` and
benefits from the O(1) `uinByUid` map even on freshly-loaded
sessions.
- `BridgeManager`'s session-started callback drops the QQInfo
parameter; OneBotInstance no longer carries a `qqInfo` field and
exposes a `nickname` getter for the WebUI listing.
- `contact-actions` and the per-theme bridge action files stop
importing QQInfo; they read everything via `bridge.identity.*`.
Pull the cache→DB→network-fetch fallback cascade for UIN→UID translation
into a single async `resolveUid` on IdentityService, and drop the
duplicated `resolveUserUid` helper that used to live in bridge-oidb. Bridge
injects itself as the IdentityFetcher post-construction so the network
fallback runs through the same OIDB profile fetch the helper used.
Each action module's `resolveUserUid(bridge, uin, groupId?)` call becomes
`bridge.resolveUserUid(uin, groupId?)` — same signature on Bridge, but
internally it now goes through `identity.resolveUid` so future changes
(retry, coalescing, alternative resolvers) only need to land in one place.
This is part 1 of the IdentityService deepening (RoadMap item 1). The
QQInfo bypass in msg-push-handler and the broader QQInfo absorption land
in the follow-up commit.
Distinguish "message not found" from "private chats don't support
emoji reactions". The latter previously masqueraded as "not a group
message", which sounded like a missing feature; clarify that the
limitation is on QQ's side, not ours.
Bumps version, pushes dev with chore(release): prefix to trigger
Promote, waits for the PR to merge, then tags main and pushes
the tag to kick off the release workflow.
set_msg_emoji_like silently no-op'd for unicode emoji because the
reaction request didn't tell the server which emoji namespace the
code belongs to (QQ face vs unicode codepoint). Derive the type
from the code length — short numeric ids are QQ faces, longer
codepoint strings are unicode.
The NTV2 upload-response decoder used stub schemas that omitted fields
QQ NT echoes back (notably video.fromScene/toScene, pic.fromScene/
toScene/oldFileId, the ptt scene/waveform set), so finalizeMediaMsgInfo
re-encoded the commonElem.pbElem with those fields missing. For c2c
video this triggered `send private message rejected: result=79` on
every send_private_msg [{type:'video'}] call — the upload itself
fast-pathed fine but the follow-up SendMessage was rejected by NT.
Drop the duplicate NTV2 placeholder schemas and route NTV2ExtBizInfo
through the element-side PicExtBizInfo / VideoExtBizInfo /
PttExtBizInfo, which are field-complete. Also zero out the main
video sub-file's width/height/time/videoFormat in the upload request
to mirror NapCat — those fields belong on the thumb, not the source
mp4, and non-zero values trip schema validation on c2c sends.
The session warmup only set qqInfo.nickname when QQ's friend-list
response happened to echo self back, which it omits for some
accounts / versions / multi-account warmup races. The WebUI online
sessions card then rendered a blank nickname row above the UIN.
Fall back to a direct user-profile fetch when the friend-list scan
misses self, and seed qqInfo.nickname with the UIN at session
creation so the panel never paints empty while warmup is in flight.
- WebUI sidebar/login display and OneBot get_version_info now read the
root package.json version via Vite `define`, removing hardcoded
literals in webui/src/types.ts and core/onebot/actions/info.ts.
- tools/bump-version.mjs (exposed as `pnpm bump <ver>`) syncs the
version field across the root and all five workspace packages.
- Bump everything to 1.7.8.
get_forward_msg now returns full OB11Message objects (self_id, time,
message_id, sender, etc.) instead of node-segment wrappers, and event
emission keeps the resId on incoming forward segments instead of
dropping it via the unknown-element fallback. Extends ForwardNodePayload
with optional context fields so download/upload paths preserve enough
state to synthesize the OB11Message shape NapCat clients expect.
With SNOWLUMA_HOOK_AUTOLOAD=1, the QQ window came up blank — no QR code,
login stuck. Cause: the native enumerator (get_all_main_process_ids)
returned the main QQ pid plus 2 zygote subprocesses because their
cmdline contains "qq" and they transiently inherit wrapper.node via
fork copy-on-write. Auto-load fired loadModuleManual for all three,
spawning an in-process resolver thread inside each zygote. Renderer
processes Electron later forked from those zygotes then inherited
those resolver threads + the partially-initialised hook state, which
breaks QQ's IPC and prevents the login UI from rendering.
Add `shouldAutoLoadPid` which reads /proc/<pid>/cmdline and returns
false when it contains `--type=` (Electron child process marker:
zygote / renderer / gpu-process / utility). Manual loadProcess() is
unaffected — operators picking PIDs from WebUI keep full control.
SNOWLUMA_HOOK_AUTOLOAD_ALL=1 disables the filter as an escape hatch.
Verified on tempserver: container restart with autoload=1 now shows
the QR-code login screen as expected, and only the main qq pid gets
the mojo.<pid>.*.sock pair (zygotes stay clean).
Headless / Docker deployments previously needed a human to click
"Load" in WebUI for every newly-discovered QQ process. Add an opt-in
HookManager.autoLoadOnDiscovery flag wired up through two layers:
- SNOWLUMA_HOOK_AUTOLOAD env var (highest priority)
- hookAutoLoad in runtime.json (persistent fallback)
When enabled, every 'process-discovered' event from PipeWatcher fires
session.load() fire-and-forget; failures stay scoped to the session via
existing error-state handling and don't break the watcher loop.
Default stays off, so non-Docker installs see no behaviour change.
Two small cleanups that came out of the round-2 architecture review
and are sub-five-minutes each — bundled because each one is too
small to justify its own commit.
#5 — flatten single-file directories
packages/core/src/bridge/builders/element-builder.ts
-> packages/core/src/bridge/element-builder.ts
packages/core/src/bridge/handlers/msg-push-handler.ts
-> packages/core/src/bridge/msg-push-handler.ts
Both dirs had exactly one file in them — a smell that says
"planned a sibling that never landed". Moving up one level
removes the wrapper directory.
Touch list:
- bridge.ts: 2 import paths
- bridge/actions/forward.ts: 2 import paths
- msg-push-handler.ts: internal ../X -> ./X for events,
proto/element, proto/message (the
dynamic-import-typeof references too)
- element-builder.ts: internal ../X -> ./X for bridge,
events, highway/*
- 4 test files: import paths (2 regular, 2 vi.mock)
#6 — drop IdentityService.hasWriteFailure
identity-service.ts had a `private writeFailed = false` field set
by the runWrite catch block and exposed via `get hasWriteFailure()`,
but a full-repo grep showed zero callers of the getter. It was a
public API stub for a feature that hadn't been wired (a webui
health indicator, presumably).
Removed:
- the field
- the getter
- the assignment in runWrite's catch block (the error log on
the next line is the actual observable behavior; nothing else
reads the flag)
If we want a "did any write fail this session" surface later,
it's trivial to add back with an explicit consumer in mind.
Behavior preserved end-to-end. No public API change outside the
moved files. 369 tests pass (unchanged). 3 stability runs.
The OneBotInstance constructor still carried two non-trivial closures
inside its converterCtx object — a 26-line mediaUrlResolver that
branched bridge URL fetches by element.type + isGroup, and a 60-line
mediaSegmentSink that fanned out to mediaStore.rememberImage / Record /
Video with subtly different field maps. Both closed over `this` and
were untestable without instantiating the whole instance.
Extracted into two small, focused modules:
onebot/media-url-resolver.ts (64 lines)
class MediaUrlResolver(bridge, rkeyCache)
.resolve(element, isGroup, sessionId): Promise<string>
Picks the right Bridge.fetchXxx based on element.type + isGroup,
mutates element.url in-place (preserved behavior), then applies
the cached RKey via rkeyCache.resolveMediaUrl. Bridge-fetch
errors are swallowed so the RKey pass always runs.
onebot/media-indexer.ts (90 lines)
class MediaIndexer(mediaStore)
.remember(mediaType, element, data, isGroup, sessionId): void
One method, dispatches to mediaStore.rememberImage / Record /
Video with the right field map per mediaType. Defaults are
preserved exactly (?? 0 for missing numbers, ?? '' for strings).
OneBotInstance constructor shrinks from 134 lines to ~50 lines (-62%).
The converterCtx is now visually obvious — four callbacks each one
line, delegating to the right collaborator:
const mediaUrlResolver = new MediaUrlResolver(this.bridge, this.rkeyCache);
const mediaIndexer = new MediaIndexer(this.mediaStore);
this.converterCtx = {
selfId: parseInt(this.uin, 10) || 0,
imageUrlResolver: (el, ig) => this.rkeyCache.resolveImageUrl(this.bridge, el, ig),
mediaUrlResolver: (el, ig, sid) => mediaUrlResolver.resolve(el, ig, sid),
messageIdResolver: (ig, sid, seq, name) => hashMessageIdInt32(...),
mediaSegmentSink: (mt, el, d, ig, sid) => mediaIndexer.remember(mt, el, d, ig, sid),
};
Adds 19 happy-path tests:
media-url-resolver.test.ts (12 tests):
- file element: group / c2c-with-hash / c2c-without-hash
- record element: group / c2c
- video element: group / c2c
- record without mediaNode: no bridge call
- element.url already set: short-circuit, only rkey runs
- bridge throws: swallowed, rkey still applied
- rkey is always called at the end
media-indexer.test.ts (7 tests):
- image: full field map, file falls back to fileId
- record: full field map, file falls back to fileName
- video: full field map, data.file overrides element fields
- record: file falls back to fileId when fileName also missing
- missing numeric / string fields default to 0 / ''
- only the matching rememberX is called
Behavior preserved end-to-end: same bridge methods, same field
mappings into MediaStore, same in-place element.url mutation, same
RKey-always-runs guarantee, same best-effort error swallowing.
The existing media-store integration test (which still wires the
sink through the real converter) continues to pass unchanged.
334 tests pass (was 317); 3 stability runs, same pre-existing
macOS-arm64 websocket addon failure, unrelated.
event-converter.ts (541 lines) was a class with a 16-case switch
mapping bridge events to OneBot wire JSON, plus a 13-case helper
mapping bridge elements to OneBot segments, plus four lazily-injected
resolver setters (image-url / media-url / message-id / media-segment
sink). Testing one case required instantiating the class and wiring
four setters; 22 of the 29 cases (10 notices + 2 requests + 13 element
types) had zero tests.
This commit kills the class and replaces it with a pure-function
family that takes a ConverterContext (a plain object holding selfId
+ the four resolver callbacks). Each per-event handler becomes a
small typed function that's trivial to call from a test with two
lines of setup.
New layout: packages/core/src/onebot/event-converter/
index.ts 133 ConverterContext + four resolver types +
convertEvent dispatcher + re-exports.
to-message.ts 112 friend / group / temp message (3 handlers)
to-notice.ts 189 group_member_join / leave / mute / admin /
friend_recall / group_recall / friend_poke /
group_poke / group_essence / group_file_upload /
friend_add (11 handlers)
to-request.ts 37 friend_request / group_invite (2 handlers)
to-segment.ts 145 13 element -> segment cases + elementsToJson +
elementsToOneBotSegments
utils.ts 111 parseSelfId / isSameActor / applyMessageIdResolver /
resolveReplyId / segmentsToRawMessage + CQ encoding
Caller migration (3 files, all inside onebot/):
instance.ts: replaces `new EventConverter()` + four setter
calls with a single `converterCtx: ConverterContext`
object built once at construction. The four
closures that used to be passed through setters
are now properties of the context.
instance-context.ts: `eventConverter: EventConverter` field renamed
to `converterCtx: ConverterContext`.
event-pipeline.ts: `ctx.eventConverter.convert(ctx.uin, event)` is
now `convertEvent(ctx.converterCtx, event)`.
External callers (modules/message-actions.ts) keep working unchanged:
elementsToOneBotSegments is re-exported from the new index.ts with
the same signature.
Adds 28 new tests covering every previously-untested case:
message kinds (already partly covered): 7 tests
- friend / group / temp_message peer + self post_type tagging
- messageIdResolver override
notice kinds (new): 11 tests
- all 11 cases, including the sub-type axes
(approve/invite, leave/kick/kick_me, ban/lift_ban,
set/unset, add/delete, etc.)
request kinds (new): 2 tests
- friend_request, group_invite (with sub_type default)
element segments (new): 13 tests
- text / face / image (with + without resolver) / at /
at-all / reply (with + without resolver) / record /
video / json / xml (with + without subType) / file /
mface / poke
mediaSegmentSink wiring (new): 1 test
Plus 3 tests in media-store.test.ts and 1 in event-pipeline.test.ts
adapted to the new API.
317 tests pass (was 285); 3 stability runs, same pre-existing
macOS-arm64 websocket addon failure, unrelated.
The three highway uploaders — image-upload, ptt-upload, video-upload —
each implemented the same NTV2 envelope assembly, OIDB response decode,
error handling, and Highway PUT loop, with the only real per-format
differences being the file-info fields, the extBizInfo blob, and the
Highway command id. The duplicated boilerplate had drifted slightly
between files and any future NTQQ protocol change would have needed
parallel edits in three places.
New: packages/core/src/bridge/highway/pipeline.ts (249 lines).
runNtv2Upload({ bridge, isGroup, targetIdOrUid, oidbCmd, serviceCmd,
requestId, businessType, uploadInfo, compatQmsgSceneType,
extBizInfo, uploads, label })
-> awaited upload object
Builds the full reqHead + upload envelope, sends through OIDB,
decodes the response, runs the per-sub-file Highway PUTs (caching
the Highway session across them — video uses two PUTs and now only
fetches the session once), and surfaces a typed fastOnlyError when
the server demands bytes but the caller passed a fingerprint.
finalizeMediaMsgInfo(upload, defaultPic?) -> Uint8Array
Encodes the outgoing commonElem MsgInfo. `defaultPic` is the
image-only fallback: image fills bizType + textSummary when the
server omits the pic ext-biz-info; ptt / video pass undefined.
hexToBytes(hex), makeClientRandomId(): shared helpers used by every
uploader's fingerprint payload + client-randomId generation.
MediaSubFileUpload models per-sub-file routing:
- source: 'top' -> upload.uKey + upload.ipv4s (main file)
- source: N -> upload.subFileInfos[N].uKey + .ipv4s (video thumb)
- cmdId, bytes, md5, sha1, subFileIndex, fastOnlyError
Each upload file shrinks to its format-specific logic only:
image-upload.ts: 237 -> 163 (-31%)
format detection, picFormat mapping, pic/reserveTroop/reserveC2c
extBizInfo, group/c2c command id choice, finalize with defaultPic.
ptt-upload.ts: 300 -> 205 (-32%)
silk transcoding, temp-file cleanup, NapCat-style bytesGeneralFlags
(different per group/c2c), voiceFormat honouring.
video-upload.ts: 584 -> 507 (-13%)
Sha1StreamState (per-1MB streaming SHA1 for the main Highway PUT),
ffmpeg-driven thumb extraction with FALLBACK_THUMB, the two-sub-file
OIDB body (main mp4 + thumb jpg with subFileType 100), and the
fastOnlyError asymmetry (main file has it; thumb always has bytes).
Video stays the largest because its load step is genuinely the most
work — the share-out gain here is in concentration, not line count.
Behavior preserved end-to-end. Same NTV2 OIDB cmd numbers (image
0x11C4/5, ptt 0x126E/D, video 0x11EA/9), same service-cmd strings,
same requestId (image=1, ptt=group:1/c2c:4, video=3), same
compatQmsgSceneType (image+ptt: isGroup?2:1; video: 2), same
NapCat-derived bytesGeneralFlags, same fastUpload fallback strings.
Adds 42 happy-path tests across 4 new files in tests/highway/ :
pipeline.test.ts 22 envelope construction, response decode,
OIDB error paths, group vs c2c scene,
Highway PUT trigger + fast-path skip,
sub-file routing, session caching,
fastOnlyError fire / silent-skip,
finalize with/without defaultPic, helpers.
image-upload.test.ts 7 group/c2c oidbCmd + cmdId mapping,
fingerprint payload shape, picFormat /
dimensions wiring, subType -> bizType.
ptt-upload.test.ts 6 group requestId=1 / c2c requestId=4,
per-scene bytesGeneralFlags, voiceFormat
default and override, fingerprint
preconditions, finalize-without-pic.
video-upload.test.ts 7 two-sub-file shape, thumb subFileInfos[0]
routing, fastOnlyError asymmetry,
uploadInfo[mp4+jpg] with subFileType 0+100,
FALLBACK_THUMB always has bytes.
Tests mock highway-client for transport and the pipeline module (for
per-uploader tests) so each suite hits exactly the contract it's
testing. Pipeline tests roundtrip a real OIDB envelope through
protobuf encode/decode to exercise the actual decode path.
285 tests pass (was 244). Same pre-existing macOS-arm64 websocket
addon failure, unrelated.
ApiActionContext had 81 optional method fields (\`name?: ...\`) plus 4
required ones — but every single optional field was wired in
buildApiContext (verified by diffing the two lists). The optionality
was dead: nothing else implemented this interface, no test ever
swapped fields out, and the action handlers all paid for the
fiction with defensive guards like:
if (!ctx.sendGroupMessage) {
return failedResponse(RETCODE.ACTION_FAILED, 'send_group_msg is not implemented');
}
— 80 such guards total across the action files (78 in the 3-line
form, 1 single-line, 1 \`if (!(ctx.a && ctx.b))\` compound). None of
them could ever fire.
This commit deletes the dead optionality. Two mechanical changes:
1. api-handler.ts: 81 \`name?: ...\` -> \`name: ...\` in ApiActionContext.
The MessageSendResult optionals (meta?, echoEvent?) are unrelated
and stay as-is. After: 85 required fields, 0 optionals.
2. actions/*.ts: drop the 80 guard blocks. Net -129 lines across
extended, group-admin, group-file, group-info, friend, message,
request. info.ts had none to begin with.
What this buys:
- The type system now enforces the wiring contract. If
buildApiContext forgets to wire a field, tsc fails at the call
site — the bug we were ostensibly catching at runtime in 80 places
is now caught at compile time in 0 places, for free.
- Action handler bodies shrink visibly (avg ~3 lines per handler).
extended.ts goes 1021 -> 935.
- AI / human readers no longer skim past dead code.
Caught one TS2774 ("This condition will always return true since
this function is always defined") on a compound guard in
extended.ts:186 that the regex missed; removed it manually. That
diagnostic is the type system actually doing its job — exactly the
point of the change.
244 tests pass (was 244). Same pre-existing macOS-arm64 websocket
addon failure, unrelated.
bridge-actions.ts was a single 1814-line file holding 55 unrelated
exported functions — admin/file/forward/interaction/recall/profile/
status/translate/sign/avatar all jumbled together. Each function
already takes `bridge: Bridge` as its first parameter, so the
"deepening" target (per-UIN state object threaded into themed action
functions) was structurally there — what was missing was a coherent
file-level grouping that AI tools and humans could navigate.
This commit is candidate #2 from the deepening list, A-only variant:
pure file split, no facade change, no caller change outside the
bridge module.
New layout under packages/core/src/bridge/actions/ :
shared.ts 82 private helpers (toInt, ensureRetCodeZero,
resolveSelfUid) and the MediaIndexNode type.
group-admin.ts 153 mute/kick/leave + setGroup{Admin/Card/Name/
SpecialTitle/AddOption/Search/Remark/AddRequest}
+ getGroupAtAllRemain. (14 fns)
group-file.ts 821 upload/list/url/delete/move/folder ops, both
group + private files, media-URL fetchers for
ptt/video, fetchGroupFileCount. Owns file-
specific helpers (normalizeDirectory,
buildGroupFileUploadExt, normalizeMediaNode,
fetchNtv2DownloadUrl, ...). (15 fns)
group-message 101 recall* / markRead* / setGroupEssence. (5 fns)
interaction.ts 61 poke / like / reaction / emoji-likes. (4 fns)
forward.ts 197 uploadForwardNodes, fetchForwardNodes +
in-memory resId cache. (2 fns)
friend.ts 53 setFriendAddRequest, deleteFriend,
setFriendRemark. (3 fns)
profile.ts 269 setOnlineStatus, setProfile, setSelfLongNick,
setInputStatus, setAvatar, fetchCustomFace,
getProfileLike, getUnidirectionalFriendList.
(8 fns)
misc.ts 173 translateEn2Zh, getMiniAppArk,
clickInlineKeyboardButton, sendGroupSign.
(4 fns)
bridge.ts updates its imports — one themed import block per action
module instead of one giant block from bridge-actions.ts. GroupFilesResult
and MediaIndexNode type imports now point at actions/group-file and
actions/shared. Public Bridge facade API is unchanged: every caller
outside `bridge/` keeps the same `bridge.X(...)` surface and the
delegated function it points at.
bridge-actions.ts is deleted. The new shared.ts holds the three
helpers that span themes; everything else lives co-located with the
functions that use it.
Adds 60 happy-path tests across tests/actions/ — one .test.ts per
themed file plus a shared `_helpers.ts` (mockBridge fixture):
group-admin 10 command + payload dispatch, UID resolution,
flag-driven sub-command selection (mute on/off,
add-request filtered/unfiltered).
group-file 13 fetchGroupFileCount, upload happy path with
and without highway, OIDB error bubbling, file
listing pagination + folder/file split, URL
builder shape, delete/move/folder dispatch,
NTV2 URL assembly.
group-message 5 recall (group/private), markRead, essence on/off,
transport failure propagation.
interaction 6 poke (group vs friend payload), like, reaction
on/off, emoji-likes cookie/isLast logic.
forward 5 empty-array rejection, dispatch + res_id return,
transport failure, cache reuse after upload.
friend 5 numeric flag → UID resolution path, opaque flag
passthrough, delete + best-effort cache refresh.
profile 9 status dispatch, setProfile no-op when undefined,
setAvatar highway cmd 90, getProfileLike +
getUnidirectionalFriendList JSON parsing.
misc 6 translate, mini-app type guard, click + sign
dispatch.
Tests use vi.mock on `bridge-oidb` (and `highway-client`/`highway-utils`
where relevant) so each action runs against a tiny fake Bridge, no
native pipe / real OIDB exchange needed. Previously these 55 functions
had zero unit-test coverage.
244 tests pass (was 184); only failing suite remains the pre-existing
macOS-arm64 missing websocket native addon, unrelated.
Captures protocol-level media fingerprints (md5/sha1/dims/format) on the
receive side and persists them alongside existing MediaStore entries, so a
forward can re-send the original message via QQ's md5 fast-upload path
without re-downloading the source CDN bytes. Avoids the stale-rkey trap
where the cached imageUrl 404s a few hours after receipt.
- MessageElement: add md5Hex / sha1Hex / pic|video|voiceFormat /
noByteFallback optional fields.
- MediaStore: extend CachedImage / CachedRecord with fingerprints, add
CachedVideo + rememberVideo / findVideo / updateVideoUrl. Per-row growth
~80-90 bytes; LRU cap stays at 4096 per type.
- msg-push-handler: extract fingerprints from NTV2 image/record/video and
legacy NotOnlineImage/CustomFace/Ptt paths.
- event-converter: invoke mediaSegmentSink for video too.
- highway image/ptt/video upload: add fast-only branch that skips
loadBinarySource/encodeSilk/stageVideoSource when noByteFallback is set,
and fails fast if the server still returns uKey. Video forward uses the
100-byte FALLBACK_THUMB as its subFile (original thumb not preserved in
onebot semantics).
- message-actions: add forwardSingleMessage which looks up the cached
event, enriches each media element with cached fingerprints, and
dispatches via the existing sendGroup/sendPrivateMessage path. Files
reject explicitly (separate upload protocol, out of scope).
- extended actions: wire forward_friend_single_msg / forward_group_single_msg
to the new context method, replacing the not-implemented stubs.
NtqqHandler was a 54-line "shallow module": half of its public surface
(registerCmd by service-cmd) had zero callers — cmdHandlers was a Map
that nothing ever wrote to. The remaining half (registerCmdAll) had
exactly one subscriber: BridgeManager.bind() wiring its private
onPacket. So NtqqHandler was, in effect, a one-listener event emitter
plus a five-line field-rename from QqHookPacket to PacketInfo.
The deletion test concentrates the change rather than scattering it:
- HookSession.handlePacket inlines the field rename and pushes
straight into a PacketSink dependency (PacketInfo => void).
HookSession's ctor now takes `onPacket?: PacketSink` instead of
`ntqq?: NtqqHandler` — the new shape is exactly what tests want
(a vi.fn() spy with no event-emitter scaffolding).
- HookManager's `ntqq: NtqqHandler` constructor dep becomes
`onPacket?: PacketSink`, defaulting to `bridgeManager.onPacket` so
the common-case wiring stays one line at the call site.
- BridgeManager.bind(ntqq) is deleted; BridgeManager.onPacket becomes
public (it was always the real entry point). The file header
comment now describes onPacket as the single packet entry rather
than "wires NtqqHandler".
- index.ts shrinks: no `new NtqqHandler()` and no `bridgeManager.bind`.
`new HookManager({ bridgeManager })` covers both wires.
- packages/core/src/protocol/ntqq-handler.ts deleted.
Behavior preserved: same field rename (Buffer.from(packet.body) for
the body copy that QqHookClient already does, kept to match
byte-for-byte), same login + real-uin filter, same logging scope is
gone (`createLogger('NTQQ')` had no remaining call sites). PacketSink
type alias added to protocol/types.ts so the dep type stays readable
across HookSession + HookManager.
Adds 5 unit tests for the inlined packet path that the deleted module
never had: PacketInfo shape, session-uin fallback when packet.uin is
empty, pre-login drop, non-real-uin drop, and a no-sink no-op.
184 tests pass (was 179); only failing suite is the pre-existing
macOS-arm64 missing websocket native addon, unrelated.
HookManager was a 515-line god class with four tangled responsibilities
(state machine, watcher loop, per-PID serialization, lifecycle plumbing)
and no tests — every code path needed a real QQ.exe to exercise.
Split into three modules:
- PipeWatcher: the only module that polls the OS for QQ.exe processes
and live SnowLuma named pipes. Emits diff events (process-discovered,
process-gone, pipe-up, pipe-down, tick). Native list functions are
constructor deps so tests can drive ticks with in-memory fakes.
- HookSession: per-PID lifecycle. Owns its own state machine, its own
promise chain (serializes load/unload/refresh/onPipeUp/onPipeDown so
rapid user clicks don't race), and its own QqHookClient. Emits
high-level events (login, disconnected, status-changed, disposed)
that the manager forwards instead of reaching into BridgeManager
directly. Injector and pipe-client factory are deps for testability.
- HookManager: shrinks to a thin orchestrator (227 lines, was 515).
Routes user commands and watcher events to sessions, forwards session
events to BridgeManager, retries stuck-in-connecting sessions on every
watcher tick (preserves the original tickWatcher reconcile pass).
Public API (listProcesses/loadProcess/unloadProcess/refreshProcess)
unchanged for WebUI callers; only the constructor moves to a deps
object: new HookManager({ ntqq, bridgeManager }).
Behavior preserved including all the edge cases the original code
handles: re-using a SnowLuma DLL that survived a process restart
(fast-path via pipeWatcher.isPipeLive), stale close events from a
replaced client, DLL-unload-failed fallback to "watcher will
reconnect", QQ.exe killed with a live pipe (pipe-down emitted before
process-gone so disconnect runs before dispose).
Adds 27 unit tests across two new vitest suites (hook-session.test.ts
and pipe-watcher.test.ts) covering load fast-path, login emission,
duplicate-login suppression, connect retry on failure, pipe up/down
cycles, unload while logged in, unload verification failure, user
command serialization, and process-gone handling — none of which
previously had test coverage.
* feat: implement more group admin action (kick members and set search and set add type)
* feat: implement some user extend func (set group mark \\ get custom emoji)
* feat: implement get send emoji his
* feat: implement get profile like
* feat: implement get at all remain
* feat: implement get undirectional friends
* feat: implement set self long nick
* feat: implement set input status
* feat: implement EN 2 ZH
* feat: implement get mini app ark
* feat: implement click inline button
* feat: implement set and send group sign
* feat: implement set qq avatar
* feat: group notice with pic and delete notice implement
* fix(group-notice): POST api and fix new bkn logic
Add a `force` flag to member cache refresh logic so events that affect the bot itself trigger an immediate refresh. When the event userUin matches the bot's UIN, `triggerMemberCacheRefresh` sets `force = true` and forwards it to `fetchGroupMemberList`. `fetchGroupMemberList` now accepts an optional `force` parameter (default false) and bypasses the TTL cache when `force` is true, ensuring up-to-date member data after join/leave events.
Stop exposing and retaining hook state for PIDs that are not currently running. listProcesses() no longer returns orphaned states; live-pipe handling ignores PIDs not present in the current process list. When a process is not running its state is immediately torn down (tearDownClient called) and removed, and bridgeManager.onPidDisconnected is notified if the state was logged in. Also reorganized runningSet creation so it can be reused for these checks.
Introduce NT SILK-based voice (PTT) upload pipeline and native FFmpeg addon wrapper.
- Add ffmpeg-addon wrapper (packages/core/src/bridge/highway/ffmpeg-addon.ts) to load platform/arch .node binaries, detect SILK files, and convert inputs to NT SILK via the native addon. Provides encodeSilk, isSilkFile and default temp dir helpers.
- Implement ptt-upload pipeline (packages/core/src/bridge/highway/ptt-upload.ts) to: resolve/fetch audio bytes, convert to NT SILK if needed, send OIDB upload request, perform highway HTTP upload when required, and produce Encodable MsgInfo bytes for commonElem.
- Wire record element support into element-builder: uploadPttMsgInfo is used to build a commonElem for 'record' sends; when SendContext is absent, record sends are skipped with a warning (graceful no-bridge path).
- Update message parsing to accept record segments from data.file, data.url or data.path and drop empty sources.
- Enable canSendRecord in OneBot instance context.
- Add tests covering record parsing and the graceful send path (packages/core/tests/message-parser.test.ts).
- Include prebuilt native ffmpeg addon binaries under packages/runtime/native/ffmpeg and update vite config to validate & copy the ffmpeg addon into the dist layout.
These changes enable sending voice messages by converting/encoding sources to the expected NT SILK format and uploading them through the existing highway/NTV2 flows.
Translate and consolidate verbose WebUI log messages to shorter English variants (dev mode, initial credentials, forced password change, password update, port fallback, and listening message). Remove a startup log emitted in core index.ts. In HookManager, preserve an existing state.method when detecting an already-injected PID (only set to 'reconnect' if not present) and remove a redundant injection success log to reduce noise.
Introduce a typed per-kind BridgeEventBus and migrate away from the legacy single-callback firehose. Bridge now exposes `events` and emits via the bus; BridgeManager/OneBotManager no longer wire a global event callback. Add a focused onebot event pipeline (event-pipeline.ts) that subscribes per-kind handlers on instance construction. Replace the in-memory MediaCache with a persistent MediaStore and update all lookups accordingly. Replace the old Http/Ws/HttpPost transport implementations with a unified OneBotNetworkManager and pluggable adapters (server/client/post), and update OneBotInstance to install and manage adapters from config. Remove several legacy files (http-transport, http-post-transport, ws-transport, media-cache) and update imports across the codebase. Also add tests for the bridge event bus, event pipeline, network manager, and rename media tests to reflect MediaStore usage. The bus dispatches handlers in parallel and reports handler errors via an onError hook to avoid one faulty listener blocking others.
Introduce an in-memory MediaCache to index recently seen image and record segments and wire a MediaSegmentSink into EventConverter to populate it. OneBotInstance now constructs MediaCache and registers a sink to remember image/record metadata; instance-context exposes get_image/get_record lookup handlers that consult the cache (and re-resolve record URLs via bridge OIDB when needed). ApiHandler actions get_image/get_record now accept file_id fallback and use the new context lookups. Removed the old findMediaInStore stub and added comprehensive tests for the cache and sink behavior.
Switch default merge_method from 'merge' to 'squash' so dev->main PRs collapse the dev branch's incremental commits into one squash commit on main, keeping main's history linear and release-tag-friendly. Affects: workflow_dispatch input default, decide-step initial value + workflow_dispatch fallback, both push-trigger branches (tag + commit-msg), and the case-statement fallback in the auto-merge step. CONTRIBUTING.md updated to reflect the new default.
- Tag trigger switched from v* to chore.* so the promote workflow no longer collides with release.yml's v* tag handling. v* tags now drive only the release build; chore.* tags drive only dev->main promotion.
- Commit-message detection on dev is now prefix-only: '^[merge]' or '^chore(release):' (case-insensitive). 'fix: stuff [merge]' no longer triggers; the marker must be at the start of the message.
- CONTRIBUTING.md updated: prefix examples, chore.* tag examples, and an explicit 'all required status checks must pass' branch-protection setup that lists the dev-build typecheck/build matrix as required.
Adds .github/workflows/promote-dev-to-main.yml which uses the SnowLuma Bot GitHub App to open (or refresh) a PR from dev into main. Triggered by [merge] or chore(release): commit-msg markers on dev, by v* tag pushes, or via manual workflow_dispatch. Auto-merge is enabled when triggered.
Adds CONTRIBUTING.md describing the dev/main branch model, the promote workflow, the required SNOWLUMA_BOT_APP_ID / SNOWLUMA_BOT_PRIVATE_KEY secrets, and the GitHub branch protection setup needed to forbid direct pushes to main.
Update release workflows to fallback to 'SnowLuma/SnowLuma.Docker.Framework' when RELEASE_REPOSITORY is unset and to resolve the target workflow by name, path, or id. Replace the simple workflow_id string with logic that paginates listRepoWorkflows, finds the matching workflow, validates it exists, and passes workflow.id to createWorkflowDispatch. Improve error messages and logging to include workflow name and id.
Update GitHub Actions release workflows to use the SNOWLUMA_TOKEN secret instead of DOCKER_RELEASE_TOKEN. Changed the github-token input in .github/workflows/release.yml and .github/workflows/dispatch-docker-release.yml for the docker release steps.
Introduce a manual re-dispatch workflow and wire automatic dispatch from releases to the Docker workflow. dispatch-docker-release.yml was converted to a workflow_dispatch-based "Re-dispatch Docker Release" that accepts snowluma_tag, docker_image_override and platforms_override inputs and forwards them (plus source repository) to the downstream docker-image.yml in the Docker release repo. release.yml gains a dispatch-docker job that runs after the release job and uses a PAT to invoke the same downstream workflow for newly published tags. These changes let maintainers rebuild Docker images for existing tags (e.g. to fix Dockerfile issues or rotate credentials) without re-tagging, and ensure the downstream dispatch runs under the configured token.
Switch the release dispatch to call actions.createWorkflowDispatch instead of repos.createDispatchEvent because the target repo only listens for workflow_dispatch on its docker workflow. Add env vars DOCKER_PLATFORMS, DOCKER_WORKFLOW and DOCKER_REF (with sensible defaults) and pass image, tag, push and platforms as inputs. Update log output to include workflow, ref, image, tag and platforms.
Normalize OneBot WS role values to canonical PascalCase ('Api'|'Event'|'Universal') across core and web UI, and support auto-migration from legacy lowercase on-disk values. Updated types, defaults, serializers/parsers, and runtime checks in ws-transport, adjusted WebUI select options and default entries, and updated the client User-Agent string. Added a test to verify that legacy lowercase role values are migrated to the new canonical form on load.
Trigger the external Docker release pipeline when a SnowLuma version tag is pushed.
Keep Docker image and release target configuration in the SnowLuma environment.
Remove the '测试要求' testing section from README.md and add a new RoadMap.md containing planned V2.0.0 tasks (unify Uid/Uin service with SQLite persistence, improve debug experience with no-packaging debug and correct data dir). This separates roadmap details from the README for clarity and future tracking.
Unify per-adapter network configuration into a single `networks` structure and add migration/normalization for legacy on-disk formats. Introduce per-adapter options (messageFormat, reportSelfMessage, enabled, name) and stronger typing in types.ts. Add event-filter utilities to prebuild two serialized payload variants and pick the right one per adapter to avoid repeated JSON.stringify calls. Update HTTP/WS transports to use adapter names/signatures for hot-reload, respect per-adapter options, and improve logging; WS transport also improves client/server lifecycle/reconnect handling. Mark self-sent messages as `message_sent` in the event converter and wire instance dispatch to use the new DispatchPayload. Misc: README edits and accompanying tests added/updated for the refactor.
Introduce a development-only WebUI auth mode controlled by SNOWLUMA_DEV_MODE. When enabled, a fixed in-memory password ("snowluma-dev") is used, config/webui.json is not read or written, and password changes are disabled. Expose WebuiAuth.isDevMode() and WebuiAuth.devPassword, add startup logs when dev mode is active, and wire up dev:mode npm scripts (root and packages/core) using cross-env to set the env flags.
Replace packages/runtime/native/snowluma-win32-x64.dll with an updated binary build. This commit updates the native Windows x64 runtime DLL; no other source changes are present in this diff.
Remove external GPU detection (no more exec/promisify or detectGpus) and stop returning GPU list from /api/system. Instead expose the Node.js process runtime info (pid, rss, heapTotal, heapUsed, external, arrayBuffers) from the server. Update types to replace gpus with runtime and update the Overview UI: remove GPU list, show PID and formatted runtime memory stats, and adjust imports/icons accordingly. This simplifies system probing (avoids spawning platform commands) and surfaces useful process memory metrics in the WebUI.
Harden parsing of message segments in OneBot instance: skip non-object or array segments, normalize a local `type` string and a safe `data` object, and use those for all branch checks. This prevents runtime errors when segments or segment.data are missing or malformed, while preserving existing previews and placeholder labels (image, face, at, reply, record, video, fallback).
Previous behavior: when an uninstall operation failed, the system did not provide any error feedback to the user and would simply reconnect during a polling check.
Fixed behavior: if an uninstall fails, a failure notification is now displayed in the WebUI, informing the user that the uninstall has failed.
Replace rebuilt native artifacts for Windows x64: packages/runtime/native/snowluma-win32-x64.dll and packages/runtime/native/snowluma-win32-x64.node. This updates the compiled DLL and Node addon (likely due to native fixes, dependency or build changes) without touching source files.
Introduce a background pipe-watcher and per-PID operation serialization in HookManager to reliably detect and reconnect to SnowLuma pipes, reduce races, and remove the previous connect retry loop. Add new status 'connecting' and a refreshProcess API endpoint to force a probe/reconcile for a PID. Implement QqHookClient.listLivePipes() (and isClosed/probePipe updates) to enumerate live mojo pipes efficiently. Simplify client teardown logic and improve state transitions/logging. Update web UI: add a Refresh button, track inflight process ops, show connecting status and updated action messages. Update shared types to include the new 'connecting' status.
Previous behavior:
Replies visually displayed a quote block, but the quoted content was blank or invalid, and clicking to jump to the original message also failed.
Fixed behavior:
The quote now correctly references the original message, displaying its actual content and enabling a functional jump to the quoted message.
Change the documented localhost port in .github/workflows/release.yml from 8080 to 5099 so packaged builds reference the correct WebUI endpoint. This updates the startup instructions shown in the release workflow to match the new default port.
Introduce a `typecheck` job to GitHub Actions that sets up pnpm and Node.js (v22), installs dependencies, and runs `pnpm typecheck` on the workspace. Make the `build` job depend on `typecheck`. Also add a `typecheck` script (`tsc --noEmit`) to packages/websocket/package.json to enable package-level type checking. This ensures TypeScript errors are caught before the build runs.
Previous behavior: display adapter detection relied exclusively on wmic path Win32_VideoController. On recent Windows versions (e.g., Windows 11 24H2) where wmic is deprecated and disabled by default, this resulted in a complete failure to identify any display adapters.
Fixed behavior: added a new primary detection path using PowerShell’s Get-CimInstance Win32_VideoController, which is available and recommended on all modern Windows installations. The original wmic method is kept as an automatic fallback for older systems or environments where the CIM/PowerShell approach is unavailable. This restores GPU detection across a wide range of Windows versions without changing the public API or returned data structure.
Comment out the linux-arm64 matrix entry in .github/workflows/release.yml so the ubuntu-24.04-arm runner is no longer included in release jobs. This temporarily disables ARM64 releases; re-enable by uncommenting the linux-arm64 lines.
Temporarily comment out the linux-arm64 matrix entry in .github/workflows/dev-build.yml (name, os, target) to prevent the ARM64 job from running. Lines are commented rather than removed so the job can be re-enabled easily later.
Previous behavior: after editing an unreachable reverse-ws OneBot config entry, the new config took effect, but reconnect attempts could still target the old URL.
Fixed behavior: reconnect now only applies to currently active OneBot config entries; removed or changed old entries are no longer retried.
Previous behavior: after refreshing the WebUI, OneBot config entries for the same account were already loaded and active in backend, but appeared empty in the WebUI config page.
Fixed behavior: OneBot config API response shape is now unified and backward-compatible, so persisted OneBot config entries render correctly after WebUI refresh.
Previous behavior: no-token OneBot config entries could be automatically assigned a token during load/refresh.
Fixed behavior: fixed the issue where no-token config entries were auto-populated with tokens; OneBot config entry token values now strictly follow explicit user configuration (empty stays empty).
Previous behavior: after multiple reconnect failures for a reverse-ws OneBot config entry, multiple connections could be created concurrently when the target server came back.
Fixed behavior: added per-entry connection/reconnect deduplication so each OneBot config entry maintains only one active connection and one reconnect timer.
- Implemented a new SettingsPage component for user preferences including appearance, behavior, and account security settings.
- Added a ThemeToggle component to switch between light, dark, and system modes.
- Created reusable UI components: AlertDialog, Avatar, Badge, Button, Card, Dialog, Input, Label, Progress, ScrollArea, Separator, Sheet, Skeleton, Tooltip.
- Introduced utility functions for class name merging and formatting bytes/uptime.
- Added a custom hook for media query handling
Add a lightweight pipe liveness probe and use it to detect/reconnect to existing SnowLuma hooks instead of always re-injecting. Introduces PROBE_TIMEOUT_MS (400ms) and QqHookClient.probePipe(pid, timeout) which quickly checks if the control pipe accepts a connection (no hello exchange). HookManager now parallel-probes freshly-enumerated processes (probeAndSeed) and fast-checks before injecting in loadProcess; positive hits mark the state as injected with method="reconnect" and avoid redundant injection. Also deduplicate login notifications in handleLoginState (skip if already logged in with the same UIN) and adjust the loginState emission ordering in QqHookClient.
Restructure GitHub Actions to build Windows and Linux matrix targets and produce platform-specific artifacts.
- .github/workflows/dev-build.yml: split cleanup/build jobs, add matrix (win-x64, linux-x64), set SNOWLUMA_TARGET for builds, produce full and -lite archives (.zip on Windows, .tar.gz on Linux), unify upload step and ensure errors when artifacts missing.
- .github/workflows/release.yml: convert release build to matrix, produce platform archives, download/collect artifacts, generate multi-platform release notes (bash), and create the GitHub release with both .zip and .tar.gz assets.
- packages/core/vite.config.ts: add fs import and SNOWLUMA_TARGET handling, pick platform-specific runtime files (launcher.bat or launcher.sh), enumerate native files per target, fail CI if expected native binaries are missing, and copy native files into dist/native.
- packages/runtime/launcher.sh: add a portable launcher for Linux that prefers a bundled node binary or falls back to PATH and execs index.mjs.
These changes enable cross-target CI packaging and enforce that native binaries are present before releasing.
Simplify CI by removing job matrices and always building the WebUI flavor. Both dev and release workflows now run build:all, verify the websocket native module, and produce two archives: a zero-install bundle that includes node.exe and a no-node variant (requires Node >=22). Artifact names and upload steps were adjusted (dev uses SHA-based names; release uses tag-based names), and release notes were updated to document the two packages and WebUI defaults.
Adjust logger sanitization to keep the ESC (0x1B) character so ANSI color sequences produced by render() reach the terminal. The regex was refined from removing all ASCII control chars to excluding ESC, while still stripping other control characters (including BEL) to prevent unwanted system beeps and control behavior. Comment updated to reflect this rationale.
Introduce an in-tree TypeScript WebSocket package (@snowluma/websocket): move JS websocket implementation into packages/websocket/src (client, server, websocket, extensions, native, index) and add package.json + tsconfig. Replace direct 'ws' dependency in core with the workspace package and update runtime manifest/description. Implement a native addon loader for platform-specific binaries, add typings/refinements across client/server/websocket (more strict types, handshake parsing, permessage-deflate plumbing, buffer/raw data handling), and wire WebSocketClient as the package default export while exposing internal types. Update vite config to bundle the new package and copy only platform-target native binaries into dist/native. Remove legacy JS entrypoints and native loader, and adjust imports/usages in core (ws-transport) to accept broader raw data types.
Introduce a new WebSocket package implementing RFC6455 functionality and permessage-deflate support. Adds core connection handling (packages/websocket/websocket.js), client wrapper (client.js), server and upgrade handling (server.js), extensions (permessage-deflate) and helpers (extensions.js), an index and native loader (native.js). Also include prebuilt native addon binaries for multiple platforms and integration points to use the native Parser and frame builder. The server supports handleUpgrade, subprotocol negotiation, and verifyClient hooks; the client performs handshakes and queues sends until open. Error handling, UTF-8 validation, close/ping/pong control frames, and max-payload checks are implemented.
Restructure the repository into a pnpm workspace under packages/ (core, webui, runtime). Move source files for core and webui into packages/*, add package manifests for @snowluma/core and @snowluma/runtime, and remove the old launcher package.json. Update root package.json to be a monorepo controller (scripts delegate to pnpm filters, set packageManager and Node engine). Configure build outputs to emit into the repo-root dist/ (vite config changes) so the existing release pipeline continues to work. Add .npmrc with mirrors, expand .gitignore for monorepo layout, add tsconfig base and package-level tsconfigs, and add vitest config for the core package. Adjust injector native search paths and update tests import paths to the new package layout. Small CI/workflow comment added to clarify build behavior and README updated with monorepo structure and common commands.
Set checkout fetch-depth to 0 and add a PowerShell step that generates release-notes.md for the current tag (computes previous tag, collects commit messages, and emits localized download/usage notes for Windows x64 builds). Update the GitHub Release step to use body_path: release-notes.md and overwrite_files: true (replacing auto-generated notes) so the release includes the curated changelog and artifact information.
Enable runtime config reload and dynamic endpoint management across transports, and add server-side log streaming + UI.
- Transport hot-reload: HttpTransport, HttpPostTransport and WsTransport now maintain endpoint lists and start/stop individual endpoints (servers/clients) dynamically; servers/clients use keys/Maps to identify instances; added reloadConfig methods and helper key functions.
- OneBot control: OneBotInstance.reloadConfig delegating to transports; OneBotManager.reloadConfig(uin) to load and apply new config; added getPids helper.
- Logger & streaming: added in-memory recent log buffer, subscriber API (getRecentLogs, subscribeLogs) and LogEntry shape; web UI exposes /api/logs and /api/logs/stream (SSE) and improved token/query handling.
- Web UI: added LogsPage, integrated into layout and sidebar, EventSource client to show live logs; config save now attempts hot-reload and returns reloaded status.
- Misc: refactors to use Maps for server lists, cleanup on stop, and various small helpers and safety checks.
Add a /avatar/:uin proxy endpoint that fetches QQ avatars (fetchQqAvatar) and caches them server-side (30d TTL) with browser-cache headers (30d max-age, immutable). Validate UINs and handle upstream failures (502 if no cache), and log failures. Update ConfigPage and OverviewPage to render avatar <img> from /avatar/:uin (referrerPolicy=no-referrer) and adjust styles (overflow-hidden, object-cover) to replace initial-letter placeholders with actual avatars.
Add a new bigint property `exceptionTable` to the `ManualMapHandle` interface in src/hook/injector.ts and adjust formatting. The native build artifacts (native/snowluma-win32-x64.dll and native/snowluma-win32-x64.node) were also updated, indicating a rebuilt native addon to match the interface/ABI change.
2026-05-02 19:55:26 +08:00
680 changed files with 65707 additions and 16058 deletions
"description":"SnowLuma `inject` channel implementation — in-process NTQQ hook runtime. Bundles HookManager / HookSession / pipe-watcher / injector / qq-hook-client plus the `HookChannel` and `HookAdapter` that `Hub` (in @snowluma/core) registers as the primary transport on Windows. Depends on `@snowluma/channel` for the abstract `Channel` + `ChannelAdapter` contracts.",
"description":"SnowLuma `socket` channel implementation — placeholder for the future pure-socket runtime (no QQ.exe, no hook). Today registers as a no-op `ChannelAdapter` so the Hub-adapter architecture is exercised end-to-end. Will gain a `SocketClient` long-lived TCP login session when the protocol runtime lands.",
"description":"SnowLuma transport abstract layer. Defines the `Channel` abstract base + `ChannelCtx` capability POJO + `ChannelAdapter` port that `Hub` (in @snowluma/core) consumes. Concrete transports live in `@snowluma/channel-hook` (in-process NTQQ hook) and `@snowluma/channel-socket` (future pure-socket).",
"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).",
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.