先画边界：我们能从 Claude Agent SDK 看见什么

返回 Claude 课程地图

课程地图已经追到了公开 SDK 与 CLI 交接的地方，这一篇先把边界说清楚，看每类证据到底能支持哪些结论。

学习 Claude Agent Harness（智能体框架）时，第一道难关并不在代码，而是别把几个不同的对象写成同一件事。日常交流里，人们常把 Claude 模型、Claude Code、Agent SDK 和自己的 Python 应用都叫作 Claude，但你若带着这种简称去读源码，就很容易引错证据，最后把结论也写错。

四个对象分别是谁

你的 Python 应用
  → Claude Agent SDK（本课程可读源码）
  → Claude Code CLI（公开产品，内部实现不在本仓库）
  → 模型服务与执行环境

• Claude 模型负责根据上下文生成文本或工具请求。
• Claude Code是承载 Agent 行为的产品运行时，包含 CLI 表面，但主体实现不是本课程锁定的开源源码。
• Claude Agent SDK让应用启动或连接 CLI，发送消息，接收类型化事件，并处理公开控制协议。
• 你的应用决定怎样配置 SDK、实现权限回调和 Hooks、保存产物以及独立评测结果。

因此，「Python SDK 里有一个 Query 类」只能证明 Python SDK 怎样路由协议，不能证明 Claude Code 内部也有同名类。同理，即使官方文档说 SDK 提供 Agent Loop（智能体循环），你也不能拿这项公开契约去补画闭源循环的源码调用图。

两套 SDK 的证据并不对称

Python Agent SDK 锁定在提交 542fefb3b94be87760b2513fff889b91bb5b6672。这个仓库里有 query.py、client.py、内部 Transport（传输层）、消息解析、控制协议和测试，我们可以沿着 Python 真正走过的调用链一站站读下去。

• Python 公开入口
• Python 内部 Client
• Python 控制协议

TypeScript Agent SDK 锁定在提交 48275071e804139579fabada9bb8d90cfe02b062。当前锁定的仓库只公开了 README、CHANGELOG、许可证和 Session Store（会话存储）示例，我们看不到 SDK 主体运行时的源码，也就无法沿着它的内部实现继续追踪。这门课可以讲它公开承诺的 API 和看得见的示例，但不会装作已经读过其内部实现：查看锁定 README。

「没有看到源码」有明确的范围：这句话只针对当前锁定的 Git 树，不能外推到 npm 分发包、其他仓库、私有实现或未来版本。

怎样判断一句话能不能写进源码课程

先看这句话说的到底是谁，再根据对象去找能够直接支持它的证据。

句子想说明什么	首选证据	合理写法
产品公开支持什么	官方文档和公开 API 契约	「官方文档说明……」
Python SDK 在该版本怎样运行	锁定源码与测试	「Python SDK 在此提交中……」
某配置下实际发生什么	固定版本的复现实验	「在这些条件下观察到……」
TypeScript 内部怎样实现	当前证据不足	明确未知和所需证据
Claude Code 内部怎样调度	当前证据不足	保留产品边界，不补想象图

例如，下面这句话不能直接发布。

Python 与 TypeScript SDK 内部都由同一个 Query 控制器驱动 Claude Code。

这句话一口气跨过了三个对象，可我们能从这三处拿到的证据并不对等：锁定的 Python 源码只能证明 Python 入口把工作交给了内部 Client，TypeScript 锁定树里又没有主体实现，Claude Code 的内部运作则仍在产品边界之内。把这些限制一起写清楚，句子才能改成下面这样。

两套 SDK 都公开了查询表面，但只有 Python 锁定源码可以核对其 Client、Transport 与控制协议链路。当前 TypeScript 锁定树无法证明内部实现与 Python 同构，因此也不能据此推断 Claude Code 内部对象图。

从最小入口练习边界判断

Python 的公开 query() 最后几行非常简单，代码如下。

if options is None:
    options = ClaudeAgentOptions()

client = InternalClient()
async for message in client.process_query(
    prompt=prompt, options=options, transport=transport
):
    yield message

源码：查看完整入口

这段代码能支持三个结论：入口会在没有 Options 时补上默认值，然后实例化 InternalClient，并从 process_query() 异步取出消息。但这几行还没有走到后面的模型循环和工具执行，因此你不能据此断定「这里已经实现了模型循环」「每条工具调用都由这个函数执行」或「CLI 内部也使用 InternalClient」。

读源码的价值，在于弄清这几行改变了哪些状态、下一步应该去哪里，以及哪些问题到了这里仍然没有答案。

官方文档与源码冲突时怎么办

在线文档说的是当前对外公开的契约，锁定源码记录的则是某个历史提交。两者对不上时，别急着拿其中一个覆盖另一个，而要把版本和证据来源一起交代清楚：

1. 写明文档页面和访问日期；
2. 写明源码提交；
3. 判断差异是版本漂移、语言 SDK 差异，还是理解错误；
4. 在没有同版本证据前并列描述。

许可证也得逐个仓库处理，因为 Python 仓库里的 MIT 许可不会自动覆盖 TypeScript 仓库或 Claude Code 产品。几份材料的技术接口即使看起来相似，授权范围也仍然可能完全不同。

本课程之后怎样标注边界

后续文章遵循三种明确语气：

• 源码事实：给出锁定提交、文件和行号，追踪调用者、输入、状态变化、返回和下一站。
• 机制解释：用课程自己的图或伪代码帮助理解，并明确它是抽象，不伪装成上游类图。
• 产品边界：到公开 SDK 无法继续进入的地方停止，不用熟悉的设计模式填空。

边界清楚了，下一篇就只沿着锁定的 Python 源码往里走：从公开入口进入 InternalClient，再看 Transport 和控制协议怎样接上 CLI。

下一篇开始走真实主链：Python 入口、Transport 与双向控制。