🐋 深海鱼篓

dsh-whale-catch · 让本场会话的交付物自己游进篮子

自动收集 · 一处预览 · 就地看差异 · 搜索排序 · 一键打包 / 归档

🚀 快速开始 · ✨ 功能地图 · ⚙️ 配置 · 🛡️ 安全模型 · English

_{🧪 0.3.2 面板静态预览：用 lib/client.js 里真实的面板组件 + 示例数据渲染，不是 DSH 实机截图。排序框、预览入口、行内差异都在图里；实际配色跟随你的主题。}

给 DeepSeek Harness（DSH）的右侧栏插件：把一场会话里产出或改动过的文件汇总到「鱼篓」里，支持预览、行内差异、搜索、按轮分组、打包 zip、归档与复制清单。

🧭 目录

• 🐋 为什么需要它
• ✨ 功能地图
• 🚀 30 秒上手
• 🖥️ 界面与交互
• 🧠 零登记是怎么做到的
• ⚙️ 配置
• 🛡️ 安全模型
• 📊 兼容性与已知限制
• 🛠️ 开发与测试
• 🗺️ 路线图
• 🤝 参与与致谢

🐋 为什么需要它

在 DSH 里连续干上几轮活之后，「文件到底产出到哪了」几乎是日常问题：

• 🪟 内核的产出物卡片只在当前这一轮出现，往下翻几屏就散了；
• 🐚 在 bash 里跑 python build_doc.py、npm run build 写出来的 docx / pdf / zip，既不算「文件工具改动」，也没调 present，两套机制都不认；
• 📦 攒了十几个交付物想一次发给别人，只能回目录里翻，还要担心漏掉；
• 🔍 改过的文件想看看「改了多少、改了什么」，得切回 git 或翻历史。

鱼篓只做三件事：自动收、一处看、一键打包 / 归档。改过的文件还能就地展开 unified diff，搜索、按轮分组、复制 Markdown 清单也都在同一个侧栏里完成。

💡 一句话： 不改变你的工作流，只给「这一场会话到底产出了什么」一个常驻的答案。

🆚 和内核产出物的区别

这不是重复造轮子——内核的 deliverables/presented 与 workspace/changes 鱼篓照单全收，只是把它们覆盖不到的场景补上：

✨ 功能地图

🎁 0.3.2 亮点

• 🪟 预览不再开新窗口：Desktop 的 Electron 主进程会 deny 所有 window.open（只放行 https: 外链），之前「点预览没反应」就是这个原因。现在统一交给 DSH Document Preview：图片 / PDF / Markdown / 文本 / 源码 / Office 都在右侧栏打开。
• 📍 只保留一个「预览」入口；cwd 外文件明确提示「复制路径或归档」，不再假装能打开。
• 🖼️ 预览图按 0.3.2 面板重新渲染（排序 + 预览入口 + 行内差异）。

🎁 0.3.1 亮点

• 🔎 未知后缀也能读：/file 对 .patch、.bak 这类文件先嗅探前 8 KiB，是文本就按 text/plain 返回，不再一律触发下载。

🎁 0.3.0 亮点

• 📄 Office 文档交给 Document Preview：docx / xlsx / pptx 由 DSH 的预览按 PDF 渲染，转换交给内核 officeToPdf；0.3.2 起与其他文件统一成一个「预览」入口。
• ↕️ 排序：最近修改 / 名称 / 体积 / 类型，四档切换；已删除文件永远沉底。
• 🪟 分批渲染：先铺 200 行，点「显示更多」再追加——800 条也不会一次全渲染。
• 🧹 归档保留策略（可选）：archiveKeep: 2 时每次归档写进独立批次目录，只保留最近 2 批；默认 0 保持旧布局，行为不变。

🎁 0.2.2 亮点

• 🛑 面板轮询不再扫盘：5 秒轮询只读缓存，首次打开、turn/end、手动刷新才扫描。
• 🌊 zip 流式写入：逐文件读取、异步压缩、边压边发，不再把整包攒进内存。
• 🎯 Range / ETag：PDF、大文件预览可拖动进度，不用重拉整份。
• 🛡️ Host 白名单：堵住 DNS rebinding 下「Origin 与 Host 同时是攻击者域名」的绕过。
• 🧹 归档安全：拒绝 archiveDir == cwd，realpath 挡住符号链接穿越，失败进 failed。
• 🔎 面板搜索：按名称 / 路径 / 描述过滤，和分类 chip 一起生效。

🚀 30 秒上手

环境要求

• DSH >= 0.2.0-rc.2
• Node ^22.19 || >=24（Desktop 自带运行时已满足）
• 无需构建、无需额外服务、无需配置数据库

1. 安装

Desktop 用户走应用内：设置 → 插件 → 安装，粘贴下面任一标识（desktop profile 由 Electron 独占，命令行 dsh plugin --profile desktop add 会被拒绝）：

github:Rosynb666/dsh-whale-catch     # GitHub 最新 main
dsh-whale-catch@0.3.2                # npm 指定版本

非 Desktop 的自建 profile 才用 CLI：

dsh plugin --profile <profile> add github:Rosynb666/dsh-whale-catch
dsh plugin --profile <profile> add dsh-whale-catch@0.3.2

2. 打开面板

刷新页面（⌘R / Ctrl+R），右侧栏点 +，在引导页里选 「打开深海鱼篓」；也可以直接点侧栏里的 🐋 图标。

3. 开始干活

让 agent 随便做点产出，或手动点一次「刷新」，文件就会出现在鱼篓里。勾选文件 → 「打包 zip」或「归档」。

卸载

Desktop：设置 → 插件 → 卸载。非 Desktop profile：

dsh plugin --profile <profile> remove dsh-whale-catch

🖥️ 界面与交互

窄栏布局，下面是一张示意（实际宽度随侧栏变化）：

┌──────────────────────────────────────────────┐
│ 🐋 鱼篓              12 条鱼 · 3.4 MB  [刷新] │
│ [全部 12] [📄 文档 7] [📊 表格 3] [🖼 图片 2] │
│ [🔎 搜索文件名、路径或描述…                  ] │
├──────────────────────────────────────────────┤
│ ☑ 📄 项目周报.docx                   +12 −3  │
│    第三季度周报 · 周报.docx    [预览] [差异] ⧉ │
│    1.2 MB · 3 分钟前 · 交付 · 改动            │
│ ☐ 📊 预算表-2026.xlsx                         │
│    plan.xlsx · 88 KB · 12 分钟前              │
│ ☐ 🖼 产品手册.pdf                             │
│    ...                                        │
├──────────────────────────────────────────────┤
│ 已选 2 项                    [归档] [打包 zip] │
│ 扫描于 刚刚                                   │
└──────────────────────────────────────────────┘

🎛️ 控件速查

📦 打包后的 zip 长这样

季度交付.zip
├── 项目周报.docx
├── assets/
│   └── chart.png
├── _external/
│   └── 外部交付.pdf
└── _whale-catch/
    ├── manifest.json       # 机器可读：会话、包内路径、体积、轮次、sha256…
    └── 交付清单.md          # 人可读：Markdown 表格

🗂️ 归档后的目录长这样

$DSH_HOME/whale-catch/archive/
└── <session-id>/
    ├── 项目周报.docx
    ├── assets/chart.png
    └── _external/外部交付.pdf

开启 archiveKeep 后，每次归档进独立批次，旧批次自动清理：

$DSH_HOME/whale-catch/archive/
└── <session-id>/
    └── runs/
        ├── 20261030-153012-120/
        │   └── 项目周报.docx
        └── 20261030-160145-004/   # 只保留最近 N 批
            └── 项目周报.docx

🧠 零登记是怎么做到的

鱼篓不要求 agent 调工具登记文件。它把三条来源按绝对路径合并：

session/event
 ├─ deliverables/presented ──────────────┐
 ├─ workspace/changes ───────────────────┤
 └─ turn/end ──► scan cwd ───────────────┤
                                        ▼
                             Basket（按绝对路径合并）
                                        │
                         GET /basket ───┴──► 右侧栏面板

🧭 扫描边界

• 只在当前会话 cwd 内，不越界、不跟符号链接；
• 跳过 node_modules / .git 等默认目录；
• 跳过点开头的文件与目录（.env、.gitignore 不会自动进筐；需要交付请用 present）；
• maxDepth（默认 6）、maxFiles（默认 800）、maxFileBytes（默认 64 MB）、访问目录项上限 20000；
• 超限会标记 truncated，面板会提示「目录太大」。

⏱️ 什么时候扫描

会话表按 LRU 保留最近 40 个会话；快照里的文件 stat 用 16 路并发限流。

⚙️ 配置

配置写在你自己的 profile 补丁层里，不要改包里的 cordis.patch.yml（升级会被覆盖）：

# ~/.dsh/profiles/desktop/cordis.patch.yml
- id: dsh-whale-catch
  config:
    archiveDir: ~/Documents/鱼篓归档   # 归档目录；默认 $DSH_HOME/whale-catch/archive
    ignore: [dist, build, .venv]        # 额外忽略的目录名
    maxFiles: 800                       # 最多收录多少个文件
    maxDepth: 6                         # 目录遍历深度
    maxFileBytes: 67108864              # 单文件上限 64 MB
    maxZipBytes: 536870912              # 打包总量上限 512 MB
    maxBodyBytes: 1048576               # 请求体上限 1 MB
    archiveKeep: 0                      # 归档保留批次数；0 = 不启用批次目录与清理
    lookbackMinutes: 720                # 拿不到会话创建时间时往回看 12 小时
    allowHosts: []                      # 额外放行的 Host 名；默认只认 localhost / IP 字面量

改完热重载即生效，无需重启。

🛡️ 安全模型

接口跑在本机 loopback 上，所以按「浏览器里的第三方页面会来打本机接口」来设防，而不是「本机其它进程」（它们本来就能读你的文件）。

隐私提示

• zip 的 _whale-catch/manifest.json 与 交付清单.md 会记录 cwd（用户主目录前缀脱敏为 ~）、会话 id 与 sha256；分享前留意。
• 扫描有意跳过点文件，避免把 .env、.gitignore 自动收进筐。
• 安全问题请走私密渠道：SECURITY.md。

📊 兼容性与已知限制

✅ 兼容性

⚠️ 已知限制

❓ 常见问题

npm pack --dry-run --cache="$(mktemp -d)"

🛠️ 开发与测试

npm install
npm test        # 68 项：扫描 / 合并 / 改动元数据 / 流式 zip / Range / HTTP 栅栏 / 差异裁剪 / 原生地址 / 归档保留 / 插件装载
npm run check   # 契约自检：包结构、patch、client.inject、locale meta、icon、依赖纪律
npm run verify  # check + test

没有构建步骤：lib/index.js 是 Host 半边，lib/client.js 是原样交给 __ModuleLoader__ 的浏览器半边，改完直接重装即可。

依赖纪律：运行时依赖只有 @deepseek-ai/schemastery（纯校验库）。它必须是 dependencies 而不是 peer——profile 的 pnpm 配置是 autoInstallPeers: false，放 peer 在干净 profile 里根本装不上，Host 半边会在加载时直接失败。

dsh-whale-catch/
├── lib/
│   ├── index.js      # 插件入口：会话事件 → 鱼篓登记表，注册 HTTP 路由
│   ├── basket.js     # 三来源合并、改动元数据、快照、路径准入（白名单）
│   ├── scan.js       # 带边界的工作区扫描
│   ├── zip.js        # 零依赖 ZIP 写入器（流式 STORE + DEFLATE）
│   ├── routes.js     # HTTP 接口：预览 / 差异 / zip / archive
│   ├── http.js       # 同源 + Host 栅栏、JSON 收发、MIME、Range
│   └── client.js     # 右侧栏 tab + 面板（纯 JS，零构建）
├── locale/           # 市场与设置页展示用的元数据
├── test/             # node:test，无测试框架依赖
├── scripts/          # 契约自检
└── docs/             # 架构、发布清单、开发手册

• 🏗️ 架构与不变量：docs/architecture.md
• 🚢 发布清单：docs/publish.md
• 🤝 参与开发：CONTRIBUTING.md
• 🛡️ 安全报告：SECURITY.md

🗺️ 路线图

• 🌉 跨会话视图：把所有会话的产物汇总成一个总台账。
• 💾 持久化 present 描述与轮次，Host 重启后仍可读。
• 🧹 归档清理的 dry-run，以及按日期 / 按项目的整理视图（archiveKeep 已支持按批保留）。
• ⚡ 大列表真正的窗口化（当前是 200 行分批 + 「显示更多」）。
• 🧪 客户端 Panel 的真实渲染测试、tsc --checkJs / lint。

🤝 参与与致谢

• 有 bug / 需求：走 Issue 模板。
• 想改代码：先看 CONTRIBUTING.md。
• 安全问题：不要公开提 issue，走 SECURITY.md。

感谢每一位愿意把「文件生成完就找不到」这个痛点讲出来的人，也感谢 DSH 社区里那些把插件边界踩清楚的前辈。

🐋 深海鱼篓 用爱、米饭和一点点强迫症维护。 如果它帮你省下过一次翻目录的时间，点个 ⭐ 就是最好的投喂。

📄 许可

MIT © Rosynb666