Claude Code 完全教程指南

面向零代码基础产品经理的实操手册创建日期：2026-03-19

第一部分：Claude Code 核心模块

1. CLAUDE.md — 给 AI 的工作手册

是什么？

CLAUDE.md 是一个文本文件，Claude 每次开始新对话都会自动读取它。相当于你给 AI 写的一份"入职须知"，告诉它：你是谁、怎么工作、有什么规矩。

三级层次

层级	位置	作用范围	用途
用户级	`~/.claude/CLAUDE.md`	你所有项目通用	写通用偏好（中文回复、通俗解释等）
项目级	项目根目录的 `CLAUDE.md` 或 `.claude/CLAUDE.md`	某个具体项目	写该项目的技术规范、构建命令
文件夹级	子目录中的 `CLAUDE.md`	某个子模块	特定模块的规则

优先级：文件夹级 > 项目级 > 用户级（更具体的规则覆盖更通用的规则）。

高级功能

引用其他文件：用 @路径 语法引用外部文件：

参考 @README.md 了解项目概况
参考 @package.json 了解可用的 npm 命令

按路径生效的规则：在 .claude/rules/ 目录下创建带路径限定的规则文件：

yaml

---
paths:
  - "src/api/**/*.ts"
---
# API 开发规则
- 所有接口必须包含输入校验
- 使用统一的错误响应格式

注意事项

建议单个文件不超过 200 行，太长会影响效果
规则写得越具体越好（"用 2 空格缩进" 优于 "格式要好看"）
永久性规则一定写在 CLAUDE.md 里，不要只在对话中说，因为对话内容可能被压缩掉

2. Settings — AI 的权限和行为规则

是什么？

设置文件控制 Claude 能做什么、不能做什么。比如：允许它运行测试命令，但禁止它删文件。

三个配置位置（优先级从高到低）

位置	文件路径	用途
本地级	`.claude/settings.local.json`	你个人的项目私有设置（不提交到 Git）
项目级	`.claude/settings.json`	团队共享的项目设置（提交到 Git）
用户级	`~/.claude/settings.json`	你个人的全局设置

可配置的内容

配置项	作用	示例
`permissions.allow`	允许 Claude 做的事	运行测试、读写文件
`permissions.deny`	禁止 Claude 做的事	删除文件、强制推送
`mcpServers`	外部服务集成	GitHub、数据库
`hooks`	自动化触发器	编辑后自动格式化
`model`	使用的 AI 模型	sonnet / opus / haiku

配置示例

json

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(npm test)",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  }
}

通俗类比：这相当于给 AI 一张"工牌"——可以进入办公室（读写文件）、可以检查工作（运行测试），但不能碰消防栓（删除文件）、不能私自发布产品（强制推送代码）。

3. Plan Mode — 只看不动手模式

是什么？

Plan Mode 让 Claude 进入"只读模式"：它可以看代码、分析问题、提出方案，但不能修改任何东西。只有你批准计划后，它才能动手。

怎么用？

按 Shift+Tab 两次切换到 Plan Mode
或启动时加参数：claude --permission-mode plan

Claude 在 Plan Mode 下能做 / 不能做

能做	不能做
读取文件	编辑文件
搜索代码	运行命令
向你提问	修改任何东西
制定详细计划	—

适用场景

技术选型："对比 React 和 Vue 做这个项目，从维护难度、交接友好度、社区生态分析"
架构分析："帮我理清这个项目的整体结构"
方案设计："规划一下怎么给这个系统加用户认证"
代码评审："看看这段代码有什么问题"

典型工作流

1. 按 Shift+Tab 两次 → 切换到 Plan Mode
2. 输入需求 → Claude 调研分析，输出方案
3. 你审阅方案 → 提问、调整
4. 确认满意 → 按 Shift+Tab 切回默认/自动模式
5. Claude 开始执行计划

4. Subagents — AI 的助手团队

是什么？

Claude 可以派出"小助手"去做特定任务，做完后汇报结果。主对话不会被大量细节淹没。

通俗类比：你是总经理，Claude 是总监。总监可以派实习生（子代理）去做具体调研，然后把结果摘要汇报给你。

三种内置子代理

类型	擅长	速度	使用场景
Explore	搜索文件、分析代码结构	最快	"帮我搞清楚这个项目的文件结构"
Plan	只读研究、制定方案	中等	技术选型调研
通用（General）	能读能写，全能	最慢	复杂的多步骤任务

自定义子代理（Agent）

你可以创建自己的"专家角色"。在 .claude/agents/ 目录下创建 .md 文件即可。

代码审查员示例 — .claude/agents/code-reviewer.md：

yaml

---
name: code-reviewer
description: 代码质量审查
tools: Read, Grep, Glob
---
你是一个高级代码审查员，请对照项目目标和计划，检查：
1. 代码是否实现了需求
2. 是否有安全问题
3. 代码是否可读、可维护
4. 测试是否覆盖
用中文输出审查报告。

控制方式

配置	作用
`tools: Read, Grep, Glob`	限制子代理只能用特定工具（如只读）
`model: haiku`	指定使用更快/更便宜的模型
`disable-model-invocation: true`	只能你手动调用，Claude 不能自动调用

5. MCP Servers — 给 AI 装插件

是什么？

MCP（Model Context Protocol）是一种协议，让 Claude 连接外部工具和服务。就像给手机装 App，装了之后 Claude 就能操作那个工具。

安装命令

bash

# 添加 GitHub 集成（推荐）
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 添加 Sentry 错误监控
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

三个作用域

作用域	命令参数	共享范围
本地	默认	只有你，只在这个项目
项目	`--scope project`	团队所有人（通过 `.mcp.json` 共享）
用户	`--scope user`	你自己所有项目

常用 MCP 服务

服务	用途	对应需求
GitHub	管理仓库、PR、Issue	版本管理 + 过程管控
Sentry	监控线上错误	部署后监控
数据库	直接查询数据	数据分析
Slack	发送消息通知	团队协作

管理命令

bash

claude mcp list          # 查看已安装的 MCP 服务
claude mcp remove github # 删除某个 MCP 服务

在 Claude Code 会话内用 /mcp 查看连接状态和资源占用。

6. Hooks — 自动化检查站

是什么？

Hooks 是在 Claude 执行操作前后自动触发的脚本。

通俗类比：工厂流水线上的质检点——产品经过时自动检测，不合格就拦下来。

全部 Hook 事件

事件	触发时机	典型用法
`PreToolUse`	Claude 使用工具之前	阻止危险操作（如 `rm -rf`）
`PostToolUse`	Claude 使用工具之后	自动格式化刚编辑的代码
`PermissionRequest`	Claude 请求权限时	自动批准安全操作
`UserPromptSubmit`	你发送消息时	自动注入当前项目状态信息
`SessionStart`	会话启动时	加载环境变量
`Stop`	Claude 完成回复时	检查测试是否通过
`SubagentStart`	子代理启动时	设置子代理的环境

配置位置

写在 .claude/settings.json 的 hooks 字段中。

配置示例

编辑文件后自动运行代码检查：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint"
          }
        ]
      }
    ]
  }
}

Claude 完成任务时弹出桌面通知（macOS）：

json

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude 已完成\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Hook 的四种类型

类型	用途	复杂度
command	运行一条 Shell 命令	最简单
http	调用远程接口	中等
prompt	让 AI 做一个是/否判断	中等
agent	启动一个子代理做复杂验证	最复杂

7. Skills — 一键触发的工作流

是什么？

Skills 是预设好的指令模板，输入 /技能名 一键调用。

通俗类比：你手机的快捷指令/自动化——按一下就执行一整套操作。

内置技能

技能	作用	适用场景
`/simplify`	审查最近改动的代码质量	每完成一个模块后执行
`/loop 5m 检查部署状态`	定时循环执行某个操作	部署后持续监控
`/claude-api`	加载 Claude API 文档	开发 AI 相关功能

自定义技能

在 .claude/skills/技能名/SKILL.md 中创建。

文件结构：

.claude/skills/
├── requirement/SKILL.md    ← 需求整理技能
├── review/SKILL.md         ← 代码审查技能
└── handover/SKILL.md       ← 交接文档技能

技能文件格式：

yaml

---
name: 技能名称
description: 技能描述（Claude 用这个判断何时触发）
user-invocable: true          # true = 你可以用 /名称 触发
disable-model-invocation: true # true = 只有你能触发，Claude 不能自动触发
allowed-tools: Read, Grep      # 可选，限制技能可用的工具
---

这里写具体的指令内容...

Skills vs Agents 的区别

对比维度	Skills（技能）	Agents（子代理）
本质	一段指令模板	一个独立的 AI 角色
运行在	当前对话中	独立的上下文中
能看到主对话历史？	能	不能
适合	流程化的操作步骤	需要独立判断的专项任务

8. Memory — AI 的笔记本

是什么？

Claude 能自动记住跨会话的经验教训，下次新对话会自动加载。

两种记忆机制

类型	谁来写	保存在哪	何时加载
CLAUDE.md	你手动写	项目目录或 `~/.claude/`	每次会话自动加载
Auto Memory	Claude 自动写	`~/.claude/projects/<项目>/memory/`	每次会话自动加载前 200 行

Auto Memory 的工作方式

你多次纠正 Claude 同一个问题 → 它记住
你表扬某种做法 → 它记住
它发现有用的调试经验 → 它记住
你主动说"记住：XXXX" → 它立即记住
你说"忘记 XXXX" → 它删除对应记忆

管理记忆

会话内输入 /memory → 查看加载了哪些记忆文件
记忆文件结构示例：

~/.claude/projects/<项目>/memory/
├── MEMORY.md          ← 索引文件（前 200 行自动加载）
├── debugging.md       ← 调试经验
├── api-conventions.md ← API 设计决策
└── preferences.md     ← 你的偏好

9. Git 集成 — 代码版本管理

基本操作

你说的话	Claude 做的事
"提交这些改动"	执行 `git add` + `git commit`，自动写提交信息
"创建一个 PR"	调用 `gh pr create`，创建 Pull Request
"看看最近的改动"	显示 `git log` 和 `git diff`
"切换到 main 分支"	执行 `git checkout main`

Worktrees — 并行开发

当你需要同时做两件事（比如一边修 bug 一边开发新功能），Worktree 给你创建互不干扰的"平行空间"。

终端 1：claude --worktree 修复登录bug    ← 独立的文件副本和分支
终端 2：claude --worktree 开发支付功能    ← 独立的文件副本和分支
两者互不影响，各自独立工作。

通俗类比：相当于复印了两份文件，分别在两份上标注修改，最后再合并。

10. Task System — AI 的待办清单

是什么？

Claude 在处理复杂任务时，会自动创建待办列表来跟踪进度。

操作方式

操作	方式
查看任务列表	按 `Ctrl+T` 或输入 `/tasks`
让 Claude 创建任务	"帮我把这个功能拆成子任务"
标记完成	Claude 完成后自动标记，或你说"标记任务 3 为完成"
清除任务	"清除所有任务"

特点

任务在上下文压缩后依然保留
适合多步骤的复杂开发任务

11. Context Management — 上下文管理

是什么？

Claude 的"工作记忆"有容量限制（上下文窗口）。对话越长，早期内容可能被压缩。

通俗类比：Claude 的脑子就像一张桌子，能同时摊开的文件有限。桌子快满了，就得整理收纳一下。

上下文中包含的内容

你们的对话历史
Claude 读过的文件内容
命令运行结果
CLAUDE.md 和规则文件
MCP 服务的工具描述
系统指令

管理命令

命令	作用
`/compact`	压缩历史对话，释放空间
`/compact 重点保留API设计`	带重点的压缩
`/context`	查看当前空间使用情况
`/clear`	完全清空，重新开始

优化建议

永久规则写 CLAUDE.md，别只在对话里说
大量输出的任务交给子代理
定期 /compact 保持"桌面"整洁
用 /mcp 检查不用的 MCP 服务，禁用以节省空间

12. 权限模式 — 安全阀

按 Shift+Tab 循环切换三种模式：

模式	说明	适用阶段
默认模式	每步操作都要你批准	刚接触 Claude Code 时
自动批准模式	自动编辑文件，命令仍需批准	进入开发阶段后
计划模式	只能看不能改	技术选型、方案分析

权限规则的通配符

Bash(npm *)         → 允许所有 npm 命令
Bash(git status)    → 只允许 git status 这一条
Bash(* --version)   → 允许查看任何工具的版本

第二部分：命令类型详解

Claude Code 里的"命令"分为 5 大类，各自有不同的触发方式和用途。

类型一：内置斜杠命令（Slash Commands）

系统自带的命令，输入 / 开头触发。不可修改，不可扩展。

会话管理类

命令	作用	使用场景
`/clear`	清空当前对话，重新开始	对话太乱，想从头来
`/compact`	压缩历史对话，释放空间	对话长了，Claude 开始"忘事"
`/compact 关键词`	带重点的压缩	指定压缩时保留哪些内容
`/context`	查看上下文使用情况	想知道"内存"还剩多少

/clear 是扔掉笔记本重买一本；/compact 是整理浓缩笔记，腾出空白页。

配置查看类

命令	作用	使用场景
`/memory`	查看加载的 CLAUDE.md 和记忆文件	确认规则是否被读到
`/permissions`	查看当前权限设置	检查 Claude 能做/不能做什么
`/mcp`	查看已连接的 MCP 服务	确认外部服务是否连上
`/cost`	查看本次会话的 Token 消耗和费用	控制成本
`/status`	查看登录状态和账户信息	确认账号正常

操作类

命令	作用	使用场景
`/help`	查看帮助信息	不知道怎么用的时候
`/fast`	切换快速模式（同模型，更快输出）	简单任务想加速
`/tasks`	查看任务列表	查看 Claude 拆分的任务进度
`/bug`	报告 Claude Code 的 Bug	遇到工具本身的问题

类型二：技能命令（Skills）

可扩展的工作流命令，输入 /技能名 触发。可自定义。

与内置斜杠命令的区别

对比	内置斜杠命令	技能命令
提供者	Claude Code 系统自带	你自己创建 / 插件提供
能否修改	不能	完全自定义
用途	系统操作	业务工作流

已有的技能命令

系统内置

命令	作用	使用场景
`/simplify`	审查最近改动的代码质量	模块开发完后审查
`/loop 5m 指令`	每 N 分钟自动执行一次	持续监控
`/claude-api`	加载 Claude API 文档	开发 AI 功能时参考

ECC 增强（已安装）

命令	作用	使用场景
`/plan`	需求分析 + 实施规划，等确认后才动手	开始新功能或新项目时
`/tdd`	测试驱动开发：先写测试再写代码	代码开发阶段
`/code-review`	对照目标做代码质量审查	每完成一个模块后
`/verify`	验证代码是否符合计划目标	审查阶段
`/quality-gate`	质量门禁检查，不达标不放行	模块完成后的最终检查
`/checkpoint`	保存当前开发状态快照	阶段性成果保存
`/build-fix`	自动修复编译和运行错误	遇到报错时
`/update-docs`	生成开发者接手文档	部署或交接时

类型三：自然语言命令

直接用中文说话，最灵活，最常用的交互方式。不需要任何特殊语法。

使用示例

你说的话	Claude 做的事	对应场景
"帮我分析一下这个项目的文件结构"	扫描目录，输出结构说明	了解项目
"用 React 写一个登录页面"	创建代码文件	代码开发
"对比 React 和 Vue 的优劣"	调研分析，输出对比报告	技术选型
"把这些改动提交到 GitHub"	执行 git commit + push	版本管理
"帮我创建一个 PR"	创建 Pull Request	过程管控
"搜索一下最新的 AI 行业新闻"	联网搜索	内容创作
"把这段内容改写成小红书风格"	文本改写	内容创作
"记住：我所有项目都用 GitHub"	写入 Memory	持久化偏好

`@` 引用文件

在自然语言中用 @ 可以引用文件，Claude 会自动读取该文件内容：

请阅读 @src/components/Login.tsx 并检查有没有安全问题
参考 @需求文档.md 帮我生成项目计划

类型四：Bash 命令

直接运行终端命令，有两种方式：

方式 1：`!` 前缀（你直接执行）

!npm test        ← 直接运行，不经过 Claude 判断
!git status      ← 直接运行
!ls -la          ← 直接运行

方式 2：自然语言委托 Claude 执行

运行一下 npm test 看看测试结果    ← Claude 判断并执行，可能需要你确认

两种方式对比

方式	谁在执行	是否需要确认	适合
`!命令`	你自己	不需要	你明确知道要运行什么
自然语言	Claude 代你执行	取决于权限模式	不确定具体命令时

建议：零代码基础用户主要用自然语言方式，让 Claude 帮你判断该运行什么命令。

类型五：键盘快捷键

通过按键触发，不需要输入文字。

模式切换

快捷键	作用
`Shift+Tab`	循环切换权限模式：默认 → 自动批准 → 计划模式

操作控制

快捷键	作用	场景
`Ctrl+C`	中断 Claude 当前操作	Claude 跑偏了或输出太多
`Ctrl+T`	显示/隐藏任务列表	查看任务进度
`Ctrl+L`	清屏（不丢历史）	屏幕太乱想清爽
`Shift+Enter`	换行（不发送）	想输入多行文字再一起发送
`Ctrl+O`	切换详细模式	想看 Claude 的详细推理过程
`Esc` `Esc`	回退到之前的状态	Claude 搞错了，想撤回

五类命令总结对比

┌──────────────────────────────────────────────────────────────┐
│                    Claude Code 命令类型                        │
├───────────┬──────────────────────────────────────────────────┤
│  /clear   │  ① 内置斜杠命令 — 系统操作                        │
│  /compact │     清屏、压缩、查看状态                           │
│  /memory  │     ★ 用来"管理 Claude 本身"                      │
├───────────┼──────────────────────────────────────────────────┤
│  /review  │  ② 技能命令 — 自定义工作流                        │
│  /handover│     可自己创建的业务流程                           │
│  /simplify│     ★ 用来"标准化你的工作流程"                     │
├───────────┼──────────────────────────────────────────────────┤
│  中文对话  │  ③ 自然语言 — 最灵活的方式                        │
│  @引用文件 │     直接说需求，Claude 自动判断怎么做              │
│           │     ★ 你 90% 时间用这种方式                       │
├───────────┼──────────────────────────────────────────────────┤
│  !npm test│  ④ Bash 命令 — 直接运行终端命令                   │
│  !git log │     跳过 AI 解读，直接执行                        │
│           │     ★ 熟悉后的进阶用法                            │
├───────────┼──────────────────────────────────────────────────┤
│ Shift+Tab │  ⑤ 键盘快捷键 — 按键触发                         │
│ Ctrl+C    │     切换模式、中断、查看任务                       │
│ Ctrl+T    │     ★ 随时需要随时按                              │
└───────────┴──────────────────────────────────────────────────┘

使用优先级建议

  优先用                                              以后再学
    ↓                                                    ↓
 自然语言  →  内置斜杠命令  →  键盘快捷键  →  技能命令  →  Bash 命令
（90%时间）  （日常管理）    （随手操作）   （建好后用）  （进阶用法）

第三部分：实操配置指南

按你的工作流程分阶段配置

阶段 1：需求收集与计划

用到的模块	配置/操作
CLAUDE.md	写入输出格式要求（Part A + Part B）
Plan Mode	`Shift+Tab` 切到计划模式做需求分析
自定义技能	创建 `/requirement` 技能
WebSearch	Claude 自动联网搜索补充信息

阶段 2：技术选型确认

用到的模块	配置/操作
Plan Mode	全程在计划模式下做技术调研
Subagents	Claude 派 Explore 子代理分析项目结构
自然语言	"对比 React 和 Vue 的优劣，从维护成本、社区生态角度"

阶段 3：代码开发

用到的模块	配置/操作
权限模式	切到自动批准模式加速开发
Task System	Claude 自动拆分任务并跟踪进度
CLAUDE.md	项目级规则确保代码风格统一
Memory	自动记住开发过程中的经验

阶段 4：模块级审查

用到的模块	配置/操作
自定义技能	`/review` 一键审查
自定义 Agent	`code-reviewer` 子代理做独立审查
Hooks	编辑后自动运行 lint 检查
/simplify	内置技能审查代码质量

阶段 5：部署上线

用到的模块	配置/操作
自定义技能	`/handover` 生成交接文档
Git 集成	创建 PR、管理版本
MCP GitHub	直接通过 Claude 管理 GitHub

搭建路线图

第 1 步 ──→ 配置 ~/.claude/CLAUDE.md（通用偏好）
             │
第 2 步 ──→ 配置 ~/.claude/settings.json（权限规则）
             │
第 3 步 ──→ 安装 ECC 增强组件（agents/commands/rules/skills）
             │
第 4 步 ──→ 开始第一个项目时，创建项目级 CLAUDE.md
             │
第 5 步 ──→ 添加 GitHub MCP 集成
             │
第 6 步 ──→ 按需扩展：添加更多 ECC 组件或 Hooks

ECC 增强组件（已安装）

是什么？

Everything Claude Code (ECC) 是一个开源的 Claude Code 增强套件，提供了经过验证的子代理、工作流命令、编码规则和技能模板。我们从中精选了适合当前需求的部分组件，安装到用户级目录。

通俗类比：Claude Code 是一台电脑，ECC 是一套预装的办公软件。我们没有全装，只挑了最实用的几个。

安装了什么

所有组件安装在 ~/.claude/（用户级），对所有项目全局生效：

Agents — 5 个专职子代理

子代理	文件	用途	对应工作阶段
planner	`~/.claude/agents/planner.md`	需求分析、任务拆分、实施规划	阶段 1 需求收集
architect	`~/.claude/agents/architect.md`	技术选型、架构设计	阶段 2 技术选型
tdd-guide	`~/.claude/agents/tdd-guide.md`	测试驱动开发指导	阶段 3 代码开发
code-reviewer	`~/.claude/agents/code-reviewer.md`	代码质量审查	阶段 4 模块审查
build-error-resolver	`~/.claude/agents/build-error-resolver.md`	编译/运行错误修复	阶段 3-4

这些子代理在独立的上下文窗口中运行，不消耗主对话的空间。Claude 会根据任务自动判断何时委派给它们。

Commands — 8 个工作流命令

命令	文件	用途	怎么触发
`/plan`	`~/.claude/commands/plan.md`	启动规划流程，等待确认后才动手	输入 `/plan`
`/tdd`	`~/.claude/commands/tdd.md`	测试驱动开发：先写测试再写代码	输入 `/tdd`
`/code-review`	`~/.claude/commands/code-review.md`	对照目标做代码审查	输入 `/code-review`
`/verify`	`~/.claude/commands/verify.md`	验证代码是否符合计划目标	输入 `/verify`
`/checkpoint`	`~/.claude/commands/checkpoint.md`	保存当前开发状态快照	输入 `/checkpoint`
`/quality-gate`	`~/.claude/commands/quality-gate.md`	质量门禁：不达标不放行	输入 `/quality-gate`
`/build-fix`	`~/.claude/commands/build-fix.md`	自动修复编译和运行错误	输入 `/build-fix`
`/update-docs`	`~/.claude/commands/update-docs.md`	生成/更新开发者接手文档	输入 `/update-docs`

Rules — 14 个编码规则

目录	文件数	内容	加载方式
`~/.claude/rules/common/`	9	通用编码风格、Git 流程、测试、安全等	每次会话启动加载
`~/.claude/rules/typescript/`	5	TypeScript/React 特定规则	仅访问 .ts/.tsx/.js/.jsx 文件时按需加载

通用规则约占 10KB 上下文，影响很小。TypeScript 规则有 paths 限定（如 **/*.ts），不做 Web 开发时完全不加载。

Skills — 4 个开发技能

技能	目录	用途
tdd-workflow	`~/.claude/skills/tdd-workflow/`	TDD 工作流模板，确保 80%+ 测试覆盖
coding-standards	`~/.claude/skills/coding-standards/`	编码标准和最佳实践
frontend-patterns	`~/.claude/skills/frontend-patterns/`	React/Next.js 前端模式
deployment-patterns	`~/.claude/skills/deployment-patterns/`	部署、CI/CD、Docker 模式

技能采用两阶段加载：描述始终在上下文中（让 Claude 知道有这个技能），完整内容只在调用时加载。

ECC 增强后的 5 阶段工作流

阶段 1：需求收集与计划
  └─ /plan → planner 子代理分析需求，输出实施计划 → 等你确认

阶段 2：技术选型
  └─ Shift+Tab 切到计划模式 → architect 子代理对比技术方案 → 你做决策

阶段 3：代码开发
  └─ /tdd → tdd-guide 子代理指导 → 先写测试再写代码 → 任务小颗粒度拆分

阶段 4：模块审查
  └─ /code-review → code-reviewer 子代理审查
  └─ /verify → 验证是否符合计划目标
  └─ /quality-gate → 质量门禁检查
  └─ 通过后 → /checkpoint 保存状态 → 进入下一模块

阶段 5：部署上线
  └─ /update-docs → 生成接手文档（拉代码、装依赖、运行、部署步骤）
  └─ /build-fix → 遇到编译错误时修复

各组件的上下文消耗

安装组件会占用 Claude 的"工作记忆"，了解消耗有助于合理管控：

组件类型	消耗方式	影响大小
Rules（无 paths）	每次会话启动全部加载	小（约 10KB）
Rules（有 paths）	仅访问匹配文件时加载	极小
Skill 描述	始终在上下文中	小（总预算约 16K 字符）
Skill 完整内容	仅调用 `/技能名` 时加载	按需，不用不占
Agent 定义	在独立上下文窗口运行	零消耗（不占主对话空间）
Commands	仅调用 `/命令` 时加载	按需，不用不占

扩展与管理

ECC 源码仓库保留在 ~/Desktop/ecc-source/，后续扩展直接从这里复制。

添加新组件：

bash

# 示例：后续想加内容创作技能
cp -r ~/Desktop/ecc-source/skills/content-engine ~/.claude/skills/
cp -r ~/Desktop/ecc-source/skills/article-writing ~/.claude/skills/

# 示例：后续想加安全审查子代理
cp ~/Desktop/ecc-source/agents/security-reviewer.md ~/.claude/agents/

删除组件：直接删除对应文件即可，不需要卸载步骤。

bash

# 示例：删除不需要的规则
rm -rf ~/.claude/rules/typescript/  # 不做 TS 开发时可删除

禁用但不删除：

Skill：在 frontmatter 中设 disable-model-invocation: true
Agent：在 settings.json 的 permissions.deny 中加 Agent(agent-name)
MCP 服务：在 settings.json 中加到 disabledMcpServers 列表
Rules：重命名为非 .md 后缀（如 .md.bak）

附录

键盘快捷键速查表

快捷键	作用
`Shift+Tab`	切换权限模式
`Ctrl+C`	中断当前操作
`Ctrl+T`	显示/隐藏任务列表
`Ctrl+L`	清屏
`Ctrl+O`	详细模式
`Shift+Enter`	多行输入
`Esc Esc`	回退操作
`@文件路径`	引用文件

常用斜杠命令速查表

内置命令

命令	作用
`/clear`	清空对话
`/compact`	压缩对话
`/context`	查看上下文用量
`/memory`	查看记忆文件
`/permissions`	查看权限
`/mcp`	查看 MCP 服务
`/cost`	查看费用
`/help`	帮助
`/fast`	快速模式
`/tasks`	任务列表
`/simplify`	代码审查

ECC 增强命令

命令	作用	典型使用时机
`/plan`	需求分析 + 实施规划	开始新功能时
`/tdd`	测试驱动开发	写代码时
`/code-review`	代码质量审查	模块完成后
`/verify`	验证是否符合目标	审查阶段
`/quality-gate`	质量门禁	最终检查
`/checkpoint`	保存状态	阶段性成果
`/build-fix`	修复编译错误	报错时
`/update-docs`	生成接手文档	部署/交接时

文件位置速查表

文件	位置	用途
用户级 CLAUDE.md	`~/.claude/CLAUDE.md`	个人通用规则
用户级设置	`~/.claude/settings.json`	个人通用设置
用户级 Agents	`~/.claude/agents/*.md`	全局子代理（ECC 安装）
用户级 Commands	`~/.claude/commands/*.md`	全局工作流命令（ECC 安装）
用户级 Rules	`~/.claude/rules/*/.md`	全局编码规则（ECC 安装）
用户级 Skills	`~/.claude/skills/*/`	全局技能（ECC + 其他插件）
项目级 CLAUDE.md	`项目根目录/CLAUDE.md`	项目规则
项目级设置	`项目根目录/.claude/settings.json`	项目设置
项目级 Agent	`项目根目录/.claude/agents/名称.md`	项目专属子代理
项目级 Skill	`项目根目录/.claude/skills/名称/SKILL.md`	项目专属技能
自动记忆	`~/.claude/projects/<项目>/memory/`	Claude 的学习笔记
MCP 配置	`项目根目录/.mcp.json`	外部服务集成
ECC 源码仓库	`~/Desktop/ecc-source/`	扩展时从这里复制组件

Yazi — 终端文件管理器（Claude Code 的好搭档）

是什么？

Yazi 是一个用 Rust 编写的超快终端文件管理器，操作逻辑类似 Vim。用它可以在终端里可视化地浏览文件，快速定位到项目目录，然后启动 Claude Code。

通俗类比：Yazi 就是终端里的"访达（Finder）"，用键盘代替鼠标操作文件。

安装

bash

brew install yazi     # macOS

界面布局

Yazi 采用三栏布局，类似 macOS Finder 的分栏模式：

┌──────────┬──────────────────────┬──────────────────┐
│  父目录   │    当前目录（主区域）   │   预览区          │
│  上级视角  │    光标高亮选中项      │   文件内容/目录    │
│          │                      │   子项列表         │
└──────────┴──────────────────────┴──────────────────┘

底部状态栏：模式 | 文件大小 | 文件名 | 权限 | 位置百分比 | 当前项/总项数

进入一个目录后三栏整体左移：左栏变父级，中栏变新目录，右栏预览新内容。

快捷键速查

最常用（先记住这些就够了）

按键	功能
`↑`/`k` `↓`/`j`	上下移动光标
`←`/`h`	返回上级目录
`→`/`l` 或 `Enter`	进入目录 / 打开文件
`Space`	选中/取消选中文件
`q`	退出 Yazi
`~` 或 `F1`	打开帮助菜单（忘了快捷键就按这个）

文件操作

按键	功能
`y`	复制选中的文件
`x`	剪切选中的文件
`p` / `P`	粘贴（P 覆盖同名文件）
`a`	新建文件（名称以 `/` 结尾则创建目录）
`r`	重命名
`d`	删除到回收站
`D`	永久删除（谨慎！）
`.`	显示/隐藏隐藏文件

导航跳转

按键	功能
`g h`	跳到 Home 目录
`g d`	跳到 Downloads 目录
`g c`	跳到配置目录
`g Space`	交互式输入路径跳转（最灵活）
`g g` / `G`	跳到列表顶部 / 底部
`Ctrl+f` / `Ctrl+b`	向下 / 向上翻页
`z`	用 zoxide 智能跳转（需安装 zoxide）
`Z`	用 fzf 模糊搜索跳转

搜索与筛选

按键	功能
`f`	过滤当前目录文件
`/` / `?`	向下 / 向上查找文件名
`n` / `N`	跳到下一个 / 上一个匹配
`s`	按文件名搜索（需安装 fd）
`S`	按文件内容搜索（需安装 ripgrep）

选择文件

按键	功能
`Space`	切换当前文件的选中状态
`v` / `V`	进入 / 退出可视模式（批量选择）
`Ctrl+a`	全选
`Ctrl+r`	反选
`Esc`	取消所有选择

复制路径（很实用）

按键	功能
`c c`	复制文件完整路径
`c d`	复制所在目录路径
`c f`	复制文件名
`c n`	复制文件名（不含扩展名）

排序（按 `,` 进入排序模式）

按键	功能
`m` / `M`	按修改时间排（正序/倒序）
`s` / `S`	按大小排
`e` / `E`	按扩展名排
`n` / `N`	自然排序

标签页

按键	功能
`t`	新建标签页
`1`-`9`	切换到对应标签页
`[` / `]`	切换上一个/下一个标签页

其他

按键	功能
`;` 或 `:`	运行 shell 命令
`w`	打开任务管理器（查看复制/移动进度）
`Ctrl+z`	挂起 Yazi（回到终端，用 `fg` 恢复）
`O`	交互式打开（选择用什么程序打开）

与 Claude Code 配合使用

场景 1：用 Yazi 导航到项目目录，然后启动 Claude

在 Yazi 里浏览到目标项目目录后，按 ; 输入 claude 回车，即可在该目录启动 Claude Code。

场景 2：退出 Yazi 后终端自动跟随目录

默认退出 Yazi 后终端还停在原目录。在 ~/.zshrc 中加入以下函数，用 y 代替 yazi 启动：

bash

function y() {
    local tmp="$(mktemp -t "yazi-cwd.XXXXXX")" cwd
    yazi "$@" --cwd-file="$tmp"
    if cwd="$(command cat -- "$tmp")" && [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
        builtin cd -- "$cwd"
    fi
    rm -f -- "$tmp"
}

配置后的典型工作流：

1. 终端输入 y → 启动 Yazi
2. 用 j/k/h/l 浏览，或 g Space 输入路径跳转到项目目录
3. 按 q 退出 → 终端自动 cd 到该目录
4. 输入 claude → 在项目目录启动 Claude Code

场景 3：配合 zoxide 智能跳转

安装 zoxide 后，在 Yazi 内按 z 可输入关键词智能跳转到常去的目录，无需记住完整路径。

bash

# 安装 zoxide
brew install zoxide

# 在 ~/.zshrc 末尾加一行
eval "$(zoxide init zsh)"

zoxide 会自动学习你 cd 过的目录，按访问频率排序。之后在 Yazi 里按 z，输入 my-app 就能直接跳到 /Users/xxx/Projects/my-app。

自定义配置

Yazi 的配置文件在 ~/.config/yazi/ 目录下：

文件	用途
`keymap.toml`	自定义快捷键
`yazi.toml`	通用设置（排序方式、显示选项等）
`theme.toml`	主题和颜色

CC-Viewer — Claude Code 的"监控仪表盘"

是什么？

CC-Viewer 是一个开源的 Claude Code 监控工具。它能实时捕获并可视化展示 Claude 和 API 之间的所有交互数据，包括请求内容、Token 消耗、缓存命中率等。

通俗类比：Claude Code 是你的员工在干活，CC-Viewer 就是办公室的监控大屏——你能实时看到他在做什么、花了多少资源、效率如何，但完全不影响他的工作。

为什么需要它？

痛点	CC-Viewer 怎么解决
不知道 Claude 每次请求花了多少 Token	每条请求旁边直接显示 Token 用量和缓存命中率
想回看之前的对话，但终端翻不回去了	所有交互自动记录成日志文件，随时可回看
想在手机上看 Claude 的工作进度	扫二维码，手机浏览器直接看
不清楚 Claude 调用了哪些子代理	自动标注 Main Agent / Sub Agent，一目了然

安装

bash

npm install -g cc-viewer --registry=https://registry.npmjs.org

安装后在任意目录都可以使用 ccv 命令。

注意：必须用 npm install -g（全局安装）。如果漏了 -g，就只装到了当前目录，换个目录就用不了。详见下方"常见问题"。

三种使用模式

模式一：编程模式（最常用）

用 ccv 替代 claude 命令启动 Claude Code：

bash

# 原来这样启动 Claude Code：
claude

# 现在改成这样：
ccv

效果：Claude Code 照常运行，同时自动打开一个网页仪表盘（地址：http://localhost:7008），实时显示所有 API 交互。

支持所有 Claude 命令参数：

命令	作用
`ccv`	正常启动（交互模式）
`ccv -c`	继续上次对话
`ccv -r`	恢复对话
`ccv --model opus`	指定使用 Opus 模型
`ccv -p "你好"`	单次提问模式

模式二：日志模式（后台记录）

bash

ccv -logger

不替代 claude 命令，而是在后台静默记录所有 API 请求到日志文件。你仍然用原来的 claude 命令工作，CC-Viewer 只负责记录。

日志保存在：~/.claude/cc-viewer/[项目名]/日期.jsonl

关闭日志模式：

bash

ccv --uninstall

模式三：对话模式（回看历史）

在网页仪表盘中点击"Conversation Mode"按钮，可以把原始 API 日志转换成聊天界面：

你的消息显示为右侧蓝色气泡
Claude 的回复显示为左侧深色气泡
思考过程可以折叠/展开

通俗类比：就像微信聊天记录一样的界面，比看原始日志舒服得多。

CLI 命令完整参考

ccv 的完整用法：

ccv [选项] [命令] [提示词]

CCV 专属选项

这三个是 CC-Viewer 自己的选项，不会传给 claude：

选项	作用	通俗解释
`-logger`	安装/修复 CC-Viewer 的 Hook	Hook 是一种自动运行的脚本，装好后 CC-Viewer 就能捕获 Claude 的交互数据并显示在网页上
`--uninstall`	卸载 CC-Viewer 集成	移除它安装的 Hook 和相关配置，恢复原状
`--d`	`--dangerously-skip-permissions` 的快捷方式	跳过所有权限确认弹窗。⚠️ 危险操作，仅在你完全信任当前任务时使用

Claude 透传选项

以下选项会原封不动传给底层的 claude 命令，功能完全一致：

会话管理

选项	作用	通俗解释
`-c, --continue`	续接最近一次对话	不开新会话，接着上次聊
`-r, --resume [ID]`	恢复指定对话	不传 ID 则弹出选择器让你挑一个历史会话
`-w, --worktree [名称]`	创建 Git 工作树	创建仓库的独立副本，适合不影响主分支的情况下工作

模型与性能

选项	作用	通俗解释
`--model <模型>`	指定 AI 模型	如 `opus`（最强推理）、`sonnet`（平衡）、`haiku`（最快最便宜）
`--effort <级别>`	推理努力程度	`low`（快速简答）、`medium`（平衡）、`high`（深度思考）、`max`（最大推理）

输出模式

选项	作用	通俗解释
`-p, --print`	打印模式	输出回答后立即退出，适合管道使用，如 `ccv -p "解释代码" \| less`
`--output-format <格式>`	输出格式（仅 `--print`）	`text`（纯文本）、`json`（JSON 对象）、`stream-json`（流式 JSON）
`--json-schema <schema>`	结构化输出	指定 JSON Schema，让 Claude 按固定结构返回结果
`--verbose`	详细输出	显示更多运行信息，排查问题时有用

权限与安全

选项	作用	通俗解释
`--dangerously-skip-permissions`	跳过所有权限检查	Claude 可以不经确认直接执行任何操作。⚠️ 仅在完全信任时使用
`--allowedTools <工具...>`	工具白名单	只允许 Claude 使用你指定的工具
`--disallowedTools <工具...>`	工具黑名单	禁止 Claude 使用指定的工具
`--permission-mode <模式>`	权限模式	设置自动批准、手动确认或只读等模式

提示词定制

选项	作用	通俗解释
`--system-prompt <提示词>`	替换系统提示词	完全覆盖默认的系统指令
`--append-system-prompt <提示词>`	追加系统提示词	在默认指令末尾追加内容，不覆盖原有规则

其他

选项	作用	通俗解释
`-d, --debug [过滤器]`	调试模式	开启调试输出，可选过滤器限定范围，排查问题时使用
`--mcp-config <配置...>`	加载 MCP 配置	从 JSON 文件加载 MCP 服务器配置（MCP = 让 Claude 连接外部工具的协议）
`--add-dir <目录...>`	添加访问目录	把额外目录加入 Claude 的访问白名单，默认只能访问当前工作目录
`--max-budget-usd <金额>`	API 花费上限	设置最大花费（美元），仅 `--print` 模式生效
`-h, --help`	帮助	显示帮助信息
`-v, --version`	版本	显示版本号

常用组合示例

bash

ccv                                     # 启动交互模式（最常用）
ccv -c                                  # 续接上次对话
ccv -r                                  # 从历史会话中选一个恢复
ccv -p "你好"                            # 单次提问，输出后退出
ccv --model opus                        # 用最强的 Opus 模型
ccv --d                                 # 跳过权限（危险快捷方式）
ccv -c --model sonnet --effort max      # 组合：续接 + Sonnet 模型 + 最大推理
ccv -logger                             # 安装/修复 Hook（日志模式）

核心理解：ccv 本质就是 claude 的包装器，额外加了 Web 监控界面。三个专属选项（-logger、--uninstall、--d）管理 Viewer 本身，其余选项全部透传给 Claude Code。

网页仪表盘功能一览

启动后浏览器访问 http://localhost:7008，可以看到：

功能区域	看什么	有什么用
请求列表	每条 API 请求的详情	看 Claude 具体在做什么
Token 统计	输入/输出 Token 数量	监控成本，避免浪费
缓存统计	缓存命中率、重建原因	判断对话效率
代理标注	Main Agent / Sub Agent 标签	看 Claude 派了几个子代理
工具统计	各工具/技能的调用频率排名	了解 Claude 的工作模式
日志管理	导入、合并、导出历史日志	回看和分析历史会话

手机远程查看

CC-Viewer 启动后会在终端显示一个二维码。用手机扫描后，即可在手机浏览器上实时查看 Claude 的工作状态。

前提：手机和电脑必须在同一个 Wi-Fi 网络下。

日志管理

操作	方法
查看历史日志	网页仪表盘 → 下拉菜单 → 按项目和日期选择
导入本地日志	支持加载 `.jsonl` 文件（最大 500MB）
合并多个日志	多选后合并成一个完整会话
导出对话记录	提取用户提示词，导出为 TXT 文件

配置

CC-Viewer 基本开箱即用，不需要额外配置。如有特殊需求：

配置项	方法	说明
自定义日志目录	设置环境变量 `CCV_LOG_DIR=/你的路径`	默认 `~/.claude/cc-viewer`
自定义 API 地址	在 `~/.claude/settings.json` 中设置，或设置环境变量 `ANTHROPIC_BASE_URL`	用了代理/中转时需要
开启调试日志	设置环境变量 `CCV_DEBUG_PLUGINS=1`	排查问题时用

常见问题

Q：安装了但换个目录就用不了 ccv 命令？

说明你安装时漏了 -g 参数，只做了本地安装。本地安装把工具装在了当前目录的 node_modules 里，不在系统 PATH 中，所以换目录就找不到了。

解决：重新全局安装一次：

bash

npm install -g cc-viewer --registry=https://registry.npmjs.org

Q：ccv 和 claude 有什么区别？

ccv 是 claude 的"包装版"。它会先启动监控服务，然后把你的所有参数原封不动地传给 claude。功能完全一样，只是多了一个监控网页。

Q：CC-Viewer 会影响 Claude Code 的性能吗？

不会。监控是旁路捕获的，不会减慢 Claude 的响应速度。

Q：不想用了怎么卸载？

bash

# 如果开启了日志模式，先关闭
ccv --uninstall

# 卸载 CC-Viewer
npm uninstall -g cc-viewer

Claude HUD — 状态栏增强插件

是什么？

Claude HUD 是一个 Claude Code 状态栏插件，把终端底部那一行状态信息升级成了一个迷你仪表盘。它能实时显示上下文健康度、Git 分支状态、工具活动、子代理进度、使用限额等信息。

通俗类比：Claude Code 原来的状态栏就像汽车仪表盘上只有一个速度表，Claude HUD 给你加上了油量表、转速表、导航信息、胎压监测……一眼就能知道整体状况。

为什么需要它？

痛点	Claude HUD 怎么解决
不知道上下文快用完了，Claude 突然开始"忘事"	彩色进度条实时显示上下文消耗（绿→黄→红）
不知道 Claude 当前在用什么工具	实时显示正在运行的工具（编辑、搜索、读取等）
派了子代理不知道跑到哪一步了	显示子代理名称和运行状态
忘了当前在哪个 Git 分支	分支名 + 未提交变更提示，一目了然
Pro/Max 用户不知道速率限额还剩多少	显示 5 小时和 7 天限额消耗百分比

状态栏长什么样？

Claude HUD 有两种布局模式：

展开模式（expanded，默认）

 myproject main*                  Opus 4.6
 Context ██████░░░░ 58%    5h: 23% | 7d: 12%
 ◐ Edit: login.tsx | ✓ Read ×3 | ✓ Grep ×2
 ▸ code-reviewer (running)  Tasks: 3/5
 ⏱ 12m  📄 3 rules  🔌 2 MCPs

各行含义：

行	内容	一句话解释
第 1 行	项目名 + Git 分支 + 模型名	当前在哪个项目的哪个分支，用的什么模型
第 2 行	上下文进度条 + 使用限额	"内存"用了多少，速率限额还剩多少
第 3 行	工具活动	Claude 正在做什么（编辑、搜索、读取文件等）
第 4 行	子代理 + 任务进度	派出的助手在干嘛，任务完成了几个
第 5 行	会话时长 + 配置计数	干了多久，加载了多少规则和插件

紧凑模式（compact）

所有信息压缩到一行，适合小屏幕。

与原有状态栏（ccstatusline）的对比

对比维度	ccstatusline（原有）	Claude HUD（新装）
显示内容	模型、上下文%、花费、Token 数	模型、上下文进度条、Git、工具、代理、任务、限额
视觉效果	纯文本，单行	彩色进度条，可多行
Git 集成	无	分支名 + 脏状态 + 领先/落后
工具追踪	无	实时显示正在使用的工具
子代理追踪	无	显示运行中的子代理
任务进度	无	显示 Todo 完成情况
使用限额	无	5 小时 / 7 天速率限额
花费显示	有（USD）	无
Token 明细	有（输入/输出/缓存）	无（只有百分比）

总结：ccstatusline 侧重成本监控（花了多少钱、用了多少 Token），Claude HUD 侧重开发状态感知（干到哪了、还能干多久、分支对不对）。两者各有所长，所以我们做了一键切换。

安装

已通过插件市场安装完成。如需在新环境重新安装：

# 在 Claude Code 交互界面中依次执行：
/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/claude-hud:setup

安装后需要完全退出并重启 Claude Code 才能看到效果。

配置

方式一：交互式配置（推荐新手）

/claude-hud:configure

会弹出选项让你选择预设布局和功能开关。

方式二：手动编辑配置文件

配置文件位置：~/.claude/plugins/claude-hud/config.json

当前已启用的配置：

json

{
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showConfigCounts": true,
    "showSessionName": true
  }
}

全部可配置项

配置项	默认值	作用	通俗解释
`lineLayout`	`expanded`	布局模式	`expanded` 多行显示，`compact` 压缩成一行
`pathLevels`	`1`	项目路径深度	显示几层目录名（1=只显示项目名）
`gitStatus.enabled`	`true`	Git 分支	显示当前 Git 分支名
`gitStatus.showDirty`	`true`	脏状态	有未提交改动时显示 `*`
`gitStatus.showAheadBehind`	`false`	领先/落后	显示比远程多/少几个提交（↑N ↓N）
`gitStatus.showFileStats`	`false`	文件统计	显示修改/新增/删除的文件数
`display.showModel`	`true`	模型名	显示当前使用的 AI 模型
`display.showContextBar`	`true`	上下文进度条	彩色进度条显示"内存"用量
`display.contextValue`	`percent`	上下文格式	`percent`（百分比）/ `tokens`（Token 数）/ `remaining`（剩余）
`display.showUsage`	`true`	使用限额	显示 5 小时和 7 天速率限额（仅官方账号）
`display.showTools`	`false`	工具活动	显示 Claude 正在使用的工具
`display.showAgents`	`false`	子代理状态	显示运行中的子代理
`display.showTodos`	`false`	任务进度	显示 Todo 完成情况
`display.showConfigCounts`	`false`	配置计数	显示加载了多少 CLAUDE.md、规则、MCP、Hooks
`display.showDuration`	`false`	会话时长	显示当前会话持续了多久
`display.showSpeed`	`false`	输出速度	显示 Token 输出速率
`display.showSessionName`	`false`	会话名称	显示会话标识或 /rename 设置的名称

三种预设布局

用 /claude-hud:configure 可以快速选择：

预设	内容	适合谁
Full	所有功能全开	想看最全信息的重度用户
Essential	活动行 + Git 状态，其他精简	大多数日常使用
Minimal	只有模型名和上下文进度条	喜欢极简界面的用户

上下文进度条颜色含义

颜色	含义	建议操作
🟢 绿色	充足，放心使用	继续工作
🟡 黄色	过半，注意节约	考虑 `/compact` 压缩一下
🔴 红色	接近满载	立刻 `/compact` 或 `/clear`

使用限额说明

条件	Usage 是否显示
官方账号登录（Pro/Max/Team 订阅）	正常显示 5 小时和 7 天限额
API Key 模式（按 Token 计费）	不显示（因为没有速率限制）
本地代理转发	取决于代理是否转发了限额数据

当 7 天使用量 ≥ 80% 时，状态栏会显示黄色警告。

一键切换状态栏

我们安装了切换脚本，可以在 Claude HUD 和 ccstatusline 之间一键切换：

bash

bash ~/.claude/switch-statusline.sh

每次切换后都需要重启 Claude Code 才能生效。

什么时候该切换？

场景	推荐用	理由
日常开发，关注进度和分支	Claude HUD	Git 状态、工具追踪、任务进度一目了然
关注成本，想看花了多少钱	ccstatusline	有花费（USD）和 Token 明细显示
远程协作，需要看限额	Claude HUD	使用限额百分比提醒
屏幕小或终端窗口窄	ccstatusline 或 HUD compact 模式	单行显示更省空间

文件位置速查

文件	位置	用途
插件代码	`~/.claude/plugins/cache/claude-hud/`	插件本体（自动管理，不要手动改）
HUD 配置	`~/.claude/plugins/claude-hud/config.json`	显示选项（可手动编辑）
切换脚本	`~/.claude/switch-statusline.sh`	一键在两个状态栏之间切换
原配置备份	`~/.claude/settings.json.bak`	安装前的完整设置备份

常见问题

Q：重启 Claude Code 后状态栏没变化？

macOS 上需要完全退出（不是关窗口），然后重新打开终端输入 claude 启动。如果用了 tmux，需要退出 tmux 会话后重新启动。

Q：上下文进度条一直显示 0%？

正常现象。刚启动时上下文为空，随着对话进行会逐渐增加。

Q：使用限额（Usage）不显示？

三种可能：

你用的是 API Key 而非官方订阅账号 → 按 Token 计费无速率限制，不显示是正常的
你用了本地代理 → 代理可能没有转发限额数据
display.showUsage 被设为 false → 在配置文件中改回 true

Q：想恢复到安装前的状态？

bash

# 还原设置文件
cp ~/.claude/settings.json.bak ~/.claude/settings.json

# 重启 Claude Code 即可

Q：Claude HUD 会影响 Claude Code 的性能吗？

不会。状态栏命令是 Claude Code 主动调用的，每次刷新只需约 300 毫秒，完全在后台完成，不影响对话响应速度。

Q：插件更新后需要重新配置吗？

不需要。状态栏命令使用了动态路径查找，插件更新后会自动使用最新版本。配置文件（config.json）独立于插件代码，更新不会覆盖你的配置。

双模式切换 — 官方订阅 vs 中转站

背景

Claude Code 支持两种连接方式：直接使用 Anthropic 官方订阅（Pro/Max 套餐），或者通过第三方中转站转发请求。两套方案不能同时使用，需要切换配置文件。

两套方案对比

	方案 A：中转站	方案 B：官方订阅
原理	请求经过第三方代理转发	直接连 Anthropic 官方服务器
认证	中转站自动管理	你的 claude.ai 账号（OAuth 登录）
计费	按中转站的规则	按你的订阅套餐（固定月费）
封号风险	无（不经过官方风控）	有（需注意 IP、环境等）

怎么切换

两套方案的唯一区别，就是配置文件 ~/.claude/settings.json 里 "env" 这一段内容。其他所有配置（权限、插件、模型等）完全不用动。

切到方案 A：中转站

打开 ~/.claude/settings.json，确保 "env" 部分是：

json

"env": {
  "ANTHROPIC_AUTH_TOKEN": "PROXY_MANAGED",
  "ANTHROPIC_BASE_URL": "http://127.0.0.1:15721",
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
},

操作步骤：

确保 ccswitch 代理已启动
退出 Claude Code（Ctrl+C）
重新打开终端，输入 claude（或 ccv）启动，直接可用

切到方案 B：官方订阅

打开 ~/.claude/settings.json，把 "env" 部分改成：

json

"env": {
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
},

也就是删掉 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 这两行。

操作步骤：

确保你的代理（梯子）已开启，IP 为稳定的住宅 IP
退出 Claude Code（Ctrl+C）
重新打开终端，输入 claude 启动
首次切换会自动弹出浏览器，登录你的 claude.ai 账号并点击授权
之后再切回来不用重新登录，凭证已保存在 macOS 钥匙串中

方案 B 防封注意事项

每次使用官方订阅前，确保以下三点：

代理已开启，且 IP 所在地固定（不要频繁换国家）
不要短时间高强度使用（比如 1 小时几千条消息）
不要在无代理的情况下启动 Claude Code（会暴露真实 IP）

怎么确认当前用的是哪套方案

启动后输入 /status，看 Auth token 和 Anthropic base URL 两行：

看到的内容	说明
`Auth token: ANTHROPIC_AUTH_TOKEN` + 中转站地址	当前是方案 A（中转站）
显示你的账号信息 + 官方地址	当前是方案 B（官方订阅）

常见问题

Q：切换时会丢失聊天记录吗？

不会。聊天记录存在本地，跟用哪套方案无关。

Q：忘记改配置直接启动了怎么办？

没事，退出来改好配置再启动就行，不会造成任何损坏。

Q：两套方案能同时用吗？

不能。ANTHROPIC_AUTH_TOKEN 的优先级高于 OAuth 登录，如果两者都在，Claude Code 只会走中转站，官方订阅的登录会被忽略。更危险的是，如果 ANTHROPIC_BASE_URL 还指向中转站，你的官方账号凭证可能会被发送到第三方服务器。所以必须二选一。

claude-run — 轻量历史会话查看器

是什么？

claude-run 是一个轻量级的 Web 界面工具，用来浏览 Claude Code 的历史对话记录。一行命令启动，自动打开浏览器，就能看到你所有的历史会话。

通俗类比：Claude Code 的对话都存在你电脑的一个隐藏文件夹里（~/.claude/），但这些文件是机器格式，人看不懂。claude-run 就是把这些数据翻译成好看的聊天界面，让你像翻微信聊天记录一样回看跟 Claude 的对话。

为什么需要它？

痛点	claude-run 怎么解决
终端对话翻不回去了	所有历史会话按时间排列，随时回看
想找之前某次对话，但忘了在哪个项目	支持按项目筛选 + 关键词搜索
Claude 正在干活，想实时看进度	实时流式更新，边干活边看
想继续某次中断的对话	一键复制恢复命令，回终端粘贴即可

安装

bash

# 全局安装（推荐，装一次到处用）
npm install -g claude-run

# 或者不安装，直接运行（每次会临时下载）
npx claude-run

使用方法

bash

# 最简单的用法：直接运行
claude-run

运行后自动打开浏览器，地址是 http://localhost:12001。

命令行选项

选项	作用	通俗解释
`-V, --version`	显示版本号	检查装的是哪个版本
`-p, --port <端口号>`	自定义端口（默认 12001）	如果 12001 被占用，换个数字
`-d, --dir <路径>`	指定 Claude 目录	默认读 `~/.claude/`，一般不用改
`--no-open`	不自动打开浏览器	想手动打开时用
`-h, --help`	显示帮助	忘了选项就看这个

界面功能

┌────────────────────┬──────────────────────────────────┐
│  会话列表（左栏）    │     对话详情（右栏）               │
│                    │                                  │
│  🔍 搜索框          │  📋 会话标题 + 项目名 + 时间       │
│  📂 项目筛选器      │                                  │
│                    │  👤 你的消息                       │
│  ─────────────     │  🤖 Claude 的回复                 │
│  会话 1 (最新)      │  🔧 工具调用（可折叠）             │
│  会话 2            │  ...                             │
│  会话 3            │                                  │
│  ...               │  [复制恢复命令] 按钮               │
└────────────────────┴──────────────────────────────────┘

主要功能：

功能	说明
会话列表	按最近使用时间排序，最新的在最上面
项目筛选	点击左上角筛选器，只看某个项目的对话
搜索	输入关键词，按对话内容或项目名搜索
实时更新	如果 Claude 正在对话中，内容会实时刷新
工具调用折叠	Claude 调用的工具（读文件、运行命令等）默认折叠，点击展开
恢复对话	每个会话右上角有"复制恢复命令"按钮，粘贴到终端即可继续该对话
深色模式	默认深色主题，护眼

常见问题

Q：claude-run 和 CC-Viewer 有什么区别？

claude-run 是只读查看器，只能看历史对话，不能启动或控制 Claude Code。CC-Viewer 是 Claude 的包装器，替代 claude 命令使用，除了看对话还能监控 Token 消耗和 API 请求。两者定位不同。

Q：数据安全吗？会上传到网上吗？

不会。claude-run 是纯本地工具，只读取你电脑上 ~/.claude/ 目录的数据，数据不会离开你的电脑。

Q：启动后看不到任何会话？

说明你还没用 Claude Code 进行过对话，或者 ~/.claude/ 目录里没有会话数据。先用 claude 命令进行至少一次对话，再启动 claude-run。

Q：不想用了怎么卸载？

bash

npm uninstall -g claude-run

claude-code-viewer — 全功能历史会话管理客户端

是什么？

claude-code-viewer 是一个功能齐全的 Web 版 Claude Code 客户端。不仅能回看历史对话，还能直接在网页上启动新会话、发送消息、管理 Git、上传文件——几乎把终端里能做的事搬到了网页上。

通俗类比：如果说 claude-run 是"微信聊天记录导出查看器"，那 claude-code-viewer 就是"网页版微信"——不仅能看历史消息，还能直接在里面聊天、发文件、管理群组。

为什么需要它？

痛点	claude-code-viewer 怎么解决
终端界面不直观，操作不方便	提供图形化 Web 界面，所见即所得
想在手机/iPad 上用 Claude Code	浏览器访问，移动端优化过的 UI
想看 Claude 改了哪些代码	内置 Git Diff 查看器，代码改动一目了然
想上传图片让 Claude 分析	支持拖拽上传图片、PDF、文本文件
想定时让 Claude 执行任务	支持 cron 定时调度消息发送
不想记终端命令	搜索、恢复会话、切分支都是点击操作

安装

bash

# 全局安装（推荐）
npm install -g @kimuson/claude-code-viewer

# 或者不安装，直接运行
npx @kimuson/claude-code-viewer@latest --port 3400

使用方法

bash

# 启动（推荐指定端口）
claude-code-viewer --port 3400

运行后浏览器访问 http://localhost:3400。

命令行选项

选项	环境变量	作用	通俗解释
`-p, --port <端口>`	`PORT`	监听端口（默认 3000）	网页服务开在哪个端口
`-h, --hostname <主机>`	`HOSTNAME`	监听主机名（默认 localhost）	要从其他设备访问就改成 `0.0.0.0`
`-P, --password <密码>`	`CCV_PASSWORD`	设置访问密码	防止别人打开你的网页
`-e, --executable <路径>`	`CCV_CC_EXECUTABLE_PATH`	Claude Code 可执行文件路径	一般自动检测，不用设
`--claude-dir <路径>`	`CCV_GLOBAL_CLAUDE_DIR`	Claude 目录（默认 `~/.claude`）	一般不用改
`--terminal-disabled`	`CCV_TERMINAL_DISABLED`	禁用终端面板	不需要网页终端时用
`--terminal-shell <路径>`	`CCV_TERMINAL_SHELL`	终端使用的 shell	自动检测，一般不用设
`--api-only`	`CCV_API_ONLY`	仅启动 API，不启动网页界面	给开发者用的

界面功能

┌──────────────┬────────────────────────────┬──────────────┐
│  项目列表     │      对话区域               │  右侧面板     │
│              │                            │              │
│  📂 项目 A   │  👤 你: 帮我看看这个bug     │  📄 文件摘要  │
│  📂 项目 B   │  🤖 Claude: 我来分析...     │  🔧 工具调用  │
│    ├ 会话 1  │  🔧 [读取文件] (可展开)     │  📋 待办事项  │
│    ├ 会话 2  │  🤖 Claude: 找到问题了...   │  🔗 MCP 服务  │
│              │                            │  ℹ️ 系统信息  │
│  🔍 ⌘K 搜索  │  ─────── 输入区域 ────────  │              │
│              │  [输入消息...] [📎] [发送]   │              │
├──────────────┴────────────────────────────┴──────────────┤
│  终端面板（可展开/折叠）                                    │
│  $ _                                                     │
└──────────────────────────────────────────────────────────┘

核心功能详解

会话管理

功能	操作方式	说明
查看历史	左栏点击会话	按项目分组，按时间排序
搜索	`⌘K`（Mac）或 `Ctrl+K`	全文搜索，支持模糊匹配
启动新会话	点击"新建会话"按钮	相当于在终端运行 `claude`
恢复会话	点击历史会话的恢复按钮	相当于 `claude -r <会话ID>`
继续会话	直接在对话框输入	不中断，继续当前对话

文件与预览

功能	说明
文件上传	支持拖拽上传图片、PDF、文本文件，Claude 会自动分析
浏览器预览	右侧面板可以嵌入预览你的 Web 应用（开发前端时很方便）
文件工具检查器	查看 Claude 编辑过的文件摘要和工具调用列表

Git 操作

功能	说明
查看改动	内置 Git Diff 查看器，代码改动高亮显示
提交代码	直接从网页界面执行 `git commit`
推送代码	直接从网页界面执行 `git push`
切换分支	下拉选择本地分支，一键切换

高级功能

功能	说明
消息调度	支持 cron 表达式定时发送消息（如：每天凌晨 2 点让 Claude 跑测试）
终端面板	底部可展开的 WebSocket 终端，直接执行 shell 命令
待办事项	显示 Claude 用 `TodoWrite` 创建的待办列表
MCP 查看器	查看当前配置的 MCP 服务器
多语言	支持英语、日语、简体中文

远程使用（手机/iPad 访问）

要从其他设备访问，需要两步：

bash

# 1. 启动时监听所有网络接口 + 设置密码
claude-code-viewer --hostname 0.0.0.0 --port 3400 --password 你的密码

# 2. 在手机浏览器输入：http://电脑的局域网IP:3400
#    输入密码后即可使用

查看电脑局域网 IP：终端运行 ifconfig | grep "inet " | grep -v 127.0.0.1，通常是 192.168.x.x。

前提：手机和电脑必须在同一个 Wi-Fi 网络下。

Docker 部署（进阶）

如果你想把它部署在服务器上长期运行：

bash

# 克隆项目
git clone https://github.com/d-kimuson/claude-code-viewer.git
cd claude-code-viewer

# 构建并启动
docker compose up --build

或者手动构建：

bash

docker build -t claude-code-viewer .
docker run --rm -p 3400:3400 \
  -e PORT=3400 \
  -e CCV_PASSWORD=你的密码 \
  claude-code-viewer

用户设置

在网页界面右上角打开设置，可以调整：

设置项	默认值	说明
隐藏无用户消息的会话	开启	过滤掉系统自动产生的空会话
合并同名会话	关闭	开启后同标题只显示最新版本
速率限制自动恢复	关闭	遇到限速时自动排队重试
回车发送行为	Shift+Enter	可改为 Enter 直接发送
搜索快捷键	⌘K	可自定义
主题	跟随系统	深色/浅色/自动
语言	跟随系统	英语/日语/简体中文

常见问题

Q：claude-code-viewer 和 claude-run 有什么区别？

claude-run 是只读的历史查看器，claude-code-viewer 是可交互的完整客户端。详见下方对比表。

Q：支持 Windows 吗？

不支持。目前仅支持 macOS 和 Linux。

Q：需要什么版本的 Claude Code？

最低 v1.0.50。要使用工具批准功能（在网页上批准 Claude 的操作请求），需要 v1.0.82 或更高。

Q：不想用了怎么卸载？

bash

npm uninstall -g @kimuson/claude-code-viewer

claude-run vs claude-code-viewer 选择指南

一句话总结

claude-run：只想快速回看历史对话 → 用这个
claude-code-viewer：想要完整的 Web 客户端，远程操作、Git 管理、文件上传 → 用这个

功能对比

功能	claude-run	claude-code-viewer
查看历史对话	✅	✅
搜索会话	✅	✅（更强，支持模糊匹配）
按项目筛选	✅	✅
实时流式更新	✅	✅
恢复/继续对话	复制命令到终端	网页内直接操作
启动新会话	❌	✅
发送消息	❌	✅
上传文件	❌	✅（图片/PDF/文本）
浏览器预览	❌	✅
Git 操作	❌	✅（diff/commit/push/分支切换）
终端面板	❌	✅
定时任务	❌	✅（cron 调度）
待办事项查看	❌	✅
MCP 服务器查看	❌	✅
密码保护	❌	✅
多语言界面	❌	✅（中/英/日）
Docker 部署	❌	✅
移动端优化	基本响应式	专门优化过

使用场景推荐

你的需求	推荐	理由
偶尔翻翻历史对话	claude-run	启动快、零配置、够用
日常开发，习惯用终端	claude-run	不改变工作流，只是加个查看器
想在手机/iPad 远程操作	claude-code-viewer	完整 Web 客户端 + 移动端优化
团队共享查看	claude-code-viewer	支持密码保护 + 远程访问
需要 Git 可视化操作	claude-code-viewer	内置 diff/commit/push
想给 Claude 上传图片分析	claude-code-viewer	支持文件拖拽上传
服务器上长期运行	claude-code-viewer	支持 Docker 部署

可以同时用吗？

可以。两个工具读取的是同一份数据（~/.claude/ 目录），互不冲突。只要端口不同就能同时启动：

bash

# 终端 1：启动 claude-run（端口 12001）
claude-run

# 终端 2：启动 claude-code-viewer（端口 3400）
claude-code-viewer --port 3400

实际使用建议：日常用 claude-run 快速查看，需要远程操作或高级功能时再启动 claude-code-viewer。

本文档基于 Claude Code 官方文档整理，结合零代码基础产品经理的使用场景编写。如有疑问，可在 Claude Code 中输入 /help 查看官方帮助。

Claude Code 完全教程指南 ​

目录 ​

第一部分：Claude Code 核心模块 ​

1. CLAUDE.md — 给 AI 的工作手册 ​

是什么？ ​

三级层次 ​

高级功能 ​

注意事项 ​

2. Settings — AI 的权限和行为规则 ​

是什么？ ​

三个配置位置（优先级从高到低） ​

可配置的内容 ​

配置示例 ​

3. Plan Mode — 只看不动手模式 ​

是什么？ ​

怎么用？ ​

Claude 在 Plan Mode 下能做 / 不能做 ​

适用场景 ​

典型工作流 ​

4. Subagents — AI 的助手团队 ​

是什么？ ​

三种内置子代理 ​

自定义子代理（Agent） ​

控制方式 ​

5. MCP Servers — 给 AI 装插件 ​

是什么？ ​

安装命令 ​

三个作用域 ​

常用 MCP 服务 ​

管理命令 ​

6. Hooks — 自动化检查站 ​

是什么？ ​

全部 Hook 事件 ​

配置位置 ​

配置示例 ​

Hook 的四种类型 ​

7. Skills — 一键触发的工作流 ​

是什么？ ​

内置技能 ​

自定义技能 ​

Skills vs Agents 的区别 ​

8. Memory — AI 的笔记本 ​

是什么？ ​

两种记忆机制 ​

Auto Memory 的工作方式 ​

管理记忆 ​

9. Git 集成 — 代码版本管理 ​

基本操作 ​

Worktrees — 并行开发 ​

10. Task System — AI 的待办清单 ​

是什么？ ​

操作方式 ​

特点 ​

11. Context Management — 上下文管理 ​

是什么？ ​

上下文中包含的内容 ​

管理命令 ​

优化建议 ​

12. 权限模式 — 安全阀 ​

权限规则的通配符 ​

第二部分：命令类型详解 ​

类型一：内置斜杠命令（Slash Commands） ​

会话管理类 ​

配置查看类 ​

操作类 ​

类型二：技能命令（Skills） ​

与内置斜杠命令的区别 ​

已有的技能命令 ​

系统内置 ​

ECC 增强（已安装） ​

推荐创建的自定义技能 ​

类型三：自然语言命令 ​

使用示例 ​

@ 引用文件 ​

类型四：Bash 命令 ​

方式 1：! 前缀（你直接执行） ​

方式 2：自然语言委托 Claude 执行 ​

两种方式对比 ​

类型五：键盘快捷键 ​

模式切换 ​

Claude Code 完全教程指南

目录

第一部分：Claude Code 核心模块

1. CLAUDE.md — 给 AI 的工作手册

是什么？

三级层次

高级功能

注意事项

2. Settings — AI 的权限和行为规则

是什么？

三个配置位置（优先级从高到低）

可配置的内容

配置示例

3. Plan Mode — 只看不动手模式

是什么？

怎么用？

Claude 在 Plan Mode 下能做 / 不能做

适用场景

典型工作流

4. Subagents — AI 的助手团队

是什么？

三种内置子代理

自定义子代理（Agent）

控制方式

5. MCP Servers — 给 AI 装插件

是什么？

安装命令

三个作用域

常用 MCP 服务

管理命令

6. Hooks — 自动化检查站

是什么？

全部 Hook 事件

配置位置

配置示例

Hook 的四种类型

7. Skills — 一键触发的工作流

是什么？

内置技能

自定义技能

Skills vs Agents 的区别

8. Memory — AI 的笔记本

是什么？

两种记忆机制

Auto Memory 的工作方式

管理记忆

9. Git 集成 — 代码版本管理

基本操作

Worktrees — 并行开发

10. Task System — AI 的待办清单

是什么？

操作方式

特点

11. Context Management — 上下文管理

是什么？

上下文中包含的内容

管理命令

优化建议

12. 权限模式 — 安全阀

权限规则的通配符

第二部分：命令类型详解

类型一：内置斜杠命令（Slash Commands）

会话管理类

配置查看类

操作类

类型二：技能命令（Skills）

与内置斜杠命令的区别

已有的技能命令

系统内置

ECC 增强（已安装）

推荐创建的自定义技能

类型三：自然语言命令

使用示例

`@` 引用文件

类型四：Bash 命令

方式 1：`!` 前缀（你直接执行）

方式 2：自然语言委托 Claude 执行

两种方式对比

类型五：键盘快捷键

模式切换