first commit
This commit is contained in:
nasir@endelospay.com
265
docs/CONTRIBUTING_zh.md
Normal file
265
docs/CONTRIBUTING_zh.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# 贡献指南 🤝
|
||||
|
||||
感谢您对 Chrome MCP Server 项目的贡献兴趣！本文档为贡献者提供指南和信息。
|
||||
|
||||
## 🎯 如何贡献
|
||||
|
||||
我们欢迎多种形式的贡献：
|
||||
|
||||
- 🐛 错误报告和修复
|
||||
- ✨ 新功能和工具
|
||||
- 📚 文档改进
|
||||
- 🧪 测试和性能优化
|
||||
- 🌐 翻译和国际化
|
||||
- 💡 想法和建议
|
||||
|
||||
## 🚀 开始贡献
|
||||
|
||||
### 环境要求
|
||||
|
||||
- **Node.js 18+** 和 **pnpm**（最新版本）
|
||||
- **Chrome/Chromium** 浏览器用于测试
|
||||
- **Git** 版本控制
|
||||
- **Rust**（用于 WASM 开发，可选）
|
||||
- **TypeScript** 知识
|
||||
|
||||
### 开发环境设置
|
||||
|
||||
1. **Fork 并克隆仓库**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/chrome-mcp-server.git
|
||||
cd chrome-mcp-server
|
||||
```
|
||||
|
||||
2. **安装依赖**
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
3. **启动项目**
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
4. **在 Chrome 中加载扩展**
|
||||
- 打开 `chrome://extensions/`
|
||||
- 启用"开发者模式"
|
||||
- 点击"加载已解压的扩展程序"，选择 `your/extension/dist`
|
||||
|
||||
## 🏗️ 项目结构
|
||||
|
||||
```
|
||||
chrome-mcp-server/
|
||||
├── app/
|
||||
│ ├── chrome-extension/ # Chrome 扩展 (WXT + Vue 3)
|
||||
│ │ ├── entrypoints/ # 后台脚本、弹窗、内容脚本
|
||||
│ │ ├── utils/ # AI 模型、向量数据库、工具
|
||||
│ │ └── workers/ # 用于 AI 处理的 Web Workers
|
||||
│ └── native-server/ # 原生消息服务器 (Fastify + TypeScript)
|
||||
│ ├── src/mcp/ # MCP 协议实现
|
||||
│ └── src/server/ # HTTP 服务器和原生消息
|
||||
├── packages/
|
||||
│ ├── shared/ # 共享类型和工具
|
||||
│ └── wasm-simd/ # SIMD 优化的 WebAssembly 数学函数
|
||||
└── docs/ # 文档
|
||||
```
|
||||
|
||||
## 🛠️ 开发工作流
|
||||
|
||||
### 添加新工具
|
||||
|
||||
1. **在 `packages/shared/src/tools.ts` 中定义工具模式**：
|
||||
|
||||
```typescript
|
||||
{
|
||||
name: 'your_new_tool',
|
||||
description: '描述您的工具功能',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
// 定义参数
|
||||
},
|
||||
required: ['param1']
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **在 `app/chrome-extension/entrypoints/background/tools/browser/` 中实现工具**：
|
||||
|
||||
```typescript
|
||||
class YourNewTool extends BaseBrowserToolExecutor {
|
||||
name = TOOL_NAMES.BROWSER.YOUR_NEW_TOOL;
|
||||
|
||||
async execute(args: YourToolParams): Promise<ToolResult> {
|
||||
// 实现
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **在 `app/chrome-extension/entrypoints/background/tools/browser/index.ts` 中导出工具**
|
||||
|
||||
4. **在相应的测试目录中添加测试**
|
||||
|
||||
### 代码风格指南
|
||||
|
||||
- **TypeScript**：使用严格的 TypeScript 和适当的类型
|
||||
- **ESLint**：遵循配置的 ESLint 规则（`pnpm lint`）
|
||||
- **Prettier**：使用 Prettier 格式化代码（`pnpm format`）
|
||||
- **命名**：使用描述性名称并遵循现有模式
|
||||
- **注释**：为公共 API 添加 JSDoc 注释
|
||||
- **错误处理**：始终优雅地处理错误
|
||||
|
||||
## 📝 Pull Request 流程
|
||||
|
||||
1. **创建功能分支**
|
||||
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
2. **进行更改**
|
||||
|
||||
- 遵循代码风格指南
|
||||
- 为新功能添加测试
|
||||
- 如需要，更新文档
|
||||
|
||||
3. **测试您的更改**
|
||||
|
||||
- 确保所有现有测试通过
|
||||
- 手动测试 Chrome 扩展
|
||||
- 验证 MCP 协议兼容性
|
||||
|
||||
4. **提交您的更改**
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: 添加您的功能描述"
|
||||
```
|
||||
|
||||
我们使用 [约定式提交](https://www.conventionalcommits.org/)：
|
||||
|
||||
- `feat:` 用于新功能
|
||||
- `fix:` 用于错误修复
|
||||
- `docs:` 用于文档更改
|
||||
- `test:` 用于添加测试
|
||||
- `refactor:` 用于代码重构
|
||||
|
||||
5. **推送并创建 Pull Request**
|
||||
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
## 🐛 错误报告
|
||||
|
||||
报告错误时，请包含：
|
||||
|
||||
- **环境**：操作系统、Chrome 版本、Node.js 版本
|
||||
- **重现步骤**：清晰的分步说明
|
||||
- **预期行为**：应该发生什么
|
||||
- **实际行为**：实际发生了什么
|
||||
- **截图/日志**：如果适用
|
||||
- **MCP 客户端**：您使用的 MCP 客户端（Claude Desktop 等）
|
||||
|
||||
## 💡 功能请求
|
||||
|
||||
对于功能请求，请提供：
|
||||
|
||||
- **用例**：为什么需要这个功能？
|
||||
- **建议解决方案**：它应该如何工作？
|
||||
- **替代方案**：考虑过的任何替代解决方案？
|
||||
- **附加上下文**：截图、示例等
|
||||
|
||||
## 🔧 开发技巧
|
||||
|
||||
### 使用 WASM SIMD
|
||||
|
||||
如果您要为 WASM SIMD 包做贡献：
|
||||
|
||||
```bash
|
||||
cd packages/wasm-simd
|
||||
# 如果尚未安装，请安装 Rust 和 wasm-pack
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
cargo install wasm-pack
|
||||
|
||||
# 构建 WASM 包
|
||||
pnpm build
|
||||
|
||||
# 构建的文件将复制到 app/chrome-extension/workers/
|
||||
```
|
||||
|
||||
### 调试 Chrome 扩展
|
||||
|
||||
- 使用 Chrome DevTools 调试扩展弹窗和后台脚本
|
||||
- 检查 `chrome://extensions/` 查看扩展错误
|
||||
- 使用 `console.log` 语句进行调试
|
||||
- 在后台脚本中监控原生消息连接
|
||||
|
||||
### 测试 MCP 协议
|
||||
|
||||
- 使用 MCP Inspector 进行协议调试
|
||||
- 使用不同的 MCP 客户端测试（Claude Desktop、自定义客户端）
|
||||
- 验证工具模式和响应符合 MCP 规范
|
||||
|
||||
## 📚 资源
|
||||
|
||||
- [模型上下文协议规范](https://modelcontextprotocol.io/)
|
||||
- [Chrome 扩展开发](https://developer.chrome.com/docs/extensions/)
|
||||
- [WXT 框架文档](https://wxt.dev/)
|
||||
- [TypeScript 手册](https://www.typescriptlang.org/docs/)
|
||||
|
||||
## 🤝 社区
|
||||
|
||||
- **GitHub Issues**：用于错误报告和功能请求
|
||||
- **GitHub Discussions**：用于问题和一般讨论
|
||||
- **Pull Requests**：用于代码贡献
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
通过为 Chrome MCP Server 做贡献，您同意您的贡献将在 MIT 许可证下获得许可。
|
||||
|
||||
## 🎯 贡献者指南
|
||||
|
||||
### 新手贡献者
|
||||
|
||||
如果您是第一次为开源项目做贡献：
|
||||
|
||||
1. **从小处开始**：寻找标有 "good first issue" 的问题
|
||||
2. **阅读代码**：熟悉项目结构和编码风格
|
||||
3. **提问**：在 GitHub Discussions 中提出问题
|
||||
4. **学习工具**：了解 Git、GitHub、TypeScript 等工具
|
||||
|
||||
### 经验丰富的贡献者
|
||||
|
||||
- **架构改进**：提出系统级改进建议
|
||||
- **性能优化**：识别和修复性能瓶颈
|
||||
- **新功能**：设计和实现复杂的新功能
|
||||
- **指导新手**：帮助新贡献者入门
|
||||
|
||||
### 文档贡献
|
||||
|
||||
- **API 文档**：改进工具文档和示例
|
||||
- **教程**：创建使用指南和最佳实践
|
||||
- **翻译**：帮助翻译文档到其他语言
|
||||
- **视频内容**：创建演示视频和教程
|
||||
|
||||
### 测试贡献
|
||||
|
||||
- **单元测试**：为新功能编写测试
|
||||
- **集成测试**：测试组件间的交互
|
||||
- **性能测试**：基准测试和性能回归检测
|
||||
- **用户测试**：真实场景下的功能测试
|
||||
|
||||
## 🏆 贡献者认可
|
||||
|
||||
我们重视每一个贡献，无论大小。贡献者将在以下方式获得认可：
|
||||
|
||||
- **README 致谢**：在项目 README 中列出贡献者
|
||||
- **发布说明**：在版本发布说明中感谢贡献者
|
||||
- **贡献者徽章**：GitHub 个人资料上的贡献者徽章
|
||||
- **社区认可**：在社区讨论中的特别感谢
|
||||
|
||||
感谢您考虑为 Chrome MCP Server 做贡献！您的参与使这个项目变得更好。
|
||||
Reference in New Issue
Block a user