opencode-skills-doctor 0.4.1 → 0.5.0

package/README.md

@@ -20,9 +20,10 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills
 | **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`) |
+| **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 |
-| **Quality** | 49 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
+| **Quality** | 53 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
 
 ## Why
 
@@ -59,7 +60,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
@@ -102,6 +103,23 @@ skills-doctor check --html report.html --open
 
 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"*.
 
+### `plan` (how many tokens can I actually save?)
+
+```powershell
+skills-doctor plan
+skills-doctor plan --budget 800 --desc-target 160 --steps 200
+skills-doctor plan --json
+```
+
+It answers "how much can I cut, exactly?":
+
+- only **advertised** definitions cost tokens — archiving shadowed duplicates saves 0, and the plan says so instead of pretending;
+- **Option A** trims every description longer than `--desc-target` (default 160 chars, cut at sentence boundaries) and computes the exact saving;
+- **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.
+
 ### `scan`
 
 Lists every skill with its source, precedence, whether the model can see it, and token cost.
@@ -255,7 +273,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.
@@ -265,6 +283,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
@@ -467,13 +486,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.6: 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          # 53 tests (node test/doctor.test.mjs)
 npm run bench     # lint timing for 100/500/1000 skills
 ```
 

package/docs/README.zh-CN.md

@@ -20,9 +20,10 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | **能查** | 同 ID 遮蔽、重复、超长描述、超大正文、每步 token 预算、断链引用、非法 frontmatter、空正文、陈旧 skill |
 | **能修** | 归档遮蔽定义（可逆）、隐藏低频 skill、catalog 同步并检测 drift |
 | **报告** | 终端、JSON，或自包含 HTML（`--html [file] --open`） |
+| **规划** | 精确 token 节省：精简描述 / 隐藏 skill，按 N 步折算 |
 | **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
 | **要求** | Node ≥ 20，零运行时依赖 |
-| **质量** | 49 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
+| **质量** | 53 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
 ## 为什么需要它
 
@@ -59,7 +60,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 倍
@@ -102,6 +103,23 @@ skills-doctor check --html report.html --open
 
 插件和 MCP 工具同样接受 `html` 参数，所以可以让 agent 先问你要存哪里——例如：*"把报告存到 D:\reports\skills.html"*。
 
+### `plan`（到底能省多少 token？）
+
+```powershell
+skills-doctor plan
+skills-doctor plan --budget 800 --desc-target 160 --steps 200
+skills-doctor plan --json
+```
+
+回答「能省多少、怎么省」：
+
+- 只有**会展示给模型**的定义才花 token —— 归档遮蔽重复定义省 0，方案里会明说，不糊弄；
+- **方案 A**：把所有超过 `--desc-target`（默认 160 字符，按句子边界截断）的 description 精简，算出精确节省；
+- **方案 B**：用最少的隐藏数量把总量压进预算（仍可 `@id` 加载；按单项节省从大到小取，对「最少隐藏数」是最优的）；
+- **推荐方案**：先精简再隐藏，不重复计算，并按 `--steps`（默认 100）折算总节省。
+
+超预算时 `check` 会打印一行提示，HTML 报告里有同样的「potential savings」卡片。
+
 ### `scan`
 
 列出所有 skill 及其来源、优先级、是否会被模型看到、token 占用。
@@ -255,7 +273,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` 跳过装包。
@@ -265,6 +283,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 描述预算超标时，系统提示里会注入一次提醒（每个会话最多一次）。
 
 ### 卸载
@@ -467,13 +486,13 @@ token 是启发式估算，1200 是建议预算。可以用 `--budget` 或 `.ski
 
 ## Roadmap
 
-- v0.4：内容层面的建议（哪些 skill 从未被使用）、catalog 签名校验
+- v0.6：CI 治理（baseline 只报新增问题、官方 GitHub Action）、内容层建议（哪些 skill 从未被使用）、catalog 签名校验
 - 后续：V1/Claude skill 兼容迁移报告
 
 ## 开发与贡献
 
 ```powershell
-npm test          # 41 个测试（node test/doctor.test.mjs）
+npm test          # 53 个测试（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.1",
+  "version": "0.5.0",
   "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,7 @@ import { loadConfig } from "./config.mjs"
 import { startMcpServer } from "./mcp.mjs"
 import { installOpenCode, uninstallOpenCode } from "./install.mjs"
 import { writeHtmlReport, openReport } from "./html.mjs"
+import { planBudget } from "./plan.mjs"
 import {
   checkForUpdate,
   resolveMode,
@@ -76,12 +77,14 @@ function parseArgs(argv) {
     open: false,
     apply: false,
     updateCheck: true,
+    descTarget: 160,
+    steps: 100,
     help: false,
     version: false,
   }
 
   const args = [...argv]
-  const commands = new Set(["check", "scan", "update", "fix", "install", "uninstall", "upgrade", "mcp", "help"])
+  const commands = new Set(["check", "scan", "plan", "update", "fix", "install", "uninstall", "upgrade", "mcp", "help"])
   if (args[0] && commands.has(args[0])) {
     options.command = args.shift()
   }
@@ -101,6 +104,12 @@ function parseArgs(argv) {
       case "--stale-days":
         options.staleDays = Number(args[++i])
         break
+      case "--desc-target":
+        options.descTarget = Number(args[++i])
+        break
+      case "--steps":
+        options.steps = Number(args[++i])
+        break
       case "--strict":
         options.strict = true
         break
@@ -279,6 +288,92 @@ function printCheck(audit, result, options, t) {
     console.log(bold(t("check.hints")))
     for (const rule of usedRules) console.log(dim(`  - ${t(HINT_KEYS[rule])}`))
   }
+
+  if (audit.summary.advertisedTokens > audit.budget) {
+    const plan = planBudget(audit)
+    if (plan.recommended.savings > 0) {
+      console.log("")
+      console.log(yellow(t("check.planHint", { tokens: plan.recommended.savings })))
+    }
+  }
+}
+
+function printPlan(plan, t) {
+  console.log(bold(t("plan.title")))
+  console.log(dim(t("plan.current", { tokens: plan.current, count: plan.advertised })))
+  console.log(dim(t("plan.budget", { budget: plan.budget, gap: plan.gap })))
+  console.log(dim(t("plan.steps", { steps: plan.steps })))
+  console.log("")
+
+  const sessionLine = (savings) => {
+    if (plan.steps > 0 && savings > 0) console.log(dim(t("plan.session", { tokens: savings * plan.steps, steps: plan.steps })))
+  }
+
+  if (plan.current <= plan.budget) {
+    console.log(green(t("plan.under")))
+    if (plan.trim.count) {
+      console.log("")
+      console.log(bold(t("plan.trimTitle", { chars: plan.descTarget })))
+      console.log(
+        t("plan.trimLine", {
+          count: plan.trim.count,
+          savings: plan.trim.savings,
+          final: Math.max(0, plan.current - plan.trim.savings),
+        }),
+      )
+      sessionLine(plan.trim.savings)
+    }
+    return
+  }
+
+  console.log(bold(t("plan.trimTitle", { chars: plan.descTarget })))
+  if (plan.trim.count) {
+    console.log(
+      t("plan.trimLine", {
+        count: plan.trim.count,
+        savings: plan.trim.savings,
+        final: Math.max(0, plan.current - plan.trim.savings),
+      }),
+    )
+    for (const item of plan.trim.items.slice(0, 10)) {
+      console.log(dim(t("plan.trimItem", { id: item.id, saving: item.saving })))
+    }
+    if (plan.trim.items.length > 10) console.log(dim(t("plan.more", { count: plan.trim.items.length - 10 })))
+  } else {
+    console.log(dim(t("plan.trimNone")))
+  }
+  console.log("")
+
+  console.log(bold(t("plan.hideTitle")))
+  if (plan.hideOnly.count) {
+    console.log(
+      t("plan.hideLine", {
+        count: plan.hideOnly.count,
+        savings: plan.hideOnly.savings,
+        final: plan.hideOnly.final,
+      }),
+    )
+  } else {
+    console.log(dim(t("plan.hideNone")))
+  }
+  console.log("")
+
+  console.log(bold(t("plan.recTitle")))
+  console.log(
+    t("plan.recLine", {
+      trims: plan.trim.count,
+      hides: plan.recommended.hides.length,
+      final: plan.recommended.final,
+      savings: plan.recommended.savings,
+    }),
+  )
+  for (const item of plan.recommended.hides) {
+    console.log(dim(t("plan.hideItem", { id: item.id, tokens: item.tokens })))
+  }
+  if (plan.recommended.hidesEverything) console.log(yellow(t("plan.hidesAll")))
+  sessionLine(plan.recommended.savings)
+  console.log("")
+  console.log(dim(t("plan.next")))
 }
 
 function printScan(discovered, options, managed, t) {
@@ -592,6 +687,21 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "plan") {
+    const audit = auditSkills({
+      cwd,
+      includeGlobal: options.global,
+      lang,
+      configPath: options.config,
+      budget: options.budget,
+      staleDays: options.staleDays,
+    })
+    const plan = planBudget(audit, { descTarget: options.descTarget, steps: options.steps })
+    if (options.json) console.log(JSON.stringify(plan, null, 2))
+    else printPlan(plan, t)
+    return
+  }
+
   if (options.command === "check") {
     const audit = auditSkills({
       cwd,

package/src/html.mjs

@@ -1,6 +1,7 @@
 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])
@@ -13,6 +14,7 @@ export function renderHtml(audit, { title = "skills-doctor report", now = new Da
   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"
@@ -89,6 +91,7 @@ export function renderHtml(audit, { title = "skills-doctor report", now = new Da
     <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>
@@ -97,6 +100,7 @@ export function renderHtml(audit, { title = "skills-doctor report", now = new Da
   <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">

package/src/i18n.mjs

@@ -7,6 +7,7 @@ const dict = {
 
 Usage:
   skills-doctor check  [options]   check sources, conflicts and context budget (default)
+  skills-doctor plan   [options]   estimate how many tokens you can save, and how
   skills-doctor scan   [options]   list every skill with its source and precedence
   skills-doctor fix    [options]   archive shadowed definitions (safe structural fixes)
   skills-doctor update [options]   compare and download skills from HTTP catalogs
@@ -19,6 +20,8 @@ Options:
   --root <dir>         working directory (default: current directory)
   --no-global          skip ~/.claude, ~/.agents and ~/.config/opencode
   --budget <n>         tokens allowed for advertised descriptions (default 1200)
+  --desc-target <n>    plan: target description length in chars (default 160)
+  --steps <n>          plan: project savings over n model steps (default 100)
   --stale-days <n>     report skills not updated in n days (default: off)
   --strict             exit non-zero on warnings too
   --json               print JSON
@@ -56,6 +59,27 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "check.summary": "{errors} error, {warnings} warn, {infos} info",
     "check.strict": " (--strict: warnings also fail)",
     "check.hints": "Hints:",
+    "check.planHint": "  ! potential: about {tokens} tokens/step can be saved; run `skills-doctor plan` for the breakdown",
+
+    "plan.title": "skills-doctor plan",
+    "plan.current": "  current: ~{tokens} tokens/step ({count} advertised skills)",
+    "plan.budget": "  budget: {budget}  gap: {gap}",
+    "plan.steps": "  projection: {steps} model steps",
+    "plan.under": "Under budget — no changes needed.",
+    "plan.trimTitle": "Option A — trim descriptions to {chars} chars (stays discoverable)",
+    "plan.trimLine": "  {count} skills, saves ~{savings} tokens/step → ~{final} tokens",
+    "plan.trimNone": "  nothing to trim.",
+    "plan.trimItem": "    - {id} (−{saving})",
+    "plan.hideTitle": "Option B — hide skills (autoinvoke: false, still loadable with @id)",
+    "plan.hideLine": "  hide {count} skills, saves ~{savings} tokens/step → ~{final} tokens",
+    "plan.hideNone": "  no hide needed.",
+    "plan.recTitle": "Recommended",
+    "plan.recLine": "  trim {trims} + hide {hides} → ~{final} tokens/step (saves ~{savings})",
+    "plan.hideItem": "    - hide {id} (−{tokens})",
+    "plan.hidesAll": "  ! this would hide every skill; consider raising the budget instead.",
+    "plan.session": "  over {steps} steps that saves ~{tokens} tokens",
+    "plan.more": "    …and {count} more",
+    "plan.next": "Next: hide with `skills-doctor fix --hide <ids>`, or trim descriptions and keep discoverability.",
 
     "scan.title": "skills-doctor {version} — scan",
     "scan.workdir": "  working dir: {dir}",
@@ -192,6 +216,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
 
 用法:
   skills-doctor check  [选项]   检查来源、冲突与上下文预算（默认命令）
+  skills-doctor plan   [选项]   估算能省多少 token、怎么省
   skills-doctor scan   [选项]   列出所有 skill 及其来源/优先级
   skills-doctor fix    [选项]   归档被遮蔽的定义（安全的结构性修复）
   skills-doctor update [选项]   对比并拉取 HTTP catalog 里的 skill
@@ -204,6 +229,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --root <dir>        以该目录为工作目录（默认当前目录）
   --no-global         不扫描 ~/.claude、~/.agents、~/.config/opencode
   --budget <n>        模型每步可看的 description token 预算（默认 1200）
+  --desc-target <n>   plan: description 目标字符数（默认 160）
+  --steps <n>         plan: 按 n 个模型步骤折算节省量（默认 100）
   --stale-days <n>    超过 n 天未更新的 skill 给出提示（默认关闭）
   --strict            有 warning 也返回非 0
   --json              输出 JSON
@@ -241,6 +268,27 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "check.summary": "{errors} error, {warnings} warn, {infos} info",
     "check.strict": "（--strict：warning 也会非 0 退出）",
     "check.hints": "建议:",
+    "check.planHint": "  ! 预计每步还能省约 {tokens} tokens；运行 `skills-doctor plan` 看具体方案",
+
+    "plan.title": "skills-doctor 省 token 方案",
+    "plan.current": "  当前: 约 {tokens} tokens/步（{count} 个会展示的 skill）",
+    "plan.budget": "  预算: {budget}  差距: {gap}",
+    "plan.steps": "  折算: {steps} 个模型步骤",
+    "plan.under": "已在预算内，无需改动。",
+    "plan.trimTitle": "方案 A —— 精简 description 到 {chars} 字符（仍可被发现）",
+    "plan.trimLine": "  {count} 个 skill，每步省约 {savings} tokens → 约 {final} tokens",
+    "plan.trimNone": "  没有需要精简的。",
+    "plan.trimItem": "    - {id}（−{saving}）",
+    "plan.hideTitle": "方案 B —— 隐藏 skill（autoinvoke: false，仍可 @id 加载）",
+    "plan.hideLine": "  隐藏 {count} 个，每步省约 {savings} tokens → 约 {final} tokens",
+    "plan.hideNone": "  无需隐藏。",
+    "plan.recTitle": "推荐方案",
+    "plan.recLine": "  精简 {trims} 个 + 隐藏 {hides} 个 → 约 {final} tokens/步（省约 {savings}）",
+    "plan.hideItem": "    - 隐藏 {id}（−{tokens}）",
+    "plan.hidesAll": "  ! 这样会把所有 skill 都隐藏；建议改为提高预算。",
+    "plan.session": "  按 {steps} 步计算，共省约 {tokens} tokens",
+    "plan.more": "    …还有 {count} 个",
+    "plan.next": "下一步：用 `skills-doctor fix --hide <ids>` 隐藏，或精简 description 保留可发现性。",
 
     "scan.title": "skills-doctor {version} — scan",
     "scan.workdir": "  工作目录: {dir}",

package/src/plan.mjs

@@ -0,0 +1,142 @@
+import { estimateTokens } from "./parse.mjs"
+import { resolveWinners } from "./lint.mjs"
+
+export const DEFAULT_DESC_TARGET = 160
+export const DEFAULT_STEPS = 100
+
+function costOf(skill, description = skill.description) {
+  return estimateTokens(`${skill.id} ${skill.displayName} ${description}`)
+}
+
+/**
+ * 把 description 截到目标长度，优先在句子边界断开（中英文标点都算）。
+ * 纯函数：相同输入永远得到相同输出，便于在报告里预览「如果这么改会省多少」。
+ */
+export function trimDescription(text, limit = DEFAULT_DESC_TARGET) {
+  const value = String(text ?? "")
+  if (value.length <= limit) return value
+  const slice = value.slice(0, limit)
+  const cut = Math.max(
+    slice.lastIndexOf("。"),
+    slice.lastIndexOf("."),
+    slice.lastIndexOf("！"),
+    slice.lastIndexOf("？"),
+    slice.lastIndexOf("；"),
+    slice.lastIndexOf(";"),
+    slice.lastIndexOf("\n"),
+  )
+  const trimmed = cut >= limit * 0.5 ? value.slice(0, cut + 1).trim() : slice.trim()
+  return trimmed || slice.trim()
+}
+
+/** 在候选中选「数量最少」的一组，使节省量 ≥ gap；按单项节省降序取前缀即为最优。 */
+function pickMinimal(items, gap) {
+  if (gap <= 0) return { count: 0, savings: 0, items: [], enough: true }
+  const sorted = [...items].sort((a, b) => b.tokens - a.tokens || a.id.localeCompare(b.id))
+  const picked = []
+  let savings = 0
+  for (const item of sorted) {
+    if (savings >= gap) break
+    picked.push(item)
+    savings += item.tokens
+  }
+  return { count: picked.length, savings, items: picked, enough: savings >= gap }
+}
+
+/**
+ * 预算规划：当前每步消耗多少、精简到多少、隐藏多少、最终能省多少。
+ *
+ * 规则：
+ * - 只有会被「展示给模型」的定义才有成本；被遮蔽的重复定义省不出 token（诚实很重要）。
+ * - 精简 description 不改变可发现性；隐藏（autoinvoke: false）省掉整条成本，但仍可用 @id 加载。
+ * - 推荐方案先精简所有超长描述，再按「单项节省最大」贪心隐藏，直到进入预算。
+ *   被隐藏的技能若也被精简过，其节省按原始成本计，不会重复计算。
+ */
+export function planBudget(
+  audit,
+  { budget = audit.budget, descTarget = DEFAULT_DESC_TARGET, steps = DEFAULT_STEPS } = {},
+) {
+  const target = Number.isFinite(budget) && budget > 0 ? budget : audit.budget
+  const winners = [...resolveWinners(audit.skills).values()]
+  const advertised = winners.filter((skill) => skill.advertised)
+
+  const current = advertised.reduce((sum, skill) => sum + costOf(skill), 0)
+  const gap = Math.max(0, current - target)
+
+  // 1) 精简：所有 description 超过目标的，按句子边界截断
+  const trimMap = new Map()
+  const trims = []
+  for (const skill of advertised) {
+    if (skill.description.length <= descTarget) continue
+    const preview = trimDescription(skill.description, descTarget)
+    const before = costOf(skill)
+    const after = costOf(skill, preview)
+    const saving = Math.max(0, before - after)
+    if (!saving) continue
+    trimMap.set(skill.id, { preview, cost: after })
+    trims.push({
+      id: skill.id,
+      file: skill.file,
+      before,
+      after,
+      saving,
+      preview,
+    })
+  }
+  trims.sort((a, b) => b.saving - a.saving || a.id.localeCompare(b.id))
+  const trimSavings = trims.reduce((sum, item) => sum + item.saving, 0)
+
+  // 2) 只隐藏（不精简）的方案
+  const hideCandidates = advertised.map((skill) => ({
+    id: skill.id,
+    file: skill.file,
+    tokens: costOf(skill),
+  }))
+  const hideOnly = pickMinimal(hideCandidates, gap)
+
+  // 3) 推荐方案：先精简，再在「精简后的成本」上隐藏
+  const afterTrim = advertised.map((skill) => ({
+    id: skill.id,
+    file: skill.file,
+    tokens: trimMap.get(skill.id)?.cost ?? costOf(skill),
+    originalTokens: costOf(skill),
+  }))
+  const postTrimTotal = afterTrim.reduce((sum, item) => sum + item.tokens, 0)
+  const recommendedHides = pickMinimal(afterTrim, Math.max(0, postTrimTotal - target))
+  const hideSavings = recommendedHides.savings
+  const savings = trimSavings + hideSavings
+  const final = Math.max(0, current - savings)
+
+  return {
+    cwd: audit.cwd,
+    budget: target,
+    descTarget,
+    steps,
+    current,
+    gap,
+    advertised: advertised.length,
+    trim: {
+      count: trims.length,
+      savings: trimSavings,
+      items: trims,
+    },
+    hideOnly: {
+      count: hideOnly.count,
+      savings: hideOnly.savings,
+      final: Math.max(0, current - hideOnly.savings),
+      enough: hideOnly.enough,
+      items: hideOnly.items,
+    },
+    recommended: {
+      trims: trims.map((item) => item.id),
+      hides: recommendedHides.items,
+      trimSavings,
+      hideSavings,
+      savings,
+      final,
+      reachable: final <= target,
+      stepsSavings: savings * steps,
+      hidesEverything: advertised.length > 0 && recommendedHides.count === advertised.length,
+    },
+  }
+}