工作空间与 Agent 会话
- 文档状态
- draft
- 文档 Owner
- DOC
- 事实源
- canonical-docs
- 更新
- 2026/10/16
工作空间是任务的执行目录，Agent 会话是其中运行的编码进程与对话上下文。目录可以跨 worker 调用复用；重试不等于把已有工作清空后重新开始。
以下行为依据官方参考实现 be10a1b79df723d6d7612b5651c8522704dafb2e 的 Workspace、AgentRunner及 SPEC §9–10。不据此宣称团队部署启用了远程 worker。
目录身份与复用
工作目录位于配置的 workspace.root 下。参考实现以任务标识生成目录 key，只保留字母、数字、点、下划线和连字符；发生替换时附加原始标识的稳定哈希片段，以减少名称碰撞。
创建前会检查路径边界。有效的已有目录可复用，新目录才调用 after_create。因此 clone、依赖准备等一次性步骤适合放在 after_create；每次执行前必须重新检查的条件放在 before_run。项目若需要分支或工作树策略，必须在自己的 hook / workflow 合同中明确，不能从“目录按任务隔离”推导默认创建了 Git worktree。
hook 的执行顺序与失败语义
| hook | 何时执行 | 失败或超时后怎样处理 |
|---|---|---|
after_create | 创建新目录之后 | 目录准备失败，本次不能进入 Agent 执行 |
before_run | 每次 worker 执行 Agent 之前 | 当前尝试失败 |
after_run | 执行收尾；Runner 进入运行准备后通过收尾路径调用 | 记录错误，不用它覆盖主要执行结果 |
before_remove | 清理目录之前 | 记录错误，清理路径不以 hook 成功作为保证 |
hook 在任务目录上下文执行，受 hooks.timeout_ms 约束。它是宿主 shell 脚本，不是受限声明式配置；不要把不可信任务正文拼接成 hook 命令。保留成果、上传证据或归档策略应在清理前完成，不能依赖一次失败也会被忽略的 hook 作为唯一保障。
Agent 如何进入目录
Runner 先获得工作空间并报告其位置，再调用 before_run，随后启动 Codex app-server。提示模板使用任务字段构造；一次调用中可以在同一 app-server 线程继续多轮，轮次间按 ID 刷新来源任务。
codex.command 是启动命令。能找到二进制、版本兼容、已具备有效认证和工作目录内所需工具，都是启动的实际前提。配置里出现命令字符串不证明这些前提成立。app-server 的审批、沙箱、输入请求和工具协议还受所选 Codex 版本影响。
目录边界检查保障路径选择；Codex 的 sandbox / approval 配置和宿主权限才决定进程能访问或执行什么。任务目录本身不是系统级隔离或凭据隔离。 来源原生工具使用宿主侧认证时，还要检查该凭据的真实权限范围。
何时保留、何时清理
失败后通常保留目录供后续重试继续。任务退出活跃范围但尚未终态时，停止执行也会保留目录；发现终态的启动清理、运行核对或重试刷新可删除对应目录。关闭任务前先确认尚未提交的成果、证据和所需归档已得到处理。
重启会丢失内存会话与认领，文件系统中的目录可能仍在。复用目录不等于恢复原 app-server 线程，也不证明重启前的子进程已经清理完毕；恢复步骤见失败与恢复。
远程 worker 的适用范围
此固定参考版本含 SSH worker 扩展，调度器可以选择 worker host，目录与执行随所选主机处理。它不是要求所有 Symphony 部署都使用 SSH 的核心前提。启用前需核对该版本的 worker 配置、主机工具、路径、认证与并发限制；本文不提供团队环境的主机或凭据资料。