@ charrater- foundry/ charrater- foundry
通用TypeScript库用于读取,写作,并转换AI字符卡格式.
安装
# Stable release
npm install @character-foundry/character-foundry
# Development release (latest features, may be unstable)
npm install @character-foundry/character-foundry@dev
快速启动
import { parseCard } from '@character-foundry/character-foundry/loader';
import { exportCard } from '@character-foundry/character-foundry/exporter';
// Load any format (PNG, CharX, Voxta, JSON)
const { card, assets, format } = parseCard(buffer);
console.log(card.data.name);
// Export to different format
const pngBuffer = exportCard(card, assets, { format: 'png' });
支持的格式
| 格式 | 读取 | 写入 |
|---|---|---|
| PNG (泰文卡 v2/v3) (英语) | ✅ | ✅ |
| CharX (里苏语) | ✅ | ✅ |
| Voxta (.voxpkg) (英语) | ✅ | ✅ |
| 原始 JSON 语录 | ✅ | ✅ |
| 独立目录 | ✅ | ✅ |
子路径导入
所有功能都可以通过子路径导出:
// Core functionality
import { parseCard } from '@character-foundry/character-foundry/loader';
import { exportCard, checkExportLoss } from '@character-foundry/character-foundry/exporter';
// Schemas and validation
import { CCv3DataSchema, isV3Card, parseV3Card } from '@character-foundry/character-foundry/schemas';
// Format-specific
import { readVoxta, mergeCharacterEdits } from '@character-foundry/character-foundry/voxta';
import { readCharX, writeCharX } from '@character-foundry/character-foundry/charx';
import { readPng, writePng } from '@character-foundry/character-foundry/png';
// Utilities
import { countTokens } from '@character-foundry/character-foundry/tokenizers';
import { ccv2ToCCv3, ccv3ToCCv2Wrapped } from '@character-foundry/character-foundry/normalizer';
import { parseLorebook, serializeLorebook } from '@character-foundry/character-foundry/lorebook';
可用的子路径
| 子路径 | 说明 |
|---|---|
/loader | 带有格式检测的通用剖面卡( ) |
/exporter | 通用导出卡( ) 并检测损失 |
/schemas | CCv2, CCv3, Voxta 类型 + Zod 验证 |
/core | 二等公用事业、ZIP、基地64、安保 |
/png | PNG 块处理、元数据嵌入 |
/charx | CharX 格式, JPEG+ZIP 混合 |
/voxta | 多特征软件包,情景 |
/lorebook | Lorebook 解析和转换 |
/normalizer | V2 → V3 转换 |
/tokenizers | GPT-4/LLAMA 符号计数 |
/media | 图像格式检测, 缩略图 |
/image-utils | 图像 URL 提取、 SSRF 保护 |
/federation | 活动Pub联合会(实验) |
/app-framework | 使用自动格式的 Schema 驱动 UI |
运行时间验证
import { CCv3DataSchema, isV3Card, safeParse } from '@character-foundry/character-foundry/schemas';
// Type guard
if (isV3Card(data)) {
console.log(data.data.name);
}
// Safe parse with error details
const result = safeParse(CCv3DataSchema, data);
if (!result.success) {
console.error(`${result.error} at ${result.field}`);
}
CLI 工具
对于命令行的使用,安装 CLI 包 :
npm install -g @character-foundry/cli
cf detect card.png
cf info card.png
cf export card.png --to charx
文档
许可证
麻省理工学院