Qoder Agent SDK 提供 TypeScript、Python 和 Java 三个语言版本。三者共用同一套 CLI 运行时协议，Agent 循环、工具、权限、Hooks、会话和 MCP 等核心能力一致；API 签名、类型定义和命名风格各自遵循所在语言的习惯（TypeScript 和 Java 为 camelCase，Python 公共 options 为 snake_case）。TypeScript 与 Python 的能力面基本相同，Java 的能力面较窄，部分选项只在一两种语言中提供，参见下方语言差异。完整 API 参考按语言分开维护：
TypeScript 与 Python 的选项绝大多数一一对应，Java 缺少其中一部分。以下列出差异，各语言的参考页仍是其自身能力面的权威来源。
以下能力 Python 没有。
以下能力在 TypeScript 或 Python 中提供，Java 没有对应的选项或方法。
以下能力三种语言都有，但 Java 的行为不同：
三个 SDK 的核心 API 对照如下，方便跨语言迁移：
各功能页已合并多语言示例，可在代码块内切换 TypeScript / Python / Java。Java 没有对应能力的小节，在标题或页首标注了适用语言：
按语言查看
| 语言 | 参考页 | 包名 |
|---|---|---|
| TypeScript | SDK References - TypeScript | @qodercn-ai/qodercn-agent-sdk |
| Python | SDK References - Python | qodercn-agent-sdk |
| Java | SDK References - Java | cn.qoder.sdk:qodercn-agent-sdk |
语言差异
TypeScript 与 Python 的选项绝大多数一一对应，Java 缺少其中一部分。以下列出差异，各语言的参考页仍是其自身能力面的权威来源。
仅 TypeScript
| 能力 | 选项或方法 | 说明 |
|---|---|---|
| 内置工具行为 | toolConfig | 调整内置工具的行为，参见工具 |
| 会话持久化控制 | persistSession、resumeSessionAt、resumeDropsTurn | 细粒度控制恢复会话时加载和保留的内容 |
| 提示建议 | promptSuggestions | 接收建议的后续提示词 |
| Goal 最大轮次 | goalMaxTurns、setGoalMaxTurns() | 配置后续 Goal 且不修改当前 Goal，参见 TypeScript 参考 |
| 模型请求调整 | modelRequestPatches | 调整发出的模型请求 |
| 自定义传输与进程控制 | transport、spawnQoderCLIProcess、executable、executableArgs | 替换运行时的启动或连接方式 |
仅 Python
| 能力 | 选项 | 说明 |
|---|---|---|
| 从文件加载系统提示词 | system_prompt={"type": "file", "path": ...} | 参见从文件加载提示词 |
| MCP 认证回调 | on_mcp_oauth_required | 服务需要 OAuth 时的入向回调；TypeScript 通过运行时方法完成同类能力 |
| MCP 状态回调 | on_mcp_status_change | 服务状态变化的入向回调 |
| 读取缓冲上限 | max_buffer_size | 限制传输层读取缓冲区大小 |
TypeScript 与 Java
以下能力 Python 没有。
| 能力 | TypeScript | Java | 说明 |
|---|---|---|---|
| Hook 事件进入消息流 | includeHookEvents | includeHookEvents(boolean) | 在消息流中投递 Hook 生命周期事件，不影响 Hook 回调本身 |
Java 暂不提供
以下能力在 TypeScript 或 Python 中提供，Java 没有对应的选项或方法。
| 能力 | TypeScript / Python 入口 | Java 的情况 |
|---|---|---|
| 子 Agent 定义 | agents | 没有对应选项，参见子 Agent |
| 插件 | plugins | 没有 plugins 选项；reloadPlugins() 不返回插件列表，参见 Plugins |
| Skills 与设置来源 | skills、settingSources | 只支持单条消息选择 Skill 和 reloadSkills() |
| 代码安全扫描 | securityScan / security_scan | 没有对应选项，参见代码安全扫描 |
| 用量与上下文查询 | getContextUsage()、getUsageInfo() 等 | 只有 ResultMessage.usage() 提供本轮的输入、输出 token 数，参见成本和用量 |
| settings 与输出风格 | settings、输出风格设置 | 参见用 settings 提供权限规则、单独调整输出风格 |
| 会话内更新权限 | PermissionUpdate | 用 PermissionResult.allow().withScope(PermissionScope.SESSION)，参见PermissionScope |
| 外部授权工具、MCP Tool Policy | permissionPromptToolName、MCP Tool Policy | 参见权限控制 |
| 启动时的额外目录 | additionalDirectories / add_dirs | 没有启动选项；会话建立后可调用 QoderSession.addDirectories(List<Path>) 添加，参见访问额外目录 |
| 认证失败回调 | onAuthExpired / on_auth_expired | 捕获错误码为 CLI_AUTH_FATAL 的 AuthenticationException，参见认证失败回调 |
| 自定义工具封装 | tool()、createSdkMcpServer() | 实现 InProcessMcpHandler，参见 MCP 集成 |
| 严格 MCP 配置 | strictMcpConfig / strict_mcp_config | 没有对应选项 |
| 运行时切换模型 | 固定模型模式下切换当前模型 | 没有对应方法，参见模型选择 |
| 指定新会话 ID | sessionId | 会话 ID 由 CLI 分配，从 initialization() 读取，参见会话控制 |
| 外置会话存储的读取超时与写入策略 | loadTimeoutMs、sessionStoreFlush | 用 sessionMirrorOptions(...) 设置镜像的批量和等待上限，参见外置会话存储 |
| 会话重命名、打标签和导入 | renameSession() 等函数 | 没有对应函数 |
| stderr 回调 | stderr | CLI 异常退出时用 CliProcessException.getStderrTail() 读取 stderr 尾部 |
Java 行为差异
以下能力三种语言都有，但 Java 的行为不同：
- CLI 运行时：Java SDK 不随包携带 CLI，首次启动时下载本版本锁定的 CLI 并缓存复用，参见托管 CLI（Java）。
- 认证：认证在
QoderClient.Builder.auth()上配置，同一客户端创建的会话共用。Auth.accessTokenEnv()只读取 JVM 进程的环境变量，不读取putEnvironment()传入的变量。 - 子进程环境：CLI 子进程默认只继承
PATH，其他变量要显式传入，参见子进程环境（Java）。 - 工具列表：
tools(空列表)等同于未设置，交给 CLI 默认，不能用空列表禁用全部工具，参见工具。 - 输入优先级：
UserInput默认优先级为NOW，参见多轮对话。 - 运行时控制：切换权限模式、MCP 管理、回滚等运行时方法只在
QoderSession上提供，一次性查询的QoderQuery没有。 - 外置会话存储：恢复时找不到外部记录会直接失败，不回退到 CLI 本地存储，参见外置会话存储。
- 模型选择回调超时：不会以异常交给应用，用诊断监听器识别，参见SDK 异常。
命名对照
三个 SDK 的核心 API 对照如下，方便跨语言迁移：
| 能力 | TypeScript | Python | Java |
|---|---|---|---|
| 一次性查询 | query() | query() | QoderClient.query() |
| 多轮会话 | query() + 异步消息流 | QoderSDKClient | QoderClient.openSession() + QoderSession.send() |
| 会话 options | Options（query({ options })） | QoderAgentOptions | SessionOptions（SessionOptions.builder()） |
| 认证：环境变量 PAT | accessTokenFromEnv() | access_token_from_env() | Auth.accessTokenEnv() |
| 认证：直接传 PAT | accessToken() | access_token() | Auth.accessToken(SecretValue) |
| 认证：Service Account | serviceAccount() | service_account() | Auth.serviceAccountKey() / Auth.serviceAccountTokenProvider() |
| 认证：本机登录态 | qodercliAuth() | qodercli_auth() | Auth.qoderCli() |
| 自定义工具 | tool() | @tool() 装饰器 | 在 InProcessMcpHandler 中实现 tools/list、tools/call |
| 进程内 MCP server | createSdkMcpServer() | create_sdk_mcp_server() | McpServerConfig.inProcess() |
| 权限回调 | canUseTool | can_use_tool | canUseTool(ToolPermissionHandler) |
| 中断当前回复 | q.interrupt() | client.interrupt() | query.interrupt() / session.interrupt() |
| 文件回滚 | q.rewindFiles() | client.rewind_files() | session.rewindFiles() |
| MCP 状态查询 | q.mcpServerStatus() | client.get_mcp_status() | session.mcpServerStatus() |
| 初始化结果 | q.initializationResult() | client.get_server_info() | initialization() |
| 上下文用量 | q.getContextUsage() | client.get_context_usage() | — |
| 账号与会话用量 | q.getUsageInfo() | client.get_usage_info() | — |
注意：Python 的AgentDefinition、hooks 输出、settings 等协议层结构沿用线路协议的 camelCase 字段名（如maxTurns、hookSpecificOutput），与公共 options 的 snake_case 不同，详见各功能页说明。