用途:面向解码器、编解码器、解析器、校验器、格式化器、编译器、转译器、linter 等执行数据转换的纯函数模块,为其提供 shell 可达的入口和批量验证手段。
主要能力与用法:
- CLI 暴露。每个转换模块通过 <bin> <module> <subcmd> 调用。info 为纯读取,打印头部或元数据,必需;decode/parse 从源格式转出,模块消费输入时必需;encode/render 转回源格式,模块产生输出时必需;identify/validate 用于分类或校验,可选但成本低。子命令是 shell 入口,复用模块既有函数,不重新实现。
- stdout 优先。读取类子命令省略目标参数时默认流式输出到 stdout,便于管道使用,例如 mytool codec info foo.bin | head -20、mytool codec decode foo.bin | jq .header、mytool codec decode foo.bin | cmp - expected.raw。错误写入 stderr,退出码遵循 0 成功、非 0 失败;读取命令不向 stdout 打印装饰性横幅。
- 模块纯度。CLI 路径依赖尽量少,例如编解码模块的 CLI 入口不应导入应用 UI/框架层。判断标准是 CLI 能否在无头、无框架环境运行。
- 每个子命令一个 justfile recipe,命名为 <module>-<subcmd>,并以构建为前置依赖,路径通过 GAME_ROOT/DATA_DIR/FIXTURE_DIR 等工作区变量解析。
- 每个模块一个 <module>-smoke recipe,遍历每个随发布提供的输入并打印单行摘要。
- 同一提交落地。CLI、recipe 与模块代码在同一个提交中完成,否则功能不推进到下一状态。
适用场景:设计具有明确输入输出契约的新模块、为既有库增加 CLI 暴露、编写批量验证 recipe、判断功能是否完成。
限制:内部无稳定接口的辅助函数、消费者仅为同进程模块的代码、一次性脚本、纯实验实现均不适用;模块需要 UI 或框架上下文时应先重构。资料未提供安装命令、具体项目结构、依赖要求、价格或平台信息。