Skip to content

README.zh-CN.md

Latest commit

 

History

History
237 lines (177 loc) · 6.33 KB

README.zh-CN.md

File metadata and controls

237 lines (177 loc) · 6.33 KB
Raw

CodeHawk logo

面向 GitHub Pull Request 的 AI 辅助代码审查平台。

CodeHawk 是一个面向 GitHub Pull Request 的 AI 辅助代码审查平台。它接收 GitHub App webhook 事件，获取 PR 上下文，执行代码索引和静态分析任务，并将 PR 摘要或代码审查结果写回 GitHub。

English documentation: README.md

功能

  • GitHub App webhook 接收与签名校验。
  • 针对 PR opened 和 synchronize 事件生成 PR 摘要。
  • 使用 AI agent 生成结构化代码审查结果和 inline comments。
  • 使用 Ruff 和 Bandit 运行静态分析。
  • 使用 MinIO 存储仓库归档和 SAT 报告。
  • 对 Python 代码进行 chunk indexing，并写入 PostgreSQL。
  • 待实现：本地 Go CLI，用于审查 staged、unstaged 或全部未提交改动。
  • 使用 Docker Compose 启动 backend、MinIO 和 PostgreSQL。

技术栈

  • 后端：Python 3.14、FastAPI、httpx、Pydantic、structlog。
  • AI Agent：OpenAI Agents SDK。
  • 静态分析：Ruff、Bandit。
  • 存储：PostgreSQL、MinIO。
  • 容器：Docker、Docker Compose。
  • CLI：Go、Cobra。
  • 测试：pytest。
  • 包管理：Python 使用 uv，CLI 使用 Go modules。

架构

GitHub Pull Request Event
        |
        v
FastAPI Webhook Endpoint
        |
        v
GithubHandler
        |
        +--> PR Summary Service
        |       +--> PR Summary Agent
        |       +--> GitHub Issue Comment
        |
        +--> Code Indexing Service
        |       +--> Git Fetcher Container --> MinIO repo archive
        |       +--> SAT Runner Container --> MinIO SAT report
        |       +--> Code Chunker + Reference Parser --> PostgreSQL code index
        |       +--> Embedding Builder --> PostgreSQL pgvector
        |       +--> Convention Indexing --> Repository Convention KB
        |
        +--> Code Review Service
                +--> Workflow Run/Step State --> PostgreSQL
                +--> SAT Summary JSON Agent
                +--> Code Review Planning Agent
                +--> Structural Evidence Agent --> Code index queries
                +--> Convention Evidence Agent --> Convention KB + semantic search
                +--> Evidence Validator
                +--> Code Review Writer Agent
                +--> Patch-line Review Output Validator
                +--> GitHub PR Review

主要模块：

  • codehawk/api：FastAPI 路由和 webhook endpoint。
  • codehawk/handlers：GitHub webhook 事件分发。
  • codehawk/services：PR 摘要、代码审查、代码索引等工作流编排。
  • codehawk/agents：PR 摘要、SAT 摘要、评审规划、证据检索和 Review 生成 agents。
  • codehawk/github：GitHub 认证、installation token 缓存和 GitHub API client。
  • codehawk/minio：对象存储 URL 生成。
  • codehawk/postgresql：数据库连接，以及代码索引、embedding、仓库规范知识库和 Review workflow 状态仓库。
  • codehawk/code_index：仓库拉取、SAT runner、Python 代码 chunking、引用解析和 embedding 生成。
  • codehawk/models：DTO 和上下文模型。
  • codehawk/utils：确定性校验器和 OpenAI 重试辅助工具。

更多架构说明见 dev_docs/high_level_architecture.md。

安装

前置要求

  • Python 3.14+
  • uv
  • Docker 和 Docker Compose
  • Go 1.24+，用于 CLI
  • 一个 GitHub App，包括 webhook secret 和 private key
  • OpenAI API key

后端安装

  1. 复制环境变量模板：
cp .env.example .env
  1. 填写 .env 中的关键配置：
OPENAI_API_KEY=
GITHUB_WEBHOOK_SECRET=
GITHUB_APP_CLIENT_ID=
GITHUB_PRIVATE_KEY_PATH=
MINIO_ACCESS_KEY=
MINIO_SECRET_KEY=
MINIO_BUCKET=repos
POSTGRES_DB=codehawk
POSTGRES_USER=codehawk
POSTGRES_PASSWORD=codehawk
  1. 安装 Python 依赖：
uv sync
  1. 启动本地基础设施和后端：
docker compose up --build

后端默认地址：

http://localhost:8300

健康检查：

curl http://localhost:8300/health

GitHub webhook endpoint：

POST /webhook/github

GitHub App 配置

将 GitHub App 的 webhook URL 配置为：

https://<your-public-host>/webhook/github

GitHub App 需要读取 repository contents 和 pull requests，并具备写入 PR review 或 issue comment 的权限。GITHUB_PRIVATE_KEY_PATH 需要指向 GitHub App private key，Docker Compose 会将它只读挂载到后端容器中。

CLI

CLI 位于 cli/。

CLI 工具仍在开发中。命令、配置字段以及 API 集成行为在稳定版本发布前可能会调整。

构建 CLI：

cd cli
go build -o codehawk .

初始化仓库配置：

./codehawk config init

审查 staged 改动：

./codehawk review --type staged

支持的 review type：

staged, unstaged, all

如果设置了 CODEHAWK_API_URL，CLI 会将 review 请求发送到该 endpoint。否则，CLI 会直接打印生成的请求 payload。

CLI 配置文件是 .codehawk.yaml。配置说明见 cli/docs/configuration-reference.md。

开发

运行测试：

uv run pytest

不使用 Docker 直接启动后端：

uv run fastapi dev codehawk/main.py

手动运行静态检查：

uv run ruff check .
uv run bandit --format=json --quiet -r .

环境变量

重要环境变量：

变量 说明
OPENAI_API_KEY OpenAI API key，用于 agents。
GITHUB_WEBHOOK_SECRET 用于校验 GitHub webhook 签名。
GITHUB_APP_CLIENT_ID GitHub App client ID。
GITHUB_PRIVATE_KEY_PATH GitHub App private key 的本地路径。
MINIO_ENDPOINT 后端容器访问 MinIO 的 API endpoint。
MINIO_ACCESS_KEY MinIO access key。
MINIO_SECRET_KEY MinIO secret key。
MINIO_BUCKET 用于存储仓库归档和 SAT 报告的 bucket。
POSTGRES_HOST PostgreSQL hostname。
POSTGRES_DB PostgreSQL database name。
POSTGRES_USER PostgreSQL user。
POSTGRES_PASSWORD PostgreSQL password。

完整配置见 .env.example。

当前状态

CodeHawk 仍在开发中。当前实现重点覆盖 GitHub PR 摘要、静态分析、代码索引和 AI 辅助 PR review 工作流。