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），若未设置则需要向用户确认保存路径