# 执行环境

工作空间可以绑定多台本地执行机，或在同一台机器上绑定多个目录，作为新会话中可显式选择的执行环境。绑定不会创建新的工作空间、任务副本或成员关系；模型、插件、环境变量、工作指引和权限始终来自当前空间，只有命令执行与执行机文件来源使用所选 Host 和目录。

如果新会话不显式选择执行环境，会使用空间设置中的[空间模式](/docs/workspace/workspace-mode)配置默认执行方式。空间模式负责将默认环境设置为云端或本地执行；执行环境只表示用户显式添加、按需选择的本地执行机和目录。

## 管理绑定

工作空间管理员可在当前空间 Header 点击齿轮，进入空间设置的“执行环境”中新增、自定义名称、修改目录、启停或解除绑定。存量执行空间不能管理绑定。可选执行环境必须满足：

每个主空间最多绑定 100 个执行环境；同一台执行机可以绑定多个不同目录。

- Local Agent 在线且路径配置有效；目录是否存在在实际使用时校验。
- 绑定已启用并属于当前主空间。
- 当前用户是已认证的空间管理员或编辑者；只读成员和 Guest 不可使用。
- 当前用户在该执行环境的可用范围内（见下文“负责人与可用范围”）；拷贝初始化尚未完成的环境暂不可用。

旧本地模式割接派生的兼容投影不会作为新会话里的额外候选项；默认执行仍由空间模式配置承接。解绑显式执行环境不会删除机器上的文件，也不会改写已有会话快照。

![执行环境管理](/images/docs/workspace/execution-environment-settings.png)

新增执行环境时，需要填写名称、选择在线[本地执行机](/docs/organization/local-agent)，并配置该执行环境对应的工作目录。

![添加执行环境](/images/docs/workspace/execution-environment-create.png)

### 第一次使用

空间还没有执行环境时，设置页会显示三步引导：

1. **接入本地执行机**：组织内还没有可用执行机时，点击“去接入”前往执行机管理页完成接入；已有执行机时显示“已接入”。
2. **添加执行环境**：选择执行机和工作目录，等同于右上角的“添加执行环境”。
3. **选择初始化方式**：推荐“从 Git 初始化”，让新环境自动准备好代码。

未添加任何执行环境时，新会话使用[空间模式](/docs/workspace/workspace-mode)配置的默认执行方式。

## 负责人与可用范围

执行环境常常对应某位成员自己电脑上的开发目录。为了避免他人的会话或任务误跑进别人的目录，每个执行环境都有一位**负责人**，并可以设置**谁可以使用**。

- **只有空间管理员能新建和管理执行环境**。负责人、可用范围、授权名单和 Tag 都在“编辑执行环境”中由空间管理员修改；负责人和编辑者如需收紧范围、加人或改 Tag，请联系空间管理员。
- **负责人**：始终可以使用该环境，但不因此获得管理权限。新建时负责人默认是你自己，也可以直接选择本空间的其他管理员或编辑者，方便替同事创建他的个人环境。
- **谁可以使用**：
  - **团队共享**：空间管理员和编辑者都可以使用，适合公共的测试机、构建机。
  - **仅负责人和指定成员**：只有负责人和授权名单中的成员可以使用，个人开发目录建议选这项。不选择任何人时，仅负责人可用。
- **管理员也不例外**：设为“仅负责人和指定成员”后，不是负责人、也不在名单中的空间管理员同样不能使用该环境。编辑时如果你自己不在名单中，会提示“你自己不在名单中，保存后也无法使用”，可一键“把我加入”。
- **只防误用，不是数据隔离**：可用范围用于避免误选、误派发，并不对机器上的文件做访问隔离；移除成员也不会影响已经创建的会话。

无权使用的环境不会出现在新会话的执行环境切换器、派发 Bot 任务和自动化任务的执行环境下拉中。如果环境刚被收紧，正在选择它的成员发起会话时会收到“没有使用该执行环境的权限”的提示，并自动回到“默认环境”；已指定该环境的自动化任务，若执行人失去使用权，触发时会直接失败并在执行历史中写明原因（详见[自动化任务](../task-management/scheduled-tasks.md)）。

### 授权名单

选择“仅负责人和指定成员”后，可以在“授权成员”中搜索并添加本空间的管理员或编辑者，点击成员标签上的移除按钮即可取消授权。成员不再是管理员或编辑者时，名单中会标注“已失效”，不再生效，可随时移除。

从“仅负责人和指定成员”切换回“团队共享”时，名单会保留但不生效；再切回时自动恢复。

### 更换负责人

在“编辑执行环境”中改选负责人后，页面会提示“保存后原负责人将失去使用权限”：

- 勾选“把原负责人加入授权名单”，原负责人保存后仍可继续使用该环境；
- 不勾选时，原负责人保存后失去使用权限（团队共享的环境除外）。

负责人不再是本空间的管理员或编辑者时，列表中会显示“负责人已失效”，建议尽快更换负责人。

## Tag

可以为执行环境打上最多 10 个 Tag（每个不超过 32 个字符），例如 `feature`、`bug`、项目名，用于区分环境用途。Tag 在添加或编辑执行环境时输入，回车或逗号确认，也可以从已有 Tag 中选择。

- **设置列表按 Tag 筛选**：执行环境列表上方的“Tag”下拉可只显示带某个 Tag 的环境；没有匹配时显示“没有带「xxx」标签的执行环境”。
- **切换器展示 Tag**：新对话的执行环境切换器中，每个环境会显示负责人和 Tag，仅限指定成员使用的环境带有锁形标识，方便快速选对环境。
- **选择时快速过滤**：有多个执行环境时，打开执行环境切换器或“分配 Bot 执行”弹窗的执行环境下拉后，顶部会出现搜索框和 Tag 按钮（与选择授权成员的方式一致）。搜索框可按名称、主机、负责人或 Tag 关键字查找；点击 Tag 只显示带该 Tag 的环境（可多选，命中任意一个即显示）。“默认环境”始终可选；没有匹配时可一键清除筛选。

## 初始化方式

添加执行环境时，可以选择如何准备工作目录。初始化方式只在添加时选择，之后在编辑中只读展示。

| 方式 | 适用场景 | 说明 |
| --- | --- | --- |
| 不初始化 | 目录已准备好 | 直接使用所填目录，不做任何处理 |
| 从 Git 初始化（推荐） | 代码托管在 Git 仓库的开发协作 | 由 AI 在新环境中拉取代码 |
| 从主空间拷贝 | 空间没有使用 Git | 把主空间文件同步到新目录；文件多时较慢 |

### 从 Git 初始化

如果空间已配置 Git，仓库地址和分支会自动预填；也可以手动填写其他仓库，此时将使用执行机上已有的 Git 凭据。仓库地址和分支都需要填写。

保存后，系统会在新环境中自动新开一个会话，并在输入框中填入初始化提示词；确认无误后由你发送，AI 随即在执行机上拉取代码。工作目录已有内容时，AI 会先检查目录现状并询问你如何处理，不会直接覆盖。

如果负责人是其他成员且环境仅限指定成员使用，你本人无法在该环境中发起会话，此时会弹出“初始化提示词”，可一键复制后交给负责人发送。

从 Git 初始化需要执行机在线；执行机离线时会提示错误，可改为“不初始化”或稍后再试。

### 从主空间拷贝

拷贝会**以主空间为准镜像同步**到所填工作目录：

- 目录不存在或为空时直接开始拷贝。
- 目录已有内容时会二次确认，提示目录中已有的文件数量；确认“覆盖并拷贝”后，**主空间中没有的文件将被删除**。根目录、一级目录或用户主目录等不安全位置不允许覆盖，需要换一个子目录。
- 主空间使用本机模式时，拷贝来源是主空间的云端副本，可能不是最新内容。
- 拷贝完成前该环境不可用，不会出现在新会话候选中，也不能修改工作目录。
- 执行机需要在线，离线时会提示错误。

### 拷贝进度与失败重试

拷贝进行中，执行环境列表对应行会显示“拷贝中”和进度条，完成后提示“拷贝完成，环境已可用”。

拷贝失败时会显示失败原因（例如执行机离线），并提供“重试拷贝”。重试前会再次确认：将以主空间为准重新同步，目录中多余的文件会被删除。

## 创建与继续对话

有可用绑定时，新对话输入框底部会显示执行环境，默认项显示为“默认环境”。选择绑定后，只有首条消息携带执行环境 ID。该 ID 表示空间与执行机的绑定关系，不是 Host ID；继续旧会话也不能重新指定执行环境。旧会话未显式选择执行环境时，也会只读显示为“默认环境”。

只读成员查询新会话执行环境时会得到空列表，界面不展示切换入口，新会话只使用“默认环境”。即使手工构造 `executionEnvironmentId`，服务端也会拒绝该请求。

会话创建时会保存绑定、Host 名称、Host ID、本地目录及目录摘要的标量快照。禁用、改目录或解绑只影响新会话候选；旧会话继续按快照路由。Host 被删除或离线时，历史会话显示“环境不可用”并禁止继续执行。

空间管理员和编辑者可以在新对话输入区选择本次会话要使用的执行环境；保留“默认环境”时，系统会使用[空间模式](/docs/workspace/workspace-mode)中的默认执行方式。

![输入区选择执行环境](/images/docs/workspace/execution-environment-input-selector.png)

## 查看与编辑文件

在工作空间的资源工作区打开 **知识** 后，文件树标题栏可以在“主空间”和已打开执行机会话之间切换。两个来源的同路径文件使用不同标签页，不会互相覆盖。

打开执行机会话后，文件树标题栏会展示当前文件来源，并可在默认环境和已绑定执行环境之间切换查看。

![切换执行环境文件来源](/images/docs/workspace/execution-environment-switcher.png)

执行机文件支持与主空间一致的只读预览类型，包括文本、代码、Markdown、图片、PDF、Office、XMind 和音视频；预览会遵循各类型的大小上限。文件编辑仍仅支持已存在、最大 10 MB 的 UTF-8 文本，不提供通用的新建或删除接口；编辑器粘贴图片时会在当前执行环境中创建对应资源文件。保存使用 SHA-256 版本校验；文件被外部修改时拒绝覆盖并保留编辑草稿，只有对明确冲突再次确认后才可使用短期、用户与内容绑定的覆盖令牌。

## 与执行空间的关系

执行空间是历史工作副本模型，目前停止新增但存量继续可见可用。需要新的独立运行目录时，优先在“执行环境”中绑定本地执行机和目录；需要配置当前空间不选择执行环境时的默认云端或本地运行方式，使用[空间模式](/docs/workspace/workspace-mode)。