KiCad转换器 v2.0

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

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

✨ 核心特性

🔄 双向转换

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

⚡ 高性能处理

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

🛠️ 多种使用方式

• NPM脚本命令: 完整的本地CLI界面
• 程序化API: TypeScript/JavaScript库
• 批量操作: 目录级别的批量转换
• 数据验证: 独立的验证功能

📦 快速开始

本地项目运行

# 1. 进入项目目录
cd /path/to/react-demo

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

# 3. 构建项目
npm run build

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

基本使用示例

# 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 <script-name> -- [参数]

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

可用参数

实际使用示例

# 转换项目中的示例文件
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符号库文件 (.kicad_sym) - 完整支持所有属性
• ✅ JSON格式 (.json) - 结构化数据输出
• ✅ 符号属性 - Reference、Value、Footprint、Datasheet等
• ✅ 引脚信息 - 完整的引脚定义和属性
• ✅ 图形元素 - 矩形、线条、文本等绘图元素
• ✅ 版本兼容 - 支持KiCad 9.x格式

🧪 程序化API

基础使用（在项目中）

// 导入核心转换功能
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
});

增强版转换器

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);
}

通过脚本使用

// 创建转换脚本 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无法识别"

# ❌ 错误：直接使用kicad-converter命令
kicad-converter input.kicad_sym

# ✅ 正确：使用npm脚本
npm run convert -- input.kicad_sym

Q: 帮助信息中的命令格式

# ✅ 现在所有帮助信息都使用正确的npm格式
npm run convert -- --help
# 显示的示例可以直接复制使用

文件路径问题（Windows）

# 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"

开发相关

# 修改代码后需要重新构建
npm run build

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

# 类型检查
npm run typecheck

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

🔧 开发

构建和开发

# 开发模式（直接运行TypeScript）
npm run dev -- --help

# 构建项目
npm run build

# 类型检查
npm run typecheck

# 清理构建文件
npm run clean

开发工作流

# 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"

📊 性能数据

实际测试结果

🤝 贡献指南

1. Fork项目仓库
2. 创建功能分支: git checkout -b feature/awesome-feature
3. 修改代码并测试: npm run dev -- --help
4. 构建验证: npm run build
5. 提交更改: git commit -m 'Add awesome feature'
6. 推送分支: git push origin feature/awesome-feature
7. 创建Pull Request

开发规范

• 使用TypeScript严格模式
• 修改后运行 npm run typecheck
• 确保所有npm脚本正常工作
• 更新相关文档

📄 许可证

本项目采用 MIT许可证

🙏 致谢

• KiCad - 开源电子设计自动化套件
• TypeScript - 类型安全的JavaScript
• Node.js - JavaScript运行时环境

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

🚀 快速测试

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

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

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