opencode-skills-doctor 0.4.0 → 0.4.2

package/README.md

@@ -22,7 +22,7 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills
 | **Reports** | terminal, JSON, or a self-contained HTML report (`--html [file] --open`) |
 | **Cost** | CLI: 0 tokens. Plugin: ~191 tokens/step for the tool definition, plus a one-time warning per session |
 | **Requirements** | Node ≥ 20, zero runtime dependencies |
-| **Quality** | 49 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
+| **Quality** | 50 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
 
 ## Why
 
@@ -59,7 +59,7 @@ skills-doctor check
 What a run looks like:
 
 ```text
-skills-doctor 0.3.13
+skills-doctor 0.4.1
   sources: 5 (2 exist)  definitions: 29  unique IDs: 29  advertised: 29  description budget: ~3074 tokens
 
 [E] token-budget   Advertised skill descriptions cost about 3074 tokens per model step, over 2x the 1200 budget
@@ -157,6 +157,30 @@ Local execution is free, but any tool registered with the model is visible on ev
 
 So the plugin trades a small fixed overhead for the agent being able to audit by itself. In the example above the skill descriptions cost 3,074 tokens per step; dropping that to the 1,200 budget saves more than 10× the plugin overhead. If you want **zero** context cost, don't install the plugin — run `npx opencode-skills-doctor check` from the terminal or CI instead.
 
+## Self-update
+
+`skills-doctor` checks npm for a newer version of itself at most once per 24 hours (skipped in CI, non-TTY and `--json` runs):
+
+```powershell
+skills-doctor upgrade            # check now
+skills-doctor upgrade --open     # check and open the GitHub release page
+skills-doctor upgrade --apply    # npm install -g opencode-skills-doctor@latest
+```
+
+Opt out permanently in `.skills-doctor.json`:
+
+```json
+{ "checkUpdates": "off" }
+```
+
+| Value | Behavior |
+|---|---|
+| `"notify"` (default) | print a one-line notice when a newer version exists |
+| `"open"` | same, plus opens the release page in the browser |
+| `"off"` | never check |
+
+Per run: `--no-update-check`. Per environment: `SKILLS_DOCTOR_UPDATE_CHECK=0`. The plugin injects the same notice into the system prompt once per session when an update exists. Cached state lives in `~/.skills-doctor/self-update.json`.
+
 ## Configuration
 
 Optional `.skills-doctor.json` in the working directory (or pass `--config <file>`):
@@ -166,12 +190,13 @@ Optional `.skills-doctor.json` in the working directory (or pass `--config <file
   "budget": 1200,
   "staleDays": 180,
   "lang": "en",
+  "checkUpdates": "notify",
   "rules": { "long-description": "off", "hidden-skill": "info" },
   "ignore": ["legacy-skill"]
 }
 ```
 
-`rules` accepts `off`, `info`, `warn` or `error`; `ignore` drops findings that only involve those IDs. CLI flags override the file.
+`rules` accepts `off`, `info`, `warn` or `error`; `ignore` drops findings that only involve those IDs; `checkUpdates` is `notify` / `open` / `off`. CLI flags override the file.
 
 ## OpenCode plugin
 
@@ -186,8 +211,10 @@ The package also exports an OpenCode 2.x plugin:
 
 It registers:
 
-- the `skills_doctor` tool (namespace `skills`) — the agent can audit with `{ directory?, budget? }` and gets a markdown report;
-- the `/skills-doctor` command — asks the agent to run the audit and summarize fixes.
+- the `skills_doctor` tool (namespace `skills`) — the agent can audit with `{ directory?, budget?, html? }` and gets a markdown report;
+- the `/skills-doctor` command — asks the agent to run the audit and summarize fixes;
+- `/skills-report` — asks where to save an HTML report, then writes it;
+- `/skills-upgrade` — checks whether skills-doctor itself has a newer version.
 
 `@opencode/plugin` is an optional peer dependency; OpenCode provides it at runtime.
 
@@ -228,7 +255,7 @@ npx opencode-skills-doctor install
 The installer detects your OpenCode version and wires everything up:
 
 - **2.x** — adds `"plugins": ["opencode-skills-doctor"]` to `opencode.json(c)`;
-- **1.x** — installs the package into `~/.config/opencode`, writes the local plugin entry, adds a `/skills-doctor` command, sets `"type": "module"`;
+- **1.x** — installs the package into `~/.config/opencode`, writes the local plugin entry, generates `/skills-doctor`, `/skills-report` and `/skills-upgrade` markdown commands, sets `"type": "module"`;
 - backs up the config file as `<config>.bak-<timestamp>` before editing.
 
 Use `--dry-run` to preview, `--config-dir <dir>` for a custom config location, and `--no-npm` to skip the package install.
@@ -238,6 +265,7 @@ Once installed you get:
 - the `skills_doctor` tool (with an optional `html` argument to write a report to a path you choose);
 - the `/skills-doctor` command (1.x: generated markdown command; 2.x: plugin command);
 - the `/skills-report` command (2.x) that asks where to save the HTML report;
+- the `/skills-upgrade` command (2.x) that checks for a newer skills-doctor;
 - a one-time system-prompt warning when the skill description budget is exceeded.
 
 ### Uninstall
@@ -440,13 +468,13 @@ Executing code is free, but the tool definition is part of the model's context.
 
 ## Roadmap
 
-- v0.4: content-aware suggestions (which skills are never used), catalog signature verification
+- v0.5: CI governance (baseline that only reports new issues, official GitHub Action), content-aware suggestions (which skills are never used), catalog signature verification
 - Later: V1/Claude skill migration report
 
 ## Development and contributing
 
 ```powershell
-npm test          # 41 tests (node test/doctor.test.mjs)
+npm test          # 50 tests (node test/doctor.test.mjs)
 npm run bench     # lint timing for 100/500/1000 skills
 ```
 

package/docs/README.zh-CN.md

@@ -22,7 +22,7 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | **报告** | 终端、JSON，或自包含 HTML（`--html [file] --open`） |
 | **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
 | **要求** | Node ≥ 20，零运行时依赖 |
-| **质量** | 49 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
+| **质量** | 50 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
 ## 为什么需要它
 
@@ -59,7 +59,7 @@ skills-doctor check
 跑出来大概是这样：
 
 ```text
-skills-doctor 0.3.13
+skills-doctor 0.4.1
   来源: 5 个（存在 2 个）  定义: 29  唯一 ID: 29  会展示: 29  描述预算: ~3074 tokens
 
 [E] token-budget   模型每步要看到的 skill 描述约 3074 tokens，超过预算 1200 的 2 倍
@@ -157,6 +157,30 @@ skills-doctor update --into .\team-skills
 
 所以插件是用固定的少量开销，换「模型能自己体检」。上面的例子里 skill 描述每步 3074 tokens，压到 1200 预算能省下 10 倍于插件开销的 token。想要**零上下文成本**，就别装插件——用 `npx opencode-skills-doctor check` 在终端或 CI 里跑。
 
+## 自更新
+
+`skills-doctor` 最多每 24 小时查一次 npm 上自己有没有新版本（CI、非 TTY、`--json` 时自动跳过）：
+
+```powershell
+skills-doctor upgrade            # 立即检查
+skills-doctor upgrade --open     # 检查并打开 GitHub Release 页面
+skills-doctor upgrade --apply    # npm install -g opencode-skills-doctor@latest
+```
+
+在 `.skills-doctor.json` 里永久关闭：
+
+```json
+{ "checkUpdates": "off" }
+```
+
+| 取值 | 行为 |
+|---|---|
+| `"notify"`（默认） | 有新版本时打印一行提示 |
+| `"open"` | 提示 + 自动打开 Release 页面 |
+| `"off"` | 完全不检查 |
+
+单次关闭：`--no-update-check`；环境变量：`SKILLS_DOCTOR_UPDATE_CHECK=0`。插件在有新版本时会把提示注入系统提示（每个会话一次）。检查缓存位于 `~/.skills-doctor/self-update.json`。
+
 ## 配置
 
 在工作目录放一个可选的 `.skills-doctor.json`（或用 `--config <file>` 指定）：
@@ -166,12 +190,13 @@ skills-doctor update --into .\team-skills
   "budget": 1200,
   "staleDays": 180,
   "lang": "en",
+  "checkUpdates": "notify",
   "rules": { "long-description": "off", "hidden-skill": "info" },
   "ignore": ["legacy-skill"]
 }
 ```
 
-`rules` 接受 `off` / `info` / `warn` / `error`；`ignore` 会丢掉只涉及这些 ID 的 finding。命令行参数优先级高于配置文件。
+`rules` 接受 `off` / `info` / `warn` / `error`；`ignore` 会丢掉只涉及这些 ID 的 finding；`checkUpdates` 取 `notify` / `open` / `off`。命令行参数优先级高于配置文件。
 
 ## OpenCode 插件
 
@@ -186,8 +211,10 @@ skills-doctor update --into .\team-skills
 
 它会注册：
 
-- `skills_doctor` 工具（命名空间 `skills`）—— agent 传 `{ directory?, budget? }` 就能拿到 markdown 审计报告；
-- `/skills-doctor` 命令 —— 让 agent 跑一次审计并总结修复建议。
+- `skills_doctor` 工具（命名空间 `skills`）—— agent 传 `{ directory?, budget?, html? }` 就能拿到 markdown 审计报告；
+- `/skills-doctor` 命令 —— 让 agent 跑一次审计并总结修复建议；
+- `/skills-report` —— 先问你要把 HTML 报告存到哪里，再写文件；
+- `/skills-upgrade` —— 检查 skills-doctor 自身有没有新版本。
 
 `@opencode/plugin` 是可选 peer 依赖，运行时由 OpenCode 提供。
 
@@ -228,7 +255,7 @@ npx opencode-skills-doctor install
 安装器会自动识别 OpenCode 版本并接好：
 
 - **2.x** —— 在 `opencode.json(c)` 里加 `"plugins": ["opencode-skills-doctor"]`；
-- **1.x** —— 把包装进 `~/.config/opencode`、写本地插件入口、生成 `/skills-doctor` 命令、补 `"type": "module"`；
+- **1.x** —— 把包装进 `~/.config/opencode`、写本地插件入口、生成 `/skills-doctor`、`/skills-report`、`/skills-upgrade` 三个 markdown 命令、补 `"type": "module"`；
 - 改配置前会备份为 `<config>.bak-<timestamp>`。
 
 支持 `--dry-run` 预览、`--config-dir <dir>` 指定配置目录、`--no-npm` 跳过装包。
@@ -238,6 +265,7 @@ npx opencode-skills-doctor install
 - `skills_doctor` 工具（可选 `html` 参数，把报告写到指定路径）；
 - `/skills-doctor` 命令（1.x 是生成的 markdown 命令，2.x 是插件命令）；
 - `/skills-report` 命令（2.x）—— 会先问你要把 HTML 报告存到哪里；
+- `/skills-upgrade` 命令（2.x）—— 检查 skills-doctor 自身是否有新版本；
 - 当 skill 描述预算超标时，系统提示里会注入一次提醒（每个会话最多一次）。
 
 ### 卸载
@@ -440,13 +468,13 @@ token 是启发式估算，1200 是建议预算。可以用 `--budget` 或 `.ski
 
 ## Roadmap
 
-- v0.4：内容层面的建议（哪些 skill 从未被使用）、catalog 签名校验
+- v0.5：CI 治理（baseline 只报新增问题、官方 GitHub Action）、内容层建议（哪些 skill 从未被使用）、catalog 签名校验
 - 后续：V1/Claude skill 兼容迁移报告
 
 ## 开发与贡献
 
 ```powershell
-npm test          # 41 个测试（node test/doctor.test.mjs）
+npm test          # 50 个测试（node test/doctor.test.mjs）
 npm run bench     # 100/500/1000 个 skill 的 lint 耗时
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Audit, fix and update agent skills: token cost, broken references, shadowed duplicates, HTML reports, catalog sync. CLI, OpenCode plugin, MCP server; works with OpenCode, Claude Code, Codex, Grok CLI and Cursor skill layouts.",
   "type": "module",
   "exports": {

package/src/cli.mjs

@@ -10,6 +10,14 @@ import { loadConfig } from "./config.mjs"
 import { startMcpServer } from "./mcp.mjs"
 import { installOpenCode, uninstallOpenCode } from "./install.mjs"
 import { writeHtmlReport, openReport } from "./html.mjs"
+import {
+  checkForUpdate,
+  resolveMode,
+  upgradeCommand,
+  applyUpgrade,
+  openReleasePage,
+  RELEASES_URL,
+} from "./self-update.mjs"
 import { padDisplay } from "./parse.mjs"
 import { detectLang, normalizeLang, translator } from "./i18n.mjs"
 
@@ -66,12 +74,14 @@ function parseArgs(argv) {
     noNpm: false,
     html: null,
     open: false,
+    apply: false,
+    updateCheck: true,
     help: false,
     version: false,
   }
 
   const args = [...argv]
-  const commands = new Set(["check", "scan", "update", "fix", "install", "uninstall", "mcp", "help"])
+  const commands = new Set(["check", "scan", "update", "fix", "install", "uninstall", "upgrade", "mcp", "help"])
   if (args[0] && commands.has(args[0])) {
     options.command = args.shift()
   }
@@ -145,6 +155,12 @@ function parseArgs(argv) {
       case "--open":
         options.open = true
         break
+      case "--apply":
+        options.apply = true
+        break
+      case "--no-update-check":
+        options.updateCheck = false
+        break
       case "-h":
       case "--help":
         options.help = true
@@ -446,6 +462,27 @@ function runFix(audit, options, t) {
   return errors.length ? 1 : 0
 }
 
+async function maybeNotifyUpdate({ options, config, t }) {
+  if (!options.updateCheck) return
+  if (options.json || !process.stdout.isTTY || process.env.CI) return
+  const mode = resolveMode(config)
+  if (mode === "off") return
+  const update = await checkForUpdate({ current: pkg.version, mode })
+  if (!update) return
+  console.log("")
+  console.log(
+    dim(
+      t("update.toolAvailable", {
+        latest: update.latest,
+        current: pkg.version,
+        cmd: "npx opencode-skills-doctor@latest check",
+        url: update.url,
+      }),
+    ),
+  )
+  if (mode === "open") openReleasePage({ url: update.url })
+}
+
 export async function main(argv) {
   const options = parseArgs(argv)
 
@@ -517,6 +554,44 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "upgrade") {
+    const update = await checkForUpdate({ current: pkg.version, force: true })
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            current: pkg.version,
+            latest: update?.latest ?? pkg.version,
+            updateAvailable: Boolean(update),
+            url: update?.url ?? RELEASES_URL,
+            command: upgradeCommand(),
+          },
+          null,
+          2,
+        ),
+      )
+    } else {
+      console.log(bold(t("upgrade.title")))
+      console.log(dim(t("upgrade.current", { version: pkg.version })))
+      if (update) {
+        console.log(t("upgrade.available", { latest: update.latest, current: pkg.version }))
+        console.log(dim(t("upgrade.command", { cmd: upgradeCommand() })))
+        console.log(dim(t("upgrade.open", { url: update.url })))
+        if (options.open) openReleasePage({ url: update.url })
+        if (options.apply) {
+          if (applyUpgrade()) console.log(green(t("upgrade.done")))
+          else {
+            console.log(red(t("upgrade.failed", { cmd: upgradeCommand() })))
+            process.exitCode = 1
+          }
+        }
+      } else {
+        console.log(green(t("upgrade.upToDate")))
+      }
+    }
+    return
+  }
+
   if (options.command === "check") {
     const audit = auditSkills({
       cwd,
@@ -545,6 +620,7 @@ export async function main(argv) {
     } else {
       printCheck(audit, result, options, t)
       if (htmlPath) console.log(dim(t("check.htmlSaved", { path: htmlPath })))
+      await maybeNotifyUpdate({ options, config: loaded.config, t })
     }
     process.exitCode = result.exitCode
     return
@@ -571,6 +647,7 @@ export async function main(argv) {
       return
     }
     printScan(discovered, options, managedInfo.managed, t)
+    await maybeNotifyUpdate({ options, config: loaded.config, t })
     return
   }
 

package/src/config.mjs

@@ -15,6 +15,10 @@ function normalize(raw) {
     }
   }
   if (Array.isArray(raw?.ignore)) config.ignore = raw.ignore.filter((id) => typeof id === "string")
+  const checkUpdates = raw?.checkUpdates ?? raw?.updateCheck
+  if (checkUpdates === false || checkUpdates === "off") config.checkUpdates = "off"
+  else if (checkUpdates === true) config.checkUpdates = "notify"
+  else if (checkUpdates === "notify" || checkUpdates === "open") config.checkUpdates = checkUpdates
   return config
 }
 

package/src/i18n.mjs

@@ -12,6 +12,7 @@ Usage:
   skills-doctor update [options]   compare and download skills from HTTP catalogs
   skills-doctor install [options]  wire the plugin into OpenCode (1.x / 2.x)
   skills-doctor uninstall [options] remove it again (config entry, generated files, package)
+  skills-doctor upgrade [options]  check for a newer skills-doctor itself (--apply installs it)
   skills-doctor mcp                run as an MCP server (Claude Code, Codex, any MCP client)
 
 Options:
@@ -33,6 +34,8 @@ Options:
   --open               check: open the HTML report after writing it
   --config-dir <dir>   install/uninstall: OpenCode config directory (default: ~/.config/opencode)
   --no-npm             install/uninstall: do not run npm (1.x)
+  --apply              upgrade: run npm install -g opencode-skills-doctor@latest
+  --no-update-check    skip the automatic update check for this run
   -h, --help           show this help
   -v, --version        print version
 
@@ -90,6 +93,16 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "install.next": "Restart OpenCode to activate.",
     "uninstall.title": "Remove OpenCode integration",
     "uninstall.next": "Restart OpenCode to finish removal.",
+    "update.toolAvailable":
+      "  ! skills-doctor {latest} is available (you have {current}); update with: {cmd}  ·  {url}",
+    "upgrade.title": "skills-doctor upgrade",
+    "upgrade.current": "  current: {version}",
+    "upgrade.available": "New version available: {latest} (current {current})",
+    "upgrade.command": "  upgrade with: {cmd}",
+    "upgrade.open": "  release notes: {url}",
+    "upgrade.upToDate": "Already up to date.",
+    "upgrade.done": "Upgraded to the latest version.",
+    "upgrade.failed": "Upgrade failed; run it manually: {cmd}",
     "update.lockTooNew": "  ! lock is newer than this tool; parsed in compatibility mode (unknown fields ignored)",
     "update.detector": "  check now sees these skills ({dir} is where opencode reads)",
     "update.noCatalogs": "No HTTP catalog configured. Add https://... to the skills array in opencode.json(c).",
@@ -184,6 +197,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   skills-doctor update [选项]   对比并拉取 HTTP catalog 里的 skill
   skills-doctor install [选项]  把插件接入 OpenCode（1.x / 2.x）
   skills-doctor uninstall [选项] 撤销安装（配置条目、生成的文件、npm 包）
+  skills-doctor upgrade [选项]  检查 skills-doctor 自身是否有新版本（--apply 直接装）
   skills-doctor mcp            以 MCP server 方式运行（Claude Code、Codex 等任何 MCP 客户端）
 
 选项:
@@ -205,6 +219,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --open              check: 写完报告后用浏览器打开
   --config-dir <dir>  install/uninstall: OpenCode 配置目录（默认 ~/.config/opencode）
   --no-npm            install/uninstall: 不执行 npm（1.x）
+  --apply             upgrade: 执行 npm install -g opencode-skills-doctor@latest
+  --no-update-check   本次运行跳过自动更新检查
   -h, --help          帮助
   -v, --version       版本
 
@@ -262,6 +278,15 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "install.next": "重启 OpenCode 生效。",
     "uninstall.title": "撤销 OpenCode 集成",
     "uninstall.next": "重启 OpenCode 完成卸载。",
+    "update.toolAvailable": "  ! skills-doctor 有新版本 {latest}（当前 {current}）；更新：{cmd}  ·  {url}",
+    "upgrade.title": "skills-doctor 自更新",
+    "upgrade.current": "  当前版本: {version}",
+    "upgrade.available": "发现新版本: {latest}（当前 {current}）",
+    "upgrade.command": "  更新命令: {cmd}",
+    "upgrade.open": "  更新说明: {url}",
+    "upgrade.upToDate": "已是最新版本。",
+    "upgrade.done": "已升级到最新版本。",
+    "upgrade.failed": "升级失败，请手动执行: {cmd}",
     "update.lockTooNew": "  ! lock 版本比本工具新，已按兼容模式解析（未知字段忽略）",
     "update.detector": "  check 现在可以直接检测到这些 skill（{dir} 是 opencode 会读取的目录）",
     "update.noCatalogs": "没有配置 HTTP catalog。在 opencode.json(c) 的 skills 数组里写 https://... 即可。",

package/src/install.mjs

@@ -21,9 +21,16 @@ description: Write an HTML skills report to a path you choose
 Ask the user where to save the HTML report (default ./skills-report.html), then call the skills_doctor tool with the html argument set to that path and tell them where it was written. $ARGUMENTS
 `
 
+const V1_UPGRADE_COMMAND = `---
+description: Check whether skills-doctor itself has a newer version
+---
+Run \`npx -y opencode-skills-doctor upgrade\` in the terminal (add --apply only after the user confirms), then report whether a newer version exists. $ARGUMENTS
+`
+
 const V1_COMMANDS = [
   { file: "skills-doctor.md", body: V1_COMMAND },
   { file: "skills-report.md", body: V1_REPORT_COMMAND },
+  { file: "skills-upgrade.md", body: V1_UPGRADE_COMMAND },
 ]
 
 export function defaultConfigDir() {

package/src/plugin-v1.mjs

@@ -2,6 +2,24 @@ import { tool } from "@opencode-ai/plugin"
 import { auditSkills, formatMarkdown } from "./audit.mjs"
 import { writeHtmlReport } from "./html.mjs"
 import { budgetWarning } from "./warning.mjs"
+import { loadConfig } from "./config.mjs"
+import { checkForUpdate, resolveMode, toolVersion } from "./self-update.mjs"
+
+const VERSION = toolVersion()
+const notifiedSessions = new Set()
+
+async function updateNote({ directory, sessionID }) {
+  if (!sessionID || notifiedSessions.has(sessionID)) return null
+  notifiedSessions.add(sessionID)
+  try {
+    const { config } = loadConfig(directory)
+    const update = await checkForUpdate({ current: VERSION, mode: resolveMode(config) })
+    if (!update) return null
+    return `skills-doctor ${update.latest} is available (current ${VERSION}). Update: npx -y opencode-skills-doctor@latest upgrade --apply`
+  } catch {
+    return null
+  }
+}
 
 const z = tool.schema
 
@@ -36,6 +54,8 @@ export const SkillsDoctorPlugin = async ({ directory }) => ({
   "experimental.chat.system.transform": async (input, output) => {
     const warning = budgetWarning({ cwd: directory, sessionID: input?.sessionID })
     if (warning) output.system.push(warning)
+    const note = await updateNote({ directory, sessionID: input?.sessionID })
+    if (note) output.system.push(note)
   },
 })
 

package/src/plugin.mjs

@@ -2,6 +2,24 @@ import { Plugin } from "@opencode/plugin"
 import { auditSkills, formatMarkdown } from "./audit.mjs"
 import { writeHtmlReport } from "./html.mjs"
 import { budgetWarning } from "./warning.mjs"
+import { loadConfig } from "./config.mjs"
+import { checkForUpdate, resolveMode, toolVersion } from "./self-update.mjs"
+
+const VERSION = toolVersion()
+const notifiedSessions = new Set()
+
+async function updateNote({ directory, sessionID }) {
+  if (!sessionID || notifiedSessions.has(sessionID)) return null
+  notifiedSessions.add(sessionID)
+  try {
+    const { config } = loadConfig(directory)
+    const update = await checkForUpdate({ current: VERSION, mode: resolveMode(config) })
+    if (!update) return null
+    return `skills-doctor ${update.latest} is available (current ${VERSION}). Update: npx -y opencode-skills-doctor@latest upgrade --apply`
+  } catch {
+    return null
+  }
+}
 
 /**
  * OpenCode 插件入口：把 skills-doctor 暴露成 skills_doctor 工具和 /skills-doctor 命令。
@@ -70,12 +88,26 @@ export default Plugin.define({
           })
         },
       })
+      editor.add({
+        name: "skills-upgrade",
+        description: "Check whether skills-doctor itself has a newer version",
+        execute: async ({ sessionID, prompt, delivery }) => {
+          await ctx.session.prompt({
+            ...prompt,
+            sessionID,
+            text: "Run `npx -y opencode-skills-doctor upgrade` in the terminal (add --apply only after I confirm), then report whether a newer version exists.",
+            delivery,
+          })
+        },
+      })
     })
 
     // 每个会话最多注入一次预算预警，避免刷屏
-    await ctx.session.hook("context", (event) => {
+    await ctx.session.hook("context", async (event) => {
       const warning = budgetWarning({ cwd: ctx.location.directory, sessionID: event.sessionID })
       if (warning) event.system.push({ type: "text", text: warning })
+      const note = await updateNote({ directory: ctx.location.directory, sessionID: event.sessionID })
+      if (note) event.system.push({ type: "text", text: note })
     })
   },
 })

package/src/self-update.mjs

@@ -0,0 +1,142 @@
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+import { spawnSync, spawn } from "node:child_process"
+
+export const REGISTRY_URL =
+  process.env.SKILLS_DOCTOR_REGISTRY_URL || "https://registry.npmjs.org/opencode-skills-doctor/latest"
+export const RELEASES_URL = "https://github.com/wangyuchen5110/opencodeplugginprogram/releases/latest"
+
+export const CACHE_DIR = path.join(os.homedir(), ".skills-doctor")
+export const CACHE_FILE = path.join(CACHE_DIR, "self-update.json")
+const DAY_MS = 24 * 60 * 60 * 1000
+
+let cachedVersion = null
+/** 当前安装版本（读取包内 package.json，插件/MCP 里也能用）。 */
+export function toolVersion() {
+  if (cachedVersion) return cachedVersion
+  try {
+    const file = new URL("../package.json", import.meta.url)
+    cachedVersion = JSON.parse(fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "")).version ?? "0.0.0"
+  } catch {
+    cachedVersion = "0.0.0"
+  }
+  return cachedVersion
+}
+
+/** 语义化版本比较：只看 major.minor.patch，预发布版视为更低。 */
+export function compareVersions(a, b) {
+  const parse = (value) => {
+    const [core, pre = ""] = String(value ?? "").trim().replace(/^v/i, "").split("-")
+    const numbers = core.split(".").map((part) => Number.parseInt(part, 10) || 0)
+    return { numbers: [numbers[0] ?? 0, numbers[1] ?? 0, numbers[2] ?? 0], pre }
+  }
+  const left = parse(a)
+  const right = parse(b)
+  for (let i = 0; i < 3; i++) {
+    if (left.numbers[i] !== right.numbers[i]) return left.numbers[i] > right.numbers[i] ? 1 : -1
+  }
+  if (left.pre === right.pre) return 0
+  if (!left.pre) return 1
+  if (!right.pre) return -1
+  return left.pre > right.pre ? 1 : -1
+}
+
+/** off | notify | open；环境变量 SKILLS_DOCTOR_UPDATE_CHECK 可以强制关闭/开启。 */
+export function resolveMode(config = {}, env = process.env) {
+  const envValue = String(env.SKILLS_DOCTOR_UPDATE_CHECK ?? "").trim().toLowerCase()
+  if (["0", "false", "off", "no"].includes(envValue)) return "off"
+  if (["1", "true", "on", "yes"].includes(envValue)) return "notify"
+
+  const value = config.checkUpdates ?? config.updateCheck
+  if (value === false) return "off"
+  if (value === true) return "notify"
+  if (value === "off" || value === "notify" || value === "open") return value
+  return "notify"
+}
+
+export async function fetchLatest({ fetchImpl = globalThis.fetch, url = REGISTRY_URL, timeoutMs = 4000 } = {}) {
+  if (typeof fetchImpl !== "function") throw new Error("fetch is not available in this Node runtime")
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetchImpl(url, { signal: controller.signal, headers: { accept: "application/json" } })
+    if (!response.ok) throw new Error(`HTTP ${response.status}`)
+    const data = await response.json()
+    const version = String(data?.version ?? "").trim()
+    if (!version) throw new Error("missing version")
+    return { version, url: RELEASES_URL }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function readCache(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8").replace(/^\uFEFF/, ""))
+  } catch {
+    return null
+  }
+}
+
+function writeCache(file, value) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n", "utf8")
+  } catch {}
+}
+
+/**
+ * 检查工具自身是否有新版本。
+ * 返回 null（没有/关闭/失败）或 { latest, url, current, checkedAt, cached }。
+ */
+export async function checkForUpdate({
+  current,
+  mode = "notify",
+  ttlMs = DAY_MS,
+  now = Date.now(),
+  fetchImpl,
+  cacheFile = CACHE_FILE,
+  force = false,
+} = {}) {
+  if (mode === "off" || !current) return null
+  const cache = readCache(cacheFile)
+
+  if (!force && cache && cache.current === current && Number.isFinite(cache.checkedAt) && now - cache.checkedAt < ttlMs) {
+    if (cache.latest && compareVersions(cache.latest, current) > 0) return { ...cache, cached: true }
+    return null
+  }
+
+  try {
+    const latest = await fetchLatest({ fetchImpl })
+    writeCache(cacheFile, { current, latest: latest.version, url: latest.url, checkedAt: now })
+    if (compareVersions(latest.version, current) > 0) {
+      return { latest: latest.version, url: latest.url, current, checkedAt: now, cached: false }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+export function upgradeCommand() {
+  return "npm install -g opencode-skills-doctor@latest"
+}
+
+/** 真正执行全局升级；调用方负责确认（CLI 的 --apply）。 */
+export function applyUpgrade({ spawnImpl = spawnSync, npm = process.platform === "win32" ? "npm.cmd" : "npm" } = {}) {
+  const result = spawnImpl(npm, ["install", "-g", "opencode-skills-doctor@latest", "--no-audit", "--no-fund"], {
+    stdio: "inherit",
+    env: process.env,
+    timeout: 300000,
+  })
+  return result.status === 0
+}
+
+export function openReleasePage({ url = RELEASES_URL, spawnImpl = spawn } = {}) {
+  try {
+    if (process.platform === "win32") spawnImpl("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref()
+    else if (process.platform === "darwin") spawnImpl("open", [url], { detached: true, stdio: "ignore" }).unref()
+    else spawnImpl("xdg-open", [url], { detached: true, stdio: "ignore" }).unref()
+  } catch {}
+}