🐋 @swell05/dsh-whale-tank —— 一个小巧的鲸鱼缸

中文 · <a href="README_EN.md">English</a>

> 鲸鱼缸，为你提供两个功能： > > 🛠️ ① 造一个干净的插件开发专属“鱼缸” > > 🩺 ② 把拿不准的插件丢进单独的“鱼缸”做个体检 > > 不动你真实的 ~/.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 会走三阶段：

1. 静态危害检查：npm pack 拉发布产物 → 规则引擎扫 install 脚本、凭据读取与流向、外联、eval/混淆——凭据按 source→sink 判级：读到 API key 是信号（正常 LLM 插件读 key 调已知服务商属预期、放行），凭据流向非服务商（硬编码/动态出口）才判高危；命中高危直接"不建议"，直接不执行； 2. 受限动态验证：复刻 profile → 两层冲突检测 → 插拔抵消（diff=0 才算干净），全程默认不执行不可信代码； 3. 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 触发：

1. 初始化插件项目 —— 输入 /whale-tank-init：告诉它插件的主要功能，它会逐步确认细节后，在目标目录搭好沙盒 + 骨架 +（可选）知识包，写盘前 ask_user 确认，不覆盖已有内容；

2. 体检第三方插件 —— 输入 /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。

dsh-whale-tank

Install

Check the source files

🐋 @swell05/dsh-whale-tank —— 一个小巧的鲸鱼缸

🛠️ 创建插件开发沙盒

🩺 插件在线体检

🚀 快速开始

安装 / 卸载

在 dsh 里使用

🧾 完整命令表（`.wttools` 工作区工具）

`status`

`deps`

`plug`

`unplug`

`plug-test`

`run-test`

`restore`

`reset`

`upgrade-knowledge`

🌐 Skills & Tools（仅测试过dsh web模式）

实机疑难排查

📄 License

Source facts

Install

Check the source files

🐋 @swell05/dsh-whale-tank —— 一个小巧的鲸鱼缸

🛠️ 创建插件开发沙盒

🩺 插件在线体检

🚀 快速开始

安装 / 卸载

在 dsh 里使用

🧾 完整命令表（.wttools 工作区工具）

status

deps

plug

unplug

plug-test

run-test

restore

reset

upgrade-knowledge

🌐 Skills & Tools（仅测试过dsh web模式）

实机疑难排查

📄 License

More related plugins

dsh-base

dsh-headless

mirage#dsh

🧾 完整命令表（`.wttools` 工作区工具）

`status`

`deps`

`plug`

`unplug`

`plug-test`

`run-test`

`restore`

`reset`

`upgrade-knowledge`