# @guuey/threads 中文文档

规范地址：https://npmcn.com/package/%40guuey/threads/

版本：0\.36\.0
npm 元数据更新时间：2026-11-14T17:05:19.973Z
中文译文更新时间：2026-11-17T08:05:47.289Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40guuey/threads
原文对照：https://npmcn.com/package/%40guuey/threads/?lang=original
项目主页：https://guuey.com/
源码仓库：https://github.com/withguuey/guuey-sdks

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：291 kB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：3 个
- peer 依赖：vitest \>=3\.2\.7 \<5
- 首次发布：2026-08-07T12:39:58.609Z
- 最新版本发布：2026-11-14T17:05:19.559Z
- 近 30 天下载量：5014（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：74（近 12 个月 74 个）

## 中文简介

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

## 安装

```sh
npm install @guuey/threads
```

也可以使用：`pnpm add @guuey/threads`、`yarn add @guuey/threads`、`bun add @guuey/threads`

## README

# @ 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`** 港口合同套房 运行它对 装订和"记忆中的工作" 和"真实事物上的工作"的意思 同样的保证.

```ts
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);
```

```ts
// 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)`。 。 。 .

```ts
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` =仍然开放),应用程序的操作员可能 不读。 一个向操作员显示对话数据的阅读器检查 与输出的助手,绝不用手:

```ts
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://guuey.com/discord)。 。 。 . 错误和特性请求 : [https://github.com/wisguuey/guey-sdks/ 问题](https://github.com/withguuey/guuey-sdks/issues)。 。 。 .

## 常见问题

### @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 和提交记录判断。

