TypeScript DaemonClient

DaemonClient 连接已有 qwen serve，和 query 自行管理 CLI 进程不同。官方 quickstart 标注演示组合为 CLI v0.24.0 与 SDK 0.1.12；实际应用仍需按 capabilities 检查目标 daemon。

连接与工作区选择

import { DaemonClient } from '@qwen-code/sdk';

const client = new DaemonClient({ baseUrl: 'http://127.0.0.1:4170' });
const caps = await client.capabilities();
const workspace = caps.workspaces?.find((item) => item.trusted);
if (!workspace) throw new Error('No trusted workspace is available.');

const session = await client.createOrAttachSession({
  workspaceCwd: workspace.cwd,
});
console.log(session.sessionId, session.attached);

token 省略时在构造时读取 QWEN_SERVER_TOKEN，去首尾空白，空值视为未设。构造后修改环境不会更新已有 client；浏览器没有 process 时没有此自动来源。

SDK 的 workspaceCwd 转成 HTTP cwd。省略只应表示有意使用 primary，不应在 workspace_mismatch 或 403 untrusted_workspace 后擅自回退 primary。刷新目录并重新选择目标，或明确注册原目标。

订阅窗口

subscribeEvents 是异步流，取得 iterator 不代表 SSE 已握手。开始订阅时传 lastEventId: 0，再发 prompt，可让 replay ring 覆盖握手间隙里产生的事件。以后把实际收到的数字 event.id 存为 cursor；undefined 表示仅看新事件。

const abort = new AbortController();
const subscription = (async () => {
  for await (const event of client.subscribeEvents(session.sessionId, {
    signal: abort.signal,
    lastEventId: 0,
  })) {
    console.log(event);
  }
})();

try {
  const result = await client.prompt(session.sessionId, {
    prompt: [{ type: 'text', text: 'Explain the repository structure.' }],
  });
  console.log(result.stopReason);
} finally {
  abort.abort();
  await subscription;
}

此片段接前例，展示事件消费与关闭，不实现审批 UI。收到 permission_request 时，应将选项交给实际授权方，并使用会话限定审批路由。官方 quickstart 的旧全局投票示例仅适合 primary，不能直接复制到多工作区客户端。8000 事件的默认 ring 也不能覆盖任意长断连。

创建前确定 ID 与模型

createOrAttachSession 可指定 sessionId，先要求 session_id_override，规范化后若 daemon 返回不同 ID，会抛 DaemonSessionIdProtocolError。该选项始终新建 thread 会话，不是幂等 attach；创建结果未知时，用已知 ID load/resume 核对，不重复 create。

createOrAttachSession 和 createStandaloneSession 可传 startupConfig，含必需 modelServiceId 和可选 reasoningEffort，并检查 session_startup_config。显式 effort 须适配该模型；不支持推理控制的模型只传 model。

成功响应需确认 modelApplied: true 和匹配的 startupConfigApplied；缺失或不匹配直接报错，不借 standalone recovery 自动收养结果。启动选择不保存共享默认，也不终身锁定模型。

恢复、状态与文件

closeSession 不删除持久 transcript。保存 ID 后可用 loadSession 回放历史，或 resumeSession 只恢复 agent 句柄；两者不继续被中断轮次，需要时单独 continueSession。sessionStatus 查 live owner，getSessionTranscriptPage 查持久记录，nextCursor 原样回传，不自行构造。

用 workspaceById(workspace.id) 绑定文件 helper。editWorkspaceFile 与 replace 需刚读到的完整原始字节 hash；部分大文件窗口不能靠非空断言伪造可用 hash。读取范围和并发写规则见Daemon 文件接口。

DaemonHttpError 包含 HTTP status 和结构化 body。cancel(sessionId) 取消当前 active prompt，队列里已接纳的后续 prompt 仍可运行；关闭事件订阅本身不等于取消服务端任务。