openai-assistants

用途

OpenAI Assistants API v2 用于构建有状态的聊天机器人。它通过 Assistant、Thread、Message、Run 四个核心对象管理对话状态，适合需要持久化消息历史、文件处理或函数调用的应用场景。

⚠️ 弃用提示：OpenAI 正在弃用 Assistants API，转向 Responses API。v1 已于 2024 年 12 月 18 日弃用，v2 将于 2026 年 8 月 26 日停止服务。本技能适用于维护遗留应用或迁移现有代码（约 12-18 个月窗口），不建议用于新项目（新项目应使用 openai-responses 技能）。迁移参考见 references/migration-to-responses.md。

主要能力

核心对象

Assistants：配置了指令（v2 最大 256k 字符，v1 为 32k）、模型、工具和元数据的 AI 助手。
Threads：对话容器，持久保存消息历史（最多 100k 条消息）。
Messages：用户/助手消息，可附带文件附件。
Runs：异步执行，状态包括 queued、in_progress、requires_action、completed、failed、expired（最长 10 分钟）。

工具

Code Interpreter：在沙箱中运行 Python 代码，可生成图表、处理文件（CSV、JSON、PDF、图片等），单文件最大 512MB。
File Search（RAG）：基于向量存储的语义搜索，v2 最多 10,000 个文件（v1 为 20 个）。定价：$0.10/GB/天（1GB 免费）。
Function Calling：当 run.status 为 requires_action 时提交工具输出。

流式传输

支持 runs.stream，关键事件包括 thread.run.created、thread.message.delta（流式内容）、thread.run.step.delta（工具进度）、thread.run.completed、thread.run.requires_action。

使用方式

安装：npm install openai@6.16.0

基本流程：

创建 assistant（指定 model、instructions、tools）。
创建 thread。
向 thread 添加 message。
创建 run。
轮询 run 状态直至 completed。
列出 messages 获取响应。

代码示例（来自资料）：

import OpenAI from 'openai';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const assistant = await openai.beta.assistants.create({
  name: "Math Tutor",
  instructions: "You are a math tutor. Use code interpreter for calculations.",
  tools: [{ type: "code_interpreter" }],
  model: "gpt-5",
});

const thread = await openai.beta.threads.create();
await openai.beta.threads.messages.create(thread.id, {
  role: "user",
  content: "Solve: 3x + 11 = 14",
});

const run = await openai.beta.threads.runs.create(thread.id, {
  assistant_id: assistant.id,
});

let status = await openai.beta.threads.runs.retrieve(thread.id, run.id);
while (status.status !== 'completed') {
  await new Promise(r => setTimeout(r, 1000));
  status = await openai.beta.threads.runs.retrieve(thread.id, run.id);
}

const messages = await openai.beta.threads.messages.list(thread.id);
console.log(messages.data[0].content[0].text.value);

关键限制：指令最大 256k 字符（v2），最多 128 个工具，16 对元数据，每线程最多 100k 条消息。

适用场景

维护使用 Assistants API 的遗留应用。
迁移现有代码至 Responses API。
需要 Code Interpreter、File Search 或 Function Calling 的有状态聊天机器人。

限制与已知问题

资料列出了 10 个已知错误：

线程已有活动 run：需先取消活动 run。
Run 轮询超时/不完整状态：需优雅处理 incomplete 状态。
向量存储未就绪：需轮询至 status === 'completed'。
文件上传格式问题：上传前验证扩展名。
向量存储上传文档错误：需将文件流包装为 { files: [...] }。
推理模型拒绝 temperature 参数：需显式设为 null。
uploadAndPoll 返回向量存储 ID 而非批次 ID：需使用替代方法获取批次 ID。
向量存储文件删除影响所有存储：删除操作具有全局效果。
大文件上传内存泄漏（社区来源）：长运行服务器需监控内存。
线程已有活动 run 的竞态条件（社区来源）：取消时可能发生竞态。

文件格式支持：Code Interpreter 支持 .c、.cpp、.csv、.docx、.html、.java、.json、.md、.pdf、.php、.pptx、.py、.rb、.tex、.txt、.css、.jpeg、.jpg、.js、.gif、.png、.tar、.ts、.xlsx、.xml、.zip（最大 512MB）；File Search 支持 .c、.cpp、.docx、.html、.java、.json、.md、.pdf、.php、.pptx、.py、.rb、.tex、.txt、.css、.js、.ts、.go（最大 512MB）。

与其他技能的关系

openai-api（Chat Completions）：无状态，手动管理历史，直接响应，适用于简单生成。
openai-responses（Responses API）：推荐用于新项目，更好的推理、现代 MCP 集成、活跃开发。
openai-assistants：已弃用，仅用于遗留应用。

模板与参考

模板：templates/basic-assistant.ts、code-interpreter-assistant.ts、file-search-assistant.ts、function-calling-assistant.ts、streaming-assistant.ts。

参考：references/top-errors.md、thread-lifecycle.md、vector-stores.md、migration-to-responses.md、migration-from-v1.md。

最后更新：2026-01-21；包版本：openai@6.16.0；状态：生产就绪（⚠️ 已弃用，2026 年 8 月 26 日停止服务）。