@nicekit/steam - NiceSteam

Steam 数据分析与游戏库组件库，三端融合，SQLite 持久化，AI 智能分析

项目概述

NiceSteam 是一个功能完整的 Steam 数据分析与游戏库管理组件库，提供游戏数据导入、分析、比价、AI 智能分析等核心能力。支持 Web、桌面端(Tauri)、移动端(Capacitor) 三端融合，使用 SQLite 进行数据持久化存储。

核心特性

🎮 游戏库管理

• Steam 游戏数据导入（JSON/CSV格式）
• 游戏库统计与分析
• 成就追踪与同步
• 游戏时间统计

📊 数据分析服务

• 多维度玩家画像分析
• 游戏偏好雷达图
• 价值分析与性价比评估
• 游戏趋势分析

💰 多区域比价系统

• AugmentedSteam API 集成
• 15+ Steam 区域价格查询
• 智能汇率转换（3层降级策略）
• 代购分析与推荐

🤖 AI 智能分析

• 游戏库深度分析
• 玩家画像生成
• 游戏推荐引擎
• 雷达图数据生成

📱 三端融合

• Web: React SPA 应用
• 桌面端: Tauri 原生应用
• 移动端: Capacitor 混合应用

🗄️ 数据持久化

• SQLite WebAssembly 存储
• 离线优先策略
• 数据同步机制

安装

npm install @nicekit/steam

# 如需使用 React 组件
npm install react react-dom react-router-dom

# 如需使用核心库功能
npm install @nicekit/core

快速开始

基础使用

import { 
  SteamApiService, 
  SteamPriceService, 
  SteamAnalyticsService 
} from '@nicekit/steam';

// 初始化 Steam API 服务
const apiService = new SteamApiService('your-steam-api-key');

// 获取玩家游戏库
const games = await apiService.getOwnedGames('76561198000000000', {
  includeAppInfo: true,
  includePlayedFreeGames: true
});

// 获取玩家摘要
const summary = await apiService.getPlayerSummaries('76561198000000000');

多区域比价

import { SteamPriceService, STEAM_REGIONS } from '@nicekit/steam';

const priceService = new SteamPriceService();

// 查询游戏多区域价格
const priceResult = await priceService.analyzeAppPrices(123456);
console.log('最便宜区域:', priceResult.proxyAnalysis?.cheapestRegion);
console.log('代购分析:', priceResult.proxyAnalysis);

// 批量查询价格
const batchResults = await priceService.batchAnalyzePrices([123456, 789012, 345678]);

AI 分析

import { SteamAnalyticsService } from '@nicekit/steam';

const analyticsService = new SteamAnalyticsService();

// 生成玩家画像
const persona = await analyticsService.generatePlayerPersona(games);
console.log('玩家类型:', persona.tier);
console.log('游戏偏好:', persona.dimensions);

// 游戏库分析
const analysis = await analyticsService.analyzeLibrary(games);
console.log('总游戏时间:', analysis.totalPlaytime);
console.log('最爱类型:', analysis.favoriteGenres);

React 组件使用

import { 
  SteamDashboard, 
  SteamImportPage, 
  SteamPriceComparePage 
} from '@nicekit/steam';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<SteamDashboard />} />
        <Route path="/import" element={<SteamImportPage />} />
        <Route path="/price-compare" element={<SteamPriceComparePage />} />
      </Routes>
    </BrowserRouter>
  );
}

核心服务详解

1. SteamApiService - Steam 官方 Web API 客户端

封装全部 25+ 官方端点，通过 HttpAdapter 统一发起请求。

const apiService = new SteamApiService(apiKey);

// ISteamUser 接口
const summaries = await apiService.getPlayerSummaries(steamIds);
const friends = await apiService.getFriendList(steamId);
const bans = await apiService.getPlayerBans(steamIds);
const groups = await apiService.getUserGroupList(steamId);
const steamId = await apiService.resolveVanityURL('customurl');

// IPlayerService 接口
const games = await apiService.getOwnedGames(steamId);
const level = await apiService.getSteamLevel(steamId);
const badges = await apiService.getBadges(steamId);
const recentGames = await apiService.getRecentlyPlayedGames(steamId);

// ISteamUserStats 接口
const achievements = await apiService.getPlayerAchievements(steamId, appId);
const stats = await apiService.getUserStats(steamId, appId);
const globalAch = await apiService.getGlobalAchievementPercentages(appId);
const schema = await apiService.getSchemaForGame(appId);

// ISteamApps 接口
const appList = await apiService.getAppList();
const servers = await apiService.getServersAtAddress(ip);

// 其他接口
const news = await apiService.getNewsForApp(appId);
const mostPlayed = await apiService.getMostPlayedGames();
const currentPlayers = await apiService.getCurrentPlayers(appId);

2. SteamLowPriceService - 低价分析服务

基于 AugmentedSteam API 的多区域价格查询与分析服务。

import { SteamLowPriceService, STEAM_REGIONS, DEFAULT_SYNC_REGIONS } from '@nicekit/steam';

const lowPriceService = new SteamLowPriceService();

// 查询单游戏多区域价格
const result = await lowPriceService.analyzeAppPrices(123456);
console.log('价格概览:', result.priceOverview);
console.log('代购分析:', result.proxyAnalysis);
console.log('历史最低:', result.historicalLow);
console.log('区域价格:', result.regionPrices);

// 批量查询价格
const batchResults = await lowPriceService.batchAnalyzePrices([123456, 789012, 345678]);

// 获取汇率
await lowPriceService.ensureRatesAvailable();
const cnyPrice = await lowPriceService.convertToCNY(9.99, 'USD');
console.log('转换为人民币:', lowPriceService.formatCNY(cnyPrice));

// 计算性价比评分
const valueScore = lowPriceService.calculateValueScore(
  68,      // 价格（人民币）
  85,      // Metacritic 评分
  20       // 游戏时间（小时）
);
console.log('性价比评分:', valueScore);

// 支持的区域
console.log('所有区域:', lowPriceService.getAllRegions());
console.log('货币配置:', lowPriceService.getCurrencyConfig('USD'));

3. SteamPriceService - 多区域比价服务

基于 AugmentedSteam API 的多区域价格查询与分析服务。

const priceService = new SteamPriceService();

// 查询单游戏多区域价格
const result = await priceService.analyzeAppPrices(appId);
console.log(result.priceOverview);    // 价格概览
console.log(result.proxyAnalysis);    // 代购分析
console.log(result.regionPrices);     // 区域价格列表
console.log(result.historicalLow);    // 历史最低价

// 批量查询
const batchResult = await priceService.batchAnalyzePrices([appId1, appId2, appId3]);

// 获取汇率
await priceService.ensureRatesAvailable();
const cnyPrice = priceService.convertToCNY(9.99, 'USD');

// 支持的区域
import { STEAM_REGIONS, DEFAULT_SYNC_REGIONS } from '@nicekit/steam';
console.log(STEAM_REGIONS);           // 所有支持的区域
console.log(DEFAULT_SYNC_REGIONS);    // 默认同步区域列表

4. SteamMetaService - 第三方元数据聚合服务

聚合 HLTB、Metacritic、OpenCritic、SteamPeek 等第三方数据源。

const metaService = new SteamMetaService();

// 商店页面聚合数据
const storeData = await metaService.fetchStorePageData(appId);
console.log(storeData.hltb);           // HowLongToBeat 数据
console.log(storeData.reviews);        // 评测数据
console.log(storeData.players);        // 在线玩家数据
console.log(storeData.familySharing);  // 家庭共享支持

// 相似游戏推荐
const similarGames = await metaService.fetchSimilarGames(appId);
console.log(similarGames);             // 相似游戏列表

// DLC 信息
const dlcInfo = await metaService.fetchDlcInfo(appId);
console.log(dlcInfo.dlcs);             // DLC 列表

// 卡牌市场价格
const cardPrices = await metaService.fetchCardPrices(appId);
console.log(cardPrices);               // 卡牌价格数据

// 绝版游戏追踪
const delistedGames = await metaService.fetchDelistedGames();
console.log(delistedGames);            // 绝版游戏列表

// 商店应用详情元数据
const appMetadata = await metaService.fetchAppMetadata(appId);
console.log(appMetadata.workshopSupport);  // 创意工坊支持
console.log(appMetadata.screenshots);      // 截图列表
console.log(appMetadata.categories);       // 分类信息
console.log(appMetadata.platforms);        // 平台支持

4. SteamSyncService - 同步编排服务

协调 API 和 DAO 的数据同步，支持成就断点续传。

const syncService = new SteamSyncService();

// 同步成就数据
const syncResult = await syncService.syncAchievements({
  steamId: '76561198000000000',
  appId: 123456,
  onProgress: (progress) => {
    console.log(`同步进度: ${progress.current}/${progress.total}`);
  }
});

// 同步游戏库
await syncService.syncGameLibrary(steamId);

// 同步好友列表
await syncService.syncFriends(steamId);

5. SteamImportService - 数据导入服务

支持 JSON/CSV 格式的游戏数据导入。

const importService = new SteamImportService();

// 导入 JSON 数据
const jsonResult = await importService.importFromJson(jsonData);
console.log('导入结果:', jsonResult);

// 导入 CSV 数据
const csvResult = await importService.importFromCsv(csvData);
console.log('导入结果:', csvResult);

6. SteamAnalyticsService - 分析计算服务

SQL 聚合 + 5 维度玩家画像引擎。

const analyticsService = new SteamAnalyticsService();

// 生成玩家画像
const persona = await analyticsService.generatePlayerPersona(games);
console.log('玩家等级:', persona.tier);        // casual/regular/hardcore/whale
console.log('游戏偏好:', persona.dimensions);   // 5个维度分析

// 游戏库分析报告
const report = await analyticsService.analyzeLibrary(games);
console.log('总游戏时间:', report.totalPlaytime);
console.log('最爱类型:', report.favoriteGenres);
console.log('价值分析:', report.valueAnalysis);
console.log('成就分析:', report.achievementAnalysis);

// 生成雷达图数据
const radarData = await analyticsService.generateRadarData(games);
console.log(radarData);  // 用于 Chart.js 等图表库

核心模块

SteamID 标识符处理

import { SteamID, GameID } from '@nicekit/steam';

// SteamID 转换
const steamId = new SteamID('76561198000000000');
console.log(steamId.getSteamID64());      // 76561198000000000
console.log(steamId.getSteamID2());       // STEAM_0:0:12345678
console.log(steamId.getSteamID3());       // [U:1:12345678]
console.log(steamId.getAccountID());      // 12345678
console.log(steamId.getAccountType());    // Individual

// GameID 处理
const gameId = new GameID(123456);
console.log(gameId.getAppId());           // 123456
console.log(gameId.getType());            // Game

工具函数

import { 
  // CDN URL 工具
  getAvatarURL,
  getAppIconURL,
  getAppHeaderURL,
  getCapsuleURL,
  getStoreURL,
  
  // 格式化工具
  formatPlaytime,
  formatFileSize,
  getPersonaStateText,
  
  // 验证工具
  isValidApiKey,
  isValidSteamId64,
  isValidAppId,
  extractSteamIdFromURL,
  extractAppIdFromStoreURL,
  
  // 卡牌挂卡推断
  inferCardDropProgress,
  buildFarmableGame,
  buildBadgeMap,
  
  // 徽章解析
  classifySteamBadge,
  resolveSteamBadgeName,
} from '@nicekit/steam';

// 使用示例
const avatarUrl = getAvatarURL('abc123');
const playtime = formatPlaytime(12345);  // "205h 45m"
const isValid = isValidSteamId64('76561198000000000');
const appId = extractAppIdFromStoreURL('https://store.steampowered.com/app/123456/');

常量定义

import { 
  STEAM_WEB_API_BASE,
  STEAM_STORE_API_BASE,
  STEAM_COMMUNITY_BASE,
  STEAM_CDN_BASE,
  STEAM_INTERFACES,
  STEAM_METHODS,
  EPersonaState,
  PERSONA_STATE_NAMES,
  EFriendRelationship,
  GAME_LANGUAGES,
  STEAM_STORE_CATEGORIES,
  STEAM_REGIONS,
  REGION_CURRENCY_MAP,
} from '@nicekit/steam';

// 使用示例
console.log(STEAM_WEB_API_BASE);  // 'https://api.steampowered.com'
console.log(EPersonaState.Online); // 1
console.log(PERSONA_STATE_NAMES[1]); // 'Online'

服务层架构

@nicekit/steam
├── services/               # 服务层
│   ├── SteamApiService    # Steam 官方 Web API 客户端
│   ├── SteamStoreService  # 内部 Store API（熔断 + TTL 缓存 + 去重）
│   ├── SteamMetaService   # 第三方元数据聚合
│   ├── SteamPriceService  # 多区域比价与代购分析
│   ├── SteamLowPriceService # 低价分析服务（区域价格查询 + 汇率转换）
│   ├── SteamSyncService   # 同步编排（API+DAO 协调）
│   ├── SteamImportService # 数据导入（JSON/CSV 解析写入 SQLite）
│   └── SteamAnalyticsService # 分析计算（SQL 聚合 + 5 维度玩家画像）
├── hooks/                  # React Hooks
│   ├── useSteamServices   # 服务实例管理
│   ├── useSteamSync       # 同步状态管理
│   ├── useSteamPrice      # 价格查询
│   ├── useSteamAnalytics  # 分析计算
│   └── useSocial          # 社交功能
├── store/                  # 状态管理（Zustand）
├── db/                     # 数据库层（SQLite + DAO）
├── components/             # UI 组件
│   ├── steam/             # Steam 专用组件
│   ├── library/           # 游戏库组件
│   ├── pages/             # 页面组件
│   └── ui/                # 基础 UI 组件
├── utils/                  # 工具函数
│   ├── steamId.ts         # SteamID 标识符处理
│   └── steamUtils.ts      # CDN URL、格式化、验证等工具
├── platform/               # 平台适配层（Tauri/Capacitor/Web）
└── types/                  # TypeScript 类型定义

依赖关系

核心依赖

{
  "@nicekit/core": ">=0.2.0",
  "react": ">=18.0.0",
  "react-dom": ">=18.0.0",
  "react-router-dom": ">=7.0.0"
}

主要依赖

• sql.js: SQLite WebAssembly 实现
• zustand: 轻量级状态管理
• framer-motion: 动画库
• lucide-react: 图标库
• clsx: 类名合并工具
• tailwind-merge: Tailwind 类名合并

平台适配

NiceSteam 通过平台适配层支持三端运行：

Web 平台

// 自动使用浏览器原生 fetch
const httpAdapter = getHttpAdapter();

Tauri 桌面端

// 使用 Tauri HTTP 客户端，绕过 CORS
const httpAdapter = getHttpAdapter();

Capacitor 移动端

// 使用 Capacitor HTTP 插件
const httpAdapter = getHttpAdapter();

配置

API Key 配置

import { SteamApiService } from '@nicekit/steam';

const apiService = new SteamApiService('your-steam-api-key');

// 或动态更新
apiService.setApiKey('new-api-key');

数据库配置

import { initializeDatabase } from '@nicekit/steam';

// 初始化 SQLite 数据库
await initializeDatabase();

最佳实践

1. 错误处理

import { SteamApiService } from '@nicekit/steam';

try {
  const games = await apiService.getOwnedGames(steamId);
} catch (error) {
  if (error.code === 'RATE_LIMIT') {
    // 处理限流
    await delay(error.retryAfter);
  } else if (error.code === 'INVALID_API_KEY') {
    // 处理 API Key 错误
    console.error('请检查 API Key');
  }
}

2. 缓存策略

import { SteamPriceService } from '@nicekit/steam';

const priceService = new SteamPriceService();

// 自动使用缓存
const result = await priceService.analyzeAppPrices(appId);

// 清除缓存
priceService.clearCache();

3. 批量请求

// 自动分页处理
const summaries = await apiService.getPlayerSummaries([
  '76561198000000001',
  '76561198000000002',
  '76561198000000003',
  // ... 支持任意数量，自动分页 100人/批
]);

4. React Hooks 使用

import { useSteamServices, useSteamPrice, useSteamAnalytics } from '@nicekit/steam';

function GameDetail({ appId }: { appId: number }) {
  const { priceService } = useSteamServices();
  const { price, loading, error } = useSteamPrice(appId);
  const { analysis, analyze } = useSteamAnalytics();

  useEffect(() => {
    if (price) {
      analyze(price);
    }
  }, [price]);

  if (loading) return <div>加载中...</div>;
  if (error) return <div>错误: {error.message}</div>;

  return (
    <div>
      <h2>游戏价格</h2>
      <p>当前价格: {price.current}</p>
      <p>历史最低: {price.historicalLow}</p>
      {analysis && (
        <div>
          <h3>分析结果</h3>
          <p>性价比评分: {analysis.valueScore}</p>
        </div>
      )}
    </div>
  );
}

开发指南

安装依赖

cd nice-steam
npm install

开发模式

npm run dev

构建

# 构建组件库
npm run build:lib

# 构建 Web 应用
npm run build

# 构建 Tauri 桌面应用
npm run tauri:build

# 构建 Android APK
npm run build:apk

测试

npm run test:e2e

更新日志

v0.3.0

• 新增 SteamLowPriceService 低价分析服务（参考 steam-kit）
• 新增 SteamID 标识符处理模块（SteamID64/SteamID2/SteamID3 转换）
• 新增 GameID 处理模块
• 新增 CDN URL 工具函数（头像、图标、截图、视频等）
• 新增格式化工具（游戏时间、文件大小、在线状态等）
• 新增验证工具（API Key、SteamID64、App ID 验证）
• 新增卡牌挂卡推断功能
• 新增徽章解析与分类功能
• 新增通用工具函数（防抖、节流、深拷贝、JSON 解析等）
• 完善 README 文档，添加详细使用示例

v0.2.0

• 新增多区域比价系统
• 新增 AI 智能分析功能
• 新增绝版游戏追踪
• 新增卡牌市场价格查询
• 优化三端融合架构

v0.1.0

• 初始版本发布
• 基础游戏库管理
• 数据导入导出
• 基础统计分析

许可证

MIT License

联系方式

• 项目主页: https://github.com/SmallRob/nicekit-projects
• 问题反馈: https://github.com/SmallRob/nicekit-projects/issues

相关项目

• @nicekit/core - 核心 AI 工具库
• @nicekit/cli - CLI 工具包
• @nicekit/mcp - MCP 协议服务组件
• @nicekit/agent - AI Agent 管理平台