@guuey/threads

中文文档
0.36.0发布于 2026/11/15MITTypeScriptES Module构建来源已验证近 30 天下载 5014

AgJSON代理的通用会话/线程持续——ThreadStore合同(附录,历史,快照),折叠相映射,并装入内装. Guuey主机运行时间为一绑定; 执行端口对应于自己的商店和运行 t

中文使用文档
文档目录4 节
  1. 主机绑定 — 弹出后保留记忆
  2. 行大小限制
  3. 密封信件
  4. 支助

@ guuey/ 线索

AgJSON代理的通用会话/线段持续.

宿主Guuey代理 得到线回水("我的代理 记得这一点" 从平台上。 此软件包是和 公共合同,因此被开除和自行托管的代理人——和融合 ——分享:

  • ThreadStore ——存储不可知逻辑:线程分辨率和 所有权,无原子差距的顺序, clientMessageId 专横, 转折级折叠持久性(信息+基因-UI卡行+ 最新替换快照),以及快跑历史投影.
  • ThreadPersistencePort 狭长的地表是装订工具. InMemoryThreadPersistence (d) 箱内船舶(dev、测试、CI) 主机运行时间绑定 DynatomDB; HttpThreadPersistence 点a 在 guuey 的主机线程 API 上自行托管代理 (“ 退出代码, 保留您的代码 ” ) );或针对自己的商店执行端口.
  • 折叠qq行映射 —— 说 agMessageToRow, (中文(简体) ), reassembleFold, (中文(简体) ), uiCardArtifactsFromMessages 朋友: 字节标识的持久性 @silverprotocol/core AgReduceResult,包括预测: 在工具结果块上携带的MCP-App卡.
  • @guuey/threads/testing 港口合同套房 运行它对 装订和"记忆中的工作" 和"真实事物上的工作"的意思 同样的保证.
import { InMemoryThreadPersistence, ThreadStore } from "@guuey/threads";

const store = new ThreadStore(new InMemoryThreadPersistence());
const threadId = await store.ensureThread({
  userId: "g_dev",
  appId: "my-agent",
  region: "local",
});
await store.appendMessage({
  threadId,
  userId: "g_dev",
  role: "user",
  content: "hello",
  text: "hello",
  clientMessageId: "m1",
});
const history = await store.loadHistory(threadId);
// your-binding.test.ts
import { runThreadPersistenceContractSuite } from "@guuey/threads/testing";
runThreadPersistenceContractSuite("MyBinding", async () => ({ port: makeMyPort() }));

主机绑定 — 弹出后保留记忆

HttpThreadPersistence 在 Guuey 线程 API 上执行同一端口, 所以 您自己运行的代理 读取并撰写 SAME 对话 主机运行时间是 。 它被设定为一个应用程序和一个最终用户:通过 终端用户的无记名符号——一个您的应用软件配置的身份签发器被铸造 (你自己的IDP,或Guuey的每个应用程序部件发行商通过 @guuey/widget-auth) (中文(简体) ). 服务器对发行人进行验证 获得相同的最终用户ID 主机运行时间用途,并限制每个操作 (app, user)。 。 。 .

import { HttpThreadPersistence, ThreadStore } from "@guuey/threads";

const appId = process.env.GUUEY_APP_ID!;
const port = new HttpThreadPersistence({
  baseUrl: "https://api.us-east-1.guuey.com",
  appId,
  token: endUserToken, // per request — the end-user's own token
});
const { userId, region } = await port.scope(); // what the token resolves to
const store = new ThreadStore(port);
const threadId = await store.ensureThread({ threadId: clientThreadId, userId, appId, region });

要求应用程序运行已识别的终端用户(userAuthMode: "byo"); 来宾 和Cognitto课程只服务于平台。 表面错误为 HttpThreadStoreError (单位:千美元)status, (中文(简体) ), code) (中文(简体) ). 在网络上重试一次 失败或 5xx; 写不出来 .

行大小限制

有项目大小限制的商店宣布它为端口的可选选项 rowBudget (单位:千美元){ maxBytes, bytesOf(row), numberFits?(n) }) (中文(简体) ). 迪纳摩DB支持 装订, HttpThreadPersistence 包含、声明 DYNAMODB_ROW_BUDGET数字 : 380,000字节 dynamoItemBytes,在DynamoDB的上行 拥有项目大小规则,以及 dynamoNumberFits,拒绝数字 DynamoDB 无法以书面(在安全整数范围、NaN或无限范围以外,或 a 低于1e-130的非零级。 一个没有预算的端口完全行 和地图一样.

appendFold 在预算出现之前

  • 一个值作为标记被存储在其位置, { "com.guuey/elided": { "bytes": <UTF-8 length of its JSON> } }A级 工具调用值是,当它携带一个数字时,商店无法持有 (单位:千美元)reason: "number") (中文(简体) ). 超大小的行会留下数值直到符合 (单位:千美元)reason: "size"),是每个步骤中最大的第一名: 工具结果 uiData 是一个带文本的内置UI资源 (单位:千美元){ uri, text }当同一转弯的牌行带有相同的值时 同一电话:field: "uiData";卡行持有资源,以及 线程的读者从它抽出牌,然后每个 providerMetadata.wireInput 复制,然后每个 input文本块 滑动。 结果列出每个在 elidedToolInputs。 。 。 .
  • 仍然无法存储的转动永远不会被部分写入 。 与 unstorableNotice: { text } 转弯被存储为 one 代理行 文本和内容 content.error.code "stored_turn_too_large" 或者说 "stored_turn_unstorable_number" (单位:千美元)classifyStoredRow 改为: 失败),结果随之而来 unstorable没有它, appendFold 掷出 StoredRowTooLargeError 或者说 StoredRowUnstorableNumberError 财务报告和审定财务报表 写什么.

appendMessage 在分配以下各行之前拒绝同样的行. withItemSizeLimit(port) 从 @guuey/threads/testing 将任何端口覆盖到 宣布预算,并拒绝DynamoDB(关于 putMessage 财务报告和审定财务报表 putSnapshot),用于测试.

转弯的快照是在同一个预算下规划的 任何一行之前 写( a)planSnapshot),所以快照写在行后不会失败 着陆 :

  • A 类 workingState 带有商店无法持有的号码,则不存储. 快照保存着 priorWorkingState 转弯所生的状态, 或无所施相时无所施相.
  • 包含这样数字的线程记忆元素被忽略.
  • 预算上,转弯状态先被拒绝,然后是内存记录 这个转弯被忽略了,最大的第一个。 记录未变 从 priorThreadMemory和携带的元素,留下来.
  • 仍不相容的快照不写,前作站立.

结果 refusedSnapshot (单位:千美元){ state?, memoryNumber, memorySize, notWritten }报告遗漏的内容,按计算.

密封信件

线索行可以携带 sealIntervals: 信件长度(fromSeq 改为 toSeq(b) 不 toSeq =仍然开放),应用程序的操作员可能 不读。 一个向操作员显示对话数据的阅读器检查 与输出的助手,绝不用手:

import { isSeqSealed, readableThreadPreview, readSealState } from "@guuey/threads";

const seal = readSealState(row.sealIntervals); // absent = legacy, wholly readable
if (isSeqSealed(seal, message.seq)) {
  /* withhold this message */
}
const preview = readableThreadPreview(row); // '' when its source message is sealed

一份有封条但内容不全的封条 每个 预览记录它取自( )lastMessagePreviewSeq)和a 数据 案文摘要(lastMessagePreviewDigest, (中文(简体) ), previewDigest(preview)(单位:千美元) 同样的更新。 在一条有密封部分的线上,预览其后续部分 ,或者其摘要缺少或与其文本不符的,被扣。 A 类 绑定,执行端口同时写出预览.

事件行( 交接、 报告) 离开预览, 如卡片 排行:它来自整个对话,所以它永远不会成为 线程预览 .

支助

问题和帮助:Discord上的贵人社区—— https://guuey.com/discord (英语)。 。 。 . 错误和特性请求 : https://github.com/wisguuey/guey-sdks/ 问题。 。 。 .

版本与发布记录

@guuey/threads 共发布 74 个版本,首次发布于 2026/08/07;过去 12 个月发布了 74 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.36.0latest2026/11/152 天前
0.35.02026/11/116 天前
0.34.02026/11/0610 天前
0.33.02026/11/0610 天前
0.32.02026/11/0611 天前
0.31.12026/09/291 个月前

其他发布通道:next → 0.16.15。

关于 @guuey/threads 的常见问题

@guuey/threads 是什么?

AgJSON代理的通用会话/线程持续——ThreadStore合同(附录,历史,快照),折叠相映射,并装入内装. Guuey主机运行时间为一绑定; 执行端口对应于自己的商店和运行 t

如何安装 @guuey/threads?

在项目目录运行 npm install @guuey/threads,或使用 pnpm add / yarn add / bun add。

@guuey/threads 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guuey/threads 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@guuey/threads 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.12.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@guuey/threads 可以商用吗?

@guuey/threads 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@guuey/threads 的下载量有多少?

根据 npm 官方下载统计,@guuey/threads 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,014 次,日均约 167 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guuey/threads 还在维护吗?

最新版本 0.36.0 发布于 2026/11/15(2 天前);至今共发布 74 个版本,其中过去 12 个月发布了 74 个;首次发布于 2026/08/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。