superproject-workspace 是一个面向多仓库工作区的智能体技能。它的核心思路是建立一个“超级项目”(superproject):一个把其他仓库作为 git 子模块挂载的仓库,让一次智能体会话同时获得所有仓库的上下文和编辑权限,而每个子仓库仍保留自己的远端、PR 和发布周期。代价在于 gitlink 记录的是提交而不是分支,子仓库合并 PR 后超级项目会悄悄落后,检出容易变成 detached、脏状态或游离分支,指针也可能指向没人推送过的提交——“漂移”是默认状态而非缺陷。该技能让漂移可见,并按策略移动指针。
主要能力:
一、策略模型。每个子仓库在 .gitmodules 中以额外键声明策略,Git 会忽略不认识的键,因此这些键与 path、url 同处一地、不会失步。支持三种策略:track(保持在最新 origin/<branch>,可通过 pull 快进后 bump 移动指针,可自动化)、pin(保持在已知基线,如生产、某发布或复现环境,仅在指定原因时 bump)、lazy(参考资料,仅在任务需要时获取)。未设置视为 pin,audit 会告警。track 可设置 bump 模式:pr(定时 CI 在 chore/submodule-bump 上开一个 PR)、direct(CI 在 preflight 通过后直接提交默认分支)、manual(人工或智能体运行 bump)。还可用 x-tier 分组、x-role 记录一行用途说明,显示在仓库地图中。
二、两种模式。子模块超级项目(推荐)用 .gitmodules 和 gitlink 固定版本,一次外层提交即一个精确快照,支持 bump/preflight/CI bump,克隆按策略惰性进行。指针式 home repo(备选)在 .superproject 中用 [repo "<name>"] 记录普通克隆,没有版本快照,不支持 bump,克隆始终按需(init <name>)。指南建议尽可能用子模块;只有外层历史无法容纳 gitlink、克隆必须留在原处、有大量很少触及的仓库、协作者无法使用子模块或没人会去 bump 时才选指针模式。两种类型可共存于同一根目录。
三、CLI 与工作流。脚本 scripts/superproject.py 提供 new、add、status、init、pull、bump、preflight、worktree add|list|remove、task open|list|close、repair、audit、adopt、ci-plan 等命令。常用参数有 --root(或 $SUPERPROJECT_ROOT)、--json、--dry-run。选择子项可用位置名称(name、path 或 basename)、--tier、--policy、--kind、--mode。退出码 0 表示正常,1 表示拒绝或检查失败,2 表示用法错误。典型流程:用 new 从零创建、用 add 添加子仓库;用 status --fetch 和 audit 查看策略、滞后、漂移、脏状态与 worktree;用 init 初始化所需子项;在子仓库的 worktree 中开发并走子仓库自身流程;用 pull 快进 track 子项,用 bump 在子项已推送的前提下移动指针,一次跨仓库变更对应一次外层提交;用 preflight 守护外层提交;可用 adopt 将已有超级项目纳入本技能约定。
四、审计与修复。audit 给出发现及精确修复命令;repair 可分无损重连、裁剪失效 worktree 与过期子模块配置、将孤儿 worktree 重新挂到子仓库 store 中的 rescue 分支等模式,且从不删除 .git/modules store、不强删脏 worktree、不移动 worktree。
五、外层仓库规则。外层检出始终停在默认分支;跨仓库特性在子仓库分支上进行;不得为子仓库工作在超级项目上创建 worktree;先提交并推送子仓库,再用一次外层提交覆盖所有受影响的 gitlink;辅助工具自身不提交不推送(除 bump --commit 按要求)。在子仓库内部,子仓库自己的指令文件优先。
使用限制与注意:普通单仓库 git 工作、单个子仓库内的 issue/PR 生命周期、临时跨几个检出读取、已有第三方清单工具管理的场景不适合本技能。new、add、adopt 会改变仓库性质或写入元数据,仅在用户明确要求时运行;仅有 .gitmodules 不等于请求。不要将 CLI 复制进每个超级项目,应引用已安装技能,仅在离线环境 vendor。在超级项目中 git pull 不会更新子仓库。git submodule update 会 detached HEAD,可能遗留不在分支上的本地提交。“最新”从不意味着重置 pin。不得 bump 到未推送的子仓库提交。子模块名不等于其路径。安装命令资料未明确提供(仅提及 npx skills update 可升级已安装技能)。
适用场景:需要单一智能体入口协同多个关联仓库的团队、跨仓库功能开发、子仓库 PR 合并后推进指针、从零搭建多仓库工作区、将遗留超级项目纳入统一约定。具体分类归入编程与开发。