站点控制与站点规则

通过黑白名单决定插件运行范围，并用 per-site JSON 安全配置匹配、selector、布局、阈值和 CSS。

Read Frog 有两套用途不同的站点设置：

功能	位置	用途
站点控制	设置 → 通用	通过黑名单或白名单允许/阻止插件在整个主机名上运行。
站点规则	设置 → 站点规则	修改匹配网页的解析、布局、过滤或样式。

“站点控制”适合权限策略；插件能运行但选错节点、破坏行内文字、翻译代码或需要专属 CSS 时使用“站点规则”。

通用站点控制

黑名单模式会在除列表外的所有主机运行；白名单模式只在列表中的主机运行。这里只按主机名精确或子域匹配：example.com 也匹配 news.example.com，但不接受路径和通配符。

翻译页的“自动翻译网站”和“永不自动翻译网站”也使用这种主机名格式。自动列表只控制是否自动启动，通用站点控制决定插件能否运行。

Site Rule URL pattern

站点规则支持更丰富的 URL pattern，匹配时忽略 query string。

Pattern	匹配范围
`github.com`	`github.com` 的 HTTP/HTTPS 页面
`*.example.com`	根域名及所有子域名
`docs.example.com/guides/*`	指定主机的 guides 路径
`https://example.com/*`	仅 HTTPS 页面
`www.amazon.*`	多个顶级域下的 Amazon 主机
`javdb*.com`	`javdb` 后带匹配文字的主机名

scheme 可以是 http、https 或 *，不允许显式端口。宽泛规则需要排除某些页面时使用 excludeMatches。

多条规则如何合并

Read Frog 先依次应用所有匹配且启用的内置规则，再应用用户规则。可按 ID 禁用某条内置规则。

selector 列表按顺序经过基础字段、.add 和 .remove 处理；
minCharacters、minWords 是标量，最后匹配的值生效；
injectedCss 与 injectedCss.add 按匹配顺序拼接；
无效 URL pattern 或 selector 会被忽略并显示警告，不会执行。

因此用户规则通常拥有最终决定权，但数组不会简单整体覆盖。用 .remove 撤销前面规则添加的 selector，用 .add 扩展它。

可用字段

每条规则都必须有唯一 id 和 matches。编辑器接受单个对象或对象数组。

字段	含义
`id`	稳定且唯一的规则 ID。
`description`	可选说明。
`matches` / `excludeMatches`	URL pattern 或 pattern 数组。
`enabled`	是否启用用户规则。
`excludeSelectors`	永不翻译的节点。
`includeSelectors`	明确纳入处理的区域。
`forceBlockSelectors`	强制按块级内容处理。
`forceInlineSelectors`	强制保留在行内文字流中。
`preserveTextSelectors`	保留匹配节点的原文。
`minCharacters` / `minWords`	为该站点覆盖小段过滤阈值。
`injectedCss`	注入到匹配网页的 CSS。

selector 集合也支持 .add 和 .remove，例如 excludeSelectors.add。

安全示例

从一个窄主机名、少量稳定 selector 和限定作用域的 CSS 开始：

[
  {
    "id": "example-docs",
    "description": "Translate article copy but leave navigation and code untouched.",
    "matches": ["docs.example.com/*"],
    "excludeSelectors": [
      "nav",
      "pre",
      "code",
      "[aria-label='Breadcrumb']"
    ],
    "includeSelectors": ["main article"],
    "forceBlockSelectors": ["article p", "article li"],
    "preserveTextSelectors": [".product-name", ".command-name"],
    "minCharacters": 2,
    "minWords": 1,
    "injectedCss": ".read-frog-translated-content-wrapper { max-width: 100%; }"
  }
]

保存后重新加载一个匹配页面，确认结果再扩大 pattern。优先使用语义属性或长期稳定的 class；构建生成的 class 往往会随网站发布变化。

调整前面的规则

用后置用户规则扩展或撤销内置 selector，而不必复制整条内置规则：

[
  {
    "id": "example-docs-adjustment",
    "matches": ["docs.example.com/*"],
    "excludeSelectors.add": [".sidebar-ad"],
    "excludeSelectors.remove": [".article-summary"],
    "forceInlineSelectors.add": [".term-with-tooltip"]
  }
]

如果整条内置规则都有问题，直接禁用它比重建全部字段更可靠。

校验、限制与排查

编辑器保存前会校验 JSON、schema、重复 ID、selector、pattern、规则数量和大小。目前最多 200 条用户规则，JSON 最多 65,536 字符，每个 CSS 值最多 8,192 字符。

注入 CSS 会在规则匹配的每个页面运行。保持 pattern 足够窄，并避免隐藏登录、安全或账户控件。

排查顺序：确认通用站点控制允许当前主机；确认规则启用且 pattern 覆盖当前路径；检查 excludeMatches；在浏览器检查器中测试 selector；临时删除一半字段定位问题；保存后重新加载页面。