# @basilica-digital/maypop-sdk 中文文档

规范地址：https://npmcn.com/package/%40basilica-digital/maypop-sdk/

版本：1\.5\.0
npm 元数据更新时间：2026-10-29T10:17:48.792Z
中文译文更新时间：2026-11-07T18:05:43.191Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40basilica-digital/maypop-sdk
原文对照：https://npmcn.com/package/%40basilica-digital/maypop-sdk/?lang=original
项目主页：https://github.com/basilica-digital/maypop-sdk#readme
源码仓库：https://github.com/basilica-digital/maypop-sdk

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

- 包体积（解压后）：5.9 MB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：next \>=14 \<17，vite \>=5 \<9，react \>=18\.2，@rsbuild/core \>=1 \<3
- 首次发布：2026-09-21T11:12:39.858Z
- 最新版本发布：2026-10-29T10:17:48.368Z
- 近 30 天下载量：5973（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

在Maypop上运行的应用程序的浏览器SDK.

## 安装

```sh
npm install @basilica-digital/maypop-sdk
```

也可以使用：`pnpm add @basilica-digital/maypop-sdk`、`yarn add @basilica-digital/maypop-sdk`、`bun add @basilica-digital/maypop-sdk`

## README

# 鸡尾酒

用于在Maypop上运行的应用程序的框架中立浏览器SDK. 它揭露了 与主机相同的对象和能力 `/sdk/v1.js` 脚本: 身份, KV, Drive, AI, 集成, 多人游戏, 通知, 以及其他 API 在其中 类型 `Maypop` 合同.

## 安装

```sh
pnpm add @basilica-digital/maypop-sdk
```

从浏览器代码导入 SDK, 在使用 Maypop 主机前等待 能力:

```ts
import { maypop } from "@basilica-digital/maypop-sdk";

await maypop.ready();
const todos = await maypop.kv.list({ prefix: "todo/" });
```

默认和命名导出与 `window.maypop`这样 框架代码和脚本可以互操作而无需适配器:

```ts
import maypop, { type Maypop } from "@basilica-digital/maypop-sdk";

function currentUser(sdk: Maypop = maypop) {
  return sdk.user;
}
```

当一个框架在服务器上制作时,模块是安全的导入 。 访问 sDK 仍然扔出,因为能力属于浏览器托管的应用程序 届会。 打电话 `getMaypop()` 当一个 SSR 框架需要时从只浏览器代码中 明确推迟访问.

## 反应

React App可以订阅Maypop状态而无需手动协调主机 握手或效果清理:

```tsx
import {
  useMaypopKV,
  useMaypopMode,
  useMaypopSession,
} from "@basilica-digital/maypop-sdk/react";

export function Counter() {
  const session = useMaypopSession();
  const mode = useMaypopMode();
  const count = useMaypopKV("counter", 0);

  if (session.status === "connecting") return <p>Connecting…</p>;
  if (session.status === "error") return <p>{session.error.message}</p>;

  return (
    <button
      disabled={mode === "read-only" || count.isMutating}
      onClick={() => count.setValue(count.value + 1)}
    >
      {count.value}
    </button>
  );
}
```

钩子自动使用主机SDK. `MaypopProvider` 仅需 在测试或未来的本地沙盒主机中注入另一个客户端 :

```tsx
import { MaypopProvider } from "@basilica-digital/maypop-sdk/react";

<MaypopProvider client={sandboxClient}>
  <App />
</MaypopProvider>
```

## 当地发展东道方

### 维特

将 Maypop 插件添加到现有的 Vite 配置中 :

```ts
import { maypop } from "@basilica-digital/maypop-sdk/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [maypop()],
});
```

### 建设

将等效插件添加到 Rsbuilding 配置 :

```ts
import { defineConfig } from "@rsbuild/core";
import { maypop } from "@basilica-digital/maypop-sdk/rsbuild";

export default defineConfig({
  plugins: [maypop()],
});
```

### 下一个.js

包装下一个.js配置 。 包装器只将其沙盒代理添加到 `next dev`; 构建和生产服务器保留原始配置 :

```ts
import { withMaypop } from "@basilica-digital/maypop-sdk/next";

export default withMaypop({
  output: "export",
});
```

框架的正常开发命令然后作为 Maypop 主机服务其 URL 包括路由程序打开或 刷新深的 URL 。 该应用程序使用生产SDK握手,iframe 权限,和 API 形状。 共享 KV 状态持续到 `.maypop/local/kv.json`,而驱动元数据与字节持续在 `.maypop/local/drive/`。 。 。 .

Next.js 绑定器也添加了机器的活跃网络地址到 `allowedDevOrigins`从另一个设备打开开发服务器 局域网装入并水合其客户端脚本。 任何配置的条目是 保留了下来.

身份、成员、KV、Drive、模拟MCP集成、共享卡预览和a 本地可提供通知收发箱。 他们的能力范围是: 通过报告 `maypop.user.scopes`; 需要其它能力的API失败 与 `maypop/unsupported` 当他们到达当地的宿主. `maypop.apps.open()` 组设置导航仍然无法进行,因为它们需要 Maypop产品外壳而不是应用API.

`maypop.notify()` 被默认捕获,而不是交付。 打开 开发主机的Maypop徽章,或访问 `/_maypop/notifications`,改为 检查请求的和已解决的收件人、头衔、身体和深层链接. 接获的电话持续 `.maypop/local/notifications.json`。 。 。 .

### 认证开发

创建 `.maypop/local/dev.json` 选择此机器为认证 能力。 吉特忽略了它与其余部分 `.maypop/local/`: 它选择一个 开发者账户并能够访问真实的应用数据或可计费的AI呼叫.

混合模式将 KV 和 Drive 保留在本地,同时转发一组明确的 通过账户认证的仅读或非数据能力 `maypop auth`数字 :

```json
{
  "mode": "hybrid",
  "profile": "dev",
  "remoteCapabilities": ["ai", "members", "link", "mcp", "multiplayer"],
  "notifications": "inspect"
}
```

`ai` 包括聊天完成、流传、决定(类型分类、, 在TypeSafe的Jev模型上进行路由,取笑,并评分,图像,视频,音频, 转录,和 `maypop.agent` (开发主机为它的懒浏览器服务) 块. 这些呼叫使用所选账户的实际允许使用,并可以消费 学分. `members` 阅读真正的应用程序名册, `link` 启用服务器侧 URL 脱发, `mcp` 曝光该应用程序真正的连接 MCP 服务器和工具,以及 `multiplayer` 在装入Iroh JS/Wasm时使用真实的会合API 本地运行时间 。 KV和Drive继续留在当地,通知留在 探长 连接服务器 `maypop mcp connect`运行 `maypop mcp link` 在启动开发服务器之前在应用程序仓库中。 一个混合 配置无法结合真实 `mcp` 具备 `.maypop/local/mcp.json` 固定装置.

连接模式跳过本地 KV/ Drive 初始化并发送整个app API 表面到真实的应用程序 :

```json
{
  "mode": "connected",
  "profile": "dev",
  "notifications": "inspect"
}
```

项目必须已经连接到 `maypop init`,并选择了 CLI 配置文件必须经过认证,并能够访问该应用程序。 奥米 `profile` 改为 使用通常的 CLI 选择规则,包括 `MAYPOP_PROFILE` 和简介 其 API URL 符合寄存器 。 节点开发主机读取 由 : `maypop auth` 薄荷薄荷, 应用范围会议本身。 保存的 CLI 证书和会话刷新符号 从未接触过应用程序代码,也从未在下列情况下被写入: `.maypop/`。 。 。 .

真正的通知交付需要连接模式和第二次明确 选入 :

```json
{
  "mode": "connected",
  "notifications": "live"
}
```

使用 `"notifications": "disabled"` 完全取消通知许可. 默认是 `"inspect"` 在每一个开发模式中.

### 当地身份和受众

Sandbox 模式可以从匿名、读者、作家、编辑或管理员开始 收视者并出露出可塑观众. 这同样是公开的 身份、模式、范围、成员以及作为主机SDK的登录行为:

```json
{
  "mode": "sandbox",
  "viewer": {
    "username": "Visitor",
    "role": "reader",
    "anonymous": true,
    "signInGrantsWrite": true,
    "signedInUsername": "Alice",
    "signedInRole": "writer"
  },
  "members": [
    { "username": "Bob", "role": "editor", "connected": false }
  ],
  "guestCount": 2
}
```

通话 `maypop.signIn()` 将本地会话升级 重新装入应用程序为已配置的登录查看器 。 本地API执行 只读 KV、 Drive 和通知范围, 因此直接请求不能绕过 浏览器 SDK 的权限检查 .

本地 KV 写入验证生产密钥和值限制 。 设定 `"strictStorage": true` 以额外强制执行承诺 `.maypop/kv-policy.json` 在当地拉和推的时候 预设和高级 政策使用的作用、关键模式和所有权的前提与 平台.

### 模拟整合和东道方行动

添加 `.maypop/local/mcp.json` 进行MCP发现、工具包装、呼叫和 代理工具, 不引用真正的外部整合 :

```json
{
  "schemaVersion": 1,
  "servers": [
    {
      "id": "search",
      "name": "Fixture search",
      "url": "mock://search",
      "account": "developer@example.com",
      "tools": [
        {
          "name": "lookup",
          "description": "Return a fixed search fixture.",
          "inputSchema": {
            "type": "object",
            "properties": { "query": { "type": "string" } }
          },
          "result": {
            "content": [{ "type": "text", "text": "Fixture result" }],
            "structuredContent": { "items": [] }
          }
        }
      ]
    }
  ]
}
```

`maypop.link.to(path)` 返回本地深链接,并 `maypop.share()` 打开一个 包含一个主机的卡片 。 带a的扣押通知 `path` 曝光一个 **在本地应用程序中打开** 动作在收发箱。 本地主机打开这些路 Maypop 这样做——应用程序在输入时加载路径 `location.hash` 财务报告和审定财务报表 `maypop.launchPath` ——如此一个应用程序,使这里的路线正确 路线正确 曾经出版。 没有任何人声称曾发表过本地链接,或者 已发出扣押通知.

本地无记名符號是随机的,每一次服务器运行,一个锁可以防止两次 从写入同一数据目录的开发服务器。 用别的 目录或查看器名称 :

```ts
maypop({
  dataDirectory: ".maypop/alice",
  username: "Alice",
});
```

本地主机是开发工具,而不是安全边界. 留着 将开发服务器绑入可信任的界面,除非项目本身是 安全地暴露出来.

这台机器属于什么 `.maypop/local/`:当地身份, `dev.json`、MCP固定装置、KV和Drive数据、捕获的通知和 锁上锁 开发服务器用它自己创建 `.gitignore`,所以它留下来 即使是Git的应用程序 `.gitignore` 没有提及它. `.maypop/kv-policy.json` 站在一边,承诺:平台阅读 并应用到每个已发布的版本。 在第一个 运行,服务器将旧版本直接写入 `.maypop/` 输入 `.maypop/local/`它留下了一个旧的 `.maypop/.lock` 它在哪里,不再读 ; 与 `git rm --cached .maypop/.lock`。 。 。 .

锁只在写它的过程运行时保存. 它记录 process的 PID 和启动时间, 所以服务器留下的锁 ,或者它的沙盒重新启动并将其PID交给另一个进程 已经接管了 一个不关闭而退出的服务器仍然会去掉其锁.

绑定只会影响框架开发服务器. 生产建筑 仍然是普通的应用程序捆绑. `maypop init` 记录匹配的构建适配器 内 `maypop.toml`,以及 `maypop publish` 构建并上传其静态输出.

## 主机脚本兼容性

现有应用程序可以继续加载全局架构 :

```html
<script src="https://api.dev.maypop.ai/sdk/v1.js"></script>
```

导入 `@basilica-digital/maypop-sdk` 相反,从软件包中安装相同的构件。 两者 窗体使用相同的主机握手和后端 API,两个都曝光 `window.maypop`。不要在一个应用程序中使用两种表格;运行时间为一元时间, 但一个就够了.

这个包是"Maypop"协议的来宾一面. 在Maypop外边, `maypop.ready()` 等待兼容的主机。 以上框架的整合 提供主机协议而不要求应用程序更改其SDK 进口.

## 后端文物

已出版的柏球还包含生成的主机脚本,懒惰能力 块、外壳文件、合同和Iroh WebAssembly运行时间 `dist/`。 。 。 . Maypop后端针入精确的软件包版本,并将这些文件嵌入其中 二进制,所以后端的构建从不依赖于SDK寄存器的移动分支.

源合同和运行时间可通过 `@basilica-digital/maypop-sdk/source/v1` 财务报告和审定财务报表 `@basilica-digital/maypop-sdk/source/runtime` 为了梅波自己的合同工具。 应用 代码应使用上述公共入口.

## 发展

所有维护的SDK代码都住在 `src/` 作为类型脚本. `pnpm build` 汇编 npm 输入,主机为全球,懒散的能力块, shell 主机,注入脚本, 服务人员、申报和后端文物 `dist/` 目录。 生成的 JavaScript 从来不是真理的来源, 不应该是 直接编辑.

伊洛赫跑步时间 `iroh/`;其生成的约束和WebAssembly是 所犯 `iroh/prebuilt/` 因此普通软件包构建不需要 Rust/Wasm工具链。 更改后 `iroh/src`,安装 `wasm32-unknown-unknown` 目标, `wasm-bindgen-cli` 匹配被钉住的箱子 版本,和 二分法 `wasm-opt`,然后运行 :

```sh
just build-iroh
```

## 释放

版本跟随SemVer, 标记使用匹配 `vX.Y.Z` 形式。 在标记之前, 更新 `package.json` 和锁文件,然后运行:

```sh
pnpm install --frozen-lockfile
pnpm test
pnpm pack
```

正在推动匹配标记运行 npm 出版工作流程 。 第一次发布 必须由 npm 拥有者发布; 在此之后, 配置此寄存器为 软件包的可信出版商 `.github/workflows/release.yml`。 。 。 .

## 常见问题

### @basilica-digital/maypop-sdk 是什么？

在Maypop上运行的应用程序的浏览器SDK\.

### 如何安装 @basilica-digital/maypop-sdk？

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

### @basilica-digital/maypop-sdk 支持 TypeScript 吗？

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

### @basilica-digital/maypop-sdk 支持 ESM 还是 CommonJS？

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

### @basilica-digital/maypop-sdk 需要什么版本的 Node\.js？

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

### @basilica-digital/maypop-sdk 可以商用吗？

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

### @basilica-digital/maypop-sdk 的下载量有多少？

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

### @basilica-digital/maypop-sdk 还在维护吗？

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