开发者架构设计

这页面向需要修改实现的人。它关心的不是营销式“大图”，而是维护时必须保持稳定的结构约束：模块如何分层、数据如何流动、哪些点一旦改坏就会直接影响性能或可维护性。

系统分层

FastQTools 可以粗分为四层：

1. CLI 层：负责解析参数、组织日志、把外部输入转成明确命令；
2. 应用命令层：把 stat / filter 这样的用户意图映射到内部配置；
3. 公共 API 层：通过 include/fqtools/ 暴露稳定接口；
4. 实现层：在 src/io/、src/processing/、src/statistics/ 等目录中完成真正的读写、处理与统计。

维护时最重要的原则是：外部边界尽量窄，内部实现可以演化，但不要让 CLI、公共头文件与内部细节纠缠在一起。

执行模型

项目的核心执行模型可以概括为：source → processing → sink。

• source：读取输入、解压与解析 FASTQ 记录；
• processing：对批次应用谓词、修剪器、统计器等实际计算；
• sink：写出结果、汇总统计，并保持必要的顺序约束。

在并行路径中，这个模型通常由 tbb::parallel_pipeline 承载。维护者需要特别关注串行边界与并发边界是否仍然清晰，因为很多性能问题并不是算法错误，而是把本该分层的工作重新耦合在一起。

FastqBatch 为什么重要

FastqBatch 是理解项目性能与内存行为的关键入口。它把一批记录组织为可批量搬运、可复用的内存单元，并尽量减少不必要的字符串复制。

当你修改 I/O、过滤器或统计逻辑时，应该优先问自己：

• 这次改动是否破坏了批处理边界？
• 是否引入了额外的拷贝或生命周期风险？
• 是否让原本可以并行的阶段被串行化？

维护时常见的判断题

• 如果你改的是用户可见行为，要同步检查 CLI 文档与 API 文档；
• 如果你改的是执行路径，要同步检查 benchmark 叙事是否仍然成立；
• 如果你改的是模块边界，要回看 OpenSpec baseline 与相关 ADR，确认不是在局部修补中悄悄改变架构承诺。