From 304379c80cac4f5cc2554d901c9aca607f73a8d9 Mon Sep 17 00:00:00 2001
From: Kaxi <1042864399@qq.com>
Date: Sun, 27 Sep 2026 04:23:31 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AF=B4=E6=98=8E=20test-qr=20?=
 =?UTF-8?q?=E7=9A=84=E5=8F=82=E8=80=83=E5=AE=9E=E7=8E=B0=E5=89=8D=E7=BD=AE?=
 =?UTF-8?q?=E6=9D=A1=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

test-qr.mjs 需要一个 npm qrcode 作为对照（仅测试用，非运行时依赖），
但脚本与 README 都没说明如何准备，克隆后直接 npm test 会在这一步失败。
现在脚本直接打印可复制的准备命令，README 中英双语也补充了说明与
QR_ORACLE_DIR 的用法。
---
 README.en.md        | 3 +++
 README.md           | 3 +++
 scripts/test-qr.mjs | 3 +++
 3 files changed, 9 insertions(+)

diff --git a/README.en.md b/README.en.md
index f5d4e74..17ed0de 100644
--- a/README.en.md
+++ b/README.en.md
@@ -125,6 +125,9 @@ adaptive choice, remove the last three entries of `cordis.patch.yml` (the
 node scripts/build-client.mjs   # generates client.js from src/panel.js + src/qrcode.js
 node scripts/smoke.mjs          # host forwarding contract (HTTP/WS/Host/Origin/cookie/bind failure)
 node scripts/test-qr.mjs        # module-by-module comparison against the npm qrcode reference
+# test-qr.mjs compares against a reference implementation (test-only, never a runtime dep):
+#   mkdir -p /tmp/qr-oracle && cd /tmp/qr-oracle && npm init -y && npm i qrcode@1.5.4
+# elsewhere: QR_ORACLE_DIR=<dir> node scripts/test-qr.mjs
 node scripts/test-client.mjs    # browser contract (slot registration, render, route agreement)
 ```
 
diff --git a/README.md b/README.md
index ee5686b..d621be2 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,9 @@ DSH 官方把「持久化设置」限制在回环页面：客户端由 `location
 node scripts/build-client.mjs   # 由 src/panel.js + src/qrcode.js 生成 client.js
 node scripts/smoke.mjs          # 宿主端转发契约（HTTP/WS/Host/Origin/cookie/绑定失败）
 node scripts/test-qr.mjs        # 与 npm qrcode 参考实现逐模块比对
+# test-qr.mjs 需要一个“参考实现”作为对照（仅测试用，不是运行时依赖）：
+#   mkdir -p /tmp/qr-oracle && cd /tmp/qr-oracle && npm init -y && npm i qrcode@1.5.4
+# 放在别处就用 QR_ORACLE_DIR=<dir> node scripts/test-qr.mjs
 node scripts/test-client.mjs    # 浏览器端契约（槽位注册、渲染、路由一致）
 ```
 
diff --git a/scripts/test-qr.mjs b/scripts/test-qr.mjs
index d8bede5..7f04d30 100644
--- a/scripts/test-qr.mjs
+++ b/scripts/test-qr.mjs
@@ -16,6 +16,9 @@ try {
   oracle = requireFromOracle('qrcode')
 } catch (error) {
   console.error(`cannot load the qrcode oracle from ${oracleDir}: ${error.message}`)
+  console.error('prepare it once with:')
+  console.error(`  mkdir -p ${oracleDir} && cd ${oracleDir} && npm init -y && npm i qrcode@1.5.4`)
+  console.error(`or point QR_ORACLE_DIR at a directory that already has it.`)
   process.exit(2)
 }