OrionSeeker/StoryRibbons

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

StoryRibbons/README.md

星觅

Initial commit

963bdba8

PreviewCode viewBlame

Story Ribbons 本地化开发环境

本项目基于开源项目 Story Ribbons 进行二次开发和本地化部署，提供完整的中文开发环境和使用说明。

项目简介

Story Ribbons 是一个基于大语言模型（LLM）的交互式故事线可视化系统。通过 LLM 驱动的数据解析管道，自动从小说和剧本中提取相关信息，帮助文学分析师在多个叙事层面探索详细的角色和主题轨迹。

原始项目信息

论文: Story Ribbons: Reimagining Storyline Visualizations with Large Language Models
演示: Story Ribbons Demo
文档: Story Ribbons Docs
原始仓库: GitHub - catherinesyeh/story-viz

二次开发说明

本项目在原始 Story Ribbons 代码基础上进行了本地化配置和开发环境优化，主要包括：

云原生开发环境配置（Docker + CNB 平台）
中文使用文档和快速开始指南
开发工具和编辑器配置优化
国内网络环境优化（镜像源配置）

技术栈

前端技术栈

框架: React 18 + TypeScript
构建工具: Vite 5
UI 组件库: Mantine 7
数据可视化: D3.js + Chroma.js
状态管理: Zustand
样式: Sass

后端技术栈

语言: Python 3.12
框架: Flask
包管理: Pipenv
AI 集成: OpenAI API

开发工具

容器化: Docker
云原生: CNB (Cloud Native Build)
代码编辑: code-server（VS Code 浏览器版）

目录结构


/workspace/
├── .cnb.yml              # 云原生构建配置文件
├── Dockerfile            # Docker 镜像构建配置
├── settings.json         # VS Code 编辑器配置
├── README.md            # 本文档
└── story-viz/           # Story Ribbons 核心源代码
    ├── src/              # 前端 React 源代码
    │   ├── components/   # React 组件
    │   ├── data/        # 数据文件（JSON 格式）
    │   ├── stores/      # Zustand 状态管理
    │   ├── utils/       # 工具函数
    │   └── App.tsx      # 主应用组件
    ├── backend/         # 后端 Python 服务
    │   ├── server.py    # Flask 服务器
    │   ├── prompts.py   # LLM 提示词模板
    │   └── helpers.py   # 辅助函数
    ├── public/          # 静态资源
    │   ├── chapters/    # 小说章节文本文件
    │   ├── characters/  # 角色图片资源
    │   └── covers/     # 书籍封面图片
    ├── notebooks/       # Jupyter 数据解析笔记本
    │   ├── parsing-data.ipynb  # 主要数据解析流程
    │   ├── scripts/     # 原始故事文本文件
    │   ├── chapters/    # 解析后的章节文件
    │   └── json/       # 中间数据文件
    ├── package.json     # 前端依赖配置
    └── Pipfile         # Python 依赖配置

环境要求

系统要求

操作系统: Linux / macOS / Windows（支持 Docker）
内存: 建议 4GB 及以上
磁盘空间: 建议 10GB 及以上

软件要求

Node.js: 22.x 或更高版本
Python: 3.12 或更高版本（Ubuntu 24.04 内置）
Pipenv: Python 虚拟环境管理工具
Yarn: npm 包管理工具
Docker（可选，用于容器化部署）

快速开始

方式一：本地开发环境

1. 配置 API 密钥

后端服务需要 OpenAI API 密钥来进行文本分析和数据解析。


# 复制示例配置文件
cp story-viz/secrets_example.json story-viz/secrets.json

# 使用编辑器打开配置文件
nano story-viz/secrets.json

配置文件格式：


{
    "openai_key": "your-openai-api-key-here"
}

注意：请妥善保管你的 API 密钥，不要将 secrets.json 文件提交到代码仓库（已在 .gitignore 中排除）。

2. 安装前端依赖

首次运行前需要安装前端依赖包：


cd story-viz
yarn install

安装过程可能需要几分钟时间，取决于网络速度。

3. 启动前端服务

在 story-viz 目录下运行：


yarn dev

前端服务将在 http://localhost:5200 启动。

在浏览器中访问该地址即可看到 Story Ribbons 的用户界面。

4. 启动后端服务

打开新的终端窗口（保持前端服务运行）：


cd story-viz

# 首次运行需要安装 Python 依赖（会创建 .venv 虚拟环境）
pipenv install --python 3.12

# 激活 Python 虚拟环境
pipenv shell

# 启动后端服务器
python backend/server.py

后端服务将在 http://127.0.0.1:5000 启动。

现在两个服务都已启动，可以开始使用 Story Ribbons 进行故事可视化了。

方式二：云原生开发环境

使用 Docker 容器进行开发，确保环境一致性。

1. 构建 Docker 镜像


docker build -t story-ribbons-cn:latest .

2. 启动容器


docker run -it -p 5200:5200 -p 5000:5000 -v $(pwd):/workspace story-ribbons-cn:latest /bin/bash

3. 在容器内启动服务

按照"方式一"中的步骤在容器内配置并启动服务。

方式三：CNB 平台部署

使用 CNB（Cloud Native Build）平台进行自动化构建和部署。

项目已配置 .cnb.yml 文件，支持一键构建和部署到 CNB 平台。

详细操作请参考 CNB 平台文档。

项目构建

开发模式

开发模式支持热重载，适合日常开发调试。


cd story-viz
yarn dev

访问 http://localhost:5200 查看开发版本。

生产构建

生产构建会进行代码压缩和优化，生成可直接部署的静态文件。


cd story-viz
yarn build

构建产物将生成在 dist/ 目录中。

预览生产构建

在本地预览生产构建的结果：


cd story-viz
yarn build
yarn preview

添加新故事

要添加新的文学作品到可视化系统，请按照以下步骤操作：

详细步骤

第一步：准备故事文本

打开数据处理笔记本

打开 story-viz/notebooks/parsing-data.ipynb，运行到 setup 部分的末尾。
确保必要的文件夹存在

确认 notebooks/ 文件夹下已创建以下子文件夹：
- notebooks/scripts/ - 存放原始故事文本
- notebooks/chapters/ - 存放解析后的章节
- notebooks/json/ - 存放中间数据
添加故事文本文件

将故事文本文件（仅支持 .txt 格式）添加到 notebooks/scripts/ 文件夹中。

命名建议：使用简短但具代表性的名称，例如《了不起的盖茨比》命名为 "gatsby.txt"。

第二步：配置分析参数

在 parsing-data.ipynb 的 split text into chapters 部分的第一个单元格中，设置以下参数：


og_story_name = "gatsby"  # 你的故事名称（不含 .txt）
story_name = og_story_name
analysis_type = "character"  # "character" 或 "theme"

分析类型说明：

character: 分析角色关系和轨迹
theme: 分析主题演变

建议先尝试 character 分析类型。

第三步：分割文本为章节

运行此部分的代码，直到 analyze scene 之前停止。

检查生成的章节文本文件，位置：notebooks/chapters/你的故事名/（如 notebooks/chapters/gatsby/）。

重要提示：这是整个流程中唯一可能需要手动干预的步骤。

如果遇到问题：

可能需要手动调整 notebooks/json/ 文件夹中生成的 summary.json 文件
调整内容：首行、末行和章节标记
修改后，重新运行此代码块，直到章节文本文件看起来正确

第四步：分析场景和生成数据

从 analyze scene 部分开始运行笔记本的其余代码。

这部分应该运行顺畅，笔记本按语义分段，有助于调试。

第五步：获取最终数据文件

在笔记本的最后，运行 generating the final json file 部分后，你应该能在 notebooks/json/你的故事名/ 文件夹中看到 final_data.json 文件。

第六步：复制数据到前端

检查 src/data/ 文件夹，你应该看到对应的 JSON 文件：

角色分析：文件命名为 你的故事名-new.json（如 "gatsby-new.json"）
主题分析：文件命名为 你的故事名-new-themes.json（如 "gatsby-new-themes.json"）

如果没有看到文件，请将 final_data.json 文件复制到 src/data/ 文件夹，并按照上述说明重命名。

第七步：复制章节文本到公共资源

检查 public/chapters/ 文件夹，确认是否存在对应的故事文件夹（如 public/chapters/gatsby/），其中包含章节 .txt 文件。

如果文件夹不存在或为空，请将 notebooks/chapters/ 中你的故事的完整章节文件夹复制到 public/chapters/ 文件夹中。

第八步：更新前端选项列表

打开 src/components/Header/PlotOptions.tsx，将你的文件名添加到 storyOptions 列表中：


const storyOptions = [
    "gatsby-new",
    "gatsby-new-themes",
    // 在这里添加你的新故事...
];

第九步：运行应用

保存更改并重新启动前端服务：


cd story-viz
yarn dev

现在你应该能够从下拉菜单中选择你的故事，并看到可视化结果了！

常用命令

前端开发命令


# 进入前端目录
cd story-viz

# 安装依赖
yarn install

# 启动开发服务器
yarn dev

# 构建生产版本
yarn build

# 预览生产构建
yarn preview

# 代码检查
yarn lint

后端开发命令


# 进入项目目录
cd story-viz

# 安装依赖（会创建 .venv 虚拟环境）
pipenv install --python 3.12

# 激活虚拟环境
pipenv shell

# 启动服务器
python backend/server.py

# 退出虚拟环境
exit

Docker 命令


# 构建镜像
docker build -t story-ribbons-cn:latest .

# 运行容器
docker run -it -p 5200:5200 -p 5000:5000 -v $(pwd):/workspace story-ribbons-cn:latest

# 查看运行中的容器
docker ps

# 停止容器
docker stop <container-id>

常见问题

1. 前端服务无法启动

问题：运行 yarn dev 时出现端口被占用错误。

解决方案：


# 检查端口占用
lsof -i :5200

# 或者修改端口
# 编辑 story-viz/vite.config.ts，修改 server.port

2. 后端服务连接失败

问题：前端无法连接到后端服务。

解决方案：

确认后端服务正在运行（访问 http://127.0.0.1:5000）
检查 secrets.json 中的 API 密钥是否正确
查看后端终端的错误日志

3. 数据解析失败

问题：运行 Jupyter Notebook 时出现错误。

解决方案：

确认 OpenAI API 密钥有效且有足够配额
检查故事文本文件格式是否正确
尝试减少章节数量或简化文本内容

4. Docker 容器无法构建

问题：Docker 构建过程中出现网络错误。

解决方案：

检查网络连接
配置 Docker 镜像加速器
尝试使用 VPN 或代理

学术引用

如果你在研究或项目中使用了 Story Ribbons，请引用原始论文：


@article{yeh2025story,
  title={Story Ribbons: Reimagining Storyline Visualizations with Large Language Models},
  author={Yeh, Catherine and Menon, Tara and Arya, Robin Singh and He, Helen and Weigel, Moira and Vi{\'e}gas, Fernanda and Wattenberg, Martin},
  journal={IEEE Transactions on Visualization and Computer Graphics},
  year={2025},
  publisher={IEEE}
}