harveyz-skill 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.35.0] - 2026-09-21
+
+### Added
+- `learn-video`：新增 `build_creator_index.py`（`build`/`check` 两个子命令）。扫描 vdl 写出的全部 `meta.json`，按归一化后的 YouTube handle（去 `@`、转小写）分组，产出 `<knowledgeRoot>/videos/creators.json`。不读、不写 `registry.json`——"是不是在关注这个人"是判断，判断不落盘在事实旁边，完全交给下游（scholia）现查决定，索引本身永远不含 `watched`/`creator_id`。原子写（临时文件 + rename），构建失败旧索引原样保留；单个 `meta.json` 损坏时归入 `unresolved` 而不是从统计里静默消失；`work` 目录不存在（vdl 的 `WORK_ROOT` 漂了）时报错退出，不会把一个正常的索引悄悄替换成空索引
+
+### Changed
+- **破坏性变更** `learn-video`：`archive.py` 从"写 `meta.json`"降级为"校验 `meta.json`"。vdl（Video-Learner 仓库）现在自己把 `uploader_id`/`channel_id`/`uploader_url` 三个新字段与统一存储契约的三个必填字段（`source_url`/`title`/`fetched_at`）全部写好，`archive.py` 只剩读一遍 `meta.json` 核对必填字段是否齐全，不再从 vdl 的 sqlite 捞取任何展示字段，也不再写文件。CLI 入参从 `TASK_ID`/`SOURCE_URL`/`TITLE`/`FETCHED_AT` 四个环境变量精简到只剩 `TASK_ID`。version 1.8.2 → 1.9.0
+  - **升级路径**：这是 vdl 那一侧先落地的改动的下游收尾。若本机 vdl 版本落后（写出的 `meta.json` 还没有新增字段/契约字段），归档步骤会直接报错停下并列出缺的字段名，不会再像过去那样悄悄补一份缺字段的 `meta.json`。看到这个报错，先确认 Video-Learner 是否需要升级
+
+## [0.34.0] - 2026-09-16
+
+### Added
+- `hskill` 双来源安装与粘性更新：`hskill update --local <路径>` 从本地仓库 `npm pack` 出 tarball 再全局安装（真实拷贝，走 `prepack` 与 `files[]` 白名单，等于在发 npm 前预演一次真实发布），`hskill update --npm` 切回 registry，裸 `hskill update` 沿用当前来源不跨轨道。此前 `update` 是一行硬编码的 `npm install -g harveyz-skill@latest`，手工装的本地版会被它静默替换掉且事后无从察觉。来源痕迹（`.hskill-source.json` + 版本号后缀 `+local`）只写在全局安装目录内，因而任何一次 `npm install -g`——包括绕过 hskill 的手工安装——都会自动抹掉它，"记录的来源"与"实际的来源"不可能分叉。`hskill version` 展示来源与 branch/commit，`version --check` 在本地来源下比对 commit 而非版本号（开发分支上版本号常常不动）。设计见 `docs/superpowers/specs/2026-09-15-hskill-install-source-design.md`
+- `agent-canvas` bundle：新增 `agent-canvas-control`、`capture-requirement`、`close-node`、`describe-node`、`relate-node`、`relation-review` 六个 skill，在 Agent Canvas 画布节点里操控节点实体、摆放画布、梳理节点间语义关系
+
+### Fixed
+- `hskill <任意子命令> --json` 在输出走管道时被截断：Node 写管道是异步的，而每个子命令块以 `process.exit()` 结尾，不等缓冲区排空。`status --json` 的输出刚随 agent-canvas 六个 skill 涨到 66,739 字节、越过 64KiB 管道缓冲区，于是 `hskill status --json | jq` 拿到退出码 0 和一段从字符串中间断掉的 JSON——**静默失败**，退出码还宣称成功。16 处 `--json` 出口统一改走等待写入落地的 `emitJson()`；回归测试逐字节比对管道输出与直接重定向输出，且在负载跌回缓冲区以下时显式 skip 而非假绿
+- `hskill version` / `hskill --version` 在 npm 不在 PATH 上时抛原始堆栈崩溃（cron、受限 PATH、精简镜像）：来源追踪让 `readSource()` 每次都经 `globalRoot()` 打一次 `npm root -g`，而它只兜住了 JSON 解析失败。现在 `globalRoot()` 的失败并入同一个 `null`，即回落到缺省的 npm 来源
+- `compareVersions()` 遇到 semver build metadata（`0.33.0+local`）会解析出 `NaN` 导致比较结果无意义，现按规范在比较前截断 `+` 及其后内容
+
 ## [0.33.0] - 2026-09-15
 
 ### Added

package/README.md

@@ -96,14 +96,43 @@ hskill install --bundle dev                     # 安装整个 bundle
 hskill install --skill git-workflow-init        # 安装单个 skill
 hskill install --tool hub                       # 安装 shell 工具
 hskill list                                     # 查看可用 skill
-hskill update                                   # 更新到最新版
+hskill update                                   # 更新 hskill 自身（沿用当前来源）
+hskill version                                  # 查看版本与安装来源
 hskill --help                                   # 查看帮助
 ```
 
 Skills 安装到 `~/.claude/skills/`，shell 工具安装到 `~/.local/bin/`。
 
+**从本地仓库安装 hskill 自身**
+
+发版前想先用一阵子工作树里的改动，可以把 hskill 装成本地来源：
+
+```bash
+hskill update --local ~/Projects/harveyz-skill   # 从本地仓库打包安装
+hskill update                                    # 之后裸跑就一直走本地，不会跳回 npm
+hskill update --npm                              # 显式切回 npm registry
+```
+
+`--local` 走的是 `npm pack` + 安装 tarball，**不是软链**——产出独立快照，并且真实执行 `prepack` 与 `package.json` 的 `files[]` 白名单，等于在发 npm 之前预演一次真实发布，能提前暴露打包问题。
+
+两种来源共存于同一个命令，`update` 是**粘性**的：本地装的就从原仓库重新打包，npm 装的就走 registry，**裸 `update` 永远不跨来源**。跨来源只能由 `--local` / `--npm` 显式触发，触发时会打印完整迁移行。
+
+安装来源记在全局安装目录里（`.hskill-source.json` + 版本号后缀 `+local`）。因为任何一次 `npm install -g` 都会清空重建该目录，绕过 hskill 手工安装也会自动抹掉痕迹，所以记录的来源不会与实际情况脱节：
+
+```console
+$ hskill version
+0.34.0+local
+
+source: local  /Users/you/Projects/harveyz-skill
+branch: staging  commit: 3d4192a
+```
+
+本地来源下 `hskill version --check` 比对的是**记录的 commit 与仓库 HEAD**，不是版本号——开发分支上版本号常常几十个提交不动，能动的只有 commit。
+
 **本地源码开发**
 
+不安装、直接从仓库跑 CLI 来装 skill：
+
 ```bash
 node bin/cli.js install --skill mermaid-diagram --target claude
 node bin/cli.js install --bundle dev --target claude
@@ -149,7 +178,7 @@ hskill hooks uninstall check-similar-branch --scope project    # 从当前项目
 | **hskill_install** | 安装一个 bundle、指定 skill 或 shell 工具 |
 | **hskill_uninstall** | 卸载指定的 skill 或 shell 工具 |
 | **hskill_hooks** | 查看、安装或卸载 hskill git hooks |
-| **hskill_update** | 将 hskill 自身更新到最新版本 |
+| **hskill_update** | 更新 hskill 自身，沿用当前安装来源（npm 或本地仓库）；切换来源需用 CLI 的 `--npm` / `--local` |
 
 在 MCP host 的配置中注册（假设已通过 `npm install -g harveyz-skill` 全局安装）：
 

package/bin/cli.js

@@ -2,14 +2,14 @@
 import { select, input, confirm } from '@inquirer/prompts'
 import chalk from 'chalk'
 import { execSync, spawnSync } from 'child_process'
-import { existsSync, writeFileSync, unlinkSync } from 'fs'
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdtempSync } from 'fs'
 import { createRequire } from 'module'
 import os from 'os'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import {
   getAllSkillItems, getAllToolItems, getAllHookItems, checkHookInstalled,
-  checkInstalled, checkToolInstalled, scopeSummary,
+  checkInstalled, checkToolInstalled, scopeSummary, toSkillItems,
   resolveSkills, resolveSkillsByName, resolveTools, resolveToolsByName,
   TOOL_BUNDLE_CHOICES,
 } from '../lib/bundles.js'
@@ -24,6 +24,16 @@ const args = process.argv.slice(2)
 const subcommand = args[0]
 const jsonFlag = args.includes('--json')
 
+// Writing to a pipe is asynchronous in Node, and process.exit() throws away
+// whatever is still buffered. Anything past the 64KiB pipe buffer was being cut
+// mid-string, so `hskill status --json | jq` got exit code 0 and unparseable
+// JSON. Every --json emitter goes through here, which resolves only once the
+// write has actually landed.
+async function emitJson(value) {
+  const text = JSON.stringify(value, null, 2) + '\n'
+  await new Promise(resolve => process.stdout.write(text, resolve))
+}
+
 // ── Help ─────────────────────────────────────────────────────────────────────
 function printHelp() {
   console.log(`
@@ -50,10 +60,12 @@ function printHelp() {
     hskill uninstall <tool>            uninstall a shell tool and clean up all files
     hskill uninstall <tool> --yes      skip all confirmations (incl. config files)
     hskill uninstall <skill> --scope <s> --target <t>  uninstall a skill
-    hskill update                  update hskill to the latest version
+    hskill update                  update hskill (sticky: refreshes from whichever source is installed)
+    hskill update --local <path>   switch to / refresh a local repo (npm pack + install)
+    hskill update --npm            switch back to npm registry
     hskill mcp                     start an MCP server (stdio) exposing hskill's tools to MCP-capable agent hosts
-    hskill version                 show version
-    hskill version --check         compare local version against npm registry (no install)
+    hskill version                 show version (adds source/branch/commit lines when installed from a local repo)
+    hskill version --check         compare against npm registry, or against the local source repo's HEAD
     hskill --help                  show this help
 
   ${chalk.cyan('Examples:')}
@@ -74,7 +86,7 @@ function printHelp() {
 
 if (args[0] === '--help' || args[0] === '-h') {
   if (jsonFlag || args.includes('--json')) {
-    console.log(JSON.stringify({
+    await emitJson({
       name: 'hskill',
       version,
       description: 'Skill manager for Claude Code, Cursor, Codex, OpenClaw, Hermes, OpenCode, and Pi',
@@ -138,7 +150,11 @@ if (args[0] === '--help' || args[0] === '-h') {
         },
         {
           name: 'update',
-          description: 'Update hskill to the latest version via npm',
+          description: 'Update hskill; sticky to whichever source (npm or local repo) is currently installed',
+          flags: [
+            { name: '--local', arg: '<path>', description: 'Switch to / refresh a local repo source (npm pack + install -g)' },
+            { name: '--npm',   description: 'Switch back to the npm registry source' },
+          ],
         },
         {
           name: 'mcp',
@@ -149,7 +165,7 @@ if (args[0] === '--help' || args[0] === '-h') {
           description: 'Print version and exit',
         },
       ],
-    }, null, 2))
+    })
     process.exit(0)
   }
   printHelp()
@@ -157,12 +173,37 @@ if (args[0] === '--help' || args[0] === '-h') {
 }
 
 if (args[0] === '--version' || args[0] === '-v' || subcommand === 'version') {
+  const { readSource, gitInfo } = await import('../lib/install-source.js')
+  const source = readSource()
+
   if (subcommand === 'version' && args.includes('--check')) {
+    if (source) {
+      let current
+      try {
+        current = gitInfo(source.repo)
+      } catch (err) {
+        console.error(chalk.red(`  ✗ Could not read local source repo: ${err.message}`))
+        process.exit(1)
+      }
+      const upToDate = current.commit === source.commit && !current.dirty
+      if (jsonFlag) {
+        await emitJson({ source: 'local', repo: source.repo, installedCommit: source.commit, currentCommit: current.commit, dirty: current.dirty, upToDate })
+      } else if (upToDate) {
+        console.log(chalk.green(`  ✔ hskill is up to date with local source (${source.repo}@${current.commit})`))
+      } else if (current.commit !== source.commit) {
+        console.log(chalk.yellow(`  ⚠ local source has new commits: ${source.commit} → ${current.commit}`))
+        console.log(chalk.dim('  Run: hskill update'))
+      } else {
+        console.log(chalk.yellow('  ⚠ local source has uncommitted changes not yet packed'))
+        console.log(chalk.dim('  Run: hskill update'))
+      }
+      process.exit(0)
+    }
     try {
       const { checkNpmVersion } = await import('../lib/version-check.js')
       const { current, latest, upToDate } = await checkNpmVersion('harveyz-skill', version)
       if (jsonFlag) {
-        console.log(JSON.stringify({ current, latest, upToDate }, null, 2))
+        await emitJson({ current, latest, upToDate })
       } else if (upToDate) {
         console.log(chalk.green(`  ✔ hskill v${current} is up to date`))
       } else {
@@ -176,6 +217,11 @@ if (args[0] === '--version' || args[0] === '-v' || subcommand === 'version') {
     process.exit(0)
   }
   console.log(version)
+  if (source) {
+    console.log('')
+    console.log(`source: local  ${source.repo}`)
+    console.log(`branch: ${source.branch}  commit: ${source.commit}${source.dirty ? ' (dirty)' : ''}`)
+  }
   process.exit(0)
 }
 
@@ -223,22 +269,138 @@ async function checkArchivedInstalls() {
 }
 
 // ── Update ───────────────────────────────────────────────────────────────────
-if (subcommand === 'update') {
+// Sticky: whichever source is currently installed (recorded in .hskill-source.json
+// inside the global install dir) is what a bare `update` refreshes from. `--local`
+// and `--npm` explicitly switch the source. See docs/superpowers/specs/2026-09-15-hskill-install-source-design.md
+async function updateToNpm(priorSource) {
   console.log(chalk.dim('  · Updating hskill…'))
   try {
     execSync('npm install -g harveyz-skill@latest', { stdio: 'inherit' })
-    console.log(chalk.green('  ✔ hskill updated'))
   } catch {
     console.error(chalk.red('  ✗ Update failed. Try: npm install -g harveyz-skill@latest'))
     process.exit(1)
   }
+  if (priorSource) {
+    const { globalRoot } = await import('../lib/install-source.js')
+    const newVersion = JSON.parse(readFileSync(path.join(globalRoot(), 'harveyz-skill', 'package.json'), 'utf8')).version
+    console.log(`  ${priorSource.version}+local (${priorSource.branch}@${priorSource.commit}) → ${newVersion} (npm)`)
+  }
+  console.log(chalk.green('  ✔ hskill updated'))
+}
+
+async function updateToLocal(repoPath, priorSource) {
+  if (!existsSync(repoPath)) {
+    console.error(chalk.red(`  ✗ 本地来源仓库不存在：${repoPath}`))
+    console.error(chalk.dim('    改用 npm：   hskill update --npm'))
+    console.error(chalk.dim(`    指向新路径： hskill update --local <新路径>`))
+    process.exit(1)
+  }
+
+  const { gitInfo, writeSource, globalRoot } = await import('../lib/install-source.js')
+  // git info must be collected before `npm pack` — its `prepack` hook rewrites
+  // the tracked .npmignore, which would otherwise poison the dirty check.
+  const info = gitInfo(repoPath)
+  const origVersion = JSON.parse(readFileSync(path.join(repoPath, 'package.json'), 'utf8')).version
+
+  console.log(chalk.dim('  · Packing local repo…'))
+  const tmpDir = mkdtempSync(path.join(os.tmpdir(), 'hskill-pack-'))
+  const packResult = spawnSync('npm', ['pack', '--pack-destination', tmpDir], { cwd: repoPath, encoding: 'utf8' })
+  if (packResult.status !== 0) {
+    console.error(chalk.red('  ✗ npm pack failed'))
+    process.exit(1)
+  }
+  const tarballName = packResult.stdout.trim().split('\n').pop()
+
+  console.log(chalk.dim('  · Installing packed tarball…'))
+  const installResult = spawnSync('npm', ['install', '-g', path.join(tmpDir, tarballName)], { stdio: 'inherit' })
+  if (installResult.status !== 0) {
+    console.error(chalk.red('  ✗ Install failed'))
+    process.exit(1)
+  }
+
+  const installedPkgPath = path.join(globalRoot(), 'harveyz-skill', 'package.json')
+  const installedPkg = JSON.parse(readFileSync(installedPkgPath, 'utf8'))
+  installedPkg.version = `${origVersion}+local`
+  writeFileSync(installedPkgPath, JSON.stringify(installedPkg, null, 2) + '\n')
+
+  writeSource({
+    repo: repoPath,
+    branch: info.branch,
+    commit: info.commit,
+    dirty: info.dirty,
+    version: origVersion,
+    installedAt: new Date().toISOString(),
+  })
+
+  if (priorSource === null) {
+    console.log(`  ${version} (npm) → ${origVersion}+local (${info.branch}@${info.commit})`)
+  } else if (priorSource.repo !== repoPath) {
+    console.log(`  ${priorSource.version}+local (${priorSource.branch}@${priorSource.commit}) → ${origVersion}+local (${info.branch}@${info.commit})`)
+  }
+
+  const npmignoreStatus = execSync('git status --porcelain -- .npmignore', { cwd: repoPath, encoding: 'utf8' }).trim()
+  if (npmignoreStatus) {
+    console.log(chalk.dim('  · .npmignore changed by prepack — left as-is, review with `git diff .npmignore`'))
+  }
+
+  console.log(chalk.green('  ✔ hskill updated'))
+}
+
+if (subcommand === 'update') {
+  const updateArgs = args.slice(1)
+  const localIdx   = updateArgs.indexOf('--local')
+  const npmFlag    = updateArgs.includes('--npm')
+  const localGiven = localIdx !== -1
+  const localPath  = localGiven ? updateArgs[localIdx + 1] : undefined
+
+  if (localGiven && npmFlag) {
+    console.error(chalk.red('  ✗ --local and --npm are mutually exclusive'))
+    process.exit(1)
+  }
+  if (localGiven && (!localPath || localPath.startsWith('--'))) {
+    console.error(chalk.red('  ✗ --local requires a path: hskill update --local <path>'))
+    process.exit(1)
+  }
+
+  const { readSource } = await import('../lib/install-source.js')
+  const priorSource = readSource()
+
+  if (npmFlag) {
+    await updateToNpm(priorSource)
+  } else if (localGiven) {
+    await updateToLocal(localPath, priorSource)
+  } else if (priorSource) {
+    await updateToLocal(priorSource.repo, priorSource)
+  } else {
+    await updateToNpm(priorSource)
+  }
+
+  // Re-require fresh: the self-update above just replaced this install
+  // directory's skills-index.json on disk, but bin/cli.js's own top-level
+  // import of lib/bundles.js already cached the *old* skillDefs at process
+  // start. A plain require() here is the first hit for this path in this
+  // process, so it reads what's actually on disk now.
+  const { renames = [], skills: freshSkillDefs = [] } = require('../skills-index.json')
+  const skillsRoot = path.join(__dirname, '..', 'skills')
+
+  // Auto-upgrade skills opted into `autoUpdate: true` (skills-index.json),
+  // scoped to `user` to match `hskill upgrade`'s default scope.
+  const autoUpdateRows = buildSkillRows(null, toSkillItems(freshSkillDefs, skillsRoot))
+    .filter(r => r.autoUpdate)
+  if (autoUpdateRows.length > 0) {
+    const autoTargets = resolveTargets(['all'], 'user')
+    const autoSummary = await upgradeOutdatedSkills(autoUpdateRows, autoTargets, 'userDetail')
+    const upgraded = [...new Set(Object.values(autoSummary).flatMap(s => s.installed ?? []))]
+    const failed   = [...new Set(Object.values(autoSummary).flatMap(s => (s.failed ?? []).map(f => f.name)))]
+    if (upgraded.length > 0) console.log(chalk.green(`  ✔ Auto-updated ${upgraded.length} skill(s): ${upgraded.join(', ')}`))
+    if (failed.length   > 0) console.log(chalk.yellow(`  ⚠ Auto-update failed for: ${failed.join(', ')}`))
+  }
+
   // Run skill rename migrations
-  const { renames = [], skills: skillDefs = [] } = require('../skills-index.json')
   if (renames.length > 0) {
     console.log(chalk.dim('  · Migrating renamed skills…'))
     const targets = SKILL_TARGETS.map(name => ({ name, dir: userSkillDir(name) }))
-    const skillsRoot = path.join(__dirname, '..', 'skills')
-    const migrationSummary = await migrateRenamedSkills(renames, targets, skillsRoot, skillDefs)
+    const migrationSummary = await migrateRenamedSkills(renames, targets, skillsRoot, freshSkillDefs)
     const totalMigrated = Object.values(migrationSummary).reduce((n, s) => n + s.migrated.length, 0)
     const totalFailed   = Object.values(migrationSummary).reduce((n, s) => n + s.failed.length, 0)
     if (totalMigrated > 0) console.log(chalk.green(`  ✔ Migrated ${totalMigrated} skill(s)`))
@@ -276,10 +438,10 @@ if (subcommand === 'list') {
   const { skills, tools = [] } = require('../skills-index.json')
   const sorted = [...skills].sort((a, b) => a.bundle.localeCompare(b.bundle) || a.path.split('/').pop().localeCompare(b.path.split('/').pop()))
   if (jsonFlag) {
-    console.log(JSON.stringify({
+    await emitJson({
       skills: sorted.map(s => ({ name: s.path.split('/').pop(), path: s.path, bundle: s.bundle, global: s.global ?? false })),
       tools: tools.map(t => t.name),
-    }, null, 2))
+    })
     process.exit(0)
   }
   const nw = Math.max(...sorted.map(s => s.path.split('/').pop().length), 4)
@@ -310,10 +472,11 @@ function resolveHookDisplayVersion(inst, sourceVersion) {
 }
 
 // ── Shared skill scan ─────────────────────────────────────────────────────────
-function buildSkillRows(nameFilter = null) {
+function buildSkillRows(nameFilter = null, sourceItems = null) {
+  const allItems = sourceItems ?? getAllSkillItems()
   const items = nameFilter
-    ? getAllSkillItems().filter(s => s.skillName === nameFilter)
-    : getAllSkillItems()
+    ? allItems.filter(s => s.skillName === nameFilter)
+    : allItems
   return items.map(s => {
     const inst = checkInstalled(s.skillName, s.version ?? '—')
     return {
@@ -321,6 +484,7 @@ function buildSkillRows(nameFilter = null) {
       bundle:       s.bundle        ?? '—',
       version:      s.version       ?? '—',
       installScope: s.installScope  ?? null,
+      autoUpdate:   s.autoUpdate    ?? false,
       srcPath:      s.srcPath,
       userStatus:   scopeSummary(inst.user),
       projectStatus: scopeSummary(inst.project),
@@ -330,6 +494,26 @@ function buildSkillRows(nameFilter = null) {
   })
 }
 
+// Shared by `upgrade` and the post-`update` auto-upgrade step: for each
+// target, install whichever rows are outdated (status === 'update') on that
+// target's scope. Rows not carrying the given scope's detail are left alone.
+async function upgradeOutdatedSkills(rows, targetList, scopeKey) {
+  const summary = {}
+  for (const { name: targetName, dir } of targetList) {
+    const upgradeList = rows
+      .filter(r => r[scopeKey]?.[targetName]?.status === 'update')
+      .map(r => ({ skillName: r.name, srcPath: r.srcPath, version: r.version }))
+
+    if (!upgradeList.length) continue
+
+    console.log('')
+    const result = await installSkills(upgradeList, [{ name: targetName, dir }], true)
+    Object.assign(summary, result)
+    console.log('')
+  }
+  return summary
+}
+
 // ── Status / Outdated ─────────────────────────────────────────────────────────
 if (subcommand === 'status' || subcommand === 'outdated') {
   const outdatedOnly = subcommand === 'outdated'
@@ -380,12 +564,12 @@ if (subcommand === 'status' || subcommand === 'outdated') {
       return { name: h.name, description: h.description, user: inst.user, project: inst.project }
     })
     if (outdatedOnly) {
-      console.log(JSON.stringify({
+      await emitJson({
         skills: jsonSkills.filter(s => Object.values(s.user).some(v => v.status === 'update') || Object.values(s.project).some(v => v.status === 'update')),
         tools:  jsonTools.filter(t => t.status === 'update'),
-      }, null, 2))
+      })
     } else {
-      console.log(JSON.stringify({ skills: jsonSkills, tools: jsonTools, hooks: jsonHooks }, null, 2))
+      await emitJson({ skills: jsonSkills, tools: jsonTools, hooks: jsonHooks })
     }
     process.exit(0)
   }
@@ -513,17 +697,17 @@ if (subcommand === 'info') {
   if (jsonFlag) {
     if (skill) {
       const inst = checkInstalled(skill.skillName, skill.version ?? '—')
-      console.log(JSON.stringify({
+      await emitJson({
         name: skill.skillName, type: 'skill', version: skill.version ?? '—',
         user:    Object.fromEntries(targets.map(t => [t, inst.user[t]])),
         project: Object.fromEntries(targets.map(t => [t, inst.project[t]])),
-      }, null, 2))
+      })
     } else {
       const inst = checkToolInstalled(tool.toolName, tool.srcPath)
-      console.log(JSON.stringify({
+      await emitJson({
         name: tool.toolName, type: 'tool', version: tool.version ?? '—',
         installed: inst,
-      }, null, 2))
+      })
     }
     process.exit(0)
   }
@@ -590,7 +774,7 @@ if (subcommand === 'uninstall') {
     const { removed, failed } = await uninstallTool(nameToRemove, { yes: yesFlag })
     if (jsonFlag) {
       console.error = originalError
-      console.log(JSON.stringify({ removed: removed.length > 0, failed: failed.length > 0 }, null, 2))
+      await emitJson({ removed: removed.length > 0, failed: failed.length > 0 })
     } else if (removed.length > 0) {
       console.error(chalk.green.bold(`✔ ${nameToRemove} uninstalled`))
     }
@@ -617,7 +801,7 @@ if (subcommand === 'uninstall') {
   }
   if (jsonFlag) {
     console.error = originalError2
-    console.log(JSON.stringify({ removed: anyRemoved, failed: anyFailed }, null, 2))
+    await emitJson({ removed: anyRemoved, failed: anyFailed })
   } else if (anyRemoved) {
     console.error(chalk.green.bold(`✔ ${nameToRemove} uninstalled`))
   }
@@ -663,7 +847,7 @@ if (subcommand === 'hooks') {
           codex: inst.codex,
         }
       })
-      console.log(JSON.stringify({ hooks: out }, null, 2))
+      await emitJson({ hooks: out })
       process.exit(0)
     }
     function hookIcon(s) {
@@ -724,7 +908,7 @@ if (subcommand === 'hooks') {
     const { installed, skipped, failed } = await installHooksForTarget(toInstall, hookTargetArg, hookScopeArg, hookProjectArg, hookForce)
 
     if (hookJsonFlag) {
-      console.log(JSON.stringify({ installed, skipped, failed }, null, 2))
+      await emitJson({ installed, skipped, failed })
       process.exit(failed.length ? 1 : 0)
     } else {
       if (installed.length) console.error(chalk.green.bold(`✔ Hooks installed (${hookScopeArg}):`), installed.join(', '))
@@ -746,7 +930,7 @@ if (subcommand === 'hooks') {
     }
     const { removed } = await uninstallHook(nameToRemove, hookScopeArg, hookProjectArg)
     if (hookJsonFlag) {
-      console.log(JSON.stringify({ removed }, null, 2))
+      await emitJson({ removed })
     } else if (!removed) {
       console.log(chalk.dim(`  · ${nameToRemove} was not installed in ${hookScopeArg} scope`))
     }
@@ -781,26 +965,14 @@ if (subcommand === 'upgrade') {
   const targetList  = resolveTargets(upgradeTargetArg ? [upgradeTargetArg] : ['all'], upgradeScopeArg)
   const scopeKey    = upgradeScopeArg + 'Detail'   // 'userDetail' or 'projectDetail'
 
-  const summary = {}
-  for (const { name: targetName, dir } of targetList) {
-    const upgradeList = rows
-      .filter(r => r[scopeKey]?.[targetName]?.status === 'update')
-      .map(r => ({ skillName: r.name, srcPath: r.srcPath, version: r.version }))
-
-    if (!upgradeList.length) continue
-
-    console.log('')
-    const result = await installSkills(upgradeList, [{ name: targetName, dir }], true)
-    Object.assign(summary, result)
-    console.log('')
-  }
+  const summary = await upgradeOutdatedSkills(rows, targetList, scopeKey)
 
   const nothingUpgraded = Object.keys(summary).length === 0
   if (jsonFlag) {
     if (nothingUpgraded) {
-      console.log(JSON.stringify({ skills: {}, upToDate: true }, null, 2))
+      await emitJson({ skills: {}, upToDate: true })
     } else {
-      console.log(JSON.stringify({ skills: summary }, null, 2))
+      await emitJson({ skills: summary })
     }
   } else {
     if (nothingUpgraded) {
@@ -1512,7 +1684,7 @@ try {
     const out = {}
     if (skillSummary !== null) out.skills = skillSummary
     if (toolSummary  !== null) out.tools  = toolSummary
-    console.log(JSON.stringify(out, null, 2))
+    await emitJson(out)
   } else {
     printSummary(skillSummary, toolSummary)
   }

package/lib/bundles.js

@@ -101,21 +101,29 @@ export function buildAllChoices() {
   return choices
 }
 
-// 所有 skill 展开为 { kind:'skill', skillName, bundle, srcPath } 列表（对应 all 选项）
-export function getAllSkillItems() {
-  return skillDefs.map(skill => {
-    const srcPath = path.join(skillsRoot, skill.path)
+// 把一组原始 skill 定义（来自 skills-index.json 的 skills[]）展开为运行时条目。
+// 抽出来是因为 `hskill update` 在自更新落盘后，需要绕开本模块顶部那次一次性
+// require() 缓存的旧 skillDefs，直接用刚写到磁盘的新 skills-index.json 重新展开。
+export function toSkillItems(defs, root) {
+  return defs.map(skill => {
+    const srcPath = path.join(root, skill.path)
     return {
       kind: 'skill',
       skillName: skill.path.split('/').pop(),
       bundle: skill.bundle,
       installScope: skill.installScope ?? null,
+      autoUpdate: skill.autoUpdate ?? false,
       srcPath,
       version: readVersion(srcPath),
     }
   })
 }
 
+// 所有 skill 展开为 { kind:'skill', skillName, bundle, srcPath } 列表（对应 all 选项）
+export function getAllSkillItems() {
+  return toSkillItems(skillDefs, skillsRoot)
+}
+
 // 所有 tool 展开为 { kind:'tool', toolName, srcPath, version } 列表
 export function getAllToolItems() {
   return toolDefs.map(tool => {

package/lib/install-source.js

@@ -0,0 +1,46 @@
+import { execSync } from 'child_process'
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import path from 'path'
+
+let cachedGlobalRoot = null
+
+export function globalRoot() {
+  if (process.env.HSKILL_GLOBAL_ROOT) return process.env.HSKILL_GLOBAL_ROOT
+  // stdio 'pipe' keeps npm's own stderr off ours: callers that tolerate failure
+  // (readSource) would otherwise leak "npm: command not found" into clean output.
+  if (!cachedGlobalRoot) cachedGlobalRoot = execSync('npm root -g', { encoding: 'utf8', stdio: 'pipe' }).trim()
+  return cachedGlobalRoot
+}
+
+function sourceFilePath() {
+  return path.join(globalRoot(), 'harveyz-skill', '.hskill-source.json')
+}
+
+// null means "npm source" — the default. An unreadable trace file and an
+// unreachable npm both collapse into it: `version` must keep working where npm
+// is off PATH, and a source we cannot read is not a source we can update from.
+export function readSource() {
+  let file
+  try {
+    file = sourceFilePath()
+  } catch {
+    return null
+  }
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export function writeSource(info) {
+  writeFileSync(sourceFilePath(), JSON.stringify(info, null, 2) + '\n')
+}
+
+export function gitInfo(repo) {
+  const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: repo, encoding: 'utf8' }).trim()
+  const commit = execSync('git rev-parse --short HEAD', { cwd: repo, encoding: 'utf8' }).trim()
+  const dirty = execSync('git status --porcelain', { cwd: repo, encoding: 'utf8' }).trim().length > 0
+  return { branch, commit, dirty }
+}

package/lib/mcp-server.js

@@ -152,12 +152,12 @@ export function createServer() {
   })
 
   server.registerTool('hskill_update', {
-    description: 'Update hskill itself to the latest version via `npm install -g harveyz-skill@latest`. This replaces the globally installed hskill binary and is irreversible except by manually reinstalling a specific version.',
+    description: 'Update hskill itself from whichever source the current install came from: the npm registry (the default) or, if it was installed from a local repo, that same repo re-packed. Never switches between the two — use the CLI (`hskill update --npm` / `--local <path>`) to change source. This replaces the globally installed hskill binary and is irreversible except by manually reinstalling a specific version.',
     inputSchema: {},
   }, async () => {
     const { code, stdout, stderr } = await runCli(['update'])
     if (code === 0) {
-      return { content: [{ type: 'text', text: 'hskill updated to the latest version.' }] }
+      return { content: [{ type: 'text', text: stdout.trim() || 'hskill updated.' }] }
     }
     const message = stderr.trim() || stdout.trim() || `update failed with exit code ${code}`
     return { content: [{ type: 'text', text: message }], isError: true }

package/lib/version-check.js

@@ -2,8 +2,8 @@ const DEFAULT_REGISTRY = 'https://registry.npmjs.org'
 const REGISTRY_TIMEOUT_MS = 5000
 
 export function compareVersions(a, b) {
-  const pa = a.split('.').map(Number)
-  const pb = b.split('.').map(Number)
+  const pa = a.split('+')[0].split('.').map(Number)
+  const pb = b.split('+')[0].split('.').map(Number)
   for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
     const diff = (pa[i] || 0) - (pb[i] || 0)
     if (diff !== 0) return diff