智能体技能路由框架zprolab/WhaleKit

WhaleKit

WhaleKit 是面向 DeepSeek Harness (DSH) 的智能体技能框架。它是一组可组合、DSH 原生的 SKILL.md 技能，外加一个确保智能体使用它们的入口技能——为从上游路线图实现完全自主而构建，并通过对抗性审查机制加固以抵御幻觉。

它与 install.sh 一起，用五级路由仪式取代了二元技能调用（Superpowers 的弱点）：每个任务选择相应的流程深度，从 L1 的无流程一直到 L5 的完整仪式。Git 是可追溯层；每份权威文档都可修订，但每次修订都是一次提交。

快速开始

1. 安装

在仓库根目录运行安装程序：

./install.sh                 # install into ~/.dsh/skills (DSH_HOME overrides the root)
./install.sh --project       # install into /.dsh/skills instead
./install.sh --uninstall     # remove every WhaleKit skill symlink (works with --project too)

- 默认：将所有 22 个技能符号链接到 $DSH_HOME/skills（默认为 ~/.dsh/skills）。
- --project：符号链接到 /.dsh/skills，DSH 将其排在主目录根之上。
- --uninstall：移除每个 WhaleKit 符号链接以及被清空的目标目录。
- 选项与顺序无关（install.sh --uninstall --project 行为完全相同）。

DSH 从 /.dsh/skills（排名 100）发现技能，先于 ~/.dsh/skills（排名 400），因此项目本地安装优先于全局安装。

2. 首次会话

using-whalekit 是入口技能：必须在任何对话开始时调用。在 using-whalekit 之后，调用 whalekit-conventions（强制）——这是规范的全局约定技能，在任何任务工作开始之前约束每个智能体，包括子智能体。当你开始一项任务时，WhaleKit 会对其进行分类（琐碎 vs 非琐碎），如有需要则运行 targeted-exploration，推荐一个路由层级，并呈现 2–3 个层级选项供你选择。用户的决定是系统提示之下最高权威——智能体绝不单独选择层级。

五个层级

WhaleKit 用渐进式路由菜单取代了二元技能调用。每个任务选择相应的流程深度，从 L1 的无流程一直到 L5 的完整仪式。核心流程：

Session start → using-whalekit (mandatory entry)
→ Task assessment: is exploration needed?
├─ Trivial task (one-line fix) → artifact chain at Q1
└─ Non-trivial task → targeted-exploration (target = task core or whole project)
→ Exploration report: findings + evidence + risks + scope estimate
→ Main agent applies routing: asks the artifact chain one question at a time
(Q1 memo? → Q2 spec? → Q3 plan? → Q4 dual?)
→ User answers each question (gold standard)
→ Skills gated by reached tier → execution

| 层级 | 流程 | 触发信号（来自探索报告） |
|---|---|---|
| L1 立即实施 | 无流程 | 纯机械性变更，风险极低 |
| L2 仅备忘录 | 备忘录持久化到磁盘 | 小型功能，单文件 |
| L3 备忘录 → 规格说明 | + 规格说明 | 中型功能，涉及接口 |
| L4 备忘录 → 规格说明 → 计划 | + 实施计划 | 大型功能，多文件/多模块 |
| L5 完整 | + 双重记录 | 新项目，架构级别，方向性决策 |

层级通过产物链一次一个问题地达成——层级 = 链条延伸了多远（备忘录 → 规格说明 → 计划 → 双重记录，一次一个问题）：Q1 回答“否”则停在 L1，仅备忘录为 L2，备忘录 + 规格说明为 L3，备忘录 + 规格说明 + 计划为 L4，双重记录为 L5。

路由的铁律：

1. 用户是黄金标准。 任何层级建议都必须提供 2–3 个选项；由用户选择。
智能体绝不单独决定层级。
2. 单向棘轮。 任务中途发现的隐藏复杂性会升级层级——停下来，说明情况，升级。
任务中途不得降级。
3. 先探索，后建议。 非平凡任务的层级建议必须基于
定向探索报告，绝不能基于印象。

技能清单

22 项技能（9 项原创 + 13 项改编）。改编技能保留其
Adapted from obra/superpowers (MIT) 头部；归属信息见各 SKILL.md 头部。

| 技能 | 来源 |
|---|---|
| using-whalekit | 原创 — 入口技能，路由启动 |
| whalekit-conventions | 原创 — 约束所有智能体的规范全局约定 |
| targeted-exploration | 原创 — 子智能体驱动的防偏离探索，为路由提供输入 |
| routing | 原创 — 五个层级、门控、单向棘轮 |
| adversarial-review | 原创 — 红/蓝/黑元技能（决策 + 审查模式） |
| dual-records | 原创 — DEVELOPMENT.md + README.md（可修订的真相） |
| commit | 原创 — 提交策略门控 + 逻辑提交流程 |
| clarification-questioner | 原创 — 提问方法论：生成 → 筛选 → 一次问一个 → 将答案收敛为经过验证的结论表（清晰度/质量已检查），然后再设计 |
| decision-approval | 原创 — 被豁免的决策形成草稿表（提案/理由/替代方案/置信度），由用户批准或编辑后生效 |
| socratic-brainstorming | 改编（重度）— 来自 obra/superpowers brainstorming |
| test-driven-development | 改编 — 来自 obra/superpowers |
| systematic-debugging | 改编 — 来自 obra/superpowers |
| verification-before-completion | 改编 — 来自 obra/superpowers |
| requesting-code-review | 改编 — 来自 obra/superpowers |
| receiving-code-review | 改编 — 来自 obra/superpowers |
| using-git-worktrees | 改编 — 来自 obra/superpowers |
| finishing-a-development-branch | 改编 — 来自 obra/superpowers |
| writing-plans | 改编 — 来自 obra/superpowers |
| executing-plans | 改编 — 来自 obra/superpowers |
| subagent-driven-development | 改编 — 来自 obra/superpowers |
| writing-skills | 改编 — 来自 obra/superpowers（技能 TDD） |
| dispatching-agents | 改编 — 来自 obra/superpowers（通用委派协议；2026-08-14 从搁置的并行克隆重新划定范围） |

设计哲学

- 用户是金标准。 用户的决定是系统提示之下的最高权威。每个重大决策都会呈现 2–3 个选项；智能体绝不独自决定。
- 仪式随任务而伸缩。 流程深度是分级的（5 个层级），并按任务选择；小任务得到小流程。这是对 Superpowers 二元调用问题的直接回应。
- 以对抗性审查对抗幻觉。 重大决策和架构级缺陷会经过红/蓝/黑子智能体循环（决策模式）以及审查模式的红方发现/蓝方修复循环，而非单智能体判断。
- 可修订的真相。 审查基线（双重记录中的 README.md）具有权威性，但明确可修订，且每次修订都在 git 中留痕。

所有文档构成一条金标准链——Dual → Plan → Spec → Memo → User requirement——其中用户需求是最高权威，而实时的用户决策优先于该链。流程产物经同意进入 git：每次产物写入之前都会进行提交策略检查。

安装

单个 install.sh 将技能符号链接到 DSH 根目录，并带有 --project（项目本地 .dsh/skills）和 --uninstall 模式。参见快速开始。

测试

通过 tests/pressure// 中的压力场景进行技能 TDD——每个技能有 ≥2 个场景（一个跳过诱惑，一个误导性执行）外加 pass-criteria.md。运行测试框架：

tests/run.sh           # print the scenario prompt and pass criteria
tests/run.sh  --dispatch  # print a ready-to-use subagent dispatch prompt
tests/run.sh  --live      # print a manual live-session verification checklist

--live 是为入口敏感型技能（其仪式会被  块正确地豁免于被派发的子智能体）以及任何需要实时用户交互的技能而存在的。

路线图

- v0.1（当前）： 仅 DSH，编码领域，22 个技能，五级路由。
- v0.2（计划中——2026-08-14 决策）： 多运行时规划。仅 DSH 是一种集中风险（SuperPowers 移植到许多测试框架）；评估将技能集适配到其他测试框架以减少单一运行时暴露。范围和时程由规范级决策确定。

许可证

MIT。部分内容改编自 obra/superpowers（MIT）；归属信息见各个 SKILL.md 头部。