dsh-skill-importer 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-importer",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Web UI plugin for DeepSeek Harness: import skills from local Markdown files or URLs into the skill roots the harness discovers automatically",
   "type": "module",
   "main": "lib/index.js",
@@ -47,6 +47,9 @@
     "build": "rm -rf lib && tsc -p tsconfig.json && tsdown",
     "test:batch": "node --experimental-strip-types tests/batch-import.test.mjs",
     "test:atomic-delete": "node --experimental-strip-types tests/atomic-skill-delete.test.mjs",
+    "test:update": "node --experimental-strip-types tests/update.test.mjs",
+    "test:list": "node --experimental-strip-types tests/skill-list.test.mjs",
+    "test:effective": "node --experimental-strip-types tests/effective-skills.test.mjs",
     "watch": "tsdown --watch"
   },
   "license": "MIT",

package/src/server.ts

@@ -18,7 +18,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import { isValidSkillName, parseSkillFile } from './frontmatter.ts'
 import type {
   BatchCommitEntry, BatchScanEntry, BatchScanRequest,
-  ImportRequest, ImportTarget, ImportUrlRequest, SkillListEntry,
+  ImportRequest, ImportTarget, ImportUrlRequest, SkillListEntry, SkillListIssue,
 } from './types.ts'
 
 /** Hard cap for one imported skill body (matches the client preview limit). */
@@ -44,18 +44,31 @@ export function dshHomeDir(): string {
 /** Absolute skill root for one target under one workspace. */
 export function skillRoot(target: ImportTarget, workspacePath: string): string {
   switch (target) {
-    case 'user':
-      return join(dshHomeDir(), 'skills')
+    case 'project-dsh':
+      return join(workspacePath, '.dsh', 'skills')
     case 'project-agents':
       return join(workspacePath, '.agents', 'skills')
+    case 'user-dsh':
+      return join(dshHomeDir(), 'skills')
+    case 'user-agents':
+      return join(process.env.DSH_AGENTS_HOME ?? join(homedir(), '.agents'), 'skills')
   }
 }
 
 /** Discovery rank per root (lower wins), mirroring dsh-skill-filesystem. */
-const ROOT_RANK: Record<ImportTarget, number> = { 'project-agents': 200, user: 400 }
+const ROOT_RANK: Record<ImportTarget, number> = {
+  'project-dsh': 100,
+  'project-agents': 200,
+  'user-dsh': 400,
+  'user-agents': 500,
+}
 
-/** Scan order: project roots first so project skills win duplicate names. */
-const SCAN_ORDER: readonly ImportTarget[] = ['project-agents', 'user']
+/** Official default-root order (custom rank 300 is not a stable import destination). */
+const SCAN_ORDER: readonly ImportTarget[] = ['project-dsh', 'project-agents', 'user-dsh', 'user-agents']
+
+export function isProjectTarget(target: ImportTarget): boolean {
+  return target === 'project-dsh' || target === 'project-agents'
+}
 
 /**
  * Quote one frontmatter string value when plain YAML would mis-parse it:
@@ -113,7 +126,7 @@ export function normalizeSkillText(text: string): string {
 export function writeSkillFile(name: string, target: ImportTarget, content: string, workspacePath?: string): string {
   if (!KEBAB_CASE.test(name)) throw new Error('技能名必须是 kebab-case（小写字母、数字、短横线）')
   if (Buffer.byteLength(content, 'utf8') > MAX_CONTENT_BYTES) throw new Error(`内容超过 ${MAX_CONTENT_BYTES / 1024} KB`)
-  if (target !== 'user' && workspacePath === undefined) {
+  if (isProjectTarget(target) && workspacePath === undefined) {
     throw new Error('项目目标需要 workspacePath（当前工作区路径）')
   }
   const normalized = normalizeSkillText(content)
@@ -127,30 +140,55 @@ export function writeSkillFile(name: string, target: ImportTarget, content: stri
 }
 
 /** Scan one skill root and fold its skills into the name-keyed map (rank-aware). */
-function scanRoot(root: string, source: ImportTarget, out: Map<string, SkillListEntry>): void {
-  if (!existsSync(root)) return
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
-    const entryPath = join(root, entry.name)
-    let file: string | undefined
-    if (entry.isDirectory()) {
-      const candidate = join(entryPath, 'SKILL.md')
-      if (existsSync(candidate)) file = candidate
-    } else if (entry.isFile() && entry.name.endsWith('.md')) {
-      file = entryPath
+function scanRoot(
+  root: string,
+  source: ImportTarget,
+  workspacePath: string | undefined,
+  out: Map<string, SkillListEntry>,
+  issues: SkillListIssue[],
+): void {
+  try {
+    if (!existsSync(root)) return
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      const entryPath = join(root, entry.name)
+      let file: string | undefined
+      if (entry.isDirectory()) {
+        const candidate = join(entryPath, 'SKILL.md')
+        if (existsSync(candidate)) file = candidate
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        file = entryPath
+      }
+      if (file === undefined) continue
+      try {
+        const { frontmatter } = parseSkillFile(readFileSync(file, 'utf8'))
+        if (frontmatter.name === undefined || frontmatter.description === undefined) continue
+        if (!isValidSkillName(frontmatter.name)) continue
+        const existing = out.get(frontmatter.name)
+        if (existing !== undefined && ROOT_RANK[existing.source] <= ROOT_RANK[source]) continue
+        out.set(frontmatter.name, {
+          name: frontmatter.name,
+          description: frontmatter.description,
+          ...(frontmatter.whenToUse !== undefined ? { whenToUse: frontmatter.whenToUse } : {}),
+          modelInvocable: frontmatter.disableModelInvocation !== true,
+          userInvocable: frontmatter.userInvocable !== false,
+          source,
+          ...(workspacePath === undefined ? {} : { workspacePath }),
+        })
+      } catch (error) {
+        issues.push({
+          source,
+          path: file,
+          ...(workspacePath === undefined ? {} : { workspacePath }),
+          message: error instanceof Error ? error.message : String(error),
+        })
+      }
     }
-    if (file === undefined) continue
-    const { frontmatter } = parseSkillFile(readFileSync(file, 'utf8'))
-    if (frontmatter.name === undefined || frontmatter.description === undefined) continue
-    if (!isValidSkillName(frontmatter.name)) continue
-    const existing = out.get(frontmatter.name)
-    if (existing !== undefined && ROOT_RANK[existing.source] <= ROOT_RANK[source]) continue
-    out.set(frontmatter.name, {
-      name: frontmatter.name,
-      description: frontmatter.description,
-      ...(frontmatter.whenToUse !== undefined ? { whenToUse: frontmatter.whenToUse } : {}),
-      modelInvocable: frontmatter.disableModelInvocation !== true,
-      userInvocable: frontmatter.userInvocable !== false,
+  } catch (error) {
+    issues.push({
       source,
+      path: root,
+      ...(workspacePath === undefined ? {} : { workspacePath }),
+      message: error instanceof Error ? error.message : String(error),
     })
   }
 }
@@ -162,16 +200,26 @@ function scanRoot(root: string, source: ImportTarget, out: Map<string, SkillList
  * rank at discovery time). Display order groups by source, then name.
  * @param workspacePaths - canonical paths of the registered workspaces.
  */
-export function listSkills(workspacePaths: readonly string[]): SkillListEntry[] {
+export function listSkills(workspacePaths: readonly string[]): { skills: SkillListEntry[]; issues: SkillListIssue[] } {
   const rows: SkillListEntry[] = []
+  const issues: SkillListIssue[] = []
   for (const target of SCAN_ORDER) {
-    const out = new Map<string, SkillListEntry>()
-    for (const path of target === 'user' ? [dshHomeDir()] : workspacePaths) {
-      scanRoot(skillRoot(target, path), target, out)
+    if (!isProjectTarget(target)) {
+      const out = new Map<string, SkillListEntry>()
+      scanRoot(skillRoot(target, ''), target, undefined, out, issues)
+      rows.push(...out.values())
+      continue
     }
-    rows.push(...out.values())
+    for (const workspacePath of workspacePaths) {
+      const out = new Map<string, SkillListEntry>()
+      scanRoot(skillRoot(target, workspacePath), target, workspacePath, out, issues)
+      rows.push(...out.values())
+    }
+  }
+  return {
+    skills: rows.sort((a, b) => a.name.localeCompare(b.name)),
+    issues,
   }
-  return rows.sort((a, b) => a.name.localeCompare(b.name))
 }
 
 /**
@@ -184,7 +232,7 @@ export function listSkills(workspacePaths: readonly string[]): SkillListEntry[]
  */
 export function deleteSkillFile(name: string, source: ImportTarget, workspacePath?: string): boolean {
   if (!KEBAB_CASE.test(name)) throw new Error('技能名必须是 kebab-case（小写字母、数字、短横线）')
-  if (source !== 'user' && workspacePath === undefined) {
+  if (isProjectTarget(source) && workspacePath === undefined) {
     throw new Error('项目来源需要 workspacePath（当前工作区路径）')
   }
   const root = skillRoot(source, workspacePath ?? '')
@@ -290,7 +338,7 @@ export function scanBatch(request: BatchScanRequest): BatchScanSession {
   if (!isSkillsRoot && !isSkillDirectory) {
     throw new Error('批量导入仅支持名为 skills 的目录或其中的单个技能目录')
   }
-  if (request.target !== 'user' && request.workspacePath === undefined) throw new Error('项目目标需要 workspacePath（当前工作区路径）')
+  if (isProjectTarget(request.target) && request.workspacePath === undefined) throw new Error('项目目标需要 workspacePath（当前工作区路径）')
   const sources = batchSources(sourcePath)
   if (sources.length === 0) throw new Error('所选目录中没有找到可导入的技能')
   if (sources.length > MAX_BATCH_SKILLS) throw new Error(`一次最多扫描 ${MAX_BATCH_SKILLS} 个技能`)

package/src/types.ts

@@ -5,7 +5,7 @@
  */
 
 /** Where the imported skill file should land. */
-export type ImportTarget = 'user' | 'project-agents'
+export type ImportTarget = 'project-dsh' | 'project-agents' | 'user-dsh' | 'user-agents'
 
 /** One installed skill row served by `/skill-importer/list`. */
 export interface SkillListEntry {
@@ -19,8 +19,18 @@ export interface SkillListEntry {
   readonly modelInvocable: boolean
   /** False marks a model-only skill (`user-invocable: false`). */
   readonly userInvocable: boolean
-  /** Skill root (`'project-agents'` or `'user'`). */
+  /** Writable DSH skill root that owns this copy. */
   readonly source: ImportTarget
+  /** Exact registered workspace that owns a project-scoped copy. */
+  readonly workspacePath?: string
+}
+
+/** One skill root or entry that could not be inspected without failing the whole list. */
+export interface SkillListIssue {
+  readonly source: ImportTarget
+  readonly path: string
+  readonly workspacePath?: string
+  readonly message: string
 }
 
 /** File-import request body. */
@@ -36,7 +46,7 @@ export interface ImportRequest {
 /** Delete-request body. */
 export interface DeleteRequest {
   readonly name: string
-  /** Which root the copy lives in (`'project-agents'` or `'user'`). */
+  /** Which writable DSH root owns this copy. */
   readonly source: ImportTarget
   /** Canonical workspace path for project sources (host-validated). */
   readonly workspacePath?: string
@@ -107,6 +117,18 @@ export interface BatchCommitResponse {
 export interface SkillListResponse {
   readonly ok: true
   readonly skills: readonly SkillListEntry[]
+  readonly issues: readonly SkillListIssue[]
+}
+
+/** `/skill-importer/update-status` response. */
+export interface UpdateStatusResponse {
+  readonly ok: true
+  readonly currentVersion: string
+  readonly latestVersion?: string
+  readonly updateAvailable: boolean
+  readonly command?: string
+  /** A failed registry check is non-fatal: the installed version is still useful. */
+  readonly error?: string
 }
 
 /** Success response of an import. */

package/tests/batch-import.test.mjs

@@ -43,7 +43,7 @@ try {
   mkdirSync(existing, { recursive: true })
   writeFileSync(join(existing, 'SKILL.md'), skill('alpha', 'old'))
 
-  const scan = scanBatch({ sourcePath: source, target: 'user' })
+  const scan = scanBatch({ sourcePath: source, target: 'user-dsh' })
   assert.equal(scan.entries.find(row => row.name === 'alpha')?.conflict, true)
   assert.equal(scan.entries.find(row => row.name === 'windows-crlf')?.status, 'ready')
   assert.equal(scan.entries.find(row => row.name === 'invalid')?.status, 'error')
@@ -63,7 +63,7 @@ try {
   const changedSource = join(sandbox, '.codex', 'skills')
   mkdirSync(join(changedSource, 'beta'), { recursive: true })
   writeFileSync(join(changedSource, 'beta', 'SKILL.md'), skill('beta'))
-  const changedScan = scanBatch({ sourcePath: changedSource, target: 'user' })
+  const changedScan = scanBatch({ sourcePath: changedSource, target: 'user-dsh' })
   writeFileSync(join(changedSource, 'beta', 'SKILL.md'), skill('beta', 'changed after scan'))
   const changedResults = commitBatch(changedScan, new Set())
   assert.equal(changedResults[0]?.status, 'error')
@@ -74,15 +74,15 @@ try {
   const customAgentSource = join(sandbox, 've_hcs_agent', 'skills')
   mkdirSync(join(customAgentSource, 'gamma'), { recursive: true })
   writeFileSync(join(customAgentSource, 'gamma', 'SKILL.md'), skill('gamma'))
-  assert.equal(scanBatch({ sourcePath: customAgentSource, target: 'user' }).entries[0]?.name, 'gamma')
+  assert.equal(scanBatch({ sourcePath: customAgentSource, target: 'user-dsh' }).entries[0]?.name, 'gamma')
 
   const empty = join(sandbox, '.agents', 'skills')
   mkdirSync(empty, { recursive: true })
-  assert.throws(() => scanBatch({ sourcePath: empty, target: 'user' }), /没有找到/)
+  assert.throws(() => scanBatch({ sourcePath: empty, target: 'user-dsh' }), /没有找到/)
 
   const arbitrary = join(sandbox, 'arbitrary')
   mkdirSync(arbitrary)
-  assert.throws(() => scanBatch({ sourcePath: arbitrary, target: 'user' }), /名为 skills/)
+  assert.throws(() => scanBatch({ sourcePath: arbitrary, target: 'user-dsh' }), /名为 skills/)
 
   assert.equal(originAllowed({ headers: {} }), false)
   assert.equal(originAllowed({ headers: { origin: 'https://evil.example' } }), false)

package/tests/effective-skills.test.mjs

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict'
+import { effectiveSkills } from '../src/client/effectiveSkills.ts'
+
+const row = (name, source, workspacePath) => ({
+  name,
+  source,
+  workspacePath,
+  description: source,
+  modelInvocable: true,
+  userInvocable: true,
+})
+
+const effective = effectiveSkills([
+  row('shared', 'user-agents'),
+  row('shared', 'project-agents', '/project'),
+  row('shared', 'user-dsh'),
+  row('shared', 'project-dsh', '/project'),
+  row('global-only', 'user-dsh'),
+])
+
+assert.deepEqual(effective.map((skill) => [skill.name, skill.source]), [
+  ['global-only', 'user-dsh'],
+  ['shared', 'project-dsh'],
+])
+console.log('effective skills test: OK')

package/tests/skill-list.test.mjs

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict'
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { listSkills, skillRoot } from '../src/server.ts'
+
+const sandbox = mkdtempSync(join(tmpdir(), 'dsh-skill-list-test-'))
+const previousHome = process.env.DSH_HOME
+const previousAgentsHome = process.env.DSH_AGENTS_HOME
+process.env.DSH_HOME = join(sandbox, 'home')
+process.env.DSH_AGENTS_HOME = join(sandbox, 'agents-home')
+
+try {
+  assert.equal(skillRoot('project-dsh', '/workspace'), join('/workspace', '.dsh', 'skills'))
+  assert.equal(skillRoot('project-agents', '/workspace'), join('/workspace', '.agents', 'skills'))
+  assert.equal(skillRoot('user-dsh', ''), join(process.env.DSH_HOME, 'skills'))
+  assert.equal(skillRoot('user-agents', ''), join(process.env.DSH_AGENTS_HOME, 'skills'))
+
+  const first = join(sandbox, 'first')
+  const second = join(sandbox, 'second')
+  const firstRoot = join(first, '.agents', 'skills')
+  const secondRoot = join(second, '.agents', 'skills')
+  mkdirSync(join(firstRoot, 'shared'), { recursive: true })
+  mkdirSync(join(secondRoot, 'shared'), { recursive: true })
+  writeFileSync(join(firstRoot, 'shared', 'SKILL.md'), '---\nname: shared\ndescription: first\n---\n')
+  writeFileSync(join(secondRoot, 'shared', 'SKILL.md'), '---\nname: shared\ndescription: second\n---\n')
+
+  const listed = listSkills([first, second])
+  assert.equal(listed.issues.length, 0)
+  assert.deepEqual(
+    listed.skills.map(skill => [skill.name, skill.description, skill.workspacePath]),
+    [['shared', 'first', first], ['shared', 'second', second]],
+  )
+
+  chmodSync(secondRoot, 0o000)
+  const partial = listSkills([first, second])
+  assert.equal(partial.skills.length, 1)
+  assert.equal(partial.skills[0]?.workspacePath, first)
+  assert.equal(partial.issues.length, 1)
+  assert.equal(partial.issues[0]?.path, secondRoot)
+  chmodSync(secondRoot, 0o755)
+} finally {
+  if (previousHome === undefined) delete process.env.DSH_HOME
+  else process.env.DSH_HOME = previousHome
+  if (previousAgentsHome === undefined) delete process.env.DSH_AGENTS_HOME
+  else process.env.DSH_AGENTS_HOME = previousAgentsHome
+  rmSync(sandbox, { recursive: true, force: true })
+}
+
+console.log('skill list test: OK')

package/tests/update.test.mjs

@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { compareVersions, currentVersion, updateCommand } from '../src/update.ts'
+
+test('compares stable semantic versions', () => {
+  assert.equal(compareVersions('0.2.3', '0.2.4'), -1)
+  assert.equal(compareVersions('1.0.0', '1.0.0'), 0)
+  assert.equal(compareVersions('2.0.0', '1.9.9'), 1)
+})
+
+test('orders prereleases before stable releases', () => {
+  assert.equal(compareVersions('1.0.0-rc.2', '1.0.0'), -1)
+  assert.equal(compareVersions('1.0.0-rc.10', '1.0.0-rc.2'), 1)
+})
+
+test('reads package version and produces an exact update command', () => {
+  assert.equal(currentVersion(), '0.2.5')
+  assert.equal(
+    updateCommand('0.2.4'),
+    'npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@0.2.4',
+  )
+})