分层配置系统完全指南从 wigolo 提取基准中的 ReadTheDocs 风格配置文档到真实实现【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo本文以 wigolo 仓库提取基准extraction benchmark中的参考文档 golden/docs-003.md 为骨架系统讲解一套完整的ReadTheDocs 风格分层配置系统包括六层配置来源与优先级、YAML/TOML 文件格式、环境变量映射、命令行覆盖、编程式访问、Schema 校验、多环境 Profile、热重载与密钥管理同时以 wigolo 真实的配置实现src/config.ts、src/persisted-config.ts作为仓库侧佐证帮助读者理解分层配置在真实项目中的落地方式以及这份 golden 文档在自动化评估网页内容提取质量时扮演的角色。文档定位一份作为参考答案的配置文档首先需要明确docs-003.md在仓库中的性质。它位于 benchmarks/extraction/fixtures/golden/ 目录下是 wigolo 提取基准benchmarks/extraction的golden金标准文件之一而不是 wigolo 官方文档的一部分。它的作用是为给定的 HTML 测试页面提供理想提取结果的参考答案让提取管线有可量化对标的对象。从 manifest.json 可以看到对应条目{ id: docs-003, url: https://docs.example.com/cli/commands, category: docs, htmlFixturePath: html/docs-003.html, goldenPath: golden/docs-003.md, expectedExtractor: defuddle, tags: [cli, reference] }该条目属于docs文档站类别模拟的是CLI 命令参考 / 配置文档类页面期望由defuddle提取器命中。同目录下的docs-002.md是 MDN 风格的 API 参考文档而docs-003.md则是 ReadTheDocs 风格的项目配置文档——两者共同说明golden 文件刻意模拟了真实世界中的主流文档写作风格。正因为这份文档本身技术内容完整、结构清晰它也是一份极佳的分层配置系统教学素材适合在讲解配置体系时作为范本展开。配置来源与优先级六层合并的确定性顺序文档开篇即给出核心设计配置系统采用分层layered方式多个来源的设置按既定优先级合并。六个来源按优先级从低到高排列内置默认值built-in defaults系统级配置文件/etc/myapp/config.yaml用户级配置文件~/.config/myapp/config.yaml项目级配置文件./myapp.config.yaml环境变量MYAPP_*前缀命令行参数优先级更高的来源会覆盖低优先级来源从而保证默认值可用、环境可裁剪、最终以命令行为准。wigolo 的真实分层佐证wigolo 的配置解析同样遵循分层 确定优先级的思路但精简为更贴近本地优先工具的三层。官方文档 docs/configuration.md 明确写出environment variable ~/.wigolo/config.json built-in default并且指出Env vars win per-field, so you can persist a baseline inconfig.jsonand override one knob per process.WIGOLO_CONFIG_PATHrelocates the config file itself.环境变量按字段优先因此你可以在config.json中持久化基线配置并按进程覆盖某一个旋钮WIGOLO_CONFIG_PATH可重定位配置文件本身。在源码 src/config.ts 中getConfig()的注释与实现进一步印证了这一层级// Load persisted settings once. Precedence per field: // explicit env var config.json value built-in default const { settings } readPersistedConfig(defaultConfigPath());其中defaultConfigPath()定义在 src/persisted-config.tsexport function defaultConfigPath(): string { return process.env.WIGOLO_CONFIG_PATH ?? join(homedir(), .wigolo, config.json); }也就是说golden 文档中系统级 → 用户级 → 项目级 → 环境变量的递减层级在 wigolo 中被收敛为内置默认值 → 单个 JSON 配置文件 → 环境变量的简洁模型而WIGOLO_CONFIG_PATH相当于把配置文件在哪里这个决策本身也交给了环境变量。配置文件格式YAML 与 TOML文档给出了配置文件的两种主流格式YAML完整功能与 TOML简化示例。YAML完整示例与字段语义# myapp.config.yaml server: host: 0.0.0.0 port: 8080 workers: 4 timeout: 30s max_request_size: 10MB database: driver: postgres host: localhost port: 5432 name: myapp_production pool: min_connections: 5 max_connections: 20 idle_timeout: 300s logging: level: info format: json output: stderr file: enabled: false path: /var/log/myapp/app.log max_size: 100MB max_backups: 5 compress: true cache: backend: redis redis: url: redis://localhost:6379/0 prefix: myapp: ttl: 3600 memory: max_items: 10000 max_size: 256MB auth: jwt: secret_env: MYAPP_JWT_SECRET expiration: 3600 refresh_expiration: 86400 algorithm: HS256 oauth: enabled: false providers: [] rate_limit: enabled: true window: 60s max_requests: 100 by: ip whitelist: - 127.0.0.1 - ::1逐块解读各字段的语义server 块定义服务监听地址与资源预算。host默认监听所有接口0.0.0.0port为服务端口workers表示并发工作进程数默认取 CPU 核数timeout为请求超时max_request_size限制单请求体积上限。database 块连接信息与连接池参数。driver支持postgres、mysql、sqlitepool.min_connections/pool.max_connections控制连接池伸缩范围idle_timeout回收空闲连接。logging 块日志级别debug/info/warn/error、输出格式json或文本、输出目标stderr/文件以及文件轮转参数max_size、max_backups、compress。cache 块backend在redis/memory/memcached间选择redis 后端带 URL、key 前缀与 TTL内存后端带条目数与容量上限。auth 块JWT 的密钥通过secret_env间接引用环境变量而不是直接写入文件expiration/refresh_expiration控制令牌有效期algorithm指定签名算法OAuth 默认关闭。rate_limit 块按window时间窗口、max_requests上限、by: ip维度做限流whitelist放行本机回环地址。TOML 与多格式支持同样的配置也可以用 TOML 表达文档给出 server 与 database 两个块的对照[server] host 0.0.0.0 port 8080 workers 4 timeout 30s [database] driver postgres host localhost port 5432 name myapp_production [database.pool] min_connections 5 max_connections 20 idle_timeout 300s要点TOML 用[块名]表达嵌套层级[database.pool]即 YAML 中的database.pool对象时长类字段在 YAML 中写作30s、在 TOML 中写作30s字符串——多格式支持的关键是内部统一转换为带类型的运行时值。对照 wigolo数据目录、监听与日志旋钮wigolo 的配置字段虽未采用 YAML 文件但语义上高度对应。以下映射来自 src/config.ts 中的默认值与解析逻辑golden 文档配置项wigolo 对应字段默认值说明server.host/server.portdaemonHost127.0.0.1/daemonPort3333守护进程监听地址与端口server.timeoutfetchTimeoutMs10000等一批超时旋钮按场景细分fetch、playwright、challenge-completion、search stage budget 等database数据存储dataDir~/.wigolo缓存库、模型、密钥、插件、shell 历史的根目录logging.level/logging.formatlogLevelinfo/logFormatjson支持debug/info/warn/error与json/textcache.ttlcacheTtlSearch86400/cacheTtlContent604800搜索缓存与内容缓存分别设 TTL秒rate_limit.*crawlConcurrency/crawlDelayMs、crawlPrivateConcurrency/crawlPrivateDelayMs抓取的并发度与礼貌性限速例如 src/config.ts 中daemonPort: envInt(WIGOLO_DAEMON_PORT, 3333, settings, daemonPort), daemonHost: (() { const raw envStr(WIGOLO_DAEMON_HOST, 127.0.0.1, settings, daemonHost); return raw?.trim() || 127.0.0.1; })(),可见监听地址 端口 超时这一组服务器配置的范式在 wigolo 中以 daemon 子系统的形式真实存在。环境变量映射点路径到全大写下划线文档规定所有配置项都可通过环境变量设置规则是用MYAPP_前缀 点路径转全大写下划线。例如server.host对应MYAPP_SERVER_HOST。原文映射表完整如下Config PathEnvironment VariableExampleserver.hostMYAPP_SERVER_HOST0.0.0.0server.portMYAPP_SERVER_PORT8080database.hostMYAPP_DATABASE_HOSTdb.example.comdatabase.pool.max_connectionsMYAPP_DATABASE_POOL_MAX_CONNECTIONS50logging.levelMYAPP_LOGGING_LEVELdebugcache.backendMYAPP_CACHE_BACKENDredisauth.jwt.expirationMYAPP_AUTH_JWT_EXPIRATION7200这种点路径 ↔ 全大写下划线的机械映射带来的好处是配置的键与环境的键一一对应、无需额外映射表即可推导且天然避免了在代码里手写一堆互不相干的魔法字符串。wigolo 的 env 辅助函数族wigolo 在 src/config.ts 中实现了同构的一套辅助函数并且统一遵循同一优先级规则explicit env var persisted config.json value built-in default显式环境变量 持久化 config.json 值 内置默认值function envStr(key, fallback, settings, settingsKey?): string | null function envInt(key, fallback, settings, settingsKey?): number function envIntArray(key, fallback, settings, settingsKey?): number[] function envBool(key, fallback, settings, settingsKey?): boolean它们的行为可以对照 golden 文档理解envStr取字符串值环境变量存在即返回否则看持久化配置再退回默认值。envInt解析整数parseInt失败NaN时静默回退到默认值——相当于隐式的类型校验与容错。envBool布尔判定不是false且不是0即为真并支持从config.json读取布尔值。envIntArray把逗号分隔字符串解析为数字数组如WIGOLO_BOOTSTRAP_BACKOFF_SECONDS任一项非法即整体回退默认值。由于 wigolo 使用WIGOLO_/SEARCH_/LOG_等独立前缀而非统一MYAPP_具体键并非点路径转下划线而是显式书写例如export WIGOLO_DAEMON_PORT9090 export WIGOLO_TLS_TIERauto export LOG_LEVELdebug export LOG_FORMATjson export WIGOLO_MULTI_QUERY_MAX10使用方式与 golden 文档中的MYAPP_*环境变量完全同构只是键名命名风格不同。命令行参数覆盖最高优先级的最后一道闸文档给出命令行覆盖示例myapp serve --server.port9090 --logging.leveldebug --database.hostremote-db--server.port9090这类点路径参数与环境变量遵循同一套键体系因而学习成本极低命令行参数位于优先级最顶端适合临时调试、一次性运行或 CI 场景。wigolo 的配置命令行wigolo 将配置即命令落到了 docs/configuration.md 描述的wigolo config子命令上wigolo config # 交互式设置 shellTUI wigolo config --plain # 打印当前设置并退出 wigolo config --plain --json wigolo config --set searchBackendhybrid # 无交互地更新单个设置 wigolo config --storage # 存储占用地图 wigolo config --cache-stats wigolo config --export settings.json # 导出密钥除外 wigolo config --import settings.json wigolo config --cleanup cache # cache|embeddings|models|browser|searxng其中--set keyvalue正是 golden 文档中--server.port9090这种单键覆盖思路的交互式版本不动整个文件只更新一个字段。wigolo dashboard是wigolo config的别名。值得注意的原则是密钥LLM Key、代理凭据永远不会进入config.json而是存放在操作系统钥匙串中详见下文密钥管理一节。编程式访问配置文档提供的 Python 编程式访问示例from myapp.config import Config config Config.load() # 点号访问 port config.server.port # 8080 db_host config.database.host # localhost # 字典式访问 port config[server][port] # 8080 # 带默认值获取 workers config.get(server.workers, default2) # 判断键是否存在 has_cache config.has(cache.backend) # True这套 API 设计提供了三种互补能力属性式点号访问config.server.port适合编译期/静态检查友好的代码字典式访问config[server][port]适合动态键get带默认值与has存在性判断适合可选配置。整体目标是把配置变成与普通对象无异的类型化数据而不是到处散落的全局变量。wigolo 的等价物getConfig()wigolo 的 TypeScript 侧对应物是 src/config.ts 的getConfig()读取一次持久化配置后构建完整的Config对象并缓存在模块级变量cachedConfig中后续所有字段都通过config.daemonPort、config.cacheTtlSearch这样的属性直接访问let cachedConfig: Config | null null; export function getConfig(): Config { if (cachedConfig) return cachedConfig; // 按字段执行 env config.json default 的优先级合并 const { settings } readPersistedConfig(defaultConfigPath()); cachedConfig { /* ... 每个字段逐一解析 ... */ }; return cachedConfig; }Config接口在 src/config.ts 中定义了 100 余个字段并配以详细注释——例如searchPrewarmBrowser注明Latency-only — no change to results仅影响延迟、不影响结果searchMojeekProbeOnly解释为何让 mojeek 引擎保持仅探测以规避 403 惩罚。这展示了高质量配置项注释的写法不仅说明是什么还解释为什么。配置校验与约束规则文档强调配置在加载时按 Schema 校验。示例代码如下from myapp.config import Config, ValidationError try: config Config.load() except ValidationError as e: print(fConfiguration error: {e}) for error in e.errors: print(f - {error.path}: {error.message})ValidationError.errors是错误列表每项含path出错的配置路径与message原因便于精准定位与批量上报。原文的完整校验规则表如下FieldTypeRequiredDefaultConstraintsserver.hoststringNo0.0.0.0Valid IP or hostnameserver.portintegerNo80801-65535server.workersintegerNoCPU count1-256server.timeoutdurationNo30s1s-300sdatabase.driverstringYes-postgres,mysql,sqlitedatabase.hoststringYes-Valid hostnamedatabase.portintegerNoDriver default1-65535database.namestringYes-Non-emptydatabase.pool.min_connectionsintegerNo51-max_connectionsdatabase.pool.max_connectionsintegerNo20min_connections-1000logging.levelstringNoinfodebug,info,warn,errorcache.backendstringNomemorymemory,redis,memcached这张表浓缩了配置校验的最佳实践显式标注必填Required 列如database.driver/database.host/database.name必填缺失即拒绝启动范围约束Constraints 列端口 1-65535、worker 数 1-256、超时 1s-300s、连接池min ≤ max枚举约束driver、logging.level、cache.backend只能在固定集合内取值有意义的默认值默认值本身即免配置可用的体现。wigolo 中的校验式防护wigolo 未引入独立的 JSON Schema 校验器但把同样的防护分散在解析层。最典型的是 src/config.ts 中的validateTlsBrowser白名单校验WIGOLO_TLS_BROWSER的值会被透传给 Rust napi 绑定未经验证的值可能导致原生层崩溃因此只接受chrome|firefox|safari|edge|opera加数字版本号的格式const TLS_BROWSER_PATTERN /^(chrome|firefox|safari|edge|opera)_\d$/; export function validateTlsBrowser(raw: string | null | undefined, fallback: string): string { if (!raw) return fallback; if (TLS_BROWSER_PATTERN.test(raw)) return raw; process.stderr.write( [wigolo] WIGOLO_TLS_BROWSER${JSON.stringify(raw)} is not in the allowlist ... falling back to ${fallback}\n, ); return fallback; }与之配套的防护还包括envInt对非法整数的 NaN 回退类型容错tlsTier/stealth/localLlm等枚举字段的规范化任何未知值归一化到安全默认如tlsTier非auto/on一律回offstealth非off/on一律回autosrc/persisted-config.ts 中MAX_CONFIG_BYTES 1_000_000的体积上限超过 1MB 的config.json被视为损坏直接跳过防止意外大文件或恶意文件拖垮解析。可见范围约束 枚举白名单 失败回退到安全默认值是 golden 文档校验规则表在真实代码里的三种落地形态。多环境 Profile同一份文件、多套预设文档的 Profile 机制允许在同一文件内为不同环境预置多套配置# myapp.config.yaml profiles: development: server: port: 3000 logging: level: debug format: text database: name: myapp_dev staging: server: port: 8080 logging: level: info database: name: myapp_staging production: server: workers: 8 logging: level: warn format: json database: pool: max_connections: 50激活方式有两种——环境变量或命令行参数二选一MYAPP_PROFILEproduction myapp serve # 或 myapp serve --profileproductionProfile 的设计价值在于配置只写一份环境差异以增量覆盖表达。development把端口改 3000、日志调 debugproduction提高 worker 数到 8、日志收窄到 warn 并开 JSON 格式。主配置的字段在未被覆盖时依然生效避免为每个环境复制整份文件。wigolo 的对应做法需要说明的是从源码结构看wigolo 没有内建profiles文件级 Profile 机制它采用按进程覆盖的等价思路——用环境变量覆盖config.json中的基线值。例如切换 LLM 后端只需export WIGOLO_LLM_PROVIDERollama export WIGOLO_LLM_BASE_URLhttp://localhost:11434src/config.ts 中localLlm字段专门实现了三级取值off默认禁用、auto自动探测本地端点、或显式http(s)://URL任何其他值都归一化为offfail-safe。这正是同一份基线配置 按环境覆盖思想在无 Profile 系统下的替代实现。如果你的部署环境需要完整的多环境文件切换WIGOLO_CONFIG_PATH指向不同的config.json即可实现等价效果。热重载与变更生效边界文档允许配置变更不重启即生效config Config.load(watchTrue) config.on_change(logging.level) def on_log_level_change(old_value, new_value): logger.setLevel(new_value) logger.info(fLog level changed from {old_value} to {new_value})同时文档明确划出了可热重载字段与必须重启字段的边界支持热重载logging.level、logging.format、rate_limit.*、cache.ttl需要重启server.host、server.port、database.*这一划分是热重载设计中最容易被忽略、也最关键的工程决策只有进程内可安全重建的资源才允许运行时变更。监听地址、端口、连接池这类与内核资源绑定、或一旦建连就难以迁移的配置强行热更新只会引入隐蔽的失效状态因此宁可要求重启。wigolo 的生效语义wigolo 的配置采取启动时解析 进程内缓存的语义getConfig()将结果缓存到cachedConfig同一进程内后续读取都命中缓存。变更配置后需要重启进程使其生效测试代码则通过resetConfig()清空缓存以重新读取export function resetConfig(): void { cachedConfig null; // 同时重置 persisted-config 缓存使测试中修改 WIGOLO_CONFIG_PATH 或 // 写入新配置文件后下一次 getConfig() 能读到干净状态 resetPersistedConfig(); }这与 golden 文档server.host/server.port需要重启的边界保持一致——wigolo 将绝大多数配置都归入了需要重启这一类换来的是实现简单、行为可预测。它把热重载的复杂度排除在核心路径之外符合本地优先工具配置一次、长期运行的使用画像。密钥管理密钥永不落盘文档给出两条密钥管理原则。第一条是环境变量引用而非直接存值database: password_env: MYAPP_DB_PASSWORD auth: jwt: secret_env: MYAPP_JWT_SECRET配置文件中只记录从哪个环境变量取密钥密钥本身在运行时才注入。第二条是对接专用密钥后端secrets: backend: vault vault: address: https://vault.example.com path: secret/data/myapp token_env: VAULT_TOKENHashiCorp Vault 这类后端提供集中化的密钥存储、访问审计与轮换能力适合多服务、多环境的生产部署。wigolo 的密钥三道防线wigolo 在 src/persisted-config.ts 与 src/security/keychain.ts 中实现了比 golden 文档示例更细的密钥防护第一道写入路径的密钥黑名单。明确列出哪些字段永不允许落入config.jsonexport const SETTINGS_SECRETS_DENYLIST new Setstring([braveApiKey, githubToken]);任何writePersistedConfig调用在合并前都会剥掉这两个键防止 API Key 以明文形式持久化到磁盘。第二道代理/求解器/阅读器 URL 的凭据拆分。对于proxyUrl、solverUrl、hostedReaderUrl这类可能内联user:pass的 URL写入时用processCredentialUrls把 userinfo 剥离出来存入 OS 钥匙串磁盘上只保留无凭据的 URL读取时若发现手工编辑的config.json里内嵌了凭据会剥离并告警而不会静默使用if (mode read) { // 手工编辑的 config.json 绝不能在运行时被静默使用其中的内联凭据 warnings.push([wigolo] ${key} in config.json embedded a credential inline; ignoring it. ...); }第三道文件权限与原子写入。atomicWrite用临时文件 rename保证写入不撕裂并以0o600仅属主可读写权限落盘const CONFIG_FILE_MODE 0o600; writeFileSync(tmp, JSON.stringify(cfg, null, 2), { mode: CONFIG_FILE_MODE }); renameSync(tmp, configPath);对照 golden 文档可以发现同一原则贯穿始终配置文件不是密钥仓库——要么通过环境变量间接引用要么交给钥匙串/Vault 等专用设施。golden 文档如何量化评估从写得好到提取得好作为 wigolo 提取基准的参考目标docs-003.md的工程价值还在于它参与了自动化的质量度量。在 benchmarks/extraction/runner.ts 中每个 manifest 条目都会经历读取 HTML fixture → 调用extractContent(html, url)src/extraction/pipeline.ts→ 与 golden Markdown 对比计算指标的流程const result await extractContent(html, entry.url); const metrics computeMetrics(result.markdown, golden);benchmarks/extraction/metrics.ts 定义了五类量化指标Precision / Recall基于 tokenizer.ts 的归一化分词后做集合重叠计算——提取结果中命中 golden 的 token 占比为精确率golden 中被子集覆盖的 token 占比为召回率F1精确率与召回率的调和平均衡量综合质量ROUGE-L基于最长公共子序列LCS的相似度能感知内容的顺序结构标题数匹配countHeadings用/^#{1,6}\s/gm统计 Markdown 标题数量比对提取结果与 golden 的标题结构是否一致链接数匹配countLinks统计非图片的 Markdown 链接数量。此外 per-category.ts 还会对比 legacy 管线extractContent与 v1 路由提取器的逐类别 F1 差值并设有质量门禁聚合 F1 不得低于 legacy单类别 F1 跌幅不得超过 3%否则判定 FAIL。这套体系意味着像docs-003.md这样结构完整、层级清晰的配置文档既是理想配置文档长什么样的范本也是网页 → Markdown 提取管线是否达标的客观标尺。好的配置文档清晰的标题层级、完整的参数表、可复制的代码块天然就是好的提取基准。小结一份ReadTheDocs 风格的配置文档其本质是对工程上反复验证过的配置体系设计原则的固化分层合并、确定性优先级——默认值兜底、环境/命令行逐级覆盖多格式文件 统一内部模型——YAML/TOML 都映射为类型化配置对象机械可推导的环境变量命名——点路径转大写下划线键即文档加载即校验——必填、范围、枚举三类约束在启动时拒绝坏配置Profile 增量覆盖——一份文件表达多环境差异热重载划分生效边界——只对可安全重建的资源开绿灯密钥与配置分离——环境引用或专用后端永不落盘。在 wigolo 仓库中golden/docs-003.md 是这套原则的参考答案而 src/config.ts 与 src/persisted-config.ts 则展示了同样的原则如何在真实项目中被精简、加固与落地三层优先级env config.json default、按字段独立解析、密钥黑名单与钥匙串拆分、0o600原子写入、白名单校验与失败回退。对照阅读两者既能掌握配置系统设计的通用方法论也能看到本地优先工具如何在零配置可用与深度可调之间取得平衡。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 分层配置系统完全指南：从 wigolo 提取基准中的 ReadTheDocs 风格配置文档到真实实现
分层配置系统完全指南从 wigolo 提取基准中的 ReadTheDocs 风格配置文档到真实实现【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo本文以 wigolo 仓库提取基准extraction benchmark中的参考文档 golden/docs-003.md 为骨架系统讲解一套完整的ReadTheDocs 风格分层配置系统包括六层配置来源与优先级、YAML/TOML 文件格式、环境变量映射、命令行覆盖、编程式访问、Schema 校验、多环境 Profile、热重载与密钥管理同时以 wigolo 真实的配置实现src/config.ts、src/persisted-config.ts作为仓库侧佐证帮助读者理解分层配置在真实项目中的落地方式以及这份 golden 文档在自动化评估网页内容提取质量时扮演的角色。文档定位一份作为参考答案的配置文档首先需要明确docs-003.md在仓库中的性质。它位于 benchmarks/extraction/fixtures/golden/ 目录下是 wigolo 提取基准benchmarks/extraction的golden金标准文件之一而不是 wigolo 官方文档的一部分。它的作用是为给定的 HTML 测试页面提供理想提取结果的参考答案让提取管线有可量化对标的对象。从 manifest.json 可以看到对应条目{ id: docs-003, url: https://docs.example.com/cli/commands, category: docs, htmlFixturePath: html/docs-003.html, goldenPath: golden/docs-003.md, expectedExtractor: defuddle, tags: [cli, reference] }该条目属于docs文档站类别模拟的是CLI 命令参考 / 配置文档类页面期望由defuddle提取器命中。同目录下的docs-002.md是 MDN 风格的 API 参考文档而docs-003.md则是 ReadTheDocs 风格的项目配置文档——两者共同说明golden 文件刻意模拟了真实世界中的主流文档写作风格。正因为这份文档本身技术内容完整、结构清晰它也是一份极佳的分层配置系统教学素材适合在讲解配置体系时作为范本展开。配置来源与优先级六层合并的确定性顺序文档开篇即给出核心设计配置系统采用分层layered方式多个来源的设置按既定优先级合并。六个来源按优先级从低到高排列内置默认值built-in defaults系统级配置文件/etc/myapp/config.yaml用户级配置文件~/.config/myapp/config.yaml项目级配置文件./myapp.config.yaml环境变量MYAPP_*前缀命令行参数优先级更高的来源会覆盖低优先级来源从而保证默认值可用、环境可裁剪、最终以命令行为准。wigolo 的真实分层佐证wigolo 的配置解析同样遵循分层 确定优先级的思路但精简为更贴近本地优先工具的三层。官方文档 docs/configuration.md 明确写出environment variable ~/.wigolo/config.json built-in default并且指出Env vars win per-field, so you can persist a baseline inconfig.jsonand override one knob per process.WIGOLO_CONFIG_PATHrelocates the config file itself.环境变量按字段优先因此你可以在config.json中持久化基线配置并按进程覆盖某一个旋钮WIGOLO_CONFIG_PATH可重定位配置文件本身。在源码 src/config.ts 中getConfig()的注释与实现进一步印证了这一层级// Load persisted settings once. Precedence per field: // explicit env var config.json value built-in default const { settings } readPersistedConfig(defaultConfigPath());其中defaultConfigPath()定义在 src/persisted-config.tsexport function defaultConfigPath(): string { return process.env.WIGOLO_CONFIG_PATH ?? join(homedir(), .wigolo, config.json); }也就是说golden 文档中系统级 → 用户级 → 项目级 → 环境变量的递减层级在 wigolo 中被收敛为内置默认值 → 单个 JSON 配置文件 → 环境变量的简洁模型而WIGOLO_CONFIG_PATH相当于把配置文件在哪里这个决策本身也交给了环境变量。配置文件格式YAML 与 TOML文档给出了配置文件的两种主流格式YAML完整功能与 TOML简化示例。YAML完整示例与字段语义# myapp.config.yaml server: host: 0.0.0.0 port: 8080 workers: 4 timeout: 30s max_request_size: 10MB database: driver: postgres host: localhost port: 5432 name: myapp_production pool: min_connections: 5 max_connections: 20 idle_timeout: 300s logging: level: info format: json output: stderr file: enabled: false path: /var/log/myapp/app.log max_size: 100MB max_backups: 5 compress: true cache: backend: redis redis: url: redis://localhost:6379/0 prefix: myapp: ttl: 3600 memory: max_items: 10000 max_size: 256MB auth: jwt: secret_env: MYAPP_JWT_SECRET expiration: 3600 refresh_expiration: 86400 algorithm: HS256 oauth: enabled: false providers: [] rate_limit: enabled: true window: 60s max_requests: 100 by: ip whitelist: - 127.0.0.1 - ::1逐块解读各字段的语义server 块定义服务监听地址与资源预算。host默认监听所有接口0.0.0.0port为服务端口workers表示并发工作进程数默认取 CPU 核数timeout为请求超时max_request_size限制单请求体积上限。database 块连接信息与连接池参数。driver支持postgres、mysql、sqlitepool.min_connections/pool.max_connections控制连接池伸缩范围idle_timeout回收空闲连接。logging 块日志级别debug/info/warn/error、输出格式json或文本、输出目标stderr/文件以及文件轮转参数max_size、max_backups、compress。cache 块backend在redis/memory/memcached间选择redis 后端带 URL、key 前缀与 TTL内存后端带条目数与容量上限。auth 块JWT 的密钥通过secret_env间接引用环境变量而不是直接写入文件expiration/refresh_expiration控制令牌有效期algorithm指定签名算法OAuth 默认关闭。rate_limit 块按window时间窗口、max_requests上限、by: ip维度做限流whitelist放行本机回环地址。TOML 与多格式支持同样的配置也可以用 TOML 表达文档给出 server 与 database 两个块的对照[server] host 0.0.0.0 port 8080 workers 4 timeout 30s [database] driver postgres host localhost port 5432 name myapp_production [database.pool] min_connections 5 max_connections 20 idle_timeout 300s要点TOML 用[块名]表达嵌套层级[database.pool]即 YAML 中的database.pool对象时长类字段在 YAML 中写作30s、在 TOML 中写作30s字符串——多格式支持的关键是内部统一转换为带类型的运行时值。对照 wigolo数据目录、监听与日志旋钮wigolo 的配置字段虽未采用 YAML 文件但语义上高度对应。以下映射来自 src/config.ts 中的默认值与解析逻辑golden 文档配置项wigolo 对应字段默认值说明server.host/server.portdaemonHost127.0.0.1/daemonPort3333守护进程监听地址与端口server.timeoutfetchTimeoutMs10000等一批超时旋钮按场景细分fetch、playwright、challenge-completion、search stage budget 等database数据存储dataDir~/.wigolo缓存库、模型、密钥、插件、shell 历史的根目录logging.level/logging.formatlogLevelinfo/logFormatjson支持debug/info/warn/error与json/textcache.ttlcacheTtlSearch86400/cacheTtlContent604800搜索缓存与内容缓存分别设 TTL秒rate_limit.*crawlConcurrency/crawlDelayMs、crawlPrivateConcurrency/crawlPrivateDelayMs抓取的并发度与礼貌性限速例如 src/config.ts 中daemonPort: envInt(WIGOLO_DAEMON_PORT, 3333, settings, daemonPort), daemonHost: (() { const raw envStr(WIGOLO_DAEMON_HOST, 127.0.0.1, settings, daemonHost); return raw?.trim() || 127.0.0.1; })(),可见监听地址 端口 超时这一组服务器配置的范式在 wigolo 中以 daemon 子系统的形式真实存在。环境变量映射点路径到全大写下划线文档规定所有配置项都可通过环境变量设置规则是用MYAPP_前缀 点路径转全大写下划线。例如server.host对应MYAPP_SERVER_HOST。原文映射表完整如下Config PathEnvironment VariableExampleserver.hostMYAPP_SERVER_HOST0.0.0.0server.portMYAPP_SERVER_PORT8080database.hostMYAPP_DATABASE_HOSTdb.example.comdatabase.pool.max_connectionsMYAPP_DATABASE_POOL_MAX_CONNECTIONS50logging.levelMYAPP_LOGGING_LEVELdebugcache.backendMYAPP_CACHE_BACKENDredisauth.jwt.expirationMYAPP_AUTH_JWT_EXPIRATION7200这种点路径 ↔ 全大写下划线的机械映射带来的好处是配置的键与环境的键一一对应、无需额外映射表即可推导且天然避免了在代码里手写一堆互不相干的魔法字符串。wigolo 的 env 辅助函数族wigolo 在 src/config.ts 中实现了同构的一套辅助函数并且统一遵循同一优先级规则explicit env var persisted config.json value built-in default显式环境变量 持久化 config.json 值 内置默认值function envStr(key, fallback, settings, settingsKey?): string | null function envInt(key, fallback, settings, settingsKey?): number function envIntArray(key, fallback, settings, settingsKey?): number[] function envBool(key, fallback, settings, settingsKey?): boolean它们的行为可以对照 golden 文档理解envStr取字符串值环境变量存在即返回否则看持久化配置再退回默认值。envInt解析整数parseInt失败NaN时静默回退到默认值——相当于隐式的类型校验与容错。envBool布尔判定不是false且不是0即为真并支持从config.json读取布尔值。envIntArray把逗号分隔字符串解析为数字数组如WIGOLO_BOOTSTRAP_BACKOFF_SECONDS任一项非法即整体回退默认值。由于 wigolo 使用WIGOLO_/SEARCH_/LOG_等独立前缀而非统一MYAPP_具体键并非点路径转下划线而是显式书写例如export WIGOLO_DAEMON_PORT9090 export WIGOLO_TLS_TIERauto export LOG_LEVELdebug export LOG_FORMATjson export WIGOLO_MULTI_QUERY_MAX10使用方式与 golden 文档中的MYAPP_*环境变量完全同构只是键名命名风格不同。命令行参数覆盖最高优先级的最后一道闸文档给出命令行覆盖示例myapp serve --server.port9090 --logging.leveldebug --database.hostremote-db--server.port9090这类点路径参数与环境变量遵循同一套键体系因而学习成本极低命令行参数位于优先级最顶端适合临时调试、一次性运行或 CI 场景。wigolo 的配置命令行wigolo 将配置即命令落到了 docs/configuration.md 描述的wigolo config子命令上wigolo config # 交互式设置 shellTUI wigolo config --plain # 打印当前设置并退出 wigolo config --plain --json wigolo config --set searchBackendhybrid # 无交互地更新单个设置 wigolo config --storage # 存储占用地图 wigolo config --cache-stats wigolo config --export settings.json # 导出密钥除外 wigolo config --import settings.json wigolo config --cleanup cache # cache|embeddings|models|browser|searxng其中--set keyvalue正是 golden 文档中--server.port9090这种单键覆盖思路的交互式版本不动整个文件只更新一个字段。wigolo dashboard是wigolo config的别名。值得注意的原则是密钥LLM Key、代理凭据永远不会进入config.json而是存放在操作系统钥匙串中详见下文密钥管理一节。编程式访问配置文档提供的 Python 编程式访问示例from myapp.config import Config config Config.load() # 点号访问 port config.server.port # 8080 db_host config.database.host # localhost # 字典式访问 port config[server][port] # 8080 # 带默认值获取 workers config.get(server.workers, default2) # 判断键是否存在 has_cache config.has(cache.backend) # True这套 API 设计提供了三种互补能力属性式点号访问config.server.port适合编译期/静态检查友好的代码字典式访问config[server][port]适合动态键get带默认值与has存在性判断适合可选配置。整体目标是把配置变成与普通对象无异的类型化数据而不是到处散落的全局变量。wigolo 的等价物getConfig()wigolo 的 TypeScript 侧对应物是 src/config.ts 的getConfig()读取一次持久化配置后构建完整的Config对象并缓存在模块级变量cachedConfig中后续所有字段都通过config.daemonPort、config.cacheTtlSearch这样的属性直接访问let cachedConfig: Config | null null; export function getConfig(): Config { if (cachedConfig) return cachedConfig; // 按字段执行 env config.json default 的优先级合并 const { settings } readPersistedConfig(defaultConfigPath()); cachedConfig { /* ... 每个字段逐一解析 ... */ }; return cachedConfig; }Config接口在 src/config.ts 中定义了 100 余个字段并配以详细注释——例如searchPrewarmBrowser注明Latency-only — no change to results仅影响延迟、不影响结果searchMojeekProbeOnly解释为何让 mojeek 引擎保持仅探测以规避 403 惩罚。这展示了高质量配置项注释的写法不仅说明是什么还解释为什么。配置校验与约束规则文档强调配置在加载时按 Schema 校验。示例代码如下from myapp.config import Config, ValidationError try: config Config.load() except ValidationError as e: print(fConfiguration error: {e}) for error in e.errors: print(f - {error.path}: {error.message})ValidationError.errors是错误列表每项含path出错的配置路径与message原因便于精准定位与批量上报。原文的完整校验规则表如下FieldTypeRequiredDefaultConstraintsserver.hoststringNo0.0.0.0Valid IP or hostnameserver.portintegerNo80801-65535server.workersintegerNoCPU count1-256server.timeoutdurationNo30s1s-300sdatabase.driverstringYes-postgres,mysql,sqlitedatabase.hoststringYes-Valid hostnamedatabase.portintegerNoDriver default1-65535database.namestringYes-Non-emptydatabase.pool.min_connectionsintegerNo51-max_connectionsdatabase.pool.max_connectionsintegerNo20min_connections-1000logging.levelstringNoinfodebug,info,warn,errorcache.backendstringNomemorymemory,redis,memcached这张表浓缩了配置校验的最佳实践显式标注必填Required 列如database.driver/database.host/database.name必填缺失即拒绝启动范围约束Constraints 列端口 1-65535、worker 数 1-256、超时 1s-300s、连接池min ≤ max枚举约束driver、logging.level、cache.backend只能在固定集合内取值有意义的默认值默认值本身即免配置可用的体现。wigolo 中的校验式防护wigolo 未引入独立的 JSON Schema 校验器但把同样的防护分散在解析层。最典型的是 src/config.ts 中的validateTlsBrowser白名单校验WIGOLO_TLS_BROWSER的值会被透传给 Rust napi 绑定未经验证的值可能导致原生层崩溃因此只接受chrome|firefox|safari|edge|opera加数字版本号的格式const TLS_BROWSER_PATTERN /^(chrome|firefox|safari|edge|opera)_\d$/; export function validateTlsBrowser(raw: string | null | undefined, fallback: string): string { if (!raw) return fallback; if (TLS_BROWSER_PATTERN.test(raw)) return raw; process.stderr.write( [wigolo] WIGOLO_TLS_BROWSER${JSON.stringify(raw)} is not in the allowlist ... falling back to ${fallback}\n, ); return fallback; }与之配套的防护还包括envInt对非法整数的 NaN 回退类型容错tlsTier/stealth/localLlm等枚举字段的规范化任何未知值归一化到安全默认如tlsTier非auto/on一律回offstealth非off/on一律回autosrc/persisted-config.ts 中MAX_CONFIG_BYTES 1_000_000的体积上限超过 1MB 的config.json被视为损坏直接跳过防止意外大文件或恶意文件拖垮解析。可见范围约束 枚举白名单 失败回退到安全默认值是 golden 文档校验规则表在真实代码里的三种落地形态。多环境 Profile同一份文件、多套预设文档的 Profile 机制允许在同一文件内为不同环境预置多套配置# myapp.config.yaml profiles: development: server: port: 3000 logging: level: debug format: text database: name: myapp_dev staging: server: port: 8080 logging: level: info database: name: myapp_staging production: server: workers: 8 logging: level: warn format: json database: pool: max_connections: 50激活方式有两种——环境变量或命令行参数二选一MYAPP_PROFILEproduction myapp serve # 或 myapp serve --profileproductionProfile 的设计价值在于配置只写一份环境差异以增量覆盖表达。development把端口改 3000、日志调 debugproduction提高 worker 数到 8、日志收窄到 warn 并开 JSON 格式。主配置的字段在未被覆盖时依然生效避免为每个环境复制整份文件。wigolo 的对应做法需要说明的是从源码结构看wigolo 没有内建profiles文件级 Profile 机制它采用按进程覆盖的等价思路——用环境变量覆盖config.json中的基线值。例如切换 LLM 后端只需export WIGOLO_LLM_PROVIDERollama export WIGOLO_LLM_BASE_URLhttp://localhost:11434src/config.ts 中localLlm字段专门实现了三级取值off默认禁用、auto自动探测本地端点、或显式http(s)://URL任何其他值都归一化为offfail-safe。这正是同一份基线配置 按环境覆盖思想在无 Profile 系统下的替代实现。如果你的部署环境需要完整的多环境文件切换WIGOLO_CONFIG_PATH指向不同的config.json即可实现等价效果。热重载与变更生效边界文档允许配置变更不重启即生效config Config.load(watchTrue) config.on_change(logging.level) def on_log_level_change(old_value, new_value): logger.setLevel(new_value) logger.info(fLog level changed from {old_value} to {new_value})同时文档明确划出了可热重载字段与必须重启字段的边界支持热重载logging.level、logging.format、rate_limit.*、cache.ttl需要重启server.host、server.port、database.*这一划分是热重载设计中最容易被忽略、也最关键的工程决策只有进程内可安全重建的资源才允许运行时变更。监听地址、端口、连接池这类与内核资源绑定、或一旦建连就难以迁移的配置强行热更新只会引入隐蔽的失效状态因此宁可要求重启。wigolo 的生效语义wigolo 的配置采取启动时解析 进程内缓存的语义getConfig()将结果缓存到cachedConfig同一进程内后续读取都命中缓存。变更配置后需要重启进程使其生效测试代码则通过resetConfig()清空缓存以重新读取export function resetConfig(): void { cachedConfig null; // 同时重置 persisted-config 缓存使测试中修改 WIGOLO_CONFIG_PATH 或 // 写入新配置文件后下一次 getConfig() 能读到干净状态 resetPersistedConfig(); }这与 golden 文档server.host/server.port需要重启的边界保持一致——wigolo 将绝大多数配置都归入了需要重启这一类换来的是实现简单、行为可预测。它把热重载的复杂度排除在核心路径之外符合本地优先工具配置一次、长期运行的使用画像。密钥管理密钥永不落盘文档给出两条密钥管理原则。第一条是环境变量引用而非直接存值database: password_env: MYAPP_DB_PASSWORD auth: jwt: secret_env: MYAPP_JWT_SECRET配置文件中只记录从哪个环境变量取密钥密钥本身在运行时才注入。第二条是对接专用密钥后端secrets: backend: vault vault: address: https://vault.example.com path: secret/data/myapp token_env: VAULT_TOKENHashiCorp Vault 这类后端提供集中化的密钥存储、访问审计与轮换能力适合多服务、多环境的生产部署。wigolo 的密钥三道防线wigolo 在 src/persisted-config.ts 与 src/security/keychain.ts 中实现了比 golden 文档示例更细的密钥防护第一道写入路径的密钥黑名单。明确列出哪些字段永不允许落入config.jsonexport const SETTINGS_SECRETS_DENYLIST new Setstring([braveApiKey, githubToken]);任何writePersistedConfig调用在合并前都会剥掉这两个键防止 API Key 以明文形式持久化到磁盘。第二道代理/求解器/阅读器 URL 的凭据拆分。对于proxyUrl、solverUrl、hostedReaderUrl这类可能内联user:pass的 URL写入时用processCredentialUrls把 userinfo 剥离出来存入 OS 钥匙串磁盘上只保留无凭据的 URL读取时若发现手工编辑的config.json里内嵌了凭据会剥离并告警而不会静默使用if (mode read) { // 手工编辑的 config.json 绝不能在运行时被静默使用其中的内联凭据 warnings.push([wigolo] ${key} in config.json embedded a credential inline; ignoring it. ...); }第三道文件权限与原子写入。atomicWrite用临时文件 rename保证写入不撕裂并以0o600仅属主可读写权限落盘const CONFIG_FILE_MODE 0o600; writeFileSync(tmp, JSON.stringify(cfg, null, 2), { mode: CONFIG_FILE_MODE }); renameSync(tmp, configPath);对照 golden 文档可以发现同一原则贯穿始终配置文件不是密钥仓库——要么通过环境变量间接引用要么交给钥匙串/Vault 等专用设施。golden 文档如何量化评估从写得好到提取得好作为 wigolo 提取基准的参考目标docs-003.md的工程价值还在于它参与了自动化的质量度量。在 benchmarks/extraction/runner.ts 中每个 manifest 条目都会经历读取 HTML fixture → 调用extractContent(html, url)src/extraction/pipeline.ts→ 与 golden Markdown 对比计算指标的流程const result await extractContent(html, entry.url); const metrics computeMetrics(result.markdown, golden);benchmarks/extraction/metrics.ts 定义了五类量化指标Precision / Recall基于 tokenizer.ts 的归一化分词后做集合重叠计算——提取结果中命中 golden 的 token 占比为精确率golden 中被子集覆盖的 token 占比为召回率F1精确率与召回率的调和平均衡量综合质量ROUGE-L基于最长公共子序列LCS的相似度能感知内容的顺序结构标题数匹配countHeadings用/^#{1,6}\s/gm统计 Markdown 标题数量比对提取结果与 golden 的标题结构是否一致链接数匹配countLinks统计非图片的 Markdown 链接数量。此外 per-category.ts 还会对比 legacy 管线extractContent与 v1 路由提取器的逐类别 F1 差值并设有质量门禁聚合 F1 不得低于 legacy单类别 F1 跌幅不得超过 3%否则判定 FAIL。这套体系意味着像docs-003.md这样结构完整、层级清晰的配置文档既是理想配置文档长什么样的范本也是网页 → Markdown 提取管线是否达标的客观标尺。好的配置文档清晰的标题层级、完整的参数表、可复制的代码块天然就是好的提取基准。小结一份ReadTheDocs 风格的配置文档其本质是对工程上反复验证过的配置体系设计原则的固化分层合并、确定性优先级——默认值兜底、环境/命令行逐级覆盖多格式文件 统一内部模型——YAML/TOML 都映射为类型化配置对象机械可推导的环境变量命名——点路径转大写下划线键即文档加载即校验——必填、范围、枚举三类约束在启动时拒绝坏配置Profile 增量覆盖——一份文件表达多环境差异热重载划分生效边界——只对可安全重建的资源开绿灯密钥与配置分离——环境引用或专用后端永不落盘。在 wigolo 仓库中golden/docs-003.md 是这套原则的参考答案而 src/config.ts 与 src/persisted-config.ts 则展示了同样的原则如何在真实项目中被精简、加固与落地三层优先级env config.json default、按字段独立解析、密钥黑名单与钥匙串拆分、0o600原子写入、白名单校验与失败回退。对照阅读两者既能掌握配置系统设计的通用方法论也能看到本地优先工具如何在零配置可用与深度可调之间取得平衡。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考