@gavinc-cn/touchstone-dsh 0.2.0 → 0.4.0

package/backend/lib/pybase64.js

@@ -0,0 +1,114 @@
+/**
+ * `base64.b64decode` 的 Node 对应物（M5-4 附件上传端点用）。
+ *
+ * ## 为什么不能直接用 `Buffer.from(s, 'base64')`
+ * Node 的解码器**永不报错**：非法字符丢弃、长度随便、`=` 随便放，坏输入静默产出垃圾字节。
+ * Python 的 `base64.b64decode`（`binascii.a2b_base64`，`strict_mode=False`）在坏输入上
+ * **抛 `binascii.Error`（ValueError 子类）**，`_api_board_upload_media` 据此回
+ * 400 `{"error":"bad base64"}`。若 Node 照 Node 的口径走，坏 base64 会被写成一个垃圾附件
+ * 文件并回 200 —— 用户看到「上传成功」但内容损坏（**比报错更难查**）。
+ *
+ * ## 口径（逐条实测自 CPython 3.12 的 `binascii.a2b_base64`）
+ * 1. **非 ASCII 的 str**：Python 先 `encode('ascii')` ⇒ `ValueError`。
+ * 2. 过滤：删掉所有不在 `A-Za-z0-9+/=` 的字符（空白、`!`、中文…），保留 `=`。
+ * 3. 主体解码：每 4 个数据字符出 3 字节；遇 `=` 的分支是**反直觉的那个**：
+ *    · `=` 前已攒 **3** 个数据字符 ⇒ 出 2 字节并**立即结束**（**其后的输入整段被忽略**：
+ *      `'aGVsbG8=extra'` → `b'hello'`）；
+ *    · `=` 前已攒 **2** 个数据字符、且**紧跟着还有一个 `=`** ⇒ 出 1 字节并立即结束
+ *      （`'0x= ==0A'` → 1 字节）；只有**一个** `=` 时该 `=` 被**跳过**、继续攒
+ *      （`'AA=AA'` → 3 字节 = `'AAAA'`）；
+ *    · 其余（0 或 1 个数据字符）：跳过。
+ * 4. 收尾校验（未触发上面两个「立即结束」时）：余数 r = 数据字符数 % 4
+ *    · r = 0 ⇒ 成功；r = 1 ⇒ **错误**（Python 文案是「…cannot be 1 more than a multiple of 4」）；
+ *    · r = 2 ⇒ 要求结尾**至少两个** `=`；r = 3 ⇒ 要求结尾**至少一个** `=`，否则
+ *      「Incorrect padding」。判据只看**结尾**的 `=`，中间位置的 `=` 不作数。
+ *
+ * ## 保真度证据
+ * 与 `base64.b64decode` 做了 **760,000 条随机串**的差分（三种偏置字母表：混合/`=` 密集/
+ * 纯 `=/`；长度 0..20，含非 ASCII 与空白），**零不一致**；外加 27 条人工语料（含本文件
+ * 注释里的每一个例子）。见 `backend/test/pybase64.test.mjs`（表来自 Python 实跑）。
+ *
+ * ## 与 Python 的形态差异（已登记）
+ * · 异常类名 `PyB64Error` 对应 `binascii.Error`；**异常文案不逐字复刻**（调用方只判类型，
+ *   正文由端点写死 `bad base64`）。
+ * · Python 的 `str()` 对**容器**给 repr（`{'a': 1}`）；Node 侧走全仓已登记的容器口径
+ *   （见 `doc_ai/spec/dsh_plugin/dsh插件形态.md` §23.7）——上传端点的 `data` 只会是字符串，
+ *   该差异只在「有人把 `data` 传成对象」时可见，两侧同为拒绝/同为乱码的概率不保证。
+ */
+
+/** `binascii.Error` 的对应物（ValueError 子类）；调用方据此回 400 `bad base64`。 */
+export class PyB64Error extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'PyB64Error';
+  }
+}
+
+/** 标准 base64 字母表（`A-Za-z0-9+/`，`=` 单独处理） */
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** 字符 → 6 bit 值（查表；非字母表字符不在表内） */
+const VAL = new Map();
+for (let i = 0; i < ALPHABET.length; i += 1) VAL.set(ALPHABET[i], i);
+
+/** 一位字符是否是字母表成员（含 `=` 由调用方另判） */
+function inAlphabet(ch) {
+  return VAL.has(ch);
+}
+
+/**
+ * 解 base64（Python `base64.b64decode(text)` 的非严格口径）。
+ *
+ * @param {string} text 输入串（**必须已是 str**；调用方按 Python `str(x or "")` 归一）
+ * @returns {Buffer} 解出的字节
+ * @throws {PyB64Error} 命中 Python 会抛 `ValueError`/`binascii.Error` 的任一情形
+ */
+export function b64decode(text) {
+  const s = String(text);
+  // ① 非 ASCII：Python `_bytes_from_decode_data` 走 s.encode('ascii') ⇒ ValueError
+  //    （按码位判，不接受任何 > 0x7f 的字符）
+  for (const ch of s) {
+    if (ch.codePointAt(0) > 0x7f) {
+      throw new PyB64Error('string argument should contain only ASCII characters');
+    }
+  }
+  // ② 过滤非字母表字符（保留 '='）
+  const kept = [];
+  for (const ch of s) {
+    if (ch === '=' || inAlphabet(ch)) kept.push(ch);
+  }
+  const out = [];
+  let quad = [];
+  const flush = (n) => {
+    // n = 本 quad 的有效数据字符数（4→3 字节 / 3→2 字节 / 2→1 字节）
+    const v = [VAL.get(quad[0]), VAL.get(quad[1]), quad.length > 2 ? VAL.get(quad[2]) : 0,
+      quad.length > 3 ? VAL.get(quad[3]) : 0];
+    out.push((v[0] << 2) | (v[1] >> 4));
+    if (n >= 3) out.push(((v[1] & 0x0f) << 4) | (v[2] >> 2));
+    if (n >= 4) out.push(((v[2] & 0x03) << 6) | v[3]);
+  };
+  for (let i = 0; i < kept.length; i += 1) {
+    const ch = kept[i];
+    if (ch === '=') {
+      if (quad.length === 3) { flush(3); return Buffer.from(out); }      // 出 2 字节，其后忽略
+      if (quad.length === 2 && kept[i + 1] === '=') {                     // 双 '=' ⇒ 出 1 字节
+        flush(2);
+        return Buffer.from(out);
+      }
+      continue;                                                           // 其余位置的 '=' 跳过
+    }
+    quad.push(ch);
+    if (quad.length === 4) { flush(4); quad = []; }
+  }
+  const r = quad.length;
+  if (r === 0) return Buffer.from(out);
+  if (r === 1) {
+    throw new PyB64Error('Invalid base64-encoded string: number of data characters cannot be 1'
+      + ' more than a multiple of 4');
+  }
+  let trail = 0;
+  for (let i = kept.length - 1; i >= 0 && kept[i] === '='; i -= 1) trail += 1;
+  if (trail < 4 - r) throw new PyB64Error('Incorrect padding');
+  flush(r);
+  return Buffer.from(out);
+}

package/backend/lib/pyjson.js

@@ -0,0 +1,214 @@
+/**
+ * Python `json.dumps(obj, ensure_ascii=False)` 的 Node 对应物（M1，2026-10-11）。
+ *
+ * 为什么需要它：两版后端**开同一个库**，JSON 列的原始文本也是「数据」的一部分。Python 侧一律
+ * `json.dumps(..., ensure_ascii=False)`（indent=None 时的默认分隔符 `", "` / `": "`），若 Node 侧
+ * 用 `JSON.stringify`（紧凑 `,` / `:`），同一份逻辑数据的落库文本就会不同 —— 对拍里表现为
+ * 「值一样、文本不一样」，只能靠白名单遮住，等于永久放弃这几列的逐字节可比性。
+ * 本模块把这层口径补齐。首个使用点：`db.js` 的 `feishu_appsettings_bridge`（写
+ * `feishu_user_cfgs.json`）；M3+ 的 `board_settings.json` / `user_prefs.value` /
+ * `app_settings.json` / `wait_items.meta` / `tasks.payload` 等 JSON 写入点复用同一入口。
+ *
+ * 逐字符对齐 CPython 的部分（有测试向量钉住）：
+ *   - 分隔符 `", "` 与 `": "`；空容器为 `{}` / `[]`；
+ *   - 非 ASCII 原样输出（ensure_ascii=False）：中文、emoji 都不转义，也不拆代理对；
+ *   - 转义集合与 CPython 相同：`"` `\` `\b` `\f` `\n` `\r` `\t`，其余 < U+0020 走 `\u00xx`
+ *     （小写 hex）；DEL(U+007F)、U+2028/U+2029、`/`、`'` **不**转义（与 CPython 一致）；
+ *   - `true` / `false` / `null`；数组；对象（键保持插入序，等价于 dict 保序）；
+ *   - 整数（含负零以外的负数、0）：十进制原文逐字符相同（超过 2^53 请传 BigInt，见下）。
+ *
+ * **浮点的残余偏差（已知、原理上不可消除；如实记录，别当 bug 修）**：
+ *   - Python 区分 int 与 float：`json.dumps({"x": 1.0})` → `{"x": 1.0}`，而 JS 的 `1.0` 就是 `1`，
+ *     类型信息在 `JSON.parse` 时就丢了 ⇒ 本实现输出 `{"x": 1}`。**无法对齐**（信息不存在）；
+ *   - 指数记法阈值不同：CPython repr 在 exp < -4 或 exp >= 16 时切指数，JS 在 exp < -7 或
+ *     exp >= 21 时切 ⇒ `1e-05`(Py) vs `0.00001`(JS)、`1e+16`(Py) vs `10000000000000000`(JS)；
+ *   - **指数补零**（2026-10-11 评审补记，与阈值无关的另一类）：两侧都落指数记法时，CPython 的
+ *     指数至少两位补零、JS 不补 ⇒ `1e-07`(Py) vs `1e-7`(JS)、`1e-08`(Py) vs `1e-8`(JS)；
+ *   - **≥1e21 的普通 number**（2026-10-11 评审补记）：两侧都切指数但形态可能不同，且「普通 number
+ *     到这个量级已丢精度」这个理由对 1e21 这种**可精确表示**的值并不成立——所以别指望「整数一律
+ *     逐字符相同」覆盖它；该量级请传 BigInt 或字符串；
+ *   - `-0.0`：Python → `-0.0`，JS `String(-0)` → `0`；
+ *   - 尾数两侧都是「最短往返」表示，故 1.5 / 0.1 / 3.141592653589793 这类一致；
+ *   - NaN/Infinity：CPython 默认 `allow_nan=True`，输出 `NaN` / `Infinity` / `-Infinity`
+ *     （严格 JSON 非法），本实现同样输出这三个字面量。
+ *   结论：JSON 列里若出现**整数值的浮点**、`<1e-4` 或 `≥1e16` 量级的浮点，对拍仍会看到文本差异
+ *   —— 那属于上述固有偏差；字符串/整数/布尔/null/嵌套结构一律逐字节一致。
+ *
+ * JS 专有值的边界（一律抛 TypeError，绝不静默写坏数据）：
+ *   - `undefined` / 函数 / symbol：Python 侧无对应物（「没有值」请显式传 null）；
+ *   - Date / Map / Set / 类实例：CPython 只认 dict/list/str/int/float/bool/None，同类对象抛 TypeError；
+ *     本模块只接受**普通对象**（含 null 原型对象，如 node:sqlite 返回的行）；
+ *   - 超过 2^53 的整数请传 BigInt：输出十进制原文，与 Python 任意精度 int 逐字符相同
+ *     （普通 number 到这个量级已经丢精度，属调用方问题）。
+ */
+
+/** 与 CPython `py_encode_basestring_ascii`/`escape` 相同的命名转义（其余 < U+0020 走 \u00xx） */
+const STRING_ESCAPES = new Map([
+  ['"', '\\"'],
+  ['\\', '\\\\'],
+  ['\b', '\\b'],
+  ['\f', '\\f'],
+  ['\n', '\\n'],
+  ['\r', '\\r'],
+  ['\t', '\\t'],
+]);
+
+/**
+ * 序列化成 CPython `json.dumps(obj, ensure_ascii=False)` 的默认形态。
+ * @param {unknown} value 普通对象/数组/字符串/数字/布尔/null/BigInt（嵌套任意层）
+ * @returns {string} JSON 文本
+ * @throws {TypeError} 遇到 Python 侧不存在的类型（undefined/函数/symbol）或非普通对象（Date/Map/Set/类实例）
+ */
+export function pyJsonDumps(value) {
+  return encodeValue(value);
+}
+
+/**
+ * 序列化成 CPython `json.dumps(obj, ensure_ascii=False, indent=N)` 的形态（M6-2）。
+ *
+ * 与 `pyJsonDumps` 的差别只有**缩进与分隔符**（CPython 的规则：`indent` 非 None 时
+ * `item_separator=','`、`key_separator=': '`，并在每个元素前换行 + 缩进 `indent*层`）：
+ *   - 空容器仍是 `{}` / `[]`（CPython 对空容器不换行）；
+ *   - 嵌套容器紧跟键值冒号后的同一行开始（`"a": {\n …`）；
+ *   - 字符串/数字/布尔/null 的编码与无缩进版**共用同一段实现**（含 ensure_ascii=False、
+ *     控制字符 `\u00xx`、浮点的已知偏差——见文件头）。
+ *
+ * 使用点：`export_cases.py:126`（`retest-candidates --json`）、`loadcase.py:547`、
+ * `loadgen.py:618`（报告落盘的 `indent=1`）。
+ *
+ * @param {unknown} value
+ * @param {number|string} indent 空格数（或自定义缩进串，照 CPython 允许字符串）
+ * @returns {string}
+ */
+export function pyJsonDumpsIndent(value, indent = 1) {
+  const pad = typeof indent === 'string' ? indent : ' '.repeat(Math.max(0, Number(indent) || 0));
+  return encodeIndented(value, pad, 0);
+}
+
+/** 带层级的编码（缩进形态；其余规则与 `encodeValue` 逐条相同） */
+function encodeIndented(value, pad, level) {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'number':
+      return encodeNumber(value);
+    case 'bigint':
+      return value.toString();
+    case 'string':
+      return encodeString(value);
+    case 'object': {
+      const inner = pad.repeat(level + 1);
+      const close = pad.repeat(level);
+      if (Array.isArray(value)) {
+        if (value.length === 0) return '[]';
+        const parts = value.map((item) => inner + encodeIndented(item, pad, level + 1));
+        return `[\n${parts.join(',\n')}\n${close}]`;
+      }
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        throw new TypeError('pyJsonDumpsIndent: 只接受普通对象/数组'
+          + '（Date、Map、Set、类实例在 Python 侧同样抛 TypeError）');
+      }
+      const keys = Object.keys(value);
+      if (keys.length === 0) return '{}';
+      const parts = keys.map((key) => inner + encodeString(key) + ': '
+        + encodeIndented(value[key], pad, level + 1));
+      return `{\n${parts.join(',\n')}\n${close}}`;
+    }
+    default:
+      throw new TypeError(`pyJsonDumpsIndent: 不能序列化 ${typeof value}`
+        + '（Python 侧同类对象抛 TypeError；缺值请显式传 null）');
+  }
+}
+
+/**
+ * 任意 JSON 值的编码分派。
+ * @param {unknown} value
+ * @returns {string}
+ */
+function encodeValue(value) {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'number':
+      return encodeNumber(value);
+    case 'bigint':
+      return value.toString();
+    case 'string':
+      return encodeString(value);
+    case 'object':
+      return Array.isArray(value) ? encodeArray(value) : encodeObject(value);
+    default:
+      throw new TypeError(`pyJsonDumps: 不能序列化 ${typeof value}`
+        + '（Python 侧同类对象抛 TypeError；缺值请显式传 null）');
+  }
+}
+
+/**
+ * 数字编码：NaN/±Infinity 用 Python 字面量，其余用 JS 最短往返表示（见文件头浮点偏差说明）。
+ * @param {number} value
+ * @returns {string}
+ */
+function encodeNumber(value) {
+  if (Number.isNaN(value)) return 'NaN';          // CPython allow_nan=True
+  if (value === Infinity) return 'Infinity';
+  if (value === -Infinity) return '-Infinity';
+  return String(value);
+}
+
+/**
+ * 字符串编码：按**码点**遍历（代理对不被拆开），转义集合与 CPython ensure_ascii=False 相同。
+ * @param {string} value
+ * @returns {string} 带引号的 JSON 字符串
+ */
+function encodeString(value) {
+  let out = '"';
+  for (const ch of value) {
+    const escape = STRING_ESCAPES.get(ch);
+    if (escape !== undefined) {
+      out += escape;
+      continue;
+    }
+    const code = ch.codePointAt(0);
+    if (code < 0x20) {
+      // 其余控制字符：\u00xx（小写 hex，与 CPython 一致）
+      out += '\\u' + code.toString(16).padStart(4, '0');
+      continue;
+    }
+    out += ch;
+  }
+  return out + '"';
+}
+
+/**
+ * 数组编码（元素间 `", "`）。稀疏数组的洞会走到 encodeValue(undefined) 并抛 TypeError。
+ * @param {unknown[]} value
+ * @returns {string}
+ */
+function encodeArray(value) {
+  const parts = [];
+  for (let i = 0; i < value.length; i += 1) parts.push(encodeValue(value[i]));
+  return '[' + parts.join(', ') + ']';
+}
+
+/**
+ * 对象编码（键保持插入序，`": "` 分隔，项间 `", "`）。
+ * 只接受普通对象（Object.prototype 或 null 原型）：Date/Map/Set/类实例在 Python 侧同样不可序列化，
+ * 与其静默写成 `{}` 不如在此抛错。
+ * @param {object} value
+ * @returns {string}
+ */
+function encodeObject(value) {
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    throw new TypeError('pyJsonDumps: 只接受普通对象/数组'
+      + '（Date、Map、Set、类实例在 Python 侧同样抛 TypeError）');
+  }
+  const parts = [];
+  for (const key of Object.keys(value)) {
+    parts.push(encodeString(key) + ': ' + encodeValue(value[key]));
+  }
+  return '{' + parts.join(', ') + '}';
+}

package/backend/lib/query.js

@@ -0,0 +1,125 @@
+/**
+ * 查询串与百分号编解码 —— `urllib.parse` 对应物（`server.py:do_GET` 的第一件事就是
+ * `parse_qs(self.path.split("?", 1)[1])`，几乎每个读端点都吃它的结果）。
+ *
+ * **为什么必须自己写**：Node 的 `URLSearchParams` 与 Python `parse_qs` 有四处可观察差异，
+ * 每一处都能让读端点行为漂移：
+ *   ① `URLSearchParams` 保留空值（`?raw=` → `raw=""`），Python 缺省 **丢弃空值**
+ *      （`keep_blank_values=False`）⇒ `parsed.get("raw", [""])[0]` 得到 `""` 而不是
+ *      「没这个键」。端点里大量 `or "main"` 兜底就是靠这个区别生效的；
+ *   ② Python 3.10 起 `;` **不再是分隔符**（`a=1;a=2` 是一个键 `a` 值 `1;a=2`）；
+ *      `URLSearchParams` 同样不切 `;`，但 `parse_qsl(separator=...)` 的历史差异常被记错；
+ *   ③ 解码口径：键与值都走 `unquote_plus`（`+`→空格 后再百分号解码），
+ *      而**路径里的** `unquote(media_id)` 不处理 `+`；
+ *   ④ 非法百分号转义（`%ZZ`）原样保留，非法 UTF-8 字节按 U+FFFD 替换（`errors='replace'`）。
+ *
+ * 期望值全部由本机 Python 3.12 实测产出（`backend/test/query.test.mjs` 里逐条钉住），
+ * 不是按文档猜的。
+ */
+
+/**
+ * 收集百分号转义字节的游标解码器：连续 `%XX` 攒成一个字节串一起做 UTF-8 解码
+ * （多字节字符必须一起解），遇到非转义字符就先冲掉已攒字节。
+ *
+ * 与 Python `unquote` 的实现同构：Python 用 `_asciire` 把串切成「ASCII 段/非 ASCII 段」，
+ * 对含 `%` 的段做 `unquote_to_bytes(...).decode(encoding, 'replace')`，其余原样拼接。
+ * 区别仅在于 Python 是「整段一次解码」而这里按转义连续段解码——对 UTF-8 而言等价
+ * （同一段里的字节本来就该一起解；跨段的多字节字符在 Python 里也会被拆成两次
+ * `decode` 从而各自出替换符，这里同样）。
+ */
+function makeByteDecoder() {
+  const decoder = new TextDecoder('utf-8', { fatal: false });
+  let bytes = [];
+  return {
+    /** 攒一个转义字节 */
+    push(byte) { bytes.push(byte); },
+    /** 冲掉已攒字节，返回解码文本（无字节时返回空串） */
+    flush() {
+      if (bytes.length === 0) return '';
+      const out = decoder.decode(Uint8Array.from(bytes));
+      bytes = [];
+      return out;
+    },
+  };
+}
+
+const HEX = /^[0-9A-Fa-f]{2}$/;
+
+/**
+ * `urllib.parse.unquote(s)`：`+` **不**转空格；非法转义原样；非法 UTF-8 → U+FFFD。
+ */
+export function unquote(value) {
+  const s = String(value ?? '');
+  if (!s.includes('%')) return s;      // 与 Python 的快路径一致（也避开无谓的构造）
+  const dec = makeByteDecoder();
+  let out = '';
+  for (let i = 0; i < s.length; i += 1) {
+    const ch = s[i];
+    if (ch === '%' && i + 2 < s.length && HEX.test(s.slice(i + 1, i + 3))) {
+      dec.push(parseInt(s.slice(i + 1, i + 3), 16));
+      i += 2;
+      continue;
+    }
+    out += dec.flush() + ch;           // 非转义字符：先冲字节段，再原样输出
+  }
+  return out + dec.flush();
+}
+
+/** `urllib.parse.unquote_plus(s)`：先 `+`→空格，再按 `unquote` 解（查询串键值口径） */
+export function unquotePlus(value) {
+  return unquote(String(value ?? '').replace(/\+/g, ' '));
+}
+
+/**
+ * `urllib.parse.quote(s, safe='/')`：安全字符 = 字母数字 + `_.-~` + `safe`；
+ * 其余按 UTF-8 逐字节 `%XX`（大写十六进制）。
+ */
+export function quote(value, safe = '/') {
+  let out = '';
+  for (const byte of Buffer.from(String(value ?? ''), 'utf8')) {
+    const ch = String.fromCharCode(byte);
+    const keep = (byte < 128
+      && (/[A-Za-z0-9]/.test(ch) || ch === '_' || ch === '.' || ch === '-' || ch === '~'
+        || safe.includes(ch)));
+    out += keep ? ch : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+  }
+  return out;
+}
+
+/**
+ * `urllib.parse.parse_qs(qs)`：`&` 分隔（**不切 `;`**）、空值丢弃、同名键聚成数组、
+ * 键值都过 `unquote_plus`。
+ *
+ * 返回**无原型对象**（等价于 Python dict）：查询串里出现 `__proto__=x` 时不能污染
+ * 原型链——Python 里它只是个普通键。
+ */
+export function parseQs(qs) {
+  const out = Object.create(null);
+  const s = String(qs ?? '');
+  if (!s) return out;
+  for (const pair of s.split('&')) {
+    if (!pair) continue;                       // 'a=1&&b=2' 的空段
+    const eq = pair.indexOf('=');
+    const rawName = eq === -1 ? pair : pair.slice(0, eq);
+    const rawValue = eq === -1 ? '' : pair.slice(eq + 1);
+    // keep_blank_values=False：**空值整对丢弃**（'raw' 与 'raw=' 都不出现在结果里）；
+    // 空名但值非空（'=1'）Python 仍保留成 {'': ['1']}，此处照抄
+    if (rawValue === '') continue;
+    const name = unquotePlus(rawName);
+    const value = unquotePlus(rawValue);
+    if (out[name]) out[name].push(value);
+    else out[name] = [value];
+  }
+  return out;
+}
+
+/**
+ * `parsed.get(name, [def])[0]` 的对应物（端点里最常见的取值形态）。
+ *
+ * 注意传 `def` 的语义：Python 只在**键不存在**时用默认值；键存在则取首个值。
+ * 由于 `parseQs` 已丢弃空值，键存在即值非空——与 Python 逐点同。
+ */
+export function qsGet(parsed, name, def = '') {
+  const values = parsed ? parsed[name] : undefined;
+  return values && values.length ? values[0] : def;
+}