# TabSyncByGitee

**Repository Path**: zhenruyan/tab-sync-by-gitee

## Basic Information

- **Project Name**: TabSyncByGitee
- **Description**: 书签和tab同步到gitee仓库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tab & BookMark Sync Gitee

[English](./README.md) | [简体中文](./README_zh.md)

一款基于 **Gitee** 的跨浏览器（Chrome / Firefox）扩展，可将浏览器标签页和书签同步到你自己的 Gitee 仓库，并内置 Git 版本管理能力。

## 项目简介

Tab & BookMark Sync Gitee 通过 Gitee OpenAPI 将标签页会话与书签以 JSON 文件的形式存储在你自己的 Gitee 仓库中。由于数据保存在 Git 仓库里，你可以免费获得完整的版本历史、版本对比、标签和回滚能力，并能在不同浏览器和设备间无缝同步。

项目基于 [WXT](https://wxt.dev) 构建，同一套源码可同时产出 Chrome MV3 与 Firefox MV2 版本。

## 功能特性

- **标签页管理** —— 将当前窗口或全部窗口保存为命名会话；可恢复到新窗口或当前窗口。
- **书签备份与恢复** —— 备份完整书签树；支持合并恢复或覆盖恢复。
- **Git 版本管理** —— 浏览提交历史、对比版本、回滚到历史状态。
- **标签管理** —— 创建和管理 Gitee 标签（如 `v1.0.0`）以标记重要版本。
- **导入 / 导出** —— 将标签页/书签以 JSON 在本地导入导出，完全离线可用。
- **离线支持** —— 离线时回退到本地缓存；待同步操作进入队列，恢复联网后自动补同步。

## 技术栈

- **框架**: [WXT](https://wxt.dev) —— 提供 entrypoints、manifest 生成、跨浏览器构建
- **UI**: Svelte 5（runes）+ 原生 CSS
- **构建**: Vite 8（经 WXT 封装）+ `@wxt-dev/module-svelte`
- **语言**: JavaScript (ES6+) / Svelte
- **扩展 API**: 通过 `wxt/browser` 导出的 `browser.*`（Promise 化，Chrome/Firefox 通用）
- **后端 API**: Gitee OpenAPI v5（`https://gitee.com/api/v5`）

## 项目结构

```
.
├── wxt.config.ts              # WXT 配置（按浏览器区分 manifest）
├── package.json
├── Makefile
└── src/
    ├── entrypoints/
    │   ├── background.js       # Service Worker / 后台脚本
    │   ├── popup/              # 弹出窗口（Svelte）
    │   │   ├── App.svelte
    │   │   ├── Icon.svelte
    │   │   ├── TabsPanel.svelte / BookmarksPanel.svelte / HistoryPanel.svelte
    │   │   ├── utils.js
    │   │   ├── main.js
    │   │   └── index.html
    │   └── options/            # 设置 / 管理控制台（Svelte，open_in_tab）
    │       ├── App.svelte
    │       ├── messaging.js
    │       ├── main.js
    │       ├── index.html
    │       └── components/
    │           ├── Sidebar.svelte
    │           ├── TabsPanel.svelte
    │           ├── BookmarksPanel.svelte
    │           ├── BookmarkNode.svelte
    │           ├── TagsPanel.svelte
    │           ├── HistoryPanel.svelte
    │           └── SettingsPanel.svelte
    ├── utils/                  # 共享逻辑（被 background 引用）
    │   ├── gitee-api.js        # Gitee API 封装（单例 giteeApi）
    │   ├── storage-helper.js   # browser.storage 封装（单例 storage）
    │   └── utils.js            # logger、retry、id 生成等工具
    └── public/icons/           # manifest 引用的 PNG 图标
```

## 快速开始

### 环境要求

- Node.js 18+ 与 npm

### 安装与构建

```bash
make install        # 安装依赖
make build          # 构建 Chrome（.output/chrome-mv3）
make build-firefox  # 构建 Firefox（.output/firefox-mv2）
```

或直接使用 npm：

```bash
npm install
npm run build
npm run build:firefox
```

### 开发模式（热更新）

```bash
make dev            # Chrome 开发模式
make dev-firefox    # Firefox 开发模式
```

### 在浏览器中加载

**Chrome / Edge**

1. 打开 `chrome://extensions`
2. 启用「开发者模式」
3. 点击「加载已解压的扩展程序」，选择 `.output/chrome-mv3`

**Firefox**

1. 打开 `about:debugging#/runtime/this-firefox`
2. 点击「临时载入附加组件…」，选择 `.output/firefox-mv2` 中的任意文件

## 配置

首次使用时，打开设置页面并配置 Gitee 仓库信息：

1. **仓库所有者** —— 你的 Gitee 用户名或组织名
2. **仓库名称** —— 用于存储数据的仓库
3. **访问令牌** —— Gitee 个人访问令牌（设置 → 私人令牌），需勾选 `projects` 权限
4. **默认分支** —— 默认分支（如 `main`）

点击「测试连接」验证后保存。

## Gitee 数据存储结构

```
/
├── tabs/        tabs_YYYYMMDD_HHMMSS.json
└── bookmarks/   bookmarks_YYYYMMDD_HHMMSS.json
```

提交信息遵循 Conventional Commits，例如 `feat: 保存标签页集合 - {name}`。

## 架构

所有特权操作集中在 background 脚本中。UI 从不直接调用 Gitee，而是通过 `browser.runtime.sendMessage` 通信：

```
popup / options (Svelte)
   └── sendMessage({ action, ... })
          └── background.js onMessage  → 返回 Promise
                 ├── TabManager / BookmarkManager   (browser.tabs / bookmarks)
                 ├── SyncManager                     (在线/离线、缓存、待同步队列)
                 │      ├── giteeApi  → Gitee REST API
                 │      └── storage   → browser.storage.local
                 └── 统一返回: { success, data?, error? }
```

## 安全考虑

- 访问令牌仅存于 `browser.storage.local`，不写入代码或日志。
- 请求使用 HTTPS；Gitee `access_token` 经 query/form 参数传递。
- 权限最小化：仅声明 `tabs`、`bookmarks`、`storage`（Chromium 额外含 `tabGroups`）；`host_permissions` 仅限 `https://gitee.com/*`。

## 贡献

提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)：`feat` / `fix` / `docs` / `style` / `refactor` / `test` / `chore`。

## 版本号

扩展版本号会自动跟随 git tag。构建时 `wxt.config.ts` 通过 `git describe` 读取最近的 tag：

- `version`（manifest）取最近 tag 的数字部分（如 tag `v1.2.0` → `1.2.0`）；按扩展规范必须为 1~4 段纯数字。
- `version_name`（仅 Chromium，展示用）携带完整的 `git describe` 输出（如 `1.2.0-3-gabc123`）。
- 当不存在 tag（或不在 git 检出环境，例如 AMO 的 sources zip）时，回退到 `package.json` 的 `version` 字段。

发布新版本只需打 tag：`git tag v1.2.0` 后构建即可。

## 许可证

MIT License