mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-18 06:15:51 +00:00
docs: 文档大重组，对齐 README 入口
以 README 为单一事实来源，重构整个 docs/ 目录。 最终结构（3 大组、15 篇文档）： - 开始: installation / quickstart / model-providers - 核心功能: pipes-and-lan、acp、channels、chrome-control、computer-use、 voice-mode、web-browser-tool、auto-dream、remote-control-self-hosting、 langfuse-monitoring - 内部机制: growthbook-adapter、sentry-setup 主要变更： - 删除 56 个 README 未提及的文档（architecture 全部 / guides 全部 / features 中未在 README 出现的 20 篇 / internals 中的 5 篇） - 合并 6 组重复文档（pipes-and-lan、chrome-control、acp、computer-use、 auto-dream、coordinator-mode 简化为入口） - features 子组从 5 → 4，ui/ 合并入 tools/ - 所有保留文档加上人性化 frontmatter（title/description/keywords） - docs.json navigation 简化为 3 大组，redirects 重新过滤为 7 条合并跳转 - 新增 docs.md 工作大纲与验证脚本（verify-docs / check-docs-orphans / dump-docs-outline） 总计 130 文件改动，从约 35000 行精简到约 2000 行。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
This commit is contained in:
claude-code-best
125
docs/getting-started/installation.mdx
Normal file
125
docs/getting-started/installation.mdx
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: "安装 Claude Code Best"
|
||||
description: "通过 NPM 一行命令安装 CCB，或从源码克隆构建。支持 macOS、Linux、Windows。"
|
||||
keywords: ["安装", "CCB", "NPM", "源码构建", "Bun"]
|
||||
og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
|
||||
---
|
||||
|
||||
CCB 提供两种安装方式：**NPM 安装**（推荐普通用户）和**源码构建**（推荐贡献者/二次开发者）。
|
||||
|
||||
## 方式一：NPM 安装（推荐）
|
||||
|
||||
无需克隆仓库，一行命令安装到全局：
|
||||
|
||||
```sh
|
||||
npm i -g claude-code-best
|
||||
|
||||
# 验证
|
||||
ccb --version
|
||||
```
|
||||
|
||||
启动方式：
|
||||
|
||||
```sh
|
||||
ccb # 以 Node.js 形态运行
|
||||
ccb-bun # 以 Bun 形态运行（启动更快）
|
||||
ccb update # 更新到最新版本
|
||||
```
|
||||
|
||||
> 💡 **不推荐** `bun i -g claude-code-best`：bun 全局安装在部分平台有路径冲突问题，建议用 npm。如果一定要用 bun，记得 `bun pm -g trust claude-code-best @claude-code-best/mcp-chrome-bridge` 解除信任限制。
|
||||
|
||||
### 远程控制模式（可选）
|
||||
|
||||
如果你有自己的 Remote Control Server，可以通过环境变量直连：
|
||||
|
||||
```sh
|
||||
CLAUDE_BRIDGE_BASE_URL=https://your-rcs.example.com/ \
|
||||
CLAUDE_BRIDGE_OAUTH_TOKEN=your-token \
|
||||
ccb --remote-control
|
||||
```
|
||||
|
||||
详情见 [Remote Control 自托管](../features/modes/remote-control-self-hosting)。
|
||||
|
||||
### 安装失败排查
|
||||
|
||||
| 症状 | 处理 |
|
||||
|------|------|
|
||||
| `command not found: ccb` | 重开终端，或手动把 npm global bin 加入 PATH |
|
||||
| 旧版本残留导致异常 | `npm rm -g claude-code-best && npm i -g claude-code-best@latest` |
|
||||
| 拉取特定版本 | `npm i -g claude-code-best@<版本号>` |
|
||||
| Windows 上启动报错 | 改用 `ccb-bun` 或安装 [Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) |
|
||||
|
||||
---
|
||||
|
||||
## 方式二：源码构建（贡献者）
|
||||
|
||||
源码运行需要 **Bun ≥ 1.3.11**。
|
||||
|
||||
### 1. 安装 Bun
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# Windows (PowerShell)
|
||||
powershell -c "irm bun.sh/install.ps1 | iex"
|
||||
```
|
||||
|
||||
安装后让当前 shell 识别 bun：
|
||||
|
||||
```bash
|
||||
exec /bin/zsh # macOS 默认 zsh
|
||||
# 或
|
||||
source ~/.bashrc # Linux bash
|
||||
```
|
||||
|
||||
> ⚠️ **一定要最新版 bun**：`bun upgrade`。低版本会触发各种奇怪的 BUG。
|
||||
|
||||
### 2. 克隆并安装依赖
|
||||
|
||||
```bash
|
||||
git clone https://github.com/claude-code-best/claude-code.git
|
||||
cd claude-code
|
||||
bun install
|
||||
```
|
||||
|
||||
### 3. 开发模式运行
|
||||
|
||||
```bash
|
||||
bun run dev # 默认开发模式（启用所有 feature）
|
||||
bun run dev:inspect # 带调试器（BUN_INSPECT=9229 改端口）
|
||||
echo "say hello" | bun run src/entrypoints/cli.tsx -p # Pipe 模式
|
||||
```
|
||||
|
||||
### 4. 构建产物
|
||||
|
||||
```bash
|
||||
bun run build # 默认 Bun.build，输出 dist/cli.js + chunks/
|
||||
bun run build:vite # 备选 Vite 构建（chunk 体积更小）
|
||||
```
|
||||
|
||||
构建后可直接用 node 运行：
|
||||
|
||||
```bash
|
||||
node dist/cli.js
|
||||
```
|
||||
|
||||
> 🔍 **为什么 Vite 构建强制代码分割？** 单文件 17MB 产物会让 Bun/JSC 全量解析 bytecode，RSS 暴涨至 ~1GB；分割为 600+ 小 chunk 后按需加载，`--version` RSS 从 966MB 降至 35MB。详见 [architecture/](../architecture/what-is-claude-code)。
|
||||
|
||||
### 5. 提交前检查
|
||||
|
||||
每次修改后必须运行：
|
||||
|
||||
```bash
|
||||
bun run precheck # typecheck + lint fix + test
|
||||
```
|
||||
|
||||
`precheck` 必须零错误通过，pre-commit hook 会自动拦截不合格的提交。
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- [快速上手](./quickstart) — 5 分钟学会基本使用
|
||||
- [配置模型供应商](./model-providers) — 接入 DeepSeek、GLM、OpenAI 等第三方模型
|
||||
- [Feature Flags](../internals/feature-flags) — 了解运行时功能开关
|
||||
165
docs/getting-started/model-providers.mdx
Normal file
165
docs/getting-started/model-providers.mdx
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
title: "配置模型供应商"
|
||||
description: "通过 /login 命令接入 OpenAI / Anthropic / Gemini / Grok 兼容协议，或直接用环境变量配置。支持 DeepSeek、GLM、OpenRouter、Bedrock 代理等任意兼容服务。"
|
||||
keywords: ["模型供应商", "/login", "OpenAI", "Gemini", "Grok", "DeepSeek", "GLM"]
|
||||
og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
|
||||
---
|
||||
|
||||
CCB 不绑定 Anthropic 官方账号，你可以接入任意**协议兼容**的第三方服务。两种配置方式：
|
||||
|
||||
- **交互式**：REPL 里输入 `/login`，按引导填字段（推荐首次用户）
|
||||
- **环境变量**：写入 shell 配置或 `.envrc`（推荐 CI / 自动化场景）
|
||||
|
||||
## 协议矩阵
|
||||
|
||||
| 协议 | 启用方式 | 适用场景 |
|
||||
|------|---------|---------|
|
||||
| **Anthropic Compatible**（默认） | 无需额外开关 | Anthropic 官方 / OpenRouter / Bedrock 代理 / 任意 Messages API 兼容服务 |
|
||||
| **OpenAI 兼容** | `CLAUDE_CODE_USE_OPENAI=1` | DeepSeek、Ollama、vLLM、Moonshot、本地部署等 |
|
||||
| **Gemini 兼容** | `CLAUDE_CODE_USE_GEMINI=1` | Google Gemini 系列模型 |
|
||||
| **Grok 兼容** | `CLAUDE_CODE_USE_GROK=1` | xAI Grok 系列模型 |
|
||||
|
||||
## 方式一：`/login` 交互配置（推荐）
|
||||
|
||||
在 REPL 里输入 `/login`，进入引导界面，选择对应协议栏目：
|
||||
|
||||
```
|
||||
┌─ Select Provider ───────────────────────┐
|
||||
│ ❯ Anthropic Compatible │
|
||||
│ OpenAI Compatible │
|
||||
│ Gemini Compatible │
|
||||
│ Grok Compatible │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Anthropic Compatible 需要填写
|
||||
|
||||
| 字段 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| Base URL | API 服务地址 | `https://api.example.com/v1` |
|
||||
| API Key | 认证密钥 | `sk-xxx` |
|
||||
| Haiku Model | 快速模型 ID | `claude-haiku-4-5-20251001` |
|
||||
| Sonnet Model | 均衡模型 ID | `claude-sonnet-4-6` |
|
||||
| Opus Model | 高性能模型 ID | `claude-opus-4-6` |
|
||||
|
||||
> ⌨️ **Tab / Shift+Tab** 切字段，**Enter** 确认并跳到下一个，最后一个字段按 Enter 保存。
|
||||
|
||||
### OpenAI 兼容（DeepSeek / Ollama / vLLM 等）
|
||||
|
||||
`CLAUDE_CODE_USE_OPENAI=1` 启用后，配置以下环境变量：
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_OPENAI=1
|
||||
export OPENAI_API_KEY=sk-xxx
|
||||
export OPENAI_BASE_URL=https://api.deepseek.com/v1
|
||||
export OPENAI_MODEL=deepseek-chat # 可选，默认让 CCB 选合适档位
|
||||
```
|
||||
|
||||
DeepSeek 的 thinking mode 已自动适配，无需额外配置。
|
||||
|
||||
### Gemini 兼容
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_GEMINI=1
|
||||
export GEMINI_API_KEY=AIzaSy... # 必填
|
||||
export GEMINI_MODEL=gemini-2.5-pro # 直接指定模型（最高优先级）
|
||||
# 或按能力档位映射：
|
||||
export GEMINI_DEFAULT_SONNET_MODEL=gemini-2.5-flash
|
||||
export GEMINI_DEFAULT_OPUS_MODEL=gemini-2.5-pro
|
||||
```
|
||||
|
||||
模型映射优先级：`GEMINI_MODEL` > `GEMINI_DEFAULT_*_MODEL`。
|
||||
|
||||
### Grok 兼容
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_GROK=1
|
||||
export XAI_API_KEY=xai-...
|
||||
export GROK_MODEL=grok-4 # 可选
|
||||
```
|
||||
|
||||
## 环境变量优先级
|
||||
|
||||
CCB 选择 provider 的逻辑：
|
||||
|
||||
```
|
||||
命令行参数 --provider > 环境变量 CLAUDE_CODE_USE_* > 默认 firstParty (Anthropic)
|
||||
```
|
||||
|
||||
可以同时配置多个 provider，通过环境变量切换：
|
||||
|
||||
```bash
|
||||
# 临时用 DeepSeek 跑一个会话
|
||||
CLAUDE_CODE_USE_OPENAI=1 OPENAI_MODEL=deepseek-reasoner ccb
|
||||
```
|
||||
|
||||
## 国内服务接入示例
|
||||
|
||||
### DeepSeek
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_OPENAI=1
|
||||
export OPENAI_API_KEY=sk-xxx
|
||||
export OPENAI_BASE_URL=https://api.deepseek.com/v1
|
||||
export OPENAI_MODEL=deepseek-chat
|
||||
```
|
||||
|
||||
### 智谱 GLM
|
||||
|
||||
GLM 官方提供 OpenAI 兼容接口：
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_OPENAI=1
|
||||
export OPENAI_API_KEY=xxx
|
||||
export OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4
|
||||
export OPENAI_MODEL=glm-4.6
|
||||
```
|
||||
|
||||
### 通义千问
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_OPENAI=1
|
||||
export OPENAI_API_KEY=sk-xxx
|
||||
export OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
export OPENAI_MODEL=qwen-max
|
||||
```
|
||||
|
||||
### OpenRouter（一站式多模型）
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
|
||||
export ANTHROPIC_API_KEY=sk-or-...
|
||||
# 然后用 /login 选择 Anthropic Compatible，模型 ID 填 OpenRouter 的 ID
|
||||
```
|
||||
|
||||
## 穷鬼模式（Poor Mode）
|
||||
|
||||
接入便宜的第三方模型后，建议开启 `/poor` 进一步降本：
|
||||
|
||||
```
|
||||
/poor on
|
||||
```
|
||||
|
||||
效果：
|
||||
|
||||
- 关闭自动记忆提取（`extract_memories`）
|
||||
- 关闭输入提示建议（`prompt_suggestion`）
|
||||
- 关闭 verification agent
|
||||
|
||||
通常能减少 30%-50% 的 token 消耗。设置写入 `~/.claude/settings.json`，重启后保留。
|
||||
|
||||
## 排查
|
||||
|
||||
| 症状 | 检查 |
|
||||
|------|------|
|
||||
| `401 Unauthorized` | API Key 错误或过期 |
|
||||
| `model not found` | 模型 ID 写错，或 provider 没有这个模型 |
|
||||
| 响应慢到超时 | 网络问题或 base URL 写错（注意有的 provider 需要去掉 `/v1` 后缀） |
|
||||
| 工具调用不工作 | 部分小厂兼容服务不支持 tool_use，换模型或换 provider |
|
||||
| 中文乱码 | 终端编码问题，检查 `LANG=zh_CN.UTF-8` 是否设置 |
|
||||
|
||||
## 下一步
|
||||
|
||||
- [快速上手](./quickstart) — 基本使用流程
|
||||
- [Token Budget](../features/tools/token-budget) — 给每个会话设定 token 上限
|
||||
- [Langfuse 监控](../features/tools/langfuse-monitoring) — 实时观察每次 agent loop 的 token 消耗
|
||||
128
docs/getting-started/quickstart.mdx
Normal file
128
docs/getting-started/quickstart.mdx
Normal file
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: "快速上手"
|
||||
description: "5 分钟掌握 CCB 的基本使用：启动会话、输入指令、审批工具调用、用斜杠命令管理状态。"
|
||||
keywords: ["快速开始", "使用教程", "REPL", "斜杠命令"]
|
||||
og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
|
||||
---
|
||||
|
||||
这篇指南假设你已经按 [安装文档](./installation) 装好了 `ccb` 命令。
|
||||
|
||||
## 启动第一个会话
|
||||
|
||||
在任意项目目录下运行：
|
||||
|
||||
```bash
|
||||
cd my-project
|
||||
ccb
|
||||
```
|
||||
|
||||
首次启动会经过简短的初始化：
|
||||
|
||||
1. **信任确认** — 询问是否信任当前目录的文件读写权限
|
||||
2. **主题选择** — 浅色 / 深色 / 自动
|
||||
3. **登录配置**（首次）— 跳到 `/login`，配置 API（详见 [配置模型供应商](./model-providers)）
|
||||
|
||||
进入 REPL 后会看到：
|
||||
|
||||
```
|
||||
╭─────────────────────────────────────────────╮
|
||||
│ ✻ Welcome to Claude Code Best │
|
||||
│ /help for commands, ctrl+c to exit │
|
||||
╰─────────────────────────────────────────────╯
|
||||
>
|
||||
```
|
||||
|
||||
## 基本对话
|
||||
|
||||
直接输入任何自然语言指令，回车发送：
|
||||
|
||||
```
|
||||
> 看一下这个项目的目录结构，告诉我用的是什么技术栈
|
||||
```
|
||||
|
||||
CCB 会：
|
||||
|
||||
1. 调用 `Glob` / `Read` 工具扫描文件
|
||||
2. 把结果交给模型分析
|
||||
3. 在终端打印回答
|
||||
|
||||
如果模型决定改文件或跑命令，会先弹出**权限确认**对话框：
|
||||
|
||||
```
|
||||
┌─ File Edit ────────────────────────────────┐
|
||||
│ src/foo.ts │
|
||||
│ - export const x = 1 │
|
||||
│ + export const x = 2 │
|
||||
│ │
|
||||
│ ❯ 1. Yes 2. Yes, and don't ask again │
|
||||
│ 3. No │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
按数字键或方向键选择。`2` 会把这类操作加入白名单，后续不再询问。
|
||||
|
||||
## 常用斜杠命令
|
||||
|
||||
| 命令 | 作用 |
|
||||
|------|------|
|
||||
| `/help` | 列出所有可用命令 |
|
||||
| `/login` | 配置 / 切换模型供应商 |
|
||||
| `/clear` | 清空当前会话上下文 |
|
||||
| `/compact` | 手动压缩历史，节省 token |
|
||||
| `/poor` | 切换穷鬼模式（关闭记忆提取和提示建议，省 token） |
|
||||
| `/agents` | 管理自定义 agent |
|
||||
| `/mcp` | 管理 MCP 服务器 |
|
||||
| `/dream` | 手动触发记忆整理 |
|
||||
| `/exit` | 退出 |
|
||||
|
||||
> 🔍 完整命令列表在 REPL 中输入 `/help` 查看。
|
||||
|
||||
## 权限模式
|
||||
|
||||
CCB 有 4 种权限模式，启动时按需选择：
|
||||
|
||||
| 模式 | 行为 |
|
||||
|------|------|
|
||||
| **default** | 每个潜在危险操作都询问（最安全） |
|
||||
| **acceptEdits** | 自动批准文件编辑，其他仍询问 |
|
||||
| **plan** | 只规划不执行（读代码、列出步骤，但不改任何东西） |
|
||||
| **bypassPermissions** | 跳过所有权限检查（**危险**，仅在沙箱里用） |
|
||||
|
||||
切换模式：在 REPL 里按 `Shift+Tab` 循环切换，或启动时 `ccb --permission-mode plan`。
|
||||
|
||||
## 用 Plan 模式做需求分析
|
||||
|
||||
复杂任务建议先用 plan 模式做规划：
|
||||
|
||||
```
|
||||
> 想给这个项目加一个 CI workflow，跑 typecheck 和 test。先告诉我你打算怎么改
|
||||
```
|
||||
|
||||
模型会列出实施计划，你审阅后输入 `/exit-plan-mode` 让它落地。
|
||||
|
||||
详见 [安全与权限 - Plan 模式](../architecture/safety/plan-mode)。
|
||||
|
||||
## 后台任务 / 多 Agent
|
||||
|
||||
CCB 支持把长任务派给后台 agent，主对话不被阻塞：
|
||||
|
||||
```
|
||||
> 帮我跑一遍全量测试，跑完告诉我结果
|
||||
> （自动用 Task tool 在后台执行）
|
||||
```
|
||||
|
||||
后台 agent 状态会显示在底部状态条，用 ↑/↓ 切换查看。详见 [Background Agent Selector](../features/agents/background-agent-selector)。
|
||||
|
||||
## 退出与会话恢复
|
||||
|
||||
- `Ctrl+C` 两次 — 退出 REPL
|
||||
- `ccb --resume` — 恢复上次会话
|
||||
- `ccb --continue` — 继续上次会话并保留全部历史
|
||||
|
||||
会话文件存在 `~/.claude/projects/<project-hash>/` 下。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [配置模型供应商](./model-providers) — 接入第三方 API
|
||||
- [工具系统](../architecture/tools/what-are-tools) — 了解 CCB 有哪些内置工具
|
||||
- [使用指南](../guides/hooks) — 用 Hooks 在工具调用前后注入自定义逻辑
|
||||
Reference in New Issue
Block a user