用途:当用户询问 Codex Local Environments、worktree 的 setup/cleanup 脚本、Codex actions、.codex/environments/environment.toml、CODEX_WORKTREE_PATH、CODEX_SOURCE_TREE_PATH,或如何让 worktree 就绪时使用本技能。
主要能力:Codex 应用本地环境属于项目配置而非一次性终端命令;可分享的配置位于项目根目录 .codex/environments/environment.toml。setup 脚本在 Codex 为新线程创建 worktree 时运行,cleanup 脚本在清理 worktree 前运行,actions 显示在 Codex 应用顶栏并在集成终端运行。由于 worktree 只包含已提交文件,被忽略的 .env 等需由 setup 复制或重建。
推荐结构:配置放 .codex/environments/environment.toml,可执行入口放 scripts/(如 scripts/worktree-up、scripts/worktree-down)。TOML 采用 version=1、name、[setup]、[cleanup] 与多个 [[actions]] 的形式,setup/cleanup 只做简短调用,逻辑放在 scripts/ 中。
脚本规则:脚本以 set -euo pipefail 开头并 cd 到工作树;用 CODEX_SOURCE_TREE_PATH 定位源检出;复制被忽略的 env 文件;遵循项目包管理器约定;为本地数据库生成确定性的 worktree DB 名并重写 .env 中 DB 相关值;保持可重复执行,提供显式重置开关;cleanup 只删除 worktree env 引用的数据库,使用 dropdb --if-exists,之后移除复制的本地 env 文件,缺失工具时干净退出。
验证与环境限制:用 bash -n 检查脚本、查看 TOML、运行 git status --short,Python 3.11+ 可用 tomllib 校验。不要读写 .conductor 目录,不要打印完整 env 值或密钥,不要重复创建环境,不要在 TOML 中放入大型易碎 shell,不要硬编码开发端口,不要删除来源不明的数据库。若面向未来 worktree,配置与脚本应存在于源检出/主分支。