[ranxianglei]

报错文案：SQLite 引擎缺失时只说一句"需要 Node.js 22+"

背景：裁决③④⑤之后，索引库打不开一律拒绝启动并给修复指引（不再静默降级）。但"没有可用 SQLite 引擎"这一类（Node < 22 且 better-sqlite3 未装）原来的提示要么为空、要么夹在大段策略说明里，用户抓不到重点。owner 定调：这个报错只需要说需要 Node.js 22 以上。

改动（全部用户可见措辞统一为同一句：requires Node.js 22 or newer）

• src/storage/shadow.ts：sqliteOpenFailureHint() 新增唯一一条跨平台分支 no SQLite engine available → requires Node.js 22 or newer；拒绝启动日志行最终形如 …REFUSING TO START (…)to serve JSON-only; requires Node.js 22 or newer。其余不变（win32 readonly/CANTOPEN 长提示照旧）。
• src/server.ts：boot 拒启日志行原来给裸错误无任何指引，现同带该提示。
• src/storage/engine-bootstrap.ts：旧措辞 node:sqlite needs Node.js >= 22.5 的 nodeSqliteUpgradeHint() 统一为 Node.js 22 or newer（内部判定阈值仍是真实的 22.5，只改展示文案）——此前同一故障有"22 or newer"与">= 22.5"两套话并存，现在全局一句。
• /__bili/status 的 degradeReason 走同一函数，自动带上这句。

测试

• tests/storage-cantopen-hint.test.ts：钉住三平台都出该短语；tests/storage-engine-bootstrap.test.ts、tests/acp-status-storage-degraded.test.ts 措辞断言同步（逻辑断言不动）。
• TSC 干净；本轮三个受测文件 58 项全绿，前轮 multi-instance-live + web-storage-banner + storage-engine-proofs + issue5188 等共 69 项全绿。

关联：#4343（Node 20 bootstrap 故障史）、#5213 落地后的拒绝启动消息体系。

[github-actions]

📦 Built Package Artifact

Branch: 2026-10-31_node22-hint (c592548)

Latest build — install this exact version

npm install -g billion-context@0.0.7466-pr.5326.7d6cb7c

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit	version	build
c592548	billion-context@0.0.7466-pr.5326.7d6cb7c	build
ffc6f6a	billion-context@0.0.7464-pr.5326.5d6d445	build

Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pr5326.tgz
npm install -g package

---

Install instructions are refreshed on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重：不重复——镜像全文检索（no-engine / Node.js 22 / SQLite engine hint）无其他 issue/PR 涉及同一主题；本 PR（GitHub #5326）即该定调的唯一工作项。

审核结论：可合入

独立验证证据（全部在「当前 master f6e69ae + PR head c592548」的合并树上实测，非照抄 PR 描述）：

• 与最新 master 合并干净（git merge-tree exit 0）。注意：master 自分支基点后删掉了 shadow.ts 里 SQLite cache has no graceful degradation when the driver is unavailable: llm/stream throws `Cannot read properties of un | sqlite 缓存在驱动不可用时没有降级：llm/stream 每回合抛 Cannot read properties of undefined (reading 'prepare')（DSH/Electron 打包环境） #5046 的第二写者拒绝块，合并后无冲突、语义不互踩。
• 定向测试 7 个文件 78/78 全绿：storage-cantopen-hint、storage-engine-bootstrap、acp-status-storage-degraded、multi-instance-live、web-storage-banner、storage-engine-proofs、issue5188-sidecar-recoverable-open。
• tsc --noEmit 干净。
• CI（sha c592548，镜像缓存）：30 项中 29 绿/skip，唯一红是 unused-exports——本地在纯 master 复现同样红（src/codex-models.ts: CodexWindowSource），属 master 继承性失败，与本 PR 无关；按 CI Control Center: Centralized CI Failure Handling & Status Sync (Comment all CI issues here; do not open new issues) | CI 总控: CI 失败集中处理与状态同步(所有 CI 问题在此评论, 勿开新 issue) #4599 政策该修收敛到 ci-fixes 哨兵，未在本分支动。
• 分支 BEHIND master 但零冲突，GitHub 可自动合并；合并前建议作者把 master 并进来（非阻塞）。

结构化八问：

1. 是什么问题：没有可用 SQLite 引擎（Node<22 且 better-sqlite3 未装）时 bili 拒绝启动，但这类报错要么没指引、要么升级线索埋在长段策略说明里，用户抓不到重点。
2. 什么原因导致的：sqliteOpenFailureHint() 原先只有两个分支（win32 readonly/CANTOPEN 长提示、其余静默兜底）——"no SQLite engine available" 这个错误串落不进任何分支，于是拒绝启动日志行没有任何可操作指引；status 侧另走 nodeSqliteUpgradeHint()，两处文案各自为政。
3. 影响范围与严重程度：仅错误文案可读性。触发面 = Node<22 且无 better-sqlite3 的机器上启动被拒的用户；体验瑕疵（拒绝本身是正确的裁决行为，只是原因说不清）。
4. 怎么修复的：在唯一 hint 函数里加一条跨平台分支（no-engine → "requires Node.js 22 or newer — upgrade Node.js to v22+"），并把所有拒绝启动日志行统一路由过它（shadow.ts boot-refusal + src/server.ts:565 的 getStore().ready() catch）；同时把面向用户的措辞全局统一为 "Node.js 22 or newer"。改的是指引的产生点，不是逐处打补丁。
5. 是否有回归问题：逐项审过既有行为——win32 CANTOPEN/readonly 长提示不变；非 win32 非 no-engine 保持静默（负向断言保留："file is not a database"→""、linux/darwin CANT_OPEN/READONLY→""）；完整性损坏 fail-open 路径（[Bug][split-brain] Restart-handover notice persists forever after the peer pid is gone (stale storage.splitBrain) #4626 裁决域）未触碰；内部 22.5 门槛逻辑不变（测试钉死 22.4.9→给提示、22.5.1→不给）。无意回归：无。有意变更两条见下。
6. 是否破坏缓存：不涉及。
7. 是否改了设计方向：不涉及（纯文案 + 既有行路由到既有函数）。
8. 是否引入新配置：不涉及。

行为变更披露（旧值→新值 + 原因）：

• A. win32 上 CANTOPEN/readonly 类拒绝启动日志行：原来只有裸错误信息，现在会带上长 win32 提示。PR 正文明确「拒绝启动的日志行统一走该 hint」，有意变更。
• B. 用户可见措辞：Node.js >= 22.5 → Node.js 22 or newer（owner 定调：报错只需要说需要 Node.js 22 以上）。内部门槛仍是 22.5 且测试钉住。副作用提示：严格按"22"升级到 22.0–22.4 的用户仍无内置引擎（实际从 22.5 起），但完整句子仍带 "upgrade Node.js for the builtin engine" 且自下载镜像链兜底，按定调执行。
• C. 一处描述与机制不符（不影响验收）：PR 正文说 "/__bili/status 的 degradeReason 走同一函数自动带上这句"——实测 status 侧 no-engine 情形先命中更早的 isNoEngineError 分支（用 nodeSqliteUpgradeHint()），新分支主要作用于日志行；status 侧本来就有升级指引，最终用户可见结果一致，只是归因写偏了。

测试有效性：新增断言有牙——删掉新分支或给它加平台门都会红；负方向（该静默的仍静默）保留；22.5 门槛正反两侧都有钉。真测试。

判定：可合入。唯一红（unused-exports）为 master 继承，不拦本 PR；建议合并前顺手 merge 一次 master。