@topmindspace/topmind-writing-skills 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [0.9.2] - 2026-10-31
+
+- 宿主包运行时显式提供文章渲染、从源稿渲染、本地文本提取、长度评估和长度规则集评估。文章结果绑定所选稿与产物的 SHA-256，可选绑定创作快照指纹。
+- 长度规则集只接受调用方传入的 JSON，先校验结构和日期再报告。本包不附带、也不启用真实平台规则。Unicode 码点上限不能代替 X 加权长度或编辑器里的最终核对。
+- 八个技能的版本不变。
+
+## [0.9.1] - 2026-10-28
+
+- 安装器新增 `install all`、`update` 与 `status`：整套首次安装只需一条命令，后续更新只处理已装技能，状态直接显示安装版本与包快照。
+- 默认目标优先识别真实安装与宿主配置；多个候选要求明确 `--to`，避免静默写入错误目录。
+- 安装记录用于识别本地改动；受管副本的改动在自动更新时会阻止覆盖，显式强制更新与旧版未受管安装会保留旧副本。软链接和异名目录不再被替换。
+- 根 README 中英文对齐新的上手、升级与本地安装流程。
+
 ## [0.9.0] - 2026-10-27
 
 - 扩展 8 个技能的创作方向、完整示例和适用条件，保留事实、排版、保真与工具协议，清理统一审美门槛和旧规则冲突。

package/README.en.md

@@ -14,10 +14,12 @@ English | [中文](./README.md)
 </p>
 
 ```bash
-npx @topmindspace/topmind-writing-skills install topmind-viral-posts   # install one
-npx @topmindspace/topmind-writing-skills list                          # see all
+npx @topmindspace/topmind-writing-skills install all      # first-time setup
+npx @topmindspace/topmind-writing-skills@latest update    # later, update installed skills
 ```
 
+Then tell your AI assistant "revise this", "write a quick brief", or "make a cover for this article". To install just one skill, use `install topmind-revise` or another ID from `list`. Desktop and Obsidian already include a reviewed writing snapshot; update it through each app's About & Updates screen rather than these npx commands.
+
 Hosts start with the active note and allow explicit source changes. Drafts, a small read-only memory window and the selected skill are loaded in layers; other resources are retrieved as needed. Compaction does not reset completed work or budgets.
 
 ## Desktop and Obsidian integration
@@ -28,6 +30,8 @@ Open a Markdown document and choose **Writing & delivery** from the article tool
 
 Built-in HTML/text typography requires no Python. Preview and copy use the same output; changed sources or images require regeneration. Diagnostics identify missing images, diagram source, extended containers and table paste limitations. AI images, PNG rendering and publishing require their respective tools. Copying does not publish; wording scores do not decide editorial quality.
 
+The host pack also renders from source bytes, extracts local text from clipboard HTML, and evaluates a length rule set. The length entry accepts only caller-supplied JSON. This package does not ship or enable production platform rules. Fields, dates and reports are in [the length rule-set contract](docs/length-ruleset-v1.md). A Unicode code-point ceiling is not X weighted length and is not the target editor's final check. JavaScript and Python renderer differences are in [the capability matrix](docs/renderer-capability-matrix.md).
+
 About & updates tracks the application, core skills, independent writing pack and integrations separately. Writing resources can update independently; compiled renderer code follows the host release. Managed packs are isolated, local modifications block replacement and failed installs preserve the previous version. Supported Desktop installs can download an update and explicitly restart; manual downloads remain available when signing or the installation channel prevents automatic updates.
 
 ## More choices, concrete references
@@ -240,15 +244,19 @@ Every skill drafts only; you publish.
 **npm = pinned snapshot; GitHub = latest.**
 
 ```bash
+npx @topmindspace/topmind-writing-skills install all --to ./.claude/skills
+npx @topmindspace/topmind-writing-skills status --to ./.claude/skills
+npx @topmindspace/topmind-writing-skills@latest update --to ./.claude/skills
 npx @topmindspace/topmind-writing-skills install topmind-briefs --to ./.claude/skills
-npx @topmindspace/topmind-writing-skills@latest install topmind-briefs   # upgrade in place
-npx @topmindspace/topmind-writing-skills install topmind-briefs --force   # reinstall / downgrade
+npx @topmindspace/topmind-writing-skills install topmind-briefs --force --to ./.claude/skills
 npx @topmindspace/topmind-writing-skills uninstall topmind-briefs --to ./.claude/skills
-npx github:topmindspace/topmind-writing-skills install topmind-briefs     # latest from GitHub
+npx github:topmindspace/topmind-writing-skills update --to ./.claude/skills
 ```
 
-- Probes `./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`, then user-level directories; the summary prints the target.
-- Older installs are staged before replacement; failures retain the previous copy. Equal versions report up to date; reinstalling the same version or downgrading needs `--force`. Back up local modifications first.
+- `install all` installs the full set once; `update` changes only already installed skills, and `status` compares the package snapshot with a destination. All accept `--to`.
+- Without `--to`, the CLI selects a single existing TopMind installation, skills directory, or host configuration. If several match, it lists them and asks for `--to`. With no host configured, it uses `./.agents/skills` in the current project. Output always names the destination.
+- Replacements are staged first; failures keep the old copy. Local edits to a managed skill stop automatic updates until `--force` is explicit, which retains the previous copy. Upgrading an older untracked installation also retains a backup. Symlinks and unrelated directories are never replaced.
+- Equal versions are left alone; downgrading a newer installed version needs `--force`. Reopen the AI session after updating so the host discovers new skills.
 - Skill ids are not npm packages; don't `npm install topmind-briefs`.
 
 ### Upgrade from a local checkout
@@ -256,12 +264,11 @@ npx github:topmindspace/topmind-writing-skills install topmind-briefs     # late
 Install local, unpublished changes from the checkout; `@latest` contains only the published npm snapshot. Verify the target first. If tools share skills through symlinks, update the resolved shared directory and preserve those links. For a standalone Codex installation, run from the repository root:
 
 ```bash
-for skill in $(node scripts/discover_skills.js); do
-  node bin/topmind-writing-skills.js install "$skill" --to "$HOME/.codex/skills" || break
-done
+node bin/topmind-writing-skills.js status --to "$HOME/.codex/skills"
+node bin/topmind-writing-skills.js update --to "$HOME/.codex/skills"
 ```
 
-Replace `--to` with the verified shared destination when appropriate and check every result. Reopen the session to refresh skill discovery; unpublished changes with the same version require an explicit `--force` reinstall.
+Use `install all` for the first install. Replace `--to` with the verified shared destination when appropriate. Unpublished changes with the same skill version require `install <id> --force --to <actual-dir>`. The CLI copies each skill's self-contained resources and never writes to a destination's root `shared/` directory.
 
 <details>
 <summary>Repository layout and releases</summary>

package/README.md

@@ -14,10 +14,12 @@
 </p>
 
 ```bash
-npx @topmindspace/topmind-writing-skills install topmind-viral-posts   # 装一个
-npx @topmindspace/topmind-writing-skills list                          # 看全部
+npx @topmindspace/topmind-writing-skills install all      # 首次安装整套
+npx @topmindspace/topmind-writing-skills@latest update    # 以后只更新已装技能
 ```
 
+装好后直接对 AI 说「改这篇」「写条快讯」「给这篇做封面」。只想装一个，用 `install topmind-revise` 等技能 ID；`list` 查看全部。Desktop 和 Obsidian 已内置经过验证的写作快照，应用内更新从各自“关于与更新”进入，不需要再运行上面的 npx 命令。
+
 宿主默认绑定活跃笔记，允许显式换稿。当前稿件、少量全局记忆和所选技能分层加载；其余资源按需读取，压缩不重置已完成操作和预算。
 
 ## 在 Desktop 与 Obsidian 中使用
@@ -28,6 +30,8 @@ npx @topmindspace/topmind-writing-skills list                          # 看全
 
 内置 HTML/文本排版无需 Python，预览与复制同源；源稿或图片改变后需要重新生成。扩展容器、图表源码、缺图和平台表格粘贴限制会显示诊断。封面生图、PNG 和外部发布依赖实际工具，复制不等于已发布。审校不使用“AI 味分数”作为定稿门槛。
 
+宿主包运行时另外提供从源稿生成文章结果、从剪贴板 HTML 提取本地文本，以及长度规则集评估。长度入口只接受调用方传入的 JSON，本包不附带、也不启用真实平台规则。规则字段、日期和报告见 [长度规则集运行契约](docs/length-ruleset-v1.md)。Unicode 码点上限不能代替 X 加权长度或目标编辑器里的最终核对。JavaScript 与 Python 渲染器的差异见 [能力矩阵](docs/renderer-capability-matrix.md)。
+
 “关于与更新”分别展示 Desktop、核心技能、独立写作包和集成组件。写作资源可独立更新；编译进宿主的排版代码随宿主升级。受管包按身份隔离，覆盖本地定制会被阻止，失败保留旧版。Desktop 支持标准更新器下载后显式重启；签名、平台或渠道不支持时保留手动下载。
 
 ## 加选项，让经验帮助创作
@@ -258,15 +262,19 @@ python3 scripts/de_ai_lint.py 文章.md --genre long      # 长文
 **npm = 钉版本快照；GitHub = 跟仓库最新。**
 
 ```bash
+npx @topmindspace/topmind-writing-skills install all --to ./.claude/skills
+npx @topmindspace/topmind-writing-skills status --to ./.claude/skills
+npx @topmindspace/topmind-writing-skills@latest update --to ./.claude/skills
 npx @topmindspace/topmind-writing-skills install topmind-briefs --to ./.claude/skills
-npx @topmindspace/topmind-writing-skills@latest install topmind-briefs   # 升级：暂存完成再替换，失败保留旧版
-npx @topmindspace/topmind-writing-skills install topmind-briefs --force   # 同版本重装 / 降级
+npx @topmindspace/topmind-writing-skills install topmind-briefs --force --to ./.claude/skills
 npx @topmindspace/topmind-writing-skills uninstall topmind-briefs --to ./.claude/skills
-npx github:topmindspace/topmind-writing-skills install topmind-briefs     # 跟仓库最新
+npx github:topmindspace/topmind-writing-skills update --to ./.claude/skills
 ```
 
-- 默认探测 `./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`，再到用户级目录；安装摘要会打印实际目标目录。
-- 更旧的安装先暂存再替换，失败保留旧版；版本相同提示已是最新；同版本重装或降级用 `--force`。有本地修改先备份。
+- `install all` 首次安装整套；`update` 默认只更新已装的技能，不会擅自加装新技能；`status` 显示当前包快照与安装目录的差异。三者都支持 `--to` 指定实际目录。
+- 不写 `--to` 时先找唯一的 TopMind 安装，再找唯一的技能目录或宿主配置；若同时存在多个候选，会列出目录并要求明确选择。没有宿主配置时使用当前项目的 `./.agents/skills`。结果会打印实际目录。
+- 更新先复制到临时目录，完整后才替换；失败保留旧版。受管安装发现本地改动会停止，需明确 `--force`；强制替换时保留旧副本。升级早期未带安装记录的副本也会自动留备份。软链接或非同名技能目录不会被覆盖。
+- 同版本不重复复制；已装版本比包新时拒绝降级，除非显式 `--force`。升级后重新打开 AI 会话，让宿主重新发现技能。
 - 技能 id 不是独立 npm 包，不要 `npm install topmind-briefs`。
 
 ### 从本地仓库升级
@@ -274,11 +282,12 @@ npx github:topmindspace/topmind-writing-skills install topmind-briefs     # 跟
 本地未发布改动要从当前仓库安装，`@latest` 只包含 npm 已发布版本。先核实目标目录；已有跨工具软链接时更新其共享实际目录，保留链接关系。Codex 独立安装可在仓库根目录运行：
 
 ```bash
-for skill in $(node scripts/discover_skills.js); do
-  node bin/topmind-writing-skills.js install "$skill" --to "$HOME/.codex/skills" || break
-done
+node bin/topmind-writing-skills.js status --to "$HOME/.codex/skills"
+node bin/topmind-writing-skills.js update --to "$HOME/.codex/skills"
 ```
 
+首次安装改用 `install all`；修改过技能内容而未改版本号时，用 `install <id> --force --to <实际目录>` 明确重装。CLI 只复制单个技能目录内的独立资源，不写入目标根目录的 `shared/`。
+
 若 Codex 技能链接到其他共享目录，将 `--to` 换为核实后的实际目录；检查每项安装输出。安装了新技能或更新入口后，重开会话让宿主重新发现；同版本未发布内容需要明确加 `--force` 才会重装。
 
 <details>

package/bin/topmind-writing-skills.js

@@ -17,11 +17,13 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 const ROOT = path.resolve(__dirname, '..');
 // Skills live at repo root (one directory per skill with SKILL.md).
 const INFRA_DIRS = new Set(['bin', 'docs', 'scripts', 'shared', 'evals', 'node_modules', 'dist', 'release-assets']);
 const SKILL_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const INSTALL_RECORD = '.topmind-install.json';
 
 function die(msg, code = 1) {
   console.error(msg);
@@ -113,7 +115,7 @@ function installerVersion() {
 
 function resolveDefaultTarget() {
   const home = process.env.HOME || process.env.USERPROFILE || '';
-  const candidates = [
+  const candidates = [...new Set([
     path.join(process.cwd(), '.agents', 'skills'),
     path.join(process.cwd(), '.claude', 'skills'),
     path.join(process.cwd(), '.cursor', 'skills'),
@@ -123,25 +125,89 @@ function resolveDefaultTarget() {
     path.join(home, '.agents', 'skills'),
     path.join(home, '.cursor', 'skills'),
     path.join(home, '.codex', 'skills'),
-  ];
-  for (const dir of candidates) {
-    if (dir && fs.existsSync(path.dirname(dir))) {
-      return dir;
-    }
+  ])];
+  const choose = (paths) => {
+    if (paths.length === 1) return paths[0];
+    if (paths.length > 1) die(`More than one skill directory matches:\n  ${paths.join('\n  ')}\nChoose one with --to <dir>.`);
+    return null;
+  };
+  // Prefer the user's existing TopMind installation, then an existing skills
+  // directory, then a single host configuration. A mere cwd is not a signal.
+  const ids = listSkillIds();
+  const withTopmind = candidates.filter((dir) => ids.some((id) => fs.existsSync(path.join(dir, id, 'SKILL.md'))));
+  const withSkills = candidates.filter((dir) => fs.existsSync(dir));
+  const withHost = candidates.filter((dir) => fs.existsSync(path.dirname(dir)) && path.dirname(dir) !== process.cwd() && path.dirname(dir) !== home);
+  for (const group of [withTopmind, withSkills, withHost]) {
+    const selected = choose(group);
+    if (selected) return selected;
   }
+  // No host exists yet: use the cross-agent project convention explicitly.
   return path.join(process.cwd(), '.agents', 'skills');
 }
 
+function readSkillName(skillPath) {
+  try {
+    const text = fs.readFileSync(path.join(skillPath, 'SKILL.md'), 'utf8');
+    const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    return (fm && fm[1].match(/^name:\s*([a-z0-9-]+)\s*$/m) || [])[1] || '';
+  } catch { return ''; }
+}
+
+function skipGeneratedEntry(entry) {
+  return (entry.isDirectory() && ['node_modules', 'dist', '__pycache__'].includes(entry.name)) ||
+    (entry.isFile() && entry.name.endsWith('.pyc'));
+}
+
+function skillDigest(skillPath) {
+  const hash = crypto.createHash('sha256');
+  const walk = (dir, relative = '') => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!relative && entry.name === INSTALL_RECORD) continue;
+      if (skipGeneratedEntry(entry)) continue;
+      const rel = path.join(relative, entry.name);
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(absolute, rel);
+      } else {
+        hash.update(rel.replace(/\\/g, '/') + '\0');
+        if (entry.isFile()) hash.update(fs.readFileSync(absolute));
+        else hash.update(`non-regular:${entry.name}`);
+        hash.update('\0');
+      }
+    }
+  };
+  walk(skillPath);
+  return hash.digest('hex');
+}
+
+function installedState(skillId, targetRoot) {
+  const dest = path.join(targetRoot, skillId);
+  let stat;
+  try { stat = fs.lstatSync(dest); } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return { kind: 'missing', version: '' };
+    throw error;
+  }
+  if (!stat.isDirectory() || readSkillName(dest) !== skillId) return { kind: 'conflict', version: '' };
+  const version = readSkillVersion(dest);
+  const recordPath = path.join(dest, INSTALL_RECORD);
+  if (!fs.existsSync(recordPath)) return { kind: 'legacy', version };
+  try {
+    const record = JSON.parse(fs.readFileSync(recordPath, 'utf8'));
+    if (record.id === skillId && record.digest === skillDigest(dest)) return { kind: 'managed', version };
+  } catch { /* Treat unreadable records as local changes. */ }
+  return { kind: 'modified', version };
+}
+
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     const s = path.join(src, entry.name);
     const d = path.join(dest, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '__pycache__') continue;
+      if (skipGeneratedEntry(entry)) continue;
       copyDir(s, d);
     } else if (entry.isFile()) {
-      if (entry.name.endsWith('.pyc')) continue;
+      if (skipGeneratedEntry(entry)) continue;
       fs.copyFileSync(s, d);
     } else {
       console.warn(`warning: skipping non-regular file: ${s}`);
@@ -207,7 +273,7 @@ function compareVersions(a, b) {
   return 0;
 }
 
-function install(skillId, targetRoot, { force = false, defaultTarget = false } = {}) {
+function planInstall(skillId, targetRoot, force) {
   assertSkillId(skillId);
   const src = skillDir(skillId);
   if (!fs.existsSync(path.join(src, 'SKILL.md'))) {
@@ -215,6 +281,26 @@ function install(skillId, targetRoot, { force = false, defaultTarget = false } =
   }
   const dest = path.join(targetRoot, skillId);
   assertDestOutsideSource(src, dest);
+  const state = installedState(skillId, targetRoot);
+  if (state.kind === 'conflict') die(`Refusing to replace ${dest}: it is not a ${skillId} skill directory.`);
+  if (state.kind === 'modified' && !force) {
+    die(`Local changes found in ${dest}. Keep them or pass --force to replace; the previous copy will be retained.`);
+  }
+  const packageVer = readSkillVersion(src) || 'unknown';
+  const cmp = compareVersions(packageVer, state.version);
+  if (state.kind !== 'missing' && !force && cmp < 0) {
+    die(`Installed ${skillId} ${state.version} is newer than packaged ${packageVer}; not downgrading. Pass --force (or -f) to downgrade.`);
+  }
+  return { src, dest, state, packageVer, cmp };
+}
+
+function install(skillId, targetRoot, { force = false, defaultTarget = false } = {}) {
+  const { src, dest, state, cmp } = planInstall(skillId, targetRoot, force);
+  if (state.kind !== 'missing' && !force && cmp === 0) {
+    console.log(`Already up to date: ${skillId} ${state.version} (use --force to reinstall)`);
+    console.log(`  at:      ${dest}`);
+    return;
+  }
   try {
     fs.mkdirSync(targetRoot, { recursive: true });
   } catch (e) {
@@ -224,37 +310,28 @@ function install(skillId, targetRoot, { force = false, defaultTarget = false } =
         'Choose a --to directory that can be created (not a file, not unwritable).'
     );
   }
-  let upgradedFrom = null;
-  if (fs.existsSync(dest)) {
-    // 已装过：默认升级。打包版本更新 → 直接覆盖（不备份）；相同 → 已是最新；已装版本更新 → 需 --force。
-    const installedVer = readSkillVersion(dest);
-    const packageVer = readSkillVersion(src) || 'unknown';
-    const cmp = compareVersions(packageVer, installedVer);
-    if (!force && cmp === 0) {
-      console.log(`Already up to date: ${skillId} ${installedVer} (use --force to reinstall)`);
-      console.log(`  at:      ${dest}`);
-      return;
-    }
-    if (!force && cmp < 0) {
-      die(
-        `Installed ${skillId} ${installedVer} is newer than packaged ${packageVer}; not downgrading. ` +
-          'Pass --force (or -f) to downgrade.'
-      );
-    }
-    upgradedFrom = cmp > 0 ? installedVer || 'unknown' : null;
-  }
+  const upgradedFrom = state.kind !== 'missing' && cmp > 0 ? state.version || 'unknown' : null;
+  const retainPrevious = state.kind === 'legacy' || state.kind === 'modified';
   const stage = fs.mkdtempSync(path.join(targetRoot, `.${skillId}-stage-`));
   let previous = null;
   try {
     copyDir(src, stage);
-    if (fs.existsSync(dest)) {
+    fs.writeFileSync(path.join(stage, INSTALL_RECORD), JSON.stringify({
+      id: skillId,
+      version: readSkillVersion(src),
+      digest: skillDigest(stage),
+    }, null, 2) + '\n');
+    if (state.kind !== 'missing') {
       previous = fs.mkdtempSync(path.join(targetRoot, `.${skillId}-previous-`));
       fs.rmdirSync(previous);
       fs.renameSync(dest, previous);
     }
     try { fs.renameSync(stage, dest); }
     catch (error) { if (previous) { fs.renameSync(previous, dest); previous = null; } throw error; }
-    if (previous) { try { fs.rmSync(previous, { recursive: true, force: true }); } catch { console.warn(`Previous copy retained at: ${previous}`); } }
+    if (previous && !retainPrevious) {
+      try { fs.rmSync(previous, { recursive: true, force: true }); }
+      catch { console.warn(`Previous copy retained at: ${previous}`); }
+    }
   } catch (error) {
     fs.rmSync(stage, { recursive: true, force: true });
     die(`Install failed; the previous installed skill was retained. ${error.message}`);
@@ -266,9 +343,25 @@ function install(skillId, targetRoot, { force = false, defaultTarget = false } =
   else console.log(`Installed ${skillId}`);
   console.log(`  to:      ${dest}${toNote}`);
   console.log(`  version: skill ${skillVer} (installer ${installerVersion()})`);
+  if (previous && retainPrevious) console.log(`  backup:  ${previous} (previous untracked or locally changed copy)`);
   console.log(`  next:    ${nextStep(skillId, dest)}`);
 }
 
+function status(targetRoot) {
+  console.log(`Skill directory: ${targetRoot}`);
+  console.log('Packaged version | Installed version | State | Skill');
+  for (const id of listSkillIds()) {
+    const packaged = readSkillVersion(skillDir(id)) || 'unknown';
+    const state = installedState(id, targetRoot);
+    let label = state.kind;
+    if (state.kind === 'managed' || state.kind === 'legacy') {
+      const cmp = compareVersions(packaged, state.version);
+      label = cmp > 0 ? 'update available' : cmp < 0 ? 'installed newer' : state.kind === 'legacy' ? 'untracked' : 'current';
+    }
+    console.log(`${packaged} | ${state.version || '—'} | ${label} | ${id}`);
+  }
+}
+
 function nextStep(skillId, dest) {
   return 'restart your agent so it picks up the skill';
 }
@@ -319,22 +412,25 @@ function usageText() {
 
 Usage:
   topmind-writing-skills list|ls
-  topmind-writing-skills install <skill-id> [--to|-t <dir>] [--force|-f]
+  topmind-writing-skills status [--to|-t <dir>]
+  topmind-writing-skills install <skill-id|all> [--to|-t <dir>] [--force|-f]
+  topmind-writing-skills update [skill-id|all] [--to|-t <dir>] [--force|-f]
   topmind-writing-skills uninstall <skill-id> [--to|-t <dir>]
   topmind-writing-skills help
 
 Behavior:
-  install    copies <skill-id>/ into <dir>/<skill-id>/. If the skill is already
-             installed: a newer packaged version upgrades it in place (no backup,
-             prints "Upgraded <id> <old> -> <new>"); the same version prints
-             "Already up to date" (--force reinstalls); an installed version newer
-             than the package is refused unless --force. A missing/unparseable
-             installed version counts as an upgrade. Prints where/what-version/
-             next-steps when done.
+  status     compares the local package with skills installed in <dir>.
+  install    installs one skill or all eight; newer packaged versions upgrade
+             existing copies. Equal versions are left alone. A newer installed
+             version requires --force. Locally changed managed copies are kept
+             unless --force is explicit. Untracked older copies are backed up
+             during upgrade. The replacement is staged before switching.
+  update     upgrades only installed skills (all by default); does not add new ones.
   uninstall  removes <dir>/<skill-id>/ (refuses: not installed, not a skill
              directory, or the package's own skill source).
-  No --to: the target directory is auto-detected (probe order below) and
-  printed explicitly in the install summary.
+  No --to: choose a single existing TopMind installation, skills directory or
+  host configuration. Ambiguous matches require --to. With no host configured,
+  use ./.agents/skills and print the chosen location.
 
 Target probe order (no --to): ./.agents/skills, ./.claude/skills,
   ./.cursor/skills, ./.codex/skills, ./.mimocode/skills, then
@@ -342,6 +438,9 @@ Target probe order (no --to): ./.agents/skills, ./.claude/skills,
 
 Examples (npm recommended when published):
   npx @topmindspace/topmind-writing-skills list
+  npx @topmindspace/topmind-writing-skills status
+  npx @topmindspace/topmind-writing-skills install all
+  npx @topmindspace/topmind-writing-skills@latest update
   npx @topmindspace/topmind-writing-skills install topmind-briefs
   npx @topmindspace/topmind-writing-skills install topmind-briefs --to ./.agents/skills
   npx @topmindspace/topmind-writing-skills install topmind-briefs --force
@@ -358,6 +457,22 @@ function usage() {
   console.log(usageText());
 }
 
+function parseOptions(args, start, { allowForce = false } = {}) {
+  let to = null;
+  let force = false;
+  for (let i = start; i < args.length; i++) {
+    if (args[i] === '--to' || args[i] === '-t') {
+      to = args[++i];
+      if (!to || to.startsWith('-')) die('Option --to requires a directory path.');
+    } else if (allowForce && (args[i] === '--force' || args[i] === '-f')) {
+      force = true;
+    } else {
+      die(`Unknown option: ${args[i]}\n\n` + usageText());
+    }
+  }
+  return { targetRoot: to ? path.resolve(to) : resolveDefaultTarget(), force, defaultTarget: !to };
+}
+
 function main(argv) {
   const args = argv.slice(2);
   const cmd = args[0];
@@ -381,25 +496,32 @@ function main(argv) {
     return;
   }
 
-  if (cmd === 'install') {
-    const skillId = args[1];
-    if (!skillId || skillId.startsWith('-')) {
+  if (cmd === 'status') {
+    const { targetRoot } = parseOptions(args, 1);
+    status(targetRoot);
+    return;
+  }
+
+  if (cmd === 'install' || cmd === 'update') {
+    const requested = cmd === 'update' && (!args[1] || args[1].startsWith('-')) ? 'all' : args[1];
+    if (!requested || requested.startsWith('-')) {
       die('Missing skill id.\n\n' + usageText());
     }
-    let to = null;
-    let force = false;
-    for (let i = 2; i < args.length; i++) {
-      if (args[i] === '--to' || args[i] === '-t') {
-        to = args[++i];
-        if (!to) die('Option --to requires a directory path.');
-      } else if (args[i] === '--force' || args[i] === '-f') {
-        force = true;
-      } else {
-        die(`Unknown option: ${args[i]}\n\n` + usageText());
-      }
+    const optionStart = cmd === 'update' && requested === 'all' && args[1] !== 'all' ? 1 : 2;
+    const options = parseOptions(args, optionStart, { allowForce: true });
+    const ids = requested === 'all' ? listSkillIds() : [requested];
+    const selected = cmd === 'update'
+      ? ids.filter(id => installedState(id, options.targetRoot).kind !== 'missing')
+      : ids;
+    if (!selected.length) {
+      console.log(`No TopMind writing skills installed in ${options.targetRoot}. Run install all to get started.`);
+      return;
     }
-    const targetRoot = to ? path.resolve(to) : resolveDefaultTarget();
-    install(skillId, targetRoot, { force, defaultTarget: !to });
+    // Check every target before the first write; a conflict should not leave
+    // an avoidably half-updated set.
+    for (const id of selected) planInstall(id, options.targetRoot, options.force);
+    for (const id of selected) install(id, options.targetRoot, options);
+    if (selected.length > 1) console.log(`${cmd === 'install' ? 'Installed' : 'Updated'} ${selected.length} writing skills in ${options.targetRoot}.`);
     return;
   }
 

package/lib/host-pack.cjs

@@ -28,7 +28,17 @@ function buildHostPack(root) {
     if (!/^---\r?\n/u.test(raw) || !/^name:\s*/mu.test(raw)) throw new Error(`Invalid skill: ${id}`);
     return { id, name: id, description: meta.description || id, version: meta.version, packId: 'topmind-writing-skills' };
   });
-  const manifest = { schema_version: 1, name: 'topmind-writing-skills', version: pkg.version, license: pkg.license, repository: pkg.repository, entry_files: ids.map(id => `${id}/SKILL.md`), files, runtime: { api: 1, entry: 'runtime/article-renderer.mjs', update: 'host-release' } };
+  const capabilities = [
+    { id: 'article.render', entry: 'runtime/article-renderer.mjs', export: 'prepareArticleResult' },
+    { id: 'article.renderFromSource', entry: 'runtime/article-renderer.mjs', export: 'prepareArticleResultFromSource' },
+    { id: 'article.localTextDocument', entry: 'runtime/article-renderer.mjs', export: 'articleLocalTextDocument' },
+    { id: 'length.evaluate', entry: 'runtime/length-rules.mjs', export: 'evaluateLengthRules' },
+    { id: 'length.ruleset.evaluate', entry: 'runtime/length-ruleset.mjs', export: 'evaluateLengthRuleSet' },
+  ];
+  for (const capability of capabilities) {
+    if (!Object.hasOwn(files, capability.entry)) throw new Error(`Missing runtime capability entry: ${capability.entry}`);
+  }
+  const manifest = { schema_version: 1, name: 'topmind-writing-skills', version: pkg.version, license: pkg.license, repository: pkg.repository, entry_files: ids.map(id => `${id}/SKILL.md`), files, runtime: { api: 1, entry: 'runtime/article-renderer.mjs', capabilities, update: 'host-release' } };
   const digest = hash(JSON.stringify(manifest));
   return { manifest: { ...manifest, digest }, snapshot: { id: manifest.name, version: pkg.version, source: 'https://github.com/topmindspace/topmind-writing-skills', license: pkg.license, digest, skills, resources } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topmindspace/topmind-writing-skills",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "TopMindSpace 写作技能合集 — 通过 npm / npx 安装技能（公众号长文、X 长文、干货短文、X 引流短帖、改稿与质检、封面图、长图海报）。只出稿与发布包，不代发。",
   "license": "MIT",
   "author": "TopMindspace",
@@ -76,7 +76,7 @@
     "check:pack": "node scripts/check_npm_pack.js",
     "validate:spec": "bash -c 'for s in $(node scripts/discover_skills.js); do ${AGENTSKILLS:-agentskills} validate \"$s\" || exit 1; done'",
     "prepack": "node scripts/sync_npm_files.js --check && node scripts/sync_shared.js --check && python3 shared/scripts/knowledge.py validate",
-    "install:skills": "node -e \"const {discoverSkills}=require('./scripts/discover_skills'); const {spawnSync}=require('child_process'); for (const id of discoverSkills()) { const r=spawnSync(process.execPath,['bin/topmind-writing-skills.js','install',id],{stdio:'inherit'}); if(r.status) process.exit(r.status||1); }\"",
+    "install:skills": "node bin/topmind-writing-skills.js install all",
     "check": "node scripts/run_skill_gates.js check",
     "privacy": "python3 scripts/ci_privacy_scan.py",
     "audit": "node scripts/run_skill_gates.js audit",

package/runtime/article-renderer.d.mts

@@ -1,9 +1,30 @@
 export type WritingPlatform = 'wechat' | 'x' | 'text';
 export type WritingTheme = 'minimal-ink' | 'tech-blue' | 'newsprint' | 'graphite';
 export const WRITING_THEMES: Record<WritingTheme, { ink: string; accent: string; paper: string; muted: string }>;
+export const ARTICLE_RENDERER_PROVIDER: Readonly<{ id: string; version: string }>;
 export const WRITING_ACTIONS: ReadonlyArray<{ id: string; zh: string; en: string; prompt: string; promptEn: string }>;
 export function stripFrontmatter(value: string): string;
 export interface ArticleDelivery { platform: WritingPlatform; theme: WritingTheme; html: string; body: string; text: string; checklist: string; images: Array<{ source: string; alt: string; status: string }>; diagnostics: Array<{ code: string; source?: string }> }
 export function renderArticle(input: { markdown: string; platform?: WritingPlatform; theme?: WritingTheme; title?: string; images?: Record<string, string> }): ArticleDelivery;
 export function resolveArticleImage(sourcePath: string, reference: string): string;
 export function prepareArticle(input: { sourcePath: string; markdown: string; platform?: WritingPlatform; theme?: WritingTheme; title?: string }, readImage: (relative: string) => Promise<string>): Promise<ArticleDelivery>;
+export interface ArticleResult {
+  schemaVersion: 1;
+  capabilityId: 'article.render';
+  provider: Readonly<{ id: string; version: string }>;
+  status: 'ok' | 'warning' | 'error';
+  input: { fingerprint: string | null; target?: { platform: WritingPlatform; theme: WritingTheme };
+    source?: { relativePath: string; sha256: string };
+    imageBytes?: Array<{ relativePath: string; sha256: string }>;
+    creationSnapshotFingerprint?: string; localTextTitle?: string | null;
+    renderParameters?: { theme: WritingTheme; title: string } };
+  artifacts: Array<{ role: 'preview' | 'clipboard-html' | 'source-markdown' | 'image-checklist' | 'local-clipboard-text'; format: string; content: string; sha256: string }>;
+  images: ArticleDelivery['images'];
+  diagnostics: Array<{ code: string; severity: 'warning' | 'error'; message: string; location?: { source: string } }>;
+}
+export function renderArticleResult(input?: { markdown?: string; platform?: WritingPlatform; theme?: WritingTheme; title?: string; sourcePath?: string; images?: Record<string, string> }): Promise<ArticleResult>;
+export function prepareArticleResult(input: { sourcePath: string; markdown: string; platform?: WritingPlatform; theme?: WritingTheme; title?: string }, readImage: (relative: string) => Promise<string>): Promise<ArticleResult>;
+export function prepareArticleResultFromSource(input: { sourcePath: string; sourceBytes: Uint8Array;
+  platform?: WritingPlatform; theme?: WritingTheme; title?: string; creationSnapshotFingerprint?: string },
+  readImage: (relative: string) => Promise<string>): Promise<ArticleResult>;
+export function articleLocalTextDocument(result: ArticleResult): { text_kind: 'platform_text'; title?: string; body: string } | null;