312 lines
7.4 KiB
Markdown
Executable File
312 lines
7.4 KiB
Markdown
Executable File
# TBtools 式轻量扩展插件方案
|
||
|
||
## 1. 目标
|
||
|
||
本文档定义 bbav5 中“扩展分析阶段”的减法版本：先按 TBtools 插件式能力接入，而不是立即建设为完整核心分析阶段。
|
||
|
||
目标是把用户已经跑通的代码包装成一个轻量插件，使其具备：
|
||
|
||
- 可通过统一入口运行；
|
||
- 可保留用户跑通时的默认参数；
|
||
- 可允许用户修改少量开放参数；
|
||
- 可收集输出结果；
|
||
- 可记录运行命令、参数、日志和状态。
|
||
|
||
该方案优先解决“能稳定复用用户代码”的问题，暂不追求完整的 Agent 自动规划、复杂依赖推理和下游自动消费。
|
||
|
||
## 2. 与正式阶段的边界
|
||
|
||
轻量扩展插件不是 identify、motif、domain、expression 这类完整正式阶段。
|
||
|
||
它暂时不要求：
|
||
|
||
- 新增完整 stage contract；
|
||
- 接入 PlanningAgentV2 自动规划；
|
||
- 参与核心阶段依赖推理；
|
||
- 声明复杂 consumes/provides 类型系统；
|
||
- 被下游阶段自动识别和消费；
|
||
- 为每个插件开发专用前端结果组件；
|
||
- 接入复杂 diagnosis 自动修复；
|
||
- 接受完整 publication-grade 方法学审查。
|
||
|
||
轻量插件只要求做到：
|
||
|
||
```text
|
||
用户跑通代码
|
||
-> 标准插件入口
|
||
-> 参数可配置
|
||
-> 输出可收集
|
||
-> 日志可查看
|
||
-> manifest 可追踪
|
||
```
|
||
|
||
如果后续某个插件稳定、常用，且结果需要参与下游流程，再升级为正式 bbav5 stage。
|
||
|
||
## 3. 最小插件结构
|
||
|
||
推荐目录结构：
|
||
|
||
```text
|
||
plugins/<plugin_id>/
|
||
config.yaml
|
||
run.py
|
||
README.md
|
||
examples/
|
||
```
|
||
|
||
其中：
|
||
|
||
- `config.yaml` 描述插件元信息、运行环境、默认参数和输出目录；
|
||
- `run.py` 是标准 CLI wrapper，负责调用用户原始分析代码；
|
||
- `README.md` 说明插件用途、输入、输出和示例命令；
|
||
- `examples/` 可保存最小示例输入或参数模板。
|
||
|
||
## 4. config.yaml 最小规范
|
||
|
||
轻量插件的配置只保留必要字段。
|
||
|
||
```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. 参数减法原则
|
||
|
||
参数不需要一次性全部暴露。
|
||
|
||
只开放三类参数：
|
||
|
||
1. 用户明确希望修改的参数；
|
||
2. 对结果有明显影响的核心参数；
|
||
3. 运行资源参数，例如 `threads`、`cpu`、`memory`。
|
||
|
||
暂不开放：
|
||
|
||
- 内部临时文件名；
|
||
- 中间目录；
|
||
- 不建议普通用户调整的调试参数；
|
||
- 只为兼容原始代码存在的变量；
|
||
- 修改后容易破坏流程的隐藏参数。
|
||
|
||
默认值必须来自用户已经跑通的版本。用户不修改参数时，插件应尽量复现原始运行结果。
|
||
|
||
## 6. run.py 最小职责
|
||
|
||
`run.py` 不需要重写用户分析逻辑，只做适配层。
|
||
|
||
最小职责：
|
||
|
||
- 解析 CLI 参数；
|
||
- 检查必要输入是否存在；
|
||
- 创建输出目录；
|
||
- 调用用户原始代码或核心函数；
|
||
- 收集结果文件；
|
||
- 写运行日志；
|
||
- 写 manifest；
|
||
- 失败时返回非零 exit code。
|
||
|
||
推荐命令形式：
|
||
|
||
```bash
|
||
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。
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
```
|
||
|
||
成功条件：
|
||
|
||
```text
|
||
exit code = 0
|
||
+ manifest.status = success
|
||
+ outputs 中声明的文件存在
|
||
+ 关键输出文件非空
|
||
```
|
||
|
||
失败时也要写 manifest：
|
||
|
||
```json
|
||
{
|
||
"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：
|
||
|
||
- 多个用户或多个项目反复使用；
|
||
- 输入输出格式稳定；
|
||
- 结果需要被下游阶段消费；
|
||
- 参数集合稳定；
|
||
- 运行环境明确；
|
||
- 已有真实数据验证；
|
||
- 失败模式清楚；
|
||
- 前端需要专门展示。
|
||
|
||
升级步骤：
|
||
|
||
```text
|
||
轻量插件
|
||
-> 新增 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 正式阶段，而是先让用户跑通代码具备可调用、可配置、可记录、可复用的最小系统形态。
|
||
|
||
推荐当前定位：
|
||
|
||
```text
|
||
不是核心 stage
|
||
不是 Agent 自动规划节点
|
||
不是下游依赖源
|
||
|
||
而是：
|
||
|
||
可配置的用户分析插件
|
||
+ 可运行入口
|
||
+ 默认参数
|
||
+ 输出收集
|
||
+ 日志记录
|
||
+ manifest 追踪
|
||
```
|
||
|
||
这能最大程度降低接入成本，也能保留未来升级为正式阶段的路径。
|