Skill Runtime V2

September 4, 2026 · View on GitHub

dsh-pentester 的 Worker 能力运行时：Agent 拥有什么能力、Worker 如何发现并加载专项 Skill。 本文是 Skill Runtime V2 的正式入口；实现历史见文末 Implementation History。

Builtin Skills 分发（External Skill Pack）：961 个 Builtin Skill 不随 Git 仓库 / npm package 分发， 而是打包为独立 GitHub Release Asset（dsh-pentester-skills-vX.Y.Z.tar.gz，含 SHA256 + manifest）。 运行时未安装时，Settings → Pentester → Skills 显示「初始化」，用户点击后 Host 安全下载、 SHA256 校验、原子安装到 $DSH_HOME/dsh-pentester/skill-packs/<version>/skills/ 并重扫 Registry。 $DSH_HOME/dsh-pentester/skills/ 继续只属于 Custom / User Skills（严禁混用）。 实现细节见 docs/external-skill-pack-implementation.md。

1. 核心三分：Assignment ≠ Search ≠ Load

三者是不同概念，不能混为一谈：

Skill Assignment  = Agent 被授权使用什么能力（allowedSkillIds）
Skill Search      = Subagent 在当前任务中发现什么能力可能有用
Skill Load        = 真正读取哪些 SKILL.md 到上下文

一个 Agent 可以被授权 50 / 100 / 150 个 Skill（Assignment），但 Worker 在任何时刻 Loaded Skills 从 0 开始，只在执行中按需 Load 少量（通常 1~4 个）。

Allowed Skills  ≠  Loaded Skills

2. Bundle 与 Leaf

*.skills/  = 可分配的 Bundle（顶层 collection）
*.skill/   = 可分配的 Leaf Skill（含 SKILL.md）

Bundle 内的 Leaf 也可以独立分配。例如：

pentest-skills.skills/
└── web/
    └── sql-injection.skill/

既可以分配整个 Bundle pentest-skills，也可以只分配 Leaf sql-injection。 内置 Agent 默认使用精确 Leaf Grant；Bundle Grant 保留给用户想整体授权的场景。

3. Agent Grant

Agent Profile（profile.yml）
   ↓  Bundle / Leaf Grant
Resolve（单继承 + skills ∪ skillsRemove）
   ↓
allowedSkillIds（+ provenance）
  • 9 个 Builtin Agent 有默认 Grant（见 §7 Topology）。
  • 用户自定义方式：
    • Create Profile From This（extends 某 builtin，推荐长期方式）
    • skills / skillsRemove（leaf 或 bundle）
    • Builtin Override（agent-overrides/<id>.yml，不修改 builtin 文件）
    • Reset Override
  • 推荐长期自定义用「Custom Agent Profile extends Builtin」，而不是直接改 builtin package 文件。

4. Runtime 流程

Worker Spawn
   ↓
Loaded Skills = 0

执行中发现需要专项能力
   ↓
pentester_skill_search（只搜 allowedSkillIds，返回多个候选 + recommendedLoad）
   ↓
pentester_skill_load（一次加载 1~N，去重、拒绝越权）
   ↓
继续执行

5. Immutable Snapshot

Worker 创建时，Host 把能力边界冻结到两个位置：

delegation/input/agent-profile.json
   = allowedSkillIds + skill revisions（immutable metadata，无 Skill Body）

pentesterHome/runtime/skill-snapshots/<target-id>/<run-id>/<stage>-<D-xxx>/
   = frozen Skill Bundle 快照（Host-private，不 mount 进 /workspace）

完整 Skill Body 唯一入口 = pentester_skill_load。Worker 运行期间修改 Agent Profile 或 Custom Skill 不能静默改变正在运行的 Worker 的能力边界（search/load 只读 frozen snapshot，绝不重新 resolve 当前 Profile）。

6. Search Pipeline

pentester_skill_search 是 deterministic 检索（不调用 runtime LLM）：

Query Normalization
→ Alias Expansion（security terms + tool aliases）
→ Structured Match（exact id / technique / tool / capability / family）
→ Field-weighted BM25（name/technique/tools 高权重）
→ Candidate Top-N（高 recall，候选 ~25）
→ Relation/family-aware MMR（relevance + coverage − redundancy）
→ Top Results（3~8）
→ recommendedLoad（1~4，general/specialist/tool 组合）

权限模型：候选生成一开始就限定 allowedSkillIds，绝不从全局召回再过滤。

当前检索质量（101 query + 50 paraphrase，详见 §8 History）：

Recall@3 = 0.901   Recall@5 = 0.941   Recall@8 = 0.99   MRR = 0.777
MustRecall Miss Rate = 0.01   Duplicate Rate = 0.366
Paraphrase Stability = 1.0   Tool Exact Recall = 1.0   Technique Exact Recall = 1.0

Semantic Retrieval Evaluated: YES，Enabled: NO —— deterministic hybrid 已达到质量目标， 没有必要引入 embedding / vector DB / runtime LLM 的复杂度。

7. Builtin Agent Topology

9 个 Builtin Agent：

web  recon  threat-model  vulnerability  validation  impact  reporting
active-directory  cloud

Stage 绑定（src/stages.ts DEFAULT_STAGE_AGENTS）：

pre-engagement          []
intelligence-gathering  [recon, web]
threat-modeling         [threat-model]
vulnerability-analysis  [web, vulnerability, active-directory, cloud]
exploitation            [validation, active-directory, cloud]
post-exploitation       [impact, active-directory, cloud]
reporting              [reporting]

8. Implementation History

开发审计记录（按时间）：

9. Future / Optional（未实现）

以下为 follow-up，非当前功能：

V2.4 Real PTES Skill Runtime Evaluation
74 manual-review grants
Embedding / semantic vector retrieval
Worker Loaded Skills UI
DSH native tool-skill migration