StarVault：AI 驱动的全平台收藏与工具管理套件架构设计

StarVault 是一款面向开发者和极客的全平台收藏管理工具。本文档是其 v0.1 版本的完整架构设计，涵盖产品定位、技术选型、数据模型、AI 知识库、多端同步、前端架构、内置工具和开发路线图。目前处于设计阶段，核心架构蓝图已确定。

---

一、项目背景与产品定位

1.1 为什么设计这个项目？

开发者在日常工作中会积累大量数字资产：

• GitHub 上 Star 的仓库越来越多，根本看不过来
• 浏览器书签堆积成山，找不到想要的
• 各种好用的软件、工具、文章散落在不同平台
• 想用 AI 帮忙整理、摘要、搜索，但不想把数据交给第三方服务器

StarVault 的目标就是解决这些问题：

一个本地优先、零服务器成本、AI 增强的全平台收藏管理工具。

1.2 核心定位

维度	描述
核心功能	管理 GitHub Stars、网站书签、软件工具，内置常用开发工具
差异化	AI 知识库化、自然语言搜索、智能标签网络、相似项目推荐
目标用户	开发者、设计师、技术管理者
商业模式	开源免费 + 可选高级 AI 功能（用户自带 API Key）
架构原则	本地优先、零服务器成本、AI 增强

1.3 核心功能清单

├── 数据管理
│   ├── GitHub Stars 全量/增量同步
│   ├── 网站/软件手动添加 + 浏览器扩展一键收藏
│   ├── 分类管理（文件夹 + 标签体系）
│   └── 数据导入/导出
├── AI 能力
│   ├── README 自动抓取 + 中文摘要生成
│   ├── 自然语言搜索（跨仓库名、描述、README）
│   ├── AI 自动标签建议与标签网络
│   ├── 相似项目/替代品推荐
│   └── 支持 OpenAI / Anthropic / 兼容接口（用户自带 Key）
├── 多端同步
│   ├── Web 端（PWA）
│   ├── 桌面端（Electron/Tauri）
│   ├── 移动端（React Native / 小程序）
│   └── 数据零成本同步（GitHub Gist / 私有仓库）
├── 内置工具
│   ├── JSON 格式化/校验
│   ├── Base64 编解码
│   ├── 正则表达式测试
│   ├── 颜色选择器/转换
│   ├── 时间戳转换
│   ├── 二维码生成
│   └── Markdown 预览
└── 用户体验
    ├── 浅色/深色模式切换
    ├── 响应式设计
    └── 离线优先（Local-First）

---

二、技术架构总览

2.1 整体架构图

┌─────────────────────────────────────────────────────────────────────┐
│                        客户端层 (Client Layer)                        │
├──────────────┬──────────────┬──────────────┬──────────────────────┤
│   Web (PWA)  │  Desktop App │  Mobile App  │     微信小程序         │
│   (React)    │  (Tauri)     │ (React Native)│   (Taro/UniApp)      │
└──────┬───────┴──────┬───────┴──────┬───────┴──────────┬───────────────┘
       │              │              │                  │
       └──────────────┴──────────────┴──────────────────┘
                              │
                    ┌─────────▼──────────┐
                    │   统一 API 层 (REST)  │
                    │   + GraphQL (可选)   │
                    └─────────┬──────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
┌───────▼────────┐  ┌──────────▼──────────┐  ┌──────▼──────┐
│  本地数据库     │  │   向量数据库         │  │  AI 服务层   │
│  (SQLite/LMDB) │  │  (SQLite-vec/      │  │ (用户自带   │
│                │  │   pgvector 本地版)  │  │  API Key)   │
└───────┬────────┘  └──────────┬──────────┘  └─────────────┘
        │                      │
        └──────────────────────┘
                   │
        ┌──────────▼──────────┐
        │   同步引擎 (Sync)    │
        │  GitHub Gist/Repo   │
        │  + 增量 Diff 算法    │
        └─────────────────────┘

2.2 技术栈选择

层级	技术选型	理由
Web 前端	React 19 + TypeScript + Tailwind CSS + shadcn/ui	生态成熟，UI 组件丰富，深色模式支持好
桌面端	Tauri 2.0 (Rust 后端)	包体积小（~3MB），内存占用低，Rust 高性能
移动端	React Native (Expo)	一套代码双端，热更新，社区活跃
小程序	Taro 4.0 (React 语法)	代码复用率高，支持多端编译
本地数据库	SQLite	零配置，单文件，跨平台
向量检索	sqlite-vec / usearch	零额外依赖，本地运行，足够支撑万级数据
状态管理	Zustand + TanStack Query	轻量，支持持久化，服务端状态管理
同步协议	CRDT (Yjs) 或自定义增量 Diff	冲突解决，离线优先
AI 调用	用户配置 OpenAI/Anthropic API Key	零服务器成本，隐私安全
构建工具	Vite	极速 HMR，生态完善

2.3 为什么桌面端选 Tauri 而不是 Electron？

对比项	Tauri	Electron
包体积	~3MB	~150MB
内存占用	~50MB	~200MB
启动速度	快	慢
安全性	Rust 原生安全	需要额外注意
学习成本	需学 Rust（但后端逻辑简单）	纯 JS

结论：Tauri 更适合个人项目，包体积小意味着用户更愿意下载试用。

---

三、数据存储方案

3.1 核心原则：零服务器成本

用户数据存储优先级：
1. 本地 SQLite 数据库（Primary）
2. GitHub Gist / 私有仓库（Sync Backup）
3. 可选：用户自托管的 WebDAV / S3

3.2 核心数据模型

items（项目/收藏主表）

CREATE TABLE items (
    id              TEXT PRIMARY KEY,           -- UUID v4
    type            TEXT NOT NULL,              -- 'github' | 'website' | 'software' | 'tool'
    source_url      TEXT NOT NULL,              -- 原始 URL
    title           TEXT NOT NULL,
    description     TEXT,

    -- GitHub 特有字段
    github_owner    TEXT,
    github_repo     TEXT,
    github_stars    INTEGER DEFAULT 0,
    github_forks    INTEGER DEFAULT 0,
    github_language TEXT,
    github_topics   TEXT,                       -- JSON 数组
    readme_content  TEXT,                       -- 原始 README Markdown
    readme_summary  TEXT,                       -- AI 生成的中文摘要
    last_sync_at    DATETIME,                   -- 上次 GitHub 同步时间

    -- 通用字段
    icon_url        TEXT,
    screenshot_urls TEXT,                       -- JSON 数组
    notes           TEXT,                       -- 用户备注

    -- 元数据
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    user_created    BOOLEAN DEFAULT FALSE,       -- 是否用户手动添加
    is_archived     BOOLEAN DEFAULT FALSE
);

tags（标签表）

CREATE TABLE tags (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL UNIQUE,
    color       TEXT DEFAULT '#3b82f6',
    description TEXT,
    parent_id   TEXT REFERENCES tags(id),        -- 支持层级标签
    is_ai_generated BOOLEAN DEFAULT FALSE,
    created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

item_tags（项目-标签关联）

CREATE TABLE item_tags (
    item_id TEXT REFERENCES items(id) ON DELETE CASCADE,
    tag_id  TEXT REFERENCES tags(id) ON DELETE CASCADE,
    confidence REAL DEFAULT 1.0,                 -- AI 标签置信度
    PRIMARY KEY (item_id, tag_id)
);

collections（文件夹/分类表）

CREATE TABLE collections (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL,
    icon        TEXT DEFAULT 'folder',
    color       TEXT,
    parent_id   TEXT REFERENCES collections(id),
    sort_order  INTEGER DEFAULT 0,
    created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

embeddings（向量嵌入表）

CREATE TABLE embeddings (
    item_id     TEXT PRIMARY KEY REFERENCES items(id) ON DELETE CASCADE,
    embedding   BLOB NOT NULL,                  -- 768 维 float32 数组
    model       TEXT DEFAULT 'text-embedding-3-small',
    updated_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

sync_meta（同步元数据表）

CREATE TABLE sync_meta (
    id              INTEGER PRIMARY KEY CHECK (id = 1),  -- 单例表
    last_sync_at    DATETIME,
    sync_target     TEXT,                               -- 'github_gist' | 'github_repo' | 'webdav'
    sync_target_id  TEXT,                               -- Gist ID 或 Repo 名
    device_id       TEXT NOT NULL,                      -- 本机唯一标识
    schema_version  INTEGER DEFAULT 1
);

change_log（操作日志表，用于增量同步）

CREATE TABLE change_log (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    table_name  TEXT NOT NULL,
    record_id   TEXT NOT NULL,
    operation   TEXT NOT NULL,                      -- 'INSERT' | 'UPDATE' | 'DELETE'
    old_data    TEXT,                               -- JSON
    new_data    TEXT,                               -- JSON
    timestamp   DATETIME DEFAULT CURRENT_TIMESTAMP,
    synced      BOOLEAN DEFAULT FALSE,
    sync_retry  INTEGER DEFAULT 0
);

3.3 向量搜索索引

-- 使用 sqlite-vec 创建虚拟表
CREATE VIRTUAL TABLE vec_items USING vec0(
    item_id TEXT PRIMARY KEY,
    embedding FLOAT[768]  -- OpenAI text-embedding-3-small
);

-- 搜索示例：
-- SELECT item_id, distance FROM vec_items 
-- WHERE embedding MATCH vec_normalize(?1) 
-- ORDER BY distance LIMIT 20;

3.4 GitHub 同步存储方案

方案 A：GitHub Gist（推荐起步）

优点：免费、有 API、天然版本历史、无需服务器。

限制：单个文件最大 1MB，速率限制 60/5000 请求每小时。

数据分片策略：

- data_v1.json      -- 主数据（items, tags, collections）
- embeddings_v1.bin -- 向量数据（二进制分片）
- changelog.json    -- 增量变更日志

方案 B：GitHub 私有仓库（数据量大时）

优点：无单文件大小限制，支持 Git LFS，更好的组织结构。

/.starvault/
  ├── data/
  │   ├── items/2024/07/items_202407.json
  │   ├── tags.json
  │   ├── collections.json
  │   └── embeddings/embeddings_202407.bin
  ├── changelog/20240708_143022.json
  └── meta.json

方案 C：用户自托管（高级用户）

• WebDAV (Nextcloud/ownCloud)
• S3 兼容存储 (Cloudflare R2 免费 10GB/月)
• 自建 Sync 服务器（未来扩展）

---

四、核心功能模块设计

4.1 GitHub Stars 同步模块

全量同步流程

用户授权 → 获取所有 Starred repos 列表 → 批量获取详情 → 并行抓取 README → AI 生成摘要 → 写入本地 DB → 生成向量嵌入

技术细节：

1. 分页获取：/users/{username}/starred?per_page=100
2. 并发控制：p-limit 限制 10 个并发请求
3. README 抓取：raw.githubusercontent.com/{owner}/{repo}/main/README.md
4. 增量标记：记录每个 repo 的 updated_at，下次只同步变更

增量同步策略

async function incrementalSync() {
  const lastSync = await db.getLastSyncTime();

  // 1. 获取用户所有 stars（只取基本元数据，很快）
  const allStars = await githubApi.getAllStarredRepos();

  // 2. 对比本地数据，找出新增、更新、删除
  const { added, updated, removed } = diffRepos(localRepos, allStars);

  // 3. 只处理变更项
  for (const repo of [...added, ...updated]) {
    const detail = await githubApi.getRepoDetail(repo.full_name);
    const readme = await fetchReadme(repo.full_name);
    const summary = await aiService.summarize(readme);
    await db.upsertItem({ ...detail, readme_summary: summary });
    await vectorIndex.upsert(await generateEmbedding(detail, summary));
  }

  for (const repo of removed) {
    await db.archiveItem(repo.id);  // 软删除，保留数据
  }

  await db.setLastSyncTime(new Date());
}

4.2 AI 摘要生成模块

Prompt 设计

const SUMMARY_PROMPT = `你是一个技术文档摘要专家。请根据以下 GitHub 项目的 README 内容，生成一份简洁的中文摘要。

要求：
1. 摘要长度控制在 100-200 字
2. 包含：项目用途、核心功能、技术栈、适用场景
3. 语言简洁专业，适合开发者快速了解项目
4. 如果 README 是中文，直接提炼；如果是英文，翻译成中文

README 内容：
{readme_content}

请输出纯文本摘要，不要 Markdown 格式：`;

大 README 流式/截断处理

function truncateReadme(readme: string): string {
  const sections = parseReadmeSections(readme);
  const priority = ['description', 'overview', 'features', 'usage', 'getting started'];
  let result = '';
  for (const p of priority) {
    const section = sections.find(s => s.title.toLowerCase().includes(p));
    if (section) result += section.content + '\n';
    if (result.length > 6000) break;
  }
  return result || readme.slice(0, 6000);
}

4.3 自然语言搜索模块

混合搜索策略

interface SearchResult {
  item: Item;
  score: number;
  matchType: 'semantic' | 'keyword' | 'tag';
}

async function search(query: string): Promise<SearchResult[]> {
  // 1. 语义搜索（向量相似度）
  const queryEmbedding = await ai.embed(query);
  const semanticResults = await vectorSearch(queryEmbedding, limit = 50);

  // 2. 关键词搜索（SQLite FTS5）
  const keywordResults = await ftsSearch(query);

  // 3. 标签搜索
  const tagResults = await tagSearch(query);

  // 4. 融合排序（Reciprocal Rank Fusion）
  return reciprocalRankFusion([semanticResults, keywordResults, tagResults], k=60);
}

RRF 融合公式

function reciprocalRankFusion(results: SearchResult[][], k: number): SearchResult[] {
  const scores = new Map<string, number>();

  for (const resultList of results) {
    for (let i = 0; i < resultList.length; i++) {
      const id = resultList[i].item.id;
      const current = scores.get(id) || 0;
      scores.set(id, current + 1 / (k + i + 1));
    }
  }

  return Array.from(scores.entries())
    .sort((a, b) => b[1] - a[1])
    .map(([id, score]) => ({ item: getItem(id), score }));
}

SQLite FTS5 全文搜索

CREATE VIRTUAL TABLE items_fts USING fts5(
    title,
    description,
    readme_content,
    readme_summary,
    content='items',
    content_rowid='id'
);

-- 自动同步触发器
CREATE TRIGGER items_fts_insert AFTER INSERT ON items BEGIN
    INSERT INTO items_fts(rowid, title, description, readme_content, readme_summary)
    VALUES (new.id, new.title, new.description, new.readme_content, new.readme_summary);
END;

4.4 AI 标签网络模块

标签生成策略

async function generateTags(item: Item): Promise<TagSuggestion[]> {
  const prompt = `根据以下项目信息，生成 5-10 个最相关的技术标签。

项目：${item.title}
描述：${item.description}
语言：${item.github_language}
Topics：${item.github_topics?.join(', ')}
README 摘要：${item.readme_summary}

要求：
1. 标签要具体，避免过于宽泛
2. 包含：技术领域、用途类型、语言/框架
3. 返回 JSON 格式
4. 标签名用英文，但 reason 用中文`;

  const response = await ai.chatCompletion(prompt);
  return JSON.parse(response).tags;
}

标签共现网络算法

function buildTagNetwork(items: Item[]): TagNetwork {
  const cooccurrence = new Map<string, number>();
  const tagCounts = new Map<string, number>();

  for (const item of items) {
    const tags = item.tags.map(t => t.name);
    for (const tag of tags) {
      tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
    }
    for (let i = 0; i < tags.length; i++) {
      for (let j = i + 1; j < tags.length; j++) {
        const key = [tags[i], tags[j]].sort().join('|');
        cooccurrence.set(key, (cooccurrence.get(key) || 0) + 1);
      }
    }
  }

  // 过滤低频标签和弱关联
  const nodes = Array.from(tagCounts.entries())
    .filter(([, count]) => count >= 2)
    .map(([name, count]) => ({ id: name, name, count, color: getTagColor(name) }));

  const edges = Array.from(cooccurrence.entries())
    .filter(([, weight]) => weight >= 2)
    .map(([key, weight]) => {
      const [source, target] = key.split('|');
      return { source, target, weight };
    });

  return { nodes, edges };
}

4.5 相似项目推荐模块

推荐算法融合三种信号：

1. 向量相似度：语义相似
2. 标签重叠度：Jaccard 相似度
3. 语言/领域匹配：同编程语言或同领域

async function findSimilarItems(item: Item): Promise<SimilarItem[]> {
  const embedding = await db.getEmbedding(item.id);
  const semanticSimilar = await vectorSearch(embedding, limit = 30);

  const tagSimilar = items.filter(other => {
    const intersection = new Set([...item.tags].filter(t => other.tags.has(t)));
    const union = new Set([...item.tags, ...other.tags]);
    return intersection.size / union.size > 0.3;
  });

  const domainSimilar = items.filter(other => 
    other.github_language === item.github_language && other.id !== item.id
  );

  // 融合排序 + 去重
  const candidates = new Map<string, { item: Item; score: number; reasons: string[] }>();
  for (const [list, reason] of [
    [semanticSimilar, '语义相似'],
    [tagSimilar, '标签匹配'],
    [domainSimilar, '同语言/领域']
  ]) {
    for (const result of list) {
      const existing = candidates.get(result.item.id);
      if (existing) {
        existing.score += result.score * 0.3;
        if (!existing.reasons.includes(reason)) existing.reasons.push(reason);
      } else {
        candidates.set(result.item.id, {
          item: result.item,
          score: result.score,
          reasons: [reason]
        });
      }
    }
  }

  return Array.from(candidates.values())
    .sort((a, b) => b.score - a.score)
    .slice(0, 10);
}

---

五、AI 知识库系统设计

5.1 架构概览

┌─────────────────────────────────────────────────────────────┐
│                     AI 知识库系统                            │
├─────────────────────────────────────────────────────────────┤
│  数据层                                                      │
│  ├── 原始数据：GitHub README、网站内容、软件描述              │
│  ├── 处理数据：AI 摘要、标签、分类                            │
│  └── 向量数据：768 维 Embedding（SQLite-vec 存储）           │
├─────────────────────────────────────────────────────────────┤
│  处理管道（Pipeline）                                          │
│  1. 抓取 → 2. 清洗 → 3. 分块 → 4. Embedding → 5. 索引        │
├─────────────────────────────────────────────────────────────┤
│  查询层                                                       │
│  ├── 语义搜索：向量相似度检索                                  │
│  ├── 关键词搜索：SQLite FTS5                                  │
│  └── 混合排序：RRF 融合 + 重排序                               │
├─────────────────────────────────────────────────────────────┤
│  AI 层（用户自带 API Key）                                    │
│  ├── 摘要生成：gpt-4o-mini / claude-3-haiku                  │
│  ├── Embedding：text-embedding-3-small                        │
│  └── 标签/推荐：gpt-4o-mini                                   │
└─────────────────────────────────────────────────────────────┘

5.2 成本分析（以 1000 个 Stars 为例）

操作	模型	估算 Tokens	成本
README 摘要	gpt-4o-mini	5M	~$1.50
Embedding 生成	text-embedding-3-small	500K	~$0.01
标签生成	gpt-4o-mini	200K	~$0.06
总计一次性			~$1.57
月度增量（新增 50 个 Stars）		~250K	~$0.08/月

结论：即使使用 OpenAI 官方 API，1000 个 Stars 的初始化成本不到 2 美元，后续每月几美分。

5.3 本地 Embedding 备选方案

如果用户不想用 OpenAI Embedding，支持本地模型：

import { pipeline } from '@xenova/transformers';

const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');

async function localEmbedding(text: string): Promise<number[]> {
  const output = await embedder(text, { pooling: 'mean', normalize: true });
  return Array.from(output.data);
}

// 模型大小：~80MB，CPU 运行，延迟~100ms/文本

---

六、多端同步架构

6.1 同步策略：GitHub Gist 作为"无服务器数据库"

┌──────────┐     ┌──────────────┐     ┌──────────┐
│  设备 A   │◄───►│ GitHub Gist  │◄───►│  设备 B  │
│ (本地 DB) │     │ (JSON 数据)  │     │ (本地 DB)│
└──────────┘     └──────────────┘     └──────────┘
       │                │                  │
       └────────────────┴──────────────────┘
                          │
                    冲突解决策略：
                    1. 时间戳优先（Last-Write-Wins）
                    2. 字段级合并（结构数据）
                    3. 手动冲突提示（无法自动合并时）

6.2 同步数据格式

interface SyncPayload {
  version: 1;
  device_id: string;
  timestamp: string;  // ISO 8601
  checksum: string;   // SHA256 of data

  data: {
    items: Item[];
    tags: Tag[];
    collections: Collection[];
    // embeddings 不通过 Gist 同步（太大），各设备本地生成
  };

  changelog: {
    from_version: string;
    to_version: string;
    changes: ChangeRecord[];
  };
}

6.3 增量同步算法

class SyncEngine {
  async sync(): Promise<SyncResult> {
    // 1. 获取云端数据
    const remote = await this.fetchGist();
    const local = await this.getLocalState();

    // 2. 对比变更
    const localChanges = await db.getUnsyncedChanges();

    // 3. 如果云端有更新，先拉取
    if (remote.timestamp > local.lastSyncAt) {
      const merged = this.mergeStates(local.data, remote.data);
      await db.applyChanges(merged.remoteChanges);
    }

    // 4. 推送本地变更
    if (localChanges.length > 0) {
      await this.updateGist({
        ...remote,
        data: this.applyChanges(remote.data, localChanges),
        changelog: { from_version: remote.version, changes: localChanges },
        timestamp: new Date().toISOString()
      });
    }

    // 5. 标记已同步
    await db.markSynced(localChanges.map(c => c.id));

    return { success: true, pushed: localChanges.length, pulled: merged?.remoteChanges.length || 0 };
  }

  private mergeStates(local: Data, remote: Data): MergeResult {
    const merged = { items: new Map(), tags: new Map(), collections: new Map() };
    const conflicts = [];

    // items 按 updated_at 时间戳优先
    for (const [id, item] of [...local.items, ...remote.items]) {
      const existing = merged.items.get(id);
      if (!existing || new Date(item.updated_at) > new Date(existing.updated_at)) {
        merged.items.set(id, item);
      }
    }

    return { data: merged, conflicts, remoteChanges: [] };
  }
}

---

七、前端架构

7.1 Monorepo 项目结构

starvault/
├── apps/
│   ├── web/                    # React Web 应用 (PWA)
│   ├── desktop/                # Tauri 桌面应用
│   ├── mobile/                 # React Native (Expo)
│   └── miniprogram/            # 微信小程序 (Taro)
├── packages/
│   ├── core/                   # 共享核心逻辑（类型、DB、同步、AI、搜索）
│   ├── ui/                     # 共享 UI 组件库
│   └── config/                 # 共享配置（ESLint、TypeScript、Tailwind）
├── turbo.json                  # Turborepo 配置
└── package.json

7.2 主题系统

export const themes = {
  light: {
    '--bg-primary': '#ffffff',
    '--bg-secondary': '#f8fafc',
    '--text-primary': '#0f172a',
    '--text-secondary': '#475569',
    '--accent': '#3b82f6',
    '--success': '#22c55e',
    '--danger': '#ef4444',
  },
  dark: {
    '--bg-primary': '#0f172a',
    '--bg-secondary': '#1e293b',
    '--text-primary': '#f8fafc',
    '--text-secondary': '#cbd5e1',
    '--accent': '#60a5fa',
    '--success': '#4ade80',
    '--danger': '#f87171',
  }
};

Tailwind 配置使用 CSS 变量：

export default {
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        bg: {
          primary: 'var(--bg-primary)',
          secondary: 'var(--bg-secondary)',
        },
        text: {
          primary: 'var(--text-primary)',
          secondary: 'var(--text-secondary)',
        },
        accent: {
          DEFAULT: 'var(--accent)',
        }
      }
    }
  }
};

7.3 核心页面布局

┌─────────────────────────────────────────────────────────┐
│  Sidebar (200px)        │  Main Content                │
│  ┌─────────────────┐    │  ┌─────────────────────────┐ │
│  │  🔍 搜索栏       │    │  │  Header: 视图切换 + 筛选 │ │
│  ├─────────────────┤    │  ├─────────────────────────┤ │
│  │  📁 收藏夹       │    │  │                         │ │
│  │    ├─ 全部       │    │  │   卡片网格 / 列表视图    │ │
│  │    ├─ GitHub    │    │  │                         │ │
│  │    ├─ 网站       │    │  │   ┌─────┐ ┌─────┐      │ │
│  │    ├─ 软件       │    │  │   │Card │ │Card │ ...  │ │
│  │    └─ 工具       │    │  │   └─────┘ └─────┘      │ │
│  ├─────────────────┤    │  │                         │ │
│  │  🏷️ 标签云       │    │  └─────────────────────────┘ │
│  ├─────────────────┤    │                              │
│  │  ⚡ 内置工具      │    │                              │
│  ├─────────────────┤    │                              │
│  │  ⚙️ 设置         │    │                              │
│  └─────────────────┘    └──────────────────────────────┘
└─────────────────────────────────────────────────────────┘

---

八、内置工具设计

工具	实现方式	复杂度
JSON 格式化/校验	JSON.stringify + 语法高亮	低
Base64 编解码	btoa/atob	低
正则表达式测试	RegExp + 匹配高亮	中
颜色选择器/转换	HEX/RGB/HSL 互转	低
时间戳转换	Date API	低
二维码生成	qrcode 库	低
Markdown 预览	react-markdown + remark-gfm	中
JWT 解码	jwt-decode	低
URL 编解码	encodeURIComponent	低
文本对比（Diff）	diff-match-patch	中

工具注册表：

interface Tool {
  id: string;
  name: string;
  icon: string;
  description: string;
  component: React.ComponentType;
  category: 'encode' | 'format' | 'generate' | 'dev';
}

const tools: Tool[] = [
  {
    id: 'json-formatter',
    name: 'JSON 格式化',
    icon: 'braces',
    description: '格式化、校验、压缩 JSON',
    component: JsonFormatter,
    category: 'format'
  },
  // ... 更多工具
];

// 动态加载（代码分割）
const ToolPage = lazy(() => import(`./tools/${toolId}`));

---

九、开发路线图

Phase 1: MVP（4-6 周）

Week 1-2: 基础架构
├── 搭建 Monorepo (Turborepo)
├── 配置 Tailwind + shadcn/ui 主题系统
├── 实现 SQLite 本地数据库
├── 设计并实现核心数据模型
└── 实现 GitHub OAuth 授权 + Stars 列表获取

Week 3-4: 核心功能
├── GitHub Stars 全量同步（分页 + 并发控制）
├── README 抓取 + AI 摘要（接入 OpenAI API）
├── 基础搜索（FTS5 全文搜索）
├── 标签管理（手动添加/编辑）
└── 收藏夹管理（CRUD）

Week 5-6: 多端与同步
├── 实现 GitHub Gist 同步（增量 + 冲突解决）
├── 打包桌面端（Tauri）
├── PWA 配置（离线缓存、Service Worker）
└── 基础 UI 打磨（响应式、动画）

Phase 2: AI 增强（3-4 周）

├── 向量 Embedding 生成与存储（sqlite-vec）
├── 语义搜索实现
├── AI 自动标签生成
├── 标签网络可视化（D3.js / ECharts）
├── 相似项目推荐
└── 支持 Anthropic/兼容接口

Phase 3: 扩展平台（3-4 周）

├── 移动端 App（React Native / Expo）
├── 微信小程序（Taro）
├── 浏览器扩展（一键收藏当前页面）
├── 内置工具集（JSON、Base64 等）
└── 数据导入/导出（HTML 书签、JSON）

Phase 4: Polish（持续）

├── 性能优化（虚拟列表、懒加载）
├── 高级筛选（多维度）
├── 统计面板（Stars 趋势、语言分布）
├── 社区功能（分享收藏集）
└── 插件系统

---

十、开发规范与约定

10.1 代码规范

├── TypeScript: strict 模式
├── ESLint: @antfu/eslint-config
├── 组件: 函数组件 + Hooks，禁止 class 组件
├── 样式: Tailwind 优先，复杂样式用 CSS Modules
├── 状态: Zustand（客户端）+ TanStack Query（服务端）
├── API 调用: 统一封装，自动重试 + 错误处理
└── 测试: Vitest + React Testing Library（核心逻辑必测）

10.2 Git 工作流

main        ─────●─────●─────●─────●─────
               ↑     ↑     ↑     ↑
develop  ─────┘     └─────┘     └─────
               ↑           ↑
feature/xxx ───┘           └──────────
               ↑
fix/xxx ───────┘

10.3 提交规范（Conventional Commits）

feat: 新增 AI 标签生成功能
fix: 修复同步时 Gist ID 丢失问题
docs: 更新 API 文档
style: 调整深色模式配色
refactor: 重构搜索模块
test: 添加同步引擎单元测试
chore: 更新依赖版本

10.4 环境变量

# .env.local (不提交到 Git)
GITHUB_CLIENT_ID=your_github_app_client_id
GITHUB_CLIENT_SECRET=your_github_app_client_secret

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
AI_PROVIDER=openai  # openai | anthropic | custom
AI_BASE_URL=         # 自定义接口地址（可选）

SYNC_PROVIDER=github_gist  # github_gist | github_repo | webdav
SYNC_GIST_ID=               # 首次同步后自动生成

---

十一、项目状态与价值

当前状态

StarVault 目前处于架构设计阶段，已完成：

• 产品定位与核心功能规划
• 技术栈选型与架构设计
• 完整数据模型设计
• AI 知识库、搜索、标签、推荐算法设计
• 多端同步架构设计
• 前端 Monorepo 结构与主题系统设计
• 4 阶段开发路线图

设计亮点

亮点	说明
本地优先	数据主要存在本地 SQLite，隐私安全
零服务器成本	用 GitHub Gist/Repo 做同步，无需租服务器
AI 增强	摘要、标签、语义搜索、相似推荐
多端覆盖	Web、桌面、移动、小程序
混合搜索	向量相似度 + FTS5 关键词 + 标签，RRF 融合
标签网络	基于共现关系构建可视化标签网络
用户自带 API Key	AI 调用成本透明可控

可写进简历的方向

独立设计 StarVault 全平台收藏管理套件架构，覆盖 Web/桌面/移动/小程序多端；规划本地优先 + GitHub Gist 零成本同步方案；设计 AI 知识库系统，实现 README 自动摘要、自然语言搜索、智能标签网络、相似项目推荐；采用 React + Tauri + SQLite-vec + OpenAI Embedding 技术栈，输出完整数据模型、API 设计和开发路线图。

---

十二、项目文档位置

• 本地路径：G:\A_Person\Code\WebDevelopment\StarVault
• 核心文档：StarVault_开发文档.md