JMComic Agent CLI

面向 AI Agent 和自动化脚本的 JMComic 命令行工具。项目第一次公开发布即为 JS/Node 版本，目标是提供一个可以从源码构建、输出结构化 JSON、方便 Agent 调用的本地 CLI。

English README

当前状态

• 包名预留：jm-agent-cli
• CLI 命令：jm-agent
• 运行环境：Node.js >=20
• 支持平台：JMComic
• 当前没有发布到 npm registry
• 当前使用方式：从源码构建或本地 npm link

功能

• config：查看默认参数、数据目录、状态目录和 provider 能力。
• auth login/status/logout：登录 JMComic，保存 JWT session，不保存明文密码。
• library favorites：读取登录账号的收藏列表，支持过滤、排序和 JSON 缓存。
• library sync：执行收藏夹目录和逐收藏夹云同步，写入本地 SQLite。
• discover：按关键词或标签搜索，按比例生成适合 Agent 阅读的一批候选，支持稳定 cursor 继续看下一批。
• resolve：返回一批更聚焦的高置信候选，不再默认只拍板 1 本，也支持稳定 cursor 继续看下一批。
• comments：读取本子的评论文本，自动清洗 HTML 标记，保留主评论与子评论层级，并压缩成 500 字内树状文本。
• browse latest/weekly/random：支持最近更新、周榜和随机抽一本这类无关键词浏览入口。
• preview：支持正文页预览和轻量封面预览，封面模式支持高并发批量拉取，默认展示带红色序号的封面图。
• download：按 id 或查询生成下载计划，也可执行下载，支持多本并发和单本页图并发。
• download --resume-manifest：从旧 manifest 恢复下载。
• download --failed-pages-only：只重试 manifest 中记录的失败页。
• package：将图片目录或 manifest 打包为 ZIP、CBZ、PDF，支持批量并发转 PDF，默认压缩档位为 small。

默认所有运行产物会写入同级数据目录：

JM Agent CLI Data/

包括下载图片、manifest、报告、收藏缓存和登录 session。

从源码构建

当前还没有公开 npm 包，因此不要使用：

npm install -g jm-agent-cli

请从源码安装依赖并运行：

git clone https://github.com/rmtd418/JMComic-Agent-CLI.git
cd JMComic-Agent-CLI
npm install
node .\bin\jm-agent.js config --json

本地链接为命令：

npm link
jm-agent config --json

本地打包安装：

npm pack
npm install -g .\jm-agent-cli-0.1.0.tgz
jm-agent config --json

AI Skill

仓库提供一个给 AI Agent 使用的英文 skill：

skills/comic-downloader-cli/SKILL.md

这个 skill 只记录漫画搜索、收藏、预览、下载、恢复和打包的常用命令，不提供任何安装方式，也不会打进 npm 包。需要使用时，请把整个 skills/comic-downloader-cli 文件夹拖到对应 Agent 软件的 skills 目录中。不同 Agent 软件的 skills 目录位置不同，请按你自己的软件规则放置。

常用命令

jm-agent config --json
jm-agent auth login --provider jm --json
jm-agent auth status --provider jm --json
jm-agent comments --provider jm --id 1429850 --json
jm-agent browse latest --provider jm --json
jm-agent browse weekly --provider jm --json
jm-agent browse random --provider jm --from latest --json
jm-agent library sync --provider jm --json
jm-agent library favorites --provider jm --limit 5 --json
jm-agent discover --provider jm --query love --profile balanced --exposure 20 --json
jm-agent discover --provider jm --query love --profile balanced --exposure 20 --cursor "<token>" --json
jm-agent resolve --provider jm --query love --profile deep --exposure 20 --json
jm-agent preview --provider jm --id 1429850,1430127 --mode cover --json
jm-agent preview --provider jm --id 1429850 --pages 1 --package pdf --pdf-quality small --json
jm-agent download --provider jm --id 1429850,1430127 --execute --page-limit 1 --json
jm-agent package --input "<manifest.json>" --format cbz --format pdf --pdf-quality small --json

搜索参数概览

默认 profile 是 balanced。

profile	搜索页数	搜索窗口	详情并发
fast	2	160	6
balanced	4	320	12
deep	8	640	20

搜索结果现在按两次比例递减处理：

• 第一次：搜索窗口 -> 候选池
• 第二次：候选池 -> AI shortlist

常用输出参数：

• --profile fast|balanced|deep
• --exposure：默认 20，范围 0 ~ 40
• --cursor：优先用于继续同一批固定搜索会话
• --offset：兼容保留，主要用于没有 cursor 时继续下一批
• --pick best|top|recent|random：默认 best。

结果输出现在还有这些固定行为：

• 所有可继续操作的结果列表默认带 index
• 搜索、浏览、预览、下载、收藏相关结果会附带 next_actions
• 搜索结果会返回 cursor.token，优先用它继续翻下一批，保证同一次搜索会话里的结果顺序稳定
• 搜索、浏览、收藏、下载这些 AI 面向结果默认不再暴露原始封面 URL；要展示图片，先走 preview
• 同一组搜索条件有 48 小时搜索去重缓存，重复搜索会优先给没见过的新结果

默认 20% 下的三档结果大致为：

• fast：160 -> 32 -> 6
• balanced：320 -> 64 -> 13
• deep：640 -> 128 -> 26

最终 AI 可见结果保底 6。

验证

离线检查：

npm run verify

在线 JM smoke：

npm run smoke:online

登录、收藏、下载在线验证：

npm run validate:auth-online
npm run validate:favorites-online
npm run validate:download-online
npm run validate:search-preview-online

在线验证会访问 JMComic 网络服务，请只在你确认网络环境和账号状态可用时运行。

免责声明

本项目仅用于技术研究、个人数据整理、自动化工作流实验和合法备份场景。使用者应自行确认所在国家或地区的法律法规、平台服务条款、网络访问规则和内容合规要求。

本项目不提供、托管、分发任何漫画内容，也不鼓励绕过平台限制、传播侵权内容或进行任何违法用途。由于不同地区对相关内容和网络访问的要求差异较大，尤其在中国大陆环境下可能存在额外合规风险，请自行承担使用风险。

项目作者和贡献者不对使用本工具造成的账号风险、网络风险、法律风险、数据损失或第三方损失承担责任。

致谢

感谢以下项目和资料提供的参考价值：

• JMComic-Crawler-Python：JMComic 接口、下载流程和相关生态经验的重要参考。
• Breeze：JMComic API 文档、数据模型和客户端实现参考。

本项目包含 tools/vendor/JmComic.bundle.cjs 作为 JM 请求桥接运行时。后续正式发布 npm 包前，需要继续审查该 vendor bundle 的来源、许可证和再分发风险。

许可证

本项目使用 MIT License。