Hister 浏览器扩展完全指南自动索引浏览历史、qutebrowser 集成与认证配置【免费下载链接】histerYour own search engine项目地址: https://gitcode.com/GitHub_Trending/hi/hister本文是 Hister 浏览器扩展的完整技术指南覆盖扩展在 Chrome / Chromium / Edge / Firefox 与 qutebrowser 中的安装与配置、自动页面索引的采集策略、手动重新索引、键盘快捷键、搜索引擎结果追踪以及 Popup 与选项页的全部设置项。读完本文你将掌握如何让 Hister 在后台静默采集浏览内容、如何用访问令牌或浏览器会话完成认证、如何借助 skip 规则控制索引范围并理解扩展与 Hister 服务端之间完整的 API 调用链与底层实现原理。Hister 浏览器扩展是自动索引浏览历史的主要方式它安静地在后台运行随浏览过程把页面内容发送到你的 Hister 服务器。扩展只与你的 Hister 服务器通信绝不会联系任何第三方服务也不会访问你浏览的网站收集页面数据时下载页面 favicon 除外。安装Chrome / Chromium / Edge从 Chrome Web Store 安装 Hister 扩展。Firefox从 Firefox Add-ons 安装同时支持 Firefox for Android。qutebrowser使用内置的hister companion qutebrowser命令详见下文。安装完成后点击浏览器工具栏中的扩展图标打开 Popup确认 Server URL 是否正确。从仓库源码看扩展基于 Manifest V3 构建manifest.json声明了tabs、storage、cookies三项权限与*://*/*的主机权限并在commands中定义了三个浏览器级快捷键。首次启动时后台脚本会通过 settings.ts 中的ensureDefaultServerURL()把默认服务器地址http://127.0.0.1:4433/写入chrome.storage.local这也是 Hister 服务端默认监听的地址。qutebrowserqutebrowser companion 会把渲染后的页面标题、文本、HTML 和 favicon 提交给 Hister并持续监测单页应用SPA带来的内容变化。从配置的 Hister base URL 提供的页面会被自动忽略避免重复索引扩展自身的 Web UI对应isHisterPage判断见 companion.go。内置的hister companion qutebrowser命令通过本地 Qt WebEngine DevTools 端点接收标签页、导航和 DOM 更新事件。内容提取运行在隔离的 JavaScript 世界中随后 companion 直接把渲染后的内容提交给 Hister访问令牌永远不会注入到被检查的页面中。先关闭所有 qutebrowser 进程然后以仅回环loopback调试端点启动 qutebrowserQTWEBENGINE_REMOTE_DEBUGGING127.0.0.1:9222 qutebrowser在另一个终端运行 companionhister companion qutebrowser该命令使用常规 Hister 配置中的server.base_url与app.access_token。全局--server-url、--token、--client-timeout选项可以覆盖目标设置hister --server-url http://127.0.0.1:4433 \ --token replace-with-app-access-token \ companion qutebrowserDevTools 端点默认是http://127.0.0.1:9222。可以在qutebrowser子命令后使用--devtools-url、--label、--initial-delay、--debounce、--max-wait等参数调整其行为运行命令时加--help可查看全部选项。各参数的默认值定义在 options.go 的DefaultOptions()中并通过 companion.go 中的addQutebrowserCompanionFlags()暴露为 CLI flag参数默认值说明--devtools-urlhttp://127.0.0.1:9222qutebrowser DevTools HTTP 端点--label空附加到提交文档上的标签--initial-delay1s新加载页面提交前的延迟新页面加载后 1 秒提交--debounce10s页面内容更新后需要经过的静默期后续内容变更使用 10 秒静默期--max-wait30s持续变化页面允许推迟提交的最长时间默认 30 秒设为 0 可禁用上限--retry-delay30s提交失败后的重试延迟设为 0 可禁用重试--reconnect-delay3sDevTools 断线后重连的延迟--command-timeout10s单个 DevTools 命令的超时--request-timeout30sDevTools 发现与 favicon 请求的超时--max-favicon-bytes10485761 MiB允许接受的最大 favicon 响应体积在--max-wait生效时companion 对同一个页面记录更新开始时间静默期到期与最大等待时间二者取较早者触发提交scheduleUpdate中的maxDue逻辑保证持续产生 DOM 变化的页面最终仍会被提交而非无限期推迟。安全提示远程调试能对打开的浏览器页面拥有完全访问权限。companion 只接受 localhost 或回环 IP 的 DevTools 端点normalizeOptions中的isLoopbackHost校验绝不要把 Qt WebEngine 调试端口暴露到网络中。从源码层面看companion 的工作流程如下companion.go通过Target.setDiscoverTargets/Target.getTargets发现并Target.attachToTarget每个类型为page的目标在每个页面会话上启用Page与Runtime域并注册名为__histerCompanionChanged_随机后缀的 bindingbinding 绑定到名为hister-companion的隔离世界executionContextName页面脚本无法篡改通过Page.addScriptToEvaluateOnNewDocumentPage.createIsolatedWorldRuntime.evaluate注入 MutationObserver 脚本该脚本监听attributes、characterData、childList含 subtree并对load、hashchange、popstate事件去抖1 秒后触发变更信号收到Runtime.bindingCalled、Page.frameNavigated、Page.loadEventFired、Page.lifecycleEventDOMContentLoaded/load/networkIdle等事件后调度提取提取脚本在隔离世界中运行读取 title、innerText、URL、完整 HTML 与 favicon URL用 SHA-256 对URL HTML计算指纹pageFingerprint与上次指纹一致则跳过提交避免无意义重复索引favicon 只允许与页面同源且不超过--max-favicon-bytes会被转成 data URI 随文档提交连接意外断开时按--reconnect-delay自动重连run()中的重连循环。CDP 客户端cdp.go通过浏览器/json/version端点发现 WebSocket 调试地址并强制将连接保持在使用者指定的主机上即使 Chromium 通告的是通配地址防止被本地端点诱导到其他主机。功能自动页面索引扩展会采集可见页面包括页面标题、全文、HTML 和 favicon然后通过 Hister 的 API 发送到服务器。后台标签页中的页面在你查看时才会被采集。定时与触发策略核心实现在 content.ts轮询节奏页面保持可见期间扩展以 30 秒为起点检查内容变化无变化时检查间隔翻倍上限为 5 分钟minimumUpdateInterval 30s、maximumPollInterval 5min。导航防抖页面内导航后等待 1 秒静默再做检查navigationDebounce 1000且自动检查与提交在同一页面内至少间隔 30 秒。因此快速连续导航可能只会采集到最终页面状态。触发条件文本、标题、favicon 或页面元数据发生变化会触发一次更新stateChanged比较 url/text/title/faviconURL/metadata。预览检查节流仅外观性标记markup变化时会等待预览检查预览检查最多每 5 分钟一次previewCheckInterval 5min所以动画和不断变化的 HTML 属性不会持续触发索引。每次提交都包含当前完整 HTML供服务端提取与预览使用。隐藏标签页隐藏标签页时扩展捕获最后一次快照并停止轮询如果快照有变化会在剩余的提交延迟结束后提交。重新显示标签页时用全新内容恢复检查。关闭/导航离开关闭标签页或导航离开时立即把变化内容冲刷到扩展后台进程绕过剩余延迟未变化的内容不会重复提交。上述内容在visibilitychange捕获快照、cooldown()控制冲刷时机与pagehidepageLeaving置位、立即submit(snapshot)两个事件处理器中实现配合lastSubmissionAt保证同一页面两次提交间隔不低于 30 秒。支持的内容类型限定为text/html、application/xhtmlxml、text/plainPDF 则由后台脚本单独处理isPDFUrl识别以.pdf结尾的 URL通过api/add_pdf提交 base64 编码的 PDF 内容。后台脚本还会在收到Page.loadEventFired等事件后调用updateTabIcon根据 skip 规则命中情况把图标置灰。自动索引可以随时通过 Popup 中的开关暂停。关闭自动索引时后台会把图标变为灰色setGreyIcon对图标做灰度化处理便于直观确认当前页面处于跳过状态。手动重新索引Popup 中的Index this page now立即索引此页按钮会立即提交当前页面或 PDF即使自动索引被禁用或存在命中的 skip 规则时也是如此。索引键盘快捷键的行为相同。当你把某个域名排除在自动索引之外、却想保存该域名下的个别页面时这个功能非常有用。手动索引会随文档保存一条 skip 规则覆盖标记metadata.ignore_skip_rules: true见 background.ts因此重建索引后该文档仍能保留同时它不会改动你的 skip 规则和自动索引设置之后的自动提交仍然尊重这些规则。敏感内容检查与常规访问限制依然生效。键盘快捷键扩展定义了浏览器级的索引操作快捷键声明于 manifest.json 的commands由chrome.commands.onCommand分发到indexCurrentTab/disableIndexingForCurrentTab操作Windows / LinuxmacOS说明索引当前页面CtrlICommandI即使自动索引被禁用也会执行禁用当前页面索引CtrlBCommandB为当前精确 URL 添加 skip 规则禁用当前域名索引CtrlYCommandY为当前来源含 scheme 与域名添加 skip 规则成功的快捷键操作会在扩展图标上短暂显示✓徽标失败则显示!徽标setPreviouslyIndexedBadge/setErrorBadge2.5 秒后清除。URL 与域名 skip 规则的正则构造方式为URL 规则对完整 URL 做正则转义并追加$buildUrlSkipPattern域名规则则取new URL(url).origin作为锚定前缀buildDomainSkipPattern随后写入服务端api/rules的skip字段。后台会缓存 skip 规则正则 60 秒SKIP_RULES_TTL以降低对服务端的请求频率。浏览器快捷键可以在扩展的快捷键设置中修改Chrome / Chromium / Edge 打开chrome://extensions/shortcutsFirefox 打开about:addons进入扩展快捷键设置后编辑 Hister 的快捷键。搜索引擎结果追踪扩展会检测你在Google或DuckDuckGo上点击搜索结果的行为并把查询词连同结果的标题与 URL 一并记录从而在将来执行相同查询时能够提供该结果。实现位于 extract.tsGoogleExtractor匹配www.google.com/search页面中点击H3标题的搜索结果DuckDuckGoExtractor匹配duckduckgo.com首页点击的SPAN结果提取后通过api/history提交到服务端。Popup点击扩展图标即可打开 Popup快速访问最常用的控件控件说明自动索引开关启用或禁用自动页面索引设置立即保存Reindex Page重新索引页面按钮强制把当前页面重新提交到服务器Authenticate with Browser Session使用浏览器会话认证按钮当未使用访问令牌时复制已登录 Hister Web UI 的会话 Cookie 来认证扩展设置图标⚙展开内联表单无需打开完整选项页即可查看和更新 Server URL 与 Access TokenShow indicator for indexed pages显示已索引页面指示设置在已索引页面上显示✓徽标从 Popup 打开设置视图后可用Submit as public documents以公共文档提交设置把新索引的页面以用户 id0存储为公共文档扩展完成认证后出现任何操作后Popup 底部会出现状态横幅显示成功或错误反馈。如果服务器拒绝了最近一次提交扩展图标会显示!徽标保存有效设置后会清除它。已索引页面指示默认关闭。启用方法点击扩展图标 → 点击设置图标打开设置视图 → 打开Show indicator for indexed pages。启用后扩展会把当前页面与 Hister 服务器比对后台通过HEAD api/document?url...判断返回 200 表示已存在并在已入库的页面上保持可见的✓徽标。Popup 还提供了两个与索引控制相关的附加能力Label标签可为当前页面应用标签或保存为默认标签应用到后续索引的所有页面之后可用label:yourtext过滤搜索结果与SkipRuleActions为当前页面或域名添加 skip 规则、可选删除已索引的匹配文档这些操作经由后台的addSkipRule/checkSkipRule消息与api/rules、api/delete接口联动。选项页完整的选项页可通过浏览器扩展管理器访问右键扩展图标 →选项或进入扩展设置页面Chromechrome://extensions→ 找到 Hister →详细信息→扩展程序选项Firefoxabout:addons→ 找到 Hister →…菜单 →首选项连接设置设置项类型默认值说明Server URLstringhttp://127.0.0.1:4433/Hister 服务器的完整 URL含 scheme 与端口Custom Headersmap[string]string无随每个请求附加的 HTTP 头可用于反向代理认证或其他服务端要求Access Tokenstring无用于认证扩展请求的可选全局或个人访问令牌Submit as public documentsbool关把新索引的页面以用户 id 0 存储为公共文档该选项在认证后出现点击Save Settings应用配置。保存前扩展会调用GET /api/config校验连接URL 无效时会显示错误而不是保存成功见 Popup.svelte 与 Options.svelte 的save()逻辑。从网络层实现network.ts看每个请求都会携带存储的 Cookie 头Cookie与访问令牌X-Access-Token请求头当服务端返回 401/403 时扩展会尝试从浏览器读取并刷新已保存的服务器 Cookie 后重试一次避免会话过期导致索引中断。Custom Headers 中的所有头也会逐一附加到每个请求因此可以在扩展前面放置需要自定义认证头的反向代理。认证扩展支持访问令牌与浏览器会话两种认证方式。使用访问令牌在 Popup 设置或选项页中输入全局访问令牌或个人访问令牌然后保存设置即可。令牌通过X-Access-Token请求头随每个请求发送保存时扩展会调用GET /api/profile验证令牌有效性令牌被拒绝时会提示Settings saved, but the access token was rejected。使用浏览器会话当启用了 user handling多用户支持时可以改用 Hister Web 界面共享的会话 Cookie在同一个浏览器中登录 Hister Web 界面点击 Popup 或选项页中的Authenticate with Browser Session按钮。扩展会读取当前浏览器中该站点域名的活动会话 Cookiechrome.cookies.getAll序列化后存入histerCookies此后扩展就以你的用户账户提交页面。即使在 Web 界面中退出登录也无需重复此步骤。认证完成后Popup 设置与选项页都会显示Submit as public documents。开启后扩展提交的页面将以公共文档形式可见而不是只存储在你的用户账户下扩展会随文档提交附带X-Hister-Public: 1请求头服务端将这些文档以用户 id0存储getDocumentSubmissionHeaders见 background.ts。未认证用户 id 为 0时该开关会被自动关闭。故障排查扩展图标显示!徽标最近一次向服务器发送页面数据的尝试失败了。打开 Popup 查看具体错误。常见原因Hister 服务器未运行用hister listen启动它。Server URL填写错误确认与服务器启动时打印的地址一致默认http://127.0.0.1:4433/。启用了 user handling 但扩展未认证配置访问令牌或在登录 Web 界面后点击Authenticate with Browser Session。页面没有被索引确认 Popup 中的Automatic indexing自动索引已开启。检查服务器是否可达、URL 是否正确见上文。如果启用了 user handling确认扩展已经认证见上文。部分页面如chrome://…、about:…等浏览器内部页面无法被扩展访问会被静默跳过后台的updateTabIcon会直接忽略这些 URL 前缀。另外命中服务端 skip 规则时扩展会把图标置灰服务端返回 406包含敏感内容的页面会被拒绝并置灰服务端返回 422这两类情况均不属于提交错误。小结Hister 浏览器扩展把浏览即索引变成现实MV3 扩展在后台以 30 秒起、最长 5 分钟的智能轮询策略采集可见页面结合导航防抖、预览检查节流与隐藏/关闭时的快照冲刷机制在内容变化与资源消耗之间取得平衡qutebrowser 用户则可以通过基于 Qt WebEngine DevTools 的 companion 获得同等的渲染后页面索引能力。配合访问令牌或浏览器会话认证、skip 规则、手动重新索引与键盘快捷键你可以精确控制哪些页面进入索引并在多用户场景下决定文档归属公共还是个人空间。上述行为均有仓库源码佐证webui/ext/src、cmd/companion/qutebrowser如需深入调试可继续阅读对应实现与 user handling 文档。【免费下载链接】histerYour own search engine项目地址: https://gitcode.com/GitHub_Trending/hi/hister创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Hister 浏览器扩展完全指南自动索引浏览历史、qutebrowser 集成与认证配置【免费下载链接】histerYour own search engine项目地址: https://gitcode.com/GitHub_Trending/hi/hister本文是 Hister 浏览器扩展的完整技术指南覆盖扩展在 Chrome / Chromium / Edge / Firefox 与 qutebrowser 中的安装与配置、自动页面索引的采集策略、手动重新索引、键盘快捷键、搜索引擎结果追踪以及 Popup 与选项页的全部设置项。读完本文你将掌握如何让 Hister 在后台静默采集浏览内容、如何用访问令牌或浏览器会话完成认证、如何借助 skip 规则控制索引范围并理解扩展与 Hister 服务端之间完整的 API 调用链与底层实现原理。Hister 浏览器扩展是自动索引浏览历史的主要方式它安静地在后台运行随浏览过程把页面内容发送到你的 Hister 服务器。扩展只与你的 Hister 服务器通信绝不会联系任何第三方服务也不会访问你浏览的网站收集页面数据时下载页面 favicon 除外。安装Chrome / Chromium / Edge从 Chrome Web Store 安装 Hister 扩展。Firefox从 Firefox Add-ons 安装同时支持 Firefox for Android。qutebrowser使用内置的hister companion qutebrowser命令详见下文。安装完成后点击浏览器工具栏中的扩展图标打开 Popup确认 Server URL 是否正确。从仓库源码看扩展基于 Manifest V3 构建manifest.json声明了tabs、storage、cookies三项权限与*://*/*的主机权限并在commands中定义了三个浏览器级快捷键。首次启动时后台脚本会通过 settings.ts 中的ensureDefaultServerURL()把默认服务器地址http://127.0.0.1:4433/写入chrome.storage.local这也是 Hister 服务端默认监听的地址。qutebrowserqutebrowser companion 会把渲染后的页面标题、文本、HTML 和 favicon 提交给 Hister并持续监测单页应用SPA带来的内容变化。从配置的 Hister base URL 提供的页面会被自动忽略避免重复索引扩展自身的 Web UI对应isHisterPage判断见 companion.go。内置的hister companion qutebrowser命令通过本地 Qt WebEngine DevTools 端点接收标签页、导航和 DOM 更新事件。内容提取运行在隔离的 JavaScript 世界中随后 companion 直接把渲染后的内容提交给 Hister访问令牌永远不会注入到被检查的页面中。先关闭所有 qutebrowser 进程然后以仅回环loopback调试端点启动 qutebrowserQTWEBENGINE_REMOTE_DEBUGGING127.0.0.1:9222 qutebrowser在另一个终端运行 companionhister companion qutebrowser该命令使用常规 Hister 配置中的server.base_url与app.access_token。全局--server-url、--token、--client-timeout选项可以覆盖目标设置hister --server-url http://127.0.0.1:4433 \ --token replace-with-app-access-token \ companion qutebrowserDevTools 端点默认是http://127.0.0.1:9222。可以在qutebrowser子命令后使用--devtools-url、--label、--initial-delay、--debounce、--max-wait等参数调整其行为运行命令时加--help可查看全部选项。各参数的默认值定义在 options.go 的DefaultOptions()中并通过 companion.go 中的addQutebrowserCompanionFlags()暴露为 CLI flag参数默认值说明--devtools-urlhttp://127.0.0.1:9222qutebrowser DevTools HTTP 端点--label空附加到提交文档上的标签--initial-delay1s新加载页面提交前的延迟新页面加载后 1 秒提交--debounce10s页面内容更新后需要经过的静默期后续内容变更使用 10 秒静默期--max-wait30s持续变化页面允许推迟提交的最长时间默认 30 秒设为 0 可禁用上限--retry-delay30s提交失败后的重试延迟设为 0 可禁用重试--reconnect-delay3sDevTools 断线后重连的延迟--command-timeout10s单个 DevTools 命令的超时--request-timeout30sDevTools 发现与 favicon 请求的超时--max-favicon-bytes10485761 MiB允许接受的最大 favicon 响应体积在--max-wait生效时companion 对同一个页面记录更新开始时间静默期到期与最大等待时间二者取较早者触发提交scheduleUpdate中的maxDue逻辑保证持续产生 DOM 变化的页面最终仍会被提交而非无限期推迟。安全提示远程调试能对打开的浏览器页面拥有完全访问权限。companion 只接受 localhost 或回环 IP 的 DevTools 端点normalizeOptions中的isLoopbackHost校验绝不要把 Qt WebEngine 调试端口暴露到网络中。从源码层面看companion 的工作流程如下companion.go通过Target.setDiscoverTargets/Target.getTargets发现并Target.attachToTarget每个类型为page的目标在每个页面会话上启用Page与Runtime域并注册名为__histerCompanionChanged_随机后缀的 bindingbinding 绑定到名为hister-companion的隔离世界executionContextName页面脚本无法篡改通过Page.addScriptToEvaluateOnNewDocumentPage.createIsolatedWorldRuntime.evaluate注入 MutationObserver 脚本该脚本监听attributes、characterData、childList含 subtree并对load、hashchange、popstate事件去抖1 秒后触发变更信号收到Runtime.bindingCalled、Page.frameNavigated、Page.loadEventFired、Page.lifecycleEventDOMContentLoaded/load/networkIdle等事件后调度提取提取脚本在隔离世界中运行读取 title、innerText、URL、完整 HTML 与 favicon URL用 SHA-256 对URL HTML计算指纹pageFingerprint与上次指纹一致则跳过提交避免无意义重复索引favicon 只允许与页面同源且不超过--max-favicon-bytes会被转成 data URI 随文档提交连接意外断开时按--reconnect-delay自动重连run()中的重连循环。CDP 客户端cdp.go通过浏览器/json/version端点发现 WebSocket 调试地址并强制将连接保持在使用者指定的主机上即使 Chromium 通告的是通配地址防止被本地端点诱导到其他主机。功能自动页面索引扩展会采集可见页面包括页面标题、全文、HTML 和 favicon然后通过 Hister 的 API 发送到服务器。后台标签页中的页面在你查看时才会被采集。定时与触发策略核心实现在 content.ts轮询节奏页面保持可见期间扩展以 30 秒为起点检查内容变化无变化时检查间隔翻倍上限为 5 分钟minimumUpdateInterval 30s、maximumPollInterval 5min。导航防抖页面内导航后等待 1 秒静默再做检查navigationDebounce 1000且自动检查与提交在同一页面内至少间隔 30 秒。因此快速连续导航可能只会采集到最终页面状态。触发条件文本、标题、favicon 或页面元数据发生变化会触发一次更新stateChanged比较 url/text/title/faviconURL/metadata。预览检查节流仅外观性标记markup变化时会等待预览检查预览检查最多每 5 分钟一次previewCheckInterval 5min所以动画和不断变化的 HTML 属性不会持续触发索引。每次提交都包含当前完整 HTML供服务端提取与预览使用。隐藏标签页隐藏标签页时扩展捕获最后一次快照并停止轮询如果快照有变化会在剩余的提交延迟结束后提交。重新显示标签页时用全新内容恢复检查。关闭/导航离开关闭标签页或导航离开时立即把变化内容冲刷到扩展后台进程绕过剩余延迟未变化的内容不会重复提交。上述内容在visibilitychange捕获快照、cooldown()控制冲刷时机与pagehidepageLeaving置位、立即submit(snapshot)两个事件处理器中实现配合lastSubmissionAt保证同一页面两次提交间隔不低于 30 秒。支持的内容类型限定为text/html、application/xhtmlxml、text/plainPDF 则由后台脚本单独处理isPDFUrl识别以.pdf结尾的 URL通过api/add_pdf提交 base64 编码的 PDF 内容。后台脚本还会在收到Page.loadEventFired等事件后调用updateTabIcon根据 skip 规则命中情况把图标置灰。自动索引可以随时通过 Popup 中的开关暂停。关闭自动索引时后台会把图标变为灰色setGreyIcon对图标做灰度化处理便于直观确认当前页面处于跳过状态。手动重新索引Popup 中的Index this page now立即索引此页按钮会立即提交当前页面或 PDF即使自动索引被禁用或存在命中的 skip 规则时也是如此。索引键盘快捷键的行为相同。当你把某个域名排除在自动索引之外、却想保存该域名下的个别页面时这个功能非常有用。手动索引会随文档保存一条 skip 规则覆盖标记metadata.ignore_skip_rules: true见 background.ts因此重建索引后该文档仍能保留同时它不会改动你的 skip 规则和自动索引设置之后的自动提交仍然尊重这些规则。敏感内容检查与常规访问限制依然生效。键盘快捷键扩展定义了浏览器级的索引操作快捷键声明于 manifest.json 的commands由chrome.commands.onCommand分发到indexCurrentTab/disableIndexingForCurrentTab操作Windows / LinuxmacOS说明索引当前页面CtrlICommandI即使自动索引被禁用也会执行禁用当前页面索引CtrlBCommandB为当前精确 URL 添加 skip 规则禁用当前域名索引CtrlYCommandY为当前来源含 scheme 与域名添加 skip 规则成功的快捷键操作会在扩展图标上短暂显示✓徽标失败则显示!徽标setPreviouslyIndexedBadge/setErrorBadge2.5 秒后清除。URL 与域名 skip 规则的正则构造方式为URL 规则对完整 URL 做正则转义并追加$buildUrlSkipPattern域名规则则取new URL(url).origin作为锚定前缀buildDomainSkipPattern随后写入服务端api/rules的skip字段。后台会缓存 skip 规则正则 60 秒SKIP_RULES_TTL以降低对服务端的请求频率。浏览器快捷键可以在扩展的快捷键设置中修改Chrome / Chromium / Edge 打开chrome://extensions/shortcutsFirefox 打开about:addons进入扩展快捷键设置后编辑 Hister 的快捷键。搜索引擎结果追踪扩展会检测你在Google或DuckDuckGo上点击搜索结果的行为并把查询词连同结果的标题与 URL 一并记录从而在将来执行相同查询时能够提供该结果。实现位于 extract.tsGoogleExtractor匹配www.google.com/search页面中点击H3标题的搜索结果DuckDuckGoExtractor匹配duckduckgo.com首页点击的SPAN结果提取后通过api/history提交到服务端。Popup点击扩展图标即可打开 Popup快速访问最常用的控件控件说明自动索引开关启用或禁用自动页面索引设置立即保存Reindex Page重新索引页面按钮强制把当前页面重新提交到服务器Authenticate with Browser Session使用浏览器会话认证按钮当未使用访问令牌时复制已登录 Hister Web UI 的会话 Cookie 来认证扩展设置图标⚙展开内联表单无需打开完整选项页即可查看和更新 Server URL 与 Access TokenShow indicator for indexed pages显示已索引页面指示设置在已索引页面上显示✓徽标从 Popup 打开设置视图后可用Submit as public documents以公共文档提交设置把新索引的页面以用户 id0存储为公共文档扩展完成认证后出现任何操作后Popup 底部会出现状态横幅显示成功或错误反馈。如果服务器拒绝了最近一次提交扩展图标会显示!徽标保存有效设置后会清除它。已索引页面指示默认关闭。启用方法点击扩展图标 → 点击设置图标打开设置视图 → 打开Show indicator for indexed pages。启用后扩展会把当前页面与 Hister 服务器比对后台通过HEAD api/document?url...判断返回 200 表示已存在并在已入库的页面上保持可见的✓徽标。Popup 还提供了两个与索引控制相关的附加能力Label标签可为当前页面应用标签或保存为默认标签应用到后续索引的所有页面之后可用label:yourtext过滤搜索结果与SkipRuleActions为当前页面或域名添加 skip 规则、可选删除已索引的匹配文档这些操作经由后台的addSkipRule/checkSkipRule消息与api/rules、api/delete接口联动。选项页完整的选项页可通过浏览器扩展管理器访问右键扩展图标 →选项或进入扩展设置页面Chromechrome://extensions→ 找到 Hister →详细信息→扩展程序选项Firefoxabout:addons→ 找到 Hister →…菜单 →首选项连接设置设置项类型默认值说明Server URLstringhttp://127.0.0.1:4433/Hister 服务器的完整 URL含 scheme 与端口Custom Headersmap[string]string无随每个请求附加的 HTTP 头可用于反向代理认证或其他服务端要求Access Tokenstring无用于认证扩展请求的可选全局或个人访问令牌Submit as public documentsbool关把新索引的页面以用户 id 0 存储为公共文档该选项在认证后出现点击Save Settings应用配置。保存前扩展会调用GET /api/config校验连接URL 无效时会显示错误而不是保存成功见 Popup.svelte 与 Options.svelte 的save()逻辑。从网络层实现network.ts看每个请求都会携带存储的 Cookie 头Cookie与访问令牌X-Access-Token请求头当服务端返回 401/403 时扩展会尝试从浏览器读取并刷新已保存的服务器 Cookie 后重试一次避免会话过期导致索引中断。Custom Headers 中的所有头也会逐一附加到每个请求因此可以在扩展前面放置需要自定义认证头的反向代理。认证扩展支持访问令牌与浏览器会话两种认证方式。使用访问令牌在 Popup 设置或选项页中输入全局访问令牌或个人访问令牌然后保存设置即可。令牌通过X-Access-Token请求头随每个请求发送保存时扩展会调用GET /api/profile验证令牌有效性令牌被拒绝时会提示Settings saved, but the access token was rejected。使用浏览器会话当启用了 user handling多用户支持时可以改用 Hister Web 界面共享的会话 Cookie在同一个浏览器中登录 Hister Web 界面点击 Popup 或选项页中的Authenticate with Browser Session按钮。扩展会读取当前浏览器中该站点域名的活动会话 Cookiechrome.cookies.getAll序列化后存入histerCookies此后扩展就以你的用户账户提交页面。即使在 Web 界面中退出登录也无需重复此步骤。认证完成后Popup 设置与选项页都会显示Submit as public documents。开启后扩展提交的页面将以公共文档形式可见而不是只存储在你的用户账户下扩展会随文档提交附带X-Hister-Public: 1请求头服务端将这些文档以用户 id0存储getDocumentSubmissionHeaders见 background.ts。未认证用户 id 为 0时该开关会被自动关闭。故障排查扩展图标显示!徽标最近一次向服务器发送页面数据的尝试失败了。打开 Popup 查看具体错误。常见原因Hister 服务器未运行用hister listen启动它。Server URL填写错误确认与服务器启动时打印的地址一致默认http://127.0.0.1:4433/。启用了 user handling 但扩展未认证配置访问令牌或在登录 Web 界面后点击Authenticate with Browser Session。页面没有被索引确认 Popup 中的Automatic indexing自动索引已开启。检查服务器是否可达、URL 是否正确见上文。如果启用了 user handling确认扩展已经认证见上文。部分页面如chrome://…、about:…等浏览器内部页面无法被扩展访问会被静默跳过后台的updateTabIcon会直接忽略这些 URL 前缀。另外命中服务端 skip 规则时扩展会把图标置灰服务端返回 406包含敏感内容的页面会被拒绝并置灰服务端返回 422这两类情况均不属于提交错误。小结Hister 浏览器扩展把浏览即索引变成现实MV3 扩展在后台以 30 秒起、最长 5 分钟的智能轮询策略采集可见页面结合导航防抖、预览检查节流与隐藏/关闭时的快照冲刷机制在内容变化与资源消耗之间取得平衡qutebrowser 用户则可以通过基于 Qt WebEngine DevTools 的 companion 获得同等的渲染后页面索引能力。配合访问令牌或浏览器会话认证、skip 规则、手动重新索引与键盘快捷键你可以精确控制哪些页面进入索引并在多用户场景下决定文档归属公共还是个人空间。上述行为均有仓库源码佐证webui/ext/src、cmd/companion/qutebrowser如需深入调试可继续阅读对应实现与 user handling 文档。【免费下载链接】histerYour own search engine项目地址: https://gitcode.com/GitHub_Trending/hi/hister创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
