@mingmaple/dsh-handover 0.0.0-stage → 0.9.12

package/src/lib/absrefs.mjs

@@ -0,0 +1,112 @@
+/**
+ * 绝对路径体检：扫「文件内容里写死的本机绝对路径」，只报告、不改写。
+ * 跨机器/跨平台迁移时，这些位置必须由人或项目会话自己处理——插件改不了用户文件里的路径语义。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKIP_EXT = new Set([
+  '.7z', '.zip', '.gz', '.zst', '.tar', '.rar',
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.svg',
+  '.pdf', '.docx', '.doc', '.xlsx', '.xls', '.pptx', '.ppt',
+  '.mp3', '.mp4', '.mov', '.wav', '.flac', '.m4a',
+  '.woff', '.woff2', '.ttf', '.otf', '.eot',
+  '.exe', '.dll', '.so', '.dylib', '.node', '.pyc', '.class', '.jar',
+  '.db', '.sqlite', '.bin', '.dat',
+]);
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_PER_FILE = 3;
+
+/**
+ * 识别模式：本机路径的典型写法。
+ * 盘符前必须是词边界、冒号后不能再跟斜杠——否则 https:// 、file:/// 的尾字母会被误判成盘符。
+ */
+const PATTERNS = [
+  ['盘符路径', /(?<![A-Za-z0-9_])[A-Za-z]:[\\/](?![\\/])[^\s'"`<>|]*/g],
+  ['UNC 网络路径', /(?<![A-Za-z0-9_\\])\\\\[A-Za-z0-9_.-]+\\[^\s'"`<>|]*/g],
+  ['POSIX 家目录', /(?<![A-Za-z0-9_.-])\/(?:Users|home)\/[A-Za-z0-9_.-]+\/[^\s'"`<>|]*/g],
+  ['file URL', /file:\/\/\/[^\s'"`<>|]*/g],
+];
+
+function walk(root, rel, out) {
+  let names = [];
+  try { names = fs.readdirSync(path.join(root, rel)); } catch { return out; }
+  for (const name of names) {
+    const r = rel ? rel + '/' + name : name;
+    const abs = path.join(root, rel, name);
+    let st;
+    try { st = fs.statSync(abs); } catch { continue; }
+    if (st.isDirectory()) walk(root, r, out);
+    else if (st.isFile()) out.push({ rel: r, abs, bytes: st.size });
+  }
+  return out;
+}
+
+/**
+ * 扫一个目录（或给定相对清单）里的绝对路径引用。
+ * @returns {{files:number, scanned:number, skipped:number, hits:Array, totalHits:number, crlf:number, lf:number, nonUtf8:Array, mixed:Array}}
+ */
+export function scanAbsoluteRefs(root, relPaths) {
+  const list = Array.isArray(relPaths) && relPaths.length
+    ? relPaths.map((rel) => ({ rel, abs: path.join(root, rel.split('/').join(path.sep)) }))
+    : walk(root, '', []);
+  const res = { files: list.length, scanned: 0, skipped: 0, hits: [], totalHits: 0, crlf: 0, lf: 0, nonUtf8: [], mixed: [] };
+  for (const it of list) {
+    const ext = path.extname(it.rel).toLowerCase();
+    if (SKIP_EXT.has(ext)) { res.skipped++; continue; }
+    let buf;
+    try {
+      const st = fs.statSync(it.abs);
+      if (!st.isFile() || st.size > MAX_BYTES) { res.skipped++; continue; }
+      buf = fs.readFileSync(it.abs);
+    } catch { res.skipped++; continue; }
+    const text = buf.toString('utf8');
+    res.scanned++;
+    if (text.indexOf(String.fromCharCode(0xFFFD)) !== -1) res.nonUtf8.push(it.rel);
+    const hasCrlf = text.indexOf(String.fromCharCode(13, 10)) !== -1;
+    const hasLfOnly = /\n/.test(text) && !hasCrlf;
+    if (hasCrlf) res.crlf++;
+    if (hasLfOnly) res.lf++;
+    const lines = text.split(String.fromCharCode(10));
+    const items = [];
+    for (let i = 0; i < lines.length && items.length < MAX_PER_FILE; i++) {
+      const line = lines[i];
+      for (const [kind, re] of PATTERNS) {
+        re.lastIndex = 0;
+        const m = re.exec(line);
+        if (!m) continue;
+        const sample = String(m[0]).trim().slice(0, 90);
+        if (!sample) continue;
+        if (items.some((x) => x.kind === kind && x.sample === sample)) continue;
+        items.push({ kind, sample, line: i + 1 });
+        if (items.length >= MAX_PER_FILE) break;
+      }
+    }
+    if (items.length) {
+      res.hits.push({ path: it.rel, items });
+      res.totalHits += items.length;
+    }
+  }
+  return res;
+}
+
+/** 渲染成给人看的中文结论。 */
+export function renderAbsoluteRefs(res, opts) {
+  const o = opts || {};
+  const out = [];
+  const title = o.title || '绝对路径体检';
+  out.push(title + '：扫描 ' + res.scanned + ' 个文本文件（跳过二进制/超大 ' + res.skipped + ' 个）');
+  if (!res.totalHits) {
+    out.push('  未发现写死的本机绝对路径');
+  } else {
+    out.push('  发现 ' + res.hits.length + ' 个文件里有 ' + res.totalHits + ' 处绝对路径（**插件不改写这些内容**）：');
+    for (const h of res.hits.slice(0, o.max || 10)) {
+      out.push('  ' + h.path);
+      for (const it of h.items) out.push('      L' + it.line + ' [' + it.kind + '] ' + it.sample);
+    }
+    if (res.hits.length > (o.max || 10)) out.push('  …还有 ' + (res.hits.length - (o.max || 10)) + ' 个文件（见 manifest）');
+  }
+  if (res.nonUtf8.length) out.push('  非 UTF-8（疑似 GBK/其他编码）' + res.nonUtf8.length + ' 个：' + res.nonUtf8.slice(0, 5).join('、'));
+  if (res.crlf && res.lf) out.push('  换行混用：CRLF ' + res.crlf + ' 个 / LF ' + res.lf + ' 个（跨系统请项目会话自行统一）');
+  return out;
+}

package/src/lib/api.mjs

@@ -0,0 +1,291 @@
+/**
+ * 设置页数据与动作的唯一实现：HTTP 路由（旧通道）和 /api 载体（新通道）都调它。
+ * 返回统一信封：{ ok:true, value } | { ok:false, error:{code,message,details}, http }。
+ * http 只是给旧 HTTP 通道用的状态码提示，载体通道不用它。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isDir } from './text.mjs';
+import { buildStatus } from './status.mjs';
+import { createGlobalWorkspace } from './scaffold.mjs';
+import { probeMove, startMove, moveStatus, cleanupOld, stageSwitch, repairLink, stageRetarget, applyRetarget } from './mover.mjs';
+import { routeWorkspace } from './workspace.mjs';
+import { grantConsent, listConsent, consumedConsent } from './consent.mjs';
+import { newSessionIn } from './session-create.mjs';
+
+function msgOf(e) { return String(e && e.message ? e.message : e); }
+
+/** 当前全局根：先按 cwd 推断，推不出来再查注册表里标题含「全局」的那个。 */
+export function currentRoot(env) {
+  let ws = '';
+  try { ws = String(routeWorkspace(env) || ''); } catch { ws = ''; }
+  if (ws && isDir(path.join(ws, '_Control_Center'))) return ws;
+  try {
+    const reg = env.registry && env.registry();
+    const list = reg && typeof reg.list === 'function' ? reg.list() || [] : [];
+    for (const w of list) {
+      const p = String((w && w.path) || '');
+      if (!p) continue;
+      if (String((w && w.title) || '').indexOf('全局') === -1) continue;
+      if (isDir(path.join(p, '_Control_Center'))) return p;
+    }
+  } catch { /* ignore */ }
+  return ws || '';
+}
+
+/** 状态快照缓存：设置页只取现成结果，不让请求等待现算。 */
+const statusCache = new WeakMap();   // env → { at, json, ms }
+const STATUS_TTL_MS = 30000;
+
+function invalidateStatus(env) { try { statusCache.delete(env); } catch { /* ignore */ } }
+
+export function statusSnapshot(env, info, why) {
+  const now = Date.now();
+  const hit = statusCache.get(env);
+  if (hit && now - hit.at < STATUS_TTL_MS) {
+    env.log('状态快照：命中缓存（' + (why || 'call') + '，' + hit.ms + ' ms 前计算）');
+    return hit.json;
+  }
+  const t0 = Date.now();
+  const json = buildStatus(env, info);
+  const ms = Date.now() - t0;
+  statusCache.set(env, { at: Date.now(), json, ms });
+  env.log('状态快照：现算 ' + ms + ' ms（' + (why || 'call') + '）');
+  return json;
+}
+
+/** 允许在设置页与聊天命令里填短号：session-xxxx… 前 8 位即可，这里补全成完整 id。 */
+export function resolveShortSid(env, input) {
+  const s = String(input || '').trim();
+  if (!s) return '';
+  if (s.indexOf('session-') === 0) return s;
+  try {
+    const dir = typeof env.cacheDir === 'function' ? env.cacheDir() : '';
+    if (dir) {
+      for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.json')) continue;
+        const stem = name.replace('.json', '');
+        if (stem.indexOf('session-' + s) === 0) return stem;
+        if (stem.slice(8, 8 + s.length) === s) return stem;
+      }
+    }
+  } catch { /* 找不到就按原样 */ }
+  return s;
+}
+
+/** 在已注册的工作区里建一个「全局」会话：先按工作区 id，抓不到再用 cwd。 */
+async function createGlobalSession(env, rootPath, title) {
+  let workspaceId = '';
+  try {
+    const reg = env.registry && env.registry();
+    const list = reg && typeof reg.list === 'function' ? (reg.list() || []) : [];
+    const norm = (s) => String(s || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+    const hit = list.find((w) => w && norm(w.path) === norm(rootPath));
+    if (hit) workspaceId = String(hit.id || '');
+  } catch { workspaceId = ''; }
+  const made = await newSessionIn(env, {
+    workspaceId,
+    cwd: workspaceId ? '' : rootPath,
+    title: title || '全局',
+    role: 'global',
+  });
+  return { sessionId: made.sessionId || '', error: made.error || '', workspaceId };
+}
+
+export function createApi(env, info) {
+  const ok = (value) => ({ ok: true, value });
+  const bad = (code, message, http) => ({ ok: false, error: { code, message, details: {} }, http: http || 400 });
+  const boom = (e, http) => bad('failed', msgOf(e), http || 400);
+
+  async function call(method, payload) {
+    const p = payload && typeof payload === 'object' ? payload : {};
+    try {
+      if (method === 'status') {
+        env.lastStatusCallAt = Date.now();   // 供预热判断「最近有人看过设置页」
+        return ok(statusSnapshot(env, info, 'call'));
+      }
+
+      if (method === 'setup') {
+        const r = createGlobalWorkspace(p.parent, { name: p.name });
+        invalidateStatus(env);
+        return r && r.ok ? ok(r) : { ok: false, error: { code: 'setup-failed', message: String((r && r.error) || '建立失败'), details: {} }, http: 400 };
+      }
+
+      if (method === 'deploy') {
+        // 一键部署：建文件体系 → 注册「全局」工作区 → 建「全局」会话（三件事一次做完）。
+        const scaffold = createGlobalWorkspace(p.parent, { name: p.name });
+        if (!scaffold || scaffold.ok !== true) {
+          return { ok: false, error: { code: 'setup-failed', message: String((scaffold && scaffold.error) || '建立失败'), details: {} }, http: 400 };
+        }
+        let ws = null;
+        let workspaceError = '';
+        try {
+          const reg = env.registry && env.registry();
+          if (reg && typeof reg.create === 'function') ws = await reg.create(scaffold.root, '全局');
+          else workspaceError = 'workspaceRegistry 不可用';
+        } catch (e) { workspaceError = '注册工作区失败：' + msgOf(e); }
+        const made = await createGlobalSession(env, scaffold.root, '全局');
+        invalidateStatus(env);
+        env.log('一键部署：体系 ' + scaffold.root + '；工作区 ' + (ws ? String(ws.id) : '失败') + '；会话 ' + (made.sessionId || '失败'));
+        return ok({
+          root: scaffold.root,
+          created: scaffold.created || [],
+          written: scaffold.written || [],
+          workspace: ws ? { id: String(ws.id || ''), title: String(ws.title || '全局'), path: String(ws.path || scaffold.root) } : null,
+          workspaceError,
+          sessionId: made.sessionId || '',
+          sessionError: made.error || '',
+        });
+      }
+
+      if (method === 'global-session') {
+        // 已接入工作区但没有全局会话时，补建一个（不建体系、不动既有文件）。
+        const root = currentRoot(env);
+        if (!root) return bad('no-workspace', '未找到全局根（工作区未接入）');
+        const made = await createGlobalSession(env, root, p.title || '全局');
+        invalidateStatus(env);
+        if (!made.sessionId) return bad('session-failed', made.error || '建会话失败');
+        env.log('补建全局会话：' + made.sessionId);
+        return ok({ root, sessionId: made.sessionId });
+      }
+
+      if (method === 'register') {
+        const target = String(p.path || '').trim();
+        if (!target) return bad('bad-request', '缺少 path（已存在的绝对目录）');
+        let st = null;
+        try { st = fs.statSync(target); } catch { st = null; }
+        if (!st || !st.isDirectory()) return bad('bad-request', '目录不存在或不是目录：' + target);
+        const reg = env.registry && env.registry();
+        if (!reg || typeof reg.create !== 'function') {
+          return { ok: false, error: { code: 'no-registry', message: 'workspaceRegistry 不可用', details: { hint: '请手工把这个路径粘进 DSH 的新建工作区：' + target } }, http: 501 };
+        }
+        const title = String(p.title || '').trim() || target.split(/[\\/]/).filter(Boolean).pop() || target;
+        try {
+          const w = await reg.create(target, title);
+          invalidateStatus(env);
+          return ok({
+            id: String((w && w.id) || ''),
+            title: String((w && w.title) || title),
+            path: String((w && w.path) || target),
+          });
+        } catch (e) {
+          return { ok: false, error: { code: 'register-failed', message: '建工作区失败：' + msgOf(e), details: {} }, http: 500 };
+        }
+      }
+
+      if (method === 'extra-prompt') {
+        if (typeof p.text !== 'string') return bad('bad-request', '缺少 text（空字符串＝不注入）');
+        // 写入门禁：内容与开关都没变就不写。提示词一改，下一次请求的整段前缀缓存失效。
+        let before = '';
+        let beforeEnabled = false;
+        try { before = String(env.extraPrompt() || ''); } catch { before = ''; }
+        try { beforeEnabled = env.extraPromptEnabled() === true; } catch { beforeEnabled = false; }
+        const nextEnabled = typeof p.enabled === 'boolean' ? p.enabled : (String(p.text).trim() !== '');
+        if (before === p.text && beforeEnabled === nextEnabled) {
+          return ok({ unchanged: true, chars: p.text.length, enabled: beforeEnabled, note: '内容与开关均未变化，已跳过写入（避免无谓的缓存失效）。' });
+        }
+        try {
+          const r = env.setExtraPrompt(p.text, nextEnabled);
+          invalidateStatus(env);
+          env.log('全局前置提示词：' + (r.enabled ? '已开启' : '已关闭') + '，' + r.chars + ' 字符（下一次请求前缀缓存失效）');
+          return ok(Object.assign({}, r, {
+            changed: true,
+            note: '已保存。提示词位于段序 950，改动会让下一次请求的整段前缀缓存失效，建议在压缩或换任的边界处修改。',
+          }));
+        } catch (e) { return boom(e); }
+      }
+
+      if (method === 'role') {
+        if (typeof env.applyRole !== 'function') return { ok: false, error: { code: 'not-ready', message: '宿主侧没有装配 applyRole', details: {} }, http: 501 };
+        const r = await env.applyRole({
+          sessionId: p.session_id || p.sessionId,
+          role: p.role,
+          project: p.project,
+          task: p.task,
+          wake: p.wake !== false,
+        });
+        env.log('会话角色：' + (r.ok ? (r.role + ' · 存活=' + r.live + ' · 已投递=' + r.delivered) : ('失败 ' + r.error)));
+        invalidateStatus(env);
+        return r.ok ? ok(r) : bad('bad-request', String(r.error || '设定失败'));
+      }
+
+      if (method === 'move.probe') {
+        const src = currentRoot(env);
+        if (!src) return bad('no-workspace', '未找到全局根（工作区未接入）');
+        return ok(await probeMove({ src, to: p.to }));
+      }
+
+      if (method === 'move.start') {
+        const src = currentRoot(env);
+        if (!src) return bad('no-workspace', '未找到全局根（工作区未接入）');
+        env.log('搬迁：开始复制 ' + src + ' → ' + String(p.to || ''));
+        const startedAt = Date.now();
+        const r = await startMove({ src, to: p.to });
+        env.log('搬迁：' + (r.ok ? '校验通过' : '校验有差异') + '，用时 ' + Math.round((Date.now() - startedAt) / 1000) + ' s');
+        return r.ok ? ok(r) : { ok: false, error: { code: 'verify-failed', message: '复制完成但校验有差异，未生成切换脚本', details: r.report }, http: 500 };
+      }
+
+      if (method === 'move.switch') {
+        const r = stageSwitch({ relaunch: p.relaunch === true });
+        env.log('搬迁：后台切换助手 ' + (r.already ? '无需再派（已切换）' : '已派出 pid=' + r.pid));
+        return ok(r);
+      }
+
+      if (method === 'move.status') {
+        // 一律以搬迁标记里的源路径为准：修改登记生效后当前工作区根已经变成新位置，
+        // 再拿它去比对会把「已经是新位置」误报成「还指着旧路径」。
+        return ok(moveStatus());
+      }
+
+      if (method === 'consent.grant') {
+        const sid = resolveShortSid(env, p.session_id);
+        if (!sid) return bad('bad-request', '缺少 session_id');
+        const g = grantConsent(sid, '设置页点击');
+        env.log('压缩授权：' + sid + '（5 分钟）');
+        invalidateStatus(env);
+        return ok(g);
+      }
+
+      if (method === 'consent.list') return ok({ rows: listConsent() });
+
+      if (method === 'consent.revoke') {
+        const sid = String(p.session_id || '').trim();
+        if (sid) consumedConsent(sid);
+        invalidateStatus(env);
+        return ok({ revoked: sid });
+      }
+
+      if (method === 'move.retarget') {
+        // 不是「等退出再改」时的即时执行：只在 DSH 已退出后由助手调用；页面走 stageRetarget。
+        const plan = applyRetarget();
+        invalidateStatus(env);
+        return ok(plan);
+      }
+
+      if (method === 'move.retarget-stage') {
+        const r = stageRetarget();
+        env.log('搬迁：登记修改登记助手 ' + (r.already ? '无需（已在新位置）' : '已派出 pid=' + r.pid));
+        return ok(r);
+      }
+
+      if (method === 'move.repair') {
+        const r = repairLink();
+        env.log('搬迁：重建链接 ' + (r.already ? '已存在' : r.src + ' → ' + r.dst));
+        invalidateStatus(env);
+        return ok(r);
+      }
+
+      if (method === 'move.cleanup') {
+        const r = await cleanupOld({ confirm: p.confirm === true });
+        env.log('搬迁：清理旧副本 ' + (r.removed || []).length + ' 个');
+        return ok(r);
+      }
+
+      return bad('unknown-method', '未知方法：' + method, 404);
+    } catch (e) {
+      return boom(e);
+    }
+  }
+
+  return { call, methods: ['status', 'setup', 'deploy', 'global-session', 'register', 'extra-prompt', 'role', 'move.probe', 'move.start', 'move.switch', 'move.status', 'move.retarget', 'move.retarget-stage', 'move.repair', 'move.cleanup', 'consent.grant', 'consent.list', 'consent.revoke'] };
+}

package/src/lib/archive.mjs

@@ -0,0 +1,198 @@
+/**
+ * 自带归档器：不依赖 7-Zip 的 tar(.gz) 读写（纯 Node，node:zlib 压缩）。
+ * 目的：插件所有功能都必须能用「构建产物 + DSH 自带环境」跑起来；7-Zip 只是可选加速器，不是前提。
+ * 格式口径：ustar + GNU 长名（typeflag L）；只存普通文件与目录；符号链接、硬链接一律不读不写。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+
+const BLOCK = 512;
+const MAX_TOTAL = 512 * 1024 * 1024;
+
+function octal(value, len) {
+  const s = Math.max(0, Math.floor(value)).toString(8);
+  if (s.length > len - 1) throw new Error('归档字段溢出：' + s);
+  return s.padStart(len - 1, '0') + String.fromCharCode(0);
+}
+
+function tarHeader(nameBytes, opts) {
+  const o = opts || {};
+  const h = Buffer.alloc(BLOCK, 0);
+  nameBytes.copy(h, 0, 0, Math.min(nameBytes.length, 100));
+  h.write(octal(o.mode === undefined ? 420 : o.mode, 8), 100, 'ascii');
+  h.write(octal(0, 8), 108, 'ascii');
+  h.write(octal(0, 8), 116, 'ascii');
+  h.write(octal(o.size || 0, 12), 124, 'ascii');
+  h.write(octal(o.mtime || 0, 12), 136, 'ascii');
+  h.write('        ', 148, 'ascii');
+  h.write(o.type || '0', 156, 'ascii');
+  h.write('ustar' + String.fromCharCode(0), 257, 'ascii');
+  h.write('00', 263, 'ascii');
+  let sum = 0;
+  for (const b of h) sum += b;
+  const cs = sum.toString(8).padStart(6, '0');
+  h.write(cs + String.fromCharCode(0) + ' ', 148, 'ascii');
+  return h;
+}
+
+function padToBlock(buf) {
+  const rem = buf.length % BLOCK;
+  return rem === 0 ? Buffer.alloc(0) : Buffer.alloc(BLOCK - rem, 0);
+}
+
+function walkEntries(root) {
+  const out = [];
+  const visit = (rel) => {
+    const abs = rel ? path.join(root, rel.split('/').join(path.sep)) : root;
+    let ents = [];
+    try { ents = fs.readdirSync(abs, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const r = rel ? rel + '/' + e.name : e.name;
+      const a = path.join(root, r.split('/').join(path.sep));
+      if (e.isDirectory()) {
+        out.push({ rel: r + '/', abs: a, dir: true, mtime: 0 });
+        visit(r);
+      } else if (e.isFile()) {
+        let st = null;
+        try { st = fs.statSync(a); } catch { continue; }
+        out.push({ rel: r, abs: a, dir: false, size: st.size, mtime: st.mtimeMs });
+      }
+    }
+  };
+  visit('');
+  return out;
+}
+
+/** 把目录打成 tar.gz。返回 { files, entries, bytes, archive }。 */
+export function packDirTarGz(srcDir, outFile) {
+  const entries = walkEntries(srcDir);
+  const total = entries.reduce((s, e) => s + (e.size || 0), 0);
+  if (total > MAX_TOTAL) throw new Error('待归档总量 ' + total + ' B 超过上限 ' + MAX_TOTAL + ' B，拒绝打包');
+  const chunks = [];
+  let files = 0;
+  for (const e of entries) {
+    const nameBuf = Buffer.from(e.rel, 'utf8');
+    const mtime = Math.floor((e.mtime || Date.now()) / 1000);
+    if (e.rel.length > 100) {
+      const payloadName = Buffer.concat([Buffer.from(e.rel, 'utf8'), Buffer.alloc(1, 0)]);
+      chunks.push(
+        tarHeader(Buffer.from('././@LongLink', 'utf8'), { size: payloadName.length, mtime, type: 'L' }),
+        payloadName,
+        padToBlock(payloadName),
+      );
+    }
+    if (e.dir) {
+      chunks.push(tarHeader(nameBuf, { type: '5', mode: 493, mtime }));
+      continue;
+    }
+    const body = fs.readFileSync(e.abs);
+    chunks.push(tarHeader(nameBuf, { size: body.length, mtime }), body, padToBlock(body));
+    files++;
+  }
+  chunks.push(Buffer.alloc(BLOCK * 2, 0));
+  const tar = Buffer.concat(chunks);
+  fs.writeFileSync(outFile, zlib.gzipSync(tar, { level: 6 }));
+  return { files, entries: entries.length, bytes: tar.length, archive: outFile };
+}
+
+/** 归档格式：'7z' | 'targz' | 'unknown'（按魔数判断，不看扩展名）。 */
+export function detectFormat(file) {
+  let fd = null;
+  try {
+    fd = fs.openSync(file, 'r');
+    const head = Buffer.alloc(8, 0);
+    fs.readSync(fd, head, 0, 8, 0);
+    if (head[0] === 0x37 && head[1] === 0x7a && head[2] === 0xbc && head[3] === 0xaf) return '7z';
+    if (head[0] === 0x1f && head[1] === 0x8b) return 'targz';
+    return 'unknown';
+  } catch {
+    return 'unknown';
+  } finally {
+    if (fd !== null) { try { fs.closeSync(fd); } catch { /* ignore */ } }
+  }
+}
+
+/** 把归档里的相对路径规范化；不安全（绝对路径、盘符、..）返回 null。 */
+export function safeRel(name) {
+  const raw = String(name || '').replace(/\\/g, '/');
+  if (raw === '') return null;
+  if (raw.charAt(0) === '/') return null;
+  if (/^[a-zA-Z]:/.test(raw)) return null;
+  const segs = raw.split('/').filter((s) => s !== '' && s !== '.');
+  if (!segs.length) return null;
+  for (const s of segs) if (s === '..') return null;
+  return segs.join('/');
+}
+
+function readOctal(buf, off, len) {
+  let s = '';
+  for (let i = off; i < off + len; i++) {
+    const c = buf[i];
+    if (c === 0) break;
+    s += String.fromCharCode(c);
+  }
+  s = s.trim();
+  return s === '' ? 0 : parseInt(s, 8) || 0;
+}
+
+function parseTar(buf, onEntry) {
+  let off = 0;
+  let longName = null;
+  while (off + BLOCK <= buf.length) {
+    const header = buf.subarray(off, off + BLOCK);
+    let allZero = true;
+    for (const b of header) if (b !== 0) { allZero = false; break; }
+    if (allZero) break;
+    const size = readOctal(header, 124, 12);
+    const typeByte = header[156] === 0 ? 48 : header[156];
+    const type = String.fromCharCode(typeByte);
+    let nameEnd = header.indexOf(0, 0);
+    if (nameEnd === -1 || nameEnd > 100) nameEnd = 100;
+    let name = header.toString('utf8', 0, nameEnd);
+    const bodyStart = off + BLOCK;
+    const body = buf.subarray(bodyStart, Math.min(bodyStart + size, buf.length));
+    const pad = (BLOCK - (size % BLOCK)) % BLOCK;
+    off = bodyStart + size + pad;
+    if (type === 'L') { longName = body.toString('utf8').replace(/\u0000+$/, ''); continue; }
+    if (longName) { name = longName; longName = null; }
+    onEntry({ name, type, size, body });
+  }
+}
+
+/** 列出 tar.gz 内的条目：[{ rel, size, type }]（rel 不安全的条目也照实列出，标 safe:false）。 */
+export function listTarGz(file) {
+  const buf = zlib.gunzipSync(fs.readFileSync(file));
+  const out = [];
+  parseTar(buf, (e) => {
+    const rel = safeRel(e.name);
+    out.push({ rel: rel === null ? e.name : rel, size: e.size, type: e.type, safe: rel !== null });
+  });
+  return out;
+}
+
+/** 解 tar.gz 到 destDir；跳过不安全路径与链接类条目。返回 { written, dirs, skipped }。 */
+export function extractTarGz(file, destDir) {
+  const buf = zlib.gunzipSync(fs.readFileSync(file));
+  const root = path.resolve(destDir);
+  let written = 0;
+  let dirs = 0;
+  const skipped = [];
+  parseTar(buf, (e) => {
+    const rel = safeRel(e.name);
+    if (rel === null) { skipped.push('不安全路径：' + e.name); return; }
+    const dest = path.resolve(root, rel.split('/').join(path.sep));
+    if (dest !== root && !dest.startsWith(root + path.sep)) { skipped.push('越界：' + rel); return; }
+    if (e.type === '5') {
+      fs.mkdirSync(dest, { recursive: true });
+      dirs++;
+      return;
+    }
+    if (e.type === '1' || e.type === '2') { skipped.push('链接条目不解：' + rel); return; }
+    if (e.type !== '0' && e.type !== '') { skipped.push('未知条目类型 ' + e.type + '：' + rel); return; }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, e.body);
+    written++;
+  });
+  return { written, dirs, skipped };
+}

package/src/lib/brief.mjs

@@ -0,0 +1,74 @@
+/** 起始简报：水位、闸门、活跃与沉默、预警、阶段与提示，一行一字段。 */
+import { driftVerdict } from './drift.mjs';
+
+function pad2(n) { return n < 10 ? "0" + n : "" + n; }
+
+export function stamp(ms) {
+  const d = new Date(ms);
+  return d.getFullYear() + "-" + pad2(d.getMonth() + 1) + "-" + pad2(d.getDate()) + " " + pad2(d.getHours()) + ":" + pad2(d.getMinutes());
+}
+
+/** 带时区偏移的时间戳（硬规定：对用户可见的时间一律带偏移，例 2026-10-23 21:40 +0800）。 */
+export function stampTz(ms) {
+  const d = new Date(ms);
+  const off = -d.getTimezoneOffset();
+  const sign = off >= 0 ? "+" : "-";
+  const a = Math.abs(off);
+  return stamp(ms) + " " + sign + pad2(Math.floor(a / 60)) + pad2(a % 60);
+}
+
+/** 会话短号：去掉 session- 前缀后取末 8 位。 */
+function sidShort(sid) {
+  const s = sid.indexOf('session-') === 0 ? sid.slice(8) : sid;
+  return s.slice(0, 8);
+}
+
+function thousands(n) {
+  const s = String(n);
+  let out = "";
+  for (let i = 0; i < s.length; i++) {
+    if (i > 0 && (s.length - i) % 3 === 0) out += ",";
+    out += s[i];
+  }
+  return out;
+}
+
+export function composeBrief(input) {
+  const out = [];
+  const cfg = input.cfg || {};
+  out.push('== 起始简报 ' + stamp(Date.now()) + ' ==');
+  if (input.selfUsed === null || input.selfWin === null) {
+    out.push('水位   无法读取，需人工判断');
+  } else {
+    const pct = (input.selfUsed / input.selfWin) * 100;
+    const warn = cfg.warnRatio === undefined ? 0.32 : cfg.warnRatio;
+    out.push("水位   " + pct.toFixed(1) + "%（" + thousands(input.selfUsed) + " / " + thousands(input.selfWin) + "）→ " + (pct >= warn * 100 ? "已过阈值，该写交接" : "可继续"));
+  }
+  const gate = input.gate;
+  if (!gate || gate.error) {
+    out.push('闸门   ' + (gate && gate.error ? gate.error : '读不到') + ' · 退出码 ? · ?');
+    if (gate && gate.noWorkspace) out.push('       首次安装？把工作区接入即可：ho_workspace(action="create", path="<绝对目录>", title="全局")，再开一个标题含「全局」的会话。');
+  } else {
+    out.push("闸门   " + gate.total + " 库 · 正文 " + gate.bodyLines + " 行 · 退出码 " + (gate.ok ? 0 : 10) + " · 判定：" + gate.verdict);
+  }
+  const scan = input.scan;
+  if (!scan) {
+    out.push('活跃   读不到（投影缓存目录不可用）');
+  } else {
+    const notifProjects = new Set(scan.notify.map((r) => r.project));
+    const skipProjects = new Set(scan.skip.map((r) => r.project));
+    out.push("活跃   " + notifProjects.size + " 个项目，需要通知 " + scan.notify.length + " 个会话：" + (scan.notify.length ? scan.notify.map((r) => r.project + "(" + sidShort(r.sid) + ",在任)").join("、") : "无"));
+    out.push("沉默   " + skipProjects.size + " 个项目，跳过 " + scan.skip.length + " 个会话（不唤醒，省 token）");
+    if (scan.hot.length) out.push("预警   " + scan.hot.length + " 个会话已进预警区（≥" + Math.round(scan.warn) + "%）—— 全为退场、前任则可忽略");
+  }
+  if (input.drift) {
+    out.push('Δ交接  ' + driftVerdict(input.drift));
+    const stale = input.drift.rows.filter((r) => r.verdict === '需刷交接');
+    if (stale.length) out.push('        需刷：' + stale.map((r) => r.project + '(' + sidShort(r.sid) + ')').join('、'));
+  } else {
+    out.push('Δ交接  读不到（会话日志不可用）');
+  }
+  if (input.advice && input.advice.text) out.push('阶段   ' + input.advice.text);
+  out.push('提示   ' + (input.ok ? '按「活跃」名单逐个 peer_send 广播本会话 id 并记回 §3；可正常开始作业' : '本会话已过阈值或闸门异常，应先收齐交接，再开展新任务'));
+  return out;
+}