kurenai-studio/kurenai

Kurenai Studio

DSH 原生 Cocos 氛围编程：在实时 Headless Cocos 预览旁聊天，查看
运行时场景树，点击一个节点，并将该选中项用作精确的智能体
上下文。

状态：可用的 MVP。Kurenai 直接使用每个 DSH 会话的工作区
目录作为其 Cocos 项目根目录。

历史预览研究树位于
shinjiyu/headless-cocos
（已迁移 / 只读）。将 KURENAI_HEADLESS_ROOT 指向本地检出
或运行时套件；不要将该远程仓库视为产品主仓库。

产品闭环

Click a node in the preview
→ Kurenai Inspector resolves node/path/components
→ selection becomes DSH chat context
→ agent edits the Cocos project on disk
→ Headless Cocos compiles and HMR refreshes the iframe

Kurenai 有意编辑源文件，而不是仅变更浏览器
运行时，因此更改在重新加载后依然存在，并且始终可供审查。

工作区工作流

Kurenai 不维护独立的项目注册表。

- 新项目 — 创建/打开一个空的 DSH 工作区，然后从提供的
headless-cocos 检出中选择 base-ai 2D 模板或 base-ai-3d 模板。
- 现有项目 — 将 Cocos 项目目录作为 DSH 工作区打开；
Kurenai 会从 package.json 中检测到它并启动预览。
- 继续工作 — 重新打开现有的 DSH 工作区/会话。DSH 仍然是
项目路径、最近工作区和对话的唯一事实来源。

仓库结构

- src/index.ts — DSH 宿主插件和预览生命周期工具。
- src/preview/controller.ts — 启动/停止外部 Headless Cocos 检出。
- src/project/ — 当前 DSH 工作区检测、初始化和本地
预览控制 API。
- src/client/ — DSH shell 覆盖层，将左侧的聊天与
右侧的预览/Inspector 工作区分隔开。
- src/inspector-runtime/ — 用于场景树、选中和
初始 2D UI 命中测试的浏览器运行时。
- src/shared/protocol.ts — iframe 与
DSH 之间带版本的 postMessage 契约。

当前 DSH 工具

- kurenai_project_initialize
- kurenai_project_current
- kurenai_preview_start
- kurenai_preview_status
- kurenai_preview_stop
- kurenai_publish — 无头静态发布（platform=web MVP；可通过插件扩展）

无头发布 CLI（无需 Creator）：

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

参见 headless-cocos/spike/publish/README.md。

开发

npm install
npm run check

构建后将开发版本安装到 DSH 配置文件中：

dsh plugin --profile  add

使用 Cocos 项目和本地
headless-cocos 检出配置生成的 Cordis 行：

- id: kurenai
name: "@kurenai-studio/dsh-plugin-kurenai"
config:
port: 7460
controlPort: 7459
通过 KURENAI_HEADLESS_ROOT 指向 Headless Cocos 栈。项目路径始终从活动 DSH 会话的 cwd 读取。

运行时套件和 Cocos 引擎二进制文件有意不由本仓库分发。请遵循 Headless Cocos 运行时套件说明和 Cocos 许可要求。

MVP 限制

- DSH 不提供原生的中心分栏槽位。Kurenai 通过附加的 shell.overlay 槽位挂载，并在打开时临时保留右侧框架内边距，从而保留原始对话和输入框。
- 选择节点可以复制结构化上下文块。直接插入到活动 DSH 输入框仍需要受支持的对话 API 适配器。
- 初始画布拾取针对 2D UITransform 边界。尚未实现相机感知的 3D 射线投射和复杂的多相机场景。

许可证

Kurenai 源代码采用 MIT 许可证。Cocos Creator 引擎快照、打包器二进制文件及其他供应商资源不属于本仓库，仍受其各自许可证约束。