# @aglit-ai/sdk 中文文档

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

版本：0\.1\.17208
npm 元数据更新时间：2026-11-02T18:19:23.756Z
中文译文更新时间：2026-11-06T09:06:15.089Z
软件包许可：Aglit AI Commercial License

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

原始 npm 页面：https://www.npmjs.com/package/%40aglit-ai/sdk
原文对照：https://npmcn.com/package/%40aglit-ai/sdk/?lang=original
项目主页：https://github.com/Aglit-AI/monorepo/tree/main/packages/sdk
源码仓库：https://github.com/Aglit-AI/monorepo

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

- 包体积（解压后）：1.6 MB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-02-01T01:35:44.900Z
- 最新版本发布：2026-11-02T18:19:23.529Z
- 近 30 天下载量：3671（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

Aglit AI SDK 帮助器 + OpenAPI 驱动的客户端生成条目

## 安装

```sh
npm install @aglit-ai/sdk
```

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

## README

# `@aglit-ai/sdk`

MIT授权SDK针对Aglit AI桌面API和工具运行时间进行建设.

-   需要本地运行的 Aglit AI 桌面应用/ API
-   类型安全 `fetch` 桌面 API 的包装
-   JSON-RPC 工具执行器 `x_aglit_ai_tool_reason`
-   桌面 + 工具构建器 + 提供方 SPI API 的 OpenAPI 规格

> 您必须让 Aglit AI 桌面应用程序/ API 本地运行( 本地主机) 。 设定 `SERVER_PORT`编号 :`PORT`编号 :`AGLIT_DESKTOP_BASE_URL` 视需要而定.

## 加密的私人网站内容

值得信赖的人 `/_sites/bootstrap` shell 可以制作一个普通的设备本地网站 而不将其 HTML,脚本,资产或HTTP API 机构暴露于网关:

```ts
import { createAuthenticatedSiteRuntimeFetch, mountEncryptedSite } from '@aglit-ai/sdk/browser';

const response = await fetch('/_sites/context', { credentials: 'same-origin', cache: 'no-store' });
if (!response.ok) throw new Error('Sign in to this site’s team');
const context = await response.json();
const runtimeFetch = await createAuthenticatedSiteRuntimeFetch({
  deviceId: context.site.deviceId,
  authenticatedEmail: context.user.email,
});
const surface = await mountEncryptedSite(document.querySelector('#site')!, {
  siteName: context.site.name,
  deviceId: context.site.deviceId,
  agentId: context.site.agentId,
  initialPath: new URLSearchParams(location.hash.slice(1)).get('path') ?? '/',
  runtimeFetch,
});
// On teardown: await surface.destroy();
```

单干SDK `site-worker.js` 作为可信,认证 `/_sites/worker.js`,与 `Service-Worker-Allowed: /` 和一个 JavaScript 内容类型. 提供捆绑的外壳密码 `/_sites/bootstrap.js`壳,工人, b. 环境与现有 `/remote-access/api/...` 终点仍受到其 犬形服务器认证和路由许可列表. 其他网站内容是: 仅通过生成 `proxyPrivateSiteRequest` 内部操作 已签名和加密的运行时频道。 裸露的现场饼干从不 替换频道.

该页面持有犬科终点密码;工人没有收到钥匙。 一个 内元信息Channel 绑定精确的顶层外壳, 单用初始 Iframe 导航,以及浏览器拥有的儿童客户端ID. 它返回解密的响应 当地到iframe。 它从不直接获取网站内容或存储内容 或缓存Storage、索引DB或服务人员缓存中的密钥。 答复使用情况 `no-store` 和同一来源的 CSP; 外部内容请求失败。 这个 工人只离开保留网关 `/_sites/*` 财务报告和审定财务报表 `/remote-access/api/*` 向现有的经认证的处理人员提出请求.

坚固的外壳必须活下来 一个封闭的外壳,拒绝会员资格, 缺少端点校验, 或者没有加密返回一个错误 而不是简洁的背面。 工人重新开始失去委托人监护权,所以贝壳 重新连接并重新装入新拥有的 Iframe 。 网站文件共享 来源和代码信任; iframe 是渲染表面, **没有** 隔离 站点本身的脚本与其Aglit SDK能力之间的边界.

Shell 链接使用 `/_sites/bootstrap#path=<encoded-local-path>` 因此应用 路径和查询在工人导航时保持浏览器本地化。 保密 保密 保密 在工人控制页面之前输入的普通 URL 的首页 网络URL必然是路由元数据.

第一个版本支持被绑定的 HTTP 请求机构最多 1 MiB 和个人 不超过8个米B的响应。 无限媒体范围被限定为1个米B部分. 网站饼干、工人登记、外部资源、WebSockets和无限制 HTTP流不是由内容桥传输的. 使用直接的 WebRTC 下面原始的用于活应用/桌面视频和输入.

## 私人网站应用程序和桌面流

浏览器应用程序可以导入 `@aglit-ai/sdk/browser` 不装入本地 证书文件或IPC助手. 本地默认 SDK 条目仍然保留 桌面/服务器集成.

`createDirectRemoteStreamTransport(binding, { baseUrl, runtimeFetch })` 连接 到已认证的WebRTC运行时间. `mountAppStream`, (中文(简体) ), `mountDesktopStream`,以及 `mountRemoteStream` 提供框架中立的视频, 连接状态,和可选指针/键盘控制. 他们使用现有的 OpenAPI生成的信号路由和直通ICE/TURN介质,相同 `aglit-input-reliable` 财务报告和审定财务报表 `aglit-input-volatile` 输入频道为 Aglit .

```ts
import { createAuthenticatedSiteRuntimeFetch, createDirectRemoteStreamTransport, mountAppStream } from '@aglit-ai/sdk/browser';

// binding comes from your authorized backend's exact persisted game chat/window:
// binding: { agentId, deviceId, sessionId, streamId,
//   target: { streamType: 'app', appId, windowId } }
const response = await fetch('/_sites/context', { credentials: 'same-origin', cache: 'no-store' });
if (!response.ok) throw new Error('Sign in to this site’s team');
const context = await response.json();
if (context.site.deviceId !== binding.deviceId) throw new Error('Game device changed');
const encryptedRuntimeFetch = await createAuthenticatedSiteRuntimeFetch({
  deviceId: context.site.deviceId,
  authenticatedEmail: context.user.email,
  runtimeSessionId: binding.sessionId,
});
const surface = mountAppStream(document.querySelector('#game')!, {
  title: "slurp's up!",
  interactive: true,
  transport: createDirectRemoteStreamTransport(binding, {
    baseUrl: window.location.origin,
    runtimeFetch: encryptedRuntimeFetch,
    captureSpeakerAudio: true,
  }),
});
await surface.connect();
// During component/page cleanup:
await surface.destroy();
```

对于桌面, 使用 `mountDesktopStream` 与 `target: { streamType: 'desktop', displayId }` 并省略 `interactive`。 。 。 . 此版本的桌面流只查看: 交互式桌面安装为 拒绝,直接传输则拒绝桌面控制/输入。 显示视频 像素可以不同于Retina上的逻辑原生坐标或缩放捕获; 桌面控制需要cononic验证的逻辑显示范围映射. 提供真正的持续聊天 、 原始注册设备, 以及精确列出的应用程序窗口或 显示后端授权的显示。 ID 选择一个目标; 他们从来不允许访问 . 原始人不会推出应用或创建账户,团队,或设备赠款.

`createAuthenticatedSiteRuntimeFetch` 通过已有的浏览器录入此浏览器 运行时间 auth/ key 流量 。 从经认证的账户和设备获取 `/_sites/context`,从不要求URL。 它重新使用可重复的可复制浏览器 密钥、设备身份验证和现有有管理的指针或指纹 证实UI。 请求通过配置的计算机验证代码 一个真正的代码对话框; 被拒绝的访问和 API- key 要求仍然失败 . 分开的现场饼干只留下来 没有 cookie 或设备密钥被复制到 应用程序 JavaScript. 可选 `runtimeSessionId` 是一个已有的任务/聊天 用于选择服务运行时生成; 认证流分配自己的 单独的加密会话.

结果 **经认证、加密的运行时间** 接收未更改的 生成 `/remote-access/api/...` 网站的 URL 源代码。 网站网关保存其准确路径和查询,包括 URL绑定的加密证明;它从不重写在另一个API前缀后. 通过普通 `fetch` 使用站点 cookie 不确定运行时间 届会。 本地没有宽 SDK 令牌、 浏览器 cookie 导出或提供者终止 媒体倒置被引入.

适配器在精确的加密字节和URL上签有"Cononic v2"的证明, 然后只接受经认证的非限制性成功答复。 它有一个 账户/设备范围每页; 账户、设备或证书更改后重新加载.

App 输入默认关闭 。 与 `interactive: true`,用户明确选择 **掌权** 在授权的直接输入通道打开后。 指针输入 被映射到包含的视频而不是其信箱。 默认模式 发送犬科完整 `keyEvent: press` 手势,包括 浏览器键盘重复,并在指针上完成点击或左键拖动 释放。 中断的指针手势在当地被取消. 从不离开 原生密钥或按钮等待从已消失的取景器中释放出后.

对于需要连续移动的游戏,明确设置 `keyboardMode: 'hold'`。 。 。 . 连接然后需要实际包装的本地助手的广告应用 握有钥匙的能力。 它发送现有 `down`编号 :`up` 一个事件 `keyHoldId` 每一实际持有; `keyHoldRenew: true` 更新保留了这种身份,从不重复按键 召回电话。 同时键保持并存. 更新运行每250 ms 只当视频有焦点时,页面可见,而这个表面有控制. 模糊,隐藏的页面,按键上下拆解在发送发布前停止更新. 在本地入境前已排出/ 更新的包已过期; 无法续签 创建一个控件。 原生倒置/更新也需要保留被捕获的窗口 未来应用的精确焦点窗口, 不聚焦或改变窗口.

本地的帮助者拥有一个独家的应用键盘拥有者 每个进程, 被捆绑在过程的诞生 并承认准确的窗口。 应用输入和全局 来自另一个查看器的键盘事件无法释放或中断这些键. 现有授权的桌面指针控制可能改变焦点; 停止应用 键更新。 缺失的更新将到期 其两秒本土 租赁,每100米检查一次;帮助者EOF/有秩序地关闭也放行. 清理使用 抓取的进程身份,从不聚焦或解决替换应用程序. 过期/解除扣留的身份证不能被重新扣押。 旧运行时间 拒绝控件模式;它们继续支持取景并完成压力. 原生活化和真正的游戏接受仍然需要新的被签名的帮助. 突然帮助崩溃、SIGKILLL或已中止的本地进程无法进行清理; 到期保障要求当地援助者保持预定时间和健康. 直播按钮控件拖放和独立的修改器拖放仍然不支持 . 音频开始变音以遵守浏览器的回放要求; 网站可以曝光 使用 `surface.video.muted`。目前所有观众共享 相同运行的应用程序和玩家状态。 本地控件模式允许一个输入拥有者, 而 键被持有; Kake 控制按钮本身不赋予额外权限 .

打电话 `surface.destroy()` 卸载以中止信号,取消待输入,以及 只删除此精确的查看器会话。 认证/信号失败会关闭 pal; 在恢复授权的运行时会话后创建新的表面. 提供创建和当地的社民党准备状态在全部内分开 60秒启动最后期限,匹配网页浏览器的浏览器兼容路径.

见 `examples/site-game.ts` 为最小的游戏包装.

## 安装

```bash
pnpm add @aglit-ai/sdk
# or: npm install @aglit-ai/sdk
```

## 快速启动( TypeScript)

```ts
import { createDesktopClient, executeTool } from '@aglit-ai/sdk';

const SERVER_PORT = process.env.SERVER_PORT ?? '49117';
const baseUrl = `http://127.0.0.1:${SERVER_PORT}`;
const agentId = 'root-agent';

const desktop = createDesktopClient({ baseUrl });

// Call REST endpoints (typed from OpenAPI)
const tasks = await desktop.GET('/tasks');
console.log(tasks.data?.tasks?.length);

// Execute tools via IPC (requires x_aglit_ai_tool_reason)
const response = await executeTool({
  agentId,
  request: {
    jsonrpc: '2.0',
    id: 'sdk-run-terminal',
    params: {
      name: 'p1_terminal',
      arguments: {
        action: 'open',
        x_aglit_ai_tool_reason: 'SDK example: open terminal via IPC',
      },
    },
    context: {
      sessionId: `sdk-terminal-${Date.now()}`,
      agentId,
    },
  },
});
console.log('tool response', response.data?.result);
```

## 快速启动 (JavaScript)

```js
const { executeTool } = require('@aglit-ai/sdk');

(async () => {
  const response = await executeTool({
    agentId: 'root-agent',
    request: {
      jsonrpc: '2.0',
      id: 'sdk-ipc-example',
      params: {
        name: 'p1_todo',
        arguments: {
          action: 'list',
          x_aglit_ai_tool_reason: 'SDK IPC example: list todos',
        },
      },
      context: {
        agentId: 'root-agent',
        sessionId: 'sdk-ipc-session',
      },
    },
  });
  console.log(JSON.stringify(response, null, 2));
})();
```

## IPC 工具执行

本地工具执行运行于 IPC 经纪人之上, 所以回回回路上没有未经认证的 HTTP 表面 . 如果您将 IPC 配置存储到自定义的某处, 设置 `AGLIT_SDK_IPC_CONFIG_PATH` 因此( 默认 : `<user-data>/ipc/sdk-ipc.json`时 `<user-data>` 实值 `~/Library/Application Support/Aglit AI/` (原始内容存档于2018-09-28). on macOS.

在macOS上,SDK线路通过一个签名的助手请求进入XPC经纪人. 经纪人只接受 信任的应用程序的请求, 如果新应用程序请求访问, 则会在桌面应用程序中提示 。 套接字 结束点从未写入磁盘 。 用于地方发展 `AGLIT_SDK_XPC_ONLY=0` 保留遗产 套接字配置 .

总是包含 `x_aglit_ai_tool_reason` 并传递结构化的参数,而不是生壳字符串。 IPC经纪人 也执行UI中看到的相同的工具政策,包括批准流和记录. 从 Aglit 聊天终端继承开始的脚本 `AGLIT_AGENT_ID`, (中文(简体) ), `AGLIT_SESSION_ID`,以及 `AGLIT_SDK_MODULE_PATH`。将捆绑的 SDK 装入 `require(process.env.AGLIT_SDK_MODULE_PATH)` 以避免旧的工作空间副本. `executeTool` 自动使用所继承的会话ID; a 明确请求 `_meta.sessionId` 以优先为准.

## 实例

SDK飞船即时运行的通用自动化表面实例. 总是包含 `x_aglit_ai_tool_reason` 解释为什么使用这一工具.

### 终端命令

```ts
await executeTool({
  agentId: 'root-agent',
  request: {
    jsonrpc: '2.0',
    id: 'open-terminal',
    params: {
      name: 'p1_terminal',
      arguments: {
        action: 'open',
        x_aglit_ai_tool_reason: 'SDK example: open terminal',
      },
    },
    context: { sessionId: 'sdk-shell', agentId: 'root-agent' },
  },
});

await executeTool({
  agentId: 'root-agent',
  request: {
    jsonrpc: '2.0',
    id: 'type-ls',
    params: {
      name: 'p1_terminal',
      arguments: {
        action: 'type',
        windowId: '<window-id-from-open>',
        text: 'ls -la /tmp',
        submit_command: true,
        x_aglit_ai_tool_reason: 'SDK example: list temp files',
      },
    },
    context: { sessionId: 'sdk-shell', agentId: 'root-agent' },
  },
});
```

### 浏览器自动化

使用SDK兼容适配器进行结构化浏览器动作. 适配器执行 仅限 `p1_codex_browser` 登记电话,保留聊天授权和批准, 并返回准确的本地标签 ID。 页面评价为只读; 使用本地 点击/填充动作以更改页面.

```ts
import { executeNativeControl, unwrapNativeControlResult } from '@aglit-ai/sdk';

const call = (args: Record<string, unknown>, reason: string) => executeNativeControl({
  toolName: 'p1_codex_browser', agentId: 'root-agent', sessionId: 'sdk-browser', args, reason,
});
const nav = unwrapNativeControlResult(await call(
  { action: 'navigate', url: 'https://example.com' }, 'Open example.com'
));
if (!nav?.tabId) throw new Error('Native browser returned no exact tab ID');
await call({ action: 'execute_javascript', tabId: nav.tabId, code: 'document.title' },
  'Read the page title');
```

### 创建聊天会话

```ts
import { createDesktopClient } from '@aglit-ai/sdk';

const desktop = createDesktopClient({ baseUrl });

const chat = await desktop.POST('/chats', {
  body: {
    agentId: 'root-agent',
    initialText: 'Say hello from the SDK',
  },
});
console.log('chat id', chat.data?.chat?.id);
```

## 运行组合示例

请确定桌面应用程序/ API 正在本地运行, 然后 :

```bash
pnpm --filter @aglit-ai/sdk run build        # if you haven't built yet
pnpm --filter @aglit-ai/sdk run test:examples
```

通过环境配置 :

-   `AGLIT_DESKTOP_BASE_URL` (管理主机/端口)
-   `SERVER_PORT` 或者说 `PORT` (默认 49117 prod; 49217 为本地 dev)
-   `AGLIT_AGENT_ID` (默认) `root-agent`(中文(简体) )

## OpenAPI 光谱

SDK 解析当前 OpenAPI 源文件 `@aglit-ai/types`数字 :

-   桌面 API : `@aglit-ai/types/schema/api.openapi.yaml`
-   工具构建器 API : `@aglit-ai/types/schema/tools-api.openapi.yaml`
-   提供方 SPI API : `@aglit-ai/types/schema/provider-spi.openapi.yaml`

## 本土控制移徙

`executeNativeControl({toolName, args, reason, agentId, sessionId})` 调整结构 自定义工具浏览器/应用程序动作 `p1_codex_browser` 财务报告和审定财务报表 `p1_codex_computer`现有 本地执行/抓捕/流/焦点呼叫通过. 退休的身份证仍然被拒绝.

```ts
import { executeNativeControl } from '@aglit-ai/sdk';
const result = await executeNativeControl({
  toolName: 'p1_codex_browser',
  args: {action: 'navigate', url: 'https://example.com'},
  reason: 'Open the requested example page',
  agentId, sessionId,
});
```

适配器保存精确的本地目标, 保存打字/ 提交标记, 返回原始 证明和熟悉的结果字段,永远不要重放不确定的变异。 页面评价 只读。 授权 DOM 输入计划使用 `aglitNativeClick(element)` 财务报告和审定财务报表 `aglitNativeFill(element, text)` 检查期间;适配器执行这些行动 之后通过本地输入 API. 不使用页面突变,CDP或终端倒置. 本地自定义运行时间包这个相同的SDK适配器,所以不需要新的SDK依赖.

原生控制仍然需要代理商现有的不受限制的剖面图和明确 进入。 上传/备案权限仍然是单独的本地赠款。 下载返回已保存 直接路径; 旧的下载进度流 ID 不支持。 App 窗口请求为 根据输入前的私人捕获收据进行核查;模棱两可/匹配目标 失败。 被编码的录音和一些遗留下来的只使用桌面的API没有本土的等效.

## 建设和部署

运行 `pnpm run build` 在此之前 `pnpm run deploy`. 部署需要汇编 输入点和捆绑的 OpenAPI 计划,然后发布已经建成的 SDK 使用 `package.json` 和现有的登记册全权证书. 部署不会重建、突起版本或启动交互式登记册登录.

## 常见问题

### @aglit-ai/sdk 是什么？

Aglit AI SDK 帮助器 \+ OpenAPI 驱动的客户端生成条目

### 如何安装 @aglit-ai/sdk？

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

### @aglit-ai/sdk 支持 TypeScript 吗？

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

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

@aglit-ai/sdk 使用 Aglit AI Commercial License 许可。声明的许可为 Aglit AI Commercial License，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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