SDK v0.4.3 · Node.js 20+

项目先在本地建立，
再同步云端备份

Zera 本地 SDK 先创建真实工作目录与项目清单，再登记云端镜像；连接器密钥、店铺关系和真实平台 API 调用仍留在用户的 macOS 或 Windows 设备。

下载 SDK 查看文档
Local项目创建源0云端平台密钥Retry断网可重试
LOCAL EXECUTION PATH
Z
BACKUP MIRRORZera 云端

项目镜像 · 同步游标 · 结构化备份

不创建本地目录
登记镜像并同步
L
LOCAL SDK用户本地设备

系统钥匙串 · 本地审批 · Agent 执行

先建立工作目录
本机直接请求
API
PLATFORM API淘宝与其他平台

用户自己的 AppKey 与平台身份

平台规则约束
DOWNLOADS

选择你的本地运行环境

两种下载均包含完整 SDK；平台入口会自动启用对应的系统安全凭证存储。

01
macOS

Keychain 版本

使用系统 Keychain 保存设备会话与连接器密钥，不写入明文配置文件。

下载 SDK
02
Windows

DPAPI 版本

使用 CurrentUser DPAPI 加密本地凭证，密文仅能由当前 Windows 用户解密。

下载 SDK
安装下载包npm install ./zera-connector-sdk-{macos|windows}-0.4.3.tgz
SHA-2561e468b8d1b587eadf4f78b95457a2fe762210745f3b79fa50c2201a9044d7f1d两个平台下载使用同一份跨平台源码包，因此校验值相同。
QUICK START

从本地建项目到云端备份

项目以本地工作目录为起点；云端只登记镜像并同步明确选择的数据。连接外部平台时，用户仍使用自己的平台开发者身份。

  1. 01
    完成一次主登录

    桌面客户端建立账号级设备会话；项目同步和连接器此后只静默复用，不再发起登录授权。

  2. 02
    本地创建项目

    SDK 先建立工作目录、数据目录和原子项目清单；断网也能完成。

  3. 03
    登记云端镜像

    只发送项目身份和清单摘要，不发送本地绝对路径。

  4. 04
    备份并持续同步

    首次快照分批幂等写入，之后继续使用游标与 CAS 增量同步。

local-project.mjsmacOS / Windows
import { createMacOSConnectorSdk } from
  "@lumii/local-client/macos";

// Windows 使用：
// import { createWindowsConnectorSdk }
//   from "@lumii/local-client/windows";

const sdk = createMacOSConnectorSdk({
  baseUrl: "https://tradeos.digitalrobotics.io",
  approvalHandler: async (action) =>
    confirmLocally(action),
});

// 仅由桌面客户端的主登录动作调用一次；重复调用会复用已有会话。
await sdk.oauthClient.authenticate();
// 登录或启动后按需读取一次账号长期有效的连接器开关。
await sdk.manager.synchronize();

const project = await sdk.projects.create({
  tenantId: "tnt_example",
  name: "我的本地项目",
  metadata: selectedLocalPath
});

// 断网时项目仍已在本地创建：
if (project.cloud.status === "pending") {
  await sdk.projects.register(project.metadata);
}

await sdk.projects.backupSnapshot(
  project.metadata,
  { mutations: initialLocalRecords }
);
DRIVER CONTRACT

用统一接口承载不同平台

淘宝、独立站和企业系统都由本地驱动实现；Agent 只看到账号已开通的连接器能力。

const driver = {
  manifest: {
    id: "taobao",
    version: "1.0.0",
    topology: "local",
    capabilities: [
      { id: "order.read", approval: "auto" },
      { id: "inventory.write", approval: "confirm" }
    ]
  },

  async connect({ credentials }) {
    return createPlatformClient(credentials);
  },

  async execute({ connection, capability, input }) {
    return connection.invoke(capability, input);
  }
};
01
Manifest

声明连接器 ID、版本、运行位置、能力范围和每项能力的本地审批等级。

02
Connect

只在本地进程中读取系统凭证并创建平台客户端，不把凭证返回云端。

03
Execute

先检查账号开通状态和 capability，再执行驱动；受控写操作必须经过审批回调。

04
Audit

本地应用可以记录动作、结果和耗时；SDK 不上传输入、响应或密钥。

CONTROL PLANE API

SDK 调用的云端接口

项目接口接收镜像元数据与明确同步的结构化记录；连接器接口只处理目录和账号权限。设备只在主登录时建立一次 OAuth 会话，同步与连接器静默复用，不存在连接器专属登录或设备授权。两类接口都不接受本地绝对路径、AppKey 或平台密钥。

POST/api/v1/project-mirrors

登记本地项目的云端备份镜像，不上传工作目录路径

POST/api/v1/projects/:id/sync/bootstrap

分批接收首次结构化数据备份，支持幂等重试

GET/api/v1/connectors/catalog

读取连接器目录、接入方式和能力范围

GET/api/v1/me/connector-entitlements

按需读取账号长期有效的连接器开通状态

POST/api/v1/oauth/token

使用系统安全存储中的 Refresh Token 静默刷新15分钟访问令牌

SECURITY BOUNDARY

云端备份项目数据，
但不掌握本地工作目录。

云端保存
  • 项目镜像与清单摘要
  • 明确同步的结构化项目记录
  • 游标、回执与备份版本
仅本地保存
  • 工作目录绝对路径
  • AppKey、Secret 与 Token
  • 店铺和平台账号关系