自定义 Agent 只有你自己能用？用 AI Catalog 让全组复用
自定义 Agent 只有你自己能用？用 AI Catalog 让全组复用
定义框：AI 目录（AI Catalog）是极狐GitLab Duo Agent Platform 中 Agent 与流程的中央列表。它把 Agent 从「某个项目里的一段配置」升级为可发现、可共享、可版本化的平台级资产：在这里发现官方与社区创建的 Agent，创建自己的自定义 Agent 并共享给他人，再把它们启用到具体项目或群组中供编排使用。
为什么「写完一个 Agent」不等于「用起来一个 Agent」
Agent 的门槛其实不高。定义一段系统提示、挑几个允许它调用的工具，一个能干的自定义 Agent 就成型了。真正卡住团队的从来不是创建，而是扩散。
一个自定义的 Agent 如果只是躺在某个项目里，它的作用域就是那个项目。隔壁组想用，要么复制一份配置过去，要么去翻那个项目的 .gitlab 目录然后把 YAML 抄过来。抄过去之后呢？原项目改了系统提示，抄的那份不会跟着变。三个月后同一个「代码评审 Agent」在组织里存在五个版本，行为各不相同，谁也说不清哪个是对的。
这不是假设。版本历史这一节里，文档对自定义 Agent 的行为描述得很具体：当你更改项目配置时，极狐GitLab 会自动创建一个新版本，用语义化版本控制表示更改范围，且更新总是递增次版本号。反过来说，Agent 的变更是持续发生的——提示词会被打磨、工具权限会被收紧。没有中央目录与版本机制，这些变更就只会变成散落各处的分叉。
还有一层是可见性问题。多数团队里，其他人根本不知道你写过一个 Agent。文档给出的两条查看入口——顶部栏「搜索或跳转到 > 探索 > AI 目录」，以及 Duo 侧边栏里的「极狐GitLab Duo AI 目录」——本身就说明这是一个需要被主动浏览的公共资产页，而不是藏在某个项目设置里的私人物件。
所以真正的命题是：如何让一个 Agent 从个人产出变成团队可依赖、可回滚、可治理的能力。
怎么用：把 Agent 从个人资产推进团队资产的四步
第一步：确认你的角色与可用范围
启用是有权限门槛的。要在群组或项目中从 AI 目录启用 Agent 和流程，你需要具备维护者或所有者角色；如果只是查看某个 Agent 或流程的当前版本，开发者角色即可。
同时要确认交付形态：AI 目录同时支持 JihuLab.com 与私有化部署。但两者之间有一处关键差异——在私有化部署实例上，AI 目录中不会显示在 JihuLab.com 上创建的自定义 Agent，也不会显示尚未添加到该实例的、由极狐GitLab 管理的第三方 Agent。跨形态复用前，先把这条边界说清楚，能省掉一轮无效排查。
第二步：进入 AI 目录，区分 Agent 与流程两个页签
两条入口任选其一：
顶部栏：选择「搜索或跳转到」>「探索」>「AI 目录」；
Duo 侧边栏：先定位到你的项目，再选择「极狐GitLab Duo AI 目录」。
进入后默认展示 Agent 列表，切到「流程」页签可以看到可用的流程。注意区分三种 Agent 类型：
Agent 类型 | 由谁创建 | 如何触发 | 典型用途 |
|---|---|---|---|
内置 Agent | 极狐GitLab 预构建、生产就绪 | 默认开启，直接在 Duo Chat 中使用 | 常见工作流、特定领域专业知识 |
自定义 Agent | 团队自己配置（系统提示 + 工具） | 在群组或项目中启用后在 Chat 中使用 | 内置未覆盖的专业工作流 |
外部 Agent | 集成极狐GitLab 之外的 AI 模型提供商 | 从讨论、议题或合并请求直接触发 | 引入外部模型能力 |
文档里还点名了一个由极狐GitLab 维护的外部 Agent：Wiki Agent，可根据项目代码仓库生成或更新项目 Wiki。这类「官方维护的外部 Agent」通常是最容易被忽略、但开箱即用价值最高的一档。
第三步：把 Agent 启用到项目或群组，并理解版本锁定
这一步是「复用」真正发生的地方，也是最容易出意外的一步。启用后，版本会被锁定：
在群组中启用时，极狐GitLab 会锁定最新版本；
在不管理该项目的项目中启用时，会锁定与该项目顶级群组相同的版本；
在管理该项目的项目中启用时不会锁定，管理项目始终使用最新版本。
版本锁定的含义是：你的项目或群组使用固定版本的 Agent 或流程，AI 目录中的更新不会自动影响你的配置，何时采用新版本由你决定。这条机制是「共享」能成立的前提——否则上游一次提示词调整就会静默改变全组织的行为。
第四步：用版本历史做变更回溯与灰度
每个自定义 Agent 与流程都维护版本历史，语义化版本由极狐GitLab 自动管理。触发新版本的场景有两个：更新自定义 Agent 的系统提示，或修改第三方 Agent 或流程的配置。版本一旦创建即不可变。
查看当前版本需要开发者、维护者或所有者角色，路径为「AI > Agent」或「AI > 流程」，详情页会展示锁定版本、版本标识符（如 1.2.0）以及该版本的配置详情。更新到最新版本则需要维护者或所有者角色。
由此可以推导出一条很实用的灰度路径：先在管理项目里迭代（它始终跟最新版本），验证稳定后，再到消费项目里执行「查看最新版本 > 更新到 x.y.z」，把锁定版本推上去。
# 消费项目侧的变更清单（人工核对项，非命令）
# 1. 进入 项目 > AI > Agent / 流程
# 2. 打开目标 Agent，查看「当前版本」= 1.2.0
# 3. 选择「查看最新版本」>「更新到 1.3.0」
# 4. 在 Chat 中复跑一个已知场景，比对输出差异把这套灰度路径固化成流程，每一步的责任人与出口条件如下：
阶段 | 所在位置 | 版本状态 | 出口条件 |
|---|---|---|---|
迭代 | 管理项目 | 始终跟随最新版本 | 提示词与工具权限调整完成 |
固化 | AI 目录 | 自动生成新的次版本号，版本不可变 | 新版本可见且配置正确 |
验证 | 管理项目 | 最新版本 | 已知场景输出符合预期 |
推广 | 消费项目 / 群组 | 锁定版本 | 执行更新后复跑比对通过 |
落地 Tips：三个常见的坑
坑一：把消费项目当成迭代现场。 只有管理项目始终使用最新版本，消费项目在被启用时锁定的是当时的版本。在消费项目里反复改配置却看不到行为变化，通常不是缓存问题，而是锁定版本根本没动。
坑二：忽视私有化部署的可见性边界。 私有化实例上看不到 JihuLab.com 创建的自定义 Agent，也看不到未添加到实例的第三方 Agent。做跨环境迁移规划时，这一条要写进实施清单，否则会在验收环节才发现「Agent 不见了」。
坑三：指望内置 Agent 也有版本历史。 版本控制只作用于自定义 Agent 和流程，内置 Agent 与流程不使用版本控制。因此基于内置能力做的二次封装，才有版本化治理的必要。
还有一个容易被忽略的时间线问题：AI 目录在 18.5 以实验功能引入（带 global_ai_catalog 功能标志，JihuLab.com 默认启用），18.6 增加第三方 Agent 支持（带 ai_catalog_third_party_flows 功能标志），18.7 转为测试版并引入版本历史，18.8 GA，18.10 移除功能标志并新增「管理项目始终使用最新版本」，18.11 起可从 Duo 侧边栏直接查看。如果你维护的实例版本较早，上述能力可能尚未可用，升级前先对照这条时间线确认。
FAQ
Q1：自定义 Agent 和内置 Agent 该怎么选？
内置 Agent 由极狐GitLab 预构建、生产就绪，默认开启，可直接通过 Duo Chat 使用，适合常见工作流。自定义 Agent 由你自己用系统提示定义行为并选择可访问的工具，适合内置能力未覆盖的专业工作流。判断标准很简单：先看内置 Agent 里有没有能覆盖的场景，没有再自定义。
Q2：AI 目录支持哪些版本与部署形态？
覆盖基础版、专业版、旗舰版，同时支持 JihuLab.com 与私有化部署。需要注意的是，历史版本的功能标志与计费方式有过调整——global_ai_catalog 功能标志已在 18.10 移除，同版本起 JihuLab.com 的基础版层级可通过极狐GitLab 积分使用。
Q3：Agent 更新后，我的项目会自动跟着变吗？
取决于项目类型。管理 Agent 或流程的项目始终使用最新版本；其他项目与群组启用时会锁定版本，AI 目录里的更新不会影响已有配置，需要由维护者或所有者主动执行「查看最新版本 > 更新到 x.y.z」才会变更。
想要在自己的项目里跑通这套 Agent 复用流程？
可以先从官方文档中心的「AI 目录」与「Agent」两节入手，确认实例版本对应的能力范围，再挑一个高频场景（比如代码评审或流水线修复）做第一个自定义 Agent，把它启用到群组里验证扩散效果。
参考资料：AI 目录 ｜ Agent ｜ 极狐GitLab 官网
