# 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 追踪
```

这能最大程度降低接入成本，也能保留未来升级为正式阶段的路径。