jeffusion/archived-gitea-ai-assistant
1
0
Fork 0
mirror of https://github.com/jeffusion/gitea-ai-assistant.git synced 2026-03-27 10:05:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(readme): reorganize docs and screenshot gallery

Browse Source 
Align project docs with current behavior using progressive disclosure and bilingual deep-dive guides. Add per-page admin screenshots with consistent page-* naming to make UI documentation clearer.
This commit is contained in:
jeffusion
2026-03-24 15:43:57 +08:00
committed by 路遥知码力
parent 63f419228e
commit c313764b61
18 changed files with 647 additions and 445 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
README.md
View File

@@ -2,50 +2,48 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
AI-powered code review assistant for Gitea. Automatically reviews Pull Requests and commits using pluggable LLM providers (OpenAI Compatible, OpenAI Responses API, Anthropic, Google Gemini), providing intelligent code quality analysis with both summary comments and line-level feedback.
AI-powered code review assistant for Gitea. It receives webhooks, runs staged AI review workflows, and posts summary + line-level feedback back to Gitea.
**[中文文档](./docs/README.zh-CN.md)**
- English docs: [./docs/README.md](./docs/README.md)
- 中文文档: [./docs/README.zh-CN.md](./docs/README.zh-CN.md)
## Features
## Why this project
- 🤖 **AI Code Review** - Automatic review of PRs and commits using pluggable LLM providers
- 📝 **Line-Level Comments** - Precise feedback on specific code changes
- 🔄 **Task-Based Review Engines** - Agent staged review (skip/light/full) plus optional Codex CLI execution mode
- 🔔 **Feishu Notifications** - Integrated notification system for PR events
- 🎛️ **Admin Dashboard** - Web UI for managing repository webhooks and LLM provider configuration
- 🔐 **Secure Webhooks** - HMAC-SHA256 signature verification
- 🤖 **Automated PR + commit review** via webhook events (`pull_request`, `status`)
- 🧠 **Two review engines**: `agent` (staged tasks) and `codex` (Codex CLI pipeline)
- 🧵 **Pluggable LLM providers**: OpenAI Compatible, OpenAI Responses API, Anthropic, Gemini
- 📍 **Actionable output**: summary comments and line-level findings
- 🎛️ **Web Admin UI** for runtime configuration (providers, models, webhook, review policy)
- 🔔 **Notifications**: Feishu + WeCom (企业微信)
- 🔐 **Security-first defaults**: webhook signature verification + encrypted API key storage
## Architecture
## Product screenshot
> Dashboard screenshot is generated from local dev service.
![Gitea AI Assistant Dashboard - Repository Page](./docs/assets/page-repos.png)
More screenshots (one per admin menu): [EN](./docs/screenshots.md) | [中文](./docs/screenshots.zh-CN.md)
## Architecture (high-level)
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Gitea Server │────▶│ Gitea Assistant │────▶│ LLM Gateway │
│ (Webhooks) │ │ (Hono + Bun) │ │ (Multi-Provider)│
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
▼ ├─ OpenAI Compatible
┌──────────────────┐ ├─ OpenAI Responses API
│ Admin Dashboard │ ├─ Anthropic
│ (React SPA) │ └─ Google Gemini
└──────────────────┘
Gitea Webhook -> Gitea AI Assistant (Hono + Bun) -> LLM Gateway (multi-provider)
|
+-> Admin Dashboard (React)
```
### Review Engines
For component-level design, see [Architecture docs](./docs/README.md#architecture--design).
| Engine | Description | Use Case |
|--------|-------------|----------|
| `agent` | Task-based staged review (`skip` / `light` / `full`) with scoped specialist routing and optional reflection/debate escalation | Deep reviews with token-aware execution |
| `codex` | Codex CLI review execution with independent configuration | External Codex-driven review pipeline |
## Quick start (minimal)
## Quick Start
### 1) Prerequisites
### Prerequisites
- Bun >= 1.2.5
- Reachable Gitea instance
- At least one LLM provider credential
- [Bun](https://bun.sh/) >= 1.2.5
- Gitea instance with API access
- At least one LLM provider API key (OpenAI, Anthropic, Google Gemini, or any OpenAI-compatible endpoint)
### Installation
### 2) Install
```bash
git clone https://github.com/user/gitea-ai-assistant.git
@@ -53,196 +51,53 @@ cd gitea-ai-assistant
bun install
```
> `bun install` at repository root now triggers frontend dependency installation automatically via `postinstall`.
> If your environment skips lifecycle scripts, run `bun run bootstrap` once.
### Configuration
Create a `.env` file with only infrastructure-level settings:
If lifecycle scripts are disabled in your environment, run:
```bash
bun run bootstrap
```
### 3) Minimal `.env`
```bash
# Server port
PORT=5174
# REQUIRED: encryption key for API key storage (generate with: openssl rand -hex 32)
ENCRYPTION_KEY=
# Optional: custom database path (default shown)
ENCRYPTION_KEY= # required, 64 hex chars (openssl rand -hex 32)
# DATABASE_PATH=./data/assistant.db
```
> **All other configuration** (Gitea connection, webhook secret, admin password, review engine, Feishu, memory settings, etc.) is managed through the **Admin Dashboard Web UI** at `http://your-server:5174`. On first boot, all settings are seeded with secure defaults automatically.
> `ENCRYPTION_KEY` is mandatory. The app refuses to start without it.
See [Configuration Reference](#configuration-reference) for all options.
### Running
### 4) Run
```bash
bun run dev # Development mode
bun run start # Production mode
bun run dev
# or
bun run start
```
### Setting Up Webhooks
### 5) Configure in Admin UI
**Option 1: Admin Dashboard (Recommended)**
Open `http://your-server:5174`, login with default `password` (first boot only), then change it immediately.
1. Access `http://your-server:5174`
2. Log in with the admin password (default: `password` — change it in the dashboard)
3. Click "Enable" on repositories to auto-configure webhooks
- Configure Gitea API + tokens
- Configure webhook secret
- Configure LLM providers/models
- Configure review engine and policy
**Option 2: Manual Configuration**
### 6) Add webhook in Gitea
In Gitea repository settings, add a webhook:
- **URL**: `http://your-server:5174/webhook/gitea`
- **Content Type**: `application/json`
- **Secret**: Same as the Webhook Secret configured in the dashboard
- **Events**: "Pull Request" and "Status"
## Configuration Reference
- URL: `http://your-server:5174/webhook/gitea`
- Content-Type: `application/json`
- Secret: same as dashboard webhook secret
- Events: Pull Request + Status
### Environment Variables (Minimal)
## Progressive disclosure: detailed docs
Only infrastructure-level settings that must be known before the database is initialized:
| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `5174` |
| `DATABASE_PATH` | SQLite database file path | `./data/assistant.db` |
| `ENCRYPTION_KEY` | **Required.** AES-256-GCM encryption key for API key storage (64 hex chars). Generate with `openssl rand -hex 32` | — |
### Web UI Configuration (Admin Dashboard)
All runtime configuration is managed through the **Admin Dashboard** at `http://your-server:PORT`. Changes take effect immediately without restart.
On first boot with an empty database, all settings are seeded with secure defaults:
- `JWT_SECRET` and `WEBHOOK_SECRET` are auto-generated (64-char hex via `crypto.randomBytes`)
- `ADMIN_PASSWORD` defaults to `password` — **change this immediately**
#### Gitea
| Setting | Description |
|---------|-------------|
| Gitea API URL | Gitea API endpoint (e.g. `https://gitea.example.com/api/v1`) |
| Access Token | Token for code review (read + comment permissions) |
| Admin Token | Token for webhook management (optional) |
#### Security
| Setting | Description | Default |
|---------|-------------|---------|
| Webhook Secret | HMAC-SHA256 webhook signature secret | Auto-generated |
| Admin Password | Dashboard login password | `password` |
| JWT Secret | JWT signing secret | Auto-generated |
#### LLM Provider Configuration
LLM providers and models are configured exclusively through the **Admin Dashboard** Web UI:
1. Navigate to **LLM 配置** (LLM Configuration)
2. Add your LLM providers (OpenAI Compatible, OpenAI Responses API, Anthropic, Google Gemini)
3. Assign models to review roles (planner, specialist, judge, embedding)
> API keys are stored encrypted (AES-256-GCM) in the local SQLite database.
#### Feishu Integration
| Setting | Description |
|---------|-------------|
| Feishu Webhook URL | Feishu bot webhook URL |
| Feishu Webhook Secret | Feishu webhook secret (optional) |
#### Agent Review Engine
| Setting | Description | Default |
|---------|-------------|---------|
| Review Engine | Engine mode (`agent` or `codex`) | `agent` |
| Enable Triage | Enable planner triage for task routing | `true` |
| Small Max Files | Upper file-count bound for `small` review size | `3` |
| Small Max Changed Lines | Upper changed-lines bound for `small` review size | `80` |
| Medium Max Files | Upper file-count bound for `medium` review size | `10` |
| Medium Max Changed Lines | Upper changed-lines bound for `medium` review size | `400` |
| Token Budget Small | Token budget cap for `small` staged tasks | `12000` |
| Token Budget Medium | Token budget cap for `medium` staged tasks | `45000` |
| Token Budget Large | Token budget cap for `large` staged tasks | `120000` |
| Review Work Directory | Working directory for repo clones | `/tmp/gitea-assistant` |
| Max Parallel Runs | Max concurrent review tasks | `2` |
| Max Files per Run | Max files analyzed per review | `200` |
| Auto-publish Min Confidence | Min confidence score for auto-publish | `0.8` |
| Enable Human Gate | Require human approval before publishing | `true` |
Agent review execution model (current):
- `skip`: docs/assets/rename-only style changes can bypass specialist review.
- `light`: low-risk code changes run minimal scoped specialist checks.
- `full`: sensitive or larger changes run full specialist tasks, with optional reflection/debate escalation.
- Triage outputs task scopes (`paths`, `riskTags`, `mode`, `tokenBudget`) and orchestrator dispatches specialists by task scope instead of broad fan-out.
#### Memory & Learning (Experimental)
| Setting | Description | Default |
|---------|-------------|---------|
| Qdrant URL | Qdrant vector database URL | - |
| Enable Memory | Enable memory system | `false` |
| Enable Reflection | Enable self-critique | `false` |
| Enable Debate | Enable multi-agent debate | `false` |
## Deployment
### Docker
```bash
docker build -t gitea-assistant .
docker run -d -p 5174:5174 -v ./data:/app/data -e PORT=5174 gitea-assistant
```
### Docker Compose
```bash
docker-compose up -d
```
### Kubernetes
Kubernetes manifests are located in the `k8s/` directory.
**1. Create the encryption secret**
```bash
# Generate a key and create the secret
kubectl apply -f k8s/namespace.yaml
ENCRYPTION_KEY=$(openssl rand -hex 32)
kubectl -n gitea-assistant create secret generic gitea-assistant-secret \
--from-literal=ENCRYPTION_KEY=$ENCRYPTION_KEY
# Save this key! You'll need it if you ever redeploy.
echo "Your ENCRYPTION_KEY: $ENCRYPTION_KEY"
```
**2. Deploy**
```bash
kubectl apply -k k8s/
```
Or apply individually:
```bash
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/qdrant.yaml
kubectl apply -f k8s/gitea-assistant.yaml
```
**4. Verify**
```bash
kubectl -n gitea-assistant get pods
kubectl -n gitea-assistant get svc
```
**5. Expose the Service (optional)**
By default, services use `ClusterIP`. To expose externally, use an Ingress or change the Service type:
```bash
kubectl -n gitea-assistant patch svc gitea-assistant -p '{"spec":{"type":"NodePort"}}'
```
- [Documentation index](./docs/README.md)
- [Getting started details](./docs/getting-started.md)
- [Configuration reference](./docs/configuration.md)
- [Review engines](./docs/review-engines.md)
- [Deployment (Docker / Compose / Kubernetes)](./docs/deployment.md)
## License

21
docs/README.md Normal file
View File

@@ -0,0 +1,21 @@
# Documentation
This project keeps the root `README.md` concise and moves implementation/deployment details here.
## Start here
- [Getting started](./getting-started.md)
- [Configuration reference](./configuration.md)
- [Review engines](./review-engines.md)
- [Deployment](./deployment.md)
- [Screenshot gallery](./screenshots.md)
## Architecture & design
- [Pluggable LLM providers](./design/pluggable-llm-providers.md)
- [Notification service refactoring](./design/notification-service-refactoring.md)
- [UI theme language](./design/ui-theme-language.md)
## Language
- 中文： [README.zh-CN.md](./README.zh-CN.md)

256
docs/README.zh-CN.md
View File

@@ -1,249 +1,25 @@
# Gitea AI Assistant
# 文档中心
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
根目录 `README.md` 保持简洁；本目录提供详细说明与设计文档。
基于 AI 的 Gitea 代码审查助手。自动审查 Pull Request 和提交，支持多种 LLM 提供商（OpenAI 兼容、OpenAI Responses API、Anthropic、Google Gemini），提供智能代码质量分析，支持总体评论和行级反馈。
## 快速导航
**[English Documentation](../README.md)**
- [快速开始](./getting-started.zh-CN.md)
- [配置参考](./configuration.zh-CN.md)
- [审查引擎](./review-engines.zh-CN.md)
- [部署指南](./deployment.zh-CN.md)
- [截图集](./screenshots.zh-CN.md)
## 功能特点
## 架构与设计
- 🤖 **AI 代码审查** - 使用可插拔的 LLM 提供商自动审查 PR 和提交
- 📝 **行级评论** - 针对具体代码变更的精确反馈
- 🔄 **任务化审查引擎** - Agent 分级审查（skip/light/full）+ 可选 Codex CLI 审查模式
- 🔔 **飞书通知** - PR 事件通知集成
- 🎛️ **管理后台** - 用于管理仓库 Webhook 和 LLM 提供商配置的 Web 界面
- 🔐 **安全验证** - HMAC-SHA256 签名验证
- [可插拔 LLM 提供商设计](./design/pluggable-llm-providers.md)
- [通知服务重构设计](./design/notification-service-refactoring.md)
- [UI 主题语言设计](./design/ui-theme-language.md)
## 架构设计
## 产品截图
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Gitea 服务器 │────▶│ Gitea Assistant │────▶│ LLM 网关 │
│ (Webhooks) │ │ (Hono + Bun) │ │ (多提供商) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
▼ ├─ OpenAI 兼容
┌──────────────────┐ ├─ OpenAI Responses API
│ 管理后台 │ ├─ Anthropic
│ (React SPA) │ └─ Google Gemini
└──────────────────┘
```
![Gitea AI Assistant 管理后台（仓库管理页）](./assets/page-repos.png)
### 审查引擎对比
## 语言切换
| 引擎 | 描述 | 适用场景 |
|------|------|----------|
| `agent` | 任务化分级审查（`skip` / `light` / `full`），按路径范围派发 specialist，并按需升级到反思/辩论 | 在控制 token 成本的前提下做深度审查 |
| `codex` | 通过 Codex CLI 执行审查，独立配置 | 对接外部 Codex 审查流程 |
## 快速开始
### 环境要求
- [Bun](https://bun.sh/) >= 1.2.5
- 可访问的 Gitea 实例
- 至少一个 LLM 提供商的 API 密钥（OpenAI、Anthropic、Google Gemini 或任何 OpenAI 兼容端点）
### 安装步骤
```bash
git clone https://github.com/user/gitea-ai-assistant.git
cd gitea-ai-assistant
bun install
```
> 在仓库根目录执行 `bun install` 会通过 `postinstall` 自动安装 `frontend` 依赖。
> 若你的环境跳过生命周期脚本，请额外执行一次 `bun run bootstrap`。
### 配置说明
创建 `.env` 文件，仅填写基础设施级别的配置：
```bash
# 服务端口
PORT=5174
# 必填：API Key 加密存储密钥（运行 openssl rand -hex 32 生成）
ENCRYPTION_KEY=
# 可选：自定义数据库路径（以下为默认值）
# DATABASE_PATH=./data/assistant.db
```
> **所有其他配置**（Gitea 连接、Webhook 密钥、管理员密码、审查引擎、飞书、记忆系统等）均通过 **Web 管理后台** 在 `http://your-server:5174` 进行配置。首次启动时，所有设置会自动以安全的默认值进行初始化。
完整配置项请参阅 [配置参考](#配置参考)。
### 启动服务
```bash
bun run dev # 开发模式
bun run start # 生产模式
```
### 配置 Webhook
**方式一：管理后台（推荐）**
1. 在浏览器中访问 `http://your-server:5174`
2. 使用管理员密码登录（默认：`password`，请在后台及时修改）
3. 点击仓库对应的「启用」按钮自动配置 Webhook
**方式二：手动配置**
在 Gitea 仓库设置中添加 Webhook：
- **URL**: `http://your-server:5174/webhook/gitea`
- **内容类型**: `application/json`
- **密钥**: 与管理后台中配置的 Webhook 密钥相同
- **触发事件**: 「Pull Request」和「Status」
## 配置参考
### 环境变量（最小化）
仅包含数据库初始化前必须已知的基础设施级别配置：
| 变量 | 描述 | 默认值 |
|------|------|--------|
| `PORT` | 服务端口 | `5174` |
| `DATABASE_PATH` | SQLite 数据库文件路径 | `./data/assistant.db` |
| `ENCRYPTION_KEY` | **必填。** AES-256-GCM 加密密钥，用于加密存储 API Key（64 位十六进制字符串）。运行 `openssl rand -hex 32` 生成 | — |
### Web 界面配置（管理后台）
所有运行时配置均通过 **管理后台** `http://your-server:PORT` 进行管理，修改后立即生效，无需重启。
首次以空数据库启动时，所有设置会自动以安全默认值初始化：
- `JWT_SECRET` 和 `WEBHOOK_SECRET` 自动生成（通过 `crypto.randomBytes` 生成 64 位十六进制字符串）
- `ADMIN_PASSWORD` 默认为 `password`，**请立即修改**
#### Gitea
| 配置项 | 描述 |
|--------|------|
| Gitea API 地址 | Gitea API 端点（如 `https://gitea.example.com/api/v1`） |
| 访问令牌 | 代码审查令牌（需读取和评论权限） |
| 管理员令牌 | Webhook 管理令牌（可选） |
#### 安全
| 配置项 | 描述 | 默认值 |
|--------|------|--------|
| Webhook 密钥 | HMAC-SHA256 Webhook 签名密钥 | 自动生成 |
| 管理员密码 | 后台登录密码 | `password` |
| JWT 密钥 | JWT 签名密钥 | 自动生成 |
#### LLM 提供商配置
LLM 提供商和模型通过**管理后台** Web 界面进行配置：
1. 导航到 **LLM 配置** 页面
2. 添加 LLM 提供商（OpenAI 兼容、OpenAI Responses API、Anthropic、Google Gemini）
3. 为审查角色分配模型（planner、specialist、judge、embedding）
> API 密钥使用 AES-256-GCM 加密存储在本地 SQLite 数据库中。
#### 飞书集成
| 配置项 | 描述 |
|--------|------|
| 飞书 Webhook 地址 | 飞书机器人 Webhook URL |
| 飞书 Webhook 密钥 | 飞书 Webhook 密钥（可选） |
#### Agent 审查引擎
| 配置项 | 描述 | 默认值 |
|--------|------|--------|
| 审查引擎 | 引擎模式（`agent` 或 `codex`） | `agent` |
| 启用分流（Enable Triage） | 启用 planner 分流并输出任务化审查计划 | `true` |
| Small 文件上限 | 判定 `small` 规模审查的文件数上限 | `3` |
| Small 变更行上限 | 判定 `small` 规模审查的变更行数上限 | `80` |
| Medium 文件上限 | 判定 `medium` 规模审查的文件数上限 | `10` |
| Medium 变更行上限 | 判定 `medium` 规模审查的变更行数上限 | `400` |
| Small Token 预算 | `small` 任务的 token 预算上限 | `12000` |
| Medium Token 预算 | `medium` 任务的 token 预算上限 | `45000` |
| Large Token 预算 | `large` 任务的 token 预算上限 | `120000` |
| 工作目录 | 仓库克隆工作目录 | `/tmp/gitea-assistant` |
| 最大并发数 | 最大并发审查任务数 | `2` |
| 最大文件数 | 单次审查最大文件数 | `200` |
| 自动发布置信度 | 自动发布最小置信度 | `0.8` |
| 启用人工审批 | 发布前要求人工确认 | `true` |
当前 Agent 审查执行模型：
- `skip`：文档/资源/纯重命名等低风险改动可直接跳过 specialist。
- `light`：低风险代码改动执行最小化、按路径范围限定的 specialist 审查。
- `full`：敏感路径或中大型改动执行完整任务审查，并可按配置升级到 reflection/debate。
- Triage 输出任务（`paths`、`riskTags`、`mode`、`tokenBudget`），Orchestrator 按任务范围派发，不再默认全量扇出。
#### 记忆与学习（实验性）
| 配置项 | 描述 | 默认值 |
|--------|------|--------|
| Qdrant 地址 | Qdrant 向量数据库地址 | - |
| 启用记忆 | 启用记忆系统 | `false` |
| 启用反思 | 启用自我批评 | `false` |
| 启用辩论 | 启用多代理辩论 | `false` |
## 部署指南
### Docker
```bash
docker build -t gitea-assistant .
docker run -d -p 5174:5174 -v ./data:/app/data -e PORT=5174 gitea-assistant
```
### Docker Compose
```bash
docker-compose up -d
```
### Kubernetes
Kubernetes 部署清单位于 `k8s/` 目录。
**1. 创建加密密钥**
```bash
# 生成密钥并创建 Secret
kubectl apply -f k8s/namespace.yaml
ENCRYPTION_KEY=$(openssl rand -hex 32)
kubectl -n gitea-assistant create secret generic gitea-assistant-secret \
--from-literal=ENCRYPTION_KEY=$ENCRYPTION_KEY
# 请保存此密钥！重新部署时需要使用。
echo "你的 ENCRYPTION_KEY: $ENCRYPTION_KEY"
```
**2. 部署**
```bash
kubectl apply -k k8s/
```
或逐个应用：
```bash
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/qdrant.yaml
kubectl apply -f k8s/gitea-assistant.yaml
```
**4. 验证**
```bash
kubectl -n gitea-assistant get pods
kubectl -n gitea-assistant get svc
```
**5. 暴露服务（可选）**
默认使用 `ClusterIP` 类型。如需外部访问，可使用 Ingress 或修改 Service 类型：
```bash
kubectl -n gitea-assistant patch svc gitea-assistant -p '{"spec":{"type":"NodePort"}}'
```
## 许可证
MIT 许可证
- English: [README.md](./README.md)

0
docs/assets/.gitkeep Normal file
View File

BIN
docs/assets/page-config.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 196 KiB

BIN
docs/assets/page-notifications.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 190 KiB

BIN
docs/assets/page-repos.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 126 KiB

BIN
docs/assets/page-review-config.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 197 KiB

77
docs/configuration.md Normal file
View File

@@ -0,0 +1,77 @@
# Configuration Reference
## Configuration model
This project uses a DB-first runtime configuration model:
- `.env` contains only infrastructure-level bootstrap values.
- Runtime settings (Gitea, providers, secrets, review policy, notifications) are managed in Admin UI and stored in SQLite.
## Environment variables (minimal)
| Variable | Required | Description | Default |
|---|---|---|---|
| `ENCRYPTION_KEY` | Yes | AES-256-GCM master key (64 hex chars) for API key encryption | - |
| `PORT` | No | Service port | `5174` |
| `DATABASE_PATH` | No | SQLite path | `./data/assistant.db` |
Generate key:
```bash
openssl rand -hex 32
```
## First boot defaults
When database is empty:
- `JWT_SECRET` auto-generated
- `WEBHOOK_SECRET` auto-generated
- `ADMIN_PASSWORD` defaults to `password`
Change `ADMIN_PASSWORD` immediately after first login.
## Runtime groups in Admin UI
## 1) Gitea
- API URL
- Access token
- Admin token (optional)
## 2) Security
- Webhook secret (HMAC-SHA256 verification)
- Admin password
- JWT secret
## 3) LLM
- Providers: OpenAI Compatible / OpenAI Responses / Anthropic / Gemini
- Role mapping: planner, specialist, judge, embedding
## 4) Notification
- Feishu webhook and optional secret
- WeCom (企业微信) webhook
## 5) Review
- Engine mode: `agent` or `codex`
- Triage switch
- Size thresholds (`small`/`medium`/`large`)
- Execution modes (`skip`/`light`/`full`)
- Token budgets and concurrency limits
> Size and mode are different layers:
>
> - `small/medium/large`: change-size classification
> - `skip/light/full`: review execution depth
## 6) Memory & learning (optional)
- `ENABLE_MEMORY` (default `false`)
- Qdrant URL
- Reflection/debate toggles
Qdrant is only required when memory is enabled.

77
docs/configuration.zh-CN.md Normal file
View File

@@ -0,0 +1,77 @@
# 配置参考
## 配置模型
项目采用 DB-first 运行时配置模型：
- `.env` 仅用于基础设施级引导参数
- 运行时配置（Gitea、Provider、密钥、审查策略、通知）由管理后台维护并持久化到 SQLite
## 环境变量（最小集）
| 变量 | 必填 | 说明 | 默认值 |
|---|---|---|---|
| `ENCRYPTION_KEY` | 是 | API Key 加密主密钥（AES-256-GCM，64 位十六进制） | - |
| `PORT` | 否 | 服务端口 | `5174` |
| `DATABASE_PATH` | 否 | SQLite 路径 | `./data/assistant.db` |
生成密钥：
```bash
openssl rand -hex 32
```
## 首次启动默认值
当数据库为空时：
- `JWT_SECRET` 自动生成
- `WEBHOOK_SECRET` 自动生成
- `ADMIN_PASSWORD` 默认 `password`
首次登录后请立即修改管理员密码。
## 管理后台配置分组
## 1) Gitea
- API URL
- Access Token
- Admin Token（可选）
## 2) 安全
- Webhook Secret（HMAC-SHA256 验签）
- Admin Password
- JWT Secret
## 3) LLM
- Provider：OpenAI Compatible / OpenAI Responses / Anthropic / Gemini
- 角色模型：planner、specialist、judge、embedding
## 4) 通知
- Feishu Webhook 与可选签名密钥
- WeCom（企业微信）Webhook
## 5) 审查
- 引擎模式：`agent` / `codex`
- Triage 开关
- 规模阈值（`small`/`medium`/`large`）
- 执行模式（`skip`/`light`/`full`）
- Token 预算与并发限制
> 规模与模式是两个层次：
>
> - `small/medium/large`：变更规模分类
> - `skip/light/full`：审查执行深度
## 6) 记忆与学习（可选）
- `ENABLE_MEMORY`（默认 `false`）
- Qdrant URL
- Reflection / Debate 开关
仅在开启记忆能力时需要 Qdrant。

61
docs/deployment.md Normal file
View File

@@ -0,0 +1,61 @@
# Deployment
## Docker
```bash
docker build -t gitea-assistant .
docker run -d -p 5174:5174 -v ./data:/app/data -e PORT=5174 gitea-assistant
```
## Docker Compose
```bash
docker compose up -d
```
`docker-compose.yml` includes both:
- `gitea-assistant`
- `qdrant`
If you do not use memory features, Qdrant can be optional in custom compose setups.
## Kubernetes
Kubernetes manifests are in `k8s/`.
### 1) Create namespace and encryption secret
```bash
kubectl apply -f k8s/namespace.yaml
ENCRYPTION_KEY=$(openssl rand -hex 32)
kubectl -n gitea-assistant create secret generic gitea-assistant-secret \
--from-literal=ENCRYPTION_KEY=$ENCRYPTION_KEY
```
### 2) Deploy
```bash
kubectl apply -k k8s/
```
Or apply individually:
```bash
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/qdrant.yaml
kubectl apply -f k8s/gitea-assistant.yaml
```
### 3) Verify
```bash
kubectl -n gitea-assistant get pods
kubectl -n gitea-assistant get svc
```
### 4) Expose service (optional)
```bash
kubectl -n gitea-assistant patch svc gitea-assistant -p '{"spec":{"type":"NodePort"}}'
```

61
docs/deployment.zh-CN.md Normal file
View File

@@ -0,0 +1,61 @@
# 部署指南
## Docker
```bash
docker build -t gitea-assistant .
docker run -d -p 5174:5174 -v ./data:/app/data -e PORT=5174 gitea-assistant
```
## Docker Compose
```bash
docker compose up -d
```
`docker-compose.yml` 默认包含：
- `gitea-assistant`
- `qdrant`
如果不使用记忆能力，可在自定义编排中将 Qdrant 设为可选。
## Kubernetes
Kubernetes 清单位于 `k8s/` 目录。
### 1) 创建命名空间与加密密钥
```bash
kubectl apply -f k8s/namespace.yaml
ENCRYPTION_KEY=$(openssl rand -hex 32)
kubectl -n gitea-assistant create secret generic gitea-assistant-secret \
--from-literal=ENCRYPTION_KEY=$ENCRYPTION_KEY
```
### 2) 部署
```bash
kubectl apply -k k8s/
```
或逐个应用：
```bash
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/qdrant.yaml
kubectl apply -f k8s/gitea-assistant.yaml
```
### 3) 验证
```bash
kubectl -n gitea-assistant get pods
kubectl -n gitea-assistant get svc
```
### 4) 对外暴露（可选）
```bash
kubectl -n gitea-assistant patch svc gitea-assistant -p '{"spec":{"type":"NodePort"}}'
```

68
docs/getting-started.md Normal file
View File

@@ -0,0 +1,68 @@
# Getting Started
## Prerequisites
- Bun >= 1.2.5
- A reachable Gitea instance
- At least one LLM provider credential
## Install
```bash
git clone https://github.com/user/gitea-ai-assistant.git
cd gitea-ai-assistant
bun install
```
`bun install` at repository root installs frontend dependencies via `postinstall`.
If lifecycle scripts are disabled:
```bash
bun run bootstrap
```
## Minimal environment
Create `.env`:
```bash
PORT=5174
ENCRYPTION_KEY= # required, generate with: openssl rand -hex 32
# DATABASE_PATH=./data/assistant.db
```
> `ENCRYPTION_KEY` is required. Application startup fails when it is missing.
## Run
```bash
bun run dev
# or
bun run start
```
## First login
- Open `http://your-server:5174`
- Default admin password is `password` on first boot
- Change admin password immediately after login
## Webhook setup
### Option A: Admin UI (recommended)
In repository list, click enable to auto-provision webhook.
### Option B: Manual
In Gitea repository settings:
- URL: `http://your-server:5174/webhook/gitea`
- Content Type: `application/json`
- Secret: same value as dashboard webhook secret
- Events: Pull Request + Status
## Health endpoint
Use `/api/health` to check service status.

68
docs/getting-started.zh-CN.md Normal file
View File

@@ -0,0 +1,68 @@
# 快速开始
## 环境要求
- Bun >= 1.2.5
- 可访问的 Gitea 实例
- 至少一个 LLM 提供商凭证
## 安装
```bash
git clone https://github.com/user/gitea-ai-assistant.git
cd gitea-ai-assistant
bun install
```
在仓库根目录执行 `bun install` 会通过 `postinstall` 自动安装 `frontend` 依赖。
如果你的环境禁用了生命周期脚本：
```bash
bun run bootstrap
```
## 最小环境变量
创建 `.env` 文件：
```bash
PORT=5174
ENCRYPTION_KEY= # 必填，使用 openssl rand -hex 32 生成
# DATABASE_PATH=./data/assistant.db
```
> `ENCRYPTION_KEY` 为必填项，缺失时服务会拒绝启动。
## 启动服务
```bash
bun run dev
# 或
bun run start
```
## 首次登录
- 访问 `http://your-server:5174`
- 首次启动默认管理员密码为 `password`
- 登录后请立即修改管理员密码
## Webhook 配置
### 方式 A：管理后台（推荐）
在仓库列表点击启用按钮，由系统自动配置 webhook。
### 方式 B：手动配置
在 Gitea 仓库设置中配置：
- URL：`http://your-server:5174/webhook/gitea`
- Content Type：`application/json`
- Secret：与管理后台中的 Webhook Secret 保持一致
- 事件：Pull Request + Status
## 健康检查
可通过 `/api/health` 查看服务状态。

46
docs/review-engines.md Normal file
View File

@@ -0,0 +1,46 @@
# Review Engines
## Overview
The system supports two engines:
- `agent`: native staged review pipeline
- `codex`: Codex CLI-backed review pipeline
Engine is selected by `REVIEW_ENGINE` runtime configuration.
## Agent engine
Agent engine classifies changes and dispatches specialist tasks.
### Review modes
- `skip`: low-risk changes may bypass specialist review
- `light`: minimal specialist checks for low-risk code changes
- `full`: full specialist review for risky or larger changes
### Size policy
`small`/`medium`/`large` thresholds are used by triage to choose mode and token budgets.
## Codex engine
Codex engine runs review through Codex CLI with independent runtime settings:
- `CODEX_API_URL`
- `CODEX_API_KEY`
- `CODEX_MODEL`
- `CODEX_TIMEOUT_MS`
- `CODEX_REVIEW_PROMPT`
## Event support
Both engines process:
- Pull request webhook events
- Commit status webhook events
## Output
- PR/commit summary comment
- Line-level findings with confidence and severity

46
docs/review-engines.zh-CN.md Normal file
View File

@@ -0,0 +1,46 @@
# 审查引擎
## 概览
系统支持两种审查引擎：
- `agent`：原生任务化分级审查
- `codex`：基于 Codex CLI 的审查流水线
通过运行时配置 `REVIEW_ENGINE` 选择引擎。
## Agent 引擎
Agent 引擎会先做变更分流，再按领域派发 specialist 任务。
### 审查模式
- `skip`：低风险改动可跳过 specialist
- `light`：对低风险代码执行最小化专项检查
- `full`：对高风险或大规模改动执行完整审查
### 规模策略
`small` / `medium` / `large` 阈值用于 triage 阶段决策模式与 token 预算。
## Codex 引擎
Codex 引擎通过 Codex CLI 执行审查，支持独立配置：
- `CODEX_API_URL`
- `CODEX_API_KEY`
- `CODEX_MODEL`
- `CODEX_TIMEOUT_MS`
- `CODEX_REVIEW_PROMPT`
## 事件支持
两种引擎都支持：
- Pull Request webhook 事件
- Commit Status webhook 事件
## 输出
- PR/提交总结评论
- 行级问题（含置信度与严重性）

23
docs/screenshots.md Normal file
View File

@@ -0,0 +1,23 @@
# Screenshot Gallery
All screenshots are captured from local development service.
## Repository management (`/repos`)
![Repository management](./assets/page-repos.png)
## System configuration (`/config`)
![System configuration](./assets/page-config.png)
## Notification management (`/notifications`)
![Notification management](./assets/page-notifications.png)
## Review configuration (`/review-config`)
![Review configuration](./assets/page-review-config.png)
## Language
- 中文： [screenshots.zh-CN.md](./screenshots.zh-CN.md)

23
docs/screenshots.zh-CN.md Normal file
View File

@@ -0,0 +1,23 @@
# 截图集
以下截图来自本地开发环境。
## 仓库管理（`/repos`）
![仓库管理](./assets/page-repos.png)
## 系统配置（`/config`）
![系统配置](./assets/page-config.png)
## 通知管理（`/notifications`）
![通知管理](./assets/page-notifications.png)
## 审查配置（`/review-config`）
![审查配置](./assets/page-review-config.png)
## 语言切换
- English: [screenshots.md](./screenshots.md)