| name | kmdr |
| description | Kmoe 漫画下载器。支持搜索漫画、下载漫画、管理凭证池等。当用户想要从 Kmoe 网站下载漫画、搜索漫画、管理下载账号配额时触发此 skill。 Use when this capability is needed. |
| metadata | {"author":"chrisis58"} |
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]
<keyword>: 搜索关键字（必需）-p, --page: 页码，默认为 1-m, --minimal: 仅返回书名和链接
使用场景：用户想要搜索特定漫画、查找某作者的作品、发现新漫画。
下载漫画
kmdr --mode toolcall [--fast-auth] download [options]
关键选项：
-l, --book-url <url>: 漫画详情页 URL-d, --dest <path>: 下载保存路径，默认从配置中读取，如果没有配置则是当前目录-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/ 目录。
典型工作流
- 检查环境 → 确认已安装并登录（参见"环境准备"）
- 搜索 →
kmdr --mode toolcall --fast-auth search "漫画名称"
- 获取详情 → 从搜索结果中获取
url 字段
- 预估下载 →
kmdr --mode toolcall --fast-auth download -l <url> -v <volume> --explain
- 确认配额 → 根据预估消耗决定是否继续（若消耗较大需向用户确认）
- 启动后台下载 →
kmdr --mode toolcall --fast-auth download -l <url> -v <volume> --background
- 响应用户查询 → 当用户询问下载进度（如"查询下载进度"）时，使用
progress 命令查询并报告
- 完成确认 → 下载完成后向用户报告最终结果
后台下载模式
下载任务通常耗时 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 是后续查询进度的唯一凭证。智能体必须在当前会话中牢记 task_id，以便用户后续发起查询时能直接使用，无需用户再次提供。
步骤 3：响应用户的进度查询
本步骤仅为用户主动询问时触发，无需智能体主动轮询。当用户提出"查询下载进度""下载完了吗"或类似请求时，使用 progress 命令：
kmdr --mode toolcall progress <task_id> --wait 15
⚠️ 重要：必须使用 --wait 参数，值至少为 15。--wait 的阻塞行为天然适配"用户提问 → 阻塞等待 → 立即回答"的交互模型。
参数：
<task_id>: 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 时：
- 向用户报告下载完成
- 展示
data 字段中的结果：
book: 漫画名称total: 总卷数completed: 成功下载数failed: 失败数skipped: 跳过数
- 如果有失败，可读取日志文件查看详细错误信息
注意事项
- 后台下载进程独立运行，如果进程意外终止（崩溃、被系统杀掉），下载会中断
- 日志文件存放在系统临时目录，会被系统定期清理
- task_id 是关键信息，智能体应在会话上下文中始终保留；若丢失则提醒用户提供
- 如果下载失败，可以查看日志文件了解详细错误信息
- 智能体无需主动轮询进度，仅在用户询问时响应即可
注意事项
- 认证要求：大部分操作需要先登录或配置有效的 cookies
- 配额限制：下载会消耗账号配额，建议在下载前检查配额状态
- 搜索结果过滤：用户提供的关键词可能会多个相似结果（相同书名），请查看默认的下载路径
- 如果本地有参考 → 自动选择匹配版本
- 如果本地无参考 → 列出选项供用户选择
- 代理配置：如果遇到被屏蔽的内容，可以单独配置代理：
kmdr download -p <proxy_server> -l <url> -v <volume>
快速参考
| 命令 | 用途 | 示例 |
|---|
search | 搜索漫画 | kmdr --mode toolcall [--fast-auth] search "fate" |
download --explain | 预估下载计划 | kmdr --mode toolcall [--fast-auth] download -l <url> -v <volume> --explain |
download --background | 后台下载 | kmdr --mode toolcall [--fast-auth] download -l <url> -v <volume> --background |
progress | 查询后台任务进度 | kmdr --mode toolcall progress <task_id> --wait 15 |
login | 登录账号 | kmdr --mode toolcall login -u user -p pass |
status | 查看配额 | kmdr --mode toolcall status |
pool list | 列出凭证 | kmdr --mode toolcall pool list |
config | 配置设置 | kmdr --mode toolcall config --set dest=/downloads |
Source: chrisis58/kmoe-manga-downloader — distributed by TomeVault.
