alnkit 0.1.0__py3-none-any.whl

alnkit/__init__.py

@@ -0,0 +1,11 @@
+"""alnkit：比对结果中外源插入（及未来结构变异）的证据提取与可视化。
+
+已迁入老三套流程的全部命令：三代（A1–A7）、二代（B1/B2）、绘图（C1/C2），
+并提供坐标/表契约层与 `alnkit selftest`。
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

alnkit/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m alnkit`` 等价于 ``alnkit``。"""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

alnkit/_docs.py

@@ -0,0 +1,52 @@
+"""文档生成：表契约 → markdown（唯一来源是 ``core.tables``）。
+
+放成私有模块（而不是 ``scripts/`` 里的独立脚本），是为了让测试能直接 import 并校验
+“文档与代码一致”，不必做 sys.path 手脚。
+"""
+
+from __future__ import annotations
+
+from .core import tables
+
+_HEADER = """# 表契约
+
+> 本页由 `alnkit.core.tables` 的 `COLUMNS` / `COLUMN_DOC` 生成，**不要手改**。
+> 重新生成：`python scripts/gen_table_docs.py`。
+
+规则：
+
+- 列序即下表顺序，写表只能通过 `alnkit.core.tables.write_tsv`；
+- 坐标列名必须带 `_0based` / `_1based` 后缀；长度列（`*_bp`、`*_len`、`*_length`、`*_count`）不带；
+- 旧表（legacy `.xls` / 旧 TSV）列名保持不变，由 `--columns legacy:*` 复现；
+- 浮点固定 4 位小数；空值写 `-`。
+"""
+
+
+#: 注册了但还没有生产者的表（文档里要写明，避免用户去找不存在的文件）
+NOT_PRODUCED = frozenset({"insert_sites"})
+
+
+def render_table_docs() -> str:
+    """渲染 docs/concepts/tables.md 的完整内容。"""
+    chunks = [_HEADER]
+    for table, columns in tables.COLUMNS.items():
+        docs = tables.COLUMN_DOC.get(table, {})
+        chunks.append(f"\n## `{table}`\n")
+        if table in NOT_PRODUCED:
+            chunks.append(
+                '!!! warning "尚未实现"\n'
+                "    0.1.0 还没有命令输出这张表；列定义先冻结在这里，计划 0.2 接上。\n"
+            )
+        chunks.append("| # | 列名 | 基准 | 说明 |")
+        chunks.append("|---|---|---|---|")
+        for index, column in enumerate(columns, start=1):
+            if column.endswith("_0based"):
+                basis = "0-based"
+            elif column.endswith("_1based"):
+                basis = "1-based"
+            elif tables.is_coordinate_column(column):  # pragma: no cover - 注册时已拦住
+                basis = "**缺失**"
+            else:
+                basis = "—"
+            chunks.append(f"| {index} | `{column}` | {basis} | {docs.get(column, '')} |")
+    return "\n".join(chunks) + "\n"

alnkit/cli/__init__.py

@@ -0,0 +1,53 @@
+"""命令行入口：``alnkit <command>``。
+
+``doctor`` / ``selftest`` / ``plot tracks`` 已可用；其余分析命令随 P1–P3 迁入。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from .. import __version__
+from ..core import errors
+from . import align, doctor, long, plot, ref, seg, selftest, short
+from ._common import apply_global_options
+
+_COMMANDS = (doctor, selftest, ref, align, seg, plot, short, long)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """构建完整命令树（供 CLI 与文档生成共用）。"""
+    parser = argparse.ArgumentParser(
+        prog="alnkit",
+        description="比对结果中外源插入（及未来结构变异）的证据提取与可视化工具集",
+        epilog="例子：alnkit doctor   |   alnkit selftest   |   alnkit <command> --help",
+    )
+    parser.add_argument("--version", action="version", version=f"alnkit {__version__}")
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+    for module in _COMMANDS:
+        module.add_parser(subparsers)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI 主入口；返回进程退出码。"""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if getattr(args, "command", None) is None:
+        parser.print_help()
+        return 0
+    apply_global_options(args)
+    try:
+        return int(args.handler(args))
+    except errors.AlnkitError as exc:
+        print(f"alnkit {args.command}: {exc}", file=sys.stderr)
+        return exc.exit_code
+    except KeyboardInterrupt:
+        print("已中断", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

alnkit/cli/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m alnkit.cli`` 等价于 ``alnkit``（便于在子进程里调用，不必依赖 PATH）。"""
+
+from __future__ import annotations
+
+import sys
+
+from . import main
+
+if __name__ == "__main__":
+    sys.exit(main())

alnkit/cli/_common.py

@@ -0,0 +1,25 @@
+"""CLI 公共件：解析器骨架、全局参数、统一错误出口。
+
+参数命名规则：kebab-case 长参数，尽量与旧脚本同名（`--min-mapq`、`--merge-window-bp`…），
+迁移期用户只需换命令名。退出码：0 成功 / 1 运行期错误 / 2 参数或前置校验失败。
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ..core.logging import configure
+
+GLOBAL_OPTIONS = argparse.ArgumentParser(add_help=False)
+GLOBAL_OPTIONS.add_argument(
+    "--log-level",
+    default="INFO",
+    choices=("DEBUG", "INFO", "WARNING", "ERROR"),
+    help="日志级别（默认 INFO）",
+)
+GLOBAL_OPTIONS.add_argument("--quiet", action="store_true", help="只输出错误")
+
+
+def apply_global_options(args: argparse.Namespace) -> None:
+    """把全局参数应用到日志系统。"""
+    configure(level=getattr(args, "log_level", "INFO"), quiet=getattr(args, "quiet", False))

alnkit/cli/align.py

@@ -0,0 +1,52 @@
+"""``alnkit align <reads>``：把 reads 比对到合并参考（A2）。"""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import prepare
+from ._common import GLOBAL_OPTIONS
+
+
+def add_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    align = subparsers.add_parser(
+        "align",
+        help="比对（reads -> 合并参考）",
+        description="调用 minimap2 + samtools 的薄封装；需要它们装在 PATH 里。",
+    )
+    sub = align.add_subparsers(dest="align_command", metavar="<subcommand>")
+    sub.required = True
+
+    parser = sub.add_parser(
+        "reads",
+        parents=[GLOBAL_OPTIONS],
+        help="长读长 reads -> sorted BAM（-ax map-hifi -Y -N 50）",
+        description=(
+            "等价于旧 shell：minimap2 建 .mmi -> minimap2 -ax map-hifi -Y -N 50 -> "
+            "samtools sort -> samtools index。"
+        ),
+        epilog=(
+            "例子：alnkit align reads --reference 01_merge_ref/merged_reference.fa \\\n"
+            "          --reads input.fastq --outdir 02_align --threads 12"
+        ),
+    )
+    parser.add_argument("--reference", required=True, help="合并参考 FASTA（需 .fai）")
+    parser.add_argument("--reads", required=True, help="原始 reads（FASTQ/FASTA）")
+    parser.add_argument("--outdir", required=True, help="输出目录")
+    parser.add_argument("--name", default="reads_to_merged", help="输出 BAM 文件名前缀")
+    parser.add_argument("--threads", type=int, default=12, help="线程数（默认 12）")
+    parser.set_defaults(handler=run_align)
+
+
+def run_align(args: argparse.Namespace) -> int:
+    result = prepare.align_reads(
+        prepare.AlignSettings(
+            reference=args.reference,
+            reads=args.reads,
+            outdir=args.outdir,
+            name=args.name,
+            threads=args.threads,
+        )
+    )
+    print(f"完成：{result['bam']}")
+    return 0

alnkit/cli/doctor.py

@@ -0,0 +1,81 @@
+"""``alnkit doctor``：打印运行环境，缺什么就说什么。"""
+
+from __future__ import annotations
+
+import argparse
+import platform
+from importlib.metadata import PackageNotFoundError, version
+
+from .. import __version__
+from ..core import errors
+from ..core.external import ALIGNERS, REFERENCE_TOOLS, find_tool
+from ._common import GLOBAL_OPTIONS
+
+_REQUIRED_PACKAGES = ("pysam",)
+_OPTIONAL_PACKAGES = (("matplotlib", "绘图子命令 alnkit plot *"),)
+
+
+def add_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "doctor",
+        parents=[GLOBAL_OPTIONS],
+        help="检查运行环境（Python / 依赖 / 外部命令）",
+        description="打印版本与可用性；必需项缺失时以退出码 1 结束。",
+        epilog="例子：alnkit doctor",
+    )
+    parser.set_defaults(handler=run)
+
+
+def _package_version(name: str) -> str | None:
+    try:
+        return version(name)
+    except PackageNotFoundError:
+        return None
+
+
+def run(args: argparse.Namespace) -> int:
+    del args  # doctor 不使用全局参数以外的入参
+    rows: list[tuple[str, str, str]] = []
+    rows.append(("alnkit", __version__, "必需"))
+    rows.append(("python", platform.python_version(), ">=3.10"))
+
+    missing_required: list[str] = []
+    for name in _REQUIRED_PACKAGES:
+        found = _package_version(name)
+        rows.append((name, found or "缺失", "必需"))
+        if found is None:
+            missing_required.append(name)
+
+    missing_optional: list[str] = []
+    for name, purpose in _OPTIONAL_PACKAGES:
+        found = _package_version(name)
+        rows.append((name, found or "缺失", f"可选：{purpose}"))
+        if found is None:
+            missing_optional.append(name)
+
+    for name in ALIGNERS:
+        tool = find_tool(name)
+        rows.append((name, tool.describe(), "可选：比对（至少装一个）"))
+    for name in REFERENCE_TOOLS:
+        tool = find_tool(name)
+        rows.append((name, tool.describe(), "可选：参考索引 / BAM 处理"))
+
+    width = max(len(name) for name, _, _ in rows)
+    print(f"alnkit {__version__}  平台 {platform.platform()}")
+    print(f"{'组件':<{width}}  版本{'':<38}说明")
+    for name, value, note in rows:
+        print(f"{name:<{width}}  {value:<40}{note}")
+
+    aligners = [name for name in ALIGNERS if find_tool(name).available]
+    if missing_required:
+        raise errors.RunError(
+            "缺少必需依赖：" + ", ".join(missing_required) + "。安装：pip install alnkit"
+        )
+    if missing_optional:
+        print(
+            f"\n提示：未安装 {', '.join(missing_optional)}；"
+            '绘图子命令需要 `pip install "alnkit[plot]"`。'
+        )
+    if not aligners:
+        print(f"\n警告：{'/'.join(ALIGNERS)} 都未找到；分析链路需要用户自行提供 BAM/PAF。")
+    return 0

alnkit/cli/long.py

@@ -0,0 +1,346 @@
+"""长读长子命令：``alnkit long <classify|graph|breakpoints|assemble|locate>``。
+
+目前只有 ``classify``（A3）从旧流程迁入；其余随 P3 补齐。
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ..longread import assemble, breakpoints, classify, graph, locate
+from ._common import GLOBAL_OPTIONS
+
+
+def add_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    long = subparsers.add_parser(
+        "long",
+        help="长读长链路（三代：断点 / 类 / 组装 / 落点）",
+        description="PacBio/ONT 长读长上检测外源插入的结构：先分类，再建断点图与类。",
+    )
+    long_subparsers = long.add_subparsers(dest="long_command", metavar="<subcommand>")
+    long_subparsers.required = True
+    _add_graph(long_subparsers)
+    _add_classify(long_subparsers)
+    _add_breakpoints(long_subparsers)
+    _add_assemble(long_subparsers)
+    _add_locate(long_subparsers)
+
+
+def _add_classify(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "classify",
+        parents=[GLOBAL_OPTIONS],
+        help="目标 reads 分类 + 接头事件/位点/区域聚类",
+        description=(
+            "先按外源证据筛出目标 read，再逐段判定外源/基因组/可疑错配，"
+            "最后把接头事件聚成位点与区域，并导出相关 reads 子集。"
+        ),
+        epilog=(
+            "例子：alnkit long classify --bam reads_to_merged.sorted.bam \\\n"
+            "          --reads input.fastq --merged-fai merged.fa.fai \\\n"
+            "          --exog h301_h --exog h301_l --outdir 03_classify"
+        ),
+    )
+    parser.add_argument("--bam", required=True, help="reads -> 合并参考 的 BAM")
+    parser.add_argument("--reads", required=True, help="原始 fastq")
+    parser.add_argument(
+        "--merged-fai", dest="merged_fai", required=True, help="合并参考 .fai（取序列长度）"
+    )
+    parser.add_argument(
+        "--exog", action="append", default=[], required=True, help="外源序列名，可重复"
+    )
+    parser.add_argument("--outdir", required=True, help="输出目录")
+    parser.add_argument(
+        "--min-mapq", dest="min_mapq", type=int, default=20, help="比对质量下限（默认 20）"
+    )
+    parser.add_argument(
+        "--min-exog-block-bp",
+        dest="min_exog_block_bp",
+        type=int,
+        default=100,
+        help="外源比对段最小长度（默认 100 bp）",
+    )
+    parser.add_argument(
+        "--contig-edge-bp",
+        dest="contig_edge_bp",
+        type=int,
+        default=100,
+        help="contig 两端多近算边缘（默认 100 bp）",
+    )
+    parser.add_argument(
+        "--short-genome-block-bp",
+        dest="short_genome_block_bp",
+        type=int,
+        default=500,
+        help="边缘处基因组段多短算可疑错配（默认 500 bp）",
+    )
+    parser.add_argument(
+        "--junction-max-gap-bp",
+        dest="junction_max_gap_bp",
+        type=int,
+        default=10_000,
+        help="基因组段与外源段在 read 轴上多近算相邻（默认 10 kb）",
+    )
+    parser.add_argument(
+        "--site-gap-bp",
+        dest="site_gap_bp",
+        type=int,
+        default=20,
+        help="同一位点的边界允许错位（默认 20 bp）",
+    )
+    parser.add_argument(
+        "--region-gap-bp",
+        dest="region_gap_bp",
+        type=int,
+        default=200_000,
+        help="同染色体位点归为同一区域的最大间距（默认 200 kb）",
+    )
+    parser.set_defaults(handler=run_classify)
+
+
+def run_classify(args: argparse.Namespace) -> int:
+    settings = classify.ClassifySettings(
+        bam=args.bam,
+        reads=args.reads,
+        merged_fai=args.merged_fai,
+        exog=tuple(args.exog),
+        outdir=args.outdir,
+        min_mapq=args.min_mapq,
+        min_exog_block_bp=args.min_exog_block_bp,
+        contig_edge_bp=args.contig_edge_bp,
+        short_genome_block_bp=args.short_genome_block_bp,
+        junction_max_gap_bp=args.junction_max_gap_bp,
+        site_gap_bp=args.site_gap_bp,
+        region_gap_bp=args.region_gap_bp,
+    )
+    result = classify.run(settings)
+    print(
+        f"完成：总 reads {result['total_reads']}，目标 {result['target_reads']}，"
+        f"位点 {result['sites']}，区域 {result['regions']}；输出 {result['outdir']}"
+    )
+    return 0
+
+
+def _add_breakpoints(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "breakpoints",
+        parents=[GLOBAL_OPTIONS],
+        help="断点图方案 A：紧邻片段断点 + 共享 reads 合并成类",
+        description=(
+            "在 read 轴上按“紧邻片段”定义断点（基因组–外源 = vector S##；"
+            "基因组–基因组 = genome G##a/G##b），两个断点共享 reads >= --min-shared 就合并为一类。"
+        ),
+        epilog=(
+            "例子：alnkit long breakpoints \\\n"
+            "          --segments 03_classify/alignment_segments.tsv \\\n"
+            "          --classification 03_classify/read_classification.tsv \\\n"
+            "          --overlaps 04_overlap/overlap_edges.tsv \\\n"
+            "          --reads 03_classify/related_reads.fastq \\\n"
+            "          --merged-fai merged.fa.fai --outdir 05_breakpoints"
+        ),
+    )
+    parser.add_argument("--segments", required=True, help="alignment_segments.tsv")
+    parser.add_argument("--classification", required=True, help="read_classification.tsv")
+    parser.add_argument("--overlaps", required=True, help="overlap_edges.tsv")
+    parser.add_argument("--reads", required=True, help="related_reads.fastq（输出每类子集用）")
+    parser.add_argument(
+        "--merged-fai", dest="merged_fai", required=True, help="合并参考 .fai（取序列长度）"
+    )
+    parser.add_argument("--outdir", required=True, help="输出目录（建议 05_breakpoints）")
+    parser.add_argument(
+        "--site-gap",
+        dest="site_gap",
+        type=int,
+        default=20,
+        help="同一 site 的边界允许错位（默认 20 bp）",
+    )
+    parser.add_argument(
+        "--min-shared",
+        dest="min_shared",
+        type=int,
+        default=2,
+        help="合并断点所需最少共享 reads（默认 2）",
+    )
+    parser.set_defaults(handler=run_breakpoints)
+
+
+def run_breakpoints(args: argparse.Namespace) -> int:
+    settings = breakpoints.BreakpointSettings(
+        segments=args.segments,
+        classification=args.classification,
+        overlaps=args.overlaps,
+        reads=args.reads,
+        merged_fai=args.merged_fai,
+        outdir=args.outdir,
+        site_gap=args.site_gap,
+        min_shared=args.min_shared,
+    )
+    result = breakpoints.run(settings)
+    print(
+        f"完成：断点 {result['sites']} 个，类 {result['classes']} 个，"
+        f"segment_ends {result['segment_ends']} 行；输出 {result['outdir']}"
+    )
+    return 0
+
+
+def _add_assemble(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "assemble",
+        parents=[GLOBAL_OPTIONS],
+        help="按 overlap 关系贪心延伸组装每个类",
+        description=(
+            "每个类先拿一条最长的接头 read 作种子，再从 overlap 边里反复挑一条能往"
+            "左/右延伸的 read，把非重叠悬垂序列接到 contig 两端。"
+        ),
+        epilog=(
+            "例子：alnkit long assemble \\\n"
+            "          --classes-dir 05_breakpoints/classes \\\n"
+            "          --paf 04_overlap/overlaps.paf --outdir 06_assembly"
+        ),
+    )
+    parser.add_argument(
+        "--classes-dir", dest="classes_dir", required=True, help="05_breakpoints/classes"
+    )
+    parser.add_argument("--paf", required=True, help="all-vs-all PAF")
+    parser.add_argument("--outdir", required=True, help="输出目录")
+    parser.add_argument(
+        "--min-overlap",
+        dest="min_overlap",
+        type=int,
+        default=500,
+        help="延伸所需最小 overlap（默认 500 bp）",
+    )
+    parser.add_argument(
+        "--min-identity",
+        dest="min_identity",
+        type=float,
+        default=0.90,
+        help="延伸所需最小一致率（默认 0.90）",
+    )
+    parser.add_argument(
+        "--agreement-bp",
+        dest="agreement_bp",
+        type=int,
+        default=200,
+        help="多个邻居给出同一位置时允许的起点差（默认 200 bp）",
+    )
+    parser.set_defaults(handler=run_assemble)
+
+
+def run_assemble(args: argparse.Namespace) -> int:
+    settings = assemble.AssembleSettings(
+        classes_dir=args.classes_dir,
+        paf=args.paf,
+        outdir=args.outdir,
+        min_overlap=args.min_overlap,
+        min_identity=args.min_identity,
+        agreement_bp=args.agreement_bp,
+    )
+    result = assemble.run(settings)
+    print(f"完成：{result['classes']} 个类，{result['contigs']} 条 contig；输出 {result['outdir']}")
+    return 0
+
+
+def _add_locate(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "locate",
+        parents=[GLOBAL_OPTIONS],
+        help="50 bp 断点锚点 + 外源查询 -> 丝带图 + 参考坐标还原",
+        description=(
+            "为每个类构造查询序列（断点旁 50 bp 锚点 + 全部外源），与类组装比对后逐条 contig 出图，"
+            "并把锚点/外源在 contig 上的落点还原成参考基因组坐标。"
+        ),
+        epilog=(
+            "例子：alnkit long locate \\\n"
+            "          --regions 05_breakpoints/breakpoint_classes.tsv \\\n"
+            "          --sites 05_breakpoints/breakpoint_sites.tsv \\\n"
+            "          --reference-fasta reference.fa \\\n"
+            "          --exog exog/h301_h.fa --exog exog/h301_l.fa \\\n"
+            "          --assembly-dir 06_assembly --outdir 07_ribbon_positions"
+        ),
+    )
+    parser.add_argument("--regions", required=True, help="breakpoint_classes.tsv")
+    parser.add_argument("--sites", required=True, help="breakpoint_sites.tsv")
+    parser.add_argument(
+        "--reference-fasta",
+        dest="reference_fasta",
+        required=True,
+        help="参考基因组 fasta（需 .fai）",
+    )
+    parser.add_argument(
+        "--exog", action="append", default=[], required=True, help="外源 fasta，可重复"
+    )
+    parser.add_argument("--assembly-dir", dest="assembly_dir", required=True, help="06_assembly")
+    parser.add_argument("--outdir", required=True, help="输出目录")
+    parser.add_argument("--threads", type=int, default=12, help="minimap2 线程数（默认 12）")
+    parser.add_argument(
+        "--flank-bp", dest="flank_bp", type=int, default=50, help="断点锚点长度（默认 50 bp）"
+    )
+    parser.set_defaults(handler=run_locate)
+
+
+def run_locate(args: argparse.Namespace) -> int:
+    settings = locate.LocateSettings(
+        regions=args.regions,
+        sites=args.sites,
+        reference_fasta=args.reference_fasta,
+        exog=tuple(args.exog),
+        assembly_dir=args.assembly_dir,
+        outdir=args.outdir,
+        threads=args.threads,
+        flank_bp=args.flank_bp,
+    )
+    result = locate.run(settings)
+    print(
+        f"完成：{result['classes']} 个类，{result['figures']} 张图，"
+        f"位置行 {result['position_rows']} 行；输出 {result['outdir']}"
+    )
+    return 0
+
+
+def _add_graph(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "graph",
+        parents=[GLOBAL_OPTIONS],
+        help="read-vs-read overlap 边与连通分量",
+        description=(
+            "读 all-vs-all PAF（minimap2 -x ava-pb -c），每对 read 只保留最好的一条 overlap，"
+            "再求全局连通分量。方案 A 的类别由断点共享 reads 决定，这里只用于观察 overlap 结构。"
+        ),
+        epilog=(
+            "例子：minimap2 -x ava-pb -c -t 8 related.fastq related.fastq > overlaps.paf\n"
+            "     alnkit long graph --paf overlaps.paf \\\n"
+            "          --classification 03_classify/read_classification.tsv --outdir 04_overlap"
+        ),
+    )
+    parser.add_argument("--paf", required=True, help="all-vs-all PAF（minimap2 -x ava-pb -c）")
+    parser.add_argument("--classification", required=True, help="read_classification.tsv")
+    parser.add_argument("--outdir", required=True, help="输出目录")
+    parser.add_argument(
+        "--min-overlap",
+        dest="min_overlap",
+        type=int,
+        default=300,
+        help="边所需最小 overlap（默认 300 bp）",
+    )
+    parser.add_argument(
+        "--min-identity",
+        dest="min_identity",
+        type=float,
+        default=0.85,
+        help="边所需最小一致率（默认 0.85）",
+    )
+    parser.set_defaults(handler=run_graph)
+
+
+def run_graph(args: argparse.Namespace) -> int:
+    settings = graph.GraphSettings(
+        paf=args.paf,
+        classification=args.classification,
+        outdir=args.outdir,
+        min_overlap=args.min_overlap,
+        min_identity=args.min_identity,
+    )
+    result = graph.run(settings)
+    print(f"完成：overlap 边 {result['edges']} 条，连通分量 {result['components']} 个")
+    return 0