opencode-skills-doctor 0.9.6 → 0.9.7

package/README.md

@@ -5,8 +5,8 @@
 <h1 align="center">skills-doctor</h1>
 
 <p align="center">
-  <b>Audit the token cost your coding agent pays for skills on every step.</b><br>
-  A word-piece estimate, boilerplate-aware overlap, and a plan that keeps the routing sentence and hides the redundant skill first.
+  <b>Your skills are quietly taxing every single step.</b><br>
+  29 skills = ~3,074 tokens burned before the model even sees your code.
 </p>
 
 <p align="center">
@@ -32,25 +32,27 @@
 > **Runs 100% locally.** No telemetry, no account, no uploads — your skills,
 > prompts and files never leave your machine. See [Privacy](#privacy-local-only-no-data-collection).
 
-## Contents
+## The hidden tax
 
-- [The 30-second version](#the-30-second-version) · [Privacy](#privacy-local-only-no-data-collection)
-- [See it](#see-it) · [How it works](#how-it-works) · [Quick start](#quick-start)
-- [Install](#install) · [Use it in CI](#use-it-in-ci-github-action) · [Commands](#commands) · [Works where you work](#works-where-you-work)
-- [Why it is safe](#why-it-is-safe) · [Development](#development)
+Every agent skill with a `description` is injected into the system prompt on **every single step**. On a real machine with 29 skills that was **~3,074 tokens** — before the model read a single line of code. Duplicates silently shadow each other. Long descriptions never get trimmed. Broken references go unnoticed.
 
-## The 30-second version
+`skills-doctor` measures the exact cost, shows which definition actually wins, and gives you a concrete plan to cut it:
 
-Every agent skill with a `description` is advertised to the model on **every single step**. On a machine with 29 skills that is **~3,074 tokens per step** — before the model reads a line of your code. Duplicates silently shadow each other, descriptions drift, and references to files that no longer exist go unnoticed.
+```text
+current: ~3,124 tokens/step (30 advertised)   budget: 1,200
+
+Recommended: trim 26 + hide 2 → 1,184 tokens/step  (−1,940)
+Over 100 steps that saves ~194,000 tokens.
+```
 
-`skills-doctor` measures that cost, shows which definition actually wins, and fixes it:
+One command. Runs 100% locally. No account, no telemetry, nothing leaves your machine.
 
 | | |
 |---|---|
 | **Find** | token budget, shadowed duplicates, flat/dir collisions, long descriptions, oversized bodies, broken references, invalid frontmatter, stale skills |
 | **Fix** | archive shadowed definitions (reversible), hide redundant skills before unique ones, keep the routing sentence in the plan |
 | **Update** | sync skills from HTTP catalogs with a lockfile, drift detection and `--prune` |
-| **Report** | terminal, JSON, or a self-contained HTML report |
+| **Report** | a short note in the OpenCode chat, plus the terminal and JSON |
 | **Run it** | CLI · OpenCode plugin (1.x/2.x/Desktop) · MCP server · DeepSeek Harness skill |
 
 ## Privacy: local-only, no data collection
@@ -63,17 +65,13 @@ Every agent skill with a `description` is advertised to the model on **every sin
 | **Never reads** | conversation history, session transcripts, source code, documents, credentials, API keys or environment secrets |
 | **Uploads** | nothing: there is no server component and no remote endpoint besides the two optional calls below |
 | **Network** | only when you ask for it. `update` fetches the HTTP catalogs **you** configure; `upgrade` / the daily update check reads the npm registry for the latest version number (cached 24 h — disable with `"checkUpdates": "off"`, `SKILLS_DOCTOR_UPDATE_CHECK=0` or `--no-update-check`) |
-| **Writes** | only what you asked for: the HTML/JSON report, `.skills-doctor-archive/`, `.skills-doctor.json`, the lockfile, and the plugin/MCP/skill entries created by `install` |
+| **Writes** | only what you asked for: `.skills-doctor-archive/`, `.skills-doctor.json`, the lockfile, and the plugin/MCP/skill entries created by `install` |
 
 `opencode.json(c)` and MCP configs can contain credentials; they are parsed locally only to find the relevant entries, and those values are never sent anywhere nor included in a report. Reports contain file paths and skill descriptions (which are part of your skill files), never file bodies. `check`, `plan`, `scan`, `fix --dry-run` and `mcp` all work with the network fully offline.
 
-## See it
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/wangyuchen5110/opencodeplugginprogram/main/docs/assets/report.png" alt="skills-doctor HTML report" width="82%">
-</p>
+## What you see
 
-A real `check --html` run: summary cards, the context-budget bar, filterable findings, and the exact potential savings.
+In OpenCode 2, the first message of a session gets one notice in the chat when a skill is over budget, shadowed, or broken. It names at most three problems and does not change any file. `/skills-doctor` posts that notice again. The terminal `check` and `--json` output stay for CI.
 
 ## How it works
 
@@ -84,7 +82,7 @@ flowchart LR
   C --> D["lint<br/>16 rules + token budget"]
   D --> E{"findings?"}
   E -->|"yes"| F["plan / fix<br/>trim · hide · archive"]
-  E -->|"always"| G["report<br/>terminal · JSON · HTML"]
+  E -->|"always"| G["tell you<br/>chat · terminal · JSON"]
   F --> G
   G --> H["you · CI · the agent"]
 ```
@@ -100,26 +98,12 @@ npx -y opencode-skills-doctor check
 
 # how many tokens can I actually cut?
 npx -y opencode-skills-doctor plan
-
-# shareable HTML report
-npx -y opencode-skills-doctor check --html report.html --open
-```
-
-Example `plan` output on a real setup:
-
-```text
-current: ~3,124 tokens/step (30 advertised)   budget: 1,200
-
-Option A — trim descriptions   26 skills → 1,606  (−1,518)
-Option B — hide skills         11 skills → 1,200  (−1,924)
-Recommended                     trim 26 + hide 2 → 1,184  (−1,940)
-over 100 steps that saves ~194,000 tokens
 ```
 
 ## Install
 
 ```powershell
-# OpenCode — plugin + /skills-doctor, /skills-report, /skills-upgrade commands
+# OpenCode — plugin + /skills-doctor and /skills-upgrade
 npx -y opencode-skills-doctor install              # auto-detects 1.x / 2.x / Desktop
 npx -y opencode-skills-doctor install --client desktop
 
@@ -158,16 +142,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: wangyuchen5110/opencodeplugginprogram@v0.9.6
+      - uses: wangyuchen5110/opencodeplugginprogram@v0.9.7
         with:
           budget: "1200"
           fail-on: warn             # error | warn | never
-          html: skills-report.html  # written and uploaded as an artifact
           comment: "true"           # post the summary on the PR
 ```
 
-It writes a summary to the job page, uploads the HTML report, optionally comments
-on the pull request, and fails the job according to `fail-on`.
+It writes a summary to the job page, optionally comments on the pull request,
+and fails the job according to `fail-on`.
 
 | Input | Default | Purpose |
 |---|---|---|
@@ -175,7 +158,6 @@ on the pull request, and fails the job according to `fail-on`.
 | `budget` | `1200` | Description tokens paid per model step |
 | `fail-on` | `error` | Fail on `error`, `warn`, or `never` |
 | `extra-args` | — | Extra `check` flags, e.g. `--no-global` |
-| `html` | — | HTML report path; uploaded as an artifact when set |
 | `comment` | `false` | Post/append the summary as a pull request comment |
 
 Outputs: `exit-code`, `error-count`, `warning-count`, `advertised-tokens`.
@@ -206,7 +188,7 @@ All commands accept `--json`, `--lang en|zh`, `--budget`, `--root` and `--no-glo
 | **Claude Code / Codex** | MCP server (`npx -y opencode-skills-doctor mcp`) |
 | **Grok CLI / Cursor** | their skill roots are scanned natively |
 | **Hermes Agent** | MCP entry in `~/.hermes/config.yaml`; `~/.hermes/skills` is scanned |
-| **Kimi Code** | `install --client kimi` writes `~/.kimi-code/mcp.json` + the audit skill |
+| **Kimi Code** | `install --client kimi` writes `~/.kimi-code/mcp.json` + the audit skill; or use the native plugin: [kimi-skills-doctor](https://github.com/wangyuchen5110/kimi-skills-doctor) |
 | **OpenClaw** | separate wrapper with its own native plugin: [openclaw-skills-doctor](https://github.com/wangyuchen5110/openclaw-skills-doctor) |
 
 ## Why it is safe

package/SECURITY.md

@@ -33,7 +33,7 @@ Include the version, a reproduction, the impact, and a suggested fix if you have
 - **No network by default.** Two opt-in/opt-out exceptions: `update` fetches the catalog URLs you configure, and the daily update check reads only the latest version number from the npm registry (24 h cache; disable with `"checkUpdates": "off"`, `SKILLS_DOCTOR_UPDATE_CHECK=0` or `--no-update-check`).
 - **No user data is read.** The tool reads skill files, their referenced resources, agent configuration and its own lockfile. It does not read chat history, session transcripts, source code, documents, model credentials or API keys — and it does not upload anything it reads.
 - **Config files may hold secrets** (`opencode.json(c)`, MCP configs). They are parsed locally only to locate the entries the tool needs; values are never transmitted, printed, or copied into reports.
-- **Reports are local files.** HTML/JSON reports contain file paths and skill descriptions, never file bodies. They can reveal your directory layout, so review them before sharing.
+- **Reports stay on the machine.** Terminal output, JSON, the pull-request comment and the chat notice contain file paths and skill descriptions, never file bodies. They can reveal your directory layout, so review them before sharing.
 - `check`, `plan`, `scan`, `fix --dry-run` and `mcp` are fully offline; you can run them with networking disabled.
 
 ## Risk areas and mitigations

package/SECURITY.zh-CN.md

@@ -33,7 +33,7 @@
 - **默认不联网。** 只有两个例外：`update` 抓取你配置的 catalog URL；每日更新检查只从 npm registry 读取最新版本号（缓存 24h，可用 `"checkUpdates": "off"`、`SKILLS_DOCTOR_UPDATE_CHECK=0` 或 `--no-update-check` 关闭）。
 - **不读取用户数据。** 只读 skill 文件及其引用资源、agent 配置和自身 lockfile；不读对话历史、会话记录、源代码、文档、模型凭据或 API key，也不上传任何读到的内容。
 - **配置文件可能含密钥**（`opencode.json(c)`、MCP 配置）：只在本地解析以定位需要的条目，值不会被传输、打印或写进报告。
-- **报告是本地文件。** HTML/JSON 报告含文件路径和 skill 描述，不含文件正文；可能暴露目录结构，分享前请自行检查。
+- **报告留在本机。** 终端输出、JSON、PR 评论和对话通知含文件路径和 skill 描述，不含文件正文；可能暴露目录结构，分享前请自行检查。
 - `check`、`plan`、`scan`、`fix --dry-run`、`mcp` 完全离线，可在断网环境运行。
 
 ## 风险点与缓解措施

package/docs/README.zh-CN.md

@@ -49,9 +49,9 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | **来源** | `.opencode/skills`、`.claude/skills`、`.agents/skills`、`.grok/skills`、`.cursor/skills`、`.hermes/skills`、`.kimi-code/skills`、`.dsh/skills`（含 `$DSH_HOME`）、`opencode.json(c)` 配置、HTTP catalog |
 | **能查** | 同 ID 遮蔽、重复、超长描述、超大正文、每步 token 预算、断链引用、非法 frontmatter、空正文、陈旧 skill |
 | **能修** | 归档遮蔽定义（可逆）、先藏重复的 skill、方案只留路由用的第一句 |
-| **报告** | 终端、JSON，或自包含 HTML（`--html [file] --open`） |
+| **报告** | OpenCode 对话里的一条通知，加上终端和 JSON |
 | **规划** | 精确 token 节省：精简描述 / 隐藏 skill，按 N 步折算 |
-| **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
+| **成本** | CLI 0 token；有问题时每个会话在对话里发一条通知 |
 | **要求** | Node ≥ 20，零运行时依赖 |
 | **质量** | 63 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
@@ -65,7 +65,7 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | **不会读** | 对话历史、会话记录、源代码、文档、凭据、API key、环境变量里的密钥 |
 | **不会上传** | 任何东西：没有服务端组件，除下面两个可选联网外没有任何远端地址 |
 | **联网** | 只在你主动触发时发生：`update` 抓取**你自己配置**的 HTTP catalog；`upgrade` / 每日更新检查只读 npm registry 的最新版本号（缓存 24h，可用 `"checkUpdates": "off"`、`SKILLS_DOCTOR_UPDATE_CHECK=0` 或 `--no-update-check` 关闭） |
-| **会写** | 只写你要求的内容：HTML/JSON 报告、`.skills-doctor-archive/`、`.skills-doctor.json`、lockfile，以及 `install` 生成的插件/MCP/skill 条目 |
+| **会写** | 只写你要求的内容：`.skills-doctor-archive/`、`.skills-doctor.json`、lockfile，以及 `install` 生成的插件/MCP/skill 条目 |
 
 `opencode.json(c)` 和 MCP 配置里可能有凭据；它们只在本地被解析用来定位相关条目，值不会被发送，也不会出现在报告里。报告只含文件路径和 skill 描述（本来就是你的 skill 文件内容），不包含正文。`check`、`plan`、`scan`、`fix --dry-run`、`mcp` 都可以在断网环境下运行。
 
@@ -132,20 +132,13 @@ skills-doctor check
 skills-doctor check --json
 skills-doctor check --budget 800 --strict    # CI 用
 skills-doctor check --root .\some-project --no-global
-skills-doctor check --html report.html       # 自包含 HTML 报告
-skills-doctor check --html report.html --open
 ```
 
-### HTML 报告
+### 对话通知
 
-`--html [file]` 生成单个自包含 HTML 文件（无外部资源）：
+OpenCode 2 在你发出第一条消息时，如果有 error 或 warning，就在对话里发一条通知。它是带描述 `skills-doctor` 的 synthetic 消息，会单独占一行，不会再开一轮模型。`/skills-doctor` 会再发一次，没有问题也会说。工具和 MCP 返回同一段短文，不写文件。最多列三条。归档和隐藏仍然要你确认。
 
-- 摘要卡片 + 上下文预算条；
-- 可按严重级别和文本过滤的 findings；
-- skill 表格：来源、token 成本、描述预览、文件路径；
-- 只写 `--html` 不带路径时默认 `./skills-report.html`；`--open` 自动打开浏览器。
-
-插件和 MCP 工具同样接受 `html` 参数，所以可以让 agent 先问你要存哪里——例如：*"把报告存到 D:\reports\skills.html"*。
+OpenCode 1.x 没有这条通知接口，同一段话交给模型，让它在回复里说出来。
 
 ### `plan`（到底能省多少 token？）
 
@@ -162,7 +155,7 @@ skills-doctor plan --json
 - **方案 B**：用最少的隐藏数量把总量压进预算（仍可 `@id` 加载；按单项节省从大到小取，对「最少隐藏数」是最优的）；
 - **推荐方案**：先精简再隐藏，不重复计算，并按 `--steps`（默认 100）折算总节省。
 
-超预算时 `check` 会打印一行提示，HTML 报告里有同样的「potential savings」卡片。
+超预算时 `check` 会打印一行提示。具体方案看 `plan`。
 
 ### `scan`
 
@@ -273,9 +266,8 @@ skills-doctor upgrade --apply    # npm install -g opencode-skills-doctor@latest
 
 它会注册：
 
-- `skills_doctor` 工具（命名空间 `skills`）—— agent 传 `{ directory?, budget?, html? }` 就能拿到 markdown 审计报告；
+- `skills_doctor` 工具（命名空间 `skills`）—— `{ directory?, budget? }` 返回对话简报，不写文件；
 - `/skills-doctor` 命令 —— 让 agent 跑一次审计并总结修复建议；
-- `/skills-report` —— 先问你要把 HTML 报告存到哪里，再写文件；
 - `/skills-upgrade` —— 检查 skills-doctor 自身有没有新版本。
 
 `@opencode/plugin` 是可选 peer 依赖，运行时由 OpenCode 提供。
@@ -317,7 +309,7 @@ npx opencode-skills-doctor install --client desktop
 ```
 
 - 在标准安装位置探测桌面版，并从 `resources/app.asar` 读出内置 core 版本（例如 1.17.11），据此选择对应插件 API；
-- 写入与 CLI 相同的插件条目和 `/skills-doctor`、`/skills-report`、`/skills-upgrade` 命令 —— 装完重启桌面应用；
+- 写入与 CLI 相同的插件条目和 `/skills-doctor`、`/skills-upgrade` 命令 —— 装完重启桌面应用；
 - `--client auto`（默认）在同时装了 CLI 时优先 CLI 版本；`--client opencode` 跳过桌面探测；
 - `uninstall --client desktop` 反向撤销。
 
@@ -332,16 +324,15 @@ npx opencode-skills-doctor install
 安装器会自动识别 OpenCode 版本并接好：
 
 - **2.x** —— 在 `opencode.json(c)` 里加 `"plugins": ["opencode-skills-doctor"]`；
-- **1.x** —— 把包装进 `~/.config/opencode`、写本地插件入口、生成 `/skills-doctor`、`/skills-report`、`/skills-upgrade` 三个 markdown 命令、补 `"type": "module"`；
+- **1.x** —— 把包装进 `~/.config/opencode`、写本地插件入口、生成 `/skills-doctor`、`/skills-upgrade` 两个 markdown 命令、补 `"type": "module"`；
 - 改配置前会备份为 `<config>.bak-<timestamp>`。
 
 支持 `--dry-run` 预览、`--config-dir <dir>` 指定配置目录、`--no-npm` 跳过装包。
 
 装好后你会得到：
 
-- `skills_doctor` 工具（可选 `html` 参数，把报告写到指定路径）；
+- `skills_doctor` 工具，返回对话简报，不写文件；
 - `/skills-doctor` 命令（1.x 是生成的 markdown 命令，2.x 是插件命令）；
-- `/skills-report` 命令（2.x）—— 会先问你要把 HTML 报告存到哪里；
 - `/skills-upgrade` 命令（2.x）—— 检查 skills-doctor 自身是否有新版本；
 - 当 skill 描述预算超标时，系统提示里会注入一次提醒（每个会话最多一次）。
 
@@ -396,7 +387,7 @@ npx -y opencode-skills-doctor install --client dsh
 
 它会找到 `~/.dsh/profiles/<profile>/cordis.patch.yml`（默认 `desktop`，否则用 `--profile <name>`），把 `mcp-skills-doctor` 这一行放在 `- insert:` 块里幂等写入，并把 `skills-doctor-audit` 技能复制到 `~/.dsh/skills/`。重启 DSH（启用 HMR 时会自动重载 patch）加载 MCP 工具；skill 目录有监听，无需重启。
 
-- 工具名 `mcp__skills_doctor__skills_doctor`，参数 `directory`、`budget`、`lang`、`global`、`html`；
+- 工具名 `mcp__skills_doctor__skills_doctor`，参数 `directory`、`budget`、`lang`、`global`；
 - `uninstall --client dsh` 同时移除配置条目和 skill；
 - `--dsh-home <dir>` 用于非默认的 DSH 主目录。
 

package/docs/REFERENCE.md

@@ -13,7 +13,7 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills
 | **Skill sources** | `.opencode/skills`, `.claude/skills`, `.agents/skills`, `.grok/skills`, `.cursor/skills`, `.hermes/skills`, `.kimi-code/skills`, `opencode.json(c)` entries, HTTP catalogs |
 | **What it finds** | shadowed IDs, duplicates, long descriptions, oversized bodies, per-step token budget, broken file references, invalid frontmatter, empty bodies, stale skills |
 | **What it fixes** | archives shadowed definitions (reversible), hides low-frequency skills, syncs catalogs with drift detection |
-| **Reports** | terminal, JSON, or a self-contained HTML report (`--html [file] --open`) |
+| **Reports** | a chat notice in OpenCode, plus the terminal and JSON |
 | **Plan** | exact token savings: trim descriptions and/or hide skills, projected over N steps |
 | **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 |
@@ -82,20 +82,13 @@ skills-doctor check
 skills-doctor check --json
 skills-doctor check --budget 800 --strict    # for CI
 skills-doctor check --root .\some-project --no-global
-skills-doctor check --html report.html       # self-contained HTML report
-skills-doctor check --html report.html --open
 ```
 
-### HTML report
+### Chat notice
 
-`--html [file]` writes a single self-contained HTML file (no external assets):
+OpenCode 2 posts one notice in the session the first time you send a message, when there is an error or a warning. The notice is a synthetic message with the description `skills-doctor`, so it shows as its own row. It does not start another model turn. `/skills-doctor` posts it again, including when nothing is wrong. The tool and the MCP server return the same short text and do not write a file. At most three findings are listed. Archive and hide still wait for you to confirm.
 
-- summary cards and a context-budget bar;
-- findings filterable by severity and text;
-- a skill table with scope, token cost, description preview and file path;
-- default path `./skills-report.html` when `--html` is given without a value; `--open` launches the browser.
-
-The plugin and MCP tool accept the same thing as an `html` argument, so the agent can ask you where to save it — for example: *"save the report to D:\reports\skills.html"*.
+On OpenCode 1.x the same text is handed to the model with an instruction to say it in the chat.
 
 ### `plan` (how many tokens can I actually save?)
 
@@ -112,7 +105,7 @@ It answers "how much can I cut, exactly?":
 - **Option B** hides the fewest skills needed to reach the budget (still loadable with `@id`; picking the largest savings first is optimal for "minimal hides");
 - **Recommended** trims first, then hides, with no double counting, and projects the saving over `--steps` model steps (default 100).
 
-`check` prints a one-line pointer when you are over budget, and the HTML report shows the same potential-savings card.
+`check` prints a one-line pointer when you are over budget. `plan` is the breakdown.
 
 ### `scan`
 
@@ -223,9 +216,8 @@ The package also exports an OpenCode 2.x plugin:
 
 It registers:
 
-- 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;
+- the `skills_doctor` tool (namespace `skills`) — `{ directory?, budget? }` returns the short chat briefing and writes nothing;
+- `/skills-doctor` — posts that briefing in the chat;
 - `/skills-upgrade` — checks whether skills-doctor itself has a newer version.
 
 `@opencode/plugin` is an optional peer dependency; OpenCode provides it at runtime.
@@ -267,7 +259,7 @@ npx opencode-skills-doctor install --client desktop
 ```
 
 - detects the app in the standard install locations and reads its bundled core version from `resources/app.asar` (e.g. 1.17.11), then uses the matching plugin API;
-- writes the same plugin entry and `/skills-doctor`, `/skills-report`, `/skills-upgrade` commands as the CLI install — restart the desktop app afterwards;
+- writes the same plugin entry and `/skills-doctor` and `/skills-upgrade` commands as the CLI install — restart the desktop app afterwards;
 - `--client auto` (default) prefers the CLI version when both are installed; `--client opencode` skips desktop detection;
 - `uninstall --client desktop` reverses it.
 
@@ -282,18 +274,17 @@ 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, generates `/skills-doctor`, `/skills-report` and `/skills-upgrade` markdown commands, sets `"type": "module"`;
+- **1.x** — installs the package into `~/.config/opencode`, writes the local plugin entry, generates `/skills-doctor` 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.
 
 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.
+- the `skills_doctor` tool, which returns the chat briefing and writes nothing;
+- `/skills-doctor` (1.x: generated markdown command; 2.x: a notice posted in the chat);
+- `/skills-upgrade` (2.x) that checks for a newer skills-doctor;
+- one chat notice per session when a skill has an error or a warning. On 1.x the same text is given to the model to say out loud. `uninstall` deletes a leftover `/skills-report` command from older installs.
 
 ### Uninstall
 
@@ -346,7 +337,7 @@ npx -y opencode-skills-doctor install --client dsh
 
 It locates `~/.dsh/profiles/<profile>/cordis.patch.yml` (default `desktop`; otherwise `--profile <name>`), inserts the `mcp-skills-doctor` row under an `- insert:` block idempotently, and copies the `skills-doctor-audit` skill into `~/.dsh/skills/`. Restart DSH (or let HMR reload the patch) to load the MCP tool; the skill is watched and appears without a restart.
 
-- tool name `mcp__skills_doctor__skills_doctor`, arguments `directory`, `budget`, `lang`, `global`, `html`;
+- tool name `mcp__skills_doctor__skills_doctor`, arguments `directory`, `budget`, `lang`, `global`;
 - `uninstall --client dsh` removes both the patch entry and the skill;
 - `--dsh-home <dir>` for a non-standard DSH home.
 

package/docs/assets/banner.svg

@@ -41,7 +41,7 @@
       <text x="22" y="96" fill="#3fb950">✓ 29 skills · ~3,074 tokens/step</text>
       <text x="22" y="128" fill="#d29922">! over budget ×2</text>
       <text x="22" y="160" fill="#58a6ff">plan → save ~1,940 tokens/step</text>
-      <text x="22" y="192" fill="#8b9bb4">HTML report ready →</text>
+      <text x="22" y="192" fill="#8b9bb4">told you in the chat →</text>
     </g>
   </g>
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.9.6",
-  "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, Cursor, Hermes Agent, Kimi Code and DeepSeek Harness.",
+  "version": "0.9.7",
+  "description": "Audit, fix and update agent skills: token cost, broken references, shadowed duplicates, catalog sync. Tells you in the chat. CLI, OpenCode plugin, MCP server; works with OpenCode, Claude Code, Codex, Grok CLI, Cursor, Hermes Agent, Kimi Code and DeepSeek Harness.",
   "type": "module",
   "exports": {
     ".": "./src/plugin.mjs",

package/skills/dsh-skills-doctor/SKILL.md

@@ -21,9 +21,9 @@ npx -y opencode-skills-doctor check --json
 Read `summary.advertisedTokens` (cost per model step), `summary.advertised` and `findings[]`.
 If the command fails, fall back to `opencode-skills-doctor` when installed globally, or ask the user to run it from the repo.
 
-## 2. Explain the top findings
+## 2. Tell the user in this chat
 
-Report at most three findings, in plain language, each with its token impact:
+Say at most three findings, in plain language. Do not write a report file.
 
 - `token-budget` — descriptions cost roughly N tokens on **every** model step;
 - `shadowed` — the same skill ID loads from several places, only one wins;
@@ -47,8 +47,3 @@ Report `recommended.savings` (per step), `recommended.final` and `recommended.st
 - Trim descriptions manually, keeping them discoverable
 - Ask first, then re-run `check` to confirm the new cost
 
-## 5. Optional shareable report
-
-```powershell
-npx -y opencode-skills-doctor check --html skills-report.html --open
-```

package/src/audit.mjs

@@ -67,6 +67,35 @@ export function auditSkills({
   }
 }
 
+/**
+ * 给对话用的短结论。agent 应原样告诉用户，不要再写成文件。
+ */
+export function formatChat(audit, { limit = 3 } = {}) {
+  const zh = audit.lang === "zh"
+  const problems = audit.findings.filter((finding) => finding.severity === "error" || finding.severity === "warn")
+  if (!problems.length) {
+    return zh
+      ? `skills-doctor：技能没有需要处理的问题。${audit.summary.advertised} 个会在每一步注入，大约 ${audit.summary.advertisedTokens} token。`
+      : `skills-doctor: no skill problems to act on. ${audit.summary.advertised} skills are injected on every step, about ${audit.summary.advertisedTokens} tokens.`
+  }
+  const lines = [
+    zh ? "skills-doctor：" : "skills-doctor:",
+    zh
+      ? `技能有 ${problems.length} 个问题：`
+      : `${problems.length} skill problem${problems.length === 1 ? "" : "s"}:`,
+  ]
+  for (const finding of problems.slice(0, limit)) lines.push(`- ${finding.message}`)
+  if (problems.length > limit) {
+    lines.push(zh ? `- 还有 ${problems.length - limit} 条，需要的话我再展开。` : `- ${problems.length - limit} more. Ask if you want them.`)
+  }
+  lines.push(
+    zh
+      ? "我不会改文件。你确认之后，我可以归档被盖住的副本，或把不常用的藏起来。"
+      : "I will not change any files. After you confirm, I can archive shadowed copies or hide skills you rarely use.",
+  )
+  return lines.join("\n")
+}
+
 /** 把审计结果渲染成适合给 agent / PR 评论用的 markdown。 */
 export function formatMarkdown(audit, { limit = 25 } = {}) {
   const lines = []

package/src/cli.mjs

@@ -11,7 +11,7 @@ import { startMcpServer } from "./mcp.mjs"
 import { installOpenCode, uninstallOpenCode } from "./install.mjs"
 import { installDsh, uninstallDsh } from "./dsh.mjs"
 import { installKimi, uninstallKimi } from "./kimi.mjs"
-import { writeHtmlReport, openReport } from "./html.mjs"
+
 import { planBudget } from "./plan.mjs"
 import {
   checkForUpdate,
@@ -80,7 +80,7 @@ function parseArgs(argv) {
     extraDirs: [],
     configDir: null,
     noNpm: false,
-    html: null,
+
     open: false,
     apply: false,
     updateCheck: true,
@@ -174,19 +174,6 @@ function parseArgs(argv) {
       case "--no-npm":
         options.noNpm = true
         break
-      case "--html": {
-        const next = args[i + 1]
-        if (next && !next.startsWith("-")) {
-          options.html = path.resolve(next)
-          i++
-        } else {
-          options.html = path.resolve("skills-report.html")
-        }
-        break
-      }
-      case "--open":
-        options.open = true
-        break
       case "--apply":
         options.apply = true
         break
@@ -838,23 +825,16 @@ export async function main(argv) {
     })
     const result = buildCheckResult(audit, options)
 
-    let htmlPath = null
-    if (options.html) {
-      htmlPath = writeHtmlReport(audit, options.html)
-      if (options.open) openReport(htmlPath)
-    }
-
     if (options.json) {
       console.log(
         JSON.stringify(
-          { ...result, html: htmlPath, skills: serializeSkills(audit.skills, audit.managed) },
+          { ...result, skills: serializeSkills(audit.skills, audit.managed) },
           null,
           2,
         ),
       )
     } 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

package/src/i18n.mjs

@@ -33,8 +33,6 @@ 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)
   --client <name>      install/uninstall: auto | opencode | desktop | dsh | kimi (default auto)
   --profile <name>     dsh: profile to install into (default: desktop, or the only one)
@@ -60,7 +58,6 @@ 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:",
@@ -265,8 +262,6 @@ 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）
   --client <name>     install/uninstall: auto | opencode | desktop | dsh | kimi（默认 auto）
   --profile <name>    dsh: 安装到哪个 profile（默认 desktop，或唯一的一个）
@@ -292,7 +287,6 @@ 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": "建议:",

package/src/install.mjs

@@ -11,15 +11,9 @@ const PLUGIN_FILE = "skills-doctor.js"
 const V1_PLUGIN_SOURCE = `// Generated by skills-doctor install\n// OpenCode 1.x plugin entry\nexport { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"\n`
 
 const V1_COMMAND = `---
-description: Audit local skills with skills-doctor
+description: Tell the user about skill problems in this chat
 ---
-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
+Call the skills_doctor tool, then tell the user its briefing in this chat. Do not write a report file. Do not change skill files unless the user confirms. $ARGUMENTS
 `
 
 const V1_UPGRADE_COMMAND = `---
@@ -30,9 +24,9 @@ Run \`npx -y opencode-skills-doctor upgrade\` in the terminal (add --apply only
 
 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 },
 ]
+const V1_LEGACY_COMMANDS = ["skills-report.md"]
 
 export function defaultConfigDir() {
   const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")
@@ -353,11 +347,14 @@ export function uninstallOpenCode({
     }
   }
 
-  for (const command of V1_COMMANDS) {
+  for (const command of [...V1_COMMANDS, ...V1_LEGACY_COMMANDS.map((file) => ({ file, legacy: true }))]) {
     const commandFile = path.join(dir, "command", command.file)
     if (!fs.existsSync(commandFile)) continue
     const content = readText(commandFile) ?? ""
-    if (content.includes("skills_doctor tool")) {
+    const owned = command.legacy
+      ? content.includes("skills_doctor") || content.includes("skills-doctor")
+      : content.includes("skills_doctor tool")
+    if (owned) {
       if (!dryRun) {
         fs.rmSync(commandFile, { force: true })
         act(`deleted ${commandFile}`)

package/src/mcp.mjs

@@ -1,5 +1,4 @@
-import { auditSkills, formatMarkdown } from "./audit.mjs"
-import { writeHtmlReport } from "./html.mjs"
+import { auditSkills, formatChat } from "./audit.mjs"
 import { normalizeLang, detectLang } from "./i18n.mjs"
 
 export const PROTOCOL_VERSION = "2025-06-18"
@@ -10,7 +9,7 @@ export function toolDefinition() {
   return {
     name: TOOL_NAME,
     description:
-      "Audit installed agent skills (OpenCode, Claude Code, Grok, Cursor, Hermes, Kimi, DSH): shadowed duplicates, per-step description token budget, oversized bodies and fix hints. Returns a markdown report.",
+      "Audit installed agent skills and return a short briefing to say to the user in the chat. Does not write a file.",
     inputSchema: {
       type: "object",
       properties: {
@@ -31,10 +30,6 @@ 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,
     },
@@ -91,12 +86,7 @@ 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 })
-        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 }] })
+        return ok(id, { content: [{ type: "text", text: formatChat(audit) }] })
       }
 
       default:

package/src/notify.mjs

@@ -0,0 +1,62 @@
+import { auditSkills, formatChat } from "./audit.mjs"
+
+const settled = new Set()
+const visible = new Set()
+
+function keyOf(cwd, sessionID) {
+  return `${cwd}::${sessionID}`
+}
+
+/** 这条会话里，用户已经能在时间线上看到通知。 */
+export function chatNoticeVisible(cwd, sessionID) {
+  return visible.has(keyOf(cwd, sessionID))
+}
+
+/**
+ * 往 OpenCode 会话里发一条用户能看见的通知。
+ * 带 description 的 synthetic 会单独出现在对话里；resume 为 false 时不另开一轮模型。
+ * 每个会话最多自动发一次。force 用于用户明确执行了 /skills-doctor。
+ */
+export async function postChatNotice({
+  sessionID,
+  cwd = process.cwd(),
+  includeGlobal = true,
+  synthetic,
+  resume = false,
+  force = false,
+  when = "problems",
+} = {}) {
+  if (!sessionID || typeof synthetic !== "function") return null
+  const key = keyOf(cwd, sessionID)
+  if (!force && settled.has(key)) return null
+
+  const audit = auditSkills({ cwd, includeGlobal })
+  const notable = audit.findings.some((finding) => finding.severity === "error" || finding.severity === "warn")
+  if (when === "problems" && !notable) {
+    settled.add(key)
+    return null
+  }
+
+  const text = formatChat(audit)
+  try {
+    await synthetic({
+      sessionID,
+      text,
+      description: "skills-doctor",
+      resume,
+    })
+  } catch {
+    if (!force) settled.add(key)
+    return null
+  }
+
+  settled.add(key)
+  visible.add(key)
+  return text
+}
+
+/** 测试用。 */
+export function resetChatNotices() {
+  settled.clear()
+  visible.clear()
+}

package/src/plugin-v1.mjs

@@ -1,6 +1,5 @@
 import { tool } from "@opencode-ai/plugin"
-import { auditSkills, formatMarkdown } from "./audit.mjs"
-import { writeHtmlReport } from "./html.mjs"
+import { auditSkills, formatChat } from "./audit.mjs"
 import { budgetWarning } from "./warning.mjs"
 import { loadConfig } from "./config.mjs"
 import { checkForUpdate, resolveMode, toolVersion } from "./self-update.mjs"
@@ -33,27 +32,21 @@ export const SkillsDoctorPlugin = async ({ directory }) => ({
   tool: {
     skills_doctor: tool({
       description:
-        "Audit installed agent skills (OpenCode, Claude Code, Grok, Cursor, Hermes, Kimi, DSH): shadowing, per-step token budget and fix hints. Returns a markdown report.",
+        "Audit installed agent skills and return a short briefing to say to the user in the chat. Does not write a file.",
       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" })
-        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
+        const audit = auditSkills({ cwd, budget: typeof args.budget === "number" ? args.budget : null })
+        return formatChat(audit)
       },
     }),
   },
   "experimental.chat.system.transform": async (input, output) => {
     const warning = budgetWarning({ cwd: directory, sessionID: input?.sessionID })
-    if (warning) output.system.push(warning)
+    if (warning) output.system.push(`Say this to the user in the chat. Do not write a file.\n\n${warning}`)
     const note = await updateNote({ directory, sessionID: input?.sessionID })
     if (note) output.system.push(note)
   },

package/src/plugin.mjs

@@ -1,6 +1,6 @@
 import { Plugin } from "@opencode/plugin"
-import { auditSkills, formatMarkdown } from "./audit.mjs"
-import { writeHtmlReport } from "./html.mjs"
+import { auditSkills, formatChat } from "./audit.mjs"
+import { postChatNotice, chatNoticeVisible } from "./notify.mjs"
 import { budgetWarning } from "./warning.mjs"
 import { loadConfig } from "./config.mjs"
 import { checkForUpdate, resolveMode, toolVersion } from "./self-update.mjs"
@@ -35,16 +35,12 @@ export default Plugin.define({
       editor.namespace({ name: "skills", description: "OpenCode skill diagnostics" })
       editor.add({
         name: "doctor",
-        description: "Audit installed agent skills (OpenCode, Claude Code, Grok, Cursor, Hermes, Kimi, DSH): shadowing, per-step token budget and fix hints",
+        description: "Audit installed agent skills and return a short briefing to say to the user in the chat. Does not write a file.",
         input: {
           type: "object",
           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,
         },
@@ -52,13 +48,8 @@ export default Plugin.define({
         execute: async (input) => {
           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" })
-          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 }
+          const audit = auditSkills({ cwd: directory, budget })
+          return { content: formatChat(audit) }
         },
       })
     })
@@ -66,25 +57,15 @@ export default Plugin.define({
     await ctx.command.transform((editor) => {
       editor.add({
         name: "skills-doctor",
-        description: "Audit local OpenCode skills",
-        execute: async ({ sessionID, prompt, delivery }) => {
-          await ctx.session.prompt({
-            ...prompt,
-            sessionID,
-            text: "Run a skills audit with the skills_doctor tool, then summarize the top issues and propose concrete fixes.",
-            delivery,
-          })
-        },
-      })
-      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,
+        description: "Tell the user about skill problems in this chat",
+        execute: async ({ sessionID }) => {
+          await postChatNotice({
             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,
+            cwd: ctx.location.directory,
+            synthetic: (input) => ctx.session.synthetic(input),
+            resume: true,
+            force: true,
+            when: "always",
           })
         },
       })
@@ -102,10 +83,32 @@ export default Plugin.define({
       })
     })
 
-    // 每个会话最多注入一次预算预警，避免刷屏
+    // 用户发消息时，把问题直接写进对话。resume 为 false，不额外叫醒模型。
+    // 没有 prompt hook 的旧宿主仍靠下面的 context 退路。
+    try {
+      await ctx.session.hook("prompt", async (event) => {
+        await postChatNotice({
+          sessionID: event.sessionID,
+          cwd: ctx.location.directory,
+          synthetic: (input) => ctx.session.synthetic(input),
+        })
+      })
+    } catch {
+      // 旧版本不认识这个 hook
+    }
+
+    // 通知已经出现在对话里时，不再把同一段话塞进系统提示。
+    // 老版本没有 synthetic 时，退回系统提示，让模型在回复里说出来。
     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 })
+      if (!chatNoticeVisible(ctx.location.directory, event.sessionID)) {
+        const warning = budgetWarning({ cwd: ctx.location.directory, sessionID: event.sessionID })
+        if (warning) {
+          event.system.push({
+            type: "text",
+            text: `Say this to the user in the chat. Do not write a file.\n\n${warning}`,
+          })
+        }
+      }
       const note = await updateNote({ directory: ctx.location.directory, sessionID: event.sessionID })
       if (note) event.system.push({ type: "text", text: note })
     })

package/src/warning.mjs

@@ -1,4 +1,4 @@
-import { auditSkills } from "./audit.mjs"
+import { auditSkills, formatChat } from "./audit.mjs"
 
 const cache = new Map()
 const warned = new Set()
@@ -15,12 +15,10 @@ export function budgetWarning({ cwd = process.cwd(), sessionID = "global", ttlMs
   let entry = cache.get(cwd)
   if (!entry || now - entry.at > ttlMs) {
     const audit = auditSkills({ cwd, includeGlobal })
-    const over = audit.counts.errors > 0
+    const notable = audit.findings.some((finding) => finding.severity === "error" || finding.severity === "warn")
     entry = {
       at: now,
-      text: over
-        ? `[skills-doctor] ${audit.summary.unique} skills use ~${audit.summary.advertisedTokens} tokens of descriptions per step (budget ${audit.budget}); ${audit.counts.errors} error(s), ${audit.counts.warnings} warning(s). Use the skills_doctor tool for details, then hide low-frequency skills with \`skills-doctor fix --hide <ids>\`.`
-        : null,
+      text: notable ? formatChat(audit) : null,
     }
     cache.set(cwd, entry)
   }

package/src/html.mjs

@@ -1,171 +0,0 @@
-import fs from "node:fs"
-import path from "node:path"
-import { spawn } from "node:child_process"
-import { planBudget } from "./plan.mjs"
-
-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 plan = planBudget(audit)
-  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"><div class="k">potential savings / step</div><div class="v">${plan.recommended.savings}</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>
-  <div class="sub">plan: trim ${plan.trim.count} + hide ${plan.recommended.hides.length} → ~${plan.recommended.final} tokens/step (saves ~${plan.recommended.savings}; ~${plan.recommended.stepsSavings} over ${plan.steps} steps)</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 {}
-}