legado-book-source-generator

name	legado-book-source-generator
description	Use when 用户要求为任意网站生成书源、生成阅读书源、分析小说站点、生成 Legado/阅读规则。强制触发词：书源、生成书源、帮我生成、book source、legado、阅读书源、小说站点分析。如果用户给出了一个 URL 并要求生成或分析，必须加载此 skill。

Legado 书源生成

这是工具箱模式。先初始化，再按当前问题选择工具；不要把流程当成必须机械执行的长状态机。

node "<skill-dir>/scripts/bsg.mjs" init <url> [--cwd <输出目录>]
node "<skill-dir>/scripts/bsg.mjs" toolbox
node "<skill-dir>/scripts/bsg.mjs" status --run <run-dir>

先读哪些 reference

• 常规流程：读 references/workflow.md。
• 匿名初探 / site-facts：读 references/probe-guide.md 和 references/assessment-template.md。
• 生成规则：读 references/legado-json-structure.md、references/official-rule-pack.json、references/legado-source-behavior.md。
• 验证失败回修：读 references/failure-diagnosis.md、references/validation-policy.md、references/validator-integration.md。
• Android、模拟器、登录态、WebView/WebJs、入口反爬复核：必须先读 references/android-probe-guide.md 和 references/policies.md；需要判断 Probe 与阅读 App 差异时再读 references/webview-behavior-matrix.md。

常用工具

• status --run <run-dir>：看当前阶段、pendingUserAction、repairContext 和下一步建议。
• check --run <run-dir>：检查评估、登录、Android 决策是否缺证据。
• source inspect --run <run-dir>：审计当前 book-source.json 的风险字段。
• android --run <run-dir>：Android 单入口；检查真机/模拟器和 Probe，必要时启动 Probe，运行 mode=android 验证并收敛报告。
• android --run <run-dir> --dump-cookie <file>：显式导出 Probe 原始 Cookie 到本地文件，供人工核对或 validator 调试；默认输出不显示 Cookie 值。
• android-status：只读诊断；检查 adb、真机/模拟器和 Android Probe。
• validate --run <run-dir> [--mode http|browser|android] [--keyword <中文关键词>] [--book-url <url>]：运行 validator，写入 validator-report.json。--book-url 跳过搜索直接从详情页开始验证（对齐阅读 debug 模式的 URL 直接入口），用于搜索被反爬阻塞但需验证后续链路的场景。
• record-validation --run <run-dir> --status <status>：把真实验证报告收敛成状态、能力矩阵和修复上下文。
• debug-bundle [--run <run-dir>]：打包状态、报告、书源和会话导出，方便复盘。
• run --run <run-dir>：可选的温和助手；它会启动下一阶段，或在已有 validator-report.json 时自动记录验证结果。

Windows / PowerShell 命令风险

当前默认 shell 是 PowerShell。复制或手写命令时先确认语法属于 PowerShell，不要混用 bash、cmd 和 PowerShell。

常见坑

• 用 curl.exe 调 HTTP，不要用 curl；PowerShell 里的 curl 可能是 Invoke-WebRequest 别名。
• 优先写一行命令。不要混用 bash 的 \、cmd 的 ^、PowerShell 的反引号续行。
• JSON 请求体优先用单引号包住：-d '{"url":"https://example.com","timeout":60000}'。复杂 JSON 用 $body = @{ ... } | ConvertTo-Json -Depth 8。
• 路径必须加双引号，尤其是中文路径、空格路径和 <skill-dir>：node "D:/.../scripts/bsg.mjs" ...。
• Select-String 没有 -First；先匹配再 | Select-Object -First 3。
• Select-Object -Index 40..80 是错的；要先读数组再用 $lines[40..80]。
• ConvertFrom-Json 只能吃纯 JSON；命令输出混有日志、提示词或乱码时，先保存/截取纯 JSON 再解析。
• 不确定 shell 写法时，不要临时拼长命令；优先运行 toolbox、android-status、android --run、validate --run 这些封装命令。

原则

• UA 完整性：书源 header 的 UA 必须完整（含引擎名+版本号）。截断的 UA 会被反爬识别。详见 references/legado-source-behavior.md。
• 验证码与登录态：验证码触发时，如果站点有登录功能，先走登录路径再重试验证。只有登录后仍被拦才判定为站点固有限制。搜索仍被阻塞时用 validate --book-url <url> 跳过搜索验证后续链路。详见 references/policies.md。
• TLS 指纹：validator 用 curl 发 HTTP 请求（非 OkHttp），避免 PC JVM 的 TLS 指纹被反爬识别。详见 references/legado-source-behavior.md。
• Browser MCP 缺失：当需要浏览器分析、登录 Cookie 或前端渲染页面时，先确认当前执行环境是否具备浏览器工具。如果没有，不要假装已经看过页面，也不要编造 DOM、接口或 Cookie。先用 HTTP/validator 能力继续分析；若该站点必须浏览器能力才能判断，明确提示用户配置 Browser MCP、使用 Android Probe，或换用支持浏览器工具的客户端。

Android / WebView 快速配方

遇到登录态、webView:true、webJs、CSR 正文、入口验证码/反爬复核，或用户已连接真机/模拟器时：

1. 读 references/android-probe-guide.md。
2. 运行 node "<skill-dir>/scripts/bsg.mjs" android --run <run-dir>。
3. 按它返回的 requiredUserAction、nextCommand 或 afterUserCommand 继续；常规 Android 场景优先跟随这个入口，不自己临时拼 adb、Probe API 或 validator 子步骤。

PC HTTP / Browser 只用于观察站点和辅助写规则。交付前如果 validator 结果不是 Android mode，record-validation 会先要求确认 Android 真机或模拟器可用性；用户明确没有设备后才允许降级记录，不能把 PC passed 写成 full pass。

android --run 是默认收敛入口，不是所有 Android 问题的唯一调试手段。只有在它返回明确诊断、脚本失败需要定位环境问题、或用户要求调试 Probe/设备时，才展开底层 adb、Probe API 或 validator 子步骤；调试结束后仍回到 android --run / record-validation 收敛结果。

如果 Probe 登录后自动 Cookie 判断和手机页面状态矛盾，先看 android --login-completed 的 probeCookieEvidence。仍不清楚时运行 android --run <run-dir> --dump-cookie "runs/<slug>/cookies.json"，人工核对域名和 Cookie 名；原始 Cookie 只用于本地调试，不要写进书源。

最终审计

交付前必须运行：

node "<skill-dir>/scripts/bsg.mjs" deliver --run <run-dir>

前提是 validator-report.json 已通过 record-validation 或 run 收敛，并且 rule-check.json、capability-matrix.json 等产物仍对应当前 book-source.json。缺什么让 deliver 返回 nextCommand / correctiveAction，不要自己补结论。

deliver 是唯一最终审计。它通过之前，不要宣称书源“可用”、“正常阅读”、“full pass”。

硬规则

0. bsg.mjs deliver 返回 ok 是任务完成的唯一标志。没有第三种状态。

本 skill 的 validator 是基于阅读书源规则语义的 JVM/Kotlin 兼容验证器，实现了书源规则解析、JS/Rhino 执行、CSS/JSONPath/XPath/Regex 提取，以及 search → detail → toc → content 的主要验证链路。书源通过 validator + record-validation + deliver 代表规则层具有较强参考价值；纯 HTTP/SSR 站点通常可直接导入使用。 涉及 Android WebView、登录态、CookieJar 持久化、付费/VIP、验证码、Cloudflare 的站点，必须以 record-validation 归一化后的状态和 capability-matrix.json 为准，不能由 AI 摘要自行改结论。

反过来：绕过 deliver 交一个 book-source.json 文件，无论你已经验证了多少链路、写了多完整的总结表格，都视为未完成。 用户拿到此书源大概率用不了，必然回来要求返工——你只是把返工成本转嫁给了用户，不是完成了任务。validator 复现了阅读书源规则引擎的核心语义，不存在"validator 过不了但阅读能用"的中间地带让你提前交差；过不了就是过不了，去修到过，或按 record-validation 返回的状态诚实停下。needs_app_review 只用于 validator 无法自动确认、且脚本已收敛为需 App 实测的硬边界；验证码、Cloudflare、登录失败、付费/VIP、规则错误、选择器为空、URL 错误都不是 needs_app_review。VIP/付费由脚本按证据收敛为 degraded 或失败，不能写成 full pass。

交付前自检：如果当前准备"写个总结交付"而不是"运行 deliver"，停下来——这会制造返工。

1. run-state.json 由命令写入，禁止手动编辑。

2. requiredUserAction 非 null 时停止自动操作。 等用户确认后再运行 resolve-user-action。

3. 验证报告生成后不要靠猜测改结论。 validator 报告已经存在时，运行 record-validation 或 run 收敛状态。

4. 最终交付事实优先来自 Android。 桌面 HTTP 或浏览器能看到内容，只能辅助写规则；Android 可用时 passed 必须来自 Android mode，没设备时先问用户并降级说明。

红旗

红旗不是穷举禁止动作，是三条判断原则——核心都是"结论不能强过证据"。冒出下列任一念头时，先用工具查证再继续：

A. 证据强度要匹配结论强度。 未验证的不当已验证，弱证据不下强结论；用"需复核 / 工具限制"归类不能掩盖本可定位的规则错误或证据缺失。

常见违反（举例，不限于）：必需链路失败就改用未验证的替代入口继续；mode=android 跑过但 probe_unavailable，仍当成 Android Probe 证据；规则错误或验证器缺证据，标成 needs_app_review / validator_limitation 蒙混。

B. 书源最终在阅读 App 跑，最高权威证据来自 Android / 真机。 有该环境必须用它取证；没有就如实降级标注，不用低权威环境的"通过"冒充交付结论。

常见违反（举例，不限于）：桌面浏览器或 HTTP 能看到内容，就断言 Android WebView / 阅读 App 一定可用；Android 在线却先用 HTTP 验证就交付；没插手机 / 没开模拟器，就直接按 PC passed 交付。

C. 判定站点性质要用对证据类型，且探测动作本身可能改变站点状态。 判 SSR/CSR 看 HTTP 原始响应（浏览器看到的是渲染后 DOM，会把 CSR 误判成 SSR）；反复探测同一反爬端点会累积触发风控，探测后才出现的验证码可能是探测副作用、不是站点固有行为。

常见违反（举例，不限于）：为判断 SSR/CSR，默认用浏览器 evaluate / JS 自动探测搜索页或登录页；JS / 反复探测后出现验证码，就断言该站天然有验证码。

输出

• outputs/<site-slug>/book-source.json — 唯一默认交付物
• runs/<site-slug>/ — 过程记录

deliver 完成后必须运行 validator-stop 关闭 validator。