---
title: 面向贡献者
---

# 面向贡献者

欢迎贡献者参与 ZCF 项目！本章提供完整的开发指南，帮助您快速上手项目开发，了解架构设计，并遵循最佳实践。

## 📋 文档导航

| 文档 | 说明 | 适合人群 |
|------|------|---------|
| [贡献指南](contributing.md) | 详细的贡献流程、代码规范、PR 指南 | 所有贡献者 |
| [架构说明](architecture.md) | 项目架构、模块组织、设计模式、扩展点 | 核心开发者 |
| [测试指南](testing.md) | TDD 方法、测试编写、Mock 使用、覆盖率要求 | 所有开发者 |

## 🚀 快速开始

### 1. 环境准备

确保您的开发环境满足以下要求：

- **Node.js**: >= 22
- **pnpm**: >= 10.17.1
- **Git**: 最新版本
- **IDE**: 推荐 VS Code（带 TypeScript 支持）

### 2. 克隆和设置

```bash
# Fork 并克隆仓库
git clone https://github.com/YOUR_USERNAME/zcf.git
cd zcf

# 安装依赖
pnpm install

# 验证安装
pnpm test:run
pnpm typecheck
```

### 3. 开发流程

```bash
# 开发模式（使用 tsx，支持热重载）
pnpm dev

# 运行测试
pnpm test

# 代码检查
pnpm lint
pnpm typecheck

# 构建
pnpm build
```

## 📚 文档概览

### 贡献指南

详细的贡献流程文档，包括：

- ✅ **开发环境设置**：从 Fork 到本地开发的完整流程
- ✅ **代码规范**：TypeScript 风格、命名约定、导出规范
- ✅ **提交规范**：Conventional Commits 格式和示例
- ✅ **PR 指南**：如何创建高质量的 Pull Request
- ✅ **文档贡献**：GitBook 文档、代码注释、模板更新
- ✅ **测试要求**：覆盖率目标、测试类型、编写建议

**适合**：所有想要贡献代码的开发者

👉 [阅读贡献指南](contributing.md)

### 架构说明

深入理解 ZCF 的架构设计：

- 🏗️ **技术栈**：使用的技术和依赖
- 📁 **项目结构**：详细的目录组织
- 🔧 **核心模块**：CLI 入口、命令层、工具层、集成模块
- 🔄 **关键流程**：命令注册、初始化、配置合并、工作流安装
- 🎨 **设计模式**：命令模式、策略模式、工厂模式、适配器模式
- 🔌 **扩展点**：如何添加新命令、工作流、MCP 服务、API 提供商

**适合**：需要深入理解项目或添加新功能的开发者

👉 [阅读架构说明](architecture.md)

### 测试指南

完整的测试编写和运行指南：

- 🧪 **测试框架**：Vitest 配置和使用
- 📝 **测试结构**：目录组织、文件命名
- ✍️ **编写测试**：TDD 工作流、单元测试、集成测试、边界测试
- 🎭 **Mock 和 Fixtures**：文件系统、命令执行、交互式提示
- 📊 **覆盖率要求**：80% 覆盖率目标、报告解读
- 💡 **最佳实践**：测试命名、组织、隔离、语言独立性

**适合**：所有编写测试的开发者（必需）

👉 [阅读测试指南](testing.md)

## 🎯 开发工作流

### TDD（测试驱动开发）

ZCF 严格遵循 TDD 方法：

1. **Red**: 先写失败的测试
2. **Green**: 写最小代码使测试通过
3. **Refactor**: 重构代码，保持测试通过

**要求**：所有新功能必须先写测试！

### 代码质量标准

- **类型安全**：严格的 TypeScript 类型检查
- **代码风格**：@antfu/eslint-config 自动格式化
- **测试覆盖**：80% 最低覆盖率要求
- **文档完整**：代码注释、API 文档、用户文档

### 国际化（i18n）

- 所有用户可见的字符串必须使用 i18n
- 支持中英文两种语言
- 使用命名空间组织翻译
- 代码注释和文档使用英文

## 🔍 项目特点

### 模块化设计

- 清晰的模块边界
- 单一职责原则
- 依赖注入模式
- 可扩展的架构

### 跨平台支持

- Windows/macOS/Linux/Termux
- 路径适配（pathe）
- 命令执行适配（tinyexec）
- 平台特定逻辑隔离

### 健壮的错误处理

- 类型安全的错误处理
- 用户友好的错误消息
- 完整的错误日志
- 优雅的降级处理

## 💬 获取帮助

如果您在开发过程中遇到问题：

1. **查看文档**：先查阅相关文档章节
2. **搜索 Issue**：查看是否已有相关问题
3. **提问**：在 GitHub Issues 或 Discussions 中提问
4. **社区**：参与项目讨论，与其他贡献者交流

## 🌟 贡献方式

除了代码贡献，您还可以：

- 📖 **文档改进**：完善或翻译文档
- 🐛 **Bug 报告**：发现并报告问题
- 💡 **功能建议**：提出改进建议
- 🧪 **测试补充**：提高测试覆盖率
- 🌍 **翻译贡献**：改进翻译质量

## 📖 相关资源

- [项目 README](https://github.com/UfoMiao/zcf/blob/main/README.md) - 项目概览和快速开始
- [CLAUDE.md](https://github.com/UfoMiao/zcf/blob/main/CLAUDE.md) - 完整的项目架构文档
- [GitHub Issues](https://github.com/UfoMiao/zcf/issues) - 问题和讨论
- [GitHub Discussions](https://github.com/UfoMiao/zcf/discussions) - 社区讨论

---

**再次感谢您对 ZCF 项目的关注和贡献！** 🎉

开始贡献之前，建议先阅读 [贡献指南](contributing.md) 了解详细的流程和规范。
