CoStage

CoStage 是一个面向 Codex 的原生 3D 预演 widget 插件。它基于 Three.js、React Three Fiber 和 Drei 提供多场景导演台，用于搭建环境、布置真实 GLB 角色与道具、调整人物姿势、设计机位，并把镜头组织成可播放的预演时间轴。

GitHub：cs68614-hash/costage

导演台由 MCP widget 直接在 Codex 中打开，正常使用不需要启动本地网页或通过 in-app browser 访问地址。场景数据默认与当前 Codex 对话关联，也可以通过显式 stageDir 让多个对话共同编辑同一个导演项目。

功能

• 在 Codex 中打开原生 Three.js CoStage widget，支持全屏导演视角和机位预览视角。
• 在一个导演项目中创建、切换、重命名、复制和删除多个场景；每个场景独立保存角色、道具、环境和机位。
• 加载项目内置的真实 GLB 角色模型，不使用占位人物；角色模型和全景资源均支持持久缓存。
• 使用移动、旋转和缩放控制器布置角色与道具；控制器跟随对象真实可视中心，并根据当前镜头和对象大小自适应显示。
• 根据当前导演镜头、FOV 和场景比例自适应添加角色、群演与道具，新增内容会出现在当前画面附近并自动选中。
• 为角色应用站立、坐姿、蹲下、行走、格斗、招手等姿势预设，也可以显示骨架关节点并逐关节旋转调整。
• 创建多个真实机位，编辑位置、注视目标和 FOV，实时查看机位预览，并切换到隐藏编辑辅助线的纯相机视角。
• 上传真实的 2:1 JPEG、PNG 或 WebP 环境全景图，或让 Codex 调用生图能力生成并应用 360 度环境。
• 调整全景水平旋转、地平线校准和环境光照；全景作为无限远背景，不参与角色与道具的物理尺度计算。
• 将不同场景和机位保存为镜头时间轴，设置镜头顺序与时长，并直接播放整段 3D 预演。
• 通过 MCP 工具读取场景、选择状态和版本，执行语义化站位、角色朝向、编组、机位及时间轴修改。
• 本地 npm run dev 使用真实的文件存储和全景图接口，不需要反复打包插件即可调试主要功能。

安装

让 Codex 自动安装

把下面这段发给 Codex：

请从 https://github.com/cs68614-hash/costage.git 安装 CoStage Codex 插件。
请 clone 仓库到 ~/plugins/costage，确认 .codex-plugin/plugin.json 存在，
运行 npm install 和 npm run build，并把 costage 加入默认 personal marketplace，
然后运行 codex plugin add costage@personal。
安装后请校验插件，并告诉我是否需要开启一个新对话来加载新的技能和 MCP 工具。

手动安装

把仓库 clone 到 personal marketplace 引用的位置：

mkdir -p ~/plugins
git clone https://github.com/cs68614-hash/costage.git ~/plugins/costage
cd ~/plugins/costage
npm install
npm run build

确保 ~/.agents/plugins/marketplace.json 中包含该插件：

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "costage",
      "source": {
        "source": "local",
        "path": "./plugins/costage"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

然后安装插件：

codex plugin add costage@personal

安装或升级后建议开启一个新的 Codex 对话，让新的 skill、MCP 工具和 widget 资源完整加载。

使用

打开导演台

在 Codex 中说：

打开当前项目的 CoStage。

插件会通过 render_director_stage_widget 打开原生 3D widget，默认使用全屏模式，不需要另外启动本地服务。

同一个 Codex 对话重新打开导演台时会继续读取原来的场景。默认数据位置为：

~/.codex/director-stage/threads/<thread-id>/director-stage.json
~/.codex/director-stage/threads/<thread-id>/selection.json
~/.codex/director-stage/threads/<thread-id>/assets/panoramas/

创建和管理场景

左侧结构树以场景文件夹组织当前导演项目。每个场景拥有独立的角色、道具、机位和环境设置，切换场景时 3D 画布会同步切换到对应内容。

可以直接在界面中新建场景，也可以告诉 Codex：

新增一个雨夜街道场景，在里面布置两名面对面交谈的角色和三个机位。

Codex 会先读取当前项目状态，再通过语义化 MCP 操作创建场景、添加真实角色、安排相对位置和朝向。面对面、画面左侧、前景、围绕、排队和错位站位等描述会按照角色方向或机位构图解析，而不是独立猜测坐标。

添加角色和道具

1. 点击底部工具栏的角色按钮，打开资源面板。
2. 选择一个官方 GLB 角色，或添加群演和几何道具。
3. 新对象会根据当前导演镜头自动计算位置和比例，出现在当前观察中心附近并立即选中。
4. 使用移动、旋转或缩放工具完成布置，也可以在右侧属性面板精确输入数值。

右键左侧结构树节点可以复制、删除或锁定对象。锁定后对象仍会保留在场景中，但不会被误操作。

调整角色姿势

1. 选中一个角色，在右侧切换到 姿势 标签。
2. 选择站立、坐姿、蹲下、行走等姿势预设。
3. 姿势模式会在人物上显示骨架和关节点。
4. 点击关节点后使用旋转控制器调整肩、肘、髋、膝、躯干和头部。

角色根节点负责整体站位，骨骼负责局部姿势。修改姿势不会替代角色的位置和整体朝向。

设计机位

1. 在导演视角中调整到需要的观察位置。
2. 点击工具栏中的机位按钮，将当前导演视角保存为一个新机位。
3. 选中机位后调整位置、注视目标、FOV 和画幅比例。
4. 右侧机位预览会实时显示该相机看到的画面，并可放大检查构图。
5. 切换到 机位视角 后，角色标签、骨架、控制器和 FOV 辅助线会隐藏，只保留最终相机画面。

也可以让 Codex 设计镜头：

为当前双人对话设计一个大全景、一个双人中景和两个越肩近景，并设置合理的 FOV。

使用环境全景图

手动上传

1. 点击导演视角的空白处，打开右侧 3D 场景 面板。
2. 在 全景背景 中上传 JPEG、PNG 或 WebP 图片。
3. 图片必须是真实的 2:1 等距柱状全景图，手动上传最低为 1024 × 512。
4. 使用水平旋转和地平线校准让全景地面与编辑网格对齐。

让 Codex 生成

在 Codex 中说：

为当前场景生成并应用一张雨夜老城区的 360 度环境全景图，保留中心区域用于人物走位。

Codex 会按 director-stage-panorama 技能生成精确 2:1 的环境图，再通过 import_director_stage_panorama 验证并保存真实图片。AI 生成全景图最低要求为 4096 × 2048，近景或窄 FOV 镜头建议使用 8192 × 4096。

全景图只提供远景环境和光照参考。可编辑角色、道具、机位和网格仍使用独立的 3D 坐标，不会跟随全景球半径缩放。

创建和播放镜头时间轴

1. 完成一个场景的初始角色站位、姿势和机位。
2. 在底部时间轴点击添加，将当前布景保存为“建立”动作阶段的镜头。
3. 修改人物位置、朝向或姿势，再添加下一动作阶段；时间轴会显示该阶段类型和名称。
4. 同一动作时刻可以使用多个机位，它们会复用同一个人物状态；进入下一动作阶段时保存新的场景快照。
5. 为镜头设置名称、时长和顺序，切换其他场景继续添加。
6. 点击播放，在一个时间轴中预演整幕的多场景、多动作阶段镜头。

每个时间轴镜头会保存 sceneId、cameraId、actionStage 和完整场景快照，因此播放时可以稳定恢复当时的人物站位与姿势，而不是只保存一张缩略图。通过 MCP 创建连续表演时，新动作阶段必须包含真实人物变化；只有文字描述变化、人物状态不变的镜头会被拒绝。

打开一个时间轴镜头并修改人物动作后，点击该镜头操作栏中的保存图标，可以用当前布景更新动作阶段和缩略图。同一动作阶段下的多个机位会同步人物状态，但保留各自的相机。AI 修改已有镜头动作时会调用 refresh_director_timeline_shot 完成同样的同步。

技能

• costage:director-stage-open：打开当前 Codex 对话关联的原生 CoStage widget。
• costage:director-stage-compose：创建和修改多场景布景、角色关系、姿势、机位和镜头时间轴。
• costage:director-stage-panorama：生成、验证、导入和调整真实 2:1 环境全景图。
• costage:shot-design-foundations：把景别、角度、构图、180° 连贯性、连续分镜和蒙太奇方案落实为 CoStage 机位与时间轴。
• costage:shot-design-production：执行单人到多人对白调度、运动镜头关键点、开幕落幕设计和剪辑节奏预演。
• costage:character-action-design：设计并应用表演、舞蹈、武术、运动和人物互动的动作阶段与静态关键姿势。

两个镜头设计 skill 的知识资料参考任磊《镜头设计：电影、短剧与短视频的拍摄之道》。它们会区分“只做方案”和“实际执行”：用户要求搭建时会读取真实场景并调用 CoStage MCP，不会只返回一份文字分镜。连续运镜在当前版本中以可检查的起点、关键点和终点机位快照表示，不会误报为已经生成平滑相机动画。

角色动作 skill 使用 CoStage 当前真实的 25 项骨骼姿势字段，把舞蹈、武术和复杂表演拆成准备、发力、强调、跟随与恢复等可检查阶段。当前版本会实际应用一个静态关键姿势，但不会把场景快照误报为连续骨骼动画；手脚 IK、接触约束和动作插值仍属于后续动作时间轴能力。

MCP 工具

• render_director_stage_widget：打开原生导演台 widget。
• get_director_stage_state、get_director_stage_revision：读取完整场景和增量版本。
• save_director_stage_state：替换并保存完整导演项目。
• apply_director_stage_operations：执行场景、节点、站位、朝向、环境和机位等语义化修改。
• get_director_stage_selection、save_director_stage_selection：读取或修改当前选择。
• read_director_stage_model：向原生 widget 提供内置真实 GLB 模型。
• import_director_stage_panorama、read_director_stage_panorama：保存和读取全景资源。
• create_director_timeline_shot、refresh_director_timeline_shot、update_director_timeline：按动作阶段创建镜头、把当前修改同步回动作阶段，或排序、改时长和删除镜头。

存储方案

默认情况下，导演项目与 Codex 对话绑定：

为兼容改名前已经创建的场景、MCP 调用和模型缓存，CoStage 继续使用 director-stage 数据目录、director_stage_* 工具名以及原缓存标识。它们属于稳定存储协议，不代表当前插件品牌仍是旧名称。

~/.codex/director-stage/threads/<thread-id>/
├── director-stage.json
├── selection.json
└── assets/
    └── panoramas/

场景 JSON 只保存全景资源的元数据和内容哈希，原始图片保存在 assets/panoramas/ 中。同一张图片按内容哈希只保存一次。

如果需要多个 Codex 对话共同编辑同一导演项目，请先确定一个绝对 stageDir，并在所有打开、读取和修改工具调用中持续传入同一个目录。不要在共享过程中省略 stageDir，否则新对话会创建自己的独立场景。

本地开发

npm install
npm run dev

开发页面默认运行在：

http://127.0.0.1:5173/

本地开发模式拥有真实的场景与全景图文件接口，不依赖 Codex widget 注入的 MCP bridge。开发数据保存在项目目录下：

.director-stage-dev/director-stage.json
.director-stage-dev/selection.json
.director-stage-dev/assets/panoramas/

本地开发数据与正式插件对话数据隔离，不会覆盖 ~/.codex/director-stage/threads/ 中的导演项目。

常用命令：

npm run dev          # 启动 Vite 开发页面
npm run build        # 类型检查并构建 widget
npm run preview      # 预览生产构建
npm run check:mcp    # 检查 MCP 和开发脚本语法
npm run probe:mcp    # 验证 MCP、存储、时间轴和原生 widget
npm run probe:dev    # 验证本地场景与全景图接口
npm run quality      # 执行完整质量检查

可选环境变量：

• CODEX_THREAD_ID：由 Codex 宿主提供，用于绑定默认对话存储。
• DIRECTOR_STAGE_DEV_STAGE_DIR：覆盖本地开发数据目录，适合自动化测试或隔离不同开发场景。

技术栈

• Three.js：3D 场景、相机、骨骼、灯光与渲染。
• React Three Fiber：React 形式的 Three.js 场景管理。
• Drei：轨道控制器、变换控制器、网格和辅助组件。
• Model Context Protocol：Codex、技能、MCP 工具和原生 widget 通信。
• Vite：本地开发与生产构建。

开发者

chongsongsong

致谢

CoStage的 3D 编辑能力基于 mrdoob/three.js、pmndrs/react-three-fiber 和 pmndrs/drei 实现。