Metaflow

Metaflow 把基于 SuperSplat 的 Editor、资源索引和定制 Viewer 组合成一条 3D Gaussian Splatting 编辑、发布与分享链路。

项目入口

入口	用途
中文文档总入口	快速开始、操作指南、概念、参考与维护
Viewer 快速开始	本地运行 Viewer 与打开 route
Editor 快速开始	本地运行当前 Editor 源码
Editor 到 Viewer	导出模型/settings 并进入稳定路由
资源索引参考	`data/index.json` schema 与生成规则
兼容边界与版本事实源	Viewer、Editor、index、上游与发布事实从哪里读取
版本与发布	SemVer、Version History 与 Ledger 的更新边界
部署	Viewer、data 与 Editor 镜像怎样进入 Netlify publish 目录
仓库地图	活跃源码、生成物与历史快照边界

当前发布恢复基线

产品	当前版本	上游基线	唯一事实来源
Viewer	`5.21.5` / package `5.21.5`	SuperSplat Viewer `1.35.2` / PlayCanvas `2.22.4`	`metadata/version-history.json`
Editor	`1.1` / app `1.1.0`	SuperSplat Editor `2.28.0`	`metadata/editor-version-history.json`
资源索引	schema `1.2`	不适用	`data/index.json`

Viewer 源码在 metaflow-viewer/；Editor 源码在 supersplat-v2.28.0/，metaflow-editor/ 是发布构建。MF-30 的 v1.29.1 运行时产品 SHA 为 26e311c，5.19.2 analytics/release 修复 SHA 为 92d11b0。viewer-v5.19.0 的 prepare 在部署前失败且生产从未切换；viewer-v5.19.1 已通过 D2 Prepare、精确 D2 CLI/API 生产发布、真实浏览器 smoke 与 15 分钟观察；5.19.2 进一步恢复 production endpoint 并加入发布前/后校验，此前生产稳定版为 5.19.3，MF-81 已发布 3 组芒种和 9 组 SZTUCCF260919 ACG，索引共 99 项；见发布核验。当前集成版本为 5.21.5；MF-106 新增 ACG 资源 /director 实验摄影入口，发布状态与核验见 MF-106 和 PR #123。贡献与变更流程见 CONTRIBUTING.md 和 MCL v1.0 candidate。

下方保留原有 Viewer 快速参考，方便已有读者继续使用；新的分层手册和当前契约以 docs/README.md 为入口。

快速开始

# 进入 Viewer 包
cd metaflow-viewer

# 安装依赖
npm ci

# 首次需要读取仓库 data/ 时建立本地链接（public/data 不存在时执行）
mkdir -p public
ln -s ../../data public/data

# 构建项目
npm run build

# 用 SPA fallback 启动服务器，稳定 route 才不会直接 404
npx --no-install serve -s public -l 3000

服务器将在 http://localhost:3000 启动。

ACG Director 实验入口

在符合条件的 ACG 单文件 SOG／PLY 资源主路由或别名后追加 /director，例如 /acg/szcaf15/honkai_star_rail-tribbie/director。页面按索引加载主模型与已声明环境；不支持流式资源，也不接受任意远程模型地址。需要 WebGPU 和浮点渲染能力。Viewer 同标签页的有效机位优先，直接打开则读取资源 JSON 初始机位。

完整站点构建和预览（先物化已登记的 Git LFS 资源）：

npm --prefix metaflow-viewer ci
npm --prefix metaflow-viewer run build
npm --prefix metaflow-director ci
npm --prefix metaflow-director run build
node scripts/stage-director-site.mjs
node metaflow-director/preview.mjs

预览地址为 http://127.0.0.1:5207；所有模型、编码器和字体读取同站路径，不需要原实验服务。发布包使用自有界面、系统字体和许可登记的开源依赖，来源见 MF-106 Spec。

开发模式

稳定 route 的开发模式使用两个终端：

# 终端 1：自动重新构建
npm run watch

# 终端 2：为未知路径提供 index.html fallback
npx --no-install serve -s public -l 3000

当前 npm run develop 内部使用不带 -s 的 serve public，适合根路径或直接 query 调试，不能单独验证 /acg/... 之类的深层 route。完整说明见 Viewer 快速开始。

使用方式

1. URL 路由（推荐）

直接访问路由路径即可加载对应资源：

http://localhost:3000/acg/ad05/delta-force
http://localhost:3000/acg/ad05/frieren
http://localhost:3000/acg/yzx/yzx

路由信息来自 /data/index.json。本地服务器必须提供 SPA fallback；否则资源即使存在，直接打开深层路径也会先得到静态服务器 404。

2. URL 参数

也可以使用 URL 参数指定内容：

http://localhost:3000/?content=/data/path/to/model.sog&settings=/data/path/to/settings.json

支持的参数：

参数	说明
`content`	模型文件路径 (.sog / .compressed.ply)
`settings`	设置文件路径 (.json)
`poster`	加载时显示的图片
`skybox`	天空盒图片
`noui`	隐藏 UI
`noanim`	禁用动画

项目结构

metaflow-viewer/
├── src/                    # 源代码
│   ├── index.html          # HTML 模板（含路由配置）
│   ├── index.scss          # 样式
│   ├── index.ts            # 入口
│   └── ...                 # 其他模块
├── public/                 # 构建产物
│   ├── index.html
│   ├── index.css
│   ├── index.js            # 打包后的 JS (含 PlayCanvas 引擎)
│   ├── data -> ../../data  # 本地开发链接；部署时由 Netlify 同步副本
│   └── serve.json          # 服务器配置（SPA 路由）
├── package.json
├── rollup.config.mjs
└── tsconfig.json

数据目录

/data/index.json 包含所有资源的索引信息：

{
  "resources": [
    {
      "id": "delta-force",
      "title": "三角洲",
      "route": "/acg/ad05/delta-force",
      "files": {
        "model": "ACG/AD05/.../Delta Force.sog",
        "settings": "ACG/AD05/.../settings.json"
      }
    }
  ]
}

部署

npm run build 生成 Viewer 文件；完整平台发布还要把仓库根 data/ 和 metaflow-editor/ 同步到 public/data/、public/editor/。当前 Netlify 命令已执行这一步，手工部署时也不能漏掉。Editor 源码的 dist/ 不会被 Netlify 自动采用；完整 staging 和发布步骤见部署。

注意：需要配置服务器支持 SPA 路由（将所有路径重定向到 index.html，除了 /data/ 等静态资源）。

Nginx 配置示例：

location / {
    try_files $uri $uri/ /index.html;
}

当前版本

字段	值
展示版本	`5.21.5` （MF-106，PR #123）
包版本	`5.21.5`
索引 schema	`1.2`
上游 SuperSplat Viewer	`v1.35.2`
PlayCanvas	`2.22.4`
当前产品实现 commit	`103afad3`（候选）
发布控制修复 commit	`92d11b0`

当前 Editor

字段	值
Metaflow Editor	`1.1`
上游 SuperSplat Editor	`v2.28.0`
当前源码目录	`supersplat-v2.28.0`
历史基线源码目录	`references/supersplat-v2.18.1`；其 `v2.18.1` 仅表示 lineage，内容身份见 `metadata/reference-snapshots.json`
`/editor` 运行时版本	`metaflow-editor/version.json`
版本历史	`metadata/editor-version-history.json`
三方审查快照登记	`metadata/reference-snapshots.json`：Viewer `v1.26.2/v1.29.1`、Editor `v2.28.0/v2.32.3`、Transform CLI `v2.5.1/v3.3.0`；执行中发布的前一候选 `v1.28.0/v1.29.0/v3.2.0` 仍作为不可变中间快照保留
三方审查结论	`docs/history/upstream-reviews/2026-08-10/`：Viewer Adopt、Editor Defer、Transform CLI Adopt（离线工具）；均未在本轮发布

最近版本

版本	commit	摘要
`5.19.3`	`f999471`	MF-81：3 组芒种、9 组 SZTUCCF260919 ACG，原始镜头 4K WebP、99 项索引；最终生产状态见 Issue #81
`5.19.2`	`92d11b0`	analytics/release 修复：production/tagged build 缺少 Supabase endpoint 时直接失败，Netlify production context 注入 endpoint，release smoke 校验最终 HTML meta；不改变资源、路由或 schema
`5.19.1`	`534b013`	MF-30 正式生产发布：修复 release/CI sparse fixture 与 build-before-test 顺序；D2 controlled Prepare 通过后，因 Netlify Git build 再次停滞，经明确授权使用精确 D2 CLI/API 发布 deploy `6a7efc396f36c800cfa0702e`；真实浏览器 smoke、15 分钟观察与 GitHub Release 均完成
`5.19.0`	`26e311c`	MF-30 同步 Viewer v1.29.1 / PlayCanvas 2.21.3 并保留 Metaflow 合同；不可变 Tag 已建立，但 workflow run `31779246997` 在 prepare 的 sparse/order 校验阶段失败，production job 未执行、没有 GitHub Release，生产从未切换到 5.19.0
`5.18.1`	`578272c`	发布 BitCity 260711 与第十五届深圳动漫节 27 条人物资源及默认 figure8 动画策略
`5.18a`	`c613a87`	新增并对齐深圳笔架山动态 voxel 场景
`5.18`	`7ce294a`	优化移动端触控游戏控制
`5.17`	`f371f48`	对照支付宝式数据面板补齐全局筛选、指标口径、D30 留存、访问时长/时段画像、可信机型明细、机型质量排行和转化目标
`5.16`	`e68d52b`	新增 Metabase 看板汇总层：今日小时对比、留存 cohort、来源分析、保守机型统计和双语看板卡片
`5.15`	`46b4ec2`	为 SZTU 全部资源补齐中文域名短链 alias，包括 `/top10-26` 和 `/fes/top10-26`
`5.14`	`7c52315`	修复深圳技术大学.com 根域跳转到 `/sztu/c2-lib`，并恢复 `/c2-lib` 短链 alias
`5.13`	`4031c46`	新增 `/dashboard` 和 `/dashboard/*` 到 Metabase 仪表盘子域的重定向
`5.12`	`de75ce5`	修复 analytics sendBeacon 跨域 credentials 上报失败，并关闭缺失 CSS sourcemap 引用
`5.11`	`b06b13c`	补充 UA/Client Hints、来源归因、Web Vitals、Resource Timing、聚合交互深度和设备/性能/用户/数据质量建模
`5.10`	`8b37760`	新增 Supabase 权威埋点链路、15 秒可见心跳、Metabase 建模表、可选 PostHog 精简镜像和多人同屏分析事件预留
`5.9`	`1d9ab2b`	调慢 SOG/流式 reveal、uRevealActive 藏点、流式主体提前高 LOD、环境不阻塞首帧、c2-lib 首次退出动画进 Orbit
`5.8`	`4e848ac`	按场景分档 reveal 点大小，修复流式 LOD 双波揭示，恢复 loading 后可见再播放
`5.7`	`4114e8f`	简化 reveal 振荡：去掉 lift 波前隆起，保留 sin 抖动，delay 缩至 1.0s
`5.5`	`f4c4621`	新增全站高斯点 reveal 粒子揭示效果，支持环境模型并提供 `?noreveal` 逃生参数
`5.3a`	`74c04c0`	更新 Cyrene 初始构图和缩略图
`5.3`	`7672825`	修复 Netlify 发布目录的数据同步方式
`5.2`	`99ffe6c`	路由索引改为强制重新验证，避免旧缓存导致黑屏
`5.1`	`6558254`	恢复旧 SOG 排序完成或超时后的首帧兜底
`5.0`	`f41f6de`	同步 SuperSplat v1.26.2 架构并移植 Metaflow 定制
`4.4`	`e47067b`	发布 Dayun tiled voxel 与版本历史基础设施
`4.3`	`8bc11d5`	补充 Firefly 设置与包管理声明

完整审计资料：

5.18a / 5.18.0 是最后一个双轨历史版本，5.18.1 是此后的首个完整 SemVer 发布。5.19.0 是已合并但在部署前失败的 MINOR 发布尝试；5.19.1 是 release transport 的 PATCH 恢复，5.19.2 是 analytics endpoint 与发布校验的 PATCH 修复。旧字母版本保持原样，后续统一使用 SemVer PATCH/MINOR/MAJOR。

URL 查询参数详解

查询参数可以追加在资源路由或根路径之后。第一个参数使用 ?，后续参数使用 &：

http://localhost:3000/acg/fireflyfes38/cyrene?debug&ministats
http://localhost:3000/?content=/data/model.sog&settings=/data/settings.json

包含空格或中文的路径应进行 URL 编码。当前覆盖规则不是统一的“query 优先”：存在 content 时会完全跳过 route/index；route 命中后会覆盖 query 中的 settings；poster、environment、collision、voxel 和 voxelManifest 则保留显式 query 值。完整矩阵和当前实现来源见 Viewer URL 参数参考。

资源参数

参数	值	说明
`content`	URL	主模型地址，支持 SOG、压缩 PLY 或流式 LOD JSON
`settings`	URL	Viewer 设置文件地址，支持 JSON 和现有 JSONC 兼容语法
`poster`	URL	加载阶段显示的封面图片
`skybox`	URL	环境天空盒图片
`environment`	URL	独立环境 Gaussian Splat 模型
`collision`	URL	碰撞资源地址；GLB 作为网格碰撞，voxel JSON 作为体素碰撞
`voxel`	URL	单体 `walk.voxel.json` 地址；首帧后在后台加载对应 BIN
`voxelManifest`	URL	tiled voxel 清单地址；分块按照用户位置按需加载

界面与动画参数

参数	说明
`noui`	隐藏 Viewer UI，适合嵌入或纯画面输出
`noanim`	禁止默认动画自动播放；不会启动 figure8，也不会消耗首次动画退出策略

渲染参数

参数	值	说明
`webgl`	无	强制使用 WebGL；未设置时优先尝试 WebGPU
`aa`	无	启用 Gaussian Splat 抗锯齿
`nofx`	无	禁用 CameraFrame 后处理
`noreveal`	无	禁用高斯点首帧粒子揭示效果；不影响普通 loading UI
`hpr`	`1`、`true`、`enable` 或空值	强制启用高精度渲染；其他显式值表示禁用
`budget`	数字	覆盖 splat budget，单位为百万，例如 `budget=3`
`fullload`	无	等待完整 LOD 质量，适合截图或离线验收
`colorize`	无	使用颜色显示 LOD 层级
`unified`	无	保留的统一渲染兼容参数；当前加载器默认使用 unified 语义

调试参数

参数	说明
`debug`	自动打开相机调试面板，可查看/编辑位置与焦点并截图；也可按 `Ctrl+Shift+D`，macOS 可按 `Cmd+Shift+D`
`ministats`	显示实时性能仪表盘，包括帧率、显存和 splat 数量
`heatmap`	将可用的碰撞调试叠层初始化为热力图模式

Viewer 会忽略未识别的查询参数。例如 cb=时间戳 可以用于生成不同 URL 或辅助缓存排查，但不会改变 Viewer 行为。

Navigation Menu

Repository navigation

About

Repository files navigation

Metaflow

项目入口

当前发布恢复基线

快速开始

ACG Director 实验入口

开发模式

使用方式

1. URL 路由（推荐）

2. URL 参数

项目结构

数据目录

部署

当前版本

当前 Editor

最近版本

URL 查询参数详解

资源参数

界面与动画参数

渲染参数

调试参数

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
analytics		analytics
data		data
docs		docs
metadata		metadata
metaflow-director		metaflow-director
metaflow-editor		metaflow-editor
metaflow-viewer		metaflow-viewer
references		references
scripts		scripts
supabase		supabase
supersplat-v2.28.0		supersplat-v2.28.0
.gitattributes		.gitattributes
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
MIGRATION_VALIDATION.md		MIGRATION_VALIDATION.md
PROJECT_INDEX.md		PROJECT_INDEX.md
README.md		README.md
ROADMAP.md		ROADMAP.md
netlify.toml		netlify.toml

Latest commit

History

Folders and files

Repository files navigation

Metaflow

项目入口

当前发布恢复基线

快速开始

ACG Director 实验入口

开发模式

使用方式

1. URL 路由（推荐）

2. URL 参数

项目结构

数据目录

部署

当前版本

当前 Editor

最近版本

URL 查询参数详解

资源参数

界面与动画参数

渲染参数

调试参数

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages