Claude-Code-Workflow/docs/zh/features/cli.md

CLI 调用系统

一句话定位

CLI 调用系统是统一的多模型 AI 执行框架 — 一个命令调用多个 AI 工具 (Gemini、Qwen、Codex、Claude)，支持 analysis/write/review 模式，自动处理流式输出和错误恢复。

解决的痛点

痛点	现状	CLI 调用系统方案
多工具分散	不同 AI 工具命令格式不一致	统一 ccw cli 入口
模型切换困难	换模型要查文档记参数	--tool + --model 简化切换
输出格式混乱	各工具输出格式不统一	统一 JSON Lines 流式输出
错误恢复缺失	工具失败只能手动重试	自动 fallback 到备用模型
上下文管理弱	多轮对话上下文不连贯	Native Resume 自动管理

核心概念速览

概念	说明	示例
Tool (工具)	AI 执行端点	gemini, qwen, codex, claude, opencode
Mode (模式)	执行权限级别	analysis (只读), write (读写), review (代码审查)
Model (模型)	工具使用的具体模型	gemini-2.5-flash, gpt-5.2, coder-model
Fallback (备用)	主模型失败时的自动切换	secondaryModel 配置
Resume (恢复)	多轮对话上下文管理	--resume 参数
Session (会话)	命令执行的对话上下文	Native UUID / 消息历史

使用场景

场景	推荐工具	推荐模式
代码分析	gemini / qwen	analysis
代码生成	codex / gemini	write
代码审查	codex	review
架构设计	gemini + codex 并行	analysis
Bug 调试	gemini (分析) -> codex (修复)	analysis -> write
文档生成	qwen / gemini	write

操作步骤

基础用法

# 分析代码（默认 analysis 模式）
ccw cli -p "分析 auth 模块的代码结构" --tool gemini

# 生成代码（write 模式）
ccw cli -p "创建一个 JWT 认证中间件" --tool codex --mode write

# 代码审查（review 模式，仅 codex）
ccw cli -p "审查本次提交的代码变更" --tool codex --mode review

# 指定模型
ccw cli -p "分析性能瓶颈" --tool gemini --model "gemini-2.5-pro" --mode analysis

从文件读取 Prompt

# 使用 -p @file 语法
ccw cli -p @prompt.txt --tool gemini

# 使用 -f 参数
ccw cli -f prompt.md --tool qwen --mode write

工作目录控制

# 在特定目录执行
ccw cli -p "分析当前项目" --tool gemini --cd /path/to/project

# 包含额外目录（用于跨项目分析）
ccw cli -p "分析 shared 和 current 项目的关系" \
  --tool gemini \
  --cd /path/to/current \
  --includeDirs /path/to/shared

多轮对话 (Resume)

# 启动新会话
ccw cli -p "设计一个用户认证系统" --tool gemini

# 继续上一轮对话
ccw cli -p "现在实现登录接口" --tool gemini --resume

# 继续指定会话
ccw cli -p "修改登录接口返回 JWT" --tool gemini --resume abc123-def456

# 合并多个会话上下文
ccw cli -p "整合之前的讨论" --tool gemini --resume abc123,def456

代码审查模式 (Codex 专用)

# 审查未提交的变更
ccw cli --tool codex --mode review

# 审查与指定分支的差异
ccw cli --tool codex --mode review --base main

# 审查指定提交
ccw cli --tool codex --mode review --commit abc123

# 带标题的审查
ccw cli -p "关注安全性问题" --tool codex --mode review --uncommitted

使用规则模板

# 加载预定义模板
ccw cli -p "分析代码安全性" \
  --tool gemini \
  --mode analysis \
  --rule analysis-assess-security-risks

# 查看可用模板
ccw cli --help

配置说明

配置文件结构

全局配置: ~/.claude/cli-tools.json

{
  "version": "3.3.0",
  "tools": {
    "gemini": {
      "enabled": true,
      "primaryModel": "gemini-2.5-flash",
      "secondaryModel": "gemini-2.5-flash",
      "availableModels": [
        "gemini-3-pro-preview",
        "gemini-2.5-pro",
        "gemini-2.5-flash",
        "gemini-2.0-flash"
      ],
      "tags": ["分析", "Debug"],
      "type": "builtin"
    },
    "codex": {
      "enabled": true,
      "primaryModel": "gpt-5.2",
      "secondaryModel": "gpt-5.2",
      "tags": [],
      "type": "builtin"
    }
  }
}

设置文件: .cw/cli-settings.json

{
  "$schema": "../cli-tools-schema.json",
  "version": "1.0.0",
  "defaultTool": "gemini",
  "promptFormat": "plain",
  "smartContext": {
    "enabled": false,
    "maxFiles": 10
  },
  "nativeResume": true,
  "recursiveQuery": true,
  "cache": {
    "injectionMode": "auto",
    "defaultPrefix": "",
    "defaultSuffix": ""
  },
  "codeIndexMcp": "ace"
}

工具类型 (Type)

类型	说明	可用模型	支持
builtin	内置 CLI 工具	完整模型列表	分析 + 写入
cli-wrapper	Claude CLI 包装	settings.json 中的模型	分析 + 写入
api-endpoint	LiteLLM 端点	端点配置的模型	仅分析

标签 (Tags) 路由

标签用于工具选择和路由：

标签	说明	适用工具
分析	代码分析、架构审查	gemini, qwen
Debug	调试、错误诊断	gemini, qwen
实现	代码生成、功能实现	codex, gemini

输出格式

JSON Lines 流式输出

所有工具统一使用 JSON Lines 输出：

{"type": "status", "message": "Connecting to API..."}
{"type": "delta", "content": "基于代码分析"}
{"type": "delta", "content": "，auth 模块包含以下组件"}
{"type": "usage", "prompt_tokens": 1000, "completion_tokens": 500}
{"type": "error", "message": "API timeout, retrying..."}
{"type": "done", "finish_reason": "stop"}

输出类型

类型	说明
status	状态更新
delta	内容增量
usage	Token 使用量
error	错误信息
done	完成标记

Dashboard 中的 CLI 终端

终端面板功能

┌─────────────────────────────────────────────────────────────┐
│                    CLI 终端面板                             │
├─────────────────────────────────────────────────────────────┤
│  ┌───────────────────────────────────────────────────────┐ │
│  │ 工具选择: [gemini ▼] 模式: [analysis ▼] 模型: [...]  │ │
│  │ 目录: /path/to/project  包含: [shared]               │ │
│  └───────────────────────────────────────────────────────┘ │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Prompt 输入区 (支持多行)                              │ │
│  │ [执行] [规则模板] [恢复会话]                          │ │
│  └───────────────────────────────────────────────────────┘ │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ 输出区 (流式显示，支持 Markdown 渲染)                │ │
│  │ - 代码高亮                                            │ │
│  │ - 错误高亮                                            │ │
│  │ - Token 统计                                          │ │
│  └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

功能按钮

• 工具选择: 下拉选择可用工具
• 模式选择: analysis / write / review
• 模型选择: 工具可用模型列表
• 规则模板: 快速加载预定义模板
• 恢复会话: 选择历史会话继续

常见问题

Q1: analysis 和 write 模式的区别？

A:

• analysis: 只读模式，AI 只能读取文件，不能创建/修改/删除
• write: 读写模式，AI 可以完整操作文件系统
• review: 仅 Codex 支持，Git 感知的代码审查模式

Q2: 如何选择合适的工具？

A: 基于场景推荐：

• 代码分析/架构设计: gemini (速度快，上下文大)
• 代码生成/Bug 修复: codex (代码能力强)
• 中文任务: qwen (中文优化)
• 长上下文: claude (200K+ tokens)

Q3: Fallback 机制如何工作？

A: 当主工具失败时：

1. 尝试 secondaryModel (同工具)
2. 尝试下一个启用的工具
3. 回退到默认工具

Q4: 如何调试 CLI 调用？

A: 使用 -d, --debug 参数：

ccw cli -p "分析代码" --tool gemini -d

输出详细诊断信息，包括：

• 工具可用性检查
• 命令构建过程
• API 调用详情
• 错误堆栈

相关功能

• Spec 规范系统 — 规范自动注入到 Prompt
• Memory 记忆系统 — Resume 上下文管理
• API 设置 — API Keys 配置
• 系统设置 — cli-tools.json 配置

进阶阅读

• CLI 执行核心: ccw/src/tools/cli-executor-core.ts
• CLI 工具管理: ccw/src/tools/claude-cli-tools.ts
• 命令路由: ccw/src/commands/cli.ts
• 前端终端: ccw/frontend/src/components/terminal-dashboard/