项目概览、技术栈与部署

1. 项目定位与设计理念

degoog 是一个高度可定制化的元搜索引擎聚合器（meta-search aggregator），其核心目标是在不依赖 Google 等单一商业搜索引擎的前提下，为用户提供聚合式的搜索体验。README.md 明确指出，本项目受 searxng 启发，是"一个模块化、更轻量的替代方案"。其核心理念可以概括为三句话：

• 核心尽量简单（"the core will stay as simple as it gets"）；
• 按需扩展（plugins、themes、engines、transports 都可以自由添加）；
• 去中心化、无追踪（项目名 degoog 已表明立场）。

项目以社区驱动的方式持续迭代，最新稳定 Beta 版为 0.22.0，该版本的一个重大变更引入了对设置页面的强制密码保护——首次启动时服务端会自动生成一个临时密码，由用户保管并自行修改（资料来源：README.md）。这一改动回应了社区对"设置可被未授权访问"的担忧。

社区反馈中频繁出现的功能请求（例如 #22 "Open in new tab"、#25 域名屏蔽与替换、#8 Maps 结果支持）也表明，本项目的核心是建立在"用户可控、可扩展、可主题化"的三大支柱之上的。

2. 技术栈与代码组织

从源码结构看，degoog 采用经典的前后端分离 + 插件化架构：

2.1 语言与运行时

服务端模块以 TypeScript 编写（见 src/server/extensions/commands/builtins/wikipedia/index.ts），声明了 interface WikiPage、AsyncTtlCache 等强类型定义，并使用 Signal、AbortController 等现代浏览器/Node API 控制外部请求的超时（资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts）。

2.2 客户端架构

客户端通过 src/client/modules/tabs/tab-search.ts 中的 performTabSearch() 调度搜索流程，先渲染骨架屏（skeletonResults、skeletonSidebar、skeletonImageGrid），再调用流式搜索接口（performStreamingSearch），并按需挂载媒体预览（setupMediaObserver）。其数据流可表示为：

flowchart LR
  A[用户输入查询] --> B[performTabSearch]
  B --> C[渲染 skeleton 占位]
  B --> D[performStreamingSearch]
  D --> E[renderResults / renderSidebar]
  E --> F[prependKnowledgePanels]
  F --> G[Wikipedia / Glance Slot]

2.3 插件系统

服务端通过 Slot 插件（如 Wikipedia）扩展搜索体验。以 Wikipedia 为例，它声明 position: SlotPanelPosition.KnowledgePanel，根据查询长度（2~100 字符）决定是否触发 trigger()，命中后通过 MediaWiki API 拉取摘要，并使用服务端模板 template.html 渲染卡片（资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts、src/server/extensions/commands/builtins/wikipedia/template.html）。

2.4 国际化

服务端内置多语言文案目录（locales/en.json、fr.json、he.json、it.json），每个 Slot 插件各自携带自己的翻译文件，便于独立分发。

2.5 设置向导

src/client/modules/wizard/steps.ts 定义了首次启动时的引导流程，引导用户安装至少一个 engine、autocomplete、theme、plugin 与 transport，再进入设置面板（资料来源：src/client/modules/wizard/steps.ts）。

3. 部署形态

degoog 支持本地 Node 运行与Docker / docker-compose 两种主要部署方式，后者更适合自托管（self-hosting）。

3.1 Docker 部署

项目根目录提供标准化的容器化资产：

• Dockerfile：构建运行镜像的基础定义；
• entrypoint.sh：容器启动脚本，负责生成/读取临时密码、注入环境变量与初始化配置；
• docker-compose.yml：标准化的多服务编排入口；
• docker-compose-examples/simple.yml：最小化部署示例，便于快速试用。

这种分层设计（生产 compose + 示例 compose + 启动脚本）让用户既可以"开箱即用"，又可以按需叠加反代、持久化卷、网络隔离等组件。社区文档中关于环境变量的说明位于 https://degoog-org.github.io/docs/env.html，被引导流程中"security"步骤直接引用（资料来源：src/client/modules/wizard/steps.ts）。

3.2 设置与安全

自 0.22.0 起，进入 /settings 必须输入密码。entrypoint.sh 会在首次启动时输出临时密码到日志，部署者应立即登录并在设置面板中修改。这一机制直接影响 Docker 部署流程——运维人员需要从容器日志中获取初始凭据（资料来源：README.md）。

3.3 扩展来源

部署完成后，用户可在设置页 → Store 中启用社区维护的扩展（engines、autocomplete、themes、plugins、transports）。README.md 强调这些扩展仅经过初步审查，用户需自行评估其安全性（资料来源：README.md）。

4. 常见运行模式与注意事项

• 流式搜索：客户端通过 performStreamingSearch 在结果陆续返回时增量渲染，配合 skeletonFeedCards 等骨架屏提升感知性能（资料来源：src/client/animations/skeleton.ts、src/client/modules/tabs/tab-search.ts）。
• 分页：buildPaginationHtml 限制可见页码最多 10 个，居中显示当前页（资料来源：src/client/utils/pagination.ts）。
• 超时与缓存：外部 API（如 Wikipedia）使用 AbortController 控制超时，并通过 useCache 抽象建立 TTL 缓存，避免重复请求（资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts）。
• 升级注意：升级到 0.22.0 及以上版本时，需要从启动日志读取临时密码，否则无法进入设置面板修改核心配置。

See Also

• Engines 与搜索流程
• Slot 插件开发指南
• 设置与安全（环境变量、密码门控）
• Docker 自托管最佳实践

扩展系统：引擎、插件、主题、传输层与商店

概述

degoog 是一个可深度定制的元搜索引擎聚合器，灵感源自 searxng，核心设计哲学是"核心保持精简、能力来自扩展" 资料来源：README.md。引擎（engines）、插件（plugins）、主题（themes）、传输层（transports）、自动补全（autocomplete）与快捷方式（shortcuts）均以独立模块形式注入；客户端通过统一的 ExtensionMeta 元数据模型按类别消费，服务器端则按子目录组织实现，使官方与社区贡献者能在不改动核心代码的前提下扩展搜索体验 资料来源：src/client/types/extension.ts。

扩展类型与组件拓扑

扩展系统的总体组件关系如下。客户端 UI 在加载时按类别拉取 ExtensionMeta，服务器端按子目录管理实现；插件（如 wikipedia）通过 SlotPlugin 接口挂载到搜索结果侧的"知识面板"位置，向搜索结果注入 HTML/CSS 而无需修改核心渲染管线 资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts。

graph LR
  subgraph 客户端
    UI[搜索界面]
    META[ExtensionMeta]
    TYPE[extension.ts 类型契约]
  end
  subgraph 服务端扩展
    ENG[engines/]
    CMD[commands/builtins/]
    THM[themes/]
    TRP[transports/]
  end
  UI --> META
  META --> TYPE
  ENG --> META
  CMD --> META
  THM --> META
  TRP --> META
  CMD -.SlotPlugin.-> UI

插件结构与生命周期

以内置的 wikipedia 插件为例，插件实现遵循统一的四阶段生命周期 资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts：

1. 初始化（init）：接收 PluginContext，保存模板渲染器、代理签名函数 signProxyUrl，并通过 ctx.useCache<WikiPage>(WIKI_NAMESPACE, WIKI_TTL_MS) 创建带 TTL 的异步缓存，避免重复访问上游。
2. 设置模式（settingsSchema）：声明用户可配置字段。wikipedia 仅暴露 domain 字段（默认 en.wikipedia.org），其说明文本明确要求输入完整的 *.wikipedia.org 域名。
3. 触发判定（trigger）：根据查询字符串决定是否激活。wikipedia 拒绝长度小于 2 或大于 100 的查询，命中缓存即直接返回，未命中时调用 MediaWiki Action API。
4. 执行（execute）：返回 { title, html }，HTML 由 template.html 渲染。模板中所有外链使用 target="_blank" rel="noopener noreferrer"，恰好回应了社区中"在新标签页打开"的功能请求（#22） 资料来源：src/server/extensions/commands/builtins/wikipedia/template.html。

当 MediaWiki 未返回缩略图时，插件回退到 Wikidata 实体查询（wbgetentities）以补全 logo，并通过相同的缓存与 AbortController 超时机制容错 资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts。自定义样式位于 style.css，通过 CSS 变量（--link-color、--text-secondary、--radius 等）与主题系统解耦 资料来源：src/server/extensions/commands/builtins/wikipedia/style.css。

国际化

每个内置插件携带 locales/ 子目录，按 ISO 语言代码组织 JSON 翻译。wikipedia 插件已提供 en、fr、he、it 等语言包，使用 wikipedia.name / wikipedia.description / wikipedia.view-on-wikipedia 等键值 资料来源：src/server/extensions/commands/builtins/wikipedia/locales/en.json 资料来源：src/server/extensions/commands/builtins/wikipedia/locales/fr.json。相同模式应用于 help 与 uuid 命令，表明这是 degoog 的一贯约定——新增插件时只需复制该目录结构即可获得多语言支持。

商店、安装与安全

首次运行时，向导（src/client/modules/wizard/steps.ts）按顺序引导用户安装：repos（仓库源）、engines、autocomplete、themes、plugins、transports。每一步 storeInstallStep 会校验"已安装数量"——例如 engines 步骤要求至少安装 1 个引擎，未达标时阻止进入下一阶段，确保搜索功能可用 资料来源：src/client/modules/wizard/steps.ts。

商店支持官方与社区两类来源，社区扩展托管在 community-extensions。README 明确警告：这些扩展"仅经过初步审核，安装运行安全由用户自行负责" 资料来源：README.md。向导末尾还设有独立的安全步骤，链接到 docs/env.html，帮助用户理解环境变量与认证机制——这与 0.22.0 版本强制设置密码的策略一致 资料来源：src/client/modules/wizard/steps.ts。

客户端类型契约

src/client/types/extension.ts 定义了客户端可见的扩展契约，是 UI 与扩展实现之间的稳定边界 资料来源：src/client/types/extension.ts：

• ExtensionMeta：通用元数据载体，按类别划分为 engines、themes、transports、autocomplete、shortcuts。
• SearchBarAction：搜索栏动作，类型字段限定为 navigate、bang、custom 三种。
• Command：命令行/bang 触发器，含 trigger、aliases、naturalLanguage 等字段。
• EngineRegistry：引擎清单与默认开关映射（defaults），每个引擎含 primaryType 与 searchTypes[]，便于不同搜索类型（网页/图片/新闻）的多态路由，也为社区请求的"地图"结果类型（#8）和"按域名屏蔽结果"（#25）等扩展方向提供了清晰的扩展点。

总结

degoog 的扩展系统由"类型化注册表 + 插槽式插件 + 商店 + 向导"四层抽象构成。开发者若希望为搜索结果侧栏注入新的信息源，遵循 SlotPlugin 接口（init/settingsSchema/trigger/execute）即可；若希望让用户从商店一键安装，只需在向导对应步骤注册新的 storeInstallStep。核心保持精简、扩展按需加载，是该项目与同类聚合器最显著的差异。

参见

• Wikipedia 插件详解
• 环境变量与认证配置
• 社区扩展商店

设置 UI、搜索管线与索引器

目的与适用范围

本页覆盖 degoog 中相互协作的三个层次：设置 UI 向导（首次配置引导）、搜索管线（结果分页、侧栏注入、命令插槽）以及索引器类型契约（前后端共享的 TS 类型入口）。

设置 UI 向导

src/client/modules/wizard/steps.ts 编排首启配置流程：

• 通过 storeInstallStep(...) 工厂生成"添加仓库并安装"步骤，覆盖 engine/autocomplete/theme/plugin/transport 五类组件，配合 liveCountSelector 实时统计；尾部由 install.done 收尾。资料来源：src/client/modules/wizard/steps.ts:1-50。
• 之后以 tab: "engines"|"autocomplete"|"server" 三类手写步骤将用户引导至对应设置面板，附带 popoverAnchor: "bottom-right" 与 interactive: true 标记以启用内嵌操作。资料来源：src/client/modules/wizard/steps.ts:50-90。
• 自 0.22.0 起设置需密码保护；security-title/security-body 步骤通过 https://degoog-org.github.io/docs/env.html 引导管理员配置环境变量与临时密码。资料来源：src/client/modules/wizard/steps.ts:80-110。

搜索管线

结果渲染与分页

src/client/modules/renderer/render.ts 是渲染入口，从 ../../constants 导入 MAX_PAGE，从 ../../state 读取当前查询；其导出 renderSidebar、renderSidebarSuggestions、prependKnowledgePanels（转自 render-sidebar.ts）以及 appendSlotPanels、clearSlotPanels、renderSlotPanels（转自 render-slots.ts）。模块内的 _resultActionsFlags() 通过 window.__DEGOOG_RESULT_ACTIONS__ 暴露 blockUi/replaceUi/scoreUi 等旗标，由 buildResultContext(r, index) 构造每条结果上下文。资料来源：src/client/modules/renderer/render.ts:1-50。

src/client/utils/search/search-actions-page.ts 中的 goToPage(pageNum)：

1. 若目标页等于 state.currentPage 则直接返回；资料来源：src/client/utils/search/search-actions-page.ts:1-20。
2. 用 skeletonImageGrid() 或 skeletonResults()（按 isImageSearchType(state.currentType) 选）填充 #results-list，清空 #pagination；
3. 调用 buildSearchUrl 与 buildSearchBody 重组查询；当 state.postMethodEnabled 为真时使用 POST /api/search 并附带 searchAuthHeaders()，否则走 GET。资料来源：src/client/utils/search/search-actions-page.ts:20-60。

侧栏与知识面板

src/client/modules/renderer/render-sidebar.ts 写入 #results-sidebar，包含"引擎性能"折叠区与"相关搜索"列表（来源为 data.relatedSearches ?? state.currentRelatedSearches，由 state.displaySearchSuggestions 控制显隐）。prependKnowledgePanels(panels: SlotPanel[]) 在侧栏顶部插入可折叠面板，当 window.innerWidth >= 768 时自动展开；视觉上借助 sidebarAccordion(title, html) 复用。资料来源：src/client/modules/renderer/render-sidebar.ts:1-50。

命令插槽：`at-a-glance` 与 `wikipedia`

两个内置命令作为 SlotPanel 注入侧栏顶部：

• at-a-glance（src/server/extensions/commands/builtins/at-a-glance/index.ts）：从 context.results 中用 _pickBestResult 选出最佳结果；当 looksLikeProse(best.snippet) 为真时直接使用，否则调用 context.fetch 抓取正文并截取到 settings.maxLength。设置项 fetchContent 与 fetchTimeoutSeconds 控制抓取行为；当 Wikipedia 槽位被 isDisabled(WIKIPEDIA_SETTINGS_ID) 标记禁用时，_pickBestResult 会跳过与其并置的逻辑。资料来源：src/server/extensions/commands/builtins/at-a-glance/index.ts:30-100。
• wikipedia（src/server/extensions/commands/builtins/wikipedia/index.ts）：触发条件为查询长度 2–100；缓存层使用 AsyncTtlCache<WikiPage>（命名空间 WIKI_NAMESPACE、TTL WIKI_TTL_MS）。_fetchWikipedia 调用 MediaWiki 的 query API，参数包括 exintro=1、explaintext=1、exsentences=6、pithumbsize=300、pilicense=any、prop=extracts|pageimages|pageprops|info|description，缺失缩略图时再走 Wikidata wbgetentities；请求附 User-Agent: degoog/1.0 (+https://github.com/degoog-org/degoog) 与 Api-User-Agent。设置项 domain 指向具体 *.wikipedia.org（非法值回落到默认域）。资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts:40-130。

模板 template.html 输出 .wiki-card → .wiki-overview + .wiki-body，链接统一加 target="_blank" rel="noopener noreferrer"，被 style.css 中的 .wiki-title/.wiki-desc/.wiki-extract/.wiki-footer-link/.wiki-thumb 等类美化。多语言在 locales/{en,fr,it,he}.json 中维护 wikipedia.name、wikipedia.description、wikipedia.view-on-wikipedia 三键。资料来源：src/server/extensions/commands/builtins/wikipedia/template.html:1-20、src/server/extensions/commands/builtins/wikipedia/style.css:1-60、src/server/extensions/commands/builtins/wikipedia/locales/en.json:1-10。

整体数据流如下：

flowchart LR
    A[用户搜索或翻页] --> B{postMethodEnabled?}
    B -- 是 --> C[POST /api/search]
    B -- 否 --> D[GET buildSearchUrl]
    C --> E[server 聚合 ScoredResult]
    D --> E
    E --> F[render.ts 主结果列表]
    E --> G[插槽命令: at-a-glance, wikipedia]
    G --> H[SlotPanel html]
    F --> I[#results-list]
    H --> J[render-sidebar prependKnowledgePanels]
    E --> K[render-sidebar 相关搜索 + 引擎统计]
    J --> L[#results-sidebar]
    K --> L

索引器类型契约

src/client/types/index.ts 通过 export * from "./indexer" 把 Indexer 子系统的 TS 类型（设置项 schema、字段类型、键名等）暴露给前端。本页所涉及的"设置"、"引擎"与"自动补全"选项卡在表单校验时复用这些契约，运行时实现在 src/server 子树中独立维护，本页面不展开。资料来源：src/client/types/index.ts:1-10。

已知限制与社区反馈

• 域级屏蔽 / 替换（issue #25）：来自 SearXNG 的用户希望按域（含正则）隐藏结果并把 reddit.com 替换为 troddit。该类能力将注入 render.ts 中 __DEGOOG_RESULT_ACTIONS__ 暴露的 blockUi/replaceUi 旗标，由 buildResultContext 在每条结果上应用。资料来源：src/client/modules/renderer/render.ts:30-80。
• 新标签页打开（issue #22）：模板已通过 <a target="_blank" rel="noopener noreferrer"> 实现该 UX（Wikipedia 卡片即如此），普通结果卡片模板可复用同一模式。资料来源：src/server/extensions/commands/builtins/wikipedia/template.html:5-15。
• Maps 结果类型（issue #8）：当前 isImageSearchType(state.currentType) 只区分图片与文本两类渲染分支，新增 Maps 需在 MAX_PAGE 等常量与骨架屏工具中补充对应分支。资料来源：src/client/modules/renderer/render.ts:1-30。
• 失败模式：当 Wikipedia API 返回 missing、pageid === undefined 或 extract 为空时，_fetchWikipedia 返回 null 并由 logger.debug(...) 记录；Wikidata 抓取同样有 AbortController + TIMEOUT_MS 截止保护。资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts:80-130。

参见

• Wikipedia Knowledge Panel Slot
• At-a-Glance Knowledge Panel Slot
• Result Renderer & Actions
• Indexer Subsystem

安全性、本地化、快捷命令与彩蛋功能

本页面汇总 degoog 中与 安全（强制设置密码）、多语言本地化、用户快捷 bang 命令 以及 彩蛋式内置命令（Wikipedia 知识卡片、At-a-Glance、UUID、Help） 相关的设计与实现。这些能力分散在插件层（SlotPlugin）、UI 层（Wizard、locales）与 HTTP 层之间，通过统一的 useCache / signProxyUrl / i18n key 协议组合到一起。资料来源：README.md:1-20。

社区中关于"在新标签页打开结果 (#22)"、"域名级屏蔽/替换 (#25)"等讨论，与本页所覆盖的设置密码、链接外跳安全策略以及 target="_blank" 渲染方式直接相关，下文会在合适位置反向引用。

1. 安全机制：设置强制密码

在最新版本 [Stable Beta] 0.22.0 的发行说明中，明确 "having a password for settings mandatory" —— 服务首次启动时会自动生成一个临时密码，并在用户首次进入设置页时强制其修改。这是 degoog 在"无登录元搜索"基础上引入的最轻量级访问控制层。资料来源：README.md:Latest Release 段落。

设置向导的最后两步直接体现了这一策略：

• security-step：标题与正文由国际化键 settings-page.wizard.security-title / security-body 提供，并附带一份外部文档链接 https://degoog-org.github.io/docs/env.html，向运维人员解释环境变量、密钥与 cookie 的关系。资料来源：src/client/modules/wizard/steps.ts:1-30。
• done-step：向用户确认所有偏好项（引擎、自动补全、主题、插件、传输、密码）已就绪。

2. 本地化：多语言资源结构

命令层和 UI 层共用 locales/<lang>.json 翻译包，按"插件.键"二级命名空间独立分发，便于插件作者携带自己的 i18n 文件。当前检出的多语言资源如下：

Wikipedia 插件本地化的语义细节值得注意：法语、意大利语只声明 read-more 作为外部链接文案，而英语、希伯来语则使用更通用的 view-on-wikipedia。这一差异意味着实现国际化文案时，应基于 t() 调用并提供完整 fallback。资料来源：src/server/extensions/commands/builtins/wikipedia/locales/en.json:1-7 对比 src/server/extensions/commands/builtins/wikipedia/locales/it.json:1-6。

3. 快捷命令（bang）与彩蛋式内置命令

3.1 Wikipedia 知识卡片（彩蛋一）

wikipediaSlot 是一个 SlotPanelPosition.KnowledgePanel 类型的内置命令。触发条件是查询词经 trim() 后长度在 2-100 之间，并能从所选 Wikipedia 镜像返回非空 extract。资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts:1-50。

性能与隐私方面有三处亮点：

1. TTL 缓存：以 ${host}:${query.toLowerCase()} 为键，通过 ctx.useCache(WIKI_NAMESPACE, WIKI_TTL_MS) 共享跨会话缓存，避免重复访问 API。资料来源：src/server/extensions/commands/builtins/wikipedia/index.ts:10-35`。
2. 图片签名代理：当 thumbnail 来自 Wikibase 时，URL 会经 signProxyUrl() 重写，防止客户端真实 IP 泄漏给 wikimedia.org。资料来源：[src/server/extensions/commands/builtins/wikipedia/index.ts:1-30] 中 _proxyImageUrl`。
3. 外链安全：模板里的 <a> 全部使用 target="_blank" rel="noopener noreferrer"。资料来源：src/server/extensions/commands/builtins/wikipedia/template.html:1-15、并配合 src/server/extensions/commands/builtins/wikipedia/style.css:1-30 中 .wiki-title:hover` 等样式。

3.2 At-a-Glance 摘要（彩蛋二）

at-a-glance 负责从搜索结果中挑选最优条目，抽取其摘要文本呈现到侧栏。其设置项 settingsSchema 暴露了 fetchContent、fetchTimeoutSeconds、maxLength 等旋钮，并提供 excerptMode 高级控制。资料来源：src/server/extensions/commands/builtins/at-a-glance/index.ts:1-30`。

当 fetchContent=true 时，插件会调 context.fetch 抓取整页，使用 looksLikeProse、stripSnippetPrefix 过滤垃圾文本；超时后回退到搜索片段（snippet），对网络抖动友好。资料来源：src/server/extensions/commands/builtins/at-a-glance/index.ts:10-30`。

3.3 Help、UUID 等"轻量彩蛋"

• Help 命令：列出所有可用 bang 命令，支持按类型前缀过滤；希伯来语版本提供 title, aliases, prefix-hint 等。资料来源：src/server/extensions/commands/builtins/help/locales/he.json:1-7`。
• UUID 命令：随机生成 UUID v4，提供"复制"按钮的本地化字符串。资料来源：src/server/extensions/commands/builtins/uuid/locales/he.json:1-6`。

这些命令通常以 !wiki、!help、!uuid、!glance 形式触发，被社区用户视作"小彩蛋"。同时，因为它们在 tab-search.ts 的搜索流程里通过 fetchSlotPanels 异步加载，能够与主流搜索结果同时呈现而不阻塞首屏。资料来源：src/client/modules/tabs/tab-search.ts:1-30 中 fetchSlotPanels` 调用。

4. 与社区议题的交叉

• #22 "Open in new tab"：用户希望结果外链默认 target="_blank"。Wikipedia 模板已经实现该行为，可作为通用渲染参考。资料来源：src/server/extensions/commands/builtins/wikipedia/template.html:1-15` 对照社区请求。
• #25 "Features Request"：searxng 用户提出的域名级屏蔽/替换、全局偏好，与 0.22.0 中"强制设置密码"为基础设施层铺路，预留了 instance-wide settings 的入口。资料来源：README.md:Latest Release 段落`。

参见

• 内置命令总览：src/server/extensions/commands/builtins/
• 搜索流程与 Slot 加载：src/client/modules/tabs/tab-search.ts
• 设置向导流程：src/client/modules/wizard/steps.ts
• 依赖与构建：package.json

Pitfall Log / 踩坑日志

项目：degoog-org/degoog

摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: random image results。

1. 安装坑 · 来源证据：[Bug]: random image results

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: random image results
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/degoog-org/degoog/issues/203 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

2. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -d --name degoog -p 4444:4444 -v ./data:/app/data -e DEGOOG_SETTINGS_PASSWORDS=changeme --restart unless-stopped ghcr.io/degoog-org/degoog:latest
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -d --name degoog -p 4444:4444 -v ./data:/app/data -e DEGOOG_SETTINGS_PASSWORDS=changeme --restart unless-stopped ghcr.io/degoog-org/degoog:latest
• 证据：identity.distribution | https://github.com/degoog-org/degoog | docker run -d --name degoog -p 4444:4444 -v ./data:/app/data -e DEGOOG_SETTINGS_PASSWORDS=changeme --restart unless-stopped ghcr.io/degoog-org/degoog:latest

3. 安装坑 · 来源证据：[Docs]: What is the Degoog engine?

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Docs]: What is the Degoog engine?
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/degoog-org/degoog/issues/173 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

4. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/degoog-org/degoog | host_targets=mcp_host, claude, cursor

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/degoog-org/degoog | README/documentation is current enough for a first validation pass.

6. 维护坑 · 来源证据：[Bug]: At-a-glance Plugins disappear once results fully load

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Bug]: At-a-glance Plugins disappear once results fully load
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/degoog-org/degoog/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。

7. 维护坑 · 来源证据：[Bug]: Defaulting to wrong language

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Bug]: Defaulting to wrong language
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/degoog-org/degoog/issues/142 | 来源类型 github_issue 暴露的待验证使用条件。

8. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/degoog-org/degoog | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/degoog-org/degoog | no_demo; severity=medium

10. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/degoog-org/degoog | no_demo; severity=medium

11. 安全/权限坑 · 来源证据：[Feature]: Hide AI Summary in case of LLM errors or timeouts

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Hide AI Summary in case of LLM errors or timeouts
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/degoog-org/degoog/issues/204 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

12. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/degoog-org/degoog | issue_or_pr_quality=unknown

13. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/degoog-org/degoog | release_recency=unknown