dsh-engram 0.3.3 → 0.3.5

package/scripts/dsh-engram.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * dsh-engram CLI — the from-scratch user's window into Context GC.
+ *
+ *   npx dsh-engram status    # what is Context GC doing right now (host + web)
+ *   npx dsh-engram doctor    # status + ranked next steps for the gaps it finds
+ *   npx dsh-engram enable    # re-run the boot-time web auto-wiring (usually a no-op)
+ *   npx dsh-engram revert    # restore the stock compaction rows everywhere —
+ *                            #   run BEFORE uninstalling dsh-engram
+ *
+ * `status`/`doctor` read the durable snapshot the plugin writes at boot
+ * (`$DSH_HOME/engram/context-gc.status.json`) and cross-check the live preset
+ * files. `enable`/`revert` act on preset compositions found under the shipped
+ * and user preset roots (or a single file via `--file <path>`).
+ */
+import { readFile, readdir, access } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { dirname, basename, resolve, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import {
+  compactionWireStatus,
+  provisionWebCompaction,
+  revertWebCompaction,
+} from "../lib/web-provision.js";
+import { contextGcStatusPath, readContextGcStatus } from "../lib/status.js";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function log(line) {
+  process.stdout.write(`${line}\n`);
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const COMPOSITION_NAMES = ["agent.cordis.yml", "agent.json"];
+
+async function compositionIn(dir) {
+  for (const name of COMPOSITION_NAMES) {
+    const candidate = join(dir, name);
+    if (await exists(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/** Preset roots this CLI can act on: last-boot facts + the two well-known ones. */
+async function discoverRoots(status) {
+  const roots = [];
+  const seen = new Set();
+  const push = (root) => {
+    const abs = resolve(root);
+    if (seen.has(abs)) return;
+    seen.add(abs);
+    roots.push(abs);
+  };
+  // Recorded directly from the last boot (authoritative for real installs).
+  for (const entry of status?.web?.presets ?? []) {
+    if (typeof entry?.path === "string") push(dirname(entry.path));
+  }
+  // Well-known roots: shipped harness + the user root.
+  push(resolve(REPO_ROOT, "..", "deepseek-harness/apps/cli/config/agent-presets"));
+  const dshHome = process.env.DSH_HOME ?? join(homedir(), ".dsh");
+  push(join(dshHome, ".agent-presets"));
+  return roots;
+}
+
+/** Discover preset compositions, shadowing duplicate ids like the roster does. */
+async function discoverPresets(status) {
+  const seen = new Set();
+  const presets = [];
+  for (const root of await discoverRoots(status)) {
+    let entries = [];
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (seen.has(entry.name)) continue;
+      const file = await compositionIn(join(root, entry.name));
+      if (file === undefined) continue;
+      seen.add(entry.name);
+      presets.push({ id: entry.name, path: file });
+    }
+  }
+  return presets;
+}
+
+function hostLine(host) {
+  if (host === "context-gc") return "Context GC（机械驱逐 + 重取指针）";
+  if (host === "default") return "DSH 默认 LLM 摘要（gcReplacesCompaction:false）";
+  if (host === "unavailable") return "未接管（引擎不可用）";
+  return "未知（尚未记录）";
+}
+
+function webLine(entry) {
+  const action = entry?.action ?? "?";
+  switch (entry?.action) {
+    case "swapped": return `已接管（${entry.path}）`;
+    case "already": return `已接管 · 配置一致（${entry.path}）`;
+    case "skipped": return `未接管 · ${entry.reason === "custom" ? "自定义/无 compaction 布局，不碰" : entry.reason ?? "跳过"}（${entry.path}）`;
+    case "failed": return `失败 · ${entry.reason ?? "?"}（${entry.path}）`;
+    default: return `${action} · ${entry?.path ?? "?"}`;
+  }
+}
+
+async function printStatus() {
+  const status = await readContextGcStatus();
+  const presets = await discoverPresets(status);
+
+  log("── dsh-engram Context GC 状态 ──────────────────────────────");
+  if (status === undefined) {
+    log("  尚无状态文件（插件还没写过，或本机没跑过 dsh web）。");
+  } else {
+    log(`  状态快照：${new Date(status.writtenAt ?? 0).toLocaleString()}（插件上次启动时写入）`);
+    log(`  host 平面：${hostLine(status.host)}`);
+    log(`  web 平面：${status.web?.action === "pending" ? "启动中（agentPresets 尚未就绪）" : `上次装配 ${status.web?.action ?? "?"}，${(status.web?.presets ?? []).length} 个预设`}`);
+    log(`  配置：autoWebCompaction=${status.configSource?.autoWebCompaction ?? "?"} · gcReplacesCompaction=${status.configSource?.gcReplacesCompaction ?? "?"} · gcNarrative=${status.configSource?.gcNarrative ?? "?"}`);
+  }
+
+  log("");
+  if (presets.length === 0) {
+    log("  未发现任何 web 代理预设（shipped 根与用户根都找不到）。");
+  } else {
+    log(`  ── web 预设现场（${presets.length} 个）──`);
+    for (const preset of presets) {
+      let text;
+      try {
+        text = await readFile(preset.path, "utf8");
+      } catch {
+        log(`  ${preset.id}: 无法读取`);
+        continue;
+      }
+      const cs = compactionWireStatus(text);
+      const note = cs === "wired"
+        ? "已接管（dsh-engram/compaction 行）"
+        : cs === "stock"
+          ? "出厂布局，重启 dsh web 后自动接管"
+          : "自定义/无 compaction，插件不碰";
+      log(`  ${preset.id}: ${cs} — ${note}`);
+    }
+  }
+  return status;
+}
+
+async function printDoctor() {
+  const status = await printStatus();
+  log("");
+  log("── 建议（doctor）──────────────────────────────────────────");
+  const prev = status?.web?.presets ?? [];
+  const presets = await discoverPresets(status);
+  const issues = [];
+
+  if (status === undefined) {
+    issues.push("尚无状态快照：把 dsh-engram 装进 profile 并启动一次（dsh web / dsh headless），插件会在启动时写入状态与自动装配。");
+  } else if (status.host !== "context-gc") {
+    issues.push(
+      `host 平面 ${status.host}：${status.host === "unavailable"
+        ? "引擎不可用——确认 @deepseek-ai/dsh-compaction-basic 依赖已安装（见启动日志 dsh-compaction-basic unavailable）。"
+        : "当前是 DSH 默认 LLM 摘要——要在 host 平面启用 Context GC，把 gcReplacesCompaction 设为 true。"}`,
+    );
+  }
+
+  const stockLeft = presets.filter((p) => {
+    try {
+      return compactionWireStatus(readFileSyncSafe(p.path)) === "stock";
+    } catch {
+      return false;
+    }
+  });
+  if (stockLeft.length > 0) {
+    issues.push(`web 平面还有 ${stockLeft.length} 个出厂布局预设未接管（${stockLeft.map((p) => p.id).join("、")}）：重启 dsh web 让自动装配跑一次，或 npx dsh-engram enable。`);
+  }
+  const customLeft = presets.filter((p) => {
+    try {
+      return compactionWireStatus(readFileSyncSafe(p.path)) === "custom";
+    } catch {
+      return false;
+    }
+  });
+  if (customLeft.length > 0) {
+    issues.push(`${customLeft.length} 个预设是自定义/无 compaction 布局（${customLeft.map((p) => p.id).join("、")}），插件不会碰；需要的话手动把 compaction 组换成 dsh-engram/compaction。`);
+  }
+  if (presets.some((p) => compactionWireStatus(readFileSyncSafe(p.path)) === "wired")) {
+    issues.push("有预设已被接管：卸载 dsh-engram 前先 npx dsh-engram revert，避免预设留下悬空引用。");
+  }
+  if (issues.length === 0) {
+    log("  一切正常：host 平面 + 全部 stock 预设都已接管 Context GC。");
+    return;
+  }
+  issues.forEach((line, index) => log(`  ${index + 1}. ${line}`));
+}
+
+/** Read helper that never throws (used by the sync-style filtering above). */
+function readFileSyncSafe(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function toService(preset) {
+  return {
+    async resolve() {
+      return { id: preset.id, path: preset.path };
+    },
+  };
+}
+
+async function runEnableRevert(command, fileFlag) {
+  const status = await readContextGcStatus();
+  let presets;
+  if (fileFlag !== undefined) {
+    const abs = resolve(fileFlag);
+    if (!(await exists(abs))) throw new Error(`file not found: ${abs}`);
+    presets = [{ id: basename(dirname(abs)), path: abs }];
+  } else {
+    presets = await discoverPresets(status);
+  }
+  if (presets.length === 0) {
+    log("未发现可操作预设。用 --file <path> 明确指定一个预设组合文件。");
+    return;
+  }
+
+  log(`dsh-engram: ${command} — ${presets.length} 个预设`);
+  let changed = 0;
+  for (const preset of presets) {
+    const service = toService(preset);
+    const report = command === "enable"
+      ? await provisionWebCompaction(service, { log })
+      : await revertWebCompaction(service, { log });
+    const entry = report.presets[0];
+    log(`  ${preset.id}: ${entry?.action ?? report.action}${entry?.reason ? ` (${entry.reason})` : ""}`);
+    if (entry?.action === "swapped" || entry?.action === "reverted") changed += 1;
+  }
+  if (command === "enable" && changed > 0) log("  下一步：重启 dsh web 让会话生效。");
+  if (command === "revert" && changed > 0) log("  已全部还原为出厂 compaction 行——可以安全卸载 dsh-engram。");
+}
+
+async function main() {
+  const [, , rawCommand, ...rest] = process.argv;
+  const command = rawCommand ?? "status";
+  const fileFlagIndex = rest.indexOf("--file");
+  const fileFlag = fileFlagIndex >= 0 ? rest[fileFlagIndex + 1] : undefined;
+  if (command === "status") {
+    await printStatus();
+  } else if (command === "doctor") {
+    await printDoctor();
+  } else if (command === "enable" || command === "revert") {
+    await runEnableRevert(command, fileFlag);
+  } else {
+    throw new Error(`未知命令 "${command}"（用 status | doctor | enable | revert）`);
+  }
+}
+
+await main().catch((error) => {
+  process.stderr.write(`dsh-engram: ${String(error?.message ?? error)}\n`);
+  process.exitCode = 1;
+});

package/scripts/engram-web-compaction.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Deprecated alias — forwards to the shipped `dsh-engram` CLI so the earlier
+ * `npm run web-compaction:*` scripts keep working. New code should call
+ * `node scripts/dsh-engram.mjs status|doctor|enable|revert`.
+ */
+await import("./dsh-engram.mjs");

package/scripts/prepublish-check.mjs

@@ -0,0 +1,106 @@
+/**
+ * Pre-publish self-check (runs on `npm publish` via prepublishOnly, and
+ * directly via `npm run prepublishOnly`).
+ *
+ * Packs the tarball, then installs it into a temp dir together with the
+ * optional peer packages exactly as a real profile's pnpm would resolve
+ * them, and finally imports BOTH the host entry (lib/index.js) and the
+ * client bundle (lib/client.js) from the INSTALLED artifact. Fails with a
+ * non-zero exit when the published fileset is missing anything the plugin
+ * needs to load — the tarball-only import is the genuine surface, not the
+ * working-tree files.
+ *
+ * Requires network access to the npm registry for the @deepseek-ai peers
+ * and zod; skipped cleanly on failure? — no: an unverifiable publish is
+ * refused.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const tmp = mkdtempSync(join(tmpdir(), "dsh-engram-pack-"));
+const PEERS = [
+  "@deepseek-ai/cordis@^4.0.1",
+  "@deepseek-ai/dsh-settings@^0.1.0-rc.7",
+  "@deepseek-ai/dsh-storage-domain@^0.1.0-rc.7",
+  "@deepseek-ai/schemastery@^3.18.1",
+];
+
+function sh(cmd, args, cwd) {
+  execFileSync(cmd, args, { cwd, stdio: "inherit" });
+}
+
+/** Newest mtime (ms) of any client source file under `dir` (recursive). */
+function newestSourceMtime(dir, acc = 0) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      acc = newestSourceMtime(p, acc);
+    } else if (/\.(ts|tsx|mjs)$/.test(entry.name)) {
+      acc = Math.max(acc, statSync(p).mtimeMs);
+    }
+  }
+  return acc;
+}
+
+/**
+ * 0. Fail the publish when the shipped client bundle is stale — the exact
+ *    0.3.4-class hazard (edit client/src, forget `npm run build:client`,
+ *    publish an old GUI). Cheap, and saves a broken release.
+ */
+function assertClientBundleFresh() {
+  const newestSrc = newestSourceMtime(join(root, "client/src"));
+  if (newestSrc === 0) return;
+  for (const bundle of ["lib/client.js", "lib/esrModel.mjs"]) {
+    const p = join(root, bundle);
+    if (!existsSync(p)) throw new Error(`${bundle} is missing — run \`npm run build:client\` before publishing`);
+    if (statSync(p).mtimeMs < newestSrc) {
+      throw new Error(`${bundle} is stale (a client/src file is newer) — run \`npm run build:client\` before publishing`);
+    }
+  }
+}
+
+try {
+  assertClientBundleFresh();
+
+  // 1. pack. npm publish --dry-run propagates npm_config_dry_run into this
+  //    script's child npm, which would make the nested pack a no-op — pin
+  //    dry-run off explicitly so the tarball is always really produced.
+  sh("npm", ["pack", "--dry-run=false", "--pack-destination", tmp], root);
+  const tarball = readdirSync(tmp).find((f) => f.endsWith(".tgz"));
+  if (tarball === undefined) throw new Error("no packed tarball produced");
+
+  // 2. install the artifact + peers into the temp dir (mirrors a real profile);
+  //    --dry-run=false again because npm publish --dry-run propagates the flag
+  //    into child npm and a no-op install would leave nothing to import.
+  sh("npm", ["install", "--no-audit", "--no-fund", "--dry-run=false", join(tmp, tarball), ...PEERS], tmp);
+
+  // 3. import host + client from the INSTALLED fileset (name may be scoped:
+  //    @scope/pkg installs under node_modules/@scope/pkg)
+  const name = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).name;
+  const installed = join(tmp, "node_modules", ...name.split("/"));
+  const manifest = JSON.parse(readFileSync(join(installed, "package.json"), "utf8"));
+  const host = await import(pathToFileURL(join(installed, manifest.main)).href);
+  // resolveConfig is a deliberate public export (settings test builds the
+  // real DEFAULTS from it); widen the host surface consciously, not silently.
+  const expected = ["apply", "inject", "name", "resolveConfig"].sort().join(",");
+  const actual = Object.keys(host).sort().join(",");
+  if (actual !== expected) {
+    throw new Error(`host exports mismatch: got ${actual}, want ${expected}`);
+  }
+  // 4. the client bundle is loaded by the web shell with its externals
+  //    (react, @deepseek-ai/dsh-client-*) provided by the host — it is NOT a
+  //    standalone-loadable module, so verify presence + size instead of import.
+  const clientStats = statSync(join(installed, "lib/client.js"));
+  if (clientStats.size < 10 * 1024) {
+    throw new Error(`suspiciously small client bundle: ${clientStats.size} bytes`);
+  }
+  console.log(
+    `✓ packed ${tarball}: host(${actual}) import OK, client bundle present (${clientStats.size} bytes)`,
+  );
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}

package/scripts/setup-links.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * dsh-engram 开发/本地链接安装依赖脚本（跨平台）。
+ *
+ * 为什么需要它：
+ *   dsh-engram 宿主侧运行期 import：
+ *     - zod（registry 唯一外部依赖）
+ *     - @deepseek-ai/{dsh-settings,dsh-storage-domain,schemastery}（harness 工作区包）
+ *     - @deepseek-ai/{dsh-compaction,dsh-compaction-basic,dsh-llm}（Context GC 引擎，
+ *       host 侧动态导入，缺省时引擎静默不加载、DSH 沿用默认 compact）
+ *   当插件以 `link:` 方式进 profile 时，Node 从插件的真实路径向上解析 import，
+ *   这层 node_modules 不随 git 分发，换机器就会 ERR_MODULE_NOT_FOUND。本脚本
+ *   一条命令重建：
+ *     - zod            → 复用 harness pnpm store 的 zod@4.x，找不到则 `npm install`
+ *     - @deepseek-ai/* → 符号链接到 harness 工作区（同 checkout 即同版本）
+ *
+ * 用法：
+ *   node scripts/setup-links.mjs            # 建立/修复依赖链接
+ *   node scripts/setup-links.mjs --check    # 只检查并打印，不写入
+ *
+ * 环境变量：
+ *   DSH_HARNESS_DIR   harness checkout 路径（默认取仓库上一级 ../deepseek-harness）
+ */
+
+import { existsSync, mkdirSync, readdirSync, readlinkSync, rmdirSync, symlinkSync, unlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const NODE_MODULES = join(REPO_ROOT, "node_modules");
+const SCOPE = join(NODE_MODULES, "@deepseek-ai");
+const CHECK_ONLY = process.argv.includes("--check");
+const IS_WIN = process.platform === "win32";
+
+function looksLikeHarness(dir) {
+  return (
+    existsSync(join(dir, "vendor", "schemastery", "package.json")) &&
+    existsSync(join(dir, "packages", "settings", "settings", "package.json"))
+  );
+}
+
+/** Locate the harness checkout directory. */
+function findHarness() {
+  if (process.env.DSH_HARNESS_DIR) {
+    const p = resolve(process.env.DSH_HARNESS_DIR);
+    if (!existsSync(p)) throw new Error(`DSH_HARNESS_DIR 不存在: ${p}`);
+    return p;
+  }
+  // common layouts:
+  //   harness/  + repo at harness/../deepseek-harness          (sibling of repo)
+  //   E:\deepseek-harness + E:\kototoro_demo\dsh-engram          (sibling of repo's parent)
+  for (const candidate of [
+    resolve(REPO_ROOT, "..", "deepseek-harness"),       // 与仓库平级
+    resolve(REPO_ROOT, "..", "..", "deepseek-harness"), // 与仓库父级平级
+  ]) {
+    if (looksLikeHarness(candidate)) return candidate;
+  }
+  let dir = dirname(REPO_ROOT);
+  for (let i = 0; i < 5; i++) {
+    if (looksLikeHarness(dir)) return dir;
+    dir = dirname(dir);
+  }
+  throw new Error(
+    "找不到 deepseek-harness checkout：请设置 DSH_HARNESS_DIR，或把 dsh-engram 放到 " +
+      "harness 兄弟目录（../deepseek-harness / ../../deepseek-harness）。",
+  );
+}
+
+/** Newest zod@4 package dir inside the harness pnpm store, or null. */
+function findStoreZod(harness) {
+  const store = join(harness, "node_modules", ".pnpm");
+  if (!existsSync(store)) return null;
+  let best = null;
+  let bestMajor = -1;
+  for (const name of readdirSync(store)) {
+    const m = /^zod@(\d+)\./.exec(name);
+    if (!m) continue;
+    const major = Number(m[1]);
+    const pkgDir = join(store, name, "node_modules", "zod");
+    if (existsSync(join(pkgDir, "package.json")) && major > bestMajor) {
+      best = pkgDir;
+      bestMajor = major;
+    }
+  }
+  return best;
+}
+
+/**
+ * The dependency plan: label -> mount point -> source inside the harness.
+ * zod's source is resolved from the pnpm store (or null → npm install).
+ */
+function buildPlan(harness) {
+  const zodDir = findStoreZod(harness);
+  const plan = [
+    {
+      label: "zod",
+      mount: join(NODE_MODULES, "zod"),
+      target: zodDir,
+      npmInstall: zodDir === null,
+    },
+    {
+      label: "@deepseek-ai/dsh-settings",
+      mount: join(SCOPE, "dsh-settings"),
+      target: join(harness, "packages", "settings", "settings"),
+    },
+    {
+      label: "@deepseek-ai/dsh-storage-domain",
+      mount: join(SCOPE, "dsh-storage-domain"),
+      target: join(harness, "packages", "storage", "storage-domain"),
+    },
+    {
+      label: "@deepseek-ai/schemastery",
+      mount: join(SCOPE, "schemastery"),
+      target: join(harness, "vendor", "schemastery"),
+    },
+    {
+      label: "@deepseek-ai/dsh-compaction",
+      mount: join(SCOPE, "dsh-compaction"),
+      target: join(harness, "packages", "compaction", "compaction"),
+    },
+    {
+      label: "@deepseek-ai/dsh-compaction-basic",
+      mount: join(SCOPE, "dsh-compaction-basic"),
+      target: join(harness, "packages", "compaction", "compaction-basic"),
+    },
+    {
+      label: "@deepseek-ai/dsh-llm",
+      mount: join(SCOPE, "dsh-llm"),
+      target: join(harness, "packages", "llm", "llm"),
+    },
+  ];
+  return plan;
+}
+
+/**
+ * A mount is "installed" when it is:
+ *   - a symlink/junction pointing at the expected source, or
+ *   - a real directory carrying a package.json (e.g. `npm install` output).
+ */
+function isInstalled(mount, expected) {
+  if (existsSync(mount)) {
+    try {
+      if (resolve(readlinkSync(mount)) === resolve(expected)) return true;
+    } catch {
+      /* not a symlink — fall through */
+    }
+    if (existsSync(join(mount, "package.json"))) return true;
+  }
+  return false;
+}
+
+function ensureLink(item) {
+  const { label, mount, target, npmInstall } = item;
+  if (npmInstall && target === null) {
+    if (CHECK_ONLY) {
+      console.log(`  ! ${label}: harness store 无 zod，需运行 \`npm install\``);
+      return;
+    }
+    console.log(`  … ${label}: harness store 无 zod，执行 npm install（请稍候）`);
+    const npm = IS_WIN ? "npm.cmd" : "npm";
+    const r = spawnSync(npm, ["install", "--no-audit", "--no-fund"], {
+      cwd: REPO_ROOT,
+      stdio: "inherit",
+      shell: IS_WIN,
+    });
+    if (r.status !== 0) {
+      console.error(`  ! ${label}: npm install 失败（exit ${r.status}）`);
+      return;
+    }
+    console.log(`  + ${label}: npm install 完成`);
+    return;
+  }
+  if (!existsSync(target)) {
+    console.log(`  ! ${label}: 源不存在（${target}），请检查 harness checkout`);
+    return;
+  }
+  if (existsSync(mount)) {
+    if (isInstalled(mount, target)) {
+      console.log(`  ✓ ${label} -> ${target}`);
+      return;
+    }
+    if (CHECK_ONLY) {
+      console.log(`  ! ${label}: ${mount} 已存在但状态异常，运行脚本修复`);
+      return;
+    }
+    // 允许替换：符号链接直接 unlink；pnpm 预建的空目录用 rmdir 清掉。
+    try {
+      unlinkSync(mount);
+      console.log(`  ~ ${label}: 替换旧链接`);
+      return;
+    } catch {
+      /* not a symlink */
+    }
+    try {
+      if (readdirSync(mount).length === 0) {
+        rmdirSync(mount);
+        console.log(`  ~ ${label}: 移除空目录后重建`);
+      } else {
+        console.log(`  ! ${label}: ${mount} 是含文件的真实目录，无法自动替换，请手动清理后重试`);
+        return;
+      }
+    } catch {
+      console.log(`  ! ${label}: ${mount} 无法自动替换，请手动清理后重试`);
+      return;
+    }
+  }
+  if (CHECK_ONLY) {
+    console.log(`  ! ${label}: 缺失（需创建）`);
+    return;
+  }
+  mkdirSync(dirname(mount), { recursive: true });
+  symlinkSync(target, mount, IS_WIN ? "junction" : "dir");
+  console.log(`  + ${label} -> ${target}`);
+}
+
+try {
+  const harness = findHarness();
+  console.log(`repo    : ${REPO_ROOT}`);
+  console.log(`harness : ${harness}`);
+  for (const item of buildPlan(harness)) ensureLink(item);
+
+  // Self-verify: the whole host module graph must resolve now — this is the
+  // exact condition `dsh web` needs at boot (no more ERR_MODULE_NOT_FOUND).
+  const entry = pathToFileURL(join(REPO_ROOT, "lib", "index.js")).href;
+  const check = spawnSync(
+    process.execPath,
+    ["--input-type=module", "-e",
+      `import(${JSON.stringify(entry)}).then(()=>console.log("host imports OK: " + ${JSON.stringify(entry)})).catch((e)=>{console.error("host imports FAIL: "+e.message);process.exit(1)})`],
+    { encoding: "utf8" },
+  );
+  const out = (check.stdout || check.stderr || "").toString().trim();
+  console.log(`自检 : ${out || "（无输出，exit " + check.status + "）"}`);
+  if (check.status !== 0) {
+    console.error("依赖自检未通过，请检查上方输出后重试（或不放心先跑 --check 看看）。");
+    process.exit(1);
+  }
+} catch (error) {
+  console.error(`setup-links 失败: ${error.message}`);
+  process.exit(1);
+}