pingtai_agent/git_agent/USAGE.md

Git Agent 使用指南

概述

Git Agent 是一个通过 SSH 在远程 Azure 服务器上执行 Git 操作的 Agent。它为 OpenClaw 提供了完整的 Git 仓库管理能力，包括克隆、拉取、推送、提交等操作。

前置条件

1. Azure 云服务器

   • 已安装 Git
   • 已配置 SSH 访问
   • 有足够的磁盘空间存储代码

2. SSH 密钥

   • 用于连接 Azure 服务器的 SSH 私钥
   • 用于 Git 仓库认证的 SSH 私钥（需在 Git 服务器配置公钥）

3. 环境变量

   • SSH_HOST - Azure 服务器 IP 或域名
   • SSH_USER - SSH 用户名
   • SSH_PRIVATE_KEY - 连接服务器的 SSH 私钥（Base64 编码）
   • GIT_SSH_KEY - Git 仓库认证私钥（Base64 编码）

工具详解

1. git_clone - 克隆仓库

将远程 Git 仓库克隆到目标服务器。

参数：

参数	类型	必需	说明
repo_url	string	是	Git 仓库地址（支持 SSH/HTTPS）
target_dir	string	否	目标目录，默认从 URL 推断
branch	string	否	要克隆的分支

示例：

curl -X POST http://localhost:8000/api/v1/clone \
  -H "Content-Type: application/json" \
  -H "api-key: your-key" \
  -d '{
    "repo_url": "git@gitee.ath.cx:taijibaga/taiji-AI-PAD.git",
    "branch": "main"
  }'

返回：

{
  "success": true,
  "repo_url": "git@gitee.ath.cx:taijibaga/taiji-AI-PAD.git",
  "local_path": "/home/azureuser/projects/taiji-AI-PAD",
  "branch": "main",
  "commit": "abc1234",
  "message": "Clone 完成: git@gitee.ath.cx:taijibaga/taiji-AI-PAD.git -> /home/azureuser/projects/taiji-AI-PAD"
}

2. git_pull - 拉取代码

从远程仓库拉取最新代码。

参数：

参数	类型	必需	说明
work_dir	string	是	本地仓库目录路径
remote	string	否	远程名称，默认 origin
branch	string	否	要拉取的分支

示例：

curl -X POST http://localhost:8000/api/v1/pull \
  -H "Content-Type: application/json" \
  -H "api-key: your-key" \
  -d '{
    "work_dir": "/home/azureuser/projects/taiji-AI-PAD"
  }'

返回：

{
  "success": true,
  "local_path": "/home/azureuser/projects/taiji-AI-PAD",
  "branch": "main",
  "before_commit": "abc1234",
  "after_commit": "def5678",
  "files_changed": 5,
  "message": "Pull 完成: 5 个文件变更"
}

3. git_push - 推送代码

将本地代码推送到远程仓库。

参数：

参数	类型	必需	说明
work_dir	string	是	本地仓库目录路径
remote	string	否	远程名称，默认 origin
branch	string	否	要推送的分支
force	boolean	否	是否强制推送，默认 false

示例：

curl -X POST http://localhost:8000/api/v1/push \
  -H "Content-Type: application/json" \
  -H "api-key: your-key" \
  -d '{
    "work_dir": "/home/azureuser/projects/taiji-AI-PAD"
  }'

返回：

{
  "success": true,
  "local_path": "/home/azureuser/projects/taiji-AI-PAD",
  "remote": "origin",
  "branch": "main",
  "commits_pushed": 2,
  "force": false,
  "message": "Push 完成: 2 个 commit 推送到 origin/main"
}

4. git_commit - 提交变更

提交本地文件变更。

参数：

参数	类型	必需	说明
work_dir	string	是	本地仓库目录路径
message	string	是	提交信息
add_all	boolean	否	是否添加所有变更，默认 true

示例：

curl -X POST http://localhost:8000/api/v1/commit \
  -H "Content-Type: application/json" \
  -H "api-key: your-key" \
  -d '{
    "work_dir": "/home/azureuser/projects/taiji-AI-PAD",
    "message": "feat: 添加新功能"
  }'

返回：

{
  "success": true,
  "local_path": "/home/azureuser/projects/taiji-AI-PAD",
  "commit": "ghi9012",
  "files_committed": 3,
  "message": "Commit 完成: 3 个文件 (ghi9012)"
}

5. git_status - 查看状态

查看仓库当前状态。

参数：

参数	类型	必需	说明
work_dir	string	是	本地仓库目录路径

示例：

curl -X POST http://localhost:8000/api/v1/status \
  -H "Content-Type: application/json" \
  -H "api-key: your-key" \
  -d '{
    "work_dir": "/home/azureuser/projects/taiji-AI-PAD"
  }'

返回：

{
  "success": true,
  "local_path": "/home/azureuser/projects/taiji-AI-PAD",
  "branch": "main",
  "commit": "abc1234",
  "staged": ["file1.py", "file2.py"],
  "modified": ["file3.py"],
  "untracked": ["new_file.py"],
  "is_clean": false,
  "message": "2 staged, 1 modified, 1 untracked"
}

6. git_diff - 查看差异

查看文件变更内容。

参数：

参数	类型	必需	说明
work_dir	string	是	本地仓库目录路径
file_path	string	否	文件路径，不指定则显示所有
staged	boolean	否	是否查看暂存区，默认 false

示例：

curl -X POST http://localhost:8000/api/v1/diff \
  -H "Content-Type: application/json" \
  -H "api-key: your-key" \
  -d '{
    "work_dir": "/home/azureuser/projects/taiji-AI-PAD",
    "file_path": "src/main.py"
  }'

返回：

{
  "success": true,
  "local_path": "/home/azureuser/projects/taiji-AI-PAD",
  "file_path": "src/main.py",
  "staged": false,
  "diff": "--- a/src/main.py\n+++ b/src/main.py\n@@ -1,3 +1,4 @@\n+# New comment\n import os",
  "files_changed": 1,
  "insertions": 1,
  "deletions": 0
}

7. git_log - 查看历史

查看提交历史。

MCP 调用：

{
  "method": "tools/call",
  "params": {
    "name": "git_log",
    "arguments": {
      "work_dir": "/home/azureuser/projects/taiji-AI-PAD",
      "count": 5
    }
  }
}

返回：

{
  "success": true,
  "local_path": "/home/azureuser/projects/taiji-AI-PAD",
  "commits": [
    {"hash": "abc1234", "message": "feat: 添加新功能"},
    {"hash": "def5678", "message": "fix: 修复 bug"},
    {"hash": "ghi9012", "message": "docs: 更新文档"}
  ],
  "count": 3
}

通过 OpenClaw 使用

在 OpenClaw（如 Telegram）中，你可以这样使用：

1. 克隆仓库

   "帮我把 taiji-AI-PAD 仓库克隆到服务器"

2. 查看状态

   "查看一下 taiji-AI-PAD 项目的 git 状态"

3. 提交并推送

   "把 taiji-AI-PAD 的修改提交并推送，提交信息是'更新配置文件'"

错误处理

所有工具在失败时都会返回：

{
  "success": false,
  "error": "错误信息",
  "local_path": "/path/to/repo"
}

常见错误：

• SSH 连接错误 - 检查 SSH_HOST、SSH_USER、SSH_PRIVATE_KEY 配置
• Clone 失败 - 检查仓库地址和 GIT_SSH_KEY 配置
• Push 失败 - 检查是否有推送权限，GIT_SSH_KEY 是否正确

注意事项

1. SSH Key 格式

   • 必须是 Base64 编码
   • 支持 RSA、ED25519 等格式

2. 仓库地址

   • 推荐使用 SSH 协议：git@gitee.ath.cx:user/repo.git
   • 也支持 HTTPS（但需要额外配置认证）

3. 工作目录

   • 所有操作都在远程 Azure 服务器上执行
   • 确保目标目录有足够的磁盘空间