Claude Code 缓存前缀匹配

02 — 地基概念

token 到底是什么

前面反复说"逐 token 匹配"。要真正理解缓存，先得知道 token 不是字符、也不完全是单词，而是模型读文字的最小单位。

模型不读字符，读 token

你输入一句话，模型不会一个字母一个字母地看。它先用一个叫 tokenizer（分词器）的部件，按一套固定的"词汇表"把文字切成一块块的碎片，每块就是一个 token，再把每个 token 换成一个数字编号。模型眼里的世界是一串数字，不是字符串。

一句话定义 token = 分词器按固定词汇表，把文字切出来的一个"子词片段"。常见的词往往是 1 个 token；生僻词、长词会被拆成好几个；中文一个汉字通常要 1 个甚至更多 token。

真实切分长这样

下面用色块表示 token 边界（每个方块 = 1 个 token，␣ 表示空格，空格通常并进它后面的词里）。注意：具体怎么切由分词器版本决定，这里是代表性示例，但"切成多块、空格归属、生僻词被拆碎"这些规律是确定的。

英文常见词 · "I love caching"

I ␣love ␣caching ≈ 3 个 token

生僻 / 长词会被拆碎 · "unbelievable"

unbelievable ≈ 4 个 token（一个词拆成 4 块）

中文更"费 token" · "帮我做登录功能"

帮我做登录功能 ≈ 7 个 token（汉字常常一字一块）

数字 / 代码 · "Tenant-Id: 000000"（缓存最容易栽在这种地方）

Tenant-Id: ␣000000 ≈ 5 个 token

官方经验值（用来估算，不是精确）

内容	大致换算
英文	≈ 4 个字符 = 1 token（≈ 0.75 个单词）
中文	一个汉字常 ≈ 1 个甚至更多 token，整体比英文更费
Opus 4.7 / 4.8	官方注明换了新分词器，同样文字可能多花最多 35% token（但单价从 $15 降到 $5，整体更便宜）

为什么这和"前缀逐字节相同"是同一件事

缓存比的就是这一串 token 序列。看一个你项目里真会发生的场景——把请求头里的 Tenant-Id: 000000 改成 000001：

改之前
        …前面几千个 token 完全一样…
        ␣000000
        …后面所有 token…
      
改之后
        …前面几千个 token 完全一样…
        ␣000001
        …后面所有 token 连带重算…
      
结果
        前面那段 命中 ✅；变了的那个 token 起 断开 ❌，到结尾全部重算。
      

你只改了 1 个字符，但它落在 000000 这个 token 上，这个 token 变成了 000001 这个不同的 token → 前缀在这里断开 → 从这个 token 到结尾全部失效。这就是"遇到第一个不一样的 token，从那里到结尾全部重新计算"的字面含义。

三个会"咬人"的细节 ① 空格也算进 token：` love` 带前导空格，多删一个空格就可能换一个 token。
② 同样的字，位置/上下文不同可能切法不同：分词器会把常见组合合并成一个 token。
③ 改 1 个字符 ≠ 只影响 1 个 token：有时会让那一小段整体重新切分。但无论如何，从第一个变化的 token 起，后面全断。

想看你自己文字的精确 token 数？

本页所有 token 数是"代表性估算"。精确值要用 Anthropic 官方的 token 计数接口 POST /v1/messages/count_tokens，或 Claude Console 里的 tokenizer 工具。
在 Claude Code 里，你不用自己数——第 10 节那些 cache_read_input_tokens 等字段,就是服务端按真实分词算好回传的 token 数。

回到主线：token 是模型读文字的最小单位；缓存逐个 token 比对前缀，任何一个 token 不同（哪怕只因改了一个字符），从那里往后就全断。

你以为	实际
第二轮说一样的话 = 完全命中	❌ 永远不是"完全"——末尾总挂着一段新的用户输入
重复的话被认出来、所以免费	❌ 那句话本身不命中；免费的是它前面没变的前缀
真正花钱的是哪部分	✅ 只有末尾那十几个新 token，几乎可忽略；几万 token 的前缀全命中

缓存操作	倍率	含义
5 分钟写缓存 cache write	1.25×	第一次把这段内容存进缓存，比正常输入贵 25%
1 小时写缓存	2×	存成存活 1 小时的缓存（需开 1h 选项），贵一倍
缓存命中 / 读 cache read	0.1×	命中时只花正常输入价的 10%

模型	基准输入	5m 写缓存	缓存命中	输出
Opus 4.8（本会话）	$5 /MTok	$6.25	$0.50	$25
Opus 4.1（旧）	$15	$18.75	$1.50	$75
Sonnet 4.6	$3	$3.75	$0.30	$15
Haiku 4.5	$1	$1.25	$0.10	$5

你改了什么	失效范围
工具定义（tools，最靠前）	tools + system + messages 全部失效 ❌
system / CLAUDE.md	system + messages 失效 ◐
对话消息（messages，最靠后）	只有 messages 失效 ✅

#	时刻	gap	read 命中	write 写入	new 全价	out	发生了什么
1	08:06:33	—	18,518	4,966	16,034	1,613	开局：你的长消息+上下文，命中已有的 system/工具缓存
2	08:10:40	247s	23,484	17,666	2	535	间隔 247s < 300s → 仍命中 ✅
3	08:10:57	17s	41,150	1,977	2	12,682	read 持续涨：前缀在变长
4	08:13:30	153s	43,127	12,765	2	631
5	08:16:52	202s	55,892	693	2	1,386
6–9	08:18	4–85s	56k→60k	~1.1k	2	—	连续工具调用，间隔几秒，缓存全热
13–14	08:21	97/42s	66,819	~580	2	—	read 稳在 66,819 = 完整命中
15	08:26:18	269s	66,819	695	2	1,157	间隔 269s 仍 < 300s → read 没掉，照样命中 ✅
16	08:28:05	106s	18,611	50,476	2	553	read 骤降、write 暴涨：靠前位置内容被改写，只有前 18,611 仍命中，5 万 token 重新写入缓存 ❌
17–19	08:28	6–27s	69k→73k	1k–4.4k	~1–2.8k	刚写入的大块立刻又被命中，read 回升

方式	怎么做
命令行 `/cost`	在 Claude Code 里输入，看本次会话累计 token 和花费（含缓存读写）
原始会话记录	会话以 `.jsonl` 存在 `~/.claude/projects/<项目>/`，每条 assistant 消息都带 usage。用 jq 即可逐轮统计

13 — 委派与并行

subagent / Agent / 团队 / 后台 / Workflow 全解

这几个词最容易混。本节严格按官方文档（code.claude.com）讲清：它们是 Claude Code 里"把活分出去、并行干"的几种不同机制，不是一回事。

先更正一个常见误解 "团队（agent teams）"是 Claude Code 真实存在的功能（实验性，需开开关），不是口语比喻。下面逐个讲，全部以官方为准。

一张总表（官方"并行运行 agent"的五种方式）

机制	是什么	上下文	彼此通信	最适合	启用方式
subagent 子智能体	单个会话内派出的专职助手	各自独立窗口	只回报给主 agent，彼此不通信	副任务返回摘要	默认就有
agent teams 代理团队	多个完整会话：1 队长 + 多队友	各自独立窗口	队友互相直接发消息	要讨论/协作的复杂活	实验开关
background agents 后台代理	后台跑的多个完整会话，一屏管理	各自独立会话	不互相通信	多个互不依赖的任务异步跑	`claude agents`
Workflow 动态工作流	用 JS 脚本确定性地编排一群 subagent	脚本调度	脚本里传数据	大规模/可复现的批处理	Workflow 工具
worktree 多会话	你自己开多个 Claude Code 会话	各自独立	不自动协调	手动并行	git worktree

来源：code.claude.com 的 sub-agents / agent-teams / agent-view 三页。下面把前四种逐个拆开。

① subagent（子智能体）+ Agent 工具

是什么：专职 AI 助手，运行在自己独立的上下文窗口里，有自己的系统提示、限定的工具、独立权限。干完只把摘要回报给主对话——好处是把刷屏的中间过程（跑测试/读日志/查文档）挡在主对话外面。
怎么启动：通过 Agent 工具（官方 v2.1.63 起由 Task 改名为 Agent，旧名仍兼容）。所以 "Agent" 是启动动作/工具，"subagent" 是被启动的实体——两面，不是两样东西。
怎么委派：主 agent 按每个 subagent 的 description 自动决定派谁；也可自然语言点名、@-提及锁定、或 --agent 让整个会话用它。
内置的：Explore（Haiku、只读、查代码）、Plan（只读、plan 模式做调研）、general-purpose（全工具），外加 statusline-setup、claude-code-guide。
怎么自定义：在 .claude/agents/*.md（项目）或 ~/.claude/agents/（用户）写 Markdown + YAML frontmatter，必填 name、description，可选 tools / model / permissionMode / skills / memory / isolation 等。也可用 /agents 命令向导创建。
关键限制（官方）：subagent 不能再生 subagent（不能嵌套）；每次启动都是全新隔离上下文，看不到主对话历史（fork 模式例外）。

何时用：副任务输出很啰嗦、想限制工具权限、活儿自包含能返回摘要。需要频繁来回/共享大量上下文/快速小改 → 留在主对话。

② agent teams（代理团队）

是什么：多个完整的 Claude Code 实例协作。一个 队长(lead) 负责建队、派活、汇总；多个 队友(teammate) 各自独立上下文、互相直接发消息、靠共享任务列表自己认领任务。
和 subagent 的本质区别（官方表）：subagent 只回报给主 agent、彼此不通信；团队队友互相通信、共享任务列表、自主认领。一句话——需要队友之间讨论/质疑/协调，才上团队。
怎么启用：实验性，默认关闭。设环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（需 v2.1.32+），然后用自然语言让 Claude "建一个团队…"。
架构：队长 / 队友 / 共享任务列表（pending→in progress→completed，支持依赖与文件锁防抢） / 邮箱（mailbox，SendMessage 通信）。存在 ~/.claude/teams/ 与 ~/.claude/tasks/。
限制：一次只能管一个团队；不能嵌套（队友不能再建队）；队长固定不可转让；token 随队友数线性增长，比单会话贵得多。官方建议 3–5 个队友、每人 5–6 个任务。
何时用：并行评审（安全/性能/测试各一人）、竞争假设并行调试（互相证伪）、新模块各管一块、跨前后端+测试协调。

③ background agents（后台代理 / agent view）

是什么：claude agents 打开一块屏幕管理所有后台会话。每个都是完整的 Claude Code 会话，由一个 supervisor 进程托管，不依赖终端——关掉窗口它还在跑。
和团队的区别：这是"很多互不通信的独立会话并行"（派一个修 bug、一个评审 PR、一个查 flaky 测试，回头看结果）；团队是"会话互相通信协作"。subagent/队友不会作为独立行显示在这里。
怎么用：在输入框敲任务回车 = 起一个后台会话；Space 偷看、回复，Enter 进入完整会话；也可 claude --bg "任务" 从 shell 直接派。研究预览阶段（需 v2.1.139+）。
注意：每个后台会话独立消耗你的用量配额，并行 10 个 ≈ 10 倍速度烧额度。

④ Workflow（动态工作流）

是什么：用一段 JS 脚本确定性地编排一群 subagent——循环、并行、流水线、分支全写死。后台跑，可断点续跑。官方文档里以 "dynamic workflow"（后台活计的一种）出现。
和团队的区别：Workflow 是代码驱动、可复现（同脚本同输入→结果一致）；团队是模型驱动的临场协作。要"结构写死、能重放"选 Workflow；要"队友自由讨论"选团队。
何时用：大规模、结构化、要复现的批处理——200 个文件逐个迁移并验证、多维度评审后交叉核验。

怎么选（一句话决策）

你的情况	用
副任务会刷屏、只要个摘要	subagent
几个工人要互相讨论/质疑再汇总	agent teams
几个互不相关的任务想异步跑、回头收	background agents
大批量、要可复现的结构化流程	Workflow
需要频繁来回 / 共享大量上下文 / 快速小改	就留在主对话

来源：code.claude.com — sub-agents、agent-teams（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS、lead/teammate/任务列表/mailbox）、agent-view（claude agents、supervisor）。Task→Agent 改名见 sub-agents 页 v2.1.63 说明。

顺带：Workflow 续跑和 token 缓存是同一个道理

这也是把这节放进缓存教程的原因。Workflow 的断点续跑用的和 token 前缀缓存完全相同的思路——"最长不变前缀"：

恢复时，从第一个 agent() 调用开始，逐个比对 它的 prompt 和参数。
连续一致的部分 → 直接返回缓存结果，瞬间跳过。
碰到第一个被改动的 agent → 它以及它之后的所有 agent 全部重跑。
脚本 + 参数完全没变 = 100% 命中；改了中间一步 = 那步往后全部重算。

和 token 前缀匹配一模一样的形状：从头连续匹配，第一个变动点之后一律重做。token 缓存比的是 token 序列，Workflow 续跑比的是 agent() 调用序列——记住这一个"最长不变前缀"模型，两处都通。

操作	结果	为什么 / 真实依据
继续追问（不改前文）	大段命中 ✅	开头逐字未变；你本会话 new≈2、read 一路涨就是这个
改工具定义（tools）	tools+system+messages 全废 ❌	层级最顶层，级联失效（官方）
改 CLAUDE.md / system	system+messages 失效 ❌	你本会话 #16 就是靠前内容变动，5 万 token 被重写
空闲 > 5 分钟再请求	前缀过期 ❌	TTL 到期回收，需重新建立
空闲 < 5 分钟（或持续命中）	仍命中 ✅	每次命中免费刷新 5 分钟；你 #2(247s)/#15(269s) 都还命中
只改最后一条消息	几乎无损 ◐	messages 在最底层，只失效 messages
内容不足 4096 token（Opus 4.8）	根本不缓存 ❌	低于最小长度，打标也无效、不报错（官方）
换模型 / 跨组织 / 跨工作区	不命中 ❌	缓存按组织+工作区隔离，前缀绑定具体内容

模块 · Memory（CLAUDE.md / 记忆）

Memory（CLAUDE.md / 记忆）

Claude Code 的两套跨会话记忆机制：你手写的 CLAUDE.md 指令文件，和 Claude 自己积累的 auto memory 笔记，二者都在每次会话开始时加载进上下文。

是什么

每次 Claude Code 会话都从一个全新的 context window 开始，靠两套机制把知识带过会话边界：CLAUDE.md files（你写的持久化指令/规则）与 Auto memory（Claude 根据你的纠正和偏好自己写的笔记）。两者都在每次对话开始时加载进上下文。注意：它们都被当作 context（上下文），不是强制配置（not enforced configuration）——Claude 会尽力遵守但不保证严格合规；要无条件拦截某个动作必须用 PreToolUse hook。指令越具体、越简洁，Claude 遵守得越一致。

怎么工作

CLAUDE.md / CLAUDE.local.md 的加载靠从当前工作目录（cwd）向上 walk up 目录树：检查每一级目录里的 CLAUDE.md 和 CLAUDE.local.md。在 foo/bar/ 启动会加载 foo/bar/CLAUDE.md、foo/CLAUDE.md 等。
所有发现的文件是 concatenated（拼接）进上下文，不是相互覆盖。跨目录树顺序是从文件系统 root 往下到 cwd——所以 foo/CLAUDE.md 排在 foo/bar/CLAUDE.md 之前，离启动位置越近的指令越靠后被读到（最后读）。
同一级目录内，CLAUDE.local.md 排在 CLAUDE.md 之后追加，所以个人笔记是该层级里最后被读的。
整体 load order 从广到窄：Managed policy → User instructions → Project instructions（→ 同级 local）。广 scope 的先进上下文，project 指令出现在 user 指令之后。
cwd 之上目录层级里的 CLAUDE.md/CLAUDE.local.md 在启动时全量加载；子目录（subdirectories）里的则不在启动时加载，而是 Claude 读取那些子目录里的文件时按需（on demand）加入上下文。
@path import 语法：CLAUDE.md 可用 @path/to/import 引入其他文件，被引文件在启动时展开并随引用它的 CLAUDE.md 一起进上下文；支持相对和绝对路径，相对路径相对于含 import 的文件（不是 cwd）；可递归 import，最大深度 4 hops。
block-level HTML 注释  在注入上下文前会被 stripped（不占 token）；但代码块内的注释保留；用 Read 工具直接打开文件时注释仍可见。
AGENTS.md：Claude Code 只读 CLAUDE.md，不读 AGENTS.md。可在 CLAUDE.md 里用 @AGENTS.md 导入，或建 symlink。
Auto memory：每个项目有独立目录 ~/.claude/projects/<project>/memory/，<project> 由 git 仓库推导，所以同一 repo 的所有 worktree 和子目录共享同一个 auto memory 目录；不在 git repo 内则用 project root。
Auto memory 是 machine-local，不跨机器或云环境共享。MEMORY.md 作为索引（index），Claude 会话中读写该目录，把详细笔记移到独立 topic 文件保持 MEMORY.md 精简。
MEMORY.md 只加载前 200 行或前 25KB（先到为准）进每次会话；超出部分不在启动时加载；topic 文件（如 debugging.md）启动时不加载，Claude 按需用标准文件工具读取。
compaction 行为：项目根的 CLAUDE.md 在 /compact 后会从磁盘 re-read 并 re-inject；子目录里的 nested CLAUDE.md 不自动 re-inject，要等 Claude 下次读该子目录文件时才 reload。

怎么配置

CLAUDE.md 位置（按 load order 从广到窄）：Managed policy — macOS /Library/Application Support/ClaudeCode/CLAUDE.md、Linux/WSL /etc/claude-code/CLAUDE.md、Windows C:\Program Files\ClaudeCode\CLAUDE.md；User ~/.claude/CLAUDE.md；Project ./CLAUDE.md 或 ./.claude/CLAUDE.md；Local ./CLAUDE.local.md（加进 .gitignore）。
导入语法：See @README ... and @package.json ...、- git workflow @docs/git-instructions.md、跨 worktree 用 - @~/.claude/my-project-instructions.md。
导入 AGENTS.md：CLAUDE.md 顶部写 @AGENTS.md，或 ln -s AGENTS.md CLAUDE.md（Windows 用 import 因 symlink 需管理员/开发者模式）。
规则目录 .claude/rules/*.md：每文件一个主题（如 testing.md），递归发现；可加 YAML frontmatter 限定路径：
---
paths:
  - "src/api/**/*.ts"
  - "src/**/*.{ts,tsx}"
---
无 paths 的 rule 无条件加载，优先级同 .claude/CLAUDE.md。用户级 ~/.claude/rules/，加载早于 project rules（project 优先级更高）。
命令：/init 生成起始 CLAUDE.md（已存在则给改进建议不覆盖）；环境变量 CLAUDE_CODE_NEW_INIT=1 启用交互式多阶段流程。/memory 列出已加载的 CLAUDE.md/CLAUDE.local.md/rules，切换 auto memory 开关，打开 auto memory 文件夹。
Auto memory 配置：autoMemoryEnabled（项目设置，默认 on）、环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1、autoMemoryDirectory（仅 user settings ~/.claude/settings.json，须绝对路径或 ~/ 开头）。
托管：managed-settings.json 里用 claudeMd 键直接放内容（如 {"claudeMd": "Always run make lint before committing.\nNever push directly to main."}）；claudeMdExcludes（glob 数组）排除无关 CLAUDE.md，放 .claude/settings.local.json。
额外目录：CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config。

什么时候用

用 CLAUDE.md：写下你每次会话都要 Claude 记住的事实——build/test 命令、约定、项目布局、'always do X' 规则。触发场景：Claude 第二次犯同样错误 / code review 抓到 Claude 本该知道的东西 / 你又把上次的纠正打进 chat / 新同事需要同样的上下文才能上手。
用 path-scoped rules（.claude/rules/ 带 paths）：指令只在特定文件类型/子目录相关时才加载，省 context。
用 skill 而不是 CLAUDE.md：如果是多步流程，或只对代码库某一部分有意义的指令。
用 auto memory：让 Claude 从你的纠正里自动学习，无需手动写（如让它记 'always use pnpm, not npm'）。
别用 CLAUDE.md 做强制拦截：要无条件拦某动作/必须在某时机执行（如每次 commit 前）用 PreToolUse / hook；要 system prompt 级别用 --append-system-prompt。
别把个人偏好放进 project CLAUDE.md（会随版本控制共享）——放 CLAUDE.local.md 或 ~/.claude/。

限制 / 坑

CLAUDE.md 是 context 不是 enforced configuration，作为 system prompt 之后的 user message 投递，不保证严格遵守，尤其指令模糊或冲突时；冲突时 Claude 可能任意挑一个。
单个 CLAUDE.md 建议 target under 200 lines，超过更耗 context 且降低 adherence。
@path import 用了也不省 context——被引文件仍在启动时全量加载进上下文，只是利于组织。
@path import 最大递归深度 4 hops。
首次遇到 external imports 会弹审批对话框列出文件；若拒绝，imports 保持禁用且对话框不再出现。
MEMORY.md 仅加载前 200 行或前 25KB（先到为准），超出不在启动时加载；此限制只针对 MEMORY.md，CLAUDE.md 无论多长都全量加载。
auto memory 是 machine-local，不跨机器/云环境共享。
--add-dir 的目录默认不加载 CLAUDE.md，需 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1。
autoMemoryDirectory 不接受 project/local settings（防止 clone 的仓库把 auto memory 写到敏感位置），只接受 policy/user settings 和 --settings flag。
Managed policy CLAUDE.md 不能被 claudeMdExcludes 排除，确保组织级指令始终生效。
/compact 后子目录 nested CLAUDE.md 不自动 re-inject，仅项目根 CLAUDE.md 会从磁盘重读重注入；仅在对话里给过的指令 compact 后会丢。
在 settings 里设 claudeMd 仅 managed/policy settings 生效，user/project/local 设无效。
Windows 创建 symlink 需 Administrator 或 Developer Mode，故 import AGENTS.md 时用 @AGENTS.md 而非 symlink。

▸ 硬事实速查（27 条精确事实）

CLAUDE.md 四个 scope 与路径：Managed policy（macOS /Library/Application Support/ClaudeCode/CLAUDE.md、Linux/WSL /etc/claude-code/CLAUDE.md、Windows C:\Program Files\ClaudeCode\CLAUDE.md）、User ~/.claude/CLAUDE.md、Project ./CLAUDE.md 或 ./.claude/CLAUDE.md、Local ./CLAUDE.local.md。
Load order 从广到窄：Managed policy → User → Project → Local；跨目录树从 root 往下到 cwd，离启动位置近的后读；同级 CLAUDE.local.md 追加在 CLAUDE.md 之后。
cwd 之上层级 CLAUDE.md/CLAUDE.local.md 启动时全量加载；子目录里的按需加载（Claude 读该目录文件时）。
import 语法 @path/to/import，相对路径相对于含 import 的文件而非 cwd，支持绝对/相对路径，可递归，maximum depth of four hops（最大 4 hops）。
block-level HTML 注释  注入前被 stripped 不占 token；代码块内注释保留；Read 工具打开时注释可见。
Claude Code 只读 CLAUDE.md 不读 AGENTS.md；桥接方式：CLAUDE.md 写 @AGENTS.md 或 ln -s AGENTS.md CLAUDE.md。
/init 生成起始 CLAUDE.md；已存在则建议改进不覆盖；会读取 AGENTS.md、.cursorrules、.windsurfrules 并整合。
CLAUDE_CODE_NEW_INIT=1 启用交互式多阶段 /init（可设置 CLAUDE.md/skills/hooks）。
.claude/rules/ 放主题 md 文件，递归发现；无 paths frontmatter 的 rule 启动加载，优先级同 .claude/CLAUDE.md；带 paths YAML frontmatter 做 path-scoped，只在读匹配文件时触发。
glob 示例：**/*.ts（任意目录 TS）、src/**/*（src 下全部）、*.md（项目根 markdown）、src/components/*.tsx；支持 brace expansion 如 src/**/*.{ts,tsx}。
用户级 rules ~/.claude/rules/，加载早于 project rules，project rules 优先级更高。
.claude/rules/ 支持 symlink（解析并正常加载，循环 symlink 会被检测处理）。
Auto memory 需 Claude Code v2.1.59 或更高（claude --version 查）。
Auto memory 默认 on；关闭：/memory 切换、或项目设置 {"autoMemoryEnabled": false}、或环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。
Auto memory 存储目录 ~/.claude/projects/<project>/memory/，<project> 由 git repo 推导，同 repo 所有 worktree/子目录共享一个目录；非 git repo 用 project root。
Auto memory 目录含 MEMORY.md（索引，loaded into every session）+ 可选 topic 文件（如 debugging.md / api-conventions.md，按需读取，启动不加载）。
autoMemoryDirectory 只能在 user settings ~/.claude/settings.json 设，须绝对路径或 ~/ 开头；不接受 project/local settings，接受 policy/user 和 --settings。
MEMORY.md 启动加载阈值：first 200 lines 或 first 25KB，whichever comes first；只对 MEMORY.md 生效，CLAUDE.md 全量加载。
界面提示 'Writing memory' / 'Recalled memory' 表示 Claude 正在写/读 ~/.claude/projects/<project>/memory/。
managed-settings.json 的 claudeMd 键可直接内嵌 CLAUDE.md 内容，precedence 同 managed CLAUDE.md（先于 user/project 加载），仅 managed/policy settings 生效。
claudeMdExcludes（glob 数组，匹配绝对路径）排除 CLAUDE.md，可配在任意 settings 层，数组跨层合并；managed policy CLAUDE.md 不可被排除。
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir <dir> 加载额外目录的 CLAUDE.md/.claude/CLAUDE.md/.claude/rules/*.md/CLAUDE.local.md；若 --setting-sources 排除 local 则跳过 CLAUDE.local.md。
/memory 命令：列出已加载 CLAUDE.md/CLAUDE.local.md/rules、切换 auto memory、提供打开 auto memory 文件夹链接、选文件可在编辑器打开。
CLAUDE.md 作为 system prompt 之后的 user message 投递，不是 system prompt 一部分；要 system prompt 级用 --append-system-prompt。
/compact 后项目根 CLAUDE.md 从磁盘 re-read 并 re-inject；nested 子目录 CLAUDE.md 不自动 re-inject。
调试工具：InstructionsLoaded hook 可记录哪些指令文件被加载、何时、为何。
Subagents 可维护自己的 auto memory（见 subagent configuration / enable persistent memory）。

官方出处：https://code.claude.com/docs/en/memory

模块 · Skills（技能）

Skills（技能）

Skills 是用 SKILL.md 文件给 Claude 扩展能力的方式：写一份指令，Claude 在相关时自动调用、或你用 /skill-name 直接触发，且正文只在用到时才加载，几乎不占常驻 context。

是什么

Skills（技能）是扩展 Claude Code 能力的机制。你创建一个 SKILL.md 文件写入指令，Claude 就把它加入自己的工具箱：当对话相关时 Claude 自动调用，或你输入 /skill-name 直接调用。和 CLAUDE.md 不同，技能的正文（body）只在被调用时才加载，因此再长的参考资料在没用到前几乎不消耗 context。Claude Code 的 skills 遵循 Agent Skills 开放标准（agentskills.io），可跨多个 AI 工具使用；Claude Code 在标准之上扩展了 invocation control（调用控制）、subagent execution（子代理执行）、dynamic context injection（动态上下文注入）等特性。官方明确：自定义命令（custom commands）已合并进 skills——.claude/commands/deploy.md 与 .claude/skills/deploy/SKILL.md 都会生成 /deploy 且行为一致，旧的 .claude/commands/ 文件继续可用。

怎么工作

每个技能是一个目录，以 SKILL.md 为入口（entrypoint），SKILL.md 必需，其他文件（template.md / examples/ / scripts/）可选。
SKILL.md 由两部分组成：--- 之间的 YAML frontmatter（告诉 Claude 何时用）+ 后面的 markdown 正文（被调用时 Claude 执行的指令）。
渐进式披露（progressive disclosure）：常规会话中，技能的 description 始终加载进 context 让 Claude 知道有哪些技能可用，但完整正文只在被调用时才加载。
调用控制由两个 frontmatter 字段决定：默认你和 Claude 都能调用；disable-model-invocation: true 只允许你手动调用（description 不进 context）；user-invocable: false 只允许 Claude 调用（从 / 菜单隐藏）。
动态上下文注入（dynamic context injection）：正文里的 ` !command ` 在发送给 Claude 之前先由 Claude Code 执行 shell 命令，用输出替换占位符，所以 Claude 收到的是真实数据而非命令本身。这是预处理，Claude 看不到命令执行过程。
替换只对原文件扫描一次，命令输出作为纯文本插入、不再被二次扫描；inline 形式仅当 ! 位于行首或紧跟空白时才识别。
子代理执行：frontmatter 加 context: fork 时，技能正文成为驱动子代理的 prompt，在隔离的 context 里运行，看不到你的对话历史；用 agent 字段指定子代理类型。
技能内容生命周期：被调用时，渲染后的 SKILL.md 作为单条 message 进入对话并在整个 session 保留；Claude Code 不会在后续回合重新读取技能文件，所以应写成贯穿任务的常驻指令而非一次性步骤。
命令名来源：~/.claude/skills/ 或 .claude/skills/ 下取目录名；.claude/commands/ 下取去扩展名的文件名；plugin 的 skills/ 子目录取目录名并加 plugin 命名空间；plugin 根目录的 SKILL.md 取 frontmatter name（无则回退到 plugin 目录名）。
同名覆盖优先级：enterprise > personal > project；skill 与同名 command 冲突时 skill 优先；plugin 技能用 plugin-name:skill-name 命名空间，不会与其他层级冲突。

怎么配置

技能存放位置（决定谁能用）：Personal ~/.claude/skills/<skill-name>/SKILL.md（所有项目可用）；Project .claude/skills/<skill-name>/SKILL.md（仅本项目）；Plugin <plugin>/skills/<skill-name>/SKILL.md；Enterprise 通过 managed settings 部署。

最小 SKILL.md：
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed...
---

## Current changes
!git diff HEAD

## Instructions
Summarize the changes above in two or three bullet points...

创建示例：mkdir -p ~/.claude/skills/summarize-changes，写入 SKILL.md，然后用 /summarize-changes 或自然语言触发。

常用 frontmatter 字段：name、description、when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、allowed-tools、disallowed-tools、model、effort、context、agent、hooks、paths、shell。所有字段都可选，仅 description 推荐。

字符串替换：$ARGUMENTS、$ARGUMENTS[N]、$N、$name、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT}、${CLAUDE_SKILL_DIR}。

子代理执行：frontmatter 加 context: fork + agent: Explore（或 Plan / general-purpose / 自定义）。

多行命令注入用  !  围栏代码块。

settings 相关：skillOverrides（控制可见性，写入 .claude/settings.local.json）、disableSkillShellExecution、skillListingBudgetFraction、maxSkillDescriptionChars。权限：在 /permissions 用 Skill（禁全部）/ Skill(commit)（精确）/ Skill(review-pr *)（前缀）。

什么时候用

何时建技能：当你反复把同一套指令/清单/多步流程粘进对话；或 CLAUDE.md 里某段已经从『事实』膨胀成了『流程』。
Reference content（参考类，如 API 约定、风格指南、领域知识）：inline 运行，Claude 在当前工作旁边参考使用。
Task content（任务类，如部署、提交、代码生成）：常希望用 /skill-name 直接调用；加 disable-model-invocation: true 防止 Claude 自动触发（尤其是有副作用的 /commit、/deploy、/send-slack-message）。
背景知识但不该作为命令被用户直接触发：用 user-invocable: false 从 / 菜单隐藏（如 legacy-system-context）。
需要隔离、独立 context 的研究/分析任务：用 context: fork——但仅适合含明确指令的技能，纯指南类（无任务）forked 后子代理拿不到可执行 prompt，会空跑无输出。
正文要保持简洁：技能一旦加载就在整个 session 占 token，按 CLAUDE.md 的简洁标准写，说『做什么』而非『怎么做/为什么』。

限制 / 坑

description + when_to_use 合并文本在技能列表中被截断到 1,536 字符（上限可用 maxSkillDescriptionChars 配置）；要把关键用例放最前面。
技能列表预算默认按模型 context window 的 1%（skillListingBudgetFraction，例 0.02=2%）；溢出时优先丢弃最少用技能的 description（仅 description 被砍，技能名始终保留），可能砍掉 Claude 匹配所需的关键词。用 /doctor 看预算是否溢出。
自动压缩（auto-compaction）后：每个技能最近一次调用被重新附加，仅保留前 5,000 tokens；所有重新附加的技能共享 25,000 tokens 预算，从最近调用的开始填，调用过多时较早的技能可能被整个丢弃；必要时压缩后重新调用以恢复完整内容。
Claude Code 不会在后续回合重新读取技能文件——写一次性步骤会失效，应写常驻指令。
context: fork 的 Explore/Plan agent 会跳过 CLAUDE.md 和 git status。
allowed-tools 只是免审批授权、不限制可用工具；要封禁工具需在 permission settings 加 deny 规则。项目 .claude/skills/ 的 allowed-tools 需先接受 workspace trust 对话框才生效——信任仓库前要先审查项目技能，因为技能能给自己授很宽的工具权限。
--add-dir / /add-dir 会加载其中的 .claude/skills/，但 permissions.additionalDirectories 设置只给文件访问、不加载技能；subagents、commands、output styles 也不从附加目录加载。
会话启动后新建一个之前不存在的顶层 skills 目录，需要重启 Claude Code 才能被监听（已存在目录内的增删改可在当前会话即时生效）。
user-invocable: false 只控制 / 菜单可见性，不阻止 Skill tool 程序化调用；要彻底屏蔽用 disable-model-invocation: true。
shell: powershell 需要环境变量 CLAUDE_CODE_USE_POWERSHELL_TOOL=1。
disableSkillShellExecution: true 会把每条 shell 命令替换为 [shell command execution disabled by policy]；bundled 与 managed 技能不受影响。
部分内置命令（/init、/review、/security-review）可通过 Skill tool 调用，但 /compact 等不行。

▸ 硬事实速查（28 条精确事实）

技能目录入口文件必须叫 SKILL.md，其他文件（template.md、examples/、scripts/）可选。
Personal 路径：~/.claude/skills/<skill-name>/SKILL.md（所有项目）。
Project 路径：.claude/skills/<skill-name>/SKILL.md（仅本项目，提交 VCS 即共享）。
Plugin 路径：<plugin>/skills/<skill-name>/SKILL.md，命令名加命名空间如 /my-plugin:review。
同名覆盖优先级：enterprise > personal > project；skill 与同名 command 冲突 skill 优先。
frontmatter 字段全集：name、description、when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、allowed-tools、disallowed-tools、model、effort、context、agent、hooks、paths、shell。所有字段可选，仅 description 推荐。
description 缺省时取 markdown 正文第一段；description+when_to_use 列表中合并截断在 1,536 字符。
disable-model-invocation 默认 false；user-invocable 默认 true。
effort 选项：low、medium、high、xhigh、max（实际可用取决于模型）；${CLAUDE_EFFORT} 还可能返回 ultra（ultracode 的存储值）。
context: fork 在 forked 子代理 context 运行；agent 缺省用 general-purpose，可选 Explore、Plan、general-purpose 或 .claude/agents/ 自定义。
shell 接受 bash（默认）或 powershell；powershell 需 CLAUDE_CODE_USE_POWERSHELL_TOOL=1。
paths 用 glob 限制激活时机，格式同 path-specific rules。
字符串替换变量：$ARGUMENTS、$ARGUMENTS[N]（0-based）、$N（如 $0、$1）、$name（按 arguments 列表位置映射）、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT}、${CLAUDE_SKILL_DIR}。
调用带参数但正文无 $ARGUMENTS 时，Claude Code 在正文末尾追加 ARGUMENTS: <your input>。
索引参数用 shell 风格引号：/my-skill "hello world" second 使 $0=hello world、$1=second。
动态注入 inline 形式 ` !command ：仅当 ! 在行首或紧跟空白时识别；KEY=!cmd 这类被当字面文本不执行。多行用 ``! 围栏块。
替换只对原文件扫描一次，命令输出不被二次扫描。
建议 SKILL.md 控制在 500 行以内，详细参考资料拆到单独文件。
自动压缩后每个技能保留前 5,000 tokens，重新附加技能共享 25,000 tokens 预算。
技能列表预算默认模型 context window 的 1%；用 skillListingBudgetFraction（如 0.02=2%）或 SLASH_COMMAND_TOOL_CHAR_BUDGET（固定字符数）调整；用 maxSkillDescriptionChars 配置 1,536 字符上限。
/run、/verify、/run-skill-generator 需 Claude Code v2.1.145 或更高；/run-skill-generator 把启动配方提交为 .claude/skills/run-<name>/。
skillOverrides 四种值：on（名+描述，列出且在/菜单）、name-only（仅名）、user-invocable-only（对 Claude 隐藏但在/菜单）、off（全隐藏）；缺省视为 on；写入 .claude/settings.local.json；plugin 技能不受 skillOverrides 影响（用 /plugin 管理）。
权限语法：Skill(name) 精确匹配，Skill(name *) 前缀匹配；deny 规则加 Skill 可禁全部。
Bundled skills 示例：/code-review、/batch、/debug、/loop、/claude-api，每个 session 都可用，在 commands reference 中标记为 Skill。
Live change detection：监听 ~/.claude/skills/、项目 .claude/skills/、--add-dir 目录内 .claude/skills/ 的增删改，当前会话即时生效；新建顶层目录需重启。
monorepo：项目技能从启动目录到仓库根逐级父目录加载，工作于子目录文件时按需发现嵌套 .claude/skills/（如 packages/frontend/.claude/skills/）。
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 用于加载 --add-dir 目录的 CLAUDE.md（默认不加载）。
正文含 ultrathink 可请求更深推理；用 /doctor 诊断技能列表预算溢出。

官方出处：https://code.claude.com/docs/en/skills

模块 · Hooks（钩子）

Hooks（钩子）

Hooks 是在 Claude Code 生命周期的特定事件点自动触发的用户自定义脚本/请求，用于观测、注入上下文或拦截/否决某些操作。

是什么

Hooks 是配置在 settings.json（或插件、Skill/Agent frontmatter）里的处理器，会在 Claude Code 运行过程中的特定事件（如 PreToolUse、UserPromptSubmit、Stop、SessionStart 等）被触发执行。处理器有 5 种类型：command（执行命令）、http（调用 HTTP 端点）、mcp_tool（调用 MCP 工具）、prompt（用小模型评估）、agent（用 agent 评估）。Hook 通过 stdin 收到 JSON 输入，通过 exit code 和 stdout 的 JSON 返回结果，从而能在事件点做日志、注入额外上下文、甚至阻断/否决工具调用与提示处理。

怎么工作

每个 hook 配置挂在某个事件名（EventName）下，事件触发时 Claude Code 按 matcher 匹配后执行对应处理器。
数据流：hook 进程通过 stdin 收到 JSON 输入（含 session_id、cwd、hook_event_name、permission_mode 以及该事件特有字段如 tool_input、prompt 等）。
返回方式有两种：(1) 退出码语义 —— exit 0 成功并解析 stdout 里的 JSON 输出；exit 2 是阻断错误，stderr 会被回喂给 Claude；其他非零是非阻断错误，只显示 stderr 第一行。(2) stdout 输出结构化 JSON 来做更细粒度的决策控制。
matcher 匹配规则：'*'/''/省略表示匹配全部；只含字母数字、_、| 时按精确字符串或竖线分隔列表匹配（如 Bash、Edit|Write）；含其他字符时按 JavaScript 正则匹配（如 ^Notebook、mcp__memory__.*）。
决策控制分两种形态：PreToolUse 用 hookSpecificOutput.permissionDecision（allow/deny/ask/defer）；UserPromptSubmit/PostToolUse/Stop 等用顶层 decision:'block' + reason。
exit 2 的可阻断性因事件而异：PreToolUse 阻断工具调用、UserPromptSubmit 阻断提示处理、Stop 阻止结束并继续对话；而 PostToolUse、SessionStart、Notification 等不可阻断，只把 stderr 显示出来。
注入上下文：SessionStart / UserPromptSubmit / Setup / SubagentStart 可通过 hookSpecificOutput.additionalContext 把内容注入到 Claude 的上下文。
配置文件被改动时由文件监听器（file watcher）自动重新加载，无需重启。
多来源 hook（User/Project/Local/Plugin/Session/Built-in）会合并；相同处理器会自动去重（command 按 command+args、http 按 URL）。

怎么配置

配置位置（优先级从低到高）：~/.claude/settings.json（user，全局）< .claude/settings.json（project，可提交）< .claude/settings.local.json（local，gitignore）< Managed policy settings（企业策略，覆盖一切）；另有插件 hooks/hooks.json 与 Skill/Agent frontmatter 内联。

JSON 结构：
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/scripts/check.sh", "timeout": 30 }
        ]
      }
    ]
  }
}

command hook 典型：通过 stdin 读 JSON，用 jq 解析，输出 hookSpecificOutput 决定 deny：
COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)
if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:"Destructive command blocked"}}'
else exit 0; fi

Skill/Agent frontmatter 内联：
hooks:
  PreToolUse:
    - matcher: "Tool"
      hooks:
        - type: command
          command: "./script.sh"
全局关闭：在 settings 里设 "disableAllHooks": true。运行时输入 /hooks 可打开只读浏览器查看所有事件与处理器（编辑只能改 JSON）。

什么时候用

何时用：需要在工具执行前做安全校验/拦截（PreToolUse 阻断 rm -rf）
何时用：会话开始时注入项目上下文或写环境变量（SessionStart + CLAUDE_ENV_FILE）
何时用：提交前/编辑后自动跑 lint、format、测试（PostToolUse / Stop）
何时用：把审计日志、通知（terminalSequence 桌面通知）接到外部系统（http hook）
别用：需要让 Claude 自己判断逻辑的业务行为——hook 是确定性的自动化，不该塞复杂业务逻辑
别用：依赖交互式终端的脚本——hook 进程没有 controlling terminal，不能开 /dev/tty

限制 / 坑

Hook 输出字符串（含 additionalContext、systemMessage、纯 stdout）上限 10,000 字符，超出会存文件只显示预览+路径。
Hook 进程无 controlling terminal（macOS/Linux v2.1.139+），不能打开 /dev/tty 或直接发转义序列，需用 systemMessage / terminalSequence 向用户输出。
terminalSequence 有白名单：只允许 OSC 0/1/2、9、9;4、99、777 和裸 BEL；CSI 光标、颜色、OSC 8 超链接、OSC 52 剪贴板、OSC 1337 会被拒绝并忽略该字段。
http hook 的 header 变量插值必须用 allowedEnvVars 显式声明，未列出的环境变量解析为空字符串。
Windows 下 exec form（设了 args）不能跑 .cmd/.bat 垫片，需要真正的 .exe；建议用 node script.js 包装。
Managed policy 的 allowManagedHooksOnly 会屏蔽 user/project/plugin hook（force-enabled 插件 hook 除外）；disableAllHooks 也不会关掉 policy 级 hook。
exit 2 并非所有事件都可阻断：StopFailure、PostToolUse、PermissionDenied、Notification、SessionStart、SessionEnd 等不可阻断。
reloadSkills 只对 settings 里的 SessionStart hook 生效；skill hook 的 once: true 只在 skill frontmatter 内被认可。

▸ 硬事实速查（21 条精确事实）

配置文件：~/.claude/settings.json（user）、.claude/settings.json（project，可提交）、.claude/settings.local.json（local，gitignore）、Managed policy settings（企业，覆盖全部）、插件 hooks/hooks.json、Skill/Agent frontmatter。
优先级：local 覆盖 project 覆盖 user；managed policy 覆盖一切；插件 hook 在插件启用时合并。
处理器类型 type：command、http、mcp_tool、prompt、agent。
默认 timeout（秒）：command/http/mcp_tool = 600，prompt = 30，agent = 60；在 UserPromptSubmit 下 command/http/mcp_tool/prompt 默认 30、agent 60。
通用输入字段：session_id、transcript_path、cwd、permission_mode（default|plan|acceptEdits|auto|dontAsk|bypassPermissions）、effort.level（low|medium|high|xhigh|max|ultra）、hook_event_name、agent_id、agent_type。
退出码：0 = 成功并解析 stdout JSON；2 = 阻断错误，stderr 回喂给 Claude；其他非零 = 非阻断错误，显示 stderr 第一行。
PreToolUse 决策：hookSpecificOutput.permissionDecision = allow|deny|ask|defer，配 permissionDecisionReason。
PermissionRequest 决策：hookSpecificOutput.decision.behavior = allow|deny（可带 updatedInput、appliedRules）。
顶层决策事件（UserPromptSubmit/UserPromptExpansion/PostToolUse/PostToolUseFailure/PostToolBatch/Stop/SubagentStop/ConfigChange/PreCompact）用 decision:"block" + reason。
通用输出字段：continue、stopReason、suppressOutput、systemMessage、terminalSequence、decision、reason、hookSpecificOutput。
matcher：'*'/''/省略=全部；纯字母数字+_+|=精确或竖线列表（Bash、Edit|Write）；含其他字符=JavaScript 正则。
MCP 工具命名格式 mcp__<server>__<tool>，例 mcp__memory__create_entities；matcher 可写 mcp__memory__.* 或 mcp__.*__write.*。
路径占位符：${CLAUDE_PROJECT_DIR}、${CLAUDE_PLUGIN_ROOT}、${CLAUDE_PLUGIN_DATA}。
环境变量：CLAUDE_PROJECT_DIR（所有 hook 进程）、CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA（插件 hook）、CLAUDE_ENV_FILE（SessionStart/Setup/CwdChanged/FileChanged，写 export 持久化到 Bash）、CLAUDE_CODE_REMOTE（web 为 "true"，CLI 未设）、CLAUDE_EFFORT（low|medium|high|xhigh|max|ultra）。
输出字符串上限 10,000 字符。
版本要求：terminalSequence 需 v2.1.141+；hook 无 controlling terminal 为 macOS/Linux v2.1.139+。
主要事件：SessionStart、Setup、UserPromptSubmit、UserPromptExpansion、PreToolUse、PermissionRequest、PermissionDenied、PostToolUse、PostToolUseFailure、PostToolBatch、Notification、MessageDisplay、SubagentStart、SubagentStop、TaskCreated、TaskCompleted、Stop、StopFailure、TeammateIdle、InstructionsLoaded、ConfigChange、CwdChanged、FileChanged、WorktreeCreate、WorktreeRemove、PreCompact、PostCompact、Elicitation、ElicitationResult、SessionEnd。
SessionStart matcher：startup|resume|clear|compact；PreCompact/PostCompact matcher：manual|auto；SessionEnd 结束原因：clear|resume|logout|prompt_input_exit|bypass_permissions_disabled|other。
Exec form（设 args）不经 shell 解释、特殊字符原样传；Shell form（省略 args）走 shell 分词/展开/管道，可用 shell:"powershell" 强制 PowerShell。
去重：command 按 command+args，http 按 URL，其他按相同处理器。
全局开关："disableAllHooks": true；运行时 /hooks 打开只读浏览器。

官方出处：https://code.claude.com/docs/en/hooks

模块 · MCP（外部工具/数据）

MCP（外部工具/数据）

MCP（Model Context Protocol）是一套开源标准，让 Claude Code 连接外部工具、数据库和 API，直接读取并操作这些系统而不用手动复制粘贴。

是什么

MCP（Model Context Protocol）是一个面向 AI-工具集成的开源标准（modelcontextprotocol.io）。通过连接 MCP server，Claude Code 可以访问你的工具、数据库和 API——例如从 JIRA 读 issue、查 Sentry 错误、查 PostgreSQL 数据库、读 Figma 设计稿。连接方式分三种传输：远程 HTTP（推荐）、远程 SSE（已废弃）、本地 stdio（本地进程）。当你发现自己在反复从别的工具（issue tracker、监控面板）往对话里复制数据时，就该接一个 MCP server。

怎么工作

三种传输：HTTP（远程云服务首选，spec 名为 streamable-http）、SSE（已废弃）、stdio（本地进程，直接系统访问）。
stdio server 启动时，Claude Code 会在其环境注入 CLAUDE_PROJECT_DIR（指向 project root），server 内用 process.env.CLAUDE_PROJECT_DIR / os.environ 读取；也可调 MCP roots/list 请求拿到启动目录。
配置按三个 scope 解析，同名 server 只连一次、取最高优先级来源的整条定义（不跨 scope 合并字段）。优先级：local > project > user > plugin-provided > claude.ai connectors。前三个按名字匹配重复，后两个按 endpoint(URL/command) 匹配。
Tool Search 默认开启：session 启动只加载 tool 名字，tool 定义延迟到 Claude 需要时通过 ToolSearch 搜索调入 context，所以加再多 server 对 context window 影响极小。
若请求需要某个仍在后台连接的 server，Claude 会等它连上；开启 tool search 时等待发生在 ToolSearch 调用内，否则（Vertex AI / 自定义 ANTHROPIC_BASE_URL / ENABLE_TOOL_SEARCH=false）用 WaitForMcpServers tool。
HTTP/SSE server 中途断开会自动重连：指数退避，最多 5 次，从 1 秒延迟开始每次翻倍；5 次失败后标记 failed，可在 /mcp 手动重试。stdio 是本地进程，不自动重连。
启动初连失败也用同样退避；v2.1.121 起对 5xx、connection refused、timeout 等瞬时错误最多重试 3 次（认证错误和 not-found 不重试）。
支持 MCP list_changed 通知：server 可动态更新 tools/prompts/resources，Claude Code 自动刷新，无需断开重连。
远程 server 返回 401 Unauthorized 或 403 Forbidden 时被标记为需认证，用 /mcp 走 OAuth 2.0 流程；token 安全存储并自动刷新。
MCP resources 用 @ 引用（@server:protocol://resource/path），引用时自动抓取并作为附件加入；MCP prompts 变成 slash command，格式 /mcp__servername__promptname。

怎么配置

三种 scope 的存储位置：local 与 user 存在 ~/.claude.json（local 写在该 project 路径下的 mcpServers，user 跨所有 project），project 存在项目根的 .mcp.json（入版本控制、团队共享，首次使用需审批）。

添加命令（所有 options 必须在 server name 之前，再用 -- 分隔传给 server 的命令）：
- HTTP: claude mcp add --transport http <name> <url>，加认证头 --header "Authorization: Bearer your-token"
- SSE（已废弃）: claude mcp add --transport sse <name> <url>
- stdio: claude mcp add [options] <name> -- <command> [args...]，例 claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server
- JSON: claude mcp add-json <name> '<json>'
- 从 Claude Desktop 导入: claude mcp add-from-claude-desktop（仅 macOS / WSL）

scope: --scope local|project|user（local 为默认；旧版 local 叫 project、user 叫 global）。

.mcp.json 标准格式（stdio 例）：
{ "mcpServers": { "shared-server": { "command": "/path/to/server", "args": [], "env": {} } } }
HTTP 例（type 可写 http 或别名 streamable-http）：
{ "mcpServers": { "api-server": { "type": "http", "url": "${API_BASE_URL:-https://api.example.com}/mcp", "headers": { "Authorization": "Bearer ${API_KEY}" } } } }
env 变量展开支持 ${VAR} 和 ${VAR:-default}，可用于 command/args/env/url/headers；必需变量未设且无默认值会导致解析失败。

管理：claude mcp list / claude mcp get <name> / claude mcp remove <name> / 交互内 /mcp（认证、看状态、清除认证）。重置 project 审批：claude mcp reset-project-choices。把 Claude Code 自身当 server：claude mcp serve。

什么时候用

该用：当你反复从外部系统（issue tracker、监控面板、数据库、设计工具）往对话里复制数据时——接 server 让 Claude 直接读写。
该用 HTTP transport：连接云端远程服务（最广泛支持）。
该用 stdio transport：需要直接系统访问或自定义本地脚本的工具。
团队共享配置时用 --scope project（写进 .mcp.json 入版本控制）；个人跨项目工具用 --scope user；个人/含密钥/实验性配置用默认 local scope（不进版本控制）。
别用 SSE transport：已废弃，有 HTTP 的地方一律用 HTTP。
连接前务必确认信任该 server：会抓外部内容的 server 有 prompt injection 风险。
用 alwaysLoad: true 仅限每轮都要用的极少数 tool，因为每个 upfront tool 都占 context。

限制 / 坑

SSE transport 已 deprecated，有 HTTP 就别用 SSE。
stdio server 是本地进程，断开后不会自动重连（只有 HTTP/SSE 自动重连）。
project-scoped server（.mcp.json）出于安全每次使用前需审批，未批的在 claude mcp list 显示 ⏸ Pending approval，拒绝的显示 ✗ Rejected。
server name 'workspace' 为内部保留名，定义了会被跳过并警告改名。
同名/同 endpoint 的 server 只取最高优先级整条定义，字段不跨 scope 合并——容易误以为会合并。
MCP 输出超 10,000 tokens 会告警；默认上限 25,000 tokens，超限内容会落盘并替换为文件引用。
tool description 和 server instructions 各自在 2KB 处被截断，关键信息要放前面。
anthropic/maxResultSizeChars 注解的硬上限是 500,000 字符；且对返回 image 的 tool 无效，图片只能靠调 MAX_MCP_OUTPUT_TOKENS。
headersHelper 执行任意 shell 命令，10 秒超时、无缓存、每次连接都重跑；在 project/local scope 下需先通过 workspace 信任对话框。
OAuth 相关 flag（--client-id/--client-secret/--callback-port）只对 HTTP 和 SSE 有效，对 stdio 无效。
claude.ai connectors 仅在认证方式为 Claude.ai 订阅时加载；设了 ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / apiKeyHelper 或用 Bedrock/Vertex 时不加载。
tool search 需要支持 tool_reference 的模型：Sonnet 4+ 或 Opus 4+，Haiku 不支持；Vertex AI 上需 Sonnet 4.5+ 或 Opus 4.5+。在 Vertex AI 及非一方 ANTHROPIC_BASE_URL 上默认关闭。
add 命令所有 options 必须在 server name 之前，否则会和 server 自身的 flag 冲突。
add-from-claude-desktop 仅支持 macOS 和 WSL；同名导入会加数字后缀如 server_1。
claude mcp serve 暴露的是 Claude Code 的 tools，单次 tool 调用的用户确认由你的 MCP client 负责实现。

▸ 硬事实速查（27 条精确事实）

三种 scope 存储：local→~/.claude.json（当前 project），project→项目根 .mcp.json（团队共享、入版本控制），user→~/.claude.json（跨所有 project）。
注意区分：MCP local-scope server 存 ~/.claude.json，而通用 local settings 存 .claude/settings.local.json（不是同一个）。
scope 优先级：1 Local 2 Project 3 User 4 Plugin-provided 5 claude.ai connectors。
传输类型：http（推荐，别名 streamable-http）、sse（deprecated）、stdio。
核心命令：claude mcp add / add-json / add-from-claude-desktop / list / get <name> / remove <name> / reset-project-choices / serve。交互内 /mcp 与 /status。
--scope 取值：local（默认，旧名 project）/ project（旧名 global 是 user）/ user（旧名 global）。
stdio server 环境会被注入 CLAUDE_PROJECT_DIR（=project root）；plugin 配置可直接用 ${CLAUDE_PROJECT_DIR}，普通 .mcp.json 引用需给默认值如 ${CLAUDE_PROJECT_DIR:-.}。
env 展开语法：${VAR} 和 ${VAR:-default}；可展开位置：command、args、env、url、headers。
重连：HTTP/SSE 自动重连，指数退避，最多 5 次，初始 1 秒延迟、每次翻倍。stdio 不重连。
v2.1.121 起：初连瞬时错误（5xx / connection refused / timeout）最多重试 3 次；认证错误与 not-found 不重试。
超时：MCP_TIMEOUT 控制 server 启动超时（例 MCP_TIMEOUT=10000 = 10 秒）；.mcp.json 每 server 加 timeout 字段（毫秒，例 "timeout": 600000 = 10 分钟）覆盖 MCP_TOOL_TIMEOUT；小于 1000 取整为 1 秒；HTTP/SSE 首字节预算有 60 秒下限。
输出：超 10,000 tokens 告警；默认上限 25,000 tokens；用 MAX_MCP_OUTPUT_TOKENS 调整（例 MAX_MCP_OUTPUT_TOKENS=50000）。
server 作者可在 tool 的 tools/list 用 _meta["anthropic/maxResultSizeChars"] 提升单 tool 文本阈值，硬上限 500,000 字符；对 image 无效。
认证：401 或 403 触发标记需认证；支持 OAuth 2.0；/mcp 走流程，菜单内 Clear authentication 撤销；client secret 存 macOS keychain 或凭据文件，不进 config。
OAuth flag：--callback-port（固定回调端口，格式 http://localhost:PORT/callback）、--client-id、--client-secret（掩码输入），或环境变量 MCP_CLIENT_SECRET；只对 HTTP/SSE 有效。
OAuth 高级 .mcp.json oauth 字段：authServerMetadataUrl（需 v2.1.64+，必须 https）、scopes（空格分隔字符串，优先级最高）；默认发现链先查 RFC 9728 /.well-known/oauth-protected-resource 再 RFC 8414 /.well-known/oauth-authorization-server。
headersHelper：动态生成请求头，命令需向 stdout 输出 JSON 字符串键值对，10 秒超时、无缓存；注入 CLAUDE_CODE_MCP_SERVER_NAME 与 CLAUDE_CODE_MCP_SERVER_URL。
Tool Search 默认开启；ENABLE_TOOL_SEARCH 取值：unset（全部延迟）/ true（强制延迟，发 beta header）/ auto（装得下 10% context 就 upfront 否则延迟）/ auto:N（自定义百分比，N 0-100，如 auto:5）/ false（全部 upfront）。可在 settings.json env 设置，或用 permissions.deny ["ToolSearch"] 禁掉。
alwaysLoad：.mcp.json server 级字段（需 v2.1.121+，所有 transport 可用）或 tool _meta 内 "anthropic/alwaysLoad": true，让 tool 始终 upfront；设 true 还会阻塞启动直到连上，上限 5 秒连接超时。
MCP resources 引用格式：@server:protocol://resource/path，例 @github:issue://123、@docs:file://api/authentication。
MCP prompts 作为 command：/mcp__servername__promptname，参数空格分隔，例 /mcp__github__pr_review 456。
plugin 内 MCP 用 ${CLAUDE_PLUGIN_ROOT}（bundled 文件）、${CLAUDE_PLUGIN_DATA}（持久化状态）、${CLAUDE_PROJECT_DIR}；session 中改了 plugin 启停需 /reload-plugins。
禁用 claude.ai MCP server：ENABLE_CLAUDEAI_MCP_SERVERS=false claude；在 claude.ai/customize/connectors 添加（Team/Enterprise 仅 admin 可加）。
scaffold 自己的 server：/plugin install mcp-server-dev@claude-plugins-official，然后 /mcp-server-dev:build-mcp-server。
Claude Code 当 server：claude mcp serve，在 claude_desktop_config.json 配 command "claude" args ["mcp","serve"]，找路径用 which claude，否则报 spawn claude ENOENT。
Elicitation：server 可中途请求结构化输入（Form mode 表单 / URL mode 浏览器），无需配置自动弹窗；可用 Elicitation hook 自动应答。
企业集中管控见 Managed MCP：managed-mcp.json + allowedMcpServers / deniedMcpServers。

官方出处：https://code.claude.com/docs/en/mcp

模块 · Slash Commands（斜杠命令）

Slash Commands（斜杠命令）

在 Claude Code 中用 / 触发的命令；自定义命令已合并进 Skills，由 SKILL.md（或旧的 .claude/commands/*.md）定义，可由你手动触发或让 Claude 自动加载。

是什么

官方文档 https://code.claude.com/docs/en/slash-commands 现已重定向到「Extend Claude with skills」页面，因为 **Custom commands have been merged into skills**（自定义斜杠命令已合并进 Skills）。一个 .claude/commands/deploy.md 文件和一个 .claude/skills/deploy/SKILL.md 都会创建 /deploy，二者行为一致；已有的 .claude/commands/ 文件继续可用。Skills 在此基础上增加了：支持文件目录、控制由你还是 Claude 调用的 frontmatter、以及 Claude 在相关时自动加载的能力。Skills 遵循 Agent Skills 开放标准（agentskills.io），Claude Code 在其上扩展了 invocation control、subagent execution、dynamic context injection。built-in commands（如 /help、/compact）和 bundled skills（如 /code-review、/batch、/debug、/loop、/claude-api）见 /en/commands 参考页。

怎么工作

命令名来自文件位置：.claude/skills/<dir>/SKILL.md 的命令名取自目录名（如 deploy-staging → /deploy-staging）；.claude/commands/x.md 取自去扩展名的文件名（→ /x）。frontmatter 的 name 字段只是列表里的显示标签，不改变你输入的 / 命令名（plugin 根 SKILL.md 是唯一例外）。
常规会话里只把 skill 的 description 注入上下文供 Claude 判断何时使用；完整 SKILL.md 内容仅在被调用时才加载（subagent preload 例外，启动即注入完整内容）。
调用后 rendered SKILL.md 作为一条 message 进入对话并在整个 session 中保留，Claude Code 不会在后续轮次重新读取该文件——所以要把贯穿任务的指引写成 standing instructions。
Auto-compaction 时按 token 预算把已调用 skill 带过摘要：每个 skill 保留前 5,000 tokens，所有重新附加的 skill 共享 25,000 tokens 预算，从最近调用的开始填，旧的可能被整个丢弃。
参数替换在内容里展开：$ARGUMENTS=全部参数原样；$ARGUMENTS[N] / $N=按 0 基下标取单个参数（shell 风格引号，多词要加引号）；若 skill 不含 $ARGUMENTS 但你传了参数，会在内容末尾追加 ARGUMENTS: <你的输入>。
动态上下文注入：` !<command> 在发给 Claude 之前先执行 shell 命令，用输出替换占位符（preprocessing，不是 Claude 执行）。只替换一次，输出不会被再次扫描；! 只在行首或紧跟空白时识别，KEY=!\cmd\ 这种会被当字面文本。多行命令用 ``! 围栏代码块。
context: fork 让 skill 在 forked subagent 里隔离运行：SKILL.md 内容成为 subagent 的 prompt，不带主对话历史；agent 字段决定执行环境（model/tools/permissions），省略则用 general-purpose。
skill 描述列表有字符预算：预算按模型 context window 的 1% 缩放，溢出时优先丢弃你最少调用的 skill 的描述；每条 description+when_to_use 合并文本上限 1,536 字符。
Live change detection：Claude Code 监听 skill 目录，在 ~/.claude/skills/、项目 .claude/skills/、--add-dir 目录下的 .claude/skills/ 增删改会在当前 session 内即时生效；但新建一个 session 启动时不存在的顶层 skills 目录需要重启。

怎么配置

文件位置（按优先级 enterprise > personal > project，plugin 用 plugin-name:skill-name 命名空间不冲突）：Personal=~/.claude/skills/<skill-name>/SKILL.md（所有项目可用）；Project=.claude/skills/<skill-name>/SKILL.md（仅本项目，提交进 VCS 共享）；Plugin=<plugin>/skills/<skill-name>/SKILL.md；旧式 Custom command=.claude/commands/<name>.md。SKILL.md 结构：--- 之间是 YAML frontmatter（所有字段可选，仅推荐写 description），其后是 markdown 指令。最小例：---\ndescription: ...\n---\n## Instructions\n...。动态注入例：!git diff HEAD。参数例：Fix GitHub issue $ARGUMENTS 配 /fix-issue 123。fork 例：frontmatter 加 context: fork 和 agent: Explore。权限预批准：allowed-tools: Bash(git add *) Bash(git commit *)。禁止 Claude 自动调用：disable-model-invocation: true。从 / 菜单隐藏：user-invocable: false。设置文件层面覆盖可见性用 .claude/settings.local.json 的 skillOverrides（/skills 菜单里 Space 切换、Enter 保存）。

什么时候用

当你反复把同一套指令/检查清单/多步流程粘贴进对话，或 CLAUDE.md 里某段已经长成了一套流程（procedure）而不是事实（fact）时——做成 skill；它的正文只在被用到时才加载，长参考材料平时几乎零成本。
Task content（部署、提交、代码生成等有副作用、需你掌控时机的动作）：用 disable-model-invocation: true 做成只你能 /name 手动触发的命令，比如 /commit、/deploy、/send-slack-message。
Reference content（约定、风格指南、领域知识）：让 Claude 在相关时自动加载、内联应用；只供 Claude 用、用户不该直接触发的背景知识用 user-invocable: false。
需要让命令拿到实时数据时用 ` !<command> ` 注入（如 git diff、gh pr diff），而不是让 Claude 自己去跑。
需要隔离/不污染主上下文的探索或研究任务用 context: fork（搭配 agent: Explore/Plan）。
别用 fork 的场景：skill 只是「用这些 API 约定」这类没有明确任务的 guideline——subagent 拿到指引却没有可执行 prompt，会空转返回。

限制 / 坑

slash-commands 页面已合并/重定向到 skills 页面：自定义命令本身不再是独立概念，而是 skills 的一种形态。
skill 调用后内容常驻整个 session、不重读文件，每行都是 recurring token 成本；正文建议 <500 行，详细参考材料拆到单独文件。
compaction 后旧 skill 可能被整个丢弃（25,000 tokens 共享预算，每个保留前 5,000 tokens，从最近的开始填）；若失效可在 compaction 后重新调用。
description+when_to_use 合并文本被截断在 1,536 字符（用 maxSkillDescriptionChars 可配）；skill 多时描述会因预算被缩短甚至丢关键词，用 /doctor 查是否溢出。
! 仅在行首或紧跟空白时触发命令注入；紧跟其他字符（如 KEY=!\cmd\``）会被当字面文本不执行。命令注入只跑一次，输出不会被二次扫描展开新的占位符。
user-invocable: false 只控制 / 菜单可见性，不阻止 Skill tool 编程调用；要彻底屏蔽 Claude 调用须用 disable-model-invocation: true。
context: fork 用 Explore/Plan agent 时会跳过 CLAUDE.md 和 git status；普通 fork 会加载 CLAUDE.md。
--add-dir / /add-dir 是文件访问授权而非配置发现，但 .claude/skills/ 是例外会自动加载；permissions.additionalDirectories 设置只给文件访问、不加载 skills；subagents/commands/output styles 都不从附加目录加载。
plugin skills 不受 skillOverrides 影响，需通过 /plugin 管理。
disableSkillShellExecution: true 会把每个命令替换为 [shell command execution disabled by policy]；bundled 和 managed skills 不受影响。

▸ 硬事实速查（21 条精确事实）

官方文档 https://code.claude.com/docs/en/slash-commands 现重定向到 skills 页（标题 Extend Claude with skills）。原文：Custom commands have been merged into skills。
路径：Personal ~/.claude/skills/<skill-name>/SKILL.md；Project .claude/skills/<skill-name>/SKILL.md；Plugin <plugin>/skills/<skill-name>/SKILL.md；旧式 .claude/commands/<name>.md。
优先级：enterprise 覆盖 personal，personal 覆盖 project；plugin 用 plugin-name:skill-name 命名空间；同名时 skill 优先于 command。
命令名来源：skills 目录名（.claude/skills/deploy-staging → /deploy-staging）；commands 去扩展名文件名（.claude/commands/deploy.md → /deploy）；plugin skills/ 子目录用目录名并加 plugin 前缀（my-plugin/skills/review → /my-plugin:review）；plugin 根 SKILL.md 用 frontmatter name、缺省回退到 plugin 目录名。
frontmatter 字段：name、description（recommended）、when_to_use、argument-hint、arguments、disable-model-invocation（默认 false）、user-invocable（默认 true）、allowed-tools、disallowed-tools、model、effort、context、agent、hooks、paths、shell。
effort 选项：low / medium / high / xhigh / max（按模型可用）。
shell 字段：bash（默认）或 powershell；powershell 需 CLAUDE_CODE_USE_POWERSHELL_TOOL=1。
字符串替换变量：$ARGUMENTS、$ARGUMENTS[N]、$N（$0 为第一个）、$name（来自 arguments 列表，按顺序映射）、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT}（low/medium/high/xhigh/max/ultra，ultra 是 ultracode 的存储值）、${CLAUDE_SKILL_DIR}（SKILL.md 所在目录）。
动态注入：行内 ` !<command> ；多行用 ``! 围栏块；在发给 Claude 前执行、输出替换占位符。
description+when_to_use 合并文本在 skill 列表中截断于 1,536 characters；可用 maxSkillDescriptionChars 配置。
skill 列表预算默认为模型 context window 的 1%，用 skillListingBudgetFraction（如 0.02=2%）或环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET（固定字符数）调整；用 /doctor 查溢出。
compaction：每个重新附加 skill 保留前 5,000 tokens；所有重新附加 skill 共享 25,000 tokens 预算。
建议 SKILL.md 保持 < 500 lines。
context: fork 用 agent 字段选 subagent：Explore / Plan / general-purpose 或 .claude/agents/ 自定义；省略则 general-purpose；Explore/Plan 会跳过 CLAUDE.md 和 git status。
Skill tool 权限：/permissions 里 deny Skill 禁用全部；Skill(name) 精确匹配、Skill(name *) 前缀匹配；少数 built-in 命令可经 Skill tool 调用，含 /init、/review、/security-review，而 /compact 等不可。
skillOverrides 四种状态：on（名+描述，菜单可见）、name-only（仅名，菜单可见）、user-invocable-only（对 Claude 隐藏，菜单可见）、off（全隐藏）；缺省视为 on；写入 .claude/settings.local.json。
Bundled skills：/code-review、/batch、/debug、/loop、/claude-api；/run、/verify、/run-skill-generator 需 Claude Code v2.1.145 或更高，记录的 per-project skill 存于 .claude/skills/run-<name>/。
disableSkillShellExecution: true（settings）禁用 user/project/plugin/additional-directory 来源的 shell 注入；bundled 与 managed skills 不受影响。
附加目录：.claude/skills/ 在 --add-dir//add-dir 目录下会自动加载（例外）；permissions.additionalDirectories 不加载 skills；附加目录 CLAUDE.md 默认不加载，需 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1。
skill 目录结构：SKILL.md（必需入口）+ 可选 template.md / examples/ / scripts/ 等支持文件。
在 skill 内容任意位置写 ultrathink 可请求更深推理。

官方出处：https://code.claude.com/docs/en/slash-commands

模块 · Plugins（插件）

Plugins（插件）

把 skills/agents/hooks/MCP/LSP/monitors 等自定义能力打包成可版本化、可跨项目复用、可通过 marketplace 分发的扩展单元。

是什么

Plugin 是 Claude Code 的扩展打包机制：一个目录里放一个 .claude-plugin/plugin.json manifest，加上 skills/、agents/、hooks/、.mcp.json、.lsp.json、monitors/、bin/、settings.json 等组件目录/文件。相对于直接放在 .claude/ 的 standalone 配置，plugin 的核心区别是：可分享给团队/社区、可版本化更新、可跨多个项目复用、通过 marketplace 安装；代价是 skill 名称被强制加上命名空间前缀（如 /my-plugin:hello）。官方文档把 standalone（.claude/，skill 名形如 /hello）与 plugin（.claude-plugin/plugin.json，skill 名形如 /plugin-name:hello）作为两种并列方式对照。

怎么工作

每个 plugin 是独立目录，目录里必须有 .claude-plugin/plugin.json manifest，Claude Code 读取其中 metadata 在 plugin manager 中展示
skills 放在 plugin 根的 skills/ 下，每个 skill 是一个文件夹含 SKILL.md；文件夹名即 skill 名，并自动加上 plugin 的 name 作为命名空间前缀，例如 plugin 名 my-first-plugin 下的 hello/ 变成 /my-first-plugin:hello
命名空间是强制的，用来避免多个 plugin 有同名 skill 时冲突；改前缀只能改 plugin.json 的 name 字段
SKILL.md 是 YAML frontmatter + 指令正文；frontmatter 里的 description 决定 Claude 何时自动调用该 skill（model-invoked）；$ARGUMENTS 占位符捕获 skill 名后面用户输入的文本
开发期用 claude --plugin-dir ./my-plugin 直接加载本地 plugin，不需要安装；改动后用 /reload-plugins 热加载（会重载 plugins/skills/agents/hooks/plugin MCP servers/plugin LSP servers），无需重启
当 --plugin-dir 加载的本地 plugin 与已安装的 marketplace plugin 同名时，本会话以本地副本为准（被 managed settings 强制启停的 plugin 除外）
hooks 放在 hooks/hooks.json，格式与 .claude/settings.json 里的 hooks 对象相同；命令通过 stdin 接收 JSON 形式的 hook input（用 jq 提取字段如 file_path）
LSP server 通过根目录 .lsp.json 配置（command/args/extensionToLanguage），给 Claude 实时代码智能；用户机器上必须装有对应 language server 二进制
background monitors 在 monitors/monitors.json 配置；plugin 激活时 Claude Code 自动启动每个 monitor，command 的每行 stdout 作为 notification 推给 Claude
bin/ 里的可执行文件在 plugin 启用期间会被加进 Bash 工具的 PATH
plugin 根的 settings.json 在 plugin 启用时应用默认设置，目前仅支持 agent 和 subagentStatusLine 两个 key；agent 可把 plugin 自带的某个 custom agent 设为主线程（套用其 system prompt/工具限制/model）
版本控制：设了 version 时用户只在你 bump 该字段后才收到更新；省略且经 git 分发时用 commit SHA，每次 commit 都算新版本

怎么配置

manifest 路径固定为 <plugin>/.claude-plugin/plugin.json，最小示例：
{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}
组件目录全部放 plugin 根（不是 .claude-plugin/ 里面）：skills/<name>/SKILL.md、commands/（旧式扁平 md，新 plugin 用 skills/）、agents/、hooks/hooks.json、.mcp.json、.lsp.json、monitors/monitors.json、bin/、settings.json。
SKILL.md frontmatter 示例：description:（决定何时调用）、disable-model-invocation: true（禁止模型自动触发）；正文里用 $ARGUMENTS 接收输入。
本地测试：claude --plugin-dir ./my-plugin（可重复多次加载多个；也接受 .zip，需 v2.1.128+）；远程 zip：claude --plugin-url https://example.com/my-plugin.zip（可重复或空格分隔）。
marketplace：/plugin marketplace add anthropics/claude-plugins-community 添加社区市场，安装用 /plugin install；提交前本地跑 claude plugin validate。

什么时候用

用 plugin：要分享给团队/社区、跨多个项目复用、需要版本化和便捷更新、要通过 marketplace 分发、能接受命名空间化的 skill 名（如 /my-plugin:hello）
用 standalone（.claude/）：只为单个项目定制、个人配置不需分享、在打包前快速试验 skill/hook、想要短 skill 名（如 /hello、/deploy）
官方建议：先在 .claude/ 里快速迭代，准备好分享时再转成 plugin
自定义 LSP plugin 仅在需要支持官方 marketplace 尚未覆盖的语言时才做；TypeScript/Python/Rust 等常见语言直接装官方预建 LSP plugin

限制 / 坑

常见错误：不要把 commands/、agents/、skills/、hooks/ 放进 .claude-plugin/ 目录——.claude-plugin/ 里只能放 plugin.json，其余目录都必须在 plugin 根级
plugin 的 skill 名称永远是命名空间化的，无法去掉前缀，只能通过改 name 字段换前缀
settings.json 目前只支持 agent 和 subagentStatusLine 两个 key，未知 key 被静默忽略
settings.json 的设置优先级高于 plugin.json 里声明的 settings
--plugin-dir 接受 .zip 需要 Claude Code v2.1.128 或更高版本
--plugin-dir 无法覆盖被 managed settings 强制启用/禁用的 plugin
--plugin-url 在启动时拉取归档，仅当前会话有效；拉取失败或归档无效则报 plugin load error 并不带它启动；只应指向你信任/掌控的归档
LSP plugin 要求用户本机已安装对应 language server 二进制，否则不可用
提交社区市场后，公开 catalog 每晚（nightly）从审核管线同步，审核通过到出现在 marketplace.json 之间存在延迟
提交表单只进入社区市场审核，不会加入 official marketplace；official marketplace 由 Anthropic 自行决定收录，无申请流程
若看不到 /plugin 命令，需把 Claude Code 升级到最新版本

▸ 硬事实速查（26 条精确事实）

manifest 固定路径：.claude-plugin/plugin.json
plugin.json 字段：name（唯一标识 + skill 命名空间）、description（plugin manager 中展示）、version（可选，控制更新）、author（可选，如 {"name": "Your Name"}）；更多字段如 homepage/repository/license 见 plugins-reference
skill 命名规则：skills/<folder>/SKILL.md，名称变为 /<plugin-name>:<folder>，如 /my-first-plugin:hello
SKILL.md frontmatter 字段示例：description、disable-model-invocation: true
skill 参数占位符：$ARGUMENTS
plugin 根目录组件清单：.claude-plugin/（仅放 plugin.json）、skills/、commands/、agents/、hooks/、.mcp.json、.lsp.json、monitors/、bin/、settings.json
commands/ = 扁平 Markdown 文件形式的 skill；新 plugin 应改用 skills/
hooks/hooks.json 格式与 .claude/settings.json 的 hooks 对象相同；hook command 通过 stdin 收 JSON
.lsp.json 字段：每语言 key 下 command、args、extensionToLanguage（如 {".go": "go"}）；示例 command gopls args ["serve"]
monitors/monitors.json 是数组，条目字段含 name、command、description；还有 when 触发器和变量替换（见 reference）
settings.json 支持的 key：agent、subagentStatusLine
bin/ 中可执行文件在 plugin 启用时加入 Bash 工具 PATH
本地加载命令：claude --plugin-dir ./my-first-plugin，可重复指定多次
--plugin-dir 接受 .zip 需 Claude Code v2.1.128+
远程加载命令：claude --plugin-url https://example.com/my-plugin.zip，可重复或空格分隔多 URL
热重载命令：/reload-plugins（重载 plugins/skills/agents/hooks/plugin MCP servers/plugin LSP servers）
查看 agent：/agents；查看 skill 列表：/help
官方两个公共 marketplace：claude-plugins-official（Anthropic 策展，每个安装自带）、claude-community（社区，第三方审核后落地）
添加社区市场命令：/plugin marketplace add anthropics/claude-plugins-community，从中安装记作 @claude-community
安装命令：/plugin install
本地校验命令：claude plugin validate（提交前跑，审核管线也跑同样检查）
社区提交表单：Claude.ai claude.ai/settings/plugins/submit、Console platform.claude.com/plugins/submit
审核通过的 plugin 在 anthropics/claude-plugins-community catalog 中被 pin 到特定 commit SHA，CI 随新 commit 自动 bump pin
社区 catalog 路径：anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json，每晚同步
迁移对照：.claude/commands/ → plugin-name/commands/；settings.json 中 hooks → hooks/hooks.json
standalone skill 名 /hello vs plugin skill 名 /plugin-name:hello

官方出处：https://code.claude.com/docs/en/plugins

模块 · Permissions（权限）

Permissions（权限）

通过 allow/ask/deny 规则、权限模式和托管策略，细粒度控制 Claude Code 能用哪些工具、能访问哪些文件和域名。

是什么

Permissions 是 Claude Code 的分层权限系统，用来精确指定 agent 被允许做什么、不被允许做什么。规则可以签入版本控制并分发给组织内所有开发者，也能被单个开发者自定义。权限规则由 Claude Code（而非模型）强制执行——prompt 或 CLAUDE.md 只能影响 Claude "想做什么"，不能改变 Claude Code "允许什么"。它和 Sandboxing（OS 级隔离）是互补的两层安全。

怎么工作

三类工具分层：只读（文件读取、Grep）不需批准；Bash 命令需批准，选"Yes, don't ask again"后按项目目录+命令永久记住；文件修改（Edit/write）需批准，但记住只到 session 结束。
规则求值顺序固定为 deny -> ask -> allow，第一条匹配的规则生效，所以 deny 永远优先。
deny 规则有两种行为：裸工具名如 Bash 会把整个工具从 Claude 的上下文里移除（Claude 根本看不到它）；带 specifier 的如 Bash(rm *) 保留工具，仅在调用匹配时阻止。
规则格式为 Tool 或 Tool(specifier)。裸工具名匹配该工具所有用法；Bash(*) 等价于 Bash。
Bash 通配符 * 可出现在命令任意位置；命令末尾带空格的 * 强制词边界——Bash(ls *) 匹配 ls -la 但不匹配 lsof，Bash(ls*) 两者都匹配；:* 后缀等价于结尾的 ' *'，只在模式末尾被识别。
Bash 能识别 shell 操作符：复合命令的每个子命令必须各自被规则匹配才放行；识别的分隔符是 && || ; | |& & 和换行。批准复合命令时会为每个需批准的子命令分别存规则，单条复合命令最多存 5 条规则。
Bash 匹配前会剥离固定的进程包装器 timeout/time/nice/nohup/stdbuf，以及无 flag 的裸 xargs；这个列表内置不可配置。
Bash 内置一组只读命令（ls/cat/echo/pwd/head/tail/grep/find/wc/which/diff/stat/du/cd 及只读形式的 git），任何模式下都不弹窗，不可配置。
Read/Edit 路径模式遵循 gitignore 规范，分四种锚点：// 绝对路径、~/ 家目录、/ 项目根相对、path 或 ./path 当前目录相对；* 匹配单层目录，** 跨目录递归。
符号链接会同时检查 symlink 本身和解析后的目标：allow 规则需两者都匹配否则降级为弹窗；deny 规则只要任一匹配就阻止。
PreToolUse hook 在权限弹窗前运行，可 deny/force prompt/skip；但 hook 决定不能绕过 deny 和 ask 规则，exit code 2 的阻塞型 hook 优先于 allow 规则。

怎么配置

用 /permissions 命令查看和管理所有规则及其来源 settings.json 文件。规则写在 settings 文件的 permissions 对象下的 allow / ask / deny 数组里，并通过 defaultMode 设置默认权限模式。settings 文件优先级（高到低）：Managed settings > 命令行参数 > .claude/settings.local.json > .claude/settings.json > ~/.claude/settings.json。示例：
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)", "Bash(git * main)"],
    "deny": ["Bash(git push *)", "Read(.env)", "Agent(Explore)"]
  }
}
扩展工作目录：启动用 --add-dir <path>，session 中用 /add-dir，持久化用 settings 里的 additionalDirectories。CLI 还可用 --allowedTools / --disallowedTools 临时覆盖。

什么时候用

何时用 allow：把高频且安全的命令/工具加入允许列表，免去反复弹窗（如 Bash(npm run *)、WebFetch(domain:example.com)）。
何时用 deny：阻止危险操作或保护敏感文件（如 Bash(git push *)、Read(.env)、Read(~/.ssh/**)）；裸工具名 deny 可彻底隐藏某工具。
何时用 ask：希望某工具每次使用都确认。
何时用 plan 模式：只想让 Claude 探索代码、读文件、跑只读命令，不改源文件。
何时用 acceptEdits：信任的本地环境里自动接受文件编辑和常见 fs 命令。
何时别用 bypassPermissions：仅在容器/VM 等隔离环境用，普通开发机绝不要用。
URL 过滤别只靠 Bash 参数约束（如 Bash(curl http://github.com/ *)）——很脆弱；改用 deny 封掉 curl/wget + WebFetch(domain:...) 白名单，或用 PreToolUse hook。

限制 / 坑

权限由 Claude Code 强制执行，不是模型；prompt 和 CLAUDE.md 改不了允许边界。
Read/Edit deny 规则只覆盖内置文件工具和 Claude Code 能识别的 Bash 文件命令（cat/head/tail/sed）；不覆盖间接读写文件的子进程（如 Python/Node 脚本）——要 OS 级封堵须启用 sandbox。
Bash 参数约束模式很脆弱：选项位置、协议差异、重定向、变量、多余空格都能绕过（curl 例子）。
进程包装器剥离列表内置不可配置；direnv exec/devbox run/mise exec/npx/docker exec 等环境 runner 不在列表里，Bash(devbox run *) 会匹配 run 后面的任意命令包括 devbox run rm -rf .，须为每个内部命令写精确规则。
exec 包装器 watch/setsid/ionice/flock 始终弹窗，无法被 Bash(watch *) 这类前缀规则自动批准；find -exec / -delete 同理，Bash(find *) 不覆盖。
复合命令单条最多存 5 条规则。
:* 只在模式末尾识别；Bash(git:* push) 里冒号被当字面字符，不匹配 git 命令。
additionalDirectories（settings 里的）只授予文件访问，不加载该目录的 .claude/ 配置；只有 --add-dir / /add-dir 才会加载部分配置（skills、部分 plugin 设置、需 env 开启的 CLAUDE.md）。
形如 /Users/alice/file 不是绝对路径，而是项目根相对；绝对路径要写 //Users/alice/file。
bypassPermissions 仍会对 rm -rf / 和 rm -rf ~ 弹窗作为熔断；管理员可用 permissions.disableBypassPermissionsMode 设为 disable 禁用该模式。
deny 在任何层级生效后，其他层级都无法 allow；managed settings 的 deny 连命令行参数都覆盖不了。

▸ 硬事实速查（30 条精确事实）

管理命令：/permissions（查看/管理规则，显示来源 settings.json）
三个规则数组：permissions.allow / permissions.ask / permissions.deny
求值顺序：deny -> ask -> allow，第一条匹配生效
规则格式：Tool 或 Tool(specifier)；Bash(*) 等价于 Bash
权限模式（defaultMode 取值）：default / acceptEdits / plan / auto（research preview）/ dontAsk / bypassPermissions
acceptEdits 自动接受文件编辑和常见 fs 命令 mkdir/touch/mv/cp 等（限工作目录或 additionalDirectories 内路径）
dontAsk：自动拒绝未经 /permissions 或 permissions.allow 预批准的工具
bypassPermissions：跳过所有弹窗，但 rm -rf / 和 rm -rf ~ 仍弹窗；会写 .git/.claude/.vscode/.idea/.husky
禁用模式：permissions.disableBypassPermissionsMode、permissions.disableAutoMode 设为 "disable"
Bash 通配符：* 可在任意位置；Bash(ls *) 匹配 ls -la 不匹配 lsof；Bash(ls*) 两者都匹配；:* 后缀等价结尾 ' *'
Bash 复合命令分隔符：&& || ; | |& & 和换行；单条复合命令最多存 5 条规则
剥离的进程包装器（内置不可配置）：timeout、time、nice、nohup、stdbuf，以及无 flag 的 xargs
始终弹窗的 exec 包装器：watch、setsid、ionice、flock；find -exec / -delete 也不被 Bash(find *) 覆盖
内置只读 Bash 命令：ls cat echo pwd head tail grep find wc which diff stat du cd 及只读形式 git（不可配置）
Read/Edit 四种 gitignore 锚点：//path 绝对、~/path 家目录、/path 项目根相对、path 或 ./path 当前目录相对
示例：Read(//Users/alice/secrets/**)、Read(~/Documents/*.pdf)、Edit(/src/**/*.ts)、Read(*.env)
Read(.env) 等价 Read(**/.env)；* 匹配单层、** 递归
Windows 路径归一化为 POSIX：C:\Users\alice -> /c/Users/alice，跨盘用 //**/.env
WebFetch 规则：WebFetch(domain:example.com)
MCP 规则：mcp__puppeteer（整个 server）、mcp__puppeteer__*（通配全部工具）、mcp__puppeteer__puppeteer_navigate（单个工具）
Agent 规则：Agent(Explore)、Agent(Plan)、Agent(my-custom-agent)；可用 --disallowedTools 禁用
PowerShell 规则：与 Bash 同形，PowerShell(Get-ChildItem *)、:* 后缀等价；别名 gci/ls/dir 会被规范化匹配；大小写不敏感；7+ 支持 && ||
工作目录扩展：--add-dir <path>（启动）、/add-dir（session）、additionalDirectories（持久化 settings）
settings 优先级（高到低）：Managed settings > 命令行参数 > .claude/settings.local.json > .claude/settings.json > ~/.claude/settings.json
CLI 标志：--allowedTools、--disallowedTools
Managed-only 设置示例：allowManagedPermissionRulesOnly、allowManagedMcpServersOnly、allowManagedHooksOnly、strictPluginOnlyCustomization、disableBypassPermissionsMode、forceRemoteSettingsRefresh
env 变量：CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1（让 --add-dir 目录加载 CLAUDE.md）
sandbox 默认 autoAllowBashIfSandboxed: true，沙箱内 Bash 即使有 ask: Bash(*) 也不弹窗，但 deny 和 rm 关键路径仍生效
符号链接检查 symlink 路径与解析目标两条路径；allow 需双匹配，deny 任一匹配即拦
PreToolUse hook：exit code 2 阻塞优先于 allow；hook 不能绕过 deny/ask

官方出处：https://code.claude.com/docs/en/permissions

模块 · Settings（设置）

Settings（设置）

Claude Code 通过分层的 settings.json 文件统一管理权限、模型、环境变量、hooks、MCP、UI 等几乎所有可配置行为，并按 Managed → 命令行 → Local → Project → User 的优先级合并。

是什么

Settings 是 Claude Code 的核心配置系统，主体是 JSON 格式的 settings.json 文件，分布在四个 scope：Managed（IT 部署、不可覆盖）、User（~/.claude/settings.json）、Project（.claude/settings.json，提交到 git）、Local（.claude/settings.local.json，被 gitignore）。同一个 key 出现在多个 scope 时按固定优先级合并。文档原话：「settings.json supports a number of options」。除 settings.json 外，还有一批存放在 ~/.claude.json 的全局/UI 类配置，以及对应的环境变量、/config 命令交互界面。

怎么工作

四个 scope 的文件被读取后按优先级「合并」（merge），不是整体替换：同名 key 高优先级覆盖低优先级，未指定的 key 沿用低优先级值。
优先级从高到低：1. Managed（最高，不可被任何东西覆盖）2. 命令行参数（临时 session 覆盖）3. Local（.claude/settings.local.json）4. Project（.claude/settings.json）5. User（~/.claude/settings.json，最低）。
permissions 的规则求值顺序固定为 deny → ask → allow，first match wins（第一个命中的规则生效），所以 deny 永远压过 allow。
权限规则语法分两种：Tool 匹配该工具全部调用；Tool(specifier) 匹配特定模式，如 Bash(npm run *)、Read(./.env)、WebFetch(domain:example.com)。
大多数设置支持 live reload：文件一改就生效无需重启（permissions、hooks、apiKeyHelper、credential helpers 等），并对每个检测到的变化触发 ConfigChange hook。
少数设置需要重启或特定动作才生效：model 需用 /model 中途切换；outputStyle 在 /clear 或重启时重建 system prompt。
Managed 设置可由 MDM/OS 策略下发（macOS managed preferences、Windows 注册表、Linux/etc 等），并支持 managed-settings.d/ 目录下多个 *.json 按字母序合并。
env 里的环境变量会注入到每个 session 及其子进程；部分行为有版本差异（如 v2.1.143 起 NO_COLOR/FORCE_COLOR 传给子进程但不改 CLI 颜色）。

怎么配置

主配置文件路径（按 scope）：User=~/.claude/settings.json；Project=.claude/settings.json（提交 git）；Local=.claude/settings.local.json（gitignore）；Managed=系统级 managed-settings.json。Windows 上 ~/.claude 解析为 %USERPROFILE%\.claude。

典型 permissions 配置：
"permissions": {
  "allow": ["Bash(npm run lint)", "Bash(npm run test *)", "Read(~/.zshrc)"],
  "deny": ["Bash(curl *)", "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"],
  "ask": ["Bash(git push *)"],
  "additionalDirectories": ["../docs/"],
  "defaultMode": "acceptEdits",
  "disableBypassPermissionsMode": "disable"
}

建议加 $schema 获得编辑器自动补全与校验：
{ "$schema": "https://json.schemastore.org/claude-code-settings.json" }

另一批 UI/全局配置存在 ~/.claude.json（如 editorMode、autoScrollEnabled、showTurnDuration、teammateMode、autoConnectIde）。交互式修改用 /config 命令（含状态查看、模型/主题/effort/memory 等切换）。

什么时候用

团队共享、需进 git 的规则（统一 lint/test 白名单、deny 敏感文件读取）→ 放 Project 的 .claude/settings.json。
个人偏好、不想提交（本地 API key helper、个人 allow 规则）→ 放 Local 的 .claude/settings.local.json（已被 gitignore）。
跨所有项目的个人默认（model、editorMode、env）→ 放 User 的 ~/.claude/settings.json。
组织强制策略（禁用 bypass、限制登录方式、MCP 白名单）→ 用 Managed，普通用户无法覆盖。
纯 UI/会话偏好（主题、自动滚动、通知方式）→ 优先用 /config 命令交互修改，落到 ~/.claude.json。
别把需要团队一致的安全规则放 User scope——它优先级最低，会被项目/本地覆盖。

限制 / 坑

Managed 优先级最高且不可被任何 scope 覆盖；命令行参数仅做临时 session 覆盖。
permissions 求值 deny → ask → allow 且 first match wins：写了 allow 但又被 deny 命中，仍被拒绝。
model 改了不会热生效，需用 /model 切换；outputStyle 改了需 /clear 或重启才重建 system prompt。
includeCoAuthoredBy 已 Deprecated，应改用 attribution。
permission mode 中的 auto 在 project/local settings 里设置会被忽略（as of v2.1.142）。
cleanupPeriodDays 最小值为 1，默认 30；过期 session 文件在启动时删除。
部分设置有最低版本要求：skillOverrides 需 v2.1.129；maxSkillDescriptionChars / skillListingBudgetFraction 需 v2.1.105；disableRemoteControl 需 v2.1.128；policyHelper 需 v2.1.136+；parentSettingsBehavior 需 v2.1.133+。
Windows 下 managed 文件路径 C:\ProgramData\ClaudeCode\ 自 v2.1.75 起不再支持，改为 C:\Program Files\ClaudeCode\。
该官方页面不含「所有可用工具 + 是否需要权限」的完整工具表，工具名仅在权限示例里出现。

▸ 硬事实速查（24 条精确事实）

四个 scope 文件路径：User=~/.claude/settings.json；Project=.claude/settings.json（committed to git）；Local=.claude/settings.local.json（gitignored）；Managed=system managed-settings.json。
优先级（高→低）：1 Managed 2 Command line arguments 3 Local 4 Project 5 User。
Windows：~/.claude 解析为 %USERPROFILE%\.claude。
其他配置文件位置：Subagents 在 ~/.claude/agents/ 或 .claude/agents/；MCP servers 在 ~/.claude.json 与 .mcp.json；CLAUDE.md 在 ~/.claude/CLAUDE.md、CLAUDE.md 或 .claude/CLAUDE.md、CLAUDE.local.md。
API/认证 key：apiKeyHelper（/bin/sh 脚本，生成 X-Api-Key 与 Authorization: Bearer 头）、forceLoginMethod（"claudeai" 或 "console"）、forceLoginOrgUUID（UUID 字符串或数组）。
模型类 key：model、availableModels（如 ["sonnet","haiku"]）、modelOverrides（映射到 Bedrock ARN 等）、alwaysThinkingEnabled、effortLevel（"low"/"medium"/"high"/"xhigh"）。
env：注入每个 session 及子进程的环境变量；v2.1.143 起 NO_COLOR/FORCE_COLOR 传子进程但不改 CLI 颜色。
permissions 子字段：allow、deny、ask、additionalDirectories、defaultMode、disableBypassPermissionsMode、skipDangerousModePermissionPrompt。
权限规则语法：Tool 匹配全部；Tool(specifier) 如 Bash(npm run *)、Read(./.env)、WebFetch(domain:example.com)。求值顺序 deny → ask → allow，first match wins。
permission modes：default（每次询问）、acceptEdits（自动批准编辑）、plan（先展示计划）、auto（AI 分类器，project/local 设置时被忽略，as of v2.1.142）、dontAsk、bypassPermissions（跳过全部权限检查）。
memory 类：autoMemoryEnabled（默认 true，可用 /memory 或 env CLAUDE_CODE_DISABLE_AUTO_MEMORY 切换）、autoMemoryDirectory、claudeMd（Managed only）、claudeMdExcludes、cleanupPeriodDays（默认 30，最小 1）。
MCP 类：enableAllProjectMcpServers、enabledMcpjsonServers（如 ["memory","github"]）、disabledMcpjsonServers、allowedMcpServers/deniedMcpServers/allowManagedMcpServersOnly（Managed）。
hooks 类：hooks、disableAllHooks、allowManagedHooksOnly（Managed）、allowedHttpHookUrls（支持 * 通配）、httpHookAllowedEnvVars、statusLine（如 {"type":"command","command":"~/.claude/statusline.sh"}）。
凭据集成：awsAuthRefresh、awsCredentialExport（输出 JSON）、gcpAuthRefresh、otelHeadersHelper。
Git/署名：attribution（{"commit":...,"pr":...}）、includeCoAuthoredBy（已 Deprecated，默认 true）、includeGitInstructions、prUrlTemplate（占位符 {host}{owner}{repo}{number}{url}）。
UI/UX：spinnerTipsEnabled（默认 true）、outputStyle（如 "Explanatory"，/clear 或重启重建）、language、viewMode、showThinkingSummaries（默认 false）、autoUpdatesChannel（"stable"/"latest"）、minimumVersion。
存于 ~/.claude.json 的全局/UI 配置：editorMode（"normal"/"vim"）、autoScrollEnabled、showTurnDuration、terminalProgressBarEnabled、teammateMode、autoConnectIde、autoInstallIdeExtension、externalEditorContext、teammateDefaultModel。
Skills 类：skillOverrides（"on"/"name-only"/"user-invocable-only"/"off"，v2.1.129）、maxSkillDescriptionChars（默认 1536，v2.1.105）、skillListingBudgetFraction（默认 0.01=1%，v2.1.105）、disableWorkflows、disableSkillShellExecution。
关键环境变量：ANTHROPIC_MODEL、CLAUDE_CODE_EFFORT_LEVEL、CLAUDE_CODE_DISABLE_THINKING=1、CLAUDE_CODE_ENABLE_TELEMETRY（默认 1）、CLAUDE_CODE_DISABLE_AUTO_MEMORY、CLAUDE_CODE_USE_POWERSHELL_TOOL=1、CLAUDE_CODE_API_KEY_HELPER_TTL_MS、DISABLE_AUTOUPDATER、OTEL_METRICS_EXPORTER、CLAUDE_CODE_NO_FLICKER。
Managed 下发路径：macOS managed preferences domain com.anthropic.claudecode；Windows 注册表 HKLM\SOFTWARE\Policies\ClaudeCode（user 级 HKCU 最低优先级）；macOS /Library/Application Support/ClaudeCode/；Linux/WSL /etc/claude-code/；Windows C:\Program Files\ClaudeCode\（C:\ProgramData\ClaudeCode\ 自 v2.1.75 不再支持）；drop-in 目录 managed-settings.d/ 下 *.json 按字母序合并。
live reload 生效项：permissions、hooks、apiKeyHelper、credential helpers，并对每个变化触发 ConfigChange hook；需重启/特定动作项：model（用 /model）、outputStyle（/clear 或重启）。
$schema 校验地址：https://json.schemastore.org/claude-code-settings.json
worktree 配置：baseRef（"fresh"/"head"）、symlinkDirectories、sparsePaths、bgIsolation（"worktree"/"none"，v2.1.143+）。
sandbox 配置含 enabled、failIfUnavailable、excludedCommands，及 filesystem（allowWrite/denyWrite/denyRead/allowRead）与 network（allowedDomains/deniedDomains/allowLocalBinding 等）子块。

官方出处：https://code.claude.com/docs/en/settings

一次请求 = 一条线性的 token 序列

token 到底是什么

模型不读字符，读 token

真实切分长这样

官方经验值（用来估算，不是精确）

为什么这和"前缀逐字节相同"是同一件事

想看你自己文字的精确 token 数？

亲手打断前缀，看缓存怎么塌

命中 vs 未命中，逐 token 对比

例 A · 连续对话 → 大段命中

例 B · 改了开头一个字 → 前缀全废

"我第二轮说了一模一样的话，是完全命中吗？"

看第二轮请求的真实结构

5 分钟 TTL：算的是"请求间隔"，不是任务总时长

三个倍率：写 1.25× · 读 0.1× · 1 小时写 2×

换算成真实美元（你正在用的 Opus 4.8）

缓存生效的几条硬规则

缓存层级：tools → system → messages（级联失效）

这就是你本次会话每一轮的命中情况

从你这张表能直接讲明白的 4 件事

本会话 vs 你这个项目全部历史

你 10 个项目、95 个会话的缓存全景

各项目缓存读取量（条宽 ∝ 命中 token 数）

逐项目 · 逐会话明细（点击展开）

怎么在你自己的记录里查命中/不命中

Claude Code 里的两种查看方式

cache_control：手动标"缓存到这里"

subagent / Agent / 团队 / 后台 / Workflow 全解

一张总表（官方"并行运行 agent"的五种方式）

① subagent（子智能体）+ Agent 工具

② agent teams（代理团队）

③ background agents（后台代理 / agent view）

④ Workflow（动态工作流）

怎么选（一句话决策）

顺带：Workflow 续跑和 token 缓存是同一个道理

什么命中、什么作废（带真实依据）

Memory（CLAUDE.md / 记忆）

是什么

怎么工作

怎么配置

什么时候用

限制 / 坑

Skills（技能）

是什么

怎么工作

怎么配置

什么时候用

限制 / 坑

Hooks（钩子）

是什么

怎么工作

怎么配置

什么时候用

限制 / 坑

MCP（外部工具/数据）

是什么

怎么工作

怎么配置

什么时候用

限制 / 坑

Slash Commands（斜杠命令）

是什么

怎么工作

怎么配置

什么时候用

限制 / 坑

Plugins（插件）

是什么

怎么工作

怎么配置

什么时候用

限制 / 坑

Permissions（权限）

是什么

怎么工作

怎么配置

什么时候用

限制 / 坑

Settings（设置）

是什么