跳到正文
Sigil 掌玺
Esc
本栏目菜单

Git 平台能力

Sigil 里能力数量最多的一块:查仓库、提 issue、开 PR、发 release、看 CI。AI 调这些工具时,Token 由金库在内部注入,它既看不到也要不到。

平台是参数,不是工具名

早期版本给每个平台各做一套工具:github_repo_list、gitee_repo_list、gitcode_repo_list —— 同一件事三个名字。结果是工具列表里大量重复项,AI 每次都要先挑平台再挑动作,挑错了就报「能力不存在」。

现在收敛成一个工具通吃三家:

调用 git_repo_list(credential_name = "gitee")
                        │
                        └─ 凭据类型是 gitee_token
                           → 自动打 Gitee 的接口

platform 参数可以不传 —— 平台从 credential_name 的凭据类型推断出来。显式传了就必须和凭据平台一致,否则直接报错(防止拿 A 平台的 Token 去打 B 平台的接口,那只会得到一个莫名其妙的 401)。

从旧版本升级

gitee_repo_list / github_issue_create 这类带平台前缀的旧名字已经不存在。如果你在提示词、脚本或自己的 MCP 客户端里写死过它们,需要改成对应的 git_* 名字。

Sigil 会在升级后提示你更新写进 CLAUDE.md / AGENTS.md 的规则段(见 MCP Server · 写规则),那份规则里的工具名是自动同步的。

三家统一的能力

分类 能力
仓库 git_repo_list / git_repo_get / git_repo_search / git_repo_create / git_repo_update / git_repo_delete
代码 git_commits_list / git_branches_list / git_tags_list / git_file_get / git_file_put / git_file_delete
协作 git_issues_list / git_issue_create / git_issue_update / git_issue_comment / git_pulls_list / git_pr_create / git_pr_merge
发布 git_release_create / git_release_delete
账号 git_user_info

几条要留意的:

  • 建仓一律私有。git_repo_create 的 private 被强制为 true,入参覆盖不了 —— 需要公开仓请到平台网页端手动改可见性。
  • 删仓要双重确认。除了桌面端弹窗,调用方还必须把 confirm_name 填成与仓库全名完全一致的字符串,防止模型一次幻觉就删掉整个仓库。
  • issue 编号两种写法都收。GitHub 是数字(42),Gitee / GitCode 可能是字母数字串(I8ABCD),传哪种都能用。

本地 Git

这两个跑的是本机的 git 命令,不是平台接口:

能力 说明
git_clone 克隆到本地目录
git_push 推送。Token 不进 URL、不进命令行参数、不落盘

强制推送只需要把 force 设成 true。Sigil 内部会自动读远端当前状态作安全基准 —— 既能覆盖重写过的历史,又能在远端被别人改动时拒绝覆盖。不开放裸的强制推送。

强推会触发桌面端的阻塞式确认(普通推送不会)。

Gitee / GitCode 的用户名

这两家推送时必须填真实登录账号;GitHub 用默认值即可。拿不准就调 list_credentials 看一眼,Sigil 写进规则文件的凭据映射表里也有。

更完整的本地仓库操作(暂存、提交、看 diff、管分支)见 Git 工作区。

GitHub 专属

有些能力只有 GitHub 提供对应接口,没法并进统一工具:

分类 能力
Actions / CI github_run_wait / github_runs_list / github_run_get / github_run_jobs / github_run_rerun / github_rerun_failed_jobs / github_run_cancel / github_run_artifacts / github_workflow_list / github_workflow_dispatch / github_actions_enable
Release github_release_list / github_release_get / github_release_publish / github_release_asset_upload / github_release_generate_notes
下载 github_release_download_all / github_download_artifact / github_download_release_asset / github_download_run_logs
Secrets / 变量 github_repo_secret_list / github_repo_secret_set / github_repo_variable_list / github_repo_variable_set / github_repo_variable_delete
引用 github_ref_create / github_ref_delete / github_ref_get
仓库管理 github_repo_update / github_collaborator_add / github_deploy_key_add / github_branch_protection_set / github_workflow_permissions_set
其他 github_billing_actions / github_repository_dispatch

其中分支保护、协作者、部署密钥、工作流权限、Actions 开关属于安全态变更,一律走阻塞式确认。

查 CI 别用轮询脚本

等 CI 跑完用 github_run_wait(v2.5.0 起):Sigil 内部按间隔查询,跑完一次性返回结果,可以只等某几个 job,超时也不报错、再调一次接着等。github_run_jobs 在「全部 job 失败却没有失败步骤」时会额外提示疑似额度耗尽 —— 这种情况看日志是看不出来的。

发版镜像产物时用 github_release_download_all 一次下载整个 release(并发、断点续传、已下载的跳过),不要逐个调 github_download_release_asset。

GitLab

GitLab 的接口路径风格和上面三家不同构,所以单独成组,共 24 个能力,覆盖面与统一工具基本对齐:仓库增删改查、文件读写、issue、合并请求、release、分支 / 提交 / tag 列表、账号信息。

调用时传 base_url 可以指向自建 GitLab,不填则用 gitlab.com。

没存 GitLab 凭据就看不到这组工具

这是按凭据渐进披露的效果:金库里没有 gitlab_token 时,这 24 个工具不会出现在 AI 的工具列表里。存一条进去,它们立刻出现,不用重启。

一个典型流程

「把改动推上去,然后确认远端收到了」:

workspace_stage   →  暂存改动
workspace_commit  →  提交
git_push          →  推送(Token 由金库注入)
git_commits_list  →  查远端最新提交,核对 hash 与本地一致

最后一步容易被跳过,但它是唯一能确认「推上去了」的办法 —— 推送命令返回成功,不代表远端真的更新了(比如远端已是最新时,什么都没推也算成功)。

相关章节

  • Git 工作区 —— 本地仓库的暂存 / 提交 / 分支管理
  • 发布与签名 —— 把产物发到 Maven Central、给安装包签名
  • 能力体系 —— 能力的确认分级与注解
  • MCP Server —— 工具列表如何按凭据动态变化