@ry-krystal/kicad-converter/README.md

专业的KiCad符号文件与JSON互转工具

# KiCad转换器 v2.0

🚀 **专业的KiCad符号文件与JSON互转工具**

一个功能完整、高性能的数据转换工具，支持KiCad符号库文件(.kicad_sym)与JSON格式之间的双向转换。

## 📋 目录

- [核心特性](#-核心特性)
- [安装与使用](#-安装与使用)
  - [全局安装（推荐）](#方式一全局安装推荐)
  - [使用 npx](#方式二使用-npx无需安装)  
  - [本地项目运行](#方式三本地项目运行)
- [使用指南](#-使用指南)
  - [全局命令行使用](#全局命令行使用推荐方式)
  - [本地 NPM 脚本使用](#本地-npm-脚本使用)
- [使用场景示例](#-使用场景示例)
- [项目架构](#-项目架构)
- [程序化API](#-程序化api)
- [常见问题](#-常见问题)
- [性能数据](#-性能数据)
- [发布和分发](#-发布和分发)
- [贡献指南](#-贡献指南)

## ✨ 核心特性

### 🔄 双向转换
- **KiCad → JSON**: 将KiCad符号文件转换为结构化JSON
- **JSON → KiCad**: 将JSON数据转换回KiCad符号文件
- **完整保真**: 支持所有KiCad符号格式特性
- **数据验证**: 内置完整性检查和错误修复

### ⚡ 高性能处理
- **双引擎架构**: 核心版(稳定)+ 增强版(高性能)
- **批量处理**: 支持目录递归转换
- **流式处理**: 处理大型符号库文件
- **智能缓存**: 提升重复操作性能

### 🛠️ 多种使用方式
- **NPM脚本命令**: 完整的本地CLI界面
- **程序化API**: TypeScript/JavaScript库
- **批量操作**: 目录级别的批量转换
- **数据验证**: 独立的验证功能

## 📦 安装与使用

### 方式一：全局安装（推荐）

#### 从 npm 安装
```bash
# 全局安装
npm install -g @ry-krystal/kicad-converter

# 在任意位置使用
kicad-converter --help
```

#### 本地构建并全局安装
```bash
# 1. 克隆或下载项目
git clone <repository-url>
cd react-demo

# 2. 安装依赖并构建
npm install
npm run build

# 3. 全局链接
npm link

# 4. 验证安装
kicad-converter --help
```

### 方式二：使用 npx（无需安装）
```bash
# 直接使用 npx 运行
npx @ry-krystal/kicad-converter --help
npx @ry-krystal/kicad-converter -i input.kicad_sym -o output.json
```

### 方式三：本地项目运行
```bash
# 1. 进入项目目录
cd /path/to/react-demo

# 2. 安装依赖（如果还没安装）
npm install

# 3. 构建项目
npm run build

# 4. 验证所有功能
npm run convert -- --help
```

## 🚀 使用指南

### 全局命令行使用（推荐方式）

安装后，可以在任意位置使用 `kicad-converter` 命令：

#### 基本语法
```bash
kicad-converter [选项] [参数]
```

#### 常用命令
```bash
# 显示帮助信息
kicad-converter --help

# 显示版本信息
kicad-converter --version

# KiCad 转 JSON
kicad-converter -i input.kicad_sym -o output.json -m to-json

# JSON 转 KiCad
kicad-converter -i input.json -o output.kicad_sym -m to-kicad

# 自动检测格式转换
kicad-converter -i input.kicad_sym -o output.json

# 批量处理目录
kicad-converter --batch -i ./symbols/ -o ./converted/

# 递归处理子目录
kicad-converter --batch --recursive -i ./input/ -o ./output/

# 验证文件格式
kicad-converter --validate -i input.kicad_sym

# 显示文件统计信息
kicad-converter --stats -i input.kicad_sym

# 使用增强引擎
kicad-converter -e enhanced -i input.kicad_sym -o output.json

# 详细输出模式
kicad-converter --verbose -i input.kicad_sym -o output.json

# 静默模式
kicad-converter --quiet -i input.kicad_sym -o output.json
```

#### 命令选项说明
| 选项 | 简写 | 说明 | 示例 |
|------|------|------|------|
| `--input` | `-i` | 输入文件路径 | `-i input.kicad_sym` |
| `--output` | `-o` | 输出文件路径 | `-o output.json` |
| `--mode` | `-m` | 转换模式 | `-m to-json` 或 `-m to-kicad` |
| `--engine` | `-e` | 转换引擎 | `-e enhanced` 或 `-e core` |
| `--batch` | `-b` | 批量处理模式 | `--batch` |
| `--recursive` | `-r` | 递归处理子目录 | `--recursive` |
| `--validate` | - | 启用数据验证 | `--validate` |
| `--optimize` | - | 启用输出优化 | `--optimize` |
| `--stats` | - | 显示详细统计 | `--stats` |
| `--verbose` | `-v` | 详细输出模式 | `--verbose` |
| `--quiet` | `-q` | 静默模式 | `--quiet` |
| `--help` | `-h` | 显示帮助信息 | `--help` |
| `--version` | - | 显示版本信息 | `--version` |

#### 实际使用示例
```bash
# 转换单个文件（自动检测格式）
kicad-converter -i amplifier.kicad_sym -o amplifier.json

# 指定转换模式和引擎
kicad-converter -i amplifier.kicad_sym -o amplifier.json -m to-json -e enhanced

# 批量转换整个目录
kicad-converter --batch -i ./kicad-symbols/ -o ./json-output/

# 验证文件并显示统计信息
kicad-converter --validate --stats -i amplifier.kicad_sym

# 静默模式批量转换（适合脚本使用）
kicad-converter --quiet --batch -i ./input/ -o ./output/

# 详细模式转换（查看处理过程）
kicad-converter --verbose -i amplifier.kicad_sym -o amplifier.json
```

### 本地 NPM 脚本使用

如果在项目目录内运行，也可以使用 npm 脚本：

```bash
# KiCad文件转JSON
npm run kicad-to-json -- input.kicad_sym output.json

# JSON文件转KiCad
npm run json-to-kicad -- input.json output.kicad_sym

# 自动检测格式转换
npm run convert -- input.kicad_sym

# 查看帮助
npm run convert -- --help
```

## 📋 可用命令

### NPM脚本命令
| 脚本命令 | 功能说明 | 示例用法 | 状态 |
|----------|----------|----------|------|
| `npm run convert` | 通用转换命令，自动检测文件格式 | `npm run convert -- input.kicad_sym output.json` | ✅ |
| `npm run kicad-to-json` | KiCad文件转JSON格式 | `npm run kicad-to-json -- input.kicad_sym output.json` | ✅ |
| `npm run json-to-kicad` | JSON文件转KiCad格式 | `npm run json-to-kicad -- input.json output.kicad_sym` | ✅ |
| `npm run batch` | 批量处理多个文件 | `npm run batch -- ./input_dir/ ./output_dir/` | ✅ |
| `npm run validate` | 验证文件格式和数据完整性 | `npm run validate -- input.kicad_sym` | ✅ |
| `npm run stats` | 显示文件统计信息 | `npm run stats -- input.kicad_sym` | ✅ |
| `npm run demo` | 运行功能演示 | `npm run demo` | ✅ |
| `npm run benchmark` | 性能基准测试 | `npm run benchmark` | ✅ |

### 开发和构建命令
| 脚本命令 | 功能说明 | 示例用法 | 状态 |
|----------|----------|----------|------|
| `npm run dev` | 开发模式运行 | `npm run dev -- --help` | ✅ |
| `npm run build` | 构建项目 | `npm run build` | ✅ |
| `npm run typecheck` | TypeScript类型检查 | `npm run typecheck` | ✅ |
| `npm run clean` | 清理构建文件 | `npm run clean` | ✅ |

## 🎯 使用说明

### 命令行语法
```bash
# 基本语法
npm run <script-name> -- [参数]

# 重要：-- 是必需的！
npm run convert --help          # ❌ 显示npm的帮助
npm run convert -- --help       # ✅ 显示转换器的帮助
```

### 可用参数
| 参数 | 说明 | 完整示例 |
|------|------|----------|
| `--mode` | 转换模式：`to-json` 或 `to-kicad` | `npm run convert -- --mode to-json input.kicad_sym` |
| `--engine` | 转换引擎：`core` 或 `enhanced` | `npm run convert -- --engine enhanced input.kicad_sym` |
| `--validate` | 启用数据验证 | `npm run convert -- --validate input.kicad_sym` |
| `--optimize` | 启用输出优化 | `npm run convert -- --optimize input.kicad_sym` |
| `--stats` | 显示详细统计 | `npm run convert -- --stats input.kicad_sym` |
| `--verbose` | 详细输出模式 | `npm run convert -- --verbose input.kicad_sym` |
| `--quiet` | 静默模式 | `npm run convert -- --quiet input.kicad_sym` |
| `--help` | 显示帮助信息 | `npm run convert -- --help` |

### 实际使用示例
```bash
# 转换项目中的示例文件
npm run kicad-to-json -- "Amplifier_Audio_output.kicad_sym" "output.json"

# 反向转换验证
npm run json-to-kicad -- "output.json" "converted_back.kicad_sym"

# 使用增强版引擎并显示统计
npm run convert -- --engine enhanced --stats "Amplifier_Audio_output.kicad_sym"

# 批量处理目录
npm run batch -- ./symbols/ ./output/

# 验证文件格式
npm run validate -- "Amplifier_Audio_output.kicad_sym"
```

## 🏗️ 项目架构

### 目录结构
```
react-demo/
├── src/
│   ├── core/           # 核心转换引擎
│   │   ├── parser.ts   # KiCad S表达式解析器
│   │   ├── converter.ts # JSON转换器
│   │   ├── generator.ts # KiCad文件生成器
│   │   ├── validator.ts # 数据验证器
│   │   └── index.ts    # 核心模块导出
│   ├── enhanced/       # 增强版转换器
│   │   ├── converter.ts # 高性能转换器
│   │   └── index.ts    # 增强模块导出
│   ├── cli/            # 命令行工具
│   │   ├── main.ts     # CLI主入口
│   │   ├── commands/   # 具体命令实现
│   │   │   ├── convert.ts   # 转换命令
│   │   │   ├── batch.ts     # 批量处理命令
│   │   │   └── validate.ts  # 验证命令
│   │   └── utils/      # CLI工具函数
│   ├── utils/          # 通用工具
│   └── index.ts        # 主入口
├── examples/           # 使用示例
│   └── demo.ts         # 功能演示脚本
├── tests/              # 测试文件
├── package.json        # 项目配置和脚本
├── tsconfig.json      # TypeScript配置
└── README.md          # 项目文档
```

### 核心模块

#### 转换引擎 (`src/core/`)
- **parser.ts**: KiCad S表达式解析器，处理.kicad_sym文件格式
- **converter.ts**: 双向转换核心逻辑，提供convertKiCadToJson、convertJsonToKicad
- **generator.ts**: KiCad文件生成器，输出标准格式
- **validator.ts**: 数据验证器，确保转换质量
- **index.ts**: 导出所有核心API

#### 增强功能 (`src/enhanced/`)
- **converter.ts**: 高性能转换器，优化大文件处理
- **EnhancedConverter类**: 提供额外的性能优化和错误恢复

#### 命令行工具 (`src/cli/`)
- **main.ts**: CLI入口，参数解析和命令分发
- **commands/**: 各种具体命令的实现逻辑

## ✅ 已验证功能

### 转换功能测试结果
| 功能 | 状态 | 测试文件 | 性能 |
|------|------|----------|------|
| KiCad → JSON | ✅ 通过 | `Amplifier_Audio_output.kicad_sym` | 0.02-0.03秒 |
| JSON → KiCad | ✅ 通过 | 反向转换 | 0.01秒 |
| 双向转换完整性 | ✅ 通过 | 往返转换验证 | 数据无损失 |
| 自动格式检测 | ✅ 通过 | 多种文件格式 | 100%准确 |
| 批量处理 | ✅ 通过 | 目录处理 | 支持递归 |
| 数据验证 | ✅ 通过 | 格式验证 | 错误检测准确 |

### 支持的文件格式
- ✅ **KiCad符号库文件** (`.kicad_sym`) - 完整支持所有属性
- ✅ **JSON格式** (`.json`) - 结构化数据输出
- ✅ **符号属性** - Reference、Value、Footprint、Datasheet等
- ✅ **引脚信息** - 完整的引脚定义和属性
- ✅ **图形元素** - 矩形、线条、文本等绘图元素
- ✅ **版本兼容** - 支持KiCad 9.x格式

## 🧪 程序化API

### 基础使用（在项目中）
```typescript
// 导入核心转换功能
import { convertKiCadToJson, convertJsonToKicad } from './src/core';
import { EnhancedConverter } from './src/enhanced';
import { readFileSync } from 'fs';

// 基本转换示例
const kicadContent = readFileSync('input.kicad_sym', 'utf8');
const jsonResult = await convertKiCadToJson(kicadContent, {
  validateOutput: true,
  optimizeOutput: true
});

if (jsonResult.success) {
  console.log('转换成功!', jsonResult.data);
  console.log('统计信息:', jsonResult.statistics);
}

// 反向转换
const jsonContent = JSON.stringify(jsonResult.data);
const kicadResult = await convertJsonToKicad(jsonContent, {
  validateOutput: true
});
```

### 增强版转换器
```typescript
import { EnhancedConverter } from './src/enhanced';

const converter = new EnhancedConverter({
  validateOutput: true,
  optimizeOutput: true,
  verbose: false
});

const result = await converter.kicadToJson(kicadContent);
if (result.success) {
  console.log('增强版转换完成:', result.statistics);
}
```

### 通过脚本使用
```javascript
// 创建转换脚本 convert-script.js
const { execSync } = require('child_process');

// 使用npm脚本进行转换
execSync('npm run kicad-to-json -- input.kicad_sym output.json', {
  stdio: 'inherit'
});

console.log('转换完成!');
```

## 🔧 常见问题

### 安装和使用问题

**Q: 提示"kicad-converter 无法识别"**
```bash
# 原因：未全局安装或安装失败
# 解决方案1：重新全局安装
npm install -g @ry-krystal/kicad-converter

# 解决方案2：使用 npx（无需安装）
npx @ry-krystal/kicad-converter --help

# 解决方案3：本地链接（开发模式）
cd /path/to/project && npm link
```

**Q: 全局安装后仍然无法使用**
```bash
# 检查全局安装路径
npm list -g --depth=0

# 检查 PATH 环境变量包含 npm 全局目录
npm config get prefix

# Windows 上确保以下路径在 PATH 中：
# %APPDATA%\npm (通常是 C:\Users\用户名\AppData\Roaming\npm)

# macOS/Linux 确保以下路径在 PATH 中：
# /usr/local/bin 或者 npm config get prefix 显示的路径
```

**Q: 权限问题（macOS/Linux）**
```bash
# 使用 sudo 安装（不推荐）
sudo npm install -g @ry-krystal/kicad-converter

# 更好的方案：配置 npm 全局路径
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @ry-krystal/kicad-converter
```

**Q: 本地项目模式下的命令格式**
```bash
# ❌ 错误：忘记使用 npm run 前缀
kicad-converter input.kicad_sym

# ✅ 正确：在项目目录内使用 npm 脚本
npm run convert -- input.kicad_sym

# ❌ 错误：忘记 -- 分隔符
npm run convert --help

# ✅ 正确：使用 -- 分隔 npm 参数和工具参数
npm run convert -- --help
```

**Q: 版本兼容性问题**
```bash
# 检查 Node.js 版本（需要 >= 18.0.0）
node --version

# 检查工具版本
kicad-converter --version

# 如果 Node.js 版本过低，请升级：
# Windows: 从 https://nodejs.org/ 下载安装
# macOS: brew install node
# Linux: 使用包管理器或 nvm
```

### 文件路径问题（Windows）
```bash
# Windows路径处理
npm run kicad-to-json -- "d:\path with spaces\file.kicad_sym" "output.json"

# 或使用正斜杠
npm run kicad-to-json -- "d:/path/file.kicad_sym" "output.json"
```

### 开发相关
```bash
# 修改代码后需要重新构建
npm run build

# 或使用开发模式直接运行
npm run dev -- --help

# 类型检查
npm run typecheck

# 清理重建
npm run clean && npm run build
```

## 🔧 开发

### 构建和开发
```bash
# 开发模式（直接运行TypeScript）
npm run dev -- --help

# 构建项目
npm run build

# 类型检查
npm run typecheck

# 清理构建文件
npm run clean
```

### 开发工作流
```bash
# 1. 修改代码后测试功能
npm run dev -- input.kicad_sym output.json

# 2. 构建验证
npm run build

# 3. 运行完整测试
npm run demo
npm run benchmark

# 4. 验证特定功能
npm run convert -- --stats "test_file.kicad_sym"
```

## 📊 性能数据

### 实际测试结果
| 操作 | 测试文件 | 文件大小 | 处理时间 | 状态 |
|------|----------|----------|----------|------|
| KiCad解析 | `Amplifier_Audio_output.kicad_sym` | ~50KB | 0.02-0.03秒 | ✅ |
| JSON生成 | 转换后的JSON | ~45KB | 同上 | ✅ |
| KiCad生成 | 反向转换 | ~50KB | 0.01秒 | ✅ |
| 数据验证 | 完整性检查 | - | <0.01秒 | ✅ |

## 📦 发布和分发

### 发布到 npm
```bash
# 1. 更新版本号
npm version patch  # 或 minor, major

# 2. 构建项目
npm run build

# 3. 发布到 npm
npm publish

# 4. 验证发布
npm view @ry-krystal/kicad-converter
```

### 用户安装方式
发布后，用户可以通过以下方式使用：

```bash
# 方式1：全局安装
npm install -g @ry-krystal/kicad-converter
kicad-converter --help

# 方式2：npx 使用（推荐给临时用户）
npx @ry-krystal/kicad-converter --help

# 方式3：项目依赖
npm install @ry-krystal/kicad-converter
npx kicad-converter --help
```

### 离线分发
```bash
# 1. 打包项目
npm pack

# 2. 生成 .tgz 文件，可以离线安装
npm install -g ry-krystal-kicad-converter-1.0.6.tgz
```

## 🤝 贡献指南

### 开发流程
1. Fork项目仓库
2. 创建功能分支: `git checkout -b feature/awesome-feature`
3. 修改代码并测试: `npm run dev -- --help`
4. 构建验证: `npm run build`
5. 全局链接测试: `npm link && kicad-converter --help`
6. 提交更改: `git commit -m 'Add awesome feature'`
7. 推送分支: `git push origin feature/awesome-feature`
8. 创建Pull Request

### 开发规范
- 使用TypeScript严格模式
- 修改后运行 `npm run typecheck`
- 确保所有npm脚本正常工作
- 测试全局命令行功能
- 更新相关文档和示例

### 测试清单
开发者在提交前应确保：
- [ ] `npm run build` 成功
- [ ] `npm run typecheck` 无错误
- [ ] `npm link` 后全局命令可用
- [ ] `kicad-converter --help` 显示正确
- [ ] 基本转换功能正常
- [ ] 更新了相关文档

## 📄 许可证

本项目采用 [MIT许可证](LICENSE)

## 🙏 致谢

- [KiCad](https://www.kicad.org/) - 开源电子设计自动化套件
- [TypeScript](https://www.typescriptlang.org/) - 类型安全的JavaScript
- [Node.js](https://nodejs.org/) - JavaScript运行时环境

---

**⭐ 如果这个项目对您有帮助，请给我们一个星标！**

## 🚀 快速开始测试

### 全局安装后快速测试
```bash
# 1. 验证安装
kicad-converter --version
kicad-converter --help

# 2. 下载示例文件或使用项目中的示例
# 如果有现成的 .kicad_sym 文件，直接使用
# 或者从项目中获取示例文件

# 3. 转换测试
kicad-converter -i your-symbol.kicad_sym -o output.json -v
kicad-converter -i output.json -o converted-back.kicad_sym -v

# 4. 验证转换结果
kicad-converter --validate -i your-symbol.kicad_sym
kicad-converter --stats -i your-symbol.kicad_sym
```

### 本地项目测试
```bash
# 1. 克隆项目并设置
git clone <repository-url>
cd react-demo
npm install
npm run build

# 2. 一键验证所有功能
npm run demo

# 3. 转换示例文件
npm run kicad-to-json -- "Amplifier_Audio_output.kicad_sym" "test.json"
npm run json-to-kicad -- "test.json" "test.kicad_sym"

# 4. 查看详细帮助
npm run convert -- --help
```

## 💡 使用场景示例

### 场景1：单个文件转换
```bash
# 将 KiCad 符号转换为 JSON 进行数据分析
kicad-converter -i library/74xx.kicad_sym -o data/74xx.json --stats

# 修改 JSON 数据后转换回 KiCad 格式
kicad-converter -i data/modified-74xx.json -o library/new-74xx.kicad_sym --validate
```

### 场景2：批量处理库文件
```bash
# 将整个符号库目录转换为 JSON 格式
kicad-converter --batch --recursive -i ./kicad-libraries/ -o ./json-backup/

# 从 JSON 备份还原符号库
kicad-converter --batch --recursive -i ./json-backup/ -o ./restored-libraries/
```

### 场景3：集成到 CI/CD 流程
```bash
#!/bin/bash
# build-script.sh

# 验证所有符号文件
for file in symbols/*.kicad_sym; do
    echo "验证文件: $file"
    kicad-converter --validate --quiet "$file" || exit 1
done

# 生成 JSON 格式的符号数据库
kicad-converter --batch --quiet -i symbols/ -o json-database/

echo "符号验证和转换完成"
```

### 场景4：数据迁移和备份
```bash
# 创建符号库的 JSON 备份
mkdir backup-$(date +%Y%m%d)
kicad-converter --batch -i ./symbols/ -o ./backup-$(date +%Y%m%d)/ --verbose

# 从备份恢复
kicad-converter --batch -i ./backup-20241201/ -o ./restored-symbols/
```

### 场景5：开发调试
```bash
# 详细模式查看转换过程
kicad-converter --verbose --stats -i problematic-symbol.kicad_sym -o debug.json

# 验证模式检查文件完整性
kicad-converter --validate -i symbol.kicad_sym

# 使用增强引擎处理复杂文件
kicad-converter -e enhanced --optimize -i complex-symbol.kicad_sym -o optimized.json
```