Communitygithub.com

AI Blackhole 全景导演技能

用于使用和排查 AI Blackhole Studio 在线全景导演的 Codex 技能。

AI Blackhole 全景导演技能 是什么?

此技能专为 AI Blackhole Studio 的全景导演功能设计,支持通过本地临时会话快速导入全景图像并开启导演模式。它提供了完整的本地工作流,包括图像导入、静态服务器启动及浏览器验证,确保用户能高效使用导演工具。该技能覆盖多个平台(如 Codex),并内置了详细的故障排除指南,涵盖服务器状态、端口占用、资产缺失等常见问题。核心逻辑强调本地优先,避免依赖公共网站,同时保留了公共 URL 作为诊断或分享的参考。通过读取引用文档和自动化的 Python 脚本,技能能够引导用户完成特征学习、自定义打包或问题排查,并执行浏览器端的加载验证与功能测试,确保全景视频或图像的交互正常。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add AIBlackhole/aiblackhole-director-skill

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

AI Blackhole 导演

使用此技能帮助用户处理本地 AI Blackhole Studio 全景导演会话。

入口点

默认工作流为本地:

  1. 使用 scripts/local_import.py 将本地图像复制到临时本地导演会话中。
  2. 启动本地静态服务器。
  3. 打开生成的 http://127.0.0.1:<端口>/panorama-viewer.html?image=... URL。

该技能包含位于 assets/panorama-director-deploy-v1.2.zip 的导演包。如果未提供 --web-dir,辅助脚本可以解压并使用此捆绑包。

不要使用 https://aiblackhole.net/panorama-viewer 作为此技能的默认路径。公共站点可以保留作为诊断或分享的参考,但本地部署是主要模式。

核心工作流

  1. 如果用户提供本地图像路径,阅读 references/local-import.md 并运行 scripts/local_import.py。
  2. 在浏览器控制可用时打开辅助脚本输出的 URL,否则将 URL 提供给用户。
  3. 在浏览器控制可用时确认页面已加载且 document.body 具有 panorama-loaded 类。
  4. 确定用户的下一步任务:
    • 使用导演
    • 学习某个功能
    • 自定义或打包本地导演文件
  5. 对于功能指引,阅读 references/feature-guide.md。
  6. 对于本地服务器、资产、图像、路由或浏览器问题,阅读 references/troubleshooting.md。
  7. 保持说明实用且面向用户。优先使用本地辅助脚本进行自动图像打开。

本地图像导入

当用户提供本地图像路径并希望自动打开时,使用:

python <技能目录>/scripts/local_import.py "<图像路径>" --open

当用户只想部署/打开本地导演而不附带图像时,使用:

python <技能目录>/scripts/local_import.py --open

仅当用户明确希望使用自定义导演 web 文件夹时,才传递 --web-dir。

使用辅助脚本输出的 URL 打开本地会话。解释图像被复制到临时本地 web 会话中,不会上传到任何公共网站。

浏览器检查

当浏览器控制可用时,验证:

  1. 生成的本地 URL 加载正常。
  2. 上传/导入的图像名称出现在文件元数据区域。
  3. 加载后空白上传状态被隐藏。
  4. document.body.dataset.viewMode 对于全景图像为 panorama,对于普通图像为 flat。
  5. 主要交互正常:添加角色、添加对象、添加遮挡物、变换选择、隐藏/显示侧边栏、保存屏幕截图。

可选的公共参考

历史的公共 URL 为:

https://aiblackhole.net/panorama-viewer

不要将其用于自动本地文件导入。公共网页无法读取任意本地文件路径;请改用本地辅助脚本。

故障排除顺序

对于本地会话,检查:

  1. 本地服务器进程正在运行。
  2. 生成的 imports/<图像> URL 返回 HTTP 200。
  3. 本地 web 文件夹中存在 panorama-viewer.html 和 panorama-director.js。
  4. 端口未被旧会话占用。
  5. 如果图像仍然加载失败,检查浏览器控制台/网络错误。

禁止

  • 不要强行将本地文件上传到公共站点。
  • 不要将公共网站用作此技能的默认路径。
  • 未经用户明确批准,不要修改正在运行中的部署。
  • 在检查服务器进程、端口、路由、资产路径和浏览器控制台基础知识之前,不要假设本地加载错误是由应用引起的。

相关技能