Claude Code（九）:Claude Code配置工具ZCF

一、简介

ZCF（Zero-Config Code Flow）是一个面向专业开发者的 CLI 工具，目标是在几分钟内完成 Claude Code 与 Codex 的端到端环境初始化。通过 npx zcf 可以一站式完成配置目录创建、API/代理接入、MCP 服务接入、工作流导入、输出风格与记忆配置，以及常用工具安装。

1.1 为什么选择 ZCF

零配置体验：自动检测操作系统、语言偏好与安装状态，必要时触发增量配置，避免重复劳动。
多工具统一：同时支持 Claude Code 与 Codex，两套环境共享一套 CLI，随时切换目标平台。
结构化工作流：预置六阶段结构化工作流、Feat 规划流、BMad 敏捷流等，内置代理与指令模板。
丰富的 MCP 集成：默认提供 Context7、Open Web Search、Spec Workflow、DeepWiki、Playwright、Serena 等服务。
可视化状态与运维：包含 CCR（Claude Code Router）配置助手以及 CCometixLine 状态栏安装与升级能力。
可扩展配置体系：支持多 API 配置并行、输出风格切换、环境权限导入、模板与语言分离管理。

1.2 使用 ZCF 你将获得什么

安全的隐私与权限配置：环境变量、权限模板与备份策略自动落地，确保极简但安全的运行环境。
API 与代理管理：支持官方登录、API Key、CCR 代理三种模式，内置 302.AI、GLM、MiniMax、Kimi 等预设。
全局输出风格与语言体系：命令行即可设置 AI 输出语言、项目级/全局输出风格与 Codex 记忆指令。
工作流与指令模板集：自动导入 /zcf:workflow、/zcf:feat、/git-commit 等命令以及对应的代理配置。
MCP 服务基座：一键启用主流 MCP Server，并根据是否需要 API Key 智能提示环境变量要求。
辅助工具链：CCometixLine 状态栏自动安装、CCR 管理菜单、Codex CLI 安装/升级、使用数据统计。

二、安装使用

需要Node.js版本不低于22。npm需要支持npx命令。npx zcf即可直接启动ZCF。

命令概览

ZCF CLI 基于 cac 实现，所有命令均可通过 npx zcf <command> 调用。常用命令如下：

命令	说明
`zcf`	打开交互式菜单，聚合所有功能
`zcf init` / `zcf i`	完整初始化，覆盖 Claude Code 或 Codex
`zcf update` / `zcf u`	更新工作流与模板，可选择语言与输出样式
`zcf ccr`	管理 Claude Code Router 代理
`zcf ccu`	Claude Code 使用分析与统计
`zcf uninstall`	卸载配置并可选择保留备份
`zcf config-switch` / `zcf cs`	在多套配置之间切换
`zcf check-updates` / `zcf check`	检查并升级工具链

每个命令均支持 --help 查看详细参数。

2.1 主菜单

执行 npx zcf 会进入交互式菜单系统。菜单是 ZCF 的核心交互界面，提供可视化的操作选项，无需记忆复杂的命令参数。

菜单特点

🎯 动态显示：根据当前代码工具（Claude Code 或 Codex）动态调整菜单项
⌨️ 快捷键操作：输入单个字符即可执行操作，无需记忆命令
🔄 智能切换：可以在 Claude Code 和 Codex 之间无缝切换
📋 功能聚合：所有常用功能都集中在菜单中，方便快速访问

Claude Code 模式菜单

选项	功能	对应命令	说明
`1`	完整初始化	`zcf init`	完整初始化 Claude Code 环境
`2`	导入/更新工作流	`zcf update`	更新工作流模板和提示词
`3`	配置 API 或 CCR	-	配置 API 密钥、提供商或 CCR 代理
`4`	配置 MCP 服务	-	安装和配置 MCP 服务
`5`	配置默认模型	-	设置默认使用的 Claude 模型
`6`	配置 AI 记忆与输出风格	-	设置 AI 输出语言和全局输出风格
`7`	导入推荐环境变量与权限	-	配置环境变量和文件系统权限
`R`	CCR 管理菜单	`zcf ccr`	Claude Code Router 管理
`U`	Claude Code 使用分析	`zcf ccu`	查看 API 使用统计
`L`	CCometixLine 管理	-	状态栏工具管理
`0`	切换脚本语言	-	切换 CLI 界面语言（zh-CN/en）
`S`	切换代码工具	-	在 Claude Code ↔︎ Codex 之间切换
`-`	卸载当前工具配置	`zcf uninstall`	卸载 Claude Code 配置
`+`	检查更新	`zcf check-updates`	检查工具版本并更新
`Q`	退出	-	退出菜单

Codex 模式菜单

Codex 模式下的菜单会调整为 Codex 对应的操作：

1 - Codex 完整初始化
2 - 更新 Codex 工作流和模板
3 - 配置 Codex API 提供商或 MCP
4 - 配置 Codex MCP 服务
S - 切换回 Claude Code
其他选项保持相同

2.1.1 菜单功能详解

1.完整初始化（选项 1）

等同于执行 npx zcf init，会引导您完成：

选择代码工具类型
配置 API（官方登录/API Key/CCR 代理）
选择 MCP 服务
选择工作流
选择输出风格
配置语言选项

2.导入/更新工作流（选项 2）

等同于执行 npx zcf update，会：

更新工作流模板
更新提示词内容
检查工具版本
选择模板语言

3.配置 API 或 CCR（选项 3）

提供以下配置选项：

配置 API Key（自定义端点）
使用 API 提供商预设（302.AI、GLM 等）
配置 CCR 代理
切换回官方登录

4.配置 MCP 服务（选项 4）

管理 MCP 服务：

安装新的 MCP 服务
移除不需要的服务
更新服务配置
检查服务状态

5.配置默认模型（选项 5）

设置默认使用的 Claude 模型：

自动选择（Claude Code 自动选择最佳模型）
Opus（高 token 消耗，谨慎使用）
Sonnet 1M（大上下文窗口）
自定义（指定主模型和快速模型）

6.配置 AI 记忆与输出风格（选项 6）

管理 AI 行为：

设置 AI 输出语言
切换全局输出风格
编辑输出风格内容
管理项目记忆

7.导入推荐环境变量与权限（选项 7）

配置开发环境：

导入环境变量模板
配置文件系统权限
设置推荐的工作目录权限

R.CCR 管理菜单（选项 R）

进入 CCR 专用管理界面：

初始化/安装 CCR
启动/停止/重启 CCR 服务
打开 CCR Web UI
查看 CCR 状态
配置路由规则

U.Claude Code 使用分析（选项 U）

查看 API 使用统计：

Token 使用量
成本统计
使用趋势
导出 JSON 数据

L.CCometixLine 管理（选项 L）

管理状态栏工具：

安装/升级 CCometixLine
卸载 CCometixLine
配置状态栏格式
查看版本信息

+.检查更新（选项 +）

检查并更新工具：

检查 Claude Code 版本
检查 CCR 版本
检查 CCometixLine 版本
自动更新可用版本

-.卸载当前工具配置（选项 -）

安全卸载配置：

完整卸载所有配置
自定义卸载特定组件
保留备份选项

2.2 CCR 代理管理

zcf ccr 提供 Claude Code Router（CCR）的完整管理菜单，包括安装、配置、服务控制和 Web UI 访问等功能。

# 打开 CCR 管理菜单
npx zcf ccr

# 或通过主菜单访问
npx zcf
# 然后选择 R. CCR 管理

1. 初始化 CCR

功能：首次设置 CCR 或重新配置 CCR

流程：

自动检测是否已安装 CCR CLI 工具
如果未安装，自动安装 @musistudio/claude-code-router
引导配置向导：
- 选择提供商预设（302.AI、GLM、MiniMax、Kimi 等）
- 配置 API 密钥（如需要）
- 选择默认模型
- 创建配置文件 ~/.claude-code-router/config.json
自动配置 Claude Code 使用 CCR 代理
备份现有配置（如果存在）

使用场景：

首次使用 CCR
需要更换提供商或重新配置
配置丢失需要重新设置

示例：

1
2
3

npx zcf ccr
# 选择 1
# 按提示完成配置

2. 启动 UI

功能：启动 CCR Web 管理界面

访问地址：http://localhost:3456/ui（默认端口）

Web UI 功能：

📊 实时使用统计和成本分析
⚙️ 路由规则配置
🔧 模型管理（添加、编辑、删除）
📈 详细的使用量统计
🔄 服务控制（启动、停止、重启）

前置条件：

必须先完成 CCR 初始化（选项 1）
配置文件 ~/.claude-code-router/config.json 必须存在

API 密钥：

启动 UI 时会显示 CCR API 密钥（默认：sk-zcf-x-ccr）
使用此密钥登录 Web UI

示例：

1
2
3

npx zcf ccr
# 选择 2
# 等待服务启动后，访问 http://localhost:3456/ui

3. 检查状态

功能：查看 CCR 服务当前运行状态

显示信息：

服务是否运行
运行端口
配置的提供商数量
路由规则摘要

使用场景：

验证服务是否正常启动
排查连接问题
查看当前配置状态

示例：

1 2	`npx zcf ccr # 选择 3`

4. 重启服务

功能：重启 CCR 服务，重新加载配置

使用场景：

修改配置文件后需要重新加载
服务异常需要重启
端口冲突后需要重启

示例：

1 2	`npx zcf ccr # 选择 4`

5. 启动服务

功能：启动 CCR 服务

使用场景：

服务停止后需要重新启动
系统重启后启动服务

示例：

1 2	`npx zcf ccr # 选择 5`

6. 停止服务

功能：停止当前运行的 CCR 服务

使用场景：

需要暂停 CCR 代理
调试时需要停止服务
更换配置前先停止服务

示例：

1 2	`npx zcf ccr # 选择 6`

路由规则配置

CCR 支持灵活的路由规则配置，可以通过 Web UI 或配置文件设置。配置文件位于 ~/.claude-code-router/config.json，使用 JSON 格式。

完整配置示例

{
  "LOG": true,
  "HOST": "127.0.0.1",
  "PORT": 3456,
  "APIKEY": "sk-zcf-x-ccr",
  "API_TIMEOUT_MS": "600000",
  "PROXY_URL": "",
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-xxx",
      "models": [
        "google/gemini-2.5-pro-preview",
        "anthropic/claude-sonnet-4",
        "anthropic/claude-3.5-sonnet"
      ],
      "transformer": {
        "use": ["openrouter"]
      }
    },
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/v1/chat/completions",
      "api_key": "sk-xxx",
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "transformer": {
        "use": ["deepseek"],
        "deepseek-chat": {
          "use": ["tooluse"]
        }
      }
    },
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen2.5-coder:latest"],
      "transformer": {
        "use": ["ollama"]
      }
    },
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": "sk-xxx",
      "models": ["gemini-2.5-flash", "gemini-2.5-pro"],
      "transformer": {
        "use": ["gemini"]
      }
    }
  ],
  "Router": {
    "default": "openrouter,google/gemini-2.5-pro-preview",
    "background": "deepseek,deepseek-chat",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,anthropic/claude-sonnet-4",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

2.2.1 配置字段说明

基础配置

字段	类型	说明	默认值
`LOG`	boolean	是否启用日志	`true`
`HOST`	string	服务监听地址	`127.0.0.1`
`PORT`	number	服务端口	`3456`
`APIKEY`	string	CCR API 密钥	`sk-zcf-x-ccr`
`API_TIMEOUT_MS`	string	API 超时时间（毫秒）	`600000`
`PROXY_URL`	string	代理 URL（可选）	`""`

Providers 配置

Providers 是一个数组，每个 Provider 包含：

字段	类型	说明
`name`	string	提供商名称（用于路由规则）
`api_base_url`	string	API 基础 URL
`api_key`	string	API 密钥（免费模型可使用 `sk-free`）
`models`	string[]	该提供商支持的模型列表
`transformer`	object	可选的请求转换器（用于 API 兼容性）

Router 配置

Router 定义了不同场景下的模型路由规则，格式为：${providerName},${modelName}

字段	类型	说明
`default`	string	默认路由（格式：`provider,model`）
`background`	string	后台任务路由（可选）
`think`	string	思考任务路由（可选）
`longContext`	string	长上下文任务路由（可选）
`longContextThreshold`	number	长上下文的 token 阈值（可选）
`webSearch`	string	网页搜索任务路由（可选）

2.2.2 提供商预设

ZCF 支持多个 CCR 提供商预设，简化配置流程：

1
2
3

npx zcf ccr
# 选择 1. 初始化 CCR
# 选择提供商预设

支持的预设包括：

302.AI：企业级 AI 服务
GLM：智谱 AI
MiniMax：MiniMax AI 服务
自定义：配置自定义提供商

2.3 使用分析 ccu

zcf ccu（Claude Code Usage）用于查看和分析 Claude Code 的使用统计信息，帮助您了解 AI 助手的使用情况和成本。

2.3.1 命令格式

# 基本使用（显示默认统计）
npx zcf ccu

# 指定统计周期
npx zcf ccu --period daily
npx zcf ccu --period weekly
npx zcf ccu --period monthly

# JSON 格式输出（用于脚本处理）
npx zcf ccu --json

# CSV 格式输出（用于 Excel 分析）
npx zcf ccu --csv

# 通过主菜单访问
npx zcf
# 然后选择 U. 使用分析

2.3.2 参数说明

参数	说明	可选值	默认值
`--period`	统计周期	`daily`, `weekly`, `monthly`	`daily`
`--json`	JSON 格式输出	无	否
`--csv`	CSV 格式输出	无	否

2.3.3 功能详解

ccusage 是一个强大的使用分析工具，主要功能包括：

📊 多维度报告：支持日度、周度、月度 token 使用量和成本报告
📅 灵活周期：支持 daily, weekly, monthly 等多种统计周期
📈 实时监控：实时仪表板显示活动会话进度、token 消耗率和成本预测
💬 会话分析：按对话会话分组的使用情况分析
🤖 模型细分：查看每个模型（Opus, Sonnet 等）的具体使用成本
💰 成本跟踪：显示每天/每月的美元成本
🔄 缓存统计：分别跟踪缓存创建和缓存读取的 token
📱 智能显示：根据终端宽度自动调整表格布局（支持紧凑模式）
🔌 多格式导出：支持 JSON 和 CSV 格式导出，方便二次分析
🚀 状态栏集成：支持与 CCometixLine 状态栏集成显示摘要

2.3.4 统计数据来源

CCusage 工具会读取 Claude Code 的官方使用数据库 usage.db，包含：

调用次数：AI 请求的总次数
使用时长：累计的 AI 使用时间
时间范围：按指定周期统计的数据
Token 详情：输入/输出/缓存 Token 数量

2.3.5 统计周期示例

日统计（`daily`）

显示每天的使用情况，适合日常监控。

📊 Claude Code Usage Statistics
Period: Daily

Date       | Requests | Duration
-----------|----------|----------
2025-01-15 | 45       | 2h 30m
2025-01-14 | 38       | 2h 15m

周统计（`weekly`）

显示每周的使用情况，适合周期性分析。

📊 Claude Code Usage Statistics
Period: Weekly

Week       | Requests | Duration
-----------|----------|----------
Week 3     | 315      | 18h 20m
Week 2     | 298      | 17h 45m

月统计（`monthly`）

显示每月的使用情况，适合长期趋势分析和成本预算。

📊 Claude Code Usage Statistics
Period: Monthly

Month      | Requests | Duration
-----------|----------|----------
2025-01    | 1250     | 72h 15m
2024-12    | 1180     | 68h 30m

2.3.6 输出格式

默认格式（表格）

适合终端查看，格式清晰易读。会自动适配终端宽度。

JSON 格式

适合脚本处理和自动化：

1	`npx zcf ccu --json --period weekly`

输出示例：

{
  "period": "weekly",
  "data": [
    {
      "date": "2025-01-15",
      "requests": 45,
      "duration": "2h 30m"
    }
  ],
  "total": {
    "requests": 315,
    "duration": "18h 20m"
  }
}

CSV 格式

适合导入 Excel 或其他分析工具：

1	`npx zcf ccu --csv --period monthly > usage.csv`

输出示例：

1
2
3

Date,Requests,Duration
2025-01-15,45,2h 30m
2025-01-14,38,2h 15m

2.3.7 使用场景

1. 日常使用监控

快速查看当天的使用情况：

1	`npx zcf ccu --period daily`

2. 团队使用统计

定期统计团队成员的使用量：

1 2	`# 每周生成统计报告 npx zcf ccu --period weekly --json > weekly-usage.json`

3. 成本分析

结合 API 价格进行成本估算：

1
2
3

# 生成月度使用报告
npx zcf ccu --period monthly --csv > monthly-usage.csv
# 然后在 Excel 中结合 API 价格计算成本

4. 自动化监控

搭配 cron 定时收集使用数据：

1 2	`# 添加到 crontab（每天执行） 0 23 * * * cd /path/to/project && npx zcf ccu --json --period daily >> usage.log`

2.3.8 与 CCometixLine 集成

CCometixLine 状态栏同样可以显示使用统计摘要：

安装 CCometixLine：npx zcf → 选择相应选项
在状态栏中查看实时使用情况
点击状态栏可查看详细统计

2.4 卸载与清理

zcf uninstall 提供安全的卸载流程，支持选择性卸载、完整卸载和冲突解决。适合需要重置环境、迁移设备或清理配置的场景。

2.4.1 完整卸载

# 交互式完整卸载
npx zcf uninstall
# 然后选择 "完整卸载"

# 非交互式完整卸载
npx zcf uninstall --mode complete

# 指定语言
npx zcf uninstall --mode complete --lang zh-CN

会删除的内容：

✅ Claude Code 配置（~/.claude/）
✅ Codex 配置（~/.codex/）
✅ CCR 配置（~/.claude-code-router/）
✅ CCometixLine 配置（~/.cometix/）
✅ ZCF 全局配置（~/.ufomiao/zcf/）
✅ 所有备份文件

不会删除的内容：

❌ Claude Code CLI 本身（需要通过其他方式卸载）
❌ Codex CLI 本身（需要通过其他方式卸载）
❌ 系统级工具和依赖

2.4.2 自定义卸载

选择性卸载特定组件：

# 交互式自定义卸载
npx zcf uninstall
# 然后选择 "自定义卸载"，再选择要卸载的组件

# 非交互式自定义卸载（逗号分隔）
npx zcf uninstall --mode custom --items "ccr,backups,cometix"

# 使用数组格式（在代码中）
npx zcf uninstall --mode custom --items '["ccr","backups"]'

可以选择性地卸载以下组件：

组件	说明	配置位置
`claude-code`	Claude Code 配置	`~/.claude/`
`codex`	Codex 配置	`~/.codex/`
`ccr`	Claude Code Router 配置	`~/.claude-code-router/`
`cometix`	CCometixLine 配置	`~/.cometix/`
`backups`	所有备份文件	`~/.claude/backup/`, `~/.codex/backup/` 等
`zcf-config`	ZCF 全局配置	`~/.ufomiao/zcf/`

# 仅卸载 CCR
npx zcf uninstall --mode custom --items ccr

# 卸载多个组件
npx zcf uninstall --mode custom --items "ccr,cometix,backups"

# 卸载所有备份（清理空间）
npx zcf uninstall --mode custom --items backups

2.4.3 常用参数

参数	说明	可选值	默认值
`--mode, -m`	卸载模式	`complete`, `custom`, `interactive`	`interactive`
`--items, -i`	要卸载的组件（自定义模式）	逗号分隔的组件名称或 JSON 数组	-
`--lang, -l`	界面语言	`zh-CN`, `en`	`en`

2.5 配置管理

ZCF 的配置分布在以下目录：

目录	说明	主要文件
`~/.claude/`	Claude Code 主配置目录	`settings.json`, `CLAUDE.md`, `prompts/`, `workflows/`
`~/.codex/`	Codex 主配置目录	`config.toml`, `auth.json`, `prompts/`, `AGENTS.md`
`~/.ufomiao/zcf/`	ZCF 全局配置目录	`config.toml`
`~/.claude-code-router/`	CCR 配置目录	`config.json`
`~/.claude/backup/`	Claude Code 备份目录	时间戳备份文件
`~/.codex/backup/`	Codex 备份目录	时间戳备份文件

Claude Code 配置

~/.claude/
├── settings.json          # 主配置文件（API、MCP、权限等）
├── CLAUDE.md              # 项目记忆和系统提示
├── prompts/               # 提示词目录
│   ├── output-style/      # 输出风格模板
│   └── memory/            # 记忆模板
└── workflows/             # 工作流目录
    ├── zcf-workflow/      # 六阶段工作流
    ├── feat/              # 功能开发工作流
    ├── git/               # Git 工作流
    └── bmad/              # BMad 工作流

Codex 配置

~/.codex/
├── config.toml            # 主配置文件（TOML 格式）
├── auth.json              # API 密钥配置（加密存储）
├── AGENTS.md              # 系统提示和代理配置
├── prompts/               # 提示词目录
│   └── workflow/          # 工作流提示词
└── system-prompt/         # 系统提示模板

ZCF 全局配置

~/.ufomiao/zcf/
├── config.toml            # ZCF 全局配置（TOML 格式）
│   ├── preferredLang      # CLI 语言偏好
│   ├── templateLang       # 模板语言偏好
│   ├── aiOutputLang       # AI 输出语言偏好
│   └── codeToolType       # 当前活动工具类型
└── backup/                # ZCF 配置备份

2.5.1 API 模型配置

四模型架构

ZCF 采用四模型架构,提供细粒度的 AI 模型选择控制:

模型类型	环境变量	默认值	用途
主模型	`ANTHROPIC_MODEL`	`claude-sonnet-4-5-20250929`	通用任务的默认模型
Haiku 模型	`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`claude-haiku-4-5-20250910`	快速、经济的简单任务模型
Sonnet 模型	`ANTHROPIC_DEFAULT_SONNET_MODEL`	`claude-sonnet-4-5-20250929`	适用于大多数工作流的平衡模型
Opus 模型	`ANTHROPIC_DEFAULT_OPUS_MODEL`	`claude-opus-4-5-20251101`	复杂任务的最强模型

模型配置参数

配置 API 设置时,您可以单独指定每个模型:

# 配置全部四个模型
npx zcf i -s \
  --api-key "sk-xxx" \
  --api-model "claude-sonnet-4-5" \
  --api-haiku-model "claude-haiku-4-5" \
  --api-sonnet-model "claude-sonnet-4-5" \
  --api-opus-model "claude-opus-4-5"

多配置文件的模型配置

使用多个 API 配置文件时,每个配置文件可以有自己的模型配置:

{
  "name": "production",
  "type": "api_key",
  "key": "sk-prod-xxx",
  "primaryModel": "claude-sonnet-4-5",
  "defaultHaikuModel": "claude-haiku-4-5",
  "defaultSonnetModel": "claude-sonnet-4-5",
  "defaultOpusModel": "claude-opus-4-5"
}

环境变量映射

配置系统将配置文件中的模型设置映射到环境变量:

primaryModel → ANTHROPIC_MODEL
defaultHaikuModel → ANTHROPIC_DEFAULT_HAIKU_MODEL
defaultSonnetModel → ANTHROPIC_DEFAULT_SONNET_MODEL
defaultOpusModel → ANTHROPIC_DEFAULT_OPUS_MODEL

{
  "primaryModel": "claude-sonnet-4-5",
  "defaultHaikuModel": "claude-haiku-4-5",
  "defaultSonnetModel": "claude-sonnet-4-5",
  "defaultOpusModel": "claude-opus-4-5"
}

模型选择最佳实践

Haiku: 用于简单任务,如格式化、基本转换、快速响应
Sonnet: 大多数开发工作流和常规编码任务的默认选择
Opus: 保留用于复杂推理、架构决策和关键代码生成
主模型: 作为未请求特定模型时的后备选项

2.5.2 AI 输出语言指令

配置机制

applyAiLanguageDirective 函数会根据 --ai-output-lang 参数将对应的语言指令写入系统提示文件。

zh-CN：中文输出指令
en：英文输出指令
custom：自定义语言指令

使用 custom 选项可以输入自定义语言指令：

1 2	`npx zcf init --ai-output-lang custom # 输入：使用日语回复，保持专业和礼貌的语调`

自定义指令会写入：

Claude Code：~/.claude/CLAUDE.md
Codex：~/.codex/AGENTS.md

语言指令的配置位置：

Claude Code：CLAUDE.md 文件顶部
Codex：AGENTS.md 文件顶部

2.5.3 模板语言选择

resolveTemplateLanguage 函数会综合以下因素确定模板语言：

命令行参数：--config-lang 或 --all-lang
配置文件：~/.ufomiao/zcf/config.toml 中的 templateLang
交互输入：如果没有指定，会提示用户选择
系统默认：最后回退到 en

模板语言与 AI 输出语言相互独立，可以灵活组合：

# 中文模板 + 英文输出（适合需要英文代码注释）
npx zcf init --config-lang zh-CN --ai-output-lang en

# 英文模板 + 中文输出（适合国际化团队）
npx zcf init --config-lang en --ai-output-lang zh-CN

模板语言影响：

工作流模板的语言版本
提示词和指令的语言
系统提示模板的语言
输出风格模板的语言

2.6 配置切换

zcf config-switch 用于在多套 API 配置之间快速切换，适合在不同项目使用不同 API 提供商的用户。

别名：可以使用 zcf cs 这一简写，所有示例都可改写为 npx zcf cs --list 等形式。

# 交互式切换（推荐）
npx zcf cs

# 列出所有可用配置
npx zcf cs --list

# 直接切换到指定配置（Claude Code）
npx zcf cs provider1

# 指定工具类型（支持简写 -T cc/cx）
npx zcf cs --list -T cc      # 列出 Claude Code 配置
npx zcf cs --list -T cx      # 列出 Codex 配置
npx zcf cs provider1 -T cx   # 切换 Codex 配置

参数说明

参数	说明	可选值	默认值
`--code-type`, `-T`	指定工具类型	`claude-code` (cc), `codex` (cx)	从 ZCF 配置读取
`--list`, `-l`	仅列出配置，不切换	无	否
`目标配置`	直接指定要切换的配置名称	配置名称或 ID	无

Claude Code 支持切换以下类型的配置：

官方登录：使用 Claude 官方 OAuth 登录
CCR 代理：使用 Claude Code Router 代理
自定义配置：通过 zcf init 创建的多 API 配置

配置来源：

配置文件：~/.claude/settings.json
Profile 管理：每个配置作为独立的 Profile 存储
当前配置标识：currentProfileId 字段

支持切换 Codex 的模型提供商：

官方登录：使用 Codex 官方 OAuth 登录
自定义提供商：通过 zcf init 配置的提供商（如 302.AI、GLM 等）

配置来源：

配置文件：~/.codex/config.toml
Provider 列表：从配置文件中读取已配置的提供商

2.7 版本检查

zcf check-updates 用于检测并更新 ZCF 工具链中的各个组件，包括 ZCF 本身、Claude Code、CCR、CCometixLine、Codex 等工具。

别名：可使用同等效果的 zcf check（如 npx zcf check -T cx）。

# 检查所有工具更新（Claude Code 模式）
npx zcf check

# 检查 Codex 相关工具更新
npx zcf check -T cx

# 非交互模式（自动更新，跳过确认）
npx zcf check -s

# 通过主菜单访问
npx zcf
# 然后选择 +. 检查更新

参数	简写	说明	可选值	默认值
`--code-type, -T`	`-T`	指定工具类型	`claude-code`, `codex`, `cc`, `cx`	从 ZCF 配置读取
`--skip-prompt, -s`	`-s`	跳过交互确认（非交互模式）	无	否（交互模式）

2.7.1 Claude Code 模式

当 -T 为 cc（或 claude-code）或未指定时，检查以下工具：

CCR (Claude Code Router)
- 包名：@musistudio/claude-code-router
- 检查方式：npm registry
Claude Code CLI
- 包名：@anthropic-ai/claude-code
- 检查方式：npm registry
CCometixLine
- 包名：@cometix/ccline
- 检查方式：npm registry

2.7.2 Codex 模式

当 -T 为 cx（或 codex）时，检查：

Codex CLI
- 检查方式：Codex 官方 API
- 更新方式：自动下载并安装最新版本

三、工作流详解

3.1 工作流概览

ZCF 通过 MCP + 工作流模板帮助团队标准化开发流程。本章介绍每个工作流的定位与使用方式。

工作流	适用场景	关键特性
ZCF 六阶段工作流	通用开发任务	六阶段闭环、自动质量把关、交互式确认
功能开发工作流	新功能设计与实现	规划 + UI/UX 代理联动
BMad 敏捷流程	大型项目敏捷迭代	多阶段仪式管理
Spec 工作流集成	需求文档与规范生成	Spec MCP 联动
Git 智能命令	Git 操作自动化	提交、回滚、清理、worktree

3.1.1 使用方法

根据使用的工具，使用不同的命令前缀：

Claude Code

在 Claude Code 中使用以下命令：

/zcf:workflow - 六阶段工作流
/zcf:feat - 功能开发工作流
/git-commit - Git 提交命令
/init-project - 项目初始化

Codex

在 Codex 中使用以下命令（注意 /prompts: 前缀）：

/prompts:workflow - 六阶段工作流
/prompts:git-commit - Git 提交命令
/prompts:git-rollback - Git 回滚命令
/prompts:git-cleanBranches - 清理已合并分支
/prompts:git-worktree - Git 工作树管理

⚠️ 注意：Codex 目前仅支持六阶段工作流和 Git 工作流。功能开发工作流（feat）、项目初始化（init-project）和 BMad 工作流暂未在 Codex 中提供。

💡 提示：Codex 使用 /prompts: 前缀访问所有工作流命令，这是 Codex 的命令格式规范。

使用建议

首次使用工作流时，可让 AI 输出任务进度文档，方便后续在新对话继续。
完成关键里程碑后请求 AI 生成进度总结，方便跨对话衔接。
搭配 best-practices/worktree.md 提升多工作区协作效率。
与 Git 工作流搭配使用，可快速完成需求拆解→编码→提交的闭环。

3.2 ZCF 六阶段工作流

六阶段工作流是 ZCF 的核心开发流程，涵盖完整的软件开发生命周期：研究 → 构思 → 计划 → 执行 → 优化 → 评审。

功能特点

📊 结构化流程：每个阶段都有明确的输入/输出与 AI 行为规范
✅ 强制确认机制：每个阶段完成后需要用户确认，避免遗漏用户反馈
📝 自动文档生成：自动生成计划文档并要求保存在项目目录
🔄 迭代支持：支持多轮迭代和持续改进

3.2.1 使用方法

Claude Code

在 Claude Code 中使用以下命令：

示例：

1	`/zcf:workflow 实现用户登录功能，支持邮箱和手机号登录`

Codex

在 Codex 中使用以下命令（注意前缀不同）：

示例：

1	`/prompts:workflow 实现用户登录功能，支持邮箱和手机号登录`

💡 提示：Codex 使用 /prompts: 前缀，而 Claude Code 使用 /zcf: 前缀。

3.2.2 六阶段详解

1. 研究（Research）

目标：深入理解任务需求和背景

AI 行为：

分析任务描述和上下文
收集相关技术资料和最佳实践
识别潜在问题和风险点
理解用户需求和业务场景

输出：

需求分析报告
技术调研结果
风险评估

2. 构思（Ideate）

目标：生成多个可行的解决方案

AI 行为：

提出多个设计方案
评估各方案的优缺点
考虑技术可行性和实现复杂度
推荐最佳方案

输出：

多个设计方案
方案对比分析
推荐方案及理由

3. 计划（Plan）

目标：制定详细的实施计划

AI 行为：

将任务拆解为具体步骤
确定技术选型和架构设计
制定时间估算和里程碑
识别依赖关系和前置条件

输出：

详细的任务分解
技术实现方案
开发计划和时间线
计划文档（保存在 .zcf/plan/current/任务名.md）

4. 执行（Execute）

目标：按照计划实施开发

AI 行为：

按照计划逐步实现功能
编写代码和测试用例
处理实现过程中的问题
保持代码质量和规范

输出：

实现的代码
测试用例
相关文档

5. 优化（Optimize）

目标：提升代码质量和性能

AI 行为：

代码重构和优化
性能优化建议
安全性检查
代码规范审查

输出：

优化后的代码
性能改进建议
安全审查报告

6. 评审（Review）

目标：最终评估和总结

AI 行为：

全面审查实现结果
生成测试报告
总结经验和教训
提出后续改进建议

输出：

完整的实现总结
测试报告
经验总结
改进建议

3.2.3 执行流程

基本流程

输入命令：输入 /zcf:workflow 或 /prompts:workflow 并描述任务
阶段执行：AI 按顺序执行六个阶段
用户确认：每个阶段完成后等待用户确认
继续下一步：用户确认后进入下一阶段
文档保存：计划文档自动保存到项目目录

文档保存位置

工作流会自动生成计划文档并要求保存：

进行中的任务：.zcf/plan/current/ 目录
已完成的任务：.zcf/plan/history/ 目录

💡 提示：.zcf/ 是统一的工作流目录，无论使用 Claude Code 还是 Codex 都使用相同的路径。

文件命名规则

进行中：任务名.md（例如：用户登录功能.md）
归档后：[完成时间]任务名.md（例如：2024-01-15_143052用户登录功能.md）

时间格式为 YYYY-MM-DD_HHMMSS，通过 bash 命令自动获取以确保准确性。

3.3 功能开发工作流

功能开发工作流面向新功能设计与实现，预置了专业的规划师（Planner）与 UI/UX 设计师（UI/UX Designer）代理，帮助您系统化地完成从需求分析到实施计划的完整流程。

3.3.1 功能概述

功能开发工作流专注于新功能的完整开发周期，通过结构化的阶段流程，确保功能开发的质量和完整性。

核心特点

🎯 需求驱动：从需求分析开始，确保功能符合用户期望
📐 多方案设计：生成多个可行方案并评估优劣
🎨 UI/UX 支持：提供专业的 UI/UX 设计建议
📋 详细计划：输出可执行的任务分解和实施计划
🤖 专业代理：内置规划师和 UI/UX 设计师代理

3.3.2 使用方法

Claude Code

在 Claude Code 中使用以下命令：

示例：

1	`/zcf:feat 实现用户评论功能，支持点赞、回复和删除`

Codex

⚠️ 注意：功能开发工作流（feat）目前仅在 Claude Code 中提供，Codex 暂不支持此工作流。

如果需要类似功能，可以在 Codex 中使用 /prompts:workflow 六阶段工作流来实现功能开发任务。

3.3.3 工作流阶段

功能开发工作流包含四个核心阶段：

1. 需求确认

目标：深入理解功能需求和业务场景

AI 行为：

分析功能描述和用户需求
识别功能范围和边界
确定成功标准和验收条件
理解业务价值和用户场景

输出：

功能需求文档
用户故事
验收标准
成功指标

示例输出：

功能范围：用户评论、点赞、回复、删除
用户角色：普通用户、管理员
验收标准：用户可以发布评论、点赞他人评论、回复评论、删除自己的评论

2. 方案规划

目标：生成多个可行的技术方案并评估

AI 行为：

提出 2-3 个不同的技术方案
评估各方案的技术复杂度
分析方案的可扩展性和维护性
考虑性能、安全性和成本因素
推荐最适合的方案

输出：

多个技术方案
方案对比分析
技术选型建议
架构设计草图

示例输出：

方案 A：使用现有数据库表结构，简单快速
方案 B：引入评论树结构，支持无限嵌套回复
方案 C：使用图数据库，支持复杂关系查询
推荐：方案 B（平衡了复杂度和功能完整性）

3. UI/UX 支撑

目标：提供专业的用户界面和交互设计建议

AI 行为：

设计用户界面布局
提供交互流程建议
生成线框图和原型建议
编写界面文案和提示语
考虑用户体验和易用性

输出：

UI 设计建议
交互流程图
界面线框图描述
文案和提示语
响应式设计考虑

示例输出：

评论列表布局：时间倒序、头像+昵称+内容
交互流程：点击回复 → 显示回复框 → 输入内容 → 提交
文案：“发表评论”、“回复”、“点赞（123）”

4. 实施计划

目标：输出详细的任务分解和实施计划

AI 行为：

将功能拆解为具体开发任务
确定技术实现细节
制定开发顺序和依赖关系
估算开发工作量
提供测试策略

输出：

详细任务列表
技术实现细节
开发时间估算
测试计划
部署考虑

示例输出：

创建评论数据模型（2 小时）
实现评论 API 接口（4 小时）
开发前端评论组件（3 小时）
实现点赞功能（2 小时）
实现回复功能（3 小时）
实现删除功能（1 小时）
编写测试用例（2 小时）
性能优化（1 小时）

3.4 BMad 敏捷流程

官方资源：BMad Method - GitHub

BMad（Build-Measure-Analyze-Decision）工作流适合大型项目的结构化迭代。BMad Method 是一个企业级的 AI 驱动敏捷开发框架，提供完整的团队协作工作流和文档模板。

什么是 BMad

BMad Method 是一个通用的 AI 代理框架，专为企业级敏捷开发而设计。它通过结构化的 Build-Measure-Analyze-Decision 循环，将复杂的开发任务分解为可管理的迭代周期。

核心特点

🏢 企业级框架：完整的敏捷开发流程和团队协作机制
🤖 专业 AI 代理团队：包含产品经理（PO）、项目经理（PM）、架构师、开发工程师、QA 测试等角色
📋 完整文档模板：自动生成 PRD、架构文档、用户故事等专业文档
🔄 迭代管理：支持持续迭代、验收和复盘
🌱 项目类型支持：支持全新项目（greenfield）和现有项目（brownfield）

3.4.1 使用方法

Claude Code

在 Claude Code 中使用以下命令初始化 BMad 工作流：

Codex

⚠️ 注意：BMad 工作流目前仅在 Claude Code 中提供，Codex 暂不支持此工作流。

如果需要类似的企业级敏捷开发流程，可以在 Codex 中使用 /prompts:workflow 六阶段工作流来实现类似功能。

3.4.2 核心功能

1. 一次性导入完整工作流

执行 /zcf:bmad-init 后，ZCF 会：

✅ 导入所有 BMad 指令集和文档模板
✅ 创建完整的项目结构
✅ 生成初始配置文件
✅ 设置 AI 代理团队

2. 迭代生命周期管理

BMad 工作流覆盖完整的迭代周期：

迭代计划：基于 PRD 和架构文档制定迭代计划
执行开发：按照计划执行开发任务
验收测试：QA 团队进行验收测试
复盘总结：团队复盘迭代成果和改进点

3. 专业 AI 代理团队

BMad 提供完整的专业 AI 代理团队，包括：

PO (Product Owner)：产品负责人，负责产品规划和需求管理
PM (Project Manager)：项目经理，负责项目进度和资源协调
架构师 (Architect)：系统架构师，负责架构设计和技术方案
开发工程师 (Developer)：开发人员，负责功能实现
QA (Quality Assurance)：测试工程师，负责质量保证和测试

4. 项目类型支持

Greenfield（全新项目）

适合从零开始的新项目：

# 在项目根目录执行
/zcf:bmad-init

# BMad 会引导你：
# 1. 创建 PRD（产品需求文档）
# 2. 设计系统架构
# 3. 生成用户故事
# 4. 创建项目结构

Brownfield（现有项目）

适合已有代码库的项目现代化和功能增强：

# 在现有项目根目录执行
/zcf:bmad-init

# BMad 会：
# 1. 分析现有代码结构
# 2. 生成架构文档
# 3. 创建功能增强计划
# 4. 保持与现有代码的兼容性

5. 文档模板系统

BMad 初始化后会生成完整的文档模板：

PRD (Product Requirements Document)：产品需求文档
架构文档：系统架构设计文档
用户故事：用户故事和验收标准
技术规范：技术实现规范
测试计划：测试计划和测试用例

3.4.3 工作流阶段

BMad 工作流遵循以下阶段：

Build（构建）

根据 PRD 和架构文档进行开发
遵循编码规范和最佳实践
实现功能模块

Measure（度量）

收集开发数据和指标
监控代码质量和性能
跟踪进度和风险

Analyze（分析）

分析迭代成果
识别问题和改进点
评估技术债务

Decision（决策）

评审迭代结果
决定下一步行动
调整开发计划

3.4.4 最佳实践最佳实践)

1. 团队统一使用

在团队环境中，建议统一使用 BMad 工作流：

# 团队成员统一执行
/zcf:bmad-init

# 这样可以确保：
# - 工作流规范一致
# - 文档格式统一
# - 协作效率提升

2. 结合 MCP 服务

结合 MCP 服务可以提升分析质量：

# 配置 MCP 服务
npx zcf
# 选择 4 (配置 MCP)

# 推荐服务：
# - Context7：查询技术文档
# - DeepWiki：获取项目背景信息
# - Spec Workflow：结构化需求分析

3. 迭代计划管理

制定明确的目标：每个迭代应该有清晰的目标和范围
保持迭代长度适中：建议 1-2 周的迭代周期
及时复盘：每次迭代结束后进行复盘，持续改进

4. 文档维护

保持文档更新：随着项目发展及时更新文档
版本控制：将文档纳入 Git 版本控制
团队共享：确保团队成员能够访问最新文档

5. 与 ZCF 其他工作流结合

BMad 可以与其他 ZCF 工作流结合使用：

# 1. 使用 BMad 进行项目规划
/zcf:bmad-init

# 2. 使用六阶段工作流实现具体功能
/zcf:workflow 实现用户登录功能

# 3. 使用功能开发工作流处理新需求
/zcf:feat 添加评论功能

# 4. 使用 Git 工作流管理代码
/git-commit

3.4.5 项目结构

BMad 初始化后会在项目根目录创建以下结构：

项目根目录/
├── .bmad-core/              # BMad 核心文件
│   ├── workflows/          # 工作流定义
│   ├── templates/          # 文档模板
│   └── agents/             # AI 代理定义
├── PRD.md                   # 产品需求文档
├── ARCHITECTURE.md          # 架构文档
├── USER_STORIES.md          # 用户故事
└── .claude/                 # Claude Code 配置
    └── plan/                # 迭代计划

3.5 Spec 工作流集成

Spec 工作流是一个综合性的 MCP 服务，提供从需求到实现的结构化特性开发工作流程。它通过标准化的需求分析、设计阶段、任务管理和实施工作流，帮助团队系统化地进行功能开发。

什么是 Spec 工作流

Spec Workflow MCP 是一个基于 Model Context Protocol (MCP) 的服务，专门为需求规格说明和设计文档生成而设计。它提供：

📋 需求分析：结构化需求收集和文档编写
🎨 设计阶段：详细的技术设计和架构规划
📊 任务管理：自动任务拆解和进度跟踪
🔄 实施工作流：从需求到实现的系统化方法
📈 交互式仪表板：内置的工作流可视化和管理仪表板
✅ 审批系统：每个开发阶段的评审和审批流程

3.5.1 安装与配置

通过 ZCF 安装

Spec 工作流作为 MCP 服务的一部分，可以在 ZCF 初始化时选择安装：

# 完整初始化时选择 Spec Workflow
npx zcf init

# 或在已有环境中添加 MCP 服务
npx zcf → 选择 4 (配置 MCP)

在 MCP 服务选择界面中，选择 spec-workflow 即可安装。

手动安装（可选）

如果需要手动安装或更新 Spec Workflow MCP：

# 安装最新版本
npm install -g @pimzino/spec-workflow-mcp@latest

# 或使用 npx 运行
npx -y @pimzino/spec-workflow-mcp@latest

配置文件位置

Spec Workflow MCP 配置会添加到 Claude Code 或 Codex 的 MCP 服务配置中：

Claude Code：

// ~/.claude/settings.json
{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest"]
    }
  }
}

Codex：

# ~/.codex/config.toml
[mcp_server."spec-workflow"]
command = "npx"
args = ["-y", "@pimzino/spec-workflow-mcp@latest"]

3.5.2 核心功能

1.需求分析

Spec 工作流提供结构化的需求收集和分析能力：

需求收集：系统化地收集功能需求、非功能需求和约束条件
需求文档化：自动生成标准化的需求规格说明文档
需求验证：检查需求的完整性、一致性和可测试性

使用示例：

2.设计阶段

提供详细的技术设计和架构规划：

技术方案设计：生成多个可行的技术方案
架构设计：设计系统架构和模块划分
接口设计：定义 API 接口和数据模型
数据库设计：设计数据库表结构（如需要）

使用示例：

3.任务管理

自动任务拆解和进度跟踪：

任务拆解：将大型需求拆解为可执行的小任务
任务优先级：自动评估和分配任务优先级
进度跟踪：实时跟踪任务完成情况
依赖管理：识别和管理任务之间的依赖关系

使用示例：

1	`请将登录功能拆解为具体的开发任务，并列出任务优先级`

4.实施工作流

系统化的实施方法：

代码生成：基于设计文档生成初始代码
测试用例：自动生成测试用例
文档同步：保持代码与文档的一致性
质量检查：集成代码质量检查

3.5.3 仪表板功能

启动仪表板

Spec Workflow MCP 提供可选的工作流可视化仪表板：

1 2	`# 使用命令行启动仪表板 npx -y @pimzino/spec-workflow-mcp@latest --dashboard`

仪表板会在默认浏览器中打开，提供：

📊 工作流可视化：图形化展示工作流状态
📋 任务列表：查看和管理所有任务
📈 进度统计：查看整体进度和统计数据
🔍 搜索和筛选：快速查找特定任务或需求

VS Code 扩展

也可以安装 VS Code 扩展获得更好的集成体验：

打开 VS Code 扩展市场
搜索 “Spec Workflow MCP”
安装 Pimzino.spec-workflow-mcp 扩展

扩展提供：

🎯 侧边栏集成：在 VS Code 侧边栏直接访问工作流
🔔 通知提醒：任务状态变更时自动提醒
📝 快速操作：直接在编辑器中执行工作流操作

3.5.4 工作流阶段

Spec 工作流通常包含以下阶段：

需求收集 → 收集和分析功能需求
需求验证 → 验证需求的完整性和可行性
方案设计 → 设计技术方案和架构
任务拆解 → 将需求拆解为可执行任务
实施开发 → 按照任务进行开发
测试验证 → 编写和执行测试用例
文档更新 → 更新相关文档
评审验收 → 进行代码评审和功能验收

3.5.5 使用示例

完整工作流示例

假设要开发一个”用户评论”功能：

步骤 1：需求分析

步骤 2：设计阶段

1	`基于刚才的需求，请设计评论功能的技术方案，包括数据模型和 API 接口`

步骤 3：任务拆解

1	`将评论功能拆解为具体的开发任务，并列出任务依赖关系`

步骤 4：实施开发

与 ZCF 工作流结合

Spec 工作流可以与 ZCF 的其他工作流结合使用：

# 在 Claude Code 中
/zcf:workflow 开发用户评论功能，使用 Spec 工作流进行需求分析

# 或使用功能开发工作流
/zcf:feat 用户评论功能

在 Codex 中，虽然 Spec 工作流可以作为 MCP 服务使用，但没有对应的 /prompts: 命令，需要直接在对话中使用。

3.5.6 最佳实践

项目早期使用

在项目早期使用 Spec 工作流锁定需求范围：

✅ 减少返工：通过结构化需求分析，避免后期需求变更
✅ 明确目标：清晰的需求文档帮助团队理解项目目标
✅ 风险识别：早期识别技术风险和实现难点

团队协作

在团队环境中：

统一模板：使用统一的需求和设计模板
定期评审：定期进行需求评审和设计评审
文档同步：保持代码、文档和需求的一致性

自定义模板

结合 advanced/templates.md 自定义 Spec 模板以适配团队规范：

# 查看模板配置
cat ~/.claude/templates/spec-requirements.md

# 自定义模板
# 编辑模板文件以符合团队规范

版本控制

建议将 Spec 工作流生成的文档纳入版本控制：

# 创建工作流文档目录
mkdir -p .spec-workflow/{requirements,design,tasks}

# 将生成的文档保存到对应目录
# 纳入 Git 版本控制
git add .spec-workflow/
git commit -m "docs: add spec workflow documents"

3.5.7 与其他工具的集成

Context7 集成

结合 Context7 MCP 服务获取库文档：

1	`请查询 React Hook Form 的最新文档，用于评论功能的表单验证`

DeepWiki 集成

使用 DeepWiki 获取项目背景信息：

Git 工作流集成

与 ZCF Git 工作流结合，自动生成提交信息：

1 2	`# 完成需求分析后 /git-commit -m "docs: add comment feature requirements spec"`

3.6 Git 智能命令

Git 工作流提供了一系列智能 Git 操作命令，简化版本控制流程。

命令列表

命令	Claude Code	Codex	说明
智能提交	`/git-commit`	`/prompts:git-commit`	智能生成提交信息并拆分提交
安全回滚	`/git-rollback`	`/prompts:git-rollback`	安全回滚到指定提交
清理分支	`/git-cleanBranches`	`/prompts:git-cleanBranches`	清理已合并分支
工作树管理	`/git-worktree`	`/prompts:git-worktree`	管理 Git Worktree，支持创建、迁移、删除

💡 提示：Codex 使用 /prompts: 前缀，而 Claude Code 直接使用 / 前缀。

3.6.1 命令详解

`/git-commit` / `/prompts:git-commit`

智能 Git 提交命令，功能包括：

🔍 自动分析改动：使用 Git 分析代码变更
✍️ 生成提交信息：自动生成符合 Conventional Commits 规范的提交信息
🎨 可选 Emoji：支持在提交信息中添加 emoji
📦 智能拆分：必要时建议拆分提交，保持提交原子性
✅ Git 钩子：默认运行本地 Git 钩子（可用 --no-verify 跳过）

使用示例：

1
2
3

/git-commit
# 或 Codex 中：
/prompts:git-commit

`/git-rollback` / `/prompts:git-rollback`

安全回滚命令，功能包括：

📋 列出分支：显示所有可用的分支
🔍 列出版本：显示指定分支的提交历史
⚠️ 二次确认：执行前要求用户确认
🔄 执行回滚：支持 reset 和 revert 两种方式
💾 备份机制：回滚前自动备份

使用示例：

1
2
3

/git-rollback
# 或 Codex 中：
/prompts:git-rollback

`/git-cleanBranches` / `/prompts:git-cleanBranches`

安全清理已合并分支，功能包括：

🔍 查找分支：自动查找已合并或过期的 Git 分支
🧪 Dry-run 模式：支持预览模式，先查看将要删除的分支
⚙️ 自定义配置：支持自定义基准分支和保护分支
🛡️ 安全机制：防止误删重要分支

使用示例：

1
2
3

/git-cleanBranches
# 或 Codex 中：
/prompts:git-cleanBranches

`/git-worktree` / `/prompts:git-worktree`

Git 工作树管理，功能包括：

📁 智能默认：在项目平级的 ../.zcf/项目名/ 目录下创建工作树
🔧 IDE 集成：自动配置 IDE 打开新工作树
📦 内容迁移：支持将现有内容迁移到工作树
🔄 完整管理：支持创建、迁移、删除等完整操作

使用示例：

1
2
3

/git-worktree 新建 feat/add-i18n 并打开
# 或 Codex 中：
/prompts:git-worktree 新建 feat/add-i18n 并打开

3.6.2 使用技巧

通过自然语言描述即可让 AI 执行多个 Git 操作
搭配 best-practices/worktree.md 可大幅提升多任务并行效率
在项目初始化后，建议先运行 /init-project（Claude Code）生成项目配置

⚠️ 注意：项目初始化工具（init-project）仅在 Claude Code 中提供，Codex 暂不支持

Reference

Claude Code > ZCF

#Claude Code #ZCF

Claude Code（九）:Claude Code配置工具ZCF

https://mztchaoqun.com.cn/posts/D96_ClaudeCode/

作者

mztchaoqun

发布于

2025年11月19日

许可协议

Claude Code（十）:Claude Code Skills 上一篇

Claude Code（八）:基于 Figma MCP 直出 App 下一篇

Claude Code（九）:Claude Code配置工具ZCF

一、简介

1.1 为什么选择 ZCF

1.2 使用 ZCF 你将获得什么

二、安装使用

2.1 主菜单

2.1.1 菜单功能详解

1.完整初始化（选项 1）

2.导入/更新工作流（选项 2）

3.配置 API 或 CCR（选项 3）

4.配置 MCP 服务（选项 4）

5.配置默认模型（选项 5）

6.配置 AI 记忆与输出风格（选项 6）

7.导入推荐环境变量与权限（选项 7）

R.CCR 管理菜单（选项 R）

U.Claude Code 使用分析（选项 U）

L.CCometixLine 管理（选项 L）

+.检查更新（选项 +）

-.卸载当前工具配置（选项 -）

2.2 CCR 代理管理

1. 初始化 CCR

2. 启动 UI

3. 检查状态

4. 重启服务

5. 启动服务

6. 停止服务

2.2.1 配置字段说明

2.2.2 提供商预设

2.3 使用分析 ccu

2.3.1 命令格式

2.3.2 参数说明

2.3.3 功能详解

2.3.4 统计数据来源

2.3.5 统计周期示例

日统计（daily）

周统计（weekly）

月统计（monthly）

2.3.6 输出格式

默认格式（表格）

JSON 格式

CSV 格式

2.3.7 使用场景

1. 日常使用监控

2. 团队使用统计

3. 成本分析

4. 自动化监控

2.3.8 与 CCometixLine 集成

2.4 卸载与清理

2.4.1 完整卸载

2.4.2 自定义卸载

2.4.3 常用参数

2.5 配置管理

2.5.1 API 模型配置

2.5.2 AI 输出语言指令

2.5.3 模板语言选择

2.6 配置切换

2.7 版本检查

2.7.1 Claude Code 模式

2.7.2 Codex 模式

三、工作流详解

3.1 工作流概览

3.1.1 使用方法

Claude Code

Codex

使用建议

3.2 ZCF 六阶段工作流

3.2.1 使用方法

Claude Code

Codex

3.2.2 六阶段详解

1. 研究（Research）

2. 构思（Ideate）

3. 计划（Plan）

4. 执行（Execute）

5. 优化（Optimize）

6. 评审（Review）

3.2.3 执行流程

基本流程

文档保存位置

3.3 功能开发工作流

日统计（`daily`）

周统计（`weekly`）

月统计（`monthly`）

3.4.4 最佳实践最佳实践)

`/git-commit` / `/prompts:git-commit`

`/git-rollback` / `/prompts:git-rollback`

`/git-cleanBranches` / `/prompts:git-cleanBranches`

`/git-worktree` / `/prompts:git-worktree`