用途:这是 AEP 系列技能(/aep-launch、/aep-build、/aep-wrap 等)的 Git 约定统一入口,供其它技能引用,避免重复内联。AEP 基于普通 git 仓库加 git worktree 实现并行智能体隔离。
集成分支 $BASE:所有操作针对集成分支。默认单分支模式(无 develop 时 $BASE=main);存在 develop 时自动进入双分支模式($BASE=develop,main 仅用于提升,AEP 不触碰)。可通过 git config aep.integration-branch 覆盖非标准分支名。解析逻辑在各技能首个 bash 块中执行。
Worktree 生命周期:创建用 git worktree add -b feat/<name> .feature-workspaces/<name> "$BASE",路径固定在被 gitignore 的 .feature-workspaces/<name>;查看用 git worktree list 与 git -C 子命令;删除用 git worktree remove 与 git branch -d(squash 合并导致未合并告警时可确认 PR 为 MERGED 后用 -D)。目录误删可用 git worktree prune、git worktree repair 修复。
分支命名:功能 feat/<short-name>,迁移 chore/,修复 fix/,迁移项目 migration/;使用 kebab-case、无空格下划线、名称不超过 30 字符。
每任务一次提交:tasks.md 有 N 个任务则功能分支有 N 个按序提交,采用 conventional commit 格式,每个提交后把短 SHA 记入 .dev-workflow/feature-verification.json 的 commit_sha 字段。出错时优先追加 fix 提交,历史保持只增。
发布与 PR:推送用 git push -u origin feat/<name>,变基后用 git push --force-with-lease。创建 PR 必须显式指定基础分支:gh pr create --base "$BASE"。合并用 gh pr merge <number> --squash --delete-branch。
控制面提交:设计、派发、归档等直接提交到集成分支,先 git pull --ff-only origin "$BASE",再 git add 具体文件(不用 -A)、提交并推送。
恢复:丢失提交用 git reflog 加 git cherry-pick;丢失分支用 git reflog 加 git branch <name> <sha>;rebase 后 openspec/ 文件丢失用 git restore --source=<sha> -- openspec/ 恢复。
磁盘:每个 worktree 约占用一份工作树副本,.git/objects 共享;可用 du -sh 监控 .feature-workspaces/ 与 .git/objects。
限制:未提交的工作树内容在 rm -rf 后无法恢复;部署与从 develop 到 main 的提升不属于 AEP 范围。