docs: add VitePress documentation site

- Add docs directory with VitePress configuration - Add GitHub Actions workflow for docs build and deploy - Support bilingual (English/Chinese) documentation - Include search, custom theme, and responsive design
2026-03-01 15:03:57 +08:00 · 2026-02-28 16:14:09 +08:00
parent ab65caec45
commit c3ddf7e322
136 changed files with 34486 additions and 0 deletions
--- a/docs/zh/features/cli.md
+++ b/docs/zh/features/cli.md
@@ -0,0 +1,308 @@
+# 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/`