设置字段语义对照
类型：wiki（知识沉淀）
描述：settings 全部字段的实际语义、对应源码、易混淆点 — 改 UI 前必查
最后更新：2026-05-26（v0.10.14）
相关源码：src/utils/storage-data.ts（SettingParams interface + DefaultSettings）
相关 rules：docs/rules/settings-change-pre-check.md
相关 wiki：shared-queue-architecture.md
是什么
settings 字段一览表 + 实际语义 + 字段名暗示与真实的差异 + 调度器在哪读它。
字段分类
SettingParams = {
搜索 (1)
地图抓取并发 (5) ← 历次踩坑高发区
任务调度 (1)
网站抓取并发 (5) ← v0.10.14 踩坑
解析规则 (3)
数据过滤 (5)
解析层开关 (12) ← v0.10.13 新加
内页跟随 (5) ← v0.10.13/14 新加
}
全字段表
搜索
| 字段 |
类型 |
实际语义 |
字段名暗示 ↔ 真实 |
searchLanguge |
string |
Google Maps URL 的 hl= 参数 |
✅ 名实一致 |
searchCountry |
string |
Google Maps URL 的 gl= 参数（"name" = 用国家名） |
⚠️ "name" 不是国家代码 |
地图抓取并发
| 字段 |
类型 |
实际语义 |
字段名暗示 ↔ 真实 |
出处 |
maxConcurrentTasks |
int 1-10 |
activeTabs.size 全局上限 |
❌ 「任务数」是错的，是 Tab 数 |
batch-controller.ts:27 |
pagerConcurrency |
int 1-5 |
全局翻页 Fetch 并发 |
⚠️ 必含「全局」字样 |
batch-controller.ts:pumpPager |
taskGapMin |
int sec |
实开 Tab 之间间隔下限 |
✅ |
|
taskGapMax |
int sec |
实开 Tab 之间间隔上限 |
✅ |
|
requestDelayMin |
int sec |
翻页 Fetch 间隔下限 |
✅ |
|
requestDelayMax |
int sec |
翻页 Fetch 间隔上限 |
✅ |
|
⚠️ 废弃：requestConcurrency（v0.10.0+ 不再读，但 storage 保留兼容）
任务调度
| 字段 |
类型 |
实际语义 |
出处 |
maxConcurrentTasks |
int |
同上（实际是 Tab 数） |
task-manager.ts:pumpTasks |
注：maxConcurrentTasks 在调度器和 UI 都用，但语义统一是 Tab 上限。
网站抓取并发
| 字段 |
类型 |
实际语义 |
字段名暗示 ↔ 真实 |
出处 |
deepScrapeConcurrency |
int 1-10 |
全局网站抓取 worker 线程数 |
❌ 「网站数」是错的，是 worker 数 |
engine-manager.ts:getConcurrency |
deepScrapeDomainConcurrency |
int 1-10 |
单域名最多几个 worker（防 DDoS 对方站） |
✅ 但要明示 "per-hostname" |
engine-manager.ts:domainActive |
scrapeDelayMin |
int sec |
网站 worker 间间隔下限 |
✅ |
|
scrapeDelayMax |
int sec |
网站 worker 间间隔上限 |
✅ |
|
scrapeTimeout |
int sec |
单页加载超时 |
✅ |
|
解析规则（基础）
| 字段 |
类型 |
实际语义 |
emailRegex |
string |
留空 = 用默认；自定义则覆盖 |
phoneRegex |
string |
留空 = 走智能 3 层级；自定义则完全覆盖层级 |
customSocials |
string |
用户自定义社媒（每行 name\|regex\|color） |
数据过滤
| 字段 |
类型 |
实际语义 |
advParms |
string[] |
去重 / 必填字段过滤 — multi-checkbox |
minRating |
float |
评分 < 此值跳过（0 = 不过滤） |
minReviews |
int |
评论 < 此值跳过（0 = 不过滤） |
categoryBlacklist |
string |
Google 商家「分类」字段含此关键词跳过 |
domainBlacklist |
string |
这些根域不进入网站抓取（在 engine-manager 过滤） |
解析层独立开关（v0.10.13 新增）
| 字段 |
默认 |
实际语义 |
cloudflareDecode |
true |
Cloudflare data-cfemail 解码 |
emailBlacklistOn |
true |
邮箱黑名单总开关 |
emailBlacklistCustom |
"" |
用户追加（v0.10.14 起支持邮箱/域名两种写法） |
emailNoiseOn |
true |
噪音过滤（.png/.jpg/@sentry 等） |
emailNoiseCustom |
"" |
用户追加噪音模式（子串匹配） |
randomIdFilter |
true |
屏蔽超长随机 ID（>25 hex 用户名） |
phoneTier1 |
true |
tel: 链接（高置信度） |
phoneTier2 |
true |
上下文关键词（Phone: / 电话:） |
phoneTier3 |
true |
自由文本（低置信度，最易噪） |
phoneBlacklistCustom |
"" |
用户追加测试号 |
socialBlacklistOn |
true |
社媒 handle 黑名单 |
socialBlacklistCustom |
"" |
用户追加 handle |
内页跟随（v0.10.13/14 新增）
| 字段 |
默认 |
实际语义 |
scrapeDepth |
1 |
1 / 2 / 3 跟随深度 |
followSubdomain |
false |
允许跟同根域子域（false = 严格 hostname） |
followKeywordsWhite |
"contact,about,..." |
优先关键词白名单 |
followKeywordsBlack |
"blog,news,..." |
排除关键词黑名单 |
followSkipAssets |
true |
跳过 jpg/css/pdf 等资源 |
followAllowedDomains |
"" |
v0.10.14 跨根域白名单（公司多域名场景） |
健康巡检 / 看门狗（v0.10.15 新增）
详见 tab-lifecycle-and-watchdog.md
| 字段 |
默认 |
范围 |
实际语义 |
watchdogEnabled |
true |
bool |
总开关 — 关掉就只靠 60s 兜底，不推荐 |
watchdogInterval |
5 |
2-30 分钟 |
巡检周期 |
watchdogStaleThreshold |
5 |
2-30 分钟 |
单 tab 寿命阈值，超过判为僵尸 |
watchdogConsecutiveLimit |
3 |
1-10 次 |
连续异常 → 强关窗口 + 重置调度器 + 通知 |
watchdogAutoResume |
true |
bool |
v0.10.23 核弹重启后自动 pumpTasks（不用手动点开始） |
watchdogAutoResumeCooldownSec |
10 |
0-600 秒 |
v0.10.24 重启后冷却（之前 60s，用户嫌慢） |
watchdogAutoResumeMaxCycles |
9999 |
1-99999 次 |
v0.10.24 默认无限（除非用户点停止）；保守用户可调小如 3-5 |
"字段名暗示 vs 真实" 速查表
仅列出真实语义与字段名暗示不一致的字段（改 UI 时最易踩坑）：
| 字段 |
名字暗示 |
真实 |
修正后 UI label |
maxConcurrentTasks |
"任务数" |
Tab 上限 |
"实开 Tab 并发上限" |
deepScrapeConcurrency |
"网站数" |
worker 数 |
"抓取并发上限（worker 线程数）" |
requestConcurrency |
"请求并发" |
已废弃 |
（UI 不显示） |
pagerConcurrency |
"翻页并发" |
全局 Fetch 上限 |
"翻页 Fetch 并发上限" |
易踩坑
⚠️ 坑 1：字段名暗示 ≠ 真实
详见上表。改 UI 前必须查本表。
⚠️ 坑 2：废弃字段还在 storage interface 里
requestConcurrency v0.10.0 起调度器不读，但 storage 保留兼容老用户数据。不要删，加 // deprecated 注释即可。
⚠️ 坑 3：手机自定义正则会"完全覆盖"3 层级
用户填 phoneRegex 时，Tier 1/2/3 开关全部失效。要在 UI helper 写明。
⚠️ 坑 4：黑名单分类不止一个
emailBlacklistCustom：邮箱级 / 域名级（v0.10.14 起）domainBlacklist：根域名级 — 不进入抓取（engine-manager 过滤）categoryBlacklist：Google 商家「分类」字段过滤（不是 URL）socialBlacklistCustom：社媒 handle 名级emailNoiseCustom：邮箱子串模糊匹配
5 个黑名单 ≠ 同一回事。UI 不要简称「黑名单」。
修改 SettingParams 时的 checklist
版本里程碑
| 版本 |
事件 |
| v0.9.x |
字段最初设计，per-task 心智 |
| v0.10.0 |
共享队列重写，但字段名没改 → 埋下命名误导坑 |
| v0.10.12 |
修正 maxConcurrentTasks UI 文案 |
| v0.10.13 |
加 12 个解析层独立开关 + 5 个内页跟随字段 |
| v0.10.14 |
修正 deepScrapeConcurrency UI + 加 followAllowedDomains |