ZCF：一键配置Claude Code完整开发环境的工具

ZCF (Zero-Config Claude-Code Flow) 是一款命令行工具，它的主要功能是帮助开发者快速配置和使用一个名为 “Claude Code” 的AI编程环境。对于想利用AI辅助写代码，但又不想手动进行复杂设置的开发者来说，这个工具提供了一键式的解决方案。它通过一个简单的命令 npx zcf，就能自动完成Claude Code的安装、API密钥配置、工作流导入等全部流程。ZCF的核心设计理念是“零配置”，目标是让开发者开箱即用，立即进入AI辅助编程的状态。除了基础的安装配置，它还集成了多种高级工作流和AI代理系统，例如用于规范开发流程的BMad框架，以及用于管理API成本和使用多种AI模型的CCR路由，让整个AI编程体验更加高效和个性化。

Lista de funções

• 交互式菜单: 用户在终端执行npx zcf后，会出现一个可视化的操作菜单，引导用户完成初始化、更新工作流、管理API等操作，非常适合新手。
• 一键初始化: 首次使用的用户，可以通过npx zcf i命令执行完整的初始化流程，包括自动检测和安装Claude Code、配置API、导入预设的AI工作流等。
• Suporte a vários idiomas: 工具的安装界面、配置文件以及AI的输出语言都可以独立设置，支持中文、英文等多种语言，方便不同语言习惯的开发者。
• AI输出风格定制: 内置了多种AI的“人设”风格，例如“专业工程师”或“猫娘工程师”，用户可以根据喜好选择不同的风格，让AI的回答方式更符合个人偏好。
• CCR代理路由: 集成了Claude Code Router (CCR)，这是一个强大的代理工具。它允许开发者将不同的请求路由到不同的AI模型，甚至可以使用一些免费模型（如Gemini），以此来大幅降低API的使用成本。
• BMad企业级工作流: 集成了一套名为BMad的AI Agent框架。这个框架模拟了一个完整的开发团队（包含产品经理、架构师、开发者、测试等多种角色），能够引导用户完成结构化的开发流程，适合用于规范化的项目开发。
• 状态栏工具集成: 支持名为CCometixLine的状态栏工具，它可以在终端底部实时显示Claude Code的API使用情况和当前项目的Git状态，帮助开发者随时掌握项目动态。
• 智能配置管理: 在配置过程中，工具能够自动备份用户原有的设置，并支持合并新旧配置，避免用户的个性化设置被覆盖。
• Compatibilidade entre plataformas: 能够在Windows、macOS、Linux以及安卓设备上的Termux等多种操作系统和环境中运行。

Usando a Ajuda

ZCF是一个通过npm运行的Node.js脚本，因此使用它的前提是你的电脑上已经安装了Node.js环境。它的设计目标是简化操作，大部分功能通过一个命令即可完成。

Início rápido

最推荐的使用方式是通过交互式菜单，它清晰地列出了所有可用操作。

1. 打开你的终端（命令行工具）。
2. Digite o seguinte comando e dê enter:

   npx zcf
   

3. 执行命令后，终端会显示一个功能选择菜单。你可以使用键盘的上下箭头来选择需要执行的任务，然后按回车确认。

   菜单选项说明：

   • 1. Full initialization: 这是为第一次使用的用户准备的完整初始化选项。它会帮你完成所有必要的步骤，包括安装Claude Code、导入工作流、配置API或CCR代理、设置MCP服务等。选择这个选项，然后根据提示一步步操作即可。
   • 2. Import workflow: 如果你已经安装过Claude Code，但想更新或导入最新的AI工作流文件，可以选择此项。它只会更新工作流相关的配置，不会动你的API等核心设置。
   • 3. Configure API: 用于单独配置API，比如更换API Key或者设置CCR代理。
   • R. CCR - Claude Code Router management: 用于管理CCR代理服务的子菜单，你可以在这里安装、启动或停止CCR服务。
   • L. CCometixLine: 用于管理CCometixLine状态栏工具的子菜单。
   • +. Check updates: 检查ZCF相关的工具（如Claude Code、CCR等）是否有新版本并进行更新。

直接使用命令

如果你是熟悉终端操作的老手，也可以跳过交互式菜单，直接使用命令参数来执行特定任务，这样效率更高。

1. 完整初始化 (第一次使用)
   如果你是第一次使用，或者想重新配置所有内容，请运行：

   npx zcf i
   

   这个命令等同于在菜单中选择1. Full initialization.

2. 仅更新工作流 (后续更新)
   如果你之前已经配置好了环境，现在官方发布了新的AI工作流或命令，你可以只更新这些文件，而保留自己的API等配置不变：

   npx zcf u
   

   这个命令等同于在菜单中选择2. Import workflow.

在项目中使用Claude Code

当你通过ZCF配置好环境后，就可以在你的代码项目中开始使用了。

1. 在你的项目文件夹根目录，打开终端。
2. 项目初始化 (推荐): 首次在项目中使用时，强烈建议先运行项目初始化命令。这个命令会让AI分析你的项目结构，并生成一个CLAUDE.md文件，帮助AI更好地理解你的项目上下文，后续回答的质量会更高。

   /init-project
   

3. 执行简单任务: 对于一些小的、独立的任务，比如修复一个bug、写一个简单的函数，你可以直接向AI描述你的任务：

   <在这里输入你的任务描述，例如：“修复登录页面的按钮样式问题”>
   

4. 开发新功能: 当你需要开发一个相对完整的新功能时，可以使用/feat命令。它会引导AI先进行规划，再进行界面设计和代码实现，流程更加结构化。

   /feat <在这里输入你的功能描述，例如：“开发一个用户个人资料编辑页面”>
   

5. 执行完整工作流: 对于更复杂的任务，可以使用/workflow命令。它会将任务分解为研究、构思、计划、执行、优化、审查六个步骤，并在每一步都与你进行确认和交互，让你对开发过程有最大的控制权。

   /workflow <在这里输入你的复杂任务描述>
   

非交互模式（用于自动化脚本）

ZCF还支持在CI/CD等自动化环境中使用。通过添加--skip-prompttalvez-s参数，可以跳过所有交互式提问，并通过命令行参数直接传入配置信息。

例如，下面是一个非交互式初始化的完整示例：

npx zcf i -s -g zh-CN -t api_key -k "sk-xxx" -u "https://xxx.xxx"

这个命令的含义是：

• i: 执行初始化。
• -s: 跳过所有交互提示。
• -g zh-CN: 将所有语言相关的设置（界面、配置、AI输出）都设为简体中文。
• -t api_key: 设置API类型为API Key。
• -k "sk-xxx": 传入你的API Key。
• -u "https://xxx.xxx": 传入你的API代理地址。

通过这种方式，你可以将ZCF集成到你的自动化部署脚本中。

cenário do aplicativo

1. 快速搭建个人AI编程环境
   对于希望尝试使用AI辅助编程的独立开发者或小型团队，ZCF提供了一种最快速的方式来搭建一个功能完备的开发环境。开发者无需关心繁琐的配置文件和脚本，只需运行一个命令，几分钟内就可以拥有一个集成了多种高效工作流的AI编程助手。
2. 标准化团队的AI辅助开发流程
   在团队协作中，可以使用ZCF的BMad工作流来统一开发规范。BMad通过模拟一个包含产品、开发、测试等角色的虚拟AI团队，引导所有成员遵循一个标准化的、从需求分析到代码实现和测试的结构化流程，从而提升团队的协作效率和代码质量。
3. 降低AI模型的使用成本
   对于API调用量较大或预算有限的用户，可以通过ZCF配置CCR代理路由。CCR允许用户将代码补全、聊天、复杂逻辑分析等不同类型的请求，智能地路由到最合适的AI模型上，例如将简单任务交给性能足够且免费的模型处理，从而在保证开发效率的同时，显著降低API账单的费用。
4. 自动化脚本与CI/CD集成
   ZCF的非交互模式使其可以被轻松集成到自动化脚本或持续集成/持续部署（CI/CD）流程中。例如，可以编写脚本来自动为一个新的开发环境配置好标准的Claude Code设置，确保所有环境的一致性。

QA

1. ZCF和Claude Code是什么关系？
   ZCF是Claude Code的“配置和管理工具”。Claude Code是实际与AI交互进行编程的核心环境，而ZCF则专注于简化这个环境的安装、配置和更新过程，并为其增加了许多预设的工作流和实用功能。你可以把ZCF理解为一个“安装向导”或“启动器”。
2. 我需要有Anthropic官方的API密钥才能使用吗？
   不一定。ZCF在配置时提供了多种选项：你可以使用Anthropic官方的API Key，也可以使用通过OAuth等方式获取的Auth Token。更灵活的是，你可以配置CCR（Claude Code Router）代理，通过这个代理你可以使用其他大模型（比如Gemini或DeepSeek的免费模型），从而绕开必须使用官方付费API的限制。
3. 这个工具支持哪些操作系统？
   ZCF具有很好的跨平台兼容性，官方文档明确指出它支持Windows、macOS和Linux三大主流桌面操作系统。除此之外，它还特别为在Android设备上使用终端模拟器Termux的场景进行了适配，确保在移动设备上也能获得完整的功能体验。
4. 更新ZCF或工作流会覆盖我的个人配置吗？
   不会。ZCF在设计时考虑到了用户配置的保留问题。当你运行更新命令（例如 npx zcf u）或者重新进行完整初始化时，ZCF会智能地备份你现有的配置文件（如API密钥、模型设置等），然后再写入新的配置。它还提供了“合并配置”的选项，可以尝试将新旧配置进行合并，最大限度地保留你的个人化设置。