Claude Code 小课 · 2026年8月31日

2026-08-31 · 主题:新功能速用(--restricted 受限模式、按 agent 的 prompt cache TTL、模型切换 hooks、/cost 缓存可观测性) 覆盖版本:v2.1.248(2026-08-27)、v2.1.250(08-28)、v2.1.251(08-28) 前置:第 8 课(上下文管理)、第 9 课(权限与沙箱)、第 15 课(成本控制)、第 4 课(hooks)

上周末连发三个版本,其中两个带了真功能。这一课按「先看见 → 再调参 → 再设闸门 → 再收边界」的顺序,把 v2.1.248 / v2.1.251 里真正会改变你日常操作的四件事讲透。

先确认版本:

claude --version
# 低于 2.1.251 的话:
claude update

技巧 1(入门):用 `/cost` 的新缓存明细,先「看见」再谈优化

第 15 课讲成本控制时,我们只能从总 token 数倒推缓存效果——很不精确。v2.1.251 给 /cost 加了每会话的 prompt cache 明细行:命中率(hit ratio)、miss 次数、重新缓存的 token 数、以及这次是 warm 还是 cold。

# 会话里直接敲
/cost

看什么:

读到	说明	该做什么
hit ratio 高、misses 少	前缀稳定,缓存在干活	不用动
tokens re-cached 很大	前缀被反复重建,钱烧在「重新贴缓存」上	查是谁在改前缀(CLAUDE.md?MCP 工具列表?)
频繁 cold	会话间隔超过 TTL,或每次都换模型	见技巧 2 和技巧 3

顺带一个真实修复:v2.1.248 修掉了长会话里大约每小时一次的缓存 miss——原因是 OAuth token 刷新后工具定义被重新渲染,导致整段前缀失效。如果你以前观察到「长会话莫名其妙贵一截」,升级本身就是修复。

同一版还给 /usage 加了 Spend limit 进度条(面向走 Claude apps gateway 且设了支出上限的开发者),以及状态栏可读的 rate_limits.spend_limit 字段。

想把缓存指标钉在状态栏上,v2.1.251 也给了 prompt_cache 对象:

# ~/.claude/statusline.sh —— 状态栏脚本从 stdin 读 JSON
input=$(cat)
echo "$input" | jq -r '"cache \(.prompt_cache.hit_ratio // 0 | .*100 | floor)% | \(.model.display_name)"'

官方文档:Claude Code changelog · Status line 配置

技巧 2(进阶):`experimental.cacheTtl` —— 按 agent 分别设置缓存 TTL

v2.1.248 给 agent frontmatter 加了 experimental.cacheTtl,取值 "5m" 或 "1h",作用是:当没有配置全局 subagent TTL 设置时,这个 agent 用自己的 TTL。

为什么值得单独设:subagent 的调用节奏差别极大。一个「每轮都被叫一次」的 code-reviewer,5 分钟 TTL 完全够;一个「一天被叫三次、每次隔一小时」的 release-auditor,5 分钟 TTL 意味着每次都是 cold start,把整份长 system prompt + 工具定义重新贴一遍。

---
name: release-auditor
description: 发版前扫一遍 migration、feature flag 与回滚触发条件
tools: Read, Grep, Glob, Bash
model: sonnet
experimental:
  cacheTtl: "1h"
---

你是发版审计员。只读不写……

对照一组高频、短命的 agent 就保持默认:

---
name: quick-grep
description: 在仓库里找符号定义与调用点,只回结论
tools: Read, Grep, Glob
model: haiku
experimental:
  cacheTtl: "5m"
---

配好之后回到技巧 1:跑几轮再看 /cost,tokens re-cached 应该明显下降。先测量、再调 TTL、再测量——这是 cacheTtl 和 /cost 缓存行同一版本前后脚发布的原因。

注意:experimental. 前缀意味着字段名和语义仍可能变动,升级后建议 /doctor 确认没有报未知字段。官方文档:Subagents · changelog v2.1.248

技巧 3(进阶):`PreModelSwitch` / `PostModelSwitch` —— 给模型切换装闸门

v2.1.251 新增两个 hook 事件,可以拦截、要求确认、或只是记录一次模型切换。这补上了第 4 课 hooks 体系里长期缺的一块:此前你能约束「改什么文件」「跑什么命令」,却管不住「用哪个模型跑」。

三个立刻能用的场景:

(a) 记账——把每次切换写进日志,月底和 /cost 对账:

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cat >> ~/.claude/model-switches.jsonl"
          }
        ]
      }
    ]
  }
}

hook 从 stdin 收到 JSON 事件,直接追加成 JSONL,之后 jq 一把就能统计。

(b) 拦截——在受成本约束的项目里禁止切到最贵的档位。写成一个脚本,放 .claude/hooks/guard-model.sh:

#!/usr/bin/env bash
# 读 stdin 的事件 JSON;字段名以 /hooks 文档为准,这里做防御式匹配
payload=$(cat)
if grep -qi 'opus' <<<"$payload"; then
  echo "本项目预算封顶,禁止切到 Opus;需要请改 .claude/settings.json" >&2
  exit 2   # 退出码 2 = 阻止本次操作,stderr 会回给 Claude
fi
exit 0

{
  "hooks": {
    "PreModelSwitch": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-model.sh" }
        ]
      }
    ]
  }
}

(c) 感知重新缓存成本——同版本还改了 SessionStart 的 resume hook:它现在会收到会话陈旧度和预估的重新缓存成本。也就是说你可以在 --resume 一个放了很久的会话时,自动提示「这次恢复大约要重贴 X token,要不要改成 /clear 重开」。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "resume",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/stale-warn.sh" }
        ]
      }
    ]
  }
}

⚠️ 这两个事件是本周新增,事件 payload 的确切字段名请以 /hooks 与官方 hooks 文档为准,上面的脚本刻意用了「整包 JSON 做子串匹配」这种不依赖字段名的写法,先跑通再收紧。官方文档:Hooks 参考 · changelog v2.1.251

技巧 4(硬核):`--restricted` —— 审阅不可信代码时的最小权限壳

第 9 课讲权限与沙箱时,「我要 clone 一个陌生仓库让 Claude 读一遍」这个场景一直只能靠一堆 deny 规则拼。v2.1.248 直接给了一个开关:

claude --restricted
# 或
CLAUDE_CODE_RESTRICTED=1 claude

它一次性做了五件事:

移除执行命令/代码的内建工具(Bash 等)与 WebFetch——除非你在 --tools 里显式点名;
文件工具锁在工作目录内;
拒绝 bypassPermissions——这个模式下没有「全部放行」这个逃生口;
忽略用户 / 项目 / 本地设置文件——这一条最关键:陌生仓库里的 .claude/settings.json 无法给自己提权;
与 --tools 组合可以精确放行你确实需要的那几个。

典型用法——审阅一个刚 clone 的仓库,只允许读和搜:

git clone https://github.com/someone/unknown-repo /tmp/audit && cd /tmp/audit
claude --restricted --tools Read,Grep,Glob -p "通读这个仓库,列出所有会发起网络请求或执行子进程的位置,给文件名+行号"

配合第 12 课的无头模式,这就是一个可以放进 CI 的、不会被被审对象反向提权的审阅壳。

同一版还有两个配套的安全收紧值得知道(都属于「你不用做什么,但要知道边界变了」):

v2.1.251 修复了文件工具在权限检查通过后、符号链接被调包导致读写到批准目录之外的问题;Grep / Glob 现在也会对经符号链接到达的文件套用 Read(...) deny 规则;
项目级 .claude/settings.json 的 env 不再能设置 CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR、TMPDIR/TMP/TEMP —— 要设请放到 shell、用户级或 managed settings。老项目升级后如果发现临时目录变了,是这条改动。

官方文档:CLI 参考 · 权限与沙箱 · changelog v2.1.248 / v2.1.251

一句话总结

这三个版本的主线是「让你看见,再让你管住」:/cost 缓存明细和 /usage Spend limit 负责看见,experimental.cacheTtl、PreModelSwitch hooks 和 --restricted 负责管住。今天最值得先做的一件事:升级后敲一次 /cost,看看你的缓存命中率到底是多少。

下一课预告候选:/schedule 与 cloud routines、agent teams 的团队编排、Remote Control 实战。

技巧 1(入门):用 /cost 的新缓存明细,先「看见」再谈优化

技巧 2(进阶):experimental.cacheTtl —— 按 agent 分别设置缓存 TTL

技巧 3(进阶):PreModelSwitch / PostModelSwitch —— 给模型切换装闸门

技巧 4(硬核):--restricted —— 审阅不可信代码时的最小权限壳

一句话总结

技巧 1(入门):用 `/cost` 的新缓存明细,先「看见」再谈优化

技巧 2(进阶):`experimental.cacheTtl` —— 按 agent 分别设置缓存 TTL

技巧 3(进阶):`PreModelSwitch` / `PostModelSwitch` —— 给模型切换装闸门

技巧 4(硬核):`--restricted` —— 审阅不可信代码时的最小权限壳