一款本地优先的 Chrome 专注与休息伴侣。
感知浏览节奏，估计当前负荷，在需要的时候陪你停一下。

开始体验 · 隐私与 AI · 开发 · 反馈问题

Note

BrainRest 目前是面向桌面版 Chrome 的公开预览项目，暂未在 Chrome 应用商店发布。

为什么是脑栖

长时间使用屏幕时，人往往最难察觉自己的状态变化。脑栖结合标签页切换、键鼠与滚动节奏、页面结构和持续浏览时间等信号，在扩展本地估计认知负荷与身体疲劳。

当数据足够时，界面会以低、中、高等级呈现当前状态；覆盖不足时明确显示“数据不足”，不会强行给出结论或触发智能提醒。桌面宠物会随状态变化，并承载快速休息、提醒、倒计时和反馈入口。

核心体验

体验	脑栖如何帮助你
状态感知	展示估计负荷、视觉疲劳与连续浏览状态，数据不足时主动降级
桌宠陪伴	可拖动、贴边，并随精力、提醒和休息状态切换动画与交互
快速休息	根据当前负荷来源给出短时、具体的恢复动作，也支持随时主动开始
每日报告	汇总当日负荷采样、提醒和注意力切换情况，可选 AI 生成简短报告
可选 AI 分类	使用自己的 API Key 对页面分类，让负荷判断和休息建议更贴近当前活动
数据控制	可移除 API Key，并清除选项、事件、分类、时长、作息和日报记录

AI 只参与页面类别判断和每日报告文案生成，不参与核心负荷计算，也不提供医学判断。它可以在初始引导中跳过，之后再到设置页配置。

开始体验

从 GitHub Releases 安装

1. 打开项目的 GitHub Releases 页面。
2. 下载最新版本中的 brainrest-x.y.z.zip 并解压。
3. 在 Chrome 打开 chrome://extensions，开启“开发者模式”。
4. 选择“加载已解压的扩展程序”，再选择包含 manifest.json 的解压目录。
5. 打开脑栖并完成作息设置；AI 页面分类可以跳过。

从源码安装

需要桌面版 Google Chrome、Node.js 22 和 npm。

git clone https://github.com/Brainllo/BrainRest.git
cd BrainRest
npm ci
npm run build

在 chrome://extensions 开启“开发者模式”，选择“加载已解压的扩展程序”，并加载仓库中的 dist/。每次重新构建后，需要先在扩展管理页重新加载脑栖，再刷新已打开的网页。

隐私与 AI 边界

“本地优先”不等于零采集或完全离线。以下是当前预览版的实际数据边界。

本地处理与存储

• 负荷和疲劳计算在 Chrome 扩展本地完成，BrainRest 没有自建的用户数据服务器。
• 当前实现可能采集并在本机处理完整页面 URL、按键值与修饰键、鼠标和点击坐标、触摸位置、滚动位置、目标元素的标签/ID/class、标签页与窗口状态、媒体状态、全屏状态和页面复杂度等信号。
• 行为事件写入 IndexedDB，用于后台计算与崩溃恢复，按滚动窗口保留约 24 小时。
• 浏览时长默认保留 7 天，每日报告底稿默认保留 14 天；页面分类、作息记录和部分校准状态会持续保留，直到被清除或扩展数据被删除。
• 设置、API Key、桌宠位置与通知、活动历史和部分自适应/校准参数保存在 chrome.storage.local；短期引擎状态和 AI 日报文案缓存保存在 chrome.storage.session。
• 设置页当前的清除流程会删除选项记录（包含 API Key）以及事件、页面分类、时长、作息和每日报告数据库；不会删除桌宠位置、活动历史和部分自适应/校准键。完整重置需要由 Chrome 清除该扩展的存储，例如卸载扩展。

可选 AI 分类

• 页面分类支持 OpenAI、DeepSeek 和自定义兼容 OpenAI 协议的 HTTP(S) 接口。
• 分类运行时，Content Script 获取完整 URL 和页面 HTML；Service Worker 将 HTML 转为 Markdown，并把完整 URL、页面标题和 Markdown 发送给用户配置的服务商。
• 生成 AI 每日报告时，Service Worker 会发送结构化摘要，包括屏幕与高负荷时长、标签页切换、提醒记录、CL/VF 统计、昨夜睡眠时长、页面类别分布和本地恢复建议；不会发送走势图原始采样序列。
• API Key 仅由扩展后台读取，网页中的页面脚本不能直接访问。
• 分类结果按 URL 指纹缓存在本地；AI 日报文案在 chrome.storage.session 中缓存 30 分钟。
• 数据到达第三方服务商后，其存储和处理方式取决于对应服务商的条款。配置前应评估页面内容、接口地址和服务商的数据政策。

Warning

当前预览版会在可注入网页上收集较细的交互事件，AI 分类可能发送页面正文，AI 日报会发送结构化状态摘要。在处理敏感页面前，请根据自己的风险偏好决定是否配置 AI。

权限说明

Content Script 当前匹配 <all_urls>；Chrome 内部页、扩展页和其他浏览器限制注入的页面仍无法运行脚本。桌宠图片资源只对 HTTP(S) 页面暴露。

权限	用途
tabs	监听页面生命周期、活动标签页和 URL 变化
windows	判断浏览器窗口焦点
storage	保存配置、运行状态和本地学习参数
idle	识别系统空闲、锁屏和恢复状态
alarms	驱动周期计算、持久化、桌宠调度和日报采样
contextMenus	在页面右键菜单中显示当前页面分类
webNavigation	识别主框架导航完成事件
OpenAI / DeepSeek 主机权限	调用预设 AI 服务商
可选 HTTP(S) 来源主机权限	用户配置自定义 Base URL 时，按来源请求访问权限

产品边界

• BrainRest 根据浏览行为和页面结构估计负荷，不是医学、生理或真实认知状态测量。
• 提醒与建议不能替代医生、心理咨询师或其他专业人员的诊断与治疗。
• 公开预览阶段的算法参数、数据结构、权限和界面仍可能调整。
• 仓库目前不承诺稳定的数据或版本兼容策略，升级前应重新检查变更和权限。

开发

项目使用 TypeScript、React 19、Vite 8、CRXJS、Chrome Manifest V3、Vitest、ESLint 和 Prettier。

常用命令

命令	用途
npm run dev	启动 Vite/CRXJS 开发服务
npm run build	执行 tsc -b，使用开发 manifest 构建到 dist/
npm run build-prod	构建生产 manifest，并生成 dist-prod/ 和发布 ZIP
npm run debug	类型检查并构建带 sourcemap 的调试产物
npm test	运行全部 Vitest 测试
npm test -- src/path/to/file.test.ts	运行单个测试文件
npm run lint	运行 ESLint
npm run format:check	检查 Prettier 格式
npm run format	使用 Prettier 改写仓库文件
npm run preview	预览普通 Vite 页面，不能验证 Chrome 扩展运行环境

Vitest 使用默认 Node 环境；涉及 chrome、window 或 document 的测试会像现有测试一样使用 vi.stubGlobal 模拟。CI 当前只运行 ESLint 和格式检查，不运行测试、类型检查或扩展构建。

运行边界

入口	职责
src/content/index.ts	注册页面事件采集、页面分析、AI 分类请求、事件端口和桌宠覆盖层
src/background/service-worker.ts	注册浏览器监听器，协调计算引擎、持久化、AI 调用和运行时消息
index.html / src/popup/main.tsx	扩展弹窗 React 入口
options.html / src/options/main.tsx	首次引导、设置、报告、调试和数据控制 React 入口
src/messages.ts	跨 Content Script、Service Worker、Popup 和 Options 的消息契约

Service Worker 没有 DOM；页面内容和 DOM 事件必须由 Content Script 采集后通过 chrome.runtime 传递。Content Script 运行在 Chrome 隔离环境，可以访问页面 DOM，但不能直接读取后台持有的 API Key。Popup 关闭后，后台仍会继续维护休息会话和周期任务。

调试

• Service Worker：在 chrome://extensions 中点击 BrainRest 的 Service Worker 检查链接。
• Content Script 与桌宠：在目标网页打开 DevTools。
• Popup：右键扩展弹窗并选择“检查”。
• Options：打开设置页后使用页面 DevTools。

日志以 [BrainRest][上下文][模块][等级] 开头。开发或解压安装会输出全部等级，生产环境只输出 warn 和 error；设置页可跨扩展上下文关闭控制台日志。问题反馈中不要粘贴 API Key、完整页面内容、私密 URL 或未脱敏日志。

生产构建

npm run build-prod

生产构建使用 src/manifest.prod.ts，写入 dist-prod/，并生成 release/brainrest-x.y.z.zip。生产 manifest 必须包含 update_url 且不能包含开发签名 key；这一差异同时控制调试和示例功能的可见性。

发版时保持 package.json、src/manifest.ts 和 src/manifest.prod.ts 的版本一致。dist/、dist-prod/ 和 release/ 都是生成目录，不应直接修改或提交。

反馈与许可

通过 GitHub Issues 提交问题时，请包含 Chrome 版本、复现步骤、预期与实际行为，以及已经脱敏的相关日志。

Copyright (c) 2026 QuinnCai, MingxuanGame, Qziky, chenjintang

MIT License，详情请见 LICENSE 文件。