@chatcode/cco-market 1.45.1

package/src/settings.ts

@@ -0,0 +1,141 @@
+/**
+ * The market's own settings namespace: the half that makes `allowRestart`
+ * a switch on the plugin configuration page instead of a line the user has
+ * to hand-write into cordis.yml.
+ *
+ * `allowRestart: false` is the documented answer for a host owned by
+ * systemd, launchd or pm2 — a supervisor restarts it, so the market's
+ * one-click restart must not launch a second one. Until now the only way to
+ * say that was editing YAML in the right place with the right indentation,
+ * where a stray space stops the profile booting.
+ *
+ * Only `allowRestart` is exposed. `profile` names which profile this
+ * instance manages: it is decided at mount from the composition or the
+ * command line, and a running instance cannot switch to another one, so
+ * offering it as a field would promise something the write cannot deliver.
+ *
+ * The release channel is NOT here either, and that is a correction rather
+ * than an omission. It was, briefly, and it made this namespace a second
+ * writer for a value the market already stores in its own state.json: the
+ * mount read the user's saved channel off disk, then `onChange` assigned
+ * `source().channel` — which knows nothing about that file — straight back
+ * over it. The choice survived exactly until the next settings event.
+ *
+ * Only a real host could show that; the unit lane mounts the routes without
+ * this layer at all. `allowRestart` needs this door because its only other
+ * one is hand-edited YAML. The channel has a control of its own on the
+ * plugin configuration page, so a second door bought nothing and cost the
+ * setting its memory.
+ *
+ * The wiring rides the scoped fiber, so a host with no settings service —
+ * every dsh before 0.1.0-rc.7 — simply never runs any of this and the entry
+ * configuration stands as composed. That is why this needs no version check
+ * of its own.
+ *
+ * It depends on the SERVICE and nothing else, which is the whole point of
+ * the shape below. This module used to import two convenience helpers,
+ * `installSettingsSection` and `settingsNamespace`, from
+ * `@deepseek-ai/dsh-settings`. dsh 0.1.2-alpha.1 deleted both — and a
+ * missing NAMED EXPORT is not a missing service. `ctx.inject` degrades
+ * quietly; an ESM named import that resolves to nothing is a SyntaxError at
+ * module evaluation, which cordis's loader reports as a failed entry and the
+ * host exits 1. Installing the market stopped the host from booting at all:
+ *
+ *   SyntaxError: The requested module '@deepseek-ai/dsh-settings' does not
+ *   provide an export named 'installSettingsSection'
+ *
+ * The service itself never changed — `sctx.settings.register(ns, schema,
+ * { base })` is identical in 0.1.0-rc.7 and 0.1.2-alpha.2. Only the two
+ * wrappers went away. So this inlines what the wrapper did (verified against
+ * its source: an inject, a register, a watch, and an unload effect) and
+ * validates the namespace here. Nothing about the graceful-degradation story
+ * changes; it just stops being conditional on an export that upstream is
+ * free to move.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { restartAllowed } from './restart.ts'
+
+/**
+ * The namespace pattern `settingsNamespace` enforced before it was removed.
+ * Kept as a literal check rather than an import for the reason above.
+ */
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
+
+/** Namespace the card on the browser side keys itself to. */
+export const MARKET_SETTINGS_NS = 'dsh-market'
+
+if (!NAMESPACE_PATTERN.test(MARKET_SETTINGS_NS)) {
+  throw new TypeError(`settings namespace "${MARKET_SETTINGS_NS}" must match ${String(NAMESPACE_PATTERN)}`)
+}
+
+/**
+ * The slice of the host's `settings` service this module uses.
+ *
+ * Declared structurally rather than imported: the package no longer exports
+ * a type for it on every supported host, and naming only what is called
+ * keeps this from breaking again when a neighbouring field moves.
+ */
+interface SettingsScope {
+  get: () => MarketSettings
+  watch: (listener: () => void) => void
+}
+interface SettingsService {
+  register: (
+    ns: string,
+    schema: z<MarketSettings>,
+    options: { base: MarketSettings },
+  ) => SettingsScope
+}
+
+/** The market settings a user may edit at runtime. */
+export interface MarketSettings {
+  allowRestart: boolean
+}
+
+export const MarketSettings: z<MarketSettings> = z.object({
+  allowRestart: z.boolean().default(true),
+})
+
+/**
+ * Wire the namespace so a saved change reaches the routes immediately.
+ *
+ * The routes read `allowRestart` off this object on every request (the
+ * status route reports the capability, the restart route enforces it), so
+ * updating it in place is what makes a toggle take effect without a
+ * restart — which would be a poor thing to require of a setting whose whole
+ * subject is restarting.
+ *
+ * @param ctx - the plugin context owning the wiring.
+ * @param resolved - the live config object the routes read.
+ */
+export function installMarketSettings(ctx: Context, resolved: { allowRestart?: boolean }): void {
+  // The switch must show what the routes will actually DO, which since #229
+  // is not simply "unset means on": under a detected supervisor an unset
+  // value means off, because the supervisor owns restarts. Asking
+  // restartAllowed() rather than re-deriving it here is what keeps the two
+  // from drifting — a switch showing On beside a hidden button is the same
+  // class of confusion the detection exists to end.
+  const entry = { allowRestart: restartAllowed(resolved) }
+  let source = (): MarketSettings => entry
+  // Assigns ONLY what this namespace owns. Writing back a field the market
+  // stores elsewhere is how the channel lost its memory.
+  const apply = (): void => { resolved.allowRestart = source().allowRestart }
+
+  // `inject` is the graceful-degradation boundary: on a host with no
+  // settings service the callback never runs and the composed entry stands.
+  ctx.inject(['settings'], (scopedCtx: Context) => {
+    const scoped = scopedCtx as unknown as Context & { settings: SettingsService }
+    const scope = scoped.settings.register(MARKET_SETTINGS_NS, MarketSettings, { base: entry })
+    source = () => scope.get()
+    // Unload restores the composed entry, so a disabled section cannot leave
+    // the routes reading a value nobody can see or change any more.
+    scoped.effect(() => () => {
+      source = () => entry
+      apply()
+    })
+    apply()
+    scope.watch(apply)
+  })
+}

package/src/skill-market/api.ts

@@ -0,0 +1,130 @@
+import { marketFetch } from '../net.ts'
+import type { ResolvedSkillMarketConfig, SkillListQuery, SkillListResult, SkillMarketItem } from './types.ts'
+
+interface ApiEnvelope {
+  readonly code?: unknown
+  readonly message?: unknown
+  readonly data?: unknown
+}
+
+/** Client for the public skill catalog and archive endpoints. */
+export class SkillMarketApi {
+  constructor(private readonly config: ResolvedSkillMarketConfig) {}
+
+  /** Fetch one validated catalog page. */
+  async list(query: SkillListQuery = {}, signal?: AbortSignal): Promise<SkillListResult> {
+    const page = positiveInteger(query.page, 1, 'page')
+    const pageSize = positiveInteger(query.pageSize, this.config.defaultPageSize, 'pageSize')
+    const params = new URLSearchParams({ page: String(page), pageSize: String(pageSize) })
+    for (const key of ['search', 'category', 'sort', 'tag'] as const) {
+      const value = query[key]
+      if (value !== undefined && value.trim().length > 0) params.set(key, value.trim())
+    }
+    const response = await fetchWithTimeout(
+      `${this.config.baseUrl}/scm/inner/skillMarketplace/open/list?${params.toString()}`,
+      this.config.requestTimeoutMs,
+      signal,
+    )
+    if (!response.ok) throw new Error(`技能列表请求失败: HTTP ${response.status}`)
+    const envelope = await response.json() as ApiEnvelope
+    if (envelope.code !== 200 && envelope.code !== '200') {
+      throw new Error(`技能列表请求失败: ${typeof envelope.message === 'string' ? envelope.message : `code=${String(envelope.code)}`}`)
+    }
+    return parseListResult(envelope.data)
+  }
+
+  /** Download a skill archive; the caller consumes and size-caps the body. */
+  async download(id: number, signal?: AbortSignal): Promise<Response> {
+    if (!Number.isSafeInteger(id) || id <= 0) throw new TypeError('skill id must be a positive integer')
+    const response = await fetchWithTimeout(
+      `${this.config.baseUrl}/scm/inner/skillMarketplace/open/download?id=${id}`,
+      this.config.downloadTimeoutMs,
+      signal,
+    )
+    if (response.status === 404) throw new Error('技能不存在或无权下载')
+    if (!response.ok) throw new Error(`技能下载失败: HTTP ${response.status}`)
+    const length = Number(response.headers.get('content-length'))
+    if (Number.isFinite(length) && length > this.config.maxDownloadBytes) {
+      throw new Error(`技能包超过 ${this.config.maxDownloadBytes} 字节限制`)
+    }
+    return response
+  }
+}
+
+async function fetchWithTimeout(url: string, timeoutMs: number, signal: AbortSignal | undefined): Promise<Response> {
+  const controller = new AbortController()
+  const abort = () => controller.abort(signal?.reason)
+  signal?.addEventListener('abort', abort, { once: true })
+  const timeout = setTimeout(() => controller.abort(new Error(`request timed out after ${timeoutMs}ms`)), timeoutMs)
+  try {
+    return await marketFetch(url, { signal: controller.signal, headers: { accept: 'application/json' } })
+  } catch (error) {
+    if (controller.signal.aborted && !signal?.aborted) throw new Error(`技能市场请求超时（${timeoutMs}ms）`, { cause: error })
+    throw error
+  } finally {
+    clearTimeout(timeout)
+    signal?.removeEventListener('abort', abort)
+  }
+}
+
+function positiveInteger(value: number | undefined, fallback: number, name: string): number {
+  const resolved = value ?? fallback
+  if (!Number.isSafeInteger(resolved) || resolved <= 0) throw new TypeError(`${name} must be a positive integer`)
+  return resolved
+}
+
+function parseListResult(value: unknown): SkillListResult {
+  if (!isRecord(value) || !Array.isArray(value.items)) throw new Error('技能列表响应格式异常：缺少 items 字段')
+  const total = readNonNegativeInteger(value.total, 'total')
+  const page = readPositiveInteger(value.page, 'page')
+  const pageSize = readPositiveInteger(value.pageSize, 'pageSize')
+  return { items: value.items.map(parseItem), total, page, pageSize }
+}
+
+function parseItem(value: unknown): SkillMarketItem {
+  if (!isRecord(value)) throw new Error('技能列表响应格式异常：技能条目不是对象')
+  return {
+    id: readPositiveInteger(value.id, 'item.id'),
+    name: readString(value.name, 'item.name'),
+    description: optionalString(value.description),
+    category: optionalString(value.category),
+    status: optionalString(value.status),
+    downloads: optionalNonNegativeInteger(value.downloads),
+    views: optionalNonNegativeInteger(value.views),
+    readme: optionalString(value.readme),
+    version: optionalString(value.version),
+    author: optionalString(value.author),
+    creatorName: optionalString(value.creatorName),
+    tags: optionalString(value.tags),
+    createTime: optionalString(value.createTime),
+    updateTime: optionalString(value.updateTime),
+    visibility: optionalString(value.visibility),
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function readString(value: unknown, name: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) throw new Error(`技能列表响应格式异常：${name}`)
+  return value
+}
+
+function optionalString(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function readPositiveInteger(value: unknown, name: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) <= 0) throw new Error(`技能列表响应格式异常：${name}`)
+  return value as number
+}
+
+function readNonNegativeInteger(value: unknown, name: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) throw new Error(`技能列表响应格式异常：${name}`)
+  return value as number
+}
+
+function optionalNonNegativeInteger(value: unknown): number {
+  return Number.isSafeInteger(value) && (value as number) >= 0 ? value as number : 0
+}

package/src/skill-market/config.ts

@@ -0,0 +1,32 @@
+import type { ResolvedSkillMarketConfig, SkillMarketConfig } from './types.ts'
+
+const DEFAULTS: ResolvedSkillMarketConfig = Object.freeze({
+  baseUrl: 'https://devops.chinaunicom.cn/inner_source_scm',
+  requestTimeoutMs: 15_000,
+  downloadTimeoutMs: 60_000,
+  defaultPageSize: 10,
+  maxDownloadBytes: 32 * 1024 * 1024,
+  maxArchiveEntries: 256,
+  maxUncompressedBytes: 64 * 1024 * 1024,
+})
+
+/** Resolve and validate deployment-varying skill-market settings. */
+export function resolveSkillMarketConfig(input: SkillMarketConfig | undefined): ResolvedSkillMarketConfig {
+  const resolved = { ...DEFAULTS, ...input, baseUrl: (input?.baseUrl ?? DEFAULTS.baseUrl).replace(/\/+$/u, '') }
+  if (resolved.baseUrl.length === 0 || !/^https?:\/\//u.test(resolved.baseUrl)) {
+    throw new TypeError('dsh-market: skillMarket.baseUrl must be an HTTP(S) URL')
+  }
+  for (const [name, value] of Object.entries({
+    requestTimeoutMs: resolved.requestTimeoutMs,
+    downloadTimeoutMs: resolved.downloadTimeoutMs,
+    defaultPageSize: resolved.defaultPageSize,
+    maxDownloadBytes: resolved.maxDownloadBytes,
+    maxArchiveEntries: resolved.maxArchiveEntries,
+    maxUncompressedBytes: resolved.maxUncompressedBytes,
+  })) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new TypeError(`dsh-market: skillMarket.${name} must be a positive integer`)
+    }
+  }
+  return Object.freeze(resolved)
+}

package/src/skill-market/installer.ts

@@ -0,0 +1,337 @@
+import { createWriteStream } from 'node:fs'
+import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { Transform } from 'node:stream'
+import { load as loadYaml } from 'js-yaml'
+import yauzl, { type Entry, type ZipFile } from 'yauzl'
+import type { ResolvedSkillMarketConfig, InstalledSkill, SkillInstallLocation, SkillInstallResult, SkillMarketMeta } from './types.ts'
+import type { SkillMarketApi } from './api.ts'
+import { resolveChatCodeHome } from '../home-paths.ts'
+
+export const SKILL_MARKET_META_FILE = '.skill-market.json'
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u
+
+/** Installs validated catalog archives into ChatCode CLI skill roots. */
+export class SkillMarketInstaller {
+  constructor(
+    private readonly api: SkillMarketApi,
+    private readonly config: ResolvedSkillMarketConfig,
+  ) {}
+
+  /** Install or update one catalog skill for a local session workspace. */
+  async install(options: {
+    readonly id: number
+    readonly name: string
+    readonly version?: string
+    readonly location: SkillInstallLocation
+    readonly cwd: string
+    readonly signal?: AbortSignal
+  }): Promise<SkillInstallResult> {
+    assertSkillName(options.name)
+    const roots = await resolveSkillRoots(options.cwd)
+    const skillsDir = roots[options.location]
+    const target = join(skillsDir, options.name)
+    const temp = await mkdtemp(join(tmpdir(), 'dsh-skill-market-'))
+    const archive = join(temp, 'skill.zip')
+    const extracted = join(temp, 'extracted')
+    let staged: string | undefined
+    let backup: string | undefined
+    try {
+      await this.downloadArchive(options.id, archive, options.signal)
+      await mkdir(extracted, { recursive: true })
+      await extractZip(archive, extracted, this.config, options.signal)
+      const contentRoot = await findSingleSkillRoot(extracted)
+      const manifest = await parseSkillManifest(join(contentRoot, 'SKILL.md'))
+      if (manifest.name !== options.name) {
+        throw new Error(`技能包名称不匹配：目录请求 ${options.name}，SKILL.md 声明 ${manifest.name}`)
+      }
+
+      await mkdir(skillsDir, { recursive: true })
+      const existing = await installedMeta(target)
+      const updated = existing !== undefined
+      if (updated && existing.id !== options.id) {
+        throw new Error(`目标 ${target} 已存在，且不属于技能市场条目 ${options.id}`)
+      }
+      if (!updated && await pathExists(target)) {
+        throw new Error(`目标 ${target} 已存在；不会覆盖非市场安装的技能`)
+      }
+
+      staged = join(skillsDir, `.${options.name}.install-${crypto.randomUUID()}`)
+      await cp(contentRoot, staged, { recursive: true, errorOnExist: true, force: false })
+      const meta: SkillMarketMeta = { id: options.id, name: options.name, version: options.version }
+      await writeFile(join(staged, SKILL_MARKET_META_FILE), `${JSON.stringify(meta, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' })
+
+      if (updated) {
+        backup = join(skillsDir, `.${options.name}.backup-${crypto.randomUUID()}`)
+        await rename(target, backup)
+      }
+      try {
+        await rename(staged, target)
+        staged = undefined
+      } catch (error) {
+        if (backup !== undefined) await rename(backup, target)
+        backup = undefined
+        throw error
+      }
+      if (backup !== undefined) {
+        await rm(backup, { recursive: true, force: true })
+        backup = undefined
+      }
+      return { skillName: options.name, installPath: target, location: options.location, updated }
+    } finally {
+      if (staged !== undefined) await rm(staged, { recursive: true, force: true })
+      if (backup !== undefined) {
+        if (!await pathExists(target)) await rename(backup, target)
+        else await rm(backup, { recursive: true, force: true })
+      }
+      await rm(temp, { recursive: true, force: true })
+    }
+  }
+
+  private async downloadArchive(id: number, destination: string, signal: AbortSignal | undefined): Promise<void> {
+    const controller = new AbortController()
+    const abort = () => controller.abort(signal?.reason)
+    signal?.addEventListener('abort', abort, { once: true })
+    const timeout = setTimeout(
+      () => controller.abort(new Error(`技能下载超时（${this.config.downloadTimeoutMs}ms）`)),
+      this.config.downloadTimeoutMs,
+    )
+    try {
+      const response = await this.api.download(id, controller.signal)
+      await writeCappedResponse(response, destination, this.config.maxDownloadBytes, controller.signal)
+    } catch (error) {
+      if (controller.signal.aborted && !signal?.aborted) {
+        throw new Error(`技能下载超时（${this.config.downloadTimeoutMs}ms）`, { cause: error })
+      }
+      throw error
+    } finally {
+      clearTimeout(timeout)
+      signal?.removeEventListener('abort', abort)
+    }
+  }
+
+  /** List market-managed skills visible from a local session workspace. */
+  async installed(cwd: string): Promise<readonly InstalledSkill[]> {
+    const roots = await resolveSkillRoots(cwd)
+    const found = await Promise.all((['project', 'user'] as const).map(async location => {
+      const root = roots[location]
+      let entries
+      try {
+        entries = await readdir(root, { withFileTypes: true })
+      } catch (error) {
+        if (isMissing(error)) return []
+        throw error
+      }
+      const installed = await Promise.all(entries.filter(entry => entry.isDirectory()).map(async (entry): Promise<InstalledSkill | undefined> => {
+        const path = join(root, entry.name)
+        if (!await pathExists(join(path, 'SKILL.md'))) return undefined
+        const meta = await installedMeta(path)
+        return {
+          name: entry.name,
+          location,
+          path,
+          ...(meta?.id === undefined ? {} : { marketId: meta.id }),
+          ...(meta?.version === undefined ? {} : { version: meta.version }),
+        }
+      }))
+      return installed.filter((item): item is InstalledSkill => item !== undefined)
+    }))
+    return found.flat().sort((a, b) => a.name.localeCompare(b.name) || a.location.localeCompare(b.location))
+  }
+}
+
+/** Resolve the two skill roots visible to a session workspace. */
+export async function resolveSkillRoots(cwd: string): Promise<Record<SkillInstallLocation, string>> {
+  if (!isAbsolute(cwd)) throw new Error('技能市场仅支持本地绝对工作目录')
+  const cwdStat = await stat(cwd).catch(error => {
+    if (isMissing(error)) throw new Error(`工作目录不存在：${cwd}`, { cause: error })
+    throw error
+  })
+  if (!cwdStat.isDirectory()) throw new Error(`工作目录不是目录：${cwd}`)
+  let projectRoot = resolve(cwd)
+  while (true) {
+    if (await pathExists(join(projectRoot, '.git'))) break
+    const parent = dirname(projectRoot)
+    if (parent === projectRoot) {
+      projectRoot = resolve(cwd)
+      break
+    }
+    projectRoot = parent
+  }
+  return {
+    project: join(projectRoot, '.chatcode-cli', 'skills'),
+    user: join(resolveChatCodeHome(), 'skills'),
+  }
+}
+
+async function writeCappedResponse(response: Response, destination: string, limit: number, signal: AbortSignal | undefined): Promise<void> {
+  if (response.body === null) throw new Error('技能下载响应无内容')
+  let bytes = 0
+  const counter = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      bytes += chunk.length
+      if (bytes > limit) callback(new Error(`技能包超过 ${limit} 字节限制`))
+      else callback(null, chunk)
+    },
+  })
+  await pipeline(response.body as never, counter, createWriteStream(destination, { flags: 'wx', mode: 0o600 }), { signal })
+}
+
+async function extractZip(zipPath: string, target: string, config: ResolvedSkillMarketConfig, signal: AbortSignal | undefined): Promise<void> {
+  const zip = await openZip(zipPath)
+  let entries = 0
+  let totalBytes = 0
+  let abort: (() => void) | undefined
+  try {
+    await new Promise<void>((resolvePromise, rejectPromise) => {
+      let settled = false
+      const fail = (error: unknown) => {
+        if (settled) return
+        settled = true
+        rejectPromise(error)
+      }
+      abort = () => fail(signal?.reason ?? new Error('技能安装已取消'))
+      signal?.addEventListener('abort', abort, { once: true })
+      zip.on('error', fail)
+      zip.on('end', () => {
+        if (settled) return
+        settled = true
+        resolvePromise()
+      })
+      zip.on('entry', (entry: Entry) => {
+        void extractEntry(zip, entry, target, {
+          addEntry: () => {
+            entries += 1
+            if (entries > config.maxArchiveEntries) throw new Error(`技能包文件数超过 ${config.maxArchiveEntries} 个限制`)
+          },
+          addBytes: (count: number) => {
+            totalBytes += count
+            if (totalBytes > config.maxUncompressedBytes) throw new Error(`技能包解压后超过 ${config.maxUncompressedBytes} 字节限制`)
+          },
+        }, signal).then(() => zip.readEntry(), fail)
+      })
+      zip.readEntry()
+    })
+  } finally {
+    if (abort !== undefined) signal?.removeEventListener('abort', abort)
+    zip.close()
+  }
+}
+
+async function extractEntry(
+  zip: ZipFile,
+  entry: Entry,
+  target: string,
+  limits: { addEntry(): void; addBytes(count: number): void },
+  signal: AbortSignal | undefined,
+): Promise<void> {
+  limits.addEntry()
+  const name = entry.fileName
+  if (name.includes('\\') || name.includes('\0') || isAbsolute(name)) throw new Error(`技能包包含非法路径：${name}`)
+  const normalized = normalize(name)
+  if (normalized === '..' || normalized.startsWith(`..${sep}`)) throw new Error(`技能包路径越界：${name}`)
+  const output = resolve(target, normalized)
+  const inside = relative(target, output)
+  if (inside.startsWith('..') || isAbsolute(inside)) throw new Error(`技能包路径越界：${name}`)
+  const mode = (entry.externalFileAttributes >>> 16) & 0o170000
+  if (mode === 0o120000) throw new Error(`技能包不允许符号链接：${name}`)
+  if (name.endsWith('/')) {
+    await mkdir(output, { recursive: true })
+    return
+  }
+  limits.addBytes(entry.uncompressedSize)
+  await mkdir(dirname(output), { recursive: true })
+  const input = await openReadStream(zip, entry)
+  let actualBytes = 0
+  const counter = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      actualBytes += chunk.length
+      if (actualBytes > entry.uncompressedSize || signal?.aborted) callback(new Error('技能包内容长度异常或安装已取消'))
+      else callback(null, chunk)
+    },
+  })
+  await pipeline(input, counter, createWriteStream(output, { flags: 'wx', mode: 0o600 }), { signal })
+}
+
+function openZip(path: string): Promise<ZipFile> {
+  return new Promise((resolvePromise, rejectPromise) => {
+    yauzl.open(path, { lazyEntries: true, strictFileNames: true, validateEntrySizes: true }, (error, zip) => {
+      if (error !== null) rejectPromise(error)
+      else if (zip === undefined) rejectPromise(new Error('无法打开技能包'))
+      else resolvePromise(zip)
+    })
+  })
+}
+
+function openReadStream(zip: ZipFile, entry: Entry): Promise<NodeJS.ReadableStream> {
+  return new Promise((resolvePromise, rejectPromise) => {
+    zip.openReadStream(entry, (error, stream) => {
+      if (error !== null) rejectPromise(error)
+      else if (stream === undefined) rejectPromise(new Error(`无法读取技能包条目：${entry.fileName}`))
+      else resolvePromise(stream)
+    })
+  })
+}
+
+async function findSingleSkillRoot(root: string): Promise<string> {
+  const found: string[] = []
+  async function walk(directory: string): Promise<void> {
+    const entries = await readdir(directory, { withFileTypes: true })
+    if (entries.some(entry => entry.isFile() && entry.name === 'SKILL.md')) found.push(directory)
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.toLowerCase() === '__macosx') continue
+      await walk(join(directory, entry.name))
+    }
+  }
+  await walk(root)
+  if (found.length === 0) throw new Error('无效的技能包：缺少 SKILL.md')
+  if (found.length > 1) throw new Error('无效的技能包：包含多个 SKILL.md 根目录')
+  return found[0]
+}
+
+async function parseSkillManifest(path: string): Promise<{ name: string }> {
+  const content = await readFile(path, 'utf8')
+  const match = /^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(content)
+  if (match === null) throw new Error('无效的 SKILL.md：缺少 YAML frontmatter')
+  const data = loadYaml(match[1])
+  if (typeof data !== 'object' || data === null) throw new Error('无效的 SKILL.md：frontmatter 不是对象')
+  const name = (data as Record<string, unknown>).name
+  const description = (data as Record<string, unknown>).description
+  if (typeof name !== 'string') throw new Error('无效的 SKILL.md：缺少 name')
+  assertSkillName(name)
+  if (typeof description !== 'string' || description.trim().length === 0) throw new Error('无效的 SKILL.md：缺少 description')
+  return { name }
+}
+
+function assertSkillName(name: string): void {
+  if (!SKILL_NAME.test(name)) throw new TypeError(`无效的技能名称：${name}`)
+}
+
+async function installedMeta(target: string): Promise<SkillMarketMeta | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(join(target, SKILL_MARKET_META_FILE), 'utf8')) as unknown
+    if (typeof parsed !== 'object' || parsed === null) return undefined
+    const value = parsed as Record<string, unknown>
+    if (!Number.isSafeInteger(value.id) || typeof value.name !== 'string') return undefined
+    return { id: value.id as number, name: value.name, version: typeof value.version === 'string' ? value.version : undefined }
+  } catch (error) {
+    if (isMissing(error) || error instanceof SyntaxError) return undefined
+    throw error
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path)
+    return true
+  } catch (error) {
+    if (isMissing(error)) return false
+    throw error
+  }
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT'
+}

package/src/skill-market/runtime.ts

@@ -0,0 +1,14 @@
+import { SkillMarketApi } from './api.ts'
+import { SkillMarketInstaller } from './installer.ts'
+import type { ResolvedSkillMarketConfig } from './types.ts'
+
+/** Shared skill-market operations consumed by Web routes and the terminal scene. */
+export class SkillMarketRuntime {
+  readonly api: SkillMarketApi
+  readonly installer: SkillMarketInstaller
+
+  constructor(readonly config: ResolvedSkillMarketConfig) {
+    this.api = new SkillMarketApi(config)
+    this.installer = new SkillMarketInstaller(this.api, config)
+  }
+}