Git 项目

Git 项目用于把一个远程仓库克隆为 Wework 左侧项目列表中的项目工作区。创建后，同一个项目下的新对话会复用同一份本地代码目录，适合围绕同一仓库连续开发、排查和验证。

前置条件

• 本地或云端执行设备处于在线状态。
• 已在设置中配置可访问目标仓库的 Git Token。
• 目标仓库和默认分支对当前账号可见。
• 执行设备能够访问 Git 服务地址。

从 Git 克隆项目

1. 在 Wework 左侧栏的“项目”标题右侧点击新建按钮。
2. 选择“从 Git 克隆”。
3. 在弹窗中选择执行设备。
4. 选择 Git 仓库。
5. 选择默认分支。
6. 点击“创建项目”。

弹窗会先打开，再异步加载仓库和分支数据。仓库加载期间，仓库选择框会显示“正在加载仓库...”。

目录规则

Git 项目会克隆到执行设备的项目根目录下：

~/.wecode/wegent-executor/workspace/projects/<repoName>

例如仓库名为 pluto 时，最终目录是：

~/.wecode/wegent-executor/workspace/projects/pluto

任务执行时也会进入同一个目录。也就是说，项目创建阶段的 git clone 目录和后续任务的工作目录保持一致。

克隆成功后，Wegent 会根据当前用户匹配该仓库域名的 Git 账号信息，在仓库本地写入提交身份：

git config user.name <git_login>
git config user.email <git_email>

这只影响该项目仓库的 .git/config，不会修改执行设备的全局 Git 配置。如果当前用户没有完整的 Git 登录名和邮箱，Wegent 会保留仓库原有配置，后续提交仍需用户或智能体补齐提交身份。

执行模式

在本地 workspace 项目的新对话输入区，可以选择任务使用哪种工作目录。项目可以来自“从 Git 克隆”，也可以来自“使用现有目录”；只要该目录当前是 Git 仓库，就可以使用新工作树。

• “本地模式”/“在本地处理”：任务直接进入项目绑定的目录，例如 projects/<repoKey>/<repoName> 或用户选择的已有目录。目录是 Git 仓库时，输入区会显示当前分支下拉框；选择其他分支后，Wegent 会在项目目录执行 git checkout <branch>。如果 Git 因本地未提交修改、未跟踪文件覆盖或其他冲突拒绝切换，当前分支和本地修改会保持不变，并在菜单中显示错误。
• “新工作树”：发送新任务前，Wegent 会在同一执行设备上运行 git worktree add，为这次任务创建独立工作树。选择“新工作树”后，输入区会显示“启动分支”下拉框；默认使用当前分支，也可以选择同一仓库中的其他分支作为创建工作树的来源。

Wework 会在任务运行期间后台刷新仓库环境。刷新不会隐藏输入区中已经解析出的当前分支；只有首次读取工作区时才会显示加载状态。

切换任务时，如果“环境信息”已固定展开，面板会直接显示新任务对应的环境，不会播放打开或滑入动画。只有用户点击右上角的“环境信息”按钮显式展开或收起面板时，才会显示该交互动画。

新工作树会创建在执行设备 workspace 根目录下：

~/.wecode/wegent-executor/workspace/worktrees/<taskId>/<projectName>

工作树 ID 使用任务 ID。任务会记录执行目录来源 git_worktree 和创建后的绝对工作树路径，用于后续打开文件、终端、IDE/code-server 和管理工作树；选择的启动分支只用于本次 git worktree add --detach <path> <branch>，不会作为任务字段重复保存。工作树设置页会通过扫描执行设备上的 worktrees 目录展示已创建的工作树。删除工作树时，Wegent 会删除对应工作树目录，并软删除使用该工作树的任务。

“新工作树”只对绑定本地执行设备、本地目录且当前目录是 Git 仓库的项目新对话可选。已有任务会锁定执行目录，避免同一个任务在中途切换工作区。如果目录当前不是 Git 仓库，输入区仍显示“本地模式”，但不会显示“新工作树”和启动分支选择；后续用户手工把该目录变成 Git 仓库后，不需要修改项目配置即可重新选择新工作树。

在输入框中引用文件、文件夹和能力

在 Wework 对话输入框中输入 @ 会打开添加菜单。菜单可以直接设置目标、开启计划模式，或引用当前模型可用的技能和应用。继续在 @ 后输入内容时，Wework 会同时搜索当前任务工作区中的文件和文件夹；选择结果后，它会显示为蓝色标签，并保留文件名和路径原本的大小写。

点击“文件和文件夹”会打开系统文件选择器。macOS 桌面版支持一次选择多个文件和文件夹；选中的每个路径都会成为独立的蓝色标签。发送消息时，标签会还原为对应的真实路径并交给 Codex，因此既能作为上下文提示，也能让 Codex 按需读取完整内容。删除标签不会删除磁盘上的文件。

工作区搜索只在当前任务或项目绑定的执行目录内进行。系统选择器可以引用工作区外的本机路径，但只适用于能够访问这些路径的本地执行设备；远程或云端任务不能依赖用户电脑上的本地路径。历史消息会继续显示已经发送的路径引用。

使用快捷短语

Wework 输入框左下角的“快捷短语”按钮会打开本机短语列表。可以用鼠标选择，也可以在搜索框中输入关键词后用方向键移动、Enter 确认、Esc 关闭。选中后，短语会换行追加到当前草稿，不会立即发送。

在“设置 > 快捷短语”中可以新建、编辑、删除和排序短语。每条短语可设为普通、计划模式或 Goal；选择时 Wework 会同步切换到该模式。快捷短语保存在当前设备，可离线使用，不会同步到其他设备。

使用系统拖拽面板

macOS 桌面版默认开启系统拖拽面板。开始拖动文件、图片、网页链接或选中的文字时，Wework 会在鼠标所在显示器的屏幕顶部显示一个紧凑的置顶面板。可以将内容放到以下区域：

• 创建新对话：激活弹出窗口并把内容追加到新任务草稿；已经位于新任务时，不会覆盖已有草稿。
• 追问：仅在弹出窗口已有对话时显示，并把内容追加到该对话的输入框。
• 临时暂存：把本次拖入的内容保存到快捷短语菜单顶部的暂存区。

只有实际拖动内容并在面板上松开鼠标时才会执行投递；单击面板区域不会创建对话、追问或暂存内容。

暂存区以横向附件卡片显示内容；多个文件会堆叠显示，图片显示缩略图。可以横向滚动、悬停预览、删除单项，或选择暂存项把文字和附件追加到任意对话的输入框。暂存内容最多保留 7 天，过期后会自动清理；也可以点击暂存区右上角的“清空”一次删除全部暂存项，普通快捷短语不会受影响。网页链接会同时保留页面标题和 URL。拖拽投递会激活弹出窗口，不会打开或激活主窗口。可在“设置 > 通用 > 弹出窗口 > 系统拖拽面板”关闭或重新开启此功能。

提交和推送更改

在桌面版 Wework 中，打开右上角“环境信息”，然后点击“提交或推送”，可以在当前任务或项目的实际工作目录中执行以下操作：

“环境信息”会显示当前分支相对于其主分支的累计文件数和增删行数。点击变更统计可审查这两个分支之间的完整 diff，因此已提交但尚未合并的分支更改也会显示；未跟踪文件仍会计入统计和审查结果。

任务运行期间，Wework 会在后台定期刷新变更统计，并在任务结束时立即刷新一次。手动重新打开或刷新“环境信息”会直接读取工作区的最新 Git 状态，不会继续显示短时间缓存中的旧统计。

• “提交”：暂存全部已跟踪和未跟踪的更改，然后创建本地提交。
• “提交并推送”：先创建本地提交，再推送当前分支。
• “推送”：不创建新提交，只推送当前分支。

提交信息可以手工填写。留空时，Wework 会先确认暂存区确实存在变更，再调用执行设备上的 Codex 根据暂存差异生成一行提交信息；没有可提交的更改时不会调用 AI，而是直接显示错误。AI 生成需要执行设备上的 Codex 已完成认证并可正常运行。

推送始终将当前本地分支发布到 origin 上的同名分支，并为它设置 upstream，相当于：

git push -u origin <current-branch>

因此，即使本地分支之前错误地跟踪了 master 或其他名称的远端分支，Wework 也不会把当前提交推送到那个旧 upstream。detached HEAD 状态下无法确定分支名，推送会被拒绝并显示错误。提交信息生成、提交和推送期间，“环境信息”会显示当前进度；Git 或 Codex 返回的错误会保留在面板中供排查。

浏览工作区文件并添加代码评论

在桌面版 Wework 中，打开右侧工作区面板后，可以只读浏览当前任务或项目的文件。文件树会从当前绑定的执行设备读取工作区目录；已有任务优先使用任务工作区，新对话优先使用当前项目工作区。

对于绑定本机 macOS 设备的项目，项目行的更多菜单会显示“在 Finder 中显示”。点击后会在 Finder 中打开该项目目录，不会改变当前 Wework 任务。

文件预览区不会保存或修改文件。你可以在预览区选中一段代码并添加本地评论，评论会作为上下文附件显示在左侧输入框上方，例如“1 个评论”。发送下一条消息时，Wework 会把文件路径、行号范围、选中的代码和评论内容一起加入请求上下文，帮助智能体理解你指向的代码位置。

当助手回复、Codex 参考或记忆引用中包含带行号的文件链接时，点击链接会打开右侧文件预览，并滚动和高亮对应行号范围。没有行号的文件链接仍会打开对应文件，不会自动选择代码行。阅读长对话中间的内容时，打开或关闭文件面板、拖动分栏以及缩放窗口仍会正常调整对话宽度；Wework 会在重新排版后保持视口第一行的屏幕位置，避免打断当前阅读位置。

助手生成最终回复前显示的流式进度文本使用相同的文件链接行为。绝对路径不会按 Wework 页面地址解析为网页链接；点击带行号的链接时，Wework 会直接打开工作区文件并定位到对应行。

文件链接目标可以使用 Markdown 的尖括号写法，例如 [文件](</绝对路径/file.ts:18>)。Wework 会移除目标路径外层的尖括号，再按绝对路径和行号打开文件；尖括号不会成为实际路径的一部分。

使用右侧浏览器

在 macOS 桌面版 Wework 中，右侧工作区面板也可以打开浏览器标签页。点击右侧面板中的新标签页按钮后选择“浏览器”，在地址栏输入 http、https、file:// 地址或本机绝对路径即可在应用内打开网页、本地文件或本机目录。目录会显示为只读索引页，可继续进入子目录或打开其中的文件。右侧面板最多保留一个浏览器标签页；浏览器已打开时，新标签页菜单不会再显示第二个浏览器入口。无法预览的本地文件不会被下载副本，Wework 只会显示提示。

浏览器标签页会保留当前页面、地址、标题和站点图标。切换到文件或审查标签页、关闭并重新打开右侧面板、或拖拽调整右侧面板宽度时，已打开的网页不会被清空。将右侧分割线一直向右拖到边界时，右侧面板会自动折叠；再次打开后会恢复浏览器标签页。

当当前任务使用“新工作树”时，右侧文件树、底部终端、macOS App 内嵌本地终端和云设备 IDE/code-server 都会使用任务记录的工作树路径。没有当前任务或任务没有工作树路径时，项目工具才使用项目工作区目录。

用户在任务中打开的底部终端会在切换到其他任务后继续保留，回到该任务时会恢复原来的终端会话。归档或删除该任务后，Wework 会关闭并卸载该任务对应的终端会话，避免继续占用本地或远程执行资源。

代码评论上下文不会上传为普通文件，也不会占用 attachment_ids。如果只添加了代码评论但没有输入正文，Wework 会使用简短默认提示发送；如果只是上传普通文件附件且没有输入正文，消息正文仍保持为空，并使用默认会话标题。

使用现有目录

在 macOS 桌面版中，为本机设备选择“使用现有目录”会打开系统 Finder 目录选择器。如果目标是远程或云端设备，Wework 仍使用应用内的远程目录选择器，确保选中的路径属于对应执行设备。

项目添加后会立即出现在左侧项目列表中，也可以立即从项目菜单中删除，无需等待本地 Executor 完成后续同步。删除本机目录项目只会移除 Wework 中的项目记录，不会删除磁盘上的目录。

通过“使用现有目录”创建 Wework 项目时，Wegent 会按当前用户、Wework 来源、执行设备和规范化后的本地目录路径查找已有项目：

• 如果同一目录对应的项目仍然有效，Wegent 会直接选中并复用该项目，不会创建重复项目。
• 如果同一目录对应的项目之前已被删除，Wegent 会恢复该项目，并把仍记录该项目标识的历史会话恢复到项目下。
• 删除 Wework 项目只会让项目从项目列表隐藏，项目下的会话仍保留项目归属，不会进入左侧“对话”列表；再次使用同一目录创建项目时，这些会话会随项目一起恢复。

Wework 左侧“对话”列表只展示不隶属于项目的独立会话。项目会话应在对应项目下查看。

目录已存在

如果目标目录已经存在，Wegent 不会创建新目录，也不会尝试复用或覆盖已有目录。界面会提示项目目录已存在。

处理方式：

• 如果这是旧的无用目录，先在执行设备上删除或重命名该目录，再重新创建项目。
• 如果要保留旧目录，可以选择其他仓库或先调整目录名称。
• 如果目录中已有同名仓库，也需要先手动处理；Wegent 不会自动切换分支或拉取更新。

排查 Git 克隆失败

在执行设备上检查以下信息：

echo "$WECODE_HOME"
echo "$WEGENT_EXECUTOR_PROJECTS_DIR"

ROOT="${WEGENT_EXECUTOR_PROJECTS_DIR:-${WECODE_HOME:-$HOME/.wecode}/wegent-executor/workspace/projects}"
ls -la "$ROOT"

然后在项目根目录下验证仓库和分支：

cd "$ROOT"
git ls-remote --heads <git_url> <branch>
git clone --branch <branch> --single-branch <git_url> <repoName>

常见原因：

现象	可能原因
Authentication failed	Git Token 未配置、过期或权限不足
Repository not found	仓库地址错误或当前账号无权限
Remote branch not found	选择的默认分支不存在
destination path already exists	目标目录已存在
Could not resolve host 或 timeout	执行设备无法访问 Git 服务