用 git-rg 检索和修改代码仓库¶

需要查找或修改远端代码时，使用 git-rg Skill 和同名命令行工具；它无需克隆仓库历史即可读取不可变版本、预览完整 diff，并在明确授权后通过平台 API 创建新分支和 Draft PR/MR。

让 Agent 搜索代码¶

为 Agent 启用 git-rg Skill 后，在任务中给出仓库地址、分支和搜索目标。例如：

使用 git-rg，在 https://gitlab.example.com/team/service.git 的 main 分支查找请求超时配置，列出文件路径、行号和相关代码。

在 obscli 中可输入 $ 选择 git-rg Skill，再发送任务。公开仓库通常可匿名读取；私有仓库需要 Agent 运行环境中可用的仓库凭证。

只想为当前会话提供 Token 时，使用会话私密凭据，将名称设为 GITRG_TOKEN。不必修改容器环境或持久化 CLI 登录；会话关闭或 Agent 重启后失效。

让 Agent 修改远端代码¶

git-rg v0.5.0 起支持由 Agent 准备代码变更并创建 Draft PR/MR。写操作默认关闭，发布使用 GITRG_WRITE_TOKEN；GITRG_TOKEN 不能替代发布凭据。只设置写 Token 不会触发写入，每次发布仍必须显式传入 --enable-write。v0.6.0 起，只有写 Token 时也可用它完成读取和预览；同时提供两个 Token 时，读取优先使用 GITRG_TOKEN。

建议在任务中同时写明仓库、目标分支、变更要求、验证要求，以及是否授权创建 Draft PR/MR。例如：

使用 git-rg 读取 gitlab:team/service 的 main 分支，修复请求超时处理。先生成变更计划并执行 dry-run，把 diff 和无法本地执行的验证告诉我；确认没有冲突后，使用当前会话的 GITRG_WRITE_TOKEN 创建新分支和 Draft MR，不要合并。

为当前会话写入 GITRG_WRITE_TOKEN 的方法与只读 Token 相同。写 Token 应绑定单个仓库和专用身份；具体创建步骤和最小权限见添加 git-rg Token。不要把 Token 放入聊天、变更计划、命令参数或仓库文件。

Agent 应按以下流程工作：

用 env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN git-rg read --auth env --ref TARGET REPOSITORY PATH 读取完整文件，记录返回的 commit SHA 与 blob SHA；后续读取固定到同一 commit。
生成 JSON 变更计划。更新和删除必须带原始 expected_blob，content 是完整的新文件内容，不是补丁片段。
在同样清除 provider Token 后执行 git-rg propose --dry-run --auth env --changes changes.json REPOSITORY，检查不可变基线、文件冲突和完整 diff。dry-run 不修改远端，但 v0.6.0 起可在缺少 GITRG_TOKEN 时使用 GITRG_WRITE_TOKEN 读取。
只有任务已经授权发布时，才执行 git-rg propose --enable-write --changes changes.json REPOSITORY。成功结果必须同时检查 proposal.result.complete=true、新分支、commit 和 Draft PR/MR URL。
单独报告编译、测试和 CI 状态；complete=true 只表示远端提交和 Draft PR/MR 完整，不代表代码已验证或可以合并。

以下示例展示命令形态；实际计划中的 SHA 和完整文件内容必须来自同一次不可变读取：

env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg read --auth env --ref main gitlab:team/service path/to/file.go
env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg propose --dry-run --auth env --changes changes.json gitlab:team/service
git-rg propose --enable-write --changes changes.json gitlab:team/service

目标分支已经变化时会返回 base_changed，文件变化时会返回 blob_conflict；此时重新读取新快照并重新生成计划。来源分支已被无关内容占用时会返回 branch_conflict，git-rg 不会覆盖它。发布请求超时后，使用完全相同的计划、仓库和 Agent identity 重试，工具会检查远端状态并恢复，不要临时改 branch 或重复创建 MR。

第一版仅支持同仓库新分支和普通 UTF-8 文本文件，不支持更新已有分支、fork PR、二进制、symlink、submodule、自动合并或执行仓库测试。需要测试时使用 CI 或另一个具备代码执行环境的流程。

使用会话私密凭据¶

Agent 主机和容器不安装或依赖 gh、glab，也不要求在节点上登录代码托管平台。所有读取和预览命令都显式使用 --auth env，所有需要认证的 git-rg 用法都只从当前会话的私密凭据环境读取 Token；会话关闭、Agent 重启或断线后凭据失效，其他会话不会继承。

读取命令还要在子进程中清除 GITHUB_TOKEN、GH_TOKEN 和 GITLAB_TOKEN，避免 git-rg 读取 Agent 进程意外继承的 provider Token。确实要匿名访问公开仓库时，在该子进程中同时清除 GITRG_TOKEN 和 GITRG_WRITE_TOKEN；只省略读 Token 不保证匿名。

搜索、refs、read 和 dry-run 优先使用 GITRG_TOKEN。清除 provider Token 后，v0.6.0 起会在读 Token 缺失时使用 GITRG_WRITE_TOKEN；v0.5.0 没有这项回退。已有 Token 被平台拒绝时不会自动换身份重试。只读任务建议单独提供低权限读 Token：GitLab 私有项目使用仅限目标项目、Reporter 角色和 read_api scope 的 project access token；GitHub 使用仅授权目标仓库、具有 Contents: read 的细粒度 Token。公开仓库可匿名读取，但命令仍使用 --auth env，避免回退到节点登录状态。

创建 Draft PR/MR 只使用 GITRG_WRITE_TOKEN 完成发布所需的校验读取和写入，不回退到读 Token。GitHub 细粒度 Token 仅授权目标仓库，并设置 Contents: read and write 与 Pull requests: read and write；只有确实要修改 .github/workflows/ 时才增加 Workflows: read and write。GitLab project access token 使用 Developer 角色与 api scope，以创建非保护来源分支和 Draft MR；write_repository 不能替代 REST API 的 api scope。需要编辑时，v0.6.0 起一个同时具备读取和发布权限的写 Token 即可完成整个流程；日常只读任务仍建议使用低权限读 Token。不要把任何 Token 放进聊天消息、仓库 URL、变更计划或仓库文件。

在 obscli 的当前聊天中输入 /credentials，按任务需要写入 GITRG_TOKEN、GITRG_WRITE_TOKEN 或两者。Agent 只能看到凭据名称和类型，命令执行时由运行时注入实际值。详细操作见添加 git-rg Token。

最小命令示例¶

以下命令在 Agent 运行环境内执行，将示例仓库和分支替换为实际值。所有选项放在搜索文本和仓库地址之前。

# 列出自建 GitLab 仓库的分支和标签
env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg refs --auth env --provider gitlab https://gitlab.example.com/team/service.git

# 在指定分支搜索字面量，显示文件、行号和两行上下文
env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg --auth env --provider gitlab --ref main --format text -F -C 2 \
  'request_timeout' https://gitlab.example.com/team/service.git

# 搜索 GitHub 仓库中的 Go 文件
env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg --auth env --ref main --glob '*.go' --format text -F \
  'request_timeout' github:OWNER/REPO

所有读取命令都必须保留 --auth env。需要确认完整搜索结果时，使用默认 NDJSON 输出并检查末尾的 summary.complete；达到结果上限或只用索引搜索时，“未找到”不能证明仓库中不存在匹配内容。

私有仓库访问失败时，检查当前会话是否提供正确的 GITRG_TOKEN、站点是否正确以及仓库读取权限；不要在 Agent 节点登录或改用持久环境变量。自建 GitLab 使用 --provider gitlab；SSH 风格仓库地址不代表支持 SSH 密钥认证。

完整选项见 git-rg 使用说明。

用 git-rg 检索和修改代码仓库¶

让 Agent 搜索代码¶

让 Agent 修改远端代码¶

使用会话私密凭据¶

最小命令示例¶

文档内容是否对您有帮助？ ×

文档内容是否对您有帮助？