Package Exports

@ry-krystal/kicad-converter
@ry-krystal/kicad-converter/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ry-krystal/kicad-converter) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

@ry-krystal/kicad-converter

Package Exports

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/`)