diff --git a/README.md b/README.md index 50ac1d3..a3f98f9 100644 --- a/README.md +++ b/README.md @@ -46,28 +46,161 @@ claude --version --- +### 1.3.1 ⚠️ 已知问题：Git Bash 检测报错 + +> [!WARNING] +> 这是一个 [GitHub 上的已知 bug](https://github.com/anthropics/claude-code/issues)，大量用户反馈即使正确安装了 Git 仍会报错。 + +**问题现象**：在 VS Code 或 Antigravity 中打开 Claude Code 扩展时，报错： + +``` +Claude Code on Windows requires git-bash (https://git-scm.com/downloads/win). +If installed but not in PATH, set environment variable pointing to your bash.exe... +``` + +**根本原因**：扩展内部用 `where.exe git` 命令检测 Git 是否存在。但 VS Code / Antigravity 的进程环境可能缺少 `System32` 或 Git `cmd` 目录的 PATH，导致检测失败。 + +> [!CAUTION] +> **`CLAUDE_CODE_GIT_BASH_PATH` 环境变量不能解决此问题！** 很多教程建议设置这个变量，但扩展的初始检测函数（`ZD6()`）并不读取此变量，它只执行 `where.exe git`。这个变量是给后续功能使用的，不影响初始检测。 + +**✅ 解决方案：修补扩展源码** + +在 PowerShell 中运行以下命令（一键修补）： + +```powershell +# 定位 extension.js 文件 +$file = (Get-ChildItem "$env:USERPROFILE\.vscode\extensions\anthropic.claude-code-*\extension.js" -ErrorAction SilentlyContinue) ?? + (Get-ChildItem "$env:USERPROFILE\.antigravity\extensions\anthropic.claude-code-*\extension.js" -ErrorAction SilentlyContinue) + +if (-not $file) { Write-Host "ERROR: Claude Code extension not found"; return } + +$content = [System.IO.File]::ReadAllText($file.FullName) + +# 查找并替换 git-bash 检测逻辑 +$pattern = 'catch{throw Error("Claude Code on Windows requires git-bash' +$idx = $content.IndexOf($pattern) + +if ($idx -ge 0) { + # 找到完整的 catch 块并替换 + $catchStart = $idx + $catchEnd = $content.IndexOf(')}")', $idx) + 3 + $oldBlock = $content.Substring($catchStart, $catchEnd - $catchStart) + $content = $content.Replace($oldBlock, 'catch{return}') + [System.IO.File]::WriteAllText($file.FullName, $content) + Write-Host "SUCCESS: Git-bash check bypassed in $($file.FullName)" +} else { + Write-Host "Already patched or pattern changed in new version" +} +``` + +> [!IMPORTANT] +> **扩展更新会覆盖补丁！** 建议： +> 1. 在 VS Code / Antigravity 设置中添加 `"extensions.autoUpdate": false` 关闭自动更新 +> 2. 保存上面的补丁命令，扩展更新后重新运行即可 + +--- + ### 1.4 配置环境变量 > 最好下面两个一起配置 #### 1.4.1 配置 settings.json 文件 -创建（如果不存在）或编辑 `C:\Users\用户名\.claude\settings.json`，输入以下值并保存： +> [!IMPORTANT] +> **文件路径**：`C:\Users\<你的用户名>\.claude\settings.json` +> +> 例如用户名为 `Lenovo`，则完整路径为：`C:\Users\Lenovo\.claude\settings.json` +> +> 如果 `.claude` 文件夹或 `settings.json` 不存在，请手动创建。 + +这个文件是 Claude Code **最核心的配置文件**，控制 API 连接、权限和 MCP 服务器。以下是完整的配置说明。 + +**API Key 配置（二选一）** + +| 方式 | 字段 | 示例值 | 安全性 | 适用场景 | +|------|------|--------|--------|----------| +| **方式一（推荐 ⭐）** | `apiKeyHelper` | `"echo sk-your-key"` | 高（Key 不明文存储） | 团队共享、版本控制 | +| 方式二 | `env.ANTHROPIC_AUTH_TOKEN` | `"sk-your-key"` | 低（明文写死） | 个人快速使用 | -```json +**完整配置示例（含 MCP 服务器）** + +```jsonc { + // ======================== + // 🔑 API 配置（更换服务商时只改这两行） + // ======================== + "apiKeyHelper": "echo sk-your-api-key-here", // ← 改这里：换成新的 API Key "env": { - "ANTHROPIC_AUTH_TOKEN": "替换为您的API Key", - "ANTHROPIC_BASE_URL": "https://www.fucheers.top", - "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "12000" + "ANTHROPIC_BASE_URL": "https://api.kimi.com/coding/", // ← 改这里：换成新的 API 地址 + "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" }, + + // ======================== + // 🔒 权限控制 + // ======================== "permissions": { - "allow": [], + "allow": [ + "Bash(ffmpeg:*)" // 允许 Claude 执行 ffmpeg 命令 + ], "deny": [] + }, + + // ======================== + // 🔌 MCP 服务器（可选，按需添加） + // ======================== + "mcpServers": { + "granola": { + "type": "sse", + "url": "https://mcp.granola.ai/mcp" + }, + "v0": { + "command": "D:\\Program Files\\nodejs\\npx.cmd", + "args": ["-y", "v0-mcp@latest"], + "timeout": 60000, + "env": { + "V0_API_KEY": "your-v0-api-key-here", + "PATH": "D:\\Program Files\\nodejs;C:\\Windows\\System32;C:\\Windows" + } + }, + "weixin-reader": { + "command": "C:\\Users\\用户名\\AppData\\Local\\Programs\\Python\\Python312\\python.exe", + "args": ["D:\\your-project\\wexin-read-mcp\\src\\server.py"], + "timeout": 30000 + }, + "ChatPRD": { + "command": "D:\\Program Files\\nodejs\\npx.cmd", + "args": ["-y", "mcp-remote", "https://app.chatprd.ai/mcp"], + "timeout": 60000, + "env": { + "PATH": "D:\\Program Files\\nodejs;C:\\Windows\\System32;C:\\Windows" + } + } } } ``` +> [!NOTE] +> 上面 JSON 中的注释仅用于说明，**实际使用时请删除所有 `//` 注释**（JSON 标准不支持注释）。 + +**字段逐行解释** + +| 字段 | 作用 | 何时需要修改 | +|------|------|-------------| +| `apiKeyHelper` | 通过命令返回 API Key | **更换 API 服务商时** | +| `env.ANTHROPIC_BASE_URL` | API 服务商地址 | **更换 API 服务商时** | +| `env.CLAUDE_CODE_GIT_BASH_PATH` | Git Bash 路径 | 仅 Git 安装路径不同时 | +| `permissions.allow` | 允许 Claude 自动执行的命令 | 按需添加 | +| `mcpServers.*` | MCP 服务器配置 | 添加/删除 MCP 服务时 | + +> [!TIP] +> **关于 MCP 服务器**： +> - `granola`：会议记录管理，通过 SSE 连接 +> - `v0`：Vercel v0 UI 原型生成，需要 [V0 API Key](https://v0.dev) +> - `weixin-reader`：微信公众号文章抓取（Python 实现） +> - `ChatPRD`：AI 产品文档生成 +> +> 每个 MCP 服务器的 `env.PATH` 需要手动补全 `nodejs` 和 `System32` 路径，因为 VS Code / Antigravity 的进程 PATH 可能不完整。 + --- #### 1.4.2 配置环境变量 @@ -95,6 +228,7 @@ echo Setting environment variables... setx ANTHROPIC_AUTH_TOKEN "%API_KEY%" setx ANTHROPIC_BASE_URL "https://www.fucheers.top" setx CLAUDE_CODE_MAX_OUTPUT_TOKENS "12000" +setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe" echo. echo ======================================== @@ -105,6 +239,7 @@ echo Environment variables set: echo ANTHROPIC_AUTH_TOKEN = %API_KEY% echo ANTHROPIC_BASE_URL = https://www.fucheers.top echo CLAUDE_CODE_MAX_OUTPUT_TOKENS = 12000 +echo CLAUDE_CODE_GIT_BASH_PATH = C:\Program Files\Git\bin\bash.exe echo. echo Please restart your terminal for changes to take effect. echo. @@ -113,6 +248,8 @@ pause 下载这个 bat 文件，输入 API Key 回车即设置完成。 +> **注意**：`CLAUDE_CODE_GIT_BASH_PATH` 主要用于 CLI 版 `claude` 命令。如果 VS Code/Antigravity 扩展仍报错，请参考 [1.3.1 节](#131-️-已知问题git-bash-检测报错) 使用源码补丁方案。 + --- ### 1.5 打开 Claude Code 终端 @@ -192,6 +329,13 @@ claude ## 4. VS Code 扩展与 Claude Code CLI +> [!TIP] +> 以下内容同样适用于 **Antigravity IDE**（Google 基于 VS Code 的 fork）。两者的区别仅在扩展安装路径： +> - VS Code：`%USERPROFILE%\.vscode\extensions\anthropic.claude-code-*\` +> - Antigravity：`%USERPROFILE%\.antigravity\extensions\anthropic.claude-code-*\` +> +> 设置界面和操作方式完全一致。 + ### 扩展设置 `~/.claude/settings.json` 中的 Claude Code 设置，在 VS Code 和 CLI 之间共享，用于配置环境变量、hooks 和 MCP servers。有关详细信息，请参阅 [Settings](https://code.claude.com/docs/en/settings)。 @@ -213,11 +357,26 @@ claude | `enableNewConversationShortcut` | `true` | 启用 Cmd/Ctrl+N 以开始新对话 | | `hideOnboarding` | `false` | 隐藏入门引导卡片（生产环境推荐） | | `respectGitIgnore` | `true` | 从文件搜索中排除 `.gitignore` 匹配项 | -| `environmentVariables` | `[]` | 为 Claude 进程设置环境变量。共享配置请使用 Claude Code 设置 | +| `environmentVariables` | `{}` | 为 Claude 进程设置环境变量。共享配置请使用 Claude Code 设置 | | **`disableLoginPrompt`** | **`false`** | **跳过身份验证提示（用于第三方提供商设置）** | | `allowDangerouslySkipPermissions` | `false` | 跳过所有权限检查请求，**谨慎使用** | | `claudeProcessWrapper` | `-` | 用于启动 Claude 进程的可执行文件路径 | +> [!CAUTION] +> **`environmentVariables` 必须使用对象格式 `{}`，不能用数组 `[]`！** +> +> 错误写法会导致 `v is not iterable` 报错，使扩展无法启动。 +> +> ```json +> // ❌ 错误：使用数组 +> "claudeCode.environmentVariables": ["ANTHROPIC_BASE_URL=https://..."] +> +> // ✅ 正确：使用对象 +> "claudeCode.environmentVariables": { +> "ANTHROPIC_BASE_URL": "https://..." +> } +> ``` + ### 关键设置：Disable Login Prompt > [!IMPORTANT] @@ -247,6 +406,60 @@ Claude Code 同时提供 VS Code 扩展（图形界面）和 CLI（终端命令 --- +## 5. 🔄 更换 API 提供商 + +当需要更换 API 服务商时（例如从 Kimi 切换到其他兼容 Anthropic API 格式的服务商），**只需修改 1 个文件的 2 个字段**。 + +### 📁 需要修改的文件 + +``` +C:\Users\<你的用户名>\.claude\settings.json +``` + +### 🔧 需要修改的字段 + +| 字段 | 改什么 | 示例 | +|------|--------|------| +| `apiKeyHelper` | `echo` 后面的 API Key | `"echo sk-new-xxx"` | +| `env.ANTHROPIC_BASE_URL` | API 服务商的地址 | `"https://new-provider.com/v1/"` | + +### 📝 修改示例（diff 对比） + +```diff + { +- "apiKeyHelper": "echo sk-kimi-旧的Key", ++ "apiKeyHelper": "echo sk-new-新的Key", + "env": { +- "ANTHROPIC_BASE_URL": "https://api.kimi.com/coding/" ++ "ANTHROPIC_BASE_URL": "https://new-provider.com/v1/" + } + } +``` + +> [!WARNING] +> **其他字段不要动！** `permissions`、`mcpServers`、`CLAUDE_CODE_GIT_BASH_PATH` 等字段与 API 服务商无关，改了可能导致功能异常。 + +### ✅ 完整操作步骤 + +1. 用任意编辑器打开 `C:\Users\<你的用户名>\.claude\settings.json` +2. 找到 `apiKeyHelper` 行 → 把 `echo` 后面的内容换成新的 API Key +3. 找到 `ANTHROPIC_BASE_URL` 行 → 把 URL 换成新服务商的地址 +4. 保存文件 +5. **使生效**（二选一）： + - **VS Code / Antigravity**：按 `Ctrl+Shift+P` → 输入 `Reload Window` 回车 + - **CLI 终端**：关闭终端窗口，重新打开后运行 `claude` +6. 输入 `/status` 确认已连接到新的服务商 ✅ + +### 🔍 常见第三方 API 服务商参考 + +| 服务商 | `ANTHROPIC_BASE_URL` 格式 | +|--------|---------------------------| +| Kimi | `https://api.kimi.com/coding/` | +| Fucheers | `https://www.fucheers.top` | +| 其他兼容服务商 | 参考服务商文档中的 Base URL | + +--- + ## 📎 相关资源 | 资源 | 说明 |