# @everme/agent-sdk 中文文档

规范地址：https://npmcn.com/package/%40everme/agent-sdk/

版本：0\.7\.10
npm 元数据更新时间：2026-11-06T06:08:53.250Z
中文译文更新时间：2026-11-14T01:28:54.073Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40everme/agent-sdk
原文对照：https://npmcn.com/package/%40everme/agent-sdk/?lang=original
项目主页：https://everme.evermind.ai/
源码仓库：https://github.com/EverMind-AI/EverMe

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

- 包体积（解压后）：198 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2026-05-12T05:19:17.207Z
- 最新版本发布：2026-11-06T06:08:53.049Z
- 近 30 天下载量：3347（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

EverMe AI代理插件共享核心. HTTP 客户端,搜索/文本,代理-记忆书写,编辑,即时帮助. Host-agnostic——与@everme/openclaw,@everme/claude-code,@everme/memory-mcp相配,.....

## 安装

```sh
npm install @everme/agent-sdk
```

也可以使用：`pnpm add @everme/agent-sdk`、`yarn add @everme/agent-sdk`、`bun add @everme/agent-sdk`

## README

# @everme/代理服务器

这个 `createToolEventBuffer` 工具池保存完整的序列化输入 输出字段, 包括空字符串; 它不应用普通消息 8000-特征预算. 它现有的文件总大小政策没有改变. 主机 在附加事件之前,必须验证其本地工具合同.

每个 EverMe AI 代理插件的共享核心 . **主机不可知论** - 与EverMe网关进行会谈`/api/v1/mem/*` +前标 + S3多段)而无别. Per-host关注(MCP框架,OpenClaw生命周期,克洛德代码钩子. )生活在自己的包中并依赖于这个SDK.

## 为什么会这样

EverMe每个AI代理主机一个插件,这样每个插件就可以独立地进行:

| 软件包 | 东道主 | 格式 |
| --- | --- | --- |
| `@everme/memory-mcp` | 光标 / Cline / 通用 MCP 主机 | MCP 服务器( stdio / JSON- RPC) |
| `@everme/openclaw` | 打开Claw | 环境引擎插件( 在进程模块) |
| `@everme/claude-code` | 克劳德代码 | 本地插件( 呼克 + 命令 + 技能 + MCP) |

如果没有一个共享的 SDK 插件,每个插件将会重新执行 EverMe 有线协议——复制编辑、搜索/文本塑造、代理-记忆书写,以及每个插件中不可避免的错误。 SDK是"如何与EverMe网关交谈"的单一真理来源,而每个主机插件都是上方的薄适配器.

## 出口

```js
import {
  // HTTP layer
  createClient, EvermeError, redactError,
  // Agent-memory realtime writes
  saveAgentMemory, AGENT_MEMORY_ROLES, AGENT_MEMORY_TOOL_CALL_TYPES,
  // Search / context
  searchMemory, getContext,
  // Config (env + host-config merge)
  resolveConfig, assertConfigUsable, TIMEOUT_MS, UPLOAD_TIMEOUT_MS,
  // Prompt helpers
  buildMemoryPrompt, MEMORY_TYPES, MEMORY_TYPE_LABELS,
  // Message helpers
  extractText, toText, stripChannelMetadata, isSessionResetPrompt,
} from "@everme/agent-sdk";
```

## 电线合同

```
POST /api/v1/mem/search            → {items, profiles, rawMessages, agentMemory}
POST /api/v1/mem/context           → {profile, cachedAt, generatedAt}  // body: { forceRefresh?: bool }
POST /api/v1/mem/agent-memory      → {status, messageCount, flushed}
```

认证 : `Authorization: Bearer <emk_*|evt_*>`。 。 。 .

每个终点的信封如下:

```js
{ error, requestId, status, result }   // status === 0 → success, return result
```

写入同步合同 : `/mem/agent-memory` 接受 `flush` (同步添加于 每批+取出冲)和 `sync` (仅同步添加,无冲出). `saveAgentMemory` 套装 `sync: true` 提出多项要求的主要请求 上传其冲出最后的要求,所以早期的批次保留 同步添加保证. 钩子运行时间也设定 `sync: true` 每页 排队,所以检查站和后来的地盘/地盘冲出完成 增加而不是仅仅是一项被接受的同步工作。 直接 SDK 呼叫器可以 选择此选项 `sync: true`; 平面 `flush: false` 电话保持同步. 此命令保证需要一个网关支持现有的 `sync` 字段; 忽略它不能提供保证的旧服务器. `flushed` 打开 结果意味着冲出.. `status` 编号 : `extracted` 这是 实现信号,以及 `status: "no_extraction"` 是指上游地区 排入会话时尚未取出 .

上传超过 500 个信件按源顺序分割, 倾向于完成 转动,然后是完整的工具调用/结果组,然后是硬信息限制. 工具结果文本不会被共享作者限制为8000个字符; 主机侧剖析/重排仍然适用。 普通用户/助理文本和 个人记忆文本保留其现有的预算。 服务器请求大小限制 工具结果必须保持一个信息,而不是若干信息 相同识别结果碎片.

用户和助理文本保留文字协议实例、元数据引用和时间戳; 共享写入器不将这些字符串当作用户频道信封. 这既适用于代理记忆,也适用于个人记忆。 主机适配器 继续负责排除使用本地控制记录的实际控制记录 源结构. 现有的空地正常化和文本预算依然存在. `extractText` 提供纯文本提取,而不包含信封高压 主机写入适配器 . `toText` 财务报告和审定财务报表 `stripChannelMetadata` 保留现有的 查询- 规范化行为; 它们不能重新分类本地对话文本 .

当用户/ 新建时, 助理信件才会关闭转折 `turnId`, (中文(简体) ), 或适配器供应时 `turnComplete: true`,而且没有待拨电话. 明确 `turnComplete: false` 标记评论或执行记录 防止这些记录被用作收尾. 仅用完投入并不能证明完成. `turnId` 仍为地方. 明显的布尔 `turnComplete` 助理信件也发送到 EverMe网关使得其以字节为基础的批量可以使用同源证据. 网关会消耗此可选字段而不转发到 EverOS. 年长的客户忽略它并保持他们现有的行为;年长的网关忽略 因此,它不会得到这一字节的改进。 强制分割 保存实际信息而不产生缺失结果或结尾.

请求代号合同: `createClient` 每个请求生成一个UUID并发送 作为 `requestId` 页眉; 网关重新使用有效的输入值, 所以插件 stderr, EverMe ELK,和云平台的日志搜索都在一个ID上加入. `client.requestWithMeta(...)` 决定: `{ result, requestId }`; 包装 帮助者( e)`searchMemory` 编号 : `getContext` 编号 : `saveAgentMemory` 编号 : `savePersonalMemory`在结果上显示同样的标识,以及 `EvermeError` 带着它`err.requestId`由 `err.describe()` 编号 : `describeError(err)`) (中文(简体) ).

工具结果内容被转换为带有前导/后导白空间的文本 已修剪, 但频道元数据模式没有被删除: 工具输出可以 包含字面协议示例、日志时间戳或信件ID。 一样 文字内容规则适用于上述用户和助理信息.

## 适配器转弯边界

写入的适配器 `readStoreBatches` 必须说一个钩子 引用是一个合乎逻辑的转折:

```js
export const myAdapter = { platform: "my-host", turnBoundary: "stop", /* ... */ };
```

与 `turnBoundary: "stop"` sDK索赔 `channel: "hook"` 每个批次 a 停止并宣布 `turns: 1` 最后一批(早期批次携带) `turns: 0`, (中文(简体) ), 这使得主机的写作在 L1-2 捕捉完成 分母 。 在会话尾端上传的整会话主机保留它 : 他们不运行每个回合的交货标记,不能报告掉落的转弯,并且不能 输入他们永远无法触及的损失分母。 简单 `readLastTurn` 路径总是要求通道;它通过建造而倒转.

## 信封文件优先级

共享钩子运行时间合并主机 `everme.env` 输入进程内。 文件值从不覆盖在 shell 中已经设置的变量 - **除外** `EVERME_AGENT_TOKEN` 财务报告和审定财务报表 `EVERME_AGENT_ID`,文件获胜的地方。 这种不对称是故意的: `evercli` 通过重写旋转每台机器 evt 令牌 `everme.env`,且在外壳中导出的一个 steal sorder 绝不能阴影旋转的证书.

## 设备路径( 本地内存)

EverMe 桌面写入 `~/.everme/memory/route.json` 当用户打开本地内存( w)`$EVERME_MEMORY_HOME/route.json` 当它被设定的时候。 虽然它说 `local`, (中文(简体) ), `createClient` 将每个请求发送到它的回回网关,不管什么 `apiBase` 编号 : `EVERME_API_BASE` 说 文件每个请求都会被读取,所以长寿的主机(OpenClaw,MCP服务器)跟随一个切换而无需重启. 它失败关闭: 无法读取、 腐败或关闭的路由仍然意味着默认网关(`http://127.0.0.1:18790`) (中文(简体) ). 一个已停止的网关以提示失败请求打开 EverMe 桌面;客户端永远不会倒入云中.

## 货币/安全合同

-   **重试**数字 : `execWithRetry` 重复一次运输故障——但仅限于GET/HEAD. POST写道(`/mem/agent-memory`)表面显示传输错误,以便呼叫者可以决定;在中空投放后重试一个POST可以重复写作.
-   **编辑**数字 : `redactError` 洗涤器 `evt_*`, (中文(简体) ), `emk_*`, (中文(简体) ), `X-Amz-Signature/Credential/Security-Token`,并且 AWS 访问密钥标识 。 在传递到主机 stderr / 模型上下文之前, 应用到每个错误槽 .
-   **超时**数字 : `EvermeError{type:"timeout"}` 被抛出,所以呼叫者可以在其上分取(例如被降解为倒回),而不是重新试验,仿佛它是一个运输机。 读出身体的超时性也会被抓住——被卡住的身体不再沉默地描述为: `null`。 。 。 .

## 测试

```
npm test
```

封面为 HTTP 信封, 重试 Gating, 配置优先级, 消息正常化, 代理- 记忆塑造 .

## 许可证

阿帕奇 - 2.0

## 任务意识批量

`saveAgentMemory` 接受可选 `syncScope` 为原生片段的进步. 范围写入检查 `/mem/agent-memory/state` 在发送任何批次前: 钩 写入需要 `hookSyncScopeSupported: true`,导入写入需要 `syncScopeSupported: true`。所有批次都保留范围;旧服务器失败 不写。 未瞄准的呼叫和单独的会话冲出保留其原始 协议。 这个字段不会改变上游对话的特性和 无法与 `deduplication`。 。 。 .

`saveAgentMemory` ưμ㼯a `deduplication: "client-native-id"` 每批装有后端保护的钩子上 QuenWork, OpenClaw, Pi and ZeroClaw). 维基文库中相关的原始文献: 维基语录链接:名人名言 - 文学作品 - 谚语 - 谚语 - 谚语 - 谚语 - 谚语 它需要一个支持服务器, `channel: "hook"`,没有 `offline`。写作也可以携带 `baseTurn` 改为 锚起转水印. 服务器拒绝其他值和组合. 这个 默认保留位置 。 本地ID 选择为客户端所有; 服务器绕过位置 水印而不是存储每个消息的身份。 它不能保证 交叉通道分解或完全重复 POST 重试。 记名检查站 `commit(stateId, uploadedCount, { nativeMessageIds })` 持续本地可选 身份密钥仅在成功上传后;仅计数的调用者不变.

`saveAgentMemory` 接受可选 `taskBatching: true`; 接钩适配器选择使用 拥有同样的财产。 目前只有Codex允许. 其他打电话者保留 现有的分批路径。 这是本地的SDK选项,从来不是电线场.

战略规划用户任务,保留匹配原始结果,压缩 仅用 KiB UTF-8 工具结果预算进行字节超标的任务,然后拆分 其余为文本/空白/硬边界优先权。 它用64个KB软 目标,280 KiB消息预算 和500个消息封顶。 它保存消息计数, 命令和源元数据,所以 BaseTurn/turns 和 main-batch slush 行为停止 上传路径。 硬倒置并不能保证关闭的任务.

## 常见问题

### @everme/agent-sdk 是什么？

EverMe AI代理插件共享核心\. HTTP 客户端,搜索/文本,代理-记忆书写,编辑,即时帮助\. Host-agnostic——与@everme/openclaw,@everme/claude-code,@everme/memory-mcp相配,\.\.\.\.\.

### 如何安装 @everme/agent-sdk？

在项目目录运行 npm install @everme/agent-sdk，或使用 pnpm add / yarn add / bun add。

### @everme/agent-sdk 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/everme\_\_agent-sdk 是否存在。

### @everme/agent-sdk 支持 ESM 还是 CommonJS？

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

### @everme/agent-sdk 需要什么版本的 Node\.js？

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

### @everme/agent-sdk 可以商用吗？

@everme/agent-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @everme/agent-sdk 的下载量有多少？

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

### @everme/agent-sdk 还在维护吗？

最新版本 0\.7\.10 发布于 2026/11/06（7 天前）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/05/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。