@newton-cloud/sdk

面向浏览器的无头 TypeScript SDK，负责创建任务、轮询状态、管理消息和业务资源，并通过 HTTPS 调用浏览器安全网关。

如何选择

| 需求 | 安装包 | | --- | --- | | 在 React 应用中开箱即用地接入完整 Agent | @newton-cloud/react | | 自行组合框架或界面，只使用任务状态与控制能力 | @newton-cloud/sdk | | 只使用受控 React 组件和默认样式 | @newton-cloud/ui | | 在自己的服务器上部署浏览器安全网关 | @newton-cloud/server |

包之间的关系

• npm 运行时依赖：@newton-cloud/react 精确依赖 @newton-cloud/sdk 和 @newton-cloud/ui，安装 React 集成时会自动安装这两个包。
• HTTPS 部署关系：@newton-cloud/sdk 通过 HTTPS 调用 @newton-cloud/server 或兼容的企业网关，再由网关访问 Newton Cloud Open API。
• 独立使用：@newton-cloud/ui 不依赖 SDK，可由应用直接传入 props 和处理交互意图。
• 独立部署：@newton-cloud/server 不会进入浏览器 bundle，也不会随 React 集成自动安装或部署。

安装

固定精确版本安装，不依赖可移动 dist-tag：

npm install --save-exact @newton-cloud/[email protected]

License

Apache-2.0。Copyright 2026 Newton Cloud Open Contributors.

运行环境边界

• SDK 用于由 Vite、ICE 3 / Webpack 5 或其他兼容 ESM bundler 构建的浏览器应用。
• serverBase 必须指向 @newton-cloud/server 或兼容的企业浏览器安全网关，不得直接指向 Newton Cloud Open API。
• 浏览器代码不得包含 app secret、access token、签名凭证或其他服务端凭证。
• 当前支持范围是浏览器 ESM bundler；Node.js 原生 ESM、CommonJS、SSR 和 Next.js server runtime 不属于本包的兼容性承诺。

基本用法

import { NewtonAgent } from '@newton-cloud/sdk';

const agent = new NewtonAgent({
  serverBase: 'https://newton-gateway.example.test',
});

const unsubscribe = agent.subscribe(state => {
  console.log(state.status, state.messages);
});

await agent.sendMessage('Summarize the latest task output');
unsubscribe();

目标服务必须通过 CORS 策略允许前端 origin。HTTPS 页面必须使用 HTTPS 服务地址，避免被浏览器作为 mixed content 拦截。

业务资源、刷新与 replay

state.businessData 是与消息 block 并列的 canonical business resource 视图。每个资源以 descriptor 标识请求上下文，以 origin 区分 live / replay，并通过 phase: 'loading' | 'ready' | 'error' 和可选 data 表达生命周期。id、status、 fetchParams、tableData 等字段是现有消费者的兼容投影，不应作为新业务状态机的输入。

当前 followOrder policy 支持显式的一次性刷新：

import {
  AgentBusinessActionError,
  NewtonAgent,
} from '@newton-cloud/sdk';

async function refresh(agent: NewtonAgent, resourceId: string) {
  try {
    await agent.executeBusinessAction(resourceId, { type: 'refresh' });
  } catch (error) {
    if (error instanceof AgentBusinessActionError) {
      console.error(error.code); // resource_not_found | unsupported_action
    }
    throw error;
  }
}

刷新复用对应 runtime policy 的 request builder，不会启动 timer、自动重复请求或引入 refreshing phase。其他未声明该 action 的 policy 会以 unsupported_action 失败。

myOrders / RiskOrder 两个订单场景 policy 额外支持远程分页 action { type: 'changePage', page }：页码作为 policy-owned runtime state { page, confirmedPage } 在 I/O 前原子采用，每个 action 成功统一对账 confirmedPage = 本次请求页；无 canonical data、页码越界或不支持分页的 policy 在 I/O 前本地失败。两场景响应的 total 是契约保证， 缺失或非法按请求错误处理并保留旧数据与页码状态。

afterSale policy 额外支持场景中立 action { type: 'changeFilter', filter: { orderRefundListParam } | null }。generic controller 不解释 filter；该 policy 先以 stage: 'cascadeOptions' 拉取级联树，再由非空 filter 拉取列表， null 会重查级联选项。已选态使用 { filter, page, confirmedPage, cascadeOptions }，未选态使用 { filter: null, cascadeOptions }，并复用 changePage 的远程分页语义。所有请求都按 stage 严格 allowlist 构造，不携带 chunk 中的 followUps、身份字段或未知参数。

历史业务资源可以通过窄 replay API 重新进入同一 ingestion / policy / fetch / normalize 路径：

await agent.replayBusinessResources({
  entries: [
    { taskId: 'task-1', chunk: historicalComplexTableChunk },
  ],
});

replay 只接受 complex_table chunk，并等待已接受资源的初始化 fetch settle；它不会恢复 messages、完整 conversation、pending interaction、task polling 或多 session 历史。

企业兼容网关路径

企业网关的 method、请求体、响应、HTTP 状态、轮询游标和任务生命周期与默认任务 API 完全一致， 但路径不同时，可以通过 taskPaths 声明相对路径：

const agent = new NewtonAgent({
  serverBase: 'https://agent.isv.example.com/gateway',
  taskPaths: {
    createTask: '/internal/newton/create',
    getTask: '/internal/newton/query',
    resumeTask: '/internal/newton/resume',
    killTask: '/internal/newton/stop',
    fetchTask: '/internal/newton/fetch',
  },
});

taskPaths 只接受以单个 / 开始、无 fragment 的同服务相对路径。未配置的 operation 回退到 /api/newton/task/* 默认路径；多域名或动态路由仍由高级 request executor 自行处理。

自定义 request executor

已有统一 HTTP 封装的应用可以注入 request executor。最终路径和网关请求体仍由 SDK 负责构造：

import axios from 'axios';
import {
  NewtonAgent,
  type NewtonRequestExecutor,
} from '@newton-cloud/sdk';

const request: NewtonRequestExecutor = async req => {
  const response = await axios.request({
    url: req.url,
    method: req.method,
    headers: {
      ...req.headers,
      Authorization: getEnterpriseToken(),
      'x-tenant-id': currentTenantId(),
    },
    data: req.body,
    signal: req.signal,
    validateStatus: () => true,
  });
  return { status: response.status, data: response.data };
};

const agent = new NewtonAgent({
  serverBase: 'https://agent.isv.example.com',
  taskPaths: {
    createTask: '/internal/newton/create',
    getTask: '/internal/newton/query',
  },
  request,
});

executor 可以添加浏览器侧会话或企业上下文，但不得包含 app secret、上游 access token 或签名材料。企业网关或 兼容服务必须真实校验身份，并校验当前用户/租户对 taskId、sessionId 的操作权限。

如果企业统一网络层只是在标准网关响应外增加 { code, result, requestId } 等 HTTP envelope，可以用 transformResponse 解包回 { success, data, eagleTraceId? }。 它不能重命名业务入参、补造轮询游标或替代缺失的 resume/kill/fetch。