pingtai_agent/git_agent/README.md

Git Agent

通过 SSH 在远程 Azure 服务器上执行 Git 操作的 Agent，为 OpenClaw 提供 Git 仓库管理能力。

功能特性

• git_clone - 克隆远程仓库到目标服务器
• git_pull - 拉取远程仓库最新代码
• git_push - 推送本地代码到远程仓库（SSH Key 认证）
• git_commit - 提交本地变更
• git_status - 查看仓库状态
• git_diff - 查看文件变更
• git_log - 查看提交历史

架构

OpenClaw → Git Agent (AKS) → SSH → Azure 服务器 → Git 仓库

快速开始

环境变量

# 必需 - SSH 连接配置
export SSH_HOST=your-azure-server-ip
export SSH_USER=azureuser
export SSH_PRIVATE_KEY=base64-encoded-ssh-private-key

# 必需 - Git SSH Key（用于仓库认证）
export GIT_SSH_KEY=base64-encoded-git-ssh-key

# 可选
export SSH_PORT=22
export GIT_WORK_DIR=/home/azureuser/projects
export GIT_USERNAME="Git Agent"
export GIT_EMAIL="git-agent@taiji.io"
export API_HOST=0.0.0.0
export API_PORT=8000

本地运行

# 安装依赖
pip install -r requirements.txt

# 启动服务
python run_api_server.py

Docker 运行

# 构建镜像
docker build -t git-agent .

# 运行容器
docker run -p 8000:8000 \
  -e SSH_HOST=your-server-ip \
  -e SSH_USER=azureuser \
  -e SSH_PRIVATE_KEY=base64-key \
  -e GIT_SSH_KEY=base64-git-key \
  git-agent

API 端点

端点	方法	描述
/	GET	服务状态
/health	GET	健康检查
/mcp	POST	MCP JSON-RPC
/mcp/sse	GET/POST	MCP SSE 流式
/api/v1/clone	POST	克隆仓库
/api/v1/pull	POST	拉取代码
/api/v1/push	POST	推送代码
/api/v1/commit	POST	提交变更
/api/v1/status	POST	查看状态
/api/v1/diff	POST	查看差异
/api/v1/tools	GET	获取工具列表

MCP 工具

工具名称	功能
git_clone	克隆远程仓库到目标服务器
git_pull	拉取远程仓库最新代码
git_push	推送本地代码到远程仓库
git_commit	提交本地变更
git_status	查看仓库状态
git_diff	查看文件变更
git_log	查看提交历史

使用示例

克隆仓库

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",
    "target_dir": "/home/azureuser/projects/taiji-AI-PAD"
  }'

响应：

{
  "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 完成"
}

推送代码

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"
  }'

项目结构

git_agent/
├── Dockerfile
├── README.md
├── USAGE.md
├── requirements.txt
├── run_api_server.py
├── common/
│   ├── __init__.py
│   └── agent_callback_utils.py
└── src/
    ├── __init__.py
    └── server/
        ├── __init__.py
        ├── api_server.py      # FastAPI + MCP HTTP
        ├── mcp_server.py      # MCP 工具定义
        └── ssh_client.py      # SSH 连接管理

SSH Key 配置

1. 生成 SSH Key（如果没有）

ssh-keygen -t ed25519 -C "git-agent@taiji.io" -f ~/.ssh/git_agent_key

2. 在 Git 服务器配置公钥

将 ~/.ssh/git_agent_key.pub 的内容添加到 Git 服务器的 SSH Keys 中。

3. Base64 编码私钥

# Linux/macOS
cat ~/.ssh/git_agent_key | base64 -w 0

# Windows PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("$HOME\.ssh\git_agent_key"))

4. 设置环境变量

export GIT_SSH_KEY="base64编码后的私钥内容"

安全注意事项

1. SSH 私钥保护

   • 私钥通过环境变量传入，不硬编码
   • 运行时写入临时文件，设置 600 权限
   • 操作完成后清理临时文件

2. API 认证

   • 所有 API 端点需要 api-key 认证
   • 支持 Header: api-key 或 Authorization: Bearer <key>

3. 网络安全

   • 建议 Agent 和目标服务器在同一 VNet
   • 使用 SSH 加密通信

许可证

MIT License