createAssistant()

GolemBot 作为库使用的主入口。

签名

import { createAssistant } from 'golembot';

function createAssistant(opts: CreateAssistantOpts): Assistant;

CreateAssistantOpts

interface CreateAssistantOpts {
  dir: string;                  // 助手目录路径
  engine?: string;              // 覆盖 golem.yaml 中的引擎
  model?: string;               // 覆盖 golem.yaml 中的模型
  apiKey?: string;              // Agent API Key
  maxConcurrent?: number;       // 全局最大并发 chat() 数（默认：10）
  maxQueuePerSession?: number;  // 每个 sessionKey 最大排队数（默认：3）
  timeoutMs?: number;           // 引擎调用超时毫秒数（默认：300000）
}

字段	类型	必填	说明
dir	string	是	助手目录路径（必须包含 golem.yaml）
engine	string	否	覆盖 golem.yaml 中的 engine
model	string	否	覆盖 golem.yaml 中的 model
apiKey	string	否	传给底层引擎的 API Key
maxConcurrent	number	否	全局最大并发 chat 数。超出时会先产出 error，再以 completion: failed 收尾。默认 10
maxQueuePerSession	number	否	每个 sessionKey 的最大排队数。超出时会先产出 error，再以 completion: failed 收尾。默认 3
timeoutMs	number	否	引擎调用超时毫秒数。超时会中断底层 CLI，先产出 error，最后以 completion: aborted 收尾。默认 300000

Assistant 接口

interface Assistant {
  chat(message: string, opts?: ChatOpts): AsyncIterable<StreamEvent>;
  init(opts: { engine: string; name: string }): Promise<void>;
  resetSession(sessionKey?: string): Promise<void>;
  cancel(sessionKey?: string): Promise<boolean>;
}

chat(message, opts?)

发送消息并接收事件流。

interface ChatOpts {
  sessionKey?: string;   // 默认："default"
}

返回 AsyncIterable<StreamEvent>。详见 StreamEvent。

每次 chat() 调用现在都会以且仅以一个 type: 'completion' 事件收尾。它才是最终的终态语义；done 仍然保留，但只表示底层引擎流结束。

并发：相同 sessionKey 的调用串行化（排队）。不同 sessionKey 并行运行。

// 单用户
for await (const event of assistant.chat('你好')) {
  if (event.type === 'text') process.stdout.write(event.content);
}

// 多用户
for await (const event of assistant.chat('你好', { sessionKey: 'user-123' })) {
  // ...
}

init(opts)

初始化新的助手目录。如果 golem.yaml 已存在则抛出错误。

resetSession(sessionKey?)

清除指定 Key 的会话和累计历史（默认："default"）。

await assistant.resetSession();            // 清除默认会话 + 历史
await assistant.resetSession('user-123');  // 清除指定会话 + 历史

cancel(sessionKey?)

中断指定会话当前正在执行的任务，但不清空历史。

await assistant.cancel();            // 中断默认会话
await assistant.cancel('user-123');  // 中断指定会话

如果确实取消到了一个正在运行的任务，返回 true；否则返回 false。

生产环境：限流 + 超时

const assistant = createAssistant({
  dir: './my-bot',
  maxConcurrent: 20,       // 超过 20 个并发立即返回 error 事件
  maxQueuePerSession: 2,   // 同一用户超过 2 个排队请求立即返回 error 事件
  timeoutMs: 120_000,      // 2 分钟强制超时
});

// 处理限流 / 超时 / 最终终态
for await (const event of assistant.chat('你好', { sessionKey: 'user-1' })) {
  if (event.type === 'error') {
    console.error('聊天错误:', event.message);
  }
  if (event.type === 'completion') {
    console.log('终态:', event.status);
    break;
  }
  if (event.type === 'text') process.stdout.write(event.content);
}

重导出

golembot 包还重导出：

export type { StreamEvent } from './engine.js';
export type { CompletionEvent } from './engine.js';
export type { GolemConfig, SkillInfo, ChannelsConfig, GatewayConfig,
              StreamingConfig } from './workspace.js';
export { createGolemServer, startServer, type ServerOpts } from './server.js';
export type { ChannelAdapter, ChannelMessage, ReadReceipt } from './channel.js';
export { buildSessionKey, stripMention } from './channel.js';
export { startGateway } from './gateway.js';