添加新作品指南

📖 目录

1. 对于非程序员
2. 基本流程
3. 数据结构详解
4. 目录结构
5. 数据文件格式
6. 示例
7. 数据准备工具
8. 常见问题
9. 总结

👥 对于非程序员

如果你不熟悉 Git、GitHub 或编程，但希望为 Sparkle 添加新的文学作品数据，你可以通过以下方式：

你可以提供的数据形式

• 小说人物列表（Excel、Word 或文本文件）
• 人物关系图（手绘、思维导图或任何图表）
• 人物关系描述（自然语言描述）
• 小说章节分析

📋 基本流程

1. 创建书籍目录：在 data/ 目录下创建新的书籍目录
2. 创建版本索引：在书籍目录下创建 index-zh.js 文件
3. 创建人物数据：在书籍目录下创建版本数据文件（如 default.js）
4. 更新作者索引：在 data/index-zh.js 中添加或更新作者和作品信息
5. 测试验证：在本地运行项目，验证数据是否正确加载
6. 提交贡献：通过 Pull Request 提交你的贡献

🏗️ 数据结构详解

Sparkle 使用三层数据结构来组织作品数据：

📁 目录结构

data/
├── index-zh.js                    # 作者和作品索引
└── [book-id]/                     # 书籍目录（使用唯一ID）
    ├── index-zh.js                # 版本索引
    └── [version].js               # 人物关系数据（如 default.js）

命名规范

• book-id：书籍唯一标识符，建议使用时间戳格式（如 202603262212）
• version：版本标识符，如 default、version1 等

📄 数据文件格式

1. 作者索引文件格式 (data/index-zh.js)

export default [
  {
    id: "202603262231",                    // 作者唯一ID
    name: "费奥多尔·米哈伊洛维奇·陀思妥耶夫斯基", // 作者姓名
    biography: "1821年11月11日—1881年2月9日", // 作者生平
    description: "到后来，他竟作为罪孽深重的罪人，同时也是残酷的拷问官而出现了...", // 作者介绍
    books: [                               // 作品列表
      {
        id: "202603262212",                // 作品唯一ID
        name: "卡拉马佐夫兄弟",             // 作品名称
      },
      {
        id: "202603262213",
        name: "群魔",
      }
    ]
  }
];

2. 版本索引文件格式 (data/[book-id]/index-zh.js)

export default [
  {
    version: "default",                    // 版本标识符
    name: "荣如德-上海译文-2012",           // 版本显示名称
    description: "不错~不错~",              // 版本描述（可选）
  }
  // 可以添加更多版本
];

3. 人物关系数据格式 (data/[book-id]/[version].js)

export default [
  // 节点（人物）
  {
    data: {
      id: "a1",                            // 人物唯一ID
      name: "费奥多尔·巴甫洛维奇·卡拉马佐夫", // 人物姓名
      gender: "男",                         // 性别（男/女）
      nickname: ["老卡拉马佐夫"],           // 别名列表（可选）
      // 其他自定义字段...
    }
  },

  // 边（关系）
  {
    data: {
      id: "e1",                            // 关系唯一ID
      source: "a1",                        // 源节点ID
      target: "a2",                        // 目标节点ID
      name: "父子关系",                     // 关系描述
      // 其他自定义字段...
    }
  }
];

📚 示例：为《红楼梦》添加数据

data/
└── 202501010001/          # 《红楼梦》目录

export default [
  {
    version: "default",
    name: "人民文学出版社-2008",
    description: "经典版本",
  }
];

export default [
  // 人物节点
  {
    data: {
      id: "h1",
      name: "贾宝玉",
      gender: "男",
      nickname: ["宝玉", "怡红公子"],
    }
  },
  // ... 更多人物
];

export default [
  // 原有作者...
  {
    id: "202501010000",
    name: "曹雪芹",
    biography: "约1715年—约1763年",
    description: "清代小说家，《红楼梦》的作者...",
    books: [
      {
        id: "202501010001",
        name: "红楼梦",
      }
    ]
  }
];

🛠️ 数据准备工具

手动准备

对于小型作品，可以直接编辑 JSON 文件创建数据。

推荐工具

• 表格工具：使用 Excel 或 Google Sheets 整理数据后导出为 JSON
• 可视化工具：使用 draw.io 或 Lucidchart 绘制关系图后提取数据
• 脚本工具：使用 Python 或 JavaScript 脚本处理现有数据

数据转换示例（Python）

import json

# 示例：从CSV转换
characters = [
    {"id": "c1", "name": "张三", "gender": "男"},
    {"id": "c2", "name": "李四", "gender": "女"}
]

relationships = [
    {"id": "r1", "source": "c1", "target": "c2", "name": "夫妻"}
]

# 组合数据
elements = []
for char in characters:
    elements.append({"data": char})
for rel in relationships:
    elements.append({"data": rel})

# 保存为JS文件
with open("default.js", "w", encoding="utf-8") as f:
    f.write("export default ")
    json.dump(elements, f, ensure_ascii=False, indent=2)

❓ 常见问题

{
  data: {
    id: "c1",
    name: "角色名",
    custom_field: "自定义值",  // 自定义字段
    age: 25,                   // 自定义字段
    role: "主角"               // 自定义字段
  }
}

✨ 总结

贡献方式对比

核心要点

• 标签必加：无论通过哪个平台提需求，都请加上 book-wanted 标签
• 信息完整：提供尽可能完整和准确的作品信息
• 平台区分：GitHub 用于代码贡献，Gitee 仅用于国内用户提需求
• 社区互助：相信社区的力量，你的需求可能会被其他热心用户实现

愿景

我们希望 Sparkle 成为一个真正社区驱动的项目，让每个人都能参与进来：

• 程序员可以通过技术贡献实现数据
• 文学爱好者可以通过提需求和提供信息参与
• 研究者可以分享他们的分析成果
• 读者可以享受更丰富的文学作品可视化

无论你是谁，都能为 Sparkle 的璀璨星空增添一颗星星！ ✨