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 会保留仓库原有配置，后续提交仍需用户或智能体补齐提交身份。
执行模式
在本地 workspace 项目的新对话输入区，可以选择任务使用哪种工作目录。项目可以来自“从 Git 克隆”，也可以来自“使用现有目录”；只要该目录当前是 Git 仓库，就可以使用新工作树。
- “本地模式”/“在本地处理”：任务直接进入项目绑定的目录，例如
projects/<repoKey>/<repoName>或用户选择的已有目录。 - “新工作树”：发送新任务前，Wegent 会在同一执行设备上运行
git worktree add，为这次任务创建独立工作树。选择“新工作树”后，输入区会显示“启动分支”下拉框；默认使用当前分支，也可以选择同一仓库中的其他分支作为创建工作树的来源。
新工作树会创建在执行设备 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 中，打开右侧工作区面板后，可以只读浏览当前任务或项目的文件。文件树会从当前绑定的执行设备读取工作区目录；已有任务优先使用任务工作区，新对话优先使用当前项目工作区。
文件预览区不会保存或修改文件。你可以在预览区选中一段代码并添加本地评论，评论会作为上下文附件显示在左侧输入框上方，例如“1 个评论”。发送下一条消息时，Wework 会把文件路径、行号范围、选中的代码和评论内容一起加入请求上下文，帮助智能体理解你指向的代码位置。
当当前任务使用“新工作树”时，右侧文件树、底部终端、macOS App 内嵌本地终端和云设备 IDE/code-server 都会使用任务记录的工作树路径。没有当前任务或任务没有工作树路径时，项目工具才使用项目工作区目录。
代码评论上下文不会上传为普通文件，也不会占用 attachment_ids。如果只添加了代码评论但没有输入正文，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 服务 |