@boostkit-dsh/skill-market 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 0.3.1 - 2026-09-22
+
+- 首次发布前将包名缩短为 `@boostkit-dsh/skill-market`，避免重复 scope 中的 `boostkit`。
+- 将 DSH 精确兼容基线升级为 `0.1.7-alpha.1`，并同步鉴权依赖到 `@boostkit-dsh/auth-management@0.1.1`。
+
+## 0.3.0 - 2026-09-22
+
+- 对鉴权与审计管理增加精确硬依赖，禁止匿名浏览、读取和修改 Skill。
+- 安装、更新、启停和卸载写入最小化本地审计事件。
+
+## 0.2.2 - 2026-09-20
+
+- 安装目标改为市场页面中明确选择的 DSH 工作区，不再取启动 `dsh web` 时的当前目录。
+- Host 只接受已登记的工作区 ID，并按 DSH filesystem Skill Provider 相同的向上 `.git` 规则确定项目根目录。
+- 工作区选择器只展示工作区名称；catalog 接口不再返回项目和 Skill 的绝对路径。
+
+## 0.2.1 - 2026-09-20
+
+- Skill 详情使用 DSH 原生 Markdown 组件渲染完整 `SKILL.md`，不再展示原始 Markdown 文本。
+- 启用/禁用控件直接复用 DSH 原生 `Switch`，与 DSH 其他设置控件保持一致。
+- 启停和卸载成功后在前端就地更新状态，移除多余的远程 npm catalog 强制刷新。
+
+## 0.2.0 - 2026-09-20
+
+- 将市场从设置页迁移为 DSH 首页左侧导航中的独立主页面。
+- 列表仅展示简短说明和必要状态，长说明最多显示两行。
+- 已安装 Skill 可打开详情弹窗并滚动查看完整 `SKILL.md`。
+- 详情弹窗支持启用、禁用和卸载；禁用保留文件与版本锁记录。
+- 移除页面中的项目绝对路径和 Skill 安装目录展示。
+
+## 0.1.0 - 2026-09-20
+
+- 建立 BoostKit Skill npm catalog 协议及完整性校验。
+- 支持项目级 Skill 安装、更新、卸载和精确版本锁定。
+- 提供 DSH 设置区的 Skill 浏览、搜索、详情和操作页面。
+- 增加分类筛选、结果统计、分享信息和 GitCode 贡献入口。
+- 展示实际项目与 Skill 安装目录，便于现场验证安装结果。

package/README.md

@@ -0,0 +1,85 @@
+# BoostKit Skill 市场
+
+`@boostkit-dsh/skill-market` 是一个可独立安装的 DSH 插件，用于浏览、安装、启停、更新和卸载 BoostKit 项目级 Skill。
+
+`0.3.0` 起要求 GitCode 鉴权；当前版本精确依赖 `@boostkit-dsh/auth-management@0.1.1`。目录、详情和全部变更都要求有效 GitCode ActorRef，不提供匿名浏览；安装、更新、启停和卸载会记录不含 Skill 正文的最小化审计事件。
+
+## 市场能力
+
+- 浏览 BoostKit Skill 目录，按名称、说明、标签搜索并按类别筛选；
+- 在 DSH 首页左侧导航中提供独立市场页面，位置在插件入口之后、工作区之前；
+- 在页面顶部明确选择安装目标工作区；默认选择 DSH 工作区列表中的第一项，只展示工作区名称；
+- 列表采用渐进披露，只展示简短说明、分类、少量标签、版本和安装状态；
+- 点击已安装 Skill 可在弹窗中滚动查看 DSH 原生渲染后的完整 `SKILL.md`，并通过 DSH 原生开关启用或禁用、或在左下角卸载；
+- 展示 Skill 的源码位置、精确 npm 包版本和当前项目安装状态；
+- 一键复制可分享的 Skill 信息，或进入 GitCode 提交贡献；
+- 安装、更新和卸载项目级 Skill，并在 `.boostkit-lock.json` 中锁定版本；
+
+首次联调可直接按[手工测试说明](../../docs/boostkit-skill-market-manual-test.md)准备两个最小测试包并完成页面验收。
+
+## 边界
+
+- 运行时目录来自 `@boostkit-dsh/skills-catalog`，通过 npm registry、镜像或 CDN 分发；
+- GitCode 只保存 Skill 源码和 PR，不作为日常下载源；
+- Skill 安装到项目根目录的 `.dsh/skills/<name>/`，由 DSH 原生 filesystem Skill Provider 发现；
+- 禁用时 Skill 可逆移动到 `.dsh/skills/.disabled/<name>/`，保留内容与 lock 记录，但不再被 DSH 发现；
+- 启停只执行同文件系统目录移动与 lock 原子写入，成功后前端就地更新，不刷新远程 npm catalog；
+- 安装器只下载、校验和解包文件，不运行 `preinstall`、`install`、`postinstall` 或 Skill 脚本；
+- 编辑、试运行和贡献 PR 属于 Skill Studio，不在本插件中实现。
+
+## 安装作用域
+
+页面中的“安装到工作区”是安装目标的唯一真源。浏览器只提交 DSH 工作区 ID，Host 从 `workspaceRegistry` 读取已登记路径，再使用 DSH filesystem Skill Provider 相同的规则向上查找最近的 `.git`：找到时以该 Git 根目录为项目根，未找到时以工作区路径本身为项目根。Skill 最终写入该项目根的 `.dsh/skills/`。
+
+因此，启动 `dsh web` 的当前目录不会影响页面发起的安装、更新、启停、详情读取或卸载。多个工作区之间的本地安装状态相互独立，切换选择器时页面会重新读取对应项目。
+
+可选配置：
+
+```yaml
+- id: boostkit-skill-market
+  name: '@boostkit-dsh/skill-market'
+  config:
+    projectRoot: /path/to/project
+    catalogPackage: '@boostkit-dsh/skills-catalog'
+```
+
+`projectRoot` 仅作为没有传入工作区 ID 的兼容回退（例如直接调用 Host 服务）使用，不会覆盖页面中选择的已登记工作区，也不会在市场页面展示。插件只修改最终项目根中的 `.dsh/skills/` 和 `.dsh/skills/.boostkit-lock.json`。
+
+## Catalog 协议
+
+目录包中的 `catalog.json` 使用协议版本 `1`：
+
+```json
+{
+  "protocol": 1,
+  "release": "0.1.0",
+  "skills": [
+    {
+      "name": "example-skill",
+      "package": "@boostkit-dsh/skill-example-skill",
+      "version": "0.0.0-0123456789ab",
+      "commit": "0123456789abcdef0123456789abcdef01234567",
+      "integrity": "sha512-...",
+      "displayName": { "zh": "示例 Skill", "en": "Example Skill" },
+      "description": "示例说明",
+      "category": "development",
+      "tags": ["example"],
+      "source": {
+        "repository": "https://gitcode.com/boostkit/skills",
+        "path": "skills/example-skill"
+      }
+    }
+  ]
+}
+```
+
+每个 Skill npm 包在包根目录提供 `SKILL.md` 和相关资源。catalog 中的 integrity 必须与 npm exact-version manifest 一致；安装器还会重新计算 tarball 的 SHA-512。
+
+## 安装安全
+
+- 只接受 `@boostkit-dsh/skill-*` 精确版本包；
+- 拒绝路径穿越、绝对路径、符号链接和硬链接；
+- 限制 tarball 大小、解压后大小和文件数量；
+- 使用同文件系统临时目录和 rename 替换 Skill；
+- 不覆盖没有 lock 记录的同名本地 Skill；
+- 卸载只移除由本市场 lock 文件登记的 Skill。

package/archive.js

@@ -0,0 +1,108 @@
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, posix } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+
+const MAX_TARBALL_BYTES = 20 * 1024 * 1024
+const MAX_UNPACKED_BYTES = 50 * 1024 * 1024
+const MAX_FILES = 500
+
+function headerString(header, start, length) {
+  return header.subarray(start, start + length).toString('utf8').replace(/\0.*$/s, '')
+}
+
+function octalField(header, start, length, field) {
+  const value = headerString(header, start, length).trim()
+  if (!/^[0-7]*$/.test(value)) throw new Error(`npm tarball ${field} 非法`)
+  const parsed = Number.parseInt(value || '0', 8)
+  if (!Number.isSafeInteger(parsed) || parsed < 0) throw new Error(`npm tarball ${field} 非法`)
+  return parsed
+}
+
+function safePackagePath(path) {
+  if (!path.startsWith('package/') || path.includes('\\') || path.includes('\0')) throw new Error(`npm tarball 路径非法：${path}`)
+  const relative = path.slice('package/'.length).replace(/\/+$/, '')
+  if (relative === '' || relative.startsWith('/') || relative.split('/').includes('..')) throw new Error(`npm tarball 路径非法：${path}`)
+  const normalized = posix.normalize(relative)
+  if (normalized === '.' || normalized.startsWith('../') || normalized !== relative) throw new Error(`npm tarball 路径非法：${path}`)
+  return normalized
+}
+
+/** Verify a buffer against an npm SHA-512 Subresource Integrity value. */
+export function verifyIntegrity(buffer, integrity) {
+  if (typeof integrity !== 'string' || !integrity.startsWith('sha512-')) throw new Error('npm integrity 必须使用 sha512')
+  const expected = Buffer.from(integrity.slice('sha512-'.length), 'base64')
+  const actual = createHash('sha512').update(buffer).digest()
+  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) throw new Error('npm tarball integrity 校验失败')
+}
+
+/** Parse safe regular-file and directory entries from an npm .tgz archive. */
+export function readPackageEntries(tarball) {
+  if (!Buffer.isBuffer(tarball)) throw new TypeError('tarball 必须是 Buffer')
+  if (tarball.length > MAX_TARBALL_BYTES) throw new Error('npm tarball 超过 20 MiB')
+  const archive = gunzipSync(tarball, { maxOutputLength: MAX_UNPACKED_BYTES })
+  const entries = []
+  const paths = new Set()
+  let totalBytes = 0
+  for (let offset = 0; offset + 512 <= archive.length;) {
+    const header = archive.subarray(offset, offset + 512)
+    if (header.every((byte) => byte === 0)) break
+    const name = headerString(header, 0, 100)
+    const prefix = headerString(header, 345, 155)
+    const path = prefix ? `${prefix}/${name}` : name
+    const size = octalField(header, 124, 12, '文件大小')
+    const mode = octalField(header, 100, 8, '文件模式')
+    const type = String.fromCharCode(header[156] || 48)
+    const contentStart = offset + 512
+    const contentEnd = contentStart + size
+    if (contentEnd > archive.length) throw new Error('npm tarball 文件越界')
+    offset = contentStart + Math.ceil(size / 512) * 512
+
+    // npm may add POSIX metadata headers. Skill packages use short paths, so
+    // the metadata itself is ignored and never allowed to redirect a path.
+    if (type === 'x' || type === 'g') continue
+    if (type !== '0' && type !== '\0' && type !== '5') throw new Error(`npm tarball 禁止文件类型 ${JSON.stringify(type)}：${path}`)
+    if (path === 'package' || path === 'package/') continue
+    const relative = safePackagePath(path)
+    if (paths.has(relative)) throw new Error(`npm tarball 路径重复：${relative}`)
+    paths.add(relative)
+    if (type === '5') {
+      entries.push({ type: 'directory', path: relative })
+      continue
+    }
+    totalBytes += size
+    if (totalBytes > MAX_UNPACKED_BYTES) throw new Error('npm tarball 解压内容超过 50 MiB')
+    if (entries.length >= MAX_FILES) throw new Error(`npm tarball 文件数超过 ${MAX_FILES}`)
+    entries.push({ type: 'file', path: relative, mode, content: Buffer.from(archive.subarray(contentStart, contentEnd)) })
+  }
+  return entries
+}
+
+/** Read one regular file from a verified npm tarball. */
+export function readPackageFile(tarball, wanted) {
+  const entry = readPackageEntries(tarball).find((candidate) => candidate.type === 'file' && candidate.path === wanted)
+  if (!entry) throw new Error(`npm tarball 缺少 ${wanted}`)
+  return entry.content
+}
+
+/** Extract safe npm package contents into an existing staging directory. */
+export function extractPackage(tarball, destination) {
+  const entries = readPackageEntries(tarball)
+  for (const entry of entries) {
+    const target = join(destination, ...entry.path.split('/'))
+    if (entry.type === 'directory') {
+      mkdirSync(target, { recursive: true })
+      continue
+    }
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, entry.content)
+    try { chmodSync(target, entry.mode & 0o111 ? 0o755 : 0o644) } catch { /* Windows or restricted filesystem */ }
+  }
+  return entries.filter((entry) => entry.type === 'file').map((entry) => entry.path)
+}
+
+export const archiveLimits = {
+  maxTarballBytes: MAX_TARBALL_BYTES,
+  maxUnpackedBytes: MAX_UNPACKED_BYTES,
+  maxFiles: MAX_FILES,
+}

package/catalog.js

@@ -0,0 +1,139 @@
+import { readPackageFile, verifyIntegrity } from './archive.js'
+
+export const DEFAULT_CATALOG_PACKAGE = '@boostkit-dsh/skills-catalog'
+export const DEFAULT_REGISTRIES = ['https://registry.npmjs.org', 'https://registry.npmmirror.com']
+
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const PACKAGE_RE = /^@boostkit-dsh\/skill-[a-z0-9][a-z0-9._-]*$/
+const VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+const COMMIT_RE = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/
+const INTEGRITY_RE = /^sha512-[A-Za-z0-9+/]+={0,2}$/
+const CATEGORY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function ownObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function requiredText(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') throw new Error(`skills catalog ${field} 必填`)
+  return value.trim()
+}
+
+function manifestUrl(registry, packageName, version) {
+  return `${registry.replace(/\/$/, '')}/${encodeURIComponent(packageName)}/${version}`
+}
+
+async function responseJson(response, label) {
+  if (!response?.ok) throw new Error(`${label} HTTP ${response?.status ?? 'unknown'}`)
+  return await response.json()
+}
+
+async function responseBuffer(response, label) {
+  if (!response?.ok) throw new Error(`${label} HTTP ${response?.status ?? 'unknown'}`)
+  return Buffer.from(await response.arrayBuffer())
+}
+
+function validateManifest(manifest, expectedPackage, expectedVersion) {
+  if (!ownObject(manifest) || manifest.name !== expectedPackage || manifest.version !== expectedVersion) throw new Error(`${expectedPackage}@${expectedVersion} npm manifest 身份不匹配`)
+  const tarball = manifest.dist?.tarball
+  const integrity = manifest.dist?.integrity
+  if (typeof tarball !== 'string' || !tarball.startsWith('https://') || !INTEGRITY_RE.test(String(integrity ?? ''))) throw new Error(`${expectedPackage}@${expectedVersion} npm 分发信息非法`)
+  return { tarball, integrity }
+}
+
+/** Validate and normalize one BoostKit Skill catalog document. */
+export function validateSkillCatalog(value, expectedRelease) {
+  if (!ownObject(value) || value.protocol !== 1 || !VERSION_RE.test(String(value.release ?? '')) || !Array.isArray(value.skills)) throw new Error('skills catalog 协议不匹配')
+  if (expectedRelease !== undefined && value.release !== expectedRelease) throw new Error(`skills catalog release ${String(value.release)} 与 npm 包版本 ${expectedRelease} 不一致`)
+  const names = new Set()
+  const packages = new Set()
+  const skills = value.skills.map((entry, index) => {
+    const prefix = `skills[${index}]`
+    if (!ownObject(entry) || !NAME_RE.test(String(entry.name ?? ''))) throw new Error(`${prefix}.name 非法`)
+    if (!PACKAGE_RE.test(String(entry.package ?? ''))) throw new Error(`${prefix}.package 必须属于 @boostkit-dsh/skill-*`)
+    if (!VERSION_RE.test(String(entry.version ?? ''))) throw new Error(`${prefix}.version 必须是精确 SemVer`)
+    if (!COMMIT_RE.test(String(entry.commit ?? ''))) throw new Error(`${prefix}.commit 必须是完整 Git commit`)
+    if (!INTEGRITY_RE.test(String(entry.integrity ?? ''))) throw new Error(`${prefix}.integrity 必须使用 sha512`)
+    if (!ownObject(entry.displayName)) throw new Error(`${prefix}.displayName 必填`)
+    const displayName = {
+      zh: requiredText(entry.displayName.zh, `${prefix}.displayName.zh`),
+      ...(entry.displayName.en === undefined ? {} : { en: requiredText(entry.displayName.en, `${prefix}.displayName.en`) }),
+    }
+    const description = requiredText(entry.description, `${prefix}.description`)
+    if (!CATEGORY_RE.test(String(entry.category ?? ''))) throw new Error(`${prefix}.category 非法`)
+    if (!Array.isArray(entry.tags) || entry.tags.some((tag) => typeof tag !== 'string' || tag.trim() === '')) throw new Error(`${prefix}.tags 非法`)
+    if (!ownObject(entry.source)) throw new Error(`${prefix}.source 必填`)
+    const repository = requiredText(entry.source.repository, `${prefix}.source.repository`)
+    const path = requiredText(entry.source.path, `${prefix}.source.path`)
+    if (!repository.startsWith('https://') || path.startsWith('/') || path.split('/').includes('..')) throw new Error(`${prefix}.source 非法`)
+    if (names.has(entry.name)) throw new Error(`Skill 名称重复：${entry.name}`)
+    if (packages.has(entry.package)) throw new Error(`Skill 包重复：${entry.package}`)
+    names.add(entry.name)
+    packages.add(entry.package)
+    return {
+      name: entry.name,
+      package: entry.package,
+      version: entry.version,
+      commit: entry.commit,
+      integrity: entry.integrity,
+      displayName,
+      description,
+      category: entry.category,
+      tags: [...new Set(entry.tags.map((tag) => tag.trim()))].sort(),
+      source: { repository, path },
+    }
+  }).sort((left, right) => left.name.localeCompare(right.name))
+  return { protocol: 1, release: value.release, skills }
+}
+
+async function fromRegistries(registries, task) {
+  const errors = []
+  for (const registry of registries) {
+    try {
+      return await task(registry)
+    } catch (error) {
+      errors.push(`${registry}: ${String(error?.message ?? error)}`)
+    }
+  }
+  throw new Error(errors.join('；') || '没有可用 npm registry')
+}
+
+/** Download and verify the published BoostKit Skill catalog package. */
+export async function loadRemoteCatalog(options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const packageName = options.packageName ?? DEFAULT_CATALOG_PACKAGE
+  const registries = options.registries ?? DEFAULT_REGISTRIES
+  const signal = options.signal
+  return await fromRegistries(registries, async (registry) => {
+    const latest = await responseJson(await fetchImpl(manifestUrl(registry, packageName, 'latest'), { signal, cache: 'no-store' }), `${registry} catalog manifest`)
+    if (!VERSION_RE.test(String(latest?.version ?? ''))) throw new Error('catalog npm 版本非法')
+    const distribution = validateManifest(latest, packageName, latest.version)
+    const tarball = await responseBuffer(await fetchImpl(distribution.tarball, { signal, cache: 'force-cache' }), `${registry} catalog tarball`)
+    verifyIntegrity(tarball, distribution.integrity)
+    const catalog = JSON.parse(readPackageFile(tarball, 'catalog.json').toString('utf8'))
+    return validateSkillCatalog(catalog, latest.version)
+  })
+}
+
+/** Download one exact Skill package and verify catalog, manifest and bytes agree. */
+export async function downloadSkillPackage(entry, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const registries = options.registries ?? DEFAULT_REGISTRIES
+  const signal = options.signal
+  return await fromRegistries(registries, async (registry) => {
+    const manifest = await responseJson(await fetchImpl(manifestUrl(registry, entry.package, entry.version), { signal, cache: 'no-store' }), `${registry} Skill manifest`)
+    const distribution = validateManifest(manifest, entry.package, entry.version)
+    if (distribution.integrity !== entry.integrity) throw new Error(`${entry.package}@${entry.version} integrity 与 catalog 不一致`)
+    const tarball = await responseBuffer(await fetchImpl(distribution.tarball, { signal, cache: 'force-cache' }), `${registry} Skill tarball`)
+    verifyIntegrity(tarball, entry.integrity)
+    return tarball
+  })
+}
+
+export const skillCatalogPatterns = {
+  name: NAME_RE,
+  package: PACKAGE_RE,
+  version: VERSION_RE,
+  commit: COMMIT_RE,
+  integrity: INTEGRITY_RE,
+}