# https://github.com/degoog-org/degoog 项目说明书

生成时间：2026-07-02 15:58:26 UTC

## 目录

- [Overview, Tech Stack and Deployment](#page-overview)
- [Extension System: Engines, Plugins, Themes, Transports and Store](#page-extensions)
- [Settings UI, Search Pipeline and Indexer](#page-search-indexer)
- [Security, Localization, Shortcuts and Easter-Egg Features](#page-security-community)

<a id='page-overview'></a>

## Overview, Tech Stack and Deployment

### 相关页面

相关主题：[Extension System: Engines, Plugins, Themes, Transports and Store](#page-extensions), [Settings UI, Search Pipeline and Indexer](#page-search-indexer), [Security, Localization, Shortcuts and Easter-Egg Features](#page-security-community)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/degoog-org/degoog/blob/main/README.md)
- [package.json](https://github.com/degoog-org/degoog/blob/main/package.json)
- [Dockerfile](https://github.com/degoog-org/degoog/blob/main/Dockerfile)
- [entrypoint.sh](https://github.com/degoog-org/degoog/blob/main/entrypoint.sh)
- [docker-compose.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose.yml)
- [docker-compose-examples/simple.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/simple.yml)
- [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
- [src/client/modules/tabs/tab-search.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/tabs/tab-search.ts)
- [src/client/modules/wizard/steps.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts)
- [src/client/animations/skeleton.ts](https://github.com/degoog-org/degoog/blob/main/src/client/animations/skeleton.ts)
- [src/client/utils/pagination.ts](https://github.com/degoog-org/degoog/blob/main/src/client/utils/pagination.ts)
- [src/server/extensions/commands/builtins/wikipedia/template.html](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/template.html)
</details>

# 项目概览、技术栈与部署

## 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 采用经典的**前后端分离 + 插件化**架构：

| 层级 | 路径 | 职责 |
|------|------|------|
| 客户端 | `src/client/` | 浏览器侧 UI、状态管理、骨架屏、分页、标签搜索、向服务端发起请求 |
| 服务端 | `src/server/` | 搜索引擎代理、扩展命令、Wikipedia 等 Slot 插件、缓存、签名代理 URL |
| 共享 | `package.json` 等 | 依赖管理、构建脚本、运行时元数据 |

### 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`）。其数据流可表示为：

```mermaid
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 与搜索流程](./engines-and-search-flow.md)
- [Slot 插件开发指南](./slot-plugin-development.md)
- [设置与安全（环境变量、密码门控）](./settings-and-security.md)
- [Docker 自托管最佳实践](./docker-self-hosting.md)

---

<a id='page-extensions'></a>

## Extension System: Engines, Plugins, Themes, Transports and Store

### 相关页面

相关主题：[Overview, Tech Stack and Deployment](#page-overview), [Settings UI, Search Pipeline and Indexer](#page-search-indexer), [Security, Localization, Shortcuts and Easter-Egg Features](#page-security-community)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
- [src/server/extensions/commands/builtins/wikipedia/template.html](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/template.html)
- [src/server/extensions/commands/builtins/wikipedia/style.css](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/style.css)
- [src/server/extensions/commands/builtins/wikipedia/locales/en.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/en.json)
- [src/server/extensions/commands/builtins/wikipedia/locales/fr.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/fr.json)
- [src/client/modules/wizard/steps.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts)
- [src/client/types/extension.ts](https://github.com/degoog-org/degoog/blob/main/src/client/types/extension.ts)
- [README.md](https://github.com/degoog-org/degoog/blob/main/README.md)
</details>

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

## 概述

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]()。

```mermaid
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](https://degoog-org.github.io/community-extensions)。README 明确警告：这些扩展"仅经过**初步**审核，安装运行安全由用户自行负责" 资料来源：[README.md]()。向导末尾还设有独立的安全步骤，链接到 [docs/env.html](https://degoog-org.github.io/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 插件详解](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
- [环境变量与认证配置](https://degoog-org.github.io/docs/env.html)
- [社区扩展商店](https://degoog-org.github.io/community-extensions)

---

<a id='page-search-indexer'></a>

## Settings UI, Search Pipeline and Indexer

### 相关页面

相关主题：[Overview, Tech Stack and Deployment](#page-overview), [Extension System: Engines, Plugins, Themes, Transports and Store](#page-extensions), [Security, Localization, Shortcuts and Easter-Egg Features](#page-security-community)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/client/modules/wizard/steps.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts)
- [src/client/modules/renderer/render.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/renderer/render.ts)
- [src/client/modules/renderer/render-sidebar.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/renderer/render-sidebar.ts)
- [src/client/utils/search/search-actions-page.ts](https://github.com/degoog-org/degoog/blob/main/src/client/utils/search/search-actions-page.ts)
- [src/client/types/index.ts](https://github.com/degoog-org/degoog/blob/main/src/client/types/index.ts)
- [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
- [src/server/extensions/commands/builtins/wikipedia/style.css](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/style.css)
- [src/server/extensions/commands/builtins/wikipedia/template.html](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/template.html)
- [src/server/extensions/commands/builtins/wikipedia/locales/en.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/en.json)
- [src/server/extensions/commands/builtins/at-a-glance/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/at-a-glance/index.ts)

</details>

# 设置 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]()。

整体数据流如下：

```mermaid
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]()

---

<a id='page-security-community'></a>

## Security, Localization, Shortcuts and Easter-Egg Features

### 相关页面

相关主题：[Overview, Tech Stack and Deployment](#page-overview), [Extension System: Engines, Plugins, Themes, Transports and Store](#page-extensions), [Settings UI, Search Pipeline and Indexer](#page-search-indexer)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
- [src/server/extensions/commands/builtins/wikipedia/template.html](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/template.html)
- [src/server/extensions/commands/builtins/wikipedia/style.css](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/style.css)
- [src/server/extensions/commands/builtins/wikipedia/locales/en.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/en.json)
- [src/server/extensions/commands/builtins/wikipedia/locales/fr.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/fr.json)
- [src/server/extensions/commands/builtins/wikipedia/locales/it.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/it.json)
- [src/server/extensions/commands/builtins/wikipedia/locales/he.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/he.json)
- [src/server/extensions/commands/builtins/at-a-glance/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/at-a-glance/index.ts)
- [src/server/extensions/commands/builtins/at-a-glance/locales/he.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/at-a-glance/locales/he.json)
- [src/server/extensions/commands/builtins/help/locales/he.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/help/locales/he.json)
- [src/server/extensions/commands/builtins/uuid/locales/he.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/uuid/locales/he.json)
- [src/client/modules/wizard/steps.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts)
- [src/client/modules/tabs/tab-search.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/tabs/tab-search.ts)
- [package.json](https://github.com/degoog-org/degoog/blob/main/package.json)
- [README.md](https://github.com/degoog-org/degoog/blob/main/README.md)
</details>

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

本页面汇总 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 文件。当前检出的多语言资源如下：

| 语言 | 资源路径示例 | 关键键 | 备注 |
| --- | --- | --- | --- |
| 英语 (en) | `src/server/extensions/commands/builtins/wikipedia/locales/en.json` | `name`, `description`, `view-on-wikipedia` | 默认语言资源来源：[src/server/extensions/commands/builtins/wikipedia/locales/en.json:1-7]() |
| 法语 (fr) | `.../wikipedia/locales/fr.json` | `name`, `description`, `read-more` | "Wikipédia" 资料来源：[src/server/extensions/commands/builtins/wikipedia/locales/fr.json:1-6]() |
| 意大利语 (it) | `.../wikipedia/locales/it.json` | `name`, `description`, `read-more` | 资料来源：[src/server/extensions/commands/builtins/wikipedia/locales/it.json:1-6]() |
| 希伯来语 (he) | `.../wikipedia/locales/he.json`、`.../help/locales/he.json`、`.../uuid/locales/he.json`、`.../at-a-glance/locales/he.json` | `name`, `description`, `view-on-wikipedia` | RTL 文案，例：`"name": "ויקיפדיה"`。资料来源：[src/server/extensions/commands/commands/builtins/wikipedia/locales/he.json:1-7]()、`[src/server/extensions/commands/builtins/uuid/locales/he.json:1-6]()`、`[src/server/extensions/commands/builtins/help/locales/he.json:1-7]()`、`[src/server/extensions/commands/builtins/at-a-glance/locales/he.json:1-6]()` |

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](https://github.com/degoog-org/degoog/blob/main/src/client/modules/tabs/tab-search.ts)
- 设置向导流程：[src/client/modules/wizard/steps.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts)
- 依赖与构建：[package.json](https://github.com/degoog-org/degoog/blob/main/package.json)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: degoog-org/degoog; human_manual_source: deepwiki_human_wiki -->