bio-workbench

生信分析工作台约定（dsh-science-workbench）

这是 agent 在执行生信分析时必须遵守的约定。核心原则：每个产物都可溯源、可重放——回答"这张图 = 哪段代码 + 哪些输入 + 什么环境 + 什么参数/种子"，并能重跑。

1. 项目布局

每个分析项目是一个目录，结构固定：

<workspace>/bio-projects/<name>/
├─ manifest.json        # 唯一事实来源（账本）：cells + artifacts + provenance + 反馈
├─ environment.lock     # 环境快照（interpreter 版本 + pip freeze）
├─ code/                # 每个 cell 一个自包含脚本 cell_0001.py / cell_0001_v2.py ...
├─ data/                # 输入数据（引用或副本）
├─ figures/             # 只放图：.svg / .pdf / .tiff / .png
├─ results/             # 非图产物：tsv/csv/bed/npz + source data
└─ .git/                # 项目自动 git（每次 cell 跑完/反馈 自动本地 commit，不 push）

项目里不保留 QA 产物。 审计（alignment / collision）必须照跑，但它们的产物是 scratch： alignment overlay 是测量示意图（每个可比面板一个矩形 + PASS 页脚），collision overlay 标的是 可疑的文字/描边碰撞。两者都不是图，摆在项目里就是污染分析结果，还会招来误解点击。 一律写到项目外的临时目录，例如：

import os, tempfile
QADIR = os.path.join(tempfile.gettempdir(), 'nature-figure-qa',
                     os.path.basename(os.path.abspath('.')))   # cwd = 项目根
os.makedirs(QADIR, exist_ok=True)
print(f'QA scratch dir (outside the project): {QADIR}')

并且绝不把 QA 文件写进 outputs 声明。踩过的坑：collision 审计在 0 冲突时不写 overlay PDF， 但 outputs 里仍列着那个路径，于是账本里留下一条文件不存在的幽灵 artifact，在 UI 里点开就是空的。

2. cell 契约（脚本头声明块）

每个 cell 脚本顶部有一段由工具生成的声明头，声明即契约：

# @cell: cell_0001
# @title: TSS profile
# @language: python
# @seed: 42
# @params: {"bin": 50, "upstream": 3000}
# @inputs: ["data/peaks.bed"]
# @outputs: ["figures/tss_profile.png"]

规则：

• 图必须写到 figures/ 下（相对项目根路径），这样运行后能自动被发现并登记 provenance。
• 审计产物写到项目外的临时目录，绝不写进项目（见 §1）。figures/ 被自动扫描并在 UI 里当图展示；alignment overlay 每面板一个矩形 + PASS 页脚，放进去会被误认成坏图。
• QA 路径不要出现在 outputs 里，否则会留下文件不存在的幽灵 artifact。
• 非图的中间产物（tsv/csv/bed 等）通过 outputs 显式声明，放 results/。
• 脚本要自包含：显式读输入、写输出；cwd = 项目根；用相对路径。

3. manifest 记账（唯一事实来源）

{
  "schemaVersion": 1,
  "name": "...", "root": "...",
  "environment": {"language": "python", "interpreter": "3.12.x", "lockFile": "environment.lock"},
  "cells": [ { "id", "title", "script", "language", "params", "seed", "inputs",
               "status": "ok|error", "artifacts": [], "ranAt", "stdoutTail", "stderrTail", "derivedFrom" } ],
  "artifacts": [ { "path", "kind": "figure|data|file", "producedBy", "inputHashes",
                   "outputHash", "params", "seed", "env", "createdAt", "feedback": [], "derivedFrom" } ]
}