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

何时用

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

开始前

• 这些操作都在桌面版应用中心完成。项目右键菜单可以修改列表中的显示名称，但不会修改目录、.the 文件或项目文档中的名称；应用中心也不会删除磁盘工程。选中项目后可从会话页顶栏 Build 或 Run。
• 一个有效工程的根目录必须且只能包含一个 *.the 项目文件。使用打开项目选择项目文件，使用打开文件夹选择项目或普通目录。
• 从 Git 导入需要系统中已安装 Git；新建和本地打开不需要 Git。
• 移动或删除工程目录前，先确认已有可恢复的 Git 提交或备份。

新建项目

1. 在应用中心左侧选择新建项目。
2. 输入App名称。
3. 在创建位置选择父目录。
4. 选择创建项目。Theseus 创建 <App名称>/<App名称>.the 及完整空白工程，并打开编辑器。新项目的模块列表为空，需要时再到 Settings 启用。

命令行使用同一 SDK 创建链路。在目标父目录中运行 theseus new <appName>，固定创建 ./<appName>/<appName>.the；没有父目录或项目文件名参数。

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

打开本地项目

1. 在应用中心左侧或文件菜单选择打开项目，也可按 ⌘/Ctrl+O。
2. 选择工程的 *.the 项目文件；所在根目录必须只有一个有效的项目文件。
3. Theseus 登记项目并直接打开编辑器。

Theseus 直接使用原目录，不会复制或移动工程。也可以在资源管理器、Finder 或命令行中把 .the 文件交给 Theseus 打开；新打开的项目会放到所属分区顶部，重复打开也会移到顶部。

打开项目编辑器，或在应用中心选中项目、打开该项目的会话后，Theseus 会在后台准备页面编辑环境。你可以同时继续对话，无需先打开页面才开始准备。

打开普通文件夹

在应用中心选择打开文件夹，选择本地目录后即可在该目录开始 AI 会话。普通文件夹与项目使用同一列表，支持显示名称、置顶、排序和会话恢复。

没有有效 .the 时，可以聊天、操作文件、执行命令和使用 Git，但不会显示 Build、Run 或打开编辑器，也不会启用 Theseus 项目工具和内置工程工作流。识别只检查所选目录根部；多个或损坏的 .the 会显示错误，目录仍可用于聊天。

从 Git 导入

普通 Git 仓库也可以导入，无须包含 .the；Theseus 不会递归寻找子目录工程。

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

导入成功后可直接开始 AI 会话，并在任务详情中核对分支。有有效 .the 的工程才可继续选择打开编辑器。

从侧栏管理项目

应用中心及编辑器的可拖拽分隔线在鼠标悬停和拖动时提亮，保持原有粗细；拖动可调整相邻面板大小。鼠标拖拽热区为 4px，触屏分栏保留更大的热区。

侧栏顶部紧凑排列新对话、新建项目、打开项目、打开文件夹、导入项目和学习入口，为下方项目与会话列表留出更多空间。

悬停项目或会话可查看详情卡片；深色主题下，卡片使用比页面更亮的深灰背景、细灰边框和轻阴影。项目整行高亮即时同步切换，不带颜色淡入淡出；鼠标移到右侧操作按钮，或用键盘聚焦这些按钮时，整行仍保持高亮。

深色主题下，侧栏使用炭灰底色、浅灰选中态和柔和灰色文字；分组标题与辅助信息使用更淡的文字层次。会话的悬停与选中背景覆盖整行（包括左侧缩进区域），文字保持缩进。

应用中心启动时沿用当前主题的背景色，显示静态、淡灰色的 Theseus Logo 水印，并恢复上次查看的会话；没有记录或会话已删除时进入新建会话页。项目统一在侧栏管理，标题中的项目选择器支持搜索名称和路径。

侧栏展开项目可查看历史会话，项目旁的新对话按钮可在该项目开始任务。需要完整编辑器时，右键项目选择打开编辑器，或使用项目信息卡、当前会话页顶栏的打开编辑器。

如果项目文件夹被删除或移动，项目条目仍会保留，使用原文件夹图标并置灰。项目旁的新对话按钮不可用，悬停时提示“该项目文件夹已被删除或移动”。仍可展开项目并打开历史会话，会话列表不会置灰或清空。

应用中心为每个条目记录显示名称、项目文件或目录的位置以及置顶状态，不记录打开时间。今后新建、打开或从 Git 导入的项目会移到所属分区顶部，其他项目保持相对顺序；已有列表不会批量重排。

要整理列表，在项目条目间拖拽即可调整顺序；展开项目后，也可以拖拽其中的多个 AI 会话。拖动时，条目保持原位，被拖动的条目变暗，目标插入位置显示一根细线，同时有一个显示项目图标与名称或会话标题的浮动预览跟随鼠标。拖动期间不会触发其他条目的悬停高亮、操作按钮或提示卡片；松开后才完成移动。项目顺序和每个项目的会话顺序都会持久化，不按修改时间自动重排。

在项目右键菜单中选择重命名项目可以修改列表显示名称。这不会修改磁盘上的目录名、.the 文件名或项目文档名称。选择移除项目只删除应用中心记录，也不会修改磁盘文件；以后重新打开同一个 .the 时，它会作为新条目放到列表顶部。

在应用中心左侧栏，将鼠标移到项目上并点击更多项目操作，或者直接右键项目，然后选择置顶。置顶项目会移到已置顶分区；在同一菜单中选择取消置顶可将它移回普通项目分区。置顶只改变本机项目列表的分组，不会修改工程文件。

悬停项目条目时，右侧信息卡会显示项目名、当前会话与活动状态、工作区路径和打开编辑器入口。项目折叠后如果仍有运行中、排队中或等待输入的会话，项目条目右侧会保留活动指示。

选中项目进入 AI 会话页后，左上角提供 Build 和 Run。Build 使用磁盘上已保存的工程并部署到项目绑定的 Runtime target。Run 会检查该部署是否对应已保存工程的最新 Build；不是最新时先询问是否构建并运行，确认后才依次 Build、Deploy、Run，并在新窗口打开项目首页。

等待功能包准备

打开文件夹和 Git 导入只登记目录并进入应用中心；新建项目和打开项目会打开编辑器。选中有效项目或打开编辑器后，Theseus 会按项目锁定的版本在后台准备所需内容。准备完成后，在同一次 Theseus 运行期间切回该项目或打开其编辑器会复用已准备好的环境；依赖发生变化时重新准备。

准备期间：

• Files、Source、版本和 Settings 仍可使用，普通源码可以查看、编辑和保存。
• Design、Flow 和依赖功能包的编辑能力会显示等待状态，准备完成后自动加载。

如果准备失败，右下角只短暂提示一次且可以立即关闭；等待页会保留 Restore 返回的具体错误并提供重试。不要通过反复关闭项目来掩盖错误，也不要在准备失败时交付到现场。

设置语言和外观

在应用中心打开系统设置：

• 通用：选择界面语言，管理账户、启动和更新设置。
• 外观：选择主题，以及界面字体。

打开界面字体下拉列表，从本机已安装的字体中选择。选中即保存，并立即应用到所有打开的 App Hub、Editor 和 AI 面板。选择系统默认即可恢复默认字体。未安装的字体或缺少的字符使用系统字体，不会下载字体；代码字体和运行页面不受影响。

在 Settings 中管理功能包

打开Settings → 功能包：

• 项目依赖只列出当前 App 声明的功能包和版本，不预检 lock 或本机内容；恢复直接执行 Restore，并原样报告该操作的失败。
• Registry 可按名称或 namespace 搜索固定 Theseus Registry 中的功能包，并选择明确版本执行添加。
• 检查更新只查询可用新版本；更新全部或单包更新会先下载并验证内容，再同时提交项目依赖与锁定版本。
• 移除只删除当前 App 的依赖和锁定项，不会清理其他 App 可复用的本机内容。

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

同一套能力也可从工程目录使用 CLI：

theseus package search <query> [--prerelease]
theseus package list [--outdated]
theseus package add <namespace.package>[@version] [--prerelease]
theseus package update [<namespace.package>[@version] ...] [--prerelease] [--dry-run]
theseus package remove <namespace.package>
theseus package restore [--locked]

未指定版本的添加和更新默认选择最新稳定版。--locked 不允许生成或修改 lock；项目与 lock 不一致时直接失败。

成功表现

• 新建工程可以正常进入编辑器。
• 本地打开不会改变原路径；新建或打开的项目位于所属分区顶部，已登记项目保留显示名称。
• Git 导入后，版本面板显示正确分支和远程仓库。
• 功能包准备成功后，Design、Flow 和语义功能不再显示等待或错误。
• 修改列表显示名称或移除项目后，磁盘目录、.the 文件和项目文档仍保持不变。

常见问题

打开目录后没有显示项目功能

确认选择的是工程根目录，其中必须有唯一且有效的 .the 文件。Theseus 不会递归查找子目录；多个或损坏的项目文件会显示识别错误。

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

阅读等待页保留的 Restore 原始错误并选择重试。如果仍失败，再按错误指向检查网络、Theseus Registry、项目文件或依赖锁是否来自正确提交。项目或依赖锁无效时，优先从版本控制恢复正确版本，避免猜测。

Theseus Registry 不可用

项目依赖视图仍可离线查看项目声明。搜索、检查更新、添加或更新需要访问固定 Theseus Registry；恢复锁定包时，如果本机已具备全部内容则不需要访问网络。

Git 导入持续认证失败

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

AI 可以怎么帮

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

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

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

必须人工确认

• App 名称、工程路径、Git 仓库和分支属于正确客户与项目。
• 功能包 id、版本以及对应项目元数据修改属于同一次预期变更。
• 手工移动或删除磁盘工程前，已有可恢复提交或备份。
• 准备失败的 App 不进入设备调试或生产交付。