zcf 介绍
了解项目的详细信息和使用方法
✨ 快速链接: Codex 支持 | BMad 工作流 | Spec 工作流 | 开放网络搜索 | CCR 路由器 | CCometixLine | AI 输出样式 | 多配置管理
零配置、一键设置 Claude Code 和 Codex，支持双语、智能代理系统和个性化 AI 助手
🚀 快速开始
🎯 推荐：使用交互式菜单 (v2.0 新增)
bash1npx zcf # 打开交互式菜单，根据需要选择操作
菜单选项包括：
1完整初始化 (相当于zcf i)2导入工作流 (相当于zcf u)3配置 API 或 CCR - API 配置或 CCR 代理设置4配置 MCP - MCP 服务配置和管理5配置默认模型 - 设置默认模型 (opus/sonnet/sonnet 1m/自定义)6配置 AI 记忆 - 配置 AI 输出语言和全局输出样式7配置环境权限 - 导入环境变量和权限RClaude Code 路由器管理 (v2.8.1 增强)Uccusage - Claude Code 使用情况分析LCCometixLine - 高性能状态栏工具，集成 Git 和实时使用追踪 (v2.9.9+ 新增)+检查更新 - 检查并更新 Claude Code、CCR 和 CCometixLine 版本 (v2.9.9+ 增强)- 更多功能...
🎯 关键配置功能
模型配置 (选项 5): 灵活配置您的默认 Claude 模型：
- 默认: 让 Claude Code 自动为每个任务选择最佳模型
- Opus: 专门使用 Claude-4.1-Opus (令牌消耗高，请谨慎使用)
- Sonnet 1M: 使用具有 1M 上下文窗口的 Sonnet，适用于更大的上下文任务
- 自定义: 为主要任务和快速任务指定自己的模型名称 (支持任何自定义模型)
AI 记忆配置 (选项 6): 个性化您的 AI 助手：
- AI 输出语言: 设置 AI 响应的语言 (中文、英文或自定义)
- 全局输出样式: 配置 AI 个性和响应风格
或者，使用直接命令：
🆕 首次使用 Claude Code
bash1npx zcf i # 直接执行完整初始化：安装 Claude Code + 导入工作流 + 配置 API + 设置 MCP 服务 2# 或 3npx zcf → 选择 1 # 通过菜单执行完整初始化
🔄 已安装 Claude Code
bash1npx zcf u # 仅更新工作流：快速添加 AI 工作流和命令系统 2# 或 3npx zcf → 选择 2 # 通过菜单执行工作流更新
注意:
- 从 v2.0 开始，
zcf默认打开交互式菜单，提供可视化操作界面- 您可以通过菜单选择操作，或直接使用命令快速执行
zcf i= 完整初始化，zcf u= 仅更新工作流
🌐 语言支持
ZCF 支持双语操作，所有命令自动切换语言：
bash1# 使用中文进行所有操作 2npx zcf --lang zh-CN # 中文交互式菜单 3npx zcf init --lang zh-CN # 中文界面初始化 4npx zcf ccr --all-lang zh-CN # 中文配置 CCR 5 6# 语言参数优先级 (从高到低)： 7# --all-lang > --lang > 保存的用户偏好 > 交互式提示
语言参数：
--lang, -l: ZCF 界面语言 (适用于所有命令)--all-lang, -g: 一次性设置所有语言参数 (最方便)--config-lang, -c: 模板文件语言 (仅限 init/update 命令)--ai-output-lang, -a: AI 助手输出语言 (仅限 init 命令)
🤖 非交互模式
适用于 CI/CD 和自动化设置，使用 --skip-prompt 配合参数：
bash1# 简写版本 2npx zcf i -s -g zh-CN -t api_key -k "sk-xxx" -u "https://xxx.xxx" 3 4# 完整版本 5npx zcf i --skip-prompt --all-lang zh-CN --api-type api_key --api-key "sk-xxx" --api-url "https://xxx.xxx" 6 7# 简写版本 (带自定义模型) 8npx zcf i -s -t api_key -k "sk-xxx" -M "claude-sonnet-4-5" -F "claude-haiku-4-5" 9 10# 完整版本 (带自定义模型) 11npx zcf i --skip-prompt \ 12 --api-type api_key \ 13 --api-key "sk-xxx" \ 14 --api-url "https://xxx.xxx" \ 15 --api-model "claude-sonnet-4-5" \ 16 --api-fast-model "claude-haiku-4-5"
非交互模式参数
使用 --skip-prompt 时，可用以下参数：
| 参数 | 描述 | 值 | 必需 | 默认值 |
|---|---|---|---|---|
--skip-prompt, -s | 跳过所有交互式提示 | - | 是 (非交互模式) | - |
--lang, -l | ZCF 显示语言 (适用于所有命令) | zh-CN, en | 否 | en 或用户保存的偏好 |
--config-lang, -c | 配置语言 (模板文件语言) | zh-CN, en | 否 | en |
--ai-output-lang, -a | AI 输出语言 | zh-CN, en, 自定义字符串 | 否 | en |
--all-lang, -g | 设置所有语言参数 (适用于所有命令) | zh-CN, en, 自定义字符串 | 否 | - (优先级：--all-lang > --lang > 保存的用户偏好 > 交互式提示。自定义字符串将 AI 输出语言设置为自定义，而交互和配置语言保持 'en') |
--config-action, -r | 配置处理 | new, backup, merge, docs-only, skip | 否 | backup |
--api-type, -t | API 配置类型 | auth_token, api_key, ccr_proxy, skip | 否 | skip |
--api-key, -k | API 密钥 (适用于 API 密钥和认证令牌类型) | 字符串 | 当 api-type 不是 skip 时必需 | - |
--api-url, -u | 自定义 API URL | URL 字符串 | 否 | 官方 API |
--api-model, -M | 主要 API 模型 | 字符串 (例如 claude-sonnet-4-5) | 否 | - |
--api-fast-model, -F | 快速 API 模型 (仅限 Claude Code) | 字符串 (例如 claude-haiku-4-5) | 否 | - |
--mcp-services, -m | 要安装的 MCP 服务 (多选，逗号分隔) | context7, open-websearch, spec-workflow, mcp-deepwiki, Playwright, exa, serena, 或 skip 表示不安装 | 否 | all |
--workflows, -w | 要安装的工作流 (多选，逗号分隔) | commonTools, sixStepsWorkflow, featPlanUx, gitWorkflow, bmadWorkflow, 或 skip 表示不安装 | 否 | all |
--output-styles, -o | 要安装的输出样式 (多选，逗号分隔) | engineer-professional, nekomata-engineer, laowang-engineer, ojousama-engineer, 或 skip 表示不安装 | 否 | all |
--default-output-style, -d | 默认输出样式 | 与输出样式相同，加上内置：default, explanatory, learning | 否 | engineer-professional |
--install-cometix-line, -x | 安装 CCometixLine 状态栏工具 | true, false | 否 | true |
🤖 Codex 支持 (v3.0.0+ 新增)
Codex 是 OpenAI 官方的代码生成 CLI 工具。ZCF 现在支持完整的 Codex 集成，提供与 Claude Code 相同的配置便利性。
主要特性：
- 统一工具管理: 通过 ZCF 菜单在 Claude Code 和 Codex 之间无缝切换
- 智能配置: 自动安装 Codex CLI、设置 API 提供商和集成 MCP 服务
- 完整备份系统: 所有配置更改都包含带时间戳的备份，具有恢复能力
- 多提供商支持: 配置多个 API 提供商 (OpenAI、自定义端点)，支持轻松切换
- 系统提示集成: 安装专业的 AI 个性 (工程师、猫又工程师、老王工程师)
- 工作流模板: 导入针对代码生成任务优化的结构化开发工作流
- 高级卸载器: 选择性移除 Codex 组件，解决冲突
开始使用 Codex：
在 ZCF 主菜单中切换到 Codex 模式：
bash1npx zcf → 选择 S # 在 Claude Code 和 Codex 之间切换
或直接访问 Codex 功能：
bash1# 完整 Codex 初始化 2npx zcf → 选择 1 (切换到 Codex 模式后) 3 4# 单独 Codex 配置 5npx zcf → 选择 3 # 配置 Codex API 提供商 6npx zcf → 选择 4 # 配置 Codex MCP 服务
配置选项：
-
API 提供商配置：
- 官方登录: 使用 OpenAI 的官方认证系统
- 自定义提供商: 配置多个 API 端点，支持提供商切换
- 增量管理: 添加、编辑或移除提供商，不影响现有配置
-
系统提示样式：
- 工程师专业版: 遵循 SOLID、KISS、DRY、YAGNI 原则的稳健代码
- 猫又工程师: 严谨技术标准的可爱猫娘工程师
- 老王工程师: 从不容忍不合格代码的暴躁技术风格
-
工作流集成：
- 六步工作流: 从研究到优化的结构化开发流程
- 自定义工作流: 导入和配置特定任务的开发模板
- ⚠️ 重要: 由于 Codex 提示限制，
/workflow命令无法直接传递参数。先使用/workflow，然后在后续消息中提供任务描述
-
MCP 服务: 完全兼容现有 MCP 服务，包括：
- Context7、开放网络搜索、Spec 工作流
- DeepWiki、Playwright、EXA 搜索
- Serena 助手，用于语义代码检索和编辑
- 自动服务配置和 API 密钥管理
文件位置：
- 配置：
~/.codex/config.toml - 认证：
~/.codex/auth.json - 系统提示：
~/.codex/AGENTS.md - 工作流：
~/.codex/prompts/ - 备份：
~/.codex/backup/
工具间迁移：
ZCF 允许在 Claude Code 和 Codex 之间无缝切换，同时保留您的偏好和工作流配置。两个工具共享相同的 MCP 服务和工作流模板，提供一致的开发体验。
🎨 AI 输出样式 (v2.12+ 新功能)
ZCF 现在支持可定制的 AI 输出样式，个性化您的 Claude Code 体验：
可用输出样式：
engineer-professional: 遵循 SOLID、KISS、DRY、YAGNI 原则的专业软件工程师nekomata-engineer: 专业的猫娘工程师 UFO Nya，结合严谨工程与可爱猫娘特质laowang-engineer: 老王暴躁技术风格，从不容忍代码错误和非标准代码ojousama-engineer: 傲娇金发大小姐程序员 Halley-chan，结合严谨工程卓越与傲娇大小姐特质- 内置样式：
default,explanatory,learning(始终可用)
特性：
- 安装多个样式并在它们之间切换
- 为所有项目设置全局默认样式
- 自动清理旧版个性文件
- 基于模板的定制系统
使用技巧：
- 使用
/output-style命令随时切换项目级输出样式 - 或在 ZCF 菜单选项 6 中修改全局输出样式
重要：
- Claude Code 版本必须大于 1.0.81 才能支持 output-style。使用
npx zcf check进行更新。 - 旧版全局记忆规则已迁移到
engineer-professional输出样式，解决了令牌使用过多和 AI 忘记全局记忆的问题。
🎯 BMad 工作流 (v2.7 新功能)
BMad (BMad 方法：通用 AI 代理框架) 是一个企业级工作流系统，提供：
- 完整的专业 AI 代理团队 (产品负责人、项目经理、架构师、开发、测试等)
- 带质量门控的结构化开发流程
- 自动文档生成
- 支持新项目和现有项目
安装后，在项目中使用 /bmad-init 初始化 BMad 工作流。
📋 Spec 工作流 (v2.12.4+ 新功能)
Spec 工作流 是一个全面的 MCP 服务，提供从需求到实现的结构化功能开发工作流：
- 需求分析: 结构化需求收集和文档化
- 设计阶段: 详细技术设计和架构规划
- 任务管理: 自动任务分解和进度跟踪
- 实现工作流: 从需求到实现的系统方法
- 交互式仪表板: 内置工作流可视化管理仪表板
- 审批系统: 每个开发阶段的评审和批准流程
Spec Workflow MCP 提供可选仪表板用于工作流可视化。用户可以手动启动仪表板：
bash1npx -y @pimzino/spec-workflow-mcp@latest --dashboard
或者，您可以安装 VS Code 扩展 进行集成的工作流管理。
使用指南: 详细使用说明和最佳实践，请参阅 官方 Spec 工作流文档。
🔍 开放网络搜索 (v2.12.9+ 新功能)
开放网络搜索 是一个多功能网络搜索 MCP 服务，提供对多个搜索引擎的访问：
- 多引擎支持: 跨 DuckDuckGo、Bing 和 Brave 搜索引擎搜索
- 注重隐私: 默认使用尊重隐私的搜索引擎
- 灵活配置: 可定制的搜索引擎偏好
- 无需 API 密钥: 无需额外认证即可使用
- 搜索聚合: 能够合并多个引擎的结果
🚀 CCR (Claude Code 路由器) 支持 (v2.8+ 增强)
CCR 是一个强大的代理路由器，支持：
- 免费模型访问: 通过 Claude Code 界面使用免费 AI 模型 (如 Gemini、DeepSeek)
- 自定义路由: 根据您的规则将不同类型的请求路由到不同的模型
- 成本优化: 通过为不同任务使用适当的模型显著降低 API 成本
- 轻松管理: 用于 CCR 配置和服务控制的交互式菜单
- 自动更新: CCR 和 Claude Code 的自动版本检查和更新 (v2.8.1+)
访问 CCR 功能：
bash1npx zcf ccr # 打开 CCR 管理菜单 2# 或 3npx zcf → 选择 R
CCR 菜单选项：
- 初始化 CCR - 使用预设提供商安装和配置 CCR
- 启动 UI - 启动 CCR Web 界面进行高级配置
- 服务控制 - 启动/停止/重启 CCR 服务
- 检查状态 - 查看当前 CCR 服务状态
CCR 设置后，ZCF 自动配置 Claude Code 使用 CCR 作为 API 代理。
📊 CCometixLine 支持 (状态栏工具) (v2.9.9+ 新增)
CCometixLine 是一个基于 Rust 的高性能状态栏工具，提供：
- 实时使用追踪: 实时监控 Claude Code API 使用情况
- Git 集成: 显示 Git 状态和分支信息
- 状态栏显示: 与您的终端状态栏原生集成
- 性能优化: 使用 Rust 构建，资源使用最少
- TUI 配置: 交互式终端 UI，用于自定义主题、段和显示选项
- 自动更新: 包含在 ZCF 的更新检查系统中
CCometixLine 菜单选项 (通过 npx zcf → L 访问)：
1安装或更新 - 使用 npm 安装或更新 CCometixLine2打印默认配置 - 显示当前 CCometixLine 配置3自定义配置 - TUI 配置模式 - 交互式终端 UI 用于自定义设置
v2.9.9 用户重要提示: 如果您之前使用过 ZCF v2.9.9 设置环境，请重新运行初始化过程以确保正确添加 CCometixLine 配置。运行
npx zcf并选择适当的设置选项，使用 CCometixLine 支持更新您的配置。
🚀 检查更新 (v2.8.1+, CCometixLine 支持 v2.9.9+)：
bash1npx zcf check-updates # 检查并更新 Claude Code、CCR 和 CCometixLine 到最新版本 2# 或 3npx zcf → 选择 +
设置过程
完整初始化 (npx zcf) 将自动：
- ✅ 检测并安装 Claude Code
- ✅ 选择 AI 输出语言 (新功能)
- ✅ 配置 API 密钥或 CCR 代理
- ✅ 选择和配置 MCP 服务
- ✅ 设置所有必要的配置文件
使用
配置后：
- 首次在项目中使用时，强烈建议运行
/init-project生成 CLAUDE.md，以便 AI 更好地理解项目架构 <任务描述>- 直接执行，无需工作流，遵循 SOLID、KISS、DRY 和 YAGNI 原则，适用于小任务如错误修复/feat <任务描述>- 开始新功能开发，分为计划和 UI 阶段/workflow <任务描述>- 执行完整开发工作流，非自动化，从多个解决方案选项开始，在每个步骤询问用户反馈，允许计划修改，最大控制
附注:
- feat 和 workflow 各有优势，可以都试试比较
- 生成的文档默认位于项目根目录的
.claude/xxx.md，您可以将.claude/添加到项目的.gitignore
✨ ZCF 工具特性
🌏 多语言支持
- 脚本交互语言：控制安装提示语言
- 配置文件语言：确定安装哪个配置集 (zh-CN/en)
- AI 输出语言：选择 AI 响应的语言 (支持中文、英文和自定义语言)
- AI 输出样式：支持多种预设样式 (专业工程师、猫又工程师、老王工程师、大小姐工程师)，提供定制化体验
🔧 智能安装
- 自动检测 Claude Code 安装状态
- 使用 npm 自动安装 (确保兼容性)
- 跨平台支持 (Windows/macOS/Linux/WSL/Termux)
- 自动 MCP 服务配置
- 智能配置合并和部分修改支持 (v2.0 新增)
- 增强的命令检测机制 (v2.1 新增)
- 危险操作确认机制 (v2.3 新增)
📦 完整配置
- CLAUDE.md 系统指令
- settings.json 配置文件
- commands 自定义命令
- agents AI 代理配置
🔐 API 配置
- 支持两种认证方式：
- 认证令牌: 用于通过 OAuth 或浏览器登录获取的令牌
- API 密钥: 用于从 Anthropic 控制台获取的 API 密钥
- 自定义 API URL 支持
- 支持稍后手动配置
- 部分修改：仅更新需要的配置项 (v2.0 新增)
💾 配置管理
- 智能备份现有配置 (所有备份保存在 ~/.claude/backup/)
- 配置合并选项 (v2.0 增强：支持深度合并)
- 安全覆盖机制
- MCP 配置更改前自动备份
- 默认模型配置 (v2.0 新增)
- AI 记忆管理 (v2.0 新增)
- ZCF 缓存清理 (v2.0 新增)
🧩 多配置管理 (v3.2.0 新增)
为 Claude Code 和 Codex 提供统一、增量、交互式管理：- Claude Code：管理 API 配置文件（添加/编辑/删除、默认配置、重复检测）
- Codex：管理模型提供商（列表/切换、通过交互式官方登录）
- 安全备份；防止删除最后一个配置文件（Claude Code）
- 将环境设置应用到
~/.claude/settings.json并在需要时重启 CCR - 配置存储：
~/.ufomiao/zcf/config.toml（备份文件为config.backup.YYYY-MM-DD_HH-mm-ss.toml）
明确选择工具类型：
bash1# -T 接受：claude-code|codex 或短别名 cc|cx 2npx zcf cs --list -T cc # 列出 Claude Code 配置文件 3npx zcf cs --list -T cx # 列出 Codex 提供商 4npx zcf cs -l -T cc # --list 的短选项 5npx zcf cs -l -T cx # --list 的短选项
Claude Code 用法：
bash1# 快速切换 2npx zcf cs official -T cc # 切换到官方登录 3npx zcf cs ccr -T cc # 切换到 CCR 代理 4npx zcf cs my-profile -T cc
Codex 用法：
bash1# 列出并切换提供商 2npx zcf cs --list -T cx 3npx zcf cs my-provider -T cx 4 5# 切换到官方登录（交互式选择） 6npx zcf config-switch -T cx
注意：
- 环境变量映射（Claude Code）：API 密钥 →
ANTHROPIC_API_KEY，认证令牌 →ANTHROPIC_AUTH_TOKEN，基础 URL →ANTHROPIC_BASE_URL。 - 当前激活的代码工具类型存储在 ZCF 配置中；仅当目标工具与当前工具不同时使用
-T cc/cx。
📖 使用说明
交互式菜单（v2.0）
bash1$ npx zcf 2 3 ZCF - 零配置代码流 4 5? 选择 ZCF 显示语言 / Select ZCF display language: 6 ❯ 简体中文 7 English 8 9选择功能： 10 -------- Claude Code -------- 11 1. 完整初始化 - 安装 Claude Code + 导入工作流 + 配置 API 或 CCR 代理 + 配置 MCP 服务 12 2. 导入工作流 - 仅导入/更新工作流相关文件 13 3. 配置 API - 配置 API URL 和认证（支持 CCR 代理） 14 4. 配置 MCP - 配置 MCP 服务（包含 Windows 修复） 15 5. 配置默认模型 - 设置默认模型（opus/sonnet/sonnet 1m/自定义） 16 6. 配置 Claude 全局记忆 - 配置 AI 输出语言和输出风格 17 7. 导入推荐环境变量和权限 - 导入隐私保护环境变量和系统权限 18 19 --------- 其他工具 ---------- 20 R. CCR - Claude Code 路由器管理 21 U. ccusage - Claude Code 使用情况分析 22 L. CCometixLine - 高性能状态栏工具，集成 Git 和实时使用情况跟踪 23 24 ------------ ZCF ------------ 25 0. 选择显示语言 / 更改显示语言 - 更改 ZCF 界面语言 26 -. 卸载 - 从系统中移除 Claude Code 配置和工具 27 +. 检查更新 - 检查并更新 Claude Code、CCR 和 CCometixLine 版本 28 Q. 退出 29 30输入您的选择：_
完整初始化流程（选择 1 或使用 zcf i）
bash1? 选择 Claude Code 配置语言： 2 ❯ English (en) - 英语（推荐，Token 消耗更低） 3 简体中文 (zh-CN) - 中文（便于中文用户自定义） 4 日本語 (ja) - 日语（面向日本用户） 5 6? 选择 AI 输出语言： 7 AI 将使用此语言回复您 8 ❯ English 9 简体中文 10 日本語 11 自定义 12 （支持法语、德语等更多语言） 13 14? 未找到 Claude Code。是否自动安装？(Y/n) 15 16✔ Claude Code 安装成功 17 18? 检测到现有配置。如何处理？ 19 ❯ 备份并覆盖 - 将现有配置备份到 ~/.claude/backup/ 20 仅更新文档 - 仅更新工作流和文档，保留现有 API 配置 21 合并配置 - 与现有配置合并，保留用户自定义设置 22 跳过 - 跳过配置更新 23 24? 选择 API 认证方式 25 ❯ 使用官方登录 26 使用官方认证系统，无需配置 API 27 使用认证令牌（OAuth 认证） 28 适用于通过 OAuth 或浏览器登录获取的令牌 29 使用 API 密钥（密钥认证） 30 适用于从 Anthropic 控制台获取的 API 密钥 31 配置 CCR 代理（Claude Code 路由器） 32 通过代理路由使用多个 AI 模型以降低成本并探索可能性 33 跳过（稍后手动配置） 34 35? 输入 API URL：https://api.anthropic.com 36? 输入认证令牌或 API 密钥：xxx 37 38? 选择要安装的输出风格： 39 ❯ 工程师专业版 - 遵循 SOLID、KISS、DRY、YAGNI 原则的专业软件工程师 40 猫娘工程师 - 专业的猫娘工程师 UFO Nya，结合严谨工程学与可爱猫娘特质 41 老王暴躁技术风 - 老王暴躁技术风格，绝不容忍代码错误和非规范代码 42 大小姐工程师 - 傲娇金发大小姐程序员 Halley-chan，结合严谨工程卓越与傲娇大小姐特质 43 44? 选择全局默认输出风格： 45 ❯ 工程师专业版 46 47? 选择要安装的工作流（空格选择，回车确认）： 48❯ ◉ 常用工具（init-project + init-architect + get-current-datetime）- 必要的项目初始化和实用命令 49◉ 六步工作流（workflow）- 完整的六阶段开发流程 50◉ 功能规划与 UX 设计（feat + planner + ui-ux-designer）- 结构化功能开发 51◉ Git 命令（commit + rollback + cleanBranches + worktree）- 简化的 Git 操作 52◉ BMAD 方法扩展安装器 - 企业级敏捷开发工作流 53 54✔ 正在安装工作流... 55✔ 已安装命令：zcf/workflow.md 56✔ 已安装命令：zcf/feat.md 57✔ 已安装代理：zcf/plan/planner.md 58✔ 已安装代理：zcf/plan/ui-ux-designer.md 59✔ 已安装命令：zcf/git/git-commit.md 60✔ 已安装命令：zcf/git/git-rollback.md 61✔ 已安装命令：zcf/git/git-cleanBranches.md 62✔ 已安装命令：zcf/git/git-worktree.md 63✔ 已安装命令：zcf/bmad-init.md 64✔ 工作流安装成功 65 66? 配置 MCP 服务？(Y/n) 67 68? 选择要安装的 MCP 服务（空格选择，回车确认）： 69❯ ◉ Context7 文档查询 - 查询最新库文档和代码示例 70◉ DeepWiki - 查询 GitHub 仓库文档和示例 71◉ Playwright 浏览器控制 - 直接浏览器自动化控制 72◉ Exa AI 搜索 - 使用 Exa AI 进行网络搜索 73◉ Serena 助手 - 类似 IDE 的语义化代码检索和编辑 74◯ 安装所有服务 75 76✔ MCP 服务已配置 77 78? 安装 CCometixLine 状态栏工具？(Y/n) 79 80✔ 设置完成！Claude Code 环境已准备就绪 81 82🎉 设置完成！使用 'claude' 命令启动。 83
命令行选项
命令快速参考
| 命令 | 别名 | 描述 |
|---|---|---|
zcf | - | 显示交互式菜单（v2.0 默认命令） |
zcf init | zcf i | 初始化 Claude Code 配置 |
zcf update | zcf u | 更新工作流相关的 md 文件并备份 |
zcf ccu | - | 运行 Claude Code 使用情况分析工具 - ccusage |
zcf ccr | - | 打开 CCR（Claude Code 路由器）管理菜单 |
zcf config-switch | zcf cs | Claude Code 和 Codex 的 API 提供商/配置切换（-T cc / -T cx） |
zcf uninstall | - | Claude Code 配置和工具的交互式卸载工具 |
zcf check-updates | - | 检查并更新 Claude Code、CCR 和 CCometixLine 版本 |
常用选项
bash1# 指定配置语言 2npx zcf --config-lang zh-CN 3npx zcf -c zh-CN # 使用短选项 4 5# 强制覆盖现有配置 6npx zcf --force 7npx zcf -f # 使用短选项 8 9# 更新工作流相关的 md 文件并备份（保留 API 和 MCP 配置） 10npx zcf u # 使用 update 命令 11npx zcf update # 完整命令 12 13# 显示帮助信息 14npx zcf --help 15npx zcf -h 16 17# 显示版本 18npx zcf --version 19npx zcf -v
使用示例
bash1# 显示交互式菜单（默认） 2npx zcf 3 4# 首次安装，完整初始化 5npx zcf i 6npx zcf init # 完整命令 7 8# 更新工作流相关的 md 文件并备份，保留 API 和 MCP 配置 9npx zcf u 10npx zcf update # 完整命令 11 12# 强制重新初始化，使用中文配置 13npx zcf i --config-lang zh-CN --force 14npx zcf i -c zh-CN -f # 使用短选项 15 16# 更新为英文提示（Token 消耗更低） 17npx zcf u --config-lang en 18npx zcf u -c en # 使用短选项 19 20# 运行 Claude Code 使用情况分析工具（由 ccusage 提供支持） 21npx zcf ccu # 每日使用情况（默认），或使用：monthly, session, blocks 22 23# Codex API 提供商切换（v3.0.0+ 新增） 24npx zcf config-switch # 交互式提供商选择 25npx zcf cs # 使用别名 26npx zcf cs provider-name # 直接切换到指定提供商 27npx zcf cs --list # 列出所有可用提供商
📁 项目结构
zcf/
├── README.md # 文档
├── package.json # npm 包配置
├── bin/
│ └── zcf.mjs # CLI 入口点
├── src/ # 源代码
│ ├── cli.ts # CLI 主逻辑
│ ├── commands/ # 命令实现
│ ├── utils/ # 工具函数
│ └── constants.ts # 常量定义
├── templates/ # 配置模板
│ ├── CLAUDE.md # 项目级配置（v2.0 新增）
│ ├── settings.json # 基础配置（包含隐私环境变量）
│ ├── en/ # 英文版本
│ │ ├── rules.md # 核心原则（原 CLAUDE.md）
│ │ ├── output-styles/ # AI 输出风格（v2.12+ 新增）
│ │ ├── mcp.md # MCP 服务指南（v2.0 新增）
│ │ ├── agents/ # AI 代理
│ │ └── commands/ # 命令定义
│ └── zh-CN/ # 中文版本
│ └── ...（相同结构）
└── dist/ # 构建输出
✨ 核心功能（v2.0 增强版）
🤖 专业代理
- 任务规划器：将复杂任务分解为可执行步骤
- UI/UX 设计师：提供专业界面设计指导
- AI 个性：支持多种预设个性和自定义（v2.0 新增）
- BMad 团队（新增）：完整的敏捷开发团队，包括：
- 产品负责人（PO）：需求收集和优先级排序
- 项目经理（PM）：计划和协调
- 系统架构师：技术设计和架构
- 开发人员：实现和编码
- QA 工程师：测试和质量保证
- Scrum Master（SM）：流程促进
- 业务分析师：需求分析
- UX 专家：用户体验设计
⚡ 命令系统
- 功能开发（
/feat）：结构化的新功能开发 - 工作流（
/workflow）：完整的六阶段开发工作流 - Git 命令：简化的 Git 操作
/git-commit：智能提交，自动暂存和生成提交信息/git-rollback：安全回滚到之前的提交并备份/git-cleanBranches：清理已合并分支，维护仓库整洁/git-worktree：管理 Git 工作树，集成 IDE 和内容迁移
- BMad 工作流（
/bmad-init）：为企业开发初始化 BMad 工作流- 支持绿地（新项目）和棕地（现有项目）
- 提供 PRD、架构文档和用户故事的全面模板
- 集成的质量门和检查清单系统
🔧 智能配置
- API 密钥管理（支持部分修改）
- 细粒度权限控制
- 多种 Claude 模型支持（可配置默认模型）
- 交互式菜单系统（v2.0 新增）
- AI 记忆管理（v2.0 新增）
🎯 开发工作流
六阶段工作流
- [模式：研究] - 理解需求
- [模式：构思] - 设计方案
- [模式：规划] - 创建详细计划
- [模式：执行] - 实施开发
- [模式：优化] - 提高质量
- [模式：评审] - 最终评估
🛠️ 开发
bash1# 克隆项目 2git clone https://github.com/UfoMiao/zcf.git 3cd zcf 4 5# 安装依赖（使用 pnpm） 6pnpm install 7 8# 构建项目 9pnpm build 10 11# 本地测试 12node bin/zcf.mjs
💡 最佳实践
- 任务分解：保持任务独立且可测试
- 代码质量：遵循 SOLID、KISS、DRY 和 YAGNI 原则
- 文档管理：计划将存储在项目根目录的
.claude/plan/目录中
🔧 故障排除
如果遇到问题：
- 重新运行
npx zcf重新配置 - 检查
~/.claude/目录中的配置文件 - 确保 Claude Code 正确安装
- 如果路径包含空格，ZCF 会自动处理引号包装
- 优先使用 ripgrep（
rg）进行文件搜索以获得更好性能
跨平台支持
Windows 平台
ZCF 完全支持 Windows 平台：
- 自动检测：在 Windows 系统上自动使用兼容的
cmd /c npx格式 - 配置修复：在更新期间自动修复现有不正确的配置
- 零配置：Windows 用户无需任何额外步骤，与 macOS/Linux 体验相同
如果在 Windows 上遇到 MCP 连接问题，运行 npx zcf 将自动修复配置格式。
WSL 支持（v2.12.12+ 新增）
ZCF 现在为 Windows Subsystem for Linux（WSL）提供全面支持：
- 智能检测：使用环境变量、系统文件和挂载点进行多层 WSL 环境检测
- 发行版识别：自动识别 WSL 发行版（Ubuntu、Debian 等）以优化配置
- 无缝安装：在 WSL 环境中提供原生 Linux 风格的安装体验
- 路径管理：智能处理 WSL 特定的配置路径和文件位置
如果在 WSL 中运行，ZCF 将自动检测环境并显示适当的安装消息。
Termux 支持（v2.1 新增）
ZCF 现在支持在 Android Termux 环境中运行：
- 自动适配：自动检测 Termux 环境并使用兼容配置
- 增强检测：智能识别可用命令，确保在受限环境中正常运行
- 完整功能：在 Termux 中享受与桌面系统相同的完整功能
安全功能（v2.3 新增）
危险操作确认机制
为保护用户数据安全，以下操作需要明确确认：
- 文件系统：删除文件/目录、批量修改、移动系统文件
- 代码提交：
git commit、git push、git reset --hard - 系统配置：修改环境变量、系统设置、权限
- 数据操作：数据库删除、模式更改、批量更新
- 网络请求：发送敏感数据、调用生产 API
- 包管理：全局安装/卸载、更新核心依赖
🙏 致谢
本项目受以下开源项目启发并整合了其内容：
感谢这些社区贡献者的分享！