forks: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

Forks 是一个 Git 仓库管理工具，提供 Web UI 管理本地克隆的 GitHub 仓库。后端 Go + Gin，前端 Vue 3 + Naive UI，前后端分离，前端通过 //go:embed web/dist 嵌入到 Go 二进制中。

构建与运行

后端：

go build -o forks        # 构建
./forks serve             # 启动服务 (默认 :8080)
./forks serve -p 9090     # 指定端口
./forks serve --token xxx # 启用 Bearer Token 认证

环境变量配置：

• FORKS_PORT — 服务端口（优先级低于 -p 参数，默认 8080）
• FORKS_ADDRESS — 监听地址（默认 0.0.0.0）
• FORKS_HOME — 数据目录（默认 ~/.forks/）
• FORKS_REPO_PATH — 仓库存储路径

首次运行会交互式要求输入仓库存储路径，数据保存在 ~/.cicbyte/forks/。

前端：

cd web
npm install
npm run dev       # 开发服务器 (localhost:3000)
npm run build     # 构建到 web/dist/
npm run lint      # ESLint 检查
npm run format    # Prettier 格式化

前端构建后需要重新 go build 才能将新前端嵌入二进制。

Node 要求： ^20.19.0 || >=22.12.0

架构

main.go              → 入口，embed web/dist 资源
├── cmd/
│   ├── root.go      → Cobra 根命令，DB/日志初始化，建表
│   └── serve.go     → 所有 HTTP 路由和业务逻辑（Gin）
├── common/           → 全局变量（Db, LogFile）
├── models/           → 数据结构（GitRepoInfo, ProxyConfig, GitPlusConfig）
├── utils/            → 配置路径管理、GitHub API、JSON 工具、分页
├── assets/           → 嵌入资源桥接
└── web/              → Vue 3 前端 SPA
    └── src/
        ├── api/         → Axios API 调用
        ├── views/       → 页面组件
        ├── components/  → 通用组件
        ├── stores/      → Pinia 状态管理
        └── router/      → Vue Router

关键设计决策

• serve.go 是单体路由文件：所有 API 路由、SSE 事件流、业务逻辑都在 cmd/serve.go 中（约 3700+ 行），没有分层 controller/service。
• SQLite 数据库：使用 go-sqlite3（需 CGO），表结构在 cmd/root.go 中通过 CREATE TABLE IF NOT EXISTS 创建，字段变更通过 ALTER TABLE ADD COLUMN 兼容旧数据。
• SSE 实时推送：长时间操作（clone、pull、reset、scan、batch-clone）通过 SSE 推送进度，使用临时 token 认证。
• Git Smart HTTP：通过 git-upload-pack --stateless-rpc 实现只读镜像克隆，路径 /git/{source}/{author}/{repo}.git。Docker 环境需 git config --global --add safe.directory '*'。
• 代理支持：运行时代理配置存储在内存中（currentProxyConfig），支持 HTTP/SOCKS5，Git 命令和 GitHub API 调用都走代理。
• GitHub API：通过 utils/github.go 获取仓库元信息（stars、forks、topics 等），未使用 SDK，直接 HTTP 请求 GitHub REST API。
• 剪贴板兼容：web/src/utils/clipboard.js 统一封装，优先 navigator.clipboard，fallback 到 execCommand('copy') 兼容 HTTP 环境。