7.4 KiB
Executable File
7.4 KiB
Executable File
TBtools 式轻量扩展插件方案
1. 目标
本文档定义 bbav5 中“扩展分析阶段”的减法版本：先按 TBtools 插件式能力接入，而不是立即建设为完整核心分析阶段。
目标是把用户已经跑通的代码包装成一个轻量插件，使其具备：
- 可通过统一入口运行；
- 可保留用户跑通时的默认参数；
- 可允许用户修改少量开放参数；
- 可收集输出结果；
- 可记录运行命令、参数、日志和状态。
该方案优先解决“能稳定复用用户代码”的问题，暂不追求完整的 Agent 自动规划、复杂依赖推理和下游自动消费。
2. 与正式阶段的边界
轻量扩展插件不是 identify、motif、domain、expression 这类完整正式阶段。
它暂时不要求：
- 新增完整 stage contract；
- 接入 PlanningAgentV2 自动规划；
- 参与核心阶段依赖推理；
- 声明复杂 consumes/provides 类型系统；
- 被下游阶段自动识别和消费；
- 为每个插件开发专用前端结果组件；
- 接入复杂 diagnosis 自动修复；
- 接受完整 publication-grade 方法学审查。
轻量插件只要求做到：
用户跑通代码
-> 标准插件入口
-> 参数可配置
-> 输出可收集
-> 日志可查看
-> manifest 可追踪
如果后续某个插件稳定、常用，且结果需要参与下游流程，再升级为正式 bbav5 stage。
3. 最小插件结构
推荐目录结构：
plugins/<plugin_id>/
config.yaml
run.py
README.md
examples/
其中：
config.yaml描述插件元信息、运行环境、默认参数和输出目录；run.py是标准 CLI wrapper，负责调用用户原始分析代码；README.md说明插件用途、输入、输出和示例命令；examples/可保存最小示例输入或参数模板。
4. config.yaml 最小规范
轻量插件的配置只保留必要字段。
plugin:
id: custom_xxx
name: Custom XXX Analysis
version: 1.0.0
description: 用户自定义分析插件
runtime:
conda_env: test4py311
entry:
command: python plugins/custom_xxx/run.py
parameters:
evalue:
type: float
default: 1e-5
editable: true
description: 序列搜索显著性阈值
threads:
type: integer
default: 8
editable: true
description: 运行线程数
outputs:
directory: results/custom_xxx
字段要求：
plugin.id必须唯一；runtime.conda_env使用已有 conda 环境，优先test4py311、rnaseq、rnaR；entry.command指向插件入口；parameters.*.default使用用户原始跑通参数；parameters.*.editable只对用户需要修改的参数设为true；outputs.directory是插件输出收集目录。
5. 参数减法原则
参数不需要一次性全部暴露。
只开放三类参数：
- 用户明确希望修改的参数；
- 对结果有明显影响的核心参数；
- 运行资源参数，例如
threads、cpu、memory。
暂不开放：
- 内部临时文件名；
- 中间目录；
- 不建议普通用户调整的调试参数；
- 只为兼容原始代码存在的变量；
- 修改后容易破坏流程的隐藏参数。
默认值必须来自用户已经跑通的版本。用户不修改参数时，插件应尽量复现原始运行结果。
6. run.py 最小职责
run.py 不需要重写用户分析逻辑，只做适配层。
最小职责：
- 解析 CLI 参数；
- 检查必要输入是否存在；
- 创建输出目录；
- 调用用户原始代码或核心函数；
- 收集结果文件；
- 写运行日志；
- 写 manifest；
- 失败时返回非零 exit code。
推荐命令形式：
python plugins/custom_xxx/run.py \
--workspace workspace/<job_id> \
--input input.fa \
--output results/custom_xxx \
--evalue 1e-5 \
--threads 8
7. manifest 最小规范
轻量插件不使用完整 stage manifest，先使用 plugin manifest。
{
"manifest_version": "1.0",
"plugin_id": "custom_xxx",
"status": "success",
"parameters": {
"evalue": 1e-5,
"threads": 8
},
"command": "python plugins/custom_xxx/run.py --input input.fa --evalue 1e-5 --threads 8",
"outputs": [
"results/custom_xxx/result.tsv",
"results/custom_xxx/plot.pdf"
],
"logs": [
"results/custom_xxx/run.log"
],
"started_at": "2026-06-10T10:00:00",
"finished_at": "2026-06-10T10:03:00"
}
成功条件：
exit code = 0
+ manifest.status = success
+ outputs 中声明的文件存在
+ 关键输出文件非空
失败时也要写 manifest：
{
"manifest_version": "1.0",
"plugin_id": "custom_xxx",
"status": "failed",
"parameters": {},
"command": "...",
"error": "missing required input: input.fa",
"logs": [
"results/custom_xxx/run.log"
]
}
8. 前端与调度减法
前端只需要一个通用插件执行界面。
最低能力：
- 从
config.yaml读取插件名和参数； - 自动生成参数表单；
- 提供运行按钮；
- 显示运行状态；
- 显示日志；
- 显示结果文件列表；
- 对常见文件类型使用通用预览或下载。
不要求：
- 每个插件单独设计页面；
- 每个插件单独开发图表组件；
- 插件结果自动并入核心阶段结果页；
- 插件输出自动驱动下游分析。
9. 后端执行减法
后端只需要提供通用插件执行能力。
最低能力：
- 根据
plugin_id找到插件目录； - 读取
config.yaml； - 合并默认参数和用户修改参数；
- 执行
entry.command； - 保存 stdout/stderr；
- 读取 manifest；
- 返回状态和 outputs。
暂不要求：
- 接入核心
run_stage全路径； - 接入 StageToolRegistry；
- 接入 PlanningAgentV2；
- 接入 stage status；
- 接入正式 reproducibility_v2；
- 接入复杂 diagnosis repair。
10. 升级路径
当轻量插件满足以下条件时，可以升级为正式 bbav5 stage：
- 多个用户或多个项目反复使用；
- 输入输出格式稳定；
- 结果需要被下游阶段消费；
- 参数集合稳定；
- 运行环境明确；
- 已有真实数据验证；
- 失败模式清楚；
- 前端需要专门展示。
升级步骤：
轻量插件
-> 新增 stage contract
-> 新增 apps/cli/run_<stage>.py
-> 新增或迁移 skills/<stage>/
-> 注册 StageCapability/StageTool
-> 接入 backend run_stage
-> 接入 stage status
-> 接入 result display
-> 接入 diagnosis
-> 接入 reproducibility
11. 推荐验收标准
一个轻量扩展插件只要通过以下验收，即可认为达到 TBtools 式插件标准：
- 使用默认参数可以运行成功；
- 用户修改开放参数后，实际命令中参数同步变化；
- 输出目录生成结果文件；
- manifest 记录实际运行参数和输出文件；
- 缺少必要输入时能给出明确错误；
- 日志文件可查看；
- 前端或通用接口能列出结果文件。
12. 总结
如果当前目标是“做到和 TBtools 插件一样”，应主动做减法。
轻量扩展插件的核心不是让它立即成为完整 bbav5 正式阶段，而是先让用户跑通代码具备可调用、可配置、可记录、可复用的最小系统形态。
推荐当前定位：
不是核心 stage
不是 Agent 自动规划节点
不是下游依赖源
而是：
可配置的用户分析插件
+ 可运行入口
+ 默认参数
+ 输出收集
+ 日志记录
+ manifest 追踪
这能最大程度降低接入成本，也能保留未来升级为正式阶段的路径。