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/             # 图产物（.png 等，可配 .data.tsv 原始绘图数据）
└─ .git/                # 项目自动 git（每次 cell 跑完/反馈 自动本地 commit，不 push）

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。
• 非图的中间产物（tsv/csv/bed 等）通过 outputs 显式声明。
• 脚本要自包含：显式读输入、写输出；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" } ]
}

• 每个 artifact 的 outputHash 与每个 inputHashes 都是 SHA-256，保证可复现性证据。
• feedback 挂在 artifact 上；derivedFrom 记录版本派生关系（v1 → v2）。

4. 出图 → 反馈 → 重画循环

1. 出图：调用 bio_run_cell（含 title + code + params + seed + inputs）。
2. 视觉自检（Tier 0，默认）：程序化检查——渲染是否成功（exit code）、是否有图产出、dpi/尺寸合理性。人（用户）是默认的眼睛：图永远先给用户看。
3. 反馈：用户对图提出反馈（"改 x 轴 / 换配色 / 加 p 值"），用 bio_add_feedback 把反馈作为结构化记录挂到对应 artifact 上（进 manifest + git commit）。
4. 重画：调用 bio_rerun_cell（cellId + editedCode），生成版本化新 cell（cell_0001_v2），重跑、重新发现图、登记新 artifact 并记录 derivedFrom 派生关系。