kmdr - Kmoe 漫画下载器

概述

kmdr 是一个用于从 Kmoe 网站下载漫画的命令行工具。此 skill 教导如何使用 kmdr 完成漫画搜索、下载、账号管理等任务。

环境准备

安装 kmdr

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

验证安装：

kmdr --mode toolcall version

如果命令不存在，说明 kmdr 未安装或未添加到 PATH。

登录配置

检测登录状态

kmdr --mode toolcall status

• 返回 code: 0 → 已登录，可继续操作
• 返回 code: 21 或 code: 23 → 未登录或凭证失效，需配置凭证

配置凭证

方式一（推荐）：用户自行登录

在终端中执行：

kmdr login -u <username> [-p <password>]

如果不提供 -p 参数，将交互式提示输入密码。凭证将安全存储在本地配置文件中，不会暴露给智能体。

方式二：智能体代为登录

如果用户确认当前环境安全，可提供用户名和密码，由智能体执行登录命令。

⚠️ 风险提示：凭证将出现在对话历史中，请确认环境安全后再选择此方式。

调用方式

你的所有命令都应使用 --mode toolcall 参数以获取结构化的 JSON 输出：

kmdr --mode toolcall <command> [options]

值得注意的是，当你向用户建议手动执行命令时，不要包含 --mode toolcall 参数，以便用户使用默认的交互式的输出格式。

主要命令

搜索漫画

kmdr --mode toolcall [--fast-auth] search <keyword> [-p <page>] [-m]

• : 搜索关键字（必需）
• -p, --page: 页码，默认为 1
• -m, --minimal: 仅返回书名和链接

使用场景：用户想要搜索特定漫画、查找某作者的作品、发现新漫画。

下载漫画

kmdr --mode toolcall [--fast-auth] download [options]

关键选项：

• -l, --book-url : 漫画详情页 URL
• -d, --dest : 下载保存路径，默认从配置中读取，如果没有配置则是当前目录
• -v, --volume: 指定下载卷号（如 1,2,3 或 1-5 或 all）
• -P, --use-pool: 启用凭证池自动故障转移
• -b, --background: 后台下载，立即返回 task_id 和 PID，配合 progress 查询进度
• --explain: 仅输出下载计划，不执行实际下载

使用场景：用户想要下载指定漫画、批量下载多个卷。推荐使用 --background 后台启动，用户可随时通过 progress 查询进度。

登录和状态

kmdr --mode toolcall login -u <username> -p <password>
kmdr --mode toolcall status

使用场景：用户需要登录账号、查看剩余配额。

凭证池管理

kmdr --mode toolcall pool add -u <username> -p <password>
kmdr --mode toolcall pool list [--refresh]
kmdr --mode toolcall pool use <username>
kmdr --mode toolcall pool remove <username>

使用场景：用户需要管理多个账号、切换默认账号、查看所有账号配额。

配置管理

kmdr --mode toolcall config --set <key>=<value>
kmdr --mode toolcall config --list
kmdr --mode toolcall config --clear

可配置项：dest, proxy, num_workers, retry, callback, format

使用场景：用户需要设置下载路径、配置代理、调整并发数。在更新配置后，请使用 config --list 验证更改是否生效。

输出格式

详细输出格式请参阅 ./references/output-format.md。

结果类型

• {"type": "result", "code": 0, ...}: 最终结果
• {"type": "progress", ...}: 进度更新（仅下载命令）

错误处理

错误通过 code 字段表示，详细状态码请参阅 ./references/error-codes.md。

示例场景

详细示例请参阅 ./assets/examples/ 目录。

典型工作流

1. 检查环境 → 确认已安装并登录（参见"环境准备"）
2. 搜索 → kmdr --mode toolcall --fast-auth search "漫画名称"
3. 获取详情 → 从搜索结果中获取 url 字段
4. 预估下载 → kmdr --mode toolcall --fast-auth download -l -v --explain
5. 确认配额 → 根据预估消耗决定是否继续（若消耗较大需向用户确认）
6. 启动后台下载 → kmdr --mode toolcall --fast-auth download -l -v --background
7. 响应用户查询 → 当用户询问下载进度（如"查询下载进度"）时，使用 progress 命令查询并报告
8. 完成确认 → 下载完成后向用户报告最终结果

后台下载模式

下载任务通常耗时 1-2 分钟（大批量下载可能更长），统一使用后台下载模式，这样可以跟踪进度并向用户报告。

工作流程

步骤 1：预估下载计划

先用 --explain 获取下载计划：

kmdr --mode toolcall --fast-auth download -l <url> -v <volume> --explain

返回信息包括：

• estimate_quota_usage_mb: 预估配额消耗
• avai_quota_mb: 当前可用配额
• to_download: 待下载列表及各卷大小
• skipped: 已存在文件列表

步骤 2：启动后台下载

使用 --background 参数启动后台下载：

kmdr --mode toolcall --fast-auth download -l <url> -v <volume> --background

立即返回：

• task_id: 任务 ID（如 20260415_143000）
• pid: 后台下载进程的 PID

task_id 格式：YYYYMMDD_HHMMSS（时间戳），用于查询任务状态。

将 task_id 返回给用户。告知用户："下载已启动，正在后台进行。您可以随时让我查询进度（例如'查询下载进度'或'查询进度 '）。"

⚠️ task_id 是后续查询进度的唯一凭证。智能体必须在当前会话中牢记 task_id，以便用户后续发起查询时能直接使用，无需用户再次提供。

步骤 3：响应用户的进度查询

本步骤仅为用户主动询问时触发，无需智能体主动轮询。当用户提出"查询下载进度""下载完了吗"或类似请求时，使用 progress 命令：

kmdr --mode toolcall progress <task_id> --wait 15

⚠️ 重要：必须使用 --wait 参数，值至少为 15。--wait 的阻塞行为天然适配"用户提问 → 阻塞等待 → 立即回答"的交互模型。

参数：

• : download --background 返回的任务 ID。如果智能体从上下文中找不到 task_id，可提醒用户提供
• --wait: 阻塞等待时间（秒），至少 15

阻塞行为：

• 命令会阻塞等待，任务完成则立即返回结果
• 如果任务未完成，等待指定时间后返回当前进度

返回格式：统一返回 result 类型：

{"type": "result", "code": 0, "msg": "success", "data": {...}}

判断方式：通过 data.is_finished 判断任务状态：

• is_finished: false → 任务进行中，检查 data.volumes 字段获取各卷进度，告知用户当前进度
• is_finished: true → 任务完成，检查 data 字段获取最终结果（book、total、completed、failed、skipped）

步骤 4：完成确认

当 progress 返回 is_finished: true 时：

1. 向用户报告下载完成
2. 展示 data 字段中的结果：
• book: 漫画名称
• total: 总卷数
• completed: 成功下载数
• failed: 失败数
• skipped: 跳过数
3. 如果有失败，可读取日志文件查看详细错误信息

注意事项

• 后台下载进程独立运行，如果进程意外终止（崩溃、被系统杀掉），下载会中断
• 日志文件存放在系统临时目录，会被系统定期清理
• task_id 是关键信息，智能体应在会话上下文中始终保留；若丢失则提醒用户提供
• 如果下载失败，可以查看日志文件了解详细错误信息
• 智能体无需主动轮询进度，仅在用户询问时响应即可

注意事项

1. 认证要求：大部分操作需要先登录或配置有效的 cookies
2. 配额限制：下载会消耗账号配额，建议在下载前检查配额状态
3. 搜索结果过滤：用户提供的关键词可能会多个相似结果（相同书名），请查看默认的下载路径
• 如果本地有参考 → 自动选择匹配版本
• 如果本地无参考 → 列出选项供用户选择
4. 代理配置：如果遇到被屏蔽的内容，可以单独配置代理：kmdr download -p -l -v

快速参考

| 命令 | 用途 | 示例 |

|------|------|------|

| search | 搜索漫画 | kmdr --mode toolcall [--fast-auth] search "fate" |

| download --explain | 预估下载计划 | kmdr --mode toolcall [--fast-auth] download -l -v --explain |

| download --background | 后台下载 | kmdr --mode toolcall [--fast-auth] download -l -v --background |

| progress | 查询后台任务进度 | kmdr --mode toolcall progress --wait 15 |

| login | 登录账号 | kmdr --mode toolcall login -u user -p pass |

| status | 查看配额 | kmdr --mode toolcall status |

| pool list | 列出凭证 | kmdr --mode toolcall pool list |