---
title: 工作区与工作目录
summary: Agent Home、项目工作区、执行根以及 worktree，以及工作区隔离的边界。
order: 50
---

# 工作区与工作目录

工作区（Workspace）为 Agent 提供项目上下文：限定生效的局部指引范围，并作为工具操作的默认目录。每个 Agent 在同一时间只能有一个活动工作区；它也可以绑定多个可用工作区，但不一定处于激活状态。

要求 Agent 修改代码仓库时，应切换到该项目的项目工作区；而 Agent 自身的角色定位与个人工作记录，则保存在 Agent Home。即使同一个 Agent 会同时用到这两处，它们的定位也各不相同。

## 涉及的核心位置

| 位置 | 作用 |
|---|---|
| Agent Home | 保存 Agent 本地指引、精选记忆、工作笔记与运行时状态，也是系统回退的默认工作区。 |
| 项目工作区（Project workspace） | 当前工作的项目绑定与指引生效范围。 |
| 执行根（Execution root） | 当前实际用于执行命令的物理根目录，例如主检出目录或关联的 worktree。 |
| 工作目录（Working directory） | 某条命令启动时的当前工作路径（cwd）。 |

同一个代码仓库的工作区绑定可以保持不变，而 Agent 在一个关联的独立 worktree 中工作。该 worktree 是一个独立的物理执行位置；引用产物文件时，路径必须指向实际包含该文件的检出目录。

## 挂载、切换与切换目录

挂载（Attach）工作区只是让该绑定对 Agent 可用；切换（Switch）才会激活已有绑定或已登记的执行根，供后续操作使用。单纯挂载不会自动切换，切换也不会自动创建新的代码检出。

在终端执行 `cd` 仅改变当前命令进程的工作目录，不会改变运行时的活动工作区、已加载的工作区指引，也不会改变后续相对 patch 的基准路径。同理，为某条命令指定 `workdir` 也不等于持久切换了工作区。

假设 Agent 正在审查仓库 A，此时需要修复仓库 B。单次执行 `cd` 进入 B 虽然可以临时查看 B 的文件，但运行时的全局工作区上下文依然停留在 A。如果要持续对 B 展开工作，应当先挂载 B（若尚未挂载），将其激活，并在修改文件前确认当前生效的执行根。

## 用于并行改动的 Worktree

通过 Git worktree，任务可以拥有独立的代码检出和分支，同时保留与主仓库的关联。当一个 Agent 在审查改动而另一个 Agent 在准备修复时，独立的 worktree 能够有效避免在工作副本中互相覆盖文件。

不过，worktree 并不会隔离共享的 Git 元数据、外部服务或主机凭据。若两个 Agent 操作相同的外部资源，依然可能产生冲突。在移交产物时，应当明确权属，并使用实际汇报的物理执行路径。

资源清理必须显式进行。离开某个工作区不会自动删除其 worktree；解绑工作区也不会删除项目文件。清理受控 worktree 时，系统会自动检查是否存在未提交修改或正在被任务占用。一个任务执行完毕，并不代表它有权随意删除其他 Agent 的检出目录。

## 目录组织不等于沙箱隔离

活动工作区决定了命令执行和相对路径修改的默认基准，但它不是文件系统沙箱。在本地宿主执行模式下，只要宿主权限允许，显式绝对路径和 shell 命令仍然可以访问工作区外部的文件。

操作者提出的“仅修改该目录”的要求始终具备约束力，即使运行环境在技术上能够触达更多路径。如果需要强隔离，应在宿主或底层执行环境层面单独配置。详见[安全与执行边界](./security-and-execution-boundaries.md)。

## 下一步

- [在项目工作区或 worktree 中工作](../guides/work-with-workspaces.md)
- [工作区与执行参考](../reference/workspaces.md)
- [工作区与执行规格](../spec/workspace-and-execution.md)
- [交付结果与产物位置](./results-and-artifacts.md)