极狐GitLab AI 目录：自定义 Agent 的版本锁定与团队复用
极狐GitLab AI 目录：自定义 Agent 的版本锁定与团队复用
自定义 Agent 的第一版总是好用的。第二版开始出现分歧：有人调了系统提示，有人改了工具范围，有人把参数从严格改成了宽松。等到第三个人接手时，已经没人说得清线上跑的到底是哪一版——直到某天它把不该改的东西改了。
这不是模型能力问题，是资产管理问题。当 Agent 从「个人的调试玩具」变成「流程里的一环」，它就需要和代码一样被对待：有版本、有来源、有授权、可回滚。
一、Agent 正在重复「脚本散落」的老路
过去十年，很多团队都经历过同一件事：运维脚本从一台机器的 ~/bin 开始，被复制、被改写、被私有化，最后没人敢删、没人敢改。CI/CD 的出现给出了答案——既然脚本要被执行，就把它变成受版本控制的流水线定义。
Agent 现在走的是同一条路。极狐GitLab Duo Agent Platform 把智能体嵌进了软件开发生命周期，团队可以构建自定义 Agent 来解决自己的独特开发需求。但一旦「自定义」的门槛降到人人都能改，一个新问题就出现了：配置漂移。
具体表现有三类：
来源不明：某个 Agent 在三个项目里跑，但只有创建者知道它的系统提示被改过几次；
更新失控：上游修了一个 Agent 的问题，下游却不知道自己用的是旧版本，也不知道该不该跟；
授权模糊：一个 Agent 能被哪些项目启用、由谁启用，全凭口头约定。
这三类问题的共同点：它们都不是技术故障，而是缺少一个登记与授权的中心。
二、AI 目录：Agent 和流程的中央列表
依据官方文档，AI 目录是 Agent 和流程的中央列表。把这些 Agent 和流程添加到项目中，即可开始编排 Agent AI 任务。
它解决三件事：
发现——浏览由极狐GitLab 团队和社区成员创建的 Agent 和流程；
沉淀——创建自定义 Agent 和流程，并与其他用户共享；
启用——在项目中启用 Agent 和流程，以便在极狐GitLab Duo Agent Platform 中使用。
入口有两个：顶部栏的「搜索或跳转到 → 探索 → AI 目录」，或者从极狐GitLab Duo 侧边栏直接进入（该入口在 18.11 引入）。切换「流程」选项卡即可查看可用的任务流。
这里有一条容易被忽略的权限边界：要启用 Agent 和流程，你在群组中、或项目中必须具有维护者或所有者角色。这条约束很关键——能用和能改，是两个权限。日常开发者可以调用 Agent，但把它注册进项目、改变它的生效范围，属于治理动作。
至于落地节奏，官方版本历史给出了明确路径：AI 目录在 18.5 作为实验功能引入（功能标志 global_ai_catalog），18.6 加入第三方 Agent 支持，18.7 转为测试版，18.8 正式 GA，18.10 移除了功能标志，并支持 JihuLab.com 上的基础版层级通过极狐GitLab 积分使用。如果你的实例版本还在 18.8 之前，升级是启用它的前置条件。
三、版本控制：解决「改了什么」的问题
AI 目录里每个自定义 Agent 和流程都维护着一份版本历史。注意这个限定：内置 Agent 和流程不使用版本控制——它们由平台统一维护，不需要团队操心。
机制上有三个设计值得注意：
第一，自动触发。 你不需要手动打版本号。更新自定义 Agent 的系统提示、或修改第三方 Agent 或流程的配置，极狐GitLab 就会自动创建一个新版本。
第二，语义化且只递增次版本号。 版本号形如 1.0.0、1.1.0，由极狐GitLab 自动管理。Agent 或流程的更新总是递增次版本号。这意味着一件事：官方把「配置调整」明确定义为兼容性变更，不会用主版本号来制造噪音。
第三，不可变。 版本一旦创建就不能再改。这条约束是整个机制的地基——如果版本可篡改，「回滚到 1.1.0」这句话就失去了确定性。
版本控制解决的是「改了什么、什么时候改的」。但团队真正会踩的坑在下一个问题：我用的到底是哪一版？
四、版本锁定：解决「会不会被上游带崩」的问题
这是 18.10 引入的能力，也是我认为最值得单独拿出来讲的一条。
规则并不复杂：
在群组中启用一个 AI 目录项目时，极狐GitLab 会锁定最新版本；
在不管理该项目的项目中启用时，极狐GitLab 会锁定与该项目顶级群组相同的版本。
锁定带来的结果是可预测性：
你的项目或群组使用的是一个固定版本；
AI 目录中该 Agent 或流程的更新，不会影响你现有的配置；
采用新版本的时机由你决定，而不是由上游替你决定。
有一个例外必须说清楚：如果你是在管理该项目的项目中启用 AI 目录项目，极狐GitLab 不会锁定版本——管理项目始终使用该项目的最新版本。这个例外是合理的：源头跟着自己走，下游才需要稳定锚点。
至于历史包袱，官方也给了解释：如果你在 18.10 之前就已经在管理项目中启用了它，配置会保持在锁定版本；在你首次主动更新到最新版本后，此后才会自动跟随最新。
这套逻辑和依赖管理的心智模型完全一致：下游默认锁版本，升级是一次显式动作。
五、落地：如何查看和更新一个 Agent 的版本
配置动作本身很轻。以项目级为例，查看当前版本需要开发者、维护者或所有者角色：
在顶部栏选择「搜索或跳转到」，找到你的项目或群组；
在左侧边栏选择 AI > Agent 或 AI > 流程；
选择要查看的 Agent 或流程。
详情页会显示三项信息：你的项目或群组正在使用的锁定版本、版本标识符（例如 1.2.0）、以及该版本的具体配置详情。
要把项目或群组切到最新版本，需要维护者或所有者角色：
同样从左侧边栏进入 AI > Agent 或 AI > 流程；
选中目标 Agent 或流程；
仔细核对最新版本后，选择「查看最新版本 > 更新到 」。
注意最后一步的措辞：官方特意写了「仔细检查最新版本」。这不是客套——升级动作被设计成一次需要人确认的显式操作，而不是后台静默同步。这正是锁定机制的价值所在。
顺带提醒两个私有化部署的场景差异：在私有化部署实例上，在 JihuLab.com 创建的自定义 Agent 不会显示在 AI 目录中，尚未添加到实例的、由极狐GitLab 管理的第三方 Agent 同样不会显示。所以如果你在私有化环境里「找不到某个 Agent」，先确认它是本地创建还是 SaaS 侧创建的。
六、为什么这件事值得认真做
把 AI 目录放到更大的图景里看，它回答的是企业落地 AI 时最实际的一个问题：怎么让 Agent 从"某个人会用的工具"，变成"组织能依赖的能力"。
答案并不新奇，就是软件工程用了三十年的那套办法——中心化的注册、语义化的版本、显式的升级、明确的授权边界。区别只在于，这次被治理的对象从代码库换成了智能体。
值得留意的还有权限的分层设计：启用需要维护者及以上，查看版本只需开发者，更新版本又要维护者。这种"看得见、改不动"的分层，让 Agent 的日常消费和治理决策被拆成了两个动作，避免了"能调就顺手改"的常见失控。
写在最后
Agent 的价值在于自动化，但自动化一旦进入生产流程，可复现性就成了硬性前提。一个说不清版本的智能体，和一个没人敢动的运维脚本没有本质区别。
如果你正在多个项目里重复维护相似的 Agent 配置，或者经历过"上游改了、下游崩了"的场面，AI 目录的版本锁定机制值得花半小时摸一遍。完整的启用条件、版本规则与操作路径，可以参考官方文档中心。也欢迎在评论区聊聊：你们团队的 Agent 配置，现在是集中管理还是各自维护？
