mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-22 00:05:51 +00:00
docs: 添加文档大纲及 superpowers/outline 目录
Co-Authored-By: deepseek-v4-pro <deepseek-ai@claude-code-best.win>
This commit is contained in:
claude-code-best
210
docs/outline-output/user/01-installation.md
Normal file
210
docs/outline-output/user/01-installation.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# 第一章：从零开始 —— 安装、首次启动与环境要求
|
||||
|
||||
> 把工具装到本机，跑通第一次对话。
|
||||
|
||||
## 我需要先装什么？Bun 与 Node.js 的取舍
|
||||
|
||||
这一份 Claude Code（反编译重建版，下面统一叫 CCB）有两种运行形态，对应两套前置依赖。**普通使用者只需要 Node.js**：通过 npm 装好 `ccb` 命令后，`ccb` 默认就是用 Node.js 跑的（`package.json` 里的 `"ccb": "dist/cli-node.js"`）。Node.js 用 18 或更新的版本即可，没有特别严格的版本要求。
|
||||
|
||||
如果你打算从源码克隆、改代码、跑测试或调试，那需要装 Bun。源码模式对 Bun 版本有硬性要求：`package.json` 的 `engines.bun` 字段写明 `>=1.3.0`，安装文档进一步建议 `bun upgrade` 升到最新，老版本会触发一些奇怪的 BUG（路径解析、热重载偶发失败等）。装 Bun 的方式：
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# Windows (PowerShell)
|
||||
powershell -c "irm bun.sh/install.ps1 | iex"
|
||||
```
|
||||
|
||||
为什么要同时支持两个运行时？源码构建出的产物是同一份 JS（`dist/cli.js` 加几百个 chunk 文件），两个 shebang 入口只是把它喂给不同的解释器：
|
||||
|
||||
- `dist/cli-bun.js` 头部是 `#!/usr/bin/env bun`，启动快、内存占用低（`--version` RSS 大约 35MB）
|
||||
- `dist/cli-node.js` 头部是 `#!/usr/bin/env node`，兼容性更好，不依赖 Bun
|
||||
|
||||
`build.ts` 末尾会自动生成这两个入口，所以你不用纠结——装好哪个运行时就调对应那个命令即可。
|
||||
|
||||
## 三种安装方式：npm 全局、源码 dev、构建产物
|
||||
|
||||
### 方式一：npm 全局安装（最常用）
|
||||
|
||||
一行命令搞定，适合只想把工具用起来的人：
|
||||
|
||||
```sh
|
||||
npm i -g claude-code-best
|
||||
ccb --version # 应输出类似 2.7.0 (Claude Code)
|
||||
```
|
||||
|
||||
装完后会得到三个全局命令：`ccb`（Node 形态，默认推荐）、`ccb-bun`（Bun 形态，启动更快）、`claude-code-best`（与 `ccb` 等价的别名）。日常调用用 `ccb` 就行；如果你的机器装了 Bun 且追求更冷启动，可以试 `ccb-bun`。
|
||||
|
||||
更新到最新版的命令是：
|
||||
|
||||
```sh
|
||||
ccb update
|
||||
```
|
||||
|
||||
> 不推荐 `bun i -g claude-code-best`：bun 全局安装在部分平台有路径冲突。如果一定要用 bun，先跑 `bun pm -g trust claude-code-best @claude-code-best/mcp-chrome-bridge` 解除信任限制。
|
||||
|
||||
### 方式二：源码 dev 模式（贡献者/想折腾的人）
|
||||
|
||||
需要 Bun ≥ 1.3.0：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/claude-code-best/claude-code.git
|
||||
cd claude-code
|
||||
bun install
|
||||
bun run dev
|
||||
```
|
||||
|
||||
`bun run dev` 实际执行的是 `scripts/dev.ts`：它通过 `bun -d MACRO.X:Y` 把版本号等常量在启动时注入，再通过 `--feature <name>` 把 `DEFAULT_BUILD_FEATURES` 列表里的功能开关逐个打开。也就是说，dev 模式默认启用全部功能，最贴近"完整体验"。
|
||||
|
||||
带调试器启动：
|
||||
|
||||
```bash
|
||||
BUN_INSPECT=9229 bun run dev:inspect
|
||||
```
|
||||
|
||||
`BUN_INSPECT` 环境变量被 `scripts/dev.ts` 读取后会自动加上 `--inspect-wait=9229`，浏览器或 VS Code 连上 `chrome://inspect` 即可断点调试。
|
||||
|
||||
一次性管道调用：
|
||||
|
||||
```bash
|
||||
echo "say hello" | bun run src/entrypoints/cli.tsx -p
|
||||
```
|
||||
|
||||
### 方式三：构建产物
|
||||
|
||||
把源码编出 `dist/` 目录，之后既可以用 bun 也可以用 node 跑：
|
||||
|
||||
```bash
|
||||
bun run build # 默认走 Bun.build，输出 dist/cli.js + chunks/
|
||||
# 或
|
||||
bun run build:vite # 备选 Vite 链，chunk 体积更小
|
||||
|
||||
node dist/cli.js --version
|
||||
```
|
||||
|
||||
`build.ts` 做了四件事：用 `Bun.build` 切分代码（`splitting: true`），把 `import.meta.require` 改写成 Node 兼容版本，给第三方依赖里 `var { x } = globalThis.Bun` 这类解构加 `typeof` 守卫，再把 `vendor/audio-capture/` 和 `src/utils/vendor/ripgrep/` 拷到 `dist/vendor/` 下。
|
||||
|
||||
## 第一次启动会发生什么：trust dialog、init 流程
|
||||
|
||||
进入任意项目目录后启动：
|
||||
|
||||
```bash
|
||||
cd my-project
|
||||
ccb
|
||||
```
|
||||
|
||||
第一次（或换了新目录）会依次经过这几个阶段：
|
||||
|
||||
**1. 信任对话框（Trust Dialog）**
|
||||
|
||||
弹出一个红框问你 "Is this a project you trust?"，下面列出当前目录绝对路径，选项只有两个：
|
||||
|
||||
- `Yes, I trust this folder` —— 把"已信任"标记写到当前项目的 `.claude/settings.json`（`hasTrustDialogAccepted: true`），之后这个目录不再询问
|
||||
- `No, exit` —— 直接退出，进程返回码 1
|
||||
|
||||
这一步不是仪式感的，它真在守门：在用户确认信任之前，CLAUDE.md 预读、系统上下文预取、MCP server 拉起等副作用统统不会跑。`src/main.tsx` 里通过 `checkHasTrustDialogAccepted()` 判断，未信任时只 prefetch 安全内容。源码在 `src/components/TrustDialog/TrustDialog.tsx`。
|
||||
|
||||
**2. 初始化（init）**
|
||||
|
||||
信任通过后，`src/entrypoints/init.ts` 的 `init()` 接管。它会：启用配置系统（`enableConfigs`）、应用 `.claude/settings.json` 里的环境变量（先应用"安全"子集，再在信任后应用全集）、配置代理与 mTLS、初始化 Sentry 与 Langfuse（没配 key 就是 no-op）、对 Anthropic API 做 TCP+TLS 预连接（重叠 100~200ms 握手时间）。`init()` 用 `lodash-es/memoize` 包了一层，整个进程只会跑一次。
|
||||
|
||||
**3. 进入 REPL**
|
||||
|
||||
最后渲染欢迎框：
|
||||
|
||||
```
|
||||
╭─────────────────────────────────────────────╮
|
||||
│ ✻ Welcome to Claude Code Best │
|
||||
│ /help for commands, ctrl+c to exit │
|
||||
╰─────────────────────────────────────────────╯
|
||||
>
|
||||
```
|
||||
|
||||
第一次还没配 API 的话，发任何消息都会被引导去 `/login` 配置 Provider（见第二章）。
|
||||
|
||||
## 快速路径命令一览
|
||||
|
||||
`src/entrypoints/cli.tsx` 的 `main()` 按优先级串了十几条"快速路径"，意图是让某些子命令几乎零模块加载就返回，避免动辄加载几 MB 代码。
|
||||
|
||||
最常用、最快的就是看版本：
|
||||
|
||||
```bash
|
||||
ccb --version
|
||||
# 或
|
||||
ccb -v
|
||||
```
|
||||
|
||||
`cli.tsx` 第 80 行的判断只匹配参数数量为 1 且就是 `--version` / `-v` / `-V`，命中后直接 `console.log` MACRO 里编译期注入的版本号就 return，**完全不加载任何其他模块**。版本号的单一来源是 `package.json`（`scripts/defines.ts` 的 `getMacroDefines()` 读它注入 `MACRO.VERSION`），避免多处写死产生漂移。
|
||||
|
||||
其他快速路径包括：
|
||||
|
||||
```bash
|
||||
ccb --dump-system-prompt # 输出渲染后的系统提示（feature-gated，外部构建会被 DCE 掉）
|
||||
ccb --computer-use-mcp # 启动 Computer Use MCP server 模式
|
||||
ccb --chrome-native-host # Chrome native messaging host 模式
|
||||
ccb remote-control # Bridge / Remote Control 模式（也叫 rc / remote / sync / bridge）
|
||||
ccb daemon start # Daemon 长驻模式
|
||||
ccb ps / logs / attach / kill # 后台会话管理
|
||||
ccb --resume # 恢复上次会话
|
||||
ccb -c # 继续当前目录最近一次会话
|
||||
```
|
||||
|
||||
完整子命令列表在 `src/main.tsx`（Commander.js 注册），想看自己关心的命令用法：
|
||||
|
||||
```bash
|
||||
ccb --help
|
||||
ccb mcp --help
|
||||
ccb doctor --help
|
||||
```
|
||||
|
||||
## 把 `ccb` 设为全局命令：`cli-bun.js` 与 `cli-node.js` 双入口
|
||||
|
||||
如果走 npm 全局安装，`ccb` 命令已经自动注册好。如果走源码模式想让全局也能直接调，可以手动把 `dist/cli-bun.js` 或 `dist/cli-node.js` 软链到 PATH 里。两个入口内容极简：
|
||||
|
||||
```js
|
||||
// dist/cli-bun.js
|
||||
#!/usr/bin/env bun
|
||||
import "./cli.js"
|
||||
|
||||
// dist/cli-node.js
|
||||
#!/usr/bin/env node
|
||||
import "./cli.js"
|
||||
```
|
||||
|
||||
实际逻辑都在 `dist/cli.js`（以及几百个按需加载的 chunk）。两个入口只是换运行时，`build.ts` 最后用 `chmodSync(path, 0o755)` 给它们加了可执行位。
|
||||
|
||||
选哪个？机器装了 Bun 就用 `cli-bun.js`（启动更快、内存占用更低，`--version` 的 RSS 实测从 966MB 降到 35MB），没装或不想装就用 `cli-node.js`（兼容性更好）。注意 `package.json` 里的 `"bin"` 字段默认把 `ccb` 指向 `dist/cli-node.js`——也就是说普通用户拿到的是 Node 版本，想用 Bun 版本要么显式调 `ccb-bun`，要么自己改 bin。
|
||||
|
||||
## 环境自检：`ccb doctor`
|
||||
|
||||
`ccb doctor`（在 `src/main.tsx` 第 5282 行注册）是一个独立的健康检查子命令，会跳过信任对话框、跳过启动 `setup()`，专门用来诊断安装状态。它渲染的是 `src/screens/Doctor.tsx`，列出：
|
||||
|
||||
- 当前版本号、npm 上最新版本与稳定版本（通过 `getNpmDistTags()` 拉取）
|
||||
- 安装类型（`native` 还是 npm 全局）
|
||||
- 当前生效的设置文件路径与解析错误
|
||||
- MCP server 连接状态、agent 定义加载情况
|
||||
- 沙箱状态（`SandboxDoctorSection`）
|
||||
- 文件锁状态（`getAllLockInfo`、`cleanupStaleLocks`）
|
||||
|
||||
跑一次：
|
||||
|
||||
```bash
|
||||
ccb doctor
|
||||
```
|
||||
|
||||
它的描述里有句重要警告："The workspace trust dialog is skipped and stdio servers from .mcp.json are spawned for health checks. Only use this command in directories you trust."（信任对话框被跳过，stdio 类 MCP server 会被拉起做检查，**只在信任的目录里跑**）。
|
||||
|
||||
升级到最新版：
|
||||
|
||||
```bash
|
||||
ccb update
|
||||
```
|
||||
|
||||
`ccb update` 对应 `src/cli/updateCCB.ts`：先看当前是不是 bun 装的（看 `process.execPath` 是不是落在 bun 的全局路径），是的话用 `bun update -g`，否则用 `npm install -g`。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想配 API（Anthropic / OpenAI 兼容 / Gemini / Grok / 国产大模型），看 [第二章：让 Claude 听你的 —— 配置 Provider 与模型](./02-providers.md)
|
||||
- 想直接发消息、看流式回复、切权限模式，看 [第三章：日常对话 —— 交互式 REPL 怎么用](./03-repl.md)
|
||||
- 想知道有哪些 slash 命令、按场景找，看 [第四章：slash 命令速查](./04-slash-commands.md)
|
||||
239
docs/outline-output/user/02-providers.md
Normal file
239
docs/outline-output/user/02-providers.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# 第二章：让 Claude 听你的 —— 配置 Provider 与模型
|
||||
|
||||
> 把 CCB 接到你自己想用的那家 API 上：怎么选、怎么切、为什么没生效。
|
||||
|
||||
## 一张表看懂 7 个 Provider
|
||||
|
||||
CCB 不绑定 Anthropic 官方账号，内置了 7 条 API 通道。`src/commands/provider.ts` 里硬编码的有效值就这 7 个，对应 `/provider <name>` 能接的参数：
|
||||
|
||||
| Provider | `modelType` 值 | 适合谁 |
|
||||
|----------|---------------|--------|
|
||||
| Anthropic 官方 | `anthropic`（默认，内部叫 `firstParty`） | 有 Anthropic API key 或 Claude 订阅的人 |
|
||||
| OpenAI 兼容 | `openai` | DeepSeek、Ollama、vLLM、智谱、通义、Moonshot、Cerebras、Groq 等任何 OpenAI Chat Completions 协议端点 |
|
||||
| Gemini | `gemini` | Google Gemini 系列 |
|
||||
| Grok | `grok` | xAI Grok 系列（`GROK_API_KEY` 或 `XAI_API_KEY` 都行） |
|
||||
| Bedrock | `bedrock` | AWS 用户，走 `CLAUDE_CODE_USE_BEDROCK=1`，依赖 `AWS_REGION` 等 |
|
||||
| Vertex | `vertex` | Google Cloud 用户，走 `CLAUDE_CODE_USE_VERTEX=1`，需要 `ANTHROPIC_VERTEX_PROJECT_ID` 等 |
|
||||
| Foundry | `foundry` | Azure AI Foundry 用户，走 `CLAUDE_CODE_USE_FOUNDRY=1`，需要 `ANTHROPIC_FOUNDRY_*` 系列 |
|
||||
|
||||
注意一个区别：`anthropic` / `openai` / `gemini` / `grok` 这四个会落到 `~/.claude/settings.json` 的 `modelType` 字段持久化；`bedrock` / `vertex` / `foundry` 三个云厂商只设环境变量，**不写 `settings.json`**——源码注释明确写了 "cloud providers controlled solely by env vars"。
|
||||
|
||||
想知道当前生效的是哪个：
|
||||
|
||||
```
|
||||
/provider
|
||||
Current API provider: openai
|
||||
```
|
||||
|
||||
## 三种切换方式：`/provider`、`/login`、环境变量
|
||||
|
||||
同一个目标有三条路，按你的场景选。
|
||||
|
||||
**`/provider <name>` 最直接**——一行命令立刻切换，写入 `settings.json`。比如刚配完 DeepSeek 的环境变量，想切过去：
|
||||
|
||||
```
|
||||
/provider openai
|
||||
API provider set to openai.
|
||||
```
|
||||
|
||||
它还会顺手做体检：切到 `openai` 时如果缺 `OPENAI_API_KEY` 或 `OPENAI_BASE_URL`，会返回 warning 而不是直接报错；切到 `gemini` 缺 `GEMINI_API_KEY` 同理。切到 `grok` 时接受 `GROK_API_KEY` 或 `XAI_API_KEY` 任一存在即可。
|
||||
|
||||
**`/login` 是引导式表单**——会弹出一个交互界面（`ConsoleOAuthFlow` 组件），让你按栏目填字段、选预设。对第一次配的人最友好，特别是接国产大模型（见下一节）。它除了填表单，还会触发一连串副作用：重置 cost state、刷新 GrowthBook feature flags、清掉 trusted device token 再重新 enroll、把 `authVersion` 自增让其他 hook 重新拉数据。所以 `/login` 不只是"写个 key"那么简单。
|
||||
|
||||
**环境变量是 CI/自动化场景的玩法**——所有 provider 都有对应的 `CLAUDE_CODE_USE_*` 开关，写到 shell 配置或 `.envrc` 里，`ccb` 启动时自动生效：
|
||||
|
||||
```bash
|
||||
# 临时用 DeepSeek 跑一个会话，不污染全局配置
|
||||
CLAUDE_CODE_USE_OPENAI=1 OPENAI_API_KEY=sk-xxx \
|
||||
OPENAI_BASE_URL=https://api.deepseek.com/v1 \
|
||||
OPENAI_MODEL=deepseek-chat ccb
|
||||
```
|
||||
|
||||
三条路里**优先级在 `src/utils/model/providers.ts` 的 `getAPIProvider()`** 里写死：先看 `settings.modelType`（`/provider` 写进去的），再看 `CLAUDE_CODE_USE_BEDROCK/VERTEX/FOUNDRY`，再看 `CLAUDE_CODE_USE_OPENAI/GEMINI/GROK`，最后 fallback 到 `firstParty`。这个顺序解释了下一个排错点。
|
||||
|
||||
## 中国 LLM 引导式登录：DeepSeek、智谱、通义、小米 MiMo
|
||||
|
||||
`/login` 走 "China LLM" 栏目时会用上 `src/utils/chinaLlmProviders.ts` 里的预设表。这张表内置了四家：
|
||||
|
||||
- **DeepSeek** — `https://api.deepseek.com`，注册送 5M tokens（30 天），最便宜。模型有 `deepseek-v4-pro`（推荐）、`deepseek-v4-flash`（快）。
|
||||
- **智谱 GLM** — `https://open.bigmodel.cn/api/paas/v4`，`GLM-4.7-Flash` 永久免费，有 Coding Plan（Lite ¥72/mo、Pro ¥216/mo、Max ¥576/mo）。
|
||||
- **通义千问** — `https://dashscope.aliyuncs.com/compatible-mode/v1`，开通后 90 天免费 tier，Coding Plan ¥200/mo。
|
||||
- **小米 MiMo** — `https://api.xiaomimimo.com/v1`，1M 上下文，Token Plan 四档（Lite ¥39/mo 起）。
|
||||
|
||||
预设表的好处是：你不用记 base URL、不用查 key 怎么申请、不用猜模型 ID。表单里每个 provider 都带 `apiKeyPage` 字段，直接给你跳转申请 key 的链接；每个模型还标了输入/输出每百万 token 的价格、上下文窗口、推荐 tag。选 Coding Plan 模式时，`resolveChinaProviderBaseURL()` 会自动把 base URL 切到对应 coding endpoint（比如智谱切到 `https://open.bigmodel.cn/api/coding/paas/v4`），key 格式也会提示（如 `tp-...`、`sk-sp-...`）。
|
||||
|
||||
填完表单后写入 `~/.claude/settings.json` 的 `env` 字段并触发 `applyConfigEnvironmentVariables()`，不用重启 `ccb`。
|
||||
|
||||
## 用 ChatGPT 订阅当后端：设备码流程与凭证存储
|
||||
|
||||
如果你有 ChatGPT 订阅，可以让 CCB 直接走 ChatGPT 账号体系，而不是去 OpenAI 平台申请 API key。这套实现在 `src/services/api/openai/chatgptAuth.ts`。
|
||||
|
||||
启用方式是设置 `OPENAI_AUTH_MODE=chatgpt`（同时把 provider 切到 `openai`）。CCB 会启动 OAuth 设备码流程：调 `https://auth.openai.com/api/accounts/deviceauth/usercode` 拿一个 `user_code` 和验证 URL，你在浏览器里打开 `https://auth.openai.com/codex/device` 输入这个 code 完成登录，CCB 这边轮询 `/api/accounts/deviceauth/token`（最多 15 分钟，每 5 秒一次）拿回 authorization code，再换成 `id_token` / `access_token` / `refresh_token` 三件套。
|
||||
|
||||
凭证默认存到 `~/.claude/openai-chatgpt-auth.json`（文件权限 `0600`）。**值得注意的兼容点**：如果那个文件不存在，CCB 会 fallback 读 `~/.codex/auth.json`（即 Codex CLI 的凭证文件，路径由 `CODEX_HOME` 环境变量控制，默认 `~/.codex`）。源码里有句日志：`[OpenAI] Using ChatGPT auth from Codex auth.json`。这意味着你在 Codex CLI 登过的账号，CCB 可以无缝接用。
|
||||
|
||||
刷新偏差窗口是 `REFRESH_SKEW_MS = 5 * 60 * 1000`，即 5 分钟。`getValidChatGPTAuth()` 每次被调用时检查 access_token 的 JWT `exp` 字段，如果距离过期不到 5 分钟就主动 refresh，避免请求途中 token 失效。
|
||||
|
||||
## 每个 Provider 需要哪些环境变量
|
||||
|
||||
下面这张清单是从源码逐个挖出来的，配的时候照着对一遍就不会漏。
|
||||
|
||||
**OpenAI 兼容**（`src/services/api/openai/client.ts`）：
|
||||
|
||||
- `OPENAI_API_KEY` — 必填
|
||||
- `OPENAI_BASE_URL` — 强烈推荐，比如 `http://localhost:11434/v1`（Ollama）
|
||||
- `OPENAI_ORG_ID`、`OPENAI_PROJECT_ID` — 可选
|
||||
- `OPENAI_AUTH_MODE=chatgpt` — 走 ChatGPT 订阅模式时设
|
||||
- `OPENAI_MODEL` — 指定模型 ID（可选，不设 CCB 自己选档位）
|
||||
|
||||
**Gemini 兼容**（`packages/@ant/model-provider/src/providers/gemini/modelMapping.ts`）：
|
||||
|
||||
- `GEMINI_API_KEY` — 必填，没有就 `resolveGeminiModel()` 会直接 throw
|
||||
- `GEMINI_MODEL` — 直接指定模型（最高优先级）
|
||||
- `GEMINI_DEFAULT_SONNET_MODEL` / `GEMINI_DEFAULT_OPUS_MODEL` / `GEMINI_DEFAULT_HAIKU_MODEL` — 按 anthropic 模型族映射
|
||||
- `ANTHROPIC_DEFAULT_SONNET_MODEL` 等 — 向后兼容（已废弃但仍读）
|
||||
|
||||
**Grok 兼容**（`src/services/api/grok/client.ts` + `modelMapping.ts`）：
|
||||
|
||||
- `GROK_API_KEY` 或 `XAI_API_KEY` — 任一即可，前者优先
|
||||
- `GROK_BASE_URL` — 可选，默认 `https://api.x.ai/v1`
|
||||
- `GROK_MODEL` — 直接指定（最高优先级）
|
||||
- `GROK_DEFAULT_OPUS_MODEL` 等 — 按 family 映射
|
||||
- `GROK_MODEL_MAP` — JSON 字符串，一次性传完整映射表
|
||||
|
||||
**Bedrock / Vertex / Foundry**：依赖各家 SDK 的标准环境变量（`AWS_REGION`、`ANTHROPIC_VERTEX_PROJECT_ID`、`ANTHROPIC_FOUNDRY_*`），CCB 自己不额外定义。
|
||||
|
||||
## 模型映射是怎么决定的
|
||||
|
||||
CCB 内部统一用 Anthropic 的模型名（`claude-sonnet-4-6`、`claude-opus-4-6`、`claude-haiku-4-5-20251001` 等）做调度，落到具体 provider 时再做一次映射。映射函数遵循同一条优先级链：
|
||||
|
||||
1. `PROVIDER_MODEL`（如 `GEMINI_MODEL`、`GROK_MODEL`、`OPENAI_MODEL`）——直接写死，最高优先级
|
||||
2. `PROVIDER_DEFAULT_{FAMILY}_MODEL`——按 sonnet / opus / haiku 三个 family 分别覆盖
|
||||
3. `ANTHROPIC_DEFAULT_{FAMILY}_MODEL`——向后兼容的共享环境变量
|
||||
4. 内置默认表（Grok 在 `modelMapping.ts` 里有硬编码表，比如 opus family 默认映射到 `grok-4.20-reasoning`）
|
||||
|
||||
举两个具体例子。Gemini 路径下如果你只设了 `GEMINI_DEFAULT_SONNET_MODEL=gemini-2.5-flash`，那么 CCB 调用 sonnet 时会用 flash，调用 opus 时会因为找不到映射抛错：`Gemini provider requires GEMINI_MODEL or GEMINI_DEFAULT_OPUS_MODEL (or ANTHROPIC_DEFAULT_OPUS_MODEL for backward compatibility) to be configured.`。
|
||||
|
||||
Grok 路径下，没设任何 `GROK_*` 时走默认表：opus family → `grok-4.20-reasoning`，sonnet/haiku family → `grok-3-mini-fast`。模型名带 `[1m]` 后缀（1M 上下文标记）会在映射前被 `replace(/\[1m\]$/, '')` 剥掉。
|
||||
|
||||
## 为什么切了 Provider 没生效
|
||||
|
||||
这是 issue 区最高频的困惑之一，根因几乎都在 `getAPIProvider()` 的优先级上。
|
||||
|
||||
**`settings.modelType` 优先于环境变量**。如果你之前用过 `/provider openai`，那 `~/.claude/settings.json` 里就写死了 `"modelType": "openai"`。后来你想换回 Anthropic 官方，只在 shell 里 `unset CLAUDE_CODE_USE_OPENAI`——没用，因为 settings 的优先级更高。正确做法是用 `/provider unset`，它会清掉 `modelType` 字段并删除所有 `CLAUDE_CODE_USE_*` 环境变量：
|
||||
|
||||
```
|
||||
/provider unset
|
||||
API provider cleared (will use environment variables).
|
||||
```
|
||||
|
||||
注意 `/provider unset` **只清 Provider，不清 API key**。`OPENAI_API_KEY`、`GEMINI_API_KEY` 这些是独立保留的，你想彻底换 provider 还得自己清 key。
|
||||
|
||||
**`isFirstPartyAnthropicBaseUrl()` 有个 TODO 陷阱**（`src/utils/model/providers.ts:43`）。这个函数判断当前是不是走 Anthropic 官方 endpoint，逻辑是看 `ANTHROPIC_BASE_URL` 有没有设、设的是不是 `api.anthropic.com`。但 TODO 注释明确写了："这里会有问题, 只配置了 openai 协议的用户, 按理说会为 true 导致问题"。意思是：如果你只设了 `OPENAI_BASE_URL`（指向 DeepSeek）但没设 `ANTHROPIC_BASE_URL`，这个函数会返回 `true`（因为 `ANTHROPIC_BASE_URL` 未设默认 firstParty），让下游某些 firstParty 专属的行为（比如特定 betas 头）泄漏到 OpenAI 兼容路径上。如果遇到奇怪的请求被拒，先检查这个。
|
||||
|
||||
## 我改了 API key 但没生效
|
||||
|
||||
另一个高频坑，根因是模块级 client cache。
|
||||
|
||||
`getOpenAIClient()`（`src/services/api/openai/client.ts:39`）和 `getGrokClient()`（`src/services/api/grok/client.ts`）都是单例缓存：第一次调用时读 `process.env.OPENAI_API_KEY` / `OPENAI_BASE_URL` 构造一个 OpenAI SDK 实例，存到模块级变量 `cachedClient`，之后所有调用直接复用这个实例。
|
||||
|
||||
```ts
|
||||
// client.ts 的核心逻辑
|
||||
let cachedClient: OpenAI | null = null
|
||||
export function getOpenAIClient(): OpenAI {
|
||||
if (cachedClient) return cachedClient
|
||||
// ... 读 env、new OpenAI(...)
|
||||
cachedClient = client
|
||||
return client
|
||||
}
|
||||
```
|
||||
|
||||
这意味着：你在 REPL 里改了 `process.env.OPENAI_API_KEY`（或通过 `/login` 重写了 `settings.json` 的 env），但当前会话的 client 实例还是用旧 key 构造的——下一次请求还是旧 key。两种解法：
|
||||
|
||||
1. **重启 `ccb`**——最简单粗暴，所有模块级 cache 自然清空
|
||||
2. **调用 `clearOpenAIClientCache()` / `clearGrokClientCache()`**——程序化清缓存，但你没法在 REPL 里直接调，需要走 `/login` 这类会触发完整副作用的路径
|
||||
|
||||
`/login` 命令的 `onDone` 回调里调了 `context.onChangeAPIKey()`，这个 hook 会负责让下游感知 key 变了。所以**改 key 的正确姿势是走 `/login`，而不是手改 `settings.json` 后期望立刻生效**。
|
||||
|
||||
## 本地模型与自托管端点
|
||||
|
||||
CCB 的 OpenAI 兼容层对本地模型特别友好，因为 Ollama、vLLM、LM Studio 这些工具都暴露 OpenAI Chat Completions 协议。
|
||||
|
||||
**Ollama**（本地跑 Llama、Qwen 等）：
|
||||
|
||||
```bash
|
||||
# 先启动 ollama 并 pull 一个模型
|
||||
ollama serve &
|
||||
ollama pull qwen2.5-coder:32b
|
||||
|
||||
# 让 CCB 用它
|
||||
export CLAUDE_CODE_USE_OPENAI=1
|
||||
export OPENAI_API_KEY=ollama # ollama 不校验 key，随便填
|
||||
export OPENAI_BASE_URL=http://localhost:11434/v1
|
||||
export OPENAI_MODEL=qwen2.5-coder:32b
|
||||
ccb
|
||||
```
|
||||
|
||||
**vLLM**（自托管推理引擎）：把 `OPENAI_BASE_URL` 指向你的 vLLM server（默认 `http://localhost:8000/v1`），`OPENAI_MODEL` 填你启动 vLLM 时 `--model` 传的名字。
|
||||
|
||||
**DeepSeek 自托管**：跟官方 API 一样走 OpenAI 兼容，区别只是 base URL。注意思维模式的请求体格式跟官方 API 略有不同（见下一节）。
|
||||
|
||||
本地模型的两个实用环境变量：
|
||||
|
||||
- `OPENAI_MAX_TOKENS` —— 显卡显存不够时强制限制 max output tokens（比如 RTX 3060 12GB 跑 65536-token 模型会 OOM，调小这个）
|
||||
- `API_TIMEOUT_MS` —— 默认 600000（10 分钟），本地模型推理慢的话可以调大
|
||||
|
||||
## DeepSeek 思维模式：三格式注入与空字符串回显
|
||||
|
||||
DeepSeek 系列模型（`deepseek-reasoner`、`deepseek-v3`、`deepseek-v4`、`deepseek-chat`、`deepseek-coder`、`deepseek-r1` 等，凡是模型名包含 `deepseek` 的）会自动启用思维模式。检测逻辑在 `src/services/api/openai/requestBody.ts:21` 的 `isOpenAIThinkingEnabled()`：
|
||||
|
||||
```ts
|
||||
return modelLower.includes('deepseek') || modelLower.includes('mimo')
|
||||
```
|
||||
|
||||
想强制关掉？设 `OPENAI_ENABLE_THINKING=0`。想给非 DeepSeek 模型强制开？设 `OPENAI_ENABLE_THINKING=1`。
|
||||
|
||||
启用思维模式后，CCB 会在请求体里**同时塞三种格式**，因为不同 endpoint 认不同的字段，互不冲突：
|
||||
|
||||
```ts
|
||||
...(enableThinking && {
|
||||
thinking: { type: 'enabled' }, // 官方 DeepSeek API
|
||||
enable_thinking: true, // 自托管 DeepSeek-V3.2
|
||||
chat_template_kwargs: { thinking: true, enable_thinking: true }, // 自托管 + MiMo
|
||||
}),
|
||||
```
|
||||
|
||||
这里有个反直觉但关键的细节：**必须把 `reasoning_content: ''`（空字符串）原样回显回去**。DeepSeek v4 在思维模式下，如果模型直接回答（不思考），会在 assistant message 里返回 `reasoning_content: ""`（空字符串而非缺失）。下一次请求必须把这个空字符串原样传回去，否则 DeepSeek 返回 400：`reasoning_content ... must be passed back`。
|
||||
|
||||
这套回显策略在 `src/services/providerRegistry/providerCompatMatrix.ts` 里按 provider 分了三档：
|
||||
|
||||
- `always-preserve`（DeepSeek）——总是保留，包括空字符串
|
||||
- `drop-on-non-thinking`（permissive 默认）——非思维模型时丢掉
|
||||
- `strip`（Cerebras / Groq / strict-openai）——总是丢掉
|
||||
|
||||
所以同一份对话历史，发给 DeepSeek 时带 `reasoning_content`，发给 Groq 时被剥得干干净净，互不污染。
|
||||
|
||||
## `/effort` 与 `CLAUDE_CODE_EFFORT_LEVEL`：思考强度的四档
|
||||
|
||||
`/effort` 控制模型在回答前思考多久。`src/commands/effort/effort.tsx` 接受的参数：`low` / `medium` / `high` / `xhigh` / `max` / `auto`。`EFFORT_LEVELS` 在 `src/utils/effort.ts` 里写死是 `['low', 'medium', 'high', 'xhigh', 'max']`（注意 `max` 对外部用户是 session-only，不持久化；只有 `USER_TYPE === 'ant'` 才能 persist）。
|
||||
|
||||
```
|
||||
/effort low # Quick, straightforward implementation with minimal overhead
|
||||
/effort medium # Balanced approach with standard implementation and testing
|
||||
/effort high # Comprehensive implementation with extensive testing
|
||||
/effort xhigh # Extended reasoning beyond high, short of max
|
||||
/effort max # Maximum capability with deepest reasoning
|
||||
/effort auto # 跟随模型默认
|
||||
```
|
||||
|
||||
`CLAUDE_CODE_EFFORT_LEVEL` 环境变量覆盖一切，优先级最高。它还接受 `unset` / `auto` 两个特殊值表示"别发 effort 参数"。设了环境变量再跑 `/effort medium`，CCB 会告诉你："Not applied: CLAUDE_CODE_EFFORT_LEVEL=xxx overrides effort this session"。
|
||||
|
||||
落地到 ChatGPT 订阅模式（`OPENAI_AUTH_MODE=chatgpt` + 走 Responses API）时，`src/services/api/openai/responsesAdapter.ts` 把 effort 映射成 `reasoning.effort` 参数。Responses API 只认四档（`'low' | 'medium' | 'high' | 'xhigh'`），所以 `/effort max` 在 ChatGPT 模式下会被 `resolveAppliedEffort()` 降级为 `xhigh`（源码注释："Keep /effort max usable as a familiar alias in ChatGPT subscription mode"）。
|
||||
|
||||
不是所有模型都支持 effort。`modelSupportsEffort()` 在 `src/utils/effort.ts:34` 里维护白名单，目前包含 `opus-4-7`、`opus-4-6`、`sonnet-4-6`、`deepseek-v4-pro`，以及 ChatGPT Codex 推理模型。设 `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1` 可以强制全开（自担 API 报错风险）。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想知道日常发消息、看流式回复、切权限模式怎么操作，看 [第三章：日常对话 —— 交互式 REPL 怎么用](./03-repl.md)
|
||||
- 想按场景查 slash 命令（`/clear`、`/compact`、`/cost` 等），看 [第四章：slash 命令速查](./04-slash-commands.md)
|
||||
- 想接入 MCP server、装插件、写 Skill，看 [第五章：扩展 Claude 的能力](./05-extensions.md)
|
||||
184
docs/outline-output/user/03-repl-daily.md
Normal file
184
docs/outline-output/user/03-repl-daily.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# 第三章：日常对话 -- 交互式 REPL 怎么用
|
||||
|
||||
> 装好 Claude Code 之后，每天打开它会做什么、怎么用。
|
||||
|
||||
## 发消息、看回复、中断与退出
|
||||
|
||||
启动 `claude` 之后，你会看到一个输入框。直接输入你想说的话，按 Enter 发送。Claude 的回复会以流式文本逐字出现，就像在聊天。
|
||||
|
||||
如果你中途觉得方向不对，想停下来，按 **Esc** 可以中断当前正在生成的回复。中断后，已输出的部分仍然保留在对话里，你可以换个方向继续追问。如果 Claude 正在调用某个工具（比如读文件或执行命令），Esc 也会中断工具执行。
|
||||
|
||||
想要彻底退出 REPL，按 **Ctrl+C**。第一次按会尝试中断当前任务，再次按会退出程序。
|
||||
|
||||
你也可以在非交互场景下使用 pipe 模式，一次性发送问题并获取结果：
|
||||
|
||||
```bash
|
||||
echo "解释一下 package.json 里的 scripts 字段" | claude -p
|
||||
```
|
||||
|
||||
这种模式下不需要启动完整的交互界面，适合脚本调用和快速提问。
|
||||
|
||||
## 会话持久化：恢复、历史与清空
|
||||
|
||||
Claude Code 会把每次对话自动保存为会话日志。下次你想继续上次的对话，有几种方式。
|
||||
|
||||
**恢复上次对话**：直接在输入框里输入 `/resume`，会弹出一个历史会话列表，你可以按时间或项目筛选。也可以在启动时直接恢复：
|
||||
|
||||
```bash
|
||||
# 恢复当前项目最近的对话
|
||||
claude --continue
|
||||
|
||||
# 恢复指定会话 ID 的对话
|
||||
claude --resume <session-id>
|
||||
|
||||
# 恢复时创建新的会话 ID（不影响原始会话）
|
||||
claude --continue --fork-session
|
||||
```
|
||||
|
||||
`--continue`（简写 `-c`）恢复当前目录下最近一次对话，`--resume` 可以指定会话 ID 或搜索关键词。
|
||||
|
||||
**查看历史**：输入 `/history`（别名 `/hist`）可以浏览所有历史会话，包括跨项目的记录。
|
||||
|
||||
**清空当前上下文**：如果对话太长、上下文窗口快满了，输入 `/clear`（别名 `/reset`、`/new`）会清空当前对话历史，从零开始。这不会删除会话日志，只是释放当前上下文窗口。
|
||||
|
||||
## 切换模型与思考强度
|
||||
|
||||
不同的任务适合不同的模型。你可以随时在对话中切换。
|
||||
|
||||
**切换模型**：输入 `/model`，后面跟模型名称即可。不传参数时会显示当前使用的模型：
|
||||
|
||||
```
|
||||
/model claude-sonnet-4-20250514
|
||||
/model opus
|
||||
```
|
||||
|
||||
模型名称支持简写。切换后立即生效，下一轮对话就会使用新模型。
|
||||
|
||||
**调整思考强度**：用 `/effort` 命令控制 Claude 的推理深度：
|
||||
|
||||
```
|
||||
/effort low # 快速响应，适合简单问题
|
||||
/effort medium # 默认，平衡速度和质量
|
||||
/effort high # 深度思考，适合复杂任务
|
||||
/effort xhigh # 扩展推理，超过 high 但不到 max
|
||||
/effort max # 最大推理强度（外部用户为会话级，不持久化）
|
||||
/effort auto # 让系统自动决定
|
||||
```
|
||||
|
||||
设置会持久化到用户配置，下次启动仍然生效。你也可以通过环境变量 `CLAUDE_CODE_EFFORT_LEVEL` 设置。
|
||||
|
||||
**ultrathink 触发词**：当 `ULTRATHINK` feature 启用时，在输入中包含 `ultrathink` 关键词会自动将本轮对话的思考强度提升到 `high`。这是一种"按需激活"的方式，不需要提前切换 `/effort`，只需在需要深度思考的那一轮输入里写上 ultrathink 即可。
|
||||
|
||||
## 权限模式切换
|
||||
|
||||
Claude Code 执行文件读写、Shell 命令等操作时，默认会逐个询问你是否允许。你可以通过 `/mode` 命令切换交互模式来调整这个行为。
|
||||
|
||||
输入 `/mode` 后会弹出一个选择器，可用的模式包括：
|
||||
|
||||
- `default` -- 标准模式，每次工具调用都需要确认
|
||||
- `gentle` -- 更温和的交互风格
|
||||
- `sharp` -- 精简直接
|
||||
- `workhorse` -- 工作流优化，减少不必要的确认
|
||||
- `token-saver` -- 节省 token 消耗
|
||||
- `super-ai` -- 高自主性模式
|
||||
|
||||
模式切换会立即生效并持久化到配置中。选择哪种模式取决于你的信任程度和任务类型：在做探索性任务时可以用更自主的模式，在操作关键文件时切回 default。
|
||||
|
||||
## 查看 token 消耗与费用
|
||||
|
||||
想知道这一轮对话花了多少钱、用了多少 token，输入 `/usage`（别名 `/cost` 或 `/stats`）。
|
||||
|
||||
```
|
||||
/usage
|
||||
```
|
||||
|
||||
这会显示当前会话的费用估算、token 使用量、以及计划限额的剩余情况。对于有 rate limit 的 Provider，还会显示限流相关状态。
|
||||
|
||||
费用追踪基于 API 响应中的 usage 字段实时计算，每个 Provider 的计费方式不同，但 `/usage` 会统一展示。
|
||||
|
||||
## 上下文管理与自动压缩
|
||||
|
||||
长时间对话会让上下文窗口越来越满。Claude Code 有几种机制来管理这个问题。
|
||||
|
||||
**手动压缩**：输入 `/compact` 可以触发上下文压缩。Claude 会把之前的对话总结成一段摘要，释放上下文空间但保留关键信息。你也可以附上自定义的压缩指令：
|
||||
|
||||
```
|
||||
/compact 重点保留代码修改相关的讨论
|
||||
```
|
||||
|
||||
系统在上下文接近上限时也会自动触发 compact，无需手动干预。
|
||||
|
||||
**强制剪裁**：输入 `/force-snip` 会在当前位置插入一个剪裁边界。边界之前的所有消息将从下一轮对话的模型视角中移除，但 REPL 的 UI 滚动历史仍然保留，你仍然可以往回翻看。与 `/compact` 不同，`/force-snip` 不会生成摘要，而是直接丢弃旧消息。
|
||||
|
||||
一般来说，优先使用 `/compact`（保留摘要），只有当你确认旧消息完全不再需要时才用 `/force-snip`。
|
||||
|
||||
## 导出与分享对话
|
||||
|
||||
有时候你想把对话内容保存下来或分享给同事。
|
||||
|
||||
**导出到文件**：输入 `/export` 会把当前对话导出为一个文件。支持指定文件名：
|
||||
|
||||
```
|
||||
/export my-session.md
|
||||
```
|
||||
|
||||
导出内容是纯文本格式，包含完整的对话记录，方便用其他工具查看或归档。
|
||||
|
||||
**上传分享**：输入 `/share` 会把当前会话日志上传到 GitHub Gist，生成一个可分享的链接：
|
||||
|
||||
```
|
||||
/share # 默认创建 secret Gist
|
||||
/share --public # 创建公开 Gist
|
||||
/share --mask-secrets # 自动脱敏 API key 等凭证
|
||||
/share --summary-only # 只分享摘要（每轮截取前 200 字符）
|
||||
/share --allow-public-fallback # gh 不可用时回退到 0x0.st
|
||||
```
|
||||
|
||||
**隐私提示**：`/share` 上传的 JSONL 文件包含当前会话的所有输入和工具输出。虽然 `--mask-secrets` 可以自动替换常见格式的 API key、Bearer token、AWS key 和 GitHub token，但不保证能覆盖所有敏感信息。分享前请确认内容安全。如果只想让别人了解大概讨论了什么，用 `--summary-only` 是更安全的选择。
|
||||
|
||||
**生成摘要**：输入 `/summary` 会让 Claude 对当前对话生成一份结构化的会话摘要。这比 `/compact` 更详细，适合在结束一个长会话前做总结归档。
|
||||
|
||||
## 更换主题、输出风格与语言
|
||||
|
||||
**主题**：输入 `/theme` 可以更换界面配色方案。适合根据终端背景和个人偏好调整。
|
||||
|
||||
**输出风格**：`/output-style` 命令可以调整 Claude 的回复风格（该命令目前标记为已废弃，推荐使用 `/config` 代替）。
|
||||
|
||||
**界面语言**：输入 `/lang` 可以切换显示语言：
|
||||
|
||||
```
|
||||
/lang zh # 简体中文
|
||||
/lang en # English
|
||||
/lang auto # 跟随系统语言
|
||||
```
|
||||
|
||||
这个设置影响的是界面提示和部分 UI 文本的显示语言，不影响 Claude 的回复语言（回复语言由对话上下文和 CLAUDE.md 配置决定）。
|
||||
|
||||
## 配置项目记忆：CLAUDE.md 与 /memory
|
||||
|
||||
Claude Code 每次启动时会自动加载项目目录下的 `CLAUDE.md` 文件作为上下文。你可以在里面写项目约定、代码规范、常用命令等，让 Claude "记住"你的项目特性。
|
||||
|
||||
CLAUDE.md 支持四层层级，后加载的优先级更高：
|
||||
|
||||
1. **Managed** -- 平台管理的全局指令
|
||||
2. **User** -- 用户主目录下的 `~/.claude/CLAUDE.md`
|
||||
3. **Project** -- 项目根目录的 `CLAUDE.md`
|
||||
4. **Local** -- 子目录中的 `CLAUDE.md`
|
||||
|
||||
你可以用 `@include` 指令在 CLAUDE.md 里引用其他文件，支持相对路径、家目录路径和绝对路径：
|
||||
|
||||
```markdown
|
||||
@./docs/coding-standards.md
|
||||
@~/my-global-rules.md
|
||||
@/etc/claude/company-rules.md
|
||||
```
|
||||
|
||||
支持的文件类型不限于 `.md`，还包括 `.ts`、`.py`、`.rs`、`.sql` 等几十种文本格式。如果引用的文件不存在，会被静默忽略。
|
||||
|
||||
在对话中输入 `/memory` 可以直接编辑 Claude 的记忆文件，快速追加或修改项目知识。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想快速查找某个 slash 命令，看 [第四章：slash 命令速查](./04-slash-commands.md)
|
||||
- 想接入外部工具扩展 Claude 的能力，看 [第五章：扩展 Claude 的能力](./05-extensions.md)
|
||||
- 想了解 token 消耗优化和配置进阶，看 [第九章：省钱、提速、定制](./09-budget-config.md)
|
||||
318
docs/outline-output/user/04-slash-commands.md
Normal file
318
docs/outline-output/user/04-slash-commands.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# 第四章：slash 命令速查 —— 不用记全部，按场景找
|
||||
|
||||
> 你想做什么？翻到这里，按场景找到对应命令。
|
||||
|
||||
在 Claude Code 的交互式 REPL 中，输入 `/` 开头的文本即可触发 slash 命令。命令很多，但不需要死记硬背——按你想做的事情找就行。如果实在不确定要哪个，直接输入 `/help` 会打开一个分类浏览面板，里面有所有可用命令。
|
||||
|
||||
## 会话与上下文管理
|
||||
|
||||
当你的对话变长、上下文快满了，或者想换个话题重新开始，这些命令帮你管好会话状态。
|
||||
|
||||
**`/clear`**（别名 `/reset`、`/new`）清空当前对话历史，从头开始。就像关闭再重新打开一个聊天窗口，之前的消息不会丢失到磁盘上的会话记录里，但不再参与本次对话的上下文。
|
||||
|
||||
```
|
||||
你: /clear
|
||||
```
|
||||
|
||||
**`/compact`** 比 `/clear` 更温和——它会用 AI 总结当前对话，然后清除原始消息，只保留总结。这样你可以在不丢失要点的前提下释放上下文空间。你还可以给它自定义总结指令：
|
||||
|
||||
```
|
||||
你: /compact 用中文总结，保留所有文件路径和关键决策
|
||||
```
|
||||
|
||||
如果 `DISABLE_COMPACT` 环境变量被设置，`/compact` 会被禁用。
|
||||
|
||||
**`/force-snip`** 在当前位置插入一个"剪裁边界"。下次查询时，边界之前的消息会被从模型视角移除（REPL 的滚动历史里仍然可见）。这是在 `/compact` 不够用时的手动干预手段。
|
||||
|
||||
**`/resume`**（别名 `/continue`）恢复之前的对话。可以传会话 ID 或搜索关键词：
|
||||
|
||||
```
|
||||
你: /resume abc123
|
||||
你: /continue 修复认证bug
|
||||
```
|
||||
|
||||
**`/history`**（别名 `/hist`）查看会话历史列表。
|
||||
|
||||
**`/context`** 可视化当前上下文使用情况——显示一个彩色网格，直观展示上下文窗口里各部分占用了多少空间。非交互模式下会以文本形式展示。
|
||||
|
||||
**`/rewind`**（别名 `/checkpoint`）将代码和/或对话恢复到之前的某个节点。
|
||||
|
||||
## 模型与 Provider 切换
|
||||
|
||||
想换一家 API、换一个模型、或者调整思考强度，用这几个命令。
|
||||
|
||||
**`/provider`**（别名 `/api`）切换 API 提供商。支持 7 个 provider：`anthropic`、`openai`、`gemini`、`grok`、`bedrock`、`vertex`、`foundry`。不带参数时显示当前 provider，`unset` 清除设置回退到环境变量：
|
||||
|
||||
```
|
||||
你: /provider gemini
|
||||
你: /provider unset
|
||||
你: /provider
|
||||
> Current API provider: anthropic
|
||||
```
|
||||
|
||||
注意：`bedrock`、`vertex`、`foundry` 通过环境变量控制（`CLAUDE_CODE_USE_BEDROCK=1` 等），不会写入 settings.json。切换到 `openai`、`gemini`、`grok` 时会检查对应的 API key 是否已配置，如果缺失会给出警告。
|
||||
|
||||
**`/model`** 切换模型。不带参数时显示当前模型及描述，带参数时设置新模型。模型名通常形如 `claude-sonnet-4`、`claude-opus-4` 等：
|
||||
|
||||
```
|
||||
你: /model claude-opus-4
|
||||
你: /model
|
||||
```
|
||||
|
||||
**`/effort`** 设置思考强度，影响模型在推理上的投入程度。支持 `low`、`medium`、`high`、`xhigh`、`max`、`auto` 几档：
|
||||
|
||||
```
|
||||
你: /effort high
|
||||
```
|
||||
|
||||
**`/login`** 通过引导式流程登录 Anthropic 账号。如果已登录则显示为"切换账号"。设置 `DISABLE_LOGIN_COMMAND=1` 可禁用此命令。
|
||||
|
||||
**`/logout`** 退出当前账号登录状态。设置 `DISABLE_LOGOUT_COMMAND=1` 可禁用此命令。
|
||||
|
||||
## 费用、用量与限流
|
||||
|
||||
想知道花了多少钱、用了多少 token、遇到限流怎么办，看这里。
|
||||
|
||||
**`/usage`**（别名 `/cost`、`/stats`）显示会话费用、套餐用量和活动统计。三个名字指向同一个命令，用哪个都行：
|
||||
|
||||
```
|
||||
你: /usage
|
||||
你: /cost
|
||||
你: /stats
|
||||
```
|
||||
|
||||
**`/rate-limit-options`** 当你撞到 API 限流时，这个命令会弹出一个菜单，提供几个选项：申请额外用量（extra usage）、升级套餐（upgrade plan）、或等待限流重置。具体可用的选项取决于你的订阅类型——Team/Enterprise 用户看到的是"申请更多"，Max 20x 用户看不到升级选项。
|
||||
|
||||
**`/reset-limits`** 重置限流状态。注意：当前版本此命令是一个 stub（占位），功能尚未实现。
|
||||
|
||||
如果你使用的是 OpenAI 兼容层，限流追踪是通过响应头 `x-ratelimit-*-requests`/`x-ratelimit-*-tokens` 和 `Reset-After` 自动完成的，不需要手动干预。
|
||||
|
||||
**`/perf-issue`** 生成一份性能快照报告，包含内存占用、CPU 使用、token 消耗、工具调用次数、缓存命中率、费用估算等信息。默认以 Markdown 格式写入 `~/.claude/perf-reports/` 目录：
|
||||
|
||||
```
|
||||
你: /perf-issue
|
||||
> Perf snapshot written to:
|
||||
> `~/.claude/perf-reports/perf-2026-06-14T10-30-00-abc12345.md`
|
||||
|
||||
你: /perf-issue --format=json --limit=5000
|
||||
```
|
||||
|
||||
## 配置与个性化
|
||||
|
||||
让 Claude Code 按你的习惯工作——主题、语言、快捷键、配置面板。
|
||||
|
||||
**`/config`**（别名 `/settings`）打开配置面板，可以集中管理各种设置项。
|
||||
|
||||
**`/theme`** 切换终端界面主题。会弹出可选主题列表供你选择。
|
||||
|
||||
**`/lang`** 设置显示语言，支持 `en`、`zh`、`auto`（自动检测）：
|
||||
|
||||
```
|
||||
你: /lang zh
|
||||
你: /lang auto
|
||||
```
|
||||
|
||||
**`/keybindings`** 打开或创建你的快捷键配置文件 `~/.claude/keybindings.json`。需要 `isKeybindingCustomizationEnabled()` 返回 true 才可用。
|
||||
|
||||
**`/env`** 显示当前环境信息快照，包括运行时信息（平台、CWD、PID、Bun/Node 版本、session ID）和关键环境变量。敏感值（匹配 token/password/auth/api_key 等关键词的）会被自动遮掩。只显示 `CLAUDE_*`、`FEATURE_*`、`ANTHROPIC_*`、`BUN_*`、`NODE_*`、`GEMINI_*`、`OPENAI_*`、`GROK_*` 等前缀的环境变量：
|
||||
|
||||
```
|
||||
你: /env
|
||||
> ## Runtime
|
||||
> platform: darwin arm64
|
||||
> cwd: /Users/you/project
|
||||
> pid: 12345
|
||||
> bun: 1.2.0
|
||||
> ## Environment Variables (allowlisted prefixes)
|
||||
> ANTHROPIC_API_KEY=sk-a…d2 (38 chars)
|
||||
> ...
|
||||
```
|
||||
|
||||
**`/output-style`** 修改输出风格。已标记为 deprecated（不推荐使用），建议改用 `/config` 来调整。
|
||||
|
||||
**`/mode`** 切换交互模式，支持多种预设：`default`、`gentle`、`sharp`、`workhorse`、`token-saver`、`super-ai`：
|
||||
|
||||
```
|
||||
你: /mode token-saver
|
||||
```
|
||||
|
||||
## 项目与文件操作
|
||||
|
||||
让 Claude 关注特定的目录、查看文件列表和变更差异。
|
||||
|
||||
**`/add-dir`** 将一个新目录添加到 Claude Code 的工作范围内：
|
||||
|
||||
```
|
||||
你: /add-dir /path/to/another/project
|
||||
```
|
||||
|
||||
**`/diff`** 查看未提交的代码变更和每轮对话中的 diff。会以交互式界面展示。
|
||||
|
||||
**`/files`** 列出当前上下文中包含的所有文件。注意：此命令仅对 Anthropic 内部用户可用（`USER_TYPE=ant`）。
|
||||
|
||||
**`/context`** 和 **`/ctx_viz`** 都用于可视化上下文使用。`/context` 是主要命令，在交互模式下显示彩色网格，非交互模式下显示文本摘要。`/ctx_viz` 当前是 stub（禁用状态）。
|
||||
|
||||
## 插件、Skill 与扩展
|
||||
|
||||
当内置功能不够用，想装插件、浏览技能市场或管理 Skill。
|
||||
|
||||
**`/plugin`**（别名 `/plugins`、`/marketplace`）管理 Claude Code 插件——浏览、安装、启用、禁用、卸载。可以进入插件市场（Marketplace）浏览社区贡献的插件。
|
||||
|
||||
```
|
||||
你: /plugin
|
||||
你: /plugins
|
||||
你: /marketplace
|
||||
```
|
||||
|
||||
**`/skills`** 列出当前可用的所有 Skill。Skill 是一种可复用的工作流单元。
|
||||
|
||||
**`/skill-store`**（别名 `/ss`、`/cloud-skills`）浏览和安装远程技能市场中的 Skill。需要 Claude Pro/Max/Team 订阅。支持 list、get、versions、install 等子命令：
|
||||
|
||||
```
|
||||
你: /skill-store list
|
||||
你: /skill-store get my-skill-id
|
||||
你: /skill-store install my-skill-id@1.0
|
||||
```
|
||||
|
||||
**`/reload-plugins`** 激活待定的插件变更到当前会话。当你安装或更新了插件后，需要执行此命令让改动生效（SDK 调用方通常通过 `query.reloadPlugins()` 来触发）。
|
||||
|
||||
**`/hooks`** 查看和管理工具事件的钩子配置。在 `settings.json` 中配置的 hooks 会在特定工具事件发生时自动执行脚本。
|
||||
|
||||
## 工作流自动化
|
||||
|
||||
把日常重复操作固化为可重放的工作流。
|
||||
|
||||
**`/commit`** 让 Claude 帮你生成 git commit。它只被允许执行 `git add`、`git status`、`git commit` 三个命令，会分析你的变更后生成合适的 commit message 并提交。
|
||||
|
||||
```
|
||||
你: /commit
|
||||
```
|
||||
|
||||
**`/commit-push-pr`** 一条龙完成 commit、push 和创建 PR。Claude 会自动创建分支、提交代码、推送并在 GitHub 上创建 Pull Request。
|
||||
|
||||
**`/review`** 让 Claude 审查一个 Pull Request。不带参数时会列出所有开放的 PR，带 PR 编号时直接审查指定 PR：
|
||||
|
||||
```
|
||||
你: /review
|
||||
你: /review 42
|
||||
```
|
||||
|
||||
还有 `/ultrareview` 命令，它会在 Claude Code on the web 上运行一个更深入的 bug 搜索和验证流程，大约需要 10-20 分钟。
|
||||
|
||||
**`/plan`** 进入 Plan 模式或查看当前计划。先想清楚再动手：
|
||||
|
||||
```
|
||||
你: /plan 重构认证模块，将 JWT 逻辑抽到独立 service
|
||||
你: /plan open
|
||||
```
|
||||
|
||||
**`/triggers`**（别名 `/cron`）管理云端定时触发的远程代理任务（cloud cron）。需要 Claude Pro/Max/Team 订阅。支持创建、查看、更新、删除、运行、启用、禁用等操作：
|
||||
|
||||
```
|
||||
你: /triggers list
|
||||
你: /triggers create "*/30 * * * *" "检查 deploy 状态"
|
||||
你: /triggers run trigger-123
|
||||
```
|
||||
|
||||
注意：命令名叫 `/triggers`（对应底层 API endpoint `/v1/code/triggers`），别名 `/cron`。
|
||||
|
||||
**`/goal`** 设置一个持续性目标，Claude 会跨轮次自动推进。支持 status、clear、pause、resume、complete 等子命令：
|
||||
|
||||
```
|
||||
你: /goal 完成 login 模块的单元测试覆盖
|
||||
你: /goal status
|
||||
你: /goal complete
|
||||
```
|
||||
|
||||
**`/workflows`** 打开工作流监控面板，实时显示运行中的 workflow 的 run/phase/agent 进度。
|
||||
|
||||
## 权限与安全
|
||||
|
||||
管理工具权限、沙箱模式，控制 Claude 能做什么。
|
||||
|
||||
**`/permissions`**（别名 `/allowed-tools`）管理工具的 allow/deny 权限规则。可以精细控制哪些工具被允许自动执行，哪些需要每次确认。
|
||||
|
||||
**`/sandbox`** 切换沙箱模式。沙箱模式下，shell 命令会被限制在一个隔离环境中执行，防止意外修改系统文件。支持配置排除模式——某些命令可以不经沙箱直接执行：
|
||||
|
||||
```
|
||||
你: /sandbox
|
||||
> (sandbox enabled, 可配置 exclude 规则)
|
||||
```
|
||||
|
||||
注意：此命令仅在支持的平台上显示，且需要平台在启用列表中。
|
||||
|
||||
**`/poor`** 切换穷鬼模式——关闭 `extract_memories` 和 `prompt_suggestion` 两个功能来节省 token 消耗。设置会持久化到 `settings.json`：
|
||||
|
||||
```
|
||||
你: /poor
|
||||
> Poor mode enabled — extract_memories and prompt_suggestion disabled.
|
||||
```
|
||||
|
||||
## 记忆与会话输出
|
||||
|
||||
管理 Claude 的记忆文件、导出和分享会话。
|
||||
|
||||
**`/memory`** 编辑 Claude 的记忆文件（CLAUDE.md 等）。会打开一个编辑界面让你查看和修改 Claude 对你项目的长期记忆。
|
||||
|
||||
**`/summary`** 手动触发一次会话摘要生成。通常会自动在满足条件时提取，但你可以随时用这个命令主动生成：
|
||||
|
||||
```
|
||||
你: /summary
|
||||
> Session summary updated.
|
||||
> [摘要内容]
|
||||
```
|
||||
|
||||
**`/export`** 将当前对话导出到文件或剪贴板：
|
||||
|
||||
```
|
||||
你: /export conversation-backup.md
|
||||
```
|
||||
|
||||
**`/share`** 将当前会话日志上传到 GitHub Gist，方便分享给同事或提交 issue。支持多个标志来控制分享方式：
|
||||
|
||||
```
|
||||
你: /share --private --mask-secrets
|
||||
你: /share --public --summary-only
|
||||
你: /share --mask-secrets --allow-public-fallback
|
||||
```
|
||||
|
||||
可选标志：
|
||||
- `--public`：创建公开 Gist（默认 `--private`）
|
||||
- `--mask-secrets`：上传前遮掩 API key、token 等敏感信息
|
||||
- `--summary-only`：只上传摘要（每轮截取前 200 字符）
|
||||
- `--allow-public-fallback`：如果 `gh gist` 失败，回退到 0x0.st
|
||||
|
||||
注意：需要安装 `gh` CLI 工具并已登录。
|
||||
|
||||
## 诊断与帮助
|
||||
|
||||
遇到问题或需要了解系统状态时。
|
||||
|
||||
**`/help`** 打开帮助面板。面板有三个标签页：general（通用快捷键和用法）、commands（所有内置命令）、custom-commands（自定义命令）。设置 `DISABLE_DOCTOR_COMMAND=1` 可禁用。
|
||||
|
||||
```
|
||||
你: /help
|
||||
```
|
||||
|
||||
**`/doctor`** 诊断和验证你的 Claude Code 安装及配置是否正确。遇到莫名其妙的问题时，先跑这个：
|
||||
|
||||
```
|
||||
你: /doctor
|
||||
```
|
||||
|
||||
**`/status`** 显示 Claude Code 的综合状态信息：版本号、当前模型、账号信息、API 连通性、工具状态等。
|
||||
|
||||
**`/version`** 只显示当前运行的版本号和构建时间：
|
||||
|
||||
```
|
||||
你: /version
|
||||
> 2.7.0 (built 2026-06-14T08:00:00Z)
|
||||
```
|
||||
|
||||
**`/feedback`**（别名 `/bug`）提交关于 Claude Code 的反馈。注意：在 Bedrock、Vertex、Foundry 或隐私模式下此命令不可用。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想了解 MCP Server、插件和 Skill 的详细用法，看 [第五章：扩展 Claude 的能力](./05-extensions.md)
|
||||
- 想在 CI 或脚本中无交互调用 Claude，看 [第十一章：自动化与 CI 集成](./11-ci-integration.md)
|
||||
- 遇到报错或卡住，看 [第十章：可观测性与排错](./10-troubleshooting.md)
|
||||
383
docs/outline-output/user/05-mcp-plugins-skills.md
Normal file
383
docs/outline-output/user/05-mcp-plugins-skills.md
Normal file
@@ -0,0 +1,383 @@
|
||||
# 第五章：扩展 Claude 的能力 -- MCP Server、插件、Skill
|
||||
|
||||
> 内置工具不够用时，用 MCP 接入外部服务，用插件扩展功能，用 Skill 沉淀工作流。
|
||||
|
||||
## MCP 是什么？什么时候该用它
|
||||
|
||||
MCP（Model Context Protocol）是一种标准化协议，让 Claude Code 能调用外部程序提供的工具和资源。你可以把它理解成一个"工具插件接口"：任何实现了 MCP 协议的程序，都可以把自身能力暴露给 Claude Code 使用。
|
||||
|
||||
典型的使用场景包括：
|
||||
|
||||
- **数据库操作**：接入一个 MCP server，让 Claude Code 能直接查询和管理数据库
|
||||
- **API 交互**：接入 Sentry、GitHub、Slack 等服务的 MCP server，让 Claude Code 能直接操作这些服务
|
||||
- **文件系统扩展**：接入特定格式（比如 Figma 设计文件）的 MCP server
|
||||
|
||||
MCP server 通过三种传输方式与 Claude Code 通信：
|
||||
|
||||
| 传输方式 | 适合场景 | 典型命令 |
|
||||
|----------|---------|---------|
|
||||
| **stdio** | 本地命令行程序，如 `npx my-mcp-server` | `claude mcp add my-server -- npx my-mcp-server` |
|
||||
| **SSE** | 远程服务，通过 Server-Sent Events 通信 | `claude mcp add --transport sse my-server https://example.com/sse` |
|
||||
| **HTTP** | 远程 HTTP 端点 | `claude mcp add --transport http sentry https://mcp.sentry.dev/mcp` |
|
||||
|
||||
如果你只是想让 Claude Code 做一些固定的本地操作（比如跑测试、读日志），通常写一个 Skill（见本章后半部分）更轻量。MCP 更适合需要持续运行的外部服务或复杂的多工具场景。
|
||||
|
||||
## 用 `claude mcp add` 接入现成 MCP server
|
||||
|
||||
最常见的方式是通过 `claude mcp add` 命令，把一个现成的 MCP server 注册到 Claude Code。
|
||||
|
||||
### 添加 stdio 类型的 server
|
||||
|
||||
stdio 类型适用于本地可执行程序，比如通过 `npx` 运行的 Node.js 包：
|
||||
|
||||
```bash
|
||||
# 添加一个 stdio server，自动以 -- 后面的内容为子命令
|
||||
claude mcp add my-server -- npx my-mcp-server
|
||||
|
||||
# 带环境变量
|
||||
claude mcp add -e API_KEY=xxx my-server -- npx my-mcp-server
|
||||
|
||||
# 带额外参数
|
||||
claude mcp add my-server -- my-command --some-flag arg1
|
||||
```
|
||||
|
||||
### 添加 HTTP 或 SSE 类型的 server
|
||||
|
||||
对于远程 MCP 服务，需要指定传输方式：
|
||||
|
||||
```bash
|
||||
# HTTP server
|
||||
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
|
||||
|
||||
# 带认证头的 HTTP server
|
||||
claude mcp add --transport http corridor https://app.corridor.dev/api/mcp \
|
||||
--header "Authorization: Bearer your-token"
|
||||
|
||||
# SSE server
|
||||
claude mcp add --transport sse my-server https://example.com/sse
|
||||
```
|
||||
|
||||
### 配置范围
|
||||
|
||||
`-s` 参数控制配置写入的位置，影响谁能看到这个 MCP server：
|
||||
|
||||
| 范围 | 说明 | 配置文件位置 |
|
||||
|------|------|------------|
|
||||
| `local`（默认） | 仅当前项目 | 项目目录下的配置文件 |
|
||||
| `user` | 当前用户所有项目 | 用户主目录下的全局配置 |
|
||||
| `project` | 项目级共享（可提交到 git） | 项目目录下的配置文件 |
|
||||
|
||||
例如，把一个数据库 MCP server 配置为整个团队可用：
|
||||
|
||||
```bash
|
||||
claude mcp add -s project my-db -- npx my-db-mcp-server
|
||||
```
|
||||
|
||||
## 管理已接入的 server
|
||||
|
||||
注册之后，你可以在对话内或通过 CLI 管理这些 MCP server。
|
||||
|
||||
### CLI 方式
|
||||
|
||||
```bash
|
||||
# 列出所有已配置的 MCP server
|
||||
claude mcp list
|
||||
|
||||
# 查看某个 server 的详情
|
||||
claude mcp get my-server
|
||||
|
||||
# 移除一个 server
|
||||
claude mcp remove my-server
|
||||
|
||||
# 从特定范围移除
|
||||
claude mcp remove -s local my-server
|
||||
```
|
||||
|
||||
### 对话内方式
|
||||
|
||||
在 REPL 中输入 `/mcp` 会打开 MCP 管理面板。你可以在这里：
|
||||
|
||||
- **启用/禁用 server**：`/mcp enable my-server` 或 `/mcp disable my-server`
|
||||
- **批量操作**：`/mcp enable all` 或 `/mcp disable all`
|
||||
- **重新连接**：`/mcp reconnect my-server`（当连接断开时）
|
||||
- **查看 server 提供的工具和资源**：在面板中选择 server 查看详情
|
||||
|
||||
启用或禁用是会话级别的操作，不会删除配置。重启 Claude Code 后，之前禁用的 server 会恢复启用状态。
|
||||
|
||||
## 把 Claude Code 自己暴露为 MCP server
|
||||
|
||||
`claude mcp serve` 命令把 Claude Code 自身启动为一个 MCP server，让其他 MCP 客户端（比如 IDE、其他 AI 工具）能调用它的工具：
|
||||
|
||||
```bash
|
||||
# 启动 Claude Code MCP server
|
||||
claude mcp serve
|
||||
|
||||
# 带调试信息
|
||||
claude mcp serve --debug
|
||||
|
||||
# 详细输出
|
||||
claude mcp serve --verbose
|
||||
```
|
||||
|
||||
这在你想把 Claude Code 的文件操作、搜索、代码编辑等能力暴露给外部工具时很有用。
|
||||
|
||||
## MCP server 连接了但工具看不到？排查要点
|
||||
|
||||
接入 MCP server 后，如果 Claude Code 似乎"不知道"新工具的存在，可能有以下原因：
|
||||
|
||||
1. **server 启动失败**：用 `claude mcp list` 检查 server 状态。stdio 类型的 server 如果命令路径不对或依赖缺失，会静默失败。
|
||||
2. **工具是延迟加载的**：非核心工具（包括所有 MCP 工具）默认不会全部加载到上下文。Claude Code 使用 SearchExtraTools 机制，按需搜索和加载延迟工具。当你的请求需要用到 MCP 工具时，它会自动搜索并加载。
|
||||
3. **OAuth 认证未完成**：需要 OAuth 的 HTTP/SSE server 如果认证未通过，工具虽然能被发现但调用会失败。
|
||||
4. **scope 不对**：`claude mcp add -s local` 添加的 server 只在当前项目目录生效。切换到其他目录后该 server 不可用。
|
||||
|
||||
## 自己写一个 MCP server 的最小骨架
|
||||
|
||||
如果你找不到现成的 MCP server 来满足需求，可以自己写一个。核心步骤是：
|
||||
|
||||
1. 使用 MCP SDK 创建一个 Server 实例
|
||||
2. 注册工具（ListTools + CallTool）
|
||||
3. 通过 stdio 或 HTTP 暴露服务
|
||||
|
||||
下面是一个最简单的 stdio MCP server（TypeScript，使用官方 `@modelcontextprotocol/sdk`）：
|
||||
|
||||
```typescript
|
||||
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
||||
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
||||
import {
|
||||
CallToolRequestSchema,
|
||||
ListToolsRequestSchema,
|
||||
} from "@modelcontextprotocol/sdk/types.js";
|
||||
|
||||
const server = new Server(
|
||||
{ name: "my-mcp-server", version: "1.0.0" },
|
||||
{ capabilities: { tools: {} } }
|
||||
);
|
||||
|
||||
server.setRequestHandler(ListToolsRequestSchema, async () => ({
|
||||
tools: [
|
||||
{
|
||||
name: "get_weather",
|
||||
description: "Get the current weather for a city",
|
||||
inputSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
city: { type: "string", description: "City name" },
|
||||
},
|
||||
required: ["city"],
|
||||
},
|
||||
},
|
||||
],
|
||||
}));
|
||||
|
||||
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
||||
const { city } = request.params.arguments as { city: string };
|
||||
return {
|
||||
content: [{ type: "text", text: `Weather in ${city}: sunny, 22C` }],
|
||||
};
|
||||
});
|
||||
|
||||
const transport = new StdioServerTransport();
|
||||
await server.connect(transport);
|
||||
```
|
||||
|
||||
写好后注册到 Claude Code：
|
||||
|
||||
```bash
|
||||
claude mcp add weather-server -- npx tsx my-mcp-server.ts
|
||||
```
|
||||
|
||||
接下来在对话里让 Claude Code "查询北京的天气"，它就会自动调用你的 `get_weather` 工具。
|
||||
|
||||
## 内置 MCP 能力：Computer Use、Chrome 控制、语音输入
|
||||
|
||||
除了接入外部 MCP server，Claude Code 本身也提供了几个内置的 MCP 功能，覆盖屏幕控制、浏览器操作和语音输入。
|
||||
|
||||
### Computer Use（屏幕控制）
|
||||
|
||||
通过 `--computer-use-mcp` 启动参数加载，提供截屏、键鼠控制和应用管理能力。支持 macOS、Windows、Linux 三大桌面平台，共 38 个工具。
|
||||
|
||||
```bash
|
||||
claude --computer-use-mcp
|
||||
```
|
||||
|
||||
启用后，Claude Code 可以看到你的屏幕、模拟鼠标键盘操作、管理应用窗口。比如你可以说"打开系统设置，把亮度调到 80%"，它会截图、识别界面、操作完成。详见 [Computer Use 文档](../../features/external/computer-use.md)。
|
||||
|
||||
### Chrome 浏览器控制
|
||||
|
||||
通过 `--chrome-native-host` 或 `--claude-in-chrome-mcp` 启动参数加载。提供两种方案：
|
||||
|
||||
- **Chrome Use MCP**（社区开源）：通过 MCP 扩展接入，适合自托管场景
|
||||
- **Claude in Chrome**（原生集成）：Anthropic 官方扩展，提供完整能力（截图、网络监控、JS 执行等）
|
||||
|
||||
详见 [Chrome 控制文档](../../features/external/chrome-control.md)。
|
||||
|
||||
### 语音输入
|
||||
|
||||
通过 `FEATURE_VOICE_MODE=1` 启用，支持 Push-to-Talk 语音输入。长按空格键录音，释放后自动转录并发送。支持 Anthropic STT 和豆包 ASR 两种后端。
|
||||
|
||||
```bash
|
||||
FEATURE_VOICE_MODE=1 claude
|
||||
```
|
||||
|
||||
在对话中用 `/voice` 切换语音模式，`/voice doubao` 切换到豆包后端。详见 [Voice Mode 文档](../../features/external/voice-mode.md)。
|
||||
|
||||
## 插件系统：安装和管理社区插件
|
||||
|
||||
插件（Plugin）是在 Claude Code 中扩展功能的另一种方式。与 MCP server 不同，插件可以包含工具、命令、设置项等多种能力，更像一个"功能包"。
|
||||
|
||||
### 浏览和安装插件
|
||||
|
||||
在 REPL 中输入 `/plugin`（或 `/plugins`、`/marketplace`）打开插件管理界面。你也可以用命令行子操作：
|
||||
|
||||
```bash
|
||||
# 打开插件菜单
|
||||
/plugin
|
||||
|
||||
# 安装插件
|
||||
/plugin install plugin-name
|
||||
|
||||
# 从指定 marketplace 安装
|
||||
/plugin install plugin-name@marketplace-url
|
||||
|
||||
# 管理已安装的插件
|
||||
/plugin manage
|
||||
|
||||
# 启用/禁用/卸载
|
||||
/plugin enable plugin-name
|
||||
/plugin disable plugin-name
|
||||
/plugin uninstall plugin-name
|
||||
```
|
||||
|
||||
### 插件市场
|
||||
|
||||
插件通过 marketplace 分发。Claude Code 支持管理多个 marketplace 来源：
|
||||
|
||||
```bash
|
||||
# 添加一个 marketplace
|
||||
/plugin marketplace add https://my-marketplace.example.com/registry.json
|
||||
|
||||
# 列出已添加的 marketplace
|
||||
/plugin marketplace list
|
||||
|
||||
# 更新 marketplace 索引
|
||||
/plugin marketplace update
|
||||
```
|
||||
|
||||
### 验证插件
|
||||
|
||||
安装前可以验证插件的完整性：
|
||||
|
||||
```bash
|
||||
/plugin validate path/to/plugin
|
||||
```
|
||||
|
||||
### 插件 vs MCP server
|
||||
|
||||
两者的界限有时模糊，但大致可以这样区分：
|
||||
|
||||
| 维度 | MCP Server | 插件 |
|
||||
|------|-----------|------|
|
||||
| 通信方式 | 标准协议（stdio/SSE/HTTP） | 直接集成到 Claude Code |
|
||||
| 包含内容 | 工具和资源 | 工具 + 命令 + 设置 + UI 组件 |
|
||||
| 来源 | 任何实现了 MCP 的程序 | Claude Code 插件市场 |
|
||||
| 管理方式 | `claude mcp add/list/remove` | `/plugin install/manage` |
|
||||
|
||||
简单来说：MCP server 适合对接外部服务，插件适合扩展 Claude Code 自身的行为。
|
||||
|
||||
## Skill 是什么？
|
||||
|
||||
Skill 是一段 Markdown 文本，定义了 Claude Code 在特定场景下应该怎么行动。它不是"可执行代码"，而是一份结构化的行为指南，被 Claude Code 读取后影响它的决策和操作方式。
|
||||
|
||||
你可以把 Skill 理解为给 Claude Code 的一份"操作手册"：告诉它在遇到特定类型任务时，应该遵循什么步骤、用什么工具、注意什么事项。
|
||||
|
||||
### 查看可用 Skill
|
||||
|
||||
在 REPL 中输入 `/skills` 打开 Skill 列表面板。你会看到所有可用的 Skill 及其简要描述。每个 Skill 有一个名称和触发条件（whenToUse），Claude Code 会根据对话上下文自动匹配最相关的 Skill。
|
||||
|
||||
### Skill Store（远程 Skill 市场）
|
||||
|
||||
`/skill-store` 命令打开远程 Skill 市场，可以浏览和安装社区发布的 Skill。它需要 Anthropic API Key 或 workspace API key：
|
||||
|
||||
```bash
|
||||
# 打开 Skill Store
|
||||
/skill-store
|
||||
|
||||
# 列出可用 Skill
|
||||
/skill-store list
|
||||
|
||||
# 查看某个 Skill 的详情
|
||||
/skill-store get skill-id
|
||||
|
||||
# 查看版本历史
|
||||
/skill-store versions skill-id
|
||||
|
||||
# 安装 Skill
|
||||
/skill-store install skill-id
|
||||
```
|
||||
|
||||
`/skill-store` 也叫 `/ss` 或 `/cloud-skills`，三个别名指向同一个命令。
|
||||
|
||||
### `/skills` 与 `/skill-store` 的区别
|
||||
|
||||
| 命令 | 作用 | 数据来源 |
|
||||
|------|------|---------|
|
||||
| `/skills` | 查看当前会话可用的所有 Skill（本地 + 远程 + 内置） | 本地 `.claude/skills/` 目录 + 内置 Skill |
|
||||
| `/skill-store` | 浏览和安装远程社区的 Skill | Anthropic Skill 市场（需 API Key） |
|
||||
|
||||
简单说：`/skills` 看你"有什么"，`/skill-store` 去"买新的"。
|
||||
|
||||
## 写一个自己的 Skill 并复用
|
||||
|
||||
自定义 Skill 是 Markdown 文件，放在 `.claude/skills/` 目录下（项目级）或 `~/.claude/skills/`（用户级）。
|
||||
|
||||
### Skill 文件结构
|
||||
|
||||
一个 Skill 文件就是一份结构化的 Markdown：
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-code-review
|
||||
description: Review code changes with security and performance focus
|
||||
---
|
||||
|
||||
# Code Review Skill
|
||||
|
||||
When asked to review code, follow these steps:
|
||||
|
||||
1. Read the changed files using the Read tool
|
||||
2. Check for common security issues (injection, auth bypass, data leaks)
|
||||
3. Check for performance anti-patterns (N+1 queries, unnecessary allocations)
|
||||
4. Verify error handling is complete
|
||||
5. Report findings in a structured table format
|
||||
```
|
||||
|
||||
把这个文件保存为 `.claude/skills/my-code-review.md` 后，Claude Code 在处理代码审查请求时就会参考这个 Skill 的指导。
|
||||
|
||||
### Skill 搜索与自动匹配
|
||||
|
||||
启用 Skill Search（`/skill-search start`）后，Claude Code 会在每轮对话中自动搜索并加载与当前任务最相关的 Skill。搜索基于 TF-IDF 向量余弦相似度算法，支持英文词干化和中文 bi-gram 分词。
|
||||
|
||||
```bash
|
||||
/skill-search start # 启用自动匹配
|
||||
/skill-search stop # 禁用自动匹配
|
||||
/skill-search status # 查看当前状态
|
||||
```
|
||||
|
||||
启用后，Skill Search 会索引 `.claude/skills/` 和 `~/.claude/skills/` 下的所有 Markdown 文件，根据对话内容自动匹配并注入相关 Skill 指导。
|
||||
|
||||
### 延迟工具加载：SearchExtraTools 与 ExecuteExtraTools
|
||||
|
||||
Claude Code 的工具系统采用延迟加载策略。核心工具（Read、Edit、Write、Bash、Glob、Grep 等 38 个）始终可用，其余工具（包括所有 MCP 工具）需要按需发现和加载。
|
||||
|
||||
当你让 Claude Code 执行一个需要非核心工具的操作时，它会自动完成两步：
|
||||
|
||||
1. **SearchExtraTools** -- 搜索并发现需要的工具
|
||||
2. **ExecuteExtraTool** -- 加载并执行发现的工具
|
||||
|
||||
这个过程对用户完全透明。比如你说"帮我创建一个定时任务，每 5 分钟检查部署状态"，Claude Code 会自动搜索 `CronCreate` 工具，然后执行它。你不需要手动触发任何操作。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想让 Claude Code 自动执行多步任务，看 [第六章：子代理、Plan 模式、Task 系统](./06-agents-plans-tasks.md)
|
||||
- 想省钱和优化性能，看 [第九章：穷鬼模式、缓存、Hooks、配置文件](./09-budget-caches-hooks.md)
|
||||
- 遇到 MCP server 连接问题，看 [第十章：可观测性与排错](./10-observability-troubleshooting.md)
|
||||
300
docs/outline-output/user/06-agents-plan-tasks.md
Normal file
300
docs/outline-output/user/06-agents-plan-tasks.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# 第六章：让 Claude 帮你跑大任务 -- 子代理、Plan 模式、Task 系统
|
||||
|
||||
> 当任务太大、一步做不完时，如何让 Claude 自己拆分、规划和并行推进。
|
||||
|
||||
## 什么时候该"升级"任务处理方式
|
||||
|
||||
日常对话中，你给 Claude 一条指令，它执行一次就完成了。但有些任务天然不适合一口气干完：代码库迁移涉及几十个文件、排查 bug 需要同时在多处搜索、重构需要先理清依赖再动手。在这些场景下，三个工具能帮你把大任务拆小：**子代理（Agent）** 处理独立的子任务，**Plan 模式** 先想清楚再动手，**Task 系统** 跟踪进度和依赖。
|
||||
|
||||
一个简单的判断标准：如果你发现自己反复对 Claude 说"再看看那个文件"、"顺便改一下这个"，说明这个任务已经需要拆分了。
|
||||
|
||||
## 子代理：让 Claude 派一个"分身"去干活
|
||||
|
||||
Claude Code 有一个 Agent 工具，允许 Claude 在对话过程中派生出子代理来处理子任务。子代理有自己的上下文和工具集，完成后会把结果汇报给主对话。你不需要手动启动子代理 -- 当 Claude 判断某个子任务适合独立处理时，它会自动使用 Agent 工具。
|
||||
|
||||
### 内置的子代理类型
|
||||
|
||||
Claude Code 内置了几种专门化的子代理，各有分工：
|
||||
|
||||
- **general-purpose** -- 通用子代理，能使用全部工具。当你让 Claude 做一个需要多步骤研究或跨文件分析的任务时，它可能会派这个子代理去执行。
|
||||
- **Explore** -- 只读搜索专家，不能修改任何文件。擅长用 Glob、Grep、FileRead 快速在代码库中定位文件和关键词。当你问"这个功能在代码里怎么实现的"时，Explore 子代理会并行搜索多个路径然后汇总结果。
|
||||
- **Plan** -- 架构规划师，同样只读。它会深入阅读代码、理解现有架构，然后输出一份包含步骤和关键文件的实施方案。
|
||||
|
||||
你不需要记住这些类型名。Claude 会根据你的问题自动选择合适的子代理。
|
||||
|
||||
### 子代理是怎么工作的
|
||||
|
||||
当你给 Claude 一个复杂指令时，它可能会这样处理：
|
||||
|
||||
```
|
||||
你: 把 src/utils/ 下所有用到 deprecatedFunction 的地方重构掉
|
||||
|
||||
Claude: [使用 Agent 工具，派出一个 Explore 子代理搜索所有引用]
|
||||
|
||||
> Agent (Explore): 正在搜索 src/utils/ 下的 deprecatedFunction 引用...
|
||||
|
||||
[子代理完成，返回搜索结果]
|
||||
|
||||
Claude: 找到了 12 处引用，分布在 5 个文件中。让我逐一替换...
|
||||
```
|
||||
|
||||
子代理运行时，你会看到一个带颜色的进度提示，标明子代理的类型和当前状态。每个子代理的输出会作为一条消息出现在对话中，Claude 主线程会基于这些结果继续工作。
|
||||
|
||||
子代理之间也可以形成层级：主对话可以派子代理，子代理在复杂场景下还能继续派更小的子代理（取决于配置和 feature flag）。
|
||||
|
||||
### 关于并行子代理
|
||||
|
||||
当你使用一些 Skill（如 `ultra-batch` 或 `dispatching-parallel-agents`）时，可以显式要求 Claude 同时派发多个子代理并行处理不同子任务。这在需要同时探索多个代码路径、或同时修改多个独立文件时特别高效。
|
||||
|
||||
```
|
||||
你: 用 3 个子代理同时查一下 authentication、authorization 和 session 管理的实现
|
||||
|
||||
Claude: [同时派出 3 个 Explore 子代理，并行搜索]
|
||||
> Agent #1 (Explore): 搜索 authentication 相关文件...
|
||||
> Agent #2 (Explore): 搜索 authorization 相关文件...
|
||||
> Agent #3 (Explore): 搜索 session 管理相关文件...
|
||||
|
||||
[三个子代理各自返回结果，Claude 汇总]
|
||||
```
|
||||
|
||||
## Task 系统：跟踪任务进度和依赖
|
||||
|
||||
Task 系统提供了一套完整的任务管理工具，让 Claude 能够像使用待办清单一样跟踪工作进度。这套工具包括 `TaskCreate`、`TaskUpdate`、`TaskList` 和 `TaskGet`。
|
||||
|
||||
### 任务是怎么创建的
|
||||
|
||||
Claude 会在拆分大任务时自动使用 `TaskCreate` 创建子任务。你也可以在对话中明确要求它创建任务清单：
|
||||
|
||||
```
|
||||
你: 帮我把用户模块重构拆成任务清单
|
||||
|
||||
Claude: [使用 TaskCreate 创建任务]
|
||||
|
||||
> Task #1 created: 提取用户验证逻辑到独立 service
|
||||
> Task #2 created: 重构用户数据模型，添加类型约束
|
||||
> Task #3 created: 更新 API 路由使用新的 service 层
|
||||
> Task #4 created: 编写单元测试覆盖新 service
|
||||
```
|
||||
|
||||
每个任务包含标题（subject）、描述（description）和状态（pending / in_progress / completed）。创建任务时，Claude 还可以设置 `activeForm`（进行中时显示的活动描述，如"Running tests"），以及任意的 `metadata` 键值对。
|
||||
|
||||
### 任务状态流转
|
||||
|
||||
任务创建后默认是 `pending` 状态。Claude 会用 `TaskUpdate` 把任务标记为 `in_progress`（开始执行）、`completed`（完成）或 `deleted`（删除）。
|
||||
|
||||
```
|
||||
你: 继续执行任务清单
|
||||
|
||||
Claude: [使用 TaskUpdate 更新状态]
|
||||
|
||||
> Updated task #1 in_progress, status
|
||||
[开始执行第一个任务...]
|
||||
|
||||
> Updated task #1 completed, status
|
||||
> Updated task #2 in_progress, status
|
||||
[继续下一个任务...]
|
||||
```
|
||||
|
||||
用 `TaskList` 可以随时查看所有任务的当前状态：
|
||||
|
||||
```
|
||||
#1 [in_progress] 提取用户验证逻辑到独立 service
|
||||
#2 [pending] 重构用户数据模型，添加类型约束
|
||||
#3 [pending] 更新 API 路由使用新的 service 层
|
||||
#4 [pending] 编写单元测试覆盖新 service
|
||||
```
|
||||
|
||||
`TaskGet` 则用于查看单个任务的完整详情，包括描述和依赖关系。
|
||||
|
||||
### 任务依赖
|
||||
|
||||
任务之间可以设置阻塞关系。如果任务 A 阻塞了任务 B（task B 被 task A blocked），那么在 A 完成之前，B 无法开始。Claude 在规划执行顺序时会参考这些依赖关系：
|
||||
|
||||
```
|
||||
#1 [completed] 提取用户验证逻辑到独立 service
|
||||
#2 [in_progress] 重构用户数据模型，添加类型约束
|
||||
#3 [blocked by #2] 更新 API 路由使用新的 service 层
|
||||
#4 [blocked by #3] 编写单元测试覆盖新 service
|
||||
```
|
||||
|
||||
### 任务钩子
|
||||
|
||||
Task 系统支持 hooks 集成。你可以在 `settings.json` 中配置 hooks，让特定事件（如任务创建、任务完成）触发自定义逻辑。比如，当某个关键任务完成时自动运行测试套件。
|
||||
|
||||
## Plan 模式：先想清楚再动手
|
||||
|
||||
Plan 模式是处理复杂任务的最佳实践。进入 Plan 模式后，Claude 会切换到只读状态：它可以搜索代码、阅读文件、分析架构，但不能修改任何文件。等方案设计完毕并获得你的批准后，才退出 Plan 模式开始实际编码。
|
||||
|
||||
### 进入 Plan 模式
|
||||
|
||||
有两种方式进入 Plan 模式：
|
||||
|
||||
**方式一：用 `/plan` 命令**
|
||||
|
||||
```
|
||||
/plan 重构用户模块的数据层
|
||||
```
|
||||
|
||||
这会启用 Plan 模式，并把你给出的描述作为规划目标。Claude 会在只读状态下探索代码库、设计实施方案。
|
||||
|
||||
**方式二：让 Claude 自动进入**
|
||||
|
||||
对于足够复杂的任务，Claude 会自动调用 `EnterPlanMode` 工具进入 Plan 模式。你不需要显式要求，但可以用 `/plan` 强制进入。
|
||||
|
||||
### Plan 模式下发生了什么
|
||||
|
||||
进入 Plan 模式后，权限模式会切换为 `plan`。在这个模式下：
|
||||
|
||||
- Claude 只能使用只读工具（Read、Glob、Grep、Bash 的只读操作）
|
||||
- 文件编辑工具（Edit、Write）被禁用
|
||||
- Claude 会深入探索代码库，理解现有模式和架构
|
||||
- Claude 可能会问你一些问题来澄清需求
|
||||
|
||||
Claude 会把规划结果写入一个计划文件。你可以随时用 `/plan` 查看当前计划，或用 `/plan open` 在你的默认编辑器中打开并手动修改计划内容。
|
||||
|
||||
### 退出 Plan 模式并开始执行
|
||||
|
||||
当 Claude 完成规划后，它会调用 `ExitPlanMode` 工具。这时你会看到一个审批对话框，显示完整的计划内容。你可以：
|
||||
|
||||
- **批准** -- Claude 立即开始按计划编码
|
||||
- **编辑** -- 在编辑器中修改计划，然后批准修改后的版本
|
||||
- **拒绝** -- 让 Claude 重新规划
|
||||
|
||||
批准后，权限模式会恢复到进入 Plan 模式之前的状态（通常是 `default` 或 `auto`），Claude 开始按计划执行。
|
||||
|
||||
### VerifyPlanExecution：确认计划已正确执行
|
||||
|
||||
在较新的版本中，Claude 在退出 Plan 模式之前可能会调用 `VerifyPlanExecution` 工具，对计划的执行情况进行校验。它会检查：
|
||||
|
||||
- 计划中的所有步骤是否都已完成
|
||||
- 测试是否通过
|
||||
- 关键文件是否已正确创建或修改
|
||||
|
||||
如果某些步骤被跳过或失败了，验证结果中会包含说明。
|
||||
|
||||
## Goal 命令：给 Claude 一个自主推进的目标
|
||||
|
||||
`/goal` 命令让你给 Claude 设定一个长期目标，然后 Claude 会自主地持续工作直到目标达成，而不是等你一轮一轮地下指令。
|
||||
|
||||
### 设置和查看目标
|
||||
|
||||
```
|
||||
/goal 把所有 API 端点从 REST 迁移到 GraphQL
|
||||
```
|
||||
|
||||
这会设定一个目标。Claude 会开始自主规划、拆分任务、执行修改，每完成一轮会自动继续下一轮。你可以随时查看目标状态：
|
||||
|
||||
```
|
||||
/goal status
|
||||
```
|
||||
|
||||
输出会显示目标描述、当前状态、已用 token 数量、活跃时间和已执行的轮次。
|
||||
|
||||
### 控制目标进度
|
||||
|
||||
`/goal` 支持几个子命令来控制执行：
|
||||
|
||||
- `/goal pause` -- 暂停自动继续
|
||||
- `/goal resume` -- 从暂停恢复
|
||||
- `/goal continue` -- 在达到最大轮次限制后重置计数器继续
|
||||
- `/goal complete` -- 手动标记目标已完成
|
||||
- `/goal clear` -- 清除当前目标
|
||||
|
||||
当 Claude 遇到无法自行解决的阻塞时，它会用 `GoalTool` 将目标标记为 `blocked` 并说明原因。连续 3 轮遇到同样的阻塞条件后，目标会被自动标记为阻塞状态，等待你介入。
|
||||
|
||||
### Goal 与 Task 系统的配合
|
||||
|
||||
`/goal` 通常会与 Task 系统配合使用。Claude 设定目标后会自动创建任务清单，然后逐个执行。你可以在 `/workflows` 面板中同时看到目标和任务的状态。
|
||||
|
||||
## Worktree 隔离：在独立分支里做实验
|
||||
|
||||
当你需要做一些可能有风险或需要独立验证的改动时，Claude 可以用 `EnterWorktree` 工具创建一个 git worktree -- 一个独立的工作目录，关联到一个新的 git 分支。
|
||||
|
||||
### Claude 如何使用 Worktree
|
||||
|
||||
你不需要手动管理 worktree。当你告诉 Claude 做一些需要隔离的操作时，它可能会自动调用 `EnterWorktree`：
|
||||
|
||||
```
|
||||
你: 试试把 ORM 从 Prisma 换成 Drizzle，先在一个独立分支上验证可行性
|
||||
```
|
||||
|
||||
Claude 会创建一个 worktree，在新分支上做实验，完成后汇报结果。你的主工作目录完全不受影响。
|
||||
|
||||
### Worktree 的生命周期
|
||||
|
||||
- **创建**：`EnterWorktree` 创建 worktree 和关联分支，会话切换到 worktree 目录
|
||||
- **退出 -- 保留**：`ExitWorktree(action: "keep")` 保留 worktree 和分支，会话切回原目录
|
||||
- **退出 -- 删除**：`ExitWorktree(action: "remove")` 删除 worktree 和分支。如果有未提交的改动或未合并的 commit，Claude 会先列出它们，需要你确认并传入 `discard_changes: true` 才会执行删除
|
||||
|
||||
你也可以在启动 Claude 时直接指定 worktree 模式：
|
||||
|
||||
```bash
|
||||
claude --tmux --worktree
|
||||
```
|
||||
|
||||
这会自动创建一个 worktree 并在 tmux 会话中运行。
|
||||
|
||||
## Coordinator 模式：多 Worker 协作
|
||||
|
||||
Coordinator 模式是一个高级特性（需要 `COORDINATOR_MODE` feature flag），把 Claude 变成一个任务调度器。启用后，Claude 只能使用 Agent（派发子任务）、SendMessage（给子代理发消息）和 TaskStop（停止子任务）三个工具，不再直接执行任何操作。
|
||||
|
||||
### 启用 Coordinator 模式
|
||||
|
||||
```
|
||||
/coordinator
|
||||
```
|
||||
|
||||
启用后，Claude 会变成一个编排者。你给它一个大任务，它会拆分成多个子任务，然后派发给不同的 worker 子代理并行执行：
|
||||
|
||||
```
|
||||
你: 把这个 monorepo 的所有包从 CommonJS 迁移到 ESM
|
||||
|
||||
Claude (Coordinator): 我把这个任务拆成 5 个子任务，派发给 worker 执行...
|
||||
|
||||
> Agent (worker #1): 迁移 packages/utils/ ...
|
||||
> Agent (worker #2): 迁移 packages/core/ ...
|
||||
> Agent (worker #3): 迁移 packages/api/ ...
|
||||
...
|
||||
|
||||
[Worker 完成后汇报结果，Coordinator 汇总]
|
||||
```
|
||||
|
||||
再次输入 `/coordinator` 可以关闭 Coordinator 模式，恢复正常的工具使用。
|
||||
|
||||
## Workflow 脚本：固化可重放的多步工作流
|
||||
|
||||
`/workflows` 命令打开一个监控面板，实时显示当前工作流的运行状态、各阶段进度和子代理活动。这个面板适合在 Claude 执行复杂多步任务时监控整体进展。
|
||||
|
||||
在面板中，你可以看到：
|
||||
|
||||
- 当前工作流的运行状态（running / paused / completed）
|
||||
- 各阶段的进度
|
||||
- 活跃的子代理列表及其状态
|
||||
- 用键盘快捷键控制工作流（暂停、继续、取消）
|
||||
|
||||
```
|
||||
/workflows
|
||||
```
|
||||
|
||||
面板以终端 UI 形式展示，不阻塞主对话。
|
||||
|
||||
## 如何选择合适的方式
|
||||
|
||||
面对一个大任务，选择哪种方式取决于任务的性质：
|
||||
|
||||
| 场景 | 推荐方式 |
|
||||
|------|----------|
|
||||
| 需要先理解代码再动手 | Plan 模式 |
|
||||
| 需要长时间自主推进 | `/goal` |
|
||||
| 需要并行处理多个独立子任务 | Agent 子代理 / Coordinator 模式 |
|
||||
| 需要在隔离环境做实验 | Worktree |
|
||||
| 需要跟踪多个子任务的进度 | Task 系统 |
|
||||
| 需要监控复杂工作流的执行 | `/workflows` 面板 |
|
||||
|
||||
这些方式可以组合使用。比如，你可以先用 Plan 模式设计方案，然后 Claude 自动创建 Task 清单，再派子代理并行执行各任务，同时你在 `/workflows` 面板中监控进度。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想了解如何让 Claude 定时或后台执行任务，看 [第七章：Daemon、Background Sessions、Schedule](./07-daemon-bg-schedule.md)
|
||||
- 想了解如何通过 Bridge 或 RCS 远程控制这些任务，看 [第八章：跨机器与跨团队协作](./08-bridge-remote-acp.md)
|
||||
- 想了解权限模式如何影响子代理和 Plan 模式的行为，看 [第九章：省钱、提速、定制](./09-budget-caching-hooks.md)
|
||||
272
docs/outline-output/user/07-daemon-bg-schedule.md
Normal file
272
docs/outline-output/user/07-daemon-bg-schedule.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 第七章：让 Claude 长时间帮你干活 -- Daemon、Background Sessions、Schedule
|
||||
|
||||
> 任务跑太久、需要定时执行、想让 Claude 在后台默默干活 -- 这章讲三种长时间运行的方式。
|
||||
|
||||
## Daemon 是什么？跟普通对话的区别
|
||||
|
||||
你在终端里敲 `claude` 启动的是一个交互式 REPL 会话：你打字、Claude 回复、你继续问。关掉终端，会话就没了。Daemon 是一种不同的运行模式 -- 它在后台启动一个常驻进程（supervisor），由 supervisor 管理若干 worker 子进程，每个 worker 负责一种长时间任务。
|
||||
|
||||
目前 daemon 内置的 worker 类型是 `remoteControl`，它运行一个 headless bridge 循环，用于接受远程会话连接。supervisor 会监控 worker 的存活状态：如果 worker 崩溃了，supervisor 会自动重启它，使用指数退避策略（从 2 秒开始，每次翻倍，上限 120 秒）。如果 worker 在 10 秒内连续崩溃 5 次，supervisor 会把 worker "停泊"（park），不再尝试重启，避免无限重启循环。
|
||||
|
||||
Daemon 需要启用 `DAEMON` feature flag。启动 daemon 后，它会在 `~/.claude/daemon/` 下写一个状态文件（`remote-control.json`），记录 PID、工作目录、启动时间和 worker 类型，方便其他 CLI 进程查询状态或发送停止信号。
|
||||
|
||||
## 启停 Daemon
|
||||
|
||||
在终端中用 `claude daemon` 命令管理 daemon 的生命周期：
|
||||
|
||||
```bash
|
||||
# 启动 daemon supervisor（默认启动 remoteControl worker）
|
||||
claude daemon start
|
||||
|
||||
# 查看 daemon 和后台会话的统一状态
|
||||
claude daemon status
|
||||
# 或者
|
||||
claude daemon ps
|
||||
|
||||
# 停止 daemon（发送 SIGTERM，超时后 SIGKILL）
|
||||
claude daemon stop
|
||||
```
|
||||
|
||||
启动时可以指定工作目录、worker 模式、并发容量等参数：
|
||||
|
||||
```bash
|
||||
claude daemon start --dir /path/to/project --spawn-mode worktree --capacity 4 --permission-mode auto-accept --sandbox
|
||||
```
|
||||
|
||||
也可以在 REPL 里用 `/daemon` 斜杠命令执行同样的操作：
|
||||
|
||||
```
|
||||
/daemon status
|
||||
/daemon start
|
||||
/daemon stop
|
||||
/daemon bg -p "run the test suite"
|
||||
```
|
||||
|
||||
注意，`/daemon attach` 不能在 REPL 内使用 -- attach 是一个阻塞交互操作，需要在外部终端执行。
|
||||
|
||||
## Background Sessions：让 Claude 在后台跑
|
||||
|
||||
Daemon 管的是 supervisor + worker 的架构，如果你只是想让 Claude 在后台跑一个任务、不想折腾 supervisor，background sessions 是更轻量的选择。
|
||||
|
||||
### 启动后台会话
|
||||
|
||||
```bash
|
||||
# 最简方式：用 -p 参数传入提示词
|
||||
claude daemon bg -p "run the full test suite and report results"
|
||||
|
||||
# 也可以用 --bg 快捷标志
|
||||
claude --bg -p "check for lint errors and fix them"
|
||||
|
||||
# 带命名参数
|
||||
claude daemon bg --name nightly-audit -p "audit all TODO comments in src/"
|
||||
```
|
||||
|
||||
后台会话支持两种引擎：
|
||||
|
||||
- **tmux 引擎**（macOS/Linux，需要安装 tmux）：启动一个 tmux session 来运行 Claude，你可以随时 attach 进去看到交互界面。
|
||||
- **detached 引擎**（Windows 或没有 tmux 的环境）：进程脱离终端运行，日志写到文件，attach 时查看日志。
|
||||
|
||||
引擎选择是自动的：在 macOS/Linux 上优先用 tmux，如果 tmux 不可用则回退到 detached；Windows 上直接用 detached。如果使用 detached 引擎，必须带 `-p` 或 `--pipe` 参数，因为 detached 模式没有交互式终端。
|
||||
|
||||
```bash
|
||||
# 安装 tmux（macOS）
|
||||
brew install tmux
|
||||
|
||||
# 安装 tmux（Linux）
|
||||
sudo apt install tmux
|
||||
```
|
||||
|
||||
启动成功后会输出会话信息：
|
||||
|
||||
```
|
||||
Background session started: claude-bg-a1b2c3d4
|
||||
Engine: tmux
|
||||
Log: ~/.claude/sessions/logs/claude-bg-a1b2c3d4.log
|
||||
|
||||
Use `claude daemon attach claude-bg-a1b2c3d4` to reconnect.
|
||||
Use `claude daemon status` to check status.
|
||||
Use `claude daemon kill claude-bg-a1b2c3d4` to stop.
|
||||
```
|
||||
|
||||
### 管理后台会话
|
||||
|
||||
```bash
|
||||
# 列出所有活跃会话
|
||||
claude daemon status
|
||||
|
||||
# 输出示例：
|
||||
# 2 active sessions:
|
||||
#
|
||||
# PID: 12345
|
||||
# Kind: bg
|
||||
# Engine: tmux
|
||||
# Session: claude-bg-a1b2c3d4
|
||||
# CWD: /home/user/myproject
|
||||
# Name: nightly-audit
|
||||
# Started: 6/14/2026, 9:00:00 AM
|
||||
#
|
||||
# PID: 12346
|
||||
# Kind: daemon-worker
|
||||
# Engine: tmux
|
||||
# Session: claude-bg-e5f6g7h8
|
||||
# CWD: /home/user/myproject
|
||||
# Started: 6/14/2026, 9:00:05 AM
|
||||
|
||||
# 重新连接到会话（tmux 引擎直接进入交互界面）
|
||||
claude daemon attach claude-bg-a1b2c3d4
|
||||
|
||||
# 查看会话日志
|
||||
claude daemon logs claude-bg-a1b2c3d4
|
||||
|
||||
# 终止会话（SIGTERM -> 2秒等待 -> SIGKILL）
|
||||
claude daemon kill claude-bg-a1b2c3d4
|
||||
```
|
||||
|
||||
如果没有指定目标名称，`attach` 和 `kill` 会列出可用的会话让你选择。会话的元数据（PID、session ID、名称、启动时间等）保存在 `~/.claude/sessions/` 目录下的 JSON 文件中，进程退出后对应的 JSON 文件会被自动清理。
|
||||
|
||||
## Template Jobs：模板化任务
|
||||
|
||||
如果你经常重复执行某种结构的任务 -- 比如每天写日报、每周做代码审查 -- 可以用模板把任务的结构固定下来，之后只需 `claude job new <template>` 就能快速创建。
|
||||
|
||||
模板是放在 `.claude/templates/` 或 `~/.claude/templates/` 目录下的 Markdown 文件，支持 frontmatter：
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate a daily standup summary from git log
|
||||
author: team-lead
|
||||
---
|
||||
|
||||
Read the git log from the last 24 hours and write a concise standup summary.
|
||||
Include: commits made, PRs opened/closed, blockers encountered.
|
||||
Format the output as a bullet list.
|
||||
```
|
||||
|
||||
```bash
|
||||
# 列出所有可用模板
|
||||
claude job list
|
||||
|
||||
# 用模板创建一个新任务
|
||||
claude job new daily-standup
|
||||
|
||||
# 带参数
|
||||
claude job new daily-standup --since yesterday
|
||||
|
||||
# 查看任务状态
|
||||
claude job status abc12345
|
||||
|
||||
# 向已有任务追加回复
|
||||
claude job reply abc12345 please also include deployment notes
|
||||
```
|
||||
|
||||
模板查找顺序：先在项目的 `.claude/templates/` 目录下找，再在用户级的 `~/.claude/templates/` 目录下找，同名模板项目级优先。每个任务创建后会在 `~/.claude/jobs/<job-id>/` 下生成 `state.json`、`template.md` 和 `input.txt`，记录任务的状态和上下文。
|
||||
|
||||
## 定时调度：用 `/loop` 让 Claude 反复跑
|
||||
|
||||
`/loop` 是一种本地定时机制 -- 让 Claude 按固定间隔反复执行同一个提示词或斜杠命令，适合持续监控、定时巡检等场景。
|
||||
|
||||
```bash
|
||||
# 每 5 分钟跑一次 /babysit-prs
|
||||
/loop 5m /babysit-prs
|
||||
|
||||
# 每 30 分钟检查一次部署状态（默认 10 分钟间隔）
|
||||
/loop 30m check the deploy status
|
||||
|
||||
# 每 2 小时做一次 standup
|
||||
/loop 2h /standup 1
|
||||
|
||||
# 每天一次（午夜本地时间）
|
||||
/loop 1d run the nightly full test suite
|
||||
|
||||
# 也可以用自然语言描述间隔
|
||||
/loop check the deploy every 20m
|
||||
```
|
||||
|
||||
`/loop` 底层通过 `CronCreate` 工具创建 cron 调度，所以它遵循 cron 系统的运行规则：任务只在 REPL 空闲时触发（不会打断正在进行的查询），调度器会在你指定的时间上自动加一个小的随机偏移来错峰。循环任务最长运行 7 天后自动过期。
|
||||
|
||||
管理循环任务：
|
||||
|
||||
```bash
|
||||
# 查看当前所有定时任务
|
||||
/cron-list
|
||||
|
||||
# 取消某个任务
|
||||
/cron-delete <job-id>
|
||||
```
|
||||
|
||||
如果 `/loop` 无法使用（cron 系统被 `CLAUDE_CODE_DISABLE_CRON=1` 环境变量禁用），可以改用系统级的 cron + pipe 模式作为替代：
|
||||
|
||||
```bash
|
||||
# 在 crontab 里配置
|
||||
*/30 * * * * cd /path/to/project && echo "check the deploy status" | claude -p
|
||||
```
|
||||
|
||||
## 远程定时触发器：`/schedule` 与 `/triggers`
|
||||
|
||||
`/loop` 和本地 cron 任务有一个限制：它们只在你的本地机器上运行，关了终端就停了。如果你需要任务在云端定时执行 -- 不依赖你的电脑是否开机 -- 可以使用远程触发器。
|
||||
|
||||
```
|
||||
/schedule
|
||||
```
|
||||
|
||||
这个命令（也叫 `/triggers` 或 `/cron`）会引导你创建一个远程调度触发器。远程触发器的特点：
|
||||
|
||||
- 任务在 Anthropic 的云端基础设施中运行，不在你的本地机器上
|
||||
- 每个 trigger 在指定时间创建一个完全隔离的远程会话（CCR）
|
||||
- 最小调度间隔为 1 小时（本地 cron 没有这个限制）
|
||||
- 需要 Claude Pro/Max/Team 订阅和 `/login` 登录
|
||||
|
||||
创建一个远程触发器的交互流程大致如下：
|
||||
|
||||
```
|
||||
你: /schedule
|
||||
|
||||
Claude: What would you like to do with scheduled remote agents?
|
||||
1. Create a new trigger
|
||||
2. List existing triggers
|
||||
3. Update a trigger
|
||||
4. Run a trigger now
|
||||
|
||||
你: 我想创建一个每周一早上 9 点检查主分支 CI 状态的触发器
|
||||
|
||||
Claude: 好的，让我帮你设置。9am 你的本地时间（Asia/Shanghai）= 1am UTC。
|
||||
触发器的 cron 表达式将是 `0 1 * * 1`。
|
||||
我会使用默认模型 claude-sonnet-4-6。你确认吗？...
|
||||
```
|
||||
|
||||
远程触发器也可以通过命令参数直接操作：
|
||||
|
||||
```
|
||||
/schedule list
|
||||
/schedule get <trigger-id>
|
||||
/schedule update <trigger-id> enabled false
|
||||
/schedule run <trigger-id>
|
||||
/schedule delete <trigger-id>
|
||||
/schedule enable <trigger-id>
|
||||
/schedule disable <trigger-id>
|
||||
```
|
||||
|
||||
创建触发器时可以关联 MCP connector（比如 Datadog、Slack），让远程 agent 能访问外部服务。connector 在 https://claude.ai/settings/connectors 管理。删除触发器需要到网页端操作：https://claude.ai/code/scheduled
|
||||
|
||||
## 该用哪种方式？
|
||||
|
||||
三种长时间运行的方式各有适用场景：
|
||||
|
||||
| 方式 | 适用场景 | 是否需要本地机器在线 | 最小间隔 |
|
||||
|------|---------|---------------------|---------|
|
||||
| Background Session | 一次性后台任务，跑完就结束 | 是 | 无（一次性） |
|
||||
| `/loop` + 本地 cron | 周期性本地监控、巡检、自动修复 | 是（终端不能关） | 1 分钟 |
|
||||
| `/schedule` 远程触发器 | 云端定时任务，不依赖本地机器 | 否 | 1 小时 |
|
||||
|
||||
简单判断标准：
|
||||
|
||||
- 如果是"跑完一个任务就行"，用 background session。
|
||||
- 如果是"每隔几分钟帮我检查一下"，用 `/loop`。
|
||||
- 如果是"我不在线的时候也要跑"，用 `/schedule` 远程触发器。
|
||||
|
||||
如果你需要 tmux 引擎但机器上没有安装 tmux，系统会自动回退到 detached 引擎。detached 引擎没有交互界面，所有输出只能通过日志文件查看，所以一定要带 `-p` 参数明确告诉 Claude 该做什么。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想了解如何把 Claude 嵌入 CI 流水线做自动化，看 [第十一章：自动化与 CI 集成](./11-ci-automation.md)
|
||||
- 想让 Claude 在远程机器上被外部客户端调用，看 [第八章：跨机器与跨团队协作](./08-bridge-remote-acp.md)
|
||||
- 想了解如何让 Claude 跑大任务、派子代理，看 [第六章：让 Claude 帮你跑大任务](./06-agents-plan-task.md)
|
||||
271
docs/outline-output/user/08-bridge-rcs-acp.md
Normal file
271
docs/outline-output/user/08-bridge-rcs-acp.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# 第八章：跨机器与跨团队协作 -- Bridge、Remote Control、ACP
|
||||
|
||||
> 让 Claude 从另一台机器、浏览器或 IDE 里被操控。
|
||||
|
||||
## Bridge 模式与 Remote Control -- 在浏览器里用 Claude
|
||||
|
||||
Bridge 模式是 Claude Code 的远程控制核心。启用后，你的本地 Claude Code 会话可以被远程客户端（浏览器、Web UI、其他工具）访问和操控。这在你想从另一台机器控制本地的 Claude，或者让团队成员在浏览器里审批权限请求时特别有用。
|
||||
|
||||
Bridge 由 `BRIDGE_MODE` feature flag 控制，dev 模式和默认构建都已启用。你不需要额外做任何事来开启它，只需要使用对应命令即可。
|
||||
|
||||
有两种常见的启动方式。第一种是从 REPL 内部启动：在 Claude Code 的对话中输入 `/remote-control`，它会将当前会话桥接到远程控制服务，并在终端显示一个 URL。
|
||||
|
||||
```
|
||||
> /remote-control
|
||||
Remote Control connecting...
|
||||
This session is available via Remote Control at https://rcs.example.com/code?bridge=abc123
|
||||
```
|
||||
|
||||
再次输入 `/remote-control` 会弹出对话框，提供三个选项：断开连接、显示二维码（方便手机扫码）、或继续当前连接。
|
||||
|
||||
第二种方式是通过命令行直接启动，这会进入"环境型"Remote Control 模式，注册一个可被分配工作的环境：
|
||||
|
||||
```bash
|
||||
# 以下五个命令完全等价
|
||||
claude remote-control
|
||||
claude rc
|
||||
claude remote
|
||||
claude sync
|
||||
claude bridge
|
||||
```
|
||||
|
||||
启动后，终端会持续轮询任务，等待远程客户端分配工作。浏览器打开终端显示的 URL 后即可创建会话、发送消息、审批权限请求。
|
||||
|
||||
### 自托管 Remote Control Server (RCS)
|
||||
|
||||
RCS 是 Bridge 模式的服务端，负责接收 CLI 的注册、分发任务、转发消息。它可以部署在你自己的服务器上，所有数据流经你控制的网络，不经过任何第三方基础设施。
|
||||
|
||||
RCS 是一个纯内存的 HTTP + WebSocket 服务，基于 Hono 框架构建。它支持两套传输协议：V1 的 WebSocket 长连接和 V2 的 SSE + HTTP POST。
|
||||
|
||||
部署 RCS 最简单的方式是 Docker。在项目根目录执行：
|
||||
|
||||
```bash
|
||||
docker build -t rcs:latest -f packages/remote-control-server/Dockerfile .
|
||||
```
|
||||
|
||||
然后启动容器：
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name rcs \
|
||||
-p 3000:3000 \
|
||||
-e RCS_API_KEYS=sk-rcs-your-secret-key-here \
|
||||
-e RCS_BASE_URL=https://rcs.example.com \
|
||||
--restart unless-stopped \
|
||||
rcs:latest
|
||||
```
|
||||
|
||||
也可以用 Docker Compose：
|
||||
|
||||
```yaml
|
||||
version: "3.8"
|
||||
services:
|
||||
rcs:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: packages/remote-control-server/Dockerfile
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
- RCS_API_KEYS=sk-rcs-your-secret-key-here
|
||||
- RCS_BASE_URL=https://rcs.example.com
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
RCS 的核心配置通过环境变量控制。`RCS_API_KEYS` 是唯一的必填项，它既是客户端认证的 API Key，也用于 JWT 令牌签名，务必设置一个足够强的密钥。
|
||||
|
||||
在 Claude Code 这边，连接到自托管 RCS 只需要设置两个环境变量：
|
||||
|
||||
```bash
|
||||
export CLAUDE_BRIDGE_BASE_URL="https://rcs.example.com"
|
||||
export CLAUDE_BRIDGE_OAUTH_TOKEN="sk-rcs-your-secret-key-here"
|
||||
```
|
||||
|
||||
设置 `CLAUDE_BRIDGE_BASE_URL` 后，代码会自动识别为自托管模式，跳过所有云端门控检查，不需要 claude.ai 账户。之后正常启动 Claude Code 并执行 `/remote-control` 即可。
|
||||
|
||||
如果你使用反向代理（Nginx 或 Caddy），需要确保代理支持 WebSocket 升级：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name rcs.example.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:3000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 86400s;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Caddy 会自动处理 WebSocket 升级，配置更简单：
|
||||
|
||||
```
|
||||
rcs.example.com {
|
||||
reverse_proxy localhost:3000
|
||||
}
|
||||
```
|
||||
|
||||
### RCS Web UI
|
||||
|
||||
RCS 自带一个 Web 控制面板，通过 `/code/*` 路径访问。它是一个 React 19 + Vite + Radix UI 构建的单页应用，支持暗色和亮色主题切换。
|
||||
|
||||
Web UI 提供的核心功能包括：
|
||||
|
||||
- 查看所有已注册的运行环境，区分 Claude Code 和 ACP Agent 类型
|
||||
- 创建和管理远程会话，实时查看对话消息和工具调用
|
||||
- 审批 Claude Code 的工具权限请求，支持六种权限模式切换
|
||||
- 查看 Plan 可视化，包含进度条、状态图标和优先级标签
|
||||
- 查看 Autopilot 状态（`standby` 等待下一轮、`sleeping` 模型休眠中）
|
||||
- 通过 QR 码扫码快速连接
|
||||
|
||||
Web UI 使用 UUID 认证，无需用户账户系统，适合部署在受信任的内网环境中。
|
||||
|
||||
## ACP 协议 -- 把 Claude Code 接入 IDE
|
||||
|
||||
ACP（Agent Client Protocol）是一种标准化的 stdio 协议，允许 IDE 和编辑器通过 stdin/stdout 的 NDJSON 流驱动 AI Agent。Claude Code 实现了完整的 ACP agent 端，可以被 Zed、Cursor 等支持 ACP 的客户端直接调用。
|
||||
|
||||
启用 ACP 模式只需要 `--acp` 参数。它是一个 CLI 快速路径（位于 `src/entrypoints/cli.tsx` 中），由 `FEATURE_ACP` feature flag 控制。
|
||||
|
||||
```bash
|
||||
claude --acp
|
||||
```
|
||||
|
||||
启动后，Claude Code 不再进入 REPL，而是通过 stdin/stdout 与 ACP 客户端通信。所有 console 输出都被重定向到 stderr，避免干扰 ACP 的 NDJSON 协议流。
|
||||
|
||||
### 在 Zed 中接入 Claude Code
|
||||
|
||||
Zed 是最典型的 ACP 客户端。打开 Zed 的设置（`Cmd+,`），在 `settings.json` 中添加：
|
||||
|
||||
```json
|
||||
{
|
||||
"agent_servers": {
|
||||
"claude-code": {
|
||||
"type": "custom",
|
||||
"command": "claude",
|
||||
"args": ["--acp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你需要显式传入 API 凭证（而不是依赖 `settings.json` 中的配置），可以在 `env` 字段中指定：
|
||||
|
||||
```json
|
||||
{
|
||||
"agent_servers": {
|
||||
"claude-code": {
|
||||
"command": "claude",
|
||||
"args": ["--acp"],
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "https://api.example.com/v1",
|
||||
"ANTHROPIC_AUTH_TOKEN": "sk-xxx"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
重启 Zed 后，按 `Cmd+'` 打开 Agent Panel，在顶部下拉菜单中选择 "claude-code" 即可开始对话。
|
||||
|
||||
在 ACP 模式下，Claude Code 支持完整的会话管理（新建、恢复、加载、分叉、关闭）、斜杠命令和 Skills（输入 `/` 查看列表，如 `/commit`、`/review`）、权限审批、模型切换和模式切换。当 Zed 重启时，之前的会话可以自动恢复并回放历史消息。
|
||||
|
||||
### 权限模式与 ACP 权限管道
|
||||
|
||||
ACP 模式下的权限系统与 REPL 模式略有不同。当 Claude 需要使用某个工具时，权限请求会被转发到 ACP 客户端（如 Zed），由用户在 IDE 中选择 Allow、Reject 或 Always Allow。
|
||||
|
||||
支持六种权限模式：`default`（每次确认）、`auto`（自动判断）、`acceptEdits`（自动接受文件编辑）、`plan`（规划模式）、`dontAsk`（不询问，未预批准则拒绝）、`bypassPermissions`（绕过所有权限检查，仅在非 root 或 sandbox 环境下可用）。
|
||||
|
||||
权限模式可以通过环境变量设置默认值：
|
||||
|
||||
```bash
|
||||
ACP_PERMISSION_MODE=auto claude --acp
|
||||
```
|
||||
|
||||
也可以在 ACP 客户端中动态切换。当 Claude 处于 Plan 模式并执行退出计划时，ACP 会显示一个特殊的选项面板，让你选择退出后进入哪种模式（auto、acceptEdits、default、plan、bypassPermissions）。
|
||||
|
||||
## acp-link -- 通过网络暴露 ACP Agent
|
||||
|
||||
ACP 协议本身基于 stdio，意味着 ACP agent 只能在本机使用。`acp-link` 是一个 WebSocket 代理服务器，将远程 WebSocket 客户端桥接到本地 ACP agent 的 stdio 接口，让 ACP agent 可以通过网络访问。
|
||||
|
||||
### 独立使用
|
||||
|
||||
最基本的用法：启动 acp-link，让它管理一个 ACP agent 子进程：
|
||||
|
||||
```bash
|
||||
acp-link claude --acp
|
||||
```
|
||||
|
||||
默认监听 `localhost:9315`。你也可以指定端口和主机：
|
||||
|
||||
```bash
|
||||
acp-link --port 9000 --host 0.0.0.0 claude --acp
|
||||
```
|
||||
|
||||
启用 HTTPS（自动生成自签名证书）：
|
||||
|
||||
```bash
|
||||
acp-link --https claude --acp
|
||||
```
|
||||
|
||||
acp-link 启动后会自动生成一个随机认证 token。WebSocket 客户端通过 `rcs.auth.<base64url-token>` 子协议传递 token。如果需要固定 token：
|
||||
|
||||
```bash
|
||||
ACP_AUTH_TOKEN=my-fixed-token acp-link claude --acp
|
||||
```
|
||||
|
||||
开发环境下可以禁用认证（不推荐在生产环境使用）：
|
||||
|
||||
```bash
|
||||
acp-link --no-auth claude --acp
|
||||
```
|
||||
|
||||
### 与 RCS 集成
|
||||
|
||||
acp-link 可以将 ACP agent 注册到 RCS，通过 RCS 的 Web UI 进行交互。设置两个环境变量即可：
|
||||
|
||||
```bash
|
||||
ACP_RCS_URL=http://localhost:3000 \
|
||||
ACP_RCS_TOKEN=sk-rcs-your-key \
|
||||
acp-link claude --acp
|
||||
```
|
||||
|
||||
注册流程分两步：首先通过 REST API 向 RCS 注册环境，然后建立 WebSocket 连接并发送 identify 消息。之后 ACP agent 会出现在 RCS Web UI 的环境列表中，与普通 Claude Code 会话一起管理和监控。
|
||||
|
||||
## IDE 集成 -- 在编辑器里使用 Claude Code
|
||||
|
||||
除了通过 ACP 协议接入 Zed 等原生 ACP 客户端，Claude Code 还提供 `/ide` 命令，帮助检测和连接正在运行的 IDE。这个命令会自动扫描本地已安装的 IDE（包括 JetBrains 系列和各种终端），并提供选择界面。
|
||||
|
||||
在 REPL 中输入：
|
||||
|
||||
```
|
||||
/ide
|
||||
```
|
||||
|
||||
Claude Code 会检测本地运行的 IDE 和支持的终端，让你选择要连接的目标。连接后，Claude Code 可以通过 IDE 的 Language Server Protocol 获取代码上下文，提供更精准的编辑建议。
|
||||
|
||||
## SSH 远程模式
|
||||
|
||||
`SSH_REMOTE` feature 允许 Claude Code 通过 SSH 在远程机器上工作。在 main.tsx 中通过 `feature('SSH_REMOTE')` 控制，当启用时会接管 `--ssh` 参数和相关的 SSH 连接逻辑。
|
||||
|
||||
启用 SSH 远程模式后，Claude Code 可以在远程机器上启动会话，通过 SSH 隧道保持通信。这对于在服务器或 CI 环境中使用 Claude Code 特别有用。`/remote-setup` 命令提供辅助设置流程，`/remote-env` 命令提供远程环境管理界面。
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Remote Control is not available in this build** -- `BRIDGE_MODE` feature flag 未启用。使用 dev 模式（`bun run dev`）默认启用，或确保构建时包含该 flag。
|
||||
|
||||
**认证失败 (401 Unauthorized)** -- 检查 `CLAUDE_BRIDGE_OAUTH_TOKEN` 是否与 RCS 的 `RCS_API_KEYS` 中的值完全匹配，注意排除多余空格或换行。
|
||||
|
||||
**WebSocket 连接中断** -- 如果使用反向代理，确认已配置 WebSocket 升级（`Upgrade` / `Connection` 头），`proxy_read_timeout` 建议设为 86400 秒。
|
||||
|
||||
**RCS 重启后数据丢失** -- RCS 使用纯内存存储，重启后所有会话和环境数据都会清除。`/app/data` 卷已预留但当前未使用。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想配置 Provider 和模型，看 [第二章](./02-providers.md)
|
||||
- 想了解权限模式和安全配置，看 [第九章](./09-budget-caching-hooks.md)
|
||||
- 想在 CI 流水线中使用 Claude Code，看 [第十一章](./11-ci-integration.md)
|
||||
- 想处理连接问题和其他报错，看 [第十章](./10-troubleshooting.md)
|
||||
320
docs/outline-output/user/09-budget-hooks-config.md
Normal file
320
docs/outline-output/user/09-budget-hooks-config.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# 第九章：省钱、提速、定制 -- 穷鬼模式、缓存、Hooks、配置文件
|
||||
|
||||
> token 账单太高、响应太慢、想让 Claude 自动响应特定事件 -- 这章帮你解决。
|
||||
|
||||
## 穷鬼模式：关掉不需要的自动任务，直接省钱
|
||||
|
||||
如果你用 Anthropic 官方 API 按量计费，可能会注意到每次对话结束时 Claude 会在后台做一些额外工作 -- 提取记忆、生成下一步建议。这些功能有用，但不是每次都需要。穷鬼模式 (`/poor`) 就是用来一键关掉它们的。
|
||||
|
||||
在 REPL 里输入 `/poor` 即可切换。你会看到类似这样的反馈：
|
||||
|
||||
```
|
||||
Poor mode ON — extract_memories and prompt_suggestion are disabled
|
||||
```
|
||||
|
||||
再次输入 `/poor` 则关闭：
|
||||
|
||||
```
|
||||
Poor mode OFF — extract_memories and prompt_suggestion are restored
|
||||
```
|
||||
|
||||
穷鬼模式关掉的核心功能有三个：`extract_memories`（每次 turn 结束后提取长期记忆）、`prompt_suggestion`（生成下一步操作建议）、以及 `verification_agent`（任务完成后自动验证结果）。这三个功能会额外消耗 API 调用和 token，关掉后只保留核心对话能力。
|
||||
|
||||
这个开关是持久化的 -- 它会写入 `settings.json` 的 `poorMode` 字段，下次启动 Claude 仍然生效。你可以用 `/config` 命令在设置界面中确认状态，也可以直接编辑 `~/.claude/settings.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"poorMode": true
|
||||
}
|
||||
```
|
||||
|
||||
穷鬼模式对所有 Provider 都生效，包括 OpenAI 兼容层、Gemini 和 Grok，因为跳过的是对话流程中的额外步骤，跟具体 API 后端无关。
|
||||
|
||||
## Prompt 缓存：为什么第二次回答更快
|
||||
|
||||
Anthropic API 有 prompt 缓存机制 -- 如果连续请求之间系统提示和对话历史没有变化，API 可以复用之前的结果，响应更快、费用更低。Claude Code 在构建过程中默认利用了这个缓存。
|
||||
|
||||
当对话变长、需要压缩（compact）时，缓存可能会被"打断"，因为压缩后的上下文和之前不同了。`PROMPT_CACHE_BREAK_DETECTION` 功能（构建时默认启用）会在压缩操作前后检测缓存是否仍然命中，帮助理解为什么某次请求变慢了。
|
||||
|
||||
对于普通用户来说，你不需要做任何特殊配置。只需要知道：保持对话的连贯性（不要频繁 `/compact`）有助于维持缓存命中，从而获得更快的响应速度。
|
||||
|
||||
## Token 预算：控制每次请求的 token 上限
|
||||
|
||||
`TOKEN_BUDGET` 功能（构建时默认启用）会在系统提示中注入当前会话的 token 使用情况，让 Claude 感知到 token 预算的存在。它和 `/cost` 命令联动 -- 当你查看费用时，看到的 token 数据就是预算追踪系统收集的。
|
||||
|
||||
这个功能对使用按量计费 API 的用户特别有用。它不会硬性限制你的使用，而是让模型在生成回复时"心中有数"，更倾向于给出精简而非冗长的回答。
|
||||
|
||||
## Hooks：让 Claude 在特定事件发生时自动执行操作
|
||||
|
||||
Hooks 是 Claude Code 的自动化基础设施。你可以在设置文件里定义"当 X 发生时，执行 Y"，比如"每次文件修改后自动跑测试"或"每次会话结束时自动提交 git 日志"。
|
||||
|
||||
### Hook 的四种类型
|
||||
|
||||
Claude Code 支持 4 种 hook 类型：
|
||||
|
||||
- **command** -- 执行 shell 命令
|
||||
- **prompt** -- 发送一个 LLM 提示请求
|
||||
- **agent** -- 启动一个代理来验证结果
|
||||
- **http** -- 向某个 URL 发送 POST 请求
|
||||
|
||||
### 可用的事件
|
||||
|
||||
Hook 可以绑定到以下事件上（在 `settings.json` 中作为 key）：
|
||||
|
||||
| 事件 | 触发时机 |
|
||||
|------|----------|
|
||||
| `PreToolUse` | 工具调用前 |
|
||||
| `PostToolUse` | 工具调用完成后 |
|
||||
| `PostToolUseFailure` | 工具调用失败时 |
|
||||
| `SessionStart` | 会话开始时 |
|
||||
| `SessionEnd` | 会话结束时 |
|
||||
| `Stop` | Claude 停止生成时 |
|
||||
| `UserPromptSubmit` | 用户提交输入时 |
|
||||
| `PreCompact` | 上下文压缩前 |
|
||||
| `PostCompact` | 上下文压缩后 |
|
||||
| `Notification` | 收到通知时 |
|
||||
| `SubagentStart` / `SubagentStop` | 子代理启停时 |
|
||||
| `FileChanged` | 文件发生变化时 |
|
||||
|
||||
### 配置示例
|
||||
|
||||
在 `settings.json` 的 `hooks` 字段中添加 hook。下面是一个实际场景：每次 Claude 调用 Bash 工具执行 `git push` 之前，自动检查是否有未提交的更改：
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Bash",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "git status --short",
|
||||
"if": "Bash(git push *)",
|
||||
"shell": "bash"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`if` 字段使用权限规则语法来过滤 -- 只有匹配 `Bash(git push *)` 模式的工具调用才会触发这个 hook，避免每次用 Bash 都执行。
|
||||
|
||||
再举一个会话启动时的例子，自动在日志中记录工作环境：
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo \"$(date): Claude session started in $(pwd)\" >> ~/.claude/session-log.txt"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 管理 Hooks
|
||||
|
||||
在 REPL 中输入 `/hooks` 会打开一个交互式配置界面，你可以浏览、添加、编辑和删除 hook。你也可以直接编辑 `settings.json`。
|
||||
|
||||
### Hook 的高级选项
|
||||
|
||||
command 类型 hook 支持这些额外字段：
|
||||
|
||||
- `shell` -- 指定 shell 解释器（`bash` 或 `powershell`），默认用 bash
|
||||
- `timeout` -- 超时时间（秒）
|
||||
- `async` -- 设为 true 则在后台运行，不阻塞主流程
|
||||
- `asyncRewake` -- 后台运行，如果退出码为 2 则唤醒模型（阻塞式错误）
|
||||
- `once` -- 设为 true 则只执行一次，之后自动删除
|
||||
- `statusMessage` -- 执行时显示的状态栏消息
|
||||
|
||||
http 类型 hook 支持通过 `headers` 字段添加自定义 HTTP 头，可以用 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量（需配合 `allowedEnvVars` 字段声明允许的变量名列表）。
|
||||
|
||||
## settings.json 与 settings.local.json：团队共享 vs 个人覆盖
|
||||
|
||||
Claude Code 的配置文件分多个层级，支持组织统一管理和个人定制。
|
||||
|
||||
### 四个配置来源
|
||||
|
||||
| 来源 | 文件位置 | 用途 | 是否提交到 git |
|
||||
|------|----------|------|---------------|
|
||||
| **managed-settings** | `/etc/claude-code/managed-settings.json`（Linux）或对应系统目录 | 组织管理员强制策略，优先级最高 | 不适用 |
|
||||
| **userSettings** | `~/.claude/settings.json` | 个人全局配置，所有项目共享 | 不适用 |
|
||||
| **projectSettings** | 项目根目录下 `.claude/settings.json` | 项目级配置，团队共享 | 应提交 |
|
||||
| **localSettings** | 项目根目录下 `.claude/settings.local.json` | 个人项目级覆盖 | 应 gitignore |
|
||||
|
||||
优先级从高到低：managed > local > project > user。后面的配置会合并（不是覆盖）前面的。比如 projectSettings 里设了 `hooks`，localSettings 里设了 `permissions`，两者都会生效。
|
||||
|
||||
### 实际用法
|
||||
|
||||
**团队协作场景**：在项目的 `.claude/settings.json` 中放入团队共享的权限规则和 hook 配置，提交到 git。团队成员各自可以在 `.claude/settings.local.json` 中添加个人偏好。
|
||||
|
||||
**个人偏好场景**：在 `~/.claude/settings.json` 中设置 `poorMode`、`defaultMode` 等全局偏好，对所有项目生效。
|
||||
|
||||
### 用 /config 命令管理
|
||||
|
||||
在 REPL 中输入 `/config` 会打开一个交互式设置界面，包含 Config、Hooks、Permissions 等标签页，可以直接修改各项配置。
|
||||
|
||||
## CLAUDE.md 四层层级：给 Claude 的项目指令
|
||||
|
||||
CLAUDE.md 是告诉 Claude "怎么理解这个项目"的文件，但它不是一个文件，而是四层层级：
|
||||
|
||||
1. **Managed**（如 `/etc/claude-code/CLAUDE.md`）-- 组织全局指令，所有用户、所有项目生效
|
||||
2. **User**（`~/.claude/CLAUDE.md`）-- 个人全局指令，你所有项目共享
|
||||
3. **Project**（项目目录下的 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md`）-- 项目级指令，通常提交到 git 让团队共享
|
||||
4. **Local**（`CLAUDE.local.md`）-- 个人项目级指令，不提交
|
||||
|
||||
加载顺序是从 Managed 到 Local，越晚加载的优先级越高（模型会更关注后加载的内容）。如果你在嵌套目录中工作，`src/CLAUDE.md` 的优先级高于项目根目录的 `CLAUDE.md`。
|
||||
|
||||
每个层级支持多个文件：比如 `.claude/rules/` 目录下的所有 `.md` 文件都会被加载。还有一个特殊机制：`.gitignore` 的规则会被用来排除不想被加载的 CLAUDE.md 文件。
|
||||
|
||||
### @include 指令：引用其他文件
|
||||
|
||||
CLAUDE.md 支持 `@include` 语法来引用其他文件内容，避免把所有东西写在一个文件里。语法有四种形式：
|
||||
|
||||
```
|
||||
@path/to/file # 相对路径（等同于 @./path/to/file）
|
||||
@./relative/path # 相对路径
|
||||
@~/home/path # 用户主目录下的路径
|
||||
@/absolute/path # 绝对路径
|
||||
```
|
||||
|
||||
比如你在项目的 `CLAUDE.md` 中写：
|
||||
|
||||
```markdown
|
||||
# 项目规范
|
||||
|
||||
请遵循以下代码规范：
|
||||
|
||||
@./docs/coding-standards.md
|
||||
|
||||
@~/claude-rules/my-personal-preferences.md
|
||||
```
|
||||
|
||||
`@include` 只在文本节点中生效（不会解析代码块内的内容），支持 60 多种文本扩展名（`.md`、`.ts`、`.py`、`.json`、`.yaml`、`.sql` 等）。不存在的文件会被静默忽略，循环引用会被自动检测和阻断。
|
||||
|
||||
## keybindings.json：自定义快捷键
|
||||
|
||||
Claude Code 的快捷键可以通过 `~/.claude/keybindings.json` 文件自定义。在 REPL 中输入 `/keybindings` 会自动生成一个模板文件（如果还没有的话）并在编辑器中打开它。
|
||||
|
||||
生成的模板包含所有可绑定的默认快捷键。你可以修改绑定值、添加新的绑定，或者设为 `null` 来取消某个快捷键。每个绑定项包含 context（如 `"normal"` 或 `"insert"`）和具体的键映射。
|
||||
|
||||
模板文件顶部会包含 JSON Schema 引用，支持编辑器的自动补全和校验：
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://www.schemastore.org/claude-code-keybindings.json",
|
||||
"$docs": "https://code.claude.com/docs/en/keybindings",
|
||||
"bindings": [
|
||||
{
|
||||
"context": "normal",
|
||||
"bindings": {
|
||||
"enter": "submit",
|
||||
"escape": "cancel"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
注意：部分快捷键是保留的（如退出快捷键），不可重新绑定，模板中已自动过滤掉这些项。
|
||||
|
||||
## 权限规则配置：控制 Claude 能做什么
|
||||
|
||||
权限规则定义了 Claude 在使用工具时需要什么样的批准。你可以在 settings 的 `permissions` 字段中配置 `allow`、`deny` 和 `ask` 规则列表。
|
||||
|
||||
### 规则语法
|
||||
|
||||
每条规则是一个字符串，格式为 `ToolName` 或 `ToolName(content)`：
|
||||
|
||||
```
|
||||
Bash # 匹配所有 Bash 工具调用
|
||||
Bash(npm test) # 只匹配执行 "npm test" 的 Bash 调用
|
||||
Bash(git *) # 匹配所有以 "git " 开头的 Bash 调用
|
||||
Read(*.ts) # 匹配所有读取 .ts 文件的操作
|
||||
Write # 匹配所有文件写入
|
||||
```
|
||||
|
||||
圆括号内的内容支持通配符 `*`。如果只写工具名不写内容（如 `Bash`），则匹配该工具的所有调用。
|
||||
|
||||
### 配置示例
|
||||
|
||||
在项目的 `.claude/settings.json` 中配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Read",
|
||||
"Glob",
|
||||
"Grep",
|
||||
"Bash(git status *)",
|
||||
"Bash(git diff *)",
|
||||
"Bash(git log *)",
|
||||
"Bash(npm test *)",
|
||||
"Bash(npm run lint *)"
|
||||
],
|
||||
"deny": [
|
||||
"Bash(rm -rf *)"
|
||||
],
|
||||
"defaultMode": "ask"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这个配置的含义是：读文件、搜索、查看 git 状态和日志、跑测试和 lint 不需要确认；`rm -rf` 命令一律拒绝；其他操作需要手动确认。
|
||||
|
||||
### 管理
|
||||
|
||||
在 REPL 中输入 `/permissions` 会打开一个交互式权限管理界面，可以添加、编辑、删除规则，还可以重试之前被拒绝的工具调用。
|
||||
|
||||
### 权限模式
|
||||
|
||||
`defaultMode` 可以设为以下值：
|
||||
- `ask` -- 每次需要工具权限时询问（默认）
|
||||
- `auto` -- 自动批准所有工具调用
|
||||
- `deny` -- 拒绝所有工具调用
|
||||
- `sandbox` -- 在沙箱环境中执行
|
||||
|
||||
在 REPL 中也可以通过 `/mode` 命令临时切换权限模式。
|
||||
|
||||
## Feature Flag 运行时开关
|
||||
|
||||
Feature flag 控制着哪些功能在运行时启用。大部分功能在构建时已经由 `DEFAULT_BUILD_FEATURES` 决定了默认状态，但你可以通过环境变量在运行时覆盖。
|
||||
|
||||
用法：设置 `FEATURE_<FLAG_NAME>=1` 来启用某个 flag。例如：
|
||||
|
||||
```bash
|
||||
FEATURE_MONITOR_TOOL=1 bun run dev
|
||||
```
|
||||
|
||||
### 已禁用的 feature flag
|
||||
|
||||
以下 flag 在构建中已被注释掉，意味着即使设置环境变量也不会生效（代码路径不存在）：
|
||||
|
||||
| Flag | 禁用原因 |
|
||||
|------|----------|
|
||||
| `CONTEXT_COLLAPSE` | 实现是空壳 stub，启用后会抑制 auto compact 导致上下文管理失效 |
|
||||
| `HISTORY_SNIP` | snip 功能暂时关闭 |
|
||||
| `FORK_SUBAGENT` | 已通过 Agent tool 的等效方式实现，无需单独功能 |
|
||||
| `UDS_INBOX` | 构建后 node.js 环境卡住 |
|
||||
| `LAN_PIPES` | 依赖 UDS_INBOX，同样有 node.js 兼容问题 |
|
||||
| `REVIEW_ARTIFACT` | API 请求无响应，待排查 schema 兼容性 |
|
||||
| `SKILL_LEARNING` | 功能暂停 |
|
||||
| `TEAMMEM` | 依赖 COORDINATOR_MODE，邮箱文件无限增长 |
|
||||
|
||||
对于这些已禁用的 flag，不要尝试启用 -- 相关代码可能不完整或不兼容。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想了解所有 slash 命令的完整分类，看 [第四章：slash 命令速查](./04-slash-commands.md)
|
||||
- 想了解 token 消费和费用查看，看 [第三章：日常对话](./03-repl-daily.md)
|
||||
- 想排查 Provider 报错或性能问题，看 [第十章：可观测性与排错](./10-troubleshooting.md)
|
||||
316
docs/outline-output/user/10-observability-troubleshooting.md
Normal file
316
docs/outline-output/user/10-observability-troubleshooting.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# 第十章：可观测性与排错 -- 卡住了怎么办
|
||||
|
||||
> Claude 报错、卡住、行为不对？本章帮你快速定位原因并解决。
|
||||
|
||||
## 第一步永远先跑：`claude doctor`
|
||||
|
||||
遇到任何不明原因的问题，第一件事是跑 `/doctor`（或在终端输入 `claude doctor`）。这个命令会自动检查你的安装环境、配置文件、MCP 连接状态、插件加载情况、版本是否最新，并给出一份结构化的诊断报告。
|
||||
|
||||
在 REPL 中输入：
|
||||
|
||||
```
|
||||
/doctor
|
||||
```
|
||||
|
||||
或在终端直接运行：
|
||||
|
||||
```bash
|
||||
claude doctor
|
||||
```
|
||||
|
||||
Doctor 会逐项检查并标记状态。常见检查项包括：
|
||||
|
||||
- 版本是否过期（与 npm 远程 `latest` / `stable` 标签对比）
|
||||
- 配置文件 (`settings.json` / `settings.local.json`) 是否有语法错误
|
||||
- MCP server 是否成功连接
|
||||
- 插件是否有加载失败
|
||||
- Sandbox / 权限相关检测
|
||||
- Keybinding 冲突警告
|
||||
|
||||
另一个快速自检命令是 `bun run health`，它会检查运行时依赖是否齐全。如果你在开发模式下使用（`bun run dev`），这个命令可以在不启动完整 REPL 的情况下快速验证环境。
|
||||
|
||||
## Provider 报错对照表
|
||||
|
||||
API 调用失败时，Claude Code 会显示错误信息。以下是常见错误码的含义和应对方法。
|
||||
|
||||
### 401 / 403 -- 认证失败
|
||||
|
||||
**401 Unauthorized**：API key 无效、过期或未设置。检查你当前的 Provider 配置：
|
||||
|
||||
```
|
||||
/provider
|
||||
```
|
||||
|
||||
确认 key 已正确设置。如果你使用 OpenAI 兼容层，确认 `OPENAI_API_KEY` 环境变量已填入有效值。
|
||||
|
||||
**403 Forbidden**：通常表示地区限制或账号权限不足。某些 API 端点对特定地区不可用，或者你的订阅计划不包含所请求的模型。
|
||||
|
||||
### 429 -- 限流
|
||||
|
||||
当请求频率超过 API 的速率限制时，你会收到 429 错误。Claude Code 会自动解析 OpenAI 兼容层的限流响应头：
|
||||
|
||||
- `x-ratelimit-remaining-requests` / `x-ratelimit-limit-requests` -- 每分钟请求数
|
||||
- `x-ratelimit-remaining-tokens` / `x-ratelimit-limit-tokens` -- 每分钟 token 数
|
||||
- `x-ratelimit-reset-requests` / `x-ratelimit-reset-tokens` -- 重置时间
|
||||
|
||||
限流发生时，最直接的做法是等一会儿再试。如果你是 Anthropic 订阅用户，可以在 REPL 中输入 `/rate-limit-options` 查看可用的升级方案。
|
||||
|
||||
### overloaded_error（1305） -- 上游过载
|
||||
|
||||
这是 Anthropic API 返回的 `overloaded_error`（错误码 1305），表示服务端暂时过载。与限流不同，这不是你的请求频率问题，而是 Anthropic 服务本身在排队。等几分钟再重试即可。
|
||||
|
||||
### 模型不存在
|
||||
|
||||
当你请求的模型名称无法被 Provider 识别时，请求会失败。例如使用 Gemini 兼容层时，如果 `GEMINI_MODEL` 和 `GEMINI_DEFAULT_SONNET_MODEL` / `GEMINI_DEFAULT_OPUS_MODEL` 都没有设置，模型映射可能找不到匹配项，Gemini 客户端会直接抛出异常。
|
||||
|
||||
确认你当前使用的模型：
|
||||
|
||||
```
|
||||
/model
|
||||
```
|
||||
|
||||
## 兼容层特有坑
|
||||
|
||||
使用 OpenAI / Gemini / Grok 兼容层时，除了上述通用错误，还可能遇到以下兼容层特有的问题。
|
||||
|
||||
### DeepSeek `reasoning_content` 缺失
|
||||
|
||||
DeepSeek 在启用思维模式时会返回 `reasoning_content` 字段。如果某次请求的响应中缺少这个字段（即使是空值），下一次请求会被 DeepSeek API 拒绝并返回 400 错误。这是因为兼容层在流适配过程中，如果未回显 `reasoning_content: ''`（空字符串），会导致 DeepSeek 的会话状态不一致。
|
||||
|
||||
如果你使用 DeepSeek 且频繁遇到 400 错误，尝试切换到普通模型（关闭思维模式），或检查你的 DeepSeek 端点版本是否支持思维模式。
|
||||
|
||||
### OpenAI 客户端缓存
|
||||
|
||||
`getOpenAIClient()` 使用模块级缓存：第一次调用后客户端实例被缓存，后续调用直接返回缓存实例。这意味着如果你在运行期间修改了 `OPENAI_API_KEY` 或 `OPENAI_BASE_URL`，新值不会生效。
|
||||
|
||||
解决方法：重启 Claude Code。在脚本或自动化场景中，需要中途更换 key 的，可以调用 `clearOpenAIClientCache()` 清除缓存。同样的问题也存在于 `getGrokClient()`。
|
||||
|
||||
### Gemini 模型映射失败
|
||||
|
||||
Gemini 是唯一在模型映射链全部缺失时直接抛出异常的 Provider。映射优先级为：`GEMINI_MODEL` > `GEMINI_DEFAULT_SONNET_MODEL` / `GEMINI_DEFAULT_OPUS_MODEL` > 默认映射表。如果默认映射表中找不到匹配项，你会看到类似以下错误：
|
||||
|
||||
```
|
||||
Gemini API request failed (404 Not Found): ...
|
||||
```
|
||||
|
||||
设置明确的模型名称可以避免这个问题：
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"GEMINI_MODEL": "gemini-2.5-pro"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Bedrock Opus 4.7 的 400 错误
|
||||
|
||||
如果你使用 AWS Bedrock 作为 Provider，调用 Opus 4.7 模型时可能遇到 400 "invalid beta flag" 错误。这是一个已知的上游 SDK bug：`@anthropic-ai/bedrock-sdk`（版本 0.26.4 至 0.28.1）会将 `anthropic-beta` HTTP 头的值错误地复制到请求体的 `anthropic_beta` 字段中，而 Bedrock 的 Opus 4.7 端点会拒绝请求体中包含此字段的请求。
|
||||
|
||||
Claude Code 通过自定义的 `BedrockClient`（继承自 `AnthropicBedrock`）自动修补这个问题：在 SDK 构建 `buildRequest` 完成后，删除请求体中的 `anthropic_beta` 字段，同时保留 HTTP 头中的正确值。
|
||||
|
||||
项目提供了 probe 脚本用于验证 SDK 状态：
|
||||
|
||||
```bash
|
||||
bun run scripts/probe-local-wiring.ts
|
||||
```
|
||||
|
||||
## MCP server 连不上
|
||||
|
||||
当 MCP server 无法连接时，检查以下几点：
|
||||
|
||||
**stdio 模式**：确认命令路径和参数正确。
|
||||
|
||||
```bash
|
||||
claude mcp list
|
||||
```
|
||||
|
||||
检查已配置的 MCP server 列表。确认 `command` 指向的可执行文件存在且可执行。
|
||||
|
||||
**SSE 模式**：确认 URL 可达、超时设置合理。如果 MCP server 启动较慢，可能需要调整超时时间。
|
||||
|
||||
**OAuth 认证**：某些 MCP server 需要 OAuth 授权。在 REPL 中使用 `/mcp-auth` 进行认证。如果认证失败，检查回调 URL 是否正确配置。
|
||||
|
||||
**MCP 配置语法错误**：`claude mcp list` 会显示解析警告。如果添加 server 后出现 `McpParsingWarnings`，说明配置 JSON 有格式问题，需要修正。
|
||||
|
||||
## 权限被拒、工具被禁用、延迟工具没加载
|
||||
|
||||
Claude Code 使用权限模式控制工具的使用。如果你发现某个工具被禁用或权限被拒：
|
||||
|
||||
1. **确认当前权限模式**：在 REPL 中输入 `/permissions` 查看当前权限规则。
|
||||
2. **权限规则配置**：在 `settings.json` 中配置 `allow` / `deny` 规则，使用工具名匹配和 glob 模式。例如：
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(npm test*)",
|
||||
"FileReadTool"
|
||||
],
|
||||
"deny": [
|
||||
"Bash(rm -rf*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **延迟工具加载**：60 个内置工具中，只有 38 个核心工具是始终加载的（`CORE_TOOLS` 白名单）。其余工具通过 `SearchExtraTools` 按需搜索和加载。如果你需要的工具没有被自动加载，可以在对话中明确提及工具名，触发搜索和加载过程。
|
||||
|
||||
## 内存膨胀与长会话
|
||||
|
||||
长时间运行的会话（daemon 模式、`/loop` 循环、大量工具调用）可能导致内存膨胀。这是因为 Bun 使用的 JSC 引擎的 `Performance` 对象将 marks/measures 存储在一个永不收缩的 C++ Vector 中。
|
||||
|
||||
Claude Code 通过 `performanceShim` 解决这个问题：它在启动时将 `globalThis.performance` 替换为 JS Map 支持的实现，`performance.now()` 仍然走原生（精确且快速），但 `mark` / `measure` / `getEntries` 操作存储在 GC 可回收的 JS 内存中。
|
||||
|
||||
如果你仍然感觉到长会话变慢，可以：
|
||||
|
||||
1. 使用 `/compact` 压缩上下文，减少内存中的消息量。
|
||||
2. 使用 `/force-snip` 强制裁剪更早的消息。
|
||||
3. 重启 Claude Code 会话。
|
||||
|
||||
## 调试模式
|
||||
|
||||
### `BUN_INSPECT` 调试器
|
||||
|
||||
使用 Bun 内置的调试器来排查运行时问题：
|
||||
|
||||
```bash
|
||||
BUN_INSPECT=9229 bun run dev:inspect
|
||||
```
|
||||
|
||||
然后连接 Chrome DevTools（打开 `chrome://inspect`）或使用 VS Code 的调试面板连接到 `ws://localhost:9229`。
|
||||
|
||||
### `--dump-system-prompt`
|
||||
|
||||
查看当前构建版本生成的完整系统提示（需要 `DUMP_SYSTEM_PROMPT` feature 启用）：
|
||||
|
||||
```bash
|
||||
FEATURE_DUMP_SYSTEM_PROMPT=1 claude --dump-system-prompt --model claude-sonnet-4-20250514
|
||||
```
|
||||
|
||||
这会将渲染后的系统提示打印到终端，适合调试 prompt 组装逻辑。
|
||||
|
||||
### `/debug-tool-call` 查看工具调用
|
||||
|
||||
在 REPL 中输入 `/debug-tool-call` 查看最近 5 次工具调用的输入和输出。指定数字可以查看更多：
|
||||
|
||||
```
|
||||
/debug-tool-call 10
|
||||
```
|
||||
|
||||
它会从当前会话的 transcript 日志中读取最近的工具调用对，显示工具名、输入参数和返回结果。
|
||||
|
||||
### `/perf-issue` 性能快照
|
||||
|
||||
当遇到性能问题时，使用 `/perf-issue` 生成一份详细的性能报告：
|
||||
|
||||
```
|
||||
/perf-issue
|
||||
```
|
||||
|
||||
报告保存到 `~/.claude/perf-reports/` 目录，包含：
|
||||
|
||||
- 进程内存使用（RSS、heap、external）
|
||||
- CPU 使用统计
|
||||
- Token 用量分解（input/output/cache_creation/cache_read）
|
||||
- 缓存命中率
|
||||
- 费用估算（基于 Anthropic 公开定价）
|
||||
- 工具调用次数和平均执行时间
|
||||
- 会话挂钟时间
|
||||
|
||||
支持三种输出格式：
|
||||
|
||||
```
|
||||
/perf-issue --format=json
|
||||
/perf-issue --format=csv
|
||||
/perf-issue --format=md
|
||||
```
|
||||
|
||||
### `/heapdump` 堆快照
|
||||
|
||||
当怀疑内存泄漏时，使用 `/heapdump` 导出 V8 堆快照文件：
|
||||
|
||||
```
|
||||
/heapdump
|
||||
```
|
||||
|
||||
快照文件会保存到桌面（`~/Desktop/`），可以用 Chrome DevTools 的 Memory 面板加载分析。
|
||||
|
||||
## Langfuse 追踪
|
||||
|
||||
如果你想深入了解每次 API 调用的细节（模型、Provider、token 消耗、工具执行链路），可以启用 Langfuse 追踪。Langfuse 是一个开源的 LLM 可观测性平台，支持自部署或使用 Langfuse Cloud。
|
||||
|
||||
在 `settings.json` 中配置三个必填环境变量：
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"LANGFUSE_PUBLIC_KEY": "pk-xxx",
|
||||
"LANGFUSE_SECRET_KEY": "sk-xxx",
|
||||
"LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
可选参数包括 `LANGFUSE_TRACING_ENVIRONMENT`（环境标签，默认 `development`）、`LANGFUSE_FLUSH_AT`（批量发送阈值，默认 20）、`LANGFUSE_FLUSH_INTERVAL`（定时刷新间隔秒数，默认 10）等。
|
||||
|
||||
未配置时，所有追踪函数为 no-op，零开销。
|
||||
|
||||
启用后，每次查询会创建一个 Trace（agent 类型），其中包含：
|
||||
|
||||
- **LLM Generation** -- 记录 API 调用，按 Provider 映射为不同名称（`ChatAnthropic`、`ChatOpenAI`、`ChatGoogleGenerativeAI`、`ChatXAI` 等）
|
||||
- **Tool Observation** -- 记录每个工具调用的输入输出和耗时
|
||||
- **子 Agent Trace** -- 通过 Agent 工具派生的子代理有独立的 Trace
|
||||
|
||||
所有上传的数据会自动脱敏：API key、token、password 等敏感字段被替换为 `[REDACTED]`，文件读写工具的输出被完全遮蔽，Shell 工具输出截断至 500 字符。
|
||||
|
||||
## 导出会话
|
||||
|
||||
当你需要把对话记录分享给同事、存档或提交 bug 报告时，可以使用以下命令：
|
||||
|
||||
- `/export` -- 导出当前会话为文件
|
||||
- `/share` -- 分享会话（具体格式取决于实现）
|
||||
- `/recap` -- 生成会话摘要
|
||||
|
||||
注意隐私边界：导出的内容可能包含你对话中的代码片段和文件内容，但不会包含 API key 等凭证。在分享前检查导出内容，确保不包含敏感信息。
|
||||
|
||||
## 反馈与上报 bug
|
||||
|
||||
### `/feedback` 提交反馈
|
||||
|
||||
在 REPL 中输入 `/feedback` 可以提交产品反馈。你可以在描述中附上遇到的问题，也可以引用 `/perf-issue` 生成的报告。
|
||||
|
||||
### `/bughunter` 自动排查
|
||||
|
||||
`/bughunter` 命令在当前版本中为 stub（`isEnabled` 返回 `false`），尚未实现。
|
||||
|
||||
### GitHub Issues
|
||||
|
||||
如果以上方法都无法解决问题，可以在项目 GitHub 仓库提交 Issue。提交时建议附上：
|
||||
|
||||
- `/perf-issue` 生成的性能报告
|
||||
- `/debug-tool-call` 的输出
|
||||
- 具体的错误信息和复现步骤
|
||||
- 你使用的 Provider 和模型
|
||||
|
||||
## 已知禁用的 feature flag
|
||||
|
||||
以下 feature flag 在构建时被禁用，启用可能导致核心功能异常：
|
||||
|
||||
- `CONTEXT_COLLAPSE` -- 上下文折叠（反编译丢失）
|
||||
- `HISTORY_SNIP` -- 历史剪裁（反编译丢失）
|
||||
- `FORK_SUBAGENT` -- 分叉子代理（反编译丢失）
|
||||
- `UDS_INBOX` -- Unix Domain Socket 收件箱（反编译丢失）
|
||||
- `LAN_PIPES` -- 局域管道（反编译丢失）
|
||||
- `REVIEW_ARTIFACT` -- 代码审查产物（反编译丢失）
|
||||
- `SKILL_LEARNING` -- 技能学习（原本即为 stub）
|
||||
- `TEAMMEM` -- 团队成员（原本即为 stub）
|
||||
|
||||
除非你清楚知道后果，否则不要通过 `FEATURE_<NAME>=1` 启用这些 flag。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想配置 Provider 和模型，看 [第二章](./02-providers.md)
|
||||
- 想理解 slash 命令，看 [第四章](./04-slash-commands.md)
|
||||
- 想配置 MCP server 和插件，看 [第五章](./05-mcp-plugins-skills.md)
|
||||
- 想省钱和优化性能，看 [第九章](./09-budget-cache-hooks.md)
|
||||
370
docs/outline-output/user/11-ci-integration.md
Normal file
370
docs/outline-output/user/11-ci-integration.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# 第十一章：自动化与 CI 集成 —— 把 Claude 嵌入流水线
|
||||
|
||||
> 不想每次都手动对话？让 Claude 在脚本、CI 和容器里自动干活。
|
||||
|
||||
## Pipe 模式：一句话调用，拿结果就走
|
||||
|
||||
Pipe 模式（也叫 headless / print 模式）是 Claude Code 最直接的自动化入口。不需要 TTY，不需要交互，传入提示词，拿回结果，进程退出。它在 `src/main.tsx` 里注册为 `-p, --print` 选项，描述原文是 "Print response and exit (useful for pipes)"。
|
||||
|
||||
最基本的用法：
|
||||
|
||||
```bash
|
||||
# 把结果直接输出到终端
|
||||
claude -p "解释当前目录的 package.json 依赖关系"
|
||||
|
||||
# 管道传入提示词
|
||||
echo "列出 src/ 下所有 .ts 文件" | claude -p
|
||||
|
||||
# 把结果存到文件
|
||||
claude -p "给 src/utils/hash.ts 写单元测试" > hash.test.ts
|
||||
```
|
||||
|
||||
Pipe 模式有几个值得注意的行为。第一，**信任对话框被跳过**——命令行帮助文本明确写了 "The workspace trust dialog is skipped when Claude is run with the -p mode. Only use this flag in directories you trust." 意味着 Claude 会直接在当前目录操作文件，不会先问你是否信任它。所以只在可信目录用 `-p`。
|
||||
|
||||
第二，支持结构化输出。配合 `--output-format json` 可以拿到 JSON 格式的结果，方便脚本解析：
|
||||
|
||||
```bash
|
||||
claude -p "列出 3 个最常见的 TypeScript 性能问题" --output-format json
|
||||
```
|
||||
|
||||
第三，支持流式 JSON 输出（`--output-format stream-json`），适合需要实时处理中间结果的场景。
|
||||
|
||||
第四，可以限制工具白名单。在 CI 环境中，你可能不想让 Claude 随意执行任意命令。通过 `--allowed-tools` 参数可以精确控制：
|
||||
|
||||
```bash
|
||||
claude -p "检查 package.json 里有没有废弃依赖" \
|
||||
--allowed-tools Bash(npm audit:*) Bash(cat:*) Read
|
||||
```
|
||||
|
||||
`--allowed-tools` 的值支持 glob 风格匹配，比如 `Bash(git:*)` 匹配所有 git 命令，`Bash(npm install:*)` 只允许 npm install 相关命令。
|
||||
|
||||
## Headless 模式的环境差异
|
||||
|
||||
Pipe 模式的底层走的是 headless 路径。在 `src/main.tsx` 中，headless 模式会在启动时创建一个轻量级的 `headlessStore`（Zustand store），跳过 Ink UI 渲染、MCP 交互式认证等需要 TTY 的步骤。
|
||||
|
||||
在无 TTY 的环境（CI runner、Docker 容器、cron 任务）下，Claude Code 会自动检测并进入 headless 行为。但有一个常见坑：**嵌套 bun 启动时 TTY 检测可能出错**。比如你的脚本用 bun 调用另一个 bun 进程时，子进程可能误判自己有 TTY。
|
||||
|
||||
解决方案是设置环境变量 `CLAUDE_CODE_FORCE_INTERACTIVE`：
|
||||
|
||||
```bash
|
||||
# 在 CI 脚本中，如果 Claude 意外进入了交互模式（卡住等待输入），
|
||||
# 反过来设置这个变量让 stdin/stdout/stderr 的 isTTY 被强制标记为 true
|
||||
CLAUDE_CODE_FORCE_INTERACTIVE=1 claude -p "你的提示词"
|
||||
```
|
||||
|
||||
这个环境变量的处理逻辑在 `src/entrypoints/cli.tsx` 的顶层，在 main() 函数之前就生效。它会把 `process.stdin`、`process.stdout`、`process.stderr` 的 `isTTY` 属性强行覆写为 `true`。代码注释说这是 "Best-effort dev-only override for nested bun launch on Windows"，但实际上在任何嵌套场景都可能用到。
|
||||
|
||||
`--bare` 模式是更激进的 headless 变体。它设置 `CLAUDE_CODE_SIMPLE=1`，跳过 hooks、LSP、plugin sync、attribution、auto-memory、background prefetches、keychain reads 和 CLAUDE.md 自动发现。适合只需要最原始能力的 CI 场景：
|
||||
|
||||
```bash
|
||||
claude --bare -p "解释这个函数的作用" --system-prompt "你是一个代码审查助手"
|
||||
```
|
||||
|
||||
注意 `--bare` 模式下 OAuth 和 keychain 认证不会被读取，只能通过 `ANTHROPIC_API_KEY` 环境变量或 `--settings` 参数提供凭证。
|
||||
|
||||
## 容器环境与 `CLAUDE_CODE_REMOTE`
|
||||
|
||||
在 Docker 容器或远程 CI 环境里跑 Claude Code 时，内存管理是个实际问题。Bun/JSC 的内存行为和 Node.js/V8 不同（详见设计篇），在大代码库上可能消耗较多内存。
|
||||
|
||||
`src/entrypoints/cli.tsx` 顶层有一段专门处理容器环境的逻辑：
|
||||
|
||||
```typescript
|
||||
if (process.env.CLAUDE_CODE_REMOTE === 'true') {
|
||||
const existing = process.env.NODE_OPTIONS || '';
|
||||
process.env.NODE_OPTIONS = existing
|
||||
? `${existing} --max-old-space-size=8192`
|
||||
: '--max-old-space-size=8192';
|
||||
}
|
||||
```
|
||||
|
||||
设置 `CLAUDE_CODE_REMOTE=true` 后，会自动给 `NODE_OPTIONS` 追加 `--max-old-space-size=8192`（8GB 上限）。这对 Node.js 运行时的构建产物生效——V8 引擎会尊重这个限制。容器通常有 16GB 内存配额，8GB 上限留足余量。
|
||||
|
||||
在 Docker Compose 或 CI 配置中这样用：
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
claude-worker:
|
||||
image: your-claude-image
|
||||
environment:
|
||||
- CLAUDE_CODE_REMOTE=true
|
||||
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
|
||||
working_dir: /app
|
||||
command: ["node", "dist/cli.js", "-p", "运行测试并报告结果"]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# GitHub Actions workflow
|
||||
env:
|
||||
CLAUDE_CODE_REMOTE: true
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
```
|
||||
|
||||
## GitHub Actions 集成：`install-github-app`
|
||||
|
||||
Claude Code 内置了一套完整的 GitHub Actions 自动配置流程，通过 `/install-github-app` 命令触发。这个命令是 `local-jsx` 类型（交互式 React 组件），会引导你一步步完成配置。
|
||||
|
||||
整个流程大致如下：
|
||||
|
||||
1. 检查 GitHub CLI (`gh`) 是否安装
|
||||
2. 选择目标仓库（默认检测当前 git 仓库）
|
||||
3. 选择 API Key 认证方式（已有 key / 新建 key / OAuth）
|
||||
4. 选择要安装的 workflow（PR 助手 `claude.yml` / 代码审查 `claude-code-review.yml`，可多选）
|
||||
5. 自动创建分支、写入 workflow 文件、设置 secret、打开浏览器创建 PR
|
||||
|
||||
安装完成后，你的仓库里会多两个 workflow 文件。
|
||||
|
||||
**PR 助手 workflow** (`.github/workflows/claude.yml`)：监听 PR/Issue 评论中包含 `@claude` 的事件，自动触发 Claude 执行任务：
|
||||
|
||||
```yaml
|
||||
name: Claude Code
|
||||
|
||||
on:
|
||||
issue_comment:
|
||||
types: [created]
|
||||
pull_request_review_comment:
|
||||
types: [created]
|
||||
issues:
|
||||
types: [opened, assigned]
|
||||
pull_request_review:
|
||||
types: [submitted]
|
||||
|
||||
jobs:
|
||||
claude:
|
||||
if: |
|
||||
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
|
||||
...
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: anthropics/claude-code-action@v1
|
||||
with:
|
||||
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
```
|
||||
|
||||
配置成功后，在 PR 评论中 `@claude 修复这个测试失败`，Claude 就会在 GitHub Actions runner 里自动分析、修改代码、提交。
|
||||
|
||||
**代码审查 workflow** (`.github/workflows/claude-code-review.yml`)：在 PR 创建或更新时自动触发代码审查，使用 `code-review` 插件生成结构化的审查报告。
|
||||
|
||||
前置条件：
|
||||
- 安装 GitHub CLI：`brew install gh`（macOS）或参考 [cli.github.com](https://cli.github.com/)
|
||||
- `gh` 已登录并有目标仓库的 admin 权限
|
||||
- 准备好 Anthropic API Key（OAuth token 也支持）
|
||||
|
||||
如果不想用交互式命令，`setupGitHubActions.ts` 里暴露了完整的 API 级流程。`install-github-app` 命令本质上就是对这个 API 的 UI 包装。
|
||||
|
||||
## `/commit-push-pr`：一键提交、推送、开 PR
|
||||
|
||||
`/commit-push-pr` 是一个 prompt 类型命令（不是交互式命令），适合在 CI 或自动化流程中调用。它会分析当前分支相对于默认分支的所有变更（不是只看最新 commit），自动生成 commit message、推送到远程、创建 PR。
|
||||
|
||||
它内置了一个允许工具白名单，严格限制只能执行 git 和 gh 命令：
|
||||
|
||||
```typescript
|
||||
const ALLOWED_TOOLS = [
|
||||
'Bash(git checkout --branch:*)',
|
||||
'Bash(git checkout -b:*)',
|
||||
'Bash(git add:*)',
|
||||
'Bash(git status:*)',
|
||||
'Bash(git push:*)',
|
||||
'Bash(git commit:*)',
|
||||
'Bash(gh pr create:*)',
|
||||
'Bash(gh pr edit:*)',
|
||||
'Bash(gh pr view:*)',
|
||||
'Bash(gh pr merge:*)',
|
||||
'SearchExtraTools',
|
||||
'mcp__slack__send_message',
|
||||
'mcp__claude_ai_Slack__slack_send_message',
|
||||
]
|
||||
```
|
||||
|
||||
在交互式 REPL 中直接输入：
|
||||
|
||||
```
|
||||
/commit-push-pr
|
||||
```
|
||||
|
||||
或者带上额外指令：
|
||||
|
||||
```
|
||||
/commit-push-pr 重点说明新增了缓存层来优化查询性能
|
||||
```
|
||||
|
||||
Claude 会自动查看 `git status`、`git diff`、`git branch --show-current`，分析所有相关提交，生成 commit message，推送到远程，并通过 `gh pr create` 创建 PR。如果 CLAUDE.md 里配置了 Slack 通知，还会尝试搜索 Slack 工具并发送 PR 链接。
|
||||
|
||||
Git 安全协议被硬编码在 prompt 里：不更新 git config、不跑破坏性命令（`push --force`、`hard reset`）、不跳 hooks、不提交含密钥的文件。
|
||||
|
||||
## `/subscribe-pr`：订阅 PR 事件
|
||||
|
||||
`/subscribe-pr` 命令让你关注某个 PR 的动态——新评论、CI 状态变化、review 等。它把订阅信息存在本地的 `~/.claude/pr-subscriptions.json` 文件里。
|
||||
|
||||
使用方式：
|
||||
|
||||
```
|
||||
# 通过完整 URL 订阅
|
||||
/subscribe-pr https://github.com/owner/repo/pull/123
|
||||
|
||||
# 通过短引用
|
||||
/subscribe-pr owner/repo#123
|
||||
|
||||
# 如果在 git 仓库内，直接用 PR 编号
|
||||
/subscribe-pr 123
|
||||
|
||||
# 查看当前订阅列表
|
||||
/subscribe-pr --list
|
||||
|
||||
# 取消订阅
|
||||
/subscribe-pr --remove 123
|
||||
```
|
||||
|
||||
订阅数据结构很简单——每条记录包含仓库、PR 编号和订阅时间。这个功能在 Bridge 模式下特别有用，Bridge 层的 `useReplBridge` 和 `webhookSanitizer` 会根据订阅过滤入站事件，只推送你关心的 PR 通知。
|
||||
|
||||
## Pipe 多会话与 `/pipe-status`
|
||||
|
||||
Claude Code 支持主从 pipe 架构——一个主会话可以连接多个子会话，通过 pipe IPC 机制传递消息和任务。`/pipe-status` 命令查看当前连接状态。
|
||||
|
||||
有三种角色：
|
||||
|
||||
- **Main 模式**：未连接任何子会话的默认状态
|
||||
- **Slave（被控）模式**：被主会话控制，所有数据上报给 master
|
||||
- **Master（主控）模式**：已连接子会话，可以向子会话派发任务
|
||||
|
||||
在 master 模式下，`/pipe-status` 会显示每个子会话的状态、连接时间、历史记录数，并列出可用操作：
|
||||
|
||||
```
|
||||
/pipe-status
|
||||
# Master mode — 2 sub session(s) connected:
|
||||
#
|
||||
# worker-1
|
||||
# Status: idle (connected)
|
||||
# Connected: 14:32:05
|
||||
# History: 12 entries
|
||||
#
|
||||
# worker-2
|
||||
# Status: busy (connected)
|
||||
# Connected: 14:33:12
|
||||
# History: 8 entries
|
||||
#
|
||||
# Commands:
|
||||
# /send <name> <msg> — Send a task to a sub session
|
||||
# /history <name> — View sub session transcript
|
||||
# /detach [name] — Disconnect from a sub session (or all)
|
||||
```
|
||||
|
||||
## BYOC Runner：`environment-runner` 与 `self-hosted-runner`
|
||||
|
||||
BYOC（Bring Your Own Compute）Runner 是两种 headless 长驻运行模式，设计目标是在你自己的基础设施上运行 Claude Code 任务。它们都在 `src/entrypoints/cli.tsx` 中注册为独立的 fast-path，避免加载完整 CLI。
|
||||
|
||||
**`claude environment-runner`**：
|
||||
|
||||
```bash
|
||||
claude environment-runner <args...>
|
||||
```
|
||||
|
||||
这是一个 BYOC（自带计算环境）的 headless runner。入口在 `src/environment-runner/main.ts`，受 `BYOC_ENVIRONMENT_RUNNER` feature flag 控制。
|
||||
|
||||
**`claude self-hosted-runner`**：
|
||||
|
||||
```bash
|
||||
claude self-hosted-runner <args...>
|
||||
```
|
||||
|
||||
这是一个自托管 runner，对接 SelfHostedRunnerWorkerService API（register + poll，poll 同时充当 heartbeat）。入口在 `src/self-hosted-runner/main.ts`，受 `SELF_HOSTED_RUNNER` feature flag 控制。
|
||||
|
||||
注意：这两个 runner 的当前实现是 stub（占位），`main.ts` 里只有 `Promise.resolve()`。它们是 feature-gated 的，需要在构建时启用对应 feature 才能使用。实际的 BYOC 能力目前更多通过 Bridge 模式（`BRIDGE_MODE`）和 ACP 协议（`ACP`）实现。
|
||||
|
||||
如果你想在自己的服务器上长驻运行 Claude 任务，当前可用的替代方案是：
|
||||
- Bridge 模式：`claude remote-control` 启动后，外部客户端通过 WebSocket 连接
|
||||
- ACP 协议：`claude --acp` 把 Claude 暴露为 ACP agent
|
||||
- 自托管 RCS：`bun run rcs` 启动 Remote Control Server，包含 Web UI
|
||||
|
||||
## 定时任务：cron + pipe 实现巡检
|
||||
|
||||
自动化不只是"跑一次"，很多时候你需要定期巡检。有两种方式：
|
||||
|
||||
**方式一：cron 调用 pipe 模式**
|
||||
|
||||
最简单的方式是用系统 crontab 定时调用 `claude -p`：
|
||||
|
||||
```bash
|
||||
# 每 30 分钟检查一次主分支是否有新的 CI 失败
|
||||
*/30 * * * * cd /path/to/repo && claude --bare -p "检查 CI 是否有失败，如果有则列出失败原因" >> /var/log/claude-ci-check.log 2>&1
|
||||
|
||||
# 每天早上 9 点生成一份代码变更摘要
|
||||
0 9 * * * cd /path/to/repo && claude --bare -p "总结过去 24 小时 main 分支的所有变更" | mail -s "日报" team@example.com
|
||||
```
|
||||
|
||||
**方式二：`/schedule` 远程 cron 触发器**
|
||||
|
||||
`/schedule` 命令创建远程 cron 触发器，由服务端按计划触发（需要认证）。这种方式不依赖本机在线：
|
||||
|
||||
```
|
||||
# 创建一个每小时触发一次的巡检任务
|
||||
/schedule create "检查依赖安全漏洞" --cron "0 * * * *" --prompt "运行 npm audit 并报告高危漏洞"
|
||||
```
|
||||
|
||||
更详细的内容见第七章（Daemon、Background Sessions、Schedule）。
|
||||
|
||||
## 退出码与脚本判断
|
||||
|
||||
在脚本里调用 Claude 时，判断成功失败很重要。Pipe 模式下，Claude Code 的退出码取决于执行结果：
|
||||
|
||||
- `0`：正常完成
|
||||
- 非 `0`：出错或被拒绝
|
||||
|
||||
结合 shell 的 `&&` / `||` 可以实现条件执行：
|
||||
|
||||
```bash
|
||||
# 只有 Claude 确认代码正确才执行部署
|
||||
claude -p "审查这个 PR 的代码质量，如果有问题就说 FAIL" && ./deploy.sh
|
||||
|
||||
# Claude 分析失败时发送告警
|
||||
claude -p "分析错误日志 /var/log/app.log" || echo "分析失败，需要人工介入" | mail -s "告警" ops@example.com
|
||||
```
|
||||
|
||||
`src/entrypoints/cli.tsx` 中，各个 fast-path 在出错时通过 `process.exitCode = 1` 或 `process.exit(1)` 设置退出码。主流程的退出码由 `src/main.tsx` 中的 action handler 决定。
|
||||
|
||||
一个实用的 CI 脚本模板：
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# 环境准备
|
||||
export ANTHROPIC_API_KEY="${API_KEY}"
|
||||
export CLAUDE_CODE_REMOTE=true # 容器环境内存优化
|
||||
|
||||
# 运行 Claude 分析
|
||||
if claude --bare -p "检查 src/ 下是否有明显的 bug 或安全问题" --allowed-tools "Read Grep Glob"; then
|
||||
echo "检查通过"
|
||||
exit 0
|
||||
else
|
||||
echo "发现问题，检查输出"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## `CLAUDE_CODE_ABLATION_BASELINE`：消融实验基线
|
||||
|
||||
`CLAUDE_CODE_ABLATION_BASELINE` 是一个用于 harness-science L0 消融实验的环境变量。当同时满足 `feature('ABLATION_BASELINE')` 和设置了该环境变量时，`cli.tsx` 顶层会批量设置一组简化开关：
|
||||
|
||||
```
|
||||
CLAUDE_CODE_SIMPLE=1 # 简化模式
|
||||
CLAUDE_CODE_DISABLE_THINKING=1 # 禁用 thinking
|
||||
DISABLE_INTERLEAVED_THINKING=1 # 禁用交错 thinking
|
||||
DISABLE_COMPACT=1 # 禁用 compact
|
||||
DISABLE_AUTO_COMPACT=1 # 禁用自动 compact
|
||||
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 # 禁用自动记忆
|
||||
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 # 禁用后台任务
|
||||
```
|
||||
|
||||
这个逻辑被特意放在 `cli.tsx` 的顶层（不在 `init.ts` 里），因为 `BashTool`、`AgentTool`、`PowerShellTool` 在 import 时就把 `DISABLE_BACKGROUND_TASKS` 等环境变量捕获进模块级常量——如果放在 `init()` 里就太晚了。
|
||||
|
||||
普通用户不需要关心这个环境变量。它是给做模型能力消融实验的研究者用的。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想在 PR 评论中自动触发 Claude，回到本章"GitHub Actions 集成"部分，参考 `setupGitHubActions` 的自动配置流程
|
||||
- 想了解 `@claude` 在 GitHub 中的完整配置，看 [claude-code-action 仓库](https://github.com/anthropics/claude-code-action) 的使用文档
|
||||
- 想让 Claude 定时自动执行任务（不依赖本机 crontab），看 [第七章：Daemon、Background Sessions、Schedule](./07-daemon-bg-schedule.md)
|
||||
- 想把 Claude 暴露给外部客户端调用，看 [第八章：Bridge、Remote Control、ACP](./08-bridge-rcs-acp.md)
|
||||
- 想限制 Claude 在 CI 中的权限，看 [第九章：权限规则配置指南](./09-savings-hooks-config.md) 中的 `allow` / `deny` 规则部分
|
||||
315
docs/outline-output/user/12-experimental-community.md
Normal file
315
docs/outline-output/user/12-experimental-community.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# 第十二章：进阶实验性能力与社区生态
|
||||
|
||||
> 想折腾更多？这里是一张"还能玩什么"的地图。
|
||||
|
||||
## 实验性 Feature Flag 速览
|
||||
|
||||
Claude Code 有几十个 feature flag，大部分在构建时已默认启用（见 `scripts/defines.ts` 中的 `DEFAULT_BUILD_FEATURES` 列表），用户无需关心。但有几个 flag 的行为比较有趣，值得单独了解。
|
||||
|
||||
已默认启用的进阶 flag 包括：
|
||||
|
||||
| Flag | 作用 |
|
||||
|------|------|
|
||||
| `BUDDY` | 陪伴宠物角色，在输入框旁边显示一个 ASCII 小伙伴 |
|
||||
| `KAIROS` | 定时任务系统核心，配合 `/brief` 使用 |
|
||||
| `LODESTONE` | 上下文锚点，优化长对话中的相关性检索 |
|
||||
| `ULTRAPLAN` | 超级规划模式，深度分析后生成实施计划 |
|
||||
| `MONITOR_TOOL` | 流式监控后台进程输出 |
|
||||
| `KAIROS_BRIEF` | 定时摘要，定时汇报当前会话状态 |
|
||||
| `ULTRATHINK` | 超深度思考模式，增加推理链长度 |
|
||||
|
||||
所有 flag 都可以通过环境变量在运行时控制。格式是 `FEATURE_<FLAG_NAME>=1`，例如：
|
||||
|
||||
```bash
|
||||
# 启用 Buddy 宠物（构建时已默认启用，这里只是演示语法）
|
||||
FEATURE_BUDDY=1 bun run dev
|
||||
|
||||
# Dev 模式默认启用全部 flag，无需额外设置
|
||||
bun run dev
|
||||
```
|
||||
|
||||
注意：`feature()` 函数有 Bun 编译器的限制，只能出现在 `if` 条件或三元表达式中，不能赋值给变量。用户层面不需要关心这个细节，只需要知道"设置环境变量后重启即生效"。
|
||||
|
||||
Skill 搜索与工具搜索预取是两个特殊的实验性 flag：`EXPERIMENTAL_SKILL_SEARCH` 和 `EXPERIMENTAL_SEARCH_EXTRA_TOOLS`。它们虽然被编译进了构建产物，但运行时默认关闭。要开启需要额外设置环境变量 `SKILL_SEARCH_ENABLED=1`。这两个 flag 的设计考虑是： bounded caches 已修复了内存溢出风险，但磁盘侧的观察累积和首次查询时的模型选择仍然是运营层面的权衡，因此默认关闭、由使用者自行决定是否开启。
|
||||
|
||||
```bash
|
||||
# 开启 Skill 搜索实验
|
||||
FEATURE_EXPERIMENTAL_SKILL_SEARCH=1 SKILL_SEARCH_ENABLED=1 bun run dev
|
||||
```
|
||||
|
||||
## Buddy：你的编码小伙伴
|
||||
|
||||
`/buddy` 命令会在你的输入框旁边召唤一个 ASCII 小伙伴。它是一个纯本地的陪伴角色，不会消耗任何 API token，也不影响对话功能。
|
||||
|
||||
第一次运行 `/buddy` 时，系统会根据一个随机种子生成一个随机物种、名字和性格：
|
||||
|
||||
```
|
||||
> /buddy
|
||||
|
||||
A wild companion appeared!
|
||||
|
||||
╭──────────╮
|
||||
│ ○ ○ │
|
||||
│ >│ │
|
||||
│ ╰────╯ │
|
||||
╰──────────╯
|
||||
|
||||
Waddles the Duck
|
||||
Rarity: ** (common)
|
||||
"Quirky and easily amused. Leaves rubber duck debugging tips everywhere."
|
||||
|
||||
Your companion will now appear beside your input box!
|
||||
Say its name to get its take . /buddy pet . /buddy off
|
||||
```
|
||||
|
||||
物种包括 duck、goose、blob、cat、dragon、octopus、owl、penguin、turtle、snail、ghost、axolotl、capybara、cactus、robot、rabbit、mushroom、chonk 共 18 种，每种有固定的默认名字和性格描述。稀有度从 common 到 legendary 不等，还有极低概率出现 shiny 变体。
|
||||
|
||||
`/buddy` 支持几个子命令：
|
||||
|
||||
- `/buddy pet` -- 摸一下小伙伴，触发心形动画和反应台词，同时自动取消静音
|
||||
- `/buddy off` -- 静音小伙伴（不删除，只是不显示）
|
||||
- `/buddy on` -- 取消静音，重新显示
|
||||
- `/buddy`（无参数）-- 如果已有小伙伴则显示卡片，没有则孵化新的
|
||||
|
||||
小伙伴的数据保存在全局配置的 `companion` 字段中，所以重启后仍然存在。每个人的小伙伴由种子决定，理论上相同种子会生成相同结果。
|
||||
|
||||
## Brief 与 Recap：会话状态摘要
|
||||
|
||||
当你离开一段时间后回来，不想滚动翻阅大量历史消息，可以用 `/recap`（别名 `/away` 或 `/catchup`）生成一句当前会话的摘要：
|
||||
|
||||
```
|
||||
> /recap
|
||||
|
||||
You're refactoring the authentication module. The JWT refresh logic has been
|
||||
implemented; next up is adding unit tests for the token rotation edge case.
|
||||
```
|
||||
|
||||
`/recap` 由 `AWAY_SUMMARY` feature flag 控制，构建时已默认启用。它会调用一个独立的 Opus 模型来分析当前会话的上下文，生成不超过 40 个单词的简短描述，涵盖当前目标、活跃任务和下一步行动。没有任何格式标记，就是一句纯文本。
|
||||
|
||||
`/brief` 则是一个更宏观的"简报模式"开关。开启后，Claude 的所有面向用户的输出会通过 Brief 工具统一处理，实现结构化的简报式展示。这个命令由 `KAIROS` 和 `KAIROS_BRIEF` 两个 feature flag 共同控制：
|
||||
|
||||
```
|
||||
> /brief
|
||||
|
||||
Brief-only mode enabled
|
||||
```
|
||||
|
||||
再次输入 `/brief` 可以关闭。注意 Brief 工具有账户级别的权限检查（`isBriefEntitled`），如果你的账户未启用该功能，开启时会提示 "Brief tool is not enabled for your account"。
|
||||
|
||||
## Advisor、Insights 和 Thinkback：让 Claude 反思自己
|
||||
|
||||
这三个命令各有不同的用途。
|
||||
|
||||
`/advisor` 允许你设置一个"顾问模型"，让当前模型在生成回复时参考另一个模型的意见。这是一个高级功能，由 `canUserConfigureAdvisor()` 控制可见性：
|
||||
|
||||
```
|
||||
> /advisor
|
||||
|
||||
Advisor: not set
|
||||
Use "/advisor <model>" to enable (e.g. "/advisor opus").
|
||||
|
||||
> /advisor opus
|
||||
|
||||
Advisor set to claude-opus-4-20250514.
|
||||
```
|
||||
|
||||
设置后会持久化到用户配置（`userSettings`），重启后依然生效。使用 `/advisor unset` 或 `/advisor off` 可以关闭。如果当前使用的主模型不支持 advisor 功能，系统会提示你切换到支持的模型。
|
||||
|
||||
`/insights` 是一个重量级命令，会分析你所有的 Claude Code 会话历史，生成一份完整的 HTML 报告。它使用 Opus 模型对会话数据进行多维分析，覆盖以下方面：
|
||||
|
||||
- 项目领域分布（你在哪些项目上花了多少时间）
|
||||
- 交互风格分析（你通常怎么使用 Claude Code）
|
||||
- 有效工作流发现（哪些使用方式效果最好）
|
||||
- 摩擦点分析（哪些地方让你感到不便）
|
||||
- 改进建议和未来展望
|
||||
|
||||
`/insights` 会读取本地存储的所有会话日志，需要 Opus 模型权限，运行时间较长。报告以 HTML 文件形式保存在本地，适合定期回顾自己的使用模式。
|
||||
|
||||
`/think-back`（注意带横杠）是一个季节性功能，由 GrowthBook 的 `tengu_thinkback` 特性门控。它会生成你的 Claude Code "年度回顾"动画，类似音乐平台的年度听歌报告。配合 `/thinkback-play` 可以重放动画效果。
|
||||
|
||||
## Teleport：跨设备恢复会话
|
||||
|
||||
`/teleport`（别名 `/tp`）让你从 Claude.ai 网页端恢复一个会话到本地 CLI。这对于"在网页上开始的任务，想在本地终端继续"的场景特别有用。
|
||||
|
||||
不带参数运行 `/teleport` 会从 Sessions API 拉取你的会话列表：
|
||||
|
||||
```
|
||||
> /teleport --print
|
||||
|
||||
## Available sessions (most recent first)
|
||||
|
||||
01. Refactor auth module to use JWT active 2025-06-14 id=abc12345-...
|
||||
02. Debug memory leak in worker process completed 2025-06-13 id=def67890-...
|
||||
03. Add integration tests for API layer active 2025-06-12 id=ghi24680-...
|
||||
|
||||
Run `/teleport <session-id>` to resume a session.
|
||||
```
|
||||
|
||||
传入会话 ID 可以恢复具体会话。恢复前系统会检查本地 git 状态是否干净，因为恢复过程可能涉及分支切换。如果 git 有未提交的修改，会报错并提示你先处理。
|
||||
|
||||
```bash
|
||||
# 查看可用会话
|
||||
/teleport
|
||||
|
||||
# 恢复特定会话
|
||||
/teleport abc12345-6789-abcd-ef01-234567890abc
|
||||
```
|
||||
|
||||
Teleport 的前提是你已通过 OAuth 认证登录（`claude auth login`）。如果认证 token 过期或无效，会提示你重新登录。该命令不支持通过 Remote Control / Bridge 使用（`bridgeSafe: false`）。
|
||||
|
||||
## Pipes：跨会话消息传递
|
||||
|
||||
`/pipes` 命令管理跨机器、跨会话的消息管道。它属于 `pipes` 模块的一部分，用于在多个 Claude Code 实例之间广播消息。
|
||||
|
||||
不带参数运行 `/pipes` 会显示当前管道状态，包括你的管道名称、角色（main 或 sub）、连接的管道列表等：
|
||||
|
||||
```
|
||||
> /pipes
|
||||
|
||||
Your pipe: claude-macbook-pro
|
||||
Role: main
|
||||
Machine ID: a1b2c3d4...
|
||||
IP: 192.168.1.42
|
||||
Host: macbook-pro.local
|
||||
|
||||
Main machine: a1b2c3d4... (this machine)
|
||||
[main] claude-macbook-pro macbook-pro.local/192.168.1.42 [alive] (you)
|
||||
[sub-1] claude-linux-box linux-server/192.168.1.100 [alive]
|
||||
|
||||
Selected: (none -- messages run locally only)
|
||||
|
||||
Commands:
|
||||
/pipes select <name> -- select pipe for broadcast
|
||||
/pipes deselect <name> -- deselect pipe
|
||||
/pipes all -- select all connected
|
||||
/pipes none -- deselect all
|
||||
/send <name> <msg> -- send to specific pipe
|
||||
/claim-main -- claim this machine as main
|
||||
```
|
||||
|
||||
通过 `/pipes select <name>` 选择目标管道后，你的消息会被广播到选中的管道。`/send <name> <msg>` 则可以直接向特定管道发送一条消息而不影响广播设置。
|
||||
|
||||
`/pipes` 依赖管道注册表（`pipeRegistry`）来发现网络上的其他实例。在 LAN_PIPES feature 启用时，还会通过局域网信标（`lanBeacon`）自动发现局域网内的对等节点。
|
||||
|
||||
## Local Vault 与 Memory Stores：本地长期记忆
|
||||
|
||||
`/local-vault` 提供一个本地的键值存储，你可以用它保存想要跨会话持久化的信息。它不依赖任何远程服务，数据完全存储在本地。
|
||||
|
||||
```bash
|
||||
# 查看所有条目
|
||||
> /local-vault list
|
||||
|
||||
# 存储一条信息
|
||||
> /local-vault set project-arch We use a monorepo with turborepo
|
||||
|
||||
# 读取一条信息（默认隐藏值）
|
||||
> /local-vault get project-arch
|
||||
project-arch: ********
|
||||
|
||||
# 读取并显示明文
|
||||
> /local-vault get project-arch --reveal
|
||||
project-arch: We use a monorepo with turborepo
|
||||
|
||||
# 删除一条信息
|
||||
> /local-vault delete project-arch
|
||||
```
|
||||
|
||||
键名不能以 `-` 开头（包括各种 Unicode 连字符变体），这是为了防止与命令行参数标志混淆。
|
||||
|
||||
`/memory-stores` 是一个更结构化的记忆管理系统，支持创建多个记忆库（store），每个库下可以创建多条记忆（memory），支持版本管理和内容撤回：
|
||||
|
||||
```bash
|
||||
# 创建一个新的记忆库
|
||||
> /memory-stores create project-conventions
|
||||
|
||||
# 在库中添加一条记忆
|
||||
> /memory-stores create-memory <store-id> Always use Zod for input validation
|
||||
|
||||
# 查看某个库的所有记忆
|
||||
> /memory-stores memories <store-id>
|
||||
|
||||
# 更新一条记忆
|
||||
> /memory-stores update-memory <store-id> <memory-id> Always use Zod or Valibot for input validation
|
||||
|
||||
# 查看某个库的版本历史
|
||||
> /memory-stores versions <store-id>
|
||||
|
||||
# 撤回某个版本的内容
|
||||
> /memory-stores redact <store-id> <version-id>
|
||||
|
||||
# 归档不再使用的库
|
||||
> /memory-stores archive <store-id>
|
||||
```
|
||||
|
||||
Memory stores 比 local-vault 更适合管理需要跟踪变更的结构化知识。local-vault 更适合存储简单的键值对配置。两者互补，根据你的数据复杂度选择即可。
|
||||
|
||||
## TUI 模式：无闪烁全屏体验
|
||||
|
||||
`/tui` 命令切换 Claude Code 的显示模式。开启后使用 ANSI 备用屏幕缓冲区（alternate screen buffer），UI 占据整个终端窗口，退出后自动恢复原始内容，不会污染你的终端滚动历史。
|
||||
|
||||
```bash
|
||||
# 开启 TUI 模式
|
||||
> /tui on
|
||||
|
||||
## TUI mode enabled
|
||||
|
||||
Marker written: `~/.claude/.tui-mode`
|
||||
|
||||
Flicker-free alternate-screen rendering will be active on the next
|
||||
session start. Add this to your shell profile to make it permanent:
|
||||
|
||||
[ -f "$HOME/.claude/.tui-mode" ] && export CLAUDE_CODE_NO_FLICKER=1
|
||||
|
||||
To disable: `/tui off`
|
||||
```
|
||||
|
||||
TUI 模式的设置通过标记文件 `~/.claude/.tui-mode` 持久化，跨会话生效。你还可以通过环境变量 `CLAUDE_CODE_NO_FLICKER` 控制：
|
||||
|
||||
```bash
|
||||
# 强制开启（覆盖标记文件）
|
||||
CLAUDE_CODE_NO_FLICKER=1 claude
|
||||
|
||||
# 强制关闭
|
||||
CLAUDE_CODE_NO_FLICKER=0 claude
|
||||
```
|
||||
|
||||
推荐在 shell 配置文件中添加自动检测，这样每次启动 Claude Code 时都会自动启用 TUI 模式：
|
||||
|
||||
```bash
|
||||
# 添加到 ~/.zshrc 或 ~/.bashrc
|
||||
[ -f "$HOME/.claude/.tui-mode" ] && export CLAUDE_CODE_NO_FLICKER=1
|
||||
```
|
||||
|
||||
`/tui status` 可以查看当前 TUI 模式的状态，包括标记文件是否存在、环境变量设置情况等。注意：运行时修改环境变量不会立即生效，需要重启会话。
|
||||
|
||||
## Stickers 和 Output Style
|
||||
|
||||
`/stickers` 命令用于订购 Claude Code 的实体贴纸。这是一个简单的互动功能，不涉及任何技术配置。
|
||||
|
||||
`/output-style` 命令已被标记为隐藏（deprecated），官方推荐使用 `/config` 命令来更改输出风格。如果你在旧版本的文档中看到 `/output-style`，直接使用 `/config` 替代即可。
|
||||
|
||||
## 贡献与反馈
|
||||
|
||||
如果你在使用过程中遇到问题或有改进建议，有几种反馈渠道：
|
||||
|
||||
`/feedback`（别名 `/bug`）是最直接的反馈方式。它会在交互式界面中引导你提交反馈。注意：当你使用 Bedrock、Vertex 或 Foundry 作为 Provider 时，`/feedback` 命令会被自动禁用。如果你手动设置了 `DISABLE_FEEDBACK_COMMAND=1` 或 `DISABLE_BUG_COMMAND=1`，该命令也会被隐藏。
|
||||
|
||||
```bash
|
||||
# 直接提交反馈
|
||||
> /feedback
|
||||
|
||||
# 带描述提交
|
||||
> /feedback The Grep tool sometimes returns stale results after file edits
|
||||
```
|
||||
|
||||
如果你是开发者或想深入了解项目内部，可以：
|
||||
|
||||
- 查看 GitHub Issues 提交 bug 报告或功能请求
|
||||
- 在本地启动文档站查看最新文档：`bun run docs:dev`（基于 Mintlify）
|
||||
- 阅读项目中的 `CLAUDE.md` 了解贡献规范和代码约定
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想了解如何切换模型和 Provider，看 [第二章](./02-providers.md)
|
||||
- 想排查错误或查看常见问题，看 [第十章](./10-observability-troubleshooting.md)
|
||||
- 想把 Claude 嵌入 CI 流水线，看 [第十一章](./11-ci-integration.md)
|
||||
277
docs/outline-output/user/13-security.md
Normal file
277
docs/outline-output/user/13-security.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 第十三章：安全 —— 凭证、权限、刷新、共享
|
||||
|
||||
> 你的 API 密钥和令牌到底存在哪里、谁能看到、怎么撤回。
|
||||
|
||||
## 凭证存储位置清单
|
||||
|
||||
Claude Code 在运行过程中会接触多种凭证，分布在 `~/.claude/` 目录下的几个文件中。了解它们的位置和用途，是保护自己账户安全的第一步。
|
||||
|
||||
**Anthropic API Key（Workspace Key）**
|
||||
|
||||
Anthropic 的 API 密钥有两个来源。优先级最高的是环境变量 `ANTHROPIC_API_KEY`，其次是全局配置文件 `~/.claude.json` 中的 `workspaceApiKey` 字段。当你通过 `/login` 选择 "API Usage Billing" 时，密钥会被保存到 `~/.claude.json`。保存后，代码会尝试对文件执行 `chmod 600`，确保只有文件所有者可以读取。在 Windows 上 `chmod` 无效，代码会输出一条提醒，建议你用 `icacls` 手动限制访问。
|
||||
|
||||
Workspace Key 只接受 `sk-ant-api03-` 前缀的密钥，长度限制在 20 到 256 字符之间。错误信息中永远不会包含密钥原文，即使验证失败也只会显示前 4 个字符。
|
||||
|
||||
```bash
|
||||
# 查看当前配置中是否存有 Workspace Key
|
||||
cat ~/.claude.json | python3 -c "import sys,json; d=json.load(sys.stdin); print('has workspaceApiKey' if 'workspaceApiKey' in d else 'no workspaceApiKey')"
|
||||
```
|
||||
|
||||
**ChatGPT 订阅凭证**
|
||||
|
||||
如果你通过 ChatGPT 订阅路径使用 Claude Code（`OPENAI_AUTH_MODE=chatgpt`），OAuth 令牌会存储在 `~/.claude/openai-chatgpt-auth.json` 中。这个文件的权限是 `0600`（仅 owner 可读写）。文件中包含 `id_token`、`access_token`、`refresh_token` 三类令牌和上次刷新的时间戳。
|
||||
|
||||
```json
|
||||
// ~/.claude/openai-chatgpt-auth.json（简化示意）
|
||||
{
|
||||
"auth_mode": "chatgpt",
|
||||
"tokens": {
|
||||
"id_token": "eyJhbGc...",
|
||||
"access_token": "eyJhbGc...",
|
||||
"refresh_token": "v1.MjQ...",
|
||||
"account_id": "account-abc123"
|
||||
},
|
||||
"last_refresh": "2025-06-14T10:30:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
**跨工具共享的 Codex 凭证**
|
||||
|
||||
Claude Code 会检查 `~/.codex/auth.json`（路径受 `CODEX_HOME` 环境变量影响）。当 `~/.claude/openai-chatgpt-auth.json` 中没有有效令牌时，会回退读取这个文件。这意味着如果你之前用 Codex CLI 登录过同一个 ChatGPT 账户，Claude Code 可以直接复用那些令牌，不需要再走一遍设备码流程。
|
||||
|
||||
**Trusted Device Token**
|
||||
|
||||
在 Bridge / Remote Control 模式下，Claude Code 使用受信任设备令牌来标识已注册的设备。这个令牌存储在 macOS Keychain 中（通过 `security` 命令读写），不是普通的文件。你也可以通过环境变量 `CLAUDE_TRUSTED_DEVICE_TOKEN` 手动指定一个令牌，这在测试场景中很方便。
|
||||
|
||||
**`settings.json` / `settings.local.json`**
|
||||
|
||||
这两个文件存储权限规则、hooks、keybindings 等配置。`settings.json` 是团队共享的，`settings.local.json` 是个人覆盖，后者不应提交到版本控制。这两个文件本身不存储 API 密钥，但如果你在 hooks 中引用了密钥路径，就要注意不要把它们分享出去。
|
||||
|
||||
## OAuth 设备码流程
|
||||
|
||||
Claude Code 支持两种 OAuth 登录路径：Anthropic 官方 OAuth 和 ChatGPT 订阅的设备码流程。两者的交互方式类似，但底层协议不同。
|
||||
|
||||
**Anthropic OAuth（/login 默认路径）**
|
||||
|
||||
输入 `/login` 后选择 "Subscription Plan" 或 "API Usage Billing"，终端会打开浏览器跳转到 Anthropic 的 OAuth 页面。你在浏览器中完成授权后，终端会收到授权码（通过粘贴码或自动回调），然后 Claude Code 用这个码换取 access token 并保存到系统。登录成功后，代码会刷新 GrowthBook feature flags、策略限制、远程托管设置，并注册受信任设备令牌。
|
||||
|
||||
如果浏览器没有自动打开，终端会在几秒后提示你手动复制 URL 并粘贴返回的授权码。输入 `c` 可以快速复制 URL 到剪贴板。
|
||||
|
||||
**ChatGPT 订阅设备码流程**
|
||||
|
||||
当你选择 ChatGPT 订阅作为后端时，`/login` 会启动一个不同的设备码流程。流程分为三步：
|
||||
|
||||
1. 请求设备码：向 `https://auth.openai.com/api/accounts/deviceauth/usercode` 发送 POST 请求，获取一个 6 位的用户码和 `deviceAuthId`。
|
||||
2. 等待授权：终端提示你打开 `https://auth.openai.com/codex/device` 并输入用户码。之后 Claude Code 每 5 秒轮询一次 token 端点，等待你完成授权。超时上限是 15 分钟。
|
||||
3. 交换令牌：授权完成后，用 `authorization_code` 和 `code_verifier` 向 `/oauth/token` 端点换取 `id_token`、`access_token` 和 `refresh_token`，然后保存到 `~/.claude/openai-chatgpt-auth.json`。
|
||||
|
||||
```
|
||||
# 设备码流程终端输出示意
|
||||
> /login
|
||||
1. Anthropic Subscription Plan (Claude Pro/Max)
|
||||
2. API Usage Billing (Anthropic Console)
|
||||
3. ChatGPT account with subscription
|
||||
4. OpenAI Chat Completions API
|
||||
5. Gemini API
|
||||
...
|
||||
[选择 3]
|
||||
|
||||
Requesting device code...
|
||||
Please open this URL in your browser and enter the code:
|
||||
|
||||
URL: https://auth.openai.com/codex/device
|
||||
Code: ABC-DEF
|
||||
|
||||
Waiting for authorization... (timeout: 15m)
|
||||
Authorization successful. Tokens saved.
|
||||
```
|
||||
|
||||
**中国 LLM 提供商**
|
||||
|
||||
中国 LLM 提供商（DeepSeek、智谱 GLM、通义千问、Moonshot、Cerebras、Groq）使用不同的登录流程。在 `/login` 中选择对应的提供商后，终端会展示一个选择界面，让你选择访问模式（API 或 Coding Plan），然后输入 API Key。这些密钥会保存到配置中，不走 OAuth 设备码流程。
|
||||
|
||||
## OAuth 令牌自动刷新
|
||||
|
||||
ChatGPT 订阅路径的令牌不会永不过期。Claude Code 在每次使用令牌前都会检查是否即将过期，并在必要时自动刷新。
|
||||
|
||||
**5 分钟偏差窗口**
|
||||
|
||||
`chatgptAuth.ts` 中定义了一个常量 `REFRESH_SKEW_MS = 5 * 60 * 1000`（5 分钟）。当 access token 的过期时间距离当前时间不到 5 分钟时，就会触发刷新。这意味着即使在高延迟的网络环境下，也不会因为令牌刚好过期而中断操作。
|
||||
|
||||
刷新使用 `refresh_token` 向 `/oauth/token` 发送 `grant_type=refresh_token` 请求。成功后获得新的 `id_token`、`access_token`，以及可能更新的 `refresh_token`（如果服务端返回了新的）。新令牌会立即写回 `~/.claude/openai-chatgpt-auth.json` 并更新 `last_refresh` 时间戳。
|
||||
|
||||
**Bridge 模式的令牌刷新**
|
||||
|
||||
在 Bridge（Remote Control）模式下，Claude Code 使用 `createTokenRefreshScheduler` 来管理会话令牌的自动刷新。这个调度器会解析 JWT 的 `exp` 字段，在令牌过期前 5 分钟触发刷新。如果 JWT 无法解析（例如使用了不透明的 OAuth token），调度器会保持现有的定时器不被覆盖，避免中断刷新链。
|
||||
|
||||
刷新失败时不会立刻放弃，而是会重试最多 3 次（`MAX_REFRESH_FAILURES = 3`），每次间隔 60 秒。如果连续 3 次都无法获取新的 OAuth token，调度器会停止尝试，后续需要手动重新连接。
|
||||
|
||||
```
|
||||
# Bridge 模式令牌刷新日志示意
|
||||
[bridge:token] Scheduled token refresh for sessionId=abc123 in 25m (expires=2025-06-14T12:00:00.000Z, buffer=300s)
|
||||
[bridge:token] Refreshing token for sessionId=abc123: new token prefix=eyJhbGcDk7xYk2...
|
||||
[bridge:token] Scheduled follow-up refresh for sessionId=abc123 in 30m
|
||||
```
|
||||
|
||||
**Anthropic OAuth 刷新**
|
||||
|
||||
Anthropic 官方 OAuth 的令牌刷新机制嵌入在 `OAuthService` 中。当你执行 `/login` 后，OAuth token 会被安装到系统中。Bridge 模式会通过 `installOAuthTokens` 保存这些令牌，并在后续的 API 调用中自动使用。刷新逻辑与 ChatGPT 路径类似，也是基于 token 的过期时间。
|
||||
|
||||
## 权限模式语义
|
||||
|
||||
Claude Code 的权限系统决定了 Claude 在使用工具（执行命令、读写文件、搜索代码等）时是否需要你的明确许可。理解每种模式的含义和切换方式，可以让你在使用效率和安全性之间找到平衡。
|
||||
|
||||
**六种权限模式**
|
||||
|
||||
| 模式 | 含义 | 切换方式 |
|
||||
|------|------|----------|
|
||||
| Default | 每次工具调用都需要你手动确认或拒绝 | 默认模式 |
|
||||
| Plan | 只规划不执行，退出 Plan 后回到 Default | `/plan` |
|
||||
| Accept Edits | 自动批准文件编辑，其他操作仍需确认 | `M-x` 快捷键 |
|
||||
| Bypass | 自动批准所有工具调用 | 仅限特定环境 |
|
||||
| Don't Ask | 自动批准但跳过某些检查 | 内部模式 |
|
||||
| Auto | 基于分类器自动决定批准或拒绝 | 仅限内部用户 |
|
||||
|
||||
日常使用中，你最常接触的是 Default 和 Accept Edits。Default 模式适合你希望对每个操作保持掌控的场景，比如在生产代码库中工作。Accept Edits 适合你信任 Claude 的编辑能力、但仍然想监督命令执行的场景。
|
||||
|
||||
**Bypass 模式的可用性**
|
||||
|
||||
Bypass 模式（自动批准所有工具调用）不是随时可用的。代码中有一个 `bypassPermissionsKillswitch` 模块来管理这个模式的可用性。在大多数环境下，bypass 权限始终可用（当前实现是 no-op），但在远程模式或特定安全策略下，它可能被禁用。
|
||||
|
||||
**权限规则**
|
||||
|
||||
除了模式级别的开关，你还可以通过 `/permissions` 命令配置细粒度的 allow/deny 规则。规则会根据工具名匹配和 glob 模式来决定是否跳过确认。规则分为 allow（白名单）和 deny（黑名单）两类，deny 规则的优先级高于 allow。
|
||||
|
||||
```
|
||||
# 在 /permissions 界面中配置规则的交互流程
|
||||
> /permissions
|
||||
|
||||
Permission Rules
|
||||
|
||||
[+] Add rule
|
||||
[x] Allow: BashTool(npm test)
|
||||
[x] Allow: BashTool(npm run lint)
|
||||
[x] Deny: BashTool(rm -rf*)
|
||||
|
||||
Rules are evaluated in order. Deny rules override allow rules.
|
||||
```
|
||||
|
||||
**ACP 权限管道**
|
||||
|
||||
当你通过 ACP（Agent Client Protocol）连接 Claude Code 时，权限决策会经过一条统一的管道。`createAcpCanUseTool` 函数先运行本地的权限规则检查（deny/allow/bypass），如果本地规则没有得出结论，就把决策委托给 ACP 客户端。客户端可以返回 "Always Allow"、"Allow Once" 或 "Reject" 三种选择。
|
||||
|
||||
ACP 管道对 `ExitPlanMode` 工具有特殊处理，提供额外的选项："Yes, and use auto mode"、"Yes, and auto-accept edits"、"Yes, and manually approve edits"。
|
||||
|
||||
## JWT 与 Bridge 模式认证
|
||||
|
||||
Bridge 模式（通过 `claude remote-control`、`claude rc` 或 `claude bridge` 启动）是一种让外部客户端（如 Web UI、IDE 插件）远程控制 Claude Code 会话的方式。在这种模式下，认证和安全机制与本地 REPL 有显著不同。
|
||||
|
||||
**JWT 令牌的生命周期**
|
||||
|
||||
Bridge 模式使用 JWT（JSON Web Token）进行会话认证。`jwtUtils.ts` 中的 `decodeJwtPayload` 函数可以解码 JWT 的 payload（不验证签名），提取 `exp` 过期时间。`sk-ant-si-` 前缀的 session-ingress token 会被自动去除前缀后再解码。
|
||||
|
||||
令牌刷新调度器会在令牌过期前 5 分钟（`TOKEN_REFRESH_BUFFER_MS`）触发刷新。如果无法从 JWT 中解析过期时间（例如使用了不透明的 OAuth token），调度器会使用一个 30 分钟的固定刷新间隔作为后备。
|
||||
|
||||
**受信任设备令牌**
|
||||
|
||||
Bridge 会话使用 `TrustedDeviceToken` 进行设备级认证。这个令牌通过 `enrollTrustedDevice()` 在 `/login` 时注册，存储在 macOS Keychain 中。注册有严格的时间窗口限制——必须在账户创建后的 10 分钟内完成。令牌有 90 天的滚动过期时间，每次成功使用都会续期。
|
||||
|
||||
受信任设备令牌受 GrowthBook feature gate `tengu_sessions_elevated_auth_enforcement` 控制。只有当这个 gate 启用时，CLI 才会在请求中携带 `X-Trusted-Device-Token` header。令牌读取使用 `memoize` 缓存，避免每次请求都启动 `security` 子进程。
|
||||
|
||||
**令牌刷新失败处理**
|
||||
|
||||
当 Bridge 模式下的令牌刷新连续失败时，系统会：
|
||||
1. 记录失败次数，最多允许 3 次连续失败。
|
||||
2. 每次失败后等待 60 秒再重试。
|
||||
3. 超过 3 次后停止尝试，输出诊断日志 `bridge_token_refresh_no_oauth`。
|
||||
4. 之后需要重新建立连接才能恢复。
|
||||
|
||||
登录切换账户时（`/login` → 新账户），代码会先清除旧的受信任设备令牌（`clearTrustedDeviceToken`），然后异步注册新账户的令牌，避免用旧令牌发送 bridge 请求。
|
||||
|
||||
## /share 与 /export 的隐私边界
|
||||
|
||||
当你想跟同事分享一段 Claude Code 的对话时，`/share` 和 `/export` 是两个主要工具。它们对隐私的处理方式不同，你需要根据场景选择。
|
||||
|
||||
**`/export`：导出到本地文件**
|
||||
|
||||
`/export` 把当前对话渲染成纯文本文件并保存到你指定的路径（默认是当前工作目录）。文件名自动根据第一条消息的前 50 个字符生成，加上时间戳后缀。
|
||||
|
||||
导出的内容包含对话中的所有用户消息和助手回复（包括工具调用的结果），以纯文本格式呈现。`/export` 不会对内容做脱敏处理——如果你的对话中包含了 API 密钥、文件路径或其他敏感信息，它们会原样出现在导出文件中。
|
||||
|
||||
```bash
|
||||
# 导出到指定文件
|
||||
> /export my-session.txt
|
||||
Conversation exported to: /home/user/project/my-session.txt
|
||||
|
||||
# 不带参数会弹出文件名对话框
|
||||
> /export
|
||||
```
|
||||
|
||||
**`/share`：上传到 GitHub Gist**
|
||||
|
||||
`/share` 把会话日志（JSONL 格式）上传到 GitHub Gist。默认创建 secret Gist（只有拥有链接的人可以访问），你也可以用 `--public` 创建公开 Gist。
|
||||
|
||||
上传前，`/share` 提供了几种隐私保护选项：
|
||||
|
||||
- `--mask-secrets`：自动脱敏 API 密钥和令牌。代码会匹配 `sk-ant-*`、`sk-*`、`Bearer` token、AWS 密钥（`AKIA*`）、GitHub token（`ghp_*`/`gho_*`等）、Slack token（`xoxb-*`）等模式，替换为 `[REDACTED_*]` 占位符。
|
||||
- `--summary-only`：只上传摘要，每轮对话只取前 200 个字符。
|
||||
- `--private`：创建 secret Gist（默认行为）。
|
||||
- `--allow-public-fallback`：当 `gh` CLI 不可用时，回退到 `0x0.st` 粘贴服务。
|
||||
|
||||
```bash
|
||||
# 安全地分享（脱敏 + 摘要）
|
||||
> /share --mask-secrets --summary-only
|
||||
|
||||
## Session shared
|
||||
|
||||
URL: https://gist.github.com/abc123...
|
||||
Session: sess_xyz
|
||||
Visibility: secret
|
||||
Content: summary only (truncated)
|
||||
Secrets: masked before upload
|
||||
```
|
||||
|
||||
**注意**：即使使用了 `--mask-secrets`，脱敏也不是万无一失的。代码注释明确说明不会匹配普通的 32 位以上十六进制字符串（因为它们可能匹配 git commit SHA 或 base64 内容）。分享前最好自己检查一遍内容。
|
||||
|
||||
**没有 `gh` CLI 时的选择**
|
||||
|
||||
如果你没有安装 GitHub CLI（`gh`），`/share` 会告诉你手动命令并提示安装 `gh`。你也可以用 `--allow-public-fallback` 让它回退到 `0x0.st`，但注意 `0x0.st` 是公开的粘贴服务，任何知道 URL 的人都能看到内容。
|
||||
|
||||
## 跨工具凭证共享的隐私影响
|
||||
|
||||
Claude Code 和 Codex CLI 可以共享 ChatGPT 订阅的 OAuth 令牌。这种共享带来了便利，但也意味着两个工具对同一组令牌拥有相同的访问权限。
|
||||
|
||||
**共享机制**
|
||||
|
||||
当 `~/.claude/openai-chatgpt-auth.json` 中没有有效令牌时，Claude Code 会读取 `~/.codex/auth.json`。这意味着如果你之前用 Codex CLI 登录过 ChatGPT 账户，切换到 Claude Code 后不需要重新登录。
|
||||
|
||||
```typescript
|
||||
// chatgptAuth.ts 中的回退逻辑（简化）
|
||||
let tokens = await readStoredAuth(authFilePath()) // ~/.claude/openai-chatgpt-auth.json
|
||||
if (!tokens) {
|
||||
tokens = await readStoredAuth(codexAuthFilePath()) // ~/.codex/auth.json
|
||||
}
|
||||
```
|
||||
|
||||
**这意味着什么**
|
||||
|
||||
两个工具共享同一组 refresh token。如果你在一个工具中执行了 `/logout` 或删除了凭证文件，另一个工具也会失去访问权限。反过来，如果你在 Codex CLI 中刷新了令牌，Claude Code 会使用新的令牌（因为它读取的是文件内容，而不是内存缓存）。
|
||||
|
||||
令牌文件的权限是 `0o600`（仅 owner 可读写），这提供了基础的文件系统级保护。但如果你的主目录权限设置不当，或者在其他用户的机器上工作，就要格外注意这两个文件的安全性。
|
||||
|
||||
**撤销访问**
|
||||
|
||||
如果你想撤销 Claude Code 对 ChatGPT 账户的访问，除了删除本地的 `openai-chatgpt-auth.json` 和 `~/.codex/auth.json`，还应该到 OpenAI 的账户设置中撤销对应的 OAuth 应用授权。否则，refresh token 可能仍然有效，已经获取的 access token 在过期前仍可使用。
|
||||
|
||||
```bash
|
||||
# 删除本地凭证文件
|
||||
rm ~/.claude/openai-chatgpt-auth.json
|
||||
rm ~/.codex/auth.json
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- 想了解如何配置 Provider 和切换 API 后端，看 [第二章：让 Claude 听你的](./02-providers.md)
|
||||
- 想了解 Bridge 和 Remote Control 模式的完整用法，看 [第八章：跨机器与跨团队协作](./08-bridge-rcs-acp.md)
|
||||
- 想了解遇到认证错误如何排错，看 [第十章：可观测性与排错](./10-observability-troubleshooting.md)
|
||||
- 想了解权限规则的具体语法和配置方法，看 [第九章：省钱、提速、定制](./09-budget-hooks-config.md)
|
||||
Reference in New Issue
Block a user