dsh-skill-hub 0.3.26 → 0.3.28

package/src/skillfs/audit.ts

@@ -0,0 +1,229 @@
+/**
+ * 技能内容审计：安装前拦截与常驻体检共用的一套纯函数规则。
+ *
+ * 两条设计约束：
+ * 1. 零依赖、纯字符串处理。宿主每 5 秒轮询一次 /catalog，扫描必须廉价，
+ *    否则面板响应时间会随技能数量线性变慢（与 scanDiagnostics 同一理由）。
+ * 2. 规则只认结构特征（不可见字符、命令管道、凭据路径），不做语义判断。
+ *    语义/LLM 判断误报率高且要模型调用，不属于一个管理器的职责边界；
+ *    这里的目标是「让藏起来的东西显形」，不是「判定作者意图」。
+ *
+ * 两级严重度：
+ * - `block`：安装阶段拒绝落盘。只用于「没有任何正当用途」的特征 ——
+ *   裸 ESC 控制字符、Unicode 标签字符、双向控制符、以及体积越界。
+ * - `warn`：落盘但标记。零宽字符、危险命令、凭据路径、超长描述都可能
+ *   出现在正常技能里（比如一个教人用 curl 的技能），交给人判断。
+ */
+
+/** 规则 id：稳定，测试与文案都按它断言。 */
+export type AuditRuleId =
+  | 'ansi-escape'
+  | 'unicode-tag'
+  | 'bidi-control'
+  | 'zero-width'
+  | 'dangerous-command'
+  | 'credential-path'
+  | 'file-too-large'
+  | 'bundle-too-large'
+  | 'too-many-files'
+  | 'description-too-long'
+
+export type AuditSeverity = 'block' | 'warn'
+
+/** 一条审计发现。`file` 相对技能目录，便于在面板上直接定位。 */
+export interface AuditFinding {
+  rule: AuditRuleId
+  severity: AuditSeverity
+  file: string
+  /** 1 起行号；整文件级规则（体积、文件数）省略。 */
+  line?: number
+  message: string
+}
+
+/** 单文件字节上限：技能是纯文本加少量脚本，2 MiB 已远超正常体积。 */
+export const MAX_SKILL_FILE_BYTES = 2 * 1024 * 1024
+/** 单个技能总字节上限。 */
+export const MAX_SKILL_BUNDLE_BYTES = 10 * 1024 * 1024
+/** 单个技能文件数上限。 */
+export const MAX_SKILL_FILES = 500
+/** agentskills.io 规范对 description 的硬上限。 */
+export const MAX_DESCRIPTION_CHARS = 1024
+
+/** 裸 ESC —— 终端转义注入（CWE-150）的起点，正常技能正文不含。 */
+const ANSI_RE = /\u001B/
+/** Unicode 标签字符区，唯一用途是承载不可见文本。 */
+const UNICODE_TAG_RE = /[\u{E0000}-\u{E007F}]/u
+/** 双向控制符：Trojan Source 式视觉重排。 */
+const BIDI_RE = /[\u202A-\u202E\u2066-\u2069]/
+/** 零宽字符：可能来自从网页复制的正文，也可能用于隐藏内容。 */
+const ZERO_WIDTH_RE = /[\u200B-\u200D\u2060\uFEFF]/
+
+/**
+ * 危险命令：只匹配「下载后直接执行」这一族，也就是审计报告里出现频率最高、
+ * 且人类肉眼最容易滑过去的那几种形态。普通的 `curl URL` 取数据不在此列。
+ */
+const DANGEROUS_COMMANDS: ReadonlyArray<{ re: RegExp; label: string }> = [
+  { re: /\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?(?:ba|z|k)?sh\b/, label: 'remote script piped straight into a shell' },
+  { re: /\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?python[0-9.]*\b/, label: 'remote script piped straight into python' },
+  { re: /\bbase64\s+(?:-d|--decode)\b[^\n|]*\|\s*(?:ba|z|k)?sh\b/, label: 'base64 payload decoded into a shell' },
+  { re: /\beval\s+["']?\$\(\s*(?:curl|wget)\b/, label: 'eval of a downloaded command' },
+  { re: /\bnc\b[^\n]*\s-e\s/, label: 'netcat with command execution' },
+  { re: /\/dev\/tcp\//, label: 'raw TCP socket via /dev/tcp' },
+]
+
+/** 凭据路径：技能正文提到这些路径本身未必有恶意，但值得让人看一眼上下文。 */
+const CREDENTIAL_PATHS: ReadonlyArray<{ re: RegExp; label: string }> = [
+  { re: /(?:^|[\s"'`/])\.ssh\/id_(?:rsa|dsa|ecdsa|ed25519)\b/, label: 'SSH private key' },
+  { re: /(?:^|[\s"'`/])\.aws\/credentials\b/, label: 'AWS credentials file' },
+  { re: /(?:^|[\s"'`/])\.netrc\b/, label: 'netrc credentials file' },
+  { re: /Library\/Keychains\b/, label: 'macOS keychain' },
+  { re: /(?:^|[\s"'`])\.docker\/config\.json\b/, label: 'Docker registry credentials' },
+  { re: /(?:^|\s)\/etc\/shadow\b/, label: 'system password database' },
+]
+
+/** 1 起行号（按 `\n` 计）。 */
+function lineOf(text: string, index: number): number {
+  let line = 1
+  const end = Math.min(index, text.length)
+  for (let i = 0; i < end; i += 1) if (text.charCodeAt(i) === 10) line += 1
+  return line
+}
+
+/** 首个匹配位置与总数。每次新建带 `g` 的正则，避免 lastIndex 跨调用残留。 */
+function collect(text: string, re: RegExp): { first: number; count: number } {
+  const global = new RegExp(re.source, 'gu')
+  let first = -1
+  let count = 0
+  let match: RegExpExecArray | null
+  while ((match = global.exec(text)) !== null) {
+    if (first === -1) first = match.index
+    count += 1
+    if (match[0].length === 0) global.lastIndex += 1
+  }
+  return { first, count }
+}
+
+/**
+ * 审计一段技能文本（SKILL.md 正文、脚本、参考文档都适用）。
+ * 纯函数：同样的输入永远给同样的结果，便于单测与「改动前后对比」。
+ */
+export function auditSkillText(relativePath: string, text: string): AuditFinding[] {
+  const findings: AuditFinding[] = []
+  // 文件开头的 BOM 是合法编码标记，不算零宽隐藏；先剥掉再检测。
+  const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+  const push = (rule: AuditRuleId, severity: AuditSeverity, message: string, index: number): void => {
+    findings.push({ rule, severity, file: relativePath, line: lineOf(body, index), message })
+  }
+
+  if (ANSI_RE.test(body)) {
+    push('ansi-escape', 'block', 'contains a raw ESC control character — it can rewrite what a terminal displays (escape-sequence injection, CWE-150)', body.search(ANSI_RE))
+  }
+
+  const tags = collect(body, UNICODE_TAG_RE)
+  if (tags.count > 0) {
+    push('unicode-tag', 'block', `contains ${tags.count} invisible Unicode tag character(s); text hidden there is not rendered by any editor, so a reviewer cannot see what the agent reads`, tags.first)
+  }
+
+  const bidi = collect(body, BIDI_RE)
+  if (bidi.count > 0) {
+    push('bidi-control', 'block', `contains ${bidi.count} bidirectional control character(s); they can make the file read differently than it executes`, bidi.first)
+  }
+
+  const zeroWidth = collect(body, ZERO_WIDTH_RE)
+  if (zeroWidth.count > 0) {
+    push('zero-width', 'warn', `contains ${zeroWidth.count} zero-width character(s); usually a copy-paste artifact, but they can also split a keyword so a reviewer's search misses it`, zeroWidth.first)
+  }
+
+  for (const { re, label } of DANGEROUS_COMMANDS) {
+    const hit = re.exec(body)
+    if (hit !== null && hit.index !== undefined) {
+      push('dangerous-command', 'warn', `contains ${label}: \`${hit[0].trim().slice(0, 120)}\``, hit.index)
+      break
+    }
+  }
+
+  for (const { re, label } of CREDENTIAL_PATHS) {
+    const hit = re.exec(body)
+    if (hit !== null && hit.index !== undefined) {
+      push('credential-path', 'warn', `references ${label}; check the surrounding instructions actually need it`, hit.index)
+      break
+    }
+  }
+
+  return findings
+}
+
+/** description 超出规范上限：部分客户端会截断，技能因此静默失去自动激活能力。 */
+export function auditDescription(file: string, description: string): AuditFinding[] {
+  if (description.length <= MAX_DESCRIPTION_CHARS) return []
+  return [{
+    rule: 'description-too-long',
+    severity: 'warn',
+    file,
+    message: `description is ${description.length} chars; the Agent Skills spec caps it at ${MAX_DESCRIPTION_CHARS} and longer ones get truncated by clients, which silently stops the skill from auto-activating`,
+  }]
+}
+
+/** 一个待落盘/待检查的技能文件。`text` 只在能当作文本读时提供。 */
+export interface AuditBundleFile {
+  /** 相对技能目录的路径。 */
+  path: string
+  size: number
+  /** 文本内容；二进制或未下载时省略。 */
+  text?: string
+}
+
+/**
+ * 审计一个完整技能目录：体积/数量上限 + 每个文本文件的规则扫描。
+ * `block` 级发现（体积越界）意味着不该落盘；文本级 `block` 由调用方决定。
+ */
+export function auditSkillBundle(files: readonly AuditBundleFile[], description?: string): AuditFinding[] {
+  const findings: AuditFinding[] = []
+  if (files.length > MAX_SKILL_FILES) {
+    findings.push({
+      rule: 'too-many-files',
+      severity: 'block',
+      file: '.',
+      message: `skill has ${files.length} files; the hub imports at most ${MAX_SKILL_FILES} per skill`,
+    })
+  }
+  const totalBytes = files.reduce((sum, file) => sum + file.size, 0)
+  if (totalBytes > MAX_SKILL_BUNDLE_BYTES) {
+    findings.push({
+      rule: 'bundle-too-large',
+      severity: 'block',
+      file: '.',
+      message: `skill is ${formatBytes(totalBytes)} in total; the hub imports at most ${formatBytes(MAX_SKILL_BUNDLE_BYTES)} per skill`,
+    })
+  }
+  for (const file of files) {
+    if (file.size > MAX_SKILL_FILE_BYTES) {
+      findings.push({
+        rule: 'file-too-large',
+        severity: 'block',
+        file: file.path,
+        message: `${formatBytes(file.size)} is over the ${formatBytes(MAX_SKILL_FILE_BYTES)} per-file limit`,
+      })
+      continue
+    }
+    if (file.text !== undefined) findings.push(...auditSkillText(file.path, file.text))
+  }
+  if (description !== undefined) findings.push(...auditDescription('SKILL.md', description))
+  return findings
+}
+
+/** 阻断性发现的单行摘要（导入失败时的错误文本）。 */
+export function blockingReason(findings: readonly AuditFinding[]): string | undefined {
+  const blocked = findings.filter((finding) => finding.severity === 'block')
+  if (blocked.length === 0) return undefined
+  const head = blocked.slice(0, 3).map((finding) => `${finding.file}${finding.line !== undefined ? ':' + String(finding.line) : ''} ${finding.message}`)
+  const rest = blocked.length > head.length ? ` (+${blocked.length - head.length} more)` : ''
+  return 'skill rejected by content audit: ' + head.join('; ') + rest
+}
+
+/** 字节数的人读形式（诊断文案用）。 */
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`
+}

package/src/skillfs/foreign.test.ts

@@ -0,0 +1,121 @@
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { foreignRoots, importForeignSkill, scanForeignSkills } from './foreign.ts'
+
+describe('foreignRoots', () => {
+  it('never lists the hub writable root ~/.agents/skills', () => {
+    const dirs = foreignRoots('/home/u').map((root) => root.dir)
+    expect(dirs).not.toContain('/home/u/.agents/skills')
+    expect(dirs.some((dir) => dir.endsWith('.claude/skills'))).toBe(true)
+  })
+})
+
+describe('scanForeignSkills', () => {
+  let home: string
+
+  beforeEach(async () => {
+    home = await mkdtemp(join(tmpdir(), 'dsh-foreign-scan-'))
+  })
+
+  afterEach(async () => {
+    await rm(home, { recursive: true, force: true })
+  })
+
+  async function writeSkill(relativeDir: string, name: string, extra = ''): Promise<void> {
+    const dir = join(home, relativeDir)
+    await mkdir(dir, { recursive: true })
+    await writeFile(join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: A ${name} skill for testing\n---\n\nbody\n${extra}`, 'utf8')
+  }
+
+  it('finds directory bundles and flat files across agents', async () => {
+    await writeSkill('.claude/skills/review', 'review')
+    await writeSkill('.codex/skills/plan', 'plan')
+    const flatDir = join(home, '.cursor', 'skills')
+    await mkdir(flatDir, { recursive: true })
+    await writeFile(join(flatDir, 'notes.md'), '---\nname: notes\ndescription: Flat note skill\n---\nbody\n', 'utf8')
+
+    const skills = await scanForeignSkills(home)
+    expect(skills.map((skill) => `${skill.agent}:${skill.name}:${skill.kind}`)).toEqual([
+      'cursor:notes:flat',
+      'codex:plan:directory',
+      'claude-code:review:directory',
+    ])
+  })
+
+  it('skips entries whose frontmatter cannot be parsed', async () => {
+    const dir = join(home, '.claude', 'skills', 'broken')
+    await mkdir(dir, { recursive: true })
+    await writeFile(join(dir, 'SKILL.md'), '# no frontmatter\n', 'utf8')
+    expect(await scanForeignSkills(home)).toEqual([])
+  })
+
+  it('marks names that already exist in the hub catalog', async () => {
+    await writeSkill('.claude/skills/taken', 'taken')
+    const skills = await scanForeignSkills(home, new Set(['taken']))
+    expect(skills[0]?.existing).toBe(true)
+  })
+
+  it('returns nothing when no external root exists', async () => {
+    expect(await scanForeignSkills(home)).toEqual([])
+  })
+})
+
+describe('importForeignSkill', () => {
+  let home: string
+  let targetRoot: string
+
+  beforeEach(async () => {
+    home = await mkdtemp(join(tmpdir(), 'dsh-foreign-import-'))
+    targetRoot = join(home, 'skills')
+  })
+
+  afterEach(async () => {
+    await rm(home, { recursive: true, force: true })
+  })
+
+  it('copies a directory bundle with its support files', async () => {
+    const dir = join(home, '.claude', 'skills', 'demo')
+    await mkdir(join(dir, 'scripts'), { recursive: true })
+    await writeFile(join(dir, 'SKILL.md'), '---\nname: demo\ndescription: Demo skill for tests\n---\nbody\n', 'utf8')
+    await writeFile(join(dir, 'scripts', 'run.sh'), 'npm test\n', 'utf8')
+    const [skill] = await scanForeignSkills(home)
+    const path = await importForeignSkill(skill!, targetRoot)
+    expect(path).toBe(join(targetRoot, 'demo', 'SKILL.md'))
+    await expect(readFile(path, 'utf8')).resolves.toContain('name: demo')
+    await expect(readFile(join(targetRoot, 'demo', 'scripts', 'run.sh'), 'utf8')).resolves.toBe('npm test\n')
+  })
+
+  it('lands a flat skill as a directory bundle', async () => {
+    const dir = join(home, '.codex', 'skills')
+    await mkdir(dir, { recursive: true })
+    await writeFile(join(dir, 'flat.md'), '---\nname: flat\ndescription: Flat skill for tests\n---\nbody\n', 'utf8')
+    const [skill] = await scanForeignSkills(home)
+    const path = await importForeignSkill(skill!, targetRoot)
+    expect(path).toBe(join(targetRoot, 'flat', 'SKILL.md'))
+    await expect(readFile(path, 'utf8')).resolves.toContain('name: flat')
+  })
+
+  it('rejects a skill carrying hidden Unicode tag characters', async () => {
+    const dir = join(home, '.claude', 'skills', 'sneaky')
+    await mkdir(dir, { recursive: true })
+    const body = '---\nname: sneaky\ndescription: Looks fine\n---\nbody' + String.fromCodePoint(0xe0041) + '\n'
+    await writeFile(join(dir, 'SKILL.md'), body, 'utf8')
+    const [skill] = await scanForeignSkills(home)
+    await expect(importForeignSkill(skill!, targetRoot)).rejects.toThrow(/invisible Unicode tag/)
+    await expect(readFile(join(targetRoot, 'sneaky', 'SKILL.md'), 'utf8')).rejects.toThrow()
+  })
+
+  it('does not follow symlinks out of the external skill', async () => {
+    const dir = join(home, '.claude', 'skills', 'linked')
+    await mkdir(dir, { recursive: true })
+    await writeFile(join(dir, 'SKILL.md'), '---\nname: linked\ndescription: Linked skill for tests\n---\nbody\n', 'utf8')
+    const secret = join(home, 'secret.txt')
+    await writeFile(secret, 'private\n', 'utf8')
+    await symlink(secret, join(dir, 'leak.txt'))
+    const [skill] = await scanForeignSkills(home)
+    await importForeignSkill(skill!, targetRoot)
+    await expect(readFile(join(targetRoot, 'linked', 'leak.txt'), 'utf8')).rejects.toThrow()
+  })
+})

package/src/skillfs/foreign.ts

@@ -0,0 +1,198 @@
+/**
+ * 外部 agent 技能的只读发现与收编。
+ *
+ * SKILL.md 已经是跨 agent 的事实标准（Claude Code / Codex / Cursor / Gemini CLI
+ * 等 45+ 产品读同一份文件），但**发现路径各家不同**。于是「我在 Claude Code 里
+ * 调好的技能」在 dsh 里看不见，用户只能手工复制目录。
+ *
+ * 这里只做两件事：读（列出别处有什么）和复制（把选中的收编到本地可写根）。
+ * 外部目录一律**只读**，绝不改写 —— 那是别的 agent 的资产。
+ */
+
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, relative } from 'node:path'
+import { parseFrontmatter } from './frontmatter.ts'
+import { scanRoot } from './scan.ts'
+import { auditSkillBundle, blockingReason, MAX_SKILL_FILES, type AuditBundleFile } from './audit.ts'
+
+/** 一个外部 agent 的技能根。`agent` 是展示用的稳定标识。 */
+export interface ForeignRoot {
+  agent: string
+  /** 绝对路径；不存在时扫描直接返回空。 */
+  dir: string
+}
+
+/** 一条可收编的外部技能。 */
+export interface ForeignSkill {
+  /** 技能名（目录名或扁平文件名，与 frontmatter 一致时才算有效）。 */
+  name: string
+  description: string
+  /** 来源 agent 标识。 */
+  agent: string
+  /** 发现文件绝对路径。 */
+  path: string
+  /** 资源基目录（目录包本身，或扁平文件的父目录）。 */
+  directory: string
+  kind: 'directory' | 'flat'
+  /** 目标根已有同名技能（不可导入）。 */
+  existing: boolean
+}
+
+/**
+ * 常见 agent 的用户级技能目录。`~/.agents/skills` 不在此列 —— 那是 hub 自己的
+ * 可写根（user-agents），重复列会让同一个技能出现两次。
+ * 路径取自 vercel-labs/skills 的 agent 注册表，只保留桌面端常见的几个。
+ */
+export function foreignRoots(userHome: string): ForeignRoot[] {
+  return [
+    { agent: 'claude-code', dir: join(userHome, '.claude', 'skills') },
+    { agent: 'codex', dir: join(userHome, '.codex', 'skills') },
+    { agent: 'cursor', dir: join(userHome, '.cursor', 'skills') },
+    { agent: 'gemini-cli', dir: join(userHome, '.gemini', 'skills') },
+    { agent: 'copilot', dir: join(userHome, '.copilot', 'skills') },
+    { agent: 'opencode', dir: join(userHome, '.config', 'opencode', 'skills') },
+    { agent: 'goose', dir: join(userHome, '.config', 'goose', 'skills') },
+  ]
+}
+
+/**
+ * 扫描所有外部根。解析不出 frontmatter 的条目直接跳过 —— 它们在任何 agent 里
+ * 都不会生效，列出来只会让人以为「导入就好了」。
+ */
+export async function scanForeignSkills(userHome: string, existing: ReadonlySet<string> = new Set()): Promise<ForeignSkill[]> {
+  const found: ForeignSkill[] = []
+  for (const root of foreignRoots(userHome)) {
+    for (const entry of await scanRoot(root.dir)) {
+      let text: string
+      try {
+        text = await readFile(entry.path, 'utf8')
+      } catch {
+        continue
+      }
+      const parsed = parseFrontmatter(text)
+      if ('error' in parsed) continue
+      const name = entry.kind === 'directory' ? basename(entry.directory) : basename(entry.path, '.md')
+      found.push({
+        name,
+        description: parsed.value.description,
+        agent: root.agent,
+        path: entry.path,
+        directory: entry.directory,
+        kind: entry.kind,
+        existing: existing.has(name),
+      })
+    }
+  }
+  return found.sort((a, b) => (a.name === b.name ? a.agent.localeCompare(b.agent) : a.name.localeCompare(b.name)))
+}
+
+interface CollectedFile {
+  /** 相对技能目录的路径。 */
+  path: string
+  absolute: string
+  size: number
+}
+
+/**
+ * 递归列文件。符号链接不跟随（lstat）：一个指向 `~/.ssh` 的链接不该因为
+ * 「用户点了导入」就被复制进技能目录。
+ */
+async function walk(dir: string, base: string, depth: number, out: CollectedFile[]): Promise<void> {
+  if (depth > 8 || out.length >= MAX_SKILL_FILES) return
+  let names: string[]
+  try {
+    names = await readdir(dir)
+  } catch {
+    return
+  }
+  names.sort()
+  for (const name of names) {
+    if (out.length >= MAX_SKILL_FILES) return
+    if (name === '.git') continue
+    const absolute = join(dir, name)
+    let info
+    try {
+      info = await lstat(absolute)
+    } catch {
+      continue
+    }
+    if (info.isSymbolicLink()) continue
+    if (info.isDirectory()) await walk(absolute, base, depth + 1, out)
+    else if (info.isFile()) out.push({ path: relative(base, absolute), absolute, size: info.size })
+  }
+}
+
+async function collectForCopy(skill: ForeignSkill): Promise<CollectedFile[]> {
+  if (skill.kind === 'flat') {
+    const info = await lstat(skill.path)
+    return [{ path: basename(skill.path), absolute: skill.path, size: info.size }]
+  }
+  const out: CollectedFile[] = []
+  await walk(skill.directory, skill.directory, 0, out)
+  return out
+}
+
+/** 文本文件的判定与市场导入一致：无 NUL、解码无替换字符。 */
+function asText(buffer: Buffer): string | undefined {
+  if (buffer.includes(0)) return undefined
+  const text = buffer.toString('utf8')
+  return text.includes('\uFFFD') ? undefined : text
+}
+
+/**
+ * 把一个外部技能收编到 `targetRoot`（通常是 `~/.dsh/skills`）。
+ *
+ * 与市场导入同一套闸：体积/数量上限 + 内容审计，命中阻断级直接拒绝；
+ * 落盘仍是「临时目录 → 校验 → 原子 rename」，失败不留半成品。
+ * 扁平技能统一落成目录包 —— hub 的所有写入路径都建目录包，两种形态并存会
+ * 触发同名不可达（issue #16 那一类）。
+ */
+export async function importForeignSkill(skill: ForeignSkill, targetRoot: string): Promise<string> {
+  const collected = await collectForCopy(skill)
+  if (collected.length === 0) throw new Error('skill has no files to import')
+
+  const audited: AuditBundleFile[] = []
+  const payload: Array<{ relative: string; buffer: Buffer }> = []
+  for (const file of collected) {
+    const buffer = await readFile(file.absolute)
+    const text = asText(buffer)
+    audited.push({ path: file.path, size: buffer.length, ...(text !== undefined ? { text } : {}) })
+    payload.push({ relative: file.path, buffer })
+  }
+  const blocked = blockingReason(auditSkillBundle(audited))
+  if (blocked !== undefined) throw new Error(blocked)
+
+  await mkdir(targetRoot, { recursive: true })
+  const tempDir = await mkdtemp(join(targetRoot, '.' + skill.name + '.foreign-'))
+  try {
+    for (const file of payload) {
+      const target = join(tempDir, file.relative)
+      await mkdir(dirname(target), { recursive: true })
+      await writeFile(target, file.buffer)
+    }
+    const discovery = skill.kind === 'flat' ? join(tempDir, basename(skill.path)) : join(tempDir, 'SKILL.md')
+    let text: string
+    try {
+      text = await readFile(discovery, 'utf8')
+    } catch {
+      throw new Error('imported skill has no SKILL.md')
+    }
+    const parsed = parseFrontmatter(text)
+    if ('error' in parsed) throw new Error('imported skill rejected: ' + parsed.error)
+    if (parsed.value.name !== skill.name) {
+      throw new Error(`skill declares name "${parsed.value.name}", expected "${skill.name}"`)
+    }
+    // 扁平技能落成目录包：`<name>.md` → `<name>/SKILL.md`，让两条写入路径归一。
+    if (skill.kind === 'flat') {
+      await mkdir(join(tempDir, skill.name), { recursive: true })
+      await rename(discovery, join(tempDir, skill.name, 'SKILL.md'))
+    }
+    const targetDir = join(targetRoot, skill.name)
+    await rename(skill.kind === 'flat' ? join(tempDir, skill.name) : tempDir, targetDir)
+    return join(targetDir, 'SKILL.md')
+  } finally {
+    // 成功后 tempDir 只剩空壳（目录包被整体移走），失败时里面还有残留；
+    // 一条 force 清理覆盖两种情况。
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {})
+  }
+}

package/src/skillfs/hash.test.ts

@@ -0,0 +1,129 @@
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { hashSkillAt, hashSkillDirectory } from './hash.ts'
+
+describe('hashSkillDirectory', () => {
+  let dir: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hash-'))
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  async function write(relative: string, content: string): Promise<void> {
+    const full = join(dir, relative)
+    await mkdir(join(full, '..'), { recursive: true })
+    await writeFile(full, content, 'utf8')
+  }
+
+  it('is stable across calls for identical content', async () => {
+    await write('SKILL.md', '---\nname: demo\n---\nbody\n')
+    await write('scripts/run.sh', 'npm test\n')
+    const first = await hashSkillDirectory(dir)
+    const second = await hashSkillDirectory(dir)
+    expect(first).toBeDefined()
+    expect(first).toBe(second)
+  })
+
+  it('changes when a file body changes', async () => {
+    await write('SKILL.md', 'body one\n')
+    const before = await hashSkillDirectory(dir)
+    await write('SKILL.md', 'body two\n')
+    expect(await hashSkillDirectory(dir)).not.toBe(before)
+  })
+
+  it('changes when a file is added', async () => {
+    await write('SKILL.md', 'body\n')
+    const before = await hashSkillDirectory(dir)
+    await write('extra.md', 'more\n')
+    expect(await hashSkillDirectory(dir)).not.toBe(before)
+  })
+
+  it('changes when a path is renamed but content is identical', async () => {
+    await write('SKILL.md', 'body\n')
+    await write('a.md', 'same\n')
+    const before = await hashSkillDirectory(dir)
+    await rm(join(dir, 'a.md'))
+    await write('b.md', 'same\n')
+    expect(await hashSkillDirectory(dir)).not.toBe(before)
+  })
+
+  it('returns undefined for an empty directory', async () => {
+    expect(await hashSkillDirectory(dir)).toBeUndefined()
+  })
+
+  it('returns undefined for a missing directory', async () => {
+    expect(await hashSkillDirectory(join(dir, 'nope'))).toBeUndefined()
+  })
+
+  it('ignores .git and .trash', async () => {
+    await write('SKILL.md', 'body\n')
+    const before = await hashSkillDirectory(dir)
+    await write('.git/config', 'noise\n')
+    await write('.trash/old/SKILL.md', 'junk\n')
+    expect(await hashSkillDirectory(dir)).toBe(before)
+  })
+
+  it('does not follow symlinks out of the skill directory', async () => {
+    await write('SKILL.md', 'body\n')
+    const before = await hashSkillDirectory(dir)
+    const outside = await mkdtemp(join(tmpdir(), 'dsh-skill-hash-out-'))
+    try {
+      await writeFile(join(outside, 'secret.txt'), 'do not read me\n', 'utf8')
+      await symlink(join(outside, 'secret.txt'), join(dir, 'link.txt'))
+      expect(await hashSkillDirectory(dir)).toBe(before)
+    } finally {
+      await rm(outside, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('hashSkillAt', () => {
+  let dir: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hash-at-'))
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('hashes a directory bundle through its SKILL.md path', async () => {
+    const bundle = join(dir, 'demo')
+    await mkdir(bundle)
+    await writeFile(join(bundle, 'SKILL.md'), 'bundle body\n', 'utf8')
+    expect(await hashSkillAt(join(bundle, 'SKILL.md'))).toBe(await hashSkillDirectory(bundle))
+  })
+
+  it('hashes a disabled bundle through SKILL.md.disabled', async () => {
+    const bundle = join(dir, 'demo')
+    await mkdir(bundle)
+    await writeFile(join(bundle, 'SKILL.md.disabled'), 'bundle body\n', 'utf8')
+    expect(await hashSkillAt(join(bundle, 'SKILL.md.disabled'))).toBe(await hashSkillDirectory(bundle))
+  })
+
+  it('hashes a flat skill file directly', async () => {
+    const flat = join(dir, 'flat.md')
+    await writeFile(flat, 'flat body\n', 'utf8')
+    const first = await hashSkillAt(flat)
+    expect(first).toBeDefined()
+    await writeFile(flat, 'flat body changed\n', 'utf8')
+    expect(await hashSkillAt(flat)).not.toBe(first)
+  })
+
+  it('treats a flat .md.disabled file as a flat skill', async () => {
+    const flat = join(dir, 'flat.md.disabled')
+    await writeFile(flat, 'flat body\n', 'utf8')
+    expect(await hashSkillAt(flat)).toBeDefined()
+  })
+
+  it('returns undefined when the discovery file is missing', async () => {
+    expect(await hashSkillAt(join(dir, 'ghost', 'SKILL.md'))).toBeUndefined()
+  })
+})