jsql-neo 6.5.12 → 6.5.14

package/README.md

@@ -3,7 +3,7 @@
 > **One engine to rule them all** — a Rust-powered embedded database that speaks your language:
 > MySQL, PostgreSQL, MongoDB, Redis, SQL, TypeScript, **and the browser**.
 
-> **v6.5.12** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.14** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
 
 ![Engines](https://img.shields.io/badge/engines-Native%20%7C%20WASM%20%7C%20Pure%20JS-7ee787)
 ![MySQL](https://img.shields.io/badge/protocol-MySQL%20compatible-1f6feb)

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.5.12 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.5.14 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');

package/lib/btree.js

@@ -24,8 +24,6 @@ class BTree {
         this._unique = unique;
         this._root = new BTreeNode();
         this._size = 0;
-        this._minKeys = Math.floor(order / 2) - 1;
-        this._minDegree = Math.ceil(order / 2);
     }
 
     get size() { return this._size; }
@@ -273,122 +271,81 @@ class BTree {
 
     remove(key, rowIndex) {
         if (!this._root) return false;
-        const removed = this._removeFromNode(this._root, key, rowIndex);
-        // 删掉整个键（而非仅删某个 rowIndex）后，叶子的键域可能缩小，
-        // 沿途的分隔键副本可能已指向不存在的键 —— 自顶向下重建一次。
-        if (removed) {
-            this._size--;
-            if (!this._root.leaf) this._fixSeparators(this._root);
-        }
-        if (this._root.keys.length === 0 && !this._root.leaf && this._root.children.length > 0) {
-            this._root = this._root.children[0];
-        }
-        return removed;
+        const res = this._removeFromNode(this._root, key, rowIndex);
+        if (!res.found) return false;
+        if (!res.remaining) this._size--;
+        // 只做惰性删除 + 分隔键归一：不再在下降途中借用/合并。
+        // 旧实现先对路由到的子节点做 borrow/merge 再检查键是否存在，
+        // 删除一个不存在的键（或 rowIndex 不匹配）也会重构整棵树，
+        // 合并时丢掉的分隔键副本可能正好是仍然存活的数据键 —— 条目静默丢失。
+        this._normalize();
+        return !res.remaining;
     }
 
     _removeFromNode(node, key, rowIndex) {
         if (node.leaf) {
             const i = this._lowerBound(node.keys, key);
-            if (i >= node.keys.length || node.keys[i] !== key) return false;
-            if (!node.values[i].includes(rowIndex)) return false;
+            if (i >= node.keys.length || node.keys[i] !== key) return { found: false };
+            const pos = node.values[i].indexOf(rowIndex);
+            if (pos === -1) return { found: false };
             const vals = node.values[i].filter(v => v !== rowIndex);
             if (vals.length === 0) {
                 node.keys.splice(i, 1);
                 node.values.splice(i, 1);
-                return true;
+                return { found: true, remaining: false };
             }
             node.values[i] = vals;
-            return false;
+            return { found: true, remaining: true };
         }
 
-        let i = this._route(node, key);
-
-        // 下降前确保子节点有足够键，避免欠满子节点
+        const i = this._route(node, key);
         const child = node.children[i];
-        if (child.keys.length <= this._minKeys) {
-            i = this._rebalanceChild(node, i);
-        }
-        return this._removeFromNode(node.children[i], key, rowIndex);
+        if (!child) return { found: false };
+        return this._removeFromNode(child, key, rowIndex);
     }
 
-    _rebalanceChild(parent, i) {
-        if (i > 0 && parent.children[i - 1].keys.length > this._minKeys) {
-            this._borrowFromLeft(parent, i);
-            return i;
-        }
-        if (i + 1 < parent.children.length && parent.children[i + 1].keys.length > this._minKeys) {
-            this._borrowFromRight(parent, i);
-            return i;
-        }
-        if (i > 0) {
-            this._mergeChildren(parent, i - 1);
-            return i - 1;
-        }
-        this._mergeChildren(parent, i);
-        return i;
+    /**
+     * 惰性回收：删掉节点里空的叶子/空子树，折叠只剩一个孩子的内部节点，
+     * 并按「分隔键 = 左子树最大键」的约定重算所有内部键，最后重建叶子链表。
+     * 节点欠满不影响正确性（插入时仍然按满则分裂），因此无需借用/合并。
+     */
+    _normalize() {
+        const root = this._cleanNode(this._root);
+        this._root = root || new BTreeNode();
+        this._relinkLeaves();
     }
 
-    _borrowFromLeft(parent, i) {
-        const left = parent.children[i - 1];
-        const right = parent.children[i];
-        if (right.leaf) {
-            // 叶子节点：移动左叶最大键到右叶最小位置
-            const k = left.keys.pop();
-            const v = left.values.pop();
-            right.keys.unshift(k);
-            right.values.unshift(v);
-            // 父节点分隔键应为左叶新的最大值（pop 后的最后一个键）
-            parent.keys[i - 1] = left.keys[left.keys.length - 1];
-            parent.values[i - 1] = left.values[left.values.length - 1];
-        } else {
-            right.keys.unshift(parent.keys[i - 1]);
-            right.values.unshift(parent.values[i - 1]);
-            parent.keys[i - 1] = left.keys.pop();
-            parent.values[i - 1] = left.values.pop();
-            right.children.unshift(left.children.pop());
+    _cleanNode(node) {
+        if (node.leaf) return node.keys.length === 0 ? null : node;
+        const kids = [];
+        for (const c of node.children) {
+            const kept = this._cleanNode(c);
+            if (kept) kids.push(kept);
         }
-    }
-
-    _borrowFromRight(parent, i) {
-        const left = parent.children[i];
-        const right = parent.children[i + 1];
-        if (left.leaf) {
-            // 叶子节点：用被移动的键而非旧分隔键，避免重复
-            const k = right.keys.shift();
-            const v = right.values.shift();
-            left.keys.push(k);
-            left.values.push(v);
-            parent.keys[i] = k;
-            parent.values[i] = v;
-        } else {
-            left.keys.push(parent.keys[i]);
-            left.values.push(parent.values[i]);
-            parent.keys[i] = right.keys.shift();
-            parent.values[i] = right.values.shift();
-            left.children.push(right.children.shift());
+        node.children = kids;
+        if (kids.length === 0) return null;
+        if (kids.length === 1) return kids[0];
+        node.keys = [];
+        node.values = [];
+        for (let i = 0; i < kids.length - 1; i++) {
+            const m = this._getMax(kids[i]);
+            node.keys.push(m.key);
+            node.values.push(m.value);
         }
+        return node;
     }
 
-    /**
-     * 修复内部节点的分隔键：keys[i] 必须是一个**确实存在于 child[i] 里**的键。
-     *
-     * 背景：分隔键的约定是「左子树的最大键」（叶子上存真实数据，父节点存副本）。
-     * remove() 删掉叶子上的某个键后，如果那个键正好是父节点的分隔键副本，
-     * 分隔键就会指向一个已经不存在的值 —— 树还能路由对，但内部键不再严格递增，
-     * 下一次 borrow/merge 就会把它复制成重复键，直接破坏结构。
-     *
-     * 最小复现（BTree(4)）：
-     *   +28:1 +24:4 +0:0 +14:2 -24:4 +25:4 +24:2 +28:1 -26:2
-     * 前 8 步都正常，第 9 步把 keys=[24,25] 变成 [24,24]。
-     */
-    _fixSeparators(node) {
-        if (node.leaf) return;
-        for (let i = 0; i < node.keys.length; i++) {
-            const m = this._getMax(node.children[i]);
-            node.keys[i] = m.key;
-            node.values[i] = m.value;
+    _relinkLeaves() {
+        let head = this._root;
+        while (head && !head.leaf) head = head.children[0];
+        let prev = null;
+        let node = head;
+        while (node) {
+            if (prev) prev.next = node;
+            prev = node;
+            node = node.next;
         }
-        for (const c of node.children) this._fixSeparators(c);
+        if (prev) prev.next = null;
     }
 
     _getMax(node) {
@@ -397,27 +354,6 @@ class BTree {
         return { key: node.keys[i], value: node.values[i] };
     }
 
-    _mergeChildren(parent, index) {
-        const left = parent.children[index];
-        const right = parent.children[index + 1];
-        const midKey = parent.keys[index];
-        const midVal = parent.values[index];
-
-        // 叶子节点：分隔键是叶子的副本（已在 left 或 right 中），不能重复压入
-        if (!left.leaf) {
-            left.keys.push(midKey);
-            left.values.push(midVal);
-        }
-        for (const __e of right.keys) left.keys.push(__e);
-        for (const __e of right.values) left.values.push(__e);
-        if (!left.leaf) for (const __e of right.children) left.children.push(__e);
-        if (left.leaf) left.next = right.next;
-
-        parent.keys.splice(index, 1);
-        parent.values.splice(index, 1);
-        parent.children.splice(index + 1, 1);
-    }
-
     // ============================================================
     // 遍历
     // ============================================================

package/lib/database.js

@@ -1344,15 +1344,11 @@ class Database {
             startedAt: Date.now()
         };
 
-        if (level === 'REPEATABLE_READ') {
-            // 快照：保存当前所有数据（深拷贝，保证嵌套对象可回滚）
-            this._transaction.snapshot = this._captureTxSnapshot();
-        } else {
-            // READ_COMMITTED：只保存 autoIncrement
-            for (const [name, table] of Object.entries(this._tables)) {
-                this._transaction.autoIncrements[name] = table._autoIncrement;
-            }
-        }
+        // 无论隔离级别都要保存完整快照：ROLLBACK 必须撤销本事务写入的行。
+        // 此前 READ_COMMITTED 只记 autoIncrement，回滚后行原样残留（静默不撤销）。
+        // 隔离级别只影响「读取时能否看到其他事务的已提交数据」（这里是单连接内嵌库，
+        // 不涉及并发可见性），不应影响回滚能力。
+        this._transaction.snapshot = this._captureTxSnapshot();
 
         this._savepointStack = [];
         this._walWrite({ op: 'begin', level });
@@ -1374,12 +1370,6 @@ class Database {
 
         if (this._transaction.snapshot) {
             this._restoreTxSnapshot(this._transaction.snapshot);
-        } else {
-            // READ_COMMITTED：没有行快照，只能退回自增值
-            for (const [name, table] of Object.entries(this._tables)) {
-                const v = this._transaction.autoIncrements[name];
-                if (v !== undefined) table._autoIncrement = v;
-            }
         }
 
         this._walWrite({ op: 'rollback', at: this._transaction.startedAt });
@@ -1668,12 +1658,19 @@ class Database {
             const pluginName = manifest.name || entry.name;
             // 查找入口文件：manifest.main || manifest.entry || 'index.js'
             const entryFile = manifest.main || manifest.entry || 'index.js';
-            // 兼容两种路径：根级 + plugins/ 子目录
+            // 兼容三种布局：
+            //   1. entry 是仓库相对路径（如 "plugins/xql/index.js"）且文件在根级 → basename
+            //   2. entry 是根级相对路径（如 "index.js"）且文件在根级
+            //   3. plugins/ 子目录（旧布局）
             const candidates = [
                 path.join(dir, entryFile),
                 path.join(dir, entryFile + '.js'),
+                path.join(dir, path.basename(entryFile)),
+                path.join(dir, path.basename(entryFile) + '.js'),
                 path.join(dir, 'plugins', entryFile),
                 path.join(dir, 'plugins', entryFile + '.js'),
+                path.join(dir, 'plugins', path.basename(entryFile)),
+                path.join(dir, 'plugins', path.basename(entryFile) + '.js'),
             ];
             let entryPath = null;
             for (const c of candidates) {
@@ -1850,8 +1847,8 @@ class Database {
         let rows = table._applyFilterOptimized(table._getVisibleRows(), filter || {});
         if (limit > 0) rows = rows.slice(offset, offset + limit);
         else if (offset > 0) rows = rows.slice(offset);
-        // P1-11: 返回浅拷贝，防止调用方修改影响内部数据
-        rows = rows.map(r => ({ ...r }));
+        // P1-11: 返回深拷贝，防止调用方修改（含嵌套对象/数组）影响内部数据
+        rows = rows.map(r => Table.cloneRow(r));
         this._touchTable(tableName);
         await this._runHooks('afterFind', [tableName, { filter, opts }, rows]);
         return rows;
@@ -1883,8 +1880,8 @@ class Database {
         const row = this._resolveId(table, id);
         // P1-4: 软删除行对普通读取不可见
         if (row && row._deleted) return null;
-        // P1-11: 返回浅拷贝，防止调用方修改影响内部数据
-        const result = row ? { ...row } : null;
+        // P1-11: 返回深拷贝，防止调用方修改（含嵌套对象/数组）影响内部数据
+        const result = row ? Table.cloneRow(row) : null;
         this._touchTable(tableName);
         await this._runHooks('afterFind', [tableName, { id }, result]);
         return result;
@@ -1895,7 +1892,7 @@ class Database {
         if (!table) throw createError('ER_NO_SUCH_TABLE', tableName);
         if (!(await this._runHooks('beforeFind', [tableName, { ids }]))) return null;
         // P1-4: 过滤掉软删除行；P1-11: 返回浅拷贝
-        const rows = ids.map(id => this._resolveId(table, id)).filter(r => r !== null && !r._deleted).map(r => ({ ...r }));
+        const rows = ids.map(id => this._resolveId(table, id)).filter(r => r !== null && !r._deleted).map(r => Table.cloneRow(r));
         this._touchTable(tableName);
         await this._runHooks('afterFind', [tableName, { ids }, rows]);
         return rows;

package/lib/errors.js

@@ -81,11 +81,10 @@ function createError(codeKey, ...args) {
         return new JSQL_Error('UNKNOWN', `Unknown error: ${codeKey}`, { codeKey, args });
     }
 
-    let msg = template.msg;
-    for (let i = 0; i < args.length; i++) {
-        // 使用函数替换避免 $& 等特殊字符被解释
-        msg = msg.replace('%s', () => String(args[i]));
-    }
+    // 单趟替换所有 %s：既避免参数值里本身含有 %s 时被后续替换再次消费造成串位，
+    // 也避免实参不足时消息里残留裸 %s。
+    let idx = 0;
+    const msg = template.msg.replace(/%s/g, () => (idx < args.length ? String(args[idx++]) : ''));
 
     return new JSQL_Error(template.code, msg, { args });
 }

package/lib/migrate.js

@@ -30,8 +30,12 @@ function normalizeSchema(schema) {
     if (d.type === 'varchar' || d.type === 'text' || d.type === 'char') d.type = 'string';
     if (d.type === 'double' || d.type === 'real' || d.type === 'decimal' || d.type === 'numeric') d.type = 'float';
     if (d.type === 'bool') d.type = 'boolean';
-    delete d.length;
-    if (d.maxLength) { d.length = d.maxLength; delete d.maxLength; }
+    // 保留用户显式配置的 length；maxLength 只是别名，仅在 length 未给出时回填。
+    // 此前无条件 delete d.length 再仅从 maxLength 恢复，导致显式 length 丢失。
+    if (d.maxLength !== undefined) {
+      if (d.length === undefined) d.length = d.maxLength;
+      delete d.maxLength;
+    }
     out[name] = d;
   }
   return out;

package/lib/mongo_server.js

@@ -461,7 +461,7 @@ class MongoServer {
           await engine.insert(coll, merged);
           value = doc.new ? { ...merged } : null;
         }
-        return { ok: 1, value, lastErrorObject: { n: found ? 1 : (doc.upsert ? 1 : 0), updatedExisting: !!found && !doc.remove } };
+        return { ok: 1, value: value ? this._publicDoc(value) : value, lastErrorObject: { n: found ? 1 : (doc.upsert ? 1 : 0), updatedExisting: !!found && !doc.remove } };
       }
       case 'distinct': {
         const coll = String(doc.distinct);
@@ -496,7 +496,7 @@ class MongoServer {
         if (skip > 0) rows = rows.slice(skip);
         const limit = typeof doc.limit === 'number' ? doc.limit : 0;
         if (limit > 0) rows = rows.slice(0, limit);
-        return { ok: 1, cursor: { id: { $long: 0 }, ns: `${this._dbOf(doc)}.${coll}`, firstBatch: rows } };
+        return { ok: 1, cursor: { id: { $long: 0 }, ns: `${this._dbOf(doc)}.${coll}`, firstBatch: rows.map(r => this._publicDoc(r)) } };
       }
       case 'getMore':
         return { ok: 1, cursor: { id: { $long: 0 }, ns: String(doc.collection || ''), nextBatch: [] } };
@@ -673,7 +673,7 @@ class MongoServer {
             rows = out;
           }
         }
-        return { ok: 1, cursor: { id: { $long: 0 }, ns: `${this._dbOf(doc)}.${coll}`, firstBatch: rows } };
+        return { ok: 1, cursor: { id: { $long: 0 }, ns: `${this._dbOf(doc)}.${coll}`, firstBatch: rows.map(r => this._publicDoc(r)) } };
       }
       default:
         return { ok: 1, n: 0 };
@@ -684,6 +684,23 @@ class MongoServer {
     return row._id != null ? row._id : row.id;
   }
 
+  /**
+   * 剥离 JSQL 内部字段后再返回给 Mongo 客户端。
+   *
+   * _deleted（软删除标记）、_rid（内部行号）、_score（全文检索得分）
+   * 都只属于引擎内部实现，泄漏到文档里会污染用户数据、影响后续 $set/$unset
+   * 以及客户端 schema 推断。
+   */
+  _publicDoc(row) {
+    if (!row || typeof row !== 'object') return row;
+    if (row._deleted === undefined && row._rid === undefined && row._score === undefined) return row;
+    const out = { ...row };
+    delete out._deleted;
+    delete out._rid;
+    delete out._score;
+    return out;
+  }
+
   async _matching(engine, coll, filter) {
     const rows = await engine.find(coll, {});
     return rows.filter((r) => this._match(r, filter || {}));

package/lib/mysql_server.js

@@ -578,8 +578,9 @@ class MysqlConnection {
         case 0x19: this._handleStmtClose(body); break; // COM_STMT_CLOSE
         case 0x1a: this._send(okPacket()); break; // COM_STMT_RESET
         case 0x0a: { // COM_PROCESS_INFO
-          const seq = this.sequence;
-          this.sequence = (this.sequence + 1) & 0xff;
+          // _handlePacket 已把 this.sequence 设为 cmdSeq+1，_send 会在写入后自增。
+          // 此前这里额外自增一次，导致首个响应包序列号比请求大 2（跳号），
+          // 严格校验序列号的客户端会判定协议错误并断开。
           this._send(encodeLenenc(1));
           this._send(columnDefinition({ name: 'Id', type: MYSQL_TYPE_LONG }));
           this._send(eofPacket());

package/lib/nedb_compat.js

@@ -77,8 +77,21 @@ function matchOperator(value, op, expected) {
     case '$in': return Array.isArray(expected) && expected.some(e => looseEqual(value, e));
     case '$nin': return Array.isArray(expected) && !expected.some(e => looseEqual(value, e));
     case '$exists': return expected ? value !== undefined : value === undefined;
-    case '$regex':
-      return typeof value === 'string' && new RegExp(expected.source, expected.flags || 'i').test(value);
+    case '$regex': {
+      if (typeof value !== 'string') return false;
+      // expected 允许两种写法：/re/flags（RegExp），或 MySQL 风格的字符串模式。
+      // 此前直接读 expected.source：字符串没有 source → new RegExp(undefined)
+      // 等价于 /(?:)/，静默匹配所有文档。
+      let re;
+      if (expected instanceof RegExp) {
+        re = expected;
+      } else if (typeof expected === 'string') {
+        try { re = new RegExp(expected); } catch { return false; }
+      } else {
+        return false;
+      }
+      return re.test(value);
+    }
     case '$size': return Array.isArray(value) && value.length === expected;
     default: return false;
   }

package/lib/pg_server.js

@@ -792,7 +792,10 @@ class PgServer {
       if (user !== this.options.user) return undefined;
       return this.options.password || '';
     }
-    return '';
+    // 未配置任何认证信息：默认拒绝连接（返回 undefined → 认证失败）。
+    // 此前返回 '' 会被 _startAuth 当成 trust，导致任意用户名 + 空密码即可连入，
+    // 与 MysqlServer 的默认拒绝策略保持一致。仅显式 noAuth: true 才放行。
+    return undefined;
   }
 
   _canAccessDb(user, dbName) {

package/lib/plugin.js

@@ -104,10 +104,16 @@ function definePlugin(name, def = {}) {
 }
 
 /** 登记单个钩子；未知钩子名会自动创建，便于插件自定义扩展点 */
-function registerHook(engine, hook, fn) {
+function registerHook(engine, hook, fn, priority = 0) {
   if (typeof fn !== 'function') return engine;
   if (!engine._hooks) engine._hooks = createHookRegistry();
   if (!engine._hooks[hook]) engine._hooks[hook] = [];
+  // 记录优先级：即使插件是后加载的，也应按 priority 决定执行顺序，
+  // 而不是简单追加在已有钩子之后（此前 sort(_plugins) 只排插件列表，
+  // 钩子链仍按注册顺序执行，导致 priority 实际无效）。
+  try {
+    Object.defineProperty(fn, '__jsqlHookPriority', { value: priority, configurable: true, writable: true });
+  } catch (e) { /* 冻结函数等无法打标，按 0 处理 */ }
   engine._hooks[hook].push(fn);
   return engine;
 }
@@ -115,9 +121,10 @@ function registerHook(engine, hook, fn) {
 /** 把一个插件声明的所有钩子登记到引擎上 */
 function registerHooks(engine, plugin) {
   if (!plugin || !plugin.hooks) return engine;
+  const priority = plugin.priority || 0;
   for (const [hook, val] of Object.entries(plugin.hooks)) {
     const fns = Array.isArray(val) ? val : [val];
-    for (const fn of fns) registerHook(engine, hook, fn);
+    for (const fn of fns) registerHook(engine, hook, fn, priority);
   }
   return engine;
 }
@@ -253,7 +260,11 @@ function runHooks(engine, hookName, args) {
 
   return (async () => {
     try {
-      for (const fn of hooks) {
+      // priority 大的先执行；同 priority 保持注册顺序（sort 在现代引擎是稳定的）
+      const ordered = hooks.length > 1
+        ? hooks.slice().sort((a, b) => (b.__jsqlHookPriority || 0) - (a.__jsqlHookPriority || 0))
+        : hooks;
+      for (const fn of ordered) {
         const result = await fn(...args);
         if (result === false) return false;
       }

package/lib/sql.js

@@ -2811,8 +2811,15 @@ class Parser {
     // MySQL 中 RLIKE 是 REGEXP 的同义词
     if (t2.type === 'keyword' && (t2.value === 'REGEXP' || t2.value === 'RLIKE')) {
       this.next();
-      const pattern = this.parseValue();
-      return { type: 'regexp', operand: left, pattern, not };
+      let pattern = this.parseValue();
+      // `expr REGEXP BINARY 'pat'`：BINARY 前缀表示大小写敏感匹配。
+      // 解析出的 pattern 会包一层 { type:'binary', operand }，这里解包并标记 ci=false。
+      let binary = false;
+      if (pattern && typeof pattern === 'object' && pattern.type === 'binary') {
+        binary = true;
+        pattern = pattern.operand;
+      }
+      return { type: 'regexp', operand: left, pattern, not, ci: !binary };
     }
 
     // PG JSON 包含操作符
@@ -4476,7 +4483,14 @@ function evaluateExpr(expr, row, ctx) {
   switch (expr.type) {
     case 'and': return evaluateExpr(expr.left, row, ctx) && evaluateExpr(expr.right, row, ctx);
     case 'or': return evaluateExpr(expr.left, row, ctx) || evaluateExpr(expr.right, row, ctx);
-    case 'xor': return Boolean(evaluateExpr(expr.left, row, ctx)) !== Boolean(evaluateExpr(expr.right, row, ctx));
+    case 'xor': {
+      // 三值逻辑：任一操作数为 UNKNOWN 时结果也是 UNKNOWN。
+      // 旧实现用 Boolean() 归一，Boolean(null)=false 会把 NULL XOR TRUE 误判为 TRUE。
+      const l = evaluateExpr(expr.left, row, ctx);
+      const r = evaluateExpr(expr.right, row, ctx);
+      return sqlXor(l === null || l === undefined ? null : Boolean(l),
+        r === null || r === undefined ? null : Boolean(r));
+    }
     case 'not': {
       // 三值逻辑：NOT UNKNOWN = UNKNOWN（返回 null，在 WHERE/ON/HAVING 中视为不选中）
       // 必须用 resolveOperand 取值：evaluateExpr 只认布尔类节点，
@@ -4569,8 +4583,18 @@ function evaluateExpr(expr, row, ctx) {
     case 'regexp': {
       const v = resolveOperand(expr.operand, row, ctx);
       if (v === null || v === undefined) return false;
-      // REGEXP / RLIKE 历史上就是大小写不敏感的；`~` 敏感、`~*` 不敏感
-      const re = new RegExp(String(expr.pattern), expr.ci === false ? '' : 'i');
+      // pattern 可能是字面量、列引用或表达式：统一用 resolveOperand 取值。
+      // 过去 String(expr.pattern) 对 { type:'binary'|'column' } 对象只会得到
+      // "[object Object]"，BINARY 前缀的大小写敏感语义也因此完全失效。
+      // pattern 可能是字面量、列引用或表达式：字面量（primitive）直接使用，
+      // 只有 AST 节点才走 resolveOperand —— 否则字符串会被当成列名。
+      const pat = (expr.pattern && typeof expr.pattern === 'object')
+        ? resolveOperand(expr.pattern, row, ctx)
+        : expr.pattern;
+      if (pat === null || pat === undefined) return false;
+      let re;
+      try { re = new RegExp(String(pat), expr.ci === false ? '' : 'i'); } catch { return false; }
+      // REGEXP / RLIKE 默认大小写不敏感；`~` 敏感、`~*` 不敏感；REGEXP BINARY 敏感
       const r = re.test(String(v));
       return expr.not ? !r : r;
     }
@@ -4590,8 +4614,11 @@ function evaluateExpr(expr, row, ctx) {
       // 三值逻辑：任一操作数为 NULL 时结果是 UNKNOWN（用 null 表示），
       // 与普通比较运算符一致；不能返回 false，否则 NOT BETWEEN 会被误判为真。
       if (v === null || v === undefined || lo === null || lo === undefined || hi === null || hi === undefined) return null;
-      const inRange = typeof v === 'number' && typeof lo === 'number' && typeof hi === 'number'
-        ? v >= lo && v <= hi
+      // 数值（含数字字符串）必须按数值比较，否则 '10' BETWEEN 2 AND 9 会退化成
+      // 字典序 ('10' >= '2' 为 false)，与 MySQL 不一致。
+      const nv = numericIfNumeric(v), nlo = numericIfNumeric(lo), nhi = numericIfNumeric(hi);
+      const inRange = nv !== null && nlo !== null && nhi !== null
+        ? nv >= nlo && nv <= nhi
         : String(v) >= String(lo) && String(v) <= String(hi);
       return expr.not ? !inRange : inRange;
     }
@@ -5447,11 +5474,21 @@ class SQLExecutor {
         }
         if (typeof statement.limit === 'number') candidates = candidates.slice(0, statement.limit);
         let count = 0;
+        // UPDATE 的赋值表达式同样可能含标量子查询，SELECT 路径在 _materialize
+        // 里统一物化，但 UPDATE 从未调用它 —— 子查询节点 _value 一直是 undefined，
+        // resolveOperand 直接返回 NULL，`SET x = (SELECT ...)` 静默写成 NULL。
+        for (const [, val] of statement.assignments) {
+          if (val && typeof val === 'object') await this._materialize(val);
+        }
         for (const row of candidates) {
           const id = this._rowPkId(row, pkCols);
           if (id !== undefined) {
             const data = {};
             for (const [col, val] of statement.assignments) {
+              if (val && typeof val === 'object' && val.type) {
+                // 相关子查询：按当前行重算（非相关时重算是幂等的，结果一致）
+                for (const sub of this._collectSubqueries(val)) await this._evalCorrelated(sub, row);
+              }
               data[col] = typeof val === 'object' && val !== null && val.type ? resolveOperand(val, row, this.ctx) : val;
             }
             // 必须 await：wasm / native client 的 updateById 是异步的，

package/lib/star-nag.js

@@ -156,22 +156,33 @@ function checkStarred() {
   // 用同步 API：CLI 启动阶段还没有 event loop 可用
   try {
     const { execFileSync } = require('child_process');
-    const out = execFileSync('curl', [
+    // 用 -w 追加 HTTP 状态码，按状态码判定，而不是靠 body 长度猜。
+    // 该端点语义：已 star → 204（空 body）；未 star → 404。
+    // 此前把「空 body」一律当已 star：遇到 302/500 等空 body 响应或代理异常时
+    // 会误判为 star 过，从此永久闭嘴。
+    const raw = execFileSync('curl', [
       '-sS', '-m', '4',
+      '-w', '\n%{http_code}',
       '-H', `Authorization: Bearer ${token}`,
       '-H', 'Accept: application/vnd.github+json',
       '-H', 'X-GitHub-Api-Version: 2022-11-28',
       `https://api.github.com/user/starred/${REPO}`,
     ], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).toString();
-    if (out.trim() === '') return true;     // 200 + 空数组 = 列了但没有这个仓库
-    const j = JSON.parse(out);
-    // GitHub 出错时返回的是 {"message":"Bad credentials"} 之类，不是数组。
-    // 那说明 token 无效/过期 —— 属于「无法确认」，不能当成「没 star」，
-    // 否则会永远提示下去。
-    if (j && !Array.isArray(j) && typeof j.message === 'string') return null;
-    return Array.isArray(j) && j.length > 0;
+    const nl = raw.lastIndexOf('\n');
+    const status = Number(raw.slice(nl + 1).trim());
+    const body = raw.slice(0, nl).trim();
+    if (status === 204) return true;
+    if (status === 404) return false;
+    if (status === 200 && body) {
+      // 兼容返回数组的旧行为：数组里有该仓库才算 star
+      try {
+        const j = JSON.parse(body);
+        if (Array.isArray(j)) return j.length > 0;
+      } catch (e) { /* 非 JSON，无法确认 */ }
+    }
+    return null;                  // 401/403/3xx/5xx → 无法确认
   } catch (e) {
-    return null;                  // 网络不通 / 401 / 没装 curl → 不确定
+    return null;                  // 网络不通 / 没装 curl → 不确定
   }
 }
 

package/lib/table.js

@@ -118,6 +118,24 @@ function isSafeRegex(pattern) {
     return groups.length === 0;
 }
 
+/**
+ * 深拷贝一行数据（普通对象/数组/Date），用于隔离内部存储与调用方。
+ *
+ * 过去 insert/find 只做 `{ ...row }` 浅拷贝：行里的嵌套对象/数组与内部存储
+ * 共享引用，调用方修改返回值（或插入后继续改传入对象）会静默污染数据库内容。
+ * 非普通对象（Map/Set/类实例等）保持原引用，避免破坏无法安全克隆的类型。
+ */
+function cloneRow(value) {
+    if (value === null || typeof value !== 'object') return value;
+    if (value instanceof Date) return new Date(value.getTime());
+    if (Array.isArray(value)) return value.map(cloneRow);
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) return value;
+    const out = {};
+    for (const k of Object.keys(value)) out[k] = cloneRow(value[k]);
+    return out;
+}
+
 class Table {
     constructor(name, schema, db) {
         this._name = name;
@@ -245,7 +263,7 @@ class Table {
         }
 
         const rowIndex = this._rows.length;
-        this._rows.push({ ...data });
+        this._rows.push(cloneRow(data));
         this._addToIndexes(rowIndex, data);
         this._dirty = true;
         this._db._markDirty(this._name);
@@ -299,7 +317,7 @@ class Table {
         const result = new Array(N);
         for (let i = 0; i < N; i++) {
             // 在副本上做默认值/计算列/类型归一，避免污染调用方传入的原始对象
-            let data = { ...items[i] };
+            let data = cloneRow(items[i]);
             for (const [f, dv] of Object.entries(defaults)) {
                 if (data[f] === undefined) data[f] = typeof dv === 'function' ? dv() : dv === 'CURRENT_TIMESTAMP' ? now() : dv;
             }
@@ -308,7 +326,8 @@ class Table {
             data = this._validateDataTypes(data);
             for (const field of this._cachedSchemaFields) {
                 const def = schema[field];
-                if (def.required && (data[field] === undefined || data[field] === null)
+                const isPk = def.primaryKey || def.primary === true;
+                if ((def.required || isPk) && (data[field] === undefined || data[field] === null)
                     && !(def.autoIncrement && data[field] === undefined)) throw createError('ER_BAD_NULL_ERROR', field);
                 if (def.unique && data[field] !== undefined) {
                     if (uniqueTracker[field].has(data[field])) throw createError('ER_DUP_ENTRY', String(data[field]), field);
@@ -346,7 +365,7 @@ class Table {
                 this._autoIncrement = data[autoIncField];
             }
             const rowIdx = this._rows.length;
-            this._rows.push(Object.assign({}, data));
+            this._rows.push(cloneRow(data));
             if (this._pkIndex && this._primaryKey) {
                 const pkVal = data[this._primaryKey];
                 if (pkVal !== undefined && pkVal !== null) {
@@ -391,7 +410,7 @@ class Table {
         if (Object.keys(query).length > 0) {
             rows = this._applyFilterOptimized(rows, query);
         }
-        return rows.map(r => ({ ...r }));
+        return rows.map(r => cloneRow(r));
     }
 
     findOne(query = {}) {
@@ -399,7 +418,7 @@ class Table {
         if (Object.keys(query).length > 0) {
             rows = this._applyFilterOptimized(rows, query);
         }
-        return rows.length > 0 ? { ...rows[0] } : null;
+        return rows.length > 0 ? cloneRow(rows[0]) : null;
     }
 
     exists(query = {}) {
@@ -415,7 +434,7 @@ class Table {
             const rowIndex = this._pkIndex.get(id);
             if (rowIndex !== undefined) {
                 const row = this._rows[rowIndex];
-                if (row && !row._deleted) return { ...row };
+                if (row && !row._deleted) return cloneRow(row);
             }
             return null;
         }
@@ -423,7 +442,7 @@ class Table {
             const indices = this._btrees[this._primaryKey].search(id);
             if (indices.length > 0) {
                 const row = this._rows[indices[0]];
-                if (row && !row._deleted) return { ...row };
+                if (row && !row._deleted) return cloneRow(row);
             }
             return null;
         }
@@ -431,7 +450,7 @@ class Table {
     }
 
     findAll() {
-        return this._getVisibleRows().map(r => ({ ...r }));
+        return this._getVisibleRows().map(r => cloneRow(r));
     }
 
     count(query = {}) {
@@ -995,18 +1014,22 @@ class Table {
         for (const [field, condition] of Object.entries(query)) {
             if (field === '$or' || field === '$and' || field === '$not') continue;
             if (typeof condition !== 'object' || condition === null || Array.isArray(condition) || condition instanceof RegExp) {
-                if (this._btrees[field]) {
+                // 索引只收非 NULL 值：condition 为 null/undefined 时必须全表扫描，
+                // 否则 search(null) 命中空数组直接返回 0 行（索引列 IS NULL 漏行）。
+                const nullish = condition === null || condition === undefined;
+                if (!nullish && this._btrees[field]) {
                     const indices = this._btrees[field].search(condition);
                     if (indices.length === 0) return [];
                     return this._applyFilter(this._rowsFromIndices(indices), query);
                 }
-                if (this._indexes[field] && this._indexes[field].has(condition)) {
+                if (!nullish && this._indexes[field] && this._indexes[field].has(condition)) {
                     return this._applyFilter(this._rowsFromIndices(this._indexes[field].get(condition)), query);
                 }
-                if (this._indexes[field]) return [];
+                if (!nullish && this._indexes[field]) return [];
             }
             if (condition && typeof condition === 'object') {
-                if (this._btrees[field] && Array.isArray(condition.$in) && condition.$in.length > 0) {
+                if (this._btrees[field] && Array.isArray(condition.$in) && condition.$in.length > 0
+                    && !condition.$in.some(v => v === null || v === undefined)) {
                     const indices = this._btrees[field].searchMany(condition.$in);
                     if (indices.length === 0) return [];
                     return this._applyFilter(this._rowsFromIndices(indices), query);
@@ -1355,8 +1378,9 @@ class Table {
         for (const [field, def] of Object.entries(this._schema)) {
             if (field === '_softDelete') continue;
 
-            // NOT NULL
-            if (def.required && (data[field] === undefined || data[field] === null)
+            // NOT NULL（主键隐式 NOT NULL，否则唯一约束检查会因 NULL 短路而被绕过）
+            const isPk = def.primaryKey || def.primary === true;
+            if ((def.required || isPk) && (data[field] === undefined || data[field] === null)
                 && !(def.autoIncrement && data[field] === undefined)) {
                 throw createError('ER_BAD_NULL_ERROR', field);
             }
@@ -1664,4 +1688,5 @@ class Table {
     }
 }
 
-module.exports = Table;
+module.exports = Table;
+Table.cloneRow = cloneRow;

package/lib/web_ui.js

@@ -69,19 +69,22 @@ tr:nth-child(even) td { background: #0d1117; }
 <script>
 let dbs = [], cur = null;
 const q = async (u, o) => { const r = await fetch(u, o); return r.json(); };
-function esc(s) { return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
+function esc(s) { return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;'); }
 async function load() {
   dbs = await q('/api/databases');
   const el = document.getElementById('dbs');
-  el.innerHTML = dbs.map(d => '<div class="db" onclick="openDb(' + esc(d.name) + ')">' + esc(d.name) + ' <span class="rows">(' + d.tables + ' tbl)</span></div>').join('');
+  el.innerHTML = dbs.map(d => '<div class="db" data-name="' + esc(d.name) + '">' + esc(d.name) + ' <span class="rows">(' + d.tables + ' tbl)</span></div>').join('');
+  el.querySelectorAll('.db').forEach(e => e.addEventListener('click', () => openDb(e.dataset.name)));
   if (!cur && dbs.length) openDb(dbs[0].name);
 }
 async function openDb(n) {
   cur = n;
-  document.querySelectorAll('.db').forEach(e => e.classList.toggle('active', e.textContent.indexOf(n) === 0));
+  document.querySelectorAll('.db').forEach(e => e.classList.toggle('active', e.dataset.name === n));
   const r = await q('/api/tables?db=' + encodeURIComponent(n));
-  document.getElementById('tbls').innerHTML = r.tables.map(t =>
-    '<div class="tbl" onclick="sel(' + esc(t.name) + ')">' + esc(t.name) + ' (' + t.count + ')</div>').join('');
+  const tl = document.getElementById('tbls');
+  tl.innerHTML = r.tables.map(t =>
+    '<div class="tbl" data-name="' + esc(t.name) + '">' + esc(t.name) + ' (' + t.count + ')</div>').join('');
+  tl.querySelectorAll('.tbl').forEach(e => e.addEventListener('click', () => sel(e.dataset.name)));
 }
 function sel(n) { document.getElementById('sql').value = 'SELECT * FROM ' + n + ' LIMIT 100'; run(); }
 async function run() {

package/lib/xql/src/compiler.js

@@ -136,7 +136,7 @@ class Emitter {
         const lo = this.emit(node.lo);
         const hi = this.emit(node.hi);
         const t = this.tmp();
-        this.push(`let ${t} = (${v} == null ? null : (${v} >= ${lo} && ${v} <= ${hi}));`);
+        this.push(`let ${t} = (${v} == null || ${lo} == null || ${hi} == null ? null : (${v} >= ${lo} && ${v} <= ${hi}));`);
         return t;
       }
       case 'like': {
@@ -183,8 +183,8 @@ class Emitter {
       case '*': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} * ${r});`); break;
       case '/': this.push(`let ${t} = (${l} == null || ${r} == null || Number(${r}) === 0 ? null : ${l} / ${r});`); break;
       case '%': this.push(`let ${t} = (${l} == null || ${r} == null || Number(${r}) === 0 ? null : ${l} % ${r});`); break;
-      case '=': this.push(`let ${t} = (${l} == null ? null : ${l} === ${r});`); break;
-      case '!=': this.push(`let ${t} = (${l} == null ? null : ${l} !== ${r});`); break;
+      case '=': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} === ${r});`); break;
+      case '!=': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} !== ${r});`); break;
       case '<': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} < ${r});`); break;
       case '>': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} > ${r});`); break;
       case '<=': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} <= ${r});`); break;
@@ -197,15 +197,25 @@ class Emitter {
   emitIn(node) {
     const v = this.emit(node.e);
     const t = this.tmp();
-    const not = node.neg ? '!' : '';
-    const join = node.neg ? ' && ' : ' || ';
     if (node.list.every(n => n.k === 'lit')) {
       const name = '_set' + this.sets.length;
       this.sets.push({ name, set: new Set(node.list.map(n => n.v)) });
-      this.push(`let ${t} = (${v} == null ? null : ${not}${name}.has(${v}));`);
+      // 完整三值逻辑：被查找值为 NULL → UNKNOWN；列表含 NULL 且未匹配 → UNKNOWN。
+      const hasNull = node.list.some(n => n.v === null);
+      if (node.neg) {
+        this.push(`let ${t} = (${v} == null ? null : (${name}.has(${v}) ? false : (${hasNull} ? null : true)));`);
+      } else {
+        this.push(`let ${t} = (${v} == null ? null : (${name}.has(${v}) ? true : (${hasNull} ? null : false)));`);
+      }
     } else {
-      const parts = node.list.map(n => `(${v} != null && ${v} === ${this.emit(n)})`);
-      this.push(`let ${t} = (${v} == null ? null : ${not}(${parts.join(join)}));`);
+      const elems = node.list.map(n => this.emit(n));
+      const anyMatch = elems.map(e => `(${v} === ${e})`).join(' || ');
+      const anyNull = elems.map(e => `${e} == null`).join(' || ');
+      if (node.neg) {
+        this.push(`let ${t} = (${v} == null ? null : (${anyMatch} ? false : (${anyNull} ? null : true)));`);
+      } else {
+        this.push(`let ${t} = (${v} == null ? null : (${anyMatch} ? true : (${anyNull} ? null : false)));`);
+      }
     }
     return t;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "6.5.12",
+  "version": "6.5.14",
   "description": "JSQL-NEO \u2014 Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",
@@ -35,6 +35,7 @@
     "index.d.ts",
     "lib/",
     "bin/",
+    "src/",
     "wasm/",
     "native/",
     "nativesrc/",

package/src/cli/index.js

@@ -0,0 +1,12 @@
+/**
+ * JSQL CLI — 模块化入口
+ *
+ * 将各子命令拆分为独立模块，bin/jsql 通过此文件加载。
+ * 当前包含: plugin 命令
+ */
+
+const plugin = require('./plugin');
+
+module.exports = {
+  plugin,
+};

package/src/cli/plugin.js

@@ -0,0 +1,346 @@
+/**
+ * JSQL Plugin Registry CLI
+ *
+ * 协议文档: /root/.openclaw/workspace/registry-protocol.md
+ * Registry API: https://registry-beta.vexify.top/?action=xxx
+ *
+ * 注意: 当前 registry-beta 实例仅实现了 plugins / search / registry 三个 action，
+ * 尚未实现 info 和 download。本模块优先使用实际 API，缺失能力时给出友好提示。
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const REGISTRY_BASE = 'https://registry-beta.vexify.top';
+const PLUGIN_DIR = path.join(os.homedir(), '.jsql', 'plugins');
+const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024;
+const MAX_ARCHIVE_ENTRIES = 10000;
+
+// ─── 工具函数 ──────────────────────────────────────────────
+
+/** 插件名只允许字母/数字/点/下划线/连字符，杜绝路径注入 */
+function assertValidPluginName(name) {
+  if (typeof name !== 'string' || !name) {
+    throw new Error('Plugin name must be a non-empty string');
+  }
+  if (name.length > 128) {
+    throw new Error(`Invalid plugin name: too long (${name.length} > 128)`);
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.includes('..')) {
+    throw new Error(`Invalid plugin name: '${name}'`);
+  }
+  return name;
+}
+
+/** 校验 tar 清单：拒绝绝对路径、`..`、设备/符号链接/硬链接 */
+function assertSafeTarEntries(archivePath, destDir) {
+  const names = execFileSync('tar', ['-tzf', archivePath], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 16 * 1024 * 1024,
+  }).split(/\r?\n/).filter(Boolean);
+  if (names.length > MAX_ARCHIVE_ENTRIES) {
+    throw new Error(`Archive contains too many entries (${names.length} > ${MAX_ARCHIVE_ENTRIES})`);
+  }
+  const destResolved = path.resolve(destDir);
+  for (const entry of names) {
+    if (entry.startsWith('/') || entry.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(entry)) {
+      throw new Error(`Archive contains absolute path: ${entry}`);
+    }
+    if (entry.split(/[\\/]+/).includes('..')) {
+      throw new Error(`Archive contains path traversal: ${entry}`);
+    }
+    const target = path.resolve(destResolved, entry);
+    if (target !== destResolved && !target.startsWith(destResolved + path.sep)) {
+      throw new Error(`Archive entry escapes plugin directory: ${entry}`);
+    }
+  }
+  // 类型检查单独用 -tvzf，避免解析带空格的路径
+  const verbose = execFileSync('tar', ['-tvzf', archivePath], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  for (const line of verbose.split(/\r?\n/)) {
+    if (!line) continue;
+    const type = line.charAt(0);
+    if (type === 'l' || type === 'h') {
+      throw new Error('Archive contains links, which are not allowed');
+    }
+    if (type !== '-' && type !== 'd') {
+      throw new Error(`Archive contains unsupported entry type '${type}'`);
+    }
+  }
+}
+
+/** 确保插件目录存在 */
+function ensurePluginDir() {
+  if (!fs.existsSync(PLUGIN_DIR)) {
+    fs.mkdirSync(PLUGIN_DIR, { recursive: true });
+  }
+}
+
+/** 从可能含有 PHP Warning 前缀的响应文本中提取 JSON */
+function extractJson(text) {
+  // 找到第一个 '{' 的位置，从那里开始解析
+  const idx = text.indexOf('{');
+  if (idx === -1) return null;
+  try {
+    return JSON.parse(text.slice(idx));
+  } catch {
+    return null;
+  }
+}
+
+/** 发起 registry API 请求，返回解析后的 JSON */
+async function apiRequest(action, params = {}) {
+  const url = new URL(REGISTRY_BASE);
+  url.searchParams.set('action', action);
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null) url.searchParams.set(k, v);
+  }
+
+  const res = await fetch(url.toString());
+  const text = await res.text();
+  const body = extractJson(text);
+
+  if (!res.ok || !body || body.status !== 'success') {
+    const msg = body?.error || `HTTP ${res.status}`;
+    throw new Error(`Registry error: ${msg}`);
+  }
+  return body.data;
+}
+
+// ─── 核心操作 ──────────────────────────────────────────────
+
+/** 列出所有插件（支持 category / tag / author / q / sort / order / page / limit） */
+async function listPlugins(opts = {}) {
+  const params = {};
+  if (opts.category) params.category = opts.category;
+  if (opts.tag) params.tag = opts.tag;
+  if (opts.author) params.author = opts.author;
+  if (opts.q) params.q = opts.q;
+  if (opts.sort) params.sort = opts.sort;
+  if (opts.order) params.order = opts.order;
+  if (opts.page) params.page = opts.page;
+  if (opts.limit) params.limit = opts.limit;
+  return apiRequest('plugins', params);
+}
+
+/** 搜索插件（q 参数必填） */
+async function searchPlugins(query, opts = {}) {
+  if (!query) throw new Error('Search query is required');
+  const params = { q: query };
+  if (opts.category) params.category = opts.category;
+  if (opts.tag) params.tag = opts.tag;
+  if (opts.sort) params.sort = opts.sort;
+  return apiRequest('search', params);
+}
+
+/** 获取单个插件信息（实际 API 未实现 info action，通过 plugins 列表过滤） */
+async function getPluginInfo(name) {
+  const plugins = await listPlugins({ q: name, limit: 100 });
+  const plugin = plugins.find(p => p.name === name);
+  if (!plugin) throw new Error(`Plugin '${name}' not found in registry`);
+  return plugin;
+}
+
+/**
+ * 带重试的 fetch（P1 修复：install 网络间歇性失败 30-40%）
+ * 3 次重试 + 指数退避（500ms, 1s, 2s）
+ */
+async function fetchWithRetry(url, retries = 3, baseDelay = 500) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const res = await fetch(url.toString());
+      if (res.ok) return res;
+      // 5xx / 429 可重试
+      if ((res.status >= 500 || res.status === 429) && i < retries - 1) {
+        const delay = baseDelay * Math.pow(2, i);
+        await new Promise(r => setTimeout(r, delay));
+        continue;
+      }
+      return res;
+    } catch (e) {
+      if (i < retries - 1) {
+        const delay = baseDelay * Math.pow(2, i);
+        await new Promise(r => setTimeout(r, delay));
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+
+/** 安装插件：下载 tgz 并解压到 ~/.jsql/plugins/<name>/ */
+async function installPlugin(name) {
+  assertValidPluginName(name);
+  ensurePluginDir();
+
+  // 检查是否已安装
+  const pluginDir = path.join(PLUGIN_DIR, name);
+  const manifestPath = path.join(pluginDir, 'manifest.json');
+  if (fs.existsSync(manifestPath)) {
+    const existing = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    throw new Error(`Plugin '${name}' is already installed (v${existing.version})`);
+  }
+
+  // 下载插件包（带重试）
+  const url = new URL(REGISTRY_BASE);
+  url.searchParams.set('action', 'download');
+  url.searchParams.set('name', name);
+
+  const res = await fetchWithRetry(url);
+  const ct = res.headers.get('content-type') || '';
+  const buf = Buffer.from(await res.arrayBuffer());
+
+  if (buf.length > MAX_ARCHIVE_BYTES) {
+    throw new Error(`Plugin archive too large (${buf.length} > ${MAX_ARCHIVE_BYTES} bytes)`);
+  }
+
+  // 检查 Content-Type 或 magic bytes
+  if (!ct.includes('gzip') && buf[0] !== 0x1f) {
+    // 返回了错误 JSON，不是 tgz
+    const text = buf.toString('utf8');
+    const body = extractJson(text);
+    throw new Error(body?.error || `Download failed (HTTP ${res.status})`);
+  }
+
+  const archivePath = path.join(PLUGIN_DIR, `${name}.tgz`);
+  fs.writeFileSync(archivePath, buf, { mode: 0o600 });
+
+  // 解压 tgz：先校验清单，再用 execFile 避免 shell 注入
+  fs.mkdirSync(pluginDir, { recursive: true });
+  try {
+    assertSafeTarEntries(archivePath, pluginDir);
+    execFileSync('tar', ['-xzf', archivePath, '-C', pluginDir], {
+      stdio: 'pipe',
+    });
+  } catch (e) {
+    fs.rmSync(pluginDir, { recursive: true, force: true });
+    fs.rmSync(archivePath, { force: true });
+    throw new Error(`Failed to extract plugin archive: ${e.message}`);
+  }
+
+  // 读取 manifest（兼容两种路径：根级 + plugins/ 子目录）
+  let manifestFile = path.join(pluginDir, 'manifest.json');
+  if (!fs.existsSync(manifestFile)) {
+    manifestFile = path.join(pluginDir, 'plugins', 'manifest.json');
+  }
+  let manifest;
+  if (fs.existsSync(manifestFile)) {
+    manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+  } else {
+    // 创建默认 manifest
+    manifest = { name, version: '0.0.0', installedAt: new Date().toISOString() };
+    fs.writeFileSync(path.join(pluginDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+  }
+
+  // 清理压缩包
+  fs.rmSync(archivePath, { force: true });
+
+  return manifest;
+}
+
+/**
+ * 卸载插件
+ * P0 安全修复：校验 name 不含路径遍历序列，使用 basename 隔离，
+ * 防止 `jsql plugin uninstall '../../etc/something'` 删除任意目录。
+ */
+function uninstallPlugin(name) {
+  if (typeof name !== 'string' || !name) {
+    throw new Error('Plugin name must be a non-empty string');
+  }
+  // 拒绝包含路径遍历的名称
+  if (name.includes('..') || name.includes('/') || name.includes('\\')) {
+    throw new Error(`Invalid plugin name: '${name}'`);
+  }
+  // 使用 basename 进一步隔离
+  const safeName = path.basename(name);
+  if (safeName !== name) {
+    throw new Error(`Invalid plugin name: '${name}'`);
+  }
+  const pluginDir = path.join(PLUGIN_DIR, safeName);
+  // 二次校验：确保解析后的路径严格在 PLUGIN_DIR 之下
+  const resolved = path.resolve(pluginDir);
+  const pluginDirResolved = path.resolve(PLUGIN_DIR);
+  if (resolved !== pluginDirResolved && !resolved.startsWith(pluginDirResolved + path.sep)) {
+    throw new Error(`Plugin name resolves outside plugin directory: '${name}'`);
+  }
+  if (!fs.existsSync(pluginDir)) {
+    throw new Error(`Plugin '${safeName}' is not installed`);
+  }
+  fs.rmSync(pluginDir, { recursive: true, force: true });
+  return { name: safeName, uninstalled: true };
+}
+
+/** 列出已安装的插件（兼容根级 + plugins/ 子目录两种布局） */
+function listInstalled() {
+  ensurePluginDir();
+  const entries = fs.readdirSync(PLUGIN_DIR, { withFileTypes: true });
+  const plugins = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    // 兼容两种路径：根级 manifest.json + plugins/ 子目录 manifest.json
+    const manifestPaths = [
+      path.join(PLUGIN_DIR, entry.name, 'manifest.json'),
+      path.join(PLUGIN_DIR, entry.name, 'plugins', 'manifest.json'),
+    ];
+    for (const manifestPath of manifestPaths) {
+      if (fs.existsSync(manifestPath)) {
+        try {
+          plugins.push(JSON.parse(fs.readFileSync(manifestPath, 'utf8')));
+        } catch { /* 跳过损坏的 manifest */ }
+        break;
+      }
+    }
+  }
+  return plugins;
+}
+
+// ─── 格式化输出 ────────────────────────────────────────────
+
+/** 格式化插件列表为表格 */
+function formatPluginList(plugins) {
+  if (!plugins.length) return 'No plugins found.';
+  const rows = plugins.map(p =>
+    `${p.name.padEnd(24)} ${(p.version || '?').padEnd(10)} ${(p.description || '').slice(0, 50)}`
+  );
+  return rows.join('\n');
+}
+
+/** 格式化插件详情 */
+function formatPluginInfo(p) {
+  const lines = [
+    `Name:        ${p.name}`,
+    `Version:     ${p.version}`,
+    `Author:      ${p.author}`,
+    `License:     ${p.license}`,
+    `Category:    ${p.category}`,
+    `Description: ${p.description}`,
+    `Tags:        ${(p.tags || []).join(', ')}`,
+    `Downloads:   ${p.downloads || 0}`,
+  ];
+  if (p.jsql) {
+    lines.push(`JSQL:        ${p.jsql.minVersion}+${p.jsql.maxVersion ? ' – ' + p.jsql.maxVersion : ''}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  PLUGIN_DIR,
+  ensurePluginDir,
+  assertValidPluginName,
+  assertSafeTarEntries,
+  listPlugins,
+  searchPlugins,
+  getPluginInfo,
+  installPlugin,
+  uninstallPlugin,
+  listInstalled,
+  formatPluginList,
+  formatPluginInfo,
+  fetchWithRetry,
+};

package/test/plugin-xql.test.js

@@ -125,10 +125,33 @@ async function testTableName() {
   await db.stop();
 }
 
+async function testInstalledPluginAutoLoad() {
+  console.log('\n===== 注册表插件自动加载（entry 仓库相对路径 + 根级文件）=====');
+  const os = require('os');
+  const fs = require('fs');
+  const home = os.homedir();
+  const name = '_xqltest_registry';
+  const dir = path.join(home, '.jsql', 'plugins', name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'index.js'),
+    "module.exports = { name: '" + name + "', install(engine) { engine.__xqltest = true; } };\n");
+  fs.writeFileSync(path.join(dir, 'manifest.json'),
+    JSON.stringify({ name, version: '1.0.0', entry: 'plugins/' + name + '/index.js', files: [] }));
+  try {
+    const db = new Database(':memory:', { modules: true });
+    await db.start();
+    ok('仓库相对 entry + 根级 index.js 能自动加载', db.__xqltest === true);
+    await db.stop();
+  } finally {
+    try { fs.rmSync(path.join(home, '.jsql', 'plugins', name), { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+}
+
 (async () => {
   await testEngine(Database, 'Database (Pure JS)');
   await testAutoLoadOff();
   await testTableName();
+  await testInstalledPluginAutoLoad();
 
   // native 引擎（Linux 上可用；Android 等平台无二进制时跳过）
   try {