创作空间 / Creation Space

面向 AI 影像创作的本地优先工作台：从文字设定、视觉资产到无限分镜画布，把故事资料、镜头关系和 AI 共创流程放进同一个项目空间。

创作空间是一个为导演、编剧、分镜师和 AI 影像创作者设计的开源工具。它不把“资产库”和“分镜画布”割裂开：世界观、剧本、人物、场景、道具与参考资料可以先以文字资产沉淀，再提炼为视觉资产，最后作为可追溯的引用进入镜头和时间轴。

当前版本以 macOS 本地版为主要使用方式，服务只监听 127.0.0.1，项目结构保存在本机数据库，图片、文档和可恢复清单保存在用户选择的项目文件夹中。

项目状态： v0.1.0，可用于真实项目，但仍处于快速迭代阶段。重要项目请同时备份素材文件夹和兼容数据目录。

核心能力

• 无限分镜画布：镜头节点、资产节点、分组、连线、框选、批量删除、缩放与惯性拖动。
• 资产结构：世界观、剧本、角色、场景、道具和参考资料；文字资产与视觉资产分层管理。
• 视觉创作：把主体设定、补充文字、参考图、候选图与完整提示词组织为节点式视觉任务，并保留候选来源。
• 镜头生产链路：把资产拖入画布并连接到镜头，关系类型和继承来源会随项目数据保存。
• 时间轴与制作表：镜头顺序、时长、状态、景别、运动、对白和备注共享同一份画布文档。
• 本地优先：D1/SQLite 保存结构数据，项目文件夹保存素材与 project.jingyu.json 恢复清单。
• AI 共创工作区：每个项目可生成可读的 Markdown/JSON 投影；AI 通过受控同步、版本条件和审计记录修改内容。
• 并发安全：画布和资产写入带版本校验；多个编辑窗口发生冲突时保留本地意图，不静默覆盖。

完整功能说明见 docs/FEATURES.md，数据与同步设计见 docs/ARCHITECTURE.md。

快速开始

环境要求

• macOS（本地桌面启动器当前只支持 macOS）
• Node.js >= 22.13.0
• Google Chrome（本地文件夹授权依赖 File System Access API）

从源码运行本地版

git clone https://github.com/pengkain-ctrl/creation-space.git
cd creation-space
npm install
npm run local:start

本地版会构建并打开 http://127.0.0.1:43127。停止服务：

npm run local:stop

打开兼容数据目录：

npm run local:data

仓库根目录也提供 创作空间.app、关闭创作空间.app 和 打开创作空间数据.app 三个可移植的 macOS 启动器。克隆完成后可直接双击；如 macOS 阻止首次运行，可在“系统设置 → 隐私与安全性”中允许该本地脚本。

Web 开发模式

npm install
npm run dev

常用检查：

npm run build
npm run lint
npm test

使用流程

1. 新建项目或导入已有的本地项目文件夹。
2. 在资产库建立世界观、剧本、人物、场景与道具的文字设定。
3. 从文字资产创建视觉子资产，上传参考图、候选图和对应提示词。
4. 在分镜画布中建立镜头，把已有资产拖入画布并连接到目标镜头。
5. 在时间轴和制作表中整理顺序、时长、状态、对白与制作备注。
6. 将整个项目素材文件夹纳入 Time Machine 或其他备份系统。

AI 共创

本地服务会为项目生成 AI工作区。AI 可以编辑项目说明、已有资产正文和镜头语义字段，也可以通过正式命令录入图片与提示词；数据库、内部 ID、revision、画布几何、.jingyu/ 和 project.jingyu.json 仍由系统管理。

npm run local:ai:status

npm run local:ai:import-image -- \
  --project-id "项目 UUID" \
  --parent-asset-id "文字资产 UUID" \
  --file "/absolute/path/reference.png" \
  --name "角色视觉方向 A" \
  --prompt "生成这张图时使用的完整提示词"

设计原则是：AI 可以绕过界面操作，但不能绕过数据规则。 所有正式写入都经过身份校验、版本条件、幂等处理和操作审计。

数据与隐私

• 本地服务默认只绑定 127.0.0.1:43127。
• 仓库不包含任何用户项目、图片、数据库、运行日志或 project.jingyu.json。
• 为兼容早期版本，本地数据根目录仍使用 ~/Documents/镜域本地数据；这只是稳定的内部路径，不影响产品名称。
• 请勿手工编辑兼容数据目录中的数据库文件，也不要把真实项目数据提交到公开仓库。

技术栈

• React 19 + TypeScript
• Vinext + Vite
• Cloudflare Workers compatible runtime
• D1 / SQLite + Drizzle ORM
• R2-compatible object storage
• Node.js 本地启动器与 AI 工作区桥接器

项目结构

app/        UI、画布模型与 API 路由
db/         Drizzle schema
drizzle/    数据库迁移
local/      本地启动器、AI 工作区与命令行工具
tests/      模型、API、同步、安全与运行时测试
public/     产品图与静态资源
docs/       功能和架构说明

参与贡献

欢迎提交 Issue 和 Pull Request。开始前请阅读 CONTRIBUTING.md；安全问题请按 SECURITY.md 私下报告。

许可证

本项目使用 MIT License。