dsh-science-workbench

dsh plugin --profile web add dsh-science-workbench

dsh-science-workbench

[English](README.md) | 中文




面向 DeepSeek Harness 的可复现科学工作台插件，融合三种范式的长处：

• Jupyter —— 可看、可重跑的 cell 与内联图；
• Claude Science —— agent 作为执行引擎；
• Nextflow / nf-core —— 每个产物都带完整 provenance。

核心承诺：每张图、每个产物都可溯源、可重放。你永远能回答 “它 = 哪段代码 + 哪些输入 + 什么环境 + 什么参数/种子”，并一键重跑。

---

✨ 能力

• 代码出图 → 反馈 → 重画 —— agent 跑自包含 cell 出图、图内联显示；你给图挂结构化反馈，bio_rerun_cell 生成派生版本（v1 → v2 → v3）。
• 每项目一个账本 —— 明文 manifest.json 是唯一事实来源：cells、artifacts、provenance 与反馈历史。
• 天生可复现 —— 自包含脚本、每 cell 全新子进程、environment.lock、SHA-256 输入/输出哈希、固定 seed。
• 自动 git 版本化 —— 每个项目创建时 git init，每一步自动本地 commit（不 push）。
• 跨平台 —— Host shell 层 macOS/Linux 用 bash、Windows 用 PowerShell；Python 在 Windows 用 python、POSIX 用 python3。

🛠 工具

9 个 agent 工具 + 一个浏览器工作台：

工具 · 作用

bio_init_project · 建/开项目：code/ data/ figures/ + manifest.json + environment.lock + git init。

bio_run_cell · 跑一个自包含 cell，发现图、登记产物哈希、提交。

bio_rerun_cell · 用改过的代码重跑 cell，生成派生版本（记录 lineage）。

bio_add_feedback · 给产物挂结构化反馈（“重画它”这条备注就这样变成历史）。

bio_get_project · 返回项目摘要：cells、artifacts、provenance 与反馈。

bio_list_projects · 列出 projects 根目录下的所有项目。

bio_set_projects_dir · 设置项目存储根目录（跨重启持久化）。

bio_delete_cell · 删除一个 cell 及其产物（脚本 + 图）。

bio_mark_cell · 标记 cell 为「成品」，或取消标记 —— 工作台与索引中会显示成品徽标。

「分析工作台」 标签页用三栏 UI 展示 notebook、产物、溯源与反馈，支持内联图预览（PNG/JPEG/SVG/PDF/TIFF/BMP）、可检索项目选择器（按名称过滤 + 最近活动日期排序）、cell 检索框、系统原生目录选择器（设置项目根目录）与成品标记徽标。超大图（数 MB～数十 MB）按需加载也能完整显示。

插件还内置两个出版级出图 skill（改编自 Claude Science，Apache-2.0）：figure-style（图形正确性与易读性规则 + apply_figure_style()）与 figure-composer（多面板组合图 + 对抗式自审循环）。见 skills/ 与 [ATTRIBUTIONS.md](./ATTRIBUTIONS.md)。

📸 功能展示

反馈 → 重画回路 —— 每张图保留结构化反馈历史，一键「让 agent 重画」生成派生版本。

工作台标签页 —— 三栏布局：左侧「分析步骤」列表（含状态与派生链路 cell_0001 → cell_0001_v2 → cell_0001_v3），右侧「产物详情」（内联图 + 溯源/代码标签 + 脚本/删除/Finder 操作）。

「代码」标签 —— 每个产物的生成脚本带声明头（cell / title / language / seed / params / inputs），可随时查看与复用。

「溯源」标签 —— 完整 provenance：产出 cell、输出 SHA-256 哈希、参数、seed、派生自、创建时间。

📦 安装

dsh-science-workbench 是一个 DSH 双面包（Host + Client）。用标准 dsh plugin 命令安装 —— 它是对 pnpm 的薄封装，把包装进 profile 并自动加进 dsh.profile.bundles（因为本包声明了 dsh.bundle.patch）。

# 从 npm（已发布）：
dsh plugin --profile web add dsh-science-workbench

# 本地开发（从源码目录）：
dsh plugin --profile web add file:/path/to/dsh-science-workbench

然后重启 dsh web。bio_* 工具全局可用、工作台标签页出现、插件在 设置 → 插件 里可见。

DSH 桌面版

桌面版使用自己的 desktop profile，dsh 命令行拒绝写入它（profile "desktop" is managed exclusively by the Electron application）。请在界面内安装：

1. 侧边栏打开 Plugins。

2. Add plugin → 粘贴包名（dsh-science-workbench）或本地源码目录的绝对路径（/path/to/dsh-science-workbench）→ Install → Enable now。

3. 重启桌面版让 Host 半边加载（模块热重载按设计忽略 node_modules，所以运行期间不会热加载用 link: 装的源码目录）。

项目可以放在会话工作区之外 —— 用 bio_set_projects_dir 指到你自己的根目录（例如 ~/bio-projects），文件写入不受会话工作区沙箱限制。

🚀 快速上手

装好并重启后，直接用大白话让 agent 干活：

“帮我用 demo_tss 项目画一个 TSS 附近的信号热图。”

agent 会替你驱动工具。等价的手动流程是：

1. bio_init_project { name: "demo_tss" }
2. bio_run_cell { title: "TSS profile", code: "..." }   # 写 figures/*.png
3. 看内联图 → bio_add_feedback { artifactPath, text: "把配色改成 Blues" }
4. bio_rerun_cell { cellId: "cell_0001", editedCode: "..." }  # → cell_0001_v2 + 新图

每一步都提交进项目的 git 历史、记进 manifest.json，整条 lineage（cell_0001 → cell_0001_v2 → …）随时可查。

🧪 可复现模型

每个 cell 是一个自包含脚本，带声明头：

# @cell: cell_0001
# @title: TSS profile
# @language: python
# @seed: 42
# @params: {"colorMap": "Blues"}
# @inputs: ["data/peaks.bed"]
# @outputs: []

它在全新子进程里跑，cwd = 项目根目录。完成后 Host 会：

1. 发现写到 figures/ 的图，并加 cell id 前缀；

2. 把每个输入/输出做 SHA-256 哈希，记进产物记录；

3. 把 cell + artifacts 追加进 manifest.json、更新 index.md；

4. 全部提交到项目的本地 git 仓库。

📁 项目布局

<workspace>/bio-projects/<name>/
├─ manifest.json        # 唯一事实来源：cells + artifacts + provenance + 反馈
├─ environment.lock     # 解释器版本 + pip freeze 快照
├─ index.md             # 人类可读的项目索引
├─ code/                # 每个 cell 一个自包含脚本（cell_0001.py, cell_0001_v2.py, …）
├─ data/                # 输入数据
├─ figures/             # 图（带 cell 前缀，如 cell_0001_tss_profile.png）
└─ .git/                # 自动创建、自动提交

🧩 架构

• Host（lib/index.js）是唯一事实来源。它把 bio_ 工具注册进宿主 tools 注册表、负责所有执行与溯源，并通过 webServer 服务 /biowb/ 数据路由。
• Client（lib/client.js）是纯投影 —— 手写的浏览器 bundle，经同源 fetch('/biowb/<method>') 读写。不依赖 typert Remote 桥、不需要 Harness monorepo 构建。
• 约定 skill（skills/bio-workbench）教 agent 项目布局、cell 契约与反馈回路。

🌍 跨平台

操作 · macOS / Linux · Windows

Shell · bash · PowerShell

哈希 · shasum -a 256 · Get-FileHash

建目录 / 移动 / 删除 · mkdir -p / mv / rm -f · New-Item / Move-Item / Remove-Item

文件管理器打开 · open / open -R · explorer.exe / explorer.exe /select,

Python · python3 · python

🔧 开发

git clone https://github.com/poplarity/dsh-science-workbench
cd dsh-science-workbench

# 语法检查
npm run lint

# 装进你的 profile 并重启
dsh plugin --profile web add file:$(pwd)

结构：lib/index.js（Host）· lib/client.js（Client bundle）· index.js（入口再导出）· cordis.patch.yml（bundle 补丁）· skills/（约定 skill）· docs/（设计文档）· examples/（示例项目）。

License

[MIT](./LICENSE)