4.5 KiB
Worktree 路径、命名与复用
创建、复用隔离目录或排查同机多工程冲突时读取本文件。它定义 Agent 的选择步骤，CLI 不自动创建或改名。工单须先按占用规则领取；目录名称不是所有权依据。环境安排另按本机验证，登记和回收按生命周期。
先确定工程与已有任务
通过 Git common dir、git worktree list --porcelain -z 和宿主附件确定真实主工作目录及目标仓库，核对无凭据的 origin 与工单仓库。不能用当前 linked worktree 作为另一个工程根目录，也不能只用目录 basename 区分同名工程。无可识别主工作目录、bare 仓库或归属不明时先核实，不猜路径。
继续同一任务时，先核对远端 owner/令牌、台账、实际 Git common dir、分支、HEAD、未提交内容与宿主占用。确认属于本任务且允许续接后复用实际路径；目录旧名与分支不同不自动改名或删除。发现另一个任务或活动会话正在使用则保留，按转交/协调流程处理；不能创建一个随机新目录绕过同单占用。
位置优先级
- 用户或工程明确约定优先，并核对是否适用于当前宿主与仓库。
- 工程默认
native-first：可用时调用宿主原生 worktree 工具，保存返回的实际路径与附件 ID；允许目录在工程外，不自行拼出、移动或改名宿主管理路径。工具可选名称仅作提示，结果以实际返回为准。 - 宿主不支持目标仓库时使用工程配置
worktree.fallback，默认.local/agent/worktrees。以真实主工作目录解析，不以当前任务目录解析。现有配置仅支持工程内相对路径；绝对路径及..不合法。用户明确要求自管全局目录时，先说明该配置不支持，再按明确约定单独安排，不能把全局路径写成有效 fallback。
Git fallback 创建前核对父目录的真实路径仍在本工程内，无符号链接越界；完整目标及父目录未跟踪且被 Git 忽略。检查目标路径（包括悬空链接）不存在、目标分支不存在且未被其他 worktree 使用。创建失败后读取 Git/目录实际状态；仅确认无原任务及遗留创建结果时才换短 ID 重试，不能覆盖、强制 checkout 或强制删除。
新建命名
工程没有明确命名约定时，Git fallback 使用：
目录：<真实主工作目录>/<worktree.fallback>/issue-<编号>-<简述>-<短ID>
分支：codex/issue-<编号>-<简述>-<短ID>
示例目录尾部：issue-23-finance-note-a1b2c3d4e5f6
- 编号取当前仓库真实工单；同编号在不同仓库是不同任务。简述只用小写 ASCII 字母、数字和单个连字符，去首尾连字符，最多 32 字符，无法形成简述时用
task；不直接使用工单标题作 shell 参数或路径。 - 短 ID 为新生成 UUID 的前 12 位小写十六进制，一次任务固定并登记。短 ID 降低重名概率，创建前检查及 Git 的排他创建仍必须执行。存在分支先核对归属，不为重试同任务再生成新分支。
- 明确不关联工单的维护任务用
task-<简述>-<短ID>；业务需求或 Bug 仍先取得工单编号，不能用此例外跳过工单。 - 分支前缀遵循宿主/工程明确约定，默认
codex/；创建前用git check-ref-format --branch校验。宿主自行分配名称或 detached HEAD 时保留其管理方式，登记真实状态，不强行套用 Git fallback 命名。
同机不同工程默认各有自己的目录根，即使工单编号和简述相同也分离。用户明确约定自管共享目录时，再增加 <工程标识>/ 层：工程标识为规范化主目录 basename（同简述字符规则）加 - 和 SHA-256 前 12 位；哈希输入为“无凭据的规范仓库标识 + 换行 + realpath 后主目录路径”。同名工程及同仓库不同 clone 因此区分，仍检查碰撞；宿主原生路径不套此规则。工程迁移路径时先保留、核对已有任务记录，不重新计算后丢弃旧目录。
创建或复用成功后，台账保存工程标识（如使用）、任务短 ID、仓库、工单、owner、实际路径、分支/HEAD、宿主附件及基线提交；路径不存在或登记失败时不报告准备完成。旧任务不为符合新名称批量改名，安装和升级也不搬迁目录。用户测试交付提供实际绝对路径、分支、提交与运行入口，不能让用户凭目录名猜版本。