Git 项目
Git 项目用于把一个远程仓库克隆为 Wework 左侧项目列表中的项目工作区。创建后，同一个项目下的新对话会复用同一份本地代码目录，适合围绕同一仓库连续开发、排查和验证。
前置条件
- 本地或云端执行设备处于在线状态。
- 已在设置中配置可访问目标仓库的 Git Token。
- 目标仓库和默认分支对当前账号可见。
- 执行设备能够访问 Git 服务地址。
从 Git 克隆项目
- 在 Wework 左侧栏的“项目”标题右侧点击新建按钮。
- 选择“从 Git 克隆”。
- 在弹窗中选择执行设备。
- 选择 Git 仓库。
- 选择默认分支。
- 点击“创建项目”。
弹窗会先打开，再异步加载仓库和分支数据。仓库加载期间，仓库选择框会显示“正在加载仓库...”。
目录规则
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 会保留仓库原有配置，后续提交仍需用户或智能体补齐提交身份。
执行模式
协作项目的任务工作区
在协作项目的「管理 → 执行环境 → 环境配置」中选择「任务工作区」：
- 独立工作树（推荐）：Git 项目的新任务使用独立 worktree。工作树准备失败会明确报错，不会静默改为共享目录。无代码仓库的空白环境直接使用环境目录。
- 共享项目目录：新任务直接使用项目环境目录。并行修改可能相互覆盖，请谨慎选择。
这项设置属于项目，不属于机器人或模型运行配置。修改只影响新任务，不迁移已有任务，也不要求重新克隆仓库或初始化环境。同一任务的后续消息继续使用原工作区。工作流明确继承上一阶段工作区时保留继承关系。
「设置 → 工作树」管理的是设备上的目录和回收策略，不决定协作项目是否隔离执行。「归档并回收」需要确认：它会停止并归档关联对话、保存快照并回收目录。快照不包含 Git 忽略的文件，例如依赖和构建产物。源仓库仍可用时，可以通过「恢复工作树」恢复目录；恢复本身不会继续运行任务。
在本地 workspace 项目的新对话输入区，可以选择任务使用哪种工作目录。项目可以来自“从 Git 克隆”，也可以来自“使用现有目录”；只要该目录当前是 Git 仓库，就可以使用新工作树。
- “本地模式”/“在本地处理”：任务直接进入项目绑定的目录，例如
projects/<repoKey>/<repoName>或用户选择的已有目录。目录是 Git 仓库时，输入区会显示当前分支下拉框；选择其他分支后，Wegent 会在项目目录执行git checkout <branch>。如果 Git 因本地未提交修改、未跟踪文件覆盖或其他冲突拒绝切换，当前分支和本地修改会保持不变，并在菜单中显示错误。 - “新工作树”：Wegent 会为任务预留独立工作树路径，并在任务获得执行并发槽位后，在同一执行设备上运行
git worktree add。如果并发槽位已满，任务会先进入队列，此时不会提前创建目录或占用 Git 工作树锁。选择“新工作树”后，输入区会显示“启动分支”下拉框；默认使用当前分支，也可以选择同一仓库中的其他分支作为创建工作树的来源。
发送使用“新工作树”的任务后，Wework 会保留并展示用户刚发送的消息，同时显示工作树搭建动画：提交节点从主线分出新支线，并展开为独立代码工作区；阶段提示会依次说明定位提交、创建分支、展开工作区和整理文件。此时对话输入区会暂时隐藏，避免用户在隔离目录尚未准备好时继续操作。创建阶段不会提前显示“正在思考”；工作树创建完成后，任务会自动开始并进入正常对话界面，无需再次发送。系统开启“减少动态效果”时，动画会切换为静态状态。
Wework 会在任务运行期间后台刷新仓库环境。刷新不会隐藏输入区中已经解析出的当前分支；只有首次读取工作区时才会显示加载状态。
切换任务时，如果“环境信息”已固定展开，面板会直接显示新任务对应的环境，不会播放打开或滑入动画。只有用户点击右上角的“环境信息”按钮显式展开或收起面板时，才会显示该交互动画。
新工作树会创建在执行设备 workspace 根目录下：
~/.wecode/wegent-executor/workspace/worktrees/<taskId>/<projectName>
工作树 ID 使用任务 ID。任务会记录执行目录来源 git_worktree 和创建后的绝对工作树路径，用于后续打开文件、终端、IDE/code-server 和管理工作树；选择的启动分支只用于本次 git worktree add --detach <path> <branch>，不会作为任务字段重复保存。工作树设置页展示执行设备管理的工作树及可恢复快照。「归档并回收」会归档关联任务并回收目录；「恢复工作树」恢复目录，不自动运行任务。
任务排队期间，任务记录中保存的是确定性的计划路径；该路径对应的目录可以尚不存在。任务被强制启动、并发上限提高、前序任务结束或 Executor 重启后恢复队列时，都会先创建工作树，再启动模型执行。创建失败会使该任务进入失败状态并释放已占用的并发槽位，后续排队任务仍可继续调度。
“新工作树”只对绑定本地执行设备、本地目录且当前目录是 Git 仓库的项目新对话可选。已有任务会锁定执行目录，避免同一个任务在中途切换工作区。如果目录当前不是 Git 仓库，输入区仍显示“本地模式”，但不会显示“新工作树”和启动分支选择；后续用户手工把该目录变成 Git 仓库后，不需要修改项目配置即可重新选择新工作树。
在输入框中引用文件、文件夹和能力
选择“设置目标”后，目标模式标签会随当前会话草稿保留。在同一工作区标签页中切换到其他会话再返回时，即使尚未输入文字，标签也会恢复；其他会话不会继承此选择。将工作区标签页移到其他窗口或移回主窗口时，目标模式也会随草稿一起移交。取消目标模式会保留草稿文字，再次切换回来也不会重新启用目标模式。
在 Wework 对话输入框中输入 @ 会打开添加菜单。菜单可以直接设置目标、开启计划模式，或引用当前模型可用的技能和应用。继续在 @ 后输入内容时，Wework 会同时搜索当前任务工作区中的文件和文件夹；选择结果后，它会显示为蓝色标签，并保留文件名和路径原本的大小写。
点击“文件和文件夹”会打开系统文件选择器。macOS 桌面版支持一次选择多个文件和文件夹；选中的每个路径都会成为独立的蓝色标签。发送消息时，标签会还原为对应的真实路径并交给 Codex，因此既能作为上下文提示，也能让 Codex 按需读取完整内容。删除标签不会删除磁盘上的文件。
工作区搜索只在当前任务或项目绑定的执行目录内进行。系统选择器可以引用工作区外的本机路径，但只适用于能够访问这些路径的本地执行设备；远程或云端任务不能依赖用户电脑上的本地路径。历史消息会继续显示已经发送的路径引用。
使用快捷短语
Wework 输入框左下角的“快捷短语”按钮会打开本机短语列表。可以用鼠标选择，也可以在搜索框中输入关键词后用方向键移动、Enter 确认、Esc 关闭。选中后，短语会换行追加到当前草稿，不会立即发送。
在“设置 > 快捷短语”中可以新建、编辑、删除和排序短语。每条短语可设为普通、计划模式或 Goal；选择时 Wework 会同步切换到该模式。快捷短语保存在当前设备，可离线使用，不会同步到其他设备。
本地项目还可以在“项目设置 > 快捷短语”中维护项目专属短语。打开该项目的输入框时，项目短语会显示在设备全局短语之前；切换到其他项目后不会显示。系统拖拽形成的暂存项仍然是设备全局内容。
使用系统拖拽面板
macOS 桌面版默认开启系统拖拽面板。开始拖动文件、图片、网页链接或选中的文字时，Wework 会在鼠标所在显示器的屏幕顶部显示一个紧凑的置顶面板。可以将内容放到以下区域：
- 创建新对话：激活弹出窗口并把内容追加到新任务草稿；已经位于新任务时，不会覆盖已有草稿。
- 追问：仅在弹出窗口已有对话时显示，并把内容追加到该对话的输入框。
- 临时暂存：把本次拖入的内容保存到快捷短语菜单顶部的暂存区。
只有实际拖动内容并在面板上松开鼠标时才会执行投递；单击面板区域不会创建对话、追问或暂存内容。
暂存区以横向附件卡片显示内容；多个文件会堆叠显示，图片显示缩略图。可以横向滚动、悬停预览、删除单项，或选择暂存项把文字和附件追加到任意对话的输入框。暂存内容最多保留 7 天，过期后会自动清理；也可以点击暂存区右上角的“清空”一次删除全部暂存项，普通快捷短语不会受影响。网页链接会同时保留页面标题和 URL。拖拽投递会激活弹出窗口，不会打开或激活主窗口。可在“设置 > 通用 > 弹出窗口 > 系统拖拽面板”关闭或重新开启此功能。
提交和推送更改
在桌面版 Wework 中，打开右上角“环境信息”，然后点击“提交或推送”，可以在当前任务或项目的实际工作目录中执行以下操作：
“环境信息”会显示当前分支相对于其主分支的累计文件数和增删行数。点击变更统计可审查这两个分支之间的完整 diff，因此已提交但尚未合并的分支更改也会显示；未跟踪文件仍会计入统计和审查结果。
任务运行期间，Wework 会在后台定期刷新变更统计，并在任务结束时立即刷新一次。手动重新打开或刷新“环境信息”会直接读取工作区的最新 Git 状态，不会继续显示短时间缓存中的旧统计。
- “提交”：暂存全部已跟踪和未跟踪的更改，然后创建本地提交。
- “提交并推送”：先创建本地提交，再推送当前分支。
- “推送”：不创建新提交，只推送当前分支。
提交信息可以手工填写。留空时，Wework 会先确认暂存区确实存在变更，再通过应用的文本生成服务根据暂存差异生成一行提交信息；没有可提交的更改时不会调用 AI，而是直接显示错误。生成优先使用设置中的标题生成模型，未配置时使用可用模型，并复用应用的模型路由和认证。生成超过 60 秒会取消请求；模型不可用、认证失败或返回无效信息时，不会继续提交或推送，可以手工填写提交信息后重试。
推送始终将当前本地分支发布到 origin 上的同名分支，并为它设置 upstream，相当于：
git push -u origin <current-branch>
因此，即使本地分支之前错误地跟踪了 master 或其他名称的远端分支，Wework 也不会把当前提交推送到那个旧 upstream。detached HEAD 状态下无法确定分支名，推送会被拒绝并显示错误。提交信息生成、提交和推送期间，“环境信息”会显示当前进度；Git 或模型返回的错误会保留在面板中供排查。
浏览工作区文件并添加代码评论
在桌面版 Wework 中，打开右侧工作区面板后，可以只读浏览当前任务或项目的文件。文件树会从当前绑定的执行设备读取工作区目录；已有任务优先使用任务工作区，新对话优先使用当前项目工作区。
对于绑定本机 macOS 设备的项目，项目行的更多菜单会显示“在 Finder 中显示”。点击后会在 Finder 中打开该项目目录，不会改变当前 Wework 任务。
文件预览区不会保存或修改文件。你可以在预览区选中一段代码并添加本地评论，评论会作为上下文附件显示在左侧输入框上方，例如“1 个评论”。发送下一条消息时，Wework 会把文件路径、行号范围、选中的代码和评论内容一起加入请求上下文，帮助智能体理解你指向的代码位置。
当助手回复、Codex 参考或记忆引用中包含带行号的文件链接时，点击链接会打开右侧文件预览，并滚动和高亮对应行号范围。没有行号的文件链接仍会打开对应文件，不会自动选择代码行。阅读长对话中间的内容时，打开或关闭文件面板、拖动分栏以及缩放窗口仍会正常调整对话宽度；Wework 会在重新排版后保持视口第一行的屏幕位置，避免打断当前阅读位置。
同一个文档同时出现在助手正文链接和下方参考卡片中时，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 会作废删除前发起但尚未完成的云端刷新和远程项目同步，避免旧请求把已删除项目重新写回侧栏。后续列表以 Executor 和云端返回的当前项目状态为准。
通过“使用现有目录”创建 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 服务 |