# 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` | ## 操作步骤 ### 基础用法 ```bash # 分析代码（默认 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 ```bash # 使用 -p @file 语法 ccw cli -p @prompt.txt --tool gemini # 使用 -f 参数 ccw cli -f prompt.md --tool qwen --mode write ``` ### 工作目录控制 ```bash # 在特定目录执行 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) ```bash # 启动新会话 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 专用) ```bash # 审查未提交的变更 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 ``` ### 使用规则模板 ```bash # 加载预定义模板 ccw cli -p "分析代码安全性" \ --tool gemini \ --mode analysis \ --rule analysis-assess-security-risks # 查看可用模板 ccw cli --help ``` ## 配置说明 ### 配置文件结构 **全局配置**: `~/.claude/cli-tools.json` ```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` ```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 输出： ```json {"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` 参数： ```bash ccw cli -p "分析代码" --tool gemini -d ``` 输出详细诊断信息，包括： - 工具可用性检查 - 命令构建过程 - API 调用详情 - 错误堆栈 ## 相关功能 - [Spec 规范系统](./spec.md) — 规范自动注入到 Prompt - [Memory 记忆系统](./memory.md) — Resume 上下文管理 - [API 设置](./api-settings.md) — API Keys 配置 - [系统设置](./system-settings.md) — 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/`