TypeScript 查询 SDK

使用 query 消费结构化消息，选择 CLI、会话身份和系统提示。

This page has not been translated into English yet. The original Chinese version is shown below.

@qwen-code/sdk 提供实验性的 TypeScript 程序接口。要求 Node.js 22.0.0 或更高版本；官方列出的 CLI 最低要求是 0.4.0 stable，SDK 默认使用随包 CLI，只有需要自定义版本时才指定 executable。

安装和最小查询

npm install @qwen-code/sdk

import { query, isSDKAssistantMessage, isSDKResultMessage } from '@qwen-code/sdk';

const result = query({
  prompt: 'Explain the project structure.',
  options: { cwd: '/path/to/project' },
});

for await (const message of result) {
  if (isSDKAssistantMessage(message)) {
    console.log(message.message.content);
  } else if (isSDKResultMessage(message)) {
    console.log(message);
  }
}

先把 cwd 换成实际项目，确保模型认证可用。assistant content 是结构化内容，不应无条件当成纯字符串；result 消息与中间 assistant 消息也应分开处理。其他 type guards 包括 isSDKUserMessage、isSDKSystemMessage、isSDKPartialAssistantMessage。

QueryOptions

字段	默认或用途
cwd	默认 process.cwd()，决定文件和命令上下文
model	显式值优先于 OPENAI_MODEL、QWEN_MODEL
pathToQwenExecutable	默认随包 CLI；可指定 PATH 名、绝对路径、.js bundle、node: 或 bun: 前缀
env	覆盖并合并到当前进程环境，不是完全替换环境
permissionMode	默认 default；还有 plan、auto-edit、auto、yolo
maxSessionTurns	默认 -1 不限，必须为整数
includePartialMessages	默认 false，开启后提供生成中的消息
debug	默认 false，控制 CLI 诊断输出
agents	配置可调用 subagent
authType	传给 CLI 的认证类型选择

authType 的历史类型包括 qwen-oauth，不应将类型仍存在理解成对应免费登录仍可用于新环境。认证现状见配置说明。权限和工具选择另见控制与权限。

会话身份与多轮

prompt 可是字符串，或 AsyncIterable。后者的消息含 type: user、session_id、message.role/content 和 parent_tool_use_id，可按应用输入顺序供给多轮消息。

options.resume 用已保存的会话 ID 恢复历史，sessionId 为新会话指定身份，不表示恢复。通过 Query.getSessionId() 保存实际 ID。不要用会话名代替 UUID 或把相同 ID 的重复创建当作可靠重试；daemon 另有创建身份契约。

maxSessionTurns 的一轮包含用户消息与助手响应。对话结束、主动中断一轮和关闭整个查询不同；应按应用生命周期清理 Query。

替换或追加系统提示

字符串 systemPrompt 完全替换内置 Qwen Code 系统提示。希望保留内置行为时，使用 preset 并 append：

const options = {
  systemPrompt: {
    type: 'preset' as const,
    preset: 'qwen_code' as const,
    append: 'Be concise and distinguish facts from assumptions.',
  },
};

该对象可传给 query 的 options。不要把“追加说明”和“替换全部系统提示”混为同一配置效果。