Claude-Code-Workflow/docs/zh/guide/cli-tools.md

CLI 工具配置

为你的开发工作流配置和自定义 CCW CLI 工具。

配置文件

CCW CLI 工具在 ~/.claude/cli-tools.json 中配置：

{
  "version": "3.3.0",
  "tools": {
    "tool-id": {
      "enabled": true,
      "primaryModel": "model-name",
      "secondaryModel": "fallback-model",
      "tags": ["tag1", "tag2"],
      "type": "builtin | api-endpoint | cli-wrapper"
    }
  }
}

工具类型

内置工具

具有所有功能的完整工具：

{
  "gemini": {
    "enabled": true,
    "primaryModel": "gemini-2.5-flash",
    "secondaryModel": "gemini-2.5-pro",
    "tags": ["analysis", "debug"],
    "type": "builtin"
  }
}

功能：分析 + 写入工具

API 端点工具

用于专门任务的分析专用工具：

{
  "custom-api": {
    "enabled": true,
    "primaryModel": "custom-model",
    "tags": ["specialized-analysis"],
    "type": "api-endpoint"
  }
}

功能：仅分析

CLI 命令格式

通用模板

ccw cli -p "PURPOSE: [目标] + [原因] + [成功标准]
TASK: • [步骤 1] • [步骤 2] • [步骤 3]
MODE: [analysis|write|review]
CONTEXT: @[文件模式] | Memory: [上下文]
EXPECTED: [输出格式]
CONSTRAINTS: [约束]" --tool <tool-id> --mode <mode> --rule <template>

必需参数

参数	描述	选项
--mode <mode>	必需 - 执行权限级别	analysis（只读） | write（创建/修改） | review（git 感知审查）
-p <prompt>	必需 - 带有结构化模板的任务提示	-

可选参数

参数	描述	示例
--tool <tool>	显式工具选择	--tool gemini
--rule <template>	加载规则模板以生成结构化提示	--rule analysis-review-architecture
--resume [id]	恢复之前的会话	--resume 或 --resume session-id
--cd <path>	设置工作目录	--cd src/auth
--includeDirs <dirs>	包含额外目录（逗号分隔）	--includeDirs ../shared,../types
--model <model>	覆盖工具的主要模型	--model gemini-2.5-pro

工具选择

基于标签的路由

根据任务要求选择工具：

# 带有 "analysis" 标签的任务路由到 gemini
ccw cli -p "PURPOSE: 调试认证问题
TASK: • 追踪认证流程 • 识别失败点
MODE: analysis" --tool gemini --mode analysis

# 无标签 - 使用第一个启用的工具
ccw cli -p "PURPOSE: 实现功能 X
TASK: • 创建组件 • 添加测试
MODE: write" --mode write

显式选择

覆盖自动选择：

ccw cli -p "任务描述" --tool codex --mode write

规则模板

自动加载结构化提示模板：

# 架构审查模板
ccw cli -p "分析系统架构" --mode analysis --rule analysis-review-architecture

# 功能实现模板
ccw cli -p "添加 OAuth2 认证" --mode write --rule development-implement-feature

模型配置

主要 vs 备用

{
  "codex": {
    "primaryModel": "gpt-5.2",
    "secondaryModel": "gpt-5.2"
  }
}

• primaryModel：工具的默认模型
• secondaryModel：主要模型失败时的备用

可用模型

工具	可用模型
gemini	gemini-3-pro-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash
codex	gpt-5.2
claude	sonnet, haiku
qwen	coder-model

工具标签

标签启用自动工具选择：

标签	用例
analysis	代码审查、架构分析
debug	错误诊断、故障排除
implementation	功能开发、代码生成
documentation	文档生成、技术写作
testing	测试生成、覆盖率分析

验证

要验证你的配置，直接检查配置文件：

cat ~/.claude/cli-tools.json

或测试工具可用性：

ccw cli -p "PURPOSE: 测试工具可用性
TASK: 验证工具是否工作
MODE: analysis" --mode analysis

故障排除

工具不可用

Error: Tool 'custom-tool' not found

解决方案：检查工具在配置中是否启用：

{
  "custom-tool": {
    "enabled": true
  }
}

模型未找到

Error: Model 'invalid-model' not available

解决方案：使用可用模型列表中的有效模型名称。

::: info 另见

• CLI 参考 - CLI 用法
• 模式 - 执行模式 :::