附录 A：核心概念速查与常见坑精选
A.1 一句话速查
- Agent SDK：把 Claude Code 的自动驾驶打包成库。
- Agent Loop：想—做—看 的循环，直到干完。
- session_id：记忆钥匙，存它才能 resume。
- MCP：给 Agent 装外挂的标准协议。
- Hook：在 Agent 每一步插进你的代码。
- 子代理：一个 Agent 指挥一队专精 Agent。
- 沙箱：把 Agent 关进 OS/内核层的笼子，防 prompt injection 乱来。
- 凭证代理：API Key 不进 Agent 边界，由边界外的代理注入。
- OpenTelemetry：生产可观测性的标准出口，导出到任意 OTLP 后端。
A.2 配置项速查
| 选项 |
作用 |
model |
opus/sonnet/haiku 或完整 ID |
maxTurns |
工具调用轮次上限 |
maxBudgetUsd |
花费上限（保险丝） |
allowedTools |
免审批工具白名单（不影响 bypassPermissions） |
disallowedTools |
危险工具黑名单（优先于模式，bypassPermissions 也拦） |
permissionMode |
审批策略（default/acceptEdits/plan/dontAsk/bypassPermissions） |
settingSources |
加载 .claude/ 配置的来源 |
mcpServers |
自定义/外部 MCP 服务器 |
hooks |
工具执行前后回调 |
agents |
子代理定义 |
effort |
每轮思考深度 |
cwd |
工作目录（决定文件操作根，指向带 .claude/ 的目录） |
resume |
续接会话（传 session_id） |
sessionStore |
会话镜像到 S3/Redis/Postgres（多机 resume 必备） |
env |
注入子进程环境变量（OTel、缓存 TTL、代理等） |
A.3 常见坑精选（来自官方 25 条）
- 自定义工具名带前缀
mcp__<server>__<tool>。
settingSources 默认空，必须显式设。- Hook 的 matcher 是正则，用
Write|Edit 不是 glob。
- V2 API 名字以
unstable_v2_ 开头，可能变。
cwd 决定文件操作根目录，指向带 .claude/ 的目录。- 传
abortController 才能取消。
- 流式输入必须是
{ type: 'user', message: {...} } 形状。
- V1 resume 要从
system/init 和 result 都抓 session_id。
- 遍历 assistant 内容要处理
tool_result 块。
.env 可能被系统变量覆盖，用 override: true。
A.4 阅读指南
| 时间 |
章节 |
目标 |
| Day 1 |
§01-§03 |
从零跑通第一个会修 bug 的 Agent |
| Day 2-3 |
§04-§07 |
看懂 Loop、消息、权限、会话 |
| Day 4-5 |
§08-§10 |
接 MCP、用子代理、上生产 |
| Day 6 |
附录 A |
当速查表反复翻 |
标叔出品 · AI Native Coder · 独立开发者
公众号「标叔」| B站「Liangdabiao」