🎭 HumanVIZ

/workspace/
├── README.md                     # 项目说明文档
├── .cnb.yml                      # 云原生构建配置文件（CNB 平台配置）
├── Dockerfile                    # Docker 镜像构建配置
├── LICENSE                       # 开源许可证
├── files/                        # 项目文档与比赛资料
│   ├── Problem.md                # ChinaVIS 2026 赛题说明
│   ├── Start.md                  # 快速上手指南
│   ├── Submit.md                 # 作品提交说明
│   ├── OUTLINE.md                # 项目架构设计与规划
│   ├── OPERATION.md              # 前端开发手册
│   ├── BACKEND.md                # 后端 API 文档
│   ├── FULL-STACK.md             # 全栈技术栈参考
│   ├── DATASET.md                # 数据集详细说明
│   ├── analysis_report_4.md      # 数据分析报告
│   ├── 多人协作开发指南.md        # 多人协作开发规范
│   ├── StoryRibbons.pdf         # 原始论文 PDF
│   └── 1-I_answerSheet.pdf      # 比赛答题纸
├── scripts/                      # 脚本工具
│   ├── init-claude.sh            # Claude Code CLI 配置初始化脚本
│   ├── init-codex.sh             # CodeX CLI 配置初始化脚本
│   ├── start.sh                  # 一键启动脚本（自动检查环境、安装依赖、启动服务）
│   ├── stop.sh                   # 停止服务脚本
│   └── test_api.py               # LLM API 测试脚本
└── HumanVIZ/                     # HumanVIZ 核心源代码
    ├── data/                     # 数据目录
    │   └── dataset/              # 京剧剧本数据集（1473 个 PDF，38 个文件夹）
    │       ├── 01000000/         # 《戏考》
    │       ├── 02000000/         # 《国剧大成》
    │       ├── 03000000/         # 《京剧汇编》
    │       ├── 04000000/         # 《京剧丛刊》
    │       └── ...               # 其他剧目文件夹（共 38 个）
    ├── notebooks/                # Jupyter Notebook 数据分析
    │   ├── parsing-data.ipynb    # 数据解析与处理
    │   └── scripts/              # 辅助脚本
    ├── backend/                  # 后端 Python 服务 (FastAPI)
    │   ├── main.py               # FastAPI 应用入口
    │   ├── api/                  # API 路由
    │   │   ├── routes.py         # 路由定义
    │   │   └── dependencies.py   # 依赖注入
    │   ├── core/                 # 核心模块
    │   │   ├── config.py         # 配置管理
    │   │   └── exceptions.py     # 异常处理
    │   ├── database/             # 数据库模块
    │   │   ├── connection.py     # 数据库连接管理
    │   │   └── models.py         # ORM 模型定义
    │   ├── models/               # 数据模型
    │   │   └── schemas.py        # Pydantic 模型
    │   ├── scripts/              # 数据导入脚本
    │   │   └── import_data.py    # 数据导入工具
    │   ├── services/             # 业务服务
    │   │   ├── llm_service.py    # LLM 服务
    │   │   ├── data_service.py   # 数据服务
    │   │   └── prompts.py        # LLM 提示词模板
    │   ├── static/               # 静态资源
    │   │   ├── css/              # 样式文件
    │   │   └── favicon.svg       # 网站图标
    │   └── templates/            # Jinja2 模板（管理后台）
    │       ├── base.html         # 基础布局模板
    │       ├── dashboard.html    # 管理后台首页
    │       ├── data_manager.html # 数据管理页面
    │       ├── data_preview.html # 数据预览页面
    │       ├── import_export.html# 数据导入导出
    │       ├── llm_test.html     # LLM 测试页面
    │       ├── sql_query.html    # SQL 查询页面
    │       ├── api_docs.html     # API 文档页面
    │       └── color_schemes.html# 配色方案管理
    ├── public/                   # 前端静态资源
    │   ├── chapters/             # 章节文本文件
    │   ├── characters/           # 角色图片资源
    │   ├── covers/               # 封面图片
    │   └── fav.svg               # 网站图标
    ├── src/                      # 前端 React 源代码
    │   ├── components/           # React 组件
    │   │   ├── Header/           # 顶部导航栏组件
    │   │   ├── Legend/           # 图例组件
    │   │   ├── Misc/             # 杂项组件
    │   │   ├── Modals/           # 弹窗组件（含 ChinaVIS 概览、数据概览等）
    │   │   ├── Overlays/         # 覆盖层组件
    │   │   ├── Vis/              # 可视化核心组件（角色网络、故事图等）
    │   │   ├── XAxis/            # X 轴组件
    │   │   ├── YAxis/            # Y 轴组件
    │   │   ├── Dashboard/        # 综合仪表盘（朝代环、时间轴等）
    │   │   ├── Overview/         # 数据总览组件
    │   │   ├── Stage3D/          # 3D 京剧舞台组件
    │   │   └── TaskViews/        # 任务视图组件（叙事结构等）
    │   ├── data/                 # 数据文件（JSON 格式）
    │   ├── stores/               # Zustand 状态管理
    │   │   ├── storyStore.ts     # 故事/叙事状态
    │   │   ├── dataStore.ts      # 数据加载状态
    │   │   ├── positionStore.ts  # 位置/布局状态
    │   │   └── dashStore.ts      # 仪表盘状态
    │   ├── styles/               # 全局样式
    │   │   ├── dashboard.scss    # 仪表盘样式
    │   │   └── overview.scss     # 总览样式
    │   ├── types/                # TypeScript 类型定义
    │   │   └── geojson.d.ts      # GeoJSON 类型声明
    │   ├── utils/                # 工具函数
    │   │   └── colors.ts         # 色彩工具
    │   ├── App.scss              # 主样式文件
    │   ├── App.tsx               # 主应用组件
    │   └── main.tsx              # 应用入口
    ├── .eslintrc.cjs             # ESLint 配置
    ├── index.html                # HTML 入口
    ├── package.json              # 前端依赖配置
    ├── requirements.txt          # Python 依赖清单
    ├── vite.config.ts            # Vite 构建配置
    ├── secrets_example.json      # API 密钥配置示例
    ├── tsconfig.json             # TypeScript 配置
    ├── tsconfig.node.json        # TypeScript Node 配置
    ├── README.md                 # HumanVIZ 子项目说明
    └── yarn.lock                 # Yarn 锁定文件

@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}
}