PlantAI-dev/docs/cleanup_inventory_20260522.md

# bbav5 项目清理候选清单

生成时间：2026-05-22

范围：`/home/xia-lab/wutx/00test/bbav5_0502_Yang_Tihuan.7880`

说明：本文件是只读扫描后的清理候选汇总，不代表已经删除任何文件。当前目录不是 Git 仓库，因此“是否使用”主要依据静态引用扫描、入口注册表、文件名模式和目录用途判断。真正清理前建议先整体归档或移动到隔离目录，再跑核心流程冒烟测试。

## 结论摘要

可以优先整理的低风险类别：

- Python 缓存：所有 `__pycache__/` 和 `*.pyc`。
- 显式备份/历史副本：`*.bak*`、`*.backup.*`、`*.before_*`、`*_backup*`、`apps/web/vue3copy0416/`、`apps/web/vue3copy0417/`、`backups/`。
- 历史运行产物：`workspace/`、`input/`、`final/`、`reproducibility/`、`logs/`、`cost_logs/` 中的旧 job、日志和 manifest 归档。
- 明显实验/演示/手动测试脚本：顶层 `test_*.sh`、`test_*.py`、`example_*`、`pipeline_backend_patch.py` 等。
- 大体量资源和资料：`paper/`、`models/`、`scripts/bge-m3-model/`、`memory_storage/`，这些不一定无用，但更适合放到外部资料/缓存目录，不建议混在代码根目录。

不建议直接清理的核心代码：

- `apps/cli/run_*.py` 中大多数仍被 `apps/web/pipeline_backend.py` 或 `gfa_core/mas/tools/stage_tools.py` 调用。
- `gfa_core/mas/`、`gfa_core/pipelines/`、`gfa_core/api_clients/` 下当前无备份后缀的源码。
- `skills/*/run.py`、`skills/*/SKILL.md`、`skills/*/config.yaml`，这些是阶段封装的一部分。
- `scripts/` 下被 CLI 调用的 R/Python 工具脚本，例如绘图、FASTA/GFF 处理、motif/domain/tree 相关工具。

## 入口和仍在使用的文件依据

主要运行入口：

- 前端/后端：`apps/web/vue3/main.py`
- 后端阶段执行：`apps/web/pipeline_backend.py`
- Agent 阶段注册：`gfa_core/mas/tools/stage_tools.py`
- 阶段目录和依赖：`gfa_core/mas/stage_catalog.py`
- Celery 任务：`tasks.py`、`celery_app.py`

明确注册或调用的 CLI 脚本包括：

- 核心基因家族阶段：`run_identify.py`、`run_phylogeny.py`、`run_motif.py`、`run_domain.py`、`run_structure.py`、`run_promoter.py`、`run_synteny.py`、`run_interspecies_synteny.py`、`run_karyotype.py`、`run_combo.py`、`run_ppi.py`、`run_ppi_v2.py`、`run_expression.py`、`run_pep.py`、`run_kaks_v2.py`、`run_ortholog.py`、`run_summary.py`。
- 准备/辅助阶段：`run_genome_prepare.py`、`run_prepare_substep.py`、`run_ncbi_fetch_sequences.py`、`run_sequence_extract_by_id.py`、`run_msa_region_plot.py`、`run_reference_classification.py`、`run_subfamily_confirm.py`、`run_identify_refine.py`。
- RNA-seq 阶段：`run_rnaseq_qc.py`、`run_rnaseq_align.py`、`run_rnaseq_quant.py`、`run_rnaseq_sample_qc.py`、`run_rnaseq_de.py`、`run_rnaseq_enrich.py`、`run_rnaseq_fgsea.py`、`run_rnaseq_wgcna.py`、`run_rnaseq_candidate_family.py`。
- 其他 API/配置入口：`run_annotation.py`、`run_config_autofill.py`、`run_samples_autofill.py`。

注意：`apps/cli/run_rnaseq_enrich_v2.py` 在 AGENTS.md 中被描述为 RNA-seq 富集入口，但当前 `pipeline_backend.py` 和 `stage_tools.py` 实际调用的是 `run_rnaseq_enrich.py`。该文件不建议立即删除，建议先确认是否是兼容入口或历史入口。

## 第一优先级：低风险清理候选

这些文件/目录通常可以进入“待清理隔离清单”，清理风险最低。

### Python 缓存

模式：

- `__pycache__/`
- `*.pyc`

扫描到的主要位置：

- `apps/cli/__pycache__/`
- `apps/web/__pycache__/`
- `apps/web/vue3/__pycache__/`
- `gfa_core/**/__pycache__/`
- `scripts/__pycache__/`
- `skills/*/__pycache__/`
- `tests/**/__pycache__/`

建议动作：可直接移入清理清单，运行时会自动重新生成。

### 显式备份文件

代表性文件：

- `apps/cli/run_genome_prepare.py.bak_family_allpep_20260504_193257`
- `apps/cli/run_identify.py.bak_family_allpep_20260504_193257`
- `apps/cli/run_interspecies_synteny.py.bak_blast_engine`
- `apps/cli/run_interspecies_synteny.py.bak_family_allpep_20260504_193257`
- `apps/cli/run_interspecies_synteny.py.bak_highlight_local`
- `apps/cli/run_interspecies_synteny.py.bak_pairwise_20260504_165043`
- `apps/cli/run_interspecies_synteny.py.bak_species_select`
- `apps/cli/run_rnaseq_qc.py.bak.20260430_050459`
- `apps/web/pipeline_backend.py.bak_blast_engine`
- `apps/web/pipeline_backend.py.bak_species_select`
- `apps/web/vue3/index.html.backup.1776015080`
- `apps/web/vue3/index.html.backup.1777477761`
- `apps/web/vue3/index.html.bak_blast_engine`
- `apps/web/vue3/index.html.bak_config_upload`
- `apps/web/vue3/index.html.bak_species_select`
- `apps/web/vue3/main.py.bak_blast_engine`
- `apps/web/vue3/main.py.bak_config_upload`
- `apps/web/vue3/main.py.bak_species_select`
- `gfa_core/mas/agents/result_parser.py.bak_20250421`
- `gfa_core/mas/agents/result_parser.py.before_simple`
- `gfa_core/mas/agents/result_parser.py.current_bak`
- `gfa_core/mas/tools/stage_tools.py.bak_blast_engine`
- `gfa_core/mas/tools/stage_tools.py.bak_species_select`

建议动作：优先移动到 `cleanup_candidates/backups/` 或外部归档目录；确认当前无回滚需求后删除。

### 备份目录和复制目录

目录：

- `backups/`
- `apps/cli/_backup_unused_scripts/`
- `apps/web/vue3/backups/`
- `apps/web/vue3copy0416/`
- `apps/web/vue3copy0417/`
- `gfa_core/mas/agents/backup/`

判断依据：

- 目录名明确为 `backup`、`backups`、`copy0416`、`copy0417` 或 `_backup_unused_scripts`。
- 当前主入口使用 `apps/web/vue3/main.py`、`apps/web/vue3/index.html`、`apps/web/pipeline_backend.py`，不是 `vue3copy0416` 或 `vue3copy0417`。
- `_backup_unused_scripts` 名称已经标注为未使用备份。

建议动作：整体作为历史快照归档。若需要保留，建议移出项目代码根目录。

## 第二优先级：运行产物和缓存

这些不是源码，建议按保留策略清理，例如仅保留最近 N 个 job 或最近 7-30 天。

目录：

- `workspace/`
- `input/`
- `final/`
- `reproducibility/`
- `logs/`
- `cost_logs/`
- `memory_storage/`
- `memory/`

扫描计数参考：

- `workspace/`：约 6497 个文件。
- `input/`：约 532 个文件。
- `reproducibility/`：约 52 个文件。
- `logs/`：约 14 个文件。
- `cost_logs/`：约 18 个文件。
- `memory_storage/`：约 124 个文件。

建议动作：

- `workspace/` 和 `input/`：按 job_id 分组，仅保留仍需复查的 job；已交付结果建议导出后归档。
- `reproducibility/`：保留正式分析对应的 job，删除测试 job 或过期 job。
- `logs/` 和 `cost_logs/`：可按日期保留最近 30 天。
- `memory_storage/`、`memory/`：如果是会话记忆，不属于代码，建议移到外部状态目录。

## 第三优先级：资料、模型和外部缓存

这些不一定无用，但不应长期混放在代码项目根目录。

目录：

- `paper/`
- `models/`
- `scripts/bge-m3-model/`
- `data/rag_db/`
- `data/kegg_pathway_cache/`
- `data/kegg_species_cache/`
- `data/go/go-basic.obo`

判断依据：

- `paper/` 是论文资料库，不是运行代码。
- `models/` 和 `scripts/bge-m3-model/` 是模型权重/ONNX/HuggingFace 缓存，体量通常大且可复用。
- `data/*cache*` 是可重建或可外置的缓存。

建议动作：

- 建议迁移到统一资源目录，例如 `~/wutx/shared_resources/` 或项目外部缓存目录。
- 代码中若硬编码路径，需要先统一配置化再移动。

## 第四优先级：疑似未被引用的代码文件

以下来自静态“文件名被其他文本引用”扫描。它们未在当前代码/文档中通过文件名直接引用，但不代表一定无用，可能是手动工具、命令行工具或通过动态路径调用。

高疑似历史/实验文件：

- `apps/web/vue3/main_new_funcs.py`
- `apps/web/vue3copy0417/rag_integration.py`
- `apps/web/vue3copy0417/start_server_7869.sh`
- `apps/web/vue3copy0417/test_rag_integration.py`
- `gfa_core/mas/agents/planning_v2_current_backup.py`
- `scripts/build_faiss.sh`
- `scripts/sim_verify_go_only_stage.py`
- `scripts/sim_verify_three_stages.py`
- `scripts/test_rnaseq_de_to_go_enrich_simulated_full.py`
- `scripts/test_rnaseq_enrich_background_recovery_flow.py`
- `scripts/test_rnaseq_go_kegg_annotation_agent_flow.py`
- `scripts/test_rnaseq_multiagent_linkage.py`

可能是手动工具或脚本库，需要人工确认：

- `gfa_core/config_templates.py`
- `gfa_core/mas/utility_tasks.py`
- `scripts/GeneFamily_stat.py`
- `scripts/MOTree.pm`
- `scripts/calculate_fpkm_tpm.R`
- `scripts/combine_hmm_blast.py`
- `scripts/draw_enrich_expression.R`
- `scripts/gene_highlight_jcvi.py`
- `scripts/get_dataset_color.py`
- `scripts/get_dataset_symbol.py`
- `scripts/get_mapchart_tandem.py`
- `scripts/map_data_ids.py`
- `scripts/map_fasta_ids.py`
- `scripts/motree_py.py`
- `scripts/plot_interspecies_synteny.R`
- `scripts/plot_tree.Huihuai.R`
- `scripts/prefix_reference_gff.py`
- `scripts/promoter_visualization_enhanced.R`
- `scripts/promoter_visualization_enhanced_v3.R`
- `scripts/promoter_visualization_enhanced_v4.R`
- `scripts/sort_fasta_by_ids.py`
- `scripts/subfamliy_blast.py`
- `scripts/tree_motif_domain_structure.R/motif_plot.R`
- `scripts/tree_motif_domain_structure.R/tree_motif_structure.R`

建议动作：

- 不要直接删除第二组；先对每个脚本执行 `rg "脚本名"` 和一次核心流程冒烟测试。
- 对保留的手动工具，建议加 README 或移动到 `tools/legacy/`，避免继续和生产脚本混淆。

## 测试/演示/临时脚本候选

这些文件更适合进入 `tests/` 或 `devtools/`，其中顶层测试脚本不建议长期放根目录。

- `test_agent_manual.sh`
- `test_annotation_skill.sh`
- `test_full_integration.sh`
- `test_langgraph_state.py`
- `test_rnaseq_align.sh`
- `test_router.py`
- `test_tree_plot.sh`
- `run_kaks_manual.sh`
- `example_task_with_wechat.py`
- `pipeline_backend_patch.py`
- `validate_js.py`
- `apps/web/test_stage_integration.py`
- `apps/web/vue3/static/interpretation-modal-demo.html`

建议动作：保留有价值的移入 `tests/` 或 `devtools/`；过期的移入清理清单。

## 顶层杂项文件候选

需要根据当前是否仍使用微信/通知/会话功能确认：

- `wechat_bot.py`
- `wechat_service.py`
- `wechat_task_bridge.py`
- `wechat_integration.py`
- `notify_integration.py`
- `get_wechat_id.py`
- `start_wechat_bot.sh`
- `start_wechat_service.sh`
- `WECHAT_INTEGRATION.md`
- `enable_persistent_memory.py`
- `session_storage.py`
- `check_cost.py`
- `update_prompts.py`

判断：这些是外围集成，不是核心 13 个分析阶段。若当前系统仍依赖微信通知或会话记忆，则不要删除；若只保留基因家族分析执行系统，可归档到 `integrations/wechat/` 或清理候选目录。

## 不建议清理或需谨慎清理

- `AGENTS.md`、`CLAUDE.md`、`pytest.ini`：项目/测试配置。
- `apps/web/vue3/main.py`、`apps/web/vue3/index.html`、`apps/web/pipeline_backend.py`：当前服务主路径。
- `tasks.py`、`celery_app.py`、`start_celery*.sh`：当前 Celery 队列相关。
- `gfa_core/schemas/`：阶段契约和 manifest schema。
- `gfa_core/mas/stage_catalog.py`、`gfa_core/mas/tools/stage_tools.py`、`gfa_core/mas/core/`、`gfa_core/mas/agents/` 中无备份后缀的文件。
- `skills/*` 中无缓存后缀的 `SKILL.md`、`run.py`、`config.yaml`、`templates/`。
- `scripts/plot_*.R`、`scripts/*structure*.R`、`scripts/*motif*.R`、`scripts/*promoter*.R` 等绘图脚本，除非确认当前 CLI 不再调用。

## 建议的后续清理流程

1. 创建隔离目录，例如 `cleanup_candidates/20260522/`。
2. 先移动第一优先级文件：`__pycache__`、`*.pyc`、显式 `.bak*`、`apps/web/vue3copy*`、`backups/`。
3. 运行冒烟测试：启动 `apps/web/vue3/main.py`，并至少测试 `identify`、`phylogeny`、`motif/domain/structure`、`rnaseq_enrich` 的 dry-run 或小数据任务。
4. 再按 job_id 清理 `workspace/`、`input/`、`reproducibility/`、`logs/`。
5. 最后处理模型/论文/缓存资源，把路径改为配置项后迁移到项目外。

## 建议保留的清理策略文件结构

后续如果要真正执行清理，建议生成一个机器可读清单，例如：

```text
cleanup_candidates/
  20260522/
    delete_low_risk.txt
    archive_backups.txt
    archive_runtime_jobs.txt
    review_manual_tools.txt
    keep_core.txt
```

其中 `delete_low_risk.txt` 只放缓存和明确备份；`review_manual_tools.txt` 放本报告第四优先级的脚本，等人工确认后再进入删除或归档清单。