跳到主要内容

新建、打开、导入和管理最近项目

何时用​

当你要开始新工程、从磁盘打开已有工程、克隆团队仓库，或整理应用中心的最近项目时，使用本指南。

开始前​

  • 这些操作都在桌面版应用中心完成。应用中心不提供项目改名、删除磁盘工程或打开运行页的操作。
  • 一个有效工程的根目录必须且只能包含一个 *.the 项目文件。打开项目只接受这个文件，不接受目录。
  • 从 Git 导入需要系统中已安装 Git；新建和本地打开不需要 Git。
  • 移动或删除工程目录前，先确认已有可恢复的 Git 提交或备份。

新建项目​

  1. 在应用中心左侧选择新建项目。
  2. 输入App名称。
  3. 在创建位置选择父目录。Theseus 会在其中创建一个以 App 名称命名的新文件夹。
  4. 在包含模块中按需选择运动控制和视觉；都不选就是普通项目。选中模块只创建初始配置，不会假定现场硬件。
  5. 选择创建项目。Theseus 创建完整项目并打开编辑器。

新项目不会自动初始化 Git。需要版本管理时，在编辑器的版本面板选择初始化仓库；远程仓库地址可以随后按团队流程配置。

打开本地项目​

  1. 在应用中心左侧选择打开项目。系统文件选择器会立即出现。
  2. 定位到工程根目录并选择其中的 *.the 文件。
  3. 等待编辑器窗口显示。编辑器显示后应用中心会关闭；关闭编辑器后应用中心重新出现。

Theseus 直接使用原目录，不会复制或移动工程。也可以在资源管理器、Finder 或命令行中把 .the 文件交给 Theseus 打开；成功打开后会更新同一份最近项目列表。

从 Git 导入​

仓库根目录必须是一个完整的 Theseus 项目。导入入口不会在子目录中猜测工程。

  1. 在应用中心左侧选择导入项目。
  2. 如果页面显示未检测到 Git，先选择下载 Git安装 Git for Windows，再选择重新检测。
  3. 输入仓库 URL。需要固定分支时填写分支；留空则使用仓库默认分支。
  4. 在克隆位置选择父目录。Theseus 会在其中创建以导入 App 名称命名的工程文件夹。
  5. 选择克隆并打开，等待状态从克隆进入打开项目。
  6. 如果认证失败，按页面提示填写用户名和访问令牌后重试。不要把凭据写进仓库 URL；只有在符合团队凭据策略时才启用保存到系统 Git 凭据。

导入成功后，编辑器的版本面板应显示预期分支和远程仓库。

使用最近项目列表​

应用中心只记录成功打开过的 .the 路径，并按最近打开时间排序。你可以搜索项目、切换网格或列表视图，并用以下方式再次打开：

  • 双击项目卡片或列表行。
  • 选中项目后按 Enter。
  • 使用卡片上的打开编辑器操作。
  • 在右键菜单中选择打开编辑器。

要整理列表，在项目右键菜单中选择从最近项目中移除。这只删除应用中心记录，不会修改磁盘文件；以后重新打开同一个 .the，项目会回到列表顶部。

等待功能包准备​

新建、本地打开和 Git 导入只负责建立工程与编辑器窗口，不会在应用中心恢复功能包。编辑器打开后，Theseus 才按项目锁定的版本异步准备所需内容。

准备期间：

  • Files、Source、版本和 Settings 仍可使用，普通源码可以查看、编辑和保存。
  • Design、Page Preview、Flow 和依赖功能包的编辑能力会显示等待状态，准备完成后自动加载。
  • 需要下载时，右下角任务提示会显示当前阶段和进度；本机已有所需内容时可能很快完成而不显示提示。

如果准备失败，等待页会保留具体错误，并提供重试和打开功能包设置。不要通过反复关闭项目来掩盖错误，也不要在准备失败时交付到现场。

在 Settings 中管理功能包​

打开Settings → 功能包：

  • 已安装显示当前 App 需要的功能包、安装版本和明确的问题状态，例如缺少锁定信息、版本不匹配、缺少内容或内容无效。
  • 源显示所选包源当前可安装的内容。根据当前状态使用安装、更新或切换版本；Theseus 不会静默换成另一个版本。
  • 必需功能包不能移除；可选功能包可以使用移除操作。
  • 切换到包源可以启用或停用源。内置 Theseus 源无需登录；创建或使用个人、组织包源时先登录正确的 Qixin 账号。

Theseus 自动管理功能包及其版本，不需要额外安装其他工具。功能包变更属于工程变更；提交协作仓库时，应确认项目修改完整进入同一次提交。

成功表现​

  • 新建工程可以正常进入编辑器。
  • 本地打开不会改变原路径，项目会出现在最近列表顶部。
  • Git 导入后，版本面板显示正确分支和远程仓库。
  • 功能包准备成功后，Design、Page Preview、Flow 和语义功能不再显示等待或错误。
  • 从最近列表移除项目后，磁盘目录仍保持不变。

常见问题​

文件选择器里看得到目录，却无法直接打开​

这是预期行为。返回工程根目录并选择准确的 .the 文件；不要选择目录，也不要在同一根目录保留多个 .the。

打开后提示功能包准备失败​

先保留原始错误并选择重试。如果仍失败，打开Settings → 功能包检查问题状态，再确认网络、Qixin 登录、包源可用性和项目是否来自正确提交。项目中的功能包信息无效时，优先从版本控制恢复正确版本，避免猜测。

包源不可用​

已安装视图仍可用于检查本机状态。需要下载或切换版本时，确认使用了正确 Qixin 账号、组织成员资格和可访问的包源，然后在源视图选择刷新。

Git 导入持续认证失败​

确认仓库 URL 和分支存在，访问令牌具有读取权限，并通过认证提示重试。不要把用户名或令牌嵌入 URL。

AI 可以怎么帮​

AI Command Center 只处理当前已经打开的 App，不能代替应用中心新建、打开、导入或管理最近项目。进入编辑器后，可以这样问：

只读检查当前 App 的工程结构、功能包状态和最近一次 Build 问题。列出阻止继续编辑或运行的原因和人工验证顺序，不要修改文件。

不要把 Git 凭据、私有仓库 URL 中的令牌或包源凭据发送给 AI。

必须人工确认​

  • App 名称、工程路径、Git 仓库和分支属于正确客户与项目。
  • 个人或组织包源的使用符合授权和交付要求。
  • 手工移动或删除磁盘工程前，已有可恢复提交或备份。
  • 准备失败的 App 不进入设备调试或生产交付。