代码托管平台集成

激活方式：一句提示词

代码托管集成不走"管理台 UI"，也不需要用户手动去仓库 Settings 配 webhook。正确做法是——

在一个 combo-agent session 里，直接用自然语言告诉 Agent 你的诉求。

你说的话	Agent 加载的 skill
"帮我监控这个 GitHub 仓库 `uu5208/ragbase` 的 PR 审核"	`github-integration`
"把 GitLab 项目 `team/backend` 接到自动审核"	`gitlab-integration`
"给 Gitee 仓库 `myorg/myapp` 配 PR 审核"	`gitee-integration`
"监控 Gerrit 项目 `platform/core` 的新 patchset"	`gerrit-integration`
"审核 Gerrit change 12345"	`gerrit-integration`

Agent 从 SKILL.md 的「触发词」命中后，会按一条强制流水线自动完成从收凭据到链路验收的所有动作。用户全程只回答一个问题：贴一下 Token。

Rendering diagram…

关键：webhook 回调地址由平台自动生成，用户永远不需要自己去 GitHub/GitLab/Gerrit 的 settings 里填 webhook URL；Agent 会通过 *_create_webhook（GitHub/GitLab/Gitee 走 REST API）或 git 协议（Gerrit 走 refs/meta/config）远端代配。

支持的平台与能力

平台	激活 skill	webhook 配置方式	审查回写	仓库搜索
Gerrit	`gerrit-integration`	Agent push `webhooks.config` 到 `refs/meta/config`；插件不在时走 cron 兜底	✅（Change / Patchset + 行级）	—
GitLab（社区版 / EE / 自建）	`gitlab-integration`	`gitlab_create_webhook` REST API	✅（MR Comment + Discussion）	✅
GitHub / GHE	`github-integration`	`github_create_webhook` REST API	✅（PR Review + Check Run）	✅
Gitee / Gitee Enterprise	`gitee-integration`	`gitee_create_webhook` REST API	✅（PR Comment）	✅

凭据类型（Agent 会通过 ask_user 弹窗问你要）

平台	凭据类型	权限最小范围
Gerrit	HTTP Password（`Settings → HTTP Credentials → Generate Password`）	目标项目 `Read` + `Label: Code-Review`；路径 A 还需 `Push: refs/meta/config`
GitLab	Personal Access Token（`glpat_...`）或 Project/Group Token	`api`, `read_repository`
GitHub	Personal Access Token（`ghp_...`，classic 或 fine-grained）	`repo`（或 fine-grained: `Pull requests: R/W`, `Contents: R`, `Checks: W`）
Gitee	Personal Access Token	`pull_requests`, `issues`, `hook`

不要用个人管理员 Token。出事无法吊销到人。优先用 Project Token / 机器账号 / GitHub App。

Agent 内部都做了什么（4 Step 流水线）

每个 SKILL.md 里都写死了这 4 步，Agent 不得跳步、不得换顺序。

Step 1：`ask_user` 收凭据 + 预检

Agent 在对话里弹一个输入框（不是普通文本），用户贴 Token 后，立即调 *_verify_token 到远端做连通性校验。校验失败会原样汇报错误，不做"自救"。

Step 2：`manage_scm_bot` 入库

manage_scm_bot(
  action="create",
  provider="github",
  instance_name="github-uu5208-ragbase",
  credentials_json='{"github_token":"ghp_xxx"}',
  config_json='{"repo":"uu5208/ragbase"}'
)

该工具：

再做一次远端预检（与 Step 1 相同 API），预检失败不入库——避免"验证过但库里没记录"的幽灵状态
写 tenant_channel_bot 表
返回完整的 webhook 回调地址，如 https://combo.example.com/webhook/github-uu5208-ragbase

这一步是最高频翻车点。Agent 有时会跳过 manage_scm_bot 直接去远端建 webhook，secret 自己 openssl rand 生成——结果平台路由表空，仓库推来的 webhook 全 404。SKILL.md 对此做了红字禁令。

Step 3：远端建 webhook（分平台两条路）

GitHub / GitLab / Gitee（REST API 路径）

github_create_webhook(
  owner="uu5208",
  repo="ragbase",
  instance_name="github-uu5208-ragbase"
  # webhook_url 留空，工具自动从 Step 2 结果拼
)

用户不用去 GitHub 的 Settings → Webhooks 页面，Agent 用你的 Token 直接远端建好。

Gerrit（git 协议路径 A）

Gerrit 没有 gerrit_create_webhook 这种 REST 工具——它的 webhook 必须写在项目的 refs/meta/config 分支的 webhooks.config 文件里。Agent 借 git skill + run_shell 一次性 clone → 写文件 → push：

[remote "ragbase"]
  url = <Step 2 返回的回调地址>
  event = patchset-created
  secret = <Step 2 config_json 里的随机 16 字节串>
  sslVerify = true

Gerrit 默认只订 patchset-created——绝不能加 comment-added / change-merged。原因：Agent 自己写的 gerrit_post_review / gerrit_post_comment 也归为 comment-added，订阅会立刻形成「审核 → 评论 → 被自己触发 → 再审核」死循环（真实事故：20 分钟烧 6 轮 LLM）。平台 event_filter 用 fnmatch 不支持正则否定，从源头掐断才是唯一正确做法。

Gerrit（cron 路径 B，兜底）

三种情况退回轮询：

Gerrit 服务端没装 plugins/webhooks
客户 policy 禁止改 refs/meta/config
沙盒出不了公网、无法到达 Gerrit

manage_cron_job(
  action="create",
  name="gerrit-poll-{project_slug}",
  schedule_type="every",
  schedule_value="10m",     # 最小 5m，推荐 10~15m
  prompt="gerrit_list_changes(query='project:{project} status:open') 与 last_seen 对比，只审增量"
)

路径 A 与 B 只能选一条。Agent 必须在 Step 3 前按决策表判定（URL 含 gerrithub.io → A；curl /plugins/ 列表含 webhooks → A；其余 → B）；中途不得自己换路径。路径 A 失败原因必须 ask_user 汇报，不得偷偷建 cron 当替代。

Step 4：`manage_event_trigger` 绑 prompt

manage_event_trigger(
  action="create",
  name="github-uu5208-ragbase-pr-review",
  source_type="webhook",
  source_bot_instance="github-uu5208-ragbase",
  event_filter='{"event_type":"pull_request"}',
  execution_mode="main",
  prompt="请根据以上 PR 事件执行代码审核：
  1. github_get_pr_diff 获取变更
  2. 逐文件分析代码质量、安全风险、bug
  3. github_post_pr_review 将审核结论回写"
)

prompt 字段就是未来事件触发时 Agent 执行的指令——这是 session 提示词驱动的本质：把"审核 PR"这条指令持久化下来，webhook 一到就原样回放。

Step 5：端到端 curl 验收（不得跳）

curl -sI "<Step 2 返回的回调地址>"

返回	判断
200 / 405	✅ 平台路由存在（405 = POST only），通了
404	❌ `tenant_channel_bot` 没记录，Step 2 写库失败了，必须 `ask_user` 汇报
连接超时	❌ `RAGFLOW_PUBLIC_URL` 没配对，或公网不可达

git push 成功 ≠ 链路通了。Gerrit 那头收了配置不代表平台这头接得住。必须 curl 过了才能声称"完成"。

触发后的执行回路

配置完成后，每次远端仓库有新 PR/patchset：

Rendering diagram…

EventTrigger 把 scm_tool_context 作为结构化数据注入 session——Agent 直接拿 pr_number / change_id 调工具，不需要自己解析 URL。

能力细节

代码审查回写

平台	评论粒度	决策标记
Gerrit	Change 级 + 行级	`Code-Review: +1/-1`, `Verified: +1/-1`
GitLab	MR 级 + 行级 + Discussion	Approve / Request changes
GitHub	PR 级 + 行级 + Check Run	Approve / Request changes, Check `success/failure`
Gitee	PR 级 + 行级	评论

海外 GitHub → 凭据 A（github-orgA-repoX）
国内自建 GitLab → 凭据 B（gitlab-team-backend）
内部 Gerrit → 凭据 C（gerrit-platform-core）

Agent 在会话里判断目标仓库的 URL 后自动路由到对应 bot 的 channel_context。

常见坑位

问题	解决
`curl` 验收 404	Step 2 写库失败了，不要继续，`ask_user` 汇报原始输出
Gerrit 回帖 403	凭据账号缺 `Label: Code-Review` 权限；机器人账号需项目管理员显式授权
GitHub 偶发 401	PAT 过期；或 GitHub App Installation Token 1 小时刷新失败，检查系统时钟
GitLab webhook 收不到	自建实例需在 Admin → Settings → Network → 勾选 `Allow requests to the local network`
Gerrit `fatal: couldn't find remote ref refs/meta/config`	`git clone` 默认不拉 meta refs，需 `git fetch origin refs/meta/config:refs/remotes/origin/meta/config`
Gerrit `not a registered email`	committer 邮箱必须是 Gerrit 注册邮箱——先调 `gerrit_get_me` 拿真实 email，不要硬编码
Gerrit 审核死循环	`webhooks.config` 里只能订 `patchset-created`，不要加 `comment-added`
大仓库 diff 慢	平台自动降级为"只看变更文件"；可在 Agent 侧配 `max_diff_kb`