dsh-skill-hub 0.3.26 → 0.3.28

package/src/protocol/catalog.ts

@@ -54,6 +54,60 @@ export interface DiagnosticEntry {
   reason: string
   /** Whether this diagnostic can be auto-fixed (e.g. unquoted colon). */
   fixable?: boolean
+  /**
+   * 条目来源。缺省 = 发现诊断（provider 跳过了这个文件）；`security` = 内容审计
+   * （文件能被加载，但正文里有值得看一眼的东西）。两者共用同一块 UI，但
+   * security 条目不能「修复」，只能说清问题在哪一行。
+   */
+  kind?: 'security'
+  /** security 条目的严重度；发现诊断条目省略。 */
+  severity?: 'block' | 'warn'
+}
+
+/**
+ * 技能目录在 system prompt 里占用的公告预算。渐进加载的第一层只放
+ * name + description，但技能多了这一层本身就会顶到客户端的上限而被截断，
+ * 表现为「装了却不触发」—— 面板必须能看见这个数字。
+ */
+export interface AnnouncementBudget {
+  /** 参与公告的技能数（已启用且 modelInvocable）。 */
+  skills: number
+  /** name + description + whenToUse 的总字符数。 */
+  chars: number
+  /** 粗略 token 估算（按 3 字符/token）。 */
+  approxTokens: number
+  /** 建议预算（字符），超出即 overBudget。 */
+  budget: number
+  overBudget: boolean
+}
+
+/**
+ * 技能目录的建议字符预算。取 8000：这是 Codex 在上下文窗口未知时对初始
+ * 技能清单的硬上限，也是目前公开客户端里最保守的一档。超出后尾部条目会被
+ * 静默丢弃（技能看起来装了，实际不触发）。
+ */
+export const ANNOUNCEMENT_CHAR_BUDGET = 8000
+
+/**
+ * 按「已启用且模型可调用」的技能估算公告成本。只统计一层渐进加载真正注入的
+ * 字段（name + description + whenToUse），不含正文 —— 正文是激活后才载入的，
+ * 不占常驻预算。
+ */
+export function computeAnnouncementBudget(skills: readonly CatalogSkill[]): AnnouncementBudget {
+  let chars = 0
+  let count = 0
+  for (const skill of skills) {
+    if (!skill.invocation.modelInvocable) continue
+    count += 1
+    chars += skill.name.length + skill.description.length + (skill.whenToUse?.length ?? 0)
+  }
+  return {
+    skills: count,
+    chars,
+    approxTokens: Math.ceil(chars / 3),
+    budget: ANNOUNCEMENT_CHAR_BUDGET,
+    overBudget: chars > ANNOUNCEMENT_CHAR_BUDGET,
+  }
 }
 
 /** POST /api/skill-hub/diagnostic/fix — repair a fixable diagnostic in place. */
@@ -78,6 +132,8 @@ export interface CatalogResponse {
   disabled: DisabledSkill[]
   /** Files in the writable roots the provider ignores, with reasons. */
   diagnostics: DiagnosticEntry[]
+  /** 技能目录占用的公告预算（见 AnnouncementBudget）。 */
+  announcement: AnnouncementBudget
   /** Skill names that appeared in multiple roots (first wins, others hidden). Mirrors codex name_counts. */
   duplicateNames?: string[]
 }

package/src/protocol/foreign.ts

@@ -0,0 +1,47 @@
+/**
+ * 外部 agent 技能（收编）的线格式。
+ *
+ * 发现源是别的 agent 的用户级技能目录（Claude Code / Codex / Cursor / …），
+ * 它们一律只读：这里只描述「看到了什么」和「要收编哪一个」。
+ */
+
+/** 一个被扫描的外部技能根。 */
+export interface ForeignRootView {
+  agent: string
+  dir: string
+  /** 该目录在本机是否存在（不存在时 skills 里不会出现它的条目）。 */
+  present: boolean
+}
+
+/** 一条可收编的外部技能。 */
+export interface ForeignSkillView {
+  name: string
+  description: string
+  agent: string
+  /** 发现文件绝对路径（只读展示）。 */
+  path: string
+  kind: 'directory' | 'flat'
+  /** 目标根已有同名技能，不可导入。 */
+  existing: boolean
+}
+
+/** GET /api/skill-hub/foreign */
+export interface ForeignListResponse {
+  ok: true
+  roots: ForeignRootView[]
+  skills: ForeignSkillView[]
+}
+
+/** POST /api/skill-hub/foreign/import — 按 agent + 名字收编（不信任前端给的路径）。 */
+export interface ForeignImportRequest {
+  items: Array<{ agent: string; name: string }>
+}
+
+export interface ForeignImportResponse {
+  ok: true
+  imported: string[]
+  /** 导入前被移入回收站的同名占位（已禁用的发现文件 / 空壳目录），可恢复。 */
+  replaced?: string[]
+  skipped: Array<{ name: string; reason: string }>
+  failed: Array<{ name: string; error: string }>
+}

package/src/protocol/sources.ts

@@ -15,6 +15,12 @@ export interface SourceRecord {
   skills: string[]
   /** 仓库内路径 → 文件大小 的基线清单（差异检测用；缺失 = 无基线）。 */
   manifest?: Record<string, number>
+  /**
+   * 技能名 → 本地内容哈希（导入/同步落盘后立刻采集）。用于区分「上游变了」
+   * 与「本地被改过」：没有它，「全部更新」只能盲覆盖。缺失 = 该技能还没采集过
+   * （旧记录），比对时按「未知」处理，不误报为已修改。
+   */
+  localHashes?: Record<string, string>
 }
 
 /** 回收站条目：上游删除后跟进删除（移入 .trash）的技能。 */
@@ -77,6 +83,11 @@ export interface SourceCheckResult {
   throttled?: boolean
   /** 该来源此前没有快照（迁移/旧记录），本次已回填 commit，尚未有差异基线。 */
   unverified?: boolean
+  /**
+   * 本地磁盘内容与上次导入/同步时不一致的技能（用户自己改过）。只在检查
+   * 时本地能读到文件才判定；哈希未采集过（旧记录）的技能不出现在这里。
+   */
+  localModified?: string[]
 }
 
 /** POST /api/skill-hub/sources/check */
@@ -100,6 +111,8 @@ export interface SourceSyncResponse {
   commitSha: string
   /** 成功同步的技能。 */
   synced: string[]
+  /** 本次同步覆盖掉的、本地有改动的技能（改前哈希 ≠ 记录哈希）。 */
+  overwritten?: string[]
   /** 失败的技能。 */
   failed: Array<{ name: string; error: string }>
 }

package/src/protocol.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { ANNOUNCEMENT_CHAR_BUDGET, computeAnnouncementBudget, type CatalogSkill } from './protocol.ts'
+
+function skill(overrides: Partial<CatalogSkill> = {}): CatalogSkill {
+  return {
+    name: 'demo',
+    description: 'does things',
+    invocation: { modelInvocable: true, userInvocable: true },
+    provider: 'filesystem',
+    writable: true,
+    source: 'user-dsh',
+    ...overrides,
+  }
+}
+
+describe('computeAnnouncementBudget', () => {
+  it('reports zero for an empty catalog', () => {
+    expect(computeAnnouncementBudget([])).toEqual({
+      skills: 0,
+      chars: 0,
+      approxTokens: 0,
+      budget: ANNOUNCEMENT_CHAR_BUDGET,
+      overBudget: false,
+    })
+  })
+
+  it('sums name, description and whenToUse', () => {
+    const budget = computeAnnouncementBudget([
+      skill({ name: 'abc', description: 'de', whenToUse: 'fg' }),
+    ])
+    expect(budget.skills).toBe(1)
+    expect(budget.chars).toBe(7)
+    expect(budget.approxTokens).toBe(3)
+  })
+
+  it('skips skills the model cannot invoke', () => {
+    const budget = computeAnnouncementBudget([
+      skill({ name: 'model-visible', description: '' }),
+      skill({ name: 'hidden', description: '', invocation: { modelInvocable: false, userInvocable: true } }),
+    ])
+    expect(budget.skills).toBe(1)
+    expect(budget.chars).toBe('model-visible'.length)
+  })
+
+  it('flags a catalog over the budget', () => {
+    const budget = computeAnnouncementBudget([
+      skill({ name: 'a', description: 'x'.repeat(ANNOUNCEMENT_CHAR_BUDGET) }),
+    ])
+    expect(budget.overBudget).toBe(true)
+  })
+
+  it('treats exactly the budget as within it', () => {
+    const budget = computeAnnouncementBudget([
+      skill({ name: 'a', description: 'x'.repeat(ANNOUNCEMENT_CHAR_BUDGET - 1) }),
+    ])
+    expect(budget.chars).toBe(ANNOUNCEMENT_CHAR_BUDGET)
+    expect(budget.overBudget).toBe(false)
+  })
+})

package/src/protocol.ts

@@ -15,6 +15,7 @@ export type {
   CatalogSkill,
   DisabledSkill,
   DiagnosticEntry,
+  AnnouncementBudget,
   DiagnosticFixRequest,
   DiagnosticFixResponse,
   CatalogResponse,
@@ -29,6 +30,7 @@ export type {
   CreateRequest,
   CreateResponse,
 } from './protocol/catalog.ts'
+export { ANNOUNCEMENT_CHAR_BUDGET, computeAnnouncementBudget } from './protocol/catalog.ts'
 export type { SkillStat, StatsResponse, SkillStatsCheckpoint } from './protocol/stats.ts'
 export type { ErrorResponse, HubConfig, HubSettingsValue, RedactedHubConfig, ConfigResponse, ConfigRequest } from './protocol/config.ts'
 export { HUB_CONFIG_DEFAULTS, HUB_ENTRY_ID, HEX_COLOR_RE, GITHUB_TOKEN_RE, resolveHubConfig, redactGithubToken } from './protocol/config.ts'
@@ -89,3 +91,4 @@ export type {
   SourceTrashClearResponse,
 } from './protocol/sources.ts'
 export { isProjectSource } from './protocol/sources.ts'
+export type { ForeignRootView, ForeignSkillView, ForeignListResponse, ForeignImportRequest, ForeignImportResponse } from './protocol/foreign.ts'

package/src/repo/install.ts

@@ -10,6 +10,7 @@ import type { RepoSkillEntry } from '../protocol.ts'
 import { errorText } from '../error-text.ts'
 import { mapConcurrent } from '../concurrency.ts'
 import { parseFrontmatter } from '../skillfs.ts'
+import { auditSkillBundle, blockingReason, MAX_SKILL_FILE_BYTES, type AuditBundleFile } from '../skillfs/audit.ts'
 import { NO_COMPRESSION, RepoFetchError, fetchError, githubAuthHeaders, isAbortError } from './github-client.ts'
 import { relativeToSkillDir } from './discovery.ts'
 import type { RepoFile } from './types.ts'
@@ -57,10 +58,25 @@ export async function downloadGitHubFile(repo: string, ref: string, path: string
   }
 }
 
+/**
+ * Treat a downloaded buffer as text when it plausibly is one: no NUL byte and
+ * no U+FFFD from a failed UTF-8 decode. Binary files (icons, archives) are
+ * size-checked only — running the text rules over a PNG would produce noise.
+ */
+function asAuditText(buffer: Buffer): string | undefined {
+  if (buffer.includes(0)) return undefined
+  const text = buffer.toString('utf8')
+  return text.includes('\uFFFD') ? undefined : text
+}
+
 /**
  * Download a full skill directory into a temporary dir, validate SKILL.md,
  * then atomically rename it into place. The target root is created when missing.
  * Callers pass a target root and a skill entry plus its collected files.
+ *
+ * 写盘前有两道闸：体积/数量上限（预检用 tree 的 size，落盘前再用实际字节复核）
+ * 和内容审计（隐藏字符、危险命令、凭据路径）。审计的 `block` 级发现直接拒绝
+ * 导入 —— 一个能藏住指令的技能不该靠用户「看得仔细」来兜底。
  */
 export async function downloadRepoSkill(
   repo: string,
@@ -73,6 +89,12 @@ export async function downloadRepoSkill(
   onProgress?: (bytes: number, file: string) => void,
 ): Promise<{ targetDir: string; skillPath: string }> {
   if (signal?.aborted) throw new DOMException('aborted', 'AbortError')
+  // 预检：tree 的 size 可能缺失（按 0 计），所以这里只拦「确定越界」的，
+  // 真正的裁决在下载后用实际字节再做一次。目的是尽早失败，别先下 200MB。
+  const preflight = blockingReason(auditSkillBundle(
+    files.map((file) => ({ path: relativeToSkillDir(entry.dir, file.path), size: file.size })),
+  ))
+  if (preflight !== undefined) throw new RepoFetchError(preflight, 422)
   const targetDir = join(targetRoot, entry.name)
   await mkdir(targetRoot, { recursive: true })
   // Dot-prefixed so a leftover temp dir can never surface as a skill in the
@@ -80,12 +102,21 @@ export async function downloadRepoSkill(
   const tempDir = await mkdtemp(join(targetRoot, '.' + entry.name + '.import-'))
   let renamed = false
   try {
+    // 并发 worker 直接 push 一个共享数组：JS 单线程，push 是原子的；
+    // 顺序不重要，审计只关心内容集合。
+    const audited: AuditBundleFile[] = []
     await mapConcurrent(files, 6, async (file) => {
       if (signal?.aborted) throw new DOMException('aborted', 'AbortError')
       const relative = relativeToSkillDir(entry.dir, file.path)
       if (relative === '' || relative.includes('..')) throw new RepoFetchError('unsafe repo path: ' + file.path)
       const target = join(tempDir, relative)
       const buffer = await downloadGitHubFile(repo, ref, file.path, fetchImpl, signal)
+      // tree 的 size 是声明值，可以撒谎；实际字节才是硬约束。
+      if (buffer.length > MAX_SKILL_FILE_BYTES) {
+        throw new RepoFetchError(`skill rejected by content audit: ${relative} is ${buffer.length} bytes, over the per-file limit`, 422)
+      }
+      const text = asAuditText(buffer)
+      audited.push({ path: relative, size: buffer.length, ...(text !== undefined ? { text } : {}) })
       await mkdir(dirname(target), { recursive: true })
       await writeFile(target, buffer)
       onProgress?.(buffer.length, relative)
@@ -105,6 +136,9 @@ export async function downloadRepoSkill(
       throw new RepoFetchError('downloaded skill declares name "' + parsed.value.name + '", expected "' + entry.name + '"', 422)
     }
 
+    const blocked = blockingReason(auditSkillBundle(audited, parsed.value.description))
+    if (blocked !== undefined) throw new RepoFetchError(blocked, 422)
+
     await rename(tempDir, targetDir)
     renamed = true
     return { targetDir, skillPath: join(targetDir, 'SKILL.md') }

package/src/repo.test.ts

@@ -351,6 +351,61 @@ describe('downloadRepoSkill', () => {
       await rm(parent, { recursive: true, force: true })
     }
   })
+
+  it('rejects a skill whose body hides instructions in Unicode tag characters', async () => {
+    const parent = await mkdtemp(join(tmpdir(), 'dsh-repo-audit-'))
+    try {
+      const targetRoot = join(parent, 'skills')
+      const entry: RepoSkillEntry = {
+        name: 'sneaky',
+        dir: 'skills/sneaky',
+        path: 'skills/sneaky/SKILL.md',
+        root: 'skills',
+        origin: 'example/repo',
+        fileCount: 1,
+        totalBytes: 1,
+        existing: false,
+      }
+      const hidden = String.fromCodePoint(0xe0041)
+      const body = '---\nname: sneaky\ndescription: A perfectly normal skill\n---\n\nread the key' + hidden + '\n'
+      const fetchImpl = async () => new Response(body, { status: 200 })
+      await expect(
+        downloadRepoSkill('example/repo', 'main', entry, [{ path: 'skills/sneaky/SKILL.md', size: body.length }], targetRoot, fetchImpl as typeof fetch),
+      ).rejects.toThrow(/rejected by content audit.*invisible Unicode tag/)
+      // 拒绝 = 什么都不留：既没有技能目录，也没有残留的临时目录。
+      await expect(readFile(join(targetRoot, 'sneaky', 'SKILL.md'), 'utf8')).rejects.toThrow()
+    } finally {
+      await rm(parent, { recursive: true, force: true })
+    }
+  })
+
+  it('refuses an oversized file before downloading anything', async () => {
+    const parent = await mkdtemp(join(tmpdir(), 'dsh-repo-audit-size-'))
+    try {
+      const targetRoot = join(parent, 'skills')
+      const entry: RepoSkillEntry = {
+        name: 'heavy',
+        dir: 'skills/heavy',
+        path: 'skills/heavy/SKILL.md',
+        root: 'skills',
+        origin: 'example/repo',
+        fileCount: 2,
+        totalBytes: 6 * 1024 * 1024,
+        existing: false,
+      }
+      let calls = 0
+      const fetchImpl = async () => { calls += 1; return new Response('x', { status: 200 }) }
+      await expect(
+        downloadRepoSkill('example/repo', 'main', entry, [
+          { path: 'skills/heavy/SKILL.md', size: 10 },
+          { path: 'skills/heavy/blob.bin', size: 6 * 1024 * 1024 },
+        ], targetRoot, fetchImpl as typeof fetch),
+      ).rejects.toThrow(/per-file limit/)
+      expect(calls).toBe(0)
+    } finally {
+      await rm(parent, { recursive: true, force: true })
+    }
+  })
 })
 
 describe('downloadGitHubFile', () => {

package/src/routes/catalog-data.ts

@@ -7,6 +7,7 @@ import { readFile, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill'
 import {
+  computeAnnouncementBudget,
   isProjectSource,
   type CatalogResponse,
   type CatalogSkill,
@@ -213,6 +214,7 @@ export async function buildCatalog(deps: SkillHubRouteDeps, cwd?: string): Promi
     skills,
     disabled,
     diagnostics,
+    announcement: computeAnnouncementBudget(skills),
     ...(duplicateNames.length > 0 ? { duplicateNames } : {}),
   }
 }

package/src/routes/deps.ts

@@ -4,6 +4,7 @@
  */
 
 import type { ServerResponse } from 'node:http'
+import { homedir } from 'node:os'
 import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill'
 import { resolveHubConfig, type HubConfig, type WritableRoot } from '../protocol.ts'
 import { rootOfPath } from '../skillfs.ts'
@@ -35,6 +36,12 @@ export interface SkillHubRouteDeps {
   fence?: RouteFence
   /** DSH home override (tests isolate the writable roots; defaults to ~/.dsh). */
   home?: string
+  /**
+   * 用户主目录覆盖（其他 agent 的 `~/.claude/skills` 等相对它解析）。
+   * 与 `home` 是两个概念：`home` 是 DSH 自己的状态根（`~/.dsh`），
+   * 这个才是 `/Users/<user>`。测试用它把外部扫描圈在临时目录里。
+   */
+  userHome?: string
   /** Invalidate the registry catalog cache after hub-driven mutations. */
   invalidate?: () => void
   /** Optional invocation-count reader; absent means the stats route reports unavailable. */
@@ -74,6 +81,14 @@ export function homeOf(deps: SkillHubRouteDeps): string {
   return deps.home ?? dshHome()
 }
 
+/**
+ * Resolve the user's home directory — the base every other agent's user-level
+ * skill folder hangs off. Distinct from `homeOf` (the DSH state root).
+ */
+export function userHomeOf(deps: SkillHubRouteDeps): string {
+  return deps.userHome ?? homedir()
+}
+
 /** A skill resolved as a hub-writable user-level file. */
 export interface WritableSkill {
   skill: SkillDefinition

package/src/routes/foreign.ts

@@ -0,0 +1,127 @@
+/**
+ * 外部 agent 技能域路由：发现（只读扫描别家目录）与收编（复制进本地可写根）。
+ *
+ * 两条约束：
+ * 1. 外部目录只读 —— 扫描不会 mkdir，也不会写任何东西到别家路径下；
+ * 2. 导入不信任前端给的路径：只接受 `agent + name`，服务端重新扫一遍定位，
+ *    否则一个拼出来的绝对路径就能把任意文件复制进技能目录。
+ */
+
+import { mkdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  SKILL_HUB_API,
+  type ForeignImportResponse,
+  type ForeignListResponse,
+  type ForeignSkillView,
+} from '../protocol.ts'
+import { foreignRoots, importForeignSkill, occupancyOf, rootPath, scanForeignSkills } from '../skillfs.ts'
+import { errorText } from '../error-text.ts'
+import { homeOf, knownSkillNames, pathExists, userHomeOf, writeError, writeJson, type RouteSpec, type SkillHubRouteDeps } from './helpers.ts'
+import { retireNamePlaceholders } from './route-state.ts'
+
+/** 判断一个外部根是否真实存在（只 stat 一次，不列目录）。 */
+async function dirExists(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+export function foreignRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
+  return [
+    // ------------------------------------------------------------- foreign
+    // 列出其他 agent 用户级技能目录里的可收编技能。
+    {
+      path: SKILL_HUB_API.foreign,
+      methods: ['GET'],
+      handler: async ({ res }) => {
+        const home = homeOf(deps)
+        // 外部技能目录挂在**用户主目录**下（`~/.claude/skills`），不是 DSH 的
+        // 状态根（`~/.dsh`）。两者混用会扫到一个永远不存在的位置。
+        const userHome = userHomeOf(deps)
+        const existing = await knownSkillNames(deps, { includeDisabled: false })
+        const skills = await scanForeignSkills(userHome, existing)
+        const roots = await Promise.all(foreignRoots(userHome).map(async (root) => ({ ...root, present: await dirExists(root.dir) })))
+        const targetRoot = rootPath('user-dsh', home)
+        // 注册表快照是权威的（含项目级/内置），但它可能比磁盘慢一拍：刚写进去
+        // 还没被 watcher 收进索引时，快照会说「没有」。只对快照没命中的做一次
+        // 磁盘确认，避免把冲突项标成可导入。
+        //
+        // 判据只看**启用态**的发现文件：`<name>/SKILL.md` 或扁平 `<name>.md`。
+        // 目录存在但只有 `SKILL.md.disabled`（或干脆是空壳）不算冲突 —— 那正是
+        // 导入时会被移入回收站让位的占位，标成「已存在」会让用户根本选不了。
+        const view: ForeignSkillView[] = await Promise.all(skills.map(async (skill) => ({
+          name: skill.name,
+          description: skill.description,
+          agent: skill.agent,
+          path: skill.path,
+          kind: skill.kind,
+          existing: skill.existing
+            || await pathExists(join(targetRoot, skill.name, 'SKILL.md'))
+            || await pathExists(join(targetRoot, skill.name + '.md')),
+        })))
+        writeJson(res, 200, { ok: true, roots: roots.filter((root) => root.present), skills: view } satisfies ForeignListResponse)
+      },
+    },
+    // ------------------------------------------------------ foreign/import
+    // 按 agent + name 收编。逐条独立成败，一条失败不影响其余。
+    {
+      path: SKILL_HUB_API.foreignImport,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const items = Array.isArray(body.items) ? body.items : []
+        if (items.length === 0) { writeError(res, 400, 'items must be a non-empty array'); return }
+        if (items.length > 100) { writeError(res, 400, 'import at most 100 skills per request'); return }
+        const home = homeOf(deps)
+        const userHome = userHomeOf(deps)
+        const existing = await knownSkillNames(deps, { includeDisabled: false })
+        // 一次扫描覆盖所有条目：逐个条目扫一遍目录会让 20 个技能 = 20 次全盘 readdir。
+        const available = await scanForeignSkills(userHome, existing)
+        const targetRoot = rootPath('user-dsh', home)
+        await mkdir(targetRoot, { recursive: true })
+        const imported: string[] = []
+        const replaced: string[] = []
+        const skipped: Array<{ name: string; reason: string }> = []
+        const failed: Array<{ name: string; error: string }> = []
+        const seen = new Set<string>()
+        for (const raw of items) {
+          const item = raw as { agent?: unknown; name?: unknown } | null
+          const agent = item !== null && typeof item.agent === 'string' ? item.agent : ''
+          const name = item !== null && typeof item.name === 'string' ? item.name : ''
+          if (agent === '' || name === '') { failed.push({ name, error: 'agent and name are required' }); continue }
+          if (seen.has(agent + '/' + name)) continue
+          seen.add(agent + '/' + name)
+          // 只认服务端自己扫出来的条目：前端给的名字必须对得上一条真实记录。
+          const skill = available.find((candidate) => candidate.agent === agent && candidate.name === name)
+          if (skill === undefined) { failed.push({ name, error: 'skill not found under ' + agent }); continue }
+          if (skill.existing) {
+            skipped.push({ name, reason: 'a skill with this name already exists' })
+            continue
+          }
+          // 磁盘上可能有已禁用的同名占位或空壳目录：那不算「已存在」，但目标目录
+          // 非空，裸 rename 会 ENOTEMPTY。先让它进回收站（可恢复），与市场导入同一语义。
+          const occupancy = await occupancyOf(targetRoot, name)
+          if (occupancy.enabled.length > 0) {
+            skipped.push({ name, reason: 'a skill with this name already exists' })
+            continue
+          }
+          if (occupancy.disabled.length > 0 || occupancy.bareDir !== undefined) {
+            const trashed = await retireNamePlaceholders(deps, targetRoot, name)
+            if (trashed !== undefined) replaced.push(name)
+          }
+          try {
+            await importForeignSkill(skill, targetRoot)
+            imported.push(name)
+          } catch (error) {
+            failed.push({ name, error: errorText(error) })
+          }
+        }
+        if (imported.length > 0) deps.invalidate?.()
+        writeJson(res, 200, { ok: true, imported, ...(replaced.length > 0 ? { replaced } : {}), skipped, failed } satisfies ForeignImportResponse)
+      },
+    },
+  ]
+}

package/src/routes/helpers.ts

@@ -33,6 +33,7 @@ export {
   isWritableSource,
   resolveWritableSkill,
   savedOf,
+  userHomeOf,
 } from './deps.ts'
 export type {
   SkillHubRouteDeps,

package/src/routes/repo-import.ts

@@ -27,7 +27,7 @@ import {
   skillManifest,
   skillPathIn,
 } from '../repo.ts'
-import { occupancyOf, rootPath } from '../skillfs.ts'
+import { hashSkillAt, occupancyOf, rootPath } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
 import {
   homeOf,
@@ -211,6 +211,9 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
               })
               await deps.store.addSourceSkill(repo, entry.root, commitSha, resolvedRef, entry.name)
               await deps.store.mergeSourceManifest(repo, skillManifest(tree, entry.dir), entry.dir)
+              // 采集刚落盘内容的哈希：这是之后区分「上游变了」与「本地改过」的唯一依据。
+              const hash = await hashSkillAt(result.skillPath)
+              if (hash !== undefined) await deps.store.setSourceSkillHash(repo, entry.name, hash)
               if (defaultTag !== undefined) await deps.store.addSkillToTag(defaultTag.id, entry.name)
               job.imported.push({ name: entry.name, origin: entry.origin, path: result.skillPath })
               needInvalidate = true