Workspace 与执行环境
心智模型与规格契约： 理解工作区的安全隔离与信任边界，请查阅 安全与执行边界；查阅执行根绑定与 worktree 内部契约，请参阅维护者专属的 工作区与执行规格。
Workspace 是 Agent 的执行根目录，Agent 在这里读文件、跑命令、应用补丁。每个 Agent 始终只有一个活动 workspace。
Workspace 定义了什么
| 关注点 | 由 workspace 决定 |
|---|---|
| 指令根目录 | AGENTS.md 和政策文件从哪里解析 |
| 执行根目录 | 命令的默认工作目录 |
| ApplyPatch 目标 | 文件改动落在哪里 |
| 记忆范围 | Workspace 范围内的片段记录和索引 |
Workspace 与 shell 目录的区别
Workspace 不是 shell 的 cd。Shell cd 只改变那一个命令进程的目录。
Agent 用显式的绑定和激活工具来改变运行时工具的操作位置。
| 操作 | 效果 |
|---|---|
在 shell 里 cd /other | 只影响该命令 |
AttachWorkspace | 添加 workspace 绑定，但不切换 |
SwitchWorkspace | 改变后续操作的活动 workspace |
holon workspace attach /path | 为路径附加绑定，但不切换活动 workspace |
Workspace 命令
附加（attach）
把项目目录附加到 Agent：
holon workspace attach /path/to/project
holon workspace attach --agent my-agent /path/to/project
这会为该目录发现或创建 workspace 记录，并把它绑定到 Agent。附加本身不会改变
活动 workspace；准备在那里工作时，用 SwitchWorkspace 激活它。该绑定会跨
会话保留。
退出（exit）
返回 Agent 的 home workspace：
holon workspace exit
holon workspace exit --agent my-agent
分离（detach）
彻底移除一条 workspace 记录：
holon workspace detach <workspace-id>
分离不会删除目录，只是把 workspace 记录从 Holon 的索引中移除。与该 workspace 关联的记忆和片段记录会保留。
Worktree 隔离
CreateWorktree 依据一个显式附加的 workspace、分支和基准引用，创建一个受管理的
链接 worktree：
CreateWorktree {
workspace_id: "ws_...",
branch: "feature/example",
base_ref: "origin/main"
}
隔离 workspace 适合：
- 安全试验，不污染工作副本
- 不同 Agent 在同一仓库上并行工作
- PR 评审分支，改动不应外泄
Agent Home 与项目 Workspace
| Workspace 类型 | 用途 | 示例 |
|---|---|---|
| Agent home | Agent 本地状态和记忆 | ~/.holon/agents/my-agent/ |
| 项目 workspace | 正在处理的代码和文件 | /path/to/project |
每个 Agent 启动时都以自己的 Agent home 作为活动 workspace。用
workspace attach 绑定项目 workspace，用 SwitchWorkspace 激活它，用
workspace exit 返回 Agent home。
Agent Workspace 工具
GetWorkspaceState({})— 查看绑定、活动投影、worktree 和占用情况AttachWorkspace({ path: "/repo" })— 附加但不切换SwitchWorkspace({ workspace_id: "ws_..." })— 激活规范根目录SwitchWorkspace({ execution_root_id: "..." })— 激活一个保留的 worktreeSwitchWorkspace({ workspace_id: "agent_home" })— 返回 Agent homeCreateWorktree(...)— 创建或安全复用链接 worktreeRemoveWorktree(...)— 仅限清理的注册表清理DetachWorkspace({ workspace_id: "ws_..." })— 移除绑定；活动目标会先返回 Agent home
UseWorkspace 仍是为历史调用保留的隐藏兼容别名。