diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 85c38b4..be68fe6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,12 @@ -# 贡献指南 / Contributing Guide +# 贡献指南 + +> English version: [CONTRIBUTING_EN.md](./CONTRIBUTING_EN.md) 感谢你考虑为 cursor-byok 做出贡献！ -Thank you for considering contributing to cursor-byok! ---- +## 开发环境 -## 开发环境 / Prerequisites - -| 依赖 / Dependency | 版本要求 / Version | +| 依赖 | 版本要求 | |------|---------| | Go | >= 1.25 | | Node.js | >= 20 | @@ -15,45 +14,45 @@ Thank you for considering contributing to cursor-byok! | [Task](https://taskfile.dev) | >= 3 | | [Wails v3 CLI](https://v3alpha.wails.dev) | alpha.74+ | -Linux 额外依赖 / Additional Linux dependencies: `libgtk-3-dev`, `libwebkit2gtk-4.1-dev`. +Linux 额外依赖：`libgtk-3-dev`、`libwebkit2gtk-4.1-dev`（Wails 运行时需要）。 -## 快速开始 / Quick Start +## 快速开始 ```bash -# 安装前端依赖 / Install frontend dependencies +# 安装前端依赖 cd frontend && yarn install --frozen-lockfile && cd .. -# 启动开发模式（热重载）/ Start dev mode (hot reload) +# 启动开发模式（热重载） task dev -# 构建当前平台分发包 / Build for current platform +# 构建当前平台分发包 task build ``` -## 项目结构 / Project Structure +## 项目结构 ``` -├── main.go # 入口 / Entry point -├── internal/ # Go 后端（代理、转发、客户端管理）/ Go backend -├── frontend/ # Vue 3 + Vite + Tailwind 前端 / Frontend +├── main.go # 入口 +├── internal/ # Go 后端（代理、转发、客户端管理等） +├── frontend/ # Vue 3 + Vite + Tailwind 前端 │ ├── src/ -│ │ ├── views/ # 页面 / Pages -│ │ ├── components/ # 组件 / Components -│ │ ├── i18n/ # 国际化 / i18n (zh-CN / en-US / ja-JP / ru-RU) -│ │ └── state/ # 全局状态 / Global state -│ └── plugins/ # Vite 插件 / Vite plugins -├── prompt/ # 内置 Agent prompt 模板 / Built-in agent prompts -├── proto/ # Protobuf 定义 / Protobuf definitions -├── build/ # 构建配置与平台 Taskfile / Build configs -├── scripts/ # 辅助脚本 / Helper scripts -└── Taskfile.yml # 顶层任务编排 / Top-level task orchestration +│ │ ├── views/ # 页面 +│ │ ├── components/ # 组件 +│ │ ├── i18n/ # 国际化（zh-CN / en-US / ja-JP / ru-RU） +│ │ └── state/ # 全局状态 +│ └── plugins/ # Vite 插件（i18n 静态扫描等） +├── prompt/ # 内置 Agent prompt 模板 +├── proto/ # Protobuf 定义 +├── build/ # 构建配置与平台 Taskfile +├── scripts/ # 辅助脚本（release、metrics） +└── Taskfile.yml # 顶层任务编排 ``` -## 开发规范 / Development Guidelines +## 开发规范 -### 提交信息 / Commit Messages +### 提交信息 -采用 [Conventional Commits](https://www.conventionalcommits.org/) 风格： +采用 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/) 风格： ``` feat(proxy): 支持自定义 upstream 超时 @@ -61,35 +60,31 @@ fix(i18n): 补全日语翻译缺失 key release: 0.0.42 ``` -### 代码风格 / Code Style +### 代码风格 - Go：遵循 `gofmt` / `go vet`，不引入额外 linter 配置。 - Follow `gofmt` / `go vet`; no additional linter config. - 前端：Vue SFC + Composition API，Tailwind 工具类优先。 - Frontend: Vue SFC + Composition API, Tailwind utility-first. - 新增 UI 文案必须同步更新所有 locale 文件（`frontend/src/i18n/locales/`）。 - New UI strings must be added to ALL locale files. -### 分支与 PR / Branching & PRs +### 分支与 PR -1. 从 `main` 创建功能分支 / Create feature branches from `main`: `feat/xxx`, `fix/xxx`. -2. 保持 PR 小而聚焦 / Keep PRs small and focused. -3. PR 描述中说明动机和测试方式 / Describe motivation and how to test. +1. 从 `main` 创建功能分支：`feat/xxx`、`fix/xxx`。 +2. 保持 PR 小而聚焦，一个 PR 解决一个问题。 +3. PR 描述中说明动机和测试方式。 -## 构建与发布 / Build & Release +## 构建与发布 ```bash -# 构建全平台（仅 macOS 主机）/ Build all platforms (macOS host only) +# 构建全平台（仅 macOS 主机） task build:all -# 准备发布资产 / Prepare release assets +# 准备发布资产 task release:prepare -# 发布到 GitHub Releases / Publish to GitHub Releases +# 发布到 GitHub Releases task release:github ``` -## 许可证 / License +## 许可证 -提交代码即表示你同意以 [MIT License](./LICENSE) 授权你的贡献。 -By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE). \ No newline at end of file +提交代码即表示你同意以 [MIT License](./LICENSE) 授权你的贡献。 \ No newline at end of file diff --git a/CONTRIBUTING_EN.md b/CONTRIBUTING_EN.md new file mode 100644 index 0000000..76393bb --- /dev/null +++ b/CONTRIBUTING_EN.md @@ -0,0 +1,90 @@ +# Contributing Guide + +> 中文版本：[CONTRIBUTING.md](./CONTRIBUTING.md) + +Thank you for considering contributing to cursor-byok! + +## Prerequisites + +| Dependency | Version | +|------------|---------| +| Go | >= 1.25 | +| Node.js | >= 20 | +| Yarn | 1.x (classic) | +| [Task](https://taskfile.dev) | >= 3 | +| [Wails v3 CLI](https://v3alpha.wails.dev) | alpha.74+ | + +Additional Linux dependencies: `libgtk-3-dev`, `libwebkit2gtk-4.1-dev` (required by Wails runtime). + +## Quick Start + +```bash +# Install frontend dependencies +cd frontend && yarn install --frozen-lockfile && cd .. + +# Start dev mode (hot reload) +task dev + +# Build for current platform +task build +``` + +## Project Structure + +``` +├── main.go # Entry point +├── internal/ # Go backend (proxy, forwarding, client management) +├── frontend/ # Vue 3 + Vite + Tailwind frontend +│ ├── src/ +│ │ ├── views/ # Pages +│ │ ├── components/ # Components +│ │ ├── i18n/ # Internationalization (zh-CN / en-US / ja-JP / ru-RU) +│ │ └── state/ # Global state +│ └── plugins/ # Vite plugins (i18n static scanner, etc.) +├── prompt/ # Built-in agent prompt templates +├── proto/ # Protobuf definitions +├── build/ # Build configs & platform Taskfiles +├── scripts/ # Helper scripts (release, metrics) +└── Taskfile.yml # Top-level task orchestration +``` + +## Development Guidelines + +### Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +feat(proxy): support custom upstream timeout +fix(i18n): add missing Japanese translation keys +release: 0.0.42 +``` + +### Code Style + +- Go: follow `gofmt` / `go vet`; no additional linter config. +- Frontend: Vue SFC + Composition API, Tailwind utility-first. +- New UI strings must be added to ALL locale files (`frontend/src/i18n/locales/`). + +### Branching & PRs + +1. Create feature branches from `main`: `feat/xxx`, `fix/xxx`. +2. Keep PRs small and focused — one problem per PR. +3. Describe motivation and how to test in the PR description. + +## Build & Release + +```bash +# Build all platforms (macOS host only) +task build:all + +# Prepare release assets +task release:prepare + +# Publish to GitHub Releases +task release:github +``` + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE). \ No newline at end of file