Skip to main content
核心概念

工作原理

两种 SDK 都在本地 qodercli 进程中运行 Agent。SDK 与 qodercli 通过 JSONL 交换消息和控制请求；qodercli 调用模型服务并执行经过授权的工具。

整体架构

+----------------------------- 应用 --------------------------------+
|  TypeScript query()                 Python query() / SDK Client   |
|                    消息解析、回调、会话控制                        |
+-------------------------------+-----------------------------------+
                                |
                    本地 stdin/stdout JSONL
                                |
+-------------------------------v-----------------------------------+
|                        qodercli SDK 模式                           |
|  协议与会话  ->  Agent 循环  ->  权限检查与工具执行                |
+--------------------------+----------------------+------------------+
                           |                      |
                         模型请求                本地执行
                           |               文件 / 命令 / MCP
                           v                      |
                    Qoder 模型服务                |
                           |                      |
                           +------ 执行结果 -------+
一个本地运行会话由一个 qodercli 进程承载。使用字符串调用 query() 时，通常会在最终结果产生后关闭该会话；多轮 API 会保持进程运行，等待应用继续发送输入。

启动与握手

默认本地会话按以下顺序启动：
  1. 选择运行时。 如果显式指定了 qodercli 路径，SDK 使用该路径；否则查找随安装包提供的兼容运行时或环境中可用的运行时。
  2. 启动 SDK 模式。 SDK 以结构化流式输入和输出模式启动 qodercli。进程使用配置的工作目录和环境变量。
  3. 传递认证信息。 SDK 解析所选认证方式，通过临时的一次性认证载荷把认证信息交给 qodercli，不把凭据写入消息流。
  4. 初始化能力。 发送第一条任务前，SDK 与 qodercli 通过 initialize 控制请求完成握手。SDK 在此阶段注册 Hooks、Agent、Skills 和进程内 MCP 服务；qodercli 返回运行时能力和可用资源。
  5. 发送任务。 初始化成功后，SDK 发送第一条用户消息，并开始向应用产出 qodercli 消息。
初始化失败会在任务运行前返回，因此应用可以把配置或认证问题与 Agent 执行失败区分开。

SDK 与 qodercli 如何通信

默认进程 Transport 使用 JSON Lines（JSONL）：一行对应一个 JSON 协议对象。SDK 已经负责读写和解析该数据流，应用应使用带类型的 SDK 消息，不要直接解析进程输出。 
应用
 |
 | SDK 写入 qodercli stdin
 |   用户消息
 |   控制请求和对应的控制响应
 v
qodercli
 |
 | qodercli 写入 stdout
 |   system、assistant、task、hook、result 消息
 |   启用后输出增量 stream event
 |   控制请求和对应的控制响应
 v
SDK 消息迭代器

qodercli stderr --------------------> 诊断信息（不属于协议数据）
协议流量分为两类：
  • Agent 消息承载用户输入、Agent 文本、工具活动、进度以及最终结果。
  • 控制消息处理初始化、中断、会话操作、权限决策、Hooks 和进程内 MCP 调用。每个控制响应通过 request_id 与请求对应，因此可以安全地区分同时进行的多个操作。
控制请求可以由任一方发起。SDK 可以要求 qodercli 中断当前任务；qodercli 可以要求应用审批工具或执行 SDK 侧 Hook。SDK 会把收到的请求路由到相应回调，再把回调结果发送给 qodercli。

qodercli 的 Agent 循环

qodercli 会反复请求模型，直到任务完成或达到配置限制。前一次循环的工具结果会成为下一次模型请求的上下文： 
用户任务 + 对话历史 + 指令 + 工具定义
                    |
                    v
              构造下一次模型请求
                    |
                    v
                流式模型输出
                    |
             +------+-------+
             |              |
          文本内容         工具调用
             |              |
       输出 Agent 事件   检查策略和 Hooks
                            |
                         执行工具
                            |
                    把工具结果加入历史
                            |
                            +------> 下一次循环

               模型不再调用工具
                    |
                执行结束 Hooks
                    |
                 输出最终结果
  1. 构造上下文。 qodercli 组合当前任务、对话历史、系统指令、工作区配置、可用工具和相关 Hook 上下文。
  2. 请求模型。 模型输出以流式方式返回。文本可以立即输出，完整的工具请求会进入执行链路。
  3. 授权操作。 qodercli 依次应用工具可用范围、允许/询问/拒绝规则、权限回调和工具执行前 Hooks。被拒绝的工具不会执行，而是生成说明拒绝原因的工具结果。
  4. 执行工具。 运行时调度经过批准的内置工具、MCP 工具或子 Agent，并收集结果；在安全的情况下，互不依赖的工具调用可以并发执行。
  5. 带着证据继续。 工具结果加入对话，模型通过下一次循环检查结果并决定下一步。
  6. 完成或停止。 当模型不再调用工具且结束 Hook 接受结果时正常完成；达到配置限制、发生中断、取消或错误时也会停止。
模型本身不会直接打开文件或启动进程。模型只提出工具调用，由 qodercli 决定是否执行以及如何执行。

工具、MCP 与子 Agent

qodercli 只向模型提供当前会话可用的工具：
  • 内置工具用于读取和修改文件、搜索项目、运行命令以及执行其他本地操作。
  • MCP 工具可以来自外部 MCP 服务，也可以来自 SDK 应用托管的进程内 MCP 服务。调用进程内服务时，qodercli 向 SDK 发送 MCP 控制请求，SDK 调用已注册服务，再通过同一控制通道返回响应。
  • 子 Agent使用独立的提示词和上下文执行委派任务，通常只拥有更窄的工具范围；最终输出作为工具结果返回主 Agent。
工具结果既会成为后续模型上下文，也会成为 SDK 事件。结果过大时，运行时可能缩短对话中的内容，同时保留足够的信息供 Agent 继续处理。

上下文与会话状态

qodercli 保存实时对话状态；SDK 保存应用回调，并把协议对象转换为 TypeScript 或 Python 消息类型。 随着会话增长，qodercli 会监控模型上下文用量。必要时，它会在下一次模型请求前压缩较早的历史，让长任务能够继续，而不要求应用重新构造提示词。不过，重要信息仍应写入文件或显式会话状态，不应依赖无限的对话记忆。 启用会话持久化后，qodercli 可以保存 Transcript 并在以后恢复。详见会话存储和Checkpoint。

完成、错误与取消

应用应持续消费消息，直到收到 result，或迭代器抛出错误。
  • Agent 一轮任务的成功或失败由最终 result 消息总结，其中包含状态和可用的用量信息。
  • interrupt 会要求 qodercli 停止当前任务；在支持的长会话中，会话本身仍可继续使用。
  • 关闭或中止 SDK 消息流会关闭 Transport。进程 Transport 会先尝试优雅退出，qodercli 未退出时再升级终止方式。
  • 进程启动失败、协议消息无效、运行时丢失或初始化超时会表现为 SDK 错误，而不是 Agent 的最终结果。
公开控制 API 见会话控制，用量字段见成本与用量。

安全与数据流

SDK 和 qodercli 位于同一台机器，并不表示整个任务只在本机处理。 
本地应用 <-------- 本地协议 --------> qodercli
                                       |
                                       +----> Qoder 模型服务
                                       |      任务上下文和执行结果
                                       |
                                       +----> 本地或已配置工具
                                              可能产生真实副作用
  • 认证信息通过临时载荷独立传给 qodercli，不进入 JSONL 消息流；SDK 会清理该载荷。
  • qodercli 会把推理所需的任务上下文发送给模型服务，其中可能包含任务文本、文件片段和工具结果。
  • 工具在 qodercli 所在环境运行，可以按配置读取、写入或调用其他系统。
  • cwd、工具白名单、权限规则、Hooks、沙箱和基础设施隔离是互补的控制措施，应根据任务可能造成的影响组合配置。
审批模式和权限策略见权限控制，生命周期拦截方式见 Hooks。

TypeScript 与 Python 的会话形态

两种 SDK 共享运行时协议，但提供符合各自语言习惯的会话 API：
场景TypeScriptPython
一条任务、一个结果query({ prompt: string, ... })query(prompt=..., options=...)
多条用户消息向 query() 传入异步消息迭代器连接 QoderSDKClient 并再次调用 query()
读取输出使用 for await 遍历可辨识联合消息使用 async for 遍历带类型消息对象
运行时控制调用 query 消息流上的方法调用 QoderSDKClient 方法

下一步

快速开始
核心概念
对话与会话
扩展能力
控制与可观测性
参考