@nightpainters/dsh-ling 1.6.1 → 1.7.0

package/lib/host/api.js

@@ -9,7 +9,7 @@ import { sessionLineProbe, sessionLineState } from './session-line.js'; // E3(20
 import { selectL1 } from './l1.js';
 import { applySuggestionAsRule, dismissSuggestion } from './feedback.js';
 import { applyCorpusSuggestion, dismissCorpusSuggestion } from './suggestions.js';
-import { runDeepPass, rerunOne, candidateFor, deepSummarizeOne, llmOnce, importRawTargets } from './deepsummary.js';
+import { runDeepPass, rerunOne, candidateFor, deepSummarizeOne, llmOnce, importRawTargets, resolveAuto, storedAuto } from './deepsummary.js';
 import { GENESIS_SYS, parseGenesisResult, buildGenesisSource, composeGenesisRows, filterNamePairs } from './genesis.js';
 import { scanIntoMemory } from './scan-dsweb.js';
 import { scanDshHistory } from './backfill.js';
@@ -21,6 +21,9 @@ import { logImport, listImportLog, formatLogLine, cleanTooBig, cleanTooBigNames,
 import { checkRequest, lanAddresses, sanitizePersonaPatch } from './guard.js';
 // 手术门(2026-09-30 深夜):本机判据 / 每启动票据 / 承诺句 / 哈希链留痕 —— 判据本体只在 surgery.js 一处。
 // ⚠️ 上面那行 guard.js 的 import **不许动形态**:tests/guard.test.mjs:139 逐字匹配它。
+// `/auto` 的白名单(2026-10-16)因此**另起一行**:并进上面那行会把那条逐字匹配的护栏打红,
+// 而它护的是"api.js 真的接上了守卫"这件事,不该为了少一行 import 去动它。
+import { sanitizeAutoPatch } from './guard.js';
 import {
   gateSurgery, isLocalSurgeryRequest, readSurgeryTicket, rotateSurgeryTicket,
   listSurgeryEvents,
@@ -44,6 +47,9 @@ import {
   openSource, buildCandidates, conversationText, probeAssistant, summarizeWithRetry, cleanSummary,
   touchMemoryVersion, resolveAssistant, MIN_TURNS_DEFAULT, SUMMARY_SYS,
 } from './dsweb-summary.js';
+// 1.7 图书馆导入通道的**模型段**(契约 §11.1):两档引擎(小助手 / 全局)的接线都归那个模块一处所有,
+// 本文件只负责"把 body 里的引擎名翻成一个 hook + 一个如实的 label"。
+import { IMPORT_ENGINES, makeImportModelHook } from './library-import-engine.js';
 import { TRUNK_ID } from './memory.js';
 import { bucketize, nameBucket } from './autotree.js';
 import { accessLogStatus } from '../audit/index.js';
@@ -377,7 +383,11 @@ export function readBody(req, maxBytes = BODY_MAX_BYTES, opts = {}) {
 }
 
 export function registerApi(ctx, deps, config) {
-  const { gate, memory, settings } = deps;
+  // 1.7(2026-10-07):多一个**图书馆运行时**依赖(`library`)。它由主线实现并注入同一个实例
+  // (index.js 的 API / 全局工具 / agent 级工具三处收同一份 —— 见 1.7-integration-design §Configuration)。
+  // ⚠️ 它是**可选**的:未注入(老调用方 / 测试)时,/library/* 一律回 503 unavailable,
+  //   其余 40+ 端点**一个字都不变** —— "图书馆不可用只降级图书馆"这条是契约硬要求。
+  const { gate, memory, settings, library } = deps;
 
   // ── 手术门:票据**每启动轮换**(规格 §1.2)──────────────────────────────────────
   // 这一句就是"每启动"的落点:插件随宿主启动装配一次 ⇒ 覆盖写一枚新的 32 字节随机票,
@@ -389,6 +399,14 @@ export function registerApi(ctx, deps, config) {
   let disposed = false;
   let disposeRoutes = null;
   let timer = null;
+  const cleanup = () => {
+    disposed = true;
+    if (timer) { clearInterval(timer); timer = null; }
+    if (disposeRoutes) {
+      const release = disposeRoutes; disposeRoutes = null;
+      release();
+    }
+  };
 
   const tryMount = () => {
     if (disposed || disposeRoutes) return;
@@ -400,9 +418,11 @@ export function registerApi(ctx, deps, config) {
         ctx.inject?.(['webServer'], (child) => {
           scopeCtx = child;
           const s2 = child?.webServer;
-          if (s2 && typeof s2.register === 'function' && !disposeRoutes) {
-            disposeRoutes = mountRoutes(s2);
-            memory.kvSet('api.registered', '1');
+          if (!disposed && s2 && typeof s2.register === 'function' && !disposeRoutes) {
+            try {
+              disposeRoutes = mountRoutes(s2);
+              memory.kvSet('api.registered', '1');
+            } catch (error) { cleanup(); throw error; }
           }
         });
       } catch (e) {
@@ -410,7 +430,7 @@ export function registerApi(ctx, deps, config) {
       }
       server = scopeCtx?.webServer ?? null;
     }
-    if (server && typeof server.register === 'function') {
+    if (!disposed && !disposeRoutes && server && typeof server.register === 'function') {
       disposeRoutes = mountRoutes(server);
       memory.kvSet('api.registered', '1');
     }
@@ -418,6 +438,22 @@ export function registerApi(ctx, deps, config) {
 
   const mountRoutes = (server) => {
     const disposers = [];
+    const pendingLibraryChecks = new Set();
+    const releaseRoutes = () => {
+      for (const controller of pendingLibraryChecks) {
+        if (controller.signal.aborted) continue;
+        const error = new Error('插件卸载,本次核对被取消(不写核对留痕)。');
+        error.code = 'unloaded'; error.cancelled = true;
+        controller.abort(error);
+      }
+      pendingLibraryChecks.clear();
+      for (const dispose of disposers.splice(0).reverse()) {
+        try { if (typeof dispose === 'function') dispose(); } catch { /* continue releasing all routes */ }
+      }
+    };
+    // Registration may throw after some routes have mounted. Roll those back
+    // here: the caller has not yet received a disposer for this partial batch.
+    try {
     // 一键深摘(import 源)的运行状态:单实例串行,防并发重入
     const impRun = { running: false, total: 0, done: [], startedAt: 0, finishedAt: 0 };
     // 网页端库"补摘要"运行状态(与深摘同纪律:单实例串行 + 轮询进度)
@@ -461,7 +497,7 @@ export function registerApi(ctx, deps, config) {
       '/deep/run-import', '/deep/run', '/deep/one',
       '/dsweb/summary/run',
       '/feedback/apply', '/feedback/dismiss', '/suggestions/apply', '/suggestions/dismiss',
-      // ── 1.5.3(2026-09-29 夜,尝生批;依据作者的审计台账《1.5.3 端点写面 · 未进 POST_ONLY》,该台账不随包公开)──
+      // ── 1.5.3(2026-09-29 夜,用户批;依据作者的审计台账《1.5.3 端点写面 · 未进 POST_ONLY》,该台账不随包公开)──
       // ⚠️ 版本号由主会话校正:本批**尚未发布**(`package.json` 仍是 `1.5.3-dev`)⇒ 归 **1.5.3**;
       //    原先这里写的 `1.5.4` 是修复代理想当然的版本号,仓库里从无 1.5.4 的计划。
       // 三条都是**形态上就不该由 GET 执行**的端点,补进同一处声明(仍守"一处维护、一眼看全"):
@@ -475,10 +511,53 @@ export function registerApi(ctx, deps, config) {
       // ── 1.5.3(2026-09-30 深夜,手术门)· 取票 = **发放凭据**的动作,形态上就不该由 GET 执行 ──
       // `/surgery/ticket` 只对**本机直连**(无代理头 **且** 带 UA)发一枚 32 字节票;**不缓存**(no-store)—— 票据是每启动轮换的。
       '/surgery/ticket',
+      // ── 1.7 图书馆(2026-10-07)· 四个写面 ────────────────────────────────────────────
+      // 与其余写面同一个取舍:集中在这张表里声明,而不是在 4 个 register 调用点各写一遍。
+      // 语义:create/revise/withdraw 会**改库**(新版本 / 留痕撤下),check 会**落一条核对留痕**
+      // (`library_check` 行)—— 四者都不是"读",故 GET 一律 405。
+      '/library/create', '/library/revise', '/library/withdraw', '/library/check',
+      // ── 1.7 图书馆 · 导入通道(2026-10-10)· 两条写面 ──────────────────────────────
+      // `analyze` 本身不写库,但它**收下整份原文**(可达 importTextMaxBytes = 1 MiB)、
+      // 且带模型段(能花全局模型额度)⇒ 形态上就不该由 GET 执行;
+      // `commit` 会**真落库**(逐条 create)⇒ 与其余四个写面同一类。
+      '/library/import/analyze', '/library/import/commit',
+      // ── 1.7 · 后台自动行为(2026-10-16)· 一条写面 ─────────────────────────────────
+      // `/auto` 会**改 settings.auto**(关掉自动深摘 / 反馈回路 ⇒ 直接改插件以后的行为),
+      // 与 /persona 同一类:写半边只许 POST ⇒ 进这张表(`GET` 拿不到写分支)。
+      // ⚠️ 它是**双方法路径**(GET 读 / POST 写),读半边由下面的 `DUAL_METHOD_READ_PATHS` 放行 ——
+      //    不这么做,这道闸会把读半边一起 405 掉,面板就永远读不到自己的开关。
+      '/auto',
+    ]);
+
+    // ── 双方法路径(2026-10-16):同一路径 GET 读 + POST 写,读半边单独放行 ────────────────
+    // 为什么要另立一张表:上面那道方法闸是**整条路径**级的(`POST_ONLY.has(sub) && method !== 'POST'`),
+    //   而 `/auto` 两个半边都要 —— GET 读生效值(面板的开/关与"这个值谁定的"从这来),POST 写 auto 子树。
+    //   `/assistant/config` 是同一个形状,但它**不在** POST_ONLY 里(见 guard.test.mjs 的差集快照第 643 行);
+    //   `/auto` 选择"进表 + 放行读",因为这样"改行为的写面只许 POST"这句话在声明里看得见。
+    // 纪律:handler 内部按 method 分支,GET 分支**一个字节都不写盘**;纯读端点不许塞进这里(纯读走 GET_ONLY)。
+    const DUAL_METHOD_READ_PATHS = new Set(['/auto']);
+    // ── 1.7 图书馆 · **只读面**(2026-10-07)────────────────────────────────────────────
+    // 这是本文件**第一张 GET_ONLY 表**(此前只有"写面不许 GET"这半边闸):
+    // 契约 §Integration Routes 明写"Reads allow GET only",1.7-integration-design §API and tools
+    // 同样要求"Reject unsupported methods"。为什么读面也要**反向**收紧:
+    // 宿主路由表的 `WebRoute` 没有 method 字段,凡是注册成 exact 的路径**任何方法都会进来**
+    // (与 POST_ONLY 那段注释同源)⇒ 不钉死 GET,`POST /library/search` 就能带着 body 走一条
+    // 谁也不认识的路;而读回执是**源资料**面,不该有"带体的写形状"的入口。
+    // 取 405(不是 403):它挡的是"方法不对",与身份无关 —— 故与 POST_ONLY 一样**先于**鉴权。
+    const GET_ONLY = new Set([
+      '/library/status', '/library/search', '/library/item', '/library/history', '/library/checks',
+      '/library/browse',
+      // ── B 档(2026-10-15)· 深层库(结论层)只读面 ────────────────────────────────
+      // 纯读(`listDeepItems` + 两个 COUNT,不写一个字节);写面**不走这条路** ——
+      // 落条与作废是经主人授权的动作,走工具 `deep_item`。反向收紧的理由同上:
+      // 宿主路由表没有 method 字段,不钉死 GET,`POST /deep/items` 就能带体走进来。
+      '/deep/items',
     ]);
     // ── 手术门下沉(2026-09-30 深夜;规格 §1.3「门下沉为一处」)──────────────────────────
     // 判据本体**只在** lib/host/surgery.js 的 requireSurgery() 里;这里只是**唯一**的调用点。
-    // 覆盖面 = 全部 12 条能改人格/规矩/习惯的写面(逐条清单见 surgery.js 头部注释):挂在 guard(handler)
+    // 覆盖面 = 全部 14 条能改人格/规矩/习惯的写面(逐条清单见 surgery.js 头部注释):挂在 guard(handler)
+    //   ⚠️ 条数 2026-10-05 夜由 12 订正为 14(B-5):清单逐条列了 14 行,而这里与 surgery.js:15 一直写"12"
+    //      ⇒ 三处不一致的根源是"没人拿清单行数当唯一真值"。现口径:**以清单行数为准**,改清单须同批改这两处。
     // 上就"一眼看全、零回归面",与 POST_ONLY / 413 出口同一个取舍 —— 而不是在 49 个 register 调用点各写一遍。
     // 安全的位置:本调用在 POST_ONLY(405)与 guardVerdict(403)**之后** ⇒ 被挡下的请求绝不会走到 handler。
     // ⚠️ 承诺句必须**惰性**取:多数写端点的载荷由 `await readBody(req)` 消费,而请求流**只能读一次** ——
@@ -506,7 +585,10 @@ export function registerApi(ctx, deps, config) {
       // 方法校验**先于鉴权** —— 它挡的是"浏览器被诱导发出的同站请求",与身份无关。
       // 两种 url 形态都能处理:带前缀(`/api/dsh-ling/x`)被 replace 剥掉,不带的原样保留。
       const sub = String(req.url || '').split('?')[0].replace(/^\/api\/dsh-ling/, '');
-      if (POST_ONLY.has(sub) && String(req.method || 'GET').toUpperCase() !== 'POST') {
+      const methodNow = String(req.method || 'GET').toUpperCase();
+      // 双方法路径(见 DUAL_METHOD_READ_PATHS 声明处):`GET` 是它的读半边,放行到 handler 的读分支。
+      if (POST_ONLY.has(sub) && methodNow !== 'POST'
+        && !(methodNow === 'GET' && DUAL_METHOD_READ_PATHS.has(sub))) {
         // ── C-14（rejection 误标）──────────────────────────────────────────────
         // 上面第 225 行就把这次请求交给访问日志了，但**判定点在这里**：只按状态码反推的
         // rejectionReason() 分不清"哪个栅栏拒的"。故判定完成后把真因挂到请求对象上；
@@ -517,6 +599,14 @@ export function registerApi(ctx, deps, config) {
         sendJson(res, 405, { ok: false, error: 'method-not-allowed', want: 'POST' });
         return;
       }
+      // ── 1.7 图书馆 · 只读面反向收紧(2026-10-07)────────────────────────────────────
+      // 与上面 POST_ONLY 同一个位置、同一个理由:方法闸**先于鉴权**、更先于 handler。
+      // 回执形状照抄 POST_ONLY 那一支的既有约定(`error`/`want`),只把 want 换成 'GET'。
+      if (GET_ONLY.has(sub) && String(req.method || 'GET').toUpperCase() !== 'GET') {
+        req.__dshLingRejection = 'method-not-allowed';
+        sendJson(res, 405, { ok: false, error: 'method-not-allowed', want: 'GET' });
+        return;
+      }
       const verdict = guardVerdict(req);
       if (!verdict.ok) {
         req.__dshLingRejection = verdict.reason; // C-14：同上，写日志发生在下面的 sendJson→res.end 之内
@@ -530,7 +620,7 @@ export function registerApi(ctx, deps, config) {
       // 但调用点必须落在"载荷已经解析出来"的地方(见下),因为请求流只能读一次。
       // 每个写端点的形状固定为:`const body = JSON.parse(…); if (!gateSurgery(req, res, sendJson, body, { settings, logFile: surgeryLog, endpoint: sub })) return;`
       //   · 这一句就是全部接线:判据(本机 / 每启动票据 / 承诺句)与拒绝回应都在 surgery.js;
-      //   · 覆盖面 = 12 条写面,逐条清单与"改前是否过门"见 surgery.js 头部注释。
+      //   · 覆盖面 = 14 条写面,逐条清单与"改前是否过门"见 surgery.js 头部注释。
       try {
         await handler(req, res);
       } catch (e) {
@@ -1130,7 +1220,7 @@ export function registerApi(ctx, deps, config) {
       sendJson(res, 200, { ok: true, total: list.length, log: list });
     }));
 
-    // POST /branch-log/pending —— 复盘守门(2026-09-22 尝生:「互相复盘不应该被我绕过」)。
+    // POST /branch-log/pending —— 复盘守门(2026-09-22 用户:「互相复盘不应该被我绕过」)。
     // 返回"自器灵上次开口以来累积了多少笔结构改动还没交代";侧栏据此提示,
     // 并在未同步时**拦住"退出复盘模式"** —— 改完树必须让器灵有机会看到。
     // ⚠️ 进 `POST_ONLY` 的原因:它不是纯读 —— `memory.branchLogPending()` 在"水位键缺失 +
@@ -1159,12 +1249,12 @@ export function registerApi(ctx, deps, config) {
     // GET /conflicts?status=pending|confirmed|dismissed —— 待复盘矛盾(带两侧标题,复盘界面直接可读)
     disposers.push(register('/conflicts', async (req, res) => {
       const q = new URL(req.url, 'http://dsh.internal').searchParams;
-      // 2026-09-21:补两侧**摘要全文** —— 只给标题时人根本判不出"到底哪矛盾"(尝生实测反馈)。
+      // 2026-09-21:补两侧**摘要全文** —— 只给标题时人根本判不出"到底哪矛盾"(用户实测反馈)。
       const ovOf = (src, cid) => {
         try { return memory.overviewById(String(src), String(cid)) || null; } catch { return null; }
       };
       // 2026-09-21:涉及归档会话的矛盾不进列表 —— 归档意味着"这条别再提了",
-      //   但已登记的旧记录不会自动消失,所以在这里按当前归档状态实时筛(尝生实测反馈:
+      //   但已登记的旧记录不会自动消失,所以在这里按当前归档状态实时筛(用户实测反馈:
       //   扫描侧上一轮已排除归档,可已存在的记录仍会一直显示)。
       const archSet = memory.archivedConvIdSet();
       const isArch = (side) => side && side.source === 'dsh' && archSet.has(String(side.convId));
@@ -1199,7 +1289,7 @@ export function registerApi(ctx, deps, config) {
       sendJson(res, r.ok ? 200 : 400, r);
     }));
 
-    // ---- 一键生成记忆树(D9-b,2026-09-21 与尝生定案) ----
+    // ---- 一键生成记忆树(D9-b,2026-09-21 与用户定案) ----
     //   两阶段:① 机械分段(零成本、只读) ② 小助手命名 ③ 主人审核后落库。
     //   不变量:不改写任何记忆内容 —— 只建枝/主脉 + 挂会话归属。
     const autoSeg = (gapDays, maxSize) => bucketize(memory.overviewIndex(), { gapDays, maxSize });
@@ -1303,7 +1393,7 @@ export function registerApi(ctx, deps, config) {
       const created = [];
       let assigned = 0;
       let skipped = 0;
-      // 零散合簇(尝生 2026-09-21 裁决):名字含「零散」的簇统一挂到同一个主脉「零散会话」下。
+      // 零散合簇(用户 2026-09-21 裁决):名字含「零散」的簇统一挂到同一个主脉「零散会话」下。
       //   理由:历史网页端的一次性问答主题天然分散、不属于任何工作线;合并成一簇后可在
       //   复盘时展开细化(设计稿 §10.3)。主脉按名复用,不重复建。
       const ZERO_NAME = '零散会话';
@@ -1490,7 +1580,7 @@ export function registerApi(ctx, deps, config) {
       const text = '主脉名称:' + String(v.name || veinId) + '\n\n素材(共 ' + mat.length + ' 条):\n'
         + mat.map((m, i) => (i + 1) + '. ' + (m.title || m.convId) + ' —— ' + m.summary).join('\n');
       const t0 = Date.now();
-      // 全局大模型(2026-09-25 尝生:「你在给自己做整理,别让小助手代劳」)。
+      // 全局大模型(2026-09-25 用户:「你在给自己做整理,别让小助手代劳」)。
       // 原先走本机小助手(summarizeWithRetry + /no_think),但"这几条枝讲的是不是一件事"
       // 是**判断**不是搬砖 —— 该用器灵自己的脑;小助手留给压缩/分类这类机械活。
       //
@@ -1799,7 +1889,7 @@ export function registerApi(ctx, deps, config) {
       const body = JSON.parse((await readBody(req)) || '{}');
       const limit = Math.max(10, Math.min(200, Number(body.limit) || 60));
       const threshold = Math.max(0.3, Math.min(0.95, Number(body.threshold) || 0.55));
-      // 2026-09-21:排除**已归档**会话 —— 封存的对话不该再被拉出来互相判矛盾(尝生实测反馈)。
+      // 2026-09-21:排除**已归档**会话 —— 封存的对话不该再被拉出来互相判矛盾(用户实测反馈)。
       const archived = memory.archivedConvIdSet();
       const rows = memory.queryOverviews({ limit }).items
         .filter((r) => r.source === 'dsh' || r.source === 'import')
@@ -2081,7 +2171,7 @@ export function registerApi(ctx, deps, config) {
     //   上锁(sealed:true)需带新承诺句 → 覆盖哈希;撤锁清哈希;每次成功变更后存「结果档案」。
     disposers.push(register('/persona', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
-      // ── 手术门(第 1/12 条写面)────────────────────────────────────────────────
+      // ── 手术门(第 1/14 条写面)────────────────────────────────────────────────
       // 载荷必须**在这里**交上去:请求流只能读一次(见 guard 里的接线说明)。
       // 只交 `unlock` 一项:门只读它(§1.3 判据 3)。把整份 patch 交上去 = 让留痕的"字段指纹"
       // 记下一串与判据无关的内容(越少记越好;要留痕的是"这次手术",不是"他改成了什么")。
@@ -2127,13 +2217,58 @@ export function registerApi(ctx, deps, config) {
       });
     }));
 
+    // ---- 1.7(2026-10-16 与用户定):「后台行为」开关 —— 一个路径按 method 分派 ----
+    // 缘起:自动深摘 / 启动探活 / 反馈回路一直**默认开着**,却既没文档也没面板开关。
+    //   现在给出开关,但**默认值一个字节都不变**(见 persona.js 的 DEFAULT_SETTINGS.auto)。
+    //   GET  /auto → 生效值(resolveAuto 的三级解析结果)+ 落盘的 auto 子树 + 插件配置旧键快照(只读,不写盘)
+    //   POST /auto { patch } → 过白名单收窄后 settings.update({ auto: clean }),回生效值 + 丢弃/夹取清单
+    // 白名单纪律与 /persona 同源(G10 那次:`/`persona` 能持久化关掉守卫):`/auto` 收的是任意 body,
+    //   而 settings 是**以后每次启动都读**的持久面 ⇒ 不收窄就等于开了一个"改守卫/人格/记忆"的写入口。
+    disposers.push(register('/auto', async (req, res) => {
+      // 插件配置一侧的**只读快照**(旧键名):面板要能说出"这个值是不是配置里定的"。
+      // 四个键给 `null` 而不是省略 = "没写"(不是 false / 0)——免得前端把 undefined 看成设成了 0。
+      const pc = (config && typeof config === 'object' && !Array.isArray(config)) ? config : {};
+      const pluginConfig = {
+        feedbackAuto: pc.feedbackAuto ?? null,
+        deepSummaryAuto: pc.deepSummaryAuto ?? null,
+        deepIntervalMin: pc.deepIntervalMin ?? null,
+        deepMaxPerRun: pc.deepMaxPerRun ?? null,
+      };
+      if (String(req.method || 'GET').toUpperCase() === 'POST') {
+        const body = JSON.parse((await readBody(req)) || '{}');
+        // 形状照抄 /persona:既收 `{patch:{…}}` 也收裸 body(前端两种写法都有先例)。
+        const raw = (body.patch && typeof body.patch === 'object') ? body.patch : body;
+        const { clean, dropped, clamped } = sanitizeAutoPatch(raw);
+        if (dropped.length) console.warn('[dsh-ling] /auto 丢弃白名单外的字段: %s', dropped.join(', '));
+        if (!Object.keys(clean).length) {
+          // 全是白名单外/类型不符 ⇒ **不落盘**,但如实回报丢在哪(clamp 与 dropped 一起给)。
+          return sendJson(res, 400, { ok: false, error: 'nothing-to-update', dropped, clamped });
+        }
+        await settings.update({ auto: clean });
+        return sendJson(res, 200, {
+          ok: true,
+          // 生效值重新解析一次(settings 实例已在 update 后自更新;source 会如实变成 'settings')。
+          effective: resolveAuto(settings, pc),
+          dropped, clamped,
+        });
+      }
+      // `stored` = **落盘的** auto 子树(即用户真的写过的键;settings.json 只持久化用户补丁)。
+      //   刻意不用 `settings.get().auto`:那个把代码默认值也合并了进来,五个键永远都在 ⇒ 看不出"用户设过什么"。
+      return sendJson(res, 200, {
+        ok: true,
+        effective: resolveAuto(settings, pc),
+        stored: storedAuto(settings),
+        pluginConfig,
+      });
+    }));
+
     // POST /persona/check { unlock }  客户端「解锁修改」先验钥(只读,不落盘)
     // 进 `POST_ONLY` 是**防御性**:今天 GET 下 body 恒为 `{}` ⇒ 只回"承诺句不一致"(无写),
     // 但 handler 读 body、注释也自称 POST ⇒ 形态已经是 POST 端点,补进去零成本。
     disposers.push(register('/persona/check', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
       const cur = settings.get();
-      // 手术门(第 2/12 条写面):**这一条本身不写** —— 它是"验句预言机"(在线猜句的入口)。
+      // 手术门(第 2/14 条写面):**这一条本身不写** —— 它是"验句预言机"(在线猜句的入口)。
       // 门口径与别处**完全一致**:已定型 ⇒ 必须本机 + 带票 + 原句,否则连"这句对不对"都不告诉它
       // (改前它对任意调用者有求必应 ⇒ 猜句成功率只受网络延迟限制)。
       if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/persona/check' })) return;
@@ -2165,7 +2300,7 @@ export function registerApi(ctx, deps, config) {
     //   无论是否定型,只允许更新 persona.aiTitle(定位自述)单字段;其余字段仍需手术/承诺句。
     disposers.push(register('/persona/self-summary', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
-      // 手术门(第 3/12 条写面):身份自述 aiTitle 属身份保护区。只交 unlock(见 /persona 处说明)。
+      // 手术门(第 3/14 条写面):身份自述 aiTitle 属身份保护区。只交 unlock(见 /persona 处说明)。
       if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/persona/self-summary' })) return;
       const text = String(body.text ?? '').trim();
       if (!text) return sendJson(res, 200, { ok: false, reason: 'empty', message: '内容为空' });
@@ -2189,7 +2324,7 @@ export function registerApi(ctx, deps, config) {
     //   (习惯不能直达;这里的用户点击就是确认动作),重量前先归档。
     disposers.push(register('/persona/hint-adopt', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
-      // 手术门(第 4/12 条写面):一次点击即 propose+confirm 落一条习惯。只交 unlock。
+      // 手术门(第 4/14 条写面):一次点击即 propose+confirm 落一条习惯。只交 unlock。
       if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/persona/hint-adopt' })) return;
       const text = String(body.text ?? '').trim();
       if (text.length < 4 || text.length > 400) {
@@ -2229,7 +2364,7 @@ export function registerApi(ctx, deps, config) {
     //      "去掉 quote"**不再等于**"来自面板":归因只由 ruleWriteAttribution() 一处判(见文件头)。
     disposers.push(register('/persona/rule', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
-      // 手术门(第 5+6/12 条写面:add 与 remove 同一端点,一次判过):
+      // 手术门(第 5+6/14 条写面:add 与 remove 同一端点,一次判过):
       //   规矩是他的指令(quote 是"经同意"的凭据),但**删规矩能整批删光** ⇒ 一律过门。
       if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/persona/rule' })) return;
       const action = String(body.action || 'add');
@@ -2271,7 +2406,7 @@ export function registerApi(ctx, deps, config) {
     //   习惯不直达:propose(任一方可提)/ confirm(对方点头)/ reject / remove。
     disposers.push(register('/persona/habit', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
-      // 手术门(第 7+8/12 条写面:propose/confirm/reject 与 remove 同一端点,一次判过)。
+      // 手术门(第 7+8/14 条写面:propose/confirm/reject 与 remove 同一端点,一次判过)。
       // 改前只有 remove 过门 —— "加比删容易"正是侦察里指出的不对称,现在两条都过门。
       if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/persona/habit' })) return;
       const action = String(body.action || 'propose');
@@ -2303,7 +2438,17 @@ export function registerApi(ctx, deps, config) {
 
     // POST /persona/habits/scan  通道 A:零模型,扫"跨会话重复出现的纠正"→ 落成习惯候选(待确认)
     //   阈值:同类纠正 ≥4 次 且 跨 ≥3 个会话(单次会话里被说三遍不算模式;口径与变更记录见 habit-gen.js 的 SCAN_DEFAULTS)
-    disposers.push(register('/persona/habits/scan', async (_req, res) => {
+    disposers.push(register('/persona/habits/scan', async (req, res) => {
+      // ── 手术门(A-1,2026-10-05 夜;交办单 HANDOFF-机制面复核交办单 §A-1)──────────────────
+      //   ⚠️ 本端点**会写 `habitsPending`** ⇒ 它进的是**人格面** ⇒ 按 P-5 第 5 条必须过闸。
+      //   改前它是 14 条清单外的漏点:确认侧 `/persona/habit`(:2276)**过门**,而两条**产出候选**
+      //   的写面(`scan` / `reflect`)不过门 —— 一条通路的两半只改了一半,正是
+      //   DESIGN §0.1 工程理念 9「两半同批」的反例(2026-10-05 机制面复核 A-1)。
+      //   接线形状照抄 `/persona/habit`:必须先 `readBody` 再判门(请求流只能读一次,门要拿
+      //   `unlock` 原句);空 body 用 `|| '{}'` 兜住(面板按钮不带 body)。
+      //   判据本体仍**只在** `surgery.js` 的 `requireSurgery()` 一处,这里只接线、不重判。
+      const body = JSON.parse((await readBody(req)) || '{}');
+      if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/persona/habits/scan' })) return;
       try {
         // 上限(2026-09-16 定案):待确认满了就**明确驳回**,并说明为什么 —— 不排队、不静默丢弃。
         const capS = pendingMaxOf(settings);
@@ -2341,7 +2486,13 @@ export function registerApi(ctx, deps, config) {
 
     // POST /persona/habits/reflect  通道 B:让她"回想最近的相处" → 1~5 条习惯候选(一次 LLM,只提议不落盘)
     // 手动触发,材料给足:主人真人原话 + 记忆概述 + 纠正统计 + 她现状(默认预算 20 万字符,可用 settings.habits.reflect* 覆盖)
-    disposers.push(register('/persona/habits/reflect', async (_req, res) => {
+    disposers.push(register('/persona/habits/reflect', async (req, res) => {
+      // ── 手术门(A-1,同 scan;两处必须同批改 —— 它们共享 `proposeHabit` 这一半)──────────
+      //   `reflect` 的候选经 `parseReflect` → `proposeHabit`(:2436)落进 `habitsPending` ⇒ 同属写面。
+      //   注意它另有 kv 写入(`habits.reflect.cursor` / `.last` / `.debug`)—— 那些是**运行记录**,
+      //   不是人格面内容 ⇒ 单独看它们不构成"必须过门"的理由;过门的理由是候选落进人格面。
+      const body = JSON.parse((await readBody(req)) || '{}');
+      if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/persona/habits/reflect' })) return;
       try {
         // 上限(2026-09-16 定案):与 scan 同一条规则 —— 满了明确驳回,不排队、不静默丢弃。
         const capR = pendingMaxOf(settings);
@@ -2507,7 +2658,7 @@ export function registerApi(ctx, deps, config) {
     //   自性类成长通道:白名单字段(语气枚举 + 风格追加),锁定下亦可采纳;不可逆操作一律不做。
     disposers.push(register('/persona/grow', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
-      // 手术门(第 9/12 条写面):改语气 / 追加风格注 —— 旧注释自陈"锁定下亦可采纳",那正是缺口。
+      // 手术门(第 9/14 条写面):改语气 / 追加风格注 —— 旧注释自陈"锁定下亦可采纳",那正是缺口。
       if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/persona/grow' })) return;
       const patch = {};
       const toneIn = body.tone && typeof body.tone === 'object' ? body.tone : {};
@@ -2543,7 +2694,7 @@ export function registerApi(ctx, deps, config) {
     // POST /persona/rollback { ts, unlock? }  回滚到某历史存档(同样受定型门约束)
     disposers.push(register('/persona/rollback', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
-      // 手术门(第 10/12 条写面):整体回写 {persona,styles}(含 sealed/sealPhrase)——
+      // 手术门(第 10/14 条写面):整体回写 {persona,styles}(含 sealed/sealPhrase)——
       // 回滚到定型前快照 = **撤锁**,故判据必须在"看存档是否存在"之前:格式不对的请求也不该探到存档。
       if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/persona/rollback' })) return;
       const ts = Number(body.ts);
@@ -2920,7 +3071,7 @@ export function registerApi(ctx, deps, config) {
       const body = JSON.parse((await readBody(req)) || '{}');
       // ⚠️ **手术门补在这一条上**(2026-10-04 发布关④ 抓到):它**写人格**(诞生仪式生成的自我介绍
       //   会被主人采纳进 persona),却一直没有门 —— 而 README 与 `gateSurgery` 的注释都写着
-      //   "**全部 12 条写面**已由手术门统一判过",实测全仓只有 11 处 `gateSurgery` 调用点。
+      //   "**全部 14 条写面**已由手术门统一判过",实测全仓只有 11 处 `gateSurgery` 调用点。
       //   补门后它与其余写面同级:本机 + 每启动票据 + 原句匹配。
       //   ⚠️ 载荷只交 `unlock` 一项(与 `/persona` 同口径):门只读它,把整份 body 交上去
       //   会让留痕的"字段指纹"记下与判据无关的内容。
@@ -2974,7 +3125,7 @@ export function registerApi(ctx, deps, config) {
     // POST /feedback/apply { id }
     disposers.push(register('/feedback/apply', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
-      // 手术门(第 11/12 条写面):采纳建议 → 落习惯 / 改自称。改前只有身份两 kind 有门。
+      // 手术门(第 11/14 条写面):采纳建议 → 落习惯 / 改自称。改前只有身份两 kind 有门。
       if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/feedback/apply' })) return;
       const r = await applySuggestionAsRule(memory, settings, body.id);
       if (!r.ok) return sendJson(res, 200, { ok: false, reason: r.reason });
@@ -3016,7 +3167,7 @@ export function registerApi(ctx, deps, config) {
     // POST /suggestions/apply { id }
     disposers.push(register('/suggestions/apply', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
-      // 手术门(第 13/12 条写面):采纳建议。改前**只有** kind∈{aiName,userTitle} 才验句,
+      // 手术门(第 13/14 条写面):采纳建议。改前**只有** kind∈{aiName,userTitle} 才验句,
       // 惯例类(hardrule 等)可自由追加 ⇒ 现在整条端点统一过门(下面那段身份分支因此成了一道冗余的深防线,
       // 保留不动:判据更严的一侧永远不会把请求放过去)。
       if (!gateSurgery(req, res, sendJson, { unlock: body.unlock }, { settings, logFile: surgeryLog, endpoint: '/suggestions/apply' })) return;
@@ -3065,6 +3216,31 @@ export function registerApi(ctx, deps, config) {
       });
     }));
 
+    // ── 深层库(结论层)· 只读面(B 档,2026-10-15)──────────────────────────────────
+    // 为什么要有这一面:411 条结论此前**只有读的路、没有看得见的门** —— 面板里连"结论层"
+    // 都没有,于是"我正在被注入什么"这件事只能靠 `recall` 间接感到(用户问"是不是没通道"
+    // 的观感就来自这里)。写面**不在**这条路上:落条与作废走工具 `deep_item`(经他授权)。
+    // 纯读:`listDeepItems` + 两个 COUNT,不写一个字节。
+    // ⚠️ `all` 报**在役**条数(总数 − 已退役),与工具面同一口径 —— 别把退役的算进"有多少条结论"。
+    // ⚠️ 行映射走 `memory.deepItemView`(单一来源):api.js 与 tools.js 报的是同一种东西,
+    //    各写一份必然漂。
+    disposers.push(register('/deep/items', async (req, res) => {
+      const q = new URL(req.url, 'http://dsh.internal').searchParams;
+      const kind = String(q.get('kind') || '').trim();
+      const n = Number(q.get('limit'));
+      const limit = Number.isFinite(n) && n > 0 ? Math.min(500, Math.trunc(n)) : 200;
+      const includeSuperseded = q.get('includeSuperseded') === '1';
+      const rows = memory.listDeepItems({ kind, limit, includeSuperseded });
+      const retired = memory.deepRetiredCount();
+      sendJson(res, 200, {
+        ok: true,
+        items: rows.map((r) => memory.deepItemView(r)),
+        shown: rows.length,
+        all: memory.deepItemCount() - retired,
+        retired,
+      });
+    }));
+
     // POST /deep/run { limit? }
     disposers.push(register('/deep/run', async (req, res) => {
       const body = JSON.parse((await readBody(req)) || '{}');
@@ -3117,7 +3293,7 @@ export function registerApi(ctx, deps, config) {
       const q = new URL(req.url, 'http://dsh.internal').searchParams;
       const text = await readBody(req);
       const parsed = JSON.parse(text || '{}');
-      // 手术门(第 14/12 条写面)⚠️ **前移到 importBundle 之前** —— 这是本批唯一一处"改前门在后面"的修正:
+      // 手术门(第 14/14 条写面)⚠️ **前移到 importBundle 之前** —— 这是本批唯一一处"改前门在后面"的修正:
       //   改前:`memory.importBundle()`(下一行)先跑,门在它**之后** ⇒ 一个带着恶意 bundle 的请求
       //   即使人格回写被拒,**记忆也已经整体被换掉了**(DESIGN §3 该行备注"门拦不住记忆被换")。
       //   现在:已定型时,未过门(非本机 / 无票 / 原句不符)的请求**一个字节都不落库**。
@@ -3149,13 +3325,392 @@ export function registerApi(ctx, deps, config) {
       sendJson(res, 200, { ok: report.errors === 0, personaApplied, report });
     }));
 
-    return () => {
-      for (const d of disposers) {
-        try {
-          d();
-        } catch {}
+    // ══ 1.7 图书馆 · HTTP 面(2026-10-07)══════════════════════════════════════════════
+    // 九个端点:GET status/search/item/history/checks + POST create/revise/withdraw/check。
+    // 三条纪律(契约 §Integration Response Decisions + 1.7-integration-design §API and tools):
+    //   ① 方法与鉴权都在上面那个 `guard` 里(POST_ONLY / GET_ONLY 两张表)—— 本块**不重判**;
+    //   ② 收下的载荷**先严格校验再动手**:未知/重复 query、未知 body 字段、非对象 body 一律 400,
+    //      绝不"静默剥离"(与存储层"维护拒绝未知只读字段"同一条口径);
+    //   ③ 回执**如实透传**运行时的 canonical `{ok,reason,message}` —— 本层只做三件事:
+    //      选 HTTP 状态码、给 check 补 `adoption_reason`、把不可用/未找到/哈希冲突翻成 503/404/409。
+    //      ⚠️ **不补** `total`(契约:search 回执里没有命中总数,连不可枚举别名都不许有)。
+    const LIB_ITEM_MAX_FALLBACK = 65536;   // = 契约 §Limits 的 itemMaxBytes 默认值
+    /** 只多留一层**信封**余量:`{item}` / `{id,item,expectedHash}` 这些字段名本身的字节。
+     *  为什么不干脆等号:`itemMaxBytes` 是**条目载荷**的闸(存储层自己还会再判一次字节),
+     *  这里限的是**请求体** —— 两者只差一个对象外壳。取 8 KiB 足够任何信封,且不会把
+     *  "体量超限"从 413 放成"进库之后才回 400"(那样调用方拿到的是语义错,不是体量错)。 */
+    const LIB_BODY_ENVELOPE_BYTES = 8192;
+    const libraryBodyMax = () => {
+      const n = library && library.limits && library.limits.itemMaxBytes;
+      return (Number.isFinite(n) && n > 0 ? n : LIB_ITEM_MAX_FALLBACK) + LIB_BODY_ENVELOPE_BYTES;
+    };
+    /** 往响应写字之前的**最后一道闸**(与 `guard` 里 `res.destroyed` 那条同一条纪律):
+     *  客户端断开的路上,响应对象可能已经死了 —— 再 `end()` 就是往死 socket 写。
+     *  `/library/check` 是**唯一**会出现"响应已死但 handler 还在跑"的端点(取源要时间),
+     *  故本块的每一次发送都走这里,而不是直接 `sendJson`。 */
+    const libSend = (res, status, body) => {
+      if (res && (res.writableEnded || res.destroyed)) return;
+      sendJson(res, status, body);
+    };
+    /** 运行时不在场 = 图书馆不可用(**不是**"零命中")—— 契约 §Store Surface 的硬要求。 */
+    const libraryReady = () => !!library && typeof library === 'object';
+    const sendLibraryUnavailable = (res) => libSend(res, 503, {
+      ok: false, reason: 'unavailable',
+      message: '图书馆运行时不可用:插件未注入 library 依赖(其余记忆功能不受影响)。',
+    });
+    /** reason(机器短码)→ HTTP 状态码。**表里没有的一律 400**:语义错由 reason 说,不假装成 5xx。
+     *  · 503:库关着 / 配置关掉 / 运行时不可用(构造失败)—— "服务不可用"三态。
+     *    ⚠️ 运行时(1.7 `library-runtime.js`)自己的短码是**带下划线**的两个:
+     *       `library_unavailable`(打不开库:构造失败/操作抛错)与 `library_disabled`(配置里关了)
+     *       —— 它们必须是 503,不能落到 400(否则"服务不可用"被显示成"你参数写错了")。
+     *       老别名(closed / disabled / unavailable / library-unavailable)一并保留。
+     *  · 404:条目不存在(`not_found`);
+     *  · 409:两处**冲突**——① 修订/撤下的观测哈希与当前内容不符(`hash_mismatch`);
+     *       ② 该条目的同一次核对**正在飞**(`in_flight`)或并发额度用完(`concurrency_limit`)
+     *       —— 都不是参数错,重发/排队才有意义,故与哈希冲突同码;
+     *  · 503(2026-10-12 补):`model_failed` —— 导入通道的**模型段**没跑成(小助手不可达 / 回了
+     *       没法解析的东西 / 全局模型调用抛错)。它**不是**参数错(请求本身完全合法),所以绝不能落
+     *       400 让界面把"小助手没连上"显示成"你参数写错了";正确出路是修好模型来源或换一档重发,
+     *       与上面那三态同属"服务这一趟不可用"。
+     *       ⚠️ **2026-10-14 D11 放行之后,analyze 不再发出这个 reason** —— 模型段失败改成
+     *       `200` + `stats.model_error`(显式标注的降级回执:规则段候选照给)。这条映射**保留**:
+     *       一来别的路径/将来可能再用,二来删了会让"老客户端读到 `model_failed` 该按几号处理"没答案。
+     *  · 400:其余一切(`invalid_*` / `unknown_field` / `readonly_field` / 未知 reason)按语义错。 */
+    const libraryHttpStatus = (reason) => {
+      const r = String(reason || '');
+      if (r === 'closed' || r === 'disabled' || r === 'unavailable' || r === 'library-unavailable'
+        || r === 'library_unavailable' || r === 'library_disabled' || r === 'model_failed'
+        || r === 'sqlite_unavailable') return 503;
+      if (r === 'not_found' || r === 'not-found') return 404;
+      if (r === 'hash_mismatch' || r === 'hash-mismatch' || r === 'in_flight' || r === 'concurrency_limit') return 409;
+      return 400;
+    };
+    /** 如实发回执:ok ⇒ 200;失败 ⇒ 按 reason 选码,**原样**带 reason/message(不吞字段)。 */
+    const sendLibrary = (res, r) => {
+      if (!r || typeof r !== 'object') {
+        return libSend(res, 500, { ok: false, reason: 'internal', message: '图书馆运行时没有返回回执。' });
+      }
+      if (r.ok) return libSend(res, 200, r);
+      return libSend(res, libraryHttpStatus(r.reason), r);
+    };
+    const lib400 = (res, reason, message, extra) => libSend(res, 400, { ok: false, reason, message, ...(extra || {}) });
+    /** 只读面的 query 严格校验:**未知键拒、重复键拒**(都 400,不静默取头一个)。
+     *  为什么重复键也要拒:`URLSearchParams.get()` 只回**头一个** ⇒ `?id=a&id=b` 会被读成 `a`,
+     *  调用方以为发的是 b、账却记在 a 名下。宁可回一个能看见原因的 400。 */
+    const strictQuery = (url, allowed) => {
+      const params = new URL(url || '/', 'http://dsh.internal').searchParams;
+      for (const key of params.keys()) {
+        if (!allowed.includes(key)) return { ok: false, reason: 'unknown-param', param: key };
+      }
+      const out = {};
+      for (const key of allowed) {
+        const all = params.getAll(key);
+        if (all.length > 1) return { ok: false, reason: 'duplicate-param', param: key };
+        if (all.length === 1) out[key] = all[0];
+      }
+      return { ok: true, params: out };
+    };
+    /** 写面的 body 严格校验:有界读(保留熔断)→ JSON 解析失败 400(**不是** 500)→ 必须是对象 →
+     *  未知字段 400。**返回错误而不是抛**:抛出去会被 `guard` 的 catch 兜成 500
+     *  (既有 40 多个端点就是这个形状:`JSON.parse` 一抛,调用方看到的是"服务器内部错误")——
+     *  契约要求这里必须能分辨"载荷不合法"(400)。 */
+    const readLibraryBody = async (req, allowed, max = libraryBodyMax()) => {
+      let text;
+      try {
+        text = await readBody(req, max);
+      } catch (e) {
+        // 体量/静默两条路:**rethrow** ⇒ 落回 `guard` 既有的 413 出口(一处覆盖全部端点)。
+        if (e && e.code === 'BODY_TOO_LARGE') throw e;
+        return { ok: false, reason: 'body-read-failed', message: String((e && e.message) || e) };
+      }
+      let body;
+      try {
+        body = JSON.parse(text || '{}');
+      } catch (e) {
+        return { ok: false, reason: 'bad-json', message: '请求体不是合法 JSON:' + String((e && e.message) || e).slice(0, 120) };
+      }
+      if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return { ok: false, reason: 'bad-body', message: '请求体必须是一个 JSON 对象。' };
+      }
+      const unknown = Object.keys(body).filter((k) => !allowed.includes(k));
+      if (unknown.length) {
+        return { ok: false, reason: 'unknown-field', message: '请求体含未知字段:' + unknown.join(', ') };
+      }
+      return { ok: true, body };
+    };
+    /** 端点外壳:运行时不在场 ⇒ 503;异常 ⇒ 语义错(400)/ 不可用(503)/ 体量(413,rethrow)。 */
+    const libraryRoute = (handler) => async (req, res) => {
+      if (!libraryReady()) return sendLibraryUnavailable(res);
+      try {
+        await handler(req, res);
+      } catch (e) {
+        if (e && e.code === 'BODY_TOO_LARGE') throw e;   // ⇒ guard 的 413 出口(既有约定)
+        if (e && (e.code === 'library-unavailable' || e.code === 'LIBRARY_UNAVAILABLE')) {
+          return sendJson(res, 503, { ok: false, reason: 'unavailable', message: String(e.message || '图书馆不可用') });
+        }
+        sendJson(res, 400, { ok: false, reason: 'bad-request', message: String((e && e.message) || e).slice(0, 200) });
+      }
+    };
+    /** `id` 的**本地**必填判据(只管"在不在、是不是非空字符串" —— 形状判据归存储层)。 */
+    const requireId = (params) => {
+      const id = String((params && params.id != null) ? params.id : '').trim();
+      return id ? { ok: true, id } : { ok: false, reason: 'id-required', message: 'id 必填。' };
+    };
+    /** 分页参数:能当整数就交整数,否则**原样**交出去让运行时自己拒(不在这里悄悄吞掉)。 */
+    const pagingOf = (params) => {
+      const out = {};
+      for (const key of ['offset', 'limit']) {
+        if (params[key] === undefined) continue;
+        out[key] = /^-?\d+$/.test(params[key]) ? Number(params[key]) : params[key];
       }
+      return out;
+    };
+    /** check 回执补 `adoption_reason`(契约:check 响应要能看出"这次证据有没有被采纳")。
+     *  统一三值(与 tools.js 的 library_check **同一份**,两处都只有这几行):
+     *    · `adopted:true` ⇒ `'adopted'`;
+     *    · 有记录但没采纳 ⇒ 取存储层 `recordCheck` 的 reason(实测取值:`stale_or_inactive`);
+     *    · **整条没有记录**(取消 / in_flight / concurrency_limit / not_found)⇒ `'not_recorded'`
+     *      —— 如实说"没留下记录",不替它编具体原因。
+     *  ⚠️ 故意**不**用 `r.reason`:那是**本次核对**的 reason(如 `declared_comparison_mismatch`),
+     *     与"证据有没有被采纳"是两回事 —— 混用会把"哈希陈旧"显示成"比较不符"。
+     *  ⚠️ 运行时自己给了**可用**的值(字符串)就原样保留;给 `null`(`library-runtime.js` 早先的
+     *     `record?.reason ?? null` 形状)视同"没给" ⇒ 仍由本层按上面三步补齐,避免调用方拿到 null。 */
+    const withAdoptionReason = (r) => {
+      if (!r || typeof r !== 'object') return r;
+      if (typeof r.adoption_reason === 'string') return r;   // 运行时已给出采用口径 ⇒ 不覆盖
+      const record = (r.record && typeof r.record === 'object') ? r.record : null;
+      const hasOutcome = r.ok === true || r.record !== undefined || r.recorded !== undefined;
+      if (!hasOutcome) return r;   // 没走到"核对结果"这一步:不硬贴采用口径
+      const adoption_reason = r.adopted === true ? 'adopted' : String((record && record.reason) || 'not_recorded');
+      return { ...r, adoption_reason };
     };
+
+    // ── 五个只读面 ────────────────────────────────────────────────────────────
+    disposers.push(register('/library/status', libraryRoute(async (req, res) => {
+      // `[]` = 这个端点**一个 query 都不收**:status 的回执由运行时自己决定,
+      // 任何 query(尤其 `?enforce=0` / `?id=x` 这类"看着像开关"的键)都不许进来。
+      const q = strictQuery(req.url, []);
+      if (!q.ok) return lib400(res, q.reason, '查询参数 ' + q.param + ' 不被 /library/status 接受。', { param: q.param });
+      sendLibrary(res, await library.status());
+    })));
+
+    disposers.push(register('/library/search', libraryRoute(async (req, res) => {
+      const q = strictQuery(req.url, ['q', 'offset', 'limit']);
+      if (!q.ok) return lib400(res, q.reason, '查询参数 ' + q.param + ' 不被 /library/search 接受。', { param: q.param });
+      const query = {};
+      if (q.params.q !== undefined) query.q = q.params.q;
+      Object.assign(query, pagingOf(q.params));
+      // ⚠️ 不注入 includeInactive:它是**存储层内部**只读扩展(契约 §Integration Response Decisions),
+      //    模型工具与公开检索面都不暴露 —— 这里连"透传"都不做(透传 = 暴露)。
+      sendLibrary(res, await library.search(query));
+    })));
+
+    // 浏览面(只读):**不搜也能翻** —— 按 类目/来源 分组列条目(含留痕行)+ 恒定全量的分组计数表。
+    // 它是读面 ⇒ 进 `GET_ONLY`;query 只收两个分组维度 + 分页(与 /library/search 同款 strictQuery)。
+    disposers.push(register('/library/browse', libraryRoute(async (req, res) => {
+      const q = strictQuery(req.url, ['category', 'source_kind', 'offset', 'limit', 'fields']);
+      if (!q.ok) return lib400(res, q.reason, '查询参数 ' + q.param + ' 不被 /library/browse 接受。', { param: q.param });
+      const query = {};
+      if (q.params.category !== undefined) query.category = q.params.category;
+      if (q.params.source_kind !== undefined) query.source_kind = q.params.source_kind;
+      if (q.params.fields !== undefined) query.fields = q.params.fields;
+      Object.assign(query, pagingOf(q.params));
+      sendLibrary(res, await library.browse(query));
+    })));
+
+    disposers.push(register('/library/item', libraryRoute(async (req, res) => {
+      const q = strictQuery(req.url, ['id']);
+      if (!q.ok) return lib400(res, q.reason, '查询参数 ' + q.param + ' 不被 /library/item 接受。', { param: q.param });
+      const id = requireId(q.params);
+      if (!id.ok) return lib400(res, id.reason, id.message);
+      sendLibrary(res, await library.get(id.id));
+    })));
+
+    disposers.push(register('/library/history', libraryRoute(async (req, res) => {
+      const q = strictQuery(req.url, ['id', 'offset', 'limit']);
+      if (!q.ok) return lib400(res, q.reason, '查询参数 ' + q.param + ' 不被 /library/history 接受。', { param: q.param });
+      const id = requireId(q.params);
+      if (!id.ok) return lib400(res, id.reason, id.message);
+      sendLibrary(res, await library.history(id.id, pagingOf(q.params)));
+    })));
+
+    disposers.push(register('/library/checks', libraryRoute(async (req, res) => {
+      const q = strictQuery(req.url, ['id', 'offset', 'limit']);
+      if (!q.ok) return lib400(res, q.reason, '查询参数 ' + q.param + ' 不被 /library/checks 接受。', { param: q.param });
+      const id = requireId(q.params);
+      if (!id.ok) return lib400(res, id.reason, id.message);
+      sendLibrary(res, await library.checks(id.id, pagingOf(q.params)));
+    })));
+
+    // ── 四个写面(载荷逐一严格校验;不接 `gateSurgery` —— 图书馆不是人格/规矩面)──
+    /** 写面的 query 必须**严格为空**:载荷只走请求体。
+     *  为什么连"看着无害的" query 都拒:`URLSearchParams` 取的是**头一个**同名键 ⇒ 一旦将来某个
+     *  handler 顺手读了 query,`?id=a&id=b` 就会变成"调用方以为发的是 body、实际生效的是 query"
+     *  这种账实不符;而且 query 还能绕开"body 字段白名单"的检查面。判据复用只读面那份 `strictQuery`,
+     *  只是 allowed 恒为 `[]`(未知键拒、重复键拒,一律 400)。 */
+    const writeQueryGuarded = (req, res, route) => {
+      const q = strictQuery(req.url, []);
+      if (q.ok) return false;
+      lib400(res, q.reason, '写面 ' + route + ' 不接受 query 参数(' + q.reason + ':' + q.param + ');载荷请走请求体。', { param: q.param });
+      return true;
+    };
+    disposers.push(register('/library/create', libraryRoute(async (req, res) => {
+      if (writeQueryGuarded(req, res, '/library/create')) return;
+      const b = await readLibraryBody(req, ['item']);
+      if (!b.ok) return lib400(res, b.reason, b.message);
+      const item = b.body.item;
+      if (!item || typeof item !== 'object' || Array.isArray(item)) {
+        return lib400(res, 'invalid_item', 'item 必须是条目对象。');
+      }
+      sendLibrary(res, await library.create(item));
+    })));
+
+    disposers.push(register('/library/revise', libraryRoute(async (req, res) => {
+      if (writeQueryGuarded(req, res, '/library/revise')) return;
+      const b = await readLibraryBody(req, ['id', 'item', 'expectedHash']);
+      if (!b.ok) return lib400(res, b.reason, b.message);
+      const id = String(b.body.id ?? '').trim();
+      if (!id) return lib400(res, 'id-required', 'id 必填。');
+      const item = b.body.item;
+      if (!item || typeof item !== 'object' || Array.isArray(item)) return lib400(res, 'invalid_item', 'item 必须是条目对象。');
+      if (typeof b.body.expectedHash !== 'string' || !b.body.expectedHash.trim()) {
+        return lib400(res, 'hash-required', 'expectedHash 必填(修订必须带观测到的 content_hash)。');
+      }
+      sendLibrary(res, await library.revise(id, item, b.body.expectedHash));
+    })));
+
+    disposers.push(register('/library/withdraw', libraryRoute(async (req, res) => {
+      if (writeQueryGuarded(req, res, '/library/withdraw')) return;
+      const b = await readLibraryBody(req, ['id', 'reason', 'expectedHash']);
+      if (!b.ok) return lib400(res, b.reason, b.message);
+      const id = String(b.body.id ?? '').trim();
+      if (!id) return lib400(res, 'id-required', 'id 必填。');
+      const reason = String(b.body.reason ?? '').trim();
+      if (!reason) return lib400(res, 'reason-required', 'reason 必填(撤下要留痕)。');
+      if (typeof b.body.expectedHash !== 'string' || !b.body.expectedHash.trim()) {
+        return lib400(res, 'hash-required', 'expectedHash 必填(撤下必须带观测到的 content_hash)。');
+      }
+      sendLibrary(res, await library.withdraw(id, reason, b.body.expectedHash));
+    })));
+
+    // check 是**唯一**的长活端点:它可能要取源(网络/磁盘)。两条取消来源都要接:
+    //   ① HTTP 客户端断开(`req.aborted` / `res.close`);② 插件卸载(disposer,见下面的 return)。
+    //   `AbortController` 由**本条请求**拥有;`finally` 里**必拆监听** —— 不拆的话 close 监听会
+    //   一直挂在已结束的响应上(长跑进程里就是稳定泄漏)。
+    //   ⚠️ signal 的 reason 必须带 `cancelled:true`:checker 按这个标记区分"被取消"(不写库)
+    //      与"取源失败"(写一条 unknown 留痕)—— 见 library-checker.js 的 signal.reason?.cancelled。
+    disposers.push(register('/library/check', libraryRoute(async (req, res) => {
+      if (writeQueryGuarded(req, res, '/library/check')) return;
+      const b = await readLibraryBody(req, ['id']);
+      if (!b.ok) return lib400(res, b.reason, b.message);
+      const id = String(b.body.id ?? '').trim();
+      if (!id) return lib400(res, 'id-required', 'id 必填。');
+      const controller = new AbortController();
+      const onDisconnect = () => {
+        if (controller.signal.aborted) return;
+        const err = new Error('客户端已断开,本次核对被取消(不写核对留痕)。');
+        err.code = 'client-disconnected';
+        err.cancelled = true;
+        controller.abort(err);
+      };
+      pendingLibraryChecks.add(controller);
+      req.on?.('aborted', onDisconnect);
+      res.on?.('close', onDisconnect);
+      try {
+        sendLibrary(res, withAdoptionReason(await library.check(id, { signal: controller.signal })));
+      } finally {
+        req.off?.('aborted', onDisconnect);
+        res.off?.('close', onDisconnect);
+        pendingLibraryChecks.delete(controller);
+      }
+    })));
+
+    // ── 1.7 图书馆 · **导入通道**(2026-10-10;契约 §3,两阶段)────────────────────────
+    /** 两条导入路由**各有各的读体上限**(不复用 itemMaxBytes 那把尺):
+     *  · `analyze` 收的是**整份源文本** ⇒ 尺 = `importTextMaxBytes`(默认 1 MiB);
+     *  · `commit` 收的是**人审后的整批** ⇒ 尺 = `importBatchMaxBytes`(默认 3 MiB)。
+     *  为什么必须分开:`readBody` 的闸在 **handler 之前** —— 用 itemMaxBytes(64 KiB)那把尺读,
+     *  一份合法的 1 MiB 表格会在还没人看它一眼时就被 413 顶回去(而且错误说的是"条目太大",
+     *  与真实原因不符)。信封与其余图书馆端点同一份(+8 KiB 给 JSON 封套与转义余量)。
+     *  ⚠️ 读体上限 ≠ 语义上限:超了读体 ⇒ **413**(transport);批内条数/字节超 `importBatchMaxItems`
+     *     ⇒ 由 `commitImport` 回 `batch_too_large`,**400**(语义错,重发同样内容没用)。 */
+    const libraryImportBodyMax = (key, fallback) => {
+      const n = library && library.limits && library.limits[key];
+      return (Number.isFinite(n) && n > 0 ? n : fallback) + LIB_BODY_ENVELOPE_BYTES;
+    };
+
+    disposers.push(register('/library/import/analyze', libraryRoute(async (req, res) => {
+      if (writeQueryGuarded(req, res, '/library/import/analyze')) return;
+      const b = await readLibraryBody(req,
+        ['kind', 'name', 'text', 'path', 'table', 'category', 'source_kind', 'as_of', 'model', 'offset'],
+        libraryImportBodyMax('importTextMaxBytes', 1048576));
+      if (!b.ok) return lib400(res, b.reason, b.message);
+      const input = {
+        kind: b.body.kind, name: b.body.name,
+        text: b.body.text === undefined || b.body.text === null ? '' : b.body.text,
+      };
+      // SQLite 通道(路 A,D14):源在盘上 ⇒ 入参是 `path`(+`table`),不是 text。
+      // ⚠️ 这两把只对 kind=sqlite 有意义:别的通道带上它 ⇒ **当场 400**,不静默丢
+      //   (静默丢参数正是复核 §11.6 A.3 点名的那条坑)。
+      for (const key of ['path', 'table']) {
+        const value = b.body[key];
+        if (value === undefined || value === null || value === '') continue;
+        if (typeof value !== 'string') {
+          return lib400(res, `${key}-invalid`, `${key} 必须是字符串(实际 ${JSON.stringify(value)})`);
+        }
+        if (String(b.body.kind ?? '').trim() !== 'sqlite') {
+          return lib400(res, 'param-not-applicable', `${key} 只对 kind=sqlite 有意义(kind=${JSON.stringify(b.body.kind)})`);
+        }
+        input[key] = value;
+      }
+      // 默认值走 opts(与 §4 的"面板给今天作默认、但可改"一致):不给就由 analyzeImport 用自己的默认。
+      const opts = {};
+      for (const [from, to] of [['category', 'category'], ['source_kind', 'source_kind'], ['as_of', 'today']]) {
+        if (typeof b.body[from] === 'string' && b.body[from].trim() !== '') opts[to] = b.body[from].trim();
+      }
+      // 分段/翻页(D12):`offset` = 从第几个内容单元开始(CSV 一行 / 文本一段)。
+      // ⚠️ 值非法 ⇒ **当场 400**,不静默当 0 —— 把"你要的第 2 页"悄悄换成第 1 页是最坏的一种回执。
+      if (b.body.offset !== undefined && b.body.offset !== null) {
+        const off = typeof b.body.offset === 'number' ? b.body.offset : NaN;
+        if (!Number.isInteger(off) || off < 0) {
+          return lib400(res, 'offset-invalid', `offset 必须是 >= 0 的整数(实际 ${JSON.stringify(b.body.offset)})`);
+        }
+        if (off > 0) opts.offset = off;
+      }
+      // 模型段(2026-10-12,契约 §11.1):引擎名 ∈ IMPORT_ENGINES,两档复用**既有**调用路径:
+      //   `assistant` = 本机小助手(零成本) / `global` = 当前全局大模型(会花额度)。
+      // ⚠️ **不给 `model` 就是不调模型**:只走规则段 —— 默认不烧额度、不让人等(显式才花)。
+      // ⚠️ 值不合法 ⇒ **当场 400**,不静默回落成"没选模型"(那会让调用方以为自己在用小助手)。
+      const engine = typeof b.body.model === 'string' ? b.body.model.trim() : '';
+      if (engine !== '') {
+        if (!IMPORT_ENGINES.includes(engine)) {
+          return lib400(res, 'model-invalid', `model 只能是 ${IMPORT_ENGINES.join(' / ')}(实际 ${engine})`);
+        }
+        const built = makeImportModelHook({ engine, ctx, settings });
+        opts.model = built.hook;
+        opts.modelLabel = built.label;   // 回执如实写明"这一趟是哪个模型跑的"(契约 §3)
+      }
+      sendLibrary(res, await library.analyzeImport(input, opts));
+    })));
+
+    disposers.push(register('/library/import/commit', libraryRoute(async (req, res) => {
+      if (writeQueryGuarded(req, res, '/library/import/commit')) return;
+      const b = await readLibraryBody(req, ['source_hash', 'items'],
+        libraryImportBodyMax('importBatchMaxBytes', 3145728));
+      if (!b.ok) return lib400(res, b.reason, b.message);
+      // 两处**本地**必填判据(只管"在不在、是不是数组")—— 形状与限额判据归导入层,两套**不合并**。
+      if (typeof b.body.source_hash !== 'string' || b.body.source_hash.trim() === '') {
+        return lib400(res, 'hash-required', 'source_hash 必填(幂等键的前半截由它定)。');
+      }
+      if (!Array.isArray(b.body.items)) return lib400(res, 'items-required', 'items 必须是数组。');
+      sendLibrary(res, await library.commitImport({ source_hash: b.body.source_hash, items: b.body.items }));
+    })));
+
+    return releaseRoutes;
+    } catch (error) {
+      releaseRoutes();
+      throw error;
+    }
   };
 
   const reqSessionId = (url) => {
@@ -3163,32 +3718,28 @@ export function registerApi(ctx, deps, config) {
     return q.get('sessionId') || q.get('sid') || null;
   };
 
-  tryMount();
-  if (!disposeRoutes) {
-    // 服务启动顺序兜底:每 3s 重试,成功或插件卸载即停
-    timer = setInterval(() => {
-      if (disposed || disposeRoutes) {
-        clearInterval(timer);
-        timer = null;
-        return;
-      }
-      tryMount();
-    }, 3000);
-  }
-
-  return () => {
-    disposed = true;
-    if (timer) {
-      clearInterval(timer);
-      timer = null;
-    }
-    if (disposeRoutes) {
-      try {
-        disposeRoutes();
-      } catch {}
-      disposeRoutes = null;
+  try {
+    tryMount();
+    if (!disposeRoutes) {
+      // 服务启动顺序兜底:每 3s 重试,成功或插件卸载即停
+      timer = setInterval(() => {
+        if (disposed || disposeRoutes) {
+          clearInterval(timer);
+          timer = null;
+          return;
+        }
+        try { tryMount(); }
+        catch (error) {
+          cleanup();
+          console.error('[dsh-ling] delayed API mount failed', error);
+        }
+      }, 3000);
     }
-  };
+    return cleanup;
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
 }
 
 function allSnapshotSessionIds(gate) {