TypeScript SDK

@halfway/atlas-sdk 是知识库 Runtime 的类型化客户端。

安装

npm install @halfway/atlas-sdk

初始化

import { createAtlasClient } from "@halfway/atlas-sdk";

const atlas = createAtlasClient({
  baseUrl: "https://atlas.halfwaylab.cn", // 或 http://localhost:4150
  apiKey: "atlas_live_...",               // 开启鉴权时必填
  timeoutMs: 15000,                        // 可选，默认 15s
});

方法

方法	说明
ready()	就绪检查 + 知识包版本（公开）
openapi()	获取 OpenAPI 契约（公开）
stats()	知识包统计（版本/计数/治理）
lookup(idOrSlug)	按 id 或 slug 精确查找实体/关系/证据
search({ q, scope?, limit? })	全文检索（scope 限实体类型）
graph({ rootId, maxDepth?, maxNodes? })	实体邻域图谱（BFS）

lookup

const r = await atlas.lookup("per_tadao-ando");
// { kind: "entity", id: "per_tadao-ando", data: { displayName: "安藤忠雄", ... } }

search

const r = await atlas.search({ q: "包豪斯", scope: ["movement"], limit: 10 });
for (const hit of r.hits) {
  console.log(hit.score, hit.kind, hit.displayName);
}

graph

const g = await atlas.graph({ rootId: "per_tadao-ando", maxDepth: 2, maxNodes: 40 });
console.log(g.nodes.length, g.edges.length, g.truncated);

错误处理

所有错误统一为 AtlasApiError，含 status 与 code：

import { AtlasApiError } from "@halfway/atlas-sdk";

try {
  await atlas.stats();
} catch (err) {
  if (err instanceof AtlasApiError) {
    console.error(err.status, err.code, err.message); // 401 UNAUTHORIZED / 429 QUOTA_EXCEEDED ...
  }
}

常用错误码：UNAUTHORIZED（401）、NOT_FOUND（404）、INVALID_REQUEST（400）、 QUOTA_EXCEEDED（429）、RELOAD_FAILED（500）、NETWORK_ERROR / TIMEOUT。