gh-gitlab
让
dsh-superagent的 GitHub Source 去监听一个 GitLab 项目 —— 不改官方插件一行代码。
dsh-superagent 的 Source 只支持 github.com(官方文档原话:GitHub Enterprise
Server is not supported)。但它的「智能体的 GitHub CLI」字段接受任意可执行文件,
而它所有的远端调用都只经过一个入口:gh api <path>。
于是有了这个桥:一个用 Node 实现的、gh 兼容的 CLI,把 GitHub REST 路径翻译成
GitLab API v4,再把 GitLab 的对象反向归一化成插件校验所需的 GitHub 形状。
issue 进来 → 授权门 → 评估 → 工单 → worker 在独立 worktree 里干活 → 回到 issue 评论回帖。 整条链路都能跑通,插件侧零改动。
GitLab issue / 评论
│ gh api repos/<group>/<project>/issues?since=…
▼
bin/gh-gitlab ──► /api/v4/projects/<id>/issues?updated_after=…
│ │
│ 归一化成 GitHub 形状 ◄┘
▼
dsh-superagent(Trigger → Policy 授权门 → Eval → Ticket → Worker)
│ gh api repos/…/issues/<iid>/comments --method POST -f body=…
▼
GitLab 评论回帖
它不是什么
- 不是官方插件,也没有被 DeepSeek 背书。它是一个社区兼容层,利用的是官方 明确留出的「CLI 可替换」这个口子。
- 不是 GitLab API 的完整封装。它只翻译
dsh-superagent真正会打的那些调用, 其余一律返回空的合法数据。哪些通、哪些不通,逐条写在 docs/LIMITATIONS.md,请先读它再决定要不要用。 - 不能推送代码。它能读 issue、能发评论,仅此而已。
快速开始
1. 准备一个智能体账号
插件会丢弃「智能体自己账号」发出的所有消息(否则会自问自答),所以智能体账号 必须和发起请求的人不同。
GitLab → 新建用户 my-agent-bot
→ 该项目 Members → 邀请 my-agent-bot,角色 Reporter
(Reporter 能读 issue、能发评论,但不能 push —— 这正是我们要的)
→ 用 my-agent-bot 登录 → Preferences → Access Tokens
→ 勾选 api scope → 生成,得到 glpat-…
2. 安装
两个平台是同一份源码,区别只在启动器和安装脚本:
| 平台 | CLI 入口 | 安装脚本 | 配置位置 |
|---|---|---|---|
| Linux / macOS / WSL | bin/gh-gitlab(sh) |
scripts/install.sh |
~/.config/gh-gitlab/credentials.json |
| Windows | bin/gh-gitlab.exe(安装时构建) |
scripts/install.ps1 |
%APPDATA%\gh-gitlab\credentials.json |
| 任意平台(临时调试) | node src/gh-gitlab.mjs |
— | $GH_GITLAB_CONFIG 指定的路径 |
Linux / macOS / WSL
git clone https://github.com/hoogte-oile/gh-gitlab.git
cd gh-gitlab
./scripts/install.sh # 链接到 ~/.local/bin + 生成配置模板
$EDITOR ~/.config/gh-gitlab/credentials.json
node scripts/doctor.mjs group/project
Windows(PowerShell)
git clone https://github.com/hoogte-oile/gh-gitlab.git
cd gh-gitlab
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
notepad $env:APPDATA\gh-gitlab\credentials.json
node scripts\doctor.mjs group/project
install.ps1 做四件事:校验 Node ≥ 20 → 把 windows/launcher.cs 编译成
bin\gh-gitlab.exe 并把 node 的绝对路径写进 bin\node-path.txt → 生成配置模板(首次)
→ 把 bin 加进用户 PATH(-NoPath 可跳过)。加 -- 到 PATH 只是方便你在终端里手动
调用;插件用的是绝对路径,不依赖 PATH。
为什么 Windows 需要
.exe:Node 的execFile()不能直接执行.cmd/.bat(会抛EINVAL),而插件正是用execFile()调这个 CLI。所以bin\gh-gitlab.cmd只给你在 cmd/PowerShell 里手动用,插件必须指向.exe。
WSL 特别注意:装在你运行 dsh-superagent 的那一侧。插件调用 CLI 的是它自己所在的
操作系统——服务跑在 WSL 里就在 WSL 里跑 install.sh(用 bin/gh-gitlab),服务跑在
Windows 上就构建 bin\gh-gitlab.exe。跨侧调用会以「找不到可执行文件」的方式失败。
credentials.json(两个平台内容相同):
{
"base": "https://gitlab.example.com",
"username": "my-agent-bot",
"token": "glpat-…"
}
令牌放在文件里,不要放环境变量。DSH 会把名字里含
KEY/TOKEN/SECRET的环境变量从子进程里剥掉,环境变量里的令牌会静默消失。
3. 接到插件上
把仓库的 Source 指向这个 CLI:
| 字段 | 值 |
|---|---|
repository |
group/project |
cli |
bin/gh-gitlab 或 bin/gh-gitlab.exe 的绝对路径 |
observeIssues |
开 |
observeComments |
开 |
observePulls / observeCi |
关(GitLab 侧没有对应物) |
保存方式(面板或本地管理 API)见 examples/source-config.md。
4. 验证
node scripts/doctor.mjs group/project # 账号、项目、issue 可读性
scripts/dsh-superagent status # 退出码 0 = setup 通过
然后在项目里开一个 issue,正文写上 @my-agent-bot 干点啥。一个轮询周期内,
Superagent 面板应出现一张 Ticket,随后 issue 下会出现回帖。
支持矩阵
| 能力 | 状态 | 说明 |
|---|---|---|
| 新 issue 触发工单 | ✅ | 仓库级 issue 流 |
| issue 评论回帖 | ✅ | 写 notes |
| 已有工单的后续评论 | ✅ | 走插件的 thread 轮询 |
| 未生成工单的 issue 评论 | ❌ | GitLab 没有仓库级评论流 |
| Merge request 触发 | ❌ | 未桥接 |
| inline review 评论 | ❌ | 未桥接 |
| CI / checks 状态 | ❌ | 未桥接 |
| 通知接口 | ❌ | 返回空,改走 issue 流 |
完整清单与后果:docs/LIMITATIONS.md。
已知坑
permissions.push是被合成出来的true。 插件的 setup 硬性要求账号「能推」, 否则拒绝启动,所以桥按它的期望回答。这不代表能推:本工具没有任何推送能力。 真正的封堵请在 git 层做(不给 remote,或 pre-push 钩子),并只给 Reporter 角色。- 部分 UI 链接会指向 github.com。 插件内部用
https://github.com/<repo>/…拼展示链接。回帖不受影响(回帖地址带的是 GitLab 的web_url),只是有些链接点开 404。 @提及受插件正则限制:用户名里含.或以-结尾时可能识别不到「点名」, 请求会从「明确」降级为「推断候选」。- 一个实例只能盯一个项目。 这是插件自身的设计(Source 按 kind 唯一),多项目
请起多个 profile + 多个端口 + 多个
stateDir。
安全
- 令牌需要
apiscope,权限不小。文件权限设成600,目录700。 - 只给 Reporter:能读、能评论、不能推。
- 建议给智能体单独的 OS 用户或独立容器运行 —— worker 会以宿主用户身份执行 shell。
- 出问题先吊销令牌:GitLab → Preferences → Access Tokens → Revoke。
排障
| 现象 | 原因与处理 |
|---|---|
The agent GitHub CLI cannot read its account + 401 |
令牌错、过期、或没勾 api scope |
414 Project Not Found / 404 |
账号不在项目成员里;或 repository 写错(要 group/project) |
| setup 通过但 issue 不触发 | observeIssues 没开;或发起人不在 Policy 白名单;或发起人就是智能体自己 |
| 工单生成了但不回帖 | 令牌缺写权限(Reporter 足够);或该 issue 被锁 |
已读但没反应 |
看 docs/LIMITATIONS.md:可能是未桥接的 MR / CI 事件 |
Windows 上 EINVAL |
用了 .cmd;改跑 scripts\install.ps1 或 scripts\build-launcher.ps1,指向产出的 .exe |
Linux 上 bad interpreter: /bin/sh^M |
检出时被转成 CRLF;git config core.autocrlf false 后重新检出(本仓库已用 .gitattributes 固定 LF) |
no such file or directory 指向 .exe |
服务跑在 WSL 而 CLI 是 Windows 侧产物,或反之;在服务所在的那一侧重新安装 |
调试时打开追踪:
# Linux / macOS / WSL
GH_GITLAB_TRACE=1 bin/gh-gitlab api user
# Windows
$env:GH_GITLAB_TRACE = '1'; .\bin\gh-gitlab.exe api user
开发
CI 在 ubuntu-latest 和 windows-latest 上都跑一遍(Node 20 / 22):
- 三个
.mjs的语法检查 - CLI 契约:
--version不依赖配置;配置缺失时退出码 2 且给出可操作提示 - 断言
bin/gh-gitlab与scripts/install.sh里没有 CRLF(否则 shebang 在execFile下必挂) - Windows 上构建
.exe并跑一次--version - Linux 上跑
scripts/install.sh并检查配置模板落盘
node --check src/gh-gitlab.mjs
node scripts/doctor.mjs group/project
背景
- 上游插件:deepseek-ai/dsh-superagent-prototype(MIT,研究原型)
- 运行宿主:deepseek-ai/deepseek-harness(DSH,MIT)
- 实测环境:DSH
0.2.1-rc.3+dsh-superagent8c32a9d,GitLab 18(该版本把 issue 显示为 “work items”,API 路径仍是/issues)
许可
MIT。与 DeepSeek 无隶属关系;上游插件本身声明为「仅供研究参考的原型,不是官方产品」, 本桥沿用同样的预期:先读懂它,再决定是否用在你在意的项目上。
No comments yet. Be the first to write one.