opencode-skills-doctor 0.9.4 → 0.9.7

package/src/fix.mjs

@@ -96,11 +96,39 @@ export function applyFixes(plan, { dryRun = false } = {}) {
   return { moved, errors }
 }
 
-/** 在 frontmatter 里把 metadata.opencode/autoinvoke 设为 false。 */
+/** 先写临时文件再替换，避免隐藏 skill 时把 SKILL.md 写到一半。 */
+function writeFileAtomic(target, data) {
+  const tmp = `${target}.${process.pid}-${Math.random().toString(16).slice(2)}.tmp`
+  fs.writeFileSync(tmp, data)
+  try {
+    fs.renameSync(tmp, target)
+    return
+  } catch (err) {
+    // Windows refuses to rename onto an existing file (EPERM / EEXIST).
+    if (err?.code !== "EPERM" && err?.code !== "EEXIST") {
+      try {
+        fs.rmSync(tmp, { force: true })
+      } catch {}
+      throw err
+    }
+  }
+  try {
+    fs.copyFileSync(tmp, target)
+  } finally {
+    try {
+      fs.rmSync(tmp, { force: true })
+    } catch {}
+  }
+}
+
+/** 在 frontmatter 里把 metadata.opencode/autoinvoke 设为 false。保留原来的换行符。 */
 export function setAutoinvokeFalse(text) {
-  const lines = text.split(/\r?\n/)
+  const source = String(text ?? "")
+  const newline = source.includes("\r\n") ? "\r\n" : "\n"
+  const lines = source.split(/\r?\n/)
   const snippet = ["metadata:", "  opencode/autoinvoke: false"]
-  if (lines[0]?.trim() !== "---") return ["---", ...snippet, "---", ...lines].join("\n")
+  const join = (parts) => parts.join(newline)
+  if (lines[0]?.trim() !== "---") return join(["---", ...snippet, "---", ...lines])
 
   let end = -1
   for (let i = 1; i < lines.length; i++) {
@@ -109,12 +137,12 @@ export function setAutoinvokeFalse(text) {
       break
     }
   }
-  if (end === -1) return ["---", ...snippet, "---", ...lines].join("\n")
+  if (end === -1) return join(["---", ...snippet, "---", ...lines])
 
   const fm = lines.slice(1, end)
   const metaIdx = fm.findIndex((line) => /^metadata\s*:/.test(line.trim()))
   if (metaIdx === -1) {
-    return [lines[0], ...fm, ...snippet, ...lines.slice(end)].join("\n")
+    return join([lines[0], ...fm, ...snippet, ...lines.slice(end)])
   }
 
   const metaIndent = fm[metaIdx].length - fm[metaIdx].trimStart().length
@@ -131,7 +159,7 @@ export function setAutoinvokeFalse(text) {
   }
   if (!replaced) block.unshift(" ".repeat(metaIndent + 2) + "opencode/autoinvoke: false")
 
-  return [lines[0], ...fm.slice(0, metaIdx + 1), ...block, ...fm.slice(j), ...lines.slice(end)].join("\n")
+  return join([lines[0], ...fm.slice(0, metaIdx + 1), ...block, ...fm.slice(j), ...lines.slice(end)])
 }
 
 /**
@@ -154,7 +182,7 @@ export function hideSkills(skills, ids, { dryRun = false } = {}) {
     try {
       if (!dryRun) {
         const text = fs.readFileSync(skill.file, "utf8")
-        fs.writeFileSync(skill.file, setAutoinvokeFalse(text), "utf8")
+        writeFileAtomic(skill.file, setAutoinvokeFalse(text))
       }
       changed.push({ id, file: skill.file })
     } catch (err) {

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:",
@@ -193,7 +190,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
       'Both {flat} and {dir} exist in the same source (ID "{id}"), semantics are ambiguous',
     "lint.duplicateContent": "These skills have identical bodies: {ids}",
     "lint.nearDuplicate":
-      '"{a}" and "{b}" descriptions are {score}% similar; the model may pick the wrong one',
+      '"{a}" and "{b}" overlap {score}% on {terms}; the model may pick the wrong one',
     "lint.missingDescription":
       '"{id}" has no description, so the model will not discover it (only explicit @{id})',
     "lint.longDescription": '"{id}" description is {chars} chars; it is paid on every model step',
@@ -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": "建议:",
@@ -420,7 +414,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
       'ID "{id}" 有 {count} 处定义，实际生效的是 {winner}；其余 {losers} 处被遮蔽（白占体积、容易改错文件）',
     "lint.flatDirCollision": '同一来源同时存在 {flat} 与 {dir}（ID 都是 "{id}"），语义不明确',
     "lint.duplicateContent": "这些 skill 的正文完全相同：{ids}",
-    "lint.nearDuplicate": '"{a}" 与 "{b}" 的描述相似度 {score}%，模型容易选错',
+    "lint.nearDuplicate": '"{a}" 与 "{b}" 在 {terms} 上重叠 {score}%，模型容易选错',
     "lint.missingDescription": '"{id}" 没有 description，模型不会发现它（只能 @{id} 手动加载）',
     "lint.longDescription": '"{id}" 的 description 有 {chars} 字符，每个模型步骤都会占上下文',
     "lint.hiddenSkill": '"{id}" 被隐藏（autoinvoke/disable-model-invocation），不会出现在模型列表里',

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/lint.mjs

@@ -1,27 +1,36 @@
 import fs from "node:fs"
 import path from "node:path"
-import { estimateTokens } from "./parse.mjs"
+import { advertisedStepTokens, distinctiveTokenSet } from "./parse.mjs"
 import { extractReferences } from "./refs.mjs"
 import { translator } from "./i18n.mjs"
 
 export const SEVERITY_ORDER = { error: 0, warn: 1, info: 2 }
 
 const ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/
-const NEAR_DUPLICATE_THRESHOLD = 0.75
+const JACCARD_THRESHOLD = 0.72
+const CONTAINMENT_THRESHOLD = 0.85
+const MIN_SHARED = 3
+const MIN_SIZE_RATIO = 0.5
 
-function tokenSet(text) {
-  const tokens = String(text ?? "")
-    .toLowerCase()
-    .split(/[^\p{L}\p{N}]+/u)
-    .filter((t) => t.length >= 2)
-  return new Set(tokens)
-}
-
-function jaccard(a, b) {
-  if (!a.size || !b.size) return 0
-  let inter = 0
-  for (const t of a) if (b.has(t)) inter++
-  return inter / (a.size + b.size - inter)
+/** 两个描述有多容易让模型选错。套话已在 distinctiveTokenSet 里去掉。 */
+export function pairOverlap(a, b) {
+  if (!a?.size || !b?.size) return { jaccard: 0, containment: 0, shared: 0, terms: [] }
+  const small = a.size <= b.size ? a : b
+  const large = small === a ? b : a
+  let shared = 0
+  const terms = []
+  for (const token of small) {
+    if (!large.has(token)) continue
+    shared++
+    if (terms.length < 4) terms.push(token)
+  }
+  if (!shared) return { jaccard: 0, containment: 0, shared: 0, terms: [] }
+  return {
+    jaccard: shared / (a.size + b.size - shared),
+    containment: shared / small.size,
+    shared,
+    terms,
+  }
 }
 
 function byId(skills) {
@@ -48,6 +57,7 @@ export function resolveWinners(skills) {
 }
 
 export function lint(skills, options = {}) {
+  existsCache.clear()
   const t = options.t ?? translator("en")
   const budget = options.budget ?? 1200
   const staleDays = options.staleDays ?? 0
@@ -146,7 +156,7 @@ export function lint(skills, options = {}) {
       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 (!pathExists(target)) missingRefs.push(ref)
       }
       if (missingRefs.length) {
         add("broken-reference", "warn", t("lint.brokenReference", { id: skill.id, refs: missingRefs.slice(0, 5).join(", ") }), {
@@ -178,10 +188,7 @@ export function lint(skills, options = {}) {
   // 4) 上下文预算（只算会被模型看到的）
   const advertised = [...winners.values()].filter((s) => s.advertised)
   const described = advertised.filter((s) => s.description)
-  const advertisedTokens = described.reduce(
-    (sum, s) => sum + estimateTokens(`${s.id} ${s.displayName} ${s.description}`),
-    0,
-  )
+  const advertisedTokens = described.reduce((sum, s) => sum + advertisedStepTokens(s), 0)
 
   if (advertisedTokens > budget * 2) {
     add("token-budget", "error", t("lint.tokenBudgetError", { tokens: advertisedTokens, budget }), {
@@ -203,28 +210,34 @@ export function lint(skills, options = {}) {
     })
   }
 
-  // 5) 描述近似（token 集合只算一次；按大小升序后用 Jaccard 上界提前结束）
+  // 5) 描述近似：丢掉套话后看 Jaccard，以及短描述是否被长描述包含。
+  // 按特征数升序，|a|/|b| 低于 MIN_SIZE_RATIO 后不可能再达到任一门槛。
   const withDesc = described
-    .map((skill) => ({ skill, tokens: tokenSet(skill.description) }))
-    .filter((entry) => entry.tokens.size > 0)
-    .sort((x, y) => x.tokens.size - y.tokens.size)
+    .map((skill) => ({ skill, tokens: distinctiveTokenSet(skill.description) }))
+    .filter((entry) => entry.tokens.size >= MIN_SHARED)
+    .sort((x, y) => x.tokens.size - y.tokens.size || x.skill.id.localeCompare(y.skill.id))
   const pairs = []
   for (let i = 0; i < withDesc.length; i++) {
     const a = withDesc[i]
     for (let j = i + 1; j < withDesc.length; j++) {
       const b = withDesc[j]
       if (a.skill.id === b.skill.id) continue
-      // 大小升序：a 为空集已过滤，|a|/|b| 随 j 单调下降，低于阈值后再无可能命中。
-      if (a.tokens.size / b.tokens.size < NEAR_DUPLICATE_THRESHOLD) break
-      const score = jaccard(a.tokens, b.tokens)
-      if (score >= NEAR_DUPLICATE_THRESHOLD) pairs.push({ a: a.skill.id, b: b.skill.id, score })
+      if (a.tokens.size / b.tokens.size < MIN_SIZE_RATIO) break
+      const overlap = pairOverlap(a.tokens, b.tokens)
+      if (overlap.shared < MIN_SHARED) continue
+      const byJaccard = overlap.jaccard >= JACCARD_THRESHOLD
+      const byContainment = overlap.containment >= CONTAINMENT_THRESHOLD
+      if (!byJaccard && !byContainment) continue
+      const score = Math.max(overlap.jaccard, overlap.containment)
+      pairs.push({ a: a.skill.id, b: b.skill.id, score, terms: overlap.terms.join(", ") })
     }
   }
+  pairs.sort((x, y) => y.score - x.score || x.a.localeCompare(y.a))
   for (const pair of pairs.slice(0, 15)) {
     add(
       "near-duplicate-description",
       "warn",
-      t("lint.nearDuplicate", { a: pair.a, b: pair.b, score: (pair.score * 100).toFixed(0) }),
+      t("lint.nearDuplicate", { a: pair.a, b: pair.b, score: (pair.score * 100).toFixed(0), terms: pair.terms }),
       { skills: [pair.a, pair.b] },
     )
   }
@@ -234,6 +247,16 @@ export function lint(skills, options = {}) {
 
 const SEVERITIES = new Set(["error", "warn", "info"])
 
+const existsCache = new Map()
+
+function pathExists(target) {
+  const cached = existsCache.get(target)
+  if (cached !== undefined) return cached
+  const ok = fs.existsSync(target)
+  existsCache.set(target, ok)
+  return ok
+}
+
 function applyOverrides(findings, options) {
   const overrides = options.ruleOverrides ?? {}
   const ignore = new Set(options.ignore ?? [])
@@ -261,9 +284,7 @@ export function summarize(skills) {
     advertised: advertised.length,
     hidden: [...winners.values()].filter((s) => s.hidden).length,
     shadowed: skills.length - winners.size,
-    advertisedTokens: advertised
-      .filter((s) => s.description)
-      .reduce((sum, s) => sum + estimateTokens(`${s.id} ${s.displayName} ${s.description}`), 0),
+    advertisedTokens: advertised.filter((s) => s.description).reduce((sum, s) => sum + advertisedStepTokens(s), 0),
     bodyTokens: skills.reduce((sum, s) => sum + s.bodyTokens, 0),
   }
 }

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/parse.mjs

@@ -105,13 +105,100 @@ export function parseYamlLite(lines) {
 }
 
 const CJK_CHAR = /[\u2e80-\u9fff\uac00-\ud7af\uf900-\ufaff\uff00-\uffef]/
-const CJK_ALL = /[\u2e80-\u9fff\uac00-\ud7af\uf900-\ufaff\uff00-\uffef]/g
 
-/** 粗略 token 估算：CJK 约 1.7 字/token，其余约 4 字符/token。 */
+function isCjkUnit(code) {
+  return (
+    (code >= 0x2e80 && code <= 0x9fff) ||
+    (code >= 0xac00 && code <= 0xd7af) ||
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xff00 && code <= 0xffef)
+  )
+}
+
+function isAsciiWord(code) {
+  return (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122)
+}
+
+/** 一个英文词在 BPE 里通常是 1 个 token；超过 6 个字符后每 4 个字符再加 1。 */
+function latinWordTokens(length) {
+  if (length <= 6) return 1
+  return 1 + Math.ceil((length - 6) / 4)
+}
+
+/**
+ * 按词切分的 token 估算，比「字符数 / 4」接近模型的真实切法：
+ * - 空白不计
+ * - 每个 CJK 字符 1 token（Grok / Claude / GPT-4o 这一档）
+ * - 英文词 1 token 起，长词和长标识符按每 4 个额外字符加 1
+ * - 连字符会把标识符切开，标点各自计 1
+ */
 export function estimateTokens(text) {
   const str = String(text ?? "")
-  const cjk = (str.match(CJK_ALL) ?? []).length
-  return Math.ceil(cjk * 1.7 + (str.length - cjk) / 4)
+  let tokens = 0
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i)
+    if (code === 32 || code === 9 || code === 10 || code === 13) continue
+    if (isCjkUnit(code)) {
+      tokens++
+      continue
+    }
+    if (isAsciiWord(code)) {
+      let length = 0
+      while (i < str.length && isAsciiWord(str.charCodeAt(i))) {
+        length++
+        i++
+      }
+      i--
+      tokens += latinWordTokens(length)
+      continue
+    }
+    tokens++
+  }
+  return tokens
+}
+
+const STOPWORDS = new Set([
+  "a", "an", "the", "and", "or", "to", "of", "for", "in", "on", "with", "when", "use", "using", "used",
+  "this", "that", "skill", "skills", "user", "users", "want", "wants", "wanted", "please", "from", "into",
+  "by", "as", "is", "are", "be", "it", "its", "their", "your", "you", "if", "then", "than", "via", "over",
+  "about", "how", "what", "which", "can", "will", "just", "also", "not", "but", "at", "we", "our", "them",
+  "的", "了", "和", "与", "或", "在", "为", "用", "使用", "当", "技能", "用户", "一个", "进行", "可以", "这个", "以及", "把", "将", "对", "从",
+])
+
+/**
+ * 描述里真正用来路由的词。丢掉套话（use this skill when…）和过短的英文词。
+ * 中文没有空格，用相邻二字作为特征，避免整句变成一个 token。
+ */
+export function distinctiveTokenSet(text) {
+  const set = new Set()
+  const str = String(text ?? "").toLowerCase()
+  let prevCjk = ""
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i)
+    if (isCjkUnit(code)) {
+      const ch = str[i]
+      if (prevCjk && !STOPWORDS.has(prevCjk) && !STOPWORDS.has(ch)) set.add(prevCjk + ch)
+      prevCjk = STOPWORDS.has(ch) ? "" : ch
+      continue
+    }
+    prevCjk = ""
+    if (!isAsciiWord(code)) continue
+    let j = i
+    while (j < str.length && isAsciiWord(str.charCodeAt(j))) j++
+    const word = str.slice(i, j)
+    if (word.length >= 3 && !STOPWORDS.has(word)) set.add(word)
+    i = j - 1
+  }
+  return set
+}
+
+/**
+ * 一条会被展示给模型的 skill，每步付出的描述 token。
+ * 扫描时已经算过的 `stepTokens` 直接复用；description 被改写（例如精简预览）时重算。
+ */
+export function advertisedStepTokens(skill, description = skill?.description ?? "") {
+  if (skill && description === skill.description && Number.isFinite(skill.stepTokens)) return skill.stepTokens
+  return estimateTokens(`${skill?.id ?? ""} ${skill?.displayName ?? ""} ${description}`)
 }
 
 /** 终端显示宽度（CJK 记 2 列） */

package/src/plan.mjs

@@ -1,38 +1,64 @@
-import { estimateTokens } from "./parse.mjs"
+import { advertisedStepTokens, distinctiveTokenSet } 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}`)
+  return advertisedStepTokens(skill, description)
+}
+
+function firstSentenceEnd(value) {
+  const match = /[.!?。！？]/.exec(value)
+  return match ? match.index + 1 : -1
 }
 
 /**
- * 把 description 截到目标长度，优先在句子边界断开（中英文标点都算）。
- * 纯函数：相同输入永远得到相同输出，便于在报告里预览「如果这么改会省多少」。
+ * 目录里只需要路由用的第一句。第一句放得进上限就只留它；
+ * 第一句本身超长时，再在分句标点处断开，最后才按字符硬切。
+ * 纯函数：相同输入永远得到相同输出。
  */
 export function trimDescription(text, limit = DEFAULT_DESC_TARGET) {
-  const value = String(text ?? "")
+  const value = String(text ?? "").trim()
   if (value.length <= limit) return value
+  const sentenceEnd = firstSentenceEnd(value)
+  if (sentenceEnd > 0 && sentenceEnd <= limit) return value.slice(0, sentenceEnd).trim()
   const slice = value.slice(0, limit)
   const cut = Math.max(
-    slice.lastIndexOf("。"),
-    slice.lastIndexOf("."),
-    slice.lastIndexOf("！"),
-    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()
+  const trimmed = cut >= limit * 0.5 ? value.slice(0, cut).trim() : slice.trim()
   return trimmed || slice.trim()
 }
 
-/** 在候选中选「数量最少」的一组，使节省量 ≥ gap；按单项节省降序取前缀即为最优。 */
-function pickMinimal(items, gap) {
+/** 这条描述有多少已经被别的 skill 说过。1 = 触发词是别人的子集，0 = 完全独特。 */
+function redundancyOf(id, sets) {
+  const mine = sets.get(id)
+  if (!mine || mine.size < 3) return 0.35
+  let best = 0
+  for (const [other, tokens] of sets) {
+    if (other === id || !tokens?.size) continue
+    let shared = 0
+    for (const token of mine) if (tokens.has(token)) shared++
+    const covered = shared / mine.size
+    if (covered > best) best = covered
+  }
+  return best
+}
+
+/**
+ * 选一组隐藏项盖住缺口。排序不是「谁最贵藏谁」，而是节省 × 重复度：
+ * 触发词已经被别的 skill 覆盖的，优先藏；独特的留到最后。
+ */
+function pickPreserving(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 score = (item) => item.tokens * (0.15 + 0.85 * item.redundancy)
+  const sorted = [...items].sort((a, b) => score(b) - score(a) || a.id.localeCompare(b.id))
   const picked = []
   let savings = 0
   for (const item of sorted) {
@@ -49,8 +75,8 @@ function pickMinimal(items, gap) {
  * 规则：
  * - 只有会被「展示给模型」的定义才有成本；被遮蔽的重复定义省不出 token（诚实很重要）。
  * - 精简 description 不改变可发现性；隐藏（autoinvoke: false）省掉整条成本，但仍可用 @id 加载。
- * - 推荐方案先精简所有超长描述，再按「单项节省最大」贪心隐藏，直到进入预算。
- *   被隐藏的技能若也被精简过，其节省按原始成本计，不会重复计算。
+ * - 推荐方案先把超长描述收成第一句，再优先隐藏「触发词已经被别的 skill 覆盖」的条目。
+ *   被隐藏的技能若也被精简过，其节省按精简后的成本计，不会把同一份 token 算两次。
  */
 export function planBudget(
   audit,
@@ -86,23 +112,27 @@ export function planBudget(
   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 tokenSets = new Map(advertised.map((skill) => [skill.id, distinctiveTokenSet(skill.description)]))
+
+  // 2) 只隐藏（不精简）的方案。重复的先藏。
   const hideCandidates = advertised.map((skill) => ({
     id: skill.id,
     file: skill.file,
     tokens: costOf(skill),
+    redundancy: redundancyOf(skill.id, tokenSets),
   }))
-  const hideOnly = pickMinimal(hideCandidates, gap)
+  const hideOnly = pickPreserving(hideCandidates, gap)
 
-  // 3) 推荐方案：先精简，再在「精简后的成本」上隐藏
+  // 3) 推荐方案：先精简，再在「精简后的成本」上按重复度隐藏
   const afterTrim = advertised.map((skill) => ({
     id: skill.id,
     file: skill.file,
     tokens: trimMap.get(skill.id)?.cost ?? costOf(skill),
     originalTokens: costOf(skill),
+    redundancy: redundancyOf(skill.id, tokenSets),
   }))
   const postTrimTotal = afterTrim.reduce((sum, item) => sum + item.tokens, 0)
-  const recommendedHides = pickMinimal(afterTrim, Math.max(0, postTrimTotal - target))
+  const recommendedHides = pickPreserving(afterTrim, Math.max(0, postTrimTotal - target))
   const hideSavings = recommendedHides.savings
   const savings = trimSavings + hideSavings
   const final = Math.max(0, current - savings)