# UranusTab

**Repository Path**: wx114/uranus-tab

## Basic Information

- **Project Name**: UranusTab
- **Description**: 个人专属新标签页扩展
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UranusTab

完全属于你的本地优先（local-first）新标签页浏览器扩展。Chrome / Edge（Manifest V3）。

## 快速开始

```bash
npm install
npm run dev
```

> **Chrome 136+ 说明**：正式版 Chrome 已禁止命令行加载未打包扩展（`--load-extension` 被忽略），
> 所以本项目 dev 模式配置为手动加载（`wxt.config.ts` 中 `webExt.disabled: true`）：
>
> 1. `npm run dev` 启动后，构建产物在 `.output/chrome-mv3-dev`
> 2. 打开 `chrome://extensions` → 开启「开发者模式」→「加载已解压的扩展程序」→ 选择 `.output/chrome-mv3-dev`
> 3. 保持 dev server 运行：改代码页面即时热更新；manifest 级变更在扩展页点刷新或按 `Alt+R`
>
> 首次加载后扩展会保留在该浏览器配置中，之后 `npm run dev` 不必重复加载。

## 手动加载正式构建（Chrome / Edge）

1. `npm run build`
2. 打开 `chrome://extensions`（Edge 为 `edge://extensions`），开启「开发者模式」
3. 「加载已解压的扩展程序」→ 选择 `.output/chrome-mv3` 目录（注意与 dev 目录区分）
4. 打开新标签页

## 常用脚本

| 命令 | 作用 |
|---|---|
| `npm run dev` | 开发模式（HMR 热更新，产物在 `.output/chrome-mv3-dev`） |
| `npm run dev:edge` | 用 Edge 进行开发调试 |
| `npm run build` | 构建到 `.output/chrome-mv3` |
| `npm run zip` | 打包可上架/分发的 zip |
| `npm test` | 运行单元测试（Vitest） |
| `npm run e2e` | 构建后运行 Playwright E2E（首次需准备本地浏览器，见下） |
| `npm run compile` | TypeScript 类型检查 |
| `npm run check` | ESLint + 类型检查 + 测试 全量校验 |

## E2E 测试（首次准备）

正式版 Chrome 136+ 禁止 `--load-extension`，E2E 使用本地 Chrome for Testing（非品牌构建，
该参数仍有效）。Playwright 自带下载源国内较慢，手动准备一次：

```bash
curl -L -o .e2e.zip https://cdn.npmmirror.com/binaries/chrome-for-testing/<版本>/win64/chrome-win64.zip
mkdir -p .e2e && powershell -Command "Expand-Archive -Path .e2e.zip -DestinationPath .e2e -Force" && rm .e2e.zip
npm run e2e
```

## 功能概览（Phase 1–4：MVP + 小组件 + 云同步 + AI 与专注）

- **启动台**：图标卡片增删改、iTab 式左侧分组导航栏、拖拽排序/跨组移动、多引擎搜索与本地历史
- **智能书签导入**（差异化旗舰）：一键读取收藏夹 → 自动分析分组（原文件夹保留/域名聚合/内置 12 类规则/关键词兜底）→ 自动匹配图标（favicon 本地缓存 + 在线补全 + 首字母色块三级回退）→ 预览调整 → 去重导入
- **小组件系统**：注册制 + 自由拖拽网格（12 列、碰撞吸附、尺寸切换）；天气（Open-Meteo 可插拔源、多城市、断网缓存降级）、待办、倒数日（年度事件自动循环）、日历（农历/节气/休班标示）
- **壁纸**：纯色渐变 / 本地图片多张轮换（IndexedDB）/ 必应每日一图（默认关、当日缓存、离线回退）/ 本地视频循环（标签页切走自动暂停）
- **视觉**：主题取色（从图片壁纸提取主色作全局强调色）、极简模式（Alt+M 一键只留时钟+搜索）
- **时钟**：农历 + 节气（本地计算）、节假日与调休休/班徽标（内置 2025–2026 国务院安排）
- **数据**：一键导出/导入 JSON（含壁纸/待办/倒数日；覆盖/去重合并）、清空数据
- **云端同步与账号（自托管，Phase 3）**：Docker 一键部署 Sync Server（Fastify + MySQL）；
  全量快照 + revision 乐观锁多机同步，冲突可选保留云端/本地；账号注册三策略（开放/邀请码/关闭）、
  设备会话管理与远程吊销、改密全下线；服务器不可达自动降级纯本地（详见 docs/DEPLOY.md）
- **AI 对话（Phase 4）**：OpenAI 兼容端点（OneAPI/NewAPI/中转），流式打字机输出、
  停止生成、Alt+I 呼出、System Prompt；API Key 仅存本机（不进备份与云同步）
- **专注模式（Phase 4）**：极简模式（Alt+M）内嵌番茄钟（工作/休息自动切换）与今日焦点（隔天自动清）
- **个性化（Phase 4）**：账号头像上传（本机 IndexedDB）、分组自选线形图标（16 种 + 自动匹配）、
  admin 用户管理（删除/重置密码/角色转让）
- **本地优先**：无账号也能用满全部功能；断网除必应壁纸与天气刷新外全部可用

产物体积：总量约 955KB（< 2MB 预算）；首屏主包 < 350KB，分组引擎与农历库按需加载。

## 目录结构

```
server/               自托管 Sync Server（Fastify + MySQL，Docker 一键部署，见 docs/DEPLOY.md）
entrypoints/newtab/   新标签页入口（唯一页面入口）
components/           UI 组件（Clock / SearchBar / IconGrid / SettingsPanel）
core/config/          schemaVersion 化的配置类型、默认值、合并与迁移
core/storage/         StorageAdapter 抽象 + chrome.storage.local 实现（Phase 3 云端后端替换点）
core/store/           Zustand 全局状态（配置读写走 adapter）
assets/               全局样式（Tailwind v4 + CSS 变量主题）
tests/                单元测试（chrome.storage 内存 mock）
docs/                 产品文档：PRD、Phase 计划、竞品调研
```

## 设计原则

- **本地优先**：默认无账号、零上报，数据只存本机（chrome.storage + IndexedDB）
- **存储抽象**：所有读写走 `StorageAdapter` 接口；云端同步经自托管 Sync Server 落 MySQL（PRD 6.7/6.8 已交付）
- **权限克制**：仅声明 `storage`；`bookmarks`/`favicon` 为 Phase 1 智能书签导入预留（optional，触发时才申请）

## 文档

- [docs/PRD-UranusTab.md](docs/PRD-UranusTab.md) — 产品需求文档（v0.4）
- [docs/PLAN-Phase4.md](docs/PLAN-Phase4.md) — 当前阶段实施计划
- [docs/DEPLOY.md](docs/DEPLOY.md) — Sync Server 部署指南
- [docs/竞品调研-新标签页产品.md](docs/竞品调研-新标签页产品.md) — 竞品调研报告