Claude Code 核心概念详解

AI交流专区
1

author: 左岚

Claude Code 核心概念详解

在线文档

https://ai.feishu.cn/drive/folder/UQgzfSmeSlDA8Nd43UOc0WOCnRd

ai杂谈目录下

一、Claude Code 简介

1.1 什么是 Claude Code

Claude Code 是由 Anthropic 公司开发的 AI 编程辅助框架，具有以下核心特性：

  • 框架定位：非 AI 模型本身，而是专为 AI 编程设计的开发框架
  • 原生支持：完美集成 Claude 系列模型（Sonnet、Opus、Haiku）
  • 接入方式：提供官方订阅和 API 接入两种方案

:warning: 重要提示：由于区域限制，Anthropic 官方服务在中国大陆不可用，且节点不纯净可能导致封号风险。强烈建议使用 API 接入方案。

1.2 API 接入方式对比

接入方式 优势 劣势 适用场景
官转 API • 智商最高
• 稳定性好
• 上下文长（支持 1M）		 • 价格较高（但有倍率折扣） 专业开发、商业项目
2API 逆向 • 价格低廉
• 部分免费		 • 效果较差
• 上下文短
• 稳定性差		 轻度使用、测试学习
第三方模型 • 成本可控
• 框架兼容		 • 能力因模型而异 预算有限、多模型对比

1.2.1 官转 API（推荐）

  • 通过 NewAPI 平台进行官方 API 的分发和转换
  • 保持原生 Claude 模型的完整能力
  • 支持完整的上下文缓存和长文本处理
  • 推荐用于对质量要求高的项目

1.2.2 2API 逆向方案

  • 从 Cursor、Kiro 等集成 Claude 的软件逆向获取 API
  • 常见公益站点：
  • 注意：稳定性和质量无保障，建议仅用于测试

1.2.3 第三方模型适配

  • 支持智谱 GLM、Minimax、Kimi 等国产模型
  • 这些模型已适配 Claude Code 接口标准
  • 可根据预算和需求灵活选择

二、核心概念详解

2.1 API URL 与 Token

定义：

  • API URL：API 服务的访问地址（如 https://api.example.com/v1）
  • API Token：用于身份验证的密钥（通常以 sk- 开头）

获取方式：

  • 不同站点提供的格式和参数可能略有差异
  • 通过 API 中转站购买后在后台生成

2.2 倍率计费机制

核心概念：倍率是你享受的折扣比例，数值越低越划算。

2.2.1 充值与倍率的关系

第一步：充值（1:1 兑换）

  • 你支付 1 元人民币
  • 获得 1 美元等值额度（Credit/Dollar）
  • 这是"充值汇率"，优质站点通常是 1:1

第二步：消费倍率（实际扣费）

  • 假设官方定价：某模型 API 调用需要 $10
  • 普通用户消费：扣除 $10 额度
  • 带倍率 0.55 的用户：实际扣除 $10 × 0.55 = $5.5

2.2.2 实际收益计算

案例：充值 100 元，倍率 0.55

实际可用服务价值 = 100 ÷ 0.55 ≈ 181.8 元
相当于 5.5 折优惠

2.2.3 防坑指南

  1. 确认充值汇率：

    • :white_check_mark: 优质站点：1 RMB = 1 USD 额度
    • :cross_mark: 黑心商家：1 RMB = 0.14 USD 额度（1:7 汇率）

  2. 模型质量验证：

    • 倍率低但模型质量差毫无意义
    • 建议先小额充值测试后再大额投入

2.3 上下文缓存机制

核心作用：避免重复计费，大幅降低长期对话成本。

2.3.1 缓存原理

无缓存模式（金鱼记忆）：

  • 每次对话都需要重新发送完整上下文
  • 重复计费相同的 Token
  • 成本高昂

缓存模式（持久记忆）：

  • 首次对话写入缓存（略贵）
  • 后续对话直接读取缓存（便宜或免费）
  • 缓存有效期内大幅节省成本

2.3.2 缓存时长选择

时长 适用场景 说明
5 分钟 快速问答、脚本调试 短时间内集中提问，超时即清理
1 小时 重度开发、代码调试 长时间反复访问同一代码库，成本最低

2.3.3 :brain: 缓存策略：看间隔，不看总长

并不是说你坐那一天就要开1小时缓存，而是要看你两次提问中间隔了多久。

  • :brick: 持久战场景（写代码）
    • 建议： 直接选 1 小时。
    • 理由： 写代码时，你查完一个 Bug，可能需要 10-20 分钟去改代码、综合、甚至烧写板子，这个**“思考/操作间隔”**很容易超过 5 分钟。
    • 结果： 如果选 5 分钟，等你改完代码回来问，缓存早过期了，又得重新付费写入，血亏！所以选 1 小时，容错率高，越久越省心。:smiling_face_with_sunglasses:
  • :high_voltage: 快速问答场景（查单词、简单脚本语法）
    • 建议： 选择 5 分钟 或者 不开缓存。
    • 理由： 这种时候你的请求间隔很短，或者根本就是“一次性买卖”。
    • 结果： 问完就跑，没必要为了那点并不存在的“下一次”去付存储费。
  • :money_bag: 首次写入成本（门槛警告）
    • 核心逻辑： 只有多次访问才划算。
    • 理由： 开启缓存的那一次（首次写入）是要付全款的！如果没有后续的请求来利用这个缓存（享受低价读取），那你就是纯纯的大冤种，白交了存储费。

2.4 上下文长度管理

2.4.1 上下文长度说明

  • 默认长度：200K tokens
  • 扩展长度：1M tokens（需站点支持）

什么是上下文：

  • 大模型在当前对话中可以记住的内容
  • 包括历史消息、读取的文件、生成的代码等

2.4.2 切换到 1M 上下文

/model sonnet[1m]

前提：你购买的 API 站点需要支持 1M 上下文

2.4.3 上下文压缩

自动压缩（默认开启）：

  • 当上下文使用超过 95% 时自动触发
  • 保留摘要，清除详细历史

手动压缩：

/compact

配置管理：

/config

2.5 模型切换

2.5.1 Claude 模型家族

模型 特点 适用场景
Sonnet 平衡性能和速度 日常开发、代码生成
Opus 最强推理能力 复杂问题、架构设计
Haiku 速度最快、成本最低 简单任务、快速迭代

2.5.2 命令行切换

# 打开模型选择菜单
/model

# 直接切换到指定模型
/model sonnet
/model opus
/model haiku

# 切换到 1M 上下文版本
/model sonnet[1m]

2.6 项目模式（Project Mode）

2.6.1 什么是项目模式

  • Claude Code 在特定目录下工作时会自动检测为项目
  • 项目模式下会保存：
    • 对话历史
    • 文件修改记录
    • 项目特定配置

2.6.2 项目初始化

# 在项目目录下启动 Claude Code
cd your-project
claude

# 或指定项目路径
claude --project /path/to/project

2.6.3 项目数据存储

Windows：%USERPROFILE%\.claude\projects\项目名\
Linux/macOS：~/.claude/projects/项目名/

存储内容：

  • history.jsonl：对话历史
  • context.json：项目上下文
  • metadata.json：项目元数据

2.7 MCP（Model Context Protocol）

2.7.1 MCP 简介

MCP 是 Claude Code 的扩展机制，允许接入外部工具和服务：

  • 文档查询：Context7、DeepWiki
  • 浏览器自动化：Playwright
  • Web 搜索：Exa、Open WebSearch
  • 自定义工具：通过 MCP 协议自行开发

2.7.2 MCP 工作原理

Claude Code → MCP Server → 外部工具/服务 → 返回结果 → Claude Code

2.7.3 常用 MCP 服务器

MCP Server 功能 推荐度
context7 查询最新技术文档 :star::star::star::star::star:
deepwiki 知识库检索 :star::star::star::star::star:
playwright 浏览器自动化 :star::star::star::star:
exa 智能 Web 搜索 :star::star::star::star:

2.8 Hooks（钩子机制）

2.8.1 什么是 Hooks

Hooks 是在特定事件触发时自动执行的 Shell 脚本：

  • 工具调用前：before-tool-use
  • 工具调用后：after-tool-use
  • 消息提交前：user-prompt-submit

2.8.2 Hooks 配置位置

全局 Hooks：

  • Windows：%USERPROFILE%\.claude\hooks\
  • Linux/macOS：~/.claude/hooks/

项目 Hooks：

  • .claude/hooks/（项目根目录）

2.8.3 常见应用场景

  1. 代码检查：提交前自动运行 ESLint
  2. 安全审计：工具调用前验证权限
  3. 日志记录：记录所有工具调用

2.9 Slash Commands（斜杠命令）

2.9.1 内置命令

命令 功能 示例
/model 切换模型 /model sonnet
/cost 查看令牌使用 /cost
/compact 压缩上下文 /compact
/config 打开配置 /config
/resume 恢复历史对话 /resume
/clear 清空当前对话 /clear

2.9.2 自定义命令

创建位置：

  • 全局：%USERPROFILE%\.claude\commands\
  • 项目：.claude/commands/

命令格式：

# my-command.md
这是自定义命令的提示词内容

使用方式：

/my-command

2.10 输出样式（Output Style）

2.10.1 样式类型

Claude Code 支持多种输出风格：

样式 特点 适用人群
Default 标准输出 通用
Concise 简洁模式 有经验的开发者
Detailed 详细解释 新手学习
Engineer Professional 工程师专业版 专业开发者

2.10.2 配置输出样式

在 settings.json 中配置：

{
  "outputStyle": "engineer-professional"
}

ZCF 用户：

  • 安装时会自动配置为 engineer-professional
  • 包含代码原则检查、危险操作确认等特性

2.11 免授权模式（:warning: 极度危险）

2.11.1 启动命令

claude --dangerously-skip-permissions

2.11.2 行为说明

  • Claude Code 将直接执行所有操作，无需确认
  • 极高风险：可能导致文件删除、系统配置变更等不可逆操作

:no_entry: 严重警告：除非完全信任执行的操作，否则强烈不推荐使用此模式！

2.11.3 适用场景

  • CI/CD 自动化流程
  • 完全可控的沙箱环境
  • 批量脚本执行（已验证安全性）

2.12 停止输出

快捷键：ESC（按一次即可）

效果：

  • 立即中断 Claude Code 的输出
  • 显示 Interrupted by user 提示

使用场景：

  • 发现问题描述错误
  • 输出方向不符合预期
  • 需要重新组织问题

2.13 图片上传

2.13.1 支持方式

  • 粘贴上传：Ctrl + V 或 Alt + V
  • 拖拽上传：直接拖拽图片到终端

2.13.2 兼容性说明

  • Claude Code 原生支持图片识别
  • 部分第三方 API 不支持图片处理（需调用 MCP）

2.13.3 应用场景

  • 截图调试：直接粘贴错误截图
  • UI 设计：上传设计稿生成代码
  • 文档识别：识别图片中的文字

2.14 令牌使用查询

2.14.1 原生查询方式

/cost

2.14.2 实时状态栏（推荐）

使用 CCometixLine 插件在状态栏实时显示：

  • 当前会话令牌消耗
  • 累计费用
  • 剩余额度

详细配置方法见《Claude Code 安装配置指南》。

2.15 历史记录管理

2.15.1 存储位置

Windows：

  • 历史记录：%USERPROFILE%\.claude\history.jsonl
  • 项目数据：%USERPROFILE%\.claude\projects\

Linux/macOS：

  • 历史记录：~/.claude/history.jsonl
  • 项目数据：~/.claude/projects/

2.15.2 命令行查看

/resume

2.15.3 可视化工具

Claudia Global：

  • 可视化历史记录查看
  • API 和 URL 配置管理
  • 可替代 CC Switch 使用

项目地址：Claudia Global

三、高级特性

3.1 多会话管理

3.1.1 会话隔离

  • 每个终端窗口独立会话
  • 不同项目目录独立上下文
  • 可同时运行多个 Claude Code 实例

3.1.2 会话切换

# 查看所有会话
/resume

# 恢复指定会话
/resume <session-id>

3.2 配置文件层级

3.2.1 配置优先级

项目配置 > 用户配置 > 全局配置

3.2.2 配置文件位置

  1. 全局配置：~/.claude/settings.json
  2. 用户配置：~/.claude/config.json
  3. 项目配置：.claude/config.json

3.3 环境变量

3.3.1 核心环境变量

变量名 作用 示例
ANTHROPIC_BASE_URL API 基础 URL https://api.example.com/v1
ANTHROPIC_AUTH_TOKEN API 认证令牌 sk-xxxxxxxxxxxx
CLAUDE_MODEL 默认模型 claude-sonnet-4
CLAUDE_MAX_TOKENS 最大上下文 1000000

3.3.2 设置环境变量

Windows：

[System.Environment]::SetEnvironmentVariable("变量名", "值", [System.EnvironmentVariableTarget]::User)

Linux/macOS：

export 变量名="值"
echo 'export 变量名="值"' >> ~/.bashrc

四、最佳实践

4.1 性能优化

  1. 启用上下文缓存：重度开发选择 1 小时缓存
  2. 合理压缩上下文：定期使用 /compact 清理无用历史
  3. 选择合适模型：简单任务用 Haiku，复杂问题用 Opus

4.2 成本控制

  1. 小额多次充值：降低资金风险
  2. 监控令牌消耗：使用 CCometixLine 实时监控
  3. 多站点备份：避免单点故障

4.3 安全建议

  1. 妥善保管 API Token：不要泄露到公共仓库
  2. 谨慎使用免授权模式：仅在可控环境使用
  3. 定期备份项目：防止意外数据丢失
11 个赞