项目详情
深入了解 zcf 的功能与特性
✨ 快速链接: Codex 支持 | BMad 工作流 | Spec 工作流 | 开放网络搜索 | CCR 路由器 | CCometixLine | AI 输出样式 | 多配置管理
零配置、一键设置 Claude Code 和 Codex，支持双语、智能代理系统和个性化 AI 助手
🚀 快速开始
🎯 推荐：使用交互式菜单 (v2.0 新增)
bash
npx 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
bash
npx zcf i # 直接执行完整初始化：安装 Claude Code + 导入工作流 + 配置 API + 设置 MCP 服务
# 或
npx zcf → 选择 1 # 通过菜单执行完整初始化
🔄 已安装 Claude Code
bash
npx zcf u # 仅更新工作流：快速添加 AI 工作流和命令系统
# 或
npx zcf → 选择 2 # 通过菜单执行工作流更新
注意:
- 从 v2.0 开始，
zcf默认打开交互式菜单，提供可视化操作界面- 您可以通过菜单选择操作，或直接使用命令快速执行
zcf i= 完整初始化，zcf u= 仅更新工作流
🌐 语言支持
ZCF 支持双语操作，所有命令自动切换语言：
bash
# 使用中文进行所有操作
npx zcf --lang zh-CN # 中文交互式菜单
npx zcf init --lang zh-CN # 中文界面初始化
npx zcf ccr --all-lang zh-CN # 中文配置 CCR
# 语言参数优先级 (从高到低)：
# --all-lang > --lang > 保存的用户偏好 > 交互式提示
语言参数：
--lang, -l: ZCF 界面语言 (适用于所有命令)--all-lang, -g: 一次性设置所有语言参数 (最方便)--config-lang, -c: 模板文件语言 (仅限 init/update 命令)--ai-output-lang, -a: AI 助手输出语言 (仅限 init 命令)
🤖 非交互模式
适用于 CI/CD 和自动化设置，使用 --skip-prompt 配合参数：
bash
# 简写版本
npx zcf i -s -g zh-CN -t api_key -k "sk-xxx" -u "https://xxx.xxx"
# 完整版本
npx zcf i --skip-prompt --all-lang zh-CN --api-type api_key --api-key "sk-xxx" --api-url "https://xxx.xxx"
# 简写版本 (带自定义模型)
npx zcf i -s -t api_key -k "sk-xxx" -M "claude-sonnet-4-5" -F "claude-haiku-4-5"
# 完整版本 (带自定义模型)
npx zcf i --skip-prompt \
--api-type api_key \
--api-key "sk-xxx" \
--api-url "https://xxx.xxx" \
--api-model "claude-sonnet-4-5" \
--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 模式：
bash
npx zcf → 选择 S # 在 Claude Code 和 Codex 之间切换
或直接访问 Codex 功能：
bash
# 完整 Codex 初始化
npx zcf → 选择 1 (切换到 Codex 模式后)
# 单独 Codex 配置
npx zcf → 选择 3 # 配置 Codex API 提供商
npx 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 提供可选仪表板用于工作流可视化。用户可以手动启动仪表板：
bash
npx -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 功能：
bash
npx zcf ccr # 打开 CCR 管理菜单
# 或
npx 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+)：
bash
npx zcf check-updates # 检查并更新 Claude Code、CCR 和 CCometixLine 到最新版本
# 或
npx 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）
明确选择工具类型：
bash
# -T 接受：claude-code|codex 或短别名 cc|cx
npx zcf cs --list -T cc # 列出 Claude Code 配置文件
npx zcf cs --list -T cx # 列出 Codex 提供商
npx zcf cs -l -T cc # --list 的短选项
npx zcf cs -l -T cx # --list 的短选项
Claude Code 用法：
bash
# 快速切换
npx zcf cs official -T cc # 切换到官方登录
npx zcf cs ccr -T cc # 切换到 CCR 代理
npx zcf cs my-profile -T cc
Codex 用法：
bash
# 列出并切换提供商
npx zcf cs --list -T cx
npx zcf cs my-provider -T cx
# 切换到官方登录（交互式选择）
npx zcf config-switch -T cx
注意：
- 环境变量映射（Claude Code）：API 密钥 →
ANTHROPIC_API_KEY，认证令牌 →ANTHROPIC_AUTH_TOKEN，基础 URL →ANTHROPIC_BASE_URL。 - 当前激活的代码工具类型存储在 ZCF 配置中；仅当目标工具与当前工具不同时使用
-T cc/cx。
📖 使用说明
交互式菜单（v2.0）
bash
$ npx zcf
ZCF - 零配置代码流
? 选择 ZCF 显示语言 / Select ZCF display language:
❯ 简体中文
English
选择功能：
-------- Claude Code --------
1. 完整初始化 - 安装 Claude Code + 导入工作流 + 配置 API 或 CCR 代理 + 配置 MCP 服务
2. 导入工作流 - 仅导入/更新工作流相关文件
3. 配置 API - 配置 API URL 和认证（支持 CCR 代理）
4. 配置 MCP - 配置 MCP 服务（包含 Windows 修复）
5. 配置默认模型 - 设置默认模型（opus/sonnet/sonnet 1m/自定义）
6. 配置 Claude 全局记忆 - 配置 AI 输出语言和输出风格
7. 导入推荐环境变量和权限 - 导入隐私保护环境变量和系统权限
--------- 其他工具 ----------
R. CCR - Claude Code 路由器管理
U. ccusage - Claude Code 使用情况分析
L. CCometixLine - 高性能状态栏工具，集成 Git 和实时使用情况跟踪
------------ ZCF ------------
0. 选择显示语言 / 更改显示语言 - 更改 ZCF 界面语言
-. 卸载 - 从系统中移除 Claude Code 配置和工具
+. 检查更新 - 检查并更新 Claude Code、CCR 和 CCometixLine 版本
Q. 退出
输入您的选择：_
完整初始化流程（选择 1 或使用 zcf i）
bash
? 选择 Claude Code 配置语言：
❯ English (en) - 英语（推荐，Token 消耗更低）
简体中文 (zh-CN) - 中文（便于中文用户自定义）
日本語 (ja) - 日语（面向日本用户）
? 选择 AI 输出语言：
AI 将使用此语言回复您
❯ English
简体中文
日本語
自定义
（支持法语、德语等更多语言）
? 未找到 Claude Code。是否自动安装？(Y/n)
✔ Claude Code 安装成功
? 检测到现有配置。如何处理？
❯ 备份并覆盖 - 将现有配置备份到 ~/.claude/backup/
仅更新文档 - 仅更新工作流和文档，保留现有 API 配置
合并配置 - 与现有配置合并，保留用户自定义设置
跳过 - 跳过配置更新
? 选择 API 认证方式
❯ 使用官方登录
使用官方认证系统，无需配置 API
使用认证令牌（OAuth 认证）
适用于通过 OAuth 或浏览器登录获取的令牌
使用 API 密钥（密钥认证）
适用于从 Anthropic 控制台获取的 API 密钥
配置 CCR 代理（Claude Code 路由器）
通过代理路由使用多个 AI 模型以降低成本并探索可能性
跳过（稍后手动配置）
? 输入 API URL：https://api.anthropic.com
? 输入认证令牌或 API 密钥：xxx
? 选择要安装的输出风格：
❯ 工程师专业版 - 遵循 SOLID、KISS、DRY、YAGNI 原则的专业软件工程师
猫娘工程师 - 专业的猫娘工程师 UFO Nya，结合严谨工程学与可爱猫娘特质
老王暴躁技术风 - 老王暴躁技术风格，绝不容忍代码错误和非规范代码
大小姐工程师 - 傲娇金发大小姐程序员 Halley-chan，结合严谨工程卓越与傲娇大小姐特质
? 选择全局默认输出风格：
❯ 工程师专业版
? 选择要安装的工作流（空格选择，回车确认）：
❯ ◉ 常用工具（init-project + init-architect + get-current-datetime）- 必要的项目初始化和实用命令
◉ 六步工作流（workflow）- 完整的六阶段开发流程
◉ 功能规划与 UX 设计（feat + planner + ui-ux-designer）- 结构化功能开发
◉ Git 命令（commit + rollback + cleanBranches + worktree）- 简化的 Git 操作
◉ BMAD 方法扩展安装器 - 企业级敏捷开发工作流
✔ 正在安装工作流...
✔ 已安装命令：zcf/workflow.md
✔ 已安装命令：zcf/feat.md
✔ 已安装代理：zcf/plan/planner.md
✔ 已安装代理：zcf/plan/ui-ux-designer.md
✔ 已安装命令：zcf/git/git-commit.md
✔ 已安装命令：zcf/git/git-rollback.md
✔ 已安装命令：zcf/git/git-cleanBranches.md
✔ 已安装命令：zcf/git/git-worktree.md
✔ 已安装命令：zcf/bmad-init.md
✔ 工作流安装成功
? 配置 MCP 服务？(Y/n)
? 选择要安装的 MCP 服务（空格选择，回车确认）：
❯ ◉ Context7 文档查询 - 查询最新库文档和代码示例
◉ DeepWiki - 查询 GitHub 仓库文档和示例
◉ Playwright 浏览器控制 - 直接浏览器自动化控制
◉ Exa AI 搜索 - 使用 Exa AI 进行网络搜索
◉ Serena 助手 - 类似 IDE 的语义化代码检索和编辑
◯ 安装所有服务
✔ MCP 服务已配置
? 安装 CCometixLine 状态栏工具？(Y/n)
✔ 设置完成！Claude Code 环境已准备就绪
🎉 设置完成！使用 'claude' 命令启动。
命令行选项
命令快速参考
| 命令 | 别名 | 描述 |
|---|---|---|
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 版本 |
常用选项
bash
# 指定配置语言
npx zcf --config-lang zh-CN
npx zcf -c zh-CN # 使用短选项
# 强制覆盖现有配置
npx zcf --force
npx zcf -f # 使用短选项
# 更新工作流相关的 md 文件并备份（保留 API 和 MCP 配置）
npx zcf u # 使用 update 命令
npx zcf update # 完整命令
# 显示帮助信息
npx zcf --help
npx zcf -h
# 显示版本
npx zcf --version
npx zcf -v
使用示例
bash
# 显示交互式菜单（默认）
npx zcf
# 首次安装，完整初始化
npx zcf i
npx zcf init # 完整命令
# 更新工作流相关的 md 文件并备份，保留 API 和 MCP 配置
npx zcf u
npx zcf update # 完整命令
# 强制重新初始化，使用中文配置
npx zcf i --config-lang zh-CN --force
npx zcf i -c zh-CN -f # 使用短选项
# 更新为英文提示（Token 消耗更低）
npx zcf u --config-lang en
npx zcf u -c en # 使用短选项
# 运行 Claude Code 使用情况分析工具（由 ccusage 提供支持）
npx zcf ccu # 每日使用情况（默认），或使用：monthly, session, blocks
# Codex API 提供商切换（v3.0.0+ 新增）
npx zcf config-switch # 交互式提供商选择
npx zcf cs # 使用别名
npx zcf cs provider-name # 直接切换到指定提供商
npx zcf cs --list # 列出所有可用提供商
📁 项目结构
python
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 新增）
🎯 开发工作流
六阶段工作流
- [模式：研究] - 理解需求
- [模式：构思] - 设计方案
- [模式：规划] - 创建详细计划
- [模式：执行] - 实施开发
- [模式：优化] - 提高质量
- [模式：评审] - 最终评估
🛠️ 开发
bash
# 克隆项目
git clone https://github.com/UfoMiao/zcf.git
cd zcf
# 安装依赖（使用 pnpm）
pnpm install
# 构建项目
pnpm build
# 本地测试
node 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
- 包管理：全局安装/卸载、更新核心依赖
🙏 致谢
本项目受以下开源项目启发并整合了其内容：
感谢这些社区贡献者的分享！