# Contributing to CogitoAgent > 感谢你有兴趣为 CogitoAgent 做出贡献！我们欢迎各种形式的贡献，包括但不限于代码、文档、测试、bug 报告和功能建议。 > > Thanks for your interest in contributing to CogitoAgent! We welcome contributions of all kinds, including but not limited to code, documentation, tests, bug reports, and feature suggestions. --- ## Table of Contents / 目录 - [How to Contribute / 如何贡献](#how-to-contribute--如何贡献) - [Development Setup / 开发环境搭建](#development-setup--开发环境搭建) - [Development Workflow / 开发流程](#development-workflow--开发流程) - [Code Standards / 代码规范](#code-standards--代码规范) - [Commit Message Guidelines / 提交信息规范](#commit-message-guidelines--提交信息规范) - [Testing / 测试](#testing--测试) - [Project Structure / 项目结构](#project-structure--项目结构) - [Communication / 沟通](#communication--沟通) --- ## How to Contribute / 如何贡献 ### 🚀 5-Minute Quick Start / 5 分钟快速贡献 > 想快速体验贡献流程？以下是新手最快上手的方式。 > Want to experience the contribution process quickly? Here's the fastest way for beginners. 1. **找一个新手任务** — 查看 [good first issue](https://github.com/SnowLeopard-io/CogitoAgent/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) 标签 2. **Fork 仓库** — 点击 GitHub 右上角的 Fork 按钮 3. **克隆到本地** — `git clone https://github.com/你的用户名/CogitoAgent.git` 4. **创建分支** — `git checkout -b fix/your-bug-fix` 5. **修改代码** — 可以是文档、测试、或简单的 bug 修复 6. **提交 PR** — 在 GitHub 上创建 Pull Request，等待审查 --- ### 1. 寻找任务 / Find a Task - 查看 [Issues](https://github.com/SnowLeopard-io/CogitoAgent/issues) 页面，寻找标有 `good first issue` 或 `help wanted` 标签的任务 - 如果你有新的想法或发现了 bug，可以先创建一个 Issue 进行讨论 - Check the [Issues](https://github.com/SnowLeopard-io/CogitoAgent/issues) page for tasks labeled with `good first issue` or `help wanted` - If you have new ideas or find bugs, create an Issue to discuss first ### 2. Fork 仓库 / Fork the Repository 点击 GitHub 页面右上角的 **Fork** 按钮，将仓库克隆到你的账户下。 Click the **Fork** button in the upper right corner of the GitHub page to clone the repository to your account. ### 3. 创建分支 / Create a Branch 从 `main` 分支创建一个新分支，分支命名遵循以下规则： Create a new branch from the `main` branch, following these naming conventions: ```bash git checkout -b feature/your-feature-name # 新功能 / New feature git checkout -b fix/your-bug-fix # Bug 修复 / Bug fix git checkout -b docs/your-documentation # 文档更新 / Documentation update git checkout -b refactor/your-refactoring # 代码重构 / Code refactoring ``` --- ## Development Setup / 开发环境搭建 ### 环境要求 / Requirements - **Node.js** 24 或更高版本 / 24 or higher - **npm** 或 **yarn** 包管理器 / or yarn package manager - **Python** 3.x（可选，用于 Python 代码执行）/ (optional, for Python code execution) ### 安装步骤 / Installation ```bash # 克隆你的 fork / Clone your fork git clone https://github.com/your-username/CogitoAgent.git cd CogitoAgent # 安装依赖 / Install dependencies npm install ``` ### 国内用户注意 / Note for Users in China 如果 `npm install` 下载 Electron 失败，请设置国内镜像： If `npm install` fails to download the Electron binary, set the Chinese mirror: ```bash $env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/" npm install ``` ### 启动开发模式 / Start Development ```bash npm start # 启动设置向导 / Start setup wizard npm run cli # CLI 模式 / CLI mode npm run electron:desktop # 桌面悬浮窗口模式 / Desktop floating window mode npm run electron:dashboard # 仪表盘模式 / Dashboard mode ``` --- ## Development Workflow / 开发流程 1. **同步上游代码 / Sync with Upstream** 在开始工作前，确保你的 fork 与原始仓库保持同步： Before starting work, ensure your fork is synchronized with the original repository: ```bash git remote add upstream https://github.com/SnowLeopard-io/CogitoAgent.git git fetch upstream git checkout main git merge upstream/main ``` 2. **编写代码 / Write Code** - 遵循项目的代码规范（见下文）/ Follow the project's code standards (see below) - 为新增功能编写测试 / Write tests for new features - 更新相关文档 / Update relevant documentation 3. **提交代码 / Commit Changes** ```bash git add . git commit -m "feat: add new feature" # 使用规范的提交信息 / Use standard commit message ``` 4. **推送到远程 / Push to Remote** ```bash git push origin feature/your-feature-name ``` 5. **创建 Pull Request / Create a Pull Request** 在 GitHub 上打开你的 fork，点击 **Compare & pull request** 按钮，填写 PR 描述并提交。 Open your fork on GitHub, click the **Compare & pull request** button, fill in the PR description, and submit. --- ## Code Standards / 代码规范 ### TypeScript - 核心模块使用 TypeScript（`.ts` 扩展名）/ Core modules use TypeScript (`.ts` extension) - 保持类型安全，避免 `any` 类型 / Maintain type safety, avoid `any` type - 导出类型定义到 `src/types/index.ts` / Export type definitions to `src/types/index.ts` ### 代码风格 / Code Style 项目使用 ESLint + Prettier 进行代码检查和格式化： The project uses ESLint + Prettier for code checking and formatting: ```bash npm run lint # 运行 ESLint 检查并自动修复 / Run ESLint and auto-fix npm run lint:check # 仅检查，不自动修复 / Check only, no auto-fix npm run format # 使用 Prettier 格式化代码 / Format code with Prettier npm run typecheck # TypeScript 类型检查 / TypeScript type check ``` ### 提交前检查 / Pre-commit Checks 项目使用 Husky 配置了 pre-commit 钩子，提交前会自动运行： The project uses Husky for pre-commit hooks, which automatically run before commits: - ESLint 检查 / ESLint check - Prettier 格式化 / Prettier formatting ### 命名规范 / Naming Conventions | 类型 / Type | 格式 / Format | 示例 / Example | | --------------------------- | ------------------------------ | -------------------------- | | 文件 / File | kebab-case | `tool-parser.ts` | | 类 / Class | PascalCase | `class Agent { }` | | 函数/方法 / Function/Method | camelCase | `executeTool()` | | 变量 / Variable | camelCase | `sessionId` | | 常量 / Constant | UPPER_SNAKE_CASE | `MAX_TOKEN_LIMIT` | | 接口 / Interface | PascalCase + `I` 前缀 / prefix | `interface IToolEntry { }` | --- ## Commit Message Guidelines / 提交信息规范 提交信息使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式： Commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) format: ``` ():