kmdr - Kmoe 漫画下载器

概述

kmdr 是一个用于从 Kmoe 网站下载漫画的命令行工具。

环境准备

安装：

pip install --pre "kmoe-manga-downloader>=1.4.0.a3,<2.0.0"

验证安装：

kmdr --mode toolcall version

登录（二选一）：

• 推荐：让用户在终端执行 kmdr login -u <username> [-p <password>]，凭证不会暴露给智能体
• 备选：用户提供凭证，智能体执行 kmdr --mode toolcall login -u <username> -p <password>（凭证会出现在对话历史中）

检测登录状态：

kmdr --mode toolcall status

调用方式

所有命令必须使用 --mode toolcall 以获取结构化 JSON 输出。向用户建议手动执行命令时不要包含此参数。

--fast-auth 原则：会话首次命令联网同步凭证，后续只读操作可跳过，写操作不要跳过以确保配额准确。

• 会话首次命令（无论 search / download --explain）→ 不加 --fast-auth
• 后续只读（search、download --explain、progress、config --list、pool list）→ 加 --fast-auth
• 写操作（download、pool add/remove/use、config --set）→ 不加 --fast-auth
• status、login → --fast-auth 对其无效

命令速览

命令	语法	用途
search	kmdr --mode toolcall search <keyword> [-p N] [-m]	搜索漫画
download	kmdr --mode toolcall download -l <url> -v <vol> [--explain|--background]	下载漫画
progress	kmdr --mode toolcall progress <task_id> [--wait N]	查询后台下载进度
login	kmdr --mode toolcall login -u <user> -p <pass>	登录账号
status	kmdr --mode toolcall status	查看配额
pool	kmdr --mode toolcall pool <add|list|use|remove>	管理凭证池
config	kmdr --mode toolcall config <--set|--list|--clear>	管理配置

完整选项见 kmdr --mode toolcall <command> --help。输出格式详见 ./references/output-format.md。

典型工作流

搜索 → 获取详情 → 预估下载计划 → 确认配额 → 启动后台下载 → 响应用户进度查询 → 完成确认

步骤	命令
1. 检查环境	确认安装并登录（见「环境准备」）
2. 搜索漫画	kmdr --mode toolcall search "漫画名称"
3. 获取详情	从搜索结果中取 url 字段（结合 tags 区分语言版本）
4. 预估下载	kmdr --mode toolcall --fast-auth download -l <url> -v <volume> --explain
5. 确认配额	kmdr --mode toolcall --fast-auth status，对比预估消耗决定是否继续
6. 启动后台下载	kmdr --mode toolcall download -l <url> -v <volume> --background（返回 task_id）
7. 响应用户查询	用户询问进度时执行 kmdr --mode toolcall progress <task_id> [--wait N]
8. 完成确认	下载完成后报告结果（成功/失败/跳过数）

实际顺序可能不同，遵循 --fast-auth 原则即可。

后台下载要点

• 预估：先用 --explain 获取下载计划和配额预估（estimate_quota_usage_mb、avai_quota_mb）
• 启动：--background 立即返回 task_id（格式 YYYYMMDD_HHMMSS）和 pid
• 查询：progress <task_id> [--wait N]。用户随口一问用 --wait 0（即时返回），要求等完成用 --wait 60（阻塞等待，完成即返回）
• 判断：通过 data.is_finished 判断——false 进行中（看 data.volumes），true 已完成（看 completed/failed/skipped）
• task_id 是查询进度的唯一凭证，智能体应在会话中记住它；无需主动轮询，仅在用户询问时响应

错误处理

命令通过 code 字段表示状态（0 = 成功）。遇到非 0 的 code 时，必须查阅 错误码文档 获取恢复策略，不可自行猜测处理方式。

注意事项

• 搜索结果中可能存在同名但语言/版本不同的条目。BookInfo.tags 字段包含语言标签（日語/英文，无标签则为中文翻译版）和状态标签（完結/停更），可用于区分和选择
• 下载前检查 dest 配置（kmdr config --list），若未设置则需要向用户确认保存路径