nostop-cli 0.1.0__tar.gz

nostop_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nostop contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nostop_cli-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include src/nostop *.sh

nostop_cli-0.1.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: nostop-cli
+Version: 0.1.0
+Summary: Resume-capable command wrapper for Linux: rerun interrupted commands and skip completed steps.
+Author: nostop
+License-Expression: MIT
+Project-URL: Homepage, https://example.com/nostop
+Keywords: cli,resume,checkpoint,pipeline,bioinformatics
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Console
+Classifier: Topic :: System :: Shells
+Classifier: Programming Language :: Unix Shell
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nostop
+
+一个极小的 Linux 命令行工具，用于**包装并执行任意命令**，并在命令因断网、断电、
+崩溃等任何原因中断后，能够**从中断处继续**，避免从头重跑浪费时间。
+
+```bash
+nostop <命令>          # 运行 / 续跑一条命令
+nostop stats           # 查看此前中断的命令（命令内容 + 中断时的工作目录）
+```
+
+---
+
+## 它解决什么问题
+
+- 跑了 6 个小时的生信流程，第 5 步时断电 / 断网 / 节点被回收，重跑又要 6 小时。
+- 写了一个多步骤的 shell 流程，中途失败，希望**已完成的步骤不要再跑**。
+
+nostop 的价值：
+
+1. **通用**：`nostop <任意命令>` 的行为与直接执行该命令完全一致（输出、退出码、环境都透传）。
+2. **可续跑**：中断后再次运行**完全相同**的 `nostop <命令>`（同一工作目录），工具会识别已完成的
+   进度并跳过，从断点继续。
+3. **可查询**：`nostop stats` 列出此前中断的命令，含命令内容与其**中断时所在路径（cwd）**，
+   方便你回到原目录重新启动。
+4. **简约**：单个 bash 脚本，无编译、无依赖、无守护进程、无数据库；体积几 KB，运行时几乎零开销。
+5. **支持广**：既支持“多步骤 shell 脚本”（用 checkpoint API 精确跳过步骤），也支持“单个长时间
+   运行的程序”（如 megahit 等自带断点续跑能力的二进制，nostop 负责用完全相同的方式重新拉起它）。
+
+---
+
+## 安装
+
+### 方式一：pip 安装（推荐）
+
+本工具已打包为 Python 项目，可直接用 pip 从源码或你们内部的 PyPI 源安装：
+
+```bash
+# 从本地源码目录安装
+pip install .
+
+# 或打包后安装（生成 dist/nostop-cli-*.whl / tar.gz）
+pip install build
+python -m build
+pip install dist/nostop-cli-*.whl
+
+# 如需发布到你们内部的 PyPI 或公开 PyPI：
+twine upload dist/*
+# 之后他人即可：pip install nostop-cli   （命令名仍是 nostop）
+```
+
+安装后 `nostop` 命令即可用（其实质是一个极薄的 Python 入口，启动后立刻 exec
+到内置的 bash 脚本，运行时不依赖 Python）。也可用 `python -m nostop ...` 运行。
+
+### 方式二：单文件拷贝（零依赖，连 Python 都不需要）
+
+如果你只想用一个文件、连 Python 环境都不想依赖，直接复制内置脚本即可
+（依赖系统自带的 bash 与 coreutils，CentOS / Ubuntu 等主流发行版默认都有）：
+
+```bash
+sudo cp src/nostop/nostop.sh /usr/local/bin/nostop
+sudo chmod +x /usr/local/bin/nostop
+
+# 可选：自定义状态目录（默认 ~/.nostop）
+# export NOSTOP_HOME=/data/.nostop
+```
+
+验证：`nostop help`
+
+---
+
+## 快速开始
+
+```bash
+# 像平常一样运行命令，只是前面加 nostop
+nostop "bash my_pipeline.sh"
+
+# 中断后，回到同一个目录，原样再敲一次即可续跑
+nostop "bash my_pipeline.sh"
+
+# 查看哪些命令之前中断了（含命令内容与工作目录）
+nostop stats
+```
+
+---
+
+## 场景一：多步骤 shell 流程（精确到步骤的跳过）
+
+对“脚本里有多个步骤”的情况，使用 nostop 提供的 **checkpoint（检查点）API**。
+在脚本里把每个步骤包成 `nostop step <名字> -- <命令>`：
+
+```bash
+#!/bin/bash
+# my_pipeline.sh
+nostop step prepare  -- "echo 准备数据 && sleep 2"
+nostop step align    -- "echo 比对 && sleep 2"
+nostop step call     -- "echo 变异检测 && sleep 2"
+nostop step report   -- "echo 出报告"
+echo "全部完成"
+```
+
+运行：
+
+```bash
+nostop "bash my_pipeline.sh"
+```
+
+- 第一次正常运行，每完成一步就记录一个检查点。
+- 中途断电/被杀：再次 `nostop "bash my_pipeline.sh"` 时，已完成的步骤会被**自动跳过**
+  （输出 `[nostop] skip step 'prepare' (already done)`），直接从断点继续。
+- 步骤失败（退出码非 0）不会被标记为完成，下次会自动重跑该步骤。
+
+> 如果你的步骤本身是一条带管道 / 重定向的复杂命令，可以写成单个字符串：
+> `nostop step build -- "make && make test | tee build.log"`。
+
+手动控制检查点（更灵活）：
+
+| 写法 | 作用 |
+| --- | --- |
+| `nostop step <名字> -- <命令>` | 运行命令；成功则标记 `<名字>` 完成，下次跳过 |
+| `nostop done <名字>` | 退出码 0 表示该检查点已完成，否则 1（用于 `if` 判断） |
+| `nostop mark <名字>` | 直接把 `<名字>` 标记为完成 |
+
+例如在脚本里手写分支：
+
+```bash
+if nostop done align; then
+  echo "比对已完成，跳过"
+else
+  do_align && nostop mark align
+fi
+```
+
+> 注意：checkpoint API 只在 `nostop <命令>` 内部才记录进度；直接 `bash my_pipeline.sh`
+> 运行时它会退化为“直接执行”，不影响结果，只是不记录进度。
+
+---
+
+## 场景二：单个长时间运行的程序（如 megahit）
+
+很多生信程序（megahit、Trinity、SPAdes 等）**自身就支持断点续跑**——只要用相同的输出目录
+重新运行，它们会接着上次的产物继续。nostop 在这里的作用是：**用完全相同的方式重新拉起命令，
+并替你记录状态 / 方便重跑**。
+
+```bash
+# 第一次运行
+nostop "megahit -1 read1.fq -2 read2.fq -o mega.out"
+
+# 中断后，回到同一目录，原样再敲一次；megahit 会基于 mega.out 里已有的中间文件续跑
+nostop "megahit -1 read1.fq -2 read2.fq -o mega.out"
+```
+
+nostop 本身对“单个二进制内部进度”无感知（那是程序自己的事），但它保证：
+- 用**完全相同的命令字符串与工作目录**重启；
+- 把这次运行登记到状态库，供 `nostop stats` 查看；
+- 程序成功跑完（退出码 0）后记为 `DONE`，之后原样再跑会被直接跳过，不会重复计算。
+
+> 如果程序需要显式续跑参数（例如某些工具要用 `--continue` / `-c`），把它写进命令里即可，
+> 因为 nostop 是“原样重放”。
+
+## 场景三：批处理（nostop batch）
+
+当同一道命令要对多组输入分别跑一遍（例如多个样本分别做 fastp / spades），用 `nostop batch`
+一次性提交。它把每条输入展开到模板里，并把**每条输入当作一个检查点**——中断后续跑时，
+已完成的样本会被自动跳过。
+
+模板占位符：
+
+- `{N}`：第 N 个字段（从 1 起），输入按 `:` 切分。例 `s1_1.fq:s1_2.fq` → `{1}=s1_1.fq`、`{2}=s1_2.fq`。
+- `{}`：整条输入原文（含 `:`）。
+
+```bash
+# 双端配对（{1}/{2} 占位）
+nostop batch "fastp -i {1} -I {2} -o {1}.clean.fq -O {2}.clean.fq" s1_1.fq:s1_2.fq s2_1.fq:s2_2.fq
+
+# 工具无续跑参数时，结合幂等写法最稳（重跑时已完成的组装直接跳过）
+nostop batch "[ -s asm_{}/final.contigs.fa ] || spades.py -1 {1} -2 {2} -o asm_{}" s1_1.fq:s1_2.fq s2_1.fq:s2_2.fq
+```
+
+- 每条输入即 `nostop step <输入>` 检查点，状态同样出现在 `nostop stats`。
+- 某个样本失败，batch 会停下（不再跑后续），修好后重跑即可；已完成样本自动跳过。
+- `{}` 是整条输入原文（如 `s1_1.fq:s1_2.fq`），故 `asm_{}` 目录名会带冒号（Linux 下合法）；
+  想要干净目录名时，把样本名单独作为条目传入、用 `{1}/{2}` 拼文件路径即可。
+
+---
+
+## 子命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `nostop <命令>` | 运行 / 续跑一条命令 |
+| `nostop batch <模板> <条目>...` | 对每条条目展开模板并分别运行，已完成的跳过 |
+| `nostop stats [--all]` | 列出**中断 / 失败 / 正在运行**的命令；`--all` 同时显示已完成的 |
+| `nostop show <id>` | 查看某条运行的详情（命令、目录、开始时间、尾部输出） |
+| `nostop resume <id>` | 在原始工作目录下，重新运行该命令（不用再手敲整条命令） |
+| `nostop clean [--all|<id>]` | 清除某条（或全部）运行的状态；用于需要强制重跑时 |
+| `nostop step/mark/done <名字>` | 见上文 checkpoint API |
+| `nostop help` | 帮助 |
+
+`stats` 示例输出：
+
+```
+ID         STATUS       COMMAND
+97ecb77e   INTERRUPTED  bash my_pipeline.sh
+                        cwd: /home/user/project
+                        last checkpoint: align
+```
+
+- `ID` 是状态库里的短标识，可直接用于 `nostop show <id>` / `nostop resume <id>` / `nostop clean <id>`。
+- `STATUS` 取值：`RUNNING`（仍在跑） / `INTERRUPTED`（被中断，最常见：断电、被杀、崩溃） /
+  `FAILED`（命令自身非零退出） / `DONE`（已成功完成）。
+
+---
+
+## 工作原理（如何检测“中断”）
+
+状态保存在 `$NOSTOP_HOME/runs/<hash>/`，其中 `<hash>` 由 **命令字符串 + 当前工作目录** 计算。
+每次运行写入 `meta` 文件，记录 `status`（初始 `running`）、`pid`、`boot_id`（来自
+`/proc/sys/kernel/random/boot_id`）、命令、目录等。
+
+- 命令**成功退出** -> `status=done`；**非零退出** -> `status=failed`。
+- 若进程被 **SIGINT/SIGTERM** 终止 -> 捕获后记为 `interrupted`。
+- 若机器**断电 / 崩溃**（nostop 来不及响应）-> `meta` 仍停留在 `running`，
+  且记录的 `pid` 已不存在（或 `boot_id` 与本次启动不一致）-> 查询时判定为 `INTERRUPTED`。
+
+因此 `nostop stats` 能可靠区分“正在跑”、“被中断”、“已成功”、“已失败”。
+
+---
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `NOSTOP_HOME` | `~/.nostop` | 状态库根目录，可指向大容量磁盘 |
+
+---
+
+## 兼容性与限制
+
+- **兼容性**：纯 bash + coreutils（`sha256sum`/`date`/`kill`/`tee`），CentOS 7/8、Ubuntu 20.04/22.04
+  等主流发行版开箱即用；仅依赖 Linux 的 `/proc/sys/kernel/random/boot_id`（缺失时退化为仅按 PID 判断）。
+- **限制**：
+  - 对“单个不自带续跑能力的黑盒二进制”，nostop 只能保证原样重放，无法替它在内部续跑；
+    这类场景请用脚本 + `nostop step` 拆成可重入的步骤，或选用自带续跑的程序。
+  - 检查点跳过依赖**步骤本身是可重入 / 幂等**的；请确保重试某步不会造成破坏。
+  - 同一“命令 + 目录”被视为同一次运行；若想以不同参数再跑一份，请换目录或改命令。
+- **已知命令已 DONE 时**再原样运行会被直接跳过（输出提示）。需要强制重跑请先 `nostop clean <id>`。
+
+---
+
+## 文件结构
+
+```
+nostop            # 工具本体（单文件，拷贝即用）
+README.md         # 本文档
+examples/         # 示例脚本
+  pipeline.sh     # 场景一：带 checkpoint 的多步骤流程
+  megahit.sh      # 场景二：单个长时间程序续跑示例
+```

nostop_cli-0.1.0/README.md

@@ -0,0 +1,258 @@
+# nostop
+
+一个极小的 Linux 命令行工具，用于**包装并执行任意命令**，并在命令因断网、断电、
+崩溃等任何原因中断后，能够**从中断处继续**，避免从头重跑浪费时间。
+
+```bash
+nostop <命令>          # 运行 / 续跑一条命令
+nostop stats           # 查看此前中断的命令（命令内容 + 中断时的工作目录）
+```
+
+---
+
+## 它解决什么问题
+
+- 跑了 6 个小时的生信流程，第 5 步时断电 / 断网 / 节点被回收，重跑又要 6 小时。
+- 写了一个多步骤的 shell 流程，中途失败，希望**已完成的步骤不要再跑**。
+
+nostop 的价值：
+
+1. **通用**：`nostop <任意命令>` 的行为与直接执行该命令完全一致（输出、退出码、环境都透传）。
+2. **可续跑**：中断后再次运行**完全相同**的 `nostop <命令>`（同一工作目录），工具会识别已完成的
+   进度并跳过，从断点继续。
+3. **可查询**：`nostop stats` 列出此前中断的命令，含命令内容与其**中断时所在路径（cwd）**，
+   方便你回到原目录重新启动。
+4. **简约**：单个 bash 脚本，无编译、无依赖、无守护进程、无数据库；体积几 KB，运行时几乎零开销。
+5. **支持广**：既支持“多步骤 shell 脚本”（用 checkpoint API 精确跳过步骤），也支持“单个长时间
+   运行的程序”（如 megahit 等自带断点续跑能力的二进制，nostop 负责用完全相同的方式重新拉起它）。
+
+---
+
+## 安装
+
+### 方式一：pip 安装（推荐）
+
+本工具已打包为 Python 项目，可直接用 pip 从源码或你们内部的 PyPI 源安装：
+
+```bash
+# 从本地源码目录安装
+pip install .
+
+# 或打包后安装（生成 dist/nostop-cli-*.whl / tar.gz）
+pip install build
+python -m build
+pip install dist/nostop-cli-*.whl
+
+# 如需发布到你们内部的 PyPI 或公开 PyPI：
+twine upload dist/*
+# 之后他人即可：pip install nostop-cli   （命令名仍是 nostop）
+```
+
+安装后 `nostop` 命令即可用（其实质是一个极薄的 Python 入口，启动后立刻 exec
+到内置的 bash 脚本，运行时不依赖 Python）。也可用 `python -m nostop ...` 运行。
+
+### 方式二：单文件拷贝（零依赖，连 Python 都不需要）
+
+如果你只想用一个文件、连 Python 环境都不想依赖，直接复制内置脚本即可
+（依赖系统自带的 bash 与 coreutils，CentOS / Ubuntu 等主流发行版默认都有）：
+
+```bash
+sudo cp src/nostop/nostop.sh /usr/local/bin/nostop
+sudo chmod +x /usr/local/bin/nostop
+
+# 可选：自定义状态目录（默认 ~/.nostop）
+# export NOSTOP_HOME=/data/.nostop
+```
+
+验证：`nostop help`
+
+---
+
+## 快速开始
+
+```bash
+# 像平常一样运行命令，只是前面加 nostop
+nostop "bash my_pipeline.sh"
+
+# 中断后，回到同一个目录，原样再敲一次即可续跑
+nostop "bash my_pipeline.sh"
+
+# 查看哪些命令之前中断了（含命令内容与工作目录）
+nostop stats
+```
+
+---
+
+## 场景一：多步骤 shell 流程（精确到步骤的跳过）
+
+对“脚本里有多个步骤”的情况，使用 nostop 提供的 **checkpoint（检查点）API**。
+在脚本里把每个步骤包成 `nostop step <名字> -- <命令>`：
+
+```bash
+#!/bin/bash
+# my_pipeline.sh
+nostop step prepare  -- "echo 准备数据 && sleep 2"
+nostop step align    -- "echo 比对 && sleep 2"
+nostop step call     -- "echo 变异检测 && sleep 2"
+nostop step report   -- "echo 出报告"
+echo "全部完成"
+```
+
+运行：
+
+```bash
+nostop "bash my_pipeline.sh"
+```
+
+- 第一次正常运行，每完成一步就记录一个检查点。
+- 中途断电/被杀：再次 `nostop "bash my_pipeline.sh"` 时，已完成的步骤会被**自动跳过**
+  （输出 `[nostop] skip step 'prepare' (already done)`），直接从断点继续。
+- 步骤失败（退出码非 0）不会被标记为完成，下次会自动重跑该步骤。
+
+> 如果你的步骤本身是一条带管道 / 重定向的复杂命令，可以写成单个字符串：
+> `nostop step build -- "make && make test | tee build.log"`。
+
+手动控制检查点（更灵活）：
+
+| 写法 | 作用 |
+| --- | --- |
+| `nostop step <名字> -- <命令>` | 运行命令；成功则标记 `<名字>` 完成，下次跳过 |
+| `nostop done <名字>` | 退出码 0 表示该检查点已完成，否则 1（用于 `if` 判断） |
+| `nostop mark <名字>` | 直接把 `<名字>` 标记为完成 |
+
+例如在脚本里手写分支：
+
+```bash
+if nostop done align; then
+  echo "比对已完成，跳过"
+else
+  do_align && nostop mark align
+fi
+```
+
+> 注意：checkpoint API 只在 `nostop <命令>` 内部才记录进度；直接 `bash my_pipeline.sh`
+> 运行时它会退化为“直接执行”，不影响结果，只是不记录进度。
+
+---
+
+## 场景二：单个长时间运行的程序（如 megahit）
+
+很多生信程序（megahit、Trinity、SPAdes 等）**自身就支持断点续跑**——只要用相同的输出目录
+重新运行，它们会接着上次的产物继续。nostop 在这里的作用是：**用完全相同的方式重新拉起命令，
+并替你记录状态 / 方便重跑**。
+
+```bash
+# 第一次运行
+nostop "megahit -1 read1.fq -2 read2.fq -o mega.out"
+
+# 中断后，回到同一目录，原样再敲一次；megahit 会基于 mega.out 里已有的中间文件续跑
+nostop "megahit -1 read1.fq -2 read2.fq -o mega.out"
+```
+
+nostop 本身对“单个二进制内部进度”无感知（那是程序自己的事），但它保证：
+- 用**完全相同的命令字符串与工作目录**重启；
+- 把这次运行登记到状态库，供 `nostop stats` 查看；
+- 程序成功跑完（退出码 0）后记为 `DONE`，之后原样再跑会被直接跳过，不会重复计算。
+
+> 如果程序需要显式续跑参数（例如某些工具要用 `--continue` / `-c`），把它写进命令里即可，
+> 因为 nostop 是“原样重放”。
+
+## 场景三：批处理（nostop batch）
+
+当同一道命令要对多组输入分别跑一遍（例如多个样本分别做 fastp / spades），用 `nostop batch`
+一次性提交。它把每条输入展开到模板里，并把**每条输入当作一个检查点**——中断后续跑时，
+已完成的样本会被自动跳过。
+
+模板占位符：
+
+- `{N}`：第 N 个字段（从 1 起），输入按 `:` 切分。例 `s1_1.fq:s1_2.fq` → `{1}=s1_1.fq`、`{2}=s1_2.fq`。
+- `{}`：整条输入原文（含 `:`）。
+
+```bash
+# 双端配对（{1}/{2} 占位）
+nostop batch "fastp -i {1} -I {2} -o {1}.clean.fq -O {2}.clean.fq" s1_1.fq:s1_2.fq s2_1.fq:s2_2.fq
+
+# 工具无续跑参数时，结合幂等写法最稳（重跑时已完成的组装直接跳过）
+nostop batch "[ -s asm_{}/final.contigs.fa ] || spades.py -1 {1} -2 {2} -o asm_{}" s1_1.fq:s1_2.fq s2_1.fq:s2_2.fq
+```
+
+- 每条输入即 `nostop step <输入>` 检查点，状态同样出现在 `nostop stats`。
+- 某个样本失败，batch 会停下（不再跑后续），修好后重跑即可；已完成样本自动跳过。
+- `{}` 是整条输入原文（如 `s1_1.fq:s1_2.fq`），故 `asm_{}` 目录名会带冒号（Linux 下合法）；
+  想要干净目录名时，把样本名单独作为条目传入、用 `{1}/{2}` 拼文件路径即可。
+
+---
+
+## 子命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `nostop <命令>` | 运行 / 续跑一条命令 |
+| `nostop batch <模板> <条目>...` | 对每条条目展开模板并分别运行，已完成的跳过 |
+| `nostop stats [--all]` | 列出**中断 / 失败 / 正在运行**的命令；`--all` 同时显示已完成的 |
+| `nostop show <id>` | 查看某条运行的详情（命令、目录、开始时间、尾部输出） |
+| `nostop resume <id>` | 在原始工作目录下，重新运行该命令（不用再手敲整条命令） |
+| `nostop clean [--all|<id>]` | 清除某条（或全部）运行的状态；用于需要强制重跑时 |
+| `nostop step/mark/done <名字>` | 见上文 checkpoint API |
+| `nostop help` | 帮助 |
+
+`stats` 示例输出：
+
+```
+ID         STATUS       COMMAND
+97ecb77e   INTERRUPTED  bash my_pipeline.sh
+                        cwd: /home/user/project
+                        last checkpoint: align
+```
+
+- `ID` 是状态库里的短标识，可直接用于 `nostop show <id>` / `nostop resume <id>` / `nostop clean <id>`。
+- `STATUS` 取值：`RUNNING`（仍在跑） / `INTERRUPTED`（被中断，最常见：断电、被杀、崩溃） /
+  `FAILED`（命令自身非零退出） / `DONE`（已成功完成）。
+
+---
+
+## 工作原理（如何检测“中断”）
+
+状态保存在 `$NOSTOP_HOME/runs/<hash>/`，其中 `<hash>` 由 **命令字符串 + 当前工作目录** 计算。
+每次运行写入 `meta` 文件，记录 `status`（初始 `running`）、`pid`、`boot_id`（来自
+`/proc/sys/kernel/random/boot_id`）、命令、目录等。
+
+- 命令**成功退出** -> `status=done`；**非零退出** -> `status=failed`。
+- 若进程被 **SIGINT/SIGTERM** 终止 -> 捕获后记为 `interrupted`。
+- 若机器**断电 / 崩溃**（nostop 来不及响应）-> `meta` 仍停留在 `running`，
+  且记录的 `pid` 已不存在（或 `boot_id` 与本次启动不一致）-> 查询时判定为 `INTERRUPTED`。
+
+因此 `nostop stats` 能可靠区分“正在跑”、“被中断”、“已成功”、“已失败”。
+
+---
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `NOSTOP_HOME` | `~/.nostop` | 状态库根目录，可指向大容量磁盘 |
+
+---
+
+## 兼容性与限制
+
+- **兼容性**：纯 bash + coreutils（`sha256sum`/`date`/`kill`/`tee`），CentOS 7/8、Ubuntu 20.04/22.04
+  等主流发行版开箱即用；仅依赖 Linux 的 `/proc/sys/kernel/random/boot_id`（缺失时退化为仅按 PID 判断）。
+- **限制**：
+  - 对“单个不自带续跑能力的黑盒二进制”，nostop 只能保证原样重放，无法替它在内部续跑；
+    这类场景请用脚本 + `nostop step` 拆成可重入的步骤，或选用自带续跑的程序。
+  - 检查点跳过依赖**步骤本身是可重入 / 幂等**的；请确保重试某步不会造成破坏。
+  - 同一“命令 + 目录”被视为同一次运行；若想以不同参数再跑一份，请换目录或改命令。
+- **已知命令已 DONE 时**再原样运行会被直接跳过（输出提示）。需要强制重跑请先 `nostop clean <id>`。
+
+---
+
+## 文件结构
+
+```
+nostop            # 工具本体（单文件，拷贝即用）
+README.md         # 本文档
+examples/         # 示例脚本
+  pipeline.sh     # 场景一：带 checkpoint 的多步骤流程
+  megahit.sh      # 场景二：单个长时间程序续跑示例
+```

nostop_cli-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nostop-cli"
+version = "0.1.0"
+description = "Resume-capable command wrapper for Linux: rerun interrupted commands and skip completed steps."
+readme = "README.md"
+requires-python = ">=3.6"
+license = "MIT"
+keywords = ["cli", "resume", "checkpoint", "pipeline", "bioinformatics"]
+authors = [{ name = "nostop" }]
+classifiers = [
+    "Operating System :: POSIX :: Linux",
+    "Environment :: Console",
+    "Topic :: System :: Shells",
+    "Programming Language :: Unix Shell",
+]
+
+[project.urls]
+Homepage = "https://example.com/nostop"
+
+[project.scripts]
+nostop = "nostop.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nostop = ["nostop.sh"]

nostop_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nostop_cli-0.1.0/src/nostop/__main__.py

@@ -0,0 +1,4 @@
+from nostop.cli import main
+
+if __name__ == "__main__":
+    main()

nostop_cli-0.1.0/src/nostop/cli.py

@@ -0,0 +1,26 @@
+"""Console-script entry point for the nostop bash tool.
+
+This thin wrapper just exec's bash on the bundled ``nostop.sh`` so the real
+implementation stays a single portable shell script (no Python at runtime
+beyond launching it). exec replaces this process, so argv, environment
+(NOSTOP_RUN_DIR, NOSTOP_HOME, ...) and the exit code all pass through
+unchanged, and nested ``nostop step`` calls from inside a wrapped script
+resolve back to this same wrapper on PATH.
+"""
+
+import os
+import shutil
+import sys
+
+_SCRIPT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "nostop.sh")
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    bash = shutil.which("bash") or "/bin/bash"
+    os.execv(bash, [bash, _SCRIPT] + list(argv))
+
+
+if __name__ == "__main__":
+    main()

nostop_cli-0.1.0/src/nostop/nostop.sh

@@ -0,0 +1,343 @@
+#!/usr/bin/env bash
+# nostop - a tiny resume-capable command wrapper for Linux.
+#
+# Usage:  nostop <command>          # run / continue a command
+#         nostop stats [--all]       # list interrupted commands
+#         nostop show <id>           # details + tail of output for a run
+#         nostop resume <id>         # re-run a stored command in its dir
+#         nostop clean [--all|<id>]  # forget run state
+#         nostop step <name> -- <c>  # (inside a script) run c once, mark name
+#         nostop mark <name>         # mark checkpoint 'name' done
+#         nostop done <name>         # exit 0 if 'name' already done
+#
+# State lives in ${NOSTOP_HOME:-$HOME/.nostop}.  No daemon, no DB, just files.
+set -u
+
+NOSTOP_HOME="${NOSTOP_HOME:-$HOME/.nostop}"
+RUNS_DIR="$NOSTOP_HOME/runs"
+mkdir -p "$RUNS_DIR" 2>/dev/null || {
+  echo "[nostop] cannot create state dir $RUNS_DIR" >&2; exit 1; }
+
+SELF="$(readlink -f "$0" 2>/dev/null || command -v nostop 2>/dev/null || echo "$0")"
+
+usage() {
+  cat <<'EOF'
+nostop - wrap a command so it can resume after an interruption
+
+Usage:
+  nostop <command>                Run (or continue) COMMAND. On rerun of the
+                                  exact same command in the same directory,
+                                  completed checkpoints are skipped.
+  nostop batch <tpl> <e1> [<e2>...]  Run TEMPLATE for each entry; {1},{2},... are the
+                                  colon-separated fields, {} the whole entry.
+                                  Completed entries are skipped on resume.
+  nostop stats [--all]            List interrupted commands (cmd + working dir).
+  nostop show <id>                Show a run's details and tail of its output.
+  nostop resume <id>              Re-run a stored command in its original dir.
+  nostop clean [--all|<id>]       Forget run state (one run or everything).
+  nostop step <name> -- <cmd...>  Inside a script: run cmd once; mark 'name' done.
+  nostop mark <name>              Mark checkpoint 'name' complete for this run.
+  nostop done <name>              Exit 0 if 'name' already done, else 1.
+  nostop help                     Show this help.
+
+Env:
+  NOSTOP_HOME   override state directory (default ~/.nostop)
+
+See README.md for the checkpoint pattern and examples (megahit, pipelines).
+EOF
+}
+
+# ---------- helpers ----------
+now_iso() { date '+%Y-%m-%d %H:%M:%S'; }
+
+boot_id() {
+  if [ -r /proc/sys/kernel/random/boot_id ]; then
+    cat /proc/sys/kernel/random/boot_id
+  else
+    echo "unknown"
+  fi
+}
+
+cmd_hash() {  # cmd cwd -> sha256
+  printf '%s\0%s' "$1" "$2" | sha256sum | cut -d' ' -f1
+}
+
+# run a list of tokens the same way bash would: a single token is a shell
+# string (supports pipes/redirects); many tokens keep their quoting.
+run_args() {
+  if [ "$#" -eq 1 ]; then bash -c "$1"; else bash -c '"$@"' nostop "$@"; fi
+}
+
+_get_meta() {  # file key
+  local file="$1" key="$2" line
+  [ -f "$file" ] || return 1
+  while IFS= read -r line; do
+    case "$line" in "$key="*) printf '%s' "${line#$key=}"; return 0 ;; esac
+  done < "$file"
+  return 1
+}
+
+_set_meta() {  # file key value
+  local file="$1" key="$2" val="$3" tmp line
+  tmp="$file.tmp"
+  : > "$tmp"
+  if [ -f "$file" ]; then
+    while IFS= read -r line; do
+      case "$line" in "$key="*) ;; *) printf '%s\n' "$line" >> "$tmp" ;; esac
+    done < "$file"
+  fi
+  printf '%s=%s\n' "$key" "$val" >> "$tmp"
+  mv "$tmp" "$file"
+}
+
+compute_status() {  # st pid bid
+  local st="$1" pid="$2" bid="$3" cur
+  cur="$(boot_id)"
+  case "$st" in
+    done)        echo DONE ;;
+    failed)      echo FAILED ;;
+    interrupted) echo INTERRUPTED ;;
+    running)
+      if [ "$bid" != "$cur" ]; then echo INTERRUPTED
+      elif kill -0 "$pid" 2>/dev/null; then echo RUNNING
+      else echo INTERRUPTED; fi ;;
+    *) echo "$st" ;;
+  esac
+}
+
+# ---------- run setup (shared by run_command and batch_cmd) ----------
+# Sets up the run directory / meta / traps for a given command identity and
+# exports NOSTOP_RUN_DIR etc. RUN_DIR and META become globals for the caller.
+begin_run() {
+  local cmd="$1"
+  local cwd; cwd="$(pwd)"
+  local id; id="$(cmd_hash "$cmd" "$cwd")"
+  RUN_DIR="$RUNS_DIR/$id"
+  mkdir -p "$RUN_DIR"
+  META="$RUN_DIR/meta"
+  touch "$RUN_DIR/checkpoints"
+
+  # Refuse to launch a second instance of a still-running command.
+  if [ -f "$META" ]; then
+    local st pid
+    st="$(_get_meta "$META" status || true)"
+    pid="$(_get_meta "$META" pid || true)"
+    if [ "$st" = "done" ]; then
+      echo "[nostop] already completed successfully (run ${id:0:8}). Use 'nostop clean ${id:0:8}' to rerun." >&2
+      exit 0
+    fi
+    if [ "$st" = "running" ] && kill -0 "${pid:-}" 2>/dev/null; then
+      echo "[nostop] still running (pid $pid). Refusing to start a duplicate." >&2
+      exit 1
+    fi
+  fi
+
+  {
+    echo "id=$id"
+    echo "command=$cmd"
+    echo "cwd=$cwd"
+    echo "started=$(now_iso)"
+    echo "pid=$$"
+    echo "boot_id=$(boot_id)"
+    echo "status=running"
+    echo "argv_b64=${ORIG_ARGV_B64:-}"
+  } > "$META"
+
+  export NOSTOP_RUN_DIR="$RUN_DIR"
+  export NOSTOP_RUN_ID="$id"
+  export PATH="$(dirname "$SELF"):$PATH"
+
+  _on_exit() {
+    local s; s="$(_get_meta "$META" status 2>/dev/null || true)"
+    [ "$s" = "running" ] && _set_meta "$META" status interrupted
+  }
+  _on_sig() { _set_meta "$META" status interrupted; exit 130; }
+  trap '_on_exit' EXIT
+  trap '_on_sig' INT
+  trap '_on_sig' TERM
+
+  echo "[nostop] run ${id:0:8} | cwd=$cwd" >&2
+  echo "[nostop] cmd: $cmd" >&2
+}
+
+run_command() {
+  local cmd="$*"
+  [ -z "$cmd" ] && { usage; exit 2; }
+  begin_run "$cmd"
+  local rc=0
+  run_args "$@" 2>&1 | tee -a "$RUN_DIR/run.log"
+  rc=${PIPESTATUS[0]}
+  if [ "$rc" -eq 0 ]; then
+    _set_meta "$META" status done
+    echo "[nostop] finished successfully." >&2
+  else
+    _set_meta "$META" status failed
+    echo "[nostop] exited with code $rc." >&2
+  fi
+  exit "$rc"
+}
+
+# ---------- batch ----------
+# Expand a template against one entry. Entry is split on ':' into fields.
+# {N} -> N-th field (1-indexed); {} -> the whole entry.
+expand_template() {
+  local tpl="$1" entry="$2"
+  local IFS=':'
+  local -a fields=($entry)
+  local result="$tpl" i f n=${#fields[@]}
+  for ((i=1; i<=n; i++)); do
+    f="${fields[$((i-1))]}"
+    result="${result//\{$i\}/$f}"
+  done
+  result="${result//\{\}/$entry}"
+  printf '%s' "$result"
+}
+
+batch_cmd() {
+  if [ "$#" -eq 0 ]; then echo "usage: nostop batch <template> <entry> [<entry>...]" >&2; exit 2; fi
+  local template="$1"; shift
+  [ -z "$template" ] && { echo "usage: nostop batch <template> <entry> [<entry>...]" >&2; exit 2; }
+  [ "$#" -eq 0 ] && { echo "nostop batch: no entries given" >&2; exit 2; }
+  local entries=("$@")
+  local CMD="batch $template${entries[*]:+ ${entries[*]}}"
+  begin_run "$CMD"
+  # Mirror all output (incl. nested step output) into the run log.
+  exec > >(tee -a "$RUN_DIR/run.log") 2>&1
+  local entry key concrete rc
+  for entry in "${entries[@]}"; do
+    key="$entry"
+    concrete="$(expand_template "$template" "$entry")"
+    echo "[nostop] === entry: $key ===" >&2
+    echo "[nostop] cmd : $concrete" >&2
+    # Each entry is one checkpoint: completed entries are skipped on rerun.
+    bash "$SELF" step "$key" -- "$concrete"; rc=$?
+    if [ "$rc" -ne 0 ]; then
+      echo "[nostop] entry '$key' failed (exit $rc); stopping batch so you can resume." >&2
+      _set_meta "$META" status failed
+      exit "$rc"
+    fi
+  done
+  _set_meta "$META" status done
+  echo "[nostop] batch finished successfully (${#entries[@]} entries)." >&2
+  exit 0
+}
+
+# ---------- step / mark / done (checkpoint API) ----------
+step_cmd() {
+  local name="$1"; shift
+  [ "$1" = "--" ] && shift
+  [ -z "$name" ] && { echo "usage: nostop step <name> -- <command...>" >&2; exit 2; }
+  local rd="${NOSTOP_RUN_DIR:-}"
+  if [ -z "$rd" ]; then
+    run_args "$@"; exit "$?"   # standalone: just run, no tracking
+  fi
+  if grep -qxF "$name" "$rd/checkpoints" 2>/dev/null; then
+    echo "[nostop] skip step '$name' (already done)" >&2
+    exit 0
+  fi
+  echo "[nostop] run step '$name' ..." >&2
+  run_args "$@"; local rc=$?
+  if [ "$rc" -eq 0 ]; then
+    printf '%s\n' "$name" >> "$rd/checkpoints"
+    echo "[nostop] step '$name' done" >&2
+  else
+    echo "[nostop] step '$name' failed (exit $rc), not marked" >&2
+  fi
+  exit "$rc"
+}
+
+mark_cmd() {
+  local rd="${NOSTOP_RUN_DIR:-}"
+  [ -z "$rd" ] && { echo "nostop mark: not inside a nostop run" >&2; exit 1; }
+  printf '%s\n' "$1" >> "$rd/checkpoints"
+}
+
+done_cmd() {
+  local rd="${NOSTOP_RUN_DIR:-}"
+  [ -z "$rd" ] && exit 1
+  grep -qxF "$1" "$rd/checkpoints" 2>/dev/null
+}
+
+# ---------- stats / show / resume / clean ----------
+stats_cmd() {
+  local all=0
+  [ "${1:-}" = "--all" ] && all=1
+  local any=0
+  printf '%-10s %-12s %s\n' "ID" "STATUS" "COMMAND"
+  local m
+  for m in "$RUNS_DIR"/*/meta; do
+    [ -f "$m" ] || continue
+    local id cmd cwd st pid bid disp lastck
+    id="$(_get_meta "$m" id || true)"
+    cmd="$(_get_meta "$m" command || true)"
+    cwd="$(_get_meta "$m" cwd || true)"
+    st="$(_get_meta "$m" status || true)"
+    pid="$(_get_meta "$m" pid || true)"
+    bid="$(_get_meta "$m" boot_id || true)"
+    disp="$(compute_status "$st" "$pid" "$bid")"
+    [ "$all" -eq 0 ] && [ "$disp" = "DONE" ] && continue
+    any=1
+    lastck="$(tail -n1 "${m%/meta}/checkpoints" 2>/dev/null)"
+    printf '%-10s %-12s %s\n' "${id:0:8}" "$disp" "$cmd"
+    printf '%-10s %-12s cwd: %s\n' "" "" "$cwd"
+    [ -n "$lastck" ] && printf '%-10s %-12s last checkpoint: %s\n' "" "" "$lastck"
+  done
+  [ "$any" -eq 0 ] && echo "(no runs found)"
+}
+
+show_cmd() {
+  local id="$1"; [ -z "$id" ] && { echo "usage: nostop show <id>" >&2; exit 2; }
+  local meta; meta="$(ls -d "$RUNS_DIR"/"$id"*/meta 2>/dev/null | head -1)"
+  [ -f "$meta" ] || { echo "no run matching '$id'" >&2; exit 1; }
+  cat "$meta"
+  echo "---- last output (tail) ----"
+  tail -n 20 "${meta%/meta}/run.log" 2>/dev/null
+}
+
+resume_cmd() {
+  local id="$1"; [ -z "$id" ] && { echo "usage: nostop resume <id>" >&2; exit 2; }
+  local meta; meta="$(ls -d "$RUNS_DIR"/"$id"*/meta 2>/dev/null | head -1)"
+  [ -f "$meta" ] || { echo "no run matching '$id'" >&2; exit 1; }
+  local cmd cwd argv_b64 a argv
+  cmd="$(_get_meta "$meta" command || true)"
+  cwd="$(_get_meta "$meta" cwd || true)"
+  argv_b64="$(_get_meta "$meta" argv_b64 || true)"
+  cd "$cwd" 2>/dev/null || { echo "cannot cd to '$cwd'" >&2; exit 1; }
+  # Replay the exact argv if available (preserves spaces-in-args),
+  # otherwise fall back to the joined command string.
+  if [ -n "$argv_b64" ]; then
+    argv=()
+    while IFS= read -r -d '' a; do argv+=("$a"); done < <(printf '%s' "$argv_b64" | base64 -d)
+    exec "$SELF" "${argv[@]}"
+  else
+    exec "$SELF" "$cmd"
+  fi
+}
+
+clean_cmd() {
+  if [ "${1:-}" = "--all" ]; then rm -rf "$RUNS_DIR"/*; echo "cleared all runs"; return; fi
+  local id="$1"; [ -z "$id" ] && { echo "usage: nostop clean [--all|<id>]" >&2; exit 2; }
+  local d; d="$(ls -d "$RUNS_DIR"/"$id"* 2>/dev/null | head -1)"
+  [ -d "$d" ] || { echo "no run matching '$id'" >&2; exit 1; }
+  rm -rf "$d"; echo "removed $d"
+}
+
+# ---------- dispatch ----------
+main() {
+  ORIG_ARGV_B64="$(printf '%s\0' "$@" | base64 | tr -d '\n')"
+  case "${1:-}" in
+    ""|-h|--help|help) usage; exit 0 ;;
+    stats)  shift; stats_cmd "$@" ;;
+    show)   shift; show_cmd "$@" ;;
+    resume) shift; resume_cmd "$@" ;;
+    clean)  shift; clean_cmd "$@" ;;
+    batch)  shift; batch_cmd "$@" ;;
+    step)   shift; step_cmd "$@" ;;
+    mark)   shift; mark_cmd "$@" ;;
+    done)   shift; done_cmd "$@" ;;
+    --)     shift; run_command "$@" ;;
+    *)      run_command "$@" ;;
+  esac
+}
+
+main "$@"

nostop_cli-0.1.0/src/nostop_cli.egg-info/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: nostop-cli
+Version: 0.1.0
+Summary: Resume-capable command wrapper for Linux: rerun interrupted commands and skip completed steps.
+Author: nostop
+License-Expression: MIT
+Project-URL: Homepage, https://example.com/nostop
+Keywords: cli,resume,checkpoint,pipeline,bioinformatics
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Console
+Classifier: Topic :: System :: Shells
+Classifier: Programming Language :: Unix Shell
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nostop
+
+一个极小的 Linux 命令行工具，用于**包装并执行任意命令**，并在命令因断网、断电、
+崩溃等任何原因中断后，能够**从中断处继续**，避免从头重跑浪费时间。
+
+```bash
+nostop <命令>          # 运行 / 续跑一条命令
+nostop stats           # 查看此前中断的命令（命令内容 + 中断时的工作目录）
+```
+
+---
+
+## 它解决什么问题
+
+- 跑了 6 个小时的生信流程，第 5 步时断电 / 断网 / 节点被回收，重跑又要 6 小时。
+- 写了一个多步骤的 shell 流程，中途失败，希望**已完成的步骤不要再跑**。
+
+nostop 的价值：
+
+1. **通用**：`nostop <任意命令>` 的行为与直接执行该命令完全一致（输出、退出码、环境都透传）。
+2. **可续跑**：中断后再次运行**完全相同**的 `nostop <命令>`（同一工作目录），工具会识别已完成的
+   进度并跳过，从断点继续。
+3. **可查询**：`nostop stats` 列出此前中断的命令，含命令内容与其**中断时所在路径（cwd）**，
+   方便你回到原目录重新启动。
+4. **简约**：单个 bash 脚本，无编译、无依赖、无守护进程、无数据库；体积几 KB，运行时几乎零开销。
+5. **支持广**：既支持“多步骤 shell 脚本”（用 checkpoint API 精确跳过步骤），也支持“单个长时间
+   运行的程序”（如 megahit 等自带断点续跑能力的二进制，nostop 负责用完全相同的方式重新拉起它）。
+
+---
+
+## 安装
+
+### 方式一：pip 安装（推荐）
+
+本工具已打包为 Python 项目，可直接用 pip 从源码或你们内部的 PyPI 源安装：
+
+```bash
+# 从本地源码目录安装
+pip install .
+
+# 或打包后安装（生成 dist/nostop-cli-*.whl / tar.gz）
+pip install build
+python -m build
+pip install dist/nostop-cli-*.whl
+
+# 如需发布到你们内部的 PyPI 或公开 PyPI：
+twine upload dist/*
+# 之后他人即可：pip install nostop-cli   （命令名仍是 nostop）
+```
+
+安装后 `nostop` 命令即可用（其实质是一个极薄的 Python 入口，启动后立刻 exec
+到内置的 bash 脚本，运行时不依赖 Python）。也可用 `python -m nostop ...` 运行。
+
+### 方式二：单文件拷贝（零依赖，连 Python 都不需要）
+
+如果你只想用一个文件、连 Python 环境都不想依赖，直接复制内置脚本即可
+（依赖系统自带的 bash 与 coreutils，CentOS / Ubuntu 等主流发行版默认都有）：
+
+```bash
+sudo cp src/nostop/nostop.sh /usr/local/bin/nostop
+sudo chmod +x /usr/local/bin/nostop
+
+# 可选：自定义状态目录（默认 ~/.nostop）
+# export NOSTOP_HOME=/data/.nostop
+```
+
+验证：`nostop help`
+
+---
+
+## 快速开始
+
+```bash
+# 像平常一样运行命令，只是前面加 nostop
+nostop "bash my_pipeline.sh"
+
+# 中断后，回到同一个目录，原样再敲一次即可续跑
+nostop "bash my_pipeline.sh"
+
+# 查看哪些命令之前中断了（含命令内容与工作目录）
+nostop stats
+```
+
+---
+
+## 场景一：多步骤 shell 流程（精确到步骤的跳过）
+
+对“脚本里有多个步骤”的情况，使用 nostop 提供的 **checkpoint（检查点）API**。
+在脚本里把每个步骤包成 `nostop step <名字> -- <命令>`：
+
+```bash
+#!/bin/bash
+# my_pipeline.sh
+nostop step prepare  -- "echo 准备数据 && sleep 2"
+nostop step align    -- "echo 比对 && sleep 2"
+nostop step call     -- "echo 变异检测 && sleep 2"
+nostop step report   -- "echo 出报告"
+echo "全部完成"
+```
+
+运行：
+
+```bash
+nostop "bash my_pipeline.sh"
+```
+
+- 第一次正常运行，每完成一步就记录一个检查点。
+- 中途断电/被杀：再次 `nostop "bash my_pipeline.sh"` 时，已完成的步骤会被**自动跳过**
+  （输出 `[nostop] skip step 'prepare' (already done)`），直接从断点继续。
+- 步骤失败（退出码非 0）不会被标记为完成，下次会自动重跑该步骤。
+
+> 如果你的步骤本身是一条带管道 / 重定向的复杂命令，可以写成单个字符串：
+> `nostop step build -- "make && make test | tee build.log"`。
+
+手动控制检查点（更灵活）：
+
+| 写法 | 作用 |
+| --- | --- |
+| `nostop step <名字> -- <命令>` | 运行命令；成功则标记 `<名字>` 完成，下次跳过 |
+| `nostop done <名字>` | 退出码 0 表示该检查点已完成，否则 1（用于 `if` 判断） |
+| `nostop mark <名字>` | 直接把 `<名字>` 标记为完成 |
+
+例如在脚本里手写分支：
+
+```bash
+if nostop done align; then
+  echo "比对已完成，跳过"
+else
+  do_align && nostop mark align
+fi
+```
+
+> 注意：checkpoint API 只在 `nostop <命令>` 内部才记录进度；直接 `bash my_pipeline.sh`
+> 运行时它会退化为“直接执行”，不影响结果，只是不记录进度。
+
+---
+
+## 场景二：单个长时间运行的程序（如 megahit）
+
+很多生信程序（megahit、Trinity、SPAdes 等）**自身就支持断点续跑**——只要用相同的输出目录
+重新运行，它们会接着上次的产物继续。nostop 在这里的作用是：**用完全相同的方式重新拉起命令，
+并替你记录状态 / 方便重跑**。
+
+```bash
+# 第一次运行
+nostop "megahit -1 read1.fq -2 read2.fq -o mega.out"
+
+# 中断后，回到同一目录，原样再敲一次；megahit 会基于 mega.out 里已有的中间文件续跑
+nostop "megahit -1 read1.fq -2 read2.fq -o mega.out"
+```
+
+nostop 本身对“单个二进制内部进度”无感知（那是程序自己的事），但它保证：
+- 用**完全相同的命令字符串与工作目录**重启；
+- 把这次运行登记到状态库，供 `nostop stats` 查看；
+- 程序成功跑完（退出码 0）后记为 `DONE`，之后原样再跑会被直接跳过，不会重复计算。
+
+> 如果程序需要显式续跑参数（例如某些工具要用 `--continue` / `-c`），把它写进命令里即可，
+> 因为 nostop 是“原样重放”。
+
+## 场景三：批处理（nostop batch）
+
+当同一道命令要对多组输入分别跑一遍（例如多个样本分别做 fastp / spades），用 `nostop batch`
+一次性提交。它把每条输入展开到模板里，并把**每条输入当作一个检查点**——中断后续跑时，
+已完成的样本会被自动跳过。
+
+模板占位符：
+
+- `{N}`：第 N 个字段（从 1 起），输入按 `:` 切分。例 `s1_1.fq:s1_2.fq` → `{1}=s1_1.fq`、`{2}=s1_2.fq`。
+- `{}`：整条输入原文（含 `:`）。
+
+```bash
+# 双端配对（{1}/{2} 占位）
+nostop batch "fastp -i {1} -I {2} -o {1}.clean.fq -O {2}.clean.fq" s1_1.fq:s1_2.fq s2_1.fq:s2_2.fq
+
+# 工具无续跑参数时，结合幂等写法最稳（重跑时已完成的组装直接跳过）
+nostop batch "[ -s asm_{}/final.contigs.fa ] || spades.py -1 {1} -2 {2} -o asm_{}" s1_1.fq:s1_2.fq s2_1.fq:s2_2.fq
+```
+
+- 每条输入即 `nostop step <输入>` 检查点，状态同样出现在 `nostop stats`。
+- 某个样本失败，batch 会停下（不再跑后续），修好后重跑即可；已完成样本自动跳过。
+- `{}` 是整条输入原文（如 `s1_1.fq:s1_2.fq`），故 `asm_{}` 目录名会带冒号（Linux 下合法）；
+  想要干净目录名时，把样本名单独作为条目传入、用 `{1}/{2}` 拼文件路径即可。
+
+---
+
+## 子命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `nostop <命令>` | 运行 / 续跑一条命令 |
+| `nostop batch <模板> <条目>...` | 对每条条目展开模板并分别运行，已完成的跳过 |
+| `nostop stats [--all]` | 列出**中断 / 失败 / 正在运行**的命令；`--all` 同时显示已完成的 |
+| `nostop show <id>` | 查看某条运行的详情（命令、目录、开始时间、尾部输出） |
+| `nostop resume <id>` | 在原始工作目录下，重新运行该命令（不用再手敲整条命令） |
+| `nostop clean [--all|<id>]` | 清除某条（或全部）运行的状态；用于需要强制重跑时 |
+| `nostop step/mark/done <名字>` | 见上文 checkpoint API |
+| `nostop help` | 帮助 |
+
+`stats` 示例输出：
+
+```
+ID         STATUS       COMMAND
+97ecb77e   INTERRUPTED  bash my_pipeline.sh
+                        cwd: /home/user/project
+                        last checkpoint: align
+```
+
+- `ID` 是状态库里的短标识，可直接用于 `nostop show <id>` / `nostop resume <id>` / `nostop clean <id>`。
+- `STATUS` 取值：`RUNNING`（仍在跑） / `INTERRUPTED`（被中断，最常见：断电、被杀、崩溃） /
+  `FAILED`（命令自身非零退出） / `DONE`（已成功完成）。
+
+---
+
+## 工作原理（如何检测“中断”）
+
+状态保存在 `$NOSTOP_HOME/runs/<hash>/`，其中 `<hash>` 由 **命令字符串 + 当前工作目录** 计算。
+每次运行写入 `meta` 文件，记录 `status`（初始 `running`）、`pid`、`boot_id`（来自
+`/proc/sys/kernel/random/boot_id`）、命令、目录等。
+
+- 命令**成功退出** -> `status=done`；**非零退出** -> `status=failed`。
+- 若进程被 **SIGINT/SIGTERM** 终止 -> 捕获后记为 `interrupted`。
+- 若机器**断电 / 崩溃**（nostop 来不及响应）-> `meta` 仍停留在 `running`，
+  且记录的 `pid` 已不存在（或 `boot_id` 与本次启动不一致）-> 查询时判定为 `INTERRUPTED`。
+
+因此 `nostop stats` 能可靠区分“正在跑”、“被中断”、“已成功”、“已失败”。
+
+---
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `NOSTOP_HOME` | `~/.nostop` | 状态库根目录，可指向大容量磁盘 |
+
+---
+
+## 兼容性与限制
+
+- **兼容性**：纯 bash + coreutils（`sha256sum`/`date`/`kill`/`tee`），CentOS 7/8、Ubuntu 20.04/22.04
+  等主流发行版开箱即用；仅依赖 Linux 的 `/proc/sys/kernel/random/boot_id`（缺失时退化为仅按 PID 判断）。
+- **限制**：
+  - 对“单个不自带续跑能力的黑盒二进制”，nostop 只能保证原样重放，无法替它在内部续跑；
+    这类场景请用脚本 + `nostop step` 拆成可重入的步骤，或选用自带续跑的程序。
+  - 检查点跳过依赖**步骤本身是可重入 / 幂等**的；请确保重试某步不会造成破坏。
+  - 同一“命令 + 目录”被视为同一次运行；若想以不同参数再跑一份，请换目录或改命令。
+- **已知命令已 DONE 时**再原样运行会被直接跳过（输出提示）。需要强制重跑请先 `nostop clean <id>`。
+
+---
+
+## 文件结构
+
+```
+nostop            # 工具本体（单文件，拷贝即用）
+README.md         # 本文档
+examples/         # 示例脚本
+  pipeline.sh     # 场景一：带 checkpoint 的多步骤流程
+  megahit.sh      # 场景二：单个长时间程序续跑示例
+```

nostop_cli-0.1.0/src/nostop_cli.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/nostop/__init__.py
+src/nostop/__main__.py
+src/nostop/cli.py
+src/nostop/nostop.sh
+src/nostop_cli.egg-info/PKG-INFO
+src/nostop_cli.egg-info/SOURCES.txt
+src/nostop_cli.egg-info/dependency_links.txt
+src/nostop_cli.egg-info/entry_points.txt
+src/nostop_cli.egg-info/top_level.txt

nostop_cli-0.1.0/src/nostop_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nostop_cli-0.1.0/src/nostop_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nostop = nostop.cli:main

nostop_cli-0.1.0/src/nostop_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+nostop