opencode-skills-doctor 0.6.0 → 0.6.1

package/README.md

@@ -23,7 +23,7 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills
 | **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** | 57 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
+| **Quality** | 58 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
 
 ## Why
 
@@ -348,22 +348,23 @@ One command installs both the MCP tool and a skill that tells the model when to
 npx -y opencode-skills-doctor install --client dsh
 ```
 
-It locates `~/.dsh/profiles/<profile>/cordis.patch.yml` (default `desktop`; otherwise `--profile <name>`), appends the `mcp-skills-doctor` entry idempotently, and copies the `skills-doctor-audit` skill into `~/.dsh/skills/`. Restart DSH to load the MCP tool; the skill is watched and appears without a restart.
+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`;
 - `uninstall --client dsh` removes both the patch entry and the skill;
 - `--dsh-home <dir>` for a non-standard DSH home.
 
-Manual fallback — add this to the profile patch yourself:
+Manual fallback — DSH patches add new entries under `insert`, so append this block:
 
 ```yaml
-- id: mcp-skills-doctor
-  name: "@deepseek-ai/dsh-mcp-client"
-  config:
-    serverName: skills_doctor
-    transport: stdio
-    command: npx
-    args: ["-y", "opencode-skills-doctor", "mcp"]
+- insert:
+    - id: mcp-skills-doctor
+      name: "@deepseek-ai/dsh-mcp-client"
+      config:
+        serverName: skills_doctor
+        transport: stdio
+        command: npx
+        args: ["-y", "opencode-skills-doctor", "mcp"]
 ```
 
 On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`.
@@ -517,7 +518,7 @@ Executing code is free, but the tool definition is part of the model's context.
 ## Development and contributing
 
 ```powershell
-npm test          # 57 tests (node test/doctor.test.mjs)
+npm test          # 58 tests (node test/doctor.test.mjs)
 npm run bench     # lint timing for 100/500/1000 skills
 ```
 

package/docs/README.zh-CN.md

@@ -23,7 +23,7 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | **规划** | 精确 token 节省：精简描述 / 隐藏 skill，按 N 步折算 |
 | **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
 | **要求** | Node ≥ 20，零运行时依赖 |
-| **质量** | 57 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
+| **质量** | 58 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
 ## 为什么需要它
 
@@ -348,22 +348,23 @@ args = ["-y", "opencode-skills-doctor", "mcp"]
 npx -y opencode-skills-doctor install --client dsh
 ```
 
-它会找到 `~/.dsh/profiles/<profile>/cordis.patch.yml`（默认 `desktop`，否则用 `--profile <name>`），幂等地追加 `mcp-skills-doctor` 条目，并把 `skills-doctor-audit` 技能复制到 `~/.dsh/skills/`。重启 DSH 加载 MCP 工具；skill 目录有监听，无需重启。
+它会找到 `~/.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`；
 - `uninstall --client dsh` 同时移除配置条目和 skill；
 - `--dsh-home <dir>` 用于非默认的 DSH 主目录。
 
-手动兜底 —— 自己往 profile patch 里加：
+手动兜底 —— DSH 的 patch 里新增条目必须放在 `insert` 下，追加这一块：
 
 ```yaml
-- id: mcp-skills-doctor
-  name: "@deepseek-ai/dsh-mcp-client"
-  config:
-    serverName: skills_doctor
-    transport: stdio
-    command: npx
-    args: ["-y", "opencode-skills-doctor", "mcp"]
+- insert:
+    - id: mcp-skills-doctor
+      name: "@deepseek-ai/dsh-mcp-client"
+      config:
+        serverName: skills_doctor
+        transport: stdio
+        command: npx
+        args: ["-y", "opencode-skills-doctor", "mcp"]
 ```
 
 Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`。
@@ -517,7 +518,7 @@ token 是启发式估算，1200 是建议预算。可以用 `--budget` 或 `.ski
 ## 开发与贡献
 
 ```powershell
-npm test          # 57 个测试（node test/doctor.test.mjs）
+npm test          # 58 个测试（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.6.0",
+  "version": "0.6.1",
   "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 and DeepSeek Harness.",
   "type": "module",
   "exports": {

package/src/dsh.mjs

@@ -7,13 +7,16 @@ export const ENTRY_ID = "mcp-skills-doctor"
 export const SERVER_NAME = "skills_doctor"
 export const SKILL_NAME = "skills-doctor-audit"
 
-const ENTRIES = `- id: ${ENTRY_ID}
-  name: "@deepseek-ai/dsh-mcp-client"
-  config:
-    serverName: ${SERVER_NAME}
-    transport: stdio
-    command: npx
-    args: ["-y", "opencode-skills-doctor", "mcp"]
+// DSH 的 cordis.patch.yml 是 patch 列表：新增条目必须放在 insert 下，
+// 裸条目会被当成「覆盖不存在的 id」而跳过。
+const INSERT_BLOCK = `- insert:
+    - id: ${ENTRY_ID}
+      name: "@deepseek-ai/dsh-mcp-client"
+      config:
+        serverName: ${SERVER_NAME}
+        transport: stdio
+        command: npx
+        args: ["-y", "opencode-skills-doctor", "mcp"]
 `
 
 export function dshHome(env = process.env) {
@@ -56,76 +59,136 @@ function skillSourceDir() {
   return fileURLToPath(new URL("../skills/dsh-skills-doctor", import.meta.url))
 }
 
-function copySkill(source, target, dryRun, act, dry) {
-  if (!fs.existsSync(source)) return false
-  const file = path.join(source, "SKILL.md")
-  if (!fs.existsSync(file)) return false
-  const targetFile = path.join(target, "SKILL.md")
-  if (fs.existsSync(targetFile) && fs.readFileSync(targetFile, "utf8") === fs.readFileSync(file, "utf8")) {
-    act(`skill already up to date ${target}`)
-    return true
+function indentOf(line) {
+  return (line.match(/^[ \t]*/) ?? [""])[0].length
+}
+
+function blockEnd(lines, start) {
+  let end = start + 1
+  while (end < lines.length) {
+    const line = lines[end]
+    if (line.trim() === "" || indentOf(line) > 0) end++
+    else break
   }
-  if (dryRun) {
-    dry(`install skill ${SKILL_NAME} into ${target}`)
-    return true
+  return end
+}
+
+/** 找到包含我们 id 的 insert 块，或旧版裸条目。 */
+function findEntry(lines, id) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (indentOf(line) === 0 && /^-\s*insert:\s*$/.test(line)) {
+      const end = blockEnd(lines, i)
+      const block = lines.slice(i, end).join("\n")
+      if (block.includes(id)) return { type: "insert", start: i, end }
+      i = end - 1
+      continue
+    }
+    if (indentOf(line) === 0 && line.trim() === `- id: ${id}`) {
+      return { type: "legacy", start: i, end: blockEnd(lines, i) }
+    }
   }
-  fs.mkdirSync(target, { recursive: true })
-  fs.copyFileSync(file, targetFile)
-  act(`wrote skill ${targetFile}`)
-  return true
+  return null
+}
+
+function removeEntryBlock(text, id) {
+  const lines = text.split(/\r?\n/)
+  const found = findEntry(lines, id)
+  if (!found) return { text, changed: false, type: null }
+
+  if (found.type === "insert") {
+    const block = lines.slice(found.start, found.end)
+    const rows = block.filter((line) => /^\s+- id:/.test(line))
+    if (rows.length > 1) {
+      // insert 块里还有别人的条目：只摘掉我们这一行及其子行
+      const rowIndex = block.findIndex((line) => line.trim() === `- id: ${id}`)
+      let rowEnd = rowIndex + 1
+      while (
+        rowEnd < block.length &&
+        (block[rowEnd].trim() === "" || indentOf(block[rowEnd]) > indentOf(block[rowIndex]))
+      ) {
+        rowEnd++
+      }
+      const kept = [...lines.slice(0, found.start), ...block.slice(0, rowIndex), ...block.slice(rowEnd), ...lines.slice(found.end)]
+      return { text: kept.join("\n"), changed: true, type: "insert-row" }
+    }
+  }
+
+  const kept = [...lines.slice(0, found.start), ...lines.slice(found.end)]
+  return { text: kept.join("\n"), changed: true, type: found.type }
+}
+
+function appendInsert(text) {
+  const header = text.trim() ? (text.endsWith("\n") ? "\n" : "\n\n") : ""
+  return `${text}${header}${INSERT_BLOCK}`
 }
 
-/** 在 cordis.patch.yml 里追加 MCP 条目（幂等）。 */
-function appendEntry(patchFile, dryRun, act, dry) {
+function ensureEntry(patchFile, dryRun, act, dry) {
   const existing = fs.existsSync(patchFile) ? fs.readFileSync(patchFile, "utf8") : ""
-  if (existing.includes(ENTRY_ID) || existing.includes(`serverName: ${SERVER_NAME}`)) {
-    act(`MCP entry already present in ${patchFile}`)
+  const lines = existing.split(/\r?\n/)
+  const found = findEntry(lines, ENTRY_ID)
+
+  if (found && found.type === "insert") {
+    act(`MCP insert entry already present in ${patchFile}`)
     return false
   }
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+
+  let next = existing
+  if (found && found.type === "legacy") {
+    next = removeEntryBlock(existing, ENTRY_ID).text
+    act(`migrating legacy patch row in ${patchFile}`)
+  }
+  next = appendInsert(next)
+
   if (dryRun) {
-    dry(`append ${ENTRY_ID} to ${patchFile}`)
+    dry(`write ${ENTRY_ID} insert block to ${patchFile}`)
     return true
   }
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-")
   if (existing) fs.copyFileSync(patchFile, `${patchFile}.bak-${stamp}`)
-  const header = existing
-    ? (existing.endsWith("\n") ? "" : "\n")
-    : "# DSH profile patch layer\n"
-  const next = `${existing}${header}${existing.trim() ? "\n" : ""}${ENTRIES}`
   fs.writeFileSync(patchFile, next, "utf8")
-  act(`appended ${ENTRY_ID} to ${patchFile}`)
+  act(`wrote ${ENTRY_ID} insert block to ${patchFile}`)
   return true
 }
 
 function removeEntry(patchFile, dryRun, act, dry) {
   if (!fs.existsSync(patchFile)) return false
   const text = fs.readFileSync(patchFile, "utf8")
-  const lines = text.split(/\r?\n/)
-  const index = lines.findIndex((line) => line.trim() === `- id: ${ENTRY_ID}`)
-  if (index < 0) return false
-
-  let end = index + 1
-  while (end < lines.length) {
-    const line = lines[end]
-    if (line.trim() === "" || /^[ \t]/.test(line)) end++
-    else break
-  }
+  const result = removeEntryBlock(text, ENTRY_ID)
+  if (!result.changed) return false
   if (dryRun) {
     dry(`remove ${ENTRY_ID} from ${patchFile}`)
     return true
   }
   const stamp = new Date().toISOString().replace(/[:.]/g, "-")
   fs.copyFileSync(patchFile, `${patchFile}.bak-${stamp}`)
-  fs.writeFileSync(patchFile, lines.slice(0, index).concat(lines.slice(end)).join("\n"), "utf8")
+  fs.writeFileSync(patchFile, result.text, "utf8")
   act(`removed ${ENTRY_ID} from ${patchFile}`)
   return true
 }
 
+function copySkill(source, target, dryRun, act, dry) {
+  const file = path.join(source, "SKILL.md")
+  if (!fs.existsSync(file)) return false
+  const targetFile = path.join(target, "SKILL.md")
+  if (fs.existsSync(targetFile) && fs.readFileSync(targetFile, "utf8") === fs.readFileSync(file, "utf8")) {
+    act(`skill already up to date ${target}`)
+    return true
+  }
+  if (dryRun) {
+    dry(`install skill ${SKILL_NAME} into ${target}`)
+    return true
+  }
+  fs.mkdirSync(target, { recursive: true })
+  fs.copyFileSync(file, targetFile)
+  act(`wrote skill ${targetFile}`)
+  return true
+}
+
 function removeSkill(target, dryRun, act, dry) {
   const file = path.join(target, "SKILL.md")
   if (!fs.existsSync(file)) return false
-  const text = fs.readFileSync(file, "utf8")
-  if (!text.includes("Skill audit workflow")) {
+  if (!fs.readFileSync(file, "utf8").includes("Skill audit workflow")) {
     act(`kept ${target} (not the generated skill)`)
     return false
   }
@@ -157,7 +220,7 @@ export function installDsh({ home = dshHome(), profile = null, dryRun = false }
   if (dryRun) dry(`profile: ${picked.profile} (${dir})`)
   else act(`profile: ${picked.profile}`)
 
-  appendEntry(patchFile, dryRun, act, dry)
+  ensureEntry(patchFile, dryRun, act, dry)
   copySkill(skillSourceDir(), skillDir, dryRun, act, dry)
 
   return { ok: errors.length === 0, home, profile: picked.profile, patchFile, skillDir, actions, errors, dryRun }

package/src/i18n.mjs

@@ -127,7 +127,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "dsh.profile": "  profile: {profile}",
     "dsh.patch": "  patch: {file}",
     "dsh.skill": "  skill: {dir}",
-    "dsh.restart": "Restart DSH to load the MCP tool (the skill updates live).",
+    "dsh.restart": "Restart DSH to load the MCP tool (HMR reloads the patch when enabled; the skill updates live).",
     "dsh.failed": "DSH integration failed.",
     "update.toolAvailable":
       "  ! skills-doctor {latest} is available (you have {current}); update with: {cmd}  ·  {url}",
@@ -348,7 +348,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "dsh.profile": "  profile: {profile}",
     "dsh.patch": "  patch: {file}",
     "dsh.skill": "  skill: {dir}",
-    "dsh.restart": "重启 DSH 加载 MCP 工具（skill 会即时更新）。",
+    "dsh.restart": "重启 DSH 加载 MCP 工具（启用 HMR 时会自动重载 patch；skill 即时更新）。",
     "dsh.failed": "DSH 集成失败。",
     "update.toolAvailable": "  ! skills-doctor 有新版本 {latest}（当前 {current}）；更新：{cmd}  ·  {url}",
     "upgrade.title": "skills-doctor 自更新",