dsh-isolation-gate 0.0.0-stage → 0.2.1

package/bin/gate.mjs

@@ -0,0 +1,473 @@
+#!/usr/bin/env node
+/**
+ * gate —— 受管辖的访问通道（agent / 工具侧唯一入口）
+ *
+ * 用法（全部先判定、后动手；判定不通过就**一个字节都不碰**）：
+ *
+ *   node bin/gate.mjs status                     看全部受管对象的级别（agent 读状态用）
+ *   node bin/gate.mjs policy                     紧凑策略行（可直接塞进提示词/规则）
+ *   node bin/gate.mjs check --name Zcode --op read
+ *   node bin/gate.mjs check --path "D:\\Zcode\\某文件" --op delete
+ *   node bin/gate.mjs check --path "E:\\资料\\合作档案\\某项目\\a.md" --op read
+ *   node bin/gate.mjs traverse --path "D:\\Zcode"
+ *   node bin/gate.mjs read  --path "D:\\Zcode\\某文件"
+ *   node bin/gate.mjs write --path "D:\\Zcode\\某文件" --text "内容"
+ *   node bin/gate.mjs delete --path "D:\\Zcode\\某文件"      （删前自动备份到回收站）
+ *   node bin/gate.mjs rmdir  --path "D:\\Zcode\\空目录"      （只删**空目录**；不递归，非空一律拒）
+ *   node bin/gate.mjs log --limit 20
+ *
+ * 退出码：0 = 放行 / 成功 · 3 = **被拒**（授权不足，拒绝文案在 stderr） · 2 = 用错或环境错误。
+ *
+ * 可选参数：--state <路径> · --roster <路径> · --root <盘根> · --log <审计路径>
+ *          --channel <通道名> · --json · --no-backup
+ *
+ * ⚠️ **fail-closed**：名单文件缺失 / 读坏 ⇒ **一律拒绝**（exit 3，文案含"名单不可用"）。
+ *    旧版在同样情形下会"放行一切"（隔离悄悄失效）—— 现已改为拒到底。
+ *
+ * ⚠️ 本通道**只**能替代"你本来要直接读写受管对象"的那一步；它不会自己变聪明：
+ * 走别的路绕开它，等于把"授权以 GUI 门禁开关为准"这条规则丢掉。
+ */
+
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { appendAudit, readAudit } from '../lib/audit.js';
+import { buildReport, check, levelInfo, normalizeConfig } from '../lib/service.js';
+import { readRoster } from '../lib/roster.js';
+import { readState } from '../lib/store.js';
+
+const CHANNEL = 'dsh-isolation-gate/bin/gate.mjs';
+const MAX_READ_BYTES = 2 * 1024 * 1024;
+const DEFAULT_DELETE_BACKUP_DIR = 'D:\\回收站\\门禁-改前';
+
+function parseArgs(argv) {
+  const positional = [];
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token.startsWith('--')) {
+      const eq = token.indexOf('=');
+      if (eq > 0) {
+        options[token.slice(2, eq)] = token.slice(eq + 1);
+        continue;
+      }
+      const key = token.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        options[key] = true;
+        continue;
+      }
+      options[key] = next;
+      i += 1;
+      continue;
+    }
+    positional.push(token);
+  }
+  return { positional, options };
+}
+
+function configFrom(options) {
+  const raw = {};
+  if (typeof options.state === 'string') raw.statePath = options.state;
+  if (typeof options.roster === 'string') raw.rosterPath = options.roster;
+  if (typeof options.root === 'string') raw.root = options.root;
+  if (typeof options.log === 'string') raw.auditPath = options.log;
+  if (typeof options['backup-dir'] === 'string') raw.backupDir = options['backup-dir'];
+  return normalizeConfig(raw);
+}
+
+function emit(options, payload, human) {
+  if (options.json === true) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  else process.stdout.write(`${human}\n`);
+}
+
+function deny(options, decision) {
+  const message = decision.error ? `拒绝/出错：${decision.error}` : decision.reason;
+  if (options.json === true) {
+    process.stdout.write(`${JSON.stringify({ ok: true, allowed: false, decision }, null, 2)}\n`);
+  } else {
+    process.stderr.write(`${message}\n`);
+  }
+  process.exit(decision.error ? 2 : 3);
+}
+
+/**
+ * 判定 → 通过才继续；不通过就退出（不碰任何文件）。
+ * 名单读不到时判定侧**一律拒绝**（fail-closed），所以这里不需要再补丁。
+ */
+function gate(cfg, options, target) {
+  const stateRead = readState(cfg.statePath);
+  const rosterRead = readRoster(cfg.rosterPath);
+  const decision = check(cfg, {
+    name: target.name,
+    path: target.path,
+    op: target.op,
+    channel: typeof options.channel === 'string' && options.channel !== '' ? options.channel : CHANNEL,
+  });
+  if (!decision.ok || !decision.allowed) {
+    deny(options, decision);
+    return decision; // deny() 已经 exit，这一行只为静态可读性
+  }
+  if (!stateRead.ok && !rosterRead.ok) {
+    // 配置都读不出来还放行是不可能的（放行只会来自"不属于任何受管对象"）—— 不做特殊处理。
+  }
+  return decision;
+}
+
+function statusCommand(cfg, options) {
+  const report = buildReport(cfg, { auditLimit: 5 });
+  const lines = [];
+  lines.push(`门禁状态（唯一生效依据：${report.paths.state}）`);
+  lines.push(`受管名单：${report.paths.roster}（存在=${report.files.rosterExists}）`);
+  if (report.files.gateClosed) lines.push(`⚠ ${report.files.rosterGateMessage}`);
+  if (report.files.stateError) lines.push(`⚠ 状态文件：${report.files.stateError}`);
+  if ((report.files.rosterInvalid || []).length > 0) {
+    lines.push(`⚠ 名单里有不合法、未生效的行：${report.files.rosterInvalid.map((row) => row.raw).join(' / ')}`);
+  }
+  lines.push('');
+  if (report.roster.length === 0) lines.push('（名单为空）');
+  for (const row of report.roster) {
+    lines.push(
+      `  ${(row.isPath ? '[路径] ' : '')}${row.name.padEnd(14)} = ${row.level.padEnd(5)}（${row.levelLabel}）` +
+        ` · 允许：${row.allowedOps.join(',') || '无'}` +
+        (row.dirExists ? '' : '  ⚠ 目录不存在'),
+    );
+  }
+  if (report.stateOnly.length > 0) {
+    lines.push('');
+    lines.push('（状态里有、名单里没有 ⇒ 当前不受管辖）');
+    for (const row of report.stateOnly) lines.push(`  ${row.name} = ${row.level}（${row.levelLabel}）`);
+  }
+  if (options.json === true) {
+    emit(options, { ok: true, state: report.paths.state, roster: report.roster, stateOnly: report.stateOnly }, '');
+    return 0;
+  }
+  process.stdout.write(`${lines.join('\n')}\n`);
+  return 0;
+}
+
+function policyCommand(cfg, options) {
+  const report = buildReport(cfg, { auditLimit: 1 });
+  const text = report.policy.join('\n');
+  if (options.json === true) emit(options, { ok: true, policy: report.policy, levels: levelInfo() }, '');
+  else process.stdout.write(`${text}\n`);
+  return 0;
+}
+
+function checkCommand(cfg, options) {
+  const op = typeof options.op === 'string' ? options.op : 'read';
+  const decision = check(cfg, {
+    name: typeof options.name === 'string' ? options.name : undefined,
+    path: typeof options.path === 'string' ? options.path : undefined,
+    op,
+    channel: typeof options.channel === 'string' ? options.channel : CHANNEL,
+  });
+  if (!decision.ok) {
+    process.stderr.write(`判定失败：${decision.error}\n`);
+    return 2;
+  }
+  if (options.json === true) process.stdout.write(`${JSON.stringify(decision, null, 2)}\n`);
+  else {
+    const levelText = decision.rosterUnavailable === true ? '名单不可用' : (decision.level ?? '不在名单');
+    process.stdout.write(
+      `${decision.allowed ? '放行' : '拒绝'} · ${decision.name ?? '?'} · 级别=${levelText} · 操作=${op}\n` +
+        `${decision.reason}\n`,
+    );
+  }
+  return decision.allowed ? 0 : 3;
+}
+
+function traverseCommand(cfg, options) {
+  const target = resolve(String(options.path));
+  const decision = gate(cfg, options, { path: target, op: 'traverse' });
+  let entries;
+  try {
+    entries = readdirSync(target, { withFileTypes: true }).map((entry) => ({
+      name: entry.name,
+      kind: entry.isDirectory() ? 'dir' : entry.isSymbolicLink() ? 'link' : 'file',
+    }));
+  } catch (error) {
+    process.stderr.write(`列出失败：${error?.message ?? String(error)}\n`);
+    return 2;
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name, 'zh-Hans-CN'));
+  if (options.json === true) emit(options, { ok: true, allowed: true, path: target, decision, entries }, '');
+  else {
+    process.stdout.write(`放行：${target}（${entries.length} 项）\n`);
+    // 放行理由也要说清：是"没被隔离管辖"还是"已授权"——两者含义完全不同。
+    if (decision.inRoster === false) process.stdout.write(`  · ${decision.reason}\n`);
+    for (const entry of entries) process.stdout.write(`  [${entry.kind}] ${entry.name}\n`);
+  }
+  return 0;
+}
+
+function readCommand(cfg, options) {
+  const target = resolve(String(options.path));
+  gate(cfg, options, { path: target, op: 'read' });
+  let stats;
+  try {
+    stats = statSync(target);
+  } catch (error) {
+    process.stderr.write(`读取失败：${error?.message ?? String(error)}\n`);
+    return 2;
+  }
+  if (!stats.isFile()) {
+    process.stderr.write(`读取失败：不是普通文件（${target}）\n`);
+    return 2;
+  }
+  if (stats.size > MAX_READ_BYTES) {
+    process.stderr.write(`读取失败：文件 ${stats.size} 字节，超过通道上限 ${MAX_READ_BYTES}\n`);
+    return 2;
+  }
+  let text;
+  try {
+    text = readFileSync(target, 'utf8');
+  } catch (error) {
+    process.stderr.write(`读取失败：${error?.message ?? String(error)}\n`);
+    return 2;
+  }
+  if (options.json === true) emit(options, { ok: true, allowed: true, path: target, bytes: stats.size, text }, '');
+  else process.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+  return 0;
+}
+
+function writeCommand(cfg, options) {
+  const target = resolve(String(options.path));
+  gate(cfg, options, { path: target, op: 'write' });
+  if (typeof options.text !== 'string') {
+    process.stderr.write('写入失败：缺少 --text（本通道不做交互式编辑）\n');
+    return 2;
+  }
+  try {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, options.text, 'utf8');
+  } catch (error) {
+    process.stderr.write(`写入失败：${error?.message ?? String(error)}\n`);
+    return 2;
+  }
+  appendAudit(cfg.auditPath, {
+    channel: CHANNEL,
+    name: null,
+    op: 'write',
+    allowed: true,
+    detail: `已写 ${target}（${Buffer.byteLength(options.text, 'utf8')} 字节）`,
+  });
+  if (options.json === true) emit(options, { ok: true, allowed: true, path: target, bytes: Buffer.byteLength(options.text, 'utf8') }, '');
+  else process.stdout.write(`已写入：${target}\n`);
+  return 0;
+}
+
+function deleteCommand(cfg, options) {
+  const target = resolve(String(options.path));
+  gate(cfg, options, { path: target, op: 'delete' });
+  if (!existsSync(target)) {
+    process.stderr.write(`删除失败：目标不存在（${target}）\n`);
+    return 2;
+  }
+  let stats;
+  try {
+    stats = statSync(target);
+  } catch (error) {
+    process.stderr.write(`删除失败：${error?.message ?? String(error)}\n`);
+    return 2;
+  }
+  if (stats.isDirectory()) {
+    process.stderr.write(
+      '删除失败：本通道只删**文件**，不删目录（目录的递归删/搬属高风险动作，' +
+        '请按房规先备份、由户主/管家单独授权执行；空目录请用 rmdir）\n',
+    );
+    return 2;
+  }
+  let backup = null;
+  if (options['no-backup'] !== true) {
+    try {
+      const backupDir = join(String(options['backup-dir'] ?? DEFAULT_DELETE_BACKUP_DIR));
+      mkdirSync(backupDir, { recursive: true });
+      const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+      backup = join(backupDir, `${stamp}__${target.replace(/[:\\/]/g, '_')}`);
+      cpSync(target, backup);
+    } catch (error) {
+      process.stderr.write(`删除中止：删前备份失败（房规：删前必先备份）—— ${error?.message ?? String(error)}\n`);
+      return 2;
+    }
+  }
+  try {
+    rmSync(target, { force: true });
+  } catch (error) {
+    process.stderr.write(`删除失败：${error?.message ?? String(error)}\n`);
+    return 2;
+  }
+  appendAudit(cfg.auditPath, {
+    channel: CHANNEL,
+    name: null,
+    op: 'delete',
+    allowed: true,
+    detail: `已删 ${target}；备份=${backup ?? '（--no-backup 跳过）'}`,
+  });
+  if (options.json === true) emit(options, { ok: true, allowed: true, path: target, backup }, '');
+  else process.stdout.write(`已删除：${target}（备份：${backup ?? '未做'}）\n`);
+  return 0;
+}
+
+/**
+ * 删**空目录**（不递归）。
+ *
+ * 为什么补这个命令（2026-10-09 户主实测发现）：`write` 会自动建父目录 ⇒ 通道**能建目录**，
+ * 却没有能力删掉自己建的目录 ⇒ 收尾必留残渣。这里只补"删空目录"这一最小能力；
+ * 非空目录**一律拒绝**（递归删仍属高风险，按房规走户主/管家单独授权）。
+ * 护栏：① 只删受管范围之下第 2 层及更深（盘根与受管对象本身不可由本通道删）
+ *       ② 只删空目录（不递归）③ 目标是链接/junction 时拒（本通道不动链接）
+ */
+function rmdirCommand(cfg, options) {
+  const target = resolve(String(options.path));
+  gate(cfg, options, { path: target, op: 'delete' });
+  if (!existsSync(target)) {
+    process.stderr.write(`删除目录失败：目标不存在（${target}）\n`);
+    return 2;
+  }
+  let link;
+  try {
+    link = lstatSync(target);
+  } catch (error) {
+    process.stderr.write(`删除目录失败：${error?.message ?? String(error)}\n`);
+    return 2;
+  }
+  if (link.isSymbolicLink()) {
+    process.stderr.write(`删除目录失败：目标是链接 / junction（${target}）—— 本通道不动链接，请人工处理\n`);
+    return 2;
+  }
+  if (!link.isDirectory()) {
+    process.stderr.write(`删除目录失败：不是目录（${target}）—— 删文件请用 delete\n`);
+    return 2;
+  }
+  const rel = relative(resolve(cfg.root), target);
+  const depth = rel.split(/[\\/]/).filter(Boolean).length;
+  if (depth < 2) {
+    process.stderr.write(
+      `删除目录失败：只能删「受管范围之下第 2 层及更深」的目录；${target} 是第 ${depth} 层` +
+        '（盘根与受管对象目录本身不得由本通道删除）\n',
+    );
+    return 2;
+  }
+  const entries = readdirSync(target);
+  if (entries.length > 0) {
+    process.stderr.write(
+      `删除目录失败：目录非空（${entries.length} 项）—— 本通道**不递归删**；` +
+        '请先用 delete 逐个删文件，或由户主 / 管家按房规单独授权处理\n',
+    );
+    return 2;
+  }
+  try {
+    // ⚠️ 必须用 rmdirSync：fs.rmSync(recursive:false) 对**目录**会直接抛 EISDIR（2026-10-09 实测踩到）。
+    //    rmdirSync 本身只删空目录 —— 与"不递归"的语义天然一致。
+    rmdirSync(target);
+  } catch (error) {
+    process.stderr.write(`删除目录失败：${error?.message ?? String(error)}\n`);
+    return 2;
+  }
+  appendAudit(cfg.auditPath, {
+    channel: CHANNEL,
+    name: null,
+    op: 'delete',
+    allowed: true,
+    detail: `已删空目录 ${target}（空目录无内容可备份）`,
+  });
+  if (options.json === true) emit(options, { ok: true, allowed: true, path: target, removed: 'empty-dir' }, '');
+  else process.stdout.write(`已删除空目录：${target}（空目录无内容，未做备份）\n`);
+  return 0;
+}
+
+function logCommand(cfg, options) {
+  const limit = Number.parseInt(String(options.limit ?? '20'), 10);
+  const result = readAudit(cfg.auditPath, Number.isInteger(limit) && limit > 0 ? limit : 20);
+  if (options.json === true) emit(options, { ok: true, audit: result }, '');
+  else if (result.entries.length === 0) process.stdout.write(`（无审计记录；${cfg.auditPath}）\n`);
+  else {
+    process.stdout.write(`审计（最新在前，共 ${result.total ?? 0} 条；${cfg.auditPath}）\n`);
+    for (const entry of result.entries) {
+      process.stdout.write(
+        `  ${entry.atLocal ?? entry.at} · ${entry.allowed ? '放行' : '拒绝'} · ${entry.channel} · ` +
+          `${entry.name ?? '-'} · ${entry.op} · ${entry.detail ?? ''}\n`,
+      );
+    }
+  }
+  return 0;
+}
+
+function usage() {
+  process.stdout.write(
+    [
+      'gate —— 受管辖的访问通道',
+      '',
+      '  status                                  看全部受管对象的级别（agent 读状态用）',
+      '  policy                                  紧凑策略行（塞提示词用）',
+      '  check   --name X --op read              只判定不动手',
+      '  check   --path P --op delete            路径也支持（最长前缀命中）',
+      '  traverse --path P                       列目录名（需 traverse 权限）',
+      '  read    --path P                        读文件（需 read 权限）',
+      '  write   --path P --text S               写文件（需 write 权限）',
+      '  delete  --path P                        删**文件**（需 delete 权限；删前自动备份）',
+      '  rmdir   --path P                        删**空目录**（需 delete 权限；不递归，非空则拒）',
+      '  log     [--limit 20]                    审计日志',
+      '',
+      '  级别：deny 禁（默认） / read 只读 / full 可读写删',
+      '  退出码：0 放行 · 3 被拒 · 2 用错或环境错误',
+      '  fail-closed：名单缺失 / 损坏 ⇒ 一律拒绝（exit 3，文案含"名单不可用"）',
+      '',
+    ].join('\n'),
+  );
+  return 2;
+}
+
+function main() {
+  const { positional, options } = parseArgs(process.argv.slice(2));
+  const command = positional[0];
+  if (!command || command === 'help' || options.help === true) return usage();
+  const cfg = configFrom(options);
+  switch (command) {
+    case 'status':
+      return statusCommand(cfg, options);
+    case 'policy':
+      return policyCommand(cfg, options);
+    case 'check':
+      return checkCommand(cfg, options);
+    case 'traverse':
+    case 'list':
+      if (typeof options.path !== 'string') {
+        process.stderr.write('traverse 需要 --path\n');
+        return 2;
+      }
+      return traverseCommand(cfg, options);
+    case 'read':
+      if (typeof options.path !== 'string') {
+        process.stderr.write('read 需要 --path\n');
+        return 2;
+      }
+      return readCommand(cfg, options);
+    case 'write':
+      if (typeof options.path !== 'string') {
+        process.stderr.write('write 需要 --path\n');
+        return 2;
+      }
+      return writeCommand(cfg, options);
+    case 'delete':
+      if (typeof options.path !== 'string') {
+        process.stderr.write('delete 需要 --path\n');
+        return 2;
+      }
+      return deleteCommand(cfg, options);
+    case 'rmdir':
+      if (typeof options.path !== 'string') {
+        process.stderr.write('rmdir 需要 --path\n');
+        return 2;
+      }
+      return rmdirCommand(cfg, options);
+    case 'log':
+      return logCommand(cfg, options);
+    default:
+      process.stderr.write(`未知命令：${command}\n`);
+      return usage();
+  }
+}
+
+process.exitCode = main();

package/cordis.patch.yml

@@ -0,0 +1,37 @@
+# dsh-isolation-gate bundle patch
+#
+# 挂上本插件的 loader 行。两个半边：
+#
+#   · 宿主半（lib/index.js）—— 本机 HTTP 路由 /__dsh-isolation-gate/*：
+#       GET  /__dsh-isolation-gate/ping     插件身份 + 三级说明
+#       GET  /__dsh-isolation-gate/state    名单 / 级别 / 磁盘差异 / 审计尾部 / agent 策略行
+#       POST /__dsh-isolation-gate/level    改一个受管对象的三级授权（写状态文件）
+#       POST /__dsh-isolation-gate/roster   名单增删（**先备份**，新增项自动建 deny）
+#       POST /__dsh-isolation-gate/check    受管辖通道判定（不读任何内容）
+#       GET  /__dsh-isolation-gate/log      最近审计
+#     它只读写两个配置文件（状态 JSON / 名单 TXT）、列出盘根**一层目录名**，
+#     并对名单里**显式列出的路径**做一次存在性判定；受管对象内部内容的读写全部在
+#     bin/gate.mjs 那条受管辖通道里，同样由本插件判定。
+#
+#   · 客户端半（lib/client.js，经 package.json 的 dsh.client 声明）—— 通过框架官方
+#     `slots` 服务挂两个座位（与官方「插件」「自动化任务」页同一个扩展点）：
+#       1. 左上应用级导航排 `sidebar.panellist`（root 作用域 **list**）→ 图标行，
+#          `order: 6` —— 官方「插件」= 0、「自动化任务」= 10、已装的「技能」= 5，
+#          因此 6 正好落在**「技能」正下方**（外壳按 order 升序排，与加载先后无关）。
+#       2. 主区 `main`（root 作用域 **keyed**）→ 整页，key 同行 id：`isolation-gate`。
+#     因此本包**不声明任何 @deepseek-ai/dsh\* peer 依赖**（它从不 import 它们；
+#     `slots` 是经 ctx.inject 来的运行时服务）⇒ 不受 DSH 兼容性豁免闸门影响。
+#
+# 装配方式（**归管家域**，本卡不动 profile）——二者取一：
+#   (a) 在 profile 的 dsh.profile.bundles 列表里加 "dsh-isolation-gate"；或
+#   (b) 用用户 patch 层插同一行：
+#
+#   - insert:
+#       - id: isolation-gate
+#         name: 'dsh-isolation-gate'
+#
+# `name` 就是 npm 包名；loader 从 profile 的 node_modules 里解析它。
+
+- insert:
+    - id: isolation-gate
+      name: 'dsh-isolation-gate'

package/docs/banner.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="320" viewBox="0 0 1200 320" role="img" aria-label="门禁 · dsh-isolation-gate">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0b1220"/>
+      <stop offset="0.55" stop-color="#101a2e"/>
+      <stop offset="1" stop-color="#1a1030"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#5eead4"/>
+      <stop offset="0.5" stop-color="#60a5fa"/>
+      <stop offset="1" stop-color="#c084fc"/>
+    </linearGradient>
+  </defs>
+  <rect width="1200" height="320" fill="url(#bg)"/>
+  <g opacity="0.18" stroke="#94a3b8" stroke-width="1">
+    <path d="M0 80h1200M0 160h1200M0 240h1200"/>
+    <path d="M200 0v320M400 0v320M600 0v320M800 0v320M1000 0v320"/>
+  </g>
+  <g transform="translate(80,92)">
+    <rect x="0" y="0" width="96" height="96" rx="22" fill="#0f172a" stroke="url(#accent)" stroke-width="3"/>
+    <path d="M30 52V40a18 18 0 0 1 36 0v12" fill="none" stroke="#5eead4" stroke-width="6" stroke-linecap="round"/>
+    <rect x="24" y="52" width="48" height="30" rx="7" fill="#5eead4"/>
+    <circle cx="48" cy="66" r="4" fill="#0b1220"/>
+  </g>
+  <text x="208" y="132" font-family="Segoe UI, PingFang SC, Microsoft YaHei, sans-serif" font-size="46" font-weight="700" fill="#f8fafc">门禁 · dsh-isolation-gate</text>
+  <text x="208" y="176" font-family="Segoe UI, PingFang SC, Microsoft YaHei, sans-serif" font-size="22" fill="#94a3b8">默认禁 · 名单制 · 分组批量 · 可审计 · agent 自查</text>
+  <g font-family="Segoe UI, Microsoft YaHei, sans-serif" font-size="17">
+    <rect x="208" y="204" width="120" height="36" rx="18" fill="#0f172a" stroke="#334155"/>
+    <text x="268" y="228" text-anchor="middle" fill="#e2e8f0">deny</text>
+    <rect x="340" y="204" width="120" height="36" rx="18" fill="#0f172a" stroke="#334155"/>
+    <text x="400" y="228" text-anchor="middle" fill="#e2e8f0">read</text>
+    <rect x="472" y="204" width="120" height="36" rx="18" fill="#0f172a" stroke="#334155"/>
+    <text x="532" y="228" text-anchor="middle" fill="#e2e8f0">full</text>
+  </g>
+  <text x="1120" y="286" text-anchor="end" font-family="Segoe UI, Microsoft YaHei, sans-serif" font-size="16" fill="#64748b">for DeepSeek Harness</text>
+</svg>

package/docs/screenshots/README.md

@@ -0,0 +1,9 @@
+# 截图目录
+
+| 文件 | 内容 | 来源 |
+|---|---|---|
+| `01-overview.png` | 新界面总览：摘要条（受管 3 / 分组 0 / 工具门已开 / 名字 2·路径 1）+ v1 自动迁移提示 + 三个受管对象 + 分段控件 + 未入名单目录 | 户主真机截图（2026-10-21 19:0x，重启后） |
+| `02-group.png` | 「harness 隔离」组卡片：2 个成员、组头分段控件、组内统一「禁」 | **待补**（需在门禁页刷新后截图；户主已确认界面有此组） |
+| `03-picker-fallback.png` | 目录选择器不可用时的退路：未入名单一层目录 + 路径输入 | **待补**（当前宿主 `picker=false`） |
+
+> 截图只用于文档；不含任何受管目录内部内容。

package/lib/audit.js

@@ -0,0 +1,92 @@
+/**
+ * 门禁 · 访问审计（受管辖通道的每一次判定都留痕）
+ *
+ * 落点：`~/.dsh/dsh-isolation-gate/access-log.jsonl`（插件数据位，非源码位）。
+ * 记什么：时间 · 通道 · 名字 · 级别 · 操作 · 放行/拒绝。
+ * **不记**隔离区内部内容 —— 只记路径名与判定结果（红线：只碰名字与存在性）。
+ *
+ * 有上限（默认 500 行）：超了从头截掉，避免日志无限长。
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** 插件数据目录（房规：插件数据进 `~\.dsh\<插件名>\`）。 */
+export const DEFAULT_LOG_DIR = join(homedir(), '.dsh', 'dsh-isolation-gate');
+
+/** 审计日志默认落点。 */
+export const DEFAULT_LOG_PATH = join(DEFAULT_LOG_DIR, 'access-log.jsonl');
+
+/** 保留的最大行数。 */
+export const DEFAULT_MAX_ENTRIES = 500;
+
+function pad(n) {
+  return String(n).padStart(2, '0');
+}
+
+function stamp(now) {
+  const d = now instanceof Date ? now : new Date();
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+    `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+  );
+}
+
+/** 读日志（逆序，最新在前）。永不抛异常。 */
+export function readAudit(logPath = DEFAULT_LOG_PATH, limit = 20) {
+  if (!existsSync(logPath)) return { ok: true, exists: false, entries: [], error: null };
+  let text;
+  try {
+    text = readFileSync(logPath, 'utf8');
+  } catch (error) {
+    return { ok: false, exists: true, entries: [], error: `审计日志读取失败：${error?.message ?? String(error)}` };
+  }
+  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1);
+  const lines = text.split(/\r?\n/).filter((line) => line.trim() !== '');
+  const entries = [];
+  for (let i = lines.length - 1; i >= 0 && entries.length < Math.max(1, limit); i -= 1) {
+    try {
+      entries.push(JSON.parse(lines[i]));
+    } catch {
+      entries.push({ raw: lines[i], parseError: true });
+    }
+  }
+  return { ok: true, exists: true, total: lines.length, entries, error: null };
+}
+
+/**
+ * 追加一条审计。失败只报错、不抛 —— 审计不该拦住主流程。
+ * @param {string} logPath
+ * @param {{channel:string,name?:string,level?:string,op:string,allowed:boolean,detail?:string}} entry
+ */
+export function appendAudit(logPath, entry, options = {}) {
+  const maxEntries = Number.isInteger(options.maxEntries) && options.maxEntries > 0 ? options.maxEntries : DEFAULT_MAX_ENTRIES;
+  const record = {
+    at: options.now instanceof Date ? options.now.toISOString() : new Date().toISOString(),
+    atLocal: stamp(options.now),
+    channel: entry?.channel ?? 'unknown',
+    name: entry?.name ?? null,
+    level: entry?.level ?? null,
+    op: entry?.op ?? null,
+    allowed: entry?.allowed === true,
+    detail: typeof entry?.detail === 'string' ? entry.detail.slice(0, 300) : undefined,
+  };
+  try {
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify(record)}\n`, 'utf8');
+  } catch (error) {
+    return { ok: false, error: `审计写入失败：${error?.message ?? String(error)}` };
+  }
+  // 超上限就该截断（低频动作，读一次整文件可以接受）。
+  try {
+    const text = readFileSync(logPath, 'utf8');
+    const lines = text.split(/\r?\n/).filter((line) => line.trim() !== '');
+    if (lines.length > maxEntries) {
+      writeFileSync(logPath, `${lines.slice(lines.length - maxEntries).join('\n')}\n`, 'utf8');
+    }
+  } catch {
+    /* 截断失败无所谓：宁可日志长一点，也不能因此丢记录或报错 */
+  }
+  return { ok: true, record };
+}