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/api-settings.md
+++ b/docs/zh/features/api-settings.md
@@ -0,0 +1,394 @@
+# API 设置
+
+## 一句话定位
+
+**API 设置是统一的多端点配置管理** — 在一个地方配置所有 AI 服务商的 API Keys 和端点，支持多环境切换和密钥加密存储。
+
+## 解决的痛点
+
+| 痛点 | 现状 | API 设置方案 |
+| --- | --- | --- |
+| **配置分散** | API Keys 散落在各工具配置中 | 统一配置入口 |
+| **安全性弱** | 明文存储密钥 | 支持密钥加密 |
+| **切换困难** | 切换服务商需要修改多处 | 一个配置文件管理所有 |
+| **环境隔离差** | 开发/生产环境混用 | 支持多环境配置 |
+
+## 核心概念速览
+
+| 概念 | 说明 | 位置 |
+| --- | --- | --- |
+| **API Keys** | 服务商认证密钥 | `settings.json` / `settings.local.json` |
+| **Providers** | AI 服务提供商 | OpenAI, Anthropic, Gemini, LiteLLM |
+| **Endpoints** | API 服务端点 | URL + 认证配置 |
+| **LiteLLM** | 统一代理服务 | 支持 100+ 模型 |
+| **本地配置** | 项目级配置 | `.cw/settings.json` |
+| **全局配置** | 用户级配置 | `~/.claude/settings.json` |
+
+## 配置层级
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    配置优先级                                │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. settings.local.json (最高优先级，不提交)               │
+│     └─ 本地开发配置，覆盖其他配置                           │
+│           │                                                 │
+│           ▼                                                 │
+│  2. .cw/settings.json (项目配置)                          │
+│     └─ 项目特定配置，团队成员共享                           │
+│           │                                                 │
+│           ▼                                                 │
+│  3. ~/.claude/settings.json (全局配置)                     │
+│     └─ 用户默认配置，所有项目共享                           │
+│           │                                                 │
+│           ▼                                                 │
+│  4. 默认值 (最低优先级)                                    │
+│     └─ 系统内置默认配置                                     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 配置说明
+
+### settings.json 结构
+
+```json
+{
+  "$schema": "https://cdn.jsdelivr.net/gh/your-repo/schema/settings-schema.json",
+  "providers": {
+    "openai": {
+      "apiKey": "sk-...",
+      "baseURL": "https://api.openai.com/v1",
+      "models": {
+        "gpt-4": "gpt-4-turbo",
+        "gpt-3.5": "gpt-3.5-turbo"
+      }
+    },
+    "anthropic": {
+      "apiKey": "sk-ant-...",
+      "baseURL": "https://api.anthropic.com/v1",
+      "models": {
+        "claude-opus": "claude-3-opus-20240229",
+        "claude-sonnet": "claude-3-sonnet-20240229"
+      }
+    },
+    "gemini": {
+      "apiKey": "AIza...",
+      "baseURL": "https://generativelanguage.googleapis.com/v1beta",
+      "models": {
+        "gemini-pro": "gemini-pro",
+        "gemini-flash": "gemini-1.5-flash"
+      }
+    },
+    "litellm": {
+      "apiKey": "sk-...",
+      "baseURL": "https://litellm.example.com/v1",
+      "models": {
+        "qwen-embed": "qwen/qwen3-embedding-sf"
+      }
+    }
+  },
+  "cw": {
+    "defaultTool": "gemini",
+    "promptFormat": "plain",
+    "smartContext": {
+      "enabled": false,
+      "maxFiles": 10
+    },
+    "nativeResume": true,
+    "recursiveQuery": true,
+    "cache": {
+      "injectionMode": "auto",
+      "defaultPrefix": "",
+      "defaultSuffix": ""
+    },
+    "codeIndexMcp": "ace"
+  },
+  "hooks": {
+    "prePrompt": [],
+    "postResponse": []
+  }
+}
+```
+
+### Providers 配置详解
+
+#### OpenAI
+
+```json
+{
+  "providers": {
+    "openai": {
+      "apiKey": "sk-proj-...",
+      "baseURL": "https://api.openai.com/v1",
+      "organization": "org-...",
+      "timeout": 60000,
+      "maxRetries": 3
+    }
+  }
+}
+```
+
+#### Anthropic (Claude)
+
+```json
+{
+  "providers": {
+    "anthropic": {
+      "apiKey": "sk-ant-...",
+      "baseURL": "https://api.anthropic.com/v1",
+      "version": "2023-06-01",
+      "timeout": 60000,
+      "maxRetries": 3
+    }
+  }
+}
+```
+
+#### Gemini (Google)
+
+```json
+{
+  "providers": {
+    "gemini": {
+      "apiKey": "AIza...",
+      "baseURL": "https://generativelanguage.googleapis.com/v1beta",
+      "timeout": 60000
+    }
+  }
+}
+```
+
+#### LiteLLM (统一代理)
+
+```json
+{
+  "providers": {
+    "litellm": {
+      "apiKey": "sk-...",
+      "baseURL": "https://litellm.example.com/v1",
+      "dropParams": ["max_tokens"],
+      "timeout": 120000
+    }
+  }
+}
+```
+
+### CCW 配置详解
+
+```json
+{
+  "cw": {
+    "defaultTool": "gemini",
+    "promptFormat": "plain",
+    "smartContext": {
+      "enabled": false,
+      "maxFiles": 10
+    },
+    "nativeResume": true,
+    "recursiveQuery": true,
+    "cache": {
+      "injectionMode": "auto",
+      "defaultPrefix": "",
+      "defaultSuffix": ""
+    },
+    "codeIndexMcp": "ace"
+  }
+}
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `defaultTool` | string | `gemini` | 默认 CLI 工具 |
+| `promptFormat` | string | `plain` | Prompt 格式: `plain` / `yaml` / `json` |
+| `smartContext.enabled` | boolean | `false` | 智能上下文开关 |
+| `smartContext.maxFiles` | number | `10` | 最大文件数量 |
+| `nativeResume` | boolean | `true` | 本地会话恢复 |
+| `recursiveQuery` | boolean | `true` | 递归查询 |
+| `cache.injectionMode` | string | `auto` | 缓存注入模式 |
+| `codeIndexMcp` | string | `ace` | 代码索引 MCP: `codexlens` / `ace` / `none` |
+
+### Hooks 配置
+
+```json
+{
+  "hooks": {
+    "prePrompt": [
+      {
+        "type": "command",
+        "command": "ccw",
+        "args": ["spec", "load", "--stdin"]
+      },
+      {
+        "type": "mcp",
+        "server": "cw-tools",
+        "tool": "core_memory",
+        "args": {
+          "operation": "search",
+          "query": "{{userPrompt}}",
+          "top_k": 5
+        }
+      }
+    ],
+    "postResponse": [
+      {
+        "type": "command",
+        "command": "ccw",
+        "args": ["memory", "capture"]
+      }
+    ]
+  }
+}
+```
+
+## 操作步骤
+
+### 初始化配置
+
+```bash
+# 在项目中初始化配置文件
+ccw config init
+
+# 编辑配置
+ccw config edit
+```
+
+### 设置 API Keys
+
+**方式 1: 编辑配置文件**
+
+```bash
+# 编辑项目配置
+code .cw/settings.json
+
+# 编辑全局配置
+code ~/.claude/settings.json
+```
+
+**方式 2: 使用命令**
+
+```bash
+# 设置 OpenAI API Key
+ccw config set providers.openai.apiKey "sk-proj-..."
+
+# 设置 Anthropic API Key
+ccw config set providers.anthropic.apiKey "sk-ant-..."
+
+# 设置默认工具
+ccw config set cw.defaultTool "codex"
+```
+
+**方式 3: 环境变量**
+
+```bash
+# 设置环境变量（优先级最高）
+export OPENAI_API_KEY="sk-proj-..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+export GEMINI_API_KEY="AIza..."
+```
+
+### 本地配置 (不提交)
+
+```bash
+# 创建本地配置（自动添加到 .gitignore）
+cat > .cw/settings.local.json << 'EOF'
+{
+  "providers": {
+    "openai": {
+      "apiKey": "sk-proj-..."
+    }
+  }
+}
+EOF
+```
+
+### 验证配置
+
+```bash
+# 验证 API Keys
+ccw config verify
+
+# 测试连接
+ccw cli -p "Hello" --tool gemini --mode analysis
+```
+
+## 配置文件位置
+
+| 配置文件 | 位置 | 用途 | Git |
+| --- | --- | --- | --- |
+| 项目配置 | `.cw/settings.json` | 项目共享配置 | 提交 |
+| 本地配置 | `.cw/settings.local.json` | 个人开发配置 | **不提交** |
+| 全局配置 | `~/.claude/settings.json` | 用户默认配置 | 不适用 |
+| CLI 工具配置 | `~/.claude/cli-tools.json` | CLI 工具定义 | 不适用 |
+| CLI 设置 | `.cw/cli-settings.json` | CLI 行为配置 | 提交 |
+
+## 常见问题
+
+### Q1: API Key 存储安全吗？
+
+A: 建议使用 `settings.local.json` 存储敏感信息：
+- `settings.local.json` 自动被 `.gitignore` 排除
+- 永不提交到仓库
+- 优先级最高，覆盖其他配置
+
+### Q2: 如何切换不同环境？
+
+A: 使用多配置文件：
+
+```bash
+# 开发环境
+.cw/settings.dev.json
+
+# 生产环境
+.cw/settings.prod.json
+
+# 切换环境
+cp .cw/settings.dev.json .cw/settings.local.json
+```
+
+### Q3: LiteLLM 如何配置？
+
+A: 配置 LiteLLM 端点：
+
+```json
+{
+  "providers": {
+    "litellm": {
+      "apiKey": "sk-...",
+      "baseURL": "https://your-litellm-proxy.com/v1"
+    }
+  },
+  "cw": {
+    "defaultTool": "litellm"
+  }
+}
+```
+
+### Q4: 配置不生效怎么办？
+
+A: 检查优先级和语法：
+
+```bash
+# 验证配置语法
+ccw config validate
+
+# 查看有效配置
+ccw config show
+
+# 查看配置来源
+ccw config --debug
+```
+
+## 相关功能
+
+- [CLI 调用系统](./cli.md) — 使用 API Keys 执行命令
+- [系统设置](./system-settings.md) — cli-tools.json 配置
+- [Dashboard 面板](./dashboard.md) — 可视化配置管理
+
+## 进阶阅读
+
+- 配置加载: `ccw/src/config/settings-loader.ts`
+- 配置验证: `ccw/src/config/settings-validator.ts`
+- CLI 配置: `ccw/src/tools/claude-cli-tools.ts`
+- Hooks 执行: `ccw/src/core/hooks/`