@morehao/dsh-skills-console 0.2.4 → 0.3.0

package/lib/core/installer.js

@@ -0,0 +1,351 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { extractTarball } from './archive.js';
+import { contentHash } from './hash.js';
+import { discoverSkills } from './discovery.js';
+import { gitTreeSha } from './git-tree.js';
+import { createBackup, pruneBackups, readBackup, restoreBackup } from './trash.js';
+import { makeLockEntry, readLockFile, updateLock } from './lock.js';
+import { parseSource } from './updates.js';
+import { downloadTarball } from './remote.js';
+
+/**
+ * Native Installer：canonical（`~/.agents/skills`）与 v3 lock 的**唯一写入者**。
+ *
+ * 事务边界（设计 §核心流程/安装）：
+ * 1. 下载 + 安全解压 + 发现全部在临时目录完成；此时 canonical/lock 一个字节都没动。
+ * 2. 校验 lock 可写（版本/损坏在下载前就失败）。
+ * 3. 需要覆盖的旧目录先 `createBackup`，再把 staging 复制到 canonical 下的同盘临时目录，
+ *    逐个 `rename` 到最终位置（同文件系统，单目录原子替换）。
+ * 4. 所有目录就位后**一次** `updateLock` 写全部条目（`expectedDigest` 防外部并发）。
+ * 5. 任一步失败：反向删除已 promote 的目录、从备份恢复旧目录；lock 未写或保持原样。
+ *
+ * 只负责文件与 lock，不碰 state / 链接 / 回收站（那些仍是 Service 的职责）。
+ */
+
+export class InstallerError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = 'InstallerError';
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+function nearestExisting(dir) {
+  let current = path.resolve(dir);
+  for (;;) {
+    if (fs.existsSync(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return current;
+    current = parent;
+  }
+}
+
+function assertSafeSkillName(name) {
+  if (typeof name !== 'string' || name.length === 0 || name.length > 120) {
+    throw new InstallerError('invalid-name', `技能名非法: ${String(name)}`);
+  }
+  if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+    throw new InstallerError('invalid-name', `技能名不能含路径分隔符: ${name}`);
+  }
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(name)) {
+    throw new InstallerError('invalid-name', `技能名含控制字符: ${JSON.stringify(name)}`);
+  }
+  return name;
+}
+
+function copyTree(from, to) {
+  fs.cpSync(from, to, { recursive: true, dereference: false, preserveTimestamps: true });
+}
+
+function validIsoOrUndefined(value) {
+  return typeof value === 'string' && Number.isFinite(Date.parse(value)) ? value : undefined;
+}
+
+function normalizeError(error) {
+  if (error instanceof InstallerError) return error;
+  const code = error?.code || 'install-failed';
+  return new InstallerError(code, error?.message || String(error), {
+    cause: error,
+    status: error?.status ?? null,
+  });
+}
+
+export function createInstaller({
+  paths,
+  env = process.env,
+  fetchImpl = fetch,
+  token,
+  logger = () => {},
+} = {}) {
+  const authToken = token ?? env.GITHUB_TOKEN ?? env.GH_TOKEN ?? null;
+
+  /** 与旧 `/state.cli` 兼容的就绪状态：只有 lock 与 canonical 都可写时 usable 才为 true。 */
+  function readiness() {
+    let problem = null;
+    try {
+      readLockFile(paths.lockFile);
+    } catch (error) {
+      problem = error?.code || 'lock-unreadable';
+    }
+    let writable = false;
+    try {
+      fs.accessSync(nearestExisting(paths.canonical), fs.constants.W_OK);
+      writable = true;
+    } catch {
+      writable = false;
+    }
+    const usable = !problem && writable;
+    return {
+      usable,
+      source: 'native',
+      version: null,
+      json: true,
+      fullDepth: true,
+      problem: problem || (writable ? null : 'canonical-not-writable'),
+    };
+  }
+
+  /**
+   * 安装/重装一组技能。
+   * @param {{source:string, ref?:string|null, commit?:string|null, subpath?:string|null,
+   *          names?:string[], expectedEntries?:Array<{name:string, treeSha?:string|null}>}} options
+   */
+  async function install({ source, ref = null, commit = null, subpath = null, names = [], expectedEntries = null, strict = false } = {}) {
+    const parsed = parseSource(source);
+    if (!parsed) throw new InstallerError('bad-source', `只接受 owner/repo 或 GitHub URL: ${source}`);
+    const canonicalSource = `${parsed.owner}/${parsed.repo}`;
+    const pin = commit || ref;
+    if (typeof pin !== 'string' || pin.length === 0) {
+      throw new InstallerError('missing-ref', '安装需要 commit 或 ref');
+    }
+    const requested = (Array.isArray(names) ? names : []).filter(Boolean);
+    if (new Set(requested).size !== requested.length) {
+      throw new InstallerError('duplicate-selection', '选择列表里有重复技能名');
+    }
+
+    // 下载前先确认 lock 可写：坏 lock / 版本过高不应该先花一次网络请求
+    const lockBefore = readLockFile(paths.lockFile);
+
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'dshsc-install-'));
+    const tarball = path.join(tempRoot, 'repo.tar.gz');
+    const staging = path.join(tempRoot, 'stage');
+    const backups = new Map();
+    const attempted = [];
+    let preparedRoot = null;
+
+    try {
+      const downloaded = await downloadTarball({
+        source: canonicalSource,
+        ref: pin,
+        token: authToken,
+        dest: tarball,
+        fetchImpl,
+      });
+      const extracted = await extractTarball({ tarball, dest: staging });
+      const discovered = discoverSkills({ dir: extracted.dir, subpath, repoName: parsed.repo });
+      if (discovered.length === 0) {
+        throw new InstallerError('no-skills', `${canonicalSource} 里没有找到 SKILL.md`);
+      }
+
+      const available = new Map(discovered.map((skill) => [skill.name, skill]));
+      const selected =
+        requested.length > 0
+          ? requested.map((name) => {
+              const skill = available.get(name);
+              if (!skill) {
+                throw new InstallerError('skill-not-found', `${canonicalSource} 里找不到技能 ${name}`, {
+                  name,
+                  available: [...available.keys()],
+                });
+              }
+              return skill;
+            })
+          : discovered;
+
+      const planned = selected.map((skill) => ({
+        ...skill,
+        treeSha: gitTreeSha(skill.dirPath),
+        contentHash: contentHash(skill.dirPath),
+      }));
+
+      const warnings = [];
+      const expected = new Map((expectedEntries || []).map((entry) => [entry.name, entry]));
+      const mismatched = [];
+      for (const item of planned) {
+        const want = expected.get(item.name);
+        if (want?.treeSha && want.treeSha !== item.treeSha) {
+          const detail = {
+            name: item.name,
+            warning: '本地 tree SHA 与快照不一致（可能下载到了别的 commit）',
+            expected: want.treeSha,
+            actual: item.treeSha,
+          };
+          mismatched.push(detail);
+          warnings.push(detail);
+        }
+      }
+      // 更新要求「下载到的内容」与计划中的目标完全一致；普通安装只警告，不阻断。
+      if (strict && mismatched.length > 0) {
+        throw new InstallerError('tree-mismatch', `下载内容与目标 tree 不一致: ${mismatched[0].name}`, {
+          mismatched,
+        });
+      }
+
+      // 同盘 staging：先复制到 canonical 下的隐藏目录，再 rename 到最终位置。
+      // 隐藏目录以 `.` 开头，inventory 扫描会跳过，不会把半成品当成技能。
+      fs.mkdirSync(paths.canonical, { recursive: true });
+      preparedRoot = path.join(
+        paths.canonical,
+        `.dshsc-staging-${process.pid}-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`,
+      );
+      fs.mkdirSync(preparedRoot, { recursive: false });
+      for (const item of planned) {
+        copyTree(item.dirPath, path.join(preparedRoot, item.name));
+      }
+
+      for (const item of planned) {
+        const dest = path.join(paths.canonical, item.name);
+        if (fs.existsSync(dest)) {
+          const stat = fs.lstatSync(dest);
+          if (stat.isSymbolicLink()) {
+            throw new InstallerError('unsupported-existing', `${dest} 是符号链接，拒绝覆盖`);
+          }
+          const previousHash = contentHash(dest);
+          // 事务期间不 prune：多技能安装时先备份的目录不能被后面的 createBackup 挤掉
+          const backup = createBackup({ paths, skill: item.name, fromDir: dest, hash: previousHash, prune: false });
+          backups.set(item.name, { key: backup.key, previousHash });
+        }
+        // 先登记再动盘：任何一步失败都要能从备份恢复（包括 rm 之后、rename 之前）
+        attempted.push({ item, dest, backup: backups.get(item.name) || null });
+        fs.rmSync(dest, { recursive: true, force: true });
+        fs.renameSync(path.join(preparedRoot, item.name), dest);
+        const promotedHash = contentHash(dest);
+        if (promotedHash !== item.contentHash) {
+          throw new InstallerError('verify-failed', `${item.name} 落盘后内容哈希不一致`, {
+            expected: item.contentHash,
+            actual: promotedHash,
+          });
+        }
+      }
+
+      const now = new Date();
+      const updatedAt = now.toISOString();
+      const entries = new Map();
+      for (const item of planned) {
+        const existing = lockBefore.data?.skills?.[item.name] || null;
+        entries.set(
+          item.name,
+          makeLockEntry({
+            source: canonicalSource,
+            ref: pin,
+            skillPath: item.skillPath,
+            treeSha: item.treeSha,
+            installedAt: validIsoOrUndefined(existing?.installedAt),
+            updatedAt,
+            now,
+          }),
+        );
+      }
+
+      updateLock({
+        lockPath: paths.lockFile,
+        expectedDigest: lockBefore.digest,
+        mutate: (draft) => {
+          for (const [name, entry] of entries) {
+            const previous = draft.skills[name];
+            // 已知字段以新条目为准，旧条目里的未知字段保留（旧 CLI/未来 CLI 加的字段不丢）
+            draft.skills[name] = previous && typeof previous === 'object' ? { ...previous, ...entry } : entry;
+          }
+        },
+      });
+
+      try {
+        pruneBackups({ paths });
+      } catch {
+        // 备份清理是维护动作，失败不影响安装结果
+      }
+
+      const installed = planned.map((item) => {
+        const backup = backups.get(item.name) || null;
+        const previousLockHash = lockBefore.data?.skills?.[item.name]?.skillFolderHash || null;
+        return {
+          name: item.name,
+          skillPath: item.skillPath,
+          treeSha: item.treeSha,
+          contentHash: item.contentHash,
+          backup: backup?.key || null,
+          backupHash: backup?.previousHash || null,
+          backupTreeSha:
+            typeof previousLockHash === 'string' && /^[0-9a-f]{40}$/.test(previousLockHash)
+              ? previousLockHash
+              : null,
+        };
+      });
+      logger('installer.install', {
+        source: canonicalSource,
+        ref: pin,
+        skills: installed.map((item) => item.name),
+        bytes: downloaded.bytes,
+        warnings: warnings.length,
+      });
+      return { installed, warnings, root: extracted.root };
+    } catch (error) {
+      for (const entry of [...attempted].reverse()) {
+        fs.rmSync(entry.dest, { recursive: true, force: true });
+        if (entry.backup) {
+          const restored = readBackup({ paths, key: entry.backup.key });
+          if (restored) restoreBackup({ backup: restored, toDir: entry.dest });
+        }
+      }
+      throw normalizeError(error);
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+      if (preparedRoot) fs.rmSync(preparedRoot, { recursive: true, force: true });
+    }
+  }
+
+  /** 删除 canonical 目录与 lock 条目；lock 写失败时不删目录，避免半状态。 */
+  function remove({ name } = {}) {
+    assertSafeSkillName(name);
+    const lockBefore = readLockFile(paths.lockFile);
+    const entry = lockBefore.data?.skills?.[name] || null;
+    const canonicalPath = path.join(paths.canonical, name);
+
+    updateLock({
+      lockPath: paths.lockFile,
+      expectedDigest: lockBefore.digest,
+      mutate: (draft) => {
+        delete draft.skills[name];
+      },
+    });
+
+    try {
+      fs.rmSync(canonicalPath, { recursive: true, force: true });
+    } catch (error) {
+      // 目录删不掉就把 lock 条目放回去（尽量恢复，恢复不了也如实报错）
+      if (entry) {
+        try {
+          updateLock({
+            lockPath: paths.lockFile,
+            mutate: (draft) => {
+              draft.skills[name] = entry;
+            },
+          });
+        } catch {
+          // 恢复失败只能让调用方看到原始错误；lock 里最多少一条，不会指错目录
+        }
+      }
+      throw new InstallerError('remove-failed', `删除 ${name} 失败: ${error.message}`, { cause: error });
+    }
+
+    logger('installer.remove', { name, hadLockEntry: Boolean(entry) });
+    return { removed: Boolean(entry), treeSha: entry?.skillFolderHash || null };
+  }
+
+  return { readiness, install, remove };
+}

package/lib/core/lock.js

@@ -0,0 +1,310 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * v3 skill lock（`~/.agents/.skill-lock.json`，或 XDG_STATE_HOME 下）的**唯一写入者**。
+ *
+ * 兼容目标（与 `skills` CLI 落盘格式一致）：
+ * - `version` 必须恰好是 3；>3 视为不认识的新版本，只读并抛 `lock-unsupported`，绝不覆盖。
+ * - JSON 损坏同样抛错；宁可写失败，也不拿空账覆盖用户的 lock。
+ * - 顶层未知字段、每个技能条目的未知字段、`dismissed` 全部原样保留，只动调用方明确要动的键。
+ * - 写入：同目录临时文件 → fsync → rename；写前留 `.bak`；rename 失败时原文件不会被截断。
+ * - `expectedDigest` 用来防止覆盖外部 CLI 刚写入的内容：写前重算，不一致就报冲突。
+ *
+ * 语义边界：只负责文件一致性，不判断技能是否该装、不碰 canonical；事务边界由 installer 负责。
+ */
+
+export const LOCK_VERSION = 3;
+
+const SOURCE_TYPES = new Set(['github', 'local', 'download']);
+const TREE_SHA_RE = /^[0-9a-f]{40}$/;
+const CONTENT_SHA_RE = /^[0-9a-f]{64}$/;
+
+export class LockError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = 'LockError';
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function lockDigest(text) {
+  return crypto.createHash('sha256').update(text).digest('hex');
+}
+
+/**
+ * 读 lock 用于写。返回 `{ present, raw, digest, data }`；
+ * 文件不存在返回 `present:false`（调用方创建空账）；其余异常一律抛 LockError。
+ */
+export function readLockFile(lockPath) {
+  if (typeof lockPath !== 'string' || lockPath.length === 0) {
+    throw new LockError('lock-invalid', 'readLockFile 需要 lock 路径');
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(lockPath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return { present: false, raw: null, digest: null, data: null };
+    }
+    throw new LockError('lock-unreadable', `无法读取 lock: ${error.message}`, { cause: error });
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    throw new LockError('lock-corrupt', `lock 不是合法 JSON: ${error.message}`, { cause: error });
+  }
+  if (!isPlainObject(data)) throw new LockError('lock-corrupt', 'lock 顶层不是对象');
+  if (typeof data.version !== 'number' || !Number.isInteger(data.version)) {
+    throw new LockError('lock-corrupt', 'lock.version 缺失或不是整数');
+  }
+  if (data.version !== LOCK_VERSION) {
+    throw new LockError(
+      'lock-unsupported',
+      `lock.version ${data.version} 不是可写的 v${LOCK_VERSION}，拒绝覆盖`,
+      { version: data.version },
+    );
+  }
+  if (!isPlainObject(data.skills)) throw new LockError('lock-corrupt', 'lock.skills 缺失或不是对象');
+  if (data.dismissed !== undefined && !isPlainObject(data.dismissed)) {
+    throw new LockError('lock-corrupt', 'lock.dismissed 不是对象');
+  }
+  return { present: true, raw, digest: lockDigest(raw), data };
+}
+
+function emptyLock() {
+  return { version: LOCK_VERSION, skills: {}, dismissed: {} };
+}
+
+function assertLockShape(data) {
+  if (!isPlainObject(data)) throw new LockError('lock-invalid', '写回的 lock 不是对象');
+  if (data.version !== LOCK_VERSION) {
+    throw new LockError('lock-invalid', `写回的 lock.version 必须是 ${LOCK_VERSION}`);
+  }
+  if (!isPlainObject(data.skills)) throw new LockError('lock-invalid', '写回的 lock.skills 不是对象');
+  if (data.dismissed !== undefined && !isPlainObject(data.dismissed)) {
+    throw new LockError('lock-invalid', '写回的 lock.dismissed 不是对象');
+  }
+}
+
+function atomicWrite(target, text) {
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(
+    dir,
+    `.${path.basename(target)}.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString('hex')}.tmp`,
+  );
+  let fd = null;
+  try {
+    fd = fs.openSync(tmp, 'wx', 0o644);
+    fs.writeFileSync(fd, text, 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    fs.renameSync(tmp, target);
+  } catch (error) {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // 已经关掉就算了，别覆盖原始错误
+      }
+    }
+    fs.rmSync(tmp, { force: true });
+    throw new LockError('lock-write-failed', `写 lock 失败: ${error.message}`, { cause: error });
+  }
+}
+
+/**
+ * 读改写 lock。`mutate(draft)` 直接改 draft（同步）；返回 `{ data, digest, changed, backup }`。
+ *
+ * - `expectedDigest` 传 `null` 表示“写之前必须不存在”；传字符串表示必须等于当前内容摘要；
+ *   不传则不校验。
+ * - 内容没变化时不落盘（不产生 `.bak`、不更新时间戳）。
+ */
+export function updateLock({ lockPath, mutate, expectedDigest } = {}) {
+  if (typeof mutate !== 'function') {
+    throw new LockError('lock-invalid', 'updateLock 需要 mutate 函数');
+  }
+  const current = readLockFile(lockPath);
+  if (expectedDigest !== undefined && current.digest !== expectedDigest) {
+    throw new LockError('lock-conflict', 'lock 在本次操作期间被其他进程修改，拒绝覆盖', {
+      expectedDigest,
+      actualDigest: current.digest,
+    });
+  }
+
+  const draft = current.present ? structuredClone(current.data) : emptyLock();
+  const result = mutate(draft);
+  const next = result === undefined ? draft : result;
+  assertLockShape(next);
+
+  const text = `${JSON.stringify(next, null, 2)}\n`;
+  if (current.present && text === current.raw) {
+    return { data: next, digest: current.digest, changed: false, backup: null };
+  }
+
+  let backup = null;
+  if (current.present) {
+    backup = `${lockPath}.bak`;
+    try {
+      fs.writeFileSync(backup, current.raw, { encoding: 'utf8', mode: 0o644 });
+    } catch (error) {
+      throw new LockError('lock-write-failed', `备份 lock 失败: ${error.message}`, { cause: error });
+    }
+  }
+  atomicWrite(lockPath, text);
+  return { data: next, digest: lockDigest(text), changed: true, backup };
+}
+
+const KNOWN_ENTRY_KEYS = new Set([
+  'source',
+  'sourceType',
+  'sourceUrl',
+  'ref',
+  'skillPath',
+  'skillFolderHash',
+  'installedAt',
+  'updatedAt',
+]);
+
+/**
+ * 新旧条目合并：已知字段以新条目为准（新条目没有 `ref` 就删掉旧的），
+ * 未知字段原样保留 —— 与 CLI 的“不重建整个对象”语义一致，未来 CLI 加字段不会被我们抹掉。
+ */
+function mergeLockEntry(previous, entry) {
+  if (!isPlainObject(previous)) return entry;
+  const merged = {};
+  for (const [key, value] of Object.entries(previous)) {
+    if (!KNOWN_ENTRY_KEYS.has(key)) merged[key] = value;
+  }
+  return { ...merged, ...entry };
+}
+
+/** 安装/更新后写入一个技能条目；`entry` 由 makeLockEntry 或调用方按 CLI 形状构造。 */
+export function upsertSkill({ lockPath, name, entry, expectedDigest } = {}) {
+  assertSkillName(name);
+  assertLockEntry(name, entry);
+  return updateLock({
+    lockPath,
+    expectedDigest,
+    mutate: (draft) => {
+      draft.skills[name] = mergeLockEntry(draft.skills[name], entry);
+    },
+  });
+}
+
+/** 删除一个技能条目；条目本就不存在时视为成功（changed:false）。 */
+export function removeSkill({ lockPath, name, expectedDigest } = {}) {
+  assertSkillName(name);
+  return updateLock({
+    lockPath,
+    expectedDigest,
+    mutate: (draft) => {
+      delete draft.skills[name];
+    },
+  });
+}
+
+function assertSkillName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new LockError('lock-invalid', '技能名必须是非空字符串');
+  }
+  if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+    throw new LockError('lock-invalid', `技能名不能含路径分隔符: ${name}`);
+  }
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(name)) {
+    throw new LockError('lock-invalid', `技能名不能含控制字符: ${JSON.stringify(name)}`);
+  }
+}
+
+function isIsoDate(value) {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  const time = Date.parse(value);
+  return Number.isFinite(time);
+}
+
+/**
+ * 校验一条 lock 条目。允许 40 位 tree SHA 或旧数据的 64 位内容 hash，
+ * 但 `makeLockEntry` 只产出 40 位 —— 新安装绝不用内容 hash 冒充 tree SHA。
+ */
+export function assertLockEntry(name, entry) {
+  const fail = (message) => {
+    throw new LockError('lock-invalid', `${name}: ${message}`);
+  };
+  if (!isPlainObject(entry)) fail('条目不是对象');
+  if (typeof entry.source !== 'string' || !/^[\w.-]+\/[\w.-]+$/.test(entry.source)) {
+    fail('source 不是 owner/repo');
+  }
+  if (!SOURCE_TYPES.has(entry.sourceType)) fail(`sourceType 不认识: ${entry.sourceType}`);
+  if (typeof entry.sourceUrl !== 'string' || !entry.sourceUrl.startsWith('https://')) {
+    fail('sourceUrl 必须是 https URL');
+  }
+  if (typeof entry.skillPath !== 'string' || entry.skillPath.length === 0) fail('skillPath 缺失');
+  if (
+    entry.skillPath.startsWith('/') ||
+    entry.skillPath.includes('\\') ||
+    entry.skillPath.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')
+  ) {
+    fail(`skillPath 不是安全的 POSIX 相对路径: ${entry.skillPath}`);
+  }
+  if (!entry.skillPath.endsWith('.md')) fail('skillPath 应指向 .md 文件');
+  if (typeof entry.skillFolderHash !== 'string') fail('skillFolderHash 缺失');
+  if (!TREE_SHA_RE.test(entry.skillFolderHash) && !CONTENT_SHA_RE.test(entry.skillFolderHash)) {
+    fail('skillFolderHash 既不是 40 位 tree SHA 也不是 64 位内容 hash');
+  }
+  if (!isIsoDate(entry.installedAt)) fail('installedAt 不是 ISO 时间');
+  if (!isIsoDate(entry.updatedAt)) fail('updatedAt 不是 ISO 时间');
+  if (entry.ref !== undefined && entry.ref !== null) {
+    if (typeof entry.ref !== 'string' || entry.ref.length === 0 || entry.ref.length > 200) {
+      fail('ref 不是合法字符串');
+    }
+    if (!/^[A-Za-z0-9._/-]+$/.test(entry.ref) || entry.ref.includes('..')) fail(`ref 含非法字符: ${entry.ref}`);
+  }
+  return entry;
+}
+
+/**
+ * 按 CLI 落盘形状构造条目（键顺序照 skills@1.7.4：source / sourceType / sourceUrl /
+ * [ref] / skillPath / skillFolderHash / installedAt / updatedAt）。
+ * `ref` 为空时直接省略（CLI 对默认分支安装就是这么写的）。
+ */
+export function makeLockEntry({
+  source,
+  ref = null,
+  skillPath,
+  treeSha,
+  installedAt,
+  updatedAt,
+  now = new Date(),
+} = {}) {
+  const normalized = typeof source === 'string' ? source.trim().replace(/\.git$/, '') : source;
+  if (typeof normalized !== 'string' || !/^[\w.-]+\/[\w.-]+$/.test(normalized)) {
+    throw new LockError('lock-invalid', `source 必须是 owner/repo: ${source}`);
+  }
+  if (typeof treeSha !== 'string' || !TREE_SHA_RE.test(treeSha)) {
+    throw new LockError('lock-invalid', `treeSha 必须是 40 位小写 hex: ${treeSha}`);
+  }
+  const stamp = now instanceof Date ? now.toISOString() : new Date(now).toISOString();
+  const entry = {
+    source: normalized,
+    sourceType: 'github',
+    sourceUrl: `https://github.com/${normalized}.git`,
+  };
+  if (ref !== null && ref !== undefined) entry.ref = ref;
+  entry.skillPath = skillPath;
+  entry.skillFolderHash = treeSha;
+  entry.installedAt = installedAt === undefined ? stamp : installedAt;
+  entry.updatedAt = updatedAt === undefined ? stamp : updatedAt;
+  assertLockEntry(source, entry);
+  return entry;
+}