导入项目、模板库与共创入口
本页解决什么问题：帮你把已有工程安全导入陶泥工坊，正确使用模板，并分清“导入项目”“使用模板”和“从平台作品开始共创”。
三种进入方式不是一回事
| 入口 | 来源 | 是否复制平台作品 | 常见用途 |
|---|---|---|---|
| 导入项目 | 你电脑上的已有工程目录 | 否 | 继续开发自己的 Vite、Unity、Cocos、Godot 或纯 HTML 工程 |
| 使用模板 | 模板库中的官方模板 | 否 | 从可运行骨架开始新项目 |
| 开始共创 | 平台上已公开且作者允许共创的作品 | 是 | 复制整份工程，在副本上继续改造 |
从公开作品开始共创的确认页和授权规则见开始共创与作品族谱。
导入已有项目
操作步骤
- 打开左侧“项目组”。
- 点“导入项目”。
- 在系统目录选择器中选择工程目录。
- 等待客户端识别布局。
- 如果出现“识别项目布局”弹窗，阅读识别结果并选择要使用的布局。
- 点“导入”确认。
- 导入完成后进入项目工作台。
导入确认会写入项目的 .agent 元数据，所以即使只识别到一个候选，也需要你点一次确认。取消不会写入布局，也不会把项目登记进最近项目。
支持的目录
客户端当前会识别这些工程：
| 类型 | 识别方式 | 导入后 |
|---|---|---|
| Vite Web 工程 | 根目录或四层以内子目录中的 Vite 工程 | 直接作为 Web 项目打开 |
| Unity 工程 | 目录中有 Unity 工程结构 | 保留原引擎工程并建立陶泥工坊项目记录 |
| Cocos Creator 工程 | 目录中有 Cocos 工程结构 | 保留原引擎工程并建立项目记录 |
| Godot 工程 | 目录中有 Godot 项目文件 | 保留原引擎工程并建立项目记录 |
| 纯 HTML 工程 | 有 HTML 入口，但没有可运行的 Vite 配置 | 先导入，再进入“转换为 Vite 工程”流程 |
如果目录“读不了”“没有入口”或“不是 Vite 工程”，识别弹窗会给出原因。没有可用候选时不会显示“导入”按钮，只能取消并换一个目录。
多个候选怎么选
一个目录里可能包含多个可运行的 Web 工程。识别弹窗会列出候选，要求你选择本次使用的那个。
- 候选很多时只展示前一批，建议直接选择更具体的项目子目录。
- 选择后点“导入”。
- 不要选择包含多个项目的大目录后再猜；后续运行和导出只会围绕选中的工程根。
.agent/layout.json 与布局变更
客户端把识别结果记录在项目的 .agent/layout.json。它的作用是记住“真正的工程根在哪里”，例如根目录、game/ 或某个子目录。
以下动作会触发布局确认：
- 第一次导入项目时。
- 运行或导出因布局不匹配失败后，客户端重新识别当前目录时。
如果工程结构发生了变化，例如把 game/ 移到根目录、删除了原入口或更换了构建配置，运行失败后会弹出“项目结构已变化”：
| 选择 | 含义 |
|---|---|
| 更新项目配置 | 采纳这次识别到的新布局，写入 .agent/layout.json |
| 暂不更新 | 保留旧配置，继续留在项目里；下一次运行失败仍可能再次提示 |
打开项目本身不会立刻判定布局漂移。只有运行或导出以布局失败收场后，才会进入这条确认流程。布局弹窗通常用底部按钮或点遮罩关闭，不依赖 Esc。
布局配置只描述工程根，不包含你的源码内容。选择“更新项目配置”不会删除源码，但如果选错根目录，后续运行可能找不到入口。确认前看清“原配置”和“新配置”。
纯 HTML 项目转 Vite 的边界
纯 HTML 项目不是一个可以直接长期运行和发布的标准工程。导入时会出现“识别到纯 HTML 工程”：
- 选择要转换的 HTML 目录和入口。
- 点“导入并转换”。
- 进入“转换为 Vite 工程”面板，阅读转换前说明。
- 在右侧转换对话中检查或修改陶泥儿准备好的提示词、模型和说明。
- 点“检查”确认目录已经能识别为 Vite 工程。
- 在随后的布局确认中选择工程根并确认，项目才会作为 Vite 工程继续使用。
这不是一键自动迁移，也不是无条件接受任意 HTML 站点：
- 多个 HTML 入口时，必须先选一个待转换目录。
- 转换由独立的对话线程完成，关闭面板后下次重新打开会重新开始。
- 转换进行中退出会弹出确认，可选择继续或“终止 code agent 并退出”。
- 原有单 HTML 工程不会被后台悄悄改成 npm 工程；必须经过这条转换链路。
如果只是临时试玩旧 HTML，没有转换需求，不要把它当作已完成的正式项目。
使用模板库
模板库入口在左侧栏，只有当前账号已开放时才显示。
搜索与筛选
- 搜索框支持模板名称、玩法、标签和引擎等关键词；多个关键词按“同时包含”匹配。
- “运行时”可按网页、Unity、Godot、Cocos 等筛选。
- “标签”可以多选，选中后显示与标签数量。
- “仅看已下载”只保留本机已有模板。
- 有筛选条件时会出现“清除筛选”。
下载、更新与使用
| 卡片动作 | 行为 |
|---|---|
| 下载 | 从模板库获取模板并安装到本机 |
| 更新 | 本机已有旧版本，重新下载到当前模板版本 |
| 使用模板 | 缺包时先下载，然后用模板自动创建项目并进入工作台 |
卡片上的“已下载”表示本机已有同版本模板；版本落后时仍会提供“更新”。下载和创建过程中按钮会显示进度，短时间内不要重复点击。
模板创建的项目同样落在“项目创建目录”下。使用前建议先确认设置里的工作区目录。
当前限制
- 模板清单来自平台，可能受账号、登录状态或发布灰度限制。
- 清单读取失败时页面会显示错误和重试；页面可能先展示本机缓存。
- 模板是起点，不代表已经完成你的玩法、素材或发布配置。
从平台作品开始共创
如果你看到的是平台上的公开作品，而不是电脑上的工程，入口是作品详情页的“开始共创”，不是项目组的“导入项目”。
关系可以这样理解：
- 你在网页端打开作品详情，点“开始共创”。
- 平台唤起陶泥工坊的“开始共创”确认页。
- 确认授权和工程同步后，客户端复制整份工程到你自己的项目。
- 复制完成后进入工作台，副本独立，不影响原作者。
客户端没有额外的“共创列表页”，深链是这条确认页的主要入口。作品未公开、已删除、作者禁止共创或没有工程源包时，客户端会给出对应失败原因。
使用模板不会产生作品族谱；开始共创会记录来源和原作者。两者不要混用。
常见失败
| 现象 | 原因与处理 |
|---|---|
| 目录没反应 | 目录不存在、无权限或不是文件夹；换一个目录重试 |
| 无法识别布局 | 当前目录不是 Vite/引擎工程，或入口被移动；重新选择更具体的子目录 |
| 导入后运行失败 | 可能是布局错误或依赖未安装；按失败面板重新识别或修复依赖 |
| 纯 HTML 转换后仍不能运行 | 检查转换面板的“检查”结果，按失败项继续和陶泥儿修正 |
| 模板按钮不可用 | 当前账号未开放模板库，或清单/下载失败；检查登录和网络 |
| 共创失败 | 检查作品是否公开、作者授权、是否有工程源包，以及当前账号是否登录 |