Javdb CLI

javdb-cli Operator

本 skill 让 agent 安全、准确地操作 javdb。命令语义以当前安装二进制的 javdb <command> --help 为准；本文件只给出流程、安全边界与易混淆语义。

预检与账号检查

1. 运行 javdb --version。这是唯一默认环境检查；二进制不存在或不可执行时，说明阻塞原因。只有用户明确要求安装或修复时，才阅读 references/install.md，不得猜测安装方式。
2. 不要在每轮会话枚举本地账号。只有认证、默认账号选择或用户明确要求时才运行 javdb auth list；账号存在不代表 token 有效。
3. 仅在确实需要联网验证身份时运行 javdb auth check --json。它不会打印 token，但会发出 API 请求。

不可违反的规则

1. ~/.javdb-cli/auth.json 含用户名、密码与 JWT（支持 POSIX 权限的平台使用 0600）。绝不在 commentary、结果、日志或代码块中回显、总结或转述这些值，也不读取该文件内容来“帮助排错”。
2. 交互式 javdb auth login 仅在用户明确要求且能亲自输入凭据时运行。没有可交互终端时，不启动一个会永久等待的登录进程。
3. 用户已经明确提供用户名和密码并明确要求登录时，才可使用 auth login -u … -p …；执行前说明凭据会进入本次命令的进程参数与记录。不要复述密码。
4. 账号切换/删除、配置写入、观看标记和取消标记都是状态变更。必须有本次操作的明确用户指令；授权不自动延续至后续目标。
5. 不接受 Cookie、浏览器会话或其他网页抓取替代方案。此 CLI 使用 App API；认证或 API 错误应原样说明，不要暗中换数据源、重试或伪造空结果。
6. auto_relogin=true 会在默认账号 JWT 失效时，使用已保存密码静默重登一次。这是持久化配置，只有用户明确要求才可通过 javdb config set auto_relogin true 开启。

操作分级

top250、watched、want、recent、collections 与默认 lists 需要默认登录账号。magnets 与 detail --magnets 无需登录即可使用：有默认账号时携带其 token，token 失效则自动回退匿名请求。

输出与参数控制

1. 先按用户的范围表达请求；仅在该命令 --help 显示 --limit 且用户给出条数时传入正数。不要为节省上下文擅自附加限额、页数、超时或重试次数。
2. 小结果供人阅读时使用默认制表符文本；需要提取 ID、过滤或稳定字段时使用 --json，需要逐条管道信封或 fan-out 结果时使用 --ndjson。显式机器输出 flag 优先于 TTY 人类可读快捷路径。
3. --json 只描述成功输出，并在适用时保留既有 legacy shape；--ndjson 输出可验证的 javdb.pipeline/v1 信封，fan-out 列表/合集结果分别把原始对象放在 data.list/data.entity。先检查命令退出状态；遇到认证、参数、网络或服务端错误时，报告 stderr 的真实原因，不要把它解析成 JSON 或伪装为“无结果”。 列表与合集的 fan-out NDJSON 是有意的 v1 machine-contract 迁移；每个 list/entity 信封必须有非空稳定 ID，缺少 ID 时显式失败，显示名称缺失时 ref 回退到 ID。消费旧聚合数据的程序必须按逐信封结果迁移，legacy 人类输出和显式聚合 --json 保持既有输出 shape；list/entity 缺少稳定 ID 时显式失败。
4. --all 只在用户明确要求完整遍历时使用；它仅出现在实体/合集电影列表等支持的命令上。不要把它加到不支持的命令，也不要猜测 CLI 内部的分页行为。
5. --best 会把 magnets 的结果缩为单个优先项（中字 > HD > 体积）。用户要完整列表时不要添加它。
6. comments 每次只读一个页面，默认第 1 页、每页 20 条；不要为它附加 --all 或自动读取下一页。用户指定页码或条数时，原样传入正数。
7. 影片媒体资产走两步:javdb assets list ABC-123 先看资产(编号只是位置),再用 selector 或 --type 过滤后管道到 javdb assets download。list 默认在最终选择后以有界并发流式 probe 图片尺寸/预览视频元数据；--json/--ndjson 可选增加 width、height、视频 duration（整数秒），TTY 显示 SIZE/DURATION，单项失败只省略字段。pipe 仍严格输出 TYPE<TAB>URL。可用 config set assets.probe.enabled false 关闭额外媒体请求，assets.probe.concurrency 默认 4 且必须为正数。-d DIR 自动命名(image-001.jpg/video-001.mp4),-o PATH 只接受恰好一个资产。两者都是本地资源写入,目标不能已存在,不表示支持完整影片或磁力下载。assets download stdout 每行只输出最终路径,无装饰文本。

命令速查

执行前仍需用 --help 核对标志；以下示例是导航，不是稳定 API 合约。

javdb --version
javdb update --check --json
javdb config path
javdb config get host
javdb auth list
javdb auth check --json

javdb search "ABC-123" --limit 5 --json
javdb search "巨乳" --type actor --json
javdb detail ABC-123 --json
javdb detail MOVIE_ID --id --json        # 仅当 MOVIE_ID 已确认是内部 ID
javdb comments ABC-123 --page 1 --limit 20 --json
javdb magnets ABC-123 --cnsub --hd --json
javdb magnets ABC-123 --best --json
javdb assets list ABC-123 --type image 1-2 | javdb assets download -d ./images
javdb assets list ABC-123 --type video | javdb assets download -o ./preview.mp4

javdb tags --zone censored
javdb browse --tag 巨乳 --main m --limit 20 --json
javdb actor "山手梨愛" --main m --has-magnets --json
javdb series SERIES_ID --page 1 --limit 20 --json
javdb rankings movies --type fc2 --period week
javdb top250 --limit 20

javdb lists search "关键词" --zone all --json
javdb list LIST_ID --json
javdb lists related ABC-123 --json

javdb mark ABC-123 --want
javdb unmark ABC-123

所有数据命令可加的全局参数只有本次调用生效：--proxy URL 与 --host auto|mirror|main|URL。--proxy 支持 http/https/socks4/socks4a/socks5/socks5h， 必须带 host（socks 还需显式端口）；显式传入的空白值会直接报错，而不是静默覆盖继承代理后直连。 默认 auto 验证缓存线路成功后会立即复用；只有缓存失效时才从 startup 配置发现候选、重选 最快主机并改写 ~/.javdb-cli/route.json；固定 mirror/main/绝对 URL 完全跳过线路发现。 不要把未审阅的 URL 写入持久化配置。配置优先级为 CLI 参数 > 环境变量 > config.toml > 默认值。

关键语义与常见陷阱

1. detail NUMBER 默认把参数作为番号解析；--id 表示内部 movie ID。没有可靠来源时不要猜测并加 --id。
2. list REF 是某个公开/用户合集中的电影；不带子命令的 lists 是“我的合集”，需要认证。lists show/search/related 与 list 的含义不同；lists search/related --ndjson 每个列表输出一个带稳定 ID 的 kind=list 信封，lists related 收到带 ID 的 movie 信封时直接使用该 ID；缺少 list/entity 稳定 ID 时命令显式失败。
3. search --type 可返回 movie 以外的维度。将搜索结果交给 actor、series、maker、director、code 或 list 前，使用 JSON 中的实际 ID/名称，不要从显示文本臆测。
4. tags 的首次调用可能联网建立缓存；--refresh 会明确覆写该缓存。标签参数可用 ID、英文名或中文名，优先使用刚读取到的确切值。
5. mark 必须在 --watched 与 --want 中二选一；mark/unmark 的番号定位会去除首尾空白，先按大小写不敏感的完整匹配处理；没有完整匹配时，只有唯一且无歧义的格式等价番号才接受；对应多个不同影片 ID 或只有模糊候选时失败，不选择搜索首项。管道 movie envelope 带非空 id 时直接使用该 ID；只有确认 raw 引用是内部 ID 时才使用 --id。--content 是要保存到远端的文本，提交前应让用户确认其内容与目标。
6. auth check、TOP250 和用户列表的失败是认证或网络问题的信号，不应自动登录、重设账号或切换 host。只有用户明确要求时才改变配置或账号。magnets/detail --magnets 在 token 被拒时会自动回退匿名请求，其失败更可能是网络或服务端问题。
7. update --check --json 是唯一可机器读取且不改写安装的更新方式。update 会独立解析 Release 代理并忽略 --host、JAVDB_HOST 与已配置 host，再按已检测的 Homebrew、go install 或 Release 压缩包渠道安装；开发构建会拒绝自更新。预发布版本只能在用户明确要求时加 --prerelease，且 Homebrew 渠道不支持它。
8. comments NUMBER 默认把参数作为番号解析；--id 才是内部 movie ID。它只请求指定的一页，JSON 输出保留该页完整评论对象。
9. 影片媒体资产:javdb assets list ABC-123 输出资产序列(TTY 带编号描述、尺寸和预览时长;管道为 TYPE<TAB>URL),机器输出保留 type/url 并在可用时增加 probe metadata;javdb assets download 消费该记录流并验证落盘。下载链路不要求自己解析 preview_images JSON、手写 Referer、调用 ffmpeg，也不为 list 解析完整媒体。该命令域只写入本地 thumbnail/preview 资源,不支持完整影片或磁力目标。失败时如实报告,不能把已包装的图片字节或不完整视频当作成功结果。
10. rankings movies --type 与 rankings playback --filter-by 使用 censored|uncensored|western|fc2；三个排行命令的 --period 都使用 day|week|month。将这些 CLI 值原样传入，不要预先猜成数字分区或 daily|weekly|monthly。
11. search --zone 与 lists search --zone 只使用 censored|uncensored|western|fc2|all；search --filter-by 的文档值为 can_play|magnets|subtitle|single。magnets 与集成搜索的 --min-size 必须为非负数，负小数也拒绝，零合法。

以图搜番与管道

1. 以图搜番：javdb search IMAGE|URL [--source NAME] [--no-cache]。只接受 JPEG/PNG/WEBP （≤ 8 MiB）；图片会上传到内置 AVScan 或已配置的外部 source，向用户说明这一隐私影响后再执行。 候选按严格番号精确匹配联动 JavDB 详情；某候选失败时输出会继续并以非零退出，不要把它当成 "无结果"。
2. 反搜缓存：默认启用（30 天，按 source + 原图 SHA-256）。javdb cache reverse-search [--source NAME] [--clear] 只清理反搜缓存；--no-cache 按次绕过。
3. 管道：多数命令接受非 TTY stdin 批处理，TTY stdout 默认输出人类文本，非 TTY stdout 默认输出稳定记录流（逐行 ref/URI）；显式 --ndjson 才输出 javdb.pipeline/v1 NDJSON 信封（--ndjson/--json 互斥）。--json 可保留 producer 的 legacy 聚合 shape，但 --ndjson 按结果输出一个信封；例如 javdb search SSIS --ndjson | javdb detail。位置参数与非空 stdin 同时出现是歧义错误。 auth login、config set 与密码提示不使用管道 stdin。
4. 一体化磁力搜索：javdb search KEYWORD --magnets N 一次完成搜索、筛选、排序和 磁力获取。--cnsub、--hd、--min-size 在排序前筛选；--min-size 必须为非负数， 零合法，负小数也拒绝。N=0 返回全部，N>0 取前 N。文本模式输出磁力 URI，NDJSON 输出 kind=magnet 信封。仅支持 movie 搜索。

路由