opencode-skills-doctor 0.0.0-stage → 0.3.0

package/src/catalog.mjs

@@ -0,0 +1,166 @@
+import fs from "node:fs"
+import path from "node:path"
+import { createHash } from "node:crypto"
+import { translator } from "./i18n.mjs"
+
+export const LOCK_NAME = ".skills-doctor.lock.json"
+export const LOCK_VERSION = 2
+
+function sha1Buffer(buffer) {
+  return createHash("sha1").update(buffer).digest("hex")
+}
+
+function safeRelPath(p) {
+  if (typeof p !== "string" || !p.trim()) return false
+  if (path.isAbsolute(p)) return false
+  const normalized = p.replace(/\\/g, "/")
+  if (normalized.split("/").some((seg) => seg === "..")) return false
+  if (/^[a-z][a-z0-9+.-]*:/i.test(normalized)) return false
+  return true
+}
+
+function resolveInside(baseDir, rel, t) {
+  const base = path.resolve(baseDir)
+  const target = path.resolve(base, rel)
+  if (target !== base && !target.startsWith(base + path.sep)) {
+    throw new Error(t("catalog.unsafePath", { rel }))
+  }
+  return target
+}
+
+export function validateCatalogEntry(entry, t = translator("en")) {
+  const problems = []
+  if (!entry || typeof entry !== "object") return [t("catalog.entryNotObject")]
+  if (typeof entry.name !== "string" || !entry.name.trim()) problems.push(t("catalog.missingName"))
+  if (typeof entry.version !== "string" && typeof entry.version !== "number") {
+    problems.push(t("catalog.missingVersion"))
+  }
+  if (!Array.isArray(entry.files) || entry.files.length === 0) {
+    problems.push(t("catalog.missingFiles"))
+  } else {
+    for (const file of entry.files) {
+      if (!safeRelPath(file)) problems.push(t("catalog.safePath", { file }))
+    }
+    const hasEntryFile =
+      entry.files.includes("SKILL.md") ||
+      (typeof entry.name === "string" && entry.files.includes(`${entry.name}.md`))
+    if (!hasEntryFile) problems.push(t("catalog.missingEntryFile"))
+  }
+  return problems
+}
+
+/** 读取某目录下的 lock（容忍旧版本、未来版本、BOM、损坏）。 */
+export function readLockFile(dir) {
+  const file = path.join(dir, LOCK_NAME)
+  if (!fs.existsSync(file)) return null
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8").replace(/^\uFEFF/, ""))
+    if (!parsed || typeof parsed !== "object" || typeof parsed.catalogs !== "object" || !parsed.catalogs) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+function lockEntryVersion(entry) {
+  if (typeof entry === "string") return entry
+  if (entry && typeof entry === "object" && entry.version != null) return String(entry.version)
+  return null
+}
+
+/** 本地文件是否仍与 lock 里的哈希一致（无哈希时视为一致）。 */
+function filesMatch(into, name, files, t) {
+  if (!files || typeof files !== "object") return true
+  for (const [rel, expected] of Object.entries(files)) {
+    const target = resolveInside(path.join(into, name), rel, t)
+    if (!fs.existsSync(target)) return false
+    if (sha1Buffer(fs.readFileSync(target)) !== expected) return false
+  }
+  return true
+}
+
+/** 抓取 <url>/index.json。未知字段一律忽略（向上兼容）。 */
+export async function fetchCatalogIndex(url, { fetchImpl = fetch, timeoutMs = 15000, t = translator("en") } = {}) {
+  const base = url.replace(/\/+$/, "")
+  const res = await fetchImpl(`${base}/index.json`, { signal: AbortSignal.timeout(timeoutMs) })
+  if (!res.ok) throw new Error(t("catalog.indexHttp", { status: res.status }))
+  const json = await res.json()
+  if (!json || !Array.isArray(json.skills)) throw new Error(t("catalog.indexShape"))
+  return { base, skills: json.skills }
+}
+
+/**
+ * 更新器：对比 HTTP catalog 的 version，必要时下载到 into 目录并写 lock。
+ * lock 里记录每个文件的 sha1，检测器据此判断「更新后是否被改过」。
+ */
+export async function updateCatalogs(catalogs, { into = process.cwd(), checkOnly = false, fetchImpl = fetch, t = translator("en") } = {}) {
+  const lockPath = path.join(into, LOCK_NAME)
+  const lock = readLockFile(into) ?? { version: LOCK_VERSION, catalogs: {} }
+  const lockTooNew = Number(lock.version ?? 1) > LOCK_VERSION
+  const results = []
+
+  for (const catalog of catalogs) {
+    const result = { url: catalog.url, error: null, updated: [], unchanged: [], invalid: [], files: 0 }
+    try {
+      const { base, skills } = await fetchCatalogIndex(catalog.url, { fetchImpl, t })
+      const baseUrl = new URL(base + "/")
+      const previousSkills = lock.catalogs[catalog.url]?.skills ?? {}
+      const nextSkills = {}
+
+      for (const entry of skills) {
+        const problems = validateCatalogEntry(entry, t)
+        if (problems.length) {
+          result.invalid.push({ name: String(entry?.name ?? "?"), problems })
+          continue
+        }
+        const version = String(entry.version)
+        const previousVersion = lockEntryVersion(previousSkills[entry.name])
+        const prevEntry = previousSkills[entry.name]
+        const prevHashes = prevEntry && typeof prevEntry === "object" ? prevEntry.files : null
+        const drifted = previousVersion === version && prevHashes ? !filesMatch(into, entry.name, prevHashes, t) : false
+
+        if (previousVersion === version && !drifted) {
+          result.unchanged.push(entry.name)
+          nextSkills[entry.name] = typeof prevEntry === "string" ? { version: prevEntry, files: {} } : prevEntry
+          continue
+        }
+
+        if (checkOnly) {
+          result.updated.push({ name: entry.name, version, previous: previousVersion, reason: drifted ? "drift" : null })
+          continue
+        }
+
+        const hashes = {}
+        for (const file of entry.files) {
+          const encodedPath = file.split("/").map(encodeURIComponent).join("/")
+          const fileUrl = new URL(`${encodeURIComponent(entry.name)}/${encodedPath}`, baseUrl)
+          if (fileUrl.origin !== baseUrl.origin) throw new Error(t("catalog.crossOrigin", { file }))
+          const res = await fetchImpl(fileUrl, { signal: AbortSignal.timeout(30000) })
+          if (!res.ok) throw new Error(t("catalog.fileHttp", { name: entry.name, file, status: res.status }))
+          const buffer = Buffer.from(await res.arrayBuffer())
+          const target = resolveInside(path.join(into, entry.name), file, t)
+          fs.mkdirSync(path.dirname(target), { recursive: true })
+          fs.writeFileSync(target, buffer)
+          hashes[file] = sha1Buffer(buffer)
+          result.files++
+        }
+        nextSkills[entry.name] = { version, files: hashes }
+        result.updated.push({ name: entry.name, version, previous: previousVersion, reason: drifted ? "drift" : null })
+      }
+
+      if (!checkOnly) lock.catalogs[catalog.url] = { skills: nextSkills }
+    } catch (err) {
+      result.error = String(err?.message ?? err)
+    }
+    results.push(result)
+  }
+
+  if (!checkOnly && results.some((r) => !r.error)) {
+    lock.version = LOCK_VERSION
+    lock.generatedAt = new Date().toISOString()
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true })
+    fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf8")
+  }
+
+  return { lockPath, lockTooNew, results }
+}

package/src/cli.mjs

@@ -0,0 +1,484 @@
+import fs from "node:fs"
+import path from "node:path"
+import { discoverSources, scanAll } from "./discover.mjs"
+import { resolveWinners, SEVERITY_ORDER } from "./lint.mjs"
+import { updateCatalogs, LOCK_NAME } from "./catalog.mjs"
+import { inspectManaged } from "./managed.mjs"
+import { planFixes, applyFixes, hideSkills } from "./fix.mjs"
+import { auditSkills } from "./audit.mjs"
+import { loadConfig } from "./config.mjs"
+import { padDisplay } from "./parse.mjs"
+import { detectLang, normalizeLang, translator } from "./i18n.mjs"
+
+const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"))
+
+const color = process.stdout.isTTY && !process.env.NO_COLOR
+const paint = (code, text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text)
+const red = (t) => paint("31", t)
+const yellow = (t) => paint("33", t)
+const green = (t) => paint("32", t)
+const cyan = (t) => paint("36", t)
+const dim = (t) => paint("2", t)
+const bold = (t) => paint("1", t)
+
+const HINT_KEYS = {
+  shadowed: "hint.shadowed",
+  "flat-dir-collision": "hint.flat-dir-collision",
+  "duplicate-content": "hint.duplicate-content",
+  "near-duplicate-description": "hint.near-duplicate-description",
+  "missing-description": "hint.missing-description",
+  "long-description": "hint.long-description",
+  "large-body": "hint.large-body",
+  "token-budget": "hint.token-budget",
+  "too-many-skills": "hint.too-many-skills",
+  "invalid-id": "hint.invalid-id",
+  "hidden-skill": "hint.hidden-skill",
+  "stale-skill": "hint.stale-skill",
+}
+
+function parseArgs(argv) {
+  const options = {
+    command: "check",
+    root: process.cwd(),
+    global: true,
+    budget: null,
+    staleDays: null,
+    strict: false,
+    json: false,
+    lang: null,
+    config: null,
+    dryRun: false,
+    hide: [],
+    into: null,
+    checkOnly: false,
+    help: false,
+    version: false,
+  }
+
+  const args = [...argv]
+  const commands = new Set(["check", "scan", "update", "fix", "help"])
+  if (args[0] && commands.has(args[0])) {
+    options.command = args.shift()
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    switch (arg) {
+      case "--root":
+        options.root = path.resolve(args[++i] ?? ".")
+        break
+      case "--no-global":
+        options.global = false
+        break
+      case "--budget":
+        options.budget = Number(args[++i])
+        break
+      case "--stale-days":
+        options.staleDays = Number(args[++i])
+        break
+      case "--strict":
+        options.strict = true
+        break
+      case "--json":
+        options.json = true
+        break
+      case "--lang":
+        options.lang = args[++i] ?? null
+        break
+      case "--config":
+        options.config = args[++i] ?? null
+        break
+      case "--dry-run":
+        options.dryRun = true
+        break
+      case "--hide":
+        options.hide.push(
+          ...String(args[++i] ?? "")
+            .split(",")
+            .map((id) => id.trim())
+            .filter(Boolean),
+        )
+        break
+      case "--into":
+        options.into = path.resolve(args[++i] ?? ".")
+        break
+      case "--check-only":
+        options.checkOnly = true
+        break
+      case "-h":
+      case "--help":
+        options.help = true
+        break
+      case "-v":
+      case "--version":
+        options.version = true
+        break
+      default:
+        if (arg.startsWith("-")) {
+          console.error(`unknown option: ${arg}`)
+          process.exit(2)
+        }
+    }
+  }
+
+  if (options.budget !== null && (!Number.isFinite(options.budget) || options.budget <= 0)) options.budget = null
+  if (options.staleDays !== null && (!Number.isFinite(options.staleDays) || options.staleDays < 0)) options.staleDays = null
+  return options
+}
+
+function serializeSkills(skills, managed = new Map()) {
+  return skills.map((s) => ({
+    id: s.id,
+    form: s.form,
+    file: s.file,
+    kind: s.source.kind,
+    scope: s.source.scope,
+    order: s.order,
+    advertised: s.advertised,
+    hidden: s.hidden,
+    descriptionChars: s.description.length,
+    descriptionTokens: s.descriptionTokens,
+    bodyTokens: s.bodyTokens,
+    bytes: s.bytes,
+    mtime: s.mtime ? new Date(s.mtime).toISOString() : null,
+    managed: managed.get(s.file) ?? null,
+  }))
+}
+
+function buildCheckResult(audit, options) {
+  return {
+    tool: "skills-doctor",
+    version: pkg.version,
+    lang: audit.lang,
+    cwd: audit.cwd,
+    projectRoot: audit.projectRoot,
+    config: audit.config,
+    budget: audit.budget,
+    staleDays: audit.staleDays,
+    sources: audit.sources.map((s) => ({
+      kind: s.kind,
+      scope: s.scope,
+      dir: s.dir,
+      order: s.order,
+      exists: fs.existsSync(s.dir),
+    })),
+    catalogs: audit.catalogs,
+    missing: audit.missing,
+    summary: audit.summary,
+    managed: { count: audit.managed.size },
+    findings: audit.findings,
+    counts: audit.counts,
+    exitCode: audit.counts.errors > 0 || (options.strict && audit.counts.warnings > 0) ? 1 : 0,
+  }
+}
+
+function printCheck(audit, result, options, t) {
+  const { summary, counts } = audit
+  console.log(bold(t("check.title", { version: result.version })))
+  console.log(dim(t("check.workdir", { dir: result.cwd })))
+  console.log(dim(t("check.projectRoot", { dir: result.projectRoot })))
+  if (result.config.error) {
+    console.log(yellow(t("config.error", { file: result.config.file, error: result.config.error })))
+  } else if (fs.existsSync(result.config.file)) {
+    console.log(dim(t("check.config", { file: result.config.file })))
+  }
+  console.log(
+    t("check.sources", {
+      total: result.sources.length,
+      existing: result.sources.filter((s) => s.exists).length,
+      definitions: summary.total,
+      unique: summary.unique,
+      advertised: summary.advertised,
+      tokens: summary.advertisedTokens,
+    }),
+  )
+  if (result.catalogs.length) console.log(dim(t("check.catalogs", { count: result.catalogs.length })))
+  if (result.managed.count > 0) console.log(dim(t("check.managed", { count: result.managed.count })))
+  for (const missing of result.missing) {
+    if (missing.kind === "config-error") {
+      console.log(yellow(t("check.configError", { path: missing.path, error: missing.error })))
+    } else if (missing.kind === "missing-path") {
+      console.log(yellow(t("check.missingPath", { path: missing.path })))
+    }
+  }
+  console.log("")
+
+  if (!result.findings.length) {
+    console.log(bold(t("check.none")))
+  } else {
+    const badge = { error: red("[E]"), warn: yellow("[W]"), info: cyan("[i]") }
+    for (const finding of result.findings) {
+      console.log(`${badge[finding.severity]} ${dim(finding.rule)}  ${finding.message}`)
+    }
+    console.log("")
+    console.log(
+      t("check.summary", { errors: counts.errors, warnings: counts.warnings, infos: counts.infos }) +
+        (options.strict ? t("check.strict") : ""),
+    )
+  }
+
+  const usedRules = [...new Set(result.findings.map((f) => f.rule))].filter((r) => HINT_KEYS[r])
+  if (usedRules.length) {
+    console.log("")
+    console.log(bold(t("check.hints")))
+    for (const rule of usedRules) console.log(dim(`  - ${t(HINT_KEYS[rule])}`))
+  }
+}
+
+function printScan(discovered, options, managed, t) {
+  const winners = resolveWinners(discovered.skills)
+  const rows = discovered.skills
+    .slice()
+    .sort((a, b) => a.id.localeCompare(b.id) || a.order - b.order)
+    .map((s) => {
+      const info = managed.get(s.file)
+      return {
+        id: s.id + (winners.get(s.id) === s ? " *" : "") + (info ? ` @${info.version}` : ""),
+        scope: s.source.scope,
+        adv: s.advertised ? "yes" : "no",
+        tokens: String(s.descriptionTokens),
+        body: String(s.bodyTokens),
+        file: s.file,
+      }
+    })
+
+  console.log(bold(t("scan.title", { version: pkg.version })))
+  console.log(dim(t("scan.workdir", { dir: path.resolve(options.root) })))
+  console.log(dim(t("scan.projectRoot", { dir: discovered.projectRoot })))
+  console.log("")
+
+  const widths = {
+    id: Math.max(4, ...rows.map((r) => r.id.length)) + 2,
+    scope: 8,
+    adv: 4,
+    tokens: 7,
+    body: 6,
+  }
+  console.log(
+    dim(
+      padDisplay(t("scan.col.id"), widths.id) +
+        padDisplay(t("scan.col.scope"), widths.scope) +
+        padDisplay(t("scan.col.adv"), widths.adv) +
+        padDisplay(t("scan.col.desc"), widths.tokens) +
+        padDisplay(t("scan.col.body"), widths.body) +
+        t("scan.col.file"),
+    ),
+  )
+  for (const row of rows) {
+    console.log(
+      padDisplay(row.id, widths.id) +
+        padDisplay(row.scope, widths.scope) +
+        padDisplay(row.adv, widths.adv) +
+        padDisplay(row.tokens, widths.tokens) +
+        padDisplay(row.body, widths.body) +
+        dim(row.file),
+    )
+  }
+  console.log("")
+  console.log(dim(t("scan.winner")))
+  if (discovered.catalogs.length) {
+    console.log(dim(t("scan.catalogs", { urls: discovered.catalogs.map((c) => c.url).join(", ") })))
+  }
+}
+
+async function runUpdate(discovered, options, cwd, t) {
+  const into = options.into ? path.resolve(options.into) : path.join(cwd, ".opencode", "skills")
+  if (!discovered.catalogs.length) {
+    console.log(bold(t("update.title")))
+    console.log(`  ${t("update.noCatalogs")}`)
+    return 0
+  }
+
+  const { lockPath, results, lockTooNew } = await updateCatalogs(discovered.catalogs, {
+    into,
+    checkOnly: options.checkOnly,
+    t,
+  })
+
+  if (options.json) {
+    console.log(JSON.stringify({ lockPath, checkOnly: options.checkOnly, results }, null, 2))
+    return results.some((r) => r.error) ? 1 : 0
+  }
+
+  console.log(bold(t(options.checkOnly ? "update.titleCheckOnly" : "update.title")))
+  console.log(dim(t("update.into", { dir: into })))
+  console.log("")
+  for (const result of results) {
+    console.log(cyan(result.url))
+    if (result.error) {
+      console.log(red(t("update.failed", { error: result.error })))
+      continue
+    }
+    if (result.updated.length) {
+      const label = t(options.checkOnly ? "update.labelAvailable" : "update.labelUpdated")
+      const items = result.updated
+        .map((u) => {
+          if (u.reason === "drift") return t("update.driftRepair", { name: u.name, version: u.version })
+          if (u.previous) return t("update.versionBump", { name: u.name, previous: u.previous, version: u.version })
+          return t("update.versioned", { name: u.name, version: u.version })
+        })
+        .join(", ")
+      console.log(green(t("update.updated", { label, count: result.updated.length, items })))
+    }
+    if (result.unchanged.length) console.log(dim(t("update.unchanged", { count: result.unchanged.length })))
+    if (result.files) console.log(dim(t("update.files", { count: result.files })))
+    for (const invalid of result.invalid) {
+      console.log(yellow(t("update.skipped", { name: invalid.name, problems: invalid.problems.join("; ") })))
+    }
+    if (!result.updated.length && !result.unchanged.length && !result.invalid.length) {
+      console.log(dim(t("update.empty")))
+    }
+  }
+  console.log("")
+  console.log(dim(t("update.lock", { path: lockPath, name: LOCK_NAME })))
+  if (lockTooNew) console.log(yellow(t("update.lockTooNew")))
+  if (!options.checkOnly && results.some((r) => !r.error)) {
+    console.log(dim(t("update.detector", { dir: into })))
+  }
+  return results.some((r) => r.error) ? 1 : 0
+}
+
+function runFix(audit, options, t) {
+  const { plan, skipped } = planFixes(audit.skills, audit.managed)
+  const archived = applyFixes(plan, { dryRun: options.dryRun })
+  const hidden = options.hide.length ? hideSkills(audit.skills, options.hide, { dryRun: options.dryRun }) : { changed: [], errors: [], missing: [] }
+
+  const errors = [...archived.errors, ...hidden.errors]
+
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          tool: "skills-doctor",
+          version: pkg.version,
+          lang: audit.lang,
+          dryRun: options.dryRun,
+          archived: archived.moved.map((m) => ({ id: m.id, from: m.from, to: m.target })),
+          hidden: hidden.changed,
+          skipped: skipped.map((s) => ({ id: s.id, file: s.file })),
+          missing: hidden.missing,
+          errors: errors.map((e) => ({ id: e.id, error: e.error })),
+        },
+        null,
+        2,
+      ),
+    )
+    return errors.length ? 1 : 0
+  }
+
+  const nothing = !plan.length && !skipped.length && !hidden.changed.length && !hidden.missing.length
+  if (nothing) {
+    console.log(bold(t("fix.title")))
+    console.log(`  ${t("fix.none")}`)
+    return 0
+  }
+
+  console.log(bold(t("fix.title")))
+  if (options.dryRun) console.log(dim(t("fix.dryRun")))
+  for (const item of archived.moved) console.log(green(t("fix.moved", { from: item.from, to: item.target })))
+  for (const item of hidden.changed) console.log(green(t("fix.hidden", { id: item.id, file: item.file })))
+  for (const item of skipped) console.log(dim(t("fix.skippedManaged", { path: item.file })))
+  for (const id of hidden.missing) console.log(yellow(t("fix.unknownHide", { id })))
+  for (const item of errors) console.log(red(t("fix.error", { path: item.file ?? item.from, error: item.error })))
+  console.log("")
+  console.log(
+    t("fix.summary", {
+      moved: archived.moved.length,
+      hidden: hidden.changed.length,
+      skipped: skipped.length,
+    }),
+  )
+  console.log(dim(t("fix.rerun")))
+  return errors.length ? 1 : 0
+}
+
+export async function main(argv) {
+  const options = parseArgs(argv)
+
+  if (options.lang && !normalizeLang(options.lang)) {
+    console.error(`unsupported --lang: ${options.lang} (expected en or zh)`)
+    process.exit(2)
+  }
+
+  const cwd = path.resolve(options.root)
+  const loaded = loadConfig(cwd, options.config)
+  const lang = normalizeLang(options.lang) ?? normalizeLang(loaded.config.lang) ?? detectLang()
+  const t = translator(lang)
+
+  if (options.help || options.command === "help") {
+    console.log(t("help", { version: pkg.version }))
+    return
+  }
+  if (options.version) {
+    console.log(pkg.version)
+    return
+  }
+
+  if (options.command === "check") {
+    const audit = auditSkills({
+      cwd,
+      includeGlobal: options.global,
+      lang,
+      configPath: options.config,
+      budget: options.budget,
+      staleDays: options.staleDays,
+    })
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          { ...buildCheckResult(audit, options), skills: serializeSkills(audit.skills, audit.managed) },
+          null,
+          2,
+        ),
+      )
+    } else {
+      const result = buildCheckResult(audit, options)
+      printCheck(audit, result, options, t)
+      process.exitCode = result.exitCode
+      return
+    }
+    process.exitCode = buildCheckResult(audit, options).exitCode
+    return
+  }
+
+  const discovered = scanAll(discoverSources({ cwd, includeGlobal: options.global }))
+  const managedInfo = inspectManaged(discovered.scans, { t })
+
+  if (options.command === "scan") {
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            tool: "skills-doctor",
+            version: pkg.version,
+            lang,
+            cwd,
+            skills: serializeSkills(discovered.skills, managedInfo.managed),
+          },
+          null,
+          2,
+        ),
+      )
+      return
+    }
+    printScan(discovered, options, managedInfo.managed, t)
+    return
+  }
+
+  if (options.command === "update") {
+    process.exitCode = await runUpdate(discovered, options, cwd, t)
+    return
+  }
+
+  if (options.command === "fix") {
+    const audit = auditSkills({
+      cwd,
+      includeGlobal: options.global,
+      lang,
+      configPath: options.config,
+      budget: options.budget,
+      staleDays: options.staleDays,
+    })
+    process.exitCode = runFix(audit, options, t)
+  }
+}

package/src/config.mjs

@@ -0,0 +1,34 @@
+import fs from "node:fs"
+import path from "node:path"
+
+export const CONFIG_NAME = ".skills-doctor.json"
+
+function normalize(raw) {
+  const config = {}
+  if (Number.isFinite(raw?.budget) && raw.budget > 0) config.budget = raw.budget
+  if (Number.isFinite(raw?.staleDays) && raw.staleDays >= 0) config.staleDays = raw.staleDays
+  if (typeof raw?.lang === "string") config.lang = raw.lang
+  if (raw?.rules && typeof raw.rules === "object") {
+    config.rules = {}
+    for (const [rule, level] of Object.entries(raw.rules)) {
+      if (level === "off" || level === "info" || level === "warn" || level === "error") config.rules[rule] = level
+    }
+  }
+  if (Array.isArray(raw?.ignore)) config.ignore = raw.ignore.filter((id) => typeof id === "string")
+  return config
+}
+
+/**
+ * 读取配置（默认 <cwd>/.skills-doctor.json）。
+ * 解析失败时返回 { error, file }，调用方决定是否继续。
+ */
+export function loadConfig(cwd, configPath = null) {
+  const file = configPath ? path.resolve(cwd, configPath) : path.join(cwd, CONFIG_NAME)
+  if (!fs.existsSync(file)) return { file, config: {} }
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8").replace(/^\uFEFF/, ""))
+    return { file, config: normalize(raw) }
+  } catch (err) {
+    return { file, config: {}, error: String(err?.message ?? err) }
+  }
+}