@ry-krystal/kicad-converter

v1.0.12

Published

4 months ago

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

0High
0Medium
0Low

ry-krystal

kicad json converter electronics schematic symbol cli tool

KiCad转换器 v2.0

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

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

📋 目录

✨ 核心特性

🔄 双向转换

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

⚡ 高性能处理

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

🛠️ 多种使用方式

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

📦 安装与使用

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

从 npm 安装

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

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

本地构建并全局安装

# 1. 克隆或下载项目
git clone <repository-url>
cd react-demo

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

# 3. 全局链接
npm link

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

方式二：使用 npx（无需安装）

# 直接使用 npx 运行
npx @ry-krystal/kicad-converter --help
npx @ry-krystal/kicad-converter -i input.kicad_sym -o output.json

方式三：本地项目运行

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

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

# 3. 构建项目
npm run build

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

🚀 使用指南

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

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

基本语法

kicad-converter [选项] [参数]

常用命令

# 显示帮助信息
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 |

实际使用示例

# 转换单个文件（自动检测格式）
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 脚本：

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

🎯 使用说明

命令行语法

# 基本语法
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 |

实际使用示例

# 转换项目中的示例文件
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

基础使用（在项目中）

// 导入核心转换功能
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 无法识别"

# 原因：未全局安装或安装失败
# 解决方案1：重新全局安装
npm install -g @ry-krystal/kicad-converter

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

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

Q: 全局安装后仍然无法使用

# 检查全局安装路径
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）

# 使用 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: 本地项目模式下的命令格式

# ❌ 错误：忘记使用 npm run 前缀
kicad-converter input.kicad_sym

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

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

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

Q: 版本兼容性问题

# 检查 Node.js 版本（需要 >= 18.0.0）
node --version

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

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

文件路径问题（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"

📊 性能数据

实际测试结果

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

📦 发布和分发

发布到 npm

# 1. 更新版本号
npm version patch  # 或 minor, major

# 2. 构建项目
npm run build

# 3. 发布到 npm
npm publish

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

用户安装方式

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

# 方式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

离线分发

# 1. 打包项目
npm pack

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

🤝 贡献指南

开发流程

Fork项目仓库
创建功能分支: git checkout -b feature/awesome-feature
修改代码并测试: npm run dev -- --help
构建验证: npm run build
全局链接测试: npm link && kicad-converter --help
提交更改: git commit -m 'Add awesome feature'
推送分支: git push origin feature/awesome-feature
创建Pull Request

开发规范

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

测试清单

开发者在提交前应确保：

[ ] npm run build 成功
[ ] npm run typecheck 无错误
[ ] npm link 后全局命令可用
[ ] kicad-converter --help 显示正确
[ ] 基本转换功能正常
[ ] 更新了相关文档

📄 许可证

本项目采用 MIT许可证

🙏 致谢

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

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

🚀 快速开始测试

全局安装后快速测试

# 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

本地项目测试

# 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：单个文件转换

# 将 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：批量处理库文件

# 将整个符号库目录转换为 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 流程

#!/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：数据迁移和备份

# 创建符号库的 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：开发调试

# 详细模式查看转换过程
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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

KiCad转换器 v2.0

📋 目录

✨ 核心特性

🔄 双向转换

⚡ 高性能处理

🛠️ 多种使用方式

📦 安装与使用

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

从 npm 安装

本地构建并全局安装

方式二：使用 npx（无需安装）

方式三：本地项目运行

🚀 使用指南

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

基本语法

常用命令

命令选项说明

实际使用示例

本地 NPM 脚本使用

📋 可用命令

NPM脚本命令

开发和构建命令

🎯 使用说明

命令行语法

可用参数

实际使用示例

🏗️ 项目架构

目录结构

核心模块

转换引擎 (src/core/)

增强功能 (src/enhanced/)

命令行工具 (src/cli/)

✅ 已验证功能

转换功能测试结果

支持的文件格式

🧪 程序化API

基础使用（在项目中）

增强版转换器

通过脚本使用

🔧 常见问题

安装和使用问题

文件路径问题（Windows）

开发相关

🔧 开发

构建和开发

开发工作流

📊 性能数据

实际测试结果

📦 发布和分发

发布到 npm

用户安装方式

离线分发

🤝 贡献指南

开发流程

开发规范

测试清单

📄 许可证

🙏 致谢

🚀 快速开始测试

全局安装后快速测试

本地项目测试

💡 使用场景示例

场景1：单个文件转换

场景2：批量处理库文件

场景3：集成到 CI/CD 流程

场景4：数据迁移和备份

场景5：开发调试

转换引擎 (`src/core/`)

增强功能 (`src/enhanced/`)

命令行工具 (`src/cli/`)