一个 PAT 跑通自建 GitLab：TeamAI CLI 团队 AI 资产同步完整实录
【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cli
TeamAI CLI 是把 skills、rules、agents 等资源放进一个 Git 仓库自动分发的团队 AI 资产同步工具。如果你维护自建 GitLab 实例，希望团队的 AI 知识库完整留在内网，这篇实录演示完整链路：从安装 CLI 到自动建仓、创建 MR 与拉取，只需 2 个配置项，后续 push / pull 全部由一个 Personal Access Token 驱动。
先看效果：跑通后三条命令长什么样
配置完成后的日常形态，就是两条命令来回：
$ teamai push ✔ Pushed 3 resources ✔ Pull Request created: https://git.example.com/yourgroup/your-teamai/-/merge_requests/7 $ teamai pull ✔ Synced: 12 skills, 4 rules, 2 agents背后由 PAT 驱动的操作面如下，全部走 GitLab REST API v4，不需要安装任何平台 CLI：
| 操作 | 实现方式 |
|---|---|
| 克隆仓库 | git clone，token 经http.extraHeader注入，不落盘到.git/config |
| 自动建仓 | POST /api/v4/projects，按路径解析 Group，解析不到直接报错 |
| 创建 MR | POST /merge_requests，reviewer 用户名自动解析为 ID |
| 导入 MR 数据 | 标题 + 提交 + diff（截断 50KB），用于知识沉淀 |
| 列出 Group 仓库 | include_subgroups=true，覆盖子组，供批量导入 |
动手前检查：依赖、权限和唯一手动环节
| 项目 | 要求 | 确认方式 |
|---|---|---|
| Node.js | ≥ 20 | node -v |
| Git | 任意可用版本 | git --version |
| GitLab 账号 | 目标 Group 成员，可推分支、可建仓 | 浏览器打开 Group 确认 |
| PAT | apiscope | 见下一节 |
全程唯一需要登录 Web 界面的环节，就是去 GitLab 后台签发那个 token，其余步骤全部在终端完成。如果要看实现细节，源码在 src/providers/gitlab/，也可以git clone https://gitcode.com/GitHub_Trending/te/teamai-cli本地阅读。
如何拿到带 api 权限的 token
为什么是它：GitLab provider 的所有写操作（建仓、MR）都靠PRIVATE-TOKEN请求头里的这一个凭据，它是 API 的唯一入口。不配会怎样：init阶段就会提示GitLab authentication unavailable。
- 打开实例 → 头像 →User Settings → Access Tokens
- 勾选
api，设好有效期，创建后立即复制（形如glpat-xxxx）
export GITLAB_TOKEN=glpat-xxxxxxxx验证 token 与实例可达性：
curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "$GITLAB_URL/api/v4/user" | head -c 120返回你的账号 JSON 即通过。token 有三个名字按优先级生效：GITLAB_TOKEN>GITLAB_PRIVATE_TOKEN>GITLAB_PAT，空串和纯空白视为未设置，自动顺延下一个，兼容已有 CI 的命名习惯。
⚠️scope 只勾
read_api不行：克隆能过，但自动建仓和建 MR 会在第一次 push 时直接失败。
实例地址怎么配才不会指错地方
为什么需要它：GITLAB_URL决定 API 调用与克隆 URL 的落点；不配时默认回落到gitlab.com，自建实例的 token 会被发往公网，所以 CLI 对自建场景要求显式配置。
export GITLAB_URL=https://git.example.com配置时记住这四条规则：
| 规则 | 说明 |
|---|---|
| 必须带 scheme | 只写gitlab.example.com会报错退出，而不是静默指向公网实例 |
| 内网 http、非标端口原样保留 | http://10.0.0.5:8929会原样进入克隆 URL |
| 支持子路径部署 | 挂在https://example.com/gitlab下的实例写完整 base URL |
| 网关改写了 API 路径 | 加export GITLAB_API_PREFIX=api/gitlab，否则请求默认打到/api/v4 |
验证配置落点正确：
curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "$GITLAB_URL/api/v4/version"返回 JSON 版本信息即正确。多实例场景可用TEAMAI_GITLAB_HOST直接指定 host 覆盖，解析顺序是TEAMAI_GITLAB_HOST>GITLAB_URL推导 > 默认gitlab.com，逻辑见 src/providers/gitlab/repo-url.ts。
⚠️
TEAMAI_GITLAB_HOST与GITLAB_URL指向不同 host 时：CLI 会直接报错，拒绝猜测 token 属于哪个实例——这是防凭据外发的设计，不是 bug。
如何跑通第一条 teamai init
背景：init从仓库 URL 的 host 判断 provider，host 命中GITLAB_URL就进 gitlab provider。如果 host 完全未知，它会匿名请求该站登录页做一次探测（3 秒超时，不发送 token、不跟随重定向），确认是 GitLab 就停下来提示你补配置，绝不带着凭据盲试。这个设计很贴心：探测只是配置提示，不构成把 PAT 发往该地址的许可。
teamai init https://git.example.com/yourgroup/your-teamai成功后 provider 被写入团队仓库的teamai.yaml，此后所有人的push/pull都跟随这个值。验证初始化结果：
teamai doctor # 每一行都应通过 teamai status⚠️早期初始化为
provider: git的仓库有小坑：光补环境变量不生效，必须手动把teamai.yaml里的provider改成gitlab。push失败后的诊断会打印这条修复提示，但不会替你自动切换。
一个 PAT 解锁的其余能力
| 能力 | 说明 |
|---|---|
| 🔒 凭据不落盘 | 克隆时 token 用oauth2:基本认证经-c http.extraHeader临时注入，远程 URL 保持干净 |
| 建仓不跑偏 | 创建 project 时按 URL 编码的完整路径查 Group ID，查不到就报错，不会悄悄建到你的个人空间 |
| MR 导入防伪造 | MR 链接的 host 必须与已配置实例严格匹配（含端口、去www.），否则拒绝请求 |
| 子组全覆盖 | 列 Group 仓库默认带include_subgroups=true，子组下的项目不会漏 |
日常循环就剩：
teamai push # 资源推送并自动开 MR teamai pull # 拉取团队最新共享资源自检清单：交付团队前逐条过一遍
- ☐
GITLAB_URL以http(s)://开头，host 与浏览器地址栏完全一致（含端口与子路径） - ☐ PAT 勾选的是
api而不是read_api - ☐ token 值首尾无多余空白或换行，CI 里
$(cat token)记得 trim - ☐ 你的账号在目标 Group 有建仓权限，否则
init的自动建仓一步必挂 - ☐ 团队仓库
teamai.yaml的provider字段是gitlab而非git - ☐ 网关改写过 API 路径时已设置
GITLAB_API_PREFIX - ☐ 多实例场景下
TEAMAI_GITLAB_HOST与GITLAB_URL指向同一台实例
收尾
从签发 PAT 到第一条push/pull跑通，通常只需 10~15 分钟。更完整的 Provider 检测与命令细节见 docs/usage-guide.zh-CN.md 和 docs/guide/zh-CN/getting-started.md，GitLab provider 全部实现在 src/providers/gitlab/。
【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cli
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
