dsh-session-index-lau 2.4.1 → 2.5.2

package/server.mjs

@@ -26,9 +26,10 @@ import { loadNotes, saveNotes, addNote, queryNotes, removeNote, noteChunks, note
 import { expandQuery, matchesQuery, rankCandidates, rrfMerge, makeSnippet } from './lib/semantic.mjs';
 import { embeddingConfig, syncVectors, vectorRank, cardChunks, vectorStats } from './lib/embedding.mjs';
 import { pack, packAll, listPacks } from './lib/pack.mjs';
+import { stageConfig, buildStageDocument, stageToken, bridgeOverview, findDuplicate, postStage, StageError } from './lib/stage.mjs';
 
 const { sessionsRoot, indexDir, workbuddyProjectsDir } = defaultPaths();
-const VERSION = '2.4.1';
+const VERSION = '2.5.2';
 const SUPPORTED_PROTOCOLS = new Set(['2024-11-05', '2025-03-26', '2025-06-18']);
 const log = (...parts) => process.stderr.write(`[dsh-session-index-lau] ${parts.join(' ')}\n`);
 
@@ -557,6 +558,130 @@ async function toolRefresh(args = {}) {
   }
 }
 
+/**
+ * 控制器：会话整理文档 → 思源桥待入库队列。
+ * 只负责解析参数、组装源数据、格式化响应；渲染与 HTTP 都在 lib/stage.mjs。
+ * 两步确认：不带 confirmToken 一律只预览，带对 token 才投递；永不写库。
+ */
+async function toolStage(args = {}) {
+  const cfg = stageConfig();
+  if (!cfg.enabled) {
+    return { ok: false, code: 'STAGE_DISABLED', error: '暂存投递已被关闭', hint: '设置 SESSION_INDEX_STAGE=1 后重启 MCP 服务' };
+  }
+  const asError = (err) => (err instanceof StageError ? err.toJSON()
+    : { ok: false, code: 'STAGE_FAILED', error: String(err.message || err) });
+
+  if (args.status === true) {
+    try {
+      return await bridgeOverview(cfg);
+    } catch (err) {
+      return asError(err);
+    }
+  }
+
+  const template = ['brief', 'decisions', 'detail'].includes(args.template) ? args.template : 'brief';
+  const app = args.app || 'all';
+  const query = typeof args.query === 'string' ? args.query.trim() : '';
+  const workspace = typeof args.workspace === 'string' ? args.workspace.trim() : '';
+  const limit = clamp(args.limit, 1, 20, 8);
+  const maxChars = clamp(args.maxChars, 1000, 30000, 12000);
+  const ids = Array.isArray(args.sessionIds) ? args.sessionIds.filter((x) => typeof x === 'string' && x.trim()) : [];
+
+  // 源数据：指定会话时直接取卡片，否则用 brief 的最近/主题聚合
+  let sessions;
+  let memories;
+  if (ids.length) {
+    const cards = Object.values(freshCards().cards || {});
+    const picked = cards.filter((c) => ids.some((p) => String(c.id || '').startsWith(p))).slice(0, 20);
+    sessions = picked.map((c) => ({
+      id: c.id, app: appOf(c), title: c.title, updatedAt: c.updatedAt, digest: c.digest,
+      decisions: (c.decisions || []).slice(0, 3), questions: (c.questions || []).slice(0, 1),
+      keywords: (c.keywords || []).slice(0, 6),
+    }));
+    memories = queryNotes(freshNotes(), { query, limit: 5 })
+      .map((r) => ({ type: r.note.type, text: String(r.note.text).slice(0, 200), importance: r.note.importance }));
+  } else {
+    const brief = toolBrief({ query, app, workspace, limit, maxChars, includeMemory: true });
+    sessions = brief.sessions || [];
+    memories = brief.memories || [];
+  }
+  if (args.since || args.until) {
+    const since = Number(args.since) || 0;
+    const until = Number(args.until) || Infinity;
+    sessions = sessions.filter((s) => (s.updatedAt || 0) >= since && (s.updatedAt || 0) <= until);
+  }
+
+  let hits = [];
+  if (template === 'detail' && (query || ids.length)) {
+    try {
+      const sr = query ? await toolSearch({ query, app, workspace, mode: 'semantic', limit: 8, contextChars: 260 }) : null;
+      hits = (sr?.results || []).map((r) => ({
+        title: r.title, sessionId: r.sessionId, app: r.app, seq: r.seq,
+        snippet: r.snippet || r.text || '',
+      }));
+    } catch (err) {
+      log('stage detail 片段检索降级: ' + err.message);
+    }
+  }
+
+  const payloadOpts = {
+    notebook: args.notebook || cfg.defaultNotebook,
+    hpath: args.hpath || cfg.defaultHpath,
+    note: typeof args.note === 'string' ? args.note : '',
+    template,
+  };
+  let doc;
+  try {
+    doc = buildStageDocument({ sessions, memories, hits }, {
+      ...payloadOpts, query, title: typeof args.title === 'string' ? args.title : '', app,
+    });
+  } catch (err) {
+    return asError(err);
+  }
+  const token = stageToken(doc, payloadOpts);
+
+  // 第一步：只预览，绝不产生任何写操作
+  if (!args.confirmToken) {
+    return {
+      ok: true, dryRun: true, staged: false, token,
+      title: doc.title, chars: doc.chars, template,
+      sessions: sessions.length, memories: memories.length, hits: hits.length,
+      target: { service: cfg.url, notebook: payloadOpts.notebook, hpath: payloadOpts.hpath },
+      preview: doc.markdown.slice(0, 1200),
+      previewTruncated: doc.markdown.length > 1200,
+      confirmWith: {
+        query, app, workspace, template, title: doc.title, sessionIds: ids.length ? ids : undefined,
+        since: args.since, until: args.until, limit, maxChars,
+        notebook: args.notebook, hpath: args.hpath, note: args.note, confirmToken: token,
+      },
+      hint: '仅预览，未投递。确认无误后把 confirmWith 原样作为本工具参数再调一次；本工具永远不会自动写入思源笔记库',
+    };
+  }
+
+  // 第二步：令牌必须匹配（防止预览 A、投递 B）
+  if (String(args.confirmToken) !== token) {
+    return {
+      ok: false, code: 'TOKEN_MISMATCH', staged: false,
+      error: '确认令牌与当前内容不一致，已拒绝投递',
+      hint: '索引可能刚更新或参数被改动。请重新预览，并原样带回新的 confirmWith',
+    };
+  }
+
+  try {
+    const dup = await findDuplicate(cfg, doc);
+    if (dup) {
+      return {
+        ok: true, staged: false, alreadyQueued: true, id: dup.id, title: doc.title, chars: doc.chars,
+        hint: '待入库队列里已有同标题同字数的稿，未重复投递',
+      };
+    }
+    const result = await postStage(cfg, doc, payloadOpts);
+    return { ...result, token, sessions: sessions.length, template, duplicateChecked: true };
+  } catch (err) {
+    return asError(err);
+  }
+}
+
 const HANDLERS = {
   session_index_status: toolStatus,
   session_index_brief: toolBrief,
@@ -571,6 +696,7 @@ const HANDLERS = {
   session_index_package: toolPackage,
   session_index_vectors: toolVectors,
   session_index_refresh: toolRefresh,
+  session_index_stage: toolStage,
 };
 
 // ---------------------------------------------------------------- MCP 声明与自描述
@@ -589,6 +715,8 @@ const GUIDE_TEXT = `# dsh-session-index-lau 使用说明
 - 沉淀结论：session_index_remember；召回：session_index_recall；归档：session_index_forget。
 - 打包分发：session_index_package（plugin / skill / all，自动生成 zip）。
 - 查看索引与自动维护状态：session_index_status（autoIndex.watch 可看事件监听状态）。
+- 会话整理成文档送进思源：session_index_stage（两步确认，只投递到「待入库」）。
+- 探测思源桥服务与队列：session_index_stage {status:true}（只读）。
 
 ## 铁律
 1. 逐级放大：brief → related/thread → search(片段) → get(原文)。
@@ -610,6 +738,7 @@ const INSTRUCTIONS = [
   '会话开始或用户提到「之前/上次/继续/记得」时，先调 session_index_brief 接上跨会话结论与长期记忆。',
   '找具体报错或命令用 session_index_search（默认语义检索，只返回片段）；看完整原文用 session_index_get 传 seqs。',
   '有新结论时用 session_index_remember 沉淀；需要分发时用 session_index_package 自动打包。',
+  '要把会话整理成文档送进思源笔记时，用 session_index_stage：先不带 confirmToken 预览，用户确认后原样回传 confirmWith 才投递到「待入库」；绝不自动写库。',
   '完整说明见资源 session-index://guide，不要直接读取 .zstd 源会话文件。',
 ].join(' ');
 
@@ -627,6 +756,7 @@ const TOOLS = [
   { name: 'session_index_package', description: '【自动打包】无需手工压缩，一键生成可分发 zip。mode=plugin 打完整插件包，skill 打技能包（可直接导入 DSH 技能管理器），all 两种都打，status 查看已生成包。包内自动附 MANIFEST.json 与 INSTALL.md，且排除所有会话数据/索引/密钥。', inputSchema: { type: 'object', properties: { mode: { type: 'string', description: 'plugin / skill / all(默认) / status' } }, additionalProperties: false } },
   { name: 'session_index_vectors', description: '【可选向量层】查看/同步/查询向量缓存。未配置 SESSION_INDEX_EMBED_* 时本地语义检索照常工作且零成本。', inputSchema: { type: 'object', properties: { action: { type: 'string', description: 'status/sync/search' }, query: { type: 'string' }, limit: { type: 'number' } }, additionalProperties: false } },
   { name: 'session_index_refresh', description: '手动立即刷新索引。注意：新会话已由文件事件自动识别，通常无需调用；仅改抽取规则或需即时生效时用。', inputSchema: { type: 'object', properties: { force: { type: 'boolean' } }, additionalProperties: false } },
+  { name: 'session_index_stage', description: '【会话整理 → 思源桥待入库】把会话卡/结论/检索片段整理成 Markdown 文档。两步确认：不带 confirmToken 只返回预览与令牌，原样回传 confirmWith 才投递到思源桥 /api/stage；绝不自动写入思源笔记库。支持指定会话、主题、模板、落点与去重。status=true 只读探测服务与队列。', inputSchema: { type: 'object', properties: { status: { type: 'boolean', description: '只读：探测思源桥服务与待入库队列' }, query: { type: 'string', description: '主题词，按主题聚合会话' }, sessionIds: { type: 'array', items: { type: 'string' }, description: '指定会话 id（支持前缀），不传则按最近/主题取' }, app: { type: 'string', description: 'dsh / workbuddy / all' }, workspace: { type: 'string' }, since: { type: 'number' }, until: { type: 'number' }, template: { type: 'string', description: 'brief(默认) / decisions / detail' }, title: { type: 'string', description: '自定义文档标题；确认时请回传预览给出的 title' }, notebook: { type: 'string' }, hpath: { type: 'string', description: '目标目录，默认 /会话札记/思源' }, note: { type: 'string' }, limit: { type: 'number' }, maxChars: { type: 'number' }, confirmToken: { type: 'string', description: '预览返回的令牌；带上且匹配才真正投递' } }, additionalProperties: false } },
 ];
 
 const PROMPTS = [

package/smoke.mjs

@@ -7,17 +7,53 @@
  * 测试写入的记忆会在结尾物理清除，不污染真实记忆库。
  */
 import { spawn } from 'node:child_process';
+import http from 'node:http';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { inspectZip } from './lib/pack.mjs';
 
+// 本地假思源桥：完整实现 status / stage / autostage 三个只读端点与 POST /api/stage，
+// 用来验证两步确认与去重，绝不碰 5599 上真实的「待入库」队列。
+const stagePosts = [];
+const stagedItems = [];
+const mockBridge = http.createServer((req, res) => {
+  const send = (code, obj) => {
+    res.writeHead(code, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(obj));
+  };
+  const u = new URL(req.url, 'http://127.0.0.1');
+  if (req.method === 'GET' && u.pathname === '/api/status') return send(200, { kernel: '3.8.9', staged: stagedItems.length, notebooks: [] });
+  if (req.method === 'GET' && u.pathname === '/api/stage') return send(200, { items: stagedItems, discarded: 0 });
+  if (req.method === 'GET' && u.pathname === '/api/autostage') return send(200, { enabled: true, dir: 'D:/mock/session-docs', hpath: '/会话札记/思源', files: [] });
+  if (req.method === 'POST' && u.pathname === '/api/stage') {
+    let raw = '';
+    req.on('data', (c) => { raw += c; });
+    req.on('end', () => {
+      const p = JSON.parse(raw || '{}');
+      stagePosts.push(p);
+      const item = { id: '20261114140000-abcdef', title: p.title, chars: String(p.markdown || '').length, hpath: p.hpath, notebook: p.notebook, note: p.note };
+      stagedItems.push(item);
+      send(200, { id: item.id, title: item.title, chars: item.chars, staged: true });
+    });
+    return;
+  }
+  if (u.pathname.includes('/commit')) {
+    stagePosts.push({ __forbidden: 'commit' });
+    return send(200, {});
+  }
+  return send(404, { error: 'not found' });
+});
+await new Promise((r) => mockBridge.listen(0, '127.0.0.1', r));
+const stageUrl = `http://127.0.0.1:${mockBridge.address().port}`;
+
 const here = path.dirname(fileURLToPath(import.meta.url));
 const child = spawn(process.execPath, [path.join(here, 'server.mjs')], {
   cwd: here,
   stdio: ['pipe', 'pipe', 'pipe'],
   env: {
     ...process.env,
+    SIYUAN_BRIDGE_URL: stageUrl,
     SESSION_INDEX_WATCH_DEBOUNCE_MS: '60000',
     SESSION_INDEX_AUTO_INTERVAL_MS: '3600000',
   },
@@ -92,16 +128,16 @@ try {
   const init = await request('initialize', {
     protocolVersion: '2024-11-05',
     capabilities: {},
-    clientInfo: { name: 'smoke-test', version: '2.4.1' },
+    clientInfo: { name: 'smoke-test', version: '2.5.2' },
   });
-  check('initialize 握手与能力声明', init.result?.serverInfo?.version === '2.4.1' && Boolean(init.result?.capabilities?.prompts) && Boolean(init.result?.capabilities?.resources), init.result?.serverInfo?.version);
+  check('initialize 握手与能力声明', init.result?.serverInfo?.version === '2.5.2' && Boolean(init.result?.capabilities?.prompts) && Boolean(init.result?.capabilities?.resources), init.result?.serverInfo?.version);
   check('initialize 返回自描述 instructions', (init.result?.instructions || '').includes('session_index_brief'));
   check('声明 listChanged 通知能力', init.result?.capabilities?.resources?.listChanged === true && init.result?.capabilities?.prompts?.listChanged === true);
   notify('notifications/initialized');
 
   const listed = await request('tools/list');
   const names = (listed.result?.tools || []).map((t) => t.name);
-  check('tools/list 返回 13 个工具', names.length === 13 && names.includes('session_index_package'), `${names.length} 个`);
+  check('tools/list 返回 14 个工具', names.length === 14 && names.includes('session_index_stage'), `${names.length} 个`);
   check('ping', (await request('ping')).result !== undefined);
 
   // 自动索引守护 + 文件事件监听
@@ -215,7 +251,7 @@ try {
     check(`resources/read ${uri.split('//')[1]}`, (r.result?.contents?.[0]?.text || '').length > 10);
   }
   const pluginJson = JSON.parse((await request('resources/read', { uri: 'session-index://plugin.json' })).result.contents[0].text);
-  check('插件清单机器可读', pluginJson.mcp?.toolCount === 13 && pluginJson.automatic?.watchNewSessions === true, `v${pluginJson.version}`);
+  check('插件清单机器可读', pluginJson.mcp?.toolCount === 14 && pluginJson.automatic?.watchNewSessions === true, `v${pluginJson.version}`);
   const cardUri = await request('resources/read', { uri: `session-index://card/${firstId.slice(0, 12)}` });
   check('resources/read 单会话卡模板', (cardUri.result?.contents?.[0]?.text || '').includes('"id"'));
 
@@ -225,6 +261,32 @@ try {
   const refreshed = await payload(await call('session_index_refresh', { force: false }));
   check('refresh 手动刷新仍可用', refreshed.ok === true && refreshed.cardsIndexed > 0);
   check('refresh 返回自动维护状态', Boolean(refreshed.autoIndex));
+  // ---- 会话整理 → 思源桥待入库（本地假服务，全程不碰真实 5599 队列）
+  const ov = await payload(await call('session_index_stage', { status: true }));
+  check('stage 只读探测服务与队列', ov.ok === true && ov.kernel === '3.8.9' && ov.queued === 0, JSON.stringify({ kernel: ov.kernel, queued: ov.queued }));
+  check('stage 探测返回自动接入目录', ov.autoStageDir === 'D:/mock/session-docs' && ov.autoStageEnabled === true);
+  check('stage 探测不产生写入', stagePosts.length === 0);
+
+  const prev = await payload(await call('session_index_stage', { query: '插件', template: 'brief', limit: 3 }));
+  check('stage 默认只预览不投递', prev.dryRun === true && prev.staged === false && typeof prev.token === 'string' && stagePosts.length === 0, prev.code || prev.error || '');
+  check('stage 预览含 Markdown 与落点', String(prev.preview || '').includes('# 会话整理') && prev.target?.hpath === '/会话札记/思源');
+  check('stage 预览给出可回传的 confirmWith', prev.confirmWith?.confirmToken === prev.token && typeof prev.confirmWith?.title === 'string');
+
+  const bad = await payload(await call('session_index_stage', { ...prev.confirmWith, confirmToken: 'deadbeef' }));
+  check('stage 错误令牌被拒绝', bad.ok === false && bad.code === 'TOKEN_MISMATCH' && bad.staged === false, bad.code || '');
+  check('stage 拒绝后仍无写入', stagePosts.length === 0);
+
+  const posted = await payload(await call('session_index_stage', prev.confirmWith));
+  check('stage 确认后投递成功', posted.ok === true && posted.staged === true && posted.id === '20261114140000-abcdef' && stagePosts.length === 1, posted.code || posted.error || '');
+  check('stage 投递体含标题与 Markdown', typeof stagePosts[0]?.title === 'string' && String(stagePosts[0]?.markdown || '').includes('# 会话整理'));
+  check('stage 文档声明未写入笔记库', /未写入笔记库/.test(String(stagePosts[0]?.markdown || '')));
+  check('stage 绝不调用 commit', stagePosts.every((p) => !p.__forbidden));
+
+  const dup = await payload(await call('session_index_stage', prev.confirmWith));
+  check('stage 重复投递被去重', dup.alreadyQueued === true && dup.staged === false && stagePosts.length === 1, dup.code || '');
+  const dec = await payload(await call('session_index_stage', { template: 'decisions', limit: 2 }));
+  check('stage decisions 模板可用', dec.dryRun === true && dec.chars > 0);
+
   check('空 query 被规范化拒绝', (await call('session_index_search', { query: '' })).result?.isError === true);
   check('通知通道可用（声明级）', Array.isArray(notifications), `收到 ${notifications.length} 条通知`);
 } catch (err) {
@@ -239,6 +301,7 @@ try {
   }
   child.stdin.end();
   child.kill();
+  mockBridge.close();
 }
 
 const failed = results.filter((r) => !r.ok).length;

package/tools/push-doc.mjs

@@ -0,0 +1,335 @@
+/**
+ * 把任意文档（Markdown / HTML）推送到思源桥「待入库」队列。
+ *
+ * 三种用法：
+ *   node tools/push-doc.mjs                              单文件预览（默认《操作使用手册.html》）
+ *   node tools/push-doc.mjs --file README.md --send     推送任意单个文档
+ *   node tools/push-doc.mjs --from-workbuddy            批量：列出 WorkBuddy 会话文档（只读）
+ *   node tools/push-doc.mjs --from-workbuddy --send     批量：全部投递到待入库
+ *   node tools/push-doc.mjs --from-workbuddy --seed     批量：把当前文档记为「已推送」（不投递）
+ *
+ * 批量数据源：~/.workbuddy/artifact-index/<会话id>.json 的 contentType=document 条目。
+ * 默认排除临时验证目录/依赖目录/旧开发副本，按内容哈希去重，避免把同一份 README
+ * 推十几遍。用 --no-exclude 关闭排除，--source 按生成方式收窄，--limit 设上限。
+ *
+ * 判重（对齐思源桥 autoStage 的 .auto-staged.json）：状态文件按「文档路径 + 内容哈希」
+ * 持久化记录已推送过的文档，**不依赖队列当前状态**。所以在思源桥里「丢弃」某篇后，
+ * 下次自动化不会把它重新推送回来；只有内容真的变了才会作为新版本再投一次。
+ * --force 可绕过状态与队列检查；--seed 用于首次启用时把历史文档补进状态基线。
+ *
+ * 可控点：默认 dry-run；--send 才入队；**永远不调用 /api/stage/commit**，
+ *         写入思源笔记库由人在界面确认。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const argv = process.argv.slice(2);
+const arg = (name, fallback) => {
+  const i = argv.indexOf(name);
+  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : fallback;
+};
+const has = (...names) => names.some((n) => argv.includes(n));
+const SEND = has('--send');
+const SEED = has('--seed');
+const BATCH = has('--from-workbuddy');
+const NO_EXCLUDE = has('--no-exclude');
+const FORCE = has('--force');
+const LIMIT = Math.max(1, Math.min(500, Number(arg('--limit', 60)) || 60));
+const SOURCE = arg('--source', '');
+const SINCE = Number(arg('--since', 0)) || 0;
+const FILE = path.resolve(ROOT, arg('--file', '操作使用手册.html'));
+const BRIDGE = (process.env.SIYUAN_BRIDGE_URL || `http://127.0.0.1:${process.env.SIYUAN_BRIDGE_PORT || 5599}`).replace(/\/+$/, '');
+const VERSION = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
+const HPATH = arg('--hpath', process.env.SESSION_INDEX_STAGE_HPATH || '/会话札记/思源');
+const NOTEBOOK = arg('--notebook', '思源桥');
+const TITLE_OVERRIDE = arg('--title', '');
+const OUT_DIR = path.join(ROOT, 'dist');
+// 和思源桥 .auto-staged.json 同类的持久化状态：判重只看这里，不看队列里还在不在
+const STATE_FILE = process.env.PUSH_DOC_STATE
+  || path.join(process.env.SESSION_INDEX_DIR || path.join(os.homedir(), '.dsh', 'session-index'), 'push-doc-state.json');
+
+function loadState() {
+  try {
+    const j = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+    if (j && typeof j.pushed === 'object' && j.pushed) return j;
+  } catch {
+    // 首次运行或文件损坏，按空状态处理
+  }
+  return { version: 1, pushed: {} };
+}
+
+function saveState(state) {
+  state.version = 1;
+  state.updatedAt = new Date().toISOString();
+  fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+  const tmp = `${STATE_FILE}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+  // Windows 上目标被另一进程短暂占用时 rename 会 EPERM，做短退避
+  let last;
+  for (const delay of [0, 40, 120, 300]) {
+    if (delay) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
+    try {
+      fs.renameSync(tmp, STATE_FILE);
+      return;
+    } catch (err) {
+      last = err;
+      if (!['EPERM', 'EACCES', 'EBUSY'].includes(err.code)) break;
+    }
+  }
+  try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+  throw last;
+}
+
+/** 稳定键：文档相对路径；内容哈希单独比较，内容变了才算新版本。 */
+const stateKey = (relShort) => String(relShort).replace(/\\/g, '/').toLowerCase();
+
+/** 默认排除：临时验证副本、依赖目录、旧开发副本、UI 源码。 */
+const EXCLUDE = [
+  /(^|\/)(node_modules|dist|\.git|__pycache__)(\/|$)/i,
+  /(^|\/)\.verify-/i,
+  /(^|\/)DSH-probe(\/|$)/i,
+  /(^|\/)dsh-session-index(\/|$)/i,
+  /(^|\/)backup-/i,
+  /\.backup-/i,
+  /\.audit-/i,
+  /(^|\/)service\/public\//i,
+];
+
+const api = async (p, init) => {
+  const r = await fetch(BRIDGE + p, init);
+  const j = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(`${p} → HTTP ${r.status}: ${j.error || r.statusText}`);
+  return j;
+};
+const post = (p, body) => api(p, {
+  method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
+});
+const sha = (s) => createHash('sha256').update(s).digest('hex');
+const cleanTitle = (s) => String(s).replace(/[\\/:*?"<>|\r\n]+/g, ' ').trim().slice(0, 110);
+
+/** 把 HTML 正文裁干净后用思源桥自带转换器（只读）转 Markdown；MD 原样返回。 */
+async function toMarkdown(raw, label) {
+  const isHtml = /^\s*<(!doctype|html|main|div|h[1-6])/i.test(raw);
+  if (!isHtml) return raw.trim();
+  const main = /<main>([\s\S]*?)<\/main>/i.exec(raw)?.[1] || raw;
+  const cleaned = main
+    .replace(/<button\b[^>]*>[\s\S]*?<\/button>/gi, '')
+    .replace(/<div class="badges">[\s\S]*?<\/div>\s*<\/header>/i, '</header>')
+    .replace(/<script\b[\s\S]*?<\/script>/gi, '')
+    .replace(/<style\b[\s\S]*?<\/style>/gi, '')
+    .replace(/\sdata-kw="[^"]*"/g, '')
+    .trim();
+  const converted = (await post('/api/paste/html', { html: cleaned })).markdown || '';
+  return converted.replace(/^\s*#\s+[^\n]*操作使用手册[^\n]*\s*\n/m, '').trim() || `# ${label}`;
+}
+
+/** 组装一篇待投递文档：统一头部元信息 + 正文。 */
+async function buildDoc(raw, { title, origin, conv }) {
+  const body = await toMarkdown(raw, title);
+  const header = [
+    `# ${title}`,
+    '',
+    `> 来源：\`${origin}\`${conv ? ` · 会话 ${conv.slice(0, 8)}` : ''} · 插件 v${VERSION}`,
+    `> 转换：${/^\s*</.test(raw) ? '思源桥内置 HTML→Markdown' : '原样 Markdown'} · ${new Date().toLocaleString('zh-CN', { hour12: false })}`,
+    '> 状态：**仅进入待入库队列，未写入思源笔记库**，请在界面确认后再落库。',
+    '',
+    '---',
+    '',
+    '',
+  ].join('\n');
+  const markdown = `${header}${body}\n`;
+  const problems = [];
+  for (const bad of ['已复制', 'btn.textContent', 'data-kw', '@media', '<style', 'function(']) {
+    const n = markdown.split(bad).length - 1;
+    if (n) problems.push(`${bad} × ${n}`);
+  }
+  return { title, markdown, problems, chars: markdown.length };
+}
+
+function shortPath(abs) {
+  const marker = 'Tool开发';
+  const i = abs.replace(/\\/g, '/').lastIndexOf(marker);
+  return i === -1 ? path.basename(abs) : abs.replace(/\\/g, '/').slice(i + marker.length + 1);
+}
+
+/** 从 WorkBuddy 产物索引收集文档。 */
+function collectWorkbuddyDocs() {
+  const dir = process.env.WORKBUDDY_ARTIFACT_INDEX
+    || path.join(os.homedir(), '.workbuddy', 'artifact-index');
+  if (!fs.existsSync(dir)) throw new Error(`找不到 WorkBuddy 产物索引：${dir}`);
+  const seenHash = new Set();
+  const seenPath = new Set();
+  const docs = [];
+  let rawCount = 0;
+  let excluded = 0;
+  let missing = 0;
+  let dup = 0;
+  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.json'))) {
+    let j;
+    try {
+      j = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+    } catch {
+      continue;
+    }
+    const conv = f.replace(/\.json$/, '');
+    for (const a of j.artifacts || []) {
+      const docExt = has('--include-txt') ? /\.(md|markdown|html?|txt)$/i : /\.(md|markdown|html?)$/i;
+      if (a.contentType !== 'document' || !docExt.test(a.name || '')) continue;
+      if (SOURCE && String(a._meta?.sourceTool || '') !== SOURCE) continue;
+      if (SINCE && Number(a.updatedAt || 0) < SINCE) continue;
+      rawCount++;
+      let abs;
+      try {
+        abs = decodeURIComponent(String(a.uri || '').replace(/^file:\/\/\//, '')).replace(/\//g, path.sep);
+      } catch {
+        continue;
+      }
+      const rel = String(a.uri || '').replace(/^file:\/\/\//, '');
+      if (!NO_EXCLUDE && EXCLUDE.some((re) => re.test(rel))) { excluded++; continue; }
+      if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) { missing++; continue; }
+      const key = abs.toLowerCase();
+      if (seenPath.has(key)) { dup++; continue; }
+      const raw = fs.readFileSync(abs, 'utf8');
+      const h = sha(raw);
+      if (seenHash.has(h)) { dup++; continue; }
+      seenPath.add(key);
+      seenHash.add(h);
+      const relShort = shortPath(abs);
+      const label = path.basename(abs);
+      docs.push({
+        abs, raw, conv,
+        relShort,
+        contentHash: h,
+        stateKey: stateKey(relShort),
+        title: cleanTitle(TITLE_OVERRIDE || `${label.replace(/\.[^.]+$/, '')} · ${relShort}`),
+        origin: relShort,
+      });
+    }
+  }
+  return { docs, stats: { dir, rawCount, excluded, missing, dup, unique: docs.length } };
+}
+
+async function deliver(doc, queue, state) {
+  if (doc.problems.length) return { skipped: true, why: '含杂质：' + doc.problems.join(', ') };
+  if (doc.chars > 256 * 1024) return { skipped: true, why: '超过 256 KiB' };
+  if (!SEND) return { skipped: true, why: 'dry-run（未写入）' };
+
+  // 第一道：持久化状态。丢弃 / 清空队列 / 服务重启都不会让已推过的文档再出现。
+  const prev = state && doc.stateKey ? state.pushed[doc.stateKey] : null;
+  if (prev && prev.hash === doc.contentHash && !FORCE) {
+    return { skipped: true, why: '已推送过（丢弃也不重推）' };
+  }
+
+  // 第二道：队列同名（状态文件丢失时的兜底，不影响「丢弃后不重推」）
+  const same = queue.filter((it) => String(it.title).trim() === doc.title);
+  if (same.length && !FORCE) {
+    // 思源桥会规整 Markdown，队列里的 chars 与发送时未必相等，所以按标题判重更可靠
+    return { skipped: true, why: '队列中已有同名稿（--force 可再投）' };
+  }
+  const r = await post('/api/stage', {
+    title: doc.title, markdown: doc.markdown, notebook: NOTEBOOK, hpath: HPATH,
+    note: `WorkBuddy 会话产物 · ${doc.conv.slice(0, 8)} · v${VERSION} · 待人工确认`,
+  });
+  queue.push({ title: doc.title, chars: doc.chars });
+  if (state && doc.stateKey) {
+    state.pushed[doc.stateKey] = {
+      hash: doc.contentHash, title: doc.title, id: r.id || null, at: new Date().toISOString(),
+    };
+  }
+  return { staged: true, id: r.id, chars: r.chars };
+}
+
+// ------------------------------------------------------------------ 主流程
+
+const state = BATCH ? loadState() : null;
+const queue = (SEND && !SEED) ? ((await api('/api/stage')).items || []) : [];
+let jobs;
+
+if (BATCH) {
+  const { docs, stats } = collectWorkbuddyDocs();
+  console.log('=== WorkBuddy 会话文档扫描 ===');
+  console.log(`索引目录：${stats.dir}`);
+  console.log(`命中文档条目 ${stats.rawCount} · 排除临时/依赖目录 ${stats.excluded} · 文件已不存在 ${stats.missing} · 路径或内容重复 ${stats.dup}`);
+  console.log(`唯一可推送 ${stats.unique} 篇，本次上限 ${LIMIT} 篇${NO_EXCLUDE ? '（已关闭默认排除）' : ''}${SOURCE ? ` · 仅 ${SOURCE}` : ''}`);
+  jobs = docs.slice(0, LIMIT);
+  if (!jobs.length) {
+    console.log('\n没有可推送的文档。');
+    process.exit(0);
+  }
+  console.log('\n清单：');
+  jobs.forEach((d, i) => console.log(`  ${String(i + 1).padStart(2)}. [${d.conv.slice(0, 8)}] ${d.title}`));
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+
+  // --seed：纯本地建立状态基线，不碰思源桥、不投递任何文档。
+  if (SEED) {
+    let added = 0;
+    let same = 0;
+    for (const j of jobs) {
+      const prev = state.pushed[j.stateKey];
+      if (prev && prev.hash === j.contentHash && !FORCE) { same++; continue; }
+      state.pushed[j.stateKey] = {
+        hash: j.contentHash, title: j.title, id: prev?.id || 'seeded', at: new Date().toISOString(),
+      };
+      added++;
+    }
+    saveState(state);
+    console.log(`\n状态基线：新增 ${added} 条 / 已存在 ${same} 条 / 共 ${Object.keys(state.pushed).length} 条`);
+    console.log(`状态文件：${STATE_FILE}`);
+    console.log('未投递任何文档，未写入思源笔记库。');
+    process.exit(0);
+  }
+} else {
+  if (!fs.existsSync(FILE)) throw new Error(`找不到文件：${FILE}`);
+  const raw = fs.readFileSync(FILE, 'utf8');
+  const base = path.basename(FILE);
+  jobs = [{
+    raw, conv: '', relShort: shortPath(FILE), origin: base,
+    title: cleanTitle(TITLE_OVERRIDE || (/\.html?$/i.test(FILE)
+      ? `dsh-session-index 操作使用手册 v${VERSION}` : base.replace(/\.[^.]+$/, ''))),
+  }];
+}
+
+const results = [];
+for (const j of jobs) {
+  const doc = await buildDoc(j.raw, { title: j.title, origin: BATCH ? j.origin : j.relShort, conv: j.conv });
+  if (!BATCH) {
+    fs.mkdirSync(OUT_DIR, { recursive: true });
+    fs.writeFileSync(path.join(OUT_DIR, 'push-doc-preview.md'), doc.markdown, 'utf8');
+    console.log(`\n文件：${FILE}`);
+    console.log(`转换：${j.raw.length} → ${doc.chars} 字 · 章节标题 ${doc.markdown.split('\n').filter((l) => /^#{1,3} /.test(l)).length} 个`);
+    console.log(`杂质检查：${doc.problems.length ? doc.problems.join(', ') : '干净 ✓'}`);
+    console.log(`预览：${path.join(OUT_DIR, 'push-doc-preview.md')}`);
+    console.log(`\n--- 前 12 行 ---\n${doc.markdown.split('\n').slice(0, 12).join('\n')}`);
+  }
+  results.push({
+    title: doc.title,
+    ...(await deliver({
+      ...doc, conv: j.conv || '', stateKey: j.stateKey, contentHash: j.contentHash,
+    }, queue, state)),
+  });
+}
+
+if (BATCH && SEND && state && results.some((r) => r.staged)) saveState(state);
+
+if (BATCH) {
+  const staged = results.filter((r) => r.staged);
+  const skipped = results.filter((r) => r.skipped);
+  const reasons = new Map();
+  for (const r of skipped) reasons.set(r.why, (reasons.get(r.why) || 0) + 1);
+  console.log(`\n=== 结果 ===`);
+  console.log(`投递成功 ${staged.length} 篇 / 跳过 ${skipped.length} 篇 / 队列现有 ${queue.length} 篇`);
+  for (const [why, n] of reasons) console.log(`  ${why}: ${n}`);
+  if (staged.length) console.log(`  首篇 id=${staged[0].id} · 落点=${HPATH}`);
+  console.log(`  状态基线 ${Object.keys(state.pushed).length} 篇 · ${STATE_FILE}`);
+  if (!SEND) console.log('\n[只读预览] 未产生任何写入。确认清单后加 --send 才批量投递。');
+  else console.log('\n未调用 commit；请在思源桥「待入库」界面逐篇或批量勾选写入。');
+} else {
+  const r = results[0];
+  if (r.staged) console.log(`\n已投递：id=${r.id} · chars=${r.chars} · hpath=${HPATH}\n未调用 commit。`);
+  else console.log(`\n未投递：${r.why}`);
+  if (!SEND) console.log('[只读预览] 确认后加 --send 才进入待入库队列。');
+}

package/update.cmd

@@ -2,13 +2,13 @@
 rem Pure ASCII output on purpose: cmd.exe mis-parses UTF-8 .cmd files.
 setlocal EnableExtensions EnableDelayedExpansion
 chcp 65001 >nul 2>nul
-title dsh-session-index-lau updater
+title dsh-session-index updater
 
 set "PLUGIN_DIR=%~dp0"
 if "%PLUGIN_DIR:~-1%"=="\" set "PLUGIN_DIR=%PLUGIN_DIR:~0,-1%"
 
 echo ============================================================
-echo   dsh-session-index-lau updater (git pull + reinstall)
+echo   dsh-session-index updater (git pull + reinstall)
 echo   Dir: %PLUGIN_DIR%
 echo ============================================================
 echo.