跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

query() 有两种输入模式：
  • 单消息查询模式：一次提交一条用户消息，SDK 完成本轮回复后关闭会话。见 快速开始。
  • 多消息会话模式：保持会话开启，和模型进行多轮对话。

​
多消息会话

定义一个按顺序产出用户消息的序列： 
import { qodercliAuth, query, type SDKUserMessage } from '@qoder-ai/qoder-agent-sdk';

async function* messages(): AsyncGenerator<SDKUserMessage> {
  yield {
    type: 'user',
    message: { role: 'user', content: [{ type: 'text', text: 'Analyze this codebase for security issues' }] },
    parent_tool_use_id: null,
  };

  // 中间可以等待任意外部条件再产出下一条
  await new Promise((resolve) => setTimeout(resolve, 2000));

  yield {
    type: 'user',
    message: { role: 'user', content: [{ type: 'text', text: 'Now write a short report' }] },
    parent_tool_use_id: null,
  };
}

for await (const msg of query({
  prompt: messages(),
  options: {
    auth: qodercliAuth(),
    allowedTools: ['Read', 'Grep'],
  },
})) {
  if (msg.type === 'result' && msg.subtype === 'success') {
    console.log(msg.result);
  }
}
模型每收到一条用户消息回一轮，消息序列结束后会话自动关闭。消息字段定义见 SDKUserMessage。

​
管理会话生命周期

多消息会话下，query() 返回对象的生命周期由调用方掌握。SDK 只会在消息序列自然结束时顺带关闭会话；其余情况都需要调用方主动决定何时收尾，否则会话会一直挂着。 常见的需要调用方主动管理的场景：
  • 消息序列本身不会结束，例如循环等外部输入的 generator： 
    async function* fromUserUI(): AsyncGenerator<SDKUserMessage> {
  while (true) {
    const text = await waitForUserInput();   // 你的 UI 输入源
    yield {
      type: 'user',
      message: { role: 'user', content: [{ type: 'text', text }] },
      parent_tool_use_id: null,
    };
  }
}
  • 想在消息序列正常结束之前提前终止：超时、用户取消、其他业务条件。
两种关闭方式：

​
自动管理（推荐，Node 22+ 或支持显式资源管理的运行时）

适合会话生命周期和某个函数 / 代码块一致的场景，离开作用域时自动释放。 
{
  await using q = query({ prompt: fromUserUI(), options: { auth: qodercliAuth() } });
  for await (const msg of q) { /* ... */ }
}  // 离开作用域自动关闭

​
手动关闭

适合外部触发关闭的场景：超时、用户取消、其他业务条件。 
const q = query({ prompt: fromUserUI(), options: { auth: qodercliAuth() } });
setTimeout(() => q.close(), 30_000);   // 30 秒后强制结束

for await (const msg of q) { /* ... */ }