前言¶

在 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 / 幻方沒有官方從屬關係，不應把它理解爲官方應用商店。