swell05/dsh-whale-tank
鲸鱼缸——一个DSH 插件开发沙盒辅助工具：隔离 DSH_HOME，建立开发态的DSH配置沙箱与插件开发骨架、附带开发知识包、插拔副作用检测与沙箱复原、第三方插件vet体检功能
安装Install
dsh plugin --profile web add @swell05/dsh-whale-tank把 swell05/dsh-whale-tank 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
🐋 @swell05/dsh-whale-tank —— 一个小巧的鲸鱼缸
中文 · English
鲸鱼缸，为你提供两个功能：
🛠️ ① 造一个干净的插件开发专属“鱼缸”
🩺 ② 把拿不准的插件丢进单独的“鱼缸”做个体检
不动你真实的
~/.dsh。
🛠️ 创建插件开发沙盒
插件开发就像装修——总得先圈出工地，别把小鲸鱼的客厅弄脏。init 会：
- 建一个纯净沙盒：独立的
DSH_HOME+ 官方基线 profile +state.json，从此随便折腾，真身~/.dsh毫发无伤； - 按类型生成能直接构建的骨架（
host / client / both，tsdown 双配置、cordis.patch.yml、测试桩一条龙），附带一个开发工具包； - 可选载入开发知识包（AGENTS.md / NOTES.md / docs/dev-guidance）——写给其它 Agent 看的参考书，按 merge-spec 增量合并，绝不覆盖你写的内容，冲突只告警不自动动手。
🩺 插件在线体检
直接装插件没把握，装之前先装进鲸鱼缸把把关。vet 会走三阶段：
- 静态危害检查：
npm pack拉发布产物 → 规则引擎扫 install 脚本、凭据读取与流向、外联、eval/混淆——凭据按 source→sink 判级：读到 API key 是信号（正常 LLM 插件读 key 调已知服务商属预期、放行），凭据流向非服务商（硬编码/动态出口）才判高危；命中高危直接"不建议"，直接不执行； - 受限动态验证：复刻 profile → 两层冲突检测 → 插拔抵消（diff=0 才算干净），全程默认不执行不可信代码；
- LLM 源码审查：模型通读候选源码，找出规则引擎抓不到的"暗功夫"——混淆业务逻辑、误导性描述、可疑副作用/数据外发、版本投毒迹象，与规则引擎互相兜底；
体检结果放在本地文件：vet-report.md（人读）+ vet-result.json（机器读）落在 .vetting/，结论三选一——未发现漏洞 / 谨慎 / 不建议。
⚠️ 注意事项：vet 是启发式预检，不是安全保证。隔离靠独立 DSH_HOME + 受限执行，防状态污染、不防本机执行；网络行为只记录不阻断。而且它只在 web 里经
/whale-tank-vet使用——CLI 暂不提供。
🚀 快速开始
npm 已发布，装进 DSH profile 即用。
安装 / 卸载
# 装进 web profile
dsh plugin --profile web add @swell05/dsh-whale-tank
# 卸载
dsh plugin --profile web remove @swell05/dsh-whale-tank
装完重启 web（bundle 层栈在 boot 合成）。
在 dsh 里使用
装好重启后，在 dsh web 的空工作区对话里输入 skill 触发：
- 初始化插件项目 —— 输入
/whale-tank-init：告诉它插件的主要功能，它会逐步确认细节后，在目标目录搭好沙盒 + 骨架 +（可选）知识包，写盘前 ask_user 确认，不覆盖已有内容；
- 体检第三方插件 —— 输入
/whale-tank-vet：把想检查的 npm 包名丢给它，三阶段体检自动走完，结论落在.vetting/（vet-report.md人读 +vet-result.json机器读）。
🧾 完整命令表（.wttools 工作区工具）
init 后项目内有 .wttools/，是插件开发可用的工具包，在项目文件夹里直接敲命令调用（Windows 用 .wttools\，Unix 用 ./.wttools/）。.wttools 是自包含工具（零依赖单文件），插件卸载后仍可用。
| 命令 | 作用 |
|---|---|
.wttools\status |
沙盒状态体检（插拔是否 dirty、知识包是否过时） |
.wttools\deps |
双通道装依赖（插件 → 沙盒 profile；普通库 → 项目 package.json） |
.wttools\plug |
把项目插件接入沙盒 profile（快照 → 构建 → 注入 → 冒烟） |
.wttools\unplug |
取出并对账（diff=0 → clean） |
.wttools\plug-test |
一发插拔复原合成测试（日常开发主循环） |
.wttools\run-test |
挂载 + 前台实跑开发中的插件，Ctrl+C 结束自动复原 |
.wttools\restore |
回拷最近快照复原（--full 走 reset） |
.wttools\reset |
删除 .sandbox/ 整体重建（删除前 ask_user） |
.wttools\upgrade-knowledge |
升级沙盒里的知识包（幂等） |
status
沙盒状态体检，无参数。
.wttools\status
输出：项目名/类型、版本模式（local/standalone）、声明与实际 dsh 版本、漂移与混合版本告警、profile、plugState（clean/plugged/dirty）、知识包锚定版本与当前模板（过时提示）。dirty 时附快照 diff 明细。退出码：clean=0，否则 1。
deps
双通道依赖安装。插件依赖 → 沙盒 profile（对账进 bundles）；普通 npm 库 → 项目 package.json + npm install。
| 参数 | 作用 |
|---|---|
--add <包名> |
直接给包名（可带 @版本，如 @deepseek-ai/dsh-client-runtime、lodash@^4）；智能抽取包名+版本并按包名判定通道（无 LLM） |
--pkg <包名> |
显式包名（配合 --channel 用） |
--channel plugin|npm |
显式指定通道 |
--version <版本> |
指定版本；npm 通道默认 *，plugin 通道默认 = 沙盒运行时 dsh 版本 |
--section <dependencies|devDependencies|peerDependencies> |
npm 通道写入 package.json 的区段（默认 dependencies） |
--remove |
移除而不是添加 |
--yes |
跳过确认 |
.wttools\deps --add @deepseek-ai/dsh-tools # 包名含 dsh → plugin 通道
.wttools\deps --add lodash@^4 # 普通库 → npm 通道
.wttools\deps --pkg @deepseek-ai/dsh-tools --channel plugin
.wttools\deps --pkg lodash --channel npm --section devDependencies
通道判定规则（纯字符串，无语义解析）：包名含 @deepseek-ai/、dsh- 前缀或含 dsh → plugin；否则 → npm。plugin 通道强制版本一致性（铁律 6：≠ 沙盒运行时版本直接拒绝），装后 dump-config 冒烟。
plug
把项目插件接入沙盒 profile。前置 plugState 必须 clean。
| 参数 | 作用 |
|---|---|
--no-build |
跳过 npm run build（默认会先构建） |
流程：快照（插前基线）→ 构建 → dsh plugin add file:<项目> + 客户端 insert → 分型冒烟（host/both 走 dump-config+boot，client 走 web boot + client bundle 断言）。成功后 plugState → plugged。
unplug
取出插件并对账，无参数。
.wttools\unplug
流程：dsh plugin remove → 快照 diff（对比插前基线）。diff=0 → clean（exit 0）；diff≠0 → dirty + 残留清单（exit 1）。
plug-test
一发插拔复原合成测试（日常开发主循环）。
| 参数 | 作用 |
|---|---|
--no-build |
跳过构建 |
--no-restore |
diff≠0 时保留现场不自动复原（仍判失败） |
流程：plug → 冒烟 → unplug → diff。diff=0 → 报告各阶段 + exit 0；diff≠0 → 残留清单完整进报告 → 自动 restore（现场备份在快照目录，证据不丢）→ 终态 clean + exit 1。
run-test
挂载 + 前台实跑开发中的插件——把项目插件注入沙盒指定 profile 并真实启动，Ctrl+C 结束自动复原。
| 参数 | 作用 |
|---|---|
--profile <名> |
目标 profile（沙盒内任意 profile，如 web/headless；默认 web） |
--port <n> |
web 端口覆盖（默认 13080；其他 profile 尊重自身配置） |
--no-build |
跳过 npm run build |
.wttools\run-test # 默认 web:13080，打开浏览器实跑
.wttools\run-test --profile headless # 跑 headless profile
.wttools\run-test --port 8080
流程：构建 → 注入（dsh plugin add file:，全程显式沙盒 DSH_HOME + profile 路径断言，不会逃逸到真实 ~/.dsh）→ 前台 boot → Ctrl+C → remove + diff 复原（diff≠0 证据落袋 + 自动复原该 profile）。
⚠️ run-test 内部会先
npm run build——新骨架先npm install再跑，否则报tsc不存在。
restore
两级复原。
| 参数 | 作用 |
|---|---|
--full |
走 reset：删除 .sandbox/ 整体重建 |
--yes |
跳过删除确认 |
不带 --full：回拷最近快照的 profile 文件 → 重建 node_modules → 清沙盒 sessions → 重写 state（clean）→ 冒烟确认。
reset
独立 verb：删除 .sandbox/ 整体重建沙盒，删除前 ask_user（--yes 跳过）。适合沙盒彻底坏掉时用。
upgrade-knowledge
把插件内置的更新版知识包按 merge-spec 增量合并进项目（幂等，绝不覆盖用户内容），无参数。
.wttools\upgrade-knowledge
新版本块追加、旧版本块保留（两版并存待人工清理）、冲突只告警不自动动手。
🌐 Skills & Tools（仅测试过dsh web模式）
| Skill | 作用 |
|---|---|
/whale-tank-init |
初始化项目：已有 .sandbox/state.json → 升级知识包；空目录 → init；非空未初始化 → 拒绝 |
/whale-tank-vet |
第三方插件体检，三阶段走完 |
工具是惰性注册的：skill 触发的那一轮才进作用域，随会话结束注销，其余时间零上下文注入——不打扰，无残留。
实机疑难排查
.wttools命令不在 PATH 也没关系：.wttools是自包含工具（零依赖单文件），在项目文件夹里直接敲.wttools\status等即可，不需要全局安装。- 骨架生成后 build 报 tsc 不存在：脚手架不含依赖，先
npm install（或.wttools\deps）再npm run build。
📄 License
MIT © 2026 swell05
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…