dsh-skill-hub 0.3.13 → 0.3.15

package/src/routes/helpers.ts

@@ -8,7 +8,7 @@
  */
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
-import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import type { WebRoute, WebRouteKind } from '@deepseek-ai/dsh-host-webserver'
 import { disabledGate, type SkillHubRouteDeps } from './deps.ts'
 import { isLoopbackRequest, readJsonBody, writeError, writeRouteError } from './http.ts'
 
@@ -65,6 +65,13 @@ export type RouteHandler = (context: RouteContext) => Promise<void>
 /** One declarative route: path + accepted methods + the business handler. */
 export interface RouteSpec {
   path: string
+  /**
+   * Match kind: 'exact' (default) matches the pathname verbatim; 'prefix'
+   * matches the path and everything beneath it. The webserver consults the
+   * exact table first and then resolves prefixes longest-first, so a prefix
+   * route is a catch-all that can never shadow a real route.
+   */
+  kind?: WebRouteKind
   /** Accepted HTTP methods; anything else answers 405. */
   methods: readonly ('GET' | 'POST')[]
   /** POST requests must carry a JSON body (400 when missing/unparseable). */
@@ -82,7 +89,7 @@ export interface RouteSpec {
  */
 export function createRoute(deps: SkillHubRouteDeps, spec: RouteSpec): WebRoute {
   return {
-    kind: 'exact',
+    kind: spec.kind ?? 'exact',
     path: spec.path,
     handler: async (req, res) => {
       if (!isLoopbackRequest(req)) { writeError(res, 403, 'forbidden: loopback-only'); return }

package/src/routes/market.ts

@@ -1,11 +1,12 @@
 /**
  * 市场域路由：market 列表 / source 增删 / ref 锁定 / versions 选择器 /
- * check 更新检查 / stats 星标统计 / sync 对齐版本。从 routes.ts 原样搬出，
- * handler 逻辑不变。
+ * source/check 更新检查 / stats 星标统计 / source/sync 对齐版本。
+ * 从 routes.ts 原样搬出，handler 逻辑不变。
  */
 
 import {
   SKILL_HUB_API,
+  SKILL_HUB_API_DEPRECATED_MARKET_CHECK,
   type MarketCheckResponse,
   type MarketSourceResponse,
   type MarketSourcesResponse,
@@ -28,6 +29,7 @@ import {
   readString,
   writeError,
   writeJson,
+  type RouteHandler,
   type RouteSpec,
   type SkillHubRouteDeps,
 } from './helpers.ts'
@@ -42,6 +44,41 @@ import {
 
 /** 市场域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 export function marketRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
+  // Update check over every market source: compares the pinned ref's commit
+  // against the recorded baseline and surfaces newer releases. 5-minute
+  // throttle mirrors the source check. Shared by the canonical route and its
+  // deprecated alias, so the two can never drift apart.
+  const checkMarketSources: RouteHandler = async ({ res }) => {
+    const sources = await deps.store.listMarketSources()
+    if (lastMarketCheck.size > 500) lastMarketCheck.clear()
+    const results: MarketCheckResponse['results'] = []
+    for (const source of sources) {
+      const base = { repo: source.repo, ...(source.ref !== undefined ? { ref: source.ref } : {}) }
+      const now = Date.now()
+      const last = lastMarketCheck.get(source.repo) ?? 0
+      if (now - last < MIN_CHECK_INTERVAL_MS) {
+        results.push({ ...base, updateAvailable: false, commitSha: source.commitSha ?? '', throttled: true })
+        continue
+      }
+      try {
+        const latestTag = await getLatestReleaseTag(source.repo)
+        if (source.ref === undefined) {
+          // Not pinned yet: report the latest release so the UI can
+          // suggest pinning, but never claim an update.
+          results.push({ ...base, updateAvailable: false, commitSha: source.commitSha ?? '', ...(latestTag !== undefined ? { latestTag } : {}) })
+          continue
+        }
+        const latest = await getLatestCommit(source.repo, source.ref)
+        lastMarketCheck.set(source.repo, now)
+        const commitMoved = source.commitSha !== undefined && latest.commitSha !== source.commitSha
+        const newRelease = latestTag !== undefined && latestTag !== source.ref
+        results.push({ ...base, updateAvailable: commitMoved || newRelease, commitSha: latest.commitSha, ...(newRelease ? { latestTag } : {}) })
+      } catch (error) {
+        results.push({ ...base, updateAvailable: false, commitSha: source.commitSha ?? '', error: errorText(error) })
+      }
+    }
+    writeJson(res, 200, { ok: true, results } satisfies MarketCheckResponse)
+  }
   return [
     // --------------------------------------------------------------- market
     // Market sources: the user adds repo slugs; each source can
@@ -117,44 +154,19 @@ export function marketRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         } satisfies MarketSourceVersionsResponse)
       },
     },
-    // ------------------------------------------------------- market/check
-    // Update check over every market source: compares the pinned ref's
-    // commit against the recorded baseline and surfaces newer releases.
-    // 5-minute throttle mirrors the source check.
+    // ------------------------------------------------- market/source/check
+    // Canonical path; the sibling sync route lives at market/source/sync.
     {
       path: SKILL_HUB_API.marketCheck,
       methods: ['GET'],
-      handler: async ({ res }) => {
-        const sources = await deps.store.listMarketSources()
-        if (lastMarketCheck.size > 500) lastMarketCheck.clear()
-        const results: MarketCheckResponse['results'] = []
-        for (const source of sources) {
-          const base = { repo: source.repo, ...(source.ref !== undefined ? { ref: source.ref } : {}) }
-          const now = Date.now()
-          const last = lastMarketCheck.get(source.repo) ?? 0
-          if (now - last < MIN_CHECK_INTERVAL_MS) {
-            results.push({ ...base, updateAvailable: false, commitSha: source.commitSha ?? '', throttled: true })
-            continue
-          }
-          try {
-            const latestTag = await getLatestReleaseTag(source.repo)
-            if (source.ref === undefined) {
-              // Not pinned yet: report the latest release so the UI can
-              // suggest pinning, but never claim an update.
-              results.push({ ...base, updateAvailable: false, commitSha: source.commitSha ?? '', ...(latestTag !== undefined ? { latestTag } : {}) })
-              continue
-            }
-            const latest = await getLatestCommit(source.repo, source.ref)
-            lastMarketCheck.set(source.repo, now)
-            const commitMoved = source.commitSha !== undefined && latest.commitSha !== source.commitSha
-            const newRelease = latestTag !== undefined && latestTag !== source.ref
-            results.push({ ...base, updateAvailable: commitMoved || newRelease, commitSha: latest.commitSha, ...(newRelease ? { latestTag } : {}) })
-          } catch (error) {
-            results.push({ ...base, updateAvailable: false, commitSha: source.commitSha ?? '', error: errorText(error) })
-          }
-        }
-        writeJson(res, 200, { ok: true, results } satisfies MarketCheckResponse)
-      },
+      handler: checkMarketSources,
+    },
+    // Deprecated alias, kept for one release: a browser tab still running the
+    // previous client bundle calls the old path until it reloads.
+    {
+      path: SKILL_HUB_API_DEPRECATED_MARKET_CHECK,
+      methods: ['GET'],
+      handler: checkMarketSources,
     },
     // ------------------------------------------------------- market/stats
     // Stars + release-asset downloads per market source. Stale-while-revalidate:

package/src/routes/repo-import.ts

@@ -26,6 +26,7 @@ import {
   normalizeRepoInput,
   repoSlug,
   skillManifest,
+  skillPathIn,
 } from '../repo.ts'
 import { rootPath } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
@@ -158,7 +159,7 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           for (const entry of selected) {
             if (controller.signal.aborted) break
             job.current = entry.name
-            job.currentFile = entry.dir + '/SKILL.md'
+            job.currentFile = entry.path
             if (entry.existing) {
               job.skipped.push({ name: entry.name, reason: 'exists' })
               job.downloadedBytes += entry.totalBytes
@@ -176,7 +177,7 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             try {
               const result = await downloadRepoSkill(repo, resolvedRef, entry, files, targetRoot, fetch, controller.signal, (bytes, file) => {
                 job.downloadedBytes += bytes
-                job.currentFile = entry.dir + '/' + file
+                job.currentFile = skillPathIn(entry.dir, file)
               })
               await deps.store.addSourceSkill(repo, entry.root, commitSha, resolvedRef, entry.name)
               await deps.store.mergeSourceManifest(repo, skillManifest(tree, entry.dir), entry.dir)

package/src/routes/sources.ts

@@ -27,6 +27,7 @@ import {
   repoSkillEntry,
   repoSlug,
   skillDirOf,
+  skillFileAt,
   skillManifest,
 } from '../repo.ts'
 import { clearTrash, restoreSkill, rootOfPath, rootPath, trashSkill } from '../skillfs.ts'
@@ -144,7 +145,7 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             // 上游可能用分类子目录（skills/engineering/<name>/）且目录会移动：
             // 先在上游 tree 里搜真实位置，manifest 兜底，否则嵌套技能会 404。
             entry.dir = skillDirOf(source, name, tree.map((item) => item.path))
-            entry.path = entry.dir + '/SKILL.md'
+            entry.path = skillFileAt(entry.dir)
             const files = collectRepoSkillFiles(tree, entry.dir)
             if (files.length === 0) { failed.push({ name, error: 'skill missing upstream' }); continue }
             const targetDir = join(targetRoot, name)

package/src/routes.test.ts

@@ -6,7 +6,7 @@ import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { makeRoutes, type SkillHubRouteDeps } from './routes.ts'
 import { SkillHubStore, statePath } from './store.ts'
-import { SKILL_HUB_API, type CatalogResponse, type ConfigResponse, type ErrorResponse, type HubConfig } from './protocol.ts'
+import { SKILL_HUB_API, SKILL_HUB_API_DEPRECATED_MARKET_CHECK, SKILL_HUB_API_ROOT, type CatalogResponse, type ConfigResponse, type ErrorResponse, type HubConfig } from './protocol.ts'
 
 /** Minimal response double recording status/headers/body. */
 class FakeResponse {
@@ -495,6 +495,49 @@ describe('skill-hub routes', () => {
     expect(body.saved).toEqual({ enabled: false })
   })
 
+  it('never echoes the github token back from the config route', async () => {
+    const token = 'ghp_secretsecret123abc'
+    // GET with a token in effect: the flag says yes, no payload field carries it.
+    const getRoutes = makeRoutes({
+      ...deps,
+      config: () => ({ enabled: true, announceToAgent: true, githubToken: token }),
+      saved: () => ({ githubToken: token }),
+    })
+    const get = new FakeResponse()
+    await getRoutes.find((r) => r.path === SKILL_HUB_API.config)?.handler(fakeReq('GET', SKILL_HUB_API.config), get as never)
+    expect(get.status).toBe(200)
+    const body = get.json() as ConfigResponse
+    expect(body.githubTokenSet).toBe(true)
+    expect(body.config).not.toHaveProperty('githubToken')
+    expect(body.saved).not.toHaveProperty('githubToken')
+    expect(get.body).not.toContain(token)
+
+    // POST, local merge path (no owner updateConfig).
+    const merged = new FakeResponse()
+    await getRoutes.find((r) => r.path === SKILL_HUB_API.config)?.handler(fakeReq('POST', SKILL_HUB_API.config, { enabled: true }), merged as never)
+    expect(merged.status).toBe(200)
+    expect((merged.json() as ConfigResponse).config).not.toHaveProperty('githubToken')
+    expect(merged.body).not.toContain(token)
+
+    // POST, owner updateConfig path.
+    const updateConfig = async (): Promise<HubConfig> => ({ enabled: true, announceToAgent: true, showUseCount: true, showUseTime: true, showGroupSummary: true, githubToken: token })
+    const postRoutes = makeRoutes({ ...deps, updateConfig })
+    const posted = new FakeResponse()
+    await postRoutes.find((r) => r.path === SKILL_HUB_API.config)?.handler(fakeReq('POST', SKILL_HUB_API.config, { enabled: true }), posted as never)
+    expect(posted.status).toBe(200)
+    const postBody = posted.json() as ConfigResponse
+    expect(postBody.githubTokenSet).toBe(true)
+    expect(postBody.config).not.toHaveProperty('githubToken')
+    expect(posted.body).not.toContain(token)
+  })
+
+  it('reports githubTokenSet false when no token is configured', async () => {
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.config).handler(fakeReq('GET', SKILL_HUB_API.config), res as never)
+    const body = res.json() as ConfigResponse
+    expect(body.githubTokenSet).toBe(false)
+  })
+
   it('patches the hub config through the owner updateConfig', async () => {
     const patches: Array<Partial<HubConfig>> = []
     const updateConfig = async (patch: Partial<HubConfig>): Promise<HubConfig> => {
@@ -970,3 +1013,66 @@ describe('skill-hub routes', () => {
   })
 
 })
+
+describe('skill-hub API surface', () => {
+  let dir: string
+  let home: string
+  let store: SkillHubStore
+  let deps: SkillHubRouteDeps
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hub-api-'))
+    home = join(dir, 'home')
+    await mkdir(join(home, 'skills'), { recursive: true })
+    store = new SkillHubStore(statePath(home))
+    deps = { skills: { snapshot: async () => ({ skills: [], complete: true }), get: async () => undefined }, store, home }
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('keeps every path inside the family root and registered', () => {
+    const routes = makeRoutes(deps)
+    const registered = new Set(routes.filter((route) => route.kind === 'exact').map((route) => route.path))
+    const declared = Object.values(SKILL_HUB_API)
+    for (const path of declared) expect(path.startsWith(SKILL_HUB_API_ROOT + '/')).toBe(true)
+    // 常量与注册表互为子集：一个声明了没注册（客户端必然 404），或注册了没声明
+    // （客户端永远调不到），都是漂移。唯一的豁免是显式弃用别名。
+    expect([...registered].sort()).toEqual([...declared, SKILL_HUB_API_DEPRECATED_MARKET_CHECK].sort())
+    expect(registered.has(SKILL_HUB_API_DEPRECATED_MARKET_CHECK)).toBe(true)
+  })
+
+  it('pairs the market update check with the sync that acts on it', () => {
+    // 曾经的坑：check 在 /market/check，sync 在 /market/source/sync，
+    // 写客户端时很容易把同步写成 /market/sync（未命中路径还会回 401）。
+    expect(SKILL_HUB_API.marketCheck).toBe('/api/skill-hub/market/source/check')
+    for (const path of [SKILL_HUB_API.marketCheck, SKILL_HUB_API.marketSync]) {
+      expect(path.startsWith('/api/skill-hub/market/source/')).toBe(true)
+    }
+    expect(SKILL_HUB_API_DEPRECATED_MARKET_CHECK).not.toBe(SKILL_HUB_API.marketCheck)
+  })
+
+  it('answers the deprecated market-check alias instead of 404', async () => {
+    const routes = makeRoutes(deps)
+    const route = routes.find((r) => r.path === SKILL_HUB_API_DEPRECATED_MARKET_CHECK)
+    expect(route).toBeDefined()
+    const res = new FakeResponse()
+    await route?.handler(fakeReq('GET', SKILL_HUB_API_DEPRECATED_MARKET_CHECK), res as never)
+    // Same handler as the canonical route: a list of per-source results.
+    expect(res.status).toBe(200)
+    expect((res.json() as { results: unknown[] }).results).toEqual([])
+  })
+
+  it('registers one 404 catch-all covering the whole family', async () => {
+    const routes = makeRoutes(deps)
+    const catchAll = routes.filter((route) => route.kind === 'prefix')
+    expect(catchAll).toHaveLength(1)
+    expect(catchAll[0].path).toBe(SKILL_HUB_API_ROOT)
+    // 未知路径给出写明路径的 404，而不是让请求落到宿主 fallback 的 401。
+    const res = new FakeResponse()
+    await catchAll[0].handler(fakeReq('GET', '/api/skill-hub/market/sync'), res as never)
+    expect(res.status).toBe(404)
+    expect((res.json() as ErrorResponse).error).toContain('/api/skill-hub/market/sync')
+  })
+})

package/src/routes.ts

@@ -13,7 +13,8 @@
  */
 
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
-import { createRoute, type SkillHubRouteDeps, type SkillLookupLike } from './routes/helpers.ts'
+import { SKILL_HUB_API_ROOT } from './protocol.ts'
+import { createRoute, writeError, type SkillHubRouteDeps } from './routes/helpers.ts'
 import { catalogRoutes } from './routes/catalog.ts'
 import { configRoutes } from './routes/config.ts'
 import { marketRoutes } from './routes/market.ts'
@@ -26,7 +27,7 @@ export type { SkillHubRouteDeps, SkillLookupLike } from './routes/helpers.ts'
 /**
  * Build every /api/skill-hub route.
  * @param deps - skill registry view + sidecar store.
- * @returns the exact-path routes.
+ * @returns the exact-path routes plus the family's 404 catch-all.
  */
 export function makeRoutes(deps: SkillHubRouteDeps): WebRoute[] {
   // 各域返回裸 spec，统一在这里包上请求围栏（回环信任 → 方法 → 总开关
@@ -39,5 +40,22 @@ export function makeRoutes(deps: SkillHubRouteDeps): WebRoute[] {
     ...groupRoutes(deps),
     ...sourceRoutes(deps),
   ]
-  return specs.map((spec) => createRoute(deps, spec))
+  return [
+    ...specs.map((spec) => createRoute(deps, spec)),
+    // 兜底：本族的未知路径。插件只注册精确路径，未命中的请求会落到宿主的
+    // SPA fallback，那里对 /api/* 统一回 401，排查时极易被误判成鉴权/令牌
+    // 问题，而真实原因是路径写错。这个 prefix 路由把整族纳入命名路由表，
+    // 于是未知路径在宿主侧变成「已命中」→ 由我们回一个写明路径的 404。
+    // 匹配顺序保证安全：宿主先查精确表、再按最长前缀命中，本路由不可能
+    // 抢走任何已注册的精确路由。
+    createRoute(deps, {
+      kind: 'prefix',
+      path: SKILL_HUB_API_ROOT,
+      methods: ['GET', 'POST'],
+      skipGate: true,
+      handler: async ({ res, url }) => {
+        writeError(res, 404, 'unknown skill-hub route: ' + url.pathname + ' (see SKILL_HUB_API in src/protocol/api.ts)')
+      },
+    }),
+  ]
 }

package/src/store/migrate.ts

@@ -1,4 +1,5 @@
 import type { DisabledSkill, HubConfig, MarketSourceRecord, MarketStatsSnapshot, SkillStatsCheckpoint, SkillTag, SourceRecord, TrashEntry } from '../protocol.ts'
+import { isValidRepoRoot } from '../protocol/repo.ts'
 import { STORE_VERSION } from './paths.ts'
 
 /** Normalized raw sidecar document after schema migration (fields still unvalidated). */
@@ -149,7 +150,7 @@ export function hydrateMigratedState(migrated: MigratedStore): HydratedState {
       const source = entry as { repo?: unknown; ref?: unknown; root?: unknown; commitSha?: unknown; skills?: unknown; manifest?: unknown } | null
       if (source !== null && typeof source === 'object' && typeof source.repo === 'string' && source.repo !== '' && Array.isArray(source.skills)) {
         const manifest = source.manifest as Record<string, unknown> | undefined
-        const rawRoot = typeof source.root === 'string' && source.root !== '' && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(source.root) ? source.root : 'skills'
+        const rawRoot = isValidRepoRoot(source.root) ? source.root : 'skills'
         sourcesByRepo.set(source.repo, {
           repo: source.repo,
           ...(typeof source.ref === 'string' && source.ref !== '' ? { ref: source.ref } : {}),
@@ -190,7 +191,7 @@ export function hydrateMigratedState(migrated: MigratedStore): HydratedState {
           path: item.path,
           movedAt: typeof item.movedAt === 'number' ? item.movedAt : 0,
           ...(typeof item.sourcePath === 'string' && item.sourcePath !== '' ? { sourcePath: item.sourcePath } : {}),
-          ...(origin !== null && typeof origin === 'object' && typeof origin.repo === 'string' && origin.repo !== '' && typeof origin.root === 'string' && origin.root !== '' && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(origin.root)
+          ...(origin !== null && typeof origin === 'object' && typeof origin.repo === 'string' && origin.repo !== '' && isValidRepoRoot(origin.root)
             ? {
                 origin: {
                   repo: origin.repo,

package/src/store/store.ts

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import type { DisabledSkill, HubConfig, MarketSourceRecord, MarketStatsSnapshot, SkillStatsCheckpoint, SkillTag, SourceRecord, TrashEntry } from '../protocol.ts'
+import { skillDirPrefix } from '../repo/discovery.ts'
 import { StoreError } from './errors.ts'
 import { hydrateMigratedState, migrateStore } from './migrate.ts'
 import { DEFAULT_SCENE_NAME, STORE_VERSION, statePath, type StoreFile } from './paths.ts'
@@ -351,14 +352,18 @@ export class SkillHubStore {
    * When `dir` is given, every baseline path under that skill directory is
    * dropped first, so files the upstream removed never linger in the
    * baseline and skew later update diffs.
+   *
+   * `dir` may be '' — a skill whose SKILL.md sits at the repo root. Its prefix
+   * is empty, so the whole baseline is replaced: that skill owns the tree, and
+   * keeping stale paths would make every later diff report "changed" forever.
    */
   async mergeSourceManifest(repo: string, manifest: Record<string, number>, dir?: string): Promise<void> {
     await this.ensureLoaded()
     const existing = this.sourcesByRepo.get(repo)
     if (existing === undefined || Object.keys(manifest).length === 0) return
     const base: Record<string, number> = { ...(existing.manifest ?? {}) }
-    if (dir !== undefined && dir !== '') {
-      const prefix = dir + '/'
+    if (dir !== undefined) {
+      const prefix = skillDirPrefix(dir)
       for (const path of Object.keys(base)) {
         if (path.startsWith(prefix)) delete base[path]
       }

package/src/store.test.ts

@@ -125,6 +125,26 @@ describe('SkillHubStore', () => {
     expect(again[0].manifest).toEqual({ 'skills/docx/SKILL.md': 120 })
   })
 
+  it('drops only the given skill directory from the baseline', async () => {
+    await store.addSourceSkill('a/b', 'skills', 'sha-1', undefined, 'docx')
+    await store.addSourceSkill('a/b', 'skills', 'sha-1', undefined, 'pdf')
+    await store.mergeSourceManifest('a/b', { 'skills/docx/SKILL.md': 1, 'skills/docx/gone.md': 2, 'skills/pdf/SKILL.md': 3 })
+    // Re-merging docx must drop its stale baseline without touching pdf.
+    await store.mergeSourceManifest('a/b', { 'skills/docx/SKILL.md': 1 }, 'skills/docx')
+    const sources = await store.listSources()
+    expect(sources[0].manifest).toEqual({ 'skills/pdf/SKILL.md': 3, 'skills/docx/SKILL.md': 1 })
+  })
+
+  it('replaces the whole baseline for a skill at the repo root', async () => {
+    await store.addSourceSkill('blader/humanizer', '', 'sha-1', undefined, 'humanizer')
+    await store.mergeSourceManifest('blader/humanizer', { 'SKILL.md': 1, 'old.md': 2 }, '')
+    await store.mergeSourceManifest('blader/humanizer', { 'SKILL.md': 900, 'README.md': 30 }, '')
+    const sources = await store.listSources()
+    // The empty prefix covers the whole tree, so the upstream-dropped old.md
+    // must not linger — otherwise the diff would report "changed" forever.
+    expect(sources[0].manifest).toEqual({ 'SKILL.md': 900, 'README.md': 30 })
+  })
+
   it('derives origins from sources and drops empty sources', async () => {
     await store.addSourceSkill('repo/a', 'skills', '', undefined, 'one')
     await store.addSourceSkill('repo/a', 'skills', '', undefined, 'two')
@@ -250,6 +270,36 @@ describe('SkillHubStore', () => {
     expect(await fresh.listDisabled()).toEqual([])
   })
 
+  it('keeps an empty root through a reload (repo-root skill), still coercing a corrupt one', async () => {
+    // 空 root 是「技能在仓库根」的合法取值：装载时把它改写成 skills 会让来源
+    // 对不上任何 blob，下一次「检查更新」就会把技能当成被上游删除 → 进回收站。
+    await writeFile(file, JSON.stringify({
+      version: 4,
+      sources: [
+        { repo: 'blader/humanizer', root: '', commitSha: 'sha-1', skills: ['humanizer'], manifest: { 'SKILL.md': 900 } },
+        { repo: 'a/b', root: '.hidden', commitSha: 'sha-2', skills: ['x'] },
+      ],
+    }), 'utf8')
+    const sources = await store.listSources()
+    expect(sources.find((s) => s.repo === 'blader/humanizer')?.root).toBe('')
+    // 损坏的 root 仍然回落到默认根。
+    expect(sources.find((s) => s.repo === 'a/b')?.root).toBe('skills')
+    // 写盘-再读一次仍然保持空 root。
+    await store.addMarketSource('new/repo')
+    const reloaded = new SkillHubStore(file)
+    expect((await reloaded.listSources()).find((s) => s.repo === 'blader/humanizer')?.root).toBe('')
+  })
+
+  it('keeps the origin of a trashed repo-root skill', async () => {
+    await writeFile(file, JSON.stringify({
+      version: 4,
+      trash: [{ name: 'humanizer', path: '/tmp/trash/humanizer', movedAt: 1, origin: { repo: 'blader/humanizer', root: '', commitSha: 'sha-1' } }],
+    }), 'utf8')
+    const entry = (await store.listTrash()).find((e) => e.name === 'humanizer')
+    // 空 root 曾被 sanitizer 丢掉整个 origin → 恢复后技能会变成「个人技能」。
+    expect(entry?.origin).toMatchObject({ repo: 'blader/humanizer', root: '' })
+  })
+
   it('migrates a v3 file (no skillStats) and persists a checkpoint round-trip at v4', async () => {
     // v3 旧文件：无 skillStats 字段 → 装载后检查点为空，写盘时版本升到当前。
     await writeFile(file, JSON.stringify({

package/src/update.ts

@@ -9,7 +9,7 @@
 
 import { createRequire } from 'node:module'
 import { errorText } from './error-text.ts'
-import { githubAuthHeaders } from './repo.ts'
+import { apiHeaders } from './repo.ts'
 import type { UpdateCheckResponse } from './protocol.ts'
 
 /** Repository checked for releases. Keep in sync with package.json. */
@@ -51,7 +51,9 @@ export async function checkLatestRelease(repo = UPDATE_REPO, fetchImpl: typeof f
   let response: Response
   try {
     response = await fetchImpl(url, {
-      headers: { accept: 'application/vnd.github+json', ...githubAuthHeaders() },
+      // apiHeaders() 而非手写等价物：它带上 `accept-encoding: identity`，
+      // 缺了它在「启动环境带代理」时响应会变成解不开的 gzip（见 github-client.ts）。
+      headers: apiHeaders(),
     })
   } catch (error) {
     return failure(errorText(error))