dsh-skill-hub 0.3.27 → 0.3.28

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

package/src/routes/sources.ts

@@ -30,8 +30,9 @@ import {
   skillFileAt,
   skillManifest,
 } from '../repo.ts'
-import { clearTrash, occupancyOf, restoreSkill, rootOfPath, rootPath, trashSkill, trashSourceOf, WRITABLE_ROOTS } from '../skillfs.ts'
+import { clearTrash, hashSkillAt, occupancyOf, restoreSkill, rootOfPath, rootPath, trashSkill, trashSourceOf, WRITABLE_ROOTS } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
+import { mapConcurrent } from '../concurrency.ts'
 import {
   buildCollections,
   homeOf,
@@ -45,6 +46,32 @@ import {
 } from './helpers.ts'
 import { MIN_CHECK_INTERVAL_MS, lastSourceCheck, replaceInPlace, retireNamePlaceholders } from './route-state.ts'
 
+/**
+ * 本地被改过的技能：磁盘内容哈希 ≠ 导入/同步时记录的哈希。
+ *
+ * 只对「记录里已有哈希」的技能判定 —— 旧记录没采集过哈希，硬比会得到
+ * 「全部已改」的假警报。技能目录读不到（被删/被移走）同样不算改过：
+ * 那是另一种状态，由发现诊断去报。
+ */
+async function localModifiedSkills(source: { skills: readonly string[]; localHashes?: Record<string, string> }, home: string): Promise<string[]> {
+  const hashes = source.localHashes
+  if (hashes === undefined || Object.keys(hashes).length === 0) return []
+  const base = rootPath('user-dsh', home)
+  const modified: string[] = []
+  // 有界并发，与 scanDiagnostics 同一理由：一个来源可能跟踪几十个技能，
+  // 裸 Promise.all 会同时打开上百个文件句柄。
+  await mapConcurrent(source.skills, 8, async (name) => {
+    const expected = hashes[name]
+    if (expected === undefined) return
+    const occupancy = await occupancyOf(base, name)
+    const path = occupancy.enabled[0] ?? occupancy.disabled[0]
+    if (path === undefined) return
+    const actual = await hashSkillAt(path)
+    if (actual !== undefined && actual !== expected) modified.push(name)
+  })
+  return modified.sort((a, b) => a.localeCompare(b))
+}
+
 /** 来源跟踪域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
   return [
@@ -78,9 +105,16 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         if (only !== undefined && source === undefined) { writeError(res, 404, 'source not found: ' + only); return }
         const sources = source !== undefined ? [source] : await deps.store.listSources()
         if (lastSourceCheck.size > 500) lastSourceCheck.clear()
+        const home = homeOf(deps)
         const results: SourceCheckResult[] = []
         for (const item of sources) {
-          const base = { repo: item.repo, ...(item.ref !== undefined ? { ref: item.ref } : {}) }
+          // 本地改动是磁盘事实，与网络检查成败无关，所以放在节流判断之前。
+          const modified = await localModifiedSkills(item, home)
+          const base = {
+            repo: item.repo,
+            ...(item.ref !== undefined ? { ref: item.ref } : {}),
+            ...(modified.length > 0 ? { localModified: modified } : {}),
+          }
           const now = Date.now()
           const last = lastSourceCheck.get(item.repo) ?? 0
           if (now - last < MIN_CHECK_INTERVAL_MS) {
@@ -131,6 +165,7 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         const targetRoot = rootPath('user-dsh', homeOf(deps))
         await mkdir(targetRoot, { recursive: true })
         const synced: string[] = []
+        const overwritten: string[] = []
         const failed: Array<{ name: string; error: string }> = []
         for (const name of targets) {
           // Sync writes under the user root: only accept real skill names
@@ -154,6 +189,14 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             // 落盘位置永远是目录包，所以本地无论是目录包还是扁平文件（启用或禁用）
             // 都得先让开，否则同名两形态会并存（issue #16 类）。
             const download = () => downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot)
+            // 覆盖前的如实上报：本地内容与记录不符时，这次同步会丢掉用户的改动。
+            // 是否继续由调用方（GUI 确认弹窗）决定，这里只负责不隐瞒。
+            const expectedHash = source.localHashes?.[name]
+            const localPath = occupancy.enabled[0] ?? occupancy.disabled[0]
+            if (expectedHash !== undefined && localPath !== undefined) {
+              const actualHash = await hashSkillAt(localPath)
+              if (actualHash !== undefined && actualHash !== expectedHash) overwritten.push(name)
+            }
             // 1) 禁用件与空壳让位（顺带清掉 sidecar 禁用记录）。
             await retireNamePlaceholders(deps, targetRoot, name)
             // 2) 启用件按「替换」语义处理：先挪到点前缀备份，下载失败则原样恢复。
@@ -175,6 +218,13 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
               await deps.store.removeDisabled(name)
             }
             await deps.store.mergeSourceManifest(repo, skillManifest(tree, entry.dir), entry.dir)
+            // 落盘后的实际内容才是新基线：禁用态文件已改名，所以要重新解析占位。
+            const settled = await occupancyOf(targetRoot, name)
+            const settledPath = settled.enabled[0] ?? settled.disabled[0]
+            if (settledPath !== undefined) {
+              const hash = await hashSkillAt(settledPath)
+              if (hash !== undefined) await deps.store.setSourceSkillHash(repo, name, hash)
+            }
             synced.push(name)
           } catch (error) {
             failed.push({ name, error: errorText(error) })
@@ -187,7 +237,7 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           await deps.store.setSourceCommit(repo, latest.commitSha)
         }
         deps.invalidate?.()
-        writeJson(res, 200, { ok: true, repo, commitSha: latest.commitSha, synced, failed } satisfies SourceSyncResponse)
+        writeJson(res, 200, { ok: true, repo, commitSha: latest.commitSha, synced, ...(overwritten.length > 0 ? { overwritten } : {}), failed } satisfies SourceSyncResponse)
       },
     },
     // ------------------------------------------------------- sources/delete