@zleap-ai/sag-sdk

简体中文 | English

要求 Node.js ≥ 20.19，使用 npm install @zleap-ai/sag-sdk 安装。支持 ESM、CommonJS 和 NodeNext 声明。SDK 不安装 CLI，不读取 Profile、YAML 或环境凭据，不默认选择 localhost，不打开浏览器、不处理进程信号，也不输出终端内容。

公开入口

• @zleap-ai/sag-sdk：SagSdkError 及通用错误、通知、诊断类型。
• @zleap-ai/sag-sdk/personal：SagClient、地址规范化、个人结果和状态汇总。
• @zleap-ai/sag-sdk/enterprise：createEnterpriseClient、连接与账号适配、知识、文件夹和上传类型。

根入口不聚合产品运行时。原始 HTTP、multipart 和可执行文件计划属于私有实现。CommonJS 使用 require() 加载相同入口。

个人 SAG

import { SagClient } from "@zleap-ai/sag-sdk/personal";

const client = new SagClient({
  origin: "https://sag.example",
  token: async () => obtainToken(), // 由应用提供
});
const sources = await client.listSources();

支持就绪、认证、信源与文档、状态汇总、检索、读取、outline、grep 和实体上下文。个人 URL 保留可规范化路径的兼容行为；企业连接要求纯 HTTP/HTTPS Origin。

企业连接与账号存储

import { createEnterpriseClient } from "@zleap-ai/sag-sdk/enterprise";

const client = createEnterpriseClient({
  connection: async () => ({
    origin: "https://sag.example",
    authorization: { kind: "token", token: async () => obtainOpenLinkToken() },
  }),
  timeoutMs: 15_000,
  askTimeoutMs: 60_000,
});
const bases = await client.listKnowledgeBases();
const { knowledgeBase, documents } = await client.listDocuments({
  knowledgeBase: "Engineering",
});
const answer = await client.ask({ question: "最近有什么变化？" });

知识库选择器接受准确 ID、别名或唯一名称。ask() 省略选择器时执行全局问答。最近文档、预览链接、重命名、回收删除和导入状态也使用显式选择器。一次在线操作固定一个 Origin，选库和轮询不会随连接提供器后续变化而漂移。可用 fetchImplementation 注入传输。

账号授权使用 { kind: "account", store }。实现 AccountSessionStore.read(origin)、save(origin, account)、remove(origin) 和 exclusive(origin, operation)。锁必须覆盖同一存储的所有使用者，需要时跨进程互斥。save 应原子合并账号并保留宿主配置的其他字段。账号包含 accessToken、refreshToken、accessExpiresAt、refreshExpiresAt 和 user: { id, name }。

SDK 在请求前通过 exclusive 刷新过期的账号访问凭据并保存轮换结果，不重放被远端拒绝的业务请求。开放链接 Token 不走账号刷新或浏览器回退。账号宿主可调用 beginLogin()，自行显示或打开返回的 verificationUrl，再调用 waitForLogin(attempt)。logout() 撤销并移除账号；浏览器、界面和存储策略由宿主负责。

开放链接授予 manage_files 时，可用 uploadPublishedFile({ path, driveSpaceId, folderId?, mediaType?, signal? }) 上传一个本地网盘文件。SDK 读取文件、校验 1 字节至 100 MiB 的大小、核对服务端分片方案，并在一次选定的 Origin 上创建会话、逐片发送、提交完成。返回值是服务端完成调用的结果；若传输中断，调用方须根据返回的错误及服务端会话状态判断结果，不应自行重放写入请求。

上传、预览与确认

const preview = await client.upload({ paths: ["./guides"], dryRun: true });
// 宿主显示 preview.plan 并取得确认。
const controller = new AbortController();
const result = await client.upload({
  paths: ["./guides"],
  knowledgeBase: "Engineering",
  confirmed: true,
  root: true,
  waitMs: 30_000,
  signal: controller.signal,
  onProgress: (event) => reportProgress(event),
  onError: ({ scope, itemId, error }) => reportError(scope, itemId, error),
  onCallbackError: ({ callback, failure }) => reportObserverFailure(callback, failure),
});

示例中的凭据、界面和报告函数由应用提供。无连接的 createEnterpriseClient() 可以离线预览；dry run 和未确认的多文件、目录上传不解析连接。多文件以及任何目录输入需要 confirmed: true，单个普通文件不需要。每次调用都传路径；预览不是可执行输入，后续调用会重新扫描当前文件。

目录只扫描第一层，最多 100 项。SDK 校验格式白名单、规范路径去重、Unicode 文件名冲突和文件快照。单文件取 25 MiB 与服务端限额的较小值。目标选择 folderId 或显式 root；省略时保留根目录语义。上传到文件夹前校验面包屑。idempotencyKey 表示重试身份；只有批准服务端重复冲突后才使用 overwriteDocumentId。

plan.planned 暴露只读的 id、displayPath、sizeBytes、modifiedAtMs 和 sha256（sha256: 加十六进制摘要）；plan.ignored 包含显示路径和原因。这些字段用于观察，不授予复用快照的能力；内部绝对路径、inode、ctime 不对外提供。

上传串行提交，立即保存已接受回执，再共用一个 waitMs 预算轮询。waitMs: 0 只提交不轮询。结果状态有 planned、completed、completed_with_errors、detached；每项状态为 completed、failed、detached 或 not_started。检查 operationError、interrupted 和全部 items。中断或处理超时不会取消服务端任务。传输失败且没有回执时，是否已被接受是未知的；SDK 不猜测，也不重试写请求。已接受项的 importId、documentId、jobId 会保留。

文件夹、通知与错误

client.folders 提供 list、path、create、rename、previewDelete、delete。全部接收 knowledgeBase，定位文件夹的操作还接收 folderId。重命名接收 name、etag；删除必须使用已审阅预览的 etag、impactToken（来自 impact_token），用户确认由宿主负责。写操作接受可选 idempotencyKey。列表接受 parentId、cursor、limit；版本或影响范围变化后需要重新预览。

在线方法接受操作级 signal、onProgress、onError、onCallbackError。普通进度为 request_started / request_completed，上传还包含计划、接受回执和处理事件。通知按事实顺序调用但不等待；同步抛错和 Promise 拒绝不改变结果。诊断只包含回调名及 threw / rejected，诊断回调自身失败也会隔离。

捕获 SagSdkError 可读取 code、可选 HTTP status、平台 problemCode、脱敏 details 和 partialResult。上传使用 SagSdkError<UploadResult> 标注部分结果。提交前错误会拒绝并将计划项标记为 not_started；文件局部失败和提交后的系统错误保留结果账本。SDK 错误没有 CLI 退出码。不要记录注入的凭据或未经处理的回调异常。

SDK 首发为 0.1.0，与 CLI 独立计版。后续公开变化添加 SDK Changeset，发布过程见仓库发布指南。