ZCF（Zero-Config Code Flow）架构与实战指南：一键配置 Claude Code 与 Codex 环境的 TypeScript CLI 工具

开发工具CLIAI 应用【免费下载链接】zcfZero-Config Code Flow for Claude code Codex项目地址https://gitcode.com/gh_mirrors/zc/zcf点击查看免费下载本文以仓库根目录CLAUDE.md为骨架结合package.json、src/cli-setup.ts、src/config/、src/constants.ts等源码实现系统讲解 ZCF 的模块架构、CLI 命令体系、开发构建流程、编码规范与内置 AI 团队协作机制。读完本文你将掌握 ZCF 的命令行用法、源码目录组织、i18n 国际化体系、多代码工具支持Claude Code / Codex以及一套可复用的测试与发布流程。项目定位与核心能力ZCFZero-Config Code Flow是一个以 TypeScript 编写、以 npm 包形式分发的 CLI 工具核心目标是一键配置 Claude Code 环境。它自动完成 Claude Code 的配置文件生成、API 设置、MCP 服务接入和 AI 工作流安装无需手动翻阅官方文档逐项填写。当前仓库版本号为 v3.7.2package.json核心特性包括多代码工具架构同时支持 Claude Code、Codex 两种代码工具的环境配置通过--code-type参数或cc/cx短别名切换i18next 国际化全部用户可见字符串支持 zh-CN 与 en 双语言采用命名空间组织翻译文件支持动态语言切换API Provider 预设系统内置 302.AI、GLM、MiniMax、Kimi、DeepSeek 等十余家服务商预设将原本 5 步以上的 API 配置压缩到选择服务商 填写密钥两步智能 IDE 检测自动识别 git-worktree 环境并完成 IDE 自动打开跨平台兼容覆盖 Windows、macOS、Linux 以及 Termux 环境高级卸载系统支持冲突解决、选择性移除与跨平台回收站集成工具生态集成内置 CCRClaude Code Router 代理、CCusage用量分析、Cometix 状态栏工具。架构总览与模块划分ZCF 采用模块化 CLI 架构遵循严格的 TypeScript 类型约束构建工具链为 unbuild测试框架为 Vitest配置为纯 ESM无 CommonJS 回退代码规范采用 antfu/eslint-config。整体架构强调健壮的错误处理、友好的交互界面和覆盖广泛的测试体系。从源码结构看项目由以下 10 个核心模块组成对应根目录 CLAUDE.md 的模块索引模块路径职责主要入口测试覆盖Commandssrc/commands/CLI 命令实现支持交互式与非交互式两种模式含卸载与配置切换init.ts、menu.ts、update.ts、ccr.ts、ccu.ts、check-updates.ts、uninstall.ts、config-switch.ts高测试套件完整Utilitiessrc/utils/配置管理、平台支持、Codex 集成、高级卸载等核心功能config.ts、installer.ts、platform.ts、workflow-installer.ts、ccr/、cometix/、code-tools/、uninstaller.ts、trash.ts高单元测试广泛CCR 集成src/utils/ccr/Claude Code Router 代理管理与配置presets.ts、commands.ts、installer.ts、config.ts高CCR 测试完整Cometix 工具src/utils/cometix/状态栏工具与配置管理errors.ts、common.ts、types.ts、commands.ts、installer.ts、menu.ts高Cometix 测试丰富Code Toolssrc/utils/code-tools/Codex 集成与双代码工具支持codex-config-detector.ts、codex-provider-manager.ts、codex-uninstaller.ts、codex-platform.ts、codex-config-switch.ts、codex-configure.ts、codex.ts高Codex 测试全面国际化src/i18n/i18next 多语言支持命名空间组织含完整卸载翻译index.ts、locales/zh-CN/、locales/en/高翻译校验Typessrc/types/全面 TypeScript 类型定义含 Claude Code 与 TOML 配置类型workflow.ts、config.ts、ccr.ts、claude-code-config.ts、toml-config.ts通过使用隐式覆盖配置src/config/集中式工作流与系统配置含 API Provider 预设workflows.ts、mcp-services.ts、api-providers.ts高配置校验测试模板templates/多语言合并模板common/共享输出样式、git 工作流与 sixStep 工作流claude-code/、codex/、common/中模板校验测试测试tests/分层覆盖架构测试含高级卸载测试commands/、utils/、unit/、integration/、edge/、i18n/、templates/自测覆盖率目标 80%模块结构图以下 mermaid 图展示了根模块与各子模块之间的依赖关系注该结构图原载于根目录 CLAUDE.md图中 click 链接分别指向src/commands/CLAUDE.md、src/utils/CLAUDE.md、src/i18n/CLAUDE.md、src/types/CLAUDE.md、src/config/CLAUDE.md、templates/claude-code/CLAUDE.md、tests/CLAUDE.md等模块文档可据此逐模块深入阅读。项目规模统计根目录 CLAUDE.md 给出了如下统计口径以文档记录为准总文件约 517 个TypeScript、JSON、Markdownsrc/下源码文件 74 个 TypeScript 文件测试文件 122 个覆盖全面翻译文件 34 个 JSONzh-CN 与 en 各 17 个模板文件 54 个工作流与输出样式10 大模块职责边界清晰。CLI 使用指南ZCF 同时提供直接命令与交互式菜单两种操作方式。入口位于 src/cli.ts使用 cac 解析命令行通过 src/cli-setup.ts 的setupCommands注册全部命令。交互式菜单与快捷命令# 交互式菜单推荐默认命令打开包含全部功能的主菜单 npx zcf # 直接命令 npx zcf i # 完整初始化init 的别名 npx zcf u # 仅更新工作流update 的别名 npx zcf ccr [--lang en|zh-CN] # Claude Code Router 管理 npx zcf ccu [args...] # 携带参数执行 ccusage 用量分析 npx zcf check-updates [--lang en|zh-CN] [--code-type claude-code|codex|codebuddy] # 检查工具更新 npx zcf config-switch [target] [--code-type claude-code|codex|codebuddy] # 切换配置 npx zcf uninstall [--mode complete|custom|interactive] [--items items] [--lang en|zh-CN] [--code-type claude-code|codex|codebuddy] # 卸载 ZCF从 src/cli-setup.ts 的命令注册代码可以确认ccr、ccu、update、check-updates、config-switch、uninstall均注册为独立命令且config-switch有cs别名check-updates有check别名。帮助信息经过customizeHelp定制顶部展示版本横幅并按 commands / options / examples 分组输出所有文案均通过i18n.t()国际化。配置切换示例npx zcf config-switch --list # 列出可用配置 npx zcf config-switch provider1 --code-type codex # 切换 Codex 服务商 npx zcf config-switch config1 --code-type claude-code # 切换 Claude Code 配置 npx zcf config-switch --code-type codebuddy # 切换 CodeBuddy 配置卸载示例npx zcf uninstall # 交互式卸载菜单 npx zcf uninstall --mode complete # 完整卸载 npx zcf uninstall --mode custom --items ccr,backups # 自定义卸载指定项init 命令的非交互参数除-l/--lang、-c/--config-lang、-f/--force等通用选项外init支持完整的非交互CI/CD参数集定义在 src/cli-setup.ts 的CliOptions接口中参数说明取值/默认值--skip-prompt, -s跳过所有交互提示非交互模式布尔--config-action, -r配置文件处理策略new/backup/merge/docs-only/skip默认backup--api-type, -tAPI 认证类型auth_token/api_key/ccr_proxy/skip--api-key, -kAPI 密钥api_key 与 auth_token 通用字符串--api-url, -u自定义 API URL字符串--api-model, -M主模型如claude-sonnet-4-5--api-haiku-model, -HHaiku 模型如claude-haiku-4-5--api-sonnet-model, -SSonnet 模型如claude-sonnet-4-5--api-opus-model, -OOpus 模型如claude-opus-4-5--provider, -pAPI 服务商预设302ai/glm/minimax/kimi/custom等--mcp-services, -m要安装的 MCP 服务逗号分隔context7,mcp-deepwiki,Playwright,exaskip跳过全部all安装全部免密钥服务默认all--workflows, -w要安装的工作流逗号分隔sixStepsWorkflow,featPlanUx,gitWorkflow,bmadWorkflowskip跳过all全部默认all--output-styles, -o输出样式逗号分隔engineer-professional,nekomata-engineer,laowang-engineer,default,explanatory,learningskip跳过all全部默认all--default-output-style, -d默认输出样式默认engineer-professional--all-lang, -g统一设置全部语言参数zh-CN/en--code-type, -T代码工具类型claude-code/codex/cc等价 claude-code/cx等价 codex--install-cometix-line, -x是否安装 CCometixLine 状态栏工具true/false默认true--api-configs多配置档位的 API 配置JSON 字符串JSON--api-configs-file多配置档位 API 配置的文件路径路径CI/CD 场景典型用法npx zcf i --skip-prompt --api-type api_key --api-key sk-ant-... npx zcf i --skip-prompt --all-lang zh-CN --api-type api_key --api-key key npx zcf i --skip-prompt --api-type ccr_proxy语言解析优先级在 src/cli-setup.ts 的resolveAndSwitchLanguage中实现allLang lang 配置文件 preferredLang 交互提示若传入skipPrompt且无其他语言来源则回退到en。命令执行前统一经过withLanguageResolution包装器完成语言切换。代码工具类型别名机制src/constants.ts 定义了短别名映射cc→claude-codecx→codexresolveCodeToolType会优先按字面值匹配再尝试别名最后回退默认值claude-codesrc/constants.ts。配置系统源码解读API Provider 预设系统src/config/api-providers.ts 定义了ApiProviderPreset接口每个预设包含 id、显示名、支持的代码工具类型以及针对 Claude CodebaseUrl authType 默认模型与 CodexbaseUrl wireApi 默认模型的分配置。当前内置预设包括预设 id名称支持工具Claude Code 认证类型Codex baseUrlpackycodePackyCodeclaude-code, codexauth_tokenhttps://www.packyapi.com/v1code0code0claude-code, codexapi_keyhttps://code0.ai/v1/openaiclaude-apiClaude APIclaude-codeapi_key—patewayPatewayAIclaude-code, codexapi_keyhttps://api.pateway.ai/v1apikey-funAPIKEY.FUNclaude-code, codexauth_tokenhttps://api.apikey.fun/v1302ai302.AIclaude-code, codexapi_keyhttps://api.302.ai/v1aicodemirrorAICodeMirrorclaude-code, codexauth_tokenhttps://api.aicodemirror.com/api/codex/backend-api/codexaicodemirror-cnAICodeMirror CNclaude-code, codexauth_tokenhttps://api.claudecode.net.cn/api/codex/backend-api/codexcrazyrouterCrazyrouterclaude-code, codexapi_keyhttps://crazyrouter.com/v1aihubAIHubclaude-code, codexapi_keyhttps://aihub.top/v1glm-cnGLM CNclaude-codeauth_token—z-aiZ.aiclaude-codeauth_token—bailian-codingBailian Codingclaude-codeauth_token默认模型 glm-5—minimaxMiniMaxclaude-code, codexauth_token默认模型 MiniMax-M3、MiniMax-M2.7https://api.minimax.io/v1kimi-codingKimi Codingclaude-codeauth_token—deepseekDeepSeekclaude-codeauth_token默认模型 deepseek-v4-pro、deepseek-v4-flash—工具函数getApiProviders(codeToolType)按代码工具类型过滤可用预设getProviderPreset(id)按 id 查找getValidProviderIds()返回全部合法 id。这解释了选择服务商 填写密钥两步完成 API 配置的实现原理选中预设后baseUrl 与 authType 均由源码直接填充。MCP 服务配置src/config/mcp-services.ts 定义了 7 个内置 MCP 服务的纯业务配置服务 id是否需 API Key命令/URLcontext7否npx -y upstash/context7-mcplateststdioopen-websearch否npx -y open-websearchlateststdio带 MODE / DEFAULT_SEARCH_ENGINE / ALLOWED_SEARCH_ENGINES 环境变量spec-workflow否npx -y pimzino/spec-workflow-mcplateststdiomcp-deepwiki否HTTPhttps://mcp.deepwiki.com/mcpPlaywright否npx -y playwright/mcplateststdioexa是EXA_API_KEYnpx -y exa-mcp-serverlateststdioserena否uvx --from githttps://github.com/oraios/serena ...stdiogetMcpServices()将业务配置与 i18n 翻译合并requiresApiKey为 true 的服务如 exa会附带apiKeyEnvVar与apiKeyPrompt在交互流程中引导用户填入密钥。根目录 CLAUDE.md 特别强调MCP 配置需要针对 Windows 路径做专门的转义与校验处理。工作流配置src/config/workflows.ts 定义了 5 个默认工作流全部默认选中按 order 排序工作流 id分类关联 Skills自动安装 AgentscommonToolscommoninit-project是init-architect、get-current-datetimesixStepsWorkflowsixStepworkflow否featPlanUxplanfeat是planner、ui-ux-designergitWorkflowgitgit-commit、git-rollback、git-clean-branches、git-worktree否bmadWorkflowbmadbmad-init否对应模板位于 templates/skills/ 与 templates/claude-code/其中 plan 分类的 planner 与 ui-ux-designer agent 模板可从 templates/claude-code/zh-CN/workflow/plan/agents/ 与 templates/claude-code/en/workflow/plan/agents/ 查看。关键路径常量src/constants.ts 集中定义了所有配置路径Claude Code~/.claude/settings.json、CLAUDE.md、config.json与~/.claude.jsonCodex~/.codex/config.toml、auth.json、AGENTS.md、prompts 目录ZCF 自身~/.ufomiao/zcf/config.toml并兼容两个旧版配置位置~/.claude/.zcf-config.json、~/.zcf.json。所有路径通过pathe的join拼接保证跨平台正确性。运行、构建与开发Build Run# 开发模式使用 tsx 直接执行 TypeScript pnpm dev # 生产构建使用 unbuild pnpm build # 类型检查 pnpm typecheck对应脚本定义于 package.jsondev为tsx ./src/cli.tsbuild为unbuildstart为node bin/zcf.mjsnpm 包的 bin 入口指向bin/zcf.mjs。代码质量与 Lint# 运行 ESLint使用 antfu/eslint-config pnpm lint # 自动修复 ESLint 问题 pnpm lint:fix项目同时配置了 Husky pre-commit 钩子与 lint-staged对所有文件执行pnpm lint以及 commitlint 约定式提交校验package.json。文档# 启动 VitePress 文档开发服务器 pnpm docs:dev # 构建生产文档 pnpm docs:build # 预览构建产物 pnpm docs:preview文档源码位于 docs/ 目录按 en、zh-CN、ja-JP 三种语言组织。测试策略# 运行全部测试 pnpm test # 监视模式开发用 pnpm test:watch # 带 UI 运行测试 pnpm test:ui # 生成覆盖率报告 pnpm test:coverage # 单次运行测试 pnpm test:run # 运行指定测试文件 pnpm vitest utils/config.test.ts # 按模式匹配运行测试 pnpm vitest --grep should handle # 专门运行 uninstaller 测试 pnpm vitest uninstaller项目采用 Vitest 分层测试架构根目录 CLAUDE.md 明确了五层结构核心测试*.test.ts基础功能与主流程边界测试*.edge.test.ts边界条件与错误场景单元测试tests/unit/隔离函数测试集成测试tests/integration/跨模块交互测试覆盖率目标行、函数、分支、语句四维度最低 80%。测试目录 tests/ 下可以看到与命令、工具、配置一一对应的测试文件例如tests/utils/下的 uninstaller 系列测试、tests/unit/utils/code-tools/下的 Codex 配置切换与备份还原测试。开发规范核心原则文档语言除 README_zh-CN 外代码注释与全部 Markdown 文档使用英文Git 提交信息使用英文测试驱动开发TDD所有功能必须先写测试再实现遵循 Red-Green-Refactor 循环每个函数/特性在实现前必须有对应测试覆盖编写测试前先检查相关测试文件是否已存在避免重复四维度覆盖率不低于 80%国际化i18n规范所有用户可见的提示、日志与错误信息必须通过 i18next 支持 i18n采用全项目统一 i18n 方案与集中式语言管理按命名空间组织翻译zh-CN 与 en 双语言功能完全对齐所有可翻译字符串统一使用i18n.t()并带命名空间前缀翻译按 common、cli、menu、errors、api、tools、uninstall 等逻辑命名空间组织。编码标准纯 ESM项目完全 ESM无 CommonJS 回退路径处理使用pathe做跨平台路径操作命令执行使用tinyexec提升跨平台支持TypeScript严格模式显式类型定义ESNext 配置错误处理全面错误处理用户友好且支持 i18n 的消息跨平台支持Windows 路径、macOS、Linux 与 Termux 环境的专门处理代码格式化antfu/eslint-config 严格规则测试组织完整的 unit/integration/edge 结构与 80% 覆盖率要求回收站集成使用trash包实现安全的跨平台文件删除。ZCF AI 团队配置根目录 CLAUDE.md 描述了一套面向 CLI 开发、i18n 系统与工具集成优化的专业 AI Agent 团队每位 Agent 具备明确的领域专长与边界便于协作分工。团队构成如下Agent模型领域主要职责typescript-cli-architectsonnetCLI 架构TypeScript CLI 设计、CAC 集成、ESM 模块、开发者体验zcf-i18n-specialistopus国际化i18next 配置、翻译管理、命名空间组织zcf-tools-integration-specialistsonnet工具集成CCR/Cometix/CCusage 集成、版本管理、跨平台兼容zcf-template-enginehaiku模板系统模板设计、工作流配置、输出样式、多语言模板zcf-config-architectopus配置管理配置合并、MCP 服务、TOML/JSON 校验、备份系统zcf-testing-specialistsonnet测试基础设施Vitest 配置、测试覆盖、Mock 系统、质量保障zcf-devops-engineerinheritDevOps 与部署构建优化、发布管理、CI/CD、跨平台部署模型选择依据Opus承担 i18n 逻辑与配置架构等复杂推理任务Sonnet为 CLI 架构、工具集成与测试提供均衡性能Haiku快速响应模板处理与简单操作Inherit对无需专门模型的 DevOps 任务更具成本效益。关键架构模式与实现细节根目录 CLAUDE.md 归纳的十大架构模式高级模块化命令结构每个命令自包含具备完整的选项接口与精细的错误处理高级 i18next I18N 支持全部用户可见字符串支持 zh-CN/en 双语言命名空间组织动态语言切换智能配置合并带完整备份系统的配置合并保留用户自定义修改前在~/.claude/backup/生成带时间戳的备份支持完整恢复全面跨平台支持Windows/macOS/Linux/Termux 兼容平台适配与路径处理合并模板系统templates/common/共享 output-styles、git 工作流与 sixStep 工作流减少 Claude Code、Codex、CodeBuddy 之间的重复智能 IDE 集成针对 git-worktree 环境的 IDE 检测与自动打开专业 AI 人格系统多种输出样式包括 engineer-professional、laowang-engineer、nekomata-engineer、ojousama-engineer、rem-engineer模板见 templates/common/output-styles/高级工具集成CCR 代理、CCusage 分析与 Cometix 状态栏工具精密卸载系统冲突解决、选择性移除、跨平台回收站集成多代码工具架构同时支持 Claude Code、Codex、CodeBuddy 环境配置共享模板资源。重要实现细节Windows 兼容MCP 配置需要复杂的 Windows 路径处理转义与校验见 src/utils/CLAUDE.md 中的fixWindowsMcpConfig接口配置备份所有修改在~/.claude/backup/生成带时间戳备份具备完整恢复能力API 配置支持 Auth TokenOAuth、API Key 与 CCR Proxy 三种认证带全面校验与 API Provider 预设系统v3.3.3智能自动更新自动更新 Claude Code、CodeBuddy、CCR 与 CCometixLine含版本检查工作流系统模块化安装具备依赖解析与冲突管理能力。测试哲学全面 Mock 策略对文件系统操作、外部命令与用户提示进行广泛 Mock覆盖真实场景高级跨平台测试平台检测 Mock 与完整的环境特定测试用例精细边界测试完整的边界条件、错误场景与恢复机制测试质量优先覆盖四维度 80% 最低覆盖率强调质量优先于数量高级集成测试完整工作流场景与外部工具交互测试卸载边界测试覆盖失败恢复与冲突解决的卸载场景测试。发布与版本管理# 为版本更新创建 changeset pnpm changeset # 根据 changeset 更新包版本 pnpm version # 构建并发布到 npm pnpm release其中release实际执行为pnpm build changeset publishpackage.jsonprepublishOnly钩子保证发布前自动构建。npm 包发布内容由files字段限定为bin、dist、templates三部分。小结ZCF 的根目录 CLAUDE.md 完整刻画了一个零配置、多工具、强 i18n的 CLI 项目从模块化命令架构src/commands/、工具集成层src/utils/、命名空间 i18nsrc/i18n/到 Provider 预设src/config/api-providers.ts、MCP 服务src/config/mcp-services.ts与工作流定义src/config/workflows.ts每一层都有清晰的文件落点与测试保障。对开发者而言既可以npx zcf直接使用也可以通过 tests/ 下的分层测试体系了解各模块行为或借助文档目录 docs/含 en、zh-CN、ja-JP 三语言深入进阶主题API Providers、多配置、工作流等。赞分享开发工具CLIAI 应用【免费下载链接】zcfZero-Config Code Flow for Claude code Codex项目地址https://gitcode.com/gh_mirrors/zc/zcf点击查看免费下载相关推荐ZCFZero-Config Code Flow快速开始指南npx 一键初始化 Claude Code 与 Codex 环境ZCFZero Config Code Flow快速开始指南npx 一键初始化 Claude Code 与 Codex 环境 ZCFZero Confi开发工具CLIAI 应用ZCFZero-Config Code Flow全面解析Claude Code 与 Codex 零配置环境搭建指南ZCFZero Config Code Flow全面解析Claude Code 与 Codex 零配置环境搭建指南 ZCF 是一个面向专业开发者的命令行工开发工具CLIAI 应用ZCF 项目全景解析Zero-Config Code Flow 为 Claude Code 与 Codex 的一键零配置环境搭建ZCF 项目全景解析Zero Config Code Flow 为 Claude Code 与 Codex 的一键零配置环境搭建 ZCFZero Confi开发工具CLIAI 应用上一篇内核态 ROP 入门与实战基于 CTF-Wiki 的 commit_creds 提权与强网杯 2018 core 完整利用下一篇awesome-osint-arsenal是什么753个OSINT开源情报工具武器库完全解读创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考