@clawling/clawchat-plugin-openclaw 2026.7.2 → 2026.7.6-1

package/src/skill-update.ts

@@ -30,8 +30,12 @@ import { fileURLToPath } from "node:url";
  *   implementation in `@clawling/clawchat-plugin-install-cli`
  *   (`packages/core/src/skills/check-update.ts`). That package is
  *   workspace-private, so the logic is duplicated here rather than imported.
- * - Strict semver compare mirrors the reference `parseComparableVersion`
- *   (`X.Y[.Z[.W]][-buildnum]`).
+ * - Update detection converges on raw sha256 comparison: ANY byte difference
+ *   from the official source (or a missing local file) is an update —
+ *   upgrade, rollback, or same-version content fix alike. The strict semver
+ *   compare (`parseComparableVersion` / `isVersionOlder`, still ported from
+ *   the reference `parseComparableVersion`, `X.Y[.Z[.W]][-buildnum]`) is kept
+ *   only for consent-prompt display wording, not for the `hasUpdate` decision.
  * - All network IO goes through an injected `FetchLike`; tests never touch the
  *   real network.
  *
@@ -138,6 +142,9 @@ export interface SkillManifestEntry {
 export interface SkillsManifest {
   schema: number;
   skills: Record<string, Record<string, SkillManifestEntry>>;
+  /** Tombstoned skill ids per target. An adapter deletes its LOCAL copy of an
+   * id ONLY when it appears here — absence from `skills` alone never deletes. */
+  removed: Record<string, string[]>;
 }
 
 export interface SkillUpdate {
@@ -156,6 +163,8 @@ export interface CheckSkillUpdateOutcome {
   ref: string;
   results: SkillUpdate[];
   hasUpdate: boolean;
+  /** Tombstoned skill ids for this target, straight from `manifest.removed`. */
+  removedIds: string[];
 }
 
 function skillsBase(base: string | undefined, ref: string): string {
@@ -222,7 +231,25 @@ export function parseSkillsManifest(text: string): SkillsManifest {
       skills[target][skillId] = asEntry(entry, `${target}.${skillId}`);
     }
   }
-  return { schema: 1, skills };
+  const removed: SkillsManifest["removed"] = {};
+  if (data.removed !== undefined) {
+    if (!data.removed || typeof data.removed !== "object" || Array.isArray(data.removed)) {
+      throw new Error("skills manifest `removed` must be an object");
+    }
+    for (const [target, ids] of Object.entries(data.removed as Record<string, unknown>)) {
+      if (!Array.isArray(ids) || !ids.every((i) => typeof i === "string" && (i as string).trim())) {
+        throw new Error(`skills manifest removed[${target}] must be a list of skill ids`);
+      }
+      const cleaned = ids.map((i) => (i as string).trim());
+      for (const id of cleaned) {
+        if (skills[target]?.[id]) {
+          throw new Error(`skill ${target}.${id} is in both skills and removed`);
+        }
+      }
+      removed[target] = cleaned;
+    }
+  }
+  return { schema: 1, skills, removed };
 }
 
 async function fetchText(url: string, fetchFn: FetchLike): Promise<string> {
@@ -239,17 +266,22 @@ async function fetchText(url: string, fetchFn: FetchLike): Promise<string> {
 }
 
 export interface CheckSkillUpdateOptions {
-  /** Locally installed versions: `{ "<skillId>": "<version>" }`. */
-  current: Record<string, string>;
+  /**
+   * Effective local state of one skill (managed-over-bundled), or null when
+   * not installed. Called once per remote manifest entry — remote-driven, so
+   * dynamically delivered extras are covered too.
+   */
+  readLocalState: (skillId: string) => Promise<LocalSkillState | null>;
   ref?: string;
   base?: string;
   fetchFn: FetchLike;
 }
 
 /**
- * Read the official manifest for the `openclaw` target and compare each skill's
- * offered version against the locally installed `current` map. A skill missing
- * from `current` is reported as `hasUpdate: true`.
+ * Read the official manifest for the `openclaw` target and compare each
+ * skill's offered content (sha256) against its effective local state, read
+ * on demand via `readLocalState`. Any sha256 mismatch — or no local state at
+ * all — is reported as `hasUpdate: true`.
  */
 export async function checkSkillUpdate(
   options: CheckSkillUpdateOptions,
@@ -264,11 +296,14 @@ export async function checkSkillUpdate(
 
   const results: SkillUpdate[] = [];
   for (const [skillId, entry] of Object.entries(targetSkills)) {
-    const current = options.current[skillId] ?? null;
-    const hasUpdate = current === null ? true : isVersionOlder(current, entry.version);
+    const state = await options.readLocalState(skillId);
+    // sha convergence: any byte difference from the official source (or a
+    // missing local file) is an update — upgrade, rollback, or same-version
+    // content fix alike.
+    const hasUpdate = !state || state.sha256 !== entry.sha256;
     results.push({
       skillId,
-      current,
+      current: state?.version ?? null,
       latest: entry.version,
       hasUpdate,
       path: entry.path,
@@ -276,7 +311,12 @@ export async function checkSkillUpdate(
       bytes: entry.bytes,
     });
   }
-  return { ref, results, hasUpdate: results.some((r) => r.hasUpdate) };
+  return {
+    ref,
+    results,
+    hasUpdate: results.some((r) => r.hasUpdate),
+    removedIds: manifest.removed[SKILL_TARGET] ?? [],
+  };
 }
 
 /**
@@ -318,58 +358,50 @@ export function parseSkillFrontmatterVersion(markdown: string): string | null {
   return raw || null;
 }
 
-/** Read one skill's frontmatter `version` from `<dir>/<skillId>/SKILL.md`. */
-async function readSingleSkillVersion(dir: string, skillId: string): Promise<string | null> {
-  try {
-    const md = await fs.readFile(path.join(dir, skillId, "SKILL.md"), "utf8");
-    return parseSkillFrontmatterVersion(md);
-  } catch {
-    return null; // missing / unreadable
-  }
+export interface LocalSkillState {
+  /** Frontmatter `version` of the effective file, or null when unparsable. */
+  version: string | null;
+  /** Lowercase hex sha256 of the effective file's raw bytes. */
+  sha256: string;
 }
 
-/**
- * Read the installed version of each requested skill from a SINGLE directory
- * (`<skillsDir>/<skillId>/SKILL.md`). Missing files / missing frontmatter
- * version are simply omitted (treated as "not installed" → update available).
- */
-export async function readLocalSkillVersions(
-  skillsDir: string,
-  skillIds: readonly string[] = OPENCLAW_SKILL_IDS,
-): Promise<Record<string, string>> {
-  const versions: Record<string, string> = {};
-  for (const skillId of skillIds) {
-    const version = await readSingleSkillVersion(skillsDir, skillId);
-    if (version) versions[skillId] = version;
+async function readSkillStateFromDir(dir: string, skillId: string): Promise<LocalSkillState | null> {
+  try {
+    const buf = await fs.readFile(path.join(dir, skillId, "SKILL.md"));
+    return {
+      version: parseSkillFrontmatterVersion(buf.toString("utf8")),
+      sha256: crypto.createHash("sha256").update(buf).digest("hex"),
+    };
+  } catch {
+    return null;
   }
-  return versions;
 }
 
 /**
- * Read the EFFECTIVE installed version of each skill, mirroring the host's
- * managed-over-bundled precedence (`src/skills/loading/workspace.ts:1220-1239`,
- * managed=3 > bundled=2): use the managed copy's frontmatter `version` when
- * `<managedDir>/<id>/SKILL.md` exists, otherwise fall back to the bundled
- * copy's. A skill present in neither is omitted (→ update available).
+ * Effective local state of ONE skill, mirroring the host's managed-over-bundled
+ * precedence: managed copy if present, else bundled, else null. Called per
+ * remote manifest entry so dynamically delivered extra skills are hashed too
+ * (a static bundled-id list would misreport extras as never-installed).
  */
-export async function readEffectiveSkillVersions(
+export async function readLocalSkillState(
   managedDir: string,
   bundledDir: string | null,
-  skillIds: readonly string[] = OPENCLAW_SKILL_IDS,
-): Promise<Record<string, string>> {
-  const versions: Record<string, string> = {};
-  for (const skillId of skillIds) {
-    const managed = await readSingleSkillVersion(managedDir, skillId);
-    if (managed) {
-      versions[skillId] = managed;
-      continue;
-    }
-    if (bundledDir) {
-      const bundled = await readSingleSkillVersion(bundledDir, skillId);
-      if (bundled) versions[skillId] = bundled;
-    }
+  skillId: string,
+): Promise<LocalSkillState | null> {
+  const managed = await readSkillStateFromDir(managedDir, skillId);
+  if (managed) return managed;
+  if (bundledDir) return readSkillStateFromDir(bundledDir, skillId);
+  return null;
+}
+
+/** True when `<managedDir>/<skillId>/SKILL.md` exists (removal precondition). */
+export async function managedSkillExists(managedDir: string, skillId: string): Promise<boolean> {
+  try {
+    await fs.access(path.join(managedDir, skillId, "SKILL.md"));
+    return true;
+  } catch {
+    return false;
   }
-  return versions;
 }
 
 /**
@@ -458,6 +490,19 @@ export async function atomicWriteSkill(
   }
 }
 
+/**
+ * Delete a tombstoned managed skill: remove `<skillsDir>/<skillId>/SKILL.md`
+ * (the host chokidar-watches the dir; the unlink triggers a snapshot rebuild
+ * that drops the registration) and best-effort remove the now-empty dir.
+ * Deletion is the ONE legitimate delete of a skill path, and ONLY for ids the
+ * official manifest explicitly tombstones. Idempotent.
+ */
+export async function removeManagedSkill(skillsDir: string, skillId: string): Promise<void> {
+  const dir = path.join(skillsDir, skillId);
+  await fs.rm(path.join(dir, "SKILL.md"), { force: true });
+  await fs.rmdir(dir).catch(() => {});
+}
+
 // ---------------------------------------------------------------------------
 // Conservative consent parsing.
 // ---------------------------------------------------------------------------
@@ -530,11 +575,16 @@ export interface PendingSkillTarget {
   bytes: number;
 }
 
+export interface PendingSkillRemoval {
+  skillId: string;
+}
+
 export interface PendingSkillUpdate {
   ownerUserId: string;
   ref: string;
   base?: string;
   updates: PendingSkillTarget[];
+  removals: PendingSkillRemoval[];
   createdAt: number;
   expiresAt: number;
 }
@@ -576,8 +626,13 @@ export interface SkillUpdateLog {
 
 export interface RunSkillUpdateCheckOptions {
   ownerUserId: string;
-  /** Locally installed versions, `{ "<skillId>": "<version>" }`. */
-  localVersions: Record<string, string>;
+  /**
+   * Effective local state of one skill (managed-over-bundled), or null when
+   * not installed. See {@link CheckSkillUpdateOptions.readLocalState}.
+   */
+  readLocalState: (skillId: string) => Promise<LocalSkillState | null>;
+  /** True when `<managedDir>/<skillId>/SKILL.md` exists (removal precondition). */
+  hasManagedSkill: (skillId: string) => Promise<boolean>;
   fetchFn: FetchLike;
   ref?: string;
   base?: string;
@@ -589,7 +644,16 @@ export interface RunSkillUpdateCheckOptions {
 }
 
 function describeUpdate(u: PendingSkillTarget): string {
-  return `「${u.skillId}」v${u.current ?? "无"} → v${u.target}`;
+  if (u.current === null) return `「${u.skillId}」v无 → v${u.target}`;
+  let cmp = -1;
+  try {
+    cmp = compareVersions(u.current, u.target);
+  } catch {
+    cmp = -1; // unparsable local version — show as a plain update
+  }
+  if (cmp === 0) return `「${u.skillId}」v${u.target}(内容修订)`;
+  if (cmp > 0) return `「${u.skillId}」v${u.current} → v${u.target}(回滚)`;
+  return `「${u.skillId}」v${u.current} → v${u.target}`;
 }
 
 /**
@@ -608,7 +672,7 @@ export async function runSkillUpdateCheck(
   }
 
   const outcome = await checkSkillUpdate({
-    current: options.localVersions,
+    readLocalState: options.readLocalState,
     ...(options.ref ? { ref: options.ref } : {}),
     ...(options.base ? { base: options.base } : {}),
     fetchFn: options.fetchFn,
@@ -616,17 +680,19 @@ export async function runSkillUpdateCheck(
 
   const updates: PendingSkillTarget[] = outcome.results
     .filter((r) => r.hasUpdate)
-    .map((r) => ({
-      skillId: r.skillId,
-      current: r.current,
-      target: r.latest,
-      path: r.path,
-      sha256: r.sha256,
-      bytes: r.bytes,
-    }));
-
-  if (updates.length === 0) {
-    options.log?.info?.("clawchat skill-update check: no updates available");
+    .map((r) => ({ skillId: r.skillId, current: r.current, target: r.latest, path: r.path, sha256: r.sha256, bytes: r.bytes }));
+
+  const removals: PendingSkillRemoval[] = [];
+  for (const skillId of outcome.removedIds) {
+    if ((OPENCLAW_SKILL_IDS as readonly string[]).includes(skillId)) {
+      options.log?.info?.(`clawchat skill-update: ignoring tombstone for bundled skill ${skillId}`);
+      continue;
+    }
+    if (await options.hasManagedSkill(skillId)) removals.push({ skillId });
+  }
+
+  if (updates.length === 0 && removals.length === 0) {
+    options.log?.info?.("clawchat skill-update check: nothing to converge");
     return null;
   }
 
@@ -636,15 +702,19 @@ export async function runSkillUpdateCheck(
     ref: outcome.ref,
     ...(options.base ? { base: options.base } : {}),
     updates,
+    removals,
     createdAt: now,
     expiresAt: now + (options.timeoutMs ?? DEFAULT_CONSENT_TIMEOUT_MS),
   };
   options.store.set(record);
 
-  const text = `我的技能有更新:${updates.map(describeUpdate).join(";")}。回复「更新」确认,「取消」忽略。`;
+  const segments: string[] = [];
+  if (updates.length > 0) segments.push(`我的技能有更新:${updates.map(describeUpdate).join(";")}`);
+  if (removals.length > 0) segments.push(`以下技能将下线移除:${removals.map((r) => `「${r.skillId}」`).join("、")}`);
+  const text = `${segments.join(";")}。回复「更新」确认,「取消」忽略。`;
   await options.sendOwnerMessage(text);
   options.log?.info?.(
-    `clawchat skill-update check: asked owner for consent on ${updates.map((u) => u.skillId).join(",")}`,
+    `clawchat skill-update check: asked owner for consent on updates=[${updates.map((u) => u.skillId).join(",")}] removals=[${removals.map((r) => r.skillId).join(",")}]`,
   );
   return record;
 }
@@ -664,8 +734,8 @@ export interface HandleOwnerConsentReplyOptions {
    */
   skillsDir: string;
   sendOwnerMessage: (text: string) => Promise<void>;
-  /** Re-read the on-disk version of a skill for idempotency checks. */
-  readLocalVersion?: (skillId: string) => Promise<string | null>;
+  /** Re-read the on-disk sha of a managed skill for idempotency checks. */
+  readLocalSha?: (skillId: string) => Promise<string | null>;
   log?: SkillUpdateLog;
 }
 
@@ -703,23 +773,24 @@ export async function handleOwnerConsentReply(
   }
 
   // verdict === "affirm"
-  const readLocalVersion =
-    options.readLocalVersion ??
+  const readLocalSha =
+    options.readLocalSha ??
     (async (skillId: string) => {
       try {
-        const md = await fs.readFile(path.join(options.skillsDir, skillId, "SKILL.md"), "utf8");
-        return parseSkillFrontmatterVersion(md);
+        const buf = await fs.readFile(path.join(options.skillsDir, skillId, "SKILL.md"));
+        return crypto.createHash("sha256").update(buf).digest("hex");
       } catch {
         return null;
       }
     });
 
   const applied: PendingSkillTarget[] = [];
+  const removed: PendingSkillRemoval[] = [];
   try {
     for (const update of pending.updates) {
-      // Idempotency: skip a skill already at the target version on disk.
-      const onDisk = await readLocalVersion(update.skillId);
-      if (onDisk === update.target) {
+      // Idempotency: skip a skill whose on-disk bytes already match the target.
+      const onDisk = await readLocalSha(update.skillId);
+      if (onDisk === update.sha256) {
         applied.push(update);
         continue;
       }
@@ -733,9 +804,21 @@ export async function handleOwnerConsentReply(
       );
       await atomicWriteSkill(options.skillsDir, update.skillId, content);
       applied.push(update);
-      options.log?.info?.(
-        `clawchat skill-update: applied ${update.skillId} -> v${update.target} (atomic overwrite)`,
-      );
+      options.log?.info?.(`clawchat skill-update: applied ${update.skillId} -> v${update.target} (atomic overwrite)`);
+    }
+    for (const removal of pending.removals) {
+      // Defensive re-guard: bundled skills must never be deleted, even though
+      // runSkillUpdateCheck already filters them out of removal candidates.
+      // Unreachable in the normal flow; kept as a cheap safety net.
+      if ((OPENCLAW_SKILL_IDS as readonly string[]).includes(removal.skillId)) {
+        options.log?.info?.(
+          `clawchat skill-update: skipped removal of bundled skill ${removal.skillId} (defensive re-guard)`,
+        );
+        continue;
+      }
+      await removeManagedSkill(options.skillsDir, removal.skillId);
+      removed.push(removal);
+      options.log?.info?.(`clawchat skill-update: removed tombstoned skill ${removal.skillId}`);
     }
   } catch (err) {
     // Keep the pending record so the owner can retry with another "更新"; report
@@ -746,7 +829,9 @@ export async function handleOwnerConsentReply(
   }
 
   options.store.clear();
-  const summary = applied.map((u) => `「${u.skillId}」v${u.target}`).join("、");
-  await options.sendOwnerMessage(`✅ 已更新到 ${summary}`);
+  const segments: string[] = [];
+  if (applied.length > 0) segments.push(`已更新到 ${applied.map((u) => `「${u.skillId}」v${u.target}`).join("、")}`);
+  if (removed.length > 0) segments.push(`已移除 ${removed.map((r) => `「${r.skillId}」`).join("、")}`);
+  await options.sendOwnerMessage(`✅ ${segments.join(";")}`);
   return true;
 }