用途：FlowIO 是低层级的 FCS 文件读写工具，适用于读取 FCS 2.0、3.0、3.1、检查 HEADER/TEXT/ANALYSIS 与通道元数据、把事件数据取为二维 NumPy 数组、读取含多个数据集的旧文件、写出 FCS 3.1 列表模式单精度文件，以及为 pandas、机器学习或下游流式工具准备数据。它不执行补偿、logicle/biexponential 变换、门控、聚类或 FlowJo 工作区处理，这些需用 FlowKit 等分析包。
安装：uv pip install "flowio==1.4.0"；确认版本：uv run python -c "import flowio; print(flowio.version)"。FlowIO 1.4.0 支持 Python 3.9 至 3.13，依赖 NumPy。
主要能力与语义：FlowData.text 的键为小写并去掉前导 $，如 date、cyt、nextdata，值仍为字符串；1.4.0 还会移除 TEXT 段中所有 $ 字符，需精确元数据时保留原文件。flow.events 是解码后展平的一维数组，整数解析已应用 PnR 范围掩码，并非原始字节。flow.as_array() 返回 float64 二维数组，列数与通道数对应；as_array(preprocess=True) 应用增益、对数与时间缩放，preprocess=False 只做重排；均不应用补偿或 logicle 变换。列索引与 fluoro_indices 等为从 0 开始，flow.channels 的 FCS 参数编号从 1 开始。FlowIO 不提供分块或内存映射访问。
使用方式：读取用 FlowData("sample.fcs") 或 Path，按需 only_text=True 仅读元数据（此时不可调用 as_array()）。多数据集用 read_multiple_data_sets("file.fcs") 而非手动解析 NEXTDATA。写出用 create_fcs()，要求已打开的二进制文件句柄、按事件/通道行主序展平的一维数据、每通道一个 PnN 名称，可选 PnS 与字符串元数据；仅写 FCS 3.1 ($MODE=L, $DATATYPE=F)。不改事件数据时可 write_fcs() 复制重写，传入 metadata 字典会替换默认而非合并。写出后应重新打开验证事件数、通道标签与代表性数值。
限制：默认严格解析，不应自动压制偏移错误；TEXT 可能含样本、受试者、操作者与仪器标识等敏感信息，仅导出任务所需字段。随附 scripts/inspect_fcs.py 可离线盘点数据集，默认仅读元数据并限制文件大小，可加 --include-text、--stats、--raw 等选项。参考文件包括 api_reference.md、workflows.md、fcs_semantics.md、troubleshooting.md、sources.md。