2026-04-24 学习日志

今日主题

ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU_MODEL 是能力层别名，代码不写死具体 model ID，而是调用 getDefaultSonnetModel() 等函数表达我需要中等能力，实际 ID 由环境变量在运行时注入。这让同一份代码对 1P/3P 用户都能工作。
ANTHROPIC_SMALL_FAST_MODEL 专门给后台轻量任务用（hooks、away 摘要、web 搜索辅助等），本质是 getDefaultHaikuModel() 的覆盖，语义是最快最便宜即可。
1M context 不是独立 model ID，而是在 model 名后加 [1m] 后缀（如 opus[1m]）触发：内部把 context window 设为 1_000_000，发 API 前 normalizeModelStringForAPI() 会 strip 掉这个后缀。CLAUDE_CODE_DISABLE_1M_CONTEXT=true 可全局禁用。
ANTHROPIC_MODEL 控制主对话模型，CLAUDE_CODE_SUBAGENT_MODEL 强制覆盖所有 subagent 模型（不设则 subagent 默认 inherit 父模型）。两者都支持语义别名（opus/sonnet/haiku）和具体 model ID，别名会经 parseUserSpecifiedModel() 展开。
1P(First Party) = 直接用 api.anthropic.com；3P(Third Party) = AWS Bedrock / Google Vertex / Azure Foundry。3P 的 model ID 格式不同（如 anthropic.claude-sonnet-4-5-v1:0），这套能力层抽象让 3P 用户只需配环境变量，内部代码无需修改。

模型配置分两个维度：别名映射（opus/sonnet/haiku 指向哪个具体 ID）和使用场景（主循环/子 Agent/小任务各用什么模型），二者正交。
ANTHROPIC_SMALL_FAST_MODEL 与 ANTHROPIC_DEFAULT_HAIKU_MODEL 不是同义词：前者优先级更高，可以是任意模型；后者只影响 haiku 别名解析，并作为前者的 fallback。
别名（opus/sonnet/haiku/best/opusplan）可在 7 个地方使用：--model 参数、ANTHROPIC_MODEL 等环境变量、settings.json model 字段、availableModels 白名单、/model 命令、Skill frontmatter model:、Agent Tool model 参数。
availableModels 白名单中的家族别名（opus/sonnet/haiku）具有通配语义，但一旦同时存在更具体的版本条目（如 opus-4-5），通配失效，只允许该具体版本。
best 别名硬编码等于 getBestModel() → getDefaultOpusModel()，无法单独配置，只能通过 ANTHROPIC_DEFAULT_OPUS_MODEL 间接影响。

Mac 上有三级 tmp：/tmp（系统级，所有用户共享，符号链接到 /private/tmp）、$TMPDIR（用户级，由 launchd 管理，路径形如 /var/folders/.../T/，重启后可能变化）、/private/tmp（/tmp 的真实目标）。
Python 的 tempfile.gettempdir() 在 Mac 上优先返回 $TMPDIR，而非 /tmp，因此结果是 /var/folders/... 而不是 /tmp。

Hook 文件放在 hooks 目录不会自动生效，必须在 settings.json 的 hooks 字段显式注册：指定触发时机（PostToolUse / PreToolUse / Stop）、matcher（正则匹配工具名）和 command。
Hook 脚本通过 stdin 接收工具调用的完整 JSON 数据（包含 tool_name、tool_input 等字段），可据此做条件判断和上报。
配置可放在项目级（.claude/settings.local.json）或全局（~/.claude/settings.json），脚本文件本身放哪里无所谓，只要 command 路径正确即可。

ReAct 循环在 AI SDK 中只需一个参数 maxSteps，不需要自己写循环。模型自动决定何时调用工具、工具结果自动回传给模型、循环直到模型认为任务完成或达到步数上限。
AI SDK 的架构分为三层：流式传输层（pipeUIMessageStreamToResponse）、业务拦截层（onStepFinish/onFinish 回调）、工具定义层（tool() 包装普通函数）。三层互不干扰，落库/审计只需在回调里做，不影响流式输出。
前端通过 message.parts 获得结构化数据，每个 part 有明确 type（text/tool-invocation/reasoning 等），按 type 分发渲染即可，不需要解析原始流。tool-invocation 包含 state（call/result）可区分执行中与已完成。
AI SDK 适合单 Agent + 工具调用 + 自定义业务场景。不覆盖的部分：多 Agent 编排、复杂任务分解、上下文窗口管理、权限控制——这些需要自己构建调度层。