opencode-skills-doctor 0.3.15 → 0.4.1

package/src/html.mjs

@@ -0,0 +1,167 @@
+import fs from "node:fs"
+import path from "node:path"
+import { spawn } from "node:child_process"
+
+function esc(value) {
+  return String(value ?? "").replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char])
+}
+
+const SEVERITY_LABEL = { error: "error", warn: "warn", info: "info" }
+
+/** 生成自包含 HTML 报告（无外部资源，可直接分享/作 CI artifact）。 */
+export function renderHtml(audit, { title = "skills-doctor report", now = new Date() } = {}) {
+  const summary = audit.summary
+  const counts = audit.counts
+  const budget = audit.budget
+  const ratio = budget > 0 ? Math.min(1.5, summary.advertisedTokens / (budget * 2)) : 0
+  const barWidth = Math.min(100, Math.round(ratio * 100))
+  const barClass = summary.advertisedTokens > budget * 2 ? "over" : summary.advertisedTokens > budget ? "warn" : "ok"
+
+  const findings = audit.findings
+    .map(
+      (finding) => `<tr class="finding ${finding.severity}" data-severity="${finding.severity}">
+  <td><span class="badge ${finding.severity}">${SEVERITY_LABEL[finding.severity] ?? finding.severity}</span></td>
+  <td class="rule">${esc(finding.rule)}</td>
+  <td>${esc(finding.message)}</td>
+</tr>`,
+    )
+    .join("\n")
+
+  const skills = audit.skills
+    .map(
+      (skill) => `<tr class="skill">
+  <td class="mono">${esc(skill.id)}</td>
+  <td>${esc(skill.source.scope)}</td>
+  <td>${skill.advertised ? "yes" : "no"}</td>
+  <td class="num">${skill.descriptionTokens}</td>
+  <td class="num">${skill.bodyTokens}</td>
+  <td class="desc">${esc(String(skill.description ?? "").slice(0, 80))}</td>
+  <td class="mono path">${esc(skill.file)}</td>
+</tr>`,
+    )
+    .join("\n")
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>
+  :root { color-scheme: light dark; --fg:#1f2328; --muted:#656d76; --bg:#fff; --card:#f6f8fa; --border:#d0d7de; --red:#cf222e; --yellow:#9a6700; --green:#1a7f37; --blue:#0969da; }
+  @media (prefers-color-scheme: dark) { :root { --fg:#e6edf3; --muted:#8d96a0; --bg:#0d1117; --card:#161b22; --border:#30363d; --red:#ff7b72; --yellow:#d29922; --green:#3fb950; --blue:#58a6ff; } }
+  * { box-sizing: border-box; }
+  body { margin:0; padding:32px; font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; color:var(--fg); background:var(--bg); }
+  h1 { margin:0 0 4px; font-size:24px; }
+  h2 { margin:32px 0 12px; font-size:18px; }
+  .sub { color:var(--muted); font-size:12px; }
+  .cards { display:grid; grid-template-columns:repeat(auto-fit,minmax(150px,1fr)); gap:12px; margin:20px 0; }
+  .card { background:var(--card); border:1px solid var(--border); border-radius:10px; padding:12px 14px; }
+  .card .k { color:var(--muted); font-size:12px; }
+  .card .v { font-size:22px; font-weight:600; margin-top:2px; }
+  .card.error .v { color:var(--red); } .card.warn .v { color:var(--yellow); } .card.info .v { color:var(--blue); }
+  .bar { height:10px; border-radius:6px; background:var(--card); border:1px solid var(--border); overflow:hidden; margin:8px 0 4px; }
+  .bar > span { display:block; height:100%; width:${barWidth}%; }
+  .bar > span.ok { background:var(--green); } .bar > span.warn { background:var(--yellow); } .bar > span.over { background:var(--red); }
+  table { width:100%; border-collapse:collapse; background:var(--bg); border:1px solid var(--border); border-radius:10px; overflow:hidden; }
+  th, td { text-align:left; padding:8px 10px; border-bottom:1px solid var(--border); vertical-align:top; }
+  th { background:var(--card); font-size:12px; color:var(--muted); text-transform:uppercase; letter-spacing:.03em; }
+  tr:last-child td { border-bottom:none; }
+  .badge { display:inline-block; padding:1px 8px; border-radius:999px; font-size:11px; font-weight:600; border:1px solid currentColor; }
+  .badge.error { color:var(--red); } .badge.warn { color:var(--yellow); } .badge.info { color:var(--blue); }
+  .rule { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; white-space:nowrap; }
+  .mono { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; }
+  .path { color:var(--muted); word-break:break-all; }
+  .num { text-align:right; font-variant-numeric:tabular-nums; }
+  .toolbar { display:flex; gap:8px; flex-wrap:wrap; margin:12px 0; }
+  .toolbar button, .toolbar input { font:inherit; padding:6px 10px; border-radius:8px; border:1px solid var(--border); background:var(--card); color:var(--fg); }
+  .toolbar button.active { border-color:var(--blue); color:var(--blue); }
+  .empty { color:var(--muted); padding:16px; }
+  footer { margin-top:40px; color:var(--muted); font-size:12px; }
+</style>
+</head>
+<body>
+  <h1>${esc(title)}</h1>
+  <div class="sub">generated ${esc(now.toISOString())} · ${esc(audit.cwd)}</div>
+
+  <div class="cards">
+    <div class="card"><div class="k">definitions</div><div class="v">${summary.total}</div></div>
+    <div class="card"><div class="k">unique IDs</div><div class="v">${summary.unique}</div></div>
+    <div class="card"><div class="k">advertised</div><div class="v">${summary.advertised}</div></div>
+    <div class="card"><div class="k">description tokens / step</div><div class="v">${summary.advertisedTokens}</div></div>
+    <div class="card error"><div class="k">errors</div><div class="v">${counts.errors}</div></div>
+    <div class="card warn"><div class="k">warnings</div><div class="v">${counts.warnings}</div></div>
+    <div class="card info"><div class="k">info</div><div class="v">${counts.infos}</div></div>
+  </div>
+
+  <h2>Context budget</h2>
+  <div class="bar"><span class="${barClass}"></span></div>
+  <div class="sub">${summary.advertisedTokens} tokens vs budget ${budget}${summary.advertisedTokens > budget * 2 ? " (over 2x)" : summary.advertisedTokens > budget ? " (over)" : " (ok)"}</div>
+
+  <h2>Findings (${audit.findings.length})</h2>
+  <div class="toolbar">
+    <button data-filter="all" class="active">all</button>
+    <button data-filter="error">error</button>
+    <button data-filter="warn">warn</button>
+    <button data-filter="info">info</button>
+    <input id="q" placeholder="filter text…" />
+  </div>
+  <table id="findings">
+    <thead><tr><th>severity</th><th>rule</th><th>message</th></tr></thead>
+    <tbody>
+${findings || '<tr><td colspan="3" class="empty">No problems found.</td></tr>'}
+    </tbody>
+  </table>
+
+  <h2>Skills (${audit.skills.length})</h2>
+  <table>
+    <thead><tr><th>ID</th><th>scope</th><th>advertised</th><th>desc tokens</th><th>body tokens</th><th>description</th><th>file</th></tr></thead>
+    <tbody>
+${skills}
+    </tbody>
+  </table>
+
+  <footer>skills-doctor · ${esc(audit.version ?? "")} · updates: re-run <code>skills-doctor check --html</code></footer>
+
+<script>
+  const buttons = [...document.querySelectorAll("[data-filter]")]
+  const q = document.getElementById("q")
+  let active = "all"
+  function apply() {
+    const text = (q.value || "").toLowerCase()
+    for (const row of document.querySelectorAll("tr.finding")) {
+      const okSeverity = active === "all" || row.dataset.severity === active
+      const okText = !text || row.textContent.toLowerCase().includes(text)
+      row.style.display = okSeverity && okText ? "" : "none"
+    }
+  }
+  for (const button of buttons) {
+    button.addEventListener("click", () => {
+      active = button.dataset.filter
+      for (const other of buttons) other.classList.toggle("active", other === button)
+      apply()
+    })
+  }
+  q.addEventListener("input", apply)
+</script>
+</body>
+</html>
+`
+}
+
+export function writeHtmlReport(audit, file, options = {}) {
+  const target = path.resolve(file)
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, renderHtml(audit, options), "utf8")
+  return target
+}
+
+/** 用系统默认程序打开报告；失败时静默（调用方已经知道路径）。 */
+export function openReport(file) {
+  const target = path.resolve(file)
+  try {
+    if (process.platform === "win32") spawn("cmd", ["/c", "start", "", target], { detached: true, stdio: "ignore" }).unref()
+    else if (process.platform === "darwin") spawn("open", [target], { detached: true, stdio: "ignore" }).unref()
+    else spawn("xdg-open", [target], { detached: true, stdio: "ignore" }).unref()
+  } catch {}
+}

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:
@@ -29,8 +30,12 @@ Options:
   --into <dir>         update: output directory (default: .opencode/skills)
   --check-only         update: only report available updates
   --prune              update: delete skills that disappeared from the catalog
+  --html [file]        check: write a self-contained HTML report (default: skills-report.html)
+  --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
 
@@ -47,6 +52,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "check.configError": "  ! cannot parse config: {path} ({error})",
     "check.missingPath": "  ! path in config does not exist: {path}",
     "check.none": "No problems found.",
+    "check.htmlSaved": "  HTML report: {path}",
     "check.summary": "{errors} error, {warnings} warn, {infos} info",
     "check.strict": " (--strict: warnings also fail)",
     "check.hints": "Hints:",
@@ -87,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).",
@@ -121,6 +137,10 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "hint.invalid-id": "Use lowercase kebab-case and keep it aligned with the directory name.",
     "hint.hidden-skill": "Confirm the skill is intentionally hidden; hidden skills are not advertised.",
     "hint.stale-skill": "Confirm the content is still current, or delete it.",
+    "hint.invalid-frontmatter": "Fix the YAML frontmatter: closing ---, string name/description, object metadata.",
+    "hint.empty-body": "Add real instructions to the body, or delete the skill.",
+    "hint.broken-reference": "Fix the path or remove the reference; missing files silently break the skill.",
+    "hint.reference-outside-skill": "Keep referenced files inside the skill directory so the skill stays portable.",
 
     "lint.shadowed":
       'ID "{id}" is defined {count} times; the effective definition is {winner}; the other {losers} are shadowed (dead weight, easy to edit the wrong file)',
@@ -140,6 +160,12 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "lint.tokenBudgetError":
       "Advertised skill descriptions cost about {tokens} tokens per model step, over 2x the {budget} budget",
     "lint.tooManySkills": "{count} skills are advertised to the model (recommended ≤ 60)",
+    "lint.invalidFrontmatter": '"{id}" has malformed frontmatter: {detail}',
+    "lint.frontmatterUnclosed": "missing closing ---",
+    "lint.frontmatterTypes": "name/description/metadata have wrong types",
+    "lint.emptyBody": '"{id}" body is nearly empty ({chars} chars)',
+    "lint.brokenReference": '"{id}" references missing files: {refs}',
+    "lint.referenceOutside": '"{id}" references files outside its skill directory: {refs}',
 
     "managed.lockUnsupported":
       "Lock version {version} is newer than the supported {supported}; parsing in compatibility mode (unknown fields ignored)",
@@ -171,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 客户端）
 
 选项:
@@ -188,8 +215,12 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --into <dir>        update 的落盘目录（默认 .opencode/skills）
   --check-only        update 只报告可用更新，不下载
   --prune             update: 删除 catalog 中已移除的 skill
+  --html [file]       check: 生成自包含 HTML 报告（默认 skills-report.html）
+  --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       版本
 
@@ -206,6 +237,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "check.configError": "  ! 配置文件无法解析: {path}（{error}）",
     "check.missingPath": "  ! 配置里引用的路径不存在: {path}",
     "check.none": "没有发现问题。",
+    "check.htmlSaved": "  HTML 报告: {path}",
     "check.summary": "{errors} error, {warnings} warn, {infos} info",
     "check.strict": "（--strict：warning 也会非 0 退出）",
     "check.hints": "建议:",
@@ -246,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://... 即可。",
@@ -278,6 +319,10 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "hint.invalid-id": "改成小写 kebab-case，并与目录名对齐。",
     "hint.hidden-skill": "确认是刻意隐藏；隐藏的 skill 不会出现在模型列表里。",
     "hint.stale-skill": "确认内容没过期，或删掉。",
+    "hint.invalid-frontmatter": "修好 frontmatter：闭合的 ---、字符串形式的 name/description、对象形式的 metadata。",
+    "hint.empty-body": "给正文补上真正的说明，否则删掉这个 skill。",
+    "hint.broken-reference": "修正路径或删掉引用；缺失的文件会让 skill 静默失效。",
+    "hint.reference-outside-skill": "把被引用的文件放进 skill 目录，保证 skill 可移植。",
 
     "lint.shadowed":
       'ID "{id}" 有 {count} 处定义，实际生效的是 {winner}；其余 {losers} 处被遮蔽（白占体积、容易改错文件）',
@@ -293,6 +338,12 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "lint.tokenBudget": "模型每步要看到的 skill 描述约 {tokens} tokens，超过预算 {budget}",
     "lint.tokenBudgetError": "模型每步要看到的 skill 描述约 {tokens} tokens，超过预算 {budget} 的 2 倍",
     "lint.tooManySkills": "有 {count} 个 skill 会展示给模型（建议 ≤ 60）",
+    "lint.invalidFrontmatter": '"{id}" 的 frontmatter 格式有问题：{detail}',
+    "lint.frontmatterUnclosed": "缺少闭合的 ---",
+    "lint.frontmatterTypes": "name/description/metadata 类型不对",
+    "lint.emptyBody": '"{id}" 正文几乎是空的（{chars} 字符）',
+    "lint.brokenReference": '"{id}" 引用了不存在的文件：{refs}',
+    "lint.referenceOutside": '"{id}" 引用了 skill 目录之外的文件：{refs}',
 
     "managed.lockUnsupported":
       "lock 版本 {version} 高于本工具支持的 {supported}，已按兼容模式解析（未知字段忽略）",

package/src/install.mjs

@@ -6,7 +6,6 @@ import { stripJsonc } from "./discover.mjs"
 
 export const PACKAGE_NAME = "opencode-skills-doctor"
 const PLUGIN_FILE = "skills-doctor.js"
-const COMMAND_FILE = "skills-doctor.md"
 
 const V1_PLUGIN_SOURCE = `// Generated by skills-doctor install\n// OpenCode 1.x plugin entry\nexport { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"\n`
 
@@ -16,6 +15,24 @@ description: Audit local skills with skills-doctor
 Use the skills_doctor tool to audit the skills in this project. Summarize the top findings and propose concrete fixes (archive shadowed duplicates, hide low-frequency skills). $ARGUMENTS
 `
 
+const V1_REPORT_COMMAND = `---
+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() {
   const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")
   return path.join(base, "opencode")
@@ -139,7 +156,6 @@ export function installOpenCode({ configDir = defaultConfigDir(), version = null
 
   // 1.x
   const pluginFile = path.join(dir, "plugins", PLUGIN_FILE)
-  const commandFile = path.join(dir, "command", COMMAND_FILE)
   const pluginPath = pluginFile
 
   const hasPackage = fs.existsSync(path.join(dir, "node_modules", PACKAGE_NAME, "package.json"))
@@ -167,14 +183,17 @@ export function installOpenCode({ configDir = defaultConfigDir(), version = null
     act(`plugin entry already exists ${pluginFile}`)
   }
 
-  if (!fs.existsSync(commandFile)) {
-    if (!dryRun) {
-      fs.mkdirSync(path.dirname(commandFile), { recursive: true })
-      fs.writeFileSync(commandFile, V1_COMMAND, "utf8")
-      act(`wrote command ${commandFile}`)
-    } else dry(`write command ${commandFile}`)
-  } else {
-    act(`command already exists ${commandFile}`)
+  for (const command of V1_COMMANDS) {
+    const commandFile = path.join(dir, "command", command.file)
+    if (!fs.existsSync(commandFile)) {
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(commandFile), { recursive: true })
+        fs.writeFileSync(commandFile, command.body, "utf8")
+        act(`wrote command ${commandFile}`)
+      } else dry(`write command ${commandFile}`)
+    } else {
+      act(`command already exists ${commandFile}`)
+    }
   }
 
   const nextPlugin = ensureUniqueEntry(config.plugin, pluginPath)
@@ -265,7 +284,6 @@ export function uninstallOpenCode({ configDir = defaultConfigDir(), version = nu
   }
 
   const pluginFile = path.join(dir, "plugins", PLUGIN_FILE)
-  const commandFile = path.join(dir, "command", COMMAND_FILE)
 
   if (Array.isArray(config.plugin) && config.plugin.includes(pluginFile)) {
     const next = config.plugin.filter((entry) => entry !== pluginFile)
@@ -294,7 +312,9 @@ export function uninstallOpenCode({ configDir = defaultConfigDir(), version = nu
     }
   }
 
-  if (fs.existsSync(commandFile)) {
+  for (const command of V1_COMMANDS) {
+    const commandFile = path.join(dir, "command", command.file)
+    if (!fs.existsSync(commandFile)) continue
     const content = readText(commandFile) ?? ""
     if (content.includes("skills_doctor tool")) {
       if (!dryRun) {

package/src/lint.mjs

@@ -1,4 +1,7 @@
+import fs from "node:fs"
+import path from "node:path"
 import { estimateTokens } from "./parse.mjs"
+import { extractReferences } from "./refs.mjs"
 import { translator } from "./i18n.mjs"
 
 export const SEVERITY_ORDER = { error: 0, warn: 1, info: 2 }
@@ -117,6 +120,49 @@ export function lint(skills, options = {}) {
       add("invalid-id", "info", t("lint.invalidId", { id: skill.id }), { skills: [skill.id] })
     }
 
+    if (skill.frontmatterBroken) {
+      add("invalid-frontmatter", "warn", t("lint.invalidFrontmatter", { id: skill.id, detail: t("lint.frontmatterUnclosed") }), {
+        skills: [skill.id],
+      })
+    } else if (skill.frontmatterInvalid) {
+      add("invalid-frontmatter", "warn", t("lint.invalidFrontmatter", { id: skill.id, detail: t("lint.frontmatterTypes") }), {
+        skills: [skill.id],
+      })
+    }
+
+    if (skill.bodyChars < 20) {
+      add("empty-body", "info", t("lint.emptyBody", { id: skill.id, chars: skill.bodyChars }), { skills: [skill.id] })
+    }
+
+    // 只审计「skill 本地资源目录」的引用，避免把 npm 包名、项目相对路径误报成断链
+    const refs = extractReferences(skill.body).filter((ref) => {
+      if (ref.startsWith("@") || ref.endsWith("/")) return false
+      return /^(?:\.\/)?(?:references|scripts|assets|templates|examples)\//.test(ref)
+    })
+    if (refs.length) {
+      const base = path.resolve(path.dirname(skill.file))
+      const missingRefs = []
+      const outsideRefs = []
+      for (const ref of refs) {
+        const target = path.resolve(base, ref)
+        if (target !== base && !target.startsWith(base + path.sep)) outsideRefs.push(ref)
+        if (!fs.existsSync(target)) missingRefs.push(ref)
+      }
+      if (missingRefs.length) {
+        add("broken-reference", "warn", t("lint.brokenReference", { id: skill.id, refs: missingRefs.slice(0, 5).join(", ") }), {
+          skills: [skill.id],
+        })
+      }
+      if (outsideRefs.length) {
+        add(
+          "reference-outside-skill",
+          "info",
+          t("lint.referenceOutside", { id: skill.id, refs: outsideRefs.slice(0, 5).join(", ") }),
+          { skills: [skill.id] },
+        )
+      }
+    }
+
     if (skill.bodyTokens > 4000) {
       add("large-body", "warn", t("lint.largeBody", { id: skill.id, tokens: skill.bodyTokens }), {
         skills: [skill.id],

package/src/mcp.mjs

@@ -1,4 +1,5 @@
 import { auditSkills, formatMarkdown } from "./audit.mjs"
+import { writeHtmlReport } from "./html.mjs"
 import { normalizeLang, detectLang } from "./i18n.mjs"
 
 export const PROTOCOL_VERSION = "2025-06-18"
@@ -30,6 +31,10 @@ export function toolDefinition() {
           type: "boolean",
           description: "Include global skill directories such as ~/.config/opencode and ~/.claude (default true)",
         },
+        html: {
+          type: "string",
+          description: "Optional path; when set, a self-contained HTML report is written there and the path is returned",
+        },
       },
       additionalProperties: false,
     },
@@ -86,7 +91,12 @@ export async function handleMessage(message, { version = "0.0.0" } = {}) {
         const lang = normalizeLang(args.lang) ?? detectLang()
 
         const audit = auditSkills({ cwd: directory, budget, lang, includeGlobal: args.global !== false })
-        return ok(id, { content: [{ type: "text", text: formatMarkdown(audit) }] })
+        let text = formatMarkdown(audit)
+        if (typeof args.html === "string" && args.html.trim()) {
+          const file = writeHtmlReport(audit, args.html.trim(), { title: "skills-doctor report" })
+          text += `\n\nHTML report written to \`${file}\``
+        }
+        return ok(id, { content: [{ type: "text", text }] })
       }
 
       default:

package/src/plugin-v1.mjs

@@ -1,6 +1,25 @@
 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
 
@@ -18,17 +37,25 @@ export const SkillsDoctorPlugin = async ({ directory }) => ({
       args: z.object({
         directory: z.string().optional().describe("Directory to audit (defaults to the current project)"),
         budget: z.number().optional().describe("Description token budget (default 1200)"),
+        html: z.string().optional().describe("Optional path; when set, a self-contained HTML report is written there"),
       }),
       execute: async (args) => {
         const cwd = args.directory || directory || process.cwd()
         const audit = auditSkills({ cwd, budget: typeof args.budget === "number" ? args.budget : null, lang: "en" })
-        return formatMarkdown(audit)
+        let markdown = formatMarkdown(audit)
+        if (typeof args.html === "string" && args.html.trim()) {
+          const file = writeHtmlReport(audit, args.html.trim(), { title: "skills-doctor report" })
+          markdown += `\n\nHTML report written to \`${file}\``
+        }
+        return markdown
       },
     }),
   },
   "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

@@ -1,6 +1,25 @@
 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 命令。
@@ -22,6 +41,10 @@ export default Plugin.define({
           properties: {
             directory: { type: "string", description: "Directory to audit (defaults to the current project)" },
             budget: { type: "number", description: "Description token budget (default 1200)" },
+            html: {
+              type: "string",
+              description: "Optional path; when set, a self-contained HTML report is written there",
+            },
           },
           additionalProperties: false,
         },
@@ -30,7 +53,12 @@ export default Plugin.define({
           const directory = (input && typeof input.directory === "string" && input.directory) || ctx.location.directory
           const budget = input && typeof input.budget === "number" ? input.budget : null
           const audit = auditSkills({ cwd: directory, budget, lang: "en" })
-          return { content: formatMarkdown(audit) }
+          let markdown = formatMarkdown(audit)
+          if (input && typeof input.html === "string" && input.html.trim()) {
+            const file = writeHtmlReport(audit, input.html.trim(), { title: "skills-doctor report" })
+            markdown += `\n\nHTML report written to \`${file}\``
+          }
+          return { content: markdown }
         },
       })
     })
@@ -48,12 +76,38 @@ export default Plugin.define({
           })
         },
       })
+      editor.add({
+        name: "skills-report",
+        description: "Write a self-contained HTML skills report to a path you choose",
+        execute: async ({ sessionID, prompt, delivery }) => {
+          await ctx.session.prompt({
+            ...prompt,
+            sessionID,
+            text: "Ask me where to save the HTML report (a file path, default ./skills-report.html), then call the skills_doctor tool with the html argument set to that path and tell me where it was written.",
+            delivery,
+          })
+        },
+      })
+      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 })
     })
   },
 })