dsh-skill-hub 0.3.13 → 0.3.15

package/src/protocol.ts

@@ -8,7 +8,7 @@
  * 新代码可按需直引 `from './protocol/<domain>.ts'`。
  */
 
-export { SKILL_HUB_API } from './protocol/api.ts'
+export { SKILL_HUB_API, SKILL_HUB_API_ROOT, SKILL_HUB_API_DEPRECATED_MARKET_CHECK } from './protocol/api.ts'
 export type {
   WritableRoot,
   HubInvocation,
@@ -30,8 +30,8 @@ export type {
   CreateResponse,
 } from './protocol/catalog.ts'
 export type { SkillStat, StatsResponse, SkillStatsCheckpoint } from './protocol/stats.ts'
-export type { ErrorResponse, HubConfig, HubSettingsValue, ConfigResponse, ConfigRequest } from './protocol/config.ts'
-export { HUB_CONFIG_DEFAULTS, HEX_COLOR_RE, GITHUB_TOKEN_RE, resolveHubConfig } from './protocol/config.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'
 export type {
   MarketSourceRecord,
   MarketSourcesResponse,

package/src/repo/discovery.ts

@@ -2,14 +2,87 @@
  * 仓库技能发现：从 GitHub 仓库树推断技能根目录、列出可导入技能、
  * 生成目录清单并做上游差异比对。纯函数为主，便于单测。
  * 从 repo.ts 抽出。
+ *
+ * 路径语义集中在几个内部函数上：`skillDirPrefix`（技能目录在树里的前缀）、
+ * `isRepoTooling`（永不属于技能的仓库基建）、`skillFileAt`（目录内的
+ * SKILL.md 路径）。collect / manifest / diff 三处必须共用它们，否则差异
+ * 比对会永远报「有更新」。
  */
 
 import { isSkillName } from '@deepseek-ai/dsh-skill'
+import { REPO_ROOT_RE } from '../protocol/repo.ts'
 import type { RepoRoot, RepoSkillEntry } from '../protocol.ts'
 import type { RepoFile, RepoRef, RepoTreeItem } from './types.ts'
 
-/** Top-level directory pattern for a skill root: visible, non-dot, safe chars. First char must be alphanum. */
-const ROOT_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
+/**
+ * Sentinel root for a skill whose SKILL.md sits directly at the repository
+ * root instead of under a top-level directory. That layout is legal and used
+ * upstream (a Claude Code plugin manifest may declare `"skills": ["./"]`),
+ * and the empty string is the representation that composes with plain prefix
+ * arithmetic: an empty prefix *is* the repo root. Every path helper below
+ * special-cases it, because `'' + '/' + name` would produce a bogus absolute
+ * `/name` that matches no tree path.
+ */
+export const REPO_ROOT: RepoRoot = ''
+
+/** True when a root denotes the repo root itself (the repo is the skill dir). */
+export function isRepoRoot(root: string): boolean {
+  return root === REPO_ROOT
+}
+
+/**
+ * The tree prefix delimiting a skill directory: empty for the repo-root skill
+ * (it owns the whole tree), otherwise `<dir>/`. Single source for collect,
+ * manifest, diff and the store's baseline cleanup, so they can never disagree.
+ */
+export function skillDirPrefix(dir: string): string {
+  return isRepoRoot(dir) ? '' : dir + '/'
+}
+
+/**
+ * A path inside a skill directory, as it appears in the repo tree. Both
+ * directions of this mapping matter: repo paths are always '/'-joined (never
+ * node:path's OS separator, these are GitHub paths shown in the UI), and the
+ * repo-root case must not grow a leading slash.
+ */
+export function skillPathIn(dir: string, relative: string): string {
+  return skillDirPrefix(dir) + relative
+}
+
+/** The SKILL.md path inside a skill directory. */
+export function skillFileAt(dir: string): string {
+  return skillPathIn(dir, 'SKILL.md')
+}
+
+/**
+ * Top-level dot entries are repo tooling, never part of a skill: `.github/`,
+ * `.claude-plugin/`, `.gitignore`. Only the repo-root skill can reach them,
+ * since its prefix is empty and would otherwise sweep in the whole repo.
+ * Nested skill dirs cannot start with a dot (ROOT_RE), so this is a no-op
+ * for them.
+ */
+function isRepoTooling(path: string): boolean {
+  return path.startsWith('.')
+}
+
+/** Every tree blob belonging to a skill directory, sorted by path. */
+function skillTreeFiles(tree: readonly RepoTreeItem[], dir: string): RepoFile[] {
+  const prefix = skillDirPrefix(dir)
+  return tree
+    .filter((item) => item.type === 'blob' && item.path.startsWith(prefix) && !isRepoTooling(item.path))
+    .map((item) => ({ path: item.path, size: typeof item.size === 'number' ? item.size : 0 }))
+    .sort((a, b) => a.path.localeCompare(b.path))
+}
+
+/**
+ * A repo file's path relative to its skill directory — the path it is written
+ * to under the skill's own directory. `dir === ''` means the repo file path
+ * *is* the relative path; slicing `dir.length + 1` would eat its first
+ * character.
+ */
+export function relativeToSkillDir(dir: string, path: string): string {
+  return isRepoRoot(dir) ? path : path.slice(dir.length + 1)
+}
 
 /** `owner/repo` slug for a parsed reference. */
 export function repoSlug(ref: RepoRef): string {
@@ -49,22 +122,32 @@ export function normalizeRepoInput(input: string): RepoRef | null {
 
 /** Collect every file inside a skill directory, including SKILL.md itself. */
 export function collectRepoSkillFiles(tree: readonly RepoTreeItem[], dir: string): RepoFile[] {
-  const prefix = dir + '/'
-  return tree
-    .filter((item) => item.type === 'blob' && item.path.startsWith(prefix))
-    .map((item) => ({ path: item.path, size: typeof item.size === 'number' ? item.size : 0 }))
-    .sort((a, b) => a.path.localeCompare(b.path))
+  return skillTreeFiles(tree, dir)
 }
 
-/** Compute an origin collection name. Multiple roots split by root, one root keeps the repo slug. */
+/**
+ * Compute an origin collection name. Multiple roots split by root, one root
+ * keeps the repo slug. The repo-root skill's name *is* the repo slug, so it
+ * never gets a trailing-slash suffix (`owner/repo/`).
+ */
 export function originForRoot(repo: string, rootsPresent: ReadonlySet<string>, root: string): string {
-  return rootsPresent.size > 1 ? `${repo}/${root}` : repo
+  if (rootsPresent.size <= 1) return repo
+  return isRepoRoot(root) ? repo : `${repo}/${root}`
 }
 
 /** Discover importable skills from a repo tree. Invalid names are ignored. Roots are auto-derived from the top-level directory of each SKILL.md. */
 export function discoverRepoEntries(tree: readonly RepoTreeItem[], repo: string, existingNames: ReadonlySet<string> = new Set()): RepoSkillEntry[] {
   const candidates: Array<{ root: RepoRoot; dir: string; name: string; path: string }> = []
   const rootsPresent = new Set<string>()
+  // Repo-root layout: `SKILL.md` at the very top of the tree, the whole repo
+  // being one skill. The name comes from the repo slug; downloadRepoSkill
+  // re-checks it against the frontmatter and rejects a mismatch with a 422,
+  // so a wrong guess is reported rather than silently mis-installed.
+  const repoName = repo.slice(repo.lastIndexOf('/') + 1)
+  if (isSkillName(repoName) && tree.some((item) => item.type === 'blob' && item.path === 'SKILL.md')) {
+    rootsPresent.add(REPO_ROOT)
+    candidates.push({ root: REPO_ROOT, dir: REPO_ROOT, name: repoName, path: 'SKILL.md' })
+  }
   for (const item of tree) {
     if (item.type !== 'blob') continue
     // Any SKILL.md at depth >=2: top segment is the root, last segment is the skill name (may be nested like root/category/name/SKILL.md)
@@ -72,7 +155,7 @@ export function discoverRepoEntries(tree: readonly RepoTreeItem[], repo: string,
     if (slash === -1) continue
     if (!item.path.endsWith('/SKILL.md')) continue
     const root = item.path.slice(0, slash)
-    if (!ROOT_RE.test(root)) continue
+    if (!REPO_ROOT_RE.test(root)) continue
     const dir = item.path.slice(0, -'/SKILL.md'.length)
     // dir must be at least root/name (reject bare root/SKILL.md)
     if (dir === root || dir.length <= root.length + 1) continue
@@ -98,15 +181,15 @@ export function discoverRepoEntries(tree: readonly RepoTreeItem[], repo: string,
     .sort((a, b) => a.name.localeCompare(b.name))
 }
 
-/** Build a path→size manifest for one skill directory from a repo tree. */
+/**
+ * Build a path→size manifest for one skill directory from a repo tree.
+ * Shares `skillTreeFiles` with collectRepoSkillFiles: a manifest that
+ * disagreed with the collected file set would make every update diff report
+ * "changed" forever.
+ */
 export function skillManifest(tree: readonly RepoTreeItem[], dir: string): Record<string, number> {
-  const prefix = dir + '/'
   const manifest: Record<string, number> = {}
-  for (const item of tree) {
-    if (item.type === 'blob' && item.path.startsWith(prefix)) {
-      manifest[item.path] = typeof item.size === 'number' ? item.size : 0
-    }
-  }
+  for (const file of skillTreeFiles(tree, dir)) manifest[file.path] = file.size
   return manifest
 }
 
@@ -119,12 +202,19 @@ export function skillManifest(tree: readonly RepoTreeItem[], dir: string): Recor
  * manifest's recorded blob path, then any same-name skill in the tree, then
  * the flat root/name fallback. Passing the tree paths makes the lookup
  * resilient to incomplete manifests and upstream moves.
+ *
+ * A repo-root record (root '') has no directory to resolve: its SKILL.md is a
+ * bare top-level path, so every nested lookup below would miss and the final
+ * fallback would hand back a bogus '/name'. Answer before them — including
+ * when the upstream SKILL.md is gone, so diffRemoteSkills reports a deletion
+ * instead of hunting for a skill that was never nested.
  */
 export function skillDirOf(
   source: { root: string; manifest?: Record<string, number> },
   name: string,
   treePaths?: readonly string[],
 ): string {
+  if (isRepoRoot(source.root)) return REPO_ROOT
   if (treePaths !== undefined) {
     const rootPrefix = source.root + '/'
     const found = treePaths.find((path) => path.startsWith(rootPrefix) && path.endsWith('/' + name + '/SKILL.md'))
@@ -144,38 +234,34 @@ export function skillDirOf(
  * Diff one source record against an upstream tree at treeSha: which tracked
  * skills disappeared (no SKILL.md blob) and which changed (manifest baseline
  * differs, or no baseline exists — treated as changed). Pure over the tree.
+ * The remote side is read through skillManifest, so the diff compares like
+ * with like against the baseline recorded at import time.
  */
 export function diffRemoteSkills(
   tree: readonly RepoTreeItem[],
   source: { root: string; skills: readonly string[]; manifest?: Record<string, number> },
 ): { updated: string[]; deleted: string[] } {
-  const blobs = new Map<string, number>()
-  for (const item of tree) {
-    if (item.type === 'blob') blobs.set(item.path, typeof item.size === 'number' ? item.size : 0)
-  }
-  const treePaths = [...blobs.keys()]
+  const treePaths = tree.filter((item) => item.type === 'blob').map((item) => item.path)
   const updated: string[] = []
   const deleted: string[] = []
+  const baseline = source.manifest ?? {}
   for (const name of source.skills) {
-    const prefix = skillDirOf(source, name, treePaths) + '/'
-    const remote = new Map<string, number>()
-    for (const [path, size] of blobs) {
-      if (path.startsWith(prefix)) remote.set(path, size)
-    }
-    if (!remote.has(prefix + 'SKILL.md')) {
+    const dir = skillDirOf(source, name, treePaths)
+    const prefix = skillDirPrefix(dir)
+    const remote = skillManifest(tree, dir)
+    if (!Object.hasOwn(remote, skillFileAt(dir))) {
       deleted.push(name)
       continue
     }
-    const baseline = source.manifest ?? {}
     const baselineEntries = Object.entries(baseline).filter(([path]) => path.startsWith(prefix))
     if (baselineEntries.length === 0) {
       updated.push(name) // no baseline (migrated/legacy import): treat as changed
       continue
     }
-    let differs = baselineEntries.length !== remote.size
+    let differs = baselineEntries.length !== Object.keys(remote).length
     if (!differs) {
       for (const [path, size] of baselineEntries) {
-        if (remote.get(path) !== size) {
+        if (remote[path] !== size) {
           differs = true
           break
         }
@@ -188,10 +274,11 @@ export function diffRemoteSkills(
 
 /** Minimal RepoSkillEntry for a tracked skill name (sync re-downloads by name). */
 export function repoSkillEntry(name: string, root: string, repo: string): RepoSkillEntry {
+  const dir = isRepoRoot(root) ? REPO_ROOT : root + '/' + name
   return {
     name,
-    dir: root + '/' + name,
-    path: root + '/' + name + '/SKILL.md',
+    dir,
+    path: skillFileAt(dir),
     root,
     origin: repo,
     fileCount: 0,

package/src/repo/github-client.ts

@@ -34,9 +34,26 @@ export function githubAuthHeaders(): Record<string, string> {
   return githubToken === '' ? {} : { authorization: 'Bearer ' + githubToken }
 }
 
+/**
+ * 传输层：显式要求服务端返回未压缩实体。
+ *
+ * 为什么必须加：dsh 会把**启动环境**里的 `HTTP_PROXY`/`HTTPS_PROXY` 装成
+ * undici 的全局 dispatcher（`@deepseek-ai/dsh-http-proxy`），插件里的 `fetch`
+ * 因此走该代理。实测本机 Clash：经代理返回的响应会**丢掉 `content-encoding`
+ * 与 `content-type` 头，而 body 仍是 gzip**；undici 只依据 `content-encoding`
+ * 决定是否解压，于是 `response.json()` 拿到 gzip 二进制并抛错，被上层的
+ * catch 映射成 `invalid github response for <url>` —— 看起来像 GitHub 坏了。
+ * 实测对照（同一 URL、同一代理）：默认 1331 字节解析失败，声明 identity 后
+ * 5245 字节解析成功。
+ *
+ * 代价是不走压缩（我们的响应体都很小），换来的是**无论中间代理是否改写头部
+ * 都能正确取到实体**，且用户无需为插件调整启动命令。
+ */
+export const NO_COMPRESSION: Record<string, string> = { 'accept-encoding': 'identity' }
+
 /** JSON API 默认请求头（含鉴权）。 */
 export function apiHeaders(): Record<string, string> {
-  return { accept: 'application/vnd.github+json', ...githubAuthHeaders() }
+  return { accept: 'application/vnd.github+json', ...NO_COMPRESSION, ...githubAuthHeaders() }
 }
 
 /** ETag cache for GitHub API JSON (mirrors codex lib.rs marker+fingerprint). In-memory only, saves 304 for daily checks. */

package/src/repo/install.ts

@@ -10,7 +10,8 @@ import type { RepoSkillEntry } from '../protocol.ts'
 import { errorText } from '../error-text.ts'
 import { mapConcurrent } from '../concurrency.ts'
 import { parseFrontmatter } from '../skillfs.ts'
-import { RepoFetchError, fetchError, githubAuthHeaders, isAbortError } from './github-client.ts'
+import { NO_COMPRESSION, RepoFetchError, fetchError, githubAuthHeaders, isAbortError } from './github-client.ts'
+import { relativeToSkillDir } from './discovery.ts'
 import type { RepoFile } from './types.ts'
 
 /**
@@ -26,7 +27,7 @@ export async function downloadGitHubFile(repo: string, ref: string, path: string
   let firstError: string | null = null
   let response: Response | null = null
   try {
-    response = await fetchImpl(rawUrl, { headers: githubAuthHeaders(), ...(signal !== undefined ? { signal } : {}) })
+    response = await fetchImpl(rawUrl, { headers: { ...NO_COMPRESSION, ...githubAuthHeaders() }, ...(signal !== undefined ? { signal } : {}) })
   } catch (error) {
     if (isAbortError(error)) throw error
     firstError = errorText(error)
@@ -36,7 +37,7 @@ export async function downloadGitHubFile(repo: string, ref: string, path: string
     // Fallback: api.github.com/contents with the raw media type.
     const apiUrl = `https://api.github.com/repos/${repo}/contents/${encodedPath}`
     try {
-      response = await fetchImpl(apiUrl, { headers: { accept: 'application/vnd.github.raw', ...githubAuthHeaders() }, ...(signal !== undefined ? { signal } : {}) })
+      response = await fetchImpl(apiUrl, { headers: { accept: 'application/vnd.github.raw', ...NO_COMPRESSION, ...githubAuthHeaders() }, ...(signal !== undefined ? { signal } : {}) })
     } catch (error) {
       if (isAbortError(error)) throw error
       throw new RepoFetchError('download failed: ' + (firstError ?? (errorText(error))))
@@ -78,7 +79,7 @@ export async function downloadRepoSkill(
   try {
     await mapConcurrent(files, 6, async (file) => {
       if (signal?.aborted) throw new DOMException('aborted', 'AbortError')
-      const relative = file.path.slice(entry.dir.length + 1)
+      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)
@@ -115,7 +116,7 @@ export async function downloadRepoSkill(
         try {
           await rm(tempDir, { recursive: true, force: true })
         } catch (secondError) {
-          console.warn(`[skill-hub] cleanup tempDir failed ${tempDir}:`, errorText(secondError), 'first:', errorText(firstError))
+          console.warn(`[dsh-skill-hub] cleanup tempDir failed ${tempDir}:`, errorText(secondError), 'first:', errorText(firstError))
         }
       }
     }
@@ -142,9 +143,9 @@ export async function cleanupLeftoverImportDirs(targetRoot: string): Promise<num
       await rm2(full, { recursive: true, force: true })
       cleaned += 1
     } catch (error) {
-      console.warn(`[skill-hub] startup cleanup failed ${full}:`, errorText(error))
+      console.warn(`[dsh-skill-hub] startup cleanup failed ${full}:`, errorText(error))
     }
   }
-  if (cleaned > 0) console.warn(`[skill-hub] startup cleaned ${cleaned} leftover import temp dir(s) in ${targetRoot}`)
+  if (cleaned > 0) console.warn(`[dsh-skill-hub] startup cleaned ${cleaned} leftover import temp dir(s) in ${targetRoot}`)
   return cleaned
 }

package/src/repo.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { mkdtemp, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { collectRepoSkillFiles, diffRemoteSkills, discoverRepoEntries, downloadGitHubFile, downloadRepoSkill, getLatestReleaseTag, getRepoStats, listRepoBranches, normalizeRepoInput, originForRoot, repoSlug, skillDirOf } from './repo.ts'
+import { NO_COMPRESSION, apiHeaders, collectRepoSkillFiles, diffRemoteSkills, discoverRepoEntries, downloadGitHubFile, downloadRepoSkill, getLatestReleaseTag, getRepoStats, listRepoBranches, normalizeRepoInput, originForRoot, relativeToSkillDir, repoSkillEntry, repoSlug, skillDirOf, skillFileAt, skillManifest } from './repo.ts'
 import type { RepoTreeItem } from './repo.ts'
 import type { RepoSkillEntry } from './protocol.ts'
 
@@ -62,6 +62,26 @@ describe('collectRepoSkillFiles', () => {
     ]
     expect(collectRepoSkillFiles(tree, 'skills/code-review').map((file) => file.path)).toEqual(['skills/code-review/README.md', 'skills/code-review/SKILL.md'])
   })
+
+  it('collects the whole repo for the repo-root skill, minus repo tooling', () => {
+    const tree = [
+      blob('SKILL.md', 900),
+      blob('AGENTS.md', 10),
+      blob('LICENSE', 20),
+      blob('README.md', 30),
+      blob('agents/openai.yaml', 5),
+      blob('scripts/validate.py', 6),
+      blob('.github/workflows/validate.yml', 999),
+      blob('.claude-plugin/plugin.json', 999),
+      blob('.gitignore', 999),
+    ]
+    const files = collectRepoSkillFiles(tree, '')
+    expect(files.map((file) => file.path)).toEqual(['AGENTS.md', 'agents/openai.yaml', 'LICENSE', 'README.md', 'scripts/validate.py', 'SKILL.md'])
+    expect(files.reduce((sum, file) => sum + file.size, 0)).toBe(971)
+    // The manifest must describe exactly the collected set, or every later
+    // update diff would report "changed".
+    expect(skillManifest(tree, '')).toEqual(Object.fromEntries(files.map((file) => [file.path, file.size])))
+  })
 })
 
 describe('discoverRepoEntries', () => {
@@ -100,16 +120,54 @@ describe('discoverRepoEntries', () => {
     expect(entries.map((e) => e.name).sort()).toEqual(['deploy', 'foo', 'my-template'])
   })
 
-  it('ignores hidden roots and bare SKILL.md at depth 1', () => {
+  it('ignores hidden roots and bare root/SKILL.md', () => {
     const tree = [
       blob('.hidden/secret/SKILL.md', 1),
-      blob('SKILL.md', 1),
       blob('skills/SKILL.md', 1),
       blob('.github/workflows/ci/SKILL.md', 1),
     ]
     expect(discoverRepoEntries(tree, 'a/b')).toEqual([])
   })
 
+  it('discovers a SKILL.md at the repo root as one skill named after the repo', () => {
+    // The whole-repo layout (a plugin manifest may declare "skills": ["./"]).
+    const tree = [
+      blob('SKILL.md', 900),
+      blob('AGENTS.md', 10),
+      blob('LICENSE', 20),
+      blob('README.md', 30),
+      blob('agents/openai.yaml', 5),
+      blob('scripts/validate.py', 6),
+      blob('.github/workflows/validate.yml', 999),
+      blob('.claude-plugin/plugin.json', 999),
+      blob('.gitignore', 999),
+    ]
+    const entries = discoverRepoEntries(tree, 'blader/humanizer')
+    expect(entries).toHaveLength(1)
+    const entry = entries[0]
+    expect(entry.name).toBe('humanizer')
+    expect(entry.root).toBe('')
+    expect(entry.dir).toBe('')
+    expect(entry.path).toBe('SKILL.md')
+    // Repo tooling (top-level dot entries) is not part of the skill.
+    expect(entry.fileCount).toBe(6)
+    expect(entry.totalBytes).toBe(971)
+    expect(entry.origin).toBe('blader/humanizer')
+  })
+
+  it('splits the repo-root origin from nested roots without a trailing slash', () => {
+    const tree = [blob('SKILL.md', 1), blob('skills/foo/SKILL.md', 1)]
+    const entries = discoverRepoEntries(tree, 'a/b')
+    expect(entries.map((e) => [e.name, e.root, e.origin])).toEqual([
+      ['b', '', 'a/b'],
+      ['foo', 'skills', 'a/b/skills'],
+    ])
+  })
+
+  it('skips the repo-root candidate when the repo name is not a valid skill name', () => {
+    expect(discoverRepoEntries([blob('SKILL.md', 1)], 'a/Not A Skill')).toEqual([])
+  })
+
   it('returns empty when no SKILL.md exists', () => {
     expect(discoverRepoEntries([blob('README.md'), blob('skills/foo/README.md')], 'a/b')).toEqual([])
   })
@@ -187,6 +245,68 @@ describe('diffRemoteSkills', () => {
   })
 })
 
+describe('repo-root skills (SKILL.md at the repository root)', () => {
+  it('maps paths without a leading slash or an over-eager slice', () => {
+    // The prefix is empty, so relative === absolute and slicing would eat a char.
+    expect(skillFileAt('')).toBe('SKILL.md')
+    expect(relativeToSkillDir('', 'SKILL.md')).toBe('SKILL.md')
+    expect(relativeToSkillDir('', 'agents/openai.yaml')).toBe('agents/openai.yaml')
+    // Nested dirs are unchanged.
+    expect(skillFileAt('skills/demo')).toBe('skills/demo/SKILL.md')
+    expect(relativeToSkillDir('skills/demo', 'skills/demo/SKILL.md')).toBe('SKILL.md')
+    expect(relativeToSkillDir('skills/demo', 'skills/demo/agents/a.yaml')).toBe('agents/a.yaml')
+  })
+
+  it('builds a repo-root entry whose dir is empty and whose path is a bare SKILL.md', () => {
+    expect(repoSkillEntry('humanizer', '', 'blader/humanizer')).toEqual({
+      name: 'humanizer',
+      dir: '',
+      path: 'SKILL.md',
+      root: '',
+      origin: 'blader/humanizer',
+      fileCount: 0,
+      totalBytes: 0,
+      existing: false,
+    })
+  })
+
+  it('resolves the skill directory to the repo root, never to "/name"', () => {
+    const manifest = { 'SKILL.md': 900, 'README.md': 30 }
+    expect(skillDirOf({ root: '', manifest }, 'humanizer')).toBe('')
+    // A tree lookup must not drag it into a same-name nested skill.
+    expect(skillDirOf({ root: '' }, 'humanizer', ['SKILL.md', 'skills/humanizer/SKILL.md'])).toBe('')
+    // Upstream deleted the SKILL.md: still '', so the diff reports a deletion
+    // instead of hunting for a nested directory that never existed.
+    expect(skillDirOf({ root: '', manifest }, 'humanizer', ['README.md'])).toBe('')
+  })
+
+  it('does not mistake an unchanged repo-root skill for a deletion', () => {
+    // Regression guard for the mid-upgrade hazard: with the old fallback
+    // (root + '/' + name) the prefix was '/humanizer/', matched no blob, and
+    // the skill was reported as deleted — which the GUI turns into a move to
+    // the trash can, even though upstream never changed.
+    const source = { root: '', skills: ['humanizer'], manifest: { 'SKILL.md': 900, 'README.md': 30, 'agents/openai.yaml': 5 } }
+    const tree = [blob('SKILL.md', 900), blob('README.md', 30), blob('agents/openai.yaml', 5), blob('.github/workflows/ci.yml', 999)]
+    expect(diffRemoteSkills(tree, source)).toEqual({ updated: [], deleted: [] })
+  })
+
+  it('reports repo-root updates and deletions', () => {
+    const source = { root: '', skills: ['humanizer'], manifest: { 'SKILL.md': 900, 'README.md': 30 } }
+    expect(diffRemoteSkills([blob('SKILL.md', 1200), blob('README.md', 30)], source)).toEqual({ updated: ['humanizer'], deleted: [] })
+    // A file removed upstream changes the manifest without being a deletion.
+    expect(diffRemoteSkills([blob('SKILL.md', 900)], source)).toEqual({ updated: ['humanizer'], deleted: [] })
+    // No SKILL.md at all is a real deletion.
+    expect(diffRemoteSkills([blob('README.md', 30)], source)).toEqual({ updated: [], deleted: ['humanizer'] })
+  })
+
+  it('treats repo tooling as neither an addition nor a change', () => {
+    // A .github-only upstream change must not flip the skill to "updated".
+    const source = { root: '', skills: ['humanizer'], manifest: { 'SKILL.md': 900 } }
+    const tree = [blob('SKILL.md', 900), blob('.github/workflows/ci.yml', 1)]
+    expect(diffRemoteSkills(tree, source)).toEqual({ updated: [], deleted: [] })
+  })
+})
+
 describe('downloadRepoSkill', () => {
   it('creates the target root when missing and imports a skill directory', async () => {
     const parent = await mkdtemp(join(tmpdir(), 'dsh-repo-download-'))
@@ -211,12 +331,32 @@ describe('downloadRepoSkill', () => {
       await rm(parent, { recursive: true, force: true })
     }
   })
+
+  it('imports a repo-root skill keeping its top-level paths intact', async () => {
+    const parent = await mkdtemp(join(tmpdir(), 'dsh-repo-download-root-'))
+    try {
+      const targetRoot = join(parent, 'skills')
+      const entry: RepoSkillEntry = repoSkillEntry('humanizer', '', 'blader/humanizer')
+      const files = [
+        { path: 'SKILL.md', size: 1 },
+        { path: 'agents/openai.yaml', size: 1 },
+      ]
+      const fetchImpl = async () => new Response('---\nname: humanizer\ndescription: Rewrite AI-sounding text\n---\n\nbody', { status: 200 })
+      const result = await downloadRepoSkill('blader/humanizer', 'main', entry, files, targetRoot, fetchImpl as typeof fetch)
+      expect(result.skillPath).toBe(join(targetRoot, 'humanizer', 'SKILL.md'))
+      // 'SKILL.md' must not be sliced down to 'KILL.md'.
+      await expect(readFile(join(targetRoot, 'humanizer', 'SKILL.md'), 'utf8')).resolves.toContain('name: humanizer')
+      await expect(readFile(join(targetRoot, 'humanizer', 'agents', 'openai.yaml'), 'utf8')).resolves.toContain('name: humanizer')
+    } finally {
+      await rm(parent, { recursive: true, force: true })
+    }
+  })
 })
 
 describe('downloadGitHubFile', () => {
   it('falls back to the api contents endpoint when raw is unreachable', async () => {
     const calls: string[] = []
-    const fetchImpl = async (url: string, init?: RequestInit) => {
+    const fetchImpl = async (url: string) => {
       calls.push(url)
       if (url.startsWith('https://raw.githubusercontent.com/')) throw new Error('raw blocked')
       if (url.includes('/contents/')) return new Response('---\nname: demo\ndescription: x\n---\n\nbody', { status: 200 })
@@ -275,3 +415,17 @@ describe('getRepoStats', () => {
     expect(await getRepoStats('a/b', fetchImpl as typeof fetch)).toEqual({ stars: 7, downloads: 0 })
   })
 })
+
+describe('GitHub 请求头', () => {
+  it('总是要求未压缩实体', () => {
+    // 经代理的响应会丢掉 content-encoding 但 body 仍是 gzip（见 github-client.ts
+    // 里 NO_COMPRESSION 的说明），一旦漏掉这个头，所有 GitHub 调用会假性失败并
+    // 报 `invalid github response for <url>`。
+    expect(NO_COMPRESSION['accept-encoding']).toBe('identity')
+    expect(apiHeaders()['accept-encoding']).toBe('identity')
+  })
+
+  it('保留 JSON 的 accept 头', () => {
+    expect(apiHeaders().accept).toBe('application/vnd.github+json')
+  })
+})

package/src/repo.ts

@@ -4,18 +4,23 @@
  * Kept dependency-free and mostly pure so the root/origin rules are easy to
  * test. Roots are auto-derived: any top-level directory that contains a
  * `**\/SKILL.md` (e.g. `skills/**`, `design-templates/**`, `templates/**`,
- * `workflows/**`) is treated as a skill root. No hard-coded allowlist.
+ * `workflows/**`) is treated as a skill root. No hard-coded allowlist. A
+ * `SKILL.md` at the repo root is the empty-string root (`REPO_ROOT`): the
+ * whole repo is one skill, named after the repo, with top-level dot entries
+ * treated as repo tooling rather than skill content.
  *
  * The implementation now lives under `./repo/` (types, discovery, api,
  * install) and this module is a barrel that re-exports it.
  */
 
 // 后向兼容：老 `from './repo.ts'` 写法继续可用，新代码可直引 github-client。
-export { RepoFetchError, fetchError, fetchJson, fetchJsonCached, githubAuthHeaders, isAbortError, setGithubToken } from './repo/github-client.ts'
+export { NO_COMPRESSION, RepoFetchError, apiHeaders, fetchError, fetchJson, fetchJsonCached, githubAuthHeaders, isAbortError, setGithubToken } from './repo/github-client.ts'
 
 export type { RepoRef, RepoTreeItem, RepoFile } from './repo/types.ts'
 
 export {
+  REPO_ROOT,
+  isRepoRoot,
   repoSlug,
   normalizeRepoInput,
   collectRepoSkillFiles,
@@ -23,6 +28,9 @@ export {
   discoverRepoEntries,
   skillManifest,
   skillDirOf,
+  skillFileAt,
+  skillPathIn,
+  relativeToSkillDir,
   diffRemoteSkills,
   repoSkillEntry,
 } from './repo/discovery.ts'

package/src/routes/config.ts

@@ -7,6 +7,7 @@ import {
   SKILL_HUB_API,
   GITHUB_TOKEN_RE,
   HEX_COLOR_RE,
+  redactGithubToken,
   type ConfigResponse,
   type DiagnosticFixRequest,
   type DiagnosticFixResponse,
@@ -25,6 +26,22 @@ import {
   type SkillHubRouteDeps,
 } from './helpers.ts'
 
+/**
+ * Build a config payload for either method. The GitHub token never goes out:
+ * the effective config and the raw saved overrides are both stripped, and its
+ * presence is reported as a plain boolean instead.
+ */
+function configResponse(config: HubConfig, saved: Partial<HubConfig>): ConfigResponse {
+  const token = config.githubToken
+  return {
+    ok: true,
+    pluginVersion: CURRENT_VERSION,
+    config: redactGithubToken(config),
+    saved: redactGithubToken(saved),
+    githubTokenSet: token !== undefined && token !== '',
+  }
+}
+
 /** 配置域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 export function configRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
   return [
@@ -38,7 +55,7 @@ export function configRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
       skipGate: true,
       handler: async ({ req, res, body }) => {
         if (req.method === 'GET') {
-          writeJson(res, 200, { ok: true, pluginVersion: CURRENT_VERSION, config: configOf(deps), saved: savedOf(deps) } satisfies ConfigResponse)
+          writeJson(res, 200, configResponse(configOf(deps), savedOf(deps)))
           return
         }
         const raw = body
@@ -85,7 +102,7 @@ export function configRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         } else {
           config = await deps.updateConfig(patch)
         }
-        writeJson(res, 200, { ok: true, pluginVersion: CURRENT_VERSION, config, saved: savedOf(deps) } satisfies ConfigResponse)
+        writeJson(res, 200, configResponse(config, savedOf(deps)))
       },
     },
     // -------------------------------------------------------------- update