@topmindspace/topmind-skills 4.15.4 → 4.15.5

package/CHANGELOG.md

@@ -4,6 +4,14 @@ topmind-skills 的版本记录。GitHub 只保留最近 2 个 Release，本文
 
 版本真源：`topmind-pack.json`。`package.json`、每个 `SKILL.md` 的 `metadata.version`、`evals/evals.json` 与之一致。
 
+## 4.15.5 — 2026-10-16
+
+### 安装器
+
+- 默认升级：包里版本更新（或已装版本缺失）就直接覆盖，不备份，打印 `Upgraded <skill> <旧> -> <新>`；同版本跳过，打印 `Already up to date`（`--force` 重装）；已装版本比包里新时拒绝降级，需 `--force`。
+- symlink 模式：之前装过的同名 skill 普通目录（SKILL.md name 一致）直接换成软链；无关目录才需要 `--force`，并给一行提示。
+- 新增 `tests/installer-upgrade.test.mjs`；README 中英文、INSTALL.md、帮助文本同步。
+
 ## 4.15.4 — 2026-10-16
 
 ### 优化

package/INSTALL.md

@@ -92,7 +92,7 @@ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -p
 # 单目录（旧 --dest 仍可用）
 npx @topmindspace/topmind-skills add topmindspace/topmind-skills --dest ~/.claude/skills
 
-# 升级（读 receipt）
+# 升级（读 receipt）：包里更新 → 直接覆盖，不备份，打印 Upgraded <skill> <旧> -> <新>；同版本 → Already up to date；已装更新 → 拒绝降级，需 --force
 npx @topmindspace/topmind-skills update -g
 
 # 查看
@@ -162,7 +162,7 @@ npx @topmindspace/topmind-skills doctor
 | `--skill <id>` | 只装列出的 skill id |
 | `--locale en-US` | locale overlay（当前未提供 overlay，回退中文正文） |
 | `-n` / `--dry-run` | 只打印计划 |
-| `--force` | symlink 模式下替换非软链目标 |
+| `--force` | 允许降级（已装版本比包里新）、同版本重装、symlink 模式下替换无关目录。之前装过的同名 skill 普通目录（SKILL.md name 一致）在 symlink 模式下会直接换成软链，不需要 --force |
 
 ### Agents
 

package/README.en.md

@@ -9,7 +9,7 @@ Portable AI skill pack: the same content contract on Claude Code / Codex / OpenC
 npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
 # subset of agents
 npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g -a claude-code -a mimocode
-# upgrade
+# upgrade (default: a newer packaged skill overwrites in place, no backup, "Upgraded <skill> <old> -> <new>"; same version is skipped "Already up to date"; a newer installed version is refused unless --force)
 npx @topmindspace/topmind-skills update -g
 
 # 2) Community CLI (fast try; omits shared/ — see INSTALL.md)

package/README.md

@@ -9,7 +9,7 @@
 npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
 # 只装给部分智能体
 npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g -a claude-code -a mimocode
-# 升级
+# 升级（默认：包里更新就直接覆盖，不备份，打印 Upgraded <skill> <旧> -> <新>；同版本跳过 Already up to date；已装更新拒绝降级，需 --force）
 npx @topmindspace/topmind-skills update -g
 
 # 2) 社区 CLI（快速试用；不含 shared/ — 见 INSTALL.md）

package/README.zh-CN.md

@@ -9,7 +9,7 @@
 npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
 # 只装给部分智能体
 npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g -a claude-code -a mimocode
-# 升级
+# 升级（默认：包里更新就直接覆盖，不备份，打印 Upgraded <skill> <旧> -> <新>；同版本跳过 Already up to date；已装更新拒绝降级，需 --force）
 npx @topmindspace/topmind-skills update -g
 
 # 2) 社区 CLI（快速试用；不含 shared/ — 见 INSTALL.md）

package/bin/install-skills.mjs

@@ -32,7 +32,7 @@
  *   --skill <id>        Only install these skill ids (repeatable / comma-separated)
  *   --global / -g       Alias: --host claude-code (user-level ~/.claude/skills)
  *   --dry-run           Print plan only
- *   --force             Replace non-symlink destinations when using symlink mode
+ *   --force             Downgrade / reinstall same version / replace unrelated folder in symlink mode
  *
  * Examples:
  *   # Like `npx skills add topmindspace/topmind-skills -g`
@@ -250,7 +250,12 @@ Options:
   --skill <id>         Only install these skill ids (repeatable / comma-separated)
   --locale <code>      Install locale overlay (e.g. en-US); falls back to topmind_LOCALE env
   -n, --dry-run        Print plan only
-  --force              Replace non-symlink destinations when using symlink mode
+  --force              Allow downgrading a newer installed skill, reinstall an up-to-date one,
+                       or replace an unrelated folder in symlink mode
+Upgrade behaviour: a newer packaged skill overwrites the installed copy in place
+  (no backup, "Upgraded <skill> <old> -> <new>"); the same version is skipped
+  ("Already up to date"); a newer installed version is refused unless --force.
+  In symlink mode a previous plain-folder install of the same skill is replaced.
 
 Examples:
   node bin/install-skills.mjs add topmindspace/topmind-skills -g
@@ -701,12 +706,75 @@ async function applyLocaleOverlay(overlayDir, targetDir) {
   }
 }
 
-async function installCopy(skillsRoot, dest, entries, locale) {
+/** Read name + version from <dir>/SKILL.md frontmatter (metadata.version or top-level version). */
+async function readSkillMeta(dir) {
+  try {
+    const t = await fs.readFile(path.join(dir, "SKILL.md"), "utf8");
+    const fm = (t.match(/^---\r?\n([\s\S]*?)\r?\n---/) || [])[1] || "";
+    const name = ((fm.match(/^name:\s*(.+?)\s*$/m) || [])[1] || "").replace(/^["']|["']$/g, "");
+    const v =
+      fm.match(/^metadata:\s*\n(?:[ \t]+.*\n)*?[ \t]+version:\s*(.+?)\s*$/m) || fm.match(/^version:\s*(.+?)\s*$/m);
+    return { name, version: v ? v[1].replace(/^["']|["']$/g, "") : "" };
+  } catch {
+    return null;
+  }
+}
+
+function parseVer(v) {
+  const m = String(v || "").trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? m.slice(1, 4).map(Number) : null;
+}
+
+/** a vs b: 1 / 0 / -1. Missing or unparseable b counts as oldest (upgrade). */
+function compareVersions(a, b) {
+  const pa = parseVer(a);
+  const pb = parseVer(b);
+  if (!pb) return 1;
+  if (!pa) return -1;
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+  return 0;
+}
+
+/** Existing non-symlink dst is a previous install of this skill (same SKILL.md name) or an installer-owned file. */
+async function isPreviousInstall(src, dst) {
+  const st = await fs.lstat(dst).catch(() => null);
+  if (!st) return false;
+  const sst = await fs.lstat(src).catch(() => null);
+  if (sst && sst.isFile() && st.isFile()) return true;
+  if (!st.isDirectory()) return false;
+  const a = await readSkillMeta(src);
+  const b = await readSkillMeta(dst);
+  return !!(a && b && a.name && a.name === b.name);
+}
+
+async function installCopy(skillsRoot, dest, entries, locale, { force = false } = {}) {
   await fs.mkdir(dest, { recursive: true });
+  // Pre-pass: never silently downgrade a skill that is newer than the packaged one.
+  const plan = new Map();
+  const newer = [];
+  for (const name of entries) {
+    const src = path.join(skillsRoot, name);
+    const dst = path.join(dest, name);
+    const sm = await readSkillMeta(src);
+    if (!sm) continue;
+    const dm = (await fs.lstat(dst).catch(() => null))?.isSymbolicLink() ? null : await readSkillMeta(dst);
+    if (!dm) continue;
+    const cmp = compareVersions(sm.version, dm.version);
+    plan.set(name, { cmp, old: dm.version || "unknown", now: sm.version || "unknown" });
+    if (cmp < 0) newer.push(`${name} ${dm.version} > ${sm.version}`);
+  }
+  if (newer.length && !force) {
+    fail(`installed version is newer than packaged (${newer.join(", ")}); not downgrading — pass --force to downgrade`);
+  }
   for (const name of entries) {
     const src = path.join(skillsRoot, name);
     const dst = path.join(dest, name);
     if (!(await pathExists(src))) continue;
+    const pv = plan.get(name);
+    if (pv && pv.cmp === 0 && !force) {
+      log(`  = Already up to date: ${name} ${pv.now}`);
+      continue;
+    }
     const st = await fs.lstat(src);
     if (await pathExists(dst)) await fs.rm(dst, { recursive: true, force: true });
     if (st.isDirectory()) {
@@ -727,7 +795,9 @@ async function installCopy(skillsRoot, dest, entries, locale) {
     } else {
       await fs.copyFile(src, dst);
     }
-    log(`  + ${name}`);
+    if (pv && pv.cmp > 0) log(`  ↑ Upgraded ${name} ${pv.old} -> ${pv.now}`);
+    else if (pv) log(`  + Reinstalled ${name} ${pv.now} (--force)`);
+    else log(`  + ${name}`);
   }
 }
 
@@ -739,8 +809,8 @@ async function installSymlink(skillsRoot, dest, entries, { force }) {
     if (!(await pathExists(src))) continue;
     if (await pathExists(dst)) {
       const st = await fs.lstat(dst);
-      if (st.isSymbolicLink() || force) await fs.rm(dst, { recursive: true, force: true });
-      else fail(`${dst} exists and is not a symlink (pass --force)`);
+      if (st.isSymbolicLink() || force || (await isPreviousInstall(src, dst))) await fs.rm(dst, { recursive: true, force: true });
+      else fail(`${dst} is an unrelated folder (no matching SKILL.md name) — pass --force to replace it`);
     }
     await fs.symlink(src, dst, "junction");
     log(`  ~ ${name} → ${src}`);
@@ -794,9 +864,9 @@ async function linkPackEntries(canonicalRoot, agentRoot, entryNames, { force })
     if ((await pathExists(dst)) || (await isBrokenSymlink(dst))) {
       const st = await fs.lstat(dst).catch(() => null);
       if (st && st.isSymbolicLink()) await fs.rm(dst, { recursive: true, force: true });
-      else if (force) await fs.rm(dst, { recursive: true, force: true });
+      else if (force || (await isPreviousInstall(src, dst))) await fs.rm(dst, { recursive: true, force: true });
       else {
-        log(`  ! ${dst} exists (not symlink) — skip (pass --force to replace)`);
+        log(`  ! ${dst} is an unrelated folder (no matching SKILL.md name) — skipped; pass --force to replace it`);
         continue;
       }
     }
@@ -845,7 +915,7 @@ async function installViaMatrix(skillsRoot, plan, opts) {
   }
 
   // 1) Full pack body → canonical
-  await installCopy(skillsRoot, canonical, plan.entries, opts.locale);
+  await installCopy(skillsRoot, canonical, plan.entries, opts.locale, opts);
 
   // 2) Private agent dirs: symlink entries (default) or copy
   for (const t of targets) {
@@ -854,7 +924,7 @@ async function installViaMatrix(skillsRoot, plan, opts) {
       continue;
     }
     if (linkMode === "copy") {
-      await installCopy(skillsRoot, t.root, plan.entries, opts.locale);
+      await installCopy(skillsRoot, t.root, plan.entries, opts.locale, opts);
     } else {
       await linkPackEntries(canonical, t.root, plan.entries, opts);
     }
@@ -1014,7 +1084,7 @@ async function cmdAdd(opts, sourceOverride) {
       }
       await installSymlink(skillsRoot, dest, plan.entries, opts);
     } else {
-      await installCopy(skillsRoot, dest, plan.entries, opts.locale);
+      await installCopy(skillsRoot, dest, plan.entries, opts.locale, opts);
     }
 
     await writeInstallReceipt(dest, {

package/evals/evals.json

@@ -1,7 +1,7 @@
 {
   "skill_name": "topmind",
   "daily_entry": "topmind",
-  "version": "4.15.4",
+  "version": "4.15.5",
   "evals": [
     {
       "id": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topmindspace/topmind-skills",
-  "version": "4.15.4",
+  "version": "4.15.5",
   "description": "topmind Agent Skills pack — spec-valid Markdown skills for capture, organize, write, memory, maintain, loop.",
   "type": "module",
   "license": "MIT",

package/topmind/SKILL.md

@@ -9,7 +9,7 @@ compatibility: >-
   topmind workspace with {NN-Name}/ categories. Host file tools primary; UTR optional.
   Install with shared/ sibling for progressive disclosure links.
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "router"
   entrypoint: "true"
   triggers: "topmind, 知识库, 工作区, 待办, 有什么要做的, 要做的事, todo, todo list"

package/topmind-capture/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 license: MIT
 compatibility: topmind workspace. Host file tools or optional UTR capture-note.
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "capture"
   entrypoint: "false"
   triggers: "收集, 收进, 保存, 剪藏, 记一下, 临时存放, 随手记, 想法, 灵感, 暂存沉淀, 记录, 备忘, 存一下, 暂存, 笔记, 抄下来, 摘录, 记一下要做, 别忘了, 要做, capture, note, save, Note it"

package/topmind-ledger/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 compatibility: Host file tools or Kernel writeback. Desktop optional mini-app. Feishu/lark-cli is not required.
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "memory"
   entrypoint: "false"
   triggers: "记账, 记一笔, 花了, 存入, 查看账单, 账户余额, bookkeeping, log expense"

package/topmind-loop/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 compatibility: topmind workspace. Progress under .topmind/loop/*. Host LLM runs the walk; UTR optional.
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "loop"
   entrypoint: "false"
   triggers: "跑一遍 loop, loop 一下, 整体体检, 工作区复盘, 把工作区跑一遍, 巡检, 继续 loop, 从断点继续, 全面检查, 复盘, review, audit, walk"

package/topmind-maintain/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 compatibility: topmind engine and/or workspace. Prefer read-only diagnostics first.
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "maintain"
   entrypoint: "false"
   triggers: "快速体检, 体检, 诊断, doctor, 健康检查, 清理, 修复, 快速检查, 检查, 状态, workspace check, scan, fix, maintain"

package/topmind-memory/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 compatibility: workspace core profile (memory/profile.md) + periodic reflections.
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "memory"
   entrypoint: "false"
   triggers: "写入专题记忆, 更新我的情况, stable memory, 追加确认结论, 记住这个, 记住我, 加到专题记忆, 沉淀结论, 提炼到记忆, update profile, memory"

package/topmind-organize/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 compatibility: topmind workspace with stream period notes, topics, or Inbox.
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "organize"
   entrypoint: "false"
   triggers: "整理本周, 理顺本周, 周复盘, 整理, 组织, 研究, 分析, 对比, 提取, 梳理, 归纳, 证据, 实体, 质量审查, 总结, 概括, 汇总, 提纲, 分类整理, 找关联, 总结成笔记要点, organize, summarize, analyze, weekly review"

package/topmind-pack.json

@@ -4,7 +4,7 @@
   "label": "topmind",
   "description": "topmind skill pack: single daily entry topmind + progressive disclosure (shared/ + references/), Agent Skills spec-valid frontmatter (custom fields under metadata, checked by agentskills validate), capture-first template-driven categories, optional connectors topmind-weread and topmind-x, optional topmind-ledger (记账). None of the optional skills is an extra user concept. WeChat (公众号) and other writing skills live in the external topmind-writing-skills pack (topmind-wechat-post etc.) and are routed only when installed. File-system-first content truth; UTR optional.",
   "daily_entry": "topmind",
-  "version": "4.15.4",
+  "version": "4.15.5",
   "updated": "2026-10-16",
   "license": "MIT",
   "locales": {

package/topmind-weread/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 compatibility: Requires WeRead Skill API key (wrk-*). Desktop WereadService preferred; host may call gateway manually.
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "connector"
   entrypoint: "false"
   triggers: "微信读书, weread, 划线同步, 读书笔记, 阅读统计, 书架, weread sync, sync highlights"

package/topmind-write/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 compatibility: topmind workspace. Delivery role category (often 88-交付 / 88-Delivery).
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "write"
   entrypoint: "false"
   triggers: "写, 写作, 起草, 续写, 修订, 润色, 交付, 改写, de-AI, 输出, 出稿, 定稿, 发布, 导出, 排版, write, draft, deliver, publish, export"

package/topmind-x/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 compatibility: Desktop needs Bearer (read) and/or xurl (post). Agent hosts use official X MCP + xurl bridge.
 metadata:
-  version: "4.15.4"
+  version: "4.15.5"
   action_category: "connector"
   entrypoint: "false"
   triggers: "发推, 推特, twitter, x.com, 发帖, 推文, post tweet, x platform"