dsh-claude-move 0.2.1

package/lib/handoff.mjs

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/handoff.mjs — 续聊交接摘要（F17，零 DSH 依赖）。
+//
+// 安全模型沿用 Demogorgon314/dsh-resume-plugin（MIT，见 THIRD_PARTY_NOTICES.md）：
+// 外部 transcript 是不可信惰性历史——摘要只转述目标、涉及文件与停止点；
+// system/developer 记录不参与（convert 已忽略），reasoning/thinking 内容不进入
+// 摘要；旧工具输出视为过期证据，继续前必须复核仓库现状。摘要按字符数截断。
+
+/** 默认交接摘要字符上限（F17 可配）。 */
+export const DEFAULT_HANDOFF_MAX_CHARS = 2048
+
+/** 已知 Claude 记录类型：未知类型计入摘要警告（宽容跳过不失败）。 */
+export const KNOWN_CLAUDE_TYPES = new Set([
+  'user', 'assistant', 'system', 'summary', 'custom-title', 'ai-title',
+  'content-replacement', 'progress', 'file-history-snapshot', 'file-history-delta',
+  'attribution-snapshot', 'queue-operation', 'last-prompt', 'tag', 'agent-name',
+  'agent-color', 'agent-setting', 'mode', 'worktree-state',
+  'context-collapse-commit', 'context-collapse-snapshot',
+  'permission', 'permission-mode', 'attachment',
+])
+
+/** 可能携带文件/命令引用的工具名（只取参数做参考，不执行任何内容）。 */
+const FILE_TOOLS = new Set([
+  'Read', 'Edit', 'Write', 'NotebookEdit', 'MultiEdit', 'Glob', 'Grep',
+  'Bash', 'LS', 'WebFetch', 'WebSearch', 'Task', 'TodoWrite',
+])
+
+/**
+ * 单行归一 + 截断（截断后再去尾空格）。
+ * @param text - 原始文本。
+ * @param limit - 码点上限。
+ * @returns 归一化文本。
+ */
+export function oneLine(text, limit) {
+  return String(text ?? '').replace(/\s+/g, ' ').trim().slice(0, limit).trim()
+}
+
+/**
+ * 提取一步的纯文本（跳过 reasoning/tool-call 块）。
+ * @param step - convert 输出的 step。
+ * @returns 文本。
+ */
+export function textOfStep(step) {
+  return (step.content ?? [])
+    .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+    .map((b) => b.text)
+    .join('\n')
+    .trim()
+}
+
+/**
+ * 从工具调用参数中提取文件/命令引用（只读字符串，不执行）。
+ * @param toolCall - convert 输出的 toolCall。
+ * @returns 引用字符串或 null。
+ */
+export function fileArgOf(toolCall) {
+  if (!toolCall || !FILE_TOOLS.has(toolCall.name)) return null
+  let args = {}
+  try {
+    args = JSON.parse(toolCall.arguments ?? '{}')
+  } catch {
+    return null
+  }
+  if (args === null || typeof args !== 'object') return null
+  const candidate = args.file_path ?? args.path ?? args.pattern ?? args.command ?? args.query
+  return typeof candidate === 'string' && candidate.length > 0 && candidate.length < 300 ? candidate : null
+}
+
+/**
+ * 生成交接摘要（F17）：目标、最后请求、涉及文件、规模、停止点、警告。
+ * @param converted - convertClaudeJsonl 输出。
+ * @param options - `{ maxChars, title, sourceCwd, workspaceCwd }`；sourceCwd
+ *   为源 Claude 项目目录，workspaceCwd 为 claudecode 模式下会话实际所在目录。
+ * @returns 摘要文本。
+ */
+export function buildHandoff(converted, { maxChars = DEFAULT_HANDOFF_MAX_CHARS, title = '', sourceCwd, workspaceCwd } = {}) {
+  const turns = converted.turns ?? []
+  const lines = []
+  lines.push('# Claude Code 会话交接（静态历史，仅参考）')
+  if (title) lines.push(`源会话：${oneLine(title, 200)}`)
+  if (typeof sourceCwd === 'string' && sourceCwd.length > 0) {
+    lines.push(`源项目目录：${oneLine(sourceCwd, 500)}`)
+  }
+  if (typeof workspaceCwd === 'string' && workspaceCwd.length > 0) {
+    lines.push(`本会话工作目录（claudecode 工作区）：${oneLine(workspaceCwd, 500)}（继续前请复核源项目当前状态）`)
+  }
+
+  const goals = turns.slice(0, 3).map((t) => oneLine(t.prompt, 200)).filter(Boolean)
+  if (goals.length > 0) lines.push('早期目标：' + goals.join(' | '))
+
+  const lastTurn = turns.at(-1)
+  if (lastTurn) lines.push('最后用户请求：' + oneLine(lastTurn.prompt, 400))
+
+  const refs = new Set()
+  for (const turn of turns.slice(-8)) {
+    for (const step of turn.steps ?? []) {
+      for (const toolCall of step.toolCalls ?? []) {
+        const arg = fileArgOf(toolCall)
+        if (arg) refs.add(arg)
+      }
+    }
+  }
+  if (refs.size > 0) {
+    lines.push('最近涉及的文件/命令：\n- ' + [...refs].slice(0, 10).join('\n- '))
+  }
+
+  lines.push(`规模：${turns.length} 轮、${converted.messages ?? 0} 条消息、${converted.toolCalls ?? 0} 次工具调用`)
+
+  const lastText = turns.flatMap((t) => t.steps ?? []).map(textOfStep).filter(Boolean).at(-1)
+  if (lastText) lines.push('最后助手输出（截断）：' + oneLine(lastText, 600))
+
+  const warnings = []
+  if ((converted.skipped ?? 0) > 0) warnings.push(`${converted.skipped} 行畸形记录被跳过`)
+  const synthesized = converted.repaired?.synthesized ?? 0
+  if (synthesized > 0) {
+    warnings.push(`${synthesized} 处被中断的工具调用已补为合成错误结果（无真实返回记录）`)
+  }
+  const summaryCount = converted.typeCounts?.summary ?? 0
+  if (summaryCount > 0) {
+    // D1 调研结论：Claude summary 记录未映射为 DSH compaction 节点（合成需要
+    // 伪造 compaction 事务的 seq 范围/检查点消息，触发平台 invariant 的风险
+    // 大于收益）；完整历史以原始轮次导入，摘要仅在此提示。
+    warnings.push(`源记录含 ${summaryCount} 条 summary（Claude 上下文压缩摘要，未映射为压缩节点）`)
+  }
+  const unknown = Object.entries(converted.typeCounts ?? {})
+    .filter(([type]) => !KNOWN_CLAUDE_TYPES.has(type))
+  if (unknown.length > 0) {
+    warnings.push('未知记录类型：' + unknown.map(([type, n]) => `${type}×${n}`).join('、'))
+  }
+  if (warnings.length > 0) lines.push('警告：' + warnings.join('；'))
+
+  lines.push('以上是静态历史。继续前请复核当前仓库状态（分支/diff/关键文件），旧工具输出视为过期证据。')
+
+  const full = lines.join('\n')
+  return full.length <= maxChars ? full : full.slice(0, maxChars - 1) + '…'
+}

package/lib/imports-store.mjs

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/imports-store.mjs — imports.json 的并发安全存取与源文件级 in-flight 锁（零 DSH 依赖）。
+//
+// 导入可以由模型工具（import_claude）、命令（claude-import-all）与面板 job
+// 并发触发；imports.json 是单一文件，读-改-写必须串行化，同一源文件并发
+// 导入必须互斥（后者等待前者落盘后按幂等路径复用结果，避免 create duplicate
+// 与映射互相覆盖）。写走 discovery 的原子写（tmp + rename），并发读方不会
+// 读到半截 JSON。
+
+import { loadImports, saveImports, resolveCacheDir } from './discovery.mjs'
+
+/**
+ * imports.json 的串行读-改-写存取器 + 源文件级互斥锁。
+ * @returns `{ update, exclusive }`。
+ */
+export function createImportsStore() {
+  let writeChain = Promise.resolve()
+  const sourceLocks = new Map()
+
+  return {
+    /**
+     * 串行执行「读取 → mutator 就地修改 → 原子写回」。多个并发调用按提交
+     * 顺序依次落地，绝不互相覆盖；单次失败不影响后续写入。
+     * @param mutator - `(imports) => result`，就地修改 imports 并返回结果。
+     * @returns 拒绝时抛出该次错误（调用方决定处理）；链上后续写不受影响。
+     */
+    update(mutator) {
+      const next = writeChain.then(async () => {
+        const imports = await loadImports(resolveCacheDir())
+        const result = await mutator(imports)
+        await saveImports(resolveCacheDir(), imports)
+        return result
+      })
+      // 队列吞掉失败：单次失败不阻塞/毒化后续写入（错误已随 next 抛给本次调用方）。
+      writeChain = next.catch(() => {})
+      return next
+    },
+
+    /**
+     * 同一源文件互斥：并发调用同一 key 时按到达顺序排队，后到者等待先行者
+     * （含失败）完成后重新执行 fn——此时 imports.json 已含先行者记录，fn
+     * 内部按幂等路径处理。排队期间的新到达者挂在最新任务后，绝不并行。
+     * @param key - 互斥键（源 transcript 绝对路径）。
+     * @param fn - 独占执行的任务。
+     * @returns fn 的结果。
+     */
+    async exclusive(key, fn) {
+      const prev = sourceLocks.get(key)
+      const task = (async () => {
+        if (prev !== undefined) await prev.catch(() => {})
+        return fn()
+      })()
+      sourceLocks.set(key, task)
+      try {
+        return await task
+      } finally {
+        if (sourceLocks.get(key) === task) sourceLocks.delete(key)
+      }
+    },
+  }
+}
+
+/** 插件进程内的默认实例（index.mjs 与测试可各持实例，互不影响）。 */
+export const importsStore = createImportsStore()

package/lib/manifest.mjs

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/manifest.mjs — move.json 迁移清单的并发安全存取（零 DSH 依赖）。
+//
+// 幂等基础：每个已执行计划记录 { digest, target, appliedAt, action }，
+// 重跑时摘要未变即跳过；force 重应用。写入串行化 + 原子写（tmp + rename），
+// 与 imports.json（会话级幂等）并存：会话走一期 imports 机制，文件类走本清单。
+
+import path from 'node:path'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { resolveCacheDir } from './discovery.mjs'
+
+/** 清单文件路径（与一期缓存同目录，`$DSH_HOME/claude-move/move.json`）。 */
+export function manifestPath(cacheDir = resolveCacheDir()) {
+  return path.join(cacheDir, 'move.json')
+}
+
+/** 原子写 JSON（tmp + rename；目录缺失先建）。 */
+export async function atomicWriteJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true })
+  const tmp = file + '.tmp-' + process.pid + '-' + Date.now()
+  await writeFile(tmp, JSON.stringify(value, null, 2), 'utf8')
+  await rename(tmp, file)
+}
+
+/**
+ * 读取清单；缺失/损坏返回空对象（损坏不抛，重跑按全新清单处理）。
+ * @param cacheDir - 缓存目录。
+ * @returns 记录映射 `{ key: { digest, target, appliedAt, action } }`。
+ */
+export async function loadManifest(cacheDir = resolveCacheDir()) {
+  try {
+    const raw = await readFile(manifestPath(cacheDir), 'utf8')
+    const parsed = JSON.parse(raw)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed
+  } catch {
+    // 缺失/损坏：空清单。
+  }
+  return {}
+}
+
+/**
+ * 清单串行读-改-写存取器（与 imports-store 同构）。
+ * `cacheDir` 每次操作时惰性解析（默认值在调用时求值）：进程级单例
+ * 不得在 import 时绑定 DSH_HOME，否则测试/临时 profile 的覆盖会写进默认家目录。
+ * @param cacheDir - 缓存目录；缺省时每次调用经 resolveCacheDir() 惰性解析。
+ * @returns `{ update, load }`。
+ */
+export function createManifestStore(cacheDir) {
+  let writeChain = Promise.resolve()
+  return {
+    load: () => loadManifest(cacheDir ?? resolveCacheDir()),
+    /** 串行「读取 → mutator 就地修改 → 原子写回」；单次失败不毒化后续写入。 */
+    update(mutator) {
+      const dir = cacheDir ?? resolveCacheDir()
+      const next = writeChain.then(async () => {
+        const manifest = await loadManifest(dir)
+        const result = await mutator(manifest)
+        await atomicWriteJson(manifestPath(dir), manifest)
+        return result
+      })
+      writeChain = next.catch(() => {})
+      return next
+    },
+  }
+}
+
+/** 记录一条已执行计划。 */
+export function recordEntry(manifest, key, record) {
+  manifest[key] = { appliedAt: new Date().toISOString(), ...record }
+}
+
+/** 默认进程内实例（index.mjs 与测试可各持实例）。 */
+export const manifestStore = createManifestStore()

package/lib/persona.mjs

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/persona.mjs — 迁移向导生成的短 persona 段落（零 DSH 依赖）。
+//
+// 对齐官方 Minimal persona 风格：一句简短角色陈述开头、保持短小
+// （`You are a helpful software engineer assistant.`）。迁移报告里给用户的
+// persona 建议与向导注入文案都从这里生成，绝不超过两三句话。
+
+/** 常见角色的中文名（保持短小）。 */
+const ZH_ROLES = { assistant: '助手', migration: '迁移', code: '编程', review: '审查' }
+
+/**
+ * 一句角色陈述（官方 Minimal persona 风格）。
+ * @param role - 角色名（默认 'assistant'）。
+ * @param lang - 'en' | 'zh'。
+ * @returns 单句 persona。
+ */
+export function personaSentence(role = 'assistant', lang = 'en') {
+  const raw = String(role ?? 'assistant').trim() || 'assistant'
+  const name = lang === 'zh' ? (ZH_ROLES[raw] ?? raw) : raw
+  return lang === 'zh'
+    ? `你是一名高效的${name}助手。`
+    : `You are a helpful ${raw} assistant.`
+}
+
+/**
+ * 迁移向导的短 persona 段落：一句角色陈述 + 一句边界说明，保持短小。
+ * 用于（a）报告中的 persona 建议；（b）OpenCode agent 转技能时的 persona 建议。
+ * @param role - 角色名。
+ * @param lang - 'en' | 'zh'。
+ * @returns 不超过两句的段落。
+ */
+export function personaParagraph(role = 'migration', lang = 'en') {
+  const sentence = personaSentence(role, lang)
+  return lang === 'zh'
+    ? `${sentence}你只负责迁移本机数据到 DeepSeek Harness，回答简短、先确认再执行。`
+    : `${sentence} You migrate local agent data into DeepSeek Harness: answer briefly and confirm before executing.`
+}

package/lib/report.mjs

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/report.mjs — 导入报告辅助（零 DSH 依赖）。
+//
+// S4：疑似密钥/凭据只报告「文件:行:类型」，绝不展示匹配内容本身。
+
+/** 疑似凭据片段模式：kind 标签 + 匹配规则。顺序敏感：更具体的前缀在前，避免重叠计数。 */
+export const SECRET_PATTERNS = Object.freeze([
+  { kind: 'aws-access-key', pattern: /\bAKIA[0-9A-Z]{16}\b/g },
+  { kind: 'github-token', pattern: /\bgh[pousr]_[0-9A-Za-z]{36,255}\b|\bgithub_pat_[0-9A-Za-z_]{22,255}\b/g },
+  { kind: 'google-api-key', pattern: /\bAIza[0-9A-Za-z_\-]{35}\b/g },
+  { kind: 'anthropic-key', pattern: /\bsk-ant-[0-9A-Za-z\-_]{20,}\b/g },
+  { kind: 'openai-key', pattern: /\bsk-(?!ant-)[0-9A-Za-z\-_]{20,}\b/g },
+  { kind: 'private-key', pattern: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/g },
+  { kind: 'slack-token', pattern: /\bxox[baprs]-[0-9A-Za-z\-]{10,}\b/g },
+  { kind: 'generic-bearer', pattern: /(?:"|')?bearer\s+[0-9A-Za-z\-._~+/]{20,}(?:"|')?/gi },
+])
+
+/**
+ * 扫描原始文本中的疑似凭据片段（S4）。
+ * @param text - 原始文本（如 transcript 全文）。
+ * @param maxHits - 上报上限，超出截断（完整计数仍保留在 total）。
+ * @returns `{ total, hits: [{ line, kind }] }`；无命中返回 `{ total: 0, hits: [] }`。
+ */
+export function scanSecrets(text, maxHits = 50) {
+  const lines = String(text).split('\n')
+  const hits = []
+  let total = 0
+  for (let i = 0; i < lines.length; i++) {
+    for (const { kind, pattern } of SECRET_PATTERNS) {
+      pattern.lastIndex = 0
+      if (pattern.test(lines[i])) {
+        total++
+        if (hits.length < maxHits) hits.push({ line: i + 1, kind })
+      }
+    }
+  }
+  return { total, hits }
+}
+
+/** 权限类记录（S5）：默认不导入，只在报告中统计。 */
+export const PERMISSION_RECORD_TYPES = Object.freeze([
+  'permission',
+  'permission-mode',
+  'queue-operation',
+])
+
+/**
+ * 从 convert 的 typeCounts 汇总权限类记录数量（S5）。
+ * @param typeCounts - convert 输出里的 typeCounts。
+ * @returns `{ byType, total }`。
+ */
+export function summarizePermissions(typeCounts) {
+  const byType = {}
+  let total = 0
+  for (const type of PERMISSION_RECORD_TYPES) {
+    const count = typeCounts?.[type] ?? 0
+    if (count > 0) {
+      byType[type] = count
+      total += count
+    }
+  }
+  return { byType, total }
+}

package/lib/settings.mjs

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/settings.mjs — Claude Code settings.json 翻译（F14，零 DSH 依赖）。
+//
+// 不直接搬运（DSH 配置格式不兼容），而是解析 allow/deny/ask 权限规则与
+// model 偏好，生成 DSH 配置建议文本；无法映射的键显式列出，绝不静默丢弃。
+// 建议里的 cordis.yml 片段是示意（DSH 权限面为 permission presets + approval
+// 策略，具体生效位置以官方 docs/permission-presets 为准）。
+
+/** 已识别的 Claude settings.json 顶层键（其余计入 unmapped）。 */
+export const KNOWN_SETTINGS_KEYS = Object.freeze([
+  'permissions', 'model', 'env', 'hooks', 'apiKeyHelper', 'includeCoAuthoredBy',
+  'forceLoginMethod', 'cleanupPeriodDays', 'spinnerTipsEnabled',
+])
+
+/**
+ * 解析 settings.json 文本。
+ * @param raw - 原始 JSON 文本。
+ * @returns 解析结果；坏 JSON 返回 `{ error }`。
+ */
+export function parseClaudeSettings(raw) {
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    return { error: String((err && err.message) || err) }
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { error: 'settings.json 根节点不是 JSON 对象' }
+  }
+  return { parsed }
+}
+
+/**
+ * 把一条 Claude 权限规则翻译为 DSH 建议。规则形如 `Read(./path)`、
+ * `Edit(~/.ssh/**)`、`Bash(npm run *)`、`WebFetch(domain:github.com)`。
+ * @param rule - 规则字符串。
+ * @param action - allow | deny | ask。
+ * @returns `{ title, tool, detail }` 或 null（无法识别工具域）。
+ */
+export function translatePermissionRule(rule, action) {
+  const match = /^([A-Za-z]+)\s*\((.+)\)$/.exec(String(rule).trim())
+  if (!match) return { title: `无法识别的规则：${rule}`, tool: 'unknown', detail: `保留原文待人工确认（${action}）。` }
+  const [, tool, target] = match
+  const actionLabel = { allow: '允许', deny: '拒绝', ask: '询问' }[action] ?? action
+  return {
+    title: `${actionLabel} ${tool}(${target})`,
+    tool,
+    target,
+    detail: '',
+  }
+}
+
+/**
+ * 翻译整个 settings.json（F14）。
+ * @param raw - settings.json 原始文本。
+ * @param location - 报告里显示的来源位置。
+ * @returns `{ suggestions, unmapped }`；解析失败返回 `{ error, unmapped: [] }`。
+ */
+export function translateSettings(raw, location) {
+  const { parsed, error } = parseClaudeSettings(raw)
+  if (error) return { error: `${location}: ${error}`, unmapped: [] }
+
+  const suggestions = []
+  const unmapped = []
+
+  const permissions = parsed.permissions
+  if (permissions && typeof permissions === 'object' && !Array.isArray(permissions)) {
+    for (const action of ['deny', 'ask', 'allow']) {
+      const rules = permissions[action]
+      if (!Array.isArray(rules)) continue
+      for (const rule of rules) {
+        const translated = translatePermissionRule(rule, action)
+        if (translated) suggestions.push({ kind: 'permission', action, ...translated })
+      }
+    }
+    if (Array.isArray(permissions.additionalDirectories)) {
+      suggestions.push({
+        kind: 'additional-directories',
+        action: 'allow',
+        title: `额外工作目录 ${permissions.additionalDirectories.length} 个`,
+        tool: 'directory',
+        target: permissions.additionalDirectories.join(', '),
+        detail: 'DSH 按工作区授权目录访问；在 DSH 中为这些目录创建工作区即可。',
+      })
+    }
+    for (const key of Object.keys(permissions)) {
+      if (!['allow', 'deny', 'ask', 'additionalDirectories', 'defaultMode'].includes(key)) {
+        unmapped.push(`permissions.${key}`)
+      }
+    }
+  }
+
+  if (typeof parsed.model === 'string' && parsed.model.length > 0) {
+    suggestions.push({
+      kind: 'model',
+      action: 'prefer',
+      title: `默认模型偏好：${parsed.model}`,
+      tool: 'model',
+      target: parsed.model,
+      detail: '在 DSH Settings → Models 中选择对应模型；DSH 不读取 Claude 的模型 id。',
+    })
+  }
+
+  if (typeof parsed.apiKeyHelper === 'string' && parsed.apiKeyHelper.length > 0) {
+    suggestions.push({
+      kind: 'api-key-helper',
+      action: 'prefer',
+      title: `apiKeyHelper：${parsed.apiKeyHelper}`,
+      tool: 'credential',
+      target: parsed.apiKeyHelper,
+      detail: 'DSH 用 Settings → Models 或凭据服务管理密钥；不执行外部脚本获取密钥。',
+    })
+  }
+
+  for (const key of Object.keys(parsed)) {
+    if (!KNOWN_SETTINGS_KEYS.includes(key)) unmapped.push(key)
+  }
+  if (parsed.env && typeof parsed.env === 'object') {
+    unmapped.push('env（环境变量不自动搬运，请在 DSH 会话里显式设置）')
+  }
+  if (parsed.hooks && typeof parsed.hooks === 'object') {
+    unmapped.push('hooks（Claude hooks 不自动搬运；DSH 对应机制为 hooks 桥接插件）')
+  }
+
+  return { suggestions, unmapped, location }
+}
+
+/**
+ * 汇总一个或多个 settings.json 的翻译结果。
+ * @param files - `[{ location, raw }]`。
+ * @returns `{ suggestions, unmapped, errors }`。
+ */
+export function translateSettingsBatch(files) {
+  const suggestions = []
+  const unmapped = []
+  const errors = []
+  for (const { location, raw } of files) {
+    const result = translateSettings(raw, location)
+    if (result.error) {
+      errors.push(result.error)
+      continue
+    }
+    suggestions.push(...result.suggestions)
+    unmapped.push(...result.unmapped)
+  }
+  return { suggestions, unmapped, errors }
+}

package/lib/skill-migrate.mjs

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/skill-migrate.mjs — 四源技能 → DSH 技能目录的兼容判定与转换（零 DSH 依赖）。
+//
+// DSH 技能落盘约定（$DSH_HOME/skills，官方 skill-filesystem 契约）：
+//   - 目录束 `<name>/SKILL.md` 或扁平 `<name>.md`；
+//   - SKILL.md 必须有 YAML frontmatter，且 name 与 description 均非空，
+//     否则该文件被跳过（甚至拖垮整目录加载，见 issue#1）；
+//   - 技能名 kebab-case（[a-z0-9]+(-[a-z0-9]+)*）。
+//
+// 迁移规则：源 SKILL.md frontmatter 含非空 name+description → 兼容，内容直拷
+// （只改落点目录名）；否则合成最小 frontmatter 转换（name 取 frontmatter/目录名
+// kebab 化，description 取 frontmatter 或正文首个标题/首行，截断），正文原样保留。
+// README.md / MEMORY.md / 隐藏目录（.system/.hub/.git）一律跳过。
+
+import path from 'node:path'
+import { parseFrontmatter } from './frontmatter.mjs'
+
+/** DSH 技能名 kebab-case 模式（与官方契约一致）。 */
+export const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+/** 非技能文档/内部目录（发现与复制都跳过）。 */
+export const SKIP_DIR_RE = /^\./            // .system/.hub/.git 等隐藏目录
+export const SKIP_FILE_RE = /^(readme|memory)\.md$/i
+
+/** 技能描述默认上限（合成时截断）。 */
+export const DESCRIPTION_MAX = 200
+
+/**
+ * 归一化为 kebab-case 技能名。
+ * @param raw - 原始名称。
+ * @param fallback - 归一化结果为空时使用。
+ * @returns kebab-case 名称。
+ */
+export function kebabName(raw, fallback = 'skill') {
+  const slug = String(raw ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-')
+  return SKILL_NAME_RE.test(slug) ? slug : fallback
+}
+
+/**
+ * 判定一个技能文件是否与 DSH 契约兼容（可直拷）。
+ * @param content - 文件原文。
+ * @returns `{ compatible, name, description }`；解析失败时 compatible=false。
+ */
+export function classifySkill(content) {
+  let meta = {}
+  let body = String(content ?? '')
+  try {
+    const parsed = parseFrontmatter(body)
+    if (parsed) {
+      meta = parsed.meta ?? {}
+      body = parsed.body ?? ''
+    }
+  } catch {
+    // 畸形 frontmatter：按不兼容处理（走转换路径补合成 frontmatter）。
+    return { compatible: false, name: '', description: '', body }
+  }
+  const name = String(meta.name ?? '').trim()
+  const description = String(meta.description ?? '').trim()
+  return {
+    compatible: name.length > 0 && description.length > 0,
+    name,
+    description,
+    body,
+  }
+}
+
+/**
+ * 从正文猜测描述：优先首个 markdown 标题，其次首个非空行。
+ * @param body - 正文（不含 frontmatter）。
+ * @returns 截断后的描述。
+ */
+export function guessDescription(body) {
+  const lines = String(body ?? '').split(/\r?\n/)
+  for (const line of lines) {
+    const t = line.trim()
+    if (!t) continue
+    const heading = t.match(/^#{1,6}\s+(.+)$/)
+    const text = heading ? heading[1].trim() : t
+    if (text.length === 0) continue
+    return text.length <= DESCRIPTION_MAX ? text : text.slice(0, DESCRIPTION_MAX - 3).trimEnd() + '...'
+  }
+  return ''
+}
+
+/**
+ * 渲染一个 DSH 技能文件（SKILL.md 全文）。
+ * @param content - 源文件原文。
+ * @param fallbackName - frontmatter 缺 name 时的兜底名（目录名/文件名 stem）。
+ * @returns `{ content, name, description, converted }`；converted=true 表示补过 frontmatter。
+ */
+export function renderSkill(content, fallbackName = 'skill') {
+  const raw = String(content ?? '')
+  const { compatible, name, description, body } = classifySkill(raw)
+  if (compatible) {
+    // 兼容直拷：内容原样保留（frontmatter + 正文）。
+    return { content: raw, name: kebabName(name), description, converted: false }
+  }
+  const finalName = kebabName(name || fallbackName)
+  const finalDescription = description || guessDescription(body) || `Migrated skill ${finalName}`
+  const rendered = `---\nname: ${finalName}\ndescription: ${finalDescription}\n---\n\n${body.trim()}\n`
+  return { content: rendered, name: finalName, description: finalDescription, converted: true }
+}
+
+/**
+ * 目标技能目录路径：`$DSH_HOME/skills/<kebab-name>/SKILL.md`。
+ * @param skillsDir - DSH 技能根目录。
+ * @param name - kebab 技能名。
+ * @returns SKILL.md 绝对路径。
+ */
+export function skillTargetPath(skillsDir, name) {
+  return path.join(skillsDir, name, 'SKILL.md')
+}
+
+/**
+ * 技能发现守卫：跳过非技能文档与隐藏目录（.system/.hub/.git 等）。
+ * @param entryName - 目录条目名。
+ * @returns 是否应跳过。
+ */
+export function skipSkillEntry(entryName) {
+  const s = String(entryName ?? '')
+  if (SKIP_DIR_RE.test(s)) return true
+  if (SKIP_FILE_RE.test(s)) return true
+  return false
+}