1.0.0

9kvr · 芊云全景开发者工具

面向芊云全景插件生态的官方 CLI + SDK。
从插件创建、工程初始化、本地开发、宿主能力调用，到构建、发布、版本上线，一条链路完成。

芊云全景 是面向全景创作者、商家与开发者的一站式 VR 全景创作与分发平台。平台不仅提供 360° 全景制作、可视化编辑、云端托管和多端传播能力，也持续开放插件、API 与宿主 SDK，让开发者可以在现有全景作品之上继续构建自己的交互、业务和品牌体验。

如果你只是想制作和发布全景作品，可以直接使用芊云全景；如果你希望进一步扩展作品能力、开发定制交互或接入自己的业务，9kvr 就是进入芊云全景开发者生态的工具链。

• 芊云全景官网：https://9kvr.cn/
• 芊云全景 Web：https://web.9kvr.cn/
• 插件开发文档：https://9kvr.cn/t/kLiUn
• 开发者凭证：https://9kvr.cn/tour/workbench/credentials

---

芊云全景能做什么？

芊云全景不是一个单纯的“全景图片播放器”，而是一套覆盖 采集、制作、编辑、托管、传播和二次开发 的 VR 全景平台。

1. 360° VR 全景制作与漫游

将标准 2:1 全景图制作成可拖动、可缩放、可沉浸浏览的 VR 全景作品，并支持多个场景组成完整漫游空间。

适合：

• 景区 / 文旅线上导览
• 房产 / 家居 VR 看房
• 校园 / 园区 / 企业展厅
• 酒店 / 民宿 / 商铺展示
• 城市、乡村、人文与自然景观记录
• 品牌空间与商业项目展示

平台提供全景发布、场景管理、场景切换和在线浏览能力，用户不需要自己搭建播放器、切片服务器和作品管理后台。

2. 所见即所得的可视化编辑器

全景作品发布之后，可以继续在芊云编辑器中进行可视化配置，而不是反复修改代码。

目前平台公开能力包括：

• 多场景漫游与场景切换
• 热点编辑与互动入口
• 背景音乐
• 引导图标
• 语音讲解与场景导览类交互
• 实时预览
• 面向作品的持续编辑与管理

对于普通创作者，它是一套低门槛的 VR 内容生产工具；对于开发者，它又提供了可以继续扩展的宿主运行环境。

3. 高清全景处理与云端托管

芊云全景提供全景图片处理和云端作品托管能力，可将高清全景素材处理成适合网络浏览的内容，并由平台负责作品访问与展示链路。

这意味着开发者或创作者可以把精力放在内容和业务上，而不是自己维护全景切片、静态资源分发、播放器部署和作品访问页面。

4. AI 辅助创作与管理

芊云全景正在把 AI 能力逐步融入工作台和全景生产流程。

面向实际业务，AI 可以参与：

• 作品管理
• 素材整理
• 热点配置
• 内容与质量优化
• 开发需求梳理
• 插件开发辅助

目标不是单独增加一个“AI 聊天入口”，而是让 AI 参与全景内容从制作到开发的真实工作流，降低学习成本和重复操作。

5. 全景视频与多渠道传播

完成的全景内容不只停留在一个网页里，还可以继续向更多渠道传播。

平台公开提供或对接的能力包括：

• 全景视频导出
• 微信生态传播
• 抖音小程序挂载
• 百度地图相关上传 / 分发能力
• Web 链接分享
• 小程序与品牌化展示场景

同一份全景内容可以同时承担作品展示、营销传播、线上导览和短视频素材等用途。

6. 3D 内容展示

除传统 360° 全景外，芊云全景也提供 3D 模型展示能力，公开支持 OBJ、GLTF、GLB 等常见模型格式，可用于独立 3D 展示或与全景内容组合呈现。

适合产品展示、数字展厅、空间说明以及需要 3D 资产辅助表达的业务场景。

7. 移动端全景采集

芊云全景提供面向移动端的全景采集能力，可通过手机完成全景拍摄流程，包括陀螺仪引导、自动拍摄、实时预览、补拍对齐和素材导出等能力。

对于没有专业全景相机的用户，这可以显著降低采集门槛，让“拍摄 → 制作 → 发布”形成更完整的闭环。

8. 开发者服务与插件生态

芊云全景不仅提供成品功能，也允许开发者在平台能力之上继续开发。

你可以通过插件和开放能力构建：

• 自定义开场页 / 封面插件
• 品牌介绍和营销交互
• 自定义热点交互
• 页面型插件与专题内容
• 场景联动逻辑
• 导览、讲解和业务入口
• 面向特定行业的定制功能
• 与自身系统结合的二次开发能力

9kvr 就是这套开发者能力的本地入口。

平台功能、套餐权益及开放范围会持续更新，具体以芊云全景官网和开发者平台当前页面为准。

---

为什么要有 9kvr？

全景插件开发最容易卡住的并不是“写一个按钮”，而是下面这些问题：

• 插件到底怎样和芊云全景里的插件记录关联？
• 宿主当前场景、视角和热点怎样读取？
• 怎样监听场景变化和热点事件？
• Vue / React 项目应该怎样组织？
• 本地写完以后怎样构建成平台可以加载的产物？
• 发布和正式上线为什么要分成两个步骤？

9kvr 把这些流程统一起来。

插件中心创建插件
        ↓
获取插件 ID
        ↓
9kvr 初始化本地工程
        ↓
本地开发 / 调试
        ↓
构建 UMD 产物
        ↓
发布历史版本
        ↓
确认后正式上线

平台负责插件身份、配置和运行环境，9kvr 负责本地工程、SDK 和发布链路，开发者只需要专注自己的插件业务。

---

9kvr 提供的开发能力

CLI：完整插件开发生命周期

9kvr CLI 已覆盖插件开发常用流程：

远程插件操作统一通过芊云 MCP 完成，不再依赖旧的快捷码、uid/token 或历史 Develop API 调用方式。

上传媒体素材

先使用开发者 Key 登录，然后可以上传本地文件：

npx 9kvr login --key=<开发者key>
npx 9kvr upload file ./cover.jpg

MCP 与 CLI 的选择建议：小于 30KB 的图片或短内容可以使用 MCP upload_media 的 Base64；大文件不要转成 Base64 发送给 MCP，应优先使用本 CLI 的 npx 9kvr upload file <文件路径>，避免 Base64 膨胀、上下文过大或传输失败。MCP 上传失败或客户端无法传递本地文件时，也使用 CLI 兜底。执行 CLI 上传前必须先完成 npx 9kvr login --key=<开发者key>。

也可以直接传入 Base64 或 Data URL。Base64 上传必须指定带扩展名的文件名：

npx 9kvr upload file \
  --base64='<base64内容或data:image/png;base64,...>' \
  --filename=cover.png \
  --name='作品封面'

命令成功后返回 JSON，包含素材表数字 media_id、素材链接 url 和文件名。不同媒体类型使用独立大小限制，用户/企业素材空间不足时会拒绝上传。

作品封面和素材封面通常使用正方形图片；如果是后续 MCP 生图或图片处理，建议提示生成约 400×400，这里只是推荐尺寸，不是 CLI 或服务端的硬性尺寸限制。

CLI 会在请求服务端前校验文件后缀、真实格式和大小，限制与服务端一致：

• 图片：jpg、jpeg、png、webp、gif，最大 500KB
• 音频：mp3、mpeg、wav，最大 5MB
• 视频：mp4，最大 10MB

文件真实格式必须与扩展名一致。服务端还会再次执行同口径校验和空间校验。素材名称、说明会进行内容安全检测；媒体上传后还会进行异步安全审核，审核异常会删除对应素材并通知用户。

SDK：直接调用芊云宿主能力

插件不需要直接操作芊云播放器内部实现。宿主通过 pluginContext / pluginBridge 向插件暴露稳定能力，SDK 再提供更易使用的封装。

当前 SDK 已覆盖：

自动清理事件监听

通过 usePluginEvents()、useScene() 和 useHotspot() 注册的部分监听会绑定当前插件作用域，并在插件卸载时自动执行清理，避免插件反复挂载后留下无效监听。

标准插件生命周期

插件统一采用：

setup
  ↓
mount
  ↓
update（0 ~ N 次）
  ↓
unmount

这使 Vue、React 和原生 JavaScript 插件都可以使用同一套宿主协议，而不需要分别适配芊云播放器内部实现。

---

支持的项目模板

初始化插件时可以直接选择：

• react — 适合 React 技术栈和组件化交互插件
• vue2 — 适合现有 Vue 2 项目和芊云生态中的存量前端方案
• vanilla — 原生 JavaScript，依赖更少，适合轻量插件

npx 9kvr plugin <插件ID>

CLI 会自动：

1. 校验开发者登录状态；
2. 从插件中心读取插件记录；
3. 读取插件 Manifest 和 Schema；
4. 让你选择模板；
5. 创建本地工程；
6. 写入 .9kvr-plugin.json；
7. 写入 plugin.manifest.json；
8. 写入 plugin.schema.json；
9. 同步插件名称、描述、版本等基础信息。

这可以保证“平台里的插件”和“本地工程”从一开始就是同一个插件，而不是两个需要人工对齐的孤立项目。

---

快速开始

1. 在芊云全景插件中心创建插件

先在平台创建插件记录，配置插件基础信息，并取得插件 ID。

不要先随意创建一个本地工程再想办法绑定。
当前推荐流程是平台先创建、本地后初始化。

2. 获取开发者 Key 并登录

开发者 Key：

https://9kvr.cn/tour/workbench/credentials

npx 9kvr login --key=<开发者key>

登录成功后凭证保存在：

~/.9kvr/auth.json

3. 初始化插件工程

npx 9kvr plugin <插件ID>

然后选择：

Vue 2
React
原生 JavaScript

npx 9kvr init <插件ID> 目前仍兼容，但已经进入迁移状态，新项目请使用 plugin 命令。

4. 安装依赖并启动开发环境

cd <插件目录>
npm install
npm run dev

5. 构建插件

npm run build

模板最终会输出芊云插件运行时需要的 UMD 构建产物。

6. 发布历史版本

npx 9kvr pub

发布成功代表：新的历史版本已经上传。

它并不等于当前线上插件已经被替换，这样可以避免一次构建错误直接影响正在使用的作品。

7. 正式上线指定版本

发布成功后会得到历史版本 ID：

npx 9kvr online --history-id=<历史版本ID>

上线后，该历史版本才会成为当前正式版本。

---

一个最小的 SDK 示例

下面的插件在挂载时读取当前场景，并监听场景切换：

import { definePlugin, useScene, useDebug } from '9kvr'

export default definePlugin({
  setup() {
    const scene = useScene()
    const debug = useDebug()

    const handleSceneChange = (packet) => {
      debug.log('scene changed', packet)
    }

    scene.onSceneChange(handleSceneChange)

    return {
      mount(el) {
        el.innerHTML = `当前场景：${scene.getCurrentSceneId()}`
      },
      update() {
        debug.log('plugin updated')
      },
      unmount() {
        // 通过 SDK 注册的监听会跟随插件作用域执行清理。
      },
    }
  },
})

你也可以进一步：

const scene = useScene()
const hotspot = useHotspot()

await scene.switchScene('scene-id')
await scene.setView({ hlookat: 90, vlookat: 0, fov: 80, duration: 800 })

hotspot.addTextHotspot({
  id: 'demo-hotspot',
  title: '了解更多',
  ath: 30,
  atv: 0,
  drag: true,
})

插件不是一块与全景内容无关的 iframe，而是可以在受控协议下感知并操作当前全景宿主状态。

---

可以开发哪些插件？

封面 / 开场插件

适合：

• 品牌开场页
• 项目介绍
• 活动海报
• 进入全景按钮
• 动画引导
• 用户须知

热点互动插件

适合：

• 商品信息
• 空间说明
• 景点讲解
• 房源信息
• 图文弹层
• 自定义行为入口
• 点击 / 拖拽交互

页面型插件

适合承载更完整的业务页面，例如：

• 项目介绍页
• 导览页
• 品牌专题页
• 商业活动页面
• 定制业务组件

场景联动插件

结合场景、视角、热点和宿主事件，可以开发：

• 自动导览
• 场景联动菜单
• 路线讲解
• 指定视角定位
• 互动任务
• 自定义空间导航

---

适合哪些开发者？

全景创作者

当编辑器现有功能不能满足特殊需求时，可以通过插件补充自己的交互，而不必自己重做一套全景播放器。

商业项目开发者

可以在芊云全景现有制作和托管能力上加入品牌、营销、导览、业务入口和行业逻辑，缩短项目交付周期。

前端开发者

可以直接使用熟悉的 React、Vue 2 或原生 JavaScript 开发，不需要从 krpano 或底层全景渲染开始重新学习整个技术栈。

SaaS / 行业解决方案团队

可以把芊云全景作为 VR 内容基础设施，在此之上扩展自己的行业产品和业务系统。

---

芊云全景典型行业场景

平台适合但不限于：

• 房产家居：VR 看房、样板间、家装空间展示
• 文旅景区：景区导览、虚拟旅游、文化遗产数字展示
• 教育校园：校园导览、线上开放日、沉浸式教学场景
• 汽车展示：车辆内外空间展示、线上展厅
• 商业零售：门店、商场、展会、产品空间化展示
• 企业展示：企业园区、工厂、展厅、品牌空间
• 城市与乡村记录：家乡、街道、景点和人文影像记录

全景的价值不只是“能转一圈”，而是把真实空间变成一个 可访问、可交互、可传播、可持续编辑 的数字内容载体。

---

构建与发布约定

所有官方模板最终都需要产出平台可加载的 UMD 文件。

当前发布逻辑会从 dist 中查找：

*.umd.min.js

推荐命名语义为：

<插件ID>.<版本号>.umd.min.js

插件运行时统一使用：

pluginContext
pluginBridge
setup / mount / update / unmount

更新已有插件时，应先修改 package.json.version，重新构建，再执行发布 / 更新流程。

---

开发原则

为了让插件在芊云宿主环境中稳定运行，建议遵循以下原则：

1. 通过 SDK / pluginBridge 调用宿主能力，不要依赖播放器内部未公开对象；
2. 把平台配置交给 Schema / pluginConfig，不要把用户配置写死在代码中；
3. 正确处理 mount / update / unmount，避免重复挂载和监听泄漏；
4. 发布与上线分离，先生成历史版本，确认无误后再上线；
5. 版本号明确递增，让每次发布都可以被识别和追踪；
6. 优先从官方模板开始，减少构建格式和宿主协议不一致的问题。

---

关于项目

9kvr 当前同时承担两类职责：

CLI

负责：

登录
插件初始化
本地开发
构建
发布
更新
上线

SDK

负责：

插件生命周期
宿主上下文
场景 / 视角
热点
事件
UI
渲染状态
调试
数据桥

项目当前版本以 package.json 为准。

---

相关入口

---

最后

芊云全景希望解决的不只是“怎样把一张 360° 图片放到网页上”，而是让 全景内容真正具备生产、编辑、托管、传播和扩展能力。

对于创作者，你可以更低成本地完成一套专业的 VR 全景作品；对于商家，你可以把真实空间变成持续传播的数字资产；对于开发者，9kvr 和芊云插件体系则提供了继续向上开发的入口。

先把全景做出来，再把你的业务能力装进去。

开始使用：https://9kvr.cn/