README_zh.md
1# Galaxy 文本与表格算子
2
3[English](README.md)
4
5本目录提供 6 个通过源码发布的 Scala 算子,基于 [Galaxy tools-devteam](https://github.com/galaxyproject/tools-devteam) 的文本工具实现,上游版本为 `ddbe2a1e6eded54877d786fbcfc18e594fb12932`。原始脚本、XML 定义和标准测试数据保留在 `upstream/`,SHA-256 记录在 `upstream-manifest.json`。本批包含 6 个通用工具,并非完整 Galaxy 工具集合,也不是 Galaxy 工作流导入器。
6
7## 选择算子
8
9所有算子的版本均为 `1.0`,包含一个 `source` bytes 输入和一个 `result` bytes 输出,文本编码为 UTF-8。它们通过 JVM SDK 提供结构推导和受大小限制的输出样例。`bytes` 输出表达表格文本,不会声明 Arrow records schema;需要 records 时应连接合适的文本/TSV 解析算子。共享运行时为 `jvm-arrow@2.1`,产物是薄 JAR,无新增运行时依赖。
10
11| 算子 | 参数(默认值) | 行为 / 上游工具 |
12| --- | --- | --- |
13| `galaxy_change_case` | `columns: c1`、`delimiter: tab`、`casing: upper` | 修改所选字段大小写,输出 TSV / `change_case/changeCase.pl` |
14| `galaxy_condense_characters` | `character: tab` | 压缩连续重复字符,输出文本 / `condense_characters/condense_characters.pl` |
15| `galaxy_convert_delimiters` | `character: tab` | 去除每行首尾空白,将连续分隔符转换为制表符,输出 TSV / `convert_characters/convert_characters.py` |
16| `galaxy_cut_columns` | `columns: c1`、`delimiter: tab` | 选择、重排、重复列,跳过 `#` 行,缺失字段填 `.`,输出 TSV / `cut_columns/cutWrapper.pl` |
17| `galaxy_merge_columns` | `columns: c1` | 将所选字段无分隔拼接后附加一列,忽略缺失字段,保留注释和空行,输出 TSV / `merge_cols/mergeCols.py` |
18| `galaxy_add_column` | `value: "1"`、`iterate: false` | 附加常量;启用递增后非负整数从该值递增,其他值生成 `value-0`、`value-1` 等,输出 TSV / `add_value/fixedValueColumn.pl` |
19
20`columns` 从 1 开始,格式如 `c1,c4,c2-c3`,展开后最多 1024 列,最大列号 999999。`delimiter` 可选 `tab`、`comma`、`dash`、`underscore`、`pipe`、`dot`、`whitespace`;`character` 还支持 `space`、`colon`。未知参数、不支持的枚举和错误列配置会在结构推导及执行时失败。`value` 不能包含制表符或换行。参数不是 shell 命令或正则表达式。这些是按分隔符处理的文本工具,不是支持引号的 CSV 工具,不能用来解析带引号的 CSV 字段。
21
22```mermaid
23flowchart LR
24 A[Item bytes 视图] --> B[统一分隔符]
25 B --> C[修改所选列大小写]
26 C --> D[附加行标识]
27 D --> E[TSV bytes 流]
28```
29
30## 执行 Job
31
32发布后,从 XStream 项目根目录执行:
33
34```bash
35xstream-engine/target/universal/stage/bin/xstream-runner \
36 examples/operators/galaxy/engine.yaml examples/operators/galaxy/job.yaml
37```
38
39示例读取 `context:/galaxy/input.txt`,将连续逗号转换为制表符,将第一列改为大写,再附加递增标识,输出:
40
41```text
42SAMPLE group row-0
43ALPHA a row-1
44BETA b row-2
45```
46
47将 `remote_operator_library_urls` 设置为所用仓库,并按需要配置传输信任。发布无需修改核心注册表,也无需重新构建执行服务器。
48
49## 构建与验证
50
51先将 XStream JVM SDK 发布到本地,然后在本目录执行:
52
53```bash
54sbt package 'Test / runMain xstream.galaxy.SafetyCheck'
55python3 make-catalog.py
56python3 verify.py --docker-prefix '' --report /tmp/galaxy-tests.json
57```
58
59验证脚本所用 Python 环境需安装 PyArrow。`verify.py` 在本地 Docker 中使用已注册的运行时镜像,执行期间禁用网络。`--docker-prefix` 默认值为本开发机使用的 `sudo -n -u cnic -g docker`;当前用户已有 Docker 权限时使用 `''`。通过 `--runtime IMAGE` 可选择其他兼容镜像。测试比较 9 组 Galaxy 原始标准测试数据,覆盖 24 个执行用例,包括空输入、两字节 Arrow 分块、Unicode、CRLF、末行无换行;还验证 6 个推导/样例契约、错误参数、非法 UTF-8、超长行和三步算子流水线。`SafetyCheck` 验证取消、I/O 异常传播、参数错误和输出展开限制。使用 `--artifact FILE --only NAME` 可以在审核前验证单个仓库构建的 JAR。
60
61输入可跨 Arrow 批次连续读取,不会缓存整个 Item。单行限制为 1,048,576 个 UTF-16 字符,所选/生成字段拼接限制为 4,194,304 个字符,参数字符串最多 4096 个字符,所选列最多 1024 个。工作内存受这些单行限制和 SDK 缓冲区约束。输出样例遵守 SDK 字节预算。读取期间和每行处理均检查取消,输入与输出异常传递给引擎。业务逻辑不调用 shell、子进程、网络或应用文件访问。
62
63## 发布源码
64
65```bash
66python3 publish.py --url http://localhost:8820 \
67 --token-file /secure/publisher.token --output /tmp/galaxy-publication
68```
69
70该命令提交 6 份源码归档,由仓库隔离构建 Scala 算子,保持待审核状态。只提交一个工具时,在末尾添加短名称,例如 `cut_columns`。管理员可以增加 `--approve-password-file /secure/admin-password`;该模式等待构建,下载并验证每个候选产物,指定 `Galaxy`、`Text processing`、`Tabular data` 分类和 4 分可信度,再审批发布,并核验公开下载与已测试候选产物一致。测试失败即停止发布。凭据从独立文件读取,不会打包或打印。远程发布必须使用 HTTPS。可信度是评估结果,不是安全保证。审核记录和产物测试报告写入 `--output`。
71
72每份源码归档包含 Scala 实现、上游证据、中英文说明、验证脚本和完整许可文本;发布的 JAR 内包含 `META-INF/LICENSE`、`META-INF/NOTICE` 和对应算子定义。源码公开。仓库管理和构建前提见[源码提交](../../../docs/operator-submission_zh.md)。
73
74## 行为与归属
75
76标准测试数据保持上游行为。有意调整包括:LF/CRLF/CR 均统一为 LF,末行没有换行时不会丢掉最后一个字符;拒绝非法 UTF-8;大小写转换采用不依赖区域设置的 Unicode 规则;`condense_characters` 将连续空白转为一个空格(上游 `s` 选项缺少有效替换分支);点号压缩输出字面量点号,避免原 Perl 脚本的转义替换结果;分隔符采用可读枚举;错误参数直接失败,不再静默忽略。change/cut 的尾部空字段遵循原 Perl 工具,merge 遵循原 Python 工具。资源限制和取消行为明确。
77
78Galaxy Contributors 保留原始工具与测试数据的版权。上游许可将 2024-12-01 前的贡献归为 AFL-3.0,此后的贡献归为 MIT。[LICENSE](LICENSE) 原样包含两种完整许可,混合来源声明为 `AFL-3.0 AND MIT`。另见 [NOTICE](NOTICE)。这些是独立的 XStream 适配实现,不是 Galaxy 官方发行版。