# GitIssue

**Repository Path**: boranli_admin/git-issue

## Basic Information

- **Project Name**: GitIssue
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-06
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitCode Agent Orchestrator

GitCode Agent Orchestrator 是一个面向 GitCode Issue 的自动化编码编排服务。它接收 GitCode Issue 和 Issue 评论 Webhook，把触发事件转换成后台任务，调用你配置的编码 Agent CLI 在独立工作区里修改代码，然后自动运行测试、提交、推送分支、创建 Pull Request，并把处理结果评论回原 Issue。

这个项目本身不内置具体 Agent。它通过通用 CLI 适配器接入 Codex、Claude Code、OpenClaw、CodeArts Agent、Hermes 或其他自定义 Agent CLI。只要该 CLI 能读取任务文件、修改当前仓库、写回结果文件，就可以接入。

## 当前可用状态

项目核心链路已经实现，并包含端到端测试：

- 接收 GitCode Issue / 评论 Webhook
- 校验 Webhook Token 和签名
- 解析 `/agent` 触发命令
- 去重重复 Webhook delivery
- 创建任务并入队
- worker clone 目标仓库并创建工作分支
- 写入 `.agent-task/` 任务上下文
- 调用配置的 Agent CLI
- 解析 Agent 输出决策
- 检查代码变更
- 运行仓库配置的测试命令
- commit、push、创建 GitCode Pull Request
- 评论处理结果到原 Issue

本地验证命令：

```bash
npm run build
npm test
```

注意：项目代码可用不等于部署后一定能处理所有仓库。生产可用还依赖这些外部条件：

- worker 运行环境已经安装并登录 Agent CLI，例如 `codex` 或 `claude`
- worker 可以 clone 和 push 目标 GitCode 仓库
- `GITCODE_TOKEN` 具备读取 Issue、评论、推送分支、创建 PR 的权限
- GitCode Webhook 可以访问你的公网 HTTPS 地址
- 目标仓库的测试命令可以在 worker 环境中正常执行

## 工作流程

```text
GitCode Issue / Issue 评论
  -> POST /webhooks/gitcode
  -> Webhook 校验和触发规则解析
  -> 创建 job
  -> 加入队列
  -> worker 消费 job
  -> clone 目标仓库
  -> checkout 默认分支
  -> 创建 agent/issue-xxx 工作分支
  -> 写入 .agent-task/instruction.md
  -> 运行 Agent CLI
  -> 读取 .agent-task/result.md
  -> 检查 git diff
  -> 运行 testCommands
  -> git commit
  -> git push
  -> 创建 GitCode Pull Request
  -> 评论原 Issue
```

## 技术栈

- Node.js 22+
- TypeScript
- Fastify
- PostgreSQL
- Redis / BullMQ
- Docker Compose
- Vitest

本地开发模式使用内存存储和内存队列。生产模式使用 PostgreSQL 存储任务、事件和日志，使用 Redis / BullMQ 分发任务。

## 目录结构

```text
src/
  api.ts              # 只启动 API 服务
  index.ts            # 开发模式：API + 内置 worker
  worker.ts           # 只启动 worker
  server.ts           # Fastify HTTP API
  webhook.ts          # GitCode Webhook 校验和解析
  workerRunner.ts     # 核心任务执行流程
  gitWorkspace.ts     # clone、分支、diff、commit、push
  gitcodeClient.ts    # GitCode API 客户端
  agentAdapter.ts     # 通用 Agent CLI 适配器
  taskFiles.ts        # .agent-task 文件生成
  verification.ts     # 测试命令执行
  store.ts            # 内存存储
  postgresStore.ts    # PostgreSQL 存储
  queue.ts            # 内存队列
  redisQueue.ts       # Redis / BullMQ 队列
tests/
  *.test.ts           # 单元和端到端测试
```

## 快速开始：本地开发

安装依赖：

```bash
npm install
```

复制配置：

```bash
cp config.example.yaml config.yaml
```

编辑 `config.yaml`，至少修改：

```yaml
gitcode:
  token: "${GITCODE_TOKEN}"
  webhookToken: "${GITCODE_WEBHOOK_TOKEN}"
  webhookSecret: "${GITCODE_WEBHOOK_SECRET}"

repositories:
  - fullName: "owner/repo"
    cloneUrl: "git@gitcode.com:owner/repo.git"
    defaultBranch: "main"
    autoRunOnNewIssue: false
    triggerLabel: "agent:run"
    testCommands:
      - "npm test"
```

启动开发模式：

```bash
npm run dev
```

开发模式会同时启动 HTTP API 和内置 worker。

健康检查：

```bash
curl http://127.0.0.1:3000/healthz
```

返回：

```json
{"ok":true}
```

如果要本地接收 GitCode Webhook，需要使用内网穿透工具，例如 ngrok、frp 或 cloudflared，把本地 `3000` 暴露成公网 HTTPS 地址。

## 编译和测试

编译：

```bash
npm run build
```

运行测试：

```bash
npm test
```

编译产物输出到 `dist/`：

```bash
node dist/src/api.js
node dist/src/worker.js
```

## 生产部署建议

正式使用建议部署到服务器，而不是本地电脑。原因是 GitCode Webhook 需要稳定访问你的公网 HTTPS 地址。

推荐架构：

```text
GitCode
  -> https://agent.example.com/webhooks/gitcode
  -> Nginx / Caddy
  -> API 服务 :3000
  -> Redis
  -> PostgreSQL
  -> worker 服务
  -> Agent CLI
  -> GitCode 仓库 clone / push
```

## 服务器部署方式一：Docker Compose

项目提供了 `docker-compose.yml`，包含：

- PostgreSQL
- Redis
- API 服务
- worker 服务

准备服务器环境：

```bash
sudo apt update
sudo apt install -y ca-certificates curl git
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
```

重新登录服务器后检查：

```bash
docker version
docker compose version
```

拉取项目：

```bash
git clone https://github.com/your-name/gitcode-agent-orchestrator.git
cd gitcode-agent-orchestrator
```

创建 `.env`：

```bash
cat > .env <<'EOF'
GITCODE_TOKEN=替换成你的GitCode访问Token
GITCODE_WEBHOOK_TOKEN=替换成一个长随机字符串
GITCODE_WEBHOOK_SECRET=替换成另一个长随机字符串
EOF
```

可以用下面命令生成随机字符串：

```bash
openssl rand -hex 32
```

编辑 `config.production.yaml`：

```yaml
repositories:
  - fullName: "你的组织/你的仓库"
    cloneUrl: "git@gitcode.com:你的组织/你的仓库.git"
    defaultBranch: "main"
    autoRunOnNewIssue: false
    triggerLabel: "agent:run"
    testCommands:
      - "npm test"
```

启动：

```bash
docker compose up -d
```

查看日志：

```bash
docker compose logs -f api
docker compose logs -f worker
```

健康检查：

```bash
curl http://127.0.0.1:3000/healthz
```

### Docker Compose 部署的重要说明

当前 `docker-compose.yml` 使用的是通用 `node:22` 镜像。这个镜像默认没有安装 Codex、Claude Code 或其他 Agent CLI。

如果直接使用当前 Compose 文件，API 可以启动，但 worker 在执行 Agent 时可能报错：

```text
spawn codex ENOENT
```

生产环境需要二选一：

- 在 worker 镜像里安装 Agent CLI
- 不用容器跑 worker，改用服务器宿主机安装 Agent CLI 并通过 systemd 跑 worker

下面给出两种方案。

## 集成 Agent CLI 到 worker 镜像

如果使用 Codex，新建 `Dockerfile.worker.codex`：

```dockerfile
FROM node:22

WORKDIR /app

RUN npm install -g @openai/codex

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

CMD ["node", "dist/src/worker.js"]
```

修改 `docker-compose.yml` 里的 worker：

```yaml
worker:
  build:
    context: .
    dockerfile: Dockerfile.worker.codex
  working_dir: /app
  environment:
    CONFIG_PATH: /app/config.production.yaml
    DATABASE_URL: postgres://gitcode_agent:gitcode_agent@postgres:5432/gitcode_agent
    REDIS_URL: redis://redis:6379
    GITCODE_TOKEN: ${GITCODE_TOKEN}
    GITCODE_WEBHOOK_TOKEN: ${GITCODE_WEBHOOK_TOKEN}
    GITCODE_WEBHOOK_SECRET: ${GITCODE_WEBHOOK_SECRET}
  volumes:
    - .:/app
    - workspaces:/app/.agent-workspaces
  depends_on:
    - postgres
    - redis
```

重新构建：

```bash
docker compose up -d --build
```

如果使用 Claude Code，新建 `Dockerfile.worker.claude`：

```dockerfile
FROM node:22

WORKDIR /app

RUN npm install -g @anthropic-ai/claude-code

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

CMD ["node", "dist/src/worker.js"]
```

然后把 compose 中的 `dockerfile` 改成：

```yaml
dockerfile: Dockerfile.worker.claude
```

注意：Agent CLI 通常需要登录或 API Key。容器化部署时，需要把相关环境变量、配置目录或凭证安全挂载进 worker 容器。不要把真实密钥提交到 GitHub。

## 服务器部署方式二：systemd 运行 API 和 worker

这个方式更适合早期上线调试，因为 Agent CLI 登录、SSH key、Git 权限都在宿主机上更容易排查。

安装 Node.js 22：

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
node -v
npm -v
```

安装依赖并编译：

```bash
cd /opt/gitcode-agent-orchestrator
npm ci
npm run build
```

只用 Docker 跑 PostgreSQL 和 Redis：

```yaml
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: gitcode_agent
      POSTGRES_USER: gitcode_agent
      POSTGRES_PASSWORD: gitcode_agent
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:7
    ports:
      - "6379:6379"

volumes:
  postgres-data:
```

保存为 `docker-compose.infra.yml`，启动：

```bash
docker compose -f docker-compose.infra.yml up -d
```

创建 API systemd 服务：

```bash
sudo nano /etc/systemd/system/gitcode-agent-api.service
```

内容：

```ini
[Unit]
Description=GitCode Agent API
After=network.target

[Service]
WorkingDirectory=/opt/gitcode-agent-orchestrator
Environment=CONFIG_PATH=/opt/gitcode-agent-orchestrator/config.production.yaml
Environment=DATABASE_URL=postgres://gitcode_agent:gitcode_agent@127.0.0.1:5432/gitcode_agent
Environment=REDIS_URL=redis://127.0.0.1:6379
EnvironmentFile=/opt/gitcode-agent-orchestrator/.env
ExecStart=/usr/bin/node dist/src/api.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

创建 worker systemd 服务：

```bash
sudo nano /etc/systemd/system/gitcode-agent-worker.service
```

内容：

```ini
[Unit]
Description=GitCode Agent Worker
After=network.target

[Service]
WorkingDirectory=/opt/gitcode-agent-orchestrator
Environment=CONFIG_PATH=/opt/gitcode-agent-orchestrator/config.production.yaml
Environment=DATABASE_URL=postgres://gitcode_agent:gitcode_agent@127.0.0.1:5432/gitcode_agent
Environment=REDIS_URL=redis://127.0.0.1:6379
EnvironmentFile=/opt/gitcode-agent-orchestrator/.env
ExecStart=/usr/bin/node dist/src/worker.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

启动：

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now gitcode-agent-api
sudo systemctl enable --now gitcode-agent-worker
```

查看日志：

```bash
journalctl -u gitcode-agent-api -f
journalctl -u gitcode-agent-worker -f
```

## 安装 Agent CLI

### Codex CLI

安装：

```bash
npm install -g @openai/codex
```

验证：

```bash
codex --version
```

首次登录：

```bash
codex
```

项目配置：

```yaml
agent:
  provider: "codex"
  command: "codex"
  args:
    - "exec"
    - "--sandbox"
    - "workspace-write"
    - "--input"
    - ".agent-task/instruction.md"
  timeoutMs: 3600000
  successExitCodes: [0]
```

### Claude Code

安装：

```bash
npm install -g @anthropic-ai/claude-code
```

验证：

```bash
claude --version
```

首次登录：

```bash
claude
```

项目配置：

```yaml
agent:
  provider: "claude-code"
  command: "claude"
  args:
    - "-p"
    - "@.agent-task/instruction.md"
  timeoutMs: 3600000
  successExitCodes: [0]
```

### 自定义 Agent CLI

示例：

```yaml
agent:
  provider: "custom"
  command: "my-agent"
  args:
    - "run"
    - "--task-file"
    - ".agent-task/instruction.md"
  timeoutMs: 3600000
  successExitCodes: [0]
```

参数中可以使用占位符：

```text
{instructionPath}
{resultPath}
{repoPath}
```

例如：

```yaml
args:
  - "run"
  - "--input"
  - "{instructionPath}"
  - "--output"
  - "{resultPath}"
  - "--repo"
  - "{repoPath}"
```

## 配置 GitCode 仓库权限

worker 需要 clone 和 push 目标仓库。

推荐使用 SSH clone URL：

```yaml
cloneUrl: "git@gitcode.com:你的组织/你的仓库.git"
```

在服务器上生成 SSH key：

```bash
ssh-keygen -t ed25519 -C "gitcode-agent" -f ~/.ssh/gitcode-agent
```

配置 SSH：

```bash
nano ~/.ssh/config
```

内容：

```sshconfig
Host gitcode.com
  HostName gitcode.com
  User git
  IdentityFile ~/.ssh/gitcode-agent
  IdentitiesOnly yes
```

把公钥添加到 GitCode：

```bash
cat ~/.ssh/gitcode-agent.pub
```

测试：

```bash
ssh -T git@gitcode.com
git ls-remote git@gitcode.com:你的组织/你的仓库.git
```

如果 worker 是 systemd 服务，请确保运行 systemd 服务的用户可以读取这个 SSH key。

如果 worker 是 Docker 容器，请把 SSH key 或 deploy key 安全挂载进 worker 容器，并配置 `~/.ssh/config`。

## 配置 HTTPS 反向代理

生产环境建议使用 HTTPS。下面以 Nginx 为例。

安装：

```bash
sudo apt install -y nginx certbot python3-certbot-nginx
```

创建配置：

```bash
sudo nano /etc/nginx/sites-available/gitcode-agent
```

内容：

```nginx
server {
    listen 80;
    server_name agent.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

启用：

```bash
sudo ln -s /etc/nginx/sites-available/gitcode-agent /etc/nginx/sites-enabled/gitcode-agent
sudo nginx -t
sudo systemctl reload nginx
```

申请证书：

```bash
sudo certbot --nginx -d agent.example.com
```

验证：

```bash
curl https://agent.example.com/healthz
```

## 配置 GitCode Webhook

在 GitCode 项目设置中添加 Webhook。

URL：

```text
https://你的域名/webhooks/gitcode
```

示例：

```text
https://agent.example.com/webhooks/gitcode
```

事件选择：

```text
Issue events
Note / Comment events
```

Token：

```text
填写 GITCODE_WEBHOOK_TOKEN 的值
```

Secret：

```text
填写 GITCODE_WEBHOOK_SECRET 的值
```

Webhook URL 必须指向 API 服务，不是 worker、PostgreSQL 或 Redis 地址。

## 使用方法

部署完成后，在 GitCode Issue 中触发 Agent。

### 方式一：Issue 标题或正文包含 `/agent`

```text
/agent
```

### 方式二：给 Issue 添加触发标签

默认标签：

```text
agent:run
```

可以通过仓库配置修改：

```yaml
triggerLabel: "agent:run"
```

### 方式三：Issue 评论命令

修复问题：

```text
/agent fix
```

实现需求：

```text
/agent implement
```

重新尝试：

```text
/agent retry
```

也支持解析：

```text
/agent run
/agent status
/agent cancel
```

当前 HTTP API 已支持查询、重试和取消排队任务。评论里的 `status` 和 `cancel` 命令目前只是被解析为命令类型，并没有完整实现“通过评论查询/取消已有任务”的交互逻辑。

### 运行结果

Agent 开始时会评论：

```text
Agent started processing this issue.

Job ID: xxx
```

如果成功，会评论 PR 地址：

```text
Agent completed the task and created a PR:

https://gitcode.com/owner/repo/pulls/1
```

如果 Agent 判断不需要改代码，会直接回复：

```text
Agent replied without code changes.
```

如果信息不足，会回复：

```text
Agent needs more information before changing code.
```

## HTTP API

健康检查：

```http
GET /healthz
GET /readyz
```

Webhook：

```http
POST /webhooks/gitcode
```

查询任务：

```http
GET /jobs/:id
```

重试任务：

```http
POST /jobs/:id/retry
```

取消排队任务：

```http
POST /jobs/:id/cancel
```

示例：

```bash
curl https://agent.example.com/jobs/任务ID
curl -X POST https://agent.example.com/jobs/任务ID/retry
curl -X POST https://agent.example.com/jobs/任务ID/cancel
```

取消接口目前只允许取消 `queued` 状态的任务，已经 `running` 的任务不会被中断。

## Agent 合约

worker 会在 clone 下来的目标仓库中创建：

```text
.agent-task/
  instruction.md
  issue.md
  comments.md
  context.json
  result.md
```

Agent 必须：

- 读取 `.agent-task/instruction.md`
- 根据任务修改仓库文件
- 如果需要，新增或更新测试
- 写入 `.agent-task/result.md`
- 不要 commit
- 不要 push
- 不要创建 Pull Request
- 不要直接评论 GitCode Issue
- 不要写入密钥或凭证

支持的结果 JSON：

```json
{"action":"code","summary":"Implemented the requested fix."}
```

```json
{"action":"reply","message":"This issue can be answered without code changes."}
```

```json
{"action":"needs_input","question":"Please provide the expected behavior."}
```

`.agent-task/` 会被写入 `.git/info/exclude`，不会被提交到目标仓库。

## 配置说明

完整配置示例：

```yaml
server:
  host: "0.0.0.0"
  port: 3000

storage:
  backend: "postgres"
  databaseUrl: "${DATABASE_URL}"

queue:
  backend: "redis"
  redisUrl: "${REDIS_URL}"
  name: "gitcode-agent-jobs"

gitcode:
  apiBaseUrl: "https://api.gitcode.com/api/v5"
  token: "${GITCODE_TOKEN}"
  webhookToken: "${GITCODE_WEBHOOK_TOKEN}"
  webhookSecret: "${GITCODE_WEBHOOK_SECRET}"
  botUsername: "gitcode-agent-bot"

agent:
  provider: "codex"
  command: "codex"
  args:
    - "exec"
    - "--sandbox"
    - "workspace-write"
    - "--input"
    - ".agent-task/instruction.md"
  timeoutMs: 3600000
  successExitCodes: [0]

workspace:
  rootDir: ".agent-workspaces"
  keepOnFailure: true

repositories:
  - fullName: "owner/repo"
    cloneUrl: "git@gitcode.com:owner/repo.git"
    defaultBranch: "main"
    autoRunOnNewIssue: false
    triggerLabel: "agent:run"
    testCommands:
      - "npm test"
```

字段说明：

- `server.host`：API 监听地址
- `server.port`：API 监听端口
- `storage.backend`：`memory` 或 `postgres`
- `queue.backend`：`memory` 或 `redis`
- `gitcode.apiBaseUrl`：GitCode API 地址
- `gitcode.token`：调用 GitCode API 的访问 Token
- `gitcode.webhookToken`：Webhook Token 校验值
- `gitcode.webhookSecret`：Webhook HMAC 签名密钥
- `gitcode.botUsername`：机器人用户名，用于避免机器人评论触发自己
- `agent.provider`：Agent 名称，仅用于记录
- `agent.command`：要执行的 CLI 命令
- `agent.args`：CLI 参数
- `agent.timeoutMs`：Agent 单次运行超时时间
- `workspace.rootDir`：worker 工作区目录
- `workspace.keepOnFailure`：失败时是否保留工作区，便于排查
- `repositories.fullName`：GitCode 仓库完整路径
- `repositories.cloneUrl`：worker clone/push 使用的地址
- `repositories.defaultBranch`：PR 目标分支
- `repositories.autoRunOnNewIssue`：新 Issue 是否自动触发
- `repositories.triggerLabel`：触发标签
- `repositories.testCommands`：Agent 修改代码后执行的测试命令

## Webhook 触发规则

支持：

- Issue 标题包含 `/agent`
- Issue 正文包含 `/agent`
- Issue label 等于配置的 `triggerLabel`
- 仓库配置 `autoRunOnNewIssue: true`
- Issue 评论以 `/agent fix` 开头
- Issue 评论以 `/agent implement` 开头
- Issue 评论以 `/agent retry` 开头
- Issue 评论以 `/agent run` 开头

会忽略：

- 未配置的仓库
- 非 Issue 评论
- system comment
- bot 自己发的评论
- 重复 delivery
- 同一个 Issue 已经有 queued/running 任务时的新触发
- 非 open 状态的 Issue

## 常见问题

### worker 报 `spawn codex ENOENT`

说明 worker 环境里没有 `codex` 命令。安装 Codex CLI，或者自定义 worker 镜像。

### worker clone 仓库失败

检查：

- `cloneUrl` 是否正确
- worker 是否有 SSH key
- SSH public key 是否添加到 GitCode
- systemd 服务或 Docker 容器是否能读取 SSH key
- `git ls-remote <cloneUrl>` 是否能成功

### push 分支失败

检查：

- SSH key 是否有写权限
- GitCode token 或 deploy key 是否允许 push
- 目标仓库是否限制了分支创建

### 创建 PR 失败

检查：

- `GITCODE_TOKEN` 是否有效
- Token 是否有创建 Pull Request 权限
- `gitcode.apiBaseUrl` 是否正确
- worker 日志里的 GitCode API 返回信息

### Agent 没有产生代码变更

如果 Agent 返回 `reply` 或 `needs_input`，这是正常行为。

如果 Agent 应该改代码但没有改，检查：

- `.agent-task/instruction.md` 是否生成正确
- Agent CLI 是否能读到任务文件
- Agent CLI 是否在目标仓库目录下执行
- Agent 是否写入 `.agent-task/result.md`

### 测试失败后会怎样

worker 会把 job 标记为 `test_failed`，不会创建 PR，并把测试摘要评论到 Issue。

### 任务失败后工作区在哪里

默认配置：

```yaml
workspace:
  rootDir: ".agent-workspaces"
  keepOnFailure: true
```

失败后工作区会保留在 `.agent-workspaces/<job-id>/repo`，方便排查。

## 安全建议

- 不要把 `.env`、Token、SSH private key 提交到 GitHub
- 给 worker 使用单独的低权限服务器用户
- 给 GitCode 使用最小权限 Token
- 生产 worker 建议使用专用镜像并限制权限
- 不要让 worker 处理不可信仓库，除非已经做好容器隔离和资源限制
- 定期更新 Agent CLI、Node.js 镜像和依赖

## 发布到 GitHub 前检查

```bash
npm run build
npm test
git status
```

确认不要提交：

```text
.env
config.yaml
.agent-workspaces/
node_modules/
dist/
```

当前 `.gitignore` 应包含这些内容。

## 许可证

请根据你的发布计划补充许可证，例如 MIT、Apache-2.0 或内部私有许可证。