External Builtin Skill Pack

September 6, 2026 · View on GitHub

将 961 个 Builtin Skill 从 Git 仓库和 npm package 中移除，打包成独立 GitHub Release Asset； 运行时未安装时 Settings UI 显示「初始化」，由用户点击后 Host 安全下载、SHA256 校验、原子安装并重扫 Skill Registry。

Architecture

dsh-pentester npm package                 GitHub Release
├── lib/                                  └── dsh-pentester-skills-v1.0.0.tar.gz
├── presets/                                  └── skills/  (6 bundles + 5 standalone)
├── agents/                                    sha256 (embedded manifest)
├── lib/generated/skill-search-index.json
├── lib/generated/skill-search-aliases.json
├── lib/generated/skill-pack-manifest.json   ← version/tag/asset/sha256
└── UI/runtime
        │  references exact Skill Pack version
        ▼
$DSH_HOME/dsh-pentester/skill-packs/1.0.0/skills/   ← Builtin（初始化安装）
$DSH_HOME/dsh-pentester/skills/                     ← Custom（严禁混用）

核心分离：

Code Package ≠ Builtin Skill Data
Builtin Skill Pack ≠ User Custom Skills
Builtin Skill Pack missing ≠ plugin broken

Git changes

  • skills/ untracked + ignored（git rm -r --cached skills/ + .gitignore /skills/）。
  • 本地 skills/（67MB）保留，仅用于构建 Skill Pack。
  • dist/skill-packs/ + *.skill-pack.tar.gz 加入 .gitignore（Release Asset 不 commit）。
  • 原未 push commit 6780d73 被 amend（见 §Release）。

Skill Pack format

dsh-pentester-skills-v1.0.0.tar.gz
└── skills/
    ├── anthropic-cybersecurity.skills/
    ├── ctf-skills.skills/
    ├── hack-skills.skills/
    ├── pentest-skills.skills/
    ├── reverse-skills.skills/
    ├── strix.skills/
    ├── hello_js_reverse.skill/
    ├── hxbai-knowledge.skill/
    ├── secknowledge-skill.skill/
    ├── security-reporter.skill/
    └── src-hunter.skill/

Deterministic：固定 mtime=0 / uid=gid=0，文件排序，gzip level 9。相同内容 → 相同 SHA256。

Versioning

Builtin Skill Pack 使用独立版本（不隐式等于 npm package version）。

version   1.0.0
tag       skill-pack-v1.0.0
asset     dsh-pentester-skills-v1.0.0.tar.gz

Manifest

src/generated/skill-pack-manifest.json（commit），build 时复制到 lib/generated/skill-pack-manifest.json（npm 发布）。

{
  "schemaVersion": 1,
  "version": "1.0.0",
  "tag": "skill-pack-v1.0.0",
  "asset": "dsh-pentester-skills-v1.0.0.tar.gz",
  "sha256": "d71b36b324514e65a5ea2ae75203342af2520758a88739ffc04df164dd636c84",
  "leafSkills": 961,
  "bundles": 6,
  "standalone": 5
}

Runtime 用 version/tag/asset/sha256 pin 精确 Release（不用 GitHub latest）。

Release

  • 仓库 github.com/fb0sh/dsh-pentester，URL 由 host runtime + embedded manifest 生成，不接受 model/UI 传 URL。
  • Release title：Builtin Skill Pack v1.0.0；asset：dsh-pentester-skills-v1.0.0.tar.gz + .sha256。

Install paths

Builtin:  $DSH_HOME/dsh-pentester/skill-packs/1.0.0/skills/   (+ .installation.json)
Custom:   $DSH_HOME/dsh-pentester/skills/
Override: $DSH_HOME/dsh-pentester/agents/ + agent-overrides/

Initialization flow

status missing
→ user clicks 初始化
→ host downloader（HTTPS github.com + timeout + size limit + status）
→ temporary archive
→ sha256 verify
→ staging dir
→ safe extract（防路径穿越 / 拒绝 symlink）
→ validate scanned skills（961/6/5）
→ write .installation.json
→ atomic rename
→ onInstalled → AgentLibrary rescan builtin + notify client
→ ready（961 Skills · 6 Bundles）

Integrity verification

  • 下载：fetch + AbortController timeout（120s）+ content-length 上限（256MB）+ 非 github.com HTTPS 拒绝。
  • SHA256：archive 字节与 embedded manifest 精确比对。
  • 提取：所有 entry resolve 后必须位于 staging root；拒绝 ../ / 绝对路径 / symlink / link。
  • ready 判定：expected version + expected sha256 + installation marker + skills 目录（缺一即 corrupt）。

Atomic install

skill-packs/
├── .staging-xxxxx/    ← 下载/校验/提取/验证阶段
└── 1.0.0/             ← 完成后 atomic rename

失败清理 staging，保留现有正常版本（corrupt 场景先 rename 旧目录，失败回滚）。

Skill Registry behavior when missing

  • missing 是正常产品状态：plugin 正常启动，Typert RPC / Settings / Agent Library 全部可用。
  • 9 个 Builtin Agent profile 仍显示；resolveAgentProfile 不因 skill 缺失抛错（validateRef 在 missing 时降级）。
  • 真正 PTES delegation 时若 Agent 的 grant 含 Pack 缺失下无法解析的 skill（builtin）且 Pack 未初始化 → pentester_delegate 纯 preflight 阶段整批拒绝，domain error builtin_skill_pack_required（0 side effects，提示去 Settings 初始化）。Custom-only Agent 不受影响（custom skill 不依赖 Pack）。
  • Custom Skills / Custom Agent Profiles 管理不受影响。

Settings UI states

missing   → Empty/Setup 状态 + [初始化 Builtin Skills]
installing → [初始化 Builtin Skills] 禁用 + "正在初始化…"
ready     → 正常 Library（961 Skills · 6 Bundles）
error     → 初始化失败 <sanitized> + [重试]
corrupt   → 损坏 + [重新初始化]
outdated  → Installed X / Required Y + [更新]

全部经 remote.pentesterAgentLibrary.command → skillPack.status / skillPack.initialize，不直接 fetch GitHub。

Custom Skill isolation

初始化 / 修复 / 更新绝不 touch $DSH_HOME/dsh-pentester/skills/、agents/、agent-overrides/。

Build / package changes

  • package.json files 移除 skills（pnpm pack 确认 skills 不在 npm 包）。
  • pnpm build 不依赖本地 skills/（clean clone 无 skills/ 可 build；build 从 analysis/ 生成 search index）。
  • 新增 scripts：skill-pack:build（deterministic archive + sha256 + manifest）、skill-pack:verify（extract + scan + 统计校验）。
  • validate:skills 支持 DSH_PENTESTER_BUILTIN_SKILLS_DIR env override。

Tests

test/skill-pack.test.ts（14）+ test/agent-library.test.ts（boundary 更新）：

status missing/ready/corrupt/outdated
download sha256 mismatch / HTTP error / 非 github URL 拒绝
extract 路径穿越 / 绝对路径拒绝
initialize 原子安装 / existing valid / 失败不破坏现有安装
Typert boundary（skillPack.status / skillPack.initialize 通过 strict schema）

Known limitations

  • 无 progress streaming（installing 状态 + 1.5s snapshot 轮询，不引入复杂 streaming）。
  • outdated 不自动下载（坚持用户显式点击）。
  • Release 上传需网络；smoke 需真实 GitHub Release。

Release smoke

（Release 创建后）临时 DSH_HOME 无 Skill Pack → Settings → Skills 显示初始化 → 点击 → GitHub Release 下载 → sha256 → 提取 → 验证 → rescan → 961 Skills / 6 Bundles。