@morehao/dsh-skills-console 0.0.0 → 0.2.1

package/lib/core/cli.js

@@ -0,0 +1,232 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export class CliUnavailableError extends Error {
+  constructor(reason) {
+    super(reason || 'skills CLI not found');
+    this.code = 'error.skills.cli-missing';
+    this.reason = reason;
+  }
+}
+
+export class CliFailedError extends Error {
+  constructor(message, detail) {
+    super(message);
+    this.code = detail?.timedOut ? 'error.skills.cli-timeout' : 'error.skills.cli-failed';
+    this.detail = detail;
+  }
+}
+
+function isExecutable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function findInPath(command, envPath) {
+  for (const dir of String(envPath || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, command);
+    if (isExecutable(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * CLI 定位四层（设计 §8.2）：显式覆盖 → 插件/宿主自带依赖 → PATH → npx。
+ * 每一层都记来源，诊断页要展示"这次到底跑的哪一个"。
+ */
+export function locateCli({ env = process.env, logger = () => {} } = {}) {
+  const override = env.DSH_SKILLS_CONSOLE_CLI;
+  if (override && override.trim()) {
+    const parts = override.trim().split(/\s+/);
+    // 覆盖值可能是测试桩：仍然让 `add --help` 自己回答能力位，别替它猜
+    return { command: parts[0], prefixArgs: parts.slice(1), source: 'env-override', jsonCapable: true };
+  }
+
+  // 宿主 profile 里的 skills 依赖（最常见的实际位置）。
+  // 注意：GUI 启动的宿主进程常常拿不到 DSH_PROFILE_DIR，所以再按 DSH_HOME/profiles/* 兜一层探测。
+  const profileDir = env.DSH_PROFILE_DIR;
+  if (profileDir) {
+    const bin = path.join(profileDir, 'node_modules', 'skills', 'bin', 'cli.mjs');
+    if (fs.existsSync(bin)) {
+      return { command: process.execPath, prefixArgs: [bin], source: 'profile-dependency', jsonCapable: true };
+    }
+  }
+  const dshHome = env.DSH_HOME || path.join(env.HOME || '', '.dsh');
+  try {
+    const profiles = fs.readdirSync(path.join(dshHome, 'profiles'), { withFileTypes: true });
+    for (const entry of profiles) {
+      if (!entry.isDirectory()) continue;
+      const bin = path.join(dshHome, 'profiles', entry.name, 'node_modules', 'skills', 'bin', 'cli.mjs');
+      if (fs.existsSync(bin)) {
+        return { command: process.execPath, prefixArgs: [bin], source: `profile:${entry.name}`, jsonCapable: true };
+      }
+    }
+  } catch {
+    // 没有 profiles 目录就继续往下走
+  }
+
+  try {
+    const pkg = require.resolve('skills/package.json');
+    const bin = path.join(path.dirname(pkg), 'bin', 'cli.mjs');
+    if (fs.existsSync(bin)) {
+      return { command: process.execPath, prefixArgs: [bin], source: 'dependency', jsonCapable: true };
+    }
+  } catch {
+    // 没有作为依赖装在本插件可见范围内，继续往下走
+  }
+
+  const onPath = findInPath('skills', env.PATH);
+  if (onPath) return { command: onPath, prefixArgs: [], source: 'path', jsonCapable: true };
+
+  const npx = findInPath('npx', env.PATH);
+  if (npx) {
+    const spec = env.DSH_SKILLS_CONSOLE_NPX_SPEC || 'skills';
+    return { command: npx, prefixArgs: ['-y', spec], source: 'npx', jsonCapable: true };
+  }
+
+  logger('cli.missing');
+  throw new CliUnavailableError('neither `skills` nor `npx` is on PATH');
+}
+
+/** 子进程封装：无 shell、argv 直传、硬超时、输出上限、非交互环境注入。 */
+export function runCli(location, args, { timeoutMs = 120000, signal, env = process.env, maxBytes = 4 * 1024 * 1024 } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(location.command, [...location.prefixArgs, ...args], {
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {
+        ...env,
+        CI: '1',
+        NO_COLOR: '1',
+        TERM: 'dumb',
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_HTTP_LOW_SPEED_LIMIT: '1',
+        GIT_HTTP_LOW_SPEED_TIME: '30',
+      },
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let truncated = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutMs);
+    const onAbort = () => child.kill('SIGKILL');
+    if (signal) signal.addEventListener('abort', onAbort, { once: true });
+
+    child.stdout.on('data', (chunk) => {
+      if (stdout.length + chunk.length > maxBytes) {
+        truncated = true;
+        stdout += chunk.subarray(0, Math.max(0, maxBytes - stdout.length)).toString('utf8');
+        return;
+      }
+      stdout += chunk.toString('utf8');
+    });
+    child.stderr.on('data', (chunk) => {
+      if (stderr.length < 65536) stderr += chunk.toString('utf8');
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      reject(new CliFailedError(error.message, { error }));
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve({ code, stdout, stderr, timedOut, truncated, args });
+    });
+  });
+}
+
+export function createCli({ env = process.env, logger = () => {} } = {}) {
+  let cached = null;
+  let capabilities = null;
+
+  function location() {
+    if (!cached) cached = locateCli({ env, logger });
+    return cached;
+  }
+
+  function call(args, options = {}) {
+    return runCli(location(), args, { env, ...options });
+  }
+
+  const api = {
+    location,
+    call,
+
+    async version() {
+      const result = await call(['--version']);
+      if (result.code !== 0) return null;
+      const match = result.stdout.trim().match(/\d+\.\d+\.\d+[\w.-]*/);
+      return match ? match[0] : null;
+    },
+
+    /** 能力位：`--json` 与 `--full-depth` 任一不支持都要在 UI 上禁用写操作（漏装比不可用更危险）。 */
+    async capabilities({ force = false } = {}) {
+      if (capabilities && !force) return capabilities;
+      const loc = location();
+      if (!loc.jsonCapable) {
+        capabilities = { version: null, json: false, fullDepth: false, source: loc.source, usable: false };
+        return capabilities;
+      }
+      const version = await api.version();
+      const help = await call(['add', '--help']);
+      const text = `${help.stdout}\n${help.stderr}`;
+      capabilities = {
+        version,
+        json: text.includes('--json'),
+        fullDepth: text.includes('--full-depth'),
+        source: loc.source,
+        usable: Boolean(version) && text.includes('--json') && text.includes('--full-depth'),
+      };
+      logger('cli.capabilities', capabilities);
+      return capabilities;
+    },
+
+    /** 列已装技能（全局）。字段只有 F20 那几项，ref/skillPath/hash 必须另读 lock。 */
+    async listGlobal() {
+      const result = await call(['list', '--json', '-g']);
+      if (result.code !== 0) {
+        throw new CliFailedError(`skills list failed`, { stderr: result.stderr, code: result.code });
+      }
+      try {
+        const parsed = JSON.parse(result.stdout);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch (error) {
+        throw new CliFailedError(`skills list returned non-JSON output`, { error: error.message });
+      }
+    },
+
+    /**
+     * 安装：`-a universal` 必带（F17），`--json` 配 `-y`（F11），`--full-depth` 必带（F24）。
+     * 永不带 `--all` / `-a '*'`。
+     */
+    async add({ source, skills = [], timeoutMs = env.DSH_SKILLS_CONSOLE_TIMEOUT_MS ? Number(env.DSH_SKILLS_CONSOLE_TIMEOUT_MS) : 120000 }) {
+      const args = ['add', source, '--skill', ...skills, '-a', 'universal', '-g', '-y', '--json', '--full-depth'];
+      const result = await call(args, { timeoutMs });
+      return result;
+    },
+
+    /** 卸载：绝不带 `-a`（带上反而删不掉真身），没有 `--json`，结论以磁盘核对为准。 */
+    async remove({ names = [], timeoutMs = 120000 }) {
+      const args = ['remove', '-s', ...names, '-g', '-y'];
+      return call(args, { timeoutMs });
+    },
+  };
+
+  return api;
+}

package/lib/core/hash.js

@@ -0,0 +1,46 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+
+function collectFiles(dir, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectFiles(full, out);
+    else if (entry.isFile()) out.push(full);
+    // 符号链接 / 设备文件不计入：与 CLI 的 collectFiles 只收普通文件一致（F6）
+  }
+  return out;
+}
+
+/**
+ * 逐字复刻 skills CLI 的内容哈希（F6）：
+ * 只收普通文件 → 跳过 `.git` / `node_modules` → 相对路径 `/` 归一 → localeCompare 排序
+ * → 先 update(路径) 再 update(内容) → sha256。
+ *
+ * 用途只有一个：进 L1「本地有没有被改过」的基线，绝不与上游 tree SHA 混用。
+ */
+export function contentHash(dir) {
+  const files = collectFiles(dir, []).map((file) =>
+    path.relative(dir, file).split(path.sep).join('/'),
+  );
+  files.sort((a, b) => a.localeCompare(b));
+  const hash = crypto.createHash('sha256');
+  for (const rel of files) {
+    hash.update(rel);
+    hash.update(fs.readFileSync(path.join(dir, rel)));
+  }
+  return hash.digest('hex');
+}
+
+export function sha256(text) {
+  return crypto.createHash('sha256').update(text).digest('hex');
+}

package/lib/core/inventory.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { contentHash } from './hash.js';
+import { inspectTarget } from './links.js';
+
+/**
+ * CLI 全局 lock（v3）。读不到、版本不认识、结构损坏都返回空账 ——
+ * CLI 自己也会在 `version` 缺失或过低时丢弃整个文件（:3755/:3761-3771），这里保持一致。
+ */
+export function readLock(paths) {
+  let raw;
+  try {
+    raw = fs.readFileSync(paths.lockFile, 'utf8');
+  } catch {
+    return { present: false, version: null, skills: {}, problem: null };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.version !== 'number') {
+      return { present: true, version: null, skills: {}, problem: 'lock.version missing' };
+    }
+    if (parsed.version < 3) {
+      return { present: true, version: parsed.version, skills: {}, problem: `lock.version ${parsed.version} too old` };
+    }
+    const skills = parsed.skills && typeof parsed.skills === 'object' ? parsed.skills : {};
+    return { present: true, version: parsed.version, skills, problem: null };
+  } catch (error) {
+    return { present: true, version: null, skills: {}, problem: `lock not JSON: ${error.message}` };
+  }
+}
+
+/** canonical 扫描：`<name>/SKILL.md` 目录包，或 `<name>.md` 平铺（原生刻意不支持嵌套）。 */
+export function scanCanonical(paths) {
+  const dir = paths.canonical;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    let isDir = entry.isDirectory();
+    if (entry.isSymbolicLink()) {
+      try {
+        isDir = fs.statSync(full).isDirectory();
+      } catch {
+        out.push({ name: entry.name, path: full, kind: 'broken', hasSkillFile: false });
+        continue;
+      }
+    }
+    if (isDir) {
+      const hasSkill = fs.existsSync(path.join(full, 'SKILL.md'));
+      out.push({ name: entry.name, path: full, kind: 'dir', hasSkillFile: hasSkill });
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push({ name: entry.name.slice(0, -3), path: full, kind: 'file', hasSkillFile: true });
+    }
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+export function readFrontmatterDescription(skillPath) {
+  try {
+    const raw = fs.readFileSync(skillPath, 'utf8');
+    const match = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    const line = match[1].split('\n').find((item) => item.trim().startsWith('description:'));
+    if (!line) return null;
+    return line.slice(line.indexOf(':') + 1).trim().replace(/^['"]|['"]$/g, '') || null;
+  } catch {
+    return null;
+  }
+}
+
+function statusOf({ install, check, locallyModified, brokenLinks }) {
+  if (!install) return 'unmanaged';
+  if (locallyModified && check?.status === 'update-available') return 'conflict';
+  if (locallyModified) return 'locally-modified';
+  if (check?.status === 'upstream-deleted') return 'upstream-deleted';
+  if (check?.status === 'update-available') return 'update-available';
+  if (brokenLinks.length > 0) return 'broken-link';
+  if (check?.status === 'current') return 'current';
+  return 'unknown';
+}
+
+/**
+ * 右栏账本：canonical + installs + links。左栏（模型可见）由调用方从 `ctx.skills.snapshot` 取。
+ * 两侧差异本身就是诊断数据，不做自动修复。
+ */
+export function buildLedger({ paths, state, registry, lock, visibleNames = new Map() }) {
+  const scanned = scanCanonical(paths);
+  const targets = registry.detected();
+  const installs = new Map(state.installs.map((item) => [item.name, item]));
+
+  const rows = scanned.map((entry) => {
+    const install = installs.get(entry.name);
+    const lockEntry = lock.skills?.[entry.name] || null;
+    const recordLinks = state.links.filter((link) => link.skill === entry.name);
+
+    // 期望接入矩阵：已有记录 + 各探测目录的现场状态
+    const links = [];
+    for (const target of targets) {
+      const linkPath = path.join(target.dir, entry.name);
+      const live = inspectTarget({ linkPath, canonicalPath: entry.path });
+      if (live.state === 'absent') continue;
+      const recorded = recordLinks.find((link) => link.target === target.target);
+      const stateName =
+        live.state === 'managed-external' && recorded ? 'managed' : live.state;
+      links.push({
+        target: target.target,
+        label: target.label,
+        linkPath,
+        state: stateName,
+        recorded: Boolean(recorded),
+        broken: Boolean(live.broken),
+      });
+    }
+
+    const brokenLinks = links.filter((link) => link.broken);
+    let currentHash = null;
+    let locallyModified = false;
+    if (install && entry.kind === 'dir') {
+      currentHash = contentHash(entry.path);
+      locallyModified = Boolean(install.installedHash) && currentHash !== install.installedHash;
+    }
+
+    const check = state.checks?.[entry.name] || null;
+    const visibleSource = visibleNames.get(entry.name);
+    return {
+      name: entry.name,
+      path: entry.path,
+      kind: entry.kind,
+      hasSkillFile: entry.hasSkillFile,
+      description: entry.hasSkillFile
+        ? readFrontmatterDescription(entry.kind === 'file' ? entry.path : path.join(entry.path, 'SKILL.md'))
+        : null,
+      managed: Boolean(install),
+      subscriptionId: install?.subscriptionId ?? null,
+      source: lockEntry?.source ?? install?.source ?? null,
+      sourceUrl: lockEntry?.sourceUrl ?? null,
+      sourceType: lockEntry?.sourceType ?? null,
+      ref: lockEntry?.ref ?? install?.ref ?? null,
+      skillPath: lockEntry?.skillPath ?? install?.skillPath ?? null,
+      commit: install?.commit ?? null,
+      lockHash: lockEntry?.skillFolderHash ?? null,
+      installedHash: install?.installedHash ?? null,
+      currentHash,
+      installedAt: install?.installedAt ?? null,
+      updatedAt: install?.updatedAt ?? null,
+      mode: install?.mode ?? 'on',
+      scopeProjects: install?.scopeProjects ?? [],
+      backup: install?.backup ?? null,
+      links,
+      brokenLinks: brokenLinks.length,
+      status: statusOf({ install, check, locallyModified, brokenLinks }),
+      check,
+      visible: visibleNames.has(entry.name),
+      visibleSource: visibleSource ?? null,
+      note: entry.kind === 'broken' ? 'canonical 里是一个悬空链接' : entry.hasSkillFile ? null : '缺少 SKILL.md，DSH 无法解析',
+    };
+  });
+
+  // 左栏有、右栏无：别人装的 / 别的 root 里的
+  const visibleOnly = [];
+  for (const [name, source] of visibleNames.entries()) {
+    if (rows.some((row) => row.name === name)) continue;
+    visibleOnly.push({ name, source });
+  }
+
+  return { rows, visibleOnly, scannedAt: new Date().toISOString() };
+}

package/lib/core/links.js

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 四态托管判定（比三态多一个 `managed-external`，见设计 §4.2）+ `absent`。
+ *
+ * - managed           指向 canonical 同名目录，且插件 state 有创建记录
+ * - managed-external  指向 canonical 同名目录，但 state 没有记录（别人建的，可"接管"）
+ * - foreign-link      是软链但指向别处（含悬空）
+ * - real              真实目录或文件（本地实体，绝不覆盖）
+ * - absent            目标位置什么都没有
+ */
+export const LINK_STATES = ['managed', 'managed-external', 'foreign-link', 'real', 'absent'];
+
+function realpathOrNull(target) {
+  try {
+    return fs.realpathSync(target);
+  } catch {
+    return null;
+  }
+}
+
+function hasSkillFile(dir) {
+  try {
+    return fs.statSync(path.join(dir, 'SKILL.md')).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function inspectTarget({ linkPath, canonicalPath }) {
+  let st;
+  try {
+    st = fs.lstatSync(linkPath);
+  } catch {
+    return { state: 'absent', linkPath };
+  }
+
+  if (!st.isSymbolicLink()) return { state: 'real', linkPath };
+
+  let rawTarget = null;
+  try {
+    rawTarget = fs.readlinkSync(linkPath);
+  } catch {
+    rawTarget = null;
+  }
+
+  const resolved = realpathOrNull(linkPath);
+  if (!resolved) return { state: 'foreign-link', linkPath, target: rawTarget, broken: true };
+
+  const canonicalReal = canonicalPath ? realpathOrNull(canonicalPath) : null;
+  const sameSkill = canonicalReal && resolved === canonicalReal && hasSkillFile(resolved);
+  if (sameSkill) return { state: 'managed-external', linkPath, target: rawTarget, resolved };
+  return { state: 'foreign-link', linkPath, target: rawTarget, resolved };
+}
+
+/**
+ * 建链：同层用相对路径（可跨机器迁移），算不出相对就退回绝对路径并标记。
+ * Windows 用 junction + 绝对路径（对齐 CLI 的 createSymlink，F2）。
+ */
+export function createLink({ linkPath, targetPath, platform = process.platform, fsImpl = fs }) {
+  fsImpl.mkdirSync(path.dirname(linkPath), { recursive: true });
+  if (platform === 'win32') {
+    fsImpl.symlinkSync(fsImpl.realpathSync(targetPath), linkPath, 'junction');
+    return { mode: 'junction', linkPath, targetPath };
+  }
+  // 非 Windows 一律用相对软链：同层时是 `../../.agents/skills/<name>`，跨层时由 path.relative 算出距离。
+  const rel = path.relative(path.dirname(linkPath), targetPath);
+  fsImpl.symlinkSync(rel || targetPath, linkPath, 'dir');
+  return { mode: 'relative', linkPath, targetPath, linkTarget: rel };
+}
+
+/** 删除链接：只删软链，且默认只删指向 canonical 的（`force` 仅用于回收悬空链）。 */
+export function removeLink({ linkPath, canonicalPath, force = false }) {
+  let st;
+  try {
+    st = fs.lstatSync(linkPath);
+  } catch {
+    return { removed: false, reason: 'absent' };
+  }
+  if (!st.isSymbolicLink()) return { removed: false, reason: 'not-a-link' };
+  if (!force) {
+    const resolved = realpathOrNull(linkPath);
+    const canonicalReal = canonicalPath ? realpathOrNull(canonicalPath) : null;
+    if (!resolved || !canonicalReal || resolved !== canonicalReal) {
+      return { removed: false, reason: 'not-managed' };
+    }
+  }
+  fs.unlinkSync(linkPath);
+  return { removed: true };
+}
+
+/** 幂等建链：已存在同内容链接 → 跳过；其他任何占用 → 跳过并说明原因。 */
+export function ensureLink({ linkPath, canonicalPath }) {
+  const current = inspectTarget({ linkPath, canonicalPath });
+  if (current.state === 'managed' || current.state === 'managed-external') {
+    return { created: false, state: current.state, linkPath };
+  }
+  if (current.state !== 'absent') {
+    return { created: false, state: current.state, linkPath, skipped: true };
+  }
+  const created = createLink({ linkPath, targetPath: canonicalPath });
+  return { created: true, state: 'managed', ...created };
+}

package/lib/core/log.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_LOG_BYTES = 1024 * 1024;
+
+/** JSONL 事件日志：1MB 滚动一次（`.1` 覆盖）。写失败不影响主流程。 */
+export function createLogger(file) {
+  return function log(event, detail) {
+    try {
+      if (fs.existsSync(file) && fs.statSync(file).size > MAX_LOG_BYTES) {
+        fs.renameSync(file, `${file}.1`);
+      }
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.appendFileSync(
+        file,
+        `${JSON.stringify({ at: new Date().toISOString(), event, ...(detail || {}) })}\n`,
+        'utf8',
+      );
+    } catch {
+      // 日志永远不该让操作失败
+    }
+  };
+}

package/lib/core/paths.js

@@ -0,0 +1,54 @@
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * 所有路径集中在这里，任何模块都不许自己拼 `~`。
+ * 覆盖顺序：显式 overrides（测试）> 环境变量 > 默认值。
+ */
+export function createPaths(env = process.env, overrides = {}) {
+  const home = overrides.home ?? env.HOME ?? os.homedir();
+  // 有些 agent 把全局技能放在 XDG config 下（opencode / amp / devin…）
+  const configHome = overrides.configHome ?? env.XDG_CONFIG_HOME ?? path.join(home, '.config');
+  const dshHome = overrides.dshHome ?? env.DSH_HOME ?? path.join(home, '.dsh');
+  const stateDir =
+    overrides.stateDir ?? env.DSH_SKILLS_CONSOLE_HOME ?? path.join(dshHome, 'skills-console');
+
+  return {
+    home,
+    configHome,
+    dshHome,
+    stateDir,
+    /** canonical 真身：CLI 唯一的落点（F1） */
+    canonical: path.join(home, '.agents', 'skills'),
+    /** CLI 全局 lock（F4） */
+    lockFile: path.join(home, '.agents', '.skill-lock.json'),
+    /** DSH 原生 user-dsh 根（rank 400） */
+    dshGlobalSkills: path.join(dshHome, 'skills'),
+    stateFile: path.join(stateDir, 'state.json'),
+    backupsDir: path.join(stateDir, 'backups'),
+    trashDir: path.join(stateDir, 'trash'),
+    logFile: path.join(stateDir, 'dsh-skills-console.log'),
+  };
+}
+
+/** 原生 project-dsh 根（rank 100）：`<projectRoot>/.dsh/skills`。 */
+export function projectSkillsDir(projectRoot) {
+  return path.join(projectRoot, '.dsh', 'skills');
+}
+
+/** 项目根 = 最近含 `.git` 的祖先，无则返回 null（F28）。 */
+export function findProjectRoot(startDir, existsSync) {
+  let current = path.resolve(startDir || process.cwd());
+  for (;;) {
+    if (existsSync(path.join(current, '.git'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** a 是否等于 b 或位于 b 之下（路径包含校验，防穿越）。 */
+export function isInside(parent, child) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}