# @gea-ai/app-sdk 中文文档

规范地址：https://npmcn.com/package/%40gea-ai/app-sdk/

版本：0\.1\.261111-alpha\.1
npm 元数据更新时间：2026-11-12T06:00:19.477Z
中文译文更新时间：2026-11-16T01:25:24.380Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40gea-ai/app-sdk
原文对照：https://npmcn.com/package/%40gea-ai/app-sdk/?lang=original
项目主页：https://musegea.com/developers/third-party-apps
源码仓库：https://github.com/bmrlab/gea

弃用说明：This package is deprecated and will no longer receive updates\.

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

- 包体积（解压后）：50.4 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-07-21T15:02:56.345Z
- 最新版本发布：2026-11-12T02:25:10.896Z
- 近 30 天下载量：3936（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：108（近 12 个月 108 个）

## 中文简介

用于与GEA整合的应用程序的公共 SDK.

## 安装

```sh
npm install @gea-ai/app-sdk
```

也可以使用：`pnpm add @gea-ai/app-sdk`、`yarn add @gea-ai/app-sdk`、`bun add @gea-ai/app-sdk`

## README

# `@gea-ai/app-sdk`

用于使用 GEA OAuth 或组织 API 密钥的应用程序的服务器端助手.

每个软件包都有一个 `client_id` 还有一个客户秘密 安装它创建 拥有的组织 `app_resource`;其id是不可改变的安装ID.

保密客户 授权代码 刷新信使 和访问信使 在附录后端。 浏览器代码只应接收应用程序自己的会话.

## OAuth 客户端

```ts
import { createOAuthClient } from "@gea-ai/app-sdk";

const gea = createOAuthClient({
  baseUrl: process.env.GEA_BASE_URL!,
  clientId: process.env.GEA_CLIENT_ID!,
  clientSecret: process.env.GEA_CLIENT_SECRET!,
});
```

SDK需要HTTPS,因为 OAuth 客户资格和无记名标志是 发送到此来源 。 Plain HTTP 只为本地开发主机接受 例如 `musegea.localhost`,它的租户子域, `localhost`和回转.

## 用户授权

当用户从 GEA 打开已安装的应用程序时, 启动 URL 包括公众 `client_id`, (中文(简体) ), `installation_id`,以及 `organization_id`。使用组织标识 作为不信任的选择器,创建随机 `state` 和应用程序中的 PKCE 验证器 后端,然后将浏览器重定向到 GEA :

```ts
const authorizationUrl = gea.getAuthorizationUrl({
  codeChallenge,
  organizationId,
  redirectUri: "https://app.example.com/oauth/callback",
  scope: ["openid", "profile", "offline_access", "resources:read"],
  state,
});
```

GEA 对照 OAuth 客户端验证选择器, 激活安装, 以及 注册用户的活跃成员。 选择者不准许访问 自己来 不支持在没有组织选择者的情况下直接授权 在此版本中.

验证后 `state` 在回调中,交换一次性代码:

```ts
const token = await gea.exchangeAuthorizationCode({
  code,
  codeVerifier,
  redirectUri: "https://app.example.com/oauth/callback",
});
```

答复包括核实 `organization` 财务报告和审定财务报表 `installation` 元数据。 这个 还包括当 `offline_access` 准予:

```ts
const renewed = await gea.refreshUserToken({
  refreshToken: token.refreshToken!,
});
```

刷新符号旋转 。 坚持每个成功者返回的替换 刷新并丢弃上一个值.

当应用程序会话或证书结束时撤销访问权限或刷新令牌 在其他方面不再需要:

```ts
await gea.revokeToken({
  token: token.accessToken,
  tokenTypeHint: "access_token",
});
```

## 租户授权

只为不作为用户的应用级API使用租户代币. 一个 组织本地应用程序省略了安装选择器,因为 GEA 推断它 拥有的组织:

```ts
const tenantToken = await gea.getTenantToken({
  scope: ["organization:read", "resources:read"],
});
```

一个“市场”应用程序提供不可改变的安装ID:

```ts
const tenantToken = await gea.getTenantToken({
  installationId: "019...",
  scope: ["organization:read", "resources:read"],
});
```

绝不接受一个组织发射弹作为授权边界。 租户 符号不包含用户主机,不能调用用户,成员,或 工作空间成员 APIs.

## ORPC 客户端

创建 API 客户端, 使用用户或租户访问符 :

```ts
import { createClient } from "@gea-ai/app-sdk";

const api = createClient({
  accessToken: token.accessToken,
  baseUrl: process.env.GEA_BASE_URL!,
});
```

只有明确接受符号类型和范围的道路可供使用. GEA重新验证 OAuth 客户端,软件包,安装,组织, 属于用户代号的成员,并请求为每个请求提供范围.

`resources.list()` 返回活动组织拥有的资源 与所有工作空间或至少一个特定工作空间共享。 用户拥有和 不包括仅限用户的资源.

## 代理聊天

代理聊天 API 需要用户访问令牌 `agents:read`, (中文(简体) ), `agent_chats:read`,和(或) `agent_chats:write`。租户代币不能使用这些 范围,因为每个聊天都以授权用户的身份运行在一个明确的 工作空间.

从符号响应中创建工作空间客户端 和您的应用程序所选择或配置的工作空间弹片 :

```ts
import { createWorkspaceClient } from "@gea-ai/app-sdk";

const gea = createWorkspaceClient({
  accessToken: token.accessToken,
  baseUrl: process.env.GEA_BASE_URL!,
  organizationSlug: token.organization.slug,
  workspaceSlug: appWorkspaceSlug,
});

const agents = await gea.agents.list();
const run = await gea.agentChats.start({
  agentId: agents[0]!.id,
  message: "Summarize the latest project context.",
});

const { chatId } = run;
const stream = await gea.agentChats.openStream({ chatId });
// Consume stream.body as an AI SDK UI message stream.

await gea.agentChats.sendMessage({
  chatId,
  message: "Turn that into three action items.",
});

const page = await gea.agentChats.messages.list({ chatId, limit: 50 });
```

当SDK第一代理暂停工具批准时,请读取待处理的助手 发送信息并提交决定,而不重复工具输入:

```ts
await gea.agentChats.respondToToolApprovals({
  chatId,
  messageId: pendingMessage.id,
  responses: [{ id: pendingApproval.id, approved: true }],
});
```

同样的"聊天"方法也与"后人"合作. 运行时间选择为自有 被选中的代理服务器侧元数据; 工具批准响应是 仅接受SDK第一代理工作聊天.

Agent APIs拒绝只组织RPC路线. 工作空间的子弹必须 显示在请求路由中; GEA 从未为一个 第三方应用.

GEA生成持续聊天和消息ID. 读取 `chatId` 产生结果 `agentChats.start()` 并用于后流,消息,和历史召来. `start()` 财务报告和审定财务报表 `sendMessage()` 目前不提供一能重试 语义, 因此在模糊后不要自动重试两个操作 网络故障. 在相应的范围下,应用程序可以读取或继续 所选组织中授权用户拥有的任何根聊天,以及 工作空间;聊天不必来自该应用程序。 创建聊天 通过此 API 记录源安装 `chat.metadata` 页:1 仅是出处,不是授权边界.

`openStream()` 交换用户代号服务器侧以换取短寿命, 聊天串流能力,然后以 那个能力 该能力仍然与该确切的OAuth赠款有关: 重新检查补助金、其阅读范围和用户当前工作空间的访问 当溪口被打开的时候, 取消补助金或取消工作空间访问使 已经发布的能力无法使用。 保留用户符和流 响应; 只转发您自己的前端需要的数据。 吉亚 简短地等待一个新的聊天程序来注册其流 。 如果反应是 `503` 与 `Retry-After`电话 `openStream()` 同样的 `chatId`A级 `204` 响应是指在串流消费者前完成的运行; 呼叫 `agentChats.messages.list()` 同样的 `chatId` 读取最后信件.

流电能力只包含不透明的授电、安装和聊天 参考文献。 GEA 解决用户、组织、安装和工作空间 当流打开时服务器侧. 信件页面保存代理发送元数据 但编辑GEA用户的内部身份和名称. 使用 OAuth 对称 `sub` 财务报告和审定财务报表 当您的应用程序需要用户身份时,明确授权的配置文件请求.

## API 密钥代理聊天

使用 `createApiKeyWorkspaceClient` 对于API键唯一的代理表面。 一个用户 键省略 `externalUserId` 他只派遣他的证明

```ts
import { createApiKeyWorkspaceClient } from "@gea-ai/app-sdk";

const gea = createApiKeyWorkspaceClient({
  apiKey: process.env.GEA_API_KEY!,
  baseUrl: process.env.GEA_BASE_URL!,
  organizationSlug: "acme",
  workspaceSlug: "research",
});

const chatId = crypto.randomUUID();
const stream = await gea.agentChats.run({
  agentId: "agent-019...",
  chatId,
  message: "Summarize this workspace.",
});

if (!stream.ok || !stream.body) {
  throw new Error(`Agent Chat failed: ${stream.status}`);
}
```

团队密钥必须为一个目录身份创建客户端. 设定 `externalUserId` 到精确的大小写敏感目录 `principalId` 编号 : `externalId`; SDK 发送为 `x-user-id` 每项RPC请求:

```ts
const gea = createApiKeyWorkspaceClient({
  apiKey: process.env.GEA_TEAM_API_KEY!,
  baseUrl: process.env.GEA_BASE_URL!,
  externalUserId: customerDirectoryPrincipalId,
  organizationSlug: "acme",
  workspaceSlug: "research",
});
```

部署必须能够 `features.teamApiKeyIdentityDelegation`组合键 仅限于此代理API及其三个代理范围 一般范围 ORPC 路由只接受个人密钥.

客户暴露 `agents.list()`, (中文(简体) ), `agentChats.run()`, (中文(简体) ), `agentChats.openStream()`, (中文(简体) ), `agentChats.messages.list()`,以及 `agentChats.files.resolve()`。 。 。 . `run()` 发送一个 `POST /api/chat` 请求和 直接返回它的 AI SDK UI 消息流. 在服务器上存储两种API密钥. 不转发团队密钥或让一个 浏览器选择 `x-user-id` 独立于经认证的客户用户.

API 密钥代理访问使用独立的 `agents.read`, (中文(简体) ), `agent_chats.read`, (中文(简体) ), 财务报告和审定财务报表 `agent_chats.write` 范围; OAuth 的结号限制范围仍然保留 不变. `run()` 需求 `agent_chats.write`· ; `openStream()` 并坚持 信件读取要求 `agent_chats.read`。两个直接的 HTTP 请求发送 相同的API 密钥, 对于一个团队密钥, 相同的固定 `x-user-id`全球环境评估决定 身份并重新检查密钥、 用户、 聊天所有权和工作空间访问 每一个请求.

不自动重试 `run()` 经过一个模糊的结果。 A 类 `503` 流线 答复可通过拨打重新测试 `openStream()` 与现有 `chatId`· ; 之后 `204`,读取最后的恒定消息 `agentChats.messages.list()`。 。 。 .

要附加文件, 请打电话 `files.upload({ file, filename })`它发送一个 多块 `POST /api/files` 并附有同一份全权证书 `agent_chats.write`,然后返回原始数据 `Response`页:1 `201` 机构包含 文件 `id`。通过这些标识作为 `fileIds` 改为 `run()` 加上字符串 `message`数字 :

```ts
const uploaded = await gea.files.upload({
  file: pdfBlob,
  filename: "report.pdf",
});
if (uploaded.status !== 201) {
  throw new Error(`Upload failed: ${uploaded.status}`);
}
const { id } = await uploaded.json();

const stream = await gea.agentChats.run({
  agentId: "agent-019...",
  chatId,
  fileIds: [id],
  message: "Analyze this report.",
});
```

每个文件最多20个MIB,最多接受10个运行 `fileIds`。一个文件可以 仅供上传该文本的用户在同一工作空间使用一次; a 无法使用 id 使 `run()` 返回时 `404` 没有开始运行.

一个代理人指的是它用下方的Markdown路径生成的文件 `/workspace` 内 其答案文本,例如 `![Revenue chart](/workspace/charts/revenue.png)` 或者说 `[Q3 report](/workspace/reports/q3.pdf)`; 流和持续消息 保持文本不变。 要显示这样的文件, 请将路径交换为 临时 URL 与 `agentChats.files.resolve({ chatId, path })`它使用 工作空间RPC和全权证书与 `messages.list` 和要求 `agent_chats.read`数字 :

```ts
const file = await gea.agentChats.files.resolve({
  chatId,
  path: "/workspace/charts/revenue.png",
});
// { path, contentType, sizeBytes, url }
```

`url` 临时 : 每次给出答案后再次解析路径 永远不要储存它。 PNG、JPEG、WebP和GIF文件返回可嵌入的URL; PDF, HTML, SVG 和所有其他类型都返回附件下载 URL. 这个 文件在请求时被读取, 因此一个覆盖的文件显示其当前 内容,而删除的文件、目录、符号链接或聊天用户 不拥有返回 `NOT_FOUND`。非条形路径(除了一条 绝对 `/workspace/...` 没有文件路径 `.`, (中文(简体) ), `..` 或空块)是 以 `BAD_REQUEST`,并且存储或签名失败表面为 `INTERNAL_SERVER_ERROR` 而不是作为一个缺失的文件。 API 密钥保留在 服务器,只将临时URL传递给浏览器.

### AI SDK浏览器集成

教书是 [代理反应](https://musegea.com/developers/third-party-apps-agent-chat) 在 GEA 开发者文档中。 这里包含同样的SDK核心模式 读者.

GEA 返回一个 [AI SDK 用户界面消息流](https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol), (中文(简体) ), 但GEA用户访问符和短寿命流能力必须保留 在应用程序服务器上。 在自己的应用程序中显示一个认证的路由,打开 GEA流并转发其正文和协议头到浏览器:

```ts
// app/api/gea-agent-chat/route.ts
import { createWorkspaceClient } from "@gea-ai/app-sdk";

const streamHeaders = [
  "cache-control",
  "content-type",
  "retry-after",
  "x-vercel-ai-ui-message-stream",
] as const;

async function getGeaForCurrentUser() {
  // Load and refresh the current user's OAuth token in your app backend.
  const connection = await loadUserGeaConnection();

  return createWorkspaceClient({
    getAccessToken: connection.getAccessToken,
    baseUrl: "https://musegea.com",
    organizationSlug: connection.organizationSlug,
    workspaceSlug: connection.workspaceSlug,
  });
}

export async function POST(request: Request) {
  const { agentId, message } = await request.json();
  const gea = await getGeaForCurrentUser();

  // Do not automatically retry this write after an ambiguous network failure.
  const run = await gea.agentChats.start({ agentId, message });
  return Response.json({ chatId: run.chatId });
}

export async function GET(request: Request) {
  const search = new URL(request.url).searchParams;
  const chatId = search.get("chatId");
  const view = search.get("view");
  if (!chatId || (view !== "messages" && view !== "stream")) {
    return new Response("chatId and view are required", { status: 400 });
  }

  const gea = await getGeaForCurrentUser();
  if (view === "messages") {
    return Response.json(
      await gea.agentChats.messages.list({ chatId, limit: 50 }),
    );
  }

  const upstream = await gea.agentChats.openStream({ chatId });
  const headers = new Headers();

  for (const name of streamHeaders) {
    const value = upstream.headers.get(name);
    if (value) headers.set(name, value);
  }

  return new Response(upstream.body, {
    headers,
    status: upstream.status,
    statusText: upstream.statusText,
  });
}
```

浏览器可以使用 `ai` 解码中继响应的软件包。 这个 运算子类曝光AI SDK的普通响应-流解析器; 浏览器 无需了解电线协议本身:

```tsx
"use client";

import { DefaultChatTransport, readUIMessageStream, type UIMessage } from "ai";
import { useState } from "react";

class GeaStreamTransport extends DefaultChatTransport<UIMessage> {
  decode(stream: ReadableStream<Uint8Array>) {
    return this.processResponseStream(stream);
  }
}

const transport = new GeaStreamTransport();

function textFromMessage(message: UIMessage) {
  return message.parts
    .filter((part) => part.type === "text")
    .map((part) => part.text)
    .join("");
}

async function openStream(chatId: string) {
  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await fetch(
      `/api/gea-agent-chat?view=stream&chatId=${encodeURIComponent(chatId)}`,
    );
    if (response.status !== 503) return response;

    const retryAfter = Number(response.headers.get("retry-after"));
    await response.arrayBuffer();
    await new Promise((resolve) =>
      window.setTimeout(
        resolve,
        Number.isFinite(retryAfter) && retryAfter > 0
          ? Math.min(retryAfter * 1000, 5000)
          : 500,
      ),
    );
  }

  throw new Error("The Agent stream was not ready after three attempts.");
}

export function AgentResult() {
  const [text, setText] = useState("");
  const [persistedMessages, setPersistedMessages] = useState<unknown>(null);

  async function run() {
    const startResponse = await fetch("/api/gea-agent-chat", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        agentId: "agent-019...",
        message: "Summarize this workspace.",
      }),
    });
    if (!startResponse.ok) throw new Error("Could not start Agent chat");
    const started = (await startResponse.json()) as { chatId: string };

    const response = await openStream(started.chatId);

    // 204 means the run completed before the stream attached. In that case,
    // skip the loop and read the persisted result below.
    if (response.status !== 204) {
      if (!response.ok || !response.body) throw new Error("Stream failed");

      const chunks = transport.decode(response.body);
      for await (const message of readUIMessageStream<UIMessage>({
        stream: chunks,
        terminateOnError: true,
      })) {
        setText(textFromMessage(message));
      }
    }

    const messagesResponse = await fetch(
      `/api/gea-agent-chat?view=messages&chatId=${encodeURIComponent(started.chatId)}`,
    );
    if (!messagesResponse.ok) throw new Error("Could not load final messages");
    setPersistedMessages(await messagesResponse.json());
  }

  return (
    <section>
      <button onClick={run} type="button">
        Run Agent
      </button>
      <pre>{text}</pre>
      <pre>{JSON.stringify(persistedMessages, null, 2)}</pre>
    </section>
  );
}
```

流出后持续读取是真相的来源 完成得太快,无法附加流或当浏览器重新连接时。 对a 完成 Next.j 的操作,并进行更详细的错误处理,请跟踪 公开 [代理反应](https://musegea.com/developers/third-party-apps-agent-chat) 教学.

## 常见问题

### @gea-ai/app-sdk 是什么？

用于与GEA整合的应用程序的公共 SDK\.注意：该包已被作者标记为弃用——This package is deprecated and will no longer receive updates\.

### 如何安装 @gea-ai/app-sdk？

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

### @gea-ai/app-sdk 支持 TypeScript 吗？

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

### @gea-ai/app-sdk 支持 ESM 还是 CommonJS？

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

### @gea-ai/app-sdk 可以商用吗？

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

### @gea-ai/app-sdk 的下载量有多少？

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

### @gea-ai/app-sdk 还在维护吗？

最新版本 0\.1\.261111-alpha\.1 发布于 2026/11/12（3 天前）；至今共发布 108 个版本，其中过去 12 个月发布了 108 个；首次发布于 2026/07/21。作者已将其标记为弃用，新项目建议寻找替代方案。

