红茧工坊 kurenai-studio/kurenai

Kurenai Studio

基于 cocos-cli 的 Cocos 氛围编程：每个项目的实时预览、运行时场景检查器，以及供编码代理使用的命令行。

状态：已从 DSH 插件和历史遗留的 headless-cocos 技术栈迁移。
预览运行 cocos-cli 自带的运行时、资源数据库和脚本打包器。代理使用 kurenai CLI；没有 MCP 服务器。
参见 docs/cocos-cli-migration.md。

产品循环

代理在 assets/ 下写入文件（预制体、材质、TypeScript 视图） → cocos 宿主监听器 → 资源数据库刷新（.meta、导入、编译） → cocos-cli 实时重载刷新预览 → 代理通过 kurenai asset info / kurenai logs 读取 uuid 和错误

预制体描述结构和外观，不携带脚本；代码按路径加载它们，并通过
addComponent(View).bind(root) 附加行为。.meta 文件
始终由引擎写入。代理遵循的规则位于 templates/shared/AGENTS.md，会复制到每个新项目中。

组成部分

- bin/kurenai.mjs — CLI（见下文）。
- bin/kurenai-cocos-host.mjs — 每个项目一个长期运行的进程。加载 cocos-cli，启动其游戏预览，监听 assets/（或使用
WATCH_POLL=1 轮询），并暴露 /__kurenai/status、/__kurenai/refresh、
/__kurenai/asset 和 /__kurenai/logs。它会在 /temp/kurenai-host.json 中公布自身。
- src/preview/controller.ts — 启动宿主（或附加到 CLI 已启动的宿主），并将 PreviewBridge 置于其前面。
- src/preview/bridge.ts — 反向代理，注入检查器并让每个预览请求都保持在桥接源上。
- src/project/control.ts — 项目检测、模板初始化、选择上下文，以及通过 cocos build 发布。
- src/inspector-runtime/ — 用于场景树、选择和 2D 命中测试的浏览器运行时。
- templates/ — base-ai（2D）和 base-ai-3d 项目模板，以及 shared 层（Boot 入口、辅助函数、AGENTS.md）。

要求

- Node.js 22+
- 一个 cocos-cli 安装。默认为 ~/Library/Application Support/cocos-default/cocos-4.0.0-alpha.33（由 PinK 安装）；可通过 KURENAI_COCOS_CLI_ROOT 或 cocosCliRoot 选项覆盖。
宿主使用 cocos-cli 内部实现（dist/core/*），因此请保持版本固定。

安装

未发布到 npm；请从 GitHub 安装：

git clone https://github.com/kurenai-studio/kurenai.git
cd kurenai
npm install
npm link # 可选：将 kurenai 放入 PATH

lib/ 已提交，因此使用 CLI 无需构建步骤。

CLI

kurenai init ./my-game --template base-ai-3d
cd my-game
kurenai host start # 后台预览宿主；打印预览 URL kurenai asset info assets/resources/materials/red.mtl # 引擎分配的 uuid、子资源 kurenai logs --errors # 编译错误和浏览器控制台 kurenai context # 项目状态 + AGENTS.md kurenai publish --platform web-desktop --out ./dist kurenai host stop

需要 host 的命令会在其未运行时启动它。输出为 JSON。

拼图演示（M2 验收）

从干净的克隆开始，node scripts/run-puzzle.mjs 会创建一个临时 2D 项目（base-ai），写入生成的 assets/resources/images/puzzle.png、一个无脚本的 PuzzleTile 预制体，以及 MainView / PuzzleTileView（3×3 切片交换，直到图片恢复原状）。它会对该图片和预制体运行 kurenai asset info（打印 uuid），然后启动预览 host。

host 启动后手动检查：打开打印出的 previewUrl，点击一个切片再点击另一个以交换切片；当九个切片全部处于正确顺序时，状态行会显示 Complete!

选项：--dir 用于指定固定的项目目录，--no-host 跳过 host，--cleanup 在完成时移除临时项目（并停止 host）。相关脚手架：issue #8（run-puzzle.mjs 入口点）。

Host 基准测试（RSS / 就绪时间）

node scripts/bench-host.mjs 会初始化一个临时项目（默认 base-ai-3d），运行
kurenai host start，打印包含就绪所需墙钟时间和 host 进程 RSS（通过 ps）的 JSON，然后停止 host。需要本地安装 cocos-cli；如果缺少 cocos-cli，脚本会以 JSON 错误退出，并且不会写入日志文件。传入 --concurrent 可在端口 7460/7461 上启动两个 host（有用但在高负载下可能不稳定）；--cleanup 会移除临时目录。

库 ts
import { ProjectControl } from "@kurenai-studio/kurenai";

const control = new ProjectControl({ scene: "db://assets/main.scene" });
await control.initialize("/path/to/new-game", "base-ai-3d");
const preview = await control.startPreview("/path/to/new-game");
console.log(preview.url); // 注入了 inspector 的 bridge URL

await control.publish("/path/to/new-game", { platform: "web-desktop" });
await control.stopServer(); // 停止 bridges 及其启动的任何 hosts

开发 sh
npm install
npm run check

CI 会在向 main 发起的 pull request 上运行 npm run check（见 .github/workflows/check.yml）。

Agent 集群

并行 worker 会认领标记为 swarm:available 的 GitHub issue。认领、分支、PR 和 manager 审查规则见 docs/SWARM.md。

限制

- 在 Docker 中（bind-mount 的项目目录），请在 cocos host 上设置 WATCH_POLL=1；见 docs/docker-watch-poll.md。
- Canvas 拾取针对 2D UITransform 边界；未实现 3D 射线投射。
- 从代码创建的材料只能使用 builtin-unlit；对于受光照材料，请编写 .mtl 文件。
- 发布支持 web-desktop 和 web-mobile。
- 每个预览 host 都是一个完整的 cocos-cli 进程（约数百 MB RSS）；在你的机器上使用 node scripts/bench-host.mjs 以获得可重复的数字。

许可证

Kurenai 源代码采用 MIT 许可证。cocos-cli、Cocos 引擎及其他供应商资产不属于本仓库，并仍受其各自许可证的约束。