前言¶

在 DSH 的插件化思路下，Cocos 项目的预览、节点检查和代码修改可以挂到同一会话旁边。DSH / 智能体开发者常见的问题不只是“让 agent 改代码”，还要同时看到运行结果、定位具体节点，并把节点选择作为准确上下文交给 agent。如果只改浏览器 runtime，改动也不容易落到项目文件里，后续审查和继续开发会缺少基础。

下面介绍的 kurenai-studio/kurenai 就是针对这个场景的 DSH 原生插件：在 DSH 会话旁提供 Headless Cocos 实时预览，检查 runtime scene tree，点击节点后把选择作为精确 agent 上下文，并直接编辑磁盘上的 Cocos 项目源文件。

这是什么¶

kurenai-studio/kurenai 是一个 DSH-native Cocos vibe coding studio，定位是带 headless preview 和 runtime inspector 的插件。仓库由 kurenai-studio 维护，Kurenai 源码采用 MIT 许可。

当前状态为 working MVP。Kurenai 直接使用每个 DSH 会话的 workspace 目录作为 Cocos 项目根目录。它把 DSH 会话、Headless Cocos 预览、runtime inspector 和项目源文件编辑放到同一工作流里。

核心功能¶

Kurenai 的核心能力围绕“预览、检查、编辑、刷新”展开：

1. 在 DSH 会话旁提供 Headless Cocos 实时预览。
2. 检查 runtime scene tree；点击节点后，将节点选择作为精确 agent 上下文。
3. 直接编辑磁盘上的 Cocos 项目源文件，而不是只修改浏览器 runtime。
4. Headless Cocos 编译后通过 HMR 刷新 iframe。
5. 从当前 DSH Workspace 检测 Cocos 项目，检测依据是 package.json，并启动 preview。
6. 支持从本地 headless-cocos checkout 选择 base-ai 2D 或 base-ai-3d 模板。
7. 提供以下 DSH tools：

kurenai_project_initialize
kurenai_project_current
kurenai_preview_start
kurenai_preview_status
kurenai_preview_stop
kurenai_publish

8. 支持 headless static publish，当前为 platform=web MVP，可扩展。

安装与启用¶

下面是开发构建安装路径。先做依赖安装和检查：

npm install
npm run check

然后安装到指定 DSH profile。下面命令中的 <profile> 和 <absolute-path-to-this-repo> 需要替换为实际值：

dsh plugin --profile <profile> add <absolute-path-to-this-repo>

安装后，配置生成的 Cordis 行。这里的 id、name、port 和 controlPort 是已给出的配置项：

- id: kurenai
  name: "@kurenai-studio/dsh-plugin-kurenai"
  config:
    port: 7460
    controlPort: 7459

Kurenai 需要外部 Headless Cocos 栈。通过 KURENAI_HEADLESS_ROOT 指向本地 headless-cocos checkout 或 runtime kit：

KURENAI_HEADLESS_ROOT

项目路径始终读取当前 DSH session cwd。历史预览研究树 shinjiyu/headless-cocos 已迁移或只读，不要把它当作产品主仓库。

典型用法¶

新建项目¶

创建或打开一个空 DSH Workspace，然后从本地 headless-cocos checkout 选择模板：

base-ai
base-ai-3d

其中 base-ai 是 2D 模板，base-ai-3d 是 3D 模板。

已有项目¶

把现有 Cocos 项目目录作为 DSH Workspace 打开。Kurenai 会从 package.json 检测 Cocos 项目，并启动 preview。

继续工作¶

重新打开现有的 DSH Workspace/session。DSH 保持项目路径、最近工作区和会话的 source of truth。

调用 DSH tools¶

在 DSH 会话中可使用这些 tools：

kurenai_project_initialize
kurenai_project_current
kurenai_preview_start
kurenai_preview_status
kurenai_preview_stop
kurenai_publish

无 Creator 发布¶

kurenai_publish 对应 headless static publish，当前支持 platform=web MVP。没有 Creator 时，可使用本地 Headless Cocos 栈中的 CLI：

node $env:KURENAI_HEADLESS_ROOT\spike\publish\cli.mjs --project=<cocos-project> --platform=web

适用场景与注意¶

适合在 DSH 中做 Cocos 客户端开发，并且希望“看到节点、选中节点、让 agent 改代码、再刷新预览”保持在同一工作流里的开发者。

使用前需要特别注意：

• 插件会以当前 dsh 进程权限运行。安装前应检查源码、依赖和许可证。
• 当前是 working MVP，Kurenai 直接使用每个 DSH 会话的 workspace 目录作为 Cocos 项目根目录。
• DSH 没有暴露原生 center-split slot；Kurenai 通过 additive shell.overlay slot 挂载，并在打开时临时保留右侧 frame padding。
• 节点选择可以复制结构化上下文块；直接插入当前 DSH composer 仍需受支持的 conversation API adapter。
• 初始 canvas picking 只针对 2D UITransform bounds；camera-aware 3D raycasting 和复杂多相机场景未实现。
• 运行时套件和 Cocos engine binaries 不随仓库分发。需要遵循 Headless Cocos runtime-kit 指令和 Cocos 许可证要求。
• Kurenai 源码为 MIT；Cocos Creator engine snapshots、packer binaries 和其他 vendor assets 保持各自许可证。
• 插件的 peerDependencies 有版本要求，包括 @deepseek-ai/cordis ^4.0.1、DSH client runtime/UI slots 的版本范围，以及 react >=18。具体范围以仓库 package.json 为准。

结尾¶

Kurenai 的价值，是把 DSH 会话、Headless Cocos 预览、runtime inspector 和磁盘源码编辑接到一起，适合需要把 Cocos 节点选择转成 agent 上下文、再让 agent 修改项目文件的开发场景。

GitHub：

https://github.com/kurenai-studio/kurenai

目录页线索：

https://www.skillhub.cn/plugins/kurenai-studio/kurenai

社区目录是独立站点，与 DeepSeek / 幻方没有官方从属关系，不应把它理解为官方应用商店。