trackswap 0.0.2 → 0.0.4

package/README.md

@@ -1,18 +1,31 @@
-# TrackSwap - GPX 轨迹处理库
+# TrackSwap - 多格式轨迹处理库
 
-一个功能强大、插件化的 GPX 轨迹文件处理库，支持解析、编码、转换和扩展。
+一个强大的多格式轨迹文件处理库，支持 GPX、FIT、TCX 文件的解析、编码和格式转换。
 
-## 🚀 快速开始
+---
 
-### 安装
+**🌐 Language / 语言**: [English](README_EN.md) | [中文](README.md)
+
+---
+
+## 🚀 特性
+
+- 🔄 **多格式支持**: GPX 1.1、FIT、TCX 格式
+- 🎯 **统一转换**: 任意格式之间相互转换
+- 🤖 **自动检测**: 智能识别文件格式
+- 🔧 **插件架构**: 基于插件的可扩展设计
+- 🛡️ **类型安全**: 完整的 TypeScript 支持
+- ⚡ **高性能**: 优化的解析和编码算法
+
+## 📦 安装
 
 ```bash
 npm install trackswap
 ```
 
-## 📖 How to use
+## 🎯 快速开始
 
-最简单的GPX文件处理：
+### 基本使用
 
 ```typescript
 import { TrackSwap } from 'trackswap';
@@ -20,364 +33,398 @@ import fs from 'fs';
 
 const trackSwap = new TrackSwap();
 
-// 解析GPX文件
-async function parseGPX() {
-  const buffer = fs.readFileSync('track.gpx');
-  const gpxData = await trackSwap.parseGPX(buffer);
-  
-  console.log('GPX版本:', gpxData?.version);
-  console.log('轨迹数量:', gpxData?.trk?.length);
-}
+// 解析 GPX 文件
+const gpxBuffer = fs.readFileSync('track.gpx');
+const gpxData = await trackSwap.parseGPX(gpxBuffer);
 
-// 从字符串解析
-async function parseFromString() {
-  const xmlString = `<?xml version="1.0"?>
-    <gpx version="1.1" creator="TrackSwap">
-      <wpt lat="39.9042" lon="116.4074">
-        <name>北京</name>
-      </wpt>
-    </gpx>`;
-  
-  const gpxData = await trackSwap.parseGPXString(xmlString);
-  console.log('航路点:', gpxData?.wpt?.[0]?.name);
-}
-```
+// 解析 FIT 文件
+const fitBuffer = fs.readFileSync('activity.fit');
+const fitData = await trackSwap.parseFIT(fitBuffer);
 
+// 解析 TCX 文件
+const tcxBuffer = fs.readFileSync('workout.tcx');
+const tcxData = await trackSwap.parseTCX(tcxBuffer);
+```
 
-## 🔧 API 参考
+### 格式转换
 
-### TrackSwap
+```typescript
+// 🔄 自动检测格式并转换
+const gpxBuffer = await trackSwap.convertFile(anyBuffer, 'gpx');
+const fitBuffer = await trackSwap.convertFile(anyBuffer, 'fit');
+const tcxBuffer = await trackSwap.convertFile(anyBuffer, 'tcx');
+
+// 🎯 指定源格式转换（提升性能）
+const convertedBuffer = await trackSwap.convertFile(
+  sourceBuffer, 
+  'fit',      // 目标格式
+  'gpx'       // 源格式（可选）
+);
+```
 
-| 方法 | 说明 | 参数 | 返回值 |
-|------|------|------|--------|
-| `parseGPX(buffer)` | 解析GPX Buffer | `Buffer` | `Promise<GPX11Type \| undefined>` |
-| `parseGPXString(xml)` | 解析GPX字符串 | `string` | `Promise<GPX11Type \| undefined>` |
-| `encodeGPX(data)` | 编码为Buffer | `GPX11Type` | `Promise<Buffer>` |
-| `encodeGPXString(data)` | 编码为字符串 | `GPX11Type` | `string` |
-| `getDecoder()` | 获取解码器实例 | - | `GPXDecoder` |
-| `getEncoder()` | 获取编码器实例 | - | `GPXEncoder` |
-| `destroy()` | 清理资源 | - | `Promise<void>` |
+### 自动解析
 
+```typescript
+// 🤖 自动检测格式并解析
+const parsedData = await trackSwap.parseFile(buffer);
 
+// 🏃‍♂️ 解析并转换为统一的运动数据格式
+const sportData = await trackSwap.parseToSport(buffer);
+```
 
-# GPX 流水线插件化解码器
+## 📖 详细使用指南
 
-这是一个基于流水线(Pipeline)和插件架构的GPX文件解码器，采用了现代化的设计模式，支持完整的插件生命周期管理和中间件机制。
+### 1. 文件解析
 
-🏗️  GPX解码器架构说明:
-
-┌─────────────────────────────────────────────────────────────┐
-│                    GPX解码器架构图                             │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  🔧 固定核心处理器 (不可修改)                                  │
-│  ┌─────────────────────────────────────────────────────────┐ │
-│  │ 1. TokenizeProcessor    - XML → Tokens                 │ │
-│  │ 2. AstGenerateProcessor - Tokens → AST                 │ │
-│  │ 3. ConvertProcessor     - AST → GPX对象                 │ │
-│  │ 4. CompleteProcessor    - 最终化处理                     │ │
-│  └─────────────────────────────────────────────────────────┘ │
-│                                                             │
-│  🔌 可扩展中间件 (真正的扩展点)                                │
-│  ┌─────────────────────────────────────────────────────────┐ │
-│  │ • onTokenize()    - Token增强、过滤                     │ │
-│  │ • onAstGenerate() - AST结构增强                         │ │
-│  │ • onConvert()     - 转换结果增强                        │ │
-│  │ • onComplete()    - 最终结果处理                        │ │
-│  │ • onError()       - 错误处理                           │ │
-│  └─────────────────────────────────────────────────────────┘ │
-│                                                             │
-│  📦 转换器插件 (支持优先级)                                   │
-│  ┌─────────────────────────────────────────────────────────┐ │
-│  │ • 默认转换器：wpt, rte, trk, metadata...               │ │
-│  │ • 自定义转换器：扩展标签、覆盖默认行为                    │ │
-│  │ • 优先级系统：多转换器处理同一标签                       │ │
-│  └─────────────────────────────────────────────────────────┘ │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-
-## 📋 快速开始
+#### GPX 文件处理
 
 ```typescript
-import { GPXDecoder } from './decoder';
-import { registerDefaultMiddlewares } from './converters';
+// 从 Buffer 解析
+const gpxData = await trackSwap.parseGPX(buffer);
 
-const decoder = new GPXDecoder();
-// 可选：注册默认中间件（性能监控、验证等）
-await registerDefaultMiddlewares(decoder);
+// 从字符串解析
+const gpxData = await trackSwap.parseGPXString(xmlString);
 
-// 解析GPX文件
-const buffer = fs.readFileSync('track.gpx');
-const gpxData = await decoder.parserByBuffer(buffer);
+// 编码为 Buffer
+const buffer = await trackSwap.encodeGPX(gpxData);
 
-// 销毁解码器
-await decoder.destroy();
+// 编码为字符串
+const xmlString = trackSwap.encodeGPXString(gpxData);
 ```
 
+#### FIT 文件处理
 
-## 🏗️ 架构设计
+```typescript
+// 解析 FIT 文件
+const fitData = await trackSwap.parseFIT(buffer);
 
-### 自动注册的组件
+// 编码为 Activity 文件
+const activityBuffer = await trackSwap.encodeFIT(fitData);
 
-创建`GPXDecoder`实例时，以下组件会自动注册：
+// 编码为 Course 文件
+const courseBuffer = await trackSwap.encodeFITCourse(fitData);
+```
 
-#### 🔧 核心流水线处理器（自动注册）
-- `TokenizeProcessor`: XML → Token数组
-- `AstGenerateProcessor`: Token数组 → AST
-- `ConvertProcessor`: AST → GPX对象 
-- `CompleteProcessor`: 性能统计和清理
+#### TCX 文件处理
 
-#### ✅ 默认转换器（自动注册）
-- `WptConverter`: 处理 `<wpt>`, `<trkpt>`, `<rtept>` 标签
-- `RteConverter`: 处理 `<rte>` 路线标签
-- `TrkConverter`: 处理 `<trk>` 轨迹标签  
-- `TrksegConverter`: 处理 `<trkseg>` 轨迹段标签
-- `MetadataConverter`: 处理 `<metadata>` 元数据标签
-- `LinkConverter`: 处理 `<link>` 链接标签
-- `PersonConverter`: 处理 `<author>` 作者标签
-- `EmailConverter`: 处理 `<email>` 邮箱标签
-- `CopyrightConverter`: 处理 `<copyright>` 版权标签
-- `BoundsConverter`: 处理 `<bounds>` 边界标签
+```typescript
+// 从 Buffer 解析
+const tcxData = await trackSwap.parseTCX(buffer);
 
-#### 🔌 用户注册的组件
-- **自定义转换器**: 处理扩展标签或覆盖默认行为
-- **中间件**: 在流水线各阶段插入自定义逻辑
+// 从字符串解析
+const tcxData = await trackSwap.parseTCXString(xmlString);
 
-### 流水线阶段
+// 编码为 Buffer
+const buffer = await trackSwap.encodeTCX(tcxData);
 
-```
-Input Buffer → Tokenize → AST Generate → Convert → Complete → Output
-     ↓            ↓            ↓           ↓          ↓
-  中间件钩子   中间件钩子    中间件钩子   中间件钩子  中间件钩子
+// 编码为字符串
+const xmlString = await trackSwap.encodeTCXString(tcxData);
 ```
 
-## 🔧 创建转换器插件
+### 2. 格式转换
 
-### 基础转换器
+#### 统一转换方法
 
 ```typescript
-import { BaseConverter } from './decoder';
-
-class MyConverter extends BaseConverter {
-  name = 'my-converter';
-  supportedTags = ['custom-tag'];
-  priority = 50; // 优先级，数字越小优先级越高
-
-  convert(ast: TokenAST, context: DecoderContext): MyDataType | undefined {
-    // 验证必要属性
-    if (!this.hasRequiredAttributes(ast, ['required-attr'])) {
-      return undefined;
-    }
-
-    const result: MyDataType = {
-      value: this.parseFloat(ast.value),
-      name: this.parseString(ast.attributes?.name)
-    };
+// 🔄 自动检测并转换
+const result = await trackSwap.convertFile(sourceBuffer, 'gpx');
 
-    // 处理子节点
-    this.processChildren(ast, result, {
-      'child-tag': (child, target) => {
-        target.childValue = this.parseString(child.value);
-      }
-    });
+// 🎯 指定格式转换
+const result = await trackSwap.convertFile(sourceBuffer, 'fit', 'gpx');
 
-    return result;
-  }
+// 📊 支持的转换组合
+// GPX ↔ FIT ↔ TCX (任意格式之间相互转换)
+```
 
-  // 可选的生命周期钩子
-  async initialize(context: DecoderContext): Promise<void> {
-    console.log(`${this.name} 转换器初始化`);
-  }
+#### SportFileType 统一格式
 
-  async destroy(context: DecoderContext): Promise<void> {
-    console.log(`${this.name} 转换器销毁`);
-  }
-}
+```typescript
+// 转换为统一的运动数据格式
+const gpxSport = await trackSwap.convertGPXToSport(gpxData);
+const fitSport = await trackSwap.convertFITToSport(fitData);
+const tcxSport = await trackSwap.convertTCXToSport(tcxData);
+
+// 从统一格式转换回具体格式
+const gpxData = await trackSwap.convertSportToGPX(sportData);
+const fitData = await trackSwap.convertSportToFIT(sportData);
+const tcxData = await trackSwap.convertSportToTCX(sportData);
 ```
 
-### 注册和使用
+### 3. 智能解析
 
 ```typescript
-const decoder = new GPXDecoder(); // 默认转换器已就绪
-await decoder.registerConverter(new MyConverter());
+// 🤖 自动检测格式
+const format = trackSwap.detectFormat(buffer);
+console.log(`检测到格式: ${format}`); // 'gpx' | 'fit' | 'tcx' | 'unknown'
 
-// 验证注册
-console.log(decoder.listConverters()); // 包含 'custom-tag' 和所有默认标签
-```
+// 📂 统一解析方法
+const parsedData = await trackSwap.parseFile(buffer);
+const parsedData = await trackSwap.parseFile(buffer, 'gpx'); // 指定格式
 
-## 🔄 创建中间件插件
+// 🏃‍♂️ 解析为统一格式
+const sportData = await trackSwap.parseToSport(buffer);
+const sportData = await trackSwap.parseToSport(buffer, 'fit'); // 指定格式
+```
 
-### 基础中间件
+## 🔧 API 参考
 
-```typescript
-import { BaseMiddleware } from './decoder';
+### TrackSwap 类
 
-class MyMiddleware extends BaseMiddleware {
-  name = 'my-middleware';
-  description = '我的自定义中间件';
+#### 解析方法
 
-  // Token处理阶段
-  async onTokenize(tokens: Token[], context: DecoderContext): Promise<Token[]> {
-    console.log(`处理了 ${tokens.length} 个token`);
-    // 可以修改或过滤token
-    return tokens.filter(token => token.type !== 'unwanted');
-  }
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `parseGPX(buffer)` | 解析 GPX Buffer | `Buffer` | `Promise<GPX11Type \| undefined>` |
+| `parseGPXString(xml)` | 解析 GPX 字符串 | `string` | `Promise<GPX11Type \| undefined>` |
+| `parseFIT(buffer)` | 解析 FIT Buffer | `Buffer` | `Promise<FITFileType>` |
+| `parseTCX(buffer)` | 解析 TCX Buffer | `Buffer` | `Promise<TCXFileType>` |
+| `parseTCXString(xml)` | 解析 TCX 字符串 | `string` | `Promise<TCXFileType>` |
+| `parseFile(buffer, type?)` | 统一解析方法 | `Buffer, string?` | `Promise<GPX11Type \| FITFileType \| TCXFileType>` |
+| `parseToSport(buffer, type?)` | 解析为统一格式 | `Buffer, string?` | `Promise<SportFileType>` |
 
-  // AST生成阶段
-  async onAstGenerate(ast: TokenAST, context: DecoderContext): Promise<TokenAST> {
-    // 可以修改AST结构
-    this.addCustomProperties(ast);
-    return ast;
-  }
+#### 编码方法
 
-  // 转换阶段
-  async onConvert(result: any, context: DecoderContext): Promise<any> {
-    // 可以对转换结果进行后处理
-    result.processedBy = this.name;
-    return result;
-  }
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `encodeGPX(data)` | 编码 GPX 为 Buffer | `GPX11Type` | `Promise<Buffer>` |
+| `encodeGPXString(data)` | 编码 GPX 为字符串 | `GPX11Type` | `string` |
+| `encodeFIT(data)` | 编码 FIT 为 Buffer | `FITFileType` | `Promise<Buffer>` |
+| `encodeFITCourse(data)` | 编码 FIT Course | `FITFileType` | `Promise<Buffer>` |
+| `encodeTCX(data)` | 编码 TCX 为 Buffer | `TCXFileType` | `Promise<Buffer>` |
+| `encodeTCXString(data)` | 编码 TCX 为字符串 | `TCXFileType` | `Promise<string>` |
 
-  // 完成阶段
-  async onComplete(result: GPX11Type, context: DecoderContext): Promise<GPX11Type> {
-    // 最终处理
-    const performance = context.metadata.get('performance');
-    console.log('处理完成，性能指标:', performance);
-    return result;
-  }
+#### 转换方法
 
-  // 错误处理
-  async onError(error: Error, context: DecoderContext): Promise<void> {
-    console.error(`中间件 ${this.name} 捕获错误:`, error.message);
-    // 可以进行错误上报、恢复等操作
-  }
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `convertFile(buffer, target, source?)` | 统一转换方法 | `Buffer, string, string?` | `Promise<Buffer>` |
+| `convertGPXToSport(data)` | GPX → Sport | `GPX11Type` | `Promise<SportFileType>` |
+| `convertFITToSport(data)` | FIT → Sport | `FITFileType` | `Promise<SportFileType>` |
+| `convertTCXToSport(data)` | TCX → Sport | `TCXFileType` | `Promise<SportFileType>` |
+| `convertSportToGPX(data)` | Sport → GPX | `SportFileType` | `Promise<GPX11Type>` |
+| `convertSportToFIT(data)` | Sport → FIT | `SportFileType` | `Promise<FITFileType>` |
+| `convertSportToTCX(data)` | Sport → TCX | `SportFileType` | `Promise<TCXFileType>` |
 
-  private addCustomProperties(ast: TokenAST): void {
-    // 添加自定义属性逻辑
-  }
-}
-```
+#### 工具方法
 
-### 注册中间件
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `detectFormat(buffer)` | 检测文件格式 | `Buffer` | `'gpx' \| 'fit' \| 'tcx' \| 'unknown'` |
+| `getSportProcessor()` | 获取运动处理器 | - | `SportProcessor` |
+| `destroy()` | 清理资源 | - | `Promise<void>` |
 
-```typescript
-const decoder = new GPXDecoder();
-await decoder.registerMiddleware(new MyMiddleware());
+## 🌟 实际应用示例
 
-console.log(decoder.listMiddlewares()); // 包含 'my-middleware'
-```
+### 批量格式转换
 
-## 🎯 实际示例
+```typescript
+import { TrackSwap } from 'trackswap';
+import fs from 'fs';
+import path from 'path';
 
-### 最简洁的使用方式
+async function batchConvert(inputDir: string, outputFormat: 'gpx' | 'fit' | 'tcx') {
+  const trackSwap = new TrackSwap();
+  const files = fs.readdirSync(inputDir);
+  
+  for (const file of files) {
+    try {
+      const inputPath = path.join(inputDir, file);
+      const buffer = fs.readFileSync(inputPath);
+      
+      // 🔄 自动检测并转换
+      const converted = await trackSwap.convertFile(buffer, outputFormat);
+      
+      const outputPath = path.join(inputDir, 
+        `${path.parse(file).name}.${outputFormat}`);
+      fs.writeFileSync(outputPath, converted);
+      
+      console.log(`✅ 转换完成: ${file} → ${outputFormat}`);
+    } catch (error) {
+      console.error(`❌ 转换失败: ${file}`, error);
+    }
+  }
+  
+  await trackSwap.destroy();
+}
 
-```typescript
-// 🎉 一行创建，立即可用！
-const decoder = new GPXDecoder();
-const result = await decoder.parserByBuffer(buffer);
+// 使用示例
+await batchConvert('./tracks', 'gpx');
 ```
 
-### 带中间件的使用方式
+### 轨迹数据分析
 
 ```typescript
-import { registerDefaultMiddlewares } from './converters';
-
-const decoder = new GPXDecoder();
-await registerDefaultMiddlewares(decoder); // 性能监控、验证等
-const result = await decoder.parserByBuffer(buffer);
+async function analyzeTrack(buffer: Buffer) {
+  const trackSwap = new TrackSwap();
+  
+  // 🔍 检测格式
+  const format = trackSwap.detectFormat(buffer);
+  console.log(`文件格式: ${format}`);
+  
+  // 📊 转换为统一格式进行分析
+  const sportData = await trackSwap.parseToSport(buffer);
+  
+  // 分析数据
+  const analysis = {
+    totalDistance: sportData.summary?.totalDistance || 0,
+    totalTime: sportData.summary?.totalTime || 0,
+    avgSpeed: sportData.summary?.avgSpeed || 0,
+    maxSpeed: sportData.summary?.maxSpeed || 0,
+    trackPoints: sportData.tracks?.[0]?.segments?.[0]?.points?.length || 0
+  };
+  
+  console.log('轨迹分析结果:', analysis);
+  
+  await trackSwap.destroy();
+  return analysis;
+}
 ```
 
-### 自定义扩展处理
+### 多格式数据融合
 
 ```typescript
-// Garmin扩展转换器
-class GarminExtensionConverter extends BaseConverter {
-  name = 'garmin-extension';
-  supportedTags = ['gpxtpx:TrackPointExtension'];
-
-  convert(ast: TokenAST, context: DecoderContext): GarminExtension {
-    const extension: GarminExtension = {};
-    
-    this.processChildren(ast, extension, {
-      'gpxtpx:hr': (child, target) => target.heartRate = this.parseFloat(child.value),
-      'gpxtpx:cad': (child, target) => target.cadence = this.parseFloat(child.value),
-      'gpxtpx:atemp': (child, target) => target.airTemp = this.parseFloat(child.value),
-    });
-
-    return extension;
+async function mergeMultiFormatTracks(files: { buffer: Buffer, name: string }[]) {
+  const trackSwap = new TrackSwap();
+  const allSportData: SportFileType[] = [];
+  
+  // 🔄 将所有格式转换为统一格式
+  for (const file of files) {
+    try {
+      const sportData = await trackSwap.parseToSport(file.buffer);
+      sportData.metadata = { ...sportData.metadata, originalFile: file.name };
+      allSportData.push(sportData);
+    } catch (error) {
+      console.error(`解析失败: ${file.name}`, error);
+    }
   }
+  
+  // 融合数据逻辑
+  const mergedData = mergeSportData(allSportData);
+  
+  // 输出为不同格式
+  const results = {
+    gpx: await trackSwap.convertSportToGPX(mergedData),
+    fit: await trackSwap.convertSportToFIT(mergedData),
+    tcx: await trackSwap.convertSportToTCX(mergedData)
+  };
+  
+  await trackSwap.destroy();
+  return results;
 }
-
-// 注册到已有解码器
-const decoder = new GPXDecoder();
-await decoder.registerConverter(new GarminExtensionConverter());
 ```
 
-## 🛠️ 管理插件
-
-```typescript
-const decoder = new GPXDecoder();
+## 🏗️ 架构设计
 
-// 查看默认注册的转换器
-console.log('默认转换器:', decoder.listConverters());
-// 输出: ['wpt', 'trkpt', 'rtept', 'rte', 'trk', 'trkseg', 'metadata', 'link', 'author', 'email', 'copyright', 'bounds']
+TrackSwap 采用模块化架构，核心组件包括：
 
-// 注册自定义插件
-await decoder.registerConverter(customConverter);
-await decoder.registerMiddleware(customMiddleware);
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    TrackSwap 架构图                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  🔧 核心处理模块                                             │
+│  ┌─────────────────────────────────────────────────────────┐ │
+│  │ • GPXDecoder/Encoder - GPX 文件处理                     │ │
+│  │ • FITDecoder/Encoder - FIT 文件处理                     │ │
+│  │ • TCXDecoder/Encoder - TCX 文件处理                     │ │
+│  │ • SportProcessor - 统一格式转换处理                      │ │
+│  └─────────────────────────────────────────────────────────┘ │
+│                                                             │
+│  🔄 转换引擎                                                │
+│  ┌─────────────────────────────────────────────────────────┐ │
+│  │ • GPXToSportConverter - GPX → SportFileType            │ │
+│  │ • FITToSportConverter - FIT → SportFileType            │ │
+│  │ • TCXToSportConverter - TCX → SportFileType            │ │
+│  │ • SportToGPXEncoder - SportFileType → GPX              │ │
+│  │ • SportToFITEncoder - SportFileType → FIT              │ │
+│  │ • SportToTCXEncoder - SportFileType → TCX              │ │
+│  └─────────────────────────────────────────────────────────┘ │
+│                                                             │
+│  🎯 统一接口                                                │
+│  ┌─────────────────────────────────────────────────────────┐ │
+│  │ • 自动格式检测                                           │ │
+│  │ • 统一解析方法                                           │ │
+│  │ • 统一转换方法                                           │ │
+│  │ • 生命周期管理                                           │ │
+│  └─────────────────────────────────────────────────────────┘ │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
 
-// 查看所有插件
-console.log('所有转换器:', decoder.listConverters());
-console.log('所有中间件:', decoder.listMiddlewares());
+## 🔍 支持的格式
 
-// 移除插件
-decoder.unregisterConverter('custom-tag');
-decoder.unregisterMiddleware('my-middleware');
+### GPX (GPS Exchange Format)
+- ✅ GPX 1.1 标准
+- ✅ 航路点 (Waypoints)
+- ✅ 路线 (Routes) 
+- ✅ 轨迹 (Tracks)
+- ✅ 元数据 (Metadata)
+- ✅ 扩展属性
 
-// 销毁解码器
-await decoder.destroy();
-```
+### FIT (Flexible and Interoperable Data Transfer)
+- ✅ Activity 文件
+- ✅ Course 文件
+- ✅ 轨迹点数据
+- ✅ 心率、速度、海拔等传感器数据
+- ✅ Garmin 设备兼容
 
-## 🔍 调试和监控
+### TCX (Training Center XML)
+- ✅ 训练数据
+- ✅ 运动轨迹
+- ✅ 心率区间
+- ✅ 圈速数据
+- ✅ Garmin Connect 兼容
 
-新架构提供了丰富的调试和监控能力：
+## 🛠️ 开发指南
 
-- **性能指标**: 自动收集各个阶段的处理时间
-- **错误处理**: 统一的错误处理机制
-- **插件状态**: 跟踪插件的生命周期状态
-- **上下文传递**: 丰富的上下文信息便于调试
-- **开箱即用**: 创建即可工作，无需配置
+### 环境要求
 
-## 📚 API参考
+- Node.js >= 16
+- TypeScript >= 4.5
 
-### GPXDecoder
+### 项目结构
 
-- `constructor()`: 创建解码器，自动注册默认转换器和流水线处理器
-- `registerConverter(plugin: IConverterPlugin)`: 注册自定义转换器
-- `registerMiddleware(plugin: IMiddlewarePlugin)`: 注册中间件
-- `getConverter(tag: string)`: 获取转换器
-- `unregisterConverter(tag: string)`: 移除转换器
-- `unregisterMiddleware(name: string)`: 移除中间件
-- `listConverters()`: 列出所有转换器
-- `listMiddlewares()`: 列出所有中间件
-- `initialize()`: 初始化解码器（自动调用）
-- `destroy()`: 销毁解码器
-- `parserByBuffer(buffer: Buffer)`: 解析GPX数据
+```
+src/
+├── TrackSwap.ts          # 主入口类
+├── GPX/                  # GPX 模块
+│   ├── decoder.ts
+│   ├── encoder.ts
+│   └── types.ts
+├── FIT/                  # FIT 模块
+│   ├── decoder.ts
+│   ├── encoder.ts
+│   └── types.ts
+├── TCX/                  # TCX 模块
+│   ├── decoder.ts
+│   ├── encoder.ts
+│   └── types.ts
+├── sport/                # 统一转换模块
+│   ├── processor.ts
+│   ├── converters.ts
+│   ├── encoders.ts
+│   └── base.ts
+└── types.ts              # 公共类型定义
+```
 
-### BaseConverter
+### 贡献指南
 
-提供转换器的基础实现和工具方法，详见"创建转换器插件"部分。
+1. Fork 项目
+2. 创建特性分支
+3. 提交更改
+4. 发起 Pull Request
 
-### BaseMiddleware
+## 📄 许可证
 
-提供中间件的基础实现，包含所有生命周期钩子的默认实现。
+MIT License
 
-## 🎊 总结
+## 🙏 致谢
 
-现在的GPX解码器真正做到了**开箱即用**：
+感谢所有贡献者和开源社区的支持！
 
-1. **创建即可用**: `new GPXDecoder()` 后立即支持所有标准GPX标签
-2. **按需扩展**: 只需要注册自定义转换器和中间件
-3. **零配置**: 无需了解内部流水线和默认转换器
-4. **完全可控**: 仍然支持完整的插件化定制能力
+---
 
-这个新架构让GPX解码变得更加简洁、易用而又不失灵活性！ 🚀 
+<div align="center">
+  <strong>TrackSwap - 让轨迹数据处理变得简单</strong><br>
+  🚀 高效 • 🔄 统一 • 🛡️ 安全 • 📈 可扩展
+</div>